@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/codegen/generate-typescript.js

@@ -0,0 +1,124 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with all
+ * Kubernetes resource and property type classes.
+ */
+import { k8sShortName } from "../spec/parse.js";
+import { propertyTypeName, extractDefName } from "./naming.js";
+import { writeResourceClass, resolveConstructorType, } from "@intentius/chant/codegen/generate-typescript";
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(results, naming, definitionTypes = []) {
+    const lines = [];
+    lines.push("// Code generated by chant k8s generate. DO NOT EDIT.");
+    const resources = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        const shortName = k8sShortName(typeName);
+        const remap = new Map();
+        for (const pt of r.propertyTypes) {
+            const defName = extractDefName(pt.name, shortName);
+            remap.set(pt.name, propertyTypeName(tsName, defName));
+        }
+        for (const e of r.enums) {
+            const defName = extractDefName(e.name, shortName);
+            remap.set(e.name, propertyTypeName(tsName, defName));
+        }
+        const dtsProps = r.resource.properties.map((p) => ({
+            name: p.name,
+            type: p.tsType,
+            required: p.required,
+            description: p.description,
+        }));
+        const dtsAttrs = r.resource.attributes.map((a) => ({
+            name: a.name,
+            type: a.tsType,
+        }));
+        resources.push({ tsName, isProperty: !!r.isProperty, properties: dtsProps, attributes: dtsAttrs, remap });
+        for (const alias of naming.aliases(typeName)) {
+            resources.push({ tsName: alias, isProperty: !!r.isProperty, properties: dtsProps, attributes: dtsAttrs, remap });
+        }
+    }
+    // Sort alphabetically
+    resources.sort((a, b) => a.tsName.localeCompare(b.tsName));
+    // Resource classes
+    const resourceEntries = resources.filter((r) => !r.isProperty);
+    const propertyEntries = resources.filter((r) => r.isProperty);
+    if (resourceEntries.length > 0) {
+        lines.push("");
+        lines.push("// --- Kubernetes Resource classes ---");
+        for (const re of resourceEntries) {
+            writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap);
+        }
+    }
+    if (propertyEntries.length > 0) {
+        lines.push("");
+        lines.push("// --- Property type classes ---");
+        for (const pe of propertyEntries) {
+            writeMembersInterface(lines, pe.tsName, undefined, pe.properties, pe.remap);
+            lines.push(`export declare class ${pe.tsName} {`);
+            lines.push(`  constructor(props: ${pe.tsName});`);
+            lines.push("}");
+        }
+    }
+    // chant #3093 — every other object definition a resource reaches. Declared
+    // as interfaces: nothing constructs them at runtime, an author writes them
+    // as object literals.
+    if (definitionTypes.length > 0) {
+        const classNames = new Set(resources.map((r) => r.tsName));
+        lines.push("");
+        lines.push("// --- Definition interfaces ---");
+        for (const dt of definitionTypes) {
+            if (classNames.has(dt.name)) {
+                throw new Error(`k8s codegen: definition ${dt.defKey} would be declared as ${dt.name}, which is already a class`);
+            }
+            const props = dt.properties.map((p) => ({
+                name: p.name,
+                type: p.tsType,
+                required: p.required,
+                description: p.description,
+            }));
+            writeMembersInterface(lines, dt.name, dt.description, props, undefined);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+const IDENT = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+/**
+ * Write the members of a property type or definition as an interface. For a
+ * property type the interface merges with its class, so `new Container({...})`
+ * and a `{...}` literal both check against the same members, and so does a
+ * field typed `Container`. A class with only a constructor has no members, and
+ * an empty instance type accepts any object (chant #3093).
+ */
+function writeMembersInterface(lines, tsName, description, props, remap) {
+    lines.push("");
+    if (description)
+        lines.push(`/** ${jsdoc(description)} */`);
+    if (props.length === 0) {
+        lines.push(`export interface ${tsName} {}`);
+        return;
+    }
+    // Required first, then optional, each alphabetical — the constructor order.
+    const sorted = [...props].sort((a, b) => {
+        if (a.required !== b.required)
+            return a.required ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    lines.push(`export interface ${tsName} {`);
+    for (const p of sorted) {
+        if (p.description)
+            lines.push(`  /** ${jsdoc(p.description)} */`);
+        const key = IDENT.test(p.name) ? p.name : JSON.stringify(p.name);
+        lines.push(`  ${key}${p.required ? "" : "?"}: ${resolveConstructorType(p.type, remap)};`);
+    }
+    lines.push("}");
+}
+/** A description made safe for a one-line JSDoc comment. */
+function jsdoc(text) {
+    return text.replace(/\*\//g, "*\\/");
+}

package/dist/codegen/generate.js

@@ -0,0 +1,173 @@
+/**
+ * Kubernetes generation pipeline — uses core generatePipeline
+ * with K8s-specific fetch, parse, naming, and generation callbacks.
+ */
+import { generatePipeline, writeGeneratedArtifacts, } from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "../spec/fetch.js";
+import { parseK8sSwaggerTypes, specListMapKeyPairs, k8sShortName, } from "../spec/parse.js";
+import { loadMultipleCRDs } from "../crd/loader.js";
+import { CRD_SOURCES } from "../crd/crd-sources.js";
+import { NamingStrategy, propertyTypeName, extractDefName } from "./naming.js";
+import { generateLexiconJSON } from "./generate-lexicon.js";
+import { generateOperationsJSON } from "./generate-operations.js";
+import { generateListMapKeysJSON } from "./generate-list-map-keys.js";
+import { generateTypeScriptDeclarations } from "./generate-typescript.js";
+import { generateRuntimeIndex as coreGenerateRuntimeIndex, } from "@intentius/chant/codegen/generate-runtime-index";
+/** Where a CRD source comes from, as a log line or an error names it. */
+function crdSourceLabel(source) {
+    return source.url ?? source.path ?? source.chart ?? "cluster";
+}
+/**
+ * Load every CRD source. A source that fails to load fails generation and the
+ * error names it (#3310): skipping it shrinks the output silently, and the loss
+ * shows up only later as a surface-snapshot diff. Every source is tried first,
+ * so one run names all the failures. `allowFailures` turns them back into
+ * warnings for a deliberate partial run.
+ */
+export async function loadCrdSources(sources, log, opts = {}) {
+    const load = opts.load ?? loadMultipleCRDs;
+    const results = [];
+    const failures = [];
+    for (const source of sources) {
+        const label = crdSourceLabel(source);
+        try {
+            const parsed = await load([source]);
+            results.push(...parsed);
+            log(`Loaded ${parsed.length} CRD type(s) from ${label}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            failures.push({ file: label, error: msg });
+            log(`${opts.allowFailures ? "Warning: skipping" : "Error:"} CRD source ${label} failed to load: ${msg}`);
+        }
+    }
+    if (failures.length > 0 && !opts.allowFailures) {
+        const lines = failures.map((f) => `  ${f.file}: ${f.error}`).join("\n");
+        throw new Error(`${failures.length} CRD source(s) failed to load, so generation would drop their kinds:\n${lines}\n` +
+            `Set CHANT_K8S_ALLOW_CRD_FAILURES=1 to generate without them deliberately.`);
+    }
+    log(`Total CRD types loaded: ${results.length}`);
+    return { results, warnings: failures };
+}
+/**
+ * Run the full Kubernetes generation pipeline.
+ */
+export async function generate(opts = {}) {
+    // Pipeline state captured in closure — no module-level mutation
+    let pendingResults = [];
+    // chant #1441 — read off the raw document in `parseSchema`, since the
+    // result set covers only the definitions chant emits types for.
+    let specPairs = [];
+    // chant #3093 — the declaration-only interfaces, which only the `.d.ts` emits.
+    let definitionTypes = [];
+    const config = {
+        fetchSchemas: async (fetchOpts) => {
+            return fetchSchemas(fetchOpts.force, opts.schemaVersion);
+        },
+        parseSchema: (_typeName, data) => {
+            // The K8s schema is a single document — parseK8sSwaggerTypes returns multiple results.
+            // The pipeline calls this once per schema entry. We return the first result
+            // and use augmentResults to inject the rest.
+            const { results, definitionTypes: defs } = parseK8sSwaggerTypes(data);
+            definitionTypes = defs;
+            specPairs = specListMapKeyPairs(data);
+            if (results.length === 0)
+                return null;
+            // Return the first result; stash the rest for augmentResults
+            pendingResults = results.slice(1);
+            return results[0];
+        },
+        createNaming: (results) => new NamingStrategy(results),
+        augmentSchemas: async (schemas, _opts, log) => {
+            // Load third-party CRDs and return as extraResults so they are
+            // included in the generated types alongside the core K8s resources.
+            const allowFailures = opts.allowCrdFailures ?? process.env.CHANT_K8S_ALLOW_CRD_FAILURES === "1";
+            const { results: crdResults, warnings } = await loadCrdSources(CRD_SOURCES, log, { allowFailures });
+            return { schemas, extraResults: crdResults, warnings };
+        },
+        augmentResults: (results, _opts, log) => {
+            // Add the remaining results from the single-schema parse
+            if (pendingResults.length > 0) {
+                results.push(...pendingResults);
+                log(`Added ${pendingResults.length} additional K8s resources from OpenAPI spec`);
+                pendingResults = [];
+            }
+            log(`Total: ${results.length} K8s resource/property schemas`);
+            return { results };
+        },
+        generateRegistry: (results, naming) => {
+            return generateLexiconJSON(results, naming);
+        },
+        generateTypes: (results, naming) => {
+            return generateTypeScriptDeclarations(results, naming, definitionTypes);
+        },
+        generateRuntimeIndex: (results, naming) => {
+            return generateRuntimeIndex(results, naming);
+        },
+        // chant #1074 — the operation surface, out of the same results the types
+        // and the registry come out of, so the live client cannot address a kind
+        // differently from how the declarable surface names it.
+        generateExtraArtifacts: (results) => ({
+            "operations.json": generateOperationsJSON(results),
+            // chant #1441 — the spec's own associative-list keys, so drift compares
+            // list elements by identity instead of by index.
+            "list-map-keys.json": generateListMapKeysJSON(specPairs, results),
+        }),
+    };
+    return generatePipeline(config, opts);
+}
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result, baseDir) {
+    writeGeneratedArtifacts({
+        baseDir,
+        files: {
+            "lexicon-k8s.json": result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+            "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+            ...(result.extraArtifacts ?? {}),
+        },
+    });
+}
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(results, naming) {
+    const resourceEntries = [];
+    const propertyEntries = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        const attrs = {};
+        for (const attr of r.resource.attributes) {
+            attrs[attr.name] = attr.name;
+        }
+        if (r.isProperty) {
+            propertyEntries.push({ tsName, resourceType: typeName });
+            for (const alias of naming.aliases(typeName)) {
+                propertyEntries.push({ tsName: alias, resourceType: typeName });
+            }
+        }
+        else {
+            resourceEntries.push({ tsName, resourceType: typeName, attrs });
+            for (const alias of naming.aliases(typeName)) {
+                resourceEntries.push({ tsName: alias, resourceType: typeName, attrs });
+            }
+        }
+        // Nested property types
+        const shortName = k8sShortName(typeName);
+        for (const pt of r.propertyTypes) {
+            const defName = extractDefName(pt.name, shortName);
+            const ptName = propertyTypeName(tsName, defName);
+            const ptType = `${typeName}.${pt.defType}`;
+            propertyEntries.push({ tsName: ptName, resourceType: ptType });
+        }
+    }
+    return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, {
+        lexiconName: "k8s",
+    });
+}

package/dist/codegen/naming.js

@@ -0,0 +1,174 @@
+/**
+ * Kubernetes naming strategy — maps K8s::{Group}::{Kind} type names
+ * to user-friendly TypeScript class names.
+ */
+import { NamingStrategy as CoreNamingStrategy, } from "@intentius/chant/codegen/naming";
+import { k8sShortName, k8sServiceName } from "../spec/parse.js";
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+const k8sNamingConfig = {
+    priorityNames: {
+        // Core
+        "K8s::Core::Pod": "Pod",
+        "K8s::Core::Service": "Service",
+        "K8s::Core::ConfigMap": "ConfigMap",
+        "K8s::Core::Secret": "Secret",
+        "K8s::Core::Namespace": "Namespace",
+        "K8s::Core::ServiceAccount": "ServiceAccount",
+        "K8s::Core::PersistentVolume": "PersistentVolume",
+        "K8s::Core::PersistentVolumeClaim": "PersistentVolumeClaim",
+        "K8s::Core::Node": "Node",
+        "K8s::Core::Endpoints": "Endpoints",
+        "K8s::Core::ResourceQuota": "ResourceQuota",
+        "K8s::Core::LimitRange": "LimitRange",
+        "K8s::Core::ReplicationController": "ReplicationController",
+        // Apps
+        "K8s::Apps::Deployment": "Deployment",
+        "K8s::Apps::StatefulSet": "StatefulSet",
+        "K8s::Apps::DaemonSet": "DaemonSet",
+        "K8s::Apps::ReplicaSet": "ReplicaSet",
+        "K8s::Apps::ControllerRevision": "ControllerRevision",
+        // Batch
+        "K8s::Batch::Job": "Job",
+        "K8s::Batch::CronJob": "CronJob",
+        // Networking
+        "K8s::Networking::Ingress": "Ingress",
+        "K8s::Networking::IngressClass": "IngressClass",
+        "K8s::Networking::NetworkPolicy": "NetworkPolicy",
+        // RBAC
+        "K8s::Rbac::Role": "Role",
+        "K8s::Rbac::ClusterRole": "ClusterRole",
+        "K8s::Rbac::RoleBinding": "RoleBinding",
+        "K8s::Rbac::ClusterRoleBinding": "ClusterRoleBinding",
+        // Autoscaling
+        "K8s::Autoscaling::HorizontalPodAutoscaler": "HorizontalPodAutoscaler",
+        // Policy
+        "K8s::Policy::PodDisruptionBudget": "PodDisruptionBudget",
+        // Storage
+        "K8s::Storage::StorageClass": "StorageClass",
+        "K8s::Storage::CSIDriver": "CSIDriver",
+        // Scheduling
+        "K8s::Scheduling::PriorityClass": "PriorityClass",
+        // Coordination
+        "K8s::Coordination::Lease": "Lease",
+        // Discovery
+        "K8s::Discovery::EndpointSlice": "EndpointSlice",
+        // Certificates
+        "K8s::Certificates::CertificateSigningRequest": "CertificateSigningRequest",
+        // Admission
+        "K8s::Admissionregistration::ValidatingWebhookConfiguration": "ValidatingWebhookConfiguration",
+        "K8s::Admissionregistration::MutatingWebhookConfiguration": "MutatingWebhookConfiguration",
+        // Events (core vs events.k8s.io — the core version wins)
+        "K8s::Core::Event": "Event",
+        // Prometheus Operator's Probe CRD would collide with the core Probe property type
+        "K8s::Monitoring::Probe": "MonitoringProbe",
+        // Property types
+        "K8s::Core::Container": "Container",
+        "K8s::Core::ContainerPort": "ContainerPort",
+        "K8s::Core::EnvVar": "EnvVar",
+        "K8s::Core::EnvFromSource": "EnvFromSource",
+        "K8s::Core::Volume": "Volume",
+        "K8s::Core::VolumeMount": "VolumeMount",
+        "K8s::Core::PodSpec": "PodSpec",
+        "K8s::Core::PodTemplateSpec": "PodTemplateSpec",
+        "K8s::Core::ServicePort": "ServicePort",
+        "K8s::Core::Probe": "Probe",
+        "K8s::Core::ResourceRequirements": "ResourceRequirements",
+        "K8s::Core::SecurityContext": "SecurityContext",
+        "K8s::Core::PodSecurityContext": "PodSecurityContext",
+        "K8s::Core::Capabilities": "Capabilities",
+        "K8s::Core::ConfigMapKeySelector": "ConfigMapKeySelector",
+        "K8s::Core::SecretKeySelector": "SecretKeySelector",
+        "K8s::Core::EnvVarSource": "EnvVarSource",
+        "K8s::Core::ObjectReference": "ObjectReference",
+        "K8s::Core::LocalObjectReference": "LocalObjectReference",
+        "K8s::Core::Toleration": "Toleration",
+        "K8s::Core::Affinity": "Affinity",
+        "K8s::Core::TopologySpreadConstraint": "TopologySpreadConstraint",
+        "K8s::Core::PersistentVolumeClaimSpec": "PersistentVolumeClaimSpec",
+        "K8s::Core::HTTPGetAction": "HTTPGetAction",
+        "K8s::Core::TCPSocketAction": "TCPSocketAction",
+        "K8s::Core::ExecAction": "ExecAction",
+        "K8s::Core::HostAlias": "HostAlias",
+        "K8s::Core::EphemeralContainer": "EphemeralContainer",
+        "K8s::Core::KeyToPath": "KeyToPath",
+        "K8s::Apps::DeploymentStrategy": "DeploymentStrategy",
+        "K8s::Apps::RollingUpdateDeployment": "RollingUpdateDeployment",
+        "K8s::Networking::IngressRule": "IngressRule",
+        "K8s::Networking::IngressTLS": "IngressTLS",
+        "K8s::Networking::HTTPIngressPath": "HTTPIngressPath",
+        "K8s::Networking::IngressBackend": "IngressBackend",
+        "K8s::Networking::IngressServiceBackend": "IngressServiceBackend",
+        "K8s::Networking::ServiceBackendPort": "ServiceBackendPort",
+        "K8s::Networking::NetworkPolicyIngressRule": "NetworkPolicyIngressRule",
+        "K8s::Networking::NetworkPolicyEgressRule": "NetworkPolicyEgressRule",
+        "K8s::Networking::NetworkPolicyPeer": "NetworkPolicyPeer",
+        "K8s::Networking::NetworkPolicyPort": "NetworkPolicyPort",
+        "K8s::Rbac::PolicyRule": "PolicyRule",
+        "K8s::Rbac::RoleRef": "RoleRef",
+        "K8s::Rbac::Subject": "Subject",
+        "K8s::Autoscaling::MetricSpec": "MetricSpec",
+        "K8s::Autoscaling::HorizontalPodAutoscalerBehavior": "HorizontalPodAutoscalerBehavior",
+        "K8s::Policy::PodDisruptionBudgetSpec": "PodDisruptionBudgetSpec",
+        "K8s::Meta::ObjectMeta": "ObjectMeta",
+        "K8s::Meta::LabelSelector": "LabelSelector",
+        "K8s::Meta::LabelSelectorRequirement": "LabelSelectorRequirement",
+    },
+    priorityAliases: {
+        "K8s::Batch::Job": ["BatchJob"],
+        "K8s::Apps::Deployment": ["Deploy"],
+        "K8s::Core::ConfigMap": ["CM"],
+        "K8s::Core::ServiceAccount": ["SA"],
+        "K8s::Autoscaling::HorizontalPodAutoscaler": ["HPA"],
+        "K8s::Core::PersistentVolumeClaim": ["PVC"],
+        "K8s::Core::PersistentVolume": ["PV"],
+        "K8s::Policy::PodDisruptionBudget": ["PDB"],
+        "K8s::Core::Namespace": ["NS"],
+        "K8s::Apps::StatefulSet": ["STS"],
+        "K8s::Apps::DaemonSet": ["DS"],
+        "K8s::Core::Secret": ["Sec"],
+        "K8s::Networking::Ingress": ["Ing"],
+        "K8s::Networking::NetworkPolicy": ["NetPol"],
+    },
+    // Names published before the Prometheus Operator CRDs (v0.94.1) added colliding
+    // property types stay with their original owners; the new CRDs' types are prefixed.
+    priorityPropertyAliases: {
+        "K8s::Monitoring::ServiceMonitor": {
+            AttachMetadata: "AttachMetadata",
+            NamespaceSelector: "NamespaceSelector",
+            Selector: "Selector",
+        },
+        "K8s::Traefik::Middleware": { BasicAuth: "BasicAuth" },
+        "K8s::Addons::HelmChartProxy": { TlsConfig: "TlsConfig" },
+        "K8s::S3::Bucket": { Lifecycle: "Lifecycle" },
+    },
+    serviceAbbreviations: {
+        Core: "Core",
+        Apps: "Apps",
+        Batch: "Batch",
+        Networking: "Net",
+        Rbac: "Rbac",
+        Autoscaling: "AS",
+        Policy: "Pol",
+        Storage: "Stor",
+        Scheduling: "Sched",
+        Coordination: "Coord",
+        Discovery: "Disc",
+        Certificates: "Cert",
+        Admissionregistration: "Adm",
+    },
+    shortName: k8sShortName,
+    serviceName: k8sServiceName,
+};
+/**
+ * Kubernetes-specific naming strategy.
+ * Extends core NamingStrategy with K8s naming config.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+    constructor(results) {
+        const inputs = results.map((r) => ({
+            typeName: r.resource.typeName,
+            propertyTypes: r.propertyTypes,
+        }));
+        super(inputs, k8sNamingConfig);
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,36 @@
+/**
+ * Kubernetes lexicon packaging — delegates to core packagePipeline
+ * with K8s-specific manifest building and skill collection.
+ */
+import { readFileSync } from "fs";
+import { k8sPlugin } from "../plugin.js";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
+/**
+ * Package the Kubernetes lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: (_genResult) => {
+            return {
+                name: "k8s",
+                version: pkgJson.version ?? "0.0.0",
+                chantVersion: ">=0.1.0",
+                namespace: "K8s",
+                intrinsics: [],
+                pseudoParameters: {},
+            };
+        },
+        srcDir: pkgDir,
+        collectSkills: () => {
+            const skillDefs = k8sPlugin.skills?.() ?? [];
+            return collectSkills(skillDefs);
+        },
+        version: pkgJson.version ?? "0.0.0",
+    }, opts);
+}

package/dist/codegen/patches.js

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+/**
+ * Registry of known schema patches.
+ */
+export const schemaPatches = [
+    {
+        description: "Break infinite recursion in JSONSchemaProps by capping nested $ref depth",
+        path: "definitions.io.k8s.apiextensions-apiserver.pkg.apis.apiextensions.v1.JSONSchemaProps",
+        apply(def) {
+            var _a;
+            // 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;
+            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]) {
+                    (_a = props[key]).description ?? (_a.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) {
+    const applied = [];
+    const skipped = [];
+    for (const patch of schemaPatches) {
+        const segments = patch.path.split(".");
+        let target = schema;
+        for (const segment of segments) {
+            if (target && typeof target === "object" && segment in target) {
+                target = target[segment];
+            }
+            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/dist/codegen/typecheck.js

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

package/dist/codegen/versions.js

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import { fetchWithRetry } from "@intentius/chant/codegen/fetch";
+import { K8S_SCHEMA_VERSION } from "../spec/fetch.js";
+/**
+ * Pinned versions of external dependencies. The Kubernetes entry mirrors
+ * K8S_SCHEMA_VERSION in spec/fetch.ts, which is the version codegen downloads.
+ */
+export const PINNED_VERSIONS = {
+    k8sOpenAPI: K8S_SCHEMA_VERSION,
+};
+/**
+ * Build the raw GitHub URL for the K8s swagger.json for a given version.
+ */
+export function k8sSwaggerUrl(version) {
+    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() {
+    try {
+        const res = await fetchWithRetry("https://api.github.com/repos/kubernetes/kubernetes/releases/latest", undefined, undefined, { headers: { Accept: "application/vnd.github+json" } });
+        const data = (await res.json());
+        const latest = data.tag_name;
+        if (!latest)
+            return null;
+        return latest !== PINNED_VERSIONS.k8sOpenAPI ? latest : null;
+    }
+    catch {
+        // Transient failures are retried inside fetchWithRetry; permanent
+        // failures (or exhausted retries) land here — treat as up-to-date.
+        return null;
+    }
+}