dependency-radar 0.8.0 → 0.9.0

package/dist/aggregator.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.aggregateData = aggregateData;
+exports.detectLocalExecutionSignals = detectLocalExecutionSignals;
+exports.collectPackageExecutionSignals = collectPackageExecutionSignals;
 const utils_1 = require("./utils");
 const license_1 = require("./license");
 const findings_1 = require("./findings");
@@ -287,6 +289,17 @@ function isWorkspacePackageNode(node, input) {
     }
     return false;
 }
+/**
+ * Builds a consolidated AggregatedData object for a dependency and audit scan.
+ *
+ * Combines package metadata, dependency graph structure, vulnerability summaries,
+ * import/usage data, outdated status, supply-chain signals, and per-dependency
+ * heuristics (license, execution/installation scripts, packaging, types support,
+ * links, peer requirements, and upgrade blockers) into a single summary object.
+ *
+ * @param input - All inputs and options required to perform aggregation (tool outputs, workspace/configuration, resolution paths, platform/runtime metadata, and optional policy overrides).
+ * @returns The assembled AggregatedData containing project metadata, environment info, per-dependency records, findings, and summary counts.
+ */
 async function aggregateData(input) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const pkg = input.pkgOverride || (await (0, utils_1.readPackageJson)(input.projectPath));
@@ -351,6 +364,7 @@ async function aggregateData(input) {
         const parentIds = Array.from(node.parents).sort();
         const origins = buildOrigins(rootCauses, parentIds, (_f = input.workspaceUsage) === null || _f === void 0 ? void 0 : _f.get(node.name), input.workspaceEnabled, MAX_TOP_ROOT_PACKAGES, MAX_TOP_PARENT_PACKAGES);
         const execution = packageInsights.execution;
+        const packaging = packageInsights.packaging;
         const id = node.key;
         const upgrade = buildUpgradeBlock(packageInsights);
         const outdated = resolveOutdated(node, direct, outdatedById, outdatedUnknownNames);
@@ -414,7 +428,8 @@ async function aggregateData(input) {
                 fanOut: node.children.size,
                 ...(subDeps ? { subDeps } : {})
             },
-            ...(execution ? { execution } : {})
+            ...(execution ? { execution } : {}),
+            ...(packaging ? { packaging } : {})
         };
     }
     const minRequiredMajor = deriveMinRequiredMajor(nodeEngineRanges);
@@ -1243,6 +1258,16 @@ function buildUpgradeBlock(insights) {
         ...(blocksNodeMajor ? { blocksNodeMajor: true } : {})
     };
 }
+/**
+ * Collects package metadata and bounded filesystem heuristics to produce insights used for dependency analysis.
+ *
+ * Gathers package.json data (description, engines, scripts, bin, dependencies, links), computes file-based stats when the package directory is available, detects TypeScript typing availability (bundled or DefinitelyTyped), counts required peer dependencies, and derives execution and packaging signals for use in aggregation and risk heuristics.
+ *
+ * @param resolvePaths - Array of filesystem roots to use when resolving package metadata.
+ * @param metaCache - Cache mapping package id (`name` or `name@version`) to previously loaded PackageMeta to avoid repeated resolution and parsing.
+ * @param statCache - Cache mapping package directory paths to previously computed PackageStats to avoid repeated filesystem scans.
+ * @returns A PackageInsights object containing deprecation, engine constraint, required peer count, optional fileCount, declared dependency maps, links, execution signals, optional packaging signals, and TypeScript types information.
+ */
 async function gatherPackageInsights(name, version, resolvePaths, metaCache, statCache) {
     var _a;
     const meta = await loadPackageMeta(name, resolvePaths, metaCache, version);
@@ -1277,7 +1302,8 @@ async function gatherPackageInsights(name, version, resolvePaths, metaCache, sta
     const hasDefinitelyTyped = await hasDefinitelyTypedPackage(name, resolvePaths, metaCache);
     const tsTypes = determineTypes(pkg, (stats === null || stats === void 0 ? void 0 : stats.hasDts) || false, hasDefinitelyTyped);
     const links = extractPackageLinks(pkg);
-    const execution = await deriveExecutionInfo(scripts, dir, stats);
+    const execution = await deriveExecutionInfo(pkg, scripts, dir, stats);
+    const packaging = derivePackagingInfo(pkg, stats);
     return {
         deprecated,
         nodeEngine,
@@ -1288,6 +1314,7 @@ async function gatherPackageInsights(name, version, resolvePaths, metaCache, sta
         declaredDependencies,
         links,
         execution,
+        ...(packaging ? { packaging } : {}),
         tsTypes
     };
 }
@@ -1321,6 +1348,12 @@ function countRequiredPeerDependencies(peerDependencies, peerDependenciesMeta) {
     }
     return count;
 }
+/**
+ * Detects whether a package.json `bin` field indicates at least one executable target.
+ *
+ * @param binField - The `bin` value from a package.json (string or object)
+ * @returns `true` if `binField` contains at least one non-empty string entry, `false` otherwise.
+ */
 function hasPackageBin(binField) {
     if (typeof binField === 'string')
         return binField.trim().length > 0;
@@ -1328,6 +1361,58 @@ function hasPackageBin(binField) {
         return false;
     return Object.values(binField).some((value) => typeof value === 'string' && value.trim().length > 0);
 }
+/**
+ * Normalize a package's `bundledDependencies` / `bundleDependencies` field into a canonical list.
+ *
+ * @param pkg - The package.json-like object to read bundling metadata from
+ * @returns A sorted list of bundled package names. Returns `['*']` when bundling is declared as `true`, or an empty array when no bundled dependencies are specified.
+ */
+function normalizeBundledDependencies(pkg) {
+    if ((pkg === null || pkg === void 0 ? void 0 : pkg.bundledDependencies) === true || (pkg === null || pkg === void 0 ? void 0 : pkg.bundleDependencies) === true) {
+        return ['*'];
+    }
+    const raw = Array.isArray(pkg === null || pkg === void 0 ? void 0 : pkg.bundledDependencies)
+        ? pkg.bundledDependencies
+        : Array.isArray(pkg === null || pkg === void 0 ? void 0 : pkg.bundleDependencies)
+            ? pkg.bundleDependencies
+            : [];
+    const entries = raw
+        .map((entry) => typeof entry === 'string' ? entry.trim() : '')
+        .filter((entry) => entry.length > 0);
+    return Array.from(new Set(entries)).sort();
+}
+/**
+ * Derives packaging-related signals from a package manifest and optional filesystem stats.
+ *
+ * @param pkg - The package.json object for the package being analyzed.
+ * @param stats - Optional file-statistics for the package directory (e.g., presence of shrinkwrap).
+ * @returns Packaging information containing `signals` (one or more of `bundled-dependencies` and `embedded-shrinkwrap`) and, when present, a `bundledDependencies` list; returns `undefined` when no packaging signals are detected.
+ */
+function derivePackagingInfo(pkg, stats) {
+    const signals = new Set();
+    const bundledDependencies = normalizeBundledDependencies(pkg);
+    if (bundledDependencies.length > 0)
+        signals.add('bundled-dependencies');
+    if (stats === null || stats === void 0 ? void 0 : stats.hasShrinkwrap)
+        signals.add('embedded-shrinkwrap');
+    const signalList = ['bundled-dependencies', 'embedded-shrinkwrap']
+        .filter((signal) => signals.has(signal));
+    if (signalList.length === 0)
+        return undefined;
+    return {
+        signals: signalList,
+        ...(bundledDependencies.length > 0 ? { bundledDependencies } : {})
+    };
+}
+/**
+ * Load and cache a package's package.json and its directory metadata.
+ *
+ * @param name - Package name to resolve
+ * @param resolvePaths - Ordered list of base paths to use when resolving the package.json
+ * @param cache - Map used to store and reuse previously loaded PackageMeta entries; keyed by `name` or `name@version`
+ * @param version - Optional version hint used when resolving a specific package variant
+ * @returns The `PackageMeta` containing the parsed `package.json` (`pkg`) and its directory (`dir`), or `undefined` if the package.json could not be resolved or read
+ */
 async function loadPackageMeta(name, resolvePaths, cache, version) {
     const cacheKey = version ? `${name}@${version}` : name;
     if (cache.has(cacheKey))
@@ -1366,12 +1451,33 @@ async function hasDefinitelyTypedPackage(name, resolvePaths, cache) {
     const meta = await loadPackageMeta(typesName, resolvePaths, cache);
     return Boolean(meta);
 }
+/**
+ * Collects filesystem-derived statistics for a package directory.
+ *
+ * Scans the package directory (best-effort) to detect whether the package
+ * contains TypeScript declaration files, native binary artifacts, a
+ * binding.gyp file, or an npm shrinkwrap file, and counts files. Nested
+ * dependency stores (node_modules) and .git directories are ignored; I/O
+ * errors are swallowed and the function returns whatever information could
+ * be gathered.
+ *
+ * @param dir - Filesystem path to the package directory to inspect.
+ * @param cache - Memoization map keyed by directory path; cached results are
+ *                returned when available and new results are stored here.
+ * @returns An object with:
+ *          - `hasDts`: `true` when any `.d.ts` files were found.
+ *          - `hasNativeBinary`: `true` when any `.node` binaries were found.
+ *          - `hasBindingGyp`: `true` when a `binding.gyp` file was found.
+ *          - `hasShrinkwrap`: `true` when an `npm-shrinkwrap.json` file was found.
+ *          - `fileCount`: total number of regular files encountered under the directory.
+ */
 async function calculatePackageStats(dir, cache) {
     if (cache.has(dir))
         return cache.get(dir);
     let hasDts = false;
     let hasNativeBinary = false;
     let hasBindingGyp = false;
+    let hasShrinkwrap = false;
     let fileCount = 0;
     async function walk(current) {
         const entries = await promises_1.default.readdir(current, { withFileTypes: true });
@@ -1393,6 +1499,8 @@ async function calculatePackageStats(dir, cache) {
                     hasNativeBinary = true;
                 if (entry.name === 'binding.gyp')
                     hasBindingGyp = true;
+                if (entry.name === 'npm-shrinkwrap.json')
+                    hasShrinkwrap = true;
             }
         }
     }
@@ -1402,7 +1510,7 @@ async function calculatePackageStats(dir, cache) {
     catch (err) {
         // best-effort; ignore inaccessible paths
     }
-    const result = { hasDts, hasNativeBinary, hasBindingGyp, fileCount };
+    const result = { hasDts, hasNativeBinary, hasBindingGyp, hasShrinkwrap, fileCount };
     cache.set(dir, result);
     return result;
 }
@@ -1493,7 +1601,16 @@ const EXECUTION_SIGNAL_ORDER = [
     'uses-ssh'
 ];
 const INSTALL_SCRIPT_MAX_BYTES = 200000;
+const LOCAL_SIGNAL_MAX_FILES_PER_PACKAGE = 24;
+const LOCAL_SIGNAL_MAX_BYTES_PER_FILE = 120000;
+const LOCAL_SIGNAL_MAX_PACKAGE_FILES = 2000;
 const COMPLEXITY_THRESHOLD = 12;
+/**
+ * Collects non-empty lifecycle hook commands from a package `scripts` object.
+ *
+ * @param scripts - The `scripts` section from a package.json (map of script names to values).
+ * @returns An object mapping each lifecycle hook found in `scripts` to its trimmed command; only hooks defined in `LIFECYCLE_HOOKS` and with non-empty string values are included.
+ */
 function collectLifecycleScripts(scripts) {
     const lifecycle = {};
     for (const hook of LIFECYCLE_HOOKS) {
@@ -1566,6 +1683,12 @@ function extractNodeScriptPath(command) {
     }
     return undefined;
 }
+/**
+ * Finds the first Node script file path referenced by lifecycle hook commands, checking hooks in predefined order.
+ *
+ * @param lifecycleScripts - Map of lifecycle hook names to their command strings; only hooks with non-empty commands are inspected.
+ * @returns The referenced script path (as found in a `node <script>` invocation) when present, `undefined` otherwise.
+ */
 function findReferencedInstallScript(lifecycleScripts) {
     for (const hook of LIFECYCLE_HOOKS) {
         const command = lifecycleScripts[hook];
@@ -1577,6 +1700,80 @@ function findReferencedInstallScript(lifecycleScripts) {
     }
     return undefined;
 }
+/**
+ * Normalize an input into a package-relative path by trimming whitespace and removing a leading `./` or `.\`.
+ *
+ * @param value - The input value to normalize (expected to be a path string)
+ * @returns The cleaned package-relative path, or `undefined` if the input is not a string, is empty after trimming, or appears to be an absolute/URL (contains `://`)
+ */
+function normalizePackageRelativePath(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const cleaned = value.trim().replace(/^[.][/\\]/, '');
+    if (!cleaned || cleaned.includes('://'))
+        return undefined;
+    return cleaned;
+}
+/**
+ * Collects normalized executable entry targets from a package `bin` field.
+ *
+ * @param binField - The package `bin` field; may be a string or an object mapping executable names to paths.
+ * @returns An array of normalized package-relative executable target paths, deduplicated and sorted.
+ */
+function packageBinTargets(binField) {
+    const targets = new Set();
+    const add = (value) => {
+        const normalized = normalizePackageRelativePath(value);
+        if (normalized)
+            targets.add(normalized);
+    };
+    if (typeof binField === 'string')
+        add(binField);
+    else if (binField && typeof binField === 'object') {
+        for (const value of Object.values(binField))
+            add(value);
+    }
+    return Array.from(targets).sort();
+}
+/**
+ * Collects candidate entry file paths from a package manifest.
+ *
+ * Supports `main`, `module`, and `exports` fields, flattening arrays and objects and normalizing package-relative paths.
+ *
+ * @param pkg - The package.json object to read entry targets from
+ * @returns An array of normalized package-relative entry paths, sorted; contains `index.js` when no entry fields are present
+ */
+function packageEntryTargets(pkg) {
+    const targets = new Set();
+    const add = (value) => {
+        if (typeof value === 'string') {
+            const normalized = normalizePackageRelativePath(value);
+            if (normalized)
+                targets.add(normalized);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach(add);
+            return;
+        }
+        if (value && typeof value === 'object') {
+            Object.values(value).forEach(add);
+        }
+    };
+    add(pkg === null || pkg === void 0 ? void 0 : pkg.main);
+    add(pkg === null || pkg === void 0 ? void 0 : pkg.module);
+    add(pkg === null || pkg === void 0 ? void 0 : pkg.exports);
+    if (targets.size === 0)
+        targets.add('index.js');
+    return Array.from(targets).sort();
+}
+/**
+ * Reads an install script file from a package directory if it is a regular file within size limits.
+ *
+ * @param scriptPath - The path to the script file as referenced in package scripts (resolved relative to `packageDir`)
+ * @param packageDir - The package root directory used to resolve and bound `scriptPath`
+ * @returns The file contents as UTF-8 text when the file exists inside `packageDir`, is a regular file, and its size is at most `INSTALL_SCRIPT_MAX_BYTES`; `undefined` otherwise.
+ */
 async function readInstallScriptFile(scriptPath, packageDir) {
     const resolvedDir = path_1.default.resolve(packageDir);
     const resolvedPath = path_1.default.resolve(resolvedDir, scriptPath);
@@ -1594,14 +1791,182 @@ async function readInstallScriptFile(scriptPath, packageDir) {
         return undefined;
     }
 }
+/**
+ * Checks whether a file path refers to an inspectable source file used for static analysis.
+ *
+ * @param filePath - The file path to test (relative or absolute)
+ * @returns `true` if the path ends with a JS/TS-related extension (`.js`, `.cjs`, `.mjs`, `.jsx`, `.ts`, `.tsx`) or has no extension, `false` otherwise.
+ */
+function isInspectableSourcePath(filePath) {
+    return /\.(?:js|cjs|mjs|jsx|ts|tsx)$/i.test(filePath) || path_1.default.extname(filePath) === '';
+}
+/**
+ * Detects whether a JavaScript-like file is likely minified or otherwise obfuscated.
+ *
+ * Uses filename and simple content heuristics to identify minified files.
+ *
+ * @param fileName - The file name or path (used to detect `.min.js/.min.cjs/.min.mjs` suffixes)
+ * @param text - The file contents to inspect
+ * @returns `true` if the file appears minified or obfuscated, `false` otherwise.
+ */
+function looksMinified(fileName, text) {
+    if (/\.min\.(?:js|cjs|mjs)$/i.test(fileName))
+        return true;
+    const lines = text.split(/\r?\n/);
+    if (lines.length <= 3 && text.length > 20000)
+        return true;
+    return lines.some((line) => line.length > 10000);
+}
+/**
+ * Determine whether a string appears to be readable text (not binary or overwhelmingly control-character data).
+ *
+ * Empty strings are considered text; presence of a NUL character marks the input as non-text. The function treats
+ * the input as text when the proportion of suspicious control or replacement characters is less than 1%.
+ *
+ * @param text - The string to evaluate
+ * @returns `true` if the input appears to be readable text, `false` otherwise.
+ */
+function looksTextLike(text) {
+    if (text.includes('\0'))
+        return false;
+    if (text.length === 0)
+        return true;
+    const suspicious = (text.match(/[\uFFFD\x00-\x08\x0E-\x1F]/g) || []).length;
+    return suspicious / text.length < 0.01;
+}
+/**
+ * Detects whether a text blob appears to be JavaScript or Node.js source.
+ *
+ * @param text - The text to inspect for JavaScript/Node indicators
+ * @returns `true` if the text contains common JavaScript or Node.js source markers (shebang with `node`, `require(`, `import`, `module.exports`, or `process.`), `false` otherwise
+ */
+function looksJavaScriptLike(text) {
+    return (/^#!.*\bnode\b/.test(text) ||
+        /\brequire\s*\(/.test(text) ||
+        /\bimport\s+/.test(text) ||
+        /\bmodule\.exports\b/.test(text) ||
+        /\bprocess\./.test(text));
+}
+/**
+ * Read and return the text of a package-relative source file when it is safe and useful to inspect.
+ *
+ * Attempts to resolve and read `filePath` inside `packageDir` and returns the file contents only if the file:
+ * - resides within `packageDir`,
+ * - matches the allowed inspectable source path patterns,
+ * - is a regular file whose size does not exceed `maxBytes`,
+ * - appears to be text (and, for extensionless files, looks like JavaScript),
+ * - does not appear minified or otherwise obfuscated.
+ *
+ * @param filePath - Path to the candidate file relative to the package directory
+ * @param packageDir - Absolute path of the package root to constrain reads
+ * @param maxBytes - Maximum number of bytes to read from the file (per-file size limit)
+ * @returns The file content when it is inspectable under the above constraints, `undefined` otherwise
+ */
+async function readInspectablePackageFile(filePath, packageDir, maxBytes = LOCAL_SIGNAL_MAX_BYTES_PER_FILE) {
+    const resolvedDir = path_1.default.resolve(packageDir);
+    const resolvedPath = path_1.default.resolve(resolvedDir, filePath);
+    if (!resolvedPath.startsWith(resolvedDir + path_1.default.sep))
+        return undefined;
+    if (!isInspectableSourcePath(resolvedPath))
+        return undefined;
+    try {
+        const stat = await promises_1.default.stat(resolvedPath);
+        if (!stat.isFile())
+            return undefined;
+        if (stat.size > maxBytes)
+            return undefined;
+        const text = await promises_1.default.readFile(resolvedPath, 'utf8');
+        if (!looksTextLike(text))
+            return undefined;
+        if (path_1.default.extname(resolvedPath) === '' && !looksJavaScriptLike(text))
+            return undefined;
+        if (looksMinified(resolvedPath, text))
+            return undefined;
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Collects a bounded list of inspectable source file paths inside a package directory.
+ *
+ * Traverses the package tree (skipping symlinks and common non-source directories) and returns
+ * a sorted array of package-relative paths for files considered inspectable.
+ *
+ * @param packageDir - Absolute path to the package directory to scan
+ * @param maxFiles - Maximum number of inspectable file paths to return
+ * @param maxPackageFiles - Maximum number of files to examine within the package (counts all files visited)
+ * @returns A sorted array of relative file paths (relative to `packageDir`) for inspectable source files
+ */
+async function collectBoundedInspectableFiles(packageDir, maxFiles, maxPackageFiles) {
+    const out = [];
+    let seen = 0;
+    async function walk(current) {
+        if (out.length >= maxFiles || seen >= maxPackageFiles)
+            return;
+        const entries = await promises_1.default.readdir(current, { withFileTypes: true }).catch(() => []);
+        entries.sort((a, b) => a.name.localeCompare(b.name, 'en', { numeric: true, sensitivity: 'base' }));
+        for (const entry of entries) {
+            if (out.length >= maxFiles || seen >= maxPackageFiles)
+                return;
+            const full = path_1.default.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'test' || entry.name === 'tests' || entry.name === 'docs')
+                    continue;
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                seen += 1;
+                if (isInspectableSourcePath(full)) {
+                    out.push(path_1.default.relative(packageDir, full));
+                }
+            }
+        }
+    }
+    await walk(packageDir);
+    return out.sort();
+}
+/**
+ * Identify execution-related static signals present in a block of source or script text.
+ *
+ * @param text - The file or lifecycle script text to analyze for execution signals
+ * @returns An ordered array of distinct execution signals detected in `text`, prioritized according to the canonical execution-signal ordering
+ */
+function detectLocalExecutionSignals(text) {
+    const signals = new Set();
+    detectFileSignals(text, signals);
+    return EXECUTION_SIGNAL_ORDER.filter((signal) => signals.has(signal));
+}
+/**
+ * Checks whether the given text matches any regular expression in the provided list.
+ *
+ * @param text - The string to test against the patterns
+ * @param patterns - Array of `RegExp` objects to test
+ * @returns `true` if at least one pattern matches `text`, `false` otherwise.
+ */
 function textHasAny(text, patterns) {
     return patterns.some((pattern) => pattern.test(text));
 }
+/**
+ * Detects install-time script characteristics from a text blob and adds matching execution signals to the provided set.
+ *
+ * Examines the input text with heuristics for common patterns and adds any of the following `ExecutionSignal` values to `signals` when matched:
+ * - `network-access` — patterns that fetch remote resources (curl, wget, http(s), fetch, axios, net.connect, dns, etc.).
+ * - `reads-env` — access to environment variables or printenv-style usage.
+ * - `reads-home` — references to user home paths or APIs returning the home directory.
+ * - `uses-ssh` — references to SSH-related files, agents, or SSH/git configuration.
+ *
+ * @param text - The script or file text to statically inspect for indicative patterns.
+ * @param signals - A mutable Set that will receive any detected execution signals.
+ */
 function detectScriptSignals(text, signals) {
     // Signals are derived from static text inspection only: no code execution and no import walking.
     // They are NOT malware detection; they merely highlight review-worthy install-time behavior.
     // "network-access" surfaces install scripts that fetch remote resources (review for expected downloads; does NOT imply exfiltration).
-    if (textHasAny(text, [/\bcurl\b/i, /\bwget\b/i, /https?:\/\//i, /\bfetch\s*\(/i, /\baxios\b/i, /node-fetch/i])) {
+    if (textHasAny(text, [/\bcurl\b/i, /\bwget\b/i, /https?:\/\//i, /\bfetch\s*\(/i, /\baxios\b/i, /node-fetch/i, /\bhttps?\.request\s*\(/, /\bnet\.connect\s*\(/, /\bdns\./])) {
         signals.add('network-access');
     }
     // "reads-env" highlights environment access (does NOT imply exfiltration).
@@ -1609,11 +1974,11 @@ function detectScriptSignals(text, signals) {
         signals.add('reads-env');
     }
     // "reads-home" highlights access to user home paths (does NOT imply credential theft).
-    if (textHasAny(text, [/\$HOME\b/, /process\.env\.HOME\b/, /os\.homedir\s*\(/, /~\//])) {
+    if (textHasAny(text, [/\$HOME\b/, /process\.env\.HOME\b/, /\bUSERPROFILE\b/, /os\.homedir\s*\(/, /~\//, /\/Users\//, /\/home\//])) {
         signals.add('reads-home');
     }
     // "uses-ssh" flags access to SSH-related paths (does NOT imply key exfiltration).
-    if (textHasAny(text, [/\.ssh\b/i, /id_rsa\b/i, /known_hosts\b/i, /\.npmrc\b/i])) {
+    if (textHasAny(text, [/\.ssh\b/i, /id_rsa\b/i, /known_hosts\b/i, /ssh-key/i, /ssh-agent/i, /GIT_SSH_COMMAND\b/, /\.npmrc\b/i])) {
         signals.add('uses-ssh');
     }
 }
@@ -1634,6 +1999,14 @@ function isObfuscated(text) {
     }
     return /[A-Za-z0-9+/]{800,}={0,2}/.test(text);
 }
+/**
+ * Detects static execution- and obfuscation-related signals from a JavaScript file's text and adds them to `signals`.
+ *
+ * Scans the provided source text for review cues such as script-level indicators, dynamic code execution APIs, child-process usage, explicit encoding patterns, and signs of obfuscation/minification. Matches are added to the supplied `signals` set; the function does not return a value and does not imply malicious intent by itself.
+ *
+ * @param text - The source text of a JavaScript file to analyze.
+ * @param signals - A mutable set that will be populated with discovered `ExecutionSignal` values.
+ */
 function detectFileSignals(text, signals) {
     // Signals from a single directly-referenced JS file (no execution, no imports, no deep scanning).
     // These are review cues only and do NOT imply malicious intent.
@@ -1643,7 +2016,7 @@ function detectFileSignals(text, signals) {
         signals.add('dynamic-exec');
     }
     // "child-process" flags process spawning (does NOT imply abuse).
-    if (textHasAny(text, [/\bchild_process\.exec\b/, /\bspawn\s*\(/, /\bexecSync\s*\(/])) {
+    if (textHasAny(text, [/\bchild_process\b/, /\bexec\s*\(/, /\bspawn\s*\(/, /\bexecFile\s*\(/, /\bexecSync\s*\(/, /\bspawnSync\s*\(/])) {
         signals.add('child-process');
     }
     // "encoding" flags explicit encode/decode flows (does NOT imply obfuscation intent).
@@ -1655,46 +2028,116 @@ function detectFileSignals(text, signals) {
         signals.add('obfuscated');
     }
 }
+/**
+ * Classifies execution-related risk level for a package based on lifecycle scripts, detected signals, and script complexity.
+ *
+ * @param hasScripts - Whether the package defines any lifecycle scripts
+ * @param hasSignals - Whether static analysis detected execution-related signals (network, child-process, dynamic execution, etc.)
+ * @param highComplexity - Whether the package's lifecycle scripts exceed the complexity threshold
+ * @param hooks - Lifecycle hooks present (note: `install` or `postinstall` count as install-time hooks)
+ * @returns `'red'` when scripts are present and either execution signals exist or scripts are highly complex on an install-time hook; `'amber'` otherwise.
+ */
 function determineExecutionRisk(hasScripts, hasSignals, highComplexity, hooks) {
     const hasInstallHook = hooks.includes('install') || hooks.includes('postinstall');
     if (hasScripts && (hasSignals || (highComplexity && hasInstallHook)))
         return 'red';
     return 'amber';
 }
-async function deriveExecutionInfo(scripts, packageDir, stats) {
+/**
+ * Collects execution-related static signals from a package's likely entry and inspectable source files using bounded, best-effort inspection.
+ *
+ * This inspects candidate entry points (e.g., `bin`, `main`, `module`, `exports`) plus a bounded set of other inspectable files, applies static detectors, and returns the detected execution signals in the canonical ordering.
+ *
+ * @param pkg - The package.json object for the package being inspected.
+ * @param packageDir - The package filesystem directory to read files from; when `undefined`, the function returns an empty array.
+ * @param options.maxFiles - Maximum number of files to inspect (default: LOCAL_SIGNAL_MAX_FILES_PER_PACKAGE).
+ * @param options.maxBytesPerFile - Maximum bytes to read per file (default: LOCAL_SIGNAL_MAX_BYTES_PER_FILE).
+ * @param options.maxPackageFiles - Maximum number of candidate package files to enumerate before selecting up to `maxFiles` for inspection (default: LOCAL_SIGNAL_MAX_PACKAGE_FILES).
+ * @returns An array of detected `ExecutionSignal` values, ordered according to the canonical `EXECUTION_SIGNAL_ORDER`. Empty if no signals are found.
+ */
+async function collectPackageExecutionSignals(pkg, packageDir, options = {}) {
+    var _a, _b, _c;
+    if (!packageDir)
+        return [];
+    const maxFiles = (_a = options.maxFiles) !== null && _a !== void 0 ? _a : LOCAL_SIGNAL_MAX_FILES_PER_PACKAGE;
+    const maxBytesPerFile = (_b = options.maxBytesPerFile) !== null && _b !== void 0 ? _b : LOCAL_SIGNAL_MAX_BYTES_PER_FILE;
+    const maxPackageFiles = (_c = options.maxPackageFiles) !== null && _c !== void 0 ? _c : LOCAL_SIGNAL_MAX_PACKAGE_FILES;
+    const candidateFiles = new Set();
+    for (const file of [...packageBinTargets(pkg === null || pkg === void 0 ? void 0 : pkg.bin), ...packageEntryTargets(pkg)]) {
+        candidateFiles.add(file);
+    }
+    for (const file of await collectBoundedInspectableFiles(packageDir, maxFiles, maxPackageFiles)) {
+        candidateFiles.add(file);
+        if (candidateFiles.size >= maxFiles)
+            break;
+    }
+    const signals = new Set();
+    let inspected = 0;
+    for (const file of candidateFiles) {
+        if (inspected >= maxFiles)
+            break;
+        const text = await readInspectablePackageFile(file, packageDir, maxBytesPerFile);
+        if (!text)
+            continue;
+        inspected += 1;
+        detectFileSignals(text, signals);
+    }
+    return EXECUTION_SIGNAL_ORDER.filter((signal) => signals.has(signal));
+}
+/**
+ * Derives install-time execution signals, script metadata, and a consolidated execution risk for a package.
+ *
+ * Analyzes lifecycle hooks, referenced install scripts, native-build indicators, and bounded package file inspection to produce ordered execution signals, an execution complexity score when applicable, and a risk classification. Returns undefined when no meaningful execution signals, scripts, or native indicators are present.
+ *
+ * @param pkg - The package.json object for the dependency; used to locate entry points and candidate files for inspection.
+ * @param scripts - The package's lifecycle `scripts` map (from package.json).
+ * @param packageDir - Absolute path to the package directory used for reading referenced install scripts and package files; when undefined, file-based inspection is skipped.
+ * @param stats - Optional PackageStats containing file-based heuristics (e.g., `hasNativeBinary`, `hasBindingGyp`) used as native indicators.
+ * @returns An execution record containing:
+ *  - `risk`: computed execution risk,
+ *  - optional `native`: `true` when native-build indicators are present,
+ *  - optional `signals`: ordered list of detected execution signals,
+ *  - optional `scripts`: metadata about lifecycle hooks including `hooks`, optional `complexity`, and optional script-only `signals`.
+ */
+async function deriveExecutionInfo(pkg, scripts, packageDir, stats) {
     const lifecycleScripts = collectLifecycleScripts(scripts);
     const hooks = LIFECYCLE_HOOKS.filter((hook) => Boolean(lifecycleScripts[hook]));
     const hasScripts = hooks.length > 0;
     const hasNative = Boolean((stats === null || stats === void 0 ? void 0 : stats.hasNativeBinary) || (stats === null || stats === void 0 ? void 0 : stats.hasBindingGyp) || scriptsContainNativeTooling(scripts));
-    if (!hasScripts && !hasNative)
-        return undefined;
-    const signals = new Set();
+    const scriptSignals = new Set();
     const combinedScripts = hooks.map((hook) => lifecycleScripts[hook]).join('\n');
     if (combinedScripts) {
-        detectScriptSignals(combinedScripts, signals);
+        detectScriptSignals(combinedScripts, scriptSignals);
     }
     if (hasScripts && packageDir) {
         const referencedScript = findReferencedInstallScript(lifecycleScripts);
         if (referencedScript) {
             const fileContent = await readInstallScriptFile(referencedScript, packageDir);
             if (fileContent) {
-                detectFileSignals(fileContent, signals);
+                detectFileSignals(fileContent, scriptSignals);
             }
         }
     }
+    const packageSignals = await collectPackageExecutionSignals(pkg, packageDir);
+    const allSignals = new Set([...scriptSignals, ...packageSignals]);
     const complexityScore = hasScripts ? scoreLifecycleScripts(lifecycleScripts) : 0;
     const complexity = complexityScore >= COMPLEXITY_THRESHOLD ? complexityScore : undefined;
-    const signalList = EXECUTION_SIGNAL_ORDER.filter((signal) => signals.has(signal));
+    const scriptSignalList = EXECUTION_SIGNAL_ORDER.filter((signal) => scriptSignals.has(signal));
+    const signalList = EXECUTION_SIGNAL_ORDER.filter((signal) => allSignals.has(signal));
+    if (!hasScripts && !hasNative && signalList.length === 0)
+        return undefined;
     const scriptsInfo = {
         hooks,
         ...(complexity !== undefined ? { complexity } : {}),
-        ...(signalList.length > 0 ? { signals: signalList } : {})
+        ...(scriptSignalList.length > 0 ? { signals: scriptSignalList } : {})
     };
     const risk = determineExecutionRisk(hasScripts, signalList.length > 0, complexity !== undefined, hooks);
     const execution = { risk };
     // Native is surface description only; not a behavioral signal.
     if (hasNative)
         execution.native = true;
+    if (signalList.length > 0)
+        execution.signals = signalList;
     if (hasScripts)
         execution.scripts = scriptsInfo;
     return execution;