codictator 0.0.0 → 0.1.2

package/dist/features/deps/dependabot.js

@@ -0,0 +1,154 @@
+function flushScanEntry(scan) {
+    if (scan.current !== null && scan.current.ecosystem !== undefined) {
+        scan.entries.push({
+            packageEcosystem: scan.current.ecosystem,
+            directory: scan.current.directory ?? "/",
+            scheduleInterval: scan.current.interval,
+            cooldownDays: scan.current.cooldown,
+            versioningStrategy: scan.current.strategy,
+        });
+    }
+    scan.current = null;
+    scan.inSchedule = false;
+    scan.inCooldown = false;
+    scan.inAllow = false;
+}
+function unquote(value) {
+    return value.replace(/^["']|["']$/g, "");
+}
+function scanUpdateKey(scan, key, stripped) {
+    if (key === "schedule") {
+        scan.inSchedule = true;
+        scan.inCooldown = false;
+        scan.inAllow = false;
+        return;
+    }
+    if (key === "cooldown") {
+        scan.inCooldown = true;
+        scan.inSchedule = false;
+        scan.inAllow = false;
+        return;
+    }
+    if (key === "allow" || key === "ignore") {
+        scan.inAllow = true;
+        scan.inSchedule = false;
+        scan.inCooldown = false;
+        return;
+    }
+    if (key !== undefined && !stripped.startsWith("      ")) {
+        scan.inSchedule = false;
+        scan.inCooldown = false;
+        scan.inAllow = false;
+    }
+}
+function scanUpdateValue(scan, key, value) {
+    if (scan.current === null || key === undefined) {
+        return;
+    }
+    if (key === "directory" || key === "directories") {
+        scan.current.directory = value;
+    }
+    else if (scan.inSchedule && key === "interval") {
+        scan.current.interval = value;
+    }
+    else if (scan.inCooldown &&
+        (key === "default-days" || key === "default_days")) {
+        scan.current.cooldown = value;
+    }
+    else if (key === "versioning-strategy") {
+        scan.current.strategy = value;
+    }
+}
+function scanUpdateLine(scan, line) {
+    const stripped = line.split("#")[0] ?? "";
+    const trimmed = stripped.trim();
+    if (trimmed === "") {
+        return;
+    }
+    if (/^-\s+package-ecosystem\s*:/.test(trimmed)) {
+        flushScanEntry(scan);
+        scan.current = {
+            ecosystem: unquote(trimmed.slice(trimmed.indexOf(":") + 1).trim()),
+        };
+        return;
+    }
+    if (scan.current === null) {
+        return;
+    }
+    const key = /^\s{4,}([a-z-]+)\s*:/.exec(stripped)?.[1];
+    scanUpdateKey(scan, key, stripped);
+    if (scan.inAllow) {
+        return;
+    }
+    const value = trimmed.includes(":")
+        ? unquote(trimmed.slice(trimmed.indexOf(":") + 1).trim())
+        : "";
+    scanUpdateValue(scan, key, value);
+}
+// Dependabot owned keys live under version updates entries; this reads only
+// the owned subset with a line scan, never a general YAML parse.
+export function parseDependabotUpdates(text) {
+    const scan = {
+        entries: [],
+        current: null,
+        inSchedule: false,
+        inCooldown: false,
+        inAllow: false,
+    };
+    for (const line of text.split("\n")) {
+        scanUpdateLine(scan, line);
+    }
+    flushScanEntry(scan);
+    return scan.entries;
+}
+function checkDependabotEntry(path, ecosystem, entry, minReleaseAgeDays) {
+    if (entry === undefined) {
+        return [
+            {
+                ruleId: "core/dep-latest-stable",
+                path,
+                message: `${path} has no updates entry for ${ecosystem}`,
+                remediation: `Regenerate the bot config with an entry for ${ecosystem}.`,
+            },
+        ];
+    }
+    const findings = [];
+    if (entry.scheduleInterval !== "daily") {
+        findings.push({
+            ruleId: "core/dep-latest-stable",
+            path,
+            message: `${path} schedules ${ecosystem} ${entry.scheduleInterval ?? "never"} instead of daily`,
+            remediation: `Regenerate the bot config with a daily schedule.`,
+        });
+    }
+    if (entry.cooldownDays !== String(minReleaseAgeDays)) {
+        findings.push({
+            ruleId: "core/dep-latest-stable",
+            path,
+            message: `${path} cools ${ecosystem} down ${entry.cooldownDays ?? "never"} instead of ${String(minReleaseAgeDays)} days`,
+            remediation: `Regenerate the bot config with the owned cooldown.`,
+        });
+    }
+    if (ecosystem === "npm" && entry.versioningStrategy !== "increase") {
+        findings.push({
+            ruleId: "core/dep-exact-pin",
+            path,
+            message: `${path} npm entry lacks versioning-strategy increase`,
+            remediation: `Regenerate the bot config with the npm increase strategy.`,
+        });
+    }
+    return findings;
+}
+// SPEC §4.8.6: one updates entry per detected ecosystem plus github-actions,
+// daily schedule, cooldown of <n> days, npm increase strategy.
+export function checkDependabotOwnedKeys(path, text, ecosystems, minReleaseAgeDays) {
+    const entries = parseDependabotUpdates(text);
+    const findings = [];
+    for (const ecosystem of [...ecosystems, "github-actions"]) {
+        const entry = entries.find((candidate) => candidate.packageEcosystem === ecosystem);
+        for (const finding of checkDependabotEntry(path, ecosystem, entry, minReleaseAgeDays)) {
+            findings.push(finding);
+        }
+    }
+    return findings;
+}

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

@@ -0,0 +1,41 @@
+import type { Finding } from "../engine/index.ts";
+import type { RegistrySnapshot } from "./index.ts";
+import type { NpmDepKind } from "./npm.ts";
+import type { DepLagParams } from "./stable.ts";
+export interface EvalDep {
+    readonly name: string;
+    readonly range: string;
+    readonly kind: NpmDepKind;
+}
+export interface EvalManifest {
+    readonly path: string;
+    readonly dependencies: ReadonlyArray<EvalDep>;
+}
+export interface DepEvalInput {
+    readonly manifests: ReadonlyArray<EvalManifest>;
+    readonly snapshot?: RegistrySnapshot;
+    readonly now: string;
+    readonly params?: Partial<DepLagParams>;
+    readonly licenseAllow?: ReadonlyArray<string>;
+    readonly lockfiles?: Readonly<Record<string, string | null>>;
+    readonly npmrc?: {
+        readonly path: string;
+        readonly text: string;
+    };
+    readonly allowedRegistryHosts?: ReadonlyArray<string>;
+    readonly newDeps?: ReadonlyArray<string>;
+    readonly addedReasons?: Readonly<Record<string, boolean>>;
+    readonly unpublished?: ReadonlyArray<string>;
+    readonly saveExactRequired?: boolean;
+    readonly platformCaps?: ReadonlyArray<string>;
+}
+export interface DepEvaluation {
+    readonly findings: ReadonlyArray<Finding>;
+    readonly notes: ReadonlyArray<string>;
+}
+export interface UniqueDep {
+    readonly path: string;
+    readonly dep: EvalDep;
+}
+export declare function uniqueDeps(manifests: ReadonlyArray<EvalManifest>): ReadonlyArray<UniqueDep>;
+export declare function pinFinding(path: string, name: string, range: string): Finding;

package/dist/features/deps/eval.js

@@ -0,0 +1,24 @@
+// SPEC §4.8.8 EC-10: a workspace monorepo judges each manifest separately
+// but counts a package once.
+export function uniqueDeps(manifests) {
+    const seen = new Set();
+    const out = [];
+    for (const manifest of manifests) {
+        for (const dep of manifest.dependencies) {
+            if (seen.has(dep.name)) {
+                continue;
+            }
+            seen.add(dep.name);
+            out.push({ path: manifest.path, dep });
+        }
+    }
+    return out;
+}
+export function pinFinding(path, name, range) {
+    return {
+        ruleId: "core/dep-exact-pin",
+        path,
+        message: `${name}@${range} in ${path} is not an exact pin`,
+        remediation: `Pin ${name} to an exact version in ${path}.`,
+    };
+}

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

@@ -0,0 +1,4 @@
+export declare function isJsonRecord(value: unknown): value is Record<string, unknown>;
+export declare function field(record: Readonly<Record<string, unknown>>, name: string): unknown;
+export declare function stringField(record: Readonly<Record<string, unknown>>, name: string): string | undefined;
+export declare function recordField(record: Readonly<Record<string, unknown>>, name: string): Record<string, unknown> | undefined;

package/dist/features/deps/fields.js

@@ -0,0 +1,18 @@
+// SPEC §4.1.2: JSON narrowing for the npm driver and its clients. Bracket
+// access through a variable keeps noPropertyAccessFromIndexSignature
+// satisfied without tripping useLiteralKeys (packs/manifest narrows the
+// same way).
+export function isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function field(record, name) {
+    return record[name];
+}
+export function stringField(record, name) {
+    const value = record[name];
+    return typeof value === "string" ? value : undefined;
+}
+export function recordField(record, name) {
+    const value = record[name];
+    return isJsonRecord(value) ? value : undefined;
+}

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

@@ -0,0 +1,67 @@
+import type { Result } from "../../kernel/index.ts";
+import type { NpmDepKind } from "./npm.ts";
+import type { ResolveOptions } from "./selection.ts";
+export interface ManifestDependency {
+    readonly name: string;
+    readonly range: string;
+    readonly kind?: NpmDepKind;
+}
+export interface Manifest {
+    readonly ecosystem: string;
+    readonly path: string;
+    readonly dependencies: ReadonlyArray<ManifestDependency>;
+}
+export interface RegistryVersion {
+    readonly published: string;
+    readonly deprecated?: boolean;
+    readonly yanked?: boolean;
+    readonly license?: string;
+    readonly engines?: string;
+}
+export interface RegistrySnapshot {
+    readonly version: 1;
+    readonly ecosystem: string;
+    readonly fetchedAt: string;
+    readonly packages: Readonly<Record<string, {
+        readonly versions: Readonly<Record<string, RegistryVersion>>;
+    }>>;
+    readonly advisories: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+export interface FileEdit {
+    readonly path: string;
+    readonly old: string;
+    readonly replacement: string;
+}
+export interface Driver {
+    readonly ecosystem: string;
+    readonly detect: (repo: string) => boolean;
+    readonly readManifests: (repo: string) => Array<Manifest>;
+    readonly registry: RegistryClient;
+    readonly edit: (upgrade: Upgrade) => Array<FileEdit>;
+}
+export interface Upgrade {
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+}
+export interface RegistryClient {
+    readonly snapshot: (names: ReadonlyArray<string>) => Promise<Result<RegistrySnapshot>>;
+}
+export declare function resolveLatest(snapshot: RegistrySnapshot, name: string, options?: ResolveOptions): Result<string>;
+export { detectUpgradeBots, isDependabotFile, isRenovateFile, type UpgradeBot, upgradeBranchName, } from "./bots.ts";
+export { capabilityOf, DEFAULT_LICENSE_ALLOW, platformCapabilityCover, } from "./capabilities.ts";
+export { checkDeps, type DepCheckContext } from "./check.ts";
+export { checkDependabotOwnedKeys, type DependabotUpdateEntry, parseDependabotUpdates, } from "./dependabot.ts";
+export { type DepEvalInput, type DepEvaluation, type EvalDep, type EvalManifest, pinFinding, type UniqueDep, uniqueDeps, } from "./eval.ts";
+export { lockfileMismatches, type NpmLockfile, parsePackageLock, } from "./lockfile.ts";
+export { classifyNpmRange, isExactNpmPin, isExactToolchainPin, isUnversionedNpmSource, NPM_ECOSYSTEM, type NpmDependency, type NpmDepKind, type NpmManifest, type NpmPinForm, parsePackageJson, parseToolchainFiles, } from "./npm.ts";
+export { NPM_PUBLIC_REGISTRY_HOST, type NpmRegistryRef, type NpmrcConfig, parseNpmrc, privateRegistryHosts, } from "./npmrc.ts";
+export { fetchOsvAdvisoryIds, fetchOsvRanges, isRetryableStatus, narrowOsvRanges, OSV_BASE_URL, OSV_TIMEOUT_MS, type OsvEvent, type OsvFetchOptions, type OsvRange, osvAdvisoryAffects, osvRangeAffectsVersion, retryDelaysMs, } from "./osv.ts";
+export { buildSnapshot, fetchNpmPackument, hashSnapshot, NPM_REGISTRY_BASE_URL, type NpmDocVersion, type NpmPackument, REGISTRY_TIMEOUT_MS, type RegistryFetchOptions, SNAPSHOT_CACHE_PATH, SNAPSHOT_MAX_AGE_MS, type SnapshotFreshness, snapshotAsOf, snapshotFreshness, } from "./registry.ts";
+export { checkRenovateOwnedKeys, expectedRenovateKeys, parseRenovateText, type RenovateOwnedKeys, } from "./renovate.ts";
+export { type EligibleVersion, eligibleStableVersions, lagDaysFor, type ResolveOptions, selectLatestStable, snapshotAdvisoriesFor, } from "./selection.ts";
+export { checkPinnedVerdicts, minimalFixedVersion, type PinnedCheckInput, pinnedOrUnversionedNote, snapshotForm, } from "./snapshot-verdicts.ts";
+export { compareNpmVersions, DEFAULT_DEP_LAG_PARAMS, DEFAULT_LAG_DAYS, DEFAULT_MAJOR_LAG_DAYS, DEFAULT_MIN_RELEASE_AGE_DAYS, type DepLagParams, isNpmPrerelease, MS_PER_DAY, parseNpmVersion, type SemVer, } from "./stable.ts";
+export { checkRemediationStepSize, DEFAULT_STEP_SIZE, type StepSizeParams, } from "./step-size.ts";
+export { planUpgradePr, runUpgradePr, type UpgradeFile, type UpgradeHost, type UpgradePrInput, type UpgradePrPlan, upgradeCommitSubject, upgradeHistoryEntry, } from "./upgrade.ts";
+export { depErrorFinding, evaluateDepVerdicts, makeDepError, manifestToEval, } from "./verdicts.ts";

package/dist/features/deps/index.js

@@ -0,0 +1,27 @@
+import { selectLatestStable } from "./selection.js";
+// SPEC §4.8.3: latest-stable resolution against the snapshot. Ages measure
+// from fetchedAt, so repeated runs observe the same instant (SPEC §10.3).
+export function resolveLatest(snapshot, name, options = {}) {
+    const selected = selectLatestStable(snapshot, name, options);
+    if (!selected.ok) {
+        return selected;
+    }
+    return { ok: true, value: selected.value.version };
+}
+export { detectUpgradeBots, isDependabotFile, isRenovateFile, upgradeBranchName, } from "./bots.js";
+export { capabilityOf, DEFAULT_LICENSE_ALLOW, platformCapabilityCover, } from "./capabilities.js";
+export { checkDeps } from "./check.js";
+export { checkDependabotOwnedKeys, parseDependabotUpdates, } from "./dependabot.js";
+export { pinFinding, uniqueDeps, } from "./eval.js";
+export { lockfileMismatches, parsePackageLock, } from "./lockfile.js";
+export { classifyNpmRange, isExactNpmPin, isExactToolchainPin, isUnversionedNpmSource, NPM_ECOSYSTEM, parsePackageJson, parseToolchainFiles, } from "./npm.js";
+export { NPM_PUBLIC_REGISTRY_HOST, parseNpmrc, privateRegistryHosts, } from "./npmrc.js";
+export { fetchOsvAdvisoryIds, fetchOsvRanges, isRetryableStatus, narrowOsvRanges, OSV_BASE_URL, OSV_TIMEOUT_MS, osvAdvisoryAffects, osvRangeAffectsVersion, retryDelaysMs, } from "./osv.js";
+export { buildSnapshot, fetchNpmPackument, hashSnapshot, NPM_REGISTRY_BASE_URL, REGISTRY_TIMEOUT_MS, SNAPSHOT_CACHE_PATH, SNAPSHOT_MAX_AGE_MS, snapshotAsOf, snapshotFreshness, } from "./registry.js";
+export { checkRenovateOwnedKeys, expectedRenovateKeys, parseRenovateText, } from "./renovate.js";
+export { eligibleStableVersions, lagDaysFor, selectLatestStable, snapshotAdvisoriesFor, } from "./selection.js";
+export { checkPinnedVerdicts, minimalFixedVersion, pinnedOrUnversionedNote, snapshotForm, } from "./snapshot-verdicts.js";
+export { compareNpmVersions, DEFAULT_DEP_LAG_PARAMS, DEFAULT_LAG_DAYS, DEFAULT_MAJOR_LAG_DAYS, DEFAULT_MIN_RELEASE_AGE_DAYS, isNpmPrerelease, MS_PER_DAY, parseNpmVersion, } from "./stable.js";
+export { checkRemediationStepSize, DEFAULT_STEP_SIZE, } from "./step-size.js";
+export { planUpgradePr, runUpgradePr, upgradeCommitSubject, upgradeHistoryEntry, } from "./upgrade.js";
+export { depErrorFinding, evaluateDepVerdicts, makeDepError, manifestToEval, } from "./verdicts.js";

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

@@ -0,0 +1,8 @@
+import { type Result } from "../../kernel/index.ts";
+import type { NpmDependency } from "./npm.ts";
+export interface NpmLockfile {
+    readonly lockfileVersion: number;
+    readonly pinned: Readonly<Record<string, string>>;
+}
+export declare function parsePackageLock(text: string): Result<NpmLockfile>;
+export declare function lockfileMismatches(dependencies: ReadonlyArray<NpmDependency>, lock: NpmLockfile): ReadonlyArray<string>;

package/dist/features/deps/lockfile.js

@@ -0,0 +1,87 @@
+// SPEC §6.1: package-lock.json (v3); pnpm/yarn frozen-lockfile commands run
+// through the external contract in a later phase.
+import { err, makeError, ok, parseJson, } from "../../kernel/index.js";
+import { field, isJsonRecord, recordField, stringField } from "./fields.js";
+import { isExactNpmPin, isUnversionedNpmSource } from "./npm.js";
+function stringTable(value) {
+    if (!isJsonRecord(value)) {
+        return {};
+    }
+    const table = {};
+    for (const key of Object.keys(value).sort()) {
+        const entry = value[key];
+        if (typeof entry === "string") {
+            table[key] = entry;
+        }
+    }
+    return table;
+}
+function collectRootPins(packages, pinned) {
+    const rootEntry = recordField(packages, "");
+    if (rootEntry === undefined) {
+        return;
+    }
+    for (const key of [
+        "dependencies",
+        "devDependencies",
+        "optionalDependencies",
+    ]) {
+        for (const [name, range] of Object.entries(stringTable(field(rootEntry, key)))) {
+            pinned[name] = range;
+        }
+    }
+}
+function collectNestedPins(packages, pinned) {
+    for (const [path, entry] of Object.entries(packages)) {
+        if (!path.startsWith("node_modules/") || !isJsonRecord(entry)) {
+            continue;
+        }
+        const name = path.slice("node_modules/".length);
+        const entryVersion = stringField(entry, "version");
+        if (entryVersion !== undefined && pinned[name] === undefined) {
+            pinned[name] = entryVersion;
+        }
+    }
+}
+export function parsePackageLock(text) {
+    const parsed = parseJson(text);
+    if (!parsed.ok) {
+        return err(parsed.error);
+    }
+    if (!isJsonRecord(parsed.value)) {
+        return err(makeError("CDX-E101", "package-lock.json must hold a JSON object at its root", "Regenerate the lockfile with the ecosystem tool."));
+    }
+    const root = parsed.value;
+    const packages = recordField(root, "packages");
+    if (packages === undefined) {
+        return err(makeError("CDX-E101", "package-lock.json has no packages table", "Regenerate the lockfile with the ecosystem tool."));
+    }
+    const pinned = {};
+    collectRootPins(packages, pinned);
+    collectNestedPins(packages, pinned);
+    const version = field(root, "lockfileVersion");
+    return ok({
+        lockfileVersion: typeof version === "number" ? version : 0,
+        pinned,
+    });
+}
+// SPEC §4.8.5 core/dep-lockfile: every manifest pin resolves to the same
+// version in the lockfile; ranges can never be in sync.
+export function lockfileMismatches(dependencies, lock) {
+    const mismatched = [];
+    for (const dep of dependencies) {
+        if (dep.kind === "peer" || isUnversionedNpmSource(dep.range)) {
+            continue;
+        }
+        if (!isExactNpmPin(dep.range)) {
+            mismatched.push(dep.name);
+            continue;
+        }
+        const locked = lock.pinned[dep.name];
+        const wanted = dep.range.replace(/^v/, "");
+        if (locked === undefined || locked.replace(/^v/, "") !== wanted) {
+            mismatched.push(dep.name);
+        }
+    }
+    return mismatched.sort();
+}

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

@@ -0,0 +1,22 @@
+import { type Result } from "../../kernel/index.ts";
+export declare const NPM_ECOSYSTEM = "npm";
+export type NpmDepKind = "prod" | "dev" | "peer" | "toolchain";
+export interface NpmDependency {
+    readonly name: string;
+    readonly range: string;
+    readonly kind: NpmDepKind;
+}
+export type NpmPinForm = "exact" | "range" | "tag" | "alias-exact" | "alias-range" | "workspace-exact" | "workspace-range" | "file" | "link" | "git-sha" | "git-unpinned" | "tarball-url";
+export declare function classifyNpmRange(range: string): NpmPinForm;
+export declare function isExactNpmPin(range: string): boolean;
+export declare function isUnversionedNpmSource(range: string): boolean;
+export interface NpmManifest {
+    readonly dependencies: ReadonlyArray<NpmDependency>;
+    readonly engines: Readonly<Record<string, string>>;
+    readonly peerRanges: Readonly<Record<string, string>>;
+    readonly packageManager: string | undefined;
+    readonly workspaces: ReadonlyArray<string>;
+}
+export declare function parsePackageJson(text: string): Result<NpmManifest>;
+export declare function parseToolchainFiles(nvmrc: string | undefined, packageManager: string | undefined): ReadonlyArray<NpmDependency>;
+export declare function isExactToolchainPin(range: string): boolean;

package/dist/features/deps/npm.js

@@ -0,0 +1,172 @@
+// SPEC §6.1 driver `npm`: manifest parsing, exact-pin forms and toolchain
+// files. Lockfile sync lives in lockfile.ts and the owned `.npmrc` entry in
+// npmrc.ts. Everything here is pure over caller-supplied text; ports stay at
+// the enforcer layer (SPEC §3.3), so a Driver instance that could do I/O
+// waits for gate-closure wiring with ports.
+import { err, makeError, ok, parseJson, } from "../../kernel/index.js";
+import { field, isJsonRecord } from "./fields.js";
+export const NPM_ECOSYSTEM = "npm";
+const EXACT_PIN = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+function stripWorkspacePrefix(range) {
+    if (range === "workspace:*") {
+        return "*";
+    }
+    if (range.startsWith("workspace:")) {
+        return range.slice("workspace:".length);
+    }
+    return undefined;
+}
+export function classifyNpmRange(range) {
+    const workspace = stripWorkspacePrefix(range);
+    if (workspace !== undefined) {
+        return EXACT_PIN.test(workspace) ? "workspace-exact" : "workspace-range";
+    }
+    if (range.startsWith("file:")) {
+        return "file";
+    }
+    if (range.startsWith("link:")) {
+        return "link";
+    }
+    if (range.startsWith("npm:")) {
+        const at = range.lastIndexOf("@");
+        const version = at < 4 ? "" : range.slice(at + 1);
+        return EXACT_PIN.test(version) ? "alias-exact" : "alias-range";
+    }
+    if (range.startsWith("git+") ||
+        range.startsWith("git://") ||
+        range.startsWith("github:")) {
+        const hash = range.split("#")[1] ?? "";
+        return FULL_SHA.test(hash) ? "git-sha" : "git-unpinned";
+    }
+    if (range.startsWith("http://") || range.startsWith("https://")) {
+        return "tarball-url";
+    }
+    if (EXACT_PIN.test(range)) {
+        return "exact";
+    }
+    if (range === "*" ||
+        range === "latest" ||
+        range === "" ||
+        /^[a-zA-Z][0-9A-Za-z.-]*$/.test(range)) {
+        return "tag";
+    }
+    return "range";
+}
+// SPEC §4.8.5: ranges, tags, *, latest and unpinned git/alias/workspace
+// forms block core/dep-exact-pin. In-repo file:/link: forms, full-SHA git
+// URLs and tarball URLs are pinned content; EC-7 allows the SHA form.
+export function isExactNpmPin(range) {
+    const form = classifyNpmRange(range);
+    return (form === "exact" ||
+        form === "alias-exact" ||
+        form === "workspace-exact" ||
+        form === "file" ||
+        form === "link" ||
+        form === "git-sha" ||
+        form === "tarball-url");
+}
+// SPEC §4.8.5 EC-7: versionless sources skip latest-stable, reported as
+// "unversioned source".
+export function isUnversionedNpmSource(range) {
+    const form = classifyNpmRange(range);
+    return (form === "file" ||
+        form === "link" ||
+        form === "git-sha" ||
+        form === "tarball-url");
+}
+function stringTable(value) {
+    if (!isJsonRecord(value)) {
+        return {};
+    }
+    const table = {};
+    for (const key of Object.keys(value).sort()) {
+        const entry = value[key];
+        if (typeof entry === "string") {
+            table[key] = entry;
+        }
+    }
+    return table;
+}
+function collectManifestDeps(root) {
+    const dependencies = [];
+    const sections = [
+        ["dependencies", "prod"],
+        ["devDependencies", "dev"],
+        ["optionalDependencies", "prod"],
+    ];
+    for (const [section, kind] of sections) {
+        for (const [name, range] of Object.entries(stringTable(field(root, section)))) {
+            dependencies.push({ name, range, kind });
+        }
+    }
+    dependencies.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    return dependencies;
+}
+function collectWorkspaces(root) {
+    const raw = field(root, "workspaces");
+    const workspaces = [];
+    const pushStrings = (value) => {
+        if (!Array.isArray(value)) {
+            return;
+        }
+        for (const entry of value) {
+            if (typeof entry === "string") {
+                workspaces.push(entry);
+            }
+        }
+    };
+    if (isJsonRecord(raw)) {
+        pushStrings(field(raw, "packages"));
+    }
+    else {
+        pushStrings(raw);
+    }
+    return workspaces;
+}
+// SPEC §6.1: dependencies, devDependencies, optionalDependencies and
+// overrides supply pins; peerDependencies and engines are compatibility
+// declarations (EC-6), never pins.
+export function parsePackageJson(text) {
+    const parsed = parseJson(text);
+    if (!parsed.ok) {
+        return err(parsed.error);
+    }
+    if (!isJsonRecord(parsed.value)) {
+        return err(makeError("CDX-E101", "package.json must hold a JSON object at its root", "Point the manifest at the package root object."));
+    }
+    const root = parsed.value;
+    const rawManager = field(root, "packageManager");
+    return ok({
+        dependencies: collectManifestDeps(root),
+        engines: stringTable(field(root, "engines")),
+        peerRanges: stringTable(field(root, "peerDependencies")),
+        packageManager: typeof rawManager === "string" ? rawManager : undefined,
+        workspaces: collectWorkspaces(root),
+    });
+}
+// SPEC §6.1 toolchain: .nvmrc exact, packageManager exact (npm@x.y.z).
+export function parseToolchainFiles(nvmrc, packageManager) {
+    const toolchains = [];
+    if (nvmrc !== undefined) {
+        toolchains.push({
+            name: "node",
+            range: nvmrc.trim().replace(/^v/, ""),
+            kind: "toolchain",
+        });
+    }
+    if (packageManager !== undefined) {
+        toolchains.push({
+            name: "packageManager",
+            range: packageManager.trim(),
+            kind: "toolchain",
+        });
+    }
+    return toolchains;
+}
+export function isExactToolchainPin(range) {
+    if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(range)) {
+        return true;
+    }
+    return /^[a-zA-Z][0-9A-Za-z_-]*@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(range);
+}

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

@@ -0,0 +1,12 @@
+export declare const NPM_PUBLIC_REGISTRY_HOST = "registry.npmjs.org";
+export interface NpmRegistryRef {
+    readonly scope: string | undefined;
+    readonly host: string;
+    readonly url: string;
+}
+export interface NpmrcConfig {
+    readonly saveExact: boolean | undefined;
+    readonly registries: ReadonlyArray<NpmRegistryRef>;
+}
+export declare function parseNpmrc(text: string): NpmrcConfig;
+export declare function privateRegistryHosts(config: NpmrcConfig): ReadonlyArray<string>;