codictator 0.0.0 → 0.1.3

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

@@ -0,0 +1,180 @@
+import { isFixturePath, ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, selectFiles, tunableStringList, } from "./binding.js";
+import { baseEnforcer, isMarkerFile, loadScopeText, parseMarkerInt, parseMarkers, } from "./health-measures.js";
+const ROOT_DOCS = new Set([
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+]);
+// Doc rules judge markdown prose and the fixture measure reports. Other
+// files carry no doc signals; reading them only pays a parse for nothing
+// and invents findings from code identifiers (a doc count in `utf8Bytes`,
+// a link-shaped string in a test fake).
+export function isDocScopeFile(file) {
+    return isMarkerFile(file) || file.toLowerCase().endsWith(".md");
+}
+// SPEC §5.10 core/doc-placement: a markdown file outside its placed
+// locations flags. Mirrors the records guard (SPEC §4.9.2); the rule's
+// allowedGlobs tunable adds locations. Fixture goldens document
+// themselves where CONVENTIONS places them (packages/codictator/fixtures,
+// SPEC §4.5.7), like the secret scanner's fixture skip.
+export function resolveDocPlacement(decl, rule) {
+    const binding = bindRule(rule);
+    const allowed = tunableStringList(binding, "allowedGlobs") ?? [];
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            const found = placementFinding(binding, file, allowed);
+            if (found !== undefined) {
+                findings.push(found);
+            }
+        }
+        return findings;
+    }));
+}
+function placementFinding(binding, file, allowed) {
+    const outside = (message) => findingFor(binding, {
+        path: file,
+        message,
+        vars: { path: file },
+    });
+    if (!file.endsWith(".md")) {
+        return undefined;
+    }
+    if (isFixturePath(file)) {
+        return undefined;
+    }
+    if (file === "docs/HISTORY.md" || file === "docs/BUGS.md") {
+        return outside(`record folder needs no top-level file: ${file}`);
+    }
+    if (!file.includes("/") && ROOT_DOCS.has(file)) {
+        return undefined;
+    }
+    if (/^docs\/[^/]+\.md$/.test(file) || /^docs\/[^/]+\/.+/.test(file)) {
+        return undefined;
+    }
+    if (/^packages\/[^/]+\/README\.md$/.test(file)) {
+        return undefined;
+    }
+    if (allowed.some((glob) => file === glob)) {
+        return undefined;
+    }
+    return outside(`doc outside its placed locations: ${file}`);
+}
+// SPEC §5.10 core/doc-one-level: a doc nested below docs/<NAME>/ flags.
+export function resolveDocOneLevel(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)) {
+            if (!isDocScopeFile(file)) {
+                continue;
+            }
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined) {
+                continue;
+            }
+            const declared = parseMarkers(text).get("path") ?? file;
+            const match = /^docs\/([^/]+)\/([^/]+)\//.exec(declared);
+            const folder = match?.[1] ?? "";
+            if (match !== null && folder !== "HISTORY" && folder !== "BUGS") {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `doc nested below docs/${folder}/: ${declared}`,
+                    vars: { path: file },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §5.10 core/doc-router-leaf: a folder with no router leaf flags.
+export function resolveDocRouterLeaf(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)) {
+            if (!isDocScopeFile(file)) {
+                continue;
+            }
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined) {
+                continue;
+            }
+            if ((parseMarkers(text).get("router") ?? "") === "missing") {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `doc folder with no router leaf in ${file}`,
+                    vars: { path: file },
+                }));
+            }
+        }
+        return findings;
+    }));
+}
+// SPEC §4.9.2 core/doc-no-corpus-counts: a corpus count flags. The
+// sentence shape is SPEC-owned: this/the corpus|repository|docs|spec|prd|
+// folder has|contains|holds|consists of N. Anything else — validation
+// numbers in history entries, SPEC citations, code identifiers — is not
+// a corpus count, so ad-hoc digit regexes must not stand in for it.
+const CORPUS_COUNT = /\b(this|the)\s+(corpus|repository|repos|docs?|spec|prd|folder)\s+(has|contains|holds|consists of)\s+\d+/i;
+// SPEC §5.10 core/doc-no-corpus-counts: a corpus count flags.
+export function resolveDocNoCorpusCounts(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)) {
+            if (!isDocScopeFile(file)) {
+                continue;
+            }
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined || /no counts/i.test(text)) {
+                continue;
+            }
+            const found = corpusFinding(binding, file, text);
+            if (found !== undefined) {
+                findings.push(found);
+            }
+        }
+        return findings;
+    }));
+}
+function corpusFinding(binding, file, text) {
+    if (!CORPUS_COUNT.test(text)) {
+        return undefined;
+    }
+    return findingFor(binding, {
+        path: file,
+        message: `corpus count in ${file}`,
+        vars: { path: file },
+    });
+}
+// SPEC §5.10 core/doc-single-owner: a fact with two owners flags.
+export function resolveDocSingleOwner(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)) {
+            if (!isDocScopeFile(file)) {
+                continue;
+            }
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined) {
+                continue;
+            }
+            const owners = parseMarkerInt(parseMarkers(text), "owners");
+            if (owners !== undefined && owners > 1) {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    message: `fact with two owners in ${file}`,
+                    vars: { path: file, value: String(owners) },
+                }));
+            }
+        }
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/engine-version-guards.d.ts

@@ -0,0 +1,6 @@
+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 resolveEngineVersionMatch(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

package/dist/features/packs/enforcers/engine-version-guards.js

@@ -0,0 +1,42 @@
+import { parseJson } from "../../../kernel/index.js";
+import { findingFor, readErrorFinding, selectFiles, } from "./binding.js";
+import { checkEnforcer, loadScopeText } from "./health-measures.js";
+async function checkEngineVersionFile(ports, binding, file, findings) {
+    const text = await loadScopeText(ports, binding, file, findings);
+    if (text === undefined) {
+        return;
+    }
+    const parsed = parseJson(text);
+    if (!parsed.ok) {
+        findings.push(readErrorFinding(binding, file, parsed.error, "parse"));
+        return;
+    }
+    const record = (typeof parsed.value === "object" && parsed.value !== null
+        ? parsed.value
+        : {});
+    if (typeof record.engine !== "string" ||
+        typeof record.pack !== "string" ||
+        record.engine === record.pack) {
+        return;
+    }
+    findings.push(findingFor(binding, {
+        path: file,
+        message: `pack version ${record.pack} does not match the engine ${record.engine}`,
+        vars: { path: file, value: record.engine },
+    }));
+}
+async function checkEngineVersionFiles(ports, binding, ctx) {
+    const findings = [];
+    for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+        if (file !== "engine.json" && !file.endsWith("/engine.json")) {
+            continue;
+        }
+        await checkEngineVersionFile(ports, binding, file, findings);
+    }
+    return findings;
+}
+// SPEC §4.14.2 core/engine-version-match: the declared version must equal
+// the installed engine; a pack ahead of the engine flags.
+export function resolveEngineVersionMatch(decl, rule, ports) {
+    return checkEnforcer(decl, rule, (binding, ctx) => checkEngineVersionFiles(ports, binding, ctx));
+}

package/dist/features/packs/enforcers/external-attribute.d.ts

@@ -0,0 +1,18 @@
+import type { Finding } from "../../engine/index.ts";
+import { type RuleBinding } from "./binding.ts";
+import type { ExternalArgs, ToolDecl, ToolEvent } from "./external.ts";
+import { type BatchOutcome } from "./external-runs.ts";
+export interface ResolvedExternal {
+    readonly tool: ToolDecl;
+    readonly args: ExternalArgs;
+    readonly specificRules: ReadonlyArray<string>;
+    readonly wildcard: boolean;
+    readonly timeoutMs: number;
+    readonly onToolEvent: ((event: ToolEvent) => void) | undefined;
+}
+export declare function detailVars(toolId: string): Record<string, string>;
+export declare function closedFinding(binding: RuleBinding, toolId: string, code: string, detail: string): Finding;
+export declare function runBatch(binding: RuleBinding, resolved: ResolvedExternal, version: string, argv: ReadonlyArray<string>, outcome: BatchOutcome): {
+    readonly findings: Array<Finding>;
+    readonly event: ToolEvent;
+};

package/dist/features/packs/enforcers/external-attribute.js

@@ -0,0 +1,122 @@
+// SPEC §4.4.5 batch attribution: parsed tool output becomes pack-rule
+// findings, escapes become one CDX-E207, and every batch outcome maps to
+// the fail-closed code the section owns (E207/E208/E209/E902).
+import { err, ok } from "../../../kernel/index.js";
+import { findingFor } from "./binding.js";
+import { parseJsonOutput, parseRegexOutput, } from "./external-output.js";
+import { digestArgv } from "./external-runs.js";
+import { parseSarif } from "./external-sarif.js";
+export function detailVars(toolId) {
+    return { detail: toolId };
+}
+export function closedFinding(binding, toolId, code, detail) {
+    return findingFor(binding, {
+        code,
+        message: `external tool "${toolId}" ${detail}`,
+        vars: detailVars(toolId),
+    });
+}
+function parseBatchOutput(resolved, text) {
+    const output = resolved.args.output;
+    if (output.format === "sarif") {
+        return parseSarif(text);
+    }
+    if (output.format === "json") {
+        if (output.select === undefined) {
+            return err({
+                code: "CDX-E207",
+                message: "json output needs a select binding",
+                remediation: "Fix the pack output binding, then reload.",
+            });
+        }
+        return parseJsonOutput(text, output.select);
+    }
+    if (output.format === "regex") {
+        if (output.pattern === undefined) {
+            return err({
+                code: "CDX-E207",
+                message: "regex output needs a pattern binding",
+                remediation: "Fix the pack output binding, then reload.",
+            });
+        }
+        return parseRegexOutput(text, output.pattern);
+    }
+    return ok({ findings: [], escapes: 0 });
+}
+function attributeFindings(binding, resolved, parsed) {
+    const findings = [];
+    for (const entry of parsed.findings) {
+        const kept = resolved.specificRules.includes(entry.toolRule) || resolved.wildcard;
+        if (!kept) {
+            continue;
+        }
+        const withPath = entry.path === undefined ? {} : { path: entry.path };
+        const withLine = entry.line === undefined ? {} : { line: entry.line };
+        findings.push(findingFor(binding, {
+            message: entry.message,
+            vars: {
+                path: entry.path ?? "",
+                line: entry.line === undefined ? "" : String(entry.line),
+            },
+            ...withPath,
+            ...withLine,
+        }));
+    }
+    if (parsed.escapes > 0) {
+        findings.push(closedFinding(binding, resolved.tool.id, "CDX-E207", `named ${String(parsed.escapes)} paths outside the repo; they were dropped`));
+    }
+    return findings;
+}
+export function runBatch(binding, resolved, version, argv, outcome) {
+    const toolId = resolved.tool.id;
+    const event = (exitCode, findingCount) => ({
+        toolId,
+        version,
+        argvDigest: digestArgv(argv),
+        exitCode,
+        findingCount,
+    });
+    if (!outcome.ok) {
+        const found = [
+            closedFinding(binding, toolId, outcome.error.code, "failed"),
+        ];
+        return { findings: found, event: event(-1, found.length) };
+    }
+    if (outcome.timedOut) {
+        const found = [closedFinding(binding, toolId, "CDX-E902", "timed out")];
+        return { findings: found, event: event(outcome.code, found.length) };
+    }
+    if (outcome.truncated) {
+        const found = [
+            closedFinding(binding, toolId, "CDX-E207", "output exceeded the size cap"),
+        ];
+        return { findings: found, event: event(outcome.code, found.length) };
+    }
+    if (resolved.args.passCodes.includes(outcome.code)) {
+        return { findings: [], event: event(outcome.code, 0) };
+    }
+    if (!resolved.args.findingCodes.includes(outcome.code)) {
+        const found = [
+            closedFinding(binding, toolId, "CDX-E207", `exited with unlisted code ${String(outcome.code)}`),
+        ];
+        return { findings: found, event: event(outcome.code, found.length) };
+    }
+    if (resolved.args.output.format === "exit-code") {
+        const found = [
+            findingFor(binding, {
+                message: `external tool "${toolId}" reported findings`,
+                vars: detailVars(toolId),
+            }),
+        ];
+        return { findings: found, event: event(outcome.code, found.length) };
+    }
+    const parsed = parseBatchOutput(resolved, outcome.text);
+    if (!parsed.ok) {
+        const found = [
+            closedFinding(binding, toolId, "CDX-E207", "output is unusable"),
+        ];
+        return { findings: found, event: event(outcome.code, found.length) };
+    }
+    const found = attributeFindings(binding, resolved, parsed.value);
+    return { findings: found, event: event(outcome.code, found.length) };
+}

package/dist/features/packs/enforcers/external-bind.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../../../kernel/index.ts";
+import { type ExternalArgs, type ToolDecl } from "./external.ts";
+export declare function narrowToolDecl(entry: unknown): Result<ToolDecl>;
+export declare function narrowExternalArgs(declId: string, args: unknown): Result<ExternalArgs>;

package/dist/features/packs/enforcers/external-bind.js

@@ -0,0 +1,206 @@
+// SPEC §4.4.5 declaration narrowing: config.tools rows (§7.2) and the
+// pack enforcer's input/output/exit-code binding. Malformed bindings fail
+// the load (CDX-E203, CDX-E206); the runner never sees them.
+import { checkPattern, err, makeError, ok, } from "../../../kernel/index.js";
+import { field, isRecord } from "../manifest.js";
+import { isExternalInput, } from "./external.js";
+const DEFAULT_TIMEOUT_MS = 30000;
+function toolError(code, detail) {
+    return err(makeError(code, detail, "Fix the external tool binding or the tool itself, then reload the pack."));
+}
+function stringList(value) {
+    if (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string")) {
+        return [...value];
+    }
+    return undefined;
+}
+function narrowTimeoutMs(timeout) {
+    return typeof timeout === "number" && Number.isInteger(timeout) && timeout > 0
+        ? timeout
+        : DEFAULT_TIMEOUT_MS;
+}
+function narrowToolIdentity(entry) {
+    const id = field(entry, "id");
+    const command = stringList(field(entry, "command")) ?? [];
+    if (typeof id !== "string" || id.length === 0 || command.length === 0) {
+        return toolError("CDX-E203", "a config.tools entry needs a non-empty id and command argv");
+    }
+    return ok({ id, command });
+}
+function narrowToolVersion(entry, id) {
+    const version = field(entry, "version");
+    if (!isRecord(version)) {
+        return toolError("CDX-E206", `tool "${id}" has no exact version pin`);
+    }
+    const pin = field(version, "pin");
+    if (typeof pin !== "string" || pin.length === 0) {
+        return toolError("CDX-E206", `tool "${id}" has no exact version pin`);
+    }
+    const probe = stringList(field(version, "probe")) ?? [];
+    const pattern = field(version, "pattern");
+    if (probe.length === 0 ||
+        typeof pattern !== "string" ||
+        pattern.length === 0) {
+        return toolError("CDX-E203", `tool "${id}" needs a probe argv and a pattern`);
+    }
+    return ok({ pin, probe, pattern });
+}
+// SPEC §7.2: a tools entry needs an id, an argv command and an exact pin
+// with its probe. CDX-E206 when the pin is missing (§8).
+export function narrowToolDecl(entry) {
+    if (!isRecord(entry)) {
+        return toolError("CDX-E203", "a config.tools entry must be an object");
+    }
+    const identity = narrowToolIdentity(entry);
+    if (!identity.ok) {
+        return identity;
+    }
+    const version = narrowToolVersion(entry, identity.value.id);
+    if (!version.ok) {
+        return version;
+    }
+    const role = field(entry, "role");
+    if (typeof role === "string" && role !== "enforcer") {
+        return toolError("CDX-E203", `tool "${identity.value.id}" is a helper and cannot back an enforcer`);
+    }
+    const timeout = field(entry, "timeoutMs");
+    const envPass = stringList(field(entry, "envPass")) ?? [];
+    return ok({
+        id: identity.value.id,
+        command: identity.value.command,
+        version: version.value,
+        role: typeof role === "string" ? role : undefined,
+        timeoutMs: narrowTimeoutMs(timeout),
+        envPass,
+    });
+}
+function narrowOutputFormat(value, withId) {
+    if (value === "sarif" ||
+        value === "json" ||
+        value === "regex" ||
+        value === "exit-code") {
+        return ok(value);
+    }
+    return withId("needs an output format of sarif, json, regex or exit-code");
+}
+function narrowOutputSource(value, withId) {
+    const source = value ?? "stdout";
+    if (source === "stdout" || source === "{out}") {
+        return ok(source);
+    }
+    return withId("needs an output source of stdout or {out}");
+}
+function narrowOutput(declId, value) {
+    if (!isRecord(value)) {
+        return toolError(declId, "needs an output binding");
+    }
+    const withId = (detail) => toolError("CDX-E203", `pack enforcer "${declId}" ${detail}`);
+    const format = narrowOutputFormat(field(value, "format"), withId);
+    if (!format.ok) {
+        return format;
+    }
+    const source = narrowOutputSource(field(value, "source"), withId);
+    if (!source.ok) {
+        return source;
+    }
+    if (format.value === "json") {
+        return narrowJsonSelect(withId, format.value, source.value, field(value, "select"));
+    }
+    if (format.value === "regex") {
+        return narrowRegexPattern(withId, format.value, source.value, field(value, "pattern"));
+    }
+    return ok({
+        format: format.value,
+        source: source.value,
+        select: undefined,
+        pattern: undefined,
+    });
+}
+function narrowJsonSelect(withId, format, output, select) {
+    if (!isRecord(select)) {
+        return withId("needs a select for json output");
+    }
+    const names = ["results", "path", "line", "rule", "message"];
+    const selected = {};
+    for (const name of names) {
+        const dotted = field(select, name);
+        if (typeof dotted !== "string" || dotted.length === 0) {
+            return withId(`needs a select.${name} dotted path`);
+        }
+        selected[name] = dotted;
+    }
+    const at = (name) => selected[name] ?? "";
+    return ok({
+        format,
+        source: output,
+        select: {
+            results: at("results"),
+            path: at("path"),
+            line: at("line"),
+            rule: at("rule"),
+            message: at("message"),
+        },
+        pattern: undefined,
+    });
+}
+function narrowRegexPattern(withId, format, output, raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        return withId("needs a pattern for regex output");
+    }
+    const safe = checkPattern(raw);
+    if (!safe.ok) {
+        return err(safe.error);
+    }
+    let pattern;
+    try {
+        pattern = new RegExp(raw);
+    }
+    catch {
+        return withId("carries a regex the engine rejects");
+    }
+    return ok({ format, source: output, select: undefined, pattern });
+}
+function codeList(value) {
+    if (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "number" && Number.isInteger(entry))) {
+        return [...value];
+    }
+    return undefined;
+}
+// SPEC §4.4.5 declaration: input mode, output binding and exit-code lists.
+// Defaults keep hand-written packs working: files in, stdout out, 0 clean,
+// 1 findings.
+export function narrowExternalArgs(declId, args) {
+    const record = isRecord(args) ? args : {};
+    const input = field(record, "input") ?? "files";
+    if (typeof input !== "string" || !isExternalInput(input)) {
+        return toolError("CDX-E203", `pack enforcer "${declId}" needs an input of file, files, staged, diff, repo or stdin-json`);
+    }
+    const output = narrowOutput(declId, field(record, "output") ?? { format: "exit-code" });
+    if (!output.ok) {
+        return err(output.error);
+    }
+    const codes = field(record, "exitCodes");
+    const passCodes = (isRecord(codes)
+        ? codeList(field(codes, "pass"))
+        : undefined) ?? [0];
+    const findingCodes = (isRecord(codes)
+        ? codeList(field(codes, "findings"))
+        : undefined) ?? [1];
+    for (const code of passCodes) {
+        if (findingCodes.includes(code)) {
+            return toolError("CDX-E203", `pack enforcer "${declId}" lists exit code ${String(code)} as both pass and findings`);
+        }
+    }
+    const timeout = field(record, "timeoutMs");
+    return ok({
+        input,
+        output: output.value,
+        passCodes,
+        findingCodes,
+        timeoutMs: typeof timeout === "number" && Number.isInteger(timeout) && timeout > 0
+            ? timeout
+            : undefined,
+    });
+}

package/dist/features/packs/enforcers/external-check.d.ts

@@ -0,0 +1,7 @@
+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";
+import type { ExternalOptions, ToolDecl } from "./external.ts";
+export declare function resolveExternal(decl: EnforcerDecl, rule: PackRule, ports: Ports, tool: ToolDecl, options?: ExternalOptions): Result<Enforcer>;