@intentius/chant-lexicon-helm 0.0.16

package/README.md

@@ -0,0 +1,22 @@
+# @intentius/chant-lexicon-helm
+
+Helm lexicon for [chant](https://intentius.io/chant/) — declare Helm charts, releases, and values as typed TypeScript.
+
+This package provides generated constructors for Helm resource types, composites for grouping related resources, and Helm-specific lint rules. It builds on the Kubernetes lexicon for base resource types. It also includes LSP and MCP server support for editor completions and hover.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-helm
+```
+
+**[Documentation →](https://intentius.io/chant/lexicons/helm/)**
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| [@intentius/chant](https://www.npmjs.com/package/@intentius/chant) | Core type system, CLI, build pipeline |
+| [@intentius/chant-lexicon-k8s](https://www.npmjs.com/package/@intentius/chant-lexicon-k8s) | Kubernetes lexicon (base dependency) |
+
+## License
+
+See the main project LICENSE file.

package/dist/integrity.json

@@ -0,0 +1,36 @@
+{
+  "algorithm": "xxhash64",
+  "artifacts": {
+    "manifest.json": "9d47d59c10c219ca",
+    "meta.json": "b7aab243e162dfaf",
+    "types/index.d.ts": "e8011da51963f058",
+    "rules/no-hardcoded-image.ts": "c75aa9c33016c3b9",
+    "rules/values-no-secrets.ts": "213276bfe1fb8ff7",
+    "rules/chart-metadata.ts": "d0cff2b78fed78d3",
+    "rules/whm103.ts": "a777a13f2eaf1831",
+    "rules/whm104.ts": "e2d644da2a9dc605",
+    "rules/whm201.ts": "f263fe69901552eb",
+    "rules/whm101.ts": "533ae8f65cb2227b",
+    "rules/whm402.ts": "f722014a723654af",
+    "rules/whm204.ts": "7b57de71795fc102",
+    "rules/whm406.ts": "c76ac5a44c3e9dcd",
+    "rules/whm301.ts": "f3ed3a269093527",
+    "rules/whm203.ts": "2bb546d268c84232",
+    "rules/whm404.ts": "8847425e930d41c1",
+    "rules/whm102.ts": "4c0c494c253df56a",
+    "rules/helm-helpers.ts": "2e0cc249268227ed",
+    "rules/whm302.ts": "44e58ce621ae6d1a",
+    "rules/whm502.ts": "2c9901ecbfaf92cb",
+    "rules/whm407.ts": "f1fbc6942aff8e96",
+    "rules/whm401.ts": "fe72c3c450a12f93",
+    "rules/whm105.ts": "8977ec834713b90c",
+    "rules/whm403.ts": "729d10edb48b0d03",
+    "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": "d2cb222caa70736e"
+  },
+  "composite": "e4128d38dbdb1bbb"
+}

package/dist/manifest.json

@@ -0,0 +1,37 @@
+{
+  "name": "helm",
+  "version": "0.0.16",
+  "chantVersion": ">=0.1.0",
+  "namespace": "Helm",
+  "intrinsics": [
+    {
+      "name": "values",
+      "description": "Proxy accessor for {{ .Values.x }} references"
+    },
+    {
+      "name": "Release",
+      "description": "Built-in Release object"
+    },
+    {
+      "name": "ChartRef",
+      "description": "Built-in Chart object"
+    },
+    {
+      "name": "include",
+      "description": "Include a named template"
+    },
+    {
+      "name": "If",
+      "description": "Conditional resource/value"
+    },
+    {
+      "name": "Range",
+      "description": "Range loop"
+    },
+    {
+      "name": "With",
+      "description": "With scope"
+    }
+  ],
+  "pseudoParameters": {}
+}

package/dist/meta.json

@@ -0,0 +1,208 @@
+{
+  "Chart": {
+    "resourceType": "Helm::Chart",
+    "kind": "resource",
+    "description": "Chart.yaml metadata — defines the chart identity, version, and type.",
+    "props": {
+      "apiVersion": {
+        "type": "string",
+        "description": "Chart API version (v2)",
+        "required": true
+      },
+      "name": {
+        "type": "string",
+        "description": "Chart name",
+        "required": true
+      },
+      "version": {
+        "type": "string",
+        "description": "Chart version (SemVer)",
+        "required": true
+      },
+      "appVersion": {
+        "type": "string",
+        "description": "Version of the app deployed by this chart"
+      },
+      "description": {
+        "type": "string",
+        "description": "A single-sentence description of this chart"
+      },
+      "type": {
+        "type": "string",
+        "description": "Chart type: application or library"
+      },
+      "keywords": {
+        "type": "string[]",
+        "description": "Keywords for chart search"
+      },
+      "home": {
+        "type": "string",
+        "description": "URL of the project home page"
+      },
+      "icon": {
+        "type": "string",
+        "description": "URL to an SVG or PNG image for the chart"
+      },
+      "deprecated": {
+        "type": "boolean",
+        "description": "Whether this chart is deprecated"
+      },
+      "sources": {
+        "type": "string[]",
+        "description": "URLs to source code for this chart"
+      },
+      "maintainers": {
+        "type": "HelmMaintainerProps[]",
+        "description": "List of chart maintainers"
+      },
+      "annotations": {
+        "type": "Record<string, string>",
+        "description": "Arbitrary key-value annotations"
+      },
+      "kubeVersion": {
+        "type": "string",
+        "description": "SemVer range of compatible Kubernetes versions"
+      },
+      "condition": {
+        "type": "string",
+        "description": "YAML path for chart enablement (subcharts)"
+      },
+      "tags": {
+        "type": "string",
+        "description": "Tags for grouping charts for enabling/disabling"
+      }
+    }
+  },
+  "Values": {
+    "resourceType": "Helm::Values",
+    "kind": "resource",
+    "description": "Typed values definition — emits values.yaml and values.schema.json.",
+    "props": {}
+  },
+  "HelmTest": {
+    "resourceType": "Helm::Test",
+    "kind": "resource",
+    "description": "Helm test pod — annotated with helm.sh/hook: test.",
+    "props": {
+      "resource": {
+        "type": "object",
+        "description": "K8s Pod resource to use as the test"
+      }
+    }
+  },
+  "HelmNotes": {
+    "resourceType": "Helm::Notes",
+    "kind": "resource",
+    "description": "NOTES.txt template content — displayed after helm install.",
+    "props": {
+      "content": {
+        "type": "string",
+        "description": "NOTES.txt content (may contain Go template expressions)",
+        "required": true
+      }
+    }
+  },
+  "HelmHook": {
+    "resourceType": "Helm::Hook",
+    "kind": "property",
+    "description": "Lifecycle hook annotation — wraps a K8s resource with helm.sh/hook annotations.",
+    "props": {
+      "hook": {
+        "type": "string",
+        "description": "Hook type: pre-install, post-install, pre-upgrade, post-upgrade, pre-delete, post-delete, pre-rollback, post-rollback, test",
+        "required": true
+      },
+      "weight": {
+        "type": "number",
+        "description": "Hook execution order weight"
+      },
+      "deletePolicy": {
+        "type": "string",
+        "description": "Hook delete policy: before-hook-creation, hook-succeeded, hook-failed"
+      },
+      "resource": {
+        "type": "object",
+        "description": "K8s resource to annotate with the hook",
+        "required": true
+      }
+    }
+  },
+  "HelmDependency": {
+    "resourceType": "Helm::Dependency",
+    "kind": "property",
+    "description": "Chart dependency entry for Chart.yaml dependencies.",
+    "props": {
+      "name": {
+        "type": "string",
+        "description": "Dependency chart name",
+        "required": true
+      },
+      "version": {
+        "type": "string",
+        "description": "Dependency version range (SemVer)",
+        "required": true
+      },
+      "repository": {
+        "type": "string",
+        "description": "Repository URL",
+        "required": true
+      },
+      "condition": {
+        "type": "string",
+        "description": "YAML path that enables/disables this dependency"
+      },
+      "tags": {
+        "type": "string[]",
+        "description": "Tags for grouping dependencies"
+      },
+      "enabled": {
+        "type": "boolean",
+        "description": "Whether this dependency is enabled"
+      },
+      "importValues": {
+        "type": "unknown[]",
+        "description": "Values to import from dependency (import-values in Chart.yaml)"
+      },
+      "alias": {
+        "type": "string",
+        "description": "Alias for the dependency"
+      }
+    }
+  },
+  "HelmMaintainer": {
+    "resourceType": "Helm::Maintainer",
+    "kind": "property",
+    "description": "Chart maintainer entry for Chart.yaml maintainers.",
+    "props": {
+      "name": {
+        "type": "string",
+        "description": "Maintainer name",
+        "required": true
+      },
+      "email": {
+        "type": "string",
+        "description": "Maintainer email"
+      },
+      "url": {
+        "type": "string",
+        "description": "Maintainer URL"
+      }
+    }
+  },
+  "HelmCRD": {
+    "resourceType": "Helm::CRD",
+    "kind": "resource",
+    "description": "Custom Resource Definition — placed in the crds/ directory.",
+    "props": {
+      "content": {
+        "type": "string",
+        "description": "CRD YAML content",
+        "required": true
+      },
+      "filename": {
+        "type": "string",
+        "description": "CRD filename (e.g. mycrd.yaml)"
+      }
+    }
+  }
+}

package/dist/rules/chart-metadata.ts

@@ -0,0 +1,64 @@
+/**
+ * WHM001: Chart Metadata Required
+ *
+ * Detects Chart constructors missing required fields: name, version, apiVersion.
+ *
+ * Bad:  new Chart({})
+ * Good: new Chart({ apiVersion: "v2", name: "my-app", version: "0.1.0" })
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const REQUIRED_FIELDS = ["name", "version", "apiVersion"];
+
+export const chartMetadataRule: LintRule = {
+  id: "WHM001",
+  severity: "error",
+  category: "correctness",
+  description:
+    "Chart must have name, version, and apiVersion fields",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for `new Chart({ ... })`
+      if (
+        ts.isNewExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "Chart" &&
+        node.arguments &&
+        node.arguments.length > 0
+      ) {
+        const arg = node.arguments[0];
+        if (ts.isObjectLiteralExpression(arg)) {
+          const presentKeys = new Set<string>();
+          for (const prop of arg.properties) {
+            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+              presentKeys.add(prop.name.text);
+            }
+          }
+
+          const missing = REQUIRED_FIELDS.filter((f) => !presentKeys.has(f));
+          if (missing.length > 0) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            diagnostics.push({
+              file: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "WHM001",
+              severity: "error",
+              message: `Chart is missing required fields: ${missing.join(", ")}`,
+            });
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/helm-helpers.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared helpers for Helm post-synth checks.
+ *
+ * Provides utilities to extract and parse the Helm chart files
+ * from the serializer's SerializerResult output.
+ */
+
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+/**
+ * Extract the files map from a serializer output.
+ * Returns empty object if output is a plain string.
+ */
+export function getChartFiles(output: string | SerializerResult): Record<string, string> {
+  if (typeof output === "string") return {};
+  return output.files ?? {};
+}
+
+/**
+ * Parse Chart.yaml content into key-value pairs.
+ * Lightweight parser — not a full YAML parser.
+ */
+export function parseChartYaml(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const match = line.match(/^([a-zA-Z]+):\s*(.+)$/);
+    if (match) {
+      result[match[1]] = match[2].replace(/^'(.*)'$/, "$1").trim();
+    }
+  }
+  return result;
+}
+
+/**
+ * Check if a string contains balanced Go template braces.
+ */
+export function hasBalancedBraces(content: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < content.length - 1; i++) {
+    if (content[i] === "{" && content[i + 1] === "{") {
+      depth++;
+      i++; // skip next char
+    } else if (content[i] === "}" && content[i + 1] === "}") {
+      depth--;
+      i++;
+      if (depth < 0) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * Extract all Go template expressions from content.
+ */
+export function extractTemplateExpressions(content: string): string[] {
+  const regex = /\{\{-?\s*(.*?)\s*-?\}\}/g;
+  const matches: string[] = [];
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    matches.push(match[1]);
+  }
+  return matches;
+}

package/dist/rules/no-hardcoded-image.ts

@@ -0,0 +1,62 @@
+/**
+ * WHM003: Container Images Should Use Values References
+ *
+ * Detects container image strings that are hardcoded in K8s resource
+ * constructors instead of using values references. In Helm charts, images
+ * should be parameterized via values.yaml so they can be overridden at
+ * install time.
+ *
+ * Bad:  image: "nginx:1.19"
+ * Good: image: printf("%s:%s", values.image.repository, values.image.tag)
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Pattern matching common container image references.
+ * Matches strings like "nginx:1.19", "registry.io/app:latest", etc.
+ */
+const IMAGE_PATTERN = /^[a-z0-9][a-z0-9._/-]*:[a-z0-9][a-z0-9._-]*$/i;
+
+export const noHardcodedImageRule: LintRule = {
+  id: "WHM003",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "Container images should use values references, not hardcoded tags",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for property assignments: `image: "nginx:1.19"`
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "image" &&
+        ts.isStringLiteral(node.initializer)
+      ) {
+        const value = node.initializer.text;
+        if (IMAGE_PATTERN.test(value)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+            node.initializer.getStart(),
+          );
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "WHM003",
+            severity: "warning",
+            message: `Hardcoded image "${value}" — use values references (e.g. printf("%s:%s", values.image.repository, values.image.tag)) for Helm chart parameterization`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/values-no-secrets.ts

@@ -0,0 +1,82 @@
+/**
+ * WHM002: Values Should Not Contain Bare Secrets
+ *
+ * Detects Values constructor props that contain keys suggesting sensitive
+ * data (password, token, key, secret, apiKey) without an `existingSecret`
+ * pattern — hardcoded secrets in values.yaml are a security anti-pattern.
+ *
+ * Bad:  new Values({ dbPassword: "hunter2" })
+ * Good: new Values({ existingSecret: "", dbPasswordKey: "password" })
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const SENSITIVE_KEY_PATTERN = /^(password|secret|token|apiKey|api_key|private_key|privateKey)$/i;
+const SAFE_PATTERNS = /existing|ref|key_name|keyName|secretName/i;
+
+export const valuesNoSecretsRule: LintRule = {
+  id: "WHM002",
+  severity: "warning",
+  category: "security",
+  description:
+    "Values should not contain bare secrets — use existingSecret pattern instead",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for `new Values({ ... })`
+      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;
+  },
+};
+
+function checkObjectLiteral(
+  obj: ts.ObjectLiteralExpression,
+  sourceFile: ts.SourceFile,
+  diagnostics: LintDiagnostic[],
+): void {
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+      const key = prop.name.text;
+
+      // Check if the key looks sensitive
+      if (SENSITIVE_KEY_PATTERN.test(key) && !SAFE_PATTERNS.test(key)) {
+        // Check if the value is a string literal (hardcoded secret)
+        if (ts.isStringLiteral(prop.initializer) && prop.initializer.text !== "") {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(prop.getStart());
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "WHM002",
+            severity: "warning",
+            message: `Values key "${key}" contains a hardcoded secret — use existingSecret pattern or leave empty as default`,
+          });
+        }
+      }
+
+      // Recurse into nested objects
+      if (ts.isObjectLiteralExpression(prop.initializer)) {
+        checkObjectLiteral(prop.initializer, sourceFile, diagnostics);
+      }
+    }
+  }
+}

package/dist/rules/whm101.ts

@@ -0,0 +1,46 @@
+/**
+ * WHM101: Chart.yaml has required fields and valid apiVersion (v2).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles, parseChartYaml } from "./helm-helpers";
+
+export const whm101: PostSynthCheck = {
+  id: "WHM101",
+  description: "Chart.yaml must have required fields (apiVersion v2, name, version)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+      const chartYaml = files["Chart.yaml"];
+      if (!chartYaml) {
+        diagnostics.push({
+          checkId: "WHM101",
+          severity: "error",
+          message: "Chart.yaml is missing from serializer output",
+          lexicon: "helm",
+        });
+        continue;
+      }
+
+      const parsed = parseChartYaml(chartYaml);
+
+      if (!parsed.apiVersion) {
+        diagnostics.push({ checkId: "WHM101", severity: "error", message: "Chart.yaml missing apiVersion", lexicon: "helm" });
+      } else if (parsed.apiVersion !== "v2") {
+        diagnostics.push({ checkId: "WHM101", severity: "error", message: `Chart.yaml apiVersion should be "v2", got "${parsed.apiVersion}"`, lexicon: "helm" });
+      }
+
+      if (!parsed.name) {
+        diagnostics.push({ checkId: "WHM101", severity: "error", message: "Chart.yaml missing name", lexicon: "helm" });
+      }
+      if (!parsed.version) {
+        diagnostics.push({ checkId: "WHM101", severity: "error", message: "Chart.yaml missing version", lexicon: "helm" });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/whm102.ts

@@ -0,0 +1,33 @@
+/**
+ * WHM102: values.schema.json present when Values type is used.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+export const whm102: PostSynthCheck = {
+  id: "WHM102",
+  description: "values.schema.json should be present when Values are non-empty",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+      const valuesYaml = files["values.yaml"];
+      const valuesSchema = files["values.schema.json"];
+
+      // If values.yaml has content (not just "{}"), schema should exist
+      if (valuesYaml && valuesYaml.trim() !== "{}" && !valuesSchema) {
+        diagnostics.push({
+          checkId: "WHM102",
+          severity: "warning",
+          message: "values.schema.json is missing — consider adding typed Values to generate a schema",
+          lexicon: "helm",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};