@intentius/chant-lexicon-docker 0.1.0

package/src/lint/rules/data/known-base-images.ts

@@ -0,0 +1,20 @@
+/**
+ * Well-known Docker base images for rule validation.
+ */
+
+export const KNOWN_BASE_IMAGES = new Set([
+  "alpine", "ubuntu", "debian", "centos", "fedora", "amazonlinux",
+  "node", "python", "ruby", "golang", "rust", "java", "openjdk",
+  "nginx", "httpd", "caddy", "traefik",
+  "postgres", "mysql", "mariadb", "mongodb", "redis", "memcached",
+  "rabbitmq", "kafka", "zookeeper",
+  "elasticsearch", "kibana", "logstash",
+  "busybox", "scratch",
+]);
+
+/**
+ * Images that are safe to use without a tag (they have meaningful `latest`).
+ */
+export const IMAGES_SAFE_LATEST = new Set([
+  "scratch",
+]);

package/src/lint/rules/index.ts

@@ -0,0 +1,5 @@
+/**
+ * All imperative lint rules for the Docker lexicon.
+ */
+
+export { noLatestTagRule } from "./no-latest-tag";

package/src/lint/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/src/lint/rules/rules.test.ts

@@ -0,0 +1,82 @@
+import { describe, test, expect } from "bun:test";
+import { noLatestTagRule } from "./no-latest-tag";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+function makeContext(code: string): LintContext {
+  const sourceFile = ts.createSourceFile(
+    "test.ts",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  return {
+    sourceFile,
+    entities: [],
+    filePath: "test.ts",
+    lexicon: "docker",
+  };
+}
+
+// ── DKRS001: no-latest-tag ────────────────────────────────────────
+
+describe("DKRS001: no-latest-tag", () => {
+  test("has correct id and severity", () => {
+    expect(noLatestTagRule.id).toBe("DKRS001");
+    expect(noLatestTagRule.severity).toBe("warning");
+    expect(noLatestTagRule.category).toBe("correctness");
+  });
+
+  test("flags :latest tag", () => {
+    const ctx = makeContext(`
+      import { Service } from "@intentius/chant-lexicon-docker";
+      export const api = new Service({ image: "nginx:latest" });
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].ruleId).toBe("DKRS001");
+    expect(diags[0].message).toContain("nginx:latest");
+  });
+
+  test("flags untagged image (no colon)", () => {
+    const ctx = makeContext(`
+      const svc = { image: "nginx" };
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].message).toContain("nginx");
+  });
+
+  test("does not flag explicitly versioned image", () => {
+    const ctx = makeContext(`
+      const svc = { image: "nginx:1.25-alpine" };
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag digest-pinned image", () => {
+    const ctx = makeContext(`
+      const svc = { image: "nginx@sha256:abc123" };
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag env() interpolation", () => {
+    const ctx = makeContext(`
+      const svc = { image: "\${APP_IMAGE:-myapp:latest}" };
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag non-image string properties", () => {
+    const ctx = makeContext(`
+      const svc = { restart: "latest" };
+    `);
+    const diags = noLatestTagRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect } from "bun:test";
+import { dockerCompletions } from "./completions";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+
+describe("dockerCompletions", () => {
+  test("is a function", () => {
+    expect(typeof dockerCompletions).toBe("function");
+  });
+
+  test("returns array for non-constructor context", () => {
+    const ctx: CompletionContext = {
+      word: "Ser",
+      isConstructorContext: false,
+      prefix: "",
+      fileContent: "",
+      position: { line: 0, character: 3 },
+    };
+    // May return [] if generated index not present, but should not throw
+    const result = dockerCompletions(ctx);
+    expect(Array.isArray(result)).toBe(true);
+  });
+
+  test("returns array for constructor context", () => {
+    const ctx: CompletionContext = {
+      word: "Service",
+      isConstructorContext: true,
+      prefix: "new ",
+      fileContent: "import { Service } from '@intentius/chant-lexicon-docker';",
+      position: { line: 0, character: 10 },
+    };
+    const result = dockerCompletions(ctx);
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,20 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-docker.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide Docker entity completions based on context.
+ */
+export function dockerCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "Docker entity");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect } from "bun:test";
+import { dockerHover } from "./hover";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+
+describe("dockerHover", () => {
+  test("is a function", () => {
+    expect(typeof dockerHover).toBe("function");
+  });
+
+  test("returns undefined for unknown word", () => {
+    const ctx: HoverContext = {
+      word: "NotADockerThing",
+      fileContent: "",
+      position: { line: 0, character: 0 },
+    };
+    // Should not throw; returns undefined if not found
+    const result = dockerHover(ctx);
+    expect(result === undefined || typeof result === "object").toBe(true);
+  });
+
+  test("returns HoverInfo with content for known resource", () => {
+    const ctx: HoverContext = {
+      word: "Service",
+      fileContent: "import { Service } from '@intentius/chant-lexicon-docker';",
+      position: { line: 0, character: 10 },
+    };
+    const result = dockerHover(ctx);
+    // If generated index exists, will return content; otherwise undefined
+    if (result !== undefined) {
+      expect(result.contents).toBeTruthy();
+      expect(typeof result.contents).toBe("string");
+    }
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,38 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-docker.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for Docker entity types.
+ */
+export function dockerHover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`Docker type: \`${entry.resourceType}\``);
+
+  if (entry.resourceType.startsWith("Docker::Compose::")) {
+    lines.push("");
+    lines.push("*Compose resource — serialized into docker-compose.yml*");
+  } else if (entry.resourceType === "Docker::Dockerfile") {
+    lines.push("");
+    lines.push("*Dockerfile resource — serialized as Dockerfile.{name}*");
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/package-cli.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/**
+ * Thin entry point for `bun run bundle` in lexicon-docker.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// 1. Generate src/generated/ files
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult, pkgDir);
+console.error(`Generated ${genResult.resources} entities, ${genResult.properties} property types, ${genResult.enums} enums`);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(pkgDir, "dist");
+mkdirSync(join(distDir, "types"), { recursive: true });
+mkdirSync(join(distDir, "rules"), { recursive: true });
+mkdirSync(join(distDir, "skills"), { recursive: true });
+
+writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
+writeFileSync(join(distDir, "meta.json"), spec.registry);
+writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
+
+for (const [name, content] of spec.rules) {
+  writeFileSync(join(distDir, "rules", name), content);
+}
+for (const [name, content] of spec.skills) {
+  writeFileSync(join(distDir, "skills", name), content);
+}
+
+if (spec.integrity) {
+  writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
+}
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "bun:test";
+import { dockerPlugin } from "./plugin";
+
+describe("dockerPlugin", () => {
+  test("has correct name", () => {
+    expect(dockerPlugin.name).toBe("docker");
+  });
+
+  test("has serializer", () => {
+    expect(dockerPlugin.serializer).toBeDefined();
+    expect(dockerPlugin.serializer.name).toBe("docker");
+  });
+
+  test("provides lint rules", () => {
+    const rules = dockerPlugin.lintRules!();
+    expect(rules.length).toBeGreaterThanOrEqual(1);
+
+    const ruleIds = rules.map((r) => r.id);
+    expect(ruleIds).toContain("DKRS001");
+  });
+
+  test("provides post-synth checks", () => {
+    const checks = dockerPlugin.postSynthChecks!();
+    expect(checks.length).toBeGreaterThanOrEqual(1);
+
+    const checkIds = checks.map((c) => c.id);
+    expect(checkIds).toContain("DKRD001");
+    expect(checkIds).toContain("DKRD002");
+    expect(checkIds).toContain("DKRD003");
+    expect(checkIds).toContain("DKRD010");
+    expect(checkIds).toContain("DKRD011");
+    expect(checkIds).toContain("DKRD012");
+  });
+
+  test("provides intrinsics", () => {
+    const intrinsics = dockerPlugin.intrinsics!();
+    expect(intrinsics.length).toBe(1);
+    expect(intrinsics[0].name).toBe("env");
+  });
+
+  test("provides init templates — default", () => {
+    const template = dockerPlugin.initTemplates!();
+    expect(template.src).toBeDefined();
+    expect(template.src["compose.ts"]).toContain("Service");
+  });
+
+  test("provides init templates — webapp", () => {
+    const template = dockerPlugin.initTemplates!("webapp");
+    expect(template.src["compose.ts"]).toContain("postgres");
+  });
+
+  test("detects Docker Compose template", () => {
+    expect(dockerPlugin.detectTemplate!({ services: {}, volumes: {} })).toBe(true);
+  });
+
+  test("rejects non-Docker data", () => {
+    expect(dockerPlugin.detectTemplate!({ jobs: {}, on: {} })).toBe(false);
+    expect(dockerPlugin.detectTemplate!(null)).toBe(false);
+  });
+
+  test("has completionProvider", () => {
+    expect(dockerPlugin.completionProvider).toBeDefined();
+  });
+
+  test("has hoverProvider", () => {
+    expect(dockerPlugin.hoverProvider).toBeDefined();
+  });
+
+  test("has templateParser", () => {
+    expect(dockerPlugin.templateParser).toBeDefined();
+  });
+
+  test("has templateGenerator", () => {
+    expect(dockerPlugin.templateGenerator).toBeDefined();
+  });
+
+  test("has generate method", () => {
+    expect(dockerPlugin.generate).toBeDefined();
+  });
+
+  test("has validate method", () => {
+    expect(dockerPlugin.validate).toBeDefined();
+  });
+
+  test("has coverage method", () => {
+    expect(dockerPlugin.coverage).toBeDefined();
+  });
+
+  test("has package method", () => {
+    expect(dockerPlugin.package).toBeDefined();
+  });
+
+  test("has docs method", () => {
+    expect(dockerPlugin.docs).toBeDefined();
+  });
+
+  test("provides skills", () => {
+    const skills = dockerPlugin.skills!();
+    expect(skills.length).toBeGreaterThanOrEqual(2);
+    const names = skills.map((s) => s.name);
+    expect(names).toContain("chant-docker");
+    expect(names).toContain("chant-docker-patterns");
+  });
+
+  test("provides MCP tools", () => {
+    const tools = dockerPlugin.mcpTools!();
+    expect(tools.length).toBe(1);
+    expect(tools[0].name).toBe("diff");
+  });
+
+  test("provides MCP resources", () => {
+    const resources = dockerPlugin.mcpResources!();
+    expect(resources.length).toBe(2);
+    expect(resources[0].uri).toBe("resource-catalog");
+    expect(resources[1].uri).toBe("examples/basic-app");
+  });
+});