@intentius/chant-lexicon-k8s 0.124.30 → 0.124.32

package/dist/lint/post-synth/crd-schema-helpers.js

@@ -0,0 +1,214 @@
+/**
+ * Shared helpers for the custom-resource spec checks (WK8501, WK8502) — chant #1372.
+ *
+ * A CRD's constructor takes `spec: Record<string, unknown>`, so a misspelled
+ * or wrong-typed field type-checks, serializes, and is accepted by the API
+ * server (which prunes what the structural schema does not know) — the
+ * controller then runs with a default nobody chose. The generated lexicon JSON
+ * carries each CRD's `spec` field schema (`specSchema`); these helpers walk a
+ * synthesized manifest against it and report what the schema would reject.
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { docsToManifests } from "./k8s-helpers.js";
+import { projectSpecSchema } from "../../project-kinds.js";
+let cachedRegistry = null;
+/** Registry key: `<apiVersion>/<kind>`, the pair a manifest carries verbatim. */
+function registryKey(apiVersion, kind) {
+    return `${apiVersion}/${kind}`;
+}
+/**
+ * Spec schemas of every CRD the lexicon ships, keyed by `apiVersion/kind`.
+ * Built-in kinds carry no `specSchema` and are never in the map.
+ */
+export function getCrdSchemaRegistry() {
+    if (cachedRegistry)
+        return cachedRegistry;
+    cachedRegistry = new Map();
+    try {
+        // Built lazily so importing this module stays edge-safe: `createRequire`
+        // throws where import.meta.url is undefined (bundled Workers), and there
+        // the registry is simply empty.
+        const require = createRequire(moduleSourceUrl(import.meta.url));
+        const lexicon = require("../../generated/lexicon-k8s.json");
+        for (const entry of Object.values(lexicon)) {
+            if (entry.kind === "resource" && entry.apiVersion && entry.gvkKind && entry.specSchema) {
+                cachedRegistry.set(registryKey(entry.apiVersion, entry.gvkKind), entry.specSchema);
+            }
+        }
+    }
+    catch {
+        // Lexicon JSON not yet generated — empty registry, checks pass.
+    }
+    return cachedRegistry;
+}
+/** Test seam: replace the registry (pass `null` to reload from the lexicon JSON). */
+export function setCrdSchemaRegistry(registry) {
+    cachedRegistry = registry;
+}
+/**
+ * The schema for a manifest's `apiVersion`/`kind`: one the project generated
+ * from its own CRDs (`chant generate`, ../../project-kinds.ts) first, then one
+ * the lexicon ships.
+ */
+export function specSchemaFor(manifest) {
+    if (typeof manifest.apiVersion !== "string" || typeof manifest.kind !== "string")
+        return undefined;
+    return (projectSpecSchema(manifest.apiVersion, manifest.kind) ??
+        getCrdSchemaRegistry().get(registryKey(manifest.apiVersion, manifest.kind)));
+}
+/** Every manifest in the build that has a shipped spec schema, with that schema. */
+export function customResources(ctx) {
+    const out = [];
+    for (const manifest of docsToManifests(ctx)) {
+        const schema = specSchemaFor(manifest);
+        if (schema)
+            out.push({ manifest, schema });
+    }
+    return out;
+}
+/**
+ * Walk `value` against `schema` and report every field the schema does not
+ * list (unless the enclosing object is `open`) and every scalar whose type or
+ * enum membership the schema rejects. Untyped nodes pass anything.
+ */
+export function validateSpec(value, schema, path = "spec") {
+    const findings = [];
+    walk(value, schema, path, findings);
+    return findings;
+}
+function walk(value, schema, path, out) {
+    if (value === null || value === undefined)
+        return;
+    // int-or-string and other deliberately untyped nodes accept anything.
+    if (!schema.type)
+        return;
+    switch (schema.type) {
+        case "object": {
+            if (typeof value !== "object" || Array.isArray(value)) {
+                out.push(mismatch(path, "an object", value));
+                return;
+            }
+            const obj = value;
+            for (const [name, child] of Object.entries(obj)) {
+                const childSchema = schema.fields?.[name];
+                if (childSchema) {
+                    walk(child, childSchema, `${path}.${name}`, out);
+                    continue;
+                }
+                if (schema.open)
+                    continue;
+                const known = Object.keys(schema.fields ?? {});
+                const suggestion = suggestField(name, known);
+                const hint = suggestion ? ` (did you mean "${suggestion}"?)` : "";
+                out.push({
+                    kind: "unknown-field",
+                    path: `${path}.${name}`,
+                    message: `unknown field "${path}.${name}"${hint}`,
+                });
+            }
+            return;
+        }
+        case "array": {
+            if (!Array.isArray(value)) {
+                out.push(mismatch(path, "an array", value));
+                return;
+            }
+            if (schema.items) {
+                value.forEach((item, i) => walk(item, schema.items, `${path}[${i}]`, out));
+            }
+            return;
+        }
+        case "string": {
+            if (typeof value !== "string") {
+                // `x-kubernetes-int-or-string` never reaches here (untyped); a plain
+                // string field given a number is a real mismatch the server coerces
+                // or rejects depending on version, so say so.
+                out.push(mismatch(path, "a string", value));
+                return;
+            }
+            checkEnum(value, schema, path, out);
+            return;
+        }
+        case "integer":
+        case "number": {
+            if (typeof value !== "number" || (schema.type === "integer" && !Number.isInteger(value))) {
+                out.push(mismatch(path, schema.type === "integer" ? "an integer" : "a number", value));
+                return;
+            }
+            checkEnum(value, schema, path, out);
+            return;
+        }
+        case "boolean": {
+            if (typeof value !== "boolean")
+                out.push(mismatch(path, "a boolean", value));
+            return;
+        }
+    }
+}
+function checkEnum(value, schema, path, out) {
+    if (!schema.enum || schema.enum.length === 0)
+        return;
+    if (schema.enum.includes(String(value)))
+        return;
+    out.push({
+        kind: "type-mismatch",
+        path,
+        message: `"${path}" must be one of ${schema.enum.map((v) => `"${v}"`).join(", ")}, got ${describe(value)}`,
+    });
+}
+function mismatch(path, expected, value) {
+    return {
+        kind: "type-mismatch",
+        path,
+        message: `"${path}" expects ${expected}, got ${describe(value)}`,
+    };
+}
+function describe(value) {
+    if (typeof value === "string")
+        return `string "${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return `${typeof value} ${String(value)}`;
+    if (Array.isArray(value))
+        return "an array";
+    if (value !== null && typeof value === "object")
+        return "an object";
+    return String(value);
+}
+/** Levenshtein distance between two strings. */
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/** Closest known field within Levenshtein distance 3 (case-insensitive), if any. */
+export function suggestField(unknown, known) {
+    let best;
+    let bestDist = 4;
+    for (const field of known) {
+        const dist = levenshtein(unknown.toLowerCase(), field.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = field;
+        }
+    }
+    return best;
+}
+/** `metadata.name` or the kind, for diagnostics. */
+export function resourceLabel(manifest) {
+    return manifest.metadata?.name ?? manifest.kind ?? "resource";
+}

package/dist/lint/post-synth/flux002.js

@@ -0,0 +1,56 @@
+import { allManifests, manifestsOfKind } from "./argo-helpers.js";
+/** Source kinds the kustomize-controller can reconcile from. */
+const SOURCE_KINDS = ["GitRepository", "OCIRepository", "Bucket"];
+/** The GitRepository `flux bootstrap` creates alongside the controllers. */
+const BOOTSTRAP_SOURCE_NAME = "flux-system";
+export const flux002 = {
+    id: "FLUX002",
+    description: "Kustomization.spec.sourceRef must reference a declared source (or the bootstrap flux-system repo)",
+    check(ctx) {
+        const diagnostics = [];
+        const manifests = allManifests(ctx);
+        // Declared sources, keyed "Kind/name". Namespace is deliberately ignored:
+        // an unset sourceRef.namespace resolves in the Kustomization's own, and
+        // the common estate keeps everything in flux-system anyway.
+        const declaredSources = new Set();
+        for (const kind of SOURCE_KINDS) {
+            for (const source of manifestsOfKind(manifests, kind)) {
+                const name = source.metadata?.name;
+                if (typeof name === "string")
+                    declaredSources.add(`${kind}/${name}`);
+            }
+        }
+        for (const kustomization of manifestsOfKind(manifests, "Kustomization")) {
+            // Flux and kustomize.config.k8s.io share the kind name; only the Flux CR
+            // carries a sourceRef-bearing spec.
+            const apiVersion = kustomization.apiVersion;
+            if (typeof apiVersion === "string" && !apiVersion.startsWith("kustomize.toolkit.fluxcd.io/"))
+                continue;
+            const name = kustomization.metadata?.name ?? "Kustomization";
+            const sourceRef = kustomization.spec?.sourceRef;
+            if (!sourceRef || typeof sourceRef.name !== "string" || sourceRef.name === "") {
+                diagnostics.push({
+                    checkId: "FLUX002",
+                    severity: "error",
+                    message: `Kustomization "${name}" has no spec.sourceRef.name — the kustomize-controller cannot resolve a source.`,
+                    entity: name,
+                    lexicon: "k8s",
+                });
+                continue;
+            }
+            const kind = typeof sourceRef.kind === "string" && sourceRef.kind !== "" ? sourceRef.kind : "GitRepository";
+            if (kind === "GitRepository" && sourceRef.name === BOOTSTRAP_SOURCE_NAME)
+                continue;
+            if (declaredSources.has(`${kind}/${sourceRef.name}`))
+                continue;
+            diagnostics.push({
+                checkId: "FLUX002",
+                severity: "error",
+                message: `Kustomization "${name}" references ${kind} "${sourceRef.name}", which is not declared. Declare the source (e.g. FluxGitSource) or point sourceRef at the bootstrap flux-system repo.`,
+                entity: name,
+                lexicon: "k8s",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/flux003.js

@@ -0,0 +1,50 @@
+import { allManifests, manifestsOfKind } from "./argo-helpers.js";
+/** Flux Kustomizations only — the kustomize.config.k8s.io kind shares the name. */
+function fluxKustomizations(manifests) {
+    return manifestsOfKind(manifests, "Kustomization").filter((m) => {
+        const apiVersion = m.apiVersion;
+        return typeof apiVersion !== "string" || apiVersion.startsWith("kustomize.toolkit.fluxcd.io/");
+    });
+}
+export const flux003 = {
+    id: "FLUX003",
+    description: "Kustomization.spec.dependsOn entries should name Kustomizations declared in the build",
+    check(ctx) {
+        const diagnostics = [];
+        const kustomizations = fluxKustomizations(allManifests(ctx));
+        const declared = new Set(kustomizations
+            .map((k) => k.metadata?.name)
+            .filter((n) => typeof n === "string"));
+        for (const kustomization of kustomizations) {
+            const name = kustomization.metadata?.name ?? "Kustomization";
+            const dependsOn = kustomization.spec?.dependsOn;
+            if (!Array.isArray(dependsOn))
+                continue;
+            for (const entry of dependsOn) {
+                const depName = entry?.name;
+                if (typeof depName !== "string" || depName === "")
+                    continue;
+                if (depName === name) {
+                    diagnostics.push({
+                        checkId: "FLUX003",
+                        severity: "warning",
+                        message: `Kustomization "${name}" depends on itself — Flux can never satisfy the edge and the app will not reconcile.`,
+                        entity: name,
+                        lexicon: "k8s",
+                    });
+                    continue;
+                }
+                if (declared.has(depName))
+                    continue;
+                diagnostics.push({
+                    checkId: "FLUX003",
+                    severity: "warning",
+                    message: `Kustomization "${name}" depends on Kustomization "${depName}", which nothing in the build declares — reconciliation stalls until it exists. Fix the name, or ignore if it is declared in another repo.`,
+                    entity: name,
+                    lexicon: "k8s",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/index.js

@@ -0,0 +1,104 @@
+import { argo002 } from "./argo002.js";
+import { argo003 } from "./argo003.js";
+import { argo005 } from "./argo005.js";
+import { flux002 } from "./flux002.js";
+import { flux003 } from "./flux003.js";
+import { wk8005 } from "./wk8005.js";
+import { wk8006 } from "./wk8006.js";
+import { wk8041 } from "./wk8041.js";
+import { wk8042 } from "./wk8042.js";
+import { wk8101 } from "./wk8101.js";
+import { wk8102 } from "./wk8102.js";
+import { wk8103 } from "./wk8103.js";
+import { wk8104 } from "./wk8104.js";
+import { wk8105 } from "./wk8105.js";
+import { wk8201 } from "./wk8201.js";
+import { wk8202 } from "./wk8202.js";
+import { wk8203 } from "./wk8203.js";
+import { wk8204 } from "./wk8204.js";
+import { wk8205 } from "./wk8205.js";
+import { wk8207 } from "./wk8207.js";
+import { wk8208 } from "./wk8208.js";
+import { wk8209 } from "./wk8209.js";
+import { wk8301 } from "./wk8301.js";
+import { wk8302 } from "./wk8302.js";
+import { wk8303 } from "./wk8303.js";
+import { wk8304 } from "./wk8304.js";
+import { wk8305 } from "./wk8305.js";
+import { wk8306 } from "./wk8306.js";
+import { wk8401 } from "./wk8401.js";
+import { wk8402 } from "./wk8402.js";
+import { wk8403 } from "./wk8403.js";
+import { wk8404 } from "./wk8404.js";
+import { wk8405 } from "./wk8405.js";
+import { wk8406 } from "./wk8406.js";
+import { wk8407 } from "./wk8407.js";
+import { wk8501 } from "./wk8501.js";
+import { wk8502 } from "./wk8502.js";
+import { wk8503 } from "./wk8503.js";
+import { wk8504 } from "./wk8504.js";
+import { wk8505 } from "./wk8505.js";
+import { wk8601 } from "./wk8601.js";
+import { wk8602 } from "./wk8602.js";
+import { wk8603 } from "./wk8603.js";
+import { wk8604 } from "./wk8604.js";
+import { wk8605 } from "./wk8605.js";
+import { wk8606 } from "./wk8606.js";
+import { wk8701 } from "./wk8701.js";
+import { wk8702 } from "./wk8702.js";
+import { wk8703 } from "./wk8703.js";
+import { wk8704 } from "./wk8704.js";
+import { wk8705 } from "./wk8705.js";
+export const postSynthChecks = [
+    argo002,
+    argo003,
+    argo005,
+    flux002,
+    flux003,
+    wk8005,
+    wk8006,
+    wk8041,
+    wk8042,
+    wk8101,
+    wk8102,
+    wk8103,
+    wk8104,
+    wk8105,
+    wk8201,
+    wk8202,
+    wk8203,
+    wk8204,
+    wk8205,
+    wk8207,
+    wk8208,
+    wk8209,
+    wk8301,
+    wk8302,
+    wk8303,
+    wk8304,
+    wk8305,
+    wk8306,
+    wk8401,
+    wk8402,
+    wk8403,
+    wk8404,
+    wk8405,
+    wk8406,
+    wk8407,
+    wk8501,
+    wk8502,
+    wk8503,
+    wk8504,
+    wk8505,
+    wk8601,
+    wk8602,
+    wk8603,
+    wk8604,
+    wk8605,
+    wk8606,
+    wk8701,
+    wk8702,
+    wk8703,
+    wk8704,
+    wk8705,
+];

package/dist/lint/post-synth/k8s-helpers.js

@@ -0,0 +1,186 @@
+/**
+ * Shared helpers for Kubernetes post-synthesis lint rules.
+ *
+ * Provides the `ctx.docs` → `K8sManifest[]` bridge every check reads through,
+ * and container extraction logic that handles all common workload types.
+ */
+import { parseOutputDocs } from "@intentius/chant/lint/post-synth";
+export { getPrimaryOutput, getAdditionalFiles } from "@intentius/chant/lint/post-synth";
+/**
+ * Every parsed Kubernetes manifest across all lexicon outputs, via `ctx.docs`
+ * (chant #975) — the shared, parse-once view every k8s post-synth check
+ * reads, in place of the old per-check `parseK8sManifests(getPrimaryOutput(output))`
+ * splitter (chant #976). Two documents are dropped rather than passed through
+ * as a "manifest":
+ *
+ * - `d.error` — a document `parseOutputDocs` could not make sense of.
+ * - `d.file` — a document that came from a `SerializerResult.files` sidecar
+ *   (a committed-encrypted secret's ciphertext, in this lexicon) rather than
+ *   a lexicon's primary output. `parseK8sManifests` only ever saw
+ *   `getPrimaryOutput(output)`, so a sidecar was invisible to every general
+ *   manifest-consuming check — see `getAdditionalFiles`'s doc comment on why
+ *   that separation is deliberate. Only `sops-helpers.ts`'s
+ *   `resolveEncryptedSecretClaims` (WK8504/WK8503's producer join) reads
+ *   `.files` explicitly; this bridge must keep it that way.
+ *
+ * `ctx.docs` is populated by every context chant itself builds (`chant
+ * build`, `@intentius/chant-test-utils`'s `createPostSynthContext` /
+ * `makePostSynthCtx*`) — see `PostSynthContext.docs`'s doc comment for why
+ * it is still optional at the type level. A handful of this lexicon's own
+ * hand-rolled `PostSynthContext` test literals (`post-synth.test.ts`'s
+ * `makeCtx`) predate that field and never set it; for those, fall back to
+ * parsing `ctx.outputs` directly with the same `parseOutputDocs` primitive,
+ * rather than silently returning no manifests.
+ */
+export function docsToManifests(ctx) {
+    const docs = ctx.docs ?? parseOutputDocs(ctx.outputs);
+    return docs
+        .filter((d) => !d.error && !d.file)
+        .map((d) => d.value);
+}
+/**
+ * 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) {
+    const kind = manifest.kind;
+    const spec = manifest.spec;
+    if (!spec)
+        return null;
+    switch (kind) {
+        case "Pod":
+            return spec;
+        case "Deployment":
+        case "StatefulSet":
+        case "DaemonSet":
+        case "Job": {
+            const template = spec.template;
+            return template?.spec ?? null;
+        }
+        case "CronJob": {
+            const jobTemplate = spec.jobTemplate;
+            const jobSpec = jobTemplate?.spec;
+            const template = jobSpec?.template;
+            return template?.spec ?? null;
+        }
+        // KServe ServingRuntime/ClusterServingRuntime carry `containers` and
+        // `tolerations` directly on spec — no template wrapper, unlike the
+        // built-in workload kinds above.
+        case "ServingRuntime":
+        case "ClusterServingRuntime":
+            return spec;
+        default:
+            return null;
+    }
+}
+/**
+ * Extract all containers (including init containers) from a workload manifest.
+ */
+export function extractContainers(manifest) {
+    const podSpec = extractPodSpec(manifest);
+    if (!podSpec)
+        return [];
+    const containers = [];
+    if (Array.isArray(podSpec.containers)) {
+        for (const c of podSpec.containers) {
+            if (typeof c === "object" && c !== null) {
+                containers.push(c);
+            }
+        }
+    }
+    if (Array.isArray(podSpec.initContainers)) {
+        for (const c of podSpec.initContainers) {
+            if (typeof c === "object" && c !== null) {
+                containers.push(c);
+            }
+        }
+    }
+    return containers;
+}
+/**
+ * Workload kinds that contain pod templates.
+ */
+export const WORKLOAD_KINDS = new Set([
+    "Pod",
+    "Deployment",
+    "StatefulSet",
+    "DaemonSet",
+    "Job",
+    "CronJob",
+]);
+/**
+ * Workload kinds that can request `nvidia.com/gpu` — the built-in workload
+ * kinds plus KServe's ServingRuntime/ClusterServingRuntime, which declare
+ * `containers`/`tolerations` directly on spec (see `extractPodSpec`).
+ */
+export const GPU_POD_KINDS = new Set([
+    ...WORKLOAD_KINDS,
+    "ServingRuntime",
+    "ClusterServingRuntime",
+]);
+/** Resource name used for GPU requests/limits across the lexicon. */
+export const NVIDIA_GPU_RESOURCE = "nvidia.com/gpu";
+/**
+ * True when any container in `containers` requests or limits
+ * `nvidia.com/gpu`.
+ */
+export function requestsGpu(containers) {
+    return containers.some((c) => {
+        const requests = c.resources?.requests;
+        const limits = c.resources?.limits;
+        return Boolean(requests?.[NVIDIA_GPU_RESOURCE]) || Boolean(limits?.[NVIDIA_GPU_RESOURCE]);
+    });
+}
+/**
+ * True when `tolerations` includes one that tolerates the `nvidia.com/gpu`
+ * taint — either an explicit `key: "nvidia.com/gpu"` toleration, or a
+ * wildcard `{ operator: "Exists" }` with no key (tolerates every taint).
+ */
+export function toleratesGpu(tolerations) {
+    if (!Array.isArray(tolerations))
+        return false;
+    return tolerations.some((t) => t.key === NVIDIA_GPU_RESOURCE || (t.operator === "Exists" && !t.key));
+}
+/**
+ * Parse a Kubernetes memory string to bytes.
+ *
+ * Handles binary suffixes (Ki, Mi, Gi, Ti) and SI suffixes (K, M, G, T).
+ * Returns NaN for unrecognised strings — callers should skip checks on NaN.
+ *
+ * @example
+ * parseMemoryBytes("4Gi")  // 4294967296
+ * parseMemoryBytes("512Mi") // 536870912
+ * parseMemoryBytes("2048") // 2048
+ */
+export function parseMemoryBytes(s) {
+    const m = /^([0-9]+(?:\.[0-9]+)?)(Ki|Mi|Gi|Ti|K|M|G|T)?$/.exec(s.trim());
+    if (!m)
+        return NaN;
+    const n = parseFloat(m[1]);
+    const multipliers = {
+        Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4,
+        K: 1000, M: 1000 ** 2, G: 1000 ** 3, T: 1000 ** 4,
+    };
+    return n * (multipliers[m[2] ?? ""] ?? 1);
+}
+/**
+ * Extract the Ray version from an image tag.
+ *
+ * Looks for a semver-style version prefix in the image tag:
+ *   "rayproject/ray:2.40.0"          → "2.40.0"
+ *   "rayproject/ray:2.40.0-py310"    → "2.40.0"
+ *   "us-docker.pkg.dev/.../ray:2.9.3-gpu" → "2.9.3"
+ *   "rayproject/ray:latest"          → undefined
+ *
+ * Returns undefined when no version can be found.
+ */
+export function extractRayVersion(image) {
+    const tag = image.includes(":") ? image.split(":").pop() : image;
+    const m = /^([0-9]+\.[0-9]+\.[0-9]+)/.exec(tag);
+    return m ? m[1] : undefined;
+}