feat: submodule SBOM support — discovery annotation + attach-or-backfill

[vpetersson]

Summary

End-to-end git-submodule support, wizard through runtime. (Supersedes #295 — the two halves depend on each other, so they ship as one PR. Backend lookup filters landed in sbomify/sbomify#1176 and are verified on stage.)

Wizard / discovery side

• Discovery detects lockfiles living in another repository: paths declared in .gitmodules (submodules) or directories with their own .git (vendored clones). DiscoveredLockfile gains nested_repo / nested_repo_kind.
• The discover screen annotates those rows (e.g. extern/lib/Cargo.lock (rust) (submodule: extern/lib)) and leaves them deselected by default, with a note explaining why — they belong to another repo and are better tracked from there.
• Never attested: submodule/vendored matrix rows get attest: false with an explicit "Deliberately NOT signed" annotation in the emitted YAML, and the attest step is gated with if: ${{ matrix.attest }}. An attestation from the parent repo's workflow would carry the wrong Sigstore identity for code owned by another repository.

Runtime side (SUBMODULE_PATH mode)

When a matrix row carries submodule_path, the action:

1. Resolves the pin to a version — gitlink SHA from the parent tree (git ls-tree, no submodule init needed), then an exact version-shaped tag on that commit via git ls-remote --tags against the .gitmodules URL (local-tag fallback, vendored-clone support). No tag → 7-char short SHA, matching trunk-strategy COMPONENT_VERSIONs. Exact match only — no git describe nearest-tag guessing.
2. Attach: if the component already has an SBOM at that (version, format) — via GET /components/{id}/sboms?version=&format=, re-checked client-side for older backends — generation and upload are skipped and the existing SBOM is tagged into the PRODUCT_RELEASE(s).
3. Backfill: otherwise the normal pipeline runs with COMPONENT_VERSION overridden to the pin-derived version, so the upload lands where the next release's lookup finds it. DUPLICATE_ARTIFACT races (two parents backfilling the same pin) recover by re-looking up the winner.

Per-format independence falls out of the matrix design: attach CycloneDX and backfill SPDX in the same release with no special casing.

Changes

• sbomify_api.py: list_component_sboms / find_component_sbom
• submodule.py (new): pin + version resolution; remote calls run with the parent repo as cwd so actions/checkout credentials apply to private submodules
• cli/main.py: submodule preflight before Step 1; Step 6 + finalization extracted into shared helpers; duplicate-upload recovery; SUBMODULE_PATH env/CLI option + validation (requires LOCK_FILE + sbomify destination; empty string = disabled)
• Wizard: discovery detection, discover-screen UX, emitter plumbing (submodule_path rows, SUBMODULE_PATH env, submodules: recursive checkout, attest gating). Non-submodule workflows emit byte-identical to before
• README: SUBMODULE_PATH documented; action.yml unchanged (Docker action, step env: flows through)

Verification

• Full suite: 2469 passed; ruff lint + format clean. New tests: real-git submodule fixtures (tag pin, SHA pin, uninitialized clone, vendored clone), API lookup incl. legacy-backend re-check, config validation, emitter shape, Textual discover-screen behavior.
• E2E against stage (stage.sbomify.com, with #1176 deployed): tag-pin backfill → attach; SHA-pin backfill → attach (idempotent re-tag); per-format miss (CDX present, SPDX absent) → SPDX backfill via syft in the Docker image built from this branch; raw server-side filter checks; releases with both formats coexisting.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds end-to-end support for lockfiles that live in git submodules or vendored repositories, spanning wizard discovery/UX and runtime “attach-or-backfill” behavior so the action can reuse an already-published SBOM for the submodule’s pinned version or generate/upload one when missing.

Changes:

• Wizard: detect nested repos (submodule/vendored), annotate those lockfiles, and default-deselect them; emit matrix/env plumbing for SUBMODULE_PATH plus attestation gating/opt-out.
• Runtime: introduce submodule pin → version resolution (tag-at-pin else short SHA), preflight SBOM lookup via API, attach existing SBOM when present, otherwise backfill; recover from duplicate-artifact races.
• API client: add component-SBOM listing + exact-match helper used by the attach path.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_wizard_textual.py	Asserts discover screen default-deselect + annotation/note for nested-repo lockfiles.
tests/test_wizard_emitter.py	Validates YAML emission for per-row attest, submodule plumbing, and checkout submodules settings.
tests/test_wizard_discovery.py	Covers .gitmodules parsing and vendored .git detection for nested-repo annotation.
tests/test_submodule.py	Exercises git pin resolution and submodule-mode pipeline behaviors.
tests/test_sbomify_api.py	Tests list_component_sboms and find_component_sbom behavior including legacy-backend recheck.
tests/test_config.py	Adds config validation expectations for SUBMODULE_PATH including empty-string disable behavior.
sbomify_action/submodule.py	New implementation for resolving pinned submodule state to a version string via tags/short SHA.
sbomify_action/sbomify_api.py	Adds component SBOM listing and exact-match finder.
sbomify_action/cli/wizard/state.py	Extends DiscoveredLockfile with nested_repo and nested_repo_kind.
sbomify_action/cli/wizard/screens/discover.py	Annotates nested-repo rows and defaults them to deselected; shows an explanatory note.
sbomify_action/cli/wizard/discovery.py	Implements .gitmodules + embedded .git detection and annotates discovered lockfiles.
sbomify_action/cli/wizard/ci_emitter.py	Emits submodule_path, SUBMODULE_PATH, recursive submodule checkout, and attest gating/annotations.
sbomify_action/cli/main.py	Adds SUBMODULE_PATH config/CLI option, preflight attach-or-backfill flow, and duplicate-upload recovery.
README.md	Documents SUBMODULE_PATH requirements and behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.