Expand dependency source classification (#352)

* Expand dependency source classification

Classify registry, Git, URL, file, project, and workspace origins from explicit Cargo, Bundler, pub, SwiftPM, and Python detector evidence. Preserve available source revisions, keep unknown evidence unset, and document the supported detector scope and safe exclusions.

* Address dependency source review feedback

Keep Swift source-control packages eligible for canonical SwiftURL matching, align Cargo lock-only workspace classification with metadata resolution, parse uv revisions from real Git URLs, and avoid empty Bundler metadata allocations. Add focused regression coverage and clarify matcher eligibility documentation.

Author: bomly-guy

dev-docs/ARCHITECTURE.md

@@ -385,6 +385,21 @@ Workspace/reactor detectors (npm and pnpm lockfile, cargo, maven) emit one `Grap
 
 **First-party packages are inventory, not enrichment targets** (`sdk.NodeIsEnrichable`). Application-typed nodes — workspace members, reactor modules, the project's own package — are absent from public advisory/registry sources, so querying OSV / deps.dev / scorecard / grype for them wastes lookups and risks coincidental name matches (a workspace member named like a real npm package would adopt its advisories). The predicate mirrors `NodeIsDiffable` and gates the two selection chokepoints (`matchers.RegistryPackagesForGraph`, the OSV matcher's graph iteration) plus external grype's result mapping. External grype's SBOM *input* is deliberately not filtered: `sbom.FromDepGraph` is shared with user-facing SBOM generation, where first-party components must remain visible — so first-party matches are dropped when grype results map back into the registry. First-party entries stay in the `packages` collection and SBOMs, just unenriched; external plugin matchers (ClearlyDefined, EOL) are expected to adopt the same predicate.
 
+**Dependency source classification belongs to detectors.** Source is an
+occurrence fact, so the detector that reads the manifest, lockfile, or build
+tool output owns it. The engine and package auditor consume the canonical
+`sdk.Dependency.Source` value but never infer one from an ecosystem, package
+name, PURL, or repository metadata. Detectors classify only explicit evidence:
+for example Cargo `registry+` and `git+` sources, Bundler `GEM`/`GIT`/`PATH`
+sections, pub lock sources, SwiftPM pin kinds, Python direct-URL metadata, and
+Python lock source tables. When a format does not retain the selected origin,
+the source stays unknown. This trades some source-change coverage for avoiding
+false provenance claims and keeps external protocol-v1 detectors compatible.
+Source and matcher eligibility are related but not identical: SwiftPM remote
+source control is classified as Git, while remaining eligible because the
+repository URL is the canonical SwiftURL identity used for vulnerability
+matching.
+
 ### Decision: Bun text lockfiles are native; binary lockfiles degrade explicitly
 
 `bun-detector` parses JSONC `bun.lock` versions 0 and 1 directly in Go. The parser removes comments and trailing commas with a string-aware state machine, inventories package tuples before constructing edges, models workspace roots as application nodes, and runs the shared Node relationship finalizer before per-workspace graph partitioning. Bun workspace entries therefore use the same multi-entry `sdk.GraphContainer` contract described above. The lockfile path never invokes or installs Bun, so committed text lockfiles remain deterministic and offline.

dev-docs/MODELS.md

@@ -128,6 +128,14 @@ Key helpers:
 - `sdk.RelationshipForPath(path)` — preserve an explicit relationship or derive direct/transitive from a root-to-target path.
 - `dep.RegistryMatchEligible()` — classify whether this occurrence may be sent to external registry enrichment.
 
+`Dependency.Source` is occurrence evidence, not a guess based on package name
+or ecosystem. A detector sets it only when the manifest, lockfile, or build
+tool output proves the origin. Cargo, Bundler, the JavaScript package managers,
+pub, SwiftPM, and the pip, Pipenv, Poetry, and uv Python paths currently expose
+that evidence. Formats that do not retain the selected feed or source leave the
+field empty. An empty source remains eligible for matching for protocol-v1
+compatibility, but it cannot create a source-change finding in a diff.
+
 An `unknown` relationship means that the package was present in the owning
 manifest but its parent could not be recovered. The component root is attached
 beneath the manifest/application root so it continues through matching,
@@ -137,7 +145,7 @@ for protocol-v1 plugins and is derived from graph structure by consumers.
 
 Dependencies **do not** carry `Licenses`, `Vulnerabilities`, or `Scorecard` fields. Detection-time licenses ride along in metadata; matching-stage data lives on the registry package.
 
-Registry matching eligibility is occurrence-based. Ordinary registry releases are eligible even when their `ResolvedURL` points at a custom registry or mirror. First-party/manifest nodes and occurrences sourced from project, workspace, link/file, Git, or arbitrary URL references are ineligible but remain in the complete graph and package registry for analysis, auditing, diff, SBOM, and output. Application type alone is not an ownership signal: an application artifact imported from an SBOM remains eligible unless it is marked first-party or has a non-registry source. An omitted source remains eligible for protocol-v1 and legacy detector compatibility. Before any built-in or external matcher runs, the engine passes it a cloned graph containing only eligible occurrences and eligible-to-eligible edges; the original graph and full registry continue to later stages unchanged.
+Registry matching eligibility is occurrence-based. Ordinary registry releases are eligible even when their `ResolvedURL` points at a custom registry or mirror. First-party/manifest nodes and occurrences sourced from project, workspace, link/file, Git, or arbitrary URL references are normally ineligible but remain in the complete graph and package registry for analysis, auditing, diff, SBOM, and output. Swift source-control packages are the exception: their repository URL is the canonical SwiftURL package identity, so Git-sourced Swift packages remain eligible for vulnerability matching. Application type alone is not an ownership signal: an application artifact imported from an SBOM remains eligible unless it is marked first-party or has a non-registry source. An omitted source remains eligible for protocol-v1 and legacy detector compatibility. Before any built-in or external matcher runs, the engine passes it a cloned graph containing only eligible occurrences and eligible-to-eligible edges; the original graph and full registry continue to later stages unchanged.
 
 ## `sdk.Package` — registry artifact (matching)
 

docs/auditors/package.md

@@ -84,7 +84,7 @@ still downgrades a configured failure.
 ## Limitations
 
 - **Names, not behavior.** This auditor cannot tell whether a package is malicious — only whether its name is denied or resembles a protected one. Pair it with the vulnerability auditor for content risk.
-- **Source-change checks currently cover JavaScript package managers.** npm, pnpm, Yarn, and Bun detectors report the source details needed by this check. Other detectors do not yet provide enough source data, so this policy cannot report their source changes.
+- **Source-change checks need detector evidence.** Cargo, Bundler, npm, pnpm, Yarn, Bun, pub, SwiftPM, and the pip, Pipenv, Poetry, and uv Python paths report source details when their lockfile or tool output proves the origin. Other detectors leave the source unknown when their input cannot distinguish a registry package from another origin.
 - **Only Git and URL moves are review signals.** Moves to project, workspace, or file sources remain informational, even when registry matching eligibility changes.
 - **Source-change policy is diff-only.** `--fail-on source-change` is accepted by other audited commands but cannot match because they do not produce dependency detail transitions.
 - **Source changes need context.** Git and URL sources can be intentional. The warning asks a reviewer to confirm the new origin and pinned reference.

docs/detectors/ecosystems/dart/pub.md

@@ -16,3 +16,8 @@ Bomly uses this chain when it finds `pub` evidence.
 | Install-first support | No |
 | Remediation hints | None |
 | Native command hints | `dart`, `syft for bomly-lite` |
+
+## Source details
+
+Bomly reads hosted, Git, and path sources from `pubspec.lock` or native pub
+output. An unrecognized source type stays unknown.

docs/detectors/ecosystems/python/pip.md

@@ -102,6 +102,12 @@ pip-compile --constraint constraints.txt requirements.in
 
 Re-scan.
 
+## Source details
+
+Pinned packages in `requirements.lock` are registry packages. On the inspection
+path, Bomly uses pip's `direct_url` record to identify Git, URL, and local-file
+installs. Missing or malformed source data stays unknown.
+
 ## Reachability (experimental)
 
 > **Experimental.** Reachability is opt-in via `--analyze`. The feature is stable in shape but may evolve; ecosystem coverage is expanding.

docs/detectors/ecosystems/python/pipenv.md

@@ -66,6 +66,11 @@ bomly scan --install-first --detectors pipenv-detector \
   --install-arg --dev --install-arg --deploy
 ```
 
+## Source details
+
+Bomly reads registry, Git, URL, and local-file sources from `Pipfile.lock`.
+When Pipenv uses pip inspection, Bomly uses pip's `direct_url` record instead.
+
 ## Reachability (experimental)
 
 > **Experimental.** Reachability is opt-in via `--analyze`. The feature is stable in shape but may evolve; ecosystem coverage is expanding.

docs/detectors/ecosystems/python/poetry.md

@@ -87,6 +87,11 @@ urllib3 = ">=2.2.2"
 
 Re-lock and re-scan.
 
+## Source details
+
+Bomly reads registry, Git, URL, and local-directory sources from each
+`poetry.lock` package source table. An unrecognized source type stays unknown.
+
 ## Reachability (experimental)
 
 > **Experimental.** Reachability is opt-in via `--analyze`. The feature is stable in shape but may evolve; ecosystem coverage is expanding.

docs/detectors/ecosystems/python/uv.md

@@ -92,6 +92,11 @@ constraint-dependencies = ["urllib3>=2.2.2"]
 
 Re-lock and re-scan.
 
+## Source details
+
+Bomly reads registry, Git, URL, path, and editable sources from each `uv.lock`
+package source table. An entry without source evidence stays unknown.
+
 ## Reachability (experimental)
 
 > **Experimental.** Reachability is opt-in via `--analyze`. The feature is stable in shape but may evolve; ecosystem coverage is expanding.

docs/detectors/ecosystems/ruby/bundler.md

@@ -79,6 +79,12 @@ gem "nokogiri", ">= 1.16.5"
 
 `bundle lock --update nokogiri`. Re-scan.
 
+## Source details
+
+Bomly maps the `GEM`, `GIT`, and `PATH` sections in `Gemfile.lock` to registry,
+Git, and local-file sources. These details let `bomly diff` review a gem that
+moves to Git.
+
 ## Reachability
 
 > **Not yet supported.** Bomly has no Ruby reachability analyzer today. `--analyze` produces `not_applicable` for Ruby packages.

docs/detectors/ecosystems/rust/cargo.md

@@ -85,6 +85,11 @@ openssl = { git = "https://github.com/sfackler/rust-openssl", tag = "openssl-v0.
 
 `cargo update`. Re-scan.
 
+## Source details
+
+Bomly reads registry, Git, path, and workspace sources from Cargo metadata or
+`Cargo.lock`. These details let `bomly diff` review a package that moves to Git.
+
 ## Reachability
 
 > **Not yet supported.** Bomly has no Rust reachability analyzer today. `--analyze` produces `not_applicable` for crates.