@vyuhlabs/dxkit 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -7,6 +7,166 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-04-24
+
+Minor release — turns the `bom` report from enumeration (1700+ rows
+of noise) into a **decision doc** (top 10 triage queue ranked by
+composite exploit-risk). Every `DepVulnFinding` now carries five
+exploitability signals — CVSS, EPSS, CISA KEV, reachability,
+composite `riskScore` — that consumers can read individually or as
+the ranked `Risk` column. `licenses` + `vulnerabilities` renders
+gain parity with the new bom surface so any dxkit command shows the
+same triage-relevant data.
+
+Nine sub-commits (Phase 10h.5) landed behind PRs #4 / #5 / #6 /
+#7 / #8 / #9 / #10 / #11 through the hardened 2.2.1 pipeline —
+the first full release cut where every commit flowed PR → CI-green →
+merge → tag → CI-publishes without deviation.
+
+### Added — exploitability enrichers
+
+- **EPSS** (`DepVulnFinding.epssScore`, 0.0–1.0) from FIRST.org's
+  `api.first.org/data/v1/epss`. Batched (≤100 CVEs/call), session-
+  cached, graceful offline fallback. Non-CVE primaries (GHSA /
+  RUSTSEC / GO / PYSEC) resolve via OSV.dev alias lookup — no
+  coverage gap across packs. (10h.5.1)
+
+- **CISA KEV** (`DepVulnFinding.kev`, boolean) from the official
+  catalog at `cisa.gov/.../known_exploited_vulnerabilities.json`.
+  Single bulk fetch per process, O(1) lookup. Badge `⚠` in every
+  render. (10h.5.2)
+
+- **Reachability** (`DepVulnFinding.reachable`, tri-state) — does
+  this repo's source actually import the vulnerable package?
+  Built from per-pack `ImportsResult`'s specifier extraction;
+  `specifierToPackage` handles TS scoped/bare, Python dotted
+  modules, Go 3-segment module paths. Coarse name-level
+  matching; undefined when no imports data available. (10h.5.3)
+
+- **Composite riskScore** (`DepVulnFinding.riskScore`, 0–100) —
+  `clamp(cvss*10 × kev? × (1+2*epss) × reach?, 0, 100)`. Formula
+  documented in `src/analyzers/tools/risk-score.ts`. Null when
+  CVSS missing (no fabrication from side signals). (10h.5.4)
+
+- **"This Week's Triage"** section at the top of every bom report —
+  top 10 advisories with riskScore ≥ 15, rationale composed from
+  most decisive signals (KEV → reachable → CVSS → EPSS), fix
+  column with "PROPOSAL:" prefix stripped. (10h.5.5)
+
+### Added — decision-doc UX
+
+- **`bom --filter=top-level`** drops transitive rows (1700+ → ~150
+  on typical repos) while the `byTopLevelDep` rollup still reflects
+  full blast radius — "upgrading `@loopback/cli` resolves 29
+  advisories" survives when those 29 transitive rows are hidden.
+  `BomEntry.isTopLevel` + `summary.filter` + `summary.unfilteredTotalPackages`
+  ride the shape. (10h.5.0)
+
+- **Nested-project aggregation** (default ON; `--no-nested` opts
+  out). `src/analyzers/bom/discovery.ts` walks the repo,
+  discovers every directory with a language manifest
+  (package.json, pyproject.toml/requirements.txt/setup.py/Pipfile,
+  go.mod, Cargo.toml, *.csproj/*.sln), runs per-root gather, and
+  merges with dedup on `(package, version)`. `BomEntry.sources`
+  unions the roots each package was found in; `isTopLevel`
+  OR-merges; vulns dedup on `(id, package, installedVersion)`.
+  Closes **D001a** — `bom platform/` previously missed
+  `platform/userserver/` entirely. Side-benefit: naturally
+  addresses **D003** (C# multi-project) since each `.csproj`
+  becomes its own root. (10h.5.0b)
+
+- **`LicenseFinding.releaseDate`** populated from the npm registry
+  for every TS-ecosystem package. Closes **D006** — xlsx col 10
+  ("Component Release Date") was previously empty. Bundled with
+  the EPSS fetcher roundtrip. (10h.5.1)
+
+- **`licenses` render** sorts top-level deps (⭐) first, transitive
+  below. Adds `Direct` + `Released` columns. Matches bom's
+  `--filter=top-level` ordering so cross-referencing the two
+  reports Just Works. (10h.5.6)
+
+- **`vulnerabilities` render (main, not --detailed)** per-advisory
+  table now sorted by `riskScore` desc with `Risk` / `KEV` /
+  `Reach` / `EPSS` columns alongside the existing fields. (10h.5.6)
+
+### Fixed
+
+- **D013** — graphify's shared Python venv moved from
+  `/tmp/graphify-venv` (subject to systemd-tmpfiles sweep + race
+  on first install) to `~/.cache/dxkit/tools-venv` (XDG persistent).
+  Also fixed `Date.now()` script-tempfile collision class in
+  graphify.ts via `fs.mkdtempSync`. Affects every Python-based
+  tool dxkit installs (graphify, semgrep, ruff, pip-audit,
+  pip-licenses, coverage). Legacy `/tmp/graphify-venv` path still
+  probed, so existing installations aren't forced into a
+  reinstall. (10f.2)
+
+- **OSV.dev GHSA case-sensitivity** — `api.osv.dev/v1/vulns/<GHSA>`
+  expects lowercase; npm-audit emits uppercase. `osv.ts`
+  `DEFAULT_FETCHER` normalizes the alphabetic portion. Silently
+  broke alias resolution for every TS finding pre-2.3.0.
+
+### Changed — output directory
+
+- **Reports moved from `.ai/reports/` to `.dxkit/reports/`**.
+  Separates tool output (regenerated each run, can be gitignored)
+  from AI-agent context (`.ai/sessions/`, `.ai/prompts/` —
+  human-authored, version-controlled). All CLI commands + every
+  scaffolded slash command / agent / template updated to the new
+  path. Existing `.ai/reports/*.md` files become orphans after
+  upgrade — acceptable since reports regenerate each run.
+
+### Process
+
+- First full release cut through the 2.2.1-hardened publish
+  pipeline: 8 PRs, every one PR→CI→admin-squash-merge→main. Each
+  dog-fooded the pre-push CI-mirror hooks landed in PR #3.
+
+## [2.2.1] - 2026-04-23
+
+Patch release hardening the publish pipeline after `v2.2.0`'s Publish
+workflow failed with `403 — version already published`. The failure
+was caused by a local `npm publish` that preceded the
+Release-triggered CI publish, not a code defect — the tarball on npm
+byte-matches main. No functional changes in this release; all work
+is on the release path (tracked internally as D015).
+
+### Added — publish pipeline guardrails
+
+- **`scripts/require-ci.js` + `prepublishOnly` guard** — any `npm publish`
+  invocation outside GitHub Actions now fails at the script hook with
+  a clear error pointing to `CLAUDE.md §"Release procedure"`. Prevents
+  accidental local publish before the registry is ever contacted.
+
+- **`publishConfig.provenance: true`** — npm publishes now carry a
+  GitHub Actions provenance attestation. Provenance requires an OIDC
+  token that only exists inside Actions; tarball-mode publishes
+  (`npm publish *.tgz`, which skips `prepublishOnly`) also fail outside
+  CI. Belt-and-suspenders with the script guard.
+
+- **Publish-workflow preflights** (`.github/workflows/publish.yml`) —
+  before `npm publish` runs, the workflow now verifies (in order):
+  1. tag `vX.Y.Z` matches `package.json` version `X.Y.Z`
+  2. tagged commit is reachable from `origin/main` (blocks
+     feature-branch tags)
+  3. the `CI` workflow succeeded on the tagged commit SHA
+  4. `X.Y.Z` is not already on npm (catches the exact 2.2.0 failure)
+
+- **Explicit pack + publish + verify** — workflow packs the tarball,
+  records its sha1, publishes that exact file, then fetches
+  `npm view dist.shasum` and fails on mismatch. Eliminates drift
+  between "what npm packed" and "what we audited."
+
+- **Tarball workflow artifact** — every release archives the published
+  `.tgz` as a workflow artifact (90-day retention) for post-mortem
+  auditability.
+
+### Documented — `CLAUDE.md`
+
+New "Release procedure" section codifying PR → CI-green → merge → tag
+→ CI publishes as the only path. Explicit "no local `npm publish`"
+rule.
+
 ## [2.2.0] - 2026-04-23
 
 Minor release adding Snyk-style top-level dep attribution across every

package/README.md

@@ -15,8 +15,12 @@ Built so agent-written code has deterministic guardrails before it ships. Scores
 cd your-repo
 npx @vyuhlabs/dxkit tools install --yes      # one-time: install cloc, gitleaks, etc.
 npx @vyuhlabs/dxkit health --detailed         # 6-dimension score + remediation plan
-npx @vyuhlabs/dxkit vulnerabilities           # secret + SAST + dep-audit scan
+npx @vyuhlabs/dxkit vulnerabilities           # secret + SAST + dep-audit (ranked by risk)
+npx @vyuhlabs/dxkit bom --filter=top-level    # Bill of Materials w/ "This Week's Triage"
 npx @vyuhlabs/dxkit test-gaps                 # import-graph + coverage-aware
+npx @vyuhlabs/dxkit quality                   # slop + duplication + lint
+npx @vyuhlabs/dxkit licenses                  # dependency license inventory
+npx @vyuhlabs/dxkit dev-report                # git activity + contributors
 ```
 
 **Scaffold AI tooling into a repo:**
@@ -32,31 +36,33 @@ The two modes are complementary. The analyzers run anywhere; the scaffolder writ
 
 ## Analyzer CLI (`vyuh-dxkit <command>`)
 
-Seven deterministic analyzers. Each emits a markdown report to `.ai/reports/` and optional structured JSON.
+Seven deterministic analyzers. Each emits a markdown report to `.dxkit/reports/` and optional structured JSON.
 
-| Command           | What it does                                                                                                                                | Runtime | Output                                     |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------ |
-| `health`          | 6-dimension score (Testing, Quality, Docs, Security, Maint, DX)                                                                             | 10–20s  | `.ai/reports/health-audit-<date>.md`       |
-| `vulnerabilities` | gitleaks + semgrep + per-pack dep-audit (per-advisory detail in `--detailed`)                                                               | 5–30s   | `.ai/reports/vulnerability-scan-<date>.md` |
-| `test-gaps`       | Coverage artifact → import-graph → filename (strongest wins)                                                                                | <1s     | `.ai/reports/test-gaps-<date>.md`          |
-| `quality`         | Slop score + jscpd duplication + eslint/ruff + hygiene                                                                                      | 5–15s   | `.ai/reports/quality-review-<date>.md`     |
-| `dev-report`      | Commits, contributors, hot files, velocity, conventional %                                                                                  | <1s     | `.ai/reports/developer-report-<date>.md`   |
-| `licenses`        | Dependency license inventory across every active pack (TS/Python/Go/Rust/C#)                                                                | 5–20s   | `.ai/reports/licenses-<date>.md`           |
-| `bom`             | **Bill of Materials** — joins licenses + vulnerabilities per package, 15-col XLSX; groups advisories by top-level manifest dep (Snyk-style) | 10–40s  | `.ai/reports/bom-<date>.{md,xlsx}`         |
+| Command           | What it does                                                                                                                                                                                                                                                                                                          | Runtime | Output                                        |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------- |
+| `health`          | 6-dimension score (Testing, Quality, Docs, Security, Maint, DX)                                                                                                                                                                                                                                                       | 10–20s  | `.dxkit/reports/health-audit-<date>.md`       |
+| `vulnerabilities` | gitleaks + semgrep + per-pack dep-audit (per-advisory detail in `--detailed`)                                                                                                                                                                                                                                         | 5–30s   | `.dxkit/reports/vulnerability-scan-<date>.md` |
+| `test-gaps`       | Coverage artifact → import-graph → filename (strongest wins)                                                                                                                                                                                                                                                          | <1s     | `.dxkit/reports/test-gaps-<date>.md`          |
+| `quality`         | Slop score + jscpd duplication + eslint/ruff + hygiene                                                                                                                                                                                                                                                                | 5–15s   | `.dxkit/reports/quality-review-<date>.md`     |
+| `dev-report`      | Commits, contributors, hot files, velocity, conventional %                                                                                                                                                                                                                                                            | <1s     | `.dxkit/reports/developer-report-<date>.md`   |
+| `licenses`        | Dependency license inventory across every active pack (TS/Python/Go/Rust/C#)                                                                                                                                                                                                                                          | 5–20s   | `.dxkit/reports/licenses-<date>.md`           |
+| `bom`             | **Bill of Materials** — joins licenses + vulns per package, groups by top-level manifest dep (Snyk-style), enriches with CISA KEV + EPSS + reachability, ranks by composite risk score with "This Week's Triage" summary, aggregates nested sub-projects, `--filter=top-level` collapses transitive rows, 15-col XLSX | 10–40s  | `.dxkit/reports/bom-<date>.{md,xlsx}`         |
 
 Plus a converter: `vyuh-dxkit to-xlsx <json-file>` renders any `licenses` or `bom` detailed JSON as the canonical 15-column XLSX.
 
 ### Flags (apply to all analyzer commands)
 
-| Flag             | Effect                                                                                 |
-| ---------------- | -------------------------------------------------------------------------------------- |
-| `--detailed`     | Also writes `<name>-detailed.md` + `.json` with evidence + ranked remediation actions  |
-| `--json`         | Emit pure JSON on stdout. Logs go to stderr so pipes stay clean                        |
-| `--verbose`      | Print per-tool timing to stderr                                                        |
-| `--no-save`      | Skip writing markdown; useful with `--json`                                            |
-| `--xlsx`         | (`licenses`, `bom` only) Also write 15-col `.xlsx` — drop-in for spreadsheet workflows |
-| `-o <file>`      | (`licenses`, `bom`, `to-xlsx`) Override output path for xlsx / converted file          |
-| `--since <date>` | (`dev-report` only) Analyze commits on or after `YYYY-MM-DD`                           |
+| Flag             | Effect                                                                                                                                        |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--detailed`     | Also writes `<name>-detailed.md` + `.json` with evidence + ranked remediation actions                                                         |
+| `--json`         | Emit pure JSON on stdout. Logs go to stderr so pipes stay clean                                                                               |
+| `--verbose`      | Print per-tool timing to stderr                                                                                                               |
+| `--no-save`      | Skip writing markdown; useful with `--json`                                                                                                   |
+| `--xlsx`         | (`licenses`, `bom` only) Also write 15-col `.xlsx` — drop-in for spreadsheet workflows                                                        |
+| `-o <file>`      | (`licenses`, `bom`, `to-xlsx`) Override output path for xlsx / converted file                                                                 |
+| `--since <date>` | (`dev-report` only) Analyze commits on or after `YYYY-MM-DD`                                                                                  |
+| `--filter`       | (`bom` only) `all` (default) or `top-level` — keep only root manifest deps; the byTopLevelDep rollup still reflects transitives               |
+| `--no-nested`    | (`bom` only) Disable nested-project aggregation. Default discovers every sub-project with a language manifest under cwd and merges their BOMs |
 
 ### Detailed mode — evidence + ranked fixes
 
@@ -188,7 +194,7 @@ CLAUDE.md                  # Main context file for Claude Code
 
 The scaffolded slash commands (`/health`, `/vulnerabilities`, `/test-gaps`, `/quality`, `/dev-report`) use a three-tier fallback:
 
-1. **Check for an existing report** in `.ai/reports/` from today
+1. **Check for an existing report** in `.dxkit/reports/` from today
 2. **Run `vyuh-dxkit <command>`** — deterministic, fast, same output
 3. **Fall back to LLM analysis** only if the CLI isn't available
 
@@ -313,10 +319,10 @@ Both loops use the session framework — checkpoints, skill evolution, progress
 
 ## Reports
 
-All analyzer commands save timestamped reports to `.ai/reports/`:
+All analyzer commands save timestamped reports to `.dxkit/reports/`:
 
 ```
-.ai/reports/
+.dxkit/reports/
   health-audit-<date>.md
   health-audit-<date>-detailed.md           # with --detailed
   health-audit-<date>-detailed.json         # agent-consumable
@@ -359,12 +365,17 @@ When create-devstack writes `.project.yaml` before calling dxkit, detection and
 ## CLI Reference
 
 ```bash
-# Analyzer commands
-vyuh-dxkit health [path]              # 6-dimension score
-vyuh-dxkit vulnerabilities [path]     # Security scan
-vyuh-dxkit test-gaps [path]           # Coverage + gaps + actions
-vyuh-dxkit quality [path]             # Slop + duplication + lint
-vyuh-dxkit dev-report [path]          # Git activity report
+# Analyzer commands — each writes to .dxkit/reports/<name>-<date>.md
+vyuh-dxkit health [path]                       # 6-dimension score
+vyuh-dxkit vulnerabilities [path]              # Security scan, ranked by composite risk
+vyuh-dxkit test-gaps [path]                    # Coverage + gaps + actions
+vyuh-dxkit quality [path]                      # Slop + duplication + lint
+vyuh-dxkit dev-report [path] [--since <date>]  # Git activity report
+vyuh-dxkit licenses [path]                     # Dependency license inventory
+vyuh-dxkit bom [path] [--filter=top-level]     # Bill of Materials + risk-ranked triage
+
+# Data conversion
+vyuh-dxkit to-xlsx <json-file>        # render licenses/bom detailed JSON as 15-col XLSX
 
 # Tool management
 vyuh-dxkit tools                      # status

package/dist/analyzers/bom/discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Project-root discovery for nested BOM aggregation.
+ *
+ * `vyuh-dxkit bom <path>` historically scanned `<path>` as a single
+ * project root. Repos like `vyuhlabs-platform/` (root devtools +
+ * `userserver/` product) fell through the cracks — the scanner saw
+ * only whichever `package.json`/lockfile lived at `<path>`, missing
+ * every sibling or nested sub-project. See D001a in the internal
+ * defect log for the incident write-up.
+ *
+ * This module walks the filesystem starting at cwd and returns every
+ * directory that looks like an independent project root (i.e. has any
+ * language manifest, regardless of whether a parent also does). The
+ * BOM analyzer then runs the existing per-root gather against each
+ * and merges the results.
+ *
+ * Why a hardcoded skip-set rather than `exclusions.ts`: this is a
+ * structural traversal, not a gitignore-based code scan. `exclusions.ts`
+ * is tuned for "which files does the user consider source code?" and
+ * pulls in `.gitignore` rules that would incorrectly hide sibling
+ * projects (e.g. `.gitignore: dist/` would skip a sub-project under
+ * `dist/` even though it might legitimately be a shippable artifact
+ * the user wants inventoried).
+ */
+/**
+ * Walk `cwd` and return every directory that contains at least one
+ * language manifest. Always includes `cwd` itself when it has one,
+ * even if nested sub-projects also exist (the aggregator treats all
+ * roots symmetrically and dedupes findings across them).
+ *
+ * Pure over the filesystem: no caching, no side effects beyond
+ * filesystem reads. Returns absolute paths, sorted alphabetically
+ * for deterministic output.
+ *
+ * Exported for unit tests.
+ */
+export declare function discoverProjectRoots(cwd: string, maxDepth?: number): string[];
+//# sourceMappingURL=discovery.d.ts.map

package/dist/analyzers/bom/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/analyzers/bom/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA2DH;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAA0B,GAAG,MAAM,EAAE,CAIhG"}

package/dist/analyzers/bom/discovery.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Project-root discovery for nested BOM aggregation.
+ *
+ * `vyuh-dxkit bom <path>` historically scanned `<path>` as a single
+ * project root. Repos like `vyuhlabs-platform/` (root devtools +
+ * `userserver/` product) fell through the cracks — the scanner saw
+ * only whichever `package.json`/lockfile lived at `<path>`, missing
+ * every sibling or nested sub-project. See D001a in the internal
+ * defect log for the incident write-up.
+ *
+ * This module walks the filesystem starting at cwd and returns every
+ * directory that looks like an independent project root (i.e. has any
+ * language manifest, regardless of whether a parent also does). The
+ * BOM analyzer then runs the existing per-root gather against each
+ * and merges the results.
+ *
+ * Why a hardcoded skip-set rather than `exclusions.ts`: this is a
+ * structural traversal, not a gitignore-based code scan. `exclusions.ts`
+ * is tuned for "which files does the user consider source code?" and
+ * pulls in `.gitignore` rules that would incorrectly hide sibling
+ * projects (e.g. `.gitignore: dist/` would skip a sub-project under
+ * `dist/` even though it might legitimately be a shippable artifact
+ * the user wants inventoried).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverProjectRoots = discoverProjectRoots;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** File basenames that mark a directory as a project root. */
+const MANIFEST_BASENAMES = new Set([
+    'package.json', // Node
+    'pyproject.toml', // Python (PEP 621 / poetry)
+    'requirements.txt', // Python (pip)
+    'setup.py', // Python (legacy)
+    'Pipfile', // Python (pipenv)
+    'go.mod', // Go
+    'Cargo.toml', // Rust
+]);
+/** File extensions that mark a directory as a project root. */
+const MANIFEST_EXTENSIONS = [
+    '.csproj', // C# project
+    '.sln', // C# solution
+];
+/**
+ * Directories we never descend into during discovery.
+ *
+ *   - Dependency trees (`node_modules`, `vendor`, `venv`, `.venv`,
+ *     `target`, `bin`, `obj`): contain manifests from installed
+ *     packages, not user projects.
+ *   - Build output (`dist`, `build`, `out`, `.next`, `.turbo`,
+ *     `.cache`): derived, not source-of-truth.
+ *   - VCS / tool metadata (`.git`, `.svn`, `.hg`): never has
+ *     meaningful manifests.
+ *
+ * Any dotfile directory is also skipped — caches, IDE state, etc.
+ */
+const SKIP_DIR_BASENAMES = new Set([
+    'node_modules',
+    'vendor',
+    'venv',
+    '.venv',
+    'target',
+    'bin',
+    'obj',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.turbo',
+    '.cache',
+    '.git',
+    '.svn',
+    '.hg',
+    'TestResults',
+    'packages',
+]);
+/** Default depth cap: enough for `packages/foo/sub`, excess discouraged. */
+const DEFAULT_MAX_DEPTH = 4;
+/**
+ * Walk `cwd` and return every directory that contains at least one
+ * language manifest. Always includes `cwd` itself when it has one,
+ * even if nested sub-projects also exist (the aggregator treats all
+ * roots symmetrically and dedupes findings across them).
+ *
+ * Pure over the filesystem: no caching, no side effects beyond
+ * filesystem reads. Returns absolute paths, sorted alphabetically
+ * for deterministic output.
+ *
+ * Exported for unit tests.
+ */
+function discoverProjectRoots(cwd, maxDepth = DEFAULT_MAX_DEPTH) {
+    const roots = new Set();
+    walk(cwd, 0, maxDepth, roots);
+    return [...roots].sort();
+}
+function walk(dir, depth, maxDepth, roots) {
+    if (depth > maxDepth)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    let isRoot = false;
+    for (const e of entries) {
+        if (!e.isFile())
+            continue;
+        if (MANIFEST_BASENAMES.has(e.name)) {
+            isRoot = true;
+            break;
+        }
+        if (MANIFEST_EXTENSIONS.some((ext) => e.name.endsWith(ext))) {
+            isRoot = true;
+            break;
+        }
+    }
+    if (isRoot)
+        roots.add(dir);
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        if (SKIP_DIR_BASENAMES.has(e.name))
+            continue;
+        // Skip dotfile directories (caches, IDE state) except the repo root's own.
+        if (e.name.startsWith('.') && depth > 0)
+            continue;
+        walk(path.join(dir, e.name), depth + 1, maxDepth, roots);
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/analyzers/bom/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/analyzers/bom/discovery.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/bom/gather.d.ts

@@ -58,6 +58,34 @@ export interface BomGatherResult {
     entries: BomEntry[];
     toolsUsed: string[];
     toolsUnavailable: string[];
+    /** Cwd-relative project-root paths the gather walked. Length 1 for
+     *  single-root scans ("." ); length >1 for nested aggregation. */
+    projectRoots: string[];
 }
+/**
+ * Merge per-root gather results into one deduplicated set.
+ *
+ * Dedupe key is `(package, version)` — the same logical package at
+ * the same version installed under two roots is the same artifact,
+ * so reporting two rows would be noise. When the same key appears
+ * under multiple roots:
+ *
+ *   - `sources` unions the sub-paths
+ *   - `isTopLevel` OR-merges — if any root treats the package as
+ *     top-level, the merged entry is top-level (upgrade decisions
+ *     surface under Top-Level Dep Groups)
+ *   - `vulns` unions with dedup on `(id, package, installedVersion)`
+ *     — the same advisory reported from two roots collapses into
+ *     one finding but its `topLevelDep` list unions
+ *   - license metadata (licenseType, sourceUrl, etc.) prefers the
+ *     first root with non-UNKNOWN data, falling back to whatever
+ *     the first-seen entry carried
+ *
+ * Pure function; unit-testable without filesystem.
+ */
+export declare function mergeNestedBomEntries(perRoot: ReadonlyArray<{
+    relPath: string;
+    result: BomGatherResult;
+}>): BomGatherResult;
 export declare function gatherBomEntries(cwd: string): Promise<BomGatherResult>;
 //# sourceMappingURL=gather.d.ts.map

package/dist/analyzers/bom/gather.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../src/analyzers/bom/gather.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,oCAAoC,CAAC;AACzF,OAAO,KAAK,EAAE,QAAQ,EAAe,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIxE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1D;AAED;mDACmD;AACnD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,CAQrE;AAYD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAkCzF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiF5E"}
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../src/analyzers/bom/gather.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,oCAAoC,CAAC;AACzF,OAAO,KAAK,EAAE,QAAQ,EAAe,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIxE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1D;AAED;mDACmD;AACnD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,CAQrE;AAYD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAkCzF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;sEACkE;IAClE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC,GACnE,eAAe,CAkEjB;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAkF5E"}