@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

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/codegen/generate-operations.ts

@@ -0,0 +1,56 @@
+/**
+ * The generated operation surface — chant #1074.
+ *
+ * `describeResources` used to reach the cluster through a hand-written
+ * `entityType → kubectl resource` map with twenty entries in it. Every one of
+ * the other ~180 generated resource types, and every CRD, fell off the end of
+ * it. The map was hand-maintained precisely because nothing derived it, and
+ * nothing derived it because the codegen pass that produces the types never
+ * emitted the addressing half.
+ *
+ * It does now. This artifact is written by the same `generate()` run that
+ * writes `lexicon-k8s.json` and `index.d.ts`, out of the same parsed results,
+ * so a resource that has a declarable class necessarily has an operation entry
+ * with the same apiVersion and kind. `operation-surface.test.ts` asserts that
+ * correspondence rather than trusting it.
+ *
+ * What it is not: an authority on what a given cluster serves. `plural` and
+ * `scope` are what the schema says; the live client confirms both against the
+ * cluster's own discovery before addressing anything, because a cluster can
+ * serve a different version of a CRD than the one chant generated from.
+ */
+
+import type { K8sParseResult } from "../spec/parse";
+import { gvkToApiVersion } from "../spec/parse";
+import { pluralizeKind, type K8sOperationDescriptor, type K8sOperationTable } from "../api/operation-surface";
+
+export type { K8sOperationDescriptor, K8sOperationTable };
+
+/** Build the operation table from the same parsed results the types come from. */
+export function buildOperationTable(results: K8sParseResult[]): K8sOperationTable {
+  const table: K8sOperationTable = {};
+  for (const result of results) {
+    if (result.isProperty) continue;
+    const entityType = result.resource.typeName;
+    // A later result for the same type wins nothing — the first parse of a
+    // preferred version is canonical, matching the registry's own precedence.
+    if (table[entityType]) continue;
+    table[entityType] = {
+      entityType,
+      apiVersion: gvkToApiVersion(result.gvk),
+      kind: result.gvk.kind,
+      plural: result.operation?.plural ?? pluralizeKind(result.gvk.kind),
+      scope: result.operation?.scope ?? "Namespaced",
+      verbs: result.operation?.verbs ?? [],
+    };
+  }
+  return table;
+}
+
+/** Serialize the table, key-sorted so regeneration produces a stable diff. */
+export function generateOperationsJSON(results: K8sParseResult[]): string {
+  const table = buildOperationTable(results);
+  const sorted: K8sOperationTable = {};
+  for (const key of Object.keys(table).sort()) sorted[key] = table[key];
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}

package/src/codegen/generate.ts

@@ -17,6 +17,7 @@ import { loadMultipleCRDs } from "../crd/loader";
 import { CRD_SOURCES } from "../crd/crd-sources";
 import { NamingStrategy, propertyTypeName, extractDefName } from "./naming";
 import { generateLexiconJSON } from "./generate-lexicon";
+import { generateOperationsJSON } from "./generate-operations";
 import { generateTypeScriptDeclarations } from "./generate-typescript";
 import {
   generateRuntimeIndex as coreGenerateRuntimeIndex,
@@ -98,6 +99,13 @@ export async function generate(opts: K8sGenerateOptions = {}): Promise<GenerateR
     generateRuntimeIndex: (results, naming) => {
       return generateRuntimeIndex(results, naming as NamingStrategy);
     },
+
+    // chant #1074 — the operation surface, out of the same results the types
+    // and the registry come out of, so the live client cannot address a kind
+    // differently from how the declarable surface names it.
+    generateExtraArtifacts: (results) => ({
+      "operations.json": generateOperationsJSON(results),
+    }),
   };
 
   return generatePipeline(config, opts);
@@ -114,6 +122,7 @@ export function writeGeneratedFiles(result: GenerateResult, baseDir: string): vo
       "index.d.ts": result.typesDTS,
       "index.ts": result.indexTS,
       "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+      ...(result.extraArtifacts ?? {}),
     },
   });
 }

package/src/config.ts

@@ -60,4 +60,21 @@ export interface K8sClusterProfile {
 export interface K8sChantConfig {
   /** Named environment → cluster bindings, keyed by environment name. */
   profiles?: Record<string, K8sClusterProfile>;
+  /**
+   * Exec credential-plugin commands chant may execute (chant #1074).
+   *
+   * On EKS, AKS and GKE, kubeconfig authentication is a subprocess:
+   * `aws eks get-token`, `kubelogin`, `gke-gcloud-auth-plugin`. Those three
+   * plus `kubectl` are allowed by default. Anything else the kubeconfig names
+   * is refused, because an exec plugin is an arbitrary binary named in a file
+   * chant did not write. Setting this **replaces** the default list.
+   *
+   * ```ts
+   * k8s: {
+   *   profiles: { prod: { context: "prod-eks" } },
+   *   execCredentialPlugins: ["aws", "my-org-oidc-helper"],
+   * } satisfies K8sChantConfig
+   * ```
+   */
+  execCredentialPlugins?: string[];
 }

package/src/crd/parser.ts

@@ -124,6 +124,14 @@ export function parseCRDSpec(spec: CRDSpec): K8sParseResult[] {
     propertyTypes: status.propertyType ? [...propertyTypes, status.propertyType] : propertyTypes,
     enums: [],
     gvk,
+    // chant #1074 — the CRD declares its own plural and scope, so the
+    // operation surface for a custom resource comes from the same document its
+    // types do, exactly as the OpenAPI `paths` supply them for built-in kinds.
+    operation: {
+      plural: spec.names.plural,
+      scope: spec.scope ?? "Namespaced",
+      verbs: ["delete", "get", "list", "patch", "post", "put", "watch"],
+    },
   });
 
   return results;

package/src/crd/types.ts

@@ -34,6 +34,13 @@ export interface CRDSource {
 export interface CRDSpec {
   /** API group (e.g. "cert-manager.io") */
   group: string;
+  /**
+   * Whether instances are namespaced. Declared by the CRD itself, so it is the
+   * authoritative source for a custom resource's scope — the equivalent of what
+   * the OpenAPI `paths` say for built-in kinds (chant #1074). Defaults to
+   * `Namespaced`, matching the API server's own default.
+   */
+  scope?: "Namespaced" | "Cluster";
   /** Name variants for the CRD */
   names: {
     kind: string;

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,
+};