Linting vizzy diagrams

The renderer never fails on bad input. A partial or slightly wrong diagram still draws what it can. That is good 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 creates a phantom node. vizzy lint reports these problems.

It uses the same command line tool as rendering. Install it once, 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 does not exist, relative to the document’s folder. Covers `.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 puts the rest of the file into the block, so everything below it disappears. Add the closing fence.
`unsupported-diagram`	warning	A ```mermaid fence whose diagram type Vizzy cannot render. 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 the tag renders literally. Use a `desc:` directive for a subtitle.
`phantom-edge`	warning	An unrecognized edge operator like `<==>`, which creates 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 probably forgotten, so Vizzy renders it as a code block instead of a diagram.
`detached-annotation`	warning	A `vizzy` annotation block (`note`/`pos`/`style`/`payload`/`hint`) with no diagram before it to attach to. Vizzy drops the whole block. Move it directly after the diagram it annotates.
`unknown-directive`	warning	A line inside a `vizzy` annotation block whose first word is not a recognized directive, such as `position` instead of `pos`. The parser ignores it.
`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, such as a renamed node or an edge written backwards. The directive does nothing.
`skipped-block`	suggestion	A line a diagram parses but never draws (a sequence `box`/`autonumber`/`activate`, or a flowchart `click`). The diagram is still valid. That piece will not appear.
`prefer-desc`	suggestion	A `<br>` in a label. It works, but a `desc:` directive is usually cleaner for a subtitle.
`prefer-theme-color`	suggestion	A raw `#hex` color in a style. Use 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 is easy to grep 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 do not fail the run. You can gate on it:

vizzy lint vizzy/ && echo "diagrams OK"

The agent loop

After a coding agent writes or updates a file, vizzy lint confirms the work before it is committed. Most usefully, it checks that every hint file path still resolves after a rename or move:

Write or update vizzy/<flow>.vizzy.md.
Run vizzy lint vizzy/<flow>.vizzy.md and fix any errors it reports.
Run vizzy render vizzy/<flow>.vizzy.md and put the PNG in your docs.