@vola-trebla/croak 0.1.0 → 0.1.1

package/dist/cli.js

@@ -18,14 +18,8 @@ import { anthropicTriage, DEFAULT_MODEL } from "./llm/client.js";
 import { renderScan, scanToJson } from "./repo-report.js";
 import { ScanTargetError, scanRepoAt } from "./scan.js";
 import { aggregate } from "./verdict.js";
-export const VERSION = "0.1.0";
-/**
- * 0 allow or warn (warnings are printed, the process succeeds),
- * 1 block, 2 usage error, 3 the scan could not complete — agents treat 3 as
- * a block (fail-closed).
- */
+export const VERSION = "0.1.1";
 export const EXIT = { ok: 0, block: 1, usage: 2, incomplete: 3 };
-/** Conventional exit code for invalid command-line usage. */
 export const EXIT_USAGE = EXIT.usage;
 const DEFAULT_DEPS = {
     scan: (root) => scanRepoAt(root),
@@ -110,7 +104,6 @@ async function runPlan(values, rest, deps) {
     if (values.installed !== undefined && values.before !== undefined)
         return usageError("plan takes --before or --installed, not both");
     if (values.installed !== undefined) {
-        // What is really in node_modules, verified folder by folder (D34).
         const tryRead = (path) => {
             try {
                 return read(path);
@@ -119,7 +112,6 @@ async function runPlan(values, rest, deps) {
                 return undefined;
             }
         };
-        // The installed tree of the manager that wrote the plan (D38).
         before = isPnpmLockfile(after)
             ? installedPnpmLockfile(values.installed, tryRead, (dir) => {
                 try {
@@ -137,7 +129,6 @@ async function runPlan(values, rest, deps) {
             return text;
         before = text;
     }
-    // pnpm's own rule for whose install scripts run, from the project's settings (D38).
     const buildsDir = values["pnpm-builds"];
     const builds = buildsDir === undefined || values["pnpm-version"] === undefined
         ? undefined
@@ -159,7 +150,6 @@ async function runPlan(values, rest, deps) {
                 }
             })(),
         }, values["pnpm-version"]);
-    // --offline: lockfile signals only, no registry requests (tests, air-gapped CI).
     const outcome = values.offline === true
         ? planInstall(before, after)
         : await planInstallOnline(before, after, {
@@ -173,7 +163,6 @@ async function runPlan(values, rest, deps) {
                 ? { llm: deps.llm }
                 : {}),
         });
-    // --llm without a key: the rules decide, and the report says the model did not run.
     const llmMissing = values.llm === true && deps.llm === undefined && values.offline !== true
         ? [
             {
@@ -209,24 +198,17 @@ async function runPlan(values, rest, deps) {
             }
         },
     };
-    // A plain npm install or npm ci also runs the project's own install scripts
-    // (D35); pnpm runs the project's pnpmfile and config dependencies on every
-    // install (D39).
     const project = values.project;
     const extra = [
         ...llmMissing,
-        // The pnpmfile check needs only the project; the version is for the build rule.
         ...(buildsDir === undefined ? [] : pnpmfileFindings(buildsDir, projectFs)),
         ...(project === undefined || outcome.status !== "complete"
             ? []
             : projectScriptFindings(project, projectFs, {
-                // The plan's lockfile parsed, so its members can be read (M6 review).
                 members: workspaceMembers(after),
                 pnpm: buildsDir !== undefined,
             })),
     ];
-    // The folder the install ran in must be a member of the workspace the plan
-    // was made at; otherwise the package manager installs elsewhere (M6 review).
     const member = values.member;
     const notMember = member !== undefined &&
         outcome.status === "complete" &&
@@ -248,9 +230,7 @@ async function runPlan(values, rest, deps) {
         : renderPlan(judged, { emoji: deps.emoji && values.plain !== true });
     return { code: exitCode(judged), stdout, stderr: "" };
 }
-/** Pure entry point: all I/O goes through deps. */
 export async function run(argv, deps = DEFAULT_DEPS) {
-    // What the planning wrapper may hand to pnpm from an untrusted project (D38).
     if (argv[0] === "sanitize") {
         const [, kind, file] = argv;
         if (file === undefined ||
@@ -273,7 +253,6 @@ export async function run(argv, deps = DEFAULT_DEPS) {
             throw error;
         }
     }
-    // The workspace root croak-install plans at (D38): the same reading as the hook's.
     if (argv[0] === "workspace-root") {
         const [, manager, dir] = argv;
         if (dir === undefined || (manager !== "npm" && manager !== "pnpm"))
@@ -288,7 +267,6 @@ export async function run(argv, deps = DEFAULT_DEPS) {
             stderr: "",
         };
     }
-    // Suggestions for package names npm does not have (croak-install on E404).
     if (argv[0] === "suggest") {
         const lines = argv.slice(1).flatMap((spec) => {
             const names = suggestNames(decodeURIComponent(spec));
@@ -300,7 +278,6 @@ export async function run(argv, deps = DEFAULT_DEPS) {
         });
         return { code: EXIT.ok, stdout: lines.join(""), stderr: "" };
     }
-    // The agent hook's two steps (scripts/croak-hook.sh); they read files only.
     if (argv[0] === "hook")
         return runHook(argv.slice(1), {
             readFile: deps.readFile ?? ((path) => readFileSync(path, "utf8")),
@@ -313,7 +290,6 @@ export async function run(argv, deps = DEFAULT_DEPS) {
         parsed = parse(argv);
     }
     catch (error) {
-        // Usage mistakes are explained, not crashed on; anything else is a bug.
         if (!isParseArgsError(error))
             throw error;
         return usageError(error.message);
@@ -345,9 +321,7 @@ export async function run(argv, deps = DEFAULT_DEPS) {
         : renderScan(outcome, { emoji: deps.emoji && values.plain !== true });
     return { code: exitCode(outcome), stdout, stderr: "" };
 }
-// Only touch the process when executed directly, not when imported by tests.
 if (import.meta.main) {
-    // Built on first use: fingerprinting croak's code costs a directory read.
     let cache;
     const contentCache = () => {
         cache ??= fileContentCache(join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "croak", "content"), codeFingerprint(import.meta.dirname));

package/dist/crypto/der.js

@@ -1,9 +1,3 @@
-/**
- * Just enough DER to read the build identity Fulcio writes into a signing
- * certificate (M7, D42). node:crypto verifies certificates but does not expose
- * custom extensions. Certificates come from the registry, so every length is
- * checked against the bytes that are there.
- */
 export class DerError extends Error {
     constructor(message) {
         super(message);
@@ -41,7 +35,6 @@ export function readTlv(buf, offset) {
         throw new DerError(`element at byte ${offset} runs past the end`);
     return { tag, start, end };
 }
-/** The elements inside a constructed element, in order. */
 export function children(buf, parent) {
     const out = [];
     for (let at = parent.start; at < parent.end;) {
@@ -63,7 +56,6 @@ function oidOf(buf, tlv) {
     const first = bytes[0];
     if (first === undefined)
         throw new DerError("empty OID");
-    // The first byte packs the first two arcs as 40 * a + b (a is at most 2).
     const top = Math.min(2, Math.floor(first / 40));
     const arcs = [top, first - top * 40];
     let value = 0;
@@ -78,7 +70,6 @@ function oidOf(buf, tlv) {
     }
     return arcs.join(".");
 }
-// Fulcio's v2 extensions (1.3.6.1.4.1.57264.1.8 onwards), each a DER UTF8String.
 const FULCIO = "1.3.6.1.4.1.57264.1.";
 const FIELDS = {
     [`${FULCIO}8`]: "issuer",
@@ -95,10 +86,6 @@ const OCTET_STRING = 0x04;
 const SEQUENCE = 0x30;
 const OID = 0x06;
 const EXTENSIONS = 0xa3;
-/**
- * The build identity in a Fulcio certificate. Reads only; whether the
- * certificate is genuine is src/crypto/sigstore.ts's job.
- */
 export function fulcioIdentity(certDer) {
     const cert = expectTag(readTlv(certDer, 0), SEQUENCE, "a certificate");
     const tbs = expectTag(children(certDer, cert)[0], SEQUENCE, "tbsCertificate");

package/dist/crypto/fields.js

@@ -1,9 +1,4 @@
 import { verify, X509Certificate } from "node:crypto";
-/**
- * Reading Sigstore bundles, which come from the registry: every field is
- * checked for shape before it is used (M7, D43).
- */
-/** Why a bundle check stopped: it is wrong, or croak cannot tell. */
 export class SigstoreError extends Error {
     status;
     constructor(status, message) {
@@ -17,7 +12,6 @@ export const unverifiable = (message) => new SigstoreError("unverifiable", messa
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** The string at `path` inside `value`; anything else is an invalid bundle. */
 export function str(value, ...path) {
     let at = value;
     for (const key of path) {
@@ -45,11 +39,6 @@ export function certFrom(der, what) {
         throw invalid(`${what} is not a certificate`);
     }
 }
-/**
- * A SHA-256 signature check that answers false instead of throwing: keys
- * and signatures come from the registry, and node:crypto throws on some
- * (an Ed25519 key with a digest, malformed DER).
- */
 export function verifies(data, key, signature) {
     try {
         return verify("sha256", data, key, signature);

package/dist/crypto/registry-signature.js

@@ -4,12 +4,6 @@ const p256 = (spkiBase64) => createPublicKey({
     format: "der",
     type: "spki",
 });
-/**
- * registry.npmjs.org/-/npm/v1/keys, pinned 2026-10-31 (D42). Pinned, not
- * fetched: keys from the same server as the packument would only check the
- * server against itself. A key croak does not know is "unverifiable", never
- * a pass.
- */
 export const NPM_REGISTRY_KEYS = [
     {
         keyid: "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA",
@@ -38,15 +32,9 @@ function verifies(message, key, sig) {
         return verify("sha256", message, key, Buffer.from(sig, "base64"));
     }
     catch {
-        // Malformed DER is a bad signature, not a crash.
         return false;
     }
 }
-/**
- * Like npm's own check: every signature by a known key must verify, and a
- * key past its expiry signs nothing published after it. Signatures by keys
- * croak does not know are skipped while a known one verifies.
- */
 export function checkRegistrySignature(pkg, keys = NPM_REGISTRY_KEYS) {
     const signatures = signaturesOf(pkg.signatures);
     if (signatures.length === 0)

package/dist/crypto/rekor.js

@@ -7,20 +7,9 @@ export function rekorLog(spkiBase64) {
         publicKey: createPublicKey({ key: der, format: "der", type: "spki" }),
     };
 }
-/**
- * rekor.sigstore.dev, pinned 2026-10-31 from github.com/sigstore/root-signing
- * targets/trusted_root.json (D42). Rekor v2 logs (Ed25519, no SET) are not
- * pinned: their entries are unverifiable (D43).
- */
 export const REKOR_V1 = rekorLog("MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2G2Y+2tabdTV5BcGiBIx0a9fAFwrkBbmLSGtks4L3qX6yYY0zufBnhC8Ur/iy55GhWP/9A/bY2LhC30M9+RYtw==");
 const SUPPORTED = ["dsse 0.0.1", "intoto 0.0.2"];
-/** A PEM certificate as Rekor stores it (base64 of the PEM text), as DER. */
 const pemCertDer = (base64Pem) => certFrom(b64(base64Pem), "the logged certificate").raw;
-/**
- * Verifies the SET over a bundle's log entry and reads what it recorded.
- * Throws a SigstoreError: invalid when the entry is not what the log
- * signed, unverifiable for a log, kind or shape croak does not support.
- */
 export function readLogEntry(entry, log) {
     const kind = `${str(entry, "kindVersion", "kind")} ${str(entry, "kindVersion", "version")}`;
     if (!SUPPORTED.includes(kind))
@@ -35,7 +24,6 @@ export function readLogEntry(entry, log) {
     if (!/^\d{1,15}$/.test(integratedTime) || !/^\d{1,15}$/.test(logIndex))
         throw invalid("the log entry's time or index is not a number");
     const body = str(entry, "canonicalizedBody");
-    // Rekor signs the canonical JSON of these four fields, keys sorted.
     const promise = JSON.stringify({
         body,
         integratedTime: Number(integratedTime),
@@ -59,7 +47,6 @@ export function readLogEntry(entry, log) {
             certificateDer: pemCertDer(str(logged, "spec", "signatures", 0, "verifier")),
             payloadHash: str(logged, "spec", "payloadHash", "value"),
         };
-    // intoto 0.0.2 stores the signature base64-encoded once more.
     const signer = ["spec", "content", "envelope", "signatures", 0];
     return {
         loggedAt,

package/dist/crypto/sigstore.js

@@ -3,11 +3,6 @@ import { DerError, fulcioIdentity } from "./der.js";
 import { b64, certFrom, invalid, isRecord, SigstoreError, str, unverifiable, verifies, } from "./fields.js";
 import { REKOR_V1, readLogEntry } from "./rekor.js";
 const pinned = (base64) => certFrom(Buffer.from(base64, "base64"), "a pinned Fulcio certificate");
-/**
- * Sigstore's public-good instance, pinned 2026-10-31 from
- * github.com/sigstore/root-signing targets/trusted_root.json (D42): the
- * Fulcio CA valid since 2022-04-13 (npm provenance began in 2023).
- */
 export const SIGSTORE_PUBLIC_GOOD = {
     fulcio: [
         pinned("MIICGjCCAaGgAwIBAgIUALnViVfnU0brJasmRkHrn/UnfaQwCgYIKoZIzj0EAwMwKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTAeFw0yMjA0MTMyMDA2MTVaFw0zMTEwMDUxMzU2NThaMDcxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjEeMBwGA1UEAxMVc2lnc3RvcmUtaW50ZXJtZWRpYXRlMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE8RVS/ysH+NOvuDZyPIZtilgUF9NlarYpAd9HP1vBBH1U5CV77LSS7s0ZiH4nE7Hv7ptS6LvvR/STk798LVgMzLlJ4HeIfF3tHSaexLcYpSASr1kS0N/RgBJz/9jWCiXno3sweTAOBgNVHQ8BAf8EBAMCAQYwEwYDVR0lBAwwCgYIKwYBBQUHAwMwEgYDVR0TAQH/BAgwBgEB/wIBADAdBgNVHQ4EFgQU39Ppz1YkEZb5qNjpKFWixi4YZD8wHwYDVR0jBBgwFoAUWMAeX5FFpWapesyQoZMi0CrFxfowCgYIKoZIzj0EAwMDZwAwZAIwPCsQK4DYiZYDPIaDi5HFKnfxXx6ASSVmERfsynYBiX2X6SJRnZU84/9DZdnFvvxmAjBOt6QpBlc4J/0DxvkTCqpclvziL6BCCPnjdlIB3Pu3BxsPmygUY7Ii2zbdCdliiow="),
@@ -38,12 +33,10 @@ function checkCertificate(leaf, chain, at) {
     if (at < leaf.validFromDate || at > leaf.validToDate)
         throw invalid("it was logged outside the signing certificate's lifetime");
 }
-/** DSSE's pre-authentication encoding: what the envelope signature covers. */
 const pae = (type, payload) => Buffer.concat([
     Buffer.from(`DSSEv1 ${Buffer.byteLength(type)} ${type} ${payload.length} `),
     payload,
 ]);
-/** A package URL with its escapes undone (npm writes `pkg:npm/%40scope/name@1.0.0`). */
 function purlName(purl) {
     try {
         return decodeURIComponent(purl);
@@ -89,7 +82,6 @@ function check(bundle, subject, trust) {
         throw invalid(`the envelope carries ${type}, not an in-toto statement`);
     const payload = b64(str(bundle, "dsseEnvelope", "payload"));
     const sig = str(bundle, "dsseEnvelope", "signatures", 0, "sig");
-    // Fulcio also certifies Ed25519 keys; npm's are EC. Others are unchecked.
     const keyType = leaf.publicKey.asymmetricKeyType;
     if (keyType !== "ec" && keyType !== "rsa")
         throw unverifiable(`the signing key is ${keyType ?? "of an unknown type"}`);
@@ -106,7 +98,6 @@ function check(bundle, subject, trust) {
         loggedAt: logged.loggedAt,
     };
 }
-/** Verifies an npm provenance bundle (the SLSA one) for this exact tarball. */
 export function verifyProvenance(bundle, subject, trust = SIGSTORE_PUBLIC_GOOD) {
     try {
         return check(bundle, subject, trust);

package/dist/detectors/git-config.js

@@ -19,7 +19,6 @@ const BOOLEAN = new Set([
 ]);
 const MAX_SHOWN = 60;
 const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
-/** What git does with a setting, or undefined when the setting runs nothing. */
 function classify({ section, key, value }) {
     const name = `${section.split(".")[0] ?? ""}.${key}`;
     if (section === "core" && key === "fsmonitor") {
@@ -41,13 +40,11 @@ function classify({ section, key, value }) {
         return { when: "runs on every git diff", severity: "block" };
     if (section.startsWith("filter.") &&
         ["clean", "smudge", "process"].includes(key)) {
-        // Git runs filter values through the shell: only the exact LFS command is benign.
         return LFS_FILTER.test(value)
             ? { when: "is a Git LFS filter", severity: "info" }
             : { when: "runs on checkout and add", severity: "block" };
     }
     if (name === "credential.helper") {
-        // Only a bare helper name (osxkeychain, store, manager) is benign.
         return NAMED_HELPER.test(value)
             ? { when: "is a named credential helper", severity: "info" }
             : { when: "runs when git asks for credentials", severity: "block" };
@@ -125,7 +122,6 @@ const isGitConfig = (path) => path === ".git/config" ||
     path.endsWith("/.git/config") ||
     posix.basename(path) === ".gitmodules";
 const isActiveHook = (path) => /(?:^|\/)\.git\/hooks\/[^/]+$/.test(path) && !path.endsWith(".sample");
-/** Git settings and hooks that make ordinary git commands run code (e.g. a zip-shipped .git). */
 export const gitConfig = (repo) => repo.entries
     .filter((e) => e.kind === "file" && !isInNodeModules(e.path))
     .flatMap((e) => {

package/dist/detectors/hidden-code.js

@@ -2,7 +2,6 @@ import { codeSignals } from "../signals/code.js";
 import { hiddenCode } from "../signals/hidden.js";
 import { isInNodeModules } from "./node-modules-present.js";
 const RULE = "repo/hidden-code";
-/** Files a toolchain, IDE, or shell may execute or load. */
 const SCANNED = /\.(?:[cm]?[jt]sx?|json|sh|bash|zsh|py|rb|pl|ps1)$/;
 const MAX_HITS_PER_FILE = 5;
 const SEVERITY_RANK = {
@@ -19,7 +18,6 @@ const DESCRIBE = {
 const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
 function severityOf(hit, path) {
     if (hit.kind === "bidi") {
-        // RTL locale files legitimately contain bidi isolates.
         return path.endsWith(".json") ? "info" : "warn";
     }
     return codeSignals(hit.hidden).length > 0 ? "block" : "warn";
@@ -27,9 +25,6 @@ function severityOf(hit, path) {
 function finding(hit, path, downgradeInstalled) {
     const signals = [...new Set(codeSignals(hit.hidden).map((s) => s.signal))];
     const raw = severityOf(hit, path);
-    // In a repo, installed and committed dependencies look the same and
-    // repo/node-modules-present already flags the directory, so content inside
-    // it is at most a warning. In a package, node_modules is bundled code npm runs.
     const severity = downgradeInstalled && isInNodeModules(path) && raw === "block"
         ? "warn"
         : raw;
@@ -43,13 +38,11 @@ function finding(hit, path, downgradeInstalled) {
         message: `${DESCRIBE[hit.kind]} at line ${hit.line}, column ${hit.column}${detail}${using}`,
     };
 }
-/** Code placed where a human reviewing the file will not see it. */
 export function hiddenCodeWith({ downgradeInstalled, }) {
     return (repo) => repo.entries
         .filter((e) => e.kind === "file" && SCANNED.test(e.path))
         .flatMap((e) => hiddenCode(repo.read(e.path) ?? "")
         .map((hit) => finding(hit, e.path, downgradeInstalled))
-        // Most severe first, so harmless decoys cannot push the payload past the cap.
         .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity])
         .slice(0, MAX_HITS_PER_FILE));
 }

package/dist/detectors/ide-autorun.js

@@ -11,14 +11,11 @@ function isRecord(value) {
 }
 const asString = (value) => typeof value === "string" ? value : undefined;
 const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
-/** Lines (1-based) that mention folderOpen, in order: one per autorun task. */
 function folderOpenLines(text) {
     return text
         .split("\n")
         .flatMap((line, index) => (line.includes("folderOpen") ? [index + 1] : []));
 }
-/** The npm script a task runs, read from the package.json next to the .vscode folder. */
-/** The package.json next to the .vscode folder: its directory and scripts. */
 function manifestFor(repo, tasksPath) {
     const folder = posix.dirname(posix.dirname(tasksPath));
     const dir = folder === "." ? "" : folder;
@@ -35,7 +32,6 @@ function manifestFor(repo, tasksPath) {
         };
     }
     catch {
-        // An unreadable package.json is reported by repo/lifecycle-script.
         return { dir, scripts: {} };
     }
 }
@@ -45,8 +41,6 @@ function taskFinding(repo, path, task, line, trigger) {
     const hidden = presentation.reveal === "never" ? ", with its terminal hidden" : "";
     const at = line === undefined ? { file: path } : { file: path, line };
     if (task.type === "npm") {
-        // Same analysis as install scripts: the script, the files it runs, and
-        // the scripts it calls through npm run.
         const script = asString(task.script) ?? "";
         const { dir, scripts } = manifestFor(repo, path);
         const command = asString(scripts[script]);
@@ -64,7 +58,6 @@ function taskFinding(repo, path, task, line, trigger) {
             message: `task "${label}" runs npm script "${script}" (${shown}) ${trigger}${hidden}${reasons}`,
         };
     }
-    // shell, process, or no type: VS Code runs the command directly.
     const args = Array.isArray(task.args)
         ? task.args.filter((a) => typeof a === "string")
         : [];
@@ -111,7 +104,6 @@ function tasksFindings(repo, path) {
     const autorun = tasks.filter((task) => isRecord(task.runOptions) && task.runOptions.runOn === "folderOpen");
     const lines = folderOpenLines(text);
     const findings = autorun.map((task, index) => taskFinding(repo, path, task, lines[index], "when the folder is opened"));
-    // Tasks an autorun task depends on run first, just as automatically.
     const seen = new Set(autorun);
     const queue = autorun.flatMap((task) => dependsOnLabels(task).map((dep) => ({
         dep,
@@ -128,7 +120,6 @@ function tasksFindings(repo, path) {
     }
     return findings;
 }
-/** VS Code tasks that run by themselves when the folder is opened. */
 export const ideAutorun = (repo) => repo.entries
     .filter((e) => e.kind === "file" &&
     (e.path === TASKS_FILE || e.path.endsWith(`/${TASKS_FILE}`)) &&

package/dist/detectors/index.js

@@ -5,7 +5,6 @@ import { lifecycleScript } from "./lifecycle-script.js";
 import { nodeModulesPresent } from "./node-modules-present.js";
 import { obfuscation } from "./obfuscation.js";
 import { unscanned } from "./unscanned.js";
-/** Registered repo detectors. `unscanned` is the safety floor and always runs. */
 export const repoDetectors = [
     unscanned,
     nodeModulesPresent,

package/dist/detectors/lifecycle-script.js

@@ -4,7 +4,6 @@ import { analyzeShell } from "../signals/shell.js";
 import { stripBom } from "../signals/text.js";
 import { isInNodeModules } from "./node-modules-present.js";
 const RULE = "repo/lifecycle-script";
-/** Every script npm runs during `npm install` in the project itself. */
 export const INSTALL_SCRIPTS = [
     "preinstall",
     "install",
@@ -13,21 +12,14 @@ export const INSTALL_SCRIPTS = [
     "preprepare",
     "prepare",
     "postprepare",
-    // runs after node_modules changes (npm docs)
     "dependencies",
 ];
-/** The only scripts npm runs for a package installed from the registry. */
 export const DEPENDENCY_INSTALL_SCRIPTS = [
     "preinstall",
     "install",
     "postinstall",
 ];
-/** node_modules/<name>/package.json or node_modules/@scope/<name>/package.json, at any depth. */
 const BUNDLED_MANIFEST = /(?:^|\/)node_modules\/(?:@[^/]+\/)?[^/@][^/]*\/package\.json$/;
-/**
- * Tools that run no project code: their install-time use can be an info note
- * (D19). Everything they do is decided by the tool, not by files in the repo.
- */
 const INERT_TOOLS = new Set([
     "husky",
     "simple-git-hooks",
@@ -43,11 +35,6 @@ const INERT_TOOLS = new Set([
     "exit",
     "printf",
 ]);
-/**
- * Recognized install-time tools that execute code from the repo — a JS/TS
- * config, workspace tasks, a generator, or patches. Recognizing one adds a
- * note; the script stays a warning.
- */
 const EXECUTING_TOOLS = new Set([
     "prisma",
     "vite",
@@ -76,7 +63,6 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
-/** 1-based line of `"name":` inside the manifest's "scripts" object, if found. */
 function scriptLine(manifest, name) {
     const lines = manifest.split("\n");
     const scripts = lines.findIndex((line) => /"scripts"\s*:/.test(line));
@@ -86,21 +72,13 @@ function scriptLine(manifest, name) {
         /"\s*:/.test(line.slice(line.indexOf(key))));
     return index === -1 ? undefined : index + 1;
 }
-/**
- * Decides whether install-time commands are routine (D19): every command is an
- * inert tool or a package-manager call that runs a script which is itself
- * routine — including npm's pre/post hooks for that script — and nothing else
- * is present: no network, local files, inline code, code signals, environment
- * assignments, redirects, wrappers, or workspace-wide runs. Results are
- * memoized per script name, so a layered script graph costs linear time.
- */
 function routineChecker(scripts) {
     const memo = new Map();
     const scriptIsRoutine = (name, depth) => {
         const known = memo.get(name);
         if (known !== undefined)
             return known;
-        memo.set(name, false); // a cycle back here is not routine
+        memo.set(name, false);
         const body = scripts[name];
         const result = typeof body === "string" &&
             commandIsRoutine(body, depth + 1) &&
@@ -122,7 +100,6 @@ function routineChecker(scripts) {
             facts.commands.length === 0) {
             return false;
         }
-        // Every package-manager call must run a script: `npm install x` does not.
         const pmCalls = facts.commands.filter((name) => PACKAGE_MANAGERS.has(name)).length;
         if (pmCalls !== facts.runScripts.length)
             return false;
@@ -132,12 +109,6 @@ function routineChecker(scripts) {
     };
     return (command) => commandIsRoutine(command, 0);
 }
-/**
- * What a script's command does, including the files and inline code it runs
- * and the package.json scripts it calls through `npm run` (with npm's pre/post
- * hooks), recursively. Signals are combined across the whole call graph, so
- * an attack split across two scripts still blocks. Memoized per script name.
- */
 export function assessor(repo, dir, scripts, suspicious = isSuspicious) {
     const memo = new Map();
     const empty = {
@@ -150,7 +121,7 @@ export function assessor(repo, dir, scripts, suspicious = isSuspicious) {
         const known = memo.get(name);
         if (known !== undefined)
             return known;
-        memo.set(name, empty); // break cycles
+        memo.set(name, empty);
         const body = scripts[name];
         const result = typeof body !== "string"
             ? {
@@ -166,8 +137,6 @@ export function assessor(repo, dir, scripts, suspicious = isSuspicious) {
             return { ...empty, reasons: ["scripts are nested too deeply to follow"] };
         const facts = analyzeShell(command);
         if (facts.unparsable) {
-            // Fail closed: unparsable text that names a download tool could be
-            // hiding curl … | sh behind a trick the parser does not understand.
             return facts.mentionsDownloader
                 ? {
                     ...empty,
@@ -254,7 +223,6 @@ function manifestFindings(repo, path, { suspicious, scripts: installScripts }) {
         manifest = JSON.parse(stripBom(text));
     }
     catch {
-        // Not swallowed: an unreadable manifest is reported, the scan continues.
         return [
             {
                 ruleId: RULE,
@@ -299,7 +267,6 @@ function manifestFindings(repo, path, { suspicious, scripts: installScripts }) {
             });
         }
     }
-    // npm runs `node-gyp rebuild` for a package with binding.gyp and no install script of its own.
     const gyp = posix.join(dir, "binding.gyp");
     if (!("install" in scripts) &&
         !("preinstall" in scripts) &&
@@ -313,12 +280,6 @@ function manifestFindings(repo, path, { suspicious, scripts: installScripts }) {
     }
     return findings;
 }
-/**
- * Install-time scripts in every package.json outside node_modules (workspaces
- * run theirs too). The policy decides which code-signal combinations block and
- * which scripts count; package contents use one that tolerates binary
- * installers and follows npm's rules for registry dependencies.
- */
 export function lifecycleScriptWith(policy) {
     return (repo) => repo.entries
         .filter((e) => e.kind === "file" &&

package/dist/detectors/node-modules-present.js

@@ -1,5 +1,4 @@
 const SEGMENT = "node_modules";
-/** The outermost node_modules directory containing path, or undefined. */
 function nodeModulesRoot(path) {
     const segments = path.split("/");
     const index = segments.indexOf(SEGMENT);
@@ -8,12 +7,6 @@ function nodeModulesRoot(path) {
 export function isInNodeModules(path) {
     return nodeModulesRoot(path) !== undefined;
 }
-/**
- * croak repo checks a repo before install, so installed dependencies in it are
- * a signal on their own: a committed node_modules is a classic hiding place.
- * One finding per directory instead of one per file keeps installed projects
- * readable.
- */
 export const nodeModulesPresent = (repo) => {
     const counts = new Map();
     for (const { path } of repo.entries) {