@intentius/chant-lexicon-k8s 0.1.14 → 0.1.16

package/src/import/live-export.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "vitest";
+import { stripServerFields, buildExportFromObjects } from "./live-export";
+import { K8sGenerator } from "./generator";
+
+// A live object as `kubectl get -o json` would return it — full of
+// server-written fields the user never authored.
+const liveDeployment = () => ({
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: {
+    name: "web",
+    namespace: "default",
+    uid: "abc-123",
+    resourceVersion: "9981",
+    generation: 4,
+    creationTimestamp: "2026-01-01T00:00:00Z",
+    managedFields: [{ manager: "kubectl", operation: "Apply" }],
+    annotations: {
+      "kubectl.kubernetes.io/last-applied-configuration": "{...}",
+      "team": "platform",
+    },
+    labels: { app: "web" },
+  },
+  spec: { replicas: 3, selector: { matchLabels: { app: "web" } } },
+  status: { readyReplicas: 3, replicas: 3 },
+});
+
+const liveService = () => ({
+  apiVersion: "v1",
+  kind: "Service",
+  metadata: { name: "web", namespace: "default", uid: "svc-1", resourceVersion: "12" },
+  spec: { ports: [{ port: 80 }], clusterIP: "10.0.0.1" },
+  status: { loadBalancer: {} },
+});
+
+describe("stripServerFields (#116)", () => {
+  test("removes status, managedFields, and server metadata", () => {
+    const cleaned = stripServerFields(liveDeployment());
+    expect(cleaned.status).toBeUndefined();
+    const md = cleaned.metadata as Record<string, unknown>;
+    expect(md.managedFields).toBeUndefined();
+    expect(md.uid).toBeUndefined();
+    expect(md.resourceVersion).toBeUndefined();
+    expect(md.generation).toBeUndefined();
+    expect(md.creationTimestamp).toBeUndefined();
+  });
+
+  test("drops server annotations but keeps authored ones", () => {
+    const cleaned = stripServerFields(liveDeployment());
+    const annotations = (cleaned.metadata as Record<string, unknown>).annotations as Record<string, string>;
+    expect(annotations["kubectl.kubernetes.io/last-applied-configuration"]).toBeUndefined();
+    expect(annotations.team).toBe("platform");
+  });
+
+  test("keeps authored spec and labels", () => {
+    const cleaned = stripServerFields(liveDeployment());
+    expect(cleaned.spec).toEqual({ replicas: 3, selector: { matchLabels: { app: "web" } } });
+    expect((cleaned.metadata as Record<string, unknown>).labels).toEqual({ app: "web" });
+  });
+
+  test("does not mutate the input", () => {
+    const input = liveDeployment();
+    stripServerFields(input);
+    expect(input.status).toBeDefined();
+    expect(input.metadata.managedFields).toBeDefined();
+  });
+});
+
+describe("buildExportFromObjects (#116)", () => {
+  test("maps live objects to export IR, stripped by default", () => {
+    const ir = buildExportFromObjects([liveDeployment(), liveService()]);
+    expect(ir.resources).toHaveLength(2);
+    const dep = ir.resources.find((r) => r.type === "K8s::Apps::Deployment")!;
+    expect(dep.properties.status).toBeUndefined();
+    expect((dep.properties.metadata as Record<string, unknown>).uid).toBeUndefined();
+  });
+
+  test("verbatim keeps server fields", () => {
+    const ir = buildExportFromObjects([liveDeployment()], { verbatim: true });
+    const dep = ir.resources[0];
+    expect(dep.properties.status).toBeDefined();
+    expect((dep.properties.metadata as Record<string, unknown>).uid).toBe("abc-123");
+  });
+
+  test("selector by type narrows the export", () => {
+    const ir = buildExportFromObjects([liveDeployment(), liveService()], {
+      selector: { type: "K8s::Core::Service" },
+    });
+    expect(ir.resources.map((r) => r.type)).toEqual(["K8s::Core::Service"]);
+  });
+
+  test("selector by name matches the live resource name", () => {
+    const ir = buildExportFromObjects([liveDeployment(), liveService()], {
+      selector: { name: "web" },
+    });
+    // Both are named "web" — name alone keeps both kinds.
+    expect(ir.resources).toHaveLength(2);
+  });
+
+  test("owned filter keeps only objects carrying the chant marker label (#120)", () => {
+    const mine = liveDeployment();
+    (mine.metadata as any).labels = { "app.kubernetes.io/managed-by": "chant", "chant.intentius.io/stack": "billing" };
+    const theirs = liveService(); // no chant label
+    const ir = buildExportFromObjects([mine, theirs], { owned: true });
+    expect(ir.resources.map((r) => r.type)).toEqual(["K8s::Apps::Deployment"]);
+  });
+
+  test("export IR feeds K8sGenerator (templateGenerator) unchanged", () => {
+    const ir = buildExportFromObjects([liveDeployment()]);
+    const files = new K8sGenerator().generate(ir);
+    expect(files.length).toBeGreaterThan(0);
+    expect(files.map((f) => f.content).join("\n")).toContain("Deployment");
+  });
+});

package/src/import/live-export.ts

@@ -0,0 +1,89 @@
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { K8sParser } from "./parser";
+
+/**
+ * Server-managed metadata fields that the API server fills in. They are not
+ * part of the declared shape and would only add noise to regenerated source,
+ * so they are stripped unless `verbatim` is set.
+ */
+const SERVER_METADATA_FIELDS = [
+  "managedFields",
+  "uid",
+  "resourceVersion",
+  "generation",
+  "creationTimestamp",
+  "selfLink",
+  "ownerReferences",
+  "finalizers",
+];
+
+/** Annotations the cluster writes back that are not authored config. */
+const SERVER_ANNOTATIONS = [
+  "kubectl.kubernetes.io/last-applied-configuration",
+  "deployment.kubernetes.io/revision",
+];
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Strip `status`, `managedFields`, and other server-written fields to reach the
+ * declared shape. Returns a new object; the input is not mutated.
+ */
+export function stripServerFields(obj: Record<string, unknown>): Record<string, unknown> {
+  const clone = JSON.parse(JSON.stringify(obj)) as Record<string, unknown>;
+  delete clone.status;
+
+  if (isRecord(clone.metadata)) {
+    const md = clone.metadata;
+    for (const f of SERVER_METADATA_FIELDS) delete md[f];
+    if (isRecord(md.annotations)) {
+      for (const a of SERVER_ANNOTATIONS) delete md.annotations[a];
+      if (Object.keys(md.annotations).length === 0) delete md.annotations;
+    }
+  }
+  return clone;
+}
+
+/**
+ * Build full-fidelity export IR from a list of live Kubernetes objects (the
+ * `items` of a `kubectl get -o json` List). Reuses the import K8sParser by
+ * feeding it the cleaned objects as JSON documents — JSON is valid YAML, so no
+ * separate serializer is needed. Pure: all I/O stays in the caller.
+ */
+export function buildExportFromObjects(
+  objects: unknown[],
+  opts: { verbatim?: boolean; selector?: ResourceSelector; owned?: boolean } = {},
+): ExportedTemplate {
+  const owning = opts.owned
+    ? objects.filter((o) => {
+        if (!isRecord(o)) return false;
+        const labels = isRecord(o.metadata) ? (o.metadata.labels as Record<string, unknown>) : undefined;
+        return hasOwnershipMarker(labels, "label");
+      })
+    : objects;
+
+  const cleaned = owning
+    .filter(isRecord)
+    .map((o) => (opts.verbatim ? o : stripServerFields(o)));
+
+  const content = cleaned.map((o) => JSON.stringify(o, null, 2)).join("\n---\n");
+  const ir = new K8sParser().parse(content);
+
+  const selector = opts.selector;
+  if (!selector || (selector.type === undefined && selector.name === undefined)) {
+    return ir;
+  }
+  return {
+    ...ir,
+    resources: ir.resources.filter((r) => {
+      const liveName = (r.metadata?.originalName as string | undefined) ?? r.logicalId;
+      return (
+        (selector.type === undefined || r.type === selector.type) &&
+        (selector.name === undefined || liveName === selector.name)
+      );
+    }),
+  };
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
   GceIngress, CockroachDbCluster, CockroachDbRegionStack,
   RayCluster, RayJob, RayService,
+  ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
   GkeFluentBitAgent, GkeOtelCollector, GkeExternalDnsAgent, AksExternalDnsAgent,
@@ -52,6 +53,10 @@ export type {
   RayClusterProps, RayClusterResult, RayClusterSpec, ResourceSpec, HeadGroupSpec, WorkerGroupSpec,
   RayJobProps, RayJobResult,
   RayServiceProps, RayServiceResult,
+  ArgoDestination, ArgoSyncPolicy,
+  ArgoAppForOptions, ArgoAppForResult,
+  ArgoRegionTarget, ArgoAppSetForRegionsOptions, ArgoAppSetForRegionsResult,
+  RegisterArgoClusterOptions, RegisterArgoClusterResult,
   AgicIngressProps, AgicIngressResult,
   AzureDiskStorageClassProps, AzureDiskStorageClassResult,
   AzureFileStorageClassProps, AzureFileStorageClassResult,

package/src/lifecycle-integration.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Cross-lexicon lifecycle integration (#163) — Kubernetes row.
+ *
+ * Drives the REAL k8sPlugin through core's live-import driver and the changeset
+ * path, with the `kubectl` edge mocked.
+ */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    exec: (
+      cmd: string,
+      cb: (err: Error | null, out: { stdout: string; stderr: string }) => void,
+    ) => {
+      const r = execMock(cmd);
+      queueMicrotask(() =>
+        r instanceof Error
+          ? cb(r, { stdout: "", stderr: "" })
+          : cb(null, r as { stdout: string; stderr: string }),
+      );
+    },
+  };
+});
+
+const { k8sPlugin } = await import("./plugin");
+const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
+const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+
+const liveDeployment = {
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: { name: "web", namespace: "default", uid: "d-1" },
+  spec: { replicas: 3, selector: { matchLabels: { app: "web" } } },
+};
+
+const emptyList = { stdout: JSON.stringify({ items: [] }), stderr: "" };
+
+describe("k8s lifecycle integration (#163)", () => {
+  beforeEach(() => execMock.mockReset());
+
+  test("live-import driver: real exportResources → IR → generated source", async () => {
+    execMock.mockImplementation((cmd?: string) =>
+      cmd?.includes("get deployment.apps")
+        ? { stdout: JSON.stringify({ items: [liveDeployment] }), stderr: "" }
+        : emptyList,
+    );
+    const output = mkdtempSync(join(tmpdir(), "chant-k8s-li-"));
+    try {
+      const result = await liveImportFromPlugins([k8sPlugin], {
+        environment: "prod",
+        output,
+        force: true,
+      });
+      expect(result.success).toBe(true);
+      expect(result.generatedFiles.length).toBeGreaterThan(0);
+      const all = readdirSync(output)
+        .map((f) => readFileSync(join(output, f), "utf-8"))
+        .join("\n")
+        .toLowerCase();
+      expect(all).toContain("deployment");
+    } finally {
+      rmSync(output, { recursive: true, force: true });
+    }
+  });
+
+  test("changeset path: real describeResources → buildChangeSet verdicts", async () => {
+    execMock.mockImplementation((cmd?: string) =>
+      cmd?.includes("deployment.apps web")
+        ? {
+            stdout: JSON.stringify({
+              metadata: { name: "web", namespace: "prod", uid: "uid-1" },
+              status: { readyReplicas: 3, replicas: 3 },
+            }),
+            stderr: "",
+          }
+        : new Error("not found"),
+    );
+
+    const observedNow = await k8sPlugin.describeResources!({
+      environment: "prod",
+      buildOutput: "",
+      entityNames: ["web"],
+      entities: new Map([
+        ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
+      ]),
+    });
+    expect(observedNow.web?.type).toBe("K8s::Apps::Deployment");
+
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["webSvc"]),
+      observedNow,
+      observedThen: undefined,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e.action]));
+    expect(byName.webSvc).toBe("create");
+    expect(byName.web).toBe("adopt");
+
+    const cs2 = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow,
+      observedThen: undefined,
+    });
+    expect(cs2.entries.find((e) => e.name === "web")!.action).toBe("noop");
+  });
+});

package/src/lint/post-synth/argo-helpers.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared helpers for the Argo post-synth checks (ARGO002, ARGO003, ARGO005).
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, type K8sManifest } from "./k8s-helpers";
+
+/** The always-present, in-cluster Argo destination. */
+export const IN_CLUSTER_SERVER = "https://kubernetes.default.svc";
+export const IN_CLUSTER_NAME = "in-cluster";
+
+/** Label that marks a Secret as an Argo CD external cluster registration. */
+export const CLUSTER_SECRET_TYPE_LABEL = "argocd.argoproj.io/secret-type";
+
+/** All manifests across every lexicon output. */
+export function allManifests(ctx: PostSynthContext): K8sManifest[] {
+  const manifests: K8sManifest[] = [];
+  for (const [, output] of ctx.outputs) {
+    manifests.push(...parseK8sManifests(getPrimaryOutput(output)));
+  }
+  return manifests;
+}
+
+/** Manifests of a given Argo kind. */
+export function manifestsOfKind(manifests: K8sManifest[], kind: string): K8sManifest[] {
+  return manifests.filter((m) => m.kind === kind);
+}
+
+/**
+ * Read a string field from a Secret's stringData or data block.
+ * (Argo cluster Secrets conventionally use stringData.)
+ */
+export function secretField(manifest: K8sManifest, key: string): string | undefined {
+  const stringData = manifest.stringData as Record<string, unknown> | undefined;
+  const data = manifest.data as Record<string, unknown> | undefined;
+  const fromStringData = stringData?.[key];
+  if (typeof fromStringData === "string") return fromStringData;
+  const fromData = data?.[key];
+  if (typeof fromData === "string") return fromData;
+  return undefined;
+}
+
+/** True if the Secret is labelled as an Argo cluster registration. */
+export function isClusterSecret(manifest: K8sManifest): boolean {
+  if (manifest.kind !== "Secret") return false;
+  const labels = manifest.metadata?.labels;
+  return labels?.[CLUSTER_SECRET_TYPE_LABEL] === "cluster";
+}

package/src/lint/post-synth/argo002.ts

@@ -0,0 +1,47 @@
+/**
+ * ARGO002: Application.spec.project must reference a declared AppProject
+ *
+ * An Argo `Application` names an `AppProject` in `spec.project`; the project is
+ * the RBAC and source/destination guardrail. If the named project isn't
+ * declared in the build, Argo will reject the Application at sync time. The
+ * built-in `default` project always exists on an Argo install, so a reference
+ * to `default` is never flagged.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+
+export const argo002: PostSynthCheck = {
+  id: "ARGO002",
+  description: "Application.spec.project must reference a declared AppProject (or the built-in default)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+
+    const declaredProjects = new Set(
+      manifestsOfKind(manifests, "AppProject")
+        .map((p) => p.metadata?.name)
+        .filter((n): n is string => typeof n === "string"),
+    );
+    // Argo ships a built-in default project.
+    declaredProjects.add("default");
+
+    for (const app of manifestsOfKind(manifests, "Application")) {
+      const project = app.spec?.project;
+      const name = app.metadata?.name ?? "Application";
+      // No project set → defaults to `default` at sync time; not this check's job.
+      if (typeof project !== "string" || project === "") continue;
+      if (declaredProjects.has(project)) continue;
+
+      diagnostics.push({
+        checkId: "ARGO002",
+        severity: "error",
+        message: `Application "${name}" references AppProject "${project}", which is not declared. Add an AppProject named "${project}" or reference an existing project.`,
+        entity: name,
+        lexicon: "k8s",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/argo003.ts

@@ -0,0 +1,80 @@
+/**
+ * ARGO003: Application.spec.destination must reference a registered cluster
+ *
+ * An Argo `Application` targets a cluster via `spec.destination.server` (an API
+ * server URL) or `spec.destination.name` (a registered cluster name). External
+ * clusters are registered with a Secret labelled
+ * `argocd.argoproj.io/secret-type: cluster`. The in-cluster target
+ * (`https://kubernetes.default.svc` / name `in-cluster`) is always available.
+ * A destination that names neither a registered cluster nor the in-cluster
+ * target won't resolve at sync time.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  allManifests,
+  manifestsOfKind,
+  isClusterSecret,
+  secretField,
+  IN_CLUSTER_SERVER,
+  IN_CLUSTER_NAME,
+} from "./argo-helpers";
+
+export const argo003: PostSynthCheck = {
+  id: "ARGO003",
+  description: "Application.spec.destination must reference a registered cluster or the in-cluster target",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+
+    const registeredServers = new Set<string>([IN_CLUSTER_SERVER]);
+    const registeredNames = new Set<string>([IN_CLUSTER_NAME]);
+    for (const secret of manifests.filter(isClusterSecret)) {
+      const server = secretField(secret, "server");
+      if (server) registeredServers.add(server);
+      const name = secretField(secret, "name") ?? secret.metadata?.name;
+      if (typeof name === "string") registeredNames.add(name);
+    }
+
+    for (const app of manifestsOfKind(manifests, "Application")) {
+      const name = app.metadata?.name ?? "Application";
+      const destination = app.spec?.destination as
+        | { server?: unknown; name?: unknown }
+        | undefined;
+
+      if (!destination || (destination.server === undefined && destination.name === undefined)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" has no spec.destination.server or spec.destination.name — Argo cannot resolve a target cluster.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+        continue;
+      }
+
+      if (typeof destination.server === "string" && !registeredServers.has(destination.server)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" targets cluster server "${destination.server}", which is not registered. Register it with a cluster Secret (label argocd.argoproj.io/secret-type=cluster) or use the in-cluster target.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+        continue;
+      }
+
+      if (typeof destination.name === "string" && !registeredNames.has(destination.name)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" targets cluster name "${destination.name}", which is not registered. Register it with a cluster Secret or use the in-cluster target.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/argo005.ts

@@ -0,0 +1,59 @@
+/**
+ * ARGO005: Application source.path should point at an existing directory (warn)
+ *
+ * When an Argo `Application` syncs from a git source it names a `source.path`
+ * inside the repo. In the common monorepo layout — Argo watches the same repo
+ * Chant builds — that path is relative to the build root, so a typo'd or moved
+ * path surfaces as a sync error only after deploy. This check warns when the
+ * path doesn't resolve to a directory under the build root.
+ *
+ * It is a warning, not an error: Applications that sync from a *different*
+ * remote repo legitimately reference paths that don't exist locally. Helm chart
+ * sources (`source.chart`) and pathless sources are skipped.
+ */
+import { existsSync, statSync } from "fs";
+import { isAbsolute, resolve } from "path";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+
+function dirExists(path: string): boolean {
+  try {
+    const full = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    return existsSync(full) && statSync(full).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export const argo005: PostSynthCheck = {
+  id: "ARGO005",
+  description: "Application source.path should resolve to an existing directory under the build root",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const app of manifestsOfKind(allManifests(ctx), "Application")) {
+      const name = app.metadata?.name ?? "Application";
+      const source = app.spec?.source as
+        | { path?: unknown; chart?: unknown }
+        | undefined;
+      if (!source) continue;
+      // Helm chart sources have no filesystem path.
+      if (typeof source.chart === "string" && source.chart !== "") continue;
+
+      const path = source.path;
+      if (typeof path !== "string" || path === "") continue;
+      if (dirExists(path)) continue;
+
+      diagnostics.push({
+        checkId: "ARGO005",
+        severity: "warning",
+        message: `Application "${name}" source.path "${path}" does not resolve to a directory under the build root. Confirm the path (or ignore if it lives in a different repo).`,
+        entity: name,
+        lexicon: "k8s",
+      });
+    }
+
+    return diagnostics;
+  },
+};