@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/src/components/kubectl-apply.ts

@@ -14,10 +14,25 @@
  * (`chant:<stack>`, the prune selector) and the deploy unit the status walk
  * reads (core `components/deploy-units.ts`) — one name, both jobs, the same
  * pairing `cfn-deploy` has with its stack.
+ *
+ * ## Outputs (#3999)
+ *
+ * A manifest has no outputs of its own, so a step names the ones a
+ * dependent reads: `outputs: { host: { object: "Service/prod/web", field:
+ * "status.loadBalancer.ingress.0.hostname" } }`, each a field of an object
+ * the manifest declares. `run` returns them as `outputs` once it applied,
+ * which is what a dependent's `stackOutput()` reads, and `outputs` reads
+ * them from the cluster without applying anything. A plan knows a field the
+ * manifest sets, since the apply writes that value, and any field of an
+ * object the plan leaves as it is; every other one is known only after
+ * apply.
  */
-import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+import type { Capability, CapabilityPlan, DeployContext, PlannedOutputs } from "@intentius/chant/components/capability";
+import type { ChangeSetAttribute, ChangeSetEntry, ChangeSetHole, ChangeSetPart } from "@intentius/chant/change-set";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { releaseAttributesSuffix } from "@intentius/chant/telemetry-attribution";
 import { annotateRelease } from "../telemetry-release";
+import { diffFields, normalizeServerObject } from "../op/activities/apply-diff";
 
 /**
  * Structural mirrors of the activity module's argument/result shapes.
@@ -49,6 +64,8 @@ export interface KubectlApplyOutcome {
    * enter the prunable set. Present whenever the prune ran.
    */
   retained?: AppliedRef[];
+  /** The fields the step names as outputs (#3999), read once the apply landed. Absent when it names none. */
+  outputs?: Record<string, unknown>;
 }
 
 interface ApplierArgs {
@@ -64,6 +81,184 @@ interface ApplierArgs {
 type Applier = (args: ApplierArgs) => Promise<KubectlApplyOutcome>;
 type ManifestReader = (path: string) => Record<string, unknown>[];
 
+/** One field change, the mirror of `../op/activities/apply-diff.ts`'s `FieldChange`. */
+interface FieldChangeShape {
+  path: string;
+  before?: unknown;
+  after?: unknown;
+}
+
+/** The mirror of the activity's `PlannedObject`. */
+interface PlannedObjectShape {
+  ref: AppliedRef;
+  action: "create" | "update" | "no-op";
+  object?: Record<string, unknown>;
+  changes: FieldChangeShape[];
+  refused?: string;
+}
+
+/** What a dry run found: the mirror of the activity's `ManifestPlanResult` (#3998). */
+export interface KubectlApplyDryRun {
+  fieldManager: string;
+  stack?: string;
+  objects: PlannedObjectShape[];
+  deletes: AppliedRef[];
+  retained: AppliedRef[];
+}
+
+type Planner = (args: ApplierArgs) => Promise<KubectlApplyDryRun>;
+
+/** The mirror of the activity's `ReadLiveObjectsArgs`. */
+interface LiveReaderArgs {
+  refs: AppliedRef[];
+  environment?: string;
+  context?: string;
+}
+
+/** Reads objects as the cluster holds them, `undefined` for one that does not exist (#3999). */
+type LiveReader = (args: LiveReaderArgs) => Promise<Array<Record<string, unknown> | undefined>>;
+
+/** What `plan` hands `run` through `DeployContext.plans` (#3998). */
+export interface KubectlApplyPlanArtifact {
+  kind: "kubectl-apply-plan";
+  planDigest: string;
+  /** The documents the plan dry-ran, release attributes set. `run` applies these. */
+  documents: Record<string, unknown>[];
+}
+
+function isPlanArtifact(value: unknown): value is KubectlApplyPlanArtifact {
+  const v = value as Partial<KubectlApplyPlanArtifact> | undefined;
+  return !!v && v.kind === "kubectl-apply-plan" && typeof v.planDigest === "string" && Array.isArray(v.documents);
+}
+
+/**
+ * `run` was handed an approved plan and a fresh dry run of the same
+ * documents gives a different digest: the cluster moved since the plan, or
+ * the plan was made against another one. Nothing is applied. `planMoved` is
+ * core's mark for a moved plan (`isPlanMovedError`), so the command that
+ * applied it exits 3. `exitCode` 3 says the same to a core that reads it.
+ */
+export class KubectlApplyPlanMovedError extends Error {
+  readonly planMoved = true;
+  readonly exitCode = 3;
+  constructor(
+    public readonly member: string,
+    public readonly approved: string,
+    public readonly fresh: string,
+  ) {
+    super(
+      `kubectl-apply "${member}": the plan moved since it was approved (approved ${approved}, now ${fresh}); ` +
+        `nothing was applied. Plan and approve again.`,
+    );
+    this.name = "KubectlApplyPlanMovedError";
+  }
+}
+
+/** Kinds whose pod template change rolls their pods. */
+const ROLLING_KINDS = new Set(["Deployment", "StatefulSet", "DaemonSet", "ReplicaSet"]);
+
+/** `Deployment/prod/web`, or `ClusterRole/admin` for a cluster-scoped object. */
+function addressOf(ref: AppliedRef): string {
+  return ref.namespace ? `${ref.kind}/${ref.namespace}/${ref.name}` : `${ref.kind}/${ref.name}`;
+}
+
+const typeOf = (ref: AppliedRef): string => `${ref.apiVersion}/${ref.kind}`;
+
+/** A Secret's `data` and `stringData` values are never carried into the change set. */
+function isSensitive(ref: AppliedRef, path: string): boolean {
+  return ref.kind === "Secret" && /^(data|stringData)\b/.test(path);
+}
+
+function attribute(ref: AppliedRef, change: FieldChangeShape): ChangeSetAttribute {
+  if (isSensitive(ref, change.path)) return { path: change.path, sensitive: true };
+  return {
+    path: change.path,
+    ...("before" in change ? { before: change.before } : {}),
+    ...("after" in change ? { after: change.after } : {}),
+  };
+}
+
+/**
+ * The member's change-set part: one entry per declared object (`no-op`
+ * included, as the terraform adapter reports them) and one `delete` per
+ * object the prune would remove. A change the API server refuses as
+ * immutable is an `update` with disruption `unknown`, plus a hole that says
+ * the apply would fail.
+ */
+function changeSetPartOf(member: string, planDigest: string, dryRun: KubectlApplyDryRun): ChangeSetPart {
+  const base = { member, lexicon: "k8s", planner: "chant" as const };
+  const entries: ChangeSetEntry[] = [];
+  const holes: ChangeSetHole[] = [];
+  for (const o of dryRun.objects) {
+    const head = { ...base, address: addressOf(o.ref), type: typeOf(o.ref), name: o.ref.name };
+    if (o.refused !== undefined) {
+      entries.push({ ...head, action: "update", disruption: "unknown", attributes: [] });
+      holes.push({
+        address: head.address,
+        type: head.type,
+        reason:
+          `the API server refuses the change: ${o.refused}. The apply does not delete and recreate ` +
+          `the object, so it fails the same way until the object is deleted`,
+      });
+      continue;
+    }
+    if (o.action === "create") {
+      const declared = normalizeServerObject(o.object ?? {});
+      delete declared.apiVersion;
+      delete declared.kind;
+      entries.push({ ...head, action: "create", attributes: diffFields({}, declared).map((c) => attribute(o.ref, c)) });
+      continue;
+    }
+    if (o.action === "no-op") {
+      entries.push({ ...head, action: "no-op", attributes: [] });
+      continue;
+    }
+    const rolling = ROLLING_KINDS.has(o.ref.kind) && o.changes.some((c) => c.path.startsWith("spec.template"));
+    entries.push({
+      ...head,
+      action: "update",
+      disruption: rolling ? "rolling" : "in-place",
+      attributes: o.changes.map((c) => attribute(o.ref, c)),
+    });
+  }
+  for (const ref of dryRun.deletes) {
+    entries.push({ ...base, address: addressOf(ref), type: typeOf(ref), name: ref.name, action: "delete", disruption: "destroy", attributes: [] });
+  }
+  return { member: { ...base, status: "planned", planDigest, holes }, entries };
+}
+
+/**
+ * What a gate on this member binds: where it applies, as whom, the documents
+ * sent, and what the dry run says each does. For an object it changes, the
+ * changed paths and their new values, so a field another manager moves
+ * between plan and apply refuses the apply only when it is one chant's
+ * apply changes. Server bookkeeping never reaches it (`apply-diff.ts`).
+ */
+function dryRunDigest(
+  ctx: DeployContext,
+  member: string,
+  input: KubectlApplyInput,
+  documents: Record<string, unknown>[],
+  dryRun: KubectlApplyDryRun,
+): string {
+  return computePlanDigest("kubectl-apply-plan", {
+    env: ctx.env,
+    member,
+    context: input.context ?? null,
+    delete: input.delete ?? "never",
+    fieldManager: dryRun.fieldManager,
+    documents,
+    objects: dryRun.objects.map((o) => ({
+      address: addressOf(o.ref),
+      type: typeOf(o.ref),
+      action: o.action,
+      changes: o.changes.map((c) => ("after" in c ? { path: c.path, after: c.after } : { path: c.path, removed: true })),
+      ...(o.refused !== undefined ? { refused: o.refused } : {}),
+    })),
+    deletes: dryRun.deletes.map((r) => `${typeOf(r)}/${r.namespace ?? ""}/${r.name}`).sort(),
+  });
+}
+
 export interface KubectlApplyInput {
   /** Path to a manifest file, or a directory of them. */
   manifest: string;
@@ -83,6 +278,64 @@ export interface KubectlApplyInput {
    * candidate.
    */
   delete?: "never" | "owned-only";
+  /**
+   * The outputs the step exposes (#3999), by name: each a field of an object
+   * the manifest declares. A dependent reads them with `stackOutput()`.
+   */
+  outputs?: Record<string, KubectlApplyOutputField>;
+}
+
+/** One output of a `kubectl-apply` step (#3999). */
+export interface KubectlApplyOutputField {
+  /**
+   * The object, named as the manifest declares it: `Kind/namespace/name`, or
+   * `Kind/name` for a document with no namespace.
+   */
+  object: string;
+  /** The field's dot path in the object; a list index is a number, `status.loadBalancer.ingress.0.hostname`. */
+  field: string;
+}
+
+/** The value at a dot path, or `undefined`. */
+function fieldAt(object: unknown, path: string): unknown {
+  return path.split(".").reduce<unknown>((acc, key) => (acc !== null && typeof acc === "object" ? (acc as Record<string, unknown>)[key] : undefined), object);
+}
+
+/** The declared ref of each output's object, keyed by output name. Throws for an object the manifest does not declare. */
+function outputRefs(member: string, input: KubectlApplyInput, documents: Record<string, unknown>[]): Map<string, AppliedRef> {
+  const declared = new Map<string, AppliedRef>();
+  for (const doc of documents) {
+    const metadata = (doc.metadata ?? {}) as { name?: unknown; namespace?: unknown };
+    const ref: AppliedRef = {
+      apiVersion: String(doc.apiVersion ?? ""),
+      kind: String(doc.kind ?? ""),
+      name: String(metadata.name ?? ""),
+      ...(metadata.namespace !== undefined ? { namespace: String(metadata.namespace) } : {}),
+    };
+    declared.set(addressOf(ref), ref);
+  }
+  const out = new Map<string, AppliedRef>();
+  for (const [name, spec] of Object.entries(input.outputs ?? {})) {
+    const ref = declared.get(spec.object);
+    if (!ref) {
+      throw new Error(`kubectl-apply "${member}": output "${name}" names ${spec.object}, which ${input.manifest} does not declare (it declares ${[...declared.keys()].join(", ") || "nothing"})`);
+    }
+    out.set(name, ref);
+  }
+  return out;
+}
+
+/** Each output's field as `objects` hold it, one object per distinct ref; an output with no value is left out. */
+async function readOutputs(read: LiveReader, refs: Map<string, AppliedRef>, input: KubectlApplyInput, where: Omit<LiveReaderArgs, "refs">): Promise<Record<string, unknown>> {
+  const distinct = [...new Map([...refs.values()].map((r) => [addressOf(r), r])).values()];
+  const live = await read({ refs: distinct, ...where });
+  const byAddress = new Map(distinct.map((r, i) => [addressOf(r), live[i]]));
+  const out: Record<string, unknown> = {};
+  for (const [name, ref] of refs) {
+    const value = fieldAt(byAddress.get(addressOf(ref)), input.outputs![name]!.field);
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
 }
 
 /** Factory with an injectable applier, so tests assert the delegation without
@@ -92,32 +345,108 @@ export interface KubectlApplyInput {
 export function createKubectlApplyCapability(
   apply?: Applier,
   read?: ManifestReader,
+  dryRun?: Planner,
+  readLive?: LiveReader,
 ): Capability<KubectlApplyInput, KubectlApplyOutcome> {
+  const activities = () => import("../op/activities/kubectl");
+  const target = (ctx: DeployContext, input: KubectlApplyInput) => ({
+    environment: ctx.env,
+    ...(input.stack !== undefined ? { stack: input.stack } : {}),
+    ...(input.context !== undefined ? { context: input.context } : {}),
+    ...(input.delete !== undefined ? { deleteMode: input.delete } : {}),
+  });
+  /** Dry-run `documents` and digest the result. */
+  const dryRunOf = async (ctx: DeployContext, input: KubectlApplyInput, member: string, documents: Record<string, unknown>[]) => {
+    const planner: Planner = dryRun ?? (await activities()).planManifest;
+    const result = await planner({ manifest: input.manifest, documents, ...target(ctx, input) });
+    return { result, planDigest: dryRunDigest(ctx, member, input, documents, result) };
+  };
+  const liveReader = async (): Promise<LiveReader> => readLive ?? (await activities()).readLiveObjects;
+  const where = (ctx: DeployContext, input: KubectlApplyInput) => ({
+    environment: ctx.env,
+    ...(input.context !== undefined ? { context: input.context } : {}),
+  });
+  /** The outputs the step names, read from the cluster now. */
+  const liveOutputs = async (ctx: DeployContext, input: KubectlApplyInput, documents: Record<string, unknown>[]) =>
+    readOutputs(await liveReader(), outputRefs(input.stack ?? ctx.component, input, documents), input, where(ctx, input));
+  /**
+   * What the plan knows of each output: a field the manifest sets, and any
+   * field of an object the dry run leaves unchanged, read from the cluster.
+   */
+  const plannedOutputs = async (ctx: DeployContext, input: KubectlApplyInput, member: string, documents: Record<string, unknown>[], dry: KubectlApplyDryRun): Promise<PlannedOutputs> => {
+    const refs = outputRefs(member, input, documents);
+    const declared = new Map(documents.map((d) => [addressOf({ apiVersion: "", kind: String(d.kind ?? ""), name: String((d.metadata as { name?: unknown } | undefined)?.name ?? ""), ...((d.metadata as { namespace?: unknown } | undefined)?.namespace !== undefined ? { namespace: String((d.metadata as { namespace: unknown }).namespace) } : {}) }), d]));
+    const unchanged = new Set(dry.objects.filter((o) => o.action === "no-op").map((o) => addressOf(o.ref)));
+    const fromLive = new Map([...refs].filter(([, ref]) => unchanged.has(addressOf(ref))));
+    const live = fromLive.size > 0 ? await readOutputs(await liveReader(), fromLive, input, where(ctx, input)) : {};
+    const known: Record<string, unknown> = {};
+    const unknown: string[] = [];
+    for (const [name, ref] of refs) {
+      const set = fieldAt(declared.get(addressOf(ref)), input.outputs![name]!.field);
+      if (set !== undefined) known[name] = set;
+      else if (name in live) known[name] = live[name];
+      else unknown.push(name);
+    }
+    return { known, unknown: unknown.sort() };
+  };
   return {
     kind: "kubectl-apply",
     // A server-side apply has no native undo (the previous object state is not
     // kept by the API server), so COMP003 requires the component to acknowledge
     // the compensation gap — the same posture as s3-sync/run-migration.
     rollbackPolicy: "needs-opt-out",
+    /**
+     * Dry-run the manifest against the cluster (#3998): the documents `run`
+     * would apply, release attributes set, server-side applied with
+     * `dryRun=All` as the same field manager, each compared with its live
+     * object. The member is the step's `stack`, or the component.
+     */
+    async plan(ctx: DeployContext, input: KubectlApplyInput): Promise<CapabilityPlan> {
+      const member = input.stack ?? ctx.component;
+      const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+      const suffix = releaseAttributesSuffix(ctx.release);
+      if (suffix !== "") annotateRelease(documents, suffix);
+      const { result, planDigest } = await dryRunOf(ctx, input, member, documents);
+      const artifact: KubectlApplyPlanArtifact = { kind: "kubectl-apply-plan", planDigest, documents };
+      const outputs = input.outputs ? await plannedOutputs(ctx, input, member, documents, result) : undefined;
+      return { member, planDigest, artifact, changeSet: changeSetPartOf(member, planDigest, result), ...(outputs ? { outputs } : {}) };
+    },
+    /**
+     * The fields the step names as outputs, as the cluster holds them now
+     * (#3999). A step that names none has none; an object not made yet
+     * leaves its outputs out.
+     */
+    async outputs(ctx: DeployContext, input: KubectlApplyInput): Promise<Record<string, unknown>> {
+      if (!input.outputs || Object.keys(input.outputs).length === 0) return {};
+      const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+      return liveOutputs(ctx, input, documents);
+    },
     async run(ctx: DeployContext, input: KubectlApplyInput): Promise<KubectlApplyOutcome> {
-      const activities = apply && read ? undefined : await import("../op/activities/kubectl");
-      const applier: Applier = apply ?? activities!.applyManifest;
+      const member = input.stack ?? ctx.component;
+      const approved = ctx.plans?.[member];
+      if (isPlanArtifact(approved)) {
+        // Apply the documents the approver saw, and only while a fresh dry
+        // run of them still says what the approved one said.
+        const { planDigest } = await dryRunOf(ctx, input, member, approved.documents);
+        if (planDigest !== approved.planDigest) throw new KubectlApplyPlanMovedError(member, approved.planDigest, planDigest);
+        const applier: Applier = apply ?? (await activities()).applyManifest;
+        const outcome = await applier({ manifest: input.manifest, documents: approved.documents, ...target(ctx, input) });
+        return input.outputs ? { ...outcome, outputs: await liveOutputs(ctx, input, approved.documents) } : outcome;
+      }
+      const loaded = apply && read ? undefined : await activities();
+      const applier: Applier = apply ?? loaded!.applyManifest;
       // A release run (#3061, ws-081) sets the release attributes on the pod template of each
       // workload the build stamped, in what it applies; the committed manifest is not touched.
       const suffix = releaseAttributesSuffix(ctx.release);
       let documents: Record<string, unknown>[] | undefined;
       if (suffix !== "") {
-        documents = (read ?? activities!.readManifestDocuments)(input.manifest);
+        documents = (read ?? loaded!.readManifestDocuments)(input.manifest);
         if (annotateRelease(documents, suffix) === 0) documents = undefined;
       }
-      return applier({
-        manifest: input.manifest,
-        ...(documents ? { documents } : {}),
-        environment: ctx.env,
-        ...(input.stack !== undefined ? { stack: input.stack } : {}),
-        ...(input.context !== undefined ? { context: input.context } : {}),
-        ...(input.delete !== undefined ? { deleteMode: input.delete } : {}),
-      });
+      const outcome = await applier({ manifest: input.manifest, ...(documents ? { documents } : {}), ...target(ctx, input) });
+      if (!input.outputs) return outcome;
+      const declared = documents ?? (read ?? (await activities()).readManifestDocuments)(input.manifest);
+      return { ...outcome, outputs: await liveOutputs(ctx, input, declared) };
     },
   };
 }

package/src/deep-observe-hooks.ts

@@ -47,7 +47,7 @@
 
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
 import {
   K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS,
@@ -202,7 +202,7 @@ let cachedListMapKeys: ListMapKeyTable | undefined;
  * class of bug in #1581. A plain fs read has no module-system dependency.
  */
 export function listMapKeyTablePath(): string {
-  return join(dirname(fileURLToPath(import.meta.url)), "generated", "list-map-keys.json");
+  return join(moduleSourceDir(import.meta.url), "generated", "list-map-keys.json");
 }
 
 /**

package/src/import/roundtrip-build.test.ts

@@ -84,4 +84,50 @@ describe("k8s import round trip", () => {
     }
     expect(await roundTrip(yaml)).toEqual(loadAll(yaml));
   });
+
+  test("import names an error-severity check the generated source will fail at build (#3605)", async () => {
+    const yaml = [
+      "apiVersion: apps/v1",
+      "kind: StatefulSet",
+      "metadata:",
+      "  name: mysql",
+      "spec:",
+      "  selector:",
+      "    matchLabels:",
+      "      app: mysql",
+      "  serviceName: mysql",
+      "  template:",
+      "    metadata:",
+      "      labels:",
+      "        app: mysql",
+      "    spec:",
+      "      containers:",
+      "      - name: mysql",
+      "        image: mysql:5.7",
+      "        env:",
+      "        - name: MYSQL_ALLOW_EMPTY_PASSWORD",
+      '          value: "1"',
+    ].join("\n");
+    const imported = await importManifest(yaml);
+    try {
+      expect(imported.result.success).toBe(true);
+      const named = imported.result.warnings.filter((w) => w.startsWith("WK8005:"));
+      expect(named).toHaveLength(1);
+      expect(named[0]).toContain('"MYSQL_ALLOW_EMPTY_PASSWORD"');
+      expect(named[0]).toContain("chant build stops on this error");
+    } finally {
+      removeDir(imported.dir);
+    }
+  });
+
+  test("import names no check for a manifest that builds cleanly", async () => {
+    const imported = await importManifest(
+      ["apiVersion: v1", "kind: ConfigMap", "metadata:", "  name: settings", "data:", "  mode: fast"].join("\n"),
+    );
+    try {
+      expect(imported.result.warnings.filter((w) => /^[A-Z]+\d+: /.test(w))).toEqual([]);
+    } finally {
+      removeDir(imported.dir);
+    }
+  });
 });

package/src/lint/post-synth/crd-schema-helpers.ts

@@ -12,6 +12,7 @@
  */
 
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 import type { CrdFieldSchema } from "../../spec/parse";
 import { docsToManifests, type K8sManifest } from "./k8s-helpers";
@@ -44,7 +45,7 @@ export function getCrdSchemaRegistry(): Map<string, CrdFieldSchema> {
     // Built lazily so importing this module stays edge-safe: `createRequire`
     // throws where import.meta.url is undefined (bundled Workers), and there
     // the registry is simply empty.
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleSourceUrl(import.meta.url));
     const lexicon = require("../../generated/lexicon-k8s.json") as Record<string, LexiconEntry>;
     for (const entry of Object.values(lexicon)) {
       if (entry.kind === "resource" && entry.apiVersion && entry.gvkKind && entry.specSchema) {

package/src/lsp/completions.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/op/activities/apply-diff.ts

@@ -0,0 +1,87 @@
+/**
+ * What a server-side apply would change in one object (#3998): the live
+ * object against the result of a dry-run apply of the declared one.
+ *
+ * Both sides come from the API server, so a field the server defaults or
+ * fills in appears on both with the same value and drops out of the diff.
+ * What is left out before comparing is the bookkeeping the server writes on
+ * every request and that says nothing about the declared state: managed
+ * fields, the resource version, the uid, the creation timestamp, the
+ * generation (a dry run of a spec change bumps it) and `status`.
+ *
+ * Pure functions only, with no client import, so the capability module can
+ * share them without reaching the API-client chain (#1074).
+ */
+
+/** One field whose value the apply would change. `before` is absent on an added field, `after` on a removed one. */
+export interface FieldChange {
+  path: string;
+  before?: unknown;
+  after?: unknown;
+}
+
+/** The `metadata` keys the server writes on every request. */
+const SERVER_METADATA = ["managedFields", "resourceVersion", "uid", "creationTimestamp", "generation", "selfLink"] as const;
+
+/** A copy of `object` without the fields the server writes on every request. */
+export function normalizeServerObject(object: Record<string, unknown>): Record<string, unknown> {
+  const { status: _status, ...rest } = object;
+  const metadata = rest.metadata;
+  if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+    const copy: Record<string, unknown> = { ...(metadata as Record<string, unknown>) };
+    for (const key of SERVER_METADATA) delete copy[key];
+    rest.metadata = copy;
+  }
+  return rest;
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Deep equality over JSON values. */
+export function jsonEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const ka = Object.keys(a);
+    if (ka.length !== Object.keys(b).length) return false;
+    return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && jsonEqual(a[k], b[k]));
+  }
+  return false;
+}
+
+/** `spec.replicas`, or `metadata.labels["app.kubernetes.io/name"]` for a key that is not a plain identifier. */
+function joinPath(prefix: string, key: string): string {
+  if (/^[A-Za-z_$][\w$-]*$/.test(key)) return prefix ? `${prefix}.${key}` : key;
+  return `${prefix}[${JSON.stringify(key)}]`;
+}
+
+/**
+ * The fields that differ between `live` and `next`, both normalized. Objects
+ * are walked to their leaves; a list is compared whole and reported at its
+ * own path, since a list's items have no stable address in general.
+ */
+export function diffFields(live: Record<string, unknown>, next: Record<string, unknown>, prefix = ""): FieldChange[] {
+  const changes: FieldChange[] = [];
+  const keys = [...new Set([...Object.keys(live), ...Object.keys(next)])].sort();
+  for (const key of keys) {
+    const path = joinPath(prefix, key);
+    const hasBefore = Object.prototype.hasOwnProperty.call(live, key);
+    const hasAfter = Object.prototype.hasOwnProperty.call(next, key);
+    const before = live[key];
+    const after = next[key];
+    // An object on both sides, or added or removed whole, is walked to its
+    // leaves. An empty object added or removed has none, so it stands as itself.
+    const walkable = (has: boolean, v: unknown) => !has || isPlainObject(v);
+    if ((isPlainObject(before) || isPlainObject(after)) && walkable(hasBefore, before) && walkable(hasAfter, after)) {
+      const inner = diffFields(hasBefore ? (before as Record<string, unknown>) : {}, hasAfter ? (after as Record<string, unknown>) : {}, path);
+      if (inner.length > 0 || hasBefore === hasAfter) {
+        changes.push(...inner);
+        continue;
+      }
+    }
+    if (hasBefore && hasAfter && jsonEqual(before, after)) continue;
+    changes.push({ path, ...(hasBefore ? { before } : {}), ...(hasAfter ? { after } : {}) });
+  }
+  return changes;
+}