@vola-trebla/croak 0.1.0 → 0.1.3

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;

package/dist/install/signature.js

@@ -3,12 +3,6 @@ const sha512Of = (integrity) => integrity
     ?.trim()
     .split(/\s+/)
     .find((hash) => hash.startsWith("sha512-"));
-/**
- * The registry's signature over this version (M7, D42). Broken blocks: a
- * known key's signature that does not verify, or a lockfile hash that is not
- * the one the registry signed. Missing or unverifiable warns: npm signs every
- * version, but a key rotation croak missed must not block every install.
- */
 export function signatureFindings(change, facts, keys = NPM_REGISTRY_KEYS) {
     const { entry } = change;
     const version = entry.version ?? "";
@@ -46,7 +40,6 @@ export function signatureFindings(change, facts, keys = NPM_REGISTRY_KEYS) {
             const locked = sha512Of(entry.integrity);
             const signed = sha512Of(facts.integrity);
             if (locked === undefined)
-                // No hash at all is install/integrity's finding.
                 return entry.integrity === undefined
                     ? []
                     : [

package/dist/install/tar.js

@@ -3,7 +3,6 @@ import { gunzipSync } from "node:zlib";
 export const DEFAULT_TAR_LIMITS = {
     maxUnpackedBytes: 256 * 1024 * 1024,
     maxEntries: 20_000,
-    // Bundles of a few MB are common in packages; reading them is cheap in memory.
     maxFileBytes: 8 * 1024 * 1024,
 };
 export class TarballError extends Error {
@@ -32,7 +31,6 @@ function verifyChecksum(block) {
     if (sum !== expected)
         throw new TarballError("header checksum mismatch: corrupted or crafted archive");
 }
-/** pax records: "<len> key=value\n" … */
 function paxRecords(data) {
     const records = new Map();
     let offset = 0;
@@ -55,9 +53,7 @@ function paxRecords(data) {
     }
     return records;
 }
-/** POSIX ustar ("ustar\0" + "00"): only then does node-tar read the name prefix. */
 const isUstar = (block) => block.toString("latin1", 257, 265) === "ustar\u000000";
-/** Drop the archive's top-level directory (`package/` in npm tarballs), as npm does. */
 function relative(path) {
     const slash = path.indexOf("/");
     const rest = slash === -1 ? "" : path.slice(slash + 1);
@@ -72,7 +68,6 @@ function relative(path) {
 }
 const FILE_TYPES = new Set(["0", "\0", "7"]);
 const LINK_TYPES = new Set(["1", "2"]);
-/** Devices, FIFOs and directories carry no code. */
 const IGNORED_TYPES = new Set(["3", "4", "5", "6"]);
 export function snapshotTarball(gzipped, limits = {}) {
     const { maxUnpackedBytes, maxEntries, maxFileBytes } = {
@@ -98,8 +93,6 @@ export function snapshotTarball(gzipped, limits = {}) {
     while (offset + BLOCK <= tar.length) {
         const block = tar.subarray(offset, offset + BLOCK);
         if (block.every((byte) => byte === 0)) {
-            // node-tar ends the archive only at two zero blocks in a row; a single
-            // one followed by more entries would hide them from croak alone.
             const next = tar.subarray(offset + BLOCK, offset + 2 * BLOCK);
             if (next.length === BLOCK && !next.every((byte) => byte === 0))
                 throw new TarballError("a zero block in the middle of the archive: entries after it would be hidden");
@@ -132,7 +125,7 @@ export function snapshotTarball(gzipped, limits = {}) {
             continue;
         }
         if (type === "K")
-            continue; // long link target: not a name
+            continue;
         if (type === "g") {
             const records = paxRecords(data);
             if (records.has("path") || records.has("size"))

package/dist/install/workspace.js

@@ -17,7 +17,6 @@ export function workspaceRoot(dir, manager, fs) {
                     manifest = JSON.parse(stripBom(fs.readFile(path)));
                 }
                 catch (error) {
-                    // npm fails on it too; it hides no install.
                     if (!(error instanceof SyntaxError))
                         throw error;
                 }

package/dist/install/yaml.js

@@ -1,12 +1,3 @@
-/**
- * A strict reader for the YAML that pnpm writes in pnpm-lock.yaml (M6, D38):
- * block mappings by indentation, plain and quoted scalars, flow mappings
- * `{a: b}` and flow sequences `[a, b]`, several documents split by `---`.
- * The lockfile comes from an untrusted repo, so anything outside that subset
- * (anchors, tags, block sequences, multi-line scalars) is a YamlError — the
- * check is then incomplete, never guessed at. Linear scanning; size, depth
- * and key counts are capped.
- */
 export class YamlError extends Error {
     constructor(message) {
         super(message);
@@ -18,7 +9,6 @@ export const DEFAULT_YAML_LIMITS = {
     maxDepth: 32,
     maxKeys: 2_000_000,
 };
-/** A scalar: 'single', "double" (simple escapes only) or plain. */
 function scalar(raw, where) {
     const text = raw.trim();
     if (text.startsWith("'")) {
@@ -41,7 +31,6 @@ function scalar(raw, where) {
         throw new YamlError(`${where}: unsupported YAML (${text.slice(0, 1)})`);
     return text;
 }
-/** Splits a flow collection's body at top-level commas, respecting quotes and nesting. */
 function splitFlow(body, where) {
     const parts = [];
     let depth = 0;
@@ -73,7 +62,6 @@ function splitFlow(body, where) {
         parts.push(last);
     return parts.map((p) => p.trim()).filter((p) => p !== "");
 }
-/** The index of the `: ` (or a final `:`) that ends a key, outside quotes and brackets. */
 function keyEnd(text) {
     let quote;
     let depth = 0;
@@ -121,7 +109,6 @@ function flowValue(raw, where, depth, limits) {
 }
 function parseDocument(lines, limits) {
     const root = {};
-    // Open mappings by indentation: the deepest last.
     const stack = [
         { indent: -1, map: root },
     ];
@@ -134,8 +121,6 @@ function parseDocument(lines, limits) {
             throw new YamlError(`${where}: tab character`);
         const indent = text.length - text.trimStart().length;
         const body = text.trim();
-        // A block sequence of scalars under a key (pnpm writes
-        // transitivePeerDependencies this way); nothing nested.
         if (body.startsWith("- ") || body === "-") {
             if (pending !== undefined && indent >= pending.indent) {
                 sequence = { indent, items: [] };
@@ -151,8 +136,6 @@ function parseDocument(lines, limits) {
             continue;
         }
         sequence = undefined;
-        // A flow collection on the line after its key (as Biome and Prettier
-        // write it) is that key's value; anywhere else it is not YAML pnpm writes.
         if (body.startsWith("{") || body.startsWith("[")) {
             if (pending === undefined || indent <= pending.indent)
                 throw new YamlError(`${where}: a flow collection without a key`);
@@ -162,7 +145,6 @@ function parseDocument(lines, limits) {
         }
         let opened = false;
         if (pending !== undefined) {
-            // The previous key opened a nested mapping (or is empty if this line is not deeper).
             if (indent > pending.indent) {
                 const child = {};
                 pending.parent[pending.key] = child;
@@ -203,10 +185,6 @@ function parseDocument(lines, limits) {
         pending.parent[pending.key] = {};
     return root;
 }
-/**
- * A line without its comment: a `#` outside quotes that starts the line or
- * follows whitespace (YAML's rule; `repo#commit` keeps its `#`).
- */
 function stripComment(line) {
     let quote;
     for (let i = 0; i < line.length; i++) {
@@ -223,7 +201,6 @@ function stripComment(line) {
     }
     return line;
 }
-/** How many flow brackets a line leaves open, outside quotes. */
 function openBrackets(line, start) {
     let depth = start;
     let quote;
@@ -241,14 +218,11 @@ function openBrackets(line, start) {
     }
     return depth;
 }
-/** Every document in the text (split at `---` lines), as plain objects. */
 export function parseYamlDocuments(text, limits = {}) {
     const all = { ...DEFAULT_YAML_LIMITS, ...limits };
     if (text.length > all.maxBytes)
         throw new YamlError(`larger than ${all.maxBytes} bytes`);
     const docs = [[]];
-    // A flow collection a formatter spread over several lines (Biome, Prettier)
-    // is joined back into one logical line, as YAML reads it.
     let open;
     const lines = text.split("\n");
     lines.forEach((raw, index) => {

package/dist/llm/client.js

@@ -1,16 +1,8 @@
 import { DEFAULT_MODEL, triage } from "./triage.js";
-/**
- * The model for `croak plan --llm`, loaded on first use (M5 review, D36). The
- * SDK is the one runtime dependency; importing it statically would load it,
- * and its own dependencies, for every croak command — the hook's steps run
- * on every agent command, outside the sandbox. This literal dynamic import is
- * the only one the invariant tripwire allows.
- */
 export function anthropicTriage(apiKey) {
     let ready;
     const load = async () => {
         const { default: Anthropic } = await import("@anthropic-ai/sdk");
-        // Well inside the hook's timeout; one retry for an overloaded API.
         const client = new Anthropic({ apiKey, timeout: 30_000, maxRetries: 1 });
         return (input) => triage(input, client);
     };

package/dist/llm/cost.js

@@ -7,7 +7,6 @@ export const PRICES = {
         longOutput: 2.5,
     },
 };
-/** Cost in USD, or undefined for a model without a known price. */
 export function costOf(model, usage) {
     const price = PRICES[model];
     if (price === undefined)
@@ -18,7 +17,6 @@ export function costOf(model, usage) {
     const long = price.longAbove !== undefined && prompt > price.longAbove;
     const input = long ? (price.longInput ?? price.input) : price.input;
     const output = long ? (price.longOutput ?? price.output) : price.output;
-    // Cache writes cost 1.25x and reads 0.1x the input price.
     const promptCost = usage.input_tokens * input +
         (usage.cache_creation_input_tokens ?? 0) * input * 1.25 +
         (usage.cache_read_input_tokens ?? 0) * input * 0.1;

package/dist/llm/diff.js

@@ -1,16 +1,7 @@
 import { posix } from "node:path";
 import { analyzeShell } from "../signals/shell.js";
 import { stripBom } from "../signals/text.js";
-/**
- * What the model sees (M5, D36): the added and changed lines between a
- * package's previous version and this one, most telling files first —
- * package.json, then the files its install scripts run, then other code —
- * within a character budget. Attacks add code, so removed lines are only
- * counted. A new package (no previous version) is shown as all added.
- */
-/** Room for the most telling files; triage cuts anything longer. */
 export const DIFF_BUDGET = 50_000;
-/** Minified bundles are one huge line; each shown line is cut to this. */
 const MAX_LINE = 400;
 const CODE = /\.(?:[cm]?[jt]sx?|json|sh|bash|py|gyp)$/;
 const SKIPPED = /\.(?:d\.[cm]?ts|map)$|(?:^|\/)(?:package-lock|npm-shrinkwrap)\.json$/;
@@ -18,7 +9,6 @@ const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall"];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Files the install scripts run, from the new version's package.json. */
 function installFiles(after) {
     const files = new Set();
     let manifest;
@@ -40,7 +30,6 @@ function installFiles(after) {
 const cut = (line) => line.length > MAX_LINE
     ? `${line.slice(0, MAX_LINE)}… (${line.length} characters)`
     : line;
-/** Lines of `after` that `before` does not have, with their line numbers. */
 function addedLines(before, after) {
     const old = new Map();
     for (const line of (before ?? "").split("\n"))
@@ -76,8 +65,6 @@ export function versionDiff(before, after, budget = DIFF_BUDGET) {
             continue;
         }
         const text = after.read(path) ?? "";
-        // A file the install scripts run is shown whole, changed or not: a payload
-        // can sit unchanged until a new version starts running it (M5 review).
         const runsAtInstall = install.has(path);
         const old = runsAtInstall ? undefined : before?.read(path);
         if (!runsAtInstall && old === text)
@@ -92,7 +79,6 @@ export function versionDiff(before, after, budget = DIFF_BUDGET) {
                 : `=== ${path} (changed: ${lines.length} line(s) added, ${removed} removed)`;
         const section = [head, ...lines].join("\n");
         if (used + section.length > budget) {
-            // A file that does not fit still gets its header, so the model knows it exists.
             notes.push(`${head.slice(4)}: not shown, over the size budget`);
             continue;
         }

package/dist/llm/plan-step.js

@@ -32,7 +32,6 @@ export async function llmStep(findings, changes, docs, llm, fetchOptions) {
         const left = maxBytes - downloaded;
         if (left <= 0)
             throw new RegistryError(`over the LLM step's ${maxBytes}-byte download budget`);
-        // fetchTarball stops reading at the cap, so the budget holds mid-download too.
         const data = await fetchTarball(url, integrity, {
             ...fetchOptions,
             maxBytes: Math.min(left, 100 * 1024 * 1024),
@@ -40,8 +39,6 @@ export async function llmStep(findings, changes, docs, llm, fetchOptions) {
         downloaded += data.length;
         return data;
     };
-    // Every copy with a warning: D35 keeps same name@version from different
-    // sources apart, and the warned one may not be the first (M5 review).
     for (const change of changes.filter((c) => warned.has(`${c.entry.name}@${c.entry.version ?? "?"}`))) {
         const { entry } = change;
         const label = `${entry.name}@${entry.version ?? "?"}`;
@@ -57,8 +54,6 @@ export async function llmStep(findings, changes, docs, llm, fetchOptions) {
         asked += 1;
         try {
             const after = snapshotTarball(await download(entry.resolved ?? "", entry.integrity));
-            // The baseline is what the project had: a new dependency is shown whole,
-            // not as a delta from the registry's previous release (M5 review).
             const previous = change.kind === "changed" ? change.previousVersion : undefined;
             const prevTarball = previous === undefined ? undefined : tarballOf(doc, previous);
             const before = prevTarball === undefined

package/dist/llm/select.js

@@ -1,12 +1,6 @@
 import { verdictRank } from "../verdict.js";
-/** name@version at the start of a finding's file: "x@1.0.0/setup.js" → "x@1.0.0". */
 const LABEL = /^((?:@[^/@]+\/)?[^/@][^/@]*@[^/]+)/;
 export const labelOf = (file) => LABEL.exec(file)?.[1];
-/**
- * Packages the rules warned about and did not block: the only ones the model
- * is asked about (D36). A block needs no second opinion; an allow is not
- * escalated, to keep the cost to the packages a human would look at anyway.
- */
 export function warnedPackages(findings) {
     const worst = new Map();
     for (const f of findings) {

package/dist/llm/triage.js

@@ -1,16 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { costOf } from "./cost.js";
-/**
- * One cheap, focused LLM call per package (M5, D36): Claude Haiku 5.5 reads
- * what changed between a package's previous version and this one, and says
- * whether the change looks malicious. Its answer can only escalate (see
- * escalate.ts). Package contents are untrusted input: they arrive inside a
- * per-call random boundary, the instructions say so, and the answer is held
- * to a JSON schema. Any failure is an LlmError, and croak falls back to its
- * deterministic verdict (invariant 3).
- */
 export const DEFAULT_MODEL = "claude-haiku-5-5";
-/** Diffs above this many characters are cut, and the model is told so. */
 export const MAX_DIFF_CHARS = 60_000;
 export class LlmError extends Error {
     constructor(message) {

package/dist/repo-report.js

@@ -1,10 +1,5 @@
 import { INCOMPLETE_ICON, SEVERITY_ICON, VERDICT_ICON } from "./ui.js";
-/** Bump when the JSON shape changes; agents and hooks depend on it. */
 export const REPORT_SCHEMA = 1;
-/**
- * What each verdict means, said out loud: neither green nor yellow is a
- * promise that the repo is safe to run.
- */
 const MEANING = {
     allow: "Nothing suspicious found. Not a guarantee: croak only knows what it checks.",
     warn: "Needs your attention: croak found behavior worth reviewing before you install or run anything. This is not a safe verdict.",
@@ -19,11 +14,6 @@ const MESSAGE_INDENT = " ".repeat(11);
 function sortFindings(findings) {
     return [...findings].sort((a, b) => ORDER[a.severity] - ORDER[b.severity] || a.file.localeCompare(b.file));
 }
-/**
- * Text from the scanned repo (commands, file names, hidden code) is hostile.
- * Escape C0/C1 control characters and bidi controls so it cannot move the
- * cursor, erase the 🔴 lines, or reorder the report itself (Trojan Source).
- */
 function isUnsafe(code) {
     return (code <= 0x1f ||
         (code >= 0x7f && code <= 0x9f) ||
@@ -71,7 +61,6 @@ export function renderScan(outcome, options) {
         footer: `${outcome.filesScanned} files scanned · ${Math.round(outcome.durationMs)} ms`,
     }, options);
 }
-/** The shared verdict layout for `croak repo` and `croak plan`. */
 export function renderVerdict(report, options) {
     const { emoji } = options;
     const status = emoji

package/dist/repo-snapshot.js

@@ -5,33 +5,21 @@ export const DEFAULT_LIMITS = {
     maxEntries: 100_000,
     maxDepth: 64,
 };
-/** The repo exceeds a safety limit. Callers fail closed: an incomplete scan is not a clean scan. */
 export class SnapshotLimitError extends Error {
     constructor(message) {
         super(message);
         this.name = "SnapshotLimitError";
     }
 }
-/** A file changed between listing and reading. Callers fail closed. */
 export class SnapshotIntegrityError extends Error {
     constructor(message) {
         super(message);
         this.name = "SnapshotIntegrityError";
     }
 }
-/** What git itself executes from inside a root .git directory. */
 const GIT_EXECUTED_FILES = ["config"];
 const GIT_HOOKS_DIR = "hooks";
-/**
- * Lists a repository without following symlinks. Symlinks and oversized files
- * are recorded (detectors may flag them) but never read. node_modules and
- * nested .git directories are walked on purpose: both are hiding places. The
- * root .git contributes only what git executes (config, hooks), not its
- * object store.
- */
 export function snapshotRepo(root, limits = {}) {
-    // O_NOFOLLOW is the read-time symlink guard; without it (Windows) we refuse
-    // rather than silently lose the protection.
     if (typeof constants.O_NOFOLLOW !== "number") {
         throw new Error("croak requires a POSIX platform (O_NOFOLLOW unavailable)");
     }
@@ -58,7 +46,6 @@ export function snapshotRepo(root, limits = {}) {
             identities.set(path, { dev: stats.dev, ino: stats.ino });
         }
     };
-    /** Streams one directory's entries instead of loading them all at once. */
     const eachEntry = (dir, visit) => {
         const handle = opendirSync(dir);
         try {
@@ -127,8 +114,6 @@ export function snapshotRepo(root, limits = {}) {
             const expected = identities.get(path);
             if (expected === undefined)
                 return undefined;
-            // O_NOFOLLOW refuses a final-component symlink; the inode check below
-            // catches any other swap, including an intermediate directory.
             const fd = openSync(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
             try {
                 const stats = fstatSync(fd, { bigint: true });
@@ -137,8 +122,6 @@ export function snapshotRepo(root, limits = {}) {
                     stats.ino !== expected.ino) {
                     throw new SnapshotIntegrityError(`${path} changed after it was listed`);
                 }
-                // Read at most one byte past the cap, so growth after listing is detected
-                // instead of silently read.
                 const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
                 let length = 0;
                 for (let n = readSync(fd, buffer, 0, buffer.length, 0); n > 0 && length < buffer.length; n = readSync(fd, buffer, length, buffer.length - length, length)) {

package/dist/scan.js

@@ -3,17 +3,12 @@ import { performance } from "node:perf_hooks";
 import { repoDetectors, scanRepo, } from "./detectors/index.js";
 import { SnapshotIntegrityError, SnapshotLimitError, snapshotRepo, } from "./repo-snapshot.js";
 import { aggregate } from "./verdict.js";
-/** The scan target is missing or not a directory: a usage error, not a verdict. */
 export class ScanTargetError extends Error {
     constructor(message) {
         super(message);
         this.name = "ScanTargetError";
     }
 }
-/**
- * Scans a repository directory. The root itself is chosen by the user and may
- * itself be a symbolic link, like /tmp on macOS; nothing inside it is followed.
- */
 export function scanRepoAt(root, options = {}) {
     if (statSync(root, { throwIfNoEntry: false })?.isDirectory() !== true) {
         throw new ScanTargetError(`${root} is not a directory`);

package/dist/signals/code.js

@@ -1,11 +1,3 @@
-// croak-invariants: pattern-data
-// Detector patterns and test inputs below are data, not code (D16).
-/**
- * Signals in JavaScript/TypeScript source that, in combination, indicate an
- * attack. A single signal is context, not evidence: install scripts fetch
- * binaries, build tools spawn processes. Patterns are deliberately narrow and
- * linear (checked by `pnpm redos`): they run on attacker-controlled text.
- */
 const LOAD = String.raw `(?:require\s*\(\s*|from\s+|import\s*\(\s*)["']`;
 const load = (modules) => new RegExp(`${LOAD}(?:node:)?(?:${modules})["']`);
 export const CODE_PATTERNS = [
@@ -31,9 +23,7 @@ export const CODE_PATTERNS = [
         label: "process library",
         pattern: load("execa|shelljs|cross-spawn"),
     },
-    // Not `$eval(` (Puppeteer and Playwright's page.$eval API).
     { signal: "eval", label: "eval", pattern: /(?<![\w$])eval\s*\)?\s*\(/ },
-    // Not `Function("return this")`, the old idiom for the global object.
     {
         signal: "eval",
         label: "Function constructor",
@@ -61,14 +51,9 @@ export const CODE_PATTERNS = [
         label: "private key",
         pattern: /\bid_(?:rsa|ed25519|ecdsa|dsa)\b/,
     },
-    // The whole environment, not process.env.PORT, a destructured
-    // `{ PORT } = process.env`, or `{ env: process.env }` handed to a child.
     {
         signal: "secrets",
         label: "whole process.env",
-        // passed whole to a call as its first or last argument (JSON.stringify,
-        // Object.entries, post(url, process.env)), spread into JSON.stringify, or
-        // walked with for…in. A spread for a child's env stays quiet.
         pattern: /[(,]\s*process\s*\.\s*env\s*\)|\(\s*process\s*\.\s*env\s*,|\bstringify\s*\(\s*\{\s*\.\.\.\s*process\s*\.\s*env\b|\bin\s+process\s*\.\s*env\b/,
     },
     { signal: "secrets", label: "home directory", pattern: /\bhomedir\s*\(/ },
@@ -82,14 +67,12 @@ export const CODE_PATTERNS = [
         label: "browser credentials",
         pattern: /\b(?:Login Data|Local State)\b|\bKeychains?\b/,
     },
-    // MetaMask's extension id: wallet stealers look for its storage directory.
     {
         signal: "secrets",
         label: "wallet",
         pattern: /\bnkbihfbeogaeaoehlefnkodbefgpgknn\b/,
     },
 ];
-/** Every pattern match, line by line. */
 export function codeSignals(text) {
     const hits = [];
     text.split("\n").forEach((lineText, index) => {
@@ -100,10 +83,6 @@ export function codeSignals(text) {
     });
     return hits;
 }
-/**
- * Network plus anything that reaches into the machine or hides code, or
- * eval of decoded data. Network alone is a warning, not an attack.
- */
 export function isSuspicious(signals) {
     const reach = signals.has("secrets") ||
         signals.has("process") ||
@@ -112,19 +91,11 @@ export function isSuspicious(signals) {
     return ((signals.has("network") && reach) ||
         (signals.has("eval") && signals.has("decode")));
 }
-/**
- * For dependency contents: native-binary installers (esbuild, swc, sharp)
- * legitimately download a binary, unpack it (String.fromCharCode on a tar
- * header), and spawn it at install time, so network plus process or decoding
- * alone only warns there. Network plus secrets or eval still blocks, as does
- * eval of decoded data.
- */
 export function isSuspiciousInDependency(signals) {
     const reach = signals.has("secrets") || signals.has("eval");
     return ((signals.has("network") && reach) ||
         (signals.has("eval") && signals.has("decode")));
 }
-/** "network (x.js:1), secrets (x.js:3)" — each signal once, at its first hit. */
 export function describeSignals(hits, file) {
     const first = new Map();
     for (const hit of hits)

package/dist/signals/git-config.js

@@ -1,12 +1,5 @@
-/**
- * A minimal git-config reader for .git/config and .gitmodules: sections,
- * `[name "subsection"]` and legacy `[name.sub]` headers, quoted values,
- * comments. Enough to see which settings make git run a command. Linear,
- * line by line; continuation lines are not supported.
- */
 const HEADER = /^\[\s*([A-Za-z0-9.-]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\]\s*(.*)$/;
 const KEY = /^([A-Za-z][A-Za-z0-9-]*)\s*(?:=\s*(.*))?$/;
-/** Removes a trailing comment outside quotes, then quotes and escapes. */
 function parseValue(raw) {
     let out = "";
     let quoted = false;