flowfig 0.6.0 → 0.8.0

package/dist/cli.js

@@ -7,29 +7,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-/**
- * Render a figure as one animated SVG — for a README, a PR, an issue, a blog post — and check it first.
- *
- *   flowfig - out.svg < spec.json        # a spec on stdin: nothing is left on disk
- *   flowfig spec.json out.svg            # a spec file
- *   flowfig figure.ts out.svg            # a module whose default export is a spec
- *   flowfig --spec out.svg               # print back the spec the SVG carries
- *   flowfig check <input> [--json]       # list the faults; the input can also be an SVG this wrote
- *   flowfig verify <input>... [--root dir]   # check that the code each figure links to still exists
- *   flowfig diff <old> <new> [--json|--md]   # list the spec changes between two figures
- *   flowfig docs                         # print the full guide (Markdown)
- *   flowfig mcp                          # serve check, render, verify, diff and docs over MCP (stdio)
- *   flowfig init [dir]                   # write flowfig instructions for the coding agents of a repo
- *   flowfig draw "<question>" [--out out.svg]   # ask Claude Code for a figure, then check it
- *   flowfig open figure.svg              # show the figure in the default browser
- *   flowfig gif figure.svg [out.gif]     # write an animated GIF of the figure (needs Chrome, Edge, Chromium or Brave)
- *
- * A render checks first and writes nothing on an error (--no-check skips that). --strict makes warnings errors; --width and
- * --min-text set the page width and the smallest text the reader should get.
- * --open opens the rendered SVG in the default browser (render and draw).
- *
- * Every rendered SVG carries its own spec in <metadata>, so a figure is editable later without anyone having to keep the JSON.
- */
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -46,8 +23,9 @@ 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 { check, toSvg } from './svg.js';
-import { links, verify } from './verify.js';
+import { check, render, toSvg } from './svg.js';
+import { checkRendered } from './check.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
@@ -60,7 +38,6 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   rende
        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)`;
-/** Bad use, not a bad figure: exit 2 with a message, not a stack trace. A declaration, so TypeScript narrows after a call. */
 function usage(message) {
     console.error(message);
     process.exit(2);
@@ -90,7 +67,7 @@ if (args[0] === 'docs') {
 }
 if (args[0] === 'mcp') {
     await serve(process.stdin, process.stdout);
-    // A pipe write is asynchronous: wait until the queued response lines are out before the exit.
+    // A pipe write is asynchronous: wait for the queued lines before the exit.
     await new Promise((done) => process.stdout.write('', () => done(undefined)));
     process.exit(0);
 }
@@ -118,7 +95,6 @@ if (args[0] === '--spec') {
     }
     process.exit(0);
 }
-/** A spec from stdin, a JSON file, an SVG this wrote, or a module. Exit 2 with a message on any failure. */
 async function load(input) {
     try {
         if (input.endsWith('.json') || input.endsWith('.svg'))
@@ -144,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);
 }
@@ -195,7 +179,6 @@ if (args[0] === 'gif') {
         usage(`${path}: ${e.message}`);
     }
     if (step !== undefined) {
-        // One step only: render the spec again with that step, so the loop holds that step alone.
         const props = (() => {
             try {
                 return loadSpec(path);
@@ -222,24 +205,22 @@ if (args[0] === 'gif') {
         usage(['gif needs Chrome, Edge, Chromium or Brave. Checked:', ...found.checked, 'Set CHROME_PATH to the browser program.'].join('\n'));
     const line = (file, frames, bytes) => `${file} — ${frames} frame${frames === 1 ? '' : 's'}, ${(frames / fps).toFixed(1)} s, ${(bytes / 1048576).toFixed(1)} MB`;
     const temp = mkdtempSync(join(tmpdir(), 'flowfig-gif-'));
-    // A Ctrl-C can come while the browser starts, so cleanup waits for the start before it stops the browser.
     let launching;
     let cleaning;
     const cleanup = () => (cleaning ??= (async () => {
         await (await launching?.catch(() => undefined))?.close();
         try {
-            // The retries cover Windows, where the browser can hold a file lock for a short time after the exit.
+            // Windows can hold a file lock briefly after the exit, so retry.
             rmSync(temp, { recursive: true, force: true, maxRetries: 10 });
         }
         catch (e) {
             console.error(`warning: could not remove ${temp}: ${e.message}`);
         }
     })());
-    // The output files of this run: a stop removes them, so no partial file stays.
     const written = [];
     let ffmpeg, ffmpegDone = Promise.resolve(), stopped = 0;
     const yieldLoop = () => new Promise((done) => setImmediate(done));
-    // The handlers stay for the whole run: a second signal during the cleanup must not end the process before the cleanup ends.
+    // Keep the handlers: a second signal must not end the process mid-cleanup.
     const onSignal = (signal) => {
         if (stopped)
             return;
@@ -252,7 +233,7 @@ if (args[0] === 'gif') {
     };
     process.on('SIGINT', onSignal);
     process.on('SIGTERM', onSignal);
-    // The encode and the ffmpeg run give the event loop a turn, so a signal handler can run. A write comes straight after this check.
+    // A write comes right after this check, so a signal must run its handler first.
     const proceed = async () => {
         await yieldLoop();
         if (stopped)
@@ -265,7 +246,7 @@ if (args[0] === 'gif') {
         const viewport = { width: Math.ceil(Number(size[1])), height: Math.ceil(Number(size[2])) };
         const { pngs } = await captureFrames(browser.cdp, pageHtml(svg, basename(path)), { ...viewport, scale, fps, dark });
         const wait = delays(pngs.length, fps);
-        // The GIF keeps the PNG bytes, not the pixels: a decoded 2400 x 1600 frame is 15 MB.
+        // The GIF keeps the PNG bytes: a decoded 2400 x 1600 frame is 15 MB.
         const gif = await encodeGif(pngs.map((png, i) => ({ load: () => decodePng(png), delay: wait[i], same: i > 0 && png.equals(pngs[i - 1]) })));
         await proceed();
         written.push(out);
@@ -275,21 +256,37 @@ if (args[0] === 'gif') {
             console.error(`warning: ${out} is ${(gif.length / 1048576).toFixed(1)} MB, over 10 MB. Try --step <n>, a lower --fps or a lower --scale.`);
         if (mp4) {
             const mp4Path = out.replace(/(\.gif)?$/, '.mp4');
-            // FLOWFIG_FFMPEG replaces the PATH lookup, so a test can hide ffmpeg and keep the full PATH.
             const ffmpegBin = process.env.FLOWFIG_FFMPEG ?? 'ffmpeg';
             if (spawnSync(ffmpegBin, ['-version']).error)
                 console.error('gif: no ffmpeg on the PATH, so no MP4. The GIF is written.');
             else {
                 await proceed();
                 written.push(mp4Path);
-                // yuv420p needs an even width and height, so the pad filter adds a pixel where needed.
+                // yuv420p needs an even width and height, so the pad filter adds a pixel.
                 ffmpeg = spawn(ffmpegBin, [
-                    ...['-y', '-loglevel', 'error', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-'],
-                    ...['-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', mp4Path],
+                    '-y',
+                    '-loglevel',
+                    'error',
+                    '-f',
+                    'image2pipe',
+                    '-framerate',
+                    String(fps),
+                    '-c:v',
+                    'png',
+                    '-i',
+                    '-',
+                    '-vf',
+                    'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+                    '-c:v',
+                    'libx264',
+                    '-pix_fmt',
+                    'yuv420p',
+                    mp4Path,
                 ]);
                 let stderr = '';
                 ffmpeg.stderr.on('data', (d) => (stderr += d));
-                ffmpeg.stdin.on('error', () => { }); // ffmpeg can exit before it reads all the input; the exit code reports that
+                // ffmpeg can exit early; the exit code reports that.
+                ffmpeg.stdin.on('error', () => { });
                 ffmpeg.stdin.end(Buffer.concat(pngs));
                 const status = await (ffmpegDone = new Promise((done) => {
                     ffmpeg.once('error', () => done(-1));
@@ -312,7 +309,7 @@ if (args[0] === 'gif') {
     finally {
         await cleanup();
     }
-    // A signal that came in the last turn runs its handler here, before the exit.
+    // A late signal runs its handler in this await, before the exit.
     await yieldLoop();
     if (stopped)
         written.forEach((f) => rmSync(f, { force: true }));
@@ -330,12 +327,10 @@ const [input, out] = args;
 if (!input)
     usage(USAGE);
 const props = await load(input);
-const findings = skip ? [] : sortFindings(check(props, opts), strict);
+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;
-/** The findings for a person: one line each, colored only on a terminal, then the counts. A render prints them to stderr, next to
- * its own output. A clean render still prints `0 errors, 0 warnings`: the agent copies that line into its reply. */
 const report = (print, tty) => {
-    // The severity field is 8 characters wide, so the painted field keeps the same width.
     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))
         print(paint(line));
@@ -351,8 +346,7 @@ report(console.error, process.stderr.isTTY);
 if (errors)
     process.exit(1);
 const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
-// The spec rides along in <metadata>: an SVG is then its own source, and no JSON has to be kept.
-const withSpec = svgWithSpec(props, opts);
+const withSpec = svgWithSpec(props, opts, rendered?.svg);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);
 if (open) {

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