@intentius/chant-lexicon-docker 0.124.31 → 0.124.32

package/src/import/generator.ts

@@ -19,33 +19,26 @@ export class DockerGenerator {
     const warnings: string[] = [];
     const imports = new Set<string>();
     const lines: string[] = [];
+    const names = new ExportNames();
 
     for (const entity of entities) {
-      switch (entity.kind) {
-        case "service":
-          imports.add("Service");
-          lines.push(generateService(entity));
-          break;
-        case "volume":
-          imports.add("Volume");
-          lines.push(generateVolume(entity));
-          break;
-        case "network":
-          imports.add("Network");
-          lines.push(generateNetwork(entity));
-          break;
-        case "config":
-          imports.add("DockerConfig");
-          lines.push(generateConfig(entity));
-          break;
-        case "secret":
-          imports.add("DockerSecret");
-          lines.push(generateSecret(entity));
-          break;
-        case "dockerfile":
-          imports.add("Dockerfile");
-          lines.push(generateDockerfile(entity, warnings));
-          break;
+      if (entity.kind === "dockerfile") {
+        imports.add("Dockerfile");
+        lines.push(generateDockerfile(entity, warnings));
+        continue;
+      }
+      const ctor = CONSTRUCTORS[entity.kind];
+      imports.add(ctor);
+      const exportName = names.take(entity.name, entity.kind);
+      const expr = `new ${ctor}(${propsLiteral(entity)})`;
+      // An export name that differs from the compose key would rename the
+      // key on build, and every reference to it by name would dangle, so
+      // the key is set explicitly (#3937).
+      if (exportName === entity.name) {
+        lines.push(`export const ${exportName} = ${expr};`);
+      } else {
+        imports.add("composeKey");
+        lines.push(`export const ${exportName} = composeKey(${JSON.stringify(entity.name)}, ${expr});`);
       }
     }
 
@@ -56,30 +49,56 @@ export class DockerGenerator {
   }
 }
 
-function generateService(svc: ServiceIR): string {
-  const propsStr = JSON.stringify(svc.props, null, 2)
-    .replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
-  return `export const ${sanitizeName(svc.name)} = new Service(${propsStr});`;
-}
-
-function generateVolume(vol: VolumeIR): string {
-  const hasProps = Object.keys(vol.props).length > 0;
-  return `export const ${sanitizeName(vol.name)} = new Volume(${hasProps ? JSON.stringify(vol.props) : "{}"});`;
-}
-
-function generateNetwork(net: NetworkIR): string {
-  const hasProps = Object.keys(net.props).length > 0;
-  return `export const ${sanitizeName(net.name)} = new Network(${hasProps ? JSON.stringify(net.props) : "{}"});`;
+const CONSTRUCTORS = {
+  service: "Service",
+  volume: "Volume",
+  network: "Network",
+  config: "DockerConfig",
+  secret: "DockerSecret",
+} as const;
+
+function propsLiteral(entity: ServiceIR | VolumeIR | NetworkIR | ConfigIR | SecretIR): string {
+  if (entity.kind === "service") {
+    return JSON.stringify(entity.props, null, 2).replace(/"([a-z_][a-z0-9_]*)":/g, "$1:");
+  }
+  return Object.keys(entity.props).length > 0 ? JSON.stringify(entity.props) : "{}";
 }
 
-function generateConfig(cfg: ConfigIR): string {
-  const hasProps = Object.keys(cfg.props).length > 0;
-  return `export const ${sanitizeName(cfg.name)} = new DockerConfig(${hasProps ? JSON.stringify(cfg.props) : "{}"});`;
-}
+/** Words an export cannot be named, and the names the generated file imports. */
+const RESERVED = new Set([
+  "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do",
+  "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "import", "in",
+  "instanceof", "new", "null", "return", "super", "switch", "this", "throw", "true", "try", "typeof",
+  "var", "void", "while", "with", "yield", "let", "static", "implements", "interface", "package",
+  "private", "protected", "public", "await", "arguments", "eval", "undefined", "NaN", "Infinity",
+  "Service", "Volume", "Network", "DockerConfig", "DockerSecret", "Dockerfile", "composeKey",
+]);
 
-function generateSecret(sec: SecretIR): string {
-  const hasProps = Object.keys(sec.props).length > 0;
-  return `export const ${sanitizeName(sec.name)} = new DockerSecret(${hasProps ? JSON.stringify(sec.props) : "{}"});`;
+/**
+ * Export names for compose keys: identifiers, unique within the file. A key
+ * shared by two kinds (a service and a volume both named `db`) gives the
+ * second one a kind suffix (`dbVolume`).
+ */
+class ExportNames {
+  private readonly used = new Set<string>();
+
+  take(key: string, kind: string): string {
+    const base = sanitizeName(key);
+    const suffixed = `${base}${kind[0]!.toUpperCase()}${kind.slice(1)}`;
+    for (const c of [base, suffixed]) {
+      if (!RESERVED.has(c) && !this.used.has(c)) {
+        this.used.add(c);
+        return c;
+      }
+    }
+    for (let i = 2; ; i++) {
+      const c = `${suffixed}${i}`;
+      if (!this.used.has(c)) {
+        this.used.add(c);
+        return c;
+      }
+    }
+  }
 }
 
 /** The instructions a step can name; anything else (MAINTAINER) is left as a comment. */
@@ -137,7 +156,15 @@ function quote(value: string): string {
   return JSON.stringify(value);
 }
 
+/**
+ * A TypeScript identifier for a compose key: kebab, snake and dotted keys
+ * become camelCase, other characters are dropped, and a leading digit gets
+ * an underscore.
+ */
 function sanitizeName(name: string): string {
-  // Convert kebab/snake to camelCase
-  return name.replace(/[-_]([a-z])/g, (_, c) => c.toUpperCase());
+  let id = name.replace(/[^A-Za-z0-9$]+([A-Za-z0-9])/g, (_, c: string) => c.toUpperCase());
+  id = id.replace(/[^A-Za-z0-9_$]/g, "");
+  if (id === "") id = "entity";
+  if (/^[0-9]/.test(id)) id = `_${id}`;
+  return id;
 }

package/src/import/parser.ts

@@ -3,6 +3,9 @@
  * to an intermediate representation (IR) for TypeScript code generation.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseYAML } from "@intentius/chant/yaml";
 
 export interface ServiceIR {
@@ -61,26 +64,58 @@ export interface ParseResult {
   warnings: string[];
 }
 
-const SERVICE_PROPS = [
-  "image", "ports", "environment", "volumes", "depends_on",
-  "restart", "healthcheck", "labels", "command", "entrypoint",
-  "networks", "build", "deploy", "secrets", "configs",
+/** The compose sections import reads, with the kind each holds and its entry in the lexicon. */
+const SECTIONS = [
+  { section: "services", kind: "service", entry: "Service" },
+  { section: "volumes", kind: "volume", entry: "Volume" },
+  { section: "networks", kind: "network", entry: "Network" },
+  { section: "configs", kind: "config", entry: "DockerConfig" },
+  { section: "secrets", kind: "secret", entry: "DockerSecret" },
 ] as const;
 
-const VOLUME_PROPS = ["driver", "driver_opts", "external", "labels"] as const;
-const NETWORK_PROPS = ["driver", "external", "attachable", "labels"] as const;
-const CONFIG_PROPS = ["file", "external"] as const;
-const SECRET_PROPS = ["file", "external"] as const;
+type ComposeKind = (typeof SECTIONS)[number]["kind"];
 
+let fieldsCache: Map<ComposeKind, Set<string>> | undefined;
+
+/**
+ * The fields the Compose spec defines for each kind, read from the generated
+ * lexicon (`lexicon-docker.json`, or `dist/meta.json` in a package built
+ * without it). The props types come from the same spec (#3934), so import
+ * keeps exactly what the types accept (#3937).
+ */
+export function composeFields(): Map<ComposeKind, Set<string>> {
+  if (fieldsCache) return fieldsCache;
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join(here, "..", "generated", "lexicon-docker.json"), join(here, "..", "..", "dist", "meta.json")];
+  const path = candidates.find((c) => existsSync(c));
+  if (!path) {
+    throw new Error(`docker import: the generated lexicon is missing (tried ${candidates.join(", ")}); run npm run generate in lexicons/docker`);
+  }
+  const lexicon = JSON.parse(readFileSync(path, "utf-8")) as Record<string, { properties?: Record<string, unknown> }>;
+  const fields = new Map<ComposeKind, Set<string>>();
+  for (const { kind, entry } of SECTIONS) {
+    fields.set(kind, new Set(Object.keys(lexicon[entry]?.properties ?? {})));
+  }
+  fieldsCache = fields;
+  return fields;
+}
+
+/**
+ * Keep every field the Compose spec defines for the kind, and `x-`
+ * extension fields. Anything else is dropped and named in `warnings`.
+ */
 function extractProps(
   raw: unknown,
-  allowed: readonly string[],
+  allowed: Set<string>,
+  where: string,
+  kind: string,
+  warnings: string[],
 ): Record<string, unknown> {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const obj = raw as Record<string, unknown>;
   const props: Record<string, unknown> = {};
-  for (const key of allowed) {
-    if (key in obj) props[key] = obj[key];
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (allowed.has(key) || key.startsWith("x-")) props[key] = value;
+    else warnings.push(`${where}: "${key}" is not a Compose ${kind} field and was dropped`);
   }
   return props;
 }
@@ -96,64 +131,22 @@ export class DockerParser {
     const entities: DockerIR[] = [];
     const warnings: string[] = [];
     const doc = parseYAML(content) as Record<string, unknown>;
+    const fields = composeFields();
 
-    // services
-    const services = doc["services"];
-    if (services && typeof services === "object" && !Array.isArray(services)) {
-      for (const [name, raw] of Object.entries(services as Record<string, unknown>)) {
-        entities.push({
-          kind: "service",
-          name,
-          props: extractProps(raw, SERVICE_PROPS),
-        });
-      }
-    }
-
-    // volumes
-    const volumes = doc["volumes"];
-    if (volumes && typeof volumes === "object" && !Array.isArray(volumes)) {
-      for (const [name, raw] of Object.entries(volumes as Record<string, unknown>)) {
-        entities.push({
-          kind: "volume",
-          name,
-          props: extractProps(raw, VOLUME_PROPS),
-        });
-      }
-    }
-
-    // networks
-    const networks = doc["networks"];
-    if (networks && typeof networks === "object" && !Array.isArray(networks)) {
-      for (const [name, raw] of Object.entries(networks as Record<string, unknown>)) {
-        entities.push({
-          kind: "network",
-          name,
-          props: extractProps(raw, NETWORK_PROPS),
-        });
-      }
-    }
-
-    // configs
-    const configs = doc["configs"];
-    if (configs && typeof configs === "object" && !Array.isArray(configs)) {
-      for (const [name, raw] of Object.entries(configs as Record<string, unknown>)) {
-        entities.push({
-          kind: "config",
-          name,
-          props: extractProps(raw, CONFIG_PROPS),
-        });
-      }
+    const known = new Set<string>(SECTIONS.map((s) => s.section));
+    for (const key of Object.keys(doc ?? {})) {
+      if (!known.has(key)) warnings.push(`"${key}" at the top level is not imported`);
     }
 
-    // secrets
-    const secrets = doc["secrets"];
-    if (secrets && typeof secrets === "object" && !Array.isArray(secrets)) {
-      for (const [name, raw] of Object.entries(secrets as Record<string, unknown>)) {
+    for (const { section, kind } of SECTIONS) {
+      const entries = doc?.[section];
+      if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
+      for (const [name, raw] of Object.entries(entries as Record<string, unknown>)) {
         entities.push({
-          kind: "secret",
+          kind,
           name,
-          props: extractProps(raw, SECRET_PROPS),
-        });
+          props: extractProps(raw, fields.get(kind)!, `${section}.${name}`, kind, warnings),
+        } as DockerIR);
       }
     }
 

package/src/import/roundtrip.test.ts

@@ -178,8 +178,6 @@ function buildImport(source: string): string {
 
 describe("roundtrip: compose → TypeScript → compose", () => {
   test("configs and secrets import as DockerConfig and DockerSecret and build the same file", () => {
-    // Names without hyphens: the generator camel-cases export names, which renames a
-    // hyphenated key (db-password becomes dbPassword, #3937).
     const content = testdata("configs-secrets.yaml");
     const { entities } = new DockerParser().parse(content);
     const { source } = new DockerGenerator().generate(entities);
@@ -188,6 +186,50 @@ describe("roundtrip: compose → TypeScript → compose", () => {
     expect(source).toContain("new DockerSecret(");
     expect(parseYAML(buildImport(source))).toEqual(parseYAML(content));
   });
+
+  test("full.yaml builds the same file: every field kept, hyphenated keys kept (#3937)", () => {
+    const content = testdata("full.yaml");
+    const { entities, warnings } = new DockerParser().parse(content);
+    expect(warnings).toEqual([]);
+    const { source } = new DockerGenerator().generate(entities);
+    expect(parseYAML(buildImport(source))).toEqual(parseYAML(content));
+  });
+
+  test("fields outside the old fixed list, x- extensions, and keys that are not identifiers survive (#3937)", () => {
+    const content = testdata("names-and-fields.yaml");
+    const { entities, warnings } = new DockerParser().parse(content);
+    expect(warnings).toEqual([]);
+    const { source } = new DockerGenerator().generate(entities);
+    expect(parseYAML(buildImport(source))).toEqual(parseYAML(content));
+  });
+
+  test("through the chant import adapter", () => {
+    const content = testdata("names-and-fields.yaml");
+    const [file] = new DockerTemplateGenerator().generate(new DockerTemplateParser().parse(content));
+    expect(parseYAML(buildImport(file!.content))).toEqual(parseYAML(content));
+  });
+});
+
+describe("compose import warns on what it cannot keep (#3937)", () => {
+  test("a field the Compose spec does not define is dropped with a warning", () => {
+    const content = "services:\n  api:\n    image: nginx\n    not_a_field: 1\nnetworks:\n  n:\n    bogus: true\n";
+    const { entities, warnings } = new DockerParser().parse(content);
+    expect(entities.find((e) => e.name === "api")).toMatchObject({ props: { image: "nginx" } });
+    expect(warnings).toEqual([
+      'services.api: "not_a_field" is not a Compose service field and was dropped',
+      'networks.n: "bogus" is not a Compose network field and was dropped',
+    ]);
+  });
+
+  test("a top-level section import does not carry is named", () => {
+    const { warnings } = new DockerParser().parse("name: proj\nservices:\n  a:\n    image: x\n");
+    expect(warnings).toEqual(['"name" at the top level is not imported']);
+  });
+
+  test("the adapter hands parser warnings to chant import", () => {
+    const ir = new DockerTemplateParser().parse("services:\n  api:\n    image: nginx\n    not_a_field: 1\n");
+    expect(ir.warnings).toEqual(['services.api: "not_a_field" is not a Compose service field and was dropped']);
+  });
 });
 
 describe("every name the importers emit is exported by the lexicon", () => {
@@ -198,7 +240,8 @@ describe("every name the importers emit is exported by the lexicon", () => {
     ];
     expect(new Set(entities.map((e) => e.kind))).toEqual(new Set(["service", "volume", "network", "config", "secret", "dockerfile"]));
     const names = importedNames(new DockerGenerator().generate(entities).source);
-    expect(names.length).toBe(6);
+    // The six constructors, and composeKey for full.yaml's hyphenated keys.
+    expect(names.length).toBe(7);
     for (const name of names) {
       expect(typeof (lexicon as Record<string, unknown>)[name], name).toBe("function");
     }

package/src/import/testdata/names-and-fields.yaml

@@ -0,0 +1,44 @@
+services:
+  web-app:
+    image: myapp:latest
+    working_dir: /srv
+    user: "1000:1000"
+    env_file:
+      - .env
+    stop_grace_period: 30s
+    x-team: platform
+    depends_on:
+      - db_primary
+    volumes:
+      - "app-data:/data"
+    networks:
+      - back-tier
+    secrets:
+      - db-password
+    configs:
+      - nginx.conf
+  db_primary:
+    image: postgres:16
+  db:
+    image: postgres:16
+    volumes:
+      - "db:/var/lib/postgresql/data"
+volumes:
+  app-data:
+    name: shared-app-data
+  db:
+networks:
+  back-tier:
+    internal: true
+    driver_opts:
+      com.docker.network.bridge.name: br-back
+configs:
+  nginx.conf:
+    content: |
+      server {}
+    name: nginx-conf
+    labels:
+      tier: edge
+secrets:
+  db-password:
+    environment: DB_PASSWORD

package/src/index.ts

@@ -17,6 +17,9 @@ export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotation
 export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-labels";
 export type { DefaultLabels, DefaultAnnotations } from "./default-labels";
 
+// Compose keys that are not identifiers (#3937)
+export { composeKey, getComposeKey, COMPOSE_KEY } from "./compose-key";
+
 // Generated entities — populated by `npm run generate`
 export * from "./generated/index";
 

package/src/lsp/completions.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 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);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 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);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/serializer.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { dockerSerializer } from "./serializer";
+import { composeKey } from "./compose-key";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 
@@ -489,3 +490,33 @@ describe("telemetry attribution", () => {
     );
   });
 });
+
+describe("composeKey (#3937)", () => {
+  test("the entity takes the key, and a reference to it serializes as the key", () => {
+    const data = composeKey("app-data", new MockVolume({ driver: "local" }));
+    const out = dockerSerializer.serialize(new Map<string, Declarable>([
+      ["web", composeKey("web-app", new MockService({ image: "nginx", volumes: [data] }))],
+      ["appData", data],
+    ])) as string;
+    expect(out).toContain("  web-app:\n");
+    expect(out).toContain("  app-data:\n");
+    expect(out).toContain("      - app-data\n");
+    expect(out).not.toContain("appData");
+  });
+
+  test("two entities of one kind with the same key is an error", () => {
+    expect(() => dockerSerializer.serialize(new Map<string, Declarable>([
+      ["db", new MockService({ image: "postgres" })],
+      ["primary", composeKey("db", new MockService({ image: "postgres" }))],
+    ]))).toThrow('docker: db and primary both take the compose key "db"');
+  });
+
+  test("a service and a volume may share a key", () => {
+    const out = dockerSerializer.serialize(new Map<string, Declarable>([
+      ["db", new MockService({ image: "postgres" })],
+      ["dbVolume", composeKey("db", new MockVolume({}))],
+    ])) as string;
+    expect(out).toContain("services:\n  db:\n");
+    expect(out).toContain("volumes:\n  db:");
+  });
+});

package/src/serializer.ts

@@ -17,6 +17,7 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import { emitYAMLEntry } from "@intentius/chant/yaml";
+import { getComposeKey } from "./compose-key";
 import { EXEC_FORM_STEPS, PER_KIND_ORDER, STEP_INSTRUCTIONS } from "./dockerfile-order";
 
 // ── Helpers ───────────────────────────────────────────────────────
@@ -368,9 +369,20 @@ export const dockerSerializer: Serializer = {
     _outputs?: LexiconOutput[],
     context?: SerializeContext,
   ): string | SerializerResult {
+    // A compose entity's key is its export name unless composeKey set one
+    // (#3937); references to it serialize as the same key. Two entities of
+    // one kind cannot share a key.
     const entityNames = new Map<Declarable, string>();
+    const taken = new Map<string, { name: string; entity: Declarable }>();
     for (const [name, entity] of entities) {
-      entityNames.set(entity, name);
+      const key = getComposeKey(entity) ?? name;
+      entityNames.set(entity, key);
+      const slot = `${(entity as unknown as Record<string, unknown>).entityType}\0${key}`;
+      const other = taken.get(slot);
+      if (other !== undefined && other.entity !== entity) {
+        throw new Error(`docker: ${other.name} and ${name} both take the compose key "${key}"`);
+      }
+      taken.set(slot, { name, entity });
     }
 
     const services = new Map<string, Declarable>();
@@ -381,7 +393,8 @@ export const dockerSerializer: Serializer = {
     const dockerfiles = new Map<string, Declarable>();
     let defaultLabels: Record<string, string> = {};
 
-    for (const [name, entity] of entities) {
+    for (const [exportName, entity] of entities) {
+      const name = entityNames.get(entity) ?? exportName;
       // Skip property-kind entities
       if (isPropertyDeclarable(entity)) continue;