fad-checker 1.0.0 → 1.0.2

package/docs/ARCHITECTURE.md

@@ -1,11 +1,11 @@
 # Architecture
 
-This is the deep-dive for anyone modifying `fad-check`'s internals or wondering why a particular finding shows up the way it does. For day-to-day usage, see [`USAGE.md`](USAGE.md).
+This is the deep-dive for anyone modifying `fad-checker`'s internals or wondering why a particular finding shows up the way it does. For day-to-day usage, see [`USAGE.md`](USAGE.md).
 
 ## Module map
 
 ```
-fad-check.js                 Thin CLI: commander parsing, orchestration only.
+fad-checker.js                 Thin CLI: commander parsing, orchestration only.
 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.
@@ -21,10 +21,10 @@ lib/retire.js                retire.js (vendored-JS scanner) wrapper + cache + n
 lib/scan-completeness.js     Warnings for deps we couldn't fully resolve.
 lib/npm/parse.js             package.json, package-lock.json (v1/2/3), yarn.lock v1 parsers.
 lib/npm/collect.js           Merge across JS manifests → unified resolvedDeps Map.
-lib/cache-archive.js         tar.gz / zip export & import of ~/.fad-check/.
-lib/config.js                Persistent user config in ~/.fad-check/config.json (mode 0600).
+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/                        Curated JSON: known-obsolete, eol-mapping, cpe-coord-map, known-public-namespaces.
-completions/                 fad-check.bash, fad-check.zsh
+completions/                 fad-checker.bash, fad-checker.zsh
 test/                        node:test suite + fixtures (simple, complex-enterprise, monorepo-mixed, …).
 ```
 
@@ -61,11 +61,11 @@ The Maven keyspace and npm keyspace never collide — `:lodash` (Maven groupId-l
 3. `getAllInheritedProps()` — merges `<dependencies>`, `<dependencyManagement>`, `<properties>` from **every** `<profile>` (with `activeByDefault` properties winning for value conflicts), follows `<scope>import</scope>` BOMs to other local POMs, and recurses into resolved parents.
 4. `rewritePoms()` — strips everything outside `nodeToKeep`, runs `cleanDeps()` to apply the `-e` regex, rewrites the `<parent>.relativePath` and `version` to the parent's value (not the child's). Skips disk writes when `readOnly`.
 
-## Report pipeline (driven by `fad-check.js` when `--report` is set)
+## Report pipeline (driven by `fad-checker.js` when `--report` is set)
 
 1. **Collect** — `collectResolvedDeps()` dedupes by `groupId:artifactId`, keeps the highest version on conflict, includes external parent POMs as `scope='parent'`. `--ignore-test` honored. For npm, `collectNpmDeps()` walks JS manifests (lockfile-only — `package.json` without sibling lockfile is skipped + warned).
 2. **Transitive expansion** (optional, `--transitive`) — `expandWithTransitives()` walks the Maven Central POM graph honouring exclusions, root depMgmt overrides, nearest-wins on version conflict, `--transitive-depth` cap. Skips test + optional scopes by default.
-3. **CVE index** — `ensureCveIndex()` downloads the daily CVEProject zip (via `curl + unzip`, or falls back to `fetch()` + `unzip` / PowerShell `Expand-Archive`), filters to Maven-relevant entries, caches the compact index to `~/.fad-check/cve-data/maven-cve-index.json`. Fresh for 24h. `--cve-refresh` forces rebuild, `--cve-offline` uses cache only.
+3. **CVE index** — `ensureCveIndex()` downloads the daily CVEProject zip (via `curl + unzip`, or falls back to `fetch()` + `unzip` / PowerShell `Expand-Archive`), filters to Maven-relevant entries, caches the compact index to `~/.fad-checker/cve-data/maven-cve-index.json`. Fresh for 24h. `--cve-refresh` forces rebuild, `--cve-offline` uses cache only.
 4. **CVE matching** — `matchDepsAgainstCves()` runs three tiers:
    - `exact`: `byPackageName["g:a"]` hit
    - `probable`: `byProduct[artifactId]` + vendor matches groupId (`apache` ↔ `org.apache.*`)
@@ -76,13 +76,13 @@ The Maven keyspace and npm keyspace never collide — `:lodash` (Maven groupId-l
 7. **CPE refinement** — `refineMatchesWithCpe()` walks NVD's `configurations[].nodes[]` against each matched dep:
    - Confirms the dep version actually falls in the vulnerable range (else `cpeFiltered: true` — likely false positive).
    - Upgrades match `confidence` from `possible` → `probable` → `exact` when a curated `cpe-coord-map.json` entry confirms vendor:product → dep coord.
-8. **retire.js** (default on) — shells out to `retire --outputformat json --jspath <src>`. Output normalised to fad-check match shape, with the vendored file path attached so the report can show where the offending `.js` lives. Cache: `~/.fad-check/retire-cache/<md5(src)>.json`, 24h TTL.
+8. **retire.js** (default on) — shells out to `retire --outputformat json --jspath <src>`. Output normalised to fad-checker match shape, with the vendored file path attached so the report can show where the offending `.js` lives. Cache: `~/.fad-checker/retire-cache/<md5(src)>.json`, 24h TTL.
 9. **EOL / Obsolete / Outdated** — `lib/outdated.js`:
    - **EOL**: matches dep coord against `data/eol-mapping.json`, fetches the cycle list from endoflife.date (cached 7d), flags cycles past their EOL date.
    - **Obsolete**: lookup in `data/known-obsolete.json` (curated: log4j 1.x, jackson-mapper-asl, joda-time, commons-httpclient 3.x, …).
    - **Outdated**: Maven Central Solr query for the latest version. Cache 24h. Concurrency 8.
 10. **Snyk** (optional, `--snyk`) — runs `snyk test --all-projects --json` against the cleaned target dir. Normalised + merged. Findings in both sources tagged `source: "both"`.
-11. **Render** — `writeReports()` produces `cve-report.html` (self-contained, inline CSS, no external assets) and `cve-report.doc` (same HTML with Office XML namespace meta tags so Word opens it natively). Default output dir: `./fad-check-report/`.
+11. **Render** — `writeReports()` produces `cve-report.html` (self-contained, inline CSS, no external assets) and `cve-report.doc` (same HTML with Office XML namespace meta tags so Word opens it natively). Default output dir: `./fad-checker-report/`.
 
 ## Report structure
 
@@ -130,7 +130,7 @@ The Maven keyspace and npm keyspace never collide — `:lodash` (Maven groupId-l
 - The CVE bundle from CVEProject is ~500 MB unpacked. We shell out to `curl + unzip` (Node built-in fallback to `fetch()` + system `unzip` / PowerShell `Expand-Archive`). The extracted JSON is deleted after the index is built.
 - The bundle ships as `cves.zip.zip` (a zip whose sole content is another zip). `extractZip()` recurses up to 3 levels.
 - `endoflife.date` API responses are cached locally for 7 days; Maven Central version lookups for 24 hours.
-- **Persistent config**: `~/.fad-check/config.json` (mode 0600) stores per-user state, currently the NVD API key. Set via `fad-check --set-nvd-key <KEY>`.
+- **Persistent config**: `~/.fad-checker/config.json` (mode 0600) stores per-user state, currently the NVD API key. Set via `fad-checker --set-nvd-key <KEY>`.
 - **`--offline` umbrella flag**: skips every network call (CVE index download, OSV queries, NVD enrichment, endoflife.date lookups, Maven Central version queries, transitive POM fetches, retire.js scans). Falls back to whatever is already cached. Per-source variants (`--cve-offline`, `--no-osv`, `--no-nvd`, `--no-retire`) still work independently.
 - `snyk` is not a dependency — we shell out via `execFile`. `snyk` exits 1 when it finds vulnerabilities, which is expected (the JSON is still on stdout).
 - The cleaned POM is the union of every profile's deps. Counts will therefore be larger than the source POM. This is intentional — verify your reasoning before "reducing" them.

package/docs/USAGE.md

@@ -5,7 +5,7 @@ Every flag, every common workflow, with copy-pasteable commands.
 ## Synopsis
 
 ```text
-fad-check -s <src> [-t <target>] [-e <regex>] [other options]
+fad-checker -s <src> [-t <target>] [-e <regex>] [other options]
 ```
 
 - `-s, --src <src>` — **required**. Root of the source tree to scan. Contains `pom.xml` and/or `package(-lock).json` / `yarn.lock`.
@@ -13,21 +13,21 @@ fad-check -s <src> [-t <target>] [-e <regex>] [other options]
 
 ## Output
 
-By default the HTML + Word reports land in `./fad-check-report/`. Override with `--report-output <dir>`.
+By default the HTML + Word reports land in `./fad-checker-report/`. Override with `--report-output <dir>`.
 
 ## Ecosystem selection
 
 ```bash
 # Auto-detect (default): scan whatever pom.xml / package(-lock).json / yarn.lock exists
-fad-check -s .
+fad-checker -s .
 
 # Force one ecosystem
-fad-check -s . --ecosystem maven
-fad-check -s . --ecosystem npm
-fad-check -s . --ecosystem both     # scan both even if only one is auto-detected
+fad-checker -s . --ecosystem maven
+fad-checker -s . --ecosystem npm
+fad-checker -s . --ecosystem both     # scan both even if only one is auto-detected
 
 # Disable JS scanning entirely (Maven-only)
-fad-check -s . --no-js
+fad-checker -s . --no-js
 ```
 
 ## Filtering deps
@@ -35,8 +35,8 @@ fad-check -s . --no-js
 `-e <regex>` filters out coords whose **groupId** (Maven) or **name** (npm) matches the regex. Useful for private/internal libs that you know aren't on a public registry.
 
 ```bash
-fad-check -s . -e "^(com\.acme|org\.private)\."
-fad-check -s . -e "^@acme/"
+fad-checker -s . -e "^(com\.acme|org\.private)\."
+fad-checker -s . -e "^@acme/"
 ```
 
 The excluded coords are listed at the end of the run so you can audit the regex.
@@ -59,18 +59,18 @@ Each data source can be disabled independently:
 
 ```bash
 # Use cached data only, no network (works for everything)
-fad-check -s . --offline
+fad-checker -s . --offline
 
 # Per-source offline
-fad-check -s . --cve-offline                  # use cached CVE index only
-fad-check -s . --cve-refresh                  # force re-download of CVE bundle
-fad-check -s . --retire-refresh               # force re-scan with retire.js (ignore cache)
+fad-checker -s . --cve-offline                  # use cached CVE index only
+fad-checker -s . --cve-refresh                  # force re-download of CVE bundle
+fad-checker -s . --retire-refresh               # force re-scan with retire.js (ignore cache)
 
 # Cache export / import (useful for air-gapped boxes)
-fad-check --export-cache fad-cache.tar.gz
-fad-check --export-cache fad-cache.tar.gz --include-config   # bundle NVD key too
-fad-check --import-cache fad-cache.tar.gz
-fad-check --import-cache fad-cache.tar.gz --force            # replace existing without backup
+fad-checker --export-cache fad-cache.tar.gz
+fad-checker --export-cache fad-cache.tar.gz --include-config   # bundle NVD key too
+fad-checker --import-cache fad-cache.tar.gz
+fad-checker --import-cache fad-cache.tar.gz --force            # replace existing without backup
 ```
 
 ## NVD API key
@@ -79,24 +79,24 @@ NVD's public rate limit is 5 requests / 30s without a key. The free key bumps it
 
 ```bash
 # Get a key in 30 seconds: https://nvd.nist.gov/developers/request-an-api-key
-fad-check --set-nvd-key YOUR_KEY      # stored in ~/.fad-check/config.json (mode 0600)
-fad-check --show-config               # confirm it's persisted (key masked)
+fad-checker --set-nvd-key YOUR_KEY      # stored in ~/.fad-checker/config.json (mode 0600)
+fad-checker --show-config               # confirm it's persisted (key masked)
 ```
 
 Or pass it ad-hoc via the `NVD_API_KEY` env var.
 
 ## Snyk integration
 
-If you have `snyk` installed and authenticated, `fad-check` can drive it:
+If you have `snyk` installed and authenticated, `fad-checker` can drive it:
 
 ```bash
-fad-check -s ./proj -t ../proj-clean -e "^com\.acme\." --snyk
+fad-checker -s ./proj -t ../proj-clean -e "^com\.acme\." --snyk
 ```
 
 This:
 1. Generates the cleaned POM tree at `../proj-clean/`.
 2. Runs `snyk test --all-projects --json` against it.
-3. Merges Snyk's findings into the report — entries present in both `fad-check` and Snyk are tagged `source: "both"`.
+3. Merges Snyk's findings into the report — entries present in both `fad-checker` and Snyk are tagged `source: "both"`.
 
 `--snyk` requires `-t` (Snyk needs a real POM tree to scan).
 
@@ -104,7 +104,7 @@ This:
 
 | Mode | Trigger | Disk writes |
 | --- | --- | --- |
-| Read-only | `-t` omitted (default) | Only `~/.fad-check/` caches and the report dir |
+| Read-only | `-t` omitted (default) | Only `~/.fad-checker/` caches and the report dir |
 | Write | `-t <dir>` provided | Above + the cleaned POM tree at `<dir>` (and `<dir>` is `rimraf`'d first!) |
 
 The `--target` guardrails refuse:
@@ -114,30 +114,30 @@ The `--target` guardrails refuse:
 ## Verbosity
 
 ```bash
-fad-check -s . -v          # progress per source (OSV batches, NVD pages, retire scan, …)
+fad-checker -s . -v          # progress per source (OSV batches, NVD pages, retire scan, …)
 ```
 
 ## Shell completion
 
 ```bash
-fad-check --completion bash > /etc/bash_completion.d/fad-check
-fad-check --completion zsh  > ~/.zsh/completions/_fad-check
+fad-checker --completion bash > /etc/bash_completion.d/fad-checker
+fad-checker --completion zsh  > ~/.zsh/completions/_fad-checker
 ```
 
 ## All flags at a glance
 
 ```bash
-fad-check --help
+fad-checker --help
 ```
 
 ## Recipes
 
 ### CI gate: fail the build on any CRITICAL prod CVE
 
-`fad-check` exits 0 even when CVEs are found (it's a reporter, not a gate). Wire your own:
+`fad-checker` exits 0 even when CVEs are found (it's a reporter, not a gate). Wire your own:
 
 ```bash
-fad-check -s . --no-nvd > /dev/null
+fad-checker -s . --no-nvd > /dev/null
 # Then grep the report or parse the structured output (planned).
 ```
 
@@ -148,7 +148,7 @@ fad-check -s . --no-nvd > /dev/null
 Keep dated copies of the report:
 
 ```bash
-fad-check -s . --report-output reports/$(date +%F)
+fad-checker -s . --report-output reports/$(date +%F)
 diff reports/2026-04-01/cve-report.html reports/2026-05-01/cve-report.html
 ```
 
@@ -157,15 +157,15 @@ diff reports/2026-04-01/cve-report.html reports/2026-05-01/cve-report.html
 On a connected machine:
 
 ```bash
-fad-check -s ./dummy-empty-dir       # populates ~/.fad-check/ caches
-fad-check --export-cache fad-cache.tar.gz --include-config
+fad-checker -s ./dummy-empty-dir       # populates ~/.fad-checker/ caches
+fad-checker --export-cache fad-cache.tar.gz --include-config
 ```
 
 Move `fad-cache.tar.gz` to the air-gapped box, then:
 
 ```bash
-fad-check --import-cache fad-cache.tar.gz
-fad-check -s ./real-project --offline
+fad-checker --import-cache fad-cache.tar.gz
+fad-checker -s ./real-project --offline
 ```
 
 ### Monorepo with Maven + JS + vendored JS
@@ -173,7 +173,7 @@ fad-check -s ./real-project --offline
 The melino-style project (Java backend, React frontend in `web/`, vendored jQuery/PDF.js under `web/src/main/webapp/`):
 
 ```bash
-fad-check -s . -e "^(com\.captcha|org\.voxaly|com\.voxaly)\."
+fad-checker -s . -e "^(com\.captcha|org\.voxaly|com\.voxaly)\."
 # → finds CVE in Maven deps, in web/package-lock.json deps,
 #   AND in the vendored .js files under webapp/.
 ```

package/{fad-check.js → fad-checker.js}

@@ -27,7 +27,7 @@ if (process.argv.includes("--completion")) {
 	const shell = process.argv[shellIdx] && !process.argv[shellIdx].startsWith("-")
 		? process.argv[shellIdx]
 		: "bash";
-	const completionPath = path.join(__dirname, "completions", `fad-check.${shell}`);
+	const completionPath = path.join(__dirname, "completions", `fad-checker.${shell}`);
 	try {
 		process.stdout.write(fs.readFileSync(completionPath, "utf8"));
 		process.exit(0);
@@ -87,7 +87,7 @@ if (process.argv.includes("--add-repo") || process.argv.includes("--remove-repo"
 		const url = process.argv[idx + 2];
 		if (!name || name.startsWith("-") || !url || url.startsWith("-")) {
 			console.error(chalk.red("❌  --add-repo requires <name> <url>"));
-			console.error("   Example: fad-check --add-repo nexus https://nexus.acme.com/repository/maven-public/");
+			console.error("   Example: fad-checker --add-repo nexus https://nexus.acme.com/repository/maven-public/");
 			console.error("   Optional auth: --add-repo nexus https://nexus.acme.com/repository/maven-public/ --auth user:pass");
 			process.exit(1);
 		}
@@ -121,7 +121,7 @@ if (process.argv.includes("--export-cache") || process.argv.includes("--import-c
 			if (exportIdx !== -1) {
 				const dest = process.argv[exportIdx + 1];
 				if (!dest || dest.startsWith("-")) {
-					console.error(chalk.red("❌  --export-cache requires a destination path (e.g. fad-check-cache.tar.gz)"));
+					console.error(chalk.red("❌  --export-cache requires a destination path (e.g. fad-checker-cache.tar.gz)"));
 					process.exit(1);
 				}
 				const includeConfig = process.argv.includes("--include-config");
@@ -150,11 +150,11 @@ if (process.argv.includes("--export-cache") || process.argv.includes("--import-c
 }
 
 const USAGE = `
-(1) fad-check -s ./proj                                              # read-only: full report (CVE + EOL + obsolete + outdated + transitive)
-(2) fad-check -s ./proj -e "^(org.private|client)"                   # same, with regex exclusion of private deps
-(3) fad-check -s ./proj -t ../pom-clean -e "^(org.private|client)"   # write cleaned POMs + full report
-(4) fad-check -s ./proj --no-transitive --no-all-libs                # faster, only direct deps, no Maven Central queries
-(5) fad-check -s ./proj -t ../pom-clean -e "^..." --snyk             # also run snyk and merge findings
+(1) fad-checker -s ./proj                                              # read-only: full report (CVE + EOL + obsolete + outdated + transitive)
+(2) fad-checker -s ./proj -e "^(org.private|client)"                   # same, with regex exclusion of private deps
+(3) fad-checker -s ./proj -t ../pom-clean -e "^(org.private|client)"   # write cleaned POMs + full report
+(4) fad-checker -s ./proj --no-transitive --no-all-libs                # faster, only direct deps, no Maven Central queries
+(5) fad-checker -s ./proj -t ../pom-clean -e "^..." --snyk             # also run snyk and merge findings
 `;
 
 program
@@ -173,13 +173,13 @@ program
 	.option("--no-osv", "skip OSV.dev (Google/GitHub aggregated Maven CVE feed)")
 	.option("--no-nvd", "skip NIST NVD enrichment of matched CVEs")
 	.option("--offline", "no network: use cached CVE/OSV/NVD/POM data only")
-	.option("--set-nvd-key <key>", "save NVD API key to ~/.fad-check/config.json (10× faster NVD enrichment)")
-	.option("--show-config", "print the persisted ~/.fad-check/config.json")
-	.option("--export-cache <file>", "tar.gz/zip the ~/.fad-check/ caches to <file> (excludes config.json by default)")
-	.option("--import-cache <file>", "restore ~/.fad-check/ from a previously exported archive (existing dir is moved to .bak unless --force)")
+	.option("--set-nvd-key <key>", "save NVD API key to ~/.fad-checker/config.json (10× faster NVD enrichment)")
+	.option("--show-config", "print the persisted ~/.fad-checker/config.json")
+	.option("--export-cache <file>", "tar.gz/zip the ~/.fad-checker/ caches to <file> (excludes config.json by default)")
+	.option("--import-cache <file>", "restore ~/.fad-checker/ from a previously exported archive (existing dir is moved to .bak unless --force)")
 	.option("--include-config", "with --export-cache: also bundle config.json (contains the NVD API key)")
-	.option("--force", "with --import-cache: replace ~/.fad-check/ without backup")
-	.option("--report-output <dir>", "report output directory", "./fad-check-report")
+	.option("--force", "with --import-cache: replace ~/.fad-checker/ without backup")
+	.option("--report-output <dir>", "report output directory", "./fad-checker-report")
 	.option("--ignore-test", "skip test-scoped dependencies in report")
 	.option("--cve-refresh", "force re-download of CVE database")
 	.option("--cve-offline", "use cached CVE index only (no download)")
@@ -218,7 +218,7 @@ async function checkMavenLibExist(groupId, artifactId, repos) {
 	const p = `${g.replace(/\./g, "/")}/${a}/maven-metadata.xml`;
 	const { existsInAny } = require("./lib/maven-repo");
 	try {
-		const hit = await existsInAny(repos, p, { userAgent: "fad-check-existence" });
+		const hit = await existsInAny(repos, p, { userAgent: "fad-checker-existence" });
 		if (hit) return true;
 		console.log(`❌  NOT found on any repo: ${g}:${a}`);
 		return false;
@@ -231,7 +231,7 @@ async function checkMavenLibExist(groupId, artifactId, repos) {
 (async function main() {
 	console.log(chalk.bold.cyan("\n🚀 Fucking Autonomous Dependency Checker\n") + chalk.gray("─────────────────────────────"));
 
-	// Build the Maven repo list once: persisted repos (from ~/.fad-check/config.json)
+	// Build the Maven repo list once: persisted repos (from ~/.fad-checker/config.json)
 	// + ad-hoc --repo URLs + Maven Central as final fallback. Used by transitive
 	// resolution, outdated-version check, and existence check.
 	const { getMavenRepos } = require("./lib/config");
@@ -401,7 +401,7 @@ async function runReportFlow(allPomMetadata, allPropsByPom, ecoFlags = {}) {
 	}
 	const directCount = resolved.size;
 
-	// Scan-completeness signals: BOMs and unresolved-version deps mean fad-check
+	// Scan-completeness signals: BOMs and unresolved-version deps mean fad-checker
 	// has gone as far as it can without running Maven/Snyk itself.
 	if (runMaven) {
 		const { detectScanCompletenessWarnings } = require("./lib/scan-completeness");
@@ -541,8 +541,11 @@ async function runReportFlow(allPomMetadata, allPropsByPom, ecoFlags = {}) {
 
 	// Split prod vs dev based on the dep's isDev flag (set at collection time
 	// from Maven scope=test/provided and npm dev/devOptional/optional).
-	const prodMatches = cveMatches.filter(m => !m.dep?.isDev);
-	const devMatches  = cveMatches.filter(m =>  m.dep?.isDev);
+	// CPE-filtered matches are excluded from the CLI headline — they're surfaced
+	// in the HTML report's "Likely false positives" appendix instead.
+	const prodMatches = cveMatches.filter(m => !m.dep?.isDev && !m.cpeFiltered);
+	const devMatches  = cveMatches.filter(m =>  m.dep?.isDev && !m.cpeFiltered);
+	const cpeFilteredCount = cveMatches.filter(m => m.cpeFiltered).length;
 
 	const stats = computeStats(prodMatches);
 	const devStats = computeStats(devMatches);
@@ -554,6 +557,7 @@ async function runReportFlow(allPomMetadata, allPropsByPom, ecoFlags = {}) {
 		console.log(`       ${chalk.red(sev)} ${m.cve.id}  ${depLabel(m.dep)}:${m.dep.version}`);
 	}
 	if (prodMatches.length > 20) console.log(`       ... and ${prodMatches.length - 20} more (see report)`);
+	if (cpeFilteredCount) console.log(chalk.gray(`     (${cpeFilteredCount} likely false positives moved to report appendix)`));
 
 	if (devMatches.length) {
 		console.log(chalk.bold.cyan(`\n  2. CVE in dev dependencies (${devMatches.length})`));
@@ -581,7 +585,7 @@ async function runReportFlow(allPomMetadata, allPropsByPom, ecoFlags = {}) {
 	if (!outdatedResults.length && options.allLibs) console.log(chalk.gray("     (none)"));
 	if (!options.allLibs) console.log(chalk.gray("     (re-run with -a/--allLibs to query Maven Central)"));
 
-	const reportDir = options.reportOutput || "./fad-check-report";
+	const reportDir = options.reportOutput || "./fad-checker-report";
 	await fs.promises.mkdir(reportDir, { recursive: true });
 	const projectInfo = {
 		name: path.basename(path.resolve(options.src)),
@@ -613,7 +617,7 @@ async function runReportFlow(allPomMetadata, allPropsByPom, ecoFlags = {}) {
 					const paths = (dep?.pomPaths || []).map(p => path.relative(options.src, p));
 					return { id, manifestPaths: paths };
 				}),
-				message: `${privateLibIds.length} Maven coord(s) not found on Maven Central — they are private/internal libraries. Their CVEs (if any) cannot be detected by fad-check; if you have an internal CVE feed, audit them separately.`,
+				message: `${privateLibIds.length} Maven coord(s) not found on Maven Central — they are private/internal libraries. Their CVEs (if any) cannot be detected by fad-checker; if you have an internal CVE feed, audit them separately.`,
 			}] : []),
 		],
 	});

package/lib/cache-archive.js

@@ -1,5 +1,5 @@
 /**
- * lib/cache-archive.js — export / import the entire ~/.fad-check/ directory.
+ * lib/cache-archive.js — export / import the entire ~/.fad-checker/ directory.
  *
  * Use case:
  *   - Move the warmed-up CVE/OSV/NVD/POM caches between machines
@@ -20,17 +20,17 @@ const { execFile } = require("child_process");
 const { promisify } = require("util");
 const execFileP = promisify(execFile);
 
-const FAD_CACHE_DIR = path.join(os.homedir(), ".fad-check");
+const FAD_CACHE_DIR = path.join(os.homedir(), ".fad-checker");
 
 /**
- * Files inside ~/.fad-check/ that hold secrets and should NOT be shipped by default.
+ * Files inside ~/.fad-checker/ that hold secrets and should NOT be shipped by default.
  * Override by passing `includeConfig: true`.
  */
 const SENSITIVE_FILES = ["config.json"];
 
 async function exportCache(destFile, opts = {}) {
 	const { verbose, includeConfig } = opts;
-	if (!fs.existsSync(FAD_CACHE_DIR)) throw new Error(`no ~/.fad-check/ directory to export`);
+	if (!fs.existsSync(FAD_CACHE_DIR)) throw new Error(`no ~/.fad-checker/ directory to export`);
 	const abs = path.resolve(destFile);
 	fs.mkdirSync(path.dirname(abs), { recursive: true });
 
@@ -49,7 +49,7 @@ async function exportCache(destFile, opts = {}) {
 			if (verbose) console.log(`📦 Compress-Archive -Path ${FAD_CACHE_DIR}\\* -DestinationPath ${abs}`);
 			// Powershell Compress-Archive doesn't have a clean exclude flag — manual copy
 			await execFileP("powershell", ["-NoProfile", "-Command",
-				`$src='${FAD_CACHE_DIR}'; $dst='${abs}'; ${includeConfig ? `Compress-Archive -Path "$src\\*" -DestinationPath $dst -Force` : `$tmp=Join-Path $env:TEMP "fad-check-stage-$(Get-Random)"; Copy-Item $src $tmp -Recurse; ${SENSITIVE_FILES.map(f => `Remove-Item -Force -ErrorAction SilentlyContinue (Join-Path $tmp '${f}')`).join("; ")}; Compress-Archive -Path "$tmp\\*" -DestinationPath $dst -Force; Remove-Item $tmp -Recurse -Force`}`]);
+				`$src='${FAD_CACHE_DIR}'; $dst='${abs}'; ${includeConfig ? `Compress-Archive -Path "$src\\*" -DestinationPath $dst -Force` : `$tmp=Join-Path $env:TEMP "fad-checker-stage-$(Get-Random)"; Copy-Item $src $tmp -Recurse; ${SENSITIVE_FILES.map(f => `Remove-Item -Force -ErrorAction SilentlyContinue (Join-Path $tmp '${f}')`).join("; ")}; Compress-Archive -Path "$tmp\\*" -DestinationPath $dst -Force; Remove-Item $tmp -Recurse -Force`}`]);
 		} else {
 			const args = ["-r", "-q", abs, path.basename(FAD_CACHE_DIR)];
 			for (const e of excludes) { args.push("-x"); args.push(e); }
@@ -70,13 +70,13 @@ async function importCache(srcFile, opts = {}) {
 	if (!fs.existsSync(abs)) throw new Error(`archive not found: ${abs}`);
 
 	if (fs.existsSync(FAD_CACHE_DIR) && !force) {
-		// Move existing aside as .fad-check.bak-<timestamp>
+		// Move existing aside as .fad-checker.bak-<timestamp>
 		const backup = `${FAD_CACHE_DIR}.bak-${Date.now()}`;
 		fs.renameSync(FAD_CACHE_DIR, backup);
-		if (verbose) console.log(`💾 existing ~/.fad-check/ moved to ${backup}`);
+		if (verbose) console.log(`💾 existing ~/.fad-checker/ moved to ${backup}`);
 	} else if (force && fs.existsSync(FAD_CACHE_DIR)) {
 		fs.rmSync(FAD_CACHE_DIR, { recursive: true, force: true });
-		if (verbose) console.log(`🗑  --force: existing ~/.fad-check/ removed`);
+		if (verbose) console.log(`🗑  --force: existing ~/.fad-checker/ removed`);
 	}
 
 	const parent = path.dirname(FAD_CACHE_DIR);
@@ -99,7 +99,7 @@ async function importCache(srcFile, opts = {}) {
 	}
 
 	if (!fs.existsSync(FAD_CACHE_DIR)) {
-		throw new Error(`import completed but ~/.fad-check/ was not created — was the archive built with fad-check --export-cache?`);
+		throw new Error(`import completed but ~/.fad-checker/ was not created — was the archive built with fad-checker --export-cache?`);
 	}
 	return { dir: FAD_CACHE_DIR };
 }

package/lib/config.js

@@ -1,5 +1,5 @@
 /**
- * lib/config.js — persistent user config in ~/.fad-check/config.json
+ * lib/config.js — persistent user config in ~/.fad-checker/config.json
  *
  * Stores credentials and per-user preferences that should survive across runs.
  * Currently: NVD API key (so users don't have to re-export the env var).
@@ -8,7 +8,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 
-const CONFIG_DIR = path.join(os.homedir(), ".fad-check");
+const CONFIG_DIR = path.join(os.homedir(), ".fad-checker");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
 function load() {
@@ -35,7 +35,7 @@ function get(key) {
 	return load()[key];
 }
 
-/** NVD API key resolution: env var first, then ~/.fad-check/config.json. */
+/** NVD API key resolution: env var first, then ~/.fad-checker/config.json. */
 function getNvdApiKey() {
 	return process.env.NVD_API_KEY || get("nvd_api_key") || null;
 }

package/lib/cpe.js

@@ -67,6 +67,17 @@ function parseCpe23(uri) {
 	};
 }
 
+// Memoize parseCpe23 on the cpeMatch object so subsequent passes (the
+// confidence walk inside evaluateCveForDep) don't re-tokenize the same URI.
+// `_parsedCpe` uses `null` (parse failed) vs `undefined` (not yet parsed) to
+// distinguish empty result from missing cache.
+function parseCpe23Cached(cpeMatch) {
+	if (!cpeMatch || typeof cpeMatch !== "object") return parseCpe23(cpeMatch?.criteria || "");
+	if (cpeMatch._parsedCpe !== undefined) return cpeMatch._parsedCpe;
+	cpeMatch._parsedCpe = parseCpe23(cpeMatch.criteria || "");
+	return cpeMatch._parsedCpe;
+}
+
 /**
  * Match a dep version against a single NVD cpeMatch entry.
  * The entry has the shape:
@@ -81,12 +92,18 @@ function parseCpe23(uri) {
 function matchVersionRange(depVersion, cpeMatch) {
 	if (!cpeMatch) return false;
 	if (!depVersion) return true; // unknown version → assume affected
-	const parsed = parseCpe23(cpeMatch.criteria || "");
+	const parsed = parseCpe23Cached(cpeMatch);
 	if (!parsed) return false;
 
 	// Hard pin in the criteria URI itself
 	if (parsed.version && parsed.version !== "*" && parsed.version !== "-") {
-		try { return compareMavenVersions(depVersion, parsed.version) === 0; }
+		// CPE 2.3 update field qualifies the version (`:1.0.0:beta1:` ≡ `1.0.0-beta1`).
+		// Without folding it in, a release like 1.0.0 would incorrectly match a pin
+		// of 1.0.0:rc1 — see H5 in CRITICAL-REVIEW.md.
+		const pinned = (parsed.update && parsed.update !== "*" && parsed.update !== "-")
+			? `${parsed.version}-${parsed.update}`
+			: parsed.version;
+		try { return compareMavenVersions(depVersion, pinned) === 0; }
 		catch { return false; }
 	}
 
@@ -112,7 +129,7 @@ function nodeAffectsDep(node, dep, cpeCoordMap) {
 	const matches = node.cpeMatch || node.cpe_match || [];
 	for (const m of matches) {
 		if (m.vulnerable === false) continue;
-		const parsed = parseCpe23(m.criteria || "");
+		const parsed = parseCpe23Cached(m);
 		if (!parsed) continue;
 		if (!cpeMatchesDep(parsed, dep, cpeCoordMap)) continue;
 		if (!matchVersionRange(dep.version, m)) continue;
@@ -168,8 +185,9 @@ function cpeMatchesDep(cpe, dep, cpeCoordMap) {
 		const p = (cpe.product || "").toLowerCase();
 		if (p !== a) return false;
 		if (g === v) return true;
+		// Mirrors vendorMatchesGroup: dot-segment membership only, no substring
+		// fallback. Unbounded substring matching leaked FPs (M4 in CRITICAL-REVIEW.md).
 		if (g.split(".").includes(v)) return true;
-		if (g.includes(v) || v.includes(g)) return true;
 	}
 	return false;
 }
@@ -213,7 +231,7 @@ function evaluateCveForDep(cveRecord, dep, cpeCoordMap) {
 			for (const n of nodes) {
 				for (const m of n.cpeMatch || n.cpe_match || []) {
 					if (m.vulnerable === false) continue;
-					const parsed = parseCpe23(m.criteria || "");
+					const parsed = parseCpe23Cached(m);
 					if (!parsed) continue;
 					if (!cpeMatchesDep(parsed, dep, map)) continue;
 					if (!matchVersionRange(dep.version, m)) continue;

package/lib/cve-download.js

@@ -13,7 +13,7 @@ const { execFile } = require("child_process");
 const { promisify } = require("util");
 const execFileP = promisify(execFile);
 
-const CVE_DATA_DIR = path.join(os.homedir(), ".fad-check", "cve-data");
+const CVE_DATA_DIR = path.join(os.homedir(), ".fad-checker", "cve-data");
 const CVE_INDEX_PATH = path.join(CVE_DATA_DIR, "maven-cve-index.json");
 const CVE_META_PATH = path.join(CVE_DATA_DIR, "meta.json");
 const CVE_EXTRACT_DIR = path.join(CVE_DATA_DIR, "extracted");
@@ -174,7 +174,7 @@ async function commandExists(name) {
 }
 
 async function fetchLatestRelease() {
-	const headers = { "User-Agent": "fad-check-cve-downloader" };
+	const headers = { "User-Agent": "fad-checker-cve-downloader" };
 	if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
 	const res = await fetch("https://api.github.com/repos/CVEProject/cvelistV5/releases/latest", { headers });
 	if (!res.ok) throw new Error(`GitHub API HTTP ${res.status}`);
@@ -341,7 +341,7 @@ async function downloadCveData(opts = {}) {
 }
 
 /**
- * Single entry point used by fad-check.js: returns a usable CVE index,
+ * Single entry point used by fad-checker.js: returns a usable CVE index,
  * downloading/refreshing as needed.
  */
 async function ensureCveIndex(opts = {}) {

package/lib/cve-match.js

@@ -166,16 +166,22 @@ function vendorMatchesGroup(vendor, groupId) {
 	const v = vendor.toLowerCase();
 	const g = groupId.toLowerCase();
 	if (g === v) return true;
-	if (g.includes(v) || v.includes(g)) return true;
-	// org.apache.commons matches vendor "apache"
-	const parts = g.split(".");
-	return parts.includes(v);
+	// org.apache.commons matches vendor "apache" via dot-segment membership.
+	// Unbounded substring checks (g.includes(v) / v.includes(g)) used to leak
+	// FPs — e.g. vendor "open" matching org.opensaml.* because "opensaml"
+	// contains "open". Dot-segment membership is strict enough.
+	if (g.split(".").includes(v)) return true;
+	return false;
 }
 
-function matchDepsAgainstCves(resolvedDeps, cveIndex) {
+function matchDepsAgainstCves(resolvedDeps, cveIndex, opts = {}) {
 	if (!cveIndex) return [];
 	const byPackage = cveIndex.byPackageName || {};
 	const byProduct = cveIndex.byProduct || {};
+	// "possible" tier (product matches but vendor doesn't) is FP-heavy and
+	// hidden by default. The CPE refinement step can still rescue a real hit
+	// later; opt-in shows the raw bucket for triage.
+	const includePossibleTier = !!opts.includePossibleTier;
 
 	const all = [];
 	for (const dep of resolvedDeps.values()) {
@@ -187,12 +193,12 @@ function matchDepsAgainstCves(resolvedDeps, cveIndex) {
 		// Tier 1: exact packageName match
 		const t1 = matchOne(dep, byPackage[key], "exact");
 		all.push(...t1);
-		// Tier 2/3: product match, scoped by vendor heuristic
+		// Tier 2: product match scoped by vendor heuristic
 		const productMatches = byProduct[dep.artifactId.toLowerCase()] || [];
 		for (const e of productMatches) {
 			if (vendorMatchesGroup(e.vendor, dep.groupId)) {
 				all.push(...matchOne(dep, [e], "probable"));
-			} else {
+			} else if (includePossibleTier) {
 				all.push(...matchOne(dep, [e], "possible"));
 			}
 		}