@intentius/chant 0.124.13 → 0.124.15

package/dist/components/verbs/cloud-executor.js

@@ -0,0 +1,110 @@
+/**
+ * Injectable cloud I/O boundary for the *agnostic* capability implementations
+ * that remain in core: the `docker` build/push client and the Neo4j bolt-port
+ * probe. Every capability here that talks to a real tool goes through a
+ * `CloudExecutor` instead of shelling out directly, so production code gets a
+ * real, `child_process`/`net`-backed executor and tests get a
+ * `MockCloudExecutor` (./__tests__/mock-cloud-executor.ts) that records calls
+ * and returns canned results — no live docker, ever, in a test run.
+ *
+ * The AWS-specific clients (CloudFormation, ECS, Lambda, EMR, CodeDeploy, SSM
+ * host, S3, CloudFront, snapshot, ECR) used to live here too. They now live in
+ * the aws lexicon (`@intentius/chant-lexicon-aws/components`), contributed
+ * through the capability-plugin seam — see docs/components/cloud-boundary. The
+ * `docker` client stays in core because it is genuinely cloud-agnostic and
+ * shared: `docker-build` (agnostic) uses it here, and the aws lexicon's
+ * `publish-image` reuses the exported `realDocker` rather than duplicating it.
+ */
+import { exec } from "node:child_process";
+import { createConnection } from "node:net";
+import { promisify } from "node:util";
+import { isAbsolute, join } from "node:path";
+export const execFileAsync = promisify(exec);
+// ── Real executor — shells out to `docker`; used outside tests ───────────────
+/** Run a shell command, capturing stdout/stderr. Internal to the docker client; the aws lexicon's executor has its own (endpoint-aware) runner. */
+function run(command) {
+    return execFileAsync(command, { maxBuffer: 64 * 1024 * 1024 });
+}
+/** Shell-quote a single argument for POSIX shells (wrap in single quotes, escaping embedded ones). Internal; the shared, exported `q` lives in ./process-runner. */
+function q(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export const realDocker = {
+    async build(args) {
+        const parts = [`docker build`, `-t ${q(args.tag)}`];
+        if (args.dockerfile) {
+            // dockerfile is relative to `context` (its documented contract); docker's `-f` resolves a relative path against cwd, not the context dir, so join them here (chant#936).
+            const dockerfilePath = isAbsolute(args.dockerfile) ? args.dockerfile : join(args.context, args.dockerfile);
+            parts.push(`-f ${q(dockerfilePath)}`);
+        }
+        if (args.target)
+            parts.push(`--target ${q(args.target)}`);
+        for (const [k, v] of Object.entries(args.buildArgs ?? {}))
+            parts.push(`--build-arg ${q(`${k}=${v}`)}`);
+        parts.push(q(args.context));
+        await run(parts.join(" "));
+        const { stdout } = await run(`docker image inspect ${q(args.tag)} --format '{{.Id}}'`);
+        return { digest: stdout.trim() };
+    },
+    async save(args) {
+        await run(`docker save ${q(args.image)} -o ${q(args.outFile)}`);
+    },
+    async load(args) {
+        const { stdout } = await run(`docker load -i ${q(args.inFile)}`);
+        const match = stdout.match(/[Ll]oaded image(?: ID)?:\s*(\S+)/);
+        return { digest: match?.[1] ?? stdout.trim() };
+    },
+    async tag(args) {
+        await run(`docker tag ${q(args.source)} ${q(args.target)}`);
+    },
+    async push(args) {
+        await run(`docker push ${q(args.image)}`);
+        const { stdout } = await run(`docker image inspect ${q(args.image)} --format '{{index .RepoDigests 0}}'`);
+        return { digest: stdout.trim() };
+    },
+    async remoteDigest(image) {
+        const { stdout } = await run(`docker manifest inspect -v ${q(image)}`);
+        return stdout.trim();
+    },
+};
+const realNeo4j = {
+    async probe(args) {
+        const endpoints = args.cluster
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const results = await Promise.all(endpoints.map((endpoint) => probeBoltPort(endpoint)));
+        return { healthyCount: results.filter(Boolean).length, total: endpoints.length };
+    },
+};
+/** Probe one `host:port` bolt endpoint by opening (and immediately closing) a TCP socket. */
+function probeBoltPort(endpoint, timeoutMs = 5000) {
+    const [host, portStr] = endpoint.split(":");
+    const port = Number(portStr ?? 7687);
+    return new Promise((resolve) => {
+        const socket = createConnection({ host, port, timeout: timeoutMs });
+        const finish = (healthy) => {
+            socket.destroy();
+            resolve(healthy);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("timeout", () => finish(false));
+        socket.once("error", () => finish(false));
+    });
+}
+/** Build a `CloudExecutor` that shells out to the real `docker` CLI and probes real bolt ports. Never used in tests. */
+export function realCloudExecutor() {
+    return { docker: realDocker, neo4j: realNeo4j };
+}
+/** Lazily-constructed process-wide default so importing a capability module never shells out at import time. */
+let defaultExecutor;
+/** The default `CloudExecutor` each capability factory falls back to when none is supplied. */
+export function defaultCloudExecutor() {
+    if (!defaultExecutor)
+        defaultExecutor = realCloudExecutor();
+    return defaultExecutor;
+}
+/** Sleep for `ms`. Shared by every polling capability (`wait-*`) between attempts. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/components/verbs/component-bom.js

@@ -0,0 +1,125 @@
+/**
+ * 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 { sbomEntries } from "./build-archive.js";
+import { writeBom } from "./bom-writer.js";
+import { DEFAULT_SBOM_FORMAT } from "./sbom-generator.js";
+/** 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) {
+    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 = 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) {
+    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, packagesByPath) {
+    return sbomEntries(manifest)
+        .filter((entry) => packagesByPath.has(entry.path))
+        .map((entry) => ({ entry, packages: packagesByPath.get(entry.path) }));
+}

package/dist/components/verbs/ensure-secret.js

@@ -0,0 +1,50 @@
+/**
+ * secrets family — `ensure-secret` (#1829, epic #1365 decision 3). The
+ * capability surface over the one generated-once materialization engine
+ * (../../secret-materialization.ts); the op step builder `ensureSecret(...)`
+ * (../../op/builders.ts) is the other surface over the same engine.
+ *
+ * Contract (read-then-write): present means done. The verb never mints over
+ * an existing value and never rotates implicitly; an existing secret that
+ * does not match the declared key-set/metadata stops the apply with a
+ * `SecretContractMismatchError` naming key names and metadata keys — never
+ * values. There is no safe undo for minting a secret others may already have
+ * consumed, and un-creating it would destroy the only copy of the material —
+ * so `rollbackPolicy: "needs-opt-out"`: COMP003 requires a component using
+ * this verb to acknowledge the compensation gap explicitly.
+ *
+ * The store adapter is per-provider (#1830 is the k8s row). Core registers a
+ * typed stub; a provider builds the real capability with
+ * {@link createEnsureSecretCapability}.
+ */
+import { CapabilityNotImplementedError } from "../capability.js";
+import { ensureSecretMaterialization, defaultSecretMaterialGenerator, } from "../../secret-materialization.js";
+/**
+ * Build the real `ensure-secret` capability over a provider's
+ * {@link SecretStoreAdapter}. The generator seam defaults to 32 CSPRNG bytes
+ * per key; the material it mints flows straight through the adapter to the
+ * store and is never returned, logged, or retained (see
+ * ../../secret-materialization.ts).
+ */
+export function createEnsureSecretCapability(deps) {
+    return {
+        kind: "ensure-secret",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            return ensureSecretMaterialization(deps.store, { name: input.name, keys: input.keys, metadata: input.metadata }, deps.generator ?? defaultSecretMaterialGenerator);
+        },
+    };
+}
+/**
+ * The starter-set registration: fully typed, correct `rollbackPolicy` for
+ * COMP003, but no store adapter — running it throws
+ * `CapabilityNotImplementedError` until a provider row (#1830, k8s) wires a
+ * real adapter via {@link createEnsureSecretCapability}.
+ */
+export const ensureSecretCapability = {
+    kind: "ensure-secret",
+    rollbackPolicy: "needs-opt-out",
+    async run() {
+        throw new CapabilityNotImplementedError("ensure-secret");
+    },
+};

package/dist/components/verbs/index.js

@@ -0,0 +1,61 @@
+/**
+ * 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`.
+ * `wrangler-deploy`/`wrangler-versions-promote` (#1293, epic #1296,
+ * ./wrangler.ts) and `r2-sync` (#1293, ./r2-sync.ts) are the Cloudflare
+ * Workers apply leaves — real implementations over the same injectable
+ * `ProcessRunner` `sign` uses, shelling to `wrangler`/`rclone` rather than an
+ * AWS-shaped SDK client. `run-agent` (#1941, epic #1564 phase 1, ./run-agent.ts)
+ * is the typed schema + registry entry for a bounded, attested agent-turn
+ * capability over a fly Sprite — a typed stub for now (`run`/`rollback`
+ * reject with `CapabilityNotImplementedError`), `rollbackPolicy: "native"`
+ * declared up front; the real sprite-lifecycle implementation is #1942.
+ */
+export * from "./build-archive.js";
+export * from "./build.js";
+export * from "./bom-writer.js";
+export * from "./sbom-generator.js";
+export * from "./sbom.js";
+export * from "./lockfile-sbom-generator.js";
+export * from "./tool-sbom-generator.js";
+export * from "./component-bom.js";
+export * from "./reproducibility.js";
+export * from "./sign.js";
+export * from "./verify.js";
+export * from "./run-agent.js";
+export * from "./wrangler.js";
+export * from "./r2-sync.js";
+export * from "./vuln-scan.js";
+export * from "./vex.js";
+export * from "./license-policy.js";
+export * from "./vuln-gate.js";
+export * from "./wait-verify.js";
+export * from "./shell.js";
+export * from "./ensure-secret.js";
+export * from "./cloud-executor.js";
+export * from "./process-runner.js";

package/dist/components/verbs/license-policy.js

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+/** 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) {
+    const doc = JSON.parse(sbom.bytes);
+    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, value) {
+    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) {
+    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, policy) {
+    const out = [];
+    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/dist/components/verbs/lockfile-sbom-generator.js

@@ -0,0 +1,191 @@
+/**
+ * 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 { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeBom } from "./bom-writer.js";
+import { DEFAULT_SBOM_FORMAT } from "./sbom-generator.js";
+import { SbomGeneratorNotImplementedError } 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 function parseNpmPackageLock(content) {
+    const lock = JSON.parse(content);
+    const seen = new Map();
+    const add = (name, version, deps) => {
+        if (!name)
+            return;
+        const key = `${name}@${version ?? ""}`;
+        const existing = seen.get(key);
+        if (existing) {
+            if (deps?.length)
+                existing.dependsOn = [...new Set([...(existing.dependsOn ?? []), ...deps])];
+            return;
+        }
+        seen.set(key, {
+            name,
+            version,
+            type: "npm",
+            purl: version ? `pkg:npm/${encodeURIComponent(name)}@${version}` : undefined,
+            dependsOn: deps?.length ? deps : undefined,
+        });
+    };
+    if (lock.packages) {
+        for (const [path, pkg] of Object.entries(lock.packages)) {
+            if (path === "")
+                continue; // the root project itself, not a dependency
+            const name = pkg.name ?? path.replace(/^.*node_modules\//, "");
+            add(name, pkg.version, pkg.dependencies ? Object.keys(pkg.dependencies) : undefined);
+        }
+    }
+    else if (lock.dependencies) {
+        for (const [name, pkg] of Object.entries(lock.dependencies)) {
+            add(name, pkg.version, pkg.requires ? Object.keys(pkg.requires) : undefined);
+        }
+    }
+    return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+// ── pom.xml (Maven — cheap, declared <dependencies> only) ───────────────────
+/**
+ * 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 function parsePomXml(content) {
+    const packages = [];
+    // Strip <dependencyManagement>...</dependencyManagement> first — it
+    // declares version *policy*, not necessarily artifacts actually used, and
+    // (like the real <dependencies> block) can itself contain a nested
+    // <dependencies> block, which a naive non-nesting-aware regex would match
+    // in its place. Removing it up front guarantees the subsequent
+    // <dependencies> match is the real, top-level one.
+    const withoutManagement = content.replace(/<dependencyManagement>[\s\S]*?<\/dependencyManagement>/, "");
+    const depsBlockMatch = withoutManagement.match(/<dependencies>([\s\S]*?)<\/dependencies>/);
+    if (!depsBlockMatch)
+        return packages;
+    const depBlock = depsBlockMatch[1];
+    const depRegex = /<dependency>([\s\S]*?)<\/dependency>/g;
+    let match;
+    while ((match = depRegex.exec(depBlock)) !== null) {
+        const entry = match[1];
+        const groupId = entry.match(/<groupId>([^<]+)<\/groupId>/)?.[1]?.trim();
+        const artifactId = entry.match(/<artifactId>([^<]+)<\/artifactId>/)?.[1]?.trim();
+        const version = entry.match(/<version>([^<]+)<\/version>/)?.[1]?.trim();
+        if (!groupId || !artifactId)
+            continue;
+        const name = `${groupId}:${artifactId}`;
+        packages.push({
+            name,
+            version,
+            type: "maven",
+            purl: version ? `pkg:maven/${encodeURIComponent(groupId)}/${encodeURIComponent(artifactId)}@${version}` : undefined,
+        });
+    }
+    return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Locate the first readable lockfile/manifest under `dir` this generator knows how to parse, in preference order (npm before Maven — most chant components are Node-first). Returns `undefined` if none is found. */
+function findManifest(dir) {
+    for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"]]) {
+        const candidate = join(dir, filename);
+        try {
+            readFileSync(candidate, "utf-8");
+            return { kind, path: candidate };
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/** Default on-disk path for a generated SBOM: `<dir>/sbom.<format>.json`, matching #613's `sbom.<format>.json` naming convention. */
+export function sbomOutputPath(dir, format) {
+    return join(dir, `sbom.${format}.json`);
+}
+/**
+ * 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 function createLockfileSbomGenerator(options = {}) {
+    const now = options.now ?? (() => new Date());
+    function generateFromDir(dir, subjectName, digest, format = DEFAULT_SBOM_FORMAT) {
+        const manifest = findManifest(dir);
+        if (!manifest) {
+            throw new Error(`no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml) — ` +
+                `the hermetic lockfile SBOM backend requires a lockfile on disk; use the deep-scan path (#610) for images with no lockfile`);
+        }
+        const content = readFileSync(manifest.path, "utf-8");
+        const packages = manifest.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
+        const generatorName = manifest.kind === "npm" ? "chant-lockfile-sbom/package-lock.json" : "chant-lockfile-sbom/pom.xml";
+        const doc = writeBom(format, { subjectName, subjectId: digest ?? manifest.path, packages, generator: generatorName }, now);
+        const outDir = options.outDir ?? dir;
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(sbomOutputPath(outDir, format), doc.bytes);
+        return { ...doc, packageCount: packages.length, generator: generatorName };
+    }
+    return {
+        async forImage(_input) {
+            throw new SbomGeneratorNotImplementedError("forImage");
+        },
+        async forJar(input) {
+            return generateFromDir(dirname(input.jarPath), input.jarPath, input.digest, input.format);
+        },
+        async forZip(input) {
+            return generateFromDir(dirname(input.zipPath), input.zipPath, input.digest, input.format);
+        },
+        async forDir(input) {
+            return generateFromDir(input.path, input.path, undefined, input.format);
+        },
+    };
+}
+/** Process-wide hermetic lockfile-backed `SbomGenerator`, ready to inject wherever ./sbom-generator.ts's `notImplementedSbomGenerator` default previously required an explicit real backend. */
+export const lockfileSbomGenerator = createLockfileSbomGenerator();