@intentius/chant-lexicon-k8s 0.0.12

package/src/serializer.test.ts

@@ -0,0 +1,275 @@
+import { describe, test, expect } from "bun:test";
+import { k8sSerializer } from "./serializer";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import {
+  defaultLabels,
+  defaultAnnotations,
+  DEFAULT_LABELS_MARKER,
+  DEFAULT_ANNOTATIONS_MARKER,
+} from "./default-labels";
+
+// ── Mock helpers ────────────────────────────────────────────────────
+
+function mockResource(
+  entityType: string,
+  props: Record<string, unknown>,
+): any {
+  return {
+    [DECLARABLE_MARKER]: true,
+    lexicon: "k8s",
+    entityType,
+    kind: "resource",
+    props,
+  };
+}
+
+function mockProperty(
+  entityType: string,
+  props: Record<string, unknown>,
+): any {
+  return {
+    [DECLARABLE_MARKER]: true,
+    lexicon: "k8s",
+    entityType,
+    kind: "property",
+    props,
+  };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────
+
+describe("k8sSerializer", () => {
+  test("name is k8s", () => {
+    expect(k8sSerializer.name).toBe("k8s");
+  });
+
+  test("rulePrefix is WK8", () => {
+    expect(k8sSerializer.rulePrefix).toBe("WK8");
+  });
+
+  test("empty entities produce empty string", () => {
+    const result = k8sSerializer.serialize(new Map());
+    expect(result).toBe("");
+  });
+
+  test("single Deployment produces valid YAML with apiVersion/kind/metadata/spec", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "myApp",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "my-app", labels: { app: "my-app" } },
+        spec: { replicas: 2 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("apiVersion:");
+    expect(result).toContain("kind: Deployment");
+    expect(result).toContain("name: my-app");
+    expect(result).toContain("replicas: 2");
+  });
+
+  test("metadata.name auto-generated from logical name (camelCase→kebab-case)", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "myWebApp",
+      mockResource("K8s::Apps::Deployment", {
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("name: my-web-app");
+  });
+
+  test("explicit metadata.name preserved", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "myApp",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "custom-name" },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("name: custom-name");
+  });
+
+  test("ConfigMap uses top-level data (specless type)", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "config",
+      mockResource("K8s::Core::ConfigMap", {
+        metadata: { name: "app-config" },
+        data: { DB_HOST: "localhost" },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: ConfigMap");
+    expect(result).toContain("DB_HOST: localhost");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("Secret uses top-level stringData (specless type)", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "secret",
+      mockResource("K8s::Core::Secret", {
+        metadata: { name: "app-secret" },
+        stringData: { API_KEY: "secret123" },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: Secret");
+    expect(result).toContain("API_KEY: secret123");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("Namespace is specless type", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "myNs",
+      mockResource("K8s::Core::Namespace", {
+        metadata: { name: "my-namespace" },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: Namespace");
+    expect(result).toContain("name: my-namespace");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("multi-resource entities joined by ---", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app" },
+        spec: { replicas: 1 },
+      }),
+    );
+    entities.set(
+      "svc",
+      mockResource("K8s::Core::Service", {
+        metadata: { name: "app" },
+        spec: { ports: [{ port: 80 }] },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("---");
+    expect(result).toContain("kind: Deployment");
+    expect(result).toContain("kind: Service");
+  });
+
+  test("default labels merged into metadata.labels", () => {
+    const entities = new Map<string, any>();
+    entities.set("labels", defaultLabels({ env: "prod" }));
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app" },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("env: prod");
+  });
+
+  test("default annotations merged into metadata.annotations", () => {
+    const entities = new Map<string, any>();
+    entities.set("annot", defaultAnnotations({ "note": "hello" }));
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app" },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("note: hello");
+  });
+
+  test("explicit labels override default labels", () => {
+    const entities = new Map<string, any>();
+    entities.set("labels", defaultLabels({ env: "dev" }));
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app", labels: { env: "prod" } },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("env: prod");
+    // Should not contain "dev" since explicit overrides
+    const envLines = result.split("\n").filter((l: string) => l.includes("env:"));
+    expect(envLines.every((l: string) => !l.includes("dev"))).toBe(true);
+  });
+
+  test("property entities skipped in output", () => {
+    const entities = new Map<string, any>();
+    entities.set("container", mockProperty("K8s::Core::Container", { name: "app" }));
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app" },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: Deployment");
+    // Only one document — property entities should not appear as separate docs
+    expect(result.split("---").length).toBeLessThanOrEqual(2);
+  });
+
+  test("DefaultLabels entities skipped in output", () => {
+    const entities = new Map<string, any>();
+    entities.set("labels", defaultLabels({ env: "prod" }));
+
+    const result = k8sSerializer.serialize(entities);
+    // defaultLabels alone should not produce any output
+    expect(result).toBe("");
+  });
+
+  test("DefaultAnnotations entities skipped in output", () => {
+    const entities = new Map<string, any>();
+    entities.set("annotations", defaultAnnotations({ note: "hi" }));
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toBe("");
+  });
+
+  test("key ordering: apiVersion, kind, metadata, spec, then rest", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app" },
+        spec: { replicas: 1 },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    const lines = result.split("\n");
+    const keyLines = lines.filter((l: string) => /^\w+:/.test(l));
+    const keys = keyLines.map((l: string) => l.split(":")[0]);
+
+    const apiIdx = keys.indexOf("apiVersion");
+    const kindIdx = keys.indexOf("kind");
+    const metaIdx = keys.indexOf("metadata");
+    const specIdx = keys.indexOf("spec");
+
+    expect(apiIdx).toBeLessThan(kindIdx);
+    expect(kindIdx).toBeLessThan(metaIdx);
+    expect(metaIdx).toBeLessThan(specIdx);
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,278 @@
+/**
+ * Kubernetes YAML serializer.
+ *
+ * Converts Chant declarables to multi-document K8s YAML output with
+ * apiVersion, kind, metadata, and spec structure.
+ */
+
+import { createRequire } from "module";
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { emitYAML } from "@intentius/chant/yaml";
+import { isDefaultLabels, isDefaultAnnotations, type DefaultLabels, type DefaultAnnotations } from "./default-labels";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * K8s resource kinds whose properties live directly on the manifest
+ * (not nested under `spec`). These types use `data`, `stringData`,
+ * or have no spec field at all.
+ */
+const SPECLESS_TYPES = new Set([
+  "ConfigMap",
+  "Secret",
+  "Namespace",
+  "ServiceAccount",
+]);
+
+/**
+ * GVK mapping entry — loaded from generated lexicon-k8s.json.
+ */
+interface GVKEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  apiVersion?: string;
+  gvkKind?: string;
+}
+
+let cachedGVKMap: Record<string, GVKEntry> | null = null;
+
+function getGVKMap(): Record<string, GVKEntry> {
+  if (cachedGVKMap) return cachedGVKMap;
+  try {
+    cachedGVKMap = require("./generated/lexicon-k8s.json") as Record<string, GVKEntry>;
+  } catch {
+    cachedGVKMap = {};
+  }
+  return cachedGVKMap!;
+}
+
+/**
+ * Resolve entityType to apiVersion and kind.
+ */
+function resolveGVK(entityType: string): { apiVersion: string; kind: string } | null {
+  const gvkMap = getGVKMap();
+
+  // Search for matching entry by resourceType
+  for (const entry of Object.values(gvkMap)) {
+    if (entry.resourceType === entityType && entry.apiVersion && entry.gvkKind) {
+      return { apiVersion: entry.apiVersion, kind: entry.gvkKind };
+    }
+  }
+
+  // Fallback: derive from entity type string (K8s::Group::Kind → group/v1, Kind)
+  return deriveGVKFromType(entityType);
+}
+
+/**
+ * Well-known K8s API group → apiVersion mappings for fallback when
+ * the generated lexicon JSON is not available.
+ */
+const API_GROUP_VERSIONS: Record<string, string> = {
+  Core: "v1",
+  Apps: "apps/v1",
+  Batch: "batch/v1",
+  Networking: "networking.k8s.io/v1",
+  Policy: "policy/v1",
+  Rbac: "rbac.authorization.k8s.io/v1",
+  Storage: "storage.k8s.io/v1",
+  Autoscaling: "autoscaling/v2",
+  Admissionregistration: "admissionregistration.k8s.io/v1",
+};
+
+function deriveGVKFromType(entityType: string): { apiVersion: string; kind: string } | null {
+  // Format: K8s::Group::Kind
+  const parts = entityType.split("::");
+  if (parts.length !== 3 || parts[0] !== "K8s") return null;
+
+  const group = parts[1];
+  const kind = parts[2];
+  const apiVersion = API_GROUP_VERSIONS[group];
+
+  if (!apiVersion) return null;
+  return { apiVersion, kind };
+}
+
+/**
+ * K8s visitor for the generic serializer walker.
+ */
+function k8sVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
+  return {
+    attrRef: (name, attr) => {
+      // For K8s, attribute references typically resolve to metadata.name
+      if (attr === "name") return name;
+      return name;
+    },
+    resourceRef: (name) => name,
+    propertyDeclarable: (entity, walk) => {
+      if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
+        return undefined;
+      }
+      const props = entity.props as Record<string, unknown>;
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) {
+          result[key] = walk(value);
+        }
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    },
+  };
+}
+
+/**
+ * Convert a value to YAML-compatible form using the walker.
+ */
+function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unknown {
+  return walkValue(value, entityNames, k8sVisitor(entityNames));
+}
+
+/**
+ * Kubernetes YAML serializer implementation.
+ */
+export const k8sSerializer: Serializer = {
+  name: "k8s",
+  rulePrefix: "WK8",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string {
+    // Build reverse map: entity → name
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) {
+      entityNames.set(entity, name);
+    }
+
+    // Collect default labels and annotations
+    let defaultLabelEntries: Record<string, unknown> = {};
+    let defaultAnnotationEntries: Record<string, unknown> = {};
+
+    for (const [, entity] of entities) {
+      if (isDefaultLabels(entity)) {
+        defaultLabelEntries = { ...defaultLabelEntries, ...(entity as DefaultLabels).labels };
+      }
+      if (isDefaultAnnotations(entity)) {
+        defaultAnnotationEntries = { ...defaultAnnotationEntries, ...(entity as DefaultAnnotations).annotations };
+      }
+    }
+
+    const documents: string[] = [];
+
+    for (const [name, entity] of entities) {
+      if (isPropertyDeclarable(entity)) continue;
+      if (isDefaultLabels(entity) || isDefaultAnnotations(entity)) continue;
+
+      const entityType = (entity as unknown as Record<string, unknown>).entityType as string;
+      const gvk = resolveGVK(entityType);
+      if (!gvk) continue;
+
+      const props = toYAMLValue(
+        (entity as unknown as Record<string, unknown>).props,
+        entityNames,
+      ) as Record<string, unknown> | undefined;
+
+      if (!props) continue;
+
+      // Build the K8s manifest structure
+      const manifest: Record<string, unknown> = {
+        apiVersion: gvk.apiVersion,
+        kind: gvk.kind,
+      };
+
+      // Build metadata
+      const metadata: Record<string, unknown> = props.metadata as Record<string, unknown> ?? {};
+      if (!metadata.name) {
+        // Use the logical name as the resource name (kebab-case)
+        metadata.name = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+      }
+
+      // Merge default labels
+      if (Object.keys(defaultLabelEntries).length > 0) {
+        const existingLabels = (metadata.labels ?? {}) as Record<string, unknown>;
+        metadata.labels = { ...defaultLabelEntries, ...existingLabels };
+      }
+
+      // Merge default annotations
+      if (Object.keys(defaultAnnotationEntries).length > 0) {
+        const existingAnnotations = (metadata.annotations ?? {}) as Record<string, unknown>;
+        metadata.annotations = { ...defaultAnnotationEntries, ...existingAnnotations };
+      }
+
+      manifest.metadata = metadata;
+
+      // The remaining properties go under spec (or directly on the manifest for certain types)
+      if (SPECLESS_TYPES.has(gvk.kind)) {
+        // These types have their data directly on the manifest (data, stringData, etc.)
+        for (const [key, value] of Object.entries(props)) {
+          if (key !== "metadata") {
+            manifest[key] = value;
+          }
+        }
+      } else if (props.spec !== undefined) {
+        // If spec is already set, use it directly
+        manifest.spec = props.spec;
+        for (const [key, value] of Object.entries(props)) {
+          if (key !== "metadata" && key !== "spec") {
+            manifest[key] = value;
+          }
+        }
+      } else {
+        // Place remaining props under spec
+        const spec: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(props)) {
+          if (key !== "metadata") {
+            spec[key] = value;
+          }
+        }
+        if (Object.keys(spec).length > 0) {
+          manifest.spec = spec;
+        }
+      }
+
+      // Emit as YAML
+      const yamlDoc = emitK8sManifest(manifest);
+      documents.push(yamlDoc);
+    }
+
+    return documents.join("\n---\n");
+  },
+};
+
+/**
+ * Emit a K8s manifest object as YAML.
+ * Preserves key ordering: apiVersion, kind, metadata, spec, then rest.
+ */
+/**
+ * Emit a key-value pair as YAML. Scalars get ` value` suffix; objects get
+ * block-style indented below the key.
+ */
+function emitKeyValue(key: string, value: unknown): string {
+  const yamlStr = emitYAML(value, 1);
+  // If the YAML starts with a newline, it's a block value (object/array)
+  if (yamlStr.startsWith("\n")) {
+    return `${key}:${yamlStr}`;
+  }
+  return `${key}: ${yamlStr}`;
+}
+
+function emitK8sManifest(manifest: Record<string, unknown>): string {
+  const orderedKeys = ["apiVersion", "kind", "metadata", "spec"];
+  const lines: string[] = [];
+
+  // Emit ordered keys first
+  for (const key of orderedKeys) {
+    if (manifest[key] !== undefined) {
+      lines.push(emitKeyValue(key, manifest[key]));
+    }
+  }
+
+  // Emit remaining keys
+  for (const [key, value] of Object.entries(manifest)) {
+    if (!orderedKeys.includes(key) && value !== undefined) {
+      lines.push(emitKeyValue(key, value));
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}

package/src/spec/fetch.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from "bun:test";
+import { fetchK8sSchema, fetchSchemas, K8S_SCHEMA_VERSION } from "./fetch";
+
+describe("fetch", () => {
+  test("fetchK8sSchema function exists", () => {
+    expect(typeof fetchK8sSchema).toBe("function");
+  });
+
+  test("fetchSchemas function exists", () => {
+    expect(typeof fetchSchemas).toBe("function");
+  });
+
+  test("K8S_SCHEMA_VERSION is defined", () => {
+    expect(typeof K8S_SCHEMA_VERSION).toBe("string");
+    expect(K8S_SCHEMA_VERSION).toMatch(/^v\d+\.\d+\.\d+$/);
+  });
+
+  test.skip("integration: fetchK8sSchema returns Buffer (requires network)", async () => {
+    const data = await fetchK8sSchema();
+    expect(data).toBeInstanceOf(Buffer);
+    const parsed = JSON.parse(data.toString("utf-8"));
+    expect(parsed.definitions).toBeDefined();
+  });
+});

package/src/spec/fetch.ts

@@ -0,0 +1,68 @@
+/**
+ * Kubernetes OpenAPI schema fetching — downloads the Swagger 2.0 spec
+ * and caches it locally.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Pinned Kubernetes version for schema download.
+ */
+export const K8S_SCHEMA_VERSION = "v1.32.0";
+
+/**
+ * Build the schema URL for a given version.
+ */
+function schemaUrl(version: string): string {
+  return `https://raw.githubusercontent.com/kubernetes/kubernetes/${version}/api/openapi-spec/swagger.json`;
+}
+
+/**
+ * Get the cache file path for the K8s schema.
+ */
+export function getCachePath(version?: string): string {
+  const ref = version ?? K8S_SCHEMA_VERSION;
+  return join(homedir(), ".chant", `k8s-swagger-${ref}.json`);
+}
+
+/**
+ * Fetch the Kubernetes OpenAPI Swagger spec, returning the raw JSON buffer.
+ * Uses local file caching with 24-hour TTL.
+ *
+ * @param force  Bypass cache and download fresh.
+ * @param version  Kubernetes version tag. Defaults to {@link K8S_SCHEMA_VERSION}.
+ */
+export async function fetchK8sSchema(force?: boolean, version?: string): Promise<Buffer> {
+  const ref = version ?? K8S_SCHEMA_VERSION;
+  return fetchWithCache(
+    {
+      url: schemaUrl(ref),
+      cacheFile: getCachePath(ref),
+    },
+    force,
+  );
+}
+
+/**
+ * Fetch the K8s schema and return it as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * The K8s schema is a single document, so we return a single entry
+ * keyed by "Kubernetes::OpenAPI" — the parse step will split it
+ * into multiple resources.
+ */
+export async function fetchSchemas(force?: boolean, version?: string): Promise<Map<string, Buffer>> {
+  const data = await fetchK8sSchema(force, version);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("Kubernetes::OpenAPI", data);
+  return schemas;
+}
+
+/**
+ * Clear the cached schema file.
+ */
+export function clearCache(version?: string): void {
+  clearCacheFile(getCachePath(version));
+}