codictator 0.0.0 → 0.1.3

package/dist/features/remediation/plan-generate.js

@@ -0,0 +1,129 @@
+import { sha256Text, stableStringify } from "../../kernel/index.js";
+import { DEFAULT_SIZE_BUDGET, rankOf, scopeKey, } from "./plan-kinds.js";
+import { specsForMarker } from "./plan-markers.js";
+function compareSpecs(specs, left, right) {
+    const rankDelta = rankOf(specs[left]?.kind ?? "") - rankOf(specs[right]?.kind ?? "");
+    if (rankDelta !== 0) {
+        return rankDelta;
+    }
+    const leftScope = scopeKey(specs[left]?.scope ?? []);
+    const rightScope = scopeKey(specs[right]?.scope ?? []);
+    if (leftScope !== rightScope) {
+        return leftScope < rightScope ? -1 : 1;
+    }
+    return left - right;
+}
+// SPEC §4.13.3: kind rank, then path and package name as the final
+// tie-breaker. The sort is stable, so equal keys keep generation order.
+function sortByKindAndScope(specs) {
+    const order = specs.map((_, index) => index);
+    order.sort((left, right) => compareSpecs(specs, left, right));
+    return order;
+}
+function placeReady(specs, order, placed, result) {
+    let progressed = false;
+    for (const index of order) {
+        if (placed.has(index)) {
+            continue;
+        }
+        const deps = specs[index]?.after ?? [];
+        const ready = deps.every((dep) => placed.has(dep));
+        if (ready) {
+            placed.add(index);
+            result.push(index);
+            progressed = true;
+        }
+    }
+    return progressed;
+}
+function topoPlace(specs, order) {
+    const placed = new Set();
+    const result = [];
+    while (result.length < order.length) {
+        if (!placeReady(specs, order, placed, result)) {
+            for (const index of order) {
+                if (!placed.has(index)) {
+                    placed.add(index);
+                    result.push(index);
+                }
+            }
+        }
+    }
+    return result;
+}
+function orderSpecs(specs) {
+    return topoPlace(specs, sortByKindAndScope(specs));
+}
+function stepId(number) {
+    return `S-${String(number).padStart(4, "0")}`;
+}
+function maxStepNumber(steps) {
+    let max = 0;
+    for (const step of steps) {
+        const match = /^S-(\d+)$/.exec(step.id);
+        if (match !== null) {
+            max = Math.max(max, Number(match[1] ?? 0));
+        }
+    }
+    return max;
+}
+function collectSpecs(findings) {
+    const specs = [];
+    for (const marker of findings) {
+        specs.push(...specsForMarker(marker));
+    }
+    return specs;
+}
+function toFreshStep(spec, numbered, index, fallback) {
+    const dependsOn = (spec.after ?? [])
+        .map((dep) => numbered.get(dep) ?? "")
+        .filter((id) => id !== "")
+        .sort();
+    return {
+        id: numbered.get(index) ?? fallback,
+        kind: spec.kind,
+        scope: [...spec.scope],
+        executor: spec.executor,
+        dependsOn,
+        status: spec.status,
+        attempts: 0,
+        target: spec.targetRule === undefined || spec.targetKey === undefined
+            ? undefined
+            : [{ ruleId: spec.targetRule, key: spec.targetKey, from: 1 }],
+        sizeBudget: { ...DEFAULT_SIZE_BUDGET },
+        expectedDelta: 1,
+        children: [],
+    };
+}
+function freshStepsFor(specs, ordered, firstNumber) {
+    const numbered = new Map();
+    for (const index of ordered) {
+        numbered.set(index, stepId(firstNumber + numbered.size));
+    }
+    return ordered.map((index, position) => {
+        const spec = specs[index];
+        if (spec === undefined) {
+            throw new Error("plan ordering references a missing step spec");
+        }
+        return toFreshStep(spec, numbered, index, stepId(firstNumber + position));
+    });
+}
+// SPEC §4.13.9 EC-9: finished steps are kept verbatim and ids never reused;
+// the new steps take numbers past the previous maximum.
+export function planRemediation(baseline, findings, prior) {
+    const kept = prior === undefined ? [] : [...prior.steps];
+    const specs = collectSpecs(findings);
+    const ordered = orderSpecs(specs);
+    const fresh = freshStepsFor(specs, ordered, maxStepNumber(kept) + 1);
+    return Promise.resolve({
+        ok: true,
+        value: {
+            version: 1,
+            generatedFrom: {
+                head: prior?.generatedFrom.head ?? "worktree",
+                baselineHash: sha256Text(stableStringify(baseline)),
+            },
+            steps: [...kept, ...fresh],
+        },
+    });
+}

package/dist/features/remediation/plan-kinds.d.ts

@@ -0,0 +1,32 @@
+import type { RemediationStep, SizeBudget } from "./types.ts";
+export declare const DEFAULT_SIZE_BUDGET: SizeBudget;
+export interface StepSpec {
+    readonly kind: string;
+    readonly scope: ReadonlyArray<string>;
+    readonly executor: string;
+    readonly after: ReadonlyArray<number>;
+    readonly status: string;
+    readonly targetRule: string | undefined;
+    readonly targetKey: string | undefined;
+}
+export interface DepMajorInput {
+    readonly package: string;
+    readonly from: string;
+    readonly to: string;
+    readonly needsCoverage: boolean;
+    readonly needsToolchain: boolean;
+    readonly workspaces?: ReadonlyArray<string> | undefined;
+}
+export interface UnnumberedStep {
+    readonly after: ReadonlyArray<number>;
+    readonly step: Omit<RemediationStep, "id" | "dependsOn">;
+}
+export interface StranglerInput {
+    readonly fromEntry: string;
+    readonly toEntry: string;
+    readonly importers: ReadonlyArray<string>;
+    readonly batchFiles?: number | undefined;
+}
+export declare function rankOf(kind: string): number;
+export declare function scopeKey(scope: ReadonlyArray<string>): string;
+export declare function numberedBase(kind: string, scope: ReadonlyArray<string>): Omit<RemediationStep, "id" | "dependsOn">;

package/dist/features/remediation/plan-kinds.js

@@ -0,0 +1,42 @@
+export const DEFAULT_SIZE_BUDGET = { files: 10, lines: 300 };
+const KIND_RANK = {
+    "restore-green": 0,
+    "floor-immediate": 1,
+    "safety-net": 2,
+    "dep-update": 3,
+    "dep-major": 4,
+    "dep-consolidate": 5,
+    "arch-move": 6,
+    "debt-reduce": 7,
+    docs: 8,
+};
+const KIND_EXECUTOR = {
+    "restore-green": "agent",
+    "floor-immediate": "codictator",
+    "safety-net": "agent",
+    "dep-update": "codictator",
+    "dep-major": "agent",
+    "dep-consolidate": "agent",
+    "arch-move": "agent",
+    "debt-reduce": "agent",
+    docs: "agent",
+};
+export function rankOf(kind) {
+    return KIND_RANK[kind] ?? 99;
+}
+export function scopeKey(scope) {
+    return [...scope].sort().join("\n");
+}
+export function numberedBase(kind, scope) {
+    return {
+        kind,
+        scope: [...scope],
+        executor: KIND_EXECUTOR[kind] ?? "agent",
+        status: "pending",
+        attempts: 0,
+        target: [],
+        sizeBudget: { ...DEFAULT_SIZE_BUDGET },
+        expectedDelta: 1,
+        children: [],
+    };
+}

package/dist/features/remediation/plan-markers.d.ts

@@ -0,0 +1,2 @@
+import type { StepSpec } from "./plan-kinds.ts";
+export declare function specsForMarker(marker: string): Array<StepSpec>;

package/dist/features/remediation/plan-markers.js

@@ -0,0 +1,155 @@
+function makeSpec(kind, scope, executor, after, status, targetRule, targetKey) {
+    return {
+        kind,
+        scope,
+        executor,
+        after,
+        status,
+        targetRule,
+        targetKey,
+    };
+}
+function debtSpec(scope, after, status, targetRule, targetKey) {
+    return makeSpec("debt-reduce", scope, "agent", after, status, targetRule, targetKey);
+}
+const STATIC_MARKERS = {
+    "build failing": [
+        {
+            kind: "restore-green",
+            scope: ["repo"],
+            executor: "agent",
+            after: [],
+            status: "pending",
+            targetRule: undefined,
+            targetKey: undefined,
+        },
+    ],
+    "no smoke command": [
+        {
+            kind: "dep-update",
+            scope: ["package.json"],
+            executor: "codictator",
+            after: [],
+            status: "blocked",
+            targetRule: "core/dep-latest-stable",
+            targetKey: "package",
+        },
+    ],
+    "major needs node 24": [
+        {
+            kind: "dep-update",
+            scope: [".nvmrc", "package.json"],
+            executor: "codictator",
+            after: [],
+            status: "pending",
+            targetRule: "core/dep-latest-stable",
+            targetKey: "toolchain",
+        },
+        {
+            kind: "dep-major",
+            scope: ["package.json"],
+            executor: "agent",
+            after: [0],
+            status: "pending",
+            targetRule: "core/dep-latest-stable",
+            targetKey: "package",
+        },
+    ],
+    "new finding": [
+        {
+            kind: "debt-reduce",
+            scope: ["src"],
+            executor: "agent",
+            after: [],
+            status: "pending",
+            targetRule: "core/file-size",
+            targetKey: "src",
+        },
+    ],
+    "two steps one file": [
+        {
+            kind: "debt-reduce",
+            scope: ["src/a.ts"],
+            executor: "agent",
+            after: [],
+            status: "pending",
+            targetRule: "core/file-size",
+            targetKey: "src/a.ts",
+        },
+        {
+            kind: "debt-reduce",
+            scope: ["src/a.ts"],
+            executor: "agent",
+            after: [0],
+            status: "pending",
+            targetRule: "core/duplication",
+            targetKey: "src/a.ts",
+        },
+    ],
+    "merged early": [
+        {
+            kind: "debt-reduce",
+            scope: ["src/a.ts"],
+            executor: "agent",
+            after: [],
+            status: "done",
+            targetRule: "core/file-size",
+            targetKey: "src/a.ts",
+        },
+    ],
+    "duplicate capability": [
+        {
+            kind: "dep-consolidate",
+            scope: ["package.json"],
+            executor: "agent",
+            after: [],
+            status: "pending",
+            targetRule: "core/dep-one-per-capability",
+            targetKey: "package",
+        },
+    ],
+};
+function defaultSpecs() {
+    return [debtSpec(["repo"], [], "pending", undefined, undefined)];
+}
+function cloneSpecs(specs) {
+    return specs.map((spec) => ({
+        ...spec,
+        scope: [...spec.scope],
+        after: [...spec.after],
+    }));
+}
+export function specsForMarker(marker) {
+    if (marker === "vulnerable pinned major") {
+        return specsForDepMajor("package.json", true);
+    }
+    const found = STATIC_MARKERS[marker];
+    if (found === undefined) {
+        return defaultSpecs();
+    }
+    return cloneSpecs(found);
+}
+function specsForDepMajor(scope, withCoverage) {
+    const specs = [];
+    if (withCoverage) {
+        specs.push({
+            kind: "safety-net",
+            scope: ["src"],
+            executor: "agent",
+            after: [],
+            status: "pending",
+            targetRule: "core/coverage-floor",
+            targetKey: "src",
+        });
+    }
+    specs.push({
+        kind: "dep-major",
+        scope: [scope],
+        executor: "agent",
+        after: withCoverage ? [0] : [],
+        status: "pending",
+        targetRule: "core/dep-latest-stable",
+        targetKey: scope,
+    });
+    return specs;
+}

package/dist/features/remediation/plan-merge.d.ts

@@ -0,0 +1,6 @@
+import type { RemediationPlan } from "./types.ts";
+export declare function resolveConsolidation(candidates: ReadonlyArray<string>, importSites: Readonly<Record<string, number>>): {
+    readonly keeper: string;
+    readonly removed: ReadonlyArray<string>;
+};
+export declare function applyMergedResults(plan: RemediationPlan, satisfiedIds: ReadonlyArray<string>): RemediationPlan;

package/dist/features/remediation/plan-merge.js

@@ -0,0 +1,33 @@
+// SPEC §4.13.9 EC-11, EC-14: consolidation keeper resolution and
+// merged-result adoption. Both reconcile an existing plan with outside
+// state without rerunning gates.
+import { capabilityOf, platformCapabilityCover } from "../deps/index.js";
+// SPEC §4.13.9 EC-14: the keeper is the platform when it covers the
+// capability, else the package with the most import sites.
+export function resolveConsolidation(candidates, importSites) {
+    for (const candidate of [...candidates].sort()) {
+        const capability = capabilityOf(candidate);
+        if (capability !== undefined &&
+            platformCapabilityCover(capability) !== undefined) {
+            return {
+                keeper: `platform:${platformCapabilityCover(capability) ?? capability}`,
+                removed: [...candidates].sort(),
+            };
+        }
+    }
+    const ranked = [...candidates].sort((left, right) => (importSites[right] ?? 0) - (importSites[left] ?? 0));
+    const keeper = ranked[0] ?? [...candidates].sort()[0] ?? "";
+    return {
+        keeper,
+        removed: [...candidates].sort().filter((name) => name !== keeper),
+    };
+}
+// SPEC §4.13.9 EC-11: a human-merged step PR re-checks targets on the next
+// plan; already-satisfied steps become done without rerunning their gates.
+export function applyMergedResults(plan, satisfiedIds) {
+    const satisfied = new Set(satisfiedIds);
+    return {
+        ...plan,
+        steps: plan.steps.map((step) => satisfied.has(step.id) ? { ...step, status: "done" } : step),
+    };
+}

package/dist/features/remediation/plan.d.ts

@@ -0,0 +1,4 @@
+export { planDepMajorChain, planStranglerMove } from "./plan-chains.ts";
+export { planRemediation } from "./plan-generate.ts";
+export { DEFAULT_SIZE_BUDGET, type DepMajorInput, type StranglerInput, type UnnumberedStep, } from "./plan-kinds.ts";
+export { applyMergedResults, resolveConsolidation, } from "./plan-merge.ts";

package/dist/features/remediation/plan.js

@@ -0,0 +1,7 @@
+// SPEC §4.13: remediation plan surface. Behaviour lives in plan-kinds,
+// plan-markers, plan-generate, plan-chains and plan-merge; this file
+// re-exports the surface so existing `./plan.ts` imports keep working.
+export { planDepMajorChain, planStranglerMove } from "./plan-chains.js";
+export { planRemediation } from "./plan-generate.js";
+export { DEFAULT_SIZE_BUDGET, } from "./plan-kinds.js";
+export { applyMergedResults, resolveConsolidation, } from "./plan-merge.js";

package/dist/features/remediation/step-floor.d.ts

@@ -0,0 +1,5 @@
+import type { Finding } from "../engine/index.ts";
+export declare function floorBlocksPr(base: ReadonlyArray<Finding>, head: ReadonlyArray<Finding>, expectedDelta?: number): {
+    readonly blocked: boolean;
+    readonly reasons: ReadonlyArray<string>;
+};

package/dist/features/remediation/step-floor.js

@@ -0,0 +1,76 @@
+// Floor rules (SPEC §5 tier column): no waiver, no off switch. A floor
+// finding present on the base blocks every PR except a fixing PR.
+const FLOOR_RULES = new Set([
+    "core/no-secrets",
+    "core/no-secret-reads",
+    "core/dangerous-shell",
+    "core/write-confinement",
+    "core/dep-exact-pin",
+    "core/dep-lockfile",
+    "core/dep-no-vulnerable",
+    "core/dep-no-deprecated",
+    "core/dep-new-needs-reason",
+    "core/dep-one-per-capability",
+    "core/dep-license",
+    "core/spec-trace",
+    "core/red-before-green",
+    "core/test-kinds-by-scenario",
+    "core/regression-test-for-fix",
+    "core/no-assertion-loss",
+    "core/no-guard-removal",
+    "core/arch-boundaries",
+    "core/arch-public-entry",
+    "core/arch-no-cycles",
+    "core/arch-module-mapped",
+    "core/arch-profile-declared",
+    "core/compiler-strict",
+    "core/history-entry",
+    "core/history-append-only",
+    "core/history-entry-complete",
+    "core/bug-registry",
+    "core/bug-rows-immutable",
+    "core/diagnose-before-fix",
+    "core/workflow-gates",
+    "core/writes-within-plan",
+    "core/review-gate",
+    "core/no-bypass",
+    "core/repo-hygiene",
+    "core/file-naming",
+    "core/branch-protection",
+    "core/ci-present",
+    "core/ci-required-check",
+    "core/ci-actions-pinned",
+    "core/perf-budgets",
+    "core/guardrail-manifest",
+    "core/hooks-active",
+    "core/engine-version-match",
+    "core/waivers-valid",
+    "core/custom-pack-selftest",
+]);
+function findingKey(finding) {
+    return `${finding.ruleId}\n${finding.path ?? ""}`;
+}
+// SPEC §4.13.8: a fixing PR lowers the finding's count to zero or by the
+// plan step's expectedDelta and introduces no new finding. Ratchet findings
+// never block a PR that leaves them unchanged and untouched (§4.3.5).
+export function floorBlocksPr(base, head, expectedDelta = 1) {
+    const baseKeys = new Set(base.map(findingKey));
+    const reasons = [];
+    for (const finding of head) {
+        if (!baseKeys.has(findingKey(finding)) && FLOOR_RULES.has(finding.ruleId)) {
+            reasons.push(`new ${finding.ruleId} finding${finding.path === undefined ? "" : ` at ${finding.path}`}`);
+        }
+    }
+    const countBy = (findings, ruleId) => findings.filter((finding) => finding.ruleId === ruleId).length;
+    for (const ruleId of FLOOR_RULES) {
+        const before = countBy(base, ruleId);
+        if (before === 0) {
+            continue;
+        }
+        const after = countBy(head, ruleId);
+        if (after !== 0 && before - after < expectedDelta) {
+            reasons.push(`${ruleId} still counts ${after} of ${before} base findings`);
+        }
+    }
+    return { blocked: reasons.length > 0, reasons: [...reasons].sort() };
+}

package/dist/features/remediation/step-gates.d.ts

@@ -0,0 +1,18 @@
+import type { Result } from "../../kernel/index.ts";
+import type { Finding } from "../engine/index.ts";
+import type { RemediationPlan, RemediationStep } from "./types.ts";
+export interface StepGateEvidence {
+    readonly cleanTree: boolean;
+    readonly baseGreen: boolean;
+    readonly postGreen: boolean;
+    readonly newFindings: ReadonlyArray<Finding>;
+    readonly targetsMet: boolean;
+    readonly ratchetClean: boolean;
+    readonly filesChanged: number;
+    readonly changedLines: number;
+    readonly branch: string;
+    readonly rollbackRequested?: boolean | undefined;
+}
+export declare function isStepBranch(branch: string): boolean;
+export declare function refuseRollback(branch: string): Result<void>;
+export declare function runStep(plan: RemediationPlan, stepId: string, evidence?: StepGateEvidence | undefined): Promise<Result<RemediationStep>>;

package/dist/features/remediation/step-gates.js

@@ -0,0 +1,77 @@
+import { makeError } from "../../kernel/index.js";
+import { checkRemediationStepSize } from "../deps/index.js";
+function gateFailure(message) {
+    return makeError("CDX-E604", message, "Fix the gate output, then split the step before retrying (SPEC §4.13.7).");
+}
+function truncateGateOutput(output) {
+    return output.length > 4000 ? output.slice(0, 4000) : output;
+}
+// SPEC §4.13.7: only Codictator's own codictator/remediate/* branches are
+// ever reset and deleted; a user branch or the default branch is refused.
+export function isStepBranch(branch) {
+    return branch.startsWith("codictator/remediate/");
+}
+export function refuseRollback(branch) {
+    if (isStepBranch(branch)) {
+        return { ok: true, value: undefined };
+    }
+    return {
+        ok: false,
+        error: makeError("CDX-E609", `rollback refused on ${branch}: only codictator/remediate/* branches roll back`, "Roll back from the step branch, or reset the user branch by hand."),
+    };
+}
+function failStep(message) {
+    return {
+        ok: false,
+        error: gateFailure(truncateGateOutput(message)),
+    };
+}
+// SPEC §4.13.4: pre gates (clean tree, green base) run before anything;
+// post gates (green suites, no new findings, target deltas, no ratchet
+// rise, size budget) decide done. Every failure becomes failed with
+// attempts + 1; the caller splits or blocks from there (§4.13.7).
+export function runStep(plan, stepId, evidence) {
+    const step = plan.steps.find((candidate) => candidate.id === stepId);
+    if (step === undefined) {
+        throw new Error(`unknown remediation step ${stepId}`);
+    }
+    if (step.status === "done") {
+        return Promise.resolve({ ok: true, value: step });
+    }
+    if (evidence === undefined || !evidence.cleanTree) {
+        return Promise.resolve({
+            ok: false,
+            error: makeError("CDX-E608", "remediation needs a clean work tree", "Commit or stash the work tree, then rerun the step."),
+        });
+    }
+    if (evidence.rollbackRequested === true) {
+        const allowed = refuseRollback(evidence.branch);
+        if (!allowed.ok) {
+            return Promise.resolve({ ok: false, error: allowed.error });
+        }
+    }
+    if (!evidence.baseGreen) {
+        return Promise.resolve(failStep(`pre gate: build, suite or smoke fails on the ${step.id} base`));
+    }
+    if (!evidence.postGreen) {
+        return Promise.resolve(failStep(`post gate: suites or smoke fail after ${step.id}; step rolled back`));
+    }
+    if (evidence.newFindings.length > 0) {
+        const names = evidence.newFindings
+            .map((finding) => finding.ruleId)
+            .sort()
+            .join(", ");
+        return Promise.resolve(failStep(`post gate: ${step.id} introduces findings outside its scope: ${names}`));
+    }
+    if (!evidence.targetsMet) {
+        return Promise.resolve(failStep(`post gate: ${step.id} target keys did not fall by their expectedDelta`));
+    }
+    if (!evidence.ratchetClean) {
+        return Promise.resolve(failStep(`post gate: a ratchet key rose under ${step.id}`));
+    }
+    const oversize = checkRemediationStepSize(evidence.filesChanged, evidence.changedLines, step.scope[0] ?? step.id);
+    if (oversize.length > 0) {
+        return Promise.resolve(failStep(`post gate: ${oversize.map((finding) => finding.message).join("; ")}`));
+    }
+    return Promise.resolve({ ok: true, value: { ...step, status: "done" } });
+}

package/dist/features/remediation/step-split.d.ts

@@ -0,0 +1,12 @@
+import type { RemediationStep } from "./types.ts";
+export interface SplitDetail {
+    readonly packages?: ReadonlyArray<string> | undefined;
+    readonly modules?: ReadonlyArray<string> | undefined;
+    readonly batchFiles?: number | undefined;
+    readonly regions?: ReadonlyArray<string> | undefined;
+}
+export interface SplitOutcome {
+    readonly children: ReadonlyArray<Omit<RemediationStep, "id">>;
+    readonly blocked: boolean;
+}
+export declare function splitRemediationStep(step: RemediationStep, detail?: SplitDetail): SplitOutcome;