codictator 0.0.0 → 0.1.3

package/dist/features/packs/enforcers/secret-scan.js

@@ -0,0 +1,173 @@
+// SPEC §4.7.1 core/no-secrets and core/no-secret-reads: the kernel
+// detectors bound to the rules. no-secrets scans every scoped file with
+// redactSecrets, skipping fixture globs; no-secret-reads blocks secret
+// paths themselves and `read:` lines naming one, plus secret reads inside
+// shell sources. Findings carry the rule id the self-test asserts.
+import { analyseShell, isFixturePath, isSecretReadPath, matchDangerousShell, ok, redactSecrets, } from "../../../kernel/index.js";
+import { bindRule, findingFor, readErrorFinding, readLossyText, selectFiles, } from "./binding.js";
+import { baseEnforcer } from "./health-measures.js";
+import { extractShellSources } from "./shell-analyse.js";
+function firstDiffLine(before, after) {
+    const beforeLines = before.split("\n");
+    const afterLines = after.split("\n");
+    const total = Math.max(beforeLines.length, afterLines.length);
+    for (let line = 1; line <= total; line += 1) {
+        if (beforeLines[line - 1] !== afterLines[line - 1]) {
+            return line;
+        }
+    }
+    return 1;
+}
+function excerpt(text, line) {
+    const found = text.split("\n")[line - 1] ?? text.split("\n")[0] ?? "";
+    return found.length > 200 ? `${found.slice(0, 200)}…` : found;
+}
+function toolInputSecretFinding(binding, text, redacted) {
+    const line = firstDiffLine(text, redacted);
+    return findingFor(binding, {
+        line,
+        message: `secret detected in tool input: ${excerpt(redacted, line)}`,
+    });
+}
+// SPEC §4.7.1: the L1 hook scope carries the proposed tool call, not disk
+// files. Both join the same redactSecrets scan: committed files keep their
+// per-path findings, while proposed write content and shell command text
+// are judged as the tool input they are.
+function toolInputTexts(scope) {
+    const texts = [];
+    if (scope.proposedContent !== undefined) {
+        texts.push(scope.proposedContent);
+    }
+    if (scope.shellCommand !== undefined &&
+        scope.shellCommand !== scope.proposedContent) {
+        texts.push(scope.shellCommand);
+    }
+    return texts;
+}
+function secretFinding(binding, file, text, redacted) {
+    const line = firstDiffLine(text, redacted);
+    return findingFor(binding, {
+        path: file,
+        line,
+        message: `secret detected in ${file}: ${excerpt(redacted, line)}`,
+        vars: { path: file, line: String(line) },
+    });
+}
+async function scanScopeFiles(ports, binding, scope) {
+    const findings = [];
+    for (const file of selectFiles(scope.files, binding.scopeGlobs)) {
+        if (isFixturePath(file)) {
+            continue;
+        }
+        const loaded = await readLossyText(ports.fs, file);
+        if (!loaded.ok) {
+            findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+            continue;
+        }
+        const redacted = redactSecrets(loaded.value.text);
+        if (redacted !== loaded.value.text) {
+            findings.push(secretFinding(binding, file, loaded.value.text, redacted));
+        }
+    }
+    return findings;
+}
+function scanToolInput(binding, scope) {
+    const findings = [];
+    for (const text of toolInputTexts(scope)) {
+        const redacted = redactSecrets(text);
+        if (redacted !== text) {
+            findings.push(toolInputSecretFinding(binding, text, redacted));
+        }
+    }
+    return findings;
+}
+export function resolveNoSecrets(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = await scanScopeFiles(ports, binding, ctx.scope);
+        findings.push(...scanToolInput(binding, ctx.scope));
+        return findings;
+    }));
+}
+function readLineTarget(line) {
+    const trimmed = line.trimStart();
+    if (!trimmed.toLowerCase().startsWith("read:")) {
+        return undefined;
+    }
+    const target = trimmed.slice("read:".length).trim();
+    return target === "" ? undefined : target;
+}
+// SPEC §4.7.1 L1: the hook scope carries the lexical read target (the
+// tool file path), never disk content. It judges by path shape alone —
+// no disk read — so `files: []` stays empty while secret-shaped reads
+// still block pre-tool.
+function checkProposedSecretReads(binding, scope) {
+    const findings = [];
+    for (const target of [...(scope.proposedPaths ?? [])].sort()) {
+        if (isSecretReadPath(target)) {
+            findings.push(findingFor(binding, {
+                path: "tool input",
+                message: `secret material must not reach the agent context: ${target}`,
+                vars: { path: "tool input" },
+            }));
+        }
+    }
+    return findings;
+}
+function scanReadLineTargets(binding, file, text, findings) {
+    for (const line of text.split("\n")) {
+        const target = readLineTarget(line);
+        if (target !== undefined && isSecretReadPath(target)) {
+            findings.push(findingFor(binding, {
+                path: file,
+                message: `secret material must not reach the agent context: ${target}`,
+                vars: { path: file },
+            }));
+        }
+    }
+}
+function scanShellSecretReads(binding, file, text, findings) {
+    for (const source of extractShellSources(text, file)) {
+        const parsed = analyseShell(source);
+        if (!parsed.ok) {
+            continue;
+        }
+        for (const violation of matchDangerousShell(parsed.value)) {
+            if (violation.class !== "secret-read") {
+                continue;
+            }
+            findings.push(findingFor(binding, {
+                path: file,
+                message: `shell command reads secret material in ${file}: ${redactSecrets(violation.raw)}`,
+                vars: { path: file },
+            }));
+        }
+    }
+}
+async function scanFileSecretReads(ports, binding, file, findings) {
+    if (isSecretReadPath(file)) {
+        findings.push(findingFor(binding, {
+            path: file,
+            message: `secret material must not reach the agent context: ${file}`,
+            vars: { path: file },
+        }));
+    }
+    const loaded = await readLossyText(ports.fs, file);
+    if (!loaded.ok) {
+        findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+        return;
+    }
+    scanReadLineTargets(binding, file, loaded.value.text, findings);
+    scanShellSecretReads(binding, file, loaded.value.text, findings);
+}
+export function resolveNoSecretReads(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            await scanFileSecretReads(ports, binding, file, findings);
+        }
+        findings.push(...checkProposedSecretReads(binding, ctx.scope));
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/shell-analyse.d.ts

@@ -0,0 +1,14 @@
+import { type Ports } from "../../../kernel/index.ts";
+import type { CheckContext, Finding } from "../../engine/index.ts";
+import type { PackRule } from "../index.ts";
+import type { EnforcerDecl } from "../manifest.ts";
+export declare function extractShellSources(content: string, path: string): Array<string>;
+export declare function resolveDangerousShell(decl: EnforcerDecl, rule: PackRule, ports: Ports): {
+    ok: true;
+    value: {
+        id: string;
+        kinds: readonly ("compact" | "post-tool" | "pre-tool" | "prompt" | "review" | "scheduled" | "startup")[];
+        budgetMs: number;
+        check: (ctx: CheckContext) => Promise<Finding[]>;
+    };
+};

package/dist/features/packs/enforcers/shell-analyse.js

@@ -0,0 +1,105 @@
+// SPEC §4.7.2 core/dangerous-shell: the kernel shell analyser bound to
+// the rule. Shell text arrives as `run:` lines of the scanned files (the
+// hook runtime feeds tool commands this way); whole files with a shell
+// extension are analysed as scripts. Findings carry the rule id the
+// self-test asserts (CDX-E212/E213).
+import { analyseShell, matchDangerousShell, redactSecrets, } from "../../../kernel/index.js";
+import { bindRule, findingFor, readErrorFinding, readLossyText, selectFiles, } from "./binding.js";
+const SCRIPT_EXTENSIONS = [
+    ".sh",
+    ".bash",
+    ".zsh",
+    ".ksh",
+    ".ps1",
+    ".cmd",
+    ".bat",
+];
+function isScriptFile(path) {
+    const lowered = path.toLowerCase();
+    return SCRIPT_EXTENSIONS.some((extension) => lowered.endsWith(extension));
+}
+// SPEC §4.7.2: one shell source per `run:` line, or the whole file for a
+// shell script. Other files carry no shell text, so they yield nothing.
+export function extractShellSources(content, path) {
+    if (isScriptFile(path)) {
+        return content.length === 0 ? [] : [content];
+    }
+    const sources = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trimStart();
+        if (trimmed.toLowerCase().startsWith("run:")) {
+            const command = trimmed.slice("run:".length).trim();
+            if (command !== "") {
+                sources.push(command);
+            }
+        }
+    }
+    return sources;
+}
+// SPEC §4.7.2: the L1 hook scope carries the shell command text itself.
+// An unparseable command blocks CDX-E306 fail-closed; every deny-class
+// match blocks with the command redacted, like the file sources below.
+function checkHookCommand(binding, scope) {
+    const findings = [];
+    const command = scope.shellCommand;
+    if (command === undefined || command === "") {
+        return findings;
+    }
+    const parsed = analyseShell(command);
+    if (!parsed.ok) {
+        findings.push(findingFor(binding, {
+            code: parsed.error.code,
+            message: "shell command in tool input is unparseable",
+            vars: { path: "tool input" },
+        }));
+        return findings;
+    }
+    for (const violation of matchDangerousShell(parsed.value)) {
+        findings.push(findingFor(binding, {
+            message: `${violation.detail} in tool input: ${redactSecrets(violation.raw)}`,
+            vars: { path: "tool input" },
+        }));
+    }
+    return findings;
+}
+export function resolveDangerousShell(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return {
+        ok: true,
+        value: {
+            id: rule.id,
+            kinds: binding.triggers,
+            budgetMs: decl.budgetMs,
+            check: async (ctx) => {
+                const findings = checkHookCommand(binding, ctx.scope);
+                for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+                    const loaded = await readLossyText(ports.fs, file);
+                    if (!loaded.ok) {
+                        findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+                        continue;
+                    }
+                    for (const source of extractShellSources(loaded.value.text, file)) {
+                        const parsed = analyseShell(source);
+                        if (!parsed.ok) {
+                            findings.push(findingFor(binding, {
+                                path: file,
+                                code: parsed.error.code,
+                                message: `shell command in ${file} is unparseable`,
+                                vars: { path: file },
+                            }));
+                            continue;
+                        }
+                        for (const violation of matchDangerousShell(parsed.value)) {
+                            findings.push(findingFor(binding, {
+                                path: file,
+                                message: `${violation.detail} in ${file}: ${redactSecrets(violation.raw)}`,
+                                vars: { path: file },
+                            }));
+                        }
+                    }
+                }
+                return findings;
+            },
+        },
+    };
+}

package/dist/features/packs/enforcers/sizes.d.ts

@@ -0,0 +1,10 @@
+import type { Ports } from "../../../kernel/index.ts";
+import { type Result } from "../../../kernel/index.ts";
+import type { CheckContext, Finding } from "../../engine/index.ts";
+import { type RuleBinding } from "./binding.ts";
+export interface SizeConfig {
+    readonly maxLines: number | undefined;
+    readonly maxBytes: number | undefined;
+}
+export declare function narrowSizeArgs(declId: string, binding: RuleBinding, args: unknown): Result<SizeConfig>;
+export declare function checkSize(ports: Ports, binding: RuleBinding, config: SizeConfig, ctx: CheckContext): Promise<Array<Finding>>;

package/dist/features/packs/enforcers/sizes.js

@@ -0,0 +1,82 @@
+// SPEC §4.4.6 file-size: source files stay under maxLines lines and every
+// committed file under maxBytes bytes (§5.6). Limits bind from the pack
+// args first, then the rule tunables; a kind with neither limit fails the
+// load instead of checking nothing.
+import { err, isFixturePath, ok } from "../../../kernel/index.js";
+import { field } from "../manifest.js";
+import { argsRecord, bindingError, findingFor, isLockfilePath, isTestPath, nonNegativeInteger, readErrorFinding, readLossyText, selectFiles, tunableNumber, } from "./binding.js";
+function countLines(text) {
+    if (text === "") {
+        return 0;
+    }
+    const parts = text.split("\n");
+    const last = parts[parts.length - 1];
+    return parts.length - (last === "" ? 1 : 0);
+}
+export function narrowSizeArgs(declId, binding, args) {
+    const record = argsRecord(declId, args);
+    if (!record.ok) {
+        return err(record.error);
+    }
+    const argLines = field(record.value, "maxLines");
+    const argBytes = field(record.value, "maxBytes");
+    if (argLines !== undefined && !nonNegativeInteger(argLines)) {
+        return bindingError(declId, "needs a non-negative integer maxLines in args");
+    }
+    if (argBytes !== undefined && !nonNegativeInteger(argBytes)) {
+        return bindingError(declId, "needs a non-negative integer maxBytes in args");
+    }
+    const maxLines = (nonNegativeInteger(argLines) ? argLines : undefined) ??
+        tunableNumber(binding, "maxLines");
+    const maxBytes = (nonNegativeInteger(argBytes) ? argBytes : undefined) ??
+        tunableNumber(binding, "maxBytes");
+    if (maxLines === undefined && maxBytes === undefined) {
+        return bindingError(declId, "needs a maxLines or maxBytes limit");
+    }
+    return ok({ maxLines, maxBytes });
+}
+export async function checkSize(ports, binding, config, ctx) {
+    const findings = [];
+    for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+        if (binding.ruleId !== "core/max-file-bytes" &&
+            (isFixturePath(file) || isLockfilePath(file) || isTestPath(file))) {
+            continue;
+        }
+        if (binding.ruleId === "core/file-size" &&
+            (file.endsWith(".md") || file.endsWith(".json"))) {
+            continue;
+        }
+        if (binding.ruleId === "core/doc-size" && !file.endsWith(".md")) {
+            continue;
+        }
+        const loaded = await readLossyText(ports.fs, file);
+        if (!loaded.ok) {
+            findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+            continue;
+        }
+        if (config.maxBytes !== undefined && loaded.value.bytes > config.maxBytes) {
+            findings.push(findingFor(binding, {
+                path: file,
+                message: `file over the byte limit: ${file}`,
+                vars: {
+                    path: file,
+                    limit: String(config.maxBytes),
+                    value: String(loaded.value.bytes),
+                },
+            }));
+        }
+        const lines = countLines(loaded.value.text);
+        if (config.maxLines !== undefined && lines > config.maxLines) {
+            findings.push(findingFor(binding, {
+                path: file,
+                message: `file over the line limit: ${file}`,
+                vars: {
+                    path: file,
+                    limit: String(config.maxLines),
+                    value: String(lines),
+                },
+            }));
+        }
+    }
+    return findings;
+}

package/dist/features/packs/enforcers/steering-guards.d.ts

@@ -0,0 +1,11 @@
+import type { Ports } from "../../../kernel/index.ts";
+import { type Result } from "../../../kernel/index.ts";
+import type { Enforcer } from "../../engine/index.ts";
+import type { PackRule } from "../index.ts";
+import type { EnforcerDecl } from "../manifest.ts";
+export declare function resolveContextSoftBand(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveContextHardBand(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveSessionToolCallLimit(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveReadDedupe(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveGraphBeforeScan(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveMcpDeclared(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

package/dist/features/packs/enforcers/steering-guards.js

@@ -0,0 +1,162 @@
+import { ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, selectFiles, tunableNumber } from "./binding.js";
+import { baseEnforcer, isMarkerFile, loadScopeText, parseMarkerInt, scopeMarkerTexts, } from "./health-measures.js";
+function parsePercent(markers, key) {
+    const raw = markers.get(key) ?? "";
+    const match = raw.match(/(\d+(?:\.\d+)?)\s*%/);
+    if (match === null) {
+        return undefined;
+    }
+    const parsed = Number.parseFloat(match[1] ?? "");
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function checkpointed(markers) {
+    return (markers.get("checkpoint") ?? "none") !== "none";
+}
+// SPEC §4.6.4 core/context-soft-band: usage at or past softPercent with no
+// checkpoint summary advises; below the band, or already checkpointed,
+// stays quiet.
+export function resolveContextSoftBand(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const soft = tunableNumber(binding, "softPercent") ?? 60;
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const { file, markers } of await scopeMarkerTexts(ports, binding, ctx, findings)) {
+            const percent = parsePercent(markers, "context-used");
+            if (percent !== undefined &&
+                percent >= soft &&
+                !checkpointed(markers)) {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `context at ${String(percent)}% is past the ${String(soft)}% soft band with no checkpoint`,
+                    vars: {
+                        path: file,
+                        detail: `${String(percent)}% with no checkpoint`,
+                        limit: String(soft),
+                    },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.4 core/context-hard-band: usage at or past hardPercent with no
+// forced checkpoint flags checkpointRequired.
+export function resolveContextHardBand(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const hard = tunableNumber(binding, "hardPercent") ?? 75;
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const { file, markers } of await scopeMarkerTexts(ports, binding, ctx, findings)) {
+            const percent = parsePercent(markers, "context-used");
+            if (percent !== undefined &&
+                percent >= hard &&
+                !checkpointed(markers)) {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `context at ${String(percent)}% is past the ${String(hard)}% hard band with no forced checkpoint`,
+                    vars: {
+                        path: file,
+                        detail: `${String(percent)}% with no checkpoint`,
+                        limit: String(hard),
+                    },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.4 core/session-tool-call-limit: calls past maxToolCalls flag.
+export function resolveSessionToolCallLimit(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const cap = tunableNumber(binding, "maxToolCalls") ?? 300;
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const { file, markers } of await scopeMarkerTexts(ports, binding, ctx, findings)) {
+            const calls = parseMarkerInt(markers, "tool-calls");
+            const limit = parseMarkerInt(markers, "limit") ?? cap;
+            if (calls !== undefined && calls > limit) {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `session made ${String(calls)} tool calls past the ${String(limit)} call limit`,
+                    vars: { path: file, limit: String(limit) },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.5 EC-10 core/read-dedupe: the same file twice flags; a first
+// read, or reads of different files, stays quiet.
+export function resolveReadDedupe(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined || !isMarkerFile(file)) {
+                continue;
+            }
+            const reads = [];
+            for (const line of text.split("\n")) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith("- ")) {
+                    reads.push(trimmed.slice(2).trim());
+                }
+            }
+            const seen = new Set();
+            for (const read of reads) {
+                if (seen.has(read)) {
+                    findings.push(findingFor(binding, {
+                        path: file,
+                        message: `repeat read of ${read} in one session`,
+                        vars: { path: read },
+                    }));
+                    break;
+                }
+                seen.add(read);
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.5 core/graph-before-scan: a full-repo scan while the graph is
+// absent violates the graph-first order; a graph-guided scan, or one with
+// the graph present, passes.
+export function resolveGraphBeforeScan(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const { file, markers } of await scopeMarkerTexts(ports, binding, ctx, findings)) {
+            const scan = markers.get("scan") ?? "";
+            const graph = markers.get("knowledge-graph") ?? "";
+            if (scan.includes("full-repo") && graph !== "present") {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: "full-repo scan with no knowledge graph on disk",
+                    vars: { path: file },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.5 core/mcp-declared: a tool call to a server the markers flag
+// as undeclared violates; a declared one passes.
+export function resolveMcpDeclared(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const { file, markers } of await scopeMarkerTexts(ports, binding, ctx, findings)) {
+            if ((markers.get("declared") ?? "false") !== "true") {
+                const tool = markers.get("tool") ?? "unknown server";
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `tool call to undeclared MCP server ${tool}`,
+                    vars: { path: file, detail: tool },
+                }));
+            }
+        }
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/testing-guards.d.ts

@@ -0,0 +1,10 @@
+import type { Ports } from "../../../kernel/index.ts";
+import { type Result } from "../../../kernel/index.ts";
+import type { Enforcer } from "../../engine/index.ts";
+import type { PackRule } from "../index.ts";
+import type { EnforcerDecl } from "../manifest.ts";
+export declare function resolveSpecTrace(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveRedBeforeGreen(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveTestKindsByScenario(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveRegressionTestForFix(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveCoverageFloor(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;