any-doctor 0.0.1

package/bin/search-host.js

@@ -0,0 +1,56 @@
+import * as os from "os";
+import * as path from "path";
+import { SEARCH_REQUEST } from "./contract.js";
+import { runEngineSearch } from "./engine.js";
+// The search host: the doctor child cannot spawn (Confinement), so it asks
+// any-doctor to run the Engine over a dedicated channel. This module is
+// the host side — a pure function from request line to response JSON,
+// directly testable without a real doctor child.
+//
+// The root check is a security decision: a run may search its target, a
+// verify may search its fixture sandboxes under the temp dir, and meta may
+// not search at all.
+export function searchBase(mode) {
+    switch (mode.kind) {
+        // Verify sandboxes are seeded under the temp dir with this prefix —
+        // not the whole temp dir, and nothing else in it.
+        case "verify": return path.join(os.tmpdir(), "any-doctor-verify-");
+        case "run": return mode.root;
+        case "meta": return "";
+    }
+}
+// Bases are anchors: a run's target directory (anything beneath it), or
+// verify's sandbox prefix (any any-doctor-verify-* sandbox). The prefix
+// form ends in "-" on purpose — mkdtemp appends to it.
+function withinBase(root, base) {
+    if (root === base)
+        return true;
+    if (base.endsWith("-"))
+        return root.startsWith(base);
+    return root.startsWith(base + path.sep);
+}
+// One request line in, one response body out (the SEARCH_RESULT sentinel
+// is framing added by the transport in the runner). Returns null for lines
+// that are not requests — the channel carries nothing else, so they are
+// ignored rather than answered.
+export function handleSearchLine(line, mode, engine = runEngineSearch) {
+    var _a;
+    if (!line.startsWith(SEARCH_REQUEST))
+        return null;
+    let req;
+    try {
+        req = JSON.parse(line.slice(SEARCH_REQUEST.length));
+    }
+    catch {
+        return JSON.stringify({ error: "ctx.search failed: malformed host request" });
+    }
+    const base = searchBase(mode);
+    // resolve() collapses `..` and anchors relatives — a prefix check on the
+    // raw string would let /target/../../etc through.
+    const root = typeof req.root === "string" ? path.resolve(req.root) : "";
+    if (base === "" || !withinBase(root, base)) {
+        return JSON.stringify({ error: "ctx.search failed: search root is outside the allowed target" });
+    }
+    const r = engine(String((_a = req.pattern) !== null && _a !== void 0 ? _a : ""), typeof req.language === "string" ? req.language : "TypeScript", root);
+    return r.ok ? JSON.stringify({ matches: r.matches }) : JSON.stringify({ error: r.error });
+}

package/bin/select.d.ts

@@ -0,0 +1,35 @@
+import { BrokenDoctor } from "./discover.js";
+import { TtyEnv } from "./tty.js";
+export interface SelectionRow {
+    scope: string;
+    slug: string;
+    description: string;
+}
+export type Selection = {
+    kind: "doctor";
+    doctorPath: string;
+    skipped: BrokenDoctor[];
+    unsafe: string[];
+} | {
+    kind: "not-found";
+    arg: string;
+} | {
+    kind: "none-discovered";
+    broken: BrokenDoctor[];
+    unsafe: string[];
+} | {
+    kind: "non-interactive";
+    rows: SelectionRow[];
+    skipped: BrokenDoctor[];
+    unsafe: string[];
+} | {
+    kind: "cancelled";
+};
+export interface SelectOptions {
+    cwd: string;
+    globalDir?: string;
+    useColor: boolean;
+    allowPicker?: boolean;
+    env: TtyEnv;
+}
+export declare function selectDoctor(doctorArg: string | undefined, options: SelectOptions): Promise<Selection>;

package/bin/select.js

@@ -0,0 +1,45 @@
+import { brokenDoctors, discoverDoctors, resolveDoctorPath, unsafeSlugs } from "./discover.js";
+import { canRunTui } from "./tty.js";
+import { pickItemOn } from "./picker.js";
+export async function selectDoctor(doctorArg, options) {
+    if (doctorArg !== undefined) {
+        const resolved = resolveDoctorPath(doctorArg, options.cwd, options.globalDir !== undefined ? { globalDir: options.globalDir } : undefined);
+        return resolved !== null
+            ? { kind: "doctor", doctorPath: resolved, skipped: [], unsafe: [] }
+            : { kind: "not-found", arg: doctorArg };
+    }
+    const discovered = await discoverDoctors(options.cwd, options.globalDir !== undefined ? { globalDir: options.globalDir } : undefined);
+    const valid = discovered.filter(d => d.meta !== null);
+    const unsafe = unsafeSlugs(discovered);
+    const broken = brokenDoctors(discovered);
+    if (valid.length === 0)
+        return { kind: "none-discovered", broken, unsafe };
+    // The gate runs before a picker ever starts, so "cancelled" can only mean
+    // the user ended the pick — never "this isn't a terminal".
+    if (!canRunTui(options.env) || options.allowPicker === false) {
+        return {
+            kind: "non-interactive",
+            skipped: broken,
+            unsafe,
+            rows: valid.map(d => ({
+                scope: d.scope,
+                slug: d.slug,
+                description: d.meta.description,
+            })),
+        };
+    }
+    const chosen = await pickItemOn(options.env, valid.map(d => ({
+        id: d.slug,
+        label: d.meta.description,
+        sub: d.scope,
+        severity: d.meta.severity,
+    })), options.useColor, "Select a doctor");
+    if (chosen === null)
+        return { kind: "cancelled" };
+    return {
+        kind: "doctor",
+        doctorPath: valid.find(d => d.slug === chosen.id).path,
+        skipped: broken,
+        unsafe,
+    };
+}

package/bin/tty.d.ts

@@ -0,0 +1,38 @@
+export interface TtyEnv {
+    stdin: TtyStdin;
+    stdout: TtyStdout;
+}
+export declare function processTtyEnv(): TtyEnv;
+export declare function canRunTui(env: {
+    stdin: {
+        readonly isTTY?: boolean;
+    };
+    stdout: {
+        readonly isTTY?: boolean;
+    };
+}): boolean;
+export interface TtyStdin {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: "data", listener: (chunk: string | Buffer) => void): unknown;
+    removeListener(event: "data", listener: (chunk: string | Buffer) => void): unknown;
+}
+export interface TtyStdout {
+    readonly isTTY?: boolean;
+    columns?: number;
+    rows?: number;
+    write(s: string): unknown;
+}
+export declare function visibleWidth(s: string): number;
+export declare function truncateVisible(s: string, width: number): string;
+export declare function paintFrame(stdout: TtyStdout, frame: string, cols: number): void;
+export interface RunTtyOptions<T> {
+    stdin: TtyStdin;
+    stdout: TtyStdout;
+    frame: () => string;
+    onKey: (key: string, finish: (result: T) => void) => void;
+}
+export declare function runTty<T>(options: RunTtyOptions<T>): Promise<T>;

package/bin/tty.js

@@ -0,0 +1,94 @@
+import { createKeyFeed } from "./keys.js";
+// The one adapter from Node's process stdio to the tty seam.
+export function processTtyEnv() {
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+    };
+}
+// "Is this a real terminal" — the shared floor of every TUI decision.
+// Deliberately excludes headless env vars and width heuristics: those are
+// report-vs-dashboard policy and belong to the command layer.
+export function canRunTui(env) {
+    return Boolean(env.stdin.isTTY && env.stdout.isTTY);
+}
+export function visibleWidth(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+export function truncateVisible(s, width) {
+    if (visibleWidth(s) <= width)
+        return s;
+    let out = "";
+    let w = 0;
+    for (const ch of s.replace(/\x1b\[[0-9;]*m/g, "")) {
+        if (w + 1 > width - 1)
+            break;
+        out += ch;
+        w++;
+    }
+    return out + "…";
+}
+// In-place repaint, always: home the cursor and rewrite every line with a
+// clear-to-end-of-line, then clear below the frame. Per-line \x1b[K plus
+// the trailing \x1b[J fully own the screen, so no full-screen \x1b[2J
+// erase is ever needed — including on the first paint, where the erase
+// showed as a one-time blank flash while the frame streamed in. The payload
+// is wrapped in DECSET 2026 (synchronized output): terminals that support
+// it hold the repaint until the frame is fully transmitted, so they never
+// paint a half-frame; terminals that don't simply ignore the mode.
+export function paintFrame(stdout, frame, cols) {
+    const width = Math.max(10, cols - 1);
+    const lines = frame.split("\n").map(l => truncateVisible(l, width) + "\x1b[K");
+    stdout.write("\x1b[?2026h\x1b[H" + lines.join("\n") + "\x1b[J\x1b[?2026l");
+}
+export function runTty(options) {
+    const { stdin, stdout, frame, onKey } = options;
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdout.write("\x1b[?25l");
+        let lastFrame;
+        const repaint = () => {
+            const f = frame();
+            if (f === lastFrame)
+                return; // identical frame: not one byte of churn
+            lastFrame = f;
+            paintFrame(stdout, f, stdout.columns || 120);
+        };
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.removeListener("data", feed);
+            if (wasRaw !== undefined)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            stdout.write("\x1b[?25h");
+            resolve(result);
+        };
+        const guarded = (key) => {
+            try {
+                onKey(key, finish);
+                if (!settled)
+                    repaint();
+            }
+            catch (e) {
+                process.stderr.write("key handling error: " + String(e));
+            }
+        };
+        const feed = createKeyFeed(guarded);
+        // The first paint gets the same armor as every repaint: a throwing
+        // frame builder degrades to a blank-but-alive session (keys still work,
+        // finish still restores the tty) instead of a hung promise and a leaked
+        // raw mode.
+        try {
+            repaint();
+        }
+        catch (e) {
+            process.stderr.write("initial paint failed: " + String(e) + "\n");
+        }
+        stdin.on("data", feed);
+    });
+}

package/docs/REPAIR-LOG.md

@@ -0,0 +1,45 @@
+# Repair log
+
+Every bug in the generated rules, in order. This log IS the generation-
+reliability data: the product's claim is that an agent can repair these from
+fixture failures, and every repair below was driven by a fixture or scan
+failure, never by hand-tuning against the target repo.
+
+## Inline-fixture-caught (rule fails to parse or fixture fails)
+
+| # | Rule | Bug | Fix | Category |
+|---|------|-----|-----|----------|
+| 1 | fetch-without-signal | YAML: unquoted `pattern: signal: $SIG` (colon in value) | quote the pattern | YAML quoting |
+| 2 | fetch-without-signal | `constraints` nested inside an `any` branch | `constraints` is a TOP-LEVEL rule-config field | API shape |
+| 3 | no-empty-catch | multi-node pattern `try $T catch ($E) { }` rejected | kind-based rule on `catch_clause` | pattern vs kind choice |
+| 4 | fetch-without-signal | `pattern: "signal: $SIG"` can't match an object pair key | match `property_identifier` kind + regex | tree-sitter kind names |
+| 5 | map-async | `async $$$ARGS` — rest metavariable after a keyword doesn't parse | explicit arrow shapes: `async $A => $B`, `async ($$$A) => $B` | metavariable rules |
+| 6 | no-empty-catch | `kind: statement` is not a real tree-sitter node → every catch flagged | regex on the block text `^\{\s*\}` | tree-sitter kind names |
+| 7 | fetch-without-signal | `has` defaulted to `stopBy: neighbor` — key is a grandchild of the options object | `stopBy: end` | **stopBy defaults** |
+| 8 | map-async | `inside` same neighbor problem (`map` → `arguments` → `Promise.all`) | `stopBy: end` | **stopBy defaults** |
+| 9 | fetch-without-signal | `await fetch(...)` variants double-reported (inner call already matches) | drop await variants | dedup / node identity |
+
+## Scan-level-fixture-caught (inline tests CANNOT catch these)
+
+| # | Rule | Bug | Fix | Category |
+|---|------|-----|-----|----------|
+| 10 | no-direct-ai-imports | rule-level `globs:` with `!` negation silently does NOTHING | rule-level `files:` / `ignores:` are the real fields; sgconfig has no `ignores` | silent schema acceptance |
+| 11 | harness design | inline test cases have no file path → glob scoping untestable inline | scan-level ground truth (sample-app) is REQUIRED as a second fixture layer | harness design finding |
+
+## Meta-findings for the skill file (the product)
+
+1. Nearly all bugs cluster into ~6 mechanical categories — none needed
+   creativity to fix. Encoding this list in the generation skill should
+   dramatically improve first-shot yield. **Generation reliability is a
+   teachable problem, not a research problem.**
+2. `stopBy: end` should be the DEFAULT in generated relational rules
+   (ast-grep's `neighbor` default is almost never what you want).
+3. ast-grep silently accepts unknown fields in both sgconfig.yml and rules
+   (bogus probe fields raised no error). A misspelled `ignores` produces a
+   rule that looks right and excludes nothing. **The harness must verify
+   behavior (scan-level fixtures), not just schema.**
+4. Two fixture layers are mandatory: inline tests (node-level truth) +
+   scan-level seeded ground truth (file-scope truth, glob/ignore behavior,
+   double-report detection).
+5. `sg test` discards generated snapshots on failed runs; baselines are
+   written with `sg test -U` and only trustworthy after a clean verify run.

package/docs/RESULTS.md

@@ -0,0 +1,70 @@
+# Kill-test prototype results (2026-08-28)
+
+Setup: 5 rules generated from intent-only one-liners ([intents.md](intents.md)),
+fixtures via `sg test`, evaluated on (a) a seeded sample app with known ground
+truth and (b) a real production repo (~234 TS files),
+with every finding hand-classified. ast-grep 0.45.2.
+
+## Sample app (seeded ground truth)
+
+- **Recall: 7/7 planted violations found (100%)**
+- **Precision: 8/8 (100%)** — the 8th finding was a *real* violation planted
+  by accident (an uncounted single-arg fetch) — correctly flagged
+- All 6 clean lookalikes (gateway imports, signal-ed fetches, 2-arg z.record,
+  logger catch, Promise.all-wrapped map, catch-with-return-null) correctly silent
+
+## Real repo (hand-verified findings)
+
+| Rule | Findings | TP | FP | Precision |
+|---|---|---|---|---|
+| fetch-without-abort-signal `[R]` | 5 | 5 | 0 | **100%** |
+| map-async-no-promise-all `[R]` | 3* | 0 | 3* | 0% |
+
+\* The table shows the two rules with real-repo findings. `zod-record-two-args`
+had no z.record usage in the target (fixtures only), and the two `[P]` import/
+catch rules fired zero times on this repo (no openai imports; no empty catches
+among 47 catch sites — spot-checked).
+
+**All 3 false positives are ONE rule hitting its DECLARED blind spot**: the
+map-async rule flags `const p = xs.map(async ...)` even when `p` is later
+wrapped in `Promise.all(p)` / `Promise.allSettled(p)` on a subsequent line —
+a cross-statement dataflow question that within-file relational operators
+cannot answer.
+
+## Verdict vs kill-test criteria
+
+- ✅ End-to-end loop works: intent → generated rule + fixtures → `sg test` →
+  scan → evidence-bearing findings. Whole thing in one working session.
+- ✅ Syntactic + simple-relational rules: precision 100% on real code.
+- ⚠️ 90% precision bar: **not met by the weakest rule** (map-async = 0/3 on
+  real repo). The failure is precisely the analysis-tier boundary, not a
+  generation failure — the rule does what its tier can do.
+- ✅ Generation reliability: 11 repairs across 5 rules, every one falling
+  into ~6 mechanical categories (see [REPAIR-LOG.md](REPAIR-LOG.md)) —
+  teachable to the generation skill.
+
+## Product implications
+
+1. **The premise is viable.** An agent can author fixture-tested ast-grep
+   rules that find real bugs in real code, and the fixture harness catches
+   generation bugs before they reach a user's CI.
+2. **The tier boundary is real and now measured.** Within-file relational
+   rules are safe; dataflow-adjacent rules ("is this result ever awaited?")
+   need either the semantic tier (D4 trigger evidence, as designed) or must
+   be shipped as audit-mode rules with their blind spot declared (D7).
+3. **Two fixture layers are required**, inline (`sg test`) and scan-level
+   seeded ground truth — inline tests cannot catch glob/scope/double-report
+   bugs (empirically demonstrated).
+4. **ast-grep's silent schema acceptance is a footgun** the harness must
+   defend against (misspelled field = rule that excludes nothing and never
+   says so).
+5. Cloudflare Code Mode: confirmed unnecessary for any of this (D2). The
+   entire loop ran locally with the user's own agent.
+
+## Next
+
+- Write the generation skill encoding the REPAIR-LOG's category lessons;
+  re-run this exact experiment measuring FIRST-shot yield (no repairs).
+  That number is the product's core metric.
+- Real kill test on the Effect codebase (dogfood), per docs/kill-test.md.
+- map-async rule is the concrete candidate to motivate the oxlint/oxc tier.