@intentius/chant-lexicon-docker 0.124.31 → 0.124.33

package/dist/import/generator.js

@@ -0,0 +1,159 @@
+/**
+ * Docker IR → TypeScript source generator.
+ *
+ * Converts parsed IR to valid chant TypeScript source code.
+ */
+/**
+ * Generator for Docker entities — IR → TypeScript chant source.
+ */
+export class DockerGenerator {
+    generate(entities) {
+        const warnings = [];
+        const imports = new Set();
+        const lines = [];
+        const names = new ExportNames();
+        for (const entity of entities) {
+            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});`);
+            }
+        }
+        const importLine = `import { ${[...imports].sort().join(", ")} } from "@intentius/chant-lexicon-docker";`;
+        const source = [importLine, "", ...lines].join("\n");
+        return { source, warnings };
+    }
+}
+const CONSTRUCTORS = {
+    service: "Service",
+    volume: "Volume",
+    network: "Network",
+    config: "DockerConfig",
+    secret: "DockerSecret",
+};
+function propsLiteral(entity) {
+    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) : "{}";
+}
+/** 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",
+]);
+/**
+ * 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 {
+    constructor() {
+        this.used = new Set();
+    }
+    take(key, kind) {
+        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. */
+const STEP_KEYS = new Set([
+    "arg", "env", "workdir", "user", "run", "copy", "add", "expose", "volume",
+    "label", "entrypoint", "cmd", "healthcheck", "shell", "stopsignal", "onbuild",
+]);
+/**
+ * A Dockerfile always imports as `steps`, one per instruction in source
+ * order, so building the import gives the same instructions in the same
+ * order (the per-kind fields would reorder them).
+ */
+function generateDockerfile(df, warnings) {
+    const out = [`export const ${sanitizeName(df.name)} = new Dockerfile({`];
+    if (df.globalArgs?.length)
+        out.push(`  globalArgs: [${df.globalArgs.map((a) => JSON.stringify(a)).join(", ")}],`);
+    const steps = (stage, indent) => {
+        out.push(`${indent}steps: [`);
+        for (const { instruction, value } of stage.instructions) {
+            const key = instruction.toLowerCase();
+            if (STEP_KEYS.has(key)) {
+                out.push(`${indent}  { ${key}: ${quote(value)} },`);
+            }
+            else {
+                warnings.push(`Dockerfile ${df.name}: ${instruction} has no step and was left as a comment`);
+                out.push(`${indent}  // ${instruction} ${value.replace(/\n/g, " ")}`);
+            }
+        }
+        out.push(`${indent}],`);
+    };
+    if (df.stages.length === 1) {
+        const stage = df.stages[0];
+        out.push(`  from: ${JSON.stringify(stage.from)},`);
+        if (stage.as)
+            out.push(`  as: ${JSON.stringify(stage.as)},`);
+        steps(stage, "  ");
+    }
+    else {
+        out.push(`  stages: [`);
+        for (const stage of df.stages) {
+            out.push(`    {`);
+            out.push(`      from: ${JSON.stringify(stage.from)},`);
+            if (stage.as)
+                out.push(`      as: ${JSON.stringify(stage.as)},`);
+            steps(stage, "      ");
+            out.push(`    },`);
+        }
+        out.push(`  ],`);
+    }
+    out.push(`});`);
+    return out.join("\n");
+}
+/** A string literal, single-quoted when that avoids escaping double quotes (exec form: `'["node", "a.js"]'`). */
+function quote(value) {
+    if (value.includes('"') && !/['\\\n]/.test(value))
+        return `'${value}'`;
+    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) {
+    let id = name.replace(/[^A-Za-z0-9$]+([A-Za-z0-9])/g, (_, c) => c.toUpperCase());
+    id = id.replace(/[^A-Za-z0-9_$]/g, "");
+    if (id === "")
+        id = "entity";
+    if (/^[0-9]/.test(id))
+        id = `_${id}`;
+    return id;
+}

package/dist/import/parser.d.ts

@@ -52,6 +52,36 @@ export interface ParseResult {
     entities: DockerIR[];
     warnings: string[];
 }
+/** The compose sections import reads, with the kind each holds and its entry in the lexicon. */
+declare const SECTIONS: readonly [{
+    readonly section: "services";
+    readonly kind: "service";
+    readonly entry: "Service";
+}, {
+    readonly section: "volumes";
+    readonly kind: "volume";
+    readonly entry: "Volume";
+}, {
+    readonly section: "networks";
+    readonly kind: "network";
+    readonly entry: "Network";
+}, {
+    readonly section: "configs";
+    readonly kind: "config";
+    readonly entry: "DockerConfig";
+}, {
+    readonly section: "secrets";
+    readonly kind: "secret";
+    readonly entry: "DockerSecret";
+}];
+type ComposeKind = (typeof SECTIONS)[number]["kind"];
+/**
+ * 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 declare function composeFields(): Map<ComposeKind, Set<string>>;
 /**
  * Parser for docker-compose.yml files.
  * Converts YAML to an IR consumable by the TypeScript generator.
@@ -81,4 +111,5 @@ export declare class DockerfileParser {
 }
 /** Whether content reads as a Dockerfile: its first instruction is FROM or ARG, or it starts with a parser directive. */
 export declare function looksLikeDockerfile(content: string): boolean;
+export {};
 //# sourceMappingURL=parser.d.ts.map

package/dist/import/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,YAAY,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE7F,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0BD;;;GAGG;AACH,qBAAa,YAAY;IACvB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAoElC;CACF;AAED,0FAA0F;AAC1F,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAuCpF;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAuBjD;CACF;AAED,yHAAyH;AACzH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAS5D"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"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"}

package/dist/import/parser.js

@@ -0,0 +1,181 @@
+/**
+ * Docker Compose + Dockerfile parser — converts existing YAML/Dockerfiles
+ * 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";
+/** 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" },
+];
+let fieldsCache;
+/**
+ * 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() {
+    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"));
+    const fields = new Map();
+    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, allowed, where, kind, warnings) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const props = {};
+    for (const [key, value] of Object.entries(raw)) {
+        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;
+}
+/**
+ * Parser for docker-compose.yml files.
+ * Converts YAML to an IR consumable by the TypeScript generator.
+ */
+export class DockerParser {
+    parse(content) {
+        if (!content.trim())
+            return { entities: [], warnings: [] };
+        const entities = [];
+        const warnings = [];
+        const doc = parseYAML(content);
+        const fields = composeFields();
+        const known = new Set(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`);
+        }
+        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)) {
+                entities.push({
+                    kind,
+                    name,
+                    props: extractProps(raw, fields.get(kind), `${section}.${name}`, kind, warnings),
+                });
+            }
+        }
+        return { entities, warnings };
+    }
+}
+/**
+ * Split Dockerfile content into logical instructions, in order. Comment
+ * and blank lines are dropped (also inside a continued instruction, as
+ * Docker does). A line ending in a backslash continues onto the next line,
+ * and a heredoc (`RUN <<EOF` ... `EOF`) runs to its terminator; both are
+ * kept in the value exactly as written, so writing the value back gives
+ * the same instruction.
+ */
+export function splitDockerfileInstructions(content) {
+    const out = [];
+    const lines = content.replace(/\r\n/g, "\n").split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const first = lines[i];
+        i++;
+        const trimmed = first.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const parts = [first.trimStart()];
+        let last = first;
+        while (/\\\s*$/.test(last) && i < lines.length) {
+            const next = lines[i];
+            i++;
+            // Docker skips comment and empty lines inside a continued instruction.
+            if (!next.trim() || next.trim().startsWith("#"))
+                continue;
+            parts.push(next);
+            last = next;
+        }
+        // Heredocs: <<EOF, <<-EOF, <<"EOF", <<'EOF' (possibly several).
+        const joined = parts.join("\n");
+        const terminators = [...joined.matchAll(/<<(-?)(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g)].map((m) => ({ dash: m[1] === "-", word: m[3] }));
+        for (const t of terminators) {
+            while (i < lines.length) {
+                const body = lines[i];
+                i++;
+                parts.push(body);
+                if ((t.dash ? body.replace(/^\t+/, "") : body) === t.word)
+                    break;
+            }
+        }
+        const text = parts.join("\n").trimEnd();
+        const match = text.match(/^([A-Za-z]+)(?:\s+([\s\S]*))?$/);
+        if (!match)
+            continue;
+        out.push({ instruction: match[1].toUpperCase(), value: (match[2] ?? "").trimStart() });
+    }
+    return out;
+}
+/**
+ * Parser for Dockerfile content.
+ */
+export class DockerfileParser {
+    parse(name, content) {
+        const stages = [];
+        const globalArgs = [];
+        let current = null;
+        for (const { instruction, value } of splitDockerfileInstructions(content)) {
+            if (instruction === "FROM") {
+                // Parse "FROM [--platform=...] image AS stagename"
+                const asMatch = value.match(/^(.+?)\s+[Aa][Ss]\s+(\S+)$/);
+                if (asMatch) {
+                    current = { from: asMatch[1].trim(), as: asMatch[2].trim(), instructions: [] };
+                }
+                else {
+                    current = { from: value.trim(), instructions: [] };
+                }
+                stages.push(current);
+            }
+            else if (current) {
+                current.instructions.push({ instruction, value });
+            }
+            else if (instruction === "ARG") {
+                globalArgs.push(value);
+            }
+        }
+        return { kind: "dockerfile", name, ...(globalArgs.length > 0 ? { globalArgs } : {}), stages };
+    }
+}
+/** Whether content reads as a Dockerfile: its first instruction is FROM or ARG, or it starts with a parser directive. */
+export function looksLikeDockerfile(content) {
+    for (const line of content.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        if (/^#\s*(syntax|escape|check)\s*=/i.test(t))
+            return true;
+        if (t.startsWith("#"))
+            continue;
+        return /^(FROM|ARG)\s/i.test(t);
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { DockerVar, ComposeVar } from "./variables.js";
 export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotations } from "./default-labels.js";
 export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-labels.js";
 export type { DefaultLabels, DefaultAnnotations } from "./default-labels.js";
+export { composeKey, getComposeKey, COMPOSE_KEY } from "./compose-key.js";
 export * from "./generated/index.js";
 export * from "./composites/index.js";
 export { generate, writeGeneratedFiles } from "./codegen/generate.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC5G,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACrF,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC5G,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACrF,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGvE,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+// Serializer
+export { dockerSerializer } from "./serializer.js";
+// Plugin
+export { dockerPlugin } from "./plugin.js";
+// Interpolation intrinsic
+export { env } from "./interpolation.js";
+// Context variables
+export { DOCKER_VARS, COMPOSE_VARS } from "./variables.js";
+// Default labels
+export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotations } from "./default-labels.js";
+export { DEFAULT_LABELS_MARKER, DEFAULT_ANNOTATIONS_MARKER } from "./default-labels.js";
+// Compose keys that are not identifiers (#3937)
+export { composeKey, getComposeKey, COMPOSE_KEY } from "./compose-key.js";
+// Generated entities — populated by `npm run generate`
+export * from "./generated/index.js";
+// Composites
+export * from "./composites/index.js";
+// Codegen pipeline (for external tooling)
+export { generate, writeGeneratedFiles } from "./codegen/generate.js";
+export { packageLexicon } from "./codegen/package.js";

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "714485e54afc638466db2fe9747fd3a766cc372ddcfce2851674c377935f1240",
+    "manifest.json": "b5756f0b60762a3250ef8b0fe3274c91f10d6aab9380727215ae02d21f2a4c93",
     "meta.json": "b566d5cb84a87836a861dc5840c229577e860c5427123192810b7839f764a9ee",
-    "types/index.d.ts": "f34a417496b2c02f047b0adc0bf41bacf9a3b207ff15af17bbe664329bbfa448",
+    "types/index.d.ts": "256644d2bffa2845900cf86984cc7dde3d9e79da5994ab13a22b0b83edf7f62a",
     "rules/no-latest-tag.ts": "2281be0457c02e782fbafe015f65ff5fd2b008ef0f879226e9b548a3ea65399b",
     "rules/per-kind-order.ts": "50622c849e9e76e312c4ca7abd97858f74641e0d7f673d2de47b055f7f6b6c6b",
     "rules/add-url-checksum.ts": "b317a30103f65a9dc658cc858aeca797f96f4c34f76525c88e4618dcb4a5cd05",
@@ -24,5 +24,5 @@
     "skills/chant-docker.md": "d499e18525f2cfd7ecc5b5be4a4c52c6931ebdef8d70f872d53279e53bed6f7e",
     "skills/chant-docker-patterns.md": "655f437c833796e0d520bbe08740a4226d48fcec4912b0438672ed5a299897e7"
   },
-  "composite": "df5bacee85a82bd437bfbd3eeb236744b1afd8fcefbefa086f3c099b2da6c057"
+  "composite": "9a5b409d8cf4f842421dcf59a3018b072a07d73d07b0f25b28729bdd3014409e"
 }

package/dist/interpolation.js

@@ -0,0 +1,54 @@
+/**
+ * Docker Compose variable interpolation intrinsics.
+ *
+ * Docker Compose supports:
+ *   ${VAR}              — required variable (fails if unset)
+ *   ${VAR:-default}     — use default if VAR is unset or empty
+ *   ${VAR:?error}       — fail with error message if VAR is unset or empty
+ *   ${VAR:+value}       — use value if VAR is set
+ *
+ * @example
+ * import { env } from "@intentius/chant-lexicon-docker";
+ *
+ * export const api = new Service({
+ *   image: env("APP_IMAGE", { default: "myapp:latest" }),
+ *   environment: {
+ *     DB_URL: env("DB_URL", { required: true }),
+ *   },
+ * });
+ *
+ * // Serializes to:
+ * // services:
+ * //   api:
+ * //     image: ${APP_IMAGE:-myapp:latest}
+ * //     environment:
+ * //       DB_URL: ${DB_URL:?DB_URL is required}
+ */
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+/**
+ * Create a Docker Compose variable interpolation intrinsic.
+ *
+ * @param name - Environment variable name
+ * @param opts - Interpolation options
+ */
+export function env(name, opts = {}) {
+    function interpolationString() {
+        if (opts.ifSet !== undefined) {
+            return `\${${name}:+${opts.ifSet}}`;
+        }
+        if (opts.default !== undefined) {
+            return `\${${name}:-${opts.default}}`;
+        }
+        if (opts.required || opts.errorMessage) {
+            const msg = opts.errorMessage ?? `${name} is required`;
+            return `\${${name}:?${msg}}`;
+        }
+        return `\${${name}}`;
+    }
+    const value = interpolationString();
+    return {
+        [INTRINSIC_MARKER]: true,
+        toJSON: () => value,
+        toString: () => value,
+    };
+}

package/dist/lint/audit-catalog.js

@@ -0,0 +1,25 @@
+/**
+ * The docker lexicon's `chant audit` catalog — metadata for the DKRD*
+ * Dockerfile/Compose post-synth rules. Contributed via `dockerPlugin.auditCatalog()` (#687).
+ */
+import { auditRule, SCORECARD_PINNED, applyLineage } from "@intentius/chant/audit/catalog";
+import { dockerAuditLineage } from "./audit-lineage.js";
+const DOCKER_SEC = { name: "Docker — Security best practices", url: "https://docs.docker.com/develop/security-best-practices/" };
+export const dockerAuditCatalog = {
+    DKRD001: auditRule("DKRD001", "merge-worthy", "guidance", "Service uses :latest or untagged image", "Pin the image to an explicit version tag (ideally a digest).", { authority: [SCORECARD_PINNED] }),
+    DKRD002: auditRule("DKRD002", "report-only", "guidance", "Named volume declared but unused", "Remove the unused volume or mount it in a service.", { category: "best-practice" }),
+    DKRD003: auditRule("DKRD003", "merge-worthy", "guidance", "Service exposes SSH (port 22)", "Don't expose SSH from a container; use exec/ephemeral access instead.", { authority: [DOCKER_SEC] }),
+    DKRD010: auditRule("DKRD010", "report-only", "guidance", "apt-get install without --no-install-recommends", "Add --no-install-recommends to keep images small.", { category: "best-practice" }),
+    DKRD011: auditRule("DKRD011", "report-only", "guidance", "ADD used where COPY would do", "Prefer COPY unless fetching a URL or extracting an archive.", { category: "best-practice" }),
+    DKRD012: auditRule("DKRD012", "merge-worthy", "guidance", "Container runs as root: the final stage has no USER, or ends on USER root", "Add a non-root USER instruction to the final stage, after the root setup steps.", { authority: [DOCKER_SEC] }),
+    DKRD013: auditRule("DKRD013", "report-only", "guidance", "Whole build context copied before a dependency install", "Copy the dependency manifests, run the install, then copy the rest of the source.", { category: "efficiency" }),
+    DKRD014: auditRule("DKRD014", "report-only", "guidance", "Root-only RUN after a non-root USER", "Run package installs and user/ownership changes before switching USER.", { category: "correctness" }),
+    DKRD015: auditRule("DKRD015", "report-only", "guidance", "More than one CMD or ENTRYPOINT in a stage", "Keep one CMD and one ENTRYPOINT per stage; only the last takes effect.", { category: "correctness" }),
+    DKRD016: auditRule("DKRD016", "report-only", "guidance", "COPY --from names no earlier stage", "Name a stage defined earlier in the Dockerfile, or a tagged image.", { category: "correctness" }),
+    DKRD017: auditRule("DKRD017", "report-only", "guidance", "ARG before FROM is never used", "Use the ARG in a FROM line, declare it again in the stage that needs it, or remove it.", { category: "best-practice" }),
+    DKRD018: auditRule("DKRD018", "report-only", "guidance", "Relative WORKDIR", "Use an absolute WORKDIR path.", { category: "best-practice" }),
+    DKRD019: auditRule("DKRD019", "report-only", "guidance", "ADD of a remote URL without --checksum", "Add --checksum=sha256:<digest> to ADD of an http(s) URL.", { category: "security" }),
+    DKRD020: auditRule("DKRD020", "report-only", "guidance", "apt-get update in its own RUN", "Run apt-get update and apt-get install in the same RUN.", { category: "correctness" }),
+};
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(dockerAuditCatalog, dockerAuditLineage);

package/dist/lint/audit-lineage.js

@@ -0,0 +1,39 @@
+export const dockerAuditLineage = {
+    DKRD001: [
+        { tool: "hadolint", rule: "DL3007", url: "https://github.com/hadolint/hadolint/wiki/DL3007", relation: "overlaps" },
+        { tool: "checkov", rule: "CKV_DOCKER_7", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "overlaps" },
+        { tool: "kics", rule: "image_version_using_latest", url: "https://docs.kics.io/latest/queries/dockerfile-queries/f45ea400-6bbe-4501-9fc7-1c3d75c32067/", relation: "overlaps" },
+    ],
+    DKRD003: [
+        { tool: "checkov", rule: "CKV_DOCKER_1", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "overlaps" },
+        { tool: "kics", rule: "Exposing Port 22 (SSH)", url: "https://docs.kics.io/latest/queries/dockerfile-queries/5907595b-5b6d-4142-b173-dbb0e73fbff8/", relation: "overlaps" },
+    ],
+    DKRD010: [
+        { tool: "hadolint", rule: "DL3015", url: "https://github.com/hadolint/hadolint/wiki/DL3015", relation: "equivalent" },
+        { tool: "kics", rule: "apt_get_not_avoiding_additional_packages", url: "https://docs.kics.io/latest/queries/dockerfile-queries/7384dfb2-fcd1-4fbf-91cd-6c44c318c33c/", relation: "equivalent" },
+    ],
+    DKRD011: [
+        { tool: "hadolint", rule: "DL3020", url: "https://github.com/hadolint/hadolint/wiki/DL3020", relation: "equivalent" },
+        { tool: "checkov", rule: "CKV_DOCKER_4", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "overlaps" },
+        { tool: "dockle", rule: "CIS-DI-0009", url: "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#cis-di-0009", relation: "overlaps" },
+    ],
+    DKRD012: [
+        { tool: "checkov", rule: "CKV_DOCKER_3", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "equivalent" },
+        { tool: "kics", rule: "missing_user_instruction", url: "https://docs.kics.io/latest/queries/dockerfile-queries/fd54f200-402c-4333-a5a4-36ef6709af2f/", relation: "equivalent" },
+        { tool: "dockle", rule: "CIS-DI-0001", url: "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#cis-di-0001", relation: "overlaps" },
+        { tool: "hadolint", rule: "DL3002", url: "https://github.com/hadolint/hadolint/wiki/DL3002", relation: "overlaps" },
+    ],
+    DKRD015: [
+        { tool: "hadolint", rule: "DL4003", url: "https://github.com/hadolint/hadolint/wiki/DL4003", relation: "overlaps" },
+        { tool: "hadolint", rule: "DL4004", url: "https://github.com/hadolint/hadolint/wiki/DL4004", relation: "overlaps" },
+    ],
+    DKRD016: [
+        { tool: "hadolint", rule: "DL3022", url: "https://github.com/hadolint/hadolint/wiki/DL3022", relation: "overlaps" },
+    ],
+    DKRD018: [
+        { tool: "hadolint", rule: "DL3000", url: "https://github.com/hadolint/hadolint/wiki/DL3000", relation: "overlaps" },
+    ],
+    DKRD020: [
+        { tool: "checkov", rule: "CKV_DOCKER_5", url: "https://www.checkov.io/5.Policy%20Index/dockerfile.html", relation: "overlaps" },
+    ],
+};

package/dist/lint/post-synth/add-url-checksum.js

@@ -0,0 +1,35 @@
+/**
+ * DKRD019: ADD of a remote URL without --checksum
+ *
+ * ADD fetches an http(s) URL at build time and trusts whatever comes back.
+ * `ADD --checksum=sha256:...` makes the build fail when the content changes.
+ */
+import { eachDockerfile, stageLabel } from "./docker-helpers.js";
+export const dkrd019 = {
+    id: "DKRD019",
+    description: "ADD fetches a remote URL without --checksum",
+    check(ctx) {
+        const diagnostics = [];
+        for (const { fileName, parsed } of eachDockerfile(ctx.outputs)) {
+            for (const stage of parsed.stages) {
+                for (const instr of stage.instructions) {
+                    if (instr.instruction !== "ADD")
+                        continue;
+                    const words = instr.value.split(/\s+/);
+                    if (words.some((w) => w.startsWith("--checksum=")))
+                        continue;
+                    const url = words.find((w) => /^https?:\/\//i.test(w));
+                    if (!url)
+                        continue;
+                    diagnostics.push({
+                        checkId: "DKRD019",
+                        severity: "warning",
+                        message: `${fileName} ${stageLabel(stage)}: ADD ${url} has no --checksum, so the build accepts whatever the URL serves. Add --checksum=sha256:<digest>.`,
+                        lexicon: "docker",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/apt-no-recommends.js

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