@intentius/chant-lexicon-helm 0.0.22 → 0.1.0

package/dist/integrity.json

@@ -1,11 +1,12 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "21f64ba92bab7858",
+    "manifest.json": "8230c04a29b03431",
     "meta.json": "b7aab243e162dfaf",
     "types/index.d.ts": "e8011da51963f058",
     "rules/no-hardcoded-image.ts": "c75aa9c33016c3b9",
     "rules/values-no-secrets.ts": "213276bfe1fb8ff7",
+    "rules/values-no-helm-tpl.ts": "ed23236546936fd0",
     "rules/chart-metadata.ts": "d0cff2b78fed78d3",
     "rules/whm103.ts": "a777a13f2eaf1831",
     "rules/whm104.ts": "e2d644da2a9dc605",
@@ -25,12 +26,13 @@
     "rules/whm401.ts": "fe72c3c450a12f93",
     "rules/whm105.ts": "8977ec834713b90c",
     "rules/whm403.ts": "729d10edb48b0d03",
+    "rules/whm005-no-empty-wrapper.ts": "1a1baea985f0bd86",
     "rules/whm405.ts": "ec82442f9120e5e0",
     "rules/whm202.ts": "dbe1cbb3237be84f",
     "rules/whm501.ts": "e9a9f2b4e034a51f",
-    "skills/chant-helm-chart-patterns.md": "7a2163247f44bf6d",
-    "skills/chant-helm-chart-security-patterns.md": "a7b950513dac7d37",
-    "skills/chant-helm-create-chart.md": "52df5756e29c32bf"
+    "skills/chant-helm.md": "6476c552b9235085",
+    "skills/chant-helm-patterns.md": "cc9bfe5595f22710",
+    "skills/chant-helm-security.md": "a7b950513dac7d37"
   },
-  "composite": "987b6dfc47cf4f5d"
+  "composite": "8872cd0d6c961e4d"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "helm",
-  "version": "0.0.22",
+  "version": "0.1.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Helm",
   "intrinsics": [

package/dist/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/dist/rules/whm005-no-empty-wrapper.ts

@@ -0,0 +1,54 @@
+/**
+ * WHM005: Chart Has Sub-chart Dependencies But Generates No Templates
+ *
+ * A chart with HelmDependency entries but no templates/*.yaml files generates
+ * an empty templates/ directory. Deploying it requires `helm dependency build`
+ * as a non-obvious prerequisite.
+ *
+ * If you only need value overrides for an upstream chart, deploy it directly:
+ *   helm upgrade upstream-chart -f values-override.yaml
+ * and use ValuesOverride to generate the override file.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+export const whm005: PostSynthCheck = {
+  id: "WHM005",
+  description:
+    "Chart with sub-chart dependencies but no templates should deploy upstream chart directly",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+      const chartYaml = files["Chart.yaml"];
+      if (!chartYaml) continue;
+
+      // Check for non-empty dependencies block
+      const hasDependencies = /^dependencies:/m.test(chartYaml);
+      if (!hasDependencies) continue;
+
+      // Check for template files (excluding _helpers.tpl and NOTES.txt)
+      const hasTemplates = Object.keys(files).some((path) => {
+        if (!path.startsWith("templates/")) return false;
+        const filename = path.slice("templates/".length);
+        if (filename === "_helpers.tpl" || filename === "NOTES.txt") return false;
+        return filename.endsWith(".yaml") || filename.endsWith(".yml");
+      });
+
+      if (!hasTemplates) {
+        diagnostics.push({
+          checkId: "WHM005",
+          severity: "warning",
+          message:
+            "Chart has sub-chart dependencies but generates no templates. Deploying this chart requires 'helm dependency build' first. If you only need value overrides for an upstream chart, deploy it directly with 'helm upgrade upstream-chart -f values-override.yaml' and use ValuesOverride to generate the override file.",
+          lexicon: "helm",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/{chant-helm-chart-patterns.md → 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