@intentius/chant-lexicon-docker 0.124.20 → 0.124.22

package/src/lint/rules/per-kind-order.ts

@@ -0,0 +1,130 @@
+/**
+ * DKRS002: Per-kind Dockerfile fields written in a different order
+ *
+ * A Dockerfile stage without `steps` writes its per-kind fields (`run`,
+ * `copy`, `user`, ...) in a fixed order: ARG, ENV, WORKDIR, USER, RUN, COPY,
+ * ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK. When the fields
+ * are declared in another order (`copy` before `run`, `run` before `user`)
+ * the generated Dockerfile does not run them in the order they read in.
+ *
+ * The fix rewrites the fields as `steps` in the fixed order, so the
+ * generated Dockerfile stays the same, with a comment to reorder them.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext, LintFix } from "@intentius/chant/lint/rule";
+import { ts } from "@intentius/chant/lint/typescript";
+import { PER_KIND_ORDER, type PerKindField } from "../../dockerfile-order";
+
+const PER_KIND = new Set<string>(PER_KIND_ORDER);
+/** Per-kind fields that take one string; the rest take a list. */
+const SINGLE = new Set<string>(["workdir", "user", "entrypoint", "cmd", "healthcheck"]);
+
+const FIX_NOTE = "// Written by the DKRS002 fix in the fixed order the per-kind fields used, so the output is unchanged. Reorder the steps as the build needs.";
+
+function propName(p: ts.ObjectLiteralElementLike): string | undefined {
+  if (!(ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p))) return undefined;
+  const n = p.name;
+  if (ts.isIdentifier(n) || ts.isStringLiteral(n)) return n.text;
+  return undefined;
+}
+
+function isDockerfileNew(node: ts.Node): node is ts.NewExpression {
+  if (!ts.isNewExpression(node)) return false;
+  const e = node.expression;
+  return (ts.isIdentifier(e) && e.text === "Dockerfile") || (ts.isPropertyAccessExpression(e) && e.name.text === "Dockerfile");
+}
+
+/** The stage-shaped object literals of one `new Dockerfile({...})`. */
+function stageLiterals(arg: ts.ObjectLiteralExpression): ts.ObjectLiteralExpression[] {
+  const stagesProp = arg.properties.find((p) => propName(p) === "stages");
+  if (!stagesProp) return [arg];
+  // With stages, the top-level per-kind fields are not written at all.
+  if (!ts.isPropertyAssignment(stagesProp) || !ts.isArrayLiteralExpression(stagesProp.initializer)) return [];
+  return stagesProp.initializer.elements.filter(ts.isObjectLiteralExpression);
+}
+
+/** The `{ key: value }` step texts for one per-kind field, or undefined when its value can't be split. */
+function stepTexts(sf: ts.SourceFile, key: string, p: ts.ObjectLiteralElementLike): string[] | undefined {
+  if (!ts.isPropertyAssignment(p)) return undefined;
+  const init = p.initializer;
+  if (SINGLE.has(key)) return [`{ ${key}: ${init.getText(sf)} }`];
+  if (!ts.isArrayLiteralExpression(init)) return undefined;
+  const out: string[] = [];
+  for (const el of init.elements) {
+    if (ts.isSpreadElement(el) || ts.isOmittedExpression(el)) return undefined;
+    out.push(`{ ${key}: ${el.getText(sf)} }`);
+  }
+  return out;
+}
+
+function buildFix(sf: ts.SourceFile, obj: ts.ObjectLiteralExpression, perKind: ts.ObjectLiteralElementLike[]): LintFix | undefined {
+  const byKey = new Map<string, ts.ObjectLiteralElementLike>();
+  for (const p of perKind) byKey.set(propName(p)!, p);
+  const steps: string[] = [];
+  for (const key of PER_KIND_ORDER) {
+    const p = byKey.get(key);
+    if (!p) continue;
+    const texts = stepTexts(sf, key, p);
+    if (!texts) return undefined;
+    steps.push(...texts);
+  }
+
+  const first = perKind[0]!;
+  const last = perKind[perKind.length - 1]!;
+  const start = first.getStart(sf);
+  const end = last.getEnd();
+  const lineStart = sf.text.lastIndexOf("\n", start - 1) + 1;
+  const indent = /^[ \t]*/.exec(sf.text.slice(lineStart, start))![0];
+  // Other props between the first and last per-kind field (rare) are kept, ahead of steps.
+  const kept = obj.properties.filter((p) => p.getStart(sf) > start && p.getEnd() < end && !perKind.includes(p)).map((p) => p.getText(sf));
+  const stepsText = `${FIX_NOTE}\n${indent}steps: [\n${steps.map((s) => `${indent}  ${s},`).join("\n")}\n${indent}]`;
+  return { range: [start, end], replacement: [...kept, stepsText].join(`,\n${indent}`), kind: "replace" };
+}
+
+function check(context: LintContext): LintDiagnostic[] {
+  const { sourceFile: sf } = context;
+  const diagnostics: LintDiagnostic[] = [];
+
+  const visit = (node: ts.Node): void => {
+    if (isDockerfileNew(node)) {
+      const arg = node.arguments?.[0];
+      if (arg && ts.isObjectLiteralExpression(arg)) {
+        for (const obj of stageLiterals(arg)) {
+          if (obj.properties.some((p) => propName(p) === "steps")) continue;
+          const perKind = obj.properties.filter((p) => PER_KIND.has(propName(p) ?? ""));
+          const declared = perKind.map((p) => propName(p)!);
+          const fixed = [...declared].sort((a, b) => PER_KIND_ORDER.indexOf(a as PerKindField) - PER_KIND_ORDER.indexOf(b as PerKindField));
+          if (declared.join() === fixed.join()) continue;
+          const { line, character } = sf.getLineAndCharacterOfPosition(perKind[0]!.getStart(sf));
+          const fix = buildFix(sf, obj, perKind);
+          diagnostics.push({
+            file: sf.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "DKRS002",
+            severity: "warning",
+            message:
+              `Dockerfile fields declared as ${declared.join(", ")} are written in the fixed order ${fixed.join(", ")}. ` +
+              `Use steps to write the instructions in the order the build needs${fix ? " (chant lint --fix rewrites them as steps)" : ""}.`,
+            ...(fix ? { fix } : {}),
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sf);
+  return diagnostics;
+}
+
+export const perKindOrderRule: LintRule = {
+  id: "DKRS002",
+  severity: "warning",
+  category: "correctness",
+  description: "Dockerfile per-kind fields are written in a fixed order that differs from the declared order — use steps",
+  check,
+  fix(context: LintContext): LintFix[] {
+    return check(context).flatMap((d) => (d.fix ? [d.fix] : []));
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -1,5 +1,9 @@
 import { describe, test, expect } from "vitest";
 import { noLatestTagRule } from "./no-latest-tag";
+import { perKindOrderRule } from "./per-kind-order";
+import { dockerSerializer } from "../../serializer";
+import { Dockerfile } from "../../generated/index";
+import type { Declarable } from "@intentius/chant/declarable";
 import type { LintContext } from "@intentius/chant/lint/rule";
 import * as ts from "typescript";
 
@@ -80,3 +84,87 @@ describe("DKRS001: no-latest-tag", () => {
     expect(diags).toHaveLength(0);
   });
 });
+
+// ── DKRS002: per-kind fields in a different order ─────────────────
+
+/** Apply a rule's fixes the way `chant lint --fix` does: last range first. */
+function applyFixes(code: string, fixes: Array<{ range: [number, number]; replacement: string }>): string {
+  for (const f of [...fixes].sort((a, b) => b.range[0] - a.range[0])) {
+    code = code.slice(0, f.range[0]) + f.replacement + code.slice(f.range[1]);
+  }
+  return code;
+}
+
+/** Run a module's `export const x = new Dockerfile(...)` and serialize what it declares. */
+function build(code: string): string {
+  const body = code.replace(/^\s*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 Object.values(result.files).join("---\n");
+}
+
+describe("DKRS002: per-kind-order", () => {
+  const reordered = `import { Dockerfile } from "@intentius/chant-lexicon-docker";
+export const app = new Dockerfile({
+  stages: [
+    {
+      from: "node:20-alpine",
+      as: "build",
+      workdir: "/app",
+      copy: ["package*.json ./", ". ."],
+      run: ["npm ci", "npm run build"],
+    },
+    {
+      from: "node:20-alpine",
+      workdir: "/app",
+      user: "node",
+      cmd: "node dist/index.js",
+    },
+  ],
+});
+`;
+
+  test("flags a stage whose fields read in a different order than they are written", () => {
+    const diags = perKindOrderRule.check(makeContext(reordered));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("DKRS002");
+    expect(diags[0].line).toBe(7);
+    expect(diags[0].message).toContain("declared as workdir, copy, run are written in the fixed order workdir, run, copy");
+  });
+
+  test("flags USER declared after RUN, on a single-stage Dockerfile", () => {
+    const diags = perKindOrderRule.check(makeContext(`new Dockerfile({ from: "debian:12", run: ["useradd app"], user: "app" });`));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("run, user");
+  });
+
+  test("does not flag fields already in the fixed order, steps, or other objects", () => {
+    expect(perKindOrderRule.check(makeContext(`new Dockerfile({ from: "a:1", workdir: "/app", user: "node", run: ["x"], copy: [". ."], cmd: "y" });`))).toHaveLength(0);
+    expect(perKindOrderRule.check(makeContext(`new Dockerfile({ from: "a:1", steps: [{ copy: ". ." }, { run: "x" }] });`))).toHaveLength(0);
+    expect(perKindOrderRule.check(makeContext(`const o = { copy: ["a"], run: ["b"] };`))).toHaveLength(0);
+  });
+
+  test("the fix rewrites the fields as steps and the output does not change", () => {
+    const fixes = perKindOrderRule.fix!(makeContext(reordered));
+    expect(fixes).toHaveLength(1);
+    const fixed = applyFixes(reordered, fixes);
+    expect(fixed).toContain(`      // Written by the DKRS002 fix`);
+    expect(fixed).toContain(`      steps: [
+        { workdir: "/app" },
+        { run: "npm ci" },
+        { run: "npm run build" },
+        { copy: "package*.json ./" },
+        { copy: ". ." },
+      ],
+    },`);
+    expect(build(fixed)).toBe(build(reordered));
+    expect(perKindOrderRule.check(makeContext(fixed))).toHaveLength(0);
+  });
+
+  test("no fix when a list value can't be split into steps", () => {
+    const diags = perKindOrderRule.check(makeContext(`new Dockerfile({ from: "a:1", copy: files, run: ["x"] });`));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].fix).toBeUndefined();
+  });
+});

package/src/plugin.test.ts

@@ -17,6 +17,7 @@ describe("dockerPlugin", () => {
 
     const ruleIds = rules.map((r) => r.id);
     expect(ruleIds).toContain("DKRS001");
+    expect(ruleIds).toContain("DKRS002");
   });
 
   test("provides post-synth checks", () => {
@@ -30,6 +31,9 @@ describe("dockerPlugin", () => {
     expect(checkIds).toContain("DKRD010");
     expect(checkIds).toContain("DKRD011");
     expect(checkIds).toContain("DKRD012");
+    for (const id of ["DKRD013", "DKRD014", "DKRD015", "DKRD016", "DKRD017", "DKRD018", "DKRD019", "DKRD020"]) {
+      expect(checkIds).toContain(id);
+    }
   });
 
   test("provides intrinsics", () => {

package/src/plugin.ts

@@ -16,6 +16,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { dockerSerializer } from "./serializer";
 import { noLatestTagRule } from "./lint/rules/no-latest-tag";
+import { perKindOrderRule } from "./lint/rules/per-kind-order";
 import { dockerCompletions } from "./lsp/completions";
 import { dockerHover } from "./lsp/hover";
 import { DockerTemplateParser, DockerTemplateGenerator } from "./import/adapter";
@@ -33,7 +34,7 @@ export const dockerPlugin: LexiconPlugin = {
   serializer: dockerSerializer,
 
   lintRules(): LintRule[] {
-    return [noLatestTagRule];
+    return [noLatestTagRule, perKindOrderRule];
   },
 
   postSynthChecks() {

package/src/serializer.test.ts

@@ -306,6 +306,118 @@ describe("dockerSerializer.serialize — multi-stage Dockerfile", () => {
   });
 });
 
+// ── Dockerfile steps ──────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — Dockerfile steps", () => {
+  const dockerfile = (props: Record<string, unknown>): string => {
+    const result = dockerSerializer.serialize(new Map<string, Declarable>([["app", new MockDockerfile(props)]]));
+    return (result as { files: Record<string, string> }).files["Dockerfile.app"]!;
+  };
+
+  test("steps are written in the order given, interleaving COPY and RUN", () => {
+    expect(dockerfile({
+      from: "node:20-alpine",
+      steps: [
+        { workdir: "/app" },
+        { copy: "package*.json ./" },
+        { run: "npm ci" },
+        { copy: ". ." },
+        { run: "npm run build" },
+        { user: "node" },
+        { cmd: ["node", "dist/index.js"] },
+      ],
+    })).toBe([
+      "FROM node:20-alpine",
+      "WORKDIR /app",
+      "COPY package*.json ./",
+      "RUN npm ci",
+      "COPY . .",
+      "RUN npm run build",
+      "USER node",
+      'CMD ["node","dist/index.js"]',
+      "",
+    ].join("\n"));
+  });
+
+  test("every instruction is available as a step, and ARG before FROM comes from globalArgs", () => {
+    expect(dockerfile({
+      globalArgs: ["NODE_VERSION=20"],
+      stages: [{
+        from: "node:${NODE_VERSION}-alpine",
+        as: "base",
+        steps: [
+          { shell: ["/bin/sh", "-eo", "pipefail", "-c"] },
+          { arg: "APP_ENV=production" },
+          { env: "NODE_ENV=$APP_ENV" },
+          { label: 'org.opencontainers.image.title="app"' },
+          { workdir: "/app" },
+          { add: "https://example.com/a.tgz /tmp/" },
+          { volume: "/data" },
+          { expose: 8080 },
+          { stopsignal: "SIGTERM" },
+          { healthcheck: "CMD wget -qO- http://localhost:8080/health || exit 1" },
+          { onbuild: "COPY . /app" },
+          { entrypoint: ["/sbin/tini", "--"] },
+          { cmd: "node index.js" },
+        ],
+      }],
+    })).toBe([
+      "ARG NODE_VERSION=20",
+      "FROM node:${NODE_VERSION}-alpine AS base",
+      'SHELL ["/bin/sh","-eo","pipefail","-c"]',
+      "ARG APP_ENV=production",
+      "ENV NODE_ENV=$APP_ENV",
+      'LABEL org.opencontainers.image.title="app"',
+      "WORKDIR /app",
+      "ADD https://example.com/a.tgz /tmp/",
+      "VOLUME /data",
+      "EXPOSE 8080",
+      "STOPSIGNAL SIGTERM",
+      "HEALTHCHECK CMD wget -qO- http://localhost:8080/health || exit 1",
+      "ONBUILD COPY . /app",
+      'ENTRYPOINT ["/sbin/tini","--"]',
+      "CMD node index.js",
+      "",
+    ].join("\n"));
+  });
+
+  test("per-kind fields keep their fixed order, byte for byte", () => {
+    expect(dockerfile({
+      from: "node:20-alpine",
+      cmd: "node index.js",
+      copy: [". ."],
+      run: ["npm ci"],
+      user: "node",
+      workdir: "/app",
+    })).toBe("FROM node:20-alpine\nWORKDIR /app\nUSER node\nRUN npm ci\nCOPY . .\nCMD node index.js\n");
+  });
+
+  test("a stage that mixes steps with per-kind fields is an error", () => {
+    expect(() => dockerfile({ from: "alpine:3.20", run: ["true"], steps: [{ user: "nobody" }] }))
+      .toThrow(/Dockerfile\.app: steps can't be combined with the per-kind fields \(run\)/);
+    expect(() => dockerfile({ stages: [{ from: "alpine:3.20", as: "b", copy: ["a b"], steps: [] }] }))
+      .toThrow(/stage "b": steps can't be combined/);
+  });
+
+  test("a step names exactly one known instruction", () => {
+    expect(() => dockerfile({ from: "alpine:3.20", steps: [{ run: "a", copy: "b" }] })).toThrow(/exactly one instruction, found run, copy/);
+    expect(() => dockerfile({ from: "alpine:3.20", steps: [{}] })).toThrow(/found none/);
+    expect(() => dockerfile({ from: "alpine:3.20", steps: [{ from: "x" }] })).toThrow(/"from" is not a Dockerfile instruction a step can name/);
+    expect(() => dockerfile({ from: "alpine:3.20", steps: [{ copy: ["a", "b"] }] })).toThrow(/COPY takes a string/);
+  });
+
+  test("steps on the Dockerfile itself with stages is an error", () => {
+    expect(() => dockerfile({ stages: [{ from: "alpine:3.20" }], steps: [{ run: "true" }] })).toThrow(/steps belongs on each stage/);
+  });
+
+  test("stages and step lists are plain values that can be shared and spread", () => {
+    const install = [{ copy: "package*.json ./" }, { run: "npm ci" }];
+    const base = { from: "node:20-alpine", as: "deps", steps: [{ workdir: "/app" }, ...install] };
+    expect(dockerfile({ stages: [base, { from: "node:20-alpine", steps: [{ copy: "--from=deps /app/node_modules ./node_modules" }] }] }))
+      .toBe("FROM node:20-alpine AS deps\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci\nFROM node:20-alpine\nCOPY --from=deps /app/node_modules ./node_modules\n");
+  });
+});
+
 // ── Name generation ───────────────────────────────────────────────
 
 describe("dockerSerializer.serialize — name gen", () => {

package/src/serializer.ts

@@ -17,6 +17,7 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import { emitYAMLEntry } from "@intentius/chant/yaml";
+import { EXEC_FORM_STEPS, PER_KIND_ORDER, STEP_INSTRUCTIONS } from "./dockerfile-order";
 
 // ── Helpers ───────────────────────────────────────────────────────
 
@@ -265,36 +266,55 @@ function emitComposeDocument(doc: Record<string, unknown>): string {
 
 // ── Dockerfile serialization ──────────────────────────────────────
 
-function serializeDockerfile(entity: Declarable): string {
+function serializeDockerfile(name: string, entity: Declarable): string {
   const props = getProps(entity);
   const lines: string[] = [];
 
+  // ARGs before the first FROM: global build args a FROM line can use.
+  if (props.globalArgs !== undefined && props.globalArgs !== null) {
+    if (!Array.isArray(props.globalArgs)) {
+      throw new Error(`Dockerfile.${name}: globalArgs must be a list of ARG values, like ["NODE_VERSION=20"]`);
+    }
+    for (const arg of props.globalArgs) lines.push(`ARG ${arg}`);
+  }
+
   // Multi-stage build via stages[]
   if (Array.isArray(props.stages) && props.stages.length > 0) {
-    for (const stage of props.stages as Array<Record<string, unknown>>) {
-      emitStage(stage, lines);
+    if (props.steps !== undefined) {
+      throw new Error(`Dockerfile.${name}: steps belongs on each stage when stages is set, not on the Dockerfile`);
     }
+    (props.stages as Array<Record<string, unknown>>).forEach((stage, i) => {
+      emitStage(stage, lines, `Dockerfile.${name} stage ${stage.as ? `"${stage.as}"` : i + 1}`);
+    });
     return lines.join("\n") + "\n";
   }
 
   // Single-stage build
-  emitStage(props, lines);
+  emitStage(props, lines, `Dockerfile.${name}`);
   return lines.join("\n") + "\n";
 }
 
-function emitStage(stage: Record<string, unknown>, lines: string[]): void {
+function emitStage(stage: Record<string, unknown>, lines: string[], where: string): void {
   // FROM must be first
   if (stage.from) {
     const as = stage.as ? ` AS ${stage.as}` : "";
     lines.push(`FROM ${stage.from}${as}`);
   }
 
-  const INSTRUCTION_ORDER = [
-    "arg", "env", "workdir", "user", "run", "copy", "add",
-    "expose", "volume", "label", "entrypoint", "cmd", "healthcheck",
-  ];
+  if (stage.steps !== undefined && stage.steps !== null) {
+    const perKind = PER_KIND_ORDER.filter((k) => stage[k] !== undefined && stage[k] !== null);
+    if (perKind.length > 0) {
+      throw new Error(
+        `${where}: steps can't be combined with the per-kind fields (${perKind.join(", ")}). Move them into steps, in the order they should run.`,
+      );
+    }
+    if (!Array.isArray(stage.steps)) throw new Error(`${where}: steps must be a list`);
+    stage.steps.forEach((step, i) => lines.push(emitStep(step, `${where} step ${i + 1}`)));
+    return;
+  }
 
-  for (const instr of INSTRUCTION_ORDER) {
+  // No steps: the per-kind fields, in the fixed order they have always had.
+  for (const instr of PER_KIND_ORDER) {
     const value = stage[instr];
     if (value === undefined || value === null) continue;
 
@@ -310,6 +330,33 @@ function emitStage(stage: Record<string, unknown>, lines: string[]): void {
   }
 }
 
+/** One step, `{ run: "npm ci" }`, as its Dockerfile line, `RUN npm ci`. */
+function emitStep(step: unknown, where: string): string {
+  if (typeof step !== "object" || step === null || Array.isArray(step)) {
+    throw new Error(`${where}: a step is an object naming one instruction, like { run: "npm ci" }`);
+  }
+  const keys = Object.keys(step).filter((k) => (step as Record<string, unknown>)[k] !== undefined);
+  if (keys.length !== 1) {
+    throw new Error(
+      `${where}: a step names exactly one instruction, found ${keys.length === 0 ? "none" : keys.join(", ")}. Split it into one step per instruction.`,
+    );
+  }
+  const key = keys[0]!;
+  if (!STEP_INSTRUCTIONS.has(key)) {
+    throw new Error(`${where}: "${key}" is not a Dockerfile instruction a step can name (FROM is the stage's from field)`);
+  }
+  const value = (step as Record<string, unknown>)[key];
+  const keyword = key.toUpperCase();
+  if (Array.isArray(value)) {
+    if (!EXEC_FORM_STEPS.has(key)) {
+      throw new Error(`${where}: ${keyword} takes a string; only RUN, CMD, ENTRYPOINT and SHELL take an exec-form array`);
+    }
+    return `${keyword} ${JSON.stringify(value.map(String))}`;
+  }
+  if (typeof value === "string" || typeof value === "number") return `${keyword} ${value}`;
+  throw new Error(`${where}: ${keyword} needs a string value`);
+}
+
 // ── Serializer ────────────────────────────────────────────────────
 
 export const dockerSerializer: Serializer = {
@@ -376,7 +423,7 @@ export const dockerSerializer: Serializer = {
 
     const files: Record<string, string> = {};
     for (const [name, entity] of dockerfiles) {
-      files[`Dockerfile.${name}`] = serializeDockerfile(entity);
+      files[`Dockerfile.${name}`] = serializeDockerfile(name, entity);
     }
 
     return { primary: composeYaml, files };

package/src/skills/chant-docker-patterns.md

@@ -53,55 +53,124 @@ export const nginx = new Service({
 
 ## Multi-stage Node.js Dockerfile
 
+Manifests before source so the install layer is cached; the runtime stage takes only what it needs and runs as `node`.
+
 ```typescript
 export const nodeApp = new Dockerfile({
   stages: [
     {
       from: "node:20-alpine",
       as: "deps",
-      workdir: "/app",
-      copy: ["package*.json ./"],
-      run: ["npm ci --only=production"],
+      steps: [
+        { workdir: "/app" },
+        { copy: "package.json package-lock.json ./" },
+        { run: "npm ci --omit=dev" },
+      ],
     },
     {
       from: "node:20-alpine",
       as: "build",
-      workdir: "/app",
-      copy: ["--from=deps /app/node_modules ./node_modules", ". ."],
-      run: ["npm run build"],
+      steps: [
+        { workdir: "/app" },
+        { copy: "package.json package-lock.json ./" },
+        { run: "npm ci" },
+        { copy: ". ." },
+        { run: "npm run build" },
+      ],
     },
     {
       from: "node:20-alpine",
-      workdir: "/app",
-      copy: [
-        "--from=deps /app/node_modules ./node_modules",
-        "--from=build /app/dist ./dist",
+      steps: [
+        { workdir: "/app" },
+        { copy: "--from=deps /app/node_modules ./node_modules" },
+        { copy: "--from=build /app/dist ./dist" },
+        { user: "node" },
+        { expose: 3000 },
+        { cmd: ["node", "dist/index.js"] },
       ],
-      user: "node",
-      expose: ["3000"],
-      cmd: `["node", "dist/index.js"]`,
     },
   ],
 });
 ```
 
-## Python service with virtualenv
+## Python service
 
 ```typescript
 export const pythonApp = new Dockerfile({
   from: "python:3.12-slim",
-  workdir: "/app",
-  env: ["PYTHONUNBUFFERED=1", "PYTHONDONTWRITEBYTECODE=1"],
-  copy: ["requirements.txt ."],
-  run: [
-    "pip install --no-cache-dir --no-deps -r requirements.txt",
+  steps: [
+    { workdir: "/app" },
+    { env: "PYTHONUNBUFFERED=1" },
+    { env: "PYTHONDONTWRITEBYTECODE=1" },
+    { copy: "requirements.txt ." },
+    { run: "pip install --no-cache-dir -r requirements.txt" },
+    { copy: ". ." },
+    { user: "1000:1000" },
+    { cmd: ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] },
   ],
-  copy: [". ."],
-  user: "1000:1000",
-  cmd: `["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]`,
 });
 ```
 
+## Root setup, then USER
+
+```typescript
+export const tool = new Dockerfile({
+  from: "debian:12-slim",
+  steps: [
+    { run: "apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*" },
+    { run: "useradd --system --create-home app" },
+    { workdir: "/home/app" },
+    { copy: "--chown=app:app bin/ ./bin/" },
+    { user: "app" },
+    { entrypoint: ["./bin/tool"] },
+  ],
+});
+```
+
+## Sharing stages and steps across modules
+
+Export `const` stages and step lists from one module and import them into each Dockerfile. This is the chant answer to `INCLUDE`.
+
+```typescript
+// src/shared/node.ts
+import type { DockerfileStage, DockerfileStep } from "@intentius/chant-lexicon-docker";
+
+export const nodeBuild: DockerfileStage = {
+  from: "node:20-alpine",
+  as: "build",
+  steps: [
+    { workdir: "/app" },
+    { copy: "package.json package-lock.json ./" },
+    { run: "npm ci" },
+    { copy: ". ." },
+    { run: "npm run build" },
+    { run: "npm prune --omit=dev" },
+  ],
+};
+
+export const nodeRuntime: DockerfileStep[] = [
+  { workdir: "/app" },
+  { copy: "--from=build /app/node_modules ./node_modules" },
+  { copy: "--from=build /app/dist ./dist" },
+  { user: "node" },
+];
+```
+
+```typescript
+// src/web.ts
+import { Dockerfile, type DockerfileStage } from "@intentius/chant-lexicon-docker";
+import { nodeBuild, nodeRuntime } from "./shared/node";
+
+const runtime: DockerfileStage = {
+  from: "node:20-alpine",
+  steps: [...nodeRuntime, { expose: 3000 }, { cmd: ["node", "dist/server.js"] }],
+};
+
+export const web = new Dockerfile({ stages: [nodeBuild, runtime] });
+```
+
+For a shared Dockerfile that takes parameters, write a `Composite((props) => ({ image: new Dockerfile({...}) }))`; spreads are allowed inside it. The `dockerfile-sharing` example in the lexicon has all three patterns.
+
 ## Network isolation
 
 ```typescript