any-doctor 0.0.1

package/bin/report.js

@@ -0,0 +1,159 @@
+import { resolveFinding } from "./contract.js";
+import { BOLD, colorizer, DIM, GLYPH, gradeColor, GREEN, RED, SEVERITY_COLOR, YELLOW } from "./palette.js";
+import { categoryRollup, computeScore, findingSeverity } from "./score.js";
+// The one place the skip-note copy lives; report, dashboard, and the CLI
+// all render this sentence so the story is identical everywhere. The count
+// is always the true total; only the name list caps — three names, then
+// "… and N more" — so a hundred malicious doctors still cost one line.
+const SKIP_NAMES_SHOWN = 3;
+export function unsafeSkipLine(names) {
+    const shown = names.slice(0, SKIP_NAMES_SHOWN).join(", ");
+    const rest = names.length - SKIP_NAMES_SHOWN;
+    const list = rest > 0 ? `${shown} \u2026 and ${rest} more` : shown;
+    return `${names.length} doctor${names.length === 1 ? "" : "s"} could be malicious — skipped: ${list}`;
+}
+// The refusal for a doctor you explicitly asked to run: the file, its
+// capabilities, one line. The runner's DoctorUnsafe renderer and every
+// caller share this so the refusal reads identically everywhere; detail
+// lines ride beneath it when there are any.
+export function unsafeRefusalLine(name, capabilities) {
+    return `${name} could be malicious (${capabilities.join(", ")}) — not running it.`;
+}
+const SEVERITY_ORDER = ["error", "warning", "info"];
+function groupSeverity(g) {
+    var _a;
+    const explicit = g.findings.find(f => f.severity);
+    return (_a = (explicit ? findingSeverity(g, explicit) : undefined)) !== null && _a !== void 0 ? _a : g.meta.severity;
+}
+function expandChecks(g) {
+    var _a;
+    const buckets = new Map();
+    for (const f of g.findings) {
+        const j = resolveFinding(g.meta, f);
+        if (!buckets.has(j.checkKey)) {
+            buckets.set(j.checkKey, {
+                ruleId: (_a = f.rule) !== null && _a !== void 0 ? _a : null,
+                heading: j.description,
+                severity: j.declaredSeverity,
+                findings: [],
+            });
+        }
+        buckets.get(j.checkKey).findings.push(f);
+    }
+    return [...buckets.values()];
+}
+export function dedupeGroups(groups) {
+    const seen = new Set();
+    const key = (f) => `${f.file}:${f.line}`;
+    const ordered = [...groups].sort((a, b) => SEVERITY_ORDER.indexOf(groupSeverity(a)) - SEVERITY_ORDER.indexOf(groupSeverity(b)));
+    const out = [];
+    let hidden = 0;
+    for (const g of ordered) {
+        if (g.findings.length === 0) {
+            out.push(g);
+            continue;
+        }
+        const kept = [];
+        for (const f of g.findings) {
+            const k = key(f);
+            if (seen.has(k)) {
+                hidden++;
+                continue;
+            }
+            seen.add(k);
+            kept.push(f);
+        }
+        if (kept.length > 0)
+            out.push({ ...g, findings: kept });
+    }
+    return { groups: out, hidden };
+}
+export function renderReport(input, useColor) {
+    const c = colorizer(useColor);
+    const lines = [];
+    const { groups, hidden } = dedupeGroups(input.groups);
+    const total = groups.reduce((n, g) => n + g.findings.length, 0);
+    const { score, grade } = computeScore(groups);
+    lines.push(`✔ Scanned ${input.fileCount} files in ${input.durationMs}ms`);
+    lines.push("");
+    const doctorWord = groups.length === 1 ? "doctor" : "doctors";
+    lines.push(c(`Any Doctor — ${groups.length} ${doctorWord}`, BOLD));
+    lines.push(c(`Score: ${score} / 100 — ${grade}`, BOLD + gradeColor(score)));
+    if (input.skippedUnsafe !== undefined && input.skippedUnsafe.length > 0) {
+        lines.push(c(`\u26a0 ${unsafeSkipLine(input.skippedUnsafe)}`, YELLOW));
+    }
+    if (total === 0) {
+        lines.push(c("No findings", BOLD + GREEN));
+        if (groups.length > 1) {
+            lines.push("");
+            for (const g of groups) {
+                lines.push(`${c("✔", GREEN)} ${c(g.meta.id, DIM)} — clean`);
+            }
+        }
+        return lines.join("\n");
+    }
+    const bySeverity = { error: 0, warning: 0, info: 0 };
+    for (const g of groups) {
+        for (const f of g.findings)
+            bySeverity[findingSeverity(g, f)]++;
+    }
+    const rollup = SEVERITY_ORDER
+        .filter(s => bySeverity[s] > 0)
+        .map(s => c(`${bySeverity[s]} ${s}`, SEVERITY_COLOR[s]))
+        .join(", ");
+    lines.push("");
+    lines.push(`${c(`${total} finding${total === 1 ? "" : "s"}`, BOLD)}  ${c(`(${rollup})`, DIM)}`);
+    for (const { category, counts } of categoryRollup(groups)) {
+        const catParts = SEVERITY_ORDER.filter(s => counts[s] > 0).map(s => c(`${counts[s]} ${s}`, SEVERITY_COLOR[s]));
+        if (catParts.length > 0) {
+            const cap = category.charAt(0).toUpperCase() + category.slice(1);
+            lines.push(`${c(cap + ":", BOLD)} ${catParts.join(", ")}`);
+        }
+    }
+    lines.push("");
+    // dedupeGroups already orders by severity; sorting again would duplicate it.
+    for (const g of groups) {
+        for (const bucket of expandChecks(g)) {
+            const n = bucket.findings.length;
+            lines.push(`${c(GLYPH[bucket.severity], SEVERITY_COLOR[bucket.severity])} ${c(bucket.heading, n > 1 ? BOLD : "")}${n > 1 ? c(` ×${n}`, SEVERITY_COLOR[bucket.severity]) : ""}`);
+            lines.push(`  ${c(bucket.ruleId ? `${g.meta.id}/${bucket.ruleId}` : g.meta.id, DIM)}`);
+            for (const f of bucket.findings.slice(0, 20)) {
+                lines.push(`  ${f.file}:${f.line}`);
+                if (f.message)
+                    lines.push(`    ${c(f.message, DIM)}`);
+            }
+            if (n > 20)
+                lines.push(`  ${c(`… and ${n - 20} more`, DIM)}`);
+            lines.push("");
+        }
+        if (g.findings.length > 0 && g.meta.blindSpots && g.meta.blindSpots.length > 0) {
+            lines.push(`  ${c("blind spots: " + g.meta.blindSpots.join("; "), DIM)}`);
+            lines.push("");
+        }
+    }
+    if (hidden > 0) {
+        lines.push(c(`${hidden} duplicate finding${hidden === 1 ? "" : "s"} hidden (same location, different doctor)`, DIM));
+    }
+    return lines.join("\n").replace(/\n+$/, "");
+}
+// Verify-gate rendering: pure state -> string, colored on request. The
+// command layer prints it and counts failures from the data.
+export function renderVerifyResult(result, useColor) {
+    const c = colorizer(useColor);
+    const lines = [];
+    for (const fixture of result.results) {
+        if (fixture.ok) {
+            lines.push(c("  ✔ " + fixture.name, GREEN));
+        }
+        else {
+            lines.push(c("  ✖ " + fixture.name, RED));
+            for (const m of fixture.missing)
+                lines.push("    " + c("missing expected finding", RED) + " " + m.file + ":" + m.line);
+            for (const u of fixture.unexpected)
+                lines.push("    " + c("unexpected finding", RED) + " " + u.file + ":" + u.line);
+            if (fixture.error)
+                lines.push("    " + c("crashed: ", RED) + fixture.error);
+        }
+    }
+    return lines.join("\n");
+}

package/bin/runner.d.ts

@@ -0,0 +1,58 @@
+import { Cause, Schema } from "effect";
+import { DoctorMeta, RunResult, VerifyRunResult } from "./contract.js";
+declare const ProgramMissing_base: Schema.Class<ProgramMissing, Schema.TaggedStruct<"ProgramMissing", {
+    readonly programPath: Schema.String;
+}>, Cause.YieldableError>;
+export declare class ProgramMissing extends ProgramMissing_base {
+}
+declare const FixturesMissing_base: Schema.Class<FixturesMissing, Schema.TaggedStruct<"FixturesMissing", {
+    readonly programPath: Schema.String;
+    readonly fixturesPath: Schema.String;
+}>, Cause.YieldableError>;
+export declare class FixturesMissing extends FixturesMissing_base {
+}
+declare const DoctorCrashed_base: Schema.Class<DoctorCrashed, Schema.TaggedStruct<"DoctorCrashed", {
+    readonly programPath: Schema.String;
+    readonly detail: Schema.String;
+}>, Cause.YieldableError>;
+export declare class DoctorCrashed extends DoctorCrashed_base {
+}
+declare const NoFramedResult_base: Schema.Class<NoFramedResult, Schema.TaggedStruct<"NoFramedResult", {
+    readonly programPath: Schema.String;
+    readonly stdout: Schema.String;
+}>, Cause.YieldableError>;
+export declare class NoFramedResult extends NoFramedResult_base {
+}
+declare const DoctorUnsafe_base: Schema.Class<DoctorUnsafe, Schema.TaggedStruct<"DoctorUnsafe", {
+    readonly programPath: Schema.String;
+    readonly capabilities: Schema.$Array<Schema.String>;
+    readonly findings: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+export declare class DoctorUnsafe extends DoctorUnsafe_base {
+}
+export type RunnerError = ProgramMissing | FixturesMissing | DoctorCrashed | NoFramedResult | DoctorUnsafe;
+export declare function isRunnerError(e: unknown): e is RunnerError;
+export declare function describeRunnerError(e: RunnerError): string;
+export declare function causeSummaryLine(e: RunnerError | undefined): string;
+export interface RunOptions {
+    programPath: string;
+    targetDir: string;
+}
+export interface VerifyOptions {
+    programPath: string;
+    fixturesPath?: string;
+}
+export interface MetaRead {
+    meta: DoctorMeta | null;
+    cause?: RunnerError;
+}
+export declare function supportsPermissionModel(): Promise<boolean>;
+export declare function permissionArgs(allowTmpWrites: boolean): Promise<string[]>;
+export declare function deniedByPermissionModel(stderr: string): boolean;
+export declare function denialCapability(stderr: string): string;
+export declare function runDoctor(options: RunOptions): Promise<RunResult>;
+export declare function verifyDoctor(options: VerifyOptions): Promise<VerifyRunResult>;
+export declare function metaDoctor({ programPath }: {
+    programPath: string;
+}): Promise<MetaRead>;
+export {};

package/bin/runner.js

@@ -0,0 +1,271 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { Cause, Effect, Exit, Schema } from "effect";
+import { fixturesPathFor, modeArgs, RESULT_SENTINEL, SEARCH_RESULT } from "./contract.js";
+import { scanDoctorFile } from "./capabilities.js";
+import { unsafeRefusalLine } from "./report.js";
+import { handleSearchLine } from "./search-host.js";
+// The Runner: the single owner of the doctor-loader protocol. Everything
+// that executes a doctor program — run, verify, meta, count — crosses this
+// interface: the argv shapes (built from a Mode value), the sentinel
+// framing, the timeout policy, and the typed failures. The parent side of
+// Confinement lives here too (permission flags, the runtime-denial
+// mapping); the Engine and the search host sit behind their own modules.
+export class ProgramMissing extends Schema.TaggedError()("ProgramMissing", {
+    programPath: Schema.String,
+}) {
+}
+export class FixturesMissing extends Schema.TaggedError()("FixturesMissing", {
+    programPath: Schema.String,
+    fixturesPath: Schema.String,
+}) {
+}
+export class DoctorCrashed extends Schema.TaggedError()("DoctorCrashed", {
+    programPath: Schema.String,
+    detail: Schema.String,
+}) {
+}
+export class NoFramedResult extends Schema.TaggedError()("NoFramedResult", {
+    programPath: Schema.String,
+    stdout: Schema.String,
+}) {
+}
+// The doctor references capabilities no doctor legitimately has (network,
+// file writes, subprocesses, imports). This is a hard refuse: every execution
+// path (run, verify, meta, count) passes through it, and there is no override.
+// The typed error carries the capability set, so callers render the refusal
+// from it — nobody re-scans to re-derive what this already knows.
+export class DoctorUnsafe extends Schema.TaggedError()("DoctorUnsafe", {
+    programPath: Schema.String,
+    capabilities: Schema.Array(Schema.String),
+    findings: Schema.Array(Schema.String),
+}) {
+}
+export function isRunnerError(e) {
+    return e instanceof ProgramMissing || e instanceof FixturesMissing
+        || e instanceof DoctorCrashed || e instanceof NoFramedResult || e instanceof DoctorUnsafe;
+}
+export function describeRunnerError(e) {
+    switch (e._tag) {
+        case "ProgramMissing": return "no such doctor program: " + e.programPath;
+        case "FixturesMissing": return "no fixtures found for this doctor — expected " + e.fixturesPath;
+        case "DoctorCrashed": return "doctor crashed:\n" + e.detail;
+        case "NoFramedResult": return "doctor produced no framed result — stdout was:\n" + e.stdout;
+        case "DoctorUnsafe": return "\ud83d\uded1 " + unsafeRefusalLine(path.basename(e.programPath), e.capabilities)
+            + "\n  " + e.findings.join("\n  ");
+    }
+}
+// One line for listings — the broken-doctor warnings and failure parts —
+// where the full detail belongs to describeRunnerError's renderers. Lives
+// beside the error taxonomy so rendering rules for one type stay in one
+// place.
+export function causeSummaryLine(e) {
+    if (e === undefined)
+        return "invalid meta";
+    if (e._tag === "DoctorCrashed")
+        return e.detail.split("\n")[0];
+    return describeRunnerError(e).split("\n")[0];
+}
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const META_TIMEOUT_MS = 30 * 1000;
+// Feature probe, run once per process: does this runtime know --permission?
+// Runtimes without it degrade to the static gate alone. Exported so tests
+// gate on the same answer the runner uses — no copied probes.
+export function supportsPermissionModel() {
+    return (probe !== null && probe !== void 0 ? probe : (probe = new Promise((resolve) => {
+        const child = spawn(process.execPath, ["--permission", "-e", "0"], { stdio: "ignore" });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    })));
+}
+let probe;
+// Node's permission model, applied to every doctor execution: filesystem
+// writes, subprocesses, and native addons are denied by the runtime itself
+// — an eval'd, obfuscated, or helper-module payload is stopped by the
+// process, whatever the static scan missed. Reads stay open (reading the
+// repo is a doctor's job); verify mode also writes to the temp dir, where
+// the loader seeds and cleans up fixture sandboxes. --allow-worker exists
+// for the import guard's hook thread only — denials propagate into worker
+// threads (verified: fs write and subprocess are denied inside them).
+// Network is not part of the permission model on current Node; the loader
+// strips the network globals instead. This never throws: an unprobeable
+// runtime just gets no flags.
+const PERMISSION_BASE = ["--permission", "--allow-fs-read=*", "--allow-worker", "--disable-warning=SecurityWarning"];
+// Exported so the loader tests can spawn children in exactly the
+// configuration production creates — no fictional flag sets.
+export async function permissionArgs(allowTmpWrites) {
+    try {
+        if (!(await supportsPermissionModel()))
+            return [];
+        return allowTmpWrites ? [...PERMISSION_BASE, `--allow-fs-write=${os.tmpdir()}`] : [...PERMISSION_BASE];
+    }
+    catch {
+        return [];
+    }
+}
+// Exported with its table: Node's denial phrasings vary across versions,
+// and what the refusal line names for an evading doctor depends on this
+// mapping — it deserves direct tests, not coverage by e2e accident.
+export function deniedByPermissionModel(stderr) {
+    return /ErrAccessDenied|not allowed by the permission model|access to this api has been restricted/i.test(stderr);
+}
+export function denialCapability(stderr) {
+    if (/--allow-fs-write/i.test(stderr))
+        return "file write";
+    if (/--allow-child-process/i.test(stderr))
+        return "subprocess";
+    if (/--allow-worker/i.test(stderr))
+        return "worker";
+    if (/--allow-addon/i.test(stderr))
+        return "native addon";
+    return "forbidden capability";
+}
+function spawnLoader(programPath, mode, timeoutMs, nodeFlags) {
+    return new Promise((resolve) => {
+        var _a, _b, _c;
+        const loader = fileURLToPath(new URL("doctor-loader.mjs", import.meta.url));
+        const child = spawn(process.execPath, [...nodeFlags, loader, ...modeArgs(mode, programPath)], {
+            stdio: ["pipe", "pipe", "pipe", "pipe"],
+            timeout: timeoutMs,
+        });
+        let stdout = "";
+        let stderr = "";
+        (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on("data", (c) => { stdout += c.toString("utf8"); });
+        (_b = child.stderr) === null || _b === void 0 ? void 0 : _b.on("data", (c) => { stderr += c.toString("utf8"); });
+        // fd 3 carries ctx.search requests; the search host answers on stdin.
+        let pending = "";
+        (_c = child.stdio[3]) === null || _c === void 0 ? void 0 : _c.on("data", (c) => {
+            var _a;
+            pending += c.toString("utf8");
+            let nl;
+            while ((nl = pending.indexOf("\n")) !== -1) {
+                const line = pending.slice(0, nl);
+                pending = pending.slice(nl + 1);
+                const response = handleSearchLine(line, mode);
+                if (response !== null)
+                    (_a = child.stdin) === null || _a === void 0 ? void 0 : _a.write(SEARCH_RESULT + response + "\n");
+            }
+        });
+        child.on("error", () => resolve({ status: null, stdout, stderr: stderr + "(loader failed to start)" }));
+        child.on("close", (status) => resolve({ status, stdout, stderr }));
+    });
+}
+function lastLines(s, n = 8) {
+    return s.trim().split("\n").slice(-n).join("\n");
+}
+// Loader frames are authored by our own doctor-loader — trusted construction.
+// The guards below separate "a usable frame" from "not a frame"; they are not
+// schema validation of the doctor contract.
+const execLoader = (programPath, mode, timeoutMs = DEFAULT_TIMEOUT_MS) => Effect.gen(function* () {
+    const abs = path.resolve(programPath);
+    if (!fs.existsSync(abs)) {
+        return yield* new ProgramMissing({ programPath: abs });
+    }
+    const gate = scanDoctorFile(abs);
+    if (gate.red.length > 0) {
+        return yield* new DoctorUnsafe({
+            programPath: abs,
+            capabilities: [...new Set(gate.red.map(f => f.capability))],
+            findings: gate.red.map(f => `${f.capability}: ${f.detail}`),
+        });
+    }
+    const nodeFlags = yield* Effect.promise(() => permissionArgs(mode.kind === "verify"));
+    const out = yield* Effect.tryPromise({
+        try: () => spawnLoader(abs, mode, timeoutMs, nodeFlags),
+        catch: (e) => new DoctorCrashed({ programPath: abs, detail: String(e) }),
+    });
+    if (out.status !== 0) {
+        if (deniedByPermissionModel(out.stderr)) {
+            return yield* new DoctorUnsafe({
+                programPath: abs,
+                capabilities: [denialCapability(out.stderr)],
+                findings: ["the runtime refused a forbidden capability:", ...lastLines(out.stderr, 2).split("\n")],
+            });
+        }
+        return yield* new DoctorCrashed({ programPath: abs, detail: lastLines(out.stderr || "exit " + out.status) });
+    }
+    const lines = out.stdout.split("\n");
+    // The last sentinel line wins. A doctor writing directly to
+    // process.stdout can forge a frame — accepted under the bug-not-
+    // adversary trust model (doctor programs are our own agents' output).
+    const idx = lines.findLastIndex(l => l.startsWith(RESULT_SENTINEL));
+    const stdout = out.stdout.slice(0, 500);
+    if (idx === -1) {
+        return yield* new NoFramedResult({ programPath: abs, stdout });
+    }
+    let frame;
+    try {
+        frame = JSON.parse(lines[idx].slice(RESULT_SENTINEL.length));
+    }
+    catch {
+        return yield* new NoFramedResult({ programPath: abs, stdout });
+    }
+    if (frame === null || typeof frame !== "object") {
+        return yield* new NoFramedResult({ programPath: abs, stdout });
+    }
+    return frame;
+});
+// Frames decode by their declared kind — the contract's Frame union is the
+// discriminator; the casts below are keyed to it, not blind.
+const asRunResult = (frame) => Effect.gen(function* () {
+    var _a;
+    if (frame.kind !== "run" || !Array.isArray(frame.findings) || frame.meta === null || typeof frame.meta !== "object") {
+        return yield* new NoFramedResult({ programPath: String((_a = frame.root) !== null && _a !== void 0 ? _a : ""), stdout: JSON.stringify(frame).slice(0, 500) });
+    }
+    return frame;
+});
+const asVerifyResult = (frame) => Effect.gen(function* () {
+    var _a;
+    if (frame.kind !== "verify" || !Array.isArray(frame.results) || frame.meta === null || typeof frame.meta !== "object") {
+        return yield* new NoFramedResult({ programPath: String((_a = frame.programPath) !== null && _a !== void 0 ? _a : ""), stdout: JSON.stringify(frame).slice(0, 500) });
+    }
+    return frame;
+});
+// ---- the public interface: plain async, typed failures thrown ----
+//
+// Effect is an implementation detail of this module. The public functions
+// throw the tagged errors above (they extend Error, so callers get _tag
+// matching and a stack); concurrency and composition stay inside.
+const squash = (cause) => {
+    const e = Cause.squash(cause);
+    // Defects (interrupt/die) never occur in this module's code paths, but a
+    // defect must not escape the typed channel.
+    return isRunnerError(e) ? e : new DoctorCrashed({ programPath: "", detail: String(e) });
+};
+async function drain(effect) {
+    const exit = await Effect.runPromiseExit(effect);
+    return Exit.match(exit, {
+        onFailure: (cause) => { throw squash(cause); },
+        onSuccess: (value) => value,
+    });
+}
+const runDoctorE = ({ programPath, targetDir }) => Effect.flatMap(execLoader(programPath, { kind: "run", root: path.resolve(targetDir) }, DEFAULT_TIMEOUT_MS), asRunResult);
+const verifyDoctorE = ({ programPath, fixturesPath }) => Effect.gen(function* () {
+    const abs = path.resolve(programPath);
+    const fixtures = path.resolve(fixturesPath !== null && fixturesPath !== void 0 ? fixturesPath : fixturesPathFor(abs));
+    if (!fs.existsSync(fixtures)) {
+        return yield* new FixturesMissing({ programPath: abs, fixturesPath: fixtures });
+    }
+    const frame = yield* execLoader(abs, { kind: "verify", fixtures }, DEFAULT_TIMEOUT_MS);
+    return yield* asVerifyResult(frame);
+});
+export async function runDoctor(options) {
+    return drain(runDoctorE(options));
+}
+export async function verifyDoctor(options) {
+    return drain(verifyDoctorE(options));
+}
+// A doctor whose meta cannot be read is data (a broken doctor), not a
+// failure: metaDoctor never throws, it returns { meta: null, error }.
+export async function metaDoctor({ programPath }) {
+    const frame = await Effect.runPromise(Effect.flatMap(Effect.exit(execLoader(programPath, { kind: "meta" }, META_TIMEOUT_MS)), (exit) => Effect.succeed(Exit.match(exit, {
+        onFailure: (cause) => ({ meta: null, cause: squash(cause) }),
+        onSuccess: (f) => ({
+            meta: f.kind === "meta" && f.meta !== null && typeof f.meta === "object" ? f.meta : null,
+        }),
+    }))));
+    return frame;
+}

package/bin/score.d.ts

@@ -0,0 +1,13 @@
+import { Finding, ReportGroup, Severity } from "./contract.js";
+export interface ScoreResult {
+    score: number;
+    grade: string;
+}
+export declare function findingSeverity(g: ReportGroup, f: Finding): Severity;
+export declare function gradeFor(score: number): string;
+export declare function scoreFromSeverities(sevs: Severity[]): ScoreResult;
+export declare function computeScore(groups: ReportGroup[]): ScoreResult;
+export declare function categoryRollup(groups: ReportGroup[]): {
+    category: string;
+    counts: Record<Severity, number>;
+}[];

package/bin/score.js

@@ -0,0 +1,39 @@
+import { resolveFinding } from "./contract.js";
+const WEIGHTS = { error: 10, warning: 4, info: 1 };
+export function findingSeverity(g, f) {
+    return resolveFinding(g.meta, f).severity;
+}
+export function gradeFor(score) {
+    if (score >= 90)
+        return "Excellent";
+    if (score >= 75)
+        return "Good";
+    if (score >= 50)
+        return "Fair";
+    if (score >= 25)
+        return "Poor";
+    return "Critical";
+}
+export function scoreFromSeverities(sevs) {
+    let score = 100;
+    for (const s of sevs)
+        score -= WEIGHTS[s];
+    score = Math.max(0, Math.min(100, score));
+    return { score, grade: gradeFor(score) };
+}
+export function computeScore(groups) {
+    return scoreFromSeverities(groups.flatMap(g => g.findings.map(f => findingSeverity(g, f))));
+}
+export function categoryRollup(groups) {
+    var _a;
+    const map = new Map();
+    for (const g of groups) {
+        const category = (_a = g.meta.category) !== null && _a !== void 0 ? _a : "general";
+        if (!map.has(category))
+            map.set(category, { error: 0, warning: 0, info: 0 });
+        for (const f of g.findings) {
+            map.get(category)[findingSeverity(g, f)]++;
+        }
+    }
+    return [...map.entries()].map(([category, counts]) => ({ category, counts }));
+}

package/bin/sdk.d.ts

@@ -0,0 +1,5 @@
+import { DoctorCtx, Finding } from "./contract.js";
+export declare function buildCtx(root: string): {
+    ctx: DoctorCtx;
+    getFindings(): Finding[];
+};

package/bin/sdk.js

@@ -0,0 +1,95 @@
+import * as fs from "fs";
+import * as path from "path";
+import { SEARCH_REQUEST, SEARCH_RESULT } from "./contract.js";
+const DEFAULT_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"];
+export function buildCtx(root) {
+    const findings = [];
+    function walk(dir, exts, out) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(abs, exts, out);
+            else if (exts.has(path.extname(entry.name)))
+                out.push(path.relative(root, abs));
+        }
+    }
+    const ctx = {
+        root,
+        files: {
+            list(exts) {
+                const extSet = new Set((exts && exts.length ? exts : DEFAULT_EXTS)
+                    .map(e => (e.startsWith(".") ? e : "." + e)));
+                const out = [];
+                walk(root, extSet, out);
+                return out.sort();
+            },
+            read(relativePath) {
+                const abs = path.resolve(root, relativePath);
+                if (abs !== root && !abs.startsWith(root + path.sep)) {
+                    throw new Error(`ctx.files.read escapes the repo root: ${relativePath}`);
+                }
+                return fs.readFileSync(abs, "utf8");
+            },
+        },
+        search: {
+            pattern(pattern, language = "TypeScript") {
+                return runSearch(pattern, language, root);
+            },
+        },
+        report: {
+            finding(f) {
+                findings.push(f);
+            },
+        },
+    };
+    return { ctx, getFindings: () => findings.slice() };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function runSearch(pattern, language, root) {
+    var _a;
+    let response;
+    try {
+        fs.writeSync(3, SEARCH_REQUEST + JSON.stringify({ pattern, language, root }) + "\n");
+        response = readSearchResponse();
+    }
+    catch (e) {
+        throw new Error(`ctx.search is unavailable — no search host on this channel (${e instanceof Error ? e.message : String(e)}). `
+            + "Doctors run through any-doctor; a bare doctor-loader.mjs invocation has no host.");
+    }
+    if (response.error !== undefined)
+        throw new Error(response.error);
+    return toMatches((_a = response.matches) !== null && _a !== void 0 ? _a : [], root);
+}
+function readSearchResponse() {
+    const chunk = Buffer.alloc(65536);
+    let buffer = "";
+    for (;;) {
+        const n = fs.readSync(0, chunk, 0, chunk.length, null);
+        if (n === 0)
+            throw new Error("search host channel closed");
+        buffer += chunk.toString("utf8", 0, n);
+        const nl = buffer.indexOf("\n");
+        if (nl !== -1) {
+            const line = buffer.slice(0, nl);
+            if (line.startsWith(SEARCH_RESULT)) {
+                return JSON.parse(line.slice(SEARCH_RESULT.length));
+            }
+            buffer = buffer.slice(nl + 1);
+        }
+    }
+}
+function toMatches(raw, root) {
+    return raw.map(m => {
+        var _a, _b, _c, _d, _e, _f;
+        return ({
+            file: (m.file || "").replace(new RegExp("^" + escapeRegExp(root) + "/"), ""),
+            line: ((_c = (_b = (_a = m.range) === null || _a === void 0 ? void 0 : _a.start) === null || _b === void 0 ? void 0 : _b.line) !== null && _c !== void 0 ? _c : 0) + 1,
+            column: ((_f = (_e = (_d = m.range) === null || _d === void 0 ? void 0 : _d.start) === null || _e === void 0 ? void 0 : _e.column) !== null && _f !== void 0 ? _f : 1),
+            text: m.text || "",
+        });
+    });
+}

package/bin/search-host.d.ts

@@ -0,0 +1,6 @@
+import { Mode } from "./contract.js";
+import { runEngineSearch } from "./engine.js";
+export declare function searchBase(mode: Mode): string;
+type Engine = typeof runEngineSearch;
+export declare function handleSearchLine(line: string, mode: Mode, engine?: Engine): string | null;
+export {};