@intentius/chant-lexicon-helm 0.124.30 → 0.124.32

package/dist/render-diff.js

@@ -0,0 +1,279 @@
+/**
+ * Render diffing (#1249 offline, #1250 live — epic #1228 Phase 6), the two
+ * halves of `chant helm diff` (./commands.ts).
+ *
+ * `diffRenders` (#1249) is the offline half: given two content digests
+ * already in the render store (render-store.ts), report what changed
+ * between them — no cluster, no credentials, no live read. This is the
+ * pre-flight question a pin, a chart bump, or a values change all raise:
+ * "what will this touch?"
+ *
+ * Pairing is document-level, keyed on `(kind, namespace, name)` — the same
+ * identity `RenderManifest.documents` already indexes (render-store.ts).
+ * That index exists precisely so two renders can be matched without
+ * reparsing a whole stream: a document present on both sides with the same
+ * per-document digest is unchanged and costs nothing further; one whose
+ * digest differs is parsed on both sides and diffed field by field.
+ *
+ * Field-level diffing reuses core's `flattenDeepProperties` /
+ * `deepValueEqual` (packages/core/src/deep-observation.ts) — the same
+ * path-flattening core's own live-drift diff (lifecycle/deep-diff.ts) is
+ * built on. This module does not reuse `diffDeep` itself for the offline
+ * path: that function's shape is declared/live/baseline/fieldOwners,
+ * tailored to a source tree vs a cluster read. A stored render has neither
+ * a baseline nor a field owner, and both sides here are equally "declared"
+ * — reusing the flatten/compare primitives without the three-way apparatus
+ * is the right cut for render-to-render.
+ *
+ * Duplicate documents (an aliased dependency emitting the same CRD twice,
+ * render-digest.ts's canonicalization note) are matched positionally within
+ * their `(kind, namespace, name)` group: first occurrence to first, second
+ * to second. A group with more entries on one side reports the surplus as
+ * added or removed rather than guessing which duplicate corresponds to
+ * which.
+ *
+ * A document neither side's manifest could index (unparseable, or missing
+ * `kind`/`metadata.name` — render-store.ts's `indexRenderDocuments`) cannot
+ * be paired by identity. It is never silently dropped: `unindexed` counts
+ * it on whichever side(s) it appears, so a diff over two renders that both
+ * carry unindexable documents does not quietly under-report.
+ *
+ * `diffRenderLive` (#1250) is the online complement: given a single
+ * `contentDigest` resolved from the render store, read the live property
+ * tree for every document the render recorded — by identity
+ * (kind/namespace/name), not by helm release — and diff each one against
+ * the render's own stored bytes with `lifecycle/deep-diff.ts`. This *does*
+ * reuse `diffDeep`'s three-way apparatus (via `diffDeepObservation`): the
+ * declared side is the render's stored documents, the live side is a
+ * cluster read, which is exactly that function's shape.
+ *
+ * The declared side for the live path is the render's stored documents,
+ * never a fresh `helm template` run and never a chant TS build. A digest
+ * not in the store — an unpinned render was never persisted
+ * (`render-store.ts`'s `persistHelmRender` refuses that) — has nothing to
+ * diff against and comes back `found: false`, never a false "no drift" over
+ * documents nobody has (epic AC: unpinned releases handled without false
+ * drift).
+ *
+ * The live side reuses the exact seam `observeResourcesDeepHelm` (#1247)
+ * uses — the k8s lexicon's typed client and normalization hooks — so a
+ * document this reads and one a release's `describeResources` reads compare
+ * under the same rules (secret masking, managed-fields ownership, pruning).
+ * Hook resources need no special handling here the way the release-scoped
+ * read needs a second `helm get hooks` channel: `helm template` (what
+ * produced the stored render) already includes hook manifests as ordinary
+ * documents, so they are simply rows in `manifest.documents` like any other.
+ */
+import yaml from "js-yaml";
+import { deepValueEqual, flattenDeepProperties, normalizeDeepObservation } from "@intentius/chant/deep-observation";
+import { diffDeepObservation } from "@intentius/chant/lifecycle/deep-observe";
+import { observeResourcesDeepK8s } from "@intentius/chant-lexicon-k8s/deep-observe";
+import { gvkToTypeName } from "@intentius/chant-lexicon-k8s/spec/parse";
+import { helmDeepNormalizationHooks } from "./deep-observe-hooks.js";
+import { CLUSTER_SCOPED_KINDS } from "./release-observe.js";
+import { loadRenderManifest, readRenderDocument } from "./render-store.js";
+function docKey(doc) {
+    return `${doc.kind}\0${doc.namespace ?? ""}\0${doc.name}`;
+}
+function docRef(doc) {
+    return { kind: doc.kind, namespace: doc.namespace, name: doc.name, source: doc.source };
+}
+/** Group a manifest's document entries by identity, preserving occurrence order for duplicate matching. */
+function groupByIdentity(documents) {
+    const groups = new Map();
+    for (const doc of documents) {
+        const key = docKey(doc);
+        const group = groups.get(key);
+        if (group)
+            group.push(doc);
+        else
+            groups.set(key, [doc]);
+    }
+    return groups;
+}
+function compareRefs(a, b) {
+    return (a.kind.localeCompare(b.kind) ||
+        (a.namespace ?? "").localeCompare(b.namespace ?? "") ||
+        a.name.localeCompare(b.name));
+}
+/**
+ * Field-level diff between a document's two parsed trees. Both sides are
+ * flattened with `flattenDeepProperties` (no ordering hooks — a stored
+ * render carries no lexicon to supply one, so arrays are compared
+ * positionally, exactly as the canonicalized bytes ordered them) and walked
+ * path by path.
+ */
+function diffDocumentFields(beforeText, afterText, entityType) {
+    const beforeTree = (yaml.load(beforeText) ?? {});
+    const afterTree = (yaml.load(afterText) ?? {});
+    const beforeFlat = flattenDeepProperties(beforeTree, { entityType, side: "declared" });
+    const afterFlat = flattenDeepProperties(afterTree, { entityType, side: "live" });
+    const paths = [...new Set([...beforeFlat.keys(), ...afterFlat.keys()])].sort();
+    const changes = [];
+    for (const path of paths) {
+        const hasBefore = beforeFlat.has(path);
+        const hasAfter = afterFlat.has(path);
+        const beforeValue = beforeFlat.get(path);
+        const afterValue = afterFlat.get(path);
+        if (hasBefore && hasAfter && deepValueEqual(beforeValue, afterValue))
+            continue;
+        const kind = !hasBefore ? "added" : !hasAfter ? "removed" : "changed";
+        changes.push({
+            path,
+            kind,
+            ...(hasBefore ? { before: beforeValue } : {}),
+            ...(hasAfter ? { after: afterValue } : {}),
+        });
+    }
+    return changes;
+}
+/**
+ * Diff two renders already in the store, by content digest. Offline: every
+ * byte compared comes from the archive (render-store.ts), never a cluster.
+ *
+ * Throws when either digest has no manifest — a diff over a render nobody
+ * persisted is a usage error, not an empty report.
+ */
+export function diffRenders(from, to, options) {
+    const opts = { root: options?.root };
+    const fromManifest = requireManifest(from, opts.root);
+    const toManifest = requireManifest(to, opts.root);
+    const fromGroups = groupByIdentity(fromManifest.documents);
+    const toGroups = groupByIdentity(toManifest.documents);
+    const added = [];
+    const removed = [];
+    const changed = [];
+    const unchanged = [];
+    const keys = new Set([...fromGroups.keys(), ...toGroups.keys()]);
+    for (const key of keys) {
+        const fromEntries = fromGroups.get(key) ?? [];
+        const toEntries = toGroups.get(key) ?? [];
+        const pairCount = Math.min(fromEntries.length, toEntries.length);
+        for (let i = 0; i < pairCount; i++) {
+            const fromDoc = fromEntries[i];
+            const toDoc = toEntries[i];
+            if (fromDoc.digest === toDoc.digest) {
+                unchanged.push(docRef(fromDoc));
+                continue;
+            }
+            const fromRead = readRenderDocument(from, fromDoc, opts);
+            const toRead = readRenderDocument(to, toDoc, opts);
+            /* c8 ignore next 5 -- indexed entries always resolve; defensive only */
+            if (!fromRead || !toRead) {
+                throw new Error(`render diff: indexed document ${fromDoc.kind}/${fromDoc.name} failed to resolve from its own store entry`);
+            }
+            changed.push({
+                ...docRef(fromDoc),
+                beforeDigest: fromDoc.digest,
+                afterDigest: toDoc.digest,
+                changes: diffDocumentFields(fromRead.text, toRead.text, fromDoc.kind),
+            });
+        }
+        for (let i = pairCount; i < fromEntries.length; i++) {
+            removed.push({ ...docRef(fromEntries[i]), digest: fromEntries[i].digest });
+        }
+        for (let i = pairCount; i < toEntries.length; i++) {
+            added.push({ ...docRef(toEntries[i]), digest: toEntries[i].digest });
+        }
+    }
+    return {
+        from: { contentDigest: fromManifest.contentDigest, chart: fromManifest.chart, releaseName: fromManifest.releaseName },
+        to: { contentDigest: toManifest.contentDigest, chart: toManifest.chart, releaseName: toManifest.releaseName },
+        added: added.sort(compareRefs),
+        removed: removed.sort(compareRefs),
+        changed: changed.sort(compareRefs),
+        unchanged: unchanged.sort(compareRefs),
+        unindexed: {
+            from: fromManifest.docCount - fromManifest.documents.length,
+            to: toManifest.docCount - toManifest.documents.length,
+        },
+    };
+}
+function requireManifest(contentDigest, root) {
+    const manifest = loadRenderManifest(contentDigest, { root });
+    if (!manifest) {
+        throw new Error(`no stored render for ${contentDigest} — resolve it first (chant helm renders), or check ` +
+            `CHANT_HELM_RENDER_ROOT if the store root was overridden.`);
+    }
+    return manifest;
+}
+/** True when the diff found no added, removed, or changed documents. */
+export function renderDiffIsEmpty(result) {
+    return result.added.length === 0 && result.removed.length === 0 && result.changed.length === 0;
+}
+function splitApiVersion(apiVersion) {
+    const slash = apiVersion.indexOf("/");
+    return slash > 0
+        ? { group: apiVersion.slice(0, slash), version: apiVersion.slice(slash + 1) }
+        : { group: "", version: apiVersion };
+}
+/** Row key convention shared with the release-scoped reads (#1246/#1247): `<Kind>/<namespace>/<name>`, `cluster:<Kind>/<name>`. */
+export function documentKey(kind, namespace, name) {
+    return namespace ? `${kind}/${namespace}/${name}` : `cluster:${kind}/${name}`;
+}
+/**
+ * A namespace-silent document defaults to the render's target namespace —
+ * the same rule a deployed release applies to its manifest (`helm apply
+ * -n <ns>` targets whatever a namespace-silent object's `.Release.Namespace`
+ * would have filled in) — unless the kind is cluster-scoped, in which case a
+ * missing namespace is never defaulted.
+ */
+export function resolveDocumentNamespace(kind, declared, renderNamespace) {
+    if (declared)
+        return declared;
+    if (CLUSTER_SCOPED_KINDS.has(kind))
+        return undefined;
+    return renderNamespace ?? undefined;
+}
+/** The document minus the envelope the row's `type` already carries — mirrors `deep-observe.ts`'s `declaredTreeOf`. */
+function declaredTreeOf(doc, namespace) {
+    const { apiVersion: _apiVersion, kind: _kind, ...rest } = doc;
+    const metadata = (rest.metadata ?? {});
+    return {
+        ...rest,
+        ...(namespace ? { metadata: { ...metadata, ...(metadata.namespace === undefined ? { namespace } : {}) } } : {}),
+    };
+}
+/**
+ * Diff one stored render's documents against the live cluster.
+ *
+ * `found: false` when `contentDigest` is not in the store — never fabricates
+ * a document, and never reports "no drift" over a render this has no bytes
+ * for. On a found render, every document indexed in its manifest becomes a
+ * synthetic declared entity (keyed like a release's rows), read live through
+ * the k8s lexicon's deep observer, and diffed property-by-property.
+ */
+export async function diffRenderLive(options, deps = {}) {
+    const manifest = loadRenderManifest(options.contentDigest, { root: options.root });
+    if (!manifest)
+        return { found: false, contentDigest: options.contentDigest };
+    const entities = new Map();
+    for (const docEntry of manifest.documents) {
+        const resolved = readRenderDocument(options.contentDigest, { kind: docEntry.kind, name: docEntry.name, namespace: docEntry.namespace }, { root: options.root });
+        if (!resolved)
+            continue; // integrity gap between the index and the content — skip, never fabricate
+        const parsed = yaml.load(resolved.text);
+        if (parsed === null || typeof parsed !== "object")
+            continue;
+        const namespace = resolveDocumentNamespace(docEntry.kind, docEntry.namespace, manifest.namespace);
+        const key = documentKey(docEntry.kind, namespace, docEntry.name);
+        const { group, version } = splitApiVersion(docEntry.apiVersion);
+        entities.set(key, {
+            entityType: gvkToTypeName({ group, version, kind: docEntry.kind }),
+            props: declaredTreeOf(parsed, namespace),
+        });
+    }
+    const k8sOptions = {
+        environment: options.environment,
+        buildOutput: "",
+        entityNames: [...entities.keys()],
+        entities,
+        ...(options.owned !== undefined ? { owned: options.owned } : {}),
+    };
+    const raw = deps.connect
+        ? await observeResourcesDeepK8s(k8sOptions, deps.connect)
+        : await observeResourcesDeepK8s(k8sOptions);
+    const live = normalizeDeepObservation(raw);
+    const diff = diffDeepObservation(entities, live, helmDeepNormalizationHooks);
+    return { found: true, manifest, diff };
+}

package/dist/render-records.js

@@ -0,0 +1,29 @@
+/**
+ * The in-process ledger of `HelmRender` invocations — split out of
+ * `./render.ts` so a post-synth check can read it without importing the
+ * render machinery (#1979 follow-up, found by the hosted audit's bump).
+ *
+ * WHM503 (`./lint/post-synth/whm503.ts`) scans these records, and post-synth
+ * barrels are edge-imported by the hosted audit service: everything they
+ * reach through static imports must be safe to initialize on workerd.
+ * `render.ts` is not — it imports the full `@intentius/chant` barrel, whose
+ * static graph reaches the TypeScript compiler (fold-import), and
+ * TypeScript's own module init touches `__filename`, which crashes the
+ * worker at startup. This module carries only the record shape and the
+ * ledger, imports nothing but a type, and keeps the barrel edge-clean;
+ * `render.ts` re-exports it all, so the lexicon's public surface is
+ * unchanged.
+ */
+const renderRecords = [];
+/** Append one invocation's record (called by `HelmRender`, ./render.ts). */
+export function recordHelmRender(record) {
+    renderRecords.push(record);
+}
+/** Every render recorded in this process, in invocation order. */
+export function getHelmRenderRecords() {
+    return renderRecords;
+}
+/** Reset the record list (test isolation). */
+export function clearHelmRenderRecords() {
+    renderRecords.length = 0;
+}