@intentius/chant 0.124.104 → 0.124.106

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 (46) hide show
  1. package/dist/bundle-check.d.ts +7 -3
  2. package/dist/bundle-check.js +61 -10
  3. package/dist/capabilities/templates.d.ts +66 -3
  4. package/dist/capabilities/templates.js +220 -81
  5. package/dist/cli/handlers/release-doctor.js +8 -3
  6. package/dist/cli/handlers/release-init.js +7 -4
  7. package/dist/cli/handlers/search.d.ts +1 -1
  8. package/dist/cli/handlers/search.js +24 -2
  9. package/dist/cli/main.js +3 -2
  10. package/dist/cli/parse-args.js +2 -2
  11. package/dist/cli/release-commands/doctor.js +5 -2
  12. package/dist/cloud-lister/aws.d.ts +9 -0
  13. package/dist/cloud-lister/aws.js +20 -0
  14. package/dist/config.d.ts +10 -0
  15. package/dist/config.js +2 -0
  16. package/dist/floor-table.data.js +1 -0
  17. package/dist/graph-refs.d.ts +13 -0
  18. package/dist/graph-refs.js +11 -4
  19. package/dist/lifecycle/derive-edges.d.ts +1 -1
  20. package/dist/lifecycle/derive-edges.js +5 -3
  21. package/dist/lifecycle/index-import.d.ts +12 -5
  22. package/dist/lifecycle/index-import.js +38 -9
  23. package/dist/lifecycle/release-artifacts.js +3 -1
  24. package/dist/lifecycle/release-at.d.ts +5 -1
  25. package/dist/lifecycle/release-at.js +69 -4
  26. package/dist/lifecycle/release-doctor.d.ts +10 -0
  27. package/dist/lifecycle/release-doctor.js +84 -14
  28. package/dist/lifecycle/release-green.d.ts +5 -2
  29. package/dist/lifecycle/release-green.js +40 -8
  30. package/dist/lifecycle/release-images.d.ts +7 -1
  31. package/dist/lifecycle/release-images.js +14 -5
  32. package/dist/lifecycle/release-init.d.ts +16 -7
  33. package/dist/lifecycle/release-init.js +212 -45
  34. package/dist/lifecycle/release-next.d.ts +1 -1
  35. package/dist/lifecycle/release-next.js +9 -4
  36. package/dist/release-floors.d.ts +1 -1
  37. package/dist/release-floors.js +1 -1
  38. package/dist/wave-runtime.mjs +38 -38
  39. package/dist/workspace/capabilities-contract.d.ts +15 -5
  40. package/dist/workspace/capabilities-contract.js +7 -4
  41. package/dist/workspace/capabilities.schema.json +45 -1
  42. package/dist/workspace/release-changed.d.ts +2 -0
  43. package/dist/workspace/release-changed.js +7 -2
  44. package/dist/workspace/release-steps/doctor.js +2 -1
  45. package/dist/workspace/train-cut.js +2 -2
  46. package/package.json +1 -1
@@ -35,6 +35,7 @@
35
35
  import { execFileSync, spawn } from "node:child_process";
36
36
  import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
37
37
  import { isAbsolute, join, resolve } from "node:path";
38
+ import { parseYAML } from "../yaml.js";
38
39
  import { createRedactor, readCredential } from "./publish-credentials.js";
39
40
  /** The first chant with `chant release doctor`, which checks each `release.publish` target before a cut, and whose `chant release workflow` runs it in a dispatched release's cut job (`release.workflow.doctor`) (#5161). */
40
41
  export const RELEASE_DOCTOR_FLOOR = "0.124.101";
@@ -58,7 +59,7 @@ export function doctorEnvironment(env, req) {
58
59
  const ref = env.GITHUB_WORKFLOW_REF ?? "";
59
60
  const repository = env.GITHUB_REPOSITORY ?? (ci === "gitlab" ? (env.CI_PROJECT_PATH ?? null) : originRepository(req.cwd));
60
61
  const workflow = ci === "github" && repository && ref.startsWith(`${repository}/`) ? ref.slice(repository.length + 1).replace(/@.*$/, "") : null;
61
- return { ci, oidc, workflow, repository, releaseWorkflow: req.releaseWorkflow };
62
+ return { ci, oidc, workflow, repository, releaseWorkflow: req.releaseWorkflow, ...(req.from ? { from: req.from } : {}) };
62
63
  }
63
64
  /** `owner/name` of the `origin` remote, or null. */
64
65
  function originRepository(cwd) {
@@ -75,7 +76,7 @@ function originRepository(cwd) {
75
76
  export async function releaseDoctor(req) {
76
77
  const env = req.env ?? process.env;
77
78
  const deps = req.deps ?? {};
78
- const environment = doctorEnvironment(env, { cwd: req.cwd, releaseWorkflow: req.releaseWorkflow });
79
+ const environment = doctorEnvironment(env, { cwd: req.cwd, releaseWorkflow: req.releaseWorkflow, ...(req.from ? { from: req.from } : {}) });
79
80
  const redactor = createRedactor(env);
80
81
  const ctx = {
81
82
  cwd: req.cwd,
@@ -214,6 +215,23 @@ function missing(ctx, check, what, fix) {
214
215
  ? { check, status: "fail", message: `${what}, so a publish from this job fails`, fix }
215
216
  : { check, status: "warn", message: `${what} in this shell; the release job needs it in its environment`, fix };
216
217
  }
218
+ /**
219
+ * An OIDC token this job lacks, where the job is the cut job (`--from cut`):
220
+ * the release workflow gives the publish job the token and keeps it from the
221
+ * cut, which runs the project's build. The check can't tell from here.
222
+ */
223
+ function deferredToPublish(ctx, check, what) {
224
+ const held = ctx.environment.ci === "gitlab" ? "the publish job's id_tokens" : "the publish job's id-token: write";
225
+ return { check, status: "unknown", message: `${what}; this is the cut job, which runs without OIDC, and ${held} is what a publish uses, so only a run of the publish job can test this` };
226
+ }
227
+ /** No OIDC ID token for a trusted-publishing check: a failure, except in the cut job, where it can't be told. */
228
+ function noIdToken(ctx, check, none, fix, failMessage = none) {
229
+ return ctx.environment.from === "cut" ? deferredToPublish(ctx, check, none) : { check, status: "fail", message: failMessage, fix };
230
+ }
231
+ /** A token the publish needs, unset here. Where the target could use OIDC instead and this is the cut job, the publish job may hold that. */
232
+ function tokenMissing(ctx, check, what, fix, oidcCapable) {
233
+ return oidcCapable && ctx.environment.from === "cut" ? deferredToPublish(ctx, check, what) : missing(ctx, check, what, fix);
234
+ }
217
235
  async function answer(ctx, url, init) {
218
236
  const res = await ctx.fetch(url, { ...init, headers: { "user-agent": "chant", ...init.headers } });
219
237
  const text = await res.text().catch(() => "");
@@ -376,7 +394,7 @@ async function checkNpm(decl, ctx) {
376
394
  else if (exists) {
377
395
  const id = await idToken(ctx, `npm:${host}`, "NPM_ID_TOKEN");
378
396
  if ("none" in id) {
379
- checks.push(user ? { check: "npm-trusted-publisher", status: "unknown", message: `no trusted-publisher exchange: ${id.none}. npm's config signs in as ${user}, which the publish uses instead` } : { check: "npm-trusted-publisher", status: "fail", message: `${id.none}, and npm's config has no token, so nothing here can publish ${name}`, fix: "Give the job permissions: id-token: write (GitLab: an NPM_ID_TOKEN under id_tokens), or a token in the npm config it reads." });
397
+ checks.push(user ? { check: "npm-trusted-publisher", status: "unknown", message: `no trusted-publisher exchange: ${id.none}. npm's config signs in as ${user}, which the publish uses instead` } : noIdToken(ctx, "npm-trusted-publisher", `${id.none}, and npm's config has no token`, "Give the job permissions: id-token: write (GitLab: an NPM_ID_TOKEN under id_tokens), or a token in the npm config it reads.", `${id.none}, and npm's config has no token, so nothing here can publish ${name}`));
380
398
  }
381
399
  else {
382
400
  const ex = await answer(ctx, `${registry}/-/npm/v1/oidc/token/exchange/package/${name.replace("/", "%2f")}`, { method: "POST", headers: { authorization: `Bearer ${id.token}` } });
@@ -414,7 +432,7 @@ async function checkNpm(decl, ctx) {
414
432
  : { check: "npm-token", status: "unknown", message: `npm's config signs in as ${user}; ${registry} did not say what ${user} may do to ${name}, and a granular token's own scope is not shown` });
415
433
  }
416
434
  else if (!user && !env.oidc) {
417
- checks.push(missing(ctx, "npm-token", "npm's config has no token and the run has no OIDC token", "npm login on a workstation; in CI, permissions: id-token: write for trusted publishing, or a token in the npm config the job reads."));
435
+ checks.push(tokenMissing(ctx, "npm-token", "npm's config has no token and the run has no OIDC token", "npm login on a workstation; in CI, permissions: id-token: write for trusted publishing, or a token in the npm config the job reads.", true));
418
436
  }
419
437
  // The reveal moves a dist-tag, unless the target publishes straight to latest.
420
438
  if (decl.stage !== false && exists) {
@@ -522,6 +540,10 @@ async function repoAccess(ctx, req) {
522
540
  const push = res.json?.permissions?.push;
523
541
  if (push === true)
524
542
  return { check: req.check, status: "ok", message: `the token in ${req.tokenFrom} may write ${req.repo}` };
543
+ // A job's GITHUB_TOKEN is an installation token: the repository API reports no push right for it
544
+ // (absent, or false), whatever the job's permissions grant. The workflow file says what it grants.
545
+ if (ctx.environment.ci === "github" && req.tokenFrom === "GITHUB_TOKEN" && req.forge === "github")
546
+ return jobTokenAccess(ctx, req);
525
547
  if (push === false)
526
548
  return { check: req.check, status: "fail", message: `the token in ${req.tokenFrom} may read ${req.repo} and not write it`, fix: `Give the token write access to ${req.repo}${req.forge === "github" ? " (contents: write)" : ""}.` };
527
549
  const scopes = res.header("x-oauth-scopes");
@@ -537,6 +559,54 @@ async function repoAccess(ctx, req) {
537
559
  message: `the token in ${req.tokenFrom} sees ${req.repo}; ${req.api} does not say what this kind of token may write${ctx.environment.ci === "github" && req.tokenFrom === "GITHUB_TOKEN" ? ", and a job token gets contents: write from the workflow's permissions" : ""}`,
538
560
  };
539
561
  }
562
+ /** The `contents` right the running job's declared `permissions` give its GITHUB_TOKEN, read from the workflow file in the checkout; null when it can't be told. */
563
+ function jobContentsPermission(ctx) {
564
+ const file = ctx.environment.workflow;
565
+ const job = ctx.env.GITHUB_JOB;
566
+ if (!file || !job)
567
+ return { right: null, where: "the workflow file", why: "GITHUB_WORKFLOW_REF or GITHUB_JOB is not set" };
568
+ const abs = join(ctx.env.GITHUB_WORKSPACE || ctx.cwd, file);
569
+ const where = `${file}, job ${job}`;
570
+ let doc;
571
+ try {
572
+ doc = parseYAML(readFileSync(abs, "utf-8"));
573
+ }
574
+ catch {
575
+ return { right: null, where, why: `${file} is not in the checkout, or does not parse` };
576
+ }
577
+ const j = doc.jobs?.[job];
578
+ if (!j || typeof j !== "object")
579
+ return { right: null, where, why: `${file} has no job ${job}` };
580
+ // A job's own `permissions` replaces the workflow's whole; with neither, the repository's default decides.
581
+ const declared = j.permissions !== undefined ? j.permissions : doc.permissions;
582
+ if (declared === undefined || declared === null)
583
+ return { right: null, where, why: "neither the job nor the workflow declares permissions, so the repository's default token permissions apply" };
584
+ if (declared === "write-all")
585
+ return { right: "write", where, why: "" };
586
+ if (declared === "read-all")
587
+ return { right: "read", where, why: "" };
588
+ if (typeof declared !== "object")
589
+ return { right: null, where, why: "its permissions are an expression" };
590
+ const contents = declared.contents;
591
+ if (contents === "write")
592
+ return { right: "write", where, why: "" };
593
+ if (contents === "read")
594
+ return { right: "read", where, why: "" };
595
+ if (contents === undefined || contents === "none")
596
+ return { right: "none", where, why: "" };
597
+ return { right: null, where, why: "its contents permission is an expression" };
598
+ }
599
+ /** What the job's GITHUB_TOKEN may do on the repository: ok or fail from the declared permissions, unknown when they can't be read. Never fail on the API's silence. */
600
+ function jobTokenAccess(ctx, req) {
601
+ const p = jobContentsPermission(ctx);
602
+ if (p.right === "write")
603
+ return { check: req.check, status: "ok", message: `the job's ${req.tokenFrom} may write ${req.repo}: ${p.where} declares contents: write` };
604
+ if (ctx.environment.from === "cut" && p.right !== null)
605
+ return { check: req.check, status: "unknown", message: `this is the cut job, whose ${req.tokenFrom} has contents: ${p.right} (${p.where}); the publish job holds the write the forge target needs, so only a run of the publish job can test this` };
606
+ if (p.right === "read" || p.right === "none")
607
+ return { check: req.check, status: "fail", message: `${p.where} declares contents: ${p.right}, so the job's ${req.tokenFrom} may read ${req.repo} and not write it`, fix: "Give the job permissions: contents: write." };
608
+ return { check: req.check, status: "unknown", message: `the job's ${req.tokenFrom} sees ${req.repo}; the API does not report what an Actions token may write, and ${p.why}` };
609
+ }
540
610
  async function checkForge(decl, ctx) {
541
611
  const { forgeApi, forgeTokenEnv } = await import("./publish-forge.js");
542
612
  const checks = [];
@@ -814,7 +884,7 @@ async function checkMcpRegistry(decl, ctx) {
814
884
  // The target reads only GitHub Actions' token service, so no variable stands in for it.
815
885
  const tok = await idToken(ctx, audience, "");
816
886
  if ("none" in tok) {
817
- checks.push({ check: "mcp-registry-auth", status: "fail", message: ctx.environment.ci === "github" ? tok.none : "this publish gets its OIDC token from GitHub Actions, and this run is not one", fix: "Give the job permissions: id-token: write." });
887
+ checks.push(noIdToken(ctx, "mcp-registry-auth", ctx.environment.ci === "github" ? tok.none : "this publish gets its OIDC token from GitHub Actions, and this run is not one", "Give the job permissions: id-token: write."));
818
888
  return t;
819
889
  }
820
890
  const ex = await answer(ctx, `${registry}/v0.1/auth/github-oidc`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ oidc_token: tok.token }) });
@@ -878,7 +948,7 @@ async function checkMarketplace(decl, ctx) {
878
948
  }
879
949
  const tok = await idToken(ctx, registry, OVSX_ID_TOKEN_ENV);
880
950
  if ("none" in tok) {
881
- checks.push({ check: "marketplace-trusted-publisher", status: "fail", message: tok.none, fix: `Give the job permissions: id-token: write, or put an ID token in ${OVSX_ID_TOKEN_ENV}.` });
951
+ checks.push(noIdToken(ctx, "marketplace-trusted-publisher", tok.none, `Give the job permissions: id-token: write, or put an ID token in ${OVSX_ID_TOKEN_ENV}.`));
882
952
  return t;
883
953
  }
884
954
  const ex = await answer(ctx, `${registry}/api/-/trusted-publishing/token`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ namespace: id.publisher, extension: id.name, token: tok.token }) });
@@ -946,7 +1016,7 @@ async function checkPypi(decl, ctx) {
946
1016
  const token = readCredential(ctx.env, [tokenName], ctx.redactor);
947
1017
  checks.push(token
948
1018
  ? { check: "pypi-token", status: "unknown", message: `the token in ${tokenName} is set; ${index.label} has no read-only check of a token, so whether it may upload shows at the upload` }
949
- : missing(ctx, "pypi-token", `${tokenName} is not set${index.site ? " and there is no OIDC ID token for trusted publishing" : ""}`, `Set ${tokenName} to an API token for the project${index.site ? ", or publish with trusted publishing from a CI job with an OIDC ID token" : ""}.`));
1019
+ : tokenMissing(ctx, "pypi-token", `${tokenName} is not set${index.site ? " and there is no OIDC ID token for trusted publishing" : ""}`, `Set ${tokenName} to an API token for the project${index.site ? ", or publish with trusted publishing from a CI job with an OIDC ID token" : ""}.`, decl.auth === undefined && index.site !== null));
950
1020
  return t;
951
1021
  }
952
1022
  if (!ctx.environment.ci && !ctx.env[PYPI_ID_TOKEN_ENV]) {
@@ -961,7 +1031,7 @@ async function checkPypi(decl, ctx) {
961
1031
  }
962
1032
  const tok = await idToken(ctx, audience, PYPI_ID_TOKEN_ENV);
963
1033
  if ("none" in tok) {
964
- checks.push({ check: "pypi-trusted-publisher", status: "fail", message: tok.none, fix: `Give the job permissions: id-token: write, or declare ${PYPI_ID_TOKEN_ENV} under the GitLab job's id_tokens with the audience ${audience}.` });
1034
+ checks.push(noIdToken(ctx, "pypi-trusted-publisher", tok.none, `Give the job permissions: id-token: write, or declare ${PYPI_ID_TOKEN_ENV} under the GitLab job's id_tokens with the audience ${audience}.`));
965
1035
  return t;
966
1036
  }
967
1037
  const ex = await answer(ctx, `${index.site}/_/oidc/mint-token`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token: tok.token }) });
@@ -1056,7 +1126,7 @@ async function checkNuget(decl, ctx) {
1056
1126
  const tokenName = nugetTokenEnv(decl);
1057
1127
  checks.push(readCredential(ctx.env, [tokenName], ctx.redactor)
1058
1128
  ? { check: "nuget-token", status: "unknown", message: `the API key in ${tokenName} is set; ${feed.label} has no read-only check of a key, so whether it may push shows at the push` }
1059
- : missing(ctx, "nuget-token", `${tokenName} is not set${feed.nugetOrg ? " and there is no OIDC ID token for trusted publishing" : ""}`, `Set ${tokenName} to an API key that may push the packages${feed.nugetOrg ? ", or publish with trusted publishing from a CI job with an OIDC ID token" : ""}.`));
1129
+ : tokenMissing(ctx, "nuget-token", `${tokenName} is not set${feed.nugetOrg ? " and there is no OIDC ID token for trusted publishing" : ""}`, `Set ${tokenName} to an API key that may push the packages${feed.nugetOrg ? ", or publish with trusted publishing from a CI job with an OIDC ID token" : ""}.`, decl.auth === undefined && Boolean(feed.nugetOrg)));
1060
1130
  return t;
1061
1131
  }
1062
1132
  const userName = nugetUserEnv(decl);
@@ -1071,7 +1141,7 @@ async function checkNuget(decl, ctx) {
1071
1141
  }
1072
1142
  const tok = await idToken(ctx, NUGET_AUDIENCE, NUGET_ID_TOKEN_ENV);
1073
1143
  if ("none" in tok) {
1074
- checks.push({ check: "nuget-trusted-publisher", status: "fail", message: tok.none, fix: `Give the job permissions: id-token: write, or declare ${NUGET_ID_TOKEN_ENV} under the GitLab job's id_tokens with aud: ${NUGET_AUDIENCE}.` });
1144
+ checks.push(noIdToken(ctx, "nuget-trusted-publisher", tok.none, `Give the job permissions: id-token: write, or declare ${NUGET_ID_TOKEN_ENV} under the GitLab job's id_tokens with aud: ${NUGET_AUDIENCE}.`));
1075
1145
  return t;
1076
1146
  }
1077
1147
  const ex = await answer(ctx, NUGET_ORG.token, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${tok.token}` }, body: JSON.stringify({ username: user.value, tokenType: "ApiKey" }) });
@@ -1121,7 +1191,7 @@ async function checkRubygems(decl, ctx) {
1121
1191
  const tokenName = rubygemsTokenEnv(decl);
1122
1192
  checks.push(readCredential(ctx.env, [tokenName], ctx.redactor)
1123
1193
  ? { check: "rubygems-token", status: "unknown", message: `the API key in ${tokenName} is set; ${label} has no read-only check of a key, so whether it may push shows at the push` }
1124
- : missing(ctx, "rubygems-token", `${tokenName} is not set${decl.host ? "" : " and there is no OIDC ID token for trusted publishing"}`, `Set ${tokenName} to an API key with the push scope${decl.host ? "" : ", or publish with trusted publishing from a GitHub Actions job with id-token: write"}.`));
1194
+ : tokenMissing(ctx, "rubygems-token", `${tokenName} is not set${decl.host ? "" : " and there is no OIDC ID token for trusted publishing"}`, `Set ${tokenName} to an API key with the push scope${decl.host ? "" : ", or publish with trusted publishing from a GitHub Actions job with id-token: write"}.`, decl.auth === undefined && !decl.host));
1125
1195
  return t;
1126
1196
  }
1127
1197
  if (!ctx.environment.ci && !ctx.env[RUBYGEMS_ID_TOKEN_ENV]) {
@@ -1130,7 +1200,7 @@ async function checkRubygems(decl, ctx) {
1130
1200
  }
1131
1201
  const tok = await idToken(ctx, RUBYGEMS_AUDIENCE, RUBYGEMS_ID_TOKEN_ENV);
1132
1202
  if ("none" in tok) {
1133
- checks.push({ check: "rubygems-trusted-publisher", status: "fail", message: tok.none, fix: "Give the job permissions: id-token: write." });
1203
+ checks.push(noIdToken(ctx, "rubygems-trusted-publisher", tok.none, "Give the job permissions: id-token: write."));
1134
1204
  return t;
1135
1205
  }
1136
1206
  const ex = await answer(ctx, `${host}/api/v1/oidc/trusted_publisher/exchange_token`, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, body: JSON.stringify({ jwt: tok.token }) });
@@ -1172,7 +1242,7 @@ async function checkCargo(decl, ctx) {
1172
1242
  if (auth === "token") {
1173
1243
  const tokenName = cargoTokenEnv(decl);
1174
1244
  const token = readCredential(ctx.env, [tokenName], ctx.redactor);
1175
- checks.push(token ? { check: "cargo-token", status: "unknown", message: `the token in ${tokenName} is set; ${label} has no read-only check of a token, so whether it may publish shows at the publish` } : missing(ctx, "cargo-token", `${tokenName} is not set`, `Set ${tokenName} to a token of ${label}.`));
1245
+ checks.push(token ? { check: "cargo-token", status: "unknown", message: `the token in ${tokenName} is set; ${label} has no read-only check of a token, so whether it may publish shows at the publish` } : tokenMissing(ctx, "cargo-token", `${tokenName} is not set`, `Set ${tokenName} to a token of ${label}.`, decl.auth === undefined && decl.registry === undefined));
1176
1246
  return t;
1177
1247
  }
1178
1248
  if (!ctx.environment.ci && !ctx.env[CRATES_IO_ID_TOKEN_ENV]) {
@@ -1181,7 +1251,7 @@ async function checkCargo(decl, ctx) {
1181
1251
  }
1182
1252
  const tok = await idToken(ctx, CRATES_IO_AUDIENCE, CRATES_IO_ID_TOKEN_ENV);
1183
1253
  if ("none" in tok) {
1184
- checks.push({ check: "cargo-trusted-publisher", status: "fail", message: tok.none, fix: "Give the job permissions: id-token: write." });
1254
+ checks.push(noIdToken(ctx, "cargo-trusted-publisher", tok.none, "Give the job permissions: id-token: write."));
1185
1255
  return t;
1186
1256
  }
1187
1257
  const api = (decl.api ?? CRATES_IO_API).replace(/\/+$/, "");
@@ -6,8 +6,11 @@
6
6
  * `ci/revoked/<sha>` tag, as `chant ci` writes them from `ci.green`
7
7
  * (./release-cut.ts). The default when `chant.workspace.json` declares
8
8
  * `ci.green` or the repository holds any `ci/green/` tag.
9
- * - `forge-checks`: the forge's checks on the commit passed. GitHub: every
10
- * check run and commit status, and each check a branch rule of the
9
+ * - `forge-checks`: the forge's checks on the commit passed. Each check is
10
+ * judged by its newest run on the commit (GitHub: per check name and app,
11
+ * and per status context; newest completion time, ties by highest id), so
12
+ * a failed merge_group run followed by a passing push run is green.
13
+ * GitHub: every check run and commit status, and each check a branch rule of the
11
14
  * branch requires. Forgejo: every commit status, and each context its
12
15
  * branch protection requires when the token can read it. GitLab: the
13
16
  * newest pipeline of each source on the commit. A check that failed or has
@@ -6,8 +6,11 @@
6
6
  * `ci/revoked/<sha>` tag, as `chant ci` writes them from `ci.green`
7
7
  * (./release-cut.ts). The default when `chant.workspace.json` declares
8
8
  * `ci.green` or the repository holds any `ci/green/` tag.
9
- * - `forge-checks`: the forge's checks on the commit passed. GitHub: every
10
- * check run and commit status, and each check a branch rule of the
9
+ * - `forge-checks`: the forge's checks on the commit passed. Each check is
10
+ * judged by its newest run on the commit (GitHub: per check name and app,
11
+ * and per status context; newest completion time, ties by highest id), so
12
+ * a failed merge_group run followed by a passing push run is green.
13
+ * GitHub: every check run and commit status, and each check a branch rule of the
11
14
  * branch requires. Forgejo: every commit status, and each context its
12
15
  * branch protection requires when the token can read it. GitLab: the
13
16
  * newest pipeline of each source on the commit. A check that failed or has
@@ -78,6 +81,25 @@ export function judgeChecks(forge, checks, required) {
78
81
  return { green: false, forge, checks, why: `the branch requires ${missing.join(", ")}, which ${forge} does not report on it` };
79
82
  return { green: true, forge, checks: [...names].sort() };
80
83
  }
84
+ const num = (v) => (typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v) ? Number(v) : 0);
85
+ const time = (...vs) => {
86
+ for (const v of vs) {
87
+ const t = typeof v === "string" ? Date.parse(v) : NaN;
88
+ if (!Number.isNaN(t))
89
+ return t;
90
+ }
91
+ return 0;
92
+ };
93
+ /** The newest reading of each key: latest time, ties by highest id. A rerun, or a later run on the same commit, supersedes the one before it, as in GitHub's own rollup. */
94
+ function newestRuns(readings) {
95
+ const out = new Map();
96
+ for (const r of readings) {
97
+ const had = out.get(r.key);
98
+ if (!had || r.at > had.at || (r.at === had.at && r.id > had.id))
99
+ out.set(r.key, r);
100
+ }
101
+ return [...out.values()].map((r) => r.check);
102
+ }
81
103
  const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
82
104
  const str = (v) => (typeof v === "string" ? v : undefined);
83
105
  /** Whether `url` is a page of one of the CI runs `runIds` (`.../actions/runs/<id>` or `.../actions/runs/<id>/...`). */
@@ -138,7 +160,7 @@ export function forgeChecksReader(target, env = process.env, fetchImpl) {
138
160
  runId.add(String(r.id));
139
161
  }
140
162
  }
141
- const checks = [];
163
+ const runReadings = [];
142
164
  for (let page = 1; page <= 20; page++) {
143
165
  const got = await get(`${repo}/commits/${sha}/check-runs?per_page=100&page=${page}`);
144
166
  const runs = isObject(got) && Array.isArray(got.check_runs) ? got.check_runs.filter(isObject) : [];
@@ -149,20 +171,29 @@ export function forgeChecksReader(target, env = process.env, fetchImpl) {
149
171
  continue;
150
172
  const status = str(r.status) ?? "unknown";
151
173
  const conclusion = str(r.conclusion) ?? null;
152
- checks.push({ name, state: checkState(status, conclusion), status: status === "completed" ? (conclusion ?? status) : status, ...(url ? { url } : {}) });
174
+ const app = isObject(r.app) ? String(r.app.id ?? r.app.slug ?? "") : "";
175
+ runReadings.push({
176
+ key: `${app}\0${name}`,
177
+ at: time(r.completed_at, r.started_at),
178
+ id: num(r.id),
179
+ check: { name, state: checkState(status, conclusion), status: status === "completed" ? (conclusion ?? status) : status, ...(url ? { url } : {}) },
180
+ });
153
181
  }
154
182
  if (runs.length < 100)
155
183
  break;
156
184
  }
185
+ const checks = newestRuns(runReadings);
157
186
  const combined = await get(`${repo}/commits/${sha}/status?per_page=100`);
187
+ const statusReadings = [];
158
188
  for (const s of isObject(combined) && Array.isArray(combined.statuses) ? combined.statuses.filter(isObject) : []) {
159
189
  const name = str(s.context);
160
190
  const url = str(s.target_url);
161
191
  if (!name || inRun(url, runId))
162
192
  continue;
163
193
  const state = str(s.state) ?? "unknown";
164
- checks.push({ name, state: state === "error" ? "failure" : checkState(state), status: state, ...(url ? { url } : {}) });
194
+ statusReadings.push({ key: name, at: time(s.updated_at, s.created_at), id: num(s.id), check: { name, state: state === "error" ? "failure" : checkState(state), status: state, ...(url ? { url } : {}) } });
165
195
  }
196
+ checks.push(...newestRuns(statusReadings));
166
197
  const required = [];
167
198
  if (branch) {
168
199
  const rules = await get(`${repo}/rules/branches/${encodeURIComponent(branch)}`, true);
@@ -185,15 +216,16 @@ export function forgeChecksReader(target, env = process.env, fetchImpl) {
185
216
  const repo = `/repos/${target.repo}`;
186
217
  return async (sha, branch) => {
187
218
  const combined = await get(`${repo}/commits/${sha}/status?limit=100`);
188
- const checks = [];
219
+ const readings = [];
189
220
  for (const s of isObject(combined) && Array.isArray(combined.statuses) ? combined.statuses.filter(isObject) : []) {
190
221
  const name = str(s.context);
191
222
  const url = str(s.target_url);
192
223
  if (!name || inRun(url, runNumber))
193
224
  continue;
194
225
  const state = str(s.status) ?? str(s.state) ?? "unknown";
195
- checks.push({ name, state: state === "error" ? "failure" : checkState(state), status: state, ...(url ? { url } : {}) });
226
+ readings.push({ key: name, at: time(s.updated_at, s.created_at), id: num(s.id), check: { name, state: state === "error" ? "failure" : checkState(state), status: state, ...(url ? { url } : {}) } });
196
227
  }
228
+ const checks = newestRuns(readings);
197
229
  const required = [];
198
230
  if (branch) {
199
231
  const protections = await get(`${repo}/branch_protections`, true);
@@ -233,7 +265,7 @@ export function forgeChecksReader(target, env = process.env, fetchImpl) {
233
265
  return judgeChecks("gitlab", checks, []);
234
266
  };
235
267
  }
236
- /** Each check name once, at the worst state any entry of that name has, so a check run and a status of the same name can't hide a failure. */
268
+ /** Each check name once, at the worst state any entry of that name has, so a check run and a status of the same name can't hide a failure. Reruns of one check are already collapsed to the newest by `newestRuns`. */
237
269
  function newestByName(checks) {
238
270
  const rank = { failure: 2, pending: 1, success: 0 };
239
271
  const out = new Map();
@@ -144,7 +144,13 @@ export declare class ReleaseImageError extends Error {
144
144
  readonly fix?: string | undefined;
145
145
  constructor(code: string, message: string, fix?: string | undefined);
146
146
  }
147
- /** Check a member's `release.images`: names valid and unique, one of `build` and `dockerfile`, paths inside the member, platforms of the form os/arch. */
147
+ /**
148
+ * Check a member's `release.images`: names valid and unique, one of `build`
149
+ * and `dockerfile`, the archive inside the member, platforms of the form
150
+ * os/arch. The Dockerfile and the context, which the build only reads, may
151
+ * leave the member with `..` (#5271), so a member at `release/<name>` builds
152
+ * the repository root's Dockerfile.
153
+ */
148
154
  export declare function checkReleaseImages(images: readonly ReleaseImageDeclaration[]): void;
149
155
  /** The digest of an OCI archive: its top manifest's, as `index.json` names it. */
150
156
  export type ArchiveDigest = (abs: string) => string;
@@ -161,7 +161,13 @@ const LABEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/;
161
161
  /** The build arguments chant passes itself, which an entry's `args` cannot set. */
162
162
  const CHANT_BUILD_ARGS = ["SOURCE_DATE_EPOCH", "CHANT_RELEASE_LABEL"];
163
163
  const outside = (p) => isAbsolute(p) || p.split(/[\\/]/).includes("..");
164
- /** Check a member's `release.images`: names valid and unique, one of `build` and `dockerfile`, paths inside the member, platforms of the form os/arch. */
164
+ /**
165
+ * Check a member's `release.images`: names valid and unique, one of `build`
166
+ * and `dockerfile`, the archive inside the member, platforms of the form
167
+ * os/arch. The Dockerfile and the context, which the build only reads, may
168
+ * leave the member with `..` (#5271), so a member at `release/<name>` builds
169
+ * the repository root's Dockerfile.
170
+ */
165
171
  export function checkReleaseImages(images) {
166
172
  const seen = new Set();
167
173
  for (const i of images) {
@@ -172,10 +178,13 @@ export function checkReleaseImages(images) {
172
178
  seen.add(i.name);
173
179
  if (isDockerfile(i) && "build" in i)
174
180
  throw new ReleaseImageError("release-image-invalid", `release.images "${i.name}" names a build command and a Dockerfile; chant builds a Dockerfile itself, so name one`);
175
- const paths = isDockerfile(i) ? [["the archive", archiveOf(i)], ["the Dockerfile", i.dockerfile], ["the context", i.context]] : [["the archive", i.archive]];
176
- for (const [what, p] of paths) {
177
- if (p !== undefined && outside(p))
178
- throw new ReleaseImageError("release-image-archive-outside", `release.images "${i.name}": ${what} ${p} is not a path inside the member`);
181
+ if (outside(archiveOf(i)))
182
+ throw new ReleaseImageError("release-image-archive-outside", `release.images "${i.name}": the archive ${archiveOf(i)} is not a path inside the member`);
183
+ if (isDockerfile(i)) {
184
+ for (const [what, p] of [["the Dockerfile", i.dockerfile], ["the context", i.context]]) {
185
+ if (p !== undefined && isAbsolute(p))
186
+ throw new ReleaseImageError("release-image-archive-outside", `release.images "${i.name}": ${what} ${p} is an absolute path; name it relative to the member`);
187
+ }
179
188
  }
180
189
  for (const [k, v] of Object.entries((isDockerfile(i) && i.labels) || {})) {
181
190
  if (!LABEL_KEY.test(k))
@@ -233,14 +233,14 @@ export declare function tagTemplateOf(facts: Pick<ProjectFacts, "tags" | "go" |
233
233
  };
234
234
  /** Plan the `release` block for a project. */
235
235
  export declare function planRelease(facts: ProjectFacts, opts: PlanOptions): ReleaseInitPlan;
236
- /** One member of a planned train: a publishable package, released at its own version from its own `chant.config.ts`. */
236
+ /** One member of a planned train: a publishable package, or what the train builds outside one, released at its own version from its own `chant.config.ts`. */
237
237
  export interface TrainMemberPlan {
238
238
  /** The member's name in `chant.workspace.json`. */
239
239
  name: string;
240
- /** The package's directory from the project root. */
240
+ /** The member's directory from the project root. */
241
241
  dir: string;
242
- /** The npm package name. */
243
- package: string;
242
+ /** The npm package name, or null for a member that is no workspace package (#5271). */
243
+ package: string | null;
244
244
  /** The member's `release` block. */
245
245
  release: Record<string, Json>;
246
246
  }
@@ -260,9 +260,15 @@ export interface ReleaseTrainPlan {
260
260
  }
261
261
  /** The environment a planned train is recorded for. */
262
262
  export declare const TRAIN_ENV = "npm";
263
+ /** The directory a train member init makes for what no workspace package holds (#5271), from the project root. */
264
+ export declare const TRAIN_OWN_DIR = "release";
265
+ /** The rule by which init gives a train member what the project builds besides its packages (#5271), as the plan's reasons print it. */
266
+ export declare const TRAIN_OWNERSHIP_RULE = "an image, chart or Python or Rust package belongs to the train member whose directory holds its file; what no member's directory holds gets a member of its own at release/<name>, one per directory, whose entries name the files with ../.. and whose release.sources names that directory, so release changed releases it when the files change";
263
267
  /**
264
268
  * Whether the project's npm, pnpm or yarn workspaces can release as a train:
265
- * one member per publishable package (#5154). `why` says why a project with
269
+ * one member per publishable package or VS Code extension (#5154, #5271),
270
+ * with the images, charts and Python or Rust package beside them given to a
271
+ * member by {@link TRAIN_OWNERSHIP_RULE}. `why` says why a project with
266
272
  * several packages gets one release instead, and is null for a project with
267
273
  * fewer than two.
268
274
  */
@@ -276,8 +282,11 @@ export declare function trainFit(facts: ProjectFacts): {
276
282
  export declare function memberNameOf(pkg: Pick<InitPackage, "name" | "dir">): string;
277
283
  /**
278
284
  * Plan a train for a project {@link trainFit} accepts: a member per
279
- * publishable workspace package, each stamping and publishing its own
280
- * package, and the root's `release.train` with a dispatched workflow.
285
+ * publishable workspace package or VS Code extension, each stamping and
286
+ * publishing its own package, the images and charts each member's
287
+ * directory holds, a member at `release/<name>` for each other directory
288
+ * that holds an image, a chart, or a Python or Rust package (#5271), and the
289
+ * root's `release.train` with a dispatched workflow.
281
290
  */
282
291
  export declare function planTrain(facts: ProjectFacts, opts: PlanOptions): ReleaseTrainPlan;
283
292
  /** A value as TypeScript source, objects and arrays on one line when short. */