flowfig 0.7.0 → 0.8.0

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.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -252,7 +254,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
 ```
 
@@ -431,6 +433,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 +469,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.7.0
+      - uses: iamalvisng/flowfig@v0.8.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -523,7 +542,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.
 

package/dist/check.js

@@ -44,9 +44,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;

package/dist/cli.js

@@ -25,7 +25,7 @@ import { diff, formatDiff } from './diff.js';
 import { loadSpec, reportLines, sortFindings, specOf, svgWithSpec } 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
@@ -120,20 +120,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);
 }

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 {};