urtext 0.1.0

package/dist/report/markdown.js

@@ -0,0 +1,168 @@
+import { EMPTY_LENS_COPY, LENSES, location, plainText, } from "./model.js";
+/**
+ * The Markdown surface, a walker over the report model — GitHub-flavored,
+ * written for the places a review gets pasted: PRs, issues, chat, downstream
+ * tools. Every sentence, tier, glyph, lens routing, ordering, and disclosure
+ * rendered here is decided by `buildReportModel`; what this file owns is
+ * format mechanics — headings, blockquote prefixes, and the code fences
+ * around excerpts.
+ *
+ * The escaping policy is deliberately minimal: prose is never entity- or
+ * backslash-escaped, so an author's `*` may render as emphasis — acceptable,
+ * because the text stays legible and unaltered either way, and a report full
+ * of visible backslashes would not. What is never acceptable is untrusted
+ * text becoming document STRUCTURE, and each construct here closes that door
+ * mechanically rather than by escaping: heading and body-paragraph text is
+ * collapsed to one line (a newline would end the heading — or begin a fresh
+ * line free to open any Markdown structure — and promote the rest to
+ * top-level text), blockquote content has every line prefixed so nothing inside can
+ * step out of the quote, and excerpts sit inside fences long enough that no
+ * backtick run they contain can close them — see
+ * `test/report/markdown.test.ts`, "escalates the fence past any backtick run
+ * in the excerpt". Concealment arrives from the model as segments; this flat
+ * surface joins them through `plainText`, which brackets each label, and a
+ * bracketed label with no `(` after it is literal text to Markdown.
+ *
+ * Unlike the HTML — whose narrative pane repeats every finding and whose
+ * filtered panes show some twice — this surface is a linear document, so it
+ * partitions: each finding appears exactly once, under its own `lens`, in
+ * model order. The model's walker rule allows precisely this (see
+ * `ReportModel.findings`: a walker "may group by `lens` or `subject` but
+ * preserves this order within a group and may never drop a finding"), and
+ * `test/report/markdown.test.ts`, "never drops a finding: every headline the
+ * model carries appears exactly once", pins it. `ReachView` site lists are
+ * this surface's one density cut, exactly as they are the terminal's: a
+ * standalone reach finding's title and body already state the reference
+ * count, and the full site list stays on the HTML surface a reader opens for
+ * depth.
+ */
+/** The floor under every fence; escalation only ever adds to it. */
+const MIN_FENCE = 3;
+/**
+ * Collapses text to one line. Headings need it because a raw newline would
+ * end the heading early. Body paragraphs need it for the inverse reason: a
+ * newline mid-paragraph begins a fresh line, and a fresh line is free to
+ * open any Markdown structure — a heading, a blockquote, a fence — turning
+ * paragraph prose into document skeleton. Upstream happens to compose
+ * bodies single-line today (`typeToString` emits one line), but nothing
+ * pins that, so the door is closed here, mechanically, like every other
+ * construct's. A space is the right joiner because a paragraph is one
+ * block by definition: whatever soft wrapping the text carried, it reads
+ * as one flow. See `test/report/markdown.test.ts`, "keeps a newline inside
+ * a body paragraph from starting a Markdown structure line".
+ */
+function inline(text) {
+    return text.replace(/\s*\r?\n\s*/g, " ");
+}
+/**
+ * Paragraphs as one blockquote, every line prefixed and a bare marker
+ * between paragraphs — so no line of model-carried text, whatever it starts
+ * with, can render outside the quote it was attributed under.
+ */
+function quote(paragraphs) {
+    return paragraphs
+        .filter((p) => p !== "")
+        .map((p) => p
+        .split(/\r?\n/)
+        .map((line) => `> ${line}`.trimEnd())
+        .join("\n"))
+        .join("\n>\n");
+}
+/** The fence info string: TypeScript's two extensions, else none — the whole table the spec names. */
+function language(file) {
+    if (file.endsWith(".tsx"))
+        return "tsx";
+    if (file.endsWith(".ts"))
+        return "ts";
+    return "";
+}
+/**
+ * A fence one backtick longer than the longest run inside the excerpt, never
+ * shorter than MIN_FENCE. The excerpt is the one place this document quotes
+ * text an adversary can author outright, and a run matching the fence would
+ * close the block early — promoting the rest of the excerpt from quoted code
+ * to live Markdown, headings and all.
+ */
+function fenceFor(code) {
+    let longest = 0;
+    for (const run of code.match(/`+/g) ?? []) {
+        longest = Math.max(longest, run.length);
+    }
+    return "`".repeat(Math.max(MIN_FENCE, longest + 1));
+}
+function evidenceBlocks(ref) {
+    const code = plainText(ref.excerpt);
+    const fence = fenceFor(code);
+    return [location(ref), `${fence}${language(ref.file)}\n${code}\n${fence}`];
+}
+/**
+ * The only way model-authored text reaches this document: one blockquote
+ * whose first line is the attribution, then the prose, then the trust
+ * caveat. All three come from the one `ModelNoteView` (see `./model.js`,
+ * where their inseparability is argued), so there is no code path that
+ * renders one without the others. Like the HTML and unlike the terminal,
+ * the block is not gated on a recorded model name — a model-tier finding's
+ * whole body is model prose, and suppressing it would leave a headline with
+ * nothing under it, so the model's UNNAMED_MODEL fallback attribution shows
+ * instead, visibly incomplete rather than absent.
+ */
+function modelNoteQuote(note) {
+    return quote([`unverified · ${note.model}`, plainText(note.text), note.caution]);
+}
+function findingBlocks(finding) {
+    const blocks = [
+        `### ${finding.glyph} ${inline(plainText(finding.headline))} [${finding.tier}]` +
+            (finding.beyondIntent ? ` (${finding.beyondIntent})` : ""),
+    ];
+    // One walk covers every tier: a model-tier finding arrives with no body
+    // paragraphs and its whole prose in `modelNote`, an inferred finding keeps
+    // its analyzer paragraphs and carries the claim's reasoning beside them,
+    // and a claim-free finding has no note at all.
+    for (const paragraph of finding.body) {
+        blocks.push(inline(plainText(paragraph)));
+    }
+    if (finding.modelNote) {
+        blocks.push(modelNoteQuote(finding.modelNote));
+    }
+    for (const ref of finding.evidence) {
+        blocks.push(...evidenceBlocks(ref));
+    }
+    return blocks;
+}
+export function renderMarkdown(model) {
+    const blocks = ["# urtext review", model.scope];
+    // The disclosures, every one, ahead of the first lens heading: a reader
+    // has to know what the review could not see before reading the list and
+    // concluding nothing else was found. Blockquotes, so they read as the
+    // report speaking about itself, set apart from the findings.
+    if (model.provenance) {
+        blocks.push(quote([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.
+        blocks.push(quote(["**This review is partial.**", ...model.notes]));
+    }
+    if (model.coverageNote) {
+        blocks.push(quote([model.coverageNote]));
+    }
+    if (model.filterNote) {
+        blocks.push(quote([model.filterNote]));
+    }
+    if (model.beyondIntentLegend) {
+        blocks.push(quote([model.beyondIntentLegend]));
+    }
+    for (const { key, label } of LENSES) {
+        blocks.push(`## ${label}`);
+        const inLens = model.findings.filter((f) => f.lens === key);
+        if (inLens.length === 0) {
+            blocks.push(EMPTY_LENS_COPY);
+            continue;
+        }
+        for (const finding of inLens) {
+            blocks.push(...findingBlocks(finding));
+        }
+    }
+    return blocks.filter((b) => b !== "").join("\n\n") + "\n";
+}

package/dist/report/model.d.ts

@@ -0,0 +1,303 @@
+import { type ConcealSegment } from "./conceal.js";
+import type { Changeset, Finding, Tier } from "../types.js";
+export { plainText } from "./conceal.js";
+export type { ConcealSegment } from "./conceal.js";
+/**
+ * The one report model every output surface walks. The terminal and HTML
+ * renderers each walked the findings themselves and shared honesty copy
+ * piecemeal, and two drift bugs shipped from exactly that split — the
+ * terminal missing the concealment defense the HTML had, and the HTML
+ * missing the filter disclosure the terminal had. Everything a surface may
+ * say about *content* — which findings, in what order, at what tier, with
+ * which disclosures — is decided here, once; a renderer applies format
+ * mechanics (escaping, wrapping, typesetting) and its own phrasing of the
+ * same truth, never a decision of its own.
+ *
+ * Concealment happens here, while the model is built, and it is structural:
+ * content-bearing fields are `ConcealSegment` arrays in which a concealed
+ * character is a segment of its own, so a walker can style it without ever
+ * parsing labels back out of flattened text — a flattened label cannot be
+ * told apart from source code that literally spells it. Identifier-shaped
+ * fields (file paths, the range label, the coverage note, warnings, the
+ * model name) stay `labelConcealed` strings, a ruled exception recorded in
+ * the design spec's addendum. Either way no raw concealing character
+ * survives into the model — see `test/report/model.test.ts`, "carries no
+ * raw concealing character anywhere: titles, bodies, headlines, file paths,
+ * the range label, warnings, the model name, and the coverage note". Where
+ * a sentence is shared verbatim by the existing surfaces it is composed
+ * here (or reached through `./coverage.js`, which keeps its composing
+ * functions); where the surfaces phrase one truth differently, the model
+ * carries the pieces and each walker keeps its phrasing.
+ */
+export interface ReportMeta {
+    model?: string;
+    /**
+     * Every reason this run fell short of its full pipeline, in the order they
+     * happened: a dead analyzer, a skipped interpretation stage, a report that
+     * could not be written. One list, because they are one thing to a reader —
+     * and because a second field for the skipped stage meant `review` in
+     * `../cli.ts` filled both and the banner printed that line twice.
+     */
+    warnings: string[];
+    /**
+     * How many claim-free standalone reach rows reconcile's filter removed.
+     * Not folded into `warnings`: the filter running as designed is not a
+     * shortfall, and its disclosure must not trip the "This review is
+     * partial." banner. Composed into `ReportModel.filterNote` with
+     * `suppressionNote`, the same sentence both surfaces print.
+     */
+    suppressed?: number;
+}
+export type Lens = "narrative" | "effects" | "surface";
+/**
+ * What a finding is about — finer than `Lens`, and carried beside it because
+ * the HTML report needs the distinction the lens alone erases: its effects
+ * pane splits "effect" from "guard" into separate sections and shows
+ * "surface" findings a second time under Contracts. See
+ * `test/report/model.test.ts`, "keeps the finer subject beside the lens, so
+ * a walker can split effects from guards and show contracts in both panes".
+ * "reach" and "citation" have no filtered lens of their own — a standalone
+ * reach finding and a citation finding each appear in the narrative only,
+ * which the effects pane's note says out loud.
+ */
+export type Subject = "effect" | "guard" | "surface" | "reach" | "citation";
+export interface EvidenceView {
+    file: string;
+    line: number;
+    /**
+     * Concealment-segmented source text; flat surfaces join it with
+     * `plainText`, and renderers add only format escaping.
+     */
+    excerpt: ConcealSegment[];
+    /**
+     * Which revision `line` counts in, copied from `EvidenceRef`: a before-side
+     * line very often points somewhere unrelated in the working tree, and every
+     * surface owes the reader that warning. Omitted means the after side.
+     */
+    side?: "before" | "after";
+}
+export interface ReachView {
+    /** Deduped count, exactly as rank computed it. */
+    references: number;
+    /** Deduped sites, capped at REACH_SITES_SHOWN exactly as the HTML is today. */
+    sites: EvidenceView[];
+    /** Count of collected-but-not-shown sites. */
+    overflow: number;
+}
+export interface ModelNoteView {
+    /** Never empty: an unnamed model renders as UNNAMED_MODEL, the existing fallback copy. */
+    model: string;
+    /** The model's prose, concealment-segmented. */
+    text: ConcealSegment[];
+    /**
+     * The trust caveat rendered with the prose — which of the two fixed
+     * sentences depends on whether the prose stands alone or explains an
+     * analyzer's finding. Carried in the note rather than chosen by a
+     * renderer, so no surface can pick the weaker caveat for the stronger
+     * claim.
+     */
+    caution: string;
+}
+export interface FindingView {
+    id: string;
+    tier: Tier;
+    /** TIER_GLYPH[tier], chosen here, once. */
+    glyph: string;
+    /** Kind-prefix routing lives here, once. */
+    lens: Lens;
+    /** See `Subject`; absent for a standalone model claim or an unprefixed id. */
+    subject?: Subject;
+    /**
+     * `file:line — title`, with a before-side anchor marked — segmented from
+     * the raw composition, so a concealing character in the path or title is
+     * a segment here even though `file` below is a flattened string. Joined
+     * with `plainText` it reads exactly as the terminal prints it. The pieces
+     * below let the HTML compose its own split headline without re-deciding
+     * any of them.
+     */
+    headline: ConcealSegment[];
+    /** Concealment-segmented title, lowercase-led as `toFinding` composes it. */
+    title: ConcealSegment[];
+    file: string;
+    line: number;
+    /**
+     * The anchor's side, from the first evidence ref — a fact's file and line
+     * are derived from that ref (see `makeFact`), so its side annotation
+     * applies to the headline too. A model-tier finding carries no evidence
+     * and no side, which is correct rather than incidental: its location is
+     * the model's own, in the after revision.
+     */
+    side?: "before" | "after";
+    /**
+     * Analyzer-authored paragraphs, each concealment-segmented. Empty for a
+     * model-tier finding: its whole body is model prose, and all model prose
+     * lives in `modelNote` so no surface can render it without attribution —
+     * see `test/report/model.test.ts`, "moves model-tier prose into the
+     * attributed model note, leaving no bare body".
+     */
+    body: ConcealSegment[][];
+    /** Prose and attribution inseparable, as today. */
+    modelNote?: ModelNoteView;
+    /**
+     * Every ref, uncapped: the HTML shows all of them. The terminal's
+     * shorter list is presentation density, applied by that walker.
+     */
+    evidence: EvidenceView[];
+    reach?: ReachView;
+    /**
+     * BEYOND_INTENT_MARK, present only when the claim behind this finding set
+     * `beyondIntent`. Carries the words rather than a boolean so no renderer
+     * composes them; absent or the mark, never a "not marked" string. See
+     * `test/report/model.test.ts`, "carries the mark's words, composed here so
+     * no renderer composes them".
+     */
+    beyondIntent?: string;
+}
+export interface ReportModel {
+    /** "44 files, 2384 lines changed · vs master" — the terminal's wording. */
+    scope: string;
+    /** The scope pieces, for the HTML's own phrasing of the same numbers. */
+    fileCount: number;
+    /** Insertions and deletions both: summing only the after side reported nothing changed for a pure deletion. */
+    lineCount: number;
+    rangeLabel: string;
+    counts: {
+        verified: number;
+        inferred: number;
+        model: number;
+    };
+    /**
+     * Present only under the gate both surfaces use today: a model name AND at
+     * least one inferred/model finding. A tier badge asserts a machine looked,
+     * and that assertion is only checkable if the reader knows which machine.
+     * See `test/report/model.test.ts`, "gates provenance on a model name AND a
+     * model-derived tier".
+     */
+    provenance?: string;
+    /**
+     * The recorded model name, labeled, absent when the run never named one.
+     * Deliberately carried beside the gated `provenance`: the terminal
+     * suppresses claim prose entirely when no model is named, and a walker
+     * cannot apply that gate from `provenance` alone once every finding is
+     * verified.
+     */
+    modelName?: string;
+    /**
+     * Every reason the review fell short, in order — analyzer failures,
+     * skipped interpretation, then the untracked-file note. Non-empty means
+     * the surface must say the review is partial.
+     */
+    notes: string[];
+    /**
+     * The deleted-file coverage note from `deletedFilesNote`; absent when no
+     * TypeScript file was deleted. Deliberately NOT in `notes`: deleting a
+     * TypeScript file is routine, and a partial-review banner that fires on
+     * every such diff is a banner a reader learns to skip. See
+     * `test/report/model.test.ts`, "carries each disclosure exactly once, in
+     * the field renderers must read it from".
+     */
+    coverageNote?: string;
+    /**
+     * Composed by `suppressionNote`; absent when nothing was suppressed.
+     * Deliberately NOT in `notes`: the filter running as designed is not a
+     * shortfall and must not trip partial-review copy.
+     */
+    filterNote?: string;
+    /**
+     * BEYOND_INTENT_MEANING, present exactly when at least one finding carries
+     * the mark. Deliberately NOT in `notes`: a badge doing its job is not a
+     * shortfall, and it must not trip partial-review copy — the same rule
+     * `filterNote` and `coverageNote` are separate fields for. See
+     * `test/report/model.test.ts`, "keeps the legend out of notes, so a badge
+     * doing its job never trips partial-review copy".
+     */
+    beyondIntentLegend?: string;
+    /**
+     * In rank order; renderers must not reorder — see
+     * `test/report/model.test.ts`, "preserves rank order exactly". A walker
+     * may group by `lens` or `subject` but preserves this order within a
+     * group and may never drop a finding.
+     */
+    findings: FindingView[];
+}
+/**
+ * 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 declare const TIER_ORDER: readonly ["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 declare const LENSES: readonly [{
+    readonly key: "narrative";
+    readonly label: "Narrative";
+}, {
+    readonly key: "effects";
+    readonly label: "Effects & contracts";
+}, {
+    readonly key: "surface";
+    readonly 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 declare 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 declare 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 declare function location(ref: {
+    file: string;
+    line: number;
+    side?: "before" | "after";
+}): string;
+/** The badge every surface shows on a marked finding. Composed here, once. */
+export declare 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 declare const BEYOND_INTENT_MEANING = "\u201Cbeyond stated intent\u201D 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 declare const TIER_GLYPH: Record<Tier, string>;
+/** The tier's display word — "model-only", not the bare tier value, where a reader sees it. */
+export declare const TIER_WORD: Record<Tier, string>;
+export declare const TIER_MEANING: Record<Tier, string>;
+/**
+ * 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 declare const UNNAMED_MODEL = "an unnamed model";
+/** The caveat beside prose the model authored with no fact underneath it. */
+export declare 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 declare 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 declare const REACH_SITES_SHOWN = 5;
+export declare function buildReportModel(changeset: Changeset, findings: Finding[], meta: ReportMeta): ReportModel;