codictator 0.0.0 → 0.1.3

package/dist/features/deps/pypi.js

@@ -0,0 +1,137 @@
+// SPEC §6.3 driver `pypi`: manifest parsing, exact-pin forms and hash
+// discipline. PEP 508 requirement strings, requirements.txt files with
+// `--hash` entries and the `.python-version` toolchain file; the
+// `[project]` table of pyproject.toml lives in pypi-pyproject.ts, mirroring
+// the npm driver split (manifest logic here, lockfile in lockfile.ts).
+// Everything here is pure over caller-supplied text; a Driver instance that
+// reads the repo waits for gate-closure wiring with ports (SPEC §3.3).
+import { err, makeError, ok } from "../../kernel/index.js";
+export const PYPI_ECOSYSTEM = "pypi";
+// SPEC §6.3: exact pin is `==` plus a full `x.y.z` (optional pre/post
+// segment); `==2` and `==2.31` are ranges, not pins.
+const PYPI_EXACT_SPEC = /^==\d+\.\d+\.\d+(?:[-+_.][0-9A-Za-z.+-]+)?$/;
+export function isExactPyPiPin(spec) {
+    const trimmed = spec.trim();
+    return PYPI_EXACT_SPEC.test(trimmed);
+}
+export function classifyPyPiSpec(spec) {
+    const trimmed = spec.trim();
+    if (trimmed.startsWith("@") || trimmed.includes("://")) {
+        return "url";
+    }
+    return isExactPyPiPin(trimmed) ? "exact" : "range";
+}
+// pip joins backslash continuations before parsing, so a `--hash` entry
+// may ride the requirement line or the lines after it.
+function logicalLines(text) {
+    const out = [];
+    let current = "";
+    for (const raw of text.split("\n")) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line.endsWith("\\")) {
+            current += `${line.slice(0, -1)} `;
+            continue;
+        }
+        current += line;
+        out.push(current);
+        current = "";
+    }
+    if (current !== "") {
+        out.push(current);
+    }
+    return out;
+}
+// A `#` starts a comment only at the line start or after whitespace, so
+// URL fragments such as `#egg=` survive the strip.
+export function stripComment(line) {
+    for (let index = 0; index < line.length; index += 1) {
+        if (line[index] === "#" &&
+            (index === 0 || line[index - 1] === " " || line[index - 1] === "\t")) {
+            return line.slice(0, index);
+        }
+    }
+    return line;
+}
+function takeHashes(line) {
+    const hashes = [];
+    const clean = line.replace(/\s+--hash=\S+/g, (token) => {
+        hashes.push(token.replace(/^\s+--hash=/, ""));
+        return "";
+    });
+    return { clean: clean.trim(), hashes };
+}
+// A PEP 508 requirement is a name with optional extras, a version spec
+// and an optional environment marker; only the name and spec judge pins.
+export function splitRequirement(line) {
+    const trimmed = line.trim();
+    const name = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?/.exec(trimmed)?.[0];
+    if (name === undefined) {
+        return undefined;
+    }
+    const rest = trimmed
+        .slice(name.length)
+        .replace(/^\[[^\]]*\]/, "")
+        .split(";", 1)[0] ?? "";
+    return { name, spec: rest.trim() };
+}
+export function sortByName(items) {
+    items.sort((left, right) => {
+        if (left.name === right.name) {
+            return 0;
+        }
+        return left.name < right.name ? -1 : 1;
+    });
+}
+export function depParseError(message, fix) {
+    return err(makeError("CDX-E101", message, fix));
+}
+function pushRequirementLine(found, uncommented) {
+    const taken = takeHashes(uncommented);
+    const req = splitRequirement(taken.clean);
+    if (req === undefined) {
+        return depParseError("requirements.txt line is not a requirement string", "Write the line as a PEP 508 requirement string.");
+    }
+    found.push({
+        name: req.name,
+        spec: req.spec,
+        hashes: [...taken.hashes],
+    });
+    return ok(undefined);
+}
+// SPEC §6.3 and §6.4 EC-7: a requirements line is pinned only as `==`;
+// ranges such as `requests>=2` block core/dep-exact-pin. A line that is
+// neither a directive nor a requirement fails closed instead of silently
+// dropping a dependency the verdicts cannot see.
+export function parseRequirementsText(text) {
+    const found = [];
+    for (const line of logicalLines(text)) {
+        const uncommented = stripComment(line).trim();
+        if (uncommented === "") {
+            continue;
+        }
+        if (uncommented.startsWith("--hash")) {
+            return depParseError("requirements.txt hash entry names no requirement", "Join the hash to the requirement line with a trailing backslash.");
+        }
+        if (uncommented.startsWith("-")) {
+            continue;
+        }
+        const pushed = pushRequirementLine(found, uncommented);
+        if (!pushed.ok) {
+            return err(pushed.error);
+        }
+    }
+    sortByName(found);
+    return ok(found);
+}
+// SPEC §6.3: a requirements lockfile is fully pinned (`==`) with hashes.
+export function requirementsFullyPinned(reqs) {
+    return (reqs.length > 0 &&
+        reqs.every((req) => isExactPyPiPin(req.spec) && req.hashes.length > 0));
+}
+// SPEC §6.3 toolchain: `.python-version` names the exact interpreter.
+export function parsePythonVersionFile(text) {
+    return text.trim();
+}
+export function isExactPythonVersion(version) {
+    return /^\d+\.\d+\.\d+(?:[-+_.][0-9A-Za-z.+-]+)?$/.test(version.trim());
+}

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

@@ -0,0 +1,29 @@
+import { type Net, type Result } from "../../kernel/index.ts";
+import type { RegistrySnapshot } from "./index.ts";
+export declare const NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+export declare const REGISTRY_TIMEOUT_MS = 30000;
+export declare const SNAPSHOT_MAX_AGE_MS: number;
+export declare const SNAPSHOT_CACHE_PATH = ".codictator/cache/registry/npm.json";
+export interface NpmDocVersion {
+    readonly deprecated: boolean;
+    readonly license: string | undefined;
+    readonly engines: string | undefined;
+}
+export interface NpmPackument {
+    readonly name: string;
+    readonly unpublished: boolean;
+    readonly times: Readonly<Record<string, string>>;
+    readonly versions: Readonly<Record<string, NpmDocVersion>>;
+}
+export interface RegistryFetchOptions {
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly retries?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export declare function fetchNpmPackument(net: Net, name: string, options?: RegistryFetchOptions): Promise<Result<NpmPackument>>;
+export declare function buildSnapshot(ecosystem: string, fetchedAt: string, packuments: ReadonlyArray<NpmPackument>, advisories: Readonly<Record<string, ReadonlyArray<string>>>): RegistrySnapshot;
+export declare function hashSnapshot(snapshot: RegistrySnapshot): string;
+export type SnapshotFreshness = "fresh" | "stale" | "missing";
+export declare function snapshotFreshness(snapshot: RegistrySnapshot | undefined, now: string): SnapshotFreshness;
+export declare function snapshotAsOf(snapshot: RegistrySnapshot): string;

package/dist/features/deps/registry.js

@@ -0,0 +1,158 @@
+// SPEC §4.8.2 and §4.8.4: the npm registry document over the Net port, the
+// §7.12 snapshot it feeds, and the freshness rules per layer. Every call
+// goes through the Net allowlist (§9.2); 127.0.0.1 replay servers arrive as
+// an injected base URL in tests, never as production code.
+import { err, makeError, ok, parseJson, sha256Text, stableStringify, } from "../../kernel/index.js";
+import { field, isJsonRecord, recordField, stringField } from "./fields.js";
+import { isRetryableStatus, retryDelaysMs } from "./osv.js";
+export const NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+export const REGISTRY_TIMEOUT_MS = 30_000;
+export const SNAPSHOT_MAX_AGE_MS = 24 * 86_400_000;
+export const SNAPSHOT_CACHE_PATH = ".codictator/cache/registry/npm.json";
+function isPublishTime(version, published) {
+    return (version !== "created" &&
+        version !== "modified" &&
+        typeof published === "string");
+}
+function narrowTimeTable(value) {
+    const times = {};
+    const timeTable = recordField(value, "time");
+    if (timeTable === undefined) {
+        return times;
+    }
+    for (const [version, published] of Object.entries(timeTable)) {
+        if (isPublishTime(version, published)) {
+            times[version] = published;
+        }
+    }
+    return times;
+}
+function narrowVersionDetail(detail) {
+    if (!isJsonRecord(detail)) {
+        return undefined;
+    }
+    const enginesTable = recordField(detail, "engines");
+    return {
+        deprecated: typeof field(detail, "deprecated") === "string" ||
+            field(detail, "deprecated") === true,
+        license: stringField(detail, "license"),
+        engines: enginesTable === undefined
+            ? undefined
+            : stringField(enginesTable, "node"),
+    };
+}
+function narrowVersionTable(value) {
+    const versions = {};
+    const versionTable = recordField(value, "versions");
+    if (versionTable === undefined) {
+        return versions;
+    }
+    for (const [version, detail] of Object.entries(versionTable)) {
+        const narrowed = narrowVersionDetail(detail);
+        if (narrowed !== undefined) {
+            versions[version] = narrowed;
+        }
+    }
+    return versions;
+}
+function narrowPackument(name, value) {
+    if (!isJsonRecord(value)) {
+        return { name, unpublished: true, times: {}, versions: {} };
+    }
+    const versions = narrowVersionTable(value);
+    if (Object.keys(versions).length === 0) {
+        return { name, unpublished: true, times: {}, versions: {} };
+    }
+    return { name, unpublished: false, times: narrowTimeTable(value), versions };
+}
+// SPEC §4.8.2: the full document (the abbreviated form lacks `time`).
+// A 404 is unpublished (EC-4), not a transport failure.
+export async function fetchNpmPackument(net, name, options = {}) {
+    const base = options.baseUrl ?? NPM_REGISTRY_BASE_URL;
+    const url = `${base}/${encodeURIComponent(name)}`;
+    const retries = options.retries ?? retryDelaysMs().length;
+    const delays = retryDelaysMs();
+    let attempt = 0;
+    for (;;) {
+        const sent = await net.request({
+            method: "GET",
+            url,
+            headers: { accept: "application/json" },
+            timeoutMs: options.timeoutMs ?? REGISTRY_TIMEOUT_MS,
+        });
+        if (!sent.ok) {
+            return err(sent.error);
+        }
+        const response = sent.value;
+        if (response.status === 200) {
+            const parsed = parseJson(response.body);
+            if (!parsed.ok) {
+                return err(parsed.error);
+            }
+            return ok(narrowPackument(name, parsed.value));
+        }
+        if (response.status === 404) {
+            return ok({
+                name,
+                unpublished: true,
+                times: {},
+                versions: {},
+            });
+        }
+        if (isRetryableStatus(response.status) && attempt < retries) {
+            const delay = delays[Math.min(attempt, delays.length - 1)] ?? 1000;
+            if (options.sleep !== undefined) {
+                await options.sleep(delay);
+            }
+            attempt += 1;
+            continue;
+        }
+        return err(makeError("CDX-E401", `npm registry query for ${name} failed with status ${String(response.status)}`, "Retry the sweep; without registry data dependency changes block fail-closed."));
+    }
+}
+// SPEC §4.8.4: each run stores the fetched documents it used with fetchedAt;
+// the snapshot hash enters every verdict (§4.3.6).
+export function buildSnapshot(ecosystem, fetchedAt, packuments, advisories) {
+    const packages = {};
+    for (const doc of packuments) {
+        const versions = {};
+        for (const version of Object.keys(doc.versions).sort()) {
+            const detail = doc.versions[version];
+            const published = doc.times[version];
+            if (detail === undefined || published === undefined) {
+                continue;
+            }
+            versions[version] = {
+                published,
+                ...(detail.deprecated ? { deprecated: true } : {}),
+                ...(detail.license !== undefined ? { license: detail.license } : {}),
+                ...(detail.engines !== undefined ? { engines: detail.engines } : {}),
+            };
+        }
+        packages[doc.name] = { versions };
+    }
+    return {
+        version: 1,
+        ecosystem,
+        fetchedAt,
+        packages,
+        advisories: { ...advisories },
+    };
+}
+export function hashSnapshot(snapshot) {
+    return sha256Text(stableStringify(snapshot));
+}
+export function snapshotFreshness(snapshot, now) {
+    if (snapshot === undefined) {
+        return "missing";
+    }
+    const nowMs = Date.parse(now);
+    const fetchedMs = Date.parse(snapshot.fetchedAt);
+    if (Number.isNaN(nowMs) || Number.isNaN(fetchedMs) || fetchedMs > nowMs) {
+        return "missing";
+    }
+    return nowMs - fetchedMs < SNAPSHOT_MAX_AGE_MS ? "fresh" : "stale";
+}
+export function snapshotAsOf(snapshot) {
+    return `as of ${snapshot.fetchedAt}`;
+}

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

@@ -0,0 +1,15 @@
+import { parseJson } from "../../kernel/index.ts";
+import type { Finding } from "../engine/index.ts";
+export interface RenovateOwnedKeys {
+    readonly rangeStrategy: string;
+    readonly minimumReleaseAge: string | null;
+    readonly osvVulnerabilityAlerts: boolean;
+    readonly pinDigests: boolean;
+    readonly separateMajorMinor: boolean;
+    readonly lockFileMaintenanceEnabled: boolean;
+    readonly dependencyDashboard: boolean;
+    readonly extendsHasActionDigests: boolean;
+}
+export declare function expectedRenovateKeys(minReleaseAgeDays: number): RenovateOwnedKeys;
+export declare function parseRenovateText(text: string): ReturnType<typeof parseJson>;
+export declare function checkRenovateOwnedKeys(path: string, text: string, minReleaseAgeDays: number): ReadonlyArray<Finding>;

package/dist/features/deps/renovate.js

@@ -0,0 +1,98 @@
+// SPEC §4.8.6: the owned keys of the Renovate config. Checks are
+// pure over caller-supplied text; the enforcer layer reads the files.
+import { parseJson } from "../../kernel/index.js";
+import { field, isJsonRecord, recordField } from "./fields.js";
+// SPEC §4.8.6: Renovate owned keys with values from the effective config.
+export function expectedRenovateKeys(minReleaseAgeDays) {
+    return {
+        rangeStrategy: "pin",
+        minimumReleaseAge: `${String(minReleaseAgeDays)} days`,
+        osvVulnerabilityAlerts: true,
+        pinDigests: true,
+        separateMajorMinor: true,
+        lockFileMaintenanceEnabled: true,
+        dependencyDashboard: true,
+        extendsHasActionDigests: true,
+    };
+}
+// JSON5 tolerance for renovate.json5: strip line/block comments and trailing
+// commas before the kernel JSON parse. Anything else stays a parse error.
+export function parseRenovateText(text) {
+    const stripped = text
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|\s)\/\/[^\n]*/g, "$1")
+        .replace(/,(\s*[}\]])/g, "$1");
+    return parseJson(stripped);
+}
+function checkRenovateRange(path, config, expected) {
+    if (field(config, "rangeStrategy") === expected.rangeStrategy) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-exact-pin",
+        path,
+        message: `${path} sets rangeStrategy to ${JSON.stringify(field(config, "rangeStrategy"))} instead of "pin"`,
+        remediation: `Regenerate the bot config so rangeStrategy is "pin".`,
+    };
+}
+function checkRenovateExtends(path, config) {
+    const extendsValue = field(config, "extends");
+    const extendsList = Array.isArray(extendsValue)
+        ? extendsValue.filter((entry) => typeof entry === "string")
+        : [];
+    if (extendsList.some((entry) => entry.includes("helpers:pinGitHubActionDigests"))) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-exact-pin",
+        path,
+        message: `${path} extends misses helpers:pinGitHubActionDigests`,
+        remediation: `Regenerate the bot config with the owned extends entry.`,
+    };
+}
+function checkRenovateOsv(path, config) {
+    if (field(config, "osvVulnerabilityAlerts") === true) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-no-vulnerable",
+        path,
+        message: `${path} disables osvVulnerabilityAlerts`,
+        remediation: `Regenerate the bot config with osvVulnerabilityAlerts enabled.`,
+    };
+}
+function checkRenovateS9(path, config) {
+    const vulnAlerts = recordField(config, "vulnerabilityAlerts");
+    if (vulnAlerts !== undefined &&
+        field(vulnAlerts, "minimumReleaseAge") === null) {
+        return undefined;
+    }
+    return {
+        ruleId: "core/dep-no-vulnerable",
+        path,
+        message: `${path} lacks the S9 vulnerabilityAlerts.minimumReleaseAge null exemption`,
+        remediation: `Regenerate the bot config with the S9 exemption.`,
+    };
+}
+// SPEC §4.8.8 EC-15: an owned key with the wrong value is drift until regen
+// rewrites it; each drift is a finding on the bot file.
+export function checkRenovateOwnedKeys(path, text, minReleaseAgeDays) {
+    const parsed = parseRenovateText(text);
+    if (!parsed.ok || !isJsonRecord(parsed.value)) {
+        return [];
+    }
+    const config = parsed.value;
+    const expected = expectedRenovateKeys(minReleaseAgeDays);
+    const findings = [];
+    for (const check of [
+        checkRenovateRange(path, config, expected),
+        checkRenovateExtends(path, config),
+        checkRenovateOsv(path, config),
+        checkRenovateS9(path, config),
+    ]) {
+        if (check !== undefined) {
+            findings.push(check);
+        }
+    }
+    return findings;
+}

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

@@ -0,0 +1,20 @@
+import { type Fs, type Net, type Result } from "../../kernel/index.ts";
+import type { RegistrySnapshot, RegistryVersion } from "./index.ts";
+import { type DepLagParams, type SemVer } from "./stable.ts";
+export interface ResolveOptions {
+    readonly pinned?: string;
+    readonly params?: Partial<DepLagParams>;
+    readonly satisfiesRuntime?: (version: RegistryVersion) => boolean;
+    readonly net?: Net;
+    readonly fs?: Fs;
+}
+export declare function snapshotAdvisoriesFor(snapshot: RegistrySnapshot, name: string, version: string): ReadonlyArray<string>;
+export interface EligibleVersion {
+    readonly version: string;
+    readonly parsed: SemVer;
+    readonly publishedMs: number;
+    readonly viaSecurityExemption: boolean;
+}
+export declare function eligibleStableVersions(snapshot: RegistrySnapshot, name: string, options?: ResolveOptions): ReadonlyArray<EligibleVersion>;
+export declare function selectLatestStable(snapshot: RegistrySnapshot, name: string, options?: ResolveOptions): Result<EligibleVersion>;
+export declare function lagDaysFor(snapshot: RegistrySnapshot, name: string, pinned: string, options?: ResolveOptions): number | undefined;

package/dist/features/deps/selection.js

@@ -0,0 +1,150 @@
+// SPEC §4.8.3: "latest stable" selection with the S9 security exemption.
+// Eligibility is pure over the §7.12 snapshot; ages measure from the
+// snapshot's fetchedAt ("as of fetchedAt", §4.8.4), never the wall clock.
+import { err, makeError, ok, } from "../../kernel/index.js";
+import { compareNpmVersions, DEFAULT_DEP_LAG_PARAMS, MS_PER_DAY, parseNpmVersion, } from "./stable.js";
+function withDefaults(params) {
+    return {
+        lagDays: params?.lagDays ?? DEFAULT_DEP_LAG_PARAMS.lagDays,
+        majorLagDays: params?.majorLagDays ?? DEFAULT_DEP_LAG_PARAMS.majorLagDays,
+        minReleaseAgeDays: params?.minReleaseAgeDays ?? DEFAULT_DEP_LAG_PARAMS.minReleaseAgeDays,
+    };
+}
+// SPEC §7.12: advisories are keyed name@version holding OSV ids.
+export function snapshotAdvisoriesFor(snapshot, name, version) {
+    const found = snapshot.advisories[`${name}@${version}`];
+    return found ?? [];
+}
+function ageDays(published, nowMs) {
+    const publishedMs = Date.parse(published);
+    if (Number.isNaN(publishedMs)) {
+        return undefined;
+    }
+    return (nowMs - publishedMs) / MS_PER_DAY;
+}
+// SPEC §11 S9: a version younger than minReleaseAgeDays is eligible when the
+// pinned version has an advisory that this version fixes — newer, same major,
+// and free of every advisory affecting the pinned version.
+function securityExempt(snapshot, name, pinned, pinnedParsed, candidate, candidateParsed) {
+    if (compareNpmVersions(candidateParsed, pinnedParsed) <= 0 ||
+        candidateParsed.major !== pinnedParsed.major) {
+        return false;
+    }
+    const pinnedAdvisories = snapshotAdvisoriesFor(snapshot, name, pinned);
+    if (pinnedAdvisories.length === 0) {
+        return false;
+    }
+    const candidateAdvisories = snapshotAdvisoriesFor(snapshot, name, candidate);
+    return candidateAdvisories.every((advisory) => !pinnedAdvisories.includes(advisory));
+}
+function eligibleVersion(input, version) {
+    const parsed = parseNpmVersion(version);
+    const detail = input.snapshot.packages[input.name]?.versions[version];
+    if (parsed === undefined || detail === undefined) {
+        return undefined;
+    }
+    // SPEC §4.8.3: prereleases, deprecations and yanked versions never
+    // qualify; EC-12 and EC-14 close over these branches.
+    if (parsed.prerelease !== undefined ||
+        detail.deprecated === true ||
+        detail.yanked === true) {
+        return undefined;
+    }
+    const days = ageDays(detail.published, input.nowMs);
+    if (days === undefined || days < 0) {
+        return undefined;
+    }
+    if (snapshotAdvisoriesFor(input.snapshot, input.name, version).length > 0) {
+        return undefined;
+    }
+    if (input.satisfiesRuntime !== undefined && !input.satisfiesRuntime(detail)) {
+        return undefined;
+    }
+    if (days >= input.params.minReleaseAgeDays) {
+        return {
+            version,
+            parsed,
+            publishedMs: Date.parse(detail.published),
+            viaSecurityExemption: false,
+        };
+    }
+    const exempt = input.pinned !== undefined &&
+        input.pinnedParsed !== undefined &&
+        securityExempt(input.snapshot, input.name, input.pinned, input.pinnedParsed, version, parsed);
+    if (!exempt) {
+        return undefined;
+    }
+    return {
+        version,
+        parsed,
+        publishedMs: Date.parse(detail.published),
+        viaSecurityExemption: true,
+    };
+}
+export function eligibleStableVersions(snapshot, name, options = {}) {
+    const nowMs = Date.parse(snapshot.fetchedAt);
+    if (Number.isNaN(nowMs) || snapshot.packages[name] === undefined) {
+        return [];
+    }
+    const entry = {
+        snapshot,
+        name,
+        params: withDefaults(options.params),
+        nowMs,
+        pinned: options.pinned,
+        pinnedParsed: options.pinned === undefined
+            ? undefined
+            : parseNpmVersion(options.pinned),
+        satisfiesRuntime: options.satisfiesRuntime,
+    };
+    const eligible = [];
+    for (const version of Object.keys(snapshot.packages[name]?.versions ?? {}).sort()) {
+        const candidate = eligibleVersion(entry, version);
+        if (candidate !== undefined) {
+            eligible.push(candidate);
+        }
+    }
+    return eligible;
+}
+// SPEC §4.8.3: latest stable is the maximum of the eligible set. An empty
+// eligible set is CDX-E401: no usable version in the snapshot.
+export function selectLatestStable(snapshot, name, options = {}) {
+    let best;
+    for (const candidate of eligibleStableVersions(snapshot, name, options)) {
+        if (best === undefined ||
+            compareNpmVersions(candidate.parsed, best.parsed) > 0) {
+            best = candidate;
+        }
+    }
+    if (best === undefined) {
+        return err(makeError("CDX-E401", `no eligible stable version for ${name} in the registry snapshot`, "Refresh the registry snapshot; if the package is unpublished, replace or remove the dependency."));
+    }
+    return ok(best);
+}
+// SPEC §4.8.5: lag is now minus the moment the oldest newer eligible version
+// became eligible (published plus minReleaseAgeDays).
+export function lagDaysFor(snapshot, name, pinned, options = {}) {
+    const params = withDefaults(options.params);
+    const nowMs = Date.parse(snapshot.fetchedAt);
+    if (Number.isNaN(nowMs)) {
+        return undefined;
+    }
+    const pinnedParsed = parseNpmVersion(pinned);
+    if (pinnedParsed === undefined) {
+        return undefined;
+    }
+    let oldestEligibleMs;
+    for (const candidate of eligibleStableVersions(snapshot, name, options)) {
+        if (compareNpmVersions(candidate.parsed, pinnedParsed) <= 0) {
+            continue;
+        }
+        const eligibleMs = candidate.publishedMs + params.minReleaseAgeDays * MS_PER_DAY;
+        if (oldestEligibleMs === undefined || eligibleMs < oldestEligibleMs) {
+            oldestEligibleMs = eligibleMs;
+        }
+    }
+    if (oldestEligibleMs === undefined) {
+        return 0;
+    }
+    return Math.max(0, (nowMs - oldestEligibleMs) / MS_PER_DAY);
+}

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

@@ -0,0 +1,16 @@
+import type { Finding } from "../engine/index.ts";
+import type { EvalDep } from "./eval.ts";
+import type { RegistrySnapshot } from "./index.ts";
+import type { DepLagParams } from "./stable.ts";
+export interface PinnedCheckInput {
+    readonly snapshot: RegistrySnapshot;
+    readonly params: DepLagParams;
+    readonly allow: ReadonlyArray<string>;
+    readonly path: string;
+    readonly dep: EvalDep;
+    readonly unpublished: ReadonlyArray<string>;
+}
+export declare function checkPinnedVerdicts(input: PinnedCheckInput, pinned: string, notes: Array<string>): ReadonlyArray<Finding>;
+export declare function minimalFixedVersion(snapshot: RegistrySnapshot, name: string, pinned: string, params: DepLagParams): string | undefined;
+export declare function pinnedOrUnversionedNote(path: string, name: string): string;
+export declare function snapshotForm(range: string): "pinned" | "unversioned" | "ranged";