@bigsteele/the-prospect 0.2.0 → 0.3.0

package/README.md

@@ -48,32 +48,55 @@ Step 0 runs offline, reads everything, and writes two files into your repo:
 - **Your industry fingerprint** - the domain vocabulary your own schema and
   routes use, which is what the second half researches against.
 
-Then:
+Step 0 takes seconds, and it is a hypothesis machine: it reads shapes and
+prints them, every one with an id. The read is the second command.
 
 ```
-npx @bigsteele/the-prospect --run
+npx @bigsteele/the-prospect --run        # or --protocol, to paste THE-PROSPECT.md into any agent
 ```
 
-opens Claude Code with the research protocol. It confirms your vertical
-with you, researches the actual vendor and API landscape with sources and
-dates, verifies every stack-cut pair against the kept platform's current
-plan, and fills Lane 2: at most five suggestions, each in a fixed shape -
-*Since you* (a fact from your code, file cited), *Have you considered*
-(always two options, or one vendor against building it yourself), *Because*
-(the industry fact, with a source URL and the year it was checked), *Your
-customer gets* (the benefit in the customer's terms), *First test* (a
-one-week test needing nobody's permission, and the observation that would
-kill the idea).
-
-A suggestion missing any leg is cut, not softened. And:
+This is a large read, not a quick check, and it says so before it starts.
+Claude Code opens with the protocol and the agent, read-only: establishes
+your North Star from the pricing page, the schema and the code before it
+judges anything; takes every Step 0 finding to the code and rules on it,
+CONFIRMED with evidence, REFUTED with the sentence that names the shape
+that lied, ON_RECORD with the deciding line, or UNKNOWN with what would
+settle it; walks the whole tree for the inventories the scan cannot finish
+on its own - every vendor with the job it does and whose money it touches,
+every subsystem built by hand and what keeping it buys, every dependency's
+job, every unreached file's real status, every multiplying call with a
+price where one is public, the database rulings against the grants, and
+the shape of the bill; researches your market in five lanes with sources
+and dates; ranks everything against the North Star; and writes
+**The Prospect - <App Name>.md** at the repository root with the next ten
+actions, the inventories in full, the evidence register, and the math.
+
+Every suggestion keeps the fixed shape - *Since you* (a fact from your
+code, file cited), *Have you considered* (always two options, or one vendor
+against building it yourself), *Because* (the industry fact, with a source
+URL and the year it was checked), *Your customer gets* (the benefit in the
+customer's terms), *First test* (a one-week test needing nobody's
+permission, and the observation that would kill the idea). A suggestion
+missing any leg is cut, not softened. And:
 
 ```
 npx @bigsteele/the-prospect --check
 ```
 
-fails the finished report mechanically if it breaks the law: unsourced
-claims, undated claims, single-vendor pitches, advice verbs, missing legs.
-Exit 0 when it holds, 2 when it does not.
+is the second opinion. It reads the deliverable and
+`.planning/prospect/VERDICTS.json`, fails any finding without a ruling,
+any ruling without evidence, any evidence the report does not show, any
+unsourced or undated claim, any single-vendor pitch, any advice verb, and
+recomputes the score from the verdicts with the math printed: a refuted
+finding costs nothing, a recorded one costs nothing, an unknown one still
+does. Exit 0 when it holds, 2 when it does not.
+
+The scan's Lane 1 is calibrated on real repositories and the calibration
+notes say what it got wrong and when it was fixed: a category is not a job
+(Stripe running Connect beside Square billing the platform is two jobs),
+one `.ilike()` is not a search engine, a socket is not a paid call, a
+`revoke ... from anon, authenticated` in a migration is a caller check, and
+a shadcn component nobody imports is scaffold, weighed a quarter.
 
 ## Standalone
 

package/dist/check.js

@@ -37,8 +37,9 @@ export function checkReport(md) {
         findings.push({ where: "whole report", problem: "no [READ] badge - the repository half is missing or unmarked" });
     }
     // Lane 2: each suggestion block (### heading under the territory section).
-    const lane2Heading = /^## .*territory.*$/im.exec(md)?.[0] ?? "";
-    const lane2 = md.split(/^## .*territory.*$/im)[1]?.split(/^## /m)[0] ?? "";
+    // Step 0 titles the lane "what the territory holds"; the protocol's deliverable titles it "Lane 2, researched".
+    const lane2Heading = /^## .*(territory|lane 2).*$/im.exec(md)?.[0] ?? "";
+    const lane2 = md.split(/^## .*(?:territory|lane 2).*$/im)[1]?.split(/^## /m)[0] ?? "";
     const ranProtocol = !/not yet run/i.test(lane2Heading + lane2);
     if (ranProtocol && lane2.trim()) {
         if (!/\[RESEARCHED\]/.test(lane2Heading + lane2)) {

package/dist/cli.js

@@ -17,7 +17,7 @@ import { mkdir, writeFile, readFile, appendFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
-import { runProspect, toMarkdown, secretShaped, checkReport, VERSION } from "./index.js";
+import { runProspect, toMarkdown, secretShaped, checkReport, checkVerdicts, rescore, showMath, VERSION } from "./index.js";
 const log = (s = "") => process.stdout.write(s + "\n");
 const args = process.argv.slice(2);
 const has = (f) => args.includes(f);
@@ -27,15 +27,17 @@ const valueOf = (f) => {
 };
 const HELP = `The Prospect ${VERSION} - a prospector's read of your codebase and your market.
 
-  npx @bigsteele/the-prospect [dir]        Step 0: scan and report (offline, read-only)
-  npx @bigsteele/the-prospect --run        open Claude Code with the research protocol
-  npx @bigsteele/the-prospect --check      fail a finished report that breaks the law
+  npx @bigsteele/the-prospect [dir]        Step 0: scan and report (offline, read-only, seconds)
+  npx @bigsteele/the-prospect --run        open Claude Code with the protocol (the deep read: long)
+  npx @bigsteele/the-prospect --protocol   drop THE-PROSPECT.md into the repo to paste into any agent
+  npx @bigsteele/the-prospect --check      rule on a finished report: verdicts, evidence, legs, the math
 
-  --repo <dir>     the repository to read (default: here)
-  --out <dir>      where the report goes (default: the repository root)
-  --report <file>  the report --check should measure (default: the newest one here)
-  --stdout         print the report instead of writing it
-  --yes            skip the confirmation on --run
+  --repo <dir>       the repository to read (default: here)
+  --out <dir>        where the report goes (default: the repository root)
+  --report <file>    the report --check should measure (default: the deliverable, else the newest scan)
+  --verdicts <file>  the verdicts --check should re-score from (default: .planning/prospect/VERDICTS.json)
+  --stdout           print the report (or, with --protocol, the protocol) instead of writing it
+  --yes              skip the confirmation on --run
 
 Exit 0 when it passes, 2 when it does not, 1 when it refuses.`;
 const slug = (s) => s.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "app";
@@ -47,42 +49,101 @@ async function main() {
     const flagsWithValue = ["--repo", "--out", "--report"];
     const positional = args.find((a) => !a.startsWith("-") && !flagsWithValue.includes(args[args.indexOf(a) - 1] ?? ""));
     const repoDir = resolve(valueOf("--repo") ?? positional ?? process.cwd());
+    const here = dirname(fileURLToPath(import.meta.url));
+    const protocol = resolve(here, "..", "prompt", "THE-PROSPECT.md");
+    if (has("--protocol")) {
+        // The protocol is a file, and the file is the product: drop it where any
+        // agent can read it, the way The Big Sean does.
+        const text = await readFile(protocol, "utf8");
+        if (has("--stdout")) {
+            log(text);
+            return 0;
+        }
+        await writeFile(join(repoDir, "THE-PROSPECT.md"), text, "utf8");
+        log(`Wrote THE-PROSPECT.md. Open Claude Code in this folder and paste the whole file in, or run --run.`);
+        return 0;
+    }
     if (has("--check")) {
         const file = valueOf("--report");
         let path = file ? resolve(file) : "";
         if (!path) {
-            // The newest prospect report beside us.
+            // The deliverable if the protocol wrote one, else the newest Step 0 report.
             const { readdir } = await import("node:fs/promises");
-            const names = (await readdir(repoDir)).filter((n) => /^the-prospect-.*\.md$/.test(n)).sort();
-            if (names.length === 0) {
+            const all = await readdir(repoDir);
+            const deliverable = all.filter((n) => /^The Prospect - .*\.md$/.test(n)).sort();
+            const step0 = all.filter((n) => /^the-prospect-.*\.md$/.test(n)).sort();
+            const pick = deliverable[deliverable.length - 1] ?? step0[step0.length - 1];
+            if (!pick) {
                 log("No report to check. Run the scan first, then the protocol, then this.");
                 return 2;
             }
-            path = join(repoDir, names[names.length - 1]);
+            path = join(repoDir, pick);
         }
         const md = await readFile(path, "utf8");
         const { pass, findings } = checkReport(md);
-        if (pass) {
-            log(`${path} holds the law: every suggestion stands on three legs, every claim carries a source.`);
-            return 0;
-        }
         for (const f of findings)
             log(`FAIL  ${f.where}: ${f.problem}${f.line ? `  | ${f.line}` : ""}`);
+        // THE VERDICTS, WHEN THE PROTOCOL LEFT THEM (0.3). Every Step 0 finding
+        // ruled on, every ruling with evidence, and the score recomputed from the
+        // rulings with the math printed. Missing verdicts fail the check the moment
+        // a verdicts file exists at all: half a ruling is no ruling.
+        const verdictsPath = resolve(valueOf("--verdicts") ?? join(repoDir, ".planning", "prospect", "VERDICTS.json"));
+        let verdictProblems = 0;
+        let scanPath = "";
+        try {
+            const v = JSON.parse(await readFile(verdictsPath, "utf8"));
+            scanPath = v.scan ? resolve(repoDir, v.scan) : "";
+            if (!scanPath) {
+                const { readdir } = await import("node:fs/promises");
+                const names = (await readdir(repoDir)).filter((n) => /^the-prospect-.*\.json$/.test(n)).sort();
+                scanPath = names.length ? join(repoDir, names[names.length - 1]) : "";
+            }
+            if (!scanPath) {
+                log(`FAIL  verdicts: no scan JSON to rule on (the-prospect-<app>.json)`);
+                verdictProblems++;
+            }
+            else {
+                const scan = JSON.parse(await readFile(scanPath, "utf8"));
+                const c = checkVerdicts(scan, v, md);
+                for (const p of c.problems)
+                    log(`FAIL  verdict: ${p}`);
+                verdictProblems = c.problems.length;
+                const r = rescore(scan, v);
+                log("");
+                log(showMath(scan, v, r, c));
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT") {
+                log(`FAIL  verdicts: ${verdictsPath} could not be read: ${e instanceof Error ? e.message : String(e)}`);
+                verdictProblems++;
+            }
+            else if (/^The Prospect - /.test(path.split("/").pop() ?? "")) {
+                log(`FAIL  verdicts: the protocol's deliverable exists but ${verdictsPath} does not; every finding needs a ruling`);
+                verdictProblems++;
+            }
+        }
+        if (pass && verdictProblems === 0) {
+            log("");
+            log(`${path} holds the law: every finding ruled on with evidence, every suggestion on three legs, every claim sourced.`);
+            return 0;
+        }
         log("");
-        log(`${findings.length} finding(s). A suggestion missing a leg is cut, not softened.`);
+        log(`${findings.length + verdictProblems} finding(s). A suggestion missing a leg is cut, not softened; a finding without a ruling is unchecked.`);
         return 2;
     }
     if (has("--run")) {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const protocol = resolve(here, "..", "prompt", "THE-PROSPECT.md");
         if (!has("--yes")) {
             log("");
-            log("This opens Claude Code and asks it to research your industry against Step 0's facts.");
-            log("It reads the scan output, verifies findings in the repository, and searches the web.");
-            log("It changes no source code. Run the scan first so the facts exist. Ctrl-C to stop.");
+            log("BEFORE YOU RUN THIS, KNOW WHAT IT IS. This is a large scan, not a quick check.");
+            log("It opens Claude Code with the protocol: the agent reads everything in this repository it can");
+            log("reach, takes every Step 0 finding to the code and rules on it with evidence, inventories every");
+            log("vendor, subsystem and dependency, researches your market with sources and dates, and writes a");
+            log("long report. Expect a long session and a lot of tokens. It changes nothing: no edits, no commits,");
+            log("no deploys, no messages, no spending. Run the scan first so the facts exist. Ctrl-C to stop.");
             log("");
         }
-        const child = spawn("claude", [`Follow the protocol in ${protocol}. The repository is ${repoDir}.`], {
+        const child = spawn("claude", [`Follow the protocol in ${protocol}, every step, to the end. The repository is ${repoDir}.`], {
             stdio: "inherit",
             shell: false,
         });
@@ -141,11 +202,16 @@ async function main() {
     log(`${p.score.total}/100 (${p.score.grade}) - Level ${p.score.level.n}: ${p.score.level.name}.`);
     if (noRef)
         log(`${noRef} of ${p.totals.runtime_deps} runtime dependencies show no reference anywhere.`);
-    if (p.overlaps.length)
-        log(`${p.overlaps.length} categor${p.overlaps.length > 1 ? "ies" : "y"} of work paid for twice.`);
+    const paidTwice = p.overlaps.filter((o) => !o.distinct).length;
+    const twoJobs = p.overlaps.length - paidTwice;
+    if (paidTwice)
+        log(`${paidTwice} categor${paidTwice > 1 ? "ies" : "y"} of work paid for twice.`);
+    if (twoJobs)
+        log(`${twoJobs} vendor pair${twoJobs > 1 ? "s" : ""} sharing a category but doing different jobs: listed, not charged.`);
     if (p.handrolled.length)
         log(`${p.handrolled.length} subsystem(s) built by hand where the market sells a rail.`);
-    log(`Next: npx @bigsteele/the-prospect --run   (the industry half, researched)`);
+    log(`This was the scan: seconds, shapes, every finding with an id. The read is the next command.`);
+    log(`Next: npx @bigsteele/the-prospect --run   (the deep read: every finding ruled on, every vendor and subsystem inventoried, the market researched)`);
     return 0;
 }
 main().then((code) => process.exit(code), (err) => {

package/dist/detect/costs.js

@@ -1,15 +1,57 @@
 import { scopeFor } from "../walk.js";
-const PAID_CALL = /\bfetch\(\s*[`"']https?:\/\/(api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|api\.stripe\.com|api\.twilio\.com|api\.resend\.com|api\.sendgrid\.com|api\.cloudflare\.com|api\.replicate\.com|api\.elevenlabs\.io)|\.(messages|completions|chat|embeddings|images)\.create\(|generateContent|\.send(Email|Mail|Sms)?\(/;
-const LOOP_HEAD = /\bfor(\s+await)?\s*\(|\bwhile\s*\(|\.(map|forEach)\(\s*(async\b|\()/;
+/**
+ * A PAID call, which is the whole point (0.2.1). `\.send\(` on its own matched
+ * `ws.send(...)` to a local Chrome DevTools socket in four build scripts, and
+ * the report billed them as four paid loops. A call is paid when it names a
+ * paid host, a paid SDK method, or a sender object that is plainly a mail or
+ * SMS client. A socket is not a vendor.
+ */
+const PAID_CALL = /\bfetch\(\s*[`"']https?:\/\/(api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|api\.stripe\.com|api\.twilio\.com|api\.resend\.com|api\.sendgrid\.com|api\.cloudflare\.com|api\.replicate\.com|api\.elevenlabs\.io)|\.(messages|completions|chat|embeddings|images|predictions)\.create\(|generateContent|\b(sendEmail|sendMail|sendSms)\(|\b(resend|sendgrid|sgMail|postmark|mailgun|transporter|mailer|twilio|ses|sns)\.\w*[sS]end\w*\(|\.emails\.send\(/;
+const LOOP_HEAD = /\bfor(\s+await)?\s*\(|\bwhile\s*\(|\.(map|forEach|flatMap)\(\s*(async\b|\()/;
 const HANDLER = /(^|\/)(functions|api|routes?|handlers?)\//i;
 const SCHEDULE = /\bsetInterval\s*\(|\bcron\b|schedule/i;
 function hostOrCall(line) {
     const host = /https?:\/\/([a-z0-9.-]+)/i.exec(line)?.[1];
     if (host)
         return host;
-    const call = /\.((?:messages|completions|chat|embeddings|images)\.create|generateContent|send(?:Email|Mail|Sms)?)\(/.exec(line)?.[1];
+    const call = /\.((?:messages|completions|chat|embeddings|images|predictions)\.create|generateContent|emails\.send|\w*[sS]end\w*)\(/.exec(line)?.[1];
     return call ?? "external call";
 }
+const count = (s, re) => (s.match(re) ?? []).length;
+/**
+ * INSIDE the loop, not below it (0.2.1). "A loop head within the twelve lines
+ * above" read `slots.map((s) => s.role).join(', ')` - a prompt being built - as
+ * the loop around the Gemini call three lines later, and reported the call as
+ * per-row twice on the first repository it met. A loop encloses the call only
+ * if the brackets it opened are still open where the call is made.
+ */
+function insideLoop(lines, at) {
+    for (let j = at - 1; j >= Math.max(0, at - 80); j--) {
+        if (!LOOP_HEAD.test(lines[j]))
+            continue;
+        // Walk forward from the loop head until the brackets it opened close. If
+        // they have not closed by the call, the call is inside. Stopping at the
+        // close means the call's OWN `fetch(` on the line above its URL is never
+        // mistaken for the loop still being open.
+        let depth = 0;
+        let opened = false;
+        let closed = false;
+        for (let k = j; k < at && !closed; k++) {
+            const opens = count(lines[k], /[{(]/g);
+            depth += opens - count(lines[k], /[})]/g);
+            // The head line opening and closing on the same line (`.map((x) => x.id).join(', ')`)
+            // is a loop that already closed; without this, the walk ran on past it and
+            // tripped over a prose parenthesis inside a prompt string forty lines later.
+            if ((k === j && opens > 0) || depth > 0)
+                opened = true;
+            if (opened && depth <= 0)
+                closed = true;
+        }
+        if (opened && !closed)
+            return true;
+    }
+    return false;
+}
 export async function detectCosts(repo) {
     const out = [];
     for (const f of scopeFor(repo.files, "implementation")) {
@@ -23,13 +65,13 @@ export async function detectCosts(repo) {
                 continue;
             const target = hostOrCall(line);
             const evidence = `${i + 1}: ${line.trim().slice(0, 110)}`;
-            // per-row: a loop head within the twelve lines above the call.
-            const above = lines.slice(Math.max(0, i - 12), i).join("\n");
-            if (LOOP_HEAD.test(above)) {
+            // per-row: the call sits inside a loop that has not closed.
+            if (insideLoop(lines, i)) {
                 out.push({ file: f, shape: "per-row", target, line: evidence });
                 continue;
             }
             // per-schedule: the call sits under an interval or a cron marker.
+            const above = lines.slice(Math.max(0, i - 12), i).join("\n");
             if (SCHEDULE.test(above) || (SCHEDULE.test(text.slice(0, 800)) && SCHEDULE.test(f))) {
                 out.push({ file: f, shape: "per-schedule", target, line: evidence });
                 continue;

package/dist/detect/database.js

@@ -75,9 +75,21 @@ export async function detectDatabase(repo) {
     const findings = [];
     let policies = 0;
     let definerFunctions = 0;
-    // Two passes: every `alter table` in the repository is collected first,
-    // because a table is very often created in one migration and secured in the
-    // next, and reading them in file order would flag every such table.
+    /**
+     * THE GRANTS ARE IN THE MIGRATIONS (0.2.1). The caller check was looked for
+     * inside the function body only, and 60 definer functions on the first real
+     * repository were reported as stating no check when each one was followed by
+     * `revoke all on function ... from public, anon, authenticated` - a caller
+     * check by another statement. Postgres grants EXECUTE to public by default,
+     * so a revoke from public/anon/authenticated is the statement that narrows
+     * who may call; a bare `grant execute ... to service_role` narrows nothing.
+     */
+    const executeRevoked = new Set();
+    let guard;
+    // Two passes: every `alter table` and every `revoke` in the repository is
+    // collected first, because a table is very often created in one migration
+    // and secured in the next, and reading them in file order would flag every
+    // such table.
     for (const f of files) {
         const raw = await repo.read(f);
         if (!raw)
@@ -90,6 +102,16 @@ export async function detectDatabase(repo) {
             if (/enable/i.test(m[2]))
                 rlsEnabled.add(t);
         }
+        for (const m of sql.matchAll(/revoke\s+(?:all|execute)(?:\s+privileges)?\s+on\s+function\s+([a-z0-9_."]+)\s*(?:\([^)]*\))?\s+from\s+([a-z_,\s"]+)/gi)) {
+            if (/\b(public|anon|authenticated)\b/i.test(m[2]))
+                executeRevoked.add(qualify(m[1]));
+        }
+        for (const g of sql.matchAll(/create\s+(?:or\s+replace\s+)?function\s+([a-z0-9_."]*(?:definer_guard|guard_scan|grant_scan)[a-z0-9_]*)\s*\(/gi)) {
+            const name = `${qualify(g[1])}()`;
+            // The one that names definers wins; otherwise the first guard seen.
+            if (!guard || (/definer/i.test(name) && !/definer/i.test(guard)))
+                guard = name;
+        }
     }
     for (const f of files) {
         const raw = await repo.read(f);
@@ -134,12 +156,13 @@ export async function detectDatabase(repo) {
             if (/create\s+(or\s+replace\s+)?function/i.test(stmt) && /security\s+definer/i.test(stmt)) {
                 definerFunctions++;
                 const name = /create\s+(?:or\s+replace\s+)?function\s+([a-z0-9_."]+)\s*\(/i.exec(stmt)?.[1];
-                if (name && !CALLER_CHECK.test(withComments)) {
+                if (name && !CALLER_CHECK.test(withComments) && !executeRevoked.has(qualify(name))) {
                     findings.push({
                         kind: "definer_without_check",
                         subject: qualify(name),
                         file: f,
-                        note: "runs with the definer's rights and states no caller check. Either it is meant to be callable by anyone, or a grant is the only thing standing between it and one.",
+                        note: "runs with the definer's rights, states no caller check in its body, and no migration revokes its EXECUTE from public, anon or authenticated. Either it is meant to be callable by anyone, or a grant applied outside the migrations is the only thing standing between it and one." +
+                            (guard ? ` The repository carries \`${guard}\`, which checks the live grants; this scan reads only what the migrations state.` : ""),
                     });
                 }
             }
@@ -168,6 +191,8 @@ export async function detectDatabase(repo) {
         tables: tablesSeen.size,
         policies,
         definer_functions: definerFunctions,
+        definer_execute_revoked: executeRevoked.size,
+        guard,
         findings: findings.sort((a, b) => a.kind.localeCompare(b.kind) || a.subject.localeCompare(b.subject)).slice(0, 60),
     };
 }

package/dist/detect/deadweight.js

@@ -13,9 +13,12 @@ function entrypoints(repo, manifests) {
     for (const f of repo.files) {
         if (/(^|\/)src\/(main|index|app|App)\.(t|j)sx?$/.test(f) ||
             /(^|\/)(functions|api)\/[^/]+\/index\.(t|j)s$/.test(f) ||
+            /^api\/.*\.(m|c)?(t|j)sx?$/.test(f) || // a root api/ tree is a serverless router (Vercel): every file is a function
+            /(^|\/)netlify\/functions\/[^/]+\.(m|c)?(t|j)s$/.test(f) ||
             /(^|\/)(pages|app)\/.*\.(t|j)sx?$/.test(f) || // file-based routers import nothing by name
             /(^|\/)scripts?\/[^/]+\.(m|c)?(t|j)s$/.test(f) ||
             /(^|\/)(index|server|worker|cli)\.(m|c)?(t|j)s$/.test(f) ||
+            NOT_BEHAVIOUR.test(f) || // a config file imports things (a playwright fixture, a vite plugin); it seeds the walk and is never itself listed
             TEST_FILE.test(f) // tests reach code; code only tests reach is a different finding
         ) {
             out.add(f);
@@ -101,32 +104,74 @@ export async function detectDeadweight(repo) {
     const roots = entrypoints(repo, manifests);
     const reached = new Set(roots);
     const queue = [...roots];
-    while (queue.length) {
-        const f = queue.pop();
-        const text = await repo.read(f);
-        if (!text)
-            continue;
-        for (const spec of specifiers(text)) {
-            const to = resolve(f, spec);
-            if (to && !reached.has(to)) {
-                reached.add(to);
-                queue.push(to);
+    const drain = async () => {
+        while (queue.length) {
+            const f = queue.pop();
+            const text = await repo.read(f);
+            if (!text)
+                continue;
+            for (const spec of specifiers(text)) {
+                const to = resolve(f, spec);
+                if (to && !reached.has(to)) {
+                    reached.add(to);
+                    queue.push(to);
+                }
+            }
+        }
+    };
+    await drain();
+    const candidates = repo.files.filter((f) => CODE.test(f) && !TEST_FILE.test(f) && !NOT_RUNTIME.test(f) && !NOT_BEHAVIOUR.test(f));
+    // NAMED BY PATH (0.2.1). A build script that does
+    // `readFileSync(join(ROOT, 'kit', 'modes.src.js'))` reaches that file as
+    // surely as an import does, and the first real repository had its whole
+    // colour pipeline listed as unreached on exactly that. A file whose name a
+    // reached file quotes is reached, and its own imports are walked in turn.
+    const GENERIC_BASENAME = /^(index|main|app|utils?|types?|config|client|server|helpers?|constants?)\./i;
+    const namedBy = new Map();
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const f of candidates) {
+            if (reached.has(f))
+                continue;
+            const base = f.split("/").pop();
+            if (base.length < 8 || GENERIC_BASENAME.test(base))
+                continue;
+            const re = new RegExp(`['"\`][^'"\`\\n]*(?<![a-z0-9_-])${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"\`]`);
+            for (const r of reached) {
+                if (r === f)
+                    continue;
+                const text = await repo.read(r);
+                if (text && re.test(text)) {
+                    reached.add(f);
+                    namedBy.set(f, r);
+                    queue.push(f);
+                    grew = true;
+                    break;
+                }
             }
         }
+        await drain();
     }
+    void namedBy;
+    // SERVED, NOT IMPORTED. Everything under public/ or static/ is handed to the
+    // browser as-is; nothing imports it because nothing has to.
+    const SERVED = /(^|\/)(public|static)\//i;
+    // A UI-kit scaffold beside a components.json: installed wholesale, imported
+    // one component at a time, never bundled when unimported.
+    const kit = repo.files.some((f) => /(^|\/)components\.json$/.test(f) && !/node_modules|fixtures?/.test(f));
     const dead = [];
-    for (const f of repo.files) {
-        if (!CODE.test(f) || TEST_FILE.test(f) || NOT_RUNTIME.test(f) || NOT_BEHAVIOUR.test(f))
-            continue;
-        if (reached.has(f))
+    for (const f of candidates) {
+        if (reached.has(f) || SERVED.test(f))
             continue;
         const text = await repo.read(f);
         if (!text)
             continue;
+        const scaffold = kit && /(^|\/)components\/ui\/[^/]+\.(t|j)sx?$/.test(f);
         dead.push({
             file: f,
             loc: text.split("\n").length,
-            note: "no import path found from any entrypoint",
+            note: scaffold ? "a UI-kit scaffold component no file imports: never bundled, only read and searched" : "no import path found from any entrypoint",
+            ...(scaffold ? { scaffold: true } : {}),
         });
     }
     return {

package/dist/detect/handrolled.js

@@ -20,17 +20,20 @@ function legs(r, file, text) {
  */
 function regionLines(r, text) {
     const lines = text.split("\n");
-    const hits = [];
-    for (const re of [r.content, r.requires].filter(Boolean)) {
-        const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
-        for (const m of text.matchAll(g))
-            hits.push(text.slice(0, m.index).split("\n").length);
+    const starts = [];
+    const ends = [];
+    // CONTENT ONLY (0.2.1). `requires` testifies that the state the job needs
+    // exists somewhere in the file; it does not bound the subsystem. Spanning to
+    // it turned one `.ilike(` on line 266 and the word "query" near the bottom
+    // into "1,002 lines of hand-rolled search" in an invite handler.
+    const g = new RegExp(r.content.source, r.content.flags.includes("g") ? r.content.flags : r.content.flags + "g");
+    for (const m of text.matchAll(g)) {
+        starts.push(text.slice(0, m.index).split("\n").length);
+        ends.push(text.slice(0, m.index + m[0].length).split("\n").length);
     }
-    if (hits.length === 0)
+    if (starts.length === 0)
         return 0;
-    const first = Math.min(...hits);
-    const last = Math.max(...hits);
-    return Math.min(lines.length, last - first + 1);
+    return Math.min(lines.length, Math.max(...ends) - Math.min(...starts) + 1);
 }
 const RULES = [
     {
@@ -82,12 +85,18 @@ const RULES = [
     },
     {
         rail: "search",
-        // NAME REQUIRED. `tokenize(query)` inside a help-centre page is a filter box,
-        // not a search engine, and the old rule reported it as 260 lines of one.
-        name: /search|query|index|lookup|find/i,
+        // NAME REQUIRED, and `index` and `query` are not names (0.2.1): with them
+        // every `index.ts` announced itself as search, and one PostgREST
+        // `.ilike('email', email)` looking up an invitee was reported as 1,002 lines
+        // of a search engine. `tokenize(query)` inside a help-centre page is a
+        // filter box, not a search engine, and was reported as 260 lines of one.
+        name: /search|lookup|finder|indexer|full.?text/i,
         name_required: true,
-        content: /(ilike|ILIKE|LIKE)\s*\(?\s*["'`]%|\.ilike\(|to_tsvector|\btokeni[sz]e\b[\s\S]{0,200}\bscore\b/i,
-        requires: /(search|query|match|find)/i,
+        // AN ENGINE, NOT A FILTER. Something is tokenised and scored, an index is
+        // built and walked, or similarity is computed by hand. One LIKE is a WHERE
+        // clause; a database doing it is the rail, not the hand.
+        content: /\btokeni[sz]e\w*\b[\s\S]{0,600}\b(score|rank)\w*\b|\b(levenshtein|trigram|jaro|bm25|tf.?idf|inverted.?index|n.?grams?)\b|\b(build|make|create)(Search)?Index\s*\(|\bsearchIndex\b/i,
+        requires: /\b(query|term|needle|q)\b[\s\S]{0,600}\b(results?|hits|matches|ranked)\b/i,
         rail_sdk: /["'](algoliasearch|meilisearch|typesense|@elastic|flexsearch|minisearch|fuse\.js)["']/,
     },
     {

package/dist/detect/stack.d.ts

@@ -45,6 +45,8 @@ export interface WorkflowFact {
     script_only: boolean;
 }
 export interface ConsolidationFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     /** A recorded decision that explains keeping both. On record is not a deduction. */
     on_record?: {
         file: string;