@intentius/chant-lexicon-docker 0.1.0

package/src/codegen/generate.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, mock } from "bun:test";
+import { generate, writeGeneratedFiles } from "./generate";
+import { mkdirSync, rmSync, existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// Mock the network fetches so tests run offline and fast
+mock.module("../spec/fetch-compose", () => ({
+  fetchComposeSpec: async () => Buffer.from("{}"),
+}));
+
+mock.module("../spec/fetch-engine", () => ({
+  fetchEngineApi: async () => Buffer.from("{}"),
+}));
+
+describe("generate()", () => {
+  test("returns a GenerateResult with correct shape", async () => {
+    const result = await generate({ verbose: false });
+
+    expect(result).toBeDefined();
+    expect(typeof result.resources).toBe("number");
+    expect(typeof result.properties).toBe("number");
+    expect(typeof result.enums).toBe("number");
+    expect(Array.isArray(result.warnings)).toBe(true);
+    expect(typeof result.lexiconJSON).toBe("string");
+    expect(typeof result.typesDTS).toBe("string");
+    expect(typeof result.indexTS).toBe("string");
+  });
+
+  test("generates all 6 entity types", async () => {
+    const result = await generate({ verbose: false });
+    expect(result.resources).toBe(6); // 5 Compose + 1 Dockerfile
+  });
+
+  test("lexiconJSON includes all entity class names", async () => {
+    const result = await generate({ verbose: false });
+    const json = JSON.parse(result.lexiconJSON);
+
+    expect(json.Service).toBeDefined();
+    expect(json.Volume).toBeDefined();
+    expect(json.Network).toBeDefined();
+    expect(json.DockerConfig).toBeDefined();
+    expect(json.DockerSecret).toBeDefined();
+    expect(json.Dockerfile).toBeDefined();
+  });
+
+  test("lexiconJSON entries have resourceType and kind", async () => {
+    const result = await generate({ verbose: false });
+    const json = JSON.parse(result.lexiconJSON);
+
+    expect(json.Service.resourceType).toBe("Docker::Compose::Service");
+    expect(json.Service.kind).toBe("resource");
+    expect(json.Dockerfile.resourceType).toBe("Docker::Dockerfile");
+  });
+
+  test("indexTS exports all entity names", async () => {
+    const result = await generate({ verbose: false });
+    expect(result.indexTS).toContain("export const Service");
+    expect(result.indexTS).toContain("export const Dockerfile");
+    expect(result.indexTS).toContain('createResource("Docker::Compose::Service"');
+  });
+
+  test("typesDTS declares all entity interfaces", async () => {
+    const result = await generate({ verbose: false });
+    expect(result.typesDTS).toContain("interface ServiceProps");
+    expect(result.typesDTS).toContain("interface DockerfileProps");
+    expect(result.typesDTS).toContain("declare const Service");
+  });
+
+  test("properties count is non-zero", async () => {
+    const result = await generate({ verbose: false });
+    expect(result.properties).toBeGreaterThan(0);
+  });
+});
+
+describe("writeGeneratedFiles()", () => {
+  const tmpDir = join(tmpdir(), `chant-docker-test-${Date.now()}`);
+
+  test("writes all expected files to src/generated/", async () => {
+    mkdirSync(join(tmpDir, "src", "generated"), { recursive: true });
+
+    const result = await generate({ verbose: false });
+    writeGeneratedFiles(result, tmpDir);
+
+    expect(existsSync(join(tmpDir, "src", "generated", "lexicon-docker.json"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src", "generated", "index.ts"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src", "generated", "index.d.ts"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src", "generated", "runtime.ts"))).toBe(true);
+
+    // Clean up
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("lexicon-docker.json is valid JSON", async () => {
+    mkdirSync(join(tmpDir, "src", "generated"), { recursive: true });
+
+    const result = await generate({ verbose: false });
+    writeGeneratedFiles(result, tmpDir);
+
+    const json = readFileSync(join(tmpDir, "src", "generated", "lexicon-docker.json"), "utf-8");
+    expect(() => JSON.parse(json)).not.toThrow();
+
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+});

package/src/codegen/generate.ts

@@ -0,0 +1,158 @@
+/**
+ * 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";
+import { generateDockerfilePipeline } from "./generate-dockerfile";
+import { entityTypeToTsName } from "./naming";
+import type { ComposeParseResult } from "../spec/parse-compose";
+import type { DockerfileParseResult } from "../spec/parse-engine";
+
+export interface DockerGenerateResult {
+  resources: number;
+  properties: number;
+  enums: number;
+  warnings: Array<{ file: string; error: string }>;
+  lexiconJSON: string;
+  typesDTS: string;
+  indexTS: string;
+}
+
+/**
+ * Run the full Docker generation pipeline.
+ */
+export async function generate(opts: { verbose?: boolean; force?: boolean } = {}): Promise<DockerGenerateResult> {
+  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: ComposeParseResult[], dockerfile: DockerfileParseResult): string {
+  const entries: Record<string, unknown> = {};
+
+  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.map((i) => [i.name, { description: i.description ?? "" }]),
+    ),
+  };
+
+  return JSON.stringify(entries, null, 2);
+}
+
+function generateTypesDTS(compose: ComposeParseResult[], dockerfile: DockerfileParseResult): string {
+  const lines: string[] = [
+    "// Code generated by chant generate. DO NOT EDIT.",
+    'import type { Declarable } from "@intentius/chant/declarable";',
+    "",
+  ];
+
+  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("");
+  }
+
+  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("");
+
+  return lines.join("\n");
+}
+
+function generateIndexTS(compose: ComposeParseResult[], dockerfile: DockerfileParseResult): string {
+  const lines: string[] = [
+    "// Code generated by chant generate. DO NOT EDIT.",
+    'import { createResource } from "./runtime";',
+    "",
+  ];
+
+  for (const c of compose) {
+    const tsName = entityTypeToTsName(c.typeName);
+    lines.push(`export const ${tsName} = createResource("${c.typeName}", "docker", {});`);
+  }
+
+  lines.push("");
+  const dfName = entityTypeToTsName(dockerfile.typeName);
+  lines.push(`export const ${dfName} = createResource("${dockerfile.typeName}", "docker", {});`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Write generated artifacts to disk under baseDir/src/generated/.
+ */
+export function writeGeneratedFiles(result: DockerGenerateResult, baseDir: string): void {
+  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/src/codegen/naming.test.ts

@@ -0,0 +1,81 @@
+import { describe, test, expect } from "bun:test";
+import {
+  entityTypeToTsName,
+  tsNameToEntityType,
+  isComposeType,
+  isDockerfileType,
+  ALL_ENTITY_TYPES,
+} from "./naming";
+
+describe("entityTypeToTsName", () => {
+  test("maps Compose Service", () => {
+    expect(entityTypeToTsName("Docker::Compose::Service")).toBe("Service");
+  });
+
+  test("maps Compose Volume", () => {
+    expect(entityTypeToTsName("Docker::Compose::Volume")).toBe("Volume");
+  });
+
+  test("maps Compose Network", () => {
+    expect(entityTypeToTsName("Docker::Compose::Network")).toBe("Network");
+  });
+
+  test("maps Compose Config with disambiguation", () => {
+    expect(entityTypeToTsName("Docker::Compose::Config")).toBe("DockerConfig");
+  });
+
+  test("maps Compose Secret with disambiguation", () => {
+    expect(entityTypeToTsName("Docker::Compose::Secret")).toBe("DockerSecret");
+  });
+
+  test("maps Dockerfile", () => {
+    expect(entityTypeToTsName("Docker::Dockerfile")).toBe("Dockerfile");
+  });
+
+  test("falls back to last segment for unknown types", () => {
+    expect(entityTypeToTsName("Docker::Unknown::Foo")).toBe("Foo");
+  });
+});
+
+describe("tsNameToEntityType", () => {
+  test("reverse maps Service", () => {
+    expect(tsNameToEntityType("Service")).toBe("Docker::Compose::Service");
+  });
+
+  test("reverse maps Dockerfile", () => {
+    expect(tsNameToEntityType("Dockerfile")).toBe("Docker::Dockerfile");
+  });
+
+  test("returns undefined for unknown name", () => {
+    expect(tsNameToEntityType("Unknown")).toBeUndefined();
+  });
+});
+
+describe("isComposeType", () => {
+  test("true for Compose types", () => {
+    expect(isComposeType("Docker::Compose::Service")).toBe(true);
+    expect(isComposeType("Docker::Compose::Volume")).toBe(true);
+  });
+
+  test("false for Dockerfile", () => {
+    expect(isComposeType("Docker::Dockerfile")).toBe(false);
+  });
+});
+
+describe("isDockerfileType", () => {
+  test("true for Dockerfile", () => {
+    expect(isDockerfileType("Docker::Dockerfile")).toBe(true);
+  });
+
+  test("false for Compose types", () => {
+    expect(isDockerfileType("Docker::Compose::Service")).toBe(false);
+  });
+});
+
+describe("ALL_ENTITY_TYPES", () => {
+  test("contains all six types", () => {
+    expect(ALL_ENTITY_TYPES).toHaveLength(6);
+    expect(ALL_ENTITY_TYPES).toContain("Docker::Compose::Service");
+    expect(ALL_ENTITY_TYPES).toContain("Docker::Dockerfile");
+  });
+});

package/src/codegen/naming.ts

@@ -0,0 +1,54 @@
+/**
+ * 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: Record<string, string> = {
+  "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: Record<string, string> = 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: string): string {
+  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: string): string | undefined {
+  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: string): boolean {
+  return entityType.startsWith("Docker::Compose::");
+}
+
+/**
+ * Check whether an entity type is the Dockerfile resource.
+ */
+export function isDockerfileType(entityType: string): boolean {
+  return entityType === "Docker::Dockerfile";
+}

package/src/codegen/package.ts

@@ -0,0 +1,65 @@
+/**
+ * Docker lexicon packaging — delegates to core packagePipeline.
+ */
+
+import { createRequire } from "module";
+import { readFileSync } from "fs";
+const require = createRequire(import.meta.url);
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import type { IntrinsicDef } from "@intentius/chant/lexicon";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Package the Docker lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+
+      buildManifest: (_genResult) => {
+        const intrinsics: IntrinsicDef[] = [
+          {
+            name: "env",
+            description: "Docker Compose variable interpolation — ${VAR}, ${VAR:-default}, ${VAR:?error}",
+            outputKey: "env",
+            isTag: false,
+          },
+        ];
+
+        return {
+          name: "docker",
+          version: pkgJson.version ?? "0.0.0",
+          chantVersion: ">=0.1.0",
+          namespace: "Docker",
+          intrinsics,
+          pseudoParameters: {},
+        };
+      },
+
+      srcDir: pkgDir,
+
+      collectSkills: () => {
+        const { dockerPlugin } = require("../plugin");
+        const skillDefs = dockerPlugin.skills?.() ?? [];
+        return collectSkills(skillDefs);
+      },
+
+      version: pkgJson.version ?? "0.0.0",
+    },
+    opts,
+  );
+}

package/src/codegen/patches.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+export interface EntityPatch {
+  /** Override entity description */
+  description?: string;
+  /** Override specific property types */
+  propertyOverrides?: Record<string, { type?: string; description?: string }>;
+  /** Properties to exclude from type generation */
+  excludeProperties?: string[];
+}
+
+/**
+ * Patches keyed by entity typeName.
+ */
+export const ENTITY_PATCHES: Record<string, EntityPatch> = {
+  "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/src/codegen/versions.ts

@@ -0,0 +1,15 @@
+/**
+ * Pinned URLs and version tags for upstream Docker specs.
+ */
+
+/** Compose Spec JSON Schema — master branch */
+export const COMPOSE_SPEC_URL =
+  "https://raw.githubusercontent.com/compose-spec/compose-spec/master/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/ */
+export const COMPOSE_SPEC_CACHE = "docker-compose-spec.json";
+export const ENGINE_API_CACHE = "docker-engine-api.yaml";

package/src/composites/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Docker lexicon composites.
+ *
+ * Composites are factory functions that return pre-configured
+ * multi-resource bundles. Docker composites will be added here.
+ */
+
+// Composites deferred — see plan for Tier 2 implementation.
+// Example future composites:
+//   - PostgresService({ version, database, user, password }) → Service + Volume
+//   - RedisService({ version, persistence }) → Service + Volume
+//   - NginxService({ port, config }) → Service

package/src/coverage.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "bun:test";
+import { analyzeDockerCoverage, computeCoverage } from "./coverage";
+
+describe("analyzeDockerCoverage", () => {
+  test("is an async function", () => {
+    expect(typeof analyzeDockerCoverage).toBe("function");
+  });
+
+  test("throws when generated dir does not exist", async () => {
+    await expect(
+      analyzeDockerCoverage({ basePath: "/tmp/nonexistent-docker-lexicon-test" }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("computeCoverage", () => {
+  test("is a function", () => {
+    expect(typeof computeCoverage).toBe("function");
+  });
+
+  test("handles a minimal lexicon JSON", () => {
+    const minimal = JSON.stringify({
+      Service: {
+        resourceType: "Docker::Compose::Service",
+        kind: "resource",
+        description: "A service",
+        properties: {},
+      },
+    });
+    const report = computeCoverage(minimal);
+    expect(report).toBeDefined();
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,54 @@
+/**
+ * Coverage analysis for Docker lexicon.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+  type CoverageThresholds,
+} from "@intentius/chant/codegen/coverage";
+
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+
+/**
+ * Run coverage analysis for the Docker lexicon.
+ */
+export async function analyzeDockerCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<CoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(basePath, "src", "generated", "lexicon-docker.json");
+
+  if (!existsSync(lexiconPath)) {
+    throw new Error(`Generated lexicon not found at ${lexiconPath}. Run "chant dev generate" first.`);
+  }
+
+  const content = readFileSync(lexiconPath, "utf-8");
+  const report = computeCoverage(content);
+
+  if (opts?.verbose) {
+    console.error(formatVerbose(report));
+  } else {
+    console.error(formatSummary(report));
+  }
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+
+  return report;
+}