@intentius/chant-lexicon-k8s 0.0.12

package/src/composites/web-app.ts

@@ -0,0 +1,180 @@
+/**
+ * WebApp composite — Deployment + Service + optional Ingress.
+ *
+ * A higher-level construct for deploying stateless web applications
+ * with common defaults (health probes, resource limits, labels).
+ */
+
+export interface WebAppProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image (e.g., "nginx:1.25"). */
+  image: string;
+  /** Container port (default: 80). */
+  port?: number;
+  /** Number of replicas (default: 2). */
+  replicas?: number;
+  /** Ingress hostname — if set, creates an Ingress resource. */
+  ingressHost?: string;
+  /** Ingress TLS secret name — if set, enables TLS on the Ingress. */
+  ingressTlsSecret?: string;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit (e.g., "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (e.g., "256Mi"). */
+  memoryLimit?: string;
+  /** CPU request (e.g., "100m"). */
+  cpuRequest?: string;
+  /** Memory request (e.g., "128Mi"). */
+  memoryRequest?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface WebAppResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  ingress?: Record<string, unknown>;
+}
+
+/**
+ * Create a WebApp composite — returns declarable instances for
+ * a Deployment, Service, and optional Ingress.
+ *
+ * @example
+ * ```ts
+ * import { WebApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, ingress } = WebApp({
+ *   name: "my-app",
+ *   image: "my-app:1.0",
+ *   port: 8080,
+ *   replicas: 3,
+ *   ingressHost: "my-app.example.com",
+ * });
+ *
+ * export { deployment, service, ingress };
+ * ```
+ */
+export function WebApp(props: WebAppProps): WebAppResult {
+  const {
+    name,
+    image,
+    port = 80,
+    replicas = 2,
+    labels: extraLabels = {},
+    cpuLimit = "500m",
+    memoryLimit = "256Mi",
+    cpuRequest = "100m",
+    memoryRequest = "128Mi",
+    namespace,
+    env,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // We return plain objects that users pass to constructors.
+  // The actual resource instantiation happens in user code with the generated classes.
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          containers: [
+            {
+              name,
+              image,
+              ports: [{ containerPort: port, name: "http" }],
+              resources: {
+                limits: { cpu: cpuLimit, memory: memoryLimit },
+                requests: { cpu: cpuRequest, memory: memoryRequest },
+              },
+              livenessProbe: {
+                httpGet: { path: "/", port },
+                initialDelaySeconds: 10,
+                periodSeconds: 10,
+              },
+              readinessProbe: {
+                httpGet: { path: "/", port },
+                initialDelaySeconds: 5,
+                periodSeconds: 5,
+              },
+              ...(env && { env }),
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  const serviceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [{ port: 80, targetPort: port, protocol: "TCP", name: "http" }],
+      type: "ClusterIP",
+    },
+  };
+
+  const result: WebAppResult = {
+    deployment: deploymentProps,
+    service: serviceProps,
+  };
+
+  if (props.ingressHost) {
+    const ingressProps: Record<string, unknown> = {
+      metadata: {
+        name,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+      },
+      spec: {
+        rules: [
+          {
+            host: props.ingressHost,
+            http: {
+              paths: [
+                {
+                  path: "/",
+                  pathType: "Prefix",
+                  backend: {
+                    service: { name, port: { number: 80 } },
+                  },
+                },
+              ],
+            },
+          },
+        ],
+        ...(props.ingressTlsSecret && {
+          tls: [
+            {
+              hosts: [props.ingressHost],
+              secretName: props.ingressTlsSecret,
+            },
+          ],
+        }),
+      },
+    };
+    result.ingress = ingressProps;
+  }
+
+  return result;
+}

package/src/composites/worker-pool.ts

@@ -0,0 +1,230 @@
+/**
+ * WorkerPool composite — Deployment + ServiceAccount + Role + RoleBinding + optional ConfigMap + optional HPA.
+ *
+ * A higher-level construct for background queue workers (Sidekiq, Celery, Bull)
+ * that need RBAC for secrets/configmaps and optional autoscaling, but no Service.
+ */
+
+export interface WorkerPoolProps {
+  /** Worker name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Command to run in the container. */
+  command?: string[];
+  /** Arguments to the command. */
+  args?: string[];
+  /** Number of replicas (default: 1, ignored if autoscaling). */
+  replicas?: number;
+  /** Config data — creates a ConfigMap and injects via envFrom. */
+  config?: Record<string, string>;
+  /** RBAC rules for the service account. */
+  rbacRules?: Array<{
+    apiGroups: string[];
+    resources: string[];
+    verbs: string[];
+  }>;
+  /** Optional autoscaling — creates an HPA when provided. */
+  autoscaling?: {
+    minReplicas: number;
+    maxReplicas: number;
+    targetCPUPercent?: number;
+  };
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "128Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "256Mi"). */
+  memoryLimit?: string;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface WorkerPoolResult {
+  deployment: Record<string, unknown>;
+  serviceAccount?: Record<string, unknown>;
+  role?: Record<string, unknown>;
+  roleBinding?: Record<string, unknown>;
+  configMap?: Record<string, unknown>;
+  hpa?: Record<string, unknown>;
+}
+
+/**
+ * Create a WorkerPool composite — returns prop objects for
+ * a Deployment, ServiceAccount, Role, RoleBinding, optional ConfigMap, and optional HPA.
+ *
+ * @example
+ * ```ts
+ * import { WorkerPool } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, serviceAccount, role, roleBinding } = WorkerPool({
+ *   name: "email-worker",
+ *   image: "worker:1.0",
+ *   command: ["bundle", "exec", "sidekiq"],
+ *   config: { REDIS_URL: "redis://redis:6379" },
+ * });
+ * ```
+ */
+export function WorkerPool(props: WorkerPoolProps): WorkerPoolResult {
+  const {
+    name,
+    image,
+    command,
+    args,
+    replicas = 1,
+    config,
+    rbacRules,
+    autoscaling,
+    cpuRequest = "100m",
+    memoryRequest = "128Mi",
+    cpuLimit = "500m",
+    memoryLimit = "256Mi",
+    labels: extraLabels = {},
+    namespace,
+    env,
+  } = props;
+
+  const saName = `${name}-sa`;
+  const roleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+  const configMapName = `${name}-config`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // undefined → default RBAC rules; explicit [] → no RBAC resources
+  const createRbac = rbacRules === undefined || rbacRules.length > 0;
+  const effectiveRbacRules = rbacRules === undefined
+    ? [{ apiGroups: [""], resources: ["secrets", "configmaps"], verbs: ["get"] }]
+    : rbacRules;
+
+  const effectiveReplicas = autoscaling ? autoscaling.minReplicas : replicas;
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ...(command && { command }),
+    ...(args && { args }),
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+    },
+    ...(env && { env }),
+    ...(config && {
+      envFrom: [{ configMapRef: { name: configMapName } }],
+    }),
+  };
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+    },
+    spec: {
+      replicas: effectiveReplicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          ...(createRbac && { serviceAccountName: saName }),
+          containers: [container],
+        },
+      },
+    },
+  };
+
+  const result: WorkerPoolResult = {
+    deployment: deploymentProps,
+  };
+
+  if (createRbac) {
+    result.serviceAccount = {
+      metadata: {
+        name: saName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+      },
+    };
+
+    result.role = {
+      metadata: {
+        name: roleName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+      },
+      rules: effectiveRbacRules,
+    };
+
+    result.roleBinding = {
+      metadata: {
+        name: bindingName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+      },
+      roleRef: {
+        apiGroup: "rbac.authorization.k8s.io",
+        kind: "Role",
+        name: roleName,
+      },
+      subjects: [
+        {
+          kind: "ServiceAccount",
+          name: saName,
+          ...(namespace && { namespace }),
+        },
+      ],
+    };
+  }
+
+  if (config) {
+    result.configMap = {
+      metadata: {
+        name: configMapName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+      },
+      data: config,
+    };
+  }
+
+  if (autoscaling) {
+    const targetCPUPercent = autoscaling.targetCPUPercent ?? 70;
+    result.hpa = {
+      metadata: {
+        name,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "autoscaler" },
+      },
+      spec: {
+        scaleTargetRef: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          name,
+        },
+        minReplicas: autoscaling.minReplicas,
+        maxReplicas: autoscaling.maxReplicas,
+        metrics: [
+          {
+            type: "Resource",
+            resource: {
+              name: "cpu",
+              target: { type: "Utilization", averageUtilization: targetCPUPercent },
+            },
+          },
+        ],
+      },
+    };
+  }
+
+  return result;
+}

package/src/coverage.test.ts

@@ -0,0 +1,27 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const generatedDir = join(pkgDir, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-k8s.json"));
+
+describe("coverage", () => {
+  test.skipIf(!hasGenerated)("analyzeK8sCoverage function exists", async () => {
+    const { analyzeK8sCoverage } = await import("./coverage");
+    expect(typeof analyzeK8sCoverage).toBe("function");
+  });
+
+  test("handles missing generated files gracefully", async () => {
+    const { analyzeK8sCoverage } = await import("./coverage");
+    // If generated files don't exist, this should throw/exit rather than crash
+    if (!hasGenerated) {
+      try {
+        await analyzeK8sCoverage();
+      } catch {
+        // Expected — no generated files
+      }
+    }
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,35 @@
+/**
+ * Coverage analysis for the Kubernetes lexicon.
+ *
+ * Analyzes generated resources for coverage of property constraints,
+ * lifecycle attributes, and other dimensions.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { computeCoverage, overallPct, type CoverageReport } from "@intentius/chant/codegen/coverage";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Analyze coverage of the K8s lexicon.
+ */
+export async function analyzeK8sCoverage(opts?: {
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<void> {
+  const generatedDir = join(pkgDir, "src", "generated");
+  const lexiconJSON = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+  const report = computeCoverage(lexiconJSON);
+
+  const pct = overallPct(report);
+  console.error(`K8s lexicon coverage: ${pct.toFixed(1)}%`);
+  console.error(`  Resources: ${report.resourceCount}`);
+  console.error(`  Property constraints: ${report.propertyPct.toFixed(1)}%`);
+
+  if (opts?.minOverall && pct < opts.minOverall) {
+    console.error(`Coverage ${pct.toFixed(1)}% is below minimum ${opts.minOverall}%`);
+    process.exit(1);
+  }
+}

package/src/crd/loader.ts

@@ -0,0 +1,112 @@
+/**
+ * CRD loader — loads Custom Resource Definitions from various sources.
+ *
+ * Supports loading from local files, remote URLs, and (placeholder)
+ * live cluster introspection via kubectl.
+ */
+
+import type { CRDSource, CRDSpec } from "./types";
+import type { K8sParseResult } from "../spec/parse";
+import { parseCRD } from "./parser";
+
+/**
+ * Load CRDs from a source and return parsed K8sParseResult entries.
+ */
+export async function loadCRDs(source: CRDSource): Promise<K8sParseResult[]> {
+  const content = await fetchCRDContent(source);
+  return parseCRD(content);
+}
+
+/**
+ * Load CRDs from multiple sources and merge results.
+ */
+export async function loadMultipleCRDs(sources: CRDSource[]): Promise<K8sParseResult[]> {
+  const results: K8sParseResult[] = [];
+  for (const source of sources) {
+    const parsed = await loadCRDs(source);
+    results.push(...parsed);
+  }
+  return results;
+}
+
+/**
+ * Fetch raw CRD YAML content from a source.
+ */
+async function fetchCRDContent(source: CRDSource): Promise<string> {
+  switch (source.type) {
+    case "file":
+      return loadFromFile(source);
+    case "url":
+      return loadFromURL(source);
+    case "cluster":
+      return loadFromCluster(source);
+    default:
+      throw new Error(`Unsupported CRD source type: ${(source as CRDSource).type}`);
+  }
+}
+
+/**
+ * Load CRD YAML from a local file.
+ */
+async function loadFromFile(source: CRDSource): Promise<string> {
+  if (!source.path) {
+    throw new Error("CRD source type 'file' requires a 'path' property");
+  }
+
+  const file = Bun.file(source.path);
+  const exists = await file.exists();
+  if (!exists) {
+    throw new Error(`CRD file not found: ${source.path}`);
+  }
+
+  return file.text();
+}
+
+/**
+ * Load CRD YAML from a remote URL.
+ */
+async function loadFromURL(source: CRDSource): Promise<string> {
+  if (!source.url) {
+    throw new Error("CRD source type 'url' requires a 'url' property");
+  }
+
+  const response = await fetch(source.url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch CRD from ${source.url}: ${response.status} ${response.statusText}`);
+  }
+
+  return response.text();
+}
+
+/**
+ * Load CRDs from a live Kubernetes cluster via kubectl.
+ *
+ * This is a placeholder implementation. Full cluster introspection
+ * requires kubectl access and proper authentication.
+ */
+async function loadFromCluster(source: CRDSource): Promise<string> {
+  const contextArg = source.context ? `--context=${source.context}` : "";
+  const nsArg = source.namespace ? `--namespace=${source.namespace}` : "";
+
+  const args = ["kubectl", "get", "crds", "-o", "yaml"];
+  if (contextArg) args.push(contextArg);
+  if (nsArg) args.push(nsArg);
+
+  const proc = Bun.spawn(args, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(
+      `kubectl failed (exit ${exitCode}): ${stderr.trim() || "unknown error"}. ` +
+      "Ensure kubectl is installed and configured with access to the target cluster.",
+    );
+  }
+
+  return stdout;
+}