fad-checker 2.1.2 → 2.2.1

package/lib/json-export.js

@@ -65,10 +65,17 @@ const SEV = ["critical", "high", "medium", "low", "none", "unknown"];
  */
 function buildFindings(payload = {}) {
 	const {
-		cveMatches = [], retireMatches = [], eolResults = [], obsoleteResults = [],
+		cveMatches = [], retireMatches = [], vendoredJsInventory = [], eolResults = [], obsoleteResults = [],
 		outdatedResults = [], licenseResults = null, resolvedDeps, projectInfo = {}, toolVersion = "0",
 	} = payload;
 
+	const { buildInventory } = require("./unmanaged");
+	const unmanaged = resolvedDeps ? buildInventory(resolvedDeps) : [];
+
+	const { buildEmbeddedInventory } = require("./embedded");
+	const embeddedMatches = cveMatches.filter(m => m.dep?.provenance === "embedded");
+	const embedded = resolvedDeps ? buildEmbeddedInventory(resolvedDeps, embeddedMatches) : [];
+
 	const sevCounts = Object.fromEntries(SEV.map(s => [s, 0]));
 	let kev = 0;
 	for (const m of cveMatches) {
@@ -90,14 +97,20 @@ function buildFindings(payload = {}) {
 			outdated: outdatedResults.length,
 			licensesFlagged: licenseResults?.flagged?.length || 0,
 			vendored: retireMatches.length,
+			unmanaged: unmanaged.length,
+			embedded: embedded.length,
+			vendoredJs: vendoredJsInventory.length,
 			suppressed: cveMatches.filter(m => m.suppressed).length,
 		},
 		cve: cveMatches.map(cveFinding),
 		vendored: retireMatches.map(cveFinding),
-		eol: eolResults.map(e => ({ product: e.product, eol: e.eol, dep: depBrief(e.dep) })),
+		eol: eolResults.map(e => ({ product: e.product, productSlug: e.productSlug || null, via: e.via || null, viaKey: e.viaKey || null, eol: e.eol, dep: depBrief(e.dep) })),
 		obsolete: obsoleteResults.map(o => ({ reason: o.reason || null, replacement: o.replacement || null, source: o.source || null, dep: depBrief(o.dep) })),
 		outdated: outdatedResults.map(o => ({ latest: o.latest, releaseDate: o.releaseDate || null, dep: depBrief(o.dep) })),
 		licenses: (licenseResults?.assessed || []).map(e => ({ category: e.category, licenses: e.ids.concat(e.raw), source: e.source || null, dep: depBrief(e.dep) })),
+		unmanaged,
+		embedded,
+		vendoredJs: vendoredJsInventory,
 	};
 }
 

package/lib/options-env.js

@@ -0,0 +1,113 @@
+/**
+ * lib/options-env.js — layered option resolution.
+ *
+ * Layers (highest → lowest): CLI flags > config file (--config / ./.fad-env.json,
+ * JSON) > FAD_CHECKER_ENV (a CLI-flag string) > global ~/.fad-checker/config.json
+ * > commander defaults. Scalar options follow precedence; `registries` are unioned
+ * elsewhere (lib/registries.js). The source flag has aliases (src/source).
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const { Command } = require("commander");
+
+/** Quote/escape-aware shell-ish tokenizer (single+double quotes, backslash). */
+function tokenize(str) {
+	const out = [];
+	let cur = "", q = null, esc = false, has = false;
+	for (const ch of String(str)) {
+		if (esc) { cur += ch; esc = false; has = true; continue; }
+		if (ch === "\\" && q !== "'") { esc = true; continue; }
+		if (q) { if (ch === q) q = null; else cur += ch; has = true; continue; }
+		if (ch === '"' || ch === "'") { q = ch; has = true; continue; }
+		if (/\s/.test(ch)) { if (has) { out.push(cur); cur = ""; has = false; } continue; }
+		cur += ch; has = true;
+	}
+	if (has) out.push(cur);
+	return out;
+}
+
+function loadConfigFile(p) {
+	const raw = fs.readFileSync(p, "utf8");
+	try { return JSON.parse(raw); }
+	catch (e) { throw new Error(`invalid JSON in config file ${p}: ${e.message}`); }
+}
+
+/** Map `source` → `src` (src wins if both present). Returns a NEW object. */
+function normalizeSource(obj) {
+	const o = { ...obj };
+	if (o.source != null && o.src == null) o.src = o.source;
+	delete o.source;
+	return o;
+}
+
+/**
+ * Parse a CLI-flag string into { options, repos } using a throwaway clone of the
+ * real program. Only options whose source !== "default" are returned, so unset
+ * flags don't clobber higher layers. `repos` (variadic --repo) returned separately.
+ */
+function parseEnvFlags(str, program) {
+	const tokens = tokenize(str);
+	if (!tokens.length) return { options: {}, repos: [] };
+	const clone = new Command();
+	clone.exitOverride().allowUnknownOption(true).configureOutput({ writeErr() {}, writeOut() {} });
+	for (const o of program.options) clone.addOption(o);
+	try { clone.parse(tokens, { from: "user" }); } catch { /* tolerate */ }
+	const all = clone.opts();
+	const options = {};
+	for (const name of Object.keys(all)) {
+		const src = clone.getOptionValueSource(name);
+		if (src && src !== "default") options[name] = all[name];
+	}
+	const repos = Array.isArray(options.repo) ? options.repo : [];
+	delete options.repo;
+	return { options: normalizeSource(options), repos };
+}
+
+/** Resolve { fileLayer, envLayer, envRepos }. */
+function loadLayers({ cwd = process.cwd(), configPath = null, envStr = process.env.FAD_CHECKER_ENV, program = null } = {}) {
+	let fileLayer = {};
+	const chosen = configPath || path.join(cwd, ".fad-env.json");
+	if (configPath) fileLayer = loadConfigFile(chosen);
+	else if (fs.existsSync(chosen)) fileLayer = loadConfigFile(chosen);
+	fileLayer = normalizeSource(fileLayer || {});
+	let envLayer = {}, envRepos = [];
+	if (envStr && program) {
+		// If FAD_CHECKER_ENV points to a readable file, treat its content as flags too.
+		let s = envStr;
+		try { if (fs.existsSync(envStr) && fs.statSync(envStr).isFile()) s = fs.readFileSync(envStr, "utf8"); } catch { /* inline */ }
+		const parsed = parseEnvFlags(s, program);
+		envLayer = parsed.options; envRepos = parsed.repos;
+	}
+	return { fileLayer, envLayer, envRepos };
+}
+
+/**
+ * Merge layers onto the parsed program. A file/env/global value fills an option
+ * ONLY when the CLI did not set it (source default/undefined). Order: file > env
+ * > global. Returns the effective options object (a copy of program.opts()).
+ */
+function applyLayers(program, layers = {}, globalStore = {}) {
+	const eff = normalizeSource(program.opts());
+	const fileLayer = normalizeSource(layers.fileLayer || {});
+	const envLayer = normalizeSource(layers.envLayer || {});
+	const cliSet = name => {
+		const s = program.getOptionValueSource(name);
+		return s && s !== "default";
+	};
+	const candidates = new Set([...Object.keys(fileLayer), ...Object.keys(envLayer), ...Object.keys(globalStore || {})]);
+	candidates.delete("registries");  // unioned separately
+	candidates.delete("excludePath"); // unioned separately
+	candidates.delete("source");
+	for (const name of candidates) {
+		if (cliSet(name)) continue; // CLI wins
+		if (name in fileLayer) eff[name] = fileLayer[name];
+		else if (name in envLayer) eff[name] = envLayer[name];
+		else if (globalStore && name in globalStore) eff[name] = globalStore[name];
+	}
+	return eff;
+}
+
+module.exports = { tokenize, loadConfigFile, normalizeSource, parseEnvFlags, loadLayers, applyLayers };

package/lib/outdated.js

@@ -42,6 +42,13 @@ function isEolCacheFresh(maxAge = EOL_CACHE_MAX_AGE_MS) {
 
 // -------- EOL via endoflife.date --------
 
+// Tag the matched mapping entry with HOW it matched (which rule + which key), so
+// the report can show where an EOL verdict comes from. Returns a COPY — the shared
+// EOL_MAPPING objects must never be mutated (they're reused across deps).
+function withOrigin(entry, via, viaKey) {
+	return entry ? { ...entry, via, viaKey } : null;
+}
+
 function findEolProduct(dep) {
 	// npm packages — and WebJars, which are client-side JS shipped as Maven
 	// artifacts — resolve by JS library name, not Maven coordinate. npm deps
@@ -49,36 +56,39 @@ function findEolProduct(dep) {
 	// first (org.webjars:angularjs → "angularjs", org.webjars.npm:angular__core
 	// → "@angular/core"). The npm package literally named "angular" is AngularJS
 	// 1.x; modern Angular is the @angular/* scope — hence the name vs. scope maps.
+	const isWebjar = dep.ecosystem !== "npm" && webjarToNpm(dep) != null;
 	const npmName = dep.ecosystem === "npm" ? (dep.artifactId || "") : webjarToNpm(dep)?.name;
 	if (npmName != null) {
 		const byName = EOL_MAPPING.by_npm_name?.[npmName];
-		if (byName) return byName;
+		if (byName) return withOrigin(byName, isWebjar ? "webjar" : "npm-name", npmName);
 		const scopes = Object.keys(EOL_MAPPING.by_npm_scope || {})
 			.sort((a, b) => b.length - a.length);
 		for (const s of scopes) {
-			if (npmName.startsWith(s)) return EOL_MAPPING.by_npm_scope[s];
+			if (npmName.startsWith(s)) return withOrigin(EOL_MAPPING.by_npm_scope[s], isWebjar ? "webjar" : "npm-scope", s);
 		}
 		return null;
 	}
 	if (dep.ecosystem === "composer") {
 		const full = `${dep.namespace || dep.groupId || ""}/${dep.name || dep.artifactId}`.toLowerCase();
-		return EOL_MAPPING.by_composer_name?.[full] || null;
+		return withOrigin(EOL_MAPPING.by_composer_name?.[full], "composer-name", full);
 	}
 	if (dep.ecosystem === "pypi") {
-		return EOL_MAPPING.by_pypi_name?.[(dep.name || dep.artifactId || "").toLowerCase()] || null;
+		const k = (dep.name || dep.artifactId || "").toLowerCase();
+		return withOrigin(EOL_MAPPING.by_pypi_name?.[k], "pypi-name", k);
 	}
 	if (dep.ecosystem === "nuget") {
-		return EOL_MAPPING.by_nuget_name?.[(dep.name || dep.artifactId || "").toLowerCase()] || null;
+		const k = (dep.name || dep.artifactId || "").toLowerCase();
+		return withOrigin(EOL_MAPPING.by_nuget_name?.[k], "nuget-name", k);
 	}
 	const key = `${dep.groupId}:${dep.artifactId}`;
 	const direct = EOL_MAPPING.by_group_artifact?.[key];
-	if (direct) return direct;
+	if (direct) return withOrigin(direct, "group-artifact", key);
 	// Match longest groupId prefix
 	const prefixes = Object.keys(EOL_MAPPING.by_group_prefix || {})
 		.sort((a, b) => b.length - a.length);
 	for (const p of prefixes) {
 		if (dep.groupId === p || dep.groupId.startsWith(p + ".")) {
-			return EOL_MAPPING.by_group_prefix[p];
+			return withOrigin(EOL_MAPPING.by_group_prefix[p], "group-prefix", p);
 		}
 	}
 	return null;
@@ -154,6 +164,8 @@ async function checkEolDeps(resolvedDeps, opts = {}) {
 			dep,
 			product: product.label || product.product,
 			productSlug: product.product,
+			via: product.via || null,
+			viaKey: product.viaKey || null,
 			cycle: cycle.cycle,
 			eol: cycle.eol === true ? "true" : String(cycle.eol),
 			latest: cycle.latest || null,

package/lib/parallel-walk.js

@@ -9,7 +9,8 @@
  * into something close to a single round-trip deep, which is dramatically faster.
  *
  * `onDir(absDir, entries)` is called once per visited directory with its Dirent[].
- * `skipDir(name)` prunes a child directory by basename (caller's own skip policy).
+ * `skipDir(absChildDir, name)` prunes a child directory (caller's own skip policy);
+ * it receives the child's absolute path (for path-relative globs) plus its basename.
  *
  * @author: N.BRAUN
  * @email: pp9ping@gmail.com
@@ -34,7 +35,9 @@ async function walkDirs(root, { skipDir = () => false, concurrency = DEFAULT_CON
 				fs.promises.readdir(cur, { withFileTypes: true }).then(entries => {
 					if (onDir) onDir(cur, entries);
 					for (const e of entries) {
-						if (e.isDirectory() && !skipDir(e.name)) queue.push(path.join(cur, e.name));
+						if (!e.isDirectory()) continue;
+						const child = path.join(cur, e.name);
+						if (!skipDir(child, e.name)) queue.push(child);
 					}
 				}).catch(() => { /* unreadable dir → skip, same as readdirSync catch */ })
 					.finally(() => { active--; pump(); });

package/lib/path-filter.js

@@ -0,0 +1,58 @@
+/**
+ * lib/path-filter.js — directory-walk pruning policy shared by every codec walker.
+ *
+ * Two layers:
+ *   - default skips: each walker's own basename set (node_modules, vendor, target,
+ *     .git, …). Bypassable with useDefaults=false (CLI --no-default-excludes).
+ *   - user globs: --exclude-path / `excludePath` config, matched gitignore-style
+ *     against the directory's path RELATIVE to the scan root (`srcRoot`). A bare
+ *     `foo/bar` matches that directory and its whole subtree (`foo/bar/**`).
+ *
+ * makeDirFilter() returns a predicate over a child directory's ABSOLUTE path, so
+ * it drops straight into parallel-walk's skipDir and the serial readdir walkers.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const path = require("path");
+const { minimatch } = require("minimatch");
+
+/**
+ * Compile glob strings into (relPath) → bool matchers. Each glob prunes both the
+ * matched directory itself and its whole subtree, so `packages/legacy/**` (or the
+ * bare `packages/legacy`) stops the walk at `packages/legacy` — a manifest sitting
+ * directly in it is never collected.
+ */
+function compileGlobs(globs) {
+	return (globs || []).filter(Boolean).map(String).map(g => g.trim()).filter(Boolean).map(g => {
+		// Paths match relative to srcRoot, so they're already root-anchored. Accept
+		// `truc`, `/truc` and `./truc` as the same thing (strip a leading ./ or /).
+		const base = g.replace(/^\.?\/+/, "").replace(/\/+$/, "");
+		const patterns = base.endsWith("/**")
+			? [base, base.slice(0, -3).replace(/\/+$/, "")] // dir + its subtree
+			: [base, base + "/**"];
+		return rel => patterns.some(p => p && minimatch(rel, p, { dot: true }));
+	});
+}
+
+/**
+ * Build a skipDir(absChildDir) predicate.
+ *   srcRoot       scan root the globs are relative to
+ *   defaultSkip   Set of basenames the walker prunes by default (its own SKIP)
+ *   excludePath   user glob strings
+ *   useDefaults   when false, ignore defaultSkip entirely (--no-default-excludes)
+ */
+function makeDirFilter({ srcRoot, defaultSkip = null, excludePath = [], useDefaults = true } = {}) {
+	const matchers = compileGlobs(excludePath);
+	return function skipDir(absChild) {
+		const name = path.basename(absChild);
+		if (useDefaults && defaultSkip && defaultSkip.has(name)) return true;
+		if (matchers.length && srcRoot) {
+			const rel = path.relative(srcRoot, absChild).split(path.sep).join("/");
+			if (rel && !rel.startsWith("..") && matchers.some(m => m(rel))) return true;
+		}
+		return false;
+	};
+}
+
+module.exports = { makeDirFilter, compileGlobs };

package/lib/registries.js

@@ -0,0 +1,112 @@
+/**
+ * lib/registries.js — per-ecosystem registry list assembly + auth + fan-out.
+ *
+ * Generalizes lib/maven-repo.js's list-building to npm/pypi/ruby/go. Custom
+ * registries are tried first (declared order); callers append the public base
+ * last via withPublic(). Lists are unioned across config layers, deduped by URL.
+ *
+ * Entry shape: { name?, url, auth?, token? }
+ *   auth  "user:pass" → Authorization: Basic <base64>
+ *   token "…"         → Authorization: Bearer <token>
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const SUPPORTED = ["maven", "npm", "pypi", "ruby", "go"];
+
+const PUBLIC_BASES = {
+	maven: "https://repo1.maven.org/maven2/",
+	npm: "https://registry.npmjs.org/",
+	pypi: "https://pypi.org/pypi/",
+	ruby: "https://rubygems.org/api/v1/gems/",
+	go: "https://proxy.golang.org/",
+};
+
+function normalise(url) {
+	if (!url) return url;
+	return url.endsWith("/") ? url : url + "/";
+}
+
+function splitUrlAuth(url) {
+	if (!url) return { url, auth: null };
+	try {
+		const u = new URL(url);
+		if (u.username || u.password) {
+			const auth = decodeURIComponent(u.username) + ":" + decodeURIComponent(u.password);
+			u.username = ""; u.password = "";
+			return { url: u.toString(), auth };
+		}
+	} catch { /* not a URL */ }
+	return { url, auth: null };
+}
+
+function authHeaderFor(entry) {
+	if (!entry) return null;
+	if (entry.token) return "Bearer " + entry.token;
+	if (entry.auth) return "Basic " + Buffer.from(entry.auth).toString("base64");
+	return null;
+}
+
+/** Union of registry entries from several layers (arrays). Dedup by URL, first wins. */
+function buildRegistryList(_ecosystem, layers = []) {
+	const out = [];
+	const seen = new Set();
+	for (const layer of layers) {
+		for (const r of layer || []) {
+			if (!r?.url) continue;
+			const { url, auth } = splitUrlAuth(normalise(r.url));
+			if (seen.has(url)) continue;
+			seen.add(url);
+			out.push({ name: r.name || url, url, auth: r.auth || auth || null, token: r.token || null });
+		}
+	}
+	return out;
+}
+
+/** Append the ecosystem's public base (no auth) as the final fallback. */
+function withPublic(ecosystem, list) {
+	const pub = PUBLIC_BASES[ecosystem];
+	const out = [...(list || [])];
+	if (pub && !out.some(r => normalise(r.url) === pub)) out.push({ name: "public", url: pub, auth: null, token: null });
+	return out;
+}
+
+/** Merge two registry maps (eco → entries[]) into one (concat per eco). */
+function mergeRegistryMaps(...maps) {
+	const out = {};
+	for (const m of maps) {
+		if (!m || typeof m !== "object") continue;
+		for (const eco of Object.keys(m)) {
+			if (!Array.isArray(m[eco])) continue;
+			out[eco] = (out[eco] || []).concat(m[eco]);
+		}
+	}
+	return out;
+}
+
+/**
+ * Try each base in order; return the first response whose `res.ok` is true,
+ * as { res, base, url }. Applies per-base auth. opts.fetcher for tests.
+ */
+async function fetchFirstOk(bases, buildUrl, opts = {}) {
+	const { fetcher = globalThis.fetch, userAgent = "fad-checker", timeoutMs, onMiss } = opts;
+	for (const base of bases) {
+		const url = buildUrl(normalise(base.url));
+		const headers = { "User-Agent": userAgent, Accept: "application/json" };
+		const ah = authHeaderFor(base);
+		if (ah) headers.Authorization = ah;
+		let res;
+		try {
+			res = await fetcher(url, { headers, ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}) });
+		} catch (err) { if (onMiss) onMiss(base, `network: ${err.message}`); continue; }
+		if (res.ok) return { res, base, url };
+		if (onMiss) onMiss(base, `HTTP ${res.status}`);
+	}
+	return null;
+}
+
+module.exports = {
+	SUPPORTED, PUBLIC_BASES,
+	normalise, splitUrlAuth, authHeaderFor,
+	buildRegistryList, withPublic, mergeRegistryMaps, fetchFirstOk,
+};

package/lib/retire.js

@@ -36,15 +36,38 @@ const RETIRE_SIG_DIR = path.join(os.homedir(), ".fad-checker", "retire-signature
 const RETIRE_SIG_FILE = path.join(RETIRE_SIG_DIR, "jsrepository-v5.json");
 const RETIRE_REPO_URL = "https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository-v5.json";
 
+// retire always emits ABSOLUTE file paths (it resolves --jspath). Make them
+// relative to the scan root robustly — resolving BOTH sides so it works whether
+// the caller passed -s as a relative ("./proj") or absolute path. The old
+// `file.startsWith(srcDir)` guard silently left paths absolute for a relative -s.
+function relToSrc(srcDir, file) {
+	if (!file) return file;
+	if (!srcDir) return file;
+	try {
+		const rel = path.relative(path.resolve(srcDir), path.resolve(file));
+		return rel && !rel.startsWith("..") ? rel : file;
+	} catch { return file; }
+}
+
 function cacheKey(srcDir) {
 	return crypto.createHash("md5").update(path.resolve(srcDir)).digest("hex") + ".json";
 }
 
+// Cache schema version. Bumped to 2 when retire started running with `--verbose`
+// (so the cached body carries the FULL vendored-JS inventory, not just vulnerable
+// hits). A cached entry without `_schema >= 2` was written by a pre-verbose build
+// (e.g. 1.0.6) and its body holds vuln-only data — trusting it would silently empty
+// the inventory chapter (1D) on an offline re-run. We treat such an entry as a
+// cache MISS so the normal path re-scans (online, or offline with local signatures)
+// and the offline report reproduces the online one.
+const RETIRE_CACHE_SCHEMA = 2;
+
 function readCache(srcDir) {
 	const p = path.join(RETIRE_CACHE_DIR, cacheKey(srcDir));
 	if (!fs.existsSync(p)) return null;
 	try {
 		const data = JSON.parse(fs.readFileSync(p, "utf8"));
+		if (!(data._schema >= RETIRE_CACHE_SCHEMA)) return null; // legacy / pre-verbose → re-scan
 		if (Date.now() - data._fetchedAt < RETIRE_CACHE_TTL_MS) return data.body;
 	} catch { /* ignore */ }
 	return null;
@@ -53,7 +76,7 @@ function readCache(srcDir) {
 function writeCache(srcDir, body) {
 	fs.mkdirSync(RETIRE_CACHE_DIR, { recursive: true });
 	fs.writeFileSync(path.join(RETIRE_CACHE_DIR, cacheKey(srcDir)),
-		JSON.stringify({ _fetchedAt: Date.now(), body }));
+		JSON.stringify({ _schema: RETIRE_CACHE_SCHEMA, _fetchedAt: Date.now(), body }));
 }
 
 function findRetireBin() {
@@ -62,6 +85,28 @@ function findRetireBin() {
 	return "retire"; // fall back to PATH
 }
 
+// Decide HOW to launch retire. The compiled (bun) binary has no node_modules to
+// spawn the retire CLI from and the air-gapped box has no `retire` on PATH — so it
+// re-execs ITSELF with __FAD_RETIRE__ set, and the entry point (fad-checker.js)
+// hands off to the statically-bundled retire CLI. Pure for testability.
+//   - localBin present (node dev / node_modules) → run it directly.
+//   - else running under bun (compiled binary)   → self-invoke this executable.
+//   - else                                       → `retire` on PATH (last resort).
+function chooseRetireLauncher({ localBin, isBun, execPath }) {
+	if (localBin) return { cmd: localBin, env: null };
+	if (isBun) return { cmd: execPath, env: { __FAD_RETIRE__: "1" } };
+	return { cmd: "retire", env: null };
+}
+
+function findRetireLauncher() {
+	const local = path.join(__dirname, "..", "node_modules", ".bin", "retire");
+	return chooseRetireLauncher({
+		localBin: fs.existsSync(local) ? local : null,
+		isBun: !!(process.versions && process.versions.bun),
+		execPath: process.execPath,
+	});
+}
+
 /**
  * Fetch retire's signature DB to a stable file inside ~/.fad-checker/ so it can
  * be bundled by --export-cache and reused offline via --jsrepo. Network call —
@@ -101,6 +146,11 @@ async function ensureSignatures({ verbose, offline } = {}) {
 // when available so retire loads signatures from disk instead of the network.
 function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
 	const args = [
+		// --verbose makes retire list EVERY identified library, not just the
+		// vulnerable ones (its own wording: "by default only vulnerable files are
+		// shown"). We need the full set for the vendored-JS inventory chapter;
+		// vulnerable findings are still flagged in each result's `vulnerabilities`.
+		"--verbose",
 		"--outputformat", "json",
 		"--outputpath", outPath,
 		"--jspath", srcDir,
@@ -110,6 +160,64 @@ function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
 	return args;
 }
 
+const SEV_RANK = { critical: 5, high: 4, medium: 3, low: 2, none: 1 };
+
+// Pick the human-meaningful line out of retire's stderr for a failure message.
+// retire dumps a multi-line stack trace; the useful part is the first non-empty,
+// non-stack-frame line (preferring an ENOENT / "no such file" / permission line).
+function retireFailureReason(stderr, fallback) {
+	const lines = String(stderr || "")
+		.split("\n")
+		.map(l => l.trim())
+		.filter(l => l && !/^at\s/.test(l));
+	if (!lines.length) return fallback;
+	const hot = lines.find(l => /ENOENT|no such file|permission denied|EACCES/i.test(l));
+	return hot || lines[0];
+}
+
+/**
+ * Extract the full inventory of identified vendored JS libraries (vulnerable or
+ * not) from retire's --verbose output. Each entry: the standalone library, where
+ * it lives, how retire identified it, and whether it carries known vulns.
+ * This is a governance/cyber-hygiene signal: third-party code no package manager
+ * governs (unknown provenance, integrity, patch story) — the JS twin of the
+ * native-binary inventory (chapter 1C).
+ */
+function extractVendoredInventory(raw, srcDir) {
+	const out = [];
+	if (!raw) return out;
+	const files = Array.isArray(raw) ? raw : (raw.data || []);
+	for (const f of files) {
+		const file = f.file;
+		const relFile = relToSrc(srcDir, file);
+		for (const res of f.results || []) {
+			if (!res.component) continue;
+			const vulns = res.vulnerabilities || [];
+			let maxSeverity = null;
+			for (const v of vulns) {
+				const s = (v.severity || "").toLowerCase();
+				if (!maxSeverity || (SEV_RANK[s] || 0) > (SEV_RANK[maxSeverity] || 0)) maxSeverity = s;
+			}
+			out.push({
+				component: res.component,
+				version: res.version || null,
+				file: relFile || null,
+				detection: res.detection || null,
+				vulnerable: vulns.length > 0,
+				vulnCount: vulns.length,
+				maxSeverity: maxSeverity ? maxSeverity.toUpperCase() : null,
+			});
+		}
+	}
+	// Vulnerable first (by severity), then by component/version/file for stability.
+	out.sort((a, b) =>
+		(SEV_RANK[(b.maxSeverity || "").toLowerCase()] || 0) - (SEV_RANK[(a.maxSeverity || "").toLowerCase()] || 0)
+		|| String(a.component).localeCompare(String(b.component))
+		|| String(a.version).localeCompare(String(b.version))
+		|| String(a.file).localeCompare(String(b.file)));
+	return out;
+}
+
 /**
  * Run retire.js against `srcDir`. Returns the parsed JSON output (an array
  * of file-level findings) or null if retire is unavailable.
@@ -119,6 +227,10 @@ function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
  */
 async function runRetire(srcDir, opts = {}) {
 	const { verbose, force, offline } = opts;
+	// Optional diagnostics collector: callers (scanWithRetireFull) read diag.error to
+	// surface a genuine SCAN FAILURE (retire crashed / produced no parseable output)
+	// as a report warning — instead of letting it masquerade as "no vendored JS found".
+	const diag = opts.diag || {};
 	// No source tree (e.g. --import-anonymized) → nothing to scan for vendored JS.
 	if (!srcDir) { if (verbose) console.warn("retire: no source dir — skipped"); return null; }
 	// Findings-cache fast path (path-keyed). Works online and offline.
@@ -139,7 +251,7 @@ async function runRetire(srcDir, opts = {}) {
 		return null;
 	}
 
-	const bin = findRetireBin();
+	const launcher = findRetireLauncher();
 	const ignoredDirs = [
 		"node_modules", "bower_components", "jspm_packages",
 		".git", ".idea", ".vscode", ".gradle", ".mvn",
@@ -152,15 +264,27 @@ async function runRetire(srcDir, opts = {}) {
 	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoredDirs, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
 	if (verbose) console.log(`retire: scanning ${srcDir}…${haveSig ? " (local signatures)" : ""}`);
 
+	let execErr = null;
 	try {
 		// retire.js exits with code 13 when it finds vulnerabilities — that's
 		// expected. Catch and ignore the non-zero exit; the JSON file is still
 		// produced.
-		await execFileP(bin, args, { maxBuffer: 1024 * 1024 * 64 });
+		await execFileP(launcher.cmd, args, {
+			maxBuffer: 1024 * 1024 * 64,
+			env: launcher.env ? { ...process.env, ...launcher.env } : process.env,
+		});
 	} catch (err) {
-		// exit code 13 (or anything where the output file exists) is OK
-		if (!fs.existsSync(tmpOut)) {
-			if (verbose) console.warn(`retire: failed to run — ${err.message}`);
+		execErr = err;
+		// exit code 13 (or anything where a non-empty output file exists) is OK.
+		// A missing OR empty (0-byte) output file means retire crashed mid-walk
+		// (e.g. ENOENT on the source path, an unreadable file) — a real failure.
+		let size = -1;
+		try { size = fs.statSync(tmpOut).size; } catch { /* missing */ }
+		if (size <= 0) {
+			const reason = retireFailureReason(err.stderr, err.message);
+			diag.error = `retire.js scan failed: ${reason}`;
+			if (verbose) console.warn(`retire: failed to run — ${reason}`);
+			try { fs.unlinkSync(tmpOut); } catch { /* best effort */ }
 			return null;
 		}
 	}
@@ -170,6 +294,8 @@ async function runRetire(srcDir, opts = {}) {
 		const body = fs.readFileSync(tmpOut, "utf8");
 		parsed = JSON.parse(body);
 	} catch (err) {
+		const reason = retireFailureReason(execErr && execErr.stderr, err.message);
+		diag.error = `retire.js scan failed: ${reason}`;
 		if (verbose) console.warn(`retire: could not parse output — ${err.message}`);
 		return null;
 	} finally {
@@ -212,7 +338,7 @@ function normaliseRetireResults(raw, srcDir) {
 	const files = Array.isArray(raw) ? raw : (raw.data || []);
 	for (const f of files) {
 		const file = f.file;
-		const relFile = srcDir && file?.startsWith(srcDir) ? path.relative(srcDir, file) : file;
+		const relFile = relToSrc(srcDir, file);
 		for (const res of f.results || []) {
 			const component = res.component;
 			const version = res.version;
@@ -263,14 +389,39 @@ async function scanWithRetire(srcDir, opts = {}) {
 	return normaliseRetireResults(raw, srcDir);
 }
 
+/**
+ * Like scanWithRetire but returns BOTH the vulnerable matches (chapter "Vendored
+ * JS") and the full identified-library inventory (chapter "Unmanaged / vendored
+ * JavaScript"). One retire run feeds both.
+ */
+async function scanWithRetireFull(srcDir, opts = {}) {
+	const diag = {};
+	const raw = await runRetire(srcDir, { ...opts, diag });
+	if (!raw) return { matches: [], inventory: [], error: diag.error || null };
+	return {
+		matches: normaliseRetireResults(raw, srcDir),
+		inventory: extractVendoredInventory(raw, srcDir),
+		error: null,
+	};
+}
+
 module.exports = {
 	scanWithRetire,
+	scanWithRetireFull,
+	extractVendoredInventory,
 	runRetire,
 	normaliseRetireResults,
 	findRetireBin,
+	findRetireLauncher,
+	chooseRetireLauncher,
 	warmRetireSignatures,
 	ensureSignatures,
 	buildRetireArgs,
+	retireFailureReason,
+	readCache,
+	writeCache,
+	cacheKey,
+	RETIRE_CACHE_SCHEMA,
 	RETIRE_CACHE_DIR,
 	RETIRE_SIG_DIR,
 	RETIRE_SIG_FILE,