Connect

Check with the CLI

vinc graph-md check tells you whether a GRAPH.md has the shape assistants expect, and exits with a code a script can act on.

Run it

vinc graph-md check --file GRAPH.md             # a file, compared with the local graph
vinc graph-md check --file GRAPH.md --no-store  # shape only, no graph needed
vinc graph-md check --doc --owner <owner>       # the copy stored in the graph

Use --no-store in CI or anywhere without a Vinc graph. It skips the rules that compare the file with the graph (marked below) and runs the rest.

What it checks

Nine rules about the file's shape: the header line, the sections and their order, the generated region, relation names, tool names, length and em-dashes. Each finding is BLOCK (the file is broken; fix it before assistants read it) or FIX (it works, but should be cleaned up). Every rule, with an example and how to fix it, is on Check rules.

Options

Option	What it does
`--file PATH`	Check this file.
`--doc`	Check the copy stored in the local graph instead of a file. Needs `--owner`.
`--owner OWNER`	Whose stored copy and whose graph to compare with.
`--no-store`	Shape only. Skip the rules that read the graph.
`--data DIR`	Use this local data folder instead of the app's.

Exit codes

Code	Meaning
`0`	No findings.
`1`	FIX findings only.
`2`	At least one BLOCK.

To keep a broken GRAPH.md out of a repository, fail the CI step on exit code 2 and treat 1 as a warning.

vinc graph-md check --file GRAPH.md --no-store --json
code=$?
[ $code -eq 2 ] && exit 1 || exit 0

Output

With --json the result is one object. Here a file used an em-dash, named a tool that does not exist, and listed an unknown relation:

{
  "kind": "graphmd.check",
  "ok": false,
  "exit_code": 2,
  "blocks": 1,
  "fixes": 2,
  "findings": [
    {"rule": "forbidden-glyph", "level": "FIX",
     "message": "em-dash is not allowed in on-screen text (D38)", "line": 9},
    {"rule": "stale-tool", "level": "FIX",
     "message": "unknown tool name: vinc_find", "line": 9},
    {"rule": "unknown-edge", "level": "BLOCK",
     "message": "relation not in the wire contract or ratified vocabulary: replaces"}
  ]
}

ok is true only when there are no findings at all. line is given when the rule can point at one line.

What it does not check

The check looks at shape only. Whether your examples are good, or your rules make sense for this graph, is not something it can judge, so it does not try. Read the file the way an assistant would: if a rule is unclear to you, it will be unclear to the assistant too.