urtext 0.1.0

package/dist/report/model.js

@@ -0,0 +1,289 @@
+import { labelConcealed, segmentConcealed } from "./conceal.js";
+import { deletedFilesNote, deletedTypeScriptFiles, suppressionNote } from "./coverage.js";
+// Flat surfaces (terminal, Markdown, PDF) join segmented fields through
+// `plainText` and never re-derive concealment themselves; re-exported here
+// so a walker needs only this module to walk the model.
+export { plainText } from "./conceal.js";
+/**
+ * The order every surface lists the tiers in: strongest evidence first.
+ * Owned here so no walker can shuffle its counts, chips, or legend into a
+ * sequence the other surfaces do not use.
+ */
+export const TIER_ORDER = ["verified", "inferred", "model"];
+/**
+ * The lens display order and headings, owned here for the same reason
+ * `TIER_ORDER` owns the tier sequence: the HTML's tab strip and the
+ * Markdown's section headings both read from this one constant, and two
+ * walkers with private copies of an order are two orders waiting to diverge.
+ */
+export const LENSES = [
+    { key: "narrative", label: "Narrative" },
+    { key: "effects", label: "Effects & contracts" },
+    { key: "surface", label: "API surface" },
+];
+/**
+ * What an empty lens says: a sentence about the filter, never about the
+ * code. A lens is a view over findings the model classified by id prefix,
+ * and if that classification ever stops matching what the analyzers emit,
+ * the empty pane is what a user sees — so it must not be able to claim
+ * nothing changed while a removed guard sits ranked first elsewhere in the
+ * report. Shared by the HTML's empty effects pane and the Markdown's empty
+ * sections; a surface may append its own pointer to where the findings are,
+ * but the filter-shaped sentence itself is single-sourced here.
+ */
+export const EMPTY_LENS_COPY = "Nothing in this range matched this view.";
+/**
+ * What a findings-free run says — one sentence about the analyzers, never
+ * about the code being fine. Shared by the surfaces that state it whole (the
+ * terminal and the PDF); the Markdown has no single no-findings line, its
+ * lens sections each carry EMPTY_LENS_COPY instead. Owned here for the same
+ * reason as EMPTY_LENS_COPY: two walkers with private copies of a sentence
+ * are two sentences waiting to diverge.
+ */
+export const NO_FINDINGS_COPY = "No findings. Nothing in this change tripped an analyzer.";
+/**
+ * `path:line`, or `path:line (before)` when the line number counts in the
+ * before revision rather than the working tree — see `EvidenceView.side`
+ * for why the reader is owed that marker. Shared by the flat surfaces
+ * (terminal, Markdown, PDF), which had verbatim private copies; the HTML
+ * composes its own marked-up location and is deliberately not a consumer.
+ */
+export function location(ref) {
+    return `${ref.file}:${ref.line}${ref.side === "before" ? " (before)" : ""}`;
+}
+/** The badge every surface shows on a marked finding. Composed here, once. */
+export const BEYOND_INTENT_MARK = "beyond stated intent";
+/**
+ * What the badge means, stated once per report rather than once per finding.
+ * Names the commit messages as the source and says what the comparison is not,
+ * because the badge alone reads stronger than the evidence behind it.
+ */
+export const BEYOND_INTENT_MEANING = "“beyond stated intent” means the commit messages in this range do not account for what the change does there. It compares the change against its own description, not against anything a person actually asked for.";
+/** The marks both surfaces already print, kept identical so every surface reads as one tool. */
+export const TIER_GLYPH = {
+    verified: "▲",
+    inferred: "●",
+    model: "○",
+};
+/** The tier's display word — "model-only", not the bare tier value, where a reader sees it. */
+export const TIER_WORD = {
+    verified: "verified",
+    inferred: "inferred",
+    model: "model-only",
+};
+export const TIER_MEANING = {
+    verified: "an analyzer found this and can point at the code",
+    inferred: "an analyzer found it; the explanation is the model's",
+    model: "the model alone — nothing mechanical corroborates it",
+};
+/**
+ * The name attached to model prose when the run recorded none. A run that
+ * produced model-tier findings without a model name is a bug upstream, not a
+ * licence to show the prose bare: the fallback keeps the attribution present
+ * and visibly incomplete rather than absent.
+ */
+export const UNNAMED_MODEL = "an unnamed model";
+/** The caveat beside prose the model authored with no fact underneath it. */
+export const MODEL_CAUTION_STANDALONE = "Nothing mechanical corroborates this. Treat it as a lead to check, not a result.";
+/** The caveat beside a claim's explanation of an analyzer's finding. */
+export const MODEL_CAUTION_CLAIM = "The finding above is an analyzer's. This explanation of why it matters is not.";
+/** How many referencing sites a finding lists before it stops listing them. */
+export const REACH_SITES_SHOWN = 5;
+/** The id `groupAddedExports` gives the finding that replaces a file's added-export findings. */
+const EXPORT_GROUP_PREFIX = "export_added_group";
+/** The id `groupSignatureChanges` gives the finding that replaces a file's signature_changed findings. */
+const SIGNATURE_GROUP_PREFIX = "signature_changed_group";
+/**
+ * Total over `FactKind` — `satisfies` makes a new kind a compile error here
+ * rather than a finding that silently falls out of every lens, unnoticed
+ * because nothing names it.
+ */
+const SUBJECT_OF_KIND = {
+    effect_added: "effect",
+    effect_removed: "effect",
+    guard_removed: "guard",
+    export_added: "surface",
+    export_removed: "surface",
+    signature_changed: "surface",
+    blast_radius: "reach",
+    citation_rot: "citation",
+};
+/**
+ * Recovered from the finding's id, not from its prose. Every fact id begins
+ * with its `FactKind` and a colon (see `makeFact`'s callers), and the
+ * grouping passes key on the same convention — classifying on a title's
+ * wording instead would tie every surface to sentences `toFinding` is free
+ * to rewrite.
+ *
+ * A standalone model claim has no subject: `reconcile` prefixes those ids
+ * with `claim:`, which matches no kind. That is the intended outcome, not a
+ * gap — the filtered lenses show what analyzers proved, and the model's own
+ * claims have nothing mechanical behind them to classify.
+ *
+ * The convention itself is pinned against real analyzer output, not against
+ * hand-written ids, by `test/report/html.test.ts`, "every id a real analyzer
+ * produces starts with its own fact kind" — a fixture written to match the
+ * code cannot notice the code changing.
+ */
+function subjectOf(id) {
+    const colon = id.indexOf(":");
+    // An id with no colon has no kind prefix at all. Slicing to what `indexOf`
+    // returns when it finds nothing would instead drop the id's last character
+    // and hand back a near-miss that can still match a kind — the one case
+    // this function exists to reject. See `test/report/model.test.ts`, "sends
+    // an id with no colon to the narrative alone".
+    if (colon < 0)
+        return undefined;
+    const prefix = id.slice(0, colon);
+    if (prefix === EXPORT_GROUP_PREFIX || prefix === SIGNATURE_GROUP_PREFIX)
+        return "surface";
+    return Object.hasOwn(SUBJECT_OF_KIND, prefix)
+        ? SUBJECT_OF_KIND[prefix]
+        : undefined;
+}
+/**
+ * The lens a subject's findings are gathered under. Effects and guards share
+ * a pane (as two sections); surface findings have their own; a standalone
+ * reach finding and a citation finding each belong to no filtered pane and
+ * live in the narrative, which shows every finding regardless of lens. A
+ * rotted citation is not an effect, not a guard, and not a change to the
+ * public surface: it belongs to the account of what this change did, which
+ * is what the narrative is.
+ */
+const LENS_OF_SUBJECT = {
+    effect: "effects",
+    guard: "effects",
+    surface: "surface",
+    reach: "narrative",
+    citation: "narrative",
+};
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function toEvidenceView(ref) {
+    const view = {
+        file: labelConcealed(ref.file),
+        line: ref.line,
+        excerpt: segmentConcealed(ref.excerpt),
+    };
+    if (ref.side)
+        view.side = ref.side;
+    return view;
+}
+function toFindingView(finding, modelName) {
+    const subject = subjectOf(finding.id);
+    const lens = subject ? LENS_OF_SUBJECT[subject] : "narrative";
+    // A fact-derived finding has its file:line derived from the first evidence
+    // ref (see `makeFact`), so that ref's side annotation applies to the
+    // headline too. A model-tier finding carries no evidence at all, so
+    // `side` stays undefined and no marker is composed — correctly, since
+    // there is no before-side line to warn about.
+    const side = finding.evidence[0]?.side;
+    const file = labelConcealed(finding.file);
+    const title = segmentConcealed(finding.title);
+    // Segmented from the RAW composition — not assembled out of the flattened
+    // `file` string — so a concealing character in the path stays structural
+    // inside the headline even though the standalone `file` field flattens it.
+    const headline = segmentConcealed(`${finding.file}:${finding.line}${side === "before" ? " (before)" : ""} — ${finding.title}`);
+    const attribution = modelName ?? UNNAMED_MODEL;
+    // All model-authored prose flows through `modelNote`, whose attribution is
+    // built into the same object — there is no field a walker can read model
+    // prose from without also holding the model's name and the caution. A
+    // model-tier finding's whole body is the model's; an inferred finding
+    // keeps its analyzer body and carries the claim's reasoning beside it.
+    const modelNote = finding.tier === "model"
+        ? {
+            model: attribution,
+            text: segmentConcealed(finding.body),
+            caution: MODEL_CAUTION_STANDALONE,
+        }
+        : finding.claim
+            ? {
+                model: attribution,
+                text: segmentConcealed(finding.claim.reasoning),
+                caution: MODEL_CAUTION_CLAIM,
+            }
+            : undefined;
+    const body = finding.tier === "model" ? [] : [segmentConcealed(finding.body)];
+    // Reach sites are a sample even before this cap — the analyzer bounds what
+    // it collects while counting every reference — so `references` and the
+    // site list are reported apart rather than as "N of M". The cap itself is
+    // pinned by `test/report/model.test.ts`, "caps reach sites as the HTML
+    // report does and counts the overflow".
+    const reach = finding.reach && finding.reach.sites.length > 0
+        ? {
+            references: finding.reach.references,
+            sites: finding.reach.sites.slice(0, REACH_SITES_SHOWN).map(toEvidenceView),
+            overflow: Math.max(finding.reach.sites.length - REACH_SITES_SHOWN, 0),
+        }
+        : undefined;
+    const view = {
+        id: finding.id,
+        tier: finding.tier,
+        glyph: TIER_GLYPH[finding.tier],
+        lens,
+        headline,
+        title,
+        file,
+        line: finding.line,
+        body,
+        evidence: finding.evidence.map(toEvidenceView),
+    };
+    if (subject)
+        view.subject = subject;
+    if (side)
+        view.side = side;
+    if (modelNote)
+        view.modelNote = modelNote;
+    if (reach)
+        view.reach = reach;
+    if (finding.beyondIntent)
+        view.beyondIntent = BEYOND_INTENT_MARK;
+    return view;
+}
+export function buildReportModel(changeset, findings, meta) {
+    const fileCount = changeset.files.length;
+    const lineCount = changeset.files.reduce((n, f) => n + f.hunks.reduce((m, h) => m + h.newLines + h.oldLines, 0), 0);
+    const rangeLabel = labelConcealed(changeset.range.label);
+    const scope = `${plural(fileCount, "file")}, ${plural(lineCount, "line")} changed · ${rangeLabel}`;
+    const counts = { verified: 0, inferred: 0, model: 0 };
+    for (const f of findings)
+        counts[f.tier]++;
+    // An empty model name is treated as no name: `InterpretResult.model` is
+    // empty when the stage was skipped, and naming an empty string would
+    // attribute a stage that never ran.
+    const modelName = meta.model ? labelConcealed(meta.model) : undefined;
+    const provenance = modelName && (counts.inferred > 0 || counts.model > 0)
+        ? `${modelName} interpreted this change.`
+        : undefined;
+    const notes = meta.warnings.map(labelConcealed);
+    const untracked = changeset.untrackedCount ?? 0;
+    if (untracked > 0) {
+        notes.push(`${plural(untracked, "untracked file")} not reviewed — git diff does not include them.`);
+    }
+    const deleted = deletedTypeScriptFiles(changeset);
+    const coverageNote = deleted.length > 0 ? labelConcealed(deletedFilesNote(deleted)) : undefined;
+    const suppressed = meta.suppressed ?? 0;
+    const filterNote = suppressed > 0 ? suppressionNote(suppressed) : undefined;
+    const model = {
+        scope,
+        fileCount,
+        lineCount,
+        rangeLabel,
+        counts,
+        notes,
+        findings: findings.map((f) => toFindingView(f, modelName)),
+    };
+    if (provenance)
+        model.provenance = provenance;
+    if (modelName)
+        model.modelName = modelName;
+    if (coverageNote)
+        model.coverageNote = coverageNote;
+    if (filterNote)
+        model.filterNote = filterNote;
+    if (model.findings.some((f) => f.beyondIntent)) {
+        model.beyondIntentLegend = BEYOND_INTENT_MEANING;
+    }
+    return model;
+}

package/dist/report/pdf.d.ts

@@ -0,0 +1,2 @@
+import { type ReportModel } from "./model.js";
+export declare function renderPdf(model: ReportModel): Promise<Buffer>;

package/dist/report/pdf.js

@@ -0,0 +1,217 @@
+import { fileURLToPath } from "node:url";
+import { LENSES, location, NO_FINDINGS_COPY, plainText, TIER_ORDER, TIER_WORD, } from "./model.js";
+/**
+ * The PDF surface, a walker over the report model — the client-presentable
+ * document, set in the SOW house style this project ports from
+ * a sibling project's exporter. Every sentence, tier, glyph, ordering, and
+ * disclosure rendered here is decided by `buildReportModel`; what this file
+ * owns is typesetting — fonts, sizes, the rule, the footer, and where the
+ * gray goes. Concealment arrives from the model as segments; this flat
+ * surface joins them through `plainText` and renders the labels verbatim.
+ *
+ * pdfkit is loaded inside `renderPdf` with a dynamic `import()` and nowhere
+ * else, so a run that never asks for a PDF never loads it — pinned by
+ * `test/report/pdf.test.ts`, "imports pdfkit dynamically and nowhere
+ * statically", which reads this file's source.
+ *
+ * Unlike the HTML's lens tabs and the Markdown's lens sections, this surface
+ * is one numbered list in model order — a client reads a single ranked
+ * document, with each finding's lens shown as a small caption rather than a
+ * grouping. The model's walker rule allows this (order is preserved, nothing
+ * is dropped), and `test/report/pdf.test.ts`, "renders every finding across
+ * pages — none silently truncated", pins it across page breaks. `ReachView`
+ * site lists are this surface's one density cut, exactly as they are the
+ * terminal's and the Markdown's: a reach finding's body already states the
+ * reference count, and the full site list stays on the HTML surface.
+ */
+/**
+ * The embedded DejaVu family, committed under `fonts/` and shipped in the
+ * npm package so the renderer works wherever the package is installed. The
+ * accepted coverage trade: DejaVu covers Latin, Cyrillic, and Greek broadly,
+ * but not CJK or other scripts — full-Unicode fonts cost tens of megabytes.
+ */
+const FONT_FILES = {
+    sans: "DejaVuSans.ttf",
+    bold: "DejaVuSans-Bold.ttf",
+    oblique: "DejaVuSans-Oblique.ttf",
+    mono: "DejaVuSansMono.ttf",
+};
+/** Registered-font names, one per file in `FONT_FILES`. */
+const SANS = "urtext-sans";
+const BOLD = "urtext-sans-bold";
+const OBLIQUE = "urtext-sans-oblique";
+const MONO = "urtext-mono";
+/**
+ * Resolved relative to this module, so the same path works from `src/report/`
+ * under tsx and from `dist/report/` in an installed package — both sit one
+ * directory tree beside `fonts/`.
+ */
+function fontPath(file) {
+    return fileURLToPath(new URL(`../../fonts/${file}`, import.meta.url));
+}
+const MARGIN = 54;
+const TITLE_SIZE = 20;
+const HEADING_SIZE = 13;
+const BODY_SIZE = 11;
+const META_SIZE = 10;
+const CAPTION_SIZE = 9;
+const FOOTER_SIZE = 8;
+/** Where the footer baseline sits, measured up from the page's bottom edge. */
+const FOOTER_RISE = 36;
+const GRAY = "#666666";
+const BLACK = "#000000";
+/** The one sentence every page's footer carries, beside the page number. */
+const FOOTER_LINE = "Generated by urtext — every finding is labeled by its evidence tier";
+const LENS_LABEL = new Map(LENSES.map((l) => [l.key, l.label]));
+/** A bold-label/value meta line, the SOW house style's header idiom. */
+function metaLine(doc, label, value) {
+    doc
+        .font(BOLD)
+        .fontSize(META_SIZE)
+        .text(`${label}: `, { continued: true })
+        .font(SANS)
+        .text(value);
+}
+/**
+ * A whole-line bold disclosure. The honesty-critical lines — "This review is
+ * partial.", every `notes` entry, the filter note — all pass through here,
+ * so no restyling can quiet one of them without quieting the style itself.
+ */
+function strongLine(doc, text) {
+    doc.font(BOLD).fontSize(META_SIZE).text(text);
+}
+function rule(doc) {
+    const y = doc.y;
+    doc
+        .moveTo(MARGIN, y)
+        .lineTo(doc.page.width - MARGIN, y)
+        .stroke();
+    doc.moveDown();
+}
+/**
+ * The only way model-authored text reaches this document: the attribution
+ * line, then the prose, then the trust caveat, all from the one
+ * `ModelNoteView` (see `./model.js`, where their inseparability is argued).
+ * Like the HTML and the Markdown, not gated on a recorded model name: the
+ * model's UNNAMED_MODEL fallback attribution shows instead, visibly
+ * incomplete rather than absent.
+ */
+function modelNoteBlock(doc, note) {
+    doc.font(OBLIQUE).fontSize(META_SIZE).text(`unverified · ${note.model}`);
+    doc.font(SANS).fontSize(BODY_SIZE).text(plainText(note.text));
+    doc.font(OBLIQUE).fontSize(META_SIZE).text(note.caution);
+}
+function evidenceBlock(doc, ref) {
+    doc.font(OBLIQUE).fontSize(CAPTION_SIZE).fillColor(GRAY).text(location(ref)).fillColor(BLACK);
+    doc.font(MONO).fontSize(CAPTION_SIZE).text(plainText(ref.excerpt));
+    doc.moveDown(0.5);
+}
+function findingSection(doc, finding, ordinal) {
+    doc
+        .font(BOLD)
+        .fontSize(HEADING_SIZE)
+        .text(`${ordinal}. ${finding.glyph} ${plainText(finding.headline)} [${finding.tier}]` +
+        (finding.beyondIntent ? ` (${finding.beyondIntent})` : ""));
+    doc
+        .font(SANS)
+        .fontSize(CAPTION_SIZE)
+        .fillColor(GRAY)
+        .text(LENS_LABEL.get(finding.lens) ?? finding.lens)
+        .fillColor(BLACK);
+    doc.moveDown(0.5);
+    for (const paragraph of finding.body) {
+        doc.font(SANS).fontSize(BODY_SIZE).text(plainText(paragraph));
+        doc.moveDown(0.5);
+    }
+    if (finding.modelNote) {
+        modelNoteBlock(doc, finding.modelNote);
+        doc.moveDown(0.5);
+    }
+    for (const ref of finding.evidence) {
+        evidenceBlock(doc, ref);
+    }
+    doc.moveDown();
+}
+/**
+ * Stamped onto every buffered page once the content is laid out — only then
+ * is the page count known. The bottom margin is zeroed for the duration of
+ * each stamp: pdfkit starts a fresh page for any text that lands inside the
+ * margin, even absolutely positioned text, and a footer that adds a page —
+ * itself footerless — would break "prints the footer on every page" in
+ * `test/report/pdf.test.ts`.
+ */
+function stampFooters(doc) {
+    const range = doc.bufferedPageRange();
+    for (let i = range.start; i < range.start + range.count; i++) {
+        doc.switchToPage(i);
+        const savedBottom = doc.page.margins.bottom;
+        doc.page.margins.bottom = 0;
+        const y = doc.page.height - FOOTER_RISE;
+        doc.font(SANS).fontSize(FOOTER_SIZE).fillColor(GRAY);
+        doc.text(FOOTER_LINE, MARGIN, y, { lineBreak: false });
+        doc.text(String(i + 1), MARGIN, y, {
+            width: doc.page.width - MARGIN * 2,
+            align: "right",
+            lineBreak: false,
+        });
+        doc.fillColor(BLACK);
+        doc.page.margins.bottom = savedBottom;
+    }
+}
+export async function renderPdf(model) {
+    const { default: PDFDocument } = await import("pdfkit");
+    return new Promise((resolve, reject) => {
+        const doc = new PDFDocument({ margin: MARGIN, bufferPages: true });
+        const chunks = [];
+        doc.on("data", (chunk) => chunks.push(chunk));
+        doc.on("end", () => resolve(Buffer.concat(chunks)));
+        doc.on("error", (err) => reject(err));
+        doc.registerFont(SANS, fontPath(FONT_FILES.sans));
+        doc.registerFont(BOLD, fontPath(FONT_FILES.bold));
+        doc.registerFont(OBLIQUE, fontPath(FONT_FILES.oblique));
+        doc.registerFont(MONO, fontPath(FONT_FILES.mono));
+        doc.font(BOLD).fontSize(TITLE_SIZE).text("urtext review");
+        doc.moveDown();
+        metaLine(doc, "Generated", new Date().toISOString().slice(0, 10));
+        metaLine(doc, "Range", model.scope);
+        metaLine(doc, "Model", model.modelName ?? "not asked");
+        metaLine(doc, "Evidence", TIER_ORDER.map((tier) => `${model.counts[tier]} ${TIER_WORD[tier]}`).join(" · "));
+        // The disclosures, every one, before the rule and the list: a reader has
+        // to know what the review could not see before reading the findings and
+        // concluding nothing else was found. Order matches the other surfaces:
+        // provenance, the partial-review notes, coverage, then the filter note.
+        if (model.provenance) {
+            doc.font(SANS).fontSize(META_SIZE).text(model.provenance);
+        }
+        if (model.notes.length > 0) {
+            // Gated on the model's `notes` exactly: non-empty means the review is
+            // partial and this surface must say so, in the same sentence the
+            // HTML's banner leads with.
+            strongLine(doc, "This review is partial.");
+            for (const note of model.notes) {
+                strongLine(doc, note);
+            }
+        }
+        if (model.coverageNote) {
+            doc.font(SANS).fontSize(META_SIZE).text(model.coverageNote);
+        }
+        if (model.filterNote) {
+            strongLine(doc, model.filterNote);
+        }
+        // Whole-line bold, like every honesty-critical line on this surface:
+        // never restyled away.
+        if (model.beyondIntentLegend) {
+            strongLine(doc, model.beyondIntentLegend);
+        }
+        doc.moveDown();
+        rule(doc);
+        if (model.findings.length === 0) {
+            doc.font(SANS).fontSize(BODY_SIZE).text(NO_FINDINGS_COPY);
+        }
+        for (const [index, finding] of model.findings.entries()) {
+            findingSection(doc, finding, index + 1);
+        }
+        stampFooters(doc);
+        doc.end();
+    });
+}

package/dist/report/terminal.d.ts

@@ -0,0 +1,2 @@
+import type { Changeset, Finding } from "../types.js";
+export declare function renderTerminal(changeset: Changeset, findings: Finding[], reportPath?: string, warnings?: string[], model?: string, suppressed?: number): string;