@intentius/chant-lexicon-docker 0.1.0

package/src/import/generator.ts

@@ -0,0 +1,127 @@
+/**
+ * Docker IR → TypeScript source generator.
+ *
+ * Converts parsed IR to valid chant TypeScript source code.
+ */
+
+import type { DockerIR, ServiceIR, VolumeIR, NetworkIR, ConfigIR, SecretIR, DockerfileIR } from "./parser";
+
+export interface GenerateResult {
+  source: string;
+  warnings: string[];
+}
+
+/**
+ * Generator for Docker entities — IR → TypeScript chant source.
+ */
+export class DockerGenerator {
+  generate(entities: DockerIR[]): GenerateResult {
+    const warnings: string[] = [];
+    const imports = new Set<string>();
+    const lines: string[] = [];
+
+    for (const entity of entities) {
+      switch (entity.kind) {
+        case "service":
+          imports.add("Service");
+          lines.push(generateService(entity));
+          break;
+        case "volume":
+          imports.add("Volume");
+          lines.push(generateVolume(entity));
+          break;
+        case "network":
+          imports.add("Network");
+          lines.push(generateNetwork(entity));
+          break;
+        case "config":
+          imports.add("Config");
+          lines.push(generateConfig(entity));
+          break;
+        case "secret":
+          imports.add("Secret");
+          lines.push(generateSecret(entity));
+          break;
+        case "dockerfile":
+          imports.add("Dockerfile");
+          lines.push(generateDockerfile(entity));
+          break;
+      }
+    }
+
+    const importLine = `import { ${[...imports].sort().join(", ")} } from "@intentius/chant-lexicon-docker";`;
+    const source = [importLine, "", ...lines].join("\n");
+
+    return { source, warnings };
+  }
+}
+
+function generateService(svc: ServiceIR): string {
+  const propsStr = JSON.stringify(svc.props, null, 2)
+    .replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
+  return `export const ${sanitizeName(svc.name)} = new Service(${propsStr});`;
+}
+
+function generateVolume(vol: VolumeIR): string {
+  const hasProps = Object.keys(vol.props).length > 0;
+  return `export const ${sanitizeName(vol.name)} = new Volume(${hasProps ? JSON.stringify(vol.props) : "{}"});`;
+}
+
+function generateNetwork(net: NetworkIR): string {
+  const hasProps = Object.keys(net.props).length > 0;
+  return `export const ${sanitizeName(net.name)} = new Network(${hasProps ? JSON.stringify(net.props) : "{}"});`;
+}
+
+function generateConfig(cfg: ConfigIR): string {
+  const hasProps = Object.keys(cfg.props).length > 0;
+  return `export const ${sanitizeName(cfg.name)} = new Config(${hasProps ? JSON.stringify(cfg.props) : "{}"});`;
+}
+
+function generateSecret(sec: SecretIR): string {
+  const hasProps = Object.keys(sec.props).length > 0;
+  return `export const ${sanitizeName(sec.name)} = new Secret(${hasProps ? JSON.stringify(sec.props) : "{}"});`;
+}
+
+function generateDockerfile(df: DockerfileIR): string {
+  if (df.stages.length > 1) {
+    // Multi-stage: emit stages array
+    const props = { stages: df.stages };
+    const propsStr = JSON.stringify(props, null, 2).replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
+    return `export const ${sanitizeName(df.name)} = new Dockerfile(${propsStr});`;
+  }
+
+  // Single-stage: flat props (preserved behaviour)
+  const stage = df.stages[0];
+  const props: Record<string, unknown> = {};
+  if (stage) props.from = stage.from;
+
+  // Group instructions by type
+  const grouped: Record<string, string[]> = {};
+  for (const { instruction, value } of stage?.instructions ?? []) {
+    const key = instruction.toLowerCase();
+    if (!grouped[key]) grouped[key] = [];
+    grouped[key].push(value);
+  }
+
+  // Single-value instructions
+  for (const single of ["workdir", "user", "entrypoint", "cmd", "healthcheck"]) {
+    if (grouped[single]?.length === 1) {
+      props[single] = grouped[single][0];
+    }
+  }
+
+  // Multi-value instructions
+  for (const multi of ["run", "copy", "add", "env", "arg", "expose", "volume", "label"]) {
+    if (grouped[multi]?.length) {
+      props[multi] = grouped[multi].length === 1 ? grouped[multi] : grouped[multi];
+    }
+  }
+
+  const propsStr = JSON.stringify(props, null, 2).replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
+  return `export const ${sanitizeName(df.name)} = new Dockerfile(${propsStr});`;
+}
+
+function sanitizeName(name: string): string {
+  // Convert kebab/snake to camelCase
+  return name.replace(/[-_]([a-z])/g, (_, c) => c.toUpperCase());
+}

package/src/import/parser.test.ts

@@ -0,0 +1,137 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { DockerParser, DockerfileParser } from "./parser";
+
+const testdata = (file: string) =>
+  readFileSync(join(import.meta.dir, "testdata", file), "utf8");
+
+describe("DockerParser — services", () => {
+  test("image extracted correctly", () => {
+    const yaml = `services:\n  api:\n    image: nginx:1.25\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "api");
+    expect(svc?.kind).toBe("service");
+    expect((svc?.props as any).image).toBe("nginx:1.25");
+  });
+
+  test("ports array preserved", () => {
+    const yaml = `services:\n  web:\n    image: nginx:1.25\n    ports:\n      - "80:80"\n      - "443:443"\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "web");
+    expect((svc?.props as any).ports).toEqual(["80:80", "443:443"]);
+  });
+
+  test("environment map preserved", () => {
+    const yaml = `services:\n  app:\n    image: node:20\n    environment:\n      NODE_ENV: production\n      PORT: "3000"\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "app");
+    expect((svc?.props as any).environment).toEqual({ NODE_ENV: "production", PORT: "3000" });
+  });
+
+  test("volumes list preserved", () => {
+    const yaml = `services:\n  db:\n    image: postgres:16\n    volumes:\n      - "pg-data:/var/lib/postgresql/data"\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "db");
+    expect((svc?.props as any).volumes).toEqual(["pg-data:/var/lib/postgresql/data"]);
+  });
+
+  test("depends_on list preserved", () => {
+    const yaml = `services:\n  api:\n    image: node:20\n    depends_on:\n      - db\n      - cache\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "api");
+    expect((svc?.props as any).depends_on).toEqual(["db", "cache"]);
+  });
+
+  test("restart string preserved", () => {
+    const yaml = `services:\n  app:\n    image: myapp:latest\n    restart: unless-stopped\n`;
+    const { entities } = new DockerParser().parse(yaml);
+    const svc = entities.find((e) => e.name === "app");
+    expect((svc?.props as any).restart).toBe("unless-stopped");
+  });
+
+  test("healthcheck object preserved", () => {
+    const { entities } = new DockerParser().parse(testdata("webapp.yaml"));
+    const svc = entities.find((e) => e.name === "api");
+    const hc = (svc?.props as any).healthcheck;
+    expect(hc).toBeDefined();
+    expect(hc.interval).toBe("30s");
+    expect(hc.retries).toBe(3);
+  });
+});
+
+describe("DockerParser — top-level sections", () => {
+  test("top-level volumes: section → VolumeIR entities", () => {
+    const { entities } = new DockerParser().parse(testdata("simple.yaml"));
+    const vol = entities.find((e) => e.kind === "volume" && e.name === "webdata");
+    expect(vol).toBeDefined();
+    expect((vol?.props as any).driver).toBe("local");
+  });
+
+  test("top-level networks: section → NetworkIR entities", () => {
+    const { entities } = new DockerParser().parse(testdata("full.yaml"));
+    const net = entities.find((e) => e.kind === "network" && e.name === "backend");
+    expect(net).toBeDefined();
+    expect((net?.props as any).driver).toBe("bridge");
+  });
+
+  test("top-level configs: section → ConfigIR entities", () => {
+    const { entities } = new DockerParser().parse(testdata("full.yaml"));
+    const cfg = entities.find((e) => e.kind === "config" && e.name === "app-config");
+    expect(cfg).toBeDefined();
+    expect((cfg?.props as any).file).toBe("./config/app.conf");
+  });
+
+  test("top-level secrets: section → SecretIR entities", () => {
+    const { entities } = new DockerParser().parse(testdata("full.yaml"));
+    const sec = entities.find((e) => e.kind === "secret" && e.name === "db-password");
+    expect(sec).toBeDefined();
+    expect((sec?.props as any).file).toBe("./secrets/db-password.txt");
+  });
+
+  test("returns empty entities for empty compose", () => {
+    const result = new DockerParser().parse("");
+    expect(result.entities).toHaveLength(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+});
+
+describe("DockerfileParser", () => {
+  test("single-stage: stages[0].from correct", () => {
+    const content = `FROM node:20-alpine\nRUN npm ci\nCMD ["node", "index.js"]\n`;
+    const result = new DockerfileParser().parse("builder", content);
+    expect(result.kind).toBe("dockerfile");
+    expect(result.stages).toHaveLength(1);
+    expect(result.stages[0].from).toBe("node:20-alpine");
+  });
+
+  test("multi-stage: two stages with correct from/as", () => {
+    const content = [
+      "FROM node:20-alpine AS builder",
+      "RUN npm ci",
+      "FROM nginx:1.25 AS runner",
+      "COPY --from=builder /app/dist /usr/share/nginx/html",
+    ].join("\n");
+    const result = new DockerfileParser().parse("app", content);
+    expect(result.stages).toHaveLength(2);
+    expect(result.stages[0].from).toBe("node:20-alpine");
+    expect(result.stages[0].as).toBe("builder");
+    expect(result.stages[1].from).toBe("nginx:1.25");
+    expect(result.stages[1].as).toBe("runner");
+  });
+
+  test("parses multiple instructions within a stage", () => {
+    const content = `FROM ubuntu:22.04\nRUN apt-get update\nCOPY . /app\nWORKDIR /app\n`;
+    const result = new DockerfileParser().parse("app", content);
+    expect(result.stages[0].instructions.length).toBeGreaterThanOrEqual(2);
+    const runInstr = result.stages[0].instructions.find((i) => i.instruction === "RUN");
+    expect(runInstr?.value).toBe("apt-get update");
+  });
+
+  test("skips comments and blank lines", () => {
+    const content = `# This is a comment\nFROM alpine:3.18\n\n# Another comment\nRUN echo hello\n`;
+    const result = new DockerfileParser().parse("test", content);
+    expect(result.stages[0].from).toBe("alpine:3.18");
+    expect(result.stages[0].instructions).toHaveLength(1);
+  });
+});

package/src/import/parser.ts

@@ -0,0 +1,190 @@
+/**
+ * Docker Compose + Dockerfile parser — converts existing YAML/Dockerfiles
+ * to an intermediate representation (IR) for TypeScript code generation.
+ */
+
+import { parseYAML } from "@intentius/chant/yaml";
+
+export interface ServiceIR {
+  kind: "service";
+  name: string;
+  props: Record<string, unknown>;
+}
+
+export interface VolumeIR {
+  kind: "volume";
+  name: string;
+  props: Record<string, unknown>;
+}
+
+export interface NetworkIR {
+  kind: "network";
+  name: string;
+  props: Record<string, unknown>;
+}
+
+export interface ConfigIR {
+  kind: "config";
+  name: string;
+  props: Record<string, unknown>;
+}
+
+export interface SecretIR {
+  kind: "secret";
+  name: string;
+  props: Record<string, unknown>;
+}
+
+export interface DockerfileStage {
+  from: string;
+  as?: string;
+  instructions: Array<{ instruction: string; value: string }>;
+}
+
+export interface DockerfileIR {
+  kind: "dockerfile";
+  name: string;
+  stages: DockerfileStage[];
+}
+
+export type DockerIR = ServiceIR | VolumeIR | NetworkIR | ConfigIR | SecretIR | DockerfileIR;
+
+export interface ParseResult {
+  entities: DockerIR[];
+  warnings: string[];
+}
+
+const SERVICE_PROPS = [
+  "image", "ports", "environment", "volumes", "depends_on",
+  "restart", "healthcheck", "labels", "command", "entrypoint",
+  "networks", "build", "deploy", "secrets", "configs",
+] as const;
+
+const VOLUME_PROPS = ["driver", "driver_opts", "external", "labels"] as const;
+const NETWORK_PROPS = ["driver", "external", "attachable", "labels"] as const;
+const CONFIG_PROPS = ["file", "external"] as const;
+const SECRET_PROPS = ["file", "external"] as const;
+
+function extractProps(
+  raw: unknown,
+  allowed: readonly string[],
+): Record<string, unknown> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const obj = raw as Record<string, unknown>;
+  const props: Record<string, unknown> = {};
+  for (const key of allowed) {
+    if (key in obj) props[key] = obj[key];
+  }
+  return props;
+}
+
+/**
+ * Parser for docker-compose.yml files.
+ * Converts YAML to an IR consumable by the TypeScript generator.
+ */
+export class DockerParser {
+  parse(content: string): ParseResult {
+    if (!content.trim()) return { entities: [], warnings: [] };
+
+    const entities: DockerIR[] = [];
+    const warnings: string[] = [];
+    const doc = parseYAML(content) as Record<string, unknown>;
+
+    // services
+    const services = doc["services"];
+    if (services && typeof services === "object" && !Array.isArray(services)) {
+      for (const [name, raw] of Object.entries(services as Record<string, unknown>)) {
+        entities.push({
+          kind: "service",
+          name,
+          props: extractProps(raw, SERVICE_PROPS),
+        });
+      }
+    }
+
+    // volumes
+    const volumes = doc["volumes"];
+    if (volumes && typeof volumes === "object" && !Array.isArray(volumes)) {
+      for (const [name, raw] of Object.entries(volumes as Record<string, unknown>)) {
+        entities.push({
+          kind: "volume",
+          name,
+          props: extractProps(raw, VOLUME_PROPS),
+        });
+      }
+    }
+
+    // networks
+    const networks = doc["networks"];
+    if (networks && typeof networks === "object" && !Array.isArray(networks)) {
+      for (const [name, raw] of Object.entries(networks as Record<string, unknown>)) {
+        entities.push({
+          kind: "network",
+          name,
+          props: extractProps(raw, NETWORK_PROPS),
+        });
+      }
+    }
+
+    // configs
+    const configs = doc["configs"];
+    if (configs && typeof configs === "object" && !Array.isArray(configs)) {
+      for (const [name, raw] of Object.entries(configs as Record<string, unknown>)) {
+        entities.push({
+          kind: "config",
+          name,
+          props: extractProps(raw, CONFIG_PROPS),
+        });
+      }
+    }
+
+    // secrets
+    const secrets = doc["secrets"];
+    if (secrets && typeof secrets === "object" && !Array.isArray(secrets)) {
+      for (const [name, raw] of Object.entries(secrets as Record<string, unknown>)) {
+        entities.push({
+          kind: "secret",
+          name,
+          props: extractProps(raw, SECRET_PROPS),
+        });
+      }
+    }
+
+    return { entities, warnings };
+  }
+}
+
+/**
+ * Parser for Dockerfile content.
+ */
+export class DockerfileParser {
+  parse(name: string, content: string): DockerfileIR {
+    const stages: DockerfileStage[] = [];
+    let current: DockerfileStage | null = null;
+
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+
+      const match = trimmed.match(/^([A-Z]+)\s+([\s\S]+)$/);
+      if (!match) continue;
+
+      const [, instruction, value] = match;
+
+      if (instruction === "FROM") {
+        // Parse "FROM image AS stagename"
+        const asMatch = value.match(/^(.+?)\s+[Aa][Ss]\s+(\S+)$/);
+        if (asMatch) {
+          current = { from: asMatch[1].trim(), as: asMatch[2].trim(), instructions: [] };
+        } else {
+          current = { from: value.trim(), instructions: [] };
+        }
+        stages.push(current);
+      } else if (current) {
+        current.instructions.push({ instruction, value: value.trim() });
+      }
+    }
+
+    return { kind: "dockerfile", name, stages };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { DockerParser, DockerfileParser } from "./parser";
+import { DockerGenerator } from "./generator";
+
+const testdata = (file: string) =>
+  readFileSync(join(import.meta.dir, "testdata", file), "utf8");
+
+describe("roundtrip: parse → generate", () => {
+  test("simple.yaml → Service + Volume constructors", () => {
+    const { entities } = new DockerParser().parse(testdata("simple.yaml"));
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("new Service(");
+    expect(source).toContain("new Volume(");
+    expect(source).toContain("nginx:1.25");
+  });
+
+  test("webapp.yaml → ports / healthcheck / depends_on survive roundtrip", () => {
+    const { entities } = new DockerParser().parse(testdata("webapp.yaml"));
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("3000:3000");
+    expect(source).toContain("depends_on");
+    expect(source).toContain("healthcheck");
+    expect(source).toContain("unless-stopped");
+  });
+
+  test("full.yaml → Config / Secret / Network constructors present", () => {
+    const { entities } = new DockerParser().parse(testdata("full.yaml"));
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("new Config(");
+    expect(source).toContain("new Secret(");
+    expect(source).toContain("new Network(");
+  });
+
+  test("multi-stage Dockerfile inline → stages: in output", () => {
+    const content = [
+      "FROM node:20-alpine AS builder",
+      "RUN npm ci",
+      "FROM nginx:1.25 AS runner",
+      "COPY --from=builder /app/dist /usr/share/nginx/html",
+    ].join("\n");
+    const entity = new DockerfileParser().parse("app", content);
+    const { source } = new DockerGenerator().generate([entity]);
+    expect(source).toContain("stages");
+    expect(source).toContain("node:20-alpine");
+    expect(source).toContain("nginx:1.25");
+  });
+});

package/src/import/testdata/full.yaml

@@ -0,0 +1,43 @@
+services:
+  app:
+    image: myapp:latest
+    ports:
+      - "8080:8080"
+    environment:
+      DB_URL: postgres://db:5432/mydb
+    networks:
+      - frontend
+      - backend
+    secrets:
+      - db-password
+    configs:
+      - app-config
+
+  db:
+    image: postgres:16
+    networks:
+      - backend
+
+volumes:
+  db-data:
+    driver: local
+  app-uploads:
+    driver: local
+    driver_opts:
+      type: nfs
+      o: addr=10.0.0.1,rw
+
+networks:
+  frontend:
+    driver: bridge
+  backend:
+    driver: bridge
+    internal: true
+
+configs:
+  app-config:
+    file: ./config/app.conf
+
+secrets:
+  db-password:
+    file: ./secrets/db-password.txt

package/src/import/testdata/simple.yaml

@@ -0,0 +1,9 @@
+services:
+  web:
+    image: nginx:1.25
+    ports:
+      - "80:80"
+
+volumes:
+  webdata:
+    driver: local

package/src/import/testdata/webapp.yaml

@@ -0,0 +1,41 @@
+services:
+  api:
+    image: node:20-alpine
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: production
+      PORT: "3000"
+    depends_on:
+      - db
+      - cache
+    restart: unless-stopped
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -f
+        - http://localhost:3000/health
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    volumes:
+      - "app-data:/data"
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: appdb
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: secret
+    volumes:
+      - "pg-data:/var/lib/postgresql/data"
+
+  cache:
+    image: redis:7-alpine
+    restart: always
+
+volumes:
+  app-data:
+  pg-data:
+    driver: local

package/src/index.ts

@@ -0,0 +1,29 @@
+// Serializer
+export { dockerSerializer } from "./serializer";
+
+// Plugin
+export { dockerPlugin } from "./plugin";
+
+// Interpolation intrinsic
+export { env } from "./interpolation";
+export type { EnvOptions, EnvIntrinsic } from "./interpolation";
+
+// Context variables
+export { DOCKER_VARS, COMPOSE_VARS } from "./variables";
+export type { DockerVar, ComposeVar } from "./variables";
+
+// Default labels
+export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotations } from "./default-labels";
+export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-labels";
+export type { DefaultLabels, DefaultAnnotations } from "./default-labels";
+
+// Generated entities — populated by `bun run generate`
+export * from "./generated/index";
+
+// Composites (to be added in Tier 2)
+// export * from "./composites/index";
+
+// Codegen pipeline (for external tooling)
+export { generate, writeGeneratedFiles } from "./codegen/generate";
+export { packageLexicon } from "./codegen/package";
+export type { PackageOptions, PackageResult } from "./codegen/package";

package/src/interpolation.test.ts

@@ -0,0 +1,41 @@
+import { describe, test, expect } from "bun:test";
+import { env } from "./interpolation";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+describe("env()", () => {
+  test("bare variable: ${VAR}", () => {
+    const e = env("APP_IMAGE");
+    expect(e.toJSON()).toBe("${APP_IMAGE}");
+    expect(e.toString()).toBe("${APP_IMAGE}");
+  });
+
+  test("default value: ${VAR:-default}", () => {
+    const e = env("APP_IMAGE", { default: "myapp:latest" });
+    expect(e.toJSON()).toBe("${APP_IMAGE:-myapp:latest}");
+  });
+
+  test("required variable: ${VAR:?error}", () => {
+    const e = env("DB_URL", { required: true });
+    expect(e.toJSON()).toBe("${DB_URL:?DB_URL is required}");
+  });
+
+  test("required with custom error message: ${VAR:?msg}", () => {
+    const e = env("DB_URL", { errorMessage: "Database URL must be set" });
+    expect(e.toJSON()).toBe("${DB_URL:?Database URL must be set}");
+  });
+
+  test("ifSet: ${VAR:+value}", () => {
+    const e = env("DEBUG", { ifSet: "true" });
+    expect(e.toJSON()).toBe("${DEBUG:+true}");
+  });
+
+  test("ifSet takes precedence over default", () => {
+    const e = env("X", { ifSet: "on", default: "off" });
+    expect(e.toJSON()).toBe("${X:+on}");
+  });
+
+  test("has INTRINSIC_MARKER", () => {
+    const e = env("FOO");
+    expect(INTRINSIC_MARKER in e).toBe(true);
+  });
+});