@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -71,14 +71,14 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.31.0"
+    "@intentius/chant-k8s-client": "^0.32.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.31.0",
+    "@intentius/chant": "^0.32.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/classify.ts

@@ -96,6 +96,19 @@ export function classifyApiFailure(err: unknown): K8sReadOutcome {
   }
 }
 
+/**
+ * The cluster's own discovery reports no such kind at all — distinct from a
+ * kind that exists but currently has zero live instances. `classifyApiFailure`
+ * folds both into `absent` for the declared-entity read path, where "no
+ * instance can exist" is exactly the signal a `create` needs. `chant kube get`
+ * (chant #1079) needs the finer distinction: an ad hoc `chant kube get
+ * widgets` against a kind the cluster has never heard of should say so, not
+ * print "No resources found." as if `widgets` were a real, empty kind.
+ */
+export function isUnknownResource(err: unknown): boolean {
+  return shapeOf(err).name === NAMES.unknownResource;
+}
+
 /**
  * Whether a failure kills the whole observation rather than one entity. A
  * refused binding, a missing client package and a rejected credential plugin

package/src/api/owner-chain.test.ts

@@ -0,0 +1,171 @@
+import { describe, test, expect, vi } from "vitest";
+import { resolveK8sOwnerChain } from "./owner-chain";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+
+function pod(uid: string, ownerRefs?: Array<Record<string, unknown>>): K8sObject {
+  return {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { name: "p", namespace: "prod", uid, ...(ownerRefs ? { ownerReferences: ownerRefs } : {}) },
+  };
+}
+
+function ownerRef(kind: string, name: string, uid: string, controller = true): Record<string, unknown> {
+  return { apiVersion: "apps/v1", kind, name, uid, controller };
+}
+
+describe("resolveK8sOwnerChain (#1077)", () => {
+  test("no ownerReferences at all → unowned", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const result = await resolveK8sOwnerChain(pod("pod-uid"), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unowned" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("owner uid matches a declared entity directly → declared, no extra reads", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("Deployment", "web", "deploy-uid")]), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("Pod → ReplicaSet (undeclared, read live) → Deployment (declared) resolves through the intermediate hop", async () => {
+    const replicaSet: K8sObject = {
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      metadata: {
+        name: "web-7d9f8c9c8",
+        namespace: "prod",
+        uid: "rs-uid",
+        ownerReferences: [ownerRef("Deployment", "web", "deploy-uid")],
+      },
+    };
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(replicaSet) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "web-7d9f8c9c8", "rs-uid")]), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+    expect(reader.readIfPresent).toHaveBeenCalledTimes(1);
+    expect(reader.readIfPresent).toHaveBeenCalledWith({
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      name: "web-7d9f8c9c8",
+      namespace: "prod",
+    });
+  });
+
+  test("chain resolves fully to a live, undeclared root → foreign", async () => {
+    const replicaSet: K8sObject = {
+      apiVersion: "apps/v1",
+      kind: "ReplicaSet",
+      metadata: { name: "other-rs", namespace: "prod", uid: "rs-uid" }, // no further owner
+    };
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(replicaSet) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "other-rs", "rs-uid")]), {
+      declaredByUid: new Map(), // nothing declared at all
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "foreign" });
+  });
+
+  test("an owner read that 404s (readIfPresent → undefined) is conservative unknown, not foreign", async () => {
+    const reader = { readIfPresent: vi.fn().mockResolvedValue(undefined) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "gone-rs", "rs-uid")]), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("an owner read that throws (RBAC denial, transport error) is conservative unknown", async () => {
+    const reader = { readIfPresent: vi.fn().mockRejectedValue(new Error("Forbidden")) };
+    const result = await resolveK8sOwnerChain(pod("pod-uid", [ownerRef("ReplicaSet", "denied-rs", "rs-uid")]), {
+      declaredByUid: new Map(),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("a cycle (A owns B, B owns A) terminates and classifies unknown rather than looping forever", async () => {
+    const objA: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "a", namespace: "prod", uid: "a-uid", ownerReferences: [ownerRef("Widget", "b", "b-uid")] },
+    };
+    const objB: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "b", namespace: "prod", uid: "b-uid", ownerReferences: [ownerRef("Widget", "a", "a-uid")] },
+    };
+    const reader = {
+      readIfPresent: vi.fn(async ({ name }: { name: string }) => (name === "a" ? objA : objB)),
+    };
+    const start: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "start", namespace: "prod", uid: "start-uid", ownerReferences: [ownerRef("Widget", "a", "a-uid")] },
+    };
+    const result = await resolveK8sOwnerChain(start, { declaredByUid: new Map(), reader, namespace: "prod" });
+    expect(result).toEqual({ root: "unknown" });
+  });
+
+  test("respects a custom maxDepth, fetching no more than maxDepth + 1 objects", async () => {
+    // A chain 5 hops deep, but bounded to 2 — never reaches the declared root.
+    const objects: Record<string, K8sObject> = {};
+    for (let i = 0; i < 5; i++) {
+      objects[`n${i}`] = {
+        apiVersion: "v1",
+        kind: "Widget",
+        metadata: { name: `n${i}`, namespace: "prod", uid: `uid-${i}`, ownerReferences: [ownerRef("Widget", `n${i + 1}`, `uid-${i + 1}`)] },
+      };
+    }
+    const reader = {
+      readIfPresent: vi.fn(async ({ name }: { name: string }) => objects[name]),
+    };
+    const start: K8sObject = {
+      apiVersion: "v1",
+      kind: "Widget",
+      metadata: { name: "start", namespace: "prod", uid: "start-uid", ownerReferences: [ownerRef("Widget", "n0", "uid-0")] },
+    };
+    const result = await resolveK8sOwnerChain(start, {
+      declaredByUid: new Map([["uid-4", "deep-entity"]]), // reachable, but past the bound
+      reader,
+      namespace: "prod",
+      maxDepth: 2,
+    });
+    expect(result).toEqual({ root: "unknown" });
+    expect(reader.readIfPresent.mock.calls.length).toBeLessThanOrEqual(3); // maxDepth + 1
+  });
+
+  test("a starting object without a uid cannot be classified — unknown", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const noUid: K8sObject = { apiVersion: "v1", kind: "Pod", metadata: { name: "p", namespace: "prod" } };
+    const result = await resolveK8sOwnerChain(noUid, { declaredByUid: new Map(), reader, namespace: "prod" });
+    expect(result).toEqual({ root: "unknown" });
+    expect(reader.readIfPresent).not.toHaveBeenCalled();
+  });
+
+  test("picks the controller:true owner reference when several are present", async () => {
+    const reader = { readIfPresent: vi.fn() };
+    const refs = [ownerRef("OtherOwner", "shared", "shared-uid", false), ownerRef("Deployment", "web", "deploy-uid", true)];
+    const result = await resolveK8sOwnerChain(pod("pod-uid", refs), {
+      declaredByUid: new Map([["deploy-uid", "web"]]),
+      reader,
+      namespace: "prod",
+    });
+    expect(result).toEqual({ root: "declared", entity: "web" });
+  });
+});

package/src/api/owner-chain.ts

@@ -0,0 +1,144 @@
+/**
+ * Resolving a live Kubernetes object's `ownerReferences` chain up to a
+ * declared, chant-observed entity (chant #1077).
+ *
+ * There is no server-side "who ultimately owns this object" query — Kubernetes'
+ * own garbage collector does not have one either; it walks the same chain one
+ * hop at a time, reading each intermediate owner. A Pod's `ownerReferences`
+ * names its ReplicaSet, which chant never declared; the ReplicaSet's own
+ * `ownerReferences` names the Deployment, which is declared. Reaching that
+ * declared entity takes reading the ReplicaSet in between.
+ *
+ * This module's only job is assembling that chain — fetching each hop through
+ * the typed client, bounded and cycle-guarded so a corrupt or adversarial
+ * chain cannot hang an observation. The bounded/cycle-safe *interpretation* of
+ * the assembled chain (declared / unowned / foreign / unknown) is core's
+ * `classifyOwnerChain` (`@intentius/chant/owner-chain`) — the issue's own
+ * division of labor: core owns the category, the lexicon supplies the chain.
+ */
+
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import {
+  classifyOwnerChain,
+  DEFAULT_MAX_OWNER_CHAIN_DEPTH,
+  type OwnerChainNode,
+  type OwnerChainVerdict,
+} from "@intentius/chant/owner-chain";
+
+interface RawOwnerRef {
+  apiVersion?: string;
+  kind?: string;
+  name?: string;
+  uid?: string;
+  controller?: boolean;
+}
+
+function ownerRefs(obj: K8sObject): RawOwnerRef[] {
+  const refs = obj.metadata?.ownerReferences;
+  return Array.isArray(refs) ? (refs as RawOwnerRef[]) : [];
+}
+
+/**
+ * The reference Kubernetes' own garbage collector treats as the controlling
+ * parent: the entry with `controller: true`, else the first. An object with
+ * several owner references (rare — usually a shared, non-controller owner
+ * alongside the controlling one) is walked through its controller, matching
+ * what actually recreates the object were it deleted.
+ */
+function controllingRef(obj: K8sObject): RawOwnerRef | undefined {
+  const refs = ownerRefs(obj);
+  return refs.find((r) => r.controller === true) ?? refs[0];
+}
+
+/** The client surface this module needs — a single object read, addressed by
+ * an owner reference's own coordinates. */
+export type OwnerChainReader = Pick<K8sClient, "readIfPresent">;
+
+export interface ResolveOwnerChainOptions {
+  /** uid → declared chant entity name, from this observation's own resolved entities. */
+  declaredByUid: ReadonlyMap<string, string>;
+  /** Reads each intermediate owner. */
+  reader: OwnerChainReader;
+  /**
+   * Namespace the starting object lives in. Owner references are same-namespace
+   * only — a namespaced object cannot be owned by an object in another
+   * namespace, the same rule Kubernetes' own garbage collector enforces —so
+   * every hop is read in this namespace.
+   */
+  namespace: string | undefined;
+  maxDepth?: number;
+}
+
+/**
+ * Walk `obj`'s owner-reference chain up to a declared entity, a foreign root,
+ * or a bound (#1077). Fetches at most `maxDepth + 1` objects (the starting
+ * object plus up to `maxDepth` ancestors) — the same bound `classifyOwnerChain`
+ * enforces when interpreting the result, so nothing is fetched that the
+ * interpretation would not have used anyway.
+ */
+export async function resolveK8sOwnerChain(
+  obj: K8sObject,
+  options: ResolveOwnerChainOptions,
+): Promise<OwnerChainVerdict> {
+  const startUid = obj.metadata?.uid;
+  if (!startUid) return { root: "unknown" };
+
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_OWNER_CHAIN_DEPTH;
+  const nodes = new Map<string, OwnerChainNode>();
+  const visited = new Set<string>();
+
+  let uid: string | undefined = startUid;
+  let object: K8sObject | undefined = obj;
+
+  for (let depth = 0; uid !== undefined && depth <= maxDepth; depth++) {
+    if (visited.has(uid)) break; // cycle — classifyOwnerChain reads it off `nodes`
+    visited.add(uid);
+
+    const declaredEntity = options.declaredByUid.get(uid);
+    if (declaredEntity) {
+      nodes.set(uid, { declaredEntity });
+      break;
+    }
+    if (!object) {
+      nodes.set(uid, { ownerUnreadable: true });
+      break;
+    }
+
+    const ref = controllingRef(object);
+    if (!ref?.uid || !ref.kind || !ref.apiVersion || !ref.name) {
+      nodes.set(uid, {}); // no further owner — a real, live root
+      break;
+    }
+    nodes.set(uid, { ownerId: ref.uid });
+
+    if (visited.has(ref.uid)) {
+      // About to cycle back to an already-visited node — let the loop's own
+      // check classify it next iteration rather than issuing a wasted read.
+      uid = ref.uid;
+      continue;
+    }
+    if (options.declaredByUid.has(ref.uid)) {
+      // Already known to be a declared entity from this observation's own
+      // resolved set — no need to read it, the next iteration resolves it
+      // from `declaredByUid` directly.
+      uid = ref.uid;
+      object = undefined;
+      continue;
+    }
+
+    try {
+      object = await options.reader.readIfPresent({
+        apiVersion: ref.apiVersion,
+        kind: ref.kind,
+        name: ref.name,
+        namespace: options.namespace,
+      });
+    } catch {
+      object = undefined;
+    }
+    if (!object) nodes.set(ref.uid, { ownerUnreadable: true });
+    uid = ref.uid;
+  }
+
+  return classifyOwnerChain(startUid, nodes, maxDepth);
+}

package/src/api/sweep-types.ts

@@ -0,0 +1,36 @@
+/**
+ * The kinds chant sweeps when nothing narrows the question.
+ *
+ * A *product* decision — what a bare `chant import` should pull back, and
+ * (chant #1075) which kinds an ownership-scoped prune has to look at to notice
+ * that a whole kind was removed from source. Not an addressing limit: since
+ * chant #1074 removed `KUBECTL_RESOURCE`, a `--selector type=<entity type>`
+ * import can name any of the ~180 types the generated operation surface
+ * carries, CRDs included.
+ *
+ * It lives in its own module, with no imports of its own, because both
+ * consumers reach it from different directions — `../export-resources.ts`
+ * pulls in the whole import parser, and a Temporal worker loading the apply
+ * activity should not.
+ */
+export const DEFAULT_IMPORT_TYPES: readonly string[] = [
+  "K8s::Apps::Deployment",
+  "K8s::Apps::StatefulSet",
+  "K8s::Apps::DaemonSet",
+  "K8s::Apps::ReplicaSet",
+  "K8s::Core::Service",
+  "K8s::Core::ConfigMap",
+  "K8s::Core::Secret",
+  "K8s::Core::Namespace",
+  "K8s::Core::Pod",
+  "K8s::Core::PersistentVolumeClaim",
+  "K8s::Core::ServiceAccount",
+  "K8s::Batch::Job",
+  "K8s::Batch::CronJob",
+  "K8s::Networking::Ingress",
+  "K8s::Networking::NetworkPolicy",
+  "K8s::Rbac::Role",
+  "K8s::Rbac::RoleBinding",
+  "K8s::Rbac::ClusterRole",
+  "K8s::Rbac::ClusterRoleBinding",
+];

package/src/deep-observe-hooks.ts

@@ -0,0 +1,125 @@
+/**
+ * The k8s lexicon's *static* deep-observation noise rules (#1076, epic #1073).
+ *
+ * Split out from `./deep-observe.ts` for one reason: this file must be safe
+ * to import from `plugin.ts` at module load time, because
+ * `LexiconPlugin.deepNormalizationHooks` is plain data core reads to
+ * normalize the *declared* tree — the half of the contract that runs whether
+ * or not a cluster is ever touched (`lifecycle diff` without `--live`,
+ * `chant build`, tests that only exercise normalization). `./deep-observe.ts`
+ * itself imports `@intentius/chant-k8s-client` for the live read, and chant
+ * #1074 made that package's reachability from the build path a structural
+ * property (`examples/k8s-client-boundary.test.ts`) rather than a lint rule —
+ * so nothing this file exports may pull that package in, directly or
+ * transitively. It imports nothing but the core contract's own types.
+ *
+ * What lives here is deliberately the *entityType-keyed, resource-agnostic*
+ * half of the rules: which fields the API server always populates regardless
+ * of what a manager wrote (`status`, `metadata.uid`, …), which fields
+ * Kubernetes defaults when a manifest is silent about them, and which arrays
+ * are sets addressed by a well-known identity (containers by name, ports by
+ * containerPort+protocol). None of that needs a live object in hand.
+ *
+ * What does *not* live here is the managed-fields prune — whether one
+ * specific field on one specific live object is chant-owned, foreign-owned,
+ * or contested. That is inherently per-object (it depends on *that* object's
+ * `metadata.managedFields`, which the declared tree never carries and which
+ * differs between two Deployments of the same type), so it cannot be
+ * expressed as a fixed rule keyed only by entity type and path — the shape
+ * every other hook in this file takes. `./deep-observe.ts` computes it once
+ * per resource and layers it on top of the rules below.
+ *
+ * The *entity-type-agnostic* half of these rules — which fields every
+ * Kubernetes API object carries regardless of kind, and the well-known
+ * list-map-key ordering conventions (containers/env/volumes/ports) — lives in
+ * `@intentius/chant/managed-fields` (chant #1087), because a GCP Config
+ * Connector custom resource is a Kubernetes object too and needs the exact
+ * same rules without depending on this lexicon's package. What stays here is
+ * only what's genuinely k8s-*lexicon*-specific: {@link K8S_SERVICE_DEFAULTS},
+ * keyed by chant's own k8s entityType catalog.
+ */
+
+import type { DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
+import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, k8sListMapOrderKey } from "@intentius/chant/managed-fields";
+
+/**
+ * Kubernetes-defaulted fields, per entity type, as index-erased property
+ * paths. Subtracted only where source never declared the property
+ * (`side === "live" && counterpart === "absent"`) — cdk-real-drift's default
+ * subtraction, same convention as AWS/Azure/Temporal's tables.
+ *
+ * Sparse and evidence-based rather than derived from the generated schema:
+ * the k8s OpenAPI spec this lexicon's codegen consumes
+ * (`lexicons/k8s/src/spec/parse.ts`) does not carry a `default` value for
+ * these fields the way ARM's schema sometimes does, so "per discovery" is not
+ * actually expressible today. Widening this table is additive and needs no
+ * contract change.
+ *
+ * `spec.strategy` is listed whole, not as `spec.strategy.type`, for the same
+ * reason Temporal's `TEMPORAL_SCHEDULE_DEFAULTS` lists `state` whole: pruning
+ * only the leaf would still recurse into the object, and a nested default the
+ * table does not separately name (`rollingUpdate.maxSurge`/`maxUnavailable`,
+ * both `"25%"` when `spec.strategy` is omitted entirely) would leave behind an
+ * empty `strategy: {}` — a value distinct from no `strategy` key at all, and
+ * itself a spurious "undeclared" finding. Matching the whole node first, before
+ * its children are ever visited, drops the wrapper outright when every field
+ * under it is exactly at its default.
+ */
+export const K8S_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
+  "K8s::Apps::Deployment": {
+    "spec.strategy": { type: "RollingUpdate", rollingUpdate: { maxSurge: "25%", maxUnavailable: "25%" } },
+    "spec.revisionHistoryLimit": 10,
+    "spec.progressDeadlineSeconds": 600,
+    "spec.template.spec.dnsPolicy": "ClusterFirst",
+    "spec.template.spec.restartPolicy": "Always",
+    "spec.template.spec.terminationGracePeriodSeconds": 30,
+    "spec.template.spec.schedulerName": "default-scheduler",
+  },
+  "K8s::Core::Service": {
+    "spec.sessionAffinity": "None",
+    "spec.type": "ClusterIP",
+  },
+};
+
+/** Stable JSON with sorted keys — the fallback ordering key for a set-like array without a natural identity field. */
+function canonicalJson(value: unknown): string {
+  return (
+    JSON.stringify(value, (_k, v: unknown) =>
+      v && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v,
+    ) ?? ""
+  );
+}
+
+/**
+ * The k8s lexicon's static noise rules: the generic Kubernetes object
+ * envelope (unconditional, by pattern, `@intentius/chant/managed-fields`) and
+ * Kubernetes-defaulted fields (gated on `counterpart === "absent"`), plus the
+ * array orderings the acceptance criteria name — `x-kubernetes-patch-merge-
+ * key`/`list-map-keys` conventions the generated surface does not currently
+ * carry (see the module doc), so these are the "else named-by-name
+ * conventions" the issue calls for: containers by `name`, `env` by `name`,
+ * `volumes` by `name`, container/service `ports` by `containerPort`/`port` +
+ * `protocol` — the same conventions `@intentius/chant/managed-fields`'s
+ * `k8sListMapOrderKey` implements, reused verbatim.
+ *
+ * This is the object `k8sPlugin.deepNormalizationHooks` is. It is also what
+ * `./deep-observe.ts` layers its per-resource managed-fields prune on top of,
+ * so the two normalization passes (the reader's own, and core's later
+ * re-normalization of both the declared and the already-normalized live tree
+ * — see `packages/core/src/lifecycle/deep-observe.ts`) apply the identical
+ * entityType-keyed rules either way.
+ */
+export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
+  prune(node: DeepNode): boolean {
+    if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern)) return true;
+
+    if (node.side !== "live" || node.counterpart !== "absent") return false;
+    const defaults = K8S_SERVICE_DEFAULTS[node.entityType];
+    if (!defaults || !Object.prototype.hasOwnProperty.call(defaults, node.pattern)) return false;
+    return canonicalJson(defaults[node.pattern]) === canonicalJson(node.value);
+  },
+
+  orderKey: k8sListMapOrderKey,
+};