@intentius/chant-lexicon-k8s 0.0.12

package/src/import/parser.ts

@@ -0,0 +1,204 @@
+/**
+ * Kubernetes YAML parser for `chant import`.
+ *
+ * Parses Kubernetes manifests (single or multi-document YAML) into the core
+ * TemplateIR format, mapping K8s resources to the K8s::{Group}::{Kind} type
+ * convention.
+ */
+
+import type { TemplateParser, TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
+import { parseYAML } from "@intentius/chant/yaml";
+
+// ── GVK to type name mapping ───────────────────────────────────────
+
+/**
+ * Well-known kind+apiVersion pairs mapped to K8s type names.
+ * Key format: "apiVersion/kind" (core group uses just "kind").
+ */
+const GVK_TYPE_MAP: Record<string, string> = {
+  // Core (v1)
+  "v1/Pod": "K8s::Core::Pod",
+  "v1/Service": "K8s::Core::Service",
+  "v1/ConfigMap": "K8s::Core::ConfigMap",
+  "v1/Secret": "K8s::Core::Secret",
+  "v1/Namespace": "K8s::Core::Namespace",
+  "v1/ServiceAccount": "K8s::Core::ServiceAccount",
+  "v1/PersistentVolume": "K8s::Core::PersistentVolume",
+  "v1/PersistentVolumeClaim": "K8s::Core::PersistentVolumeClaim",
+  "v1/Endpoints": "K8s::Core::Endpoints",
+  "v1/LimitRange": "K8s::Core::LimitRange",
+  "v1/ResourceQuota": "K8s::Core::ResourceQuota",
+
+  // Apps (apps/v1)
+  "apps/v1/Deployment": "K8s::Apps::Deployment",
+  "apps/v1/StatefulSet": "K8s::Apps::StatefulSet",
+  "apps/v1/DaemonSet": "K8s::Apps::DaemonSet",
+  "apps/v1/ReplicaSet": "K8s::Apps::ReplicaSet",
+
+  // Batch (batch/v1)
+  "batch/v1/Job": "K8s::Batch::Job",
+  "batch/v1/CronJob": "K8s::Batch::CronJob",
+
+  // Networking (networking.k8s.io/v1)
+  "networking.k8s.io/v1/Ingress": "K8s::Networking::Ingress",
+  "networking.k8s.io/v1/NetworkPolicy": "K8s::Networking::NetworkPolicy",
+  "networking.k8s.io/v1/IngressClass": "K8s::Networking::IngressClass",
+
+  // RBAC (rbac.authorization.k8s.io/v1)
+  "rbac.authorization.k8s.io/v1/Role": "K8s::Rbac::Role",
+  "rbac.authorization.k8s.io/v1/ClusterRole": "K8s::Rbac::ClusterRole",
+  "rbac.authorization.k8s.io/v1/RoleBinding": "K8s::Rbac::RoleBinding",
+  "rbac.authorization.k8s.io/v1/ClusterRoleBinding": "K8s::Rbac::ClusterRoleBinding",
+
+  // Autoscaling (autoscaling/v2)
+  "autoscaling/v2/HorizontalPodAutoscaler": "K8s::Autoscaling::HorizontalPodAutoscaler",
+  "autoscaling/v1/HorizontalPodAutoscaler": "K8s::Autoscaling::HorizontalPodAutoscaler",
+
+  // Policy (policy/v1)
+  "policy/v1/PodDisruptionBudget": "K8s::Policy::PodDisruptionBudget",
+
+  // Storage (storage.k8s.io/v1)
+  "storage.k8s.io/v1/StorageClass": "K8s::Storage::StorageClass",
+
+  // Certificates (certificates.k8s.io/v1)
+  "certificates.k8s.io/v1/CertificateSigningRequest": "K8s::Certificates::CertificateSigningRequest",
+
+  // Coordination (coordination.k8s.io/v1)
+  "coordination.k8s.io/v1/Lease": "K8s::Coordination::Lease",
+
+  // Discovery (discovery.k8s.io/v1)
+  "discovery.k8s.io/v1/EndpointSlice": "K8s::Discovery::EndpointSlice",
+};
+
+/**
+ * Resolve apiVersion + kind to a K8s type name.
+ * Falls back to constructing from the apiVersion group.
+ */
+function resolveTypeName(apiVersion: string, kind: string): string {
+  // Try exact match
+  const key = `${apiVersion}/${kind}`;
+  if (GVK_TYPE_MAP[key]) return GVK_TYPE_MAP[key];
+
+  // Core group uses just kind
+  if (apiVersion === "v1") {
+    const coreKey = `v1/${kind}`;
+    if (GVK_TYPE_MAP[coreKey]) return GVK_TYPE_MAP[coreKey];
+  }
+
+  // Construct from apiVersion group
+  const group = apiVersionToGroup(apiVersion);
+  return `K8s::${group}::${kind}`;
+}
+
+/**
+ * Extract PascalCase group name from an apiVersion string.
+ * "apps/v1" → "Apps"
+ * "v1" → "Core"
+ * "networking.k8s.io/v1" → "Networking"
+ * "rbac.authorization.k8s.io/v1" → "Rbac"
+ */
+function apiVersionToGroup(apiVersion: string): string {
+  const slashIdx = apiVersion.indexOf("/");
+  if (slashIdx === -1) return "Core"; // core group (v1)
+
+  const groupStr = apiVersion.slice(0, slashIdx);
+  const firstSegment = groupStr.split(".")[0];
+  if (firstSegment === "rbac") return "Rbac";
+  return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
+}
+
+/**
+ * Convert a K8s object name to a camelCase logical identifier.
+ * Combines kind (lowercased first char) with the object name (PascalCased).
+ *
+ * E.g., kind="Deployment", name="my-app" → "deploymentMyApp"
+ */
+function toLogicalId(kind: string, name: string | undefined): string {
+  const prefix = kind.charAt(0).toLowerCase() + kind.slice(1);
+  if (!name) return prefix;
+
+  const pascalName = name
+    .split(/[-_.]/)
+    .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+    .join("");
+  return `${prefix}${pascalName}`;
+}
+
+// ── Parser ──────────────────────────────────────────────────────────
+
+/**
+ * Kubernetes YAML parser implementation.
+ *
+ * Supports multi-document YAML (split on `---`). Each document is expected
+ * to be a standard Kubernetes object with apiVersion, kind, and metadata.
+ */
+export class K8sParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const resources: ResourceIR[] = [];
+    const namespaces = new Set<string>();
+
+    // Split on YAML document separator, filter blanks
+    const documents = content
+      .split(/^---\s*$/m)
+      .map((d) => d.trim())
+      .filter((d) => d.length > 0 && !/^[\s#]*$/.test(d.replace(/#[^\n]*/g, "")));
+
+    for (const docStr of documents) {
+      const doc = parseYAML(docStr);
+      if (!doc || typeof doc !== "object") continue;
+
+      const resource = this.parseDocument(doc as Record<string, unknown>);
+      if (resource) {
+        resources.push(resource);
+
+        // Track namespaces
+        const ns = (doc as Record<string, unknown>).metadata as Record<string, unknown> | undefined;
+        if (ns?.namespace && typeof ns.namespace === "string") {
+          namespaces.add(ns.namespace);
+        }
+      }
+    }
+
+    const metadata: Record<string, unknown> = {};
+    if (namespaces.size > 0) {
+      metadata.namespaces = [...namespaces];
+    }
+
+    return {
+      resources,
+      parameters: [],
+      metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    };
+  }
+
+  private parseDocument(doc: Record<string, unknown>): ResourceIR | null {
+    const apiVersion = doc.apiVersion as string | undefined;
+    const kind = doc.kind as string | undefined;
+
+    if (!apiVersion || !kind) return null;
+
+    const metadata = (doc.metadata ?? {}) as Record<string, unknown>;
+    const name = metadata.name as string | undefined;
+    const type = resolveTypeName(apiVersion, kind);
+    const logicalId = toLogicalId(kind, name);
+
+    // Extract the user-configurable properties (skip apiVersion, kind)
+    const properties: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(doc)) {
+      if (key === "apiVersion" || key === "kind") continue;
+      properties[key] = value;
+    }
+
+    return {
+      logicalId,
+      type,
+      properties,
+      metadata: {
+        originalName: name,
+        apiVersion,
+        kind,
+        ...(metadata.namespace ? { namespace: metadata.namespace as string } : {}),
+      },
+    };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { K8sParser } from "./parser";
+import { K8sGenerator } from "./generator";
+
+const testdataDir = join(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+  "testdata",
+  "manifests",
+);
+
+const parser = new K8sParser();
+const generator = new K8sGenerator();
+
+describe("roundtrip: parse YAML → generate TypeScript", () => {
+  test("Deployment roundtrip", () => {
+    const yaml = readFileSync(join(testdataDir, "deployment.yaml"), "utf-8");
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+
+    expect(files.length).toBe(1);
+    expect(files[0].content).toContain("new Deployment");
+    expect(files[0].content).toContain("nginx");
+  });
+
+  test("multi-doc full-app roundtrip", () => {
+    const yaml = readFileSync(join(testdataDir, "full-app.yaml"), "utf-8");
+    const ir = parser.parse(yaml);
+    expect(ir.resources.length).toBe(4); // Deployment + Service + Ingress + ConfigMap
+
+    const files = generator.generate(ir);
+    expect(files[0].content).toContain("Deployment");
+    expect(files[0].content).toContain("Service");
+    expect(files[0].content).toContain("Ingress");
+    expect(files[0].content).toContain("ConfigMap");
+  });
+
+  test("Service roundtrip preserves port info", () => {
+    const yaml = readFileSync(join(testdataDir, "service.yaml"), "utf-8");
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+
+    expect(files[0].content).toContain("new Service");
+    expect(files[0].content).toContain("80");
+  });
+
+  test("ConfigMap roundtrip preserves data", () => {
+    const yaml = readFileSync(join(testdataDir, "configmap.yaml"), "utf-8");
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+
+    expect(files[0].content).toContain("ConfigMap");
+    expect(files[0].content).toContain("DATABASE_URL");
+  });
+
+  test("inline YAML roundtrip", () => {
+    const yaml = `
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: test-app
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: test
+  template:
+    metadata:
+      labels:
+        app: test
+    spec:
+      containers:
+        - name: test
+          image: test:1.0
+          ports:
+            - containerPort: 8080
+`;
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+
+    expect(files[0].content).toContain("new Deployment");
+    expect(files[0].content).toContain("export const");
+  });
+});

package/src/index.ts

@@ -0,0 +1,38 @@
+// Serializer
+export { k8sSerializer } from "./serializer";
+
+// Plugin
+export { k8sPlugin } from "./plugin";
+
+// Default labels & annotations
+export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotations } from "./default-labels";
+export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-labels";
+
+// Variables / label constants
+export { K8sLabels, K8sAnnotations } from "./variables";
+
+// Generated entities — export everything from generated index
+// After running `chant generate`, this re-exports all K8s resource classes
+export * from "./generated/index";
+
+// Composites
+export { WebApp, StatefulApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent } from "./composites/index";
+export type { WebAppProps, WebAppResult, StatefulAppProps, StatefulAppResult, CronWorkloadProps, CronWorkloadResult, AutoscaledServiceProps, AutoscaledServiceResult, WorkerPoolProps, WorkerPoolResult, NamespaceEnvProps, NamespaceEnvResult, NodeAgentProps, NodeAgentResult } from "./composites/index";
+
+// RBAC verb constants
+export * from "./actions/index";
+
+// Spec utilities (for tooling)
+export { fetchK8sSchema, fetchSchemas, K8S_SCHEMA_VERSION } from "./spec/fetch";
+export { parseK8sSwagger, k8sShortName, k8sServiceName, gvkToTypeName, gvkToApiVersion } from "./spec/parse";
+export type { K8sParseResult, ParsedResource, ParsedProperty, ParsedPropertyType, ParsedEnum, GroupVersionKind } from "./spec/parse";
+
+// Code generation pipeline
+export { generate, writeGeneratedFiles } from "./codegen/generate";
+export { packageLexicon } from "./codegen/package";
+export type { PackageOptions, PackageResult } from "./codegen/package";
+
+// CRD framework
+export type { CRDSource, CRDSpec } from "./crd/types";
+export { parseCRD, parseCRDSpec } from "./crd/parser";
+export { loadCRDs, loadMultipleCRDs } from "./crd/loader";

package/src/lint/post-synth/k8s-helpers.test.ts

@@ -0,0 +1,219 @@
+import { describe, test, expect } from "bun:test";
+import {
+  parseK8sManifests,
+  extractContainers,
+  extractPodSpec,
+  WORKLOAD_KINDS,
+} from "./k8s-helpers";
+
+describe("parseK8sManifests", () => {
+  test("splits multi-doc YAML", () => {
+    const yaml = `
+apiVersion: v1
+kind: Service
+metadata:
+  name: svc
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+`;
+    const manifests = parseK8sManifests(yaml);
+    expect(manifests.length).toBe(2);
+    expect(manifests[0].kind).toBe("Service");
+    expect(manifests[1].kind).toBe("Deployment");
+  });
+
+  test("handles single document", () => {
+    const yaml = `
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: config
+data:
+  key: value
+`;
+    const manifests = parseK8sManifests(yaml);
+    expect(manifests.length).toBe(1);
+    expect(manifests[0].kind).toBe("ConfigMap");
+  });
+
+  test("handles empty/invalid YAML gracefully", () => {
+    expect(parseK8sManifests("")).toEqual([]);
+    expect(parseK8sManifests("---")).toEqual([]);
+    // "---\n---" doesn't split on /\n---\n/ — the full string is parsed as empty object
+    expect(parseK8sManifests("---\n---\n")).toEqual([]);
+  });
+
+  test("skips blank documents between separators", () => {
+    const yaml = `
+apiVersion: v1
+kind: Pod
+metadata:
+  name: p
+---
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: s
+`;
+    const manifests = parseK8sManifests(yaml);
+    expect(manifests.length).toBe(2);
+  });
+});
+
+describe("extractContainers", () => {
+  test("extracts from Deployment", () => {
+    const manifest = {
+      kind: "Deployment",
+      spec: {
+        template: {
+          spec: {
+            containers: [{ name: "app", image: "nginx" }],
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+    expect(containers[0].name).toBe("app");
+  });
+
+  test("extracts from Pod", () => {
+    const manifest = {
+      kind: "Pod",
+      spec: {
+        containers: [{ name: "app", image: "nginx" }],
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+  });
+
+  test("extracts from StatefulSet", () => {
+    const manifest = {
+      kind: "StatefulSet",
+      spec: {
+        template: {
+          spec: {
+            containers: [{ name: "db", image: "postgres" }],
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+  });
+
+  test("extracts from DaemonSet", () => {
+    const manifest = {
+      kind: "DaemonSet",
+      spec: {
+        template: {
+          spec: {
+            containers: [{ name: "agent", image: "fluentd" }],
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+  });
+
+  test("extracts from Job", () => {
+    const manifest = {
+      kind: "Job",
+      spec: {
+        template: {
+          spec: {
+            containers: [{ name: "worker", image: "job:1.0" }],
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+  });
+
+  test("extracts from CronJob", () => {
+    const manifest = {
+      kind: "CronJob",
+      spec: {
+        jobTemplate: {
+          spec: {
+            template: {
+              spec: {
+                containers: [{ name: "cron", image: "cron:1.0" }],
+              },
+            },
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(1);
+  });
+
+  test("includes init containers", () => {
+    const manifest = {
+      kind: "Deployment",
+      spec: {
+        template: {
+          spec: {
+            containers: [{ name: "app", image: "nginx" }],
+            initContainers: [{ name: "init", image: "busybox" }],
+          },
+        },
+      },
+    };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(2);
+  });
+
+  test("returns empty for non-workload types", () => {
+    const manifest = { kind: "ConfigMap", data: {} };
+    const containers = extractContainers(manifest);
+    expect(containers.length).toBe(0);
+  });
+});
+
+describe("extractPodSpec", () => {
+  test("returns spec for Pod", () => {
+    const manifest = {
+      kind: "Pod",
+      spec: { containers: [{ name: "app" }] },
+    };
+    const podSpec = extractPodSpec(manifest);
+    expect(podSpec).toBeDefined();
+    expect(podSpec!.containers).toBeDefined();
+  });
+
+  test("returns null for ConfigMap", () => {
+    const manifest = { kind: "ConfigMap", data: {} };
+    expect(extractPodSpec(manifest)).toBeNull();
+  });
+
+  test("returns null when no spec", () => {
+    const manifest = { kind: "Deployment" };
+    expect(extractPodSpec(manifest)).toBeNull();
+  });
+});
+
+describe("WORKLOAD_KINDS", () => {
+  test("includes all expected kinds", () => {
+    expect(WORKLOAD_KINDS.has("Pod")).toBe(true);
+    expect(WORKLOAD_KINDS.has("Deployment")).toBe(true);
+    expect(WORKLOAD_KINDS.has("StatefulSet")).toBe(true);
+    expect(WORKLOAD_KINDS.has("DaemonSet")).toBe(true);
+    expect(WORKLOAD_KINDS.has("Job")).toBe(true);
+    expect(WORKLOAD_KINDS.has("CronJob")).toBe(true);
+  });
+
+  test("does not include non-workload kinds", () => {
+    expect(WORKLOAD_KINDS.has("Service")).toBe(false);
+    expect(WORKLOAD_KINDS.has("ConfigMap")).toBe(false);
+  });
+});

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

@@ -0,0 +1,149 @@
+/**
+ * Shared helpers for Kubernetes post-synthesis lint rules.
+ *
+ * Provides YAML parsing for multi-document K8s manifests and container
+ * extraction logic that handles all common workload types.
+ */
+
+import { parseYAML } from "@intentius/chant/yaml";
+export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+/**
+ * A parsed Kubernetes manifest (loosely typed).
+ */
+export interface K8sManifest {
+  apiVersion?: string;
+  kind?: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  spec?: Record<string, unknown>;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * A Kubernetes container spec (loosely typed).
+ */
+export interface K8sContainer {
+  name?: string;
+  image?: string;
+  env?: Array<{ name?: string; value?: unknown; valueFrom?: unknown }>;
+  ports?: Array<{ name?: string; containerPort?: number; [key: string]: unknown }>;
+  resources?: {
+    limits?: Record<string, unknown>;
+    requests?: Record<string, unknown>;
+  };
+  securityContext?: Record<string, unknown>;
+  livenessProbe?: unknown;
+  readinessProbe?: unknown;
+  imagePullPolicy?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Split a multi-document YAML string on `---` boundaries and parse each
+ * document into a K8sManifest.
+ */
+export function parseK8sManifests(yaml: string): K8sManifest[] {
+  const documents = yaml.split(/\n---\n/);
+  const manifests: K8sManifest[] = [];
+
+  for (const doc of documents) {
+    const trimmed = doc.trim();
+    if (trimmed === "" || trimmed === "---") continue;
+    try {
+      const parsed = parseYAML(trimmed);
+      if (typeof parsed === "object" && parsed !== null) {
+        manifests.push(parsed as K8sManifest);
+      }
+    } catch {
+      // Skip unparseable documents
+    }
+  }
+
+  return manifests;
+}
+
+/**
+ * Extract the pod spec from any workload manifest.
+ *
+ * Handles:
+ * - Pod: spec directly
+ * - Deployment, StatefulSet, DaemonSet: spec.template.spec
+ * - Job: spec.template.spec
+ * - CronJob: spec.jobTemplate.spec.template.spec
+ */
+export function extractPodSpec(
+  manifest: K8sManifest,
+): Record<string, unknown> | null {
+  const kind = manifest.kind;
+  const spec = manifest.spec;
+  if (!spec) return null;
+
+  switch (kind) {
+    case "Pod":
+      return spec as Record<string, unknown>;
+
+    case "Deployment":
+    case "StatefulSet":
+    case "DaemonSet":
+    case "Job": {
+      const template = spec.template as Record<string, unknown> | undefined;
+      return (template?.spec as Record<string, unknown>) ?? null;
+    }
+
+    case "CronJob": {
+      const jobTemplate = spec.jobTemplate as Record<string, unknown> | undefined;
+      const jobSpec = jobTemplate?.spec as Record<string, unknown> | undefined;
+      const template = jobSpec?.template as Record<string, unknown> | undefined;
+      return (template?.spec as Record<string, unknown>) ?? null;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Extract all containers (including init containers) from a workload manifest.
+ */
+export function extractContainers(manifest: K8sManifest): K8sContainer[] {
+  const podSpec = extractPodSpec(manifest);
+  if (!podSpec) return [];
+
+  const containers: K8sContainer[] = [];
+
+  if (Array.isArray(podSpec.containers)) {
+    for (const c of podSpec.containers) {
+      if (typeof c === "object" && c !== null) {
+        containers.push(c as K8sContainer);
+      }
+    }
+  }
+
+  if (Array.isArray(podSpec.initContainers)) {
+    for (const c of podSpec.initContainers) {
+      if (typeof c === "object" && c !== null) {
+        containers.push(c as K8sContainer);
+      }
+    }
+  }
+
+  return containers;
+}
+
+/**
+ * Workload kinds that contain pod templates.
+ */
+export const WORKLOAD_KINDS = new Set([
+  "Pod",
+  "Deployment",
+  "StatefulSet",
+  "DaemonSet",
+  "Job",
+  "CronJob",
+]);