any-doctor 0.0.1

package/CONTEXT.md

@@ -0,0 +1,128 @@
+# CONTEXT.md — domain glossary
+
+Canonical vocabulary for any-doctor. Glossary only — no implementation.
+When a term here conflicts with language elsewhere, this file wins.
+
+## Doctor program
+
+The artifact an LLM writes: a JavaScript module that inspects a target
+codebase through the DoctorCtx and emits findings. One doctor program
+encodes one convention the team cares about. Retired synonym: "lint rule."
+
+## Doctor run
+
+One execution of a doctor program against one target directory.
+Deterministic for a given engine version: `ctx.search` answers via the host
+(the doctor process cannot spawn — it runs under Confinement, and any-doctor
+runs ast-grep itself, returning matches over a dedicated channel), so
+results can vary across engine upgrades.
+
+## RunOutcome
+
+One scan invocation's batch of results, assembled once and rendered by the
+report and the dashboard alike: the ReportGroups that ran, the doctor ids
+that crashed (data, named), the slugs Confinement skipped, the doctor
+id → program path map for re-run commands, and the target's file count and
+the batch's wall-clock duration — one defined meaning per field.
+
+## Confinement
+
+The layered policy that makes a doctor program safe to execute. A doctor is
+a single self-contained file: it may not import anything, and everything
+else reaches it through `ctx`. The layers, in order: the static capability
+scan refuses named capabilities before execution; the run happens under
+Node's permission model (writes, subprocesses, and native addons denied;
+worker threads exist only as the import guard's carrier and inherit every
+denial); an import guard refuses every module resolution a doctor attempts;
+and the network globals are deleted from the process before doctor code
+runs. There is no override in any mode.
+
+## Finding
+
+One emitted finding: a location (file, line) plus optional per-finding
+message or severity override. "Issue" and "instance" are retired
+synonyms — Finding is the term in code, copy, and prompts. The
+doctor-level truth (id, description, default severity, blind spots)
+lives in the program's meta, not in individual findings.
+
+## Check
+
+One rule within a doctor program. A finding names its check via `rule`;
+the check's meta supplies description, severity, impact, why, and fix;
+the doctor's meta supplies the defaults when a finding names no check.
+A check id is a short kebab-case noun phrase over [a-z0-9-], unique
+within its doctor, naming the defect (fetch-calls-without-abortsignal,
+filter-table-scan). One doctor program, many checks.
+
+## Doctor contract
+
+The interface shared by doctor programs, the runner, the report, the
+fixture harness, and the generator prompt. The single place where the
+shape of ctx, meta, findings, and the runner protocol is defined.
+
+## DoctorCtx (ctx)
+
+The capability boundary a doctor program is expected to use: read-only,
+repo-scoped file access, structural search, and a finding emitter.
+Confinement enforces it: outside ctx there is nothing — no imports, no
+writes, no subprocesses, no network.
+
+## Engine
+
+The structural-search backend a DoctorCtx uses to answer ctx.search.
+ast-grep is the engine today; oxc is a candidate for TypeScript-heavy
+repos. Engine selection is invisible to doctor programs: one doctor
+program runs unchanged on any engine. One module owns the invocation
+(src/engine.ts); the search host sits on it, and the sdk asks the host —
+there is exactly one path, with no unconfined fallback.
+
+## Meta
+
+A doctor program's declared data: id, description, default severity,
+optional category, optional checks (one CheckMeta per check), blind
+spots. Authored as data, never as comments; read by the report, the
+review tree, and the generator prompt.
+
+## Seed
+
+A set of inline files (paths + contents) a fixture materializes into a
+temporary directory so a doctor program can be exercised against
+known input.
+
+## Fixture
+
+One seed plus the findings expected from running a doctor program against
+it. Expected findings match exactly on (file, line): a missing expected
+finding is a recall failure; an unexpected finding is a precision failure.
+
+## Verify
+
+Running a doctor program against its fixtures and diffing the findings.
+The trust gate: a doctor program is not considered working until verify
+passes.
+
+## Runner
+
+The process boundary that loads a doctor program, injects ctx, and
+returns framed results. Today a local node child process; the same
+contract must hold for any future sandbox.
+
+## Registry
+
+The record of installed doctor programs per scope. Each doctor's meta is
+its registry entry; the doctors/ directory itself is the registry —
+discovery reads it directly, with no separate index or cache.
+
+## Scope
+
+Where a doctor program lives: repo-local (`./doctors/`, committed with
+the consuming repo) or user-global (`~/.any-doctor/doctors/`, available
+in every repo). Repo-local wins slug collisions. Scanning a target repo
+never writes to any scope.
+
+## Skill
+
+The instructions any-doctor provides so an agent can create a doctor that
+fits the contract. Planted as `AGENTS.md` in a scope directory and also
+served verbatim by `generate`. Any Doctor equips agents with the skill;
+it never launches, deploys, or speaks for an agent.

package/README.md

@@ -0,0 +1,68 @@
+# any-doctor
+
+> Your agent writes the analyzer. Fixtures prove it. CI reruns it forever.
+
+Any Doctor turns a one-sentence convention ("find `.map(async ...)` results
+that are never awaited") into a **doctor program** — a small piece of
+analysis code your LLM writes against our typed `ctx` API. The CLI runs it
+and renders a React-Doctor-style report: score, grouped findings with
+file:line evidence, declared blind spots, an interactive review browser,
+and a copy-paste handoff so your agent can fix what was found. The saved
+program reruns deterministically in CI with zero inference.
+
+Any Doctor equips agents; it never deploys them. Everything runs locally.
+No Cloudflare, no API keys, no server.
+
+## Usage
+
+```bash
+any-doctor generate "find fetch calls without an AbortSignal"   # copies the exact prompt for your agent
+any-doctor verify doctors/fetch-without-abort-signal.mjs        # fixture gate (exact-set)
+any-doctor run doctors/fetch-without-abort-signal.mjs path/to/repo   # scan + score + report + review menu
+```
+
+`generate` plants the skill as `AGENTS.md` in the scope dir (agents load it
+natively) and copies the generation prompt — paste it into your own agent
+session, any agent, GUI or CLI. When it has written the doctor + fixtures,
+`verify` gates it: missing expected findings fail recall, unexpected ones
+fail precision. `run` and `verify` never touch a model or an agent — pipe
+the output (or set `ANY_DOCTOR_HEADLESS=1`) for stable CI output. Requires
+Node ≥ 18.
+
+A doctor program is `<name>.mjs` (exports `meta` + `doctor(ctx)`) next to
+its fixture module `<name>.fixtures.mjs` (seeds + expected findings).
+See [CONTEXT.md](CONTEXT.md) for the vocabulary and
+[doctors/async-doctor.mjs](doctors/async-doctor.mjs) for a working
+example: one doctor, many checks — async hygiene as a category, with
+per-check fixtures and the interactive check tree in `run`.
+
+## Docs
+
+| Doc | What it holds |
+|---|---|
+| [CONTEXT.md](CONTEXT.md) | Domain glossary — canonical terms |
+| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D16). Read first; don't relitigate |
+| [docs/vision.md](docs/vision.md) | Product idea and the lifecycle novelty |
+| [docs/features.md](docs/features.md) | Doctor discovery & registry spec + status |
+| [docs/research.md](docs/research.md) | Landscape, React Doctor teardown |
+| [docs/kill-test.md](docs/kill-test.md) + [docs/RESULTS.md](docs/RESULTS.md) | The validation experiment and its numbers |
+| [docs/REPAIR-LOG.md](docs/REPAIR-LOG.md) | Generation-bug categories — feeds the generation skill |
+| [docs/example-catalog.md](docs/example-catalog.md) | Rule intents across the JS ecosystem |
+
+## Where we are (2026-09-03)
+
+1. ✅ Contract v0, verify harness, pilot doctor, kill test, packaging
+2. ✅ Generation: skill + prompt handoff (D14 — copy-based, agent-agnostic)
+3. ✅ UI layer: score header, category rollup, review browser, post-report menu
+4. ✅ Discovery & registry: fuzzy picker, repo-local + global scopes, `--all` batch modes
+5. ⬜ Frozen-fixture protocol + authored eval corpus (the trust upgrade — first-shot 10/10 is currently self-graded)
+6. ⬜ Grow `ctx`: symbols/imports resolution, JS-family languages
+7. ⬜ Publish: npm, GitHub, CI workflow, launch post
+
+## Principles
+
+- The report comes from the generated program's evidence, not the LLM's opinion.
+- Fixtures gate everything: a doctor that hasn't passed `verify` doesn't exist.
+- Programs declare their blind spots as data.
+- Any Doctor equips agents; it never launches, deploys, or speaks for them.
+- Everything runs locally. The runner seam (today a node child process) is where any future sandbox plugs in.

package/bin/capabilities.d.ts

@@ -0,0 +1,15 @@
+export type CapabilityLevel = "red" | "yellow";
+export interface CapabilityFinding {
+    capability: string;
+    level: CapabilityLevel;
+    line: number;
+    detail: string;
+}
+export interface CapabilityReport {
+    findings: CapabilityFinding[];
+    red: CapabilityFinding[];
+    yellow: CapabilityFinding[];
+}
+export declare function scanCapabilities(source: string): CapabilityReport;
+export declare function scanDoctorFile(programPath: string): CapabilityReport;
+export declare function capabilitySummary(report: CapabilityReport): string;

package/bin/capabilities.js

@@ -0,0 +1,131 @@
+import * as fs from "fs";
+const MODULE_SPEC = /(?:\bfrom\s+|\brequire\s*\(\s*)["'](node:)?/;
+const RULES = [
+    // --- red: no legitimate use in a doctor ---
+    { capability: "network", level: "red", on: "raw", kind: "network module import", pattern: new RegExp(MODULE_SPEC.source + String.raw `(https?|http2|net|tls|dns|dgram|undici)["']`) },
+    { capability: "network", level: "red", on: "masked", kind: "fetch", pattern: /\bfetch\s*\(/ },
+    { capability: "network", level: "red", on: "masked", kind: "http call", pattern: /\bhttps?\s*\.\s*(?:get|request|createServer|Agent)\s*\(/ },
+    { capability: "network", level: "red", on: "masked", kind: "WebSocket/XMLHttpRequest", pattern: /\bnew\s+(?:WebSocket|XMLHttpRequest)\b/ },
+    { capability: "file write", level: "red", on: "masked", kind: "fs write call", pattern: /\bfs\s*\.\s*(?:promises\s*\.\s*)?(?:writeFile|appendFile|createWriteStream|rm|unlink|rename|mkdir|rmdir|truncate|chmod|chown)\w*\s*\(|\bfs\s*\.\s*open\s*\(\s*[^,)]*,\s*["']w/ },
+    { capability: "file write", level: "red", on: "masked", kind: "write call (destructured import)", pattern: /\b(?:writeFile|appendFile|createWriteStream|rmSync|unlinkSync|rm|unlink)\s*\(/ },
+    { capability: "subprocess", level: "red", on: "raw", kind: "child_process import", pattern: new RegExp(MODULE_SPEC.source + String.raw `child_process["']`) },
+    { capability: "subprocess", level: "red", on: "masked", kind: "process spawn call", pattern: /(?<![.\w])(?:exec|execSync|spawn|spawnSync|execFile|execFileSync|fork)\s*\(/ },
+    // A doctor is a single self-contained file: no imports of any kind.
+    { capability: "import", level: "red", on: "raw", kind: "import statement (doctors are single-file programs)", pattern: /(?:\bimport\b|\bexport\b)[^\n]*\bfrom\s*["'][^"']*["']/ },
+    { capability: "import", level: "red", on: "raw", kind: "side-effect import (doctors are single-file programs)", pattern: /^\s*import\s*["'][^"']*["']/ },
+    { capability: "import", level: "red", on: "masked", kind: "dynamic import (doctors are single-file programs)", pattern: /\bimport\s*\(/ },
+    // --- yellow: legal but out-of-contract, surface it ---
+    // (No "fs import" yellow rule exists: every import line is red above —
+    // the single-file law — so an fs-import yellow could never fire.)
+    { capability: "direct fs read", level: "yellow", on: "masked", kind: "fs read call (bypasses ctx.files)", pattern: /\bfs\s*\.\s*(?:promises\s*\.\s*)?(?:readFile|readdir|stat|existsSync|createReadStream)\w*\s*\(/ },
+    { capability: "environment", level: "yellow", on: "masked", kind: "process.env", pattern: /\bprocess\s*\.\s*env\b/ },
+];
+function maskNonCode(source) {
+    const chars = source.split("");
+    let index = 0;
+    while (index < source.length) {
+        const char = source[index];
+        const next = source[index + 1];
+        if (char === "/" && next === "/") {
+            const end = source.indexOf("\n", index + 2);
+            const stop = end === -1 ? source.length : end;
+            for (let cursor = index; cursor < stop; cursor += 1)
+                chars[cursor] = " ";
+            index = stop;
+        }
+        else if (char === "/" && next === "*") {
+            const end = source.indexOf("*/", index + 2);
+            const stop = end === -1 ? source.length : end + 2;
+            for (let cursor = index; cursor < stop; cursor += 1) {
+                if (chars[cursor] !== "\n")
+                    chars[cursor] = " ";
+            }
+            index = stop;
+        }
+        else if (char === "'" || char === '"' || char === "`") {
+            const quote = char;
+            let cursor = index + 1;
+            while (cursor < source.length) {
+                if (source[cursor] === "\\")
+                    cursor += 2;
+                else if (source[cursor] === quote) {
+                    cursor += 1;
+                    break;
+                }
+                else
+                    cursor += 1;
+            }
+            for (let position = index; position < cursor; position += 1) {
+                if (chars[position] !== "\n")
+                    chars[position] = " ";
+            }
+            index = cursor;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return chars.join("");
+}
+// One finding per rule per line; the first matching rule wins a line so the
+// report stays a signal, not a wall.
+export function scanCapabilities(source) {
+    const maskedLines = maskNonCode(source).split("\n");
+    const rawLines = source.split("\n");
+    const findings = [];
+    for (let i = 0; i < rawLines.length; i++) {
+        for (const rule of RULES) {
+            const line = rule.on === "raw" ? rawLines[i] : maskedLines[i];
+            if (line !== undefined && rule.pattern.test(line)) {
+                findings.push({
+                    capability: rule.capability,
+                    level: rule.level,
+                    line: i + 1,
+                    detail: `${rule.kind} (line ${i + 1})`,
+                });
+                break;
+            }
+        }
+    }
+    return {
+        findings,
+        red: findings.filter(f => f.level === "red"),
+        yellow: findings.filter(f => f.level === "yellow"),
+    };
+}
+// One scan per file per process: the gate, verify's capability line, and
+// the tests all read the same report instead of re-scanning.
+const scanCache = new Map();
+export function scanDoctorFile(programPath) {
+    const cached = scanCache.get(programPath);
+    if (cached !== undefined)
+        return cached;
+    const report = readAndScan(programPath);
+    scanCache.set(programPath, report);
+    return report;
+}
+function readAndScan(programPath) {
+    let source = "";
+    try {
+        source = fs.readFileSync(programPath, "utf8");
+    }
+    catch {
+        // A missing file is the runner's error to report; the gate stays quiet
+        // so the layers don't talk over each other.
+        return { findings: [], red: [], yellow: [] };
+    }
+    return scanCapabilities(source);
+}
+export function capabilitySummary(report) {
+    if (report.findings.length === 0) {
+        return "reads via ctx only — no imports, no network, no writes, no subprocesses";
+    }
+    const parts = [];
+    if (report.red.length > 0) {
+        parts.push(`RED: ${[...new Set(report.red.map(f => f.capability))].join(", ")}`);
+    }
+    if (report.yellow.length > 0) {
+        parts.push(`note: ${[...new Set(report.yellow.map(f => f.capability))].join(", ")}`);
+    }
+    return parts.join(" · ");
+}

package/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;