urtext 0.1.0

package/dist/report/terminal.js

@@ -0,0 +1,206 @@
+import { labelConcealed } from "./conceal.js";
+import { buildReportModel, location, NO_FINDINGS_COPY, plainText, TIER_ORDER, TIER_WORD, } from "./model.js";
+/**
+ * The terminal surface, a walker over the report model. Every sentence, tier,
+ * glyph, ordering, and disclosure printed here is decided by
+ * `buildReportModel` — what this file owns is format mechanics: spacing,
+ * indentation, line wrapping, the gutter labels, and the width-limited
+ * excerpt cut. Model text arrives with concealment already applied
+ * (structurally, as `ConcealSegment` arrays, or as labelled strings for
+ * identifier-shaped fields), so this walker joins segments through
+ * `plainText` and never re-derives concealment for model content.
+ */
+function wrap(text, width, indent) {
+    const words = text.split(/\s+/);
+    const lines = [];
+    let line = "";
+    for (const w of words) {
+        if (line && (line + " " + w).length > width) {
+            lines.push(indent + line);
+            line = w;
+        }
+        else {
+            line = line ? line + " " + w : w;
+        }
+    }
+    if (line)
+        lines.push(indent + line);
+    return lines;
+}
+/** How many evidence refs to show per finding. A summary, not a dump. The model carries every ref; this cap is this surface's presentation density. */
+const EVIDENCE_SHOWN = 2;
+/** Where the excerpt cut lands, counted in rendered code points. */
+const EXCERPT_WIDTH = 56;
+/** The wrap width for body and reasoning paragraphs. */
+const BODY_WIDTH = 64;
+/**
+ * Whitespace-trims an excerpt's edges without ever deleting a concealed
+ * segment: only ordinary text segments are trimmed. A raw-string trim would
+ * silently drop the whitespace-classed concealing characters at either edge;
+ * here they stay visible as their labels, which is the point of labelling
+ * them.
+ */
+function trimSegments(segments) {
+    const out = segments.map((s) => ({ ...s }));
+    while (out.length > 0 && out[0].kind === "text") {
+        out[0].text = out[0].text.replace(/^\s+/, "");
+        if (out[0].text)
+            break;
+        out.shift();
+    }
+    while (out.length > 0 && out[out.length - 1].kind === "text") {
+        const last = out[out.length - 1];
+        last.text = last.text.replace(/\s+$/, "");
+        if (last.text)
+            break;
+        out.pop();
+    }
+    return out;
+}
+/**
+ * Width-limits an excerpt to one terminal line, segment-aware two ways.
+ * Counted in code points, not UTF-16 units — `String#slice` counts units, so
+ * an astral character straddling the cut left a lone surrogate that renders
+ * as U+FFFD; see `test/report/terminal.test.ts`, "never splits a surrogate
+ * pair at the excerpt truncation boundary". And the cut never lands inside a
+ * concealed segment's label: a bisected label would misstate the code point,
+ * so the cut falls before the whole label instead — the design spec's
+ * addendum accepts the shorter line this can produce on concealed input near
+ * EXCERPT_WIDTH.
+ */
+function excerpt(segments) {
+    const trimmed = trimSegments(segments);
+    const full = plainText(trimmed);
+    if ([...full].length <= EXCERPT_WIDTH)
+        return full;
+    // One code point of the width is reserved for the ellipsis, as before.
+    let budget = EXCERPT_WIDTH - 1;
+    let out = "";
+    for (const s of trimmed) {
+        if (s.kind === "concealed") {
+            const label = `[${s.text}]`;
+            if (label.length > budget)
+                break;
+            out += label;
+            budget -= label.length;
+        }
+        else {
+            const points = [...s.text];
+            if (points.length > budget) {
+                out += points.slice(0, budget).join("");
+                budget = 0;
+            }
+            else {
+                out += s.text;
+                budget -= points.length;
+            }
+        }
+        if (budget === 0)
+            break;
+    }
+    return out + "…";
+}
+export function renderTerminal(changeset, findings, reportPath, warnings = [], model, suppressed = 0) {
+    const m = buildReportModel(changeset, findings, { model, warnings, suppressed });
+    const out = [];
+    out.push("");
+    out.push(`urtext · ${m.scope}`);
+    // The disclosures, in model order — warnings first, then the untracked
+    // note — with the deleted-file coverage note beside them: each is a
+    // coverage statement no finding below can show, and they come before the
+    // findings because a reader has to know the review is partial before
+    // reading the list and concluding nothing else was found.
+    for (const note of m.notes) {
+        out.push(`  Note: ${note}`);
+    }
+    if (m.coverageNote) {
+        out.push(`  Note: ${m.coverageNote}`);
+    }
+    // Spacing only: analyzer warnings get a separating blank line before the
+    // findings, exactly as this surface always printed them; the untracked and
+    // coverage notes alone flow straight into the list.
+    if (warnings.length > 0)
+        out.push("");
+    if (m.findings.length === 0) {
+        out.push(`  ${NO_FINDINGS_COPY}`);
+        out.push("");
+    }
+    else {
+        const parts = [];
+        for (const tier of TIER_ORDER) {
+            if (m.counts[tier])
+                parts.push(`${m.counts[tier]} ${TIER_WORD[tier]}`);
+        }
+        out.push(`  EVIDENCE  ${parts.join(" · ")}`);
+        // Named right under the tier counts, not buried in a footer: a ● or ○
+        // badge asserts "a machine looked at this", and that assertion is only
+        // checkable if the reader also knows which machine. The gate — a model
+        // name AND a model-derived tier below — is the model's; `provenance` is
+        // simply absent otherwise.
+        if (m.provenance) {
+            out.push(`  MODEL     ${m.provenance}`);
+        }
+        // Under the provenance line, or under EVIDENCE when there is none, and
+        // before the blank line that separates the header from the findings: the
+        // badge is explained before the reader meets it.
+        if (m.beyondIntentLegend) {
+            out.push(`  ${m.beyondIntentLegend}`);
+        }
+        out.push("");
+        for (const f of m.findings) {
+            out.push(`  ${f.glyph} ${plainText(f.headline)}  [${f.tier}]` +
+                (f.beyondIntent ? `  (${f.beyondIntent})` : ""));
+            for (const paragraph of f.body) {
+                out.push(...wrap(plainText(paragraph), BODY_WIDTH, "    "));
+            }
+            if (f.tier === "model" && f.modelNote) {
+                // A model-tier finding's whole body is the model's prose, carried in
+                // `modelNote` so it can never travel without attribution. On this
+                // surface the [model] badge on the headline is that attribution, as
+                // it always was, and the prose prints as the body.
+                out.push(...wrap(plainText(f.modelNote.text), BODY_WIDTH, "    "));
+            }
+            else if (f.modelNote && m.modelName) {
+                // The analyzer's paragraphs already said what was found; this is the
+                // model's added explanation of why it matters, labelled rather than
+                // folded silently into the same paragraph — a reader deciding how
+                // much to trust an [inferred] finding needs to see the two apart.
+                //
+                // Gated on the recorded model name, not just the note's presence:
+                // model prose with no name attached to it is the one rendering state
+                // this surface must never produce, and the provenance line above is
+                // under the same gate. See `test/report/terminal.test.ts`, "never
+                // prints model prose without its attribution".
+                out.push(...wrap(`model: ${plainText(f.modelNote.text)}`, BODY_WIDTH, "    "));
+            }
+            // The evidence is the point. A tier badge with nothing checkable under
+            // it asks the reader to take the claim on faith, which is exactly what
+            // "verified" is supposed to replace.
+            for (const e of f.evidence.slice(0, EVIDENCE_SHOWN)) {
+                out.push(`      ${location(e)}  ${excerpt(e.excerpt)}`);
+            }
+            const rest = f.evidence.length - EVIDENCE_SHOWN;
+            if (rest > 0)
+                out.push(`      … ${rest} more`);
+            out.push("");
+        }
+    }
+    // Composed by the model (see `ReportModel.filterNote`); absent entirely
+    // when nothing was suppressed — see `test/report/terminal.test.ts`,
+    // "prints no filter footnote when nothing was suppressed".
+    if (m.filterNote) {
+        out.push(`  ${m.filterNote}`);
+        out.push("");
+    }
+    // Outside the findings branch on purpose: a clean review (no findings)
+    // still writes a report, and the reader needs to be told where it went
+    // exactly as much as a reader who scrolled past a full list of findings
+    // does — see `test/report/terminal.test.ts`, "prints the report path even
+    // when there are no findings". The path is the one string on this surface
+    // that does not come from the model, so the walker labels it itself.
+    if (reportPath) {
+        out.push(`  Full report: ${labelConcealed(reportPath)}`);
+        out.push("");
+    }
+    return out.join("\n");
+}

package/dist/report/write.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Filesystem-safe, lexicographically sortable timestamp for a report's
+ * filename. `Date#toISOString` already sorts lexicographically in step with
+ * time — fixed field widths, most-significant field first, UTC so there is
+ * no offset to compare across — but a colon is one of the handful of
+ * characters Windows forbids in a filename, and `toISOString` puts two of
+ * them in the time-of-day. Substituting a hyphen keeps every other property
+ * of the format and loses none of its sort order, since a hyphen still sorts
+ * before every digit in ASCII.
+ */
+export declare function reportTimestamp(date?: Date): string;
+/**
+ * Whether the reviewed repository already ignores `.urtext/`, read-only.
+ * urtext writes into the repository it is reviewing, but it must never edit
+ * a file the repository's owner tracks — a diff review tool that patches
+ * your .gitignore to tidy up after itself has changed the very thing it was
+ * asked to look at, and the next review of the working tree would report
+ * that change as if the user had made it. The caller decides what to do
+ * with a `false` result (see `review` in `cli.ts`, which prints a one-line
+ * suggestion rather than acting on it).
+ *
+ * Delegated to `git check-ignore` rather than reading and pattern-matching
+ * `.gitignore` directly: a repository can also exclude a path through
+ * `.git/info/exclude`, a user's global `core.excludesFile`, or a glob like
+ * `**\/.urtext/` that a root-only `.gitignore` read would never recognise as
+ * covering it — git already resolves all of those into one answer, so
+ * re-deriving a subset of that logic here would only reproduce it worse.
+ *
+ * The query names a file inside the directory, not the directory itself. On
+ * git for Windows, a CRLF-encoded `.gitignore` whose blank lines are a bare
+ * carriage return makes `check-ignore` match ANY query ending in a slash
+ * against one of those blank lines — the first real repository this tool
+ * reviewed answered "ignored" for a directory nothing ignored, and the tip
+ * was silently withheld. A child path never ends in a slash, so it is immune;
+ * and because a directory pattern like `.urtext/` covers everything beneath
+ * it, the child matches every pattern shape that covers the directory —
+ * whether or not either of them exists on disk. The probe file is never
+ * created; it exists only as a question.
+ */
+export declare function isUrtextGitignored(root: string): Promise<boolean>;
+/**
+ * Whether `review` in `../cli.ts` should print its gitignore tip. Distinct
+ * from `isUrtextGitignored`, whose propagate-real-failures contract is right
+ * for a function answering a question about the repository — but wrong for
+ * this call site: the tip is printed after the review has succeeded and the
+ * report is on disk, so a git failure here (a repository gone bad between
+ * the review and this last lookup) used to reject the whole `review()` call
+ * — discarding the completed terminal output while leaving a report on disk
+ * beside a nonzero exit, the exact disagreement this module's write path is
+ * designed to avoid. A tip that cannot be verified is simply not offered.
+ */
+export declare function shouldSuggestGitignore(root: string): Promise<boolean>;
+/**
+ * Writes the rendered report under the repository root, not `process.cwd()`
+ * — `urtext review` must land the file in the same place whether it runs at
+ * the root or three directories down, and only the root is stable across
+ * both. See test/cli.test.ts, "writes the report under the repository
+ * root, whether invoked from the root or a subdirectory".
+ */
+export declare function writeReport(root: string, html: string): Promise<string>;
+/**
+ * Every format `--export` can write, in the order the flag's usage copy
+ * names them. Owned beside the writer so the parser in `../cli.ts`, the
+ * writer below, and the `exportPaths` keys in the `--json` output all read
+ * from one list.
+ */
+export declare const EXPORT_FORMATS: readonly ["md", "pdf"];
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+/**
+ * Writes one export beside the already-written HTML report, sharing its
+ * timestamp stem — `review-<stamp>.md` next to `review-<stamp>.html` — so a
+ * run's outputs sort and pair by name. Derived from the report's path rather
+ * than a second `reportTimestamp()` call, which could cross a millisecond
+ * boundary and split one run's files across two stems. Takes the report path
+ * as its anchor deliberately: an export cannot be written when no report
+ * was, the same rule `review` in `../cli.ts` applies to nonzero-exit runs.
+ */
+export declare function writeExport(reportPath: string, format: ExportFormat, content: string | Buffer): Promise<string>;
+/**
+ * The subset of a `ChildProcess` the opener touches — `on("error", ...)` and
+ * `unref()` — so a test can inject a stand-in that never launches a real
+ * process without also implementing the rest of `ChildProcess`'s surface.
+ * `spawn`'s real return value satisfies this structurally.
+ */
+export interface OpenedProcess {
+    on(event: "error", listener: (err: Error) => void): void;
+    unref(): void;
+}
+/** The subset of `child_process.spawn` the opener needs. */
+export type SpawnFn = (command: string, args: readonly string[], options: {
+    detached: boolean;
+    stdio: "ignore";
+}) => OpenedProcess;
+/**
+ * Opens a written report with the platform's default handler. A no-op when
+ * no report was written — see test/report/write.test.ts, "is a no-op when
+ * no report was written".
+ *
+ * Detached and unreferenced so the opener's own lifetime never holds the CLI
+ * process open waiting for it, and given an `error` listener for the same
+ * reason: an unhandled `error` on a `ChildProcess` — the opener binary
+ * missing, most likely — would otherwise surface as an uncaught exception
+ * in a process that has already finished its own work.
+ */
+export declare function openReport(path: string | undefined, spawnFn?: SpawnFn): void;

package/dist/report/write.js

@@ -0,0 +1,160 @@
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { git } from "../extract/git.js";
+import { REPORT_DIR } from "../types.js";
+/**
+ * Filesystem-safe, lexicographically sortable timestamp for a report's
+ * filename. `Date#toISOString` already sorts lexicographically in step with
+ * time — fixed field widths, most-significant field first, UTC so there is
+ * no offset to compare across — but a colon is one of the handful of
+ * characters Windows forbids in a filename, and `toISOString` puts two of
+ * them in the time-of-day. Substituting a hyphen keeps every other property
+ * of the format and loses none of its sort order, since a hyphen still sorts
+ * before every digit in ASCII.
+ */
+export function reportTimestamp(date = new Date()) {
+    return date.toISOString().replace(/:/g, "-");
+}
+/**
+ * `git check-ignore` distinguishes a match from a non-match by exit status,
+ * not by output — with `-q` it prints nothing either way. The exit status
+ * this function reads as "no rule matched" is not an error, just the
+ * negative answer; anything else (a repository problem, for instance) is a
+ * real failure and must propagate rather than be read as "not ignored".
+ */
+function meansNotIgnored(err) {
+    return err instanceof Error && "code" in err && err.code === 1;
+}
+/**
+ * Whether the reviewed repository already ignores `.urtext/`, read-only.
+ * urtext writes into the repository it is reviewing, but it must never edit
+ * a file the repository's owner tracks — a diff review tool that patches
+ * your .gitignore to tidy up after itself has changed the very thing it was
+ * asked to look at, and the next review of the working tree would report
+ * that change as if the user had made it. The caller decides what to do
+ * with a `false` result (see `review` in `cli.ts`, which prints a one-line
+ * suggestion rather than acting on it).
+ *
+ * Delegated to `git check-ignore` rather than reading and pattern-matching
+ * `.gitignore` directly: a repository can also exclude a path through
+ * `.git/info/exclude`, a user's global `core.excludesFile`, or a glob like
+ * `**\/.urtext/` that a root-only `.gitignore` read would never recognise as
+ * covering it — git already resolves all of those into one answer, so
+ * re-deriving a subset of that logic here would only reproduce it worse.
+ *
+ * The query names a file inside the directory, not the directory itself. On
+ * git for Windows, a CRLF-encoded `.gitignore` whose blank lines are a bare
+ * carriage return makes `check-ignore` match ANY query ending in a slash
+ * against one of those blank lines — the first real repository this tool
+ * reviewed answered "ignored" for a directory nothing ignored, and the tip
+ * was silently withheld. A child path never ends in a slash, so it is immune;
+ * and because a directory pattern like `.urtext/` covers everything beneath
+ * it, the child matches every pattern shape that covers the directory —
+ * whether or not either of them exists on disk. The probe file is never
+ * created; it exists only as a question.
+ */
+export async function isUrtextGitignored(root) {
+    try {
+        await git(["check-ignore", "-q", `${REPORT_DIR}/probe`], root);
+        return true;
+    }
+    catch (err) {
+        if (meansNotIgnored(err))
+            return false;
+        throw err;
+    }
+}
+/**
+ * Whether `review` in `../cli.ts` should print its gitignore tip. Distinct
+ * from `isUrtextGitignored`, whose propagate-real-failures contract is right
+ * for a function answering a question about the repository — but wrong for
+ * this call site: the tip is printed after the review has succeeded and the
+ * report is on disk, so a git failure here (a repository gone bad between
+ * the review and this last lookup) used to reject the whole `review()` call
+ * — discarding the completed terminal output while leaving a report on disk
+ * beside a nonzero exit, the exact disagreement this module's write path is
+ * designed to avoid. A tip that cannot be verified is simply not offered.
+ */
+export async function shouldSuggestGitignore(root) {
+    try {
+        return !(await isUrtextGitignored(root));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Writes the rendered report under the repository root, not `process.cwd()`
+ * — `urtext review` must land the file in the same place whether it runs at
+ * the root or three directories down, and only the root is stable across
+ * both. See test/cli.test.ts, "writes the report under the repository
+ * root, whether invoked from the root or a subdirectory".
+ */
+export async function writeReport(root, html) {
+    const dir = join(root, REPORT_DIR);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `review-${reportTimestamp()}.html`);
+    await writeFile(path, html, "utf8");
+    return path;
+}
+/**
+ * Every format `--export` can write, in the order the flag's usage copy
+ * names them. Owned beside the writer so the parser in `../cli.ts`, the
+ * writer below, and the `exportPaths` keys in the `--json` output all read
+ * from one list.
+ */
+export const EXPORT_FORMATS = ["md", "pdf"];
+/**
+ * Writes one export beside the already-written HTML report, sharing its
+ * timestamp stem — `review-<stamp>.md` next to `review-<stamp>.html` — so a
+ * run's outputs sort and pair by name. Derived from the report's path rather
+ * than a second `reportTimestamp()` call, which could cross a millisecond
+ * boundary and split one run's files across two stems. Takes the report path
+ * as its anchor deliberately: an export cannot be written when no report
+ * was, the same rule `review` in `../cli.ts` applies to nonzero-exit runs.
+ */
+export async function writeExport(reportPath, format, content) {
+    const path = reportPath.replace(/\.html$/, `.${format}`);
+    await writeFile(path, content);
+    return path;
+}
+function openerCommand(path) {
+    if (process.platform === "win32") {
+        // Not `cmd /c start`: `cmd.exe` re-tokenizes its own already-built
+        // command line by shell rules, under which `&`, `|`, `<`, and `>` are
+        // operators rather than path characters — a repository rooted at
+        // `C:\R&D\...` produced a report path that opened fine up to the `&`
+        // and then ran whatever followed it as a second command. `rundll32` is
+        // launched directly, with no shell in between: Node builds the child's
+        // command line without cmd, and neither `CreateProcess` nor rundll32's
+        // own tail parsing treats `&`, `|`, `<`, or `>` as operators — rundll32
+        // hands everything after the entry-point name to `FileProtocolHandler`
+        // as one raw string. `url.dll,FileProtocolHandler` is the standard
+        // entry point for "open this with whatever the shell would open it
+        // with", for a local path exactly as much as for a URL.
+        return { command: "rundll32", args: ["url.dll,FileProtocolHandler", path] };
+    }
+    if (process.platform === "darwin")
+        return { command: "open", args: [path] };
+    return { command: "xdg-open", args: [path] };
+}
+/**
+ * Opens a written report with the platform's default handler. A no-op when
+ * no report was written — see test/report/write.test.ts, "is a no-op when
+ * no report was written".
+ *
+ * Detached and unreferenced so the opener's own lifetime never holds the CLI
+ * process open waiting for it, and given an `error` listener for the same
+ * reason: an unhandled `error` on a `ChildProcess` — the opener binary
+ * missing, most likely — would otherwise surface as an uncaught exception
+ * in a process that has already finished its own work.
+ */
+export function openReport(path, spawnFn = spawn) {
+    if (!path)
+        return;
+    const { command, args } = openerCommand(path);
+    const child = spawnFn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => { });
+    child.unref();
+}

package/dist/score/index.d.ts

@@ -0,0 +1,94 @@
+import type { Claim, Fact, Finding, Tier } from "../types.js";
+/**
+ * Tunable in one place on purpose: these weights will need adjusting once
+ * they have been run against real diffs.
+ */
+export declare const WEIGHTS: {
+    factKind: {
+        guard_removed: number;
+        signature_changed: number;
+        export_removed: number;
+        effect_added: number;
+        blast_radius: number;
+        export_added: number;
+        effect_removed: number;
+        citation_rot: number;
+    };
+    effect: {
+        network: number;
+        database: number;
+        process: number;
+        filesystem: number;
+        env: number;
+        timing: number;
+    };
+};
+export declare function scoreFact(fact: Fact): number;
+/**
+ * The lowest score any real analyzer fact can produce, across every fact
+ * kind and — for the two effect kinds, whose score also depends on which
+ * effect fired — every effect. Computed by actually calling `scoreFact` on
+ * a synthetic fact of each shape, not by reading `WEIGHTS.factKind` and
+ * taking its minimum directly: that minimum (shared by `blast_radius` and
+ * `effect_removed`) is a real, producible score — `effect_removed` ×
+ * `network` or `database` reaches it exactly, and so does `blast_radius` at
+ * one reference — but it is not the *lowest* producible score. `scoreFact`
+ * also multiplies `effect_removed`'s (and `effect_added`'s) base by an
+ * effect weight that can sit below `network`/`database`'s (`timing` is the
+ * lowest), which takes `effect_removed` down further still — a score
+ * `WEIGHTS.factKind` has no entry for,
+ * because it only lists each kind's base, not what the formula built on top
+ * of that base can still produce. Calling `scoreFact` directly means this
+ * tracks the real formula (the effect multiplier, the blast_radius log
+ * curve) instead of a hand-copied table that cannot see below its own
+ * bases. `reconcile.ts` derives `MODEL_CEILING` from this, so a claim can
+ * never be scored above the weakest thing an analyzer can find.
+ */
+export declare function minPossibleAnalyzerScore(): number;
+/**
+ * The evidence tier for a finding, from what produced it.
+ *
+ * - `verified` — an analyzer found it and can point at the code.
+ * - `inferred` — the model explained something an analyzer found. The fact
+ *   is still true; the *explanation* is the model's, so the finding is only
+ *   as good as that explanation.
+ * - `model` — the model alone. Nothing mechanical corroborates it.
+ *
+ * A fact always beats a claim: if there is a fact, the tier can never be
+ * `model`, because something machine-checked is underneath it.
+ */
+export declare function tierFor(fact: Fact | undefined, claim: Claim | undefined): Tier;
+/**
+ * Longest signature text, in code points, that a finding body renders
+ * verbatim on either side of a was→now sentence. Deliberately far below
+ * `MAX_SIGNATURE_LENGTH` (the storage cap in `../analyze/surface.ts`): that
+ * one bounds what a fact *carries*, this one bounds what a sentence *shows*.
+ * The first dogfood run printed a JWT-sized string literal verbatim into a
+ * body, which both drowned the sentence and republished a secret-looking
+ * literal in a report — the middle-truncated rendering is readability plus
+ * soft redaction. Nothing is hidden from a reader who wants the full text:
+ * it remains in the diff itself, at the declaration every such finding
+ * anchors its evidence to. `test/comment-contract.test.ts` derives part of
+ * its forbidden set from this, so comments name it rather than restating
+ * its value.
+ */
+export declare const MAX_RENDERED_SIGNATURE = 120;
+export declare function toFinding(fact: Fact): Finding;
+/**
+ * `rank` plus the map a model claim needs to find a fact that no longer has
+ * a finding of its own: `absorbedBy` maps a folded/grouped fact's id to the
+ * id of the finding that now speaks for it (see `foldReach`,
+ * `groupAddedExports`, and `groupSignatureChanges` — the three places facts
+ * disappear this way). Chained here because a fact can be absorbed twice in
+ * a row — a blast_radius fact folded into an `export_added` or
+ * `signature_changed` sibling whose own finding is then itself collapsed
+ * into its file's group — and only this function, which runs the fold and
+ * both grouping passes itself, sees every step. `reconcile.ts` is the only
+ * caller that needs this; everything else calls `rank`, the one-line
+ * delegate below, which just discards it.
+ */
+export declare function rankWithAbsorption(facts: Fact[]): {
+    findings: Finding[];
+    absorbedBy: Map<string, string>;
+};
+export declare function rank(facts: Fact[]): Finding[];