@intentius/chant-lexicon-helm 0.46.0 → 0.49.0

package/dist/pinnability/localize.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Double-render localizer for open generated inputs (#1236, epic #1228
+ * Phase 1).
+ *
+ * The static classifier (#1234) NAMES generator sites; this module proves
+ * which of them actually fire and maps every unstable output line back to
+ * the input that produced it. The mechanism is the epic's own: pin the
+ * input, not the output. For each candidate values path that could close a
+ * generator, render the chart twice with that path pinned — the lines that
+ * stop differing are the lines that input produced, cascades included
+ * (finding 6: one `randAlphaNum` admin password differed as the secret line
+ * PLUS a `checksum/secret` annotation derived from it; hoisting the secret
+ * alone would have desynchronized the checksum and silently broken
+ * restart-on-change).
+ *
+ * Candidate pins come from three static sources, each validated dynamically
+ * before being suggested:
+ *
+ *   1. the generator's own action (`x | default (randAlphaNum 16)` — the
+ *      classifier already names `x`),
+ *   2. enclosing control-flow gates (`if not .Values.core.existingSecret`
+ *      around the generator: supplying the existing-secret slot closes it),
+ *   3. the include chain — a generator inside `define "grafana.password"`
+ *      inherits the gates of every `include "grafana.password"` site, which
+ *      is where grafana's `{{- if .Values.adminPassword }} ... {{- else }}`
+ *      supply slot lives.
+ *
+ * A differing line no probe and no source mapping can explain is reported as
+ * UNLOCALIZED instability — never silently pinnable. A base double render
+ * with zero differing lines confirms the chart deterministic.
+ */
+import { type PinnabilityReport } from "./classify.js";
+/** Renders the chart with the given values paths pinned to literal strings. */
+export type RenderFn = (pins: Record<string, string>) => string;
+export type PinStyle = "supply" | "existing-slot" | "gate";
+export interface CandidatePin {
+    /** Root-scoped values path. */
+    path: string;
+    style: PinStyle;
+}
+/** One unstable output line, located in the rendered document set. */
+export interface LocalizedOccurrence {
+    /** Source template of the rendered document (`# Source:` origin). */
+    doc: string;
+    /** `Kind/name` of the document, when parseable. */
+    docId: string;
+    /** YAML key of the differing line (`admin-password`, `checksum/secret`). */
+    key: string;
+    /** 1-based line within the document, from the first base render. */
+    line: number;
+    /**
+     * The line lives in a different template than the generator — a derived
+     * field (checksum annotation, re-included secret) grouped under its root
+     * input rather than reported as independent instability.
+     */
+    derived: boolean;
+}
+/** One open generated input with the unstable lines localized to it. */
+export interface LocalizedInput {
+    fn: string;
+    /** Template file and line of the generator (classifier coordinates). */
+    file: string;
+    line: number;
+    /** The values path a supply-style pin uses, when one validated. */
+    valuesPath?: string;
+    /** A validated pin exists — supplying a value closes this input. */
+    suppliable: boolean;
+    /**
+     * The concrete values entry a user adds to close the input, e.g.
+     * `adminPassword: <generate once and supply>`. Absent when no candidate
+     * pin validated (the input is real but not closable via values).
+     */
+    suggestedPin?: string;
+    /** Chart-provided slots that also close it (`admin.existingSecret`). */
+    existingSlots: string[];
+    occurrences: LocalizedOccurrence[];
+}
+export interface LocalizationReport {
+    /** The base double render differed on zero lines. */
+    deterministic: boolean;
+    /** Differing line count of the base double render (per-render lines). */
+    differingLines: number;
+    inputs: LocalizedInput[];
+    /** Differing lines no probe and no source mapping explains. */
+    unlocalized: LocalizedOccurrence[];
+    /**
+     * Pinning every validated pin at once yields a stable render. Present
+     * only when at least one pin validated.
+     */
+    stableWithAllPins?: boolean;
+    /** How many `helm template` invocations the localization used. */
+    renders: number;
+}
+export interface LocalizeOptions {
+    render: RenderFn;
+    /** Values overrides, as `helm template --values` would merge them. */
+    values?: unknown;
+    /** Values files merged (in order) over the chart defaults. */
+    valuesFiles?: string[];
+    /** Probe budget per generator site (default 6). */
+    maxProbesPerInput?: number;
+}
+interface DiffOccurrence {
+    ident: string;
+    doc: string;
+    docId: string;
+    key: string;
+    line: number;
+}
+/**
+ * Diff two renders of the SAME inputs into a set of differing-line
+ * occurrences with identities stable across separate probe runs: documents
+ * pair by (`# Source:` origin, ordinal), lines identify by their YAML key
+ * plus ordinal rather than raw content — the content is exactly what varies.
+ */
+export declare function diffRenderPair(a: string, b: string): Map<string, DiffOccurrence>;
+/**
+ * Localize the open generated inputs of a chart: double-render, and map
+ * every differing line back to the input that produced it by pinning
+ * candidate inputs one at a time. See the module doc for the mechanism.
+ */
+export declare function localizeOpenInputs(chartDir: string, report: PinnabilityReport, options: LocalizeOptions): LocalizationReport;
+export {};
+//# sourceMappingURL=localize.d.ts.map

package/dist/pinnability/localize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localize.d.ts","sourceRoot":"","sources":["../../src/pinnability/localize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAWpB,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;AAEhE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,+DAA+D;IAC/D,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,QAAQ,CAAC;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAmCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CA4ChF;AA0ND;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,eAAe,GACvB,kBAAkB,CA8LpB"}

package/dist/pinnability/render-stream.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Helpers over a `helm template` output stream (#1234, epic #1228).
+ *
+ * The CRD routing rule here is what the structure-preserving wrapper
+ * (#1239) builds on, and the line diff seeds the double-render localizer
+ * (#1236). Both were proven in the survey harness before promotion.
+ */
+/** Split a `helm template` stream into non-empty documents. */
+export declare function splitDocuments(rendered: string): string[];
+/** The `# Source: <chart>/<path>` origin of a rendered document, if any. */
+export declare function sourcePath(doc: string): string | undefined;
+/**
+ * Finding 10: segment matching, not prefix matching. A subchart's CRDs
+ * arrive as `charts/<child>/crds/<file>`; `startsWith("crds/")` catches
+ * 0 of them and would route every one into templates/, making it deletable
+ * on uninstall.
+ */
+export declare function isCrdSource(path: string): boolean;
+export interface RoutedDocuments {
+    crds: string[];
+    templates: string[];
+}
+/** Route rendered documents by origin: `crds/`-segment sources vs the rest. */
+export declare function routeBySource(rendered: string): RoutedDocuments;
+/** Count lines that differ between two renders (symmetric, order-blind). */
+export declare function countDifferingLines(a: string, b: string): number;
+//# sourceMappingURL=render-stream.d.ts.map

package/dist/pinnability/render-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-stream.d.ts","sourceRoot":"","sources":["../../src/pinnability/render-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAKzD;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAO/D;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAUhE"}

package/dist/pinnability/values.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+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 declare function readChartMeta(chartDir: string): ChartMeta;
+export declare function readYamlFile(path: string): unknown;
+/**
+ * Helm-style deep merge: `override` wins, maps merge recursively, a `null`
+ * override deletes the key, arrays replace wholesale.
+ */
+export declare function mergeValues(base: unknown, override: unknown): unknown;
+/** Resolve a dot path against a values tree; undefined when absent. */
+export declare function valueAtPath(values: unknown, path: string[]): unknown;
+/**
+ * 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 declare function buildChartInstances(chartDir: string, suppliedValues?: unknown): {
+    instances: ChartInstance[];
+    warnings: string[];
+};
+//# sourceMappingURL=values.d.ts.map

package/dist/pinnability/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/pinnability/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAqBzD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGlD;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAYrE;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAOpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,OAAO,GACvB;IAAE,SAAS,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA8EpD"}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAY7F,eAAO,MAAM,UAAU,EAAE,aAqXxB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAiB7F,eAAO,MAAM,UAAU,EAAE,aA+ZxB,CAAC"}

package/dist/release-observe.d.ts

@@ -0,0 +1,109 @@
+import type { UnobservedEntity, UnobservedReason } from "@intentius/chant/lexicon";
+declare const defaultRunner: (command: string) => Promise<{
+    stdout: string;
+}>;
+/** Injectable command runner, so tests drive every branch without helm or a cluster. */
+export type HelmRunner = (command: string) => Promise<{
+    stdout: string;
+}>;
+export { defaultRunner as defaultHelmRunner };
+export declare const HELM_CHART_ENTITY_TYPE = "Helm::Chart";
+export declare const HELM_RELEASE_TYPE = "Helm::Release";
+/** Shell-quote one argv element, same convention as `helm-upgrade.ts`. */
+export declare function q(arg: string): string;
+/**
+ * The environment's kube context (#1488): the declared binding when present,
+ * ambient otherwise. Unresolvable config is ambient, chant's own fallback —
+ * identical to `list-artifacts.ts`.
+ */
+export declare function resolveHelmContext(environment: string): Promise<string | undefined>;
+/**
+ * Total verdict for a failed helm invocation (#1089/#1246). A missing binary
+ * and a missing/unusable kubeconfig are both `no-credentials` — the read had
+ * no usable way to reach the target. Anything else the CLI refused is
+ * `read-failed`.
+ */
+export declare function classifyHelmFailure(err: unknown): {
+    reason: UnobservedReason;
+    detail: string;
+};
+/**
+ * Kinds that are cluster-scoped, so a document without `metadata.namespace`
+ * must not inherit the release namespace. Well-known built-ins only; a
+ * cluster-scoped CRD instance this set does not name defaults to the release
+ * namespace, which affects the row's address, never its verdict.
+ */
+export declare const CLUSTER_SCOPED_KINDS: Set<string>;
+/** One rendered document a release holds, from either channel. */
+export interface ParsedReleaseResource {
+    /**
+     * Row key, following the k8s runtime-sweep convention
+     * (`<Kind>/<namespace>/<name>`, `cluster:<Kind>/<name>`) so a helm row and
+     * a k8s row for the same object spell the same identity.
+     */
+    key: string;
+    apiVersion: string;
+    kind: string;
+    name: string;
+    namespace?: string;
+    /** Which read reported it — hooks are invisible to the manifest channel. */
+    channel: "manifest" | "hooks";
+    /** chant's k8s entity type for the document's GVK (`K8s::Apps::Deployment`). */
+    entityType: string;
+    /** The document itself, minus nothing — the release's stored declaration. */
+    doc: Record<string, unknown>;
+    /** `helm.sh/hook*` annotations, for hook-channel rows. */
+    hook?: {
+        hook: string;
+        weight?: string;
+        deletePolicy?: string;
+    };
+}
+/** One declared chart resolved to a live release, with what the release holds. */
+export interface ObservedRelease {
+    entityName: string;
+    release: string;
+    namespace: string;
+    status?: string;
+    revision?: string;
+    chart?: string;
+    appVersion?: string;
+    updated?: string;
+    resources: ParsedReleaseResource[];
+}
+export interface ReleaseObservation {
+    /** Charts whose release was found and fully read. */
+    releases: ObservedRelease[];
+    /** Chart entities whose release `helm list` did not report — a real absence. */
+    absent: string[];
+    /** Chart entities that could not be read, with a total reason (#1089). */
+    unobserved: Record<string, UnobservedEntity>;
+    /** The helm command issued per chart entity (#1620). */
+    queried: Record<string, string>;
+}
+export interface ReleaseObserveOptions {
+    environment: string;
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    /** Deploy unit, `<namespace>/<release>` or `<release>` (see `describeStackStatus`). */
+    stack?: string;
+}
+/** The declared chart entities, with the release name each one deploys as. */
+export declare function chartEntities(entities: Map<string, {
+    entityType: string;
+    props: Record<string, unknown>;
+}>): Array<{
+    entityName: string;
+    release: string;
+}>;
+/** Parse one channel's multi-document YAML stream into per-resource rows. */
+export declare function parseReleaseDocuments(text: string, channel: "manifest" | "hooks", releaseNamespace: string): ParsedReleaseResource[];
+/**
+ * Resolve every declared chart to its release and read both channels.
+ * Never throws for a per-release failure; a whole-read failure (the `helm
+ * list` itself) lands every chart entity in `unobserved` with one reason.
+ */
+export declare function observeReleases(options: ReleaseObserveOptions, run?: HelmRunner): Promise<ReleaseObservation>;
+//# sourceMappingURL=release-observe.d.ts.map

package/dist/release-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-observe.d.ts","sourceRoot":"","sources":["../src/release-observe.ts"],"names":[],"mappings":"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"}

package/dist/render-diff.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 type { DeepDiffResult } from "@intentius/chant/lifecycle/deep-diff";
+import type { K8sConnector } from "@intentius/chant-lexicon-k8s/api/connect";
+import { type RenderManifest } from "./render-store.js";
+/** How one field within a changed document differs between the two renders. */
+export interface RenderFieldChange {
+    /** Path within the document's property tree (`spec.replicas`, `data.zeta`). */
+    path: string;
+    /**
+     * `changed` — both renders have the path, with different values.
+     * `added` — only the right-hand (`to`) render has it.
+     * `removed` — only the left-hand (`from`) render has it.
+     */
+    kind: "changed" | "added" | "removed";
+    /** Value on the `from` side. Absent for `added`. */
+    before?: unknown;
+    /** Value on the `to` side. Absent for `removed`. */
+    after?: unknown;
+}
+/** Identity of one document, for reporting — the same triple documents are paired on. */
+export interface RenderDiffDocumentRef {
+    kind: string;
+    namespace: string | null;
+    name: string;
+    /** The `# Source:` origin path, when the document carried one. */
+    source: string | null;
+}
+/** A document present on only one side. */
+export interface AddedOrRemovedDocument extends RenderDiffDocumentRef {
+    digest: string;
+}
+/** A document present on both sides with different content. */
+export interface ChangedDocument extends RenderDiffDocumentRef {
+    /** Per-document digest on the `from` side. */
+    beforeDigest: string;
+    /** Per-document digest on the `to` side. */
+    afterDigest: string;
+    /** Field-level differences, sorted by path. Empty only if a document parses but yields no leaves. */
+    changes: RenderFieldChange[];
+}
+export interface RenderDiffResult {
+    from: {
+        contentDigest: string;
+        chart: string;
+        releaseName: string;
+    };
+    to: {
+        contentDigest: string;
+        chart: string;
+        releaseName: string;
+    };
+    /** Present only on `to`. Sorted by kind/namespace/name. */
+    added: AddedOrRemovedDocument[];
+    /** Present only on `from`. Sorted by kind/namespace/name. */
+    removed: AddedOrRemovedDocument[];
+    /** Present on both, different bytes. Sorted by kind/namespace/name. */
+    changed: ChangedDocument[];
+    /** Present on both with equal per-document digest — reported as identities only, no field pass run. */
+    unchanged: RenderDiffDocumentRef[];
+    /**
+     * Documents each manifest's index could not identify — present in the
+     * stream (`docCount`) but absent from `documents` (unparseable, or no
+     * `kind` + `metadata.name`). Never matched, never silently dropped.
+     */
+    unindexed: {
+        from: number;
+        to: number;
+    };
+}
+export interface DiffRendersOptions {
+    /** Render store root override; defaults to `renderStoreRoot()`. */
+    root?: string;
+}
+/**
+ * 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 declare function diffRenders(from: string, to: string, options?: DiffRendersOptions): RenderDiffResult;
+/** True when the diff found no added, removed, or changed documents. */
+export declare function renderDiffIsEmpty(result: RenderDiffResult): boolean;
+export interface RenderLiveDiffOptions {
+    /** The stored render to diff against the cluster — a `contentDigest` from `chant helm renders`. */
+    contentDigest: string;
+    /** The chant environment the live read targets — resolves the k8s cluster binding (`k8s.profiles.<environment>.context`), same as any other live read. */
+    environment: string;
+    /** Render store root override (tests); defaults to `renderStoreRoot()`. */
+    root?: string;
+    owned?: boolean;
+}
+export interface RenderLiveDiffDeps {
+    /** Forwarded to the k8s reader — a test passes a fake cluster's connector. */
+    connect?: K8sConnector;
+}
+export type RenderLiveDiffOutcome = {
+    found: true;
+    manifest: RenderManifest;
+    diff: DeepDiffResult;
+}
+/** No such render in the store — refuse the diff rather than report a false clean result. */
+ | {
+    found: false;
+    contentDigest: string;
+};
+/** Row key convention shared with the release-scoped reads (#1246/#1247): `<Kind>/<namespace>/<name>`, `cluster:<Kind>/<name>`. */
+export declare function documentKey(kind: string, namespace: string | undefined, name: string): string;
+/**
+ * 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 declare function resolveDocumentNamespace(kind: string, declared: string | null, renderNamespace: string | null): string | undefined;
+/**
+ * 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 declare function diffRenderLive(options: RenderLiveDiffOptions, deps?: RenderLiveDiffDeps): Promise<RenderLiveDiffOutcome>;
+//# sourceMappingURL=render-diff.d.ts.map

package/dist/render-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-diff.d.ts","sourceRoot":"","sources":["../src/render-diff.ts"],"names":[],"mappings":"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"}