@intentius/chant-lexicon-docker 0.1.0

package/src/default-labels.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import {
+  DEFAULT_LABELS_MARKER,
+  DEFAULT_ANNOTATIONS_MARKER,
+  defaultLabels,
+  defaultAnnotations,
+  isDefaultLabels,
+  isDefaultAnnotations,
+} from "./default-labels";
+
+describe("DEFAULT_LABELS_MARKER", () => {
+  test("is a well-known symbol", () => {
+    expect(typeof DEFAULT_LABELS_MARKER).toBe("symbol");
+    expect(DEFAULT_LABELS_MARKER.toString()).toContain("docker.defaultLabels");
+  });
+});
+
+describe("DEFAULT_ANNOTATIONS_MARKER", () => {
+  test("is a well-known symbol", () => {
+    expect(typeof DEFAULT_ANNOTATIONS_MARKER).toBe("symbol");
+    expect(DEFAULT_ANNOTATIONS_MARKER.toString()).toContain("docker.defaultAnnotations");
+  });
+});
+
+describe("defaultLabels", () => {
+  test("creates a DefaultLabels entity", () => {
+    const labels = { "app.team": "platform", "app.managed-by": "chant" };
+    const entity = defaultLabels(labels);
+
+    expect(entity.lexicon).toBe("docker");
+    expect(entity.entityType).toBe("Docker::DefaultLabels");
+    expect(entity.props.labels).toEqual(labels);
+  });
+
+  test("has DEFAULT_LABELS_MARKER", () => {
+    const entity = defaultLabels({ "x": "y" });
+    expect(DEFAULT_LABELS_MARKER in entity).toBe(true);
+  });
+});
+
+describe("defaultAnnotations", () => {
+  test("creates a DefaultAnnotations entity", () => {
+    const annotations = { "app.version": "1.0.0" };
+    const entity = defaultAnnotations(annotations);
+
+    expect(entity.lexicon).toBe("docker");
+    expect(entity.entityType).toBe("Docker::DefaultAnnotations");
+    expect(entity.props.annotations).toEqual(annotations);
+  });
+
+  test("has DEFAULT_ANNOTATIONS_MARKER", () => {
+    const entity = defaultAnnotations({ "x": "y" });
+    expect(DEFAULT_ANNOTATIONS_MARKER in entity).toBe(true);
+  });
+});
+
+describe("isDefaultLabels", () => {
+  test("returns true for defaultLabels entity", () => {
+    const entity = defaultLabels({ "x": "y" });
+    expect(isDefaultLabels(entity)).toBe(true);
+  });
+
+  test("returns false for plain objects", () => {
+    expect(isDefaultLabels({})).toBe(false);
+    expect(isDefaultLabels(null)).toBe(false);
+    expect(isDefaultLabels("string")).toBe(false);
+  });
+});
+
+describe("isDefaultAnnotations", () => {
+  test("returns true for defaultAnnotations entity", () => {
+    const entity = defaultAnnotations({ "x": "y" });
+    expect(isDefaultAnnotations(entity)).toBe(true);
+  });
+
+  test("returns false for defaultLabels", () => {
+    const entity = defaultLabels({ "x": "y" });
+    expect(isDefaultAnnotations(entity)).toBe(false);
+  });
+
+  test("returns false for plain objects", () => {
+    expect(isDefaultAnnotations({})).toBe(false);
+    expect(isDefaultAnnotations(null)).toBe(false);
+  });
+});

package/src/default-labels.ts

@@ -0,0 +1,72 @@
+/**
+ * Default labels for Docker Compose services.
+ *
+ * Follows the K8s lexicon pattern for defaultLabels/defaultAnnotations.
+ * The serializer merges these into every Compose service's labels map.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+
+export const DEFAULT_LABELS_MARKER = Symbol.for("docker.defaultLabels");
+export const DEFAULT_ANNOTATIONS_MARKER = Symbol.for("docker.defaultAnnotations");
+
+export interface DefaultLabels extends Declarable {
+  readonly [DEFAULT_LABELS_MARKER]: true;
+  readonly props: { labels: Record<string, string> };
+}
+
+export interface DefaultAnnotations extends Declarable {
+  readonly [DEFAULT_ANNOTATIONS_MARKER]: true;
+  readonly props: { annotations: Record<string, string> };
+}
+
+export function isDefaultLabels(value: unknown): value is DefaultLabels {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DEFAULT_LABELS_MARKER in value
+  );
+}
+
+export function isDefaultAnnotations(value: unknown): value is DefaultAnnotations {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DEFAULT_ANNOTATIONS_MARKER in value
+  );
+}
+
+/**
+ * Create a DefaultLabels entity that the serializer will merge into all services.
+ *
+ * @example
+ * export const labels = defaultLabels({
+ *   "com.example.team": "platform",
+ *   "com.example.managed-by": "chant",
+ * });
+ */
+export function defaultLabels(labels: Record<string, string>): DefaultLabels {
+  return {
+    [DECLARABLE_MARKER]: true,
+    [DEFAULT_LABELS_MARKER]: true,
+    lexicon: "docker",
+    entityType: "Docker::DefaultLabels",
+    kind: "resource",
+    props: { labels },
+  };
+}
+
+/**
+ * Create a DefaultAnnotations entity.
+ * (Not used by Compose directly, but useful for Dockerfile LABEL instructions.)
+ */
+export function defaultAnnotations(annotations: Record<string, string>): DefaultAnnotations {
+  return {
+    [DECLARABLE_MARKER]: true,
+    [DEFAULT_ANNOTATIONS_MARKER]: true,
+    lexicon: "docker",
+    entityType: "Docker::DefaultAnnotations",
+    kind: "resource",
+    props: { annotations },
+  };
+}

package/src/generated/index.d.ts

@@ -0,0 +1,93 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { Declarable } from "@intentius/chant/declarable";
+
+export interface ServiceProps {
+  image?: string;
+  build?: object;
+  command?: string | string[];
+  entrypoint?: string | string[];
+  environment?: Record<string, string>;
+  ports?: string[];
+  volumes?: string[];
+  networks?: string[];
+  depends_on?: string[];
+  restart?: string;
+  labels?: Record<string, string>;
+  healthcheck?: object;
+  deploy?: object;
+  secrets?: string[];
+  configs?: string[];
+}
+export declare const Service: new (props?: ServiceProps) => Declarable;
+
+export interface VolumeProps {
+  driver?: string;
+  driver_opts?: Record<string, string>;
+  external?: boolean;
+  labels?: Record<string, string>;
+  name?: string;
+}
+export declare const Volume: new (props?: VolumeProps) => Declarable;
+
+export interface NetworkProps {
+  driver?: string;
+  driver_opts?: Record<string, string>;
+  external?: boolean;
+  labels?: Record<string, string>;
+  internal?: boolean;
+  ipam?: object;
+}
+export declare const Network: new (props?: NetworkProps) => Declarable;
+
+export interface DockerConfigProps {
+  file?: string;
+  external?: boolean;
+  labels?: Record<string, string>;
+  name?: string;
+}
+export declare const DockerConfig: new (props?: DockerConfigProps) => Declarable;
+
+export interface DockerSecretProps {
+  file?: string;
+  external?: boolean;
+  labels?: Record<string, string>;
+  name?: string;
+}
+export declare const DockerSecret: new (props?: DockerSecretProps) => Declarable;
+
+export interface DockerfileStage {
+  from: string;
+  as?: string;
+  arg?: string[];
+  env?: string[];
+  run?: string[];
+  copy?: string[];
+  add?: string[];
+  workdir?: string;
+  user?: string;
+  expose?: string[];
+  volume?: string[];
+  label?: string[];
+  entrypoint?: string;
+  cmd?: string;
+  healthcheck?: string;
+}
+export interface DockerfileProps {
+  name?: string;
+  from?: string;
+  stages?: DockerfileStage[];
+  arg?: string[];
+  env?: string[];
+  run?: string[];
+  copy?: string[];
+  add?: string[];
+  workdir?: string;
+  user?: string;
+  expose?: string[];
+  volume?: string[];
+  label?: string[];
+  entrypoint?: string;
+  cmd?: string;
+  healthcheck?: string;
+}
+export declare const Dockerfile: new (props?: DockerfileProps) => Declarable;

package/src/generated/index.ts

@@ -0,0 +1,10 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource } from "./runtime";
+
+export const Service = createResource("Docker::Compose::Service", "docker", {});
+export const Volume = createResource("Docker::Compose::Volume", "docker", {});
+export const Network = createResource("Docker::Compose::Network", "docker", {});
+export const DockerConfig = createResource("Docker::Compose::Config", "docker", {});
+export const DockerSecret = createResource("Docker::Compose::Secret", "docker", {});
+
+export const Dockerfile = createResource("Docker::Dockerfile", "docker", {});

package/src/generated/lexicon-docker.json

@@ -0,0 +1,222 @@
+{
+  "Service": {
+    "resourceType": "Docker::Compose::Service",
+    "kind": "resource",
+    "description": "A containerized service definition in Docker Compose",
+    "properties": {
+      "image": {
+        "type": "string",
+        "description": "Container image to use"
+      },
+      "build": {
+        "type": "object",
+        "description": "Build configuration"
+      },
+      "command": {
+        "type": "string | string[]",
+        "description": "Override the default command"
+      },
+      "entrypoint": {
+        "type": "string | string[]",
+        "description": "Override the default entrypoint"
+      },
+      "environment": {
+        "type": "Record<string, string>",
+        "description": "Environment variables"
+      },
+      "ports": {
+        "type": "string[]",
+        "description": "Published ports"
+      },
+      "volumes": {
+        "type": "string[]",
+        "description": "Volume mounts"
+      },
+      "networks": {
+        "type": "string[]",
+        "description": "Networks to attach"
+      },
+      "depends_on": {
+        "type": "string[]",
+        "description": "Service dependencies"
+      },
+      "restart": {
+        "type": "string",
+        "description": "Restart policy"
+      },
+      "labels": {
+        "type": "Record<string, string>",
+        "description": "Container labels"
+      },
+      "healthcheck": {
+        "type": "object",
+        "description": "Health check configuration"
+      },
+      "deploy": {
+        "type": "object",
+        "description": "Swarm deployment configuration"
+      },
+      "secrets": {
+        "type": "string[]",
+        "description": "Secrets to expose"
+      },
+      "configs": {
+        "type": "string[]",
+        "description": "Configs to expose"
+      }
+    }
+  },
+  "Volume": {
+    "resourceType": "Docker::Compose::Volume",
+    "kind": "resource",
+    "description": "A named volume definition in Docker Compose",
+    "properties": {
+      "driver": {
+        "type": "string",
+        "description": "Volume driver"
+      },
+      "driver_opts": {
+        "type": "Record<string, string>",
+        "description": "Driver options"
+      },
+      "external": {
+        "type": "boolean",
+        "description": "Whether the volume is external"
+      },
+      "labels": {
+        "type": "Record<string, string>",
+        "description": "Volume labels"
+      },
+      "name": {
+        "type": "string",
+        "description": "Custom volume name"
+      }
+    }
+  },
+  "Network": {
+    "resourceType": "Docker::Compose::Network",
+    "kind": "resource",
+    "description": "A network definition in Docker Compose",
+    "properties": {
+      "driver": {
+        "type": "string",
+        "description": "Network driver"
+      },
+      "driver_opts": {
+        "type": "Record<string, string>",
+        "description": "Driver options"
+      },
+      "external": {
+        "type": "boolean",
+        "description": "Whether the network is external"
+      },
+      "labels": {
+        "type": "Record<string, string>",
+        "description": "Network labels"
+      },
+      "internal": {
+        "type": "boolean",
+        "description": "Restrict external access"
+      },
+      "ipam": {
+        "type": "object",
+        "description": "IP address management"
+      }
+    }
+  },
+  "DockerConfig": {
+    "resourceType": "Docker::Compose::Config",
+    "kind": "resource",
+    "description": "A config definition in Docker Compose",
+    "properties": {
+      "file": {
+        "type": "string",
+        "description": "Path to the config file"
+      },
+      "external": {
+        "type": "boolean",
+        "description": "Whether the config is external"
+      },
+      "labels": {
+        "type": "Record<string, string>",
+        "description": "Config labels"
+      },
+      "name": {
+        "type": "string",
+        "description": "Custom config name"
+      }
+    }
+  },
+  "DockerSecret": {
+    "resourceType": "Docker::Compose::Secret",
+    "kind": "resource",
+    "description": "A secret definition in Docker Compose",
+    "properties": {
+      "file": {
+        "type": "string",
+        "description": "Path to the secret file"
+      },
+      "external": {
+        "type": "boolean",
+        "description": "Whether the secret is external"
+      },
+      "labels": {
+        "type": "Record<string, string>",
+        "description": "Secret labels"
+      },
+      "name": {
+        "type": "string",
+        "description": "Custom secret name"
+      }
+    }
+  },
+  "Dockerfile": {
+    "resourceType": "Docker::Dockerfile",
+    "kind": "resource",
+    "description": "A Dockerfile definition with ordered build instructions",
+    "properties": {
+      "from": {
+        "description": "Base image (required first instruction)"
+      },
+      "arg": {
+        "description": "Build-time argument"
+      },
+      "env": {
+        "description": "Environment variable"
+      },
+      "run": {
+        "description": "Run a command during build"
+      },
+      "copy": {
+        "description": "Copy files from build context"
+      },
+      "add": {
+        "description": "Add files (supports URLs and archives)"
+      },
+      "workdir": {
+        "description": "Set working directory"
+      },
+      "user": {
+        "description": "Set user for subsequent instructions"
+      },
+      "expose": {
+        "description": "Document exposed ports"
+      },
+      "volume": {
+        "description": "Create mount points"
+      },
+      "label": {
+        "description": "Add metadata labels"
+      },
+      "entrypoint": {
+        "description": "Set the entrypoint executable"
+      },
+      "cmd": {
+        "description": "Default command arguments"
+      },
+      "healthcheck": {
+        "description": "Health check instruction"
+      }
+    }
+  }
+}

package/src/generated/runtime.ts

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/src/import/generator.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from "bun:test";
+import { DockerGenerator } from "./generator";
+import type { ServiceIR, VolumeIR, NetworkIR, ConfigIR, SecretIR, DockerfileIR } from "./parser";
+
+describe("DockerGenerator", () => {
+  test("generates Service from IR with image", () => {
+    const entities: ServiceIR[] = [
+      { kind: "service", name: "api", props: { image: "nginx:1.25" } },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Service }");
+    expect(source).toContain("new Service(");
+    expect(source).toContain("nginx:1.25");
+  });
+
+  test("generates Service with ports and environment", () => {
+    const entities: ServiceIR[] = [
+      {
+        kind: "service",
+        name: "api",
+        props: {
+          image: "node:20",
+          ports: ["3000:3000"],
+          environment: { NODE_ENV: "production" },
+        },
+      },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("3000:3000");
+    expect(source).toContain("NODE_ENV");
+    expect(source).toContain("production");
+  });
+
+  test("generates Config entity", () => {
+    const entities: ConfigIR[] = [
+      { kind: "config", name: "app-config", props: { file: "./config/app.conf" } },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Config }");
+    expect(source).toContain("new Config(");
+    expect(source).toContain("app.conf");
+  });
+
+  test("generates Secret entity", () => {
+    const entities: SecretIR[] = [
+      { kind: "secret", name: "db-password", props: { file: "./secrets/db.txt" } },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Secret }");
+    expect(source).toContain("new Secret(");
+  });
+
+  test("single-stage Dockerfile generates flat props (existing behaviour)", () => {
+    const entities: DockerfileIR[] = [
+      {
+        kind: "dockerfile",
+        name: "builder",
+        stages: [
+          {
+            from: "node:20-alpine",
+            instructions: [
+              { instruction: "RUN", value: "npm ci" },
+              { instruction: "CMD", value: '["node", "index.js"]' },
+            ],
+          },
+        ],
+      },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Dockerfile }");
+    expect(source).toContain("new Dockerfile(");
+    expect(source).toContain("node:20-alpine");
+    expect(source).not.toContain('"stages"');
+  });
+
+  test("multi-stage Dockerfile generates stages: array form", () => {
+    const entities: DockerfileIR[] = [
+      {
+        kind: "dockerfile",
+        name: "app",
+        stages: [
+          { from: "node:20-alpine", as: "builder", instructions: [{ instruction: "RUN", value: "npm ci" }] },
+          { from: "nginx:1.25", as: "runner", instructions: [] },
+        ],
+      },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("stages");
+    expect(source).toContain("node:20-alpine");
+    expect(source).toContain("nginx:1.25");
+  });
+
+  test("import line includes only needed types", () => {
+    const entities: VolumeIR[] = [
+      { kind: "volume", name: "data", props: {} },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Volume }");
+    expect(source).not.toContain("Service");
+    expect(source).not.toContain("Network");
+  });
+
+  test("generates correct imports for multiple entity types", () => {
+    const entities = [
+      { kind: "service" as const, name: "api", props: { image: "nginx:1.25" } },
+      {
+        kind: "dockerfile" as const,
+        name: "build",
+        stages: [{ from: "node:20", instructions: [] }],
+      },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("Dockerfile");
+    expect(source).toContain("Service");
+  });
+
+  test("sanitizes kebab-case names to camelCase", () => {
+    const entities: ServiceIR[] = [
+      { kind: "service", name: "my-web-server", props: { image: "nginx:1.25" } },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("myWebServer");
+  });
+
+  test("generates Network entity", () => {
+    const entities: NetworkIR[] = [
+      { kind: "network", name: "backend", props: { driver: "bridge" } },
+    ];
+    const { source } = new DockerGenerator().generate(entities);
+    expect(source).toContain("import { Network }");
+    expect(source).toContain("new Network(");
+  });
+});