flowfig 0.8.0 → 0.8.1

package/README.md

@@ -65,7 +65,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.8.0
+      - uses: iamalvisng/flowfig@v0.8.1
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -117,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
@@ -167,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 |
@@ -215,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": [
     {
@@ -235,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)
@@ -283,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
 
@@ -360,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                                                                                       |
 | --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
@@ -386,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                                                                                                     |
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -469,7 +478,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.8.0
+      - uses: iamalvisng/flowfig@v0.8.1
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -477,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
@@ -503,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
@@ -586,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 = [];
@@ -104,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) => {
@@ -128,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);
@@ -181,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,7 +22,7 @@ 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 { coverageLine, links, unsureLines, verifyReport } from './verify.js';
@@ -31,13 +31,13 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   rende
        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') {
@@ -316,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') };
@@ -330,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') {
@@ -342,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/diff.js

@@ -19,9 +19,16 @@ function compare(kind, before, after, fieldsOf) {
             out.push({ kind, op: 'added', id });
     return out;
 }
-const messages = (fig) => new Map((fig.steps ?? [])
-    .flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}${h.tone ? ` [${h.tone}]` : ''}`)))
-    .map((id) => [id, id]));
+const messages = (fig) => {
+    const seen = new Map();
+    const ids = (fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => {
+        const key = `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}${h.tone ? ` [${h.tone}]` : ''}${h.source ? ` <${h.source}>` : ''}${h.via ? ` via ${h.via}` : ''}`;
+        const n = (seen.get(key) ?? 0) + 1;
+        seen.set(key, n);
+        return n > 1 ? `${key} #${n}` : key;
+    })));
+    return new Map(ids.map((id) => [id, id]));
+};
 export function diff(before, after) {
     const boxes = (f) => {
         const m = new Map();
@@ -33,8 +40,8 @@ export function diff(before, after) {
     const steps = (f) => new Map((f.steps ?? []).map((s) => [str(s.label), s]));
     const out = [
         ...compare('box', boxes(before), boxes(after), (a, b) => fields(a, b, ['label', 'sub', 'shape', 'tone', 'mark', 'from', 'to', 'source', 'group'])),
-        ...compare('edge', edges(before), edges(after), (a, b) => fields(a, b, ['from', 'to', 'label', 'source'])),
-        ...compare('step', steps(before), steps(after), () => []),
+        ...compare('edge', edges(before), edges(after), (a, b) => fields(a, b, ['from', 'to', 'label', 'source', 'via'])),
+        ...compare('step', steps(before), steps(after), (a, b) => fields(a, b, ['caption'])),
         ...compare('message', messages(before), messages(after), () => []),
     ];
     // The rail is a boolean or 'only', so str() would hide it.

package/dist/draw.js

@@ -22,7 +22,7 @@ export function slug(question) {
 const specPath = (out) => out.replace(/\.svg$/, '.json');
 export function agentArgs(o) {
     const spec = specPath(o.out);
-    const system = `${AGENT_TEXT.trimEnd()}\n\nWrite the spec to ${spec} with the Write tool. Then run exactly \`npx flowfig ${spec} ${o.out}\` as one command, alone on its line: no heredoc, no \`;\`, no \`&&\`, no pipe (the permission rule matches one plain command only). Then run \`npx flowfig verify ${o.out}\` the same way. Run every command from this folder, ${o.cwd}.`;
+    const system = `${AGENT_TEXT.trimEnd()}\n\nWrite the spec to ${spec} with the Write tool. Then run exactly \`npx flowfig ${spec} ${o.out}\` as one command, alone on its line: no heredoc, no \`;\`, no \`&&\`, no pipe (the permission rule matches one plain command only). Run every command from this folder, ${o.cwd}.`;
     const args = [
         '-p',
         o.question,

package/dist/edges.js

@@ -38,6 +38,30 @@ const CONSTS = {
     cs: /^[ \t]*(?:(?:public|private|protected|internal)\s+)?const\s+string\s+(\w+)\s*=\s*(")([^"\n]*)"/gm,
     rs: /^(?:pub(?:\([^)]*\))?\s+)?const\s+(\w+)\s*:\s*&(?:'static\s+)?str\s*=\s*(")([^"\n]*)"/gm,
 };
+const VARIABLE = {
+    ts: /^\s*(?:export\s+)?(?:const|let|var)\s/,
+    py: /^[\p{L}_][\p{L}\p{N}_]*\s*(?::[^=\n]*)?=(?!=)/u,
+    go: /^\s*(?:var|const)\b/,
+    rs: /^\s*(?:pub(?:\([^)]*\))?\s+)?(?:static|const|let)\b/,
+    java: /^[^({=;]*[=;]/,
+    cs: /^[^({=;]*[=;]/,
+};
+function topStatements(code, name) {
+    let out = '';
+    for (const m of code.matchAll(new RegExp(`^${esc(name)}\\s*[.[(]`, 'gm'))) {
+        let i = m.index;
+        for (let d = 0; i < code.length; i++) {
+            if ('([{'.includes(code[i]))
+                d++;
+            else if (')]}'.includes(code[i]))
+                d--;
+            else if (d <= 0 && (code[i] === ';' || (code[i] === '\n' && !/^\s*[.)]/.test(code.slice(i + 1, i + 80)))))
+                break;
+        }
+        out += '\n' + code.slice(m.index, i + 1);
+    }
+    return out;
+}
 const IMPORT_LINES = /\b(?:import|export)\s+(?:type\s+)?[\w*\s,{}$]*?\bfrom\b|^[ \t]*(?:from|use|using|package|import)\b.*|.*\brequire\(.*/gm;
 const MODIFIERS = new Set([
     'mut',
@@ -86,14 +110,25 @@ function params(body, from) {
     }
     return [...parts, text.slice(last)];
 }
+function paramName(p, lang) {
+    const tokens = (p.split('=')[0].match(/[\w$]+/g) ?? []).filter((t) => !MODIFIERS.has(t));
+    return lang === 'java' || lang === 'cs' ? tokens.at(-1) : tokens[0];
+}
+function paramCall(body, lang, fromName) {
+    const open = body.indexOf('(', fromName ? Math.max(0, body.indexOf(fromName)) : 0);
+    if (open < 0)
+        return undefined;
+    const rest = body.slice(matchClose(body, open) + 1);
+    return params(body, fromName)
+        .map((p) => paramName(p, lang))
+        .find((n) => n && new RegExp(`(?<![\\w$.])${esc(n)}\\s*\\(`).test(rest));
+}
 function shadows(body, name, lang, fromName, whole) {
     const n = esc(name);
     if (!whole)
-        for (const p of params(body, fromName)) {
-            const tokens = (p.split('=')[0].match(/[\w$]+/g) ?? []).filter((t) => !MODIFIERS.has(t));
-            if ((lang === 'java' || lang === 'cs' ? tokens.at(-1) : tokens[0]) === name)
+        for (const p of params(body, fromName))
+            if (paramName(p, lang) === name)
                 return true;
-        }
     return ([`\\b(let|const|var|val|mut)\\s+${n}(?![\\w$])`, `(?<![\\w$.])${n}\\s*:=`, `(^|[\\n;{])[ \\t]*${n}\\s*(:[^=\\n]+)?=(?![=>])`].some((p) => new RegExp(p).test(body)) || typedName(body, n));
 }
 const defaultIs = (ti, symbol) => new RegExp(`export\\s+default\\s+(async\\s+)?(function\\s*\\*?\\s*|class\\s+)?${esc(symbol.split('.')[0])}\\b`).test(ti.code);
@@ -284,9 +319,18 @@ export function edgeResult(root, caller, callee, via, read = readFile, cache = n
     let body = fi.code.slice(at.start, at.end);
     if (whole)
         body = body.replace(IMPORT_LINES, (m) => m.replace(/[^\n]/g, ' '));
+    const isVar = !whole && VARIABLE[fi.lang].test(body);
+    if (isVar && (fi.lang === 'ts' || fi.lang === 'py'))
+        body += topStatements(fi.code, from.symbol.split('.').at(-1));
+    const doubt = () => {
+        if (isVar && fi.lang !== 'ts' && fi.lang !== 'py')
+            return { result: 'unsure', reason: `${label(from)} is a variable; verify does not read its uses` };
+        const p = whole ? undefined : paramCall(body, fi.lang, from.symbol?.split('.').at(-1));
+        return p ? { result: 'unsure', reason: `the caller calls its parameter ${p}; the target is not known` } : null;
+    };
     if (!to.symbol) {
         const r = fileResult(root, fi, ti, body, whole, from, to, read, cache);
-        return r.result === 'not-found' ? { ...r, reason: r.reason + hint() } : r;
+        return r.result === 'not-found' ? (doubt() ?? { ...r, reason: r.reason + hint() }) : r;
     }
     const toParts = to.symbol.split('.');
     const toName = toParts.at(-1);
@@ -388,7 +432,7 @@ export function edgeResult(root, caller, callee, via, read = readFile, cache = n
                 return unsure(`${n} has no path to ${owner}`);
             }
             const dynamic = new RegExp(`\\{[^}]*\\b${esc(n)}\\b[^}]*\\}\\s*=\\s*(?:await\\s+)?(?:import|require)\\(`).test(body);
-            if ((shadowed || (n === toName && !dynamic && localType(cx, fi, body, n, lang, !whole))) && n !== fromName)
+            if ((shadowed || (n === toName && !dynamic && localType(cx, fi, body, n, lang, !whole && !isVar))) && n !== fromName)
                 return ignore;
             if (pyStar)
                 return unsure(`${n} can come from a star import`);
@@ -506,5 +550,8 @@ export function edgeResult(root, caller, callee, via, read = readFile, cache = n
     const pick = verdicts.find((v) => v.res === 'found') ?? verdicts.find((v) => v.res === 'unsure');
     if (pick)
         return { result: pick.res === 'found' ? 'found' : 'unsure', reason: pick.why };
+    const d = [...names].some((n) => word(n).test(body)) ? null : doubt();
+    if (d)
+        return d;
     return { result: 'not-found', reason: `${who} does not call ${toName}${hint()}` };
 }

package/dist/geometry.d.ts

@@ -25,12 +25,19 @@ export type Routed = {
     curve: [Pt, Pt, Pt, Pt];
     stub?: Stub;
     elbow?: Pt[];
+    around?: Around;
+    /** The px a detour and its label need outside the boxes on the `around` side. */
+    room?: number;
+    /** The px an elbow detour goes outside the boxes, for each side. */
+    bleed?: Partial<Record<Around, number>>;
 };
 /** A rect that a route keeps clear of. `box` marks a box. */
 export type Avoid = Rect & {
     box?: boolean;
 };
-type Around = 'above' | 'below';
+export declare const avoidOf: (boxes: Rect[], extra: Rect[], lanes: boolean) => Avoid[];
+type Around = 'above' | 'below' | 'left' | 'right';
+export declare const hit: (curve: [Pt, Pt, Pt, Pt], boxes: Rect[], m: number) => Rect[];
 /** Routes edges between measured boxes as curved SVG paths. `elbow` draws right-angle paths; `stub` splits a cross-lane edge in two. */
 export declare function route(edges: {
     id: string;
@@ -45,7 +52,9 @@ export declare function route(edges: {
 }[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Avoid[], area?: Rect, lanes?: {
     bands: Rect[];
     boxes: Rect[];
-}): Routed[];
+}, pad?: number): Routed[];
+export declare const arcRoom: (routed: Routed[], way: Around) => number;
+export declare function labelAlong(r: Routed, w: number, boxes: Rect[], placed: Rect[], fig?: Rect, lines?: Pt[]): Pt;
 /** True if segment a-b crosses c-d. The ends of a-b are trimmed by 1.5 px. */
 export declare function crosses(a: Pt, b: Pt, c: Pt, d: Pt): boolean;
 export {};