@intentius/chant-lexicon-k8s 0.44.13 → 0.45.0

package/src/codegen/generate-lexicon.ts

@@ -4,7 +4,7 @@
  */
 
 import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
-import type { K8sParseResult } from "../spec/parse";
+import type { K8sParseResult, CrdFieldSchema } from "../spec/parse";
 import { k8sShortName, gvkToApiVersion } from "../spec/parse";
 import type { NamingStrategy } from "./naming";
 import {
@@ -21,6 +21,12 @@ export interface K8sLexiconEntry {
   gvkKind?: string;
   deprecatedProperties?: string[];
   constraints?: Record<string, PropertyConstraints>;
+  /**
+   * Field schema of a custom resource's `spec` (chant #1372). Only CRD-derived
+   * kinds carry one; built-in kinds are typed by the `.d.ts`. Consumed by the
+   * WK8501/WK8502 post-synth checks and the MCP catalog.
+   */
+  specSchema?: CrdFieldSchema;
 }
 
 /**
@@ -56,6 +62,9 @@ export function generateLexiconJSON(
       if (propConstraints && Object.keys(propConstraints).length > 0) {
         entry.constraints = propConstraints;
       }
+      if (r?.specSchema) {
+        entry.specSchema = r.specSchema;
+      }
       return entry;
     },
     buildPropertyEntry: (resourceType, propertyType) => ({
@@ -65,5 +74,32 @@ export function generateLexiconJSON(
     }),
   });
 
-  return serializeRegistry(entries);
+  return serializeWithCompactSchemas(entries);
+}
+
+/**
+ * Pretty-print the registry the way every lexicon does, but keep each
+ * `specSchema` on one line (chant #1372). A CRD schema nests deeply — an
+ * ApplicationSet or RayCluster embeds a whole PodTemplateSpec — and two-space
+ * indentation on that tree quadruples the file for no reader's benefit.
+ * Compact, the schemas add ~0.8 MB to the registry; pretty, ~3.9 MB.
+ */
+export function serializeWithCompactSchemas(entries: Record<string, K8sLexiconEntry>): string {
+  const compact = new Map<string, string>();
+  const stripped: Record<string, unknown> = {};
+  for (const [name, entry] of Object.entries(entries)) {
+    if (!entry.specSchema) {
+      stripped[name] = entry;
+      continue;
+    }
+    const { specSchema, ...rest } = entry;
+    const token = `__chant_spec_schema_${compact.size}__`;
+    compact.set(token, JSON.stringify(specSchema));
+    stripped[name] = { ...rest, specSchema: token };
+  }
+  let out = serializeRegistry(stripped);
+  for (const [token, json] of compact) {
+    out = out.replace(`"${token}"`, json);
+  }
+  return out;
 }

package/src/codegen/snapshot.test.ts

@@ -92,4 +92,24 @@ describe("snapshot", () => {
     expect(dts).toContain("class Service");
     expect(dts).toContain("class Pod");
   });
+
+  // chant #1372 — CRD field schemas ship in the registry; built-ins do not carry one.
+  test.skipIf(!hasGenerated)("every CRD-derived resource entry carries a specSchema, built-ins none", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const crd = registry.Certificate;
+    expect(crd.resourceType).toBe("K8s::CertManager::Certificate");
+    expect(crd.specSchema.type).toBe("object");
+    expect(crd.specSchema.fields.issuerRef.fields.name.type).toBe("string");
+    expect(crd.specSchema.required).toContain("secretName");
+
+    expect(registry.Deployment.specSchema).toBeUndefined();
+    expect(registry.Certificate_Status.specSchema).toBeUndefined();
+
+    // Each schema is written on one line so the file stays reviewable; the
+    // pretty-printed form is four times the size for no reader's benefit.
+    const line = raw.split("\n").find((l) => l.includes('"specSchema": {'));
+    expect(line).toMatch(/^\s+"specSchema": \{.*\}$/);
+  });
 });

package/src/components/capability-plugin.test.ts

@@ -0,0 +1,20 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { k8sCapabilityPlugin, K8S_VERB_FAMILIES } from "./capability-plugin";
+
+describe("k8sCapabilityPlugin", () => {
+  test("satisfies the CapabilityPlugin contract", () => {
+    expect(isCapabilityPlugin(k8sCapabilityPlugin)).toBe(true);
+    expect(k8sCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("kubectl-apply");
+    expect(k8sCapabilityPlugin.families?.()).toBe(K8S_VERB_FAMILIES);
+  });
+
+  test("the plugin's version is the lexicon package's own, not a literal (#1505)", () => {
+    const { version } = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ) as { version: string };
+    expect(k8sCapabilityPlugin.version).toBe(version);
+    expect(k8sCapabilityPlugin.version).not.toBe("0.41.0");
+  });
+});

package/src/components/capability-plugin.ts

@@ -25,8 +25,11 @@ export const K8S_VERB_FAMILIES = {
 export const k8sCapabilityPlugin: CapabilityPlugin = {
   name: "k8s",
   // The lexicon package's own version (#1505) — lockstep releases bump it, so
-  // a literal here was stale one release after it was written.
-  version: ownPackageVersion(import.meta.url),
+  // a literal here was stale one release after it was written. A getter, so
+  // the package.json read happens on first access rather than at import time.
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
   capabilities(): Array<Capability<never, unknown>> {
     return [
       kubectlApplyCapability as Capability<never, unknown>,

package/src/crd/cnpg.test.ts

@@ -15,7 +15,7 @@ import { parseYAML } from "@intentius/chant/yaml";
 
 /** Serialize one declaration the way `chant build` would, and read it back. */
 function synth(logicalName: string, resource: unknown): any {
-  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]]));
+  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]])) as string;
   return parseYAML(yaml);
 }
 

package/src/crd/infisical.test.ts

@@ -13,7 +13,7 @@ import { k8sSerializer } from "../serializer";
 import { parseYAML } from "@intentius/chant/yaml";
 
 function synth(logicalName: string, resource: unknown): any {
-  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]]));
+  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]])) as string;
   return parseYAML(yaml);
 }
 

package/src/crd/parser.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { parseCRD, parseCRDSpec } from "./parser";
+import { parseCRD, parseCRDSpec, toFieldSchema } from "./parser";
 
 describe("parseCRD", () => {
   test("parses valid CRD YAML", () => {
@@ -453,3 +453,119 @@ describe("parseCRDSpec", () => {
     expect(results[0].propertyTypes.some((pt) => pt.name === "Widget_Status")).toBe(false);
   });
 });
+
+// chant #1372 — the spec field schema that ships in the lexicon JSON.
+describe("specSchema (chant #1372)", () => {
+  const microVmImage = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: microvmimages.lambda.aws.amazon.com
+spec:
+  group: lambda.aws.amazon.com
+  names:
+    kind: MicroVMImage
+    plural: microvmimages
+  scope: Namespaced
+  versions:
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              required: [source]
+              properties:
+                desiredState:
+                  type: string
+                  enum: [Active, Inactive, Deleted]
+                  description: Lifecycle state wanted for the image.
+                memorySizeMiB:
+                  type: integer
+                  minimum: 128
+                  maximum: 10240
+                autoActivate:
+                  type: boolean
+                source:
+                  type: object
+                  properties:
+                    s3Bucket:
+                      type: string
+                    s3Key:
+                      type: string
+                layers:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      arn:
+                        type: string
+                annotations:
+                  type: object
+                  additionalProperties:
+                    type: string
+                extra:
+                  type: object
+                  x-kubernetes-preserve-unknown-fields: true
+                port:
+                  x-kubernetes-int-or-string: true
+            status:
+              type: object
+              properties:
+                phase:
+                  type: string
+`;
+
+  test("is the spec's field tree — names, scalar types, enums, required — with no prose or bounds", () => {
+    const [result] = parseCRD(microVmImage);
+    expect(result.specSchema).toEqual({
+      type: "object",
+      required: ["source"],
+      fields: {
+        desiredState: { type: "string", enum: ["Active", "Inactive", "Deleted"] },
+        memorySizeMiB: { type: "integer" },
+        autoActivate: { type: "boolean" },
+        source: { type: "object", fields: { s3Bucket: { type: "string" }, s3Key: { type: "string" } } },
+        layers: { type: "array", items: { type: "object", fields: { arn: { type: "string" } } } },
+        annotations: { type: "object", open: true },
+        extra: { type: "object", open: true },
+        port: { open: true },
+      },
+    });
+    // Status never rides along — it is server-owned, not something a spec validator checks.
+    expect(JSON.stringify(result.specSchema)).not.toContain("phase");
+  });
+
+  test("absent when the CRD declares no spec schema", () => {
+    const crd = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: bars.example.com
+spec:
+  group: example.com
+  names:
+    kind: Bar
+    plural: bars
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+`;
+    const [result] = parseCRD(crd);
+    expect("specSchema" in result).toBe(false);
+  });
+
+  test("toFieldSchema infers object/array from structure when type is missing", () => {
+    expect(toFieldSchema({ properties: { a: { type: "string" } } })).toEqual({
+      type: "object",
+      fields: { a: { type: "string" } },
+    });
+    expect(toFieldSchema({ items: { type: "integer" } })).toEqual({ type: "array", items: { type: "integer" } });
+    expect(toFieldSchema({})).toEqual({});
+  });
+});

package/src/crd/parser.ts

@@ -7,7 +7,13 @@
  * with the full codegen pipeline.
  */
 
-import type { K8sParseResult, ParsedProperty, ParsedPropertyType, GroupVersionKind } from "../spec/parse";
+import type {
+  K8sParseResult,
+  ParsedProperty,
+  ParsedPropertyType,
+  GroupVersionKind,
+  CrdFieldSchema,
+} from "../spec/parse";
 import type { CRDSpec } from "./types";
 import { namespaceSegmentForGroup } from "../group-namespace";
 import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
@@ -66,6 +72,7 @@ export function parseCRDSpec(spec: CRDSpec): K8sParseResult[] {
   const properties = schema ? extractProperties(schema) : [];
   const propertyTypes = schema ? extractPropertyTypes(schema, typeName) : [];
   const status = schema ? extractStatusType(schema, typeName) : {};
+  const specSchema = schema?.properties?.spec ? toFieldSchema(schema.properties.spec) : undefined;
 
   const attributes = [
     { name: "name", tsType: "string" },
@@ -85,6 +92,10 @@ export function parseCRDSpec(spec: CRDSpec): K8sParseResult[] {
     propertyTypes: status.propertyType ? [...propertyTypes, status.propertyType] : propertyTypes,
     enums: [],
     gvk,
+    // chant #1372 — the spec's field schema, shipped in the lexicon JSON so
+    // the post-synth checks (WK8501/WK8502) can validate a custom resource
+    // the way the API server's structural schema would, before apply.
+    ...(specSchema ? { specSchema } : {}),
     // 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.
@@ -265,10 +276,12 @@ function extractStatusType(
   const statusSchema = schema.properties?.status;
   if (!statusSchema) return {};
 
-  // The `.d.ts` accessor is deliberately opaque — CRD typing lives in the
-  // lexicon JSON (the same channel `spec` uses, which is also `Record<string,
-  // unknown>` in the constructor). The rich, per-field status shape is carried
-  // by the property type below, surfaced through LSP / validation / MCP.
+  // The `.d.ts` accessor is deliberately opaque, like the constructor's
+  // `spec: Record<string, unknown>`. The writable side is typed through the
+  // lexicon JSON instead (`specSchema`, chant #1372, checked by WK8501/WK8502).
+  // Status is server-owned and never validated; the property type below only
+  // registers its name so the shape is discoverable (chant #1372 reviewed the
+  // claim that it fed LSP / validation — it did not, and does not need to).
   const attribute = { name: "status", tsType: "Record<string, unknown>" };
 
   // Opaque status (preserve-unknown or no schema) → read-only record only.
@@ -293,6 +306,59 @@ function extractStatusType(
   return { attribute, propertyType };
 }
 
+// ── Spec field schema (chant #1372) ────────────────────────────────
+
+/**
+ * Reduce an `openAPIV3Schema` node to the compact {@link CrdFieldSchema} the
+ * lexicon JSON ships. Walks the whole tree; drops descriptions, formats,
+ * defaults and numeric bounds. `allOf`/`oneOf`/`anyOf` are not modelled — a
+ * node that relies on them with no `type` of its own comes out untyped, which
+ * the validators treat as "anything goes".
+ */
+export function toFieldSchema(node: OpenAPISchema): CrdFieldSchema {
+  const out: CrdFieldSchema = {};
+
+  if (node["x-kubernetes-int-or-string"]) {
+    out.open = true;
+    return out;
+  }
+
+  const type = node.type;
+  if (type === "string" || type === "integer" || type === "number" || type === "boolean" || type === "object" || type === "array") {
+    out.type = type;
+  } else if (node.properties) {
+    out.type = "object";
+  } else if (node.items) {
+    out.type = "array";
+  }
+
+  if (node.enum && node.enum.length > 0) {
+    out.enum = node.enum.map((v) => String(v));
+  }
+
+  if (out.type === "object") {
+    if (node.properties) {
+      const fields: Record<string, CrdFieldSchema> = {};
+      for (const [name, child] of Object.entries(node.properties)) {
+        fields[name] = toFieldSchema(child);
+      }
+      out.fields = fields;
+    }
+    if (node.required && node.required.length > 0) {
+      out.required = [...node.required];
+    }
+    if (node["x-kubernetes-preserve-unknown-fields"] || node.additionalProperties || !node.properties) {
+      out.open = true;
+    }
+  } else if (out.type === "array") {
+    if (node.items) out.items = toFieldSchema(node.items);
+  } else if (node["x-kubernetes-preserve-unknown-fields"] && !out.type) {
+    out.open = true;
+  }
+
+  return out;
+}
+
 /**
  * Resolve an OpenAPI schema node to a TypeScript type string.
  */

package/src/crd/traefik.test.ts

@@ -14,7 +14,7 @@ import { k8sSerializer } from "../serializer";
 import { parseYAML } from "@intentius/chant/yaml";
 
 function synth(logicalName: string, resource: unknown): any {
-  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]]));
+  const yaml = k8sSerializer.serialize(new Map([[logicalName, resource as never]])) as string;
   return parseYAML(yaml);
 }
 

package/src/deep-observe-hooks.ts

@@ -22,14 +22,18 @@
  * 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
+ * What does *not* live here is the managed-fields ownership walk — which
+ * manager owns one specific field on one specific live object. 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.
+ * per resource and attaches it to the observation as `fieldOwners`. Since
+ * chant #1191 ownership no longer prunes anything: a foreign-owned field
+ * nobody declared is reported as `undeclared` drift, and the only static
+ * subtraction for foreign writes is `K8S_SYSTEM_METADATA_PRUNE_PATTERNS`
+ * (core's `managed-fields`), applied below.
  *
  * The *entity-type-agnostic* half of these rules — which fields every
  * Kubernetes API object carries regardless of kind, and the well-known
@@ -41,20 +45,17 @@
  * keyed by chant's own k8s entityType catalog.
  */
 
-import { createRequire } from "module";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
-import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, k8sListMapOrderKey } from "@intentius/chant/managed-fields";
+import {
+  K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS,
+  K8S_SYSTEM_METADATA_PRUNE_PATTERNS,
+  k8sListMapOrderKey,
+} from "@intentius/chant/managed-fields";
 import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 
-// This module ships as ESM (tsx strips types from src/ directly), where a bare
-// `require` is not defined — the same reason serializer.ts and the LSP modules
-// already build one. The bug only surfaced on a LIVE deep read that meets an
-// associative list (every k8s estate does: a Deployment's containers), so
-// `lifecycle diff --live` crashed with `require is not defined` on exactly the
-// estates the generated table exists for (#1441 regression, found on
-// kubemicrovm-ops).
-const require = createRequire(import.meta.url);
-
 /**
  * Kubernetes-defaulted fields, per entity type, as index-erased property
  * paths. Subtracted only where source never declared the property
@@ -184,11 +185,63 @@ type ListMapKeyTable = Record<string, string[][]>;
 
 let cachedListMapKeys: ListMapKeyTable | undefined;
 
+/**
+ * Where the generated table lives: next to this module, resolved from
+ * `import.meta.url`. This module ships as ESM (tsx strips types from src/
+ * directly), where a bare `require` is not defined — the #1441 regression
+ * crashed `lifecycle diff --live` with `require is not defined` on every
+ * estate with a Deployment, and azure's apiVersion registry hit the same
+ * 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");
+}
+
+/**
+ * Load the spec-derived table once. A missing or unreadable file degrades to
+ * an EMPTY table, which routes every list through `k8sListMapOrderKey`'s
+ * hand-written conventions — the same fallback an unlisted property already
+ * takes. The empty table is cached by the caller too, so an absent artifact
+ * costs one failed read and one warning, not one per array element
+ * (chant #1476).
+ *
+ * Degrading is the right call here, unlike azure's apiVersion registry
+ * (#1581) where a silent fallback bypasses correctness-bearing pins. Without
+ * the table, drift detection narrows back to the six hardcoded properties:
+ * less coverage, never wrong answers. The warning names the regen command so
+ * the narrowing is not silent.
+ */
+export function loadListMapKeyTable(path: string = listMapKeyTablePath()): ListMapKeyTable {
+  if (!existsSync(path)) {
+    warnMissingTable(path, "not found");
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as ListMapKeyTable;
+  } catch (err) {
+    warnMissingTable(path, `unreadable: ${err instanceof Error ? err.message : String(err)}`);
+    return {};
+  }
+}
+
+function warnMissingTable(path: string, reason: string): void {
+  console.warn(
+    `k8s: list-map-keys table ${reason} (${path}); list identity falls back to the ` +
+      "hand-written conventions in @intentius/chant/managed-fields. Run `npm run generate` " +
+      "in lexicons/k8s (dev checkout) or reinstall @intentius/chant-lexicon-k8s.",
+  );
+}
+
 function listMapKeyTable(): ListMapKeyTable {
-  cachedListMapKeys ??= require("./generated/list-map-keys.json") as ListMapKeyTable;
+  cachedListMapKeys ??= loadListMapKeyTable();
   return cachedListMapKeys;
 }
 
+/** Test hook: replace (or drop) the cached table so the next lookup reloads it. */
+export function resetListMapKeyTableCache(table?: ListMapKeyTable): void {
+  cachedListMapKeys = table;
+}
+
 /** Last dotted segment of an index-erased path: `spec.template.spec.containers` → `containers`. */
 function lastSegment(pattern: string): string {
   const at = pattern.lastIndexOf(".");
@@ -259,6 +312,15 @@ export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
 
     if (node.side !== "live" || node.counterpart !== "absent") return false;
 
+    // What Kubernetes' own controllers stamp on every object of a kind
+    // (rollout counters, selector hashes, client-side-apply bookkeeping) is
+    // not drift. This is the static allowlist that stands in for the
+    // managed-fields prune since #1191: any *other* foreign-owned field
+    // nobody declared — a `kubectl label` from the console — now reaches the
+    // diff and reports as `undeclared`, with the accepted baseline as the
+    // valve for the ones an estate has decided to live with.
+    if (K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has(node.pattern)) return true;
+
     // chant's own ownership marker is not drift (see the sets' docs).
     if (K8S_OWNERSHIP_LABEL_PATTERNS.has(node.pattern)) return true;
     if (node.pattern === K8S_MANAGED_BY_LABEL_PATTERN && node.value === OWNERSHIP_MANAGED_BY_VALUE) return true;