@bigsteele/the-prospect 0.1.1

package/dist/northstar.js

@@ -0,0 +1,95 @@
+// Root-anchored on purpose: a NORTH-STAR.md inside a fixture, a template, or
+// a vendored package is someone else's mission. The first host-repo run read
+// this package's own lean fixture as the host's North Star, which is the
+// exact self-contamination bug the family review caught in wiremap.
+const UNKNOWN_NOTE = "No North Star found. The protocol derives one with the operator before any suggestion is written; without it, neither lane can tell overbuilt from essential.";
+function section(md, heading) {
+    const lines = md.split("\n");
+    const at = lines.findIndex((l) => /^#{1,4}\s/.test(l) && heading.test(l));
+    if (at < 0)
+        return null;
+    const body = [];
+    for (const l of lines.slice(at + 1)) {
+        if (/^#{1,4}\s/.test(l))
+            break;
+        if (l.trim())
+            body.push(l.trim());
+    }
+    return body.length ? body.join(" ") : null;
+}
+const clean = (s) => s.replace(/\*\*/g, "").replace(/^[-*]\s*/, "").trim();
+/** A README whose opening is the generator's, not the product's. */
+const SCAFFOLD_README = /welcome to your \w+ project|## project info|\*\*URL\*\*: https:\/\/(lovable|bolt|v0)\.|this project (was )?(bootstrapped|generated) with|## getting started[\s\S]{0,200}(npm run dev|yarn dev|pnpm dev)/i;
+const SCAFFOLD = /\b(lovable|bolt\.new|v0\.dev|start prompting|create[- ]react[- ]app|vite|getting started|npm (run|install)|yarn (dev|install)|pnpm (dev|install)|this (template|starter|boilerplate|scaffold)|bootstrapped with|generated (by|with)|quick ?start|installation|prerequisites)\b/i;
+export async function readNorthStar(repo) {
+    const nsFile = repo.files.find((f) => /^NORTH-STAR\.md$/i.test(f));
+    if (nsFile) {
+        const md = await repo.read(nsFile);
+        if (md) {
+            const sentence = section(md, /one sentence/i) ?? section(md, /north star/i);
+            return {
+                sentence: sentence ? clean(sentence).slice(0, 400) : null,
+                source: "NORTH-STAR.md",
+                confidence: sentence ? "high" : "low",
+                note: sentence ? "" : "NORTH-STAR.md exists but states no one-sentence purpose.",
+            };
+        }
+    }
+    const planFile = repo.files.find((f) => /^\.planning\/[^/]*north-star[^/]*\.md$/i.test(f));
+    if (planFile) {
+        const md = await repo.read(planFile);
+        const sentence = md ? section(md, /one sentence/i) ?? section(md, /north star/i) : null;
+        if (sentence) {
+            return { sentence: clean(sentence).slice(0, 400), source: "planning", confidence: "high", note: "" };
+        }
+    }
+    const productFile = repo.files.find((f) => /^PRODUCT\.md$/i.test(f));
+    if (productFile) {
+        const md = await repo.read(productFile);
+        const purpose = md ? section(md, /product purpose/i) ?? section(md, /purpose/i) : null;
+        if (purpose) {
+            return { sentence: clean(purpose).slice(0, 400), source: "PRODUCT.md", confidence: "high", note: "" };
+        }
+    }
+    const readme = repo.files.find((f) => /^README\.md$/i.test(f));
+    if (readme) {
+        const md = await repo.read(readme);
+        if (md && SCAFFOLD_README.test(md.slice(0, 600))) {
+            return {
+                sentence: null,
+                source: "none",
+                confidence: "unknown",
+                note: `The README is still the scaffold's own, so it states no mission to read. ${UNKNOWN_NOTE}`,
+            };
+        }
+        if (md) {
+            const para = md.split("\n").find((l) => {
+                const x = l.trim();
+                if (x.length <= 60)
+                    return false;
+                if (/^[#>|\-![]/.test(x) || /^<!--/.test(x) || /^<[a-z]/i.test(x) || /^(```|:::)/.test(x))
+                    return false;
+                const prose = x
+                    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+                    .replace(/\bhttps?:\/\/\S+/gi, " ")
+                    .replace(/`[^`]*`/g, " ")
+                    .replace(/\*\*/g, "")
+                    .trim();
+                if (prose.replace(/^\s*[A-Za-z ]{1,20}:\s*/, "").trim().length < 40)
+                    return false;
+                if (prose.split(/\s+/).length < 8)
+                    return false;
+                return !SCAFFOLD.test(prose);
+            });
+            if (para) {
+                return {
+                    sentence: clean(para).slice(0, 300),
+                    source: "heuristic",
+                    confidence: "low",
+                    note: "Read from the README's first paragraph, not from a stated North Star.",
+                };
+            }
+        }
+    }
+    return { sentence: null, source: "none", confidence: "unknown", note: UNKNOWN_NOTE };
+}

package/dist/report.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Step 0 report: the deterministic half, written for a founder.
+ *
+ * Every line here is READ - a fact from the repository. The RESEARCHED
+ * lines (the industry half, Lane 2) do not exist yet; the protocol adds
+ * them, and the report says so plainly instead of leaving a gap a reader
+ * would mistake for "nothing found".
+ *
+ * The refusal branch is the most important part of the file, family
+ * lesson: a scan that found nothing must say the scan could not see, never
+ * "you pass". An empty vendor roster on a repo with 90 dependencies means
+ * the detector missed, not that the founder pays no one.
+ */
+import type { Prospect } from "./index.js";
+export declare function secretShaped(p: Prospect): string | null;
+export declare function toMarkdown(p: Prospect): string;

package/dist/report.js

@@ -0,0 +1,166 @@
+const CATEGORY_LABEL = {
+    ai: "AI", email: "email", sms: "SMS", payments: "payments", database: "database",
+    auth: "auth", storage: "storage", crm: "CRM", analytics: "analytics",
+    monitoring: "monitoring", render: "rendering", search: "search", queue: "queues",
+    maps: "maps", calendar: "calendar", other: "other",
+};
+const label = (c) => CATEGORY_LABEL[c] ?? c;
+const prose = (items) => items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+const SECRET = /\b(sk-[A-Za-z0-9_-]{20,}|sk_(live|test)_[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{30,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}|AIza[0-9A-Za-z_-]{30,}|pit-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+export function secretShaped(p) {
+    const m = SECRET.exec(JSON.stringify(p));
+    return m ? `${m[1].slice(0, 6)}…` : null;
+}
+export function toMarkdown(p) {
+    const L = [];
+    const noRef = p.deps.filter((d) => !d.dev && d.no_reference_found);
+    const accidental = p.duplicates.filter((d) => !d.deliberate);
+    const highHand = p.handrolled.filter((h) => h.confidence === "high");
+    const cuts = p.stack.consolidations;
+    L.push(`# The Prospect: ${p.app}`, "");
+    // The headline is an argument, not a metric.
+    const claims = [];
+    if (noRef.length)
+        claims.push(`**${noRef.length} of ${p.totals.runtime_deps}** dependencies show no reference anywhere`);
+    if (p.overlaps.length)
+        claims.push(`**${p.overlaps.length}** job${p.overlaps.length > 1 ? "s are" : " is"} paid for twice`);
+    if (highHand.length)
+        claims.push(`**${highHand.length}** subsystem${highHand.length > 1 ? "s" : ""} built by hand where the market sells a rail`);
+    if (cuts.length)
+        claims.push(`**${cuts.length}** platform${cuts.length > 1 ? "s" : ""} another platform you already run can cover`);
+    if (p.dead.length)
+        claims.push(`**${p.dead.length}** files no entrypoint reaches`);
+    const sawLittle = claims.length === 0 && accidental.length === 0 && p.cost_surfaces.length === 0;
+    if (sawLittle) {
+        // The refusal branch. Silence is not a pass.
+        L.push(`The scan read ${p.totals.files} files and could not build a case either way. That is a`, `finding about the scan, not a clean bill: the repository may be too small, written in a`, `language the detectors do not read well, or genuinely tight. The market half below is`, `still worth running - a lean codebase can still be missing what its industry now ships.`, "");
+    }
+    else {
+        L.push(claims.slice(0, 2).join(", and ") + ".", "");
+    }
+    L.push(`## Today / After`, "");
+    L.push(`| Today | After |`);
+    L.push(`| --- | --- |`);
+    if (noRef.length)
+        L.push(`| ${noRef.length} packages installed, updated and audited that nothing imports | They are gone, and every install, update and security audit is smaller |`);
+    if (p.overlaps.length) {
+        const o = p.overlaps[0];
+        L.push(`| ${prose(o.services)} ${o.services.length > 2 ? "all" : "both"} do ${label(o.category)} work | One vendor does it, one invoice, one integration to maintain |`);
+    }
+    if (highHand.length) {
+        const h = highHand[0];
+        L.push(`| ${h.loc} lines of hand-rolled ${h.rail} code you maintain alone | A decision on record: keep it on purpose, or a rail carries it |`);
+    }
+    if (cuts.length) {
+        const c = cuts[0];
+        L.push(`| ${c.candidate} runs beside ${c.keep}, which already covers ${c.covers.split(" (")[0]} | One platform, one bill, one place a deploy can fail |`);
+    }
+    if (p.dead.length)
+        L.push(`| ${p.dead.length} files everyone reads, searches and ships but nothing runs | Deleted, with this report as the receipt |`);
+    L.push(`| Suggestions arrive as opinions | Every suggestion stands on a fact in your code, a sourced fact from your market, and your North Star |`);
+    L.push("");
+    L.push(`## Score`, "");
+    L.push(`**${p.score.total}/100 (${p.score.grade})** - Level ${p.score.level.n}: **${p.score.level.name}**. ${p.score.level.meaning}`, "");
+    for (const f of p.score.floors)
+        L.push(`- ${f}`);
+    if (p.score.floors.length)
+        L.push("");
+    if (p.score.deductions.length) {
+        L.push(`| What cost points | Points | Evidence |`);
+        L.push(`| --- | --- | --- |`);
+        for (const d of p.score.deductions)
+            L.push(`| ${d.what} | ${d.points} | ${d.evidence} |`);
+        L.push("");
+    }
+    L.push(`## North Star`, "");
+    if (p.north_star.sentence) {
+        L.push(`> ${p.north_star.sentence}`, "");
+        L.push(`Read from ${p.north_star.source} (confidence: ${p.north_star.confidence}). ${p.north_star.note}`.trim(), "");
+    }
+    else {
+        L.push(p.north_star.note, "");
+    }
+    L.push(`## Lane 1 - what to subtract [READ]`, "");
+    L.push(`Every line in this lane was read from the repository. Nothing here is a guess.`, "");
+    if (noRef.length) {
+        L.push(`### Dependencies with no reference found`, "");
+        L.push(`| Package | Declared in | Looked for |`);
+        L.push(`| --- | --- | --- |`);
+        for (const d of noRef.slice(0, 25))
+            L.push(`| ${d.name} | ${d.manifest} | imports in every code file, names in every config: none found |`);
+        if (noRef.length > 25)
+            L.push(`| …and ${noRef.length - 25} more in the JSON | | |`);
+        L.push("");
+        L.push(`A package can earn its keep without an import (a CLI run from a script, a plugin loaded by name at runtime). This table is the list to answer for, not a kill list.`, "");
+    }
+    if (p.overlaps.length) {
+        L.push(`### Jobs paid for twice`, "");
+        for (const o of p.overlaps) {
+            L.push(`- **${label(o.category)}**: ${o.services.join(" + ")} (${o.call_sites} call sites). One category of work, ${o.services.length} vendors, ${o.services.length} invoices, ${o.services.length} places a key can leak.`);
+        }
+        L.push("");
+    }
+    if (p.handrolled.length) {
+        L.push(`### Built by hand where the market sells a rail`, "");
+        L.push(`| Subsystem | Size | Confidence | The line that shows it |`);
+        L.push(`| --- | --- | --- | --- |`);
+        for (const h of p.handrolled)
+            L.push(`| ${h.rail} (${h.files.length} file${h.files.length > 1 ? "s" : ""}) | ${h.loc} lines | ${h.confidence} | \`${h.signal.file}:${h.signal.line.replace(/\|/g, "\\|")}\` |`);
+        L.push("");
+        L.push(`Hand-rolled is not wrong. Half of these are the right call - control, cost, no vendor risk. The protocol researches the actual rails and puts the trade in front of you as a question, never a verdict.`, "");
+    }
+    if (cuts.length) {
+        L.push(`### The stack cut: platforms another platform already covers`, "");
+        L.push(`Both sides of every pair below were 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.`, "");
+        for (const c of cuts) {
+            L.push(`- **Keep ${c.keep}, question ${c.candidate}.** ${c.keep} covers ${c.covers}. Evidence: \`${c.evidence_keep}\` and \`${c.evidence_candidate}\`. ${c.note}`);
+        }
+        L.push("");
+        const so = p.stack.workflows.filter((w) => w.script_only);
+        if (so.length) {
+            L.push(`| Workflow | Triggers | Every step is |`);
+            L.push(`| --- | --- | --- |`);
+            for (const w of so.slice(0, 8))
+                L.push(`| \`${w.file}\` | ${w.triggers.join(", ") || "?"} | ${w.runs.slice(0, 3).join(" ; ").replace(/\|/g, "\\|")} |`);
+            L.push("");
+            L.push(`A workflow that publishes with a registry identity is doing a job a laptop cannot. These are not those: every step is an npm script, and the same line runs free as a pre-push check.`, "");
+        }
+    }
+    if (accidental.length) {
+        L.push(`### The same code in more than one place`, "");
+        for (const d of accidental.slice(0, 10)) {
+            L.push(`- ${d.lines} matching lines across ${d.files.join(", ")} - opens with \`${d.opens_with}\``);
+        }
+        const deliberate = p.duplicates.length - accidental.length;
+        if (deliberate > 0)
+            L.push(`- (${deliberate} further cop${deliberate > 1 ? "ies" : "y"} announce themselves as deliberate in a header comment; a copy that says so is a decision, not a debt.)`);
+        L.push("");
+    }
+    if (p.dead.length) {
+        L.push(`### Files no entrypoint reaches`, "");
+        L.push(`From ${p.totals.entrypoints} entrypoints, the import walk never arrived at these. A file loaded by a path built at runtime can still be alive - this is the list to answer for.`, "");
+        for (const d of p.dead.slice(0, 20))
+            L.push(`- \`${d.file}\` (${d.loc} lines)`);
+        if (p.dead.length > 20)
+            L.push(`- …and ${p.dead.length - 20} more in the JSON`);
+        L.push("");
+    }
+    if (p.cost_surfaces.length) {
+        L.push(`### Paid calls that multiply`, "");
+        L.push(`| Shape | Target | Where |`);
+        L.push(`| --- | --- | --- |`);
+        for (const c of p.cost_surfaces.slice(0, 15))
+            L.push(`| ${c.shape} | ${c.target} | \`${c.file}:${c.line.replace(/\|/g, "\\|")}\` |`);
+        L.push("");
+        L.push(`Per-row is the loud one: a paid call inside a loop bills once per record, forever. Worth deciding once, on purpose.`, "");
+    }
+    L.push(`## Lane 2 - what the territory holds [RESEARCHED - not yet run]`, "");
+    L.push(`This lane needs research your machine must not do on its own: the vendor and API landscape`, `of your industry, with sources and dates. Run \`npx @bigsteele/the-prospect --run\` and an`, `agent researches it against the facts above. Every suggestion it may make must stand on`, `three legs - a fact read from your code, a fact researched from your market, and your North`, `Star - and ends with what your customer gets. Anything short of that is cut, not softened.`, "");
+    L.push(`The evidence it starts from - your repository's own vocabulary:`, "");
+    L.push(p.fingerprint.terms.slice(0, 15).map((t) => `\`${t.term}\``).join(" ") || "(fingerprint too thin - the agent will ask what the business is)", "");
+    L.push(`## Send this in`, "");
+    L.push(`**bigsteele.com/scan** Upload this file. 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.`, "");
+    L.push(`---`, "");
+    L.push(`Step 0 is read-only and offline. No network, no database, no shell, and it never opens an`, `\`.env\` file. It never copies your source into the report beyond the single evidence lines`, `cited above. Not a security review, not a linter, not a design review; it runs nothing.`, "", `Big Steele · bigsteele.com`);
+    return L.join("\n");
+}

package/dist/score.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The score: distance from "every part earns its place".
+ *
+ * Only Lane 1 scores. Opportunity is not gradable - a repo cannot lose
+ * points for the R&D nobody has researched yet - so the number measures
+ * what the deterministic half saw: references that go nowhere, code no
+ * entrypoint reaches, the same block living in several files, two vendors
+ * doing one job, and subsystems hand-rolled where a rail exists.
+ *
+ * Levels carry floors a score cannot fake, family rule. A tidy repository
+ * with one vendor SDK it never imports is still paying for a thing it does
+ * not use, and no arithmetic talks its way past that.
+ */
+import type { DepFact, DuplicateFact, DeadFact, HandrolledFact, OverlapFact, CostFact } from "./detect/types.js";
+import type { ConsolidationFact } from "./detect/stack.js";
+export interface ProspectScore {
+    total: number;
+    grade: string;
+    level: {
+        n: 0 | 1 | 2 | 3 | 4;
+        name: string;
+        meaning: string;
+    };
+    /** Every deduction, so the number can be argued with rather than trusted. */
+    deductions: Array<{
+        what: string;
+        points: number;
+        evidence: string;
+    }>;
+    floors: string[];
+}
+export declare function grade(total: number): string;
+export interface ScoreInput {
+    deps: DepFact[];
+    overlaps: OverlapFact[];
+    handrolled: HandrolledFact[];
+    duplicates: DuplicateFact[];
+    dead: DeadFact[];
+    costs: CostFact[];
+    /** Platforms whose job another platform already present can carry. */
+    consolidations?: ConsolidationFact[];
+    /** Total runtime files, for shares. */
+    runtime_files: number;
+    /** True when a vendor SDK dependency itself has no reference found - paying for a thing never called. */
+    unused_paid_service: string | null;
+}
+export declare function scoreProspect(input: ScoreInput): ProspectScore;

package/dist/score.js

@@ -0,0 +1,93 @@
+export function grade(total) {
+    if (total >= 97)
+        return "A+";
+    if (total >= 93)
+        return "A";
+    if (total >= 90)
+        return "A-";
+    if (total >= 87)
+        return "B+";
+    if (total >= 83)
+        return "B";
+    if (total >= 80)
+        return "B-";
+    if (total >= 77)
+        return "C+";
+    if (total >= 73)
+        return "C";
+    if (total >= 70)
+        return "C-";
+    if (total >= 60)
+        return "D";
+    return "F";
+}
+const LEVELS = [
+    { n: 0, name: "Overgrown", meaning: "Dead weight, duplicates and doubled vendors in most categories. The codebase carries more than it uses, and everyone who touches it pays the freight." },
+    { n: 1, name: "Heavy", meaning: "The system works, but several categories carry weight nothing uses: unreferenced packages, unreached files, or a vendor paid twice." },
+    { n: 2, name: "Trimmed", meaning: "Most parts earn their place. What remains is a short, specific list rather than a habit." },
+    { n: 3, name: "Lean", meaning: "Little is carried that is not used. Hand-rolled subsystems remain, but each is small or clearly a choice." },
+    { n: 4, name: "Sharp", meaning: "Nothing unaccounted for: every dependency referenced, every file reached, one vendor per job, and every hand-rolled subsystem is a recorded decision." },
+];
+export function scoreProspect(input) {
+    const deductions = [];
+    const ding = (what, points, evidence) => {
+        if (points > 0)
+            deductions.push({ what, points: Math.round(points * 10) / 10, evidence });
+    };
+    const runtimeDeps = input.deps.filter((d) => !d.dev);
+    const noRef = runtimeDeps.filter((d) => d.no_reference_found);
+    // Unreferenced runtime dependencies: up to 20.
+    ding("dependencies with no reference found", Math.min(20, noRef.length * 2), noRef.length ? `${noRef.length} of ${runtimeDeps.length} runtime dependencies` : "");
+    // Files no entrypoint reaches: up to 20, by share of runtime files.
+    const deadShare = input.runtime_files > 0 ? input.dead.length / input.runtime_files : 0;
+    ding("files no entrypoint reaches", Math.min(20, Math.round(deadShare * 100)), input.dead.length ? `${input.dead.length} files (${Math.round(deadShare * 100)} in 100)` : "");
+    // Accidental duplicate clusters: up to 20. Deliberate copies cost nothing.
+    const accidental = input.duplicates.filter((d) => !d.deliberate);
+    const dupLines = accidental.reduce((t, d) => t + d.lines * (d.files.length - 1), 0);
+    ding("duplicated blocks not marked deliberate", Math.min(20, Math.round(dupLines / 40)), accidental.length ? `${accidental.length} clusters, ${dupLines} repeated lines` : "");
+    // Vendor overlap: up to 20. Two vendors in one category is a doubled bill.
+    ding("two or more vendors doing one job", Math.min(20, input.overlaps.length * 7), input.overlaps.length ? input.overlaps.map((o) => `${o.category}: ${o.services.join(" + ")}`).join("; ") : "");
+    // Hand-rolled where a rail exists: up to 12, high-confidence only.
+    const high = input.handrolled.filter((h) => h.confidence === "high");
+    ding("hand-rolled subsystems with rails available", Math.min(12, high.length * 4), high.length ? high.map((h) => h.rail).join(", ") : "");
+    // The stack cut: up to 12. A platform another platform already covers is
+    // a bill and a failure surface, and nobody decided to have both.
+    const consolidations = input.consolidations ?? [];
+    ding("platforms another platform already covers", Math.min(12, consolidations.length * 4), consolidations.length ? consolidations.map((c) => `${c.candidate} (covered by ${c.keep})`).join("; ") : "");
+    // Multiplying cost shapes: up to 8; per-row is the loud one.
+    const perRow = input.costs.filter((c) => c.shape === "per-row").length;
+    ding("paid calls that multiply per row", Math.min(8, perRow * 4), perRow ? `${perRow} loops around a paid call` : "");
+    const total = Math.max(0, 100 - deductions.reduce((t, d) => t + d.points, 0));
+    // Floors, then the level the remaining score allows.
+    const floors = [];
+    let cap = 4;
+    if (input.unused_paid_service) {
+        cap = Math.min(cap, 2);
+        floors.push(`A paid service (${input.unused_paid_service}) that nothing references caps the level at 2: a bill with no work behind it is the first one to stop.`);
+    }
+    const bigDup = accidental.find((d) => d.lines > 200);
+    if (bigDup) {
+        cap = Math.min(cap, 3);
+        floors.push(`A duplicate block over 200 lines (${bigDup.files.join(", ")}) caps the level at 3.`);
+    }
+    let n;
+    if (total >= 93)
+        n = 4;
+    else if (total >= 82)
+        n = 3;
+    else if (total >= 68)
+        n = 2;
+    else if (total >= 50)
+        n = 1;
+    else
+        n = 0;
+    if (n > cap)
+        n = cap;
+    return {
+        total: Math.round(total),
+        grade: grade(Math.round(total)),
+        level: LEVELS[n],
+        deductions: deductions.sort((a, b) => b.points - a.points),
+        floors,
+    };
+}

package/dist/walk.d.ts

@@ -0,0 +1,44 @@
+export interface Repo {
+    root: string;
+    name: string;
+    /** Every file considered, repository-relative with forward slashes. */
+    files: string[];
+    /** Text of a file, or null when it is not text, too large, an env file, or unreadable. */
+    read(rel: string): Promise<string | null>;
+    /** Files whose path matches. */
+    matching(re: RegExp): string[];
+    /** Directories skipped because they are a repository of their own or a copy of this one. */
+    skipped: string[];
+    /**
+     * The manifest of an INSTALLED package, looked up the way Node resolves it: from
+     * the directory of the manifest that declares it, up to the root. Null when it is
+     * not installed. node_modules is never walked; this reads one file on request.
+     */
+    installed(fromManifest: string, pkg: string): Promise<InstalledManifest | null>;
+}
+export interface InstalledManifest {
+    bin?: string | Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+}
+export declare function openRepo(root: string): Promise<Repo>;
+/** Files whose text matches; each hit carries the count of matches. Reads at most `limit` files. */
+export declare function grep(repo: Repo, files: string[], re: RegExp, limit?: number): Promise<Array<{
+    file: string;
+    count: number;
+}>>;
+/** Code files only: what the detectors read for behaviour. */
+export declare const CODE: RegExp;
+/** Test files, which describe behaviour but do not run in production. */
+export declare const TEST_FILE: RegExp;
+/**
+ * Not the running software: documentation trees, fixtures, golden files, and this
+ * auditor's own package when it is audited from inside the repository that holds it.
+ * The first run counted the auditor's detector source as an MCP server, a Bedrock
+ * integration and a human gate in the host repository.
+ */
+export declare const NOT_RUNTIME: RegExp;
+/** Files the detectors read for behaviour: code, in the runtime tree, not tests. */
+export declare function runtimeCode(files: string[]): string[];

package/dist/walk.js

@@ -0,0 +1,123 @@
+// Copied from ai-audit/src/walk.ts, never imported, so the package stays independently
+// deployable (family convention). The only place that touches the filesystem. Walks a repository, skips what is not the
+// project's own code, reads text files under a size cap, and never opens an env file.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".vercel", ".turbo", "coverage", "vendor", "dist.bak", ".cache", "__pycache__", ".venv", "venv", "target", "test-results", "playwright-report", ".chrome-debug", ".claude-browser"]);
+// Stylesheets are read too: `@import "tw-animate-css"` and Tailwind 4's `@plugin`
+// are how a whole class of packages is used, and a walker that listed .css files
+// but never read them flagged every one of those packages as unreferenced.
+const TEXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|php|java|kt|swift|sql|json|jsonc|ya?ml|toml|md|mdx|txt|prisma|graphql|gql|env\.example|sh|css|scss|sass|less|pcss)$/i;
+const ENV_FILE = /(^|\/)\.env(\.[a-z0-9_-]+)?$/i;
+const MAX_BYTES = 512 * 1024;
+const MAX_FILES = 25_000;
+export async function openRepo(root) {
+    const files = [];
+    const skipped = [];
+    const rootName = root.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
+    const walk = async (dir, depth) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const names = new Set(entries.map((e) => e.name));
+        // A directory below the root that is a repository of its own (its own .git), or a
+        // copy of this one (named like the root, with its own manifest), is not this
+        // software: Brokrr's audit counted a nested Brokrr/ twice and cited both.
+        if (depth > 0 && (names.has(".git") || (dir.split(/[\\/]/).pop() === rootName && names.has("package.json")))) {
+            skipped.push(relative(root, dir).split(sep).join("/"));
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (files.length >= MAX_FILES)
+                return;
+            const abs = join(dir, e.name);
+            if (e.isSymbolicLink())
+                continue;
+            if (e.isDirectory()) {
+                // dist-demo, build_old, out-web: build output under any suffix.
+                if (SKIP_DIRS.has(e.name) || /^(dist|build|out)([-_.][a-z0-9-]*)?$/i.test(e.name))
+                    continue;
+                await walk(abs, depth + 1);
+            }
+            else if (e.isFile()) {
+                files.push(relative(root, abs).split(sep).join("/"));
+            }
+        }
+    };
+    await walk(root, 0);
+    const cache = new Map();
+    const name = root.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? root;
+    return {
+        root,
+        name,
+        files,
+        skipped,
+        async read(rel) {
+            if (cache.has(rel))
+                return cache.get(rel);
+            let text = null;
+            if (TEXT.test(rel) && !ENV_FILE.test(rel)) {
+                try {
+                    const s = await stat(join(root, rel));
+                    if (s.size <= MAX_BYTES)
+                        text = await readFile(join(root, rel), "utf8");
+                }
+                catch {
+                    text = null;
+                }
+            }
+            cache.set(rel, text);
+            return text;
+        },
+        matching(re) {
+            return files.filter((f) => re.test(f));
+        },
+        async installed(fromManifest, pkg) {
+            const parts = fromManifest.split("/").slice(0, -1);
+            for (let i = parts.length; i >= 0; i--) {
+                const abs = join(root, ...parts.slice(0, i), "node_modules", ...pkg.split("/"), "package.json");
+                try {
+                    return JSON.parse(await readFile(abs, "utf8"));
+                }
+                catch {
+                    // not installed at this level
+                }
+            }
+            return null;
+        },
+    };
+}
+/** Files whose text matches; each hit carries the count of matches. Reads at most `limit` files. */
+export async function grep(repo, files, re, limit = 4000) {
+    const out = [];
+    const flags = re.flags.includes("g") ? re.flags : re.flags + "g";
+    const global = new RegExp(re.source, flags);
+    for (const f of files.slice(0, limit)) {
+        const text = await repo.read(f);
+        if (!text)
+            continue;
+        const count = (text.match(global) ?? []).length;
+        if (count > 0)
+            out.push({ file: f, count });
+    }
+    return out;
+}
+/** Code files only: what the detectors read for behaviour. */
+export const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|php|java|kt|swift)$/i;
+/** Test files, which describe behaviour but do not run in production. */
+export const TEST_FILE = /(^|\.|_|\/)(test|spec|e2e)s?(\.|\/)|(^|\/)__tests__\//i;
+/**
+ * Not the running software: documentation trees, fixtures, golden files, and this
+ * auditor's own package when it is audited from inside the repository that holds it.
+ * The first run counted the auditor's detector source as an MCP server, a Bedrock
+ * integration and a human gate in the host repository.
+ */
+export const NOT_RUNTIME = /(^|\/)(docs?|fixtures?|__fixtures__|__mocks__|golden|examples?|samples?|packages\/the-prospect)\/|(^|\/)\.(?!well-known\/)[^/]+\//i;
+/** Files the detectors read for behaviour: code, in the runtime tree, not tests. */
+export function runtimeCode(files) {
+    return files.filter((f) => CODE.test(f) && !TEST_FILE.test(f) && !NOT_RUNTIME.test(f));
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bigsteele/the-prospect",
+  "version": "0.1.1",
+  "description": "A prospector's read of your codebase and your market. Digs the ground you own: every dependency that does no work, every vendor you pay twice, every subsystem you built by hand where a rail now exists. Then surveys the territory: what your industry ships by API that your code still does the hard way. Every suggestion stands on three legs - a fact read from your code, a fact researched from your market with a source and a date, and the thing your product exists to do. Standalone: one npx, no other scan required.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": "Big Steele (Together Inc.)",
+  "homepage": "https://bigsteele.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bigsteele/blank-canvas-project.git",
+    "directory": "packages/the-prospect"
+  },
+  "bin": {
+    "the-prospect": "dist/cli.js",
+    "prospect": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "prompt",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}