@intentius/chant-lexicon-docker 0.124.20 → 0.124.22

package/src/codegen/__snapshots__/okf.test.ts.snap

@@ -23,8 +23,17 @@ okf_version: '0.2'
 * [DKRD003](/rules/DKRD003.md) - Service exposes SSH port (22) externally — this is a security risk
 * [DKRD010](/rules/DKRD010.md) - apt-get install without --no-install-recommends adds unnecessary packages
 * [DKRD011](/rules/DKRD011.md) - Prefer COPY over ADD when not fetching URLs or extracting archives
-* [DKRD012](/rules/DKRD012.md) - Dockerfile has no USER instruction — container runs as root
+* [DKRD012](/rules/DKRD012.md) - Dockerfile's final stage has no USER instruction, or ends on USER root — container runs as root
+* [DKRD013](/rules/DKRD013.md) - Whole build context copied before a dependency install — every source change re-runs the install
+* [DKRD014](/rules/DKRD014.md) - RUN needs root but comes after USER switched to a non-root user
+* [DKRD015](/rules/DKRD015.md) - More than one CMD or ENTRYPOINT in a stage — only the last one takes effect
+* [DKRD016](/rules/DKRD016.md) - COPY --from names a stage that is not defined before it
+* [DKRD017](/rules/DKRD017.md) - ARG before the first FROM is not used by any FROM or stage
+* [DKRD018](/rules/DKRD018.md) - Relative WORKDIR before any absolute WORKDIR in the stage
+* [DKRD019](/rules/DKRD019.md) - ADD fetches a remote URL without --checksum
+* [DKRD020](/rules/DKRD020.md) - apt-get update in a different RUN from apt-get install — the install can use a stale package index
 * [DKRS001](/rules/DKRS001.md) - No Latest Tag
+* [DKRS002](/rules/DKRS002.md) - Per-kind Dockerfile fields written in a different order
 ",
     "path": "index.md",
   },
@@ -119,14 +128,14 @@ Prefer COPY over ADD when not fetching URLs or extracting archives
     "content": "---
 type: post-synth-check
 title: 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
 id: DKRD012
 severity: error
 category: post-synth
 lexicon: docker
 docs: https://intentius.io/chant/lexicons/docker/rules/
 ---
-Dockerfile has no USER instruction — container runs as root
+Dockerfile's final stage has no USER instruction, or ends on USER root — container runs as root
 
 ## Applies to
 
@@ -136,6 +145,126 @@ Dockerfile has no USER instruction — container runs as root
   },
   {
     "content": "---
+type: post-synth-check
+title: DKRD013
+description: Whole build context copied before a dependency install — every source change re-runs the install
+id: DKRD013
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+Whole build context copied before a dependency install — every source change re-runs the install
+",
+    "path": "rules/DKRD013.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD014
+description: RUN needs root but comes after USER switched to a non-root user
+id: DKRD014
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+RUN needs root but comes after USER switched to a non-root user
+",
+    "path": "rules/DKRD014.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD015
+description: More than one CMD or ENTRYPOINT in a stage — only the last one takes effect
+id: DKRD015
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+More than one CMD or ENTRYPOINT in a stage — only the last one takes effect
+",
+    "path": "rules/DKRD015.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD016
+description: COPY --from names a stage that is not defined before it
+id: DKRD016
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+COPY --from names a stage that is not defined before it
+",
+    "path": "rules/DKRD016.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD017
+description: ARG before the first FROM is not used by any FROM or stage
+id: DKRD017
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+ARG before the first FROM is not used by any FROM or stage
+",
+    "path": "rules/DKRD017.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD018
+description: Relative WORKDIR before any absolute WORKDIR in the stage
+id: DKRD018
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+Relative WORKDIR before any absolute WORKDIR in the stage
+",
+    "path": "rules/DKRD018.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD019
+description: ADD fetches a remote URL without --checksum
+id: DKRD019
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+ADD fetches a remote URL without --checksum
+",
+    "path": "rules/DKRD019.md",
+  },
+  {
+    "content": "---
+type: post-synth-check
+title: DKRD020
+description: apt-get update in a different RUN from apt-get install — the install can use a stale package index
+id: DKRD020
+severity: error
+category: post-synth
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+apt-get update in a different RUN from apt-get install — the install can use a stale package index
+",
+    "path": "rules/DKRD020.md",
+  },
+  {
+    "content": "---
 type: lint-rule
 title: DKRS001
 description: No Latest Tag
@@ -155,6 +284,25 @@ No Latest Tag
   },
   {
     "content": "---
+type: lint-rule
+title: DKRS002
+description: Per-kind Dockerfile fields written in a different order
+id: DKRS002
+severity: warning
+category: correctness
+lexicon: docker
+docs: https://intentius.io/chant/lexicons/docker/rules/
+---
+Per-kind Dockerfile fields written in a different order
+
+## Applies to
+
+- [Dockerfile](/types/Dockerfile.md)
+",
+    "path": "rules/DKRS002.md",
+  },
+  {
+    "content": "---
 type: resource-type
 title: DockerConfig
 description: A config definition in Docker Compose
@@ -201,10 +349,13 @@ A Dockerfile definition with ordered build instructions
 - \`entrypoint\`: Set the entrypoint executable
 - \`cmd\`: Default command arguments
 - \`healthcheck\`: Health check instruction
+- \`globalArgs\`: ARG instructions written before the first FROM
+- \`steps\`: Instructions after FROM, written in the order given; one instruction per step
 
 ## Governed by
 
-- [DKRD012](/rules/DKRD012.md): Dockerfile has no USER instruction — container runs as root
+- [DKRD012](/rules/DKRD012.md): Dockerfile's final stage has no USER instruction, or ends on USER root — container runs as root
+- [DKRS002](/rules/DKRS002.md): Per-kind Dockerfile fields written in a different order
 ",
     "path": "types/Dockerfile.md",
   },

package/src/codegen/docs.ts

@@ -133,6 +133,19 @@ chant build src --lexicon docker -o docker-compose.yml
 chant build src --lexicon aws -o template.json
 \`\`\``;
 
+// "Optional: hand this page to your coding agent", shown under the overview's
+// title. The Dockerfile shape is the ordered \`steps\` list from chant #3926.
+const prompt = `Read https://intentius.io/chant/lexicons/docker/ and https://intentius.io/chant/lexicons/docker/dockerfiles/ first.
+Bring this project's Docker files into chant TypeScript under src/.
+Import each existing file. \`-o\` names a directory, and each import writes main.ts in it: \`chant import --lexicon docker docker-compose.yml -o src/compose/\`, and \`chant import --lexicon docker Dockerfile -o src/<name>/\` for each Dockerfile.
+An imported Dockerfile is exported as \`app\`. Rename each export after its image, since the export name sets the output file (Dockerfile.<export>), and point the Compose service's \`build.dockerfile\` at that export (\`dockerfile: webImage\`) instead of the old file name.
+Write every Dockerfile stage as an ordered \`steps\` list, one instruction per step, with FROM as the stage's \`from\` and ARGs before the first FROM in \`globalArgs\`:
+  steps: [{ workdir: "/app" }, { copy: "package*.json ./" }, { run: "npm ci" }, { copy: ". ." }, { user: "node" }, { cmd: ["node", "dist/index.js"] }]
+Where two Dockerfiles repeat a stage or a run of steps, export it once as a const (a \`DockerfileStage\` or a \`DockerfileStep[]\`) from its own module and import it in both. Spread imported consts, not function results; a Dockerfile that needs parameters is a \`Composite\`.
+Run \`chant build src --lexicon docker -o build/docker-compose.yml\` (Dockerfiles are written beside it) and compare with the original files, then \`chant lint src\`. Run \`chant lint src --fix\` for DKRS002 (per-kind fields to \`steps\`, then reorder the steps it writes), fix every other finding by hand, and repeat until lint is clean.
+Report the generated docker-compose.yml and each Dockerfile.<name>, and any finding you left and why.
+Never push an image, run \`docker compose up\` against anything but the local Docker daemon, or change files outside this project.`;
+
 export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
   const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
@@ -145,6 +158,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
     basePath: "/chant/lexicons/docker/",
     overview,
     outputFormat,
+    prompt,
   };
 
   const result = docsPipeline(config);

package/src/codegen/generate.ts

@@ -10,8 +10,9 @@ import { join } from "path";
 import { generateComposePipeline } from "./generate-compose";
 import { generateDockerfilePipeline } from "./generate-dockerfile";
 import { entityTypeToTsName } from "./naming";
+import { PER_KIND_ORDER } from "../dockerfile-order";
 import type { ComposeParseResult } from "../spec/parse-compose";
-import type { DockerfileParseResult } from "../spec/parse-engine";
+import type { DockerfileParseResult, DockerfileInstruction } from "../spec/parse-engine";
 
 export interface DockerGenerateResult {
   resources: number;
@@ -72,9 +73,13 @@ function generateLexiconJSON(compose: ComposeParseResult[], dockerfile: Dockerfi
     resourceType: dockerfile.typeName,
     kind: "resource",
     description: dockerfile.description ?? "",
-    properties: Object.fromEntries(
-      dockerfile.instructions.map((i) => [i.name, { description: i.description ?? "" }]),
-    ),
+    properties: {
+      ...Object.fromEntries(
+        dockerfile.instructions.filter((i) => !i.stepOnly).map((i) => [i.name, { description: i.description ?? "" }]),
+      ),
+      globalArgs: { description: "ARG instructions written before the first FROM" },
+      steps: { description: "Instructions after FROM, written in the order given; one instruction per step" },
+    },
   };
 
   return JSON.stringify(entries, null, 2);
@@ -100,21 +105,7 @@ function generateTypesDTS(compose: ComposeParseResult[], dockerfile: DockerfileP
   }
 
   const dfName = entityTypeToTsName(dockerfile.typeName);
-  lines.push(`export interface DockerfileStage {`);
-  lines.push(`  from: string;`);
-  lines.push(`  as?: string;`);
-  for (const i of dockerfile.instructions.filter((i) => i.name !== "from")) {
-    lines.push(`  ${i.name}?: ${i.multi ? "string[]" : "string"};`);
-  }
-  lines.push(`}`);
-  lines.push(`export interface DockerfileProps {`);
-  lines.push(`  name?: string;`);
-  lines.push(`  from?: string;`);
-  lines.push(`  stages?: DockerfileStage[];`);
-  for (const i of dockerfile.instructions.filter((i) => i.name !== "from")) {
-    lines.push(`  ${i.name}?: ${i.multi ? "string[]" : "string"};`);
-  }
-  lines.push(`}`);
+  lines.push(...dockerfileTypeLines(dockerfile));
   lines.push(`export declare const ${dfName}: new (props?: DockerfileProps) => Declarable;`);
   lines.push("");
 
@@ -137,10 +128,77 @@ function generateIndexTS(compose: ComposeParseResult[], dockerfile: DockerfilePa
   const dfName = entityTypeToTsName(dockerfile.typeName);
   lines.push(`export const ${dfName} = createResource("${dockerfile.typeName}", "docker", {});`);
   lines.push("");
+  // The Dockerfile prop types are exported from here too (not only from
+  // index.d.ts, which index.ts shadows) so a module can type a shared stage
+  // or step list: `export const install: DockerfileStep[] = [...]`.
+  lines.push(...dockerfileTypeLines(dockerfile));
+  lines.push("");
 
   return lines.join("\n");
 }
 
+/**
+ * The Dockerfile prop types: one `DockerfileStep` variant per instruction,
+ * the stage, and the props. The per-kind fields keep the instructions they
+ * always had; SHELL, STOPSIGNAL and ONBUILD are steps only.
+ */
+function dockerfileTypeLines(dockerfile: DockerfileParseResult): string[] {
+  const lines: string[] = [];
+  const stepInstructions = dockerfile.instructions.filter((i) => i.name !== "from");
+  const perKind = stepInstructions.filter((i) => !i.stepOnly);
+  const stepValue = (i: DockerfileInstruction): string =>
+    ["string", ...(i.numeric ? ["number"] : []), ...(i.execForm ? ["string[]"] : [])].join(" | ");
+  const fixed = PER_KIND_ORDER.map((k) => k.toUpperCase()).join(", ");
+
+  lines.push(`/** The Dockerfile instructions a step can name. FROM is the stage's own \`from\` field. */`);
+  lines.push(`export type DockerfileInstructionName = ${stepInstructions.map((i) => JSON.stringify(i.name)).join(" | ")};`);
+  lines.push(`type DockerfileStepOf<K extends DockerfileInstructionName, V> = { [P in K]: V } & { [P in Exclude<DockerfileInstructionName, K>]?: never };`);
+  lines.push(`/**`);
+  lines.push(` * One Dockerfile instruction, named by its single key: \`{ run: "npm ci" }\` is \`RUN npm ci\`.`);
+  lines.push(` * A string[] value (run, cmd, entrypoint, shell) is written in JSON exec form.`);
+  lines.push(` */`);
+  lines.push(`export type DockerfileStep =`);
+  for (const i of stepInstructions) {
+    lines.push(`  /** ${i.name.toUpperCase()}: ${i.description ?? ""} */`);
+    lines.push(`  | DockerfileStepOf<${JSON.stringify(i.name)}, ${stepValue(i)}>`);
+  }
+  lines[lines.length - 1] += ";";
+
+  const fields = (): void => {
+    lines.push(`  /** Instructions after FROM, written exactly in this order. Can't be combined with the per-kind fields. */`);
+    lines.push(`  steps?: DockerfileStep[];`);
+    for (const i of perKind) {
+      lines.push(`  /** ${i.name.toUpperCase()} as a per-kind field, written in the fixed order. Use \`steps\` to choose the order. */`);
+      lines.push(`  ${i.name}?: ${i.multi ? "string[]" : "string"};`);
+    }
+  };
+  const fixedDoc = ` * Without \`steps\`, the per-kind fields are written in a fixed order: ${fixed}.`;
+
+  lines.push(`/**`);
+  lines.push(` * One build stage: FROM, then its instructions.`);
+  lines.push(fixedDoc);
+  lines.push(` */`);
+  lines.push(`export interface DockerfileStage {`);
+  lines.push(`  from: string;`);
+  lines.push(`  as?: string;`);
+  fields();
+  lines.push(`}`);
+  lines.push(`/**`);
+  lines.push(` * A Dockerfile: \`stages\` for a multi-stage build, or \`from\` and the stage fields for one stage.`);
+  lines.push(fixedDoc);
+  lines.push(` */`);
+  lines.push(`export interface DockerfileProps {`);
+  lines.push(`  name?: string;`);
+  lines.push(`  /** ARG instructions written before the first FROM, e.g. \`["NODE_VERSION=20"]\`. */`);
+  lines.push(`  globalArgs?: string[];`);
+  lines.push(`  from?: string;`);
+  lines.push(`  as?: string;`);
+  lines.push(`  stages?: DockerfileStage[];`);
+  fields();
+  lines.push(`}`);
+  return lines;
+}
+
 /**
  * Write generated artifacts to disk under baseDir/src/generated/.
  */

package/src/dockerfile-order.ts

@@ -0,0 +1,20 @@
+/**
+ * The order a Dockerfile stage's per-kind fields (`run`, `copy`, `user`, ...)
+ * are written in when the stage has no `steps`. It never changes, so a
+ * Dockerfile declared with per-kind fields builds the same output it always
+ * has; `steps` is how a stage controls its own order.
+ */
+export const PER_KIND_ORDER = [
+  "arg", "env", "workdir", "user", "run", "copy", "add",
+  "expose", "volume", "label", "entrypoint", "cmd", "healthcheck",
+] as const;
+
+export type PerKindField = (typeof PER_KIND_ORDER)[number];
+
+/** The step keys whose array value is written in JSON exec form. */
+export const EXEC_FORM_STEPS: ReadonlySet<string> = new Set(["run", "cmd", "entrypoint", "shell"]);
+
+/** Every instruction a step can name. FROM is the stage's own field. */
+export const STEP_INSTRUCTIONS: ReadonlySet<string> = new Set([
+  ...PER_KIND_ORDER, "shell", "stopsignal", "onbuild",
+]);

package/src/docs-examples.test.ts

@@ -0,0 +1,141 @@
+/**
+ * The Dockerfile examples in the docs and skills build, and build what the
+ * page says they do.
+ *
+ * - A ```typescript block with no title that declares a Dockerfile is run
+ *   and serialized. When the next code block is an untitled ```dockerfile
+ *   block, the built file must equal it.
+ * - A titled ```typescript block (`title="src/web.ts"`) must equal that file
+ *   in examples/dockerfile-sharing, and a titled ```dockerfile block
+ *   (`title="Dockerfile.web"`) must equal that file from building the
+ *   example.
+ * - In importing.mdx, importing the ```dockerfile block titled "Dockerfile"
+ *   must give the ```typescript block that follows it.
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+import { build } from "@intentius/chant/build";
+import * as chant from "@intentius/chant";
+import type { Declarable } from "@intentius/chant/declarable";
+import * as lexicon from "./index";
+import { dockerSerializer } from "./serializer";
+import { DockerTemplateGenerator, DockerTemplateParser } from "./import/adapter";
+
+const root = join(import.meta.dirname, "..");
+const sharingExample = join(root, "examples", "dockerfile-sharing");
+
+interface Block {
+  lang: string;
+  title?: string;
+  code: string;
+  /** The prose between the previous code block and this one. */
+  before: string;
+}
+
+function blocks(file: string): Block[] {
+  const text = readFileSync(join(root, file), "utf8");
+  const out: Block[] = [];
+  let last = 0;
+  for (const m of text.matchAll(/^```(\w+)([^\n]*)\n([\s\S]*?)^```$/gm)) {
+    const title = m[2]!.match(/title="([^"]+)"/)?.[1];
+    out.push({ lang: m[1]!, ...(title ? { title } : {}), code: m[3]!, before: text.slice(last, m.index) });
+    last = m.index! + m[0].length;
+  }
+  return out;
+}
+
+/**
+ * Run one TypeScript block as a module and serialize the Dockerfiles it
+ * exports. A block whose first line is a path comment (`// src/web.ts`) is
+ * one module of a multi-file example: `modules` holds the exports of the
+ * page's earlier modules, by path, for its relative imports.
+ */
+function buildBlock(code: string, pageModules: Map<string, Record<string, unknown>> = new Map()): Record<string, string> {
+  const js = ts.transpileModule(code, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 } }).outputText;
+  const modules: Record<string, unknown> = { "@intentius/chant-lexicon-docker": lexicon, "@intentius/chant": chant };
+  const path = code.match(/^\/\/ (src\/\S+)\.ts\s*$/m)?.[1];
+  const req = (name: string): unknown => {
+    if (name.startsWith("./") && path) {
+      const target = join(path, "..", name).replace(/\\/g, "/");
+      const found = pageModules.get(target);
+      if (found) return found;
+    }
+    if (!(name in modules)) throw new Error(`docs example imports ${name}, which this test does not provide`);
+    return modules[name];
+  };
+  const mod = { exports: {} as Record<string, unknown> };
+  // Snippets that leave out the import line still see the lexicon's exports.
+  const globals = Object.keys(lexicon).filter((k) => /^[A-Za-z_$][\w$]*$/.test(k));
+  new Function("require", "module", "exports", ...globals, js)(req, mod, mod.exports, ...globals.map((k) => (lexicon as Record<string, unknown>)[k]));
+  if (path) pageModules.set(path, mod.exports);
+  const entities = new Map<string, Declarable>();
+  for (const [name, value] of Object.entries(mod.exports)) {
+    if (value && typeof value === "object" && "entityType" in value) entities.set(name, value as Declarable);
+  }
+  const result = dockerSerializer.serialize(entities);
+  return typeof result === "string" ? {} : (result.files ?? {});
+}
+
+const PAGES = [
+  "docs/pages/dockerfiles.mdx",
+  "docs/pages/examples.mdx",
+  "docs/pages/lint-rules.mdx",
+  "src/skills/chant-docker.md",
+  "src/skills/chant-docker-patterns.md",
+];
+
+describe("docs Dockerfile examples", () => {
+  for (const page of PAGES) {
+    test(`${page}: every Dockerfile example builds what the page shows`, () => {
+      const list = blocks(page);
+      const pageModules = new Map<string, Record<string, unknown>>();
+      let checked = 0;
+      list.forEach((b, i) => {
+        if (b.lang !== "typescript" || b.title) return;
+        const isModule = /^\/\/ src\/\S+\.ts\s*$/m.test(b.code);
+        if (!b.code.includes("new Dockerfile(") && !isModule) return;
+        const files = buildBlock(b.code, pageModules);
+        if (!b.code.includes("new Dockerfile(")) return;
+        expect(Object.keys(files).length, `${page} block ${i + 1} declares a Dockerfile`).toBeGreaterThan(0);
+        checked++;
+        // The output shown right after it, under a "`Dockerfile.name`:" line.
+        const next = list[i + 1];
+        if (next && next.lang === "dockerfile" && !next.title && /^\s*`Dockerfile\.\w+`:\s*$/.test(next.before)) {
+          expect(Object.values(files).join("---\n"), `${page} block ${i + 1}`).toBe(next.code);
+        }
+      });
+      expect(checked, `${page} has Dockerfile examples`).toBeGreaterThan(0);
+    });
+  }
+
+  test("dockerfiles.mdx sharing section matches the dockerfile-sharing example and its build", async () => {
+    const titled = blocks("docs/pages/dockerfiles.mdx").filter((b) => b.title);
+    const sources = titled.filter((b) => b.lang === "typescript");
+    const outputs = titled.filter((b) => b.lang === "dockerfile");
+    expect(sources.map((b) => b.title)).toEqual(["src/shared/node.ts", "src/web.ts", "src/worker.ts", "src/shared/node-image.ts", "src/api.ts"]);
+    for (const b of sources) {
+      expect(b.code, b.title).toBe(readFileSync(join(sharingExample, b.title!), "utf8"));
+    }
+
+    const result = await build(join(sharingExample, "src"), [dockerSerializer]);
+    expect(result.errors).toEqual([]);
+    const files = (result.outputs.get("docker") as unknown as { files: Record<string, string> }).files;
+    expect(outputs.map((b) => b.title).sort()).toEqual(Object.keys(files).sort());
+    for (const b of outputs) {
+      expect(b.code, b.title).toBe(files[b.title!]);
+    }
+  });
+
+  test("importing.mdx shows what importing its Dockerfile produces", () => {
+    const list = blocks("docs/pages/importing.mdx");
+    const at = list.findIndex((b) => b.lang === "dockerfile" && b.title === "Dockerfile");
+    expect(at).toBeGreaterThan(-1);
+    const [file] = new DockerTemplateGenerator().generate(new DockerTemplateParser().parse(list[at]!.code));
+    expect(list[at + 1]!.code).toBe(file!.content.endsWith("\n") ? file!.content : `${file!.content}\n`);
+    // And building the import gives the Dockerfile back.
+    expect(Object.values(buildBlock(list[at + 1]!.code))[0]).toBe(list[at]!.code.replace(/^#.*\n/gm, ""));
+  });
+});

package/src/generated/index.d.ts

@@ -56,39 +56,120 @@ export interface DockerSecretProps {
 }
 export declare const DockerSecret: new (props?: DockerSecretProps) => Declarable;
 
+/** 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;
 }
 export declare const Dockerfile: new (props?: DockerfileProps) => Declarable;