any-doctor 0.0.1

package/docs/kill-test.md

@@ -0,0 +1,54 @@
+# The kill test
+
+**The one empirical question:** can an agent generate ast-grep rules good
+enough that we'd trust them in CI — from intent-only descriptions, on a real
+messy repo?
+
+Everything after this (spec, harness, skill, launch) is gated on the answer.
+This is prototype-shaped: throwaway code that answers a question.
+
+## Method
+
+1. Pick a **real, messy repo** (Nick's Effect codebase — actual conventions,
+   actual aliasing, actual ugly code).
+2. Write **rule intents as one-liners only** (the exact sentences from
+   [example-catalog.md](example-catalog.md)). No hand-tuning allowed.
+3. Have the agent generate each rule + its fixtures into ast-grep YAML.
+4. Run `ast-grep scan` on the repo. **Hand-count** false positives and check
+   seeded/known violations for recall.
+5. **One repair round** allowed per rule: "this finding is wrong because X"
+   → agent revises rule *and* fixtures.
+6. Re-count. Record everything.
+
+## The example spread (tier-sampled)
+
+| Intent | Tier |
+|---|---|
+| Find every remaining import of the old design-system Button | P |
+| Find direct imports of `openai`/`anthropic` outside `lib/ai/` | P |
+| Find route handlers that touch the DB before calling `requireUser()` | R |
+| Find `fetch` calls without an `AbortSignal` | R |
+| Find `.map(async ...)` results never wrapped in `Promise.all` | R |
+| Only `api/` may import from `db/` | M |
+
+(Adjust to the target repo's real conventions — the point is the tier spread,
+not these exact rules.)
+
+## Success criteria
+
+- **Precision ≥ 90%** on the relational rules after one repair round
+  (CI-guard tolerance; pattern rules should be higher)
+- **Recall ≥ 80%** on seeded/known violations
+- Generated rules readable at a glance by a skeptical human in < 2 minutes
+
+## Kill / pivot criteria
+
+- Pattern tier can't express more than half the ruleset → evidence for the
+  oxlint semantic tier (D4 trigger), *before* any SDK is built
+- Precision lands < 75% even after repair → the premise is shaky; write the
+  post-mortem anyway (it's still the launch post)
+
+## Deliverable
+
+The numbers themselves are the launch content:
+"Can an agent write correct lint rules? I measured it."

package/docs/research.md

@@ -0,0 +1,66 @@
+# Research notes
+
+Landscape as of 2026-08-28. Refresh before making claims public.
+
+## React Doctor (millionco/react-doctor) — verified teardown
+
+The inspiration. Monorepo (pnpm/Turborepo, TypeScript) with a telling
+structure:
+
+- `core` — shared rule engine (rules authored once)
+- `eslint-plugin-react-doctor` + `oxlint-plugin-react-doctor` — **two
+  first-class executors**; rules delivered through both ESLint and oxlint
+- `evals` + `fuzz` — rule-quality measurement as first-class packages
+- `react-doctor` CLI — what neither linter can do: project-level analysis,
+  CI mode (PR-diff-scoped reporting: "only issues your change introduced"),
+  and runtime tracing (`scan <url>` launches isolated-profile Chrome, records
+  a DevTools perf trace with per-render component outlines, `--cdp` attach
+  for authed sessions)
+
+**Lessons for us:** (1) multi-executor endgame is validated — shared rule
+semantics, adapters per engine; (2) eval infrastructure is where the value
+lives — they built `evals`/`fuzz` packages; (3) diff-scoped CI reporting is
+the adoption trick for opinionated rules despite legacy backlogs.
+
+Docs: https://www.react.doctor/docs/configuration/eslint-and-oxlint-plugins
+
+## Competitive landscape
+
+- **Semgrep** — AI rule writing; [Multimodal](https://semgrep.dev/products/semgrep-multimodal)
+  combines LLM reasoning with rule-based scanning. Market has already
+  converged on "deterministic rules + AI assist" rather than "LLM judges
+  everything." Validates the inversion; security-oriented.
+- **ast-grep** — has an [agent skill for NL→YAML rules](https://mcpservers.org/agent-skills/ast-grep/ast-grep).
+  We build ON it, not against it. https://github.com/ast-grep/ast-grep
+- **Codemod.com** — NL→codemods (transformation). We do detection-only, which
+  is far easier and nobody has productized "temporary migration linters."
+- **Copilot code review / custom instructions** — NL rules applied
+  non-deterministically on every PR. The zero-infra baseline.
+- **The free baseline to beat:** ask Claude Code/Cursor to write the rule and
+  commit it. What's missing end-to-end today: sentence → *auditable rule with
+  fixtures* → CI forever. The harness, the fixture discipline, and the trust
+  artifacts are the product; generation is commoditizing.
+
+## ast-grep vs oxc (decision D3/D4 summary)
+
+| | ast-grep | oxc/oxlint |
+|---|---|---|
+| Rule artifact | YAML, declarative, ~10–30 lines | JS visitor code, free-form |
+| Analysis | per-file patterns + `inside`/`has`/`precedes` | scope tree, symbols, CFG, types (tsgolint) |
+| Alias/import resolution | no | yes |
+| Native tests | `ast-grep test` snapshots | roll your own |
+| Languages | dozens (tree-sitter) | JS/TS |
+| Generated-artifact safety | data | arbitrary code in repo/CI |
+
+oxc plugins docs: https://oxc.rs/docs/guide/usage/linter/plugins.html
+
+## Key technical facts
+
+- ast-grep relational operators (`inside`, `has`, `precedes`, `follows`) make
+  "X inside Y" and even auth-*ordering* rules declarative.
+- `ast-grep test` + YAML test cases = the fixture harness, mostly free.
+- Effect is a deceptively *friendly* first domain: very regular idioms
+  (gen/yield*/Tag), strong model priors — good for demo, stacks the deck;
+  validate on a messier domain before generalizing.
+- Precision/recall tolerance flips by mode: audit scanner wants recall, CI
+  guard wants ~95%+ precision (muted rules die).

package/docs/vision.md

@@ -0,0 +1,83 @@
+# Vision
+
+## The problem
+
+Every team has a dozen conventions nobody ever wrote a linter for: things
+that keep going wrong, enforced by code review and Slack threads and
+senior-dev memory. Hand-writing lint rules is the friction that kills
+adoption — so the rules never get written. Meanwhile "just have the LLM
+read the codebase and find violations" is non-deterministic, costs
+inference on every run, and can't gate a CI pipeline.
+
+## The core inversion
+
+> The LLM writes the analyzer. Fixtures prove it. CI reruns it forever.
+
+One LLM invocation compiles your one-sentence convention into a doctor
+program — real code written against our typed `ctx` SDK (the pattern
+Cloudflare calls Code Mode; we run it entirely locally, no vendor). After
+that: same repo + same commit = same findings, forever, at zero inference
+cost.
+
+## The experience
+
+```bash
+any-doctor generate "find fetch calls without an AbortSignal"
+any-doctor run .        # report, then walk the findings interactively
+any-doctor verify --all # the trust gate, for every doctor you own
+```
+
+The bar is React Doctor's CLI: fast scan line, grouped findings with
+file:line evidence, severity glyphs, declared blind spots, and a
+hand-off point where the findings feed your LLM to fix. The analyzer
+itself is generated on demand and scoped to exactly what you asked about.
+
+## The novel axis: lifecycle, not domain
+
+Existing linters assume rules are permanent artifacts written by experts
+and shipped in a registry. Any Doctor's moves:
+
+1. **Authoring cost → a sentence.** From intent to fixture-gated doctor
+   in one agent session.
+2. **Rules can be temporary.** Migration audits ("find every remaining
+   import of the old design-system Button") are write-one-run-once-delete.
+   Upgrade doctors compile a library changelog into pre-upgrade detection
+   rules — `tsc` catches mechanical breaks *after* you upgrade; this
+   estimates the cost *before*.
+3. **Doctors encode *your* architecture**, not a framework's — the
+   opinionated house rules that could never live in a public plugin.
+
+The JS family (TS/JS/JSX/Vue/Svelte) is the native range; Effect was the
+first dogfood domain because its idioms are regular and underserved.
+
+## Trust model
+
+- Every doctor ships fixtures (seeded files + exact-set expected findings).
+  `verify` is the gate: missing expected findings fail recall, unexpected
+  findings fail precision.
+- Generated programs declare blind spots as data; reports print them.
+- The CLI independently re-verifies anything an agent produces — an
+  agent's output is never trusted on its own word.
+- Doctors are boring files in your repo: auditable, diffable, reviewable
+  in PRs. The runner seam (today a node child process) is where a
+  technical sandbox plugs in when doctors become third-party.
+
+## Two modes, opposite tolerances
+
+- **Audit scanner** ("find every external HTTP endpoint we call"): recall
+  matters; humans triage.
+- **CI guard** (saved doctors gating PRs): precision is king — a rule with
+  a few percent false-positive rate gets muted within a week.
+
+The funnel is audit → save → CI, and the tolerances flip mid-funnel.
+
+## Non-goals (v0)
+
+- ~~Scores/dashboards until precision justifies them~~ — revisited: the
+  score header and review browser shipped, because findings carry
+  file/line evidence and fixture-proven precision, so the number
+  summarizes rather than substitutes.
+- Languages beyond the JS family.
+- Hand-rolled parser/engine internals — engines live behind `ctx` as
+  replaceable primitives (ast-grep today, oxc-backed semantics later).
+- Cloudflare or any hosted component. The Code Mode pattern, fully local.

package/doctors/AGENTS.md

@@ -0,0 +1,103 @@
+# any-doctor — doctor generation skill
+
+You are writing a **doctor program**: a small analysis tool that detects one
+codebase convention, plus the fixtures that prove it works. The INTENT is
+the entire specification. Derive everything from the intent alone — never
+scan a target repository to tune your doctor against its code.
+
+## The contract
+
+Two files, exactly:
+
+`doctors/<slug>.mjs` (slug = short kebab-case from the intent):
+
+```js
+export const meta = {
+  id: "<slug>",                       // kebab-case, matches the filename
+  description: "<one-line finding text, shown in reports>",
+  severity: "warning",                // "error" | "warning" | "info"
+  blindSpots: [                       // what this approach CANNOT see — required
+    "<honest limitation>",
+  ],
+};
+
+export async function doctor(ctx) {
+  // inspect the codebase, emit findings
+}
+```
+
+`doctors/<slug>.fixtures.mjs`:
+
+```js
+export const fixtures = [
+  {
+    name: "<what this case proves>",
+    seed: { "src/example.ts": "...inline file contents..." },
+    expected: [{ file: "src/example.ts", line: 2 }],   // exact set on (file, line)
+  },
+  // include cases where expected: [] — innocent lookalikes must stay silent
+];
+```
+
+`ctx` is the only capability a doctor has:
+
+- `ctx.files.list(exts?)` → relative paths (default .ts/.tsx/.js/.jsx/.mjs)
+- `ctx.files.read(rel)` → file contents
+- `ctx.search.pattern(pattern, language?)` → `[{ file, line, column, text }]`
+  (ast-grep pattern syntax, e.g. `"fetch($URL)"`; requires ast-grep installed)
+- `ctx.report.finding({ file, line, column?, message?, severity? })`
+
+Zero dependencies. Node >= 18. The only imports allowed are `node:` builtins.
+
+## Hard workflow
+
+1. Write both files.
+2. Run: `any-doctor verify doctors/<slug>.mjs` (or `node bin/cli.js verify doctors/<slug>.mjs`).
+3. ALL fixtures must pass. Iterate until green — a failed fixture is the
+   system telling you your rule or your expectations are wrong; fix the rule,
+   or fix the expectation if the expectation itself was wrong.
+4. Report: id, what it detects, declared blind spots, fixture count.
+
+## Fixture discipline
+
+- Matching is exact-set on (file, line): a missing expected finding fails
+  (recall); an unexpected extra finding fails (precision). Get both sides right.
+- Every doctor needs at least one `expected: []` fixture containing code that
+  LOOKS like a violation but isn't — the lookalike that a naive implementation
+  would wrongly flag.
+- Cover the simplest violation and the sneakiest one. Vary quote styles where
+  syntax allows.
+- Findings are locations. Wording lives in `meta.description`; use
+  per-finding `message` only when one violation needs its own explanation.
+
+## Honesty rules
+
+- `blindSpots` is required and is data: declare what your approach cannot
+  see (aliased imports, cross-file references, dynamic constructs).
+- Never silently narrow the intent. If the intent is not fully statically
+  checkable, implement the closest honest version and declare the gap.
+- A clean run must mean clean. Never swallow errors into empty findings.
+
+## Failure lessons (each of these shipped in a real doctor — do not repeat)
+
+1. `String.replace(text, x)` replaces only the FIRST occurrence. When
+   substituting placeholders into a regex source string, use a global regex:
+   `.replace(/NAME/g, escaped)`.
+2. Escape anything variable you interpolate into a RegExp
+   (`s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")`).
+3. Match the innermost construct once. `await fetch(x)` contains a
+   `fetch(x)` node — a pattern for the inner call already matches it;
+   adding wrapper variants double-reports.
+4. Read each file once per pass. Don't re-read inside loops.
+5. If the intent is not fully statically checkable (cross-file references,
+   runtime behavior, types), implement the closest honest version and
+   declare the gap in `blindSpots`. Never drop an intent condition silently.
+6. Your own `console.log` goes to stderr, not the report. Don't rely on
+   stdout — stdout carries only the structured result.
+
+## What NOT to do
+
+- Don't touch any file other than the two contract files.
+- Don't add dependencies or imports beyond `node:` builtins.
+- Don't scan a target repository to "tune" the doctor against its code.
+- Don't mark a fixture green by weakening the expectation — strengthen the doctor.

package/doctors/api-route-files-do-import.fixtures.mjs

@@ -0,0 +1,61 @@
+export const fixtures = [
+  {
+    name: "reports an app API route without an auth middleware import",
+    seed: {
+      "src/app/api/users/route.ts": `export async function GET() {
+  return Response.json([]);
+}`,
+    },
+    expected: [{ file: "src/app/api/users/route.ts", line: 1 }],
+  },
+  {
+    name: "reports a pages API route without an auth middleware import",
+    seed: {
+      "src/pages/api/account.js": `export default function handler(request, response) {
+  response.status(200).json({ ok: true });
+}`,
+    },
+    expected: [{ file: "src/pages/api/account.js", line: 1 }],
+  },
+  {
+    name: "allows a route with a named auth middleware import",
+    seed: {
+      "src/app/api/private/route.ts": `import { requireUser } from "@/middleware/auth";
+
+export async function GET(request) {
+  return Response.json({ user: await requireUser(request) });
+}`,
+    },
+    expected: [],
+  },
+  {
+    name: "allows a side-effect auth import with single quotes",
+    seed: {
+      "src/pages/api/session.ts": `import '../auth';
+
+export default function handler(request, response) {
+  response.status(204).end();
+}`,
+    },
+    expected: [],
+  },
+  {
+    name: "does not treat an auth-looking comment as an import",
+    seed: {
+      "src/app/api/status/route.ts": `// import { requireUser } from '@/middleware/auth';
+export async function GET() {
+  return Response.json({ status: "ok" });
+}`,
+    },
+    expected: [{ file: "src/app/api/status/route.ts", line: 1 }],
+  },
+  {
+    name: "does not inspect non-API modules with auth-looking code",
+    seed: {
+      "src/components/auth-card.tsx": `export function AuthCard() {
+  return <div>API route</div>;
+}`,
+    },
+    expected: [],
+  },
+];

package/doctors/api-route-files-do-import.mjs

@@ -0,0 +1,26 @@
+export const meta = {
+  id: "api-route-files-do-import",
+  description: "API route file does not import auth middleware.",
+  severity: "warning",
+  blindSpots: [
+    "Identifies API route files only by an api path segment, so unconventional route locations are not checked and non-route modules within an api directory can be reported.",
+    "Recognizes auth middleware only through static ES module import specifiers containing auth or middleware; aliases, dynamic imports, re-exports, and middleware applied by framework configuration are not recognized.",
+    "Cannot determine whether an imported auth or middleware module actually protects the route at runtime.",
+  ],
+};
+
+const apiDirectory = /(?:^|\/)api(?:\/|$)/;
+const authMiddlewareImport = /^\s*import\s*(?:[\s\S]*?\sfrom\s*)?["']([^"']*(?:auth|middleware)[^"']*)["']\s*;?/gim;
+
+export async function doctor(ctx) {
+  for (const file of await ctx.files.list()) {
+    if (!apiDirectory.test(file)) continue;
+
+    const source = await ctx.files.read(file);
+    authMiddlewareImport.lastIndex = 0;
+
+    if (!authMiddlewareImport.test(source)) {
+      ctx.report.finding({ file, line: 1 });
+    }
+  }
+}

package/doctors/async-doctor.fixtures.mjs

@@ -0,0 +1,147 @@
+export const fixtures = [
+  {
+    "name": "reports a fetch call without options",
+    "seed": {
+      "src/request.ts": "fetch('/api/users');\n"
+    },
+    "expected": [
+      {
+        "file": "src/request.ts",
+        "line": 1
+      }
+    ]
+  },
+  {
+    "name": "reports options that omit signal",
+    "seed": {
+      "src/request.ts": "fetch(\"/api/users\", { method: 'POST' });\n"
+    },
+    "expected": [
+      {
+        "file": "src/request.ts",
+        "line": 1
+      }
+    ]
+  },
+  {
+    "name": "accepts an explicit signal property among other options",
+    "seed": {
+      "src/request.ts": "fetch('/api/users', { method: 'GET', signal: controller.signal });\n"
+    },
+    "expected": []
+  },
+  {
+    "name": "accepts a shorthand signal property",
+    "seed": {
+      "src/request.ts": "fetch('/api/users', { signal, headers: {} });\n"
+    },
+    "expected": []
+  },
+  {
+    "name": "reports a nested signal that is not a RequestInit signal",
+    "seed": {
+      "src/request.ts": "fetch('/api/users', { headers: { signal: 'not-an-abort-signal' } });\n"
+    },
+    "expected": [
+      {
+        "file": "src/request.ts",
+        "line": 1
+      }
+    ]
+  },
+  {
+    "name": "reports an options variable whose signal cannot be determined",
+    "seed": {
+      "src/request.ts": "const options = { signal: controller.signal };\nfetch('/api/users', options);\n"
+    },
+    "expected": [
+      {
+        "file": "src/request.ts",
+        "line": 2
+      }
+    ]
+  },
+  {
+    "name": "unawaited map(async) is flagged",
+    "seed": {
+      "src/a.ts": "export function work(ids: string[]) {\n  const results = ids.map(async id => load(id))\n  return results.length\n}"
+    },
+    "expected": [
+      {
+        "file": "src/a.ts",
+        "line": 2
+      }
+    ]
+  },
+  {
+    "name": "Promise.all-consumed result is not flagged",
+    "seed": {
+      "src/b.ts": "export async function work(ids: string[]) {\n  const results = ids.map(async id => load(id))\n  return Promise.all(results)\n}"
+    },
+    "expected": []
+  },
+  {
+    "name": "directly awaited result is not flagged",
+    "seed": {
+      "src/c.ts": "export async function work(ids: string[]) {\n  const results = ids.map(async id => load(id))\n  await results\n}"
+    },
+    "expected": []
+  },
+  {
+    "name": "allSettled-consumed result in a later batch loop is not flagged",
+    "seed": {
+      "src/d.ts": "export async function work(items: string[]) {\n  const allPromises = items.map(async item => load(item))\n  const allResults = await Promise.allSettled(allPromises)\n  return allResults\n}"
+    },
+    "expected": []
+  },
+  {
+    "name": "reports an assigned timeout without cleanup",
+    "seed": {
+      "src/example.tsx": "useEffect(() => {\n  const timer = setTimeout(() => save(), 1000);\n}, []);\n"
+    },
+    "expected": [
+      {
+        "file": "src/example.tsx",
+        "line": 2
+      }
+    ]
+  },
+  {
+    "name": "allows cleanup of the assigned timeout",
+    "seed": {
+      "src/example.tsx": "useEffect(() => {\n  const timer = setTimeout(() => save(), 1000);\n  return () => clearTimeout(timer);\n}, []);\n"
+    },
+    "expected": []
+  },
+  {
+    "name": "reports only the timer missing from multi-timer cleanup",
+    "seed": {
+      "src/example.jsx": "useEffect(() => {\n  const fast = setTimeout(work, 50);\n  let slow = setTimeout(work, 500);\n  return () => clearTimeout(fast);\n}, []);\n"
+    },
+    "expected": [
+      {
+        "file": "src/example.jsx",
+        "line": 3
+      }
+    ]
+  },
+  {
+    "name": "reports an unassigned timer despite unrelated cleanup",
+    "seed": {
+      "src/example.js": "useEffect(() => {\n  setTimeout(notify, 100);\n  return () => clearTimeout(existingTimer);\n}, []);\n"
+    },
+    "expected": [
+      {
+        "file": "src/example.js",
+        "line": 2
+      }
+    ]
+  },
+  {
+    "name": "ignores timeout lookalikes outside effects and in comments",
+    "seed": {
+      "src/example.ts": "const message = 'setTimeout(callback, 10)';\n// useEffect(() => setTimeout(callback, 10))\nfunction later() {\n  setTimeout(callback, 10);\n}\n"
+    },
+    "expected": []
+  }
+];