codictator 0.0.0 → 0.1.2

package/dist/features/deps/verdicts.js

@@ -0,0 +1,219 @@
+// SPEC §4.8.5 verdicts over manifests plus snapshot. The orchestration and
+// the manifest-intrinsic rows live here; pinned rows needing registry data
+// live in snapshot-verdicts.ts and the §6.1 catalogue in capabilities.ts.
+import { makeError } from "../../kernel/index.js";
+import { capabilityOf, DEFAULT_LICENSE_ALLOW, platformCapabilityCover, } from "./capabilities.js";
+import { pinFinding, uniqueDeps, } from "./eval.js";
+import { lockfileMismatches, parsePackageLock } from "./lockfile.js";
+import { isExactNpmPin } from "./npm.js";
+import { NPM_PUBLIC_REGISTRY_HOST, parseNpmrc, privateRegistryHosts, } from "./npmrc.js";
+import { checkPinnedVerdicts, pinnedOrUnversionedNote, snapshotForm, } from "./snapshot-verdicts.js";
+import { DEFAULT_DEP_LAG_PARAMS } from "./stable.js";
+export function manifestToEval(manifest) {
+    return {
+        path: manifest.path,
+        dependencies: manifest.dependencies.map((dep) => ({
+            name: dep.name,
+            range: dep.range,
+            kind: dep.kind ?? "prod",
+        })),
+    };
+}
+// SPEC §4.8.5 verdicts over manifests plus snapshot. Anything needing data
+// the caller did not supply is skipped, never default-allowed: absence of a
+// snapshot entry means "not fetched", not "clean".
+export function evaluateDepVerdicts(input) {
+    const findings = [];
+    const notes = [];
+    checkExactPins(input, findings);
+    checkLockfiles(input, findings);
+    checkNewNeedsReason(input, findings);
+    checkOnePerCapability(input, findings);
+    checkNpmrc(input, findings);
+    if (input.snapshot !== undefined) {
+        checkSnapshotVerdicts(input, findings, notes);
+    }
+    return { findings, notes };
+}
+function checkExactPins(input, findings) {
+    for (const manifest of input.manifests) {
+        for (const dep of manifest.dependencies) {
+            if (dep.kind === "peer") {
+                continue;
+            }
+            if (!isExactNpmPin(dep.range)) {
+                findings.push(pinFinding(manifest.path, dep.name, dep.range));
+            }
+        }
+    }
+}
+function lockfileFindingsFor(manifest, text) {
+    const parsed = parsePackageLock(text);
+    if (!parsed.ok) {
+        return [
+            {
+                ruleId: "core/dep-lockfile",
+                path: manifest.path,
+                code: parsed.error.code,
+                message: `lockfile for ${manifest.path} is unparseable`,
+                remediation: `Regenerate the lockfile for ${manifest.path} with the ecosystem tool.`,
+            },
+        ];
+    }
+    const mismatched = lockfileMismatches(manifest.dependencies, {
+        lockfileVersion: 3,
+        pinned: parsed.value.pinned,
+    });
+    return mismatched.map((name) => ({
+        ruleId: "core/dep-lockfile",
+        path: manifest.path,
+        message: `${name} in ${manifest.path} is out of sync with the lockfile`,
+        remediation: `Regenerate the lockfile for ${manifest.path} with the ecosystem tool.`,
+    }));
+}
+function checkLockfiles(input, findings) {
+    if (input.lockfiles === undefined) {
+        return;
+    }
+    for (const manifest of input.manifests) {
+        if (!(manifest.path in input.lockfiles)) {
+            continue;
+        }
+        const text = input.lockfiles[manifest.path];
+        if (text === null || text === undefined) {
+            findings.push({
+                ruleId: "core/dep-lockfile",
+                path: manifest.path,
+                message: `no lockfile committed for ${manifest.path}`,
+                remediation: `Commit the lockfile for ${manifest.path}.`,
+            });
+            continue;
+        }
+        for (const finding of lockfileFindingsFor(manifest, text)) {
+            findings.push(finding);
+        }
+    }
+}
+function checkNewNeedsReason(input, findings) {
+    if (input.newDeps === undefined) {
+        return;
+    }
+    for (const manifest of input.manifests) {
+        for (const dep of manifest.dependencies) {
+            if (input.newDeps.includes(dep.name) &&
+                input.addedReasons?.[dep.name] !== true) {
+                findings.push({
+                    ruleId: "core/dep-new-needs-reason",
+                    path: manifest.path,
+                    message: `${dep.name} in ${manifest.path} has no recorded reason`,
+                    remediation: `Record why ${dep.name} is needed in ${manifest.path}.`,
+                });
+            }
+        }
+    }
+}
+function checkOnePerCapability(input, findings) {
+    const byCapability = new Map();
+    const platformHeld = new Set(input.platformCaps ?? []);
+    for (const { path, dep } of uniqueDeps(input.manifests)) {
+        const capability = capabilityOf(dep.name);
+        if (capability === undefined) {
+            continue;
+        }
+        if (platformHeld.has(capability)) {
+            const cover = platformCapabilityCover(capability) ?? capability;
+            findings.push({
+                ruleId: "core/dep-one-per-capability",
+                path,
+                message: `${dep.name} duplicates the pinned platform's ${cover} (${capability})`,
+                remediation: `Remove ${dep.name}; the pinned platform already covers ${capability}.`,
+            });
+            continue;
+        }
+        const holders = byCapability.get(capability) ?? [];
+        holders.push({ path, name: dep.name });
+        byCapability.set(capability, holders);
+    }
+    for (const [capability, holders] of [...byCapability.entries()].sort()) {
+        const first = holders[0];
+        const second = holders[1];
+        if (first !== undefined && second !== undefined) {
+            findings.push({
+                ruleId: "core/dep-one-per-capability",
+                path: first.path,
+                message: `${first.name} and ${second.name} both cover ${capability}`,
+                remediation: `Remove ${second.name}; the kept package already covers ${capability}.`,
+            });
+        }
+    }
+}
+function checkNpmrc(input, findings) {
+    if (input.npmrc === undefined) {
+        return;
+    }
+    const parsed = parseNpmrc(input.npmrc.text);
+    if (input.saveExactRequired === true && parsed.saveExact !== true) {
+        findings.push({
+            ruleId: "core/dep-exact-pin",
+            path: input.npmrc.path,
+            message: `${input.npmrc.path} lacks the owned save-exact=true entry`,
+            remediation: `Set save-exact=true in ${input.npmrc.path}.`,
+        });
+    }
+    const allowed = input.allowedRegistryHosts ?? [];
+    for (const host of privateRegistryHosts(parsed)) {
+        if (host !== NPM_PUBLIC_REGISTRY_HOST && !allowed.includes(host)) {
+            findings.push({
+                ruleId: "core/dep-exact-pin",
+                path: input.npmrc.path,
+                code: "CDX-E702",
+                message: `private registry ${host} is not on the network allowlist`,
+                remediation: `Add ${host} via config.network.registries (SPEC §9.2).`,
+            });
+        }
+    }
+}
+function checkSnapshotVerdicts(input, findings, notes) {
+    const params = { ...DEFAULT_DEP_LAG_PARAMS, ...input.params };
+    const allow = input.licenseAllow ?? DEFAULT_LICENSE_ALLOW;
+    const snapshot = input.snapshot;
+    if (snapshot === undefined) {
+        return;
+    }
+    for (const { path, dep } of uniqueDeps(input.manifests)) {
+        if (dep.kind === "peer") {
+            continue;
+        }
+        const form = snapshotForm(dep.range);
+        if (form === "unversioned") {
+            notes.push(pinnedOrUnversionedNote(path, dep.name));
+            continue;
+        }
+        if (form !== "pinned") {
+            continue;
+        }
+        const pinned = dep.range.replace(/^v/, "");
+        for (const finding of checkPinnedVerdicts({
+            snapshot,
+            params,
+            allow,
+            path,
+            dep,
+            unpublished: input.unpublished ?? [],
+        }, pinned, notes)) {
+            findings.push(finding);
+        }
+    }
+}
+export function depErrorFinding(ruleId, path, error, remediation) {
+    return {
+        ruleId,
+        path,
+        code: error.code,
+        message: error.message,
+        remediation,
+    };
+}
+export function makeDepError(code, message, remediation) {
+    return makeError(code, message, remediation);
+}

package/dist/features/engine/evaluate.d.ts

@@ -0,0 +1,12 @@
+import { type Result } from "../../kernel/index.ts";
+import type { NewEvent } from "../audit/index.ts";
+import type { Enforcer, Engine } from "./index.ts";
+import { type Waiver, type WaiverStore } from "./waivers.ts";
+export interface EngineOptions {
+    readonly waiverStore?: WaiverStore;
+    readonly append?: (event: NewEvent) => Promise<Result<void>>;
+    readonly configHash?: string;
+    readonly packs?: Readonly<Record<string, string>>;
+}
+export declare function createEngine(enforcers: ReadonlyArray<Enforcer>, options?: EngineOptions): Engine;
+export type { Waiver, WaiverStore };

package/dist/features/engine/evaluate.js

@@ -0,0 +1,165 @@
+// SPEC §4.3.3 evaluation with §4.3.8 fail closed: select rules for the
+// trigger, run their enforcers concurrently under budget, apply waivers,
+// decide, then append the verdict event before returning. The verdict is
+// a pure function of the inputs (SPEC §4.3.6): enforcer and finding order
+// is sorted and the id derives from the inputs, so replay is byte-identical.
+// The clock arrives only through CheckContext.
+import { ok, sha256Text, stableStringify, } from "../../kernel/index.js";
+import { buildMessage } from "./message.js";
+import { appendFailedFinding, runEnforcer, sortFindings, } from "./run-enforcer.js";
+import { DEFAULT_WAIVER_STORE, matchWaivers, } from "./waivers.js";
+// SPEC §4.3.2: each engine trigger evaluates at one layer. Coarse triggers
+// map to the layer of their first scope; finer hook names arrive with the
+// adapter contract (phase 5).
+const TRIGGER_LAYERS = {
+    startup: "L0",
+    prompt: "L0",
+    compact: "L0",
+    "pre-tool": "L1",
+    "post-tool": "L1",
+    review: "L3",
+    scheduled: "L5",
+};
+// SPEC §4.3.3: findings only from advisory triggers advise; everything
+// else with findings blocks. L2 (editor.save, never a gate per §4.3.8) has
+// no trigger in this union yet; prompt carries the injection path.
+const ADVISORY_TRIGGERS = ["prompt"];
+// SPEC §4.3.6: the verdict id is a pure function of the inputs, so the
+// same evaluation replays byte-identical (EC-12). Uniqueness across
+// concurrent processes lives at append time: the hook runtime passes its
+// per-process counter as the appendEvent seq (SPEC §7.10).
+function makeVerdictId(now, trigger, scope, decision, findings, waiversApplied, configHash) {
+    const stamp = now.replace(/[-:.]/g, "");
+    const canonical = stableStringify({
+        trigger,
+        files: [...scope.files].sort(),
+        sessionId: scope.sessionId,
+        // SPEC §4.3.6: the hook input is a verdict input, so the proposed
+        // tool content joins the id; two proposals never share an event.
+        ...(scope.proposedContent === undefined
+            ? {}
+            : { proposedContent: scope.proposedContent }),
+        ...(scope.shellCommand === undefined
+            ? {}
+            : { shellCommand: scope.shellCommand }),
+        ...(scope.proposedPaths === undefined
+            ? {}
+            : { proposedPaths: [...scope.proposedPaths].sort() }),
+        decision,
+        findings,
+        waiversApplied,
+        configHash,
+    });
+    return `${stamp}-${sha256Text(canonical).slice(0, 12)}`;
+}
+// SPEC §4.3.4: suppress findings covered by an active waiver, recording
+// the waiver ids. Synthetic fail-closed findings (CDX-E*) never suppress,
+// and an invalid floor-rule waiver blocks loudly instead of suppressing.
+async function applyWaivers(findings, store, now) {
+    const kept = [];
+    const applied = new Set();
+    for (const finding of findings) {
+        if (finding.code?.startsWith("CDX-E") === true) {
+            kept.push(finding);
+            continue;
+        }
+        const matched = matchWaivers(store, finding.ruleId, finding.path ?? "", now);
+        if (!matched.ok) {
+            kept.push(finding);
+            kept.push({
+                ruleId: finding.ruleId,
+                code: matched.error.code,
+                message: matched.error.message,
+                remediation: matched.error.remediation,
+            });
+            continue;
+        }
+        if (matched.value.length === 0) {
+            kept.push(finding);
+            continue;
+        }
+        for (const waiver of matched.value) {
+            applied.add(waiver.id);
+        }
+    }
+    return { kept, waiversApplied: [...applied].sort() };
+}
+function ruleIdsOf(findings) {
+    const seen = new Set();
+    for (const finding of findings) {
+        seen.add(finding.ruleId);
+    }
+    return [...seen].sort();
+}
+async function collectFindings(ordered, ctx, store) {
+    const runnable = ordered.filter((enforcer) => enforcer.kinds.includes(ctx.trigger));
+    const ran = await Promise.all(runnable.map((enforcer) => runEnforcer(enforcer, ctx)));
+    return applyWaivers(sortFindings(ran.flat()), store, ctx.now);
+}
+function decideDecision(kept, trigger) {
+    if (kept.length === 0) {
+        return "allow";
+    }
+    return ADVISORY_TRIGGERS.includes(trigger) ? "advise" : "block";
+}
+function buildVerdictEvent(trigger, now, decision, kept, waiversApplied, configHash, packs, message, clockSkew) {
+    return {
+        kind: "verdict",
+        layer: TRIGGER_LAYERS[trigger],
+        trigger,
+        ruleIds: ruleIdsOf(kept),
+        decision,
+        findings: kept,
+        durationMs: 0,
+        configHash,
+        packs,
+        message,
+        ts: now,
+        ...(clockSkew ? { clockSkew: true } : {}),
+        ...(waiversApplied.length > 0 ? { waivers: waiversApplied } : {}),
+    };
+}
+function blockedVerdict(now, trigger, scope, configHash) {
+    const blocked = [appendFailedFinding()];
+    const blockedId = makeVerdictId(now, trigger, scope, "block", blocked, [], configHash);
+    return {
+        decision: "block",
+        findings: blocked,
+        message: buildMessage("block", blocked, blockedId),
+        eventId: blockedId,
+        waiversApplied: [],
+    };
+}
+// SPEC §4.3.3: pure evaluation over registered enforcers.
+export function createEngine(enforcers, options = {}) {
+    const ordered = [...enforcers].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const store = options.waiverStore ?? DEFAULT_WAIVER_STORE;
+    const append = options.append ??
+        (() => Promise.resolve(ok(undefined)));
+    const configHash = options.configHash ?? "unknown";
+    const packs = options.packs ?? {};
+    // Per-engine memory for EC-15 skew detection: closure state, never
+    // module-level, so engines stay independent (CONVENTIONS determinism).
+    // It never leaks into the verdict, which stays a pure function of its
+    // inputs (SPEC §4.3.6).
+    let lastNow;
+    return {
+        evaluate: async (trigger, scope, now) => {
+            const clockSkew = lastNow !== undefined && now < lastNow;
+            if (lastNow === undefined || now > lastNow) {
+                lastNow = now;
+            }
+            const ctx = { trigger, scope, now, configHash };
+            const { kept, waiversApplied } = await collectFindings(ordered, ctx, store);
+            const decision = decideDecision(kept, trigger);
+            const eventId = makeVerdictId(now, trigger, scope, decision, kept, waiversApplied, configHash);
+            const message = buildMessage(decision, kept, eventId);
+            const event = buildVerdictEvent(trigger, now, decision, kept, waiversApplied, configHash, packs, message, clockSkew);
+            const appended = await append(event);
+            if (!appended.ok) {
+                return blockedVerdict(now, trigger, scope, configHash);
+            }
+            return { decision, findings: kept, message, eventId, waiversApplied };
+        },
+    };
+}

package/dist/features/engine/index.d.ts

@@ -0,0 +1,21 @@
+import type { CheckContext, Decision, Enforcer, Finding, Instant, Result, Scope, Trigger } from "../../kernel/index.ts";
+import type { EngineOptions } from "./evaluate.ts";
+import { DEFAULT_WAIVER_STORE, MAX_WAIVER_DAYS, type Waiver, type WaiverStore } from "./waivers.ts";
+export { TRIGGERS } from "../../kernel/index.ts";
+export type { CheckContext, Decision, Enforcer, EngineOptions, Finding, Result, Scope, Trigger, Waiver, WaiverStore, };
+export { DEFAULT_WAIVER_STORE, MAX_WAIVER_DAYS };
+export interface Verdict {
+    readonly decision: Decision;
+    readonly findings: ReadonlyArray<Finding>;
+    readonly message: string;
+    readonly eventId: string;
+    readonly waiversApplied: ReadonlyArray<string>;
+}
+export interface Engine {
+    readonly evaluate: (trigger: Trigger, scope: Scope, now: Instant) => Promise<Verdict>;
+}
+export declare function createEngine(enforcers: ReadonlyArray<Enforcer>, options?: EngineOptions): Engine;
+export declare function buildMessage(decision: Decision, findings: ReadonlyArray<Finding>, eventId: string): string;
+export declare function isWaived(ruleId: string, path: string, now: Instant, store?: WaiverStore): Promise<Result<boolean>>;
+export declare function matchWaivers(store: WaiverStore, ruleId: string, path: string, now: Instant): Result<ReadonlyArray<Waiver>>;
+export { compareRatchet } from "./ratchet.ts";

package/dist/features/engine/index.js

@@ -0,0 +1,24 @@
+import { createEngine as createEngineImpl } from "./evaluate.js";
+import { buildMessage as buildMessageImpl } from "./message.js";
+import { DEFAULT_WAIVER_STORE, isWaived as isWaivedImpl, MAX_WAIVER_DAYS, matchWaivers as matchWaiversImpl, } from "./waivers.js";
+export { TRIGGERS } from "../../kernel/index.js";
+export { DEFAULT_WAIVER_STORE, MAX_WAIVER_DAYS };
+// SPEC §4.3.3: pure evaluation over registered enforcers.
+export function createEngine(enforcers, options = {}) {
+    return createEngineImpl(enforcers, options);
+}
+// SPEC §4.3.7: the agent-facing verdict text inside its byte budget.
+export function buildMessage(decision, findings, eventId) {
+    return buildMessageImpl(decision, findings, eventId);
+}
+// SPEC §4.3.4: waiver lookup for the verdict path.
+export function isWaived(ruleId, path, now, store = DEFAULT_WAIVER_STORE) {
+    return isWaivedImpl(ruleId, path, now, store);
+}
+// SPEC §4.3.4: the waivers suppressing a finding, or CDX-E103 for a floor
+// rule waiver.
+export function matchWaivers(store, ruleId, path, now) {
+    return matchWaiversImpl(store, ruleId, path, now);
+}
+// SPEC §4.3.5: ratchet comparison against the baseline.
+export { compareRatchet } from "./ratchet.js";

package/dist/features/engine/message.d.ts

@@ -0,0 +1,3 @@
+import type { Decision, Finding } from "./index.ts";
+export declare const MAX_MESSAGE_BYTES = 1200;
+export declare function buildMessage(decision: Decision, findings: ReadonlyArray<Finding>, eventId: string): string;

package/dist/features/engine/message.js

@@ -0,0 +1,69 @@
+// SPEC §4.3.7: the agent-facing verdict text. E2 covers the block shape
+// the §4.3 EC rows assert (rule names, Why, Do instead, the count line);
+// the full message budget copy lands with step 4.8.
+import { redactSecrets } from "../../kernel/index.js";
+// SPEC §4.3.7: the agent message stays inside 1,200 bytes.
+export const MAX_MESSAGE_BYTES = 1200;
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+function truncateUtf8(text, maxBytes) {
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.length <= maxBytes) {
+        return text;
+    }
+    let cut = maxBytes;
+    while (cut > 0) {
+        const byte = bytes[cut];
+        if (byte === undefined || (byte & 0xc0) !== 0x80) {
+            break;
+        }
+        cut -= 1;
+    }
+    return new TextDecoder().decode(bytes.subarray(0, cut));
+}
+function ruleIdsOf(findings) {
+    const seen = new Set();
+    for (const finding of findings) {
+        seen.add(finding.ruleId);
+    }
+    return [...seen].sort();
+}
+// SPEC §4.3.7: at most the first three findings render in full, then a
+// count line for the rest.
+export function buildMessage(decision, findings, eventId) {
+    const verb = decision === "allow"
+        ? "allowed"
+        : decision === "advise"
+            ? "flagged for review"
+            : "blocked";
+    if (findings.length === 0) {
+        return redactSecrets(`Codictator ${verb} this: no findings remain. (event ${eventId})`);
+    }
+    const rules = ruleIdsOf(findings);
+    const detail = [];
+    for (const finding of findings.slice(0, 3)) {
+        detail.push(`- [${finding.ruleId}] Why: ${finding.message}`);
+        detail.push(`  Do instead: ${finding.remediation}`);
+    }
+    const lines = [`Codictator ${verb} this: ${rules.join(", ")}`, ...detail];
+    if (findings.length > 3) {
+        lines.push(`and ${findings.length - 3} more — codictator verify`);
+    }
+    lines.push(`More: codictator explain ${rules[0] ?? "unknown"} (event ${eventId})`);
+    // SPEC §4.3.9 EC-14: the message is redacted by the kernel; findings
+    // stay raw so remediation keeps its data.
+    let message = redactSecrets(lines.join("\n"));
+    if (byteLength(message) > MAX_MESSAGE_BYTES) {
+        const trimmed = lines.slice(0, 1);
+        if (findings.length > 3) {
+            trimmed.push(`and ${findings.length} more — codictator verify`);
+        }
+        trimmed.push(lines[lines.length - 1] ?? "");
+        message = redactSecrets(trimmed.join("\n"));
+    }
+    if (byteLength(message) > MAX_MESSAGE_BYTES) {
+        message = `${truncateUtf8(message, MAX_MESSAGE_BYTES - 20)}[truncated]`;
+    }
+    return message;
+}

package/dist/features/engine/ratchet.d.ts

@@ -0,0 +1 @@
+export declare function compareRatchet(baseline: Readonly<Record<string, number>>, current: Readonly<Record<string, number>>): ReadonlyArray<string>;

package/dist/features/engine/ratchet.js

@@ -0,0 +1,63 @@
+// SPEC §4.3.5: a count above its baseline blocks — worse than recorded.
+// Counts at or below baseline pass as recorded debt.
+function keysAboveBaseline(baseline, current) {
+    const violations = [];
+    for (const key of Object.keys(baseline).sort()) {
+        if (!Object.hasOwn(current, key)) {
+            continue;
+        }
+        const before = baseline[key] ?? 0;
+        const now = current[key] ?? 0;
+        if (now > before) {
+            violations.push(key);
+        }
+    }
+    return violations;
+}
+// SPEC §4.3.5: deleted files drop their keys. Each dropped key lends its
+// count so a pure rename can move it (same normalised content, same count).
+function droppedCounts(baseline, current) {
+    const dropped = new Map();
+    for (const key of Object.keys(baseline).sort()) {
+        if (Object.hasOwn(current, key)) {
+            continue;
+        }
+        const before = baseline[key] ?? 0;
+        if (before > 0) {
+            dropped.set(before, (dropped.get(before) ?? 0) + 1);
+        }
+    }
+    return dropped;
+}
+// SPEC §4.3.5: a key absent from the baseline with a count above zero is a
+// candidate block.
+function keysAbsentFromBaseline(baseline, current) {
+    const added = [];
+    for (const key of Object.keys(current).sort()) {
+        if (Object.hasOwn(baseline, key)) {
+            continue;
+        }
+        const count = current[key] ?? 0;
+        if (count > 0) {
+            added.push({ key, count });
+        }
+    }
+    return added;
+}
+// SPEC §4.3.5: ratchet comparison against the baseline. A pure rename (same
+// normalised content) moves its keys and is not touched, so each dropped
+// key cancels one added key with the same count; count equality is the only
+// move signal this pure comparison has. Every other added key blocks.
+export function compareRatchet(baseline, current) {
+    const violations = keysAboveBaseline(baseline, current);
+    const dropped = droppedCounts(baseline, current);
+    for (const entry of keysAbsentFromBaseline(baseline, current)) {
+        const spare = dropped.get(entry.count) ?? 0;
+        if (spare > 0) {
+            dropped.set(entry.count, spare - 1);
+            continue;
+        }
+        violations.push(entry.key);
+    }
+    return violations.sort();
+}

package/dist/features/engine/run-enforcer.d.ts

@@ -0,0 +1,4 @@
+import type { CheckContext, Enforcer, Finding } from "./index.ts";
+export declare function runEnforcer(enforcer: Enforcer, ctx: CheckContext): Promise<Array<Finding>>;
+export declare function sortFindings(findings: Array<Finding>): Array<Finding>;
+export declare function appendFailedFinding(): Finding;

package/dist/features/engine/run-enforcer.js

@@ -0,0 +1,82 @@
+function failFinding(enforcerId, code, detail, remediation) {
+    return {
+        ruleId: enforcerId,
+        code,
+        message: `the guard "${enforcerId}" ${detail}; the code was not judged`,
+        remediation,
+    };
+}
+// SPEC §4.3.8: a throw is CDX-E901, unless the enforcer threw its CdxError
+// for unavailable data, which is CDX-E903.
+function thrownCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        if (code === "CDX-E903") {
+            return "CDX-E903";
+        }
+    }
+    return "CDX-E901";
+}
+const TIMED_OUT = { timedOut: true };
+function withBudget(pending, budgetMs) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(TIMED_OUT);
+        }, budgetMs);
+    });
+    return Promise.race([pending, timeout]).finally(() => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    });
+}
+export async function runEnforcer(enforcer, ctx) {
+    let pending;
+    try {
+        // Rule params arrive with the pack registry (phase 5); E2 runs
+        // enforcers with an empty param set.
+        pending = enforcer.check(ctx, {});
+    }
+    catch (error) {
+        return [
+            failFinding(enforcer.id, thrownCode(error), "failed with CDX-E901", "Fix the guard or retry the hook, then run codictator verify."),
+        ];
+    }
+    try {
+        return await withBudget(pending, enforcer.budgetMs);
+    }
+    catch (error) {
+        if (error === TIMED_OUT) {
+            return [
+                failFinding(enforcer.id, "CDX-E902", `exceeded its ${enforcer.budgetMs} ms budget (CDX-E902)`, "Give the guard a larger budget or a smaller scope, then retry."),
+            ];
+        }
+        return [
+            failFinding(enforcer.id, thrownCode(error), "failed with CDX-E901", "Fix the guard or retry the hook, then run codictator verify."),
+        ];
+    }
+}
+export function sortFindings(findings) {
+    return [...findings].sort(compareFindings);
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareFindingPaths(a, b) {
+    return compareText(a.path ?? "", b.path ?? "");
+}
+function compareFindingContent(a, b) {
+    if ((a.line ?? 0) !== (b.line ?? 0)) {
+        return (a.line ?? 0) - (b.line ?? 0);
+    }
+    return compareText(a.message, b.message);
+}
+function compareFindings(a, b) {
+    return (compareText(a.ruleId, b.ruleId) ||
+        compareFindingPaths(a, b) ||
+        compareFindingContent(a, b));
+}
+export function appendFailedFinding() {
+    return failFinding("core/engine", "CDX-E801", "could not record its verdict event (CDX-E801)", "Free disk space and fix permissions on .codictator/state/, then retry.");
+}