Linting vizzy diagrams

The renderer never fails on bad input — by design, a partial or slightly-wrong diagram still draws what it can. That’s great for live editing, but it means mistakes are easy to miss: a hint pointing at a renamed file, a <sub> tag that shows up as literal text, a stray edge that leaks a phantom node. vizzy lint surfaces exactly those.

It uses the same command line tool as rendering — install it once via Vizzy ▸ Install Command Line Tool…, then:

vizzy lint vizzy/architecture.vizzy.md

Pass several files or a directory (a directory lints every *.vizzy.md it contains, recursively):

vizzy lint vizzy/                          # the whole folder
vizzy lint vizzy/auth.vizzy.md vizzy/checkout.vizzy.md

What it checks

Rule	Severity	What it catches
broken-file-ref	error	A hint, link, or image points at a local file that doesn’t exist, relative to the document’s folder — .vizzy.md, .md, source files, and assets, by relative or absolute path. Inline "…" hint previews and http(s):// URLs are skipped.
unterminated-fence	error	A </code> fence with no closing <code>. Vizzy swallows the rest of the file into the block, so everything below it silently disappears. Add the closing fence.
unsupported-diagram	warning	A ```mermaid fence whose diagram type Vizzy can’t render (gitGraph, quadrantChart, …) — it draws nothing.
unsupported-html	warning	An HTML tag other than <br> in a label (<sub>, <span>, <b>, …). Vizzy draws labels as plain text, so it would render literally — use a desc: directive for a subtitle.
phantom-edge	warning	An unrecognized edge operator like <==>, which silently leaks a stray node. Use <--> for a bidirectional edge or ==> for a thick one.
untagged-diagram	warning	A ``` fence with no language tag whose body parses as a diagram — the mermaid/vizzy tag was almost certainly forgotten, so Vizzy renders it as a literal code block instead of drawing it.
detached-annotation	warning	A vizzy annotation block (note/pos/style/payload/hint) with no diagram before it to attach to. Vizzy silently drops the whole block — move it directly after the diagram it annotates.
unknown-directive	warning	A line inside a vizzy annotation block whose leading word isn’t a recognized directive (a typo like position for pos). The parser ignores it silently.
broken-node-ref	warning	A style/desc/pos/hint/payload/phase directive whose target matches no node, edge, group, or label in the diagram it annotates (a renamed node, or an edge written backwards). The parser resolves it to nothing, so the directive is a silent no-op.
skipped-block	suggestion	A line a diagram parses but never draws (a sequence box/autonumber/activate, or a flowchart click). The shape stays valid; that piece just won’t appear.
prefer-desc	suggestion	A <br> in a label. It works, but a desc: directive is usually the cleaner way to add a subtitle.
prefer-theme-color	suggestion	A raw #hex color in a style. Prefer a palette name or vizzy.config token so the diagram stays on-theme.

Output

Each finding prints in compiler style — path:line:col: severity: message [rule] — so it’s greppable and easy for a coding agent or CI step to parse:

vizzy/architecture.vizzy.md:42:16: error: referenced file not found: ../runbooks/auth.md [broken-file-ref]
vizzy/architecture.vizzy.md:51:9: warning: <sub> renders literally in labels — use <br> for a line break, or a `desc:` directive for a subtitle [unsupported-html]
vizzy/architecture.vizzy.md:60:21: info: raw hex #E0F2FE — prefer a standard color name (blue, indigo, green, …) or a vizzy.config token so the diagram stays on-theme [prefer-theme-color]

vizzy lint exits non-zero when there are any errors (warnings and suggestions don’t fail the run), so you can gate on it:

vizzy lint vizzy/ && echo "diagrams OK"

The agent loop

Linting closes the authoring loop for a coding agent maintaining your diagrams. After it writes or updates a file, a quick vizzy lint confirms the work before it’s committed — most usefully, that every hint file path still resolves after a rename or move:

1. Write or update vizzy/<flow>.vizzy.md.
2. vizzy lint vizzy/<flow>.vizzy.md → fix any errors it reports.
3. vizzy render vizzy/<flow>.vizzy.md → drop the PNG into your docs.

Tip

Run vizzy lint vizzy/ in CI to catch a diagram that references a file someone later deleted or renamed — the kind of rot that otherwise goes unnoticed until a reader clicks a dead hint.