@intentius/chant-lexicon-docker 0.124.31 → 0.124.32

package/dist/spec/parse-compose.js

@@ -0,0 +1,160 @@
+/**
+ * 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.
+ */
+/**
+ * The TypeScript type of a Compose string slot. Compose interpolates every
+ * value, so `env()` fits where a string does; an entity (a service, network,
+ * volume, config, secret or Dockerfile) is written as its name.
+ */
+export const COMPOSE_STRING = "ComposeString";
+const ENTITIES = [
+    { def: "service", shortName: "Service", description: "A containerized service definition in Docker Compose" },
+    { def: "volume", shortName: "Volume", description: "A named volume definition in Docker Compose" },
+    { def: "network", shortName: "Network", description: "A network definition in Docker Compose" },
+    { def: "config", shortName: "Config", description: "A config definition in Docker Compose" },
+    { def: "secret", shortName: "Secret", description: "A secret definition in Docker Compose" },
+];
+/**
+ * Parse the Compose Spec JSON Schema buffer into ParsedResult entries.
+ * Returns one entry per top-level Compose resource type, with a property for
+ * every field the spec defines on it (#3934). Each property's `type` is a
+ * TypeScript type converted from the schema; string slots use
+ * {@link COMPOSE_STRING}.
+ */
+export function parseComposeSpec(data) {
+    const spec = JSON.parse(data.toString("utf-8"));
+    const defs = spec.$defs ?? spec.definitions ?? {};
+    return ENTITIES.map(({ def, shortName, description }) => {
+        const schema = defs[def];
+        const required = new Set(schema?.required ?? []);
+        const properties = Object.entries(schema?.properties ?? {}).map(([name, prop]) => ({
+            name,
+            type: toTsType(prop, defs, new Set([def])),
+            ...(prop.description ? { description: oneLine(prop.description) } : {}),
+            ...(required.has(name) ? { required: true } : {}),
+        }));
+        return { typeName: `Docker::Compose::${shortName}`, shortName, description, isResource: true, properties };
+    });
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").replace(/\*\//g, "* /").trim();
+}
+/** A property name as a TypeScript key: bare when it is an identifier. */
+function key(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/** Convert one JSON Schema node to a TypeScript type. `seen` guards $ref cycles. */
+export function toTsType(schema, defs, seen = new Set()) {
+    if (schema === undefined || schema === true)
+        return "unknown";
+    if (schema === false)
+        return "never";
+    if (schema.$ref) {
+        const name = schema.$ref.replace(/^#\/(\$defs|definitions)\//, "");
+        const target = defs[name];
+        if (!target || seen.has(name))
+            return "unknown";
+        return toTsType(target, defs, new Set([...seen, name]));
+    }
+    const alts = schema.oneOf ?? schema.anyOf;
+    if (alts) {
+        // A oneOf beside a type or properties narrows them; the alternatives carry the shape.
+        return union(alts.map((a) => toTsType(a, defs, seen)));
+    }
+    if (schema.allOf) {
+        const parts = schema.allOf.map((a) => toTsType(a, defs, seen)).filter((t) => t !== "unknown");
+        return parts.length ? parts.map(paren).join(" & ") : "unknown";
+    }
+    if (schema.const !== undefined)
+        return JSON.stringify(schema.const);
+    if (schema.enum)
+        return union(schema.enum.map((v) => JSON.stringify(v)));
+    const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+    if (types.length === 0) {
+        if (schema.properties || schema.patternProperties || schema.additionalProperties !== undefined)
+            return objectType(schema, defs, seen);
+        if (schema.items)
+            return `Array<${toTsType(schema.items, defs, seen)}>`;
+        return "unknown";
+    }
+    return union(types.map((t) => {
+        switch (t) {
+            case "string":
+                return COMPOSE_STRING;
+            case "number":
+            case "integer":
+                return "number";
+            case "boolean":
+                return "boolean";
+            case "null":
+                return "null";
+            case "array":
+                return `Array<${schema.items ? toTsType(schema.items, defs, seen) : "unknown"}>`;
+            case "object":
+                return objectType(schema, defs, seen);
+            default:
+                return "unknown";
+        }
+    }));
+}
+function objectType(schema, defs, seen) {
+    const props = Object.entries(schema.properties ?? {});
+    const patterns = Object.entries(schema.patternProperties ?? {});
+    const extensions = patterns.some(([p]) => p === "^x-");
+    const others = patterns.filter(([p]) => p !== "^x-");
+    const additional = schema.additionalProperties;
+    if (props.length === 0) {
+        const values = others.map(([, v]) => toTsType(v, defs, seen));
+        if (additional && additional !== true)
+            values.push(toTsType(additional, defs, seen));
+        if (values.length)
+            return `Record<string, ${union(values)}>`;
+        return additional === false && !extensions ? "Record<string, never>" : "Record<string, unknown>";
+    }
+    const required = new Set(schema.required ?? []);
+    const fields = props.map(([name, p]) => `${key(name)}${required.has(name) ? "" : "?"}: ${toTsType(p, defs, seen)}`);
+    if (extensions)
+        fields.push("[key: `x-${string}`]: unknown");
+    // Free-form keys beside the named ones: the named ones keep their types.
+    if (others.length || (additional && additional !== true))
+        fields.push("[key: string]: unknown");
+    return `{ ${fields.join("; ")} }`;
+}
+function paren(t) {
+    return /[|&]/.test(t) && !/^[{(]/.test(t) ? `(${t})` : t;
+}
+function union(types) {
+    const unique = [...new Set(types.flatMap(splitTop))];
+    if (unique.includes("unknown"))
+        return "unknown";
+    return unique.join(" | ");
+}
+/** The members of a union type, split only at the top level. */
+function splitTop(type) {
+    const out = [];
+    let depth = 0;
+    let quote = false;
+    let start = 0;
+    for (let i = 0; i < type.length; i++) {
+        const c = type[i];
+        if (c === '"')
+            quote = !quote;
+        if (quote)
+            continue;
+        if (c === "{" || c === "(" || c === "<" || c === "[")
+            depth++;
+        else if (c === "}" || c === ")" || c === ">" || c === "]")
+            depth--;
+        else if (depth === 0 && type.startsWith(" | ", i)) {
+            out.push(type.slice(start, i));
+            start = i + 3;
+            i += 2;
+        }
+    }
+    out.push(type.slice(start));
+    return out;
+}

package/dist/spec/parse-engine.js

@@ -0,0 +1,36 @@
+/**
+ * Parse the Docker Engine API OpenAPI spec for Dockerfile-related types.
+ *
+ * We extract only the image-builder relevant definitions:
+ * ContainerConfig, BuildInfo, and related types.
+ */
+/**
+ * Parse the Docker Engine API YAML buffer for Dockerfile instruction types.
+ * Returns a single DockerfileParseResult describing the Dockerfile entity.
+ */
+export function parseEngineApi(_data) {
+    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, execForm: 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, numeric: true },
+            { name: "volume", description: "Create mount points", multi: true },
+            { name: "label", description: "Add metadata labels", multi: true },
+            { name: "entrypoint", description: "Set the entrypoint executable", execForm: true },
+            { name: "cmd", description: "Default command arguments", execForm: true },
+            { name: "healthcheck", description: "Health check instruction" },
+            { name: "shell", description: "Set the shell for shell-form commands (JSON array form)", stepOnly: true, execForm: true },
+            { name: "stopsignal", description: "Signal sent to stop the container", stepOnly: true },
+            { name: "onbuild", description: "Instruction to run when the image is used as a base", stepOnly: true },
+        ],
+    };
+}

package/dist/types/index.d.ts

@@ -194,6 +194,8 @@ export interface ServiceProps {
   volumes_from?: Array<ComposeString>;
   /** The working directory in which the entrypoint or command will be run */
   working_dir?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A named volume definition in Docker Compose */
@@ -208,6 +210,8 @@ export interface VolumeProps {
   external?: boolean | ComposeString | { name?: ComposeString; [key: `x-${string}`]: unknown };
   /** Add metadata to the volume using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A network definition in Docker Compose */
@@ -232,6 +236,8 @@ export interface NetworkProps {
   attachable?: boolean | ComposeString;
   /** Add metadata to the network using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A config definition in Docker Compose */
@@ -250,6 +256,8 @@ export interface DockerConfigProps {
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
   /** Driver to use for templating the config's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A secret definition in Docker Compose */
@@ -270,6 +278,8 @@ export interface DockerSecretProps {
   driver_opts?: Record<string, ComposeString | number>;
   /** Driver to use for templating the secret's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 export declare const Service: new (props?: ServiceProps, attributes?: Record<string, unknown>) => Declarable;

package/dist/validate-cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run validate` in lexicon-docker.
+ */
+import { validate } from "./validate.js";
+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/dist/validate.js

@@ -0,0 +1,37 @@
+/**
+ * Validate generated lexicon-docker artifacts.
+ */
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } 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) {
+    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/dist/variables.js

@@ -0,0 +1,42 @@
+/**
+ * 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",
+};
+/** 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",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-docker",
-  "version": "0.124.31",
+  "version": "0.124.32",
   "description": "Docker lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -33,22 +33,22 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./detect": {
       "development": "./src/detect.ts",
       "types": "./dist/detect.d.ts",
-      "default": "./src/detect.ts"
+      "default": "./dist/detect.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -60,16 +60,16 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
   },
   "dependencies": {
-    "@intentius/chant-lexicon-otel": "^0.124.31"
+    "@intentius/chant-lexicon-otel": "^0.124.32"
   },
   "devDependencies": {
     "@intentius/chant": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31"
+    "@intentius/chant": "^0.124.32"
   }
 }

package/src/codegen/generate.test.ts

@@ -67,6 +67,16 @@ describe("generate()", () => {
     expect(result.typesDTS).toContain("declare const Service");
   });
 
+  test("every Compose entity's props accept x- extension fields, which import keeps (#4136)", async () => {
+    const result = await generate({ verbose: false });
+    for (const out of [result.typesDTS, result.indexTS]) {
+      for (const name of ["ServiceProps", "VolumeProps", "NetworkProps", "DockerConfigProps", "DockerSecretProps"]) {
+        const body = out.slice(out.indexOf(`export interface ${name} {`));
+        expect(body.slice(0, body.indexOf("\n}")), name).toContain("[extension: `x-${string}`]: unknown;");
+      }
+    }
+  });
+
   test("properties count is non-zero", async () => {
     const result = await generate({ verbose: false });
     expect(result.properties).toBeGreaterThan(0);

package/src/codegen/generate.ts

@@ -170,6 +170,9 @@ function composeTypeLines(compose: ComposeParseResult[]): string[] {
       if (p.description) lines.push(`  /** ${p.description} */`);
       lines.push(`  ${p.name}${opt}: ${p.type};`);
     }
+    // The Compose spec allows `x-` extension fields on every entity, and import keeps them (#4136).
+    lines.push(`  /** A Compose extension field. The spec allows any \`x-\` key, and Compose itself ignores it. */`);
+    lines.push("  [extension: `x-${string}`]: unknown;");
     lines.push(`}`);
     lines.push("");
   }

package/src/codegen/package.ts

@@ -5,7 +5,7 @@
 import { readFileSync } from "fs";
 import { dockerPlugin } from "../plugin";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { IntrinsicDef } from "@intentius/chant/lexicon";
 import {
   packagePipeline,
@@ -17,7 +17,7 @@ import { generate } from "./generate";
 
 export type { PackageOptions, PackageResult };
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
 
 /**
  * Package the Docker lexicon into a distributable BundleSpec.

package/src/compose-key.ts

@@ -0,0 +1,31 @@
+/**
+ * The key an entity takes in docker-compose.yml.
+ *
+ * A compose entity's key is its export name by default. A key that is not a
+ * TypeScript identifier (`db-password`, `nginx.conf`) cannot be an export
+ * name, so `composeKey` sets it explicitly (#3937):
+ *
+ * @example
+ * export const dbPassword = composeKey("db-password", new DockerSecret({ file: "./db-password.txt" }));
+ *
+ * References to the entity (`secrets: [dbPassword]`) serialize as the key.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+
+export const COMPOSE_KEY = Symbol.for("docker.composeKey");
+
+/** Give a compose entity an explicit key in docker-compose.yml. Returns the entity. */
+export function composeKey<T extends Declarable>(key: string, entity: T): T {
+  if (typeof key !== "string" || key === "") {
+    throw new Error("composeKey: the key must be a non-empty string");
+  }
+  Object.defineProperty(entity, COMPOSE_KEY, { value: key, enumerable: false, configurable: true });
+  return entity;
+}
+
+/** The key set by `composeKey`, or undefined. */
+export function getComposeKey(entity: Declarable): string | undefined {
+  const key = (entity as unknown as Record<symbol, unknown>)[COMPOSE_KEY];
+  return typeof key === "string" ? key : undefined;
+}

package/src/generated/index.d.ts

@@ -194,6 +194,8 @@ export interface ServiceProps {
   volumes_from?: Array<ComposeString>;
   /** The working directory in which the entrypoint or command will be run */
   working_dir?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A named volume definition in Docker Compose */
@@ -208,6 +210,8 @@ export interface VolumeProps {
   external?: boolean | ComposeString | { name?: ComposeString; [key: `x-${string}`]: unknown };
   /** Add metadata to the volume using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A network definition in Docker Compose */
@@ -232,6 +236,8 @@ export interface NetworkProps {
   attachable?: boolean | ComposeString;
   /** Add metadata to the network using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A config definition in Docker Compose */
@@ -250,6 +256,8 @@ export interface DockerConfigProps {
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
   /** Driver to use for templating the config's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A secret definition in Docker Compose */
@@ -270,6 +278,8 @@ export interface DockerSecretProps {
   driver_opts?: Record<string, ComposeString | number>;
   /** Driver to use for templating the secret's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 export declare const Service: new (props?: ServiceProps, attributes?: Record<string, unknown>) => Declarable;

package/src/generated/index.ts

@@ -196,6 +196,8 @@ export interface ServiceProps {
   volumes_from?: Array<ComposeString>;
   /** The working directory in which the entrypoint or command will be run */
   working_dir?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A named volume definition in Docker Compose */
@@ -210,6 +212,8 @@ export interface VolumeProps {
   external?: boolean | ComposeString | { name?: ComposeString; [key: `x-${string}`]: unknown };
   /** Add metadata to the volume using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A network definition in Docker Compose */
@@ -234,6 +238,8 @@ export interface NetworkProps {
   attachable?: boolean | ComposeString;
   /** Add metadata to the network using labels. */
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A config definition in Docker Compose */
@@ -252,6 +258,8 @@ export interface DockerConfigProps {
   labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
   /** Driver to use for templating the config's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 /** A secret definition in Docker Compose */
@@ -272,6 +280,8 @@ export interface DockerSecretProps {
   driver_opts?: Record<string, ComposeString | number>;
   /** Driver to use for templating the secret's value. */
   template_driver?: ComposeString;
+  /** A Compose extension field. The spec allows any `x-` key, and Compose itself ignores it. */
+  [extension: `x-${string}`]: unknown;
 }
 
 export const Service = createResource("Docker::Compose::Service", "docker", {}) as unknown as DockerResourceConstructor<ServiceProps>;

package/src/import/adapter.ts

@@ -72,10 +72,11 @@ export class DockerTemplateParser implements TemplateParser {
     if (looksLikeDockerfile(content)) {
       return { resources: [dockerIrToResource(new DockerfileParser().parse("app", content))], parameters: [] };
     }
-    const { entities } = new DockerParser().parse(content);
+    const { entities, warnings } = new DockerParser().parse(content);
     return {
       resources: entities.map(dockerIrToResource),
       parameters: [],
+      ...(warnings.length > 0 ? { warnings } : {}),
     };
   }
 }

package/src/import/generator.test.ts

@@ -36,8 +36,9 @@ describe("DockerGenerator", () => {
       { kind: "config", name: "app-config", props: { file: "./config/app.conf" } },
     ];
     const { source } = new DockerGenerator().generate(entities);
-    expect(source).toContain("import { DockerConfig }");
-    expect(source).toContain("new DockerConfig(");
+    expect(source).toContain("import { DockerConfig, composeKey }");
+    // app-config is not an identifier, so the key is set explicitly (#3937).
+    expect(source).toContain('export const appConfig = composeKey("app-config", new DockerConfig(');
     expect(source).toContain("app.conf");
   });
 
@@ -46,8 +47,8 @@ describe("DockerGenerator", () => {
       { kind: "secret", name: "db-password", props: { file: "./secrets/db.txt" } },
     ];
     const { source } = new DockerGenerator().generate(entities);
-    expect(source).toContain("import { DockerSecret }");
-    expect(source).toContain("new DockerSecret(");
+    expect(source).toContain("import { DockerSecret, composeKey }");
+    expect(source).toContain('export const dbPassword = composeKey("db-password", new DockerSecret(');
   });
 
   test("single-stage Dockerfile generates flat props (existing behaviour)", () => {