@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/agents/skills/orkestrel-harden/scripts/titles.js

@@ -1,27 +1,169 @@
 // Run from the checkout root:
 //   node .agents/skills/orkestrel-harden/scripts/titles.ts --base REV [--root DIR] [--json] [--out FILE]
-// Compare exact decoded describe/it/test title counts in tests/**/*.test.ts against REV. Report
-// deficits with their baseline files, or as moved when another tests/**/*.ts string literal holds
-// the title. Confirm moved registrations by reading their holder. Decode quote and backslash
-// escapes only. Balance each-table parentheses over code tokens, skipping lexical regions.
-// Print text by default or one JSON line with --json; --out writes .json or .txt independently.
-// Compare interpolated templates by full raw spelling. Refuse unclosed lexical tokens.
+// Each value is a separate argument: `--flag=value` and any flag the script does not read exit 64,
+// and so does a REV that opens with `-`. The baseline is read from the tree REV names, resolved
+// once with `--end-of-options`, with paths relative to --root, so a --root below the repository top
+// works.
+// Compare exact decoded describe/it/test/suite title counts in tests/**/*.test.ts against REV. A
+// baseline title with a deficit is moved when another tests/**/*.ts string literal spells it, and
+// missing otherwise. A moved row is a claim to rule, not proof: a literal that only spells the
+// title (an assertion value, a data table) also holds it, so the reader rules each moved row by
+// reading its holder, as it rules each missing row. Read a registration at any token position, with
+// its modifiers: `.each` tables (call or tagged template) and `.skipIf(...)` and `.runIf(...)` read
+// the title of the call that follows. A title that is no string or template literal is a dynamic
+// row, named per tree with its source spelling: the comparison cannot follow it, and a removed
+// `.each` table row leaves its one registered title in place. A file with fewer dynamic
+// registrations than at REV is a lost-dynamic row, which the comparison cannot rule on, so it
+// exits 3 as a missing row does. A title registered through an alias (a `test.extend` result bound
+// to another name, or `const spec = it`) is not read, and a `test.extend({...})` call itself reads
+// as one dynamic registration. Decode quote and backslash escapes only.
+// Balance each-table parentheses over code tokens, skipping lexical regions. Print text by default
+// or one JSON line with --json; --out writes .json or .txt independently. Text rows escape tab and
+// newline. Compare interpolated templates by full raw spelling. Refuse unclosed lexical tokens.
 // Track lexical brace context without a syntax tree. Function-expression and arrow bodies cannot
 // establish a following slash's grammar; refuse that detectable ambiguity instead of claiming a move.
-// Exit 0 with no missing titles, 3 with missing titles, 2 on git, filesystem or token refusal, 64 on usage.
+// Only .test.ts files register titles; a .test.tsx or .test.mts file is invisible to it.
+// Exit 0 with no missing or moved titles and no lost-dynamic file, 3 with any, 2 on git, filesystem
+// or token refusal, 64 on usage.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, extname, join, relative, resolve } from 'node:path';
-import { listFiles, normalizeSlashes, readMissingFlags, readOption, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const TITLE_PATTERN = /^\s*(?:it|test|describe)(?:\.\w+)*\(/gmu;
-const REGEX_PREFIX = /^(?:return|throw|case|delete|void|typeof|instanceof|in|of|yield|await|else|do)$/u;
-function decodeTitle(text, token) {
+/** Lists the flags this script reads, value flags and switches alike. */
+export const FLAGS = ['--base', '--root', '--json', '--out'];
+/** Holds the usage line printed on a usage refusal. */
+export const USAGE = 'usage: titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]';
+/** Caps the characters of a name an error message echoes. */
+export const NAME_LIMIT = 80;
+/** Names the directories a tree walk skips, so build output and notes stay unread. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/** Matches the keywords after which a slash opens a regular expression. */
+export const REGEX_PREFIX = /^(?:return|throw|case|delete|void|typeof|instanceof|in|of|yield|await|else|do)$/u;
+/** Matches an identifier as one word. */
+export const IDENTIFIER_PATTERN = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
+/** Names the identifiers that open a test registration. */
+export const REGISTRARS = new Set(['it', 'test', 'describe', 'suite']);
+/** Names the calls whose argument list or table precedes the registration call. */
+export const ARGUMENT_MODIFIERS = new Set(['each', 'skipIf', 'runIf', 'for']);
+/** Lists the tokens that open a bracket group. */
+export const OPENERS = ['(', '[', '{'];
+/** Lists the tokens that close a bracket group. */
+export const CLOSERS = [')', ']', '}'];
+/**
+ * Normalizes a host path to forward slashes.
+ *
+ * @param path - A host path.
+ * @returns The same path with every backslash replaced by a slash.
+ */
+export function normalizeSlashes(path) {
+    return path.split('\\').join('/');
+}
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
+ * and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--base`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
+ * reads `--flag value` pairs only.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Lists every regular file beneath a directory, skipping the named directories at any depth.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: {@link SKIPPED_DIRECTORIES}.
+ * @returns Each file's forward-slash path and modification time, in walk order.
+ * @throws Thrown when `directory` does not exist or cannot be read; check `existsSync` first.
+ */
+export function listFiles(directory, skipped = SKIPPED_DIRECTORIES) {
+    const files = [];
+    const pending = [directory];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (skipped.has(entry.name))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (entry.isFile()) {
+                files.push({ path: normalizeSlashes(path), modified: statSync(path).mtimeMs });
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Describes a name for an error message, JSON-encoded and length-capped.
+ *
+ * @param name - The untrusted name to echo.
+ * @returns The encoded name, cut where it exceeds the cap.
+ */
+export function describeName(name) {
+    return JSON.stringify(name.length > NAME_LIMIT ? `${name.slice(0, NAME_LIMIT)}…` : name);
+}
+/**
+ * Decodes the title a string or template token spells.
+ *
+ * @param text - The source text.
+ * @param token - A string or template token.
+ * @returns The raw spelling of an interpolated template, otherwise the text with quote and
+ * backslash escapes decoded.
+ */
+export function decodeTitle(text, token) {
     const raw = text.slice(token.start + 1, token.end - 1);
     return token.category === 'template' && token.children.length > 0
         ? raw
         : raw.replace(/\\(['"`\\])/gu, '$1');
 }
-class TokenScanner {
+/**
+ * Scans JavaScript or TypeScript source into lexical tokens without a syntax tree.
+ *
+ * @remarks
+ * Keeps its position and its brace and parenthesis context in `#` fields, one scanner per scan.
+ */
+export class TokenScanner {
     #text;
     #file;
     #parentheses = [];
@@ -159,14 +301,14 @@ class TokenScanner {
                 return { category: 'template', start, end: this.#position, children };
             }
             else if (this.#text.startsWith('${', this.#position)) {
-                const opening = this.#position;
+                const offset = this.#position;
                 this.#position += 2;
                 this.#braces.push({ category: 'template', ambiguous: false });
                 const expression = this.#readCode(true, depth);
                 this.#braces.pop();
                 children.push({
                     category: 'code',
-                    start: opening,
+                    start: offset,
                     end: this.#position,
                     children: expression,
                 });
@@ -178,62 +320,240 @@ class TokenScanner {
         throw new Error(`${this.#file}:${start}: Unclosed template token`);
     }
 }
-function readArguments(text, tokens, location, depth) {
-    if (depth > 256)
-        throw new Error(`${location}: each argument nesting exceeds 256`);
-    for (const token of tokens) {
-        if (token.category !== 'code')
-            continue;
-        const spelling = text.slice(token.start, token.end);
-        if (spelling === '(')
-            readArguments(text, tokens, location, depth + 1);
-        else if (spelling === ')')
-            return token.end;
+/**
+ * Reads the source text a token spans.
+ *
+ * @param text - The source text.
+ * @param token - The token.
+ * @returns The token's spelling.
+ */
+export function spell(text, token) {
+    return text.slice(token.start, token.end);
+}
+/**
+ * Checks whether a token is a comment or whitespace.
+ *
+ * @param text - The source text.
+ * @param token - The token.
+ * @returns True if the token carries no code.
+ */
+export function isTrivia(text, token) {
+    return (token.category === 'line' ||
+        token.category === 'block' ||
+        (token.category === 'code' && spell(text, token).trim() === ''));
+}
+/**
+ * Reads the line number of a token's start.
+ *
+ * @param text - The source text.
+ * @param token - The token, or undefined for the start of the text.
+ * @returns The one-based line number.
+ */
+export function readLine(text, token) {
+    return text.slice(0, token?.start ?? 0).split(/\r\n|\n/u).length;
+}
+/**
+ * Finds the parenthesis that closes a modifier's argument group.
+ *
+ * @param text - The source text.
+ * @param code - The code tokens, without comments and whitespace.
+ * @param open - The index of the opening parenthesis.
+ * @param name - The modifier name, for the refusal.
+ * @param file - The file label, for the refusal.
+ * @returns The index of the matching closing parenthesis.
+ * @throws Thrown when the group never closes.
+ */
+export function findGroupEnd(text, code, open, name, file) {
+    const found = code.slice(open).reduce((state, token, offset) => {
+        if (state.end >= 0 || token.category !== 'code')
+            return state;
+        const word = spell(text, token);
+        const depth = state.depth + (word === '(' ? 1 : word === ')' ? -1 : 0);
+        return { depth, end: word === ')' && depth === 0 ? open + offset : -1 };
+    }, { depth: 0, end: -1 });
+    if (found.end < 0) {
+        throw new Error(`${file}:${readLine(text, code[open])}: Unbalanced ${name} arguments`);
     }
-    throw new Error(`${location}: Unbalanced each arguments`);
+    return found.end;
 }
-function readRegistrations(text, tokens, file) {
-    const code = tokens
-        .map((token) => {
-        const raw = text.slice(token.start, token.end);
-        if (token.category === 'code')
-            return raw;
-        const blank = raw
-            .split('')
-            .map((character) => (/[\r\n]/u.test(character) ? character : ' '))
-            .join('');
-        return token.category === 'string' || token.category === 'template'
-            ? `\0${blank.slice(1)}`
-            : blank;
-    })
-        .join('');
-    const offset = tokens[0]?.start ?? 0;
-    const positions = new Map(tokens.map((token, index) => [token.start, index]));
-    const starts = new Set(Array.from(code.matchAll(TITLE_PATTERN)).flatMap((match) => {
-        const opening = offset + match.index + match[0].length - 1;
-        const direct = /^\s*\0/u.exec(code.slice(opening + 1 - offset));
-        if (!/\.each\(/u.test(match[0]) && direct !== null)
-            return [opening + direct[0].length];
-        const index = positions.get(opening);
-        if (index === undefined)
-            return [];
-        const line = text.slice(0, opening).split(/\r\n|\n/u).length;
-        const end = readArguments(text, tokens.slice(index + 1).values(), `${file}:${line}`, 0);
-        const title = /^\s*\(\s*\0/u.exec(code.slice(end - offset));
-        return title === null ? [] : [end + title[0].length - 1];
-    }));
+/**
+ * Finds where a registration call's first argument ends.
+ *
+ * @param text - The source text.
+ * @param code - The code tokens, without comments and whitespace.
+ * @param from - The index of the first argument's first token.
+ * @param file - The file label, for the refusal.
+ * @returns The index of the first top-level comma or closing parenthesis.
+ * @throws Thrown when the call never closes.
+ */
+export function findArgumentEnd(text, code, from, file) {
+    const found = code.slice(from).reduce((state, token, offset) => {
+        if (state.end >= 0 || token.category !== 'code')
+            return state;
+        const word = spell(text, token);
+        if (state.depth === 0 && (word === ',' || word === ')')) {
+            return { depth: 0, end: from + offset };
+        }
+        return {
+            depth: state.depth + (OPENERS.includes(word) ? 1 : CLOSERS.includes(word) ? -1 : 0),
+            end: -1,
+        };
+    }, { depth: 0, end: -1 });
+    if (found.end < 0) {
+        throw new Error(`${file}:${readLine(text, code[from - 1])}: Unbalanced call arguments`);
+    }
+    return found.end;
+}
+/**
+ * Reads the modifier chain after a registrar, up to its registration call.
+ *
+ * @remarks
+ * `.each` and its tagged-template form, `.skipIf(...)`, `.runIf(...)`, and `.for(...)` are followed
+ * by a second call that registers the title, so the first group or template is skipped.
+ *
+ * @param text - The source text.
+ * @param code - The code tokens, without comments and whitespace.
+ * @param at - The index after the registrar or the last chain element.
+ * @param last - The last modifier name read; empty after a skipped group or at the start.
+ * @param file - The file label, for a refusal.
+ * @returns The index of the registration call's opening parenthesis, or -1 when the tokens are no
+ * registration call.
+ */
+export function readCall(text, code, at, last, file) {
+    const token = code[at];
+    if (token === undefined)
+        return -1;
+    const word = token.category === 'code' ? spell(text, token) : '';
+    if (word === '.') {
+        const name = code[at + 1];
+        const spelled = name?.category === 'code' ? spell(text, name) : '';
+        return IDENTIFIER_PATTERN.test(spelled) ? readCall(text, code, at + 2, spelled, file) : -1;
+    }
+    if (token.category === 'template' && ARGUMENT_MODIFIERS.has(last)) {
+        return readCall(text, code, at + 1, '', file);
+    }
+    if (word !== '(')
+        return -1;
+    if (!ARGUMENT_MODIFIERS.has(last))
+        return at;
+    return readCall(text, code, findGroupEnd(text, code, at, last, file) + 1, '', file);
+}
+/**
+ * Checks whether the code token at an index opens a test registration.
+ *
+ * @param text - The source text.
+ * @param code - The code tokens, without comments and whitespace.
+ * @param index - The token index.
+ * @returns True if the token is a registrar word that no member access precedes.
+ */
+export function isRegistrar(text, code, index) {
+    const token = code[index];
+    if (token?.category !== 'code' || !REGISTRARS.has(spell(text, token)))
+        return false;
+    const previous = code[index - 1];
+    return !(previous?.category === 'code' && spell(text, previous) === '.');
+}
+/**
+ * Reads the registration a registrar token starts.
+ *
+ * @param text - The source text.
+ * @param code - The code tokens, without comments and whitespace.
+ * @param index - The registrar's index.
+ * @param file - The file label, for a refusal.
+ * @returns One registration, or none when the registrar starts no call.
+ */
+export function readRegistration(text, code, index, file) {
+    const call = readCall(text, code, index + 1, '', file);
+    if (call < 0)
+        return [];
+    const first = code.slice(call + 1, findArgumentEnd(text, code, call + 1, file));
+    const only = first.length === 1 ? first[0] : undefined;
+    if (only !== undefined && (only.category === 'string' || only.category === 'template')) {
+        return [{ token: only, spelling: spell(text, only) }];
+    }
+    const head = first[0];
+    const tail = first.at(-1);
     return [
-        ...tokens.filter((token) => starts.has(token.start)),
-        ...tokens.flatMap((token) => readRegistrations(text, token.children, file)),
+        {
+            token: undefined,
+            spelling: head === undefined || tail === undefined
+                ? ''
+                : text.slice(head.start, tail.end).replace(/\s+/gu, ' '),
+        },
     ];
 }
-function collectLiterals(tokens) {
+/**
+ * Reads every test registration in a token list and in the template expressions nested in it.
+ *
+ * @param text - The source text.
+ * @param tokens - The scanned tokens.
+ * @param file - The file label, for a refusal.
+ * @returns The registrations in token order, then those nested in template expressions.
+ */
+export function readRegistrations(text, tokens, file) {
+    const code = tokens.filter((token) => !isTrivia(text, token));
+    const here = code.flatMap((_token, index) => isRegistrar(text, code, index) ? readRegistration(text, code, index, file) : []);
+    return [...here, ...tokens.flatMap((token) => readRegistrations(text, token.children, file))];
+}
+/**
+ * Collects the string and template tokens of a token tree.
+ *
+ * @param tokens - The scanned tokens.
+ * @returns Every string or template token, nested ones included.
+ */
+export function collectLiterals(tokens) {
     return tokens.flatMap((token) => [
         ...(token.category === 'string' || token.category === 'template' ? [token] : []),
         ...collectLiterals(token.children),
     ]);
 }
-function readGit(root, args) {
+/**
+ * Lists the registrations of a tree that have no literal title.
+ *
+ * @param file - The file the registrations came from.
+ * @param registrations - The file's registrations.
+ * @param tree - The tree the file was read from.
+ * @returns One dynamic row per registration without a title token.
+ */
+export function readDynamic(file, registrations, tree) {
+    return registrations
+        .filter((registration) => registration.token === undefined)
+        .map((registration) => ({ file, spelling: registration.spelling, tree }));
+}
+/**
+ * Counts the registrations that have no literal title.
+ *
+ * @param registrations - A file's registrations.
+ * @returns How many have no title token.
+ */
+export function countDynamic(registrations) {
+    return registrations.filter((registration) => registration.token === undefined).length;
+}
+/**
+ * Lists the files that register fewer non-literal titles than the baseline did.
+ *
+ * @param baseline - Each baseline test file with its registrations.
+ * @param current - Each working test file with its registrations.
+ * @returns One row per baseline file whose count of non-literal registrations dropped, with the
+ * drop; a file absent from the working tree counts none.
+ */
+export function readLostDynamic(baseline, current) {
+    return baseline.flatMap(({ file, registrations }) => {
+        const before = countDynamic(registrations);
+        const now = current.find((entry) => entry.file === file);
+        const after = now === undefined ? 0 : countDynamic(now.registrations);
+        return before > after ? [{ file, deficit: before - after }] : [];
+    });
+}
+/**
+ * Runs git in a directory and returns its output.
+ *
+ * @param root - The directory to run in.
+ * @param args - The git arguments.
+ * @returns The standard output.
+ * @throws Thrown when git cannot run or exits nonzero.
+ */
+export function readGit(root, args) {
     const result = spawnSync('git', ['-C', root, ...args], {
         encoding: 'utf8',
         windowsHide: true,
@@ -244,17 +564,29 @@ function readGit(root, args) {
     }
     return result.stdout;
 }
-function readReport(base, root) {
-    const baseline = readGit(root, ['ls-tree', '-r', '-z', '--name-only', base, '--', 'tests'])
+/**
+ * Compares the titles of the working tree with the baseline revision.
+ *
+ * @param base - The revision to compare against.
+ * @param root - The directory whose `tests/` tree is compared; it may sit below the repository top.
+ * @returns The missing, moved, and dynamic rows with the baseline title count.
+ * @throws Thrown when git refuses, a file cannot be read, or a token cannot be classified.
+ */
+export function readReport(base, root) {
+    const tree = readGit(root, ['rev-parse', '--verify', '--end-of-options', `${base}^{tree}`]).trim();
+    const baselineFiles = readGit(root, ['ls-tree', '-r', '-z', '--name-only', tree, '--', 'tests'])
         .split('\0')
         .filter((file) => file.endsWith('.test.ts'))
-        .flatMap((file) => {
-        const text = readGit(root, ['show', `${base}:${file}`]);
-        return readRegistrations(text, new TokenScanner(text, `${base}:${file}`).scan(), `${base}:${file}`).map((token) => ({
+        .map((file) => {
+        const text = readGit(root, ['show', `${tree}:./${file}`]);
+        const label = `${base}:${file}`;
+        return {
             file,
-            title: decodeTitle(text, token),
-        }));
+            text,
+            registrations: readRegistrations(text, new TokenScanner(text, label).scan(), label),
+        };
     });
+    const baseline = baselineFiles.flatMap(({ file, text, registrations }) => registrations.flatMap(({ token }) => token === undefined ? [] : [{ file, title: decodeTitle(text, token) }]));
     const directory = join(root, 'tests');
     const files = (existsSync(directory) ? listFiles(directory) : [])
         .filter(({ path }) => path.endsWith('.ts'))
@@ -272,11 +604,14 @@ function readReport(base, root) {
         .sort((left, right) => left.file.localeCompare(right.file));
     const titles = files
         .filter(({ file }) => file.endsWith('.test.ts'))
-        .flatMap(({ file, text, registrations }) => registrations.map((token) => ({ file, title: decodeTitle(text, token) })));
+        .flatMap(({ file, text, registrations }) => registrations.flatMap(({ token }) => token === undefined ? [] : [{ file, title: decodeTitle(text, token) }]));
     // A surviving registration supplies its title count, never evidence that a lost duplicate moved.
-    const holders = files.flatMap(({ file, text, tokens, registrations }) => collectLiterals(tokens)
-        .filter((token) => !registrations.includes(token))
-        .map((token) => ({ file, title: decodeTitle(text, token) })));
+    const holders = files.flatMap(({ file, text, tokens, registrations }) => {
+        const registered = new Set(registrations.flatMap(({ token }) => (token === undefined ? [] : [token])));
+        return collectLiterals(tokens)
+            .filter((token) => !registered.has(token))
+            .map((token) => ({ file, title: decodeTitle(text, token) }));
+    });
     const deficits = [...Map.groupBy(baseline, ({ title }) => title)].flatMap(([title, entries]) => {
         const survivors = titles.filter((candidate) => candidate.title === title);
         const unmatched = [...Map.groupBy(entries, ({ file }) => file)].flatMap(([file, local]) => local.slice(survivors.filter((candidate) => candidate.file === file).length));
@@ -297,16 +632,50 @@ function readReport(base, root) {
         count: baseline.length,
         missing: classified.flatMap(({ entry, holder }) => (holder === undefined ? [entry] : [])),
         moved: classified.flatMap(({ entry, holder }) => holder === undefined ? [] : [{ file: entry.file, title: entry.title, holder }]),
+        dynamic: [
+            ...baselineFiles.flatMap(({ file, registrations }) => readDynamic(file, registrations, 'baseline')),
+            ...files.flatMap(({ file, registrations }) => readDynamic(file, registrations, 'working')),
+        ],
+        lostDynamic: readLostDynamic(baselineFiles, files),
     };
 }
-function renderReport(report) {
+/**
+ * Escapes the tab, carriage return, and newline characters of a text-row cell.
+ *
+ * @param cell - The cell text.
+ * @returns The cell with each of those characters written as a backslash sequence.
+ */
+export function escapeCell(cell) {
+    return cell.replace(/\t/gu, '\\t').replace(/\r/gu, '\\r').replace(/\n/gu, '\\n');
+}
+/**
+ * Renders a report as a header line and one tab-separated row per finding.
+ *
+ * @param report - The report to render.
+ * @returns The text, without a trailing line feed.
+ */
+export function renderReport(report) {
     return [
-        `titles: ${report.count} baseline title(s) at ${report.base}, ${report.missing.length} missing, ${report.moved.length} moved`,
-        ...report.missing.map(({ file, title, deficit }) => `missing\t${file}\t${title}\t${deficit}`),
-        ...report.moved.map(({ file, title, holder }) => `moved\t${file}\t${title}\t${holder}`),
+        `titles: ${report.count} baseline title(s) at ${report.base}, ${report.missing.length} missing, ${report.moved.length} moved, ${report.dynamic.length} dynamic, ${report.lostDynamic.length} lost dynamic`,
+        ...report.missing.map(({ file, title, deficit }) => ['missing', file, title, String(deficit)].map(escapeCell).join('\t')),
+        ...report.moved.map(({ file, title, holder }) => ['moved', file, title, holder].map(escapeCell).join('\t')),
+        ...report.dynamic.map(({ file, spelling, tree }) => ['dynamic', file, tree, spelling].map(escapeCell).join('\t')),
+        ...report.lostDynamic.map(({ file, deficit }) => ['lost-dynamic', file, String(deficit)].map(escapeCell).join('\t')),
     ].join('\n');
 }
-function main(argv) {
+/**
+ * Runs the comparison and prints its report.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 clean, 3 a missing or moved title or a lost-dynamic file, 2 a tool
+ * failure, 64 usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`titles: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, ['--base', '--root', '--out']);
     if (missing.length > 0) {
         console.error(`titles: ${missing.join(', ')} given with no value`);
@@ -315,7 +684,11 @@ function main(argv) {
     const base = readOption(argv, '--base');
     const out = readOption(argv, '--out');
     if (base === undefined || (out !== undefined && !['.json', '.txt'].includes(extname(out)))) {
-        console.error('usage: titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]');
+        console.error(USAGE);
+        return 64;
+    }
+    if (base.startsWith('-')) {
+        console.error(`titles: --base ${describeName(base)} opens with "-"; give a revision name or hash`);
         return 64;
     }
     try {
@@ -328,11 +701,13 @@ function main(argv) {
             writeFileSync(target, `${extname(target) === '.json' ? json : text}\n`);
         }
         console.log(argv.includes('--json') ? json : text);
-        return report.missing.length > 0 ? 3 : 0;
+        return report.missing.length + report.moved.length + report.lostDynamic.length > 0 ? 3 : 0;
     }
     catch (error) {
         console.error(`titles: ${error instanceof Error ? error.message : String(error)}`);
         return 2;
     }
 }
-process.exitCode = main(process.argv.slice(2));
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    process.exitCode = main(process.argv.slice(2));
+}