@intentius/chant-lexicon-k8s 0.38.0 → 0.41.0

package/src/generated/list-map-keys.json

@@ -0,0 +1,166 @@
+{
+  "addresses": [
+    [
+      "type"
+    ]
+  ],
+  "allocatedResourcesStatus": [
+    [
+      "name"
+    ]
+  ],
+  "claims": [
+    [
+      "name"
+    ]
+  ],
+  "conditions": [
+    [
+      "type"
+    ]
+  ],
+  "containers": [
+    [
+      "name"
+    ]
+  ],
+  "devices": [
+    [
+      "device",
+      "driver",
+      "pool",
+      "shareID"
+    ]
+  ],
+  "drivers": [
+    [
+      "name"
+    ]
+  ],
+  "env": [
+    [
+      "name"
+    ]
+  ],
+  "ephemeralContainers": [
+    [
+      "name"
+    ]
+  ],
+  "hostAliases": [
+    [
+      "ip"
+    ]
+  ],
+  "imagePullSecrets": [
+    [
+      "name"
+    ]
+  ],
+  "initContainers": [
+    [
+      "name"
+    ]
+  ],
+  "matchConditions": [
+    [
+      "name"
+    ]
+  ],
+  "ownerReferences": [
+    [
+      "uid"
+    ]
+  ],
+  "podGroupTemplates": [
+    [
+      "name"
+    ]
+  ],
+  "podIPs": [
+    [
+      "ip"
+    ]
+  ],
+  "ports": [
+    [
+      "containerPort",
+      "protocol"
+    ],
+    [
+      "port",
+      "protocol"
+    ]
+  ],
+  "reservedFor": [
+    [
+      "uid"
+    ]
+  ],
+  "resourceClaimStatuses": [
+    [
+      "name"
+    ]
+  ],
+  "resourceClaims": [
+    [
+      "name"
+    ]
+  ],
+  "resources": [
+    [
+      "resourceID"
+    ]
+  ],
+  "schedulingGates": [
+    [
+      "name"
+    ]
+  ],
+  "secrets": [
+    [
+      "name"
+    ]
+  ],
+  "storageVersions": [
+    [
+      "apiServerID"
+    ]
+  ],
+  "topologySpreadConstraints": [
+    [
+      "topologyKey",
+      "whenUnsatisfiable"
+    ]
+  ],
+  "variables": [
+    [
+      "name"
+    ]
+  ],
+  "volumeDevices": [
+    [
+      "devicePath"
+    ]
+  ],
+  "volumeMounts": [
+    [
+      "mountPath"
+    ]
+  ],
+  "volumes": [
+    [
+      "name"
+    ]
+  ],
+  "webhooks": [
+    [
+      "name"
+    ]
+  ],
+  "x-kubernetes-validations": [
+    [
+      "rule"
+    ]
+  ]
+}

package/src/list-map-order-key.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect } from "vitest";
+import { schemaListMapOrderKey } from "./deep-observe-hooks";
+import { k8sListMapOrderKey } from "@intentius/chant/managed-fields";
+import type { DeepArrayElement } from "@intentius/chant/lexicon";
+
+/**
+ * chant #1441 — list elements are identified by the key the SPEC declares,
+ * with the hand-written conventions kept as fallback.
+ *
+ * The behavioural claim under test: two observations of the same object whose
+ * associative lists arrive in different orders must canonicalize to the same
+ * sequence, so ordering alone is never reported as drift.
+ */
+
+function el(pattern: string, element: unknown, index = 0): DeepArrayElement {
+  return { entityType: "K8s::Apps::Deployment", pattern, path: pattern, element, index, side: "live" };
+}
+
+/** Sort a list the way core's normalization does, using the hook's key. */
+function canonicalOrder(pattern: string, elements: unknown[]): unknown[] {
+  return elements
+    .map((element, index) => ({ element, key: schemaListMapOrderKey(el(pattern, element, index)) }))
+    .sort((a, b) => (a.key ?? "").localeCompare(b.key ?? ""))
+    .map((e) => e.element);
+}
+
+describe("conditions — the case the hardcoded table missed", () => {
+  const ready = { type: "Ready", status: "True" };
+  const progressing = { type: "Progressing", status: "True" };
+
+  test("is identified by type", () => {
+    expect(schemaListMapOrderKey(el("status.conditions", ready))).toBe("Ready");
+  });
+
+  test("was NOT identified before this change", () => {
+    // Guards the premise: without the spec-derived table, `conditions` fell
+    // through to `undefined`, which leaves the array order alone — so two
+    // orderings compared positionally and read as drift.
+    expect(k8sListMapOrderKey(el("status.conditions", ready))).toBeUndefined();
+  });
+
+  test("two orderings of the same conditions canonicalize identically", () => {
+    expect(canonicalOrder("status.conditions", [ready, progressing])).toEqual(
+      canonicalOrder("status.conditions", [progressing, ready]),
+    );
+  });
+});
+
+describe("ports — one name, two key shapes", () => {
+  test("a container port is keyed by containerPort and protocol", () => {
+    // Byte-identical to what the hardcoded implementation produced, because
+    // this string is also the element's address in drift output.
+    const element = { containerPort: 8080, protocol: "TCP" };
+    expect(schemaListMapOrderKey(el("spec.template.spec.containers.ports", element))).toBe("08080/TCP");
+    expect(schemaListMapOrderKey(el("spec.template.spec.containers.ports", element))).toBe(
+      k8sListMapOrderKey(el("spec.template.spec.containers.ports", element)),
+    );
+  });
+
+  test("a Service port is keyed by port and protocol", () => {
+    expect(schemaListMapOrderKey(el("spec.ports", { port: 443, protocol: "TCP" }))).toBe("00443/TCP");
+  });
+
+  test("numeric key fields order numerically, not lexicographically", () => {
+    const ordered = canonicalOrder("spec.ports", [
+      { port: 443, protocol: "TCP" },
+      { port: 80, protocol: "TCP" },
+    ]);
+    expect(ordered).toEqual([
+      { port: 80, protocol: "TCP" },
+      { port: 443, protocol: "TCP" },
+    ]);
+  });
+});
+
+describe("fallback", () => {
+  test("a list the spec does not annotate still gets the hand-written key", () => {
+    // `containers` is in both the generated table and the hardcoded one; the
+    // point is that removing an element's spec-declared fields does not strand
+    // it — it lands on the by-name convention.
+    const key = schemaListMapOrderKey(el("spec.template.spec.containers", { name: "app", image: "nginx" }));
+    expect(key).toBeDefined();
+  });
+
+  test("an unknown list is left unordered, exactly as before", () => {
+    expect(schemaListMapOrderKey(el("spec.somethingUnknown", { a: 1 }))).toBeUndefined();
+  });
+
+  test("a non-object element is left to the fallback rather than crashing", () => {
+    expect(() => schemaListMapOrderKey(el("spec.template.spec.containers", "not-an-object"))).not.toThrow();
+  });
+
+  test("an element missing its declared key fields falls through", () => {
+    // A conditions entry with no `type` cannot be identified by the spec key.
+    // It must not produce `type=undefined`, which would collide across
+    // elements and silently merge distinct entries.
+    const key = schemaListMapOrderKey(el("status.conditions", { status: "True" }));
+    expect(key ?? "").not.toContain("undefined");
+  });
+});
+
+describe("compatibility with the hardcoded table", () => {
+  // The order key is the element's address in drift output, so every property
+  // the hand-written table already covered must keep producing the identical
+  // string. A change here silently rewrites existing drift paths.
+  const cases: Array<[string, unknown]> = [
+    ["spec.template.spec.containers", { name: "app", image: "nginx" }],
+    ["spec.template.spec.initContainers", { name: "init" }],
+    ["spec.template.spec.ephemeralContainers", { name: "debug" }],
+    ["spec.template.spec.containers.env", { name: "PORT", value: "8080" }],
+    ["spec.template.spec.volumes", { name: "data" }],
+    ["spec.template.spec.containers.ports", { containerPort: 80, protocol: "TCP" }],
+    ["spec.ports", { port: 443, protocol: "TCP" }],
+  ];
+
+  test.each(cases)("%s produces the same key as before", (pattern, element) => {
+    expect(schemaListMapOrderKey(el(pattern, element))).toBe(k8sListMapOrderKey(el(pattern, element)));
+  });
+});

package/src/plugin.ts

@@ -27,10 +27,12 @@ import { K8sParser } from "./import/parser";
 import { K8sGenerator } from "./import/generator";
 import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
 import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { k8sConfigSchema } from "./config-schema";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
   ownershipChannel: { keys: LABEL_OWNERSHIP_KEYS, reads: ["describeResources", "observeResourcesDeep", "exportResources"] },
+  configSchema: k8sConfigSchema,
   auditCatalog: () => k8sAuditCatalog,
   serializer: k8sSerializer,
   // Self-upgrade: where the pinned Kubernetes schema version lives + its upstream (#685).

package/src/spec/parse.test.ts

@@ -4,6 +4,7 @@ import {
   gvkToApiVersion,
   k8sShortName,
   k8sServiceName,
+  specListMapKeyPairs,
 } from "./parse";
 
 describe("gvkToTypeName", () => {
@@ -100,3 +101,44 @@ describe("k8sServiceName", () => {
     expect(typeof name).toBe("string");
   });
 });
+
+/**
+ * chant #1441 — the merge semantics the API server publishes, read off every
+ * definition rather than only the ones chant emits a type for.
+ */
+describe("specListMapKeyPairs", () => {
+  const spec = JSON.stringify({
+    definitions: {
+      "io.k8s.api.core.v1.PodSpec": {
+        properties: {
+          containers: { type: "array", "x-kubernetes-list-type": "map", "x-kubernetes-list-map-keys": ["name"] },
+          // atomic and set lists carry no identity key
+          tolerations: { type: "array", "x-kubernetes-list-type": "atomic" },
+          finalizers: { type: "array", "x-kubernetes-list-type": "set" },
+          nodeName: { type: "string" },
+        },
+      },
+      "io.k8s.api.core.v1.ServiceSpec": {
+        properties: {
+          ports: { type: "array", "x-kubernetes-list-type": "map", "x-kubernetes-list-map-keys": ["port", "protocol"] },
+        },
+      },
+      "io.k8s.api.core.v1.NoProperties": {},
+    },
+  });
+
+  test("collects only map-typed lists that name their keys", () => {
+    expect(specListMapKeyPairs(spec)).toEqual([
+      ["containers", ["name"]],
+      ["ports", ["port", "protocol"]],
+    ]);
+  });
+
+  test("accepts a Buffer, as the fetch path supplies", () => {
+    expect(specListMapKeyPairs(Buffer.from(spec, "utf-8"))).toHaveLength(2);
+  });
+
+  test("a spec with no definitions yields nothing rather than throwing", () => {
+    expect(specListMapKeyPairs(JSON.stringify({}))).toEqual([]);
+  });
+});

package/src/spec/parse.ts

@@ -25,6 +25,10 @@ export interface ParsedProperty {
   description?: string;
   enum?: string[];
   constraints: PropertyConstraints;
+  /** `x-kubernetes-list-type` — `map`, `set` or `atomic`. Absent when the spec does not say (chant #1441). */
+  listType?: string;
+  /** `x-kubernetes-list-map-keys` — the fields that jointly identify one element. Present only alongside `listType: "map"`. */
+  listMapKeys?: string[];
 }
 
 export interface ParsedPropertyType {
@@ -104,6 +108,16 @@ interface SwaggerDefinition {
   "x-kubernetes-group-version-kind"?: GroupVersionKind[];
   "x-kubernetes-int-or-string"?: boolean;
   "x-kubernetes-preserve-unknown-fields"?: boolean;
+  /**
+   * How the API server merges this list: `map` (associative, identified by
+   * {@link SwaggerDefinition["x-kubernetes-list-map-keys"]}), `set` (unordered,
+   * elements are their own identity), or `atomic` (replaced wholesale). chant
+   * #1441 — carried through so the drift engine can identify list elements
+   * semantically instead of positionally.
+   */
+  "x-kubernetes-list-type"?: string;
+  /** The property names that jointly identify one element of an associative list. */
+  "x-kubernetes-list-map-keys"?: string[];
 }
 
 interface SwaggerProperty extends SwaggerDefinition {
@@ -227,6 +241,33 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
 }
 
 /** Stable key for a GVK, used to join the `paths` pass onto the `definitions` pass. */
+/**
+ * Every `(property name, list-map keys)` pair the spec declares, across ALL
+ * definitions (chant #1441).
+ *
+ * Deliberately independent of {@link parseK8sSwagger}'s resource/property-type
+ * extraction. That extraction keeps 257 resources and 320 property types out
+ * of roughly a thousand definitions, so collecting merge keys from its output
+ * alone finds 18 of the 32 properties the spec annotates — and misses
+ * `ServicePort.port`, whose absence would silently demote every Service port
+ * list to the hand-written fallback. A definition is worth reading for its
+ * merge semantics whether or not chant emits a type for it.
+ */
+export function specListMapKeyPairs(data: string | Buffer): Array<[string, string[]]> {
+  const spec = JSON.parse(typeof data === "string" ? data : data.toString("utf-8")) as SwaggerSpec;
+  const pairs: Array<[string, string[]]> = [];
+
+  for (const def of Object.values(spec.definitions ?? {})) {
+    for (const [name, prop] of Object.entries(def.properties ?? {})) {
+      if (prop["x-kubernetes-list-type"] !== "map") continue;
+      const keys = prop["x-kubernetes-list-map-keys"];
+      if (keys?.length) pairs.push([name, [...keys]]);
+    }
+  }
+
+  return pairs;
+}
+
 export function gvkKey(gvk: GroupVersionKind): string {
   return `${gvk.group}|${gvk.version}|${gvk.kind}`;
 }
@@ -442,14 +483,22 @@ function parseProperties(
 
   for (const [name, prop] of Object.entries(properties)) {
     const tsType = resolvePropertyType(prop, definitions);
-    result.push({
+    const parsed: ParsedProperty = {
       name,
       tsType,
       required: requiredSet.has(name),
       description: prop.description,
       enum: prop.enum,
       constraints: coreExtractConstraints(prop as JsonSchemaProperty),
-    });
+    };
+    // chant #1441 — the merge semantics the API server itself uses. Kept only
+    // when present; a spec that says nothing leaves both fields absent rather
+    // than asserting a default the schema did not state.
+    const listType = prop["x-kubernetes-list-type"];
+    if (listType) parsed.listType = listType;
+    const listMapKeys = prop["x-kubernetes-list-map-keys"];
+    if (listMapKeys?.length) parsed.listMapKeys = [...listMapKeys];
+    result.push(parsed);
   }
 
   return result;