@intentius/chant-lexicon-docker 0.124.21 → 0.124.23

package/dist/rules/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/dist/rules/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/dist/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/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAoB,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AA6SlG,eAAO,MAAM,gBAAgB,EAAE,UAqE9B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAoB,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AA4VlG,eAAO,MAAM,gBAAgB,EAAE,UAqE9B,CAAC"}

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

@@ -5,7 +5,7 @@ Common Docker Compose and Dockerfile patterns using `@intentius/chant-lexicon-do
 ## Database service with volume
 
 ```typescript
-import { Service, Volume } from "@intentius/chant-lexicon-docker";
+import { Service, Volume, env } from "@intentius/chant-lexicon-docker";
 
 export const postgres = new Service({
   image: "postgres:16-alpine",
@@ -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
@@ -138,7 +207,7 @@ export const app = new Service({
 ## Environment interpolation patterns
 
 ```typescript
-import { env } from "@intentius/chant-lexicon-docker";
+import { Service, env } from "@intentius/chant-lexicon-docker";
 
 // Dev vs prod toggle:
 export const api = new Service({