@intentius/chant-lexicon-helm 0.0.16

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

@@ -0,0 +1,103 @@
+/**
+ * WHM501: Unused values keys.
+ *
+ * Parses values.yaml key paths and scans all template files for
+ * `.Values.` references. Keys defined but never referenced produce
+ * an info diagnostic.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+/** Keys that are always implicitly used (e.g. in _helpers.tpl). */
+const IMPLICIT_KEYS = new Set(["nameOverride", "fullnameOverride"]);
+
+/**
+ * Extract all top-level and nested key paths from values.yaml content.
+ * Uses indentation to track nesting (2-space indent per level).
+ */
+function extractValuePaths(content: string): string[] {
+  const paths: string[] = [];
+  const stack: string[] = [];
+  let prevIndent = -1;
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-")) continue;
+
+    const indent = line.length - trimmed.length;
+    const match = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:/);
+    if (!match) continue;
+
+    const key = match[1];
+
+    // Adjust stack based on indentation
+    while (stack.length > 0 && indent <= prevIndent) {
+      stack.pop();
+      prevIndent -= 2;
+    }
+
+    stack.push(key);
+    paths.push(stack.join("."));
+    prevIndent = indent;
+  }
+
+  return paths;
+}
+
+export const whm501: PostSynthCheck = {
+  id: "WHM501",
+  description: "Detect values keys that are defined but never referenced in templates",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+      const valuesContent = files["values.yaml"];
+      if (!valuesContent || valuesContent.trim() === "{}" || valuesContent.trim() === "") continue;
+
+      const definedPaths = extractValuePaths(valuesContent);
+      if (definedPaths.length === 0) continue;
+
+      // Collect all .Values references from templates
+      const referencedPaths = new Set<string>();
+      const valuesRegex = /\.Values\.([a-zA-Z0-9_.]+)/g;
+
+      for (const [filename, content] of Object.entries(files)) {
+        if (!filename.startsWith("templates/")) continue;
+        let match;
+        while ((match = valuesRegex.exec(content)) !== null) {
+          referencedPaths.add(match[1]);
+        }
+      }
+
+      for (const path of definedPaths) {
+        if (IMPLICIT_KEYS.has(path)) continue;
+
+        // Check if this path or any child is referenced
+        const isReferenced = referencedPaths.has(path) ||
+          [...referencedPaths].some((ref) => ref.startsWith(path + "."));
+
+        // Check if any parent of this path is referenced (parent consumed entirely)
+        const parts = path.split(".");
+        const parentReferenced = parts.some((_, i) => {
+          if (i === parts.length - 1) return false;
+          return referencedPaths.has(parts.slice(0, i + 1).join("."));
+        });
+
+        if (!isReferenced && !parentReferenced) {
+          diagnostics.push({
+            checkId: "WHM501",
+            severity: "info",
+            message: `values.yaml defines "${path}" but it is never referenced in templates`,
+            entity: "values.yaml",
+            lexicon: "helm",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,94 @@
+/**
+ * WHM502: K8s API version/kind validation.
+ *
+ * Checks for deprecated or invalid Kubernetes API versions in templates
+ * and suggests replacements.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+/**
+ * Deprecated API versions with their replacements.
+ */
+const DEPRECATED_APIS: Record<string, { replacement: string; kinds: string[] }> = {
+  "extensions/v1beta1": {
+    replacement: "networking.k8s.io/v1",
+    kinds: ["Ingress"],
+  },
+  "networking.k8s.io/v1beta1": {
+    replacement: "networking.k8s.io/v1",
+    kinds: ["Ingress", "IngressClass"],
+  },
+  "apps/v1beta1": {
+    replacement: "apps/v1",
+    kinds: ["Deployment", "StatefulSet"],
+  },
+  "apps/v1beta2": {
+    replacement: "apps/v1",
+    kinds: ["Deployment", "StatefulSet", "DaemonSet", "ReplicaSet"],
+  },
+  "rbac.authorization.k8s.io/v1beta1": {
+    replacement: "rbac.authorization.k8s.io/v1",
+    kinds: ["ClusterRole", "ClusterRoleBinding", "Role", "RoleBinding"],
+  },
+  "admissionregistration.k8s.io/v1beta1": {
+    replacement: "admissionregistration.k8s.io/v1",
+    kinds: ["MutatingWebhookConfiguration", "ValidatingWebhookConfiguration"],
+  },
+  "batch/v1beta1": {
+    replacement: "batch/v1",
+    kinds: ["CronJob"],
+  },
+  "policy/v1beta1": {
+    replacement: "policy/v1",
+    kinds: ["PodDisruptionBudget", "PodSecurityPolicy"],
+  },
+  "autoscaling/v2beta1": {
+    replacement: "autoscaling/v2",
+    kinds: ["HorizontalPodAutoscaler"],
+  },
+  "autoscaling/v2beta2": {
+    replacement: "autoscaling/v2",
+    kinds: ["HorizontalPodAutoscaler"],
+  },
+};
+
+export const whm502: PostSynthCheck = {
+  id: "WHM502",
+  description: "Detect deprecated or invalid Kubernetes API versions",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+
+      for (const [filename, content] of Object.entries(files)) {
+        if (!filename.startsWith("templates/") || filename.endsWith("_helpers.tpl") || filename.endsWith("NOTES.txt")) continue;
+
+        // Extract apiVersion from template
+        const apiVersionMatch = content.match(/apiVersion:\s*(.+)/);
+        if (!apiVersionMatch) continue;
+
+        const apiVersion = apiVersionMatch[1].trim();
+
+        // Skip template expressions
+        if (apiVersion.includes("{{")) continue;
+
+        const deprecation = DEPRECATED_APIS[apiVersion];
+        if (deprecation) {
+          diagnostics.push({
+            checkId: "WHM502",
+            severity: "warning",
+            message: `${filename}: apiVersion "${apiVersion}" is deprecated — use "${deprecation.replacement}" instead`,
+            entity: filename,
+            lexicon: "helm",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/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/src/lint/rules/lint-rules.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { chartMetadataRule } from "./chart-metadata";
+import { valuesNoSecretsRule } from "./values-no-secrets";
+import { noHardcodedImageRule } from "./no-hardcoded-image";
+
+function makeContext(code: string): LintContext {
+  const sourceFile = ts.createSourceFile("test.ts", code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: "test.ts" };
+}
+
+describe("WHM001: chartMetadataRule", () => {
+  test("passes when all required fields present", () => {
+    const ctx = makeContext(`new Chart({ apiVersion: "v2", name: "my-app", version: "0.1.0" });`);
+    expect(chartMetadataRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("fails when name is missing", () => {
+    const ctx = makeContext(`new Chart({ apiVersion: "v2", version: "0.1.0" });`);
+    const diags = chartMetadataRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("name");
+  });
+
+  test("fails when all fields are missing", () => {
+    const ctx = makeContext(`new Chart({});`);
+    const diags = chartMetadataRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("name");
+    expect(diags[0].message).toContain("version");
+    expect(diags[0].message).toContain("apiVersion");
+  });
+
+  test("ignores non-Chart constructors", () => {
+    const ctx = makeContext(`new Deployment({ name: "test" });`);
+    expect(chartMetadataRule.check(ctx)).toHaveLength(0);
+  });
+});
+
+describe("WHM002: valuesNoSecretsRule", () => {
+  test("passes with empty values", () => {
+    const ctx = makeContext(`new Values({});`);
+    expect(valuesNoSecretsRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("warns on hardcoded password", () => {
+    const ctx = makeContext(`new Values({ password: "hunter2" });`);
+    const diags = valuesNoSecretsRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WHM002");
+    expect(diags[0].message).toContain("password");
+  });
+
+  test("warns on hardcoded secret in nested object", () => {
+    const ctx = makeContext(`new Values({ db: { secret: "s3cret" } });`);
+    const diags = valuesNoSecretsRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("secret");
+  });
+
+  test("passes when secret value is empty", () => {
+    const ctx = makeContext(`new Values({ password: "" });`);
+    expect(valuesNoSecretsRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("passes for non-sensitive keys", () => {
+    const ctx = makeContext(`new Values({ replicaCount: 3, name: "test" });`);
+    expect(valuesNoSecretsRule.check(ctx)).toHaveLength(0);
+  });
+});
+
+describe("WHM003: noHardcodedImageRule", () => {
+  test("warns on hardcoded image with tag", () => {
+    const ctx = makeContext(`new Deployment({ spec: { containers: [{ image: "nginx:1.19" }] } });`);
+    const diags = noHardcodedImageRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WHM003");
+    expect(diags[0].message).toContain("nginx:1.19");
+  });
+
+  test("warns on registry/image:tag format", () => {
+    const ctx = makeContext(`({ image: "registry.io/app:latest" })`);
+    const diags = noHardcodedImageRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("passes when image is not a string literal (intrinsic)", () => {
+    const ctx = makeContext(`({ image: printf("%s:%s", values.image.repo, values.image.tag) })`);
+    expect(noHardcodedImageRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("passes for image key without colon-tag pattern", () => {
+    const ctx = makeContext(`({ image: "just-a-name" })`);
+    expect(noHardcodedImageRule.check(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/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/src/lint/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/src/lsp/completions.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const hasGenerated = existsSync(join(pkgDir, "src", "generated", "lexicon-helm.json"));
+
+describe.skipIf(!hasGenerated)("helmCompletions", () => {
+  test("returns resource completions for `new ` prefix", async () => {
+    const { helmCompletions } = await import("./completions");
+    const ctx = {
+      uri: "file:///test.ts",
+      content: "const c = new Chart",
+      position: { line: 0, character: 19 },
+      wordAtCursor: "Chart",
+      linePrefix: "const c = new Chart",
+    };
+
+    const items = helmCompletions(ctx);
+    expect(items.length).toBeGreaterThan(0);
+
+    const chartItem = items.find((i) => i.label === "Chart");
+    expect(chartItem).toBeDefined();
+    expect(chartItem?.kind).toBe("resource");
+    expect(chartItem?.detail).toContain("Helm::Chart");
+  });
+
+  test("filters resource completions by prefix", async () => {
+    const { helmCompletions } = await import("./completions");
+    const ctx = {
+      uri: "file:///test.ts",
+      content: "const h = new Helm",
+      position: { line: 0, character: 18 },
+      wordAtCursor: "Helm",
+      linePrefix: "const h = new Helm",
+    };
+
+    const items = helmCompletions(ctx);
+    for (const item of items) {
+      expect(item.label.toLowerCase().startsWith("helm")).toBe(true);
+    }
+  });
+
+  test("limits results to 50", async () => {
+    const { helmCompletions } = await import("./completions");
+    const ctx = {
+      uri: "file:///test.ts",
+      content: "const x = new ",
+      position: { line: 0, character: 14 },
+      wordAtCursor: "",
+      linePrefix: "const x = new ",
+    };
+
+    const items = helmCompletions(ctx);
+    expect(items.length).toBeLessThanOrEqual(50);
+  });
+
+  test("returns empty for non-matching context", async () => {
+    const { helmCompletions } = await import("./completions");
+    const ctx = {
+      uri: "file:///test.ts",
+      content: "const x = 42",
+      position: { line: 0, character: 13 },
+      wordAtCursor: "42",
+      linePrefix: "const x = 42",
+    };
+
+    const items = helmCompletions(ctx);
+    expect(items.length).toBe(0);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,20 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-helm.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide Helm resource completions based on context.
+ */
+export function helmCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "Helm chart resource");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,46 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const hasGenerated = existsSync(join(pkgDir, "src", "generated", "lexicon-helm.json"));
+
+describe.skipIf(!hasGenerated)("helmHover", () => {
+  test("returns hover info for Chart", async () => {
+    const { helmHover } = await import("./hover");
+    const info = helmHover({ uri: "file:///test.ts", content: "", position: { line: 0, character: 0 }, word: "Chart", lineText: "" });
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("Chart");
+    expect(info!.contents).toContain("Helm::Chart");
+  });
+
+  test("shows resource kind for resource types", async () => {
+    const { helmHover } = await import("./hover");
+    const info = helmHover({ uri: "file:///test.ts", content: "", position: { line: 0, character: 0 }, word: "Values", lineText: "" });
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("Resource");
+  });
+
+  test("returns undefined for unknown word", async () => {
+    const { helmHover } = await import("./hover");
+    const info = helmHover({ uri: "file:///test.ts", content: "", position: { line: 0, character: 0 }, word: "NotARealResource12345", lineText: "" });
+    expect(info).toBeUndefined();
+  });
+
+  test("returns undefined for empty word", async () => {
+    const { helmHover } = await import("./hover");
+    const info = helmHover({ uri: "file:///test.ts", content: "", position: { line: 0, character: 0 }, word: "", lineText: "" });
+    expect(info).toBeUndefined();
+  });
+
+  test("returns info for HelmHook property type", async () => {
+    const { helmHover } = await import("./hover");
+    const info = helmHover({ uri: "file:///test.ts", content: "", position: { line: 0, character: 0 }, word: "HelmHook", lineText: "" });
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("Helm::Hook");
+  });
+});