@intentius/chant-lexicon-docker 0.1.0

package/dist/rules/ssh-port-exposed.ts

@@ -0,0 +1,68 @@
+/**
+ * DKRD003: SSH Port Exposed
+ *
+ * Detects services exposing port 22 (SSH) on the host.
+ * Exposing SSH externally is a security risk.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices } from "./docker-helpers";
+
+function exposesSshPort(port: string): boolean {
+  // Formats: "22", "22/tcp", "0.0.0.0:22:22", "127.0.0.1:22:22", "host:container"
+  const normalized = port.trim();
+  const parts = normalized.split(":");
+
+  if (parts.length === 1) {
+    // Just a port number: "22" or "22/tcp"
+    const portNum = parts[0].split("/")[0];
+    return portNum === "22";
+  }
+
+  if (parts.length === 2) {
+    // "hostPort:containerPort" e.g. "22:22" — no IP binding, accessible on all interfaces
+    const hostPort = parts[0].split("/")[0];
+    return hostPort === "22";
+  }
+
+  if (parts.length >= 3) {
+    // "ip:hostPort:containerPort" e.g. "127.0.0.1:22:22" or "0.0.0.0:22:22"
+    const ip = parts[0];
+    const hostPort = parts[1].split("/")[0];
+    // Only flag if port is 22 AND not bound to loopback
+    if (hostPort !== "22") return false;
+    return ip !== "127.0.0.1" && ip !== "::1" && ip !== "localhost";
+  }
+
+  return false;
+}
+
+export const dkrd003: PostSynthCheck = {
+  id: "DKRD003",
+  description: "Service exposes SSH port (22) externally — this is a security risk",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      if (!yaml) continue;
+
+      const services = extractServices(yaml);
+      for (const [name, svc] of services) {
+        for (const port of svc.ports ?? []) {
+          if (exposesSshPort(port)) {
+            diagnostics.push({
+              checkId: "DKRD003",
+              severity: "error",
+              message: `Service "${name}" exposes SSH port 22 externally (port mapping: "${port}"). This is a security risk.`,
+              lexicon: "docker",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/unused-volume.ts

@@ -0,0 +1,49 @@
+/**
+ * DKRD002: Unused Named Volume
+ *
+ * Detects top-level named volumes that are not mounted by any service.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices, extractNamedVolumes } from "./docker-helpers";
+
+export const dkrd002: PostSynthCheck = {
+  id: "DKRD002",
+  description: "Named volume is declared but not mounted by any service",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      if (!yaml) continue;
+
+      const namedVolumes = extractNamedVolumes(yaml);
+      if (namedVolumes.size === 0) continue;
+
+      const services = extractServices(yaml);
+      const mountedVolumes = new Set<string>();
+
+      for (const svc of services.values()) {
+        for (const vol of svc.volumes ?? []) {
+          // Volume mount format: "volname:/container/path" or just "volname"
+          const volumeName = vol.split(":")[0].trim();
+          mountedVolumes.add(volumeName);
+        }
+      }
+
+      for (const volName of namedVolumes) {
+        if (!mountedVolumes.has(volName)) {
+          diagnostics.push({
+            checkId: "DKRD002",
+            severity: "warning",
+            message: `Named volume "${volName}" is declared but not mounted by any service.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-docker-patterns.md

@@ -0,0 +1,153 @@
+# chant-docker-patterns
+
+Common Docker Compose and Dockerfile patterns using `@intentius/chant-lexicon-docker`.
+
+## Database service with volume
+
+```typescript
+import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const postgres = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: env("POSTGRES_PASSWORD", { required: true }),
+  },
+  volumes: ["pgdata:/var/lib/postgresql/data"],
+  restart: "unless-stopped",
+  healthcheck: {
+    test: ["CMD-SHELL", "pg_isready -U myapp"],
+    interval: "10s",
+    timeout: "5s",
+    retries: 5,
+  },
+});
+
+export const pgdata = new Volume({});
+```
+
+## Redis cache
+
+```typescript
+export const redis = new Service({
+  image: "redis:7-alpine",
+  volumes: ["redisdata:/data"],
+  command: "redis-server --appendonly yes",
+  restart: "unless-stopped",
+});
+export const redisdata = new Volume({});
+```
+
+## Reverse proxy (nginx)
+
+```typescript
+export const nginx = new Service({
+  image: "nginx:1.25-alpine",
+  ports: ["80:80", "443:443"],
+  volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro", "./certs:/etc/ssl/certs:ro"],
+  depends_on: ["api"],
+  restart: "unless-stopped",
+});
+```
+
+## Multi-stage Node.js Dockerfile
+
+```typescript
+export const nodeApp = new Dockerfile({
+  stages: [
+    {
+      from: "node:20-alpine",
+      as: "deps",
+      workdir: "/app",
+      copy: ["package*.json ./"],
+      run: ["npm ci --only=production"],
+    },
+    {
+      from: "node:20-alpine",
+      as: "build",
+      workdir: "/app",
+      copy: ["--from=deps /app/node_modules ./node_modules", ". ."],
+      run: ["npm run build"],
+    },
+    {
+      from: "node:20-alpine",
+      workdir: "/app",
+      copy: [
+        "--from=deps /app/node_modules ./node_modules",
+        "--from=build /app/dist ./dist",
+      ],
+      user: "node",
+      expose: ["3000"],
+      cmd: `["node", "dist/index.js"]`,
+    },
+  ],
+});
+```
+
+## Python service with virtualenv
+
+```typescript
+export const pythonApp = new Dockerfile({
+  from: "python:3.12-slim",
+  workdir: "/app",
+  env: ["PYTHONUNBUFFERED=1", "PYTHONDONTWRITEBYTECODE=1"],
+  copy: ["requirements.txt ."],
+  run: [
+    "pip install --no-cache-dir --no-deps -r requirements.txt",
+  ],
+  copy: [". ."],
+  user: "1000:1000",
+  cmd: `["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]`,
+});
+```
+
+## Network isolation
+
+```typescript
+import { Service, Network } from "@intentius/chant-lexicon-docker";
+
+export const internal = new Network({ driver: "bridge", internal: true });
+export const external = new Network({ driver: "bridge" });
+
+export const api = new Service({
+  image: "myapi:1.0",
+  networks: ["external", "internal"],
+});
+export const db = new Service({
+  image: "postgres:16-alpine",
+  networks: ["internal"],  // only reachable via internal network
+});
+```
+
+## Secrets and configs
+
+```typescript
+import { Service, DockerSecret, DockerConfig } from "@intentius/chant-lexicon-docker";
+
+export const dbPassword = new DockerSecret({ file: "./secrets/db-password.txt" });
+export const appConfig = new DockerConfig({ file: "./config/app.yaml" });
+
+export const app = new Service({
+  image: "myapp:1.0",
+  secrets: ["dbPassword"],
+  configs: ["appConfig"],
+});
+```
+
+## Environment interpolation patterns
+
+```typescript
+import { env } from "@intentius/chant-lexicon-docker";
+
+// Dev vs prod toggle:
+export const api = new Service({
+  image: env("API_IMAGE", { default: "myapp:latest" }),
+  environment: {
+    LOG_LEVEL: env("LOG_LEVEL", { default: "info" }),
+    WORKERS: env("WORKERS", { default: "4" }),
+    SECRET_KEY: env("SECRET_KEY", { required: true }),
+    SENTRY_DSN: env("SENTRY_DSN", { default: "" }),
+  },
+});
+```

package/dist/skills/chant-docker.md

@@ -0,0 +1,129 @@
+# chant-docker
+
+You are helping a developer define Docker Compose services and Dockerfiles using the `@intentius/chant-lexicon-docker` library.
+
+## Core types
+
+```typescript
+import { Service, Volume, Network, Dockerfile, env, defaultLabels } from "@intentius/chant-lexicon-docker";
+```
+
+## Service — docker-compose.yml services:
+
+```typescript
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  environment: {
+    NODE_ENV: "production",
+    DB_URL: env("DATABASE_URL", { required: true }),
+  },
+  depends_on: ["db"],
+  restart: "unless-stopped",
+  healthcheck: {
+    test: ["CMD", "curl", "-f", "http://localhost:8080/health"],
+    interval: "30s",
+    timeout: "10s",
+    retries: 3,
+  },
+});
+```
+
+## Volume — top-level named volume:
+
+```typescript
+export const pgdata = new Volume({});
+// With driver options:
+export const nfsdata = new Volume({ driver: "local", driver_opts: { type: "nfs", o: "addr=..." } });
+```
+
+## Dockerfile — generates Dockerfile.{name}:
+
+```typescript
+// Single-stage:
+export const builder = new Dockerfile({
+  from: "node:20-alpine",
+  workdir: "/app",
+  copy: ["package*.json ./"],
+  run: ["npm ci --only=production"],
+  user: "node",
+  cmd: `["node", "dist/index.js"]`,
+});
+
+// Multi-stage build:
+export const app = new Dockerfile({
+  stages: [
+    {
+      from: "node:20-alpine",
+      as: "build",
+      workdir: "/app",
+      copy: ["package*.json ./"],
+      run: ["npm ci", "npm run build"],
+    },
+    {
+      from: "node:20-alpine",
+      workdir: "/app",
+      copy: ["--from=build /app/dist ./dist", "--from=build /app/node_modules ./node_modules"],
+      user: "node",
+      cmd: `["node", "dist/index.js"]`,
+    },
+  ],
+});
+```
+
+## Variable interpolation with env():
+
+```typescript
+import { env } from "@intentius/chant-lexicon-docker";
+
+// ${VAR} — required, no default:
+env("DATABASE_URL")
+
+// ${VAR:-default} — use default if unset:
+env("LOG_LEVEL", { default: "info" })
+
+// ${VAR:?message} — fail with error if unset:
+env("API_SECRET", { required: true })
+env("API_SECRET", { errorMessage: "API_SECRET must be set in .env" })
+
+// ${VAR:+value} — substitute value if VAR is set:
+env("DEBUG", { ifSet: "verbose" })
+```
+
+## Default labels (injected into all services):
+
+```typescript
+export const labels = defaultLabels({
+  "com.example.team": "platform",
+  "com.example.managed-by": "chant",
+  "com.example.version": "1.0.0",
+});
+```
+
+## Service → Dockerfile cross-reference:
+
+```typescript
+// The serializer emits "Dockerfile.builder" as the filename.
+// Reference it in the service build config:
+export const api = new Service({
+  build: {
+    context: ".",
+    dockerfile: "Dockerfile.builder",  // matches the Dockerfile entity name
+  },
+  ports: ["8080:8080"],
+});
+export const builder = new Dockerfile({ from: "node:20-alpine", ... });
+```
+
+## Output structure
+
+- All Compose entities → `docker-compose.yml`
+- Each Dockerfile entity → `Dockerfile.{name}`
+
+## Key rules
+
+- `DKRS001`: Never use `:latest` image tags in source — use explicit versions
+- `DKRD001`: Post-synth: no `:latest` images in generated YAML
+- `DKRD002`: Post-synth: no unused named volumes
+- `DKRD003`: Post-synth: SSH port 22 not exposed externally
+- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, USER)

package/dist/types/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/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@intentius/chant-lexicon-docker",
+  "version": "0.1.0",
+  "description": "Docker lexicon for chant — declarative IaC in TypeScript",
+  "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "lexicons/docker"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "docker",
+    "docker-compose",
+    "dockerfile",
+    "chant"
+  ],
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "bun run src/codegen/generate-cli.ts",
+    "bundle": "bun run src/package-cli.ts",
+    "validate": "bun run src/validate-cli.ts",
+    "docs": "bun run src/codegen/docs-cli.ts",
+    "prepack": "bun run generate && bun run bundle && bun run validate"
+  },
+  "devDependencies": {
+    "@intentius/chant": "0.1.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.1.0"
+  }
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry for Docker lexicon docs generation.
+ */
+
+import { generateDocs } from "./docs";
+
+const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+
+await generateDocs({ verbose });

package/src/codegen/docs.ts

@@ -0,0 +1,12 @@
+/**
+ * Docker lexicon docs generation.
+ */
+
+export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
+  if (opts?.verbose) {
+    console.error("Generating Docker lexicon docs...");
+  }
+  // Docs are currently hand-authored in docs/src/content/docs/
+  // Future: auto-generate entity reference pages from lexicon-docker.json
+  console.error("Docker docs: see docs/src/content/docs/overview.mdx");
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for Docker lexicon generation.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+async function main() {
+  const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+  const force = process.argv.includes("--force") || process.argv.includes("-f");
+
+  console.error("Generating Docker lexicon...");
+
+  const result = await generate({ verbose, force });
+  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:`);
+    for (const w of result.warnings) {
+      console.error(`  ${w.file}: ${w.error}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("Generation failed:", err);
+  process.exit(1);
+});

package/src/codegen/generate-compose.ts

@@ -0,0 +1,21 @@
+/**
+ * Generate Compose entity types from the Compose Spec JSON Schema.
+ */
+
+import { fetchComposeSpec } from "../spec/fetch-compose";
+import { parseComposeSpec, type ComposeParseResult } from "../spec/parse-compose";
+
+export interface ComposeGenerateResult {
+  results: ComposeParseResult[];
+}
+
+export async function generateComposePipeline(opts: { force?: boolean; verbose?: boolean } = {}): Promise<ComposeGenerateResult> {
+  if (opts.verbose) console.error("Fetching Compose Spec...");
+  const data = await fetchComposeSpec(opts.force);
+
+  if (opts.verbose) console.error("Parsing Compose Spec...");
+  const results = parseComposeSpec(data);
+
+  if (opts.verbose) console.error(`Parsed ${results.length} Compose entity types`);
+  return { results };
+}

package/src/codegen/generate-dockerfile.ts

@@ -0,0 +1,21 @@
+/**
+ * Generate Dockerfile entity types from the Docker Engine API OpenAPI spec.
+ */
+
+import { fetchEngineApi } from "../spec/fetch-engine";
+import { parseEngineApi, type DockerfileParseResult } from "../spec/parse-engine";
+
+export interface DockerfileGenerateResult {
+  result: DockerfileParseResult;
+}
+
+export async function generateDockerfilePipeline(opts: { force?: boolean; verbose?: boolean } = {}): Promise<DockerfileGenerateResult> {
+  if (opts.verbose) console.error("Fetching Docker Engine API...");
+  const data = await fetchEngineApi(opts.force);
+
+  if (opts.verbose) console.error("Parsing Engine API for Dockerfile types...");
+  const result = parseEngineApi(data);
+
+  if (opts.verbose) console.error(`Parsed ${result.instructions.length} Dockerfile instructions`);
+  return { result };
+}