@intentius/chant-lexicon-k8s 0.44.14 → 0.46.0

package/src/serializer.test.ts

@@ -348,7 +348,7 @@ describe("k8sSerializer", () => {
       }),
     );
 
-    const result = k8sSerializer.serialize(entities);
+    const result = k8sSerializer.serialize(entities) as string;
     expect(result).toContain("env: prod");
     // Should not contain "dev" since explicit overrides
     const envLines = result.split("\n").filter((l: string) => l.includes("env:"));
@@ -366,7 +366,7 @@ describe("k8sSerializer", () => {
       }),
     );
 
-    const result = k8sSerializer.serialize(entities);
+    const result = k8sSerializer.serialize(entities) as string;
     expect(result).toContain("kind: Deployment");
     // Only one document — property entities should not appear as separate docs
     expect(result.split("---").length).toBeLessThanOrEqual(2);
@@ -406,7 +406,7 @@ describe("k8sSerializer", () => {
       }),
     );
 
-    const result = k8sSerializer.serialize(entities);
+    const result = k8sSerializer.serialize(entities) as string;
     const docs = result.split("---");
     // First document should be the Namespace
     expect(docs[0]).toContain("kind: Namespace");
@@ -449,7 +449,7 @@ describe("k8sSerializer", () => {
       }),
     );
 
-    const result = k8sSerializer.serialize(entities);
+    const result = k8sSerializer.serialize(entities) as string;
     const lines = result.split("\n");
     const keyLines = lines.filter((l: string) => /^\w+:/.test(l));
     const keys = keyLines.map((l: string) => l.split(":")[0]);

package/src/spec/parse.ts

@@ -78,6 +78,33 @@ export interface ParsedOperation {
   verbs: string[];
 }
 
+/**
+ * Compact, recursive field schema for a custom resource's `spec` — chant #1372.
+ *
+ * Built-in kinds get their field typing from the generated `.d.ts`. A CRD's
+ * constructor takes `spec: Record<string, unknown>`, so its field names, enums
+ * and scalar types have to travel through the lexicon JSON instead. This is
+ * the shape that ships there: no descriptions, no numeric bounds, only what a
+ * validator needs to reject a misspelled field or a wrong-typed value.
+ */
+export interface CrdFieldSchema {
+  /** OpenAPI type; `integer` is kept distinct from `number`. Absent when the schema says nothing. */
+  type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
+  enum?: string[];
+  /** Object members, keyed by field name. */
+  fields?: Record<string, CrdFieldSchema>;
+  /** Required member names of an object. */
+  required?: string[];
+  /** Element schema of an array. */
+  items?: CrdFieldSchema;
+  /**
+   * True when the object accepts members its `fields` do not list —
+   * `x-kubernetes-preserve-unknown-fields` or `additionalProperties`.
+   * `x-kubernetes-int-or-string` also sets it on a scalar, meaning either type passes.
+   */
+  open?: true;
+}
+
 export interface K8sParseResult {
   resource: ParsedResource;
   propertyTypes: ParsedPropertyType[];
@@ -87,6 +114,12 @@ export interface K8sParseResult {
   isProperty?: boolean;
   /** How the API addresses this resource. Absent for property types. */
   operation?: ParsedOperation;
+  /**
+   * The `spec` field schema of a custom resource (chant #1372). Present only
+   * for CRD-derived kinds whose `openAPIV3Schema` declares a `spec`; built-in
+   * kinds carry their typing in the `.d.ts` instead.
+   */
+  specSchema?: CrdFieldSchema;
 }
 
 // ── Swagger types ──────────────────────────────────────────────────

package/src/teardown.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Env teardown over the fake cluster (chant #1222) — the k8s halves of the
+ * teardownOwned / executeTeardown capability pair, mirroring the typed-prune
+ * tests in op/activities/kubectl.test.ts: a real client over a fake request
+ * layer, so discovery, path construction, and the delete path all run for
+ * real.
+ */
+
+import { describe, test, expect } from "vitest";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { statusBody } from "@intentius/chant-k8s-client/testing";
+import { fakeCluster, objectKey, ownedObject } from "./api/fake-cluster";
+import { teardownOwned, executeTeardown } from "./teardown";
+
+const MARKER = { stack: "shop", env: "dev" };
+
+function markerLabels(stack: string, env?: string): Record<string, string> {
+  return {
+    [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+    [LABEL_OWNERSHIP_KEYS.stack]: stack,
+    ...(env ? { [LABEL_OWNERSHIP_KEYS.env]: env } : {}),
+  };
+}
+
+/** A cluster holding this env's estate plus every kind of near-miss. */
+function estateCluster(overrides: Parameters<typeof fakeCluster>[0] = {}) {
+  return fakeCluster({
+    objects: {
+      // Mine: full marker, this stack, this env.
+      [objectKey("apps/v1", "Deployment", "web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "web", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      [objectKey("v1", "Service", "cache", "prod-ns")]: ownedObject("v1", "Service", "cache", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      [objectKey("v1", "Namespace", "dev-ns")]: ownedObject("v1", "Namespace", "dev-ns", undefined, {
+        metadata: { labels: markerLabels("shop", "dev") },
+      }),
+      // Near-misses: foreign stack, foreign env, env-less marker, unmarked.
+      [objectKey("apps/v1", "Deployment", "their-web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "their-web", "prod-ns", {
+        metadata: { labels: markerLabels("blog", "dev") },
+      }),
+      [objectKey("apps/v1", "Deployment", "prod-twin", "prod-ns")]: ownedObject("apps/v1", "Deployment", "prod-twin", "prod-ns", {
+        metadata: { labels: markerLabels("shop", "prod") },
+      }),
+      [objectKey("apps/v1", "Deployment", "no-env", "prod-ns")]: ownedObject("apps/v1", "Deployment", "no-env", "prod-ns", {
+        metadata: { labels: markerLabels("shop") },
+      }),
+      [objectKey("apps/v1", "Deployment", "handmade", "prod-ns")]: {
+        apiVersion: "apps/v1",
+        kind: "Deployment",
+        metadata: { name: "handmade", namespace: "prod-ns", labels: { app: "handmade" } },
+      },
+    },
+    ...overrides,
+  });
+}
+
+describe("teardownOwned — marker-env-scoped enumeration", () => {
+  test("selects exactly the objects carrying this stack + env, nothing near", async () => {
+    const cluster = estateCluster();
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates.map((c) => c.name).sort()).toEqual(["dev-ns", "prod-ns/cache", "prod-ns/web"]);
+    for (const candidate of enumeration.candidates) {
+      expect(candidate.marker).toEqual(MARKER);
+    }
+    const web = enumeration.candidates.find((c) => c.name === "prod-ns/web")!;
+    expect(web.type).toBe("K8s::Apps::Deployment");
+    expect(web.physicalId).toBe("uid-web");
+    expect(enumeration.holes ?? []).toEqual([]);
+  });
+
+  test("the selector is sent to the server: managed-by + stack + env", async () => {
+    const cluster = estateCluster();
+    await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    const listQueries = cluster.layer.requests
+      .filter((r) => r.method === "GET" && r.query.labelSelector !== undefined)
+      .map((r) => r.query.labelSelector);
+    expect(listQueries.length).toBeGreaterThan(0);
+    for (const selector of listQueries) {
+      expect(selector).toBe(
+        `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE},` +
+        `${LABEL_OWNERSHIP_KEYS.stack}=shop,${LABEL_OWNERSHIP_KEYS.env}=dev`,
+      );
+    }
+  });
+
+  test("an object already terminating is not a candidate", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "leaving", "prod-ns")]: ownedObject("apps/v1", "Deployment", "leaving", "prod-ns", {
+          metadata: { labels: markerLabels("shop", "dev"), deletionTimestamp: "2026-08-23T00:00:00Z" } as never,
+        }),
+      },
+    });
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates).toEqual([]);
+  });
+
+  test("a kind that fails to list is a hole, and the others still enumerate (#1089)", async () => {
+    const cluster = estateCluster({
+      respond: (req) => {
+        if (req.method === "GET" && req.path.endsWith("/deployments") && req.query.labelSelector !== undefined) {
+          return { status: 500, body: statusBody(500, "InternalError", "etcd is unhappy") };
+        }
+        return undefined;
+      },
+    });
+    const enumeration = await teardownOwned({ environment: "dev", marker: MARKER }, cluster.connector);
+    expect(enumeration.candidates.map((c) => c.name).sort()).toEqual(["dev-ns", "prod-ns/cache"]);
+    const hole = (enumeration.holes ?? []).find((h) => h.name === "K8s::Apps::Deployment");
+    expect(hole).toBeDefined();
+    expect(hole!.reason).toBe("read-failed");
+  });
+});
+
+describe("executeTeardown — typed deletes, namespaces last", () => {
+  const candidates = [
+    { name: "dev-ns", type: "K8s::Core::Namespace", marker: MARKER },
+    { name: "prod-ns/web", type: "K8s::Apps::Deployment", physicalId: "uid-web", marker: MARKER },
+    { name: "prod-ns/cache", type: "K8s::Core::Service", marker: MARKER },
+  ];
+
+  test("deletes every candidate through the typed client, namespace last", async () => {
+    const cluster = estateCluster();
+    const execution = await executeTeardown({ environment: "dev", marker: MARKER, candidates }, cluster.connector);
+
+    expect(execution.outcomes.map((o) => ({ name: o.name, outcome: o.outcome }))).toEqual([
+      { name: "prod-ns/web", outcome: "deleted" },
+      { name: "prod-ns/cache", outcome: "deleted" },
+      { name: "dev-ns", outcome: "deleted" },
+    ]);
+    const deletes = cluster.layer.requests.filter((r) => r.method === "DELETE").map((r) => r.path);
+    expect(deletes).toEqual([
+      "/apis/apps/v1/namespaces/prod-ns/deployments/web",
+      "/api/v1/namespaces/prod-ns/services/cache",
+      "/api/v1/namespaces/dev-ns",
+    ]);
+  });
+
+  test("an already-absent candidate is deleted (idempotent), with no DELETE issued", async () => {
+    const cluster = fakeCluster({ objects: {} });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes).toEqual([
+      {
+        name: "prod-ns/web",
+        type: "K8s::Apps::Deployment",
+        physicalId: "uid-web",
+        outcome: "deleted",
+        detail: "already absent",
+      },
+    ]);
+    expect(cluster.layer.requests.filter((r) => r.method === "DELETE")).toEqual([]);
+  });
+
+  test("a live object whose marker changed since planning is not-prunable, never deleted", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod-ns")]: ownedObject("apps/v1", "Deployment", "web", "prod-ns", {
+          metadata: { labels: markerLabels("blog", "dev") }, // re-stamped by someone else
+        }),
+      },
+    });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("not-prunable");
+    expect(execution.outcomes[0].detail).toContain("marker identity");
+    expect(cluster.layer.requests.filter((r) => r.method === "DELETE")).toEqual([]);
+  });
+
+  test("a refused delete is a failed outcome with the server's message, not a throw", async () => {
+    const cluster = estateCluster({
+      respond: (req) =>
+        req.method === "DELETE"
+          ? { status: 403, body: statusBody(403, "Forbidden", "RBAC says no") }
+          : undefined,
+    });
+    const execution = await executeTeardown(
+      { environment: "dev", marker: MARKER, candidates: [candidates[1]] },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("failed");
+    expect(execution.outcomes[0].detail).toContain("RBAC says no");
+  });
+
+  test("a candidate of an unmapped type is not-prunable, not a crash", async () => {
+    const cluster = fakeCluster({ objects: {} });
+    const execution = await executeTeardown(
+      {
+        environment: "dev",
+        marker: MARKER,
+        candidates: [{ name: "mystery", type: "K8s::NotAThing::Widget", marker: MARKER }],
+      },
+      cluster.connector,
+    );
+    expect(execution.outcomes[0].outcome).toBe("not-prunable");
+    expect(execution.outcomes[0].detail).toContain("no operation mapping");
+  });
+});

package/src/teardown.ts

@@ -0,0 +1,225 @@
+/**
+ * Env teardown for the k8s lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair.
+ *
+ * Selection is the prune's marker selector (op/activities/kubectl.ts) with the
+ * env dimension added: `app.kubernetes.io/managed-by=chant` +
+ * `chant.intentius.io/stack=<stack>` + `chant.intentius.io/env=<env>`, sent to
+ * the server as a label selector and re-checked object by object with
+ * `readOwnership` — the server-side filter narrows the read, the client-side
+ * re-check is the one that matters, because a delete is not undoable.
+ *
+ * Swept kinds are chant's default sweep set (`DEFAULT_IMPORT_TYPES`, the same
+ * list the ownership-scoped prune unions in), listed cluster-wide: env
+ * teardown has no apply set to scope namespaces by, and the marker selector is
+ * the scope. A kind the cluster's discovery does not serve cannot hold a
+ * marked object and is skipped; a kind that resolves but fails to list is a
+ * hole (#1089) — unknown, never absent.
+ *
+ * Execution deletes the handed-over candidates through the typed client's own
+ * `delete()` — the identical delete the prune and `chant kube delete` use —
+ * with namespaces last, so a namespace's own members get individual outcomes
+ * before the cascade would have swallowed them. Before each delete the live
+ * object is re-read and its marker re-verified; an object that vanished is
+ * `deleted` (teardown is idempotent), one whose identity no longer matches is
+ * `not-prunable`, never deleted.
+ */
+
+import type {
+  TeardownCandidate,
+  TeardownEnumeration,
+  TeardownExecution,
+  TeardownHole,
+  TeardownOutcome,
+} from "@intentius/chant/lexicon";
+import {
+  LABEL_OWNERSHIP_KEYS,
+  OWNERSHIP_MANAGED_BY_VALUE,
+  readOwnership,
+  type OwnershipMarker,
+} from "@intentius/chant/ownership";
+import type { K8sClient } from "@intentius/chant-k8s-client";
+import { DEFAULT_IMPORT_TYPES } from "./api/sweep-types";
+import { operationFor } from "./api/operation-surface";
+import { defaultK8sConnector, type K8sConnector } from "./api/connect";
+
+const NAMESPACE_TYPE = "K8s::Core::Namespace";
+
+export interface K8sTeardownOptions {
+  environment: string;
+  marker: OwnershipMarker;
+}
+
+/** The label selector that scopes everything here: managed-by + stack + env. */
+function markerSelector(marker: OwnershipMarker): string {
+  return [
+    `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
+    `${LABEL_OWNERSHIP_KEYS.stack}=${marker.stack}`,
+    ...(marker.env ? [`${LABEL_OWNERSHIP_KEYS.env}=${marker.env}`] : []),
+  ].join(",");
+}
+
+/** True when a live object's own labels carry exactly the requested identity. */
+function matchesMarker(
+  labels: Record<string, string> | undefined,
+  marker: OwnershipMarker,
+): boolean {
+  const read = readOwnership(labels, LABEL_OWNERSHIP_KEYS);
+  return read !== undefined && read.stack === marker.stack && read.env === marker.env;
+}
+
+/**
+ * Enumerate the cluster's marker-matching objects — the k8s half of
+ * `chant lifecycle teardown <env>` planning.
+ */
+export async function teardownOwned(
+  options: K8sTeardownOptions,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<TeardownEnumeration> {
+  const { client } = await connect({ environment: options.environment });
+  const selector = markerSelector(options.marker);
+
+  const candidates: TeardownCandidate[] = [];
+  const holes: TeardownHole[] = [];
+
+  for (const entityType of DEFAULT_IMPORT_TYPES) {
+    const operation = operationFor(entityType);
+    if (!operation) continue;
+    const ref = { apiVersion: operation.apiVersion, kind: operation.kind };
+
+    let served: boolean;
+    try {
+      served = (await client.resolve(ref)) !== undefined;
+    } catch (err) {
+      holes.push({
+        name: entityType,
+        type: entityType,
+        reason: "read-failed",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    // A kind this cluster's discovery does not serve cannot hold a marked
+    // object — absence of the kind is knowledge, not a hole.
+    if (!served) continue;
+
+    let items;
+    try {
+      items = await client.list(ref, { labelSelector: selector });
+    } catch (err) {
+      holes.push({
+        name: entityType,
+        type: entityType,
+        reason: "read-failed",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+
+    for (const item of items) {
+      const name = item.metadata?.name;
+      if (!name) continue;
+      // The re-check that matters: a server (or fake) that ignored the label
+      // selector must not widen the set past the requested identity.
+      if (!matchesMarker(item.metadata?.labels, options.marker)) continue;
+      // Already terminating — deleting again is noise, not progress.
+      if (item.metadata?.deletionTimestamp !== undefined) continue;
+      const namespace = item.metadata?.namespace;
+      candidates.push({
+        name: namespace ? `${namespace}/${name}` : name,
+        type: entityType,
+        ...(item.metadata?.uid ? { physicalId: String(item.metadata.uid) } : {}),
+        marker: readOwnership(item.metadata?.labels, LABEL_OWNERSHIP_KEYS)!,
+      });
+    }
+  }
+
+  return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+
+/**
+ * Delete the handed-over candidates, namespaces last. One outcome per
+ * candidate, always.
+ */
+export async function executeTeardown(
+  options: K8sTeardownOptions & { candidates: TeardownCandidate[] },
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<TeardownExecution> {
+  const { client } = await connect({ environment: options.environment });
+
+  // Namespaces last: their members get individual deletes (and individual
+  // outcomes) before the namespace cascade sweeps whatever is left.
+  const ordered = [
+    ...options.candidates.filter((c) => c.type !== NAMESPACE_TYPE),
+    ...options.candidates.filter((c) => c.type === NAMESPACE_TYPE),
+  ];
+
+  const outcomes: TeardownOutcome[] = [];
+  for (const candidate of ordered) {
+    outcomes.push(await deleteCandidate(client, candidate, options.marker));
+  }
+  return { outcomes };
+}
+
+async function deleteCandidate(
+  client: K8sClient,
+  candidate: TeardownCandidate,
+  marker: OwnershipMarker,
+): Promise<TeardownOutcome> {
+  const base = {
+    name: candidate.name,
+    type: candidate.type,
+    ...(candidate.physicalId ? { physicalId: candidate.physicalId } : {}),
+  };
+
+  const operation = operationFor(candidate.type);
+  if (!operation) {
+    return { ...base, outcome: "not-prunable", detail: `no operation mapping for type ${candidate.type}` };
+  }
+
+  let info;
+  try {
+    info = await client.resolve({ apiVersion: operation.apiVersion, kind: operation.kind });
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (!info) {
+    return { ...base, outcome: "not-prunable", detail: `the cluster does not serve ${operation.kind}` };
+  }
+
+  const slash = candidate.name.indexOf("/");
+  const namespace = info.namespaced && slash > 0 ? candidate.name.slice(0, slash) : undefined;
+  const name = info.namespaced && slash > 0 ? candidate.name.slice(slash + 1) : candidate.name;
+  const ref = {
+    apiVersion: operation.apiVersion,
+    kind: operation.kind,
+    name,
+    ...(namespace !== undefined ? { namespace } : {}),
+  };
+
+  // Re-read and re-verify the identity right before deleting: the enumeration
+  // is a moment old at best, and a delete is not undoable.
+  let live;
+  try {
+    live = await client.readIfPresent(ref);
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (live === undefined) {
+    return { ...base, outcome: "deleted", detail: "already absent" };
+  }
+  if (!matchesMarker(live.metadata?.labels, marker)) {
+    return {
+      ...base,
+      outcome: "not-prunable",
+      detail: "the live object no longer carries the requested marker identity",
+    };
+  }
+
+  try {
+    await client.delete(ref);
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  return { ...base, outcome: "deleted" };
+}

package/src/validate.ts

@@ -42,9 +42,12 @@ export async function validate(opts?: { basePath?: string }): Promise<ValidateRe
     lexiconJsonFilename: "lexicon-k8s.json",
     requiredNames: REQUIRED_NAMES,
     basePath,
-    // chant #1475 — the k8s baseline was re-baselined together with the k3s
-    // CRD work (#1605), so a release must now verify the API it ships is the
-    // reviewed one. Runs only under CHANT_RELEASE_GATE=1.
-    checkSurfaceSnapshot: true,
+    // chant #1475 — the baseline was re-baselined with the k3s CRD work
+    // (#1605). k8s generates from a pinned kubernetes release tag plus CRDs
+    // vendored in this repo, so a fresh generate is deterministic and the
+    // surface can only move through a change here. Gate on every validate,
+    // not just under CHANT_RELEASE_GATE, so a CRD batch can no longer leave
+    // the snapshot behind the way #1319/#1320/#1321 did.
+    checkSurfaceSnapshot: "always",
   });
 }