@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/src/lifecycle-integration.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Cross-lexicon lifecycle integration — Helm row (#1246/#1247, epic #1228).
+ *
+ * Drives the REAL helmPlugin through core's live-diff and change-set paths,
+ * with the helm CLI faked at the PATH edge: a scripted `helm` shell double
+ * answers `list`, `get manifest` and `get hooks` from canned fixtures, so the
+ * plugin's own exec conventions (the same `helm …` command strings production
+ * runs) are what execute. The deep path is exercised through the same release
+ * plumbing with the k8s lexicon's fake cluster at the API edge — the seam the
+ * k8s lexicon's own integration test replaces.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { helmPlugin } from "./plugin";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { buildChangeSet } from "@intentius/chant/lifecycle/change-set";
+import { diffLive } from "@intentius/chant/lifecycle/live-diff";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { describeResources } from "./describe-resources";
+import type { HelmRunner } from "./release-observe";
+
+const LIST = JSON.stringify([
+  {
+    name: "web-app",
+    namespace: "prod",
+    revision: "3",
+    updated: "2026-08-01 10:00:00.000000000 +0000 UTC",
+    status: "deployed",
+    chart: "web-app-0.1.0",
+    app_version: "1.0.0",
+  },
+]);
+
+const MANIFEST = `---
+# Source: web-app/templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-app
+spec:
+  replicas: 2
+---
+# Source: web-app/templates/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web-app
+spec:
+  ports:
+    - port: 80
+`;
+
+const HOOKS = `---
+# Source: web-app/templates/migrate-job.yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: web-app-migrate
+  annotations:
+    "helm.sh/hook": pre-install
+    "helm.sh/hook-weight": "1"
+`;
+
+/** Write a scripted `helm` CLI double into its own dir and put it on PATH. */
+function installHelmShim(fixtures: { list: string; manifest: string; hooks: string; fail?: string }): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-helm-shim-"));
+  writeFileSync(join(dir, "list.json"), fixtures.list);
+  writeFileSync(join(dir, "manifest.yaml"), fixtures.manifest);
+  writeFileSync(join(dir, "hooks.yaml"), fixtures.hooks);
+  const script = `#!/bin/sh
+DIR="$(cd "$(dirname "$0")" && pwd)"
+${fixtures.fail ? `echo "${fixtures.fail}" >&2; exit 1` : ""}
+if [ "$1" = "list" ]; then cat "$DIR/list.json"; exit 0; fi
+if [ "$1" = "get" ] && [ "$2" = "manifest" ]; then cat "$DIR/manifest.yaml"; exit 0; fi
+if [ "$1" = "get" ] && [ "$2" = "hooks" ]; then cat "$DIR/hooks.yaml"; exit 0; fi
+echo "helm shim: unexpected args: $*" >&2
+exit 1
+`;
+  writeFileSync(join(dir, "helm"), script);
+  chmodSync(join(dir, "helm"), 0o755);
+  return dir;
+}
+
+const entities = new Map([
+  ["chart", { entityType: "Helm::Chart", props: { name: "web-app" } }],
+  ["valuesSchema", { entityType: "Helm::Values", props: { replicaCount: 2 } }],
+]);
+const declared = new Set(entities.keys());
+const baseOptions = {
+  environment: "prod",
+  buildOutput: "",
+  entityNames: [...entities.keys()],
+  entities,
+};
+
+describe("helm lifecycle integration (#1246/#1247)", () => {
+  const originalPath = process.env.PATH;
+  let shimDirs: string[] = [];
+
+  const useShim = (fixtures: Parameters<typeof installHelmShim>[0]): void => {
+    const dir = installHelmShim(fixtures);
+    shimDirs.push(dir);
+    process.env.PATH = `${dir}:${originalPath}`;
+  };
+
+  beforeEach(() => {
+    shimDirs = [];
+  });
+
+  afterEach(() => {
+    process.env.PATH = originalPath;
+    for (const dir of shimDirs) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("lifecycle diff --live gains helm rows: real plugin, scripted helm CLI, both channels", async () => {
+    useShim({ list: LIST, manifest: MANIFEST, hooks: HOOKS });
+
+    const observed = normalizeObservation(await helmPlugin.describeResources!(baseOptions));
+
+    // The release row and the per-resource rows, hook resource included —
+    // the row `helm get manifest` alone can never produce.
+    expect(observed.resources.chart).toMatchObject({ type: "Helm::Release", status: "deployed" });
+    expect(observed.resources["Deployment/prod/web-app"]).toBeDefined();
+    expect(observed.resources["Service/prod/web-app"]).toBeDefined();
+    expect(observed.resources["Job/prod/web-app-migrate"]).toMatchObject({
+      attributes: expect.objectContaining({ channel: "hooks", hook: "pre-install" }),
+    });
+
+    const diff = diffLive({ declared, observedNow: observed.resources, observedThen: undefined, unobserved: observed.unobserved });
+    // Nothing declared is missing, and the rendered resources are expected
+    // runtime — an unpinned release is not reported as drift (#1246).
+    expect(diff.missing).toEqual([]);
+    expect(diff.orphan).toEqual([]);
+    expect(diff.runtimeChildren.map((r) => r.name).sort()).toEqual([
+      "Deployment/prod/web-app",
+      "Job/prod/web-app-migrate",
+      "Service/prod/web-app",
+    ]);
+    expect(diff.runtimeChildren.every((r) => r.owner === "chart")).toBe(true);
+  });
+
+  test("change-set verdicts: present chart is noop, rendered resources are runtime, absent chart is create", async () => {
+    useShim({ list: LIST, manifest: MANIFEST, hooks: HOOKS });
+    const observed = normalizeObservation(await helmPlugin.describeResources!(baseOptions));
+    const cs = buildChangeSet("prod", {
+      declared,
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e.action]));
+    expect(byName.chart).toBe("noop");
+    expect(byName.valuesSchema).toBe("noop");
+    expect(byName["Deployment/prod/web-app"]).toBe("runtime");
+    expect(byName["Job/prod/web-app-migrate"]).toBe("runtime");
+  });
+
+  test("a failing helm CLI is unobserved for every declared entity — never N creates", async () => {
+    useShim({ list: "[]", manifest: "", hooks: "", fail: "Error: Kubernetes cluster unreachable" });
+    const observed = normalizeObservation(await helmPlugin.describeResources!(baseOptions));
+    expect(observed.resources).toEqual({});
+    expect(observed.unobserved.chart.reason).toBe("no-credentials");
+
+    const cs = buildChangeSet("prod", {
+      declared,
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    for (const entry of cs.entries) expect(entry.action).toBe("unobserved");
+  });
+
+  test("a missing helm binary is no-credentials, never a clean empty snapshot", async () => {
+    const empty = mkdtempSync(join(tmpdir(), "chant-helm-nopath-"));
+    shimDirs.push(empty);
+    process.env.PATH = empty; // /bin/sh is exec'd absolutely; only `helm` resolution uses PATH
+    const observed = normalizeObservation(await helmPlugin.describeResources!(baseOptions));
+    expect(observed.resources).toEqual({});
+    expect(observed.unobserved.chart.reason).toBe("no-credentials");
+    expect(observed.unobserved.valuesSchema.reason).toBe("no-credentials");
+  });
+
+  test("the deep hook is declared and shares the k8s lexicon's normalization hooks (#1247)", async () => {
+    expect(typeof helmPlugin.observeResourcesDeep).toBe("function");
+    const { k8sDeepNormalizationHooks } = await import("@intentius/chant-lexicon-k8s/deep-observe-hooks");
+    expect(helmPlugin.deepNormalizationHooks).toBe(k8sDeepNormalizationHooks);
+  });
+});
+
+// The shared conformance suite (#1089) — every observing lexicon runs it.
+// Scenarios drive the same describeResources the plugin dispatches to, with
+// the CLI seam injected per scenario.
+const scripted = (outputs: { list?: string; manifest?: string; hooks?: string; throwWith?: Error }): HelmRunner =>
+  async (command) => {
+    if (outputs.throwWith) throw outputs.throwWith;
+    if (command.startsWith("helm list")) return { stdout: outputs.list ?? "[]" };
+    if (command.startsWith("helm get manifest")) return { stdout: outputs.manifest ?? "" };
+    if (command.startsWith("helm get hooks")) return { stdout: outputs.hooks ?? "" };
+    throw new Error(`unexpected command: ${command}`);
+  };
+
+const conformanceEntities = new Map([["chart", { entityType: "Helm::Chart", props: { name: "web-app" } }]]);
+const conformanceOptions = {
+  environment: "prod",
+  buildOutput: "",
+  entityNames: ["chart"],
+  entities: conformanceEntities,
+};
+
+const MARKED_MANIFEST = `---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: web-app-config
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: shop
+    chant.intentius.io/env: prod
+data:
+  key: value
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: unmarked-config
+data:
+  key: value
+`;
+
+describeObservationConformance({
+  lexicon: "helm",
+  ownershipChannel: helmPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "a healthy release read, both channels",
+      declared: ["chart"],
+      expectPresent: ["chart"],
+      run: () => describeResources(conformanceOptions, scripted({ list: LIST, manifest: MANIFEST, hooks: HOOKS })),
+    },
+    {
+      name: "helm binary missing alongside nothing else readable",
+      declared: ["chart"],
+      expectUnobserved: ["chart"],
+      run: () =>
+        describeResources(
+          conformanceOptions,
+          scripted({ throwWith: Object.assign(new Error("helm: command not found"), { code: 127 }) }),
+        ),
+    },
+    {
+      name: "an unreachable release (list succeeds, get fails)",
+      declared: ["chart"],
+      expectUnobserved: ["chart"],
+      run: () =>
+        describeResources(conformanceOptions, async (command) => {
+          if (command.startsWith("helm list")) return { stdout: LIST };
+          throw new Error("Error: release: not found");
+        }),
+    },
+    {
+      name: "a release helm was asked about and did not report",
+      declared: ["chart"],
+      expectAbsent: ["chart"],
+      run: () => describeResources(conformanceOptions, scripted({ list: "[]" })),
+    },
+    {
+      name: "an owned read resolves real verdicts — release identity is the marker",
+      declared: ["chart"],
+      expectPresent: ["chart"],
+      owned: true,
+      run: () =>
+        describeResources(
+          { ...conformanceOptions, owned: true },
+          scripted({ list: LIST, manifest: MANIFEST, hooks: HOOKS }),
+        ),
+    },
+    {
+      name: "a marker-stamped rendered document surfaces its stack/env identity; an unmarked one surfaces none (#1222)",
+      declared: ["chart"],
+      expectPresent: ["chart", "ConfigMap/prod/web-app-config", "ConfigMap/prod/unmarked-config"],
+      expectMarker: { "ConfigMap/prod/web-app-config": { stack: "shop", env: "prod" } },
+      expectNoMarker: ["ConfigMap/prod/unmarked-config"],
+      run: () => describeResources(conformanceOptions, scripted({ list: LIST, manifest: MARKED_MANIFEST, hooks: "" })),
+    },
+  ],
+});

package/src/lint/audit-catalog.ts

@@ -26,4 +26,6 @@ export const helmAuditCatalog: Record<string, RuleMeta> = {
   WHM407: auditRule("WHM407", "merge-worthy", "guidance", "Inline Secret data", "Use ExternalSecret/SealedSecret instead of inline Secret data.", { authority: [K8S_SECRETS] }),
   WHM501: auditRule("WHM501", "report-only", "guidance", "Unused values key", "Remove values defined but never referenced.", { category: "best-practice" }),
   WHM502: auditRule("WHM502", "merge-worthy", "guidance", "Deprecated/invalid Kubernetes API version", "Update to a supported apiVersion.", { category: "correctness" }),
+  WHM503: auditRule("WHM503", "merge-worthy", "guidance", "Pinned render carries Secret data", "Declare the value with runtimeSlot() or replace the Secret with HelmExternalSecret.", { authority: [K8S_SECRETS] }),
+  WHM504: auditRule("WHM504", "merge-worthy", "guidance", "Dead value assignment", "Remove supplied values that never survive coalescing (shadowed, disabled subchart, or unknown subchart).", { category: "correctness" }),
 };

package/src/lint/post-synth/index.ts

@@ -21,6 +21,8 @@ import { whm406 } from "./whm406";
 import { whm407 } from "./whm407";
 import { whm501 } from "./whm501";
 import { whm502 } from "./whm502";
+import { whm503 } from "./whm503";
+import { whm504 } from "./whm504";
 
 export const postSynthChecks: PostSynthCheck[] = [
   whm005,
@@ -44,4 +46,6 @@ export const postSynthChecks: PostSynthCheck[] = [
   whm407,
   whm501,
   whm502,
+  whm503,
+  whm504,
 ];

package/src/lint/post-synth/whm503.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { HelmCapabilityProfile } from "../../config";
+import type { HelmRenderRecord } from "../../render";
+import { persistHelmRender } from "../../render-store";
+import { checkRenderRecordsForSecrets, whm503 } from "./whm503";
+
+const PROFILE: HelmCapabilityProfile = {
+  name: "prod",
+  kubeVersion: "1.33.6",
+  apiVersions: ["batch/v1"],
+};
+
+function freshRoot(): string {
+  return mkdtempSync(join(tmpdir(), "chant-whm503-"));
+}
+
+/** A `helm template`-shaped stream with one Secret document, `data` swapped by caller. */
+function renderedWith(secretBody: string): string {
+  return [
+    "---",
+    "# Source: tiny/templates/serviceaccount.yaml",
+    "kind: ServiceAccount",
+    "apiVersion: v1",
+    "metadata:",
+    "  name: tiny-sa",
+    "---",
+    "# Source: tiny/templates/secret.yaml",
+    "apiVersion: v1",
+    "kind: Secret",
+    "metadata:",
+    "  name: tiny-secret",
+    "  namespace: web",
+    secretBody,
+    "",
+  ].join("\n");
+}
+
+function persist(root: string, rendered: string, name = "rel") {
+  return persistHelmRender({
+    rendered,
+    releaseName: name,
+    chart: "tiny",
+    namespace: "web",
+    capabilityProfile: PROFILE,
+    root,
+  });
+}
+
+describe("WHM503: pinned render carries Secret data", () => {
+  test("flags a Secret with populated data", () => {
+    const root = freshRoot();
+    const { manifest } = persist(root, renderedWith("data:\n  password: c2VjcmV0"));
+    const records: HelmRenderRecord[] = [{ name: "rel", chart: "tiny", contentDigest: manifest.contentDigest }];
+
+    const diags = checkRenderRecordsForSecrets(records, { root });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WHM503");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("web/tiny-secret");
+    expect(diags[0].message).toContain("runtimeSlot()");
+    expect(diags[0].message).toContain("HelmExternalSecret");
+    expect(diags[0].entity).toBe("web/tiny-secret");
+  });
+
+  test("flags a Secret with populated stringData", () => {
+    const root = freshRoot();
+    const { manifest } = persist(root, renderedWith("stringData:\n  token: hunter2"));
+    const records: HelmRenderRecord[] = [{ name: "rel", chart: "tiny", contentDigest: manifest.contentDigest }];
+
+    const diags = checkRenderRecordsForSecrets(records, { root });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("web/tiny-secret");
+  });
+
+  test("passes when the Secret's data is empty", () => {
+    const root = freshRoot();
+    const { manifest } = persist(root, renderedWith("data: {}"));
+    const records: HelmRenderRecord[] = [{ name: "rel", chart: "tiny", contentDigest: manifest.contentDigest }];
+
+    expect(checkRenderRecordsForSecrets(records, { root })).toHaveLength(0);
+  });
+
+  test("passes when the render carries no Secret documents", () => {
+    const root = freshRoot();
+    const rendered = [
+      "---",
+      "# Source: tiny/templates/serviceaccount.yaml",
+      "kind: ServiceAccount",
+      "apiVersion: v1",
+      "metadata:",
+      "  name: tiny-sa",
+      "",
+    ].join("\n");
+    const { manifest } = persist(root, rendered);
+    const records: HelmRenderRecord[] = [{ name: "rel", chart: "tiny", contentDigest: manifest.contentDigest }];
+
+    expect(checkRenderRecordsForSecrets(records, { root })).toHaveLength(0);
+  });
+
+  test("skips unpinned records (no contentDigest)", () => {
+    const root = freshRoot();
+    const records: HelmRenderRecord[] = [{ name: "rel", chart: "tiny" }];
+    expect(checkRenderRecordsForSecrets(records, { root })).toHaveLength(0);
+  });
+
+  test("skips a record whose digest is not in the store", () => {
+    const root = freshRoot();
+    const records: HelmRenderRecord[] = [
+      { name: "rel", chart: "tiny", contentDigest: "sha256:" + "0".repeat(64) },
+    ];
+    expect(checkRenderRecordsForSecrets(records, { root })).toHaveLength(0);
+  });
+
+  test("flags every offending Secret across multiple pinned renders", () => {
+    const root = freshRoot();
+    const first = persist(root, renderedWith("data:\n  password: c2VjcmV0"), "rel-a");
+    const second = persist(root, renderedWith("data:\n  password: b3RoZXI="), "rel-b");
+    const records: HelmRenderRecord[] = [
+      { name: "rel-a", chart: "tiny", contentDigest: first.manifest.contentDigest },
+      { name: "rel-b", chart: "tiny", contentDigest: second.manifest.contentDigest },
+    ];
+
+    expect(checkRenderRecordsForSecrets(records, { root })).toHaveLength(2);
+  });
+
+  test("the PostSynthCheck wrapper carries the WHM503 id and description", () => {
+    expect(whm503.id).toBe("WHM503");
+    expect(whm503.description).toContain("Secret");
+  });
+});

package/src/lint/post-synth/whm503.ts

@@ -0,0 +1,101 @@
+/**
+ * WHM503: Pinned render artifact carries Secret data.
+ *
+ * WHM407 covers the pre-render concern — a chart TEMPLATE with an inline,
+ * literal `data`/`stringData` value baked into `templates/`. This rule
+ * covers a different concern (#1241, epic #1228 Phase 3): the STORED,
+ * POST-RENDER artifact (`render-store.ts`, #1238). A pinned render is
+ * durable, promoted, and pushed to a registry — unlike a normal `helm
+ * upgrade`, whose rendered bytes are computed at deploy time and discarded.
+ * By the time a render lands in the store, every `.Values` reference and
+ * `{{ }}` expression is resolved, so a `kind: Secret` document with
+ * populated `data`/`stringData` there is a live credential baked into
+ * something that outlives the deploy that produced it.
+ *
+ * Scans every pinned render recorded so far in this process
+ * (`getHelmRenderRecords()` from `../../render`) that carries a
+ * `contentDigest`, loads its manifest + canonical content from the render
+ * store, and flags any `Secret` document whose `data` or `stringData` is
+ * non-empty.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import yaml from "js-yaml";
+
+import type { HelmRenderRecord } from "../../render";
+import { getHelmRenderRecords } from "../../render";
+import { loadRenderManifest, readRenderDocument } from "../../render-store";
+
+interface ParsedSecretDoc {
+  data?: unknown;
+  stringData?: unknown;
+}
+
+/** True when a `data`/`stringData` map carries at least one key. */
+function isPopulated(value: unknown): boolean {
+  return typeof value === "object" && value !== null && Object.keys(value).length > 0;
+}
+
+/**
+ * Scan a set of `HelmRenderRecord`s for pinned renders whose stored artifact
+ * carries a `Secret` document with populated `data`/`stringData`. Exported
+ * separately from `whm503` so tests can drive it directly with hand-built
+ * records — no real `helm` binary required, unlike a `HelmRender()` call.
+ * `opts.root` overrides the render store root (test isolation).
+ */
+export function checkRenderRecordsForSecrets(
+  records: readonly HelmRenderRecord[],
+  opts?: { root?: string },
+): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const record of records) {
+    if (!record.contentDigest) continue; // unpinned — no stored artifact to scan
+
+    const manifest = loadRenderManifest(record.contentDigest, opts);
+    if (!manifest) continue; // recorded but not (or no longer) in the store
+
+    for (const doc of manifest.documents) {
+      if (doc.kind !== "Secret") continue;
+
+      const found = readRenderDocument(record.contentDigest, { kind: doc.kind, name: doc.name, namespace: doc.namespace }, opts);
+      if (!found) continue;
+
+      let parsed: ParsedSecretDoc;
+      try {
+        parsed = (yaml.load(found.text) ?? {}) as ParsedSecretDoc;
+      } catch {
+        continue; // unparseable — not this check's problem to diagnose
+      }
+
+      if (!isPopulated(parsed.data) && !isPopulated(parsed.stringData)) continue;
+
+      const locator = doc.namespace ? `${doc.namespace}/${doc.name}` : doc.name;
+      diagnostics.push({
+        checkId: "WHM503",
+        severity: "error",
+        message:
+          `pinned render "${record.name}" (${record.chart}, ${record.contentDigest}): Secret "${locator}" ` +
+          `carries populated data/stringData — a pinned render is stored, promoted, and pushed to a registry, ` +
+          `so this bakes a live credential into a durable artifact. Declare the value with runtimeSlot() so ` +
+          `it is supplied per environment, or replace this Secret with HelmExternalSecret.`,
+        entity: locator,
+        lexicon: "helm",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const whm503: PostSynthCheck = {
+  id: "WHM503",
+  description: "Pinned render artifact must not carry populated Secret data/stringData",
+
+  // This check's data source is the render store (#1238), not `ctx.outputs`
+  // (the un-rendered chart template files WHM005-WHM502 read) — see the file
+  // doc comment. `ctx` is accepted to satisfy `PostSynthCheck` and is unused.
+  check(_ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkRenderRecordsForSecrets(getHelmRenderRecords());
+  },
+};

package/src/lint/post-synth/whm504.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { whm504 } from "./whm504";
+import {
+  clearValuesProbeRecords,
+  recordValuesProbe,
+  type CoalescedValuesProbe,
+  type DeadAssignment,
+} from "../../values-probe";
+
+function makeCtx(): PostSynthContext {
+  const outputs = new Map<string, string>();
+  return {
+    outputs,
+    entities: new Map(),
+    buildResult: {
+      outputs,
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+function probeWith(deadAssignments: DeadAssignment[]): CoalescedValuesProbe {
+  return {
+    instances: [{ scope: [], chartName: "app", values: {} }],
+    disabled: [],
+    digest: "sha256:" + "0".repeat(64),
+    valueSources: {},
+    deadAssignments,
+    warnings: [],
+  };
+}
+
+describe("WHM504: dead value assignments", () => {
+  beforeEach(() => {
+    clearValuesProbeRecords();
+  });
+
+  test("no probe records, no diagnostics", () => {
+    expect(whm504.check(makeCtx())).toEqual([]);
+  });
+
+  test("a probe with no dead assignments passes", () => {
+    recordValuesProbe({ name: "app", chartDir: "/tmp/app", probe: probeWith([]) });
+    expect(whm504.check(makeCtx())).toEqual([]);
+  });
+
+  test("one warning per dead assignment, naming path, origin, and what shadowed it", () => {
+    recordValuesProbe({
+      name: "app",
+      chartDir: "/tmp/app",
+      probe: probeWith([
+        {
+          path: "web.tag",
+          origin: "supplied file (values-prod.yaml)",
+          reason: "shadowed",
+          shadowedBy: "--set",
+        },
+        {
+          path: "opt.size",
+          origin: "supplied file (values-prod.yaml)",
+          reason: "disabled-subchart",
+          shadowedBy: "disabled subchart opt (condition opt.enabled is false)",
+        },
+        {
+          path: "wbe",
+          origin: "supplied file (values-prod.yaml)",
+          reason: "unknown-subchart",
+          shadowedBy: 'no dependency, chart default, or global named "wbe"',
+        },
+      ]),
+    });
+    const diags = whm504.check(makeCtx());
+    expect(diags).toHaveLength(3);
+    for (const d of diags) {
+      expect(d.checkId).toBe("WHM504");
+      expect(d.severity).toBe("warning");
+      expect(d.entity).toBe("app");
+      expect(d.lexicon).toBe("helm");
+      expect(d.message).toContain("supplied file (values-prod.yaml)");
+    }
+    expect(diags[0].message).toContain('"web.tag"');
+    expect(diags[0].message).toContain("shadowed by --set");
+    expect(diags[1].message).toContain("disabled subchart opt (condition opt.enabled is false)");
+    expect(diags[2].message).toContain('no dependency, chart default, or global named "wbe"');
+  });
+
+  test("reports across multiple probe records", () => {
+    recordValuesProbe({
+      name: "app-a",
+      chartDir: "/tmp/a",
+      probe: probeWith([{ path: "x", origin: "--set", reason: "shadowed", shadowedBy: "--set" }]),
+    });
+    recordValuesProbe({
+      name: "app-b",
+      chartDir: "/tmp/b",
+      probe: probeWith([{ path: "y", origin: "supplied file", reason: "shadowed", shadowedBy: "--set" }]),
+    });
+    const diags = whm504.check(makeCtx());
+    expect(diags.map((d) => d.entity)).toEqual(["app-a", "app-b"]);
+  });
+});