urtext 0.1.0

package/dist/interpret/schema.d.ts

@@ -0,0 +1,74 @@
+import type { Claim } from "../types.js";
+/**
+ * The response shape the model's structured output must satisfy. Constrained
+ * rather than free prose because the output is merged with analyzer facts in
+ * `reconcile`, and a claim that cannot be attached to a fact or placed in a
+ * file is not usable there.
+ */
+export declare const CLAIMS_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly claims: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly file: {
+                        readonly type: "string";
+                        readonly description: "Repo-relative path this claim is about.";
+                    };
+                    readonly line: {
+                        readonly type: "integer";
+                        readonly description: "1-based line in that file.";
+                    };
+                    readonly summary: {
+                        readonly type: "string";
+                        readonly description: "One sentence. The finding headline.";
+                    };
+                    readonly reasoning: {
+                        readonly type: "string";
+                        readonly description: "Why it matters, in one or two sentences.";
+                    };
+                    readonly severity: {
+                        readonly type: "number";
+                        readonly description: "0..1. How much this should worry a reviewer.";
+                    };
+                    readonly correspondsTo: {
+                        readonly type: "string";
+                        readonly description: "The id of the analyzer fact this explains, when it explains one. Omit for an observation the analyzers did not make.";
+                    };
+                    readonly beyondIntent: {
+                        readonly type: "boolean";
+                        readonly description: "True when this change does something the stated intent does not account for. Only meaningful when a `Stated intent` block was given above; omit it otherwise, and omit it rather than guessing.";
+                    };
+                };
+                readonly required: readonly ["file", "line", "summary", "reasoning", "severity"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: readonly ["claims"];
+    readonly additionalProperties: false;
+};
+/**
+ * Validates and coerces model output into `Claim[]`. Throws on the whole
+ * response — rather than keeping whatever claims happened to parse — when
+ * any single claim is malformed: a partially-parsed set is indistinguishable
+ * from a complete one to `reconcile`, and the tier system's value rests on
+ * knowing exactly what the model said. See
+ * `test/interpret/schema.test.ts`, "rejects the whole response when one
+ * claim among several is malformed".
+ *
+ * `severity` and `line` are coerced rather than rejected when out of range.
+ * `severity` is zeroed on non-finite input (matching, deliberately, what
+ * `reconcile.clampSeverity` independently does to the same value) before
+ * being clamped to 0..1 — the two layers must agree here, because a value
+ * that slipped past this one by mapping `Infinity` to the top of that range
+ * would hand a claim the top of the model tier, the exact outcome
+ * `clampSeverity`'s own non-finite guard exists to prevent. `line` has no
+ * second guard downstream, so an
+ * invalid, non-finite, or non-positive value is repaired here to the first
+ * line instead of propagating a value `reconcile` and the renderer both
+ * assume is a real line number.
+ */
+export declare function parseClaims(text: string): Claim[];

package/dist/interpret/schema.js

@@ -0,0 +1,103 @@
+/**
+ * The response shape the model's structured output must satisfy. Constrained
+ * rather than free prose because the output is merged with analyzer facts in
+ * `reconcile`, and a claim that cannot be attached to a fact or placed in a
+ * file is not usable there.
+ */
+export const CLAIMS_SCHEMA = {
+    type: "object",
+    properties: {
+        claims: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    file: { type: "string", description: "Repo-relative path this claim is about." },
+                    line: { type: "integer", description: "1-based line in that file." },
+                    summary: { type: "string", description: "One sentence. The finding headline." },
+                    reasoning: { type: "string", description: "Why it matters, in one or two sentences." },
+                    severity: { type: "number", description: "0..1. How much this should worry a reviewer." },
+                    correspondsTo: {
+                        type: "string",
+                        description: "The id of the analyzer fact this explains, when it explains one. Omit for an observation the analyzers did not make.",
+                    },
+                    beyondIntent: {
+                        type: "boolean",
+                        description: "True when this change does something the stated intent does not account for. Only meaningful when a `Stated intent` block was given above; omit it otherwise, and omit it rather than guessing.",
+                    },
+                },
+                required: ["file", "line", "summary", "reasoning", "severity"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["claims"],
+    additionalProperties: false,
+};
+/**
+ * Validates and coerces model output into `Claim[]`. Throws on the whole
+ * response — rather than keeping whatever claims happened to parse — when
+ * any single claim is malformed: a partially-parsed set is indistinguishable
+ * from a complete one to `reconcile`, and the tier system's value rests on
+ * knowing exactly what the model said. See
+ * `test/interpret/schema.test.ts`, "rejects the whole response when one
+ * claim among several is malformed".
+ *
+ * `severity` and `line` are coerced rather than rejected when out of range.
+ * `severity` is zeroed on non-finite input (matching, deliberately, what
+ * `reconcile.clampSeverity` independently does to the same value) before
+ * being clamped to 0..1 — the two layers must agree here, because a value
+ * that slipped past this one by mapping `Infinity` to the top of that range
+ * would hand a claim the top of the model tier, the exact outcome
+ * `clampSeverity`'s own non-finite guard exists to prevent. `line` has no
+ * second guard downstream, so an
+ * invalid, non-finite, or non-positive value is repaired here to the first
+ * line instead of propagating a value `reconcile` and the renderer both
+ * assume is a real line number.
+ */
+export function parseClaims(text) {
+    const raw = JSON.parse(text);
+    if (typeof raw !== "object" || raw === null || !("claims" in raw)) {
+        throw new Error("interpretation response has no `claims` array");
+    }
+    const list = raw.claims;
+    if (!Array.isArray(list))
+        throw new Error("`claims` is not an array");
+    return list.map((item, i) => {
+        if (typeof item !== "object" || item === null) {
+            throw new Error(`claim ${i} is not an object`);
+        }
+        const c = item;
+        const str = (k) => {
+            const v = c[k];
+            if (typeof v !== "string" || v.length === 0) {
+                throw new Error(`claim ${i}: \`${k}\` must be a non-empty string`);
+            }
+            return v;
+        };
+        const severity = typeof c.severity === "number" && Number.isFinite(c.severity) ? c.severity : 0;
+        return {
+            id: `m${i + 1}`,
+            file: str("file"),
+            // Math.max after the floor, not a positivity guard before it: a
+            // fractional line between zero and one passes such a guard and then
+            // floors to zero, a line that does not exist under the 1-based
+            // contract.
+            line: typeof c.line === "number" && Number.isFinite(c.line)
+                ? Math.max(1, Math.floor(c.line))
+                : 1,
+            summary: str("summary"),
+            reasoning: str("reasoning"),
+            severity: Math.min(Math.max(severity, 0), 1),
+            correspondsTo: typeof c.correspondsTo === "string" ? c.correspondsTo : undefined,
+            // Strict `true` only, and deliberately not truthiness: this field puts an
+            // accusation in front of a reader, so nothing but the exact affirmative earns
+            // it. A string "true", a numeral, or a null is a malformed answer, and the
+            // honest repair for a malformed answer is the quiet default — the same
+            // direction `line` and `severity` are repaired in, toward the value that
+            // cannot mislead. See `test/interpret/schema.test.ts`, "marks a claim only on
+            // a literal boolean true".
+            beyondIntent: c.beyondIntent === true ? true : undefined,
+        };
+    });
+}

package/dist/report/conceal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The concealing-character defense, shared by both report surfaces. It lived
+ * in `html.ts` first, which left the terminal — the *default* surface —
+ * printing the same hostile bytes raw: a Trojan-source excerpt could be shown
+ * to a terminal reader, under a `[verified]` badge, in an order it does not
+ * execute in. One table and one substitution, so the surfaces cannot drift:
+ * `buildReportModel` in `./model.ts` applies it to every content field while
+ * the model is built (structurally via `segmentConcealed`, or as
+ * `labelConcealed` strings for identifier-shaped fields), and `html.ts`
+ * builds its `visible` wrapper — the symbol table's scoped renderer-side
+ * exception — from `conceals` and `codePointLabel`.
+ */
+export declare function conceals(code: number): boolean;
+export declare function codePointLabel(code: number): string;
+/**
+ * One piece of a segmented text: either a verbatim run of ordinary
+ * characters, or the label standing in for exactly one concealed character.
+ * For a `"concealed"` segment, `text` is the bare code-point label
+ * (`U+202E`, no brackets): the HTML report wraps it in its own markup while
+ * flat surfaces bracket it through `plainText`, and neither has to parse the
+ * other's rendering back apart.
+ *
+ * The raw character is dropped rather than kept beside the label. Copying an
+ * excerpt out of a report should not carry an invisible payload with it, and
+ * a reader who needs the original bytes has the file and line printed right
+ * above.
+ */
+export interface ConcealSegment {
+    kind: "text" | "concealed";
+    text: string;
+}
+/**
+ * The segmenting primitive under every surface's concealment defense: each
+ * concealing character becomes its own `"concealed"` segment and everything
+ * between them stays one verbatim `"text"` run. The distinction is
+ * structural rather than in-band because a flattened label cannot be told
+ * apart from source code that literally spells it — a walker parsing
+ * `[U+202E]` back out of plain text would style an attacker-written literal
+ * as a concealed character. See `test/report/conceal.test.ts`, "leaves a
+ * source-written label literal as ordinary text".
+ *
+ * The ranges are written as code points rather than as a character class in
+ * a regular expression literal, because a literal would mean putting the
+ * very characters this defends against into this file, where the next
+ * reader cannot see them either.
+ */
+export declare function segmentConcealed(text: string): ConcealSegment[];
+/**
+ * Flattens segments for a surface that cannot mark concealment structurally
+ * (terminal, Markdown, PDF): text runs verbatim, each concealed label in
+ * brackets — `[U+202E]`. By construction this reproduces exactly what
+ * `labelConcealed` says about the same input; see
+ * `test/report/conceal.test.ts`, "reproduces exactly the string
+ * labelConcealed produces, for any input".
+ */
+export declare function plainText(segments: ConcealSegment[]): string;
+/**
+ * Plain text with every concealing character replaced by a bracketed label
+ * of its own code point — `[U+202E]` — and everything else kept verbatim.
+ * Built on the segmenting primitive above so the flattened and structural
+ * forms cannot disagree about what was concealed.
+ */
+export declare function labelConcealed(text: string): string;

package/dist/report/conceal.js

@@ -0,0 +1,129 @@
+/**
+ * The concealing-character defense, shared by both report surfaces. It lived
+ * in `html.ts` first, which left the terminal — the *default* surface —
+ * printing the same hostile bytes raw: a Trojan-source excerpt could be shown
+ * to a terminal reader, under a `[verified]` badge, in an order it does not
+ * execute in. One table and one substitution, so the surfaces cannot drift:
+ * `buildReportModel` in `./model.ts` applies it to every content field while
+ * the model is built (structurally via `segmentConcealed`, or as
+ * `labelConcealed` strings for identifier-shaped fields), and `html.ts`
+ * builds its `visible` wrapper — the symbol table's scoped renderer-side
+ * exception — from `conceals` and `codePointLabel`.
+ */
+/**
+ * Characters that render as something other than themselves, or as nothing
+ * at all: the bidirectional overrides and isolates a Trojan Source attack
+ * uses to make a line of code display in an order it does not execute in,
+ * the zero-width and joining characters that can hide inside an identifier,
+ * the characters of both control blocks, and the Tag block — deprecated for
+ * its original purpose and now the standard way to smuggle an entire ASCII
+ * string through a surface that renders nothing for it. Tab and newline are
+ * excluded: they are layout in a code excerpt, not concealment.
+ *
+ * This matters more here than in most renderers. The whole promise of a
+ * `verified` finding is "here is the line, look at it yourself", and an
+ * excerpt that displays differently from the bytes it quotes breaks exactly
+ * that promise — the reader checks the evidence and is shown something
+ * else. See `test/report/html.test.ts`, "shows a bidi override in an
+ * excerpt rather than obeying it".
+ *
+ * What this table deliberately does not cover, so that the next reader knows
+ * where it stops rather than assuming it stops nowhere:
+ *
+ * - **Variation selectors** — the `U+FE00`–`U+FE0F` block and the Variation
+ *   Selectors Supplement above the Tag block. They can carry a payload the
+ *   same way tag characters can, but `U+FE0F` is load-bearing for ordinary
+ *   emoji presentation and the supplement encodes legitimate ideographic
+ *   variants, so labelling them would corrupt real content in a string
+ *   literal or a comment. They are also the weakest of these channels: a
+ *   variation selector cannot reorder the text around it or hide another
+ *   character — it can only hold data for a decoder that is already
+ *   co-operating. The trade lands the other way for the Tag block, whose
+ *   only surviving legitimate use is the subdivision-flag emoji sequences;
+ *   an excerpt containing one of those will render its base character
+ *   followed by tag labels, and that is a cost worth paying in source code.
+ * - **Confusables** — a Cyrillic small a (U+0430) standing in for Latin `a`,
+ *   a non-breaking space for a space, curly quotes for straight ones. Those
+ *   are visible characters that look like *other visible characters*, which
+ *   is a different problem needing a confusables table and a policy about
+ *   which scripts an identifier may mix. The rule here is narrower and
+ *   checkable: a character belongs in this table when it renders as nothing,
+ *   or changes the order of what surrounds it.
+ */
+const CONCEALING_RANGES = [
+    [0x00, 0x08],
+    [0x0b, 0x0c],
+    [0x0e, 0x1f],
+    [0x7f, 0x9f],
+    [0xad, 0xad],
+    [0x61c, 0x61c],
+    [0x200b, 0x200f],
+    [0x2028, 0x202e],
+    [0x2060, 0x2064],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+    [0xe0000, 0xe007f],
+];
+export function conceals(code) {
+    return CONCEALING_RANGES.some(([lo, hi]) => code >= lo && code <= hi);
+}
+export function codePointLabel(code) {
+    return `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+/**
+ * The segmenting primitive under every surface's concealment defense: each
+ * concealing character becomes its own `"concealed"` segment and everything
+ * between them stays one verbatim `"text"` run. The distinction is
+ * structural rather than in-band because a flattened label cannot be told
+ * apart from source code that literally spells it — a walker parsing
+ * `[U+202E]` back out of plain text would style an attacker-written literal
+ * as a concealed character. See `test/report/conceal.test.ts`, "leaves a
+ * source-written label literal as ordinary text".
+ *
+ * The ranges are written as code points rather than as a character class in
+ * a regular expression literal, because a literal would mean putting the
+ * very characters this defends against into this file, where the next
+ * reader cannot see them either.
+ */
+export function segmentConcealed(text) {
+    const segments = [];
+    let run = "";
+    for (const ch of text) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (conceals(code)) {
+            if (run) {
+                segments.push({ kind: "text", text: run });
+                run = "";
+            }
+            segments.push({ kind: "concealed", text: codePointLabel(code) });
+        }
+        else {
+            run += ch;
+        }
+    }
+    if (run)
+        segments.push({ kind: "text", text: run });
+    return segments;
+}
+/**
+ * Flattens segments for a surface that cannot mark concealment structurally
+ * (terminal, Markdown, PDF): text runs verbatim, each concealed label in
+ * brackets — `[U+202E]`. By construction this reproduces exactly what
+ * `labelConcealed` says about the same input; see
+ * `test/report/conceal.test.ts`, "reproduces exactly the string
+ * labelConcealed produces, for any input".
+ */
+export function plainText(segments) {
+    return segments
+        .map((s) => (s.kind === "concealed" ? `[${s.text}]` : s.text))
+        .join("");
+}
+/**
+ * Plain text with every concealing character replaced by a bracketed label
+ * of its own code point — `[U+202E]` — and everything else kept verbatim.
+ * Built on the segmenting primitive above so the flattened and structural
+ * forms cannot disagree about what was concealed.
+ */
+export function labelConcealed(text) {
+    return plainText(segmentConcealed(text));
+}

package/dist/report/coverage.d.ts

@@ -0,0 +1,43 @@
+import type { Changeset } from "../types.js";
+/**
+ * What the analyzers did not look at, stated the same way on all three
+ * surfaces: the terminal's note, the HTML report's header, and `--json`'s
+ * `coverage` field, which `review` in `../cli.ts` fills from here. `--json`
+ * carried nothing at all until it did, so the one consumer that cannot read
+ * prose was the one left blind to the gap.
+ *
+ * Lives in its own module because both renderers need it and neither may import
+ * the other, and because a sentence making a claim about analyzer coverage has
+ * to be checked in one place — the copy that lived in both renderers was wrong
+ * in both.
+ */
+/** Deleted TypeScript files in this range, in the order the diff listed them. */
+export declare function deletedTypeScriptFiles(changeset: Changeset): string[];
+/**
+ * What a reader is owed about a deleted TypeScript file, and no more than is
+ * true. `guardsAnalyzer` and `surfaceAnalyzer` skip a file whose status is
+ * "deleted", `blastRadiusAnalyzer` skips it too, and `mapSymbols` returns no
+ * symbols for one — so its exports, its callers, and its guards go unexamined,
+ * and without a word about it a reader cannot tell that gap from "nothing in it
+ * was worth reporting".
+ *
+ * `effectsAnalyzer` is the exception and the reason this sentence was rewritten:
+ * it reads the before side of a deletion on purpose (see the `file.status !==
+ * "deleted"` condition on its unreadable-after-side guard) and reports every
+ * effect kind that vanished with the file. The earlier wording — "every
+ * analyzer skips a deleted file, so nothing below describes what it contained"
+ * — could therefore print directly above a `verified` finding about that exact
+ * file, telling a reviewer to disregard a real one. See
+ * `test/report/coverage.test.ts`.
+ *
+ * Naming a path reports coverage; it asserts nothing about the deleted code.
+ */
+export declare function deletedFilesNote(paths: string[]): string;
+/**
+ * The one sentence disclosing reconcile's standalone-reach filter, shared by
+ * the terminal and HTML renderers so the two surfaces cannot drift apart —
+ * the same single-source rule `deletedFilesNote` above exists for. The copy
+ * is filter-shaped: it says what was removed from this report and why the
+ * filter fired, not anything about the code under review.
+ */
+export declare function suppressionNote(count: number): string;

package/dist/report/coverage.js

@@ -0,0 +1,56 @@
+import { isTypeScriptFile } from "../extract/symbols.js";
+/**
+ * What the analyzers did not look at, stated the same way on all three
+ * surfaces: the terminal's note, the HTML report's header, and `--json`'s
+ * `coverage` field, which `review` in `../cli.ts` fills from here. `--json`
+ * carried nothing at all until it did, so the one consumer that cannot read
+ * prose was the one left blind to the gap.
+ *
+ * Lives in its own module because both renderers need it and neither may import
+ * the other, and because a sentence making a claim about analyzer coverage has
+ * to be checked in one place — the copy that lived in both renderers was wrong
+ * in both.
+ */
+/** Deleted TypeScript files in this range, in the order the diff listed them. */
+export function deletedTypeScriptFiles(changeset) {
+    return changeset.files
+        .filter((f) => f.status === "deleted" && isTypeScriptFile(f.path))
+        .map((f) => f.path);
+}
+/**
+ * What a reader is owed about a deleted TypeScript file, and no more than is
+ * true. `guardsAnalyzer` and `surfaceAnalyzer` skip a file whose status is
+ * "deleted", `blastRadiusAnalyzer` skips it too, and `mapSymbols` returns no
+ * symbols for one — so its exports, its callers, and its guards go unexamined,
+ * and without a word about it a reader cannot tell that gap from "nothing in it
+ * was worth reporting".
+ *
+ * `effectsAnalyzer` is the exception and the reason this sentence was rewritten:
+ * it reads the before side of a deletion on purpose (see the `file.status !==
+ * "deleted"` condition on its unreadable-after-side guard) and reports every
+ * effect kind that vanished with the file. The earlier wording — "every
+ * analyzer skips a deleted file, so nothing below describes what it contained"
+ * — could therefore print directly above a `verified` finding about that exact
+ * file, telling a reviewer to disregard a real one. See
+ * `test/report/coverage.test.ts`.
+ *
+ * Naming a path reports coverage; it asserts nothing about the deleted code.
+ */
+export function deletedFilesNote(paths) {
+    const count = paths.length === 1
+        ? "1 deleted TypeScript file"
+        : `${paths.length} deleted TypeScript files`;
+    const subject = paths.length === 1 ? "it" : "them";
+    const possessive = paths.length === 1 ? "its" : "their";
+    return `${count}: ${paths.join(", ")} — only effects that vanished with ${subject} are reported; ${possessive} exports, callers, and guards are not analyzed.`;
+}
+/**
+ * The one sentence disclosing reconcile's standalone-reach filter, shared by
+ * the terminal and HTML renderers so the two surfaces cannot drift apart —
+ * the same single-source rule `deletedFilesNote` above exists for. The copy
+ * is filter-shaped: it says what was removed from this report and why the
+ * filter fired, not anything about the code under review.
+ */
+export function suppressionNote(count) {
+    return `Filtered: ${count} finding${count === 1 ? "" : "s"} suppressed (low-signal: single unclaimed reference).`;
+}

package/dist/report/html.d.ts

@@ -0,0 +1,4 @@
+import type { Changeset, Finding } from "../types.js";
+import type { ReportMeta } from "./model.js";
+export type { ReportMeta } from "./model.js";
+export declare function renderHtml(changeset: Changeset, findings: Finding[], meta: ReportMeta): string;