@intentius/chant-lexicon-docker 0.124.31 → 0.124.33

package/dist/codegen/docs-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry for Docker lexicon docs generation.
+ */
+import { generateDocs } from "./docs.js";
+const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+await generateDocs({ verbose });

package/dist/codegen/docs.js

@@ -0,0 +1,163 @@
+/**
+ * Docker lexicon docs generation.
+ *
+ * Uses the shared docsPipeline/writeDocsSite flow like every other lexicon
+ * (chant #1731, #1755). Hand-written prose lives under docs/pages/, each
+ * page tagged with a Diátaxis quadrant; index.mdx and serialization.mdx are
+ * generated from the overview/outputFormat strings below, and rules.mdx is
+ * generated from the rule sources under src/lint/ the same way it always
+ * was — this used to be the one lexicon whose rules table could drift from
+ * source without anything catching it (#1312), and the shared pipeline
+ * keeps that guarantee.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const overview = `
+The **Docker** lexicon provides typed constructors for Docker Compose services
+and Dockerfile build instructions — services, volumes, networks, configs, secrets,
+and multi-stage Dockerfiles.
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-docker
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+import { Service, Volume, Dockerfile, env } from "@intentius/chant-lexicon-docker";
+
+export const db = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_PASSWORD: env("DB_PASSWORD", { required: true }),
+  },
+  volumes: ["pgdata:/var/lib/postgresql/data"],
+});
+
+export const pgdata = new Volume({});
+
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  depends_on: ["db"],
+});
+\`\`\`
+
+Build:
+
+\`\`\`bash
+chant build src --lexicon docker -o docker-compose.yml
+\`\`\`
+
+## Output Domains
+
+| Entity | Output file | Section |
+|--------|-------------|---------|
+| \`Service\` | \`docker-compose.yml\` | \`services:\` |
+| \`Volume\` | \`docker-compose.yml\` | \`volumes:\` |
+| \`Network\` | \`docker-compose.yml\` | \`networks:\` |
+| \`Config\` | \`docker-compose.yml\` | \`configs:\` |
+| \`Secret\` | \`docker-compose.yml\` | \`secrets:\` |
+| \`Dockerfile\` | \`Dockerfile.{name}\` | — |`;
+const outputFormat = `
+The Docker lexicon serializes to two output formats.
+
+## docker-compose.yml
+
+\`\`\`bash
+chant build src --lexicon docker -o docker-compose.yml
+\`\`\`
+
+Each entity type maps to a top-level Compose section. The TypeScript export name becomes the key within that section.
+
+\`\`\`typescript
+export const db = new Service({ image: "postgres:16-alpine" });
+export const pgdata = new Volume({});
+export const backend = new Network({ driver: "bridge" });
+\`\`\`
+
+Produces:
+
+\`\`\`yaml
+services:
+  db:
+    image: postgres:16-alpine
+
+volumes:
+  pgdata: null
+
+networks:
+  backend:
+    driver: bridge
+\`\`\`
+
+\`defaultLabels()\` entities are not emitted as separate keys — their labels are merged into each service.
+
+## Dockerfile.\\{name\\}
+
+\`\`\`bash
+chant build src --lexicon docker
+# Writes Dockerfile.app, Dockerfile.builder, etc.
+\`\`\`
+
+Each \`Dockerfile\` entity produces a separate file. The export name is the suffix.
+
+\`\`\`typescript
+export const builder = new Dockerfile({ from: "node:20-alpine", ... });
+// → Dockerfile.builder
+\`\`\`
+
+## Field mapping
+
+| TypeScript | docker-compose.yml | Notes |
+|-----------|-------------------|-------|
+| \`env("X", { required: true })\` | \`\${X:?X is required}\` | Compose interpolation |
+| \`env("X", { default: "v" })\` | \`\${X:-v}\` | Compose interpolation |
+| \`env("X")\` | \`\${X}\` | Compose interpolation |
+| \`external: true\` | \`external: true\` | Volume/Network |
+
+## Specifying lexicon at build time
+
+The \`--lexicon docker\` flag restricts output to Docker entities only — useful in mixed-lexicon projects:
+
+\`\`\`bash
+# Only Docker output
+chant build src --lexicon docker -o docker-compose.yml
+
+# Other lexicons still get their own outputs
+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.
+Do not push an image, run \`docker compose up\` against anything but the local Docker daemon, or change files outside this project.
+Never deploy to a real cloud account or shared environment (with \`chant run\`, \`chant components\` or a platform's own CLI), approve (a pull request review, \`chant approve\` or \`chant run approve\`), override a policy denial (\`chant approve policy-override\`), or merge; never cut or publish a release (\`chant release cut --yes\` or \`chant release publish\`), push or delete a \`ci/*\` tag (\`chant ci tick\` pushes them), or change the value of an existing flag; never touch \`.chant/allowed_signers\` or \`chant/lifecycle\`.`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "docker",
+        displayName: "Docker",
+        description: "Typed constructors for Docker Compose and Dockerfile configuration",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: "/chant/lexicons/docker/",
+        overview,
+        outputFormat,
+        prompt,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error("Documentation generated");
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Docker lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    console.error("Generating Docker lexicon...");
+    const result = await generate({ verbose, force });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} entities, ${result.properties} property types, ${result.enums} enums`);
+    if (result.warnings.length > 0) {
+        console.error(`${result.warnings.length} warnings:`);
+        for (const w of result.warnings) {
+            console.error(`  ${w.file}: ${w.error}`);
+        }
+    }
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate-compose.js

@@ -0,0 +1,16 @@
+/**
+ * Generate Compose entity types from the Compose Spec JSON Schema.
+ */
+import { fetchComposeSpec } from "../spec/fetch-compose.js";
+import { parseComposeSpec } from "../spec/parse-compose.js";
+export async function generateComposePipeline(opts = {}) {
+    if (opts.verbose)
+        console.error("Fetching Compose Spec...");
+    const data = await fetchComposeSpec(opts.force);
+    if (opts.verbose)
+        console.error("Parsing Compose Spec...");
+    const results = parseComposeSpec(data);
+    if (opts.verbose)
+        console.error(`Parsed ${results.length} Compose entity types`);
+    return { results };
+}

package/dist/codegen/generate-dockerfile.js

@@ -0,0 +1,16 @@
+/**
+ * Generate Dockerfile entity types from the Docker Engine API OpenAPI spec.
+ */
+import { fetchEngineApi } from "../spec/fetch-engine.js";
+import { parseEngineApi } from "../spec/parse-engine.js";
+export async function generateDockerfilePipeline(opts = {}) {
+    if (opts.verbose)
+        console.error("Fetching Docker Engine API...");
+    const data = await fetchEngineApi(opts.force);
+    if (opts.verbose)
+        console.error("Parsing Engine API for Dockerfile types...");
+    const result = parseEngineApi(data);
+    if (opts.verbose)
+        console.error(`Parsed ${result.instructions.length} Dockerfile instructions`);
+    return { result };
+}

package/dist/codegen/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwB/G;AA2LD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAWvF"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwB/G;AA8LD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAWvF"}

package/dist/codegen/generate.js

@@ -0,0 +1,212 @@
+/**
+ * Docker lexicon generation pipeline.
+ *
+ * Orchestrates both Compose and Dockerfile type generation,
+ * then writes merged artifacts to src/generated/.
+ */
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { generateComposePipeline } from "./generate-compose.js";
+import { generateDockerfilePipeline } from "./generate-dockerfile.js";
+import { entityTypeToTsName } from "./naming.js";
+import { PER_KIND_ORDER } from "../dockerfile-order.js";
+import { COMPOSE_STRING } from "../spec/parse-compose.js";
+/**
+ * Run the full Docker generation pipeline.
+ */
+export async function generate(opts = {}) {
+    const [composeResult, dockerfileResult] = await Promise.all([
+        generateComposePipeline(opts),
+        generateDockerfilePipeline(opts),
+    ]);
+    const allCompose = composeResult.results;
+    const dockerfile = dockerfileResult.result;
+    const lexiconJSON = generateLexiconJSON(allCompose, dockerfile);
+    const typesDTS = generateTypesDTS(allCompose, dockerfile);
+    const indexTS = generateIndexTS(allCompose, dockerfile);
+    const propertyCount = allCompose.reduce((n, c) => n + c.properties.length, 0) + dockerfile.instructions.length;
+    return {
+        resources: allCompose.length + 1, // +1 for Dockerfile
+        properties: propertyCount,
+        enums: 0,
+        warnings: [],
+        lexiconJSON,
+        typesDTS,
+        indexTS,
+    };
+}
+function generateLexiconJSON(compose, dockerfile) {
+    const entries = {};
+    for (const c of compose) {
+        const tsName = entityTypeToTsName(c.typeName);
+        entries[tsName] = {
+            resourceType: c.typeName,
+            kind: "resource",
+            description: c.description ?? "",
+            properties: Object.fromEntries(c.properties.map((p) => [p.name, { type: p.type, description: p.description ?? "" }])),
+        };
+    }
+    const dfName = entityTypeToTsName(dockerfile.typeName);
+    entries[dfName] = {
+        resourceType: dockerfile.typeName,
+        kind: "resource",
+        description: dockerfile.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);
+}
+function generateTypesDTS(compose, dockerfile) {
+    const lines = [
+        "// 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 declare const ${tsName}: new (props?: ${tsName}Props, attributes?: Record<string, unknown>) => Declarable;`);
+    }
+    lines.push("");
+    const dfName = entityTypeToTsName(dockerfile.typeName);
+    lines.push(...dockerfileTypeLines(dockerfile));
+    lines.push(`export declare const ${dfName}: new (props?: DockerfileProps, attributes?: Record<string, unknown>) => Declarable;`);
+    lines.push("");
+    return lines.join("\n");
+}
+function generateIndexTS(compose, dockerfile) {
+    const lines = [
+        "// Code generated by chant generate. DO NOT EDIT.",
+        'import { createResource } from "./runtime";',
+        'import type { Declarable } from "@intentius/chant/declarable";',
+        'import type { EnvIntrinsic } from "../interpolation.js";',
+        "",
+        // 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", {}) 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", {}) as unknown as DockerResourceConstructor<DockerfileProps>;`);
+    lines.push("");
+    return lines.join("\n");
+}
+/** One props interface per Compose entity. */
+function composeTypeLines(compose) {
+    const lines = [
+        "/**",
+        " * 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};`);
+        }
+        // The Compose spec allows `x-` extension fields on every entity, and import keeps them (#4136).
+        lines.push(`  /** A Compose extension field. The spec allows any \`x-\` key, and Compose itself ignores it. */`);
+        lines.push("  [extension: `x-${string}`]: unknown;");
+        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) {
+    const lines = [];
+    const stepInstructions = dockerfile.instructions.filter((i) => i.name !== "from");
+    const perKind = stepInstructions.filter((i) => !i.stepOnly);
+    const stepValue = (i) => ["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 = () => {
+        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/.
+ */
+export function writeGeneratedFiles(result, baseDir) {
+    const generatedDir = join(baseDir, "src", "generated");
+    mkdirSync(generatedDir, { recursive: true });
+    writeFileSync(join(generatedDir, "lexicon-docker.json"), result.lexiconJSON);
+    writeFileSync(join(generatedDir, "index.d.ts"), result.typesDTS);
+    writeFileSync(join(generatedDir, "index.ts"), result.indexTS);
+    writeFileSync(join(generatedDir, "runtime.ts"), `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`);
+}

package/dist/codegen/naming.js

@@ -0,0 +1,45 @@
+/**
+ * Naming strategy for Docker lexicon entities.
+ *
+ * Converts Docker/Compose entity type names to TypeScript class names.
+ */
+/** Map entityType → TypeScript class name */
+const ENTITY_TYPE_TO_TS_NAME = {
+    "Docker::Compose::Service": "Service",
+    "Docker::Compose::Volume": "Volume",
+    "Docker::Compose::Network": "Network",
+    "Docker::Compose::Config": "DockerConfig",
+    "Docker::Compose::Secret": "DockerSecret",
+    "Docker::Dockerfile": "Dockerfile",
+};
+/** Map TypeScript class name → entityType */
+const TS_NAME_TO_ENTITY_TYPE = Object.fromEntries(Object.entries(ENTITY_TYPE_TO_TS_NAME).map(([k, v]) => [v, k]));
+/**
+ * Convert a Docker entity type name to a TypeScript class name.
+ * e.g. "Docker::Compose::Service" → "Service"
+ */
+export function entityTypeToTsName(entityType) {
+    return ENTITY_TYPE_TO_TS_NAME[entityType] ?? entityType.split("::").pop() ?? entityType;
+}
+/**
+ * Convert a TypeScript class name back to an entity type.
+ */
+export function tsNameToEntityType(tsName) {
+    return TS_NAME_TO_ENTITY_TYPE[tsName];
+}
+/**
+ * All known Docker entity types, in declaration order.
+ */
+export const ALL_ENTITY_TYPES = Object.keys(ENTITY_TYPE_TO_TS_NAME);
+/**
+ * Check whether an entity type is a Compose resource.
+ */
+export function isComposeType(entityType) {
+    return entityType.startsWith("Docker::Compose::");
+}
+/**
+ * Check whether an entity type is the Dockerfile resource.
+ */
+export function isDockerfileType(entityType) {
+    return entityType === "Docker::Dockerfile";
+}

package/dist/codegen/package.js

@@ -0,0 +1,40 @@
+/**
+ * Docker lexicon packaging — delegates to core packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { dockerPlugin } from "../plugin.js";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
+/**
+ * Package the Docker lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: (_genResult) => {
+            // Derived from the plugin's own registration (chant #1067) — this
+            // used to be a hand-maintained array independent of ../plugin.ts,
+            // free to drift from the real registration without anything
+            // noticing.
+            const intrinsics = dockerPlugin.intrinsics?.() ?? [];
+            return {
+                name: "docker",
+                version: pkgJson.version ?? "0.0.0",
+                chantVersion: ">=0.1.0",
+                namespace: "Docker",
+                intrinsics,
+                pseudoParameters: {},
+            };
+        },
+        srcDir: pkgDir,
+        collectSkills: () => {
+            const skillDefs = dockerPlugin.skills?.() ?? [];
+            return collectSkills(skillDefs);
+        },
+        version: pkgJson.version ?? "0.0.0",
+    }, opts);
+}

package/dist/codegen/patches.js

@@ -0,0 +1,31 @@
+/**
+ * Manual overrides for upstream Docker spec quirks.
+ *
+ * These patches adjust entity names, property types, or descriptions
+ * where the upstream spec is ambiguous, incorrect, or overly broad.
+ */
+/**
+ * Patches keyed by entity typeName.
+ */
+export const ENTITY_PATCHES = {
+    "Docker::Compose::Service": {
+        propertyOverrides: {
+            // The spec allows both string and object forms for these — normalize to object
+            depends_on: {
+                description: "Service dependencies (may be string[] or condition map)",
+            },
+            // healthcheck interval/timeout are duration strings in Docker syntax
+            healthcheck: {
+                description: "Health check configuration with Docker duration strings (e.g., '30s', '1m30s')",
+            },
+        },
+    },
+    "Docker::Dockerfile": {
+        propertyOverrides: {
+            // Multi-stage builds use stages array
+            stages: {
+                description: "Multi-stage build stages — each stage has its own FROM and instructions",
+            },
+        },
+    },
+};

package/dist/codegen/versions.js

@@ -0,0 +1,41 @@
+/**
+ * Pinned URLs and version tags for upstream Docker specs.
+ */
+/**
+ * Pinned commit of compose-spec/compose-spec (#1146).
+ *
+ * compose-spec/compose-spec has no tagged releases, so unlike
+ * ENGINE_API_URL below (pinned to the `v27.3.1` tag) there is no version tag
+ * to pin against — codegen used to fetch the default branch directly (the
+ * repo's default branch is `main`; the old URL fetched `master`, a legacy
+ * alias GitHub still redirects, but a moving-branch alias all the same).
+ * That meant a cold cache picked up whatever upstream state had landed since
+ * the cache last expired, while a warm cache kept serving whatever was
+ * current when it was last filled — the exact CI nondeterminism this fix
+ * closed for azure (#1144).
+ *
+ * Pinning to a commit SHA makes generation reproducible regardless of cache
+ * state. Bump policy: #523's scheduled lexicon-upgrade cron (rolling-spec
+ * bucket) is meant to propose bumps to this constant as a reviewable PR once
+ * built. Until then, bump by hand: take the current `main` HEAD sha from
+ * https://github.com/compose-spec/compose-spec/commits/main, regenerate, fix
+ * up any composite left referencing a renamed or vanished export, and update
+ * this constant + comment.
+ */
+export const COMPOSE_SPEC_COMMIT = "11296e387ba76c77db1db768b9153a4304a3c9bd";
+/** Compose Spec JSON Schema — pinned to COMPOSE_SPEC_COMMIT, not a moving branch */
+export const COMPOSE_SPEC_URL = `https://raw.githubusercontent.com/compose-spec/compose-spec/${COMPOSE_SPEC_COMMIT}/schema/compose-spec.json`;
+/** Docker Engine API OpenAPI spec (v1.45) */
+export const ENGINE_API_URL = "https://raw.githubusercontent.com/moby/moby/v27.3.1/api/swagger.yaml";
+/**
+ * Cache filenames under ~/.chant/.
+ *
+ * COMPOSE_SPEC_CACHE embeds the pin so a stale schema file fetched before a
+ * bump can never satisfy the new pin: restoring an old ~/.chant (e.g. a CI
+ * cache partial-key fallback, or a developer's pre-existing cache) simply
+ * misses this filename and re-downloads, instead of silently serving
+ * pre-bump schema under a name that still matches (#1146, mirroring azure's
+ * AZURE_SCHEMA_COMMIT-keyed cache filename, #1144).
+ */
+export const COMPOSE_SPEC_CACHE = `docker-compose-spec-${COMPOSE_SPEC_COMMIT}.json`;
+export const ENGINE_API_CACHE = "docker-engine-api.yaml";

package/dist/compose-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The key an entity takes in docker-compose.yml.
+ *
+ * A compose entity's key is its export name by default. A key that is not a
+ * TypeScript identifier (`db-password`, `nginx.conf`) cannot be an export
+ * name, so `composeKey` sets it explicitly (#3937):
+ *
+ * @example
+ * export const dbPassword = composeKey("db-password", new DockerSecret({ file: "./db-password.txt" }));
+ *
+ * References to the entity (`secrets: [dbPassword]`) serialize as the key.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+export declare const COMPOSE_KEY: unique symbol;
+/** Give a compose entity an explicit key in docker-compose.yml. Returns the entity. */
+export declare function composeKey<T extends Declarable>(key: string, entity: T): T;
+/** The key set by `composeKey`, or undefined. */
+export declare function getComposeKey(entity: Declarable): string | undefined;
+//# sourceMappingURL=compose-key.d.ts.map

package/dist/compose-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-key.d.ts","sourceRoot":"","sources":["../src/compose-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,eAAO,MAAM,WAAW,eAAkC,CAAC;AAE3D,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAM1E;AAED,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGpE"}

package/dist/compose-key.js

@@ -0,0 +1,26 @@
+/**
+ * The key an entity takes in docker-compose.yml.
+ *
+ * A compose entity's key is its export name by default. A key that is not a
+ * TypeScript identifier (`db-password`, `nginx.conf`) cannot be an export
+ * name, so `composeKey` sets it explicitly (#3937):
+ *
+ * @example
+ * export const dbPassword = composeKey("db-password", new DockerSecret({ file: "./db-password.txt" }));
+ *
+ * References to the entity (`secrets: [dbPassword]`) serialize as the key.
+ */
+export const COMPOSE_KEY = Symbol.for("docker.composeKey");
+/** Give a compose entity an explicit key in docker-compose.yml. Returns the entity. */
+export function composeKey(key, entity) {
+    if (typeof key !== "string" || key === "") {
+        throw new Error("composeKey: the key must be a non-empty string");
+    }
+    Object.defineProperty(entity, COMPOSE_KEY, { value: key, enumerable: false, configurable: true });
+    return entity;
+}
+/** The key set by `composeKey`, or undefined. */
+export function getComposeKey(entity) {
+    const key = entity[COMPOSE_KEY];
+    return typeof key === "string" ? key : undefined;
+}