@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/src/op/builders.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Typed step-builder wrappers (chant #1288 Stage 2) — see
+ * `lexicons/k8s/src/op/builders.test.ts`'s module doc for what's asserted
+ * and why (backward compat against core's original, step-output-ref
+ * composition, compile-time-only `@ts-expect-error` checks walked by
+ * `npm run typecheck`).
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  helmInstall as helmInstallOld,
+  helmInstallPinned as helmInstallPinnedOld,
+  stepOutput,
+  type StepOutputRef,
+} from "@intentius/chant/op";
+import { helmInstall, helmInstallPinned } from "./builders";
+
+describe("helm typed step builders (#1288 Stage 2)", () => {
+  test("helmInstall: identical ActivityStep to core's original for a minimal call", () => {
+    expect(helmInstall("api", "./chart")).toEqual(helmInstallOld("api", "./chart"));
+  });
+
+  test("helmInstall: identical ActivityStep with opts (namespace, values, set, capabilityProfile)", () => {
+    const opts = {
+      namespace: "prod",
+      values: "values.yaml",
+      set: { "image.tag": "v2" },
+      capabilityProfile: { kubeVersion: "1.29" },
+      profile: "fastIdempotent" as const,
+    };
+    expect(helmInstall("api", "./chart", opts)).toEqual(helmInstallOld("api", "./chart", opts));
+  });
+
+  test("helmInstallPinned: identical ActivityStep to core's original", () => {
+    const opts = { namespace: "prod" };
+    expect(helmInstallPinned("api", "sha256:abc", opts)).toEqual(helmInstallPinnedOld("api", "sha256:abc", opts));
+  });
+
+  test("helmInstall: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("render-step", "namespace");
+    const step = helmInstall("api", "./chart", { namespace: ref });
+    expect(step.args?.namespace).toBe(ref);
+  });
+
+  test("helmInstall: .out is reachable when an id is given", () => {
+    const step = helmInstall("api", "./chart", { id: "deploy" });
+    const ref: StepOutputRef = step.out.releaseName;
+    expect(ref.step).toBe("deploy");
+    expect(ref.path).toBe("releaseName");
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "nameSpace" is not a key of HelmInstallArgs (the exact
+  // typo class chant #1288 names: helmInstall("api", "./chart", { nameSpace:
+  // "prod" }) silently no-opped before this).
+  helmInstall("api", "./chart", { nameSpace: "prod" });
+
+  // @ts-expect-error — set's values must be strings, not numbers.
+  helmInstall("api", "./chart", { set: { replicas: 3 } });
+
+  // @ts-expect-error — overrideProfileAssertion must be boolean.
+  helmInstall("api", "./chart", { overrideProfileAssertion: "true" });
+
+  // @ts-expect-error — contentDigest must be a string (the `sha256:...`
+  // digest), not a number.
+  helmInstall("api", "./chart", { contentDigest: 5 });
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed step-builder wrappers for this lexicon's `helmInstall` activity
+ * (chant #1288 Stage 2 — "regenerate the step builders as fully typed
+ * wrappers"). Core cannot import a lexicon's `*Args` types (lexicons depend
+ * on core, not the other way around), so a fully typed `helmInstall` /
+ * `helmInstallPinned` has to live beside {@link HelmInstallArgs} — here,
+ * next to `./activities/helm.ts`. `opts`'s type in each wrapper below IS
+ * `HelmInstallArgs` itself (via `Omit`/`WithStepRefs`) — never a
+ * hand-restated mirror — so the option surface Stage 1's zod contracts
+ * deliberately skipped (`capabilityProfile`, `set`, `deleteMode`-adjacent
+ * cross-field options) is authoring-time typed for free.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950).
+ *
+ * `core`'s own `helmInstall`/`helmInstallPinned` (in `@intentius/chant/op`,
+ * re-exported from `@intentius/chant-lexicon-temporal`) are UNCHANGED and
+ * produce byte-identical `ActivityStep` output for the same inputs — these
+ * are purely additive. Deliberately not swapped into the temporal barrel
+ * (see `lexicons/k8s/src/op/builders.ts`'s module doc for why: it would make
+ * temporal depend on this package at runtime, undoing the product-agnostic
+ * split #809 did). An author who wants the typed surface imports it from
+ * here — `@intentius/chant-lexicon-helm` — which a project using
+ * `helmInstall` already depends on.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { HelmInstallArgs } from "./activities/helm";
+
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Deploy a helm release — the fully typed twin of core's `helmInstall`.
+ * `opts` is {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `chart`. Defaults to the `longInfra` profile.
+ */
+export const helmInstall = (
+  name: string,
+  chart: string,
+  opts?: WithStepRefs<Omit<HelmInstallArgs, "name" | "chart">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("helmInstall", { name, chart, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (#1242) —
+ * the fully typed twin of core's `helmInstallPinned`. `opts` is
+ * {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `contentDigest`. Defaults to the `longInfra` profile.
+ */
+export const helmInstallPinned = (
+  name: string,
+  contentDigest: string,
+  opts?: WithStepRefs<Omit<HelmInstallArgs, "name" | "contentDigest">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("helmInstall", { name, contentDigest, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};

package/src/pinnability/actions.ts

@@ -0,0 +1,263 @@
+/**
+ * Go template action extraction and control-flow scoping (#1234, epic #1228).
+ *
+ * The pinnability gate inspects template ACTIONS (`{{ ... }}`), never raw
+ * text. That distinction is finding 9: cert-manager carries 52 textual
+ * "lookup" occurrences, all comment prose, and a real template-action count
+ * of 0 — a text-matching gate refuses a chart that is perfectly pinnable.
+ *
+ * Beyond extraction, this module reconstructs the control-flow structure of a
+ * template file — which `if` / `with` / `range` blocks enclose each action —
+ * so the classifier can ask whether a construct is REACHABLE under the
+ * supplied values, not merely present. Reachability is what separates
+ * "unpinnable" from "pinnable with a recorded conditional hazard": bundled
+ * grafana's control-flow `lookup` sits behind `persistence.enabled`, off by
+ * default, so a default-values render never consults the cluster.
+ */
+
+export type ActionKind =
+  | "if"
+  | "elseif"
+  | "else"
+  | "with"
+  | "range"
+  | "define"
+  | "block"
+  | "end"
+  | "other";
+
+export interface TemplateAction {
+  /** Path of the file the action was found in (as given by the caller). */
+  file: string;
+  /** 1-based line the action starts on. */
+  line: number;
+  /** The action body between `{{` and `}}`, trim markers stripped. */
+  body: string;
+  /** Structural role of the action, from its leading keyword. */
+  kind: ActionKind;
+}
+
+/**
+ * One enclosing control-flow frame for an action. `conditions` are the
+ * expressions that must hold for the frame's branch to run; `negatedConditions`
+ * are prior branch conditions that must NOT hold (an `else` / `else if`
+ * branch runs only when every earlier branch condition was false).
+ */
+export interface ScopeFrame {
+  kind: "if" | "with" | "range" | "define" | "block" | "dependency-condition";
+  conditions: string[];
+  negatedConditions: string[];
+  /**
+   * When a `with` block pins the dot to a `.Values` subtree, the path of that
+   * subtree — so bare `.enabled` inside `with .Values.persistence` resolves
+   * to `persistence.enabled`. `undefined` means the dot is unresolvable
+   * (a `range` element, a non-values `with`, a `define` invoked from an
+   * unknown context).
+   */
+  dotValuesPath?: string[];
+  /** Dot is rebound to something we cannot resolve (range element etc.). */
+  dotUnresolvable?: boolean;
+}
+
+export interface ScopedAction {
+  action: TemplateAction;
+  /** Enclosing frames, outermost first. Empty for top-level actions. */
+  frames: ScopeFrame[];
+}
+
+const KIND_RE =
+  /^(if\b|else\s+if\b|else\b|with\b|range\b|define\b|block\b|end\b)/;
+
+function kindOf(body: string): ActionKind {
+  const m = body.match(KIND_RE);
+  if (!m) return "other";
+  const kw = m[1].replace(/\s+/g, " ").trim();
+  if (kw === "else if") return "elseif";
+  return kw.replace(/\b\s.*$/, "") as ActionKind;
+}
+
+/**
+ * Extract template actions from a source file, skipping comment actions
+ * (`{{/* ... *\/}}`). Text outside actions — including YAML `#` comments,
+ * where finding 9's 52 false positives lived — is never inspected by any
+ * scan built on this.
+ */
+export function extractActions(source: string, file: string): TemplateAction[] {
+  const actions: TemplateAction[] = [];
+  let i = 0;
+  let line = 1;
+  let lineScanPos = 0;
+  const lineAt = (pos: number): number => {
+    // Incremental line counting: `pos` is monotonically increasing.
+    for (; lineScanPos < pos; lineScanPos++) {
+      if (source[lineScanPos] === "\n") line += 1;
+    }
+    return line;
+  };
+  while (i < source.length) {
+    const open = source.indexOf("{{", i);
+    if (open === -1) break;
+    const actionLine = lineAt(open);
+    // Body starts after `{{` and an optional trim marker.
+    let bodyStart = open + 2;
+    if (source[bodyStart] === "-") bodyStart += 1;
+    const rest = source.slice(bodyStart);
+    // Comment action: {{/* ... */}} — skip to its closing */}}.
+    if (/^\s*\/\*/.test(rest)) {
+      const closeComment = source.indexOf("*/", bodyStart);
+      if (closeComment === -1) break;
+      const close = source.indexOf("}}", closeComment);
+      i = close === -1 ? source.length : close + 2;
+      continue;
+    }
+    const close = source.indexOf("}}", bodyStart);
+    if (close === -1) break;
+    let body = source.slice(bodyStart, close);
+    if (body.endsWith("-")) body = body.slice(0, -1);
+    body = body.trim();
+    actions.push({ file, line: actionLine, body, kind: kindOf(body) });
+    i = close + 2;
+  }
+  return actions;
+}
+
+/**
+ * The pipeline of an action, structural keyword and variable assignment
+ * stripped: `if X` → `X`, `range $i, $v := X` → `X`, `$pw := X` → `X`.
+ * This is what condition evaluation and call-reachability parse.
+ */
+export function actionPipeline(action: TemplateAction): string {
+  let expr = action.body.replace(KIND_RE, "").trim();
+  // `range $i, $v := .Values.x` / `$pw := .Values.x` — the pipeline is what
+  // follows the assignment.
+  const assign = expr.match(/^\$[\w]*\s*(?:,\s*\$[\w]*\s*)?:?=\s*(.*)$/);
+  if (assign) expr = assign[1].trim();
+  return expr;
+}
+
+
+/** `.Values.a.b` (or `$.Values.a.b`) as a path array, else undefined. */
+function valuesPathOf(expr: string): string[] | undefined {
+  const m = expr.match(/^\$?\.Values((?:\.[A-Za-z0-9_-]+)+)$/);
+  return m ? m[1].slice(1).split(".") : undefined;
+}
+
+interface BranchState {
+  frame: ScopeFrame;
+  /** All branch conditions seen so far in this if-chain. */
+  chain: string[];
+}
+
+/**
+ * Walk a file's actions and attach the enclosing control-flow frames to each.
+ * `else` / `else if` branches carry the prior branch conditions as
+ * `negatedConditions`. Structure that cannot be tracked (an unbalanced
+ * `end`, template text split across files) degrades to fewer frames — which
+ * only ever makes the classifier MORE conservative, never less: a missing
+ * frame means a gate we cannot prove closed.
+ */
+export function scopeActions(actions: TemplateAction[]): ScopedAction[] {
+  const scoped: ScopedAction[] = [];
+  const stack: BranchState[] = [];
+
+  for (const action of actions) {
+    switch (action.kind) {
+      case "if": {
+        const cond = actionPipeline(action);
+        // The `if` action itself is evaluated in the ENCLOSING scope.
+        scoped.push({ action, frames: stack.map((s) => s.frame) });
+        stack.push({
+          frame: { kind: "if", conditions: [cond], negatedConditions: [] },
+          chain: [cond],
+        });
+        break;
+      }
+      case "elseif": {
+        scoped.push({
+          action,
+          frames: stack.slice(0, -1).map((s) => s.frame),
+        });
+        const top = stack[stack.length - 1];
+        const cond = action.body.replace(/^else\s+if\b/, "").trim();
+        if (top) {
+          top.frame = {
+            kind: "if",
+            conditions: [cond],
+            negatedConditions: [...top.chain],
+          };
+          top.chain.push(cond);
+        }
+        break;
+      }
+      case "else": {
+        scoped.push({
+          action,
+          frames: stack.slice(0, -1).map((s) => s.frame),
+        });
+        const top = stack[stack.length - 1];
+        if (top) {
+          top.frame = {
+            kind: top.frame.kind === "if" ? "if" : top.frame.kind,
+            conditions: [],
+            negatedConditions: [...top.chain],
+          };
+        }
+        break;
+      }
+      case "with": {
+        const expr = actionPipeline(action);
+        scoped.push({ action, frames: stack.map((s) => s.frame) });
+        const path = valuesPathOf(expr);
+        stack.push({
+          frame: {
+            kind: "with",
+            conditions: [expr],
+            negatedConditions: [],
+            dotValuesPath: path,
+            dotUnresolvable: path === undefined,
+          },
+          chain: [expr],
+        });
+        break;
+      }
+      case "range": {
+        const expr = actionPipeline(action);
+        scoped.push({ action, frames: stack.map((s) => s.frame) });
+        stack.push({
+          frame: {
+            kind: "range",
+            conditions: [expr],
+            negatedConditions: [],
+            dotUnresolvable: true,
+          },
+          chain: [expr],
+        });
+        break;
+      }
+      case "define":
+      case "block": {
+        scoped.push({ action, frames: stack.map((s) => s.frame) });
+        // A define body runs with whatever context `include`/`template`
+        // passes. Most charts pass the root context; the frame records
+        // nothing to gate on, so constructs inside a define are treated as
+        // reachable unless gated within the define itself.
+        stack.push({
+          frame: { kind: action.kind, conditions: [], negatedConditions: [] },
+          chain: [],
+        });
+        break;
+      }
+      case "end": {
+        scoped.push({
+          action,
+          frames: stack.slice(0, -1).map((s) => s.frame),
+        });
+        stack.pop();
+        break;
+      }
+      default:
+        scoped.push({ action, frames: stack.map((s) => s.frame) });
+    }
+  }
+  return scoped;
+}