@intentius/chant-lexicon-docker 0.1.0

package/src/interpolation.ts

@@ -0,0 +1,76 @@
+/**
+ * Docker Compose variable interpolation intrinsics.
+ *
+ * Docker Compose supports:
+ *   ${VAR}              — required variable (fails if unset)
+ *   ${VAR:-default}     — use default if VAR is unset or empty
+ *   ${VAR:?error}       — fail with error message if VAR is unset or empty
+ *   ${VAR:+value}       — use value if VAR is set
+ *
+ * @example
+ * import { env } from "@intentius/chant-lexicon-docker";
+ *
+ * export const api = new Service({
+ *   image: env("APP_IMAGE", { default: "myapp:latest" }),
+ *   environment: {
+ *     DB_URL: env("DB_URL", { required: true }),
+ *   },
+ * });
+ *
+ * // Serializes to:
+ * // services:
+ * //   api:
+ * //     image: ${APP_IMAGE:-myapp:latest}
+ * //     environment:
+ * //       DB_URL: ${DB_URL:?DB_URL is required}
+ */
+
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+export interface EnvOptions {
+  /** Default value if VAR is unset or empty: ${VAR:-default} */
+  default?: string;
+  /** If true and no default, emit ${VAR:?VAR is required}: fail on missing */
+  required?: boolean;
+  /** Error message for required variables: ${VAR:?errorMessage} */
+  errorMessage?: string;
+  /** Alternate value when VAR is set: ${VAR:+value} */
+  ifSet?: string;
+}
+
+export interface EnvIntrinsic {
+  readonly [INTRINSIC_MARKER]: true;
+  /** Emit the Docker Compose interpolation string */
+  toJSON(): string;
+  toString(): string;
+}
+
+/**
+ * Create a Docker Compose variable interpolation intrinsic.
+ *
+ * @param name - Environment variable name
+ * @param opts - Interpolation options
+ */
+export function env(name: string, opts: EnvOptions = {}): EnvIntrinsic {
+  function interpolationString(): string {
+    if (opts.ifSet !== undefined) {
+      return `\${${name}:+${opts.ifSet}}`;
+    }
+    if (opts.default !== undefined) {
+      return `\${${name}:-${opts.default}}`;
+    }
+    if (opts.required || opts.errorMessage) {
+      const msg = opts.errorMessage ?? `${name} is required`;
+      return `\${${name}:?${msg}}`;
+    }
+    return `\${${name}}`;
+  }
+
+  const value = interpolationString();
+
+  return {
+    [INTRINSIC_MARKER]: true,
+    toJSON: () => value,
+    toString: () => value,
+  };
+}

package/src/lint/post-synth/apt-no-recommends.ts

@@ -0,0 +1,43 @@
+/**
+ * DKRD010: apt-get install without --no-install-recommends
+ *
+ * Detects RUN instructions with apt-get install missing
+ * --no-install-recommends, which leads to bloated images.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+export const dkrd010: PostSynthCheck = {
+  id: "DKRD010",
+  description: "apt-get install without --no-install-recommends adds unnecessary packages",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (
+            /^RUN\s+/.test(line) &&
+            line.includes("apt-get install") &&
+            !line.includes("--no-install-recommends")
+          ) {
+            diagnostics.push({
+              checkId: "DKRD010",
+              severity: "warning",
+              message: `${fileName}: RUN apt-get install should use --no-install-recommends to reduce image size.`,
+              lexicon: "docker",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/docker-helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared YAML traversal utilities for Docker post-synth checks.
+ */
+
+export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+export interface ParsedService {
+  name: string;
+  image?: string;
+  ports?: string[];
+  volumes?: string[];
+  build?: { dockerfile?: string; context?: string };
+  depends_on?: string[];
+}
+
+/**
+ * Extract services section from serialized docker-compose.yml.
+ */
+export function extractServices(yaml: string): Map<string, ParsedService> {
+  const services = new Map<string, ParsedService>();
+
+  const servicesIdx = yaml.search(/^services:\s*$/m);
+  if (servicesIdx === -1) return services;
+
+  const afterServices = yaml.slice(servicesIdx + yaml.slice(servicesIdx).indexOf("\n") + 1);
+  // Stop at next top-level key
+  const endMatch = afterServices.search(/^[a-z]/m);
+  const servicesContent = endMatch === -1 ? afterServices : afterServices.slice(0, endMatch);
+
+  // Split by service entries (2-space indent + name:)
+  const sections = servicesContent.split(/\n(?=  [a-z][a-z0-9_-]*:)/);
+
+  for (const section of sections) {
+    const nameMatch = section.match(/^\s{2}([a-z][a-z0-9_-]*):/);
+    if (!nameMatch) continue;
+
+    const name = nameMatch[1];
+    const svc: ParsedService = { name };
+
+    const imageMatch = section.match(/^\s{4}image:\s+(.+)$/m);
+    if (imageMatch) svc.image = imageMatch[1].trim().replace(/^['"]|['"]$/g, "");
+
+    const portsMatch = section.match(/^\s{4}ports:\n((?:\s{6}- .+\n?)+)/m);
+    if (portsMatch) {
+      svc.ports = [];
+      for (const line of portsMatch[1].split("\n")) {
+        const item = line.match(/^\s{6}-\s+['"]?(.+?)['"]?$/);
+        if (item) svc.ports.push(item[1].trim());
+      }
+    }
+
+    const volsMatch = section.match(/^\s{4}volumes:\n((?:\s{6}- .+\n?)+)/m);
+    if (volsMatch) {
+      svc.volumes = [];
+      for (const line of volsMatch[1].split("\n")) {
+        const item = line.match(/^\s{6}-\s+['"]?(.+?)['"]?$/);
+        if (item) svc.volumes.push(item[1].trim());
+      }
+    }
+
+    services.set(name, svc);
+  }
+
+  return services;
+}
+
+/**
+ * Extract named volumes from the top-level volumes: section.
+ */
+export function extractNamedVolumes(yaml: string): Set<string> {
+  const volumes = new Set<string>();
+
+  const volumesIdx = yaml.search(/^volumes:\s*$/m);
+  if (volumesIdx === -1) return volumes;
+
+  const afterVolumes = yaml.slice(volumesIdx + yaml.slice(volumesIdx).indexOf("\n") + 1);
+  const endMatch = afterVolumes.search(/^[a-z]/m);
+  const volumesContent = endMatch === -1 ? afterVolumes : afterVolumes.slice(0, endMatch);
+
+  for (const line of volumesContent.split("\n")) {
+    const match = line.match(/^\s{2}([a-z][a-z0-9_-]*):/);
+    if (match) volumes.add(match[1]);
+  }
+
+  return volumes;
+}
+
+/**
+ * Check if an image tag represents :latest or is untagged.
+ */
+export function isLatestOrUntagged(image: string): boolean {
+  if (!image || image.startsWith("${")) return false;
+  if (image.endsWith(":latest")) return true;
+  const parts = image.split("/");
+  const lastPart = parts[parts.length - 1];
+  return !lastPart.includes(":") && !lastPart.includes("@");
+}
+
+/**
+ * Get Dockerfile content from SerializerResult files map.
+ */
+export function extractDockerfiles(output: unknown): Map<string, string> {
+  const files = new Map<string, string>();
+  if (typeof output !== "object" || output === null) return files;
+  if (!("files" in output)) return files;
+
+  const outputFiles = (output as { files: Record<string, string> }).files;
+  for (const [name, content] of Object.entries(outputFiles)) {
+    if (name.startsWith("Dockerfile")) {
+      files.set(name, content);
+    }
+  }
+  return files;
+}

package/src/lint/post-synth/no-latest-image.ts

@@ -0,0 +1,36 @@
+/**
+ * DKRD001: No Latest Image Tag
+ *
+ * Detects services using :latest or untagged images in docker-compose.yml.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices, isLatestOrUntagged } from "./docker-helpers";
+
+export const dkrd001: PostSynthCheck = {
+  id: "DKRD001",
+  description: "Service uses :latest or untagged image — specify an explicit version tag",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      if (!yaml) continue;
+
+      const services = extractServices(yaml);
+      for (const [name, svc] of services) {
+        if (svc.image && isLatestOrUntagged(svc.image)) {
+          diagnostics.push({
+            checkId: "DKRD001",
+            severity: "warning",
+            message: `Service "${name}" uses image "${svc.image}" which is :latest or untagged. Use an explicit version tag for reproducible builds.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/no-root-user.ts

@@ -0,0 +1,36 @@
+/**
+ * DKRD012: No Root User
+ *
+ * Warns when a Dockerfile has no USER instruction,
+ * meaning the container runs as root by default.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+export const dkrd012: PostSynthCheck = {
+  id: "DKRD012",
+  description: "Dockerfile has no USER instruction — container runs as root",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const hasUser = /^USER\s+/m.test(content);
+        if (!hasUser) {
+          diagnostics.push({
+            checkId: "DKRD012",
+            severity: "warning",
+            message: `${fileName}: No USER instruction found. The container will run as root. Add a USER instruction to improve security.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,181 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { dkrd001 } from "./no-latest-image";
+import { dkrd002 } from "./unused-volume";
+import { dkrd003 } from "./ssh-port-exposed";
+import { dkrd010 } from "./apt-no-recommends";
+import { dkrd011 } from "./prefer-copy";
+import { dkrd012 } from "./no-root-user";
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["docker", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["docker", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+function makeDockerfileCtx(dockerfileName: string, content: string): PostSynthContext {
+  const result = {
+    primary: "services:\n  app:\n    image: myapp:1.0\n",
+    files: { [dockerfileName]: content },
+  };
+  return {
+    outputs: new Map([["docker", result as unknown as string]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["docker", result as unknown as string]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+// ── DKRD001: no-latest-image ─────────────────────────────────────
+
+describe("DKRD001: no-latest-image", () => {
+  test("flags :latest image", () => {
+    const yaml = `services:\n  api:\n    image: nginx:latest\n`;
+    const diags = dkrd001.check(makeCtx(yaml));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD001");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("nginx:latest");
+  });
+
+  test("flags untagged image", () => {
+    const yaml = `services:\n  api:\n    image: nginx\n`;
+    const diags = dkrd001.check(makeCtx(yaml));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD001");
+  });
+
+  test("does not flag versioned image", () => {
+    const yaml = `services:\n  api:\n    image: nginx:1.25-alpine\n`;
+    const diags = dkrd001.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── DKRD002: unused-volume ──────────────────────────────────────
+
+describe("DKRD002: unused-volume", () => {
+  test("flags unused named volume", () => {
+    const yaml = `services:\n  api:\n    image: myapp:1.0\n\nvolumes:\n  mydata:\n`;
+    const diags = dkrd002.check(makeCtx(yaml));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD002");
+    expect(diags[0].message).toContain("mydata");
+  });
+
+  test("does not flag volume that is mounted", () => {
+    const yaml = `services:\n  api:\n    image: myapp:1.0\n    volumes:\n      - mydata:/data\n\nvolumes:\n  mydata:\n`;
+    const diags = dkrd002.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no volumes section returns empty", () => {
+    const yaml = `services:\n  api:\n    image: myapp:1.0\n`;
+    const diags = dkrd002.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── DKRD003: ssh-port-exposed ───────────────────────────────────
+
+describe("DKRD003: ssh-port-exposed", () => {
+  test("flags port 22 exposure", () => {
+    const yaml = `services:\n  bastion:\n    image: ubuntu:22.04\n    ports:\n      - "22:22"\n`;
+    const diags = dkrd003.check(makeCtx(yaml));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD003");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("does not flag other ports", () => {
+    const yaml = `services:\n  api:\n    image: myapp:1.0\n    ports:\n      - "8080:8080"\n`;
+    const diags = dkrd003.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag localhost-bound port 22", () => {
+    const yaml = `services:\n  bastion:\n    image: ubuntu:22.04\n    ports:\n      - "127.0.0.1:22:22"\n`;
+    const diags = dkrd003.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── DKRD010: apt-no-recommends ──────────────────────────────────
+
+describe("DKRD010: apt-no-recommends", () => {
+  test("flags apt-get install without --no-install-recommends", () => {
+    const dockerfile = `FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y curl\n`;
+    const diags = dkrd010.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD010");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("does not flag with --no-install-recommends", () => {
+    const dockerfile = `FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y --no-install-recommends curl\n`;
+    const diags = dkrd010.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag non-apt RUN", () => {
+    const dockerfile = `FROM node:20-alpine\nRUN npm ci\n`;
+    const diags = dkrd010.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── DKRD011: prefer-copy ────────────────────────────────────────
+
+describe("DKRD011: prefer-copy", () => {
+  test("flags ADD with local file", () => {
+    const dockerfile = `FROM ubuntu:22.04\nADD src/ /app/\n`;
+    const diags = dkrd011.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD011");
+  });
+
+  test("does not flag ADD with URL", () => {
+    const dockerfile = `FROM ubuntu:22.04\nADD https://example.com/file.tar.gz /tmp/\n`;
+    const diags = dkrd011.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag ADD with archive", () => {
+    const dockerfile = `FROM ubuntu:22.04\nADD src.tar.gz /app/\n`;
+    const diags = dkrd011.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── DKRD012: no-root-user ────────────────────────────────────────
+
+describe("DKRD012: no-root-user", () => {
+  test("flags Dockerfile without USER instruction", () => {
+    const dockerfile = `FROM node:20-alpine\nRUN npm ci\nCMD ["node", "index.js"]\n`;
+    const diags = dkrd012.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].checkId).toBe("DKRD012");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("does not flag Dockerfile with USER instruction", () => {
+    const dockerfile = `FROM node:20-alpine\nRUN npm ci\nUSER node\nCMD ["node", "index.js"]\n`;
+    const diags = dkrd012.check(makeDockerfileCtx("Dockerfile.app", dockerfile));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/prefer-copy.ts

@@ -0,0 +1,53 @@
+/**
+ * DKRD011: Prefer COPY over ADD
+ *
+ * ADD has surprising behavior (auto-extracts archives, fetches URLs).
+ * Use COPY when you just need to copy local files.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+function looksLikeUrl(src: string): boolean {
+  return src.startsWith("http://") || src.startsWith("https://") || src.startsWith("ftp://");
+}
+
+function looksLikeArchive(src: string): boolean {
+  return /\.(tar|tar\.gz|tgz|tar\.bz2|tar\.xz|zip)$/i.test(src);
+}
+
+export const dkrd011: PostSynthCheck = {
+  id: "DKRD011",
+  description: "Prefer COPY over ADD when not fetching URLs or extracting archives",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const lines = content.split("\n");
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (/^ADD\s+/.test(trimmed)) {
+            // Extract src argument (first token after ADD)
+            const parts = trimmed.replace(/^ADD\s+/, "").split(/\s+/);
+            const src = parts[0];
+
+            if (!looksLikeUrl(src) && !looksLikeArchive(src)) {
+              diagnostics.push({
+                checkId: "DKRD011",
+                severity: "info",
+                message: `${fileName}: Use COPY instead of ADD when not fetching URLs or extracting archives. ADD "${src}" could be COPY.`,
+                lexicon: "docker",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ssh-port-exposed.ts

@@ -0,0 +1,68 @@
+/**
+ * DKRD003: SSH Port Exposed
+ *
+ * Detects services exposing port 22 (SSH) on the host.
+ * Exposing SSH externally is a security risk.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices } from "./docker-helpers";
+
+function exposesSshPort(port: string): boolean {
+  // Formats: "22", "22/tcp", "0.0.0.0:22:22", "127.0.0.1:22:22", "host:container"
+  const normalized = port.trim();
+  const parts = normalized.split(":");
+
+  if (parts.length === 1) {
+    // Just a port number: "22" or "22/tcp"
+    const portNum = parts[0].split("/")[0];
+    return portNum === "22";
+  }
+
+  if (parts.length === 2) {
+    // "hostPort:containerPort" e.g. "22:22" — no IP binding, accessible on all interfaces
+    const hostPort = parts[0].split("/")[0];
+    return hostPort === "22";
+  }
+
+  if (parts.length >= 3) {
+    // "ip:hostPort:containerPort" e.g. "127.0.0.1:22:22" or "0.0.0.0:22:22"
+    const ip = parts[0];
+    const hostPort = parts[1].split("/")[0];
+    // Only flag if port is 22 AND not bound to loopback
+    if (hostPort !== "22") return false;
+    return ip !== "127.0.0.1" && ip !== "::1" && ip !== "localhost";
+  }
+
+  return false;
+}
+
+export const dkrd003: PostSynthCheck = {
+  id: "DKRD003",
+  description: "Service exposes SSH port (22) externally — this is a security risk",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      if (!yaml) continue;
+
+      const services = extractServices(yaml);
+      for (const [name, svc] of services) {
+        for (const port of svc.ports ?? []) {
+          if (exposesSshPort(port)) {
+            diagnostics.push({
+              checkId: "DKRD003",
+              severity: "error",
+              message: `Service "${name}" exposes SSH port 22 externally (port mapping: "${port}"). This is a security risk.`,
+              lexicon: "docker",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/unused-volume.ts

@@ -0,0 +1,49 @@
+/**
+ * DKRD002: Unused Named Volume
+ *
+ * Detects top-level named volumes that are not mounted by any service.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices, extractNamedVolumes } from "./docker-helpers";
+
+export const dkrd002: PostSynthCheck = {
+  id: "DKRD002",
+  description: "Named volume is declared but not mounted by any service",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      if (!yaml) continue;
+
+      const namedVolumes = extractNamedVolumes(yaml);
+      if (namedVolumes.size === 0) continue;
+
+      const services = extractServices(yaml);
+      const mountedVolumes = new Set<string>();
+
+      for (const svc of services.values()) {
+        for (const vol of svc.volumes ?? []) {
+          // Volume mount format: "volname:/container/path" or just "volname"
+          const volumeName = vol.split(":")[0].trim();
+          mountedVolumes.add(volumeName);
+        }
+      }
+
+      for (const volName of namedVolumes) {
+        if (!mountedVolumes.has(volName)) {
+          diagnostics.push({
+            checkId: "DKRD002",
+            severity: "warning",
+            message: `Named volume "${volName}" is declared but not mounted by any service.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/data/deprecated-images.ts

@@ -0,0 +1,28 @@
+/**
+ * Known deprecated or EOL Docker base images.
+ */
+
+export const DEPRECATED_IMAGES: Array<{ image: string; reason: string; replacement?: string }> = [
+  {
+    image: "centos:8",
+    reason: "CentOS 8 reached EOL on December 31, 2021",
+    replacement: "rockylinux:8 or almalinux:8",
+  },
+  {
+    image: "centos:latest",
+    reason: "CentOS Stream is a rolling release; use a specific version",
+    replacement: "rockylinux:9 or almalinux:9",
+  },
+  {
+    image: "node:lts",
+    reason: "Use a specific LTS version tag for reproducible builds",
+    replacement: "node:20-alpine or node:22-alpine",
+  },
+];
+
+/**
+ * Check if an image reference matches a deprecated entry.
+ */
+export function findDeprecatedImage(imageRef: string): (typeof DEPRECATED_IMAGES)[number] | undefined {
+  return DEPRECATED_IMAGES.find((d) => imageRef === d.image || imageRef.startsWith(d.image + "@"));
+}