@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/src/pinnability/values.ts

@@ -0,0 +1,205 @@
+/**
+ * Chart model and value coalescing for the pinnability classifier (#1234,
+ * epic #1228).
+ *
+ * Pinnability is a property of `(chart, values)`, not of the chart alone —
+ * so the classifier needs each subchart instance's EFFECTIVE values to ask
+ * whether a gate is open. This module walks `Chart.yaml` dependencies
+ * (aliases and `condition:` included — finding 12: dependency conditions are
+ * values-driven and therefore closed inputs) and approximates helm's
+ * coalescing: child defaults, overridden by the parent's `<alias-or-name>`
+ * subtree, with `global` propagated down.
+ *
+ * The approximation is deliberate and bounded. `import-values`, `tags`, and
+ * `tpl`-computed values are not modeled; a gate they would decide resolves
+ * as UNKNOWN and the classifier refuses rather than pins (see
+ * conditions.ts). The build-time values probe (#1251) replaces this with
+ * helm's own coalescing.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+export interface ChartDependency {
+  name: string;
+  alias?: string;
+  /** Comma-separated values paths, evaluated against the ROOT values. */
+  condition?: string;
+}
+
+export interface ChartMeta {
+  name: string;
+  dependencies: ChartDependency[];
+}
+
+export function readChartMeta(chartDir: string): ChartMeta {
+  const raw = readYamlFile(join(chartDir, "Chart.yaml")) as
+    | { name?: unknown; dependencies?: unknown }
+    | undefined;
+  const deps: ChartDependency[] = [];
+  if (Array.isArray(raw?.dependencies)) {
+    for (const d of raw.dependencies) {
+      if (d === null || typeof d !== "object") continue;
+      const dep = d as Record<string, unknown>;
+      if (typeof dep.name !== "string") continue;
+      deps.push({
+        name: dep.name,
+        alias: typeof dep.alias === "string" ? dep.alias : undefined,
+        condition: typeof dep.condition === "string" ? dep.condition : undefined,
+      });
+    }
+  }
+  return {
+    name: typeof raw?.name === "string" ? raw.name : "",
+    dependencies: deps,
+  };
+}
+
+export function readYamlFile(path: string): unknown {
+  if (!existsSync(path)) return undefined;
+  return yaml.load(readFileSync(path, "utf8"));
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Helm-style deep merge: `override` wins, maps merge recursively, a `null`
+ * override deletes the key, arrays replace wholesale.
+ */
+export function mergeValues(base: unknown, override: unknown): unknown {
+  if (override === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(override)) {
+    if (v === null) {
+      delete out[k];
+      continue;
+    }
+    out[k] = k in out ? mergeValues(out[k], v) : v;
+  }
+  return out;
+}
+
+/** Resolve a dot path against a values tree; undefined when absent. */
+export function valueAtPath(values: unknown, path: string[]): unknown {
+  let v = values;
+  for (const seg of path) {
+    if (!isPlainObject(v)) return undefined;
+    v = v[seg];
+  }
+  return v;
+}
+
+/**
+ * One chart in the tree, with the values IT sees. An aliased dependency
+ * yields two instances over the same directory — each with its own value
+ * scope, which is why findings are evaluated per instance but reported per
+ * file.
+ */
+export interface ChartInstance {
+  /** Directory of the (sub)chart. */
+  dir: string;
+  /** Directory relative to the root chart ("" for the root). */
+  relDir: string;
+  /** Values scope from the root, e.g. ["grafana"] or ["kidtwo"]; [] for root. */
+  scope: readonly string[];
+  /** Effective values as this instance sees them. */
+  values: unknown;
+  /**
+   * When a `condition:` on the dependency chain disables this instance under
+   * the supplied values: the first condition path that resolved false, in
+   * root coordinates. Constructs inside a disabled instance are gated by it.
+   */
+  disabledBy?: string;
+}
+
+/**
+ * Build the instance tree for a chart directory and the values the render
+ * was given. `suppliedValues` merges over the root chart's `values.yaml`
+ * exactly like `helm template --values`.
+ */
+export function buildChartInstances(
+  chartDir: string,
+  suppliedValues?: unknown,
+): { instances: ChartInstance[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const rootDefaults = readYamlFile(join(chartDir, "values.yaml")) ?? {};
+  const rootValues = mergeValues(rootDefaults, suppliedValues);
+  const instances: ChartInstance[] = [];
+
+  const visit = (
+    dir: string,
+    relDir: string,
+    scope: readonly string[],
+    values: unknown,
+    disabledBy: string | undefined,
+  ): void => {
+    instances.push({ dir, relDir, scope, values, disabledBy });
+    const meta = readChartMeta(dir);
+    const chartsDir = join(dir, "charts");
+    const childDirs = existsSync(chartsDir)
+      ? readdirSync(chartsDir).filter((e) => {
+          const p = join(chartsDir, e);
+          return statSync(p).isDirectory() && existsSync(join(p, "Chart.yaml"));
+        })
+      : [];
+    const declared = new Set<string>();
+
+    const visitChild = (dep: ChartDependency): void => {
+      const key = dep.alias ?? dep.name;
+      const childDir = join(chartsDir, dep.name);
+      if (!existsSync(join(childDir, "Chart.yaml"))) {
+        warnings.push(
+          `dependency ${dep.name} of ${relDir === "" ? "the chart" : relDir} is not vendored under charts/ — not scanned`,
+        );
+        return;
+      }
+      declared.add(dep.name);
+      // Condition paths are resolved against the TOP parent's values
+      // (helm's documented semantics); first present path wins, absent
+      // conditions leave the dependency enabled.
+      let childDisabledBy = disabledBy;
+      if (childDisabledBy === undefined && dep.condition !== undefined) {
+        for (const rawPath of dep.condition.split(",")) {
+          const path = rawPath.trim();
+          if (path === "") continue;
+          const v = valueAtPath(rootValues, path.split("."));
+          if (v === undefined) continue;
+          if (v === false) childDisabledBy = path;
+          break;
+        }
+      }
+      const childDefaults = readYamlFile(join(childDir, "values.yaml")) ?? {};
+      const parentSlice = isPlainObject(values) ? values[key] : undefined;
+      let childValues = mergeValues(childDefaults, parentSlice);
+      // Globals propagate into every subchart tree.
+      const parentGlobal = isPlainObject(values) ? values.global : undefined;
+      if (parentGlobal !== undefined && isPlainObject(childValues)) {
+        childValues = {
+          ...childValues,
+          global: mergeValues(childValues.global, parentGlobal),
+        };
+      }
+      visit(
+        childDir,
+        relDir === "" ? `charts/${dep.name}` : `${relDir}/charts/${dep.name}`,
+        [...scope, key],
+        childValues,
+        childDisabledBy,
+      );
+    };
+
+    for (const dep of meta.dependencies) visitChild(dep);
+    // charts/ directories not declared in Chart.yaml are implicit,
+    // always-enabled dependencies.
+    for (const name of childDirs) {
+      if (!declared.has(name)) visitChild({ name });
+    }
+  };
+
+  visit(chartDir, "", [], rootValues, undefined);
+  return { instances, warnings };
+}

package/src/plugin.test.ts

@@ -38,12 +38,14 @@ describe("helmPlugin", () => {
 
   test("provides post-synth checks", () => {
     const checks = helmPlugin.postSynthChecks!();
-    expect(checks.length).toBe(21);
+    expect(checks.length).toBe(23);
     const ids = checks.map((c) => c.id);
     expect(ids).toContain("WHM005");
     expect(ids).toContain("WHM101");
     expect(ids).toContain("WHM105");
     expect(ids).toContain("WHM301");
+    expect(ids).toContain("WHM503");
+    expect(ids).toContain("WHM504");
   });
 
   test("detectTemplate identifies Chart.yaml data", () => {

package/src/plugin.ts

@@ -6,6 +6,8 @@
  */
 
 import type { LexiconPlugin, IntrinsicDef, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { CommandGroup } from "@intentius/chant/cli/command-group";
+import { helmCommandGroup } from "./commands";
 import { detectTemplate } from "./detect";
 import { discoverLintRules } from "@intentius/chant/lint/discover";
 import { postSynthChecks as postSynthCheckList } from "./lint/post-synth";
@@ -16,12 +18,35 @@ import { fileURLToPath } from "url";
 import { helmSerializer } from "./serializer";
 import { helmCompletions } from "./lsp/completions";
 import { helmHover } from "./lsp/hover";
+import { helmConfigSchema } from "./config";
+import { helmDeepNormalizationHooks } from "./deep-observe-hooks";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 
 export const helmPlugin: LexiconPlugin = {
   name: "helm",
+  // The `helm` namespace in chant.config.ts — capability profiles (#1235).
+  // Declaring the schema makes core validate the namespace at load, so a
+  // typo'd profile field fails the build instead of silently unpinning.
+  configSchema: helmConfigSchema,
+  // #1246 — helm resolves real ownership verdicts on the thin read (every row
+  // is release-scoped, so helm-managed = owned via release identity), and the
+  // deep read (#1247) delegates to the k8s reader, which resolves the shared
+  // label channel (`app.kubernetes.io/managed-by` + `chant.intentius.io/*`)
+  // on the live objects.
+  ownershipChannel: { keys: LABEL_OWNERSHIP_KEYS, reads: ["describeResources", "observeResourcesDeep"] },
   auditCatalog: () => helmAuditCatalog,
   serializer: helmSerializer,
 
+  // #1248 (epic #1228 Phase 6, via the #1078 seam) — `chant helm` mounts the
+  // pinned-render surface: the pinnability gate (#1234), the double-render
+  // localizer (#1236), and the recorded-render listing with digests (#1237).
+  // See ./commands.ts for the verb list; this plugin only mounts it. The
+  // diff verbs (#1249 render-to-render, #1250 render-to-live, both mounted on
+  // "diff") land there.
+  commands(): CommandGroup {
+    return helmCommandGroup();
+  },
+
   lintRules() {
     const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
     return discoverLintRules(rulesDir, import.meta.url);
@@ -37,25 +62,63 @@ export const helmPlugin: LexiconPlugin = {
   completionProvider: helmCompletions,
   hoverProvider: helmHover,
 
+  // chant #1174 — `foldsAsCall: true` opts an intrinsic's PLAIN-CALL form
+  // into `chant build --fold` (chant #1044's mechanism, previously unused by
+  // this lexicon: every helm intrinsic is a plain call — helm has no tagged
+  // templates at all — so before this PR NONE of them folded, and a single
+  // `include(...)`/`printf(...)` anywhere in a chart's resources forced the
+  // whole file back to the run path).
+  //
+  // Audited one at a time against `IntrinsicDef.foldsAsCall`'s criterion
+  // (../../../packages/core/src/lexicon.ts): "calling the intrinsic is a
+  // pure function of its arguments that builds a deterministic data
+  // envelope". Every function below (`include`/`required`/`helmDefault`/
+  // `toYaml`/`quote`/`printf`/`tpl`/`lookup`/`filesGet`/`filesGlob`/
+  // `filesAsConfig`/`filesAsSecrets`, ./intrinsics.ts) does exactly that: it
+  // builds a `HelmTpl` (or, for `lookup`, a string) by interpolating its
+  // arguments into a Go template expression string — no I/O, no mutation, no
+  // dependency on anything but the arguments. `lookup`'s own side effect
+  // (a live cluster read) happens when HELM renders the resulting template
+  // at deploy time, not when this JS function runs at `chant build` time, so
+  // it is just as pure here as the rest.
+  //
+  // Left OUT, each for a specific reason rather than an oversight:
+  //   - `values`/`Release`/`ChartRef`/`Capabilities`/`Template` are proxy
+  //     OBJECTS, never called (`values(...)` isn't valid source) — nothing
+  //     to opt in.
+  //   - `withOrder`/`argoWave` return a PLAIN record meant to be spread
+  //     (`{...withOrder(1)}`), not a `HelmTpl`. `fold()`'s object-spread
+  //     handling (`Object.assign(obj, src)`, ../fold/fold.ts) runs
+  //     SYNCHRONOUSLY on the immediately-folded value, before the async
+  //     revival that would turn a folded call into its real result — opting
+  //     these in would spread the folded `{__intrinsic, args}` envelope's
+  //     own keys into the object instead of the real record. A real
+  //     soundness hazard, not a "not yet audited."
+  //   - `If`/`ElseIf`/`Range`/`With` take an arbitrary `body`/`elseBody`
+  //     that is often an arrow function (`Range(list, (item) => ({...}))`)
+  //     or a nested Declarable — `fold()` already rejects a function used as
+  //     a value on its own terms, so opting these in buys nothing measured
+  //     on this corpus and is left for a future PR to size against real
+  //     usage rather than widened on speculation.
   intrinsics(): IntrinsicDef[] {
     return [
       { name: "values", description: "Proxy accessor for {{ .Values.x }} references", isTag: false },
       { name: "Release", description: "Built-in Release object (Name, Namespace, etc.)", isTag: false },
       { name: "ChartRef", description: "Built-in Chart object (Name, Version, AppVersion)", isTag: false },
-      { name: "include", description: 'Include a named template: {{ include "name" . }}', isTag: false },
-      { name: "required", description: 'Require a value: {{ required "msg" .Values.x }}', isTag: false },
-      { name: "helmDefault", description: 'Default value: {{ default "def" .Values.x }}', isTag: false },
-      { name: "toYaml", description: "Convert to YAML: {{ toYaml .Values.x | nindent N }}", isTag: false },
-      { name: "quote", description: "Quote a value: {{ .Values.x | quote }}", isTag: false },
-      { name: "printf", description: 'Format string: {{ printf "%s" .Values.x }}', isTag: false },
-      { name: "tpl", description: "Evaluate template: {{ tpl .Values.x . }}", isTag: false },
-      { name: "lookup", description: 'Lookup resource: {{ lookup "v1" "Secret" "ns" "name" }}', isTag: false },
+      { name: "include", description: 'Include a named template: {{ include "name" . }}', isTag: false, foldsAsCall: true },
+      { name: "required", description: 'Require a value: {{ required "msg" .Values.x }}', isTag: false, foldsAsCall: true },
+      { name: "helmDefault", description: 'Default value: {{ default "def" .Values.x }}', isTag: false, foldsAsCall: true },
+      { name: "toYaml", description: "Convert to YAML: {{ toYaml .Values.x | nindent N }}", isTag: false, foldsAsCall: true },
+      { name: "quote", description: "Quote a value: {{ .Values.x | quote }}", isTag: false, foldsAsCall: true },
+      { name: "printf", description: 'Format string: {{ printf "%s" .Values.x }}', isTag: false, foldsAsCall: true },
+      { name: "tpl", description: "Evaluate template: {{ tpl .Values.x . }}", isTag: false, foldsAsCall: true },
+      { name: "lookup", description: 'Lookup resource: {{ lookup "v1" "Secret" "ns" "name" }}', isTag: false, foldsAsCall: true },
       { name: "Capabilities", description: "Built-in Capabilities object (KubeVersion, APIVersions, HelmVersion)", isTag: false },
       { name: "Template", description: "Built-in Template object (Name, BasePath)", isTag: false },
-      { name: "filesGet", description: '.Files.Get: {{ .Files.Get "path" }}', isTag: false },
-      { name: "filesGlob", description: '.Files.Glob: {{ .Files.Glob "pattern" }}', isTag: false },
-      { name: "filesAsConfig", description: ".Files.Glob.AsConfig for ConfigMap data", isTag: false },
-      { name: "filesAsSecrets", description: ".Files.Glob.AsSecrets for Secret data", isTag: false },
+      { name: "filesGet", description: '.Files.Get: {{ .Files.Get "path" }}', isTag: false, foldsAsCall: true },
+      { name: "filesGlob", description: '.Files.Glob: {{ .Files.Glob "pattern" }}', isTag: false, foldsAsCall: true },
+      { name: "filesAsConfig", description: ".Files.Glob.AsConfig for ConfigMap data", isTag: false, foldsAsCall: true },
+      { name: "filesAsSecrets", description: ".Files.Glob.AsSecrets for Secret data", isTag: false, foldsAsCall: true },
       { name: "ElseIf", description: "Else-if chaining: {{- else if .Values.x }}...{{- end }}", isTag: false },
       { name: "If", description: "Conditional: {{- if .Values.x }}...{{- end }}", isTag: false },
       { name: "Range", description: "Range loop: {{- range .Values.x }}...{{- end }}", isTag: false },
@@ -383,6 +446,28 @@ export const service = new Service({
     return listArtifacts(options);
   },
 
+  // #1246 — per-resource observation of what each declared chart's release
+  // holds (`helm get manifest` + `helm get hooks`, both channels), with total
+  // tri-state verdicts. This is what gives `lifecycle diff --live` helm rows.
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  // #1247 — deep property-level trees for the release's resources, read live
+  // through the k8s lexicon's typed client and normalized by its hooks.
+  // Dynamic import for the same reason k8s's is: the reader reaches
+  // `@intentius/chant-k8s-client`, which must stay off the build path.
+  async observeResourcesDeep(options) {
+    const { observeResourcesDeepHelm } = await import("./deep-observe");
+    return observeResourcesDeepHelm(options);
+  },
+
+  // The k8s lexicon's hooks by reference, not a copy (#1247) — the objects a
+  // release deploys are Kubernetes objects, and core normalizes the declared
+  // tree with the same rules the reader used.
+  deepNormalizationHooks: helmDeepNormalizationHooks,
+
   // #1495 piece 4 — the deploy-unit observer for helm-upgrade units: a
   // release's presence and native status, read back by the same name the
   // capability deploys under. Dynamic import mirrors listArtifacts.