@intentius/chant-lexicon-k8s 0.0.12

package/src/crd/parser.test.ts

@@ -0,0 +1,217 @@
+import { describe, test, expect } from "bun:test";
+import { parseCRD, parseCRDSpec } from "./parser";
+
+describe("parseCRD", () => {
+  test("parses valid CRD YAML", () => {
+    const crd = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: certificates.cert-manager.io
+spec:
+  group: cert-manager.io
+  names:
+    kind: Certificate
+    plural: certificates
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                secretName:
+                  type: string
+                issuerRef:
+                  type: object
+                  properties:
+                    name:
+                      type: string
+                    kind:
+                      type: string
+`;
+    const results = parseCRD(crd);
+    expect(results.length).toBe(1);
+    expect(results[0].resource.typeName).toBe("K8s::CertManager::Certificate");
+    expect(results[0].gvk.group).toBe("cert-manager.io");
+    expect(results[0].gvk.version).toBe("v1");
+    expect(results[0].gvk.kind).toBe("Certificate");
+  });
+
+  test("parses multi-doc CRD bundle", () => {
+    const bundle = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: certificates.cert-manager.io
+spec:
+  group: cert-manager.io
+  names:
+    kind: Certificate
+    plural: certificates
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: issuers.cert-manager.io
+spec:
+  group: cert-manager.io
+  names:
+    kind: Issuer
+    plural: issuers
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+`;
+    const results = parseCRD(bundle);
+    expect(results.length).toBe(2);
+  });
+
+  test("skips non-CRD documents", () => {
+    const mixed = `
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: something
+data:
+  key: value
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: foos.example.com
+spec:
+  group: example.com
+  names:
+    kind: Foo
+    plural: foos
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+`;
+    const results = parseCRD(mixed);
+    expect(results.length).toBe(1);
+    expect(results[0].resource.typeName).toBe("K8s::Example::Foo");
+  });
+
+  test("handles CRD without schema (empty properties)", () => {
+    const crd = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: bars.example.com
+spec:
+  group: example.com
+  names:
+    kind: Bar
+    plural: bars
+  scope: Namespaced
+  versions:
+    - name: v1
+      served: true
+      storage: true
+`;
+    const results = parseCRD(crd);
+    expect(results.length).toBe(1);
+    expect(results[0].resource.properties).toEqual([]);
+  });
+
+  test("type name follows K8s::{GroupNs}::{Kind} convention", () => {
+    const crd = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: widgets.my-company.io
+spec:
+  group: my-company.io
+  names:
+    kind: Widget
+    plural: widgets
+  scope: Namespaced
+  versions:
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+`;
+    const results = parseCRD(crd);
+    expect(results[0].resource.typeName).toMatch(/^K8s::\w+::\w+$/);
+  });
+});
+
+describe("parseCRDSpec", () => {
+  test("extracts properties from openAPIV3Schema", () => {
+    const spec = {
+      group: "example.com",
+      names: { kind: "Foo", plural: "foos" },
+      scope: "Namespaced" as const,
+      versions: [
+        {
+          name: "v1",
+          served: true,
+          storage: true,
+          schema: {
+            openAPIV3Schema: {
+              type: "object",
+              properties: {
+                spec: {
+                  type: "object",
+                  properties: {
+                    count: { type: "integer" },
+                    name: { type: "string" },
+                  },
+                },
+                metadata: { type: "object" },
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const results = parseCRDSpec(spec);
+    expect(results.length).toBe(1);
+    const props = results[0].resource.properties;
+    expect(props.some((p) => p.name === "spec")).toBe(true);
+    expect(props.some((p) => p.name === "metadata")).toBe(true);
+  });
+
+  test("normalizeGroupName converts cert-manager.io to CertManager", () => {
+    const spec = {
+      group: "cert-manager.io",
+      names: { kind: "Certificate", plural: "certificates" },
+      scope: "Namespaced" as const,
+      versions: [
+        { name: "v1", served: true, storage: true },
+      ],
+    };
+
+    const results = parseCRDSpec(spec);
+    expect(results[0].resource.typeName).toBe("K8s::CertManager::Certificate");
+  });
+});

package/src/crd/parser.ts

@@ -0,0 +1,279 @@
+/**
+ * CRD parser — converts CRD YAML into K8sParseResult entries.
+ *
+ * Parses the openAPIV3Schema from a CRD's versions to extract resource
+ * properties, building the same K8sParseResult structures used by the
+ * main K8s swagger parser. This enables CRD-based resources to integrate
+ * with the full codegen pipeline.
+ */
+
+import type { K8sParseResult, ParsedProperty, ParsedPropertyType, GroupVersionKind } from "../spec/parse";
+import type { CRDSpec } from "./types";
+import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+import { parseYAML } from "@intentius/chant/yaml";
+
+/**
+ * Normalize a CRD group to a PascalCase namespace segment.
+ * "cert-manager.io" → "CertManager"
+ * "monitoring.coreos.com" → "Monitoring"
+ */
+function normalizeGroupName(group: string): string {
+  // Take the first segment before the first dot
+  const firstSegment = group.split(".")[0];
+  // Convert kebab-case to PascalCase
+  return firstSegment
+    .split("-")
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+}
+
+/**
+ * Parse a CRD YAML document string into K8sParseResult entries.
+ * Returns one result per served version in the CRD.
+ */
+export function parseCRD(content: string): K8sParseResult[] {
+  const results: K8sParseResult[] = [];
+
+  // Support multi-document YAML for CRD bundles
+  const documents = content
+    .split(/^---\s*$/m)
+    .map((d) => d.trim())
+    .filter((d) => d.length > 0);
+
+  for (const docStr of documents) {
+    const doc = parseYAML(docStr) as Record<string, unknown>;
+    if (!doc || doc.kind !== "CustomResourceDefinition") continue;
+
+    const spec = doc.spec as CRDSpec | undefined;
+    if (!spec?.group || !spec?.names?.kind || !spec?.versions) continue;
+
+    const crdResults = parseCRDSpec(spec);
+    results.push(...crdResults);
+  }
+
+  return results;
+}
+
+/**
+ * Parse a CRD spec into K8sParseResult entries.
+ * Extracts one result per served version with storage version preferred.
+ */
+export function parseCRDSpec(spec: CRDSpec): K8sParseResult[] {
+  const results: K8sParseResult[] = [];
+  const groupNs = normalizeGroupName(spec.group);
+
+  // Find the storage version (the canonical version)
+  const storageVersion = spec.versions.find((v) => v.storage && v.served);
+  // Fall back to any served version
+  const targetVersion = storageVersion ?? spec.versions.find((v) => v.served);
+
+  if (!targetVersion) return results;
+
+  const typeName = `K8s::${groupNs}::${spec.names.kind}`;
+  const gvk: GroupVersionKind = {
+    group: spec.group,
+    version: targetVersion.name,
+    kind: spec.names.kind,
+  };
+
+  const schema = targetVersion.schema?.openAPIV3Schema as OpenAPISchema | undefined;
+  const properties = schema ? extractProperties(schema) : [];
+  const propertyTypes = schema ? extractPropertyTypes(schema, typeName) : [];
+
+  results.push({
+    resource: {
+      typeName,
+      description: `Custom resource: ${spec.names.kind} (${spec.group})`,
+      properties,
+      attributes: [
+        { name: "name", tsType: "string" },
+        { name: "namespace", tsType: "string" },
+        { name: "uid", tsType: "string" },
+      ],
+      deprecatedProperties: [],
+    },
+    propertyTypes,
+    enums: [],
+    gvk,
+  });
+
+  return results;
+}
+
+// ── OpenAPI schema types ────────────────────────────────────────────
+
+interface OpenAPISchema {
+  type?: string;
+  description?: string;
+  properties?: Record<string, OpenAPISchema>;
+  required?: string[];
+  items?: OpenAPISchema;
+  additionalProperties?: boolean | OpenAPISchema;
+  enum?: string[];
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  default?: unknown;
+  "x-kubernetes-preserve-unknown-fields"?: boolean;
+  "x-kubernetes-int-or-string"?: boolean;
+}
+
+// ── Property extraction ─────────────────────────────────────────────
+
+/**
+ * Extract top-level properties from a CRD's openAPIV3Schema.
+ * Focuses on the "spec" sub-object and metadata, skipping status.
+ */
+function extractProperties(schema: OpenAPISchema): ParsedProperty[] {
+  const result: ParsedProperty[] = [];
+  const topProps = schema.properties ?? {};
+  const topRequired = new Set<string>(schema.required ?? []);
+
+  // Skip apiVersion, kind, status — same pattern as core parser
+  const skipProps = new Set(["apiVersion", "kind", "status"]);
+
+  for (const [name, prop] of Object.entries(topProps)) {
+    if (skipProps.has(name)) continue;
+
+    result.push({
+      name,
+      tsType: resolveSchemaType(prop),
+      required: topRequired.has(name),
+      description: prop.description,
+      enum: prop.enum,
+      constraints: extractConstraints(prop),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Extract nested object types as ParsedPropertyType entries.
+ * Walks the spec's properties looking for inline object definitions.
+ */
+function extractPropertyTypes(schema: OpenAPISchema, parentTypeName: string): ParsedPropertyType[] {
+  const results: ParsedPropertyType[] = [];
+  const specSchema = schema.properties?.spec;
+  if (!specSchema?.properties) return results;
+
+  for (const [name, prop] of Object.entries(specSchema.properties)) {
+    // Extract inline object definitions as property types
+    if (prop.type === "object" && prop.properties) {
+      const ptName = `${parentTypeName}::${pascalCase(name)}`;
+      const requiredSet = new Set<string>(prop.required ?? []);
+
+      results.push({
+        name: ptName,
+        defType: name,
+        properties: Object.entries(prop.properties).map(([pName, pSchema]) => ({
+          name: pName,
+          tsType: resolveSchemaType(pSchema),
+          required: requiredSet.has(pName),
+          description: pSchema.description,
+          enum: pSchema.enum,
+          constraints: extractConstraints(pSchema),
+        })),
+      });
+    }
+
+    // Array of objects
+    if (prop.type === "array" && prop.items?.type === "object" && prop.items.properties) {
+      const itemSchema = prop.items;
+      const itemProps = itemSchema.properties!;
+      const ptName = `${parentTypeName}::${pascalCase(singularize(name))}`;
+      const requiredSet = new Set<string>(itemSchema.required ?? []);
+
+      results.push({
+        name: ptName,
+        defType: name,
+        properties: Object.entries(itemProps).map(([pName, pSchema]) => ({
+          name: pName,
+          tsType: resolveSchemaType(pSchema),
+          required: requiredSet.has(pName),
+          description: pSchema.description,
+          enum: pSchema.enum,
+          constraints: extractConstraints(pSchema),
+        })),
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve an OpenAPI schema node to a TypeScript type string.
+ */
+function resolveSchemaType(schema: OpenAPISchema): string {
+  if (!schema) return "any";
+
+  if (schema["x-kubernetes-int-or-string"]) return "string | number";
+  if (schema["x-kubernetes-preserve-unknown-fields"]) return "Record<string, any>";
+
+  if (schema.enum && schema.enum.length > 0) {
+    return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+  }
+
+  switch (schema.type) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      if (schema.items) {
+        const itemType = resolveSchemaType(schema.items);
+        if (itemType.includes(" | ")) return `(${itemType})[]`;
+        return `${itemType}[]`;
+      }
+      return "any[]";
+    case "object":
+      if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        const valueType = resolveSchemaType(schema.additionalProperties);
+        return `Record<string, ${valueType}>`;
+      }
+      if (schema.properties) return "Record<string, any>"; // will be a property type
+      return "Record<string, any>";
+    default:
+      return "any";
+  }
+}
+
+/**
+ * Extract property constraints from an OpenAPI schema node.
+ */
+function extractConstraints(schema: OpenAPISchema): PropertyConstraints {
+  const constraints: PropertyConstraints = {};
+  if (schema.minimum !== undefined) constraints.minimum = schema.minimum;
+  if (schema.maximum !== undefined) constraints.maximum = schema.maximum;
+  if (schema.minLength !== undefined) constraints.minLength = schema.minLength;
+  if (schema.maxLength !== undefined) constraints.maxLength = schema.maxLength;
+  if (schema.pattern !== undefined) constraints.pattern = schema.pattern;
+  return constraints;
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function pascalCase(str: string): string {
+  return str
+    .split(/[-_.]/)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+}
+
+/**
+ * Naive singularize — removes trailing "s" for property type naming.
+ */
+function singularize(str: string): string {
+  if (str.endsWith("ies")) return str.slice(0, -3) + "y";
+  if (str.endsWith("ses")) return str.slice(0, -2);
+  if (str.endsWith("s") && !str.endsWith("ss")) return str.slice(0, -1);
+  return str;
+}

package/src/crd/types.ts

@@ -0,0 +1,54 @@
+/**
+ * CRD (Custom Resource Definition) framework types.
+ *
+ * Defines the data structures used to load, parse, and process
+ * Kubernetes CRDs for code generation and lexicon extension.
+ */
+
+/**
+ * Source from which to load CRD definitions.
+ */
+export interface CRDSource {
+  /** How to fetch the CRD */
+  type: "file" | "url" | "cluster";
+  /** File path for type="file" */
+  path?: string;
+  /** URL for type="url" */
+  url?: string;
+  /** Kubectl context for type="cluster" */
+  context?: string;
+  /** Namespace to scope the CRD lookup for type="cluster" */
+  namespace?: string;
+}
+
+/**
+ * Parsed representation of a CRD's spec section.
+ */
+export interface CRDSpec {
+  /** API group (e.g. "cert-manager.io") */
+  group: string;
+  /** Name variants for the CRD */
+  names: {
+    kind: string;
+    plural: string;
+    singular?: string;
+    shortNames?: string[];
+  };
+  /** API versions served by this CRD */
+  versions: Array<{
+    name: string;
+    served: boolean;
+    storage: boolean;
+    schema?: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Full CRD document as parsed from YAML.
+ */
+export interface CRDDocument {
+  apiVersion: string;
+  kind: "CustomResourceDefinition";
+  metadata: { name: string; [key: string]: unknown };
+  spec: CRDSpec;
+}

package/src/default-labels.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "bun:test";
+import {
+  defaultLabels,
+  defaultAnnotations,
+  isDefaultLabels,
+  isDefaultAnnotations,
+  DEFAULT_LABELS_MARKER,
+  DEFAULT_ANNOTATIONS_MARKER,
+} from "./default-labels";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+
+describe("defaultLabels", () => {
+  test("returns object with correct markers", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl[DEFAULT_LABELS_MARKER]).toBe(true);
+    expect(dl[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("has lexicon k8s", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl.lexicon).toBe("k8s");
+  });
+
+  test("has correct entityType", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl.entityType).toBe("chant:k8s:defaultLabels");
+  });
+
+  test("labels are accessible", () => {
+    const dl = defaultLabels({ env: "prod", team: "backend" });
+    expect(dl.labels.env).toBe("prod");
+    expect(dl.labels.team).toBe("backend");
+  });
+
+  test("empty labels allowed", () => {
+    const dl = defaultLabels({});
+    expect(dl.labels).toEqual({});
+  });
+});
+
+describe("defaultAnnotations", () => {
+  test("returns object with correct markers", () => {
+    const da = defaultAnnotations({ note: "hello" });
+    expect(da[DEFAULT_ANNOTATIONS_MARKER]).toBe(true);
+    expect(da[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("has lexicon k8s", () => {
+    const da = defaultAnnotations({ note: "hello" });
+    expect(da.lexicon).toBe("k8s");
+  });
+
+  test("has correct entityType", () => {
+    const da = defaultAnnotations({ note: "hello" });
+    expect(da.entityType).toBe("chant:k8s:defaultAnnotations");
+  });
+
+  test("annotations are accessible", () => {
+    const da = defaultAnnotations({ "kubernetes.io/description": "test" });
+    expect(da.annotations["kubernetes.io/description"]).toBe("test");
+  });
+
+  test("empty annotations allowed", () => {
+    const da = defaultAnnotations({});
+    expect(da.annotations).toEqual({});
+  });
+});
+
+describe("isDefaultLabels", () => {
+  test("returns true for defaultLabels result", () => {
+    expect(isDefaultLabels(defaultLabels({ env: "prod" }))).toBe(true);
+  });
+
+  test("returns false for null", () => {
+    expect(isDefaultLabels(null)).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isDefaultLabels(undefined)).toBe(false);
+  });
+
+  test("returns false for regular objects", () => {
+    expect(isDefaultLabels({ labels: { env: "prod" } })).toBe(false);
+  });
+
+  test("returns false for defaultAnnotations", () => {
+    expect(isDefaultLabels(defaultAnnotations({ note: "hi" }))).toBe(false);
+  });
+});
+
+describe("isDefaultAnnotations", () => {
+  test("returns true for defaultAnnotations result", () => {
+    expect(isDefaultAnnotations(defaultAnnotations({ note: "hi" }))).toBe(true);
+  });
+
+  test("returns false for null", () => {
+    expect(isDefaultAnnotations(null)).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isDefaultAnnotations(undefined)).toBe(false);
+  });
+
+  test("returns false for regular objects", () => {
+    expect(isDefaultAnnotations({ annotations: {} })).toBe(false);
+  });
+
+  test("returns false for defaultLabels", () => {
+    expect(isDefaultAnnotations(defaultLabels({ env: "prod" }))).toBe(false);
+  });
+});