@intentius/chant-lexicon-docker 0.124.21 → 0.124.23

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 type { ComposeParseResult } from "../spec/parse-compose";
-import type { DockerfileParseResult } from "../spec/parse-engine";
+import { PER_KIND_ORDER } from "../dockerfile-order";
+import { COMPOSE_STRING, type ComposeParseResult } from "../spec/parse-compose";
+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);
@@ -85,37 +90,23 @@ function generateTypesDTS(compose: ComposeParseResult[], dockerfile: DockerfileP
     "// Code generated by chant generate. DO NOT EDIT.",
     'import type { Declarable } from "@intentius/chant/declarable";',
     "",
+    // This file is type-checked on its own (validate's types-compile), so it
+    // can't import the interpolation module; an env() value is matched by shape.
+    "/** An `env()` interpolation, as returned by the lexicon's `env`. */",
+    "interface EnvIntrinsic { toJSON(): string; toString(): string; }",
+    "",
   ];
 
+  lines.push(...composeTypeLines(compose));
   for (const c of compose) {
     const tsName = entityTypeToTsName(c.typeName);
-    lines.push(`export interface ${tsName}Props {`);
-    for (const p of c.properties) {
-      const opt = p.required ? "" : "?";
-      lines.push(`  ${p.name}${opt}: ${p.type};`);
-    }
-    lines.push(`}`);
-    lines.push(`export declare const ${tsName}: new (props?: ${tsName}Props) => Declarable;`);
-    lines.push("");
+    lines.push(`export declare const ${tsName}: new (props?: ${tsName}Props, attributes?: Record<string, unknown>) => Declarable;`);
   }
+  lines.push("");
 
   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(`export declare const ${dfName}: new (props?: DockerfileProps) => Declarable;`);
+  lines.push(...dockerfileTypeLines(dockerfile));
+  lines.push(`export declare const ${dfName}: new (props?: DockerfileProps, attributes?: Record<string, unknown>) => Declarable;`);
   lines.push("");
 
   return lines.join("\n");
@@ -125,22 +116,128 @@ function generateIndexTS(compose: ComposeParseResult[], dockerfile: DockerfilePa
   const lines: string[] = [
     "// Code generated by chant generate. DO NOT EDIT.",
     'import { createResource } from "./runtime";',
+    'import type { Declarable } from "@intentius/chant/declarable";',
+    'import type { EnvIntrinsic } from "../interpolation";',
+    "",
+    // createResource returns a constructor with untyped props. Each constructor
+    // below is cast to one that takes its props type, so a misspelled key or a
+    // wrong field type is a compile error where the resource is written, and
+    // the editor completes the fields (#3934).
+    "/** A docker resource constructor whose props are type-checked. */",
+    "export type DockerResourceConstructor<P> = new (props?: P, attributes?: Record<string, unknown>) => InstanceType<ReturnType<typeof createResource>>;",
     "",
   ];
 
+  lines.push(...composeTypeLines(compose));
   for (const c of compose) {
     const tsName = entityTypeToTsName(c.typeName);
-    lines.push(`export const ${tsName} = createResource("${c.typeName}", "docker", {});`);
+    lines.push(
+      `export const ${tsName} = createResource("${c.typeName}", "docker", {}) as unknown as DockerResourceConstructor<${tsName}Props>;`,
+    );
   }
 
+  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("");
   const dfName = entityTypeToTsName(dockerfile.typeName);
-  lines.push(`export const ${dfName} = createResource("${dockerfile.typeName}", "docker", {});`);
+  lines.push(
+    `export const ${dfName} = createResource("${dockerfile.typeName}", "docker", {}) as unknown as DockerResourceConstructor<DockerfileProps>;`,
+  );
   lines.push("");
 
   return lines.join("\n");
 }
 
+/** One props interface per Compose entity. */
+function composeTypeLines(compose: ComposeParseResult[]): string[] {
+  const lines: string[] = [
+    "/**",
+    " * A Compose string value: a string, an `env()` interpolation, or an entity",
+    " * (service, network, volume, config, secret or Dockerfile), which is written as its name.",
+    " */",
+    `export type ${COMPOSE_STRING} = string | EnvIntrinsic | Declarable;`,
+    "",
+  ];
+  for (const c of compose) {
+    const tsName = entityTypeToTsName(c.typeName);
+    if (c.description) lines.push(`/** ${c.description} */`);
+    lines.push(`export interface ${tsName}Props {`);
+    for (const p of c.properties) {
+      const opt = p.required ? "" : "?";
+      if (p.description) lines.push(`  /** ${p.description} */`);
+      lines.push(`  ${p.name}${opt}: ${p.type};`);
+    }
+    lines.push(`}`);
+    lines.push("");
+  }
+  return lines;
+}
+
+/**
+ * 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/codegen/okf.test.ts

@@ -25,7 +25,7 @@ describe("docker OKF bundle", () => {
     expect(front.type).toBe("resource-type");
     expect(front.resource_type).toBe("Docker::Compose::Service");
     // Registry-carried property description reaches the concept body.
-    expect(service.body).toContain("- `image` (`string`): Container image to use");
+    expect(service.body).toContain("- `image` (`ComposeString`): Specify the image to start the container from.");
     // The no-latest-tag rule governs Service…
     expect(service.body).toContain("[DKRS001](/rules/DKRS001.md)");
     // …and points back at it.

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, ""));
+  });
+});