@intentius/chant-lexicon-helm 0.124.30 → 0.124.32

package/dist/project-codegen.js

@@ -0,0 +1,215 @@
+/**
+ * Typed Helm values: the helm lexicon's `projectCodegen` hook (`chant
+ * generate`, core's project-codegen.ts).
+ *
+ * For each chart a project lists under `helm.charts`, generation reads the
+ * chart's `values.schema.json` (or, without one, its `values.yaml`) and writes
+ * to `<outDir>/helm/index.ts`:
+ *
+ * - `<Name>Values`, the values type: from the schema, with every member
+ *   optional (the schema validates the values Helm merges with the chart's
+ *   defaults, so a key it requires is usually already set), or inferred from
+ *   `values.yaml` (./codegen/values-type.ts).
+ * - `<Name>Render(props)`, a factory that calls `HelmRender` with the repo,
+ *   chart and version from the config, so the type and the version it was
+ *   generated from cannot drift apart. It takes `HelmRender`'s other props.
+ *
+ * A remote chart is downloaded without the helm binary: an `oci://` chart
+ * through the registry API, a classic repository through its `index.yaml`.
+ * Both go through `ctx.fetch` when the caller passes one.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import yaml from "js-yaml";
+import { GENERATED_TS_HEADER } from "@intentius/chant/project-codegen";
+import { jsdocLines, schemaToTypeScript } from "@intentius/chant/codegen/json-schema-to-ts";
+import { fetchWithRetry } from "@intentius/chant/codegen/fetch";
+import { pullOciChart, readTarGz } from "@intentius/chant-lexicon-k8s/crd/oci-chart";
+import { CHART_KEY_PATTERN } from "./config.js";
+import { inferValuesType } from "./codegen/values-type.js";
+const CHART_FILES = ["Chart.yaml", "values.yaml", "values.schema.json"];
+/** The hook, with an injectable puller for remote charts. */
+export function helmProjectCodegen(options = {}) {
+    const pull = options.pull ?? pullRemoteChart;
+    return {
+        inputs(ctx) {
+            const charts = declaredCharts(ctx);
+            if (!charts)
+                return undefined;
+            return Object.fromEntries(charts.map(([key, chart]) => [key, describeChart(key, chart, ctx.projectRoot)]));
+        },
+        async generate(ctx) {
+            const charts = declaredCharts(ctx) ?? [];
+            const blocks = [];
+            const summary = [];
+            for (const [key, chart] of charts) {
+                describeChart(key, chart, ctx.projectRoot); // validates before any download
+                const files = "path" in chart ? readLocalChart(resolve(ctx.projectRoot, chart.path)) : await pull(chart, ctx.fetch);
+                const generated = renderChart(key, chart, files, ctx);
+                blocks.push(generated.code);
+                summary.push(generated.summary);
+            }
+            const local = charts.some(([, chart]) => "path" in chart);
+            return { files: { "index.ts": renderModule(blocks, local) }, summary };
+        },
+    };
+}
+function declaredCharts(ctx) {
+    const charts = ctx.config.helm?.charts;
+    if (!charts || Object.keys(charts).length === 0)
+        return undefined;
+    return Object.entries(charts).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * A chart as a JSON value for the drift digest: a local chart by the hashes
+ * of the files generation reads, a remote one by its pin.
+ */
+function describeChart(key, chart, projectRoot) {
+    if (!CHART_KEY_PATTERN.test(key)) {
+        throw new Error(`helm.charts.${key}: the key names the generated factory, so it must start with a letter and hold only letters, digits, - and _`);
+    }
+    if ("path" in chart) {
+        const dir = resolve(projectRoot, chart.path);
+        if (!existsSync(join(dir, "Chart.yaml")))
+            throw new Error(`helm.charts.${key}: no Chart.yaml in ${chart.path}`);
+        const hashes = {};
+        for (const file of CHART_FILES) {
+            const path = join(dir, file);
+            if (existsSync(path))
+                hashes[file] = createHash("sha256").update(readFileSync(path)).digest("hex");
+        }
+        return { path: chart.path, files: hashes };
+    }
+    if (!chart.version) {
+        throw new Error(`helm.charts.${key}: ${chart.chart} needs a version. An unpinned chart makes the generated types depend on when they were generated.`);
+    }
+    if (!chart.repo && !chart.chart.startsWith("oci://")) {
+        throw new Error(`helm.charts.${key}: ${chart.chart} needs a repo, or must be an oci:// reference`);
+    }
+    return {
+        ...(chart.repo ? { repo: chart.repo } : {}),
+        chart: chart.chart,
+        version: chart.version,
+        ...(chart.digest ? { digest: chart.digest } : {}),
+    };
+}
+function readLocalChart(dir) {
+    const read = (f) => (existsSync(join(dir, f)) ? readFileSync(join(dir, f), "utf8") : undefined);
+    return { chartYaml: read("Chart.yaml"), valuesYaml: read("values.yaml"), valuesSchema: read("values.schema.json") };
+}
+/** The top-level chart's files out of a chart archive (subcharts are ignored). */
+export function chartFilesFromArchive(files, label) {
+    const chartYamlPath = [...files.keys()].find((p) => p.split("/").length === 2 && p.endsWith("/Chart.yaml"));
+    if (!chartYamlPath)
+        throw new Error(`${label}: the archive has no top-level Chart.yaml`);
+    const dir = chartYamlPath.split("/")[0];
+    const read = (f) => files.get(`${dir}/${f}`)?.toString("utf8");
+    return { chartYaml: read("Chart.yaml"), valuesYaml: read("values.yaml"), valuesSchema: read("values.schema.json") };
+}
+/** Download a remote chart: OCI through the registry API, a classic repository through its index. */
+export async function pullRemoteChart(chart, fetchImpl) {
+    const label = `${chart.repo ? `${chart.repo} ` : ""}${chart.chart} ${chart.version}`;
+    if (!chart.repo) {
+        const http = fetchImpl ? { probe: fetchImpl, get: fetchImpl } : undefined;
+        const tgz = await pullOciChart(chart.chart, chart.version, chart.digest, http);
+        return chartFilesFromArchive(readTarGz(tgz), label);
+    }
+    const get = async (url) => {
+        const response = fetchImpl ? await fetchImpl(url) : await fetchWithRetry(url);
+        if (!response.ok)
+            throw new Error(`${url}: HTTP ${response.status}`);
+        return response;
+    };
+    const base = chart.repo.endsWith("/") ? chart.repo : `${chart.repo}/`;
+    // Failsafe: every scalar stays a string, so a digest of all digits or a
+    // version like 1.10 is read as written.
+    const index = yaml.load(await (await get(new URL("index.yaml", base).href)).text(), { schema: yaml.FAILSAFE_SCHEMA });
+    const entry = index?.entries?.[chart.chart]?.find((e) => e.version === chart.version);
+    if (!entry?.urls?.length)
+        throw new Error(`${label}: not in the repository's index.yaml`);
+    const tgz = Buffer.from(await (await get(new URL(entry.urls[0], base).href)).arrayBuffer());
+    const digest = createHash("sha256").update(tgz).digest("hex");
+    if (entry.digest && entry.digest !== digest) {
+        throw new Error(`${label}: the archive's sha256 is ${digest}, but the repository index says ${entry.digest}`);
+    }
+    if (chart.digest && chart.digest.replace(/^sha256:/, "") !== digest) {
+        throw new Error(`${label}: the archive's sha256 is ${digest}, but the config pins ${chart.digest}`);
+    }
+    return chartFilesFromArchive(readTarGz(tgz), label);
+}
+/** `ingress-nginx` -> `IngressNginx`. */
+export function factoryBase(key) {
+    return key
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}
+function renderChart(key, chart, files, ctx) {
+    const meta = (yaml.load(files.chartYaml) ?? {});
+    const base = factoryBase(key);
+    const valuesName = `${base}Values`;
+    const fnName = `${base}Render`;
+    const local = "path" in chart;
+    const chartName = local ? chart.path : chart.chart;
+    // A local chart is located from the generated module, so the render finds
+    // it whatever directory the build runs in.
+    const chartExpr = local
+        ? `chartPath(${JSON.stringify(relative(ctx.outDir, resolve(ctx.projectRoot, chart.path)).split(sep).join("/"))})`
+        : JSON.stringify(chart.chart);
+    const version = local ? meta.version : chart.version;
+    if (!version)
+        throw new Error(`helm.charts.${key}: ${chartName} has no version in Chart.yaml`);
+    const repo = local ? "" : (chart.repo ?? "");
+    const from = local ? `the chart at ${chartName}` : `${chart.chart} ${version}${chart.repo ? ` from ${chart.repo}` : ""}`;
+    const lines = [];
+    let source;
+    if (files.valuesSchema) {
+        let schema;
+        try {
+            schema = JSON.parse(files.valuesSchema);
+        }
+        catch (err) {
+            throw new Error(`helm.charts.${key}: values.schema.json does not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const { type, declarations } = schemaToTypeScript(schema, { allOptional: true, namePrefix: valuesName, rootName: valuesName });
+        for (const d of declarations)
+            lines.push(...jsdocLines(d.description, ""), `export type ${d.name} = ${d.type};`, "");
+        lines.push(`/** Values for ${from}, from its values.schema.json. */`, `export type ${valuesName} = ${type};`);
+        source = "values.schema.json";
+    }
+    else {
+        let values;
+        try {
+            values = files.valuesYaml ? yaml.load(files.valuesYaml) : undefined;
+        }
+        catch (err) {
+            throw new Error(`helm.charts.${key}: values.yaml does not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        lines.push(`/** Values for ${from}, inferred from its values.yaml defaults. */`, `export type ${valuesName} = ${inferValuesType(values)};`);
+        source = files.valuesYaml ? "values.yaml" : "no values file";
+    }
+    lines.push("", `/** \`${fnName}\`'s props: \`HelmRender\`'s, with the chart fixed by chant.config and \`values\` typed. */`, `export type ${fnName}Props = Omit<HelmRenderProps, "repo" | "chart" | "version" | "values"> & { values?: ${valuesName} };`, "", `/** Render ${from}. */`, `export function ${fnName}(props: ${fnName}Props) {`, "  return HelmRender({", "    ...props,", `    repo: ${JSON.stringify(repo)},`, `    chart: ${chartExpr},`, `    version: ${JSON.stringify(version)},`, "    values: props.values as Record<string, unknown> | undefined,", "  });", "}");
+    return { code: lines.join("\n"), summary: `${fnName} (${meta.name ?? chartName} ${version}, values from ${source})` };
+}
+function renderModule(blocks, local) {
+    return [
+        GENERATED_TS_HEADER,
+        "// Typed render factories for the charts helm.charts declares in chant.config.",
+        ...(local ? ['import { relative } from "node:path";', 'import { fileURLToPath } from "node:url";'] : []),
+        'import { HelmRender, type HelmRenderProps } from "@intentius/chant-lexicon-helm";',
+        ...(local
+            ? [
+                "",
+                "/** A chart directory given relative to this module, as a path from the working directory. */",
+                "function chartPath(fromHere: string): string {",
+                '  return relative(process.cwd(), fileURLToPath(new URL(fromHere, import.meta.url))) || ".";',
+                "}",
+            ]
+            : []),
+        "",
+        blocks.join("\n\n"),
+        "",
+    ].join("\n");
+}

package/dist/release-observe.js

@@ -0,0 +1,287 @@
+/**
+ * Release-scoped observation plumbing, shared by the helm lexicon's
+ * `describeResources` (#1246) and `observeResourcesDeep` (#1247).
+ *
+ * The helm lexicon's runtime unit is the release: the chant project declares
+ * a `Helm::Chart`, `helm upgrade --install` turns it into a release, and the
+ * release stores the rendered manifests it applied. Observation therefore
+ * resolves each declared chart to its release (via `helm list`, the same
+ * read `listArtifacts` has always used) and reads what the release holds.
+ *
+ * Two channels, both mandatory (#1246): `helm get manifest` reports the
+ * non-hook documents and `helm get hooks` reports the hook resources —
+ * hooks are excluded from the manifest channel, so reading one channel
+ * would report every hook resource as drift.
+ *
+ * Failure discipline is the observation contract (#1089): a missing helm
+ * binary or an unreachable cluster is NOT-OBSERVED with a total reason,
+ * never a clean empty result that classifies as N creates. Only a release
+ * that `helm list` was asked about and did not report is an absence.
+ *
+ * Cluster selection follows #1488, same as `list-artifacts.ts` and
+ * `describe-stack-status.ts`: the environment's declared k8s binding
+ * (`k8s.profiles.<env>.context`) rides as `--kube-context` when present;
+ * ambient otherwise.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { loadAll } from "js-yaml";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+import { gvkToTypeName } from "@intentius/chant-lexicon-k8s/spec/parse";
+// `helm get manifest` for a large chart is several megabytes, past node's
+// default 1MiB exec buffer — the same truncation `helm-upgrade.ts` hit live.
+const execP = promisify(exec);
+const defaultRunner = (command) => execP(command, { maxBuffer: 64 * 1024 * 1024 });
+export { defaultRunner as defaultHelmRunner };
+export const HELM_CHART_ENTITY_TYPE = "Helm::Chart";
+export const HELM_RELEASE_TYPE = "Helm::Release";
+/** Shell-quote one argv element, same convention as `helm-upgrade.ts`. */
+export function q(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The environment's kube context (#1488): the declared binding when present,
+ * ambient otherwise. Unresolvable config is ambient, chant's own fallback —
+ * identical to `list-artifacts.ts`.
+ */
+export async function resolveHelmContext(environment) {
+    try {
+        const { config } = await loadChantConfigUpward(process.cwd());
+        return (await resolveClusterTarget(config, environment, "helm")).context;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Total verdict for a failed helm invocation (#1089/#1246). A missing binary
+ * and a missing/unusable kubeconfig are both `no-credentials` — the read had
+ * no usable way to reach the target. Anything else the CLI refused is
+ * `read-failed`.
+ */
+export function classifyHelmFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err?.code;
+    if (code === "ENOENT" ||
+        code === 127 ||
+        /command not found|not recognized|ENOENT/i.test(message)) {
+        return { reason: "no-credentials", detail: "helm binary not found on PATH" };
+    }
+    if (/kubeconfig|kubernetes cluster unreachable|unauthorized|forbidden|no configuration has been provided|connection refused/i.test(message)) {
+        return { reason: "no-credentials", detail: firstLine(message) };
+    }
+    return { reason: "read-failed", detail: firstLine(message) };
+}
+function firstLine(message) {
+    const line = message.split("\n").find((l) => l.trim().length > 0);
+    return (line ?? message).trim();
+}
+/**
+ * Kinds that are cluster-scoped, so a document without `metadata.namespace`
+ * must not inherit the release namespace. Well-known built-ins only; a
+ * cluster-scoped CRD instance this set does not name defaults to the release
+ * namespace, which affects the row's address, never its verdict.
+ */
+export const CLUSTER_SCOPED_KINDS = new Set([
+    "Namespace",
+    "CustomResourceDefinition",
+    "ClusterRole",
+    "ClusterRoleBinding",
+    "StorageClass",
+    "PriorityClass",
+    "IngressClass",
+    "PersistentVolume",
+    "ValidatingWebhookConfiguration",
+    "MutatingWebhookConfiguration",
+    "APIService",
+    "RuntimeClass",
+    "CSIDriver",
+    "CSINode",
+]);
+/** The declared chart entities, with the release name each one deploys as. */
+export function chartEntities(entities) {
+    const charts = [];
+    for (const [entityName, entity] of entities) {
+        if (entity.entityType !== HELM_CHART_ENTITY_TYPE)
+            continue;
+        const name = entity.props?.name;
+        charts.push({ entityName, release: typeof name === "string" && name ? name : entityName });
+    }
+    return charts;
+}
+function parseStack(stack) {
+    const slash = stack.indexOf("/");
+    return slash > 0
+        ? { namespace: stack.slice(0, slash), release: stack.slice(slash + 1) }
+        : { release: stack };
+}
+/**
+ * Find the list entry for one declared chart. Release identity resolves in
+ * order: the deploy unit (`stack`), a release named after the chart, then a
+ * unique release whose `chart` field is `<chartName>-<version>` — the release
+ * installed from this chart under another name. Ambiguity resolves to
+ * nothing: two candidate releases are not an identity.
+ */
+function findRelease(entries, release, wantNamespace, chartName) {
+    const named = entries.filter((e) => e.name === release && (wantNamespace === undefined || e.namespace === wantNamespace));
+    if (named.length === 1)
+        return { entry: named[0] };
+    if (named.length > 1) {
+        // The same release name in several namespaces is not an identity — and
+        // not an absence either. Say which namespaces so the caller can scope
+        // the read with a deploy unit (`<namespace>/<release>`).
+        return { ambiguous: named.map((e) => e.namespace).join(", ") };
+    }
+    const byChart = entries.filter((e) => typeof e.chart === "string" && new RegExp(`^${escapeRegExp(chartName)}-\\d`).test(e.chart));
+    return byChart.length === 1 ? { entry: byChart[0] } : undefined;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Parse one channel's multi-document YAML stream into per-resource rows. */
+export function parseReleaseDocuments(text, channel, releaseNamespace) {
+    const rows = [];
+    let docs;
+    try {
+        docs = loadAll(text);
+    }
+    catch {
+        return rows;
+    }
+    for (const raw of docs) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            continue;
+        const doc = raw;
+        const apiVersion = typeof doc.apiVersion === "string" ? doc.apiVersion : undefined;
+        const kind = typeof doc.kind === "string" ? doc.kind : undefined;
+        const metadata = doc.metadata;
+        const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+        if (!apiVersion || !kind || !name)
+            continue;
+        const clusterScoped = CLUSTER_SCOPED_KINDS.has(kind) && typeof metadata?.namespace !== "string";
+        const namespace = clusterScoped
+            ? undefined
+            : typeof metadata?.namespace === "string"
+                ? metadata.namespace
+                : releaseNamespace; // helm applies the release namespace to namespace-silent documents
+        const slash = apiVersion.indexOf("/");
+        const entityType = gvkToTypeName({
+            group: slash > 0 ? apiVersion.slice(0, slash) : "",
+            version: slash > 0 ? apiVersion.slice(slash + 1) : apiVersion,
+            kind,
+        });
+        const annotations = metadata?.annotations ?? {};
+        const hookAnnotation = annotations["helm.sh/hook"];
+        const hook = channel === "hooks" && typeof hookAnnotation === "string"
+            ? {
+                hook: hookAnnotation,
+                ...(typeof annotations["helm.sh/hook-weight"] === "string"
+                    ? { weight: annotations["helm.sh/hook-weight"] }
+                    : {}),
+                ...(typeof annotations["helm.sh/hook-delete-policy"] === "string"
+                    ? { deletePolicy: annotations["helm.sh/hook-delete-policy"] }
+                    : {}),
+            }
+            : undefined;
+        rows.push({
+            key: namespace ? `${kind}/${namespace}/${name}` : `cluster:${kind}/${name}`,
+            apiVersion,
+            kind,
+            name,
+            ...(namespace ? { namespace } : {}),
+            channel,
+            entityType,
+            doc,
+            ...(hook ? { hook } : {}),
+        });
+    }
+    return rows;
+}
+/**
+ * Resolve every declared chart to its release and read both channels.
+ * Never throws for a per-release failure; a whole-read failure (the `helm
+ * list` itself) lands every chart entity in `unobserved` with one reason.
+ */
+export async function observeReleases(options, run = defaultRunner) {
+    const charts = chartEntities(options.entities);
+    const result = { releases: [], absent: [], unobserved: {}, queried: {} };
+    if (charts.length === 0)
+        return result;
+    const stack = options.stack ? parseStack(options.stack) : undefined;
+    // The deploy unit names the release when the project has one chart — the
+    // component flow deploys each chart under the step's `release`, which need
+    // not equal the chart name.
+    if (stack && charts.length === 1)
+        charts[0].release = stack.release;
+    const context = await resolveHelmContext(options.environment);
+    const ctxFlag = context ? ` --kube-context ${q(context)}` : "";
+    const listCommand = `helm list -A -o json${ctxFlag}`;
+    let entries;
+    try {
+        const { stdout } = await run(listCommand);
+        const parsed = JSON.parse(stdout);
+        if (!Array.isArray(parsed))
+            throw new Error("helm list returned non-array JSON");
+        entries = parsed;
+    }
+    catch (err) {
+        const { reason, detail } = classifyHelmFailure(err);
+        for (const { entityName } of charts) {
+            result.unobserved[entityName] = { type: HELM_CHART_ENTITY_TYPE, reason, detail };
+            result.queried[entityName] = listCommand;
+        }
+        return result;
+    }
+    for (const { entityName, release } of charts) {
+        const found = findRelease(entries, release, stack?.namespace, release);
+        if (found && "ambiguous" in found) {
+            result.unobserved[entityName] = {
+                type: HELM_CHART_ENTITY_TYPE,
+                reason: "read-failed",
+                detail: `release "${release}" exists in several namespaces (${found.ambiguous}) — scope the read with a <namespace>/<release> deploy unit`,
+            };
+            result.queried[entityName] = listCommand;
+            continue;
+        }
+        const entry = found?.entry;
+        if (!entry || !entry.name || !entry.namespace) {
+            result.absent.push(entityName);
+            result.queried[entityName] = listCommand;
+            continue;
+        }
+        const base = `-n ${q(entry.namespace)}${ctxFlag}`;
+        const manifestCommand = `helm get manifest ${q(entry.name)} ${base}`;
+        const hooksCommand = `helm get hooks ${q(entry.name)} ${base}`;
+        result.queried[entityName] = manifestCommand;
+        let manifestText;
+        let hooksText;
+        try {
+            ({ stdout: manifestText } = await run(manifestCommand));
+            ({ stdout: hooksText } = await run(hooksCommand));
+        }
+        catch (err) {
+            // The release exists but what it holds could not be read — an
+            // unreachable release is NOT-OBSERVED with a reason, never absent and
+            // never a clean row that claims nothing drifted (#1246).
+            const { reason, detail } = classifyHelmFailure(err);
+            result.unobserved[entityName] = { type: HELM_CHART_ENTITY_TYPE, reason, detail };
+            continue;
+        }
+        result.releases.push({
+            entityName,
+            release: entry.name,
+            namespace: entry.namespace,
+            ...(entry.status ? { status: entry.status } : {}),
+            ...(entry.revision ? { revision: entry.revision } : {}),
+            ...(entry.chart ? { chart: entry.chart } : {}),
+            ...(entry.app_version ? { appVersion: entry.app_version } : {}),
+            ...(entry.updated ? { updated: entry.updated } : {}),
+            resources: [
+                ...parseReleaseDocuments(manifestText, "manifest", entry.namespace),
+                ...parseReleaseDocuments(hooksText, "hooks", entry.namespace),
+            ],
+        });
+    }
+    return result;
+}