codictator 0.0.0 → 0.1.3

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

@@ -0,0 +1,39 @@
+import type { JsonSelect, OutputFormat } from "./external-output.ts";
+export interface ToolVersion {
+    readonly pin: string;
+    readonly probe: ReadonlyArray<string>;
+    readonly pattern: string;
+}
+export interface ToolDecl {
+    readonly id: string;
+    readonly command: ReadonlyArray<string>;
+    readonly version: ToolVersion;
+    readonly role: string | undefined;
+    readonly timeoutMs: number;
+    readonly envPass: ReadonlyArray<string>;
+}
+export type ExternalInput = "file" | "files" | "staged" | "diff" | "repo" | "stdin-json";
+export declare function isExternalInput(value: string): value is ExternalInput;
+export interface ExternalOutput {
+    readonly format: OutputFormat;
+    readonly source: "stdout" | "{out}";
+    readonly select: JsonSelect | undefined;
+    readonly pattern: RegExp | undefined;
+}
+export interface ExternalArgs {
+    readonly input: ExternalInput;
+    readonly output: ExternalOutput;
+    readonly passCodes: ReadonlyArray<number>;
+    readonly findingCodes: ReadonlyArray<number>;
+    readonly timeoutMs: number | undefined;
+}
+export interface ToolEvent {
+    readonly toolId: string;
+    readonly version: string;
+    readonly argvDigest: string;
+    readonly exitCode: number;
+    readonly findingCount: number;
+}
+export interface ExternalOptions {
+    readonly onToolEvent?: (event: ToolEvent) => void;
+}

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

@@ -0,0 +1,11 @@
+const EXTERNAL_INPUTS = [
+    "file",
+    "files",
+    "staged",
+    "diff",
+    "repo",
+    "stdin-json",
+];
+export function isExternalInput(value) {
+    return EXTERNAL_INPUTS.includes(value);
+}

package/dist/features/packs/enforcers/gate-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 resolveAgentAssetsPresent(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolvePerfBudgets(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveGuardrailManifest(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveHooksActive(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveWaiversValid(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;
+export declare function resolveCustomPackSelftest(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

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

@@ -0,0 +1,117 @@
+import { ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, tunableStringList, } from "./binding.js";
+import { baseEnforcer, parseMarkerInt, scopeMarkerTexts, } from "./health-measures.js";
+// The marker-driven guards below share one scope loop: bind the rule once,
+// walk the marker reports, and let each guard judge one file's markers. The
+// loop lives here so the resolvers hold only their own verdict and the
+// shared run the duplication gate flags stays in one place.
+function markerGuard(decl, rule, ports, judge) {
+    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)) {
+            judge(binding, file, markers, findings);
+        }
+        return findings;
+    }));
+}
+// SPEC §4.6.6 core/agent-assets-present: every required helper must be
+// present; the tunable defaults to knowledge-graph and token-saver (§5.12).
+export function resolveAgentAssetsPresent(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const required = tunableStringList(binding, "requiredHelpers") ?? [
+        "knowledge-graph",
+        "token-saver",
+    ];
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const present = new Set((markers.get("helpers") ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== ""));
+        const missing = required.filter((name) => !present.has(name));
+        if (missing.length > 0) {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: `required helper assets missing: ${missing.join(", ")}`,
+                vars: { path: file, detail: missing.join(", ") },
+            }));
+        }
+    });
+}
+// SPEC §9.3 core/perf-budgets: a measured p95 past the declared budget
+// flags; inside the budget stays quiet.
+export function resolvePerfBudgets(decl, rule, ports) {
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const rawP95 = markers.get("hook-p95-ms") ?? "";
+        const rawBudget = markers.get("budget-ms") ?? "";
+        const p95 = Number.parseFloat(rawP95);
+        const budget = Number.parseFloat(rawBudget);
+        if (Number.isFinite(p95) && Number.isFinite(budget) && p95 > budget) {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: `hook p95 of ${rawP95}ms is over the ${rawBudget}ms budget`,
+                vars: {
+                    path: file,
+                    detail: `hook p95 ${rawP95}ms`,
+                    limit: `${rawBudget}ms`,
+                },
+            }));
+        }
+    });
+}
+// SPEC §4.14.2 core/guardrail-manifest: a missing manifest flags.
+export function resolveGuardrailManifest(decl, rule, ports) {
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const manifest = markers.get("manifest") ?? "";
+        if (manifest === "" || manifest === "missing") {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: "guardrail manifest missing",
+                vars: { path: file, detail: "the guardrail manifest" },
+            }));
+        }
+    });
+}
+// SPEC §4.14.2 core/hooks-active: hooks not installed flags.
+export function resolveHooksActive(decl, rule, ports) {
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const hooks = markers.get("hooks") ?? "";
+        if (hooks === "" || hooks === "not installed") {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: "git hooks not installed",
+                vars: { path: file, detail: "the git hooks" },
+            }));
+        }
+    });
+}
+// SPEC §4.3.4 core/waivers-valid: a waiver past the pack's maxWaiverDays
+// (core: 90, §5.12) flags.
+export function resolveWaiversValid(decl, rule, ports) {
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const days = parseMarkerInt(markers, "waiver-days");
+        const max = parseMarkerInt(markers, "max") ?? 90;
+        if (days !== undefined && days > max) {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: `waiver at ${String(days)} days is past the ${String(max)} day bound`,
+                vars: { path: file, detail: `waiver at ${String(days)} days` },
+            }));
+        }
+    });
+}
+// SPEC §4.4.7 core/custom-pack-selftest: a changed custom pack whose
+// self-test did not pass flags.
+export function resolveCustomPackSelftest(decl, rule, ports) {
+    return markerGuard(decl, rule, ports, (guard, file, markers, findings) => {
+        const changed = markers.get("changed") ?? "";
+        const tested = markers.get("self-test") ?? "";
+        if (changed === "yes" && tested !== "passed") {
+            findings.push(findingFor(guard, {
+                path: file,
+                message: "changed custom pack with no passing self-test",
+                vars: { path: file, detail: "the changed custom pack" },
+            }));
+        }
+    });
+}

package/dist/features/packs/enforcers/health-abstraction.d.ts

@@ -0,0 +1,5 @@
+import type { Ports, 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 resolveNoSpeculativeAbstraction(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

package/dist/features/packs/enforcers/health-abstraction.js

@@ -0,0 +1,126 @@
+import { ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, isTestPath, selectFiles, } from "./binding.js";
+import { blankCode } from "./health-lex.js";
+import { baseEnforcer, isEntryFile, isMarkerFile, isTsFile, loadScopeText, parseMarkerInt, parseMarkers, } from "./health-measures.js";
+// SPEC §6.1: an abstraction is an interface or an abstract class; each
+// implements entry and each extends clause counts one implementation.
+const ABSTRACTION_PATTERN = /\binterface\s+([A-Za-z_$][\w$]*)|\babstract\s+class\s+([A-Za-z_$][\w$]*)/g;
+const IMPLEMENTS_PATTERN = /\bimplements\s+([A-Za-z_$][\w$]*(?:\s*,\s*[A-Za-z_$][\w$]*)*)/g;
+const EXTENDS_PATTERN = /\bextends\s+([A-Za-z_$][\w$]*)/g;
+function leafOf(path) {
+    const slash = path.lastIndexOf("/");
+    return slash < 0 ? path : path.slice(slash + 1);
+}
+// SPEC §5.6 + §3.4: ports files hold the contracts, module entries are the
+// public surface, and test trees carry doubles; none of them is judged.
+function isExemptAbstractionFile(path) {
+    return (isTestPath(path) ||
+        isEntryFile(path) ||
+        leafOf(path).toLowerCase() === "ports.ts");
+}
+function lineOfBlanked(blanked, at) {
+    let line = 1;
+    for (let index = 0; index < at && index < blanked.length; index += 1) {
+        if (blanked.charAt(index) === "\n") {
+            line += 1;
+        }
+    }
+    return line;
+}
+function compareFindings(left, right) {
+    const leftPath = left.path ?? "";
+    const rightPath = right.path ?? "";
+    if (leftPath < rightPath) {
+        return -1;
+    }
+    if (leftPath > rightPath) {
+        return 1;
+    }
+    return (left.line ?? 0) - (right.line ?? 0);
+}
+function collectAbstractions(blanked, file, declared, implementations) {
+    for (const match of blanked.matchAll(ABSTRACTION_PATTERN)) {
+        const name = match[1] ?? match[2] ?? "";
+        if (name === "" || declared.has(name)) {
+            continue;
+        }
+        declared.set(name, {
+            name,
+            file,
+            line: lineOfBlanked(blanked, match.index ?? 0),
+        });
+    }
+    for (const match of blanked.matchAll(IMPLEMENTS_PATTERN)) {
+        for (const part of (match[1] ?? "").split(",")) {
+            const reference = part.trim();
+            if (reference !== "") {
+                implementations.set(reference, (implementations.get(reference) ?? 0) + 1);
+            }
+        }
+    }
+    for (const match of blanked.matchAll(EXTENDS_PATTERN)) {
+        const reference = match[1] ?? "";
+        if (reference !== "") {
+            implementations.set(reference, (implementations.get(reference) ?? 0) + 1);
+        }
+    }
+}
+// SPEC §5.6: exactly one implements/extends of a declared abstraction
+// flags; zero or several stay clean. Exempt files neither declare nor
+// implement, so contracts, entries and doubles never judge.
+function judgeAbstractions(binding, declared, implementations) {
+    const findings = [];
+    for (const name of [...declared.keys()].sort()) {
+        if ((implementations.get(name) ?? 0) !== 1) {
+            continue;
+        }
+        const site = declared.get(name);
+        if (site === undefined) {
+            continue;
+        }
+        findings.push(findingFor(binding, {
+            path: site.file,
+            line: site.line,
+            message: `speculative abstraction ${name} has one implementation at ${site.file}:${String(site.line)}`,
+            vars: { path: site.file, line: String(site.line), value: name },
+        }));
+    }
+    return findings;
+}
+export function resolveNoSpeculativeAbstraction(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        const declared = new Map();
+        const implementations = new Map();
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text === undefined) {
+                continue;
+            }
+            if (isMarkerFile(file)) {
+                const markers = parseMarkers(text);
+                if ((markers.get("test-double") ?? "").trim().toLowerCase() === "true") {
+                    continue;
+                }
+                if (parseMarkerInt(markers, "implementations") === 1) {
+                    const name = markers.get("interface") ?? "type";
+                    findings.push(findingFor(binding, {
+                        path: file,
+                        line: 1,
+                        message: `speculative abstraction ${name} has one implementation in ${file}`,
+                        vars: { path: file, line: "1", value: name },
+                    }));
+                }
+                continue;
+            }
+            if (!isTsFile(file) || isExemptAbstractionFile(file)) {
+                continue;
+            }
+            collectAbstractions(blankCode(text), file, declared, implementations);
+        }
+        findings.push(...judgeAbstractions(binding, declared, implementations));
+        findings.sort(compareFindings);
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/health-duplication.d.ts

@@ -0,0 +1,5 @@
+import type { Ports, 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 resolveDuplication(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

package/dist/features/packs/enforcers/health-duplication.js

@@ -0,0 +1,197 @@
+import { ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, isTestPath, selectFiles, } from "./binding.js";
+import { blankCode } from "./health-lex.js";
+import { baseEnforcer, isMarkerFile, isTsFile, limitOf, loadScopeText, parseMarkerInt, parseMarkers, } from "./health-measures.js";
+// SPEC §6.1: words, numbers and single punctuation marks. String and
+// comment bodies are already blanked, so only live code shapes the run.
+const LEXEME_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]*|\d+(?:\.\d+)?|[^\sA-Za-z0-9_$]/g;
+function tokenizeSource(blanked) {
+    const starts = [0];
+    for (let index = 0; index < blanked.length; index += 1) {
+        if (blanked.charAt(index) === "\n") {
+            starts.push(index + 1);
+        }
+    }
+    const tokens = [];
+    for (const match of blanked.matchAll(LEXEME_PATTERN)) {
+        const at = match.index ?? 0;
+        let low = 0;
+        let high = starts.length - 1;
+        while (low < high) {
+            const mid = (low + high + 1) >> 1;
+            if ((starts[mid] ?? 0) <= at) {
+                low = mid;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        tokens.push({ text: match[0], line: low + 1 });
+    }
+    return tokens;
+}
+function pairKey(first, second) {
+    return JSON.stringify([first, second]);
+}
+function sharedLength(first, firstStart, second, secondStart) {
+    let length = 0;
+    while (firstStart + length < first.length &&
+        secondStart + length < second.length &&
+        first[firstStart + length]?.text === second[secondStart + length]?.text) {
+        length += 1;
+    }
+    return length;
+}
+function compareFindings(left, right) {
+    const leftPath = left.path ?? "";
+    const rightPath = right.path ?? "";
+    if (leftPath < rightPath) {
+        return -1;
+    }
+    if (leftPath > rightPath) {
+        return 1;
+    }
+    return (left.line ?? 0) - (right.line ?? 0);
+}
+// SPEC §5.6: the measure is a cross-file run of at least minTokens tokens.
+// The window index below finds every shared run; each file pair reports its
+// earliest shared site once, extended to the full shared run.
+function sharedRunFindings(binding, files, sources, minTokens) {
+    if (minTokens < 1) {
+        return [];
+    }
+    const tokened = new Map();
+    for (const file of files) {
+        const text = sources.get(file);
+        if (text === undefined || isMarkerFile(file)) {
+            continue;
+        }
+        if (!isTsFile(file) || isTestPath(file)) {
+            continue;
+        }
+        const lexemes = tokenizeSource(blankCode(text));
+        if (lexemes.length >= minTokens) {
+            tokened.set(file, lexemes);
+        }
+    }
+    const windows = new Map();
+    for (const [file, tokens] of tokened) {
+        for (let start = 0; start + minTokens <= tokens.length; start += 1) {
+            const key = tokens
+                .slice(start, start + minTokens)
+                .map((token) => token.text)
+                .join(" ");
+            let owners = windows.get(key);
+            if (owners === undefined) {
+                owners = new Map();
+                windows.set(key, owners);
+            }
+            if (!owners.has(file)) {
+                owners.set(file, start);
+            }
+        }
+    }
+    const pairs = new Map();
+    for (const key of [...windows.keys()].sort()) {
+        const owners = windows.get(key);
+        if (owners === undefined || owners.size < 2) {
+            continue;
+        }
+        const ranked = [...owners.keys()].sort();
+        for (let left = 0; left < ranked.length; left += 1) {
+            for (let right = left + 1; right < ranked.length; right += 1) {
+                const first = ranked[left] ?? "";
+                const second = ranked[right] ?? "";
+                const firstStart = owners.get(first) ?? 0;
+                const secondStart = owners.get(second) ?? 0;
+                const seen = pairs.get(pairKey(first, second));
+                if (seen === undefined) {
+                    pairs.set(pairKey(first, second), {
+                        first,
+                        firstStart,
+                        second,
+                        secondStart,
+                    });
+                }
+                else {
+                    pairs.set(pairKey(first, second), {
+                        first,
+                        firstStart: Math.min(seen.firstStart, firstStart),
+                        second,
+                        secondStart: Math.min(seen.secondStart, secondStart),
+                    });
+                }
+            }
+        }
+    }
+    const sites = new Map();
+    for (const entry of pairs.values()) {
+        const firstTokens = tokened.get(entry.first) ?? [];
+        const secondTokens = tokened.get(entry.second) ?? [];
+        const run = sharedLength(firstTokens, entry.firstStart, secondTokens, entry.secondStart);
+        const ends = [
+            { file: entry.first, line: firstTokens[entry.firstStart]?.line ?? 1 },
+            { file: entry.second, line: secondTokens[entry.secondStart]?.line ?? 1 },
+        ];
+        for (const end of ends) {
+            const key = pairKey(end.file, String(end.line));
+            const seen = sites.get(key);
+            if (seen === undefined || run > seen.run) {
+                sites.set(key, { file: end.file, line: end.line, run });
+            }
+        }
+    }
+    const findings = [];
+    for (const site of sites.values()) {
+        findings.push(findingFor(binding, {
+            path: site.file,
+            line: site.line,
+            message: `duplicated token run over the limit at ${site.file}:${String(site.line)}`,
+            vars: {
+                path: site.file,
+                line: String(site.line),
+                limit: String(minTokens),
+                value: String(site.run),
+            },
+        }));
+    }
+    return findings;
+}
+export function resolveDuplication(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const minTokens = limitOf(binding, "minTokens", 50);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        const files = selectFiles(ctx.scope.files, binding.scopeGlobs);
+        const sources = new Map();
+        for (const file of files) {
+            const text = await loadScopeText(ports, binding, file, findings);
+            if (text !== undefined) {
+                sources.set(file, text);
+            }
+        }
+        for (const file of files) {
+            const text = sources.get(file);
+            if (text === undefined || !isMarkerFile(file)) {
+                continue;
+            }
+            const duplicated = parseMarkerInt(parseMarkers(text), "duplicated-tokens");
+            if (duplicated !== undefined && duplicated > minTokens) {
+                findings.push(findingFor(binding, {
+                    path: file,
+                    line: 1,
+                    message: `duplicated token run over the limit in ${file}`,
+                    vars: {
+                        path: file,
+                        line: "1",
+                        limit: String(minTokens),
+                        value: String(duplicated),
+                    },
+                }));
+            }
+        }
+        findings.push(...sharedRunFindings(binding, files, sources, minTokens));
+        findings.sort(compareFindings);
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/health-lex-imports.d.ts

@@ -0,0 +1,5 @@
+export interface LiteralSpecifier {
+    readonly spec: string;
+    readonly line: number;
+}
+export declare function extractLiteralSpecifiers(text: string): Array<LiteralSpecifier>;