@intentius/chant-lexicon-docker 0.1.0

package/src/plugin.ts

@@ -0,0 +1,250 @@
+/**
+ * Docker lexicon plugin.
+ *
+ * Provides serializer, lint rules, post-synth checks, intrinsics, LSP support,
+ * and code generation for Docker Compose and Dockerfile resources.
+ */
+
+import { createRequire } from "module";
+import type { LexiconPlugin, IntrinsicDef, InitTemplateSet } from "@intentius/chant/lexicon";
+const require = createRequire(import.meta.url);
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { dockerSerializer } from "./serializer";
+
+export const dockerPlugin: LexiconPlugin = {
+  name: "docker",
+  serializer: dockerSerializer,
+
+  lintRules(): LintRule[] {
+    const { noLatestTagRule } = require("./lint/rules/no-latest-tag");
+    return [noLatestTagRule];
+  },
+
+  postSynthChecks() {
+    const postSynthDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "post-synth");
+    return discoverPostSynthChecks(postSynthDir, import.meta.url);
+  },
+
+  intrinsics(): IntrinsicDef[] {
+    return [
+      {
+        name: "env",
+        description: "Docker Compose variable interpolation — ${VAR}, ${VAR:-default}, ${VAR:?error}",
+        outputKey: "env",
+        isTag: false,
+      },
+    ];
+  },
+
+  initTemplates(template?: string): InitTemplateSet {
+    if (template === "webapp") {
+      return {
+        src: {
+          "compose.ts": `import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const db = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: "secret",
+  },
+  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"],
+  environment: {
+    DATABASE_URL: "postgresql://myapp:secret@db:5432/myapp",
+  },
+});
+`,
+        },
+      };
+    }
+
+    // Default template
+    return {
+      src: {
+        "compose.ts": `import { Service } from "@intentius/chant-lexicon-docker";
+
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  restart: "unless-stopped",
+});
+`,
+      },
+    };
+  },
+
+  detectTemplate(data: unknown): boolean {
+    if (typeof data !== "object" || data === null) return false;
+    const obj = data as Record<string, unknown>;
+    // Docker Compose files have a services: key
+    return "services" in obj;
+  },
+
+  completionProvider(ctx: import("@intentius/chant/lsp/types").CompletionContext) {
+    const { dockerCompletions } = require("./lsp/completions");
+    return dockerCompletions(ctx);
+  },
+
+  hoverProvider(ctx: import("@intentius/chant/lsp/types").HoverContext) {
+    const { dockerHover } = require("./lsp/hover");
+    return dockerHover(ctx);
+  },
+
+  templateParser() {
+    const { DockerParser } = require("./import/parser");
+    return new DockerParser();
+  },
+
+  templateGenerator() {
+    const { DockerGenerator } = require("./import/generator");
+    return new DockerGenerator();
+  },
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { dirname: pathDirname } = await import("path");
+    const { fileURLToPath: urlToPath } = await import("url");
+
+    const result = await generate({ verbose: options?.verbose ?? true });
+    const pkgDir = pathDirname(pathDirname(urlToPath(import.meta.url)));
+    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`);
+    }
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeDockerCoverage } = await import("./coverage");
+    await analyzeDockerCoverage({
+      verbose: options?.verbose,
+      minOverall: options?.minOverall,
+    });
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join: pathJoin, dirname: pathDirname } = await import("path");
+    const { fileURLToPath: urlToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+
+    const pkgDir = pathDirname(pathDirname(urlToPath(import.meta.url)));
+    const distDir = pathJoin(pkgDir, "dist");
+    writeBundleSpec(spec, distDir);
+
+    console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  mcpTools() {
+    return [createDiffTool(dockerSerializer, "Compare current build output against previous output for Docker Compose")];
+  },
+
+  mcpResources() {
+    return [
+      createCatalogResource(import.meta.url, "Docker Entity Catalog", "JSON list of all supported Docker entity types", "lexicon-docker.json"),
+      {
+        uri: "examples/basic-app",
+        name: "Basic App Example",
+        description: "A basic Docker Compose application with a service and volume",
+        mimeType: "text/typescript",
+        async handler(): Promise<string> {
+          return `import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const db = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: "secret",
+  },
+  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"],
+});
+`;
+        },
+      },
+    ];
+  },
+
+  async docs(options?: { verbose?: boolean }): Promise<void> {
+    const { generateDocs } = await import("./codegen/docs");
+    await generateDocs(options);
+  },
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-docker.md",
+      name: "chant-docker",
+      description: "Docker Compose service/volume/network lifecycle — build, serialize, deploy",
+      triggers: [
+        { type: "file-pattern", value: "**/*.compose.ts" },
+        { type: "file-pattern", value: "**/docker-compose.ts" },
+        { type: "context", value: "docker compose" },
+        { type: "context", value: "docker service" },
+        { type: "context", value: "dockerfile" },
+        { type: "context", value: "container" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Basic service with database",
+          description: "Create a web service and PostgreSQL database",
+          input: "Create a Node.js API with a PostgreSQL database",
+          output: `new Service({ image: "myapi:1.0", depends_on: ["db"] })`,
+        },
+      ],
+    },
+    {
+      file: "chant-docker-patterns.md",
+      name: "chant-docker-patterns",
+      description: "Docker Compose patterns — databases, caches, networks, multi-stage builds",
+      triggers: [
+        { type: "context", value: "docker compose" },
+        { type: "context", value: "multi-stage" },
+        { type: "context", value: "dockerfile pattern" },
+        { type: "context", value: "docker network" },
+        { type: "context", value: "docker volume" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Multi-stage Dockerfile",
+          input: "Create a multi-stage Dockerfile for Node.js",
+          output: `new Dockerfile({ stages: [{ from: "node:20-alpine", as: "build", ... }] })`,
+        },
+      ],
+    },
+  ]),
+};

package/src/serializer.test.ts

@@ -0,0 +1,294 @@
+import { describe, test, expect } from "bun:test";
+import { dockerSerializer } from "./serializer";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+// ── Mock entities ──────────────────────────────────────────────────
+
+class MockService implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::Compose::Service";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockVolume implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::Compose::Volume";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockNetwork implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::Compose::Network";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockDockerfile implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::Dockerfile";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockPropertyDeclarable implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::Compose::HealthCheck";
+  readonly kind = "property" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockDefaultLabels implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly [Symbol.for("docker.defaultLabels")] = true as const;
+  readonly lexicon = "docker";
+  readonly entityType = "Docker::DefaultLabels";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+// ── Identity tests ─────────────────────────────────────────────────
+
+describe("dockerSerializer", () => {
+  test("has correct name", () => {
+    expect(dockerSerializer.name).toBe("docker");
+  });
+
+  test("has correct rulePrefix", () => {
+    expect(dockerSerializer.rulePrefix).toBe("DKR");
+  });
+});
+
+// ── Empty input ────────────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — empty", () => {
+  test("returns newline for empty entities", () => {
+    const output = dockerSerializer.serialize(new Map());
+    expect(output).toBe("\n");
+  });
+});
+
+// ── Single service ─────────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — single service", () => {
+  test("serializes one service with image", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: "nginx:1.25" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).toContain("services:");
+    expect(output).toContain("api:");
+    expect(output).toContain("image: nginx:1.25");
+  });
+
+  test("omits null/undefined properties", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: "nginx", restart: undefined }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).not.toContain("restart:");
+  });
+});
+
+// ── Multi-resource ────────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — multi-resource", () => {
+  test("serializes services, volumes, networks in order", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: "myapp:latest" }));
+    entities.set("data", new MockVolume({}));
+    entities.set("frontend", new MockNetwork({}));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).toContain("services:");
+    expect(output).toContain("volumes:");
+    expect(output).toContain("networks:");
+
+    const servicesIdx = output.indexOf("services:");
+    const volumesIdx = output.indexOf("volumes:");
+    const networksIdx = output.indexOf("networks:");
+    expect(servicesIdx).toBeLessThan(volumesIdx);
+    expect(volumesIdx).toBeLessThan(networksIdx);
+  });
+});
+
+// ── Dockerfile emission ───────────────────────────────────────────
+
+describe("dockerSerializer.serialize — Dockerfile", () => {
+  test("emits Dockerfile.{name} in SerializerResult", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: "myapp:latest" }));
+    entities.set("api", new MockService({
+      build: { dockerfile: "Dockerfile.builder" },
+    }));
+    entities.set("builder", new MockDockerfile({
+      from: "node:20-alpine",
+      run: ["npm ci", "npm run build"],
+      cmd: `["node", "dist/index.js"]`,
+    }));
+
+    const output = dockerSerializer.serialize(entities);
+    expect(typeof output).toBe("object");
+    const result = output as { primary: string; files: Record<string, string> };
+    expect(result.files).toBeDefined();
+    expect(result.files["Dockerfile.builder"]).toBeDefined();
+    expect(result.files["Dockerfile.builder"]).toContain("FROM node:20-alpine");
+    expect(result.files["Dockerfile.builder"]).toContain("RUN npm ci");
+  });
+
+  test("primary contains compose YAML when Dockerfile present", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("web", new MockService({ image: "nginx" }));
+    entities.set("builder", new MockDockerfile({ from: "node:20" }));
+
+    const result = dockerSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
+    expect(result.primary).toContain("services:");
+    expect(result.primary).toContain("web:");
+  });
+
+  test("returns string (no SerializerResult) when no Dockerfile entities", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("web", new MockService({ image: "nginx" }));
+
+    const output = dockerSerializer.serialize(entities);
+    expect(typeof output).toBe("string");
+  });
+});
+
+// ── Default labels ────────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — default labels", () => {
+  test("merges default labels into every service", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("labels", new MockDefaultLabels({ labels: { "app.team": "platform" } }));
+    entities.set("api", new MockService({ image: "myapp:1.0" }));
+    entities.set("worker", new MockService({ image: "myworker:1.0" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).toContain("app.team: platform");
+  });
+
+  test("default labels are not emitted as a top-level key", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("labels", new MockDefaultLabels({ labels: { "app.team": "platform" } }));
+    entities.set("api", new MockService({ image: "myapp:1.0" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).not.toContain("Docker::DefaultLabels");
+  });
+});
+
+// ── Property kind skipping ─────────────────────────────────────────
+
+describe("dockerSerializer.serialize — property skipping", () => {
+  test("skips entities with kind=property", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: "myapp:1.0" }));
+    entities.set("hc", new MockPropertyDeclarable({ test: "curl -f http://localhost" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    // Property entities should not appear as top-level services
+    expect(output).not.toContain("Docker::Compose::HealthCheck");
+  });
+});
+
+// ── Key order ────────────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — key order", () => {
+  test("services appears before volumes appears before networks", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("net", new MockNetwork({ driver: "bridge" }));
+    entities.set("vol", new MockVolume({ driver: "local" }));
+    entities.set("svc", new MockService({ image: "nginx" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    const svcIdx = output.indexOf("services:");
+    const volIdx = output.indexOf("volumes:");
+    const netIdx = output.indexOf("networks:");
+
+    expect(svcIdx).toBeLessThan(volIdx);
+    expect(volIdx).toBeLessThan(netIdx);
+  });
+});
+
+// ── Intrinsic serialization ───────────────────────────────────────
+
+describe("dockerSerializer.serialize — intrinsics", () => {
+  test("serializes env() intrinsic to ${VAR} string", () => {
+    const mockEnvIntrinsic = {
+      [INTRINSIC_MARKER]: true,
+      toJSON: () => "${APP_IMAGE:-myapp:latest}",
+      toString: () => "${APP_IMAGE:-myapp:latest}",
+    };
+
+    const entities = new Map<string, Declarable>();
+    entities.set("api", new MockService({ image: mockEnvIntrinsic }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).toContain("${APP_IMAGE:-myapp:latest}");
+  });
+});
+
+// ── Multi-stage Dockerfile ────────────────────────────────────────
+
+describe("dockerSerializer.serialize — multi-stage Dockerfile", () => {
+  test("emits multiple FROM instructions for stages", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("app", new MockDockerfile({
+      stages: [
+        { from: "node:20-alpine", as: "builder", run: ["npm ci", "npm run build"] },
+        { from: "nginx:alpine", copy: ["--from=builder /app/dist /usr/share/nginx/html"] },
+      ],
+    }));
+
+    const output = dockerSerializer.serialize(entities);
+    const result = output as { primary: string; files: Record<string, string> };
+    const dockerfile = result.files["Dockerfile.app"];
+    expect(dockerfile).toContain("FROM node:20-alpine AS builder");
+    expect(dockerfile).toContain("FROM nginx:alpine");
+    expect(dockerfile).toContain("RUN npm ci");
+  });
+});
+
+// ── Name generation ───────────────────────────────────────────────
+
+describe("dockerSerializer.serialize — name gen", () => {
+  test("uses export name as service key", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("myWebServer", new MockService({ image: "nginx" }));
+
+    const output = dockerSerializer.serialize(entities) as string;
+    expect(output).toContain("myWebServer:");
+  });
+});