codictator 0.0.0 → 0.1.2

package/dist/features/workflow/writes.d.ts

@@ -0,0 +1,8 @@
+import type { Finding } from "../engine/index.ts";
+import type { ChangeClass, TaskRecord } from "./tasks.ts";
+export interface WriteCheckOptions {
+    readonly changeClass?: ChangeClass;
+    readonly bot?: boolean;
+}
+export declare function classifyChange(files: ReadonlyArray<string>): ChangeClass;
+export declare function checkWriteWithinPlan(task: TaskRecord | undefined, files: ReadonlyArray<string>, phase: string, options?: WriteCheckOptions): Promise<Array<Finding>>;

package/dist/features/workflow/writes.js

@@ -0,0 +1,96 @@
+// SPEC §4.12.3 L1: a write is blocked with no active task, when the
+// phase does not allow that file class, or outside files.allow. The message
+// names the phase and the command to move on or amend the plan.
+import { globMatch } from "../../kernel/index.js";
+function isDocPath(path) {
+    return path.startsWith("docs/") || path.endsWith(".md");
+}
+function isTestPath(path) {
+    return (path.includes("/tests/") ||
+        path.startsWith("tests/") ||
+        path.includes(".test."));
+}
+function isHistoryPath(path) {
+    return path.startsWith("docs/HISTORY/") || path.startsWith("docs/BUGS/");
+}
+function inAllow(path, allow) {
+    return allow.some((glob) => globMatch(glob, path));
+}
+// SPEC §4.12.2 change classes: manifests and lockfiles alone are deps and
+// need no task file; manifest-owned files alone run as guardrail.
+export function classifyChange(files) {
+    if (files.length === 0) {
+        return "code";
+    }
+    const manifestOwned = (path) => path === "package.json" ||
+        path === "package-lock.json" ||
+        path === ".nvmrc" ||
+        path.startsWith(".codictator/") ||
+        path.startsWith(".githooks/") ||
+        path.startsWith(".husky/");
+    if (files.every((path) => manifestOwned(path))) {
+        return "chore";
+    }
+    if (files.every((path) => isDocPath(path))) {
+        return "docs";
+    }
+    return "code";
+}
+export async function checkWriteWithinPlan(task, files, phase, options = {}) {
+    const changeClass = options.changeClass ?? classifyChange(files);
+    // SPEC §4.12.7 EC-12: deps class (manifests and lockfiles only) and bot
+    // dependency PRs owe no task file.
+    if (changeClass === "deps" ||
+        (options.bot === true && changeClass !== "code")) {
+        return [];
+    }
+    if (task === undefined) {
+        return [
+            {
+                ruleId: "core/workflow-gates",
+                message: "write with no active task on this branch",
+                remediation: "Run codictator task new --type <type> --title ... to open the branch task.",
+            },
+        ];
+    }
+    if (changeClass === "chore" || changeClass === "guardrail") {
+        return [];
+    }
+    const findings = [];
+    const allowedKind = (path) => {
+        // SPEC §4.12.7 EC-11: docs-only changes stay allowed in a code task.
+        if (isDocPath(path)) {
+            return true;
+        }
+        switch (phase) {
+            case "discovery":
+            case "planning": {
+                return isTestPath(path);
+            }
+            case "implementation":
+            case "validation": {
+                return inAllow(path, task.files.allow);
+            }
+            case "record": {
+                return isHistoryPath(path);
+            }
+            default: {
+                return false;
+            }
+        }
+    };
+    for (const path of [...files].sort()) {
+        if (!allowedKind(path)) {
+            const remediation = phase === "review" || phase === "integrate"
+                ? "Return to implementation to change code; the change voids proofs and review."
+                : "Run codictator task amend --allow <glob> to widen the plan; new tests return the task to planning.";
+            findings.push({
+                ruleId: "core/writes-within-plan",
+                path,
+                message: `write to ${path} is outside phase ${phase}`,
+                remediation,
+            });
+        }
+    }
+    return findings;
+}

package/dist/kernel/clock.d.ts

@@ -0,0 +1,4 @@
+import type { Clock, Instant } from "./index.ts";
+export declare class SystemClock implements Clock {
+    now(): Instant;
+}

package/dist/kernel/clock.js

@@ -0,0 +1,5 @@
+export class SystemClock {
+    now() {
+        return new Date().toISOString();
+    }
+}

package/dist/kernel/config-keys.d.ts

@@ -0,0 +1,2 @@
+export { readTomlKeys } from "./config-toml-keys.ts";
+export { readYamlKeys } from "./config-yaml-keys.ts";

package/dist/kernel/config-keys.js

@@ -0,0 +1,5 @@
+// SPEC §4.1.2: kernel barrel for the flat key readers. TOML parsing lives
+// in config-toml-keys.ts, YAML parsing in config-yaml-keys.ts; this file
+// only re-exports them so the kernel index surface is unchanged.
+export { readTomlKeys } from "./config-toml-keys.js";
+export { readYamlKeys } from "./config-yaml-keys.js";

package/dist/kernel/config-toml-keys.d.ts

@@ -0,0 +1,2 @@
+import { type Result } from "./result.ts";
+export declare function readTomlKeys(text: string, keys: ReadonlyArray<string>): Result<Readonly<Record<string, string>>>;

package/dist/kernel/config-toml-keys.js

@@ -0,0 +1,237 @@
+// SPEC §4.1.2: readTomlKeys reads only the flat or one-level keys
+// Codictator owns (Codex [features], pyproject [project] dependencies).
+// Anything unparseable for those keys returns an error, never a guess.
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+function decodeTomlEscape(next) {
+    if (next === "n") {
+        return "\n";
+    }
+    if (next === "t") {
+        return "\t";
+    }
+    if (next === '"' || next === "\\") {
+        return next;
+    }
+    return undefined;
+}
+function decodeTomlBasic(inner) {
+    let out = "";
+    let index = 0;
+    while (index < inner.length) {
+        const char = inner.charAt(index);
+        if (char === "\\") {
+            const decoded = decodeTomlEscape(inner.charAt(index + 1));
+            if (decoded === undefined) {
+                return undefined;
+            }
+            out += decoded;
+            index += 2;
+            continue;
+        }
+        if (char === "\n") {
+            return undefined;
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+function parseTomlString(raw) {
+    if (raw.startsWith('"')) {
+        if (!raw.endsWith('"') || raw.length < 2) {
+            return undefined;
+        }
+        return decodeTomlBasic(raw.slice(1, -1));
+    }
+    if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) {
+        return raw.slice(1, -1);
+    }
+    return undefined;
+}
+function parseTomlScalar(raw) {
+    const quoted = parseTomlString(raw);
+    if (quoted !== undefined) {
+        return quoted;
+    }
+    if (raw === "true" ||
+        raw === "false" ||
+        /^[+-]?[\d_]+(\.\d+)?([eE][+-]?\d+)?$/.test(raw)) {
+        return raw;
+    }
+    return undefined;
+}
+function scanTomlChar(state, char) {
+    if (char === '"' || char === "'") {
+        state.inString = char;
+    }
+    else if (char === "[") {
+        state.depth += 1;
+    }
+    else if (char === "]") {
+        state.depth -= 1;
+    }
+}
+// Scans one physical line, tracking bracket depth and string state across
+// lines. A `#` outside strings and brackets ends the scan.
+function scanTomlLine(raw, state) {
+    let index = 0;
+    while (index < raw.length) {
+        const char = raw.charAt(index);
+        if (state.inString !== "") {
+            if (char === "\\" && state.inString === '"') {
+                index += 2;
+                continue;
+            }
+            if (char === state.inString) {
+                state.inString = "";
+            }
+            index += 1;
+            continue;
+        }
+        if (char === "#" && state.depth === 0) {
+            return;
+        }
+        scanTomlChar(state, char);
+        index += 1;
+    }
+}
+// Collects logical lines: a value opening [ continues until brackets close.
+function tomlLogicalLines(text) {
+    const logical = [];
+    let pending = "";
+    const state = { depth: 0, inString: "" };
+    for (const raw of text.split("\n")) {
+        pending = pending === "" ? raw : `${pending}\n${raw}`;
+        scanTomlLine(raw, state);
+        if (state.depth < 0 || state.inString !== "") {
+            return undefined;
+        }
+        if (state.depth > 0) {
+            continue;
+        }
+        logical.push(pending);
+        pending = "";
+    }
+    if (pending !== "") {
+        return undefined;
+    }
+    return logical;
+}
+function parseTomlArray(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+        return undefined;
+    }
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === "") {
+        return [];
+    }
+    const items = [];
+    for (const part of inner.split(",")) {
+        if (part.trim() === "") {
+            continue;
+        }
+        const scalar = parseTomlScalar(part.trim());
+        if (scalar === undefined) {
+            return undefined;
+        }
+        items.push(scalar);
+    }
+    return items;
+}
+function parseTomlHeader(line) {
+    const header = /^\[([A-Za-z0-9_.-]+)\]$/.exec(line);
+    if (header === null) {
+        return undefined;
+    }
+    return header[1] ?? "";
+}
+function enterTomlSection(sections, name) {
+    let section = sections.get(name);
+    if (section === undefined) {
+        section = new Map();
+        sections.set(name, section);
+    }
+    return section;
+}
+function parseTomlAssignment(line) {
+    const assignment = /^([A-Za-z0-9_.-]+)\s*=\s*([\s\S]+)$/.exec(line);
+    if (assignment === null) {
+        return undefined;
+    }
+    const key = (assignment[1] ?? "").trim();
+    const rawValue = (assignment[2] ?? "").trim();
+    if (key === "" || rawValue === "") {
+        return undefined;
+    }
+    return { key, rawValue };
+}
+function parseTomlValue(rawValue) {
+    if (rawValue.startsWith("[")) {
+        const array = parseTomlArray(rawValue);
+        return array ?? parseTomlScalar(rawValue);
+    }
+    return parseTomlScalar(rawValue);
+}
+function parseToml(text) {
+    const logical = tomlLogicalLines(text);
+    if (logical === undefined) {
+        return undefined;
+    }
+    const sections = new Map();
+    const top = new Map();
+    sections.set("", top);
+    let current = top;
+    for (const raw of logical) {
+        const line = raw.trim();
+        if (line === "") {
+            continue;
+        }
+        const header = parseTomlHeader(line);
+        if (header !== undefined) {
+            current = enterTomlSection(sections, header);
+            continue;
+        }
+        const assignment = parseTomlAssignment(line);
+        if (assignment === undefined) {
+            return undefined;
+        }
+        const value = parseTomlValue(assignment.rawValue);
+        if (value === undefined || current.has(assignment.key)) {
+            return undefined;
+        }
+        current.set(assignment.key, value);
+    }
+    return { sections };
+}
+function lookupToml(sections, key) {
+    const dot = key.indexOf(".");
+    if (dot < 0) {
+        const value = sections.get("")?.get(key);
+        if (value === undefined) {
+            return undefined;
+        }
+        return Array.isArray(value) ? value.join("\n") : value;
+    }
+    const section = sections.get(key.slice(0, dot));
+    const value = section?.get(key.slice(dot + 1));
+    if (value === undefined) {
+        return undefined;
+    }
+    return Array.isArray(value) ? value.join("\n") : value;
+}
+export function readTomlKeys(text, keys) {
+    const parsed = parseToml(text);
+    if (parsed === undefined) {
+        return err(makeError("CDX-E101", "TOML is unparseable", "Fix the TOML syntax; keys are read exactly, never guessed."));
+    }
+    const found = {};
+    for (const key of keys) {
+        const value = lookupToml(parsed.sections, key);
+        if (value !== undefined) {
+            found[key] = value;
+        }
+    }
+    return ok(found);
+}

package/dist/kernel/config-yaml-keys.d.ts

@@ -0,0 +1,2 @@
+import { type Result } from "./result.ts";
+export declare function readYamlKeys(text: string, keys: ReadonlyArray<string>): Result<Readonly<Record<string, string>>>;

package/dist/kernel/config-yaml-keys.js

@@ -0,0 +1,177 @@
+// SPEC §4.1.2: readYamlKeys reads only the flat or one-level keys
+// Codictator owns (Dependabot updates). Anything unparseable for those keys
+// returns an error, never a guess.
+import { makeError } from "./errors.js";
+import { stableStringify } from "./json.js";
+import { err, ok } from "./result.js";
+function yamlScalar(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed === "~" || trimmed === "null") {
+        return "";
+    }
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2)) {
+        return trimmed.slice(1, -1);
+    }
+    if (/[:#[\]{}|>&*!%@`,]/.test(trimmed.charAt(0))) {
+        return undefined;
+    }
+    if (trimmed.includes(" #")) {
+        return trimmed.slice(0, trimmed.indexOf(" #")).trimEnd();
+    }
+    return trimmed;
+}
+function yamlIndent(line) {
+    let count = 0;
+    while (line.charAt(count) === " ") {
+        count += 1;
+    }
+    return count;
+}
+// Indent of the next content line, or undefined when none follows.
+function nextIndent(lines, start) {
+    for (let index = start; index < lines.length; index += 1) {
+        const raw = lines[index] ?? "";
+        if (raw.trim() === "" || raw.trimStart().startsWith("#")) {
+            continue;
+        }
+        return yamlIndent(raw);
+    }
+    return undefined;
+}
+// Minimal block parser: mappings nested by indentation plus sequences of
+// scalars. Anything else (tabs, anchors, flow maps, deep structures beyond
+// the depth cap) is unparseable, never guessed.
+function parseYamlBlock(lines, start, indent, depth) {
+    if (depth > 8) {
+        return undefined;
+    }
+    const mapping = {};
+    const sequence = [];
+    let index = start;
+    while (index < lines.length) {
+        const raw = lines[index] ?? "";
+        if (raw.trim() === "" || raw.trimStart().startsWith("#")) {
+            index += 1;
+            continue;
+        }
+        if (raw.includes("\t")) {
+            return undefined;
+        }
+        const at = yamlIndent(raw);
+        if (at < indent) {
+            break;
+        }
+        if (at > indent) {
+            return undefined;
+        }
+        const body = raw.slice(indent);
+        if (body.startsWith("- ") || body === "-") {
+            const item = body === "-" ? "" : body.slice(2);
+            const scalar = yamlScalar(item);
+            if (scalar === undefined) {
+                return undefined;
+            }
+            sequence.push(scalar);
+            index += 1;
+            continue;
+        }
+        const colon = body.indexOf(":");
+        if (colon < 0) {
+            return undefined;
+        }
+        const key = body.slice(0, colon).trim();
+        if (key === "" || /[\s#[\]{}]/.test(key)) {
+            return undefined;
+        }
+        const rest = body.slice(colon + 1).trim();
+        index += 1;
+        if (rest !== "") {
+            const scalar = yamlScalar(rest);
+            if (scalar === undefined) {
+                return undefined;
+            }
+            mapping[key] = scalar;
+            continue;
+        }
+        const childIndent = nextIndent(lines, index);
+        if (childIndent === undefined || childIndent <= indent) {
+            mapping[key] = "";
+            continue;
+        }
+        const child = parseYamlBlock(lines, index, childIndent, depth + 1);
+        if (child === undefined) {
+            return undefined;
+        }
+        mapping[key] = child.node;
+        index = child.next;
+    }
+    if (sequence.length > 0) {
+        if (Object.keys(mapping).length > 0) {
+            return undefined;
+        }
+        return { node: sequence, next: index };
+    }
+    return { node: mapping, next: index };
+}
+function parseYaml(text) {
+    if (text.includes("\t")) {
+        return undefined;
+    }
+    const lines = text.split("\n");
+    const parsed = parseYamlBlock(lines, 0, 0, 0);
+    if (parsed === undefined || parsed.next !== lines.length) {
+        return undefined;
+    }
+    return parsed.node;
+}
+function lookupYaml(node, key) {
+    const dot = key.indexOf(".");
+    const head = dot < 0 ? key : key.slice(0, dot);
+    const tail = dot < 0 ? undefined : key.slice(dot + 1);
+    let current = node;
+    if (typeof current !== "object" ||
+        current === null ||
+        Array.isArray(current)) {
+        return undefined;
+    }
+    const child = current[head];
+    if (child === undefined) {
+        return undefined;
+    }
+    current = child;
+    if (tail !== undefined) {
+        return lookupYaml(current, tail);
+    }
+    if (typeof current === "string") {
+        return current;
+    }
+    if (Array.isArray(current)) {
+        const flat = [];
+        for (const item of current) {
+            if (typeof item !== "string") {
+                return undefined;
+            }
+            flat.push(item);
+        }
+        return flat.join("\n");
+    }
+    return stableStringify(current);
+}
+export function readYamlKeys(text, keys) {
+    if (text.trim() === "") {
+        return ok({});
+    }
+    const parsed = parseYaml(text);
+    if (parsed === undefined) {
+        return err(makeError("CDX-E101", "YAML is unparseable", "Fix the YAML syntax; keys are read exactly, never guessed."));
+    }
+    const found = {};
+    for (const key of keys) {
+        const value = lookupYaml(parsed, key);
+        if (value !== undefined) {
+            found[key] = value;
+        }
+    }
+    return ok(found);
+}

package/dist/kernel/contracts.d.ts

@@ -0,0 +1,76 @@
+export type Instant = string;
+export declare const TRIGGERS: readonly ["pre-tool", "post-tool", "prompt", "startup", "compact", "review", "scheduled"];
+export type Trigger = (typeof TRIGGERS)[number];
+export interface CheckContext {
+    readonly trigger: Trigger;
+    readonly scope: Scope;
+    readonly now: Instant;
+    readonly configHash: string;
+}
+export interface Scope {
+    readonly files: ReadonlyArray<string>;
+    readonly sessionId?: string;
+    readonly proposedContent?: string;
+    readonly shellCommand?: string;
+    readonly proposedPaths?: ReadonlyArray<string>;
+}
+export interface Finding {
+    readonly ruleId: string;
+    readonly path?: string;
+    readonly line?: number;
+    readonly code?: string;
+    readonly message: string;
+    readonly remediation: string;
+}
+export type Decision = "allow" | "advise" | "block" | "escalate";
+export interface Enforcer {
+    readonly id: string;
+    readonly kinds: ReadonlyArray<Trigger>;
+    readonly budgetMs: number;
+    readonly check: (ctx: CheckContext, params: Readonly<Record<string, unknown>>) => Promise<Array<Finding>>;
+}
+export interface PackRuleParam {
+    readonly type: "integer" | "number" | "string[]";
+    readonly default: unknown;
+    readonly bound: unknown;
+    readonly stricter: "lower" | "higher" | "subset" | "superset" | "policy";
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface PackRule {
+    readonly id: string;
+    readonly family: string;
+    readonly tier: string;
+    readonly statement: string;
+    readonly reason: string;
+    readonly remediation: string;
+    readonly enforcer: string;
+    readonly triggers: ReadonlyArray<string>;
+    readonly scope: ReadonlyArray<string>;
+    readonly params: Readonly<Record<string, PackRuleParam>>;
+    readonly ratchet?: unknown;
+    readonly measureVersion: number;
+    readonly fixtures: {
+        readonly violating: ReadonlyArray<string>;
+        readonly passing: ReadonlyArray<string>;
+    };
+}
+export interface PackManifest {
+    readonly id: string;
+    readonly version: string;
+    readonly description: string;
+    readonly rules: ReadonlyArray<PackRule>;
+    readonly enforcers: ReadonlyArray<unknown>;
+    readonly drivers: ReadonlyArray<unknown>;
+    readonly extractors: ReadonlyArray<unknown>;
+    readonly measures: ReadonlyArray<unknown>;
+    readonly capabilities: ReadonlyArray<unknown>;
+    readonly assets: ReadonlyArray<unknown>;
+    readonly maxWaiverDays: number;
+}
+export interface Pack {
+    readonly manifest: PackManifest;
+    readonly enforcers: ReadonlyArray<Enforcer>;
+    readonly drivers: ReadonlyArray<unknown>;
+    readonly assets: ReadonlyArray<unknown>;
+}

package/dist/kernel/contracts.js

@@ -0,0 +1,9 @@
+export const TRIGGERS = [
+    "pre-tool",
+    "post-tool",
+    "prompt",
+    "startup",
+    "compact",
+    "review",
+    "scheduled",
+];

package/dist/kernel/entry.d.ts

@@ -0,0 +1 @@
+export declare function isEntryModule(argvOne: string | undefined, metaUrl: string): boolean;

package/dist/kernel/entry.js

@@ -0,0 +1,31 @@
+// SPEC §4.19: the built bin entry answers only when the executed path
+// resolves to this module. Under an npm-workspace symlink (or npm link)
+// argv[1] keeps the symlink spelling while the ESM loader resolves
+// import.meta.url to the real path, so a plain string compare silently
+// skips the CLI and exits 0. Comparing realpaths keeps linked installs
+// working; a path that cannot resolve falls back to its spelling, so a
+// missing entry still compares false instead of throwing.
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function resolved(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+export function isEntryModule(argvOne, metaUrl) {
+    if (argvOne === undefined || argvOne === "") {
+        return false;
+    }
+    let entry;
+    try {
+        entry = fileURLToPath(metaUrl);
+    }
+    catch {
+        return false;
+    }
+    return resolved(path.resolve(argvOne)) === resolved(entry);
+}

package/dist/kernel/env.d.ts

@@ -0,0 +1,4 @@
+import type { Env } from "./index.ts";
+export declare class NodeEnv implements Env {
+    get(name: string): string | undefined;
+}

package/dist/kernel/env.js

@@ -0,0 +1,5 @@
+export class NodeEnv {
+    get(name) {
+        return process.env[name];
+    }
+}