@intentius/chant-lexicon-helm 0.0.16

package/src/codegen/generate.ts

@@ -0,0 +1,249 @@
+/**
+ * Helm generation pipeline — static type generation.
+ *
+ * Unlike AWS/K8s, Helm types are defined statically (no upstream schema to
+ * fetch). This module generates lexicon-helm.json, index.d.ts, and index.ts
+ * directly from the known Helm resource/property type definitions.
+ */
+
+import {
+  writeGeneratedArtifacts,
+  type GenerateResult,
+} from "@intentius/chant/codegen/generate";
+
+// ── Static type definitions ──────────────────────────────
+
+interface HelmTypeEntry {
+  resourceType: string;
+  /** Export name matching resources.ts (e.g. "HelmTest" not "Test") */
+  exportName: string;
+  kind: "resource" | "property";
+  description: string;
+  props: Record<string, { type: string; description: string; required?: boolean }>;
+}
+
+const HELM_TYPES: HelmTypeEntry[] = [
+  {
+    resourceType: "Helm::Chart",
+    exportName: "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" },
+    },
+  },
+  {
+    resourceType: "Helm::Values",
+    exportName: "Values",
+    kind: "resource",
+    description: "Typed values definition — emits values.yaml and values.schema.json.",
+    props: {},
+  },
+  {
+    resourceType: "Helm::Test",
+    exportName: "HelmTest",
+    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" },
+    },
+  },
+  {
+    resourceType: "Helm::Notes",
+    exportName: "HelmNotes",
+    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 },
+    },
+  },
+  {
+    resourceType: "Helm::Hook",
+    exportName: "HelmHook",
+    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 },
+    },
+  },
+  {
+    resourceType: "Helm::Dependency",
+    exportName: "HelmDependency",
+    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" },
+    },
+  },
+  {
+    resourceType: "Helm::Maintainer",
+    exportName: "HelmMaintainer",
+    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" },
+    },
+  },
+  {
+    resourceType: "Helm::CRD",
+    exportName: "HelmCRD",
+    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)" },
+    },
+  },
+];
+
+// ── Generate artifacts ──────────────────────────────────
+
+function generateLexiconJSON(): string {
+  const registry: Record<string, Record<string, unknown>> = {};
+  for (const t of HELM_TYPES) {
+    registry[t.exportName] = {
+      resourceType: t.resourceType,
+      kind: t.kind,
+      description: t.description,
+      props: t.props,
+    };
+  }
+  return JSON.stringify(registry, null, 2);
+}
+
+function generateTypesDTS(): string {
+  const lines: string[] = [
+    '// Auto-generated Helm lexicon type declarations',
+    '// Do not edit manually',
+    '',
+    '/** Minimal Declarable interface for generated types. */',
+    'interface Declarable { [key: string]: unknown; }',
+    '',
+  ];
+
+  for (const t of HELM_TYPES) {
+    const className = t.exportName;
+    const propsInterface = `${className}Props`;
+
+    // Generate props interface
+    lines.push(`/** ${t.description} */`);
+    lines.push(`export interface ${propsInterface} {`);
+    for (const [key, prop] of Object.entries(t.props)) {
+      const optional = prop.required ? "" : "?";
+      lines.push(`  /** ${prop.description} */`);
+      lines.push(`  ${key}${optional}: ${prop.type};`);
+    }
+    if (Object.keys(t.props).length === 0) {
+      lines.push("  [key: string]: unknown;");
+    }
+    lines.push("}");
+    lines.push("");
+
+    // Generate class declaration
+    lines.push(`/** ${t.description} */`);
+    lines.push(`export declare const ${className}: new (props: ${propsInterface}) => Declarable;`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function generateRuntimeIndex(): string {
+  const lines: string[] = [
+    '// Auto-generated Helm lexicon runtime index',
+    '// Do not edit manually',
+    '',
+    'import { createResource, createProperty } from "@intentius/chant/runtime";',
+    '',
+  ];
+
+  for (const t of HELM_TYPES) {
+    if (t.kind === "resource") {
+      lines.push(`export const ${t.exportName} = createResource("${t.resourceType}", "helm", {});`);
+    } else {
+      lines.push(`export const ${t.exportName} = createProperty("${t.resourceType}", "helm");`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ── Public API ──────────────────────────────────────────
+
+export interface HelmGenerateOptions {
+  verbose?: boolean;
+  force?: boolean;
+}
+
+/**
+ * Run the Helm generation pipeline.
+ * Since Helm types are static, this doesn't fetch anything.
+ */
+export async function generate(opts: HelmGenerateOptions = {}): Promise<GenerateResult> {
+  const log = opts.verbose
+    ? (msg: string) => console.error(msg)
+    : (_msg: string) => {};
+
+  log("Generating Helm lexicon (static types)...");
+
+  const lexiconJSON = generateLexiconJSON();
+  const typesDTS = generateTypesDTS();
+  const indexTS = generateRuntimeIndex();
+
+  const resourceCount = HELM_TYPES.filter((t) => t.kind === "resource").length;
+  const propertyCount = HELM_TYPES.filter((t) => t.kind === "property").length;
+
+  log(`Generated ${resourceCount} resources, ${propertyCount} property types`);
+
+  return {
+    lexiconJSON,
+    typesDTS,
+    indexTS,
+    resources: resourceCount,
+    properties: propertyCount,
+    enums: 0,
+    warnings: [],
+  };
+}
+
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result: GenerateResult, baseDir: string): void {
+  writeGeneratedArtifacts({
+    baseDir,
+    files: {
+      "lexicon-helm.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+    },
+  });
+}

package/src/codegen/naming.ts

@@ -0,0 +1,38 @@
+/**
+ * Helm naming strategy — trivial mapping since Helm types are few and static.
+ *
+ * Maps Helm::{TypeName} → TypeName (e.g. Helm::Chart → Chart).
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+
+const helmNamingConfig: NamingConfig = {
+  priorityNames: {
+    "Helm::Chart": "Chart",
+    "Helm::Values": "Values",
+    "Helm::Test": "HelmTest",
+    "Helm::Notes": "HelmNotes",
+    "Helm::Hook": "HelmHook",
+    "Helm::Dependency": "HelmDependency",
+  },
+
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+
+  shortName: (typeName: string) => typeName.split("::").pop() ?? typeName,
+  serviceName: (_typeName: string) => "Helm",
+};
+
+/**
+ * Helm naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(inputs: NamingInput[]) {
+    super(inputs, helmNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,64 @@
+/**
+ * Helm lexicon packaging — delegates to core packagePipeline
+ * with Helm-specific manifest building and skill collection.
+ */
+
+import { createRequire } from "module";
+import { readFileSync } from "fs";
+const require = createRequire(import.meta.url);
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Package the Helm lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+
+      buildManifest: (_genResult) => {
+        return {
+          name: "helm",
+          version: pkgJson.version ?? "0.0.0",
+          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: {},
+        };
+      },
+
+      srcDir: pkgDir,
+
+      collectSkills: () => {
+        const { helmPlugin } = require("../plugin");
+        const skillDefs = helmPlugin.skills?.() ?? [];
+        return collectSkills(skillDefs);
+      },
+
+      version: pkgJson.version ?? "0.0.0",
+    },
+    opts,
+  );
+}