@intentius/chant 0.13.1 → 0.15.0

package/dist/components/verbs/license-policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * License policy over an SBOM's declared licenses (#626). The SBOM already
+ * enumerates every component and its license; this evaluates those against an
+ * allow/deny list (e.g. block a copyleft license in a proprietary product).
+ *
+ * **Report-only by default.** License posture is context-dependent — GPL is a
+ * problem for a proprietary binary but fine for a GPL project — so the gate
+ * (./vuln-gate.ts) does NOT block on license violations unless a project opts
+ * in (`failOnLicense: true`). Extraction reads both SPDX
+ * (`packages[].licenseConcluded`/`licenseDeclared`) and CycloneDX
+ * (`components[].licenses[]`) without a spec dependency.
+ */
+import type { SbomDocument } from "./sbom-generator.js";
+/** A package/component and the license the SBOM declares for it. */
+export interface PackageLicense {
+    package: string;
+    /** SPDX license expression/id as the SBOM reports it, or `"NOASSERTION"`/`""` when none is declared. */
+    license: string;
+}
+export interface LicensePolicy {
+    /** If set, ONLY these licenses are permitted — anything else is a violation. */
+    allow?: string[];
+    /** These licenses are violations (takes precedence; useful without an allowlist). */
+    deny?: string[];
+}
+/** One package whose license violates the policy. */
+export interface LicenseViolation {
+    package: string;
+    license: string;
+    /** Which rule it broke. */
+    reason: "denied" | "not-allowed";
+}
+/** Extract each package's declared license from an SBOM, dispatching on media type (SPDX vs CycloneDX). Never throws on shape — a package with no license reads as `"NOASSERTION"`. */
+export declare function extractLicenses(sbom: SbomDocument): PackageLicense[];
+/**
+ * Split an SPDX license expression into its component license atoms, so a
+ * deny/allow list matches a license hidden inside an expression like
+ * `"GPL-3.0 OR MIT"` or `"(Apache-2.0 AND MIT)"` — an exact-string compare on
+ * the whole expression would miss `GPL-3.0` and let it through. Conservative:
+ * we only need the *set* of licenses referenced, so we split on `OR`/`AND`,
+ * drop parentheses, and strip any `WITH <exception>` suffix. A single license
+ * id returns itself unchanged.
+ */
+export declare function licenseAtoms(expr: string): string[];
+/**
+ * Evaluate an SBOM's licenses against `policy`. A package violates if ANY atom
+ * of its (possibly compound) SPDX license expression is in `deny`, or (when
+ * `allow` is set) any atom is not in `allow`. This is conservative on `OR`
+ * expressions — `"GPL-3.0 OR MIT"` counts as a `GPL-3.0` deny hit even though a
+ * consumer could choose MIT — because a policy gate should surface the presence
+ * of a denied license, not silently rely on the consumer picking the permissive
+ * branch. Packages with no declared license (`NOASSERTION`/empty) are not
+ * flagged — an undeclared license is not asserted to be denied.
+ */
+export declare function evaluateLicensePolicy(sbom: SbomDocument, policy: LicensePolicy): LicenseViolation[];
+//# sourceMappingURL=license-policy.d.ts.map

package/dist/components/verbs/license-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"license-policy.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/license-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,MAAM,EAAE,QAAQ,GAAG,aAAa,CAAC;CAClC;AAcD,uLAAuL;AACvL,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,EAAE,CAapE;AAUD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,gBAAgB,EAAE,CAcnG"}

package/dist/components/verbs/lockfile-sbom-generator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Hermetic lockfile/manifest-derived `SbomGenerator` (#613, epic #551 closes
+ * the "HERMETIC-generator half of #610" per #613's scope note). Pure
+ * TypeScript: reads a declared-dependency manifest already on disk (Node
+ * `package-lock.json`, JVM `pom.xml`) and emits a real SPDX/CycloneDX
+ * document via ./bom-writer.ts. No `syft`, no `docker buildx`, no
+ * `cyclonedx-maven`, no network — every package in the resulting BOM comes
+ * from parsing bytes chant already has locally.
+ *
+ * **What this backend is, and isn't.** A lockfile enumerates every declared
+ * (transitive-resolved) dependency at the versions actually installed, so
+ * the resulting SBOM is complete for **declared** dependencies — accurate
+ * package identity and version for everything npm/Maven resolved. It is
+ * **not** a container-layer scan: it cannot see OS packages baked into a base
+ * image, binaries copied in by a Dockerfile `COPY`/`RUN`, or anything not
+ * expressed as a lockfile entry. That deeper, image-layer-aware scan is
+ * `syft`'s job (or BuildKit's native `--sbom` attestation) and stays exactly
+ * where #610 already scoped it: the optional *deep* path, layered on top of
+ * (never replacing) this hermetic baseline. See
+ * docs/components/build-archive.mdx's SBOM section, updated alongside this
+ * change, for the customer-facing version of this distinction.
+ *
+ * Registered as `forDir`/`forZip`/`forJar` implementations (the artifact
+ * shapes a source-tree or packaged-but-uninspected artifact naturally maps
+ * to); `forImage` still throws `SbomGeneratorNotImplementedError` — an image
+ * SBOM needs either BuildKit's attestation or a container-layer scan, neither
+ * of which a lockfile read can substitute for, so this backend deliberately
+ * does not claim to cover it (mirrors how ./sbom-generator.ts's own
+ * `notImplementedSbomGenerator` prefers a loud, specific failure over a
+ * silently wrong answer).
+ */
+import { type BomPackage } from "./bom-writer.js";
+import type { SbomGenerator } from "./sbom-generator.js";
+/**
+ * Parse a `package-lock.json` (v1, v2, or v3) into a flat `BomPackage[]`.
+ * Prefers the v2/v3 `packages` map (flat, one entry per resolved install
+ * location) since that's what `npm` >= 7 writes; falls back to the v1
+ * `dependencies` tree for older lockfiles. De-duplicates by `name@version`
+ * so a package appearing at multiple install paths (npm's dedup/hoisting)
+ * contributes one BOM entry, matching how a real scanner reports installed
+ * packages rather than filesystem paths.
+ */
+export declare function parseNpmPackageLock(content: string): BomPackage[];
+/**
+ * Parse the `<dependencies>` block of a `pom.xml` into a flat `BomPackage[]`.
+ * Deliberately minimal (#613 calls this out as "add JVM pom.xml if cheap"):
+ * a small tag-scoped regex walk over `<dependency>...</dependency>` blocks
+ * extracting `groupId`/`artifactId`/`version`, no XML DOM dependency, no
+ * property (`${...}`) resolution, no transitive resolution (Maven's own
+ * dependency-mediation graph isn't reproducible without invoking `mvn`,
+ * which would break the hermetic requirement). This is deliberately narrower
+ * than the npm parser above: it covers the common case (a flat, literal
+ * `<dependencies>` list) and documents its own limits rather than silently
+ * mis-resolving a `${property}` version or a `<dependencyManagement>`
+ * inheritance chain.
+ */
+export declare function parsePomXml(content: string): BomPackage[];
+export interface LockfileSbomGeneratorOptions {
+    /** Where generated SBOM documents are written on disk, as a sibling of the scanned path (see `sbomOutputPath`). Default: alongside the scanned manifest, named `sbom.<format>.json`. */
+    outDir?: string;
+    /** Clock override for deterministic tests. */
+    now?: () => Date;
+}
+/** Default on-disk path for a generated SBOM: `<dir>/sbom.<format>.json`, matching #613's `sbom.<format>.json` naming convention. */
+export declare function sbomOutputPath(dir: string, format: string): string;
+/**
+ * Build a hermetic `SbomGenerator` backed by lockfile parsing. `forDir` scans
+ * `input.path` for a known manifest (`package-lock.json`, then `pom.xml`),
+ * parses it into a `BomPackage[]`, and writes both the SBOM document (via
+ * ./bom-writer.ts) to disk and returns it as an `SbomDocument`. `forZip`/
+ * `forJar` reuse the same scan against the artifact's source directory
+ * (the directory the archive was built from is the natural place a lockfile
+ * lives — the packaged bytes themselves are not re-inspected, matching this
+ * backend's "declared deps, not a binary scan" scope). `forImage` is not
+ * implemented here: an image's dependency surface includes its base layers,
+ * which no lockfile enumerates — see this module's doc comment.
+ */
+export declare function createLockfileSbomGenerator(options?: LockfileSbomGeneratorOptions): SbomGenerator;
+/** Process-wide hermetic lockfile-backed `SbomGenerator`, ready to inject wherever ./sbom-generator.ts's `notImplementedSbomGenerator` default previously required an explicit real backend. */
+export declare const lockfileSbomGenerator: SbomGenerator;
+//# sourceMappingURL=lockfile-sbom-generator.d.ts.map

package/dist/components/verbs/lockfile-sbom-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile-sbom-generator.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/lockfile-sbom-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAMV,aAAa,EACd,MAAM,kBAAkB,CAAC;AAe1B;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAkCjE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CA8BzD;AAID,MAAM,WAAW,4BAA4B;IAC3C,wLAAwL;IACxL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAgBD,qIAAqI;AACrI,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,aAAa,CA0CrG;AAED,gMAAgM;AAChM,eAAO,MAAM,qBAAqB,EAAE,aAA6C,CAAC"}

package/dist/components/verbs/process-runner.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Injectable external-process boundary for the #610 deep-scan/attach
+ * backends (`ToolSbomGenerator` in ./tool-sbom-generator.ts,
+ * `OrasReferrerLookup` in ../../lifecycle/oras-referrer-lookup.ts, and
+ * `publish-image`'s referrer-attach step in ./publish.ts). Mirrors
+ * ./cloud-executor.ts's `CloudExecutor` pattern exactly: production code gets
+ * a `RealProcessRunner` that shells out via `node:child_process`, tests get a
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) that records calls
+ * and returns canned output — no live `syft`/`buildx`/`cyclonedx-maven`/
+ * `cdxgen`/`oras`, ever, in a test run.
+ *
+ * Kept deliberately narrower than `CloudExecutor`: every one of #610's real
+ * backends reduces to "run this external CLI, capture stdout, tell me if the
+ * tool exists" — a single `ProcessRunner` interface (`run` + `available`)
+ * covers `syft`, `docker buildx`, `cyclonedx-maven`, `cdxgen`, and `oras`
+ * alike, rather than one bespoke client per tool the way `CloudExecutor`
+ * models AWS's genuinely distinct service APIs (CloudFormation, ECS,
+ * CodeDeploy, ...).
+ */
+/** One external command invocation's result. */
+export interface ProcessResult {
+    stdout: string;
+    stderr: string;
+}
+export interface RunOptions {
+    /** Working directory the command runs in. Defaults to the current process cwd. */
+    cwd?: string;
+    /** Max buffer size for stdout/stderr, matching ./cloud-executor.ts's `run`'s 64MB allowance (SBOM/BOM documents can be large). */
+    maxBuffer?: number;
+}
+/**
+ * Injectable boundary for shelling out to a deep-scan/attach CLI tool and for
+ * checking whether one is installed. A real implementation runs the command
+ * via `node:child_process`; every method here is injected so tests substitute
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) and never invoke a
+ * real tool.
+ */
+export interface ProcessRunner {
+    /** Run a shell command, returning its stdout/stderr. Rejects (with the tool's own stderr in the error) on a non-zero exit. */
+    run(command: string, options?: RunOptions): Promise<ProcessResult>;
+    /** True if `tool` (a CLI binary name, e.g. "syft", "oras") resolves on `PATH`. Never throws — a missing tool is a normal, expected outcome the caller checks before attempting to `run` it. */
+    available(tool: string): Promise<boolean>;
+}
+/** Shell-quote a single argument for POSIX shells (wrap in single quotes, escaping embedded ones) — same convention as ./cloud-executor.ts's `q`. */
+export declare function q(value: string): string;
+/** Build a `ProcessRunner` that shells out for real via `node:child_process`. Never used in tests. */
+export declare function realProcessExecutor(): ProcessRunner;
+/** The default `ProcessRunner` each real #610 backend falls back to when none is supplied. */
+export declare function defaultProcessRunner(): ProcessRunner;
+/**
+ * Thrown when a #610 real backend needs a CLI tool that `ProcessRunner.available`
+ * reports as absent — the "graceful, actionable error if the tool is absent"
+ * #610 asks for, distinct from a generic `Error` so callers (and tests) can
+ * assert on it specifically, mirroring `SbomGeneratorNotImplementedError`'s
+ * role in ./sbom-generator.ts.
+ */
+export declare class ToolNotAvailableError extends Error {
+    readonly tool: string;
+    readonly purpose: string;
+    constructor(tool: string, purpose: string);
+}
+/** Throw `ToolNotAvailableError` unless `tool` is available, per `runner.available`. Shared guard every #610 real backend calls before shelling out. */
+export declare function requireTool(runner: ProcessRunner, tool: string, purpose: string): Promise<void>;
+//# sourceMappingURL=process-runner.d.ts.map

package/dist/components/verbs/process-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-runner.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/process-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kIAAkI;IAClI,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,8HAA8H;IAC9H,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnE,+LAA+L;IAC/L,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3C;AAED,qJAAqJ;AACrJ,wBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvC;AAqBD,sGAAsG;AACtG,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD;AAKD,8FAA8F;AAC9F,wBAAgB,oBAAoB,IAAI,aAAa,CAGpD;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;gBADf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM;CAKlC;AAED,wJAAwJ;AACxJ,wBAAsB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrG"}

package/dist/components/verbs/reproducibility.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Per-artifact reproducibility + provenance record (#614, epic #551 follow-up
+ * to #613's BOM-doc model). Attaches to a `BuildArchiveEntry`
+ * (./build-archive.ts) alongside the BOM entries #613 already added, so every
+ * artifact in a build archive carries not just "what's in it" (the BOM) but
+ * also "can this be reproduced, and from what source."
+ *
+ * **Honesty over convenience.** A single blanket "reproducible: true/false"
+ * bit on a *component* would misrepresent a component that builds more than
+ * one artifact type — a synthesized IaC template and a container image are
+ * not equally reproducible, and collapsing them into one flag would either
+ * overstate the image's reproducibility or understate the template's. This
+ * module therefore records `basis` **per artifact entry**, never per
+ * component:
+ *
+ *  - `"deterministic-synthesis"` — chant's own synthesis produced this
+ *    artifact from declarative input (a `template`-kind entry, see
+ *    ../../build.ts). Re-running `chant build` against the same source
+ *    reproduces byte-identical output — the same content-addressing property
+ *    ./build-archive.ts's `contentDigest`/`manifestDigest` already rely on.
+ *    Verification is exactly "re-synth and compare digests," expressed here
+ *    as `verifyBy: "re-synth"`.
+ *  - `"best-effort"` — an `image`/`asset` entry built by an external tool
+ *    (`docker build`, a JVM/zip packager). Nothing here observes whether the
+ *    underlying build was actually bit-for-bit reproducible (timestamps,
+ *    build-arg ordering, and base-image drift are common, unglamorous causes
+ *    of non-determinism that chant does not control) — `"best-effort"` is
+ *    the honest default absent a real reproducible-build attestation. A
+ *    future SLSA/reproducible-build-flagged backend can upgrade this to a
+ *    stronger basis; nothing here forecloses that, it just refuses to claim
+ *    it today.
+ *
+ * **Provenance** is the companion source -> output link: which source
+ * ref/commit produced this artifact's digest. Recorded per artifact for the
+ * same reason `basis` is — two artifacts from one component build may trace
+ * to different source trees (e.g. an image built from `services/search/` vs
+ * a template synthesized from `infra/search.component.ts`), so the link
+ * belongs on the entry, not hoisted to the component.
+ */
+/**
+ * How an artifact's reproducibility is established. Deliberately two values,
+ * not a spectrum: chant either produced the artifact itself via deterministic
+ * synthesis (verifiable by re-running `chant build`), or it didn't (an
+ * external build tool produced it, and no attestation proves determinism).
+ * Adding a third value (e.g. a real SLSA-attested "reproducible-build") is a
+ * later, additive change — widening `basis` never requires touching every
+ * existing artifact's recorded value, since `"best-effort"` remains true of
+ * anything not upgraded.
+ */
+export type ReproducibilityBasis = "deterministic-synthesis" | "best-effort";
+/** How a claimed `basis` can actually be checked. Optional — a `"best-effort"` entry commonly has no verification path at all. */
+export type VerificationMethod = "re-synth";
+/** The reproducibility record for one build-archive entry (#614). */
+export interface ArtifactReproducibility {
+    /** Honest, per-artifact basis for the claim — never inferred from a sibling artifact's basis. */
+    basis: ReproducibilityBasis;
+    /** How to verify the claim, when there is one. `"re-synth"` applies only to `"deterministic-synthesis"` entries — re-run `chant build` and compare the resulting digest. */
+    verifyBy?: VerificationMethod;
+}
+/**
+ * Default reproducibility basis for a given `BuildArchiveEntryKind`, absent
+ * an explicit override. A `template` entry is chant's own synthesized IaC
+ * output — deterministic by construction (the same synthesis run over the
+ * same source produces the same bytes, per ./build-archive.ts's module doc).
+ * `image`/`asset` entries are produced by an external build tool chant only
+ * orchestrates (`docker build`, a JVM/zip packager) — best-effort absent a
+ * real reproducible-build attestation. `sbom` entries describe another
+ * artifact rather than being one themselves, so they carry no
+ * reproducibility claim of their own (`undefined`) — see
+ * `../build-archive.ts`'s `BuildArchiveEntry.reproducibility` doc.
+ */
+export declare function defaultReproducibility(kind: "image" | "template" | "asset" | "sbom"): ArtifactReproducibility | undefined;
+/** One source -> output link: the source ref/commit that produced a given artifact digest. */
+export interface ProvenanceLink {
+    /** Source ref/commit the artifact was built or synthesized from (e.g. a git sha, or `"<sha>:<path>"` when a monorepo subpath matters). */
+    sourceRef: string;
+    /** The artifact digest this provenance describes — the same `BuildArchiveEntry.digest` it is attached to, repeated here so a `ProvenanceLink` remains meaningful if ever extracted/serialized apart from its entry. */
+    artifactDigest: string;
+}
+//# sourceMappingURL=reproducibility.d.ts.map

package/dist/components/verbs/reproducibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reproducibility.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/reproducibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,aAAa,CAAC;AAE7E,kIAAkI;AAClI,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE5C,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,iGAAiG;IACjG,KAAK,EAAE,oBAAoB,CAAC;IAC5B,4KAA4K;IAC5K,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAC5C,uBAAuB,GAAG,SAAS,CAUrC;AAID,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,0IAA0I;IAC1I,SAAS,EAAE,MAAM,CAAC;IAClB,uNAAuN;IACvN,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/components/verbs/sbom-generator.d.ts

@@ -0,0 +1,157 @@
+/**
+ * SBOM document type + the injectable, artifact-type-keyed `SbomGenerator`
+ * boundary (#606, epic #551 "Build & deploy observability" follow-up to
+ * #564/#568). Mirrors ./cloud-executor.ts's `CloudExecutor` pattern: a real
+ * backend may shell out to `syft`/`docker buildx --sbom`/`cyclonedx-maven`,
+ * but no test and no default import ever does — every backend here is
+ * injected, and tests construct a `MockSbomGenerator`
+ * (./__tests__/mock-sbom-generator.ts) instead.
+ *
+ * **Format-agnostic by construction.** An SBOM is stored as an opaque typed
+ * doc: `{ format, mediaType, bytes }`. Nothing downstream (the build-archive
+ * manifest, the build ledger, `chant components status`) branches on
+ * `format` — every consumer keys off `mediaType`, the same convention
+ * `BuildArchiveEntry.mediaType` already uses for image/template/asset
+ * entries (./build-archive.ts). SPDX (`application/spdx+json`) and
+ * CycloneDX (`application/vnd.cyclonedx+json`) are both first-class; neither
+ * is hardcoded as *the* format anywhere in this module or its consumers.
+ *
+ * **Default format:** SPDX, matching the epic's refinement from the
+ * devops-cloud.news SBOM article — BuildKit natively emits SPDX attestations
+ * for images, so the image/BuildKit backend defaults to SPDX; the `syft`
+ * backend can emit either and defaults to SPDX here too, for one predictable
+ * default across artifact types. Override via `chant.config.ts`'s
+ * `sbom.format` (see ../../config.ts) and/or a component's own `build.sbom`
+ * (see ../component.ts's `BuildSpec`). Documented in
+ * docs/components/build-archive.mdx.
+ *
+ * **Artifact-type-keyed generation.** "Generate an SBOM" has a different
+ * real implementation per artifact type — an image asks BuildKit or scans
+ * the built image with `syft`; a JAR is scanned with `syft` or
+ * `cyclonedx-maven`; a zip/Lambda package is scanned with `syft`; a bare
+ * source directory is scanned with `syft`/`cdxgen`. `SbomGenerator` is one
+ * interface with one method per artifact type — analogous to
+ * `PublishImageBackend` being one interface satisfied by two backends
+ * (./publish.ts) — so the *capability* (./sbom.ts) stays artifact-type
+ * agnostic and simply calls the method matching the archive entry it was
+ * handed.
+ */
+/** The two SBOM standards this module supports. Never hardcode one — consumers key off `mediaType`. */
+export type SbomFormat = "spdx" | "cyclonedx";
+/** Canonical media type per format, mirroring `BuildArchiveEntry.mediaType`'s convention (./build-archive.ts). */
+export declare const SBOM_MEDIA_TYPES: Record<SbomFormat, string>;
+/** Project-wide default SBOM format when neither `chant.config.ts`'s `sbom.format` nor a component's `build.sbom.format` says otherwise. Documented in docs/components/build-archive.mdx. */
+export declare const DEFAULT_SBOM_FORMAT: SbomFormat;
+/**
+ * The artifact types an `SbomGenerator` backend can be asked to scan —
+ * mirrors the build-family's artifact shapes (`docker-build` -> `image`,
+ * `jvm-build` -> `jar`, `zip-package` -> `zip`, a bare source tree -> `dir`),
+ * never a component/cloud name.
+ */
+export type SbomArtifactType = "image" | "jar" | "zip" | "dir";
+/**
+ * An SBOM as an opaque typed document: format, its media type (what every
+ * consumer actually keys off), and the serialized bytes. Never inspected or
+ * re-parsed by chant itself — chant's job is to generate, store, and surface
+ * it, not to interpret SBOM content (that is the scan-result/VEX policy-gate
+ * fast-follow, out of scope here — see #606's "out of scope" section).
+ */
+export interface SbomDocument {
+    /** Which standard this document is. Informational — consumers should key off `mediaType`, not this field, for anything that dispatches on the wire format. */
+    format: SbomFormat;
+    /** The document's IANA/OCI media type (`application/spdx+json` or `application/vnd.cyclonedx+json`). This is the format-agnostic key every consumer (build-archive manifest, build ledger, `chant components status`) actually reads. */
+    mediaType: string;
+    /** Serialized SBOM content (the actual SPDX/CycloneDX JSON document, as bytes/string). */
+    bytes: string;
+    /** Number of packages/components the SBOM enumerates, when the generator reports it — surfaced by `chant components status` without parsing `bytes`. */
+    packageCount?: number;
+    /** Which tool produced this document (e.g. "syft", "buildkit", "cyclonedx-maven") — surfaced alongside format/package count so `chant components status` can report SBOM *source*, not just presence. */
+    generator: string;
+}
+export interface GenerateImageSbomInput {
+    /** Archive-relative or local path to the image tarball (OCI layout, as `docker save` produces — see ./build.ts's `DockerBuildOutput.archivePath`). */
+    imagePath: string;
+    /** Image digest the SBOM is being generated for (the join key with the build-archive manifest / build ledger). */
+    digest: string;
+    format?: SbomFormat;
+}
+export interface GenerateJarSbomInput {
+    /** Path to the built jar (see ./build.ts's `JvmBuildOutput.archivePath`). */
+    jarPath: string;
+    digest: string;
+    format?: SbomFormat;
+}
+export interface GenerateZipSbomInput {
+    /** Path to the built zip/Lambda package (see ./build.ts's `ZipPackageOutput.archivePath`). */
+    zipPath: string;
+    digest: string;
+    format?: SbomFormat;
+}
+export interface GenerateDirSbomInput {
+    /** Source directory to scan (a config-only/producer component with no packaged artifact, or a pre-build source scan). */
+    path: string;
+    format?: SbomFormat;
+}
+/**
+ * Injectable, artifact-type-keyed SBOM generation boundary — the SBOM-side
+ * analogue of `CloudExecutor` (./cloud-executor.ts). A real implementation
+ * shells out (BuildKit `docker buildx build --sbom=true`/`syft <target>
+ * -o spdx-json`/`cyclonedx-maven`/`cdxgen`); every method here is injected so
+ * tests substitute `MockSbomGenerator`
+ * (./__tests__/mock-sbom-generator.ts) and never invoke a real tool or the
+ * network.
+ */
+export interface SbomGenerator {
+    /** Generate (or attest) an SBOM for a built container image. A real implementation may prefer BuildKit's native `--sbom` attestation (defaults to SPDX, per the epic's refinement) or fall back to a `syft` scan of the saved tarball. */
+    forImage(input: GenerateImageSbomInput): Promise<SbomDocument>;
+    /** Generate an SBOM for a built JVM jar (`syft`/`cyclonedx-maven`). */
+    forJar(input: GenerateJarSbomInput): Promise<SbomDocument>;
+    /** Generate an SBOM for a built zip/Lambda deployment package (`syft` on the archive). */
+    forZip(input: GenerateZipSbomInput): Promise<SbomDocument>;
+    /** Generate an SBOM for a bare source directory (`syft`/`cdxgen`). */
+    forDir(input: GenerateDirSbomInput): Promise<SbomDocument>;
+}
+/**
+ * Thrown by `NotImplementedSbomGenerator` — the "no real backend wired yet"
+ * signal, matching `CapabilityNotImplementedError`'s role for verb stubs
+ * (../capability.ts). Kept distinct from a generic `Error` so callers (and
+ * tests) can assert on it specifically.
+ */
+export declare class SbomGeneratorNotImplementedError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+/**
+ * All-throwing `SbomGenerator`: every method throws
+ * `SbomGeneratorNotImplementedError`. No longer the process-wide default (see
+ * `defaultSbomGenerator` below, #630) — kept exported for callers that
+ * deliberately want the loud, no-backend-at-all behavior (e.g. a test
+ * asserting on the thrown error itself, or a caller that wants to force
+ * "nothing is wired" rather than silently getting the hermetic backend).
+ */
+export declare const notImplementedSbomGenerator: SbomGenerator;
+/**
+ * The default `SbomGenerator` the `generate-sbom` capability falls back to
+ * when none is supplied.
+ *
+ * **Hermetic by default (#630).** This is `./lockfile-sbom-generator.ts`'s
+ * `lockfileSbomGenerator` — `forDir`/`forZip`/`forJar` parse a
+ * `package-lock.json`/`pom.xml` already on disk (no `syft`, no network, no
+ * external tool) and emit a real SPDX/CycloneDX document. That means a
+ * newcomer composing `generate-sbom` over a source directory, a zip/Lambda
+ * package, or a JAR gets a working SBOM the moment they `chant run
+ * --components`, with nothing to install first — the whole point of #630's
+ * "runnable proof" bar. `forImage` still throws
+ * `SbomGeneratorNotImplementedError`: no hermetic backend can see an image's
+ * base layers, so an image SBOM still needs the real deep-scan tool backend
+ * (`syft`/`docker buildx --sbom`/`cyclonedx-maven`/`cdxgen`, #610) — a
+ * documented, deliberate gap, not an oversight. This was previously
+ * `notImplementedSbomGenerator` (every method throwing); switching the
+ * default is intentional per #630 — the prior "loud failure by default"
+ * traded newcomer runnability for a default nobody exercised without opting
+ * in, which #613 already built a hermetic backend to fix but never wired up.
+ * A project that truly wants the old all-throwing behavior can construct
+ * `createGenerateSbomCapability(notImplementedSbomGenerator)` explicitly.
+ */
+export declare function defaultSbomGenerator(): SbomGenerator;
+//# sourceMappingURL=sbom-generator.d.ts.map

package/dist/components/verbs/sbom-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom-generator.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/sbom-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAaH,uGAAuG;AACvG,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;AAE9C,kHAAkH;AAClH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAGvD,CAAC;AAEF,6LAA6L;AAC7L,eAAO,MAAM,mBAAmB,EAAE,UAAmB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,8JAA8J;IAC9J,MAAM,EAAE,UAAU,CAAC;IACnB,yOAAyO;IACzO,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,wJAAwJ;IACxJ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yMAAyM;IACzM,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,WAAW,sBAAsB;IACrC,sJAAsJ;IACtJ,SAAS,EAAE,MAAM,CAAC;IAClB,kHAAkH;IAClH,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,yHAAyH;IACzH,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,0OAA0O;IAC1O,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/D,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3D,0FAA0F;IAC1F,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3D,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5D;AAED;;;;;GAKG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;aAC7B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAO3C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAazC,CAAC;AAKF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,CAGpD"}

package/dist/components/verbs/sbom.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `generate-sbom` capability (#606, epic #551 follow-up to #564's build
+ * archive / #568's build ledger — closes the "produce" side #568 explicitly
+ * deferred).
+ *
+ * One capability, artifact-type-keyed via the injectable `SbomGenerator`
+ * (./sbom-generator.ts — mirrors ./cloud-executor.ts's `CloudExecutor`
+ * pattern), so a build-producing component of *any* artifact type — image,
+ * JAR, zip/Lambda package, or a bare source directory for a config-only
+ * producer — generates its SBOM through the same verb. Never docker-only:
+ * dispatch is on `input.artifactType`, not on which build capability
+ * produced the artifact.
+ *
+ * Writes the result into the build-archive manifest as an `sbom`-kind entry
+ * (../verbs/build-archive.ts), content-addressed and linked to its subject
+ * artifact's digest via `subjectDigest` — the **universal home** for the
+ * SBOM regardless of artifact type or registry availability. Registering the
+ * SBOM as an OCI referrer for image artifacts at publish time is a separate,
+ * later concern (the publish step/registry tooling's job, see
+ * ../../lifecycle/build-ledger.ts's `ReferrerLookup` for the consume side);
+ * this capability only ever writes the archive-carried copy, so it works
+ * unconditionally — including the registry-less `load-image-on-host` path.
+ *
+ * Config-only / infra components have no built artifact and simply never
+ * compose this step into their `deploy`/`build` phase — "skips cleanly" is
+ * structural (no step to run), not a special case this module needs to
+ * detect. Opt-out is the same: a component that wants no SBOM omits the
+ * `generate-sbom` step from its composition.
+ */
+import type { Capability } from "../capability.js";
+import { type BuildArchiveManifest } from "./build-archive.js";
+import { type SbomArtifactType, type SbomDocument, type SbomFormat, type SbomGenerator } from "./sbom-generator.js";
+export interface GenerateSbomInput {
+    /** Which artifact type to generate an SBOM for — selects the `SbomGenerator` method dispatched to (image -> BuildKit/syft, jar -> syft/cyclonedx-maven, zip -> syft, dir -> syft/cdxgen). */
+    artifactType: SbomArtifactType;
+    /** Archive-relative (or local, for `dir`) path to the artifact being scanned — the archive entry's `path` for `image`/`jar`/`zip`, or a source directory for `dir`. An `archive:`-prefixed reference is accepted and stripped, matching `publish-image`'s `from` convention. */
+    path: string;
+    /** Digest of the artifact this SBOM describes (the `image`/`asset` archive entry's `digest`) — omitted for `dir` scans that precede any build (no artifact digest exists yet), in which case the SBOM entry's `subjectDigest` is left unset. */
+    digest?: string;
+    /** SBOM format to request. Defaults to `chant.config.ts`'s `sbom.format`, then `DEFAULT_SBOM_FORMAT` (SPDX) when neither this input nor project config says otherwise — see ./sbom-generator.ts. */
+    format?: SbomFormat;
+    /** Where the SBOM document is written inside the build archive (e.g. `"search.sbom.json"`). Defaults to `<path>.sbom.json`. */
+    into?: string;
+    /** Manifest to extend with this SBOM's entry, rather than starting a fresh one — the same accumulation convention `docker-build`'s `manifest` input uses (./build.ts), so a component's whole build phase (image + SBOM, or JAR + SBOM) shares one manifest. */
+    manifest?: BuildArchiveManifest;
+}
+export interface GenerateSbomOutput {
+    /** The generated SBOM document (format, media type, bytes, package count, generator) — see ./sbom-generator.ts. */
+    sbom: SbomDocument;
+    /** Where the SBOM was written inside the build archive. */
+    archivePath: string;
+    /** Content-addressed digest of the SBOM document's own bytes. */
+    digest: string;
+    /** The build archive's manifest, now including this SBOM's entry alongside whatever `input.manifest` already held. */
+    manifest: BuildArchiveManifest;
+}
+/**
+ * Generate an SBOM for a build-producing component's artifact (image, JAR,
+ * zip, or source directory) via the artifact-type-keyed `SbomGenerator`, and
+ * fold the result into the build-archive manifest as an `sbom`-kind entry
+ * linked to the subject artifact's digest. Format defaults to
+ * `DEFAULT_SBOM_FORMAT` (SPDX) when neither `input.format` nor the injected
+ * generator overrides it — see ./sbom-generator.ts's module doc for the
+ * full default-resolution story. `chant.config.ts`'s `sbom.format` (see
+ * ../../config.ts's `ChantConfig.sbom` and `resolveSbomFormat`) is resolved
+ * by the caller/orchestrator into `input.format` before this capability
+ * runs, the same way env config is resolved before any other capability's
+ * `run` (this module never imports ../../config.ts directly, matching how
+ * no other verb module does either).
+ *
+ * No rollback: an already-generated SBOM sitting in the archive (or, later,
+ * projected as a registry referrer) is immutable, content-addressed
+ * evidence — nothing to compensate, the same opt-out `docker-build` and
+ * `publish-image` already take for their own no-mutable-remote-state reason.
+ */
+export declare function createGenerateSbomCapability(generator?: SbomGenerator): Capability<GenerateSbomInput, GenerateSbomOutput>;
+/** Default `generate-sbom` capability, backed by the process-wide default `SbomGenerator` (throws until a real backend is injected — see ./sbom-generator.ts's `notImplementedSbomGenerator`). */
+export declare const generateSbomCapability: Capability<GenerateSbomInput, GenerateSbomOutput>;
+//# sourceMappingURL=sbom.d.ts.map

package/dist/components/verbs/sbom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/sbom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,iBAAiB;IAChC,6LAA6L;IAC7L,YAAY,EAAE,gBAAgB,CAAC;IAC/B,gRAAgR;IAChR,IAAI,EAAE,MAAM,CAAC;IACb,gPAAgP;IAChP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oMAAoM;IACpM,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+HAA+H;IAC/H,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gQAAgQ;IAChQ,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,mHAAmH;IACnH,IAAI,EAAE,YAAY,CAAC;IACnB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,sHAAsH;IACtH,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,GAAE,aAAsC,GAChD,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAwBnD;AAED,kMAAkM;AAClM,eAAO,MAAM,sBAAsB,EAAE,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAkC,CAAC"}

package/dist/components/verbs/shell.d.ts

@@ -0,0 +1,35 @@
+/**
+ * escape hatch family — `shell`. Typed, but flagged: a raw shell step run by
+ * exactly one component is the "capability-per-component" smell the model
+ * exists to avoid (see docs/components/capabilities.mdx#the-discipline).
+ * `reason` is required so lint (COMP006) can flag an escape hatch used without
+ * a stated justification.
+ */
+import type { Capability } from "../capability.js";
+import { type ProcessRunner } from "./process-runner.js";
+export interface ShellInput {
+    /** Command to run. */
+    cmd: string;
+    /** Working directory. Default: process cwd. */
+    cwd?: string;
+    /** Additional environment variables. */
+    env?: Record<string, string>;
+    /** Required justification for reaching past the capability set — lint-checked. */
+    reason: string;
+}
+export interface ShellOutput {
+    /** Captured stdout. */
+    stdout: string;
+    /** Process exit code. Always 0 on success — a non-zero exit rejects the run. */
+    exitCode: number;
+}
+/**
+ * Run an arbitrary shell command through the injectable {@link ProcessRunner}.
+ * The escape hatch — typed, lint-flagged, and requires a `reason`. A non-zero
+ * exit rejects (with the command's own stderr), failing the step like any other
+ * capability error, so `onFailure`/rollback fires.
+ */
+export declare function createShellCapability(processRunner?: ProcessRunner): Capability<ShellInput, ShellOutput>;
+/** Default `shell` capability, backed by the real process runner. */
+export declare const shellCapability: Capability<ShellInput, ShellOutput>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/components/verbs/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/shell.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,GAAE,aAAsC,GAAG,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC,CAYhI;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,UAAU,EAAE,WAAW,CAA2B,CAAC"}