@vola-trebla/croak 0.1.0 → 0.1.3

package/dist/detectors/obfuscation.js

@@ -8,22 +8,15 @@ const LEAD = {
     block: "obfuscated code",
 };
 const SCANNED = /\.[cm]?[jt]sx?$/;
-/** Type declarations are never executed (eslint and playwright types name `globalThis[key](…)`). */
 const DECLARATIONS = /\.d\.[cm]?ts$/;
-/** Legitimate code has these too: icon-font escape maps, embedded fonts or wasm. */
 const WEAK = new Set(["escapes", "encoded-blob"]);
-/** Whole-file obfuscator output: there, eval or decoding anywhere counts. */
 const FILE_WIDE = new Set(["obfuscator-names"]);
-/** Lines within which a signal and a call count as one construct… */
 const NEARBY_LINES = 3;
-/** …on ordinary lines. A minified file is one giant line, so there "nearby" is measured in characters. */
 const LONG_LINE = 1000;
 const NEARBY_CHARS = 200;
 const patternsOf = (...signals) => CODE_PATTERNS.filter((p) => signals.includes(p.signal)).map((p) => p.pattern);
-/** What runs code. Decoding alone only makes data (a parser's Unicode tables, wasm). */
 const EXECUTES = patternsOf("eval");
 const EXECUTES_OR_DECODES = patternsOf("eval", "decode");
-/** Every match of `patterns` as an absolute character span, with its line. */
 function spans(lines, patterns, onLines) {
     const found = [];
     let offset = 0;
@@ -42,11 +35,6 @@ function spans(lines, patterns, onLines) {
     return found;
 }
 const gap = (a, b) => Math.max(0, Math.max(a.start, b.start) - Math.min(a.end, b.end));
-/**
- * A signal is next to a call when enough of its matches (its per-line
- * threshold, e.g. 8 escapes) sit within NEARBY_CHARS of the call, or, on
- * ordinary short lines, within NEARBY_LINES of it.
- */
 function nearCall(lines, hit, calls) {
     const patterns = OBFUSCATION_PATTERNS.filter((p) => p.kind === hit.kind);
     const threshold = Math.min(...patterns.map((p) => p.threshold));
@@ -59,19 +47,9 @@ function nearCall(lines, hit, calls) {
         return (marks.filter((m) => gap(m, call) <= NEARBY_CHARS).length >= threshold);
     });
 }
-/**
- * Weak signals alone are context; one strong signal warns. It blocks when
- * two kinds meet in one construct, when obfuscator output has eval or decoding anywhere, when
- * a local strong signal (a computed global call, a rotated string array) sits
- * next to eval or decoding, or when a weak signal sits next to eval — a
- * Unicode regex beside String.fromCharCode in a parser is not one construct.
- */
 function assess(lines, hits) {
     const kinds = new Set(hits.map((hit) => hit.kind));
     const strong = [...kinds].filter((kind) => !WEAK.has(kind)).length;
-    // Two kinds are one construct when obfuscator output covers the file, or
-    // when a strong signal sits next to the other kind (not 10,000 lines away
-    // in a browser bundle, as in mocha.js).
     const markedBy = (hit) => spans(lines, OBFUSCATION_PATTERNS.filter((p) => p.kind === hit.kind).map((p) => p.pattern), new Set(hit.lines));
     const together = hits.some((hit) => FILE_WIDE.has(hit.kind)) ||
         hits.some((hit) => !WEAK.has(hit.kind) &&
@@ -93,9 +71,6 @@ function fileFinding(path, text, downgradeInstalled) {
     if (first === undefined)
         return undefined;
     const { raw, why } = assess(text.split("\n"), hits);
-    // As with other content detectors: installed and committed dependencies look
-    // the same, and repo/node-modules-present already flags the directory.
-    // (In a package, node_modules is bundled code npm runs: no downgrade.)
     const severity = downgradeInstalled && isInNodeModules(path) && raw === "block"
         ? "warn"
         : raw;
@@ -108,7 +83,6 @@ function fileFinding(path, text, downgradeInstalled) {
         message: `${LEAD[severity]}: ${seen}${raw === "block" ? why : ""}`,
     };
 }
-/** Code made deliberately unreadable — not merely minified. */
 export function obfuscationWith({ downgradeInstalled, }) {
     return (repo) => repo.entries
         .filter((e) => e.kind === "file" &&

package/dist/detectors/unscanned.js

@@ -1,13 +1,7 @@
 import { isInNodeModules } from "./node-modules-present.js";
-/** Code that a JS toolchain, an IDE, or git may execute or load. */
 const CODE = /\.(?:[cm]?[jt]sx?|json|sh|bash|zsh|py|rb|pl|ps1|gyp)$/;
 const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json"]);
-/** Type declarations are never executed, and lib.dom.d.ts alone is over 1 MB. */
 const DECLARATIONS = /\.d\.[cm]?ts$/;
-/**
- * Safety floor: a code file too large to read was not scanned, so the repo is
- * not clean. Padding a config past the read limit must not hide a payload.
- */
 export function unscannedWith({ jsonIsData, downgradeInstalled, }) {
     return (repo) => repo.entries
         .filter((entry) => entry.kind === "oversized")
@@ -20,8 +14,6 @@ export function unscannedWith({ jsonIsData, downgradeInstalled, }) {
         .map((entry) => {
         const name = entry.path.slice(entry.path.lastIndexOf("/") + 1);
         const data = jsonIsData && name.endsWith(".json") && name !== "package.json";
-        // Bundles over the limit are normal in installed dependencies; the
-        // presence of node_modules itself is flagged by repo/node-modules-present.
         const installed = downgradeInstalled && isInNodeModules(entry.path);
         return {
             ruleId: "repo/unscanned",

package/dist/hook/hook.js

@@ -11,7 +11,6 @@ export class HookInputError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** The Bash command and directory from a PreToolUse event, or undefined for other tools. */
 function hookCommand(input) {
     let data;
     try {
@@ -33,14 +32,8 @@ function hookCommand(input) {
         throw new HookInputError("the hook input has no Bash command or absolute cwd");
     return { command, cwd: data.cwd };
 }
-/** Text that goes to the shell as one tab-separated field. */
 const SAFE = /^[^\t\n\r\0]+$/;
 const isSafeSpec = (spec) => SAFE.test(spec) && !spec.startsWith("-");
-/**
- * npm's local prefix: the nearest directory, from `dir` up, with a
- * package.json or a node_modules folder (as @npmcli/config does); `dir` itself
- * when there is none. That is where npm installs, not where the agent is.
- */
 function npmPrefix(dir, exists) {
     for (let at = dir;; at = posix.dirname(at)) {
         if (exists(posix.join(at, "package.json")) ||
@@ -50,11 +43,6 @@ function npmPrefix(dir, exists) {
             return dir;
     }
 }
-/**
- * A registry that pnpm-workspace.yaml (pnpm 10+ settings) points pnpm at, or
- * a setting there that runs the repo's code or trusts another server, or
- * undefined.
- */
 function workspaceRegistry(root, deps) {
     const file = posix.join(root, "pnpm-workspace.yaml");
     if (!deps.exists(file))
@@ -82,24 +70,10 @@ function workspaceRegistry(root, deps) {
 }
 const PUBLIC_REGISTRY = /^https:\/\/registry\.npmjs\.org\/?$/;
 const REGISTRY_KEY = /(?:^|:)registry$|^replace-registry-host$/;
-/**
- * Keys that load another config croak would not read, change what npm or
- * pnpm runs scripts and git with, or let a proxy or certificate answer for
- * the registry: with them, a warning the user approves would still run the
- * repo's own shell, preload or binary, or packages croak never saw.
- */
 const RUNNER_KEY = /^(?:userconfig|globalconfig|script-shell|node-options|shell|git|init-module|shell-emulator|global-pnpmfile|pnpmfile|proxy|https?-proxy|ca|cafile|cert|key|strict-ssl)$/;
-/**
- * The same settings as pnpm-workspace.yaml writes them (M6 review): a shell or
- * preload for scripts, a pnpmfile outside the project, and a proxy or
- * certificate setting that lets another server answer for the registry.
- */
 const WORKSPACE_RUNNER_KEY = /^(?:scriptShell|nodeOptions|shellEmulator|globalPnpmfile|proxy|https?Proxy|ca|cafile|cert|key|strictSsl|userconfig|globalconfig)$/;
-/** Where npm config sends npm somewhere croak does not check (D34), or undefined. */
 function foreignRegistry(prefix, deps) {
     const env = Object.entries(deps.env ?? {});
-    // npm exports npm_config_userconfig when it launches a program; the file it
-    // names is checked like any other npmrc, rather than refused outright.
     const named = env
         .filter(([key]) => /^npm_config_(?:userconfig|globalconfig)$/i.test(key))
         .map(([, value]) => value ?? "");
@@ -118,19 +92,16 @@ function foreignRegistry(prefix, deps) {
             const line = raw.trim();
             if (line === "" || /^[;#]/.test(line))
                 continue;
-            // ini sections group keys croak does not read: refuse rather than guess.
             if (line.startsWith("["))
                 return `${file} uses [sections]`;
             const eq = line.indexOf("=");
             if (eq === -1)
                 continue;
-            // Quotes around a key or value are stripped, as npm's ini parser does.
             const unquote = (part) => part.trim().replace(/^(["'])(.*)\1$/, "$2");
             const key = unquote(line.slice(0, eq));
             const value = unquote(line.slice(eq + 1));
             if (REGISTRY_KEY.test(key) && !PUBLIC_REGISTRY.test(value))
                 return `${file} sets ${key}`;
-            // The project's npmrc comes with the repo; the user's own files do not.
             if (file === project && RUNNER_KEY.test(key))
                 return `${file} sets ${key}, which changes what npm runs or trusts`;
         }
@@ -183,7 +154,6 @@ export function hookPlan(input, deps) {
             continue;
         }
         const global = intent.kind === "install" && intent.global;
-        // A workspace installs at its root (D38): check there, with every member.
         const local = npmPrefix(intent.dir, deps.exists);
         const root = intent.kind === "run" || global
             ? undefined
@@ -207,8 +177,6 @@ export function hookPlan(input, deps) {
         if (intent.kind === "ci")
             mode = "ci";
         else if (intent.kind === "run") {
-            // npx runs the prefix's own bin when it has one: no download.
-            // pnpm dlx always downloads.
             specs = packages.filter((spec) => manager === "pnpm" ||
                 spec.includes("@", spec.startsWith("@") ? 1 : 0) ||
                 spec.includes("/") ||
@@ -224,14 +192,12 @@ export function hookPlan(input, deps) {
         else if (packages.length > 0)
             mode = "empty";
         else
-            continue; // npm install without a package.json installs nothing
+            continue;
         intents.push(intent);
         checks.push({
             id: checks.length + 1,
             manager,
             mode,
-            // Where npm stands: croak-install finds the root itself, and checks
-            // that this folder is one of its members (M6 review).
             dir: mode === "empty" ? intent.dir : local,
             packages: specs,
             label,
@@ -239,7 +205,6 @@ export function hookPlan(input, deps) {
     }
     return { intents, checks };
 }
-/** One line per check for the shell: check <id> <manager> <mode> <dir> <package>… (tab-separated). */
 export function planLines(plan) {
     return plan.checks
         .map((c) => ["check", String(c.id), c.manager, c.mode, c.dir, ...c.packages].join("\t"))
@@ -248,9 +213,7 @@ export function planLines(plan) {
 }
 const MAX_FINDINGS = 6;
 const DO_NOT_BYPASS = "Do not work around this check (another package manager, a different command, or editing files to install it); tell the user what croak found and let them decide.";
-/** One check's result as a verdict, with the findings worth showing. */
 function judge(result) {
-    // croak-install's own lines (and its did-you-mean hints) say more than npm's log.
     const tail = (text) => {
         const lines = text.trim().split("\n");
         const own = lines.filter((l) => /^croak-install:|did you mean/.test(l.trim()));
@@ -329,12 +292,6 @@ export function hookDecide(intents, results) {
         return output("ask", `🐸 croak found things to review before this install runs (not a safe verdict):\n${warned.join("\n")}`);
     return undefined;
 }
-/**
- * `croak hook plan <input.json>` prints the plan: a `plan <json>` line, then
- * the check lines. `croak hook decide <work>` reads that plan and each
- * check's <id>.code / <id>.out / <id>.err from the work directory and prints
- * the hook output, or nothing. Any error is the caller's cue to deny.
- */
 export function runHook(args, deps) {
     const [step, path] = args;
     if (path === undefined || (step !== "plan" && step !== "decide"))
@@ -370,7 +327,7 @@ function decideStep(path, deps) {
             return deps.readFile(posix.join(path, name));
         }
         catch {
-            return undefined; // a missing result is judged as a check that did not run
+            return undefined;
         }
     };
     const results = plan.checks.map((check) => {

package/dist/hook/install-commands.js

@@ -1,9 +1,7 @@
 import { posix } from "node:path";
 import { shellCommands, } from "../signals/shell.js";
-/** Agent commands can be long (heredocs); the parser is linear. */
 const MAX_COMMAND_LENGTH = 100_000;
 const MAX_DEPTH = 4;
-/** Any of these in a command croak cannot follow makes it unchecked. */
 const MENTIONS = /\b(?:npm|npx|pnpm|pnpx|yarn|bun|bunx|corepack)\b/;
 const PACKAGE_MANAGERS = new Set([
     "npm",
@@ -15,8 +13,6 @@ const PACKAGE_MANAGERS = new Set([
     "bunx",
     "corepack",
 ]);
-// ------------------------------------------------------------ npm commands
-/** npm's commands (npm 10/11 cmd-list), for its unique-prefix matching. */
 const NPM_COMMANDS = [
     "access",
     "adduser",
@@ -138,7 +134,6 @@ const NPM_ALIASES = {
     find: "search",
 };
 const NPM_NAMES = [...NPM_COMMANDS, ...Object.keys(NPM_ALIASES)];
-/** Subcommands that download or install packages. */
 const INSTALLING = new Set([
     "install",
     "install-test",
@@ -150,7 +145,6 @@ const INSTALLING = new Set([
     "dedupe",
     "link",
 ]);
-/** npm's deref: camelCase to kebab-case, aliases, then a unique prefix. */
 function npmCommand(word) {
     const name = word.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
     const exact = NPM_ALIASES[name] ?? (NPM_COMMANDS.includes(name) ? name : undefined);
@@ -159,7 +153,6 @@ function npmCommand(word) {
     const matches = new Set(NPM_NAMES.filter((n) => n.startsWith(name)).map((n) => NPM_ALIASES[n] ?? n));
     return matches.size === 1 ? [...matches][0] : undefined;
 }
-/** npm options that take a value (`--prefix dir`, `-C dir`, `-w pkg`). */
 const VALUE_FLAGS = new Set([
     "prefix",
     "workspace",
@@ -222,7 +215,6 @@ const VALUE_FLAGS = new Set([
     "fetch-retry-mintimeout",
     "fetch-retry-maxtimeout",
 ]);
-/** npm options that are flags (no value). */
 const BOOLEAN_FLAGS = new Set([
     "save",
     "save-dev",
@@ -282,14 +274,12 @@ const BOOLEAN_FLAGS = new Set([
     "commit-hooks",
     "shrinkwrap",
 ]);
-/** npm's short flags that take a value; every other short flag is a boolean. */
 const SHORT_VALUES = {
     "-C": "prefix",
     "-L": "location",
     "-w": "workspace",
     "-c": "call",
 };
-/** npx (not npm, where -p is --parseable) reads -p as --package. */
 const NPX_SHORT_VALUES = {
     ...SHORT_VALUES,
     "-p": "package",
@@ -316,7 +306,6 @@ function readNpmArgs(words, npx) {
     for (let i = 0; i < words.length; i++) {
         const word = words[i] ?? "";
         if (word === "--" || (npx && positional.length > 0)) {
-            // npx stops reading its own options at the command it runs.
             positional.push(...words.slice(word === "--" ? i + 1 : i));
             break;
         }
@@ -349,7 +338,6 @@ function readNpmArgs(words, npx) {
     }
     return { flags, positional, ambiguous };
 }
-/** npm init foo → create-foo; @s → @s/create; @s/foo@1 → @s/create-foo@1 (npm's rule). */
 function initializer(spec) {
     const at = spec.indexOf("@", 1);
     const [name, version] = at === -1 ? [spec, ""] : [spec.slice(0, at), spec.slice(at)];
@@ -392,7 +380,6 @@ function npmIntents(name, args, state, home, depth, raw) {
     if (sub === undefined ||
         !INSTALLING.has(sub) ||
         ((sub === "init" || sub === "link") && rest.length === 0)) {
-        // An unknown option may have swallowed the real subcommand (npm --proxy x install).
         if (ambiguous !== undefined &&
             rest.some((w) => INSTALLING.has(npmCommand(w) ?? "")))
             return unchecked(`croak cannot tell whether ${ambiguous} takes a value`);
@@ -427,10 +414,8 @@ function npmIntents(name, args, state, home, depth, raw) {
             return unchecked(`croak does not check npm ${sub} yet`);
     }
 }
-// ------------------------------------------------------------ pnpm commands
 const PNPM_INSTALL = new Set(["install", "i", "add", "install-test", "it"]);
 const PNPM_UPDATE = new Set(["update", "up", "upgrade"]);
-/** Subcommands that install, or run another pnpm, in ways croak does not plan. */
 const PNPM_UNCHECKED = new Set([
     "dedupe",
     "deploy",
@@ -444,7 +429,6 @@ const PNPM_UNCHECKED = new Set([
     "patch-remove",
     "self-update",
 ]);
-/** pnpm options that take a value. */
 const PNPM_VALUE_FLAGS = new Set([
     "-C",
     "--dir",
@@ -463,7 +447,6 @@ const PNPM_VALUE_FLAGS = new Set([
     "--node-linker",
     "--cache-dir",
 ]);
-/** pnpm options that are flags. */
 const PNPM_BOOLEAN_FLAGS = new Set([
     "-D",
     "-P",
@@ -513,8 +496,6 @@ function pnpmIntents(args, state, raw, dlx) {
     ];
     const flags = new Map();
     const positional = [];
-    // An allowlist: pnpm has flags that allow every build, load a pnpmfile or
-    // move the lockfile; a flag croak does not know is not guessed at (M6 review).
     let unknown;
     for (let i = 0; i < args.length; i++) {
         const word = args[i] ?? "";
@@ -568,7 +549,7 @@ function pnpmIntents(args, state, raw, dlx) {
     if (unknown !== undefined && installing)
         return unchecked(`croak does not know pnpm's ${unknown}, so it cannot vouch for this install`);
     if (sub === undefined)
-        return []; // bare pnpm prints its help
+        return [];
     if (sub === "dlx")
         return pnpmIntents(rest, { dir }, raw, true);
     if (sub === "create")
@@ -605,8 +586,6 @@ function pnpmIntents(args, state, raw, dlx) {
         },
     ]);
 }
-// ------------------------------------------------------------ shell commands
-/** Wrappers and the options of theirs that take a value. */
 const WRAPPERS = {
     sudo: new Set([
         "-u",
@@ -635,7 +614,6 @@ const WRAPPERS = {
     setsid: new Set(),
     caffeinate: new Set(["-t", "-w"]),
 };
-/** Shell keywords that start or end a compound command, not a command name. */
 const KEYWORDS = new Set([
     "{",
     "}",
@@ -657,7 +635,6 @@ const KEYWORDS = new Set([
     "function",
 ]);
 const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
-/** Commands that take a package manager's name as plain text, not to run it. */
 const TEXT_ONLY = new Set([
     "echo",
     "printf",
@@ -700,7 +677,6 @@ const OTHER_MANAGERS = {
 const OTHER_RUNNERS = new Set(["bunx", "corepack"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 const basename = (word) => word.slice(word.lastIndexOf("/") + 1);
-/** The command's real head and arguments, past keywords, assignments and wrappers. */
 function resolve(words) {
     let rest = words;
     let foreignEnv = false;
@@ -748,7 +724,6 @@ function resolve(words) {
                 rest = rest.slice(1);
     }
 }
-/** The script a shell runs with -c (also -lc, -ec, -e -c). */
 function shellScript(args) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i]?.text ?? "";
@@ -763,8 +738,6 @@ function intentsOf(commands, state, home, depth, text) {
     const found = [];
     for (const command of commands) {
         if (command.group !== undefined) {
-            // A subshell's cd does not leak out; a { …; } group's does. Either way,
-            // after a cd inside one, the outer directory is no longer certain.
             const inner = { dir: state.dir };
             found.push(...intentsOf(command.group, inner, home, depth, text));
             if (inner.dir !== state.dir)
@@ -786,7 +759,6 @@ function intentsOf(commands, state, home, depth, text) {
             continue;
         }
         if (head.dynamic) {
-            // n=npm; $n install x — the command is only known when the shell runs.
             if (MENTIONS.test(text))
                 unchecked("the command it runs is only known when the shell runs");
             continue;
@@ -806,8 +778,6 @@ function intentsOf(commands, state, home, depth, text) {
         if (SHELLS.has(name)) {
             const script = shellScript(argWords);
             if (script === undefined) {
-                // A script from stdin (a pipe) that mentions a package manager: croak
-                // does not see it. A script file is like `npm run x`: a documented gap.
                 const fromStdin = !argWords.some((w) => !w.text.startsWith("-"));
                 if (fromStdin && MENTIONS.test(text))
                     unchecked(`${name} runs a script from stdin croak cannot see`);
@@ -857,15 +827,12 @@ function intentsOf(commands, state, home, depth, text) {
             unchecked(`croak checks npm and pnpm; ${name} is not supported yet`);
             continue;
         }
-        // xargs npm i, find -exec npm i, watch npm i, docker run … npm i: a
-        // package manager run by another command, with arguments croak cannot follow.
         if (!TEXT_ONLY.has(name) &&
             argWords.some((w) => PACKAGE_MANAGERS.has(basename(w.text))))
             unchecked(`it runs a package manager through ${name}`);
     }
     return found;
 }
-/** Heredoc bodies are data for most commands, and a script croak cannot see for a shell. */
 function stripHeredocs(command) {
     const lines = command.split("\n");
     const out = [];
@@ -889,7 +856,6 @@ function stripHeredocs(command) {
     }
     return { text: out.join("\n"), shellHeredoc };
 }
-/** Settings in the same command that move npm to another registry. */
 const CONFIG_CHANGE = /\b(?:npm|pnpm)\s+(?:config\s+)?(?:set|edit)\b|\bexport\s+(?:npm|pnpm)_config_|>>?\s*\S*(?:\.npmrc|pnpm-workspace\.yaml)\b/i;
 function intentsFor(command, state, home, depth) {
     const { text, shellHeredoc } = stripHeredocs(command);
@@ -921,7 +887,6 @@ function intentsFor(command, state, home, depth) {
         ];
     return found;
 }
-/** Install intents in `command`, run from `cwd` (absolute) by a user whose home is `home`. */
 export function installIntents(command, cwd, home) {
     return intentsFor(command, { dir: cwd }, home, 0);
 }

package/dist/install/content-cache.js

@@ -1,7 +1,6 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-/** Only sha512 is strong enough to stand in for the tarball's content. */
 const cacheable = (integrity) => integrity !== undefined &&
     /^sha512-[A-Za-z0-9+/]{86}==$/.test(integrity.trim());
 const SEVERITIES = new Set(["info", "warn", "block"]);
@@ -16,12 +15,9 @@ function isFinding(value) {
         SEVERITIES.has(f.severity) &&
         (f.line === undefined || typeof f.line === "number"));
 }
-/** Errors from the filesystem (not bugs): the cache degrades to a miss. */
 const isFsError = (error) => error instanceof Error &&
     typeof error.code === "string";
 export function fileContentCache(dir, fingerprint) {
-    // One file per tarball and label: content and provenance findings for the
-    // same tarball do not overwrite each other.
     const path = (integrity, label) => join(dir, `${createHash("sha256").update(`${fingerprint}\n${integrity.trim()}\n${label}`).digest("hex")}.json`);
     return {
         get(integrity, label) {
@@ -39,7 +35,6 @@ export function fileContentCache(dir, fingerprint) {
             if (typeof data !== "object" || data === null)
                 return undefined;
             const entry = data;
-            // The same tarball under another name or version is not reused.
             if (entry.label !== label ||
                 !Array.isArray(entry.findings) ||
                 !entry.findings.every(isFinding))
@@ -53,7 +48,6 @@ export function fileContentCache(dir, fingerprint) {
             const tmp = `${file}.${process.pid}.tmp`;
             try {
                 mkdirSync(dir, { recursive: true, mode: 0o700 });
-                // Write then rename, so a concurrent reader never sees half a file.
                 writeFileSync(tmp, JSON.stringify({ label, findings }), {
                     mode: 0o600,
                 });
@@ -66,7 +60,6 @@ export function fileContentCache(dir, fingerprint) {
                     rmSync(tmp, { force: true });
                 }
                 catch (cleanup) {
-                    // Best effort: a stray .tmp file is never read back.
                     if (!isFsError(cleanup))
                         throw cleanup;
                 }
@@ -74,7 +67,6 @@ export function fileContentCache(dir, fingerprint) {
         },
     };
 }
-/** A hash of croak's own code (the src/ or dist/ tree this module runs from). */
 export function codeFingerprint(root) {
     const hash = createHash("sha256");
     const walk = (dir) => {

package/dist/install/content.js

@@ -3,11 +3,6 @@ import { DEPENDENCY_INSTALL_SCRIPTS, lifecycleScriptWith, } from "../detectors/l
 import { obfuscationWith } from "../detectors/obfuscation.js";
 import { unscannedWith } from "../detectors/unscanned.js";
 import { isSuspiciousInDependency } from "../signals/code.js";
-/**
- * The repo detectors that make sense for a package's own files. Not
- * ide-autorun or git-config (they do nothing inside node_modules) and not
- * node-modules-present (bundled dependencies are normal in a tarball).
- */
 const DEPENDENCY_DETECTORS = [
     unscannedWith({ jsonIsData: true, downgradeInstalled: false }),
     lifecycleScriptWith({
@@ -15,19 +10,14 @@ const DEPENDENCY_DETECTORS = [
         scripts: DEPENDENCY_INSTALL_SCRIPTS,
         manifests: "package",
     }),
-    // Bundled dependencies (node_modules inside the tarball) are code npm
-    // installs and runs: judged like the package itself, never downgraded.
     hiddenCodeWith({ downgradeInstalled: false }),
     obfuscationWith({ downgradeInstalled: false }),
 ];
-/** Findings for one package's contents, with paths prefixed by `name@version/`. */
 export function contentFindings(label, snapshot) {
     const findings = DEPENDENCY_DETECTORS.flatMap((detect) => detect(snapshot)).map((finding) => ({
         ...finding,
         file: `${label}/${finding.file}`,
     }));
-    // Context, not a warning: prebuilt binaries are how esbuild, swc, sharp
-    // and TypeScript 7 ship. What runs them at install time is checked above.
     const natives = snapshot.entries.filter((e) => e.path.endsWith(".node"));
     const first = natives[0];
     if (first !== undefined) {

package/dist/install/detectors.js

@@ -3,7 +3,6 @@ const label = (change) => `${change.entry.name}@${change.entry.version ?? "?"}`;
 const what = (change) => change.kind === "changed"
     ? `updates ${change.entry.name} ${change.previousVersion} → ${change.entry.version}`
     : "is new";
-/** npm records hasInstallScript for packages with preinstall/install/postinstall (or binding.gyp). */
 export const installScripts = (changes) => changes
     .filter((c) => c.entry.hasInstallScript)
     .map((c) => ({
@@ -12,12 +11,9 @@ export const installScripts = (changes) => changes
     file: label(c),
     message: `${what(c)} and runs code at install time (preinstall/install/postinstall or a native build)`,
 }));
-/** Why a package is not a registry download, or undefined when it is one (registryTarball). */
 function sourceProblem(resolved, name, version) {
     const tarball = registryTarball(resolved);
     if (tarball !== undefined) {
-        // The lockfile's name decides which registry facts croak reads: the URL
-        // must be that package's own tarball, not another package's.
         const base = name.slice(name.lastIndexOf("/") + 1);
         return decodeURIComponent(tarball.pathname) ===
             `/${name}/-/${base}-${version ?? ""}.tgz`
@@ -37,31 +33,36 @@ function sourceProblem(resolved, name, version) {
         return `is downloaded over ${url.protocol.replace(":", "")}, not https`;
     return `comes from ${url.host}${url.username === "" ? "" : " with credentials in the URL"}, not ${REGISTRY}`;
 }
-/** Packages that do not come from the public npm registry over https. */
-export const source = (changes) => changes.flatMap((c) => {
-    if (c.entry.link) {
-        return [
-            {
-                ruleId: "install/source",
-                severity: "info",
-                file: label(c),
-                message: "is a workspace link, not a download",
-            },
-        ];
-    }
-    const problem = sourceProblem(c.entry.resolved, c.entry.name, c.entry.version);
-    return problem === undefined
-        ? []
-        : [
-            {
-                ruleId: "install/source",
-                severity: "warn",
-                file: label(c),
-                message: `${what(c)} and ${problem}`,
-            },
-        ];
-});
-/** A downloaded package without an integrity hash is not verified by npm. */
+export const source = (changes) => {
+    const folders = new Set(changes.map((c) => c.entry.path));
+    return changes.flatMap((c) => {
+        if (c.entry.link &&
+            c.entry.resolved !== undefined &&
+            folders.has(c.entry.resolved))
+            return [];
+        if (c.entry.link) {
+            return [
+                {
+                    ruleId: "install/source",
+                    severity: "info",
+                    file: label(c),
+                    message: "is a workspace link, not a download",
+                },
+            ];
+        }
+        const problem = sourceProblem(c.entry.resolved, c.entry.name, c.entry.version);
+        return problem === undefined
+            ? []
+            : [
+                {
+                    ruleId: "install/source",
+                    severity: "warn",
+                    file: label(c),
+                    message: `${what(c)} and ${problem}`,
+                },
+            ];
+    });
+};
 export const integrity = (changes) => changes
     .filter((c) => !c.entry.link &&
     c.entry.resolved !== undefined &&