fad-checker 2.0.0 → 2.1.0

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 |

package/docs/ARCHITECTURE.md

@@ -1,182 +0,0 @@
-# Architecture
-
-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-checker.js                 Thin CLI: commander parsing + orchestration (loops over active codecs).
-lib/codecs/                  Per-ecosystem codecs (maven, npm, yarn, composer, pypi, nuget) + registry + select + recipes (see "Codecs" below).
-lib/codecs/composer/                composer.lock/composer.json parsers + Packagist registry (PHP codec internals).
-lib/codecs/pypi/                  poetry/pipfile/uv/pdm/requirements parsers + PyPI registry (Python codec internals).
-lib/codecs/nuget/                   packages.lock.json/csproj/packages.config parsers + NuGet registry (.NET codec internals).
-lib/dep-record.js            makeDepRecord(): the generalized depRecord shared by all codecs.
-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 we 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.
-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-checker.bash, fad-checker.zsh
-test/                        node:test suite + fixtures (simple, complex-enterprise, monorepo-mixed, …).
-```
-
-## Codecs
-
-Every ecosystem-specific behaviour lives behind a **codec** (`lib/codecs/*.codec.js`)
-implementing one interface (`lib/codecs/codec.interface.js`):
-
-```
-id, label, osvEcosystem, manifestNames,
-detect(dir), collect(dir,opts) → {deps, warnings},
-coordKey(dep), formatCoord(dep), osvPackageName(dep),
-checkRegistry(deps,opts) → {outdated, deprecated},
-resolveEolProduct(dep), recipe, nativeScanners
-```
-
-- `lib/codecs/index.js` is the registry: `getCodec(id)`, `allCodecs()`, `detectCodecs(dir)`.
-- `lib/codecs/select.js` turns `--ecosystem <list>` + `--no-<id>` into the active codec ids.
-- The orchestrator collects deps by looping the active codecs, then runs the **shared,
-  ecosystem-agnostic** services (OSV, NVD, CPE refinement, endoflife.date) which ask the
-  codec only for a package/product name. `nativeScanners` are extra scanners a codec owns
-  and the orchestrator runs at their pipeline position by `kind`: `cve` (maven → local
-  cvelistV5 index, merged into the CVE chapter) and `vendored` (npm → retire.js, its own
-  chapter). New ecosystems (NuGet/Composer/PyPI) ship as codecs with no native scanners —
-  OSV + NVD cover them — so no orchestrator changes are needed to add one.
-
-## The resolved-deps Map
-
-The whole pipeline hinges on a single `Map<string, depRecord>` keyed by:
-- `groupId:artifactId` for Maven entries
-- `npm:<name>` for npm/yarn entries
-
-Each `depRecord` carries:
-
-```js
-{
-  groupId, artifactId, version,
-  scope,             // "compile" | "test" | "import" | "transitive" | "parent" | "prod" | "dev" | "peer" | "optional"
-  isDev,             // Maven test/provided OR npm dev/devOptional/optional
-  ecosystem,         // "maven" | "npm"
-  ecosystemType,     // "maven" | "npm" | "yarn" | "retire"
-  pomPaths,          // absolute paths to manifests declaring this dep
-  manifestPaths,     // same as pomPaths but used by the npm collector
-  // Transitive-only:
-  via, viaPaths, depth,
-  // npm-only:
-  lockType, resolved, integrity,
-}
-```
-
-The Maven keyspace and npm keyspace never collide — `:lodash` (Maven groupId-less) becomes `npm:lodash` so the same Map can hold both ecosystems without overwrites.
-
-## Cleanup pipeline (`lib/core.js`)
-
-1. `findPomFiles(src)` — recursive walk, skips known output dirs (`target/`, `node_modules/`, `.git/`, `.idea/`, `dist/`, `build-output/`, `out/`, `.next/`, `.nuxt/`, `coverage/`, `.gradle/`, `.mvn/`, `.vscode/`, `bower_components/`, `jspm_packages/`). Note: `build/` is **not** skipped on the Maven side because some multi-module projects use it for a BOM module.
-2. `parsePom()` — xml2js to JSON. Extracts groupId/artifactId/version, `<parent>`, properties, and indexes every profile (recording which one is `activeByDefault`). Templates with literal `\${…}` are skipped.
-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-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-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.*`)
-   - `possible`: product-only match
-   Dedupes by `(dep, cve.id)` and sorts by severity. npm deps are skipped here — they're scanned by OSV instead.
-5. **OSV** (default on) — `queryOsvForDeps()` POSTs batched queries to `api.osv.dev/v1/querybatch` (Maven ecosystem for Maven deps, npm ecosystem for npm deps). Per-dep stub list cached 12h; per-vuln details cached 12h.
-6. **NVD enrichment** (default on) — for every CVE id matched, fetch the full NVD record (description, CVSS vectors, references categorised by tag, CPE configurations). Rate-limited per NIST policy (5/30s unauthenticated, 50/30s with `NVD_API_KEY`).
-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-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` (Maven) + `lib/codecs/npm/registry.js` (npm):
-   - **WebJars** (`org.webjars*` — client-side JS shipped as Maven artifacts) are reduced to their npm-equivalent coordinate by `webjarToNpm()` (`lib/codecs/npm/collect.js`): `org.webjars.npm` is a deterministic npm mirror (`angular__core` → `@angular/core`); classic `org.webjars`/bower names pass through. They then flow through the **same npm paths** below — no WebJar-specific data.
-   - **EOL**: matches dep coord against `data/eol-mapping.json`, fetches the cycle list from endoflife.date (cached 7d), flags cycles past their EOL date. npm packages and WebJars resolve by JS library name via `by_npm_name` / `by_npm_scope` (e.g. npm `angular`/webjar `angularjs` → AngularJS 1.x, `@angular/*` → Angular, `react`/`jquery`/`vue`/`bootstrap`).
-   - **Obsolete**: Maven via curated `data/known-obsolete.json` (log4j 1.x, jackson-mapper-asl, joda-time, commons-httpclient 3.x, …); npm **and WebJars** via the registry's per-version `deprecated` field (authoritative maintainer data — every dep is checked, nothing curated, nothing skipped).
-   - **Outdated**: Maven Central Solr query; npm registry `dist-tags.latest` (npm deps and WebJars). Both gated by `--no-all-libs`. 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-checker-report/`.
-
-## Report structure
-
-```
-<Executive Summary>            ← global criticality + key bullet counts
-<Summary cards>                ← critical / high / medium / low / EOL / obsolete / outdated
-<Toolbar>                      ← expand-all / collapse-all / expand CVE details
-
-0. Warnings & scan-completeness ← chapter 0 if any warnings
-1. CVE Vulnerabilities — production (N)
-  1.a Maven (n)
-    1.a.0 All (n)              ← combined direct + transitive
-    By pom.xml (k files)       ← wrapper always present
-      <relative-path-1> (m)    ← direct deps in this pom only
-      <relative-path-2> (m)
-      …
-  1.b npm (package-lock) (n)
-    1.b.0 All (n)
-    By package-lock.json (k files)
-      web/package-lock.json (m)
-2. CVE in dev dependencies (M) ← same structure as 1
-3. Vendored JS scan — retire.js (R)
-4. End-of-Life Frameworks
-5. Obsolete / Deprecated Libraries
-6. Outdated Libraries
-7. Fix Recommendations          ← per-ecosystem snippets
-  7.a Maven                     ← dependencyManagement XML
-  7.b npm                       ← package.json overrides
-  7.c yarn                      ← package.json resolutions
-```
-
-## Important conventions
-
-- **`coord()` always trims**: real-world POMs occasionally contain whitespace around `<artifactId>` (seen in the wild). Every coord-derived lookup goes through `coord()` in `lib/core.js`.
-- **`byId` keys are never polluted with `undefined`**: we only index a POM by id when both `groupId` and `artifactId` are present. Test `byId does not get polluted with undefined keys` enforces this.
-- **All profiles are merged, never prompted for**: previous versions prompted the user when a POM had multiple profiles. We now union every profile's deps 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.
-- **Map keys are ecosystem-namespaced**: Maven uses `g:a`, npm uses `npm:name`. They never collide so they can share one resolved-deps Map.
-- **Lockfile-only npm**: `package.json` without sibling `package-lock.json`/`yarn.lock` is intentionally skipped (its ranges aren't queryable) and reported in chapter 0. Avoids false negatives on deps that haven't been installed yet.
-- **Source identifiers**: every match carries `source: "fad" | "osv" | "nvd" | "snyk" | "retire"` (or a `+`-joined combination like `"fad+osv+nvd"`). The legacy "mbdc" identifier was renamed to "fad" in 3.0.
-
-## Gotchas / edge cases worth knowing
-
-- 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 and npm registry version lookups for 24 hours.
-- **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, npm registry 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`, `--no-js`) 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.
-- Unresolved `${…}` Maven variables are kept verbatim in the rewritten POM. `lib/cve-match.js` resolves them lazily via `resolveDepVersion()` when collecting deps for the scan. Deps that *still* can't be resolved (external BOM) are surfaced in chapter 0 as `unresolved-versions` warnings.
-- **Per-cache TTLs** are documented in the README's "Caching" table.
-
-## Testing
-
-```bash
-npm test                          # full suite (194 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 (two of which inject env-specific JDBC drivers), test-scoped JUnit, jackson-databind via BOM-managed version
-- `private-lib-detection/` — mixed public/private groupIds and an externally-hosted private parent — verifies missing-parent tracking
-- `monorepo-mixed/` — combined Maven (4 POMs: parent + BOM + 2 modules) + JS (npm package-lock v3 + yarn.lock v1 + a no-lockfile package.json to test the warning)
-- `cve-samples/` — small CVE / NVD JSON files to exercise the matchers without the 500 MB real bundle

package/docs/USAGE.md

@@ -1,187 +0,0 @@
-# USAGE
-
-Every flag, every common workflow, with copy-pasteable commands.
-
-## Synopsis
-
-```text
-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`.
-- `-t, --target <dir>` — optional. If given, write a parallel directory of "cleaned" POMs (private/excluded deps stripped) to `<dir>` — useful as Snyk input. Without `-t`, the run is read-only.
-
-## Output
-
-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-checker -s .
-
-# Pick ecosystems (codecs). --ecosystem is a list: auto (default) | all | comma list.
-fad-checker -s . --ecosystem maven            # Maven only
-fad-checker -s . --ecosystem maven,npm        # both, even if only one is auto-detected
-fad-checker -s . --ecosystem all              # every supported codec
-fad-checker -s . --ecosystem both             # legacy alias for maven,npm
-
-# Opt out of specific codecs (combine freely)
-fad-checker -s . --no-npm                     # skip npm
-fad-checker -s . --no-js                      # alias: skip npm + yarn (Maven-only)
-fad-checker -s . --no-pypi --no-nuget         # skip Python + C#
-```
-
-> **npm without a lockfile**: a `package.json` lacking a sibling
-> `package-lock.json`/`yarn.lock` is now scanned **best-effort** — pinned exact
-> versions are checked, ranges (`^1.0.0`) are skipped, and a `no-lockfile` warning
-> flags the partial coverage. Run `npm install`/`yarn install` for full coverage.
-
-## Filtering deps
-
-`-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-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.
-
-## Per-source toggles
-
-Each data source can be disabled independently:
-
-| Flag | Effect |
-| --- | --- |
-| `--no-report` | Skip the report flow entirely (just cleanup) |
-| `--no-transitive` | Don't fetch transitive Maven deps from Maven Central |
-| `--no-all-libs` | Don't query Maven Central for latest versions (skips chapter 6 Outdated and the "missing on Central" check) |
-| `--no-osv` | Skip OSV.dev (Google + GitHub aggregated feed) |
-| `--no-nvd` | Skip NVD enrichment (no full CVSS, no CPE refinement) |
-| `--no-retire` | Skip retire.js vendored-JS scan |
-| `--ignore-test` | Drop test-scoped Maven deps and dev npm deps from the scan entirely (chapter 2 will be empty) |
-
-## Offline / cache control
-
-```bash
-# Use cached data only, no network (works for everything)
-fad-checker -s . --offline
-
-# Per-source offline
-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-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
-
-NVD's public rate limit is 5 requests / 30s without a key. The free key bumps it to 50 / 30s — **10× faster** for the enrichment step.
-
-```bash
-# Get a key in 30 seconds: https://nvd.nist.gov/developers/request-an-api-key
-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-checker` can drive it:
-
-```bash
-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-checker` and Snyk are tagged `source: "both"`.
-
-`--snyk` requires `-t` (Snyk needs a real POM tree to scan).
-
-## Read-only vs write mode
-
-| Mode | Trigger | Disk writes |
-| --- | --- | --- |
-| 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:
-- empty `--src`
-- `--target` equal to or a subdirectory of `--src`
-
-## Verbosity
-
-```bash
-fad-checker -s . -v          # progress per source (OSV batches, NVD pages, retire scan, …)
-```
-
-## Shell completion
-
-```bash
-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-checker --help
-```
-
-## Recipes
-
-### CI gate: fail the build on any CRITICAL prod CVE
-
-`fad-checker` exits 0 even when CVEs are found (it's a reporter, not a gate). Wire your own:
-
-```bash
-fad-checker -s . --no-nvd > /dev/null
-# Then grep the report or parse the structured output (planned).
-```
-
-(A `--fail-on critical` flag is a planned addition — track it in issues.)
-
-### Diff two runs
-
-Keep dated copies of the report:
-
-```bash
-fad-checker -s . --report-output reports/$(date +%F)
-diff reports/2026-04-01/cve-report.html reports/2026-05-01/cve-report.html
-```
-
-### Air-gapped scan
-
-On a connected machine:
-
-```bash
-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-checker --import-cache fad-cache.tar.gz
-fad-checker -s ./real-project --offline
-```
-
-### Monorepo with Maven + JS + vendored JS
-
-The melino-style project (Java backend, React frontend in `web/`, vendored jQuery/PDF.js under `web/src/main/webapp/`):
-
-```bash
-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/.
-```