@intentius/chant-lexicon-docker 0.124.21 → 0.124.22

package/src/generated/index.ts

@@ -8,3 +8,120 @@ export const DockerConfig = createResource("Docker::Compose::Config", "docker",
 export const DockerSecret = createResource("Docker::Compose::Secret", "docker", {});
 
 export const Dockerfile = createResource("Docker::Dockerfile", "docker", {});
+
+/** The Dockerfile instructions a step can name. FROM is the stage's own `from` field. */
+export type DockerfileInstructionName = "arg" | "env" | "run" | "copy" | "add" | "workdir" | "user" | "expose" | "volume" | "label" | "entrypoint" | "cmd" | "healthcheck" | "shell" | "stopsignal" | "onbuild";
+type DockerfileStepOf<K extends DockerfileInstructionName, V> = { [P in K]: V } & { [P in Exclude<DockerfileInstructionName, K>]?: never };
+/**
+ * One Dockerfile instruction, named by its single key: `{ run: "npm ci" }` is `RUN npm ci`.
+ * A string[] value (run, cmd, entrypoint, shell) is written in JSON exec form.
+ */
+export type DockerfileStep =
+  /** ARG: Build-time argument */
+  | DockerfileStepOf<"arg", string>
+  /** ENV: Environment variable */
+  | DockerfileStepOf<"env", string>
+  /** RUN: Run a command during build */
+  | DockerfileStepOf<"run", string | string[]>
+  /** COPY: Copy files from build context */
+  | DockerfileStepOf<"copy", string>
+  /** ADD: Add files (supports URLs and archives) */
+  | DockerfileStepOf<"add", string>
+  /** WORKDIR: Set working directory */
+  | DockerfileStepOf<"workdir", string>
+  /** USER: Set user for subsequent instructions */
+  | DockerfileStepOf<"user", string>
+  /** EXPOSE: Document exposed ports */
+  | DockerfileStepOf<"expose", string | number>
+  /** VOLUME: Create mount points */
+  | DockerfileStepOf<"volume", string>
+  /** LABEL: Add metadata labels */
+  | DockerfileStepOf<"label", string>
+  /** ENTRYPOINT: Set the entrypoint executable */
+  | DockerfileStepOf<"entrypoint", string | string[]>
+  /** CMD: Default command arguments */
+  | DockerfileStepOf<"cmd", string | string[]>
+  /** HEALTHCHECK: Health check instruction */
+  | DockerfileStepOf<"healthcheck", string>
+  /** SHELL: Set the shell for shell-form commands (JSON array form) */
+  | DockerfileStepOf<"shell", string | string[]>
+  /** STOPSIGNAL: Signal sent to stop the container */
+  | DockerfileStepOf<"stopsignal", string>
+  /** ONBUILD: Instruction to run when the image is used as a base */
+  | DockerfileStepOf<"onbuild", string>;
+/**
+ * One build stage: FROM, then its instructions.
+ * Without `steps`, the per-kind fields are written in a fixed order: ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK.
+ */
+export interface DockerfileStage {
+  from: string;
+  as?: string;
+  /** Instructions after FROM, written exactly in this order. Can't be combined with the per-kind fields. */
+  steps?: DockerfileStep[];
+  /** ARG as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  arg?: string[];
+  /** ENV as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  env?: string[];
+  /** RUN as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  run?: string[];
+  /** COPY as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  copy?: string[];
+  /** ADD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  add?: string[];
+  /** WORKDIR as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  workdir?: string;
+  /** USER as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  user?: string;
+  /** EXPOSE as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  expose?: string[];
+  /** VOLUME as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  volume?: string[];
+  /** LABEL as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  label?: string[];
+  /** ENTRYPOINT as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  entrypoint?: string;
+  /** CMD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  cmd?: string;
+  /** HEALTHCHECK as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  healthcheck?: string;
+}
+/**
+ * A Dockerfile: `stages` for a multi-stage build, or `from` and the stage fields for one stage.
+ * Without `steps`, the per-kind fields are written in a fixed order: ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK.
+ */
+export interface DockerfileProps {
+  name?: string;
+  /** ARG instructions written before the first FROM, e.g. `["NODE_VERSION=20"]`. */
+  globalArgs?: string[];
+  from?: string;
+  as?: string;
+  stages?: DockerfileStage[];
+  /** Instructions after FROM, written exactly in this order. Can't be combined with the per-kind fields. */
+  steps?: DockerfileStep[];
+  /** ARG as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  arg?: string[];
+  /** ENV as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  env?: string[];
+  /** RUN as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  run?: string[];
+  /** COPY as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  copy?: string[];
+  /** ADD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  add?: string[];
+  /** WORKDIR as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  workdir?: string;
+  /** USER as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  user?: string;
+  /** EXPOSE as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  expose?: string[];
+  /** VOLUME as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  volume?: string[];
+  /** LABEL as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  label?: string[];
+  /** ENTRYPOINT as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  entrypoint?: string;
+  /** CMD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  cmd?: string;
+  /** HEALTHCHECK as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
+  healthcheck?: string;
+}

package/src/generated/lexicon-docker.json

@@ -220,6 +220,12 @@
       },
       "healthcheck": {
         "description": "Health check instruction"
+      },
+      "globalArgs": {
+        "description": "ARG instructions written before the first FROM"
+      },
+      "steps": {
+        "description": "Instructions after FROM, written in the order given; one instruction per step"
       }
     }
   }

package/src/import/adapter.ts

@@ -13,7 +13,7 @@
 
 import type { TemplateIR, TemplateParser, ResourceIR } from "@intentius/chant/import/parser";
 import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
-import { DockerParser } from "./parser";
+import { DockerParser, DockerfileParser, looksLikeDockerfile } from "./parser";
 import type { DockerIR, DockerfileStage } from "./parser";
 import { DockerGenerator } from "./generator";
 
@@ -23,7 +23,7 @@ function dockerIrToResource(entity: DockerIR): ResourceIR {
     return {
       logicalId: entity.name,
       type: entity.kind,
-      properties: { stages: entity.stages },
+      properties: { ...(entity.globalArgs ? { globalArgs: entity.globalArgs } : {}), stages: entity.stages },
     };
   }
   return {
@@ -41,6 +41,7 @@ function resourceToDockerIr(resource: ResourceIR): DockerIR {
       return {
         kind: "dockerfile",
         name,
+        ...(Array.isArray(resource.properties.globalArgs) ? { globalArgs: resource.properties.globalArgs as string[] } : {}),
         stages: (resource.properties.stages as DockerfileStage[] | undefined) ?? [],
       };
     case "service":
@@ -66,6 +67,11 @@ function resourceToDockerIr(resource: ResourceIR): DockerIR {
  */
 export class DockerTemplateParser implements TemplateParser {
   parse(content: string): TemplateIR {
+    // A Dockerfile has no name of its own; it imports as `app`
+    // (Dockerfile.app). Rename the export to choose the file name.
+    if (looksLikeDockerfile(content)) {
+      return { resources: [dockerIrToResource(new DockerfileParser().parse("app", content))], parameters: [] };
+    }
     const { entities } = new DockerParser().parse(content);
     return {
       resources: entities.map(dockerIrToResource),

package/src/import/generator.ts

@@ -44,7 +44,7 @@ export class DockerGenerator {
           break;
         case "dockerfile":
           imports.add("Dockerfile");
-          lines.push(generateDockerfile(entity));
+          lines.push(generateDockerfile(entity, warnings));
           break;
       }
     }
@@ -82,43 +82,59 @@ function generateSecret(sec: SecretIR): string {
   return `export const ${sanitizeName(sec.name)} = new Secret(${hasProps ? JSON.stringify(sec.props) : "{}"});`;
 }
 
-function generateDockerfile(df: DockerfileIR): string {
-  if (df.stages.length > 1) {
-    // Multi-stage: emit stages array
-    const props = { stages: df.stages };
-    const propsStr = JSON.stringify(props, null, 2).replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
-    return `export const ${sanitizeName(df.name)} = new Dockerfile(${propsStr});`;
-  }
-
-  // Single-stage: flat props (preserved behaviour)
-  const stage = df.stages[0];
-  const props: Record<string, unknown> = {};
-  if (stage) props.from = stage.from;
-
-  // Group instructions by type
-  const grouped: Record<string, string[]> = {};
-  for (const { instruction, value } of stage?.instructions ?? []) {
-    const key = instruction.toLowerCase();
-    if (!grouped[key]) grouped[key] = [];
-    grouped[key].push(value);
-  }
+/** The instructions a step can name; anything else (MAINTAINER) is left as a comment. */
+const STEP_KEYS = new Set([
+  "arg", "env", "workdir", "user", "run", "copy", "add", "expose", "volume",
+  "label", "entrypoint", "cmd", "healthcheck", "shell", "stopsignal", "onbuild",
+]);
 
-  // Single-value instructions
-  for (const single of ["workdir", "user", "entrypoint", "cmd", "healthcheck"]) {
-    if (grouped[single]?.length === 1) {
-      props[single] = grouped[single][0];
+/**
+ * A Dockerfile always imports as `steps`, one per instruction in source
+ * order, so building the import gives the same instructions in the same
+ * order (the per-kind fields would reorder them).
+ */
+function generateDockerfile(df: DockerfileIR, warnings: string[]): string {
+  const out: string[] = [`export const ${sanitizeName(df.name)} = new Dockerfile({`];
+  if (df.globalArgs?.length) out.push(`  globalArgs: [${df.globalArgs.map((a) => JSON.stringify(a)).join(", ")}],`);
+
+  const steps = (stage: DockerfileIR["stages"][number], indent: string): void => {
+    out.push(`${indent}steps: [`);
+    for (const { instruction, value } of stage.instructions) {
+      const key = instruction.toLowerCase();
+      if (STEP_KEYS.has(key)) {
+        out.push(`${indent}  { ${key}: ${quote(value)} },`);
+      } else {
+        warnings.push(`Dockerfile ${df.name}: ${instruction} has no step and was left as a comment`);
+        out.push(`${indent}  // ${instruction} ${value.replace(/\n/g, " ")}`);
+      }
     }
-  }
-
-  // Multi-value instructions
-  for (const multi of ["run", "copy", "add", "env", "arg", "expose", "volume", "label"]) {
-    if (grouped[multi]?.length) {
-      props[multi] = grouped[multi].length === 1 ? grouped[multi] : grouped[multi];
+    out.push(`${indent}],`);
+  };
+
+  if (df.stages.length === 1) {
+    const stage = df.stages[0]!;
+    out.push(`  from: ${JSON.stringify(stage.from)},`);
+    if (stage.as) out.push(`  as: ${JSON.stringify(stage.as)},`);
+    steps(stage, "  ");
+  } else {
+    out.push(`  stages: [`);
+    for (const stage of df.stages) {
+      out.push(`    {`);
+      out.push(`      from: ${JSON.stringify(stage.from)},`);
+      if (stage.as) out.push(`      as: ${JSON.stringify(stage.as)},`);
+      steps(stage, "      ");
+      out.push(`    },`);
     }
+    out.push(`  ],`);
   }
+  out.push(`});`);
+  return out.join("\n");
+}
 
-  const propsStr = JSON.stringify(props, null, 2).replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
-  return `export const ${sanitizeName(df.name)} = new Dockerfile(${propsStr});`;
+/** A string literal, single-quoted when that avoids escaping double quotes (exec form: `'["node", "a.js"]'`). */
+function quote(value: string): string {
+  if (value.includes('"') && !/['\\\n]/.test(value)) return `'${value}'`;
+  return JSON.stringify(value);
 }
 
 function sanitizeName(name: string): string {

package/src/import/parser.ts

@@ -38,12 +38,19 @@ export interface SecretIR {
 export interface DockerfileStage {
   from: string;
   as?: string;
+  /**
+   * The stage's instructions after FROM, in source order. `instruction` is
+   * the upper-case keyword; `value` is the rest of the instruction as
+   * written, line continuations and heredoc bodies included.
+   */
   instructions: Array<{ instruction: string; value: string }>;
 }
 
 export interface DockerfileIR {
   kind: "dockerfile";
   name: string;
+  /** ARG values declared before the first FROM. */
+  globalArgs?: string[];
   stages: DockerfileStage[];
 }
 
@@ -154,37 +161,99 @@ export class DockerParser {
   }
 }
 
+/** One logical Dockerfile instruction: its upper-case keyword and the rest as written. */
+export interface DockerfileInstruction {
+  instruction: string;
+  value: string;
+}
+
+/**
+ * Split Dockerfile content into logical instructions, in order. Comment
+ * and blank lines are dropped (also inside a continued instruction, as
+ * Docker does). A line ending in a backslash continues onto the next line,
+ * and a heredoc (`RUN <<EOF` ... `EOF`) runs to its terminator; both are
+ * kept in the value exactly as written, so writing the value back gives
+ * the same instruction.
+ */
+export function splitDockerfileInstructions(content: string): DockerfileInstruction[] {
+  const out: DockerfileInstruction[] = [];
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const first = lines[i]!;
+    i++;
+    const trimmed = first.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const parts = [first.trimStart()];
+    let last = first;
+    while (/\\\s*$/.test(last) && i < lines.length) {
+      const next = lines[i]!;
+      i++;
+      // Docker skips comment and empty lines inside a continued instruction.
+      if (!next.trim() || next.trim().startsWith("#")) continue;
+      parts.push(next);
+      last = next;
+    }
+
+    // Heredocs: <<EOF, <<-EOF, <<"EOF", <<'EOF' (possibly several).
+    const joined = parts.join("\n");
+    const terminators = [...joined.matchAll(/<<(-?)(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g)].map((m) => ({ dash: m[1] === "-", word: m[3]! }));
+    for (const t of terminators) {
+      while (i < lines.length) {
+        const body = lines[i]!;
+        i++;
+        parts.push(body);
+        if ((t.dash ? body.replace(/^\t+/, "") : body) === t.word) break;
+      }
+    }
+
+    const text = parts.join("\n").trimEnd();
+    const match = text.match(/^([A-Za-z]+)(?:\s+([\s\S]*))?$/);
+    if (!match) continue;
+    out.push({ instruction: match[1]!.toUpperCase(), value: (match[2] ?? "").trimStart() });
+  }
+  return out;
+}
+
 /**
  * Parser for Dockerfile content.
  */
 export class DockerfileParser {
   parse(name: string, content: string): DockerfileIR {
     const stages: DockerfileStage[] = [];
+    const globalArgs: string[] = [];
     let current: DockerfileStage | null = null;
 
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-
-      const match = trimmed.match(/^([A-Z]+)\s+([\s\S]+)$/);
-      if (!match) continue;
-
-      const [, instruction, value] = match;
-
+    for (const { instruction, value } of splitDockerfileInstructions(content)) {
       if (instruction === "FROM") {
-        // Parse "FROM image AS stagename"
+        // Parse "FROM [--platform=...] image AS stagename"
         const asMatch = value.match(/^(.+?)\s+[Aa][Ss]\s+(\S+)$/);
         if (asMatch) {
-          current = { from: asMatch[1].trim(), as: asMatch[2].trim(), instructions: [] };
+          current = { from: asMatch[1]!.trim(), as: asMatch[2]!.trim(), instructions: [] };
         } else {
           current = { from: value.trim(), instructions: [] };
         }
         stages.push(current);
       } else if (current) {
-        current.instructions.push({ instruction, value: value.trim() });
+        current.instructions.push({ instruction, value });
+      } else if (instruction === "ARG") {
+        globalArgs.push(value);
       }
     }
 
-    return { kind: "dockerfile", name, stages };
+    return { kind: "dockerfile", name, ...(globalArgs.length > 0 ? { globalArgs } : {}), stages };
+  }
+}
+
+/** Whether content reads as a Dockerfile: its first instruction is FROM or ARG, or it starts with a parser directive. */
+export function looksLikeDockerfile(content: string): boolean {
+  for (const line of content.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    if (/^#\s*(syntax|escape|check)\s*=/i.test(t)) return true;
+    if (t.startsWith("#")) continue;
+    return /^(FROM|ARG)\s/i.test(t);
   }
+  return false;
 }

package/src/import/roundtrip.test.ts

@@ -3,6 +3,24 @@ import { readFileSync } from "fs";
 import { join } from "path";
 import { DockerParser, DockerfileParser } from "./parser";
 import { DockerGenerator } from "./generator";
+import { DockerTemplateGenerator, DockerTemplateParser } from "./adapter";
+import { Dockerfile } from "../generated/index";
+import { dockerSerializer } from "../serializer";
+import type { Declarable } from "@intentius/chant/declarable";
+
+/**
+ * Dockerfile -> TypeScript -> Dockerfile. The generated source is run (its
+ * import line dropped, its exports collected) and the entity it declares is
+ * serialized again.
+ */
+function roundTrip(content: string, source?: string): { source: string; dockerfile: string } {
+  const src = source ?? new DockerGenerator().generate([new DockerfileParser().parse("app", content)]).source;
+  const body = src.replace(/^import .*$/m, "").replace(/export const (\w+) =/g, "out.$1 =");
+  const out: Record<string, Declarable> = {};
+  new Function("Dockerfile", "out", body)(Dockerfile, out);
+  const result = dockerSerializer.serialize(new Map(Object.entries(out))) as { files: Record<string, string> };
+  return { source: src, dockerfile: Object.values(result.files)[0]! };
+}
 
 const testdata = (file: string) =>
   readFileSync(join(import.meta.dirname, "testdata", file), "utf8");
@@ -46,4 +64,91 @@ describe("roundtrip: parse → generate", () => {
     expect(source).toContain("node:20-alpine");
     expect(source).toContain("nginx:1.25");
   });
+
+});
+
+describe("roundtrip: Dockerfile → TypeScript → Dockerfile keeps the instruction order", () => {
+  test("interleaved COPY and RUN", () => {
+    const content = [
+      "FROM node:20-alpine",
+      "WORKDIR /app",
+      "COPY package*.json ./",
+      "RUN npm ci",
+      "COPY . .",
+      "RUN npm run build",
+      'CMD ["node", "dist/index.js"]',
+      "",
+    ].join("\n");
+    const { source, dockerfile } = roundTrip(content);
+    expect(source).toContain("steps: [");
+    expect(dockerfile).toBe(content);
+  });
+
+  test("USER after RUN stays after it", () => {
+    const content = [
+      "FROM debian:12-slim",
+      "RUN apt-get update && apt-get install -y --no-install-recommends curl",
+      "RUN useradd --system app",
+      "USER app",
+      "RUN whoami",
+      "",
+    ].join("\n");
+    expect(roundTrip(content).dockerfile).toBe(content);
+  });
+
+  test("multi-stage, ARG before FROM, SHELL, STOPSIGNAL, ONBUILD and repeated WORKDIR", () => {
+    const content = [
+      "ARG NODE_VERSION=20",
+      "FROM node:${NODE_VERSION}-alpine AS build",
+      'SHELL ["/bin/sh", "-c"]',
+      "WORKDIR /src",
+      "COPY . .",
+      "WORKDIR /src/app",
+      "RUN npm run build",
+      "FROM nginx:1.27-alpine",
+      "COPY --from=build /src/app/dist /usr/share/nginx/html",
+      "ONBUILD COPY . /usr/share/nginx/html",
+      "STOPSIGNAL SIGQUIT",
+      "",
+    ].join("\n");
+    const { source, dockerfile } = roundTrip(content);
+    expect(source).toContain('globalArgs: ["NODE_VERSION=20"]');
+    expect(dockerfile).toBe(content);
+  });
+
+  test("line continuations and heredocs are kept as written", () => {
+    const content = [
+      "# syntax=docker/dockerfile:1",
+      "FROM debian:12-slim",
+      "RUN apt-get update \\",
+      "    # a comment Docker drops",
+      "    && apt-get install -y --no-install-recommends curl",
+      "RUN <<EOF",
+      "set -e",
+      "echo hello > /hello",
+      "EOF",
+      "USER nobody",
+      "",
+    ].join("\n");
+    const { dockerfile } = roundTrip(content);
+    expect(dockerfile).toBe([
+      "FROM debian:12-slim",
+      "RUN apt-get update \\",
+      "    && apt-get install -y --no-install-recommends curl",
+      "RUN <<EOF",
+      "set -e",
+      "echo hello > /hello",
+      "EOF",
+      "USER nobody",
+      "",
+    ].join("\n"));
+  });
+
+  test("chant import of a Dockerfile goes through the template adapter", () => {
+    const content = "FROM alpine:3.20\nCOPY run.sh /run.sh\nRUN chmod +x /run.sh\nUSER nobody\n";
+    const ir = new DockerTemplateParser().parse(content);
+    const [file] = new DockerTemplateGenerator().generate(ir);
+    expect(file!.content).toContain("export const app = new Dockerfile({");
+    expect(roundTrip(content, file!.content).dockerfile).toBe(content);
+  });
 });

package/src/lint/audit-catalog.ts

@@ -13,7 +13,15 @@ export const dockerAuditCatalog: Record<string, RuleMeta> = {
   DKRD003: auditRule("DKRD003", "merge-worthy", "guidance", "Service exposes SSH (port 22)", "Don't expose SSH from a container; use exec/ephemeral access instead.", { authority: [DOCKER_SEC] }),
   DKRD010: auditRule("DKRD010", "report-only", "guidance", "apt-get install without --no-install-recommends", "Add --no-install-recommends to keep images small.", { category: "best-practice" }),
   DKRD011: auditRule("DKRD011", "report-only", "guidance", "ADD used where COPY would do", "Prefer COPY unless fetching a URL or extracting an archive.", { category: "best-practice" }),
-  DKRD012: auditRule("DKRD012", "merge-worthy", "guidance", "No USER instruction — container runs as root", "Add a non-root USER instruction.", { authority: [DOCKER_SEC] }),
+  DKRD012: auditRule("DKRD012", "merge-worthy", "guidance", "Container runs as root: the final stage has no USER, or ends on USER root", "Add a non-root USER instruction to the final stage, after the root setup steps.", { authority: [DOCKER_SEC] }),
+  DKRD013: auditRule("DKRD013", "report-only", "guidance", "Whole build context copied before a dependency install", "Copy the dependency manifests, run the install, then copy the rest of the source.", { category: "efficiency" }),
+  DKRD014: auditRule("DKRD014", "report-only", "guidance", "Root-only RUN after a non-root USER", "Run package installs and user/ownership changes before switching USER.", { category: "correctness" }),
+  DKRD015: auditRule("DKRD015", "report-only", "guidance", "More than one CMD or ENTRYPOINT in a stage", "Keep one CMD and one ENTRYPOINT per stage; only the last takes effect.", { category: "correctness" }),
+  DKRD016: auditRule("DKRD016", "report-only", "guidance", "COPY --from names no earlier stage", "Name a stage defined earlier in the Dockerfile, or a tagged image.", { category: "correctness" }),
+  DKRD017: auditRule("DKRD017", "report-only", "guidance", "ARG before FROM is never used", "Use the ARG in a FROM line, declare it again in the stage that needs it, or remove it.", { category: "best-practice" }),
+  DKRD018: auditRule("DKRD018", "report-only", "guidance", "Relative WORKDIR", "Use an absolute WORKDIR path.", { category: "best-practice" }),
+  DKRD019: auditRule("DKRD019", "report-only", "guidance", "ADD of a remote URL without --checksum", "Add --checksum=sha256:<digest> to ADD of an http(s) URL.", { category: "security" }),
+  DKRD020: auditRule("DKRD020", "report-only", "guidance", "apt-get update in its own RUN", "Run apt-get update and apt-get install in the same RUN.", { category: "correctness" }),
 };
 
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).

package/src/lint/audit-lineage.ts

@@ -30,5 +30,19 @@ export const dockerAuditLineage: Record<string, Lineage[]> = {
     { tool: "checkov", rule: "CKV_DOCKER_3", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "equivalent" },
     { tool: "kics", rule: "missing_user_instruction", url: "https://docs.kics.io/latest/queries/dockerfile-queries/fd54f200-402c-4333-a5a4-36ef6709af2f/", relation: "equivalent" },
     { tool: "dockle", rule: "CIS-DI-0001", url: "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#cis-di-0001", relation: "overlaps" },
+    { tool: "hadolint", rule: "DL3002", url: "https://github.com/hadolint/hadolint/wiki/DL3002", relation: "overlaps" },
+  ],
+  DKRD015: [
+    { tool: "hadolint", rule: "DL4003", url: "https://github.com/hadolint/hadolint/wiki/DL4003", relation: "overlaps" },
+    { tool: "hadolint", rule: "DL4004", url: "https://github.com/hadolint/hadolint/wiki/DL4004", relation: "overlaps" },
+  ],
+  DKRD016: [
+    { tool: "hadolint", rule: "DL3022", url: "https://github.com/hadolint/hadolint/wiki/DL3022", relation: "overlaps" },
+  ],
+  DKRD018: [
+    { tool: "hadolint", rule: "DL3000", url: "https://github.com/hadolint/hadolint/wiki/DL3000", relation: "overlaps" },
+  ],
+  DKRD020: [
+    { tool: "checkov", rule: "CKV_DOCKER_5", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "overlaps" },
   ],
 };

package/src/lint/post-synth/add-url-checksum.ts

@@ -0,0 +1,38 @@
+/**
+ * DKRD019: ADD of a remote URL without --checksum
+ *
+ * ADD fetches an http(s) URL at build time and trusts whatever comes back.
+ * `ADD --checksum=sha256:...` makes the build fail when the content changes.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { eachDockerfile, stageLabel } from "./docker-helpers";
+
+export const dkrd019: PostSynthCheck = {
+  id: "DKRD019",
+  description: "ADD fetches a remote URL without --checksum",
+
+  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 !== "ADD") continue;
+          const words = instr.value.split(/\s+/);
+          if (words.some((w) => w.startsWith("--checksum="))) continue;
+          const url = words.find((w) => /^https?:\/\//i.test(w));
+          if (!url) continue;
+          diagnostics.push({
+            checkId: "DKRD019",
+            severity: "warning",
+            message: `${fileName} ${stageLabel(stage)}: ADD ${url} has no --checksum, so the build accepts whatever the URL serves. Add --checksum=sha256:<digest>.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/apt-update-alone.ts

@@ -0,0 +1,39 @@
+/**
+ * DKRD020: apt-get update in its own RUN
+ *
+ * A RUN that only runs `apt-get update` is cached as its own layer, so a
+ * later `apt-get install` in another RUN can install from a stale package
+ * index. Update and install in the same RUN.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { commandText, eachDockerfile, stageLabel } from "./docker-helpers";
+
+const UPDATE = /\bapt(-get)?\s+update\b/;
+const INSTALL = /\bapt(-get)?\s+(install|upgrade|dist-upgrade)\b/;
+
+export const dkrd020: PostSynthCheck = {
+  id: "DKRD020",
+  description: "apt-get update in a different RUN from apt-get install — the install can use a stale package index",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+      for (const stage of parsed.stages) {
+        const runs = stage.instructions.filter((i) => i.instruction === "RUN");
+        const updateAt = runs.findIndex((r) => UPDATE.test(commandText(r)) && !INSTALL.test(commandText(r)));
+        if (updateAt === -1) continue;
+        if (!runs.slice(updateAt + 1).some((r) => INSTALL.test(commandText(r)))) continue;
+        diagnostics.push({
+          checkId: "DKRD020",
+          severity: "warning",
+          message: `${fileName} ${stageLabel(stage)}: apt-get update runs in its own RUN, and a later RUN installs from that cached index. Run update and install in one RUN: apt-get update && apt-get install -y --no-install-recommends ...`,
+          lexicon: "docker",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};