md-verified 0.1.0

package/dist/src/runner.js

@@ -0,0 +1,353 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The execution engine.
+ *
+ * Loads glue code, parses a Markdown file, matches anchors to registered
+ * handlers, and runs them. Everything here is pure library -- the CLI in
+ * `check.ts` is a thin wrapper so the same engine can be driven from
+ * `bun test` (see `spec.test.ts`).
+ */
+import { resolve, dirname, basename, extname, join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { findGlueHint, parseMarkdown } from "./parser.js";
+import { checkReferences } from "./references.js";
+import { checkReviews } from "./reviews.js";
+import { getRegistrations, verify } from "./framework.js";
+/** Parse and run one Markdown file against whatever is currently registered. */
+export async function runFile(file, options = {}) {
+    const path = resolve(file);
+    const source = await readFile(path, 'utf8');
+    const parsed = parseMarkdown(source, file);
+    const run = await runParsed(parsed, options);
+    return { run, parsed };
+}
+/** Run an already-parsed document. */
+export async function runParsed(parsed, options = {}) {
+    const started = performance.now();
+    const results = [];
+    let bailed = false;
+    for (const anchor of parsed.anchors) {
+        if (options.only?.length && !options.only.includes(anchor.id)) {
+            results.push(skipped(anchor, 'filtered out by --only'));
+            continue;
+        }
+        if (bailed) {
+            results.push(skipped(anchor, 'not run (--bail)'));
+            continue;
+        }
+        const result = await runAnchor(anchor, parsed.file, options);
+        results.push(result);
+        if (options.bail && result.status === 'failed')
+            bailed = true;
+    }
+    // Referential integrity of the surrounding prose. Skipped for in-memory
+    // documents, which have no directory to resolve relative links against.
+    const references = options.links === false
+        ? []
+        : await checkReferences(parsed, { symbols: options.symbols });
+    const problems = [...parsed.problems, ...references];
+    // Reviews attest that a human read a section against the code behind it.
+    const reviews = checkReviews(parsed, { reviews: options.reviews });
+    const summary = {
+        anchors: results.length,
+        reviews: reviews.length,
+        reviewsStale: reviews.filter((r) => r.status === 'failed').length,
+        passed: results.filter((r) => r.status === 'passed').length,
+        failed: results.filter((r) => r.status === 'failed').length,
+        skipped: results.filter((r) => r.status === 'skipped').length,
+        cases: results.reduce((n, r) => n + r.cases.length, 0),
+        casesPassed: results.reduce((n, r) => n + r.cases.filter((x) => x.status === 'passed').length, 0),
+        casesFailed: results.reduce((n, r) => n + r.cases.filter((x) => x.status === 'failed').length, 0),
+        durationMs: performance.now() - started,
+    };
+    return {
+        file: parsed.file,
+        source: parsed.source,
+        anchors: results,
+        reviews,
+        problems,
+        // Structural problems are failures too -- a document that cannot bind, that
+        // points at things which no longer exist, or whose prose has not been read
+        // since the code moved, is not green.
+        ok: summary.failed === 0 && summary.reviewsStale === 0 && problems.length === 0,
+        summary,
+    };
+}
+/** Run every case for one anchor. */ /** Run every case for one anchor. */
+export async function runAnchor(anchor, file, options = {}) {
+    const plan = planCases(anchor, file);
+    if (plan.skipReason)
+        return skipped(anchor, plan.skipReason);
+    if (plan.failReason) {
+        return { ...base(anchor), status: 'failed', reason: plan.failReason, cases: [] };
+    }
+    const results = [];
+    for (const kase of plan.cases) {
+        if (options.bail && results.some((r) => r.status === 'failed')) {
+            results.push({ name: kase.name, status: 'skipped', error: null, stack: null, durationMs: 0, line: kase.line });
+            continue;
+        }
+        results.push(await runPlanned(kase, options.timeout ?? 5000));
+    }
+    const failed = results.some((r) => r.status === 'failed');
+    return {
+        ...base(anchor),
+        status: failed ? 'failed' : 'passed',
+        reason: null,
+        cases: results,
+    };
+}
+/**
+ * Resolve an anchor into runnable cases without executing them, so a test
+ * framework can own the scheduling and reporting.
+ *
+ * This is the single planning path: `runAnchor` and `bun test` both consume
+ * it, so a defective row fails identically under either.
+ */
+export function planCases(anchor, file) {
+    const registrations = getRegistrations(anchor.id);
+    if (registrations.length === 0) {
+        return { skipReason: `no handler registered for \`${anchor.id}\``, failReason: null, cases: [] };
+    }
+    const wrongKind = registrations.find((r) => r.kind !== anchor.kind);
+    if (wrongKind) {
+        return {
+            skipReason: null,
+            failReason: `handler for \`${anchor.id}\` is registered as verify.${wrongKind.kind}, but the document binds it to a ${anchor.kind}`,
+            cases: [],
+        };
+    }
+    // The asset itself could not be read: fail the anchor, but keep it bound so
+    // the reason is written back into the document.
+    if (anchor.defect) {
+        return { skipReason: null, failReason: anchor.defect, cases: [] };
+    }
+    const ctx = {
+        id: anchor.id,
+        kind: anchor.kind,
+        label: anchor.label,
+        file,
+        line: anchor.line,
+        meta: anchor.meta,
+    };
+    const cases = [];
+    const defects = anchor.kind === 'table' ? anchor.data.defects : [];
+    // A row that failed to coerce is a failing case in its own right. It never
+    // reaches a handler, so glue code never sees a half-built row.
+    for (const defect of defects) {
+        cases.push({
+            name: `row ${defect.index + 1}`,
+            line: defect.line,
+            run: async () => {
+                throw new Error(defect.message);
+            },
+        });
+    }
+    for (const registration of registrations) {
+        // A whole-asset handler must not run against a table that is silently
+        // missing rows -- a coverage check would report phantom gaps.
+        if (registration.mode === 'all' && defects.length > 0) {
+            cases.push({
+                name: wholeName(anchor.kind),
+                line: anchor.line,
+                run: async () => {
+                    throw new Error(`not run: ${defects.length} row(s) could not be read, so the ${anchor.kind} is incomplete`);
+                },
+            });
+            continue;
+        }
+        for (const kase of buildCases(anchor, registration.mode)) {
+            cases.push({
+                name: kase.name,
+                line: kase.line,
+                run: async () => {
+                    await registration.fn(kase.payload, ctx);
+                },
+            });
+        }
+    }
+    return { skipReason: null, failReason: null, cases };
+}
+/** How a whole-asset case is named, in the terminal and in error comments. */
+function wholeName(kind) {
+    return kind === 'mermaid' ? 'whole diagram' : `whole ${kind}`;
+}
+/** Fan an asset out into the cases a handler expects. */
+function buildCases(anchor, mode) {
+    if (mode === 'all') {
+        return [{ name: wholeName(anchor.kind), line: anchor.line, payload: anchor.data }];
+    }
+    if (anchor.kind === 'table') {
+        const table = anchor.data;
+        return table.rows.map((row) => ({
+            name: `row ${row.$index + 1}`,
+            line: row.$line,
+            payload: row,
+        }));
+    }
+    if (anchor.kind === 'mermaid') {
+        const graph = anchor.data;
+        return graph.edges.map((edge) => ({
+            name: `${edge.from} ${edge.directed ? '->' : '--'} ${edge.to}`,
+            line: null,
+            payload: edge,
+        }));
+    }
+    const list = anchor.data;
+    return list.flat.map((item) => ({
+        name: truncate(item.text || `item ${item.index + 1}`, 48),
+        line: item.line,
+        payload: item,
+    }));
+}
+async function runPlanned(kase, timeout) {
+    const started = performance.now();
+    try {
+        const value = kase.run();
+        await (timeout > 0 ? withTimeout(value, timeout, kase.name) : value);
+        return {
+            name: kase.name,
+            status: 'passed',
+            error: null,
+            stack: null,
+            durationMs: performance.now() - started,
+            line: kase.line,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        return {
+            name: kase.name,
+            status: 'failed',
+            error: error.message || String(err),
+            stack: error.stack ?? null,
+            durationMs: performance.now() - started,
+            line: kase.line,
+        };
+    }
+}
+function withTimeout(promise, ms, label) {
+    return new Promise((res, rej) => {
+        const timer = setTimeout(() => rej(new Error(`timed out after ${ms}ms (${label})`)), ms);
+        promise.then((v) => { clearTimeout(timer); res(v); }, (e) => { clearTimeout(timer); rej(e); });
+    });
+}
+/**
+ * Load one document and everything needed to run it, in isolation.
+ *
+ * The registry is a module-level singleton, so two documents that happen to
+ * share an anchor id -- `prices` is not an unusual name -- collide if their
+ * glue files are simply imported into the same process. Bun shares module
+ * state across test files, so that is not hypothetical.
+ *
+ * This resets the registry, loads only this document's glue, and returns cases
+ * whose closures already hold their handler. A later `loadDocument` call may
+ * reset the registry again without disturbing them. Use this rather than
+ * importing glue directly when a process handles more than one document.
+ */
+export async function loadDocument(file, options = {}) {
+    const source = await readFile(file, 'utf8');
+    // Isolate: whatever a previous document registered is not ours.
+    verify.reset();
+    const parsed = parseMarkdown(source, file);
+    if (parsed.anchors.length > 0) {
+        const gluePath = resolveGlue(file, options.glue, source);
+        if (!gluePath) {
+            throw new Error(`${file}: no glue code found. Add a <!-- verify: ./x.verify.ts --> hint, ` +
+                `create ${basename(file, extname(file))}.verify.ts next to it, or pass { glue }.`);
+        }
+        await loadGlue(gluePath);
+    }
+    const suites = parsed.anchors.map((anchor) => {
+        const plan = planCases(anchor, file);
+        return {
+            id: anchor.id,
+            kind: anchor.kind,
+            label: anchor.label,
+            line: anchor.line,
+            skipReason: plan.skipReason,
+            failReason: plan.failReason,
+            cases: plan.cases,
+        };
+    });
+    const references = options.links === false ? [] : await checkReferences(parsed, { symbols: options.symbols });
+    return {
+        file,
+        parsed,
+        suites,
+        problems: [...parsed.problems, ...references],
+        reviews: checkReviews(parsed, { reviews: options.reviews }),
+    };
+}
+// ---------------------------------------------------------------------------
+// glue-code loading
+// ---------------------------------------------------------------------------
+/** Conventional glue filenames tried next to `spec.md`, in order. */
+const GLUE_SUFFIXES = ['.verify.ts', '.verify.js', '.spec.ts', '.test.ts'];
+/**
+ * Find the glue file for a Markdown document: an explicit path wins, then a
+ * `<!-- verify: ./x.ts -->` hint in the document, then convention.
+ */
+export function resolveGlue(mdPath, explicit, source) {
+    if (explicit) {
+        const path = resolve(explicit);
+        if (!existsSync(path))
+            throw new Error(`glue file not found: ${explicit}`);
+        return path;
+    }
+    const dir = dirname(resolve(mdPath));
+    if (source) {
+        const hint = findGlueHint(source);
+        if (hint) {
+            const path = resolve(dir, hint);
+            if (!existsSync(path)) {
+                throw new Error(`glue file not found: ${hint} (from a <!-- verify: --> hint in ${basename(mdPath)})`);
+            }
+            return path;
+        }
+    }
+    const stem = basename(mdPath, extname(mdPath));
+    for (const suffix of GLUE_SUFFIXES) {
+        const candidate = join(dir, stem + suffix);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Import a glue module, bypassing the module cache so repeat runs re-register.
+ *
+ * A glue file that throws while loading is a common authoring mistake, and the
+ * bare error says nothing about which file it came from. Callers add the
+ * document; this adds the glue file and keeps the original as `cause`.
+ */
+export async function loadGlue(path) {
+    try {
+        await import(__rewriteRelativeImportExtension(`${path}?v=${Date.now()}`));
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err : new Error(String(err));
+        throw new Error(`glue file ${relative(process.cwd(), path)} failed to load: ${cause.message}`, { cause });
+    }
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function base(anchor) {
+    return { id: anchor.id, kind: anchor.kind, label: anchor.label, line: anchor.line };
+}
+function skipped(anchor, reason) {
+    return { ...base(anchor), status: 'skipped', reason, cases: [] };
+}
+function truncate(s, n) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > n ? flat.slice(0, n - 1) + '…' : flat;
+}

package/dist/src/symbols.d.ts

@@ -0,0 +1,15 @@
+export interface SymbolInfo {
+    name: string;
+    /** Declaration source, excluding leading comments. */
+    text: string;
+    /** 1-based line of the declaration. */
+    line: number;
+    kind: string;
+}
+/** Every exported symbol in a file, keyed by name. */
+export declare function exportedSymbols(path: string): Map<string, SymbolInfo> | Error;
+/** Names only. */
+export declare function exportedNames(path: string): Set<string> | Error;
+/** One exported symbol's declaration, or `undefined` if there is no such export. */
+export declare function exportedSymbol(path: string, name: string): SymbolInfo | Error | undefined;
+export declare function clearSymbolCache(): void;

package/dist/src/symbols.js

@@ -0,0 +1,112 @@
+/**
+ * Static symbol lookup, via the TypeScript compiler API.
+ *
+ * Two features need to know what a module exports and what a given export's
+ * source text is: link checking (`references.ts`) and review digests
+ * (`reviews.ts`).
+ *
+ * This reads the file rather than importing it. That matters for three
+ * reasons: importing a module runs it, which a lint has no business doing;
+ * type-only exports do not exist at runtime and so cannot be seen by an
+ * import; and a file that fails to load can still be read.
+ *
+ * The trade-off is that `export * from './x'` is not followed -- re-exported
+ * names are invisible here in a way they would not be to an import.
+ */
+import ts from 'typescript';
+const fileCache = new Map();
+/** Every exported symbol in a file, keyed by name. */
+export function exportedSymbols(path) {
+    const cached = fileCache.get(path);
+    if (cached !== undefined)
+        return cached;
+    let result;
+    try {
+        result = read(path);
+    }
+    catch (err) {
+        result = err instanceof Error ? err : new Error(String(err));
+    }
+    fileCache.set(path, result);
+    return result;
+}
+/** Names only. */
+export function exportedNames(path) {
+    const symbols = exportedSymbols(path);
+    return symbols instanceof Error ? symbols : new Set(symbols.keys());
+}
+/** One exported symbol's declaration, or `undefined` if there is no such export. */
+export function exportedSymbol(path, name) {
+    const symbols = exportedSymbols(path);
+    return symbols instanceof Error ? symbols : symbols.get(name);
+}
+export function clearSymbolCache() {
+    fileCache.clear();
+}
+// ---------------------------------------------------------------------------
+function read(path) {
+    const text = ts.sys.readFile(path);
+    if (text === undefined)
+        throw new Error('could not read file');
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
+    const found = new Map();
+    const add = (name, node, kind) => {
+        if (found.has(name))
+            return;
+        found.set(name, {
+            name,
+            text: node.getText(source),
+            line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+            kind,
+        });
+    };
+    for (const statement of source.statements) {
+        if (!isExported(statement)) {
+            // `export { a, b }` carries no modifier of its own.
+            if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+                for (const element of statement.exportClause.elements) {
+                    add(element.name.text, element, 'export');
+                }
+            }
+            continue;
+        }
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name)) {
+                    add(declaration.name.text, declaration, 'variable');
+                }
+            }
+            continue;
+        }
+        if (isDefault(statement)) {
+            add('default', statement, 'default');
+            continue;
+        }
+        const name = statement.name;
+        if (name && ts.isIdentifier(name)) {
+            add(name.text, statement, kindOf(statement));
+        }
+    }
+    return found;
+}
+function isExported(node) {
+    return Boolean(ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+}
+function isDefault(node) {
+    return Boolean(ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword));
+}
+function kindOf(node) {
+    if (ts.isFunctionDeclaration(node))
+        return 'function';
+    if (ts.isClassDeclaration(node))
+        return 'class';
+    if (ts.isInterfaceDeclaration(node))
+        return 'interface';
+    if (ts.isTypeAliasDeclaration(node))
+        return 'type';
+    if (ts.isEnumDeclaration(node))
+        return 'enum';
+    return 'declaration';
+}