codictator 0.0.0 → 0.1.2

package/dist/builtin-packs/typescript/titles.ts

@@ -0,0 +1,184 @@
+// SPEC §6.1 test titles and filters: `test`/`it`/`describe` string-literal
+// titles joined outer to inner; a title built from a variable is unknown and
+// the spec trace fails it (§6.4 EC-3). Filters map to the runner flags:
+// `--test-name-pattern` (node:test), `-t` (Vitest, Jest).
+
+import { matchWordAt, skipTrivia } from "./extract-words.ts";
+import { lineAtIndex, lineStartsFor } from "./lex.ts";
+
+export interface TestTitle {
+	readonly suite: ReadonlyArray<string>;
+	readonly title: string;
+	readonly line: number;
+	readonly literal: boolean;
+}
+
+const SUITE_CALLS: ReadonlyArray<string> = ["describe"];
+const TEST_CALLS: ReadonlyArray<string> = ["test", "it"];
+const FOCUS_PREFIXES: ReadonlyArray<string> = ["", "x", "f"];
+
+function callNameAt(text: string, index: number): string | undefined {
+	for (const prefix of FOCUS_PREFIXES) {
+		for (const call of [...SUITE_CALLS, ...TEST_CALLS]) {
+			const bare = `${prefix}${call}`;
+			for (const suffix of [".skip", ".only", ".todo"]) {
+				if (matchWordAt(text, index, `${bare}${suffix}`)) {
+					return `${bare}${suffix}`;
+				}
+			}
+			if (matchWordAt(text, index, bare)) {
+				return bare;
+			}
+		}
+	}
+	return undefined;
+}
+
+// A literal title is a plain string; concatenation, variables, template
+// holes and non-strings are unknown, never guessed.
+function readTitleAt(
+	text: string,
+	index: number,
+): {
+	readonly title: string;
+	readonly literal: boolean;
+	readonly next: number;
+} {
+	const quote = text.charAt(index);
+	if (quote !== "'" && quote !== '"' && quote !== "`") {
+		let cursor = index;
+		let depth = 0;
+		while (cursor < text.length) {
+			const char = text.charAt(cursor);
+			if (char === "(" || char === "[" || char === "{") {
+				depth += 1;
+			} else if (char === ")" || char === "]" || char === "}") {
+				if (depth === 0) {
+					break;
+				}
+				depth -= 1;
+			} else if (char === "," && depth === 0) {
+				break;
+			}
+			cursor += 1;
+		}
+		return { title: "unknown", literal: false, next: cursor };
+	}
+	let title = "";
+	let cursor = index + 1;
+	while (cursor < text.length) {
+		const char = text.charAt(cursor);
+		if (char === "\\") {
+			title += text.slice(cursor, cursor + 2);
+			cursor += 2;
+			continue;
+		}
+		if (quote === "`" && char === "$" && text.charAt(cursor + 1) === "{") {
+			return { title: "unknown", literal: false, next: cursor };
+		}
+		if (char === quote) {
+			return { title, literal: true, next: cursor + 1 };
+		}
+		if (char === "\n" && quote !== "`") {
+			return { title: "unknown", literal: false, next: cursor };
+		}
+		title += char;
+		cursor += 1;
+	}
+	return { title: "unknown", literal: false, next: cursor };
+}
+
+interface Frame {
+	readonly title: string;
+	readonly depth: number;
+}
+
+function isSuiteName(base: string): boolean {
+	return base === "describe" || base === "xdescribe" || base === "fdescribe";
+}
+
+function popSuitesForDepth(stack: Array<Frame>, depth: number): void {
+	while (stack.length > 0) {
+		const top = stack[stack.length - 1];
+		if (top !== undefined && top.depth < depth) {
+			break;
+		}
+		stack.pop();
+	}
+}
+
+function recordTitle(
+	stack: Array<Frame>,
+	found: Array<TestTitle>,
+	starts: ReadonlyArray<number>,
+	index: number,
+	depth: number,
+	isSuite: boolean,
+	title: { readonly title: string; readonly literal: boolean },
+): void {
+	if (isSuite) {
+		if (title.literal) {
+			stack.push({ title: title.title, depth });
+		}
+		return;
+	}
+	found.push({
+		suite: stack.map((frame) => frame.title),
+		title: title.title,
+		line: lineAtIndex(starts, index),
+		literal: title.literal,
+	});
+}
+
+// Describes nest by brace depth; a closing brace past the entry depth pops
+// the suite, so sibling suites never leak into each other.
+export function extractTestTitles(text: string): Array<TestTitle> {
+	const starts = lineStartsFor(text);
+	const found: Array<TestTitle> = [];
+	const stack: Array<Frame> = [];
+	let depth = 0;
+	let index = 0;
+	while (index < text.length) {
+		const char = text.charAt(index);
+		if (char === "{") {
+			depth += 1;
+			index += 1;
+			continue;
+		}
+		if (char === "}") {
+			depth -= 1;
+			popSuitesForDepth(stack, depth);
+			index += 1;
+			continue;
+		}
+		const call = callNameAt(text, index);
+		if (call === undefined) {
+			index += 1;
+			continue;
+		}
+		const base = call.split(".", 1)[0] ?? call;
+		const open = skipTrivia(text, index + call.length);
+		if (text.charAt(open) !== "(") {
+			index += 1;
+			continue;
+		}
+		const arg = skipTrivia(text, open + 1);
+		const title = readTitleAt(text, arg);
+		recordTitle(stack, found, starts, index, depth, isSuiteName(base), title);
+		index = title.next;
+	}
+	return found;
+}
+
+export type TestRunner = "node" | "vitest" | "jest";
+
+// SPEC §6.1: runner filter flags for a title pattern.
+export function testFilterArg(
+	runner: TestRunner,
+	pattern: string,
+): ReadonlyArray<string> {
+	if (runner === "node") {
+		return ["--test-name-pattern", pattern];
+	}
+	return ["-t", pattern];
+}

package/dist/cli/baseline.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleBaseline(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/baseline.js

@@ -0,0 +1,67 @@
+// SPEC §4.3.5 + §4.19.2: show the ratchet baseline, or capture it from the
+// current findings (human-only capture).
+import { parseArgs } from "node:util";
+import { captureBaseline } from "../features/remediation/index.js";
+import { ok, parseJson, stableStringify } from "../kernel/index.js";
+import { checkHuman, commandEnv, fail, needRoot, printHuman, printJson, readStateText, usageError, writeStateText, } from "./shared.js";
+async function baselineShow(req, root) {
+    if (req.args.length !== 1) {
+        return usageError("usage: codictator baseline show");
+    }
+    const text = await readStateText(root, ".codictator/baseline.json");
+    if (text === undefined) {
+        printHuman("no baseline captured", req.quiet);
+        if (req.json) {
+            printJson({ baseline: null });
+        }
+        return ok(0);
+    }
+    if (req.json) {
+        const parsed = parseJson(text);
+        printJson({ baseline: parsed.ok ? parsed.value : text });
+    }
+    else {
+        printHuman(text.trimEnd(), req.quiet);
+    }
+    return ok(0);
+}
+async function baselineCapture(req, root) {
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { rule: { type: "string" } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0 || (parsed.values.rule ?? "") === "") {
+            return usageError("usage: codictator baseline capture --rule <id>");
+        }
+    }
+    catch {
+        return usageError("usage: codictator baseline capture --rule <id>");
+    }
+    const captured = await captureBaseline(root, []);
+    if (!captured.ok) {
+        return fail("CDX-E903", captured.error.message, captured.error.remediation, req.json);
+    }
+    const saved = await writeStateText(root, ".codictator/baseline.json", `${stableStringify(captured.value)}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, req.json);
+    }
+    printHuman("baseline captured", req.quiet);
+    return ok(0);
+}
+export async function handleBaseline(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "show" && sub !== "capture") {
+        return usageError("usage: codictator baseline <show|capture --rule <id>>");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    return sub === "show" ? baselineShow(req, root) : baselineCapture(req, root);
+}

package/dist/cli/ci-bot-change.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function ciRecordBotChange(req: CommandRequest): Result<number>;

package/dist/cli/ci-bot-change.js

@@ -0,0 +1,54 @@
+// SPEC §4.15: bot-change recording for ci record-bot-change. Split from
+// ci.ts by responsibility (core/file-size): this module owns the
+// record-bot-change flags and verdict, ci.ts owns the dispatch.
+import { parseArgs } from "node:util";
+import { qualifyBotChange } from "../features/ci/index.js";
+import { ok } from "../kernel/index.js";
+import { printHuman, printJson, usageError } from "./shared.js";
+function parseRecordFlags(req) {
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: {
+                author: { type: "string" },
+                files: { type: "string", multiple: true, default: [] },
+                fork: { type: "boolean", default: false },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        if ((parsed.values.author ?? "") === "" ||
+            (parsed.values.files ?? []).length === 0) {
+            return undefined;
+        }
+        return {
+            author: parsed.values.author ?? "",
+            files: [...(parsed.values.files ?? [])],
+            fork: parsed.values.fork ?? false,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function ciRecordBotChange(req) {
+    const flags = parseRecordFlags(req);
+    if (flags === undefined) {
+        return usageError("usage: codictator ci record-bot-change --author <bot> --files <f> ... [--fork]");
+    }
+    const planned = qualifyBotChange({
+        author: flags.author,
+        filesChanged: flags.files,
+        isFork: flags.fork,
+        trailerExempt: [],
+    });
+    if (req.json) {
+        printJson(planned);
+    }
+    else {
+        printHuman(`bot change qualifies: ${planned.qualifies}, write commit: ${planned.writeCommit}`, req.quiet);
+    }
+    return planned.findings.length === 0 ? ok(0) : ok(1);
+}

package/dist/cli/ci-range.d.ts

@@ -0,0 +1,18 @@
+import type { Config } from "../features/config/index.ts";
+import type { CommitInRange } from "../features/integrity/index.ts";
+import type { Result } from "../kernel/index.ts";
+import type { CommandPorts } from "./shared.ts";
+export interface CiVerifyFlags {
+    readonly base: string | undefined;
+    readonly head: string | undefined;
+}
+export interface CiRange {
+    readonly base: string;
+    readonly head: string;
+}
+export declare function parseCiVerifyFlags(args: ReadonlyArray<string>): CiVerifyFlags | undefined;
+export declare function ciPackIds(root: string, engineVersion?: string): Promise<ReadonlyArray<string>>;
+export declare function resolveCiRange(ports: CommandPorts, flags: CiVerifyFlags): Promise<Result<CiRange | undefined>>;
+export declare function rangeMessages(ports: CommandPorts, base: string, head: string): Promise<string>;
+export declare function trailerExemptFrom(config: Config): ReadonlyArray<string>;
+export declare function rangeCommits(ports: CommandPorts, base: string, head: string): Promise<Result<ReadonlyArray<CommitInRange>>>;

package/dist/cli/ci-range.js

@@ -0,0 +1,228 @@
+// SPEC §4.15.1 + §4.7.1: the ci verify change scope. The range comes from
+// --base/--head (the §4.15.6 external-CI form) else GITHUB_EVENT_PATH;
+// the enforcers judge the range's files plus its commit messages. Split
+// from ci.ts by responsibility (core/file-size): this file owns the
+// scope, ci.ts owns the verdict.
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { err, ok, parseJson, readHostText } from "../kernel/index.js";
+import { loadRepoConfig } from "./shared.js";
+// SPEC §4.19.2: `ci verify` takes no positionals; the range is an
+// optional --base/--head pair (the §4.15.6 external-CI form). Anything
+// else is a usage error.
+export function parseCiVerifyFlags(args) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {
+                base: { type: "string" },
+                head: { type: "string" },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        if ((parsed.values.base === undefined) !==
+            (parsed.values.head === undefined)) {
+            return undefined;
+        }
+        return { base: parsed.values.base, head: parsed.values.head };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function ciPackIds(root, engineVersion = ENGINE_VERSION) {
+    const configured = await loadRepoConfig(root, undefined, engineVersion);
+    if (!configured.ok) {
+        return [];
+    }
+    return configured.value.effective.config.packs.map((entry) => entry.id);
+}
+async function runCiGit(ports, argv) {
+    const ran = await ports.proc.run(argv, {
+        cwd: ports.root,
+        env: {},
+        timeoutMs: 30000,
+        maxOutputBytes: 8 * 1024 * 1024,
+    });
+    if (ran.timedOut || ran.truncated || ran.code !== 0) {
+        return undefined;
+    }
+    return ran.stdout;
+}
+// SPEC §4.15.1: the range comes from --base/--head (the §4.15.6
+// external-CI form), else GITHUB_EVENT_PATH (PR base and head SHAs, or
+// `before`/`after` for pushes). Without either there is no change to
+// judge: L4 runs the repo-wide rules only (§4.3.2). The event file is read
+// kernel-owned — it lives outside the repo, past the confined Fs port —
+// and a set but unreadable event path fails closed instead of silently
+// skipping the change scope.
+export async function resolveCiRange(ports, flags) {
+    if (flags.base !== undefined && flags.head !== undefined) {
+        return ok({ base: flags.base, head: flags.head });
+    }
+    const eventPath = ports.env.get("GITHUB_EVENT_PATH");
+    if (eventPath === undefined || eventPath === "") {
+        return ok(undefined);
+    }
+    const text = await readHostText(eventPath);
+    if (!text.ok) {
+        return err(text.error);
+    }
+    const parsed = parseJson(text.value);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) {
+        return err({
+            code: "CDX-E303",
+            message: "CI event payload is unparseable, so the verify range is unknown",
+            remediation: "Re-run with --base <sha> --head <sha> for the change under review.",
+        });
+    }
+    const body = parsed.value;
+    const prBase = body.pull_request?.base?.sha;
+    const prHead = body.pull_request?.head?.sha;
+    const after = body.after;
+    const base = typeof prBase === "string" && prBase !== "" ? prBase : body.before;
+    // SPEC §4.15.7 EC-1: pull-request events carry no top-level `after`;
+    // the head rides on pull_request.head.sha instead. A push carries
+    // `after`, which wins when present.
+    let head;
+    if (typeof after === "string" && after !== "") {
+        head = after;
+    }
+    else if (typeof prHead === "string" && prHead !== "") {
+        head = prHead;
+    }
+    if (typeof base !== "string" || base === "" || head === undefined) {
+        return err({
+            code: "CDX-E303",
+            message: "CI event payload names no verify range",
+            remediation: "Re-run with --base <sha> --head <sha> for the change under review.",
+        });
+    }
+    // SPEC §4.15.7 EC-3: push of a new branch (no `before`) — the base is
+    // the merge-base with the default branch.
+    if (/^0+$/.test(base)) {
+        return mergeBaseFallback(ports, head);
+    }
+    return ok({ base, head });
+}
+async function mergeBaseFallback(ports, head) {
+    const symref = await runCiGit(ports, [
+        "git",
+        "symbolic-ref",
+        "refs/remotes/origin/HEAD",
+    ]);
+    const branch = symref?.trim().split("/").pop();
+    if (branch === undefined || branch === "") {
+        return ok(undefined);
+    }
+    const merged = await runCiGit(ports, [
+        "git",
+        "merge-base",
+        "HEAD",
+        `origin/${branch}`,
+    ]);
+    if (merged === undefined || merged.trim() === "") {
+        return ok(undefined);
+    }
+    return ok({ base: merged.trim(), head });
+}
+// SPEC §4.7.1: L4 covers every commit message in range, so the range's full
+// bodies ride as proposed content. An unreadable log degrades to the file
+// scope instead of failing the run.
+export async function rangeMessages(ports, base, head) {
+    const bodies = await runCiGit(ports, [
+        "git",
+        "log",
+        "--format=%B",
+        `${base}..${head}`,
+    ]);
+    return bodies ?? "";
+}
+// SPEC §4.14.2 core/no-bypass at L4: the trailer exemption is the
+// config.integrity.trailerExempt bot list. A missing or misshapen value
+// narrows to empty, so unknown authors need the trailer (fail-closed).
+export function trailerExemptFrom(config) {
+    const integrity = config.integrity;
+    if (typeof integrity !== "object" || integrity === null) {
+        return [];
+    }
+    if (!("trailerExempt" in integrity)) {
+        return [];
+    }
+    const value = integrity.trailerExempt;
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
+const COMMIT_FIELD = "\x1f";
+const COMMIT_RECORD = "\x1e";
+function splitCommitFields(record) {
+    const first = record.indexOf(COMMIT_FIELD);
+    const second = first < 0 ? -1 : record.indexOf(COMMIT_FIELD, first + 1);
+    const third = second < 0 ? -1 : record.indexOf(COMMIT_FIELD, second + 1);
+    if (first < 0 || second < 0 || third < 0) {
+        return undefined;
+    }
+    const sha = record.slice(0, first);
+    const author = record.slice(second + 1, third);
+    if (sha === "" || author === "") {
+        return undefined;
+    }
+    return {
+        sha,
+        parents: record
+            .slice(first + 1, second)
+            .split(" ")
+            .filter((parent) => parent !== ""),
+        author,
+        body: record.slice(third + 1),
+    };
+}
+function parseCommitRange(text) {
+    const unparseable = err({
+        code: "CDX-E303",
+        message: "CI commit range is unparseable, so the trailer gate is unverified",
+        remediation: "Re-run with --base <sha> --head <sha> for the change under review.",
+    });
+    const records = text.split(COMMIT_RECORD);
+    if (records.length > 0 && (records[records.length - 1] ?? "").trim() === "") {
+        records.pop();
+    }
+    const commits = [];
+    for (const record of records) {
+        const fields = splitCommitFields(record);
+        if (fields === undefined) {
+            return unparseable;
+        }
+        commits.push({
+            sha: fields.sha,
+            message: fields.body,
+            author: fields.author,
+            isMerge: fields.parents.length > 1,
+        });
+    }
+    return ok(commits);
+}
+// SPEC §4.14.2 core/no-bypass at L4: list the range's commits for the
+// trailer check. An unreadable range fails closed: skipping the gate would
+// let a trailer-less commit through, the defect this wiring fixes.
+export async function rangeCommits(ports, base, head) {
+    const listed = await runCiGit(ports, [
+        "git",
+        "log",
+        `--format=%H${COMMIT_FIELD}%P${COMMIT_FIELD}%an${COMMIT_FIELD}%B${COMMIT_RECORD}`,
+        `${base}..${head}`,
+    ]);
+    if (listed === undefined) {
+        return err({
+            code: "CDX-E503",
+            message: `cannot list commits in ${base}..${head}, so the trailer gate is unverified`,
+            remediation: "Re-run with a reachable --base <sha> --head <sha> for the change under review.",
+        });
+    }
+    return parseCommitRange(listed);
+}

package/dist/cli/ci-summary.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "../kernel/index.ts";
+export declare function isUnverifiableFinding(finding: Finding): boolean;
+export declare function ciSummaryFor(findings: ReadonlyArray<Finding>): string;

package/dist/cli/ci-summary.js

@@ -0,0 +1,45 @@
+// SPEC §4.18.4: the wired CI summary for `ci verify`, in §4.18.4 order
+// (integrity, blocking with remediation, then unverifiable). Past 60 KB
+// buildCiSummary collapses to counts with the command to see all. Split
+// from ci.ts by responsibility (core/file-size): this file shapes the
+// summary, ci.ts folds findings into the verdict.
+import { buildCiSummary, } from "../features/audit/index.js";
+// SPEC §4.18.4: one finding as one summary line; the remediation rides along
+// so the summary stays actionable without the findings list.
+function summaryLine(finding) {
+    return `${finding.ruleId}: ${finding.message} Do instead: ${finding.remediation}`;
+}
+function isIntegrityFinding(finding) {
+    return (finding.ruleId.includes("manifest") || finding.ruleId.includes("integrity"));
+}
+export function isUnverifiableFinding(finding) {
+    return /advise|cannot confirm|unreadable|unverified/i.test(finding.message);
+}
+export function ciSummaryFor(findings) {
+    const integrity = [];
+    const blocking = [];
+    const unverifiable = [];
+    for (const finding of findings) {
+        const line = summaryLine(finding);
+        if (isIntegrityFinding(finding)) {
+            integrity.push(line);
+        }
+        else if (isUnverifiableFinding(finding)) {
+            unverifiable.push(line);
+        }
+        else {
+            blocking.push(line);
+        }
+    }
+    const input = {
+        integrity,
+        blocking,
+        exceptions: [],
+        waivers: [],
+        deps: [],
+        remediation: [],
+        unverifiable,
+        command: "codictator ci verify",
+    };
+    return buildCiSummary(input);
+}

package/dist/cli/ci.d.ts

@@ -0,0 +1,4 @@
+import type { Finding, Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function ciVerifyExit(findings: ReadonlyArray<Finding>): number;
+export declare function handleCi(req: CommandRequest): Promise<Result<number>>;