@intentius/chant-lexicon-docker 0.124.31 → 0.124.33

package/dist/plugin.js

@@ -0,0 +1,229 @@
+/**
+ * Docker lexicon plugin.
+ *
+ * Provides serializer, lint rules, post-synth checks, intrinsics, LSP support,
+ * and code generation for Docker Compose and Dockerfile resources.
+ */
+import { compositeCatalog } from "./composites/catalog.js";
+import { detectTemplate } from "./detect.js";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { dockerAuditCatalog } from "./lint/audit-catalog.js";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { dockerSerializer } from "./serializer.js";
+import { noLatestTagRule } from "./lint/rules/no-latest-tag.js";
+import { perKindOrderRule } from "./lint/rules/per-kind-order.js";
+import { dockerCompletions } from "./lsp/completions.js";
+import { dockerHover } from "./lsp/hover.js";
+import { DockerTemplateParser, DockerTemplateGenerator } from "./import/adapter.js";
+export const dockerPlugin = {
+    name: "docker",
+    auditCatalog: () => dockerAuditCatalog,
+    // Self-upgrade: the moby/moby tag embedded in the Engine API spec URL + its upstream (#685).
+    upstreamPin: {
+        file: "src/codegen/versions.ts",
+        pattern: /moby\/moby\/([^/]+)\/api\/swagger\.yaml/,
+        replace: (v, line) => line.replace(/moby\/moby\/[^/]+\/api\/swagger\.yaml/, `moby/moby/${v}/api/swagger.yaml`),
+        upstream: { owner: "moby", repo: "moby", kind: "releases" },
+    },
+    serializer: dockerSerializer,
+    lintRules() {
+        return [noLatestTagRule, perKindOrderRule];
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    intrinsics() {
+        return [
+            {
+                name: "env",
+                description: "Docker Compose variable interpolation — ${VAR}, ${VAR:-default}, ${VAR:?error}",
+                outputKey: "env",
+                isTag: false,
+            },
+        ];
+    },
+    initTemplates(template) {
+        if (template === "webapp") {
+            return {
+                src: {
+                    "compose.ts": `import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const db = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: "secret",
+  },
+  volumes: ["pgdata:/var/lib/postgresql/data"],
+});
+
+export const pgdata = new Volume({});
+
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  depends_on: ["db"],
+  environment: {
+    DATABASE_URL: "postgresql://myapp:secret@db:5432/myapp",
+  },
+});
+`,
+                },
+            };
+        }
+        // Default template
+        return {
+            src: {
+                "compose.ts": `import { Service } from "@intentius/chant-lexicon-docker";
+
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  restart: "unless-stopped",
+});
+`,
+            },
+        };
+    },
+    detectTemplate,
+    completionProvider(ctx) {
+        return dockerCompletions(ctx);
+    },
+    hoverProvider(ctx) {
+        return dockerHover(ctx);
+    },
+    templateParser() {
+        return new DockerTemplateParser();
+    },
+    templateGenerator() {
+        return new DockerTemplateGenerator();
+    },
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname: pathDirname } = await import("path");
+        const { fileURLToPath: urlToPath } = await import("url");
+        const result = await generate({ verbose: options?.verbose ?? true });
+        const pkgDir = pathDirname(pathDirname(urlToPath(import.meta.url)));
+        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`);
+        }
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeDockerCoverage } = await import("./coverage.js");
+        await analyzeDockerCoverage({
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join: pathJoin, dirname: pathDirname } = await import("path");
+        const { fileURLToPath: urlToPath } = await import("url");
+        const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+        const pkgDir = pathDirname(pathDirname(urlToPath(import.meta.url)));
+        const distDir = pathJoin(pkgDir, "dist");
+        writeBundleSpec(spec, distDir);
+        console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [createDiffTool(dockerSerializer, "Compare current build output against previous output for Docker Compose", "docker")];
+    },
+    mcpResources() {
+        return [
+            createCatalogResource(import.meta.url, "Docker Entity Catalog", "JSON list of all supported Docker entity types", "lexicon-docker.json", "docker"),
+            {
+                uri: "examples/basic-app",
+                name: "Basic App Example",
+                description: "A basic Docker Compose application with a service and volume",
+                mimeType: "text/typescript",
+                async handler() {
+                    return `import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const db = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: "secret",
+  },
+  volumes: ["pgdata:/var/lib/postgresql/data"],
+});
+
+export const pgdata = new Volume({});
+
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  depends_on: ["db"],
+});
+`;
+                },
+            },
+        ];
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs(options);
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-docker.md",
+            name: "chant-docker",
+            description: "Docker Compose service/volume/network lifecycle — build, serialize, deploy",
+            triggers: [
+                { type: "file-pattern", value: "**/*.compose.ts" },
+                { type: "file-pattern", value: "**/docker-compose.ts" },
+                { type: "context", value: "docker compose" },
+                { type: "context", value: "docker service" },
+                { type: "context", value: "dockerfile" },
+                { type: "context", value: "container" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Basic service with database",
+                    description: "Create a web service and PostgreSQL database",
+                    input: "Create a Node.js API with a PostgreSQL database",
+                    output: `new Service({ image: "myapi:1.0", depends_on: ["db"] })`,
+                },
+            ],
+        },
+        {
+            file: "chant-docker-patterns.md",
+            name: "chant-docker-patterns",
+            description: "Docker Compose patterns — databases, caches, networks, multi-stage builds",
+            triggers: [
+                { type: "context", value: "docker compose" },
+                { type: "context", value: "multi-stage" },
+                { type: "context", value: "dockerfile pattern" },
+                { type: "context", value: "docker network" },
+                { type: "context", value: "docker volume" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Multi-stage Dockerfile",
+                    input: "Create a multi-stage Dockerfile for Node.js",
+                    output: `new Dockerfile({ stages: [{ from: "node:20-alpine", as: "build", ... }] })`,
+                },
+            ],
+        },
+    ]),
+    async listArtifacts(options) {
+        const { listArtifacts } = await import("./list-artifacts.js");
+        return listArtifacts(options);
+    },
+};

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAoB,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AA4VlG,eAAO,MAAM,gBAAgB,EAAE,UAqE9B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAoB,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AA6VlG,eAAO,MAAM,gBAAgB,EAAE,UAiF9B,CAAC"}

package/dist/serializer.js

@@ -0,0 +1,390 @@
+/**
+ * Docker lexicon serializer.
+ *
+ * Splits entities into two output domains:
+ * - Docker::Compose::* → docker-compose.yml (primary output)
+ * - Docker::Dockerfile → Dockerfile.{name} (per-file entries in SerializerResult)
+ *
+ * Default labels (DEFAULT_LABELS_MARKER) are merged into every service's
+ * labels map but are not emitted as standalone documents.
+ */
+import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import { mergeResourceAttributes, RELEASE_ATTRIBUTES_VARIABLE, telemetryEnvironment } from "@intentius/chant/telemetry-attribution";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { emitYAMLEntry } from "@intentius/chant/yaml";
+import { getComposeKey } from "./compose-key.js";
+import { EXEC_FORM_STEPS, PER_KIND_ORDER, STEP_INSTRUCTIONS } from "./dockerfile-order.js";
+// ── Helpers ───────────────────────────────────────────────────────
+const DEFAULT_LABELS_MARKER_KEY = Symbol.for("docker.defaultLabels");
+const DEFAULT_ANNOTATIONS_MARKER_KEY = Symbol.for("docker.defaultAnnotations");
+function isDefaultLabelsEntity(entity) {
+    return DEFAULT_LABELS_MARKER_KEY in entity;
+}
+function isDefaultAnnotationsEntity(entity) {
+    return DEFAULT_ANNOTATIONS_MARKER_KEY in entity;
+}
+function getProps(entity) {
+    if (isResourceDeclarable(entity) && typeof entity.props === "object" && entity.props !== null) {
+        return entity.props;
+    }
+    return {};
+}
+// ── Intrinsic preprocessing ───────────────────────────────────────
+function preprocessIntrinsics(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "object" && INTRINSIC_MARKER in value) {
+        if ("toJSON" in value && typeof value.toJSON === "function") {
+            return (value.toJSON)();
+        }
+    }
+    if (typeof value === "object" && value !== null && "entityType" in value) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(preprocessIntrinsics);
+    }
+    if (typeof value === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = preprocessIntrinsics(v);
+        }
+        return result;
+    }
+    return value;
+}
+// ── Visitor ───────────────────────────────────────────────────────
+function dockerVisitor(entityNames) {
+    const dockerfiles = new Set();
+    for (const [entity, name] of entityNames) {
+        if (entity.entityType === "Docker::Dockerfile")
+            dockerfiles.add(name);
+    }
+    return {
+        attrRef: (name, _attr) => name,
+        // A Dockerfile reference is its filename. Any other entity (a config, a
+        // secret, a volume) is referenced by its key in the compose file.
+        resourceRef: (name) => (dockerfiles.has(name) ? `Dockerfile.${name}` : name),
+        propertyDeclarable: (entity, walk) => {
+            const props = getProps(entity);
+            const result = {};
+            for (const [key, value] of Object.entries(props)) {
+                if (value !== undefined) {
+                    result[key] = walk(value);
+                }
+            }
+            return Object.keys(result).length > 0 ? result : undefined;
+        },
+    };
+}
+function toYAMLValue(value, entityNames) {
+    const preprocessed = preprocessIntrinsics(value);
+    return walkValue(preprocessed, entityNames, dockerVisitor(entityNames));
+}
+// ── Telemetry attribution (#2558, D22) ────────────────────────────
+/** The digest of an image reference pinned with `@sha256:...`, or undefined. */
+function imageDigest(image) {
+    if (typeof image !== "string")
+        return undefined;
+    const at = image.lastIndexOf("@");
+    return at === -1 ? undefined : image.slice(at + 1);
+}
+/** Compose's reference to the release attributes a deploy exports (#3061, ws-081), empty when unset. */
+const RELEASE_REF = `\${${RELEASE_ATTRIBUTES_VARIABLE}:-}`;
+/** A resource-attributes value that ends with the release reference, once. */
+function withReleaseRef(value) {
+    return value.includes(RELEASE_REF) ? value : `${value}${RELEASE_REF}`;
+}
+/**
+ * Stamp one service's attributes as `OTEL_SERVICE_NAME` and
+ * `OTEL_RESOURCE_ATTRIBUTES` in its environment. A value the service already
+ * sets is kept: its own `OTEL_SERVICE_NAME` wins, and its own resource
+ * attributes keep their keys while the missing ones are appended.
+ *
+ * `OTEL_RESOURCE_ATTRIBUTES` ends with `${CHANT_RELEASE_ATTRIBUTES:-}`, which
+ * Compose fills from the environment of `docker compose up`: a release deploy
+ * exports `service.version` and `vcs.ref.head.revision` there (#3061,
+ * ws-081), and any other `up` leaves it empty, so this output does not change
+ * with a release.
+ */
+function stampTelemetry(service, name, telemetry) {
+    const version = imageDigest(service.image);
+    const vars = telemetryEnvironment(telemetry, { service: name, decl: name, ...(version ? { version } : {}) });
+    const env = service.environment;
+    if (Array.isArray(env)) {
+        const entries = env.map(String);
+        const has = (key) => entries.findIndex((e) => e === key || e.startsWith(`${key}=`));
+        if (has("OTEL_SERVICE_NAME") === -1)
+            entries.push(`OTEL_SERVICE_NAME=${vars.OTEL_SERVICE_NAME}`);
+        const at = has("OTEL_RESOURCE_ATTRIBUTES");
+        if (at === -1)
+            entries.push(`OTEL_RESOURCE_ATTRIBUTES=${withReleaseRef(vars.OTEL_RESOURCE_ATTRIBUTES)}`);
+        else if (entries[at].includes("=")) {
+            entries[at] = `OTEL_RESOURCE_ATTRIBUTES=${withReleaseRef(mergeResourceAttributes(entries[at].slice(entries[at].indexOf("=") + 1), vars.OTEL_RESOURCE_ATTRIBUTES))}`;
+        }
+        service.environment = entries;
+        return;
+    }
+    const map = env && typeof env === "object" ? { ...env } : {};
+    if (!("OTEL_SERVICE_NAME" in map))
+        map.OTEL_SERVICE_NAME = vars.OTEL_SERVICE_NAME;
+    const own = map.OTEL_RESOURCE_ATTRIBUTES;
+    if (own === undefined)
+        map.OTEL_RESOURCE_ATTRIBUTES = withReleaseRef(vars.OTEL_RESOURCE_ATTRIBUTES);
+    else if (typeof own === "string")
+        map.OTEL_RESOURCE_ATTRIBUTES = withReleaseRef(mergeResourceAttributes(own, vars.OTEL_RESOURCE_ATTRIBUTES));
+    service.environment = map;
+}
+// ── Compose serialization ─────────────────────────────────────────
+function serializeCompose(services, volumes, networks, configs, secrets, defaultLabels, entityNames, telemetry) {
+    const doc = {};
+    if (services.size > 0) {
+        const servicesSection = {};
+        for (const [name, entity] of services) {
+            const props = toYAMLValue(getProps(entity), entityNames);
+            // Merge default labels into service labels
+            if (Object.keys(defaultLabels).length > 0) {
+                const existing = props.labels ?? {};
+                props.labels = { ...defaultLabels, ...existing };
+            }
+            // Remove undefined values
+            const cleaned = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (v !== undefined && v !== null)
+                    cleaned[k] = v;
+            }
+            if (telemetry)
+                stampTelemetry(cleaned, name, telemetry);
+            servicesSection[name] = cleaned;
+        }
+        doc.services = servicesSection;
+    }
+    if (volumes.size > 0) {
+        const volumesSection = {};
+        for (const [name, entity] of volumes) {
+            const props = toYAMLValue(getProps(entity), entityNames);
+            const cleaned = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (v !== undefined && v !== null)
+                    cleaned[k] = v;
+            }
+            volumesSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+        }
+        doc.volumes = volumesSection;
+    }
+    if (networks.size > 0) {
+        const networksSection = {};
+        for (const [name, entity] of networks) {
+            const props = toYAMLValue(getProps(entity), entityNames);
+            const cleaned = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (v !== undefined && v !== null)
+                    cleaned[k] = v;
+            }
+            networksSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+        }
+        doc.networks = networksSection;
+    }
+    if (configs.size > 0) {
+        const configsSection = {};
+        for (const [name, entity] of configs) {
+            const props = toYAMLValue(getProps(entity), entityNames);
+            const cleaned = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (v !== undefined && v !== null)
+                    cleaned[k] = v;
+            }
+            configsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+        }
+        doc.configs = configsSection;
+    }
+    if (secrets.size > 0) {
+        const secretsSection = {};
+        for (const [name, entity] of secrets) {
+            const props = toYAMLValue(getProps(entity), entityNames);
+            const cleaned = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (v !== undefined && v !== null)
+                    cleaned[k] = v;
+            }
+            secretsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+        }
+        doc.secrets = secretsSection;
+    }
+    return emitComposeDocument(doc);
+}
+function emitComposeDocument(doc) {
+    if (Object.keys(doc).length === 0)
+        return "\n";
+    const ORDER = ["services", "volumes", "networks", "configs", "secrets"];
+    const sections = [];
+    const emitted = new Set();
+    for (const key of ORDER) {
+        if (key in doc && doc[key] !== undefined) {
+            emitted.add(key);
+            sections.push(emitYAMLEntry(key, doc[key]));
+        }
+    }
+    for (const [key, value] of Object.entries(doc)) {
+        if (!emitted.has(key) && value !== undefined) {
+            sections.push(emitYAMLEntry(key, value));
+        }
+    }
+    return sections.join("\n\n") + "\n";
+}
+// ── Dockerfile serialization ──────────────────────────────────────
+function serializeDockerfile(name, entity) {
+    const props = getProps(entity);
+    const lines = [];
+    // ARGs before the first FROM: global build args a FROM line can use.
+    if (props.globalArgs !== undefined && props.globalArgs !== null) {
+        if (!Array.isArray(props.globalArgs)) {
+            throw new Error(`Dockerfile.${name}: globalArgs must be a list of ARG values, like ["NODE_VERSION=20"]`);
+        }
+        for (const arg of props.globalArgs)
+            lines.push(`ARG ${arg}`);
+    }
+    // Multi-stage build via stages[]
+    if (Array.isArray(props.stages) && props.stages.length > 0) {
+        if (props.steps !== undefined) {
+            throw new Error(`Dockerfile.${name}: steps belongs on each stage when stages is set, not on the Dockerfile`);
+        }
+        props.stages.forEach((stage, i) => {
+            emitStage(stage, lines, `Dockerfile.${name} stage ${stage.as ? `"${stage.as}"` : i + 1}`);
+        });
+        return lines.join("\n") + "\n";
+    }
+    // Single-stage build
+    emitStage(props, lines, `Dockerfile.${name}`);
+    return lines.join("\n") + "\n";
+}
+function emitStage(stage, lines, where) {
+    // FROM must be first
+    if (stage.from) {
+        const as = stage.as ? ` AS ${stage.as}` : "";
+        lines.push(`FROM ${stage.from}${as}`);
+    }
+    if (stage.steps !== undefined && stage.steps !== null) {
+        const perKind = PER_KIND_ORDER.filter((k) => stage[k] !== undefined && stage[k] !== null);
+        if (perKind.length > 0) {
+            throw new Error(`${where}: steps can't be combined with the per-kind fields (${perKind.join(", ")}). Move them into steps, in the order they should run.`);
+        }
+        if (!Array.isArray(stage.steps))
+            throw new Error(`${where}: steps must be a list`);
+        stage.steps.forEach((step, i) => lines.push(emitStep(step, `${where} step ${i + 1}`)));
+        return;
+    }
+    // No steps: the per-kind fields, in the fixed order they have always had.
+    for (const instr of PER_KIND_ORDER) {
+        const value = stage[instr];
+        if (value === undefined || value === null)
+            continue;
+        const keyword = instr.toUpperCase();
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                lines.push(`${keyword} ${item}`);
+            }
+        }
+        else if (typeof value === "string") {
+            lines.push(`${keyword} ${value}`);
+        }
+    }
+}
+/** One step, `{ run: "npm ci" }`, as its Dockerfile line, `RUN npm ci`. */
+function emitStep(step, where) {
+    if (typeof step !== "object" || step === null || Array.isArray(step)) {
+        throw new Error(`${where}: a step is an object naming one instruction, like { run: "npm ci" }`);
+    }
+    const keys = Object.keys(step).filter((k) => step[k] !== undefined);
+    if (keys.length !== 1) {
+        throw new Error(`${where}: a step names exactly one instruction, found ${keys.length === 0 ? "none" : keys.join(", ")}. Split it into one step per instruction.`);
+    }
+    const key = keys[0];
+    if (!STEP_INSTRUCTIONS.has(key)) {
+        throw new Error(`${where}: "${key}" is not a Dockerfile instruction a step can name (FROM is the stage's from field)`);
+    }
+    const value = step[key];
+    const keyword = key.toUpperCase();
+    if (Array.isArray(value)) {
+        if (!EXEC_FORM_STEPS.has(key)) {
+            throw new Error(`${where}: ${keyword} takes a string; only RUN, CMD, ENTRYPOINT and SHELL take an exec-form array`);
+        }
+        return `${keyword} ${JSON.stringify(value.map(String))}`;
+    }
+    if (typeof value === "string" || typeof value === "number")
+        return `${keyword} ${value}`;
+    throw new Error(`${where}: ${keyword} needs a string value`);
+}
+// ── Serializer ────────────────────────────────────────────────────
+export const dockerSerializer = {
+    name: "docker",
+    rulePrefix: "DKR",
+    serialize(entities, _outputs, context) {
+        // 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();
+        const taken = new Map();
+        for (const [name, entity] of entities) {
+            const key = getComposeKey(entity) ?? name;
+            entityNames.set(entity, key);
+            const slot = `${entity.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();
+        const volumes = new Map();
+        const networks = new Map();
+        const configs = new Map();
+        const secrets = new Map();
+        const dockerfiles = new Map();
+        let defaultLabels = {};
+        for (const [exportName, entity] of entities) {
+            const name = entityNames.get(entity) ?? exportName;
+            // Skip property-kind entities
+            if (isPropertyDeclarable(entity))
+                continue;
+            // Skip default labels/annotations markers — collect instead
+            if (isDefaultLabelsEntity(entity)) {
+                const props = getProps(entity);
+                defaultLabels = { ...defaultLabels, ...(props.labels ?? {}) };
+                continue;
+            }
+            if (isDefaultAnnotationsEntity(entity)) {
+                continue;
+            }
+            const et = entity.entityType;
+            if (et === "Docker::Compose::Service") {
+                services.set(name, entity);
+            }
+            else if (et === "Docker::Compose::Volume") {
+                volumes.set(name, entity);
+            }
+            else if (et === "Docker::Compose::Network") {
+                networks.set(name, entity);
+            }
+            else if (et === "Docker::Compose::Config") {
+                configs.set(name, entity);
+            }
+            else if (et === "Docker::Compose::Secret") {
+                secrets.set(name, entity);
+            }
+            else if (et === "Docker::Dockerfile") {
+                dockerfiles.set(name, entity);
+            }
+        }
+        const composeYaml = serializeCompose(services, volumes, networks, configs, secrets, defaultLabels, entityNames, context?.telemetry);
+        if (dockerfiles.size === 0) {
+            return composeYaml;
+        }
+        const files = {};
+        for (const [name, entity] of dockerfiles) {
+            files[`Dockerfile.${name}`] = serializeDockerfile(name, entity);
+        }
+        return { primary: composeYaml, files };
+    },
+};

package/dist/spec/fetch-compose.js

@@ -0,0 +1,28 @@
+/**
+ * Fetch and cache the Compose Spec JSON Schema.
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+import { COMPOSE_SPEC_URL, COMPOSE_SPEC_CACHE } from "../codegen/versions.js";
+export function getCachePath() {
+    return join(homedir(), ".chant", COMPOSE_SPEC_CACHE);
+}
+/**
+ * Fetch the Compose Spec JSON Schema, with local caching.
+ */
+export async function fetchComposeSpec(force) {
+    return fetchWithCache({
+        url: COMPOSE_SPEC_URL,
+        cacheFile: getCachePath(),
+    }, force);
+}
+/**
+ * Fetch compose spec as a Map keyed by entity type — for generatePipeline.
+ */
+export async function fetchComposeSchemas(force) {
+    const data = await fetchComposeSpec(force);
+    const schemas = new Map();
+    schemas.set("Docker::Compose::Service", data);
+    return schemas;
+}

package/dist/spec/fetch-engine.js

@@ -0,0 +1,19 @@
+/**
+ * Fetch and cache the Docker Engine API OpenAPI spec.
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+import { ENGINE_API_URL, ENGINE_API_CACHE } from "../codegen/versions.js";
+export function getCachePath() {
+    return join(homedir(), ".chant", ENGINE_API_CACHE);
+}
+/**
+ * Fetch the Docker Engine API swagger YAML, with local caching.
+ */
+export async function fetchEngineApi(force) {
+    return fetchWithCache({
+        url: ENGINE_API_URL,
+        cacheFile: getCachePath(),
+    }, force);
+}