@bigsteele/the-prospect 0.1.1 → 0.2.0

package/dist/detect/deps 2.js

@@ -0,0 +1,198 @@
+const CONFIG_FILE = /(^|\/)(tailwind|postcss|vite|next|nuxt|astro|svelte|webpack|rollup|babel|jest|vitest|playwright|eslint|prettier|tsup|drizzle|prisma)[^/]*\.(config\.)?(ts|js|mjs|cjs|json)$|(^|\/)\.(eslintrc|babelrc|prettierrc)(\.[a-z]+)?$|(^|\/)(package|turbo|nx|lerna)\.json$/i;
+/** Nested manifests that describe fixtures or vendored copies, not this software. */
+const NOT_A_MANIFEST = /(^|\/)(test|tests|fixtures?|__fixtures__|examples?|templates?)\//i;
+/**
+ * Peers of the frameworks whose peers are used by the framework itself, for when
+ * node_modules is not installed and the real peerDependencies cannot be read.
+ */
+const FRAMEWORK_PEERS = {
+    next: ["react", "react-dom"],
+    gatsby: ["react", "react-dom"],
+    "@remix-run/react": ["react", "react-dom"],
+    expo: ["react", "react-native"],
+    "@monaco-editor/react": ["monaco-editor"],
+    "@tiptap/react": ["@tiptap/pm"],
+    "@tiptap/starter-kit": ["@tiptap/pm"],
+};
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function importSpecifiers(text) {
+    const out = [];
+    const patterns = [
+        /\bimport\s+(?:[^"'`]*?\s+from\s+)?["']([^"'\n]+)["']/g,
+        /\brequire\(\s*["']([^"'\n]+)["']\s*\)/g,
+        /\bimport\(\s*["']([^"'\n]+)["']\s*\)/g,
+        /\bexport\s+[^"'`\n]*?\s+from\s+["']([^"'\n]+)["']/g,
+    ];
+    for (const re of patterns) {
+        for (const m of text.matchAll(re))
+            out.push(m[1]);
+    }
+    return out;
+}
+/** `@scope/pkg/deep/path` -> `@scope/pkg`; `pkg/deep` -> `pkg`. Relative and URL imports return null. */
+export function packageOf(spec) {
+    if (spec.startsWith(".") || spec.startsWith("/") || /^(node:|https?:|npm:|jsr:)/.test(spec)) {
+        // Deno-style `npm:pkg@1` still names a package worth counting.
+        const npm = /^npm:(@?[^@/]+(?:\/[^@/]+)?)/.exec(spec);
+        return npm ? npm[1] : null;
+    }
+    const parts = spec.split("/");
+    return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+export async function detectDeps(repo) {
+    const manifests = repo.files.filter((f) => /(^|\/)package\.json$/.test(f) && !/node_modules/.test(f) && !NOT_A_MANIFEST.test(f));
+    const declared = [];
+    const scriptsByManifest = new Map();
+    for (const m of manifests) {
+        const text = await repo.read(m);
+        if (!text)
+            continue;
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            continue;
+        }
+        scriptsByManifest.set(m, Object.values(json.scripts ?? {}).filter((v) => typeof v === "string"));
+        for (const [dev, block] of [[false, json.dependencies], [true, json.devDependencies]]) {
+            for (const [name, version] of Object.entries(block ?? {})) {
+                declared.push({ name, version, manifest: m, dev, imported_by: 0, config_mentions: 0, no_reference_found: false });
+            }
+        }
+    }
+    if (declared.length === 0)
+        return [];
+    const byName = new Map();
+    for (const d of declared) {
+        const list = byName.get(d.name) ?? [];
+        list.push(d);
+        byName.set(d.name, list);
+    }
+    // Imports: every code file, tests included - a dependency only tests use is
+    // still referenced, and saying otherwise would be the lie this file bans.
+    const codeFiles = repo.files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|css|scss|sass|less|pcss)$/i.test(f) && !/node_modules/.test(f));
+    for (const f of codeFiles) {
+        const text = await repo.read(f);
+        if (!text)
+            continue;
+        const seen = new Set();
+        for (const spec of importSpecifiers(text)) {
+            const pkg = packageOf(spec);
+            if (pkg && !seen.has(pkg)) {
+                seen.add(pkg);
+                for (const d of byName.get(pkg) ?? [])
+                    d.imported_by++;
+            }
+        }
+        // Stylesheets: `@import "tw-animate-css"`, Tailwind 4's `@plugin "pkg"`, and
+        // Sass's `@use` / `@forward`.
+        if (/\.(css|scss|sass|less|pcss)$/i.test(f)) {
+            for (const m of text.matchAll(/@(?:import|plugin|use|forward)\s+(?:url\(\s*)?["']([^"'\n]+)["']/g)) {
+                const pkg = packageOf(m[1].replace(/^~/, ""));
+                if (pkg && !seen.has(pkg)) {
+                    seen.add(pkg);
+                    for (const d of byName.get(pkg) ?? [])
+                        d.imported_by++;
+                }
+            }
+        }
+    }
+    // Config mentions: plugins named as bare strings, and npm scripts that
+    // invoke a package's bin by name.
+    const configs = repo.files.filter((f) => CONFIG_FILE.test(f) && !/node_modules/.test(f));
+    for (const f of configs) {
+        const text = await repo.read(f);
+        if (!text)
+            continue;
+        for (const [name, list] of byName) {
+            const bare = name.replace(/^@[^/]+\//, "");
+            if (text.includes(`"${name}"`) || text.includes(`'${name}'`) || new RegExp(`\\b${escapeRe(bare)}\\b`).test(text)) {
+                for (const d of list)
+                    if (d.manifest !== f)
+                        d.config_mentions++;
+            }
+        }
+    }
+    // ── Used without an import ────────────────────────────────────────────────
+    const referenced = (d) => d.imported_by > 0 || d.config_mentions > 0 || !!d.required_by;
+    const installedCache = new Map();
+    const installed = async (d) => {
+        const key = `${d.manifest}|${d.name}`;
+        if (!installedCache.has(key))
+            installedCache.set(key, await repo.installed(d.manifest, d.name));
+        return installedCache.get(key);
+    };
+    // Run by bin name from the declaring manifest's own scripts. The loop above
+    // skips the declaring manifest, because its dependency list names every
+    // package, so its scripts are read here instead. The bin is not always the
+    // package name: react-email installs `email`.
+    for (const d of declared) {
+        if (referenced(d))
+            continue;
+        const scripts = scriptsByManifest.get(d.manifest) ?? [];
+        if (!scripts.length)
+            continue;
+        const bins = new Set([d.name.replace(/^@[^/]+\//, "")]);
+        const inst = await installed(d);
+        if (inst?.bin && typeof inst.bin === "object")
+            for (const b of Object.keys(inst.bin))
+                bins.add(b);
+        const hit = scripts.find((cmd) => [...bins].some((b) => new RegExp(`(^|[\\s;&|(])${escapeRe(b)}(\\s|$)`).test(cmd)));
+        if (hit)
+            d.required_by = `npm script: ${hit.length > 60 ? `${hit.slice(0, 57)}...` : hit}`;
+    }
+    // The JSX runtime. Every .tsx/.jsx file compiles to an import of `react` (or
+    // whatever jsxImportSource names) that no source file spells out.
+    if (repo.files.some((f) => /\.(tsx|jsx)$/.test(f) && !/node_modules/.test(f))) {
+        let source = "react";
+        for (const tc of repo.files.filter((f) => /(^|\/)(tsconfig|jsconfig)[^/]*\.json$/.test(f) && !NOT_A_MANIFEST.test(f))) {
+            const named = /"jsxImportSource"\s*:\s*"([^"]+)"/.exec((await repo.read(tc)) ?? "")?.[1];
+            if (named) {
+                source = packageOf(named) ?? source;
+                break;
+            }
+        }
+        for (const d of byName.get(source) ?? [])
+            if (!referenced(d))
+                d.required_by = "JSX runtime";
+    }
+    // Capacitor's native build registers every installed plugin from package.json.
+    if (repo.files.some((f) => /(^|\/)capacitor\.config\.(ts|js|json)$/.test(f))) {
+        for (const d of declared) {
+            if (!referenced(d) && /^(@capacitor\/|@capacitor-community\/|cordova-plugin-)/.test(d.name)) {
+                d.required_by = "native build (Capacitor)";
+            }
+        }
+    }
+    // Peers of packages in use. Read from the installed manifest when there is one
+    // (optional peers excluded), from the short framework list when there is not.
+    // Repeated until nothing changes, because a peer can have peers.
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const user of declared) {
+            if (!referenced(user))
+                continue;
+            const inst = await installed(user);
+            const peers = inst
+                ? Object.keys(inst.peerDependencies ?? {}).filter((p) => !inst.peerDependenciesMeta?.[p]?.optional)
+                : (FRAMEWORK_PEERS[user.name] ?? []);
+            for (const peer of peers) {
+                for (const d of byName.get(peer) ?? []) {
+                    // Resolvable from where the user is declared: the same manifest, or the root.
+                    if (referenced(d) || (d.manifest !== user.manifest && d.manifest !== "package.json"))
+                        continue;
+                    d.required_by = `peer of ${user.name}`;
+                    changed = true;
+                }
+            }
+        }
+    }
+    for (const d of declared) {
+        // Types-only and tooling-adjacent packages are referenced by the compiler,
+        // not by an import statement; they never earn the flag.
+        const toolingShaped = /^@types\//.test(d.name) || /(^|-)(cli|eslint|prettier|typescript|vitest|vite|tsx?|husky|lint-staged|concurrently|nodemon)($|-)/.test(d.name);
+        d.no_reference_found = !referenced(d) && !toolingShaped;
+    }
+    return declared.sort((a, b) => Number(b.no_reference_found) - Number(a.no_reference_found) || a.name.localeCompare(b.name));
+}

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,47 @@
-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 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);
+    }
+    if (hits.length === 0)
+        return 0;
+    const first = Math.min(...hits);
+    const last = Math.max(...hits);
+    return Math.min(lines.length, last - first + 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 +53,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,10 +74,18 @@ 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",
+        // 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: 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,
         rail_sdk: /["'](algoliasearch|meilisearch|typesense|@elastic|flexsearch|minisearch|fuse\.js)["']/,
@@ -46,7 +99,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 +120,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 +147,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 +172,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,12 @@ export interface WorkflowFact {
     script_only: boolean;
 }
 export interface ConsolidationFact {
+    /** 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))

package/dist/detect/types 2.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The fact shapes. Family rule: a field is either read from the repository or
+ * absent. Nothing in these types is an opinion; opinions belong to the agent
+ * protocol, and every one it forms must cite a field from here.
+ *
+ * The one register rule encoded structurally: findings carry the honest verb.
+ * A dependency is not "unused", it has "no reference found" - the difference
+ * is a CLI-only tool that ships to production anyway versus a lie in a report
+ * a founder pays attention to.
+ */
+/** One declared dependency and every place it was actually seen. */
+export interface DepFact {
+    name: string;
+    version: string;
+    /** Which manifest declared it, repository-relative. */
+    manifest: string;
+    dev: boolean;
+    /** Files whose import/require statements name this package. */
+    imported_by: number;
+    /** Config files that name it as a string (tailwind plugins, postcss, eslint). */
+    config_mentions: number;
+    /**
+     * Why it counts as used without an import or config mention, when that is the
+     * case: "peer of next", "npm script: email dev", "JSX runtime", "native build
+     * (Capacitor)".
+     */
+    required_by?: string;
+    /** True when no import, config mention, script, or package requiring it was found. */
+    no_reference_found: boolean;
+}
+export type VendorCategory = "ai" | "email" | "sms" | "payments" | "database" | "auth" | "storage" | "crm" | "analytics" | "monitoring" | "render" | "search" | "queue" | "maps" | "calendar" | "other";
+/** One external service the code talks to, with the evidence. */
+export interface VendorFact {
+    service: string;
+    category: VendorCategory;
+    /** How it was seen: an SDK import, an outbound URL, an env var NAME. Values never. */
+    evidence: Array<{
+        kind: "sdk" | "url" | "env";
+        what: string;
+        file: string;
+    }>;
+    call_sites: number;
+}
+/** Two or more services doing the same category of work. */
+export interface OverlapFact {
+    category: VendorCategory;
+    services: string[];
+    call_sites: number;
+}
+export type RailCategory = "pdf" | "rate-limiting" | "email-templating" | "auth-session" | "queue-scheduler" | "search" | "payments-logic" | "webhook-plumbing" | "parsing-ocr";
+/** A subsystem built by hand where the market sells a rail. */
+export interface HandrolledFact {
+    rail: RailCategory;
+    files: string[];
+    loc: number;
+    /** high: the file's name and its contents agree. low: contents only. */
+    confidence: "high" | "low";
+    /** The one line of evidence that convinced the detector, with its file. */
+    signal: {
+        file: string;
+        line: string;
+    };
+}
+/** A cluster of near-identical code living in more than one file. */
+export interface DuplicateFact {
+    files: string[];
+    /** Lines in the repeated block, after normalization. */
+    lines: number;
+    /** A header comment says the copy is deliberate ("copied from", "never imported"). */
+    deliberate: boolean;
+    /** First normalized line of the block, so a reader can find it. */
+    opens_with: string;
+}
+/** A runtime file no entrypoint reaches. */
+export interface DeadFact {
+    file: string;
+    loc: number;
+    /** Why the detector believes nothing reaches it. */
+    note: string;
+}
+/** A call whose cost multiplies: per request, per row, or on a clock. */
+export interface CostFact {
+    file: string;
+    shape: "per-request" | "per-row" | "per-schedule";
+    /** What is being called - a vendor host or an SDK call name. */
+    target: string;
+    /** The line that shows the shape (the loop, the handler, the interval). */
+    line: string;
+}
+/** Vocabulary the repository uses about its own domain, ranked by weight.
+ *  The CLI never names the industry; it hands the agent the evidence. */
+export interface Fingerprint {
+    terms: Array<{
+        term: string;
+        count: number;
+        sources: string[];
+    }>;
+    /** Where the terms came from: tables, routes, copy, manifest. */
+    note: string;
+}
+export interface NorthStar {
+    sentence: string | null;
+    source: "NORTH-STAR.md" | "planning" | "PRODUCT.md" | "heuristic" | "none";
+    confidence: "high" | "low" | "unknown";
+    note: string;
+}

package/dist/detect/types 2.js

@@ -0,0 +1,11 @@
+/**
+ * The fact shapes. Family rule: a field is either read from the repository or
+ * absent. Nothing in these types is an opinion; opinions belong to the agent
+ * protocol, and every one it forms must cite a field from here.
+ *
+ * The one register rule encoded structurally: findings carry the honest verb.
+ * A dependency is not "unused", it has "no reference found" - the difference
+ * is a CLI-only tool that ships to production anyway versus a lie in a report
+ * a founder pays attention to.
+ */
+export {};