@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/src/describe-resources.test.ts

@@ -0,0 +1,255 @@
+import { describe, test, expect } from "vitest";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { describeResources } from "./describe-resources";
+import { parseReleaseDocuments } from "./release-observe";
+import type { HelmRunner } from "./release-observe";
+
+const LIST = JSON.stringify([
+  {
+    name: "web-app",
+    namespace: "prod",
+    revision: "3",
+    updated: "2026-08-01 10:00:00.000000000 +0000 UTC",
+    status: "deployed",
+    chart: "web-app-0.1.0",
+    app_version: "1.0.0",
+  },
+]);
+
+const MANIFEST = `---
+# Source: web-app/templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-app
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: shop
+    chant.intentius.io/env: prod
+spec:
+  replicas: 2
+---
+# Source: web-app/templates/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web-app
+  namespace: elsewhere
+spec:
+  ports:
+    - port: 80
+---
+# Source: web-app/crds/widgets.yaml
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: widgets.example.com
+`;
+
+const HOOKS = `---
+# Source: web-app/templates/migrate-job.yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: web-app-migrate
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "1"
+    "helm.sh/hook-delete-policy": hook-succeeded
+`;
+
+/** A scripted helm CLI: canned stdout per subcommand, recorded commands. */
+function scriptedHelm(
+  outputs: { list?: string; manifest?: string; hooks?: string },
+  commands: string[] = [],
+): HelmRunner {
+  return async (command) => {
+    commands.push(command);
+    if (command.startsWith("helm list")) return { stdout: outputs.list ?? "[]" };
+    if (command.startsWith("helm get manifest")) {
+      if (outputs.manifest === undefined) throw new Error("release: not found");
+      return { stdout: outputs.manifest };
+    }
+    if (command.startsWith("helm get hooks")) {
+      if (outputs.hooks === undefined) throw new Error("release: not found");
+      return { stdout: outputs.hooks };
+    }
+    throw new Error(`unexpected command: ${command}`);
+  };
+}
+
+const chartEntities = new Map([
+  ["chart", { entityType: "Helm::Chart", props: { name: "web-app" } }],
+  ["valuesSchema", { entityType: "Helm::Values", props: { replicaCount: 2 } }],
+]);
+
+const baseOptions = {
+  environment: "prod",
+  buildOutput: "",
+  entityNames: [...chartEntities.keys()],
+  entities: chartEntities,
+};
+
+describe("helm describeResources (#1246)", () => {
+  test("reads BOTH channels: manifest resources and hook resources are rows", async () => {
+    const commands: string[] = [];
+    const result = await describeResources(baseOptions, scriptedHelm({ list: LIST, manifest: MANIFEST, hooks: HOOKS }, commands));
+    const { resources, unobserved } = normalizeObservation(result);
+
+    expect(commands.some((c) => c.startsWith("helm get manifest 'web-app' -n 'prod'"))).toBe(true);
+    expect(commands.some((c) => c.startsWith("helm get hooks 'web-app' -n 'prod'"))).toBe(true);
+
+    // The release row, keyed by the chart entity.
+    expect(resources.chart).toMatchObject({
+      type: "Helm::Release",
+      physicalId: "prod/web-app",
+      status: "deployed",
+      ownership: "owned",
+    });
+
+    // Manifest channel: namespace-silent documents inherit the release
+    // namespace; explicit namespaces are kept; cluster-scoped kinds get none.
+    expect(resources["Deployment/prod/web-app"]).toMatchObject({
+      type: "K8s::Apps::Deployment",
+      attributes: expect.objectContaining({ channel: "manifest", release: "web-app" }),
+    });
+    expect(resources["Service/elsewhere/web-app"]).toBeDefined();
+    expect(resources["cluster:CustomResourceDefinition/widgets.example.com"]).toBeDefined();
+
+    // Hooks channel: excluded from `helm get manifest`, so this row only
+    // exists because both channels were read.
+    expect(resources["Job/prod/web-app-migrate"]).toMatchObject({
+      type: "K8s::Batch::Job",
+      attributes: expect.objectContaining({
+        channel: "hooks",
+        hook: "pre-install,pre-upgrade",
+        hookWeight: "1",
+        hookDeletePolicy: "hook-succeeded",
+      }),
+    });
+
+    expect(unobserved).toEqual({});
+  });
+
+  test("every rendered resource is owned via release identity and a runtime child of its chart (#1077)", async () => {
+    const result = await describeResources(baseOptions, scriptedHelm({ list: LIST, manifest: MANIFEST, hooks: HOOKS }));
+    const { resources } = normalizeObservation(result);
+    for (const key of ["Deployment/prod/web-app", "Service/elsewhere/web-app", "Job/prod/web-app-migrate"]) {
+      expect(resources[key].ownership).toBe("owned");
+      expect(resources[key].ownerChain).toEqual({ root: "declared", entity: "chart" });
+    }
+  });
+
+  test("surfaces chant's stack/env marker verbatim where the rendered labels carry it (#1222)", async () => {
+    const result = await describeResources(baseOptions, scriptedHelm({ list: LIST, manifest: MANIFEST, hooks: HOOKS }));
+    const { resources } = normalizeObservation(result);
+    expect(resources["Deployment/prod/web-app"].marker).toEqual({ stack: "shop", env: "prod" });
+    expect(resources["Service/elsewhere/web-app"].marker).toBeUndefined();
+  });
+
+  test("chart-authoring satellites ride the single chart's release verdict", async () => {
+    const present = normalizeObservation(
+      await describeResources(baseOptions, scriptedHelm({ list: LIST, manifest: MANIFEST, hooks: HOOKS })),
+    );
+    expect(present.resources.valuesSchema).toMatchObject({
+      type: "Helm::Values",
+      status: "deployed",
+      ownership: "owned",
+    });
+
+    // Release absent → chart AND satellites in neither map (create is right).
+    const absent = normalizeObservation(await describeResources(baseOptions, scriptedHelm({ list: "[]" })));
+    expect(absent.resources).toEqual({});
+    expect(absent.unobserved).toEqual({});
+  });
+
+  test("missing helm binary: every declared entity is unobserved with no-credentials, never a clean empty snapshot", async () => {
+    const result = await describeResources(baseOptions, async () => {
+      throw Object.assign(new Error("/bin/sh: helm: command not found"), { code: 127 });
+    });
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources).toEqual({});
+    expect(unobserved.chart.reason).toBe("no-credentials");
+    expect(unobserved.valuesSchema.reason).toBe("no-credentials");
+  });
+
+  test("unreachable cluster (kubeconfig): no-credentials with the CLI's own words", async () => {
+    const result = await describeResources(baseOptions, async () => {
+      throw new Error('Error: Kubernetes cluster unreachable: Get "https://127.0.0.1:6443/version": connect: connection refused');
+    });
+    const { unobserved } = normalizeObservation(result);
+    expect(unobserved.chart.reason).toBe("no-credentials");
+  });
+
+  test("an unreachable release is unobserved with a reason, never absent (#1246)", async () => {
+    // `helm list` succeeds, `helm get manifest` fails.
+    const result = await describeResources(baseOptions, scriptedHelm({ list: LIST }));
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources.chart).toBeUndefined();
+    expect(unobserved.chart.reason).toBe("read-failed");
+    // The satellite shares the hole, with the same reason.
+    expect(unobserved.valuesSchema.reason).toBe("read-failed");
+  });
+
+  test("a release deployed under another name resolves through its chart identity", async () => {
+    const list = JSON.stringify([
+      { name: "web-prod", namespace: "prod", status: "deployed", chart: "web-app-0.1.0", revision: "1" },
+    ]);
+    const { resources } = normalizeObservation(
+      await describeResources(baseOptions, scriptedHelm({ list, manifest: MANIFEST, hooks: "" })),
+    );
+    expect(resources.chart).toMatchObject({ physicalId: "prod/web-prod" });
+  });
+
+  test("the deploy unit (`stack`) names the release for a single-chart project", async () => {
+    const list = JSON.stringify([
+      { name: "custom-name", namespace: "apps", status: "deployed", chart: "something-else-2.0.0" },
+    ]);
+    const { resources } = normalizeObservation(
+      await describeResources(
+        { ...baseOptions, stack: "apps/custom-name" },
+        scriptedHelm({ list, manifest: "", hooks: "" }),
+      ),
+    );
+    expect(resources.chart).toMatchObject({ physicalId: "apps/custom-name" });
+  });
+
+  test("the same release name in several namespaces is unobserved, not guessed and not absent", async () => {
+    const list = JSON.stringify([
+      { name: "web-app", namespace: "a", status: "deployed", chart: "web-app-0.1.0" },
+      { name: "web-app", namespace: "b", status: "deployed", chart: "web-app-0.1.0" },
+    ]);
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(baseOptions, scriptedHelm({ list })),
+    );
+    expect(resources.chart).toBeUndefined();
+    expect(unobserved.chart.reason).toBe("read-failed");
+    expect(unobserved.chart.detail).toContain("several namespaces");
+  });
+
+  test("--owned filters nothing and says so in a note — every row is release-scoped", async () => {
+    const result = await describeResources(
+      { ...baseOptions, owned: true },
+      scriptedHelm({ list: LIST, manifest: MANIFEST, hooks: HOOKS }),
+    );
+    const { resources, notes } = normalizeObservation(result);
+    expect(Object.keys(resources).length).toBeGreaterThan(0);
+    expect(notes.some((n) => n.includes("--owned"))).toBe(true);
+  });
+});
+
+describe("helm release document parsing", () => {
+  test("tolerates comments, empty documents and non-object documents", () => {
+    const rows = parseReleaseDocuments(
+      `# just a comment\n---\n---\n"scalar"\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: cm\n`,
+      "manifest",
+      "prod",
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ key: "ConfigMap/prod/cm", entityType: "K8s::Core::ConfigMap" });
+  });
+
+  test("unparseable YAML yields no rows rather than throwing", () => {
+    expect(parseReleaseDocuments("{{ not yaml", "manifest", "prod")).toEqual([]);
+  });
+});

package/src/describe-resources.ts

@@ -0,0 +1,198 @@
+/**
+ * Live introspection of Helm releases per resource — the helm lexicon's
+ * `describeResources` (#1246, epic #1228 phase 5).
+ *
+ * `listArtifacts` reports release *metadata* (name, revision, status) and no
+ * resource state, which is why `lifecycle diff --live` had nothing to compare
+ * for a Helm-managed estate. This read goes one level down: for each release
+ * a declared `Helm::Chart` deploys, it fetches what the release holds —
+ * `helm get manifest` AND `helm get hooks`, both channels, because hooks are
+ * excluded from the manifest channel and reading one would report every hook
+ * resource as drift — and reports one row per rendered resource.
+ *
+ * ## Verdicts (#1089)
+ *
+ * - The chart entity itself is OBSERVED-PRESENT as the release
+ *   (`Helm::Release`), OBSERVED-ABSENT when `helm list` was asked and did
+ *   not report it (only that becomes a `create`), and NOT-OBSERVED with a
+ *   total reason when helm or the cluster could not be reached — a missing
+ *   binary or kubeconfig is `no-credentials`, never a clean empty snapshot.
+ * - Every rendered resource is reported `ownership: "owned"` — helm-managed
+ *   via release identity: the read is scoped to the release, so everything
+ *   it returns is by construction managed by a release this project
+ *   declares. Rows additionally surface chant's own stack/env marker
+ *   (#1222) verbatim when the rendered labels carry it.
+ * - Every rendered resource carries `ownerChain: { root: "declared" }`
+ *   pointing at its chart entity, so the diff engine classifies it
+ *   `runtime` rather than `orphan` (#1077) — an unpinned release is not
+ *   drift. Controller-created children (Pods under a chart's Deployment)
+ *   are the k8s lexicon's rows; its own owner-chain walk classifies them.
+ *
+ * ## Chart-authoring satellites
+ *
+ * `Helm::Values`, `Helm::Notes`, `Helm::Test` and the other authoring
+ * entities have no runtime identity of their own — their deployed form IS
+ * the release (helm stores the applied values and rendered NOTES.txt in the
+ * release record). In a single-chart project they ride the chart's verdict:
+ * present when the release is, absent when it is not, unobserved with the
+ * same reason otherwise. A multi-chart project cannot attribute them to one
+ * release, so they are NOT-OBSERVED (`unsupported-kind`) with a detail
+ * saying so.
+ */
+import type { ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import type { ObservationResult } from "@intentius/chant/observation";
+import { observation } from "@intentius/chant/observation";
+import { LABEL_OWNERSHIP_KEYS, readOwnership } from "@intentius/chant/ownership";
+import {
+  HELM_CHART_ENTITY_TYPE,
+  HELM_RELEASE_TYPE,
+  defaultHelmRunner,
+  observeReleases,
+  type HelmRunner,
+  type ObservedRelease,
+} from "./release-observe";
+
+export interface HelmDescribeOptions {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  region?: string;
+  owned?: boolean;
+  namespace?: string;
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+function releaseRow(release: ObservedRelease): ResourceMetadata {
+  return {
+    type: HELM_RELEASE_TYPE,
+    physicalId: `${release.namespace}/${release.release}`,
+    status: release.status ?? "unknown",
+    ...(release.updated ? { lastUpdated: release.updated } : {}),
+    ownership: "owned",
+    attributes: pruneUndefined({
+      chart: release.chart,
+      revision: release.revision,
+      appVersion: release.appVersion,
+      namespace: release.namespace,
+      resources: release.resources.length,
+    }),
+  };
+}
+
+export async function describeResources(
+  options: HelmDescribeOptions,
+  run: HelmRunner = defaultHelmRunner,
+): Promise<ObservationResult> {
+  const satellites: Array<{ entityName: string; entityType: string }> = [];
+  for (const [entityName, entity] of options.entities) {
+    if (entity.entityType !== HELM_CHART_ENTITY_TYPE) {
+      satellites.push({ entityName, entityType: entity.entityType });
+    }
+  }
+
+  const observed = await observeReleases(
+    { environment: options.environment, entities: options.entities, stack: options.stack },
+    run,
+  );
+
+  const chartCount = options.entities.size - satellites.length;
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = { ...observed.unobserved };
+  const notes: string[] = [];
+
+  if (chartCount === 0 && satellites.length > 0) {
+    for (const { entityName, entityType } of satellites) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: "chart-authoring entity with no declared Helm::Chart to attribute a release to",
+      };
+    }
+    return observation(resources, unobserved, observed.queried, notes);
+  }
+
+  for (const release of observed.releases) {
+    resources[release.entityName] = releaseRow(release);
+
+    for (const row of release.resources) {
+      const labels = (row.doc.metadata as { labels?: Record<string, unknown> } | undefined)?.labels;
+      const marker = readOwnership(labels, LABEL_OWNERSHIP_KEYS);
+      resources[row.key] = {
+        type: row.entityType,
+        physicalId: row.namespace ? `${row.namespace}/${row.name}` : row.name,
+        status: release.status ?? "unknown",
+        // Owned via release identity (#1246): the read is scoped to a release
+        // this project declares, so every document it returns is helm-managed
+        // by construction — the release IS the marker channel here.
+        ownership: "owned",
+        ...(marker ? { marker } : {}),
+        // The release's resources are what the declared chart deploys —
+        // expected runtime, never orphan/delete candidates (#1077).
+        ownerChain: { root: "declared", entity: release.entityName },
+        attributes: pruneUndefined({
+          release: release.release,
+          releaseNamespace: release.namespace,
+          namespace: row.namespace,
+          channel: row.channel,
+          hook: row.hook?.hook,
+          hookWeight: row.hook?.weight,
+          hookDeletePolicy: row.hook?.deletePolicy,
+        }),
+      };
+    }
+  }
+
+  // Chart-authoring satellites ride the single chart's verdict; see the
+  // module doc. Their deployed form is the release itself, so the release
+  // read is the honest answer for them — present, absent, or unobserved
+  // exactly as the chart is.
+  if (satellites.length > 0) {
+    if (chartCount === 1) {
+      const [chartEntity] = [...options.entities].find(
+        ([, e]) => e.entityType === HELM_CHART_ENTITY_TYPE,
+      )!;
+      const release = observed.releases.find((r) => r.entityName === chartEntity);
+      const hole = unobserved[chartEntity];
+      for (const { entityName, entityType } of satellites) {
+        if (release) {
+          resources[entityName] = {
+            type: entityType,
+            physicalId: `${release.namespace}/${release.release}`,
+            status: release.status ?? "unknown",
+            ownership: "owned",
+            attributes: { release: release.release, namespace: release.namespace, via: "release-identity" },
+          };
+        } else if (hole) {
+          unobserved[entityName] = { type: entityType, reason: hole.reason, ...(hole.detail ? { detail: hole.detail } : {}) };
+        }
+        // Release confirmed absent → the satellite is absent too: in neither
+        // map, and deploying the chart is what creates it.
+      }
+    } else {
+      for (const { entityName, entityType } of satellites) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "unsupported-kind",
+          detail: "chart-authoring entity in a multi-chart project — cannot attribute it to a single release",
+        };
+      }
+    }
+  }
+
+  if (options.owned) {
+    notes.push(
+      "helm scopes reads to declared releases, so every row is helm-managed (owned) by construction — --owned withholds nothing",
+    );
+  }
+
+  return observation(resources, unobserved, observed.queried, notes);
+}

package/src/index.ts

@@ -10,12 +10,103 @@ export { helmPlugin } from "./plugin";
 export { helmCapabilityPlugin, HELM_VERB_FAMILIES } from "./components/capability-plugin";
 export { helmUpgradeCapability, createHelmUpgradeCapability, type HelmUpgradeInput, type HelmUpgradeOutcome } from "./components/helm-upgrade";
 
+// Typed Op step-builder wrappers (chant #1288 Stage 2) — helmInstall/
+// helmInstallPinned with authoring-time types derived from this lexicon's
+// own HelmInstallArgs (see ./op/builders.ts's module doc for why these live
+// here rather than in core or the temporal barrel). Opt-in:
+// `@intentius/chant-lexicon-temporal`'s same-named exports are core's
+// original untyped builders, unchanged, for cloud-agnostic authoring.
+export { helmInstall, helmInstallPinned } from "./op/builders";
+
 // Resources
 export { Chart, Values, ValuesOverride, HelmTest, HelmNotes, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources";
 
 // HelmRender — render an upstream chart at chant build time
-export { HelmRender } from "./render";
-export type { HelmRenderProps } from "./render";
+export { HelmRender, getHelmRenderRecords, clearHelmRenderRecords } from "./render";
+export type { HelmRenderProps, HelmRenderRecord } from "./render";
+
+// #1237 — render canonicalization + the contentDigest/inputDigest split.
+export { canonicalizeRender, helmContentDigest, helmInputDigest, renderStability } from "./render-digest";
+export type { HelmInputDigestSource, RenderStabilityGroup, RenderStabilityReport } from "./render-digest";
+
+// #1238 — RenderManifest + content-addressed render storage.
+export {
+  helmValuesDigest,
+  indexRenderDocuments,
+  renderCacheKey,
+  renderStoreRoot,
+  persistHelmRender,
+  loadRenderManifest,
+  loadRenderContent,
+  listRenderManifests,
+  findRenderByCacheKey,
+  readRenderDocument,
+} from "./render-store";
+export type {
+  RenderManifest,
+  RenderDocumentEntry,
+  RenderDocumentRef,
+  RenderCacheKeySource,
+  RenderInputsIndexEntry,
+  PersistHelmRenderInput,
+  PersistedHelmRender,
+} from "./render-store";
+
+// #1239 — structure-preserving render wrapper: segment-based CRD routing.
+export { routeRender, routeStoredRender } from "./render-wrapper";
+export type {
+  RoutedRender,
+  RoutedDocument,
+  RoutedRenderWarning,
+  RoutedRenderWarningCode,
+  RouteRenderOptions,
+} from "./render-wrapper";
+
+// #1242 — pinned install path: wrapper-chart materialization.
+export { materializeWrapperChart, wrapperChartName } from "./wrapper-chart";
+export type { MaterializedWrapperChart } from "./wrapper-chart";
+
+// #1240 — addArchiveHelmRender: fold a pinned render into a build archive.
+export { addArchiveHelmRender, HELM_RENDER_MEDIA_TYPE } from "./archive-render";
+export type { AddArchiveHelmRenderInput, AddArchiveHelmRenderOutput } from "./archive-render";
+
+// #1251/#1252 — build-time coalesced-values probe and its provenance products.
+export {
+  probeCoalescedValues,
+  coalescedValuesDigest,
+  computeValueSources,
+  findDeadAssignments,
+  rootCoalescedValues,
+  getValuesProbeRecords,
+  recordValuesProbe,
+  clearValuesProbeRecords,
+} from "./values-probe";
+export type {
+  ValuesProbeOptions,
+  CoalescedValuesProbe,
+  CoalescedChartValues,
+  DisabledDependency,
+  SuppliedValuesLayer,
+  ValueOrigin,
+  ValuesAttributionInput,
+  DeadAssignment,
+  HelmValuesProbeRecord,
+} from "./values-probe";
+
+// Capability profiles — per-cluster render inputs (#1235, epic #1228)
+export {
+  helmConfigSchema,
+  helmCapabilityProfileSchema,
+  resolveCapabilityProfile,
+  validateCapabilityProfile,
+  KUBE_VERSION_PATTERN,
+} from "./config";
+export type {
+  HelmChantConfig,
+  HelmCapabilityProfile,
+  HelmCapabilityProfileConfig,
+  HelmCapabilityProfileRef,
+} from "./config";
 
 // Intrinsics
 export {
@@ -113,6 +204,19 @@ export { HelmGenerator } from "./import/generator";
 export { stripTemplateExpressions, classifyExpression } from "./import/template-stripper";
 export type { StrippedExpression, StripResult, ExpressionKind } from "./import/template-stripper";
 
+// Pinnability gate (#1234, epic #1228) — what the pinned-render pipeline
+// consults before anything is pinned
+export { classifyChart } from "./pinnability";
+export type {
+  PinnabilityVerdict,
+  PinnabilityReport,
+  ClassifyChartOptions,
+  CapabilityRequirement,
+  ClosedInput,
+  ConditionalHazard,
+  RenderEvidence,
+} from "./pinnability";
+
 // LSP providers
 export { helmCompletions } from "./lsp/completions";
 export { helmHover } from "./lsp/hover";