Skip to content

Commit b7eee7e

Browse files
bomly-guyclaude
andcommitted
refactor(sdk): shorten discovery field names and document rules per detector
- Rename DetectorDescriptor.DiscoveryIgnoredDirectories → IgnoredDirectories, DiscoveryIgnoredDirectoryMarkers → IgnoredDirectoryMarkers, and PackageManagerSupport.NativeMultiModule → MultiModule (helper WithNativeMultiModule → WithMultiModule); JSON tags follow suit. - Generated per-package-manager detector pages now carry the detector-declared discovery metadata: "Ignored directories", "Ignored directory markers", and "Multi-module resolution" rows, emitted by the componentdocs generator from the same descriptors discovery consumes, plus a how-to-read note on the ecosystem indexes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 687e2a3 commit b7eee7e

105 files changed

Lines changed: 415 additions & 178 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

dev-docs/ARCHITECTURE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ The MCP server does not return the CLI JSON documents at all. Tool results land
130130

131131
`--recursive` discovery (`planRecursiveFilesystemSubprojects`, `internal/cli/opts/planning_recursive.go`) walks the tree with `filepath.WalkDir` and plans subprojects through the same `plannedSubprojectsForPath` helper the root-only path uses. When a package manager whose detector natively expands nested modules (maven, gradle, npm, pnpm, yarn, cargo, sbt, mix) has manifest evidence at an ancestor directory, nested subprojects for that same manager are pruned: the ancestor's detector resolves those modules already (reactor TGF blocks, workspace lockfile importers, `cargo metadata` workspace members), so planning them separately would double-count every dependency. Pruning is per package manager and never skips the directory itself — a Maven ancestor must not hide a nested `requirements.txt`. `gomod` deliberately never prunes: a nested `go.mod` is excluded from the parent module by Go semantics, and the gomod detector has no `go.work` awareness, so each module scans independently (package dedup by PURL absorbs any overlap). Depth counts the root as 0 with a default cap of 3 (`--max-depth 0` = unlimited), matching the discovery probe's existing depth so error hints and the real walk agree. The resolve worker pool stays capped at 4 (`resolveWorkerCount`): recursion mostly adds cheap lockfile subprojects, and raising the cap would multiply concurrent JVM/node build-tool processes on monorepos; revisit only if large lockfile-heavy monorepos show wall-clock pain.
132132

133-
Discovery rules are **detector-owned, not hardcoded**: each detector declares its ecosystem's ignore rules on its descriptor (`sdk.DetectorDescriptor.DiscoveryIgnoredDirectories` basename globs and `DiscoveryIgnoredDirectoryMarkers` marker files such as `pyvenv.cfg`) and marks workspace-expanding support entries with `sdk.PackageManagerSupport.NativeMultiModule` (via `sdk.Support(...).WithNativeMultiModule()`). 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.
133+
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.
134134

135135
### Decision: Package locations are detector-relative today
136136

docs/PLUGINS.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -167,9 +167,9 @@ Detector plugins can participate in subproject discovery. Their runtime descript
167167

168168
Detector plugins can also shape recursive discovery (`--recursive`) through three optional descriptor fields, all aggregated across every registered detector exactly like the built-ins' declarations:
169169

170-
- `DetectorDescriptor.DiscoveryIgnoredDirectories` — directory basename globs the recursive walk must not descend into (a Node detector declares `node_modules`, a Maven detector declares `target`).
171-
- `DetectorDescriptor.DiscoveryIgnoredDirectoryMarkers` — file names whose presence marks a directory as ignored regardless of its name (the Python detectors declare `pyvenv.cfg` to skip virtualenvs).
172-
- `PackageManagerSupport.NativeMultiModule` (set via `sdk.Support(...).WithNativeMultiModule()`) — declares that the detector natively expands nested workspace/reactor modules from a root manifest, so recursive discovery prunes nested subprojects for the same package manager below a detected root instead of scanning the modules twice.
170+
- `DetectorDescriptor.IgnoredDirectories` — directory basename globs the recursive walk must not descend into (a Node detector declares `node_modules`, a Maven detector declares `target`).
171+
- `DetectorDescriptor.IgnoredDirectoryMarkers` — file names whose presence marks a directory as ignored regardless of its name (the Python detectors declare `pyvenv.cfg` to skip virtualenvs).
172+
- `PackageManagerSupport.MultiModule` (set via `sdk.Support(...).WithMultiModule()`) — declares that the detector natively expands nested workspace/reactor modules from a root manifest, so recursive discovery prunes nested subprojects for the same package manager below a detected root instead of scanning the modules twice.
173173

174174
All three are optional and older plugins that omit them keep working unchanged.
175175

docs/SCAN_TARGETS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ When a package manager whose detector natively expands nested modules is detecte
7575

7676
A nested `go.mod` is an independent Go module by language semantics, so every nested Go module becomes its own subproject (`go.work` workspaces are also scanned per-module). Pruning is per package manager: a Maven root does not hide a nested `requirements.txt`.
7777

78-
Like the ignore rules, multi-module expansion is declared by each detector (`sdk.PackageManagerSupport.NativeMultiModule`), so external detector plugins can opt their package manager into pruning.
78+
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.
7979

8080
## Git repository — `--url` and `--ref`
8181

docs/detectors/ecosystems/alpm/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Package managers Bomly recognizes in the `alpm` ecosystem:
1313
- Each package-manager page documents the exact commands Bomly runs (if any), the network behavior, and the lockfile or manifest formats supported.
1414
- Bomly tries detector chains from left to right. Later detectors in the chain are fallbacks Bomly uses when the preferred detector cannot produce graph data.
1515
- Install-first support means `--install-first` can run the package manager's normal install command before graph resolution. This downloads packages and modifies the filesystem; see [docs/DETECTORS.md](../../../DETECTORS.md#install-first).
16+
- Each package-manager page also lists the directories its detectors declare as ignored during recursive discovery (`--recursive`) and whether the chain resolves nested workspace/reactor modules from a root manifest (multi-module); see [docs/SCAN_TARGETS.md](../../../SCAN_TARGETS.md#recursive-discovery----recursive).
1617
- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

docs/detectors/ecosystems/alpm/alpm.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,8 @@ Bomly uses this chain when it finds `alpm` evidence.
1010
| Ecosystem | `alpm` |
1111
| Detector chain | `syft-detector` |
1212
| Evidence patterns | `var/lib/pacman/local/*/desc` |
13+
| Ignored directories | - |
14+
| Ignored directory markers | - |
15+
| Multi-module resolution | No |
1316
| Install-first support | No |
1417
| Native command hints | `syft for bomly-lite` |

docs/detectors/ecosystems/apk/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Package managers Bomly recognizes in the `apk` ecosystem:
1313
- Each package-manager page documents the exact commands Bomly runs (if any), the network behavior, and the lockfile or manifest formats supported.
1414
- Bomly tries detector chains from left to right. Later detectors in the chain are fallbacks Bomly uses when the preferred detector cannot produce graph data.
1515
- Install-first support means `--install-first` can run the package manager's normal install command before graph resolution. This downloads packages and modifies the filesystem; see [docs/DETECTORS.md](../../../DETECTORS.md#install-first).
16+
- Each package-manager page also lists the directories its detectors declare as ignored during recursive discovery (`--recursive`) and whether the chain resolves nested workspace/reactor modules from a root manifest (multi-module); see [docs/SCAN_TARGETS.md](../../../SCAN_TARGETS.md#recursive-discovery----recursive).
1617
- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

docs/detectors/ecosystems/apk/apk.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,8 @@ Bomly uses this chain when it finds `apk` evidence.
1010
| Ecosystem | `apk` |
1111
| Detector chain | `syft-detector` |
1212
| Evidence patterns | `lib/apk/db/installed` |
13+
| Ignored directories | - |
14+
| Ignored directory markers | - |
15+
| Multi-module resolution | No |
1316
| Install-first support | No |
1417
| Native command hints | `syft for bomly-lite` |

docs/detectors/ecosystems/conda/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Package managers Bomly recognizes in the `conda` ecosystem:
1313
- Each package-manager page documents the exact commands Bomly runs (if any), the network behavior, and the lockfile or manifest formats supported.
1414
- Bomly tries detector chains from left to right. Later detectors in the chain are fallbacks Bomly uses when the preferred detector cannot produce graph data.
1515
- Install-first support means `--install-first` can run the package manager's normal install command before graph resolution. This downloads packages and modifies the filesystem; see [docs/DETECTORS.md](../../../DETECTORS.md#install-first).
16+
- Each package-manager page also lists the directories its detectors declare as ignored during recursive discovery (`--recursive`) and whether the chain resolves nested workspace/reactor modules from a root manifest (multi-module); see [docs/SCAN_TARGETS.md](../../../SCAN_TARGETS.md#recursive-discovery----recursive).
1617
- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

docs/detectors/ecosystems/conda/conda.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,8 @@ Bomly uses this chain when it finds `conda` evidence.
1010
| Ecosystem | `conda` |
1111
| Detector chain | `syft-detector` |
1212
| Evidence patterns | `conda-meta/*.json` |
13+
| Ignored directories | - |
14+
| Ignored directory markers | - |
15+
| Multi-module resolution | No |
1316
| Install-first support | No |
1417
| Native command hints | `syft for bomly-lite` |

docs/detectors/ecosystems/cpp/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Package managers Bomly recognizes in the `cpp` ecosystem:
1313
- Each package-manager page documents the exact commands Bomly runs (if any), the network behavior, and the lockfile or manifest formats supported.
1414
- Bomly tries detector chains from left to right. Later detectors in the chain are fallbacks Bomly uses when the preferred detector cannot produce graph data.
1515
- Install-first support means `--install-first` can run the package manager's normal install command before graph resolution. This downloads packages and modifies the filesystem; see [docs/DETECTORS.md](../../../DETECTORS.md#install-first).
16+
- Each package-manager page also lists the directories its detectors declare as ignored during recursive discovery (`--recursive`) and whether the chain resolves nested workspace/reactor modules from a root manifest (multi-module); see [docs/SCAN_TARGETS.md](../../../SCAN_TARGETS.md#recursive-discovery----recursive).
1617
- Syft-backed entries provide broad compatibility, especially for containers and ecosystems without native Bomly graph resolution.

0 commit comments

Comments
 (0)