codictator 0.0.0 → 0.1.2

package/dist/features/ci/changes.js

@@ -0,0 +1,88 @@
+const RECOGNISED_BOTS = ["renovate[bot]", "dependabot[bot]"];
+const MANIFEST_BASENAMES = new Set([
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "Gemfile.lock",
+    "poetry.lock",
+    "requirements.txt",
+    "renovate.json",
+    "renovate.json5",
+    ".renovaterc",
+    ".renovaterc.json",
+    "dependabot.yml",
+    ".nvmrc",
+]);
+export function isRecognisedBot(author, trailerExempt) {
+    return RECOGNISED_BOTS.includes(author) || trailerExempt.includes(author);
+}
+function touchesOnlyManifests(files) {
+    if (files.length === 0) {
+        return false;
+    }
+    return files.every((file) => {
+        const base = file.replaceAll("\\", "/").split("/").pop() ?? file;
+        return MANIFEST_BASENAMES.has(base) || base.endsWith(".lock");
+    });
+}
+// SPEC §4.15.3: a PR qualifies when its commits only touch manifests and
+// lockfiles and its author is a recognised bot. Fork PRs are never written
+// to; their entries are required as usual (EC-8).
+export function qualifyBotChange(input) {
+    if (!isRecognisedBot(input.author, input.trailerExempt)) {
+        return { qualifies: false, writeCommit: false, findings: [] };
+    }
+    if (!touchesOnlyManifests(input.filesChanged)) {
+        return {
+            qualifies: false,
+            writeCommit: false,
+            findings: [
+                {
+                    ruleId: "core/history-entry",
+                    message: `bot PR by ${input.author} touches non-manifest files: the history entry is required`,
+                    remediation: "Record the change in docs/HISTORY like any other change (§4.15.3).",
+                },
+            ],
+        };
+    }
+    if (input.isFork) {
+        return {
+            qualifies: true,
+            writeCommit: false,
+            findings: [
+                {
+                    ruleId: "core/history-entry",
+                    message: "bot PR from a fork: no commit written; the history entry is required",
+                    remediation: "Carry the deps entry in the PR body or a follow-up commit (EC-8).",
+                },
+            ],
+        };
+    }
+    return { qualifies: true, writeCommit: true, findings: [] };
+}
+// SPEC §4.15.4: changes to committed state go to a single codictator/sweep
+// PR updated in place, never to the default branch (EC-9). A sweep that
+// finds a new floor finding on the default branch fails (EC-10).
+export function planSweep(input) {
+    return {
+        pr: "codictator/sweep",
+        action: input.sweepPrOpen ? "update-in-place" : "create",
+        findings: [...input.floorFindings],
+    };
+}
+// SPEC §4.15.6: host external skips workflow generation; without the human
+// confirmation record the gate stays unverified everywhere.
+export function externalCiStatus(options) {
+    if (options.host === "github" || options.confirmed) {
+        return [];
+    }
+    return [
+        {
+            ruleId: "core/ci-present",
+            message: "external CI host without a confirmation record: the gate is unverified",
+            remediation: "Wire `npx --no-install codictator ci verify --base <sha> --head <sha>` as a required check and confirm it (§4.15.6).",
+        },
+    ];
+}

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

@@ -0,0 +1,22 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+import { type BotChangeInput, externalCiStatus, planSweep, qualifyBotChange, type SweepInput } from "./changes.ts";
+import { type BaseRefInput, checkActionsPinned, evaluateProtection, type PinnedUse, type ProtectionRead, resolveBaseRef } from "./protection.ts";
+import { readProtection } from "./protection-read.ts";
+import { type CiWorkflow, FALLBACK_PINS, type RenderWorkflowOptions, scheduleCronFor, type WorkflowPins } from "./workflow.ts";
+export type { BaseRefInput, BotChangeInput, CiWorkflow, PinnedUse, ProtectionRead, RenderWorkflowOptions, SweepInput, WorkflowPins, };
+export { checkActionsPinned, evaluateProtection, externalCiStatus, FALLBACK_PINS, planSweep, qualifyBotChange, readProtection, resolveBaseRef, scheduleCronFor, };
+export interface CiEvidence {
+    readonly baseReachable?: boolean;
+    readonly forkPr?: boolean;
+    readonly protection?: ProtectionRead;
+    readonly unpinnedUses?: ReadonlyArray<PinnedUse>;
+    readonly workflowDrifted?: boolean;
+    readonly botChange?: BotChangeInput;
+    readonly sweep?: SweepInput;
+    readonly external?: {
+        readonly host: "github" | "external";
+        readonly confirmed: boolean;
+    };
+}
+export declare function renderWorkflow(repoRoot: string, options?: RenderWorkflowOptions): CiWorkflow;
+export declare function checkCi(_ctx: CheckContext, workflow: CiWorkflow, evidence?: CiEvidence): Array<Finding>;

package/dist/features/ci/index.js

@@ -0,0 +1,75 @@
+import { externalCiStatus, planSweep, qualifyBotChange, } from "./changes.js";
+import { checkActionsPinned, evaluateProtection, resolveBaseRef, } from "./protection.js";
+import { readProtection } from "./protection-read.js";
+import { FALLBACK_PINS, renderWorkflow as renderWorkflowImpl, scheduleCronFor, } from "./workflow.js";
+export { checkActionsPinned, evaluateProtection, externalCiStatus, FALLBACK_PINS, planSweep, qualifyBotChange, readProtection, resolveBaseRef, scheduleCronFor, };
+// SPEC §4.15.1: generated workflow rendering.
+export function renderWorkflow(repoRoot, options) {
+    return renderWorkflowImpl(repoRoot, options);
+}
+function unreachableBase() {
+    return {
+        ruleId: "core/ci-present",
+        code: "CDX-E503",
+        message: "CI base commit reachability is unconfirmed: blocking fail-closed",
+        remediation: "Fetch with fetch-depth 0 so the base is reachable, then rerun (EC-2).",
+    };
+}
+// SPEC §4.15.2 core/ci-actions-pinned: without caller evidence the check
+// reads the rendered workflow's own uses: entries (the trailing version
+// comment is not part of the ref). No rendered text to read fails closed.
+const WORKFLOW_USES_LINE = /^\s*-\s*uses:\s*(\S+)/;
+const GENERATED_WORKFLOW_FILE = ".github/workflows/codictator.yml";
+function defaultUses(workflow) {
+    if (workflow.text === undefined) {
+        return [{ file: GENERATED_WORKFLOW_FILE, uses: "actions/checkout" }];
+    }
+    const found = [];
+    for (const line of workflow.text.split("\n")) {
+        const ref = WORKFLOW_USES_LINE.exec(line)?.[1];
+        if (ref !== undefined) {
+            found.push({ file: GENERATED_WORKFLOW_FILE, uses: ref });
+        }
+    }
+    return found;
+}
+// SPEC §4.15.2: CI-side checks (required checks present, no bypass).
+// Defaults fail closed: unknown base → CDX-E503, unreadable protection →
+// advise, unpinned steps → core/ci-actions-pinned.
+export function checkCi(_ctx, workflow, evidence) {
+    const findings = [];
+    if (evidence?.baseReachable !== true) {
+        findings.push(unreachableBase());
+    }
+    findings.push(...evaluateProtection(evidence?.protection));
+    if (evidence?.unpinnedUses !== undefined) {
+        findings.push(...checkActionsPinned(evidence.unpinnedUses));
+    }
+    else if (workflow.host === "github") {
+        findings.push(...checkActionsPinned(defaultUses(workflow)));
+    }
+    if (evidence?.workflowDrifted === true) {
+        findings.push({
+            ruleId: "core/guardrail-manifest",
+            message: "CI workflow differs from its manifest entry (for example continue-on-error added)",
+            remediation: "Restore the workflow with `codictator regen` (EC-4).",
+        });
+    }
+    if (evidence?.botChange !== undefined) {
+        findings.push(...qualifyBotChange(evidence.botChange).findings);
+    }
+    else if (evidence?.forkPr === true) {
+        findings.push({
+            ruleId: "core/ci-required-check",
+            message: "PR from a fork with a read-only token: verify runs, protection reads only advise",
+            remediation: "Confirm the required check on the merge commit by hand (EC-1).",
+        });
+    }
+    if (evidence?.sweep !== undefined) {
+        findings.push(...planSweep(evidence.sweep).findings);
+    }
+    if (evidence?.external !== undefined) {
+        findings.push(...externalCiStatus(evidence.external));
+    }
+    return findings;
+}

package/dist/features/ci/protection-read.d.ts

@@ -0,0 +1,3 @@
+import { type Env, type Net } from "../../kernel/index.ts";
+import type { ProtectionRead } from "./protection.ts";
+export declare function readProtection(net: Net, env: Env): Promise<ProtectionRead | undefined>;

package/dist/features/ci/protection-read.js

@@ -0,0 +1,264 @@
+// SPEC §4.15.2 + §4.15.7 EC-1/EC-6: the live branch-protection read behind
+// `ci verify`. Pure over Net/Env: branch rules go first, classic second;
+// unreadable resolves to undefined (advise), readable classic 404 to
+// blocking (EC-7, reported-not-protected).
+import { parseJson } from "../../kernel/index.js";
+const DEFAULT_API_URL = "https://api.github.com";
+const REQUEST_TIMEOUT_MS = 10_000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Dynamic-key read: literal dot access would widen the unknown, and literal
+// bracket access trips useLiteralKeys, so every JSON field goes through here.
+function field(record, key) {
+    return record[key];
+}
+function stringItems(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string") {
+            return undefined;
+        }
+        out.push(item);
+    }
+    return out;
+}
+// Classic protection bodies list required contexts two ways: the legacy
+// `contexts` strings and the newer `checks` objects carrying `context`.
+// Null or absent means no required checks (fail closed downstream), while a
+// malformed shape means the read cannot be trusted (advise downstream).
+function requiredContexts(checks) {
+    if (checks === null || checks === undefined) {
+        return [];
+    }
+    if (!isRecord(checks)) {
+        return undefined;
+    }
+    const legacy = stringItems(field(checks, "contexts"));
+    if (legacy !== undefined) {
+        return legacy;
+    }
+    const modern = field(checks, "checks");
+    if (!Array.isArray(modern)) {
+        return undefined;
+    }
+    const out = [];
+    for (const entry of modern) {
+        if (!isRecord(entry)) {
+            return undefined;
+        }
+        const context = field(entry, "context");
+        if (typeof context !== "string") {
+            return undefined;
+        }
+        out.push(context);
+    }
+    return out;
+}
+function enabledFlag(body, key) {
+    if (!isRecord(body)) {
+        return undefined;
+    }
+    const section = field(body, key);
+    if (!isRecord(section)) {
+        return undefined;
+    }
+    const enabled = field(section, "enabled");
+    return typeof enabled === "boolean" ? enabled : undefined;
+}
+function defaultBranchOf(body) {
+    if (!isRecord(body)) {
+        return undefined;
+    }
+    const branch = field(body, "default_branch");
+    return typeof branch === "string" && branch !== "" ? branch : undefined;
+}
+// SPEC §4.15.2: a required check is verify-shaped when its context is the
+// gate's name. Matrix jobs append a parenthesised suffix (`verify
+// (ubuntu-latest)`), stripped before the exact match, so `pre-verify` fails.
+function verifyBaseOf(context) {
+    return context
+        .replace(/\s*\([^)]*\)\s*$/, "")
+        .trim()
+        .toLowerCase();
+}
+function verifyRequiredIn(contexts) {
+    return contexts.some((context) => verifyBaseOf(context) === "verify");
+}
+// SPEC §4.15.2: the branch-rules endpoint answers an array of repository
+// rules; anything else falls through to classic, never assumes.
+function protectionFromRuleset(rulesBody, repoBody) {
+    const parsed = parseJson(rulesBody);
+    if (!parsed.ok || !Array.isArray(parsed.value)) {
+        return undefined;
+    }
+    const contexts = [];
+    let forcePushBlocked = false;
+    let deletionBlocked = false;
+    for (const entry of parsed.value) {
+        if (!isRecord(entry) || typeof field(entry, "type") !== "string") {
+            return undefined;
+        }
+        const type = field(entry, "type");
+        forcePushBlocked = forcePushBlocked || type === "non_fast_forward";
+        deletionBlocked = deletionBlocked || type === "deletion";
+        if (type !== "required_status_checks") {
+            continue;
+        }
+        const params = field(entry, "parameters");
+        if (!isRecord(params)) {
+            return undefined;
+        }
+        const checks = field(params, "required_status_checks");
+        if (!Array.isArray(checks)) {
+            return undefined;
+        }
+        for (const check of checks) {
+            if (!isRecord(check)) {
+                return undefined;
+            }
+            const context = field(check, "context");
+            if (typeof context !== "string") {
+                return undefined;
+            }
+            contexts.push(context);
+        }
+    }
+    const squash = isRecord(repoBody)
+        ? field(repoBody, "allow_squash_merge")
+        : undefined;
+    return {
+        readable: true,
+        verifyRequired: verifyRequiredIn(contexts),
+        forcePushBlocked,
+        deletionBlocked,
+        ...(typeof squash === "boolean" ? { allowSquashMerge: squash } : {}),
+    };
+}
+function protectionFrom(body) {
+    const parsed = parseJson(body);
+    if (!parsed.ok || !isRecord(parsed.value)) {
+        return undefined;
+    }
+    const contexts = requiredContexts(field(parsed.value, "required_status_checks"));
+    if (contexts === undefined) {
+        return undefined;
+    }
+    const squash = field(parsed.value, "allow_squash_merge");
+    const forcePushes = enabledFlag(parsed.value, "allow_force_pushes");
+    const deletions = enabledFlag(parsed.value, "allow_deletions");
+    return {
+        readable: true,
+        verifyRequired: verifyRequiredIn(contexts),
+        ...(forcePushes === undefined ? {} : { forcePushBlocked: !forcePushes }),
+        ...(deletions === undefined ? {} : { deletionBlocked: !deletions }),
+        ...(typeof squash === "boolean" ? { allowSquashMerge: squash } : {}),
+    };
+}
+// SPEC §4.15.2 EC-7: reported-not-protected is readable, so every missing
+// setting blocks instead of advising.
+function unprotectedRead() {
+    return {
+        readable: true,
+        verifyRequired: false,
+        forcePushBlocked: false,
+        deletionBlocked: false,
+        allowSquashMerge: true,
+    };
+}
+function repoRefOf(value) {
+    if (value === undefined || value === "") {
+        return undefined;
+    }
+    const parts = value.split("/");
+    if (parts.length !== 2) {
+        return undefined;
+    }
+    const owner = parts[0];
+    const repo = parts[1];
+    if (owner === undefined ||
+        owner === "" ||
+        repo === undefined ||
+        repo === "") {
+        return undefined;
+    }
+    return { owner, repo };
+}
+function repoUrl(api, ref) {
+    return `${api}/repos/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.repo)}`;
+}
+// SPEC §4.15.7 EC-1/EC-6: outside Actions, without a token, or on any
+// unreadable answer (403, timeout, network error) the read is absent and the
+// gate advises; it never throws, so a host outage cannot fail the run.
+export async function readProtection(net, env) {
+    if (env.get("GITHUB_ACTIONS") !== "true") {
+        return undefined;
+    }
+    const token = env.get("GITHUB_TOKEN");
+    const ref = repoRefOf(env.get("GITHUB_REPOSITORY"));
+    if (token === undefined || token === "" || ref === undefined) {
+        return undefined;
+    }
+    const api = (env.get("GITHUB_API_URL") ?? DEFAULT_API_URL).replace(/\/+$/, "");
+    if (api === "") {
+        return undefined;
+    }
+    const headers = {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        // GitHub rejects API calls without a UA (403 "Request forbidden by
+        // administrative rules"); without this the read always advises.
+        "User-Agent": "codictator",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+    const repoSeen = await net.request({
+        method: "GET",
+        url: repoUrl(api, ref),
+        headers,
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    if (!repoSeen.ok || repoSeen.value.status !== 200) {
+        return undefined;
+    }
+    const repoParsed = parseJson(repoSeen.value.body);
+    if (!repoParsed.ok) {
+        return undefined;
+    }
+    const branch = defaultBranchOf(repoParsed.value);
+    if (branch === undefined) {
+        return undefined;
+    }
+    // SPEC §4.15.2: rulesets first; unreadable or untrustworthy answers
+    // fall through to classic, only a readable ruleset resolves here.
+    const rulesSeen = await net.request({
+        method: "GET",
+        url: `${repoUrl(api, ref)}/rules/branches/${encodeURIComponent(branch)}`,
+        headers,
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    if (rulesSeen.ok && rulesSeen.value.status === 200) {
+        const ruleset = protectionFromRuleset(rulesSeen.value.body, repoParsed.value);
+        if (ruleset !== undefined) {
+            return ruleset;
+        }
+    }
+    const seen = await net.request({
+        method: "GET",
+        url: `${repoUrl(api, ref)}/branches/${encodeURIComponent(branch)}/protection`,
+        headers,
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    if (!seen.ok) {
+        return undefined;
+    }
+    if (seen.value.status === 404) {
+        return unprotectedRead();
+    }
+    if (seen.value.status !== 200) {
+        return undefined;
+    }
+    return protectionFrom(seen.value.body);
+}

package/dist/features/ci/protection.d.ts

@@ -0,0 +1,25 @@
+import { type Result } from "../../kernel/index.ts";
+import type { Finding } from "../engine/index.ts";
+export interface ProtectionRead {
+    readonly readable: boolean;
+    readonly verifyRequired?: boolean;
+    readonly forcePushBlocked?: boolean;
+    readonly deletionBlocked?: boolean;
+    readonly allowSquashMerge?: boolean;
+    readonly rulesetMergeMethods?: ReadonlyArray<string>;
+}
+export interface BaseRefInput {
+    readonly eventName: "pull_request" | "push" | "schedule" | "dispatch";
+    readonly before?: string;
+    readonly pullBaseSha?: string;
+    readonly defaultBranch?: string;
+    readonly reachable?: boolean;
+}
+export interface PinnedUse {
+    readonly file: string;
+    readonly uses: string;
+    readonly image?: string;
+}
+export declare function evaluateProtection(read?: ProtectionRead): Array<Finding>;
+export declare function resolveBaseRef(input: BaseRefInput): Result<string>;
+export declare function checkActionsPinned(uses: ReadonlyArray<PinnedUse>): Array<Finding>;

package/dist/features/ci/protection.js

@@ -0,0 +1,77 @@
+// SPEC §4.15.2–§4.15.3 + §4.15.6–§4.15.7: merge-gate reads and the CI base.
+// Reads are pure over caller-supplied host data (rulesets, repo settings,
+// workflow texts); the CLI fetches them through the kernel Net/Git ports, so
+// this module never touches the network (§10.3) and fork PRs with read-only
+// tokens degrade to advise, never to allow (EC-1, EC-6).
+import { err, makeError, ok } from "../../kernel/index.js";
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+function advise(ruleId, message, remediation) {
+    return { ruleId, message, remediation };
+}
+function block(ruleId, message, remediation) {
+    return { ruleId, message, remediation };
+}
+// SPEC §4.15.2: reported not required → block; unreadable → advise (PRD
+// §11.1). The same read feeds core/branch-protection below.
+export function evaluateProtection(read) {
+    if (read === undefined || !read.readable) {
+        return [
+            advise("core/ci-required-check", "cannot confirm the verify check is required: branch protection is unreadable", "Grant the workflow read access to rulesets/branch protection, or confirm the required check by hand (EC-1, EC-6)."),
+            advise("core/branch-protection", "cannot confirm force-push, deletion and squash settings: branch protection is unreadable", "Grant the workflow read access to the repo settings and rulesets, or confirm them by hand (§4.15.2)."),
+        ];
+    }
+    const findings = [];
+    if (read.verifyRequired !== true) {
+        findings.push(block("core/ci-required-check", "the verify check is not a required check on the default branch", "Add verify to the required checks of the branch ruleset (§4.15 EC-7)."));
+    }
+    const squashExcluded = read.allowSquashMerge === false ||
+        (read.rulesetMergeMethods !== undefined &&
+            !read.rulesetMergeMethods.includes("squash"));
+    if (!squashExcluded) {
+        findings.push(block("core/branch-protection", "squash merging is allowed and no ruleset excludes it", "Set allow_squash_merge to false and exclude squash from the ruleset allowed_merge_methods (§4.9.3, EC-11, S33)."));
+    }
+    if (read.forcePushBlocked !== true || read.deletionBlocked !== true) {
+        findings.push(block("core/branch-protection", "force-push or deletion is not blocked on the default branch", "Block force-pushes and deletions on the default branch in settings and rulesets (§4.15.2)."));
+    }
+    return findings;
+}
+// SPEC §4.15.1 + EC-2/EC-3: PRs read the base from the event; pushes use
+// before, or the merge-base with the default branch when before is absent
+// (new branch); an unreachable base is CDX-E503 and blocks.
+export function resolveBaseRef(input) {
+    if (input.reachable === false) {
+        return err(makeError("CDX-E503", "CI base commit is unreachable (shallow clone despite config)", "Fetch with fetch-depth 0 and rerun; ci.verify needs the full base..head range (EC-2)."));
+    }
+    if (input.eventName === "pull_request" && input.pullBaseSha !== undefined) {
+        return ok(input.pullBaseSha);
+    }
+    const zero = "0000000000000000000000000000000000000000";
+    if (input.before !== undefined &&
+        input.before !== "" &&
+        input.before !== zero) {
+        return ok(input.before);
+    }
+    if (input.eventName === "push") {
+        return ok(`merge-base(${input.defaultBranch ?? "main"},HEAD)`);
+    }
+    return ok(input.pullBaseSha ?? `merge-base(${input.defaultBranch ?? "main"},HEAD)`);
+}
+function usesRef(uses) {
+    const at = uses.indexOf("@");
+    return at >= 0 ? uses.slice(at + 1) : undefined;
+}
+// SPEC §4.15.2: every uses: in every workflow is a 40-hex SHA; every
+// container/services image is digest-pinned (EC-5).
+export function checkActionsPinned(uses) {
+    const findings = [];
+    for (const entry of uses) {
+        const ref = entry.uses.includes("@") ? usesRef(entry.uses) : undefined;
+        if (ref === undefined || !SHA_PATTERN.test(ref)) {
+            findings.push(block("core/ci-actions-pinned", `${entry.file} uses ${entry.uses} without a full commit SHA`, "Pin every uses: by full 40-hex commit SHA with the version as a trailing comment (EC-5)."));
+        }
+        if (entry.image !== undefined && !entry.image.includes("@sha256:")) {
+            findings.push(block("core/ci-actions-pinned", `${entry.file} runs container ${entry.image} without a digest pin`, "Pin every container/services image by digest (EC-5)."));
+        }
+    }
+    return findings;
+}

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

@@ -0,0 +1,23 @@
+export interface CiWorkflow {
+    readonly host: "github" | "external";
+    readonly os: ReadonlyArray<string>;
+    readonly steps: ReadonlyArray<string>;
+    readonly text?: string;
+    readonly scheduleCron?: string;
+}
+export interface WorkflowPins {
+    readonly checkoutSha: string;
+    readonly checkoutVersion: string;
+    readonly setupNodeSha: string;
+    readonly setupNodeVersion: string;
+}
+export declare const FALLBACK_PINS: WorkflowPins;
+export interface RenderWorkflowOptions {
+    readonly os?: ReadonlyArray<string>;
+    readonly repoName?: string;
+    readonly defaultBranch?: string;
+    readonly pins?: WorkflowPins;
+    readonly bot?: "auto" | "renovate" | "dependabot" | "none";
+}
+export declare function scheduleCronFor(repoName: string): string;
+export declare function renderWorkflow(repoRoot: string, options?: RenderWorkflowOptions): CiWorkflow;