@intentius/chant-lexicon-helm 0.0.16

package/src/composites/index.ts

@@ -0,0 +1,38 @@
+export { HelmWebApp } from "./helm-web-app";
+export type { HelmWebAppProps, HelmWebAppResult } from "./helm-web-app";
+
+export { HelmStatefulService } from "./helm-stateful-service";
+export type { HelmStatefulServiceProps, HelmStatefulServiceResult } from "./helm-stateful-service";
+
+export { HelmCronJob } from "./helm-cron-job";
+export type { HelmCronJobProps, HelmCronJobResult } from "./helm-cron-job";
+
+export { HelmMicroservice } from "./helm-microservice";
+export type { HelmMicroserviceProps, HelmMicroserviceResult } from "./helm-microservice";
+
+export { HelmLibrary } from "./helm-library";
+export type { HelmLibraryProps, HelmLibraryResult } from "./helm-library";
+
+export { HelmCRDLifecycle } from "./helm-crd-lifecycle";
+export type { HelmCRDLifecycleProps, HelmCRDLifecycleResult } from "./helm-crd-lifecycle";
+
+export { HelmDaemonSet } from "./helm-daemon-set";
+export type { HelmDaemonSetProps, HelmDaemonSetResult } from "./helm-daemon-set";
+
+export { HelmWorker } from "./helm-worker";
+export type { HelmWorkerProps, HelmWorkerResult } from "./helm-worker";
+
+export { HelmExternalSecret } from "./helm-external-secret";
+export type { HelmExternalSecretProps, HelmExternalSecretResult } from "./helm-external-secret";
+
+export { HelmBatchJob } from "./helm-batch-job";
+export type { HelmBatchJobProps, HelmBatchJobResult } from "./helm-batch-job";
+
+export { HelmMonitoredService } from "./helm-monitored-service";
+export type { HelmMonitoredServiceProps, HelmMonitoredServiceResult } from "./helm-monitored-service";
+
+export { HelmSecureIngress } from "./helm-secure-ingress";
+export type { HelmSecureIngressProps, HelmSecureIngressResult } from "./helm-secure-ingress";
+
+export { HelmNamespaceEnv } from "./helm-namespace-env";
+export type { HelmNamespaceEnvProps, HelmNamespaceEnvResult } from "./helm-namespace-env";

package/src/coverage.test.ts

@@ -0,0 +1,21 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const generatedDir = join(pkgDir, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-helm.json"));
+
+describe("coverage", () => {
+  test.skipIf(!hasGenerated)("analyzeHelmCoverage function exists", async () => {
+    const { analyzeHelmCoverage } = await import("./coverage");
+    expect(typeof analyzeHelmCoverage).toBe("function");
+  });
+
+  test.skipIf(!hasGenerated)("runs coverage analysis", async () => {
+    const { analyzeHelmCoverage } = await import("./coverage");
+    // Should complete without throwing
+    await analyzeHelmCoverage();
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,50 @@
+/**
+ * Coverage analysis for the Helm lexicon.
+ *
+ * Since Helm types are static and few, coverage is inherently high.
+ * This module provides a consistent interface with other lexicons.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Analyze coverage of the Helm lexicon.
+ */
+export async function analyzeHelmCoverage(opts?: {
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<void> {
+  const generatedDir = join(pkgDir, "src", "generated");
+  let lexiconData: Record<string, unknown>;
+
+  try {
+    const raw = readFileSync(join(generatedDir, "lexicon-helm.json"), "utf-8");
+    lexiconData = JSON.parse(raw);
+  } catch {
+    console.error("Helm lexicon coverage: generated artifacts not found. Run 'just generate' first.");
+    process.exit(1);
+    return;
+  }
+
+  const typeCount = Object.keys(lexiconData).length;
+  const resources = Object.values(lexiconData).filter(
+    (e) => (e as Record<string, unknown>).kind === "resource",
+  ).length;
+  const properties = Object.values(lexiconData).filter(
+    (e) => (e as Record<string, unknown>).kind === "property",
+  ).length;
+
+  // Helm types are fully statically defined, so coverage is 100%
+  const pct = 100;
+  console.error(`Helm lexicon coverage: ${pct}%`);
+  console.error(`  Types: ${typeCount} (${resources} resources, ${properties} properties)`);
+
+  if (opts?.minOverall && pct < opts.minOverall) {
+    console.error(`Coverage ${pct}% is below minimum ${opts.minOverall}%`);
+    process.exit(1);
+  }
+}

package/src/generated/index.d.ts

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

package/src/generated/index.ts

@@ -0,0 +1,13 @@
+// Auto-generated Helm lexicon runtime index
+// Do not edit manually
+
+import { createResource, createProperty } from "@intentius/chant/runtime";
+
+export const Chart = createResource("Helm::Chart", "helm", {});
+export const Values = createResource("Helm::Values", "helm", {});
+export const HelmTest = createResource("Helm::Test", "helm", {});
+export const HelmNotes = createResource("Helm::Notes", "helm", {});
+export const HelmHook = createProperty("Helm::Hook", "helm");
+export const HelmDependency = createProperty("Helm::Dependency", "helm");
+export const HelmMaintainer = createProperty("Helm::Maintainer", "helm");
+export const HelmCRD = createResource("Helm::CRD", "helm", {});

package/src/generated/lexicon-helm.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/src/helpers.test.ts

@@ -0,0 +1,51 @@
+import { describe, test, expect } from "bun:test";
+import { generateHelpers } from "./helpers";
+
+describe("generateHelpers", () => {
+  test("generates all standard named templates", () => {
+    const content = generateHelpers({ chartName: "my-app" });
+
+    expect(content).toContain('{{- define "my-app.name" -}}');
+    expect(content).toContain('{{- define "my-app.fullname" -}}');
+    expect(content).toContain('{{- define "my-app.chart" -}}');
+    expect(content).toContain('{{- define "my-app.labels" -}}');
+    expect(content).toContain('{{- define "my-app.selectorLabels" -}}');
+    expect(content).toContain('{{- define "my-app.serviceAccountName" -}}');
+  });
+
+  test("fullname template handles nameOverride and fullnameOverride", () => {
+    const content = generateHelpers({ chartName: "test" });
+
+    expect(content).toContain(".Values.fullnameOverride");
+    expect(content).toContain(".Values.nameOverride");
+    expect(content).toContain("trunc 63");
+    expect(content).toContain('trimSuffix "-"');
+  });
+
+  test("labels template includes standard Helm labels", () => {
+    const content = generateHelpers({ chartName: "test" });
+
+    expect(content).toContain("helm.sh/chart:");
+    expect(content).toContain("app.kubernetes.io/version:");
+    expect(content).toContain("app.kubernetes.io/managed-by:");
+  });
+
+  test("selectorLabels template has name and instance", () => {
+    const content = generateHelpers({ chartName: "test" });
+
+    expect(content).toContain("app.kubernetes.io/name:");
+    expect(content).toContain("app.kubernetes.io/instance:");
+  });
+
+  test("serviceAccountName helper can be excluded", () => {
+    const content = generateHelpers({ chartName: "test", includeServiceAccount: false });
+    expect(content).not.toContain("serviceAccountName");
+  });
+
+  test("serviceAccountName helper included by default", () => {
+    const content = generateHelpers({ chartName: "test" });
+    expect(content).toContain("serviceAccountName");
+    expect(content).toContain(".Values.serviceAccount.create");
+    expect(content).toContain(".Values.serviceAccount.name");
+  });
+});

package/src/helpers.ts

@@ -0,0 +1,100 @@
+/**
+ * _helpers.tpl generation for Helm charts.
+ *
+ * Generates the standard named templates that Helm charts typically include:
+ * chart name, fullname, labels, selectorLabels, chart metadata, serviceAccountName.
+ */
+
+export interface HelpersConfig {
+  /** Chart name (from Chart.yaml) */
+  chartName: string;
+  /** Whether to include serviceAccountName helper */
+  includeServiceAccount?: boolean;
+}
+
+/**
+ * Generate the _helpers.tpl content for a Helm chart.
+ */
+export function generateHelpers(config: HelpersConfig): string {
+  const { chartName, includeServiceAccount = true } = config;
+
+  const lines: string[] = [];
+
+  // Chart name
+  lines.push(`{{/*
+Expand the name of the chart.
+*/}}
+{{- define "${chartName}.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}`);
+
+  // Fullname
+  lines.push(`
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "${chartName}.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}`);
+
+  // Chart label
+  lines.push(`
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "${chartName}.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}`);
+
+  // Common labels
+  lines.push(`
+{{/*
+Common labels
+*/}}
+{{- define "${chartName}.labels" -}}
+helm.sh/chart: {{ include "${chartName}.chart" . }}
+{{ include "${chartName}.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}`);
+
+  // Selector labels
+  lines.push(`
+{{/*
+Selector labels
+*/}}
+{{- define "${chartName}.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "${chartName}.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}`);
+
+  // Service account name
+  if (includeServiceAccount) {
+    lines.push(`
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "${chartName}.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "${chartName}.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}`);
+  }
+
+  return lines.join("\n") + "\n";
+}