codictator 0.0.0 → 0.1.3

package/dist/cli/evaluate.js

@@ -0,0 +1,213 @@
+// SPEC §4.19.2 + §4.3.3: trigger evaluation for `verify`. Resolves the
+// scope from the verify flags, loads the always-on core pack plus the
+// builtin language packs config packs name, and runs the engine over the
+// scope. Findings merge with the drift findings in inspect.ts; pack load
+// failures fail closed with their own code. Custom packs stay out until
+// their acceptance flow lands (core/custom-pack-selftest is red).
+import { createEngine } from "../features/engine/index.js";
+import { isBuiltinPackId, loadBuiltinPack, resolveManifestEnforcers, } from "../features/packs/index.js";
+import { err, isFixturePath, ok } from "../kernel/index.js";
+// SPEC §4.3.2: the layer flag selects the trigger family. L1 and L2 are
+// the local gate (pre-tool); L3 and above review the change as CI would.
+export function triggerForLayer(layer) {
+    return layer === "L3" || layer === "L4" || layer === "L5"
+        ? "review"
+        : "pre-tool";
+}
+function sortedUnique(files) {
+    return [...new Set(files)].sort();
+}
+function splitLines(output) {
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+}
+async function runGitList(ports, argv) {
+    const ran = await ports.proc.run(argv, {
+        cwd: ports.root,
+        env: {},
+        timeoutMs: 30000,
+        maxOutputBytes: 8 * 1024 * 1024,
+    });
+    if (ran.timedOut || ran.truncated || ran.code !== 0) {
+        return err({
+            code: "CDX-E703",
+            message: `git ${argv[1] ?? ""} failed while resolving the verify scope`,
+            remediation: "Run inside a git repository with git on PATH.",
+        });
+    }
+    return { ok: true, value: splitLines(ran.stdout) };
+}
+// SPEC §4.19.2: --staged evaluates the staged tree, --base/--head the
+// range, --all and the bare command the tracked tree plus staged edits.
+// SPEC §4.4.1 + §10.2: pack self-test fixtures are rule test data, judged
+// by `pack test` and the red suite, not by verify. A committed violating
+// fixture would flag on every run and can never be "fixed" without breaking
+// the self-test, so every scope here excludes fixture dirs.
+function withoutFixtures(files) {
+    return files.filter((file) => !isFixturePath(file));
+}
+export async function resolveVerifyScope(ports, flags) {
+    const trigger = triggerForLayer(flags.layer);
+    if (flags.staged) {
+        const staged = await ports.git.stagedFiles();
+        if (!staged.ok) {
+            return err(staged.error);
+        }
+        const files = withoutFixtures(staged.value);
+        return ok({
+            trigger,
+            files,
+            note: `staged ${String(files.length)} files`,
+        });
+    }
+    if (flags.base !== undefined && flags.head !== undefined) {
+        const ranged = await runGitList(ports, [
+            "git",
+            "diff",
+            "--name-only",
+            flags.base,
+            flags.head,
+        ]);
+        if (!ranged.ok) {
+            return err(ranged.error);
+        }
+        const files = withoutFixtures(ranged.value);
+        return ok({
+            trigger,
+            files,
+            note: `range ${flags.base}..${flags.head}`,
+        });
+    }
+    const tracked = await runGitList(ports, ["git", "ls-files"]);
+    if (!tracked.ok) {
+        return err(tracked.error);
+    }
+    const staged = await ports.git.stagedFiles();
+    if (!staged.ok) {
+        return err(staged.error);
+    }
+    return ok({
+        trigger,
+        files: sortedUnique(withoutFixtures([...tracked.value, ...staged.value])),
+        note: "tracked tree",
+    });
+}
+// SPEC §4.3.6: one verify evaluation reads each scope file once. Enforcers
+// close over the same ports, so without sharing a full-tree scope costs one
+// sweep per enforcer and every guard exceeds its budget under disk
+// contention. This memo shares in-flight and completed reads across the
+// evaluation; writes, appends and removals invalidate the path. Results are
+// copies, so a guard can never mutate another guard's bytes.
+function sharedRead(inner, reads) {
+    return (path) => {
+        const hit = reads.get(path);
+        if (hit !== undefined) {
+            return hit.then((result) => result.ok ? { ok: true, value: result.value.slice() } : result);
+        }
+        const pending = inner.read(path);
+        reads.set(path, pending);
+        return pending.then((result) => result.ok ? { ok: true, value: result.value.slice() } : result);
+    };
+}
+function sharedReadText(inner, texts) {
+    return (path) => {
+        const hit = texts.get(path);
+        if (hit !== undefined) {
+            return hit;
+        }
+        const pending = inner.readText(path);
+        texts.set(path, pending);
+        return pending;
+    };
+}
+function sharedRealpath(inner, reals) {
+    return (path) => {
+        const hit = reals.get(path);
+        if (hit !== undefined) {
+            return hit;
+        }
+        const pending = inner.realpath(path);
+        reals.set(path, pending);
+        return pending;
+    };
+}
+function sharedReads(inner) {
+    const reads = new Map();
+    const texts = new Map();
+    const reals = new Map();
+    const drop = (path) => {
+        reads.delete(path);
+        texts.delete(path);
+        reals.delete(path);
+    };
+    const invalidate = (done, path) => done.then((result) => {
+        if (result.ok) {
+            drop(path);
+        }
+        return result;
+    });
+    return {
+        read: sharedRead(inner, reads),
+        readText: sharedReadText(inner, texts),
+        write: (path, content) => invalidate(inner.write(path, content), path),
+        append: (path, content) => invalidate(inner.append(path, content), path),
+        remove: (path) => invalidate(inner.remove(path), path),
+        stat: (path) => inner.stat(path),
+        list: (dir) => inner.list(dir),
+        glob: (pattern, dir) => inner.glob(pattern, dir),
+        exists: (path) => inner.exists(path),
+        realpath: sharedRealpath(inner, reals),
+    };
+}
+// SPEC §4.4.2: the core pack is always loaded; language packs join from
+// config.packs order. A config that names core does not load it twice.
+// Every pack resolves against the caller's ports; the verify caller shares
+// one read cache across them, so scope files read repo-relatively (§4.1.1)
+// exactly once per run.
+export async function loadEvalEnforcers(ports, packIds, excludeRuleIds = new Set()) {
+    const core = await loadBuiltinPack("core");
+    if (!core.ok) {
+        return err(core.error);
+    }
+    const manifests = [core.value.manifest];
+    for (const id of packIds) {
+        if (id === "core" || !isBuiltinPackId(id)) {
+            continue;
+        }
+        const loaded = await loadBuiltinPack(id);
+        if (!loaded.ok) {
+            return err(loaded.error);
+        }
+        manifests.push(loaded.value.manifest);
+    }
+    const enforcers = [];
+    for (const manifest of manifests) {
+        const resolved = resolveManifestEnforcers(manifest, ports);
+        if (!resolved.ok) {
+            return err(resolved.error);
+        }
+        enforcers.push(...resolved.value);
+    }
+    return ok(enforcers.filter((enforcer) => !excludeRuleIds.has(enforcer.id)));
+}
+export async function evaluateScope(ports, packIds, scope, now, configHash, 
+// BUG-0014: diff-scope callers pass the diff-unsound rule ids (the gate
+// subset); tree callers omit it and judge everything.
+options = {}) {
+    const cached = { ...ports, fs: sharedReads(ports.fs) };
+    const excluded = options.excludeRuleIds ?? new Set();
+    const loaded = await loadEvalEnforcers(cached, packIds, excluded);
+    if (!loaded.ok) {
+        return err(loaded.error);
+    }
+    const engine = createEngine(loaded.value, { configHash });
+    const verdict = await engine.evaluate(scope.trigger, {
+        files: [...scope.files],
+        ...(scope.proposedContent === undefined || scope.proposedContent === ""
+            ? {}
+            : { proposedContent: scope.proposedContent }),
+    }, now);
+    return ok([...verdict.findings]);
+}

package/dist/cli/gate-scope.d.ts

@@ -0,0 +1,11 @@
+import type { Finding, Result } from "../kernel/index.ts";
+import type { CommandPorts } from "./shared.ts";
+export declare const GATE_DIFF_UNSOUND_RULES: ReadonlySet<string>;
+export declare function isGateDiffSound(ruleId: string): boolean;
+export interface GateScope {
+    readonly files: ReadonlyArray<string>;
+    readonly note: string;
+    readonly proposedContent?: string;
+}
+export declare function addedLines(diff: string): string;
+export declare function evaluateGateScope(ports: CommandPorts, packIds: ReadonlyArray<string>, scope: GateScope, now: string, configHash: string): Promise<Result<Array<Finding>>>;

package/dist/cli/gate-scope.js

@@ -0,0 +1,93 @@
+// BUG-0014 + SPEC §4.3.2: the gate rule subset over diff scopes. A gate
+// judges a staged or pushed diff, not the tree, so enforcers that need
+// whole-tree visibility (core/dead-code: an export looks unused when its
+// importers are outside the diff) or test-title inputs (core/spec-trace:
+// an empty rule scope selects every scoped file, so every normally
+// commented file flags) are unsound there. They stay on the human
+// `review` command over the tree; every other rule is sound on a diff.
+// The phase-5 finer trigger is this rule subset, not a new trigger name.
+import { err, ok, stableStringify } from "../kernel/index.js";
+import { evaluateScope } from "./evaluate.js";
+export const GATE_DIFF_UNSOUND_RULES = new Set([
+    "core/dead-code",
+    "core/spec-trace",
+]);
+// BUG-0014: gates select the diff-sound subset; the tree review keeps all.
+export function isGateDiffSound(ruleId) {
+    return !GATE_DIFF_UNSOUND_RULES.has(ruleId);
+}
+// BUG-0014: canonical-key order, deterministic across OSes (§4.3.6 EC-12).
+// One string comparison replaces the engine's field-by-field order, so the
+// merge stays under the complexity floor without its own ordering rules.
+function compareGateFindings(a, b) {
+    const left = gateFindingKey(a);
+    const right = gateFindingKey(b);
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
+function gateFindingKey(finding) {
+    return stableStringify({
+        ruleId: finding.ruleId,
+        path: finding.path ?? "",
+        line: finding.line ?? 0,
+        code: finding.code ?? "",
+        message: finding.message,
+    });
+}
+// BUG-0014: the two gate legs overlap on rules with both triggers
+// (core/no-secrets), so the merge dedupes exact findings.
+function mergeGateFindings(first, second) {
+    const seen = new Set();
+    const merged = [];
+    for (const finding of [...first, ...second]) {
+        const key = gateFindingKey(finding);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        merged.push(finding);
+    }
+    return merged.sort(compareGateFindings);
+}
+// BUG-0022 + SPEC §4.7.1: the L3 gate judges added lines only, so a commit
+// deleting a flagged literal passes while staging one still blocks. A diff
+// carries its removed lines as `-` rows; scanning the raw diff would match
+// those and make the removal uncommittable.
+export function addedLines(diff) {
+    return diff
+        .split("\n")
+        .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
+        .map((line) => line.slice(1))
+        .join("\n");
+}
+// BUG-0014 + SPEC §4.3.2: the gate evaluation over a diff scope. The
+// pre-tool leg keeps today's fail-closed local verdict byte for byte; the
+// review leg adds the diff-sound review subset over the same files, so the
+// gate no longer accepts the coverage loss the pre-tool-only mitigation
+// took. The diff-unsound rules never run here, whatever their triggers say.
+export async function evaluateGateScope(ports, packIds, scope, now, configHash) {
+    const input = scope.proposedContent === undefined || scope.proposedContent === ""
+        ? {}
+        : { proposedContent: scope.proposedContent };
+    const local = await evaluateScope(ports, packIds, {
+        trigger: "pre-tool",
+        files: [...scope.files],
+        note: scope.note,
+        ...input,
+    }, now, configHash);
+    if (!local.ok) {
+        return err(local.error);
+    }
+    const review = await evaluateScope(ports, packIds, {
+        trigger: "review",
+        files: [...scope.files],
+        note: scope.note,
+        ...input,
+    }, now, configHash, { excludeRuleIds: GATE_DIFF_UNSOUND_RULES });
+    if (!review.ok) {
+        return err(review.error);
+    }
+    return ok(mergeGateFindings(local.value, review.value));
+}

package/dist/cli/git-hook.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleGitHook(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/git-hook.js

@@ -0,0 +1,184 @@
+// SPEC §4.14.4 + §4.7: the git-hook engine path. Installed hooks exec
+// the launcher as `run.mjs git <hook>`; the launcher routes the `git` word
+// here (SPEC §4.19.3). pre-commit and pre-push evaluate the staged or pushed
+// the change with the gate rule subset `verify` loads over staged scopes —
+// new scope plumbing, no new detection logic. commit-msg appends
+// the Codictator-L3 trailer §4.14.2 checks at L4.
+import path from "node:path";
+import { ENGINE_VERSION, HOOK_MARKER } from "../features/config/index.js";
+import { err, makeError, ok, readHostText, writeHostText, } from "../kernel/index.js";
+import { addedLines, evaluateGateScope } from "./gate-scope.js";
+import { printFinding } from "./inspect.js";
+import { commandEnv, fail, loadRepoConfig, MIN_NODE_MAJOR, needRoot, nodeMajor, nodeTooOldMessage, printHuman, printJson, reportError, usageError, } from "./shared.js";
+const GIT_TIMEOUT_MS = 30000;
+const GIT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+async function runGitText(ports, argv) {
+    const ran = await ports.proc.run(argv, {
+        cwd: ports.root,
+        env: {},
+        timeoutMs: GIT_TIMEOUT_MS,
+        maxOutputBytes: GIT_MAX_OUTPUT_BYTES,
+    });
+    if (ran.timedOut || ran.truncated || ran.code !== 0) {
+        return err(makeError("CDX-E703", `git ${argv[1] ?? ""} failed while reading the hook scope`, "Run inside a git repository with git on PATH."));
+    }
+    return ok(ran.stdout);
+}
+function emitGitVerdict(req, hook, findings) {
+    if (req.json) {
+        printJson({
+            hook,
+            decision: findings.length === 0 ? "allow" : "block",
+            findings,
+        });
+    }
+    else {
+        for (const finding of findings) {
+            printFinding(finding, req.quiet);
+        }
+        if (findings.length === 0) {
+            printHuman(`${hook}: pass`, req.quiet);
+        }
+        else {
+            printHuman(`${hook}: blocked (${String(findings.length)} findings)`, req.quiet);
+        }
+    }
+    return ok(findings.length === 0 ? 0 : 1);
+}
+async function evaluateGitChange(ports, req, hook, packIds, files, content, now, configHash) {
+    // BUG-0014 + SPEC §4.3.2: gates judge pre-tool plus the diff-sound
+    // review subset, the phase-5 finer trigger as a rule subset. The
+    // diff-unsound rules (spec-trace, dead-code) stay on the human
+    // `review` command over the tree; a review trigger here once blocked
+    // every normally-commented file.
+    const evaluated = await evaluateGateScope(ports, packIds, {
+        files: [...files],
+        note: hook,
+        ...(content === "" ? {} : { proposedContent: addedLines(content) }),
+    }, now, configHash);
+    if (!evaluated.ok) {
+        return reportError(evaluated.error, req.json);
+    }
+    return emitGitVerdict(req, hook, evaluated.value);
+}
+// SPEC §4.7.1: L3 scans staged content. The staged file list scopes the
+// disk reads while the staged diff rides as proposed content, so a secret
+// staged but not yet matching the worktree still blocks.
+async function runPreCommit(req, ports, packIds, now, configHash) {
+    const staged = await ports.git.stagedFiles();
+    if (!staged.ok) {
+        return reportError(staged.error, req.json);
+    }
+    if (staged.value.length === 0) {
+        return emitGitVerdict(req, "pre-commit", []);
+    }
+    const diff = await runGitText(ports, ["git", "diff", "--cached", "--"]);
+    if (!diff.ok) {
+        return reportError(diff.error, req.json);
+    }
+    return evaluateGitChange(ports, req, "pre-commit", packIds, staged.value, diff.value, now, configHash);
+}
+// SPEC §4.14.4: git hands commit-msg the COMMIT_EDITMSG path, absolute in a
+// linked worktree (under the main repo's .git/worktrees/<name>/ dir, outside
+// the worktree root) but relative to the repo root (`.git/COMMIT_EDITMSG`)
+// in the main worktree. The confined Fs port rejects absolute paths
+// (CDX-E701), so the hook uses kernel-owned host I/O — which itself
+// requires absolute paths — resolving a relative handoff against the
+// invocation cwd first; an unreadable or unwritable message file blocks
+// fail-closed.
+async function runCommitMsg(req, configHash) {
+    if (req.args.length !== 2 || req.args[1] === undefined) {
+        return usageError("usage: codictator git commit-msg <file>");
+    }
+    const raw = req.args[1];
+    const file = path.isAbsolute(raw) ? raw : path.resolve(req.cwd, raw);
+    const trailer = `Codictator-L3: ${configHash.slice(0, 12)}`;
+    const read = await readHostText(file);
+    if (!read.ok) {
+        return reportError(read.error, req.json);
+    }
+    if (read.value.split("\n").some((line) => line.startsWith("Codictator-L3: "))) {
+        return ok(0);
+    }
+    const base = read.value.endsWith("\n") ? read.value : `${read.value}\n`;
+    const wrote = await writeHostText(file, `${base}\n${trailer}\n`);
+    if (!wrote.ok) {
+        return reportError(wrote.error, req.json);
+    }
+    return ok(0);
+}
+// SPEC §4.3.2: pre-push judges the `@{push}..HEAD` diff. Without an
+// upstream there is no pushed range; the commits were gated at commit time.
+async function runPrePush(req, ports, packIds, now, configHash) {
+    const upstream = await runGitText(ports, [
+        "git",
+        "rev-parse",
+        "--verify",
+        "@{push}",
+    ]);
+    if (!upstream.ok || upstream.value.trim() === "") {
+        return emitGitVerdict(req, "pre-push", []);
+    }
+    const base = upstream.value.trim();
+    const names = await runGitText(ports, [
+        "git",
+        "diff",
+        "--name-only",
+        base,
+        "HEAD",
+        "--",
+    ]);
+    if (!names.ok) {
+        return reportError(names.error, req.json);
+    }
+    const diff = await runGitText(ports, ["git", "diff", base, "HEAD", "--"]);
+    if (!diff.ok) {
+        return reportError(diff.error, req.json);
+    }
+    const files = names.value
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    return evaluateGitChange(ports, req, "pre-push", packIds, files, diff.value, now, configHash);
+}
+// SPEC §4.2.3 with §4.19.3, same shape as the L1 runtime hookEnv: the
+// launcher marks this engine process CODICTATOR_HOOK=1, which authorizes
+// evaluation instead of refusing it. Only the launcher's own marker is
+// hidden, so a foreign agent marker still refuses CDX-E107 in loadConfig.
+function hookEnv(inner) {
+    return {
+        get: (name) => name === HOOK_MARKER ? undefined : inner.get(name),
+    };
+}
+// SPEC §4.19.3: the `git` word entry. Args arrive without the word itself:
+// `pre-commit`, `commit-msg <file>` or `pre-push`. Unknown hooks are usage
+// errors (exit 2); every evaluation failure blocks.
+export async function handleGitHook(req) {
+    const version = req.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        return fail("CDX-E002", nodeTooOldMessage(version), "Install a newer Node, then retry the hook.", req.json);
+    }
+    const hook = req.args[0] ?? "";
+    if (hook !== "pre-commit" && hook !== "commit-msg" && hook !== "pre-push") {
+        return usageError("usage: codictator git <pre-commit|commit-msg <file>|pre-push>");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const configured = await loadRepoConfig(root, hookEnv(commandEnv()), req.engineVersion ?? ENGINE_VERSION);
+    if (!configured.ok) {
+        return fail(configured.error.code, configured.error.message, "Fix .codictator/config.json, then retry.", req.json);
+    }
+    const ports = configured.value.ports;
+    const packIds = configured.value.effective.config.packs.map((entry) => entry.id);
+    const now = ports.clock.now();
+    const configHash = configured.value.effective.configHash;
+    if (hook === "commit-msg") {
+        return runCommitMsg(req, configHash);
+    }
+    if (hook === "pre-push") {
+        return runPrePush(req, ports, packIds, now, configHash);
+    }
+    return runPreCommit(req, ports, packIds, now, configHash);
+}

package/dist/cli/guardrail.d.ts

@@ -0,0 +1,5 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleRegen(req: CommandRequest): Promise<Result<number>>;
+export declare function handleInstallHooks(req: CommandRequest): Promise<Result<number>>;
+export declare function handleUninstall(req: CommandRequest): Promise<Result<number>>;