md-verified 0.1.0

package/dist/check.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point.
+ *
+ *   bun run check.ts examples/spec.md
+ *   bun run check.ts examples/*.md --write
+ *   bun run check.ts examples/spec.md --json
+ */
+import { existsSync } from 'node:fs';
+import { glob, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+/** Where documents live when the caller does not say. */
+const DEFAULT_DOCS = '**/*.md';
+/** Never walk into these while globbing. */
+const IGNORED_DIRS = /(^|\/)(node_modules|\.git|dist|build|coverage|\.next|out)(\/|$)/;
+import { loadGlue, resolveGlue, runFile } from "./src/runner.js";
+import { c, formatRun, rewriteFromRun, setColor } from "./src/report.js";
+import { verify } from "./src/framework.js";
+import { parseMarkdown } from "./src/parser.js";
+const USAGE = `
+md-verified - executable specifications from native Markdown
+
+USAGE
+  md-verified <file.md|glob> [...] [options]
+
+  Globs are expanded by the tool, so quoting them is safe:
+  md-verified 'docs/**/*.md'
+
+OPTIONS
+  --glue <path>     Glue module to load. Defaults to a <!-- verify: --> hint in
+                    the document, then <name>.verify.ts next to it.
+  --write, -w       Write status glyphs and error comments back into the file.
+  --report          Print the annotated Markdown to stdout instead of writing.
+  --reset           Return every anchor to its unrun state and drop our comments.
+  --json            Emit machine-readable results (for agents and CI).
+  --stamp           Record the current digest on every review, marking the
+                    prose as read. Deliberately separate from --write.
+  --covering <path> Instead of checking, list the reviews that cover <path>.
+                    Answers "which documents describe this code?" without
+                    putting a marker in the code itself. Searches the documents
+                    given, or **/*.md when none are.
+  --no-links        Skip link, anchor and symbol checking.
+  --no-reviews      Skip review staleness checking.
+  --no-symbols      Check links, but do not import modules to check symbols.
+  --only <id>       Run only this anchor. Repeatable.
+  --bail            Stop at the first failure.
+  --timeout <ms>    Per-case timeout. Default 5000, 0 to disable.
+  --verbose, -v     Show passing cases and stack frames.
+  --no-color        Disable ANSI colour.
+  --help, -h        Show this message.
+
+EXIT CODE
+  0 when every anchor passed, 1 otherwise.
+`.trim();
+function parseArgs(argv) {
+    const flags = {
+        files: [],
+        write: false,
+        report: false,
+        reset: false,
+        stamp: false,
+        json: false,
+        verbose: false,
+        help: false,
+        only: [],
+        bail: false,
+        timeout: 5000,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--glue':
+                flags.glue = argv[++i];
+                break;
+            case '--only':
+                flags.only.push(argv[++i]);
+                break;
+            case '--timeout':
+                flags.timeout = Number(argv[++i]);
+                break;
+            case '--write':
+            case '-w':
+                flags.write = true;
+                break;
+            case '--report':
+                flags.report = true;
+                break;
+            case '--reset':
+                flags.reset = true;
+                break;
+            case '--json':
+                flags.json = true;
+                break;
+            case '--verbose':
+            case '-v':
+                flags.verbose = true;
+                break;
+            case '--no-color':
+                setColor(false);
+                break;
+            case '--stamp':
+                flags.stamp = true;
+                break;
+            case '--covering':
+                flags.covering = argv[++i];
+                break;
+            case '--no-links':
+                flags.links = false;
+                break;
+            case '--no-reviews':
+                flags.reviews = false;
+                break;
+            case '--no-symbols':
+                flags.symbols = false;
+                break;
+            case '--help':
+            case '-h':
+                flags.help = true;
+                break;
+            default:
+                if (arg.startsWith('-'))
+                    throw new Error(`unknown option: ${arg}`);
+                flags.files.push(arg);
+        }
+    }
+    return flags;
+}
+async function main() {
+    const flags = parseArgs(process.argv.slice(2));
+    if (flags.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    // JSON goes to stdout alone, so it stays pipeable.
+    if (flags.json)
+        setColor(false);
+    if (flags.covering) {
+        // Answering "which docs describe this file?" should not require the caller
+        // to remember where the documents live. Finding nothing is an answer here,
+        // not an error.
+        const searched = await expand(flags.files.length ? flags.files : [DEFAULT_DOCS]);
+        return await listCovering(flags, searched.files);
+    }
+    if (flags.files.length === 0) {
+        console.log(USAGE);
+        return 1;
+    }
+    const { files, unmatched } = await expand(flags.files);
+    const runs = [];
+    // A pattern that matches nothing is a failure, not a quiet no-op: in CI it
+    // would otherwise turn a moved or misspelled document path into a pass.
+    let failures = unmatched.length;
+    for (const pattern of unmatched) {
+        console.error(`md-verified: no files match ${pattern}`);
+    }
+    for (const file of files) {
+        try {
+            const run = await checkOne(file, flags);
+            runs.push(run);
+            if (!run.ok)
+                failures++;
+        }
+        catch (err) {
+            // One unusable document must not stop the others being reported.
+            console.error(`${file}: ${err.message}`);
+            failures++;
+        }
+    }
+    if (flags.json) {
+        console.log(JSON.stringify({
+            ok: failures === 0,
+            files: runs.map((r) => ({
+                file: r.file,
+                ok: r.ok,
+                summary: r.summary,
+                problems: r.problems,
+                reviews: r.reviews,
+                anchors: r.anchors.map((a) => ({
+                    id: a.id,
+                    kind: a.kind,
+                    line: a.line,
+                    status: a.status,
+                    reason: a.reason,
+                    cases: a.cases.map((cse) => ({
+                        name: cse.name,
+                        status: cse.status,
+                        line: cse.line,
+                        error: cse.error,
+                    })),
+                })),
+            })),
+        }, null, 2));
+    }
+    return failures === 0 ? 0 : 1;
+}
+/** Check one document. Throws only when the document cannot be run at all. */
+async function checkOne(file, flags) {
+    // Each document gets a clean registry, so ids only need to be unique per file.
+    verify.reset();
+    if (!existsSync(file))
+        throw new Error('no such file');
+    const source = await readFile(file, 'utf8');
+    const gluePath = resolveGlue(file, flags.glue, source);
+    // Glue is only required by anchors. A document that is prose plus reviews
+    // has nothing to execute, and should not be nagged for a handler file.
+    if (!gluePath && !flags.reset && parseMarkdown(source, file).anchors.length > 0) {
+        throw new Error(`no glue code found. Add a <!-- verify: ./x.verify.ts --> hint, ` +
+            `create ${basename(file, extname(file))}.verify.ts next to it, or pass --glue.`);
+    }
+    if (gluePath)
+        await loadGlue(gluePath);
+    const { run, parsed } = await runFile(file, {
+        only: flags.only.length ? flags.only : undefined,
+        bail: flags.bail,
+        timeout: flags.timeout,
+        links: flags.links,
+        symbols: flags.symbols,
+        reviews: flags.reviews,
+    });
+    if (flags.write || flags.report || flags.reset || flags.stamp) {
+        const next = rewriteFromRun(run, parsed, { reset: flags.reset, stamp: flags.stamp });
+        if (flags.report) {
+            if (!flags.json)
+                console.log(next);
+        }
+        else if (next !== run.source) {
+            await writeFile(file, next);
+        }
+    }
+    // A stamped review is current from this moment on. Reporting it as stale --
+    // and exiting non-zero -- would be complaining about the very thing the
+    // command just resolved, and would make `--stamp && ...` impossible.
+    const settled = flags.stamp ? afterStamping(run) : run;
+    if (!flags.json && !flags.report) {
+        console.log(formatRun(settled, { verbose: flags.verbose }));
+        console.log('');
+    }
+    return settled;
+}
+/**
+ * Fold a `--stamp` into the result: reviews that received a digest are now
+ * current. Reviews that failed for a reason stamping cannot fix -- covering a
+ * file that does not exist, declaring no targets -- are left failing.
+ */
+function afterStamping(run) {
+    const reviews = run.reviews.map((review) => review.status === 'failed' && review.digest !== null
+        ? { ...review, status: 'passed', reason: null, current: true }
+        : review);
+    const reviewsStale = reviews.filter((r) => r.status === 'failed').length;
+    const summary = { ...run.summary, reviewsStale };
+    return {
+        ...run,
+        reviews,
+        summary,
+        ok: summary.failed === 0 && reviewsStale === 0 && run.problems.length === 0,
+    };
+}
+/**
+ * Expand the file arguments, globbing any that need it.
+ *
+ * Shells do not always expand a pattern -- it may be quoted, or there may be no
+ * matching file in the current directory -- and passing `docs/*.md` through
+ * verbatim produced a raw `ENOENT` on the literal string.
+ */
+async function expand(patterns) {
+    const found = [];
+    const unmatched = [];
+    const seen = new Set();
+    for (const pattern of patterns) {
+        if (!/[*?[\]{}]/.test(pattern)) {
+            if (!seen.has(pattern)) {
+                seen.add(pattern);
+                found.push(pattern);
+            }
+            continue;
+        }
+        const matches = [];
+        for await (const match of glob(pattern)) {
+            const path = String(match);
+            // Skip dotfiles and vendored trees explicitly, so behaviour does not
+            // depend on which runtime's glob defaults are in play.
+            if (IGNORED_DIRS.test(path) || /(^|\/)\./.test(path))
+                continue;
+            matches.push(path);
+        }
+        if (matches.length === 0) {
+            unmatched.push(pattern);
+            continue;
+        }
+        for (const match of matches.sort()) {
+            if (seen.has(match))
+                continue;
+            seen.add(match);
+            found.push(match);
+        }
+    }
+    return { files: found, unmatched };
+}
+/**
+ * The reverse of `Covers:`.
+ *
+ * The mapping from prose to code already exists in the documents, so the
+ * question "which docs describe this file?" can be answered by reading them --
+ * no marker in the source, nothing extra to keep in sync.
+ */
+async function listCovering(flags, files) {
+    const target = resolve(flags.covering);
+    const hits = [];
+    for (const file of files) {
+        if (!existsSync(file))
+            continue;
+        const parsed = parseMarkdown(await readFile(file, 'utf8'), file);
+        const dir = dirname(resolve(file));
+        for (const review of parsed.reviews) {
+            for (const cover of review.covers) {
+                const [path] = cover.split('#');
+                if (resolve(dir, (path ?? '').trim()) === target) {
+                    hits.push({ file, id: review.id, line: review.line, target: cover });
+                }
+            }
+        }
+    }
+    if (flags.json) {
+        console.log(JSON.stringify({ covering: flags.covering, reviews: hits }, null, 2));
+    }
+    else if (hits.length === 0) {
+        console.log(`No review covers ${flags.covering} (searched ${files.length} document${files.length === 1 ? '' : 's'}).`);
+    }
+    else {
+        console.log(`Reviews covering ${flags.covering}:`);
+        for (const hit of hits) {
+            console.log(`  ${hit.file}:${hit.line}  ${hit.id}  ${c.dim(hit.target)}`);
+        }
+        console.log('');
+        console.log(c.dim('Changing this file may make the prose above wrong. Re-read it, then --stamp.'));
+    }
+    return 0;
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error(`md-verified: ${err.message}`);
+    process.exit(1);
+});

package/dist/src/assertions.d.ts

@@ -0,0 +1,25 @@
+/** Throw with `message` unless `condition` holds. */
+export declare function assert(condition: unknown, message: string): asserts condition;
+/**
+ * Assert that a computed value matches the documented one.
+ *
+ * ```ts
+ * equals(calculateTotal(row.items, row.tax), row.total, 'total');
+ * // -> "total: expected 16, got 15"
+ * ```
+ *
+ * Objects and arrays are compared structurally. `what` names the thing being
+ * checked; without it the message is just "expected 16, got 15".
+ */
+export declare function equals(actual: unknown, expected: unknown, what?: string): void;
+/**
+ * Assert that a value is one of a documented set.
+ *
+ * ```ts
+ * oneOf(row.status, ['active', 'paused'], 'status');
+ * // -> "status: \"archived\" is not one of active, paused"
+ * ```
+ */
+export declare function oneOf(value: unknown, allowed: Iterable<unknown>, what?: string): void;
+/** Render a value compactly enough to sit inside a one-line comment. */
+export declare function format(value: unknown): string;

package/dist/src/assertions.js

@@ -0,0 +1,84 @@
+/**
+ * Assertions, written for a document rather than a terminal.
+ *
+ * Any assertion library works here -- a handler fails by throwing, and that is
+ * the whole contract. But there is a constraint no test framework has: the
+ * failure message is written *into the Markdown file* and read as
+ * documentation. A terminal-shaped message is wrong for that medium:
+ *
+ *     <!-- ERROR: row 1: expect(received).toBe(expected) [nl] Expected: 15 [nl] Received: 16 -->
+ *     <!-- ERROR: row 1: total should be $15.00, got $16.00 -->
+ *
+ * So these stay deliberately few, and each one produces a single self-contained
+ * line phrased in terms of the claim the document is making. Reach for `assert`
+ * whenever you can say it better yourself -- which is often, and is the point.
+ */
+import { isDeepStrictEqual } from 'node:util';
+/** Throw with `message` unless `condition` holds. */
+export function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+/**
+ * Assert that a computed value matches the documented one.
+ *
+ * ```ts
+ * equals(calculateTotal(row.items, row.tax), row.total, 'total');
+ * // -> "total: expected 16, got 15"
+ * ```
+ *
+ * Objects and arrays are compared structurally. `what` names the thing being
+ * checked; without it the message is just "expected 16, got 15".
+ */
+export function equals(actual, expected, what) {
+    if (same(actual, expected))
+        return;
+    const subject = what ? `${what}: ` : '';
+    throw new Error(`${subject}expected ${format(expected)}, got ${format(actual)}`);
+}
+/**
+ * Assert that a value is one of a documented set.
+ *
+ * ```ts
+ * oneOf(row.status, ['active', 'paused'], 'status');
+ * // -> "status: \"archived\" is not one of active, paused"
+ * ```
+ */
+export function oneOf(value, allowed, what) {
+    const options = [...allowed];
+    if (options.some((option) => same(value, option)))
+        return;
+    const subject = what ? `${what}: ` : '';
+    throw new Error(`${subject}${format(value)} is not one of ${options.map((o) => String(o)).join(', ')}`);
+}
+function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
+        return isDeepStrictEqual(a, b);
+    }
+    return false;
+}
+/** How many characters of a formatted value we are willing to put in a line. */
+const MAX_VALUE = 60;
+/** Render a value compactly enough to sit inside a one-line comment. */
+export function format(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value === null || value === undefined || typeof value !== 'object')
+        return String(value);
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > MAX_VALUE ? `${text.slice(0, MAX_VALUE - 1)}…` : text;
+}

package/dist/src/coerce.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The value-type registry backing `**Schema:**` declarations.
+ *
+ * A schema turns opaque cell text into real JavaScript values, so glue code
+ * compares numbers to numbers instead of re-parsing `"$16.00"` by hand.
+ */
+/** Thrown when a cell cannot be read as its declared type. */
+export declare class CoercionError extends Error {
+    readonly value: string;
+    readonly type: string;
+    constructor(value: string, type: string, detail?: string);
+}
+export type Coercer = (raw: string, typeName: string) => unknown;
+/** Register a value type usable from a `**Schema:**` line. Case-insensitive. */
+export declare function registerType(name: string, coerce: Coercer): void;
+export declare function hasType(name: string): boolean;
+export declare function knownTypes(): string[];
+/** Coerce one cell. `optional` lets blank cells through as `null`. */
+export declare function coerce(raw: string, type: string, optional?: boolean): unknown;

package/dist/src/coerce.js

@@ -0,0 +1,122 @@
+/**
+ * The value-type registry backing `**Schema:**` declarations.
+ *
+ * A schema turns opaque cell text into real JavaScript values, so glue code
+ * compares numbers to numbers instead of re-parsing `"$16.00"` by hand.
+ */
+/** Thrown when a cell cannot be read as its declared type. */
+export class CoercionError extends Error {
+    // Assigned in the body rather than declared as constructor parameter
+    // properties: those are not supported by Node's strip-only type stripping,
+    // and this file is imported by glue code that Node may have to load as TS.
+    value;
+    type;
+    constructor(value, type, detail) {
+        super(`cannot read ${JSON.stringify(value)} as ${type}${detail ? ` (${detail})` : ''}`);
+        this.name = 'CoercionError';
+        this.value = value;
+        this.type = type;
+    }
+}
+const registry = new Map();
+/** Register a value type usable from a `**Schema:**` line. Case-insensitive. */
+export function registerType(name, coerce) {
+    registry.set(name.toLowerCase(), coerce);
+}
+export function hasType(name) {
+    return registry.has(name.toLowerCase());
+}
+export function knownTypes() {
+    return [...registry.keys()].sort();
+}
+/** Coerce one cell. `optional` lets blank cells through as `null`. */
+export function coerce(raw, type, optional = false) {
+    const text = raw.trim();
+    if (optional && (text === '' || text === '-' || text === '—'))
+        return null;
+    const fn = registry.get(type.toLowerCase());
+    if (!fn) {
+        throw new CoercionError(text, type, `unknown type; known types: ${knownTypes().join(', ')}`);
+    }
+    return fn(text, type);
+}
+// ---------------------------------------------------------------------------
+// Built-ins
+// ---------------------------------------------------------------------------
+/** `$1,234.50`, `(1,234.50)` and `-€12` all become numbers. */
+function parseNumeric(raw, type) {
+    let text = raw.trim();
+    let sign = 1;
+    // Accounting-style negatives: (12.00)
+    const paren = /^\((.*)\)$/.exec(text);
+    if (paren) {
+        sign = -1;
+        text = paren[1].trim();
+    }
+    text = text.replace(/[$€£¥₹]|\b(?:USD|EUR|GBP|JPY|DKK)\b/gi, '').replace(/[,\s_]/g, '');
+    if (text.startsWith('-')) {
+        sign *= -1;
+        text = text.slice(1);
+    }
+    else if (text.startsWith('+')) {
+        text = text.slice(1);
+    }
+    if (text === '' || !/^\d*\.?\d+(?:e[+-]?\d+)?$/i.test(text)) {
+        throw new CoercionError(raw, type);
+    }
+    return sign * Number(text);
+}
+registerType('Currency', (raw, type) => {
+    const n = parseNumeric(raw, type);
+    // Money is compared for equality constantly; keep it off the float knife-edge.
+    return Math.round(n * 1e6) / 1e6;
+});
+registerType('Percentage', (raw, type) => {
+    const hasSign = raw.includes('%');
+    const n = parseNumeric(raw.replace('%', ''), type);
+    // `10%` -> 0.1 so it multiplies directly. A bare `0.1` is already a fraction.
+    return hasSign ? Math.round((n / 100) * 1e6) / 1e6 : n;
+});
+registerType('Number', parseNumeric);
+registerType('Float', parseNumeric);
+registerType('Decimal', parseNumeric);
+registerType('Integer', (raw, type) => {
+    const n = parseNumeric(raw, type);
+    if (!Number.isInteger(n))
+        throw new CoercionError(raw, type, 'not a whole number');
+    return n;
+});
+registerType('Int', (raw, type) => coerce(raw, 'Integer'));
+const TRUE = new Set(['true', 'yes', 'y', '1', 'on', '✅', 'x', '☑', '✓']);
+const FALSE = new Set(['false', 'no', 'n', '0', 'off', '❌', '', '☐', '-']);
+registerType('Boolean', (raw, type) => {
+    const key = raw.trim().toLowerCase();
+    if (TRUE.has(key))
+        return true;
+    if (FALSE.has(key))
+        return false;
+    throw new CoercionError(raw, type);
+});
+registerType('Bool', (raw) => coerce(raw, 'Boolean'));
+registerType('Date', (raw, type) => {
+    const d = new Date(raw.trim());
+    if (Number.isNaN(d.getTime()))
+        throw new CoercionError(raw, type);
+    return d;
+});
+registerType('String', (raw) => raw.trim());
+registerType('Text', (raw) => raw.trim());
+registerType('JSON', (raw, type) => {
+    try {
+        return JSON.parse(raw.trim());
+    }
+    catch (err) {
+        throw new CoercionError(raw, type, err.message);
+    }
+});
+/** `a, b, c` -> `['a', 'b', 'c']`. */
+registerType('List', (raw) => raw
+    .trim()
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean));

package/dist/src/covers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Set assertions: does the document describe *all* of the thing?
+ *
+ * Per-element handlers only ever check elements that exist. If the code grows
+ * a fifth payment method and nobody adds a row, every row still passes and the
+ * specification is quietly wrong. `covers()` is the assertion that catches
+ * that -- and because a *missing* element is machine-identifiable, it is the
+ * failure an agent can act on directly.
+ */
+export interface CoversOptions {
+    /**
+     * Message for something present in `actual` but absent from the document.
+     * Pass `false` to allow the document to describe a subset.
+     */
+    missing?: ((key: string) => string) | false;
+    /**
+     * Message for something documented that does not exist.
+     * Pass `false` to allow the document to describe extras.
+     */
+    extra?: ((key: string) => string) | false;
+    /** Flag keys the document lists more than once. Default `true`. */
+    duplicates?: boolean;
+    /** Noun used in the default messages. Default `"entry"`. */
+    noun?: string;
+}
+/**
+ * Assert that the keys a document lists are exactly the keys that exist.
+ *
+ * ```ts
+ * covers(graph.edges.map((e) => `${e.from}>${e.to}`), allowedTransitions(), {
+ *   missing: (k) => `${k} is allowed in code but absent from the diagram`,
+ * });
+ * ```
+ *
+ * Throws once, listing everything wrong, so a single run tells you the whole
+ * gap rather than one element of it.
+ */
+export declare function covers(documented: Iterable<unknown>, actual: Iterable<unknown>, options?: CoversOptions): void;

package/dist/src/covers.js

@@ -0,0 +1,59 @@
+/**
+ * Set assertions: does the document describe *all* of the thing?
+ *
+ * Per-element handlers only ever check elements that exist. If the code grows
+ * a fifth payment method and nobody adds a row, every row still passes and the
+ * specification is quietly wrong. `covers()` is the assertion that catches
+ * that -- and because a *missing* element is machine-identifiable, it is the
+ * failure an agent can act on directly.
+ */
+/**
+ * Assert that the keys a document lists are exactly the keys that exist.
+ *
+ * ```ts
+ * covers(graph.edges.map((e) => `${e.from}>${e.to}`), allowedTransitions(), {
+ *   missing: (k) => `${k} is allowed in code but absent from the diagram`,
+ * });
+ * ```
+ *
+ * Throws once, listing everything wrong, so a single run tells you the whole
+ * gap rather than one element of it.
+ */
+export function covers(documented, actual, options = {}) {
+    const noun = options.noun ?? 'entry';
+    const doc = [...documented].map(String);
+    const act = [...actual].map(String);
+    const docSet = new Set(doc);
+    const actSet = new Set(act);
+    const problems = [];
+    if (options.missing !== false) {
+        const say = options.missing ?? ((k) => `missing ${noun}: ${k}`);
+        for (const key of act) {
+            if (!docSet.has(key))
+                problems.push(say(key));
+        }
+    }
+    if (options.extra !== false) {
+        const say = options.extra ?? ((k) => `unexpected ${noun}: ${k}`);
+        for (const key of docSet) {
+            if (!actSet.has(key))
+                problems.push(say(key));
+        }
+    }
+    if (options.duplicates !== false) {
+        const counts = new Map();
+        for (const key of doc)
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        for (const [key, n] of counts) {
+            if (n > 1)
+                problems.push(`duplicate ${noun}: ${key} (listed ${n} times)`);
+        }
+    }
+    if (problems.length) {
+        throw new Error(dedupe(problems).join('; '));
+    }
+}
+/** Preserve order, drop repeats -- `actual` may itself contain duplicates. */
+function dedupe(items) {
+    return [...new Set(items)];
+}