@bigsteele/the-prospect 0.1.1

package/README.md

@@ -0,0 +1,104 @@
+# The Prospect
+
+A prospector's read of your codebase and your market.
+
+You built fast, and the codebase remembers every day of it. Dependencies
+that stopped working for a living. The same block of code living in three
+files. Two vendors billing you for one job. A subsystem you wrote by hand
+in a weekend that the market now sells as an API. None of it was a bad
+decision. It accreted, and it has been nobody's job to notice.
+
+That is the ground you own. Then there is the territory: what your industry
+ships today that your code shows you are still doing the hard way. The
+credit-repair app parsing PDF reports by regex while report-access APIs
+deliver structured bureau data with no PDFs anywhere. Every vertical has
+its version of that, and finding yours is a research job, not a vibe.
+
+The Prospect does both halves.
+
+## What one run gets you
+
+```
+npx @bigsteele/the-prospect
+```
+
+Step 0 runs offline, reads everything, and writes two files into your repo:
+`the-prospect-<app>.md` and `.json`. In them:
+
+- **Lane 1 - what to subtract.** Dependencies with no reference found
+  anywhere, files no entrypoint reaches, duplicated blocks (copies that
+  announce themselves as deliberate are honoured, not flagged), jobs paid
+  for twice, subsystems built by hand where a rail exists, and paid calls
+  that multiply per row, per request, or on a clock. Every finding cites
+  its file. Every line is badged READ.
+- **The stack cut.** Platforms whose job a platform you already run can
+  carry: a vercel.json beside the Cloudflare account that already hosts
+  things, a Clerk bill beside the Supabase plan that includes auth, CI
+  workflows whose every step is an npm script the pushing machine runs
+  free. Both sides of each pair are read from your config files; whether
+  the kept platform's current plan truly carries the load is what the
+  research half verifies, with a source. Publish workflows with a registry
+  identity are never flagged: that is a job a laptop cannot do.
+- **A score out of 100** and a level, 0 Overgrown to 4 Sharp, with floors a
+  score cannot fake: an unreferenced paid service caps you at 2 no matter
+  how tidy the rest is.
+- **Your North Star, read, never invented** - from NORTH-STAR.md, your
+  planning docs, or PRODUCT.md, with the source named. If none exists, the
+  scan says UNKNOWN instead of guessing.
+- **Your industry fingerprint** - the domain vocabulary your own schema and
+  routes use, which is what the second half researches against.
+
+Then:
+
+```
+npx @bigsteele/the-prospect --run
+```
+
+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:
+
+```
+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.
+
+## Standalone
+
+One npx on a cold repository produces the full scan. No sibling scan
+installed, run, or required.
+
+## What it deliberately is not
+
+Not a linter, not a security review, not a design review; it runs nothing.
+Not a rewrite tool: it writes a report and changes no code. Not a vendor
+ad: two options minimum, always, with the trade stated. And Step 0 never
+touches the network - the research half runs only in the agent protocol,
+where every claim carries a source and a date, and the report marks every
+line as READ (from your repository) or RESEARCHED (from your market) so
+you always know which kind of fact you are holding.
+
+Read-only and offline. No network, no database, no shell, and it never
+opens an `.env` file. If any output string is shaped like a credential,
+nothing is written at all: a committed secret is the thing to fix first.
+
+## After the report
+
+**bigsteele.com/scan** - upload the report. You get a written read of the
+three moves worth making first and what each one buys. No call required to
+get it, and no pitch inside it. When you want the plan argued with a
+person: the $497 Scan Analysis call.
+
+Big Steele · bigsteele.com

package/dist/check.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The gate: measure a FINISHED Prospect report - the one the agent wrote -
+ * and fail it mechanically before a founder ever reads it.
+ *
+ * The family lesson from every scan before this one: a quality bar nothing
+ * measures drifts straight back to the writer's habits, and the writer here
+ * is a model. So the three-legged law is not a request in a prompt, it is
+ * a set of greps:
+ *
+ *   - every R&D suggestion carries all five anatomy lines
+ *   - every "Because" line carries a source URL and a year
+ *   - every "Have you considered" line carries at least two options
+ *   - banned register never appears (advice verbs, em dashes, horoscope)
+ *   - READ and RESEARCHED badges both exist - a report with no RESEARCHED
+ *     line skipped the research, and a report with no READ line skipped
+ *     the repository
+ */
+export interface CheckFinding {
+    where: string;
+    problem: string;
+    line?: string;
+}
+export declare function checkReport(md: string): {
+    pass: boolean;
+    findings: CheckFinding[];
+};

package/dist/check.js

@@ -0,0 +1,77 @@
+/**
+ * The gate: measure a FINISHED Prospect report - the one the agent wrote -
+ * and fail it mechanically before a founder ever reads it.
+ *
+ * The family lesson from every scan before this one: a quality bar nothing
+ * measures drifts straight back to the writer's habits, and the writer here
+ * is a model. So the three-legged law is not a request in a prompt, it is
+ * a set of greps:
+ *
+ *   - every R&D suggestion carries all five anatomy lines
+ *   - every "Because" line carries a source URL and a year
+ *   - every "Have you considered" line carries at least two options
+ *   - banned register never appears (advice verbs, em dashes, horoscope)
+ *   - READ and RESEARCHED badges both exist - a report with no RESEARCHED
+ *     line skipped the research, and a report with no READ line skipped
+ *     the repository
+ */
+const BANNED = [
+    { name: "advice (you should)", re: /\byou should\b/i },
+    { name: "advice (you must)", re: /\byou must\b/i },
+    { name: "advice (you need to)", re: /\byou need to\b/i },
+    { name: "em dash", re: /—/ },
+    { name: "certainty about the future", re: /\bwill (always|never|definitely)\b/i },
+    { name: "horoscope register", re: /\b(game.?changer|revolutioni[sz]e|unlock the power|supercharge|10x your)\b/i },
+];
+const ANATOMY = ["Since you", "Have you considered", "Because", "Your customer gets", "First test"];
+export function checkReport(md) {
+    const findings = [];
+    for (const b of BANNED) {
+        const lines = md.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (b.re.test(lines[i]))
+                findings.push({ where: `line ${i + 1}`, problem: b.name, line: lines[i].trim().slice(0, 100) });
+        }
+    }
+    if (!/\[READ\]/.test(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] ?? "";
+    const ranProtocol = !/not yet run/i.test(lane2Heading + lane2);
+    if (ranProtocol && lane2.trim()) {
+        if (!/\[RESEARCHED\]/.test(lane2Heading + lane2)) {
+            findings.push({ where: "Lane 2", problem: "no [RESEARCHED] badge - industry claims must be marked as researched" });
+        }
+        const blocks = lane2.split(/^### /m).slice(1);
+        if (blocks.length === 0) {
+            findings.push({ where: "Lane 2", problem: "protocol ran but no suggestion blocks found (### headings)" });
+        }
+        blocks.forEach((block, i) => {
+            const name = block.split("\n")[0]?.trim().slice(0, 60) ?? `suggestion ${i + 1}`;
+            for (const part of ANATOMY) {
+                if (!new RegExp(`\\*\\*${part}`, "i").test(block) && !new RegExp(`^${part}`, "im").test(block)) {
+                    findings.push({ where: name, problem: `missing anatomy line: "${part}"` });
+                }
+            }
+            // The Because leg needs a source and a date, or it is a vibe.
+            const because = /(?:\*\*Because\*\*|^Because)[:\s]([\s\S]*?)(?=\n\s*(?:\*\*|$))/im.exec(block)?.[1] ?? "";
+            if (because && !/https?:\/\//.test(because)) {
+                findings.push({ where: name, problem: "Because line has no source URL" });
+            }
+            if (because && !/\b20\d{2}\b/.test(because)) {
+                findings.push({ where: name, problem: "Because line has no date - an undated industry claim is a rumour" });
+            }
+            // Two options, or it reads as an ad.
+            const considered = /(?:\*\*Have you considered\*\*|^Have you considered)[:\s]([\s\S]*?)(?=\n\s*(?:\*\*|$))/im.exec(block)?.[1] ?? "";
+            if (considered && !/\bor\b/i.test(considered)) {
+                findings.push({ where: name, problem: "only one option offered - two vendors, or a vendor and the build-it-yourself path" });
+            }
+        });
+        if (blocks.length > 5) {
+            findings.push({ where: "Lane 2", problem: `${blocks.length} suggestions - the strongest five belong here, the rest in an appendix` });
+        }
+    }
+    return { pass: findings.length === 0, findings };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * The command line. Three things, meant to be run in this order:
+ *
+ *   (default)   Step 0: scan and report. Offline, read-only, writes only
+ *               the two report files.
+ *   --run       open Claude Code with the protocol: the industry half,
+ *               researched with sources and dates, against Step 0's facts.
+ *   --check     measure a finished report and fail it mechanically -
+ *               missing legs, unsourced claims, single-vendor pitches,
+ *               banned register.
+ *
+ * --check is the one that matters six months from now. The three-legged
+ * law is only a law while something fails reports that break it.
+ */
+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";
+const log = (s = "") => process.stdout.write(s + "\n");
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const valueOf = (f) => {
+    const i = args.indexOf(f);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+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
+
+  --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
+
+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";
+async function main() {
+    if (has("--help") || has("-h")) {
+        log(HELP);
+        return 0;
+    }
+    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());
+    if (has("--check")) {
+        const file = valueOf("--report");
+        let path = file ? resolve(file) : "";
+        if (!path) {
+            // The newest prospect report beside us.
+            const { readdir } = await import("node:fs/promises");
+            const names = (await readdir(repoDir)).filter((n) => /^the-prospect-.*\.md$/.test(n)).sort();
+            if (names.length === 0) {
+                log("No report to check. Run the scan first, then the protocol, then this.");
+                return 2;
+            }
+            path = join(repoDir, names[names.length - 1]);
+        }
+        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}` : ""}`);
+        log("");
+        log(`${findings.length} finding(s). A suggestion missing a leg is cut, not softened.`);
+        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("");
+        }
+        const child = spawn("claude", [`Follow the protocol in ${protocol}. The repository is ${repoDir}.`], {
+            stdio: "inherit",
+            shell: false,
+        });
+        return new Promise((res) => child.on("exit", (c) => res(c ?? 0)));
+    }
+    const p = await runProspect(repoDir);
+    const leak = secretShaped(p);
+    if (leak) {
+        log(`Refusing to write anything: the output contains something shaped like a credential (${leak}).`);
+        log("That means a secret is committed in this repository. Fix that first.");
+        return 1;
+    }
+    const md = toMarkdown(p);
+    if (has("--stdout")) {
+        log(md);
+    }
+    else {
+        const outDir = resolve(valueOf("--out") ?? repoDir);
+        const name = `the-prospect-${slug(p.app)}`;
+        await mkdir(outDir, { recursive: true });
+        await writeFile(join(outDir, `${name}.md`), md, "utf8");
+        await writeFile(join(outDir, `${name}.json`), JSON.stringify(p, null, 2), "utf8");
+        // Keep the reports out of the founder's diff without touching their .gitignore.
+        try {
+            await appendFile(join(repoDir, ".git", "info", "exclude"), `\n${name}.md\n${name}.json\n`);
+        }
+        catch {
+            // not a git repository, nothing to exclude
+        }
+        log(`Wrote ${name}.md and ${name}.json`);
+    }
+    const noRef = p.deps.filter((d) => !d.dev && d.no_reference_found).length;
+    log("");
+    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.`);
+    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)`);
+    return 0;
+}
+main().then((code) => process.exit(code), (err) => {
+    log(`the-prospect failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/detect/costs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cost surfaces: calls whose price multiplies.
+ *
+ * A model call costs a fraction of a cent. A model call in a request handler
+ * costs a fraction of a cent times every request, forever, and the invoice
+ * arrives a month after the code review that could have caught it. Three
+ * shapes multiply: per-request (inside a handler), per-row (inside a loop),
+ * and per-schedule (on a clock). The detector reports the shape and the
+ * line; whether the multiplication is worth it is the founder's call, made
+ * once, on purpose, instead of never.
+ */
+import type { Repo } from "../walk.js";
+import type { CostFact } from "./types.js";
+export declare function detectCosts(repo: Repo): Promise<CostFact[]>;

package/dist/detect/costs.js

@@ -0,0 +1,46 @@
+import { runtimeCode } 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|\()/;
+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];
+    return call ?? "external call";
+}
+export async function detectCosts(repo) {
+    const out = [];
+    for (const f of runtimeCode(repo.files)) {
+        const text = await repo.read(f);
+        if (!text || !PAID_CALL.test(text))
+            continue;
+        const lines = text.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!PAID_CALL.test(line))
+                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)) {
+                out.push({ file: f, shape: "per-row", target, line: evidence });
+                continue;
+            }
+            // per-schedule: the call sits under an interval or a cron marker.
+            if (SCHEDULE.test(above) || (SCHEDULE.test(text.slice(0, 800)) && SCHEDULE.test(f))) {
+                out.push({ file: f, shape: "per-schedule", target, line: evidence });
+                continue;
+            }
+            // per-request: the file is a request handler.
+            if (HANDLER.test(f)) {
+                out.push({ file: f, shape: "per-request", target, line: evidence });
+            }
+        }
+    }
+    // The loudest first: per-row beats per-request beats per-schedule.
+    const rank = { "per-row": 0, "per-request": 1, "per-schedule": 2 };
+    return out.sort((a, b) => rank[a.shape] - rank[b.shape]).slice(0, 40);
+}

package/dist/detect/deadweight.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime files no entrypoint reaches.
+ *
+ * Dead code is the quietest cost in a codebase: it is read by every new
+ * hire, matched by every search, weighed by every refactor, and it ships.
+ * Nobody deletes it because nobody can prove nothing uses it. This detector
+ * builds the import graph from every entrypoint and walks it; what the walk
+ * never touches is listed with the honest caption "no import path found
+ * from any entrypoint" - not "dead", because a file loaded by a string
+ * built at runtime imports nothing and lives anyway.
+ *
+ * Anything resembling config, declaration, or content is excluded before
+ * the walk: the detector's job is unreached BEHAVIOUR, not unreferenced
+ * markdown.
+ */
+import type { Repo } from "../walk.js";
+import type { DeadFact } from "./types.js";
+export declare function detectDeadweight(repo: Repo): Promise<{
+    dead: DeadFact[];
+    entrypoints: number;
+    aliases: Record<string, string>;
+}>;

package/dist/detect/deadweight.js

@@ -0,0 +1,137 @@
+import { CODE, TEST_FILE, NOT_RUNTIME } from "../walk.js";
+const NOT_BEHAVIOUR = /(\.d\.ts$)|(^|\/)((tailwind|postcss|vite|next|astro|svelte|eslint|prettier|babel|jest|vitest|playwright|tsup|drizzle)[^/]*\.config|vite-env|main\.d)/i;
+/** Entrypoints: where a runtime starts without any import naming the file. */
+function entrypoints(repo, manifests) {
+    const out = new Set();
+    for (const m of manifests) {
+        const dir = m.file.replace(/package\.json$/, "");
+        for (const b of m.bin)
+            out.add(dir + b.replace(/^\.\//, ""));
+        if (m.main)
+            out.add(dir + m.main.replace(/^\.\//, ""));
+    }
+    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) ||
+            /(^|\/)(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) ||
+            TEST_FILE.test(f) // tests reach code; code only tests reach is a different finding
+        ) {
+            out.add(f);
+        }
+    }
+    return [...out].filter((f) => repo.files.includes(f));
+}
+function specifiers(text) {
+    const out = [];
+    for (const re of [
+        /\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 m of text.matchAll(re))
+            out.push(m[1]);
+    }
+    return out;
+}
+const EXTS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", "/index.ts", "/index.tsx", "/index.js"];
+export async function detectDeadweight(repo) {
+    const fileSet = new Set(repo.files);
+    // Path aliases: the common `@/* -> src/*` and friends, read from tsconfig.
+    const aliases = {};
+    for (const tc of repo.files.filter((f) => /(^|\/)tsconfig[^/]*\.json$/.test(f))) {
+        const text = await repo.read(tc);
+        if (!text)
+            continue;
+        const paths = /"paths"\s*:\s*\{([\s\S]*?)\}/.exec(text)?.[1] ?? "";
+        for (const m of paths.matchAll(/"([^"]+)\/\*"\s*:\s*\[\s*"([^"]+)\/\*"/g)) {
+            const baseDir = tc.replace(/tsconfig[^/]*\.json$/, "");
+            aliases[m[1]] = (baseDir + m[2].replace(/^\.\//, "")).replace(/^\/+/, "");
+        }
+    }
+    const manifests = [];
+    for (const f of repo.files.filter((x) => /(^|\/)package\.json$/.test(x) && !/node_modules|fixtures?/.test(x))) {
+        const text = await repo.read(f);
+        if (!text)
+            continue;
+        try {
+            const j = JSON.parse(text);
+            const bin = typeof j.bin === "string" ? [j.bin] : Object.values(j.bin ?? {}).map(String);
+            manifests.push({ file: f, bin, main: typeof j.main === "string" ? j.main : undefined });
+        }
+        catch {
+            // a manifest that does not parse declares nothing
+        }
+    }
+    const resolve = (from, spec) => {
+        let path = null;
+        if (spec.startsWith(".")) {
+            const parts = from.split("/").slice(0, -1);
+            for (const seg of spec.split("/")) {
+                if (seg === "." || seg === "")
+                    continue;
+                else if (seg === "..")
+                    parts.pop();
+                else
+                    parts.push(seg);
+            }
+            path = parts.join("/");
+        }
+        else {
+            for (const [alias, target] of Object.entries(aliases)) {
+                if (spec === alias || spec.startsWith(alias + "/")) {
+                    path = spec.replace(alias, target);
+                    break;
+                }
+            }
+        }
+        if (!path)
+            return null;
+        const base = path.replace(/\.(js|mjs|cjs)$/, ""); // TS emits .js specifiers for .ts files
+        for (const candidate of [path, base]) {
+            for (const ext of EXTS) {
+                if (fileSet.has(candidate + ext))
+                    return candidate + ext;
+            }
+        }
+        return null;
+    };
+    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 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))
+            continue;
+        const text = await repo.read(f);
+        if (!text)
+            continue;
+        dead.push({
+            file: f,
+            loc: text.split("\n").length,
+            note: "no import path found from any entrypoint",
+        });
+    }
+    return {
+        dead: dead.sort((a, b) => b.loc - a.loc).slice(0, 60),
+        entrypoints: roots.length,
+        aliases,
+    };
+}

package/dist/detect/deps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The dependency roster: declared against actually seen.
+ *
+ * The exemplar repo declared 94 runtime dependencies. Nobody could say which
+ * ones worked for a living, because the only ledger was package.json and
+ * package.json records intentions, not usage. This detector reads every
+ * import and require in the repository and every config file that names a
+ * package as a string, and reports the difference.
+ *
+ * Honesty rule: the flag is `no_reference_found`, never "unused". A CLI tool
+ * invoked from an npm script, a peer dependency a plugin loads by name at
+ * runtime - these import nothing and still work. The report says what was
+ * looked for and not found, and lets the founder answer for the rest.
+ *
+ * The ways a package works without an import are looked for too, because each
+ * one was a false flag on a real app before it was: react-dom in a Next app
+ * (a peer of next), tw-animate-css (an `@import` in a stylesheet), @tiptap/pm
+ * (a peer of @tiptap/react), react-email (run as `email` from a script), and
+ * Capacitor plugins (registered by the native build from package.json).
+ */
+import type { Repo } from "../walk.js";
+import type { DepFact } from "./types.js";
+/** `@scope/pkg/deep/path` -> `@scope/pkg`; `pkg/deep` -> `pkg`. Relative and URL imports return null. */
+export declare function packageOf(spec: string): string | null;
+export declare function detectDeps(repo: Repo): Promise<DepFact[]>;