@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/dist/wrapper-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper-chart.d.ts","sourceRoot":"","sources":["../src/wrapper-chart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErE,wFAAwF;AACxF,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yFAAyF;IACzF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAYD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,wBAAwB,CAwCnG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-helm",
-  "version": "0.46.0",
+  "version": "0.50.0",
   "description": "Helm chart lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -49,6 +49,11 @@
       "types": "./dist/components/index.d.ts",
       "default": "./src/components/index.ts"
     },
+    "./pinnability": {
+      "development": "./src/pinnability/index.ts",
+      "types": "./dist/pinnability/index.d.ts",
+      "default": "./src/pinnability/index.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -73,7 +78,7 @@
   },
   "dependencies": {
     "@intentius/chant-lexicon-k8s": "*",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.3.1"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -81,7 +86,8 @@
     "@types/js-yaml": "^4.0.9"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.46.0",
-    "typescript": "^5.9.3"
+    "@intentius/chant": "^0.50.0",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
   }
 }

package/src/archive-render.test.ts

@@ -0,0 +1,201 @@
+/**
+ * Tests `addArchiveHelmRender` (#1240, epic #1228 Phase 3) — folding a
+ * pinned render into a build archive's manifest, and the media-type story
+ * that lets an OCI referrer lookup classify signatures/provenance/SBOMs
+ * attached to a render's digest exactly as it would for an image.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  addArchiveEntry,
+  createBuildArchiveManifest,
+  findArchiveEntry,
+  templateEntries,
+} from "@intentius/chant/components/verbs/build-archive";
+import { createOrasReferrerLookup } from "@intentius/chant/lifecycle/oras-referrer-lookup";
+import type { ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+
+import { addArchiveHelmRender, HELM_RENDER_MEDIA_TYPE } from "./archive-render";
+import type { RenderManifest } from "./render-store";
+
+const RENDER_CONTENT_DIGEST =
+  "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+function fixtureRenderManifest(overrides: Partial<RenderManifest> = {}): RenderManifest {
+  return {
+    version: 1,
+    chart: "external-secrets",
+    chartVersion: "0.10.4",
+    repo: "https://charts.external-secrets.io",
+    releaseName: "external-secrets",
+    namespace: "external-secrets",
+    valuesDigest: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    inputDigest: "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    capabilityProfile: { cluster: "prod", kubeVersion: "1.29.0", apiVersions: [] },
+    contentDigest: RENDER_CONTENT_DIGEST,
+    docCount: 3,
+    documents: [],
+    renderedAt: "2026-01-01T00:00:00.000Z",
+    helmVersion: "3.14.0",
+    chantVersion: "0.46.0",
+    sourceRef: null,
+    coalescedValuesDigest: null,
+    valueSources: null,
+    ...overrides,
+  };
+}
+
+describe("addArchiveHelmRender (#1240)", () => {
+  it("folds the render into BuildArchiveManifest.contents as a template-kind entry with the render media type", () => {
+    const render = fixtureRenderManifest();
+    const { manifest, digest } = addArchiveHelmRender({
+      path: "external-secrets.render.yaml",
+      render,
+    });
+
+    expect(digest).toBe(RENDER_CONTENT_DIGEST);
+    const entry = findArchiveEntry(manifest, "external-secrets.render.yaml");
+    expect(entry).toMatchObject({
+      kind: "template",
+      path: "external-secrets.render.yaml",
+      digest: RENDER_CONTENT_DIGEST,
+      mediaType: HELM_RENDER_MEDIA_TYPE,
+    });
+    expect(templateEntries(manifest)).toHaveLength(1);
+  });
+
+  it("reuses the render's own contentDigest rather than recomputing one from bytes", () => {
+    const render = fixtureRenderManifest({
+      contentDigest: "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+    });
+    const { manifest } = addArchiveHelmRender({ path: "chart.render.yaml", render });
+    expect(findArchiveEntry(manifest, "chart.render.yaml")?.digest).toBe(render.contentDigest);
+  });
+
+  it("the render rolls into manifestDigest — adding it changes the aggregate digest", () => {
+    const empty = createBuildArchiveManifest("my-component");
+    const { manifest } = addArchiveHelmRender({
+      path: "chart.render.yaml",
+      render: fixtureRenderManifest(),
+      manifest: empty,
+    });
+    expect(manifest.manifestDigest).not.toBe(empty.manifestDigest);
+  });
+
+  it("accumulates onto a caller-supplied manifest alongside other archive entries", () => {
+    const staged = addArchiveEntry(createBuildArchiveManifest("my-component"), {
+      kind: "image",
+      path: "app.tar",
+      digest: "sha256:img1",
+    });
+
+    const { manifest } = addArchiveHelmRender({
+      path: "chart.render.yaml",
+      render: fixtureRenderManifest(),
+      manifest: staged,
+    });
+
+    expect(manifest.contents.map((e) => e.kind).sort()).toEqual(["image", "template"]);
+  });
+
+  it("records provenance from an explicit sourceRef", () => {
+    const { manifest } = addArchiveHelmRender({
+      path: "chart.render.yaml",
+      render: fixtureRenderManifest(),
+      sourceRef: "abc123",
+    });
+    const entry = findArchiveEntry(manifest, "chart.render.yaml");
+    expect(entry?.provenance).toEqual({ sourceRef: "abc123", artifactDigest: RENDER_CONTENT_DIGEST });
+  });
+
+  it("falls back to the render's own sourceRef when the caller omits one", () => {
+    const { manifest } = addArchiveHelmRender({
+      path: "chart.render.yaml",
+      render: fixtureRenderManifest({ sourceRef: "deadbeef" }),
+    });
+    expect(findArchiveEntry(manifest, "chart.render.yaml")?.provenance).toEqual({
+      sourceRef: "deadbeef",
+      artifactDigest: RENDER_CONTENT_DIGEST,
+    });
+  });
+
+  it("records no provenance when neither the caller nor the render supplies a sourceRef", () => {
+    const { manifest } = addArchiveHelmRender({ path: "chart.render.yaml", render: fixtureRenderManifest() });
+    expect(findArchiveEntry(manifest, "chart.render.yaml")?.provenance).toBeUndefined();
+  });
+
+  it("assigns the template-kind default reproducibility basis (deterministic-synthesis)", () => {
+    const { manifest } = addArchiveHelmRender({ path: "chart.render.yaml", render: fixtureRenderManifest() });
+    expect(findArchiveEntry(manifest, "chart.render.yaml")?.reproducibility).toEqual({
+      basis: "deterministic-synthesis",
+      verifyBy: "re-synth",
+    });
+  });
+});
+
+describe("a render's digest is classified by the referrer lookup exactly like an image's (#1240)", () => {
+  const REPO = "123.dkr.ecr.us-east-1.amazonaws.com/external-secrets";
+
+  function stubRunner(stdout: string): ProcessRunner {
+    return {
+      async run() {
+        return { stdout, stderr: "" };
+      },
+      async available() {
+        return true;
+      },
+    };
+  }
+
+  it("discovers and classifies an SBOM referrer attached to the render's own contentDigest", async () => {
+    const render = fixtureRenderManifest();
+    // The archive entry this referrer would attach to — its `kind: "template"` /
+    // `HELM_RENDER_MEDIA_TYPE` never enter the lookup below, which discovers by digest alone.
+    addArchiveHelmRender({ path: "chart.render.yaml", render });
+
+    const runner = stubRunner(
+      JSON.stringify({
+        manifests: [
+          {
+            digest: "sha256:sbom1",
+            mediaType: "application/vnd.oci.image.manifest.v1+json",
+            artifactType: "application/spdx+json",
+          },
+        ],
+      }),
+    );
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner });
+
+    const referrers = await lookup.discover(render.contentDigest);
+
+    expect(referrers).toEqual([
+      { kind: "sbom", mediaType: "application/spdx+json", digest: "sha256:sbom1", location: `${REPO}@sha256:sbom1` },
+    ]);
+  });
+
+  it("discovers a provenance and a signature referrer the same way, unaffected by the subject entry's own template kind/media type", async () => {
+    const render = fixtureRenderManifest();
+    const runner = stubRunner(
+      JSON.stringify({
+        manifests: [
+          {
+            digest: "sha256:prov1",
+            mediaType: "application/vnd.oci.image.manifest.v1+json",
+            artifactType: "application/vnd.in-toto+json",
+          },
+          {
+            digest: "sha256:sig1",
+            mediaType: "application/vnd.dev.cosign.simplesigning.v1+json",
+            artifactType: "application/vnd.dev.cosign.signature",
+          },
+        ],
+      }),
+    );
+    const lookup = createOrasReferrerLookup({ repo: REPO, runner });
+
+    const referrers = await lookup.discover(render.contentDigest);
+
+    expect(referrers.map((r) => r.kind)).toEqual(["provenance", "signature"]);
+  });
+});

package/src/archive-render.ts

@@ -0,0 +1,119 @@
+/**
+ * `addArchiveHelmRender` — fold a pinned render into a `BuildArchiveManifest`
+ * (#1240, epic #1228 Phase 3).
+ *
+ * #1238 gave a pinned render durable, content-addressed storage
+ * (./render-store.ts's `RenderManifest`, modeled on core's
+ * `BuildArchiveManifest`). This module is the seam between the two: it folds
+ * one render into a *build archive*'s manifest, the same self-contained
+ * bundle `docker-build`/`addArchiveTemplate` write into
+ * (packages/core/src/components/verbs/build-archive.ts), so a component that
+ * composes a `HelmRender` alongside an image/template gets one archive that
+ * carries all of it.
+ *
+ * A rendered chart is a template: it reuses `kind: "template"` rather than
+ * adding a new `BuildArchiveEntryKind`. What distinguishes a render from a
+ * synthesized CloudFormation/other IaC template is only its media type,
+ * `HELM_RENDER_MEDIA_TYPE` — and that is enough. Core's
+ * `lifecycle/oras-referrer-lookup.ts` classifies *referrers* (SBOM/
+ * provenance/signature) by the referrer's own media type, keyed only by the
+ * subject *digest* it discovers against — never by the subject entry's own
+ * `kind`/`mediaType`. A render's digest is therefore attachable exactly like
+ * an image's: `oras discover <repo>@<renderDigest>` finds the same
+ * referrers a signing/attestation pipeline would attach to any other
+ * artifact, with no change to that lookup needed (see
+ * ./archive-render.test.ts for the referrer-classification proof).
+ *
+ * Mirrors `addArchiveTemplate` (packages/core/src/components/verbs/build.ts)
+ * in every way that matters: a plain, pure function (not a registered
+ * capability — rendering happens at chant's existing build/synth time, not
+ * as a new deploy-time verb), accumulates onto a caller-supplied manifest so
+ * a component's whole build phase shares one archive, and threads an
+ * optional `sourceRef` into a `provenance` link (#614). It differs in one
+ * respect: rather than recomputing a digest from raw content bytes (core's
+ * `contentDigest`), it reuses the render's own `contentDigest` — the real
+ * `sha256:` over the canonical rendered stream that `helmContentDigest`
+ * already computed and `persistHelmRender` already wrote to the render
+ * store — so the archive entry's identity and the render store's identity
+ * are the same digest, not two independent hashes of the same bytes.
+ */
+
+import {
+  addArchiveEntry,
+  createBuildArchiveManifest,
+  type BuildArchiveManifest,
+} from "@intentius/chant/components/verbs/build-archive";
+import type { ProvenanceLink } from "@intentius/chant/components/verbs/reproducibility";
+
+import type { RenderManifest } from "./render-store";
+
+/**
+ * Media type for a pinned helm render folded into a build archive as a
+ * `template`-kind entry. `v1` names the canonical-stream shape
+ * `canonicalizeRender` (./render-digest.ts) produces — a versioned suffix so
+ * a future incompatible canonicalization can be told apart from this one
+ * without guessing from content alone.
+ */
+export const HELM_RENDER_MEDIA_TYPE = "application/vnd.chant.helm-render.v1+yaml";
+
+export interface AddArchiveHelmRenderInput {
+  /** Where the render is written inside the build archive (e.g. `"external-secrets.render.yaml"`). */
+  path: string;
+  /**
+   * The persisted render this entry describes — see ./render-store.ts's
+   * `persistHelmRender`/`loadRenderManifest`. Supplies the entry's digest
+   * (`RenderManifest.contentDigest`, the same identity the render store
+   * keys its content-addressed entry under).
+   */
+  render: RenderManifest;
+  /**
+   * Manifest to extend, so a component's whole build phase (image/template +
+   * render) accumulates one manifest — the same accumulation convention
+   * `addArchiveTemplate`/`generate-sbom`'s `manifest` input uses. Omit to
+   * start a new manifest holding just this render.
+   */
+  manifest?: BuildArchiveManifest;
+  /**
+   * Source ref/commit this render was produced from (#614), recorded as the
+   * entry's `provenance.sourceRef`. Defaults to `render.sourceRef` when the
+   * caller omits it — the render already carries this when known; no
+   * `provenance` is recorded when neither supplies one.
+   */
+  sourceRef?: string;
+}
+
+export interface AddArchiveHelmRenderOutput {
+  /** The render's content digest — `render.contentDigest`, unchanged; returned for symmetry with `addArchiveTemplate`'s output. */
+  digest: string;
+  /** The build archive's manifest, now including this render's entry. */
+  manifest: BuildArchiveManifest;
+}
+
+/**
+ * Fold one pinned render into a build archive's manifest as a
+ * `template`-kind entry with `mediaType: HELM_RENDER_MEDIA_TYPE` — the
+ * render peer of `addArchiveTemplate`. The entry's digest is the render's
+ * own `contentDigest` (real `sha256:` over the canonical rendered stream,
+ * ./render-digest.ts's `helmContentDigest`), so the same digest that keys
+ * the render store's `sha256-<hex>/` entry (./render-store.ts) also keys
+ * this archive entry — one identity, not a second hash of the same bytes.
+ * Adding the entry recomputes `manifest.manifestDigest`
+ * (`computeManifestDigest`), so the render rolls into the archive's own
+ * aggregate identity exactly as an image or template does.
+ */
+export function addArchiveHelmRender(input: AddArchiveHelmRenderInput): AddArchiveHelmRenderOutput {
+  const digest = input.render.contentDigest;
+  const base = input.manifest ?? createBuildArchiveManifest("unknown");
+  const sourceRef = input.sourceRef ?? input.render.sourceRef ?? undefined;
+  const provenance: ProvenanceLink | undefined = sourceRef
+    ? { sourceRef, artifactDigest: digest }
+    : undefined;
+  const manifest = addArchiveEntry(base, {
+    kind: "template",
+    path: input.path,
+    digest,
+    mediaType: HELM_RENDER_MEDIA_TYPE,
+    ...(provenance ? { provenance } : {}),
+  });
+  return { digest, manifest };
+}