@intentius/chant-lexicon-k8s 0.0.12

package/dist/rules/hardcoded-namespace.ts

@@ -0,0 +1,56 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * WK8001: Hardcoded Namespace
+ *
+ * Detects hardcoded namespace strings in Kubernetes resource constructors.
+ * Namespaces should be parameterized or derived from configuration, not
+ * hardcoded as string literals.
+ *
+ * Bad:  new Deployment({ metadata: { namespace: "production" } })
+ * Good: new Deployment({ metadata: { namespace: config.namespace } })
+ */
+export const hardcodedNamespaceRule: LintRule = {
+  id: "WK8001",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "Detects hardcoded namespace strings — namespaces should be parameterized",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for property assignments like `namespace: "production"`
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "namespace" &&
+        ts.isStringLiteral(node.initializer)
+      ) {
+        const value = node.initializer.text;
+        // Skip empty strings — those are likely intentional placeholders
+        if (value !== "") {
+          const { line, character } =
+            sourceFile.getLineAndCharacterOfPosition(
+              node.initializer.getStart(),
+            );
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "WK8001",
+            severity: "warning",
+            message: `Hardcoded namespace "${value}" detected. Use a variable or configuration parameter instead.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/k8s-helpers.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared helpers for Kubernetes post-synthesis lint rules.
+ *
+ * Provides YAML parsing for multi-document K8s manifests and container
+ * extraction logic that handles all common workload types.
+ */
+
+import { parseYAML } from "@intentius/chant/yaml";
+export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+/**
+ * A parsed Kubernetes manifest (loosely typed).
+ */
+export interface K8sManifest {
+  apiVersion?: string;
+  kind?: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  spec?: Record<string, unknown>;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * A Kubernetes container spec (loosely typed).
+ */
+export interface K8sContainer {
+  name?: string;
+  image?: string;
+  env?: Array<{ name?: string; value?: unknown; valueFrom?: unknown }>;
+  ports?: Array<{ name?: string; containerPort?: number; [key: string]: unknown }>;
+  resources?: {
+    limits?: Record<string, unknown>;
+    requests?: Record<string, unknown>;
+  };
+  securityContext?: Record<string, unknown>;
+  livenessProbe?: unknown;
+  readinessProbe?: unknown;
+  imagePullPolicy?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Split a multi-document YAML string on `---` boundaries and parse each
+ * document into a K8sManifest.
+ */
+export function parseK8sManifests(yaml: string): K8sManifest[] {
+  const documents = yaml.split(/\n---\n/);
+  const manifests: K8sManifest[] = [];
+
+  for (const doc of documents) {
+    const trimmed = doc.trim();
+    if (trimmed === "" || trimmed === "---") continue;
+    try {
+      const parsed = parseYAML(trimmed);
+      if (typeof parsed === "object" && parsed !== null) {
+        manifests.push(parsed as K8sManifest);
+      }
+    } catch {
+      // Skip unparseable documents
+    }
+  }
+
+  return manifests;
+}
+
+/**
+ * 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: K8sManifest,
+): Record<string, unknown> | null {
+  const kind = manifest.kind;
+  const spec = manifest.spec;
+  if (!spec) return null;
+
+  switch (kind) {
+    case "Pod":
+      return spec as Record<string, unknown>;
+
+    case "Deployment":
+    case "StatefulSet":
+    case "DaemonSet":
+    case "Job": {
+      const template = spec.template as Record<string, unknown> | undefined;
+      return (template?.spec as Record<string, unknown>) ?? null;
+    }
+
+    case "CronJob": {
+      const jobTemplate = spec.jobTemplate as Record<string, unknown> | undefined;
+      const jobSpec = jobTemplate?.spec as Record<string, unknown> | undefined;
+      const template = jobSpec?.template as Record<string, unknown> | undefined;
+      return (template?.spec as Record<string, unknown>) ?? null;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Extract all containers (including init containers) from a workload manifest.
+ */
+export function extractContainers(manifest: K8sManifest): K8sContainer[] {
+  const podSpec = extractPodSpec(manifest);
+  if (!podSpec) return [];
+
+  const containers: K8sContainer[] = [];
+
+  if (Array.isArray(podSpec.containers)) {
+    for (const c of podSpec.containers) {
+      if (typeof c === "object" && c !== null) {
+        containers.push(c as K8sContainer);
+      }
+    }
+  }
+
+  if (Array.isArray(podSpec.initContainers)) {
+    for (const c of podSpec.initContainers) {
+      if (typeof c === "object" && c !== null) {
+        containers.push(c as K8sContainer);
+      }
+    }
+  }
+
+  return containers;
+}
+
+/**
+ * Workload kinds that contain pod templates.
+ */
+export const WORKLOAD_KINDS = new Set([
+  "Pod",
+  "Deployment",
+  "StatefulSet",
+  "DaemonSet",
+  "Job",
+  "CronJob",
+]);

package/dist/rules/wk8005.ts

@@ -0,0 +1,59 @@
+/**
+ * WK8005: Hardcoded Secrets in Environment Variables
+ *
+ * Detects container environment variables with names suggesting sensitive
+ * values (password, token, key, secret) that use hardcoded string values
+ * instead of secretKeyRef or configMapKeyRef.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+const SENSITIVE_NAME_PATTERN = /password|token|key|secret/i;
+
+export const wk8005: PostSynthCheck = {
+  id: "WK8005",
+  description: "Hardcoded secrets in env vars — sensitive environment variables should use secretKeyRef",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (const container of containers) {
+          if (!Array.isArray(container.env)) continue;
+
+          for (const envVar of container.env) {
+            if (
+              typeof envVar.name === "string" &&
+              SENSITIVE_NAME_PATTERN.test(envVar.name) &&
+              envVar.value !== undefined &&
+              envVar.value !== null &&
+              typeof envVar.value === "string" &&
+              envVar.value !== "" &&
+              !envVar.valueFrom
+            ) {
+              diagnostics.push({
+                checkId: "WK8005",
+                severity: "error",
+                message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has hardcoded value for sensitive env var "${envVar.name}" — use secretKeyRef instead`,
+                entity: resourceName,
+                lexicon: "k8s",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8006.ts

@@ -0,0 +1,68 @@
+/**
+ * WK8006: No :latest or Untagged Images
+ *
+ * Container images should use explicit version tags for reproducibility.
+ * Flags images using the `:latest` tag or no tag at all.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8006: PostSynthCheck = {
+  id: "WK8006",
+  description: "No :latest or untagged images — container images should use explicit version tags",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (const container of containers) {
+          const image = container.image;
+          if (typeof image !== "string" || image === "") continue;
+
+          // Split off digest (@sha256:...) — those are pinned and fine
+          if (image.includes("@")) continue;
+
+          // Extract the tag portion (after the last colon that isn't part of a port)
+          // Images can be: name, name:tag, registry:port/name, registry:port/name:tag
+          const slashIndex = image.lastIndexOf("/");
+          const afterSlash = slashIndex >= 0 ? image.slice(slashIndex + 1) : image;
+          const colonIndex = afterSlash.lastIndexOf(":");
+
+          if (colonIndex === -1) {
+            // No tag at all
+            diagnostics.push({
+              checkId: "WK8006",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" uses untagged image "${image}" — specify an explicit version tag`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          } else {
+            const tag = afterSlash.slice(colonIndex + 1);
+            if (tag === "latest") {
+              diagnostics.push({
+                checkId: "WK8006",
+                severity: "warning",
+                message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" uses :latest tag on image "${image}" — use a specific version tag`,
+                entity: resourceName,
+                lexicon: "k8s",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8041.ts

@@ -0,0 +1,73 @@
+/**
+ * WK8041: Hardcoded API Keys
+ *
+ * Detects well-known API key patterns in container environment variable values.
+ * Catches Stripe keys, GitHub PATs, AWS access keys, Google API keys, and
+ * other common credential formats.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+/**
+ * Known API key patterns and their descriptions.
+ */
+const API_KEY_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /^sk_live_/, label: "Stripe secret key" },
+  { pattern: /^pk_live_/, label: "Stripe publishable key" },
+  { pattern: /^sk_test_/, label: "Stripe test secret key" },
+  { pattern: /^pk_test_/, label: "Stripe test publishable key" },
+  { pattern: /^ghp_[A-Za-z0-9_]{36,}/, label: "GitHub personal access token" },
+  { pattern: /^gho_[A-Za-z0-9_]{36,}/, label: "GitHub OAuth token" },
+  { pattern: /^ghs_[A-Za-z0-9_]{36,}/, label: "GitHub app installation token" },
+  { pattern: /^ghu_[A-Za-z0-9_]{36,}/, label: "GitHub user-to-server token" },
+  { pattern: /^ghr_[A-Za-z0-9_]{36,}/, label: "GitHub refresh token" },
+  { pattern: /^AKIA[A-Z0-9]{16}$/, label: "AWS access key ID" },
+  { pattern: /^AIza[A-Za-z0-9_-]{35}$/, label: "Google API key" },
+  { pattern: /^xox[bprs]-[A-Za-z0-9-]+/, label: "Slack token" },
+  { pattern: /^SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}$/, label: "SendGrid API key" },
+];
+
+export const wk8041: PostSynthCheck = {
+  id: "WK8041",
+  description: "Hardcoded API keys — detects well-known API key patterns in env var values",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (const container of containers) {
+          if (!Array.isArray(container.env)) continue;
+
+          for (const envVar of container.env) {
+            if (typeof envVar.value !== "string" || envVar.value === "") continue;
+
+            for (const { pattern, label } of API_KEY_PATTERNS) {
+              if (pattern.test(envVar.value)) {
+                diagnostics.push({
+                  checkId: "WK8041",
+                  severity: "error",
+                  message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has a ${label} hardcoded in env var "${envVar.name ?? "(unnamed)"}" — use a Secret reference instead`,
+                  entity: resourceName,
+                  lexicon: "k8s",
+                });
+                break; // One match per env var is sufficient
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8042.ts

@@ -0,0 +1,48 @@
+/**
+ * WK8042: Private Keys in ConfigMap
+ *
+ * Detects PEM-encoded private keys stored in ConfigMap data values.
+ * Private keys should be stored in Secrets, not ConfigMaps, since
+ * ConfigMaps are not encrypted at rest by default.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+const PRIVATE_KEY_PATTERN = /-----BEGIN\s+[\w\s]*PRIVATE KEY-----/;
+
+export const wk8042: PostSynthCheck = {
+  id: "WK8042",
+  description: "Private keys in ConfigMap — private keys should be stored in Secrets, not ConfigMaps",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "ConfigMap") continue;
+
+        const resourceName = manifest.metadata?.name ?? "ConfigMap";
+        const data = manifest.data;
+        if (typeof data !== "object" || data === null) continue;
+
+        for (const [key, value] of Object.entries(data)) {
+          if (typeof value === "string" && PRIVATE_KEY_PATTERN.test(value)) {
+            diagnostics.push({
+              checkId: "WK8042",
+              severity: "error",
+              message: `ConfigMap "${resourceName}" contains a private key in data field "${key}" — use a Secret resource instead`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8101.ts

@@ -0,0 +1,65 @@
+/**
+ * WK8101: Deployment Selector Must Match Template Labels
+ *
+ * A Deployment's spec.selector.matchLabels must be a subset of
+ * spec.template.metadata.labels. If they don't match, the Deployment
+ * controller cannot find the Pods it creates, causing a runtime failure.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8101: PostSynthCheck = {
+  id: "WK8101",
+  description: "Deployment selector must match template labels — mismatched selectors cause runtime failures",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "Deployment") continue;
+
+        const resourceName = manifest.metadata?.name ?? "Deployment";
+        const spec = manifest.spec;
+        if (!spec) continue;
+
+        const selector = spec.selector as Record<string, unknown> | undefined;
+        const matchLabels = selector?.matchLabels as Record<string, string> | undefined;
+        if (!matchLabels || typeof matchLabels !== "object") continue;
+
+        const template = spec.template as Record<string, unknown> | undefined;
+        const templateMetadata = template?.metadata as Record<string, unknown> | undefined;
+        const templateLabels = templateMetadata?.labels as Record<string, string> | undefined;
+
+        if (!templateLabels || typeof templateLabels !== "object") {
+          diagnostics.push({
+            checkId: "WK8101",
+            severity: "error",
+            message: `Deployment "${resourceName}" has spec.selector.matchLabels but no spec.template.metadata.labels`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+          continue;
+        }
+
+        for (const [key, value] of Object.entries(matchLabels)) {
+          if (templateLabels[key] !== value) {
+            diagnostics.push({
+              checkId: "WK8101",
+              severity: "error",
+              message: `Deployment "${resourceName}" selector label "${key}=${value}" does not match template label "${key}=${templateLabels[key] ?? '(missing)'}"`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8102.ts

@@ -0,0 +1,42 @@
+/**
+ * WK8102: Resources Should Have Metadata Labels
+ *
+ * All Kubernetes resources should have metadata.labels for organizational
+ * purposes. Labels enable filtering, selection, and operational tooling.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8102: PostSynthCheck = {
+  id: "WK8102",
+  description: "Resources should have metadata labels — labels enable filtering and operational tooling",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !manifest.metadata) continue;
+
+        const resourceName = manifest.metadata.name ?? manifest.kind;
+        const labels = manifest.metadata.labels;
+
+        if (!labels || typeof labels !== "object" || Object.keys(labels).length === 0) {
+          diagnostics.push({
+            checkId: "WK8102",
+            severity: "warning",
+            message: `${manifest.kind} "${resourceName}" has no metadata.labels — add labels for organizational purposes`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8103.ts

@@ -0,0 +1,45 @@
+/**
+ * WK8103: Containers Must Have Name
+ *
+ * Every container in a pod spec must have a `name` field. This is required
+ * by the Kubernetes API and will be rejected at apply time if missing.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8103: PostSynthCheck = {
+  id: "WK8103",
+  description: "Containers must have name — the name field is required by the Kubernetes API",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (let i = 0; i < containers.length; i++) {
+          const container = containers[i];
+          if (!container.name || typeof container.name !== "string" || container.name.trim() === "") {
+            diagnostics.push({
+              checkId: "WK8103",
+              severity: "error",
+              message: `${manifest.kind} "${resourceName}" has a container at index ${i} without a name — the name field is required`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8104.ts

@@ -0,0 +1,69 @@
+/**
+ * WK8104: Ports Should Be Named
+ *
+ * Container ports and Service ports should have names. Named ports enable
+ * referencing by name in Service targetPort and NetworkPolicy rules,
+ * improving maintainability.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8104: PostSynthCheck = {
+  id: "WK8104",
+  description: "Ports should be named — named ports improve Service and NetworkPolicy configuration",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        const resourceName = manifest.metadata?.name ?? manifest.kind ?? "(unknown)";
+
+        // Check container ports in workloads
+        if (manifest.kind && WORKLOAD_KINDS.has(manifest.kind)) {
+          const containers = extractContainers(manifest);
+          for (const container of containers) {
+            if (!Array.isArray(container.ports)) continue;
+            for (const port of container.ports) {
+              if (typeof port === "object" && port !== null && !port.name) {
+                diagnostics.push({
+                  checkId: "WK8104",
+                  severity: "warning",
+                  message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has an unnamed port (containerPort: ${port.containerPort ?? "?"}) — add a name for clarity`,
+                  entity: resourceName,
+                  lexicon: "k8s",
+                });
+              }
+            }
+          }
+        }
+
+        // Check Service ports
+        if (manifest.kind === "Service") {
+          const spec = manifest.spec;
+          if (!spec) continue;
+          const ports = spec.ports as Array<Record<string, unknown>> | undefined;
+          if (!Array.isArray(ports)) continue;
+
+          for (const port of ports) {
+            if (typeof port === "object" && port !== null && !port.name) {
+              diagnostics.push({
+                checkId: "WK8104",
+                severity: "warning",
+                message: `Service "${resourceName}" has an unnamed port (port: ${port.port ?? "?"}) — add a name for clarity`,
+                entity: resourceName,
+                lexicon: "k8s",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};