fix: auto-quote leading-@ flowchart labels + mermaid.parse regression suite

[drakulavich]

What

A posted Iago flowchart failed to render on GitHub. Root cause: a node label starting with @ right after [ — N[@utils/utils -> @i18n -> antd locale: not loaded]. Mermaid ≥ 10.5 lexes [@ as its edge-ID/shape syntax (got 'LINK_ID' parse error). Mid-label @ is fine; only a leading @ breaks, and quoting the label fixes it.

Changes

• iago/scripts/sanitize.ts: new rule — inside flowchart/graph mermaid blocks, unquoted [@…] labels are rewritten to ["@…"], mirroring the existing ;→, sequence-label repair. Still pure string transform, no deps.
• cli/tests/helpers/mermaid.ts: jsdom-backed parseMermaid() (real mermaid.parse(), same parser GitHub runs) + extractMermaidBlocks(). mermaid/jsdom added as cli devDependencies only.
• cli/tests/fixtures/mermaid/{valid,invalid}/: fixture corpus for field rendering incidents — the exact failing diagram is stored verbatim; invalid/ must fail parse and parse again after sanitize(), valid/ must parse as-is.
• cli/tests/mermaid-validation.test.ts: runs the corpus plus a sweep of every mermaid block in iago/examples/*.md, iago/references/mermaid-templates.md, and README.md.
• Docs: authoring rule added to iago/SKILL.md and iago/references/mermaid-templates.md (with bad/good pair); CLAUDE.md critical rule extended with the incident.

Testing

• cd cli && bun test — 73 pass, 0 fail (incident fixture fails parse unquoted, parses after sanitize())
• cd cli && bun run typecheck — clean

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR fixes a Mermaid parse failure on GitHub when a flowchart node label begins with @ (e.g. N[@utils/utils -> ...]), which Mermaid ≥ 10.5 lexes as edge-ID/shape syntax. It also adds a jsdom-backed parse-validation harness so every fixture and repo example diagram is verified against the real Mermaid parser in CI.

• iago/scripts/sanitize.ts: adds LEADING_AT regex to auto-quote [@...] labels in flowchart/graph blocks; header-detection now skips both blank lines and %% directives/comments before checking for the flowchart|graph keyword.
• cli/tests/helpers/mermaid.ts + mermaid-validation.test.ts: new jsdom-backed parseMermaid() helper and corpus-driven test that validates all fixture files and repo example docs against mermaid.parse().
• cli/tests/fixtures/mermaid/{valid,invalid}/: stores the exact failing diagram verbatim as a regression fixture.

Confidence Score: 5/5

The change is a targeted string rewrite confined to mermaid fence bodies, with no production runtime dependencies added and no changes to the published CLI bundle.

The LEADING_AT regex is correct, the header-detection now properly skips %% comment/directive lines before classifying the block, and the test suite exercises the exact production failure verbatim. Both issues raised in the previous review round are addressed.

No files require special attention.

Important Files Changed

Filename	Overview
iago/scripts/sanitize.ts	Core fix: LEADING_AT regex correctly rewrites [@...] to ["@..."] only in flowchart/graph blocks; header detection now skips %% comments/directives before matching the diagram type.
cli/tests/helpers/mermaid.ts	jsdom-backed mermaid parse helper with a documented known limitation about globalThis mutation; pattern is intentional and the limitation is clearly communicated to future authors.
cli/tests/mermaid-validation.test.ts	Corpus-driven test suite: invalid fixtures must fail parse then pass after sanitize(), valid fixtures must parse as-is, and all repo doc diagrams are validated end-to-end.
cli/tests/sanitize.test.ts	Good unit coverage for the new rule: quotes leading-@ labels, leaves mid-label @ and already-quoted labels untouched, and explicitly tests the %%-comment-prefix case.
cli/tests/fixtures/mermaid/invalid/leading-at-flowchart.mmd	Verbatim copy of the exact failing production diagram stored as a regression fixture; the offending N[@utils/utils -> @i18n -> antd locale: not loaded] line is present.
cli/package.json	Adds jsdom and mermaid (+ their @types) as devDependencies only; no production bundle impact.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["sanitize(src)"] --> B["Match mermaid fences"]
    B --> C["rewriteBlock(body)"]
    C --> D["Split into lines"]
    D --> E["Find first non-blank non-%% line"]
    E --> F{"isFlow?"}
    F -->|yes| G["LEADING_AT replace: at-bracket to quoted-at-bracket"]
    F -->|no| H["MSG.exec: semicolon to comma in sequence labels"]
    G --> I["Join lines + return"]
    H --> I

Loading

_{Reviews (2): Last reviewed commit: "fix: detect flowchart header past %% com..." | Re-trigger Greptile}