Module adapter 

Canonical Adapter trait — the cross-ecosystem SDLC interface.

Every ecosystem adapter (gen-cargo, gen-npm, gen-bundler, gen-pip, gen-gomod, gen-helm, …) implements one trait; substrate’s build wrappers and operator-facing CLIs both code to this trait. Adding a new ecosystem gives every downstream consumer

• every renderer the same verb surface for free.

Verbs

• lock — author’s manifest → freshly resolved lockfile
• build — lockfile + manifest → typed build-spec (hermetic; substrate calls this via IFD inside the nix sandbox)
• plan — diff “what would change if I bump ”
• confirm — verify spec invariants (hashes valid, no orphans, features unify, source/lockfile match)
• diff — human-readable diff between two states
• sbom — emit ecosystem-flavored SBOM (CycloneDX / SPDX)

Hermetic contract

The build verb MUST run without network access — it’s called from inside a nix sandbox via IFD by substrate’s mkBuildSpec. Implementations that read from Cargo.lock / package-lock.json / Gemfile.lock directly (without invoking the ecosystem’s native resolver) satisfy this. Implementations that need to resolve transitively can do so during lock, never build.

Structs

AdapterCtx

Context every adapter verb receives. Captures workspace root + optional target filter. Extending this struct is non-breaking because verbs take it by reference.

AdapterQuirkEntry

One entry in an Adapter’s quirks registry: a package name plus the ecosystem-specific typed-quirk payloads. The quirks field is serde_json::Value so each adapter can carry its own typed shape without polluting the trait with a generic parameter — the JSON envelope is what substrate’s dispatch layer reads anyway.

AdapterRegistration

Inventory entry registered by every adapter crate. gen-cli’s quirks / adapters / future cross-ecosystem verbs iterate this distributed slice to discover every adapter at link time — no hard-coded match arms, no per-ecosystem edits to gen-cli when a new adapter lands.

BuildSpec

Output of a build invocation. The JSON shape is ecosystem-specific — Cargo.build-spec.json / package-lock.spec.json / etc. — but every adapter wraps it in this typed envelope so substrate can read uniformly.

ConfirmReport

Result of confirm. Each invariant is named so failures point at the exact rule that broke; operators get actionable output instead of a stack trace.

DepChange

DepEdge

DependencyBump

One dep that changed version during a lock invocation.

DiffReport

Diff output for plan / diff. Three buckets: added, removed, version-changed. Consumers (PR comment renderer, CI gate, …) pick what to surface.

DispatcherVariant

One variant of a typed Adapter quirk enum, surfaced via Adapter::dispatcher_reflection. Mirrors TypedDispatcher’s per-variant reflection without forcing the trait to carry a generic Quirk associated type.

InvariantBreak

LockOutcome

Outcome of a lock invocation.

Plan

Result of plan. The diff describes the resulting state minus the current state; warnings flag anything risky (yanked, MSRV bump, semver-major, license change, …).

PlanIntent

Operator-supplied intent for gen plan.

PlanWarning

One warning emitted during planning.

Sbom

Generated SBOM. Format-flavored JSON; consumers route by format.

Enums

AdapterError

Adapter-level errors. Variants stay narrow so callers can pattern-match on recoverable cases.

DiffRef

Reference for diff — what to compare current state against.

PlanWarningSeverity

SbomFormat

SBOM output format.

Traits

Adapter

The canonical SDLC trait. Each ecosystem adapter implements one.

Functions

adapter_by_name

Get one adapter by name, freshly constructed. Returns None if no adapter registered under that name.

registered_adapter_names

Every registered adapter’s name. Used for gen adapters listing

registered_adapters

Iterate every adapter the binary was linked against. Returns freshly-constructed instances so callers can hold them independently. Per-call O(N) — N = number of linked adapters, typically small (3-20).

Type Aliases

AdapterResult

Result alias for adapter operations.