@vola-trebla/croak 0.1.0 → 0.1.1

package/dist/install/lockfile.js

@@ -12,23 +12,19 @@ const asString = (value) => typeof value === "string" ? value : undefined;
 const asStrings = (value) => Array.isArray(value)
     ? value.filter((v) => typeof v === "string")
     : [];
-/** npm's rule: refused by `!value`; if any value is listed without `!`, it must be one of them. */
 function accepts(list, value) {
     if (list.includes(`!${value}`))
         return false;
     const allowed = list.filter((v) => !v.startsWith("!"));
     return allowed.length === 0 || allowed.includes(value);
 }
-/** Whether npm would install this entry on the platform (platform packages for other systems are skipped). */
 export function installsOn(entry, platform) {
     return accepts(entry.os, platform.os) && accepts(entry.cpu, platform.cpu);
 }
-/** `node_modules/a/node_modules/@s/b` → `@s/b`. */
 function nameFromPath(path) {
     const index = path.lastIndexOf("node_modules/");
     return index === -1 ? path : path.slice(index + "node_modules/".length);
 }
-/** Parses an npm lockfile (v2 or v3). Lockfile v1 has no `packages` map and is rejected. */
 export function parseLockfile(text) {
     let data;
     try {
@@ -45,7 +41,6 @@ export function parseLockfile(text) {
             return [];
         if (!isRecord(raw))
             throw new LockfileError(`entry ${path} is not an object`);
-        // Without a version croak cannot look the package up; npm always writes one.
         if (raw.link !== true && typeof raw.version !== "string")
             throw new LockfileError(`entry ${path} has no version`);
         return [
@@ -56,8 +51,6 @@ export function parseLockfile(text) {
                 resolved: asString(raw.resolved),
                 integrity: asString(raw.integrity),
                 hasInstallScript: raw.hasInstallScript === true,
-                // A key outside node_modules is a local folder npm links (a
-                // workspace member), never a download, unless it claims a source.
                 link: raw.link === true ||
                     (!path.startsWith("node_modules/") &&
                         !path.includes("/node_modules/") &&

package/dist/install/metadata.js

@@ -4,7 +4,6 @@ const RECENT_DAYS = 7;
 const NEW_PACKAGE_DAYS = 30;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const normalize = (name) => name.toLowerCase().replace(/[-_.]/g, "");
-/** Optimal string alignment distance (Levenshtein plus adjacent transpositions), capped at `cap`. */
 function distance(a, b, cap = 2) {
     if (Math.abs(a.length - b.length) >= cap)
         return cap;
@@ -28,12 +27,6 @@ function distance(a, b, cap = 2) {
     }
     return Math.min(d[a.length][b.length] ?? cap, cap);
 }
-/**
- * Popular packages a name that npm does not have might have meant (M4): up to
- * three, nearest first, within two keystrokes or one separator. Only for
- * names that do not exist, where a suggestion cannot be the attack itself;
- * an existing look-alike is a finding instead (nearPopularName).
- */
 export function suggestNames(spec) {
     const at = spec.indexOf("@", 1);
     const name = (at === -1 ? spec : spec.slice(0, at)).toLowerCase();
@@ -48,20 +41,12 @@ export function suggestNames(spec) {
         .slice(0, 3)
         .map(({ popular }) => popular);
 }
-/** The popular package this unscoped name is one keystroke (or one separator) away from. */
 export function nearPopularName(name) {
     if (name.startsWith("@") || POPULAR.has(name) || name.length < 5)
         return undefined;
     return POPULAR_PACKAGES.find((popular) => popular.length >= 5 &&
         (normalize(popular) === normalize(name) || distance(popular, name) === 1));
 }
-/**
- * Registry signals for one new or changed version. Each signal alone is a
- * warning (D25), except a new publisher, which alone is context (D28); two
- * patterns block (D26): an install script with dropped
- * provenance or a new publisher (a hijacked maintainer account), and a
- * typo-squat name on a brand-new package.
- */
 export function metadataFindings(change, facts, now = new Date()) {
     const { entry } = change;
     const file = `${entry.name}@${entry.version ?? "?"}`;
@@ -79,21 +64,14 @@ export function metadataFindings(change, facts, now = new Date()) {
         now.getTime() - facts.created.getTime() < NEW_PACKAGE_DAYS * DAY_MS;
     const recent = facts.earlier.slice(0, 5);
     const provenanceDropped = !facts.hasProvenance && recent.some((v) => v.hasProvenance);
-    // With provenance, the publisher is a CI identity tied to the source repo;
-    // a different account name there is a pipeline change, not a new person.
     const newPublisher = !facts.hasProvenance &&
         facts.publisher !== undefined &&
         facts.earlier.length > 0 &&
         !facts.earlier.some((v) => v.publisher === facts.publisher);
-    // A new publisher only matters with install-time code that is new: the same
-    // install script as before (sqlite3's prebuild-install) runs files the
-    // content checks read anyway (D30).
     const { previous } = facts;
     const sameScript = previous !== undefined &&
         facts.installCommands !== "" &&
         previous.installCommands === facts.installCommands;
-    // The lockfile's hasInstallScript is the project's (or attacker's) word;
-    // the registry's manifest says it too, and either one counts.
     const runsAtInstall = entry.hasInstallScript || facts.installScripts.length > 0;
     const hijack = runsAtInstall && (provenanceDropped || (newPublisher && !sameScript));
     const recentRelease = facts.ageDays !== undefined && facts.ageDays < RECENT_DAYS;
@@ -107,10 +85,7 @@ export function metadataFindings(change, facts, now = new Date()) {
         findings.push(finding("install/provenance", hijack ? "block" : "warn", `has no provenance, although earlier versions were published with it${pattern}`));
     }
     if (newPublisher) {
-        findings.push(finding("install/publisher", 
-        // Alone it is context: maintainers rotate and orgs publish from
-        // service accounts (microsoft1es, GitHub Actions).
-        hijack ? "block" : runsAtInstall ? "warn" : "info", `was published by ${facts.publisher}, who did not publish the earlier versions${pattern}${!hijack && runsAtInstall && sameScript && previous !== undefined ? `; it runs the same install script as ${previous.version}` : ""}`));
+        findings.push(finding("install/publisher", hijack ? "block" : runsAtInstall ? "warn" : "info", `was published by ${facts.publisher}, who did not publish the earlier versions${pattern}${!hijack && runsAtInstall && sameScript && previous !== undefined ? `; it runs the same install script as ${previous.version}` : ""}`));
     }
     const lookalike = nearPopularName(entry.name);
     if (lookalike !== undefined) {
@@ -126,11 +101,6 @@ export function metadataFindings(change, facts, now = new Date()) {
         findings.push(finding("install/new-package", "warn", `is a brand-new package (created less than ${NEW_PACKAGE_DAYS} days ago)`));
     return findings;
 }
-/**
- * Dependencies this version adds compared with its previous version. A new
- * dependency is context; a new dependency that is itself a brand-new package
- * is how the 2026 axios release smuggled in its payload (D27), so it blocks.
- */
 export function addedDependencyFindings(change, facts, createdByName, now = new Date()) {
     const { previous } = facts;
     if (previous === undefined)

package/dist/install/plan.js

@@ -1,14 +1,4 @@
-/**
- * Same package only when it comes from the same place with the same hash: a
- * second lodash@4.17.21 from another URL, or an installed copy whose hash
- * differs from the plan's, is a different download and is checked.
- */
 const key = (entry) => `${entry.name}@${entry.version ?? "?"} ${entry.resolved ?? ""} ${entry.integrity ?? ""}`;
-/**
- * Every package version the install would bring that the project did not
- * have — direct and transitive, each name@version, source and hash once. A changed version of
- * an existing package is reported with the previous version.
- */
 export function diffLockfiles(before, after) {
     const had = new Set((before ?? []).map(key));
     const previous = new Map();

package/dist/install/pnpm-builds.js

@@ -4,12 +4,10 @@ import { parseYamlDocuments, YamlError } from "./yaml.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** "nx@21.6.4 || 21.6.5" → "nx"; "@s/x@1" → "@s/x". */
 const matcherName = (key) => {
     const at = key.indexOf("@", key.startsWith("@") ? 1 : 0);
     return (at === -1 ? key : key.slice(0, at)).trim();
 };
-/** Whether the manifest pins a package manager other than exactly this pnpm version. */
 function pinnedElsewhere(manifest, pnpmVersion) {
     if (manifest.packageManager !== undefined) {
         const pin = /^pnpm@(\d+\.\d+\.\d+)(?:\+.*)?$/.exec(String(manifest.packageManager));
@@ -34,9 +32,6 @@ export function pnpmBuildPolicy(files, pnpmVersion) {
     try {
         if (files.packageJson !== undefined) {
             const manifest = JSON.parse(stripBom(files.packageJson));
-            // The real install runs the pnpm the project pins (corepack, or pnpm's
-            // own version switching), not necessarily the one croak measured: any
-            // pin but exactly that version, and every script counts (M6 review).
             if (isRecord(manifest) && pinnedElsewhere(manifest, pnpmVersion))
                 return undefined;
             if (isRecord(manifest) && isRecord(manifest.pnpm))
@@ -54,11 +49,9 @@ export function pnpmBuildPolicy(files, pnpmVersion) {
     }
     const named = new Set();
     for (const s of settings) {
-        // Anything but an explicit false allows every build (YAML has True, TRUE, …).
         if (s.dangerouslyAllowAllBuilds !== undefined &&
             !/^(?:false|False|FALSE)$/.test(String(s.dangerouslyAllowAllBuilds)))
             return undefined;
-        // A list in a file croak does not read: it could allow anything.
         if (s.onlyBuiltDependenciesFile !== undefined)
             return undefined;
         for (const field of [
@@ -77,7 +70,6 @@ export function pnpmBuildPolicy(files, pnpmVersion) {
                 for (const key of Object.keys(s[field]))
                     named.add(matcherName(key));
     }
-    // A glob or pattern croak does not expand could name anything.
     if ([...named].some((name) => /[*?{}[\]!]/.test(name)))
         return undefined;
     return (name) => named.has(name);
@@ -87,11 +79,6 @@ const SCRIPT_RULES = new Set([
     "install/install-script",
     "install/new-install-script",
 ]);
-/**
- * Warnings about install scripts pnpm will not run become info. Blocks stay:
- * a malicious script is evidence about the package, and a later
- * `pnpm approve-builds` would run it.
- */
 export function applyBuildPolicy(findings, policy) {
     return findings.map((f) => {
         const label = labelOf(f.file);

package/dist/install/pnpm-lockfile.js

@@ -1,30 +1,18 @@
 import { LockfileError } from "./lockfile.js";
 import { REGISTRY } from "./registry.js";
 import { parseYamlDocuments, YamlError } from "./yaml.js";
-/**
- * pnpm-lock.yaml (lockfile v9: pnpm 9 and later, M6, D38) as the same
- * LockEntry list the npm lockfile gives, so the rest of croak plan is shared.
- * Registry packages carry only an integrity hash: the tarball URL is the
- * public registry's, as pnpm itself derives it (the hook refuses other
- * registries, D34). Git and tarball resolutions keep their source, so
- * install/source reports them; local directories are links. pnpm records no
- * hasInstallScript: install scripts come from the registry manifest and the
- * tarball instead.
- */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 const strings = (value) => Array.isArray(value)
     ? value.filter((v) => typeof v === "string")
     : [];
-/** "@scope/name@1.2.3" → ["@scope/name", "1.2.3"]; the version may be a URL or path. */
 function splitKey(key) {
     const at = key.indexOf("@", key.startsWith("@") ? 1 : 0);
     if (at <= 0)
         throw new LockfileError(`package key without a version: ${key}`);
     return [key.slice(0, at), key.slice(at + 1)];
 }
-/** Strip a snapshot's peer suffix: "react-dom@19.2.0(react@19.3.1)" → "react-dom@19.2.0". */
 const withoutPeers = (key) => {
     const open = key.indexOf("(");
     return open === -1 ? key : key.slice(0, open);
@@ -52,7 +40,6 @@ export function parsePnpmLockfile(text) {
             throw new LockfileError(`pnpm-lock.yaml version ${String(version)} is not supported: croak reads lockfile v9 (pnpm 9 and later)`);
         const packages = isRecord(doc.packages) ? doc.packages : {};
         const snapshots = isRecord(doc.snapshots) ? doc.snapshots : {};
-        // A package is optional only when every snapshot of it is.
         const optional = new Map();
         for (const [key, snap] of Object.entries(snapshots)) {
             const id = withoutPeers(key);
@@ -77,7 +64,6 @@ export function parsePnpmLockfile(text) {
                 resolved = resolution.tarball;
             else if (integrity !== undefined)
                 resolved = registryUrl(name, ref);
-            // A git or tarball dependency's "version" is its source, not a semver.
             const semver = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/.test(ref);
             entries.push({
                 path: `pnpm:${key}`,

package/dist/install/popular.js

@@ -1,8 +1,3 @@
-/**
- * Well-known npm package names, for typo-squat checks. Curated by hand from
- * widely depended-on packages; a name one keystroke away from one of these is
- * suspicious, the names themselves are not.
- */
 export const POPULAR_PACKAGES = [
     "react",
     "react-dom",

package/dist/install/project.js

@@ -7,7 +7,6 @@ import { stripBom } from "../signals/text.js";
 import { isPnpmLockfile } from "./pnpm-lockfile.js";
 import { parseYamlDocuments, YamlError } from "./yaml.js";
 const PNPM_RULE = "repo/pnpmfile";
-/** pnpm also runs the root project's pnpm:devPreinstall before it installs anything. */
 const PNPM_ROOT_SCRIPT = "pnpm:devPreinstall";
 const policies = {
     npm: lifecycleScriptWith({
@@ -25,12 +24,6 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 const outside = (path) => path === ".." || path.startsWith("../") || path.startsWith("/");
-/**
- * The workspace members a lockfile installs, as folders relative to the
- * project (M6 review): npm's `packages` keys outside node_modules, pnpm's
- * `importers` other than the root. Both package managers run a member's
- * install scripts on a plain install, as they do the root's.
- */
 export function workspaceMembers(lockfile) {
     let keys = [];
     if (isPnpmLockfile(lockfile)) {
@@ -95,9 +88,7 @@ export function projectScriptFindings(dir, fs, options = {}) {
                 scripts = data.scripts;
         }
         catch {
-            // The detector reports an unreadable package.json itself.
         }
-        // Every local file any script runs (install scripts call others via npm run).
         const files = new Set(["package.json", "binding.gyp"]);
         for (const command of Object.values(scripts))
             if (typeof command === "string")
@@ -116,13 +107,6 @@ export function projectScriptFindings(dir, fs, options = {}) {
     ];
 }
 const PNPMFILES = [".pnpmfile.cjs", ".pnpmfile.mjs"];
-/**
- * Code pnpm runs on every install of the project, scripts or not (M6, D39):
- * the pnpmfile (`.pnpmfile.cjs`, or the file `pnpmfile:` names in
- * pnpm-workspace.yaml) and config dependencies, which pnpm installs first and
- * whose pnpmfiles it loads. A pnpmfile is a warning, a block when its code
- * reaches the network with secrets or eval; config dependencies are a warning.
- */
 export function pnpmfileFindings(dir, fs) {
     const findings = [];
     let settings = {};
@@ -144,7 +128,6 @@ export function pnpmfileFindings(dir, fs) {
             });
         }
     }
-    // One file or a list of them (M6 review).
     const listed = Array.isArray(settings.pnpmfile)
         ? settings.pnpmfile
         : settings.pnpmfile === undefined
@@ -185,8 +168,6 @@ export function pnpmfileFindings(dir, fs) {
             message: `pnpm runs ${file} on every install${hits.length > 0 ? `: ${describeSignals(hits, file)}` : ""}`,
         });
     }
-    // Patches change a dependency's files after croak checked its tarball, its
-    // package.json and install scripts included (M6 review).
     let manifestSettings;
     const manifest = fs.read(posix.join(dir, "package.json"));
     if (manifest !== undefined)
@@ -196,7 +177,6 @@ export function pnpmfileFindings(dir, fs) {
                 manifestSettings = data.pnpm;
         }
         catch {
-            // The install itself fails on it; the plan reports the lockfile.
         }
     for (const [where, from] of [
         ["pnpm-workspace.yaml", settings],

package/dist/install/provenance.js

@@ -1,7 +1,3 @@
-/**
- * The workflow file a build started from, inside its repo and without its
- * ref: tags change every release, and a renamed repo renames the URI.
- */
 function workflowOf(identity) {
     const uri = identity.buildConfigUri?.replace(/@[^@]*$/, "");
     const repo = `${identity.sourceRepositoryUri ?? ""}/`;
@@ -10,12 +6,8 @@ function workflowOf(identity) {
 const repoIdOf = (identity) => identity.sourceRepositoryId === undefined
     ? undefined
     : `${identity.issuer ?? ""}#${identity.sourceRepositoryId}`;
-/** How this build differs from the previous version's, if it does. */
 function buildChanges(now, before, version) {
     const changes = [];
-    // Repos get renamed (react now builds from github.com/react/react); the
-    // numeric id survives a rename and changes when a name is re-registered.
-    // An id is only unique at its issuer (GitHub's and GitLab's overlap).
     const nowId = repoIdOf(now);
     const beforeId = repoIdOf(before);
     const otherRepo = nowId !== undefined && beforeId !== undefined
@@ -27,24 +19,11 @@ function buildChanges(now, before, version) {
         changes.push(`was built by the workflow ${workflowOf(now) ?? "(unnamed)"}, not by ${workflowOf(before) ?? "the workflow"}, which built ${version}`);
     return changes;
 }
-/**
- * The version to compare a planned one with: its semver predecessor when that
- * has provenance, else the newest settled version that does. Comparing only
- * with the predecessor would let a release without provenance in between
- * hide another repository's build (M7 review, D45).
- */
 export function provenanceBaseline(facts) {
     return facts.previous?.hasProvenance === true
         ? facts.previous
         : facts.earlier.find((v) => v.hasProvenance);
 }
-/**
- * Provenance signals for one planned version (M7, D42). A claim that does
- * not verify blocks; one croak cannot check warns. A build from another
- * repository or workflow than the baseline's warns, and blocks with an
- * install script that is new or changed since the baseline (as in D30).
- * Provenance never lowers another finding.
- */
 export function provenanceFindings(change, current, baseline, installCommands) {
     const file = `${change.entry.name}@${change.entry.version ?? "?"}`;
     const finding = (severity, message) => ({

package/dist/install/registry.js

@@ -1,14 +1,7 @@
 import { createHash } from "node:crypto";
-/**
- * A minimal npm registry client: one packument per package, read with a time
- * limit and a size limit. Package names come from untrusted lockfiles, so they
- * are validated against npm's naming rules before they become a URL.
- */
 export const REGISTRY = "https://registry.npmjs.org";
-// @prisma/client's package document alone is 68 MB (2026-10).
 const DEFAULT_MAX_BYTES = 200 * 1024 * 1024;
 const DEFAULT_TIMEOUT_MS = 15_000;
-// Legacy packages may contain capitals (JSONStream); new ones may not.
 const NAME = /^(?:@[a-zA-Z0-9-~][a-zA-Z0-9-._~]*\/)?[a-zA-Z0-9-~][a-zA-Z0-9-._~]*$/;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const MAX_TARBALL_BYTES = 100 * 1024 * 1024;
@@ -37,7 +30,6 @@ async function readCappedBytes(response, maxBytes) {
             chunk = await reader.read();
         }
         catch (error) {
-            // A timeout or a reset after the headers: the check is incomplete, not a crash.
             throw new RegistryError(`reading the response: ${error instanceof Error ? error.message : String(error)}`);
         }
         const { done, value } = chunk;
@@ -55,7 +47,6 @@ async function readCappedBytes(response, maxBytes) {
 async function readCapped(response, maxBytes) {
     return (await readCappedBytes(response, maxBytes)).toString("utf8");
 }
-/** A JSON document from the registry, or "not-found" on 404. */
 async function getJson(url, label, options, maxBytes) {
     const doFetch = options.fetch ?? fetch;
     let response;
@@ -80,18 +71,11 @@ async function getJson(url, label, options, maxBytes) {
         throw new RegistryError(`${label}: registry response is not JSON`);
     }
 }
-/** The package document, or "not-found" when the registry has no such package. */
 export async function fetchPackument(name, options = {}) {
     return getJson(packageUrl(name), name, options, options.maxBytes ?? DEFAULT_MAX_BYTES);
 }
-// A provenance bundle is ~10 KB; a version has two attestations.
 const MAX_ATTESTATIONS_BYTES = 2 * 1024 * 1024;
 const VERSION = /^[0-9A-Za-z.+-]{1,256}$/;
-/**
- * A version's SLSA provenance bundle from the registry's attestations
- * endpoint, or "missing" when there is none. The URL is built here, never
- * taken from the packument's dist.attestations.url.
- */
 export async function fetchProvenanceBundle(name, version, options = {}) {
     if (!VERSION.test(version) || version.includes(".."))
         throw new RegistryError(`not a valid npm version: ${JSON.stringify(version)}`);
@@ -112,10 +96,8 @@ const date = (value) => {
     const parsed = new Date(value);
     return Number.isNaN(parsed.getTime()) ? undefined : parsed;
 };
-/** Days a version must have been public to count as history (D25's 7 days). */
 export const SETTLED_DAYS = 7;
 const SEMVER = /^(\d{1,15})\.(\d{1,15})\.(\d{1,15})(?:-([0-9A-Za-z.-]{1,100}))?(?:\+.*)?$/;
-/** Semver order (prereleases before their release); undefined if either is not semver. */
 export function compareVersions(a, b) {
     const x = SEMVER.exec(a);
     const y = SEMVER.exec(b);
@@ -135,7 +117,6 @@ export function compareVersions(a, b) {
         return -1;
     return px < py ? -1 : 1;
 }
-/** The highest settled version below `version`, else the newest settled one. */
 function predecessor(version, earlier) {
     const below = earlier.filter((v) => (compareVersions(v.version, version) ?? 1) < 0);
     return (below.reduce((best, v) => best === undefined ||
@@ -161,7 +142,6 @@ function versionInfo(meta) {
         dependencies: [...new Set(deps)].sort(),
     };
 }
-/** What the registry says about one version, or undefined if it does not list it. */
 export function versionFacts(packument, version, now = new Date()) {
     if (!isRecord(packument) ||
         !isRecord(packument.versions) ||
@@ -193,7 +173,6 @@ export function versionFacts(packument, version, now = new Date()) {
         previous: predecessor(version, earlier),
     };
 }
-/** A version's tarball URL and integrity, from its packument (the LLM diff's "before"). */
 export function tarballOf(packument, version) {
     if (!isRecord(packument) || !isRecord(packument.versions))
         return undefined;
@@ -206,14 +185,12 @@ export function tarballOf(packument, version) {
         integrity: typeof dist.integrity === "string" ? dist.integrity : undefined,
     };
 }
-/** The downloaded tarball does not match the lockfile's integrity hash. */
 export class IntegrityError extends Error {
     constructor(message) {
         super(message);
         this.name = "IntegrityError";
     }
 }
-/** Checks data against an SRI string ("sha512-…"), using the strongest algorithm it lists. */
 export function verifyIntegrity(data, integrity) {
     const hashes = new Map(integrity
         .trim()
@@ -229,12 +206,6 @@ export function verifyIntegrity(data, integrity) {
     if (actual !== hashes.get(algorithm))
         throw new IntegrityError(`${algorithm} does not match the lockfile`);
 }
-/**
- * The tarball URL if `resolved` points at the public registry over https,
- * with no credentials or explicit port. One predicate for what croak
- * downloads, checks online, and reports as a non-registry source, so a
- * package can never fall between them unchecked.
- */
 export function registryTarball(resolved) {
     if (resolved === undefined || !URL.canParse(resolved))
         return undefined;
@@ -247,10 +218,6 @@ export function registryTarball(resolved) {
         ? url
         : undefined;
 }
-/**
- * Downloads a tarball from the public registry (https only) with a timeout
- * and a 100 MB cap, and verifies it against the lockfile's integrity hash.
- */
 export async function fetchTarball(url, integrity, options = {}) {
     const tarball = registryTarball(url);
     if (tarball === undefined)

package/dist/install/sanitize.js

@@ -1,15 +1,5 @@
 import { stripBom } from "../signals/text.js";
 import { parseYamlDocuments } from "./yaml.js";
-/**
- * What the planning wrapper may hand to a package manager from an untrusted
- * project (M6, D38). Planning must run no project code, but pnpm runs code
- * before it resolves anything: corepack downloads and runs the pnpm version a
- * project's `packageManager` names (checked: pnpm 12 ran pnpm 9.15.0, even
- * with manage-package-manager-versions=false), and pnpm-workspace.yaml can
- * load pnpmfiles and config dependencies. So the root manifest loses its
- * package-manager pins, and the workspace file keeps only settings that shape
- * resolution. Both come out as JSON, which YAML reads too.
- */
 export class SanitizeError extends Error {
     constructor(message) {
         super(message);
@@ -19,7 +9,6 @@ export class SanitizeError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** The root package.json without the fields that make corepack fetch a package manager. */
 export function sanitizeRootManifest(text) {
     let manifest;
     try {
@@ -31,7 +20,6 @@ export function sanitizeRootManifest(text) {
     if (!isRecord(manifest))
         throw new SanitizeError("package.json is not an object");
     const { packageManager: _pm, devEngines: _de, pnpm, ...rest } = manifest;
-    // pnpm 10 reads settings from the root manifest's "pnpm" field too.
     const kept = isRecord(pnpm)
         ? {
             ...rest,
@@ -40,7 +28,6 @@ export function sanitizeRootManifest(text) {
         : rest;
     return `${JSON.stringify(kept, null, 2)}\n`;
 }
-/** Settings that only shape what pnpm resolves; nothing that loads or runs code, or moves the registry. */
 const WORKSPACE_KEYS = new Set([
     "packages",
     "catalog",
@@ -58,7 +45,6 @@ const WORKSPACE_KEYS = new Set([
     "supportedArchitectures",
     "ignoredOptionalDependencies",
 ]);
-/** YAML scalars come back as strings; pnpm wants booleans where YAML had them. */
 function typed(value) {
     if (value === "true" || value === "True" || value === "TRUE")
         return true;

package/dist/install/scan.js

@@ -13,15 +13,9 @@ import { provenanceBaseline, provenanceFindings, } from "./provenance.js";
 import { fetchPackument, fetchProvenanceBundle, fetchTarball, IntegrityError, RegistryError, registryTarball, versionFacts, } from "./registry.js";
 import { signatureFindings } from "./signature.js";
 import { snapshotTarball, TarballError } from "./tar.js";
-/** An npm package-lock.json or a pnpm-lock.yaml, told apart by their first lines. */
 export function parseAnyLockfile(text) {
     return isPnpmLockfile(text) ? parsePnpmLockfile(text) : parseLockfile(text);
 }
-/**
- * Judges what an install would bring in, from the project's lockfile before
- * and the lockfile npm planned (`--package-lock-only --ignore-scripts`).
- * croak itself runs no package manager; it only reads the two files.
- */
 export function planInstall(beforeText, afterText, detectors = installDetectors) {
     const started = performance.now();
     const parse = (text, which) => {
@@ -58,15 +52,9 @@ export function planInstall(beforeText, afterText, detectors = installDetectors)
     }
 }
 const DEFAULT_MAX_DOWNLOAD_BYTES = 300 * 1024 * 1024;
-/** The plan is too large to inspect within the download budget. */
 class BudgetError extends Error {
 }
 const keyOf = (s) => `${s.name}@${s.version}`;
-/**
- * Provenance findings (D42, D43) for planned versions the registry lists
- * with provenance: each one's bundle, and its previous version's, fetched
- * and verified, then compared.
- */
 async function provenanceOf(known, options, fetchOptions) {
     const plans = known.flatMap(({ change, facts }) => {
         if (facts === undefined || facts === "not-found" || !facts.hasProvenance)
@@ -81,8 +69,6 @@ async function provenanceOf(known, options, fetchOptions) {
         const previous = before === undefined
             ? undefined
             : subject(before.version, before.integrity);
-        // Both bundles are immutable for these tarballs, and so are both
-        // versions' install scripts: the findings can be remembered.
         const label = `provenance ${keyOf(current)} after ${previous === undefined ? "none" : `${keyOf(previous)} ${previous.integrity}`}`;
         const cached = options.cache?.get(current.integrity, label);
         return [{ change, facts, before, current, previous, label, cached }];
@@ -116,13 +102,11 @@ async function provenanceOf(known, options, fetchOptions) {
                 provenance: then,
                 installCommands: before.installCommands,
             }, facts.installCommands);
-        // A bundle the registry did not serve may be served next time.
         if (now !== "missing" && then !== "missing")
             options.cache?.set(current.integrity, plan.label, findings);
         return findings;
     });
 }
-/** Runs `work` over `items` with at most `limit` in flight. */
 async function pool(items, limit, work) {
     const results = new Array(items.length);
     let next = 0;
@@ -135,11 +119,6 @@ async function pool(items, limit, work) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
     return results;
 }
-/**
- * planInstall plus npm registry signals (D26) for every new or changed version
- * that comes from the public registry. Any registry failure makes the whole
- * check incomplete: an agent must not proceed on a partial answer.
- */
 export async function planInstallOnline(beforeText, afterText, options = {}) {
     const started = performance.now();
     const local = planInstall(beforeText, afterText);
@@ -147,7 +126,6 @@ export async function planInstallOnline(beforeText, afterText, options = {}) {
         return local;
     const before = beforeText === undefined ? undefined : parseAnyLockfile(beforeText);
     const fromRegistry = diffLockfiles(before, parseAnyLockfile(afterText)).filter((c) => !c.entry.link && registryTarball(c.entry.resolved) !== undefined);
-    // npm skips platform packages for other systems, so they are not checked.
     const platform = options.platform ?? {
         os: process.platform,
         cpu: process.arch,
@@ -193,7 +171,6 @@ export async function planInstallOnline(beforeText, afterText, options = {}) {
                 : signatureFindings(c, facts, options.registryKeys);
             return [...metadataFindings(c, facts, now), ...signature, ...deps];
         });
-        // Both only read the registry; neither waits for the other.
         const [provenance, content] = await Promise.all([
             provenanceOf(known, options, fetchOptions),
             options.content === false ? [] : contentOf(changes, options),
@@ -205,7 +182,6 @@ export async function planInstallOnline(beforeText, afterText, options = {}) {
             ...provenance,
             ...content,
         ];
-        // Before the LLM step: a script pnpm will not run needs no second opinion.
         const ruled = options.builds === undefined
             ? all
             : applyBuildPolicy(all, options.builds);
@@ -247,7 +223,6 @@ export async function planInstallOnline(beforeText, afterText, options = {}) {
         throw error;
     }
 }
-/** Any listed version, to read package-level facts such as the creation date. */
 function firstVersion(doc) {
     const versions = typeof doc === "object" && doc !== null && "versions" in doc
         ? doc.versions
@@ -256,11 +231,6 @@ function firstVersion(doc) {
         ? (Object.keys(versions)[0] ?? "")
         : "";
 }
-/**
- * Downloads each registry tarball (verified against the lockfile's integrity),
- * reads it in memory, and runs the content detectors. A tampered tarball is a
- * block; a plan over the download budget is incomplete, never partially clean.
- */
 async function contentOf(changes, options) {
     const budget = options.maxDownloadBytes ?? DEFAULT_MAX_DOWNLOAD_BYTES;
     let downloaded = 0;
@@ -293,7 +263,6 @@ async function contentOf(changes, options) {
         if (downloaded > budget)
             throw new BudgetError(`the plan downloads more than ${budget} bytes of tarballs`);
         const findings = contentFindings(label, snapshotTarball(data));
-        // Only after the download verified against this hash and was read whole.
         if (entry.integrity !== undefined)
             options.cache?.set(entry.integrity, label, findings);
         return findings;