@intentius/chant-lexicon-docker 0.124.98 → 0.124.99

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (241) hide show
  1. package/dist/codegen/docs-cli.d.ts +0 -1
  2. package/dist/codegen/docs.d.ts +0 -1
  3. package/dist/codegen/generate-cli.d.ts +0 -1
  4. package/dist/codegen/generate-compose.d.ts +0 -1
  5. package/dist/codegen/generate-dockerfile.d.ts +0 -1
  6. package/dist/codegen/generate.d.ts +0 -1
  7. package/dist/codegen/naming.d.ts +0 -1
  8. package/dist/codegen/package.d.ts +0 -1
  9. package/dist/codegen/patches.d.ts +0 -1
  10. package/dist/codegen/versions.d.ts +0 -1
  11. package/dist/compose-key.d.ts +0 -1
  12. package/dist/composites/catalog.d.ts +0 -1
  13. package/dist/composites/docker-otel-collector.d.ts +0 -1
  14. package/dist/composites/docker-web-service.d.ts +0 -1
  15. package/dist/composites/index.d.ts +0 -1
  16. package/dist/coverage.d.ts +0 -1
  17. package/dist/default-labels.d.ts +0 -1
  18. package/dist/detect.d.ts +0 -1
  19. package/dist/dockerfile-order.d.ts +0 -1
  20. package/dist/export-resources.d.ts +0 -1
  21. package/dist/generated/index.d.ts +0 -1
  22. package/dist/generated/runtime.d.ts +0 -1
  23. package/dist/import/adapter.d.ts +0 -1
  24. package/dist/import/adapter.js +4 -2
  25. package/dist/import/embedded.d.ts +0 -1
  26. package/dist/import/engine.d.ts +0 -1
  27. package/dist/import/generator.d.ts +9 -2
  28. package/dist/import/generator.js +23 -1
  29. package/dist/import/live-export.d.ts +0 -1
  30. package/dist/import/parser.d.ts +0 -1
  31. package/dist/import/testdata/tar.d.ts +0 -1
  32. package/dist/index.d.ts +0 -1
  33. package/dist/integrity.json +2 -2
  34. package/dist/interpolation.d.ts +0 -1
  35. package/dist/lint/audit-catalog.d.ts +0 -1
  36. package/dist/lint/audit-lineage.d.ts +0 -1
  37. package/dist/lint/post-synth/add-url-checksum.d.ts +0 -1
  38. package/dist/lint/post-synth/apt-no-recommends.d.ts +0 -1
  39. package/dist/lint/post-synth/apt-update-alone.d.ts +0 -1
  40. package/dist/lint/post-synth/cache-busting-copy.d.ts +0 -1
  41. package/dist/lint/post-synth/copy-from-stage.d.ts +0 -1
  42. package/dist/lint/post-synth/docker-helpers.d.ts +0 -1
  43. package/dist/lint/post-synth/index.d.ts +0 -1
  44. package/dist/lint/post-synth/no-latest-image.d.ts +0 -1
  45. package/dist/lint/post-synth/no-root-user.d.ts +0 -1
  46. package/dist/lint/post-synth/prefer-copy.d.ts +0 -1
  47. package/dist/lint/post-synth/relative-workdir.d.ts +0 -1
  48. package/dist/lint/post-synth/repeated-cmd.d.ts +0 -1
  49. package/dist/lint/post-synth/root-after-user.d.ts +0 -1
  50. package/dist/lint/post-synth/ssh-port-exposed.d.ts +0 -1
  51. package/dist/lint/post-synth/unused-global-arg.d.ts +0 -1
  52. package/dist/lint/post-synth/unused-volume.d.ts +0 -1
  53. package/dist/lint/rules/data/deprecated-images.d.ts +0 -1
  54. package/dist/lint/rules/data/known-base-images.d.ts +0 -1
  55. package/dist/lint/rules/index.d.ts +0 -1
  56. package/dist/lint/rules/no-latest-tag.d.ts +0 -1
  57. package/dist/lint/rules/per-kind-order.d.ts +0 -1
  58. package/dist/list-artifacts.d.ts +0 -1
  59. package/dist/lsp/completions.d.ts +0 -1
  60. package/dist/lsp/hover.d.ts +0 -1
  61. package/dist/manifest.json +1 -1
  62. package/dist/package-cli.d.ts +0 -1
  63. package/dist/plugin.d.ts +0 -1
  64. package/dist/serializer.d.ts +0 -1
  65. package/dist/spec/fetch-compose.d.ts +0 -1
  66. package/dist/spec/fetch-engine.d.ts +0 -1
  67. package/dist/spec/parse-compose.d.ts +0 -1
  68. package/dist/spec/parse-engine.d.ts +0 -1
  69. package/dist/validate-cli.d.ts +0 -1
  70. package/dist/validate.d.ts +0 -1
  71. package/dist/variables.d.ts +0 -1
  72. package/package.json +4 -5
  73. package/dist/codegen/docs-cli.d.ts.map +0 -1
  74. package/dist/codegen/docs.d.ts.map +0 -1
  75. package/dist/codegen/generate-cli.d.ts.map +0 -1
  76. package/dist/codegen/generate-compose.d.ts.map +0 -1
  77. package/dist/codegen/generate-dockerfile.d.ts.map +0 -1
  78. package/dist/codegen/generate.d.ts.map +0 -1
  79. package/dist/codegen/naming.d.ts.map +0 -1
  80. package/dist/codegen/package.d.ts.map +0 -1
  81. package/dist/codegen/patches.d.ts.map +0 -1
  82. package/dist/codegen/versions.d.ts.map +0 -1
  83. package/dist/compose-key.d.ts.map +0 -1
  84. package/dist/composites/catalog.d.ts.map +0 -1
  85. package/dist/composites/docker-otel-collector.d.ts.map +0 -1
  86. package/dist/composites/docker-web-service.d.ts.map +0 -1
  87. package/dist/composites/index.d.ts.map +0 -1
  88. package/dist/coverage.d.ts.map +0 -1
  89. package/dist/default-labels.d.ts.map +0 -1
  90. package/dist/detect.d.ts.map +0 -1
  91. package/dist/dockerfile-order.d.ts.map +0 -1
  92. package/dist/export-resources.d.ts.map +0 -1
  93. package/dist/generated/index.d.ts.map +0 -1
  94. package/dist/generated/runtime.d.ts.map +0 -1
  95. package/dist/import/adapter.d.ts.map +0 -1
  96. package/dist/import/embedded.d.ts.map +0 -1
  97. package/dist/import/engine.d.ts.map +0 -1
  98. package/dist/import/generator.d.ts.map +0 -1
  99. package/dist/import/live-export.d.ts.map +0 -1
  100. package/dist/import/parser.d.ts.map +0 -1
  101. package/dist/import/testdata/tar.d.ts.map +0 -1
  102. package/dist/index.d.ts.map +0 -1
  103. package/dist/interpolation.d.ts.map +0 -1
  104. package/dist/lint/audit-catalog.d.ts.map +0 -1
  105. package/dist/lint/audit-lineage.d.ts.map +0 -1
  106. package/dist/lint/post-synth/add-url-checksum.d.ts.map +0 -1
  107. package/dist/lint/post-synth/apt-no-recommends.d.ts.map +0 -1
  108. package/dist/lint/post-synth/apt-update-alone.d.ts.map +0 -1
  109. package/dist/lint/post-synth/cache-busting-copy.d.ts.map +0 -1
  110. package/dist/lint/post-synth/copy-from-stage.d.ts.map +0 -1
  111. package/dist/lint/post-synth/docker-helpers.d.ts.map +0 -1
  112. package/dist/lint/post-synth/index.d.ts.map +0 -1
  113. package/dist/lint/post-synth/no-latest-image.d.ts.map +0 -1
  114. package/dist/lint/post-synth/no-root-user.d.ts.map +0 -1
  115. package/dist/lint/post-synth/prefer-copy.d.ts.map +0 -1
  116. package/dist/lint/post-synth/relative-workdir.d.ts.map +0 -1
  117. package/dist/lint/post-synth/repeated-cmd.d.ts.map +0 -1
  118. package/dist/lint/post-synth/root-after-user.d.ts.map +0 -1
  119. package/dist/lint/post-synth/ssh-port-exposed.d.ts.map +0 -1
  120. package/dist/lint/post-synth/unused-global-arg.d.ts.map +0 -1
  121. package/dist/lint/post-synth/unused-volume.d.ts.map +0 -1
  122. package/dist/lint/rules/data/deprecated-images.d.ts.map +0 -1
  123. package/dist/lint/rules/data/known-base-images.d.ts.map +0 -1
  124. package/dist/lint/rules/index.d.ts.map +0 -1
  125. package/dist/lint/rules/no-latest-tag.d.ts.map +0 -1
  126. package/dist/lint/rules/per-kind-order.d.ts.map +0 -1
  127. package/dist/list-artifacts.d.ts.map +0 -1
  128. package/dist/lsp/completions.d.ts.map +0 -1
  129. package/dist/lsp/hover.d.ts.map +0 -1
  130. package/dist/package-cli.d.ts.map +0 -1
  131. package/dist/plugin.d.ts.map +0 -1
  132. package/dist/serializer.d.ts.map +0 -1
  133. package/dist/spec/fetch-compose.d.ts.map +0 -1
  134. package/dist/spec/fetch-engine.d.ts.map +0 -1
  135. package/dist/spec/parse-compose.d.ts.map +0 -1
  136. package/dist/spec/parse-engine.d.ts.map +0 -1
  137. package/dist/validate-cli.d.ts.map +0 -1
  138. package/dist/validate.d.ts.map +0 -1
  139. package/dist/variables.d.ts.map +0 -1
  140. package/src/codegen/__snapshots__/okf.test.ts.snap +0 -555
  141. package/src/codegen/docs-cli.ts +0 -10
  142. package/src/codegen/docs.ts +0 -171
  143. package/src/codegen/generate-cli.ts +0 -36
  144. package/src/codegen/generate-compose.ts +0 -21
  145. package/src/codegen/generate-dockerfile.ts +0 -21
  146. package/src/codegen/generate.test.ts +0 -115
  147. package/src/codegen/generate.ts +0 -258
  148. package/src/codegen/naming.test.ts +0 -81
  149. package/src/codegen/naming.ts +0 -54
  150. package/src/codegen/okf.test.ts +0 -36
  151. package/src/codegen/package.ts +0 -59
  152. package/src/codegen/patches.ts +0 -42
  153. package/src/codegen/versions.ts +0 -46
  154. package/src/compose-key.ts +0 -31
  155. package/src/composites/catalog.test.ts +0 -39
  156. package/src/composites/catalog.ts +0 -118
  157. package/src/composites/docker-otel-collector.ts +0 -83
  158. package/src/composites/docker-web-service.test.ts +0 -34
  159. package/src/composites/docker-web-service.ts +0 -75
  160. package/src/composites/index.ts +0 -9
  161. package/src/coverage.test.ts +0 -33
  162. package/src/coverage.ts +0 -54
  163. package/src/default-labels.test.ts +0 -85
  164. package/src/default-labels.ts +0 -72
  165. package/src/detect.ts +0 -7
  166. package/src/dockerfile-order.ts +0 -20
  167. package/src/docs-examples.test.ts +0 -141
  168. package/src/export-resources.ts +0 -90
  169. package/src/generated/index.d.ts +0 -407
  170. package/src/generated/index.ts +0 -410
  171. package/src/generated/runtime.ts +0 -4
  172. package/src/import/adapter.ts +0 -99
  173. package/src/import/embedded-live.test.ts +0 -250
  174. package/src/import/embedded.ts +0 -83
  175. package/src/import/engine.ts +0 -107
  176. package/src/import/generator.test.ts +0 -134
  177. package/src/import/generator.ts +0 -202
  178. package/src/import/live-export.test.ts +0 -271
  179. package/src/import/live-export.ts +0 -359
  180. package/src/import/parser.test.ts +0 -137
  181. package/src/import/parser.ts +0 -269
  182. package/src/import/roundtrip.test.ts +0 -257
  183. package/src/import/testdata/configs-secrets.yaml +0 -15
  184. package/src/import/testdata/full.yaml +0 -43
  185. package/src/import/testdata/names-and-fields.yaml +0 -44
  186. package/src/import/testdata/simple.yaml +0 -9
  187. package/src/import/testdata/tar.ts +0 -24
  188. package/src/import/testdata/webapp.yaml +0 -41
  189. package/src/index.ts +0 -32
  190. package/src/interpolation.test.ts +0 -41
  191. package/src/interpolation.ts +0 -76
  192. package/src/lint/audit-catalog.ts +0 -28
  193. package/src/lint/audit-lineage.ts +0 -48
  194. package/src/lint/post-synth/add-url-checksum.ts +0 -38
  195. package/src/lint/post-synth/apt-no-recommends.ts +0 -43
  196. package/src/lint/post-synth/apt-update-alone.ts +0 -39
  197. package/src/lint/post-synth/cache-busting-copy.ts +0 -65
  198. package/src/lint/post-synth/copy-from-stage.ts +0 -54
  199. package/src/lint/post-synth/docker-helpers.ts +0 -194
  200. package/src/lint/post-synth/index.ts +0 -33
  201. package/src/lint/post-synth/no-latest-image.ts +0 -36
  202. package/src/lint/post-synth/no-root-user.ts +0 -38
  203. package/src/lint/post-synth/post-synth.test.ts +0 -330
  204. package/src/lint/post-synth/prefer-copy.ts +0 -53
  205. package/src/lint/post-synth/relative-workdir.ts +0 -38
  206. package/src/lint/post-synth/repeated-cmd.ts +0 -35
  207. package/src/lint/post-synth/root-after-user.ts +0 -44
  208. package/src/lint/post-synth/ssh-port-exposed.ts +0 -68
  209. package/src/lint/post-synth/unused-global-arg.ts +0 -38
  210. package/src/lint/post-synth/unused-volume.ts +0 -49
  211. package/src/lint/rules/data/deprecated-images.ts +0 -28
  212. package/src/lint/rules/data/known-base-images.ts +0 -20
  213. package/src/lint/rules/index.ts +0 -6
  214. package/src/lint/rules/no-latest-tag.ts +0 -63
  215. package/src/lint/rules/per-kind-order.ts +0 -130
  216. package/src/lint/rules/rules.test.ts +0 -170
  217. package/src/list-artifacts.test.ts +0 -141
  218. package/src/list-artifacts.ts +0 -164
  219. package/src/lsp/completions.test.ts +0 -40
  220. package/src/lsp/completions.ts +0 -21
  221. package/src/lsp/hover.test.ts +0 -35
  222. package/src/lsp/hover.ts +0 -39
  223. package/src/package-cli.ts +0 -25
  224. package/src/plugin.test.ts +0 -121
  225. package/src/plugin.ts +0 -268
  226. package/src/serializer.test.ts +0 -545
  227. package/src/serializer.ts +0 -444
  228. package/src/skills/chant-docker-patterns.md +0 -222
  229. package/src/skills/chant-docker.md +0 -156
  230. package/src/spec/fetch-compose.ts +0 -35
  231. package/src/spec/fetch-engine.ts +0 -25
  232. package/src/spec/parse-compose.ts +0 -195
  233. package/src/spec/parse-engine.ts +0 -59
  234. package/src/typecheck.e2e.test.ts +0 -125
  235. package/src/typed-props.test.ts +0 -60
  236. package/src/validate-cli.ts +0 -19
  237. package/src/validate.test.ts +0 -16
  238. package/src/validate.ts +0 -44
  239. package/src/variables.test.ts +0 -32
  240. package/src/variables.ts +0 -47
  241. /package/{src → dist}/generated/lexicon-docker.json +0 -0
package/src/serializer.ts DELETED
@@ -1,444 +0,0 @@
1
- /**
2
- * Docker lexicon serializer.
3
- *
4
- * Splits entities into two output domains:
5
- * - Docker::Compose::* → docker-compose.yml (primary output)
6
- * - Docker::Dockerfile → Dockerfile.{name} (per-file entries in SerializerResult)
7
- *
8
- * Default labels (DEFAULT_LABELS_MARKER) are merged into every service's
9
- * labels map but are not emitted as standalone documents.
10
- */
11
-
12
- import type { Declarable } from "@intentius/chant/declarable";
13
- import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
14
- import type { SerializeContext, Serializer, SerializerResult } from "@intentius/chant/serializer";
15
- import { mergeResourceAttributes, RELEASE_ATTRIBUTES_VARIABLE, telemetryEnvironment, type TelemetryAttribution } from "@intentius/chant/telemetry-attribution";
16
- import type { LexiconOutput } from "@intentius/chant/lexicon-output";
17
- import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
18
- import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
19
- import { emitYAMLEntry } from "@intentius/chant/yaml";
20
- import { getComposeKey } from "./compose-key";
21
- import { EXEC_FORM_STEPS, PER_KIND_ORDER, STEP_INSTRUCTIONS } from "./dockerfile-order";
22
-
23
- // ── Helpers ───────────────────────────────────────────────────────
24
-
25
- const DEFAULT_LABELS_MARKER_KEY = Symbol.for("docker.defaultLabels");
26
- const DEFAULT_ANNOTATIONS_MARKER_KEY = Symbol.for("docker.defaultAnnotations");
27
-
28
- function isDefaultLabelsEntity(entity: Declarable): boolean {
29
- return DEFAULT_LABELS_MARKER_KEY in entity;
30
- }
31
-
32
- function isDefaultAnnotationsEntity(entity: Declarable): boolean {
33
- return DEFAULT_ANNOTATIONS_MARKER_KEY in entity;
34
- }
35
-
36
- function getProps(entity: Declarable): Record<string, unknown> {
37
- if (isResourceDeclarable(entity) && typeof entity.props === "object" && entity.props !== null) {
38
- return entity.props as Record<string, unknown>;
39
- }
40
- return {};
41
- }
42
-
43
- // ── Intrinsic preprocessing ───────────────────────────────────────
44
-
45
- function preprocessIntrinsics(value: unknown): unknown {
46
- if (value === null || value === undefined) return value;
47
-
48
- if (typeof value === "object" && INTRINSIC_MARKER in (value as object)) {
49
- if ("toJSON" in (value as object) && typeof (value as { toJSON?: unknown }).toJSON === "function") {
50
- return ((value as { toJSON(): unknown }).toJSON)();
51
- }
52
- }
53
-
54
- if (typeof value === "object" && value !== null && "entityType" in (value as object)) {
55
- return value;
56
- }
57
-
58
- if (Array.isArray(value)) {
59
- return value.map(preprocessIntrinsics);
60
- }
61
-
62
- if (typeof value === "object") {
63
- const result: Record<string, unknown> = {};
64
- for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
65
- result[k] = preprocessIntrinsics(v);
66
- }
67
- return result;
68
- }
69
-
70
- return value;
71
- }
72
-
73
- // ── Visitor ───────────────────────────────────────────────────────
74
-
75
- function dockerVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
76
- const dockerfiles = new Set<string>();
77
- for (const [entity, name] of entityNames) {
78
- if ((entity as unknown as Record<string, unknown>).entityType === "Docker::Dockerfile") dockerfiles.add(name);
79
- }
80
- return {
81
- attrRef: (name, _attr) => name,
82
- // A Dockerfile reference is its filename. Any other entity (a config, a
83
- // secret, a volume) is referenced by its key in the compose file.
84
- resourceRef: (name) => (dockerfiles.has(name) ? `Dockerfile.${name}` : name),
85
- propertyDeclarable: (entity, walk) => {
86
- const props = getProps(entity);
87
- const result: Record<string, unknown> = {};
88
- for (const [key, value] of Object.entries(props)) {
89
- if (value !== undefined) {
90
- result[key] = walk(value);
91
- }
92
- }
93
- return Object.keys(result).length > 0 ? result : undefined;
94
- },
95
- };
96
- }
97
-
98
- function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unknown {
99
- const preprocessed = preprocessIntrinsics(value);
100
- return walkValue(preprocessed, entityNames, dockerVisitor(entityNames));
101
- }
102
-
103
- // ── Telemetry attribution (#2558, D22) ────────────────────────────
104
-
105
- /** The digest of an image reference pinned with `@sha256:...`, or undefined. */
106
- function imageDigest(image: unknown): string | undefined {
107
- if (typeof image !== "string") return undefined;
108
- const at = image.lastIndexOf("@");
109
- return at === -1 ? undefined : image.slice(at + 1);
110
- }
111
-
112
- /** Compose's reference to the release attributes a deploy exports (#3061, ws-081), empty when unset. */
113
- const RELEASE_REF = `\${${RELEASE_ATTRIBUTES_VARIABLE}:-}`;
114
-
115
- /** A resource-attributes value that ends with the release reference, once. */
116
- function withReleaseRef(value: string): string {
117
- return value.includes(RELEASE_REF) ? value : `${value}${RELEASE_REF}`;
118
- }
119
-
120
- /**
121
- * Stamp one service's attributes as `OTEL_SERVICE_NAME` and
122
- * `OTEL_RESOURCE_ATTRIBUTES` in its environment. A value the service already
123
- * sets is kept: its own `OTEL_SERVICE_NAME` wins, and its own resource
124
- * attributes keep their keys while the missing ones are appended.
125
- *
126
- * `OTEL_RESOURCE_ATTRIBUTES` ends with `${CHANT_RELEASE_ATTRIBUTES:-}`, which
127
- * Compose fills from the environment of `docker compose up`: a release deploy
128
- * exports `service.version` and `vcs.ref.head.revision` there (#3061,
129
- * ws-081), and any other `up` leaves it empty, so this output does not change
130
- * with a release.
131
- */
132
- function stampTelemetry(service: Record<string, unknown>, name: string, telemetry: TelemetryAttribution): void {
133
- const version = imageDigest(service.image);
134
- const vars = telemetryEnvironment(telemetry, { service: name, decl: name, ...(version ? { version } : {}) });
135
- const env = service.environment;
136
- if (Array.isArray(env)) {
137
- const entries = env.map(String);
138
- const has = (key: string) => entries.findIndex((e) => e === key || e.startsWith(`${key}=`));
139
- if (has("OTEL_SERVICE_NAME") === -1) entries.push(`OTEL_SERVICE_NAME=${vars.OTEL_SERVICE_NAME}`);
140
- const at = has("OTEL_RESOURCE_ATTRIBUTES");
141
- if (at === -1) entries.push(`OTEL_RESOURCE_ATTRIBUTES=${withReleaseRef(vars.OTEL_RESOURCE_ATTRIBUTES)}`);
142
- else if (entries[at]!.includes("=")) {
143
- entries[at] = `OTEL_RESOURCE_ATTRIBUTES=${withReleaseRef(mergeResourceAttributes(entries[at]!.slice(entries[at]!.indexOf("=") + 1), vars.OTEL_RESOURCE_ATTRIBUTES))}`;
144
- }
145
- service.environment = entries;
146
- return;
147
- }
148
- const map: Record<string, unknown> = env && typeof env === "object" ? { ...(env as Record<string, unknown>) } : {};
149
- if (!("OTEL_SERVICE_NAME" in map)) map.OTEL_SERVICE_NAME = vars.OTEL_SERVICE_NAME;
150
- const own = map.OTEL_RESOURCE_ATTRIBUTES;
151
- if (own === undefined) map.OTEL_RESOURCE_ATTRIBUTES = withReleaseRef(vars.OTEL_RESOURCE_ATTRIBUTES);
152
- else if (typeof own === "string") map.OTEL_RESOURCE_ATTRIBUTES = withReleaseRef(mergeResourceAttributes(own, vars.OTEL_RESOURCE_ATTRIBUTES));
153
- service.environment = map;
154
- }
155
-
156
- // ── Compose serialization ─────────────────────────────────────────
157
-
158
- function serializeCompose(
159
- services: Map<string, Declarable>,
160
- volumes: Map<string, Declarable>,
161
- networks: Map<string, Declarable>,
162
- configs: Map<string, Declarable>,
163
- secrets: Map<string, Declarable>,
164
- defaultLabels: Record<string, string>,
165
- entityNames: Map<Declarable, string>,
166
- telemetry?: TelemetryAttribution,
167
- ): string {
168
- const doc: Record<string, unknown> = {};
169
-
170
- if (services.size > 0) {
171
- const servicesSection: Record<string, unknown> = {};
172
- for (const [name, entity] of services) {
173
- const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
174
- // Merge default labels into service labels
175
- if (Object.keys(defaultLabels).length > 0) {
176
- const existing = (props.labels as Record<string, string>) ?? {};
177
- props.labels = { ...defaultLabels, ...existing };
178
- }
179
- // Remove undefined values
180
- const cleaned: Record<string, unknown> = {};
181
- for (const [k, v] of Object.entries(props)) {
182
- if (v !== undefined && v !== null) cleaned[k] = v;
183
- }
184
- if (telemetry) stampTelemetry(cleaned, name, telemetry);
185
- servicesSection[name] = cleaned;
186
- }
187
- doc.services = servicesSection;
188
- }
189
-
190
- if (volumes.size > 0) {
191
- const volumesSection: Record<string, unknown> = {};
192
- for (const [name, entity] of volumes) {
193
- const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
194
- const cleaned: Record<string, unknown> = {};
195
- for (const [k, v] of Object.entries(props)) {
196
- if (v !== undefined && v !== null) cleaned[k] = v;
197
- }
198
- volumesSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
199
- }
200
- doc.volumes = volumesSection;
201
- }
202
-
203
- if (networks.size > 0) {
204
- const networksSection: Record<string, unknown> = {};
205
- for (const [name, entity] of networks) {
206
- const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
207
- const cleaned: Record<string, unknown> = {};
208
- for (const [k, v] of Object.entries(props)) {
209
- if (v !== undefined && v !== null) cleaned[k] = v;
210
- }
211
- networksSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
212
- }
213
- doc.networks = networksSection;
214
- }
215
-
216
- if (configs.size > 0) {
217
- const configsSection: Record<string, unknown> = {};
218
- for (const [name, entity] of configs) {
219
- const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
220
- const cleaned: Record<string, unknown> = {};
221
- for (const [k, v] of Object.entries(props)) {
222
- if (v !== undefined && v !== null) cleaned[k] = v;
223
- }
224
- configsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
225
- }
226
- doc.configs = configsSection;
227
- }
228
-
229
- if (secrets.size > 0) {
230
- const secretsSection: Record<string, unknown> = {};
231
- for (const [name, entity] of secrets) {
232
- const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
233
- const cleaned: Record<string, unknown> = {};
234
- for (const [k, v] of Object.entries(props)) {
235
- if (v !== undefined && v !== null) cleaned[k] = v;
236
- }
237
- secretsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
238
- }
239
- doc.secrets = secretsSection;
240
- }
241
-
242
- return emitComposeDocument(doc);
243
- }
244
-
245
- function emitComposeDocument(doc: Record<string, unknown>): string {
246
- if (Object.keys(doc).length === 0) return "\n";
247
-
248
- const ORDER = ["services", "volumes", "networks", "configs", "secrets"];
249
- const sections: string[] = [];
250
- const emitted = new Set<string>();
251
-
252
- for (const key of ORDER) {
253
- if (key in doc && doc[key] !== undefined) {
254
- emitted.add(key);
255
- sections.push(emitYAMLEntry(key, doc[key]));
256
- }
257
- }
258
-
259
- for (const [key, value] of Object.entries(doc)) {
260
- if (!emitted.has(key) && value !== undefined) {
261
- sections.push(emitYAMLEntry(key, value));
262
- }
263
- }
264
-
265
- return sections.join("\n\n") + "\n";
266
- }
267
-
268
- // ── Dockerfile serialization ──────────────────────────────────────
269
-
270
- function serializeDockerfile(name: string, entity: Declarable): string {
271
- const props = getProps(entity);
272
- const lines: string[] = [];
273
-
274
- // ARGs before the first FROM: global build args a FROM line can use.
275
- if (props.globalArgs !== undefined && props.globalArgs !== null) {
276
- if (!Array.isArray(props.globalArgs)) {
277
- throw new Error(`Dockerfile.${name}: globalArgs must be a list of ARG values, like ["NODE_VERSION=20"]`);
278
- }
279
- for (const arg of props.globalArgs) lines.push(`ARG ${arg}`);
280
- }
281
-
282
- // Multi-stage build via stages[]
283
- if (Array.isArray(props.stages) && props.stages.length > 0) {
284
- if (props.steps !== undefined) {
285
- throw new Error(`Dockerfile.${name}: steps belongs on each stage when stages is set, not on the Dockerfile`);
286
- }
287
- (props.stages as Array<Record<string, unknown>>).forEach((stage, i) => {
288
- emitStage(stage, lines, `Dockerfile.${name} stage ${stage.as ? `"${stage.as}"` : i + 1}`);
289
- });
290
- return lines.join("\n") + "\n";
291
- }
292
-
293
- // Single-stage build
294
- emitStage(props, lines, `Dockerfile.${name}`);
295
- return lines.join("\n") + "\n";
296
- }
297
-
298
- function emitStage(stage: Record<string, unknown>, lines: string[], where: string): void {
299
- // FROM must be first
300
- if (stage.from) {
301
- const as = stage.as ? ` AS ${stage.as}` : "";
302
- lines.push(`FROM ${stage.from}${as}`);
303
- }
304
-
305
- if (stage.steps !== undefined && stage.steps !== null) {
306
- const perKind = PER_KIND_ORDER.filter((k) => stage[k] !== undefined && stage[k] !== null);
307
- if (perKind.length > 0) {
308
- throw new Error(
309
- `${where}: steps can't be combined with the per-kind fields (${perKind.join(", ")}). Move them into steps, in the order they should run.`,
310
- );
311
- }
312
- if (!Array.isArray(stage.steps)) throw new Error(`${where}: steps must be a list`);
313
- stage.steps.forEach((step, i) => lines.push(emitStep(step, `${where} step ${i + 1}`)));
314
- return;
315
- }
316
-
317
- // No steps: the per-kind fields, in the fixed order they have always had.
318
- for (const instr of PER_KIND_ORDER) {
319
- const value = stage[instr];
320
- if (value === undefined || value === null) continue;
321
-
322
- const keyword = instr.toUpperCase();
323
-
324
- if (Array.isArray(value)) {
325
- for (const item of value) {
326
- lines.push(`${keyword} ${item}`);
327
- }
328
- } else if (typeof value === "string") {
329
- lines.push(`${keyword} ${value}`);
330
- }
331
- }
332
- }
333
-
334
- /** One step, `{ run: "npm ci" }`, as its Dockerfile line, `RUN npm ci`. */
335
- function emitStep(step: unknown, where: string): string {
336
- if (typeof step !== "object" || step === null || Array.isArray(step)) {
337
- throw new Error(`${where}: a step is an object naming one instruction, like { run: "npm ci" }`);
338
- }
339
- const keys = Object.keys(step).filter((k) => (step as Record<string, unknown>)[k] !== undefined);
340
- if (keys.length !== 1) {
341
- throw new Error(
342
- `${where}: a step names exactly one instruction, found ${keys.length === 0 ? "none" : keys.join(", ")}. Split it into one step per instruction.`,
343
- );
344
- }
345
- const key = keys[0]!;
346
- if (!STEP_INSTRUCTIONS.has(key)) {
347
- throw new Error(`${where}: "${key}" is not a Dockerfile instruction a step can name (FROM is the stage's from field)`);
348
- }
349
- const value = (step as Record<string, unknown>)[key];
350
- const keyword = key.toUpperCase();
351
- if (Array.isArray(value)) {
352
- if (!EXEC_FORM_STEPS.has(key)) {
353
- throw new Error(`${where}: ${keyword} takes a string; only RUN, CMD, ENTRYPOINT and SHELL take an exec-form array`);
354
- }
355
- return `${keyword} ${JSON.stringify(value.map(String))}`;
356
- }
357
- if (typeof value === "string" || typeof value === "number") return `${keyword} ${value}`;
358
- throw new Error(`${where}: ${keyword} needs a string value`);
359
- }
360
-
361
- // ── Serializer ────────────────────────────────────────────────────
362
-
363
- export const dockerSerializer: Serializer = {
364
- name: "docker",
365
- rulePrefix: "DKR",
366
-
367
- serialize(
368
- entities: Map<string, Declarable>,
369
- _outputs?: LexiconOutput[],
370
- context?: SerializeContext,
371
- ): string | SerializerResult {
372
- // A compose entity's key is its export name unless composeKey set one
373
- // (#3937); references to it serialize as the same key. Two entities of
374
- // one kind cannot share a key.
375
- const entityNames = new Map<Declarable, string>();
376
- const taken = new Map<string, { name: string; entity: Declarable }>();
377
- for (const [name, entity] of entities) {
378
- const key = getComposeKey(entity) ?? name;
379
- entityNames.set(entity, key);
380
- const slot = `${(entity as unknown as Record<string, unknown>).entityType}\0${key}`;
381
- const other = taken.get(slot);
382
- if (other !== undefined && other.entity !== entity) {
383
- throw new Error(`docker: ${other.name} and ${name} both take the compose key "${key}"`);
384
- }
385
- taken.set(slot, { name, entity });
386
- }
387
-
388
- const services = new Map<string, Declarable>();
389
- const volumes = new Map<string, Declarable>();
390
- const networks = new Map<string, Declarable>();
391
- const configs = new Map<string, Declarable>();
392
- const secrets = new Map<string, Declarable>();
393
- const dockerfiles = new Map<string, Declarable>();
394
- let defaultLabels: Record<string, string> = {};
395
-
396
- for (const [exportName, entity] of entities) {
397
- const name = entityNames.get(entity) ?? exportName;
398
- // Skip property-kind entities
399
- if (isPropertyDeclarable(entity)) continue;
400
-
401
- // Skip default labels/annotations markers — collect instead
402
- if (isDefaultLabelsEntity(entity)) {
403
- const props = getProps(entity);
404
- defaultLabels = { ...defaultLabels, ...(props.labels as Record<string, string> ?? {}) };
405
- continue;
406
- }
407
- if (isDefaultAnnotationsEntity(entity)) {
408
- continue;
409
- }
410
-
411
- const et = (entity as unknown as Record<string, unknown>).entityType as string;
412
-
413
- if (et === "Docker::Compose::Service") {
414
- services.set(name, entity);
415
- } else if (et === "Docker::Compose::Volume") {
416
- volumes.set(name, entity);
417
- } else if (et === "Docker::Compose::Network") {
418
- networks.set(name, entity);
419
- } else if (et === "Docker::Compose::Config") {
420
- configs.set(name, entity);
421
- } else if (et === "Docker::Compose::Secret") {
422
- secrets.set(name, entity);
423
- } else if (et === "Docker::Dockerfile") {
424
- dockerfiles.set(name, entity);
425
- }
426
- }
427
-
428
- const composeYaml = serializeCompose(
429
- services, volumes, networks, configs, secrets,
430
- defaultLabels, entityNames, context?.telemetry,
431
- );
432
-
433
- if (dockerfiles.size === 0) {
434
- return composeYaml;
435
- }
436
-
437
- const files: Record<string, string> = {};
438
- for (const [name, entity] of dockerfiles) {
439
- files[`Dockerfile.${name}`] = serializeDockerfile(name, entity);
440
- }
441
-
442
- return { primary: composeYaml, files };
443
- },
444
- };
@@ -1,222 +0,0 @@
1
- # chant-docker-patterns
2
-
3
- Common Docker Compose and Dockerfile patterns using `@intentius/chant-lexicon-docker`.
4
-
5
- ## Database service with volume
6
-
7
- ```typescript
8
- import { Service, Volume, env } from "@intentius/chant-lexicon-docker";
9
-
10
- export const postgres = new Service({
11
- image: "postgres:16-alpine",
12
- environment: {
13
- POSTGRES_DB: "myapp",
14
- POSTGRES_USER: "myapp",
15
- POSTGRES_PASSWORD: env("POSTGRES_PASSWORD", { required: true }),
16
- },
17
- volumes: ["pgdata:/var/lib/postgresql/data"],
18
- restart: "unless-stopped",
19
- healthcheck: {
20
- test: ["CMD-SHELL", "pg_isready -U myapp"],
21
- interval: "10s",
22
- timeout: "5s",
23
- retries: 5,
24
- },
25
- });
26
-
27
- export const pgdata = new Volume({});
28
- ```
29
-
30
- ## Redis cache
31
-
32
- ```typescript
33
- export const redis = new Service({
34
- image: "redis:7-alpine",
35
- volumes: ["redisdata:/data"],
36
- command: "redis-server --appendonly yes",
37
- restart: "unless-stopped",
38
- });
39
- export const redisdata = new Volume({});
40
- ```
41
-
42
- ## Reverse proxy (nginx)
43
-
44
- ```typescript
45
- export const nginx = new Service({
46
- image: "nginx:1.25-alpine",
47
- ports: ["80:80", "443:443"],
48
- volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro", "./certs:/etc/ssl/certs:ro"],
49
- depends_on: ["api"],
50
- restart: "unless-stopped",
51
- });
52
- ```
53
-
54
- ## Multi-stage Node.js Dockerfile
55
-
56
- Manifests before source so the install layer is cached; the runtime stage takes only what it needs and runs as `node`.
57
-
58
- ```typescript
59
- export const nodeApp = new Dockerfile({
60
- stages: [
61
- {
62
- from: "node:20-alpine",
63
- as: "deps",
64
- steps: [
65
- { workdir: "/app" },
66
- { copy: "package.json package-lock.json ./" },
67
- { run: "npm ci --omit=dev" },
68
- ],
69
- },
70
- {
71
- from: "node:20-alpine",
72
- as: "build",
73
- steps: [
74
- { workdir: "/app" },
75
- { copy: "package.json package-lock.json ./" },
76
- { run: "npm ci" },
77
- { copy: ". ." },
78
- { run: "npm run build" },
79
- ],
80
- },
81
- {
82
- from: "node:20-alpine",
83
- steps: [
84
- { workdir: "/app" },
85
- { copy: "--from=deps /app/node_modules ./node_modules" },
86
- { copy: "--from=build /app/dist ./dist" },
87
- { user: "node" },
88
- { expose: 3000 },
89
- { cmd: ["node", "dist/index.js"] },
90
- ],
91
- },
92
- ],
93
- });
94
- ```
95
-
96
- ## Python service
97
-
98
- ```typescript
99
- export const pythonApp = new Dockerfile({
100
- from: "python:3.12-slim",
101
- steps: [
102
- { workdir: "/app" },
103
- { env: "PYTHONUNBUFFERED=1" },
104
- { env: "PYTHONDONTWRITEBYTECODE=1" },
105
- { copy: "requirements.txt ." },
106
- { run: "pip install --no-cache-dir -r requirements.txt" },
107
- { copy: ". ." },
108
- { user: "1000:1000" },
109
- { cmd: ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] },
110
- ],
111
- });
112
- ```
113
-
114
- ## Root setup, then USER
115
-
116
- ```typescript
117
- export const tool = new Dockerfile({
118
- from: "debian:12-slim",
119
- steps: [
120
- { run: "apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*" },
121
- { run: "useradd --system --create-home app" },
122
- { workdir: "/home/app" },
123
- { copy: "--chown=app:app bin/ ./bin/" },
124
- { user: "app" },
125
- { entrypoint: ["./bin/tool"] },
126
- ],
127
- });
128
- ```
129
-
130
- ## Sharing stages and steps across modules
131
-
132
- Export `const` stages and step lists from one module and import them into each Dockerfile. This is the chant answer to `INCLUDE`.
133
-
134
- ```typescript
135
- // src/shared/node.ts
136
- import type { DockerfileStage, DockerfileStep } from "@intentius/chant-lexicon-docker";
137
-
138
- export const nodeBuild: DockerfileStage = {
139
- from: "node:20-alpine",
140
- as: "build",
141
- steps: [
142
- { workdir: "/app" },
143
- { copy: "package.json package-lock.json ./" },
144
- { run: "npm ci" },
145
- { copy: ". ." },
146
- { run: "npm run build" },
147
- { run: "npm prune --omit=dev" },
148
- ],
149
- };
150
-
151
- export const nodeRuntime: DockerfileStep[] = [
152
- { workdir: "/app" },
153
- { copy: "--from=build /app/node_modules ./node_modules" },
154
- { copy: "--from=build /app/dist ./dist" },
155
- { user: "node" },
156
- ];
157
- ```
158
-
159
- ```typescript
160
- // src/web.ts
161
- import { Dockerfile, type DockerfileStage } from "@intentius/chant-lexicon-docker";
162
- import { nodeBuild, nodeRuntime } from "./shared/node";
163
-
164
- const runtime: DockerfileStage = {
165
- from: "node:20-alpine",
166
- steps: [...nodeRuntime, { expose: 3000 }, { cmd: ["node", "dist/server.js"] }],
167
- };
168
-
169
- export const web = new Dockerfile({ stages: [nodeBuild, runtime] });
170
- ```
171
-
172
- For a shared Dockerfile that takes parameters, write a `Composite((props) => ({ image: new Dockerfile({...}) }))`; spreads are allowed inside it. The `dockerfile-sharing` example in the lexicon has all three patterns.
173
-
174
- ## Network isolation
175
-
176
- ```typescript
177
- import { Service, Network } from "@intentius/chant-lexicon-docker";
178
-
179
- export const internal = new Network({ driver: "bridge", internal: true });
180
- export const external = new Network({ driver: "bridge" });
181
-
182
- export const api = new Service({
183
- image: "myapi:1.0",
184
- networks: ["external", "internal"],
185
- });
186
- export const db = new Service({
187
- image: "postgres:16-alpine",
188
- networks: ["internal"], // only reachable via internal network
189
- });
190
- ```
191
-
192
- ## Secrets and configs
193
-
194
- ```typescript
195
- import { Service, DockerSecret, DockerConfig } from "@intentius/chant-lexicon-docker";
196
-
197
- export const dbPassword = new DockerSecret({ file: "./secrets/db-password.txt" });
198
- export const appConfig = new DockerConfig({ file: "./config/app.yaml" });
199
-
200
- export const app = new Service({
201
- image: "myapp:1.0",
202
- secrets: ["dbPassword"],
203
- configs: ["appConfig"],
204
- });
205
- ```
206
-
207
- ## Environment interpolation patterns
208
-
209
- ```typescript
210
- import { Service, env } from "@intentius/chant-lexicon-docker";
211
-
212
- // Dev vs prod toggle:
213
- export const api = new Service({
214
- image: env("API_IMAGE", { default: "myapp:latest" }),
215
- environment: {
216
- LOG_LEVEL: env("LOG_LEVEL", { default: "info" }),
217
- WORKERS: env("WORKERS", { default: "4" }),
218
- SECRET_KEY: env("SECRET_KEY", { required: true }),
219
- SENTRY_DSN: env("SENTRY_DSN", { default: "" }),
220
- },
221
- });
222
- ```