@intentius/chant-lexicon-helm 0.124.31 → 0.124.33

package/dist/archive-render.js

@@ -0,0 +1,76 @@
+/**
+ * `addArchiveHelmRender` — fold a pinned render into a `BuildArchiveManifest`
+ * (#1240, epic #1228 Phase 3).
+ *
+ * #1238 gave a pinned render durable, content-addressed storage
+ * (./render-store.ts's `RenderManifest`, modeled on core's
+ * `BuildArchiveManifest`). This module is the seam between the two: it folds
+ * one render into a *build archive*'s manifest, the same self-contained
+ * bundle `docker-build`/`addArchiveTemplate` write into
+ * (packages/core/src/components/verbs/build-archive.ts), so a component that
+ * composes a `HelmRender` alongside an image/template gets one archive that
+ * carries all of it.
+ *
+ * A rendered chart is a template: it reuses `kind: "template"` rather than
+ * adding a new `BuildArchiveEntryKind`. What distinguishes a render from a
+ * synthesized CloudFormation/other IaC template is only its media type,
+ * `HELM_RENDER_MEDIA_TYPE` — and that is enough. Core's
+ * `lifecycle/oras-referrer-lookup.ts` classifies *referrers* (SBOM/
+ * provenance/signature) by the referrer's own media type, keyed only by the
+ * subject *digest* it discovers against — never by the subject entry's own
+ * `kind`/`mediaType`. A render's digest is therefore attachable exactly like
+ * an image's: `oras discover <repo>@<renderDigest>` finds the same
+ * referrers a signing/attestation pipeline would attach to any other
+ * artifact, with no change to that lookup needed (see
+ * ./archive-render.test.ts for the referrer-classification proof).
+ *
+ * Mirrors `addArchiveTemplate` (packages/core/src/components/verbs/build.ts)
+ * in every way that matters: a plain, pure function (not a registered
+ * capability — rendering happens at chant's existing build/synth time, not
+ * as a new deploy-time verb), accumulates onto a caller-supplied manifest so
+ * a component's whole build phase shares one archive, and threads an
+ * optional `sourceRef` into a `provenance` link (#614). It differs in one
+ * respect: rather than recomputing a digest from raw content bytes (core's
+ * `contentDigest`), it reuses the render's own `contentDigest` — the real
+ * `sha256:` over the canonical rendered stream that `helmContentDigest`
+ * already computed and `persistHelmRender` already wrote to the render
+ * store — so the archive entry's identity and the render store's identity
+ * are the same digest, not two independent hashes of the same bytes.
+ */
+import { addArchiveEntry, createBuildArchiveManifest, } from "@intentius/chant/components/verbs/build-archive";
+/**
+ * Media type for a pinned helm render folded into a build archive as a
+ * `template`-kind entry. `v1` names the canonical-stream shape
+ * `canonicalizeRender` (./render-digest.ts) produces — a versioned suffix so
+ * a future incompatible canonicalization can be told apart from this one
+ * without guessing from content alone.
+ */
+export const HELM_RENDER_MEDIA_TYPE = "application/vnd.chant.helm-render.v1+yaml";
+/**
+ * Fold one pinned render into a build archive's manifest as a
+ * `template`-kind entry with `mediaType: HELM_RENDER_MEDIA_TYPE` — the
+ * render peer of `addArchiveTemplate`. The entry's digest is the render's
+ * own `contentDigest` (real `sha256:` over the canonical rendered stream,
+ * ./render-digest.ts's `helmContentDigest`), so the same digest that keys
+ * the render store's `sha256-<hex>/` entry (./render-store.ts) also keys
+ * this archive entry — one identity, not a second hash of the same bytes.
+ * Adding the entry recomputes `manifest.manifestDigest`
+ * (`computeManifestDigest`), so the render rolls into the archive's own
+ * aggregate identity exactly as an image or template does.
+ */
+export function addArchiveHelmRender(input) {
+    const digest = input.render.contentDigest;
+    const base = input.manifest ?? createBuildArchiveManifest("unknown");
+    const sourceRef = input.sourceRef ?? input.render.sourceRef ?? undefined;
+    const provenance = sourceRef
+        ? { sourceRef, artifactDigest: digest }
+        : undefined;
+    const manifest = addArchiveEntry(base, {
+        kind: "template",
+        path: input.path,
+        digest,
+        mediaType: HELM_RENDER_MEDIA_TYPE,
+        ...(provenance ? { provenance } : {}),
+    });
+    return { digest, manifest };
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,113 @@
+/**
+ * Documentation generation for the Helm lexicon.
+ *
+ * Generates Starlight MDX pages for Helm entities using the core docs pipeline.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Helm";
+}
+const overview = `The **Helm** lexicon generates production-quality, parameterized Helm charts from TypeScript.
+
+Unlike static manifest generators, the Helm lexicon produces real \`{{ .Values.x }}\` directives, \`values.yaml\`, \`values.schema.json\`, conditional resources, Helm hooks, and standard \`_helpers.tpl\`.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-helm @intentius/chant-lexicon-k8s
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+import { Chart, Values } from "@intentius/chant-lexicon-helm";
+import { values, include, printf, toYaml } from "@intentius/chant-lexicon-helm";
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+export const chart = new Chart({
+  apiVersion: "v2",
+  name: "my-app",
+  version: "0.1.0",
+  type: "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,
+    template: {
+      spec: {
+        containers: [{
+          name: "my-app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          ports: [{ containerPort: values.service.port, name: "http" }],
+          resources: toYaml(values.resources),
+        }],
+      },
+    },
+  },
+});
+\`\`\`
+
+Build the chart:
+
+\`\`\`bash
+chant build
+helm lint dist/
+helm template test dist/
+\`\`\`
+`;
+const outputFormat = `## Output structure
+
+The Helm serializer produces a complete chart directory:
+
+\`\`\`
+dist/
+  Chart.yaml              ← from Chart entity
+  values.yaml             ← from Values entity (defaults)
+  values.schema.json      ← auto-generated JSON Schema from Values types
+  .helmignore
+  templates/
+    _helpers.tpl          ← auto-generated standard helpers
+    deployment.yaml       ← K8s resources with {{ .Values.x }} directives
+    service.yaml
+    NOTES.txt             ← from HelmNotes entity
+    tests/
+      test-connection.yaml ← from HelmTest entities
+\`\`\`
+`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "helm",
+        displayName: "Helm",
+        description: "Typed constructors for parameterized Helm charts",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/helm/",
+        overview,
+        outputFormat,
+        serviceFromType,
+        // `lint-rules` under docs/pages/ is helm's rules documentation; the
+        // generated `rules` table duplicated it, and helm's own declared rules
+        // page was being silently overwritten by that table (#1312).
+        suppressPages: ["pseudo-parameters"],
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Helm lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    console.error("Generating Helm lexicon (static types)...");
+    const result = await generate({ verbose });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types`);
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate.js

@@ -0,0 +1,210 @@
+/**
+ * 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, } from "@intentius/chant/codegen/generate";
+const HELM_TYPES = [
+    {
+        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() {
+    const registry = {};
+    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() {
+    const lines = [
+        '// 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() {
+    const lines = [
+        '// 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");
+}
+/**
+ * Run the Helm generation pipeline.
+ * Since Helm types are static, this doesn't fetch anything.
+ */
+export async function generate(opts = {}) {
+    const log = opts.verbose
+        ? (msg) => console.error(msg)
+        : (_msg) => { };
+    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, baseDir) {
+    writeGeneratedArtifacts({
+        baseDir,
+        files: {
+            "lexicon-helm.json": result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+        },
+    });
+}

package/dist/codegen/naming.js

@@ -0,0 +1,29 @@
+/**
+ * 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, } from "@intentius/chant/codegen/naming";
+const helmNamingConfig = {
+    priorityNames: {
+        "Helm::Chart": "Chart",
+        "Helm::Values": "Values",
+        "Helm::Test": "HelmTest",
+        "Helm::Notes": "HelmNotes",
+        "Helm::Hook": "HelmHook",
+        "Helm::Dependency": "HelmDependency",
+    },
+    priorityAliases: {},
+    priorityPropertyAliases: {},
+    serviceAbbreviations: {},
+    shortName: (typeName) => typeName.split("::").pop() ?? typeName,
+    serviceName: (_typeName) => "Helm",
+};
+/**
+ * Helm naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+    constructor(inputs) {
+        super(inputs, helmNamingConfig);
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,44 @@
+/**
+ * Helm lexicon packaging — delegates to core packagePipeline
+ * with Helm-specific manifest building and skill collection.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { helmPlugin } from "../plugin.js";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
+/**
+ * Package the Helm lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts = {}) {
+    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",
+                // Derived from the plugin's own registration (chant #1067) — this
+                // used to be a hand-maintained array of 7 entries, independent of
+                // ../plugin.ts's real registration (which has grown to 22) and
+                // never updated to match. That drift is exactly why an
+                // independent second source of truth for the same data is
+                // dangerous: the generated intrinsics doc page (chant #1062) was
+                // silently reporting "7 intrinsic functions" for a lexicon that
+                // ships 22.
+                intrinsics: helmPlugin.intrinsics?.() ?? [],
+                pseudoParameters: {},
+            };
+        },
+        srcDir: pkgDir,
+        collectSkills: () => {
+            const skillDefs = helmPlugin.skills?.() ?? [];
+            return collectSkills(skillDefs);
+        },
+        version: pkgJson.version ?? "0.0.0",
+    }, opts);
+}

package/dist/codegen/values-type.js

@@ -0,0 +1,87 @@
+/**
+ * A TypeScript type for a chart's values when the chart ships no
+ * `values.schema.json`, inferred from its `values.yaml` defaults.
+ *
+ * Every member is optional, since an override sets any subset. An object's
+ * keys are the ones `values.yaml` lists and no others, so a misspelled key
+ * fails to typecheck. A default that says nothing about its type becomes
+ * `unknown`: a `null` or empty value (`key:` or `key: ~`) is `unknown`, an
+ * empty object (`podAnnotations: {}`) a map of `unknown`, an empty list an
+ * array of `unknown`. An empty string is still a string. Keys are quoted
+ * when they are not identifiers and never renamed.
+ */
+import { tsPropertyKey } from "@intentius/chant/codegen/json-schema-to-ts";
+/** The type expression for a parsed `values.yaml` document. */
+export function inferValuesType(values) {
+    if (values === null || values === undefined)
+        return "Record<string, unknown>";
+    return render(shape(values), "");
+}
+function shape(value) {
+    if (value === null || value === undefined)
+        return { kind: "unknown" };
+    if (typeof value === "string")
+        return { kind: "scalar", type: "string" };
+    if (typeof value === "number")
+        return { kind: "scalar", type: "number" };
+    if (typeof value === "boolean")
+        return { kind: "scalar", type: "boolean" };
+    if (value instanceof Date)
+        return { kind: "scalar", type: "string" };
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return { kind: "array", element: { kind: "unknown" } };
+        return { kind: "array", element: value.map(shape).reduce(merge) };
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return { kind: "map" };
+        return { kind: "object", members: new Map(entries.map(([k, v]) => [k, shape(v)])) };
+    }
+    return { kind: "unknown" };
+}
+/** Combine the shapes of two list elements: objects merge their keys, anything else unions. */
+function merge(a, b) {
+    if (a.kind === "unknown" || b.kind === "unknown")
+        return { kind: "unknown" };
+    if (a.kind === "object" && b.kind === "object") {
+        const members = new Map(a.members);
+        for (const [k, s] of b.members)
+            members.set(k, members.has(k) ? merge(members.get(k), s) : s);
+        return { kind: "object", members };
+    }
+    if (a.kind === "scalar" && b.kind === "scalar" && a.type === b.type)
+        return a;
+    if (a.kind === "map" && b.kind === "map")
+        return a;
+    if (a.kind === "array" && b.kind === "array")
+        return { kind: "array", element: merge(a.element, b.element) };
+    const shapes = [...(a.kind === "union" ? a.shapes : [a]), ...(b.kind === "union" ? b.shapes : [b])];
+    return { kind: "union", shapes };
+}
+function render(s, indent) {
+    switch (s.kind) {
+        case "unknown":
+            return "unknown";
+        case "scalar":
+            return s.type;
+        case "map":
+            return "Record<string, unknown>";
+        case "array": {
+            const element = render(s.element, indent);
+            return /^[A-Za-z]+$/.test(element) ? `${element}[]` : `Array<${element}>`;
+        }
+        case "union":
+            return [...new Set(s.shapes.map((x) => render(x, indent)))].join(" | ");
+        case "object": {
+            const inner = indent + "  ";
+            const lines = ["{"];
+            for (const [key, member] of s.members) {
+                lines.push(`${inner}${tsPropertyKey(key)}?: ${render(member, inner)};`);
+            }
+            lines.push(`${indent}}`);
+            return lines.join("\n");
+        }
+    }
+}