flowfig 0.8.3 → 0.9.0

package/README.md

@@ -65,7 +65,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.8.3
+      - uses: iamalvisng/flowfig@v0.9.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -183,6 +183,8 @@ The options are in [Open and share a figure](#open-and-share-a-figure).
 - [Check a figure](#check-a-figure)
 - [Open and share a figure](#open-and-share-a-figure)
 - [Verify in CI](#verify-in-ci)
+- [Trace the calls of a function](#trace-the-calls-of-a-function)
+- [Find stale figures](#find-stale-figures)
 - [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
@@ -478,11 +480,97 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.8.3
+      - uses: iamalvisng/flowfig@v0.9.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
 
+## Trace the calls of a function
+
+`flowfig trace` lists the calls that one function makes, and the calls that those calls make. Ask your coding agent to run it
+before it writes a figure. Then the agent reads only the lines that the trace names. Each edge passes the same check as
+`verify`.
+
+```console
+$ npx flowfig trace src/verify.ts#verify
+src/verify.ts#verify -> src/verify.ts#verifyReport          src/verify.ts:104
+src/verify.ts#verifyReport -> src/verify.ts#emptyCoverage   src/verify.ts:48
+src/verify.ts#verifyReport -> src/source.ts#links           src/verify.ts:49
+src/verify.ts#verifyReport -> src/code.ts#outside           src/verify.ts:58
+src/verify.ts#verifyReport -> src/code.ts#codeFile          src/verify.ts:65
+src/verify.ts#verifyReport -> src/code.ts#isDefined         src/verify.ts:67
+src/verify.ts#verifyReport -> src/verify.ts#escape          src/verify.ts:69
+src/verify.ts#verifyReport -> src/verify.ts#hasHeading      src/verify.ts:70
+src/verify.ts#verifyReport -> src/model.ts#nodes            src/verify.ts:79
+src/verify.ts#verifyReport -> src/edges.ts#edgeResult       src/verify.ts:81
+src/verify.ts#verifyReport -> src/model.ts#edgeId           src/verify.ts:91
+src/verify.ts#verifyReport -> src/model.ts#toBeat           src/verify.ts:95
+stop    depth 2: 11 symbols not followed
+summary: 13 symbols, 12 found, 0 unsure, 0 open, 4 calls outside the repo, 0.1 s
+```
+
+- An edge line gives the caller, the callee, and the file and line of the call.
+- `unsure`: trace cannot name the target. An example is a call of a parameter.
+- `open`: the target is a name in a string, for example a route table entry. Read that line yourself.
+- `stop`: the trace reached `--depth` or `--max`. The line gives the number of functions that it did not follow.
+- A call into a package or the standard library gives no line. The summary line counts these calls.
+
+A call that trace cannot see gives no line, for example a call through an interface with no known type.
+trace reads code as text. In rare cases, two names that look the same can give a wrong edge. `flowfig verify` and your review of the figure still check each edge.
+
+| Option         | Meaning                                            | Default            |
+| -------------- | -------------------------------------------------- | ------------------ |
+| `--depth <n>`  | The number of call levels to follow.               | 2                  |
+| `--max <n>`    | The largest number of edges. Then the trace stops. | 40                 |
+| `--root <dir>` | The repo root. The file path is relative to it.    | the current folder |
+| `--json`       | Print one JSON object in place of the lines.       | off                |
+
+The exit code is 1 if the file or the function is not found. It is also 1 if the language is not TypeScript,
+JavaScript, Python, Go, Java, C# or Rust.
+
+## Find stale figures
+
+`flowfig coverage` reads each figure in the repo and gives it one state. It also shows the code that has no figure. Run
+it each week, or in CI.
+
+```console
+$ npx flowfig coverage --entries 'src/geometry.ts'
+docs/cached-request.svg        ok      3 of 3 boxes defined
+docs/checkout-rail-only.svg    ok      4 of 4 boxes defined
+docs/checkout.svg              ok      4 of 4 boxes defined
+docs/first.svg                 none    no source links
+docs/hero.svg                  none    no source links
+docs/order-status.svg          none    no source links
+docs/refund-process.svg        ok      6 of 6 boxes defined
+docs/returns-process.svg       ok      8 of 8 boxes defined
+docs/roadmap.svg               ok      8 of 8 boxes defined
+uncovered src/geometry.ts: 1 of 1 files have no figure
+  src/geometry.ts
+summary: 9 figures: 6 ok, 0 stale, 0 fail, 3 none
+```
+
+- `fail`: `verify` finds an error, for example a symbol that is gone.
+- `stale`: `verify` finds no error, but a linked file changed in a commit after the last commit of the SVG. A linked file
+  with changes that are not committed counts as changed now.
+- `ok`: `verify` finds no error, and no linked file changed after the SVG.
+- `none`: the figure has no `source` link.
+
+`coverage` reads the commit dates from git. If the folder is not in a git repo, `coverage` does not check `stale`. It
+prints one line that says so.
+
+A figure covers a code file if one of its links names that file. With `--entries`, `coverage` lists each matched code
+file that no figure covers. With no `--entries`, it prints one count line for each top folder.
+
+| Option             | Meaning                                                       | Default            |
+| ------------------ | ------------------------------------------------------------- | ------------------ |
+| `--figures <glob>` | The SVG files to read. Only an SVG with a figure spec counts. | `**/*.svg`         |
+| `--entries <glob>` | The code files that must have a figure.                       | none               |
+| `--root <dir>`     | The repo root.                                                | the current folder |
+| `--strict`         | Exit 1 if a figure is `fail` or `stale`.                      | off                |
+| `--json`           | Print one JSON object in place of the lines.                  | off                |
+
+`coverage` skips `node_modules`, `dist` and each folder with a name that starts with a dot.
+
 ## MCP server
 
 `npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.

package/dist/cli.js

@@ -25,12 +25,16 @@ import { diff, formatDiff } from './diff.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';
+import { coverageLine, links, parseSource, unsureLines, verifyReport } from './verify.js';
+import { trace, traceLines } from './trace.js';
+import { coverageLines, coverageReport } from './coverage.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 trace <file#symbol> [--depth <n>] [--max <n>] [--root <dir>] [--json]   list the calls under a symbol, each one checked
+       flowfig coverage [--figures <glob>] [--entries <glob>] [--root <dir>] [--strict] [--json]   list failing and stale figures, and code with no figure
        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
@@ -54,6 +58,10 @@ const value = (name) => {
     const n = Number(args.splice(i, 2)[1] || NaN);
     return n > 0 && Number.isFinite(n) ? n : usage(`${name} needs a positive number`);
 };
+const option = (name) => {
+    const i = args.indexOf(name);
+    return i === -1 ? undefined : (args.splice(i, 2)[1] ?? usage(`${name} needs a value`));
+};
 if (!args[0] || ['help', '--help', '-h'].includes(args[0])) {
     if (args[0])
         console.log(USAGE);
@@ -148,6 +156,44 @@ if (args[0] === 'verify') {
     }
     process.exit(errors ? 1 : 0);
 }
+if (args[0] === 'trace') {
+    args.shift();
+    const json = flag('--json');
+    const depth = value('--depth') ?? 2, max = value('--max') ?? 40;
+    if (!Number.isInteger(depth) || !Number.isInteger(max))
+        usage('--depth and --max need a whole number');
+    const root = resolve(option('--root') ?? '.');
+    const unknown = args.find((a) => a.startsWith('-'));
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    if (args.length !== 1 || !parseSource(args[0])?.symbol)
+        usage('usage: flowfig trace <file#symbol> [--depth <n>] [--max <n>] [--root <dir>] [--json]');
+    try {
+        const r = trace(args[0], { root, depth, max });
+        console.log(json ? JSON.stringify(r, null, 2) : traceLines(r, depth, max).join('\n'));
+    }
+    catch (e) {
+        console.error(`trace: ${e.message}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+if (args[0] === 'coverage') {
+    args.shift();
+    const json = flag('--json'), strict = flag('--strict');
+    const root = resolve(option('--root') ?? '.');
+    const figures = option('--figures'), entries = option('--entries');
+    const unknown = args.find((a) => a.startsWith('-'));
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    if (args.length)
+        usage('usage: flowfig coverage [--figures <glob>] [--entries <glob>] [--root <dir>] [--strict] [--json]');
+    if (!existsSync(root))
+        usage(`${root}: the folder does not exist`);
+    const r = coverageReport({ root, figures, entries });
+    console.log(json ? JSON.stringify(r, null, 2) : coverageLines(r).join('\n'));
+    process.exit(strict && r.figures.some((f) => f.state === 'fail' || f.state === 'stale') ? 1 : 0);
+}
 if (args[0] === 'diff') {
     args.shift();
     const json = flag('--json'), md = flag('--md');

package/dist/code.d.ts

@@ -16,6 +16,8 @@ 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 depthAt(code: string, pos: number, lo: number): number;
+export declare const definitions: (file: CodeFile, name: string, lo?: number, hi?: number) => number;
 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 const locate: (file: CodeFile, symbol: string) => {

package/dist/code.js

@@ -371,7 +371,7 @@ function defPatterns(lang, name, inContainer) {
     }
 }
 const KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'new', 'await', 'typeof', 'else', 'do', 'throw']);
-function depthAt(code, pos, lo) {
+export function depthAt(code, pos, lo) {
     let d = 0;
     for (let i = lo; i < pos; i++) {
         if (code[i] === '{')
@@ -400,12 +400,12 @@ function pyMemberIndent(code, lo, hi) {
     }
     return min;
 }
-function findIn(code, lang, name, lo, hi, member, receiver) {
+function hitsIn(code, lang, name, lo, hi, member, receiver) {
+    const hits = [];
     if (KEYWORDS.has(name) && !/^(rs|py|go)$/.test(lang))
-        return null;
+        return hits;
     const inContainer = member != null;
     const memberIndent = inContainer && lang === 'py' ? pyMemberIndent(code, lo, hi) : -1;
-    const hits = [];
     const pats = defPatterns(lang, name, inContainer);
     for (const re of pats) {
         re.lastIndex = lo;
@@ -465,6 +465,11 @@ function findIn(code, lang, name, lo, hi, member, receiver) {
             hits.push({ start, end: ext[1], depth });
         }
     }
+    return hits;
+}
+export const definitions = (file, name, lo = 0, hi = file.code.length) => new Set(hitsIn(file.code, file.lang, name, lo, hi, null).map((h) => h.start)).size;
+function findIn(code, lang, name, lo, hi, member, receiver) {
+    const hits = hitsIn(code, lang, name, lo, hi, member, receiver);
     if (!hits.length)
         return null;
     hits.sort((a, b) => a.depth - b.depth || a.start - b.start);

package/dist/coverage.d.ts

@@ -0,0 +1,27 @@
+export type FigureState = 'fail' | 'stale' | 'ok' | 'none';
+export type FigureHealth = {
+    figure: string;
+    state: FigureState;
+    detail: string;
+};
+export type CoverageReport = {
+    figures: FigureHealth[];
+    git: boolean;
+    entries?: {
+        glob: string;
+        total: number;
+        uncovered: string[];
+    };
+    folders?: {
+        folder: string;
+        covered: number;
+        total: number;
+    }[];
+};
+export type CoverageOptions = {
+    root?: string;
+    figures?: string;
+    entries?: string;
+};
+export declare function coverageReport({ root, figures, entries }?: CoverageOptions): CoverageReport;
+export declare function coverageLines(r: CoverageReport): string[];

package/dist/coverage.js

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { posix, resolve } from 'node:path';
+import { langOf, readFile } from './code.js';
+import { loadSpec, specOf } from './load.js';
+import { links, verifyReport } from './verify.js';
+const MARK = '<metadata id="figure-spec">';
+const globRe = (glob) => new RegExp(`^${glob
+    .replace(/^\.\//, '')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\/|\*\*|\*|\?/g, (t) => (t === '**/' ? '(?:.*/)?' : t === '**' ? '.*' : t === '*' ? '[^/]*' : '[^/]'))}$`);
+const day = (t) => (t === Infinity ? 'now' : new Date(t * 1000).toISOString().slice(0, 10));
+const count = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
+function gitTimes(root) {
+    const git = (...a) => execFileSync('git', a, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    try {
+        const prefix = git('rev-parse', '--show-prefix').trim();
+        const dirty = new Set(git('status', '--porcelain', '-z', '--no-renames', '--untracked-files=all')
+            .split('\0')
+            .map((l) => l.slice(3))
+            .filter((p) => p && p.startsWith(prefix))
+            .map((p) => p.slice(prefix.length)));
+        const memo = new Map();
+        return (path) => {
+            if (dirty.has(path))
+                return Infinity;
+            if (!memo.has(path))
+                memo.set(path, Number(git('log', '-1', '--format=%ct', '--', path).trim()) || 0);
+            return memo.get(path);
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function coverageReport({ root = process.cwd(), figures = '**/*.svg', entries } = {}) {
+    const all = readFile.files(root).filter((p) => !p.split('/').includes('dist'));
+    const want = globRe(figures);
+    const time = gitTimes(root);
+    const cache = new Map();
+    const covered = new Set();
+    const out = [];
+    for (const figure of all.filter((p) => p.endsWith('.svg') && want.test(p))) {
+        const text = readFileSync(resolve(root, figure), 'utf8');
+        if (!text.includes(MARK))
+            continue;
+        let fig;
+        try {
+            fig = loadSpec(JSON.parse(specOf(text, figure)), figure);
+        }
+        catch (e) {
+            out.push({ figure, state: 'fail', detail: `bad spec: ${e.message}` });
+            continue;
+        }
+        const paths = [...new Set(links(fig).map((l) => posix.normalize(l.path)))];
+        paths.forEach((p) => covered.add(p));
+        if (!paths.length) {
+            out.push({ figure, state: 'none', detail: 'no source links' });
+            continue;
+        }
+        const { findings, coverage } = verifyReport(fig, { root, cache });
+        const errors = findings.filter((f) => f.severity === 'error');
+        if (errors.length) {
+            out.push({
+                figure,
+                state: 'fail',
+                detail: `${count(errors.length, 'error')}: ${[...new Set(errors.map((f) => f.rule))].join(', ')}`,
+            });
+            continue;
+        }
+        const mine = time?.(figure) || Infinity;
+        const newer = time && paths.find((p) => time(p) > mine);
+        out.push(newer
+            ? { figure, state: 'stale', detail: `${newer} changed ${day(time(newer))}, figure ${day(mine)}` }
+            : { figure, state: 'ok', detail: `${coverage.boxesDefined} of ${coverage.boxes} boxes defined` });
+    }
+    const code = all.filter((p) => langOf(p) != null);
+    const report = { figures: out, git: time != null };
+    if (entries) {
+        const re = globRe(entries);
+        const matched = code.filter((p) => re.test(p));
+        report.entries = { glob: entries, total: matched.length, uncovered: matched.filter((p) => !covered.has(p)) };
+    }
+    else {
+        const by = new Map();
+        for (const p of code) {
+            const folder = p.includes('/') ? p.slice(0, p.indexOf('/')) : '.';
+            const row = by.get(folder) ?? { folder, covered: 0, total: 0 };
+            row.total++;
+            if (covered.has(p))
+                row.covered++;
+            by.set(folder, row);
+        }
+        report.folders = [...by.values()];
+    }
+    return report;
+}
+export function coverageLines(r) {
+    const width = Math.max(0, ...r.figures.map((f) => f.figure.length));
+    const tally = (s) => r.figures.filter((f) => f.state === s).length;
+    return [
+        ...(r.git ? [] : ['no git: stale is not checked']),
+        ...r.figures.map((f) => `${f.figure.padEnd(width + 4)}${f.state.padEnd(8)}${f.detail}`),
+        ...(r.entries
+            ? [
+                `uncovered ${r.entries.glob}: ${r.entries.uncovered.length} of ${r.entries.total} files have no figure`,
+                ...r.entries.uncovered.map((p) => `  ${p}`),
+            ]
+            : []),
+        ...(r.folders ?? []).map((f) => `code ${f.folder}: ${f.covered} of ${f.total} files have a figure`),
+        `summary: ${count(r.figures.length, 'figure')}: ${tally('ok')} ok, ${tally('stale')} stale, ${tally('fail')} fail, ${tally('none')} none`,
+    ];
+}

package/dist/edges.d.ts

@@ -1,6 +1,9 @@
 import { type CodeFile, type Lang, type Read } from './code.ts';
 export type EdgeResult = 'found' | 'not-found' | 'unsure' | 'not-checked';
 export declare const EDGE_LANGS: ReadonlySet<Lang>;
+export declare function params(body: string, from: string | undefined): string[];
+export declare function paramName(p: string, lang: Lang): string | undefined;
+export declare function shadows(body: string, name: string, lang: Lang, fromName: string | undefined, whole: boolean): boolean;
 export declare function edgeResult(root: string, caller: string, callee: string | undefined, via: string | undefined, read?: Read, cache?: Map<string, CodeFile | null>): {
     result: EdgeResult;
     reason: string;

package/dist/edges.js

@@ -90,7 +90,7 @@ function typedName(body, n) {
     }
     return false;
 }
-function params(body, from) {
+export function params(body, from) {
     const open = body.indexOf('(', from ? Math.max(0, body.indexOf(from)) : 0);
     if (open < 0)
         return [];
@@ -110,7 +110,7 @@ function params(body, from) {
     }
     return [...parts, text.slice(last)];
 }
-function paramName(p, lang) {
+export 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];
 }
@@ -123,7 +123,7 @@ function paramCall(body, lang, fromName) {
         .map((p) => paramName(p, lang))
         .find((n) => n && new RegExp(`(?<![\\w$.])${esc(n)}\\s*\\(`).test(rest));
 }
-function shadows(body, name, lang, fromName, whole) {
+export function shadows(body, name, lang, fromName, whole) {
     const n = esc(name);
     if (!whole)
         for (const p of params(body, fromName))

package/dist/geometry.js

@@ -505,13 +505,16 @@ export function labelAlong(r, w, boxes, placed, fig, lines = []) {
             y: Math.max(fig.y + 9, Math.min(at.y, fig.y + fig.h - 9)),
         }
         : at;
-    const free = (at, strict) => {
+    const free = (at, strict, room = 1) => {
         const pill = { x: at.x - w / 2, y: at.y - 9, w, h: 18 };
         return (inFig(at) &&
-            !boxes.some((b) => overlaps(pill, b, 1)) &&
+            !boxes.some((b) => overlaps(pill, b, room)) &&
             !placed.some((b) => overlaps(pill, b, 1)) &&
             (!strict || !lines.some((q) => q.x > pill.x - 2 && q.x < pill.x + w + 2 && q.y > pill.y - 2 && q.y < pill.y + 20)));
     };
+    for (const at of spots)
+        if (free(at, true, 6))
+            return at;
     for (const strict of [true, false])
         for (const at of spots)
             if (free(at, strict))

package/dist/imports.d.ts

@@ -8,4 +8,5 @@ export declare const OUTSIDE = "#outside";
 export declare function resolveTs(root: string, from: string, spec: string, read: Read): string | null;
 export declare function resolvePy(root: string, from: string, mod: string, read: Read, top?: string): string | null;
 export declare function importsOf(root: string, file: CodeFile, read: Read): Import[];
+export declare function reexports(root: string, file: CodeFile, name: string, read: Read): [string | null, string][];
 export declare function leadsTo(root: string, fromPath: string, toPath: string, name: string, read?: Read, cache?: Map<string, CodeFile | null>, depth?: number): string | null;

package/dist/imports.js

@@ -172,7 +172,7 @@ export function importsOf(root, file, read) {
     }
     return out;
 }
-function reexports(root, file, name, read) {
+export function reexports(root, file, name, read) {
     const N = esc(name);
     const out = [];
     if (name === '*')

package/dist/index.js

@@ -1,11 +1,11 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
+import { Fragment, useEffect, useId, useMemo, useRef, useState } from 'react';
 import { arcRoom, avoidOf, route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, labelLines, fitCap, LABEL_LINE, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, edgeTip, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, altText, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, labelLines, fitCap, LABEL_LINE, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -42,12 +42,22 @@ const cardBody = (c) => {
             return (r.tag?.length ?? 0) > 2 ? (_jsxs("div", { children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 5, marginBottom: 1 }, children: [tag, mark] }), text] }, i)) : (_jsxs("div", { style: { display: 'flex', gap: 5, alignItems: 'baseline' }, children: [tag, text, mark] }, i));
         }) }));
 };
+const HIDDEN = {
+    position: 'absolute',
+    width: 1,
+    height: 1,
+    overflow: 'hidden',
+    clip: 'rect(0 0 0 0)',
+    whiteSpace: 'pre-line',
+};
 /**
  * The interactive player for one figure. Give it a `FlowProps` spec.
  * Use `toSvg` from `flowfig/svg` for a static animated SVG.
  */
 export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900, autoplay = true, check = false, rail: withRail = false, lanes, timeline, today, }) {
     const tl = timeline && isLanesLayout(layout);
+    const alt = useMemo(() => altText({ layout, edges, steps: stepsIn }), [layout, edges, stepsIn]);
+    const descId = useId();
     const synthetic = tl && !stepsIn.length;
     const steps = useMemo(() => (synthetic ? timelineBeats({ layout, edges, timeline, today }) : stepsIn), [synthetic, layout, edges, timeline, today, stepsIn]);
     const [axisW, setAxisW] = useState(TL_AXIS_W);
@@ -747,7 +757,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         background: v('bg'),
         color: v('muted'),
     };
-    return (_jsxs("figure", { ref: figure, className: "flowfig", style: {
+    return (_jsxs("figure", { ref: figure, className: "flowfig", "aria-label": alt.title, "aria-describedby": descId, style: {
             ...vars,
             position: full ? 'fixed' : 'relative',
             inset: full ? 0 : undefined,
@@ -760,7 +770,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             background: v('bg'),
             fontFamily: v('font'),
             color: v('fg'),
-        }, children: [_jsx("button", { type: "button", "aria-label": full ? 'Close full screen' : 'Full screen', title: full ? 'Close (Esc)' : 'Full screen', onClick: () => setFull((f) => !f), style: {
+        }, children: [_jsx("div", { id: descId, style: HIDDEN, children: alt.desc }), _jsx("button", { type: "button", "aria-label": full ? 'Close full screen' : 'Full screen', title: full ? 'Close (Esc)' : 'Full screen', onClick: () => setFull((f) => !f), style: {
                     ...iconBtn,
                     position: 'absolute',
                     top: 10,

package/dist/load.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { counts, toBeat } from './model.js';
+import { altText, counts, toBeat } from './model.js';
 import { coverageLine, owners, unsureLines, verifyReport } from './verify.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
@@ -65,7 +65,7 @@ export function summaryLines(props) {
         const hops = s.flow.reduce((k, b) => k + toBeat(b).hops.length, 0);
         return `step "${text(s.label)}": ${hops} ${hops === 1 ? 'hop' : 'hops'}`;
     });
-    return [...edges, ...steps];
+    return [...edges, ...steps, `alt: ${altText(props).title}`];
 }
 export function verifyLines(props, figure, root = process.cwd()) {
     if (!owners(props).some(([, source, via]) => source != null || via != null))

package/dist/model.d.ts

@@ -351,3 +351,7 @@ export declare const counts: (p: FlowProps) => {
     messages: number;
 };
 export declare function groupGap(g: FigGroup, edges: FigEdge[]): number;
+export declare const altText: (fig: FlowProps) => {
+    title: string;
+    desc: string;
+};

package/dist/model.js

@@ -452,22 +452,54 @@ export const counts = (p) => {
     };
 };
 const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
+const LINE_CLEAR = 16;
 export function groupGap(g, edges) {
     const side = new Map();
     g.children.forEach((c, i) => idsIn(c).forEach((id) => side.set(id, i)));
     const spans = edges.filter((e) => e.label != null && side.has(e.from) && side.has(e.to) && side.get(e.from) !== side.get(e.to) && !(g.gap != null && e.around));
     if (g.gap != null && !spans.length)
         return g.gap;
-    const need = Math.max(0, ...spans.map((e) => labelPillW(str(e.label)) + 16));
+    const need = Math.max(0, ...spans.map((e) => labelPillW(str(e.label)) + 2 * LINE_CLEAR));
     if (g.gap != null && g.direction !== 'column')
-        return Math.max(g.gap, need - 16);
+        return Math.max(g.gap, need);
     let auto;
     if (g.direction === 'column') {
         const ends = spans.map((e) => [side.get(e.from), side.get(e.to)].sort((p, q) => p - q));
         const most = Math.max(0, ...g.children.map((_, k) => ends.filter(([lo, hi]) => lo <= k && k < hi).length));
-        auto = most > 1 ? Math.min(most, 3) * 22 + 16 : 28;
+        auto = most ? Math.min(most, 3) * 22 + 2 * LINE_CLEAR - 4 : 28;
     }
     else
         auto = Math.max(56, need);
     return Math.max(g.gap ?? 0, auto);
 }
+export const altText = (fig) => {
+    const names = new Map();
+    const walk = (g) => g.children.forEach((c) => {
+        if (c.id)
+            names.set(c.id, str(c.label) || c.id);
+        if (isGroup(c))
+            walk(c);
+    });
+    walk(fig.layout);
+    const name = (id) => names.get(id) ?? id;
+    const ends = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    const boxes = nodes(fig.layout).map((n) => name(n.id));
+    const steps = fig.steps ?? [];
+    const lines = steps.flatMap((s) => [
+        `${str(s.label)}.`,
+        ...s.flow.map(toBeat).flatMap((b) => {
+            if (str(b.say))
+                return [str(b.say)];
+            return b.hops.flatMap((h) => {
+                const e = ends.get(h.edge);
+                if (!e)
+                    return [];
+                return [h.back ? `${name(e.to)} to ${name(e.from)}` : `${name(e.from)} to ${name(e.to)}`];
+            });
+        }),
+    ]);
+    return {
+        title: `Flow figure: ${boxes.join(', ')}.${steps.length ? ` Steps: ${steps.map((s) => str(s.label)).join(', ')}.` : ''}`,
+        desc: [`The figure has these boxes: ${boxes.join(', ')}.`, ...lines].join('\n'),
+    };
+};

package/dist/svg.js

@@ -5,7 +5,7 @@ import { textWidth, wrap } from './text.js';
 import { checkRendered, planFor } from './check.js';
 export { parseSource, links } from './source.js';
 export { diff, formatDiff } from './diff.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, altText, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const SUB_LINE = 15;
@@ -782,7 +782,11 @@ export function render(fig, opts = {}) {
             return `<g transform="translate(${n2(railX)} 0)">${parts.join('')}</g>`;
         })();
     const { font, ...t0 } = { ...LIGHT, ...fig.theme, ...opts.theme };
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}">
+    const alt = altText(fig);
+    const holdAt = beats[0]?.length ? n2(segs[beats[0].length - 1].t1 - 0.1) : 0;
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" font-family="${esc(font ?? SYSTEM_FONT)}" role="img">
+<title>${esc(alt.title)}</title>
+<desc>${esc(alt.desc)}</desc>
 <style>
 svg { ${vars(t0, '#eef5fd')} }
 @media (prefers-color-scheme: dark) { svg { ${vars(DARK, '#1d2733')} } }
@@ -806,6 +810,7 @@ svg { ${vars(t0, '#eef5fd')} }
 .railphase.muted { fill: var(--muted); }
 .end { text-anchor: end; }
 ${css.join('\n')}
+@media (prefers-reduced-motion: reduce) { * { animation-play-state: paused !important; animation-delay: -${holdAt}s !important; } }
 </style>
 <defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="context-stroke"/></marker></defs>
 <rect width="100%" height="100%" fill="var(--bg)"/>

package/dist/trace.d.ts

@@ -0,0 +1,30 @@
+import { type Read } from './code.ts';
+export type TraceEdge = {
+    from: string;
+    to: string;
+    at: string;
+};
+export type TraceNote = {
+    at: string;
+    reason: string;
+};
+export type TraceResult = {
+    start: string;
+    edges: TraceEdge[];
+    unsure: TraceNote[];
+    open: TraceNote[];
+    stops: {
+        reason: 'depth' | 'max';
+        count: number;
+    }[];
+    outside: number;
+    ms: number;
+};
+export type TraceOptions = {
+    root?: string;
+    depth?: number;
+    max?: number;
+    read?: Read;
+};
+export declare function trace(start: string, { root, depth, max, read }?: TraceOptions): TraceResult;
+export declare function traceLines(r: TraceResult, depth: number, max: number): string[];

package/dist/trace.js

@@ -0,0 +1,271 @@
+import { posix } from 'node:path';
+import { codeFile, definitions, depthAt, esc, langOf, locate, matchClose, pyBody, readFile } from './code.js';
+import { EDGE_LANGS, edgeResult, paramName, params, shadows } from './edges.js';
+import { OUTSIDE, importsOf, reexports } from './imports.js';
+import { ancestors, declIn, defines, findType, isUpper, makeCtx, receiver, receiverChain } from './types.js';
+import { goDirFiles } from './type-index.js';
+import { parseSource } from './source.js';
+const CALL = /(?<![\w$])([A-Za-z_$][\w$]*)\s*(?:<[^<>()]*>\s*)?\(/g;
+const REF = /[(,]\s*([A-Za-z_$][\w$]*)\s*(?=[,)])/g;
+const ROUTE = /\(\s*(['"`])\/[^'"`]*\1\s*,\s*(['"`])([A-Za-z_$][\w$]*(?:(?:\.|@|::|#)[A-Za-z_$][\w$]*)+)\2/g;
+const DEFAULT = /\bexport\s+default\s+(?:async\s+)?(?:function\s*\*?\s*|class\s+)?([A-Za-z_$][\w$]*)/;
+const KEYWORDS = new Set('if for while switch catch return typeof await function super sizeof using lock foreach elif assert yield throw not and or in with match when constructor'.split(' '));
+const innerParam = (body, n) => {
+    const N = `(?<![\\w$.])${esc(n)}(?![\\w$])`;
+    return new RegExp(`(?:\\([^()]*${N}[^()]*\\)|${N})\\s*(?::[^=)]+)?=>|\\bfunc(?:tion\\s*[\\w$]*)?\\s*\\((?:[^()]|\\([^()]*\\))*?${N}|\\blambda\\b[^:]*?${N}`).test(body);
+};
+const topLevel = (f, sym) => {
+    const s = locate(f, sym);
+    if (!s)
+        return false;
+    if (f.lang === 'go')
+        return depthAt(f.code, s.start, 0) === 0 && !/^func\s*\(/.test(f.code.slice(s.start, s.end));
+    return !/[ \t]/.test(f.code[f.code.lastIndexOf('\n', s.start - 1) + 1]);
+};
+const defined = (cx, from, to) => {
+    const [path, sym] = to.split('#');
+    const f = codeFile(cx.root, path, cx.read, cx.cache);
+    // A Java or C# constructor has the name of its type.
+    if (f.lang === 'java' || f.lang === 'cs')
+        return 1;
+    return definitions(f, sym) + (path === from ? 0 : reexports(cx.root, f, sym, cx.read).length);
+};
+const CONTROL = /^(?:if|for|while|switch|catch|with|foreach|else|match|elif|except|try)\b/;
+const enclosing = (f, pos) => {
+    const { code } = f;
+    const out = [];
+    if (f.lang === 'py') {
+        let ind = /^[ \t]*/.exec(code.slice(code.lastIndexOf('\n', pos - 1) + 1))[0].length;
+        for (let ls = code.lastIndexOf('\n', pos - 1); ls >= 0 && ind > 0; ls = code.lastIndexOf('\n', ls - 1)) {
+            const line = code.slice(ls + 1, code.indexOf('\n', ls + 1) < 0 ? undefined : code.indexOf('\n', ls + 1));
+            const w = /^[ \t]*/.exec(line)[0].length;
+            if (!line.trim() || w >= ind)
+                continue;
+            ind = w;
+            if (/^\s*(async\s+)?def\b/.test(line))
+                out.push(pyBody(code, ls + 1 + w));
+        }
+        return out;
+    }
+    if (f.lang === 'java' || f.lang === 'cs')
+        return out;
+    for (let i = pos, d = 0; i >= 0; i--) {
+        if (code[i] === '}')
+            d++;
+        else if (code[i] === '{' && d-- === 0) {
+            const head = code.slice(code.slice(0, i).search(/[;{}][^;{}]*$/) + 1, i).trim();
+            if (!CONTROL.test(head) && /(?:\)\s*(?::[^;{}]*)?|=>)$/.test(head))
+                out.push([i, matchClose(code, i)]);
+            d = 0;
+        }
+    }
+    return out;
+};
+const lineOf = (code, pos) => code.slice(0, pos).split('\n').length;
+function forward(cx, path, name, depth = 0) {
+    if (langOf(path) == null) {
+        const f = goDirFiles(cx, path).find((g) => topLevel(g, name));
+        return f ? { to: `${f.path}#${name}` } : null;
+    }
+    const f = codeFile(cx.root, path, cx.read, cx.cache);
+    if (!f)
+        return null;
+    const named = name === 'default' ? DEFAULT.exec(f.code)?.[1] : undefined;
+    if (named && locate(f, named))
+        return { to: `${path}#${named}` };
+    if (locate(f, name))
+        return { to: `${path}#${name}` };
+    if (depth >= 5)
+        return null;
+    let star = false;
+    for (const [p, inner] of reexports(cx.root, f, name, cx.read)) {
+        if (inner === '?')
+            star = true;
+        if (p == null || inner === '?')
+            continue;
+        const t = forward(cx, p, inner, depth + 1);
+        if (t)
+            return t;
+    }
+    return star ? { unsure: `star import: ${name}()` } : null;
+}
+function method(cx, d, name) {
+    for (const x of [d, ...ancestors(cx, d).flatMap((a) => (a.d ? [a.d] : []))]) {
+        const sym = `${x.name}.${name}`;
+        const files = x.info.lang === 'go' ? goDirFiles(cx, posix.dirname(x.info.path)) : [x.info];
+        const f = files.find((g) => locate(g, sym));
+        if (f)
+            return `${f.path}#${sym}`;
+    }
+    return null;
+}
+function resolve(cx, fi, body, n, rc, container, decl, imps) {
+    const gone = (p) => p == null || p === OUTSIDE;
+    if (!rc) {
+        const bind = imps.find((i) => i.local === n);
+        if (bind)
+            return gone(bind.path) ? 'outside' : bind.name === '*' ? null : forward(cx, bind.path, bind.name);
+        if (fi.lang === 'java' || fi.lang === 'cs') {
+            const m = decl && method(cx, decl, n);
+            if (m) {
+                const own = [decl, ...ancestors(cx, decl).flatMap((a) => (a.d ? [a.d] : []))].filter((x) => defines(cx, x, n));
+                return own.length > 1 ? { unsure: `${n} has two definitions` } : { to: m };
+            }
+        }
+        else if (topLevel(fi, n))
+            return { to: `${fi.path}#${n}` };
+        if (fi.lang === 'go') {
+            const f = goDirFiles(cx, posix.dirname(fi.path)).find((g) => topLevel(g, n));
+            if (f)
+                return { to: `${f.path}#${n}` };
+        }
+        if ((fi.lang === 'java' || fi.lang === 'cs' || fi.lang === 'rs') && isUpper(n)) {
+            const d = findType(cx, fi, n);
+            if (d)
+                return { to: `${d.info.path}#${d.name}` };
+        }
+        for (const i of imps.filter((x) => x.local === '*' || x.local === '.')) {
+            if (i.path == null)
+                return { unsure: `star import: ${n}()` };
+            const t = i.path === OUTSIDE ? null : forward(cx, i.path, n);
+            if (t)
+                return t;
+        }
+        return null;
+    }
+    if (rc.complex)
+        return null;
+    const head = imps.find((i) => i.local === rc.chain[0]);
+    if (head && gone(head.path))
+        return 'outside';
+    const rt = receiver(cx, fi, body, rc.chain, container, decl);
+    if (rt.name === '#external')
+        return 'outside';
+    if (rt.kind === 'module' && rt.mod)
+        return forward(cx, rt.mod, n);
+    if (rt.kind !== 'type' || rt.name === '#top')
+        return null;
+    const d = rt.decl ?? findType(cx, rt.ctx, rt.name, rt.qual);
+    const sym = d && method(cx, d, n);
+    return sym ? { to: sym } : null;
+}
+function candidates(body, own) {
+    const open = body.indexOf(own);
+    const sig = open >= 0 && /^\s*(?:<[^<>]*>\s*)?\(/.test(body.slice(open + own.length)) ? body.indexOf('(', open) : -1;
+    const from = sig < 0 ? 0 : matchClose(body, sig) + 1;
+    const out = [];
+    for (const m of body.matchAll(CALL)) {
+        const pre = body.slice(body.lastIndexOf('\n', m.index) + 1, m.index);
+        if (m.index < from || KEYWORDS.has(m[1]) || /^\s*@/.test(pre) || /\b(?:def|func|fn|function)\s+$/.test(pre))
+            continue;
+        out.push({ name: m[1], idx: m.index, call: true });
+    }
+    for (const m of body.matchAll(REF))
+        if (m.index >= from)
+            out.push({ name: m[1], idx: m.index + m[0].indexOf(m[1], 1), call: false });
+    return out.sort((a, b) => a.idx - b.idx);
+}
+function calls(cx, caller, r) {
+    const { path, symbol } = parseSource(caller);
+    const fi = codeFile(cx.root, path, cx.read, cx.cache);
+    const span = fi && locate(fi, symbol);
+    if (!fi || !span)
+        return [];
+    const body = fi.code.slice(span.start, span.end);
+    const parts = symbol.split('.');
+    const own = parts.at(-1);
+    const container = parts.length > 1 ? parts.at(-2) : null;
+    const decl = container ? (declIn(fi, container) ?? (fi.lang === 'go' ? findType(cx, fi, container) : null)) : null;
+    const imps = importsOf(cx.root, fi, cx.read);
+    const ps = new Set(params(body, own).map((p) => paramName(p, fi.lang)));
+    const at = (i) => `${path}:${lineOf(fi.code, span.start + i)}`;
+    for (const m of fi.keep.slice(span.start, span.end).matchAll(ROUTE))
+        r.open.push({ at: at(m.index), reason: `string route "${m[3]}"` });
+    const outer = enclosing(fi, span.start);
+    const targets = new Map();
+    for (const c of candidates(body, own)) {
+        const rc = receiverChain(body, c.idx, fi.lang);
+        if (c.call && !rc && ps.has(c.name)) {
+            r.unsure.push({ at: at(c.idx), reason: `parameter call: ${c.name}()` });
+            continue;
+        }
+        if (!rc && (shadows(body, c.name, fi.lang, own, false) || innerParam(body, c.name)))
+            continue;
+        const twice = { unsure: `${c.name} has two definitions` };
+        const t = !rc &&
+            [[span.start, span.end], ...outer].some(([a, b]) => definitions(fi, c.name, a, b) > (c.name === own ? 1 : 0))
+            ? twice
+            : resolve(cx, fi, body, c.name, rc, container, decl, imps);
+        if (t === 'outside')
+            r.outside += c.call ? 1 : 0;
+        else if (t && 'unsure' in t)
+            r.unsure.push({ at: at(c.idx), reason: t.unsure });
+        else if (t && !rc && defined(cx, path, t.to) > 1)
+            r.unsure.push({ at: at(c.idx), reason: twice.unsure });
+        else if (t && t.to !== caller && !targets.has(t.to))
+            targets.set(t.to, at(c.idx));
+    }
+    const found = [];
+    for (const [to, where] of targets) {
+        const { result, reason } = edgeResult(cx.root, caller, to, undefined, cx.read, cx.cache);
+        if (result === 'found')
+            found.push({ from: caller, to, at: where });
+        else if (result === 'unsure')
+            r.unsure.push({ at: where, reason });
+        else if (result === 'not-checked')
+            r.open.push({ at: where, reason });
+    }
+    return found;
+}
+export function trace(start, { root = process.cwd(), depth = 2, max = 40, read = readFile } = {}) {
+    const t0 = performance.now();
+    const src = parseSource(start);
+    if (!src?.symbol)
+        throw new Error(`${start}: expected file#symbol`);
+    const lang = langOf(src.path);
+    if (!lang || !EDGE_LANGS.has(lang))
+        throw new Error(`${src.path}: trace does not read this language`);
+    const cache = new Map();
+    const fi = codeFile(root, src.path, read, cache);
+    if (!fi)
+        throw new Error(`${src.path}: file not found`);
+    if (!locate(fi, src.symbol))
+        throw new Error(`${start}: symbol not defined`);
+    const cx = makeCtx(root, read, cache);
+    const r = { start, edges: [], unsure: [], open: [], stops: [], outside: 0, ms: 0 };
+    const seen = new Set([start]);
+    let level = [start];
+    for (let d = 0; d < depth && level.length; d++) {
+        const next = [];
+        for (const [k, caller] of level.entries())
+            for (const e of calls(cx, caller, r)) {
+                r.edges.push(e);
+                if (!seen.has(e.to))
+                    next.push(e.to);
+                seen.add(e.to);
+                if (r.edges.length >= max) {
+                    r.stops.push({ reason: 'max', count: level.length - k - 1 + next.length });
+                    r.ms = Math.round(performance.now() - t0);
+                    return r;
+                }
+            }
+        level = next;
+    }
+    if (level.length)
+        r.stops.push({ reason: 'depth', count: level.length });
+    r.ms = Math.round(performance.now() - t0);
+    return r;
+}
+const count = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
+export function traceLines(r, depth, max) {
+    const pairs = r.edges.map((e) => `${e.from} -> ${e.to}`);
+    const width = Math.max(0, ...pairs.map((p) => p.length));
+    const symbols = new Set([r.start, ...r.edges.map((e) => e.to)]).size;
+    return [
+        ...r.edges.map((e, i) => `${pairs[i].padEnd(width)}   ${e.at}`),
+        ...r.unsure.map((u) => `unsure  ${u.at}  ${u.reason}`),
+        ...r.open.map((o) => `open    ${o.at}  ${o.reason}`),
+        ...r.stops.map((s) => `stop    ${s.reason} ${s.reason === 'depth' ? depth : max}: ${count(s.count, 'symbol')} not followed`),
+        `summary: ${count(symbols, 'symbol')}, ${r.edges.length} found, ${r.unsure.length} unsure, ${r.open.length} open, ${count(r.outside, 'call')} outside the repo, ${(r.ms / 1000).toFixed(1)} s`,
+    ];
+}

package/dist/verify.d.ts

@@ -1,6 +1,6 @@
 import { type FlowProps } from './model.ts';
 import type { Finding } from './scene.ts';
-import { type Read } from './code.ts';
+import { type CodeFile, type Read } from './code.ts';
 export { parseSource, headingSlug, owners, links, type Link } from './source.ts';
 export type Coverage = {
     boxes: number;
@@ -17,9 +17,10 @@ export type Coverage = {
 export declare const coverageLine: (figure: string, c: Coverage) => string;
 export declare const unsureLines: (c: Coverage) => string[];
 /** The links against the files under `root`. A path outside `root` counts as a missing file. */
-export declare function verifyReport(fig: FlowProps, { root, read }?: {
+export declare function verifyReport(fig: FlowProps, { root, read, cache, }?: {
     root?: string;
     read?: Read;
+    cache?: Map<string, CodeFile | null>;
 }): {
     findings: Finding[];
     coverage: Coverage;

package/dist/verify.js

@@ -16,7 +16,7 @@ export const coverageLine = (figure, c) => `${figure}: ${c.boxesDefined} of ${c.
         : '');
 export const unsureLines = (c) => c.unsureEdges.map((e) => `unsure   edge "${e.id}": ${e.reason}`);
 /** The links against the files under `root`. A path outside `root` counts as a missing file. */
-export function verifyReport(fig, { root = process.cwd(), read = readFile } = {}) {
+export function verifyReport(fig, { root = process.cwd(), read = readFile, cache = new Map(), } = {}) {
     const findings = [];
     const coverage = emptyCoverage();
     const all = links(fig);
@@ -26,7 +26,6 @@ export function verifyReport(fig, { root = process.cwd(), read = readFile } = {}
             coverage,
         };
     const files = new Map();
-    const parsed = new Map();
     for (const l of all) {
         const full = resolve(root, l.path);
         if (!files.has(full))
@@ -37,7 +36,7 @@ export function verifyReport(fig, { root = process.cwd(), read = readFile } = {}
         if (text == null)
             fail('missing-file', 'file not found');
         else if (l.symbol) {
-            const code = codeFile(root, l.path, read, parsed);
+            const code = codeFile(root, l.path, read, cache);
             if (code) {
                 if (!isDefined(code, l.symbol))
                     fail('missing-symbol', 'symbol not defined');
@@ -54,7 +53,7 @@ export function verifyReport(fig, { root = process.cwd(), read = readFile } = {}
     }
     const source = new Map(nodes(fig.layout).map((n) => [n.id, n.source]));
     const check = (who, id, caller, callee, via) => {
-        const { result, reason } = caller ? edgeResult(root, caller, callee, via, read, parsed) : { result: 'not-checked', reason: '' };
+        const { result, reason } = caller ? edgeResult(root, caller, callee, via, read, cache) : { result: 'not-checked', reason: '' };
         if (result === 'found')
             coverage.found++;
         else if (result === 'not-found') {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.8.3";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The release list bumps this with package.json.
-export const VERSION = '0.8.3';
+export const VERSION = '0.9.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks each box and arrow against that code. CI fails when a diagram drifts from the code. The output is one animated SVG with no script, for a README, PR or issue. Works with Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro.",
   "license": "MIT",
   "repository": {