bomly-dev
diff --git a/‎dev-docs/ARCHITECTURE.md‎
Lines changed: 8 additions & 0 deletions b/‎dev-docs/ARCHITECTURE.md‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎dev-docs/MODELS.md‎
Lines changed: 51 additions & 0 deletions b/‎dev-docs/MODELS.md‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎docs/ARCHITECTURE.md‎
Lines changed: 23 additions & 0 deletions b/‎docs/ARCHITECTURE.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎docs/MCP.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/MCP.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/SCAN_TARGETS.md‎
Lines changed: 11 additions & 0 deletions b/‎docs/SCAN_TARGETS.md‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎docs/TUI.md‎
Lines changed: 3 additions & 1 deletion b/‎docs/TUI.md‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎internal/cli/cmd_progress.go‎
Lines changed: 6 additions & 0 deletions b/‎internal/cli/cmd_progress.go‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎internal/cli/opts/options.go‎
Lines changed: 4 additions & 1 deletion b/‎internal/cli/opts/options.go‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎internal/cli/opts/options_test.go‎
Lines changed: 3 additions & 1 deletion b/‎internal/cli/opts/options_test.go‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎internal/cli/render/reachability_test.go‎
Lines changed: 2 additions & 2 deletions b/‎internal/cli/render/reachability_test.go‎
Lines changed: 2 additions & 2 deletions
@@ -132,6 +132,14 @@ The MCP server does not return the CLI JSON documents at all. Tool results land
 
 Discovery rules are **detector-owned, not hardcoded**: each detector declares its ecosystem's ignore rules on its descriptor (`sdk.DetectorDescriptor.IgnoredDirectories` basename globs and `IgnoredDirectoryMarkers` marker files such as `pyvenv.cfg`) and marks workspace-expanding support entries with `sdk.PackageManagerSupport.MultiModule` (via `sdk.Support(...).WithMultiModule()`). Discovery aggregates the union across every registered detector (`discoveryRulesFromDetectors`), so external detector plugins contribute rules exactly like built-ins — the fields ride the existing descriptor JSON, making them backward compatible with the v1 plugin protocol (older plugins simply omit them). The walk aggregates from the request's **unfiltered** registry so `--detectors`/`--ecosystems` filters never change which directories are walked; the diagnostic probe falls back to the static built-in catalog (`registry.BuiltinDetectors`). Dot-directory skipping stays core walk behavior, independent of detector declarations.
 
+### Decision: Subprojects and modules are distinct concepts, derived in views
+
+A **subproject** is an independently discovered nested directory (its own discovery-time `sdk.Subproject`, `RelativePath != "."`); a **module** is a member the package manager natively resolves under one root manifest (reactor module, workspace member). The hierarchy is never stored: `output.ClassifyManifest`/`BuildHierarchy` (`internal/output/hierarchy.go`) derive it purely from each manifest's `Subproject` and repo-relative `Path` — a manifest whose directory sits below its subproject directory is a module manifest. Every surface (TUI trees, text report tree, markdown table, MCP compact counts) consumes the same helper, so the JSON schema gained no fields and consumers can apply the identical rule. The scan JSON's per-manifest `subproject` string plus `path` is therefore the single source of truth for project structure.
+
+### Decision: Per-module manifest emission lives in detectors, not consolidation
+
+Workspace/reactor detectors (npm and pnpm lockfile, cargo, maven) emit one `GraphEntry{Graph, ManifestMetadata}` per module using the pre-existing multi-entry `sdk.GraphContainer` — no SDK type changes. Each module entry carries the module's application root plus its reachable subtree (`detectors.SubgraphFrom`), with paths subproject-relative so consolidation's existing rebase/dedup layer stays a pure select/dedup/rebase stage. Shared transitives appear in multiple entries by design; the merged graph and PURL registry deduplicate them, and report-level counts (text manifest count, markdown/MCP package totals) deduplicate by PURL/ID rather than summing per-manifest lengths. Module directories come from the best per-ecosystem source: npm packages-map member keys, pnpm importer keys, `cargo metadata` member `manifest_path` (or `[workspace] members` globs + member `Cargo.toml`s on the lock path — which also fixed virtual workspace roots erroring), and a recursive pom `<modules>` walk for maven (TGF output carries no paths; unmatched graph roots fall back into the root entry, and any walk failure degrades to today's single merged manifest). **Deferred, degrade to one merged root manifest**: gradle and sbt (no machine-readable per-module graph in one invocation), mix and pub (low value/tool limits), yarn classic (v1 lockfiles carry no member info; berry is a follow-up), and the node *native* detectors (`npm ls` is root-scoped; per-member subprocess fan-out multiplies runtime while the lockfile detectors are the chain primaries anyway).
+
 ### Decision: Package locations are detector-relative today
 
 `PackageLocation.Position.File` is emitted by detectors in the coordinate space of the detector working directory. For single-root projects that is already repository-relative, which lets `bomly diff` compare SARIF locations with repo-relative changed-line ranges.
 
@@ -26,6 +26,46 @@ flowchart TD
     F -->|PackageRef + VulnerabilityID| P
 ```
 
+## Project structure: projects, subprojects, modules, manifests
+
+How dependencies relate to manifests, and manifests to the project tree. A
+**subproject** is an independently discovered nested directory (its own
+`sdk.Subproject`, what `--recursive` finds); a **module** is a member the
+package manager natively resolves under one root manifest (reactor module,
+workspace member) and gets its own manifest entry from the detector. A
+project/module and its manifest are two faces of the same thing — user-facing
+views merge them into one node when the mapping is 1:1; machine formats
+(JSON, SARIF, SBOM) keep the flat manifests collection.
+
+```mermaid
+flowchart TD
+    PR["Project (scan root)"]
+    SP["Subproject<br/><i>independently discovered nested dir</i><br/>sdk.Subproject, RelativePath != &quot;.&quot;"]
+    MOD["Module<br/><i>workspace/reactor member</i><br/>manifest dir below its subproject dir"]
+    MAN["Manifest entry<br/>sdk.GraphEntry{Graph, ManifestMetadata}<br/>path, kind, resolution"]
+    ROOT["Module root node<br/>sdk.Dependency, Type=application<br/><i>the project/module's own package</i>"]
+    DEP["Dependency instances<br/>sdk.Dependency (direct + transitive)"]
+    PKG["sdk.Package registry<br/>deduplicated by PURL"]
+
+    PR -->|"discovers (recursive walk)"| SP
+    PR -->|"root manifests attach directly"| MAN
+    SP -->|"its own manifests"| MAN
+    SP -->|"native expansion (npm, pnpm, cargo, maven)"| MOD
+    PR -->|"native expansion at the root"| MOD
+    MOD -->|"exactly one"| MAN
+    MAN -->|"graph root"| ROOT
+    ROOT -->|"reachable subtree"| DEP
+    DEP -->|"PURL identity (shared transitives dedup)"| PKG
+```
+
+Derivation rule (implemented once in `output.ClassifyManifest` /
+`BuildHierarchy`, consumed by every view): `dir(manifest.path)` equal to the
+manifest's `subproject` directory → the manifest belongs directly to that
+subproject (or the project when `"."`); `dir(manifest.path)` nested beneath it
+→ a module keyed by that directory. Shared transitive dependencies appear in
+every module entry that reaches them; the PURL-keyed registry counts each
+package once.
+
 ## `sdk.Dependency` — detection node
 
 ```go
@@ -205,6 +245,17 @@ dependencies are **lean** — they carry detection-time facts and a `package_ref
 into `packages`, but no inlined vulnerabilities/scorecard. Enrichment lives once,
 in `packages`, and is resolved by PURL.
 
+For workspace/reactor package managers (npm, pnpm, cargo, maven) the manifests
+collection carries **one entry per module** — e.g. `apps/web/package.json`
+alongside the root `package-lock.json` — each listing the module's reachable
+dependency instances (shared transitives appear under every module that
+reaches them; `packages` still deduplicates by PURL). Consumers derive the
+project hierarchy from the existing fields without schema additions: each
+manifest's `subproject` names its discovery directory ("." for the scan
+root), and a manifest whose `path` directory sits *below* its subproject
+directory is a **module** manifest (`output.ClassifyManifest` /
+`output.BuildHierarchy` implement this rule for every built-in view).
+
 ```jsonc
 {
   "schema_version": "1.0",
 
@@ -64,6 +64,29 @@ flowchart TD
 
 In the JSON output these surface as three top-level collections — `manifests` (with their `dependencies`), `packages`, and `findings` — and the same vocabulary carries through SARIF and SBOM output. See [Output formats](OUTPUT_FORMATS.md) and the [schema reference](SCHEMAS.md) for the exact shapes.
 
+Manifests themselves hang off the project structure. A **subproject** is an independently discovered nested directory (what `--recursive` finds); a **module** is a workspace or reactor member the package manager resolves natively (npm/pnpm workspace packages, Cargo workspace members, Maven reactor modules), each with its own manifest entry. A project or module and its manifest are two faces of the same thing, so user-facing views (interactive mode, text, markdown) merge them into a single named node; machine formats keep the flat `manifests` collection, from which the hierarchy is derived using the `subproject` and `path` fields.
+
+```mermaid
+flowchart TD
+    PR["Project (scan root)"]
+    SP["Subproject — nested dir<br/>discovered by --recursive"]
+    MOD["Module — workspace/reactor member<br/>resolved by the package manager"]
+    MAN["Manifest<br/>(path, kind, detector, resolution)"]
+    ROOT["Module's own package<br/>(graph root, application)"]
+    DEP[Dependency instances]
+    P2[Packages, deduplicated by PURL]
+
+    PR -->|discovers| SP
+    PR -->|root manifests| MAN
+    SP -->|its manifests| MAN
+    PR -->|workspace / reactor expansion| MOD
+    SP -->|workspace / reactor expansion| MOD
+    MOD -->|one manifest each| MAN
+    MAN -->|graph root| ROOT
+    ROOT -->|direct + transitive| DEP
+    DEP -->|shared transitives count once| P2
+```
+
 ## Extensibility
 
 Every built-in is an implementation of the same contract an external plugin implements — there is no privileged internal path. Three extension points are pluggable today, and a fourth is planned:
 
@@ -108,7 +108,7 @@ MCP tool results land in an agent's context window, so they use a compact respon
 
 `bomly_scan` returns:
 
-- **`summary`** — manifest/package counts, vulnerable vs clean packages, findings by severity, and whether enrich/audit ran. Clean packages are counted, never listed.
+- **`summary`** — manifest/package counts, `subprojects` and `modules` counts for scans that span nested projects or workspace/reactor members (omitted for flat scans), vulnerable vs clean packages, findings by severity, and whether enrich/audit ran. Clean packages are counted, never listed. The full hierarchy is derived from `manifests[].subproject` + `path` in the complete CLI JSON document.
 - **`remediations`** — ranked groups, each one concrete change and every finding it closes: the direct dependency to change (`target_package`, full identity with org/scope and PURL), the manifest to edit, the version to move to, and an `action` (`direct-bump`, `transitive-override`, `lockfile-refresh`, `no-fix-upstream`, `policy-review`). Transitive cases carry package-manager-specific `override_advice` (npm `overrides`, pnpm `pnpm.overrides` / `pnpm-workspace.yaml`, yarn `resolutions`, Maven `dependencyManagement`, Gradle constraints, `go get` + `go mod tidy`, and so on). Groups are ranked by known-exploited (KEV) first, then severity, EPSS, and fixability.
 - **`informational`** — warn-disposition and policy-only findings, separated from actionable work.
 - **`diagnostics`** — pipeline warnings (detector fallbacks, matcher failures) so partial results explain themselves.
 
@@ -77,6 +77,17 @@ A nested `go.mod` is an independent Go module by language semantics, so every ne
 
 Like the ignore rules, multi-module expansion is declared by each detector (`sdk.PackageManagerSupport.MultiModule`), so external detector plugins can opt their package manager into pruning.
 
+## Subprojects and modules in scan output
+
+Scan output distinguishes two kinds of nesting:
+
+- A **subproject** is an independently discovered nested directory (its own detector run) — what `--recursive` finds.
+- A **module** is a member the package manager natively resolves under one root manifest: a Maven reactor module, an npm/pnpm workspace member, a Cargo workspace member.
+
+The npm, pnpm, cargo, and maven detectors emit **one manifest entry per module** — `apps/web/package.json`, `crates/api/Cargo.toml`, `core/pom.xml` — alongside the root manifest, each carrying the module's reachable dependency subtree (a virtual Cargo workspace root emits member entries only). Detectors without per-module emission (gradle, sbt, mix, yarn classic, pub, and the node *native* detectors) keep one merged root manifest.
+
+Every view derives the same hierarchy from the manifests' `subproject` and `path` fields — no extra JSON fields: the interactive components tab shows subproject and module nodes with their manifests, the text report renders a grouped manifest tree, the markdown manifest table carries a Location column, and the MCP compact summary reports `subprojects`/`modules` counts. JSON consumers can group rows the same way: a manifest whose directory sits below its `subproject` directory is a module manifest.
+
 ## Git repository — `--url` and `--ref`
 
 Clone-then-scan, all in one step.
 
@@ -20,14 +20,16 @@ Switch with the number keys or `Tab`:
 | Key | View | What's shown |
 | --- | --- | --- |
 | `1` | Overview | Scan summary, totals by ecosystem and severity |
-| `2` | Packages | Full dependency list with tree expansion |
+| `2` | Components | Project tree: manifests and their dependency trees |
 | `3` | Vulnerabilities | Findings grouped by package |
 | `4` | Licenses | License inventory and conflicts |
 | `5` | Findings | Audit policy hits with reasons |
 | `6` | Source | Detected manifest and lockfile inventory |
 
 `Tab` cycles forward through views; `Shift+Tab` is the reverse cycle in supporting terminals.
 
+The Components tree groups manifests the way the project is actually laid out: manifests at the scan root sit directly under the project node, **subproject** nodes hold the manifests of independently discovered nested directories (what `--recursive` finds), and **module** nodes hold workspace/reactor members (npm/pnpm workspace packages, Cargo workspace members, Maven reactor modules) that resolve under one root manifest. Flat single-root scans keep a plain project → manifests tree. Group nodes expand and collapse like any other row, and their details pane shows the directory, ecosystems, and manifest counts. See [Scan targets](SCAN_TARGETS.md#subprojects-and-modules-in-scan-output) for the terminology.
+
 ## Navigation
 
 | Key | Action |
 
@@ -56,6 +56,12 @@ func subprojectProgressChildren(results []sdk.DetectionResult) []progress.Child
 		if detail != "" {
 			label += " (" + detail + ")"
 		}
+		// Multi-module resolutions (workspaces, reactors) produce one manifest
+		// entry per module; surface the count so the step explains the fan-out.
+		if r.Graphs != nil && len(r.Graphs.Entries) > 1 {
+			children = append(children, progress.Child{Label: label, Detail: fmt.Sprintf("[%d manifests]", len(r.Graphs.Entries))})
+			continue
+		}
 		children = append(children, progress.Child{Label: label})
 	}
 	return children
 
@@ -457,9 +457,12 @@ func displayTargetName(target sdk.ExecutionTarget) string {
 	if strings.TrimSpace(location) == "" {
 		return ""
 	}
-	if target.Kind == sdk.ExecutionTargetContainerImage || target.Kind == sdk.ExecutionTargetGitRepository {
+	if target.Kind == sdk.ExecutionTargetContainerImage {
 		return location
 	}
+	// Git repositories and filesystem paths both name themselves after the
+	// last path segment — the repo or directory name. The full URL stays
+	// available as the descriptor's Path.
 	trimmed := strings.TrimSuffix(strings.TrimRight(location, `/\`), ".git")
 	if idx := strings.LastIndexAny(trimmed, `/\`); idx >= 0 && idx < len(trimmed)-1 {
 		return trimmed[idx+1:]
 
@@ -52,9 +52,11 @@ func TestProjectDescriptor_UsesUserFacingTargetLabels(t *testing.T) {
 		t.Fatalf("unexpected container project descriptor: %#v", containerProject)
 	}
 
+	// Git repositories name themselves after the repo (last URL segment,
+	// .git trimmed); the full URL remains the descriptor's Path.
 	urlOptions := Options{executionTarget: sdk.ExecutionTarget{Kind: sdk.ExecutionTargetGitRepository, Location: `C:\Temp\bomly-clone`, RepositoryURL: "https://github.com/acme/demo.git", Ref: "main"}}
 	urlProject := urlOptions.ProjectDescriptor()
-	if urlProject.Name != "https://github.com/acme/demo.git" || urlProject.Path != "https://github.com/acme/demo.git" || urlProject.TargetType != "git repository" || urlProject.TargetRef != "main" {
+	if urlProject.Name != "demo" || urlProject.Path != "https://github.com/acme/demo.git" || urlProject.TargetType != "git repository" || urlProject.TargetRef != "main" {
 		t.Fatalf("unexpected url project descriptor: %#v", urlProject)
 	}
 }
 
@@ -41,7 +41,7 @@ func TestScanRendersReachabilityColumnWhenEnabled(t *testing.T) {
 			Source:          "osv",
 		},
 	}
-	out := Scan(g, registry, findings, nil /*matcherStats*/, true /*enrich*/, true /*audit*/, true /*reachability*/, nil /*failOn*/, "" /*subprojectSummary*/, nil /*fallbackNotices*/)
+	out := Scan(g, registry, findings, nil /*matcherStats*/, true /*enrich*/, true /*audit*/, true /*reachability*/, nil /*failOn*/, nil /*manifests*/, nil /*fallbackNotices*/)
 	// The compact text format shows the finding CVE ID and package name; detailed
 	// reachability info is available in the JSON and Markdown output formats.
 	if !strings.Contains(StripANSI(out), "CVE-2024-0001") {
@@ -218,7 +218,7 @@ func TestScanOmitsReachabilityColumnWhenDisabled(t *testing.T) {
 	findings := []model.Finding{
 		{ID: "CVE-2024-0001", Kind: model.FindingKindVulnerability, PackageRef: pkg.PURL, Severity: "high", Title: "x", Source: "osv"},
 	}
-	out := Scan(g, nil, findings, nil, true, true, false, nil, "", nil)
+	out := Scan(g, nil, findings, nil, true, true, false, nil, nil, nil)
 	// Compact text format never shows a REACHABILITY column; detailed info is in JSON/Markdown.
 	if strings.Contains(StripANSI(out), "REACHABILITY") {
 		t.Fatalf("REACHABILITY column should not appear in compact text output; got:\n%s", out)
Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,12 @@ func subprojectProgressChildren(results []sdk.DetectionResult) []progress.Child`
`56`	`56`	`if detail != "" {`
`57`	`57`	`label += " (" + detail + ")"`
`58`	`58`	`}`
	`59`	`+ // Multi-module resolutions (workspaces, reactors) produce one manifest`
	`60`	`+ // entry per module; surface the count so the step explains the fan-out.`
	`61`	`+ if r.Graphs != nil && len(r.Graphs.Entries) > 1 {`
	`62`	`+ children = append(children, progress.Child{Label: label, Detail: fmt.Sprintf("[%d manifests]", len(r.Graphs.Entries))})`
	`63`	`+ continue`
	`64`	`+ }`
`59`	`65`	`children = append(children, progress.Child{Label: label})`
`60`	`66`	`}`
`61`	`67`	`return children`
Original file line number	Diff line number	Diff line change
`@@ -457,9 +457,12 @@ func displayTargetName(target sdk.ExecutionTarget) string {`
`457`	`457`	`if strings.TrimSpace(location) == "" {`
`458`	`458`	`return ""`
`459`	`459`	`}`
`460`		`- if target.Kind == sdk.ExecutionTargetContainerImage \|\| target.Kind == sdk.ExecutionTargetGitRepository {`
	`460`	`+ if target.Kind == sdk.ExecutionTargetContainerImage {`
`461`	`461`	`return location`
`462`	`462`	`}`
	`463`	`+ // Git repositories and filesystem paths both name themselves after the`
	`464`	`+ // last path segment — the repo or directory name. The full URL stays`
	`465`	`+ // available as the descriptor's Path.`
`463`	`466`	trimmed := strings.TrimSuffix(strings.TrimRight(location, `/\`), ".git")
`464`	`467`	if idx := strings.LastIndexAny(trimmed, `/\`); idx >= 0 && idx < len(trimmed)-1 {
`465`	`468`	`return trimmed[idx+1:]`
Original file line number	Diff line number	Diff line change
`@@ -52,9 +52,11 @@ func TestProjectDescriptor_UsesUserFacingTargetLabels(t *testing.T) {`
`52`	`52`	`t.Fatalf("unexpected container project descriptor: %#v", containerProject)`
`53`	`53`	`}`
`54`	`54`
	`55`	`+ // Git repositories name themselves after the repo (last URL segment,`
	`56`	`+ // .git trimmed); the full URL remains the descriptor's Path.`
`55`	`57`	urlOptions := Options{executionTarget: sdk.ExecutionTarget{Kind: sdk.ExecutionTargetGitRepository, Location: `C:\Temp\bomly-clone`, RepositoryURL: "https://github.com/acme/demo.git", Ref: "main"}}
`56`	`58`	`urlProject := urlOptions.ProjectDescriptor()`
`57`		`- if urlProject.Name != "https://github.com/acme/demo.git" \|\| urlProject.Path != "https://github.com/acme/demo.git" \|\| urlProject.TargetType != "git repository" \|\| urlProject.TargetRef != "main" {`
	`59`	`+ if urlProject.Name != "demo" \|\| urlProject.Path != "https://github.com/acme/demo.git" \|\| urlProject.TargetType != "git repository" \|\| urlProject.TargetRef != "main" {`
`58`	`60`	`t.Fatalf("unexpected url project descriptor: %#v", urlProject)`
`59`	`61`	`}`
`60`	`62`	`}`