any-doctor 0.0.1

package/bin/discover.d.ts

@@ -0,0 +1,24 @@
+import { DoctorMeta } from "./contract.js";
+import { RunnerError } from "./runner.js";
+export type Scope = "repo" | "global";
+export interface DiscoveredDoctor {
+    slug: string;
+    scope: Scope;
+    path: string;
+    meta: DoctorMeta | null;
+    cause?: RunnerError;
+}
+export interface BrokenDoctor {
+    slug: string;
+    cause?: RunnerError;
+}
+export declare function unsafeSlugs(discovered: DiscoveredDoctor[]): string[];
+export declare function brokenDoctors(discovered: DiscoveredDoctor[]): BrokenDoctor[];
+export declare function globalDoctorsDir(): string;
+export declare function findRepoDoctorsDir(cwd: string): string | null;
+export declare function discoverDoctors(cwd: string, opts?: {
+    globalDir?: string;
+}): Promise<DiscoveredDoctor[]>;
+export declare function resolveDoctorPath(arg: string, cwd: string, opts?: {
+    globalDir?: string;
+}): string | null;

package/bin/discover.js

@@ -0,0 +1,87 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { DOCTOR_FILE_RE, FIXTURES_FILE_RE } from "./contract.js";
+import { metaDoctor } from "./runner.js";
+// The gate's partition over discovery — owned by the data so every surface
+// (run cohorts, verify, the picker) splits identically. Only null-meta
+// doctors belong to either bucket; a healthy doctor is neither skipped nor
+// named.
+export function unsafeSlugs(discovered) {
+    return discovered.filter(d => { var _a; return d.meta === null && ((_a = d.cause) === null || _a === void 0 ? void 0 : _a._tag) === "DoctorUnsafe"; }).map(d => d.slug);
+}
+export function brokenDoctors(discovered) {
+    return discovered
+        .filter(d => { var _a; return d.meta === null && ((_a = d.cause) === null || _a === void 0 ? void 0 : _a._tag) !== "DoctorUnsafe"; })
+        .map(d => ({ slug: d.slug, cause: d.cause }));
+}
+export function globalDoctorsDir() {
+    return path.join(os.homedir(), ".any-doctor", "doctors");
+}
+export function findRepoDoctorsDir(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(dir, "doctors");
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export async function discoverDoctors(cwd, opts) {
+    var _a;
+    const repoDir = findRepoDoctorsDir(cwd);
+    const scopes = [
+        ...(repoDir ? [{ scope: "repo", dir: repoDir }] : []),
+        { scope: "global", dir: (_a = opts === null || opts === void 0 ? void 0 : opts.globalDir) !== null && _a !== void 0 ? _a : globalDoctorsDir() },
+    ];
+    const bySlug = new Map();
+    for (const { scope, dir } of scopes) {
+        if (!fs.existsSync(dir))
+            continue;
+        const files = fs.readdirSync(dir)
+            .filter(f => (f.endsWith(".mjs") || f.endsWith(".js")) && !FIXTURES_FILE_RE.test(f))
+            .sort();
+        // Discovery fans out: every command pays this latency, metaDoctor never
+        // throws, and doctor counts grow once bundled doctors ship.
+        const reads = await Promise.all(files.map(async (f) => ({
+            slug: f.replace(DOCTOR_FILE_RE, ""),
+            abs: path.join(dir, f),
+            read: await metaDoctor({ programPath: path.join(dir, f) }),
+        })));
+        for (const { slug, abs, read } of reads) {
+            if (bySlug.has(slug))
+                continue;
+            bySlug.set(slug, { slug, scope, path: abs, meta: read.meta, cause: read.cause });
+        }
+    }
+    return [...bySlug.values()];
+}
+// Explicit paths (absolute, or containing separators) resolve directly.
+// Bare filenames are slugs: scopes win - repo-local first - so a stray
+// slug.mjs in the working directory cannot shadow an installed doctor.
+export function resolveDoctorPath(arg, cwd, opts) {
+    var _a;
+    const bare = path.basename(arg) === arg && !path.isAbsolute(arg);
+    if (!bare) {
+        const direct = path.resolve(cwd, arg);
+        if (fs.existsSync(direct))
+            return direct;
+    }
+    if (bare) {
+        const base = path.basename(arg);
+        const repoDir = findRepoDoctorsDir(cwd);
+        const scopes = [repoDir, (_a = opts === null || opts === void 0 ? void 0 : opts.globalDir) !== null && _a !== void 0 ? _a : globalDoctorsDir()].filter((d) => Boolean(d));
+        for (const dir of scopes) {
+            const candidate = path.join(dir, base);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        const direct = path.resolve(cwd, arg);
+        if (fs.existsSync(direct))
+            return direct;
+    }
+    return null;
+}

package/bin/doctor-loader.d.mts

@@ -0,0 +1 @@
+export declare function confineProcess(): void;

package/bin/doctor-loader.mjs

@@ -0,0 +1,161 @@
+import { pathToFileURL } from "url";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { register } from "node:module";
+import { buildCtx } from "./sdk.js";
+import * as contract from "./contract.js";
+// The doctor loader: the child process every doctor program runs inside.
+// It owns the Doctor-run choreography — decode the Mode, confine the
+// process, import the doctor, frame the result — and nothing else. The
+// runner owns the protocol on the parent side; this file is the other end.
+// The confinement prologue: a doctor's process has no network (the globals
+// are deleted before any doctor code can run) and may not import anything
+// (a resolve hook refuses every resolution that is not the loader's own).
+// Ordering is load-bearing: this must run AFTER this module's own imports
+// resolve (sdk, contract — which is why they are static imports above) and
+// BEFORE the doctor import below. Exported so the choreography has a direct
+// test seam instead of being provable only end-to-end.
+export function confineProcess() {
+    const g = globalThis;
+    delete g.fetch;
+    try {
+        delete g.WebSocket;
+    }
+    catch { /* already absent */ }
+    try {
+        register(new URL("./import-guard.mjs", import.meta.url));
+    }
+    catch {
+        // No loader hooks on this runtime — the other confinement layers still apply.
+    }
+}
+const USAGE = "usage: doctor-loader.mjs <program.(m)js> <root> | <program.(m)js> --verify <fixtures.(m)js> | <program.(m)js> --meta";
+const SEVERITIES = new Set(["error", "warning", "info"]);
+function validateMeta(mod) {
+    const m = mod.meta;
+    const problems = [];
+    if (!m || typeof m !== "object")
+        problems.push("missing meta export");
+    if (m && typeof m.id !== "string")
+        problems.push("meta.id must be a string");
+    if (m && typeof m.description !== "string")
+        problems.push("meta.description must be a string");
+    if (m && !SEVERITIES.has(String(m.severity)))
+        problems.push(`meta.severity must be one of error|warning|info — got ${JSON.stringify(m.severity)}`);
+    if (problems.length) {
+        console.error("invalid doctor meta: " + problems.join("; "));
+        process.exit(3);
+    }
+}
+function runOnce(root, mod) {
+    const started = Date.now();
+    const { ctx, getFindings } = buildCtx(root);
+    const fileCount = ctx.files.list().length;
+    const result = mod.doctor(ctx);
+    if (!result || typeof result.then !== "function") {
+        throw new Error("doctor() must be async — declare it `export async function doctor(ctx)`");
+    }
+    return result.then(() => ({
+        protocolVersion: contract.PROTOCOL_VERSION,
+        kind: "run",
+        root,
+        fileCount,
+        durationMs: Date.now() - started,
+        meta: mod.meta,
+        findings: getFindings(),
+    }));
+}
+function materializeSeed(tmp, rel, content) {
+    const abs = path.resolve(tmp, rel);
+    if (abs !== tmp && !abs.startsWith(tmp + path.sep)) {
+        throw new Error(`fixture seed path escapes the sandbox: ${rel}`);
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+}
+async function main() {
+    confineProcess();
+    // The mode arrives as argv and is decoded exactly once, here, into a value.
+    const decoded = contract.decodeLoaderArgs(process.argv.slice(2));
+    if (decoded === null) {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    const prog = decoded.program;
+    const mode = decoded.mode;
+    const mod = (await import(pathToFileURL(prog).href));
+    if (typeof mod.doctor !== "function") {
+        console.error("doctor program must export `doctor(ctx)` — got: " + Object.keys(mod).join(", "));
+        process.exit(3);
+    }
+    validateMeta(mod);
+    const originalLog = console.log;
+    console.log = (...args) => { process.stderr.write(args.map(a => String(a)).join(" ") + "\n"); };
+    try {
+        if (mode.kind === "meta") {
+            process.stdout.write("\n" + contract.RESULT_SENTINEL + JSON.stringify({
+                protocolVersion: contract.PROTOCOL_VERSION,
+                kind: "meta",
+                meta: mod.meta,
+            }) + "\n");
+        }
+        else if (mode.kind === "run") {
+            const result = await runOnce(mode.root, mod);
+            process.stdout.write("\n" + contract.RESULT_SENTINEL + JSON.stringify(result) + "\n");
+        }
+        else {
+            const fixturesMod = (await import(pathToFileURL(mode.fixtures).href));
+            const fixtures = fixturesMod.fixtures;
+            if (!Array.isArray(fixtures)) {
+                console.error("fixture module must export `fixtures` (array) — got: " + Object.keys(fixturesMod).join(", "));
+                process.exit(3);
+            }
+            const results = [];
+            for (const fixture of fixtures) {
+                const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "any-doctor-verify-"));
+                try {
+                    for (const [rel, content] of Object.entries(fixture.seed)) {
+                        materializeSeed(tmp, rel, content);
+                    }
+                    const result = await runOnce(tmp, mod);
+                    const diff = contract.compareFindings(fixture.expected, result.findings);
+                    results.push({ name: fixture.name, ok: diff.missing.length === 0 && diff.unexpected.length === 0, ...diff });
+                }
+                catch (e) {
+                    results.push({ name: fixture.name, ok: false, missing: [], unexpected: [], error: e instanceof Error ? e.message : String(e) });
+                }
+                finally {
+                    fs.rmSync(tmp, { recursive: true, force: true });
+                }
+            }
+            process.stdout.write("\n" + contract.RESULT_SENTINEL + JSON.stringify({
+                protocolVersion: contract.PROTOCOL_VERSION,
+                kind: "verify",
+                meta: mod.meta,
+                results,
+            }) + "\n");
+        }
+    }
+    finally {
+        console.log = originalLog;
+    }
+}
+// Direct-invocation guard: importing this module (tests, future tooling)
+// never executes a Doctor run — the script body runs only when spawned.
+const invokedDirectly = (() => {
+    try {
+        return import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+})();
+try {
+    if (invokedDirectly)
+        await main();
+}
+catch (e) {
+    console.error(e instanceof Error && e.stack ? e.stack : String(e));
+    process.exit(1);
+}

package/bin/engine.d.ts

@@ -0,0 +1,18 @@
+export interface RawSgMatch {
+    file?: string;
+    text?: string;
+    range?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+    };
+}
+export type EngineResult = {
+    ok: true;
+    matches: RawSgMatch[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function runEngineSearch(pattern: string, language: string, root: string): EngineResult;

package/bin/engine.js

@@ -0,0 +1,22 @@
+import { spawnSync } from "child_process";
+export function runEngineSearch(pattern, language, root) {
+    const r = spawnSync("sg", ["run", "-p", pattern, "-l", language, "--json", root], {
+        encoding: "utf8",
+        timeout: 120000,
+    });
+    if (r.error && r.error.code === "ENOENT") {
+        return { ok: false, error: "ctx.search requires ast-grep (sg) on PATH — install: brew install ast-grep" };
+    }
+    if (r.status !== 0 && !r.stdout.trim()) {
+        return { ok: false, error: "ctx.search failed: " + (r.stderr || "sg exited " + r.status) };
+    }
+    try {
+        return { ok: true, matches: JSON.parse(r.stdout) };
+    }
+    catch {
+        return {
+            ok: false,
+            error: `ctx.search produced unparseable output from sg — refusing to report a false green. First bytes: ${JSON.stringify(r.stdout.slice(0, 120))}`,
+        };
+    }
+}

package/bin/fuzzy.d.ts

@@ -0,0 +1,2 @@
+export declare function fuzzyScore(query: string, text: string): number;
+export declare function fuzzyFilter<T>(items: T[], textOf: (item: T) => string, query: string): T[];

package/bin/fuzzy.js

@@ -0,0 +1,31 @@
+export function fuzzyScore(query, text) {
+    var _a;
+    const q = query.toLowerCase();
+    const t = text.toLowerCase();
+    if (!q)
+        return 1;
+    let qi = 0;
+    let score = 0;
+    let streak = 0;
+    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+        if (t[ti] === q[qi]) {
+            streak++;
+            const boundary = ti === 0 || /[\W_]/.test((_a = t[ti - 1]) !== null && _a !== void 0 ? _a : "");
+            score += 2 + streak + (boundary ? 4 : 0);
+            qi++;
+        }
+        else {
+            streak = 0;
+        }
+    }
+    return qi === q.length ? score : 0;
+}
+export function fuzzyFilter(items, textOf, query) {
+    if (!query.trim())
+        return items;
+    return items
+        .map(item => ({ item, score: fuzzyScore(query.trim(), textOf(item)) }))
+        .filter(e => e.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map(e => e.item);
+}

package/bin/import-guard.mjs

@@ -0,0 +1,31 @@
+// The import guard: a doctor is a single self-contained file. Every module
+// it tries to reach — node builtins, helper files beside it, npm packages
+// in the target's node_modules — routes through this resolve hook and is
+// refused. Static, dynamic, and computed imports all land here, because
+// this is the mechanism Node itself uses to resolve them.
+//
+// This file is deliberately hand-maintained in bin/ (the one exception to
+// the tsc build): a resolve hook must be standalone — zero imports — or it
+// could not load to guard anything. Everything else in the trusted base
+// compiles from src/.
+//
+// The allow rule is role-based, not location-based: only the loader module
+// itself may resolve things here (it imports exactly two modules after
+// registration — the doctor program and its fixtures), plus the guard's
+// own initial load. Everything else — a doctor's imports, anonymous imports
+// from Function-constructor scripts — is refused with a contract error the
+// author sees at verify time.
+
+const LOADER_URL = new URL("./doctor-loader.mjs", import.meta.url).href;
+
+export function resolve(specifier, context, nextResolve) {
+  const message = `any-doctor: a doctor is a single self-contained file — import of "${specifier}" is refused (everything reaches you through ctx)`;
+  if (specifier === import.meta.url) return nextResolve(specifier, context);
+  if (specifier.startsWith("node:")) {
+    throw new Error(message);
+  }
+  if ((context.parentURL ?? "") === LOADER_URL) {
+    return nextResolve(specifier, context);
+  }
+  throw new Error(message);
+}

package/bin/keys.d.ts

@@ -0,0 +1,2 @@
+export type KeyHandler = (key: string) => void;
+export declare function createKeyFeed(onKey: KeyHandler): (chunk: string | Buffer) => void;

package/bin/keys.js

@@ -0,0 +1,72 @@
+const FLUSH_MS = 30;
+export function createKeyFeed(onKey) {
+    let buf = "";
+    let holdTimer = null;
+    const clearHold = () => {
+        if (holdTimer) {
+            clearTimeout(holdTimer);
+            holdTimer = null;
+        }
+    };
+    const flushHeldEsc = () => {
+        clearHold();
+        const held = buf;
+        buf = "";
+        onKey(held === "\x1b" ? "esc" : held);
+    };
+    return (chunk) => {
+        clearHold();
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let i = 0;
+        for (;;) {
+            if (i >= buf.length) {
+                buf = "";
+                return;
+            }
+            const ch = buf[i];
+            if (ch !== "\x1b") {
+                onKey(ch);
+                i++;
+                continue;
+            }
+            if (i === buf.length - 1) {
+                buf = buf.slice(i);
+                holdTimer = setTimeout(flushHeldEsc, FLUSH_MS);
+                return;
+            }
+            if (buf[i + 1] === "[" || buf[i + 1] === "O") {
+                let j = i + 2;
+                while (j < buf.length && !/[A-Za-z~]/.test(buf[j]))
+                    j++;
+                if (j >= buf.length) {
+                    buf = buf.slice(i);
+                    holdTimer = setTimeout(flushHeldEsc, FLUSH_MS);
+                    return;
+                }
+                const seq = buf.slice(i, j + 1);
+                if (seq === "\x1b[A" || seq === "\x1bOA")
+                    onKey("up");
+                else if (seq === "\x1b[B" || seq === "\x1bOB")
+                    onKey("down");
+                else if (seq === "\x1b[C" || seq === "\x1bOC")
+                    onKey("right");
+                else if (seq === "\x1b[D" || seq === "\x1bOD")
+                    onKey("left");
+                else
+                    onKey("ignore");
+                i = j + 1;
+                continue;
+            }
+            // Alt-chords (\x1b followed by a printable) arrive as one chunk:
+            // ignore the pair rather than decoding it as esc + keystroke, which
+            // would cancel the session on alt-<letter>.
+            if (i + 1 < buf.length && buf[i + 1] >= " " && buf[i + 1] !== "\x7f") {
+                onKey("ignore");
+                i += 2;
+                continue;
+            }
+            onKey("esc");
+            i++;
+        }
+    };
+}

package/bin/palette.d.ts

@@ -0,0 +1,7 @@
+import { Severity } from "./contract.js";
+export declare const RED = "\u001B[31m", GREEN = "\u001B[32m", YELLOW = "\u001B[33m", CYAN = "\u001B[36m", ORANGE = "\u001B[38;5;208m", DIM = "\u001B[2m", BOLD = "\u001B[1m", RESET = "\u001B[0m";
+export declare const GLYPH: Record<Severity, string>;
+export declare const SEVERITY_COLOR: Record<Severity, string>;
+export type Colorizer = (s: string, wrap?: string) => string;
+export declare function colorizer(useColor: boolean): Colorizer;
+export declare function gradeColor(score: number): string;

package/bin/palette.js

@@ -0,0 +1,14 @@
+import { gradeFor } from "./score.js";
+// The severity palette: one home for how findings are glyphed and colored
+// across the picker, report, and dashboard. Grade colors derive from
+// score.ts's bands — nothing shadows them here.
+export const RED = "\x1b[31m", GREEN = "\x1b[32m", YELLOW = "\x1b[33m", CYAN = "\x1b[36m", ORANGE = "\x1b[38;5;208m", DIM = "\x1b[2m", BOLD = "\x1b[1m", RESET = "\x1b[0m";
+export const GLYPH = { error: "✖", warning: "⚠", info: "ℹ" };
+export const SEVERITY_COLOR = { error: RED, warning: ORANGE, info: YELLOW };
+export function colorizer(useColor) {
+    return (s, wrap) => (useColor && wrap ? wrap + s + RESET : s);
+}
+export function gradeColor(score) {
+    const grade = gradeFor(score);
+    return grade === "Excellent" || grade === "Good" ? GREEN : grade === "Fair" ? YELLOW : RED;
+}

package/bin/picker.d.ts

@@ -0,0 +1,12 @@
+import { Severity } from "./contract.js";
+import { TtyEnv } from "./tty.js";
+export interface PickerItem {
+    id: string;
+    label: string;
+    sub?: string;
+    severity?: Severity;
+}
+export declare function pickerFrame(title: string, items: PickerItem[], selected: number, query: string, useColor: boolean, notice?: string): string;
+export declare function filterPickerItems(items: PickerItem[], query: string): PickerItem[];
+export declare function isPrintable(s: string): boolean;
+export declare function pickItemOn(env: TtyEnv, items: PickerItem[], useColor: boolean, title?: string, notice?: string): Promise<PickerItem | null>;

package/bin/picker.js

@@ -0,0 +1,82 @@
+import { fuzzyFilter } from "./fuzzy.js";
+import { BOLD, colorizer, DIM, GLYPH, GREEN, SEVERITY_COLOR } from "./palette.js";
+import { canRunTui, runTty } from "./tty.js";
+export function pickerFrame(title, items, selected, query, useColor, notice) {
+    const c = colorizer(useColor);
+    const lines = [];
+    lines.push(c(title, BOLD) + c("  (type to filter · ↑↓ move · enter select · esc cancel)", DIM));
+    lines.push("");
+    lines.push(c("❯ " + query, BOLD) + c("▏", DIM));
+    lines.push("");
+    if (items.length === 0) {
+        lines.push(c("  no matching doctors", DIM));
+    }
+    else {
+        const cap = Math.min(items.length, 12);
+        for (let i = 0; i < cap; i++) {
+            const it = items[i];
+            const glyph = it.severity ? c(GLYPH[it.severity] + " ", SEVERITY_COLOR[it.severity]) : "";
+            const row = `${glyph}${it.label}${it.sub ? c("  " + it.sub, DIM) : ""}`;
+            lines.push(i === selected ? c("❯ " + row, BOLD) : "  " + row);
+        }
+        if (items.length > cap)
+            lines.push(c(`  … +${items.length - cap} more`, DIM));
+    }
+    if (notice) {
+        lines.push("");
+        lines.push(c("✔ " + notice, GREEN));
+    }
+    return lines.join("\n");
+}
+export function filterPickerItems(items, query) {
+    return fuzzyFilter(items, it => { var _a; return `${it.id} ${it.label} ${(_a = it.sub) !== null && _a !== void 0 ? _a : ""}`; }, query);
+}
+export function isPrintable(s) {
+    return s.length === 1 && s >= " " && s !== "\x7f";
+}
+export async function pickItemOn(env, items, useColor, title = "Select an option", notice) {
+    if (items.length === 0 || !canRunTui(env))
+        return null;
+    let query = "";
+    let selected = 0;
+    const filtered = () => filterPickerItems(items, query);
+    const frame = () => {
+        const list = filtered();
+        if (selected >= list.length)
+            selected = Math.max(0, list.length - 1);
+        return pickerFrame(title, list, selected, query, useColor, notice);
+    };
+    return runTty({
+        stdin: env.stdin,
+        stdout: env.stdout,
+        frame,
+        onKey: (key, finish) => {
+            if (key === "\x03" || key === "esc")
+                return finish(null);
+            if (key === "\x7f" || key === "\b") {
+                query = query.slice(0, -1);
+                selected = 0;
+                return;
+            }
+            if (key === "up" || key === "k") {
+                selected = Math.max(0, selected - 1);
+                return;
+            }
+            if (key === "down" || key === "j") {
+                selected = Math.min(filtered().length - 1, selected + 1);
+                return;
+            }
+            if (key === "\r" || key === "\n") {
+                const list = filtered();
+                if (list.length > 0)
+                    finish(list[Math.min(selected, list.length - 1)]);
+                return;
+            }
+            if (isPrintable(key)) {
+                query += key;
+                selected = 0;
+                return;
+            }
+        },
+    });
+}

package/bin/report.d.ts

@@ -0,0 +1,18 @@
+import { ReportGroup, VerifyRunResult } from "./contract.js";
+export interface RunOutcome {
+    groups: ReportGroup[];
+    crashed: string[];
+    skippedUnsafe: string[];
+    doctorPaths: ReadonlyMap<string, string>;
+    fileCount: number;
+    durationMs: number;
+    targetDir: string;
+}
+export declare function unsafeSkipLine(names: string[]): string;
+export declare function unsafeRefusalLine(name: string, capabilities: readonly string[]): string;
+export declare function dedupeGroups(groups: ReportGroup[]): {
+    groups: ReportGroup[];
+    hidden: number;
+};
+export declare function renderReport(input: RunOutcome, useColor: boolean): string;
+export declare function renderVerifyResult(result: VerifyRunResult, useColor: boolean): string;