any-doctor 0.0.4 → 0.0.7

package/CONTEXT.md

@@ -39,9 +39,9 @@ call: the runner's bounded pool, the crash fold (a crash is data — id
 plus full error detail, never a throw), the process-wide analysis fold,
 the per-doctor paths, the file-count policy, and the timing. Progress
 events (settle order) are the only side channel — the live line renders
-them, it never joins the fold. Skips are a discovery fact, so the
-command layer, which owns discovery, patches `skippedUnsafe` onto the
-outcome.
+them, it never joins the fold. Skips are a discovery fact, so they ride
+in with the CohortSpec: the command layer, which owns discovery, hands
+them to the run and the outcome comes back complete.
 
 ## Summary
 
@@ -160,9 +160,14 @@ An identity question asked through `ctx.analysis`: which **Binding** a
 name resolves to, and every **Reference** to it. `ctx.analysis.bindings(file)`
 returns the file's whole identity model in one answer — every binding
 with its declaration span and its references (positions in ctx.search's
-convention, plus read/write). The engine is optional (oxc-parser +
+convention, plus read/write). `ctx.analysis.spans(file)` (D26) returns
+every function-like **Span** — functions, methods, arrows, classes with
+name, asyncness, and extent — as an AST fact, replacing the brace-counting
+scans doctors once carried privately (the audit truncation bugs lived in
+those approximations). The engine is optional (oxc-parser +
 eslint-scope behind the Engine seam's second adapter): checks declare
-the analysis they need on their CheckMeta (`needs`), narrow without it,
+the analysis they need on their CheckMeta (`needs` — vocabulary:
+"bindings", "spans"), narrow without it,
 and the report renders "narrowed" — a degraded run is visible, never
 silent. References answer by position, so analysis queries compose with
 rule queries: shapes from one engine, identities from the other.
@@ -242,7 +247,12 @@ workflow's second pass; a doctor ships only after surviving its attack.
 
 Running a doctor program against its fixtures and diffing the findings.
 The trust gate: a doctor program is not considered working until verify
-passes.
+passes. The policies that compose the gate — the claim contract, the
+per-fixture diff, the shared innocent corpus, the duplicate-location
+probe, the shared sensitivity corpus — live in one module, the
+Certification harness (`src/certify.ts`), behind one interface:
+`certify(mod, fixtures) -> result rows`. The doctor loader calls it once;
+prevention tiers land there, not in loader choreography.
 
 ## Runner
 

package/bin/analysis-host.d.ts

@@ -1,6 +1,7 @@
-import { AnalysisFile, Mode } from "./contract.js";
-import { analysisStatus, analyzeBindings } from "./analysis.js";
+import { AnalysisFile, AnalysisSpans, Mode } from "./contract.js";
+import { analysisStatus, analyzeBindings, analyzeSpans } from "./analysis.js";
 type Analyzer = typeof analyzeBindings;
+type SpansAnalyzer = typeof analyzeSpans;
 type Status = typeof analysisStatus;
 export declare function clearAnalysisCache(): void;
 export interface AnalysisRequestBody {
@@ -13,8 +14,10 @@ export type AnalysisResponse = {
     reason?: string;
 } | {
     file: AnalysisFile;
+} | {
+    file: AnalysisSpans;
 } | {
     error: string;
 };
-export declare function handleAnalysisRequest(req: AnalysisRequestBody, mode: Mode, analyzer?: Analyzer, status?: Status): AnalysisResponse;
+export declare function handleAnalysisRequest(req: AnalysisRequestBody, mode: Mode, analyzer?: Analyzer, status?: Status, spansAnalyzer?: SpansAnalyzer): AnalysisResponse;
 export {};

package/bin/analysis-host.js

@@ -1,18 +1,20 @@
 import * as fs from "fs";
 import * as path from "path";
-import { analysisStatus, analyzeBindings } from "./analysis.js";
+import { analysisStatus, analyzeBindings, analyzeSpans } from "./analysis.js";
 import { searchBase, withinBase } from "./search-host.js";
 // One cache per host process. The host lives in the runner process, so
 // the lifetime is the any-doctor invocation; across a cohort's doctors
 // the same unchanged file answers from memory.
 const modelCache = new Map();
+const spansCache = new Map();
 // Test seam: the model cache is keyed by mtime+size for the process
 // lifetime; tests bust it between cases. Invisible to slop-doctor's
 // default run (test-file consumers are the documented narrowing).
 export function clearAnalysisCache() {
     modelCache.clear();
+    spansCache.clear();
 }
-export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus) {
+export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus, spansAnalyzer = analyzeSpans) {
     const base = searchBase(mode);
     const root = typeof req.root === "string" ? path.resolve(req.root) : "";
     if (base === "" || !withinBase(root, base)) {
@@ -22,35 +24,44 @@ export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, sta
         const s = status();
         return s.available ? { available: true } : { available: false, reason: s.reason };
     }
-    if (req.kind === "bindings") {
+    if (req.kind === "bindings" || req.kind === "spans") {
         if (typeof req.file !== "string" || req.file === "") {
-            return { error: 'ctx.analysis.bindings needs a "file" path' };
+            return { error: `ctx.analysis.${req.kind} needs a "file" path` };
         }
         const abs = path.resolve(root, req.file);
         if (!withinBase(abs, root)) {
             return { error: `ctx.analysis failed: file is outside the search root: ${req.file}` };
         }
-        let source;
-        let mtimeMs;
-        let size;
-        try {
-            const stat = fs.statSync(abs);
-            mtimeMs = stat.mtimeMs;
-            size = stat.size;
-            const cached = modelCache.get(abs);
-            if (cached && cached.mtimeMs === mtimeMs && cached.size === size)
-                return { file: cached.file };
-            source = fs.readFileSync(abs, "utf8");
+        if (req.kind === "bindings") {
+            return cachedModel(abs, root, modelCache, analyzer, req.file);
         }
-        catch {
-            return { error: `ctx.analysis failed: cannot read ${req.file}` };
-        }
-        const rel = path.relative(root, abs);
-        const r = analyzer(rel, source);
-        if (!r.ok)
-            return { error: r.error };
-        modelCache.set(abs, { mtimeMs, size, file: r.file });
-        return { file: r.file };
+        return cachedModel(abs, root, spansCache, spansAnalyzer, req.file);
+    }
+    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings, spans` };
+}
+// The shared per-file model lifecycle: stat (cache hit on mtime+size),
+// read, compute, cache. Bindings and spans are the same policy over two
+// analyzers and two caches.
+function cachedModel(abs, root, cache, compute, relFile) {
+    let source;
+    let mtimeMs;
+    let size;
+    try {
+        const stat = fs.statSync(abs);
+        mtimeMs = stat.mtimeMs;
+        size = stat.size;
+        const cached = cache.get(abs);
+        if (cached && cached.mtimeMs === mtimeMs && cached.size === size)
+            return { file: cached.file };
+        source = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return { error: `ctx.analysis failed: cannot read ${relFile}` };
     }
-    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings` };
+    const rel = path.relative(root, abs);
+    const r = compute(rel, source);
+    if (!r.ok)
+        return { error: r.error };
+    cache.set(abs, { mtimeMs, size, file: r.file });
+    return { file: r.file };
 }

package/bin/analysis.d.ts

@@ -1,5 +1,5 @@
-import { AnalysisFile, BindingInfo, BindingRef } from "./contract.js";
-export type { AnalysisFile, BindingInfo, BindingRef };
+import { AnalysisFile, AnalysisSpans, BindingInfo, BindingRef, SpanInfo } from "./contract.js";
+export type { AnalysisFile, AnalysisSpans, BindingInfo, BindingRef, SpanInfo };
 export interface AnalysisStatus {
     available: true;
 }
@@ -15,4 +15,12 @@ export type AnalysisResult = {
     ok: false;
     error: string;
 };
+export type SpansResult = {
+    ok: true;
+    file: AnalysisSpans;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function analyzeSpans(file: string, source: string): SpansResult;
 export declare function analyzeBindings(file: string, source: string): AnalysisResult;

package/bin/analysis.js

@@ -8,10 +8,8 @@ function loadStack() {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { parseSync } = require_("oxc-parser");
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { analyze } = require_("eslint-scope");
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const keys = require_("eslint-visitor-keys");
-        loaded = { parseSync, analyze, keys };
+        const { analyze } = require_("@typescript-eslint/scope-manager");
+        loaded = { parseSync, analyze };
     }
     catch (e) {
         loaded = { error: `the analysis engine is not installed (${e instanceof Error ? e.message : String(e)}) — npm install oxc-parser` };
@@ -22,6 +20,89 @@ export function analysisStatus() {
     const stack = loadStack();
     return stack.error !== undefined ? { available: false, reason: stack.error } : { available: true };
 }
+// One file in, every function-like span out (D26): an AST fact answering
+// what the doctors' private brace-counting copies could only approximate.
+// Semicolons inside multi-line callbacks, strings containing braces, JSX —
+// none of it can truncate a span that the parser already knows. Named
+// declarations carry their id; arrows and anonymous expressions carry null.
+export function analyzeSpans(file, source) {
+    const stack = loadStack();
+    if (stack.error !== undefined)
+        return { ok: false, error: stack.error };
+    let program;
+    try {
+        program = stack.parseSync(file, source, { sourceType: "module" }).program;
+    }
+    catch (e) {
+        return { ok: false, error: `analysis failed to parse ${file}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const pos = positioner(source);
+    const spans = [];
+    const visit = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        const n = node;
+        let span = null;
+        if (n.type === "FunctionDeclaration" || n.type === "TSDeclareFunction") {
+            span = spanOf(n, "function", idName(n.id));
+        }
+        else if (n.type === "FunctionExpression") {
+            span = spanOf(n, "function-expression", idName(n.id));
+        }
+        else if (n.type === "ArrowFunctionExpression") {
+            span = spanOf(n, "arrow", null);
+        }
+        else if (n.type === "ClassDeclaration" || n.type === "ClassExpression") {
+            span = spanOf(n, "class", idName(n.id));
+        }
+        else if (n.type === "MethodDefinition" || n.type === "TSAbstractMethodDefinition") {
+            span = spanOf(n.value, "method", propertyName(n.key));
+        }
+        if (span !== null)
+            spans.push(span);
+        for (const key of Object.keys(n)) {
+            if (key === "range" || key === "start" || key === "end")
+                continue;
+            const v = n[key];
+            if (Array.isArray(v)) {
+                for (const child of v)
+                    if (isNode(child))
+                        visit(child);
+            }
+            else if (isNode(v))
+                visit(v);
+        }
+    };
+    visit(program);
+    return { ok: true, file: { file, spans } };
+    function spanOf(n, kind, name) {
+        if (typeof n.start !== "number" || typeof n.end !== "number")
+            return null;
+        return {
+            kind,
+            name,
+            async: n.async === true,
+            line: pos.line(n.start),
+            column: pos.column(n.start),
+            endLine: pos.line(n.end),
+            endColumn: pos.column(n.end),
+        };
+    }
+}
+function idName(id) {
+    return id && typeof id.name === "string" ? id.name : null;
+}
+function propertyName(key) {
+    const k = key;
+    if (k && typeof k.name === "string")
+        return k.name;
+    if (k && typeof k.value === "string")
+        return k.value; // computed / literal keys
+    return null;
+}
+function isNode(v) {
+    return Boolean(v) && typeof v === "object" && typeof v.type === "string";
+}
 // One file in, one identity model out: every binding (declarations,
 // parameters, imports) with the span of its declaring node and every
 // reference to it, read or write. Type-position identifiers never become
@@ -45,8 +126,6 @@ export function analyzeBindings(file, source) {
     try {
         scopeManager = stack.analyze(program, {
             sourceType: "module",
-            ecmaVersion: 2026,
-            childVisitorKeys: stack.keys.KEYS,
         });
     }
     catch (e) {
@@ -57,6 +136,10 @@ export function analyzeBindings(file, source) {
     const global = scopeManager.globalScope;
     if (global === null)
         return { ok: false, error: `analysis failed to resolve scopes in ${file}` };
+    // Language facts computed from the AST once, so doctors never re-derive
+    // them with regexes: what is exported, and what is an intentional
+    // object-rest exclusion.
+    const facts = languageFacts(program);
     for (const scope of allScopes(global)) {
         for (const variable of scope.variables) {
             const def = variable.defs[0];
@@ -64,7 +147,7 @@ export function analyzeBindings(file, source) {
                 continue; // builtins and implicit globals carry no def
             // The declaration's own extent: for variables the declarator (so a
             // binding's span contains its initializer), for parameters the
-            // identifier itself (eslint-scope hands the whole function node for
+            // identifier itself (scope managers hand the whole function node for
             // params, which would swallow the body).
             const node = def.node;
             const span = def.type === "Parameter" ? def.name.range : ((_a = node === null || node === void 0 ? void 0 : node.range) !== null && _a !== void 0 ? _a : def.name.range);
@@ -86,11 +169,102 @@ export function analyzeBindings(file, source) {
                     endColumn: pos.column(r.identifier.range[1]),
                     write: r.isWrite(),
                 })),
+                exported: facts.exported.has(variable.name) || undefined,
+                excluded: facts.excluded.has(variable.name) || undefined,
             });
         }
     }
     return { ok: true, file: { file, bindings } };
 }
+function languageFacts(program) {
+    const exported = new Set();
+    const excluded = new Set();
+    const visit = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        const n = node;
+        if (n.type === "ExportNamedDeclaration" && n.declaration) {
+            collectDeclaredNames(n.declaration, exported);
+        }
+        if (n.type === "ExportNamedDeclaration" && Array.isArray(n.specifiers)) {
+            for (const spec of n.specifiers) {
+                if (spec.local && typeof spec.local.name === "string") {
+                    exported.add(spec.local.name);
+                }
+            }
+        }
+        if (n.type === "ExportDefaultDeclaration") {
+            const d = n.declaration;
+            if (d && typeof d.id === "object" && d.id && typeof d.id.name === "string") {
+                exported.add(d.id.name);
+            }
+        }
+        if (n.type === "ObjectPattern" && Array.isArray(n.properties)) {
+            const hasRest = n.properties.some((p) => p.type === "RestElement");
+            if (hasRest) {
+                for (const p of n.properties) {
+                    if (p.type === "Property" && p.value && p.value.type === "Identifier") {
+                        excluded.add(p.value.name);
+                    }
+                }
+            }
+        }
+        for (const key of Object.keys(n)) {
+            if (key === "range" || key === "start" || key === "end" || key === "tokens" || key === "comments")
+                continue;
+            const v = n[key];
+            if (Array.isArray(v)) {
+                for (const child of v) {
+                    if (child && typeof child === "object" && typeof child.type === "string")
+                        visit(child);
+                }
+            }
+            else if (v && typeof v === "object" && typeof v.type === "string") {
+                visit(v);
+            }
+        }
+    };
+    visit(program);
+    return { exported, excluded };
+}
+// Every name a declaration binds: function/class ids, every declarator of
+// a variable statement (multi-declarator, destructured patterns), and the
+// property names of nested object/array patterns.
+function collectDeclaredNames(decl, into) {
+    if (decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration" || decl.type === "TSDeclareFunction") {
+        if (decl.id && typeof decl.id.name === "string") {
+            into.add(decl.id.name);
+        }
+        return;
+    }
+    if (decl.type === "VariableDeclaration" && Array.isArray(decl.declarations)) {
+        for (const d of decl.declarations) {
+            collectPatternNames(d.id, into);
+        }
+    }
+}
+function collectPatternNames(pattern, into) {
+    var _a, _b;
+    if (pattern.type === "Identifier") {
+        into.add(pattern.name);
+        return;
+    }
+    if ((pattern.type === "ObjectPattern" || pattern.type === "ArrayPattern") && Array.isArray((_a = pattern.properties) !== null && _a !== void 0 ? _a : pattern.elements)) {
+        const items = ((_b = pattern.properties) !== null && _b !== void 0 ? _b : pattern.elements);
+        for (const item of items) {
+            if (!item)
+                continue;
+            if (item.type === "Property")
+                collectPatternNames(item.value, into);
+            else if (item.type === "RestElement")
+                collectPatternNames(item.argument, into);
+            else
+                collectPatternNames(item, into);
+        }
+    }
+    if (pattern.type === "AssignmentPattern")
+        collectPatternNames(pattern.left, into);
+}
 // eslint-scope expects `range: [start, end]` on nodes; oxc emits start/end.
 function addRanges(node) {
     if (!node || typeof node !== "object")

package/bin/certify.d.ts

@@ -0,0 +1,15 @@
+import { buildCtx } from "./sdk.js";
+import type { Fixture, FixtureResult, RunResult } from "./contract.js";
+export interface DoctorModule {
+    meta?: unknown;
+    doctor?: (ctx: ReturnType<typeof buildCtx>["ctx"]) => unknown;
+}
+export declare function runOnce(root: string, mod: DoctorModule, opts: {
+    includeTests: boolean;
+}): Promise<RunResult>;
+export declare class ClaimContractViolation extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare function validateClaimContract(mod: DoctorModule): void;
+export declare function certify(mod: DoctorModule, fixtures: Fixture[]): Promise<FixtureResult[]>;