@intentius/chant-lexicon-helm 0.0.24 → 0.1.0

package/src/lint/rules/values-no-helm-tpl.ts

@@ -0,0 +1,92 @@
+/**
+ * WHM004: HelmTpl Expression Has No Effect in Values Constructor
+ *
+ * Detects Values constructor props that use `v.xxx` (the `values` proxy)
+ * or any HelmTpl-like expression. values.yaml is static YAML — it is NOT
+ * processed as a Go template by Helm. These expressions silently become ''.
+ *
+ * Bad:  new Values({ host: v.pgHost })
+ * Good: new Values({ host: runtimeSlot("Cloud SQL private IP") })
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const valuesNoHelmTplRule: LintRule = {
+  id: "WHM004",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "HelmTpl expression has no effect in values.yaml — use runtimeSlot() for deploy-time values",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (
+        ts.isNewExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "Values" &&
+        node.arguments &&
+        node.arguments.length > 0
+      ) {
+        const arg = node.arguments[0];
+        if (ts.isObjectLiteralExpression(arg)) {
+          checkObjectLiteral(arg, [], sourceFile, diagnostics);
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};
+
+/**
+ * Get the root identifier name of a property access / call chain.
+ * v.foo → "v"; values.x.pipe("fn") → "values"; runtimeSlot() → "runtimeSlot"
+ */
+function getRootIdentifier(node: ts.Node): string | null {
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node)) return getRootIdentifier(node.expression);
+  if (ts.isCallExpression(node)) return getRootIdentifier(node.expression);
+  return null;
+}
+
+function isHelmTplExpr(node: ts.Node): boolean {
+  const root = getRootIdentifier(node);
+  return root === "v" || root === "values";
+}
+
+function checkObjectLiteral(
+  obj: ts.ObjectLiteralExpression,
+  path: string[],
+  sourceFile: ts.SourceFile,
+  diagnostics: LintDiagnostic[],
+): void {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+
+    const keyName = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+      ? prop.name.text
+      : undefined;
+    const propPath = keyName ? [...path, keyName] : path;
+
+    if (isHelmTplExpr(prop.initializer)) {
+      const { line, character } = sourceFile.getLineAndCharacterOfPosition(prop.getStart());
+      const pathStr = propPath.join(".");
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "WHM004",
+        severity: "warning",
+        message: `HelmTpl expression has no effect in values.yaml (values.yaml is not a Go template). Use runtimeSlot() for deploy-time values or a static default.${pathStr ? ` (path: ${pathStr})` : ""}`,
+      });
+    } else if (ts.isObjectLiteralExpression(prop.initializer)) {
+      checkObjectLiteral(prop.initializer, propPath, sourceFile, diagnostics);
+    }
+  }
+}

package/src/plugin.test.ts

@@ -28,17 +28,19 @@ describe("helmPlugin", () => {
 
   test("provides lint rules", () => {
     const rules = helmPlugin.lintRules!();
-    expect(rules.length).toBe(3);
+    expect(rules.length).toBe(4);
     const ids = rules.map((r) => r.id);
     expect(ids).toContain("WHM001");
     expect(ids).toContain("WHM002");
     expect(ids).toContain("WHM003");
+    expect(ids).toContain("WHM004");
   });
 
   test("provides post-synth checks", () => {
     const checks = helmPlugin.postSynthChecks!();
-    expect(checks.length).toBe(20);
+    expect(checks.length).toBe(21);
     const ids = checks.map((c) => c.id);
+    expect(ids).toContain("WHM005");
     expect(ids).toContain("WHM101");
     expect(ids).toContain("WHM105");
     expect(ids).toContain("WHM301");

package/src/resources.ts

@@ -67,6 +67,26 @@ export const HelmDependency = createProperty("Helm::Dependency", LEXICON);
  */
 export const HelmMaintainer = createProperty("Helm::Maintainer", LEXICON);
 
+/**
+ * Helm::ValuesOverride — Generate a named YAML override file.
+ *
+ * Emits a standalone YAML file inside the chart directory, intended to be
+ * passed as `helm upgrade -f chart-dir/values-base.yaml`. Use this for
+ * static configuration shared across all deployments (disabled bundled
+ * services, shared secret references, etc.).
+ *
+ * Props: { filename: string, values: Record<string, unknown> }
+ *
+ * ```ts
+ * new ValuesOverride({
+ *   filename: "values-base",
+ *   values: { postgresql: { install: false }, redis: { install: false } },
+ * })
+ * // → generates chart-dir/values-base.yaml
+ * ```
+ */
+export const ValuesOverride = createResource("Helm::ValuesOverride", LEXICON, {});
+
 // ── CRD ──────────────────────────────────────────────────
 
 /**

package/src/serializer.test.ts

@@ -3,8 +3,8 @@ import { createResource, createProperty } from "@intentius/chant/runtime";
 import type { Declarable } from "@intentius/chant/declarable";
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { helmSerializer } from "./serializer";
-import { Chart, Values, HelmNotes, HelmTest, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources";
-import { values, include, printf, toYaml, quote, helmDefault, required, If, ElseIf, Range, With, Release, ChartRef, Capabilities } from "./intrinsics";
+import { Chart, Values, ValuesOverride, HelmNotes, HelmTest, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources";
+import { values, include, printf, toYaml, quote, helmDefault, required, If, ElseIf, Range, With, Release, ChartRef, Capabilities, runtimeSlot } from "./intrinsics";
 
 function makeEntities(...pairs: [string, Record<string, unknown>][]): Map<string, Declarable> {
   const entities = new Map<string, Declarable>();
@@ -792,6 +792,117 @@ describe("Capabilities in template", () => {
   });
 });
 
+describe("runtimeSlot in Values", () => {
+  test("emits '' for runtimeSlot in values.yaml", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const vals = new Values({
+      global: {
+        psql: { host: runtimeSlot("Cloud SQL private IP") },
+      },
+      replicaCount: 1,
+    });
+    const entities = makeEntities(["chart", chart], ["values", vals]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+    const valuesYaml = result.files!["values.yaml"];
+
+    expect(valuesYaml).toContain("host: ''");
+    expect(valuesYaml).toContain("replicaCount: 1");
+  });
+
+  test("emits values-runtime-slots.yaml when RuntimeSlot present", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const vals = new Values({
+      global: {
+        psql: { host: runtimeSlot("Cloud SQL private IP") },
+        redis: { host: runtimeSlot("Memorystore host") },
+      },
+    });
+    const entities = makeEntities(["chart", chart], ["values", vals]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+    const slotsYaml = result.files!["values-runtime-slots.yaml"];
+
+    expect(slotsYaml).toBeDefined();
+    expect(slotsYaml).toContain("# Generated by chant");
+    expect(slotsYaml).toContain("# Cloud SQL private IP");
+    expect(slotsYaml).toContain("host: ''");
+    expect(slotsYaml).toContain("# Memorystore host");
+    // Only RuntimeSlot fields should appear
+    expect(slotsYaml).not.toContain("replicaCount");
+  });
+
+  test("does not emit values-runtime-slots.yaml when no RuntimeSlot", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const vals = new Values({ replicaCount: 1, image: { repository: "nginx" } });
+    const entities = makeEntities(["chart", chart], ["values", vals]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+
+    expect(result.files!["values-runtime-slots.yaml"]).toBeUndefined();
+  });
+
+  test("runtimeSlot with empty description emits no comment", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const vals = new Values({ host: runtimeSlot() });
+    const entities = makeEntities(["chart", chart], ["values", vals]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+    const slotsYaml = result.files!["values-runtime-slots.yaml"];
+
+    expect(slotsYaml).toBeDefined();
+    expect(slotsYaml).toContain("host: ''");
+    // No comment line for empty description
+    const lines = slotsYaml!.split("\n");
+    const hostLine = lines.findIndex((l) => l.includes("host:"));
+    const prevLine = lines[hostLine - 1] ?? "";
+    expect(prevLine.trim().startsWith("#") && !prevLine.includes("Generated")).toBe(false);
+  });
+});
+
+describe("ValuesOverride serialization", () => {
+  test("emits ValuesOverride as a named yaml file", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const override = new ValuesOverride({
+      filename: "values-base",
+      values: {
+        postgresql: { install: false },
+        redis: { install: false },
+      },
+    });
+    const entities = makeEntities(["chart", chart], ["baseOverride", override]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+
+    expect(result.files!["values-base.yaml"]).toBeDefined();
+    expect(result.files!["values-base.yaml"]).toContain("postgresql:");
+    expect(result.files!["values-base.yaml"]).toContain("install: false");
+    expect(result.files!["values-base.yaml"]).toContain("redis:");
+  });
+
+  test("ValuesOverride content does not affect values.yaml", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const vals = new Values({ replicaCount: 1 });
+    const override = new ValuesOverride({
+      filename: "values-base",
+      values: { postgresql: { install: false } },
+    });
+    const entities = makeEntities(["chart", chart], ["values", vals], ["override", override]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+
+    expect(result.files!["values.yaml"]).toContain("replicaCount: 1");
+    expect(result.files!["values.yaml"]).not.toContain("postgresql");
+    expect(result.files!["values-base.yaml"]).toContain("postgresql:");
+    expect(result.files!["values-base.yaml"]).not.toContain("replicaCount");
+  });
+
+  test("multiple ValuesOverride entities emit separate files", () => {
+    const chart = new Chart({ name: "test", version: "0.1.0" });
+    const ov1 = new ValuesOverride({ filename: "values-dev", values: { env: "dev" } });
+    const ov2 = new ValuesOverride({ filename: "values-prod", values: { env: "prod" } });
+    const entities = makeEntities(["chart", chart], ["dev", ov1], ["prod", ov2]);
+    const result = helmSerializer.serialize(entities) as SerializerResult;
+
+    expect(result.files!["values-dev.yaml"]).toContain("env: dev");
+    expect(result.files!["values-prod.yaml"]).toContain("env: prod");
+  });
+});
+
 describe("helpers", () => {
   test("generateHelpers includes all standard templates", () => {
     const { generateHelpers } = require("./helpers");

package/src/serializer.ts

@@ -19,7 +19,7 @@ import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
-import { HELM_TPL_KEY, HELM_IF_KEY, HELM_RANGE_KEY, HELM_WITH_KEY, type HelmConditional } from "./intrinsics";
+import { HELM_TPL_KEY, HELM_IF_KEY, HELM_RANGE_KEY, HELM_WITH_KEY, RUNTIME_SLOT_KEY, type HelmConditional } from "./intrinsics";
 import { generateHelpers } from "./helpers";
 
 // ── GVK resolution for K8s resources ──────────────────────
@@ -96,14 +96,33 @@ function emitElseChain(elseBody: unknown, indent: number): string {
 /**
  * Emit a YAML value, detecting __helm_tpl markers and emitting them
  * as raw Go template expressions.
+ *
+ * @param valuesContext - When true, HelmTpl intrinsics are emitted as empty
+ *   string placeholders instead of raw Go template expressions. values.yaml
+ *   is not processed as a Go template by Helm, so {{ .Values.x }} is invalid
+ *   there. Actual values are provided via -f override files at deploy time.
  */
-function emitHelmYAML(value: unknown, indent: number): string {
+function emitHelmYAML(value: unknown, indent: number, valuesContext: boolean = false): string {
   const prefix = "  ".repeat(indent);
 
   if (value === null || value === undefined) return "null";
   if (typeof value === "boolean") return value ? "true" : "false";
   if (typeof value === "number") return String(value);
 
+  // Detect HelmTpl / Intrinsic objects via INTRINSIC_MARKER before string check
+  if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
+    const tplObj = value as { toJSON(): unknown };
+    if (valuesContext) {
+      // In values.yaml context: emit empty placeholder — actual value comes from override files
+      return "''";
+    }
+    const json = tplObj.toJSON() as Record<string, unknown>;
+    if (typeof json === "object" && json !== null && HELM_TPL_KEY in json) {
+      return json[HELM_TPL_KEY] as string;
+    }
+    return "''";
+  }
+
   if (typeof value === "string") {
     // Check if this is a raw template expression that was already inlined
     if (value.startsWith("{{") && value.endsWith("}}")) {
@@ -131,7 +150,7 @@ function emitHelmYAML(value: unknown, indent: number): string {
         const entries = Object.entries(item as Record<string, unknown>);
         if (entries.length > 0) {
           const [firstKey, firstVal] = entries[0];
-          const firstEmitted = emitHelmYAML(firstVal, indent + 2);
+          const firstEmitted = emitHelmYAML(firstVal, indent + 2, valuesContext);
           if (firstEmitted.startsWith("\n")) {
             lines.push(`${prefix}- ${firstKey}:${firstEmitted}`);
           } else {
@@ -139,7 +158,7 @@ function emitHelmYAML(value: unknown, indent: number): string {
           }
           for (let i = 1; i < entries.length; i++) {
             const [key, val] = entries[i];
-            const emitted = emitHelmYAML(val, indent + 2);
+            const emitted = emitHelmYAML(val, indent + 2, valuesContext);
             if (emitted.startsWith("\n")) {
               lines.push(`${prefix}  ${key}:${emitted}`);
             } else {
@@ -148,7 +167,7 @@ function emitHelmYAML(value: unknown, indent: number): string {
           }
         }
       } else {
-        lines.push(`${prefix}- ${emitHelmYAML(item, indent + 1).trimStart()}`);
+        lines.push(`${prefix}- ${emitHelmYAML(item, indent + 1, valuesContext).trimStart()}`);
       }
     }
     return "\n" + lines.join("\n");
@@ -157,8 +176,9 @@ function emitHelmYAML(value: unknown, indent: number): string {
   if (typeof value === "object") {
     const obj = value as Record<string, unknown>;
 
-    // Detect __helm_tpl marker → emit raw template expression
+    // Detect __helm_tpl marker → emit raw template expression (not valid in valuesContext)
     if (HELM_TPL_KEY in obj && typeof obj[HELM_TPL_KEY] === "string") {
+      if (valuesContext) return "''";
       return obj[HELM_TPL_KEY] as string;
     }
 
@@ -167,7 +187,7 @@ function emitHelmYAML(value: unknown, indent: number): string {
       const condition = obj[HELM_IF_KEY] as string;
       const body = obj.body;
       const elseBody = obj.else;
-      let result = `{{- if ${condition} }}\n${emitHelmYAML(body, indent)}`;
+      let result = `{{- if ${condition} }}\n${emitHelmYAML(body, indent, valuesContext)}`;
       if (elseBody !== undefined) {
         result += emitElseChain(elseBody, indent);
       }
@@ -179,21 +199,21 @@ function emitHelmYAML(value: unknown, indent: number): string {
     if (HELM_RANGE_KEY in obj) {
       const list = obj[HELM_RANGE_KEY] as string;
       const body = obj.body;
-      return `{{- range ${list} }}\n${emitHelmYAML(body, indent)}\n{{- end }}`;
+      return `{{- range ${list} }}\n${emitHelmYAML(body, indent, valuesContext)}\n{{- end }}`;
     }
 
     // Detect __helm_with marker → emit with scope
     if (HELM_WITH_KEY in obj) {
       const scope = obj[HELM_WITH_KEY] as string;
       const body = obj.body;
-      return `{{- with ${scope} }}\n${emitHelmYAML(body, indent)}\n{{- end }}`;
+      return `{{- with ${scope} }}\n${emitHelmYAML(body, indent, valuesContext)}\n{{- end }}`;
     }
 
     const entries = Object.entries(obj);
     if (entries.length === 0) return "{}";
     const lines: string[] = [];
     for (const [key, val] of entries) {
-      const emitted = emitHelmYAML(val, indent + 1);
+      const emitted = emitHelmYAML(val, indent + 1, valuesContext);
       if (emitted.startsWith("\n")) {
         lines.push(`${prefix}${key}:${emitted}`);
       } else {
@@ -209,8 +229,8 @@ function emitHelmYAML(value: unknown, indent: number): string {
 /**
  * Emit a top-level key-value pair in Helm YAML.
  */
-function emitKeyValue(key: string, value: unknown): string {
-  const yamlStr = emitHelmYAML(value, 1);
+function emitKeyValue(key: string, value: unknown, valuesContext: boolean = false): string {
+  const yamlStr = emitHelmYAML(value, 1, valuesContext);
   if (yamlStr.startsWith("\n")) {
     return `${key}:${yamlStr}`;
   }
@@ -264,16 +284,105 @@ function emitChartYaml(props: Record<string, unknown>): string {
 
 /**
  * Generate values.yaml content from Helm::Values entity props.
+ * HelmTpl intrinsics are emitted as empty placeholders since values.yaml
+ * is not processed as a Go template by Helm.
  */
 function emitValuesYaml(props: Record<string, unknown>): string {
   if (Object.keys(props).length === 0) return "{}\n";
   const lines: string[] = [];
   for (const [key, val] of Object.entries(props)) {
-    lines.push(emitKeyValue(key, val));
+    lines.push(emitKeyValue(key, val, true));
   }
   return lines.join("\n") + "\n";
 }
 
+// ── RuntimeSlot helpers ───────────────────────────────────
+
+/**
+ * Represents the tree structure built from runtime slot paths.
+ * Leaves are description strings; branches are nested SlotTree objects.
+ */
+type SlotTree = { [key: string]: SlotTree | string };
+
+/**
+ * Collect all RuntimeSlot instances from a props tree.
+ * Returns the path (as array of keys) and description for each slot.
+ */
+function collectRuntimeSlots(
+  props: unknown,
+  path: string[],
+): { path: string[]; description: string }[] {
+  const result: { path: string[]; description: string }[] = [];
+  if (props === null || props === undefined) return result;
+
+  if (typeof props === "object" && INTRINSIC_MARKER in (props as object)) {
+    const json = (props as { toJSON(): unknown }).toJSON() as Record<string, unknown>;
+    if (typeof json === "object" && json !== null && RUNTIME_SLOT_KEY in json) {
+      result.push({ path, description: json[RUNTIME_SLOT_KEY] as string });
+    }
+    return result;
+  }
+
+  if (typeof props === "object" && !Array.isArray(props)) {
+    for (const [key, value] of Object.entries(props as Record<string, unknown>)) {
+      result.push(...collectRuntimeSlots(value, [...path, key]));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a nested tree from flat path+description pairs.
+ */
+function buildSlotTree(slots: { path: string[]; description: string }[]): SlotTree {
+  const tree: SlotTree = {};
+  for (const { path, description } of slots) {
+    let node = tree;
+    for (let i = 0; i < path.length - 1; i++) {
+      const key = path[i];
+      if (typeof node[key] !== "object") {
+        node[key] = {};
+      }
+      node = node[key] as SlotTree;
+    }
+    node[path[path.length - 1]] = description;
+  }
+  return tree;
+}
+
+/**
+ * Emit a slot tree as YAML lines with description comments before leaves.
+ */
+function emitSlotTreeYaml(tree: SlotTree, indent: number): string {
+  const prefix = "  ".repeat(indent);
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(tree)) {
+    if (typeof value === "string") {
+      if (value) {
+        lines.push(`${prefix}# ${value}`);
+      }
+      lines.push(`${prefix}${key}: ''`);
+    } else {
+      lines.push(`${prefix}${key}:`);
+      const nested = emitSlotTreeYaml(value, indent + 1);
+      if (nested) lines.push(nested);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Generate values-runtime-slots.yaml from collected RuntimeSlot instances.
+ * Returns empty string if no slots found.
+ */
+function emitRuntimeSlotsYaml(slots: { path: string[]; description: string }[]): string {
+  if (slots.length === 0) return "";
+  const tree = buildSlotTree(slots);
+  return "# Generated by chant — fill these in before running helm upgrade\n" +
+    emitSlotTreeYaml(tree, 0) + "\n";
+}
+
 /**
  * Description inference — static map from common Helm value key names.
  */
@@ -397,6 +506,11 @@ function generateValuesSchema(props: Record<string, unknown>): string {
       return schema;
     }
 
+    if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
+      // HelmTpl / Intrinsic — actual value provided via -f override; accept any type
+      return {};
+    }
+
     if (typeof value === "object") {
       const obj = value as Record<string, unknown>;
       const properties: Record<string, unknown> = {};
@@ -645,6 +759,7 @@ export const helmSerializer: Serializer = {
     let notesContent: string | undefined;
     const dependencies: Record<string, unknown>[] = [];
     const maintainers: Record<string, unknown>[] = [];
+    const valuesOverrides: { filename: string; values: Record<string, unknown> }[] = [];
 
     // First pass: extract Helm-specific resources and collect metadata
     for (const [_name, entity] of entities) {
@@ -674,6 +789,14 @@ export const helmSerializer: Serializer = {
           const filename = (props.filename as string) ?? `${toFileName(_name)}.yaml`;
           files[`crds/${filename}`] = props.content as string;
         }
+      } else if (entityType === "Helm::ValuesOverride") {
+        const props = (entity as Record<string, unknown>).props as Record<string, unknown>;
+        if (props?.filename && props?.values) {
+          valuesOverrides.push({
+            filename: props.filename as string,
+            values: props.values as Record<string, unknown>,
+          });
+        }
       }
     }
 
@@ -696,6 +819,19 @@ export const helmSerializer: Serializer = {
     // Emit values.yaml
     files["values.yaml"] = emitValuesYaml(valuesProps);
 
+    // Emit values-runtime-slots.yaml if any RuntimeSlot instances found
+    if (hasValues) {
+      const slots = collectRuntimeSlots(valuesProps, []);
+      if (slots.length > 0) {
+        files["values-runtime-slots.yaml"] = emitRuntimeSlotsYaml(slots);
+      }
+    }
+
+    // Emit ValuesOverride files
+    for (const override of valuesOverrides) {
+      files[`${override.filename}.yaml`] = emitValuesYaml(override.values);
+    }
+
     // Emit values.schema.json if we have values
     if (hasValues && Object.keys(valuesProps).length > 0) {
       files["values.schema.json"] = generateValuesSchema(valuesProps);

package/src/skills/chant-helm-patterns.md

@@ -215,6 +215,58 @@ ChartRef.Name         // {{ .Chart.Name }}
 ChartRef.Version      // {{ .Chart.Version }}
 ```
 
+## Deploying Upstream Charts with Value Overrides
+
+When you need to deploy an upstream chart (like `gitlab/gitlab`) with custom values, avoid wrapper charts with no templates. Instead:
+
+1. Use `runtimeSlot()` in `new Values({...})` for deploy-time values (DB IPs, bucket names, replicas)
+2. Use `ValuesOverride` for static values shared across all environments (disabled bundled services, shared secret refs)
+3. Deploy the upstream chart directly with `-f` flags
+
+```typescript
+import { Values, ValuesOverride, runtimeSlot } from "@intentius/chant-lexicon-helm";
+
+// Runtime slots → values-runtime-slots.yaml (deploy-time checklist)
+export const vals = new Values({
+  global: {
+    psql: { host: runtimeSlot("Cloud SQL private IP") },
+    redis: { host: runtimeSlot("Memorystore host") },
+  },
+});
+
+// Static overrides → values-base.yaml (shared across all deployments)
+export const baseOverride = new ValuesOverride({
+  filename: "values-base",
+  values: {
+    postgresql: { install: false },
+    redis: { install: false },
+    certmanager: { install: false },
+    "nginx-ingress": { enabled: false },
+  },
+});
+```
+
+Outputs:
+- `chart-dir/values.yaml` — defaults; runtime slots appear as `''`
+- `chart-dir/values-base.yaml` — generated static overrides
+- `chart-dir/values-runtime-slots.yaml` — deploy-time slots with descriptions as comments
+
+Deploy:
+```bash
+# chant build generates chart-dir/ including values-base.yaml
+chant build
+
+# Fill in runtime-slot values (one per environment)
+# values-prod.yaml contains: global.psql.host, global.redis.host, etc.
+
+helm upgrade --install my-release upstream/chart \
+  -f chart-dir/values-base.yaml \
+  -f values-prod.yaml \
+  --wait
+```
+
+**WHM005** warns when a chart has `HelmDependency` entries but generates no templates — this is the "empty wrapper" anti-pattern that requires `helm dependency build` as a non-obvious prerequisite.
+
 ## Template Functions
 
 ```typescript