This directory contains project tooling scripts used to enforce formatting standards, validate invariants, generate documentation assets, and safely apply codemods across the codebase.
These scripts are not part of the application runtime. They exist to keep the repository consistent, maintainable, and CI-safe.
The scripts in this directory follow a few strict principles:
- Deterministic output — repeated runs should produce the same result
- Fail fast in CI — errors should surface early and loudly
- Separation of concerns — formatting, linting, rendering, and mutation are isolated
- Safety first — codemods are conservative and explicitly documented
Mermaid diagrams move through a clearly defined pipeline. Each stage has a single responsibility.
normalize → format → lint → render → build assetsScript: normalize-diagrams.js
- Accepts multiple diagram collection formats
- Produces a stable array shape
- Injects identifiers where needed
- Performs no validation and no mutation
This is the contract boundary for all downstream diagram tooling.
Scripts:
format-mermaid.js(pure formatter)format-diagrams.js(repository-level enforcement)
Responsibilities:
- Normalize whitespace and indentation
- Enforce Mermaid-safe structure
- Preserve semantic meaning
Important distinction:
format-mermaid.jsdefines how Mermaid should look.
format-diagrams.jsdefines where and when formatting is applied.
Script: lint-diagrams.js
- Enforces structural Mermaid invariants
- Rejects invalid diagram declarations
- Prevents tabs and malformed init blocks
- Emits warnings for readability issues
Linting is a hard gate. Any failure blocks rendering and docs generation.
Script: render-diagram-pngs.js
- Uses Playwright (Chromium) to render diagrams in a real browser
- Captures transparent PNG screenshots
- Ensures visual parity with production Mermaid rendering
This step introduces filesystem side effects and should fail CI if rendering breaks.
Script: build-diagram-assets.js
- Collects rendered diagram images
- Integrates them into the documentation output
- Ensures all referenced diagrams exist
Codemods mutate source code and should be run manually and deliberately.
Before running any codemod:
- Ensure the git working tree is clean
- Run one codemod at a time
- Review diffs carefully before committing
All codemods in this directory are designed to be:
- Conservative
- Idempotent where possible
- Focused on a single invariant
- Adds missing React
keyprops in.map()JSX - Prefers semantic identifiers (
item.id) - Falls back to index-based keys only when necessary
Does not:
- Override existing keys
- Modify non-map JSX
- Rewrites unsupported JSDoc
import()type syntax - Required for compatibility with
jsdoc-to-markdown - Operates on comments only (no runtime changes)
- Renames unused
.map()index parameters to_index - Eliminates ESLint warnings without changing behavior
| Script Type | Intended Usage |
|---|---|
| Normalize / Format / Lint | CI + local |
| Render PNGs | CI + local |
| Codemods | Manual only |
Codemods should never run automatically in CI.
Some scripts support optional debug output via environment variables.
Example:
DEBUG_DIAGRAMS=1 npm run diagrams:lintThis keeps CI output clean while preserving local debugging capabilities.
- Diagram scripts assume Mermaid version compatibility
- Rendering relies on Playwright/Chromium being installed
- Codemods should always be reviewed via git diff
If a script fails unexpectedly, do not suppress the error — investigate the root cause.
These scripts encode project standards.
If you change a script:
- Update documentation
- Consider downstream impact
- Treat the change as architectural, not incidental
This discipline keeps the codebase predictable over time.