Skip to content

scripts.md

Latest commit

 

History

History
398 lines (328 loc) · 14.6 KB

scripts.md

File metadata and controls

398 lines (328 loc) · 14.6 KB

Modules

scripts/diagrams/build-diagram-assets

scripts/diagrams/build-diagram-assets module.

scripts/diagrams/format-mermaid

Deterministic formatter for Mermaid diagram source strings.

This module operates on raw Mermaid source text and enforces:

  • Structural indentation
  • Whitespace normalization
  • Mermaid grammar safety (Mermaid v11 compatible)

Characteristics:

  • Pure function (no side effects)
  • Idempotent (repeated runs produce the same output)
  • Project-agnostic (safe to reuse elsewhere)

IMPORTANT:

  • This module does NOT read or write files
  • It does NOT validate diagram correctness
  • It only normalizes formatting

Constants

DIAGRAM_BLOCK_RE

Regex finds: diagram: ... /

CORE_TYPES

VALID_MERMAID_TYPES --------------------------------------------------------------------------- Hybrid strict mode: - CORE_TYPES are always allowed - EXTENDED_TYPES are allowed but validated more strictly /

OUTPUT_DIR

Output directory for rendered PNG assets. This directory is expected to be committed or published alongside generated documentation. /

VIEWPORT

Fixed viewport ensures: - Consistent diagram scaling - Predictable text wrapping - Stable screenshot output across environments /

Functions

addReactKeys(file, api) ⇒ string

Main codemod function that traverses the AST to find JSX elements returned from array .map() calls and adds missing key props. The function uses jscodeshift to manipulate the AST and applies the following logic:

  1. Identify .map() calls and their callback functions.
  2. For each JSX element returned from the callback, check if it already has a key prop.
  3. If not, attempt to add a key prop using the following priority: a. If the callback has an item parameter (e.g., item), use item.id as the key. b. If the callback has an index parameter (e.g., index), use the index as a fallback key.
  4. Skip any JSX elements that already have a key prop defined.
fixJsdocImportTypes(file, api) ⇒ string

Codemod function that rewrites unsupported JSDoc import() type references into plain type identifiers.

fixUnusedMapIndex(file, api) ⇒ string

Main codemod function that traverses the AST to find .map() calls and renames unused index parameters to _index. The function uses jscodeshift to manipulate the AST and applies the following logic:

  1. Identify .map() calls and their callback functions.
  2. Check if the callback has at least two parameters (item and index).
  3. Verify that the second parameter (index) is an Identifier.
  4. Traverse the callback body to check if the index parameter is referenced.
  5. If the index parameter is not used, rename it to _index.
stripInit()

Removes the Mermaid init block for structural validation only. /

extractSources()

Extracts all Mermaid source strings from a diagram block. /

lintDiagram()

Performs structural validation on a single Mermaid diagram block. /

run()

ENTRYPOINT BEHAVIOR /

normalizeMermaidSource(source) ⇒ string

Normalizes Mermaid diagram source for consistent linting. This function ensures:

  • Proper newline after init block
  • Blank line after diagram declaration
  • Consistent line endings
  • Trims leading whitespace This is a best-effort normalization to improve linting consistency. It does NOT attempt to fully parse or validate Mermaid syntax. It simply applies common formatting fixes to reduce false positives in linters.
normalizeDiagrams(input) ⇒ array

Normalizes a diagram collection into a consistent array format. Supports both object maps and legacy arrays. Applies Mermaid source normalization. This function is designed to be flexible and forgiving, allowing for various input shapes while ensuring a predictable output structure for downstream processing.

normalizeMermaidSource(source) ⇒ string

Normalizes a Mermaid diagram source string by removing init blocks, normalizing line endings, and trimming leading whitespace.

render()

Renders all Mermaid diagram blocks to PNG images.

Execution flow:

  1. Ensure output directory exists
  2. Launch headless Chromium
  3. Load Mermaid in an isolated HTML shell
  4. Inject diagram source one at a time
  5. Screenshot rendered output
  6. Close browser

This function is intentionally sequential to:

  • Avoid race conditions in Mermaid rendering
  • Prevent memory pressure from concurrent pages

scripts/diagrams/build-diagram-assets

scripts/diagrams/build-diagram-assets module.

scripts/diagrams/build-diagram-assets~run()

Main execution function for building diagram assets.

Kind: inner method of scripts/diagrams/build-diagram-assets

scripts/diagrams/format-mermaid

Deterministic formatter for Mermaid diagram source strings.

This module operates on raw Mermaid source text and enforces:

  • Structural indentation
  • Whitespace normalization
  • Mermaid grammar safety (Mermaid v11 compatible)

Characteristics:

  • Pure function (no side effects)
  • Idempotent (repeated runs produce the same output)
  • Project-agnostic (safe to reuse elsewhere)

IMPORTANT:

  • This module does NOT read or write files
  • It does NOT validate diagram correctness
  • It only normalizes formatting

module.exports(source) ⇒ string ⏏

Formats a Mermaid diagram source string into a deterministic, readable, and Mermaid-safe structure.

This function is intentionally:

  • Pure (no side effects)
  • Idempotent (safe to run multiple times)
  • Structural-only (never changes semantic meaning)

It does NOT validate diagrams — linting is handled separately.

Kind: Exported function
Returns: string - Canonically formatted Mermaid source.

Param Type Description
source string Raw Mermaid source text.

DIAGRAM_BLOCK_RE

Regex finds: diagram: ... /

Kind: global constant

CORE_TYPES

VALID_MERMAID_TYPES --------------------------------------------------------------------------- Hybrid strict mode: - CORE_TYPES are always allowed - EXTENDED_TYPES are allowed but validated more strictly /

Kind: global constant

OUTPUT_DIR

Output directory for rendered PNG assets. This directory is expected to be committed or published alongside generated documentation. /

Kind: global constant

VIEWPORT

Fixed viewport ensures: - Consistent diagram scaling - Predictable text wrapping - Stable screenshot output across environments /

Kind: global constant

addReactKeys(file, api) ⇒ string

Main codemod function that traverses the AST to find JSX elements returned from array .map() calls and adds missing key props. The function uses jscodeshift to manipulate the AST and applies the following logic:

  1. Identify .map() calls and their callback functions.
  2. For each JSX element returned from the callback, check if it already has a key prop.
  3. If not, attempt to add a key prop using the following priority: a. If the callback has an item parameter (e.g., item), use item.id as the key. b. If the callback has an index parameter (e.g., index), use the index as a fallback key.
  4. Skip any JSX elements that already have a key prop defined.

Kind: global function
Returns: string - The transformed source code with added key props.

Param Type Description
file * The file object provided by jscodeshift, containing the source code to be transformed.
api * The jscodeshift API object, used for AST manipulation.

fixJsdocImportTypes(file, api) ⇒ string

Codemod function that rewrites unsupported JSDoc import() type references into plain type identifiers.

Kind: global function
Returns: string - The transformed source code with fixed JSDoc import types.

Param Type Description
file * The file object provided by jscodeshift, containing the source code to be transformed.
api * The jscodeshift API object, used for AST manipulation.

fixUnusedMapIndex(file, api) ⇒ string

Main codemod function that traverses the AST to find .map() calls and renames unused index parameters to _index. The function uses jscodeshift to manipulate the AST and applies the following logic:

  1. Identify .map() calls and their callback functions.
  2. Check if the callback has at least two parameters (item and index).
  3. Verify that the second parameter (index) is an Identifier.
  4. Traverse the callback body to check if the index parameter is referenced.
  5. If the index parameter is not used, rename it to _index.

Kind: global function
Returns: string - Updated source code after codemod transformations.

Param Type
file *
api *

stripInit()

Removes the Mermaid init block for structural validation only. /

Kind: global function

extractSources()

Extracts all Mermaid source strings from a diagram block. /

Kind: global function

lintDiagram()

Performs structural validation on a single Mermaid diagram block. /

Kind: global function

lintDiagram~isCore

RULE: Diagram type validation (hybrid strict). /

Kind: inner constant of lintDiagram

run()

ENTRYPOINT BEHAVIOR /

Kind: global function

normalizeMermaidSource(source) ⇒ string

Normalizes Mermaid diagram source for consistent linting. This function ensures:

  • Proper newline after init block
  • Blank line after diagram declaration
  • Consistent line endings
  • Trims leading whitespace This is a best-effort normalization to improve linting consistency. It does NOT attempt to fully parse or validate Mermaid syntax. It simply applies common formatting fixes to reduce false positives in linters.

Kind: global function
Returns: string - The normalized Mermaid diagram source string.

Param Type Description
source string The raw Mermaid diagram source string.

Example

const source = `%%{init: {"theme": "dark"}}%%
graph TD
A --> B
`;
const normalized = normalizeMermaidSource(source);
console.log(normalized);
// Output:
// %%{init: {"theme": "dark"}}%%
// graph TD
// A --> B

normalizeDiagrams(input) ⇒ array

Normalizes a diagram collection into a consistent array format. Supports both object maps and legacy arrays. Applies Mermaid source normalization. This function is designed to be flexible and forgiving, allowing for various input shapes while ensuring a predictable output structure for downstream processing.

Kind: global function
Returns: array - An array of normalized diagram entries, each with a consistent structure.

Param Type Description
input object | array The raw diagram collection, either as an object map or an array.

Example

// Object map input
const diagramsMap = {
"diagram1": { diagram: "graph TD\nA --> B" },
"diagram2": { diagram: "graph LR\nC --> D" }
};
const normalizedFromMap = normalizeDiagrams(diagramsMap);
console.log(normalizedFromMap);
// Output:
// [
//   { key: "diagram1", diagram: "graph TD\nA --> B" },
//   { key: "diagram2", diagram: "graph LR\nC --> D" }
// ]

// Array input

normalizeMermaidSource(source) ⇒ string

Normalizes a Mermaid diagram source string by removing init blocks, normalizing line endings, and trimming leading whitespace.

Kind: global function
Returns: string - The normalized Mermaid diagram source string.

Param Type Description
source string The Mermaid diagram source string.

Example

const source = `%%{init: {"theme": "dark"}}%%
graph TD
A --> B
`;
const normalized = normalizeMermaidSource(source);
console.log(normalized);
// Output:
// graph TD
// A --> B

render()

Renders all Mermaid diagram blocks to PNG images.

Execution flow:

  1. Ensure output directory exists
  2. Launch headless Chromium
  3. Load Mermaid in an isolated HTML shell
  4. Inject diagram source one at a time
  5. Screenshot rendered output
  6. Close browser

This function is intentionally sequential to:

  • Avoid race conditions in Mermaid rendering
  • Prevent memory pressure from concurrent pages

Kind: global function
Throws:

  • Error If Playwright fails to launch or rendering fails.