@intentius/chant 0.13.1 → 0.15.0

package/src/components/verbs/__tests__/mock-cloud-executor.ts

@@ -0,0 +1,102 @@
+/**
+ * `MockCloudExecutor` — an in-memory fake of the *agnostic* `CloudExecutor`
+ * (../cloud-executor.ts) for tests: the `docker` build/push client and the
+ * Neo4j bolt probe, the two clients core still owns. No live docker, ever, in
+ * a test run — every method records its call and returns a canned result.
+ *
+ * The AWS clients' mock moved to the aws lexicon alongside their
+ * implementations (`@intentius/chant-lexicon-aws/components`).
+ */
+
+import type { CloudExecutor, DockerBuildArgs, DockerLoadArgs, DockerPushArgs, DockerSaveArgs, DockerTagArgs, Neo4jProbeArgs } from "../cloud-executor";
+
+export interface RecordedCall {
+  client: string;
+  method: string;
+  args: unknown;
+}
+
+export interface FakeClusterConfig {
+  /** Number of bolt endpoints (out of however many `cluster` lists) that report healthy. Default: all of them. */
+  healthyCount?: number;
+}
+
+export interface MockCloudExecutorOptions {
+  /** Neo4j cluster health, keyed by the comma-joined endpoint string `wait-cluster-healthy` probes. */
+  clusters?: Record<string, FakeClusterConfig>;
+  /** Force every docker call to fail (simulates a build/push failure). */
+  failDocker?: boolean;
+}
+
+/** An injected agnostic `CloudExecutor` plus the call log and cluster-health controls tests use. */
+export interface MockCloudExecutor {
+  executor: CloudExecutor;
+  calls: RecordedCall[];
+  /** Change how many cluster members report healthy after construction (simulates a follower catching up). */
+  setClusterHealth(cluster: string, healthyCount: number): void;
+}
+
+/** Build a fresh mock agnostic `CloudExecutor`. Every method is deterministic and synchronous-fast — no real polling delay. */
+export function createMockCloudExecutor(options: MockCloudExecutorOptions = {}): MockCloudExecutor {
+  const calls: RecordedCall[] = [];
+  const record = (client: string, method: string, args: unknown) => calls.push({ client, method, args });
+
+  const clusters = new Map<string, number>(
+    Object.entries(options.clusters ?? {}).map(([k, v]) => [k, v.healthyCount ?? Number.MAX_SAFE_INTEGER]),
+  );
+
+  const docker: CloudExecutor["docker"] = {
+    async build(args: DockerBuildArgs) {
+      record("docker", "build", args);
+      if (options.failDocker) throw new Error(`docker build failed for ${args.context}`);
+      return { digest: `sha256:${fakeDigest("build", args.context, args.tag)}` };
+    },
+    async save(args: DockerSaveArgs) {
+      record("docker", "save", args);
+    },
+    async load(args: DockerLoadArgs) {
+      record("docker", "load", args);
+      return { digest: `sha256:${fakeDigest("load", args.inFile)}` };
+    },
+    async tag(args: DockerTagArgs) {
+      record("docker", "tag", args);
+    },
+    async push(args: DockerPushArgs) {
+      record("docker", "push", args);
+      if (options.failDocker) throw new Error(`docker push failed for ${args.image}`);
+      return { digest: `sha256:${fakeDigest("push", args.image)}` };
+    },
+    async remoteDigest(image: string) {
+      record("docker", "remoteDigest", image);
+      return `sha256:${fakeDigest("remote", image)}`;
+    },
+  };
+
+  const neo4j: CloudExecutor["neo4j"] = {
+    async probe(args: Neo4jProbeArgs) {
+      record("neo4j", "probe", args);
+      const endpoints = args.cluster
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      const healthy = clusters.get(args.cluster) ?? endpoints.length;
+      return { healthyCount: Math.min(healthy, endpoints.length), total: endpoints.length };
+    },
+  };
+
+  return {
+    executor: { docker, neo4j },
+    calls,
+    setClusterHealth: (cluster, healthyCount) => clusters.set(cluster, healthyCount),
+  };
+}
+
+/** Deterministic fake digest suffix derived from its inputs — stable across calls with the same args, distinct otherwise. */
+function fakeDigest(...parts: string[]): string {
+  let hash = 0;
+  const input = parts.join("|");
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash * 31 + input.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash).toString(16).padStart(8, "0").repeat(4).slice(0, 64);
+}

package/src/components/verbs/__tests__/mock-process-runner.ts

@@ -0,0 +1,79 @@
+/**
+ * `MockProcessRunner` — an in-memory fake of `ProcessRunner`
+ * (../process-runner.ts) for tests. No live `syft`/`buildx`/
+ * `cyclonedx-maven`/`cdxgen`/`oras`, no child process spawned at all: every
+ * call is recorded, and `run`/`available` return scripted results — the same
+ * convention `../__tests__/mock-cloud-executor.ts` uses for `CloudExecutor`.
+ *
+ * Every test that exercises a #610 real backend (`ToolSbomGenerator`,
+ * `OrasReferrerLookup`, `publish-image`'s referrer-attach step) builds one
+ * `MockProcessRunner`, scripts which tools are "installed" and what each
+ * command's canned stdout is, and passes it in — never touching the real,
+ * `child_process`-backed runner.
+ */
+
+import type { ProcessResult, ProcessRunner, RunOptions } from "../process-runner";
+
+export interface RecordedProcessCall {
+  command: string;
+  options?: RunOptions;
+}
+
+export interface MockProcessRunnerOptions {
+  /** Which tools `available()` reports as installed. Default: every tool is available (opt a test into "missing tool" by naming it here with `false`, or by omitting it when `defaultAvailable` is `false`). */
+  tools?: Record<string, boolean>;
+  /** `available()`'s answer for a tool not named in `tools`. Default: `true` (most tests aren't about the missing-tool path). */
+  defaultAvailable?: boolean;
+  /**
+   * Canned stdout per command, matched by a substring (the first entry whose
+   * key is included in the command string wins) — this is deliberately loose
+   * rather than an exact-string map, since the SUT constructs full shell
+   * command lines the test doesn't want to hand-reconstruct byte-for-byte
+   * just to script a response.
+   */
+  responses?: Record<string, string>;
+  /** Command substrings that should reject (simulates the tool exiting non-zero), mapped to the error message. */
+  failures?: Record<string, string>;
+}
+
+export interface MockProcessRunner {
+  runner: ProcessRunner;
+  calls: RecordedProcessCall[];
+  /** Change a tool's reported availability after construction. */
+  setAvailable(tool: string, available: boolean): void;
+  /** Script (or replace) a command substring's canned stdout after construction. */
+  setResponse(commandSubstring: string, stdout: string): void;
+}
+
+/** Build a fresh mock `ProcessRunner`. Every method is deterministic and synchronous-fast — no real process spawned, no real delay. */
+export function createMockProcessRunner(options: MockProcessRunnerOptions = {}): MockProcessRunner {
+  const calls: RecordedProcessCall[] = [];
+  const tools = new Map<string, boolean>(Object.entries(options.tools ?? {}));
+  const responses = new Map<string, string>(Object.entries(options.responses ?? {}));
+  const failures = new Map<string, string>(Object.entries(options.failures ?? {}));
+  const defaultAvailable = options.defaultAvailable ?? true;
+
+  const runner: ProcessRunner = {
+    async run(command: string, runOptions?: RunOptions): Promise<ProcessResult> {
+      calls.push({ command, options: runOptions });
+      for (const [substring, message] of failures) {
+        if (command.includes(substring)) throw new Error(message);
+      }
+      for (const [substring, stdout] of responses) {
+        if (command.includes(substring)) return { stdout, stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    },
+    async available(tool: string): Promise<boolean> {
+      calls.push({ command: `command -v ${tool}` });
+      return tools.has(tool) ? tools.get(tool)! : defaultAvailable;
+    },
+  };
+
+  return {
+    runner,
+    calls,
+    setAvailable: (tool, available) => tools.set(tool, available),
+    setResponse: (commandSubstring, stdout) => responses.set(commandSubstring, stdout),
+  };
+}

package/src/components/verbs/__tests__/mock-sbom-generator.ts

@@ -0,0 +1,85 @@
+/**
+ * `MockSbomGenerator` — an in-memory fake of `SbomGenerator`
+ * (../sbom-generator.ts) for tests. No live `syft`/`docker buildx`/
+ * `cyclonedx-maven`/`cdxgen`, no network: every method records its call and
+ * returns a deterministic, canned `SbomDocument` derived from its inputs, the
+ * same convention `../__tests__/mock-cloud-executor.ts` uses for
+ * `CloudExecutor` (a fake digest suffix derived from the call's arguments,
+ * stable across calls with the same args).
+ *
+ * Every test that exercises `generate-sbom` (../sbom.ts) builds one
+ * `MockSbomGenerator` and passes it to `createGenerateSbomCapability`,
+ * never touching a real scanner.
+ */
+
+import type {
+  GenerateDirSbomInput,
+  GenerateImageSbomInput,
+  GenerateJarSbomInput,
+  GenerateZipSbomInput,
+  SbomDocument,
+  SbomFormat,
+  SbomGenerator,
+} from "../sbom-generator";
+import { SBOM_MEDIA_TYPES, DEFAULT_SBOM_FORMAT } from "../sbom-generator";
+
+export interface RecordedSbomCall {
+  method: "forImage" | "forJar" | "forZip" | "forDir";
+  args: unknown;
+}
+
+export interface MockSbomGeneratorOptions {
+  /** Force every call to fail (simulates a scanner crash/timeout). */
+  fail?: boolean;
+  /** Package count reported for every generated SBOM. Default: 3. */
+  packageCount?: number;
+  /** Generator/tool name reported. Default: "mock-syft". */
+  generatorName?: string;
+}
+
+export interface MockSbomGenerator {
+  generator: SbomGenerator;
+  calls: RecordedSbomCall[];
+}
+
+/** Build a fresh mock `SbomGenerator`. Every method is deterministic and synchronous-fast — no real scan delay. */
+export function createMockSbomGenerator(options: MockSbomGeneratorOptions = {}): MockSbomGenerator {
+  const calls: RecordedSbomCall[] = [];
+  const record = (method: RecordedSbomCall["method"], args: unknown) => calls.push({ method, args });
+
+  function fakeSbom(kind: string, subject: string, format: SbomFormat | undefined, generatorName: string): SbomDocument {
+    const resolvedFormat = format ?? DEFAULT_SBOM_FORMAT;
+    return {
+      format: resolvedFormat,
+      mediaType: SBOM_MEDIA_TYPES[resolvedFormat],
+      bytes: JSON.stringify({ fake: true, kind, subject, format: resolvedFormat }),
+      packageCount: options.packageCount ?? 3,
+      generator: options.generatorName ?? generatorName,
+    };
+  }
+
+  const generator: SbomGenerator = {
+    async forImage(input: GenerateImageSbomInput) {
+      record("forImage", input);
+      if (options.fail) throw new Error(`sbom generation failed for image ${input.imagePath}`);
+      return fakeSbom("image", input.imagePath, input.format, "mock-buildkit");
+    },
+    async forJar(input: GenerateJarSbomInput) {
+      record("forJar", input);
+      if (options.fail) throw new Error(`sbom generation failed for jar ${input.jarPath}`);
+      return fakeSbom("jar", input.jarPath, input.format, "mock-syft");
+    },
+    async forZip(input: GenerateZipSbomInput) {
+      record("forZip", input);
+      if (options.fail) throw new Error(`sbom generation failed for zip ${input.zipPath}`);
+      return fakeSbom("zip", input.zipPath, input.format, "mock-syft");
+    },
+    async forDir(input: GenerateDirSbomInput) {
+      record("forDir", input);
+      if (options.fail) throw new Error(`sbom generation failed for dir ${input.path}`);
+      return fakeSbom("dir", input.path, input.format, "mock-cdxgen");
+    },
+  };
+
+  return { generator, calls };
+}

package/src/components/verbs/bom-writer.test.ts

@@ -0,0 +1,331 @@
+/**
+ * Validates the native BOM writer (#613) against the *actual* published
+ * SPDX-2.3 and CycloneDX-1.5 JSON Schemas — vendored as fixtures under
+ * ./__fixtures__/schemas/, the same "vendor the spec schema as a devDep test
+ * fixture" convention #553 used for the Component contract schema and #607
+ * used for the GitLab CI schema. No network at test time: the schemas are
+ * committed, read from disk, and compiled once with `ajv`.
+ *
+ * Source of the vendored schemas (for provenance, not fetched at test time):
+ *  - spdx-2.3.schema.json: https://github.com/spdx/spdx-spec/blob/support/2.3/schemas/spdx-schema.json
+ *  - cyclonedx-1.5.schema.json: https://github.com/CycloneDX/specification/blob/1.5/schema/bom-1.5.schema.json
+ *  - jsf-0.82.schema.json / cyclonedx-spdx-license.schema.json: CycloneDX's
+ *    own `$ref` dependencies (renamed from the upstream `spdx.schema.json` to
+ *    avoid confusion with SPDX's own document schema above, which is a
+ *    different document entirely).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020";
+import Ajv from "ajv";
+import { writeSpdx, writeCycloneDx, writeBom, type BomInput, type BomPackage, type BomSubDocument } from "./bom-writer";
+
+const SCHEMAS_DIR = join(import.meta.dirname, "__fixtures__/schemas");
+
+function loadSchema(name: string): unknown {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), "utf-8"));
+}
+
+const FIXED_NOW = () => new Date("2026-01-01T00:00:00.000Z");
+
+const samplePackages: BomPackage[] = [
+  { name: "left-pad", version: "1.3.0", type: "npm", purl: "pkg:npm/left-pad@1.3.0" },
+  { name: "express", version: "4.19.2", type: "npm", purl: "pkg:npm/express@4.19.2", dependsOn: ["left-pad"] },
+];
+
+const sampleInput: BomInput = {
+  subjectName: "search-service",
+  subjectVersion: "1.0.0",
+  subjectId: "sha256:" + "a".repeat(64),
+  packages: samplePackages,
+  generator: "chant-lockfile-sbom/package-lock.json",
+};
+
+describe("writeSpdx (#613) — structural validation against the real SPDX-2.3 JSON Schema", () => {
+  const schema = loadSchema("spdx-2.3.schema.json");
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  // The vendored spdx-2.3.schema.json declares draft-07 ($schema), while
+  // Ajv2020 is instantiated for draft 2020-12 fixtures elsewhere in this
+  // repo (component-schema.test.ts) — use a plain Ajv (draft-07 capable) for
+  // this one instead, matching the schema's own declared dialect.
+  const ajvDraft07 = new Ajv({ strict: false, allErrors: true });
+  const validate = ajvDraft07.compile(schema as object);
+
+  it("is a valid JSON Schema document", () => {
+    expect(ajv.validateSchema).toBeDefined();
+    expect((schema as { $schema: string }).$schema).toContain("draft-07");
+  });
+
+  it("produces a document with every SPDX-2.3-required top-level field", () => {
+    const bytes = writeSpdx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    expect(doc.spdxVersion).toBe("SPDX-2.3");
+    expect(doc.SPDXID).toBe("SPDXRef-DOCUMENT");
+    expect(doc.documentNamespace).toEqual(expect.stringMatching(/^https:\/\//));
+    expect(doc.name).toBe("search-service");
+    expect(Array.isArray(doc.packages)).toBe(true);
+    expect(doc.packages.length).toBeGreaterThan(0);
+    for (const pkg of doc.packages) {
+      expect(pkg.name).toBeTruthy();
+      expect(pkg.SPDXID).toEqual(expect.stringMatching(/^SPDXRef-/));
+    }
+  });
+
+  it("validates against the real SPDX-2.3 JSON Schema", () => {
+    const bytes = writeSpdx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    const valid = validate(doc);
+    if (!valid) throw new Error(`SPDX document failed schema validation: ${ajvDraft07.errorsText(validate.errors)}`);
+    expect(valid).toBe(true);
+  });
+
+  it("includes a DESCRIBES relationship from the document to the subject package, and DEPENDS_ON edges for declared deps", () => {
+    const bytes = writeSpdx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    expect(doc.relationships).toContainEqual(
+      expect.objectContaining({ relationshipType: "DESCRIBES", spdxElementId: "SPDXRef-DOCUMENT" }),
+    );
+    expect(doc.relationships).toContainEqual(
+      expect.objectContaining({ relationshipType: "DEPENDS_ON", relatedSpdxElement: "SPDXRef-Package-left-pad" }),
+    );
+  });
+
+  it("is deterministic — identical input produces byte-identical output", () => {
+    const a = writeSpdx(sampleInput, FIXED_NOW);
+    const b = writeSpdx(sampleInput, FIXED_NOW);
+    expect(a).toBe(b);
+  });
+
+  it("handles an empty package list (a subject with no declared deps) without failing schema validation", () => {
+    const bytes = writeSpdx({ ...sampleInput, packages: [] }, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    expect(validate(doc)).toBe(true);
+  });
+});
+
+describe("writeCycloneDx (#613) — structural validation against the real CycloneDX-1.5 JSON Schema", () => {
+  const cdxSchema = loadSchema("cyclonedx-1.5.schema.json");
+  const jsfSchema = loadSchema("jsf-0.82.schema.json");
+  const spdxLicenseSchema = loadSchema("cyclonedx-spdx-license.schema.json");
+
+  const ajv = new Ajv({ strict: false, allErrors: true });
+  ajv.addSchema(jsfSchema as object);
+  ajv.addSchema(spdxLicenseSchema as object);
+  const validate = ajv.compile(cdxSchema as object);
+
+  it("produces a document with every CycloneDX-1.5-required top-level field", () => {
+    const bytes = writeCycloneDx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    expect(doc.bomFormat).toBe("CycloneDX");
+    expect(doc.specVersion).toBe("1.5");
+    expect(doc.serialNumber).toEqual(expect.stringMatching(/^urn:uuid:/));
+    expect(typeof doc.version).toBe("number");
+    expect(doc.metadata?.component?.name).toBe("search-service");
+    expect(Array.isArray(doc.components)).toBe(true);
+    for (const c of doc.components) {
+      expect(["application", "library", "framework", "container", "operating-system", "device", "firmware", "file"]).toContain(
+        c.type,
+      );
+      expect(c.name).toBeTruthy();
+    }
+  });
+
+  it("validates against the real CycloneDX-1.5 JSON Schema", () => {
+    const bytes = writeCycloneDx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    const valid = validate(doc);
+    if (!valid) throw new Error(`CycloneDX document failed schema validation: ${ajv.errorsText(validate.errors)}`);
+    expect(valid).toBe(true);
+  });
+
+  it("includes a dependencies section: the root subject depends on every listed component, plus declared inter-component deps", () => {
+    const bytes = writeCycloneDx(sampleInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    const rootDep = doc.dependencies.find((d: { ref: string }) => d.ref === "subject:search-service");
+    expect(rootDep.dependsOn).toEqual(expect.arrayContaining(["left-pad", "express"]));
+    const expressDep = doc.dependencies.find((d: { ref: string }) => d.ref === "express");
+    expect(expressDep.dependsOn).toEqual(["left-pad"]);
+  });
+
+  it("is deterministic — identical input produces a byte-identical serialNumber and document", () => {
+    const a = writeCycloneDx(sampleInput, FIXED_NOW);
+    const b = writeCycloneDx(sampleInput, FIXED_NOW);
+    expect(a).toBe(b);
+  });
+
+  it("handles an empty package list without failing schema validation", () => {
+    const bytes = writeCycloneDx({ ...sampleInput, packages: [] }, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    expect(validate(doc)).toBe(true);
+  });
+});
+
+describe("writeBom (#613) — format dispatch wrapping the project-wide {format, mediaType, bytes} doc shape", () => {
+  it("dispatches spdx to writeSpdx and sets the SPDX media type", () => {
+    const doc = writeBom("spdx", sampleInput, FIXED_NOW);
+    expect(doc.format).toBe("spdx");
+    expect(doc.mediaType).toBe("application/spdx+json");
+    expect(JSON.parse(doc.bytes).spdxVersion).toBe("SPDX-2.3");
+  });
+
+  it("dispatches cyclonedx to writeCycloneDx and sets the CycloneDX media type", () => {
+    const doc = writeBom("cyclonedx", sampleInput, FIXED_NOW);
+    expect(doc.format).toBe("cyclonedx");
+    expect(doc.mediaType).toBe("application/vnd.cyclonedx+json");
+    expect(JSON.parse(doc.bytes).bomFormat).toBe("CycloneDX");
+  });
+});
+
+// ── assembly: BomInput.subDocuments (#614) ──────────────────────────────────
+
+const subDocuments: BomSubDocument[] = [
+  {
+    subjectName: "software:image.tar.sbom.json",
+    subjectId: "sha256:" + "b".repeat(64),
+    packages: [{ name: "left-pad", version: "1.3.0", type: "npm" }],
+  },
+  {
+    subjectName: "config:search.template.json.config-bom.json",
+    subjectId: "sha256:" + "c".repeat(64),
+    packages: [{ name: "SearchBucket", version: "AWS::S3::Bucket", type: "config" }],
+  },
+];
+
+const assemblyInput: BomInput = {
+  subjectName: "search-service",
+  subjectId: "sha256:" + "d".repeat(64),
+  packages: [],
+  generator: "chant-component-bom-aggregator",
+  subDocuments,
+};
+
+describe("writeSpdx assembly (#614) — CONTAINS/DEPENDS_ON relationships for a multi-leaf component BOM", () => {
+  const schema = loadSchema("spdx-2.3.schema.json");
+  const ajvDraft07 = new Ajv({ strict: false, allErrors: true });
+  const validate = ajvDraft07.compile(schema as object);
+
+  it("validates against the real SPDX-2.3 JSON Schema", () => {
+    const bytes = writeSpdx(assemblyInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    const valid = validate(doc);
+    if (!valid) throw new Error(`SPDX assembly failed schema validation: ${ajvDraft07.errorsText(validate.errors)}`);
+    expect(valid).toBe(true);
+  });
+
+  it("emits a CONTAINS relationship from the root subject to each sub-document's own root package", () => {
+    const doc = JSON.parse(writeSpdx(assemblyInput, FIXED_NOW));
+    const containsFromRoot = doc.relationships.filter(
+      (r: { spdxElementId: string; relationshipType: string }) =>
+        r.spdxElementId === "SPDXRef-Package-search-service" && r.relationshipType === "CONTAINS",
+    );
+    expect(containsFromRoot).toHaveLength(2);
+  });
+
+  it("nests each sub-document's own packages under a namespace unique to it, never colliding across sub-documents", () => {
+    const doc = JSON.parse(writeSpdx(assemblyInput, FIXED_NOW));
+    const ids = doc.packages.map((p: { SPDXID: string }) => p.SPDXID);
+    expect(new Set(ids).size).toBe(ids.length); // every SPDXID unique
+    expect(ids).toContain("SPDXRef-Package-sub0-left-pad");
+    expect(ids).toContain("SPDXRef-Package-sub1-SearchBucket");
+  });
+
+  it("a same-named package in two different sub-documents does not collide (distinct SPDX IDs)", () => {
+    const collidingInput: BomInput = {
+      ...assemblyInput,
+      subDocuments: [
+        { subjectName: "leaf-a", subjectId: "sha256:1", packages: [{ name: "shared-name", version: "1.0.0" }] },
+        { subjectName: "leaf-b", subjectId: "sha256:2", packages: [{ name: "shared-name", version: "2.0.0" }] },
+      ],
+    };
+    const doc = JSON.parse(writeSpdx(collidingInput, FIXED_NOW));
+    const ids = doc.packages.map((p: { SPDXID: string }) => p.SPDXID);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(validate(doc)).toBe(true);
+  });
+
+  it("without subDocuments, behaves exactly as before #614 (no CONTAINS relationships, no behavior change)", () => {
+    const doc = JSON.parse(writeSpdx(sampleInput, FIXED_NOW));
+    const contains = doc.relationships.filter((r: { relationshipType: string }) => r.relationshipType === "CONTAINS");
+    expect(contains).toHaveLength(0);
+  });
+});
+
+describe("writeCycloneDx assembly (#614) — nested components + compositions + dependencies for a multi-leaf component BOM", () => {
+  const cdxSchema = loadSchema("cyclonedx-1.5.schema.json");
+  const jsfSchema = loadSchema("jsf-0.82.schema.json");
+  const spdxLicenseSchema = loadSchema("cyclonedx-spdx-license.schema.json");
+  const ajv = new Ajv({ strict: false, allErrors: true });
+  ajv.addSchema(jsfSchema as object);
+  ajv.addSchema(spdxLicenseSchema as object);
+  const validate = ajv.compile(cdxSchema as object);
+
+  it("validates against the real CycloneDX-1.5 JSON Schema", () => {
+    const bytes = writeCycloneDx(assemblyInput, FIXED_NOW);
+    const doc = JSON.parse(bytes);
+    const valid = validate(doc);
+    if (!valid) throw new Error(`CycloneDX assembly failed schema validation: ${ajv.errorsText(validate.errors)}`);
+    expect(valid).toBe(true);
+  });
+
+  it("nests each sub-document as a real component under metadata.component.components, not flattened into the root's own components array", () => {
+    const doc = JSON.parse(writeCycloneDx(assemblyInput, FIXED_NOW));
+    expect(doc.metadata.component.components).toHaveLength(2);
+    const names = doc.metadata.component.components.map((c: { name: string }) => c.name);
+    expect(names).toEqual(["software:image.tar.sbom.json", "config:search.template.json.config-bom.json"]);
+    // the root-level `components` array (the flat single-document list)
+    // stays empty here since assemblyInput.packages is [] — the aggregate's
+    // own packages live in the nested sub-documents, not flattened up.
+    expect(doc.components).toEqual([]);
+  });
+
+  it("records a compositions entry with aggregate: incomplete, referencing the root and every sub-document", () => {
+    const doc = JSON.parse(writeCycloneDx(assemblyInput, FIXED_NOW));
+    expect(doc.compositions).toHaveLength(1);
+    expect(doc.compositions[0].aggregate).toBe("incomplete");
+    expect(doc.compositions[0].assemblies).toEqual(
+      expect.arrayContaining(["subject:search-service", "sub0:subject:software:image.tar.sbom.json", "sub1:subject:config:search.template.json.config-bom.json"]),
+    );
+  });
+
+  it("dependencies: the root subject depends on each sub-document root, and each sub-document depends on its own packages", () => {
+    const doc = JSON.parse(writeCycloneDx(assemblyInput, FIXED_NOW));
+    const rootDep = doc.dependencies.find((d: { ref: string }) => d.ref === "subject:search-service");
+    expect(rootDep.dependsOn).toEqual(
+      expect.arrayContaining(["sub0:subject:software:image.tar.sbom.json", "sub1:subject:config:search.template.json.config-bom.json"]),
+    );
+    const sub0Dep = doc.dependencies.find((d: { ref: string }) => d.ref === "sub0:subject:software:image.tar.sbom.json");
+    expect(sub0Dep.dependsOn).toEqual(["sub0:left-pad"]);
+  });
+
+  it("a same-named package in two different sub-documents does not collide (distinct bom-refs)", () => {
+    const collidingInput: BomInput = {
+      ...assemblyInput,
+      subDocuments: [
+        { subjectName: "leaf-a", subjectId: "sha256:1", packages: [{ name: "shared-name", version: "1.0.0" }] },
+        { subjectName: "leaf-b", subjectId: "sha256:2", packages: [{ name: "shared-name", version: "2.0.0" }] },
+      ],
+    };
+    const doc = JSON.parse(writeCycloneDx(collidingInput, FIXED_NOW));
+    const allRefs = [
+      doc.metadata.component["bom-ref"],
+      ...doc.metadata.component.components.map((c: { "bom-ref": string }) => c["bom-ref"]),
+      ...doc.metadata.component.components.flatMap((c: { components: Array<{ "bom-ref": string }> }) => c.components.map((cc) => cc["bom-ref"])),
+    ];
+    expect(new Set(allRefs).size).toBe(allRefs.length);
+    expect(validate(doc)).toBe(true);
+  });
+
+  it("without subDocuments, behaves exactly as before #614 (no compositions, no nested components, no behavior change)", () => {
+    const doc = JSON.parse(writeCycloneDx(sampleInput, FIXED_NOW));
+    expect(doc.compositions).toBeUndefined();
+    expect(doc.metadata.component.components).toBeUndefined();
+  });
+
+  it("is deterministic — identical assembly input produces byte-identical output", () => {
+    const a = writeCycloneDx(assemblyInput, FIXED_NOW);
+    const b = writeCycloneDx(assemblyInput, FIXED_NOW);
+    expect(a).toBe(b);
+  });
+});