any-doctor 0.0.4 → 0.0.6

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` };
@@ -45,8 +43,6 @@ export function analyzeBindings(file, source) {
     try {
         scopeManager = stack.analyze(program, {
             sourceType: "module",
-            ecmaVersion: 2026,
-            childVisitorKeys: stack.keys.KEYS,
         });
     }
     catch (e) {
@@ -57,6 +53,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 +64,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 +86,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/contract.d.ts

@@ -77,6 +77,12 @@ export interface BindingInfo {
     endLine: number;
     endColumn: number;
     references: BindingRef[];
+    /** Named-exported from this module — computed from the export AST, not
+     *  text: every declarator of an export statement, specifiers, defaults. */
+    exported?: boolean;
+    /** Declared in an object pattern with a rest sibling — the intentional
+     *  omission idiom (`const { secret: _s, ...safe } = x`). Not dead code. */
+    excluded?: boolean;
 }
 export interface AnalysisFile {
     file: string;
@@ -119,6 +125,14 @@ export interface Fixture {
     name: string;
     seed: Record<string, string>;
     expected: ExpectedFinding[];
+    /** One sentence: the observable condition this check establishes. Not the
+     *  consequence ("this is unsafe") - the thing actually detected. */
+    claim?: string;
+    /** Innocent lookalike shapes that must remain silent (corpus candidates). */
+    lookalikes?: string[];
+    /** When analysis the check needs is unavailable: "narrow" (report says
+     *  narrowed) or "skip" (silent, declared in blindSpots). */
+    onUnknown?: "narrow" | "skip";
     /** Which analysis mode this fixture pins (D20 Stage 2): "on" (default)
      * runs with the identity engine — and skips with a named notice when it
      * is not installed in the environment; "off" forces the degraded path,

package/bin/doctor-loader.mjs

@@ -75,6 +75,7 @@ function materializeSeed(tmp, rel, content) {
     fs.writeFileSync(abs, content);
 }
 async function main() {
+    var _a;
     confineProcess();
     // The mode arrives as argv and is decoded exactly once, here, into a value.
     const decoded = contract.decodeLoaderArgs(process.argv.slice(2));
@@ -111,6 +112,30 @@ async function main() {
                 console.error("fixture module must export `fixtures` (array) — got: " + Object.keys(fixturesMod).join(", "));
                 process.exit(3);
             }
+            // The claim contract (D23): certification requires each declared
+            // check to state the observable condition it establishes, its
+            // innocent lookalikes, and - when it needs the identity engine -
+            // what happens on unknown. Prose impact is not a testable claim.
+            const checks = (_a = mod.meta) === null || _a === void 0 ? void 0 : _a.checks;
+            if (Array.isArray(checks)) {
+                const problems = [];
+                for (const c of checks) {
+                    if (typeof c.claim !== "string" || c.claim.trim().length === 0) {
+                        problems.push(`check "${String(c.id)}": claim is required — one sentence, the observable condition detected, not the consequence`);
+                    }
+                    if (!Array.isArray(c.lookalikes) || c.lookalikes.length === 0) {
+                        problems.push(`check "${String(c.id)}": lookalikes is required — at least one innocent shape that must stay silent`);
+                    }
+                    if (Array.isArray(c.needs) && c.needs.length > 0
+                        && (c.onUnknown !== "narrow" && c.onUnknown !== "skip")) {
+                        problems.push(`check "${String(c.id)}": onUnknown is required when needs is declared — "narrow" or "skip"`);
+                    }
+                }
+                if (problems.length > 0) {
+                    console.error("claim contract violations:\n  " + problems.join("\n  "));
+                    process.exit(3);
+                }
+            }
             const results = [];
             // Only a doctor whose checks declare analysis needs can have
             // analysis-on fixtures — probing anyone else would make a
@@ -158,6 +183,45 @@ async function main() {
                     fs.rmSync(tmp, { recursive: true, force: true });
                 }
             }
+            // The shared innocent corpus (D23): files that look guilty but
+            // aren't — the audit counterexamples as commons. Every doctor runs
+            // against them with expected: []; a finding here is a false positive
+            // by definition, whoever wrote the check.
+            const innocentDir = fs.realpathSync(new URL("../fixtures/innocent", import.meta.url));
+            if (fs.existsSync(innocentDir)) {
+                const seed = {};
+                const collect = (dir, prefix) => {
+                    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                        const abs = path.join(dir, entry.name);
+                        const rel = prefix ? prefix + "/" + entry.name : entry.name;
+                        if (entry.isDirectory())
+                            collect(abs, rel);
+                        else
+                            seed[rel] = fs.readFileSync(abs, "utf8");
+                    }
+                };
+                collect(innocentDir, "");
+                try {
+                    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "any-doctor-verify-innocent-"));
+                    try {
+                        for (const [rel, content] of Object.entries(seed))
+                            materializeSeed(tmp, rel, content);
+                        const result = await runOnce(tmp, mod, { includeTests: true });
+                        const diff = contract.compareFindings([], result.findings);
+                        results.push({
+                            name: "shared innocent corpus (" + Object.keys(seed).length + " files)",
+                            ok: diff.missing.length === 0 && diff.unexpected.length === 0,
+                            ...diff,
+                        });
+                    }
+                    finally {
+                        fs.rmSync(tmp, { recursive: true, force: true });
+                    }
+                }
+                catch (e) {
+                    results.push({ name: "shared innocent corpus", ok: false, missing: [], unexpected: [], error: e instanceof Error ? e.message : String(e) });
+                }
+            }
             process.stdout.write("\n" + contract.RESULT_SENTINEL + JSON.stringify({
                 protocolVersion: contract.PROTOCOL_VERSION,
                 kind: "verify",

package/bin/mask.js

@@ -15,8 +15,13 @@
 // ctx. First-party host code has no such constraint, so there is exactly
 // one copy, here.
 // A `/` opens a regex literal (not division) after these characters or
-// after these keywords; anywhere else it divides.
-const REGEX_PRECEDER_CHARS = "=([{,;:!&|?+-*%^~<>";
+// after these keywords; anywhere else it divides. `<` and `>` are
+// deliberately absent: a `/` right after `<` is a JSX CLOSING TAG
+// (`</Link>`), and treating it as a regex opener phantom-masks the rest
+// of the component — the 0.0.4 false-positive mechanism. Comparison
+// operators before a regex (`a < /re/.test(x)`) are vanishingly rare
+// next to JSX.
+const REGEX_PRECEDER_CHARS = "=([{,;:!&|?+-*%^~";
 const REGEX_PRECEDER_WORDS = new Set([
     "return", "typeof", "instanceof", "in", "of", "case", "delete", "void",
     "throw", "new", "do", "else", "yield", "await",

package/docs/decisions.md

@@ -677,6 +677,181 @@ skill teaches the rule (many questions → one batch) beside the op.
 
 ---
 
+## D21 — The semantic repair: claims may not exceed the analysis, and the analysis now sees TypeScript
+
+**Date:** 2026-09-09
+
+**Context:** Two external audits of slop-doctor on a real 630-file
+TypeScript/TSX codebase found systematic false positives across specific
+identifiable classes (unused-import, unread-binding, and hostname checks
+each produced findings that were overwhelmingly or entirely wrong; the
+audits confirmed specific true findings in the dead-export and duplicate
+checks). The mechanisms: the identity engine
+(oxc-parser + eslint-scope) did not resolve JSX references or type
+positions, so JSX-used imports read as unused; the masker treated the
+slash in JSX closing tags (`</Link>`) as a regex opener, phantom-masking
+subsequent code and defeating even the textual backstop; the duplicate
+check compared masked bodies, erasing the literal values that
+distinguish implementations; export detection was regex over text and
+broke on semicolons inside type annotations; the object-rest exclusion
+idiom (`const { secret: _s, ...safe } = x`) was flagged as unread; QA
+throw-guards were described as environment routing. The deepest
+finding: fixtures validate examples, not reliability — historical
+review evidence proves a problem occurs, not that a detector's pattern
+recognizes it.
+
+**Decision:** Claims may not exceed the analysis, and the analysis was
+ upgraded until the claims were cheap:
+
+- **The scope layer is @typescript-eslint/scope-manager** (replacing
+  eslint-scope over the same oxc AST): JSX references and type-position
+  references now RESOLVE. Two language facts are computed from the AST
+  and carried on every binding — `exported` (every declarator,
+  destructured pattern, and specifier under an export statement; no
+  text matching) and `excluded` (the object-rest omission idiom).
+  Doctors consume facts; they never re-derive them with regexes.
+- **The masker no longer treats a slash after `<` as a regex opener**
+  (JSX closing tags are not regexes; comparison-before-regex is
+  vanishingly rare next to JSX).
+- **The duplicate check compares bodies with literal values preserved**
+  (comments dropped via the masked twin) — `replace(/\\s+/g, "-")` and
+  `replace(/\\s+/g, "_")` are different implementations. Severity
+  demoted to info: duplication establishes maintenance risk, not a bug;
+  each finding names its counterpart files.
+- **Dead exports are candidates, not verdicts** (info): the consumer
+  index collects named imports, namespace members, and DYNAMIC import
+  specifiers (read from raw source — masking blanks path strings);
+  generated files (`.gen.`, `__generated__/`, `generated/`) are
+  exempt; the finding message says "candidate".
+- **The hostname check claims routing only when routing is proven** —
+  the branch must assign or return a URL-shaped constant; throw guards
+  are enforcement, not routing.
+- **The reviewer's seven counterexamples are frozen fixtures** (29
+  total) and engine/masker regression tests pin the facts.
+- **prepublishOnly runs the full suite**, not just the build: the
+  fixture gates are the registry's promise, so they fire before every
+  publish.
+- **The skill's authoring guidance was rewritten**: the regex-export
+  and occurrence-count workarounds are gone, replaced by the engine-
+  facts law and the unknown-is-not-unused rule — newly generated
+  doctors must not reproduce 0.0.4's failure modes.
+
+**Consequences:** On the audit codebase: 264 findings → 169; unused
+imports 51 → 1 (a generated file, now exempt), unread bindings 37 → 0,
+hostname 4 → 0; every audit-confirmed false positive cleared and every
+audit-confirmed real finding (two dead prompt builders, the duplicated
+schema helper family) still reported. Remaining honest noise: dead
+export candidates in repos whose consumers are string-built or
+test-only (blind spots declare both). The deeper process rule stands
+for every future doctor: measure per-rule precision on real unfamiliar
+repositories before shipping warning severity — examples passing is
+not precision.
+
+---
+
+## D22 — convex-doctor: the same law, applied to the second doctor
+
+**Date:** 2026-09-09
+
+**Context:** The external audit of convex-doctor on the same 630-file
+codebase found 387 findings with at least 118 false positives: 80
+"unawaited" calls that were members of awaited Promise.all arrays (the
+check had no consumption context at all); 27 transaction-clock warnings
+inside actions, where the deterministic-clock restriction does not
+apply; all 5 "index without range" findings had real bounds inside
+multi-line callbacks whose internal semicolons truncated statement
+reconstruction; all 4 "write in query" findings were ctx.runQuery,
+which QueryCtx supports (a wrong platform premise, not a parsing bug);
+both missing-validator findings were chrome.tabs.query — a browser API
+mistaken for a Convex function because function recognition was
+namespace-blind.
+
+**Decision:** D21's law — claims may not exceed the analysis — applied
+check by check:
+
+- **Consumption context before "unawaited":** a bare ctx call line is
+  exempt when its statement context contains a promise combiner
+  (Promise.all/allSettled/race/any, .then/.catch/.finally,
+  Effect.runPromise) or a promise/array assignment, walking back to the
+  statement start and forward across one array-close boundary.
+- **Function kinds are facts:** function spans carry their kind; the
+  clock check skips actions (live clock, no restriction). The Math.random
+  wording is corrected — a seeded sequence, not one repeated value.
+- **Platform premise fixed:** ctx.runQuery is legal inside queries (same
+  read snapshot); only mutations, actions, and scheduling are flagged.
+- **Server-side checks are import-gated:** files must import from
+  convex/server or _generated/server — chrome.tabs.query is not a Convex
+  function. Client checks (useQuery) and chain checks (ctx.db.query
+  implies Convex) stay ungated.
+- **Range detection reads a look-ahead/look-behind window** joined with
+  single spaces (squashing to nothing glued `return q.eq(` into
+  `returnq.eq(` and destroyed the word boundary): unparseable spans are
+  UNKNOWN, not unbounded.
+- **One finding per chain, the most specific one:** filter-table-scan >
+  index-without-range > index-filter-combo, with the generic
+  unbounded-collect only when no specific diagnosis applies — the
+  audit's rateLimiter 73/74/75 triple is now one finding whose fix
+  (bound the index) is the reviewer's own recommendation.
+- **Severity honesty:** spread-into-patch, public-api-in-server-call,
+  and sequential-run-in-loop are info review candidates — presence is
+  visible, consequence is not. The seven audit counterexample shapes
+  are frozen fixtures (49 total).
+
+**Consequences:** On the audit codebase: 387 findings to 233; unawaited
+116 to 17, clock 48 to 21, index-without-range 5 to 2 (both true
+positives the reviewer's own fixes confirm), write-in-query 4 to 0,
+missing-validator 2 to 0; every audited false-positive site cleared and
+every audited real finding (rateLimiter, the billing lifecycle scans)
+kept. The remaining large groups are declared-info review candidates
+(subscriptions 108, spreads 28, public-api 24) whose blind spots say
+plainly what they cannot establish.
+
+---
+
+## D23 — The claim contract and the shared innocent corpus: prevention as executable
+
+**Date:** 2026-09-09
+
+**Context:** D21 and D22 repaired the same disease twice: checks whose
+claims exceeded their analysis, validated by fixtures that tested
+examples rather than reliability. The external reviewers' deepest point:
+"fixtures validate examples, not general reliability" — and their
+strongest recommendation: "make the important requirements executable."
+
+**Decision:** Two mechanisms, both enforced by the verify gate:
+
+- **The claim contract.** Every declared check states `claim` (one
+  sentence: the observable condition detected, not the consequence),
+  `lookalikes` (innocent shapes that must stay silent — corpus
+  candidates), and `onUnknown` ("narrow" or "skip", required when the
+  check declares engine `needs`). Verify refuses to certify a doctor
+  whose checks lack these — exit 3 with guidance. "This asynchronous
+  code is unsafe" is not a claim; "this expression discards a promise"
+  is. The gate cannot prove reasoning is correct, but it can make
+  unstatable claims unshippable.
+
+- **The shared innocent corpus.** `fixtures/innocent/` holds files that
+  look guilty but aren't — the audit counterexamples as commons. Every
+  doctor's verify automatically runs against the corpus with
+  expected: []; a finding there is a false positive by definition,
+  whoever wrote the check. The corpus ships in the npm package and
+  grows with every audit's discoveries.
+
+All 41 checks across the five bundled doctors now carry contracts.
+The skill teaches the contract as a required section. The D21 wording
+was corrected: the audits measured class-level false-positive rates,
+not report-level precision — the decision log now says so.
+
+**Consequences:** A new doctor cannot be certified without stating what
+it establishes; a regression against any known-innocent shape fails the
+gate; and the corpus compounds — every future audit's counterexamples
+enlarge the commons. What this does NOT do: guarantee correctness on
+unfamiliar repos (the reviewers' caveat, adopted verbatim), or replace
+independent evaluation — the held-out set and per-check precision
+measurement remain the tier-2 process.
+
+---
+
 ## Open questions
 
 - Opt-in metrics/score API (parked, D19): count doctors run and findings

package/doctors/async-doctor.mjs

@@ -19,6 +19,8 @@ export const meta = {
       impact: "Requests cannot be cancelled: navigating away, unmounting, or superseding leaves fetches running to completion.",
       why: "A fetch without a signal has no path to cancellation, so component-driven requests outlive the components that issued them.",
       fix: "Pass an AbortController's signal via the request options and abort it on cleanup or supersede.",
+      claim: "A fetch call whose options contain no signal.",
+      lookalikes: ["signal threaded through a variable the pattern cannot see"],
     },
     {
       id: "unawaited-async-map",
@@ -28,6 +30,9 @@ export const meta = {
       impact: "The async work starts but nothing waits for it: errors vanish silently and the results are lost mid-flight.",
       why: "Array.map returns a new array of promises. Without Promise.all or an await on the result, the async callbacks run fire-and-forget.",
       fix: "Wrap the mapped array in Promise.all and await it — or drop the async if the work should actually be sequential.",
+      claim: "A .map(async ...) result whose binding has no consuming reference (combiner, per-element await, or return) and no inline combiner at the call site.",
+      lookalikes: ["inline Promise.all around the map", "for-await over results", "results returned to the caller"],
+      onUnknown: "narrow",
     },
     {
       id: "uncleared-settimeout-in-effect",
@@ -36,6 +41,8 @@ export const meta = {
       impact: "The callback fires after the component is gone: state updates on unmounted components, work the user cancelled, and hard-to-trace bugs.",
       why: "Every timer started inside an effect must be cleared in that effect's cleanup; an uncleared setTimeout outlives the render that created it.",
       fix: "Assign the timer and return a cleanup that calls clearTimeout with the same identifier.",
+      claim: "A setTimeout inside a useEffect span with no clearTimeout of the same identifier in that effect.",
+      lookalikes: ["timers cleared in cleanup", "lookalike names outside effects"],
     },
   ],
 };