@intentius/chant 0.13.1 → 0.15.0

package/src/components/verbs/component-bom.ts

@@ -0,0 +1,189 @@
+/**
+ * Component-level BOM aggregation (#614, epic #551 follow-up to #613).
+ *
+ * A component may produce more than one leaf BOM: a software SBOM
+ * (./sbom.ts's `generate-sbom`, over an image/jar/zip/dir) for its built
+ * artifact, and/or an IaC config-BOM (./config-bom.ts's `extract-config-bom`)
+ * for its synthesized template. Each leaf BOM already validates as its own
+ * standalone SPDX/CycloneDX document (#613). This module composes every leaf
+ * BOM a component's build archive carries into **one** component-level BOM —
+ * a real assembly (CycloneDX `metadata.component` + nested `components` +
+ * `compositions` + `dependencies`, or SPDX `documentDescribes`-equivalent
+ * `CONTAINS`/`DEPENDS_ON` relationships), not a re-implementation of the
+ * writer: `aggregateComponentBom` below reads each leaf BOM's own structural
+ * inventory back out (it does not re-parse the leaf's serialized bytes) and
+ * hands the result to ./bom-writer.ts's `writeBom`, which gained
+ * `BomInput.subDocuments` support for exactly this purpose.
+ *
+ * **Why not just concatenate/parse the leaf documents' bytes.** The leaf BOM
+ * bytes are the source of truth for each artifact independently, but this
+ * module needs each leaf's package list as structured data to nest it
+ * correctly in the assembly — reparsing SPDX/CycloneDX JSON back into
+ * `BomPackage[]` would be a second, format-aware reader this codebase does
+ * not otherwise need. Callers therefore pass each leaf's already-known
+ * `BomPackage[]` (what `generate-sbom`/`extract-config-bom` built before
+ * calling `writeBom` themselves) plus the archive entry it produced — see
+ * `ComponentBomLeaf` below. A caller assembling a component's archive
+ * end-to-end has both on hand already; nothing here re-derives them from
+ * scratch.
+ *
+ * **Single-artifact = 1:1, multi-artifact = a real assembly.** A component
+ * with exactly one leaf BOM produces a component BOM whose only "assembly"
+ * is itself — see `aggregateComponentBom`'s single-leaf fast path, which
+ * still runs through the same writer and produces a valid document, just
+ * with an empty `subDocuments` composition (nothing to nest). A component
+ * with two or more leaves gets `subDocuments` populated, the real multi-leaf
+ * case #614 asks for.
+ *
+ * **Release-level rollup is out of scope here** (deferred per #614's note) —
+ * this module aggregates *within* one component's archive, never across
+ * components/releases.
+ */
+
+import type { BuildArchiveEntry, BuildArchiveManifest } from "./build-archive";
+import { sbomEntries } from "./build-archive";
+import { writeBom, type BomPackage, type BomSubDocument } from "./bom-writer";
+import { DEFAULT_SBOM_FORMAT, type SbomDocument, type SbomFormat } from "./sbom-generator";
+
+// ── inputs ───────────────────────────────────────────────────────────────────
+
+/**
+ * One leaf BOM a component produced, ready to fold into the component-level
+ * aggregate. `entry` is the `sbom`-kind `BuildArchiveEntry` `generate-sbom`/
+ * `extract-config-bom` already wrote into the manifest (carries `bomKind`,
+ * `subjectDigest`, `packageCount`, `generator`); `packages` is the same
+ * `BomPackage[]` that capability built before calling `writeBom` for its own
+ * standalone document.
+ */
+export interface ComponentBomLeaf {
+  /** The `sbom`-kind manifest entry this leaf corresponds to (see `findSbomForSubject`/`findConfigBomForSubject`, ./build-archive.ts). */
+  entry: BuildArchiveEntry;
+  /** The leaf's own enumerated packages/components/resources. */
+  packages: BomPackage[];
+}
+
+export interface AggregateComponentBomInput {
+  /** Component name — becomes the aggregate BOM's subject name. */
+  component: string;
+  /** The build archive manifest this component's leaves live in — used to derive a stable subject id from `manifestDigest` and to validate that every leaf's `entry` actually belongs to this manifest. */
+  manifest: BuildArchiveManifest;
+  /** Every leaf BOM to compose. Order is preserved in the resulting `subDocuments`/nested components. Must be non-empty — a component with no BOM to aggregate has nothing for this function to do (see module doc's "skips cleanly" convention elsewhere in this directory). */
+  leaves: ComponentBomLeaf[];
+  /** BOM format for the aggregate document. Defaults to `DEFAULT_SBOM_FORMAT` (SPDX), same precedence convention as every other BOM-producing capability in this directory. */
+  format?: SbomFormat;
+  /** Clock override for deterministic tests. */
+  now?: () => Date;
+}
+
+export interface AggregateComponentBomOutput {
+  /** The composed component-level BOM document. */
+  bom: SbomDocument;
+  /** Total package/component count across every leaf (the sum `chant components status` surfaces, see ../../lifecycle/build-ledger.ts). */
+  totalPackageCount: number;
+  /** How many leaf BOMs were composed — 1 for a single-artifact component (still a valid document, just with nothing to nest), 2+ for a real multi-artifact assembly. */
+  leafCount: number;
+}
+
+/** Tool name recorded on the aggregate document — distinct from any individual leaf's own `generator` (e.g. "syft", "chant-config-bom-extractor"), since the aggregate is produced by this module, not by whichever tool generated a leaf. */
+const COMPONENT_BOM_GENERATOR = "chant-component-bom-aggregator";
+
+/**
+ * Compose a component's leaf BOMs (a software SBOM and/or an IaC config-BOM,
+ * per `input.leaves`) into one component-level BOM via ./bom-writer.ts's
+ * assembly support (`BomInput.subDocuments`). Pure — no I/O, no manifest
+ * mutation; the caller decides whether/where to write the result to disk
+ * (mirroring `extract-config-bom`'s `outDir` convention) and whether to fold
+ * it back into the archive as its own entry.
+ *
+ * Throws if `input.leaves` is empty — aggregation over zero leaves is a
+ * caller bug (compose only when at least one BOM exists), not a case this
+ * function silently no-ops on.
+ */
+export function aggregateComponentBom(input: AggregateComponentBomInput): AggregateComponentBomOutput {
+  if (input.leaves.length === 0) {
+    throw new Error(
+      `aggregateComponentBom: component "${input.component}" has no leaf BOMs to aggregate — ` +
+        `only call this once at least one generate-sbom/extract-config-bom leaf exists`,
+    );
+  }
+
+  const format = input.format ?? DEFAULT_SBOM_FORMAT;
+  const totalPackageCount = input.leaves.reduce((sum, l) => sum + l.packages.length, 0);
+
+  // Single leaf: the component BOM *is* that leaf's BOM, structurally — no
+  // sub-document nesting needed, its packages become the aggregate's own
+  // flat package list directly (still a real, standalone valid document).
+  if (input.leaves.length === 1) {
+    const leaf = input.leaves[0]!;
+    const doc = writeBom(
+      format,
+      {
+        subjectName: input.component,
+        subjectId: input.manifest.manifestDigest,
+        packages: leaf.packages,
+        generator: COMPONENT_BOM_GENERATOR,
+      },
+      input.now,
+    );
+    return {
+      bom: { ...doc, packageCount: totalPackageCount, generator: COMPONENT_BOM_GENERATOR },
+      totalPackageCount,
+      leafCount: 1,
+    };
+  }
+
+  // Multi-leaf: a real assembly — each leaf becomes its own nested
+  // sub-document, keyed by which artifact digest it describes (its
+  // `subjectDigest`) so the assembly is traceable back to a specific
+  // BuildArchiveEntry, never flattened into one anonymous package list.
+  const subDocuments: BomSubDocument[] = input.leaves.map((leaf) => ({
+    subjectName: leafSubjectName(leaf),
+    subjectId: leaf.entry.subjectDigest ?? leaf.entry.digest,
+    packages: leaf.packages,
+  }));
+
+  const doc = writeBom(
+    format,
+    {
+      subjectName: input.component,
+      subjectId: input.manifest.manifestDigest,
+      packages: [],
+      generator: COMPONENT_BOM_GENERATOR,
+      subDocuments,
+    },
+    input.now,
+  );
+
+  return {
+    bom: { ...doc, packageCount: totalPackageCount, generator: COMPONENT_BOM_GENERATOR },
+    totalPackageCount,
+    leafCount: input.leaves.length,
+  };
+}
+
+/** Human-readable sub-document name: the leaf kind plus the archive path of the BOM entry itself, so two leaves of the same `bomKind` (unlikely but not disallowed) remain distinguishable. */
+function leafSubjectName(leaf: ComponentBomLeaf): string {
+  const kind = leaf.entry.bomKind ?? "software";
+  return `${kind}:${leaf.entry.path}`;
+}
+
+// ── convenience: build leaves straight from a manifest ──────────────────────
+
+/**
+ * Convenience for the common case: given a manifest that already carries
+ * `sbom`-kind entries (written by `generate-sbom`/`extract-config-bom`) and
+ * the `BomPackage[]` each one was built from (keyed by archive path, since
+ * that's the one stable identifier a caller has for "which leaf is this"),
+ * assemble the `ComponentBomLeaf[]` `aggregateComponentBom` expects. Kept
+ * separate from `aggregateComponentBom` itself so a caller that already has
+ * `ComponentBomLeaf[]` in hand (e.g. straight from the capabilities that just
+ * ran) can skip this lookup entirely.
+ */
+export function componentBomLeavesFromManifest(
+  manifest: BuildArchiveManifest,
+  packagesByPath: Map<string, BomPackage[]>,
+): ComponentBomLeaf[] {
+  return sbomEntries(manifest)
+    .filter((entry) => packagesByPath.has(entry.path))
+    .map((entry) => ({ entry, packages: packagesByPath.get(entry.path)! }));
+}

package/src/components/verbs/index.ts

@@ -0,0 +1,49 @@
+/**
+ * The starter verb set, grouped by family, per epic #551 and
+ * docs/components/capabilities.mdx. The pilot AWS leaves — `docker-build`,
+ * `publish-image`, `load-image-on-host`, `cfn-deploy`, `ecs-update-service`,
+ * `code-deploy`, `wait-for-stack`, `wait-steady-state`, `wait-cluster-healthy`
+ * — are real implementations over the injectable `CloudExecutor` (#557/#564,
+ * epic #551, see ./cloud-executor.ts); every other verb remains a typed stub
+ * (../capability.ts). `generate-sbom` (#606) is a real implementation over
+ * the injectable, artifact-type-keyed `SbomGenerator` (./sbom-generator.ts);
+ * `./lockfile-sbom-generator.ts` (#613) is a real, hermetic backend for it
+ * (lockfile/manifest parsing, no external tool), and `./tool-sbom-generator.ts`
+ * (#610) is a real, deep-scan backend for it (`syft`/`docker buildx --sbom`/
+ * `cyclonedx-maven`/`cdxgen`, shelling out through the injectable
+ * `ProcessRunner`, ./process-runner.ts). `extract-config-bom` (#613) parses a
+ * synthesized CloudFormation template, so it moved to the aws lexicon (#684);
+ * core keeps the agnostic SPDX/CycloneDX writer, ./bom-writer.ts, which both it
+ * and `generate-sbom` share. ./component-bom.ts
+ * (#614) composes a component's leaf BOMs into one component-level BOM over
+ * that same writer, and ./reproducibility.ts (#614) records per-artifact
+ * reproducibility + provenance on each `BuildArchiveEntry`. `publish-image`
+ * (#610) also gained a best-effort OCI-referrer attach step (`oras attach`,
+ * also via `ProcessRunner`) for a supplied SBOM/component BOM — see ./publish.ts.
+ * `sign`/`attest-provenance` (#622, ./sign.ts) are real implementations over
+ * the same injectable `ProcessRunner`: keyless-by-default `cosign sign`/
+ * `cosign attest` for signature + SLSA provenance, reusing #614's
+ * `ProvenanceLink` material. `verify` (#622, ./verify.ts) is the matching
+ * deploy-time gate — `cosign verify`/`verify-attestation` against a
+ * configured identity policy, mirroring ../../lint/policy.ts's `policyGate`.
+ */
+
+export * from "./build-archive";
+export * from "./build";
+export * from "./bom-writer";
+export * from "./sbom-generator";
+export * from "./sbom";
+export * from "./lockfile-sbom-generator";
+export * from "./tool-sbom-generator";
+export * from "./component-bom";
+export * from "./reproducibility";
+export * from "./sign";
+export * from "./verify";
+export * from "./vuln-scan";
+export * from "./vex";
+export * from "./license-policy";
+export * from "./vuln-gate";
+export * from "./wait-verify";
+export * from "./shell";
+export * from "./cloud-executor";
+export * from "./process-runner";

package/src/components/verbs/license-policy.ts

@@ -0,0 +1,115 @@
+/**
+ * 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";
+
+/** 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";
+}
+
+// ── extraction ───────────────────────────────────────────────────────────────
+
+interface SpdxDoc {
+  packages?: Array<{ name?: string; licenseConcluded?: string; licenseDeclared?: string }>;
+}
+interface CycloneDxDoc {
+  components?: Array<{
+    name?: string;
+    licenses?: Array<{ license?: { id?: string; name?: string }; expression?: string }>;
+  }>;
+}
+
+/** 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 function extractLicenses(sbom: SbomDocument): PackageLicense[] {
+  const doc = JSON.parse(sbom.bytes) as SpdxDoc & CycloneDxDoc;
+  if (sbom.format === "cyclonedx" || Array.isArray(doc.components)) {
+    return (doc.components ?? []).map((c) => {
+      const first = c.licenses?.[0];
+      const license = first?.expression ?? first?.license?.id ?? first?.license?.name ?? "NOASSERTION";
+      return { package: c.name ?? "unknown", license };
+    });
+  }
+  return (doc.packages ?? []).map((p) => ({
+    package: p.name ?? "unknown",
+    license: p.licenseConcluded && p.licenseConcluded !== "NOASSERTION" ? p.licenseConcluded : (p.licenseDeclared ?? "NOASSERTION"),
+  }));
+}
+
+// ── evaluation ───────────────────────────────────────────────────────────────
+
+/** Case-insensitive membership, so `"mit"` matches `"MIT"`. */
+function includesCi(list: string[], value: string): boolean {
+  const v = value.toLowerCase();
+  return list.some((x) => x.toLowerCase() === v);
+}
+
+/**
+ * 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 function licenseAtoms(expr: string): string[] {
+  return expr
+    .replace(/[()]/g, " ")
+    .split(/\s+(?:OR|AND)\s+/i)
+    .map((a) => a.split(/\s+WITH\s+/i)[0].trim())
+    .filter(Boolean);
+}
+
+/**
+ * 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 function evaluateLicensePolicy(sbom: SbomDocument, policy: LicensePolicy): LicenseViolation[] {
+  const out: LicenseViolation[] = [];
+  for (const { package: pkg, license } of extractLicenses(sbom)) {
+    if (!license || license === "NOASSERTION") continue;
+    const atoms = licenseAtoms(license);
+    if (policy.deny && atoms.some((a) => includesCi(policy.deny!, a))) {
+      out.push({ package: pkg, license, reason: "denied" });
+      continue;
+    }
+    if (policy.allow && policy.allow.length > 0 && atoms.some((a) => !includesCi(policy.allow!, a))) {
+      out.push({ package: pkg, license, reason: "not-allowed" });
+    }
+  }
+  return out;
+}

package/src/components/verbs/lockfile-sbom-generator.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Tests the hermetic lockfile/manifest-derived `SbomGenerator` (#613) against
+ * fixture lockfiles (./__fixtures__/package-lock.json,
+ * ./__fixtures__/pom.xml) — no network, no `syft`/`docker`/`mvn` invoked.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, afterEach } from "vitest";
+import {
+  parseNpmPackageLock,
+  parsePomXml,
+  createLockfileSbomGenerator,
+  sbomOutputPath,
+} from "./lockfile-sbom-generator";
+import { SbomGeneratorNotImplementedError } from "./sbom-generator";
+
+const FIXTURES_DIR = join(import.meta.dirname, "__fixtures__");
+const NPM_LOCK = readFileSync(join(FIXTURES_DIR, "package-lock.json"), "utf-8");
+const POM_XML = readFileSync(join(FIXTURES_DIR, "pom.xml"), "utf-8");
+
+describe("parseNpmPackageLock (#613)", () => {
+  it("extracts every non-root package with its resolved version", () => {
+    const packages = parseNpmPackageLock(NPM_LOCK);
+    const names = packages.map((p) => p.name).sort();
+    expect(names).toEqual(["accepts", "body-parser", "express", "left-pad", "mocha"]);
+    const express = packages.find((p) => p.name === "express")!;
+    expect(express.version).toBe("4.19.2");
+    expect(express.type).toBe("npm");
+    expect(express.purl).toBe("pkg:npm/express@4.19.2");
+  });
+
+  it("records declared dependency edges for DEPENDS_ON relationships", () => {
+    const packages = parseNpmPackageLock(NPM_LOCK);
+    const express = packages.find((p) => p.name === "express")!;
+    expect(express.dependsOn).toEqual(expect.arrayContaining(["accepts", "body-parser"]));
+  });
+
+  it("does not include the root project itself as a dependency", () => {
+    const packages = parseNpmPackageLock(NPM_LOCK);
+    expect(packages.find((p) => p.name === "fixture-search-service")).toBeUndefined();
+  });
+
+  it("falls back to the v1 nested dependencies tree when packages is absent", () => {
+    const v1Lock = JSON.stringify({
+      name: "fixture-v1",
+      version: "1.0.0",
+      dependencies: {
+        "left-pad": { version: "1.3.0", requires: {} },
+        chalk: { version: "4.1.2", requires: { "left-pad": "1.3.0" } },
+      },
+    });
+    const packages = parseNpmPackageLock(v1Lock);
+    expect(packages.map((p) => p.name).sort()).toEqual(["chalk", "left-pad"]);
+    expect(packages.find((p) => p.name === "chalk")!.dependsOn).toEqual(["left-pad"]);
+  });
+});
+
+describe("parsePomXml (#613)", () => {
+  it("extracts every declared <dependency> from the top-level <dependencies> block", () => {
+    const packages = parsePomXml(POM_XML);
+    const names = packages.map((p) => p.name).sort();
+    expect(names).toEqual([
+      "com.fasterxml.jackson.core:jackson-databind",
+      "org.apache.spark:spark-core_2.12",
+      "org.junit.jupiter:junit-jupiter",
+    ]);
+  });
+
+  it("does not pull dependencies declared only in <dependencyManagement>", () => {
+    const packages = parsePomXml(POM_XML);
+    expect(packages.find((p) => p.name.includes("should-not-appear"))).toBeUndefined();
+  });
+
+  it("derives a maven purl from groupId/artifactId/version", () => {
+    const packages = parsePomXml(POM_XML);
+    const spark = packages.find((p) => p.name === "org.apache.spark:spark-core_2.12")!;
+    expect(spark.version).toBe("3.5.1");
+    expect(spark.type).toBe("maven");
+    expect(spark.purl).toBe("pkg:maven/org.apache.spark/spark-core_2.12@3.5.1");
+  });
+
+  it("returns an empty list when there is no <dependencies> block", () => {
+    expect(parsePomXml("<project></project>")).toEqual([]);
+  });
+});
+
+describe("createLockfileSbomGenerator (#613) — hermetic SbomGenerator backend", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function withNpmFixture(): string {
+    tmpDir = mkdtempSync(join(tmpdir(), "chant-sbom-npm-"));
+    writeFileSync(join(tmpDir, "package-lock.json"), NPM_LOCK);
+    return tmpDir;
+  }
+
+  function withMavenFixture(): string {
+    tmpDir = mkdtempSync(join(tmpdir(), "chant-sbom-maven-"));
+    writeFileSync(join(tmpDir, "pom.xml"), POM_XML);
+    return tmpDir;
+  }
+
+  it("forDir scans a directory's package-lock.json and emits a valid SPDX doc by default", async () => {
+    const dir = withNpmFixture();
+    const generator = createLockfileSbomGenerator();
+    const doc = await generator.forDir({ path: dir });
+    expect(doc.format).toBe("spdx");
+    expect(doc.mediaType).toBe("application/spdx+json");
+    expect(doc.packageCount).toBe(5);
+    expect(doc.generator).toBe("chant-lockfile-sbom/package-lock.json");
+    const parsed = JSON.parse(doc.bytes);
+    expect(parsed.spdxVersion).toBe("SPDX-2.3");
+  });
+
+  it("forDir scans a directory's pom.xml when no package-lock.json is present", async () => {
+    const dir = withMavenFixture();
+    const generator = createLockfileSbomGenerator();
+    const doc = await generator.forDir({ path: dir });
+    expect(doc.packageCount).toBe(3);
+    expect(doc.generator).toBe("chant-lockfile-sbom/pom.xml");
+  });
+
+  it("honors an explicit cyclonedx format request", async () => {
+    const dir = withNpmFixture();
+    const generator = createLockfileSbomGenerator();
+    const doc = await generator.forDir({ path: dir, format: "cyclonedx" });
+    expect(doc.format).toBe("cyclonedx");
+    expect(doc.mediaType).toBe("application/vnd.cyclonedx+json");
+    expect(JSON.parse(doc.bytes).bomFormat).toBe("CycloneDX");
+  });
+
+  it("writes the SBOM to disk as sbom.<format>.json alongside the scanned directory", async () => {
+    const dir = withNpmFixture();
+    const generator = createLockfileSbomGenerator();
+    await generator.forDir({ path: dir });
+    const written = readFileSync(sbomOutputPath(dir, "spdx"), "utf-8");
+    expect(JSON.parse(written).spdxVersion).toBe("SPDX-2.3");
+  });
+
+  it("writes to a distinct outDir when configured, instead of alongside the scanned directory", async () => {
+    const dir = withNpmFixture();
+    const outDir = join(dir, "out");
+    const generator = createLockfileSbomGenerator({ outDir });
+    await generator.forDir({ path: dir });
+    const written = readFileSync(sbomOutputPath(outDir, "spdx"), "utf-8");
+    expect(JSON.parse(written).spdxVersion).toBe("SPDX-2.3");
+  });
+
+  it("forJar/forZip scan the artifact's containing directory for a lockfile", async () => {
+    const dir = withNpmFixture();
+    const generator = createLockfileSbomGenerator();
+    const jarDoc = await generator.forJar({ jarPath: join(dir, "lib.jar"), digest: "sha256:jar1" });
+    expect(jarDoc.packageCount).toBe(5);
+    const zipDoc = await generator.forZip({ zipPath: join(dir, "fn.zip"), digest: "sha256:zip1" });
+    expect(zipDoc.packageCount).toBe(5);
+  });
+
+  it("forImage throws SbomGeneratorNotImplementedError — an image's base layers are outside a lockfile's scope", async () => {
+    const generator = createLockfileSbomGenerator();
+    await expect(generator.forImage({ imagePath: "x.tar", digest: "sha256:1" })).rejects.toBeInstanceOf(
+      SbomGeneratorNotImplementedError,
+    );
+  });
+
+  it("throws a clear error when no supported lockfile/manifest is found", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "chant-sbom-empty-"));
+    const generator = createLockfileSbomGenerator();
+    await expect(generator.forDir({ path: tmpDir })).rejects.toThrow(/no supported lockfile/);
+  });
+
+  it("two generations from identical (path + content) input produce the same digest/bytes (content-addressed)", async () => {
+    // Use two fixed, identically-named subdirectories under one root so
+    // `path` (which feeds both subjectName and, absent a digest, subjectId)
+    // is identical across both scans — isolating the assertion to "same
+    // input, same output" rather than incidentally varying by directory
+    // identity (which mkdtempSync's random suffix would otherwise do).
+    const root = mkdtempSync(join(tmpdir(), "chant-sbom-determinism-"));
+    tmpDir = root;
+    const dirA = join(root, "component");
+    const dirB = join(root, "component"); // same path, scanned twice in sequence
+    mkdirSync(dirA, { recursive: true });
+    writeFileSync(join(dirA, "package-lock.json"), NPM_LOCK);
+
+    const fixedNow = () => new Date("2026-01-01T00:00:00.000Z");
+    const docA = await createLockfileSbomGenerator({ now: fixedNow }).forDir({ path: dirA });
+    const docB = await createLockfileSbomGenerator({ now: fixedNow }).forDir({ path: dirB });
+
+    expect(docA.bytes).toBe(docB.bytes);
+  });
+});