@intentius/chant-lexicon-helm 0.45.0 → 0.49.0

package/src/config.ts

@@ -0,0 +1,220 @@
+/**
+ * Helm capability profiles — the `helm` namespace in `chant.config.ts` (#1235,
+ * epic #1228 Phase 1).
+ *
+ * `helm template` looks like a pure function of (chart, values) and is not:
+ * `.Capabilities.KubeVersion` defaults to a version baked into the helm
+ * binary (v1.31.0 on helm 3.16.2, v1.35.0 on 4.1.1), and
+ * `.Capabilities.APIVersions` is silently empty offline. Two engineers on
+ * different helm versions therefore render different bytes from identical
+ * inputs unless the capability profile is declared. Declaring it closes both
+ * inputs: `--kube-version` and `--api-versions` are passed on every render
+ * that references a profile, so the render is a function of
+ * (chart, values, profile) and its digest means something.
+ *
+ * Profiles are scoped **per cluster** (see the epic's Decisions): each
+ * cluster declares its own `kubeVersion` / `apiVersions`, and a render is
+ * pinned against exactly one profile. This mirrors how the k8s lexicon binds
+ * environments to clusters (`k8s.profiles.<env>.context`, chant #1100) — a
+ * capability profile is the same per-cluster fact seen from the render side.
+ *
+ * ```ts
+ * export default {
+ *   lexicons: ["helm", "k8s"],
+ *   helm: {
+ *     capabilityProfiles: {
+ *       prod: { kubeVersion: "1.33.6", apiVersions: ["monitoring.coreos.com/v1"] },
+ *       staging: { kubeVersion: "1.31.4", apiVersions: [] },
+ *     },
+ *   },
+ * };
+ * ```
+ *
+ * A `HelmRender` references a profile by name (`capabilityProfile: "prod"`)
+ * or carries one inline. No profile keeps today's unpinned behavior; a
+ * reference that resolves to nothing is a build error naming the profile —
+ * never a silent fallback to the binary's default.
+ *
+ * Follows the k8s lexicon's config seam (#1344): the zod schema is the
+ * runtime half core validates the namespace with, the interface is the
+ * compile-time half projects write `satisfies` against, and the agreement
+ * type at the bottom keeps the two from drifting.
+ */
+
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import { findProjectConfig } from "@intentius/chant/project-root";
+import { evaluateProjectConfigSync } from "@intentius/chant/config-sandbox";
+
+/**
+ * What `--kube-version` accepts: `1.33`, `1.33.6`, `v1.33.6`. Deliberately
+ * looser than full semver (no prerelease/build tags — helm's capability
+ * parsing does not want them) and tighter than "any string" (a typo like
+ * `"latest"` must fail at declaration, not render as garbage).
+ */
+export const KUBE_VERSION_PATTERN = /^v?\d+\.\d+(\.\d+)?$/;
+
+/**
+ * One cluster's declared capabilities, as written in
+ * `helm.capabilityProfiles.<name>`. The profile's name is the record key.
+ */
+export interface HelmCapabilityProfileConfig {
+  /** Kubernetes version the cluster runs, e.g. `"1.33.6"` — passed as `--kube-version`. */
+  kubeVersion: string;
+  /**
+   * API versions available on the cluster beyond the core set, e.g.
+   * `"monitoring.coreos.com/v1"` — each passed as `--api-versions`. Omit (or
+   * declare empty) for a cluster with no extra API groups charts probe for.
+   */
+  apiVersions?: string[];
+}
+
+/** A resolved capability profile: the declared facts plus the name they were declared under. */
+export interface HelmCapabilityProfile extends HelmCapabilityProfileConfig {
+  /** The profile's declared name (the `helm.capabilityProfiles` key, or the inline `name`). */
+  name: string;
+}
+
+/**
+ * How a `HelmRender` names its profile: a string resolved against
+ * `helm.capabilityProfiles`, or an inline profile object for the rare render
+ * whose cluster facts live nowhere else.
+ */
+export type HelmCapabilityProfileRef = string | HelmCapabilityProfile;
+
+export interface HelmChantConfig {
+  /** Per-cluster capability profiles, keyed by profile (cluster/environment) name. */
+  capabilityProfiles?: Record<string, HelmCapabilityProfileConfig>;
+}
+
+export const helmCapabilityProfileSchema = z.strictObject({
+  kubeVersion: z
+    .string()
+    .regex(KUBE_VERSION_PATTERN, 'must be a Kubernetes version like "1.33.6" or "v1.33"'),
+  apiVersions: z.array(z.string().min(1, "apiVersions entries must be non-empty strings")).optional(),
+});
+
+export const helmConfigSchema = z.strictObject({
+  capabilityProfiles: z.record(z.string(), helmCapabilityProfileSchema).optional(),
+});
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    helm?: HelmChantConfig;
+  }
+}
+
+/**
+ * Compile-time proof the augmentation above reaches `ChantConfig` — the same
+ * guard the k8s and forgejo lexicons carry (#1344). Without it, a project
+ * writing the documented snippet with `satisfies ChantConfig` fails to
+ * compile and nothing in this repo notices.
+ */
+export type HelmConfigNamespace = NonNullable<ChantConfig["helm"]>;
+
+/**
+ * The schema and the documented interface describe the same namespace. If a
+ * field is added to one and not the other, this stops compiling.
+ */
+type SchemaMatchesInterface = z.infer<typeof helmConfigSchema> extends HelmChantConfig
+  ? HelmChantConfig extends z.infer<typeof helmConfigSchema>
+    ? true
+    : never
+  : never;
+export type _SchemaAgreesWithInterface = SchemaMatchesInterface;
+
+/**
+ * Validate a resolved profile's fields. Returns one message per problem,
+ * each naming the profile — empty when the profile is sound.
+ *
+ * Config-declared profiles are already schema-checked at config load
+ * (`helmConfigSchema` via the plugin's `configSchema`); this covers inline
+ * profiles handed straight to `HelmRender`, and re-checks resolved ones so a
+ * config loaded outside the CLI (a bare API caller) fails identically.
+ */
+export function validateCapabilityProfile(profile: HelmCapabilityProfile): string[] {
+  const errors: string[] = [];
+  const label = typeof profile.name === "string" && profile.name.length > 0 ? `"${profile.name}"` : "(unnamed)";
+  if (typeof profile.name !== "string" || profile.name.length === 0) {
+    errors.push("helm capability profile: name must be a non-empty string");
+  }
+  if (typeof profile.kubeVersion !== "string" || !KUBE_VERSION_PATTERN.test(profile.kubeVersion)) {
+    errors.push(
+      `helm capability profile ${label}: kubeVersion must be a Kubernetes version like "1.33.6" or "v1.33", got ${JSON.stringify(profile.kubeVersion)}`,
+    );
+  }
+  if (profile.apiVersions !== undefined) {
+    if (!Array.isArray(profile.apiVersions)) {
+      errors.push(`helm capability profile ${label}: apiVersions must be an array of non-empty strings`);
+    } else {
+      for (const entry of profile.apiVersions) {
+        if (typeof entry !== "string" || entry.length === 0) {
+          errors.push(
+            `helm capability profile ${label}: apiVersions entries must be non-empty strings, got ${JSON.stringify(entry)}`,
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Synchronously load the nearest project config's raw object, walking upward
+ * from `startDir` exactly like `loadChantConfigUpward` (`findProjectConfig`
+ * is the shared walk). Synchronous because `HelmRender` resolves at synth
+ * time inside a composite factory — the same constraint that gave
+ * `chant lint` `evaluateProjectConfigSync`, which this reuses so the
+ * sandbox boundary (chant #1113) stays in one place.
+ */
+function loadProjectConfigSync(startDir: string): { config: ChantConfig; configPath?: string } {
+  const { dir, configPath } = findProjectConfig(startDir);
+  if (!configPath) return { config: {} };
+  if (configPath.endsWith(".json")) {
+    return { config: JSON.parse(readFileSync(configPath, "utf8")) as ChantConfig, configPath };
+  }
+  return { config: evaluateProjectConfigSync(configPath, dir) as ChantConfig, configPath };
+}
+
+/**
+ * Resolve a `HelmRender`'s profile reference to a concrete profile.
+ *
+ * - An inline profile object is validated and returned as-is.
+ * - A string is looked up in `helm.capabilityProfiles` of the nearest
+ *   `chant.config.ts`/`.json` above `opts.startDir` (default: cwd).
+ *
+ * A reference that resolves to nothing throws, naming the missing profile,
+ * the profiles that ARE declared, and where to declare it — a declared but
+ * unresolvable profile must be a build error, never a silent fall-through to
+ * the helm binary's default capabilities (epic #1228, finding 1).
+ */
+export function resolveCapabilityProfile(
+  ref: HelmCapabilityProfileRef,
+  opts?: { startDir?: string },
+): HelmCapabilityProfile {
+  if (typeof ref !== "string") {
+    const errors = validateCapabilityProfile(ref);
+    if (errors.length > 0) throw new Error(errors.join("\n"));
+    return ref;
+  }
+
+  const startDir = opts?.startDir ?? process.cwd();
+  const { config, configPath } = loadProjectConfigSync(startDir);
+  const profiles = config.helm?.capabilityProfiles;
+  const declared = profiles?.[ref];
+  if (!declared) {
+    const names = Object.keys(profiles ?? {});
+    const where = configPath ?? `chant.config.ts (no config found above ${startDir})`;
+    throw new Error(
+      `helm capability profile "${ref}" is not declared` +
+        (names.length > 0 ? ` — declared profiles: ${names.join(", ")}` : "") +
+        `. Declare it as helm.capabilityProfiles.${ref} = { kubeVersion, apiVersions } in ${where}.`,
+    );
+  }
+
+  const profile: HelmCapabilityProfile = { name: ref, ...declared };
+  const errors = validateCapabilityProfile(profile);
+  if (errors.length > 0) throw new Error(errors.join("\n"));
+  return profile;
+}

package/src/deep-observe-hooks.ts

@@ -0,0 +1,20 @@
+/**
+ * The helm lexicon's deep-observation noise rules (#1247) — the k8s
+ * lexicon's, by reference.
+ *
+ * Everything a Helm release deploys is a Kubernetes object, so the rules for
+ * which fields are server-populated, which defaults are noise, which arrays
+ * are sets, and which Secret paths must be masked are exactly the k8s
+ * lexicon's `k8sDeepNormalizationHooks`. This is deliberately the same
+ * *object*, not a copy: core applies `deepNormalizationHooks` to the
+ * declared tree as well as the live one (`lexicon.ts`), and two lists would
+ * drift apart the first time one gained a rule.
+ *
+ * Static-import safe for the same reason the k8s module is: the hooks file
+ * carries no `@intentius/chant-k8s-client` dependency, so `plugin.ts` can
+ * expose it as plain data without pulling the live-read machinery into the
+ * build path.
+ */
+import { k8sDeepNormalizationHooks } from "@intentius/chant-lexicon-k8s/deep-observe-hooks";
+
+export const helmDeepNormalizationHooks = k8sDeepNormalizationHooks;

package/src/deep-observe.test.ts

@@ -0,0 +1,165 @@
+import { describe, test, expect } from "vitest";
+import { MASKED, normalizeDeepObservation } from "@intentius/chant/deep-observation";
+import { fakeCluster, objectKey } from "@intentius/chant-lexicon-k8s/api/fake-cluster";
+import { k8sDeepNormalizationHooks } from "@intentius/chant-lexicon-k8s/deep-observe-hooks";
+import { observeResourcesDeepHelm } from "./deep-observe";
+import { helmDeepNormalizationHooks } from "./deep-observe-hooks";
+import type { HelmRunner } from "./release-observe";
+
+const LIST = JSON.stringify([
+  { name: "web-app", namespace: "prod", revision: "2", status: "deployed", chart: "web-app-0.1.0" },
+]);
+
+const MANIFEST = `---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-app
+spec:
+  replicas: 2
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: web-app-creds
+stringData:
+  password: declared-secret
+`;
+
+const scripted = (outputs: { list?: string; manifest?: string; hooks?: string }): HelmRunner =>
+  async (command) => {
+    if (command.startsWith("helm list")) return { stdout: outputs.list ?? "[]" };
+    if (command.startsWith("helm get manifest")) return { stdout: outputs.manifest ?? "" };
+    if (command.startsWith("helm get hooks")) return { stdout: outputs.hooks ?? "" };
+    throw new Error(`unexpected command: ${command}`);
+  };
+
+const entities = new Map([["chart", { entityType: "Helm::Chart", props: { name: "web-app" } }]]);
+const baseOptions = {
+  environment: "prod",
+  buildOutput: "",
+  entityNames: ["chart"],
+  entities,
+};
+
+const liveDeployment = {
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: {
+    name: "web-app",
+    namespace: "prod",
+    uid: "uid-dep",
+    resourceVersion: "9",
+    managedFields: [
+      {
+        manager: "hpa-controller",
+        operation: "Update",
+        fieldsType: "FieldsV1",
+        fieldsV1: { "f:spec": { "f:replicas": {} } },
+      },
+    ],
+  },
+  spec: { replicas: 3 },
+  status: { readyReplicas: 3, replicas: 3 },
+};
+
+const liveSecret = {
+  apiVersion: "v1",
+  kind: "Secret",
+  metadata: { name: "web-app-creds", namespace: "prod", uid: "uid-sec" },
+  data: { password: "aHVudGVyMg==" },
+};
+
+describe("helm observeResourcesDeep (#1247)", () => {
+  test("the hooks ARE the k8s lexicon's — delegation, not a copy", () => {
+    expect(helmDeepNormalizationHooks).toBe(k8sDeepNormalizationHooks);
+  });
+
+  test("deep rows come from the live cluster through the k8s machinery, keyed like the thin rows", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web-app", "prod")]: liveDeployment,
+        [objectKey("v1", "Secret", "web-app-creds", "prod")]: liveSecret,
+      },
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepHelm(baseOptions, {
+        run: scripted({ list: LIST, manifest: MANIFEST }),
+        connect: cluster.connector,
+      }),
+    );
+
+    const dep = result.resources["Deployment/prod/web-app"];
+    expect(dep).toBeDefined();
+    expect(dep.type).toBe("K8s::Apps::Deployment");
+    // The live value, not the declared one — this is what property drift diffs.
+    expect((dep.properties.spec as { replicas?: number }).replicas).toBe(3);
+    expect(result.unobserved).toEqual({});
+  });
+
+  test("normalization and masking come along for free via the k8s hooks: status pruned, Secret values masked", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web-app", "prod")]: liveDeployment,
+        [objectKey("v1", "Secret", "web-app-creds", "prod")]: liveSecret,
+      },
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepHelm(baseOptions, {
+        run: scripted({ list: LIST, manifest: MANIFEST }),
+        connect: cluster.connector,
+      }),
+    );
+
+    const dep = result.resources["Deployment/prod/web-app"];
+    // Server-populated envelope fields are pruned by the shared rules.
+    expect(dep.properties.status).toBeUndefined();
+    expect((dep.properties.metadata as Record<string, unknown>).uid).toBeUndefined();
+
+    // Secret material never reaches a consumer — masked, not returned.
+    const secret = result.resources["Secret/prod/web-app-creds"];
+    expect((secret.properties.data as Record<string, unknown>).password).toBe(MASKED);
+    expect(JSON.stringify(secret.properties)).not.toContain("aHVudGVyMg==");
+  });
+
+  test("managed-fields ownership rides through: the drift line can name the manager (#1189)", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("apps/v1", "Deployment", "web-app", "prod")]: liveDeployment },
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepHelm(baseOptions, {
+        run: scripted({ list: LIST, manifest: MANIFEST }),
+        connect: cluster.connector,
+      }),
+    );
+    const dep = result.resources["Deployment/prod/web-app"];
+    expect(dep.fieldOwners?.["spec.replicas"]).toBe("hpa-controller");
+  });
+
+  test("a rendered resource absent live is an absence, not a hole — the thin read owns existence", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("apps/v1", "Deployment", "web-app", "prod")]: liveDeployment },
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepHelm(baseOptions, {
+        run: scripted({ list: LIST, manifest: MANIFEST }),
+        connect: cluster.connector,
+      }),
+    );
+    expect(result.resources["Secret/prod/web-app-creds"]).toBeUndefined();
+    expect(result.unobserved["Secret/prod/web-app-creds"]).toBeUndefined();
+  });
+
+  test("a helm-side failure is a hole with a total reason, never a thin-but-clean tree (#1089)", async () => {
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepHelm(baseOptions, {
+        run: async () => {
+          throw Object.assign(new Error("helm: command not found"), { code: 127 });
+        },
+        connect: fakeCluster().connector,
+      }),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.chart.reason).toBe("no-credentials");
+  });
+});

package/src/deep-observe.ts

@@ -0,0 +1,121 @@
+/**
+ * Helm deep observation (#1247, epic #1228 phase 5) — property-level live
+ * trees for the resources a release manages, read through the k8s lexicon's
+ * machinery rather than a second implementation.
+ *
+ * The objects a release deploys are Kubernetes objects, so the deep read
+ * composes rather than reimplements:
+ *
+ *   1. The helm half (shared with `describeResources`, `./release-observe.ts`)
+ *      resolves each declared `Helm::Chart` to its release and parses what
+ *      the release holds — `helm get manifest` plus `helm get hooks`, both
+ *      channels. Each rendered document becomes a synthetic declared entity:
+ *      the release's stored manifest IS the declared side of a helm deep
+ *      diff — what the cluster is supposed to hold is what the release
+ *      applied.
+ *   2. The k8s half (`observeResourcesDeepK8s`) reads the live property tree
+ *      for each of those entities over the typed API client, resolves
+ *      per-field ownership from `metadata.managedFields` (#1189), and
+ *      normalizes with `k8sDeepNormalizationHooks` — so Secret-value masking
+ *      and the managed-fields rules apply to helm rows exactly as they do to
+ *      k8s rows, from the same hook object (see `./deep-observe-hooks.ts`).
+ *
+ * Verdicts compose per the deep contract (#1014/#1089): a helm-side failure
+ * (missing binary, unreachable cluster, unreadable release) lands the chart
+ * entity in `unobserved` with a total reason; a k8s-side failure lands the
+ * specific resource row there. Chart-authoring entities (`Helm::Chart`,
+ * `Helm::Values`, …) have no property tree of their own — their deep form is
+ * the per-resource rows this read returns — so on a successful read they are
+ * deliberately in neither map, which core's deep diff treats as
+ * nothing-to-compare rather than drift.
+ */
+import type { DeepObservationResult, UnobservedEntity } from "@intentius/chant/lexicon";
+import { deepObservation } from "@intentius/chant/deep-observation";
+import { unobservedAll } from "@intentius/chant/observation";
+import { observeResourcesDeepK8s } from "@intentius/chant-lexicon-k8s/deep-observe";
+import type { K8sConnector } from "@intentius/chant-lexicon-k8s/api/connect";
+import {
+  defaultHelmRunner,
+  observeReleases,
+  type HelmRunner,
+} from "./release-observe";
+
+export interface HelmDeepObserveOptions {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  region?: string;
+  owned?: boolean;
+}
+
+/** Injectable seams, so tests run without a helm binary or a kubeconfig. */
+export interface HelmDeepObserveDeps {
+  run?: HelmRunner;
+  /** Forwarded to the k8s reader — a test passes a fake cluster's connector. */
+  connect?: K8sConnector;
+}
+
+/** The document minus the envelope the row's `type` already carries. */
+function declaredTreeOf(doc: Record<string, unknown>, namespace: string | undefined): Record<string, unknown> {
+  const { apiVersion: _apiVersion, kind: _kind, ...rest } = doc;
+  const metadata = (rest.metadata ?? {}) as Record<string, unknown>;
+  return {
+    ...rest,
+    // The k8s reader addresses the object by `props.metadata.{name,namespace}`;
+    // helm applies the release namespace to namespace-silent documents, so the
+    // synthetic entity must carry the resolved one.
+    metadata: { ...metadata, ...(namespace && metadata.namespace === undefined ? { namespace } : {}) },
+  };
+}
+
+export async function observeResourcesDeepHelm(
+  options: HelmDeepObserveOptions,
+  deps: HelmDeepObserveDeps = {},
+): Promise<DeepObservationResult> {
+  const run = deps.run ?? defaultHelmRunner;
+
+  let observed;
+  try {
+    observed = await observeReleases(
+      { environment: options.environment, entities: options.entities, stack: options.stack },
+      run,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return deepObservation({}, unobservedAll(options.entityNames, "read-failed", message, options.entities));
+  }
+
+  const unobserved: Record<string, UnobservedEntity> = { ...observed.unobserved };
+
+  // One synthetic declared entity per rendered document, keyed like the thin
+  // read's rows so the two reads spell the same identity for the same object.
+  const synthetic = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  for (const release of observed.releases) {
+    for (const row of release.resources) {
+      synthetic.set(row.key, {
+        entityType: row.entityType,
+        props: declaredTreeOf(row.doc, row.namespace),
+      });
+    }
+  }
+
+  if (synthetic.size === 0) return deepObservation({}, unobserved);
+
+  const k8sOptions = {
+    environment: options.environment,
+    buildOutput: options.buildOutput,
+    entityNames: [...synthetic.keys()],
+    entities: synthetic,
+    ...(options.owned !== undefined ? { owned: options.owned } : {}),
+  };
+  const k8sResult = deps.connect
+    ? await observeResourcesDeepK8s(k8sOptions, deps.connect)
+    : await observeResourcesDeepK8s(k8sOptions);
+
+  return deepObservation(k8sResult.resources ?? {}, {
+    ...(k8sResult.unobserved ?? {}),
+    ...unobserved,
+  });
+}