@intentius/chant-lexicon-helm 0.45.0 → 0.49.0

package/src/render-wrapper.test.ts

@@ -0,0 +1,259 @@
+import { describe, test, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { canonicalizeRender } from "./render-digest";
+import { persistHelmRender } from "./render-store";
+import { routeRender, routeStoredRender, type RoutedRender } from "./render-wrapper";
+import { splitDocuments } from "./pinnability/render-stream";
+
+const FIXTURES = join(import.meta.dirname, "..", "test", "survey", "fixtures");
+
+function helmAvailable(): boolean {
+  try {
+    execFileSync("helm", ["version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasHelm = helmAvailable();
+
+function renderFixture(chartDir: string): string {
+  return execFileSync(
+    "helm",
+    ["template", "rel", chartDir, "--include-crds", "--kube-version", "1.33.6"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 },
+  );
+}
+
+/** Every routed document must be byte-identical to a document of the input stream. */
+function expectByteIdentity(routed: RoutedRender, input: string): void {
+  const inputDocs = splitDocuments(input);
+  for (const doc of [...routed.crds, ...routed.hooks, ...routed.main]) {
+    expect(inputDocs).toContain(doc.text);
+  }
+}
+
+function allRoutedTexts(routed: RoutedRender): string[] {
+  return [...routed.crds, ...routed.hooks, ...routed.main].map((d) => d.text);
+}
+
+// ── pure routing over literal streams ─────────────────────────────────────
+
+const crdDoc = (source: string, name: string, kind: string) =>
+  [
+    `# Source: umb/${source}`,
+    "apiVersion: apiextensions.k8s.io/v1",
+    "kind: CustomResourceDefinition",
+    "metadata:",
+    `  name: ${name}`,
+    "spec:",
+    "  group: example.com",
+    "  names:",
+    `    kind: ${kind}`,
+  ].join("\n");
+
+describe("routeRender", () => {
+  test("routes by crds/ segment, hook annotation, and default main; inherits chart identity", () => {
+    const stream = [
+      "---",
+      crdDoc("crds/parentcrd.yaml", "parentthings.example.com", "ParentThing"),
+      "---",
+      crdDoc("charts/kid/crds/kidcrd.yaml", "kidthings.example.com", "KidThing"),
+      "---",
+      "# Source: umb/templates/hook-job.yaml",
+      "apiVersion: batch/v1",
+      "kind: Job",
+      "metadata:",
+      "  name: setup",
+      "  annotations:",
+      '    "helm.sh/hook": pre-install',
+      "---",
+      "# Source: umb/templates/cm.yaml",
+      "apiVersion: v1",
+      "kind: ConfigMap",
+      "metadata:",
+      "  name: cm",
+    ].join("\n");
+    const routed = routeRender(stream, { chart: "umb", chartVersion: "0.1.0" });
+
+    expect(routed.chart).toBe("umb");
+    expect(routed.chartVersion).toBe("0.1.0");
+    expect(routed.crds.map((d) => d.source)).toEqual([
+      "crds/parentcrd.yaml",
+      "charts/kid/crds/kidcrd.yaml", // segment rule: a prefix match would miss this one
+    ]);
+    expect(routed.hooks.map((d) => d.kind)).toEqual(["Job"]);
+    expect(routed.main.map((d) => d.kind)).toEqual(["ConfigMap"]);
+    expect(routed.warnings).toEqual([]);
+    expectByteIdentity(routed, stream);
+  });
+
+  test("deduplicates aliased-dependency CRDs by (group, kind): first wins, warning names both sources", () => {
+    const stream = [
+      "---",
+      crdDoc("charts/kid/crds/kidcrd.yaml", "kidthings.example.com", "KidThing"),
+      "---",
+      crdDoc("charts/kidtwo/crds/kidcrd.yaml", "kidthings.example.com", "KidThing"),
+    ].join("\n");
+    const routed = routeRender(stream, { chart: "umb" });
+
+    expect(routed.crds).toHaveLength(1);
+    expect(routed.crds[0].source).toBe("charts/kid/crds/kidcrd.yaml");
+    expect(routed.warnings).toHaveLength(1);
+    expect(routed.warnings[0].code).toBe("duplicate-crd");
+    expect(routed.warnings[0].message).toContain("charts/kid/crds/kidcrd.yaml");
+    expect(routed.warnings[0].message).toContain("charts/kidtwo/crds/kidcrd.yaml");
+    expect(routed.warnings[0].message).toContain("example.com/KidThing");
+  });
+
+  test("distinct (group, kind) CRDs are never deduplicated", () => {
+    const stream = [
+      "---",
+      crdDoc("crds/a.yaml", "parentthings.example.com", "ParentThing"),
+      "---",
+      crdDoc("charts/kid/crds/b.yaml", "kidthings.example.com", "KidThing"),
+    ].join("\n");
+    const routed = routeRender(stream, { chart: "umb" });
+    expect(routed.crds).toHaveLength(2);
+    expect(routed.warnings).toEqual([]);
+  });
+
+  test("a crds/ document routing cannot identify is kept, never deduplicated", () => {
+    // Missing spec.names.kind — no (group, kind) key, so both survive.
+    const doc = [
+      "# Source: umb/crds/odd.yaml",
+      "apiVersion: apiextensions.k8s.io/v1",
+      "kind: CustomResourceDefinition",
+      "metadata:",
+      "  name: oddthings.example.com",
+    ].join("\n");
+    const routed = routeRender(["---", doc, "---", doc].join("\n"), { chart: "umb" });
+    expect(routed.crds).toHaveLength(2);
+    expect(routed.warnings).toEqual([]);
+  });
+
+  test("template-rendered CRD stays in main per the segment rule, with a note", () => {
+    const stream = [
+      "---",
+      "# Source: umb/templates/crd.yaml",
+      "apiVersion: apiextensions.k8s.io/v1",
+      "kind: CustomResourceDefinition",
+      "metadata:",
+      "  name: templated.example.com",
+      "spec:",
+      "  group: example.com",
+      "  names:",
+      "    kind: Templated",
+    ].join("\n");
+    const routed = routeRender(stream, { chart: "umb" });
+
+    expect(routed.crds).toEqual([]);
+    expect(routed.main).toHaveLength(1);
+    expect(routed.main[0].kind).toBe("CustomResourceDefinition");
+    expect(routed.warnings).toHaveLength(1);
+    expect(routed.warnings[0].code).toBe("template-crd");
+    expect(routed.warnings[0].message).toContain("templated.example.com");
+    expect(routed.warnings[0].message).toContain("templates/crd.yaml");
+  });
+
+  test("unparseable and source-less documents route to main verbatim", () => {
+    const stream = [
+      "---",
+      "not: [valid: yaml",
+      "---",
+      "apiVersion: v1",
+      "kind: ConfigMap",
+      "metadata:",
+      "  name: bare",
+    ].join("\n");
+    const routed = routeRender(stream, { chart: "umb" });
+    expect(routed.main).toHaveLength(2);
+    expect(routed.main[0]).toMatchObject({ source: null, kind: null, name: null });
+    expect(routed.main[1]).toMatchObject({ source: null, kind: "ConfigMap", name: "bare" });
+    expectByteIdentity(routed, stream);
+  });
+});
+
+// ── fixture routing (helm on PATH, offline) ───────────────────────────────
+
+describe.skipIf(!hasHelm)("routeRender over rendered fixtures", () => {
+  test("umbrella fixture: groups correct, aliased duplicate deduped with both sources named, bytes identical", () => {
+    const canonical = canonicalizeRender(renderFixture(join(FIXTURES, "umbrella-fixture")));
+    const routed = routeRender(canonical, { chart: "umbrella-fixture", chartVersion: "0.1.0" });
+
+    // 3 CRD documents rendered (parent + kid + kidtwo), 2 distinct CRDs kept.
+    expect(routed.crds.map((d) => d.name).sort()).toEqual([
+      "kidthings.example.com",
+      "parentthings.example.com",
+    ]);
+    expect(routed.crds.map((d) => d.source)).toContain("crds/parentcrd.yaml");
+    expect(routed.hooks).toEqual([]);
+    // Parent cm + kid cm + kidtwo cm (opt is disabled by default).
+    expect(routed.main.map((d) => d.kind)).toEqual(["ConfigMap", "ConfigMap", "ConfigMap"]);
+
+    expect(routed.warnings).toHaveLength(1);
+    expect(routed.warnings[0].code).toBe("duplicate-crd");
+    expect(routed.warnings[0].message).toContain("charts/kid/crds/kidcrd.yaml");
+    expect(routed.warnings[0].message).toContain("charts/kidtwo/crds/kidcrd.yaml");
+
+    // Structure preservation: every routed document is byte-identical to a
+    // canonical input document, and the groups partition the input minus
+    // exactly the one deduplicated duplicate.
+    expectByteIdentity(routed, canonical);
+    const inputDocs = splitDocuments(canonical);
+    expect(allRoutedTexts(routed)).toHaveLength(inputDocs.length - 1);
+
+    // Wrapper inherits the source chart's identity (epic Decisions).
+    expect(routed.chart).toBe("umbrella-fixture");
+    expect(routed.chartVersion).toBe("0.1.0");
+  });
+
+  test("hook fixture: hook-annotated Job routes to its own group, annotations intact", () => {
+    const canonical = canonicalizeRender(renderFixture(join(FIXTURES, "hook-fixture")));
+    const routed = routeRender(canonical, { chart: "hook-fixture", chartVersion: "0.1.0" });
+
+    expect(routed.hooks).toHaveLength(1);
+    expect(routed.hooks[0].kind).toBe("Job");
+    expect(routed.hooks[0].text).toContain("helm.sh/hook");
+    expect(routed.hooks[0].text).toContain("pre-install");
+    expect(routed.hooks[0].text).toContain("helm.sh/hook-delete-policy");
+    expect(routed.crds).toEqual([]);
+    expect(routed.main.map((d) => d.kind)).toEqual(["ConfigMap"]);
+    expect(routed.warnings).toEqual([]);
+    expectByteIdentity(routed, canonical);
+  });
+
+  test("routeStoredRender routes a stored render by contentDigest, inheriting the manifest's chart identity", () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-render-wrapper-"));
+    const rendered = renderFixture(join(FIXTURES, "umbrella-fixture"));
+    const { manifest } = persistHelmRender({
+      rendered,
+      releaseName: "rel",
+      chart: "umbrella-fixture",
+      chartVersion: "0.1.0",
+      capabilityProfile: { name: "test", kubeVersion: "1.33.6", apiVersions: [] },
+      root,
+    });
+
+    const routed = routeStoredRender(manifest.contentDigest, { root });
+    expect(routed).toBeDefined();
+    expect(routed?.chart).toBe("umbrella-fixture");
+    expect(routed?.chartVersion).toBe("0.1.0");
+    expect(routed?.crds.map((d) => d.name).sort()).toEqual([
+      "kidthings.example.com",
+      "parentthings.example.com",
+    ]);
+    // The routed bytes are the stored bytes: identical to routing the
+    // canonical stream directly.
+    expect(routed).toEqual(
+      routeRender(canonicalizeRender(rendered), { chart: "umbrella-fixture", chartVersion: "0.1.0" }),
+    );
+
+    expect(routeStoredRender(`sha256:${"0".repeat(64)}`, { root })).toBeUndefined();
+  });
+});

package/src/render-wrapper.ts

@@ -0,0 +1,274 @@
+/**
+ * Structure-preserving render wrapper (#1239, epic #1228 Phase 3).
+ *
+ * Turns a pinned render's document stream into chant-shaped routing groups
+ * WITHOUT restructuring the documents. Structure-preserving means the bytes
+ * that deploy are the bytes the render store recorded — this module only
+ * routes and labels; it never re-serializes, reorders lines, or edits a
+ * document. Each `RoutedDocument.text` is the exact document text from the
+ * input stream.
+ *
+ * Routing is by origin, not by kind. `helm template` stamps every document
+ * with `# Source: <chart>/<path>`, and the discriminator is whether that
+ * path contains a `crds/` **segment** (`(^|/)crds/` — `isCrdSource` from
+ * the #1234 classifier seeds):
+ *
+ * - A `crds/`-segment origin routes to the CRD group — the wrapper's
+ *   `crds/`. Segment matching is load-bearing: a subchart's CRDs arrive as
+ *   `charts/<child>/crds/<file>`, so a prefix rule catches none of them and
+ *   would route every subchart CRD into `templates/`, making it deletable
+ *   on uninstall (epic findings 4, 10 — the A/B test showed a flat wrap
+ *   converts `helm uninstall` from safe to data-destroying).
+ * - A hook-annotated template document (`helm.sh/hook` in
+ *   `metadata.annotations`) routes to its own group, annotations intact.
+ *   Hooks survive pinning (epic finding 5); they are surfaced separately so
+ *   the install path can account for them, never silently dropped.
+ * - Everything else routes to the main group — the wrapper's `templates/`.
+ *   A template-rendered `CustomResourceDefinition` stays here, because the
+ *   `crds/`-segment is the discriminator, not the kind: a chart that
+ *   templates its CRDs opted into template lifecycle semantics (upgrades
+ *   and deletes apply to them), and moving them to `crds/` would change
+ *   that. The routing notes it with a warning so the choice is visible.
+ *
+ * Aliased dependencies emit duplicate CRDs (epic finding 11): the same
+ * dependency included twice under an alias renders its `crds/` once per
+ * instance — two documents, one distinct CRD. The stored artifact keeps
+ * both (canonicalization is order- and duplicate-preserving), but a wrapper
+ * chart's `crds/` holds each CRD once, so the routed CRD group deduplicates
+ * by `(group, kind)`: the first occurrence wins and a warning names both
+ * sources. A CRD document that cannot be identified (unparseable, or
+ * missing `spec.group` / `spec.names.kind`) is never deduplicated — the
+ * routing must not silently drop what it cannot identify.
+ *
+ * The wrapper inherits the source chart's name and version (epic
+ * Decisions), keeping `helm history` continuous across the pinned
+ * migration; `RoutedRender.chart` / `chartVersion` carry them.
+ *
+ * This is the seam the pinned-install path (#1242) consumes:
+ * `routeStoredRender(contentDigest)` loads a stored render's canonical
+ * bytes and manifest and routes them.
+ */
+
+import yaml from "js-yaml";
+
+import { isCrdSource, sourcePath, splitDocuments } from "./pinnability/render-stream";
+import { loadRenderContent, loadRenderManifest } from "./render-store";
+
+// ── routed shapes ─────────────────────────────────────────────────────────
+
+/** One routed document: exact bytes plus the labels routing derived from them. */
+export interface RoutedDocument {
+  /**
+   * The document's exact text from the input stream (from just past the
+   * `---` separator, trimmed of surrounding blank lines — the same split
+   * `splitDocuments` performs). Never re-serialized: what deploys is what
+   * was recorded.
+   */
+  text: string;
+  /**
+   * Chart-relative `# Source:` origin path (e.g. `crds/a.yaml`,
+   * `charts/kid/crds/kidcrd.yaml`), or `null` when the document carries no
+   * source header.
+   */
+  source: string | null;
+  /** Kubernetes kind, or `null` when the document does not parse to a kinded object. */
+  kind: string | null;
+  /** apiVersion as rendered, or `null`. */
+  apiVersion: string | null;
+  /** `metadata.name`, or `null`. */
+  name: string | null;
+}
+
+/** Machine-readable warning categories the routing emits. */
+export type RoutedRenderWarningCode = "duplicate-crd" | "template-crd";
+
+export interface RoutedRenderWarning {
+  /**
+   * - `duplicate-crd` — an aliased dependency emitted the same CRD twice;
+   *   the first occurrence was kept, the duplicate dropped. The message
+   *   names both sources.
+   * - `template-crd` — a `CustomResourceDefinition` was rendered from
+   *   `templates/` (no `crds/` segment in its origin). It stays in the main
+   *   group per the segment rule; this note makes the lifecycle choice
+   *   visible.
+   */
+  code: RoutedRenderWarningCode;
+  message: string;
+}
+
+/**
+ * A pinned render routed into the structure the wrapper chart preserves.
+ * The document groups partition the input stream (minus deduplicated CRD
+ * duplicates, each named in `warnings`); no document is ever silently
+ * dropped and no document text is ever altered.
+ */
+export interface RoutedRender {
+  /**
+   * Wrapper chart name — inherited from the source chart, so `helm history`
+   * stays continuous across the pinned migration (epic Decisions).
+   */
+  chart: string;
+  /** Wrapper chart version — inherited from the source chart; `null` for a local chart rendered without one. */
+  chartVersion: string | null;
+  /**
+   * Documents whose origin has a `crds/` segment — the wrapper's `crds/`,
+   * which is what keeps `helm uninstall` from deleting them (epic finding
+   * 4). Deduplicated by `(group, kind)`, first occurrence winning.
+   */
+  crds: RoutedDocument[];
+  /**
+   * Hook-annotated template documents (`helm.sh/hook`), annotations intact.
+   * Routed as their own group so the install path can account for them —
+   * never silently dropped (epic finding 5).
+   */
+  hooks: RoutedDocument[];
+  /** Everything else — the wrapper's `templates/`. */
+  main: RoutedDocument[];
+  /** What routing had to decide beyond the mechanical rule: dropped duplicates, template-rendered CRDs. */
+  warnings: RoutedRenderWarning[];
+}
+
+// ── routing ───────────────────────────────────────────────────────────────
+
+interface ParsedDoc {
+  kind: string | null;
+  apiVersion: string | null;
+  name: string | null;
+  hook: boolean;
+  crdKey: string | null;
+}
+
+const CRD_KIND = "CustomResourceDefinition";
+
+/**
+ * Parse a document just far enough to label it. Parsing is for labels only —
+ * the routed text is always the original bytes. An unparseable document
+ * labels as `null`s and routes to the main group.
+ */
+function parseForLabels(doc: string): ParsedDoc {
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(doc);
+  } catch {
+    return { kind: null, apiVersion: null, name: null, hook: false, crdKey: null };
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return { kind: null, apiVersion: null, name: null, hook: false, crdKey: null };
+  }
+  const obj = parsed as {
+    kind?: unknown;
+    apiVersion?: unknown;
+    metadata?: { name?: unknown; annotations?: Record<string, unknown> };
+    spec?: { group?: unknown; names?: { kind?: unknown } };
+  };
+  const kind = typeof obj.kind === "string" ? obj.kind : null;
+  const annotations = obj.metadata?.annotations;
+  const hook =
+    annotations !== null &&
+    typeof annotations === "object" &&
+    Object.prototype.hasOwnProperty.call(annotations, "helm.sh/hook");
+  let crdKey: string | null = null;
+  if (kind === CRD_KIND) {
+    const group = obj.spec?.group;
+    const namesKind = obj.spec?.names?.kind;
+    if (typeof group === "string" && typeof namesKind === "string") {
+      crdKey = `${group}/${namesKind}`;
+    }
+  }
+  return {
+    kind,
+    apiVersion: typeof obj.apiVersion === "string" ? obj.apiVersion : null,
+    name: typeof obj.metadata?.name === "string" ? obj.metadata.name : null,
+    hook,
+    crdKey,
+  };
+}
+
+export interface RouteRenderOptions {
+  /** Source chart name — becomes the wrapper's name. */
+  chart: string;
+  /** Source chart version — becomes the wrapper's version. */
+  chartVersion?: string | null;
+}
+
+/**
+ * Route a rendered stream (canonical or raw `helm template` output) into
+ * `RoutedRender` groups. Pure over the stream: no store access, no helm.
+ */
+export function routeRender(rendered: string, opts: RouteRenderOptions): RoutedRender {
+  const routed: RoutedRender = {
+    chart: opts.chart,
+    chartVersion: opts.chartVersion ?? null,
+    crds: [],
+    hooks: [],
+    main: [],
+    warnings: [],
+  };
+  const firstCrdByKey = new Map<string, RoutedDocument>();
+
+  for (const text of splitDocuments(rendered)) {
+    const source = sourcePath(text) ?? null;
+    const labels = parseForLabels(text);
+    const doc: RoutedDocument = {
+      text,
+      source,
+      kind: labels.kind,
+      apiVersion: labels.apiVersion,
+      name: labels.name,
+    };
+
+    if (source !== null && isCrdSource(source)) {
+      if (labels.crdKey !== null) {
+        const first = firstCrdByKey.get(labels.crdKey);
+        if (first) {
+          routed.warnings.push({
+            code: "duplicate-crd",
+            message:
+              `duplicate CRD ${labels.crdKey}: keeping ${first.source ?? "<no source>"}, ` +
+              `dropping ${source} (an aliased dependency emits the same CRD once per instance; ` +
+              `a wrapper chart's crds/ holds it once, matching what helm installs)`,
+          });
+          continue;
+        }
+        firstCrdByKey.set(labels.crdKey, doc);
+      }
+      routed.crds.push(doc);
+      continue;
+    }
+
+    if (labels.kind === CRD_KIND) {
+      // Template-rendered CRD: the crds/-segment is the discriminator, not
+      // the kind. It stays in its rendered group with template lifecycle
+      // semantics — noted, never moved.
+      routed.warnings.push({
+        code: "template-crd",
+        message:
+          `CustomResourceDefinition ${labels.name ?? "<unnamed>"} is template-rendered ` +
+          `(source: ${source ?? "<none>"}), not shipped in crds/ — it stays in the main set ` +
+          `with template lifecycle semantics: helm upgrades and deletes will apply to it`,
+      });
+    }
+
+    (labels.hook ? routed.hooks : routed.main).push(doc);
+  }
+
+  return routed;
+}
+
+/**
+ * Route a stored pinned render by its `contentDigest`: loads the canonical
+ * bytes and the `RenderManifest` from the render store (#1238) and routes
+ * them, inheriting the manifest's chart name and version. This is the seam
+ * the pinned-install path (#1242) consumes. `undefined` when the store has
+ * no such entry.
+ */
+export function routeStoredRender(
+  contentDigest: string,
+  opts?: { root?: string },
+): RoutedRender | undefined {
+  const manifest = loadRenderManifest(contentDigest, opts);
+  if (!manifest) return undefined;
+  const content = loadRenderContent(contentDigest, opts);
+  if (content === undefined) return undefined;
+  return routeRender(content, { chart: manifest.chart, chartVersion: manifest.chartVersion });
+}