codictator 0.0.0 → 0.1.2

package/dist/cli/serve-eval.js

@@ -0,0 +1,165 @@
+// SPEC §7.15: stdio evaluation rows. `findings/list` and `verify` run
+// the same engine evaluation the `verify` command uses; log and budget
+// rows live in serve-log.ts.
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { isFixturePath } from "../kernel/index.js";
+import { evaluateScope, resolveVerifyScope, triggerForLayer, } from "./evaluate.js";
+import { dispatchLogMethod } from "./serve-log.js";
+import { invalidParamsError } from "./serve-protocol.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+import { loadRepoConfig } from "./shared.js";
+function methodFail(code, message, remediation) {
+    return {
+        ok: false,
+        error: {
+            code: -32000,
+            message: `${code} ${message}`,
+            data: { code, remediation },
+        },
+    };
+}
+function stringArrayField(params, name) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    const found = field(params, name);
+    if (!Array.isArray(found)) {
+        return undefined;
+    }
+    const files = [];
+    for (const entry of found) {
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        files.push(entry);
+    }
+    return files;
+}
+// The shared scope-and-evaluate flow: files when named, else the tracked
+// tree plus staged edits like the bare `verify` command; pack fixtures
+// stay out of every scope (§4.4.1). Answers findings with the config hash.
+async function evaluateFiles(ctx, files, layer) {
+    const root = await resolveRoot(ctx.root);
+    const configured = await loadRepoConfig(root, undefined, ctx.engineVersion ?? ENGINE_VERSION);
+    if (!configured.ok) {
+        return methodFail(configured.error.code, configured.error.message, "Fix .codictator/config.json, then retry.");
+    }
+    const scoped = files === undefined
+        ? await resolveVerifyScope(configured.value.ports, {
+            staged: false,
+            all: true,
+            base: undefined,
+            head: undefined,
+            layer,
+        })
+        : {
+            ok: true,
+            value: {
+                trigger: triggerForLayer(layer),
+                files: [...new Set(files)]
+                    .sort()
+                    .filter((file) => !isFixturePath(file)),
+                note: "stdio files",
+            },
+        };
+    if (!scoped.ok) {
+        return methodFail(scoped.error.code, scoped.error.message, scoped.error.remediation);
+    }
+    const evaluated = await evaluateScope(configured.value.ports, configured.value.effective.config.packs.map((entry) => entry.id), scoped.value, configured.value.ports.clock.now(), configured.value.effective.configHash);
+    if (!evaluated.ok) {
+        return methodFail(evaluated.error.code, evaluated.error.message, evaluated.error.remediation);
+    }
+    return methodOk({
+        findings: evaluated.value,
+        configHash: configured.value.effective.configHash,
+    });
+}
+function evaluatedParts(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        findings: field(value, "findings"),
+        configHash: field(value, "configHash"),
+    };
+}
+// SPEC §7.15: `findings/list { files? }` answers findings with remediation.
+async function findingsListMethod(params, ctx) {
+    const files = stringArrayField(params, "files");
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("findings/list params must be { files? }"),
+        };
+    }
+    if (isRecord(params) &&
+        field(params, "files") !== undefined &&
+        files === undefined) {
+        return {
+            ok: false,
+            error: invalidParamsError("findings/list files must be an array of strings"),
+        };
+    }
+    const evaluated = await evaluateFiles(ctx, files, undefined);
+    if (!evaluated.ok) {
+        return evaluated;
+    }
+    const parts = evaluatedParts(evaluated.value);
+    const findings = Array.isArray(parts?.findings) ? parts?.findings : [];
+    return methodOk({
+        decision: findings.length === 0 ? "allow" : "block",
+        findings,
+        configHash: parts?.configHash ?? "",
+    });
+}
+const LAYERS = new Set(["L1", "L2", "L3", "L4", "L5"]);
+// SPEC §7.15: `verify { layer, files? }` answers a verdict for the layer.
+async function verifyMethod(params, ctx) {
+    if (!isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify params must be { layer, files? }"),
+        };
+    }
+    const layer = field(params, "layer");
+    if (typeof layer !== "string" || !LAYERS.has(layer)) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify layer must be one of L1..L5"),
+        };
+    }
+    const files = stringArrayField(params, "files");
+    if (field(params, "files") !== undefined && files === undefined) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify files must be an array of strings"),
+        };
+    }
+    const evaluated = await evaluateFiles(ctx, files, layer);
+    if (!evaluated.ok) {
+        return evaluated;
+    }
+    const parts = evaluatedParts(evaluated.value);
+    const findings = Array.isArray(parts?.findings) ? parts?.findings : [];
+    return methodOk({
+        verdict: findings.length === 0 ? "allow" : "block",
+        layer,
+        findings,
+        configHash: parts?.configHash ?? "",
+    });
+}
+// SPEC §7.15 rows owned here; the log rows by serve-log.ts; unknown names
+// return undefined so the caller answers method-not-found.
+export async function dispatchEvalMethod(method, params, ctx) {
+    switch (method) {
+        case "findings/list": {
+            return findingsListMethod(params, ctx);
+        }
+        case "verify": {
+            return verifyMethod(params, ctx);
+        }
+        default: {
+            return dispatchLogMethod(method, params, ctx);
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import { type MethodContext, type MethodOutcome } from "./serve-shared.ts";
+export declare function dispatchLogMethod(method: string, params: unknown, ctx: MethodContext): Promise<MethodOutcome | undefined>;

package/dist/cli/serve-log.js

@@ -0,0 +1,150 @@
+// SPEC §7.15: stdio log and budget rows. Event tails and steering
+// history page the same event log the audit surfaces read; the budget row
+// answers per-session bands, or unavailable when no usage applies.
+import { currentBand } from "../features/steering/index.js";
+import { readLogEvents } from "./inspect.js";
+import { invalidParamsError } from "./serve-protocol.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+function numberField(params, name) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    const found = field(params, name);
+    return typeof found === "number" ? found : undefined;
+}
+// SPEC §7.15: `events/tail { since?, limit }` pages the event log.
+async function eventsTailMethod(params, ctx) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("events/tail params must be { since?, limit? }"),
+        };
+    }
+    const root = await resolveRoot(ctx.root);
+    const log = await readLogEvents(root);
+    if (log === undefined) {
+        return {
+            ok: false,
+            error: {
+                code: -32000,
+                message: "CDX-E903 event log unreadable",
+                data: {
+                    code: "CDX-E903",
+                    remediation: "Fix permissions on .codictator/state/, then retry.",
+                },
+            },
+        };
+    }
+    let since;
+    let limit = 100;
+    if (isRecord(params)) {
+        const rawSince = field(params, "since");
+        if (rawSince !== undefined && typeof rawSince !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("events/tail since must be an event id string"),
+            };
+        }
+        since = typeof rawSince === "string" ? rawSince : undefined;
+        const rawLimit = numberField(params, "limit");
+        if (field(params, "limit") !== undefined) {
+            if (rawLimit === undefined ||
+                !Number.isSafeInteger(rawLimit) ||
+                rawLimit <= 0) {
+                return {
+                    ok: false,
+                    error: invalidParamsError("events/tail limit must be a positive integer"),
+                };
+            }
+            limit = Math.min(rawLimit, 1000);
+        }
+    }
+    let start = 0;
+    if (since !== undefined) {
+        const at = log.events.findIndex((event) => event.id === since);
+        start = at === -1 ? log.events.length : at + 1;
+    }
+    return methodOk({
+        events: log.events.slice(start, start + limit),
+        corrupt: log.corrupt,
+    });
+}
+// SPEC §7.15: `steering/history { sessionId? }` answers injections,
+// optionally for one session.
+async function steeringHistoryMethod(params, ctx) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("steering/history params must be { sessionId? }"),
+        };
+    }
+    let sessionId;
+    if (isRecord(params)) {
+        const raw = field(params, "sessionId");
+        if (raw !== undefined && typeof raw !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("steering/history sessionId must be a string"),
+            };
+        }
+        sessionId = typeof raw === "string" ? raw : undefined;
+    }
+    const root = await resolveRoot(ctx.root);
+    const log = await readLogEvents(root);
+    if (log === undefined) {
+        return methodOk({ injections: [] });
+    }
+    return methodOk({
+        injections: log.events.filter((event) => event.kind === "injection" &&
+            (sessionId === undefined || event.sessionId === sessionId)),
+    });
+}
+// SPEC §7.15: `budget/current` answers per-session bands, or unavailable
+// when no usage applies (§4.6.7 EC-4).
+async function budgetCurrentMethod(params) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("budget/current params must be { sessionId? }"),
+        };
+    }
+    let sessionId = "stdio";
+    if (isRecord(params)) {
+        const raw = field(params, "sessionId");
+        if (raw !== undefined && typeof raw !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("budget/current sessionId must be a string"),
+            };
+        }
+        if (typeof raw === "string" && raw !== "") {
+            sessionId = raw;
+        }
+    }
+    const band = await currentBand(sessionId);
+    return methodOk({
+        available: band.available,
+        status: band.available ? band.band : "unavailable",
+        band: band.band,
+        contextWindow: band.contextWindow,
+        usedTokens: band.usedTokens,
+    });
+}
+// SPEC §7.15 log rows owned here; unknown names return undefined so the
+// caller answers method-not-found.
+export async function dispatchLogMethod(method, params, ctx) {
+    switch (method) {
+        case "events/tail": {
+            return eventsTailMethod(params, ctx);
+        }
+        case "steering/history": {
+            return steeringHistoryMethod(params, ctx);
+        }
+        case "budget/current": {
+            return budgetCurrentMethod(params);
+        }
+        default: {
+            return undefined;
+        }
+    }
+}

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

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

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>;