codictator 0.0.0 → 0.1.3

package/dist/features/deps/snapshot-verdicts.js

@@ -0,0 +1,184 @@
+import { classifyNpmRange, isUnversionedNpmSource } from "./npm.js";
+import { eligibleStableVersions, lagDaysFor, selectLatestStable, snapshotAdvisoriesFor, } from "./selection.js";
+import { compareNpmVersions, parseNpmVersion } from "./stable.js";
+function checkUnpublished(input) {
+    if (!input.unpublished.includes(input.dep.name)) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-no-deprecated",
+        path: input.path,
+        message: `${input.dep.name} is unpublished in the registry`,
+        remediation: `Replace ${input.dep.name} with a maintained package.`,
+    };
+}
+function checkDeprecated(snapshot, path, name, pinned) {
+    const detail = snapshot.packages[name]?.versions[pinned];
+    if (detail?.deprecated !== true && detail?.yanked !== true) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-no-deprecated",
+        path,
+        message: `${name}@${pinned} in ${path} is deprecated or yanked`,
+        remediation: `Replace ${name} with a maintained package.`,
+    };
+}
+// SPEC §4.8.5: the remediation names the minimal fixed version and the
+// latest stable; with no clean fix it says replace or remove (EC-3).
+function checkVulnerable(input, pinned) {
+    const affecting = snapshotAdvisoriesFor(input.snapshot, input.dep.name, pinned);
+    if (affecting.length === 0) {
+        return undefined;
+    }
+    const fixed = minimalFixedVersion(input.snapshot, input.dep.name, pinned, input.params);
+    const latest = selectLatestStable(input.snapshot, input.dep.name, {
+        pinned,
+        params: input.params,
+    });
+    const latestName = latest.ok ? latest.value.version : "unknown";
+    return {
+        ruleId: "core/dep-no-vulnerable",
+        path: input.path,
+        message: `${input.dep.name}@${pinned} in ${input.path} has ${String(affecting.length)} known advisories`,
+        remediation: fixed === undefined
+            ? `Replace or remove ${input.dep.name}; latest stable is ${latestName}.`
+            : `Upgrade ${input.dep.name} to ${fixed}; latest stable is ${latestName}.`,
+    };
+}
+function checkLicense(snapshot, allow, path, name, pinned) {
+    const license = snapshot.packages[name]?.versions[pinned]?.license;
+    if (license !== undefined && allow.includes(license)) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-license",
+        path,
+        message: `${name}@${pinned} in ${path} has license ${license ?? "unknown"}`,
+        remediation: `Replace ${name} with an allowed-license package or tighten the policy.`,
+    };
+}
+function checkPrerelease(path, name, pinned) {
+    if (parseNpmVersion(pinned)?.prerelease === undefined) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-latest-stable",
+        path,
+        message: `${name}@${pinned} in ${path} is a prerelease, never stable`,
+        remediation: `Pin ${name} to a stable release.`,
+    };
+}
+function checkStaleness(input, pinned, notes) {
+    const latest = selectLatestStable(input.snapshot, input.dep.name, {
+        pinned,
+        params: input.params,
+    });
+    if (!latest.ok || latest.value.version === pinned) {
+        return undefined;
+    }
+    const pinnedParsed = parseNpmVersion(pinned);
+    if (pinnedParsed === undefined) {
+        return undefined;
+    }
+    const sameMajor = latest.value.parsed.major === pinnedParsed.major;
+    const limit = sameMajor ? input.params.lagDays : input.params.majorLagDays;
+    const lag = lagDaysFor(input.snapshot, input.dep.name, pinned, {
+        pinned,
+        params: input.params,
+    });
+    if ((lag ?? 0) <= limit) {
+        const remaining = Math.max(0, Math.ceil(limit - (lag ?? 0)));
+        notes.push(`${input.dep.name} in ${input.path} is ${String(Math.floor(lag ?? 0))} days behind ${latest.value.version}; blocks in ${String(remaining)} days`);
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-latest-stable",
+        path: input.path,
+        message: `${input.dep.name}@${pinned} in ${input.path} lags latest stable ${latest.value.version} by ${String(Math.floor(lag ?? 0))} days`,
+        remediation: `Upgrade ${input.dep.name} to a release newer than ${String(limit)} days.`,
+    };
+}
+export function checkPinnedVerdicts(input, pinned, notes) {
+    const unpublished = checkUnpublished(input);
+    if (unpublished !== undefined) {
+        return [unpublished];
+    }
+    const findings = [];
+    const deprecated = checkDeprecated(input.snapshot, input.path, input.dep.name, pinned);
+    if (deprecated !== undefined) {
+        findings.push(deprecated);
+    }
+    const vulnerable = checkVulnerable(input, pinned);
+    if (vulnerable !== undefined) {
+        findings.push(vulnerable);
+    }
+    const license = checkLicense(input.snapshot, input.allow, input.path, input.dep.name, pinned);
+    if (license !== undefined) {
+        findings.push(license);
+    }
+    const prerelease = checkPrerelease(input.path, input.dep.name, pinned);
+    if (prerelease !== undefined) {
+        return [...findings, prerelease];
+    }
+    const stale = checkStaleness(input, pinned, notes);
+    if (stale !== undefined) {
+        findings.push(stale);
+    }
+    return findings;
+}
+// The minimal S9-aware fix: the oldest same-major version free of the pinned
+// version's advisories.
+export function minimalFixedVersion(snapshot, name, pinned, params) {
+    const pinnedParsed = parseNpmVersion(pinned);
+    if (pinnedParsed === undefined) {
+        return undefined;
+    }
+    const pinnedAdvisories = snapshotAdvisoriesFor(snapshot, name, pinned);
+    let best;
+    for (const candidate of eligibleStableVersions(snapshot, name, {
+        pinned,
+        params,
+    })) {
+        if (candidate.parsed.major !== pinnedParsed.major) {
+            continue;
+        }
+        if (snapshotAdvisoriesFor(snapshot, name, candidate.version).length > 0) {
+            continue;
+        }
+        if (pinnedAdvisories.length === 0) {
+            return candidate.version;
+        }
+        const fixes = pinnedAdvisories.some((advisory) => !snapshotAdvisoriesFor(snapshot, name, candidate.version).includes(advisory));
+        if (!fixes) {
+            continue;
+        }
+        const bestParsed = best === undefined ? undefined : parseNpmVersion(best);
+        if (bestParsed === undefined ||
+            compareNpmVersions(candidate.parsed, bestParsed) < 0) {
+            best = candidate.version;
+        }
+    }
+    return best;
+}
+export function pinnedOrUnversionedNote(path, name) {
+    return `${name} in ${path} is an unversioned source; latest-stable skipped`;
+}
+// Exact pins (and prerelease exacts, judged as never-stable) run against the
+// snapshot; unversioned sources skip latest-stable; ranges are exact-pin
+// findings, never snapshot rows.
+export function snapshotForm(range) {
+    const form = classifyNpmRange(range);
+    if (form === "exact" ||
+        form === "alias-exact" ||
+        form === "workspace-exact") {
+        return "pinned";
+    }
+    if (isUnversionedNpmSource(range)) {
+        return "unversioned";
+    }
+    if (parseNpmVersion(range)?.prerelease !== undefined) {
+        return "pinned";
+    }
+    return "ranged";
+}

package/dist/features/deps/stable.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_LAG_DAYS = 30;
+export declare const DEFAULT_MAJOR_LAG_DAYS = 60;
+export declare const DEFAULT_MIN_RELEASE_AGE_DAYS = 7;
+export declare const MS_PER_DAY = 86400000;
+export interface DepLagParams {
+    readonly lagDays: number;
+    readonly majorLagDays: number;
+    readonly minReleaseAgeDays: number;
+}
+export declare const DEFAULT_DEP_LAG_PARAMS: DepLagParams;
+export interface SemVer {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease: ReadonlyArray<string> | undefined;
+}
+export declare function parseNpmVersion(value: string): SemVer | undefined;
+export declare function isNpmPrerelease(value: string): boolean;
+export declare function compareNpmVersions(left: SemVer, right: SemVer): -1 | 0 | 1;

package/dist/features/deps/stable.js

@@ -0,0 +1,131 @@
+// SPEC §6.1: version order for the npm ecosystem (numeric parts first,
+// release beats prerelease, prerelease identifiers numeric then lexical).
+// Latest-stable selection lives in selection.ts.
+// SPEC §5.3: tunable defaults for core/dep-latest-stable.
+export const DEFAULT_LAG_DAYS = 30;
+export const DEFAULT_MAJOR_LAG_DAYS = 60;
+export const DEFAULT_MIN_RELEASE_AGE_DAYS = 7;
+export const MS_PER_DAY = 86_400_000;
+export const DEFAULT_DEP_LAG_PARAMS = {
+    lagDays: DEFAULT_LAG_DAYS,
+    majorLagDays: DEFAULT_MAJOR_LAG_DAYS,
+    minReleaseAgeDays: DEFAULT_MIN_RELEASE_AGE_DAYS,
+};
+// SPEC §6.1: an exact pin is a full x.y.z with an optional -pre suffix;
+// compare follows npm version order (numeric parts first, release beats
+// prerelease, prerelease identifiers numeric then lexical).
+// The pattern lives at module scope so its quantifiers never count as
+// branches of the function that applies it.
+const NPM_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function versionPart(match, index) {
+    return Number(match[index] ?? "");
+}
+function narrowVersionParts(match) {
+    const major = versionPart(match, 1);
+    const minor = versionPart(match, 2);
+    const patch = versionPart(match, 3);
+    if (!Number.isSafeInteger(major) ||
+        !Number.isSafeInteger(minor) ||
+        !Number.isSafeInteger(patch)) {
+        return undefined;
+    }
+    return { major, minor, patch };
+}
+export function parseNpmVersion(value) {
+    const match = NPM_VERSION_PATTERN.exec(value);
+    if (match === null) {
+        return undefined;
+    }
+    const parts = narrowVersionParts(match);
+    if (parts === undefined) {
+        return undefined;
+    }
+    const pre = match[4];
+    if (pre === undefined || pre === "") {
+        return { ...parts, prerelease: undefined };
+    }
+    return { ...parts, prerelease: pre.split(".") };
+}
+export function isNpmPrerelease(value) {
+    const parsed = parseNpmVersion(value);
+    return parsed !== undefined && parsed.prerelease !== undefined;
+}
+function compareIdentifiers(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        const leftNumber = Number(left);
+        const rightNumber = Number(right);
+        if (leftNumber < rightNumber) {
+            return -1;
+        }
+        if (leftNumber > rightNumber) {
+            return 1;
+        }
+        return 0;
+    }
+    if (leftNumeric) {
+        return -1;
+    }
+    if (rightNumeric) {
+        return 1;
+    }
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}
+function compareVersionCore(left, right) {
+    const pairs = [
+        [left.major, right.major],
+        [left.minor, right.minor],
+        [left.patch, right.patch],
+    ];
+    for (const pair of pairs) {
+        if (pair[0] < pair[1]) {
+            return -1;
+        }
+        if (pair[0] > pair[1]) {
+            return 1;
+        }
+    }
+    return 0;
+}
+function prereleaseOrderAt(left, right, index) {
+    const leftId = left[index];
+    const rightId = right[index];
+    if (leftId === undefined) {
+        return -1;
+    }
+    if (rightId === undefined) {
+        return 1;
+    }
+    const order = compareIdentifiers(leftId, rightId);
+    return order === 0 ? undefined : order;
+}
+function comparePrerelease(left, right) {
+    if (left === undefined) {
+        return right === undefined ? 0 : 1;
+    }
+    if (right === undefined) {
+        return -1;
+    }
+    const length = Math.max(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const order = prereleaseOrderAt(left, right, index);
+        if (order !== undefined) {
+            return order;
+        }
+    }
+    return 0;
+}
+export function compareNpmVersions(left, right) {
+    const core = compareVersionCore(left, right);
+    if (core !== 0) {
+        return core;
+    }
+    return comparePrerelease(left.prerelease, right.prerelease);
+}

package/dist/features/deps/step-size.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "../engine/index.ts";
+export interface StepSizeParams {
+    readonly maxFiles: number;
+    readonly maxChangedLines: number;
+}
+export declare const DEFAULT_STEP_SIZE: StepSizeParams;
+export declare function checkRemediationStepSize(filesChanged: number, changedLines: number, path: string, params?: StepSizeParams): Array<Finding>;

package/dist/features/deps/step-size.js

@@ -0,0 +1,24 @@
+// SPEC §5.6 defaults: 10 files, 300 lines (bound 20 and 600).
+export const DEFAULT_STEP_SIZE = {
+    maxFiles: 10,
+    maxChangedLines: 300,
+};
+function sizeFinding(path, count, limit, unit) {
+    return {
+        ruleId: "core/remediation-step-size",
+        path,
+        message: `remediation step touches ${count} ${unit}, above the ${limit} ${unit} budget`,
+        remediation: `Split the step touching ${path} below ${limit}.`,
+    };
+}
+// Files first, then lines, so repeated runs observe the same order (§10.3).
+export function checkRemediationStepSize(filesChanged, changedLines, path, params = DEFAULT_STEP_SIZE) {
+    const findings = [];
+    if (filesChanged > params.maxFiles) {
+        findings.push(sizeFinding(path, filesChanged, params.maxFiles, "files"));
+    }
+    if (changedLines > params.maxChangedLines) {
+        findings.push(sizeFinding(path, changedLines, params.maxChangedLines, "lines"));
+    }
+    return findings;
+}

package/dist/features/deps/upgrade.d.ts

@@ -0,0 +1,35 @@
+import type { Result } from "../../kernel/index.ts";
+export interface UpgradeFile {
+    readonly path: string;
+    readonly text: string;
+}
+export interface UpgradePrInput {
+    readonly ecosystem: string;
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+    readonly manifestPath: string;
+    readonly manifestText: string;
+    readonly historyText?: string | undefined;
+    readonly historyPath?: string | undefined;
+    readonly date: string;
+    readonly task?: string | undefined;
+    readonly advisoryIds?: ReadonlyArray<string> | undefined;
+    readonly lockfilePath?: string | undefined;
+    readonly lockfileText?: string | undefined;
+}
+export interface UpgradePrPlan {
+    readonly branch: string;
+    readonly subject: string;
+    readonly files: ReadonlyArray<UpgradeFile>;
+}
+export interface UpgradeHost {
+    readonly createBranch: (branch: string) => Promise<Result<void>>;
+    readonly writeFiles: (files: ReadonlyArray<UpgradeFile>) => Promise<Result<void>>;
+    readonly commit: (message: string) => Promise<Result<void>>;
+    readonly push: (branch: string) => Promise<Result<void>>;
+}
+export declare function upgradeCommitSubject(name: string, from: string, to: string): string;
+export declare function upgradeHistoryEntry(date: string, commitSubject: string, name: string, from: string, to: string, task: string, advisoryIds: ReadonlyArray<string>): string;
+export declare function planUpgradePr(input: UpgradePrInput): Result<UpgradePrPlan>;
+export declare function runUpgradePr(plan: UpgradePrPlan, host: UpgradeHost): Promise<Result<UpgradePrPlan>>;

package/dist/features/deps/upgrade.js

@@ -0,0 +1,124 @@
+// SPEC §4.8.7: Codictator's own upgrade changes. Planning is pure over
+// caller-supplied manifest and history text; pushing runs through the host
+// port the caller implements, so this module never touches the OS (§3.3).
+// One branch per dependency, grouping patch and minor of the same package
+// line; majors become remediation chains (§4.13.5), never single PRs.
+import { makeError } from "../../kernel/index.js";
+import { upgradeBranchName } from "./bots.js";
+// The commit subject doubles as the history entry Subject (§4.9.3 unit rule),
+// and satisfies core/conventional-commit on its own (chore with a deps scope).
+export function upgradeCommitSubject(name, from, to) {
+    return `chore(deps): upgrade ${name} ${from} to ${to}`;
+}
+// SPEC §7.7: a deps entry carries Kind, Task, Why and one Deps line per
+// change in the added, upgraded or removed form.
+export function upgradeHistoryEntry(date, commitSubject, name, from, to, task, advisoryIds) {
+    const rendered = advisoryIds.length === 0 ? "none" : [...advisoryIds].sort().join(", ");
+    return [
+        `## ${date} · ${commitSubject}`,
+        `- **Kind:** deps`,
+        `- **Task:** ${task}`,
+        `- **Why:** L5 sweep upgrades ${name} to latest stable ${to} (SPEC §4.8.7).`,
+        `- **Deps:** ↑ ${name} ${from} → ${to} — ${rendered}`,
+    ].join("\n");
+}
+function escapeRegExp(value) {
+    return value.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+}
+function bumpManifestPin(manifestText, name, from, to) {
+    const pattern = new RegExp(`"${escapeRegExp(name)}"\\s*:\\s*"${escapeRegExp(from)}"`);
+    if (!pattern.test(manifestText)) {
+        return {
+            ok: false,
+            error: makeError("CDX-E903", `${name} is not pinned at ${from} in the supplied manifest`, `Supply the manifest text pinning ${name} at ${from}, or re-resolve the upgrade.`),
+        };
+    }
+    return {
+        ok: true,
+        value: manifestText.replace(pattern, `"${name}": "${to}"`),
+    };
+}
+function appendHistoryEntry(historyText, date, entry) {
+    const day = date.slice(0, 10);
+    if (historyText === undefined || historyText.trim() === "") {
+        return `# History — ${day}\n\n${entry}\n`;
+    }
+    const endOfTitle = historyText.indexOf("\n");
+    if (endOfTitle < 0) {
+        return `${historyText}\n\n${entry}\n`;
+    }
+    const title = historyText.slice(0, endOfTitle);
+    const rest = historyText.slice(endOfTitle + 1).replace(/^\n+/, "");
+    if (rest === "") {
+        return `${title}\n\n${entry}\n`;
+    }
+    return `${title}\n\n${entry}\n\n${rest.endsWith("\n") ? rest : `${rest}\n`}`;
+}
+function checkUpgradeDate(date) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        return { ok: true, value: date };
+    }
+    return {
+        ok: false,
+        error: makeError("CDX-E903", `upgrade date ${date} is not a UTC YYYY-MM-DD date`, "Pass the commit date in UTC as YYYY-MM-DD."),
+    };
+}
+function upgradePlanFiles(input, manifestText, entry) {
+    const historyPath = input.historyPath ?? `docs/HISTORY/${input.date.slice(0, 10)}.md`;
+    const files = [
+        { path: input.manifestPath, text: manifestText },
+        {
+            path: historyPath,
+            text: appendHistoryEntry(input.historyText, input.date, entry),
+        },
+    ];
+    if (input.lockfilePath !== undefined && input.lockfileText !== undefined) {
+        files.push({ path: input.lockfilePath, text: input.lockfileText });
+    }
+    return files;
+}
+// SPEC §4.8.7: the PR holds the manifest edit, the regenerated lockfile and
+// its history entry. The lockfile bytes come from the caller (regenerated by
+// the ecosystem tool); without them the plan holds manifest plus history.
+export function planUpgradePr(input) {
+    const dated = checkUpgradeDate(input.date);
+    if (!dated.ok) {
+        return dated;
+    }
+    const bumped = bumpManifestPin(input.manifestText, input.name, input.from, input.to);
+    if (!bumped.ok) {
+        return bumped;
+    }
+    const subject = upgradeCommitSubject(input.name, input.from, input.to);
+    const entry = upgradeHistoryEntry(input.date, subject, input.name, input.from, input.to, input.task ?? "none", input.advisoryIds ?? []);
+    return {
+        ok: true,
+        value: {
+            branch: upgradeBranchName(input.ecosystem, input.name, input.to),
+            subject,
+            files: upgradePlanFiles(input, bumped.value, entry),
+        },
+    };
+}
+// One step, one PR: the branch is created from the base, committed with its
+// history entry, and pushed through the host API with the CI token. Nothing
+// is pushed to the default branch.
+export async function runUpgradePr(plan, host) {
+    const branched = await host.createBranch(plan.branch);
+    if (!branched.ok) {
+        return branched;
+    }
+    const written = await host.writeFiles(plan.files);
+    if (!written.ok) {
+        return written;
+    }
+    const committed = await host.commit(plan.subject);
+    if (!committed.ok) {
+        return committed;
+    }
+    const pushed = await host.push(plan.branch);
+    if (!pushed.ok) {
+        return pushed;
+    }
+    return { ok: true, value: plan };
+}

package/dist/features/deps/verdicts.d.ts

@@ -0,0 +1,21 @@
+import type { Finding } from "../engine/index.ts";
+import { type DepEvalInput, type DepEvaluation, type EvalManifest } from "./eval.ts";
+import type { NpmDepKind } from "./npm.ts";
+export declare function manifestToEval(manifest: {
+    readonly path: string;
+    readonly dependencies: ReadonlyArray<{
+        readonly name: string;
+        readonly range: string;
+        readonly kind?: NpmDepKind;
+    }>;
+}): EvalManifest;
+export declare function evaluateDepVerdicts(input: DepEvalInput): DepEvaluation;
+export declare function depErrorFinding(ruleId: string, path: string, error: {
+    readonly code: string;
+    readonly message: string;
+}, remediation: string): Finding;
+export declare function makeDepError(code: string, message: string, remediation: string): {
+    readonly code: string;
+    readonly message: string;
+    readonly remediation: string;
+};