Add Mermaid syntax validation for generated diagrams (linter / pre-commit hook)

[tractorjuice]

Problem

ArcKit commands that generate Mermaid diagrams (notably /arckit:data-model, /arckit:diagram, /arckit:dfd, and any artefact embedding a Mermaid block) can emit syntactically invalid Mermaid that the renderer silently fails on — the artefact is written, the docs site indexes it, and the broken diagram is only noticed when a human opens the file.

There is no automated validation in the generation pipeline, the secret-file-scanner hook, or the docs/pages build that catches Mermaid parser errors.

Concrete example (encountered today)

/arckit:data-model for an SaaS project produced an erDiagram containing:

CELL_ASSIGNMENT {
    uuid assignment_id PK
    uuid tenant_id FK UK "One assignment per tenant"
    ...
}

Loading

Mermaid's ER grammar accepts only one key constraint (PK / FK / UK) per attribute. The double FK UK causes the block to fail to render. The artefact still got committed and pushed; the error was only noticed when the user previewed the markdown.

Other classes of mistake the model is prone to in ER diagrams:

• Two key tokens on one attribute (as above)
• Reserved-ish words used as attribute names (e.g. command, key, type)
• Unbalanced quotes inside attribute comments
• Cardinality typos (e.g. ||--o| vs ||--|o)
• int/integer/number inconsistency (Mermaid is permissive but downstream consumers may not be)

Suggested approaches (any one of these would help)

1. Post-generation validation in commands: each command that emits Mermaid extracts the fenced block and runs npx -y @mermaid-js/mermaid-cli -i <tmpfile> -o /dev/null --quiet. Non-zero exit → command refuses to write or surfaces the parser error and asks for a fix-up pass.

2. PreToolUse:Write hook (mirroring the existing secret-file-scanner pattern): a mermaid-block-scanner.mjs hook extracts every ```mermaid block from the file being written and validates each via mmdc. Same blocking-via-stdout-JSON contract as the secret scanner.

3. CI / pre-commit hook: a script that walks projects/**/*.md, extracts Mermaid blocks, and validates them. Less immediate feedback but catches every artefact regardless of how it was authored.

4. Template-level guard rails: add explicit cautionary notes in templates/data-model-template.md and the mermaid-syntax skill (e.g. only one of PK/FK/UK per attribute) so the generator is steered away from common mistakes.

(1) or (2) are highest-value; (4) is cheap and complementary.

Repro

# In any ArcKit project with a REQ document
/arckit:data-model
# Inspect generated ARC-*-DATA-*.md for Mermaid `erDiagram` blocks with `FK UK` or similar double-key attributes

Environment

• ArcKit plugin v4.14.0
• Claude Code (Opus 4.7, 1M context)
• Encountered in tractorjuice/arckit-test-project-v48-arckit-as-a-service on commit a188d67 (the fix commit)

Related

• Issue issue in mermaid flow #179 (closed) — issue in mermaid flow — different symptom but adjacent area
• The mermaid-syntax skill exists but is currently only consulted at generation time; there's no validation gate after generation

[tractorjuice]

Sibling issue for the OnlineWardleyMaps (OWM) DSL: #436. Same hook architecture, different parser — they should coexist, not be merged.

[tractorjuice]

A few notes before anyone starts implementation:

Recommended approach: PreToolUse:Write hook (option 2 in the issue).

Symmetric with the existing secret-file-scanner.mjs contract, catches every artefact regardless of which command produced it (including the long tail like /arckit:hld-review, /arckit:dld-review, and anything embedding Mermaid in prose), and surfaces failures before the file lands on disk so Claude can self-correct in the same turn.

Per-command validation (option 1) duplicates wiring across ~15 commands. CI walker (option 3) catches things only after push. Template guard rails (option 4) help but don't enforce; worth doing as a complement, not a replacement.

Use mermaid.parse(), not mmdc.

@mermaid-js/mermaid-cli spins up Puppeteer/Chromium to render. PreToolUse hooks have a 5s default timeout and run on every Write under projects/**. The Mermaid JS package exposes a parser-only entry point that validates syntax without touching a headless browser. That keeps the hook in the millisecond budget that secret-file-scanner already lives in.

Sibling issue #436 should share the implementation.

Consider a single diagram-block-scanner.mjs that dispatches by fence language (mermaid vs wardley/owm) rather than two near-identical hooks. One registration entry, one telemetry path, one place to add new diagram languages later (PlantUML is the obvious next).

Existing prior art for #436.

hooks/validate-wardley-math.mjs (271 lines, currently unwired in hooks.json) already does coordinate-range and OWM-vs-inventory consistency for WARD files. The OWM half of the work in #436 is partially built; the parser-error class (dangling refs, annotation index reuse, style typos) would extend it.