@bigsteele/the-prospect 0.1.1 → 0.3.0

package/dist/detect/database.js

@@ -0,0 +1,198 @@
+import { scopeFor } from "../walk.js";
+/**
+ * Strip comments so a shape quoted in prose is not read as a declaration.
+ *
+ * NOT used when looking for a caller check. The convention for stating who may
+ * call a definer function is a `-- caller-check:` MARKER COMMENT, so stripping
+ * comments first destroys the exact evidence being looked for - which it did,
+ * and the fixture's correctly-guarded function was flagged alongside the
+ * unguarded one. Declarations are read from stripped text; guards from raw.
+ */
+function stripComments(sql) {
+    return sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ");
+}
+/**
+ * Split into statements on semicolons that are not inside a dollar-quoted body.
+ * A function body is full of semicolons and is one statement; splitting naively
+ * turns every definer function into a dozen fragments and the caller check into
+ * a fragment of its own, which is how a guard goes missing.
+ */
+function statements(sql) {
+    const out = [];
+    let buf = "";
+    let i = 0;
+    let tag = null;
+    while (i < sql.length) {
+        if (!tag) {
+            const m = /^\$([A-Za-z_]*)\$/.exec(sql.slice(i));
+            if (m) {
+                tag = m[0];
+                buf += tag;
+                i += tag.length;
+                continue;
+            }
+            if (sql[i] === ";") {
+                out.push(buf);
+                buf = "";
+                i++;
+                continue;
+            }
+        }
+        else if (sql.startsWith(tag, i)) {
+            buf += tag;
+            i += tag.length;
+            tag = null;
+            continue;
+        }
+        buf += sql[i];
+        i++;
+    }
+    if (buf.trim())
+        out.push(buf);
+    return out;
+}
+const QUALIFIED = /(?:([a-z_][a-z0-9_]*)\.)?([a-z_][a-z0-9_]*)/i;
+function qualify(raw) {
+    const m = QUALIFIED.exec(raw.replace(/"/g, ""));
+    if (!m)
+        return raw;
+    return `${m[1] ?? "public"}.${m[2]}`;
+}
+/**
+ * A definer function states who may call it, one of two ways: a marker comment
+ * naming the predicate, or a runtime check in the body. Either is a statement
+ * somebody can be held to; neither is proof it is correct, and the finding says
+ * "states no caller check", never "is insecure".
+ */
+const CALLER_CHECK = /caller-check|is_account_member|is_platform_staff|auth\.uid\s*\(\s*\)|auth\.role\s*\(\s*\)|current_setting\s*\(|has_role|raise\s+exception|assert\b/i;
+export async function detectDatabase(repo) {
+    // Migrations wherever they live; a `.sql.tmpl` shipped to a customer is the
+    // customer's database, so the template scope rules apply here as everywhere.
+    const files = scopeFor(repo.files, "database");
+    const rlsEnabled = new Set();
+    const rlsForced = new Set();
+    const tablesSeen = new Map();
+    const findings = [];
+    let policies = 0;
+    let definerFunctions = 0;
+    /**
+     * 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)
+            continue;
+        const sql = stripComments(raw);
+        for (const m of sql.matchAll(/alter\s+table\s+(?:if\s+exists\s+)?([a-z0-9_."]+)\s+([a-z\s]*row\s+level\s+security)/gi)) {
+            const t = qualify(m[1]);
+            if (/force/i.test(m[2]))
+                rlsForced.add(t);
+            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);
+        if (!raw)
+            continue;
+        const sql = stripComments(raw);
+        for (const m of sql.matchAll(/create\s+table\s+(?:if\s+not\s+exists\s+)?([a-z0-9_."]+)/gi)) {
+            const t = qualify(m[1]);
+            // `create policy p on public.x for select to public` contains the literal
+            // `table` nowhere, but a looser earlier pattern produced a table called
+            // `public.public` from exactly that line. A schema is not a table.
+            if (/^(public|auth|storage|extensions)\.(public|auth|storage)$/.test(t))
+                continue;
+            if (!tablesSeen.has(t))
+                tablesSeen.set(t, f);
+        }
+        // SPLIT THE RAW SQL, STRIP PER STATEMENT.
+        //
+        // The first version split the stripped text and the raw text separately and
+        // paired them by index, which silently drifts: removing comments removes
+        // semicolons inside them, so the two lists stop describing the same
+        // statements. On a real repository that reported 60 definer functions as
+        // stating no caller check when every one of them carried the marker - the
+        // failure mode this whole version exists to remove, arriving in the detector
+        // written to find it.
+        for (const withComments of statements(raw)) {
+            const stmt = stripComments(withComments);
+            if (/create\s+(or\s+replace\s+)?policy/i.test(stmt)) {
+                policies++;
+                const name = /create\s+(?:or\s+replace\s+)?policy\s+("?[a-z0-9_]+"?)/i.exec(stmt)?.[1]?.replace(/"/g, "");
+                // `to anon` hands the policy to unauthenticated callers. `to public`
+                // is the same reach by another name, since anon is a member of public.
+                if (name && /\bto\s+(anon|public)\b/i.test(stmt)) {
+                    findings.push({
+                        kind: "policy_reaches_anon",
+                        subject: name,
+                        file: f,
+                        note: "a policy granted to anon or public is readable by an unauthenticated caller. Deliberate for genuinely public rows, and worth one look per policy.",
+                    });
+                }
+            }
+            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) && !executeRevoked.has(qualify(name))) {
+                    findings.push({
+                        kind: "definer_without_check",
+                        subject: qualify(name),
+                        file: f,
+                        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.` : ""),
+                    });
+                }
+            }
+        }
+    }
+    for (const [t, f] of tablesSeen) {
+        if (!rlsEnabled.has(t)) {
+            findings.push({
+                kind: "table_without_rls",
+                subject: t,
+                file: f,
+                note: "no `enable row level security` anywhere in the migrations. Right for a lookup table nobody owns; a question for anything carrying one customer's rows.",
+            });
+        }
+        else if (!rlsForced.has(t)) {
+            findings.push({
+                kind: "rls_not_forced",
+                subject: t,
+                file: f,
+                note: "row level security is enabled but not forced, so the table owner bypasses it. Forcing it is one line and closes the gap.",
+            });
+        }
+    }
+    return {
+        files: files.length,
+        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/deps.js

@@ -61,6 +61,62 @@ export async function detectDeps(repo) {
             }
         }
     }
+    // MANIFESTS THAT ARE NOT package.json (0.2).
+    //
+    // The whole detector assumed npm, so a Python service with five pinned
+    // packages in requirements.txt read as a repository with no dependencies -
+    // and "no dependency with no reference found" then printed as a clean result
+    // rather than as a question never asked. Run across five repositories, that
+    // shape scored a six-file scraper at 96/100.
+    //
+    // Only formats simple enough to read without a parser, and each one's own
+    // reference test is the same as npm's: does any file name it.
+    for (const m of repo.files.filter((f) => /(^|\/)(requirements(-[a-z]+)?\.txt|pyproject\.toml|Gemfile|go\.mod|Cargo\.toml)$/.test(f) && !NOT_A_MANIFEST.test(f))) {
+        const text = await repo.read(m);
+        if (!text)
+            continue;
+        const base = m.split("/").pop();
+        if (/^requirements/.test(base)) {
+            for (const line of text.split("\n")) {
+                const t = line.trim();
+                if (!t || t.startsWith("#") || t.startsWith("-"))
+                    continue;
+                const name = /^([A-Za-z0-9._-]+)/.exec(t)?.[1];
+                const version = /[=<>~!]=?\s*([0-9][^\s;#]*)/.exec(t)?.[1] ?? "";
+                if (name)
+                    declared.push({ name, version, manifest: m, dev: /dev|test/i.test(base), imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+        }
+        else if (base === "pyproject.toml") {
+            // `dependencies = ["fastapi>=0.1", ...]` under [project] or poetry's table.
+            for (const dm of text.matchAll(/^\s*["']?([A-Za-z0-9._-]+)["']?\s*=\s*["'][\^~>=<0-9][^"']*["']/gm)) {
+                declared.push({ name: dm[1], version: "", manifest: m, dev: false, imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+            for (const dm of text.matchAll(/["']([A-Za-z0-9._-]+)\s*[>=<~!][^"']*["']/g)) {
+                declared.push({ name: dm[1], version: "", manifest: m, dev: false, imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+        }
+        else if (base === "go.mod") {
+            for (const dm of text.matchAll(/^\s+([a-z0-9.\-]+\/[^\s]+)\s+v[^\s]+/gm)) {
+                declared.push({ name: dm[1], version: "", manifest: m, dev: false, imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+        }
+        else if (base === "Cargo.toml" || base === "Gemfile") {
+            const re = base === "Gemfile" ? /gem\s+["']([A-Za-z0-9._-]+)["']/g : /^\s*([A-Za-z0-9._-]+)\s*=/gm;
+            for (const dm of text.matchAll(re)) {
+                const name = dm[1];
+                if (base === "Cargo.toml" && /^(name|version|edition|authors|license|description|repository|edition2021)$/.test(name))
+                    continue;
+                declared.push({ name, version: "", manifest: m, dev: false, imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+        }
+    }
+    // Deduplicate: pyproject's two patterns can both match one line.
+    const uniq = new Map();
+    for (const d of declared)
+        uniq.set(`${d.manifest}::${d.name}`, d);
+    declared.length = 0;
+    declared.push(...uniq.values());
     if (declared.length === 0)
         return [];
     const byName = new Map();

package/dist/detect/duplication.js

@@ -1,4 +1,4 @@
-import { runtimeCode } from "../walk.js";
+import { scopeFor } from "../walk.js";
 const WINDOW = 30;
 const MIN_FILES = 2;
 const GENERATED = /(^|\/)(.*\.gen\.|.*\.generated\.|types\/supabase|database\.types)/i;
@@ -17,7 +17,11 @@ function meaningful(lines) {
     return lines.filter((l) => l.length > 12).length >= WINDOW * 0.5;
 }
 export async function detectDuplication(repo) {
-    const files = runtimeCode(repo.files).filter((f) => !GENERATED.test(f));
+    // The duplication scope, not the runtime one: a block copied into a fixture or
+    // a test is still a block copied, and the shipped templates are where copies
+    // matter most - a generator emits them into a customer's repository, where a
+    // shared import cannot follow.
+    const files = scopeFor(repo.files, "duplication").filter((f) => !GENERATED.test(f));
     // hash of a window -> the places it occurs
     const windows = new Map();
     const fileLines = new Map();
@@ -69,10 +73,29 @@ export async function detectDuplication(repo) {
             });
         }
     }
+    // PARALLEL ADAPTERS DUPLICATE BY DESIGN (0.2). Reading the shipped templates
+    // surfaced 25 clusters on the first real repository, and the largest - a
+    // 265-line pair - floored the level. It was HarnessMount.tsx.tmpl under
+    // next-app-clerk/ and under next-app-supabase/: the same file for two customer
+    // stacks, inlined because a generated file cannot import from the generator.
+    // Same relative path, sibling directories, a parent named for what it is.
+    const PARALLEL_PARENT = /(^|\/)(adapters?|templates?|shells?|shell-templates?|generators?|stacks?|targets?)\//i;
+    const parallel = (files) => {
+        if (files.length < 2 || !files.every((f) => PARALLEL_PARENT.test(f)))
+            return false;
+        // Strip the one path segment that names the sibling; the rest must agree.
+        const tails = files.map((f) => {
+            const m = PARALLEL_PARENT.exec(f);
+            const after = f.slice(m.index + m[0].length);
+            return after.split("/").slice(1).join("/");
+        });
+        return tails.every((t) => t.length > 0 && t === tails[0]);
+    };
     return [...clusters.values()]
         .map((c) => ({
         ...c,
         deliberate: c.files.every((f) => deliberateFiles.has(f)) || c.files.filter((f) => deliberateFiles.has(f)).length >= c.files.length - 1,
+        parallel: parallel(c.files),
     }))
         .sort((x, y) => y.lines - x.lines)
         .slice(0, 25);

package/dist/detect/handrolled.js

@@ -1,9 +1,50 @@
-import { runtimeCode } from "../walk.js";
+import { scopeFor } from "../walk.js";
+/** How many of {named, implements, keeps state} a file showed. */
+function legs(r, file, text) {
+    let n = 0;
+    if (r.name?.test(file))
+        n++;
+    if (r.content.test(text))
+        n++;
+    if (r.requires ? r.requires.test(text) : false)
+        n++;
+    return n;
+}
+/**
+ * The lines that actually implement the subsystem, not the file that holds it.
+ *
+ * `countLines(text)` counted whole files, so a 700-line dashboard that mentioned
+ * the rail once contributed 700 lines to its "size". The region is the span from
+ * the first corroborating match to the last, which is a floor on the real
+ * subsystem and never a ceiling on the file.
+ */
+function regionLines(r, text) {
+    const lines = text.split("\n");
+    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 (starts.length === 0)
+        return 0;
+    return Math.min(lines.length, Math.max(...ends) - Math.min(...starts) + 1);
+}
 const RULES = [
     {
         rail: "pdf",
         name: /pdf|report.?pars|extract/i,
         content: /%PDF-|getTextContent|pdftotext|pdf.{0,12}(parse|extract|text)|(parse|extract).{0,12}pdf/i,
+        // The third leg, which this rule always implied and never stated: pulling
+        // fields OUT. A file that merely names a PDF and mentions one is a download
+        // button; a file that names one, reads its text and runs capture groups over
+        // it is a parser. The owner's worked example shows all three.
+        requires: /\.(exec|match|matchAll)\(|\/[^/\n]{3,}\/[gimsuy]*\.exec|\((\?<[a-z]+>|\[)/i,
         rail_sdk: /["'](pdf-parse|pdfjs-dist|@pdf-lib|unpdf|pdf2json)["']/,
     },
     {
@@ -15,7 +56,14 @@ const RULES = [
     },
     {
         rail: "email-templating",
+        // NAME REQUIRED. `<table` within 4,000 characters of `.send(` described an
+        // ops dashboard on the first real repository, and the report gave it a size.
+        name: /email|mail(er)?|template|notif/i,
+        name_required: true,
         content: /<(html|body|table)[\s>][\s\S]{0,4000}(sendEmail|sendMail|\.send\(|resend|smtp)/i,
+        // The third leg: a template is a template because something is interpolated
+        // into it. A static string is a string.
+        requires: /\$\{[^}]+\}|\{\{[^}]+\}\}|<%=?[\s\S]{0,80}%>|\.replace\(/,
         rail_sdk: /["'](@react-email|react-email|mjml|maizzle|handlebars)["']/,
     },
     {
@@ -29,12 +77,26 @@ const RULES = [
         rail: "queue-scheduler",
         name: /queue|worker|scheduler|cron|jobs?/i,
         content: /(setInterval|setTimeout)[\s\S]{0,300}(fetch|process|poll|dequeue|claim)|status\s*=\s*["']pending["'][\s\S]{0,400}(update|claim|lock)/i,
+        // The third leg: a queue keeps work somewhere and marks it done. A `sleep`
+        // helper in a device-flow poller is not a scheduler, and was reported as
+        // 1,265 lines of one.
+        requires: /(pending|queued|processing|claimed?|attempts?|retry|retries|dead.?letter)\b[\s\S]{0,400}(update|insert|set\(|save|delete|ack)/i,
         rail_sdk: /["'](bullmq|bee-queue|agenda|bree|graphile-worker|@trigger\.dev|inngest|temporalio)["']/,
     },
     {
         rail: "search",
-        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,
+        // 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,
+        // 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)["']/,
     },
     {
@@ -46,7 +108,11 @@ const RULES = [
     },
     {
         rail: "webhook-plumbing",
+        name: /webhook|hook|signature|signing/i,
         content: /(createHmac|timingSafeEqual)[\s\S]{0,400}(signature|x-signature|svix|webhook)/i,
+        // The third leg: verifying a signature needs the secret and the header it
+        // arrived in. A file that only defines `timingSafeEqual` is a utility.
+        requires: /(headers?|req\.headers|request\.headers)[\s\S]{0,200}(signature|hmac)|process\.env\.[A-Z_]*(SECRET|SIGNING)/i,
         rail_sdk: /["'](svix|@hono\/webhook)["']/,
     },
     {
@@ -63,7 +129,7 @@ const RULES = [
 ];
 const countLines = (t) => t.split("\n").length;
 export async function detectHandrolled(repo) {
-    const files = runtimeCode(repo.files);
+    const files = scopeFor(repo.files, "implementation");
     // A rail SDK anywhere in the repository retires that rule everywhere: the
     // decision to buy was already made, and re-litigating it is noise.
     const railInUse = new Set();
@@ -90,8 +156,15 @@ export async function detectHandrolled(repo) {
             const named = r.name ? r.name.test(f) : false;
             if (r.name_required && !named)
                 continue;
+            // THREE LEGS IN ONE FILE, or this file is not part of the subsystem.
+            // A rule with no `name` or no `requires` can only ever show two, so it
+            // must carry both to contribute: a rail defined by content alone is the
+            // shape that produced "email templating" from a dashboard's `<table`.
+            if (legs(r, f, text) < 3)
+                continue;
             const cur = byRail.get(r.rail) ?? { files: new Map(), signal: { file: f, line: "" }, named: false };
-            cur.files.set(f, countLines(text));
+            // The implementing region, not the whole file.
+            cur.files.set(f, regionLines(r, text));
             cur.named = cur.named || named;
             if (!cur.signal.line) {
                 const at = text.slice(0, m.index).split("\n").length;
@@ -108,5 +181,11 @@ export async function detectHandrolled(repo) {
         confidence: (r.named ? "high" : "low"),
         signal: r.signal,
     }))
+        // CONFIDENCE NOW GATES (0.2). It was computed and never used: five
+        // low-confidence rails printed as fact, with sizes, under a heading that
+        // said "built by hand where the market sells a rail", and the score counted
+        // them. A finding nothing corroborates is a question; the report has a place
+        // for questions and it is not this list.
+        .filter((h) => h.confidence === "high" && h.loc > 0)
         .sort((a, b) => b.loc - a.loc);
 }

package/dist/detect/stack.d.ts

@@ -45,6 +45,14 @@ 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;
+        line: number;
+        excerpt: string;
+    };
     /** The platform or service the repo already runs, that would remain. */
     keep: string;
     /** The candidate to cut. */

package/dist/detect/stack.js

@@ -1,4 +1,4 @@
-import { NOT_RUNTIME } from "../walk.js";
+import { scopeFor } from "../walk.js";
 const HOSTING = [
     { platform: "Vercel", files: /(^|\/)vercel\.json$|(^|\/)\.vercel\/project\.json$/ },
     { platform: "Netlify", files: /(^|\/)netlify\.toml$/ },
@@ -154,7 +154,15 @@ export async function detectStack(repo) {
  *  directories, docs, fixtures and this package's own tree are excluded by
  *  the same rule the walker's detectors use. */
 async function grepAny(repo, re, limit) {
-    const files = repo.files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|toml|jsonc?)$/i.test(f) && !NOT_RUNTIME.test(f) && !/node_modules|fixtures?|templates?|(^|\/)package(-lock)?\.json$/.test(f)).slice(0, limit);
+    // ASK FOR THE SCOPE BY NAME (0.2). This line used to re-derive its own, and
+    // omitted the one term `runtimeCode` had: test files. So `@auth0/nextjs-auth0`,
+    // quoted as a STRING inside a scanner's test describing a customer's codebase,
+    // read as this product importing Auth0 - and the report told an owner to drop a
+    // vendor they never had. That was the fourth self-contamination variant in this
+    // family, each one a call site that forgot a term the others remembered.
+    const files = scopeFor(repo.files, "vendor-presence")
+        .filter((f) => !/(^|\/)package(-lock)?\.json$/.test(f))
+        .slice(0, limit);
     for (const f of files) {
         const text = await repo.read(f);
         if (text && re.test(text))