fad-checker 2.0.0 → 2.1.0

package/lib/deps-descriptor.js

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+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/epss.js

@@ -0,0 +1,115 @@
+/**
+ * lib/epss.js — enrich matches with EPSS (Exploit Prediction Scoring System).
+ *
+ * EPSS gives the probability (0-1) a CVE will be exploited in the next 30 days,
+ * plus a percentile rank against all scored CVEs. FIRST.org recomputes it daily.
+ *
+ * API: https://api.first.org/data/v1/epss?cve=CVE-a,CVE-b,…  (batch ≤ ~100)
+ * Cache: ~/.fad-checker/epss-cache.json, 24h TTL (aligned with the daily refresh).
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const CACHE_DIR = path.join(os.homedir(), ".fad-checker");
+const CACHE_PATH = path.join(CACHE_DIR, "epss-cache.json");
+const CACHE_TTL_MS = 24 * 3600 * 1000;
+const EPSS_BASE = "https://api.first.org/data/v1/epss";
+const BATCH = 100;
+
+function loadCache() {
+	try { return JSON.parse(fs.readFileSync(CACHE_PATH, "utf8")); }
+	catch { return { meta: { fetchedAt: 0 }, entries: {} }; }
+}
+
+function saveCache(data) {
+	try {
+		fs.mkdirSync(CACHE_DIR, { recursive: true });
+		fs.writeFileSync(CACHE_PATH, JSON.stringify(data));
+	} catch { /* ignore */ }
+}
+
+/** Pure: FIRST.org JSON → Map<cveId, {score, percentile}>. */
+function parseEpssResponse(json) {
+	const out = new Map();
+	for (const row of json?.data || []) {
+		if (!row?.cve) continue;
+		const score = parseFloat(row.epss);
+		const percentile = parseFloat(row.percentile);
+		out.set(row.cve, {
+			score: Number.isFinite(score) ? score : null,
+			percentile: Number.isFinite(percentile) ? percentile : null,
+		});
+	}
+	return out;
+}
+
+function chunk(arr, n) {
+	const out = [];
+	for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n));
+	return out;
+}
+
+/**
+ * Enrich matches in place with cve.epssScore / cve.epssPercentile.
+ * opts: { offline, verbose, fetcher, onProgress }
+ */
+async function enrichEpss(matches, opts = {}) {
+	const { offline, verbose, fetcher = globalThis.fetch, onProgress } = opts;
+	const ids = new Set();
+	for (const m of matches || []) if (m.cve?.id?.startsWith("CVE-")) ids.add(m.cve.id);
+	if (!ids.size) return matches;
+
+	const cache = loadCache();
+	const fresh = cache.meta?.fetchedAt && (Date.now() - cache.meta.fetchedAt) < CACHE_TTL_MS;
+	if (!fresh && !offline) cache.entries = {};
+
+	const byId = new Map();
+	const liveIds = [];
+	for (const id of ids) {
+		if (cache.entries[id]) byId.set(id, cache.entries[id]);
+		else if (offline) byId.set(id, null);
+		else liveIds.push(id);
+	}
+
+	let done = 0;
+	const total = liveIds.length;
+	const report = () => { if (onProgress) onProgress(done, total); };
+	for (const group of chunk(liveIds, BATCH)) {
+		try {
+			const url = `${EPSS_BASE}?cve=${encodeURIComponent(group.join(","))}`;
+			const r = await fetcher(url, { headers: { "User-Agent": "fad-checker-epss" } });
+			if (r.ok) {
+				const parsed = parseEpssResponse(await r.json());
+				for (const id of group) {
+					// Not every CVE has an EPSS score; cache the null so we don't refetch.
+					const v = parsed.get(id) || { score: null, percentile: null };
+					cache.entries[id] = v;
+					byId.set(id, v);
+				}
+			} else if (verbose) {
+				console.warn(`   EPSS HTTP ${r.status}`);
+			}
+		} catch (err) {
+			if (verbose) console.warn(`   EPSS fetch failed: ${err.message}`);
+		}
+		done += group.length;
+		report();
+	}
+
+	cache.meta = { fetchedAt: fresh ? cache.meta.fetchedAt : Date.now() };
+	if (!offline) saveCache(cache);
+
+	for (const m of matches || []) {
+		const v = byId.get(m.cve?.id);
+		if (!v) continue;
+		if (v.score != null) m.cve.epssScore = v.score;
+		if (v.percentile != null) m.cve.epssPercentile = v.percentile;
+	}
+	return matches;
+}
+
+module.exports = { enrichEpss, parseEpssResponse, CACHE_PATH };

package/lib/gate.js

@@ -0,0 +1,45 @@
+/**
+ * lib/gate.js — CI gating: decide whether a finding set should fail the build.
+ *
+ * Levels: none | low | medium | high | critical | kev. A severity level fails
+ * when any (non-suppressed) match is at or above it; `kev` fails only on a CISA
+ * known-exploited finding — the modern "patch what's actually attacked" gate.
+ * Pure — the caller sets process.exitCode.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+
+const SEV_RANK = { none: 0, low: 1, medium: 2, high: 3, critical: 4 };
+
+/**
+ * evaluateGate(matches, level) → { failed, reason, count, level }.
+ * `matches` should already exclude cpe-filtered/dev — typically the prodActive set.
+ */
+function evaluateGate(matches, level) {
+	const lvl = String(level || "none").toLowerCase();
+	const active = (matches || []).filter(m => !m.suppressed);
+	if (lvl === "none") return { failed: false, reason: "gating disabled", count: 0, level: lvl };
+
+	if (lvl === "kev") {
+		const hits = active.filter(m => m.cve?.kev);
+		return {
+			failed: hits.length > 0,
+			count: hits.length,
+			level: lvl,
+			reason: hits.length ? `${hits.length} known-exploited (CISA KEV) finding(s)` : "no known-exploited finding",
+		};
+	}
+
+	const threshold = SEV_RANK[lvl];
+	if (threshold == null) return { failed: false, reason: `unknown level "${lvl}"`, count: 0, level: lvl };
+	const hits = active.filter(m => (SEV_RANK[(m.cve?.severity || "none").toLowerCase()] ?? 0) >= threshold);
+	return {
+		failed: hits.length > 0,
+		count: hits.length,
+		level: lvl,
+		reason: hits.length ? `${hits.length} finding(s) at or above ${lvl}` : `no finding at or above ${lvl}`,
+	};
+}
+
+module.exports = { evaluateGate, SEV_RANK };

package/lib/json-export.js

@@ -0,0 +1,110 @@
+/**
+ * lib/json-export.js — emit a single machine-readable findings document.
+ *
+ * Unlike the CycloneDX SBOM (component-centric) or CSAF VEX (status-centric),
+ * this is fad-checker's own flat findings format: every chapter (CVE, EOL,
+ * obsolete, outdated, licenses, vendored) in one JSON, easy to diff between
+ * audits and post-process. buildFindings is pure; writeFindings writes it.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const { purlFor } = require("./purl");
+
+function coordOf(dep) {
+	const ns = dep.namespace || dep.groupId || "";
+	const name = dep.name || dep.artifactId;
+	if (dep.ecosystem === "maven" && ns) return `${ns}:${name}`;
+	if (dep.ecosystem === "composer" && ns) return `${ns}/${name}`;
+	return name;
+}
+
+function depBrief(dep) {
+	return {
+		ecosystem: dep.ecosystem,
+		coord: coordOf(dep),
+		version: dep.version || null,
+		scope: dep.scope || null,
+		isDev: !!dep.isDev,
+		provenance: dep.provenance || "manifest",
+		purl: purlFor(dep),
+		manifestPaths: dep.manifestPaths || dep.pomPaths || [],
+	};
+}
+
+function cveFinding(m) {
+	const c = m.cve;
+	return {
+		id: c.id,
+		severity: c.severity || "UNKNOWN",
+		cvss: c.score ?? null,
+		cvssVector: c.cvssVector || null,
+		epss: c.epssScore ?? null,
+		epssPercentile: c.epssPercentile ?? null,
+		kev: !!c.kev,
+		kevDueDate: c.kevDueDate || null,
+		priority: c.priority ? { band: c.priority.band, score: c.priority.score } : null,
+		cwes: c.cwes || [],
+		fixVersion: c.fixVersion || null,
+		source: m.source || null,
+		confidence: m.confidence || null,
+		cpeFiltered: !!m.cpeFiltered,
+		suppressed: !!m.suppressed,
+		suppressedReason: m.suppressedReason || null,
+		dep: depBrief(m.dep),
+	};
+}
+
+const SEV = ["critical", "high", "medium", "low", "none", "unknown"];
+
+/**
+ * Build the findings document.
+ * payload: { cveMatches, retireMatches, eolResults, obsoleteResults,
+ *            outdatedResults, licenseResults, resolvedDeps, projectInfo, toolVersion }
+ */
+function buildFindings(payload = {}) {
+	const {
+		cveMatches = [], retireMatches = [], eolResults = [], obsoleteResults = [],
+		outdatedResults = [], licenseResults = null, resolvedDeps, projectInfo = {}, toolVersion = "0",
+	} = payload;
+
+	const sevCounts = Object.fromEntries(SEV.map(s => [s, 0]));
+	let kev = 0;
+	for (const m of cveMatches) {
+		if (m.cpeFiltered || m.suppressed) continue;
+		const s = (m.cve.severity || "unknown").toLowerCase();
+		sevCounts[s != null && sevCounts[s] != null ? s : "unknown"]++;
+		if (m.cve.kev) kev++;
+	}
+
+	return {
+		tool: { name: "fad-checker", version: String(toolVersion) },
+		generatedAt: projectInfo.generatedAt || null,
+		project: { name: projectInfo.name || null, src: projectInfo.src || null },
+		summary: {
+			dependencies: resolvedDeps?.size ?? null,
+			cve: { ...sevCounts, kev, total: cveMatches.filter(m => !m.cpeFiltered && !m.suppressed).length },
+			eol: eolResults.length,
+			obsolete: obsoleteResults.length,
+			outdated: outdatedResults.length,
+			licensesFlagged: licenseResults?.flagged?.length || 0,
+			vendored: retireMatches.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) })),
+		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) })),
+	};
+}
+
+function writeFindings(payload, outputPath) {
+	const doc = buildFindings(payload);
+	fs.writeFileSync(outputPath, JSON.stringify(doc, null, 2) + "\n");
+	return doc;
+}
+
+module.exports = { buildFindings, writeFindings };

package/lib/kev.js

@@ -0,0 +1,88 @@
+/**
+ * lib/kev.js — enrich matches with CISA KEV (Known Exploited Vulnerabilities).
+ *
+ * KEV is a single authoritative catalogue of CVEs CISA has observed being
+ * exploited in the wild. Membership is the strongest "patch this now" signal.
+ *
+ * Feed: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
+ * Cache: ~/.fad-checker/kev-cache.json, 24h TTL.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const CACHE_DIR = path.join(os.homedir(), ".fad-checker");
+const CACHE_PATH = path.join(CACHE_DIR, "kev-cache.json");
+const CACHE_TTL_MS = 24 * 3600 * 1000;
+const KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json";
+
+function readCache() {
+	try {
+		const data = JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
+		if (Date.now() - data._fetchedAt < CACHE_TTL_MS) return data.body;
+	} catch { /* ignore */ }
+	return null;
+}
+
+function writeCache(body) {
+	try {
+		fs.mkdirSync(CACHE_DIR, { recursive: true });
+		fs.writeFileSync(CACHE_PATH, JSON.stringify({ _fetchedAt: Date.now(), body }));
+	} catch { /* ignore */ }
+}
+
+/** Pure: KEV catalogue JSON → { byId: { cveID: {dateAdded, dueDate, ransomware} } }. */
+function indexKevCatalog(json) {
+	const byId = {};
+	for (const v of json?.vulnerabilities || []) {
+		if (!v?.cveID) continue;
+		byId[v.cveID] = {
+			dateAdded: v.dateAdded || null,
+			dueDate: v.dueDate || null,
+			ransomware: /^known$/i.test(v.knownRansomwareCampaignUse || ""),
+		};
+	}
+	return { byId };
+}
+
+/**
+ * Enrich matches in place: sets cve.kev / cve.kevDateAdded / cve.kevDueDate /
+ * cve.kevRansomware for CVEs present in the catalogue.
+ * opts: { offline, verbose, fetcher }
+ */
+async function enrichKev(matches, opts = {}) {
+	const { offline, verbose, fetcher = globalThis.fetch } = opts;
+	const hasCve = (matches || []).some(m => m.cve?.id?.startsWith("CVE-"));
+	if (!hasCve) return matches;
+
+	let index = readCache();
+	if (!index && !offline) {
+		try {
+			const r = await fetcher(KEV_URL, { headers: { "User-Agent": "fad-checker-kev" } });
+			if (r.ok) {
+				index = indexKevCatalog(await r.json());
+				writeCache(index);
+			} else if (verbose) {
+				console.warn(`   KEV HTTP ${r.status}`);
+			}
+		} catch (err) {
+			if (verbose) console.warn(`   KEV fetch failed: ${err.message}`);
+		}
+	}
+	if (!index) return matches;
+
+	for (const m of matches || []) {
+		const hit = index.byId[m.cve?.id];
+		if (!hit) continue;
+		m.cve.kev = true;
+		m.cve.kevDateAdded = hit.dateAdded;
+		m.cve.kevDueDate = hit.dueDate;
+		m.cve.kevRansomware = hit.ransomware;
+	}
+	return matches;
+}
+
+module.exports = { enrichKev, indexKevCatalog, CACHE_PATH };

package/lib/license-policy.js

@@ -0,0 +1,110 @@
+/**
+ * lib/license-policy.js — normalize free-form license strings to SPDX ids and
+ * classify them into policy categories (permissive / copyleft / proprietary).
+ *
+ * Data-driven: data/license-policy.json holds the id→category table and an
+ * alias map for the messy real-world strings registries and POMs emit
+ * ("Apache 2.0", "The MIT License", "GNU GPLv3", …). Pure — no I/O at call time.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+
+const POLICY = (() => {
+	try {
+		const raw = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "data", "license-policy.json"), "utf8"));
+		return { categories: raw.categories || {}, aliases: raw.aliases || {} };
+	} catch { return { categories: {}, aliases: {} }; }
+})();
+
+// Case-insensitive index of canonical SPDX ids for direct matches.
+const CANON_BY_LOWER = new Map(Object.keys(POLICY.categories).map(id => [id.toLowerCase(), id]));
+
+const FLAGGED_CATEGORIES = new Set(["strong-copyleft", "network-copyleft", "proprietary", "unknown"]);
+// Most-restrictive-wins order when a dep has several licenses.
+const CATEGORY_RANK = { permissive: 1, unknown: 2, "weak-copyleft": 3, proprietary: 4, "strong-copyleft": 5, "network-copyleft": 6 };
+
+/** Normalize one license token to a canonical SPDX id, or null if unknown. */
+function normalizeSpdx(raw) {
+	if (raw == null) return null;
+	// npm sometimes uses { type, url } objects.
+	const s = (typeof raw === "object" ? (raw.type || raw.name || "") : String(raw)).trim();
+	if (!s) return null;
+	const lower = s.toLowerCase();
+	if (CANON_BY_LOWER.has(lower)) return CANON_BY_LOWER.get(lower);
+	if (POLICY.aliases[lower]) return POLICY.aliases[lower];
+	// Tolerate a trailing "+" (or-later) and "-only" decorations.
+	const stripped = lower.replace(/\+$/, "").trim();
+	if (CANON_BY_LOWER.has(stripped)) return CANON_BY_LOWER.get(stripped);
+	if (POLICY.aliases[stripped]) return POLICY.aliases[stripped];
+	return null;
+}
+
+/** Split an SPDX expression / array / "A OR B" / "A/B" string into raw tokens. */
+function splitExpression(raw) {
+	if (Array.isArray(raw)) return raw.flatMap(splitExpression);
+	if (raw == null) return [];
+	if (typeof raw === "object") return [raw.type || raw.name || ""].filter(Boolean);
+	return String(raw)
+		.replace(/[()]/g, " ")
+		.split(/\s+(?:OR|AND)\s+|\s+WITH\s+|[,/|]/i)
+		.map(t => t.trim())
+		.filter(Boolean);
+}
+
+/** Category for a canonical SPDX id (defaults to "unknown"). */
+function classify(spdxId) {
+	if (!spdxId) return "unknown";
+	return POLICY.categories[spdxId] || "unknown";
+}
+
+/**
+ * Resolve a dep's raw license value(s) into { ids, raw, category }.
+ * `ids` are canonical SPDX (raw token kept when unmapped); `category` is the
+ * most restrictive among them.
+ */
+function resolveDepLicense(rawValue) {
+	const tokens = splitExpression(rawValue);
+	if (!tokens.length) return { ids: [], raw: [], category: "unknown" };
+	const ids = [];
+	const rawKept = [];
+	let best = "permissive";
+	let bestRank = 0;
+	let anyKnown = false;
+	for (const tok of tokens) {
+		const id = normalizeSpdx(tok);
+		if (id) { ids.push(id); anyKnown = true; } else rawKept.push(tok);
+		const cat = id ? classify(id) : "unknown";
+		const rank = CATEGORY_RANK[cat] || CATEGORY_RANK.unknown;
+		if (rank > bestRank) { bestRank = rank; best = cat; }
+	}
+	// All tokens unmapped → unknown overall.
+	if (!anyKnown) best = "unknown";
+	return { ids, raw: rawKept, category: best };
+}
+
+/**
+ * Assess a flat list of license findings.
+ * findings: [{ dep, licenses: <raw string|array|object>, source }]
+ * Returns { assessed: [{dep, source, ids, raw, category}], byCategory, flagged }.
+ */
+function assessLicenses(findings) {
+	const assessed = [];
+	const byCategory = {};
+	const flagged = [];
+	for (const f of findings || []) {
+		const r = resolveDepLicense(f.licenses);
+		const entry = { dep: f.dep, source: f.source || null, ids: r.ids, raw: r.raw, category: r.category };
+		assessed.push(entry);
+		(byCategory[r.category] = byCategory[r.category] || []).push(entry);
+		if (FLAGGED_CATEGORIES.has(r.category)) flagged.push(entry);
+	}
+	return { assessed, byCategory, flagged };
+}
+
+module.exports = {
+	normalizeSpdx, splitExpression, classify, resolveDepLicense, assessLicenses,
+	FLAGGED_CATEGORIES, CATEGORY_RANK,
+};

package/lib/maven-license.js

@@ -0,0 +1,52 @@
+/**
+ * lib/maven-license.js — best-effort Maven license detection, network-free.
+ *
+ * A declaring POM only lists a dependency's coordinate, not its license — the
+ * license lives in the dependency's OWN POM on Maven Central. transitive.js
+ * already caches those POMs under ~/.fad-checker/poms-cache/. We read the cached
+ * POMs (no network) and scrape the <licenses><license><name> block. Deps whose
+ * POM was never cached simply yield no license (→ unknown in the policy view).
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const { POM_CACHE_DIR } = require("./transitive");
+
+function cachedPomPath(g, a, v, dir) {
+	return path.join(dir, `${String(g).replace(/[/\\]/g, "_")}__${a}__${v}.pom`);
+}
+
+/** Pure: extract license names from a POM's <licenses> block. */
+function licensesFromPomXml(xml) {
+	if (!xml) return [];
+	const block = xml.match(/<licenses>([\s\S]*?)<\/licenses>/i);
+	if (!block) return [];
+	const names = [];
+	const re = /<name>\s*([^<]+?)\s*<\/name>/gi;
+	let m;
+	while ((m = re.exec(block[1]))) names.push(m[1].trim());
+	return names.filter(Boolean);
+}
+
+/**
+ * Collect license findings for every Maven dep with a cached POM.
+ * opts: { cacheDir = POM_CACHE_DIR }
+ * Returns [{ dep, licenses: [name…], source: "pom" }].
+ */
+function collectMavenLicenses(resolved, opts = {}) {
+	const cacheDir = opts.cacheDir || POM_CACHE_DIR;
+	const out = [];
+	for (const dep of resolved.values()) {
+		if (dep.ecosystem !== "maven" || !dep.version) continue;
+		const p = cachedPomPath(dep.namespace || dep.groupId, dep.name || dep.artifactId, dep.version, cacheDir);
+		let xml;
+		try { xml = fs.readFileSync(p, "utf8"); } catch { continue; }
+		const names = licensesFromPomXml(xml);
+		if (names.length) out.push({ dep, licenses: names, source: "pom" });
+	}
+	return out;
+}
+
+module.exports = { collectMavenLicenses, licensesFromPomXml };

package/lib/maven-repo.js

@@ -17,6 +17,9 @@
  *
  * The first 2xx wins. Misses are silently aggregated; the caller decides
  * what to do with "not found anywhere".
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 const MAVEN_CENTRAL = { name: "central", url: "https://repo1.maven.org/maven2/" };
 

package/lib/maven-version.js

@@ -9,6 +9,9 @@
  *       alpha < beta < milestone < rc < snapshot < "" (release) < sp
  *   - Trailing zeros are insignificant: 1.0 == 1.0.0 == 1.
  *   - Known release qualifiers (final, release, ga) are treated as "".
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 
 // Lower number == lower precedence
@@ -65,12 +68,14 @@ function cmpSegments(a, b) {
 	}
 	if (a.kind === "num" && b.kind === "num") return a.value - b.value;
 	if (a.kind === "num") {
-		// number vs qualifier — numbers are "newer" than pre-release qualifiers
-		const r = qualifierRank(b.value);
+		// number vs qualifier — numbers are "newer" than pre-release qualifiers.
+		// qualOf() reads the qualifier from BOTH str and qual+num segments (a bare
+		// `.value` is undefined for qual+num and would mis-rank e.g. "1.0.rc1").
+		const r = qualifierRank(qualOf(b));
 		return r < QUALIFIER_ORDER[""] ? 1 : -1;
 	}
 	if (b.kind === "num") {
-		const r = qualifierRank(a.value);
+		const r = qualifierRank(qualOf(a));
 		return r < QUALIFIER_ORDER[""] ? -1 : 1;
 	}
 	if (a.kind === "qual+num" && b.kind === "qual+num") {