fad-checker 2.0.0 → 2.0.1

package/lib/deps-descriptor.js

@@ -0,0 +1,110 @@
+/**
+ * lib/deps-descriptor.js — serialize / deserialize an *anonymized* descriptor of
+ * the resolved dependency set, for PASSI-style offline→online→offline audits.
+ *
+ * Phase 1 (offline): collect deps → serializeDeps → write JSON. No paths, URLs,
+ *   hostnames or usernames leave the air-gapped machine — only public package
+ *   coordinates (ecosystem / namespace / name / version) + scope.
+ * Phase 2 (online): read JSON → deserializeDeps → run the scan flow to warm the
+ *   coordinate-keyed caches, then `--export-cache`.
+ * Phase 3 (offline): `--import-cache` + a normal `--offline` scan re-collects the
+ *   source locally (real paths) and gets cache hits → full detailed report.
+ *
+ * See docs/superpowers/specs/2026-05-30-anonymized-deps-descriptor-passi-design.md
+ *
+ * Pure functions: no I/O, no console. The caller does file read/write.
+ */
+const { makeDepRecord, coordKeyFor } = require("./dep-record");
+
+const SCHEMA = "fad-deps/1";
+
+// Fields kept in the descriptor — everything required to query the public vuln
+// databases and to group the report. Anything path/URL/host-bearing is dropped:
+//   manifestPath(s) / pomPaths, resolved (registry URL), integrity, from
+//   (parent chain), depth, lockType.
+const ANON_NOTE = "Anonymized: public coordinates only — no paths, URLs, or host info. Review before transfer.";
+
+/**
+ * serializeDeps(resolvedMap, opts) -> descriptor object (ready for JSON.stringify).
+ *
+ * opts:
+ *   generator    — tool id/version string for traceability (no env info)
+ *   generatedAt  — ISO timestamp (override for deterministic tests)
+ *   note         — human-readable banner (defaults to the anonymization notice)
+ */
+function serializeDeps(resolvedMap, opts = {}) {
+	const { generator = "fad-checker", generatedAt = new Date().toISOString(), note = ANON_NOTE } = opts;
+	const deps = [];
+	const byEcosystem = {};
+	for (const d of resolvedMap.values()) {
+		if (!d || !d.ecosystem || !d.name) continue;
+		const versions = Array.isArray(d.versions) && d.versions.length
+			? [...new Set(d.versions)]
+			: (d.version ? [d.version] : []);
+		deps.push({
+			ecosystem: d.ecosystem,
+			ecosystemType: d.ecosystemType || d.ecosystem,
+			namespace: d.namespace || "",
+			name: d.name,
+			version: d.version || (versions[0] || null),
+			versions,
+			scope: d.scope || "prod",
+			isDev: !!d.isDev,
+		});
+		byEcosystem[d.ecosystem] = (byEcosystem[d.ecosystem] || 0) + 1;
+	}
+	// Stable order so two runs over the same tree produce identical files (easier
+	// to diff/review and to detect tampering during transfer).
+	deps.sort((a, b) => (a.ecosystem + "\0" + a.namespace + "\0" + a.name).localeCompare(b.ecosystem + "\0" + b.namespace + "\0" + b.name));
+	return {
+		schema: SCHEMA,
+		generator,
+		generatedAt,
+		note,
+		summary: { total: deps.length, byEcosystem },
+		deps,
+	};
+}
+
+/**
+ * deserializeDeps(descriptor) -> { resolved, activeIds, runMaven, runNpm }.
+ *
+ * Rebuilds depRecords with EMPTY manifestPaths (the descriptor carries none) and
+ * a RECOMPUTED coordKey (never trusts the input). Throws on schema mismatch.
+ */
+function deserializeDeps(descriptor) {
+	if (!descriptor || typeof descriptor !== "object") throw new Error("invalid descriptor: not an object");
+	if (descriptor.schema !== SCHEMA) {
+		throw new Error(`unsupported descriptor schema: got "${descriptor.schema}", expected "${SCHEMA}"`);
+	}
+	const list = Array.isArray(descriptor.deps) ? descriptor.deps : [];
+	const resolved = new Map();
+	const ecosystems = new Set();
+	for (const e of list) {
+		if (!e || !e.ecosystem || !e.name) continue;
+		const rec = makeDepRecord({
+			ecosystem: e.ecosystem,
+			ecosystemType: e.ecosystemType || e.ecosystem,
+			namespace: e.namespace || "",
+			name: e.name,
+			version: e.version || null,
+			scope: e.scope || "prod",
+			isDev: !!e.isDev,
+			// manifestPath intentionally omitted → manifestPaths/pomPaths = []
+		});
+		// Restore the full multi-version set (makeDepRecord only derives it from the
+		// single `version`); CVE/OSV matching iterates `versions`.
+		if (Array.isArray(e.versions) && e.versions.length) rec.versions = [...new Set(e.versions)];
+		resolved.set(coordKeyFor(e.ecosystem, e.namespace || "", e.name), rec);
+		ecosystems.add(e.ecosystem);
+	}
+	const activeIds = [...ecosystems];
+	return {
+		resolved,
+		activeIds,
+		runMaven: ecosystems.has("maven"),
+		runNpm: ecosystems.has("npm") || ecosystems.has("yarn"),
+	};
+}
+
+module.exports = { serializeDeps, deserializeDeps, SCHEMA, ANON_NOTE };

package/lib/nvd.js

@@ -191,7 +191,7 @@ async function fetchOne(cveId, opts = {}) {
  * Rate limited per the NIST policy (use NVD_API_KEY for faster access).
  */
 async function enrichMatches(matches, opts = {}) {
-	const { offline } = opts;
+	const { offline, onProgress } = opts;
 	const uniqueCves = new Set();
 	for (const m of matches) if (m.cve?.id?.startsWith("CVE-")) uniqueCves.add(m.cve.id);
 	const hasKey = !!getNvdApiKey();
@@ -212,13 +212,13 @@ async function enrichMatches(matches, opts = {}) {
 		liveIds.push(cveId);
 	}
 
-	if (liveIds.length) {
+	if (liveIds.length && !onProgress) {
 		const etaSec = Math.ceil((liveIds.length / burst) * (NVD_WINDOW_MS / 1000));
 		const keyHint = hasKey ? "with API key (50/30s)" : "no API key — throttled to 5/30s, run `fad-checker --set-nvd-key <KEY>` (free, instant) to be 10× faster";
 		const cachedCount = byId.size;
 		const cachedHint = cachedCount ? `, ${cachedCount} cached` : "";
 		console.log(`🔍 NVD: enriching ${liveIds.length} CVEs${cachedHint} — ${keyHint}. ETA ~${etaSec}s.`);
-	} else if (uniqueCves.size) {
+	} else if (uniqueCves.size && !onProgress) {
 		console.log(`🔍 NVD: ${uniqueCves.size} CVEs (all cached).`);
 	}
 
@@ -229,6 +229,7 @@ async function enrichMatches(matches, opts = {}) {
 	const startedAt = [];
 	const startProgress = Date.now();
 	const printProgress = (final = false) => {
+		if (onProgress) { onProgress(done, liveIds.length); return; }
 		const elapsed = Math.round((Date.now() - startProgress) / 1000);
 		const pct = liveIds.length ? Math.round((done / liveIds.length) * 100) : 100;
 		const line = `   NVD: ${done}/${liveIds.length} (${pct}%) — ${elapsed}s elapsed`;

package/lib/osv.js

@@ -152,7 +152,7 @@ function vulnToMatch(dep, vuln) {
 }
 
 async function queryBatch(deps, opts = {}) {
-	const { verbose, offline, fetcher = globalThis.fetch } = opts;
+	const { verbose, offline, fetcher = globalThis.fetch, onProgress } = opts;
 	// Build query list + parallel cached/uncached split
 	const queries = [];
 	const indexMap = []; // index in `deps` → either { cached: vulns } or { queryIdx: N }
@@ -187,7 +187,8 @@ async function queryBatch(deps, opts = {}) {
 		let batchIdx = 0;
 		for (const batch of batches) {
 			batchIdx++;
-			if (process.stdout.isTTY) process.stdout.write(`\r   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…                  `);
+			if (onProgress) onProgress(batchIdx, batches.length);
+			else if (process.stdout.isTTY) process.stdout.write(`\r   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…                  `);
 			else if (batches.length > 1) console.log(`   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…`);
 			const res = await fetcher(`${OSV_BASE}/v1/querybatch`, {
 				method: "POST",
@@ -205,7 +206,8 @@ async function queryBatch(deps, opts = {}) {
 				allResults[(batchIdx - 1) * BATCH_SIZE + j] = results[j] || { vulns: [] };
 			}
 		}
-		if (process.stdout.isTTY) process.stdout.write(`\r   OSV batches complete (${batches.length})                          \n`);
+		if (onProgress) { /* finalized by caller */ }
+		else if (process.stdout.isTTY) process.stdout.write(`\r   OSV batches complete (${batches.length})                          \n`);
 
 		// Persist per-dep cache (stub list — details cached separately)
 		for (let i = 0; i < deps.length; i++) {
@@ -239,12 +241,13 @@ async function queryBatch(deps, opts = {}) {
 	}
 
 	if (liveIds.length) {
-		console.log(`   OSV details: ${liveIds.length} to fetch${allIds.size - liveIds.length ? `, ${allIds.size - liveIds.length} cached` : ""}…`);
+		if (!onProgress) console.log(`   OSV details: ${liveIds.length} to fetch${allIds.size - liveIds.length ? `, ${allIds.size - liveIds.length} cached` : ""}…`);
 		const concurrency = 10;
 		let cursor = 0;
 		let fetched = 0;
 		const startedAt = Date.now();
 		const printOsvProgress = (final = false) => {
+			if (onProgress) { onProgress(fetched, liveIds.length); return; }
 			const elapsed = Math.round((Date.now() - startedAt) / 1000);
 			const pct = Math.round((fetched / liveIds.length) * 100);
 			const line = `   OSV details: ${fetched}/${liveIds.length} (${pct}%) — ${elapsed}s`;

package/lib/outdated.js

@@ -251,7 +251,7 @@ function parseMavenMetadataLatest(xml) {
 }
 
 async function checkOutdatedDeps(resolvedDeps, opts = {}) {
-	const { verbose, offline, concurrency = 8, repos } = opts;
+	const { verbose, offline, concurrency = 8, repos, onProgress } = opts;
 	const cache = loadJsonCache(VERSION_CACHE_PATH);
 	const fresh = cache.meta?.fetchedAt && (Date.now() - cache.meta.fetchedAt) < VERSION_CACHE_MAX_AGE_MS;
 	if (!fresh && !offline) cache.entries = {};
@@ -263,7 +263,7 @@ async function checkOutdatedDeps(resolvedDeps, opts = {}) {
 	// seconds with 8-way concurrency, but on first run (cold cache) the user
 	// would see total silence for 20-60s.
 	const liveCount = offline ? 0 : list.filter(d => !cache.entries[`${d.groupId}:${d.artifactId}`]).length;
-	if (liveCount && !offline) {
+	if (liveCount && !offline && !onProgress) {
 		console.log(`📅 Outdated: checking ${list.length} deps against Maven Central (${liveCount} live, ${list.length - liveCount} cached)…`);
 	}
 
@@ -271,6 +271,7 @@ async function checkOutdatedDeps(resolvedDeps, opts = {}) {
 	let processed = 0;
 	const startedAt = Date.now();
 	const printOutdatedProgress = (final = false) => {
+		if (onProgress) { onProgress(processed, list.length); return; }
 		if (!liveCount) return;
 		const elapsed = Math.round((Date.now() - startedAt) / 1000);
 		const pct = Math.round((processed / list.length) * 100);
@@ -308,6 +309,10 @@ module.exports = {
 	checkObsolete,
 	checkOutdatedDeps,
 	findEolProduct,
+	findCycleForVersion,
+	isEol,
 	isEolCacheFresh,
+	EOL_MAPPING,
+	EOL_CACHE_PATH,
 	KNOWN_OBSOLETE,
 };

package/lib/retire.js

@@ -24,6 +24,15 @@ const execFileP = promisify(execFile);
 const RETIRE_CACHE_DIR = path.join(os.homedir(), ".fad-checker", "retire-cache");
 const RETIRE_CACHE_TTL_MS = 24 * 3600 * 1000;
 
+// retire's own signature DB. By default retire caches it in /tmp/.retire-cache
+// (outside ~/.fad-checker/, with a 1h TTL → a network refetch on expiry). For the
+// PASSI offline workflow we instead keep a stable local copy INSIDE ~/.fad-checker/
+// so `--export-cache` carries it, and feed it to retire via `--jsrepo <file>`
+// (loaded from file, never the network — no TTL).
+const RETIRE_SIG_DIR = path.join(os.homedir(), ".fad-checker", "retire-signatures");
+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";
+
 function cacheKey(srcDir) {
 	return crypto.createHash("md5").update(path.resolve(srcDir)).digest("hex") + ".json";
 }
@@ -50,6 +59,54 @@ function findRetireBin() {
 	return "retire"; // fall back to PATH
 }
 
+/**
+ * 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 —
+ * online only. Returns { ok, path } | { ok:false, error }. Never throws.
+ */
+async function warmRetireSignatures(opts = {}) {
+	const { verbose, force } = opts;
+	if (!force && fs.existsSync(RETIRE_SIG_FILE)) {
+		if (verbose) console.log(`retire: signatures already present (${RETIRE_SIG_FILE})`);
+		return { ok: true, path: RETIRE_SIG_FILE, cached: true };
+	}
+	try {
+		const res = await fetch(RETIRE_REPO_URL);
+		if (!res.ok) throw new Error(`HTTP ${res.status}`);
+		const text = await res.text();
+		JSON.parse(text);   // validate it's the repo JSON before persisting
+		fs.mkdirSync(RETIRE_SIG_DIR, { recursive: true });
+		fs.writeFileSync(RETIRE_SIG_FILE, text);
+		if (verbose) console.log(`retire: signatures warmed → ${RETIRE_SIG_FILE}`);
+		return { ok: true, path: RETIRE_SIG_FILE };
+	} catch (e) {
+		if (verbose) console.warn(`retire: signature warm failed — ${e.message}`);
+		return { ok: false, error: e.message };
+	}
+}
+
+// Ensure a local signature file exists. Online: fetch it if missing. Offline:
+// only report whether it's already there (no network).
+async function ensureSignatures({ verbose, offline } = {}) {
+	if (fs.existsSync(RETIRE_SIG_FILE)) return true;
+	if (offline) return false;
+	const r = await warmRetireSignatures({ verbose });
+	return !!r.ok;
+}
+
+// Pure: build the retire CLI argv. `jsRepo` (a local signature file) is added
+// when available so retire loads signatures from disk instead of the network.
+function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
+	const args = [
+		"--outputformat", "json",
+		"--outputpath", outPath,
+		"--jspath", srcDir,
+		"--ignore", ignoredDirs,
+	];
+	if (jsRepo) { args.push("--jsrepo", jsRepo); }
+	return args;
+}
+
 /**
  * Run retire.js against `srcDir`. Returns the parsed JSON output (an array
  * of file-level findings) or null if retire is unavailable.
@@ -59,12 +116,9 @@ function findRetireBin() {
  */
 async function runRetire(srcDir, opts = {}) {
 	const { verbose, force, offline } = opts;
-	if (offline) {
-		const cached = readCache(srcDir);
-		if (cached) return cached;
-		if (verbose) console.warn("retire: --offline and no cache — skipped");
-		return null;
-	}
+	// 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.
 	if (!force) {
 		const cached = readCache(srcDir);
 		if (cached) {
@@ -73,6 +127,15 @@ async function runRetire(srcDir, opts = {}) {
 		}
 	}
 
+	// No findings cache → we must scan. We need a signature DB. Offline, we can
+	// only proceed if a local signature file was previously warmed (and bundled
+	// via --export-cache / --import-cache); otherwise honor --offline and skip.
+	const haveSig = await ensureSignatures({ verbose, offline });
+	if (offline && !haveSig) {
+		if (verbose) console.warn("retire: --offline, no findings cache and no local signatures — skipped");
+		return null;
+	}
+
 	const bin = findRetireBin();
 	const ignoredDirs = [
 		"node_modules", "bower_components", "jspm_packages",
@@ -83,13 +146,8 @@ async function runRetire(srcDir, opts = {}) {
 	// retire.js refuses to write to /dev/stdout, so we use a real temp file
 	// and read it back. Falls back to stdout if --outputpath is rejected.
 	const tmpOut = path.join(os.tmpdir(), `fad-checker-retire-${process.pid}-${Date.now()}.json`);
-	const args = [
-		"--outputformat", "json",
-		"--outputpath", tmpOut,
-		"--jspath", srcDir,
-		"--ignore", ignoredDirs,
-	];
-	if (verbose) console.log(`retire: scanning ${srcDir}…`);
+	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoredDirs, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
+	if (verbose) console.log(`retire: scanning ${srcDir}…${haveSig ? " (local signatures)" : ""}`);
 
 	try {
 		// retire.js exits with code 13 when it finds vulnerabilities — that's
@@ -207,5 +265,11 @@ module.exports = {
 	runRetire,
 	normaliseRetireResults,
 	findRetireBin,
+	warmRetireSignatures,
+	ensureSignatures,
+	buildRetireArgs,
 	RETIRE_CACHE_DIR,
+	RETIRE_SIG_DIR,
+	RETIRE_SIG_FILE,
+	RETIRE_REPO_URL,
 };

package/lib/transitive.js

@@ -396,12 +396,12 @@ async function resolveTransitiveDeps(directDeps, opts = {}) {
 			// Progress visible whenever stdout is a TTY — transitive resolution
 			// dominates wall-clock time on first run and used to look like a hang.
 			// On non-TTY (pipes, CI, tests) we skip the \r-overwrite spam.
-			if (process.stdout.isTTY) process.stdout.write(`\r   resolved ${out.size} transitives, queue=${queue.length - head}          `);
+			if (verbose && process.stdout.isTTY) process.stdout.write(`\r   resolved ${out.size} transitives, queue=${queue.length - head}          `);
 		}
 	});
 	await Promise.all(workers);
-	if (process.stdout.isTTY) process.stdout.write(`\r   resolved ${out.size} transitives                              \n`);
-	else if (out.size) console.log(`   resolved ${out.size} transitives`);
+	if (verbose && process.stdout.isTTY) process.stdout.write(`\r   resolved ${out.size} transitives                              \n`);
+	else if (verbose && out.size) console.log(`   resolved ${out.size} transitives`);
 
 	return out;
 }

package/lib/ui.js

@@ -0,0 +1,87 @@
+/**
+ * lib/ui.js — shared CLI presentation: banner, section headers, severity colors,
+ * and a global step progress indicator for the cache/database update phase.
+ *
+ * The Progress indicator renders a "[n/N] <spinner> label — summary" checklist.
+ * TTY: one animated line per step, rewritten in place, finalized with ✓/⊘/✗.
+ * Non-TTY (pipes, CI, files): a single plain line per finished step, no escapes.
+ */
+const chalk = require("chalk");
+
+const isTTY = !!(process.stdout && process.stdout.isTTY) && process.env.TERM !== "dumb";
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+const TITLE_A = "fad-checker";
+const TITLE_B = "Autonomous Dependency Checker";
+
+function banner() {
+	const raw = `${TITLE_A} · ${TITLE_B}`;
+	const bar = "─".repeat(raw.length + 2);
+	console.log(chalk.cyan(`\n╭${bar}╮`));
+	console.log(chalk.cyan("│ ") + chalk.bold.white(TITLE_A) + chalk.cyan(" · ") + chalk.whiteBright(TITLE_B) + chalk.cyan(" │"));
+	console.log(chalk.cyan(`╰${bar}╯`));
+}
+
+function section(title) {
+	console.log(chalk.bold.cyan("\n▸ ") + chalk.bold(title));
+}
+
+// "  label   value" aligned key/value line under a section.
+function kv(label, value, { pad = 10 } = {}) {
+	console.log("  " + chalk.dim(String(label).padEnd(pad)) + " " + value);
+}
+
+function ok(msg) { console.log("  " + chalk.green("✓") + " " + msg); }
+function warn(msg) { console.log("  " + chalk.yellow("⚠") + " " + msg); }
+function info(msg) { console.log("  " + chalk.dim("·") + " " + msg); }
+
+function sevColor(sev) {
+	switch (String(sev || "").toUpperCase()) {
+		case "CRITICAL": return chalk.bold.red;
+		case "HIGH": return chalk.red;
+		case "MEDIUM": return chalk.yellow;
+		case "LOW": return chalk.blue;
+		default: return chalk.gray;
+	}
+}
+
+class Step {
+	constructor(n, total, label) {
+		this.n = n; this.total = total; this.label = label;
+		this.live = ""; this.frame = 0; this.timer = null; this.ended = false;
+		this.prefix = chalk.dim(`[${n}/${total}]`);
+		if (isTTY) {
+			this._render();
+			this.timer = setInterval(() => { this.frame++; this._render(); }, 80);
+			if (this.timer.unref) this.timer.unref();
+		}
+	}
+	_render() {
+		if (!isTTY || this.ended) return;
+		const sp = chalk.cyan(SPINNER[this.frame % SPINNER.length]);
+		const live = this.live ? chalk.dim(" " + this.live) : chalk.dim(" …");
+		process.stdout.write(`\r  ${this.prefix} ${sp} ${this.label}${live}\x1b[K`);
+	}
+	tick(processed, total) {
+		this.live = total ? `${processed}/${total}` : String(processed || "");
+		// rendering is driven by the timer; nothing to print on non-TTY
+	}
+	_finalize(symbol, color, summary) {
+		if (this.ended) return;
+		this.ended = true;
+		if (this.timer) { clearInterval(this.timer); this.timer = null; }
+		const line = `  ${this.prefix} ${color(symbol)} ${this.label}` + (summary ? chalk.dim(" — " + summary) : "");
+		if (isTTY) process.stdout.write(`\r${line}\x1b[K\n`);
+		else console.log(line);
+	}
+	done(summary) { this._finalize("✓", chalk.green, summary); }
+	skip(reason) { this._finalize("⊘", chalk.gray, reason); }
+	fail(msg) { this._finalize("✗", chalk.red, msg); }
+}
+
+class Progress {
+	constructor(total) { this.total = total || 0; this.n = 0; }
+	start(label) { this.n += 1; return new Step(this.n, this.total, label); }
+}
+
+module.exports = { banner, section, kv, ok, warn, info, sevColor, Progress, isTTY };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fad-checker",
-  "version": "2.0.0",
-  "description": "Scans ALL Maven, npm, Yarn, Composer, Python, C#/.NET in a source tree ONE SHOT Alone like a big boy, deal with private deps, multi mvn modules, EOL, obsolete, outdated deps & give fix recos",
+  "version": "2.0.1",
+  "description": "Scan ALL Maven, npm, Yarn, Composer, Python & C#/.NET dependencies in a source tree ONE SHOT without mvn/python/etc, deal with private deps, multi mvn modules, EOL, obsolete, outdated deps & give fix recos",
   "license": "MIT",
   "repository": "https://github.com/n8tz/fad-checker",
   "author": "pp9Ping <pp9Ping@gmail.com>",
@@ -25,6 +25,7 @@
   "dependencies": {
     "chalk": "^4.1.2",
     "commander": "^14.0.1",
+    "js-yaml": "^4.1.1",
     "p-limit": "^3.1.0",
     "retire": "^5.4.2",
     "rimraf": "^6.0.1",

package/CLAUDE.md

@@ -1,147 +0,0 @@
-# CLAUDE.md
-
-Code-level orientation for contributors and Claude Code sessions on this repo.
-
-## What this is
-
-`fad-checker` — **Fucking Autonomous Dependency Checker**. Node.js CLI (`fad-checker`, or short alias `fad`) that:
-
-1. Walks a multi-module Maven tree, removes private/excluded dependencies (regex on groupId), writes a parallel directory of "cleaned" POMs that can be fed to Snyk.
-2. Walks every JS package (`package.json` + `package-lock.json` v1/v2/v3 or `yarn.lock` v1), every PHP package (`composer.lock`, or `composer.json` best-effort), and every Python project (`poetry.lock`/`Pipfile.lock`/`uv.lock`/`pdm.lock`, or `requirements.txt` best-effort), and every .NET project (`packages.lock.json`, or `*.csproj`+`Directory.Packages.props`/`packages.config` best-effort) in the same source tree. Each ecosystem is a **codec** (`lib/codecs/`): maven, npm, yarn, composer, pypi, nuget. Adding one is adding a codec.
-3. Scans the union against:
-   - the CVEProject `cvelistV5` Maven-relevant index (built locally),
-   - OSV.dev (multi-ecosystem),
-   - NIST NVD (enrichment: CVSS, CPE configurations, references),
-   - retire.js (vendored JS signatures),
-   - optionally Snyk (`--snyk`).
-4. Cross-checks every match's NVD CPE configurations against the dep version (`lib/cpe.js`) to filter false positives.
-5. Reports EOL frameworks (endoflife.date — Maven & npm), obsolete libs (curated Maven + npm-registry per-version `deprecated` field — authoritative, skips nothing), outdated libs (Maven Central + npm registry `dist-tags.latest`). **WebJars** (`org.webjars*`) are reduced to their npm coordinate by `webjarToNpm()` and run through the npm EOL/deprecation/outdated paths — so e.g. `org.webjars:angularjs:1.8.3` is flagged EOL.
-6. Produces a self-contained HTML report + Word-compatible `.doc`, organised by ecosystem and by defining manifest, with per-tool fix recipes and an executive summary.
-
-No build tool (`mvn`, `npm install`, `yarn`) is required on PATH — `pom.xml` / `package-lock.json` / `yarn.lock` are parsed directly.
-
-## Running
-
-```bash
-npm install
-npm test                  # 194 unit tests via node --test
-
-# basic cleanup workflow
-node fad-checker.js -s ./proj                                        # read-only, full report
-node fad-checker.js -s ./proj -t ../pom-clean -e "^client\\."        # write cleaned tree
-node fad-checker.js -s ./proj -t ../pom-clean -e "^client\\." --snyk # also drive snyk
-
-# read the full usage doc
-cat docs/USAGE.md
-```
-
-Binary builds (requires `bun`):
-
-```bash
-npm run build:linux   # → dist/fad-checker-linux
-npm run build:win     # → dist/fad-checker.exe
-npm run build         # both
-```
-
-Guardrails enforced at startup:
-- `--target` is required only when you want a cleaned POM tree. Without it the run is read-only.
-- `--target` may not equal or be a subdirectory of `--src`.
-- `--target` is `rimraf`'d before being rewritten — never point at anything precious.
-
-## Architecture (one-liner per file)
-
-```
-fad-checker.js                 Thin CLI: commander parsing, orchestration only (loops over active codecs).
-lib/codecs/index.js          Codec registry: getCodec / allCodecs / detectCodecs.
-lib/codecs/codec.interface.js  Codec contract + assertCodecShape() validator.
-lib/codecs/maven.codec.js    Maven codec (wraps core.js + transitive.js + CVE-index scanner).
-lib/codecs/npm.codec.js      npm codec (wraps lib/codecs/npm/* + retire.js scanner). yarn.codec.js shares it.
-lib/codecs/select.js         resolveActiveCodecs(): --ecosystem list + --no-<id> → active codec ids.
-lib/codecs/recipes.js        Per-ecosystem fix-recipe specs (pin snippet + direct-update wording).
-lib/codecs/composer.codec.js   Composer (PHP) codec.
-lib/codecs/composer/parse.js        composer.lock + composer.json parsers.
-lib/codecs/composer/registry.js     Packagist query → latest stable + `abandoned` flag.
-lib/codecs/pypi.codec.js     PyPI (Python) codec.
-lib/codecs/pypi/parse.js          poetry.lock/Pipfile.lock/uv.lock/pdm.lock (smol-toml) + requirements.txt parsers (PEP 503).
-lib/codecs/pypi/registry.js       PyPI JSON query → latest + yanked + inactive classifier.
-lib/codecs/nuget.codec.js    NuGet (C#/.NET) codec.
-lib/codecs/nuget/parse.js           packages.lock.json + *.csproj (+CPM Directory.Packages.props) + packages.config parsers.
-lib/codecs/nuget/registry.js        NuGet registration query → latest stable + per-version deprecation.
-lib/dep-record.js            makeDepRecord(): generalized depRecord ({ ecosystem, namespace, name, coordKey, … }).
-lib/core.js                  POM parsing, parent resolution, all-profile merge, rewrite.
-lib/maven-version.js         Maven version parsing + range comparison (no external deps).
-lib/cve-download.js          Bulk download of CVEProject/cvelistV5 + Maven-relevant index build.
-lib/cve-match.js             Resolved-dep collection + 3-tier CVE matching with dedup.
-lib/cve-report.js            Self-contained HTML and Word-compatible (.doc) report rendering.
-lib/cpe.js                   CPE 2.3 parsing + NVD configurations evaluator (post-match refinement).
-lib/outdated.js              EOL (endoflife.date), obsolete (curated), outdated (Maven Central).
-lib/transitive.js            Maven Central POM walker (transitive resolution).
-lib/osv.js                   OSV.dev batched query + per-vuln detail fetch.
-lib/nvd.js                   NIST NVD enrichment (CVSS, references, CPE configurations).
-lib/snyk.js                  `snyk test --all-projects --json` runner + merge.
-lib/retire.js                retire.js (vendored-JS scanner) wrapper + cache + normaliser.
-lib/scan-completeness.js     Warnings for deps fad-checker couldn't fully resolve.
-lib/codecs/npm/parse.js             package.json, package-lock.json (v1/2/3), yarn.lock v1 parsers.
-lib/codecs/npm/collect.js           Merge across JS manifests → unified resolvedDeps Map.
-lib/codecs/npm/registry.js          npm registry packument query → per-version deprecation + dist-tags.latest (npm EOL feeds via lib/outdated.js).
-lib/cache-archive.js         tar.gz / zip export & import of ~/.fad-checker/.
-lib/config.js                Persistent user config in ~/.fad-checker/config.json (mode 0600).
-data/                        known-obsolete.json, eol-mapping.json, cpe-coord-map.json, known-public-namespaces.json
-completions/                 fad-checker.bash, fad-checker.zsh
-test/                        node:test suite + fixtures (simple, complex-enterprise, monorepo-mixed, …).
-```
-
-For the deep dive — pipeline stages, the resolved-deps Map shape, report structure — see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
-
-## Important conventions
-
-- **`coord()` always trims**: real-world POMs occasionally contain whitespace around `<artifactId>`. Every coord-derived lookup goes through `coord()` in `lib/core.js`.
-- **`byId` keys are never polluted with `undefined`**: only indexed when both `groupId` and `artifactId` are present. Enforced by test.
-- **All profiles are merged, never prompted for**: every profile's deps are unioned so Snyk sees every dep any profile could pull in. `activeByDefault` wins only for property value conflicts.
-- **No `process.exit(1)` mid-pipeline**: a parse/rewrite failure for one POM logs and continues so the summary still prints.
-- **HTML report is self-contained**: inline CSS, no external assets. The `.doc` variant is the same HTML with Office XML namespace meta tags — Word opens it natively.
-- **Codec abstraction**: every ecosystem lives behind a codec (`lib/codecs/*`) implementing one interface (`detect`/`collect`/`coordKey`/`formatCoord`/`osvPackageName`/`checkRegistry`/`resolveEolProduct`/`recipe`/`nativeScanners`). The orchestrator loops over the codecs `detectCodecs()` returns. OSV/NVD/CPE and the endoflife.date fetch are **shared, ecosystem-agnostic** services that ask the codec for a package/product name. CVE-index (maven) and retire.js (npm) are `nativeScanners` owned by their codec. Adding an ecosystem = adding a codec, no orchestrator edits.
-- **Map keys are ecosystem-namespaced** (`dep.coordKey`): Maven uses a **bare** `g:a` (kept prefix-free so `transitive.js` internals and existing tests are untouched); npm uses `npm:name`; new ecosystems use `nuget:`/`composer:vendor/pkg`/`pypi:`. Bare `g:a` is collision-free against those prefixes. Built by `makeDepRecord()`; `groupId`/`artifactId`/`pomPaths` are kept as real duplicated alias fields (not getters — depRecords are spread in hot paths).
-- **Every distinct version is scanned, not just the highest**: when profiles/modules pin the same `g:a` to different versions, the resolved-dep entry keeps `version` = highest (representative for display/EOL/outdated) but `versions` = all distinct concrete versions. CVE matching (`matchOne`) and OSV (`queryOsvForDeps`) iterate `versions` so a vuln affecting only a lower-versioned profile variant isn't missed. Match dedup keys are `g:a:version|cve.id` (version included) to preserve per-version findings.
-- **npm no-lockfile = best-effort (not skipped)**: `package.json` without a sibling `package-lock.json`/`yarn.lock` is parsed best-effort — pinned exact versions (`"1.2.3"`) are scanned, ranges (`"^1.0.0"`) are skipped, and a `no-lockfile` warning (chapter 0) flags the partial coverage. (Earlier versions skipped such manifests entirely.)
-- **`--ecosystem` is a list**: `auto` (default = `detectCodecs()`) | `all` | comma list `maven,npm,nuget,composer,pypi` (legacy `both`/`maven`/`npm` still parse). Per-codec opt-out via `--no-maven`/`--no-npm`/`--no-yarn`/`--no-nuget`/`--no-composer`/`--no-pypi`; `--no-js` is an alias for `--no-npm`+`--no-yarn`.
-- **Source identifiers**: every match carries `source: "fad" | "osv" | "nvd" | "snyk" | "retire"` (or a `+`-joined combination).
-
-## Testing
-
-```bash
-node --test test/*.test.js            # full suite (96 tests)
-node --test test/core.test.js         # one file
-```
-
-Test fixtures live in `test/fixtures/`:
-- `simple/` — 3 POMs with parent inheritance + property substitution
-- `complex-enterprise/` — Spring Boot parent (external), local BOM via `scope=import`, three profiles
-- `private-lib-detection/` — mixed public/private groupIds, external private parent
-- `monorepo-mixed/` — Maven + npm (package-lock v3) + yarn.lock v1 + a no-lockfile package.json
-- `cve-samples/` — small CVE / NVD JSON files for the matchers
-
-## Gotchas / edge cases worth knowing
-
-- CVE bundle from CVEProject is ~500 MB unpacked. Shells out to `curl + unzip` (fallback to `fetch()` + `unzip` / `Expand-Archive`). Extracted JSON deleted after index build. Ships as `cves.zip.zip` (nested zip) — `extractZip()` recurses up to 3 levels.
-- `endoflife.date` API responses cached 7 days; Maven Central version lookups cached 24 hours. Cache lives in `~/.fad-checker/`.
-- **Persistent config**: `~/.fad-checker/config.json` (mode 0600). Set NVD key via `fad-checker --set-nvd-key <KEY>` (free, instant from <https://nvd.nist.gov/developers/request-an-api-key> — bumps rate limit from 5/30s to 50/30s).
-- **`--offline` umbrella flag**: skips every network call (CVE/OSV/NVD/Maven Central/endoflife/npm-registry/retire). Falls back to whatever is already cached. Per-source variants (`--cve-offline`, `--no-osv`, `--no-nvd`, `--no-retire`, `--no-transitive`) and per-codec toggles (`--no-maven`/`--no-npm`/`--no-yarn`/`--no-nuget`/`--no-composer`/`--no-pypi`, `--no-js`) still work independently. npm registry deprecation always runs when online; npm (and Maven) outdated is gated by `--no-all-libs`.
-- `snyk` is not a hard dep — shells out via `execFile`. `snyk` exits 1 on findings; the JSON is still on stdout.
-- The cleaned POM is the union of every profile's deps. Counts will be larger than the source POM. Intentional — don't "fix" that.
-- Unresolved `${…}` Maven variables stay verbatim in the rewritten POM. `lib/cve-match.js` resolves them lazily via `resolveDepVersion()` when scanning. Deps that *still* can't be resolved (external BOM not in source tree) surface in chapter 0 as `unresolved-versions` warnings.
-- **retire.js** doesn't like `--outputpath /dev/stdout`. We write to a temp file and read it back. Exit code 13 means "vulns found" — expected, not an error.
-
-### Per-cache TTLs
-
-| Cache | Location | TTL |
-|---|---|---|
-| CVEProject bulk index | `~/.fad-checker/cve-data/maven-cve-index.json` | 24 h |
-| OSV per-dep stub list | `~/.fad-checker/osv-cache/<eco>__<g>__<a>__<v>.json` | 12 h |
-| OSV vuln details | `~/.fad-checker/osv-cache/vuln_<id>.json` | 12 h |
-| NVD CVE record | `~/.fad-checker/nvd-cache/<cveId>.json` | 7 d |
-| endoflife.date cycles | `~/.fad-checker/eol-cache.json` | 7 d |
-| Maven Central latest | `~/.fad-checker/version-cache.json` | 24 h |
-| npm registry (deprecation + latest) | `~/.fad-checker/npm-registry-cache.json` | 24 h |
-| Transitive POM | `~/.fad-checker/poms-cache/<g>__<a>__<v>.pom` | ∞ (immutable on Maven Central) |
-| retire.js findings | `~/.fad-checker/retire-cache/<md5(src)>.json` | 24 h |