codictator 0.0.0 → 0.1.3

package/dist/cli/serve-methods.js

@@ -0,0 +1,181 @@
+// SPEC §7.15: stdio query methods. Read-only protocol rows built on the
+// same surfaces the CLI commands use (pack registry, explain), imported
+// through their public index.ts entries (§3.3). Status lives in
+// serve-status.ts; `run` in serve-run.ts; evaluation rows in serve-eval.ts.
+import { errorRowFor, explainCodeText, explainUnknownText, replaySummary, } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { loadBuiltinPack } from "../features/packs/index.js";
+import { parseJson } from "../kernel/index.js";
+import { readLogEvents } from "./inspect.js";
+import { dispatchEvalMethod } from "./serve-eval.js";
+import { invalidParamsError, methodNotFoundError, serverError, } from "./serve-protocol.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+import { statusMethod } from "./serve-status.js";
+import { loadRepoConfig, readStateText } from "./shared.js";
+function methodMissing(detail) {
+    return { ok: false, error: invalidParamsError(detail) };
+}
+function stringField(params, name) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    const found = field(params, name);
+    return typeof found === "string" ? found : undefined;
+}
+async function waiverRows(root) {
+    const text = await readStateText(root, ".codictator/waivers.json");
+    if (text === undefined) {
+        return [];
+    }
+    const parsed = parseJson(text);
+    if (!parsed.ok || !isRecord(parsed.value)) {
+        return [];
+    }
+    const listed = field(parsed.value, "waivers");
+    if (!Array.isArray(listed)) {
+        return [];
+    }
+    const rows = [];
+    for (const entry of listed) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const rule = field(entry, "rule");
+        if (typeof rule === "string" && rule !== "") {
+            rows.push({ rule, row: entry });
+        }
+    }
+    return rows;
+}
+// The tunables overlay for one rule: pack defaults with config values
+// where the human tuned them.
+function effectiveParams(defaults, tuned) {
+    const rawParams = isRecord(tuned) ? field(tuned, "params") : undefined;
+    const tunedParams = isRecord(rawParams) ? rawParams : {};
+    const params = {};
+    for (const [name, param] of Object.entries(defaults)) {
+        params[name] = {
+            default: param.default,
+            bound: param.bound,
+            effective: tunedParams[name] === undefined ? param.default : tunedParams[name],
+        };
+    }
+    return params;
+}
+function ruleRow(rule, pack, tunables, waivers) {
+    return {
+        id: rule.id,
+        pack,
+        statement: rule.statement,
+        reason: rule.reason,
+        tier: rule.tier,
+        family: rule.family,
+        params: effectiveParams(rule.params, tunables[rule.id]),
+        waivers: waivers
+            .filter((entry) => entry.rule === rule.id)
+            .map((entry) => entry.row),
+        coverage: "per-harness capability declarations; see codictator status",
+    };
+}
+// SPEC §7.15: `rules/list` answers rules with effective params, waivers
+// and coverage. Effective params overlay config tunables on pack defaults.
+async function rulesListMethod(ctx) {
+    const root = await resolveRoot(ctx.root);
+    const configured = await loadRepoConfig(root, undefined, ctx.engineVersion ?? ENGINE_VERSION);
+    // Tunables are optional in a repo config (§4.2 validation), so a
+    // missing section defaults before indexing by rule id.
+    const configuredTunables = configured.ok === true ? configured.value.effective.config.tunables : {};
+    const tunables = configuredTunables ?? {};
+    const waivers = await waiverRows(root);
+    const rules = [];
+    for (const id of ["core", "typescript", "dotnet", "python"]) {
+        const loaded = await loadBuiltinPack(id);
+        if (!loaded.ok) {
+            continue;
+        }
+        const pack = `${loaded.value.manifest.id}@${loaded.value.manifest.version}`;
+        for (const rule of loaded.value.manifest.rules) {
+            rules.push(ruleRow(rule, pack, tunables, waivers));
+        }
+    }
+    return methodOk({ rules });
+}
+// SPEC §4.18.2 + §7.15: `explain` answers the rule, event or error detail;
+// unknown ids fail as CDX-E010 with the nearest known ids.
+async function explainMethod(params, ctx) {
+    const id = stringField(params, "id");
+    if (id === undefined || id === "") {
+        return methodMissing("explain params must be { id: string }");
+    }
+    const coded = errorRowFor(id);
+    if (coded !== undefined) {
+        return methodOk({
+            kind: "error",
+            code: coded.code,
+            exit: coded.exit,
+            meaning: coded.meaning,
+            remediation: coded.remediation,
+            text: explainCodeText(coded),
+        });
+    }
+    if (id.includes("/")) {
+        for (const packId of ["core", "typescript", "dotnet", "python"]) {
+            const loaded = await loadBuiltinPack(packId);
+            if (!loaded.ok) {
+                continue;
+            }
+            for (const rule of loaded.value.manifest.rules) {
+                if (rule.id !== id) {
+                    continue;
+                }
+                return methodOk({
+                    kind: "rule",
+                    rule: rule.id,
+                    pack: `${loaded.value.manifest.id}@${loaded.value.manifest.version}`,
+                    statement: rule.statement,
+                    remediation: rule.remediation,
+                });
+            }
+        }
+    }
+    const root = await resolveRoot(ctx.root);
+    const log = await readLogEvents(root);
+    const event = log?.events.find((candidate) => candidate.id === id);
+    if (event !== undefined) {
+        return methodOk({ kind: "event", event: id, text: replaySummary(event) });
+    }
+    return {
+        ok: false,
+        error: serverError("CDX-E010", `unknown rule, event or error id "${id}"`, "Check the spelling; the nearest known ids were listed.", { id, text: explainUnknownText(id) }),
+    };
+}
+// SPEC §7.15: the read-row dispatch. `run` is owned by serve-run.ts; the
+// evaluation rows by serve-eval.ts; status by serve-status.ts.
+export async function dispatchMethod(method, params, ctx) {
+    switch (method) {
+        case "initialize": {
+            const root = await resolveRoot(ctx.root);
+            return methodOk({
+                protocolVersion: 1,
+                engineVersion: ctx.engineVersion ?? ENGINE_VERSION,
+                root,
+            });
+        }
+        case "status": {
+            return statusMethod(ctx);
+        }
+        case "rules/list": {
+            return rulesListMethod(ctx);
+        }
+        case "explain": {
+            return explainMethod(params, ctx);
+        }
+        default: {
+            const handled = await dispatchEvalMethod(method, params, ctx);
+            if (handled !== undefined) {
+                return handled;
+            }
+            return { ok: false, error: methodNotFoundError(method) };
+        }
+    }
+}

package/dist/cli/serve-protocol.d.ts

@@ -0,0 +1,35 @@
+export declare const PROTOCOL_VERSION = 1;
+export type RpcId = string | number | null;
+export interface RpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: RpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface RpcErrorShape {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export type DecodedLine = {
+    readonly kind: "request";
+    readonly request: RpcRequest;
+} | {
+    readonly kind: "notification";
+    readonly method: string;
+    readonly params: unknown;
+} | {
+    readonly kind: "syntax";
+} | {
+    readonly kind: "bad";
+    readonly id: RpcId;
+};
+export declare function decodeLine(line: string): DecodedLine;
+export declare function successFrame(id: RpcId, result: unknown): string;
+export declare function errorFrame(id: RpcId, error: RpcErrorShape): string;
+export declare function notificationFrame(method: string, params: unknown): string;
+export declare function parseErrorFrame(): string;
+export declare function invalidRequestFrame(id: RpcId): string;
+export declare function methodNotFoundError(method: string): RpcErrorShape;
+export declare function invalidParamsError(detail: string): RpcErrorShape;
+export declare function serverError(code: string, message: string, remediation: string, extra?: Record<string, unknown>): RpcErrorShape;

package/dist/cli/serve-protocol.js

@@ -0,0 +1,97 @@
+// SPEC §7.15 + §4.19.5: JSON-RPC 2.0 framing for `serve --stdio`. One
+// message per line, UTF-8. Frames go to stdout only; every diagnostic goes
+// to stderr, so the extension parser never sees a non-frame line. Malformed
+// input answers a parse error and the server keeps running (EC-9).
+import { parseJson, stableLineStringify } from "../kernel/index.js";
+export const PROTOCOL_VERSION = 1;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordField(record, name) {
+    return record[name];
+}
+function isValidId(value) {
+    return (typeof value === "string" || typeof value === "number" || value === null);
+}
+export function decodeLine(line) {
+    const parsed = parseJson(line);
+    if (!parsed.ok) {
+        return { kind: "syntax" };
+    }
+    const value = parsed.value;
+    if (!isRecord(value)) {
+        return { kind: "bad", id: null };
+    }
+    if (recordField(value, "jsonrpc") !== "2.0") {
+        return { kind: "bad", id: null };
+    }
+    if (typeof recordField(value, "method") !== "string") {
+        return { kind: "bad", id: null };
+    }
+    const method = recordField(value, "method");
+    if (typeof method !== "string") {
+        return { kind: "bad", id: null };
+    }
+    const rawId = recordField(value, "id");
+    if (rawId === undefined) {
+        return {
+            kind: "notification",
+            method,
+            params: recordField(value, "params"),
+        };
+    }
+    if (!isValidId(rawId)) {
+        return { kind: "bad", id: null };
+    }
+    return {
+        kind: "request",
+        request: {
+            jsonrpc: "2.0",
+            id: rawId,
+            method,
+            params: recordField(value, "params"),
+        },
+    };
+}
+export function successFrame(id, result) {
+    return stableLineStringify({ id, jsonrpc: "2.0", result });
+}
+export function errorFrame(id, error) {
+    return stableLineStringify({ error, id, jsonrpc: "2.0" });
+}
+export function notificationFrame(method, params) {
+    return stableLineStringify({ jsonrpc: "2.0", method, params });
+}
+export function parseErrorFrame() {
+    return errorFrame(null, {
+        code: -32700,
+        message: "Parse error: malformed JSON-RPC line",
+    });
+}
+export function invalidRequestFrame(id) {
+    return errorFrame(id, {
+        code: -32600,
+        message: "Invalid Request: expected a JSON-RPC 2.0 call",
+    });
+}
+export function methodNotFoundError(method) {
+    return {
+        code: -32601,
+        message: `Method not found: ${method}`,
+    };
+}
+export function invalidParamsError(detail) {
+    return {
+        code: -32602,
+        message: `Invalid params: ${detail}`,
+    };
+}
+// SPEC §7.15: method failures carry their CDX row in data, so the
+// extension can render the code and remediation beside the JSON-RPC error.
+export function serverError(code, message, remediation, extra) {
+    return {
+        code: -32000,
+        message: `${code} ${message}`,
+        data: { code, remediation, ...extra },
+    };
+}

package/dist/cli/serve-run.d.ts

@@ -0,0 +1,9 @@
+import type { Result } from "../kernel/index.ts";
+import type { CliOptions } from "./index.ts";
+import { type MethodOutcome } from "./serve-shared.ts";
+export interface RunContext {
+    readonly root: string;
+    readonly engineVersion?: string;
+    readonly execute: (options: CliOptions) => Promise<Result<number>>;
+}
+export declare function handleRun(params: unknown, ctx: RunContext): Promise<MethodOutcome>;

package/dist/cli/serve-run.js

@@ -0,0 +1,135 @@
+import { invalidParamsError, serverError } from "./serve-protocol.js";
+import { field, isRecord } from "./serve-shared.js";
+import { exitFor } from "./shared.js";
+// SPEC §4.19.2 H rows: commands (and subcommands) the human-only change
+// path reserves. The table keeps the predicate flat; the server refuses
+// these before invoking anything.
+const ALWAYS_HUMAN = new Set([
+    "init",
+    "uninstall",
+    "waive",
+]);
+const HUMAN_SUBCOMMANDS = [
+    ["baseline", "capture"],
+    ["pack", "accept"],
+    ["task", "ack"],
+];
+function isHumanOnly(argv) {
+    const command = argv[0] ?? "";
+    if (ALWAYS_HUMAN.has(command)) {
+        return true;
+    }
+    const sub = argv[1] ?? "";
+    return HUMAN_SUBCOMMANDS.some(([name, gated]) => name === command && gated === sub);
+}
+function commandLine(argv) {
+    return `codictator ${argv.join(" ")}`;
+}
+// The CLI handlers print through process.stdout/stderr, so `run` captures
+// those process-global writes per call and restores them in a finally. The
+// scope is the process, not the connection: frames stay the only stdout
+// bytes while one connection serves (each server serializes requests on
+// its pump chain), but overlapping `run` calls in one process would share
+// the globals. Same-process concurrency therefore stays sequential by
+// construction; true parallelism stays across OS processes, one server per
+// VS Code window (SPEC §4.19.6 EC-10).
+async function executeCaptured(ctx, argv) {
+    let stdout = "";
+    let stderr = "";
+    const originalStdout = process.stdout.write;
+    const originalStderr = process.stderr.write;
+    const collectStdout = (chunk, encoding, callback) => {
+        if (typeof chunk === "string") {
+            stdout += chunk;
+        }
+        else {
+            stdout += new TextDecoder().decode(chunk);
+        }
+        if (typeof encoding === "function") {
+            encoding();
+        }
+        else if (typeof callback === "function") {
+            callback();
+        }
+        return true;
+    };
+    const collectStderr = (chunk, encoding, callback) => {
+        if (typeof chunk === "string") {
+            stderr += chunk;
+        }
+        else {
+            stderr += new TextDecoder().decode(chunk);
+        }
+        if (typeof encoding === "function") {
+            encoding();
+        }
+        else if (typeof callback === "function") {
+            callback();
+        }
+        return true;
+    };
+    process.stdout.write = collectStdout;
+    process.stderr.write = collectStderr;
+    try {
+        const result = await ctx.execute(ctx.engineVersion === undefined
+            ? { argv: [...argv], cwd: ctx.root }
+            : { argv: [...argv], cwd: ctx.root, engineVersion: ctx.engineVersion });
+        if (result.ok) {
+            return { exitCode: result.value, stdout, stderr };
+        }
+        return {
+            exitCode: exitFor(result.error.code),
+            stdout,
+            stderr,
+            code: result.error.code,
+            remediation: result.error.remediation,
+        };
+    }
+    catch {
+        return {
+            exitCode: 7,
+            stdout,
+            stderr,
+            code: "CDX-E901",
+            remediation: "Retry the command; if it keeps failing, report the stall.",
+        };
+    }
+    finally {
+        process.stdout.write = originalStdout;
+        process.stderr.write = originalStderr;
+    }
+}
+// SPEC §7.15: `run { argv }` answers the CLI result; human-only argv
+// answers CDX-E107 with data.commandLine and never runs.
+export async function handleRun(params, ctx) {
+    if (!isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("run params must be { argv }"),
+        };
+    }
+    const raw = field(params, "argv");
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return {
+            ok: false,
+            error: invalidParamsError("run argv must be a non-empty array of strings"),
+        };
+    }
+    const argv = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("run argv must be a non-empty array of strings"),
+            };
+        }
+        argv.push(entry);
+    }
+    if (isHumanOnly(argv)) {
+        return {
+            ok: false,
+            error: serverError("CDX-E107", "human-only command refused: no interactive TTY on the server", "Run this command yourself in an interactive terminal, not through an agent or hook.", { commandLine: commandLine(argv) }),
+        };
+    }
+    return { ok: true, value: await executeCaptured(ctx, argv) };
+}

package/dist/cli/serve-server.d.ts

@@ -0,0 +1,5 @@
+import type { Result } from "../kernel/index.ts";
+import type { CliOptions } from "./index.ts";
+import type { StdioServerStreams } from "./serve-shared.ts";
+export type ServeExecute = (options: CliOptions) => Promise<Result<number>>;
+export declare function startStdioServer(options: CliOptions, execute: ServeExecute, streams?: StdioServerStreams): Promise<number>;

package/dist/cli/serve-server.js

@@ -0,0 +1,120 @@
+import { readLogEvents } from "./inspect.js";
+import { dispatchMethod } from "./serve-methods.js";
+import { decodeLine, errorFrame, invalidRequestFrame, notificationFrame, parseErrorFrame, successFrame, } from "./serve-protocol.js";
+import { handleRun } from "./serve-run.js";
+import { openLinePump } from "./serve-transport.js";
+function writeFrame(stdout, text) {
+    stdout.write(text);
+}
+function writeDiagnostic(stderr, text) {
+    stderr.write(`${text}\n`);
+}
+// The Fs-port watcher: the baseline is set at startup with no notify; after
+// each request new lines push one `events/appended` notification carrying
+// the new event lines.
+async function pollAppended(state) {
+    const log = await readLogEvents(state.root);
+    if (log === undefined) {
+        return;
+    }
+    const total = log.events.length + log.corrupt;
+    if (!state.seen.started) {
+        state.seen.count = total;
+        state.seen.started = true;
+        return;
+    }
+    if (total <= state.seen.count) {
+        state.seen.count = total;
+        return;
+    }
+    const fresh = log.events.slice(state.seen.count);
+    state.seen.count = total;
+    if (fresh.length > 0) {
+        writeFrame(state.io.stdout, notificationFrame("events/appended", { events: fresh }));
+    }
+}
+// One request answered with exactly one frame; a throw inside a method
+// can never escape the loop (EC-9 survival).
+async function answerRequest(id, method, params, state) {
+    try {
+        const runCtx = state.engineVersion === undefined
+            ? { root: state.root, execute: state.execute }
+            : {
+                root: state.root,
+                engineVersion: state.engineVersion,
+                execute: state.execute,
+            };
+        const methodCtx = state.engineVersion === undefined
+            ? { root: state.root }
+            : { root: state.root, engineVersion: state.engineVersion };
+        const outcome = method === "run"
+            ? await handleRun(params, runCtx)
+            : await dispatchMethod(method, params, methodCtx);
+        writeFrame(state.io.stdout, outcome.ok
+            ? successFrame(id, outcome.value)
+            : errorFrame(id, outcome.error));
+    }
+    catch {
+        writeFrame(state.io.stdout, errorFrame(id, {
+            code: -32603,
+            message: "Internal error: the method failed to complete",
+        }));
+    }
+}
+async function handleLine(line, state) {
+    if (line.trim() === "") {
+        return;
+    }
+    const decoded = decodeLine(line);
+    if (decoded.kind === "syntax") {
+        writeFrame(state.io.stdout, parseErrorFrame());
+        return;
+    }
+    if (decoded.kind === "bad") {
+        writeFrame(state.io.stdout, invalidRequestFrame(decoded.id));
+        return;
+    }
+    if (decoded.kind === "notification") {
+        return;
+    }
+    const { id, method, params } = decoded.request;
+    await answerRequest(id, method, params, state);
+    try {
+        await pollAppended(state);
+    }
+    catch {
+        // The watcher is best-effort: the request was already answered, and
+        // a watcher failure must never break the loop (EC-9 survival).
+    }
+}
+// SPEC §7.15: serve one NDJSON session on this process's stdio. The loop
+// ends on stdin EOF (the client disconnected) or a stdin error; the exit
+// is always 0 so harness tests observe a clean shutdown. A silent pipe
+// past the first-byte grace is a harness call with no client: exit 0
+// without serving, so `node --test` and coverage runs never hang.
+export function startStdioServer(options, execute, streams = {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const argv = options.argv;
+    if (argv[0] !== "serve" || argv[1] !== "--stdio" || argv.length !== 2) {
+        writeDiagnostic(streams.stderr, "usage: codictator serve --stdio");
+        return Promise.resolve(2);
+    }
+    const state = {
+        root: options.cwd,
+        ...(options.engineVersion === undefined
+            ? {}
+            : { engineVersion: options.engineVersion }),
+        execute,
+        io: streams,
+        seen: { count: 0, started: false },
+    };
+    if (streams.stdin.readableEnded || streams.stdin.readable !== true) {
+        return Promise.resolve(0);
+    }
+    return new Promise((resolve) => {
+        openLinePump(streams.stdin, pollAppended(state), (line) => handleLine(line, state), resolve);
+    });
+}

package/dist/cli/serve-shared.d.ts

@@ -0,0 +1,34 @@
+import type { RpcErrorShape } from "./serve-protocol.ts";
+export interface MethodContext {
+    readonly root: string;
+    readonly engineVersion?: string;
+}
+export type MethodOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: RpcErrorShape;
+};
+export declare function methodOk(value: unknown): MethodOutcome;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function field(record: Record<string, unknown>, name: string): unknown;
+export interface StdioServerStdin {
+    readonly readable: boolean;
+    readonly readableEnded: boolean;
+    readonly isTTY?: boolean | undefined;
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    on(event: "end" | "error", listener: () => void): unknown;
+    removeListener(event: "data" | "end" | "error", listener: (...args: Array<never>) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+export interface StdioServerStdout {
+    write(chunk: string | Uint8Array): boolean;
+}
+export interface StdioServerStreams {
+    readonly stdin: StdioServerStdin;
+    readonly stdout: StdioServerStdout;
+    readonly stderr: StdioServerStdout;
+}
+export declare function resolveRoot(cwd: string): Promise<string>;

package/dist/cli/serve-shared.js

@@ -0,0 +1,20 @@
+// SPEC §7.15: shared stdio plumbing. Method results, unknown narrowing
+// and root resolution for the read, evaluation and run rows; framing stays
+// in serve-protocol.ts. Imports kernel only, so every serve module builds
+// on this without cycles.
+import { resolveRepoRoot } from "../kernel/index.js";
+export function methodOk(value) {
+    return { ok: true, value };
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Bracket access through a variable keeps noPropertyAccessFromIndexSignature
+// satisfied without tripping useLiteralKeys (kernel schema.ts pattern).
+export function field(record, name) {
+    return record[name];
+}
+export async function resolveRoot(cwd) {
+    const root = await resolveRepoRoot(cwd);
+    return root.ok ? root.value : cwd;
+}

package/dist/cli/serve-status.d.ts

@@ -0,0 +1,2 @@
+import { type MethodContext, type MethodOutcome } from "./serve-shared.ts";
+export declare function statusMethod(ctx: MethodContext): Promise<MethodOutcome>;