@intentius/chant-lexicon-helm 0.45.0 → 0.49.0

package/src/lint/post-synth/whm504.ts

@@ -0,0 +1,52 @@
+/**
+ * WHM504: Dead value assignment (#1252, epic #1228 Phase 7).
+ *
+ * A supplied value that never survives coalescing is a lie in the config:
+ * it reads as if it configures something, and nothing ever sees it. The
+ * coalesced-values probe (#1251, ../../values-probe.ts) knows three ways a
+ * supplied value dies — shadowed by a later supplied layer, targeting a
+ * dependency a `condition:` disabled, or a values map under a top-level key
+ * that names no dependency at all (the silently-ignored subchart typo).
+ *
+ * The check reports over the probe records of the current process
+ * (`getValuesProbeRecords`): whatever ran the probe — the pinned-render
+ * build path, a test, a direct call — this check turns its dead assignments
+ * into diagnostics. No probe run, nothing to report; the probe itself needs
+ * the helm binary and the chart source, which a post-synth check must not
+ * require on its own.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getValuesProbeRecords, type DeadAssignment } from "../../values-probe";
+
+function describe(dead: DeadAssignment): string {
+  switch (dead.reason) {
+    case "shadowed":
+      return `supplied value "${dead.path}" (${dead.origin}) never survives coalescing — shadowed by ${dead.shadowedBy}`;
+    case "disabled-subchart":
+      return `supplied value "${dead.path}" (${dead.origin}) targets a disabled subchart — ${dead.shadowedBy}`;
+    case "unknown-subchart":
+      return `supplied values under "${dead.path}" (${dead.origin}) target no subchart — ${dead.shadowedBy}`;
+  }
+}
+
+export const whm504: PostSynthCheck = {
+  id: "WHM504",
+  description: "Detect supplied values that never survive coalescing (shadowed, disabled subchart, unknown subchart)",
+
+  check(_ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const record of getValuesProbeRecords()) {
+      for (const dead of record.probe.deadAssignments) {
+        diagnostics.push({
+          checkId: "WHM504",
+          severity: "warning",
+          message: describe(dead),
+          entity: record.name,
+          lexicon: "helm",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/op/activities/cluster-probe.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure comparison/parsing halves of the deploy-time capability probe
+ * (#1244). The exec-driven probe itself is exercised through `helmInstall`
+ * in helm.test.ts, against the scripted kubectl double.
+ */
+import { describe, test, expect } from "vitest";
+import { compareCapabilityProfile, majorMinorOf, type LiveClusterCapabilities } from "./cluster-probe";
+
+const live: LiveClusterCapabilities = {
+  kubeVersion: "v1.33.6+k3s1",
+  majorMinor: "1.33",
+  apiVersions: ["v1", "apps/v1", "batch/v1", "monitoring.coreos.com/v1"],
+};
+
+describe("majorMinorOf", () => {
+  test("accepts every shape KUBE_VERSION_PATTERN admits, plus live gitVersions", () => {
+    expect(majorMinorOf("1.33")).toBe("1.33");
+    expect(majorMinorOf("1.33.6")).toBe("1.33");
+    expect(majorMinorOf("v1.33.6")).toBe("1.33");
+    expect(majorMinorOf("v1.33.6+k3s1")).toBe("1.33");
+  });
+
+  test("rejects the unparseable", () => {
+    expect(majorMinorOf("latest")).toBeUndefined();
+    expect(majorMinorOf("")).toBeUndefined();
+  });
+});
+
+describe("compareCapabilityProfile", () => {
+  test("matching profile has no divergences — patch skew tolerated, extra live apiVersions ignored", () => {
+    expect(
+      compareCapabilityProfile(
+        { kubeVersion: "1.33.4", apiVersions: ["apps/v1", "monitoring.coreos.com/v1"] },
+        live,
+      ),
+    ).toEqual([]);
+  });
+
+  test("a kubeVersion divergence names both the declared and the live version", () => {
+    expect(compareCapabilityProfile({ kubeVersion: "1.31.4" }, live)).toEqual([
+      "kubeVersion: profile declares 1.31.4 (1.31), cluster runs v1.33.6+k3s1 (1.33)",
+    ]);
+  });
+
+  test("every missing apiVersion is named, one divergence each", () => {
+    expect(
+      compareCapabilityProfile(
+        { apiVersions: ["missing.io/v1", "apps/v1", "alsomissing.io/v1beta1"] },
+        live,
+      ),
+    ).toEqual([
+      "apiVersion missing.io/v1: declared by the profile, not served by the cluster",
+      "apiVersion alsomissing.io/v1beta1: declared by the profile, not served by the cluster",
+    ]);
+  });
+
+  test("kubeVersion and apiVersion divergences accumulate", () => {
+    expect(
+      compareCapabilityProfile({ kubeVersion: "1.31", apiVersions: ["missing.io/v1"] }, live),
+    ).toHaveLength(2);
+  });
+
+  test("a profile declaring nothing diverges from nothing", () => {
+    expect(compareCapabilityProfile({}, live)).toEqual([]);
+  });
+});

package/src/op/activities/cluster-probe.ts

@@ -0,0 +1,148 @@
+/**
+ * Live-cluster capability probe for the deploy-time profile assertion
+ * (#1244, epic #1228 phase 4).
+ *
+ * A render pinned for one capability profile and deployed to a cluster with
+ * another is silently skewed: the bytes were computed against a declared
+ * `kubeVersion` and `apiVersions` set, and nothing at deploy time checked
+ * the target actually matches. This module reads the target cluster's real
+ * capabilities — `kubectl version -o json` for the server version,
+ * `kubectl api-versions` for the served API set — through the same
+ * exec-and-ambient-kubeconfig convention `helmInstall` already uses for the
+ * helm binary, and names every divergence from a declared profile.
+ *
+ * The comparison tolerance is deliberate: kubeVersion matches on
+ * major.minor. A profile declaring `1.33.6` matches a live `v1.33.4+k3s1` —
+ * the capability surface helm renders against (`.Capabilities.KubeVersion`)
+ * is a major.minor fact, and patch skew within a minor changes no API
+ * surface a chart can probe. Declared apiVersions are exact-match: each one
+ * the profile names must be served by the cluster.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** What the probe read off the live cluster. */
+export interface LiveClusterCapabilities {
+  /** The server's full version string (`serverVersion.gitVersion`), e.g. `v1.33.6+k3s1`. */
+  kubeVersion: string;
+  /** The server's `major.minor`, e.g. `1.33`, parsed from `serverVersion.major`/`minor` (or `gitVersion` when those are absent). */
+  majorMinor: string;
+  /** Every API version the cluster serves, one `group/version` (or `v1`) per entry, from `kubectl api-versions`. */
+  apiVersions: string[];
+}
+
+/**
+ * Thrown when the cluster's capabilities cannot be read at all — kubectl
+ * missing, cluster unreachable, or unparseable output. A deploy that
+ * declared a profile cannot verify its guarantee through this error, so the
+ * caller must refuse to proceed rather than deploy blind.
+ */
+export class ClusterProbeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClusterProbeError";
+  }
+}
+
+/** `major.minor` from a declared or live version string (`1.33`, `1.33.6`, `v1.33.6+k3s1`). Undefined when the string has no parseable major.minor. */
+export function majorMinorOf(version: string): string | undefined {
+  const match = /^v?(\d+)\.(\d+)/.exec(version.trim());
+  return match ? `${match[1]}.${match[2]}` : undefined;
+}
+
+function parseServerVersion(raw: string): { kubeVersion: string; majorMinor: string } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new ClusterProbeError(`kubectl version -o json produced unparseable output: ${raw.slice(0, 200)}`);
+  }
+  const server = (parsed as { serverVersion?: Record<string, unknown> }).serverVersion;
+  if (!server) {
+    throw new ClusterProbeError(
+      "kubectl version -o json reported no serverVersion — the cluster did not answer",
+    );
+  }
+  const gitVersion = typeof server.gitVersion === "string" ? server.gitVersion : "";
+  // major/minor are the authoritative fields; minor can carry a vendor
+  // suffix (GKE reports "33+"), so digits are extracted rather than trusted.
+  const major = typeof server.major === "string" ? /\d+/.exec(server.major)?.[0] : undefined;
+  const minor = typeof server.minor === "string" ? /\d+/.exec(server.minor)?.[0] : undefined;
+  const majorMinor = major && minor ? `${major}.${minor}` : gitVersion ? majorMinorOf(gitVersion) : undefined;
+  if (!majorMinor) {
+    throw new ClusterProbeError(
+      `kubectl version -o json reported no usable server version (gitVersion: ${gitVersion || "<absent>"})`,
+    );
+  }
+  return { kubeVersion: gitVersion || majorMinor, majorMinor };
+}
+
+/**
+ * Read the target cluster's capabilities. Uses whatever kubeconfig/context
+ * the process environment provides — the same ambient target `helm upgrade`
+ * itself will act on, so the probe and the deploy see one cluster.
+ */
+export async function probeClusterCapabilities(signal?: AbortSignal): Promise<LiveClusterCapabilities> {
+  let versionRaw: string;
+  let apiVersionsRaw: string;
+  try {
+    const [versionResult, apiResult] = await Promise.all([
+      execAsync("kubectl version -o json", { signal }),
+      execAsync("kubectl api-versions", { signal }),
+    ]);
+    versionRaw = versionResult.stdout;
+    apiVersionsRaw = apiResult.stdout;
+  } catch (err) {
+    throw new ClusterProbeError(
+      `could not read the target cluster's capabilities: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const { kubeVersion, majorMinor } = parseServerVersion(versionRaw);
+  const apiVersions = apiVersionsRaw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return { kubeVersion, majorMinor, apiVersions };
+}
+
+/** The declared facts a profile asserts about a cluster — the activity-side profile shape. */
+export interface DeclaredCapabilityProfile {
+  name?: string;
+  kubeVersion?: string;
+  apiVersions?: string[];
+}
+
+/**
+ * Every way `live` diverges from what `profile` declares, one message per
+ * divergence, each naming the declared and the live value. Empty when the
+ * cluster matches the profile.
+ *
+ * kubeVersion compares on major.minor (see module doc). apiVersions is a
+ * subset check: everything the profile declares must be served; extra API
+ * versions on the cluster are not a divergence, since a render only ever
+ * probed the declared set.
+ */
+export function compareCapabilityProfile(
+  profile: DeclaredCapabilityProfile,
+  live: LiveClusterCapabilities,
+): string[] {
+  const divergences: string[] = [];
+  if (profile.kubeVersion) {
+    const declared = majorMinorOf(profile.kubeVersion);
+    if (declared !== live.majorMinor) {
+      divergences.push(
+        `kubeVersion: profile declares ${profile.kubeVersion} (${declared ?? "unparseable"}), ` +
+          `cluster runs ${live.kubeVersion} (${live.majorMinor})`,
+      );
+    }
+  }
+  const served = new Set(live.apiVersions);
+  for (const apiVersion of profile.apiVersions ?? []) {
+    if (!served.has(apiVersion)) {
+      divergences.push(`apiVersion ${apiVersion}: declared by the profile, not served by the cluster`);
+    }
+  }
+  return divergences;
+}