@intentius/chant-lexicon-helm 0.0.16

package/src/lsp/hover.ts

@@ -0,0 +1,46 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, 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 hover information for Helm resource types.
+ */
+export function helmHover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`Helm type: \`${entry.resourceType}\``);
+
+  if (entry.kind === "resource") {
+    lines.push("");
+    lines.push("*Resource — serialized as a top-level Helm chart artifact*");
+  } else {
+    lines.push("");
+    lines.push("*Property — used as a nested value in Helm resources*");
+  }
+
+  if (entry.attrs && Object.keys(entry.attrs).length > 0) {
+    lines.push("");
+    lines.push("**Attributes:**");
+    for (const [key, value] of Object.entries(entry.attrs)) {
+      lines.push(`- \`${key}\` \u2192 \`${value}\``);
+    }
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/package-cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for Helm lexicon packaging.
+ */
+
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+  const force = process.argv.includes("--force") || process.argv.includes("-f");
+
+  const { spec, stats } = await packageLexicon({ verbose, force });
+
+  const distDir = join(pkgDir, "..", "dist");
+  writeBundleSpec(spec, distDir);
+
+  console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+}
+
+main().catch((err) => {
+  console.error("Packaging failed:", err);
+  process.exit(1);
+});

package/src/plugin.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "bun:test";
+import { helmPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("helmPlugin", () => {
+  test("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(helmPlugin)).toBe(true);
+  });
+
+  test("has name 'helm'", () => {
+    expect(helmPlugin.name).toBe("helm");
+  });
+
+  test("serializer has name 'helm' and rulePrefix 'WHM'", () => {
+    expect(helmPlugin.serializer.name).toBe("helm");
+    expect(helmPlugin.serializer.rulePrefix).toBe("WHM");
+  });
+
+  test("provides intrinsics", () => {
+    const intrinsics = helmPlugin.intrinsics!();
+    expect(intrinsics.length).toBeGreaterThan(0);
+    const names = intrinsics.map((i) => i.name);
+    expect(names).toContain("values");
+    expect(names).toContain("Release");
+    expect(names).toContain("include");
+    expect(names).toContain("If");
+  });
+
+  test("provides lint rules", () => {
+    const rules = helmPlugin.lintRules!();
+    expect(rules.length).toBe(3);
+    const ids = rules.map((r) => r.id);
+    expect(ids).toContain("WHM001");
+    expect(ids).toContain("WHM002");
+    expect(ids).toContain("WHM003");
+  });
+
+  test("provides post-synth checks", () => {
+    const checks = helmPlugin.postSynthChecks!();
+    expect(checks.length).toBe(20);
+    const ids = checks.map((c) => c.id);
+    expect(ids).toContain("WHM101");
+    expect(ids).toContain("WHM105");
+    expect(ids).toContain("WHM301");
+  });
+
+  test("detectTemplate identifies Chart.yaml data", () => {
+    expect(helmPlugin.detectTemplate!({ apiVersion: "v2", name: "test", version: "0.1.0" })).toBe(true);
+    expect(helmPlugin.detectTemplate!({ apiVersion: "v1", name: "test", version: "0.1.0" })).toBe(false);
+    expect(helmPlugin.detectTemplate!({ kind: "Deployment" })).toBe(false);
+    expect(helmPlugin.detectTemplate!(null)).toBe(false);
+  });
+
+  test("initTemplates returns chart.ts scaffold", () => {
+    const templates = helmPlugin.initTemplates!();
+    expect(templates.src["chart.ts"]).toBeDefined();
+    expect(templates.src["chart.ts"]).toContain("new Chart");
+    expect(templates.src["chart.ts"]).toContain("new Values");
+    expect(templates.src["chart.ts"]).toContain("new Deployment");
+  });
+
+  test("skills() returns array with helm skills", () => {
+    const skills = helmPlugin.skills!();
+    expect(Array.isArray(skills)).toBe(true);
+    expect(skills.length).toBeGreaterThanOrEqual(3);
+    const names = skills.map((s) => s.name);
+    expect(names).toContain("chant-helm-create-chart");
+    expect(names).toContain("chant-helm-chart-patterns");
+    expect(names).toContain("chant-helm-chart-security-patterns");
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,206 @@
+/**
+ * Helm lexicon plugin.
+ *
+ * Implements the LexiconPlugin interface with the Helm chart serializer,
+ * Helm-specific intrinsics, lint rules, and post-synth checks.
+ */
+
+import type { LexiconPlugin, IntrinsicDef, InitTemplateSet, SkillDefinition } from "@intentius/chant/lexicon";
+import { discoverLintRules, discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { readFileSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { helmSerializer } from "./serializer";
+
+export const helmPlugin: LexiconPlugin = {
+  name: "helm",
+  serializer: helmSerializer,
+
+  lintRules() {
+    const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
+    return discoverLintRules(rulesDir, import.meta.url);
+  },
+
+  postSynthChecks() {
+    const postSynthDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "post-synth");
+    return discoverPostSynthChecks(postSynthDir, import.meta.url);
+  },
+
+  intrinsics(): IntrinsicDef[] {
+    return [
+      { name: "values", description: "Proxy accessor for {{ .Values.x }} references" },
+      { name: "Release", description: "Built-in Release object (Name, Namespace, etc.)" },
+      { name: "ChartRef", description: "Built-in Chart object (Name, Version, AppVersion)" },
+      { name: "include", description: 'Include a named template: {{ include "name" . }}' },
+      { name: "required", description: 'Require a value: {{ required "msg" .Values.x }}' },
+      { name: "helmDefault", description: 'Default value: {{ default "def" .Values.x }}' },
+      { name: "toYaml", description: "Convert to YAML: {{ toYaml .Values.x | nindent N }}" },
+      { name: "quote", description: "Quote a value: {{ .Values.x | quote }}" },
+      { name: "printf", description: 'Format string: {{ printf "%s" .Values.x }}' },
+      { name: "tpl", description: "Evaluate template: {{ tpl .Values.x . }}" },
+      { name: "lookup", description: 'Lookup resource: {{ lookup "v1" "Secret" "ns" "name" }}' },
+      { name: "Capabilities", description: "Built-in Capabilities object (KubeVersion, APIVersions, HelmVersion)" },
+      { name: "Template", description: "Built-in Template object (Name, BasePath)" },
+      { name: "filesGet", description: '.Files.Get: {{ .Files.Get "path" }}' },
+      { name: "filesGlob", description: '.Files.Glob: {{ .Files.Glob "pattern" }}' },
+      { name: "filesAsConfig", description: ".Files.Glob.AsConfig for ConfigMap data" },
+      { name: "filesAsSecrets", description: ".Files.Glob.AsSecrets for Secret data" },
+      { name: "ElseIf", description: "Else-if chaining: {{- else if .Values.x }}...{{- end }}" },
+      { name: "If", description: "Conditional: {{- if .Values.x }}...{{- end }}" },
+      { name: "Range", description: "Range loop: {{- range .Values.x }}...{{- end }}" },
+      { name: "With", description: "With scope: {{- with .Values.x }}...{{- end }}" },
+      { name: "withOrder", description: "Helm hook annotations for resource ordering (pre-install/pre-upgrade)" },
+      { name: "argoWave", description: "Argo CD sync wave annotation" },
+    ];
+  },
+
+  detectTemplate(data: unknown): boolean {
+    if (typeof data !== "object" || data === null) return false;
+    const obj = data as Record<string, unknown>;
+    // Helm charts have apiVersion: v2 in Chart.yaml
+    if (obj.apiVersion === "v2" && typeof obj.name === "string" && typeof obj.version === "string") {
+      return true;
+    }
+    return false;
+  },
+
+  initTemplates(_template?: string): InitTemplateSet {
+    return {
+      src: {
+        "chart.ts": `import { Chart, Values, HelmNotes } from "@intentius/chant-lexicon-helm";
+import { values, Release, include, toYaml, printf } from "@intentius/chant-lexicon-helm/intrinsics";
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+export const chart = new Chart({
+  apiVersion: "v2",
+  name: "my-app",
+  version: "0.1.0",
+  appVersion: "1.0.0",
+  type: "application",
+  description: "A Helm chart for my application",
+});
+
+export const valuesSchema = new Values({
+  replicaCount: 1,
+  image: {
+    repository: "nginx",
+    tag: "",
+    pullPolicy: "IfNotPresent",
+  },
+  service: {
+    type: "ClusterIP",
+    port: 80,
+  },
+});
+
+export const deployment = new Deployment({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    replicas: values.replicaCount,
+    selector: {
+      matchLabels: include("my-app.selectorLabels"),
+    },
+    template: {
+      metadata: {
+        labels: include("my-app.selectorLabels"),
+      },
+      spec: {
+        containers: [{
+          name: "my-app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          ports: [{ containerPort: values.service.port, name: "http" }],
+        }],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    type: values.service.type,
+    ports: [{
+      port: values.service.port,
+      targetPort: "http",
+      protocol: "TCP",
+      name: "http",
+    }],
+    selector: include("my-app.selectorLabels"),
+  },
+});
+`,
+      },
+    };
+  },
+
+  skills(): SkillDefinition[] {
+    const skillsDir = join(dirname(fileURLToPath(import.meta.url)), "skills");
+    const skills: SkillDefinition[] = [];
+    try {
+      for (const file of readdirSync(skillsDir)) {
+        if (!file.endsWith(".md")) continue;
+        const content = readFileSync(join(skillsDir, file), "utf-8");
+        const name = file.replace(/\.md$/, "");
+        // Derive a readable description from the filename
+        const desc = name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        skills.push({ name: `chant-helm-${name}`, description: desc, content });
+      }
+    } catch {
+      // No skills directory
+    }
+    return skills;
+  },
+
+  async docs(options?: { verbose?: boolean }): Promise<void> {
+    const { generateDocs } = await import("./codegen/docs");
+    await generateDocs({ verbose: options?.verbose });
+  },
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const result = await generate({ verbose: options?.verbose ?? true });
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeGeneratedFiles(result, pkgDir);
+
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types`);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeHelmCoverage } = await import("./coverage");
+    await analyzeHelmCoverage({
+      verbose: options?.verbose,
+      minOverall: options?.minOverall,
+    });
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const distDir = join(pkgDir, "dist");
+    writeBundleSpec(spec, distDir);
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+};

package/src/resources.ts

@@ -0,0 +1,77 @@
+/**
+ * Helm-specific resource and property types.
+ *
+ * Created via createResource/createProperty from @intentius/chant/runtime.
+ * These are static types (no upstream schema to fetch).
+ */
+
+import { createResource, createProperty } from "@intentius/chant/runtime";
+
+const LEXICON = "helm";
+
+// ── Resources ─────────────────────────────────────────────
+
+/**
+ * Helm::Chart — Chart.yaml metadata.
+ *
+ * Defines the chart's identity: apiVersion, name, version, appVersion,
+ * description, type (application|library), keywords, maintainers, dependencies.
+ */
+export const Chart = createResource("Helm::Chart", LEXICON, {});
+
+/**
+ * Helm::Values — Typed values definition.
+ *
+ * The props passed to the constructor become the default values emitted
+ * in values.yaml. The serializer also generates values.schema.json from
+ * the value types.
+ */
+export const Values = createResource("Helm::Values", LEXICON, {});
+
+/**
+ * Helm::Test — Helm test pod.
+ *
+ * Annotated with `helm.sh/hook: test` in the serialized output.
+ * Props should contain a K8s Pod spec.
+ */
+export const HelmTest = createResource("Helm::Test", LEXICON, {});
+
+/**
+ * Helm::Notes — NOTES.txt template content.
+ *
+ * The `content` prop is emitted as templates/NOTES.txt.
+ */
+export const HelmNotes = createResource("Helm::Notes", LEXICON, {});
+
+// ── Property types ────────────────────────────────────────
+
+/**
+ * Helm::Hook — Lifecycle hook annotation.
+ *
+ * Wraps a K8s resource with helm.sh/hook annotations.
+ * Props: { hook: string, weight?: number, deletePolicy?: string, resource: Declarable }
+ */
+export const HelmHook = createProperty("Helm::Hook", LEXICON);
+
+/**
+ * Helm::Dependency — Chart dependency entry.
+ *
+ * Props: { name, version, repository, condition?, tags?, enabled?, importValues?, alias? }
+ */
+export const HelmDependency = createProperty("Helm::Dependency", LEXICON);
+
+/**
+ * Helm::Maintainer — Chart maintainer entry.
+ *
+ * Props: { name, email?, url? }
+ */
+export const HelmMaintainer = createProperty("Helm::Maintainer", LEXICON);
+
+// ── CRD ──────────────────────────────────────────────────
+
+/**
+ * Helm::CRD — Custom Resource Definition placed in the crds/ directory.
+ *
+ * Props: { content: string, filename?: string }
+ */
+export const HelmCRD = createResource("Helm::CRD", LEXICON, {});