npm - md-verified - Versions diffs - 0.1.0 - Mend

md-verified 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/dist/src/report.d.ts ADDED Viewed

@@ -0,0 +1,52 @@
+/**
+ * Reporting, in two directions.
+ *
+ * *Outward*, to a human at a terminal: coloured pass/fail lines.
+ *
+ * *Back into the document*, for the next reader -- human or agent: the anchor
+ * glyph is rewritten to reflect the run, and failures are recorded as HTML
+ * comments directly beneath the anchor. Those comments are invisible in every
+ * Markdown renderer, so the document still looks hand-written, but they give
+ * an agent the exact failure text at exactly the place it must fix.
+ *
+ * Rewriting is a surgical splice against the original source -- never a
+ * re-serialisation of the AST -- so every byte the author wrote that we did
+ * not deliberately change survives untouched.
+ */
+import { type Anchor, type AnchorResult, type Review, type ReviewResult, type RunResult } from './types.ts';
+export interface RewriteOptions {
+    /** Ignore results and return every anchor to its unrun state. */
+    reset?: boolean;
+    /**
+     * Record the current digest on every review, marking it as read.
+     *
+     * Deliberately separate from a normal write: a stamp asserts that a person
+     * or agent has read the section against the code it covers. Applying it as a
+     * side effect of `--write` would make the attestation worthless.
+     */
+    stamp?: boolean;
+}
+/**
+ * Return `source` with each anchor's glyph and error comments brought in line
+ * with `results`.
+ */
+export declare function rewriteMarkdown(source: string, anchors: Anchor[], results: AnchorResult[], options?: RewriteOptions, reviews?: Review[], reviewResults?: ReviewResult[]): string;
+/** Convenience: rewrite straight from a `RunResult`. */
+export declare function rewriteFromRun(run: RunResult, parsed: {
+    anchors: Anchor[];
+    reviews: Review[];
+}, options?: RewriteOptions): string;
+/** Force colour on or off (the CLI's `--no-color` flag routes through here). */
+export declare function setColor(on: boolean): void;
+export declare const c: {
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+};
+/** Render a run as terminal text. */
+export declare function formatRun(run: RunResult, options?: {
+    verbose?: boolean;
+}): string;

package/dist/src/report.js ADDED Viewed

@@ -0,0 +1,278 @@
+/**
+ * Reporting, in two directions.
+ *
+ * *Outward*, to a human at a terminal: coloured pass/fail lines.
+ *
+ * *Back into the document*, for the next reader -- human or agent: the anchor
+ * glyph is rewritten to reflect the run, and failures are recorded as HTML
+ * comments directly beneath the anchor. Those comments are invisible in every
+ * Markdown renderer, so the document still looks hand-written, but they give
+ * an agent the exact failure text at exactly the place it must fix.
+ *
+ * Rewriting is a surgical splice against the original source -- never a
+ * re-serialisation of the AST -- so every byte the author wrote that we did
+ * not deliberately change survives untouched.
+ */
+import { REVIEW_PENDING_GLYPH, STATUS_GLYPH, } from "./types.js";
+/** Anchor first line: quote marker, optional glyph, then the bold body. */
+const FIRST_LINE_RE = /^(?<prefix>\s*>\s*)(?<glyph>[^\s*`]+\s+)?(?<body>\*\*\s*Verified[\s\S]*)$/;
+/** The same, for a review. */
+const REVIEW_LINE_RE = /^(?<prefix>\s*>\s*)(?<glyph>[^\s*`]+\s+)?(?<body>\*\*\s*Reviewed[\s\S]*)$/;
+/** A `> **Digest:** ...` line inside a review blockquote. */
+const DIGEST_LINE_RE = /^(?<prefix>\s*>\s*)\*\*\s*Digest\s*:?\s*\*\*\s*:?\s*.*$/;
+/** A status parenthetical we own and may replace. */
+const SUFFIX_RE = /\s*\((?:Failed|Passed|Skipped|Pending|Stale)[^)]*\)\s*$/i;
+/**
+ * A whole line holding a comment *we* wrote, and may therefore replace.
+ *
+ * Deliberately narrower than the parser's skip list: an author's
+ * `<!-- verify: ./glue.ts -->` hint must survive a rewrite untouched, so only
+ * our own `ERROR:` and `REVIEW:` comments match here.
+ */
+const MANAGED_LINE_RE = /^[ \t]*<!--\s*(?:ERROR|REVIEW):[\s\S]*?-->[ \t]*\r?\n?/gm;
+/** Most failures we will write into the document before summarising. */
+const MAX_COMMENTS = 8;
+/**
+ * Return `source` with each anchor's glyph and error comments brought in line
+ * with `results`.
+ */
+export function rewriteMarkdown(source, anchors, results, options = {}, reviews = [], reviewResults = []) {
+    const byAnchor = new Map(results.map((r) => [r.line + ':' + r.id, r]));
+    const byReview = new Map(reviewResults.map((r) => [r.line + ':' + r.id, r]));
+    const edits = [];
+    for (const anchor of anchors) {
+        const result = byAnchor.get(anchor.line + ':' + anchor.id);
+        const status = options.reset ? 'pending' : (result?.status ?? 'pending');
+        edits.push({
+            start: anchor.quoteRange.start,
+            end: anchor.gapRange.end,
+            replace: () => rewriteQuote(source.slice(anchor.quoteRange.start, anchor.quoteRange.end), status, result, options.reset === true) +
+                rewriteGap(source.slice(anchor.gapRange.start, anchor.gapRange.end), options.reset ? [] : commentsFor(result)),
+        });
+    }
+    for (const review of reviews) {
+        const result = byReview.get(review.line + ':' + review.id);
+        const status = options.reset ? 'pending' : (result?.status ?? 'pending');
+        // Stamping resolves the very thing the comment would report, so it clears
+        // the note rather than writing one.
+        const stamped = options.stamp === true && Boolean(result?.digest);
+        const comments = options.reset || stamped || status !== 'failed' || !result?.reason
+            ? []
+            : [comment('REVIEW', result.reason)];
+        edits.push({
+            start: review.quoteRange.start,
+            end: review.gapRange.end,
+            replace: () => rewriteReviewQuote(source.slice(review.quoteRange.start, review.quoteRange.end), status, result, options) + rewriteGap(source.slice(review.gapRange.start, review.gapRange.end), comments),
+        });
+    }
+    let out = source;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        out = out.slice(0, edit.start) + edit.replace() + out.slice(edit.end);
+    }
+    return out;
+}
+/** Convenience: rewrite straight from a `RunResult`. */
+export function rewriteFromRun(run, parsed, options = {}) {
+    return rewriteMarkdown(run.source, parsed.anchors, run.anchors, options, parsed.reviews, run.reviews);
+}
+/**
+ * Rewrite a review's blockquote: its glyph, and -- only when stamping -- the
+ * digest recorded on it.
+ */
+function rewriteReviewQuote(quote, status, result, options) {
+    const lines = quote.split('\n');
+    const head = REVIEW_LINE_RE.exec(lines[0] ?? '');
+    if (!head)
+        return quote;
+    const stamping = options.stamp === true && result?.digest;
+    const glyph = options.reset
+        ? REVIEW_PENDING_GLYPH
+        : stamping
+            ? STATUS_GLYPH.passed
+            : status === 'pending'
+                ? REVIEW_PENDING_GLYPH
+                : STATUS_GLYPH[status];
+    const body = head.groups.body.replace(SUFFIX_RE, '');
+    const suffix = options.reset || stamping || status !== 'failed' ? '' : '(Stale)';
+    lines[0] = head.groups.prefix + glyph + ' ' + body + (suffix ? ' ' + suffix : '');
+    const prefix = head.groups.prefix.replace(/\s+$/, ' ');
+    if (options.reset) {
+        return lines.filter((l) => !DIGEST_LINE_RE.test(l)).join('\n');
+    }
+    if (!stamping)
+        return lines.join('\n');
+    const digestLine = `${prefix}**Digest:** \`${result.digest}\``;
+    const existing = lines.findIndex((l) => DIGEST_LINE_RE.test(l));
+    if (existing === -1)
+        lines.push(digestLine);
+    else
+        lines[existing] = digestLine;
+    return lines.join('\n');
+}
+function rewriteQuote(quote, status, result, reset) {
+    const lines = quote.split('\n');
+    const m = FIRST_LINE_RE.exec(lines[0]);
+    if (!m)
+        return quote;
+    const body = m.groups.body.replace(SUFFIX_RE, '');
+    const suffix = reset ? '' : suffixFor(status, result);
+    lines[0] = m.groups.prefix + STATUS_GLYPH[status] + ' ' + body + (suffix ? ' ' + suffix : '');
+    return lines.join('\n');
+}
+function suffixFor(status, result) {
+    if (status === 'skipped')
+        return '(Skipped)';
+    if (status !== 'failed')
+        return '';
+    const total = result?.cases.length ?? 0;
+    const failed = result?.cases.filter((x) => x.status === 'failed').length ?? 0;
+    // Only worth counting when the asset fanned out into several cases.
+    return total > 1 ? `(Failed: ${failed} of ${total})` : '(Failed)';
+}
+function commentsFor(result) {
+    if (!result)
+        return [];
+    const lines = [];
+    if (result.status === 'skipped') {
+        if (result.reason)
+            lines.push(comment('VERIFY', result.reason));
+        return lines;
+    }
+    if (result.status !== 'failed')
+        return lines;
+    if (result.reason)
+        lines.push(comment('ERROR', result.reason));
+    // Deliberately no line numbers: writing these comments shifts the very lines
+    // they would cite, so citing them would make annotation non-idempotent. The
+    // case name identifies the case, and the comment already sits directly above
+    // the asset. Exact lines live in --json and the terminal report.
+    const failures = result.cases.filter((x) => x.status === 'failed');
+    for (const cse of failures.slice(0, MAX_COMMENTS)) {
+        lines.push(comment('ERROR', `${cse.name}: ${cse.error ?? 'failed'}`));
+    }
+    if (failures.length > MAX_COMMENTS) {
+        lines.push(comment('ERROR', `... and ${failures.length - MAX_COMMENTS} more failure(s)`));
+    }
+    return lines;
+}
+/** How many lines of a multi-line message we will write into a document. */
+const MAX_COMMENT_LINES = 6;
+/**
+ * Build one comment that cannot break out of its own delimiters.
+ *
+ * Single-line messages -- which is what the built-in assertions produce -- stay
+ * on one line. A message that genuinely has structure, typically from a
+ * third-party assertion library, keeps it: flattening a diff onto one line
+ * makes it unreadable in exactly the place people read it.
+ */
+function comment(tag, message) {
+    const safe = (text) => text.replace(/<!--/g, '&lt;!--').replace(/-->/g, '->>').replace(/[ \t]+/g, ' ').trim();
+    const lines = String(message)
+        .split(/\r?\n/)
+        .map(safe)
+        .filter(Boolean);
+    if (lines.length <= 1)
+        return `<!-- ${tag}: ${lines[0] ?? 'failed'} -->`;
+    const kept = lines.slice(0, MAX_COMMENT_LINES);
+    if (lines.length > MAX_COMMENT_LINES) {
+        kept.push(`... ${lines.length - MAX_COMMENT_LINES} more line(s)`);
+    }
+    // A blank line would end the HTML block, so there are none: `filter(Boolean)`
+    // above drops them and every continuation line carries indentation.
+    return `<!-- ${tag}: ${kept[0]}\n${kept.slice(1).map((l) => `     ${l}`).join('\n')} -->`;
+}
+function rewriteGap(gap, comments) {
+    // Drop whatever we wrote last time; keep anything the author added.
+    const authored = gap.replace(MANAGED_LINE_RE, '').trim();
+    const parts = [];
+    if (authored)
+        parts.push(authored);
+    if (comments.length)
+        parts.push(comments.join('\n'));
+    // A blank line on both sides keeps the blockquote and the asset as separate
+    // blocks, which is what makes the lookahead binding stable.
+    return parts.length ? '\n\n' + parts.join('\n\n') + '\n\n' : '\n\n';
+}
+// ---------------------------------------------------------------------------
+// Terminal output
+// ---------------------------------------------------------------------------
+const ESC = String.fromCharCode(27);
+let colorEnabled = !process.env.NO_COLOR && Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb';
+/** Force colour on or off (the CLI's `--no-color` flag routes through here). */
+export function setColor(on) {
+    colorEnabled = on;
+}
+const paint = (code) => (s) => colorEnabled ? `${ESC}[${code}m${s}${ESC}[0m` : s;
+export const c = {
+    green: paint('32'),
+    red: paint('31'),
+    yellow: paint('33'),
+    blue: paint('36'),
+    dim: paint('2'),
+    bold: paint('1'),
+};
+const MARK = {
+    passed: () => c.green('\u2714'),
+    failed: () => c.red('\u2716'),
+    skipped: () => c.yellow('\u25cb'),
+};
+/** Render a run as terminal text. */
+export function formatRun(run, options = {}) {
+    const out = [];
+    out.push(c.bold(run.file));
+    for (const p of run.problems) {
+        const where = p.column ? `${p.line}:${p.column}` : `line ${p.line}`;
+        out.push(`  ${c.red('\u2716')} ${c.dim(where)} ${p.message}`);
+    }
+    for (const a of run.anchors) {
+        const counts = a.cases.length > 1
+            ? c.dim(` ${a.cases.filter((x) => x.status === 'passed').length}/${a.cases.length}`)
+            : '';
+        const reason = a.status === 'skipped' && a.reason ? c.dim(` \u2014 ${a.reason}`) : '';
+        out.push(`  ${MARK[a.status]()} ${a.id}${counts} ${c.dim(`(${a.kind}, line ${a.line})`)}${reason}`);
+        if (a.status === 'failed' && a.reason) {
+            for (const line of a.reason.split(/\r?\n/)) {
+                if (line.trim())
+                    out.push(`      ${c.red(line.trim())}`);
+            }
+        }
+        for (const cse of a.cases) {
+            if (cse.status === 'failed') {
+                const where = cse.line ? `:${cse.line}` : '';
+                const [first, ...rest] = (cse.error ?? 'failed').split(/\r?\n/);
+                out.push(`      ${c.dim(cse.name + where)}  ${c.red(first ?? 'failed')}`);
+                for (const line of rest) {
+                    if (line.trim())
+                        out.push(`        ${c.red(line.trim())}`);
+                }
+                if (options.verbose && cse.stack) {
+                    out.push(...cse.stack.split('\n').slice(1, 4).map((l) => c.dim('        ' + l.trim())));
+                }
+            }
+            else if (options.verbose) {
+                out.push(`      ${c.green('\u00b7')} ${c.dim(cse.name)}`);
+            }
+        }
+    }
+    for (const review of run.reviews) {
+        const mark = review.status === 'passed' ? MARK.passed() : MARK.failed();
+        out.push(`  ${mark} ${review.id} ${c.dim(`(review, line ${review.line})`)}`);
+        if (review.reason) {
+            for (const line of review.reason.split(/\r?\n/)) {
+                if (line.trim())
+                    out.push(`      ${c.red(line.trim())}`);
+            }
+        }
+    }
+    const s = run.summary;
+    const bits = [
+        s.passed ? c.green(`${s.passed} passed`) : null,
+        s.failed ? c.red(`${s.failed} failed`) : null,
+        s.skipped ? c.yellow(`${s.skipped} skipped`) : null,
+    ].filter(Boolean);
+    out.push('');
+    out.push(`  ${bits.join(c.dim(', ')) || c.dim('nothing to verify')} ${c.dim(`(${s.cases} case${s.cases === 1 ? '' : 's'}` +
+        (s.reviews ? `, ${s.reviews - s.reviewsStale}/${s.reviews} reviews current` : '') +
+        `, ${s.durationMs.toFixed(0)}ms)`)}`);
+    return out.join('\n');
+}

package/dist/src/reviews.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import type { ParseResult, ReviewResult } from './types.ts';
+export interface ReviewOptions {
+    /** Skip review checking entirely. */
+    reviews?: boolean;
+}
+/** Check every review in a document against the code it covers. */
+export declare function checkReviews(parsed: ParseResult, options?: ReviewOptions): ReviewResult[];
+/**
+ * Digest the source of everything a review covers.
+ *
+ * A target is either a whole file (`./checkout.ts`) or one exported symbol
+ * (`./checkout.ts#calculateTotal`). Prefer the symbol form: a file-level
+ * digest is invalidated by every unrelated edit in that file, and a review
+ * that cries wolf gets stamped without being read.
+ *
+ * Leading comments are excluded from a symbol's text, so rewording a doc
+ * comment does not demand a re-review.
+ */
+export declare function digestOf(covers: string[], dir: string): string | Error;

package/dist/src/reviews.js ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * Review staleness.
+ *
+ * An anchor executes a claim. Most of a good document is not executable --
+ * rationale, context, the reason a rule exists at all -- and that prose is
+ * usually the part worth reading. It is also the part that rots silently.
+ *
+ * A review does not attempt to verify prose. It records which code a section
+ * describes, and a digest of that code at the moment someone last read the two
+ * together. When the code changes the digest stops matching, and the section
+ * is flagged for a human to re-read. That is an attestation, not a proof, and
+ * it is deliberately the weaker claim -- the alternative is either checking
+ * nothing, or pretending prose can be executed.
+ *
+ * Stamping is a separate, deliberate act (`--stamp`). It is never done by
+ * `--write`, because a stamp applied automatically would attest to nothing.
+ */
+import { dirname, resolve as resolvePath } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { exportedSymbol } from "./symbols.js";
+/** How many hex characters of the digest we record. */
+const DIGEST_LENGTH = 12;
+/**
+ * Digest format version, recorded in the stamp.
+ *
+ * The algorithm is part of the file format: change it and every stamp in every
+ * repository stops matching. Without a version marker that would be reported
+ * as "the code changed" -- a lie, and one that trains people to stamp blindly.
+ * With it, we can say what actually happened.
+ */
+const DIGEST_VERSION = '1';
+/** Check every review in a document against the code it covers. */
+export function checkReviews(parsed, options = {}) {
+    if (options.reviews === false)
+        return [];
+    const dir = dirname(resolvePath(parsed.file));
+    return parsed.reviews.map((review) => check(review, dir));
+}
+function check(review, dir) {
+    const base = { id: review.id, line: review.line };
+    if (review.defect) {
+        return { ...base, status: 'failed', reason: review.defect, digest: null, current: false };
+    }
+    const computed = digestOf(review.covers, dir);
+    if (computed instanceof Error) {
+        return { ...base, status: 'failed', reason: computed.message, digest: null, current: false };
+    }
+    if (!review.digest) {
+        return {
+            ...base,
+            status: 'failed',
+            reason: `never stamped; read this section against ${review.covers.join(', ')}, then run --stamp`,
+            digest: computed,
+            current: false,
+        };
+    }
+    if (!review.digest.startsWith(`${DIGEST_VERSION}:`)) {
+        return {
+            ...base,
+            status: 'failed',
+            reason: `stamped with an older digest format, so it cannot be compared; the code may well be unchanged. Re-read and run --stamp`,
+            digest: computed,
+            current: false,
+        };
+    }
+    if (review.digest !== computed) {
+        return {
+            ...base,
+            status: 'failed',
+            reason: `${review.covers.join(', ')} changed since this section was last read; re-read it, correct it if it is now wrong, then run --stamp`,
+            digest: computed,
+            current: false,
+        };
+    }
+    return { ...base, status: 'passed', reason: null, digest: computed, current: true };
+}
+/**
+ * Digest the source of everything a review covers.
+ *
+ * A target is either a whole file (`./checkout.ts`) or one exported symbol
+ * (`./checkout.ts#calculateTotal`). Prefer the symbol form: a file-level
+ * digest is invalidated by every unrelated edit in that file, and a review
+ * that cries wolf gets stamped without being read.
+ *
+ * Leading comments are excluded from a symbol's text, so rewording a doc
+ * comment does not demand a re-review.
+ */
+export function digestOf(covers, dir) {
+    if (covers.length === 0) {
+        return new Error('declares no **Covers:** targets, so there is nothing to go stale against');
+    }
+    const hasher = createHash('sha256');
+    for (const target of covers) {
+        const text = sourceOf(target, dir);
+        if (text instanceof Error)
+            return text;
+        hasher.update(`${target} ${text} `);
+    }
+    return `${DIGEST_VERSION}:${hasher.digest('hex').slice(0, DIGEST_LENGTH)}`;
+}
+/** The source text a single `Covers:` target refers to. */
+function sourceOf(target, dir) {
+    const hash = target.indexOf('#');
+    const filePart = (hash === -1 ? target : target.slice(0, hash)).trim();
+    const symbol = hash === -1 ? null : target.slice(hash + 1).trim();
+    const path = resolvePath(dir, filePart);
+    if (!existsSync(path)) {
+        return new Error(`covers ${target}, but ${filePart} does not exist`);
+    }
+    if (!symbol) {
+        try {
+            return normalise(readFileSync(path, 'utf8'));
+        }
+        catch (err) {
+            return new Error(`covers ${target}, but it could not be read: ${err.message}`);
+        }
+    }
+    const found = exportedSymbol(path, symbol);
+    if (found instanceof Error) {
+        return new Error(`covers ${target}, but ${filePart} could not be read: ${found.message}`);
+    }
+    if (!found) {
+        return new Error(`covers ${target}, but ${filePart} exports no \`${symbol}\``);
+    }
+    return normalise(found.text);
+}
+/**
+ * Line endings are a property of the checkout, not of the code.
+ *
+ * Without this, a team with mixed Windows and Unix working copies -- or one
+ * `core.autocrlf` setting -- sees every review go stale on every machine, and
+ * learns to stamp without reading.
+ */
+function normalise(text) {
+    return text.replace(/\r\n/g, '\n');
+}

package/dist/src/runner.d.ts ADDED Viewed

@@ -0,0 +1,94 @@
+import type { Anchor, AnchorKind, AnchorResult, ParseProblem, ReviewResult, ParseResult, RunResult } from './types.ts';
+export interface RunOptions {
+    /** Only run anchors whose id is in this list. */
+    only?: string[];
+    /** Check links, in-document anchors and fragment-linked symbols. Default on. */
+    links?: boolean;
+    /** Check that fragment-linked symbols exist. Default on. */
+    symbols?: boolean;
+    /** Check review staleness. Default on. */
+    reviews?: boolean;
+    /** Stop after the first failing case. */
+    bail?: boolean;
+    /** Per-case timeout in ms. `0` disables. */
+    timeout?: number;
+}
+/** Parse and run one Markdown file against whatever is currently registered. */
+export declare function runFile(file: string, options?: RunOptions): Promise<{
+    run: RunResult;
+    parsed: ParseResult;
+}>;
+/** Run an already-parsed document. */
+export declare function runParsed(parsed: ParseResult, options?: RunOptions): Promise<RunResult>;
+/** Run every case for one anchor. */ /** Run every case for one anchor. */
+export declare function runAnchor(anchor: Anchor, file: string, options?: RunOptions): Promise<AnchorResult>;
+/** One case, ready to run. Throwing from `run` is the failure signal. */
+export interface PlannedCase {
+    name: string;
+    line: number | null;
+    run: () => Promise<void>;
+}
+export interface Plan {
+    /** Set when the anchor is not this run's business at all. */
+    skipReason: string | null;
+    /** Set when the anchor fails as a whole, before any case runs. */
+    failReason: string | null;
+    cases: PlannedCase[];
+}
+/**
+ * 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 declare function planCases(anchor: Anchor, file: string): Plan;
+/** One anchor, expanded into the cases a test runner can schedule. */
+export interface DocumentSuite {
+    id: string;
+    kind: AnchorKind;
+    label: string;
+    line: number;
+    /** Set when the anchor has no handler. */
+    skipReason: string | null;
+    /** Set when the anchor fails as a whole, before any case runs. */
+    failReason: string | null;
+    cases: PlannedCase[];
+}
+export interface LoadedDocument {
+    file: string;
+    parsed: ParseResult;
+    suites: DocumentSuite[];
+    /** Parse problems and reference diagnostics, combined. */
+    problems: ParseProblem[];
+    reviews: ReviewResult[];
+}
+/**
+ * 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 declare function loadDocument(file: string, options?: RunOptions & {
+    glue?: string;
+}): Promise<LoadedDocument>;
+/**
+ * Find the glue file for a Markdown document: an explicit path wins, then a
+ * `<!-- verify: ./x.ts -->` hint in the document, then convention.
+ */
+export declare function resolveGlue(mdPath: string, explicit?: string, source?: string): string | 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 declare function loadGlue(path: string): Promise<void>;