@bigsteele/the-prospect 0.1.1 → 0.3.0

package/dist/detect/types.d.ts

@@ -10,6 +10,8 @@
  */
 /** One declared dependency and every place it was actually seen. */
 export interface DepFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     name: string;
     version: string;
     /** Which manifest declared it, repository-relative. */
@@ -27,6 +29,16 @@ export interface DepFact {
     required_by?: string;
     /** True when no import, config mention, script, or package requiring it was found. */
     no_reference_found: boolean;
+    /** A recorded decision that explains it, when one does. On record is not a deduction. */
+    on_record?: OnRecord;
+    /** Which workflow this touches, by path. A heuristic, named as one. */
+    touches?: string;
+}
+/** Where the decision record explains a finding. */
+export interface OnRecord {
+    file: string;
+    line: number;
+    excerpt: string;
 }
 export type VendorCategory = "ai" | "email" | "sms" | "payments" | "database" | "auth" | "storage" | "crm" | "analytics" | "monitoring" | "render" | "search" | "queue" | "maps" | "calendar" | "hosting" | "ci" | "other";
 /** One external service the code talks to, with the evidence. */
@@ -43,13 +55,27 @@ export interface VendorFact {
 }
 /** Two or more services doing the same category of work. */
 export interface OverlapFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     category: VendorCategory;
     services: string[];
     call_sites: number;
+    /** What each service was seen doing inside the category, when the code says. */
+    roles?: Record<string, string[]>;
+    /**
+     * Set when the code shows the services doing DIFFERENT jobs inside one
+     * category - Stripe processing on a merchant's own account beside Square
+     * billing the platform, Gemini writing text beside Replicate making images.
+     * A category is not a job. Listed, never deducted; the text is the reason.
+     */
+    distinct?: string;
+    on_record?: OnRecord;
 }
 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 {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     rail: RailCategory;
     files: string[];
     loc: number;
@@ -60,9 +86,13 @@ export interface HandrolledFact {
         file: string;
         line: string;
     };
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A cluster of near-identical code living in more than one file. */
 export interface DuplicateFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     files: string[];
     /** Lines in the repeated block, after normalization. */
     lines: number;
@@ -70,16 +100,37 @@ export interface DuplicateFact {
     deliberate: boolean;
     /** First normalized line of the block, so a reader can find it. */
     opens_with: string;
+    /**
+     * The files sit at the same relative path under sibling directories of an
+     * adapters/templates tree: parallel implementations for different stacks,
+     * which duplicate by design because a generated file cannot import from the
+     * generator. Reported, never deducted.
+     */
+    parallel?: boolean;
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A runtime file no entrypoint reaches. */
 export interface DeadFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     file: string;
     loc: number;
     /** Why the detector believes nothing reaches it. */
     note: string;
+    /**
+     * A UI-kit scaffold component (shadcn's `components.json` beside it) that no
+     * file imports. Never bundled, so it does not ship; still read and searched.
+     * Listed at a quarter of the weight.
+     */
+    scaffold?: boolean;
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A call whose cost multiplies: per request, per row, or on a clock. */
 export interface CostFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     file: string;
     shape: "per-request" | "per-row" | "per-schedule";
     /** What is being called - a vendor host or an SDK call name. */
@@ -104,3 +155,28 @@ export interface NorthStar {
     confidence: "high" | "low" | "unknown";
     note: string;
 }
+/** A shape in the migrations worth a human minute. Never a verdict. */
+export interface DatabaseFinding {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
+    kind: "table_without_rls" | "rls_not_forced" | "definer_without_check" | "policy_reaches_anon";
+    /** The table, function or policy, schema-qualified where it has one. */
+    subject: string;
+    file: string;
+    note: string;
+}
+/**
+ * What the migrations hold. The counts ride with the findings on purpose: an
+ * empty finding list and a scan that never opened a file must not read alike.
+ */
+export interface DatabaseReading {
+    files: number;
+    tables: number;
+    policies: number;
+    definer_functions: number;
+    /** Definer functions whose EXECUTE the migrations revoke from public, anon or authenticated. */
+    definer_execute_revoked: number;
+    /** A guard function the repository carries to check definer grants at runtime, when one is named. */
+    guard?: string;
+    findings: DatabaseFinding[];
+}

package/dist/detect/vendors.js

@@ -1,4 +1,4 @@
-import { runtimeCode } from "../walk.js";
+import { scopeFor, isCode } from "../walk.js";
 /** The map earns a row when a vendor is common enough that a founder would
  *  recognise the name. Everything else lands in "unrecognised outbound". */
 const KNOWN = [
@@ -53,10 +53,47 @@ const KNOWN = [
     { service: "Cal.com", category: "calendar", hosts: /api\.cal\.com$/, env: /^CAL_/ },
     { service: "Calendly", category: "calendar", hosts: /api\.calendly\.com$/, env: /^CALENDLY_/ },
 ];
+const ROLES = {
+    payments: [
+        {
+            role: "processes on a merchant's own account (Connect or OAuth markers)",
+            merchant: true,
+            re: /\/v1\/accounts\b|stripe[-_]account|on_behalf_of|transfer_data|application_fee|oauth2\/(token|authorize|revoke)|refresh_token|merchant_id|connected_account/i,
+        },
+        {
+            role: "bills the platform's own account (subscriptions, its own checkout)",
+            re: /\bsubscriptions?\b|\/v1\/checkout\/sessions|\/v2\/(checkout|subscriptions|invoices)|\binvoices?\b|price_id|\bplan_id\b/i,
+        },
+    ],
+    ai: [
+        { role: "writes text", re: /generateContent|chat\/completions|\/v1\/messages\b|messages\.create|\/completions\b|\bembeddings\b|responses\.create/i },
+        { role: "makes images", re: /\/predictions\b|images\.(generate|edit)|\/images\/generations|\bimagen\b|nano-banana|stable-diffusion|\bsdxl\b|\bflux[-/]|dall-e/i },
+        { role: "makes speech or audio", re: /text-to-speech|\/v1\/audio\/|speech\.create|audio\.transcriptions/i },
+    ],
+};
+/**
+ * A role belongs to a vendor only when it sits ON that vendor's call: the line
+ * that names the vendor, or the few lines under it that finish the same call.
+ * "Nearest vendor within forty lines" credited Gemini with making images because
+ * a `predictions:` type field sat thirty lines from its URL.
+ */
+const ROLE_REACH = 30; // lines under the vendor's line; the role regexes are endpoint-shaped, so this reach stays safe
+/** Every KNOWN service a single line names, by host, env var or import. */
+function vendorsOnLine(line, only) {
+    const out = [];
+    const host = /https?:\/\/([a-z0-9][a-z0-9.-]+\.[a-z]{2,})/i.exec(line)?.[1]?.toLowerCase();
+    const env = /([A-Z][A-Z0-9_]{2,})/.exec(line)?.[1];
+    const spec = /["']((?:npm:)?@?[a-z0-9][a-z0-9._/-]*)["']/i.exec(line)?.[1]?.replace(/^npm:/, "");
+    for (const k of only) {
+        if ((host && k.hosts?.test(host)) || (env && k.env?.test(env)) || (spec && k.sdks?.test(spec)))
+            out.push(k);
+    }
+    return out;
+}
 /** Hosts that are content, not services: fonts, CDNs of the app's own assets, social links. */
 const NOISE_HOST = /(^|\.)(esm\.sh|cdn\.jsdelivr\.net|unpkg\.com|fonts\.(googleapis|gstatic)\.com|githubusercontent\.com|github\.com|linkedin\.com|x\.com|twitter\.com|instagram\.com|facebook\.com|youtube\.com|tiktok\.com|schema\.org|w3\.org|localhost)$/i;
 export async function detectVendors(repo) {
-    const files = runtimeCode(repo.files);
+    const files = scopeFor(repo.files, "vendor-presence").filter(isCode);
     const byService = new Map();
     const touch = (k, kind, what, file) => {
         const v = byService.get(k.service) ?? { service: k.service, category: k.category, evidence: [], call_sites: 0 };
@@ -71,8 +108,13 @@ export async function detectVendors(repo) {
         const text = await repo.read(f);
         if (!text)
             continue;
-        for (const m of text.matchAll(/\bfrom\s+["']([^"'\n]+)["']|\brequire\(\s*["']([^"'\n]+)["']\s*\)/g)) {
-            const spec = (m[1] ?? m[2]);
+        // LANGUAGE-NEUTRAL IMPORTS (0.2). The vendor table is already neutral - an
+        // SDK name, a host, an env var - and only the extraction was JavaScript, so
+        // a Python service importing `stripe` read as using no payment vendor at
+        // all. Python `import x` / `from x import y`, Go's quoted import paths and
+        // Ruby's `require` all name the package the same way npm does.
+        for (const m of text.matchAll(/\bfrom\s+["']([^"'\n]+)["']|\brequire\(\s*["']([^"'\n]+)["']\s*\)|^\s*import\s+([a-z0-9_.]+)|^\s*from\s+([a-z0-9_.]+)\s+import\b|^\s*require\s+["']([^"'\n]+)["']/gim)) {
+            const spec = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5]);
             if (spec.startsWith("."))
                 continue;
             const pkg = spec.replace(/^npm:/, "").split("/").slice(0, spec.startsWith("@") || spec.startsWith("npm:@") ? 2 : 1).join("/");
@@ -93,8 +135,10 @@ export async function detectVendors(repo) {
                 unknownHosts.set(host, set);
             }
         }
-        for (const m of text.matchAll(/process\.env\.([A-Z][A-Z0-9_]{2,})|Deno\.env\.get\(\s*["']([A-Z][A-Z0-9_]{2,})["']\s*\)/g)) {
-            const name = (m[1] ?? m[2]);
+        // Same reasoning for environment variables: `os.environ["STRIPE_SECRET_KEY"]`
+        // and `os.getenv(...)` name a vendor exactly as `process.env.` does.
+        for (const m of text.matchAll(/process\.env\.([A-Z][A-Z0-9_]{2,})|Deno\.env\.get\(\s*["']([A-Z][A-Z0-9_]{2,})["']\s*\)|os\.(?:environ(?:\.get)?\(?\[?|getenv\()\s*["']([A-Z][A-Z0-9_]{2,})["']|ENV\[["']([A-Z][A-Z0-9_]{2,})["']\]|os\.Getenv\(\s*["']([A-Z][A-Z0-9_]{2,})["']/g)) {
+            const name = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5]);
             for (const k of KNOWN)
                 if (k.env?.test(name))
                     touch(k, "env", name, f);
@@ -111,11 +155,67 @@ export async function detectVendors(repo) {
     for (const [category, list] of byCategory) {
         if (category === "other" || list.length < 2)
             continue;
-        overlaps.push({
+        const o = {
             category,
             services: list.map((v) => v.service),
             call_sites: list.reduce((t, v) => t + v.call_sites, 0),
-        });
+        };
+        const roleTable = ROLES[category];
+        if (roleTable) {
+            // Roles, read from the lines near each vendor's own markers.
+            const known = list.map((v) => KNOWN.find((k) => k.service === v.service));
+            const roles = new Map(); // service -> role -> where
+            const evidenceFiles = new Set(list.flatMap((v) => v.evidence.map((e) => e.file)));
+            for (const f of evidenceFiles) {
+                const text = await repo.read(f);
+                if (!text)
+                    continue;
+                const lines = text.split("\n");
+                const marks = [];
+                lines.forEach((line, i) => {
+                    for (const k of vendorsOnLine(line, known))
+                        marks.push({ at: i, k });
+                });
+                if (!marks.length)
+                    continue;
+                lines.forEach((line, i) => {
+                    for (const r of roleTable) {
+                        if (!r.re.test(line))
+                            continue;
+                        let best = null;
+                        for (const m of marks) {
+                            const d = i - m.at; // the vendor line itself, or lines under it
+                            if (d >= 0 && d <= ROLE_REACH && (!best || d < best.d))
+                                best = { d, k: m.k };
+                        }
+                        if (!best)
+                            continue;
+                        const mine = roles.get(best.k.service) ?? new Map();
+                        if (!mine.has(r.role))
+                            mine.set(r.role, `${f}:${i + 1}`);
+                        roles.set(best.k.service, mine);
+                    }
+                });
+            }
+            if (roles.size)
+                o.roles = Object.fromEntries([...roles].map(([s, m]) => [s, [...m.keys()]]));
+            const merchantRole = roleTable.find((r) => r.merchant);
+            const merchants = merchantRole ? o.services.filter((s) => roles.get(s)?.has(merchantRole.role)) : [];
+            if (merchants.length) {
+                const where = merchants.map((s) => `${s} (${roles.get(s).get(merchantRole.role)})`).join(" and ");
+                o.distinct = `${where} ${merchants.length > 1 ? "carry" : "carries"} Connect or OAuth markers: charging on a merchant's own account. A second processor beside that is a merchant's choice of where their sales land, not the platform paying twice.`;
+            }
+            else if (o.services.every((s) => roles.get(s)?.size)) {
+                const sets = o.services.map((s) => new Set(roles.get(s).keys()));
+                const disjoint = sets.every((a, i) => sets.every((b, j) => i === j || ![...a].some((r) => b.has(r))));
+                if (disjoint) {
+                    o.distinct =
+                        o.services.map((s) => `${s} ${[...roles.get(s).entries()].map(([r, w]) => `${r} (${w})`).join(" and ")}`).join("; ") +
+                            ". One category, two jobs.";
+                }
+            }
+        }
+        overlaps.push(o);
     }
     const unrecognised = [...unknownHosts.entries()]
         .map(([host, set]) => ({ host, files: [...set].slice(0, 5) }))

package/dist/index.d.ts

@@ -1,8 +1,13 @@
+import { type Coverage } from "./walk.js";
 import { type StackReading } from "./detect/stack.js";
+import { type RepoProfile } from "./profile.js";
+import { type DecisionRecord } from "./decisions.js";
 import { type ProspectScore } from "./score.js";
-import type { CostFact, DeadFact, DepFact, DuplicateFact, Fingerprint, HandrolledFact, NorthStar, OverlapFact, VendorFact } from "./detect/types.js";
+import type { CostFact, DeadFact, DepFact, DatabaseReading, DuplicateFact, Fingerprint, HandrolledFact, NorthStar, OverlapFact, VendorFact } from "./detect/types.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
+export { checkVerdicts, rescore, showMath, findingIds } from "./verdicts.js";
+export type { Verdicts, VerdictRecord, EvidenceEntry, Verdict } from "./verdicts.js";
 export type { ProspectScore } from "./score.js";
 export interface Prospect {
     format: "bigsteele-prospect/1";
@@ -24,6 +29,14 @@ export interface Prospect {
     dead: DeadFact[];
     cost_surfaces: CostFact[];
     fingerprint: Fingerprint;
+    /** What the migrations hold, and the shapes in them worth a minute. */
+    database: DatabaseReading;
+    /** What kind of repository this is, and which questions it could answer. */
+    profile: RepoProfile;
+    /** The decision record that was read, so "on record" can be checked. */
+    decisions: DecisionRecord;
+    /** Every file walked, in exactly one bucket, each with the rule that put it there. */
+    coverage: Coverage;
     score: ProspectScore;
     totals: {
         files: number;
@@ -32,5 +45,5 @@ export interface Prospect {
         entrypoints: number;
     };
 }
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.3.0";
 export declare function runProspect(root: string): Promise<Prospect>;

package/dist/index.js

@@ -20,7 +20,7 @@
  * run, or required.
  */
 import { openRepo } from "./walk.js";
-import { runtimeCode } from "./walk.js";
+import { runtimeCode, coverageOf } from "./walk.js";
 import { detectDeps } from "./detect/deps.js";
 import { detectVendors } from "./detect/vendors.js";
 import { detectHandrolled } from "./detect/handrolled.js";
@@ -29,11 +29,15 @@ import { detectDeadweight } from "./detect/deadweight.js";
 import { detectCosts } from "./detect/costs.js";
 import { detectFingerprint } from "./detect/fingerprint.js";
 import { detectStack } from "./detect/stack.js";
+import { detectDatabase } from "./detect/database.js";
 import { readNorthStar } from "./northstar.js";
+import { profileRepo } from "./profile.js";
+import { Decisions, touches } from "./decisions.js";
 import { scoreProspect } from "./score.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
-export const VERSION = "0.1.1";
+export { checkVerdicts, rescore, showMath, findingIds } from "./verdicts.js";
+export const VERSION = "0.3.0";
 export async function runProspect(root) {
     const repo = await openRepo(root);
     const runtime = runtimeCode(repo.files);
@@ -48,13 +52,91 @@ export async function runProspect(root) {
         readNorthStar(repo),
         detectStack(repo),
     ]);
+    const database = await detectDatabase(repo);
+    // READ WHAT WAS DECIDED BEFORE REPORTING WHAT WAS BUILT (0.2). Every Lane 1
+    // finding is checked against the record; one the record explains is marked
+    // on record with the citation, listed so the reader sees the tool looked, and
+    // not deducted. A dependency loaded by name, a copy inlined on purpose, a
+    // second vendor kept on purpose: each was reported as drift before this.
+    const record = await Decisions.read(repo);
+    const few = record.critical_few;
+    // A file is named to the record by its path fragment, never its bare stem:
+    // `session` matches half the record, `shell-templates/react/src/session` does not.
+    const frag = (f) => {
+        const parts = f.replace(/\.tmpl$/, "").split("/");
+        const stem = parts.pop().replace(/\.[^.]+$/, "");
+        const dir = parts.pop();
+        return dir ? [`${dir}/${stem}`, f] : [stem, f];
+    };
+    for (const d of deps) {
+        if (!d.no_reference_found)
+            continue;
+        d.on_record = record.explains([d.name]) ?? undefined;
+        d.touches = touches(d.manifest, few);
+    }
+    // A pair is decided by an entry naming BOTH sides: "Vercel's nameservers"
+    // alone is not a decision to run Vercel beside Cloudflare.
+    for (const o of vendorsReading.overlaps)
+        o.on_record = record.explains(o.services, { all: true }) ?? undefined;
+    for (const o of stack.overlaps)
+        o.on_record = record.explains(o.services, { all: true }) ?? undefined;
+    for (const c of stack.consolidations)
+        c.on_record = record.explains([c.candidate, c.keep], { all: true }) ?? undefined;
+    for (const h of handrolled) {
+        h.on_record = record.explains(h.files.flatMap(frag)) ?? undefined;
+        h.touches = touches(h.files[0] ?? "", few);
+    }
+    for (const d of duplicates) {
+        // Parallel adapters are explained structurally; the record is not consulted.
+        d.on_record = d.parallel ? undefined : record.explains(d.files.flatMap(frag)) ?? undefined;
+        d.touches = touches(d.files[0] ?? "", few);
+    }
+    for (const d of deadReading.dead) {
+        d.on_record = record.explains(frag(d.file)) ?? undefined;
+        d.touches = touches(d.file, few);
+    }
+    // EVERY FINDING GETS A NAME (0.3). The protocol has to rule on each one -
+    // confirmed, refuted, on record, unknown - and a verdict needs something to
+    // point at. Ids are stable across runs of the same repository.
+    for (const d of deps)
+        if (d.no_reference_found)
+            d.id = `dep:${d.name}`;
+    for (const o of vendorsReading.overlaps)
+        o.id = `overlap:${o.category}`;
+    for (const o of stack.overlaps)
+        o.id = `overlap:${o.category}`;
+    for (const h of handrolled)
+        h.id = `hand:${h.rail}`;
+    for (const c of stack.consolidations)
+        c.id = `cut:${c.candidate}`;
+    duplicates.forEach((d, i) => { if (!d.deliberate && !d.parallel)
+        d.id = `dup:${i + 1}:${d.files[0] ?? ""}`; });
+    for (const d of deadReading.dead)
+        d.id = `dead:${d.file}`;
+    for (const c of costs)
+        c.id = `cost:${c.file}:${c.line.split(":")[0]}`;
+    for (const f of database.findings)
+        f.id = `db:${f.kind}:${f.subject}`;
+    // Last, and after every detector, so the ledger describes the run that just
+    // happened rather than a plan for one.
+    const coverage = await coverageOf(repo);
     // A vendor SDK that is DECLARED but never referenced is a bill with no
     // work behind it - the score's hardest floor.
     const vendorSdkNames = new Set(vendorsReading.vendors.flatMap((v) => v.evidence.filter((e) => e.kind === "sdk").map((e) => e.what)));
     const unusedPaid = deps.find((d) => !d.dev && d.no_reference_found && /^(openai|stripe|twilio|resend|@sendgrid\/|@anthropic-ai\/|@clerk\/|algoliasearch|cloudinary)/.test(d.name))?.name ?? null;
     void vendorSdkNames;
+    // The profile reads the repository's SHAPE, and it runs after the detectors
+    // because it needs to know what they found ground for: a question with no
+    // ground is recorded as not applicable rather than answered "nothing found",
+    // which is how a six-file scraper scored 96 out of 100.
+    const profile = profileRepo(repo, {
+        sqlFiles: database.files,
+        manifestDeps: deps.length,
+        analysed: coverage.analysed,
+    });
     const allOverlaps = [...vendorsReading.overlaps, ...stack.overlaps];
     const score = scoreProspect({
+        not_asked: profile.not_applicable.map((n) => n.question),
         deps,
         overlaps: allOverlaps,
         consolidations: stack.consolidations,
@@ -82,6 +164,10 @@ export async function runProspect(root) {
         dead: deadReading.dead,
         cost_surfaces: costs,
         fingerprint,
+        database,
+        profile,
+        decisions: record.toJSON(),
+        coverage,
         score,
         totals: {
             files: repo.files.length,

package/dist/northstar.js

@@ -3,17 +3,30 @@
 // 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.";
+/**
+ * The FIRST PARAGRAPH under the heading, not the whole section. The section is
+ * the sentence plus everything written to explain it, and joining the lot
+ * printed "Read it from the README's fir" - the sentence, the provenance note,
+ * and a truncation mid-word. The sentence is the first paragraph; the rest is
+ * for a person.
+ */
 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 = [];
+    let started = false;
     for (const l of lines.slice(at + 1)) {
         if (/^#{1,4}\s/.test(l))
             break;
-        if (l.trim())
-            body.push(l.trim());
+        if (!l.trim()) {
+            if (started)
+                break;
+            continue;
+        }
+        started = true;
+        body.push(l.trim());
     }
     return body.length ? body.join(" ") : null;
 }

package/dist/profile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What kind of repository is this, and which questions can honestly be asked of it.
+ *
+ * THE DEFECT THIS EXISTS FOR. The detectors encoded one repository's
+ * assumptions - npm manifests, Postgres migrations, a `caller-check:` marker
+ * convention - and then applied them everywhere. Run across five repositories of
+ * different shapes, coverage swung from 38% to 79% and a six-file scraper scored
+ * **96 out of 100**, because a question that could not be asked returned nothing
+ * found, and nothing found scored as healthy.
+ *
+ * That is the same failure the rest of this version is about, one level up. A
+ * check that reports the same whether it works or not is worthless; a SCAN that
+ * reports the same whether it looked or not is worse, because it carries a
+ * number. "No dependencies with no reference found" means one thing after
+ * reading a 68-package manifest and something else entirely when no manifest was
+ * found at all, and the report said it identically both ways.
+ *
+ * SO: profile first, then ask only what the ground supports, and say out loud
+ * which questions were not asked and why. A question skipped honestly costs
+ * nothing. A question skipped silently becomes a score.
+ */
+import type { Repo } from "./walk.js";
+export interface NotApplicable {
+    question: string;
+    why: string;
+}
+export interface RepoProfile {
+    /** Languages by weight of code files, most first. */
+    languages: string[];
+    /** Dependency manifests found, by filename. */
+    manifests: string[];
+    /** Shapes recognised: monorepo, migrations, containers, workflows, and so on. */
+    traits: string[];
+    /** Questions the repository can actually answer. */
+    questions_asked: string[];
+    /** Questions with no ground to stand on, each with the reason. */
+    not_applicable: NotApplicable[];
+    /**
+     * How much of a reading this is. A six-file scraper examined completely and a
+     * 4,000-file monorepo examined completely are both "complete" and are not the
+     * same evidence, so the report says which it is holding.
+     */
+    depth: {
+        code_files: number;
+        analysed_share: number;
+        /** thin | partial | substantial - the weight a reader should give the result. */
+        reading: "thin" | "partial" | "substantial";
+        why: string;
+    };
+}
+export declare function profileRepo(repo: Repo, seen: {
+    sqlFiles: number;
+    manifestDeps: number;
+    analysed: number;
+}): RepoProfile;

package/dist/profile.js

@@ -0,0 +1,106 @@
+import { baseName, isCode } from "./walk.js";
+const MANIFESTS = [
+    { file: /(^|\/)package\.json$/, lang: "javascript", name: "package.json" },
+    { file: /(^|\/)requirements\.txt$/, lang: "python", name: "requirements.txt" },
+    { file: /(^|\/)pyproject\.toml$/, lang: "python", name: "pyproject.toml" },
+    { file: /(^|\/)Pipfile$/, lang: "python", name: "Pipfile" },
+    { file: /(^|\/)go\.mod$/, lang: "go", name: "go.mod" },
+    { file: /(^|\/)Cargo\.toml$/, lang: "rust", name: "Cargo.toml" },
+    { file: /(^|\/)Gemfile$/, lang: "ruby", name: "Gemfile" },
+    { file: /(^|\/)composer\.json$/, lang: "php", name: "composer.json" },
+    { file: /(^|\/)pubspec\.yaml$/, lang: "dart", name: "pubspec.yaml" },
+    { file: /(^|\/)(pom\.xml|build\.gradle(\.kts)?)$/, lang: "java", name: "pom.xml / build.gradle" },
+];
+const EXT_LANG = [
+    [/\.(ts|tsx|js|jsx|mjs|cjs)$/i, "javascript"],
+    [/\.py$/i, "python"],
+    [/\.go$/i, "go"],
+    [/\.rs$/i, "rust"],
+    [/\.rb$/i, "ruby"],
+    [/\.php$/i, "php"],
+    [/\.(java|kt)$/i, "java"],
+    [/\.swift$/i, "swift"],
+    [/\.(vue|svelte|astro)$/i, "javascript"],
+];
+export function profileRepo(repo, seen) {
+    const code = repo.files.filter(isCode);
+    const weight = new Map();
+    for (const f of code) {
+        for (const [re, lang] of EXT_LANG) {
+            if (re.test(baseName(f))) {
+                weight.set(lang, (weight.get(lang) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    const languages = [...weight.entries()].sort((a, b) => b[1] - a[1]).map(([l]) => l);
+    const manifests = [];
+    for (const m of MANIFESTS) {
+        if (repo.files.some((f) => m.file.test(f) && !/node_modules/.test(f)))
+            manifests.push(m.name);
+    }
+    const traits = [];
+    if (repo.files.some((f) => /(^|\/)(packages|apps)\//.test(f)))
+        traits.push("monorepo");
+    if (seen.sqlFiles > 0)
+        traits.push("sql-migrations");
+    if (repo.files.some((f) => /(^|\/)Dockerfile$/.test(f)))
+        traits.push("containers");
+    if (repo.files.some((f) => /^\.github\/workflows\//.test(f)))
+        traits.push("ci-workflows");
+    if (repo.files.some((f) => /(^|\/)(terraform|\.tf)$|\.tf$/.test(f)))
+        traits.push("infra-as-code");
+    // A question is asked when the repository holds the thing it asks about.
+    // Anything else is recorded as not applicable, with the reason, and does not
+    // reach the score.
+    const asked = [];
+    const na = [];
+    const hasManifest = manifests.length > 0;
+    if (hasManifest && seen.manifestDeps > 0)
+        asked.push("dependencies");
+    else {
+        na.push({
+            question: "dependencies",
+            why: hasManifest
+                ? "a manifest was found and declares no runtime dependencies, so there is nothing to find unreferenced"
+                : "no dependency manifest of any recognised kind, so 'a package nothing references' has no ground to stand on",
+        });
+    }
+    if (seen.sqlFiles > 0)
+        asked.push("database");
+    else {
+        na.push({
+            question: "database",
+            why: "no SQL migrations, so row-level security and definer functions cannot be read from this repository. The database may still exist and be managed elsewhere.",
+        });
+    }
+    if (code.length >= 12)
+        asked.push("duplication", "reachability");
+    else {
+        na.push({
+            question: "duplication and reachability",
+            why: `only ${code.length} code file(s): too few for a duplicate block or an unreached module to mean anything`,
+        });
+    }
+    if (code.length > 0)
+        asked.push("vendors", "implementation");
+    const share = repo.files.length ? seen.analysed / repo.files.length : 0;
+    const reading = code.length < 15 ? "thin" : code.length < 150 || share < 0.4 ? "partial" : "substantial";
+    return {
+        languages,
+        manifests,
+        traits,
+        questions_asked: asked,
+        not_applicable: na,
+        depth: {
+            code_files: code.length,
+            analysed_share: Math.round(share * 100) / 100,
+            reading,
+            why: reading === "thin"
+                ? `${code.length} code files. A clean result here means there was little to examine, not that a large system was examined and found clean.`
+                : reading === "partial"
+                    ? `${code.length} code files, ${Math.round(share * 100)}% of the repository analysed. Enough to be worth reading, not enough to be exhaustive.`
+                    : `${code.length} code files, ${Math.round(share * 100)}% of the repository analysed.`,
+        },
+    };
+}