@intentius/chant-lexicon-docker 0.124.21 → 0.124.22

package/src/lint/post-synth/cache-busting-copy.ts

@@ -0,0 +1,64 @@
+/**
+ * DKRD013: Whole build context copied before installing dependencies
+ *
+ * `COPY . .` followed by a dependency install (npm ci, pip install -r,
+ * go mod download, ...) in the same stage invalidates the install layer on
+ * every source change. Copy the dependency manifests first, install, then
+ * copy the rest.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { commandText, eachDockerfile, instrText, stageLabel } from "./docker-helpers";
+
+/** Installs whose inputs are a few manifest files rather than the whole source tree. */
+const INSTALL = [
+  /\bnpm\s+(ci|install|i)(\s+--?[\w-]+(=\S+)?)*\s*($|&&|;|\|)/m,
+  /\byarn(\s+install)?(\s+--[\w-]+)*\s*($|&&|;|\|)/m,
+  /\bpnpm\s+(install|i)\b/,
+  /\bbun\s+install\b/,
+  /\bpip3?\s+install\b[^&;|]*\s-r\s/,
+  /\bpoetry\s+install\b/,
+  /\buv\s+sync\b/,
+  /\bpipenv\s+install\b/,
+  /\bgo\s+mod\s+download\b/,
+  /\bbundle\s+install\b/,
+  /\bcomposer\s+install\b/,
+  /\bcargo\s+fetch\b/,
+  /\bdotnet\s+restore\b/,
+  /\bmvn\b[^&;|]*\bdependency:go-offline\b/,
+];
+
+/** `COPY . <dest>` (or `./`) from the build context, not from another stage. */
+function copiesWholeContext(value: string): boolean {
+  const words = value.split(/\s+/).filter((w) => w.length > 0);
+  if (words.some((w) => w.startsWith("--from"))) return false;
+  const args = words.filter((w) => !w.startsWith("--"));
+  if (args[0]?.startsWith("[")) return false;
+  return args.slice(0, -1).some((src) => src === "." || src === "./");
+}
+
+export const dkrd013: PostSynthCheck = {
+  id: "DKRD013",
+  description: "Whole build context copied before a dependency install — every source change re-runs the install",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        const copyAt = stage.instructions.findIndex((i) => i.instruction === "COPY" && copiesWholeContext(i.value));
+        if (copyAt === -1) continue;
+        const install = stage.instructions.slice(copyAt + 1).find((i) => i.instruction === "RUN" && INSTALL.some((re) => re.test(commandText(i))));
+        if (!install) continue;
+        diagnostics.push({
+          checkId: "DKRD013",
+          severity: "warning",
+          message: `${fileName} ${stageLabel(stage)}: ${instrText(stage.instructions[copyAt]!)} comes before ${instrText(install)}, so any source change re-runs the install. Copy the dependency manifests first, run the install, then copy the rest.`,
+          lexicon: "docker",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/copy-from-stage.ts

@@ -0,0 +1,54 @@
+/**
+ * DKRD016: COPY --from names no earlier stage
+ *
+ * `COPY --from=<name>` reads from an earlier stage with that name (or
+ * index). A name that only a later stage has, or that no stage has, is
+ * pulled as an image instead, which is almost never what was meant.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { eachDockerfile, stageLabel } from "./docker-helpers";
+
+/** Looks like an image reference rather than a stage name: has a tag, digest or registry path. */
+function looksLikeImage(ref: string): boolean {
+  return /[:/@]/.test(ref);
+}
+
+export const dkrd016: PostSynthCheck = {
+  id: "DKRD016",
+  description: "COPY --from names a stage that is not defined before it",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        for (const instr of stage.instructions) {
+          if (instr.instruction !== "COPY" && instr.instruction !== "ADD") continue;
+          const m = instr.value.match(/--from=(\S+)/);
+          if (!m) continue;
+          const ref = m[1]!;
+          if (ref.includes("$")) continue;
+          const earlier = parsed.stages.slice(0, stage.index);
+          if (/^\d+$/.test(ref)) {
+            if (Number(ref) < stage.index) continue;
+          } else if (earlier.some((s) => s.as?.toLowerCase() === ref.toLowerCase())) {
+            continue;
+          }
+          const later = parsed.stages.slice(stage.index).find((s) => s.as?.toLowerCase() === ref.toLowerCase() || String(s.index) === ref);
+          if (!later && looksLikeImage(ref)) continue;
+          diagnostics.push({
+            checkId: "DKRD016",
+            severity: "warning",
+            message: later
+              ? `${fileName} ${stageLabel(stage)}: ${instr.instruction} --from=${ref} names ${stageLabel(later)}, which is not defined until later. Move that stage before this one.`
+              : `${fileName} ${stageLabel(stage)}: ${instr.instruction} --from=${ref} names no stage, so Docker pulls an image called "${ref}". Name an earlier stage, or give the image a tag.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -3,6 +3,7 @@
  */
 
 export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { splitDockerfileInstructions } from "../../import/parser";
 
 export interface ParsedService {
   name: string;
@@ -112,3 +113,82 @@ export function extractDockerfiles(output: unknown): Map<string, string> {
   }
   return files;
 }
+
+// ── Dockerfile structure ──────────────────────────────────────────
+
+export interface DockerfileInstr {
+  /** Upper-case keyword, e.g. "RUN". */
+  instruction: string;
+  /** The rest of the instruction as written. */
+  value: string;
+}
+
+export interface ParsedStage {
+  /** 0-based position among the stages. */
+  index: number;
+  /** The FROM image (or earlier stage) without `--platform` and `AS`. */
+  from: string;
+  as?: string;
+  instructions: DockerfileInstr[];
+}
+
+export interface ParsedDockerfile {
+  /** ARG instructions before the first FROM. */
+  globalArgs: DockerfileInstr[];
+  stages: ParsedStage[];
+}
+
+/** A Dockerfile's global ARGs and stages, each stage's instructions in order. */
+export function parseDockerfileStages(content: string): ParsedDockerfile {
+  const out: ParsedDockerfile = { globalArgs: [], stages: [] };
+  for (const instr of splitDockerfileInstructions(content)) {
+    if (instr.instruction === "FROM") {
+      const words = instr.value.split(/\s+/).filter((w) => !w.startsWith("--"));
+      const asAt = words.findIndex((w) => w.toLowerCase() === "as");
+      out.stages.push({
+        index: out.stages.length,
+        from: words[0] ?? "",
+        ...(asAt > 0 && words[asAt + 1] ? { as: words[asAt + 1] } : {}),
+        instructions: [],
+      });
+    } else if (out.stages.length > 0) {
+      out.stages[out.stages.length - 1]!.instructions.push(instr);
+    } else if (instr.instruction === "ARG") {
+      out.globalArgs.push(instr);
+    }
+  }
+  return out;
+}
+
+/** How a stage is named in a message: `stage "build"` or `stage 2`. */
+export function stageLabel(stage: ParsedStage): string {
+  return stage.as ? `stage "${stage.as}"` : `stage ${stage.index + 1}`;
+}
+
+/** The first line of an instruction, for a message. */
+export function instrText(instr: DockerfileInstr): string {
+  const first = instr.value.split("\n")[0]!.replace(/\s*\\$/, "");
+  return `${instr.instruction} ${first}`;
+}
+
+/** Whether a USER value is root (by name or uid 0, with or without a group). */
+export function isRootUser(value: string): boolean {
+  const user = value.trim().split(":")[0]!;
+  return user === "root" || user === "0";
+}
+
+/** Every generated Dockerfile in a build's outputs, parsed. */
+export function eachDockerfile(outputs: Map<string, unknown>): Array<{ fileName: string; content: string; parsed: ParsedDockerfile }> {
+  const out: Array<{ fileName: string; content: string; parsed: ParsedDockerfile }> = [];
+  for (const [, output] of outputs) {
+    for (const [fileName, content] of extractDockerfiles(output)) {
+      out.push({ fileName, content, parsed: parseDockerfileStages(content) });
+    }
+  }
+  return out;
+}
+
+/** A RUN value with its line continuations joined, for matching commands. */
+export function commandText(instr: DockerfileInstr): string {
+  return instr.value.replace(/\\[ \t]*\n/g, " ");
+}

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

@@ -6,6 +6,14 @@ import { dkrd003 } from "./ssh-port-exposed";
 import { dkrd010 } from "./apt-no-recommends";
 import { dkrd011 } from "./prefer-copy";
 import { dkrd012 } from "./no-root-user";
+import { dkrd013 } from "./cache-busting-copy";
+import { dkrd014 } from "./root-after-user";
+import { dkrd015 } from "./repeated-cmd";
+import { dkrd016 } from "./copy-from-stage";
+import { dkrd017 } from "./unused-global-arg";
+import { dkrd018 } from "./relative-workdir";
+import { dkrd019 } from "./add-url-checksum";
+import { dkrd020 } from "./apt-update-alone";
 
 export const postSynthChecks: PostSynthCheck[] = [
   dkrd001,
@@ -14,4 +22,12 @@ export const postSynthChecks: PostSynthCheck[] = [
   dkrd010,
   dkrd011,
   dkrd012,
+  dkrd013,
+  dkrd014,
+  dkrd015,
+  dkrd016,
+  dkrd017,
+  dkrd018,
+  dkrd019,
+  dkrd020,
 ];

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

@@ -1,34 +1,36 @@
 /**
  * DKRD012: No Root User
  *
- * Warns when a Dockerfile has no USER instruction,
- * meaning the container runs as root by default.
+ * Warns when the container would run as root: the final stage has no USER
+ * instruction, or its last USER is root. USER in an earlier stage does not
+ * carry into the final image.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { extractDockerfiles } from "./docker-helpers";
+import { eachDockerfile, isRootUser, stageLabel } from "./docker-helpers";
 
 export const dkrd012: PostSynthCheck = {
   id: "DKRD012",
-  description: "Dockerfile has no USER instruction — container runs as root",
+  description: "Dockerfile's final stage has no USER instruction, or ends on USER root — 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",
-          });
-        }
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      const final = parsed.stages[parsed.stages.length - 1];
+      if (!final) continue;
+      const users = final.instructions.filter((i) => i.instruction === "USER");
+      const last = users[users.length - 1];
+      let message: string | undefined;
+      if (!last) {
+        const anyUser = parsed.stages.some((s) => s.instructions.some((i) => i.instruction === "USER"));
+        message = anyUser
+          ? `${fileName}: The final ${stageLabel(final)} has no USER instruction; a USER in an earlier stage does not carry over. The container will run as root. Add a USER step to the final stage.`
+          : `${fileName}: No USER instruction found. The container will run as root. Add a USER instruction to improve security.`;
+      } else if (isRootUser(last.value)) {
+        message = `${fileName}: The final ${stageLabel(final)} ends on USER ${last.value.trim()}, so the container runs as root. Switch to an unprivileged USER after the root setup steps.`;
       }
+      if (message) diagnostics.push({ checkId: "DKRD012", severity: "warning", message, lexicon: "docker" });
     }
 
     return diagnostics;

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

@@ -6,6 +6,14 @@ import { dkrd003 } from "./ssh-port-exposed";
 import { dkrd010 } from "./apt-no-recommends";
 import { dkrd011 } from "./prefer-copy";
 import { dkrd012 } from "./no-root-user";
+import { dkrd013 } from "./cache-busting-copy";
+import { dkrd014 } from "./root-after-user";
+import { dkrd015 } from "./repeated-cmd";
+import { dkrd016 } from "./copy-from-stage";
+import { dkrd017 } from "./unused-global-arg";
+import { dkrd018 } from "./relative-workdir";
+import { dkrd019 } from "./add-url-checksum";
+import { dkrd020 } from "./apt-update-alone";
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
@@ -179,3 +187,144 @@ describe("DKRD012: no-root-user", () => {
     expect(diags).toHaveLength(0);
   });
 });
+
+describe("DKRD012: final stage", () => {
+  const run = (lines: string[]) => dkrd012.check(makeDockerfileCtx("Dockerfile.app", lines.join("\n") + "\n"));
+
+  test("flags a final stage with no USER when only an earlier stage sets one", () => {
+    const diags = run(["FROM node:20-alpine AS build", "USER node", "RUN npm ci", "FROM node:20-alpine", "CMD node index.js"]);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("final stage 2 has no USER");
+  });
+
+  test("flags a final stage that ends on USER root", () => {
+    const diags = run(["FROM debian:12-slim", "USER app", "USER 0:0", "CMD x"]);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("ends on USER 0:0");
+  });
+
+  test("does not flag USER root for setup followed by a non-root USER", () => {
+    expect(run(["FROM debian:12-slim", "USER root", "RUN apt-get update", "USER app", "CMD x"])).toHaveLength(0);
+  });
+});
+
+const df = (lines: string[]) => makeDockerfileCtx("Dockerfile.app", lines.join("\n") + "\n");
+
+describe("DKRD013: cache-busting copy", () => {
+  test("flags COPY . . before npm ci", () => {
+    const diags = dkrd013.check(df(["FROM node:20-alpine", "WORKDIR /app", "COPY . .", "RUN npm ci", "RUN npm run build"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("COPY . . comes before RUN npm ci");
+  });
+
+  test("flags pip install -r and go mod download, across a continuation", () => {
+    expect(dkrd013.check(df(["FROM python:3.12-slim", "COPY . /app", "RUN pip install --no-cache-dir \\", "    -r /app/requirements.txt"]))).toHaveLength(1);
+    expect(dkrd013.check(df(["FROM golang:1.23", "COPY ./ ./", "RUN go mod download"]))).toHaveLength(1);
+  });
+
+  test("does not flag manifests copied first, COPY --from, or a package added by name", () => {
+    expect(dkrd013.check(df(["FROM node:20-alpine", "COPY package*.json ./", "RUN npm ci", "COPY . .", "RUN npm run build"]))).toHaveLength(0);
+    expect(dkrd013.check(df(["FROM node:20-alpine", "COPY --from=build /app .", "RUN npm ci"]))).toHaveLength(0);
+    expect(dkrd013.check(df(["FROM node:20-alpine", "COPY . .", "RUN npm install -g serve"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD014: root-only RUN after USER", () => {
+  test("flags apt-get after a non-root USER", () => {
+    const diags = dkrd014.check(df(["FROM debian:12-slim", "USER app", "RUN apt-get update && apt-get install -y curl"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("runs as USER app");
+  });
+
+  test("does not flag root setup before USER, USER root, or sudo", () => {
+    expect(dkrd014.check(df(["FROM debian:12-slim", "RUN useradd app", "USER app", "RUN whoami"]))).toHaveLength(0);
+    expect(dkrd014.check(df(["FROM debian:12-slim", "USER app", "USER root", "RUN chown app /data", "USER app"]))).toHaveLength(0);
+    expect(dkrd014.check(df(["FROM debian:12-slim", "USER app", "RUN sudo apt-get install -y curl"]))).toHaveLength(0);
+  });
+
+  test("a USER in one stage does not carry into the next", () => {
+    expect(dkrd014.check(df(["FROM debian:12-slim AS a", "USER app", "FROM debian:12-slim", "RUN apt-get install -y curl"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD015: repeated CMD or ENTRYPOINT", () => {
+  test("flags two CMDs in a stage", () => {
+    const diags = dkrd015.check(df(["FROM alpine:3.20", 'CMD ["a"]', "RUN true", 'CMD ["b"]']));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('2 CMD instructions; only the last (CMD ["b"])');
+  });
+
+  test("does not flag one CMD per stage", () => {
+    expect(dkrd015.check(df(["FROM alpine:3.20 AS a", "CMD a", "FROM alpine:3.20", "ENTRYPOINT x", "CMD b"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD016: COPY --from stage", () => {
+  test("flags a stage that is only defined later", () => {
+    const diags = dkrd016.check(df(["FROM alpine:3.20 AS final", "COPY --from=build /out /out", "FROM alpine:3.20 AS build"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('names stage "build", which is not defined until later');
+  });
+
+  test("flags a name no stage has", () => {
+    const diags = dkrd016.check(df(["FROM alpine:3.20 AS build", "FROM alpine:3.20", "COPY --from=biuld /out /out"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('pulls an image called "biuld"');
+  });
+
+  test("does not flag earlier stages by name or index, or tagged images", () => {
+    expect(dkrd016.check(df([
+      "FROM alpine:3.20 AS build",
+      "FROM alpine:3.20",
+      "COPY --from=build /a /a",
+      "COPY --from=0 /b /b",
+      "COPY --from=nginx:1.27 /etc/nginx /etc/nginx",
+    ]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD017: unused global ARG", () => {
+  test("flags an ARG before FROM that nothing uses", () => {
+    const diags = dkrd017.check(df(["ARG UNUSED=1", "FROM alpine:3.20"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("ARG UNUSED");
+  });
+
+  test("does not flag an ARG used in FROM or declared again in a stage", () => {
+    expect(dkrd017.check(df(["ARG NODE_VERSION=20", "FROM node:${NODE_VERSION}-alpine"]))).toHaveLength(0);
+    expect(dkrd017.check(df(["ARG VERSION=1", "FROM alpine:3.20", "ARG VERSION", "RUN echo $VERSION"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD018: relative WORKDIR", () => {
+  test("flags a relative WORKDIR before any absolute one", () => {
+    const diags = dkrd018.check(df(["FROM alpine:3.20", "WORKDIR app"]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("WORKDIR app is relative");
+  });
+
+  test("does not flag a relative WORKDIR after an absolute one", () => {
+    expect(dkrd018.check(df(["FROM alpine:3.20", "WORKDIR /src", "WORKDIR app"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD019: ADD URL without checksum", () => {
+  test("flags ADD of an https URL without --checksum", () => {
+    expect(dkrd019.check(df(["FROM alpine:3.20", "ADD https://example.com/tool.tgz /tmp/"]))).toHaveLength(1);
+  });
+
+  test("does not flag --checksum or a local file", () => {
+    expect(dkrd019.check(df(["FROM alpine:3.20", "ADD --checksum=sha256:abc https://example.com/tool.tgz /tmp/", "ADD local.tgz /tmp/"]))).toHaveLength(0);
+  });
+});
+
+describe("DKRD020: apt-get update alone", () => {
+  test("flags update in one RUN and install in a later one", () => {
+    const diags = dkrd020.check(df(["FROM debian:12-slim", "RUN apt-get update", "RUN apt-get install -y --no-install-recommends curl"]));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag update and install in one RUN", () => {
+    expect(dkrd020.check(df(["FROM debian:12-slim", "RUN apt-get update \\", "  && apt-get install -y --no-install-recommends curl"]))).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/relative-workdir.ts

@@ -0,0 +1,38 @@
+/**
+ * DKRD018: Relative WORKDIR
+ *
+ * A relative WORKDIR resolves against whatever directory the base image
+ * left, which can change with the image. Use an absolute path, at least for
+ * the first WORKDIR of a stage.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { eachDockerfile, stageLabel } from "./docker-helpers";
+
+export const dkrd018: PostSynthCheck = {
+  id: "DKRD018",
+  description: "Relative WORKDIR before any absolute WORKDIR in the stage",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        for (const instr of stage.instructions) {
+          if (instr.instruction !== "WORKDIR") continue;
+          const dir = instr.value.trim().replace(/^["']|["']$/g, "");
+          if (dir.startsWith("/") || dir.startsWith("$") || /^[A-Za-z]:[\\/]/.test(dir)) break;
+          diagnostics.push({
+            checkId: "DKRD018",
+            severity: "warning",
+            message: `${fileName} ${stageLabel(stage)}: WORKDIR ${dir} is relative to the base image's working directory. Use an absolute path.`,
+            lexicon: "docker",
+          });
+          break;
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/repeated-cmd.ts

@@ -0,0 +1,35 @@
+/**
+ * DKRD015: More than one CMD or ENTRYPOINT in a stage
+ *
+ * Only the last CMD and the last ENTRYPOINT of a stage take effect; the
+ * earlier ones are silently ignored.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { eachDockerfile, instrText, stageLabel } from "./docker-helpers";
+
+export const dkrd015: PostSynthCheck = {
+  id: "DKRD015",
+  description: "More than one CMD or ENTRYPOINT in a stage — only the last one takes effect",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        for (const kw of ["CMD", "ENTRYPOINT"]) {
+          const all = stage.instructions.filter((i) => i.instruction === kw);
+          if (all.length < 2) continue;
+          diagnostics.push({
+            checkId: "DKRD015",
+            severity: "warning",
+            message: `${fileName} ${stageLabel(stage)}: ${all.length} ${kw} instructions; only the last (${instrText(all[all.length - 1]!)}) takes effect. Remove the others.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,44 @@
+/**
+ * DKRD014: Root-only command after a non-root USER
+ *
+ * A RUN that installs packages or manages users and ownership (apt-get,
+ * apk add, useradd, chown, ...) fails or misbehaves after USER switches to
+ * an unprivileged user. Run root setup first, then switch USER.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { commandText, eachDockerfile, instrText, isRootUser, stageLabel } from "./docker-helpers";
+
+const ROOT_ONLY = /(^|[\s;&|(])(apt-get\s+(install|update|upgrade|dist-upgrade|remove|purge)|apt\s+(install|update|upgrade)|apk\s+(add|update|upgrade|del)|yum\s+(install|update)|dnf\s+(install|update|upgrade)|microdnf\s+install|zypper\s+(install|in|refresh)|useradd|adduser|groupadd|addgroup|usermod|chown)\b/;
+
+export const dkrd014: PostSynthCheck = {
+  id: "DKRD014",
+  description: "RUN needs root but comes after USER switched to a non-root user",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        let user: string | undefined;
+        for (const instr of stage.instructions) {
+          if (instr.instruction === "USER") {
+            user = instr.value.trim();
+            continue;
+          }
+          if (instr.instruction !== "RUN" || user === undefined || isRootUser(user)) continue;
+          const cmd = commandText(instr);
+          if (/\bsudo\b/.test(cmd) || !ROOT_ONLY.test(cmd)) continue;
+          diagnostics.push({
+            checkId: "DKRD014",
+            severity: "warning",
+            message: `${fileName} ${stageLabel(stage)}: ${instrText(instr)} needs root but runs as USER ${user}. Move it before the USER step, or switch to USER root for it.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/unused-global-arg.ts

@@ -0,0 +1,38 @@
+/**
+ * DKRD017: ARG before FROM that nothing uses
+ *
+ * An ARG declared before the first FROM is only visible to FROM lines, and
+ * to stages that declare it again (`ARG NAME`). One that neither uses does
+ * nothing.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { eachDockerfile } from "./docker-helpers";
+
+export const dkrd017: PostSynthCheck = {
+  id: "DKRD017",
+  description: "ARG before the first FROM is not used by any FROM or stage",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, content, parsed } of eachDockerfile(ctx.outputs)) {
+      const fromLines = content.split("\n").filter((l) => /^\s*FROM\s/i.test(l)).join("\n");
+      for (const arg of parsed.globalArgs) {
+        const name = arg.value.trim().split("=")[0]!.trim();
+        if (!name) continue;
+        const used = new RegExp(`\\$\\{?${name}\\b`).test(fromLines);
+        const redeclared = parsed.stages.some((s) => s.instructions.some((i) => i.instruction === "ARG" && i.value.trim().split("=")[0]!.trim() === name));
+        if (used || redeclared) continue;
+        diagnostics.push({
+          checkId: "DKRD017",
+          severity: "warning",
+          message: `${fileName}: ARG ${name} is declared before FROM but no FROM uses it and no stage declares it again with ARG ${name}. Use it, declare it in the stage that needs it, or remove it.`,
+          lexicon: "docker",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -3,3 +3,4 @@
  */
 
 export { noLatestTagRule } from "./no-latest-tag";
+export { perKindOrderRule } from "./per-kind-order";