@intentius/chant-lexicon-k8s 0.0.12

package/src/codegen/patches.ts

@@ -0,0 +1,108 @@
+/**
+ * Schema augmentation patches for the Kubernetes OpenAPI spec.
+ *
+ * The official K8s OpenAPI spec has known issues: recursive definitions
+ * in JSONSchemaProps, ambiguous IntOrString typing, and Quantity being
+ * opaque. Patches are applied after fetch but before parse.
+ */
+
+/**
+ * A targeted fix for a schema definition.
+ */
+export interface SchemaPatch {
+  /** Human-readable description of what this patch fixes */
+  description: string;
+  /** JSON path to the definition to patch (e.g. "definitions.io.k8s.api.core.v1.Container") */
+  path: string;
+  /** Function that applies the patch to the definition */
+  apply(def: Record<string, unknown>): void;
+}
+
+/**
+ * Registry of known schema patches.
+ */
+export const schemaPatches: SchemaPatch[] = [
+  {
+    description:
+      "Break infinite recursion in JSONSchemaProps by capping nested $ref depth",
+    path: "definitions.io.k8s.apiextensions-apiserver.pkg.apis.apiextensions.v1.JSONSchemaProps",
+    apply(def) {
+      // JSONSchemaProps references itself in properties, items, additionalProperties, etc.
+      // We mark it as a plain object to prevent infinite recursion in the codegen walker.
+      const props = def.properties as Record<string, unknown> | undefined;
+      if (!props) return;
+
+      // Replace self-referencing fields with opaque Record<string, any>
+      for (const key of [
+        "properties",
+        "additionalProperties",
+        "not",
+        "allOf",
+        "oneOf",
+        "anyOf",
+      ]) {
+        if (props[key]) {
+          (props[key] as Record<string, unknown>).description ??=
+            "JSON Schema definition (recursive, treated as opaque)";
+        }
+      }
+    },
+  },
+  {
+    description:
+      "Patch IntOrString to be explicitly typed as string | number",
+    path: "definitions.io.k8s.apimachinery.pkg.util.intstr.IntOrString",
+    apply(def) {
+      // The spec marks this as just "string" with a format, but it's actually
+      // a union type used for ports, resource quantities, etc.
+      if (!def["x-kubernetes-int-or-string"]) {
+        def["x-kubernetes-int-or-string"] = true;
+      }
+    },
+  },
+  {
+    description: "Patch Quantity to be typed as string",
+    path: "definitions.io.k8s.apimachinery.pkg.api.resource.Quantity",
+    apply(def) {
+      // Quantity is serialized as a string (e.g., "500m", "1Gi") but the
+      // spec sometimes marks it as having no type. Force string.
+      if (!def.type) {
+        def.type = "string";
+      }
+    },
+  },
+];
+
+/**
+ * Apply all registered patches to a parsed schema.
+ * Modifies the schema in place.
+ */
+export function applyPatches(
+  schema: Record<string, unknown>,
+): { applied: string[]; skipped: string[] } {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const patch of schemaPatches) {
+    const segments = patch.path.split(".");
+    let target: Record<string, unknown> | undefined = schema;
+
+    for (const segment of segments) {
+      if (target && typeof target === "object" && segment in target) {
+        target = target[segment] as Record<string, unknown>;
+      } else {
+        target = undefined;
+        break;
+      }
+    }
+
+    if (target) {
+      patch.apply(target);
+      applied.push(patch.description);
+    } else {
+      skipped.push(`${patch.description} (path "${patch.path}" not found)`);
+    }
+  }
+
+  return { applied, skipped };
+}

package/src/codegen/snapshot.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const generatedDir = join(pkgDir, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-k8s.json"));
+
+describe("snapshot", () => {
+  test.skipIf(!hasGenerated)("lexicon-k8s.json is valid JSON", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    expect(typeof parsed).toBe("object");
+    expect(parsed).not.toBeNull();
+  });
+
+  test.skipIf(!hasGenerated)("lexicon entries have required fields", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    for (const [name, entry] of Object.entries(registry)) {
+      expect(entry.resourceType).toBeDefined();
+      expect(entry.kind).toBeDefined();
+      expect(["resource", "property"]).toContain(entry.kind);
+    }
+  });
+
+  test.skipIf(!hasGenerated)("contains Deployment entry", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const deployment = Object.values(registry).find(
+      (e: any) => e.resourceType === "K8s::Apps::Deployment",
+    );
+    expect(deployment).toBeDefined();
+    expect(deployment!.kind).toBe("resource");
+    expect(deployment!.apiVersion).toBe("apps/v1");
+    expect(deployment!.gvkKind).toBe("Deployment");
+  });
+
+  test.skipIf(!hasGenerated)("contains Pod entry", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const pod = Object.values(registry).find(
+      (e: any) => e.resourceType === "K8s::Core::Pod",
+    );
+    expect(pod).toBeDefined();
+    expect(pod!.kind).toBe("resource");
+  });
+
+  test.skipIf(!hasGenerated)("contains Service entry", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const svc = Object.values(registry).find(
+      (e: any) => e.resourceType === "K8s::Core::Service",
+    );
+    expect(svc).toBeDefined();
+    expect(svc!.kind).toBe("resource");
+    expect(svc!.apiVersion).toBe("v1");
+  });
+
+  test.skipIf(!hasGenerated)("contains ConfigMap entry", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const cm = Object.values(registry).find(
+      (e: any) => e.resourceType === "K8s::Core::ConfigMap",
+    );
+    expect(cm).toBeDefined();
+  });
+
+  test.skipIf(!hasGenerated)("contains Container property type", () => {
+    const raw = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const registry = JSON.parse(raw) as Record<string, any>;
+
+    const container = Object.values(registry).find(
+      (e: any) => e.resourceType === "K8s::Core::Container",
+    );
+    expect(container).toBeDefined();
+    expect(container!.kind).toBe("property");
+  });
+
+  test.skipIf(!hasGenerated)("index.d.ts contains class declarations", () => {
+    const dtsPath = join(generatedDir, "index.d.ts");
+    if (!existsSync(dtsPath)) return;
+
+    const dts = readFileSync(dtsPath, "utf-8");
+    expect(dts).toContain("class Deployment");
+    expect(dts).toContain("class Service");
+    expect(dts).toContain("class Pod");
+  });
+});

package/src/codegen/typecheck.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from "bun:test";
+import { typecheckDTS } from "./typecheck";
+
+describe("typecheckDTS", () => {
+  test("passes valid .d.ts content", async () => {
+    const result = await typecheckDTS("export declare class Foo { bar: string; }");
+    expect(result.ok).toBe(true);
+    expect(result.diagnostics).toHaveLength(0);
+  });
+
+  test("fails on syntax errors", async () => {
+    const result = await typecheckDTS("export declare class { }"); // missing class name
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.length).toBeGreaterThan(0);
+  });
+
+  test("fails on undefined type references", async () => {
+    const result = await typecheckDTS(
+      "export declare class Foo { bar: UndefinedType; }",
+    );
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.length).toBeGreaterThan(0);
+  });
+});

package/src/codegen/typecheck.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export from core — typecheck is lexicon-agnostic.
+ */
+export { typecheckDTS, type TypeCheckResult } from "@intentius/chant/codegen/typecheck";

package/src/codegen/versions.ts

@@ -0,0 +1,43 @@
+/**
+ * Pinned dependency versions for the Kubernetes lexicon.
+ *
+ * Centralises the schema version used by fetch.ts and provides
+ * a helper to check for newer Kubernetes releases.
+ */
+
+/** Pinned versions of external dependencies. */
+export const PINNED_VERSIONS = {
+  k8sOpenAPI: "v1.32.0",
+} as const;
+
+/**
+ * Build the raw GitHub URL for the K8s swagger.json for a given version.
+ */
+export function k8sSwaggerUrl(version?: string): string {
+  const v = version ?? PINNED_VERSIONS.k8sOpenAPI;
+  return `https://raw.githubusercontent.com/kubernetes/kubernetes/${v}/api/openapi-spec/swagger.json`;
+}
+
+/**
+ * Check for a newer stable Kubernetes release on GitHub.
+ * Returns the latest tag if newer than pinned, or null if up-to-date.
+ */
+export async function checkForUpdates(): Promise<string | null> {
+  try {
+    const res = await fetch(
+      "https://api.github.com/repos/kubernetes/kubernetes/releases/latest",
+      {
+        headers: { Accept: "application/vnd.github+json" },
+      },
+    );
+    if (!res.ok) return null;
+
+    const data = (await res.json()) as { tag_name?: string };
+    const latest = data.tag_name;
+    if (!latest) return null;
+
+    return latest !== PINNED_VERSIONS.k8sOpenAPI ? latest : null;
+  } catch {
+    return null;
+  }
+}

package/src/composites/autoscaled-service.ts

@@ -0,0 +1,236 @@
+/**
+ * AutoscaledService composite — Deployment + Service + HPA + PDB.
+ *
+ * A higher-level construct for production HTTP services with autoscaling
+ * and disruption budget. Enforces that HPA targets match the Deployment,
+ * PDB selectors match pod labels, and resource requests are set.
+ */
+
+export interface AutoscaledServiceProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image (e.g., "nginx:1.25"). */
+  image: string;
+  /** Container port (default: 80). */
+  port?: number;
+  /** Minimum replicas for HPA (default: 2). */
+  minReplicas?: number;
+  /** Maximum replicas for HPA (required). */
+  maxReplicas: number;
+  /** Target CPU utilization percentage (default: 70). */
+  targetCPUPercent?: number;
+  /** Target memory utilization percentage — if set, adds memory metric. */
+  targetMemoryPercent?: number;
+  /** PDB minAvailable (default: 1). */
+  minAvailable?: number | string;
+  /** CPU request (required — HPA needs resource requests). */
+  cpuRequest: string;
+  /** Memory request (required). */
+  memoryRequest: string;
+  /** CPU limit (optional — left unset if not provided). */
+  cpuLimit?: string;
+  /** Memory limit (optional — left unset if not provided). */
+  memoryLimit?: string;
+  /** Topology spread constraints (default: false). true → zone spreading, object → custom. */
+  topologySpread?: boolean | {
+    maxSkew?: number;
+    topologyKey?: string;
+  };
+  /** Liveness probe path (default: "/healthz"). */
+  livenessPath?: string;
+  /** Readiness probe path (default: "/readyz"). */
+  readinessPath?: 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 AutoscaledServiceResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  hpa: Record<string, unknown>;
+  pdb: Record<string, unknown>;
+}
+
+/**
+ * Create an AutoscaledService composite — returns prop objects for
+ * a Deployment, Service, HorizontalPodAutoscaler, and PodDisruptionBudget.
+ *
+ * @example
+ * ```ts
+ * import { AutoscaledService } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, hpa, pdb } = AutoscaledService({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   maxReplicas: 10,
+ *   cpuRequest: "100m",
+ *   memoryRequest: "128Mi",
+ * });
+ * ```
+ */
+export function AutoscaledService(props: AutoscaledServiceProps): AutoscaledServiceResult {
+  const {
+    name,
+    image,
+    port = 80,
+    minReplicas = 2,
+    maxReplicas,
+    targetCPUPercent = 70,
+    targetMemoryPercent,
+    minAvailable = 1,
+    cpuRequest,
+    memoryRequest,
+    cpuLimit,
+    memoryLimit,
+    topologySpread = false,
+    livenessPath = "/healthz",
+    readinessPath = "/readyz",
+    labels: extraLabels = {},
+    namespace,
+    env,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build topologySpreadConstraints if enabled
+  const topologyConstraints: Array<Record<string, unknown>> | undefined = (() => {
+    if (!topologySpread) return undefined;
+    const maxSkew = typeof topologySpread === "object" ? (topologySpread.maxSkew ?? 1) : 1;
+    const topologyKey = typeof topologySpread === "object"
+      ? (topologySpread.topologyKey ?? "topology.kubernetes.io/zone")
+      : "topology.kubernetes.io/zone";
+    return [{
+      maxSkew,
+      topologyKey,
+      whenUnsatisfiable: "DoNotSchedule",
+      labelSelector: { matchLabels: { "app.kubernetes.io/name": name } },
+    }];
+  })();
+
+  const resources: Record<string, unknown> = {
+    requests: { cpu: cpuRequest, memory: memoryRequest },
+    ...(cpuLimit || memoryLimit
+      ? {
+          limits: {
+            ...(cpuLimit && { cpu: cpuLimit }),
+            ...(memoryLimit && { memory: memoryLimit }),
+          },
+        }
+      : {}),
+  };
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      replicas: minReplicas,
+      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,
+              livenessProbe: {
+                httpGet: { path: livenessPath, port },
+                initialDelaySeconds: 10,
+                periodSeconds: 10,
+              },
+              readinessProbe: {
+                httpGet: { path: readinessPath, port },
+                initialDelaySeconds: 5,
+                periodSeconds: 5,
+              },
+              ...(env && { env }),
+            },
+          ],
+          ...(topologyConstraints && { topologySpreadConstraints: topologyConstraints }),
+        },
+      },
+    },
+  };
+
+  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 metrics: Array<Record<string, unknown>> = [
+    {
+      type: "Resource",
+      resource: {
+        name: "cpu",
+        target: { type: "Utilization", averageUtilization: targetCPUPercent },
+      },
+    },
+  ];
+
+  if (targetMemoryPercent !== undefined) {
+    metrics.push({
+      type: "Resource",
+      resource: {
+        name: "memory",
+        target: { type: "Utilization", averageUtilization: targetMemoryPercent },
+      },
+    });
+  }
+
+  const hpaProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "autoscaler" },
+    },
+    spec: {
+      scaleTargetRef: {
+        apiVersion: "apps/v1",
+        kind: "Deployment",
+        name,
+      },
+      minReplicas,
+      maxReplicas,
+      metrics,
+    },
+  };
+
+  const pdbProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+    },
+    spec: {
+      minAvailable,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+    },
+  };
+
+  return {
+    deployment: deploymentProps,
+    service: serviceProps,
+    hpa: hpaProps,
+    pdb: pdbProps,
+  };
+}