@intentius/chant-lexicon-cpln 0.53.0

package/dist/rules/cpl023-container-resources.ts

@@ -0,0 +1,87 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf, readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, parseCpuMillicores, parseMemoryMib } from "./helpers";
+
+/** The tag that raises the memory-to-CPU ceiling from 8 to 32. */
+const RELAX_RATIO_TAG = "cpln/relaxMemoryToCpuRatio";
+
+const CPU_MIN_MILLICORES = 25;
+const MEMORY_MIN_MIB = 32;
+const RATIO_MAX = 8;
+const RATIO_MAX_RELAXED = 32;
+
+/**
+ * CPL023: CPU and memory floors, and the memory-to-CPU ratio.
+ *
+ * The ratio is the non-obvious one. `memory(MiB) / cpu(millicores)` must be
+ * ≤ 8, so `2Gi` of memory needs at least 256 millicores of CPU — a workload
+ * asking for lots of memory and a little CPU is rejected, which surprises
+ * people coming from Kubernetes where the two are independent. The
+ * `cpln/relaxMemoryToCpuRatio` tag raises the ceiling to 32.
+ */
+export const containerResourcesCheck: PostSynthCheck = {
+  id: "CPL023",
+  description: "Container CPU and memory must clear the platform floors and the memory-to-CPU ratio",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const tags = propsOf(entity).tags;
+      const relaxed = !!tags && typeof tags === "object" && RELAX_RATIO_TAG in (tags as Record<string, unknown>);
+      const ceiling = relaxed ? RATIO_MAX_RELAXED : RATIO_MAX;
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        // Control Plane's defaults, so an omitted value is checked as what it
+        // will actually become rather than skipped.
+        const cpu = parseCpuMillicores(readString(container, "cpu") ?? "50m");
+        const memory = parseMemoryMib(readString(container, "memory") ?? "128Mi");
+
+        if (cpu !== undefined && cpu < CPU_MIN_MILLICORES) {
+          diagnostics.push({
+            checkId: "CPL023",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" requests ${cpu}m CPU; the minimum is ` +
+              `${CPU_MIN_MILLICORES}m.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        if (memory !== undefined && memory < MEMORY_MIN_MIB) {
+          diagnostics.push({
+            checkId: "CPL023",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" requests ${Math.round(memory)}Mi memory; ` +
+              `the minimum is ${MEMORY_MIN_MIB}Mi.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        if (cpu !== undefined && memory !== undefined && cpu > 0) {
+          const ratio = memory / cpu;
+          if (ratio > ceiling) {
+            const needed = Math.ceil(memory / ceiling);
+            diagnostics.push({
+              checkId: "CPL023",
+              severity: "error",
+              message:
+                `Workload "${name}" container "${containerName}" has a memory-to-CPU ratio of ` +
+                `${ratio.toFixed(1)} (${Math.round(memory)}Mi / ${cpu}m), above the limit of ${ceiling}. ` +
+                `Raise CPU to at least ${needed}m` +
+                (relaxed ? "." : `, or add the \`${RELAX_RATIO_TAG}\` tag to raise the ceiling to ${RATIO_MAX_RELAXED}.`),
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl024-probe-handler.ts

@@ -0,0 +1,51 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readPath, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/** The four mutually exclusive probe handlers. */
+const PROBE_HANDLERS = ["exec", "grpc", "tcpSocket", "httpGet"] as const;
+
+/**
+ * CPL024: a probe must set exactly one handler.
+ *
+ * Zero is the interesting case: a `readinessProbe` with only
+ * `initialDelaySeconds` and `periodSeconds` set looks configured and probes
+ * nothing.
+ */
+export const probeHandlerCheck: PostSynthCheck = {
+  id: "CPL024",
+  description: "Each health-check probe must set exactly one of exec, grpc, tcpSocket, httpGet",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+
+        for (const probeName of ["readinessProbe", "livenessProbe"]) {
+          const probe = readPath(container, probeName);
+          if (!probe || typeof probe !== "object") continue;
+
+          const set = PROBE_HANDLERS.filter((handler) => readPath(probe, handler) !== undefined);
+          if (set.length === 1) continue;
+
+          diagnostics.push({
+            checkId: "CPL024",
+            severity: "error",
+            message:
+              set.length === 0
+                ? `Workload "${name}" container "${containerName}" declares a ${probeName} with no handler. ` +
+                  `Set exactly one of ${PROBE_HANDLERS.join(", ")} — as written the probe checks nothing.`
+                : `Workload "${name}" container "${containerName}" ${probeName} sets ${set.length} handlers ` +
+                  `(${set.join(", ")}). They are mutually exclusive; keep one.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl025-autoscaling-shape.ts

@@ -0,0 +1,100 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readNumber, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/** Which strategies each workload type supports at all. */
+const SUPPORTED_METRICS: Record<string, string[]> = {
+  serverless: ["concurrency", "rps", "cpu", "memory", "disabled"],
+  standard: ["rps", "cpu", "memory", "latency", "keda", "disabled"],
+  stateful: ["rps", "cpu", "memory", "latency", "keda", "disabled"],
+};
+
+/**
+ * CPL025: mutually exclusive autoscaling fields, and the `target` ceiling.
+ *
+ * `metric` and `multi` are alternatives, not layers; `target` belongs to the
+ * single-metric form and is rejected alongside `multi`; and with cpu or memory
+ * as the metric, `target` is a utilization percentage, so above 100 it is not
+ * an aggressive setting but an invalid one.
+ */
+export const autoscalingShapeCheck: PostSynthCheck = {
+  id: "CPL025",
+  description: "Autoscaling `metric`, `multi` and `target` must form a valid combination",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const scaling = autoscalingOf(entity);
+      if (!scaling || typeof scaling !== "object") continue;
+
+      const metric = readString(scaling, "metric");
+      const multi = readArray(scaling, "multi");
+      const target = readNumber(scaling, "target");
+      const type = workloadType(entity);
+
+      if (metric && multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets both autoscaling.metric ("${metric}") and autoscaling.multi. ` +
+            `They are mutually exclusive — multi is the multi-metric form and replaces metric.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (target !== undefined && multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets autoscaling.target alongside autoscaling.multi. ` +
+            `Each entry in multi carries its own target.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (target !== undefined && (metric === "cpu" || metric === "memory") && target > 100) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets autoscaling.target ${target} with metric "${metric}", which is a ` +
+            `utilization percentage capped at 100.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      const supported = SUPPORTED_METRICS[type];
+      if (metric && supported && !supported.includes(metric)) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" is type "${type}" and uses autoscaling metric "${metric}", which that type ` +
+            `does not support. Available: ${supported.join(", ")}.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (multi.length > 0 && type === "serverless") {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" is serverless and uses multi-metric autoscaling, which is available only ` +
+            `on standard and stateful workloads.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl026-scale-to-zero.ts

@@ -0,0 +1,67 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readNumber, readPath, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/** Strategies that let a workload scale to zero, by workload type. */
+const SCALE_TO_ZERO: Record<string, string[]> = {
+  serverless: ["rps", "concurrency"],
+  standard: ["keda"],
+  stateful: ["keda"],
+};
+
+/**
+ * CPL026: scale-to-zero that will not happen.
+ *
+ * `minScale: 0` is accepted on any workload type. It only *takes effect* for
+ * serverless with `rps` or `concurrency`, or for standard/stateful under KEDA.
+ * Everywhere else the workload holds at one replica and the cost saving that
+ * motivated the setting never arrives — with nothing reported.
+ */
+export const scaleToZeroCheck: PostSynthCheck = {
+  id: "CPL026",
+  description: "minScale 0 must pair with a strategy that can actually scale to zero",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const scaling = autoscalingOf(entity);
+      if (!scaling || typeof scaling !== "object") continue;
+      if (readNumber(scaling, "minScale") !== 0) continue;
+
+      const type = workloadType(entity);
+      const metric = readString(scaling, "metric") ?? (type === "serverless" ? "concurrency" : undefined);
+
+      if (type === "cron") {
+        diagnostics.push({
+          checkId: "CPL026",
+          severity: "error",
+          message: `Cron workload "${name}" sets minScale 0. Cron workloads cannot scale to zero.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+        continue;
+      }
+
+      const allowed = SCALE_TO_ZERO[type] ?? [];
+      const usingKeda = metric === "keda" || readPath(scaling, "keda") !== undefined;
+      if (allowed.includes(metric ?? "") || (allowed.includes("keda") && usingKeda)) continue;
+
+      diagnostics.push({
+        checkId: "CPL026",
+        severity: "warning",
+        message:
+          `Workload "${name}" (type "${type}") sets minScale 0 with metric "${metric ?? "unset"}", which ` +
+          `cannot scale to zero. ` +
+          (type === "serverless"
+            ? `Serverless scales to zero only with "rps" or "concurrency".`
+            : `Standard and stateful workloads scale to zero only under KEDA, which must be enabled on the GVC.`) +
+          ` As written the workload holds at one replica with no error.`,
+        entity: name,
+        lexicon: "cpln",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl027-capacity-ai-conflict.ts

@@ -0,0 +1,78 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readBoolean, readPath, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/**
+ * CPL027: Capacity AI combined with something it excludes.
+ *
+ * Capacity AI resizes CPU and memory from observed usage, and it is **on by
+ * default** for serverless, standard and cron — so these conflicts are usually
+ * reached by adding CPU autoscaling or a GPU to a workload that never opted
+ * into Capacity AI in the first place. Each conflict has the same root: the
+ * other feature needs a stable resource baseline that Capacity AI is actively
+ * moving.
+ */
+export const capacityAiConflictCheck: PostSynthCheck = {
+  id: "CPL027",
+  description: "Capacity AI conflicts with CPU-utilization autoscaling, multi-metric autoscaling and GPUs",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const type = workloadType(entity);
+      // Default-on for every type except stateful, so `undefined` means enabled
+      // for those — which is exactly how these conflicts get reached unnoticed.
+      const declared = readBoolean(entity, "spec", "defaultOptions", "capacityAI");
+      const enabled = declared ?? type !== "stateful";
+      if (!enabled) continue;
+
+      const implicit = declared === undefined;
+      const how = implicit ? "Capacity AI is on by default for this workload type and" : "Capacity AI";
+
+      const scaling = autoscalingOf(entity);
+      const metric = scaling && typeof scaling === "object" ? readString(scaling, "metric") : undefined;
+      const multi = scaling && typeof scaling === "object" ? readArray(scaling, "multi") : [];
+
+      if (metric === "cpu") {
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}": ${how} conflicts with CPU-utilization autoscaling — dynamic CPU allocation ` +
+            `moves the baseline the metric scales against. Set defaultOptions.capacityAI false, or scale on ` +
+            `rps or memory.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}": ${how} conflicts with multi-metric autoscaling, which requires stable ` +
+            `resource baselines. Set defaultOptions.capacityAI false.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        if (readPath(container, "gpu") === undefined) continue;
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}" container "${readString(container, "name") ?? "?"}" requests a GPU, and ` +
+            `${how} conflicts with it — GPU allocation is fixed. Set defaultOptions.capacityAI false.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl028-volume-set.ts

@@ -0,0 +1,183 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readNumber, readString } from "../../entity-props";
+import { GVC, VOLUMESET, WORKLOAD, entitiesOfType } from "./helpers";
+
+/** Minimum initial capacity in GB, by performance class. */
+const MIN_CAPACITY_GB: Record<string, number> = {
+  "general-purpose-ssd": 10,
+  "high-throughput-ssd": 200,
+  shared: 10,
+};
+
+const MAX_CAPACITY_GB = 65_536;
+
+/** Filesystems that bind to exactly one stateful workload. */
+const EXCLUSIVE_FILESYSTEMS = new Set(["ext4", "xfs"]);
+
+/** Control Plane caps a workload at 15 volumes. */
+const MAX_VOLUMES = 15;
+
+const VOLUMESET_URI = /^cpln:\/\/volumeset\/(.+)$/;
+
+export const volumeSetCheck: PostSynthCheck = {
+  id: "CPL028",
+  description: "Volume set capacity, filesystem binding, and workload mount rules",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Volume sets by their declared name, so a mount can be checked against the
+    // set it names rather than only against itself.
+    const volumeSets = new Map<string, { entity: unknown; gvc?: string; fileSystemType: string }>();
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, VOLUMESET)) {
+      const declaredName = readString(entity, "name") ?? name;
+      const fileSystemType = readString(entity, "spec", "fileSystemType") ?? "ext4";
+      volumeSets.set(declaredName, { entity, gvc: readString(entity, "gvc"), fileSystemType });
+
+      const performanceClass =
+        readString(entity, "spec", "performanceClass") ?? (fileSystemType === "shared" ? "shared" : "general-purpose-ssd");
+      const capacity = readNumber(entity, "spec", "initialCapacity");
+
+      const floor = MIN_CAPACITY_GB[performanceClass];
+      if (capacity !== undefined && floor !== undefined && capacity < floor) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message:
+            `Volume set "${name}" requests ${capacity} GB with performanceClass "${performanceClass}", ` +
+            `below its ${floor} GB minimum. performanceClass is immutable after creation, so correcting ` +
+            `this later means recreating the volume set and losing its data.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (capacity !== undefined && capacity > MAX_CAPACITY_GB) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Volume set "${name}" requests ${capacity} GB, above the ${MAX_CAPACITY_GB} GB maximum.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (fileSystemType === "shared" && performanceClass !== "shared") {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "warning",
+          message:
+            `Volume set "${name}" has fileSystemType "shared" but performanceClass "${performanceClass}". ` +
+            `Control Plane forces "shared" for a shared filesystem, so the declared value will not match ` +
+            `what comes back and will read as drift on every plan.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      // Custom encryption is AWS KMS on a block device; a shared filesystem has
+      // no device to encrypt.
+      if (fileSystemType === "shared" && readString(entity, "spec", "customEncryption", "secretLink")) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Volume set "${name}" sets customEncryption with fileSystemType "shared"; it is supported on ext4 and xfs only.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const type = readString(entity, "spec", "type") ?? "serverless";
+      const workloadGvc = readString(entity, "gvc");
+      const paths: string[] = [];
+      let mountCount = 0;
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+
+        for (const volume of readArray(container, "volumes")) {
+          mountCount++;
+          const uri = readString(volume, "uri");
+          const path = readString(volume, "path");
+          if (path) paths.push(path);
+
+          const match = uri ? VOLUMESET_URI.exec(uri) : null;
+          if (!match) continue;
+
+          const target = volumeSets.get(match[1]);
+          if (!target) continue; // declared elsewhere; CPL029 covers dangling references
+
+          if (EXCLUSIVE_FILESYSTEMS.has(target.fileSystemType) && type !== "stateful") {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" is type "${type}" and container "${containerName}" mounts volume set ` +
+                `"${match[1]}", whose fileSystemType "${target.fileSystemType}" binds to exactly one ` +
+                `stateful workload. Use a "shared" volume set, or make the workload stateful.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+
+          if (target.gvc && workloadGvc && target.gvc !== workloadGvc) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" (GVC "${workloadGvc}") mounts volume set "${match[1]}" from GVC ` +
+                `"${target.gvc}". Volume sets are only mountable from within their own GVC.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+
+      if (mountCount > MAX_VOLUMES) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Workload "${name}" mounts ${mountCount} volumes; the maximum is ${MAX_VOLUMES}.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      for (const [i, path] of paths.entries()) {
+        for (const other of paths.slice(i + 1)) {
+          if (path === other) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message: `Workload "${name}" mounts two volumes at the same path "${path}".`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          } else if (isParentPath(path, other) || isParentPath(other, path)) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" mounts volumes at "${path}" and "${other}"; no mount path may be a ` +
+                `parent of another.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+/** Whether `parent` is a proper ancestor directory of `child`. */
+function isParentPath(parent: string, child: string): boolean {
+  const normalized = parent.endsWith("/") ? parent : `${parent}/`;
+  return child.startsWith(normalized);
+}