@intentius/chant-lexicon-docker 0.1.0

package/src/spec/parse-compose.ts

@@ -0,0 +1,110 @@
+/**
+ * Parse the Compose Spec JSON Schema into ParsedResult entries.
+ *
+ * The Compose spec defines a top-level "services", "volumes", "networks",
+ * "configs", and "secrets" map — each value is a typed resource.
+ * We model those as the five Compose entity types.
+ */
+
+export interface ComposeParseResult {
+  typeName: string;          // e.g. "Docker::Compose::Service"
+  shortName: string;         // e.g. "Service"
+  description?: string;
+  properties: ComposeProperty[];
+  isResource: boolean;
+}
+
+export interface ComposeProperty {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  enum?: string[];
+}
+
+/**
+ * Parse the Compose Spec JSON Schema buffer into ParsedResult entries.
+ * Returns one entry per top-level Compose resource type.
+ */
+export function parseComposeSpec(_data: Buffer): ComposeParseResult[] {
+  // The Compose spec is complex; we hand-define the five core resource types
+  // and extract key properties from the schema for documentation/type generation.
+  // Full deep parsing happens during codegen; here we return the structural outline.
+
+  return [
+    {
+      typeName: "Docker::Compose::Service",
+      shortName: "Service",
+      description: "A containerized service definition in Docker Compose",
+      isResource: true,
+      properties: [
+        { name: "image", type: "string", description: "Container image to use" },
+        { name: "build", type: "object", description: "Build configuration" },
+        { name: "command", type: "string | string[]", description: "Override the default command" },
+        { name: "entrypoint", type: "string | string[]", description: "Override the default entrypoint" },
+        { name: "environment", type: "Record<string, string>", description: "Environment variables" },
+        { name: "ports", type: "string[]", description: "Published ports" },
+        { name: "volumes", type: "string[]", description: "Volume mounts" },
+        { name: "networks", type: "string[]", description: "Networks to attach" },
+        { name: "depends_on", type: "string[]", description: "Service dependencies" },
+        { name: "restart", type: "string", description: "Restart policy" },
+        { name: "labels", type: "Record<string, string>", description: "Container labels" },
+        { name: "healthcheck", type: "object", description: "Health check configuration" },
+        { name: "deploy", type: "object", description: "Swarm deployment configuration" },
+        { name: "secrets", type: "string[]", description: "Secrets to expose" },
+        { name: "configs", type: "string[]", description: "Configs to expose" },
+      ],
+    },
+    {
+      typeName: "Docker::Compose::Volume",
+      shortName: "Volume",
+      description: "A named volume definition in Docker Compose",
+      isResource: true,
+      properties: [
+        { name: "driver", type: "string", description: "Volume driver" },
+        { name: "driver_opts", type: "Record<string, string>", description: "Driver options" },
+        { name: "external", type: "boolean", description: "Whether the volume is external" },
+        { name: "labels", type: "Record<string, string>", description: "Volume labels" },
+        { name: "name", type: "string", description: "Custom volume name" },
+      ],
+    },
+    {
+      typeName: "Docker::Compose::Network",
+      shortName: "Network",
+      description: "A network definition in Docker Compose",
+      isResource: true,
+      properties: [
+        { name: "driver", type: "string", description: "Network driver" },
+        { name: "driver_opts", type: "Record<string, string>", description: "Driver options" },
+        { name: "external", type: "boolean", description: "Whether the network is external" },
+        { name: "labels", type: "Record<string, string>", description: "Network labels" },
+        { name: "internal", type: "boolean", description: "Restrict external access" },
+        { name: "ipam", type: "object", description: "IP address management" },
+      ],
+    },
+    {
+      typeName: "Docker::Compose::Config",
+      shortName: "Config",
+      description: "A config definition in Docker Compose",
+      isResource: true,
+      properties: [
+        { name: "file", type: "string", description: "Path to the config file" },
+        { name: "external", type: "boolean", description: "Whether the config is external" },
+        { name: "labels", type: "Record<string, string>", description: "Config labels" },
+        { name: "name", type: "string", description: "Custom config name" },
+      ],
+    },
+    {
+      typeName: "Docker::Compose::Secret",
+      shortName: "Secret",
+      description: "A secret definition in Docker Compose",
+      isResource: true,
+      properties: [
+        { name: "file", type: "string", description: "Path to the secret file" },
+        { name: "external", type: "boolean", description: "Whether the secret is external" },
+        { name: "labels", type: "Record<string, string>", description: "Secret labels" },
+        { name: "name", type: "string", description: "Custom secret name" },
+      ],
+    },
+  ];
+}

package/src/spec/parse-engine.ts

@@ -0,0 +1,47 @@
+/**
+ * Parse the Docker Engine API OpenAPI spec for Dockerfile-related types.
+ *
+ * We extract only the image-builder relevant definitions:
+ * ContainerConfig, BuildInfo, and related types.
+ */
+
+export interface DockerfileParseResult {
+  typeName: string;       // "Docker::Dockerfile"
+  shortName: string;      // "Dockerfile"
+  description?: string;
+  instructions: DockerfileInstruction[];
+}
+
+export interface DockerfileInstruction {
+  name: string;
+  description?: string;
+  multi?: boolean;  // can appear multiple times
+}
+
+/**
+ * Parse the Docker Engine API YAML buffer for Dockerfile instruction types.
+ * Returns a single DockerfileParseResult describing the Dockerfile entity.
+ */
+export function parseEngineApi(_data: Buffer): DockerfileParseResult {
+  return {
+    typeName: "Docker::Dockerfile",
+    shortName: "Dockerfile",
+    description: "A Dockerfile definition with ordered build instructions",
+    instructions: [
+      { name: "from", description: "Base image (required first instruction)" },
+      { name: "arg", description: "Build-time argument", multi: true },
+      { name: "env", description: "Environment variable", multi: true },
+      { name: "run", description: "Run a command during build", multi: true },
+      { name: "copy", description: "Copy files from build context", multi: true },
+      { name: "add", description: "Add files (supports URLs and archives)", multi: true },
+      { name: "workdir", description: "Set working directory" },
+      { name: "user", description: "Set user for subsequent instructions" },
+      { name: "expose", description: "Document exposed ports", multi: true },
+      { name: "volume", description: "Create mount points", multi: true },
+      { name: "label", description: "Add metadata labels", multi: true },
+      { name: "entrypoint", description: "Set the entrypoint executable" },
+      { name: "cmd", description: "Default command arguments" },
+      { name: "healthcheck", description: "Health check instruction" },
+    ],
+  };
+}

package/src/validate-cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/**
+ * Thin entry point for `bun run validate` in lexicon-docker.
+ */
+import { validate } from "./validate";
+
+const result = await validate();
+
+for (const check of result.checks) {
+  const status = check.ok ? "OK" : "FAIL";
+  const msg = check.error ? ` — ${check.error}` : "";
+  console.error(`  [${status}] ${check.name}${msg}`);
+}
+
+if (!result.success) {
+  console.error("Validation failed");
+  process.exit(1);
+}
+console.error("All validation checks passed.");

package/src/validate.test.ts

@@ -0,0 +1,16 @@
+import { describe, test, expect } from "bun:test";
+import { validate } from "./validate";
+
+describe("validate", () => {
+  test("is an async function", () => {
+    expect(typeof validate).toBe("function");
+  });
+
+  test("returns failure when generated dir does not exist", async () => {
+    const result = await validate({ basePath: "/tmp/nonexistent-docker-lexicon-test" });
+    expect(result.success).toBe(false);
+    expect(result.checks.length).toBeGreaterThanOrEqual(1);
+    const failedCheck = result.checks.find((c) => !c.ok);
+    expect(failedCheck).toBeDefined();
+  });
+});

package/src/validate.ts

@@ -0,0 +1,44 @@
+/**
+ * Validate generated lexicon-docker artifacts.
+ */
+
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+const REQUIRED_NAMES = [
+  "Service",
+  "Volume",
+  "Network",
+  "DockerConfig",
+  "DockerSecret",
+  "Dockerfile",
+];
+
+/**
+ * Validate the generated lexicon-docker artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const generatedDir = join(basePath, "src", "generated");
+
+  if (!existsSync(generatedDir)) {
+    return {
+      success: false,
+      checks: [{
+        name: "generated-dir",
+        ok: false,
+        error: 'src/generated/ not found — run "chant dev generate" first',
+      }],
+    };
+  }
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-docker.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}

package/src/variables.test.ts

@@ -0,0 +1,32 @@
+import { describe, test, expect } from "bun:test";
+import { DOCKER_VARS, COMPOSE_VARS } from "./variables";
+
+describe("DOCKER_VARS", () => {
+  test("exposes DOCKER_BUILDKIT", () => {
+    expect(DOCKER_VARS.DOCKER_BUILDKIT).toBe("DOCKER_BUILDKIT");
+  });
+
+  test("exposes DOCKER_HOST", () => {
+    expect(DOCKER_VARS.DOCKER_HOST).toBe("DOCKER_HOST");
+  });
+
+  test("is a const object", () => {
+    expect(typeof DOCKER_VARS).toBe("object");
+    expect(Object.keys(DOCKER_VARS).length).toBeGreaterThan(0);
+  });
+});
+
+describe("COMPOSE_VARS", () => {
+  test("exposes COMPOSE_PROJECT_NAME", () => {
+    expect(COMPOSE_VARS.COMPOSE_PROJECT_NAME).toBe("COMPOSE_PROJECT_NAME");
+  });
+
+  test("exposes COMPOSE_FILE", () => {
+    expect(COMPOSE_VARS.COMPOSE_FILE).toBe("COMPOSE_FILE");
+  });
+
+  test("is a const object", () => {
+    expect(typeof COMPOSE_VARS).toBe("object");
+    expect(Object.keys(COMPOSE_VARS).length).toBeGreaterThan(0);
+  });
+});

package/src/variables.ts

@@ -0,0 +1,47 @@
+/**
+ * Well-known Docker and Docker Compose environment variable names.
+ *
+ * Use with the env() intrinsic for type-safe interpolation.
+ *
+ * @example
+ * import { env, DOCKER_VARS } from "@intentius/chant-lexicon-docker";
+ *
+ * export const api = new Service({
+ *   environment: {
+ *     BUILDKIT_ENABLED: env(DOCKER_VARS.DOCKER_BUILDKIT),
+ *   },
+ * });
+ */
+
+/** Docker daemon and client environment variables */
+export const DOCKER_VARS = {
+  /** Enable Docker BuildKit: DOCKER_BUILDKIT=1 */
+  DOCKER_BUILDKIT: "DOCKER_BUILDKIT",
+  /** Docker host socket/address */
+  DOCKER_HOST: "DOCKER_HOST",
+  /** Docker TLS verify */
+  DOCKER_TLS_VERIFY: "DOCKER_TLS_VERIFY",
+  /** Docker config directory */
+  DOCKER_CONFIG: "DOCKER_CONFIG",
+  /** Docker content trust */
+  DOCKER_CONTENT_TRUST: "DOCKER_CONTENT_TRUST",
+} as const;
+
+/** Docker Compose specific environment variables */
+export const COMPOSE_VARS = {
+  /** Override project name: COMPOSE_PROJECT_NAME */
+  COMPOSE_PROJECT_NAME: "COMPOSE_PROJECT_NAME",
+  /** Override compose file: COMPOSE_FILE */
+  COMPOSE_FILE: "COMPOSE_FILE",
+  /** Path separator for COMPOSE_FILE */
+  COMPOSE_PATH_SEPARATOR: "COMPOSE_PATH_SEPARATOR",
+  /** Docker compose profiles to enable */
+  COMPOSE_PROFILES: "COMPOSE_PROFILES",
+  /** Compose conversion flag */
+  COMPOSE_CONVERT_WINDOWS_PATHS: "COMPOSE_CONVERT_WINDOWS_PATHS",
+  /** Docker host for compose */
+  DOCKER_DEFAULT_PLATFORM: "DOCKER_DEFAULT_PLATFORM",
+} as const;
+
+export type DockerVar = (typeof DOCKER_VARS)[keyof typeof DOCKER_VARS];
+export type ComposeVar = (typeof COMPOSE_VARS)[keyof typeof COMPOSE_VARS];