@intentius/chant-lexicon-docker 0.44.13 → 0.45.0

package/dist/codegen/docs.d.ts

@@ -1,10 +1,14 @@
 /**
  * Docker lexicon docs generation.
  *
- * The docker site is hand-authored under docs/src/content/docs/, unlike every
- * other lexicon's generated Starlight site. The rules table is the exception:
- * a hand-maintained one can fall behind the rules in src/lint/ without anything
- * catching it, so it is generated from source here (#1312).
+ * 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.
  */
 export declare function generateDocs(opts?: {
     verbose?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA4HH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9E"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "faf1f56b8a1192234d62f1f8468af193d87d9b47a928631385eb0b404be65027",
+    "manifest.json": "adf1925bb04b7eda3e2e189025e6e821bc3773b15cdaae533d162ccde15d599e",
     "meta.json": "ae27dc809e705d37a645ee83b9789c50051282f7891d21d6b9e6ce8d111624ff",
     "types/index.d.ts": "758f989ff86af54284d7f841a2db2259038d51ce1f3ed839a5d8e83fa20d95b8",
     "rules/no-latest-tag.ts": "efd060453d8ca3d5b85c3972906c6650b6f63eb5f67cb6cdb0f16a41cad91228",
@@ -15,5 +15,5 @@
     "skills/chant-docker.md": "3ff0708e3c76e245f202948949c768464563af2b60cc9aa2ca52f494ef8357f1",
     "skills/chant-docker-patterns.md": "ad1b0196d8150b2df579a699ff107f604340c799c04f3460ebf65003e287b12a"
   },
-  "composite": "747eca502c828510a77462ea94c2fefe43147c9da2cdcae8049fa4e2713b1c51"
+  "composite": "3137d93f8573cd0064ab9cb409c8aee458634cc8f4d06c512ae2e0f1bfff9a89"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "docker",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Docker",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-docker",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "description": "Docker lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,7 +67,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.44.13",
+    "@intentius/chant": "^0.45.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/docs.ts

@@ -1,42 +1,156 @@
 /**
  * Docker lexicon docs generation.
  *
- * The docker site is hand-authored under docs/src/content/docs/, unlike every
- * other lexicon's generated Starlight site. The rules table is the exception:
- * a hand-maintained one can fall behind the rules in src/lint/ without anything
- * catching it, so it is generated from source here (#1312).
+ * 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 { writeFileSync } from "fs";
-import { generateRulesPage, type DocsConfig } from "@intentius/chant/codegen/docs";
+import { docsPipeline, writeDocsSite, type DocsConfig } 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
+\`\`\``;
 
 export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
   const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
-  if (opts?.verbose) {
-    console.error("Generating Docker lexicon docs...");
-  }
-
-  const config = {
+  const config: DocsConfig = {
     name: "docker",
     displayName: "Docker",
-    description: "Typed constructors for Docker Compose files and Dockerfiles",
+    description: "Typed constructors for Docker Compose and Dockerfile configuration",
     distDir: join(pkgDir, "dist"),
     outDir: join(pkgDir, "docs"),
-  } as DocsConfig;
-
-  const rules = generateRulesPage(config, join(pkgDir, "src"));
-  if (rules) {
-    const out = join(pkgDir, "docs", "src", "content", "docs", "rules.mdx");
-    writeFileSync(out, rules);
-    if (opts?.verbose) {
-      console.error(`Wrote ${out}`);
-    }
-  }
+    basePath: "/chant/lexicons/docker/",
+    overview,
+    outputFormat,
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
 
-  // Every other page is hand-authored in docs/src/content/docs/.
-  // Future: auto-generate entity reference pages from lexicon-docker.json
-  console.error("Docker docs: rules.mdx generated; prose pages are hand-authored");
+  if (opts?.verbose) {
+    console.error("Documentation generated");
+  }
 }