@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/kube/testing.ts

@@ -0,0 +1,42 @@
+/**
+ * Test doubles for `chant kube` (chant #1079).
+ *
+ * `./project.ts`'s real `loadKubeProjectContext` builds an actual project
+ * (`chant.config.ts` read, source discovered, serialized) — every verb takes
+ * it as an injectable dependency for exactly this reason: a unit test builds
+ * a `KubeProjectContext` by hand instead, the same way `../api/fake-cluster.ts`
+ * lets a test build a client without a socket.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { setProvenance, type EntityProvenance } from "@intentius/chant/provenance";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { KubeProjectContext } from "./project";
+
+export type FakeDeclarable = Declarable & { props: Record<string, unknown> };
+
+/** A minimal `Declarable` carrying `props`, optionally stamped with build provenance. */
+export function fakeDeclarable(
+  entityType: string,
+  props: Record<string, unknown>,
+  provenance?: EntityProvenance,
+): FakeDeclarable {
+  const entity: FakeDeclarable = {
+    lexicon: "k8s",
+    entityType,
+    kind: "resource",
+    props,
+    [DECLARABLE_MARKER]: true,
+  };
+  if (provenance) setProvenance(entity, provenance);
+  return entity;
+}
+
+/** A `KubeProjectContext` built from a plain name → entity map, no disk I/O. */
+export function fakeProjectContext(
+  entities: Record<string, Declarable>,
+  config: ChantConfig = {},
+  cwd = "/project",
+): KubeProjectContext {
+  return { cwd, config, entities: new Map(Object.entries(entities)) };
+}

package/src/kube/top.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster } from "../api/fake-cluster";
+import { runTop } from "./top";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+const METRICS_DISCOVERY = {
+  path: "/apis/metrics.k8s.io/v1beta1",
+  body: {
+    kind: "APIResourceList",
+    apiVersion: "v1",
+    groupVersion: "metrics.k8s.io/v1beta1",
+    resources: [
+      { name: "pods", singularName: "", namespaced: true, kind: "PodMetrics", verbs: ["get", "list"] },
+      { name: "nodes", singularName: "", namespaced: false, kind: "NodeMetrics", verbs: ["get", "list"] },
+    ],
+  },
+};
+
+function withMetricsGroup(respond: (req: { path: string }) => { status?: number; body?: unknown } | undefined) {
+  return (req: { path: string }) => {
+    if (req.path === "/apis") {
+      return {
+        body: {
+          kind: "APIGroupList",
+          groups: [
+            {
+              name: "metrics.k8s.io",
+              preferredVersion: { groupVersion: "metrics.k8s.io/v1beta1" },
+              versions: [{ groupVersion: "metrics.k8s.io/v1beta1" }],
+            },
+          ],
+        },
+      };
+    }
+    if (req.path === METRICS_DISCOVERY.path) return { body: METRICS_DISCOVERY.body };
+    return respond(req);
+  };
+}
+
+describe("chant kube top (#1079)", () => {
+  test("happy path: pods usage, per container, unsummed", async () => {
+    const cluster = fakeCluster({
+      serves: [],
+      respond: withMetricsGroup((req) =>
+        req.path === "/apis/metrics.k8s.io/v1beta1/namespaces/prod/pods"
+          ? {
+              body: {
+                items: [
+                  {
+                    metadata: { name: "web", namespace: "prod" },
+                    containers: [{ name: "app", usage: { cpu: "250m", memory: "128Mi" } }],
+                  },
+                ],
+              },
+            }
+          : undefined,
+      ),
+    });
+    const { log } = spyConsole();
+
+    const code = await runTop(["pods", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls[0][0] as string;
+    expect(out).toContain("web");
+    expect(out).toContain("app:250m");
+    expect(out).toContain("app:128Mi");
+  });
+
+  test("nodes usage", async () => {
+    const cluster = fakeCluster({
+      serves: [],
+      respond: withMetricsGroup((req) =>
+        req.path === "/apis/metrics.k8s.io/v1beta1/nodes"
+          ? { body: { items: [{ metadata: { name: "node-1" }, usage: { cpu: "500m", memory: "2Gi" } }] } }
+          : undefined,
+      ),
+    });
+    const { log } = spyConsole();
+
+    const code = await runTop(["nodes"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls[0][0] as string;
+    expect(out).toContain("node-1");
+    expect(out).toContain("500m");
+    expect(out).toContain("2Gi");
+  });
+
+  test("metrics-server absent renders a clear message, not an empty table", async () => {
+    const cluster = fakeCluster({ serves: [] });
+    const { error, log } = spyConsole();
+
+    const code = await runTop(["pods"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("metrics-server");
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  test("binding mismatch refuses loudly", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runTop(["pods", "--env", "prod"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before any connection", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runTop(["pods", "--bogus"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: an RBAC-denied metrics read renders NOT-OBSERVED", async () => {
+    const cluster = fakeCluster({
+      serves: [],
+      respond: withMetricsGroup((req) =>
+        req.path === "/apis/metrics.k8s.io/v1beta1/namespaces/prod/pods"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "forbidden" } }
+          : undefined,
+      ),
+    });
+    const { error, log } = spyConsole();
+
+    const code = await runTop(["pods", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no credentials");
+    expect(log).not.toHaveBeenCalled();
+  });
+});

package/src/kube/top.ts

@@ -0,0 +1,120 @@
+/**
+ * `chant kube top pods|nodes` (chant #1079).
+ *
+ * `metrics.k8s.io` is not part of the standard Kubernetes OpenAPI schema chant's
+ * codegen ingests — it is an aggregated API a cluster may or may not be running
+ * (metrics-server). It needs no entry in the generated operation surface either
+ * way: the typed client's kubectl-style selector (`{ resource, group }`) resolves
+ * purely off the *cluster's own* discovery, the same path `waitForReady`'s `kind`
+ * argument already uses for CRDs — so this needs no client change, only the
+ * right selector.
+ *
+ * Kubectl's own `top` sums each Pod's per-container usage into one CPU/memory
+ * figure, which needs real quantity-unit arithmetic (`250m` + `100m`, `128Mi` +
+ * `64Mi`). That normalization is not implemented here — each container's raw
+ * usage string is shown as the API reported it, unsummed. Good enough for "is
+ * anything obviously starved", not a replacement for `kubectl top --containers`.
+ */
+
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { renderTable } from "./render";
+
+export interface TopDeps {
+  connect?: K8sConnector;
+}
+
+const RESOURCE_ALIASES: Record<string, "pods" | "nodes"> = {
+  pod: "pods",
+  pods: "pods",
+  po: "pods",
+  node: "nodes",
+  nodes: "nodes",
+  no: "nodes",
+};
+
+export async function runTop(rawArgs: string[], deps: TopDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const resource = RESOURCE_ALIASES[flags.positional[0] ?? "pods"];
+  if (!resource) {
+    console.error(`error: unknown resource "${flags.positional[0]}" — chant kube top supports "pods" and "nodes"`);
+    return 1;
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(resource, { reason: connected.reason, detail: connected.detail }));
+    return 1;
+  }
+  const { client } = connected;
+
+  let info;
+  try {
+    info = await client.resolve({ resource, group: "metrics.k8s.io" });
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(resource, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+  if (!info) {
+    console.error(
+      "error: the metrics API (metrics.k8s.io) is not available in this cluster — is metrics-server installed?",
+    );
+    return 1;
+  }
+
+  const namespace = resource === "pods" && !flags.flags.allNamespaces ? (flags.values.namespace ?? client.defaultNamespace) : undefined;
+
+  let items;
+  try {
+    items = await client.list(
+      { apiVersion: info.apiVersion, kind: info.kind },
+      { ...(namespace ? { namespace } : {}) },
+    );
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(resource, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+
+  if (resource === "nodes") {
+    const rows = items.map((n) => [
+      n.metadata?.name ?? "",
+      String((n.usage as Record<string, unknown> | undefined)?.cpu ?? "<unknown>"),
+      String((n.usage as Record<string, unknown> | undefined)?.memory ?? "<unknown>"),
+    ]);
+    console.log(renderTable(["NAME", "CPU", "MEMORY"], rows));
+    return 0;
+  }
+
+  const rows = items.map((p) => {
+    const containers = (p.containers as Array<{ name?: string; usage?: Record<string, unknown> }> | undefined) ?? [];
+    const cpu = containers.map((c) => `${c.name}:${c.usage?.cpu ?? "?"}`).join(",") || "<none>";
+    const memory = containers.map((c) => `${c.name}:${c.usage?.memory ?? "?"}`).join(",") || "<none>";
+    return [p.metadata?.namespace ?? "", p.metadata?.name ?? "", cpu, memory];
+  });
+  console.log(renderTable(["NAMESPACE", "NAME", "CPU (per container)", "MEMORY (per container)"], rows));
+  return 0;
+}

package/src/kube/verdict.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "vitest";
+import { verdictFor, declaredSubsetMatches } from "./verdict";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import type { DeclaredMatch } from "./project";
+import { fakeDeclarable } from "./testing";
+
+function match(props: Record<string, unknown>): DeclaredMatch {
+  return { entityName: "web", entity: fakeDeclarable("K8s::Apps::Deployment", props), props };
+}
+
+describe("declaredSubsetMatches", () => {
+  test("extra live fields (server defaults, status) are not drift", () => {
+    expect(
+      declaredSubsetMatches({ spec: { replicas: 2 } }, { spec: { replicas: 2, strategy: "RollingUpdate" }, status: { readyReplicas: 2 } }),
+    ).toBe(true);
+  });
+
+  test("a declared field the live object disagrees on is drift", () => {
+    expect(declaredSubsetMatches({ spec: { replicas: 2 } }, { spec: { replicas: 9 } })).toBe(false);
+  });
+
+  test("arrays must match length and every element", () => {
+    expect(declaredSubsetMatches({ a: [1, 2] }, { a: [1, 2, 3] })).toBe(false);
+    expect(declaredSubsetMatches({ a: [1, 2] }, { a: [1, 2] })).toBe(true);
+  });
+});
+
+describe("verdictFor", () => {
+  test("a matched entity with an agreeing live object is declared", () => {
+    const live = { metadata: { name: "web" }, spec: { replicas: 2 } } as unknown as K8sObject;
+    expect(verdictFor(live, match({ metadata: { name: "web" }, spec: { replicas: 2 } }))).toBe("declared");
+  });
+
+  test("a matched entity whose live spec disagrees is drifted", () => {
+    const live = { metadata: { name: "web" }, spec: { replicas: 9 } } as unknown as K8sObject;
+    expect(verdictFor(live, match({ metadata: { name: "web" }, spec: { replicas: 2 } }))).toBe("drifted");
+  });
+
+  test("no match + chant's marker label is owned", () => {
+    const live = { metadata: { name: "x", labels: { "app.kubernetes.io/managed-by": "chant" } } } as unknown as K8sObject;
+    expect(verdictFor(live, undefined)).toBe("owned");
+  });
+
+  test("no match + no marker is foreign-owned", () => {
+    const live = { metadata: { name: "x" } } as unknown as K8sObject;
+    expect(verdictFor(live, undefined)).toBe("foreign-owned");
+  });
+});

package/src/kube/verdict.ts

@@ -0,0 +1,77 @@
+/**
+ * The chant verdict column `chant kube get` carries on every row (chant
+ * #1079's acceptance criterion: "get annotates each row with the declared /
+ * owned / drifted / foreign-owned verdict").
+ *
+ * Four states:
+ *
+ * - `declared` — this project's source names an entity at this exact
+ *   apiVersion/kind/name(/namespace), and the live object agrees with it on
+ *   every field the source declares.
+ * - `drifted` — same match, but the live object disagrees with the source on
+ *   at least one declared field.
+ * - `owned` — no declared match, but the live object carries chant's
+ *   ownership marker (`app.kubernetes.io/managed-by=chant`) — something
+ *   chant applied that source no longer declares, or a stack/entity this
+ *   project's build didn't resolve.
+ * - `foreign-owned` — no declared match and no marker: chant does not
+ *   consider this object its own.
+ *
+ * `unavailable` is not a verdict about the object; it is what every row gets
+ * when the project context could not be loaded at all (chant #1079's
+ * "degrades gracefully outside a chant project" — `get` and `describe` still
+ * work, this column just has nothing to say).
+ *
+ * The drift check here is a fast, best-effort *declared-subset* comparison —
+ * every path the source sets must agree on the live object — not the
+ * managed-fields-precise diff `chant lifecycle diff --live --deep` computes
+ * (chant #1076). It exists for a table column that must render for dozens of
+ * rows in one `get` call; the deep, field-ownership-aware answer stays the
+ * lifecycle command's job. A live object can disagree with the source on a
+ * field a controller owns (Kubernetes rewriting `spec.replicas` under an
+ * HPA, say) and still show `drifted` here — reach for the deep diff before
+ * treating this column as a verdict rather than a hint.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import type { DeclaredMatch } from "./project";
+
+export type KubeVerdict = "declared" | "owned" | "drifted" | "foreign-owned" | "unavailable";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * True when every path `declared` sets is present and equal on `live`.
+ * Extra fields on `live` (server defaults, status, anything the source never
+ * mentions) are not drift — chant never declared an opinion about them.
+ */
+export function declaredSubsetMatches(declared: unknown, live: unknown): boolean {
+  if (Array.isArray(declared)) {
+    if (!Array.isArray(live) || declared.length !== live.length) return false;
+    return declared.every((item, i) => declaredSubsetMatches(item, live[i]));
+  }
+  if (isPlainObject(declared)) {
+    if (!isPlainObject(live)) return false;
+    return Object.entries(declared).every(([key, value]) => declaredSubsetMatches(value, live[key]));
+  }
+  return declared === live;
+}
+
+/** The declared fields worth comparing — everything but the name/namespace identity itself. */
+function declaredComparable(props: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!props) return {};
+  const { metadata, ...rest } = props;
+  if (!isPlainObject(metadata)) return rest;
+  const { name: _name, namespace: _namespace, ...restMetadata } = metadata;
+  return { ...rest, ...(Object.keys(restMetadata).length > 0 ? { metadata: restMetadata } : {}) };
+}
+
+export function verdictFor(live: K8sObject, match: DeclaredMatch | undefined): KubeVerdict {
+  if (match) {
+    return declaredSubsetMatches(declaredComparable(match.props), live) ? "declared" : "drifted";
+  }
+  return hasOwnershipMarker(live.metadata?.labels, LABEL_OWNERSHIP_KEYS) ? "owned" : "foreign-owned";
+}

package/src/kube/wait.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster, objectKey } from "../api/fake-cluster";
+import { runWait } from "./wait";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+function certificate(ready: boolean) {
+  return {
+    apiVersion: "cert-manager.io/v1",
+    kind: "Certificate",
+    metadata: { name: "web-tls", namespace: "prod", uid: "u1" },
+    status: { conditions: ready ? [{ type: "Ready", status: "True" }] : [{ type: "Ready", status: "False" }] },
+  };
+}
+
+describe("chant kube wait (#1079)", () => {
+  test("happy path: the registry's default Ready condition is satisfied immediately", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "web-tls", "prod")]: certificate(true) },
+    });
+    const { log } = spyConsole();
+
+    const code = await runWait(["certificate", "web-tls", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("condition met");
+  });
+
+  test("--for=condition=<Type>=<Status> overrides the registry", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+          status: { conditions: [{ type: "Available", status: "True" }] },
+        },
+      },
+    });
+    const { log } = spyConsole();
+
+    const code = await runWait(["deployment", "web", "-n", "prod", "--for=condition=Available"], {
+      connect: cluster.connector,
+    });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("condition met");
+  });
+
+  test("--for=delete polls for absence", async () => {
+    const cluster = fakeCluster({});
+    const { log } = spyConsole();
+
+    const code = await runWait(["deployment", "ghost", "-n", "prod", "--for=delete", "--timeout=5s"], {
+      connect: cluster.connector,
+    });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("deleted");
+  });
+
+  test("a resource that never becomes ready times out honestly", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "web-tls", "prod")]: certificate(false) },
+    });
+    const { error } = spyConsole();
+
+    const code = await runWait(["certificate", "web-tls", "-n", "prod", "--timeout=1s"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("timed out");
+  }, 10_000);
+
+  test("binding mismatch refuses loudly, before any wait loop starts", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runWait(["deployment", "web", "--env", "prod"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before any connection", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runWait(["deployment", "web", "--bogus"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("wait requires a single named resource", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runWait(["deployment"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("requires a single named resource");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: a kind the cluster does not serve renders an explicit error", async () => {
+    const cluster = fakeCluster({ serves: [] });
+    const { error, log } = spyConsole();
+
+    const code = await runWait(["widgets", "gizmo"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain(`doesn't have a resource type "widgets"`);
+    expect(log).not.toHaveBeenCalled();
+  });
+});