flowfig 0.7.0 → 0.8.1

package/README.md

@@ -22,7 +22,7 @@ A diagram in a repo drifts from the code. Someone renames a function, and the di
 check fails, so no one sees the drift.
 
 flowfig links each part of a diagram to the code that it draws. `flowfig verify` fails when a linked file or symbol is
-gone. Run `verify` in CI, and a stale diagram fails the pull request.
+gone, and warns when the code does not make an edge. Run `verify` in CI, and a stale diagram fails the pull request.
 
 ## Fail CI when the diagram drifts
 
@@ -36,12 +36,14 @@ Rename `verifyPassword` to `checkPassword`. Then `verify` fails with exit code 1
 
 ```console
 $ npx flowfig verify login.svg
-error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not found
+error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not defined
 1 error, 0 warnings
+login.svg: 0 of 1 boxes defined
 ```
 
-`verify` checks that each linked file exists and that the symbol name still occurs in it. A link to a Markdown file can
-name a heading, so a process diagram can follow its SOP document.
+`verify` checks that each linked file exists and that it defines the symbol. It also checks each edge against the code
+(see [Verify in CI](#verify-in-ci)). A link to a Markdown file can name a heading, so a process diagram can follow its SOP
+document.
 
 The GitHub Action runs `verify` on every figure in a pull request. For each SVG that the PR changes, it comments the old
 image, the new image and the spec changes. It also names each figure whose linked code the PR changes.
@@ -63,7 +65,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.7.0
+      - uses: iamalvisng/flowfig@v0.8.1
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -115,7 +117,7 @@ the run.
 
 1. **The agent writes JSON, not pictures.** The agent reads the code and writes a spec of the parts, the calls and their
    order. flowfig does the layout.
-2. **flowfig checks the spec.** `flowfig check` has 22 rules. It finds ids that point nowhere, text wider than its box,
+2. **flowfig checks the spec.** `flowfig check` has 23 rules. It finds ids that point nowhere, text wider than its box,
    edges through boxes, overlapping labels and low contrast. A render runs the same check and writes nothing on an error.
    The agent reads the faults and fixes the spec.
 3. **The output is one animated SVG with no script.** The SVG plays in a GitHub README, PR or issue. It follows the light
@@ -165,7 +167,7 @@ The options are in [Open and share a figure](#open-and-share-a-figure).
 | ------------------------------ | --------------------------------- | ------------------------------------ | ---------------- |
 | Made by an agent from the code | Yes, with the `init` instructions | Yes, as Mermaid text                 | No               |
 | Linked to the code             | Yes, `verify` fails in CI         | No                                   | No               |
-| Checked for faults             | Yes, 22 rules in `flowfig check`  | Syntax errors only                   | No               |
+| Checked for faults             | Yes, 23 rules in `flowfig check`  | Syntax errors only                   | No               |
 | Animated                       | Yes, one packet per message       | No                                   | No               |
 | Shows payloads and order       | Yes, on the map and the rail      | Order and text in a sequence diagram | No               |
 | Plays in a GitHub README       | Yes, as an SVG                    | Yes, GitHub renders it               | Yes, as an image |
@@ -213,7 +215,7 @@ Save this spec as `first.json`. The spec has 3 boxes, 2 edges and 1 step.
   },
   "edges": [
     { "from": "browser", "to": "api", "label": "GET /user" },
-    { "from": "api", "to": "db", "label": "SELECT" }
+    { "from": "api", "to": "db", "label": "read the user" }
   ],
   "steps": [
     {
@@ -233,10 +235,18 @@ Render the spec:
 
 ```console
 $ npx flowfig first.json
+0 errors, 0 warnings
 figure: 3 boxes, 0 groups, 2 edges, 1 step, 4 messages
-first.svg — 8.8 kB
+browser -> api: GET /user
+api -> db: read the user
+step "Load a user": 4 hops
+first.svg — 9.7 kB
 ```
 
+The render prints the check result, the counts, one line per edge and one line per step. Read these lines to check the figure
+without a second command. If a box or an edge has a `source` or a `via`, the render also prints the `verify` counts.
+`--no-verify` skips them.
+
 The command writes `first.svg`:
 
 ![A browser loads a user through an API from a database](docs/first.svg)
@@ -252,7 +262,7 @@ Each SVG from the CLI carries its own spec. These commands made the rail-only fi
 npx flowfig --spec docs/checkout.svg > checkout.json   # print the spec in the SVG
 # edit checkout.json: set "props.rail" to "only"
 npx flowfig checkout.json docs/checkout-rail-only.svg
-npx flowfig verify docs/checkout.svg                    # check that each source still exists
+npx flowfig verify docs/checkout.svg                    # check each source and each edge against the code
 npx flowfig diff old.svg docs/checkout.svg              # list what changed in the spec
 ```
 
@@ -281,14 +291,14 @@ full reference, run `npx flowfig docs`.
 
 `layout` is a group. A group holds boxes and other groups.
 
-| Field       | Meaning                                                         | Default                                             |
-| ----------- | --------------------------------------------------------------- | --------------------------------------------------- |
-| `children`  | The boxes and groups in the group, in order.                    | required                                            |
-| `id`        | The name that an edge can use to reach the whole group.         | none                                                |
-| `label`     | The title of the frame. Only a group with a label has a frame.  | none                                                |
-| `direction` | `"row"` puts the children side by side. `"column"` stacks them. | `"row"`                                             |
-| `gap`       | The space between the children in px.                           | column: 28; row: fits the widest label, at least 56 |
-| `align`     | `"start"`, `"center"` or `"end"`, across the direction.         | `"center"` (a column stretches)                     |
+| Field       | Meaning                                                                                                  | Default                                             |
+| ----------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `children`  | The boxes and groups in the group, in order.                                                             | required                                            |
+| `id`        | The name that an edge can use to reach the whole group.                                                  | none                                                |
+| `label`     | The title of the frame. Only a group with a label has a frame.                                           | none                                                |
+| `direction` | `"row"` puts the children side by side. `"column"` stacks them.                                          | `"row"`                                             |
+| `gap`       | The smallest space between the children in px. It grows to fit the labels of edges that cross the group. | column: 28; row: fits the widest label, at least 56 |
+| `align`     | `"start"`, `"center"` or `"end"`, across the direction.                                                  | `"center"` (a column stretches)                     |
 
 ### Edges
 
@@ -358,7 +368,7 @@ figure: 5 boxes, 3 groups, 4 edges, 2 steps, 6 messages
 
 The last line gives the counts of the parts of the figure. Compare the counts with the parts that you planned.
 
-`flowfig check` has 22 rules: 11 errors and 11 warnings.
+`flowfig check` has 23 rules: 11 errors and 12 warnings.
 
 | Rule                        | Severity | What it finds                                                                                       |
 | --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
@@ -384,6 +394,7 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | `timeline-and-lanes`        | warning  | The figure sets `timeline` and `lanes`. The renderers draw the timeline and ignore `lanes`.         |
 | `font-estimated`            | warning  | `theme.font` is set. The SVG check estimates text width for the system font.                        |
 | `color-not-checked`         | warning  | A color that the check cannot read, so its contrast is not checked.                                 |
+| `plain-text`                | warning  | Text with a code name, a filler word, or a `say` or caption over 20 words.                          |
 
 | Option            | Effect                                                                                                     |
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -431,6 +442,23 @@ fails when the file or the symbol is gone. The action runs `verify` on every fig
 the new image for each SVG the PR changes, with the spec changes as a list, and it names each figure whose linked code the PR
 changes.
 
+`verify` prints one count line for each figure, and gives each edge one result:
+
+```console
+docs/login.svg: 7 of 7 boxes defined; edges: 9 found, 0 not found, 1 unsure, 1 not checked
+```
+
+- found: the caller code calls or references the callee through an import, the same file or a typed receiver.
+- not found: the caller code does not. `verify` warns, and `--strict` makes it an error.
+- unsure: `verify` cannot decide, for example when a receiver has no declared type. `verify` lists it with the reason. It never fails CI.
+- not checked: the edge has no `source`, or the language is not supported.
+
+A method source is `path#Owner.name`. An edge `source` names the function that makes the call.
+
+`via` on an edge names the route, queue, topic, table, file or key that both sides use. For a `via` edge, found means that the caller code and the callee file both use that token. It does not prove that a handler serves it.
+
+Edge checks support TypeScript/JavaScript, Python, Go, Java, C# and Rust. Other files keep the name check for boxes.
+
 A process figure for a team links its boxes to the SOP document, not to code: `"source": "docs/sop/refunds.md#step-3-approve-or-reject"`. The symbol is the heading as a GitHub anchor. If the heading is gone, `verify` fails.
 
 ```yaml
@@ -450,7 +478,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.7.0
+      - uses: iamalvisng/flowfig@v0.8.1
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -458,7 +486,8 @@ jobs:
 ## MCP server
 
 `npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.
-`render` writes the SVG file and returns the check lines and the path, so no SVG text goes through the model.
+`render` writes the SVG file and returns the check lines and the path, so no SVG text goes through the model. `docs` takes an
+optional `topic`.
 
 `npx flowfig init` registers the server for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), GitHub Copilot
 (`.vscode/mcp.json`), Gemini CLI (`.gemini/settings.json`) and Kiro (`.kiro/settings/mcp.json`). It merges one entry into
@@ -484,6 +513,7 @@ The player has these controls:
 - A pause button, and a speed button that changes between 1× and 2×.
 - A full screen button. Esc closes full screen.
 - A hover on a box highlights its edges. With the rail, a click on a row starts that message, and a hover highlights its edge.
+- A hover on a box, an edge or a rail row with a `source` shows the `source`. The SVG shows it as a tooltip too.
 
 The player props are the spec fields. `theme` sets the colors, `speed` sets the packet time, and `autoplay={false}` stops the
 auto start. `check` runs the check rules. If a figure is wider than its container, the player shrinks the figure to half size at
@@ -523,7 +553,8 @@ writeFileSync('first.svg', toSvg(spec));
 - `check(spec, options)` returns the findings. It also takes `width` and `minText`.
 - `render(spec, options)` returns `{ svg, scene }`. The scene is the layout that the check reads. Its shape can change.
 
-`flowfig/verify` is for Node only. It exports `verify`, `links`, `owners` and `parseSource`, the same checks as `flowfig verify`.
+`flowfig/verify` is for Node only. It exports `verify`, `verifyReport` (the findings and the counts), `links`, `owners` and `parseSource`, the same checks
+as `flowfig verify`.
 
 `toSvg` does not put the spec in the SVG. Only the CLI adds the spec, which `--spec` reads back.
 
@@ -566,7 +597,8 @@ A section sits between `<!-- flowfig:start -->` and `<!-- flowfig:end -->`. A se
 of the file. A second run also replaces a whole file that `init` wrote. If a whole file exists and did not come from `init`,
 `init` skips the file. `init` also skips a section file that has a start marker and no end marker.
 
-`npx flowfig docs` prints the full guide as Markdown.
+`npx flowfig docs` prints the core guide as Markdown. `npx flowfig docs <topic>` prints one topic: `lanes`, `timeline`, `rail`,
+`marks` or `verify`.
 
 ## What flowfig does not draw
 

package/dist/check.js

@@ -1,11 +1,68 @@
 import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, lanePlan, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
 import { layoutRail } from './rail.js';
-import { crosses } from './geometry.js';
+import { crosses, hit as curveHit } from './geometry.js';
 import { textWidth } from './text.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
 const warn = (rule, ids, message) => ({ rule, severity: 'warning', ids, message });
 const groupIds = (g) => [...(g.id ? [g.id] : []), ...g.children.flatMap((c) => (isGroup(c) ? groupIds(c) : []))];
+const FILLER = /\b(seamless(ly)?|robust|powerful|leverag(e|es|ed|ing)|effortless(ly)?|cutting-edge|state-of-the-art|holistic|synergy|empower(s|ed|ing)?|elegant(ly)?)\b/i;
+const codeShape = (t) => /^[^A-Za-z]*[a-z][A-Za-z0-9]*[A-Z]|[A-Za-z]_[A-Za-z]|\(\)|::|\w\.\w+\(/.test(t);
+const DB_COMMAND = /^(SELECT|INSERT|UPDATE|DELETE|UPSERT|MERGE|SET|GET|DEL|HSET|HGET|HDEL|EXPIRE|INCR|DECR|LPUSH|RPUSH|LPOP|RPOP|SADD|ZADD|PUBLISH|XADD)\b/;
+const HTTP_LINE = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) \//;
+const codeToken = (t) => codeShape(t) || t.split(/[./]/).some(codeShape);
+function plainText(fig) {
+    const out = [];
+    const check = (owner, field, text, o = {}) => {
+        const t = str(text).trim();
+        if (!t)
+            return;
+        const tokens = t.split(/\s+/);
+        const symbol = o.source
+            ? parseSource(o.source)
+                ?.symbol?.split(/[.#:]+/)
+                .pop()
+            : undefined;
+        const code = o.code === false ? undefined : tokens.find((w) => codeToken(w) || (w === symbol && /[a-z][A-Z]/.test(w)));
+        const filler = FILLER.exec(t)?.[0];
+        const command = o.command && DB_COMMAND.test(t) && !HTTP_LINE.test(t);
+        const why = [
+            command && `${field} "${t}" looks like code; use plain words`,
+            code &&
+                (tokens.length === 1 && field === 'label'
+                    ? `${field} "${t}" looks like code; use plain words, the code name goes in source; if this is a product name, keep it`
+                    : `${field} has the code name "${code}"; use plain words; if this is a product name, keep it`),
+            symbol && t === symbol && !code && !/^[A-Za-z]+$/.test(t) && `${field} "${t}" repeats its source; use plain words`,
+            filler && `${field} "${t}" has the filler word "${filler}"`,
+            o.words && tokens.length > 20 && `${field} has ${tokens.length} words; keep it to 20`,
+        ].filter(Boolean);
+        if (why.length)
+            out.push(warn('plain-text', [], `${owner}: ${why.join('; ')}`));
+    };
+    for (const n of nodes(fig.layout)) {
+        check(`box "${n.id}"`, 'label', n.label, { source: n.source, command: true });
+        check(`box "${n.id}"`, 'sub', n.sub);
+    }
+    const groupLabels = (g) => {
+        if (g.label != null)
+            check(`group "${g.id ?? str(g.label)}"`, 'label', g.label);
+        for (const c of g.children)
+            if (isGroup(c))
+                groupLabels(c);
+    };
+    groupLabels(fig.layout);
+    fig.edges.forEach((e) => check(`edge "${edgeId(e)}"`, 'label', e.label, { source: e.source, command: true }));
+    for (const s of fig.steps ?? []) {
+        const name = str(s.label);
+        check(`step "${name}"`, 'label', s.label);
+        check(`step "${name}"`, 'caption', s.caption, { words: true });
+        s.flow.map(toBeat).forEach((b, i) => {
+            check(`step "${name}"`, `say ${i + 1}`, b.say, { words: true });
+            b.hops.forEach((h) => check(`step "${name}"`, `data ${i + 1}`, h.data, { code: false }));
+        });
+    }
+    return out;
+}
 /** Faults in the spec: dangling ids, duplicate ids, empty steps. The renderers skip them silently. */
 export function checkSpec(fig) {
     const out = [];
@@ -44,9 +101,12 @@ export function checkSpec(fig) {
         if (e.quiet && !used.has(edges[i]))
             out.push(err('hidden-edge', [edges[i]], `edge "${edges[i]}" is quiet and no beat uses it, so the figure never shows it`));
     });
-    for (const [who, source] of owners(fig))
+    for (const [who, source, via] of owners(fig)) {
         if (source != null && !parseSource(source))
             out.push(warn('bad-source', [], `${who}: source "${source}" is not path or path#symbol`));
+        if (via != null && (typeof via !== 'string' || !/^\S+$/.test(via)))
+            out.push(warn('bad-source', [], `${who}: via ${JSON.stringify(via)} is not a string of one word`));
+    }
     const marks = nodes(fig.layout).map((n) => n.mark);
     const starts = marks.filter((m) => m === 'start').length;
     const ends = marks.filter((m) => m === 'end').length;
@@ -101,6 +161,7 @@ export function checkSpec(fig) {
     for (const n of nodes(fig.layout))
         if (n.at != null && !validAt(n.at))
             out.push(err('bad-at', [n.id], `box "${n.id}": at ${n.at} is not an integer of 0 or more`));
+    out.push(...plainText(fig));
     return out;
 }
 const at = ([p0, p1, p2, p3], t) => {
@@ -125,11 +186,9 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
         if (e.behind && !e.elbow)
             continue;
         const line = e.elbow ?? e.pts;
-        const pts = line
-            ? line.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(line[k], q, i / 16)))
-            : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+        const pts = line?.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(line[k], q, i / 16)));
         for (const b of scene.boxes)
-            if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, 2)))
+            if (b.id !== e.from && b.id !== e.to && (pts ? pts.some((p) => inside(p, b.rect, 2)) : curveHit(e.curve, [b.rect], -2).length))
                 out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}"`));
     }
     const pills = scene.edges.filter((e) => e.pts && e.label);
@@ -178,6 +237,9 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
         for (const b of scene.boxes)
             if (overlap(e.label, b.rect, 1))
                 out.push(err('label-overlap', [e.id, b.id], `the label of edge "${e.id}" covers box "${b.id}"`));
+        const [p, a] = [e.label, scene.area];
+        if (a && e.step == null && (p.x < a.x - 0.5 || p.y < a.y - 0.5 || p.x + p.w > a.x + a.w + 0.5 || p.y + p.h > a.y + a.h + 0.5))
+            out.push(err('label-overlap', [e.id], `the label of edge "${e.id}" is outside the figure`));
     });
     const shown = scene.minFont * Math.min(1, width / scene.width);
     if (shown < minText)

package/dist/cli.js

@@ -14,7 +14,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { captureFrames, findBrowser, launch } from './browser.js';
 import { delays, encodeGif } from './gif.js';
-import { GUIDE } from './guide.js';
+import { GUIDE, TOPICS } from './guide.js';
 import { runDraw } from './draw.js';
 import { runInit } from './init.js';
 import { serve } from './mcp.js';
@@ -22,22 +22,22 @@ import { openedLine, openSvg, runOpen } from './open.js';
 import { pageHtml } from './page.js';
 import { decodePng } from './png.js';
 import { diff, formatDiff } from './diff.js';
-import { loadSpec, reportLines, sortFindings, specOf, svgWithSpec } from './load.js';
+import { loadSpec, reportLines, sortFindings, specOf, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render, toSvg } from './svg.js';
 import { checkRendered } from './check.js';
-import { links, verify } from './verify.js';
+import { coverageLine, links, unsureLines, verifyReport } from './verify.js';
 const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   render a figure; a spec on stdin with -
        flowfig check <-|spec.json|figure.ts|figure.svg>   list the faults; the input can be an SVG this wrote
        flowfig --spec figure.svg                          print the spec the SVG carries
        flowfig verify <input>... [--root <dir>] [--json] [--strict]   check the code links of one or more figures
        flowfig diff <old> <new> [--json|--md]   list the spec changes between two figures
-       flowfig docs                                       print the guide (Markdown)
+       flowfig docs [topic]                               print the guide, or one topic (Markdown)
        flowfig mcp                                        serve check, render, verify, diff and docs over MCP (stdio)
        flowfig init [dir] [--agents <ids>] [-y] [--global] [--dry-run] [--no-mcp]   write flowfig instructions for the coding agents of a repo
        flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json] [--open]   ask Claude Code for a figure, then check it
        flowfig open <figure.svg> [--html <path>]          show the figure in the default browser
        flowfig gif <figure.svg> [out.gif] [--step <n>] [--dark] [--fps <n>] [--scale <n>] [--mp4]   write an animated GIF
-flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only)`;
+flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only), --no-verify (render only)`;
 function usage(message) {
     console.error(message);
     process.exit(2);
@@ -62,7 +62,10 @@ if (!args[0] || ['help', '--help', '-h'].includes(args[0])) {
     process.exit(0);
 }
 if (args[0] === 'docs') {
-    process.stdout.write(GUIDE);
+    const topic = args[1];
+    if (topic && !Object.hasOwn(TOPICS, topic))
+        usage(`unknown topic ${topic}; topics: ${Object.keys(TOPICS).join(', ')}`);
+    process.stdout.write(topic ? TOPICS[topic] : GUIDE);
     process.exit(0);
 }
 if (args[0] === 'mcp') {
@@ -120,20 +123,28 @@ if (args[0] === 'verify') {
         usage('verify needs at least one figure');
     const findings = [];
     const all = [];
+    const coverage = [];
     for (const input of args) {
         const props = await load(input);
-        const found = sortFindings([...check(props), ...verify(props, { root })], strict).map((f) => ({ ...f, figure: input }));
+        const report = verifyReport(props, { root });
+        const found = sortFindings([...check(props), ...report.findings], strict).map((f) => ({ ...f, figure: input }));
         findings.push(...found);
+        coverage.push({ figure: input, ...report.coverage });
         all.push(...links(props).map((l) => ({ ...l, figure: input })));
     }
     const errors = findings.filter((f) => f.severity === 'error').length;
     if (json)
-        console.log(JSON.stringify({ findings, links: all }, null, 2));
+        console.log(JSON.stringify({ findings, links: all, coverage }, null, 2));
     else {
         const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
         for (const f of findings)
             console.log(`${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.figure}: ${f.message}`);
         console.log(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
+        for (const c of coverage) {
+            console.log(coverageLine(c.figure, c));
+            for (const l of unsureLines(c))
+                console.log(l);
+        }
     }
     process.exit(errors ? 1 : 0);
 }
@@ -308,7 +319,7 @@ if (args[0] === 'gif') {
     process.exit(stopped || code);
 }
 const command = args[0] === 'check' ? args.shift() : 'render';
-const json = flag('--json'), strict = flag('--strict'), skip = flag('--no-check'), open = flag('--open');
+const json = flag('--json'), strict = flag('--strict'), skip = flag('--no-check'), skipVerify = flag('--no-verify'), open = flag('--open');
 if (command === 'check' && open)
     usage('--open works with a render, not with check');
 const opts = { width: value('--width'), minText: value('--min-text') };
@@ -322,9 +333,9 @@ const props = await load(input);
 const rendered = skip ? undefined : render(props, opts);
 const findings = rendered ? sortFindings(checkRendered(props, opts, rendered.scene), strict) : [];
 const errors = findings.filter((f) => f.severity === 'error').length;
-const report = (print, tty) => {
+const report = (print, tty, extra = []) => {
     const paint = (s) => tty && !process.env.NO_COLOR ? s.replace(/^(error {3}|warning )/, (w) => `\x1b[${w[0] === 'e' ? 31 : 33}m${w}\x1b[0m`) : s;
-    for (const line of reportLines(props, findings, !skip))
+    for (const line of [...reportLines(props, findings, !skip), ...extra])
         print(paint(line));
 };
 if (command === 'check') {
@@ -334,10 +345,10 @@ if (command === 'check') {
         report(console.log, process.stdout.isTTY);
     process.exit(errors ? 1 : 0);
 }
-report(console.error, process.stderr.isTTY);
+const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
+report(console.error, process.stderr.isTTY, errors ? [] : [...summaryLines(props), ...(skipVerify ? [] : verifyLines(props, dest))]);
 if (errors)
     process.exit(1);
-const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
 const withSpec = svgWithSpec(props, opts, rendered?.svg);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);

package/dist/code.d.ts

@@ -0,0 +1,26 @@
+export type Lang = 'ts' | 'py' | 'go' | 'java' | 'cs' | 'rs';
+export type Read = {
+    (full: string): string | null;
+    files?: (root: string) => string[];
+};
+export type CodeFile = {
+    path: string;
+    lang: Lang;
+    text: string;
+    code: string;
+    keep: string;
+};
+export declare const langOf: (path: string) => Lang | null;
+export declare const readFile: Read;
+type Extent = [number, number];
+export declare const esc: (s: string) => string;
+export declare function matchClose(code: string, open: number): number;
+export declare function pyBody(code: string, start: number): Extent;
+export declare function outside(root: string, path: string): boolean;
+export declare function codeFile(root: string, path: string, read?: Read, cache?: Map<string, CodeFile | null>): CodeFile | null;
+export declare function locate(file: CodeFile, symbol: string): {
+    start: number;
+    end: number;
+} | null;
+export declare const isDefined: (file: CodeFile, symbol: string) => boolean;
+export {};