@intentius/chant-lexicon-docker 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @intentius/chant-lexicon-docker
+
+Docker lexicon for [chant](https://intentius.io/chant/) — declare Docker Compose services and Dockerfile build instructions as typed TypeScript that serializes to `docker-compose.yml` and `Dockerfile.*` files.
+
+Provides typed constructors for Service, Volume, Network, Config, Secret, and multi-stage Dockerfile resources, plus variable interpolation, default labels, Docker-specific lint rules, LSP completions, and MCP server support.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-docker
+```
+
+**[Documentation →](https://intentius.io/chant/lexicons/docker/)**
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| [@intentius/chant](https://www.npmjs.com/package/@intentius/chant) | Core type system, CLI, build pipeline |
+| [@intentius/chant-lexicon-k8s](https://www.npmjs.com/package/@intentius/chant-lexicon-k8s) | Kubernetes lexicon |
+| [@intentius/chant-lexicon-aws](https://www.npmjs.com/package/@intentius/chant-lexicon-aws) | AWS CloudFormation lexicon |
+| [@intentius/chant-lexicon-flyway](https://www.npmjs.com/package/@intentius/chant-lexicon-flyway) | Flyway database migrations lexicon |
+
+## License
+
+See the main project LICENSE file.

package/dist/integrity.json

@@ -0,0 +1,19 @@
+{
+  "algorithm": "xxhash64",
+  "artifacts": {
+    "manifest.json": "3621c2b241ba2cc1",
+    "meta.json": "6a8cbb16d88dd81",
+    "types/index.d.ts": "61a04a2aae8fb72d",
+    "rules/no-latest-tag.ts": "9a513a0d0801cfbd",
+    "rules/ssh-port-exposed.ts": "73a6e5d39eebcc28",
+    "rules/no-root-user.ts": "5aad839aa8ef0407",
+    "rules/unused-volume.ts": "b6101cbbfef97481",
+    "rules/apt-no-recommends.ts": "dce8c901982e2d4",
+    "rules/no-latest-image.ts": "1730d370550a5f5e",
+    "rules/docker-helpers.ts": "667d796e1dd6771f",
+    "rules/prefer-copy.ts": "c2eb8a86389a6b1",
+    "skills/chant-docker.md": "419ee2f3187d9527",
+    "skills/chant-docker-patterns.md": "cea0225dd8450081"
+  },
+  "composite": "86524aae9dcf961b"
+}

package/dist/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "docker",
+  "version": "0.1.0",
+  "chantVersion": ">=0.1.0",
+  "namespace": "Docker",
+  "intrinsics": [
+    {
+      "name": "env",
+      "description": "Docker Compose variable interpolation — ${VAR}, ${VAR:-default}, ${VAR:?error}",
+      "outputKey": "env",
+      "isTag": false
+    }
+  ],
+  "pseudoParameters": {}
+}

package/dist/meta.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/dist/rules/apt-no-recommends.ts

@@ -0,0 +1,43 @@
+/**
+ * DKRD010: apt-get install without --no-install-recommends
+ *
+ * Detects RUN instructions with apt-get install missing
+ * --no-install-recommends, which leads to bloated images.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+export const dkrd010: PostSynthCheck = {
+  id: "DKRD010",
+  description: "apt-get install without --no-install-recommends adds unnecessary packages",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (
+            /^RUN\s+/.test(line) &&
+            line.includes("apt-get install") &&
+            !line.includes("--no-install-recommends")
+          ) {
+            diagnostics.push({
+              checkId: "DKRD010",
+              severity: "warning",
+              message: `${fileName}: RUN apt-get install should use --no-install-recommends to reduce image size.`,
+              lexicon: "docker",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/docker-helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared YAML traversal utilities for Docker post-synth checks.
+ */
+
+export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+export interface ParsedService {
+  name: string;
+  image?: string;
+  ports?: string[];
+  volumes?: string[];
+  build?: { dockerfile?: string; context?: string };
+  depends_on?: string[];
+}
+
+/**
+ * Extract services section from serialized docker-compose.yml.
+ */
+export function extractServices(yaml: string): Map<string, ParsedService> {
+  const services = new Map<string, ParsedService>();
+
+  const servicesIdx = yaml.search(/^services:\s*$/m);
+  if (servicesIdx === -1) return services;
+
+  const afterServices = yaml.slice(servicesIdx + yaml.slice(servicesIdx).indexOf("\n") + 1);
+  // Stop at next top-level key
+  const endMatch = afterServices.search(/^[a-z]/m);
+  const servicesContent = endMatch === -1 ? afterServices : afterServices.slice(0, endMatch);
+
+  // Split by service entries (2-space indent + name:)
+  const sections = servicesContent.split(/\n(?=  [a-z][a-z0-9_-]*:)/);
+
+  for (const section of sections) {
+    const nameMatch = section.match(/^\s{2}([a-z][a-z0-9_-]*):/);
+    if (!nameMatch) continue;
+
+    const name = nameMatch[1];
+    const svc: ParsedService = { name };
+
+    const imageMatch = section.match(/^\s{4}image:\s+(.+)$/m);
+    if (imageMatch) svc.image = imageMatch[1].trim().replace(/^['"]|['"]$/g, "");
+
+    const portsMatch = section.match(/^\s{4}ports:\n((?:\s{6}- .+\n?)+)/m);
+    if (portsMatch) {
+      svc.ports = [];
+      for (const line of portsMatch[1].split("\n")) {
+        const item = line.match(/^\s{6}-\s+['"]?(.+?)['"]?$/);
+        if (item) svc.ports.push(item[1].trim());
+      }
+    }
+
+    const volsMatch = section.match(/^\s{4}volumes:\n((?:\s{6}- .+\n?)+)/m);
+    if (volsMatch) {
+      svc.volumes = [];
+      for (const line of volsMatch[1].split("\n")) {
+        const item = line.match(/^\s{6}-\s+['"]?(.+?)['"]?$/);
+        if (item) svc.volumes.push(item[1].trim());
+      }
+    }
+
+    services.set(name, svc);
+  }
+
+  return services;
+}
+
+/**
+ * Extract named volumes from the top-level volumes: section.
+ */
+export function extractNamedVolumes(yaml: string): Set<string> {
+  const volumes = new Set<string>();
+
+  const volumesIdx = yaml.search(/^volumes:\s*$/m);
+  if (volumesIdx === -1) return volumes;
+
+  const afterVolumes = yaml.slice(volumesIdx + yaml.slice(volumesIdx).indexOf("\n") + 1);
+  const endMatch = afterVolumes.search(/^[a-z]/m);
+  const volumesContent = endMatch === -1 ? afterVolumes : afterVolumes.slice(0, endMatch);
+
+  for (const line of volumesContent.split("\n")) {
+    const match = line.match(/^\s{2}([a-z][a-z0-9_-]*):/);
+    if (match) volumes.add(match[1]);
+  }
+
+  return volumes;
+}
+
+/**
+ * Check if an image tag represents :latest or is untagged.
+ */
+export function isLatestOrUntagged(image: string): boolean {
+  if (!image || image.startsWith("${")) return false;
+  if (image.endsWith(":latest")) return true;
+  const parts = image.split("/");
+  const lastPart = parts[parts.length - 1];
+  return !lastPart.includes(":") && !lastPart.includes("@");
+}
+
+/**
+ * Get Dockerfile content from SerializerResult files map.
+ */
+export function extractDockerfiles(output: unknown): Map<string, string> {
+  const files = new Map<string, string>();
+  if (typeof output !== "object" || output === null) return files;
+  if (!("files" in output)) return files;
+
+  const outputFiles = (output as { files: Record<string, string> }).files;
+  for (const [name, content] of Object.entries(outputFiles)) {
+    if (name.startsWith("Dockerfile")) {
+      files.set(name, content);
+    }
+  }
+  return files;
+}

package/dist/rules/no-latest-image.ts

@@ -0,0 +1,36 @@
+/**
+ * DKRD001: No Latest Image Tag
+ *
+ * Detects services using :latest or untagged images in docker-compose.yml.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractServices, isLatestOrUntagged } from "./docker-helpers";
+
+export const dkrd001: PostSynthCheck = {
+  id: "DKRD001",
+  description: "Service uses :latest or untagged image — specify an explicit version tag",
+
+  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) {
+        if (svc.image && isLatestOrUntagged(svc.image)) {
+          diagnostics.push({
+            checkId: "DKRD001",
+            severity: "warning",
+            message: `Service "${name}" uses image "${svc.image}" which is :latest or untagged. Use an explicit version tag for reproducible builds.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/no-latest-tag.ts

@@ -0,0 +1,63 @@
+/**
+ * DKRS001: No Latest Tag
+ *
+ * Warns when a Service's image prop is set to a literal string
+ * ending with `:latest` or has no tag (implies latest).
+ * Using `:latest` prevents reproducible builds.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+function isLatestImage(imageValue: string): boolean {
+  const trimmed = imageValue.trim();
+  if (!trimmed || trimmed.startsWith("${")) return false;
+  // Has :latest tag
+  if (trimmed.endsWith(":latest")) return true;
+  // No tag at all (no colon after image name, no @sha256)
+  const parts = trimmed.split("/");
+  const lastPart = parts[parts.length - 1];
+  if (!lastPart.includes(":") && !lastPart.includes("@")) return true;
+  return false;
+}
+
+export const noLatestTagRule: LintRule = {
+  id: "DKRS001",
+  severity: "warning",
+  category: "correctness",
+  description: "Avoid :latest or untagged image references — use explicit version tags for reproducible builds",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for `image: "..."` in object literals (properties named "image")
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "image"
+      ) {
+        const init = node.initializer;
+        if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+          const text = init.text;
+          if (isLatestImage(text)) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            diagnostics.push({
+              file: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "DKRS001",
+              severity: "warning",
+              message: `Image "${text}" uses :latest or has no tag. Use an explicit version tag (e.g., "nginx:1.25-alpine") for reproducible builds.`,
+            });
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/no-root-user.ts

@@ -0,0 +1,36 @@
+/**
+ * DKRD012: No Root User
+ *
+ * Warns when a Dockerfile has no USER instruction,
+ * meaning the container runs as root by default.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+export const dkrd012: PostSynthCheck = {
+  id: "DKRD012",
+  description: "Dockerfile has no USER instruction — container runs as root",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const hasUser = /^USER\s+/m.test(content);
+        if (!hasUser) {
+          diagnostics.push({
+            checkId: "DKRD012",
+            severity: "warning",
+            message: `${fileName}: No USER instruction found. The container will run as root. Add a USER instruction to improve security.`,
+            lexicon: "docker",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/prefer-copy.ts

@@ -0,0 +1,53 @@
+/**
+ * DKRD011: Prefer COPY over ADD
+ *
+ * ADD has surprising behavior (auto-extracts archives, fetches URLs).
+ * Use COPY when you just need to copy local files.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractDockerfiles } from "./docker-helpers";
+
+function looksLikeUrl(src: string): boolean {
+  return src.startsWith("http://") || src.startsWith("https://") || src.startsWith("ftp://");
+}
+
+function looksLikeArchive(src: string): boolean {
+  return /\.(tar|tar\.gz|tgz|tar\.bz2|tar\.xz|zip)$/i.test(src);
+}
+
+export const dkrd011: PostSynthCheck = {
+  id: "DKRD011",
+  description: "Prefer COPY over ADD when not fetching URLs or extracting archives",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_outputName, output] of ctx.outputs) {
+      const dockerfiles = extractDockerfiles(output);
+
+      for (const [fileName, content] of dockerfiles) {
+        const lines = content.split("\n");
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (/^ADD\s+/.test(trimmed)) {
+            // Extract src argument (first token after ADD)
+            const parts = trimmed.replace(/^ADD\s+/, "").split(/\s+/);
+            const src = parts[0];
+
+            if (!looksLikeUrl(src) && !looksLikeArchive(src)) {
+              diagnostics.push({
+                checkId: "DKRD011",
+                severity: "info",
+                message: `${fileName}: Use COPY instead of ADD when not fetching URLs or extracting archives. ADD "${src}" could be COPY.`,
+                lexicon: "docker",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};