feat(output): version resolved-dependency SBOM purls and join vendored licenses

[mstykow]

Summary

• Completes transitive-dependency license coverage in the SBOM (issue SBOM: complete transitive-dependency license coverage #1320), fully static and no-network. Every resolved dependency carries its versioned purl (the join key for downstream enrichment) and, when its source/metadata is on disk, its license — as a single deduplicated component.
• The fix lives in the shared inventory (src/output/sbom.rs), so both CycloneDX and SPDX benefit, and SPDX now renders the versioned coordinate as a field. The native ScanCode-compatible JSON is untouched.

What changed

SbomInventory builds an owner-scoped version index and canonicalizes every dependency edge through it before promotion and graph-edge resolution:

1. Versioned purls. An unversioned requirement edge (pkg:npm/leftpad, from a manifest) is upgraded to its resolved coordinate (pkg:npm/leftpad@1.0.0) — from the edge's own resolved_package, or from a single unambiguous versioned sibling under the same owner. Identities with zero or multiple versioned candidates stay unversioned (honest-unknowns; Provenant does not guess which version a range resolved to).
2. Vendored license join / dedup. The canonicalized requirement dedups against the detected, licensed package for that purl (vendored case → one licensed, versioned component) or the versioned lockfile edge (source-absent → one versioned component, license carried from resolved_package when present, else unset). No more two-components-for-one-dependency.
3. SPDX purl/version rendering. Every SPDX package (subject and promoted dependency) with a purl/version now emits it: tag-value PackageVersion + ExternalRef: PACKAGE-MANAGER purl <purl>, RDF spdx:versionInfo + spdx:externalRef (referenceCategory packageManager, referenceType purl). SPDX previously carried neither.

Promotion and edge resolution share one resolver, so the graph stays closed (0 dangling), bom-ref/dependencies[].ref stay unique, and a dep owned by multiple packages remains a single component.

Correctness invariants (identity + version resolution)

The version-index identity and resolution are deliberately conservative — an edge only ever adopts a version that is genuinely its own resolution:

• Variant-preserving identity. The version-less identity strips only the version and is rebuilt canonically via PackageUrl, keeping type + namespace + name + qualifiers + subpath. Variants that differ only by a qualifier (arch, classifier, repository) or subpath are never conflated.
• Owner-scoped. The index is keyed by (owner, identity) from dependency edges only. An unversioned requirement under one owner never inherits a version from a sibling under a different owner (owners can resolve the same package to different versions).
• No ownerless pooling. Edges without a concrete for_package_uid neither contribute to nor consult the sibling index — an ownerless edge resolves only from its own resolved_package, else stays unversioned.
• Non-empty purls are never dropped. A non-empty purl that PackageUrl cannot parse is passed through unchanged as the component coordinate and graph ref (canonicalization is skipped for it), so a malformed-but-present dependency is never silently erased from the SBOM.

Before / after

Repro tree (package.json + package-lock.json + node_modules/leftpad/package.json with "license": "MIT"), scanned --license --package --strip-root:

• Before: two components — pkg:npm/leftpad@1.0.0 (detected, MIT) and pkg:npm/leftpad (resolved dep, unversioned, no license).
• After: one component — pkg:npm/leftpad@1.0.0 carrying MIT; edge myapp → pkg:npm/leftpad@1.0.0; 0 dangling, in both CycloneDX and SPDX.

Real examples (examples/sbom, regenerated). Components drop where an unversioned requirement coalesces onto its resolved/detected versioned sibling under the same owner; the modest deltas reflect the conservative rules above (ambiguous, cross-owner, and ownerless requirements are intentionally left as-is), graph still fully closed:

target	components (before → after)	note
ripgrep	114 → 107	workspace members that appeared as both a detected package and a resolved dep coalesce; multi-version deps (aho-corasick/bstr) correctly stay unversioned
flask	54 → 53	one requirement/resolved pair coalesced
tokio	51 → 51	versioned in place; workspace cross-member deps stay honestly unversioned
express	45 → 45	no committed lockfile, so no resolved versions exist — unchanged

Issues

• Closes: SBOM: complete transitive-dependency license coverage #1320

Scope and exclusions

• Included: owner-scoped, variant-preserving version-index + purl canonicalization in the shared inventory; SPDX tag-value + RDF purl/version rendering; ADR 0012 amendment; regenerated dependency goldens and the four examples/sbom documents.
• Explicit exclusions: no online/registry license lookup (out of scope by design — see SBOM: complete transitive-dependency license coverage #1320). Native ScanCode-compatible JSON is unchanged.

How to verify

• Build the leftpad repro above and scan --license --package --strip-root --cyclonedx - (and --spdx-tv -): one licensed, versioned component, myapp DEPENDS_ON leftpad@1.0.0, 0 dangling in both formats.

• Official-validator gate (blocking): every checked-in output-format fixture and all four examples/sbom/*/{sbom.cdx.json,sbom.spdx} pass cyclonedx-python-lib (CycloneDX 1.3 JSON schema + XSD) and pyspdxtools (SPDX-2.2, .tv→.spdx first); live-scan RDF/JSON/XML also validated via scripts/validate_output_format_fixtures.py --provenant-bin ….

  CycloneDX: ripgrep OK  express OK  flask OK  tokio OK   (+ dependency goldens OK)
  SPDX:      ripgrep OK  express OK  flask OK  tokio OK   (+ dependency + simple goldens OK)
  

• Regression unit tests in src/output/sbom.rs cover each invariant: qualifier/subpath non-conflation, cross-owner non-inheritance, ownerless non-pooling, and unparseable-purl retention.

ScanCode parity

• Unaffected. compare-outputs diffs the native ScanCode-compatible --json output; this change is confined to src/output/sbom.rs, which is imported only by the CycloneDX/SPDX renderers and never by the native writers, so the native packages[]/dependencies[] output is byte-identical (verified on the leftpad repro). (ScanCode is not installed in this environment; the conclusion follows structurally from the import graph plus the byte-identical native output.)

Expected-output fixture changes

• Files changed: testdata/output-formats/cyclonedx-dependencies-expected.{json,xml}, testdata/output-formats/spdx-dependencies-expected.tv (+ spdx-licensed/spdx-multi-package now carry PackageVersion/ExternalRef), and the four regenerated examples/sbom/* documents + READMEs.
• Why correct: the dependency sample now includes an unversioned manifest requirement plus the lockfile's versioned, licensed resolution of the same dependency; the correct SBOM is one licensed, versioned component rather than a bare purl plus a separate versioned one. The SPDX dependency test normalizes the build-specific Creator:/Created: lines like every other SPDX-tv golden (it previously used a raw assert_eq, coupling the fixture to the exact build version). All regenerated fixtures pass the official external validators.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Updates the shared SBOM inventory and SPDX serializers to preserve dependency context and emit resolved package coordinates.

• Scopes dependency-version evidence by package owner while preserving purl qualifiers, subpaths, and unparseable non-empty coordinates.
• Canonicalizes dependency promotion and graph-edge resolution through the same resolver.
• Adds package versions and purl external references to SPDX tag-value and RDF/XML output.
• Regenerates CycloneDX/SPDX fixtures, examples, and documentation for the revised inventory.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failures remain in the fixes associated with the previous review threads.

Important Files Changed

Filename	Overview
src/output/sbom.rs	Adds owner-scoped version evidence and consistent purl resolution for promoted components and dependency edges, including focused regressions for all previously reported cases.
src/output/spdx.rs	Emits package versions and purl external references in SPDX tag-value and RDF/XML output.
tests/output_format_golden.rs	Extends shared output fixtures to cover coalescing an unversioned requirement with its licensed, versioned resolution.
docs/adr/0012-sbom-resolved-dependency-components.md	Documents the owner-scoped resolution rules, identity preservation, malformed-purl handling, and SPDX output behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["Detected packages"] --> D["Shared SBOM inventory"]
  B["Declared dependency edges"] --> C["Owner-scoped purl resolver"]
  B2["Resolved dependency edges"] --> C
  C --> D
  D --> E["CycloneDX components and graph"]
  D --> F["SPDX packages and relationships"]
  F --> G["PackageVersion and purl ExternalRef"]

Loading

_{Reviews (4): Last reviewed commit: "fix(output): retain unparseable dependen..." | Re-trigger Greptile}