@intentius/chant-lexicon-docker 0.124.21 → 0.124.23

package/src/skills/chant-docker.md

@@ -39,15 +39,21 @@ export const nfsdata = new Volume({ driver: "local", driver_opts: { type: "nfs",
 
 ## Dockerfile — generates Dockerfile.{name}:
 
+Each stage is `from` plus `steps`. A step is an object with one key naming one instruction. Steps are written exactly in the order listed.
+
 ```typescript
-// Single-stage:
-export const builder = new Dockerfile({
+// Single stage. Manifests before source, so the install layer is cached; root setup before USER.
+export const server = new Dockerfile({
   from: "node:20-alpine",
-  workdir: "/app",
-  copy: ["package*.json ./"],
-  run: ["npm ci --only=production"],
-  user: "node",
-  cmd: `["node", "dist/index.js"]`,
+  steps: [
+    { workdir: "/app" },
+    { copy: "package.json package-lock.json ./" },
+    { run: "npm ci --omit=dev" },
+    { copy: "src/ ./src/" },
+    { user: "node" },
+    { expose: 3000 },
+    { cmd: ["node", "src/index.js"] },  // a list is written in JSON exec form
+  ],
 });
 
 // Multi-stage build:
@@ -56,21 +62,37 @@ export const app = new Dockerfile({
     {
       from: "node:20-alpine",
       as: "build",
-      workdir: "/app",
-      copy: ["package*.json ./"],
-      run: ["npm ci", "npm run build"],
+      steps: [
+        { workdir: "/app" },
+        { copy: "package.json package-lock.json ./" },
+        { run: "npm ci" },
+        { copy: ". ." },
+        { run: "npm run build" },
+        { run: "npm prune --omit=dev" },
+      ],
     },
     {
       from: "node:20-alpine",
-      workdir: "/app",
-      copy: ["--from=build /app/dist ./dist", "--from=build /app/node_modules ./node_modules"],
-      user: "node",
-      cmd: `["node", "dist/index.js"]`,
+      steps: [
+        { workdir: "/app" },
+        { copy: "--from=build /app/node_modules ./node_modules" },
+        { copy: "--from=build /app/dist ./dist" },
+        { user: "node" },
+        { cmd: ["node", "dist/index.js"] },
+      ],
     },
   ],
 });
 ```
 
+Step keys: `arg`, `env`, `workdir`, `user`, `run`, `copy`, `add`, `expose`, `volume`, `label`, `entrypoint`, `cmd`, `healthcheck`, `shell`, `stopsignal`, `onbuild`. `from` and `as` are stage fields, and `globalArgs: ["NAME=value"]` writes `ARG` lines before the first `FROM`. `run`, `cmd`, `entrypoint` and `shell` take a string or a list (exec form); `expose` takes a number too.
+
+Rules:
+- Use `steps`. The older per-kind fields (`run: [...]`, `copy: [...]`, `user`) are written in a fixed order (ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK), not the order written, so every RUN lands before every COPY. Lint rule DKRS002 flags this, and `chant lint --fix` rewrites them as steps.
+- A stage can't have both `steps` and per-kind fields, and a step can't name two instructions. Both are build errors.
+- Props are type-checked: `Dockerfile` takes `DockerfileProps` and the Compose constructors take `ServiceProps`, `VolumeProps`, `NetworkProps`, `DockerConfigProps` and `DockerSecretProps`. A misspelled key or a wrong value type is a TypeScript error, so run `tsc` (or read the editor's errors) before `chant build`.
+- To share stages or steps between Dockerfiles in different modules, export a `const` stage (`DockerfileStage`) or step list (`DockerfileStep[]`) and import it. List the stage in `stages`, or spread the steps: `steps: [...nodeRuntime, { cmd: ["node", "dist/server.js"] }]`. This is chant's equivalent of an INCLUDE. Spreading a function call's result is a lint error (EVL004); put parameterized Dockerfiles in a `Composite`.
+
 ## Variable interpolation with env():
 
 ```typescript
@@ -112,7 +134,10 @@ export const api = new Service({
   },
   ports: ["8080:8080"],
 });
-export const builder = new Dockerfile({ from: "node:20-alpine", ... });
+export const builder = new Dockerfile({
+  from: "node:20-alpine",
+  steps: [{ workdir: "/app" }, { copy: ". ." }, { run: "npm ci" }, { user: "node" }, { cmd: ["node", "index.js"] }],
+});
 ```
 
 ## Output structure
@@ -126,4 +151,6 @@ export const builder = new Dockerfile({ from: "node:20-alpine", ... });
 - `DKRD001`: Post-synth: no `:latest` images in generated YAML
 - `DKRD002`: Post-synth: no unused named volumes
 - `DKRD003`: Post-synth: SSH port 22 not exposed externally
-- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, USER)
+- `DKRS002`: Dockerfile per-kind fields declared in an order the fixed order changes; use `steps`
+- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, final stage USER)
+- `DKRD013–020`: order-aware Dockerfile checks: COPY . before a dependency install, root-only RUN after USER, repeated CMD/ENTRYPOINT, COPY --from an undefined stage, unused ARG before FROM, relative WORKDIR, ADD of a URL without --checksum, apt-get update in its own RUN

package/src/spec/parse-compose.ts

@@ -22,102 +22,174 @@ export interface ComposeProperty {
   enum?: string[];
 }
 
+/**
+ * The TypeScript type of a Compose string slot. Compose interpolates every
+ * value, so `env()` fits where a string does; an entity (a service, network,
+ * volume, config, secret or Dockerfile) is written as its name.
+ */
+export const COMPOSE_STRING = "ComposeString";
+
+interface JsonSchema {
+  $ref?: string;
+  type?: string | string[];
+  description?: string;
+  enum?: unknown[];
+  const?: unknown;
+  properties?: Record<string, JsonSchema>;
+  patternProperties?: Record<string, JsonSchema>;
+  additionalProperties?: boolean | JsonSchema;
+  required?: string[];
+  items?: JsonSchema;
+  oneOf?: JsonSchema[];
+  anyOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+}
+
+const ENTITIES: Array<{ def: string; shortName: string; description: string }> = [
+  { def: "service", shortName: "Service", description: "A containerized service definition in Docker Compose" },
+  { def: "volume", shortName: "Volume", description: "A named volume definition in Docker Compose" },
+  { def: "network", shortName: "Network", description: "A network definition in Docker Compose" },
+  { def: "config", shortName: "Config", description: "A config definition in Docker Compose" },
+  { def: "secret", shortName: "Secret", description: "A secret definition in Docker Compose" },
+];
+
 /**
  * Parse the Compose Spec JSON Schema buffer into ParsedResult entries.
- * Returns one entry per top-level Compose resource type.
+ * Returns one entry per top-level Compose resource type, with a property for
+ * every field the spec defines on it (#3934). Each property's `type` is a
+ * TypeScript type converted from the schema; string slots use
+ * {@link COMPOSE_STRING}.
  */
-export function parseComposeSpec(_data: Buffer): ComposeParseResult[] {
-  // The Compose spec is complex; we hand-define the five core resource types
-  // and extract key properties from the schema for documentation/type generation.
-  // Full deep parsing happens during codegen; here we return the structural outline.
-
-  return [
-    {
-      typeName: "Docker::Compose::Service",
-      shortName: "Service",
-      description: "A containerized service definition in Docker Compose",
-      isResource: true,
-      properties: [
-        { name: "image", type: "string", description: "Container image to use" },
-        { name: "build", type: "object", description: "Build configuration" },
-        { name: "command", type: "string | string[]", description: "Override the default command" },
-        { name: "entrypoint", type: "string | string[]", description: "Override the default entrypoint" },
-        { name: "environment", type: "Record<string, string>", description: "Environment variables" },
-        { name: "ports", type: "string[]", description: "Published ports" },
-        { name: "volumes", type: "string[]", description: "Volume mounts" },
-        { name: "networks", type: "string[]", description: "Networks to attach" },
-        {
-          name: "depends_on",
-          // Compose `depends_on` is a oneOf: short list-form, or long form with a
-          // wait condition (service_started/healthy/completed_successfully).
-          type: 'string[] | Record<string, { condition: "service_started" | "service_healthy" | "service_completed_successfully"; restart?: boolean; required?: boolean }>',
-          description: "Service dependencies (short list-form, or long form with a wait condition)",
-        },
-        { name: "restart", type: "string", description: "Restart policy" },
-        { name: "labels", type: "Record<string, string>", description: "Container labels" },
-        { name: "healthcheck", type: "object", description: "Health check configuration" },
-        { name: "deploy", type: "object", description: "Swarm deployment configuration" },
-        { name: "secrets", type: "string[]", description: "Secrets to expose" },
-        {
-          name: "configs",
-          // Short form names a top-level config; long form also sets where it
-          // is mounted. `source` may be the DockerConfig entity itself.
-          type: "Array<string | { source: string | Declarable; target?: string; uid?: string; gid?: string; mode?: number }>",
-          description: "Configs to expose (short form, or long form with a mount target)",
-        },
-      ],
-    },
-    {
-      typeName: "Docker::Compose::Volume",
-      shortName: "Volume",
-      description: "A named volume definition in Docker Compose",
-      isResource: true,
-      properties: [
-        { name: "driver", type: "string", description: "Volume driver" },
-        { name: "driver_opts", type: "Record<string, string>", description: "Driver options" },
-        { name: "external", type: "boolean", description: "Whether the volume is external" },
-        { name: "labels", type: "Record<string, string>", description: "Volume labels" },
-        { name: "name", type: "string", description: "Custom volume name" },
-      ],
-    },
-    {
-      typeName: "Docker::Compose::Network",
-      shortName: "Network",
-      description: "A network definition in Docker Compose",
-      isResource: true,
-      properties: [
-        { name: "driver", type: "string", description: "Network driver" },
-        { name: "driver_opts", type: "Record<string, string>", description: "Driver options" },
-        { name: "external", type: "boolean", description: "Whether the network is external" },
-        { name: "labels", type: "Record<string, string>", description: "Network labels" },
-        { name: "internal", type: "boolean", description: "Restrict external access" },
-        { name: "ipam", type: "object", description: "IP address management" },
-      ],
-    },
-    {
-      typeName: "Docker::Compose::Config",
-      shortName: "Config",
-      description: "A config definition in Docker Compose",
-      isResource: true,
-      properties: [
-        { name: "file", type: "string", description: "Path to the config file" },
-        { name: "content", type: "string", description: "Inline config content" },
-        { name: "external", type: "boolean", description: "Whether the config is external" },
-        { name: "labels", type: "Record<string, string>", description: "Config labels" },
-        { name: "name", type: "string", description: "Custom config name" },
-      ],
-    },
-    {
-      typeName: "Docker::Compose::Secret",
-      shortName: "Secret",
-      description: "A secret definition in Docker Compose",
-      isResource: true,
-      properties: [
-        { name: "file", type: "string", description: "Path to the secret file" },
-        { name: "external", type: "boolean", description: "Whether the secret is external" },
-        { name: "labels", type: "Record<string, string>", description: "Secret labels" },
-        { name: "name", type: "string", description: "Custom secret name" },
-      ],
-    },
-  ];
+export function parseComposeSpec(data: Buffer): ComposeParseResult[] {
+  const spec = JSON.parse(data.toString("utf-8")) as { $defs?: Record<string, JsonSchema>; definitions?: Record<string, JsonSchema> };
+  const defs = spec.$defs ?? spec.definitions ?? {};
+
+  return ENTITIES.map(({ def, shortName, description }) => {
+    const schema = defs[def];
+    const required = new Set(schema?.required ?? []);
+    const properties: ComposeProperty[] = Object.entries(schema?.properties ?? {}).map(([name, prop]) => ({
+      name,
+      type: toTsType(prop, defs, new Set([def])),
+      ...(prop.description ? { description: oneLine(prop.description) } : {}),
+      ...(required.has(name) ? { required: true } : {}),
+    }));
+    return { typeName: `Docker::Compose::${shortName}`, shortName, description, isResource: true, properties };
+  });
+}
+
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").replace(/\*\//g, "* /").trim();
+}
+
+/** A property name as a TypeScript key: bare when it is an identifier. */
+function key(name: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+/** Convert one JSON Schema node to a TypeScript type. `seen` guards $ref cycles. */
+export function toTsType(schema: JsonSchema | boolean | undefined, defs: Record<string, JsonSchema>, seen: Set<string> = new Set()): string {
+  if (schema === undefined || schema === true) return "unknown";
+  if (schema === false) return "never";
+
+  if (schema.$ref) {
+    const name = schema.$ref.replace(/^#\/(\$defs|definitions)\//, "");
+    const target = defs[name];
+    if (!target || seen.has(name)) return "unknown";
+    return toTsType(target, defs, new Set([...seen, name]));
+  }
+
+  const alts = schema.oneOf ?? schema.anyOf;
+  if (alts) {
+    // A oneOf beside a type or properties narrows them; the alternatives carry the shape.
+    return union(alts.map((a) => toTsType(a, defs, seen)));
+  }
+  if (schema.allOf) {
+    const parts = schema.allOf.map((a) => toTsType(a, defs, seen)).filter((t) => t !== "unknown");
+    return parts.length ? parts.map(paren).join(" & ") : "unknown";
+  }
+
+  if (schema.const !== undefined) return JSON.stringify(schema.const);
+  if (schema.enum) return union(schema.enum.map((v) => JSON.stringify(v)));
+
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  if (types.length === 0) {
+    if (schema.properties || schema.patternProperties || schema.additionalProperties !== undefined) return objectType(schema, defs, seen);
+    if (schema.items) return `Array<${toTsType(schema.items, defs, seen)}>`;
+    return "unknown";
+  }
+  return union(
+    types.map((t) => {
+      switch (t) {
+        case "string":
+          return COMPOSE_STRING;
+        case "number":
+        case "integer":
+          return "number";
+        case "boolean":
+          return "boolean";
+        case "null":
+          return "null";
+        case "array":
+          return `Array<${schema.items ? toTsType(schema.items, defs, seen) : "unknown"}>`;
+        case "object":
+          return objectType(schema, defs, seen);
+        default:
+          return "unknown";
+      }
+    }),
+  );
+}
+
+function objectType(schema: JsonSchema, defs: Record<string, JsonSchema>, seen: Set<string>): string {
+  const props = Object.entries(schema.properties ?? {});
+  const patterns = Object.entries(schema.patternProperties ?? {});
+  const extensions = patterns.some(([p]) => p === "^x-");
+  const others = patterns.filter(([p]) => p !== "^x-");
+  const additional = schema.additionalProperties;
+
+  if (props.length === 0) {
+    const values = others.map(([, v]) => toTsType(v, defs, seen));
+    if (additional && additional !== true) values.push(toTsType(additional, defs, seen));
+    if (values.length) return `Record<string, ${union(values)}>`;
+    return additional === false && !extensions ? "Record<string, never>" : "Record<string, unknown>";
+  }
+
+  const required = new Set(schema.required ?? []);
+  const fields = props.map(([name, p]) => `${key(name)}${required.has(name) ? "" : "?"}: ${toTsType(p, defs, seen)}`);
+  if (extensions) fields.push("[key: `x-${string}`]: unknown");
+  // Free-form keys beside the named ones: the named ones keep their types.
+  if (others.length || (additional && additional !== true)) fields.push("[key: string]: unknown");
+  return `{ ${fields.join("; ")} }`;
+}
+
+function paren(t: string): string {
+  return /[|&]/.test(t) && !/^[{(]/.test(t) ? `(${t})` : t;
+}
+
+function union(types: string[]): string {
+  const unique = [...new Set(types.flatMap(splitTop))];
+  if (unique.includes("unknown")) return "unknown";
+  return unique.join(" | ");
+}
+
+/** The members of a union type, split only at the top level. */
+function splitTop(type: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let quote = false;
+  let start = 0;
+  for (let i = 0; i < type.length; i++) {
+    const c = type[i];
+    if (c === '"') quote = !quote;
+    if (quote) continue;
+    if (c === "{" || c === "(" || c === "<" || c === "[") depth++;
+    else if (c === "}" || c === ")" || c === ">" || c === "]") depth--;
+    else if (depth === 0 && type.startsWith(" | ", i)) {
+      out.push(type.slice(start, i));
+      start = i + 3;
+      i += 2;
+    }
+  }
+  out.push(type.slice(start));
+  return out;
 }

package/src/spec/parse-engine.ts

@@ -15,7 +15,16 @@ export interface DockerfileParseResult {
 export interface DockerfileInstruction {
   name: string;
   description?: string;
-  multi?: boolean;  // can appear multiple times
+  multi?: boolean;  // can appear multiple times (as a per-kind field, an array)
+  /**
+   * Only available as a step (`{ shell: ... }` in `steps`), not as a per-kind
+   * field. The per-kind fields keep the set and fixed order they always had.
+   */
+  stepOnly?: boolean;
+  /** As a step, the value may be a JSON exec-form array as well as a string. */
+  execForm?: boolean;
+  /** As a step, the value may be a number as well as a string. */
+  numeric?: boolean;
 }
 
 /**
@@ -31,17 +40,20 @@ export function parseEngineApi(_data: Buffer): DockerfileParseResult {
       { name: "from", description: "Base image (required first instruction)" },
       { name: "arg", description: "Build-time argument", multi: true },
       { name: "env", description: "Environment variable", multi: true },
-      { name: "run", description: "Run a command during build", multi: true },
+      { name: "run", description: "Run a command during build", multi: true, execForm: true },
       { name: "copy", description: "Copy files from build context", multi: true },
       { name: "add", description: "Add files (supports URLs and archives)", multi: true },
       { name: "workdir", description: "Set working directory" },
       { name: "user", description: "Set user for subsequent instructions" },
-      { name: "expose", description: "Document exposed ports", multi: true },
+      { name: "expose", description: "Document exposed ports", multi: true, numeric: true },
       { name: "volume", description: "Create mount points", multi: true },
       { name: "label", description: "Add metadata labels", multi: true },
-      { name: "entrypoint", description: "Set the entrypoint executable" },
-      { name: "cmd", description: "Default command arguments" },
+      { name: "entrypoint", description: "Set the entrypoint executable", execForm: true },
+      { name: "cmd", description: "Default command arguments", execForm: true },
       { name: "healthcheck", description: "Health check instruction" },
+      { name: "shell", description: "Set the shell for shell-form commands (JSON array form)", stepOnly: true, execForm: true },
+      { name: "stopsignal", description: "Signal sent to stop the container", stepOnly: true },
+      { name: "onbuild", description: "Instruction to run when the image is used as a base", stepOnly: true },
     ],
   };
 }

package/src/typecheck.e2e.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Docker TypeScript that the repo typecheck can't see type-checks against the
+ * lexicon (#3934): the examples in the docs and skills, and the source
+ * `chant import` writes for the compose fixtures. The constructors take their
+ * props types, so an example with a misspelled field or a wrong value type
+ * fails here rather than in a reader's editor. Compiling them takes longer
+ * than the unit-test budget allows, so this runs with the e2e tests.
+ *
+ * A snippet that leaves out its import line is checked as if it imported the
+ * lexicon names it uses; a titled block or a `// src/x.ts` module block is
+ * placed at that path so the page's relative imports resolve.
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+import * as lexicon from "./index";
+import { DockerParser } from "./import/parser";
+import { DockerGenerator } from "./import/generator";
+
+const root = join(import.meta.dirname, "..");
+const repoRoot = join(root, "..", "..");
+const virtualRoot = join(root, ".typecheck");
+
+interface Block {
+  lang: string;
+  title?: string;
+  code: string;
+}
+
+function blocks(file: string): Block[] {
+  const text = readFileSync(join(root, file), "utf8");
+  return [...text.matchAll(/^```(\w+)([^\n]*)\n([\s\S]*?)^```$/gm)].map((m) => {
+    const title = m[2]!.match(/title="([^"]+)"/)?.[1];
+    return { lang: m[1]!, ...(title ? { title } : {}), code: m[3]! };
+  });
+}
+
+/** Type errors in in-memory files, compiled against the lexicon's source with the repo typecheck's options. */
+function typeErrors(files: Map<string, string>): string[] {
+  const config = ts.readConfigFile(join(repoRoot, "tsconfig.typecheck.json"), ts.sys.readFile);
+  const { options } = ts.parseJsonConfigFileContent(config.config, ts.sys, repoRoot);
+  const checkOptions = { ...options, noEmit: true, types: [], skipLibCheck: true, declaration: false, declarationMap: false, sourceMap: false };
+  const host = ts.createCompilerHost(checkOptions);
+  const getSourceFile = host.getSourceFile.bind(host);
+  host.getSourceFile = (name, lang, ...rest) =>
+    files.has(name) ? ts.createSourceFile(name, files.get(name)!, lang) : getSourceFile(name, lang, ...rest);
+  const fileExists = host.fileExists.bind(host);
+  host.fileExists = (name) => files.has(name) || fileExists(name);
+  const directoryExists = host.directoryExists?.bind(host);
+  host.directoryExists = (dir) => [...files.keys()].some((f) => f.startsWith(`${dir}/`)) || (directoryExists?.(dir) ?? false);
+  const readFile = host.readFile.bind(host);
+  host.readFile = (name) => files.get(name) ?? readFile(name);
+
+  const program = ts.createProgram([...files.keys()], checkOptions, host);
+  // Only the in-memory files are checked; the lexicon itself is the repo typecheck's job.
+  return [...files.keys()]
+    .flatMap((f) => {
+      const sf = program.getSourceFile(f)!;
+      return [...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf)];
+    })
+    .map((d) => {
+      const { line } = d.file!.getLineAndCharacterOfPosition(d.start ?? 0);
+      return `${d.file!.fileName.slice(virtualRoot.length + 1)}:${line + 1}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
+    });
+}
+
+describe("docker TypeScript outside the repo typecheck type-checks", () => {
+  test("every docker example in the docs and skills", () => {
+    const pages = [
+      ...readdirSync(join(root, "docs/pages")).filter((f) => f.endsWith(".mdx")).map((f) => `docs/pages/${f}`),
+      ...readdirSync(join(root, "src/skills")).filter((f) => f.endsWith(".md")).map((f) => `src/skills/${f}`),
+    ];
+    const lexiconNames = Object.keys(lexicon);
+    const typeNames = ["DockerfileProps", "DockerfileStage", "DockerfileStep", "DockerfileInstructionName", "ServiceProps", "VolumeProps", "NetworkProps", "DockerConfigProps", "DockerSecretProps"];
+    const files = new Map<string, string>();
+    for (const page of pages) {
+      blocks(page).forEach((b, i) => {
+        if (b.lang !== "typescript") return;
+        const modulePath = b.title ?? b.code.match(/^\/\/ (src\/\S+\.ts)\s*$/m)?.[1];
+        if (!modulePath && !/@intentius\/chant-lexicon-docker|new (Dockerfile|Service|Volume|Network|DockerConfig|DockerSecret)\(/.test(b.code)) return;
+        // A snippet sits one directory below src/, so `../web/main` and `./shared/node` reach the page's modules.
+        const file = join(virtualRoot, page.replace(/[/.]/g, "_"), modulePath ?? `src/snippets/block-${i + 1}.ts`);
+        let code = b.code;
+        if (!code.includes("@intentius/chant-lexicon-docker")) {
+          const used = [...lexiconNames, ...typeNames].filter((n) => new RegExp(`\\b${n}\\b`).test(code));
+          if (used.length) code = `import { ${used.join(", ")} } from "@intentius/chant-lexicon-docker";\n${code}`;
+        }
+        files.set(file, `${code}\nexport {};\n`);
+      });
+    }
+    expect(files.size).toBeGreaterThan(20);
+    expect(typeErrors(files)).toEqual([]);
+  }, 120_000);
+
+  test("what importing the compose fixtures writes", () => {
+    const testdata = join(root, "src/import/testdata");
+    const files = new Map<string, string>();
+    for (const fixture of readdirSync(testdata).filter((f) => f.endsWith(".yaml"))) {
+      const { source } = new DockerGenerator().generate(new DockerParser().parse(readFileSync(join(testdata, fixture), "utf8")).entities);
+      files.set(join(virtualRoot, "import", `${fixture.replace(/\.yaml$/, "")}.ts`), source);
+    }
+    expect(files.size).toBeGreaterThanOrEqual(4);
+    expect(typeErrors(files)).toEqual([]);
+  }, 120_000);
+});

package/src/typed-props.test.ts

@@ -0,0 +1,60 @@
+/**
+ * The docker constructors take their props types (#3934). The repo typecheck
+ * (scripts/typecheck.ts) compiles this file, so each `@ts-expect-error` below
+ * fails it if the line it marks stops being a type error: a misspelled key or
+ * a wrong-typed field must not compile. The tests themselves only run the
+ * well-typed declarations.
+ */
+
+import { describe, test, expect } from "vitest";
+import { Dockerfile, Service, Volume, Network, DockerConfig, DockerSecret, env } from "./index";
+import type { DockerfileStep } from "./index";
+
+describe("docker props are typed", () => {
+  test("well-typed props construct", () => {
+    const settings = new DockerConfig({ file: "./config/app.conf" });
+    const token = new DockerSecret({ file: "./secrets/token.txt" });
+    const data = new Volume({ driver: "local" });
+    const backend = new Network({ internal: true });
+    const app = new Dockerfile({ from: "node:20-alpine", steps: [{ workdir: "/app" }, { run: "npm ci" }] });
+    const api = new Service({
+      build: { context: ".", dockerfile: app },
+      image: env("API_IMAGE", { default: "api:latest" }),
+      ports: ["8080:8080", { target: 8080, published: "8080" }],
+      configs: [{ source: settings, target: "/etc/app.conf" }],
+      secrets: [token],
+      networks: [backend],
+      volumes: ["data:/var/lib/data"],
+      depends_on: { db: { condition: "service_healthy" } },
+    });
+    for (const entity of [settings, token, data, backend, app, api]) {
+      expect(entity).toHaveProperty("entityType");
+    }
+  });
+
+  test("misspelled keys and wrong-typed fields are type errors", () => {
+    // Only the type checker reads these; they are never constructed.
+    const declare = (): unknown[] => [
+      // @ts-expect-error `rnu` is not a Dockerfile instruction
+      new Dockerfile({ from: "alpine:3.20", steps: [{ rnu: "npm ci" }] }),
+      // @ts-expect-error RUN takes a string
+      new Dockerfile({ from: "alpine:3.20", steps: [{ run: 42 }] }),
+      // @ts-expect-error `form` is not a Dockerfile field
+      new Dockerfile({ form: "alpine:3.20" }),
+      // @ts-expect-error `imgae` is not a service field
+      new Service({ imgae: "nginx:1.27" }),
+      // @ts-expect-error `restart` is a string
+      new Service({ image: "nginx:1.27", restart: 3 }),
+      // @ts-expect-error `condition` is one of the wait conditions
+      new Service({ depends_on: { db: { condition: "healthy" } } }),
+      // @ts-expect-error `internal` is a boolean
+      new Network({ internal: [] }),
+      // @ts-expect-error `fiel` is not a config field
+      new DockerConfig({ fiel: "./app.conf" }),
+    ];
+    // @ts-expect-error a step names one instruction it knows
+    const step: DockerfileStep = { from: "alpine" };
+    expect(typeof declare).toBe("function");
+    expect(step).toBeDefined();
+  });
+});