@intentius/chant 0.124.70 → 0.124.72

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 (169) hide show
  1. package/dist/ci-agent.d.ts +12 -1
  2. package/dist/ci-agent.d.ts.map +1 -1
  3. package/dist/ci-agent.js +13 -8
  4. package/dist/ci-commit.d.ts +326 -0
  5. package/dist/ci-commit.d.ts.map +1 -0
  6. package/dist/ci-commit.js +725 -0
  7. package/dist/ci-estate/delivery.d.ts +75 -2
  8. package/dist/ci-estate/delivery.d.ts.map +1 -1
  9. package/dist/ci-estate/delivery.js +129 -0
  10. package/dist/ci-estate.d.ts +3 -1
  11. package/dist/ci-estate.d.ts.map +1 -1
  12. package/dist/ci-estate.js +4 -1
  13. package/dist/ci-product-words.d.ts +6 -1
  14. package/dist/ci-product-words.d.ts.map +1 -1
  15. package/dist/ci-product-words.js +3 -1
  16. package/dist/ci-product.d.ts +1 -1
  17. package/dist/ci-product.d.ts.map +1 -1
  18. package/dist/ci-product.js +1 -1
  19. package/dist/cli/handlers/approve.d.ts.map +1 -1
  20. package/dist/cli/handlers/approve.js +7 -2
  21. package/dist/cli/handlers/commit.d.ts +26 -0
  22. package/dist/cli/handlers/commit.d.ts.map +1 -0
  23. package/dist/cli/handlers/commit.js +145 -0
  24. package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
  25. package/dist/cli/handlers/notify-relay.js +22 -2
  26. package/dist/cli/handlers/pr.d.ts +6 -0
  27. package/dist/cli/handlers/pr.d.ts.map +1 -1
  28. package/dist/cli/handlers/pr.js +16 -7
  29. package/dist/cli/handlers/release.d.ts +9 -0
  30. package/dist/cli/handlers/release.d.ts.map +1 -1
  31. package/dist/cli/handlers/release.js +114 -5
  32. package/dist/cli/main.d.ts.map +1 -1
  33. package/dist/cli/main.js +17 -0
  34. package/dist/components/product-pipeline.d.ts +33 -0
  35. package/dist/components/product-pipeline.d.ts.map +1 -1
  36. package/dist/components/product-pipeline.js +34 -1
  37. package/dist/components/release-compile.d.ts +2 -0
  38. package/dist/components/release-compile.d.ts.map +1 -1
  39. package/dist/components/release-compile.js +8 -4
  40. package/dist/config.d.ts +60 -0
  41. package/dist/config.d.ts.map +1 -1
  42. package/dist/config.js +16 -0
  43. package/dist/lexicon.d.ts +54 -0
  44. package/dist/lexicon.d.ts.map +1 -1
  45. package/dist/lexicon.js +28 -0
  46. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +4 -0
  47. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  48. package/dist/lifecycle/__fixtures__/publish-fakes.js +6 -2
  49. package/dist/lifecycle/gated-request.d.ts +3 -1
  50. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  51. package/dist/lifecycle/gated-request.js +5 -2
  52. package/dist/lifecycle/git.d.ts.map +1 -1
  53. package/dist/lifecycle/git.js +57 -0
  54. package/dist/lifecycle/publish-declaration.d.ts +16 -0
  55. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  56. package/dist/lifecycle/publish-declaration.js +35 -3
  57. package/dist/lifecycle/publish-forge.d.ts +12 -0
  58. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  59. package/dist/lifecycle/publish-forge.js +102 -19
  60. package/dist/lifecycle/publish-npm.d.ts +15 -0
  61. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  62. package/dist/lifecycle/publish-npm.js +28 -1
  63. package/dist/lifecycle/publish-oci.d.ts +2 -0
  64. package/dist/lifecycle/publish-oci.d.ts.map +1 -1
  65. package/dist/lifecycle/publish-oci.js +10 -0
  66. package/dist/lifecycle/release-cut.d.ts +7 -1
  67. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  68. package/dist/lifecycle/release-cut.js +8 -1
  69. package/dist/lifecycle/release-images.d.ts +87 -0
  70. package/dist/lifecycle/release-images.d.ts.map +1 -0
  71. package/dist/lifecycle/release-images.js +138 -0
  72. package/dist/lifecycle/release-publish.d.ts +2 -0
  73. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  74. package/dist/notify-relay.d.ts +41 -1
  75. package/dist/notify-relay.d.ts.map +1 -1
  76. package/dist/notify-relay.js +40 -0
  77. package/dist/notify.d.ts +16 -3
  78. package/dist/notify.d.ts.map +1 -1
  79. package/dist/notify.js +16 -10
  80. package/dist/op/activities/review-agent.d.ts.map +1 -1
  81. package/dist/op/activities/review-agent.js +4 -2
  82. package/dist/op/gate.d.ts +5 -1
  83. package/dist/op/gate.d.ts.map +1 -1
  84. package/dist/op/gate.js +7 -2
  85. package/dist/op/op-waves-notify.d.ts +1 -1
  86. package/dist/op/op-waves-notify.d.ts.map +1 -1
  87. package/dist/op/op-waves-notify.js +2 -1
  88. package/dist/op/op-waves-run.d.ts.map +1 -1
  89. package/dist/op/op-waves-run.js +12 -8
  90. package/dist/op/op-waves.d.ts +9 -0
  91. package/dist/op/op-waves.d.ts.map +1 -1
  92. package/dist/op/op-waves.js +11 -0
  93. package/dist/pr-forge-base.d.ts +18 -0
  94. package/dist/pr-forge-base.d.ts.map +1 -0
  95. package/dist/pr-forge-base.js +29 -0
  96. package/dist/release-floors.d.ts +1 -1
  97. package/dist/release-floors.js +1 -1
  98. package/dist/wave-runtime.mjs +315 -315
  99. package/dist/workspace/ci-green.d.ts.map +1 -1
  100. package/dist/workspace/ci-green.js +1 -2
  101. package/dist/workspace/release-workflow.d.ts +47 -0
  102. package/dist/workspace/release-workflow.d.ts.map +1 -1
  103. package/dist/workspace/release-workflow.js +258 -14
  104. package/package.json +1 -1
  105. package/src/ci-agent.ts +13 -8
  106. package/src/ci-commit.test.ts +415 -0
  107. package/src/ci-commit.ts +901 -0
  108. package/src/ci-estate/__fixtures__/terragucci-dora.json +1305 -0
  109. package/src/ci-estate/delivery.ts +186 -2
  110. package/src/ci-estate/records-delivery.test.ts +55 -0
  111. package/src/ci-estate.ts +10 -0
  112. package/src/ci-product-words.ts +6 -2
  113. package/src/ci-product.ts +1 -0
  114. package/src/cli/handlers/approve.ts +6 -2
  115. package/src/cli/handlers/commit.ts +155 -0
  116. package/src/cli/handlers/notify-relay.ts +21 -2
  117. package/src/cli/handlers/operator.test.ts +2 -0
  118. package/src/cli/handlers/pr-wave-approve-lines.test.ts +32 -0
  119. package/src/cli/handlers/pr.ts +17 -7
  120. package/src/cli/handlers/release.ts +110 -5
  121. package/src/cli/main.ts +17 -0
  122. package/src/components/product-pipeline.test.ts +28 -1
  123. package/src/components/product-pipeline.ts +54 -1
  124. package/src/components/release-compile.ts +9 -3
  125. package/src/config.ts +31 -0
  126. package/src/lexicon.ts +72 -0
  127. package/src/lifecycle/__fixtures__/publish-fakes.ts +11 -5
  128. package/src/lifecycle/gated-request-spend.test.ts +115 -0
  129. package/src/lifecycle/gated-request.ts +5 -2
  130. package/src/lifecycle/git.ts +53 -0
  131. package/src/lifecycle/ledger-two-clones.test.ts +132 -0
  132. package/src/lifecycle/publish-declaration.ts +35 -3
  133. package/src/lifecycle/publish-forge-notes.test.ts +193 -0
  134. package/src/lifecycle/publish-forge.ts +100 -22
  135. package/src/lifecycle/publish-npm.ts +31 -2
  136. package/src/lifecycle/publish-oci.ts +10 -0
  137. package/src/lifecycle/publish-targets.test.ts +2 -1
  138. package/src/lifecycle/release-cut.ts +17 -1
  139. package/src/lifecycle/release-images.test.ts +242 -0
  140. package/src/lifecycle/release-images.ts +174 -0
  141. package/src/lifecycle/release-publish.ts +2 -0
  142. package/src/notify-relay.test.ts +55 -1
  143. package/src/notify-relay.ts +49 -1
  144. package/src/notify.ts +25 -12
  145. package/src/op/activities/review-agent.test.ts +20 -1
  146. package/src/op/activities/review-agent.ts +5 -2
  147. package/src/op/gate.ts +7 -2
  148. package/src/op/op-waves-approve-target.test.ts +108 -0
  149. package/src/op/op-waves-notify.ts +2 -2
  150. package/src/op/op-waves-run.ts +12 -7
  151. package/src/op/op-waves.ts +12 -0
  152. package/src/pr-forge-base.test.ts +37 -0
  153. package/src/pr-forge-base.ts +36 -0
  154. package/src/release-floors.ts +1 -1
  155. package/src/workspace/__fixtures__/release-workflow/forgejo-plain-member.yml +26 -0
  156. package/src/workspace/__fixtures__/release-workflow/forgejo-plain.yml +23 -0
  157. package/src/workspace/__fixtures__/release-workflow/forgejo-secure-member.yml +27 -0
  158. package/src/workspace/__fixtures__/release-workflow/forgejo-secure.yml +24 -0
  159. package/src/workspace/__fixtures__/release-workflow/github-plain-member.yml +26 -0
  160. package/src/workspace/__fixtures__/release-workflow/github-plain.yml +23 -0
  161. package/src/workspace/__fixtures__/release-workflow/github-secure-member.yml +27 -0
  162. package/src/workspace/__fixtures__/release-workflow/github-secure.yml +24 -0
  163. package/src/workspace/__fixtures__/release-workflow/gitlab-plain-member.yml +13 -0
  164. package/src/workspace/__fixtures__/release-workflow/gitlab-plain.yml +12 -0
  165. package/src/workspace/__fixtures__/release-workflow/gitlab-secure-member.yml +14 -0
  166. package/src/workspace/__fixtures__/release-workflow/gitlab-secure.yml +13 -0
  167. package/src/workspace/ci-green.ts +1 -2
  168. package/src/workspace/release-workflow.test.ts +199 -0
  169. package/src/workspace/release-workflow.ts +356 -14
@@ -0,0 +1,193 @@
1
+ /** #4658: a forge release's notes, read from a section of a file in the member. */
2
+ import { afterAll, describe, expect, test } from "vitest";
3
+ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { join } from "node:path";
6
+ import { createRedactor } from "./publish-credentials";
7
+ import { PublishDeclarationSchema } from "./publish-declaration";
8
+ import { releaseNotesSection } from "./publish-forge";
9
+ import { createPublishTargets } from "./publish-targets";
10
+ import { PublishTargetError, type PublishContext } from "./release-publish";
11
+ import { makeRelease } from "./release-store";
12
+ import { startFakeForge, writeLockfile } from "./__fixtures__/publish-fakes";
13
+
14
+ const dirs: string[] = [];
15
+ afterAll(() => {
16
+ for (const d of dirs) rmSync(d, { recursive: true, force: true });
17
+ });
18
+
19
+ const CHANGES = [
20
+ "# Changes",
21
+ "",
22
+ "## In 1.4.0",
23
+ "",
24
+ "- `api` reads its [config](/docs/config/) once.",
25
+ "- See [the guide](https://example.com/guide) and [a section](#later).",
26
+ "",
27
+ "```sh",
28
+ "# not a heading",
29
+ "api run",
30
+ "```",
31
+ "",
32
+ "### Fixed",
33
+ "",
34
+ "- a crash on start",
35
+ "",
36
+ "## In 1.3.0",
37
+ "",
38
+ "- older",
39
+ "",
40
+ ].join("\n");
41
+
42
+ function member(): string {
43
+ const dir = mkdtempSync(join(tmpdir(), "chant-notes-"));
44
+ dirs.push(dir);
45
+ writeFileSync(join(dir, "api-linux.tar.gz"), "binary bytes");
46
+ writeFileSync(join(dir, "CHANGES.md"), CHANGES);
47
+ writeLockfile(dir);
48
+ return dir;
49
+ }
50
+
51
+ function context(cwd: string, over: Partial<PublishContext> = {}): PublishContext & { lines: string[] } {
52
+ const env = over.env ?? {};
53
+ const redactor = createRedactor(env);
54
+ const lines: string[] = [];
55
+ return {
56
+ release: makeRelease({ member: null, commit: "c0ffee".padEnd(40, "0"), artifactDigests: [], targets: [{ env: "dev", params: [], templates: [] }] }),
57
+ label: "v1.4.0",
58
+ releaseTag: "release/v1.4.0",
59
+ provenance: { oidc: false, ci: null, reason: "not in CI" },
60
+ cwd,
61
+ tag: null,
62
+ env,
63
+ redactor,
64
+ log: (l) => lines.push(redactor.redact(l)),
65
+ ...over,
66
+ lines,
67
+ };
68
+ }
69
+
70
+ const decl = (d: unknown) => PublishDeclarationSchema.parse(d);
71
+ const NOTES = { file: "CHANGES.md", heading: "## In {version}", linkBase: "https://docs.example.com" };
72
+ const SECTION = [
73
+ "- `api` reads its [config](https://docs.example.com/docs/config/) once.",
74
+ "- See [the guide](https://example.com/guide) and [a section](#later).",
75
+ "",
76
+ "```sh",
77
+ "# not a heading",
78
+ "api run",
79
+ "```",
80
+ "",
81
+ "### Fixed",
82
+ "",
83
+ "- a crash on start",
84
+ ].join("\n");
85
+
86
+ describe("releaseNotesSection (#4658)", () => {
87
+ test("the section runs to the next heading of its level, past code and lower headings, with root links made absolute", () => {
88
+ expect(releaseNotesSection(CHANGES, "## In 1.4.0", "https://docs.example.com/")).toBe(SECTION);
89
+ });
90
+
91
+ test("a changelog's version heading with a date matches; a longer version or a prerelease does not", () => {
92
+ const log = "## [1.2.30] - 2026-11-01\n\n- no\n\n## [1.2.3] - 2026-10-01\n\n- yes\n\n## 1.2.3-rc.1\n\n- no\n";
93
+ expect(releaseNotesSection(log, "## [1.2.3]")).toBe("- yes");
94
+ expect(() => releaseNotesSection("## 1.2.3-rc.1\n\n- rc\n", "## 1.2.3")).toThrow(/no heading "## 1.2.3"/);
95
+ });
96
+
97
+ test("a missing or empty section is an error", () => {
98
+ expect(() => releaseNotesSection(CHANGES, "## In 9.9.9")).toThrow(/no heading/);
99
+ expect(() => releaseNotesSection("## In 1.4.0\n\n## In 1.3.0\n- x\n", "## In 1.4.0")).toThrow(/section is empty/);
100
+ });
101
+ });
102
+
103
+ describe("a forge release's notes (#4658)", () => {
104
+ test("the plan carries the notes, with before and after filled in, so a dry run prints them", async () => {
105
+ const dir = member();
106
+ const forge = startFakeForge("github", "https://api.github.test", "acme/api");
107
+ const notes = { ...NOTES, before: "`@acme/api@{version}` on npm.", after: "Tag {tag}, label {label}." };
108
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api: "https://api.github.test", assets: ["api-linux.tar.gz"], notes })], { fetch: forge.fetch });
109
+ const items = await t!.plan(context(dir, { env: { GITHUB_TOKEN: "ghs_x" } }));
110
+ expect(items.at(-1)).toEqual({
111
+ name: "CHANGES.md",
112
+ destination: "github acme/api release release/v1.4.0, notes",
113
+ notes: `\`@acme/api@1.4.0\` on npm.\n\n${SECTION}\n\nTag release/v1.4.0, label v1.4.0.\n`,
114
+ });
115
+ expect(forge.calls).toEqual([]);
116
+ });
117
+
118
+ test("a missing section refuses at the plan, before anything is sent", async () => {
119
+ const dir = member();
120
+ const forge = startFakeForge("github", "https://api.github.test", "acme/api");
121
+ for (const notes of [{ ...NOTES, heading: "## In 2.0.0" }, { ...NOTES, file: "NOPE.md" }]) {
122
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api: "https://api.github.test", assets: ["api-linux.tar.gz"], notes })], { fetch: forge.fetch });
123
+ const err = await t!.plan(context(dir, { env: { GITHUB_TOKEN: "ghs_x" } })).catch((e: unknown) => e);
124
+ expect(err).toBeInstanceOf(PublishTargetError);
125
+ expect((err as PublishTargetError).code).toBe("publish-forge-notes-missing");
126
+ }
127
+ expect(forge.calls).toEqual([]);
128
+ });
129
+
130
+ test("GitHub: the draft and the published release carry the notes, and the release is made latest", async () => {
131
+ const dir = member();
132
+ const forge = startFakeForge("github", "https://api.github.test", "acme/api");
133
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api: "https://api.github.test", assets: ["api-linux.tar.gz"], notes: NOTES })], { fetch: forge.fetch });
134
+ const ctx = context(dir, { env: { GITHUB_TOKEN: "ghs_x" } });
135
+ const staged = await t!.stage(ctx);
136
+ expect(forge.releases[0]).toMatchObject({ draft: true, body: `${SECTION}\n` });
137
+ await t!.reveal(ctx, staged);
138
+ expect(forge.releases[0]).toMatchObject({ draft: false, body: `${SECTION}\n`, make_latest: "true" });
139
+
140
+ // A publish run again finds the release published and sends nothing that would change its notes.
141
+ forge.releases[0]!.body = "edited by hand";
142
+ const n = forge.calls.length;
143
+ const again = await t!.stage(ctx);
144
+ await t!.reveal(ctx, again);
145
+ expect(forge.calls.slice(n).map((c) => c.method)).toEqual(["GET"]);
146
+ expect(forge.releases[0]!.body).toBe("edited by hand");
147
+ });
148
+
149
+ test("GitHub: a release cut to a channel is not made latest, and a declared latest wins", async () => {
150
+ const dir = member();
151
+ for (const [latest, sent] of [[undefined, "false"], [true, "true"]] as const) {
152
+ const forge = startFakeForge("github", "https://api.github.test", "acme/api");
153
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api: "https://api.github.test", assets: ["api-linux.tar.gz"], notes: NOTES, ...(latest !== undefined ? { latest } : {}) })], { fetch: forge.fetch });
154
+ const ctx = context(dir, { env: { GITHUB_TOKEN: "ghs_x" }, tag: "beta" });
155
+ await t!.reveal(ctx, await t!.stage(ctx));
156
+ expect(forge.releases[0]!.make_latest).toBe(sent);
157
+ }
158
+ });
159
+
160
+ test("Forgejo: the notes are the release's body, and a channel's release is a prerelease", async () => {
161
+ const dir = member();
162
+ for (const [tag, prerelease] of [[null, undefined], ["beta", true]] as const) {
163
+ const forge = startFakeForge("forgejo", "https://forgejo.test/api/v1", "acme/api");
164
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "forgejo", repo: "acme/api", api: "https://forgejo.test/api/v1", assets: ["api-linux.tar.gz"], notes: NOTES })], { fetch: forge.fetch });
165
+ const ctx = context(dir, { env: { FORGEJO_TOKEN: "fj" }, tag });
166
+ await t!.reveal(ctx, await t!.stage(ctx));
167
+ expect(forge.releases[0]).toMatchObject({ draft: false, body: `${SECTION}\n` });
168
+ expect(forge.releases[0]!.prerelease).toBe(prerelease);
169
+ expect(JSON.parse(forge.calls.at(-1)!.body as string)).not.toHaveProperty("make_latest");
170
+ }
171
+ });
172
+
173
+ test("GitLab: the notes are the release's description", async () => {
174
+ const dir = member();
175
+ const api = "https://gitlab.test/api/v4";
176
+ const forge = startFakeForge("gitlab", api, "acme/api");
177
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "gitlab", repo: "acme/api", assets: ["api-linux.tar.gz"], notes: NOTES })], { fetch: forge.fetch });
178
+ const ctx = context(dir, { env: { GITLAB_TOKEN: "glpat", CI_API_V4_URL: api } });
179
+ await t!.reveal(ctx, await t!.stage(ctx));
180
+ expect(JSON.parse(forge.calls.at(-1)!.body as string).description).toBe(`${SECTION}\n`);
181
+ });
182
+
183
+ test("a release of notes alone needs no assets and attaches no provenance statement; with neither, the declaration is refused", async () => {
184
+ const dir = member();
185
+ const forge = startFakeForge("github", "https://api.github.test", "acme/api");
186
+ const [t] = await createPublishTargets([decl({ type: "forge", forge: "github", repo: "acme/api", api: "https://api.github.test", assets: [], sbom: false, notes: NOTES })], { fetch: forge.fetch });
187
+ const ctx = context(dir, { env: { GITHUB_TOKEN: "ghs_x" } });
188
+ await t!.reveal(ctx, await t!.stage(ctx));
189
+ expect(forge.visible()).toEqual([{ tag: "release/v1.4.0", assets: [] }]);
190
+ expect(forge.releases[0]!.body).toBe(`${SECTION}\n`);
191
+ expect(() => decl({ type: "forge", forge: "github", repo: "acme/api", assets: [] })).toThrow(/assets, notes or both/);
192
+ });
193
+ });
@@ -47,6 +47,7 @@
47
47
  import { readFileSync } from "node:fs";
48
48
  import { basename } from "node:path";
49
49
  import { memberSbom, releaseProvenance } from "./publish-attachments";
50
+ import { releaseVersion } from "./publish-homebrew";
50
51
  import { readCredential, type Credential } from "./publish-credentials";
51
52
  import type { ForgePublishDeclaration } from "./publish-declaration";
52
53
  import { bytesDigest, checkReleaseDigest, memberFile, publishTargetKey } from "./publish-targets";
@@ -55,6 +56,52 @@ import { PublishTargetError, type PublishContext, type PublishDeps, type Publish
55
56
  /** The first chant that reads `latest` on a forge target and sends it as GitHub's `make_latest` (#4676). */
56
57
  export const PUBLISH_FORGE_LATEST_FLOOR = "0.124.63";
57
58
 
59
+ /** The first chant whose forge target reads `notes` and may have no assets (#4658). Products feature-detect on it. */
60
+ export const PUBLISH_FORGE_NOTES_FLOOR = "0.124.71";
61
+
62
+ /** `text` with `{label}`, `{version}` and `{tag}` filled in. */
63
+ function fillNotesText(text: string, values: { label: string; version: string; tag: string }): string {
64
+ return text.replaceAll("{label}", values.label).replaceAll("{version}", values.version).replaceAll("{tag}", values.tag);
65
+ }
66
+
67
+ /**
68
+ * The section of `page` that starts at the heading `heading` names (#4658),
69
+ * up to the next heading of the same level or higher, trimmed. A heading
70
+ * matches when it is the pattern, or the pattern and then whitespace, so
71
+ * `## [1.2.3] - 2026-11-07` matches `## [1.2.3]`, and neither `## 1.2.30`
72
+ * nor `## 1.2.3-rc.1` matches `## 1.2.3`. Links that start with `/` are
73
+ * made absolute against `linkBase`. Throws when there is no such heading or
74
+ * the section is empty.
75
+ */
76
+ export function releaseNotesSection(page: string, heading: string, linkBase?: string): string {
77
+ const level = /^(#+)/.exec(heading)![1]!.length;
78
+ const lines = page.split("\n");
79
+ const matches = (l: string): boolean => {
80
+ const t = l.trimEnd();
81
+ return t === heading || (t.startsWith(heading) && /^\s/.test(t.slice(heading.length)));
82
+ };
83
+ const start = lines.findIndex(matches);
84
+ if (start < 0) throw new Error(`it has no heading "${heading}"`);
85
+ // A `#` line inside a fenced code block is code, not a heading.
86
+ let end = lines.length;
87
+ let fence: string | null = null;
88
+ for (let i = start + 1; i < lines.length; i++) {
89
+ const f = /^\s*(```|~~~)/.exec(lines[i]!);
90
+ if (f) fence = fence === null ? f[1]! : fence === f[1] ? null : fence;
91
+ if (fence !== null || f) continue;
92
+ const m = /^(#{1,6}) /.exec(lines[i]!);
93
+ if (m && m[1]!.length <= level) {
94
+ end = i;
95
+ break;
96
+ }
97
+ }
98
+ const body = lines.slice(start + 1, end).join("\n").trim();
99
+ if (!body) throw new Error(`its "${heading}" section is empty`);
100
+ if (!linkBase) return body;
101
+ const base = linkBase.replace(/\/+$/, "");
102
+ return body.replace(/\]\((\/(?!\/)[^)\s]*)/g, (_, path: string) => `](${base}${path}`);
103
+ }
104
+
58
105
  /** The variables a forge's token is read from, in order. */
59
106
  export function forgeTokenEnv(decl: Pick<ForgePublishDeclaration, "forge" | "tokenEnv">): string[] {
60
107
  if (decl.tokenEnv) return [decl.tokenEnv];
@@ -145,7 +192,7 @@ class ForgeClient {
145
192
  }
146
193
 
147
194
  /** GitHub and Forgejo: the draft release for `tag`, made at `commit` when there is none. */
148
- async draft(tag: string, commit: string, name: string): Promise<ForgeRelease> {
195
+ async draft(tag: string, commit: string, name: string, body?: string): Promise<ForgeRelease> {
149
196
  const list = await this.call("GET", `${this.repoPath}/releases?per_page=100`);
150
197
  if (list.status !== 200) this.fail("listing releases", list.status, list.text);
151
198
  const drafts = Array.isArray(list.json) ? (list.json as Array<Record<string, unknown>>) : [];
@@ -155,25 +202,32 @@ class ForgeClient {
155
202
  return this.toRelease(mine, tag);
156
203
  }
157
204
  this.ctx.log(`creating a draft ${this.decl.forge} release for ${tag} at ${commit.slice(0, 12)}`);
158
- const create = await this.call("POST", `${this.repoPath}/releases`, JSON.stringify({ tag_name: tag, target_commitish: commit, name, draft: true }));
205
+ const create = await this.call("POST", `${this.repoPath}/releases`, JSON.stringify({ tag_name: tag, target_commitish: commit, name, draft: true, ...(body !== undefined ? { body } : {}) }));
159
206
  if (create.status !== 201 || !create.json) this.fail(`creating a draft release ${tag}`, create.status, create.text);
160
207
  return this.toRelease(create.json as Record<string, unknown>, tag);
161
208
  }
162
209
 
163
- /** GitHub and Forgejo: publish the draft `id`, with GitHub's `make_latest` when `latest` is declared. */
164
- async publishDraft(id: string, tag: string): Promise<void> {
165
- const latest = this.decl.latest;
166
- const body = latest === undefined ? { draft: false } : { draft: false, make_latest: String(latest) };
210
+ /**
211
+ * GitHub and Forgejo: publish the draft `id` with its notes. GitHub gets
212
+ * `make_latest`: the declared `latest`, else `false` for a release cut to a
213
+ * channel and `true` for any other (#4658). Forgejo has no such setting and
214
+ * takes the newest release that is not a prerelease, so a channel's release
215
+ * is marked a prerelease there.
216
+ */
217
+ async publishDraft(id: string, tag: string, o: { notes?: string; channel: boolean }): Promise<void> {
218
+ const body: Record<string, unknown> = { draft: false, ...(o.notes !== undefined ? { body: o.notes } : {}) };
219
+ if (this.decl.forge === "github") body.make_latest = String(this.decl.latest ?? !o.channel);
220
+ else if (o.channel) body.prerelease = true;
167
221
  const res = await this.call("PATCH", `${this.repoPath}/releases/${id}`, JSON.stringify(body));
168
222
  if (res.status !== 200) this.fail(`publishing the draft release ${tag}`, res.status, res.text);
169
223
  }
170
224
 
171
225
  /** GitLab: create the release for `tag` at `commit` with a link to each asset. */
172
- async createWithLinks(tag: string, commit: string, name: string, links: Array<{ name: string; url: string }>): Promise<void> {
226
+ async createWithLinks(tag: string, commit: string, name: string, links: Array<{ name: string; url: string }>, notes?: string): Promise<void> {
173
227
  const res = await this.call(
174
228
  "POST",
175
229
  `${this.repoPath}/releases`,
176
- JSON.stringify({ tag_name: tag, ref: commit, name, assets: { links: links.map((l) => ({ ...l, link_type: "package" })) } }),
230
+ JSON.stringify({ tag_name: tag, ref: commit, name, ...(notes !== undefined ? { description: notes } : {}), assets: { links: links.map((l) => ({ ...l, link_type: "package" })) } }),
177
231
  );
178
232
  if (res.status !== 201) this.fail(`creating release ${tag}`, res.status, res.text);
179
233
  }
@@ -231,19 +285,38 @@ export function forgeTarget(decl: ForgePublishDeclaration, deps: PublishDeps): P
231
285
  checkReleaseDigest(ctx.release, "asset", ctx.cwd, p, [digest]);
232
286
  return { path: p, name: basename(p), bytes, digest };
233
287
  });
234
- // #4049: the SBOM and the provenance statement over the assets go on the release with them.
288
+ // #4049: the SBOM and the provenance statement over the assets go on the release with them. A release of notes alone has no asset to state.
235
289
  const sbom = memberSbom(ctx, decl.sbom, `${decl.repo}@${tag}`, `the ${decl.forge} target`);
236
- const provenance = releaseProvenance(
237
- ctx,
238
- assets.map((a) => ({ name: a.name, digest: a.digest })),
239
- );
290
+ const provenance =
291
+ assets.length > 0
292
+ ? releaseProvenance(
293
+ ctx,
294
+ assets.map((a) => ({ name: a.name, digest: a.digest })),
295
+ )
296
+ : null;
240
297
  for (const a of [sbom, provenance]) if (a) assets.push({ path: a.name, name: a.name, bytes: a.bytes, digest: a.digest, attachment: a.kind });
241
298
  const names = new Set<string>();
242
299
  for (const a of assets) {
243
300
  if (names.has(a.name)) throw new PublishTargetError("publish-forge-asset-name-taken", `two assets are named ${a.name}, and a release holds one asset per name`);
244
301
  names.add(a.name);
245
302
  }
246
- return { tag, api, token, assets };
303
+ return { tag, api, token, assets, notes: releaseNotes(ctx, tag) };
304
+ };
305
+ // #4658: the notes are read when the target is planned, so a missing or empty section refuses before any target publishes.
306
+ const releaseNotes = (ctx: PublishContext, tag: string): string | undefined => {
307
+ const n = decl.notes;
308
+ if (!n) return undefined;
309
+ const label = ctx.label ?? tag;
310
+ const values = { label, version: releaseVersion(ctx.label) ?? label, tag };
311
+ const heading = fillNotesText(n.heading, values);
312
+ let section: string;
313
+ try {
314
+ section = releaseNotesSection(readFileSync(memberFile(ctx.cwd, n.file), "utf8"), heading, n.linkBase);
315
+ } catch (err) {
316
+ const why = (err as NodeJS.ErrnoException).code === "ENOENT" ? "it does not exist" : (err as Error).message;
317
+ throw new PublishTargetError("publish-forge-notes-missing", `the ${decl.forge} release's notes come from ${n.file}, and ${why}`, `Write the "${heading}" section in ${n.file}, or change notes.heading.`);
318
+ }
319
+ return [...(n.before ? [fillNotesText(n.before, values), ""] : []), section, ...(n.after ? ["", fillNotesText(n.after, values)] : [])].join("\n") + "\n";
247
320
  };
248
321
  const att = (a: Asset): Pick<PublishItem, "attachment"> => (a.attachment ? { attachment: a.attachment } : {});
249
322
  const where = (tag: string, name: string) => `${decl.forge} ${decl.repo} release ${tag}, asset ${name}`;
@@ -260,11 +333,14 @@ export function forgeTarget(decl: ForgePublishDeclaration, deps: PublishDeps): P
260
333
  credentialEnv: tokenNames,
261
334
  key: publishTargetKey(decl),
262
335
  async plan(ctx) {
263
- const { tag, assets } = setup(ctx);
264
- return assets.map((a) => ({ name: a.path, destination: where(tag, a.name), digest: a.digest, ...att(a) }));
336
+ const { tag, assets, notes } = setup(ctx);
337
+ return [
338
+ ...assets.map((a) => ({ name: a.path, destination: where(tag, a.name), digest: a.digest, ...att(a) })),
339
+ ...(notes !== undefined ? [{ name: decl.notes!.file, destination: `${decl.forge} ${decl.repo} release ${tag}, notes`, notes }] : []),
340
+ ];
265
341
  },
266
342
  async stage(ctx): Promise<StagedTarget> {
267
- const { tag, api, token, assets } = setup(ctx);
343
+ const { tag, api, token, assets, notes } = setup(ctx);
268
344
  ctx.log(`using the token from ${token.from}`);
269
345
  const client = new ForgeClient(decl, api, token, fetchImpl, ctx);
270
346
  const done = (items: PublishItem[], state: Record<string, string>): StagedTarget => ({ target: this.name, destination: this.destination, items, state });
@@ -300,7 +376,7 @@ export function forgeTarget(decl: ForgePublishDeclaration, deps: PublishDeps): P
300
376
  return done(items, {});
301
377
  }
302
378
 
303
- const rel = await client.draft(tag, ctx.release.commit, ctx.label ?? tag);
379
+ const rel = await client.draft(tag, ctx.release.commit, ctx.label ?? tag, notes);
304
380
  const items: PublishItem[] = [];
305
381
  for (const a of assets) {
306
382
  if (rel.assets.has(a.name)) {
@@ -316,18 +392,20 @@ export function forgeTarget(decl: ForgePublishDeclaration, deps: PublishDeps): P
316
392
  return done(items, { releaseId: rel.id });
317
393
  },
318
394
  async reveal(ctx, staged) {
319
- const { tag, api, token } = setup(ctx);
395
+ const { tag, api, token, notes } = setup(ctx);
320
396
  const client = new ForgeClient(decl, api, token, fetchImpl, ctx);
321
397
  const items = staged.items.map((i) => ({ name: i.name, destination: i.destination, ...(i.digest ? { digest: i.digest } : {}), ...(i.attachment ? { attachment: i.attachment } : {}) }));
322
398
  if (staged.state.published === "true") return { target: this.name, destination: this.destination, items: items.map((i) => ({ ...i, present: true })) };
323
399
  if (decl.forge === "gitlab") {
324
400
  ctx.log(`creating the gitlab release ${tag} at ${ctx.release.commit.slice(0, 12)} with ${items.length} asset link(s)`);
325
- await client.createWithLinks(tag, ctx.release.commit, ctx.label ?? tag, items.map((i) => ({ name: basename(i.name), url: i.destination })));
401
+ await client.createWithLinks(tag, ctx.release.commit, ctx.label ?? tag, items.map((i) => ({ name: basename(i.name), url: i.destination })), notes);
326
402
  } else {
327
403
  const id = staged.state.releaseId;
328
404
  if (!id) throw new PublishTargetError("publish-forge-failed", `the staged ${decl.forge} release for ${tag} has no draft id to publish`);
329
- ctx.log(`publishing the draft ${decl.forge} release ${tag}${decl.latest === undefined ? "" : ` with make_latest ${String(decl.latest)}`}`);
330
- await client.publishDraft(id, tag);
405
+ const channel = ctx.tag !== null;
406
+ const latest = decl.forge === "github" ? ` with make_latest ${String(decl.latest ?? !channel)}` : channel ? " as a prerelease, since it was cut to a channel" : "";
407
+ ctx.log(`publishing the draft ${decl.forge} release ${tag}${notes !== undefined ? " with its notes" : ""}${latest}`);
408
+ await client.publishDraft(id, tag, { ...(notes !== undefined ? { notes } : {}), channel });
331
409
  }
332
410
  return { target: this.name, destination: this.destination, items };
333
411
  },
@@ -59,12 +59,13 @@ import { join } from "node:path";
59
59
  import { packageSbom } from "./publish-attachments";
60
60
  import type { NpmPublishDeclaration } from "./publish-declaration";
61
61
  import { checkReleaseDigest, fileDigest, isDir, memberFile, publishTargetKey } from "./publish-targets";
62
+ import { readPins, unknownPins } from "./release-images";
62
63
  import { NPM_STAGE_TAG, PublishTargetError, type PublishContext, type PublishDeps, type PublishItem, type PublishTarget } from "./release-publish";
63
64
 
64
65
  /** npm's output when a publish could not authenticate, as publish-packages.sh matches it. */
65
66
  const NPM_AUTH_FAILED = /ENEEDAUTH|E401|need auth/;
66
67
 
67
- interface NpmPackage {
68
+ export interface NpmPackage {
68
69
  path: string;
69
70
  abs: string;
70
71
  name: string;
@@ -169,6 +170,30 @@ const NPM_VIEW_NOT_YET = /\bE404\b|\b404 Not Found\b|is not in (this|the npm) re
169
170
  /** npm's errors for a version the registry does not serve yet. */
170
171
  const NPM_NOT_SERVED = /\b(ETARGET|ERESOLVE|notarget)\b|No matching version found/;
171
172
 
173
+ /**
174
+ * #4657: refuse a package whose `pins` file holds an image digest the release
175
+ * does not record, and a target none of whose packages has the file. Read
176
+ * by the plan, so nothing is published, and by `chant release verify`.
177
+ */
178
+ export function checkPackagePins(decl: Pick<NpmPublishDeclaration, "pins">, release: PublishContext["release"], pkgs: ReadonlyArray<Pick<NpmPackage, "path" | "abs" | "name">>): void {
179
+ if (!decl.pins) return;
180
+ let found = 0;
181
+ for (const pkg of pkgs) {
182
+ const text = readPins(pkg.abs, decl.pins, isDir(pkg.abs));
183
+ if (text === null) continue;
184
+ found++;
185
+ const unknown = unknownPins(text, release);
186
+ if (unknown.length > 0) {
187
+ throw new PublishTargetError(
188
+ "publish-npm-pin-unknown",
189
+ `${pkg.name} (${pkg.path}) pins ${unknown.join(", ")} in ${decl.pins}, which release ${release.releaseDigest} does not record as an image`,
190
+ "Build the package from the digests the cut wrote (CHANT_RELEASE_DIGESTS, or chant release images <label>), or cut a new release.",
191
+ );
192
+ }
193
+ }
194
+ if (found === 0) throw new PublishTargetError("publish-npm-pins-missing", `no package of the npm target holds ${decl.pins}, which pins names`, "Build the package so it carries the file, or remove pins.");
195
+ }
196
+
172
197
  export function npmTarget(decl: NpmPublishDeclaration, deps: PublishDeps): PublishTarget {
173
198
  const bin = deps.npm ?? "npm";
174
199
  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
@@ -218,7 +243,11 @@ export function npmTarget(decl: NpmPublishDeclaration, deps: PublishDeps): Publi
218
243
  rmSync(dir, { recursive: true, force: true });
219
244
  }
220
245
  };
221
- const read = (ctx: PublishContext) => decl.packages.map((p) => readPackage(ctx, p, decl.sbom));
246
+ const read = (ctx: PublishContext) => {
247
+ const pkgs = decl.packages.map((p) => readPackage(ctx, p, decl.sbom));
248
+ checkPackagePins(decl, ctx.release, pkgs);
249
+ return pkgs;
250
+ };
222
251
  const extra = (pkg: NpmPackage) => ({ ...(pkg.digest ? { digest: pkg.digest } : {}), ...(pkg.sbom ? { sbom: pkg.sbom } : {}) });
223
252
  const plan = async (ctx: PublishContext): Promise<PublishItem[]> =>
224
253
  read(ctx).map((pkg) => ({ name: `${pkg.name}@${pkg.version}`, destination: staging ? `${shown(NPM_STAGE_TAG)}, then ${revealTag(ctx)}` : shown(revealTag(ctx)), ...extra(pkg) }));
@@ -288,6 +288,16 @@ export function ociTags(decl: OciPublishDeclaration, ctx: Pick<PublishContext, "
288
288
  return declared.filter((t) => ctx.label !== null || !t.includes("{label}")).map((t) => t.split("{label}").join(ctx.label ?? ""));
289
289
  }
290
290
 
291
+ /** The digest an OCI archive (a layout directory or a tar file of one) is pushed under: its top manifest's (#4657). */
292
+ export function ociArchiveDigest(abs: string): string {
293
+ const layout = readLayout(abs);
294
+ try {
295
+ return layout.top.digest;
296
+ } finally {
297
+ layout.cleanup();
298
+ }
299
+ }
300
+
291
301
  export function ociTarget(decl: OciPublishDeclaration, deps: PublishDeps): PublishTarget {
292
302
  const repo = parseRepository(decl.repository);
293
303
  const fetchImpl: PublishFetch = deps.fetch ?? ((url, init) => fetch(url, init as RequestInit));
@@ -371,7 +371,8 @@ describe("forge release assets", () => {
371
371
 
372
372
  await target!.reveal(ctx, staged);
373
373
  expect(forge.visible()).toEqual([{ tag: "release/v1.4.0", assets: ATTACHED }]);
374
- expect(forge.calls.at(-1)).toMatchObject({ method: "PATCH", url: `${api}/repos/acme/api/releases/100`, body: JSON.stringify({ draft: false }) });
374
+ // #4658: GitHub is told the release is latest, since it was not cut to a channel.
375
+ expect(forge.calls.at(-1)).toMatchObject({ method: "PATCH", url: `${api}/repos/acme/api/releases/100`, body: JSON.stringify({ draft: false, make_latest: "true" }) });
375
376
  expect(ctx.lines.join("\n")).not.toContain("ghs_tokentoken");
376
377
 
377
378
  // Published with every asset: a stage finds it done and uploads nothing.
@@ -112,6 +112,8 @@ export type ReleaseCutCode =
112
112
  | "release-build-inputs-differ"
113
113
  | "release-image-invalid"
114
114
  | "release-image-unknown-component"
115
+ | "release-image-name-taken"
116
+ | "release-image-build-failed"
115
117
  | "release-unsigned"
116
118
  | "release-signer-refused"
117
119
  | "declaration-invalid";
@@ -171,6 +173,12 @@ export interface CutRequest {
171
173
  * image, and the cut builds nothing for it.
172
174
  */
173
175
  images?: Readonly<Record<string, string>>;
176
+ /**
177
+ * Build the images `release.images` declares (#4657), before any
178
+ * environment is compiled, so the build command can read their digests.
179
+ * Given the commit being cut; returns each as an image artifact.
180
+ */
181
+ buildImages?: (commit: string) => Promise<ReleaseArtifact[]> | ReleaseArtifact[];
174
182
  }
175
183
 
176
184
  export interface CutResult {
@@ -462,6 +470,9 @@ async function prepare(req: CutRequest, record = false): Promise<Prepared> {
462
470
  );
463
471
  }
464
472
 
473
+ // #4657: the images first, so the build command that packs a package can pin their digests.
474
+ const builtImages = req.buildImages ? await req.buildImages(commit) : [];
475
+
465
476
  const compiled: CompiledTarget[] = [];
466
477
  for (const env of envs) compiled.push(await req.compiler.compile(env));
467
478
 
@@ -499,6 +510,11 @@ async function prepare(req: CutRequest, record = false): Promise<Prepared> {
499
510
  handedArtifacts.push(artifact);
500
511
  }
501
512
  const handedTo = new Set(handedArtifacts.map((a) => a.component));
513
+ for (const image of builtImages) {
514
+ if (enabled.has(image.component) || handedTo.has(image.component)) {
515
+ throw new ReleaseCutError("release-image-name-taken", `release.images names "${image.component}", which is also a component of this member, and a release records one image per name`, "Rename the image in release.images.");
516
+ }
517
+ }
502
518
 
503
519
  // Which environment each component's artifacts are built in: the first one it is enabled in.
504
520
  const firstEnv = new Map<string, CompiledTarget>();
@@ -510,7 +526,7 @@ async function prepare(req: CutRequest, record = false): Promise<Prepared> {
510
526
  const realCwd = realpathSync(cwd);
511
527
  const previous = firstEnv.size > 0 ? await previousRelease(top, commit, cwd) : undefined;
512
528
  const reused: CutResult["reused"] = [];
513
- const artifacts: ReleaseArtifact[] = [...handedArtifacts];
529
+ const artifacts: ReleaseArtifact[] = [...handedArtifacts, ...builtImages];
514
530
  const toBuild = new Map<string, string[]>();
515
531
  for (const [component, target] of firstEnv) {
516
532
  const prior = previous?.artifactDigests.filter((a) => a.component === component) ?? [];