@bigsteele/the-prospect 0.1.1 → 0.3.0

package/dist/report.js

@@ -17,13 +17,17 @@ export function toMarkdown(p) {
     const accidental = p.duplicates.filter((d) => !d.deliberate);
     const highHand = p.handrolled.filter((h) => h.confidence === "high");
     const cuts = p.stack.consolidations;
+    // A category is not a job: pairs the code shows doing different work are
+    // listed under their own heading and never counted as paid twice.
+    const paidTwice = p.overlaps.filter((o) => !o.distinct);
+    const twoJobs = p.overlaps.filter((o) => o.distinct);
     L.push(`# The Prospect: ${p.app}`, "");
     // The headline is an argument, not a metric.
     const claims = [];
     if (noRef.length)
         claims.push(`**${noRef.length} of ${p.totals.runtime_deps}** dependencies show no reference anywhere`);
-    if (p.overlaps.length)
-        claims.push(`**${p.overlaps.length}** job${p.overlaps.length > 1 ? "s are" : " is"} paid for twice`);
+    if (paidTwice.length)
+        claims.push(`**${paidTwice.length}** job${paidTwice.length > 1 ? "s are" : " is"} paid for twice`);
     if (highHand.length)
         claims.push(`**${highHand.length}** subsystem${highHand.length > 1 ? "s" : ""} built by hand where the market sells a rail`);
     if (cuts.length)
@@ -38,29 +42,123 @@ export function toMarkdown(p) {
     else {
         L.push(claims.slice(0, 2).join(", and ") + ".", "");
     }
-    L.push(`## Today / After`, "");
-    L.push(`| Today | After |`);
-    L.push(`| --- | --- |`);
-    if (noRef.length)
-        L.push(`| ${noRef.length} packages installed, updated and audited that nothing imports | They are gone, and every install, update and security audit is smaller |`);
-    if (p.overlaps.length) {
-        const o = p.overlaps[0];
-        L.push(`| ${prose(o.services)} ${o.services.length > 2 ? "all" : "both"} do ${label(o.category)} work | One vendor does it, one invoice, one integration to maintain |`);
+    // NEXT ACTIONS, NOT TODAY/AFTER (0.2). The Big Sean ends every finding with
+    // the workflow it protects, who does it, and how long; the Today/After table
+    // ended with "Suggestions arrive as opinions". A reader acts on the first
+    // shape and skims the second. Only what is NOT on record reaches this list.
+    const actions = [];
+    for (const d of noRef.filter((x) => !x.on_record).slice(0, 3)) {
+        actions.push({
+            what: `\`${d.name}\` is declared in \`${d.manifest}\` and nothing references it`,
+            touches: d.touches ?? "",
+            task: `grep the repository for its name outside \`${d.manifest}\`; if nothing loads it by name at runtime, remove it`,
+            retest: "install, build and run the test suite with it gone",
+        });
     }
-    if (highHand.length) {
-        const h = highHand[0];
-        L.push(`| ${h.loc} lines of hand-rolled ${h.rail} code you maintain alone | A decision on record: keep it on purpose, or a rail carries it |`);
+    for (const o of paidTwice.filter((x) => !x.on_record)) {
+        actions.push({
+            what: `${prose(o.services)} both do ${label(o.category)} work`,
+            touches: "one bill and one failure surface per vendor",
+            task: `name which one carries this job, or record in DECISIONS.md why both stay`,
+            retest: "the next scan lists the pair under On record",
+        });
     }
-    if (cuts.length) {
-        const c = cuts[0];
-        L.push(`| ${c.candidate} runs beside ${c.keep}, which already covers ${c.covers.split(" (")[0]} | One platform, one bill, one place a deploy can fail |`);
+    for (const h of highHand.filter((x) => !x.on_record)) {
+        actions.push({
+            what: `${h.loc} lines of hand-rolled ${h.rail} in \`${h.signal.file}\``,
+            touches: h.touches ?? "",
+            task: "decide once: keep it on purpose and record why, or let a rail carry it (Lane 2 names the rails)",
+            retest: "the decision appears in the record, or the subsystem is gone",
+        });
+    }
+    const bigAccidental = accidental.filter((d) => !d.parallel && !d.on_record).slice(0, 2);
+    for (const d of bigAccidental) {
+        actions.push({
+            what: `${d.lines} lines repeated across ${d.files.length} files, opening \`${d.opens_with.slice(0, 60)}\``,
+            touches: d.touches ?? "",
+            task: "lift to one place, or mark the copy deliberate in its header",
+            retest: "the cluster is gone from the next scan",
+        });
+    }
+    if (actions.length) {
+        L.push(`## Your next actions`, "");
+        L.push(`Only what no recorded decision explains. Each names the workflow it touches - by path, a heuristic - and how to know it is done.`, "");
+        actions.forEach((a, i) => {
+            L.push(`### ${i + 1}. ${a.what}`);
+            L.push(`**Touches.** ${a.touches}`);
+            L.push(`**Task.** ${a.task}`);
+            L.push(`**Retest.** ${a.retest}`, "");
+        });
+    }
+    // ON RECORD. What the scan found and the record already explains. Listed so
+    // the reader sees the tool looked, and charged nothing.
+    const onRecord = [];
+    for (const d of noRef.filter((x) => x.on_record))
+        onRecord.push({ what: `\`${d.name}\` shows no reference`, where: `${d.on_record.file}:${d.on_record.line} - ${d.on_record.excerpt}` });
+    for (const o of paidTwice.filter((x) => x.on_record))
+        onRecord.push({ what: `${prose(o.services)} both do ${label(o.category)} work`, where: `${o.on_record.file}:${o.on_record.line} - ${o.on_record.excerpt}` });
+    for (const c of cuts.filter((x) => x.on_record))
+        onRecord.push({ what: `${c.candidate} beside ${c.keep}`, where: `${c.on_record.file}:${c.on_record.line} - ${c.on_record.excerpt}` });
+    for (const h of highHand.filter((x) => x.on_record))
+        onRecord.push({ what: `hand-rolled ${h.rail}`, where: `${h.on_record.file}:${h.on_record.line} - ${h.on_record.excerpt}` });
+    for (const d of accidental.filter((x) => x.on_record))
+        onRecord.push({ what: `${d.lines} lines shared by ${d.files.map((f) => f.split("/").pop()).join(", ")}`, where: `${d.on_record.file}:${d.on_record.line} - ${d.on_record.excerpt}` });
+    const parallels = p.duplicates.filter((d) => d.parallel);
+    if (onRecord.length || parallels.length) {
+        L.push(`## On record`, "");
+        // Say what the record EXPLAINED, not what was read. An empty table under "already
+        // explained by CHECKPOINT-QUEUE.md" told the owner their notes covered the findings
+        // when they did not - and the gap between what a record holds and what the scan
+        // found is itself the useful fact here.
+        const explainedBy = [...new Set(onRecord.map((r) => r.where.split(":")[0]))];
+        L.push(onRecord.length
+            ? `Found, and already explained by ${explainedBy.slice(0, 3).map((f) => `\`${f}\``).join(", ")}. Nothing here costs points.`
+            : `${p.decisions.files.length} decision file(s) read, ${p.decisions.entries} lines. None explains a finding above: what the scan found is not yet on the record, which is the case for a line in DECISIONS.md rather than a fix.`, "");
+        if (onRecord.length) {
+            L.push(`| Finding | Where it is decided |`, `| --- | --- |`);
+            for (const r of onRecord)
+                L.push(`| ${r.what} | ${r.where.replace(/\|/g, "\\|")} |`);
+            L.push("");
+        }
+        if (parallels.length) {
+            const total = parallels.reduce((t, d) => t + d.lines * (d.files.length - 1), 0);
+            L.push(`${parallels.length} parallel adapter block(s), ${total} lines in total, at the same relative path under sibling adapter directories. A generated file cannot import from the generator, so these duplicate by design; the one question is whether the generator could render them from a single partial.`, "");
+        }
+    }
+    // TWO VENDORS, TWO JOBS. A category shared is not a bill doubled; the code
+    // showed each doing different work. Listed so the reader sees the pair was
+    // weighed, charged nothing, and asked to be written down once.
+    if (twoJobs.length) {
+        L.push(`## Two vendors, two jobs`, "");
+        L.push(`Same category, different work by the look of the code. Not charged. A line in DECISIONS.md naming both keeps the next scan from asking.`, "");
+        for (const o of twoJobs)
+            L.push(`- **${label(o.category)}**: ${o.services.join(" + ")}. ${o.distinct}${o.on_record ? ` On record: ${o.on_record.file}:${o.on_record.line}.` : ""}`);
+        L.push("");
+    }
+    // UNKNOWN. What the scan could not settle, stated rather than scored.
+    const unknowns = [];
+    if (p.north_star.confidence !== "high")
+        unknowns.push(`the North Star: ${p.north_star.note}`);
+    if (!p.decisions.files.length)
+        unknowns.push("whether any of the above is on purpose: no decision record was found (DECISIONS.md, ADRs, CLAUDE.md), so nothing could be marked on record");
+    for (const n of p.profile.not_applicable)
+        unknowns.push(`${n.question}: ${n.why}`);
+    if (unknowns.length) {
+        L.push(`## Unknown`, "");
+        for (const u of unknowns)
+            L.push(`- ${u}`);
+        L.push("");
     }
-    if (p.dead.length)
-        L.push(`| ${p.dead.length} files everyone reads, searches and ships but nothing runs | Deleted, with this report as the receipt |`);
-    L.push(`| Suggestions arrive as opinions | Every suggestion stands on a fact in your code, a sourced fact from your market, and your North Star |`);
-    L.push("");
     L.push(`## Score`, "");
     L.push(`**${p.score.total}/100 (${p.score.grade})** - Level ${p.score.level.n}: **${p.score.level.name}**. ${p.score.level.meaning}`, "");
+    // THE NUMBER NEVER TRAVELS ALONE (0.2). 96/100 on a six-file scraper and
+    // 96/100 on a four-thousand-file monorepo are not the same claim, and the
+    // report used to print them identically.
+    L.push(`_${p.profile.depth.why}_`, "");
+    if (p.score.not_asked.length) {
+        L.push(`**Not asked of this repository:** ${p.score.not_asked.join(", ")}. ` +
+            `Neither credited nor penalised - see What was read.`, "");
+    }
     for (const f of p.score.floors)
         L.push(`- ${f}`);
     if (p.score.floors.length)
@@ -72,6 +170,65 @@ export function toMarkdown(p) {
             L.push(`| ${d.what} | ${d.points} | ${d.evidence} |`);
         L.push("");
     }
+    // THE LEDGER GOES BEFORE THE FINDINGS (0.2). A reader deciding how much to
+    // trust a list of findings needs to know what was looked at to produce it, and
+    // the honest answer used to be unavailable: the scan read 473 of 2,077 files
+    // on the first repository it met and had no way to say so.
+    const c = p.coverage;
+    L.push(`## What was read`, "");
+    const pr = p.profile;
+    L.push(`A ${pr.languages[0] ?? "mixed"} repository` +
+        (pr.languages.length > 1 ? ` (also ${pr.languages.slice(1, 3).join(", ")})` : "") +
+        (pr.manifests.length ? `, declaring dependencies in ${pr.manifests.join(" and ")}` : `, with no dependency manifest found`) +
+        (pr.traits.length ? `. Shapes recognised: ${pr.traits.join(", ")}.` : "."), "");
+    if (pr.not_applicable.length) {
+        L.push(`Questions with no ground to stand on here:`, "");
+        for (const n of pr.not_applicable)
+            L.push(`- **${n.question}** - ${n.why}`);
+        L.push("");
+    }
+    L.push(`**${c.analysed} of ${c.walked} files analysed.** ` +
+        `${c.unreadable} unreadable (binaries and files over the size cap), ` +
+        `${c.walked - c.analysed - c.unreadable} excluded by a named rule, ` +
+        `${c.unaccounted} unaccounted for.`, "");
+    if (c.excluded.length) {
+        L.push(`| Excluded | Files | Why |`);
+        L.push(`| --- | --- | --- |`);
+        for (const e of c.excluded)
+            L.push(`| \`${e.rule}\` | ${e.files} | ${e.why} |`);
+        L.push("");
+    }
+    if (c.unclaimed.length) {
+        L.push(`Readable file classes no question claims. Some of these are right to ignore; ` +
+            `the list is here so the choice is visible rather than assumed.`, "");
+        for (const u of c.unclaimed) {
+            L.push(`- \`${u.ext}\` - ${u.files} files, none analysed (e.g. \`${u.examples[0] ?? ""}\`)`);
+        }
+        L.push("");
+    }
+    const db = p.database;
+    if (db.files > 0) {
+        L.push(`### The database`, "");
+        L.push(`${db.files} migration file(s): ${db.tables} table(s), ${db.policies} policy/policies, ` +
+            `${db.definer_functions} function(s) running as definer` +
+            (db.definer_execute_revoked ? `, ${db.definer_execute_revoked} of them with EXECUTE revoked from public, anon or authenticated in the migrations` : "") +
+            `. ` +
+            (db.guard ? `The repository carries \`${db.guard}\`, which checks the live grants; this scan reads only what the migrations state. ` : "") +
+            (db.findings.length === 0
+                ? `Nothing below stood out.`
+                : `${db.findings.length} shape(s) worth a minute.`), "");
+        if (db.findings.length) {
+            L.push(`| Shape | Subject | Where |`);
+            L.push(`| --- | --- | --- |`);
+            for (const x of db.findings.slice(0, 15)) {
+                L.push(`| ${x.kind.replace(/_/g, " ")} | \`${x.subject}\` | \`${x.file}\` |`);
+            }
+            if (db.findings.length > 15)
+                L.push(`| ...and ${db.findings.length - 15} more | | in the JSON |`);
+            L.push("");
+            L.push(db.findings[0].note, "");
+        }
+    }
     L.push(`## North Star`, "");
     if (p.north_star.sentence) {
         L.push(`> ${p.north_star.sentence}`, "");
@@ -93,9 +250,9 @@ export function toMarkdown(p) {
         L.push("");
         L.push(`A package can earn its keep without an import (a CLI run from a script, a plugin loaded by name at runtime). This table is the list to answer for, not a kill list.`, "");
     }
-    if (p.overlaps.length) {
+    if (paidTwice.length) {
         L.push(`### Jobs paid for twice`, "");
-        for (const o of p.overlaps) {
+        for (const o of paidTwice) {
             L.push(`- **${label(o.category)}**: ${o.services.join(" + ")} (${o.call_sites} call sites). One category of work, ${o.services.length} vendors, ${o.services.length} invoices, ${o.services.length} places a key can leak.`);
         }
         L.push("");
@@ -138,9 +295,11 @@ export function toMarkdown(p) {
     }
     if (p.dead.length) {
         L.push(`### Files no entrypoint reaches`, "");
-        L.push(`From ${p.totals.entrypoints} entrypoints, the import walk never arrived at these. A file loaded by a path built at runtime can still be alive - this is the list to answer for.`, "");
+        const scaffold = p.dead.filter((d) => d.scaffold).length;
+        L.push(`From ${p.totals.entrypoints} entrypoints, the import walk never arrived at these, and no reached file names them by path. A file loaded by a path built at runtime can still be alive - this is the list to answer for.` +
+            (scaffold ? ` ${scaffold} are UI-kit scaffold components (a components.json sits beside them) that no file imports: never bundled, only read and searched, and weighed a quarter.` : ""), "");
         for (const d of p.dead.slice(0, 20))
-            L.push(`- \`${d.file}\` (${d.loc} lines)`);
+            L.push(`- \`${d.file}\` (${d.loc} lines${d.scaffold ? ", scaffold" : ""})`);
         if (p.dead.length > 20)
             L.push(`- …and ${p.dead.length - 20} more in the JSON`);
         L.push("");

package/dist/score.d.ts

@@ -28,6 +28,7 @@ export interface ProspectScore {
         evidence: string;
     }>;
     floors: string[];
+    not_asked: string[];
 }
 export declare function grade(total: number): string;
 export interface ScoreInput {
@@ -41,6 +42,8 @@ export interface ScoreInput {
     consolidations?: ConsolidationFact[];
     /** Total runtime files, for shares. */
     runtime_files: number;
+    /** Questions the repository could not answer; carried through, never scored. */
+    not_asked?: string[];
     /** True when a vendor SDK dependency itself has no reference found - paying for a thing never called. */
     unused_paid_service: string | null;
 }

package/dist/score.js

@@ -29,30 +29,49 @@ const LEVELS = [
     { n: 4, name: "Sharp", meaning: "Nothing unaccounted for: every dependency referenced, every file reached, one vendor per job, and every hand-rolled subsystem is a recorded decision." },
 ];
 export function scoreProspect(input) {
+    // WHAT THE SCORE IS NOT (0.2). A number out of 100 invites the reading "how
+    // healthy is this repository", and across five repositories of different
+    // shapes it was measuring something closer to "how much is here". A six-file
+    // scraper with no manifest, no migrations and nothing duplicated scored 96,
+    // because every question it could not answer returned nothing found, and
+    // nothing found scored as clean.
+    //
+    // The score still measures only what was ASKED. What changes is that the
+    // report now carries the profile beside it, so 96 out of 100 on a thin
+    // reading cannot be mistaken for 96 on a thorough one - and `reading` says
+    // which it is, in the same breath as the number.
     const deductions = [];
     const ding = (what, points, evidence) => {
         if (points > 0)
             deductions.push({ what, points: Math.round(points * 10) / 10, evidence });
     };
     const runtimeDeps = input.deps.filter((d) => !d.dev);
-    const noRef = runtimeDeps.filter((d) => d.no_reference_found);
+    // ON RECORD IS NOT A DEDUCTION (0.2). What the decision record explains was
+    // chosen and written down; charging for it is charging for the choice.
+    const noRef = runtimeDeps.filter((d) => d.no_reference_found && !d.on_record);
     // Unreferenced runtime dependencies: up to 20.
     ding("dependencies with no reference found", Math.min(20, noRef.length * 2), noRef.length ? `${noRef.length} of ${runtimeDeps.length} runtime dependencies` : "");
-    // Files no entrypoint reaches: up to 20, by share of runtime files.
-    const deadShare = input.runtime_files > 0 ? input.dead.length / input.runtime_files : 0;
-    ding("files no entrypoint reaches", Math.min(20, Math.round(deadShare * 100)), input.dead.length ? `${input.dead.length} files (${Math.round(deadShare * 100)} in 100)` : "");
+    // Files no entrypoint reaches: up to 20, by share of runtime files. A UI-kit
+    // scaffold component nothing imports is never bundled, so it weighs a quarter.
+    const dead = input.dead.filter((d) => !d.on_record);
+    const scaffold = dead.filter((d) => d.scaffold).length;
+    const deadWeight = dead.length - scaffold + scaffold / 4;
+    const deadShare = input.runtime_files > 0 ? deadWeight / input.runtime_files : 0;
+    ding("files no entrypoint reaches", Math.min(20, Math.round(deadShare * 100)), dead.length ? `${dead.length} files (${Math.round(deadShare * 100)} in 100${scaffold ? `; ${scaffold} are scaffold components, weighed a quarter` : ""})` : "");
     // Accidental duplicate clusters: up to 20. Deliberate copies cost nothing.
-    const accidental = input.duplicates.filter((d) => !d.deliberate);
+    const accidental = input.duplicates.filter((d) => !d.deliberate && !d.parallel && !d.on_record);
     const dupLines = accidental.reduce((t, d) => t + d.lines * (d.files.length - 1), 0);
     ding("duplicated blocks not marked deliberate", Math.min(20, Math.round(dupLines / 40)), accidental.length ? `${accidental.length} clusters, ${dupLines} repeated lines` : "");
-    // Vendor overlap: up to 20. Two vendors in one category is a doubled bill.
-    ding("two or more vendors doing one job", Math.min(20, input.overlaps.length * 7), input.overlaps.length ? input.overlaps.map((o) => `${o.category}: ${o.services.join(" + ")}`).join("; ") : "");
+    // Vendor overlap: up to 20. Two vendors doing ONE JOB is a doubled bill; two
+    // vendors the code shows doing different jobs inside a category is not (0.2.1).
+    const overlaps = input.overlaps.filter((o) => !o.on_record && !o.distinct);
+    ding("two or more vendors doing one job", Math.min(20, overlaps.length * 7), overlaps.length ? overlaps.map((o) => `${o.category}: ${o.services.join(" + ")}`).join("; ") : "");
     // Hand-rolled where a rail exists: up to 12, high-confidence only.
-    const high = input.handrolled.filter((h) => h.confidence === "high");
+    const high = input.handrolled.filter((h) => h.confidence === "high" && !h.on_record);
     ding("hand-rolled subsystems with rails available", Math.min(12, high.length * 4), high.length ? high.map((h) => h.rail).join(", ") : "");
     // The stack cut: up to 12. A platform another platform already covers is
     // a bill and a failure surface, and nobody decided to have both.
-    const consolidations = input.consolidations ?? [];
+    const consolidations = (input.consolidations ?? []).filter((c) => !c.on_record);
     ding("platforms another platform already covers", Math.min(12, consolidations.length * 4), consolidations.length ? consolidations.map((c) => `${c.candidate} (covered by ${c.keep})`).join("; ") : "");
     // Multiplying cost shapes: up to 8; per-row is the loud one.
     const perRow = input.costs.filter((c) => c.shape === "per-row").length;
@@ -89,5 +108,7 @@ export function scoreProspect(input) {
         level: LEVELS[n],
         deductions: deductions.sort((a, b) => b.points - a.points),
         floors,
+        /** Questions with no ground in this repository, so no points either way. */
+        not_asked: input.not_asked ?? [],
     };
 }

package/dist/verdicts.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The verdicts: what the agent decided about every Step 0 finding, and the
+ * score recomputed from those decisions.
+ *
+ * Step 0 is a deterministic scan, and a deterministic scan is a hypothesis
+ * machine: it reads shapes and prints them. The protocol's first job is to
+ * take every finding to the code and rule on it, one of four ways -
+ * CONFIRMED with evidence, REFUTED with the reason the shape lied, ON_RECORD
+ * with the line that decided it, or UNKNOWN with what would settle it. A
+ * finding no verdict covers is a finding nobody checked, and the gate says so.
+ *
+ * The score then follows the verdicts, not the scan: a refuted finding costs
+ * nothing, a recorded one costs nothing, and the math is printed so the number
+ * can be argued with rather than trusted. Same rule as The Big Sean's
+ * validator: if this and the agent disagree, believe this and fix the file.
+ *
+ * PURE MODULE: no filesystem, no process. The CLI feeds it parsed JSON.
+ */
+import type { Prospect } from "./index.js";
+import { type ProspectScore } from "./score.js";
+export type Verdict = "CONFIRMED" | "REFUTED" | "ON_RECORD" | "UNKNOWN";
+export interface VerdictRecord {
+    /** The finding's id from the scan JSON: dep:zod, overlap:ai, hand:search, dead:src/x.ts, cost:file:line, db:kind:subject, cut:Vercel, dup:1:file */
+    id: string;
+    verdict: Verdict;
+    /** Evidence ids (EV-nn) from the register. Required for CONFIRMED and REFUTED. */
+    evidence?: string[];
+    /** Why - the shape that lied, the record that decided, or what would settle it. */
+    reason?: string;
+    /** For ON_RECORD: the decision line, file:line. */
+    record?: string;
+}
+export interface EvidenceEntry {
+    id: string;
+    /** What was done: the file read, the command run, the page loaded. */
+    what: string;
+    /** Where: file:line, a sanitised command, or a URL. */
+    where: string;
+    /** What was observed, in one line. Secrets and personal data never. */
+    observed: string;
+}
+export interface Verdicts {
+    format: "bigsteele-prospect-verdicts/1";
+    /** The scan these verdicts rule on. */
+    scan?: string;
+    commit?: string;
+    findings: VerdictRecord[];
+    evidence: EvidenceEntry[];
+}
+/** Every finding id the scan carries, in the order the report prints them. */
+export declare function findingIds(p: Prospect): string[];
+export interface VerdictCheck {
+    ok: boolean;
+    problems: string[];
+    counts: Record<Verdict, number> & {
+        total: number;
+        unruled: number;
+    };
+}
+/**
+ * Validate the verdicts against the scan they claim to rule on. Every scan
+ * finding needs a verdict; every CONFIRMED and REFUTED needs evidence that
+ * exists in the register; every UNKNOWN needs a reason; every ON_RECORD needs
+ * the line. A report text may be passed so that cited evidence is also
+ * required to appear in the report.
+ */
+export declare function checkVerdicts(p: Prospect, v: Verdicts, reportMd?: string): VerdictCheck;
+export interface Rescore {
+    before: ProspectScore;
+    after: ProspectScore;
+    dropped: {
+        refuted: string[];
+        on_record: string[];
+    };
+    unknown: string[];
+}
+/** The score with refuted and recorded findings removed. UNKNOWN still counts: unproven is not innocent. */
+export declare function rescore(p: Prospect, v: Verdicts): Rescore;
+/** The math, printed. Nothing on the page is typed by hand. */
+export declare function showMath(p: Prospect, v: Verdicts, r: Rescore, c: VerdictCheck): string;

package/dist/verdicts.js

@@ -0,0 +1,144 @@
+import { scoreProspect } from "./score.js";
+const VERDICTS = new Set(["CONFIRMED", "REFUTED", "ON_RECORD", "UNKNOWN"]);
+/** Every finding id the scan carries, in the order the report prints them. */
+export function findingIds(p) {
+    const ids = [];
+    for (const d of p.deps)
+        if (d.id)
+            ids.push(d.id);
+    for (const o of p.overlaps)
+        if (o.id)
+            ids.push(o.id);
+    for (const h of p.handrolled)
+        if (h.id)
+            ids.push(h.id);
+    for (const c of p.stack.consolidations)
+        if (c.id)
+            ids.push(c.id);
+    for (const d of p.duplicates)
+        if (d.id)
+            ids.push(d.id);
+    for (const d of p.dead)
+        if (d.id)
+            ids.push(d.id);
+    for (const c of p.cost_surfaces)
+        if (c.id)
+            ids.push(c.id);
+    for (const f of p.database.findings)
+        if (f.id)
+            ids.push(f.id);
+    return ids;
+}
+/**
+ * Validate the verdicts against the scan they claim to rule on. Every scan
+ * finding needs a verdict; every CONFIRMED and REFUTED needs evidence that
+ * exists in the register; every UNKNOWN needs a reason; every ON_RECORD needs
+ * the line. A report text may be passed so that cited evidence is also
+ * required to appear in the report.
+ */
+export function checkVerdicts(p, v, reportMd) {
+    const problems = [];
+    const counts = { CONFIRMED: 0, REFUTED: 0, ON_RECORD: 0, UNKNOWN: 0, total: 0, unruled: 0 };
+    if (v.format !== "bigsteele-prospect-verdicts/1")
+        problems.push(`format is "${String(v.format)}", expected "bigsteele-prospect-verdicts/1"`);
+    const evidence = new Map((v.evidence ?? []).map((e) => [e.id, e]));
+    for (const e of v.evidence ?? []) {
+        if (!/^EV-\d+$/.test(e.id))
+            problems.push(`evidence "${e.id}" is not named EV-<n>`);
+        if (!e.where || !e.observed)
+            problems.push(`evidence ${e.id} lacks where or observed`);
+    }
+    const byId = new Map();
+    for (const r of v.findings ?? []) {
+        if (byId.has(r.id))
+            problems.push(`finding ${r.id} has two verdicts`);
+        byId.set(r.id, r);
+    }
+    const ids = findingIds(p);
+    const known = new Set(ids);
+    for (const r of v.findings ?? []) {
+        if (!known.has(r.id))
+            problems.push(`verdict on "${r.id}", which the scan did not report`);
+    }
+    for (const id of ids) {
+        const r = byId.get(id);
+        counts.total++;
+        if (!r) {
+            counts.unruled++;
+            problems.push(`no verdict on ${id}: a finding nobody checked`);
+            continue;
+        }
+        if (!VERDICTS.has(r.verdict)) {
+            problems.push(`${id}: verdict "${String(r.verdict)}" is not CONFIRMED, REFUTED, ON_RECORD or UNKNOWN`);
+            continue;
+        }
+        counts[r.verdict]++;
+        if (r.verdict === "CONFIRMED" || r.verdict === "REFUTED") {
+            if (!r.evidence?.length)
+                problems.push(`${id}: ${r.verdict} with no evidence entry`);
+            for (const ev of r.evidence ?? []) {
+                if (!evidence.has(ev))
+                    problems.push(`${id}: cites ${ev}, which is not in the register`);
+                else if (reportMd && !reportMd.includes(ev))
+                    problems.push(`${id}: cites ${ev}, which the report never shows`);
+            }
+        }
+        if (r.verdict === "REFUTED" && !r.reason)
+            problems.push(`${id}: REFUTED without saying what shape lied`);
+        if (r.verdict === "UNKNOWN" && !r.reason)
+            problems.push(`${id}: UNKNOWN without saying what would settle it`);
+        if (r.verdict === "ON_RECORD" && !r.record)
+            problems.push(`${id}: ON_RECORD without the deciding line`);
+    }
+    return { ok: problems.length === 0, problems, counts };
+}
+/** The score with refuted and recorded findings removed. UNKNOWN still counts: unproven is not innocent. */
+export function rescore(p, v) {
+    const verdictOf = new Map((v.findings ?? []).map((r) => [r.id, r.verdict]));
+    const keep = (id) => !id || !(verdictOf.get(id) === "REFUTED" || verdictOf.get(id) === "ON_RECORD");
+    const refuted = [...verdictOf].filter(([, x]) => x === "REFUTED").map(([id]) => id);
+    const onRecord = [...verdictOf].filter(([, x]) => x === "ON_RECORD").map(([id]) => id);
+    const unknown = [...verdictOf].filter(([, x]) => x === "UNKNOWN").map(([id]) => id);
+    const deps = p.deps.map((d) => (keep(d.id) ? d : { ...d, no_reference_found: false }));
+    const unusedPaid = deps.find((d) => !d.dev && d.no_reference_found && /^(openai|stripe|twilio|resend|@sendgrid\/|@anthropic-ai\/|@clerk\/|algoliasearch|cloudinary)/.test(d.name))?.name ?? null;
+    const after = scoreProspect({
+        not_asked: p.score.not_asked,
+        deps,
+        overlaps: p.overlaps.filter((o) => keep(o.id)),
+        consolidations: p.stack.consolidations.filter((c) => keep(c.id)),
+        handrolled: p.handrolled.filter((h) => keep(h.id)),
+        duplicates: p.duplicates.filter((d) => keep(d.id)),
+        dead: p.dead.filter((d) => keep(d.id)),
+        costs: p.cost_surfaces.filter((c) => keep(c.id)),
+        runtime_files: p.totals.runtime_files,
+        unused_paid_service: unusedPaid,
+    });
+    return { before: p.score, after, dropped: { refuted, on_record: onRecord }, unknown };
+}
+/** The math, printed. Nothing on the page is typed by hand. */
+export function showMath(p, v, r, c) {
+    const L = [];
+    L.push(`THE PROSPECT - recomputed from ${v.scan ?? "the scan"}${v.commit ? ` at ${v.commit}` : ""}`);
+    L.push(`findings: ${c.counts.total}  CONFIRMED ${c.counts.CONFIRMED}  REFUTED ${c.counts.REFUTED}  ON_RECORD ${c.counts.ON_RECORD}  UNKNOWN ${c.counts.UNKNOWN}  unruled ${c.counts.unruled}`);
+    L.push(`evidence entries: ${(v.evidence ?? []).length}`);
+    L.push("");
+    L.push(`Step 0 score   ${String(r.before.total).padStart(3)}/100 (${r.before.grade})  Level ${r.before.level.n} ${r.before.level.name}`);
+    L.push(`After verdicts ${String(r.after.total).padStart(3)}/100 (${r.after.grade})  Level ${r.after.level.n} ${r.after.level.name}`);
+    L.push("");
+    L.push("Deductions after verdicts:");
+    if (!r.after.deductions.length)
+        L.push("  none");
+    for (const d of r.after.deductions)
+        L.push(`  ${String(d.points).padStart(4)}  ${d.what}  (${d.evidence})`);
+    for (const f of r.after.floors)
+        L.push(`  floor: ${f}`);
+    if (r.dropped.refuted.length)
+        L.push("", `Refuted, cost nothing: ${r.dropped.refuted.join(", ")}`);
+    if (r.dropped.on_record.length)
+        L.push(`On record, cost nothing: ${r.dropped.on_record.join(", ")}`);
+    if (r.unknown.length)
+        L.push(`Still unknown, still charged: ${r.unknown.join(", ")}`);
+    L.push("");
+    L.push(c.ok ? "verdicts: complete" : `verdicts: ${c.problems.length} problem(s) - the number above is not final until they are fixed`);
+    return L.join("\n");
+}