@intellectual-frontiers/libraries 0.1.1 → 0.4.0

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.
@@ -3,9 +3,8 @@
3
3
  * are written once, the workflow of each library of commons is made from its manifest, and the rest are written here as values. Nothing is read from a file but the manifests, and nothing is written.
4
4
  *
5
5
  * @remarks
6
- * `workflows(libraries)` gives every workflow, in the order of their files' names; the library workflows come from `libraryWorkflow`, which reads the folder, the name and the `verify` command of a manifest
7
- * (0027-commons-libraries FR-012) and what else the library's job needs from `LIBRARY_CI`, the facts of CI that a manifest does not hold (a library without a record has the job `verify` and nothing else).
8
- * The workflows run on the same triggers, with the same jobs and steps and the same names as the hand-written ones they replaced, so that the names of their checks do not change.
6
+ * `workflows()` gives every workflow, in the order of their files' names; the libraries are proved by one workflow, `ci`, whose plan reads which libraries a change affects and runs a matrix of those (the folder, the
7
+ * name and the `verify` command of a manifest, 0027-commons-libraries FR-012, and what else the library needs from `LIBRARY_CI`, the facts of CI that a manifest does not hold: a library without a record has `verify` on Linux and nothing else).
9
8
  *
10
9
  * @limits
11
10
  * It does not run a workflow or read one; a library that registers needs no entry of `LIBRARY_CI` unless its CI is more than `verify`.
@@ -49,154 +48,125 @@ const lines = (...l) => `${l.join("\n")}\n`;
49
48
  /** The files a workflow of this repository runs on a change of (a push and a pull request alike). */
50
49
  const BUN_ACTION = ".github/actions/bun/**";
51
50
  const own = (file) => `.github/workflows/${file}.auto.yml`;
52
- /** The facts of CI of the libraries that have more than `verify`, by the library's name. */
51
+ const NODE_TESTS = 'node --test "suite/**/*.test.ts"';
52
+ const ALL_OTHER = ["windows-latest", "macos-latest"];
53
+ const node = { nodeTests: NODE_TESTS };
54
+ /** The facts of CI of the libraries that have more than `verify` on Linux, by the library's name; a library with no record has `verify` on Linux only. */
53
55
  export const LIBRARY_CI = {
54
- data: {
55
- comment: lines("IFC data, an independent library of commons (commons 0027-commons-libraries FR-010): its own `verify` (the compiler, the specification checker and the rules on its own", "spec kit, and its tests) on Bun, and its tests on Node 26, the backup runtime (commons 0005-typescript-runtime). It runs when its folder changes or what it imports does:", "the kernel and the runtime, the specification tools, and the Bun action.").trimEnd(),
56
- afterVerify: [
57
- run("bun tools/generate-dpv.ts --check", {
58
- name: "The terms of DPV, as the vocabulary's CSV makes them (a fetch, so not in verify)",
59
- workingDirectory: "commons/data",
60
- }),
61
- ],
62
- nodeTests: 'node --test "suite/**/*.test.ts"',
63
- },
64
- core: {
65
- comment: lines("Core, the foundation of commons, the first library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the packing of its", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
66
- nodeTests: 'node --test "suite/**/*.test.ts"',
67
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
68
- },
69
- rdf: {
70
- comment: lines("RDF, typed RDF and its writers, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
71
- nodeTests: 'node --test "suite/**/*.test.ts"',
72
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
73
- },
74
- terminal: {
75
- comment: lines("Terminal, the command line and the console as pure code, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
76
- nodeTests: 'node --test "suite/**/*.test.ts"',
77
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
78
- },
79
- net: {
80
- comment: lines("Net, the network as one typed library (downloads, an HTTP server and clients, TCP and TLS, DNS and ACME), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
81
- nodeTests: 'node --test "suite/**/*.test.ts"',
82
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
83
- },
84
- grc: {
85
- comment: lines("GRC, governance, risk and compliance as code as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
86
- nodeTests: 'node --test "suite/**/*.test.ts"',
87
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
88
- },
89
- test: {
90
- comment: lines("Test, tests that run unchanged under `bun test` and `node --test` and are recorded as evidence by their own code, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
91
- nodeTests: 'node --test "suite/**/*.test.ts"',
92
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
93
- },
94
- lint: {
95
- comment: lines("Lint, the lint plugin of Intellectual Frontiers, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the pinned linter's canary, the compiler, the specification checker, the trace, its tests, which run", "the real `bun lint`, and the packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
96
- nodeTests: `bun x bun@${BUN_LINT_VERSION} --version && node --test "suite/**/*.test.ts"`,
97
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
98
- },
99
- githost: {
100
- comment: lines("Githost, the Git hosts behind one typed interface (GitHub, GitLab and plain Git) and the reading of a remote, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
101
- nodeTests: 'node --test "suite/**/*.test.ts"',
102
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
103
- },
104
- ontology: {
105
- comment: lines("Ontology, the ontologies of commons as typed values (Mizan, IFCCM, IFQS, IFR, the audit of packaging and the software supply chain), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the spec checker, the trace, its tests and the packing of its package with the inspection of its declarations) on Bun and its tests on", "Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
106
- nodeTests: 'node --test "suite/**/*.test.ts"',
107
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
108
- },
109
- mizan: {
110
- comment: lines("Mizan, the harness and the rules of the IF Spec Profile as plugins, with the change-control and release rules, the levels, the integrations and the trace, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the spec checker, the trace, its tests and the packing of its package with the inspection of its declarations) on Bun and its tests on", "Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
111
- nodeTests: 'node --test "suite/**/*.test.ts"',
112
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
113
- },
114
- libraries: {
115
- comment: lines("Libraries, the tools that manage the libraries of a repository of commons and hold it to Mizan (the manifest, the affected libraries, the typed workflows and their generator, the pinned Bun, the packer and the", "commands of the repository), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the packing of its package with", "the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
116
- nodeTests: 'node --test "suite/**/*.test.ts"',
117
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
118
- },
119
- headless: {
120
- comment: lines("Headless, the contract of a program with no window in layers (governance, logical, the command-line surface), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the layers and trace checks, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
121
- nodeTests: 'node --test "suite/**/*.test.ts"',
122
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
123
- },
124
- telemetry: {
125
- comment: lines("Telemetry, OpenTelemetry-native signals as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
126
- nodeTests: 'node --test "suite/**/*.test.ts"',
127
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
128
- },
129
- system: {
130
- comment: lines("System, the host as one typed library (files, paths, processes, Git, scheduled jobs and the terminal's streams), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
131
- nodeTests: 'node --test "suite/**/*.test.ts"',
132
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
133
- },
134
- formats: {
135
- comment: lines("Formats, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the packing of its", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
136
- nodeTests: 'node --test "suite/**/*.test.ts"',
137
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
138
- },
139
- crypto: {
140
- comment: lines("Crypto, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the packing of its", "package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
141
- nodeTests: 'node --test "suite/**/*.test.ts"',
142
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
143
- },
144
- quality: {
145
- comment: lines("Quality, the quality system of commons (the record of a run as evidence, the quality branch, the ladder, the ledger, the Trust page and the assessor pack), a library lifted out of `commons/ts`", "(commons 0032-lifting-libraries): its own `verify` on Bun and its tests, which run a real Git, on Node 26, on Linux.").trimEnd(),
146
- nodeTests: 'node --test "suite/**/*.test.ts"',
147
- },
148
- ergonex: {
149
- comment: lines("Ergonex, the workspaces management of Intellectual Frontiers, a library of commons (commons 0027-commons-libraries FR-010): its own `verify` on Bun and its tests on Node 26, the backup runtime,", "on Windows first, then macOS and Linux (ergonex 0004-onboarding): a person on any of them installs the command from npm and runs it.").trimEnd(),
150
- nodeTests: 'node --test "suite/**/*.test.ts"',
151
- systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
152
- },
56
+ data: { nodeTests: NODE_TESTS, after: "bun tools/generate-dpv.ts --check" },
57
+ core: node,
58
+ rdf: node,
59
+ terminal: node,
60
+ net: { nodeTests: NODE_TESTS, systems: ALL_OTHER },
61
+ grc: node,
62
+ test: node,
63
+ lint: { nodeTests: `bun x bun@${BUN_LINT_VERSION} --version && ${NODE_TESTS}` },
64
+ githost: node,
65
+ ontology: node,
66
+ mizan: node,
67
+ libraries: { nodeTests: NODE_TESTS, systems: ALL_OTHER },
68
+ headless: { nodeTests: NODE_TESTS, systems: ALL_OTHER },
69
+ kanon: node,
70
+ telemetry: node,
71
+ system: { nodeTests: NODE_TESTS, systems: ALL_OTHER },
72
+ formats: node,
73
+ crypto: node,
74
+ quality: node,
75
+ ergonex: { nodeTests: NODE_TESTS, systems: ALL_OTHER },
76
+ "integrations-github": node,
77
+ "integrations-fhir": node,
78
+ "integrations-x12": node,
79
+ integrations: node,
153
80
  };
154
- /** The workflow of a library of commons, made from its manifest (FR-006): its `verify` on Bun when its folder or what it imports changes, and its tests on Node where its record says so. */
155
- export function libraryWorkflow(l) {
156
- const folder = `commons/${l.name}`;
81
+ /** The cell of a library on a system (`ubuntu-latest`, where it names none), from its manifest and its record of CI; `pack` says whether the packing is checked in it. */
82
+ export function cellOf(l, os, pack = false) {
157
83
  const ci = LIBRARY_CI[l.name];
158
- const paths = l.paths;
159
- const systems = ci?.systems;
160
- const onSystems = systems === undefined
161
- ? { runsOn: "ubuntu-latest" }
162
- : { runsOn: expr("matrix.os"), strategy: { failFast: false, matrix: { os: systems } } };
163
- const verify = job({
164
- ...onSystems,
165
- timeoutMinutes: 15,
166
- steps: [
167
- checkout(),
168
- bun(),
169
- tools(folder, "The development tools, from bun.lock (the kernel is linked from commons/ts)"),
170
- run(l.verify, { name: "verify", workingDirectory: folder }),
171
- ...(ci?.afterVerify ?? []),
172
- ],
173
- });
174
- const node = ci?.nodeTests === undefined
175
- ? {}
176
- : {
177
- node: job({
178
- ...onSystems,
179
- timeoutMinutes: 15,
180
- steps: [
181
- checkout(),
182
- bun(),
183
- setupNode(),
184
- tools(folder),
185
- run(ci.nodeTests, { name: "The tests on Node 26", workingDirectory: folder }),
186
- ],
187
- }),
188
- };
189
84
  return {
190
- file: l.name,
191
85
  name: l.name,
192
- ...(ci === undefined ? {} : { comment: ci.comment }),
193
- on: { push: { paths }, pullRequest: { paths } },
194
- permissions: { contents: "read" },
195
- env: { NODE_VERSION },
196
- concurrency: supersedable,
197
- jobs: { verify, ...node },
86
+ folder: l.folder,
87
+ verify: l.verify,
88
+ pack,
89
+ node: ci?.nodeTests ?? "",
90
+ after: ci?.after ?? "",
91
+ ...(os === undefined ? {} : { os }),
198
92
  };
199
93
  }
94
+ /** The paths a push or a pull request is run for by `ci`: the libraries and what they share. What a change affects within them is the plan's to say (0001-libraries FR-012), not a filter's. */
95
+ const CI_PATHS = ["commons/**", "package.json", "bun.lock", BUN_ACTION, own("ci")];
96
+ /** The steps that prove one library of a cell: install its tools, `verify`, what comes after, and its tests on Node 26. */
97
+ const cellSteps = () => [
98
+ checkout(),
99
+ bun(),
100
+ tools(expr("matrix.folder"), "The development tools, from bun.lock (the kernel is linked from commons/ts)"),
101
+ run(expr("matrix.verify"), { name: "verify (its packing is checked where the exports changed, and by the release)", workingDirectory: expr("matrix.folder"), env: { IFC_SKIP_PACK: expr("matrix.pack == false && '1' || ''") } }),
102
+ run(expr("matrix.after"), { name: "After verify", when: "matrix.after != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
103
+ run(expr("matrix.node"), { name: "The tests on Node 26", when: "matrix.node != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
104
+ ];
105
+ /**
106
+ * The one workflow that proves the libraries (0001-libraries FR-012): a job `plan` asks `plan.ts` which libraries the push or the pull request affects (the code of the `affected` command, from the commit the
107
+ * change starts at), and a matrix of those libraries and nothing else runs `verify` and the tests on Node 26 on Linux. A library whose record says it has code of its own for Windows or macOS runs there too;
108
+ * the others are not run there. The job `ci` is the one result to require: it fails where a job it needs failed, and passes where nothing was affected. A push to main has a group of its own for each commit, so that no commit's
109
+ * run is replaced by a later one: each plan starts at the commit main was at, and a replaced run would leave what it was to prove unproved.
110
+ */
111
+ const ci = {
112
+ file: "ci",
113
+ name: "ci",
114
+ comment: lines("The libraries of commons (commons 0001-libraries FR-012, 0027-commons-libraries FR-019 to FR-022): one workflow for every library. The job `plan` reads what the push or pull request changed, from the commit it starts at,", "and the libraries that change affects (their folders, what they import and what depends on them); `verify` and the tests on Node 26 run for those libraries on Linux, and on Windows and macOS only for the libraries whose", "record of CI (`LIBRARY_CI`) names them, because they have code of their own for those systems. Nothing else is run. The job `ci` is the one result to require.").trimEnd(),
115
+ on: { push: { paths: CI_PATHS }, pullRequest: { paths: CI_PATHS }, workflowDispatch: true },
116
+ permissions: { contents: "read" },
117
+ env: { NODE_VERSION },
118
+ concurrency: {
119
+ group: `${expr("github.workflow")}-${expr("github.ref == 'refs/heads/main' && github.sha || github.ref")}`,
120
+ cancelInProgress: expr("github.ref != 'refs/heads/main'"),
121
+ },
122
+ jobs: {
123
+ plan: job({
124
+ runsOn: "ubuntu-latest",
125
+ timeoutMinutes: 10,
126
+ outputs: {
127
+ "has-linux": expr("steps.plan.outputs.has-linux"),
128
+ linux: expr("steps.plan.outputs.linux"),
129
+ "has-systems": expr("steps.plan.outputs.has-systems"),
130
+ systems: expr("steps.plan.outputs.systems"),
131
+ },
132
+ steps: [
133
+ checkout({ fetchDepth: 0, comment: "the whole history: the plan compares the head with the commit the change starts at" }),
134
+ bun(),
135
+ run("bun install --frozen-lockfile", { name: "The packages the plan reads, from the root's bun.lock" }),
136
+ run("bun commons/libraries/src/link.ts", { name: "The libraries, linked by name before any of them is imported (the root's packages are old copies from npm)" }),
137
+ run(lines("# a pull request starts at its base; a push to main at the commit main was at; any other branch at main, so a push that replaced a run that was stopped still carries what that run was to prove", 'if [ "$GITHUB_EVENT_NAME" = pull_request ]; then base="${{ github.event.pull_request.base.sha }}"', 'elif [ "$GITHUB_REF" = refs/heads/main ]; then base="${{ github.event.before }}"', "else base=origin/main; fi", 'case "$base" in ""|0000000000000000000000000000000000000000) base=origin/main ;; esac', 'if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then scope=--all; else scope="--base $base"; fi', 'bun commons/libraries/src/plan.ts $scope --github-output "$GITHUB_OUTPUT"'), { name: "The libraries this change affects, and the systems each runs on", id: "plan", shell: "bash" }),
138
+ ],
139
+ }),
140
+ verify: job({
141
+ name: "verify (${{ matrix.name }})",
142
+ needs: ["plan"],
143
+ when: "needs.plan.outputs.has-linux == 'true'",
144
+ runsOn: "ubuntu-latest",
145
+ timeoutMinutes: 20,
146
+ strategy: { failFast: false, matrix: expr("fromJSON(needs.plan.outputs.linux)") },
147
+ steps: cellSteps(),
148
+ }),
149
+ systems: job({
150
+ name: "verify (${{ matrix.name }}, ${{ matrix.os }})",
151
+ needs: ["plan"],
152
+ when: "needs.plan.outputs.has-systems == 'true'",
153
+ runsOn: expr("matrix.os"),
154
+ timeoutMinutes: 20,
155
+ strategy: { failFast: false, matrix: expr("fromJSON(needs.plan.outputs.systems)") },
156
+ steps: cellSteps(),
157
+ }),
158
+ ci: job({
159
+ comment: "The one result to require: every job it needs passed or had nothing to run.",
160
+ needs: ["plan", "verify", "systems"],
161
+ when: "always()",
162
+ runsOn: "ubuntu-latest",
163
+ timeoutMinutes: 5,
164
+ steps: [
165
+ run(lines('for r in "${{ needs.plan.result }}" "${{ needs.verify.result }}" "${{ needs.systems.result }}"; do', ' case "$r" in success|skipped) ;; *) echo "a job of ci ended $r"; exit 1 ;; esac', "done"), { name: "No job failed", shell: "bash" }),
166
+ ],
167
+ }),
168
+ },
169
+ };
200
170
  const ifcTypescriptPaths = [
201
171
  "commons/ts/**",
202
172
  "commons/docs/**",
@@ -429,7 +399,10 @@ const tests = {
429
399
  run(lines('python3 -m venv "$RUNNER_TEMP/venv"', '"$RUNNER_TEMP/venv/bin/pip" install -q rdflib==7.6.0 pyshacl==0.40.2 jsonschema==4.26.0 pyyaml==6.0.3', 'echo "$RUNNER_TEMP/venv/bin" >> "$GITHUB_PATH"'), {
430
400
  name: "Independent validators of the exports (rdflib, pySHACL, jsonschema), which the Mizan test uses where they are installed",
431
401
  }),
432
- run("bun test ./tests/", { name: "The tests on Bun", when: "matrix.runtime == 'bun'" }),
402
+ run("bun test ./tests/*.test.ts", {
403
+ name: "The tests on Bun (tests/release/ is the release's: it packs, installs and type-checks every library)",
404
+ when: "matrix.runtime == 'bun'",
405
+ }),
433
406
  run('node --test "tests/*.test.ts"', { name: "The tests on Node 26", when: "matrix.runtime == 'node'" }),
434
407
  ],
435
408
  }),
@@ -456,138 +429,93 @@ const tests = {
456
429
  }),
457
430
  },
458
431
  };
459
- /** Reads the name and version of the tarball in the working folder and says on the step's output whether that version is already on the registry (a re-run, or a first publish made by hand, never fails on a duplicate). */
460
- const HAVE = (registry) => lines(`pkg=$(tar -xzOf ./*.tgz package/package.json)`, `name=$(printf '%s' "$pkg" | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).name")`, `version=$(printf '%s' "$pkg" | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")`, `if npm view "$name@$version" version${registry} >/dev/null 2>&1; then`, ' echo "$name@$version is already there"', ' echo "have=true" >> "$GITHUB_OUTPUT"', "else", ' echo "have=false" >> "$GITHUB_OUTPUT"', "fi");
461
- const HAVE_NPM = HAVE("");
462
- const HAVE_GITHUB = HAVE(" --registry https://npm.pkg.github.com");
432
+ /** The folder of a library's package that the release workflow packs: the cell of the matrix, `matrix.folder`. */
433
+ const PUBLISH_COMMAND = "bun commons/libraries/src/releasing.ts publish --dir package";
463
434
  /**
464
- * The workflow that publishes a library to the registries its manifest names (0030-generated-workflows FR-009): on a tag `<name>-v<version>` it checks the tag is the version, proves the library, packs it
465
- * with its `tools/pack.ts` and sends the tarball to npm, with provenance and no token (npm's trusted publishing), and to the GitHub package registry with the workflow's own token.
435
+ * The one workflow that releases (0001-libraries FR-014, FR-015): run by hand from main, never by a push. It reads the release record that `release apply` wrote (`commons/generated/release.auto.json`: the libraries
436
+ * whose version is to be published and tagged, in dependency order), proves and packs each of them in a matrix, and, where the run is asked to publish, sends them in that order to npm (trusted publishing with provenance, or
437
+ * the token `INFRO_NPMJS_TOKEN` where the repository has one) and to the GitHub package registry, and makes the tag of each with the runner's token. A run that is not asked to publish stops after the packing.
466
438
  */
467
- export function publishWorkflow(l) {
468
- const folder = `commons/${l.name}`;
469
- const tarball = 'npm publish "$(ls ./*.tgz)"';
470
- const sendNpm = l.distribution.includes("npm");
471
- return {
472
- file: `${l.name}-publish`,
473
- name: `${l.name}-publish`,
474
- comment: lines(`Publishes ${l.name} (commons 0027-commons-libraries FR-015, FR-016): a tag \`${l.name}-v<version>\` (made by \`versions tag\`, commons 0026-works-versioning), or a run by hand from main, is checked against the package's version, the library is proved and packed by its own`, "tools/pack.ts, and the tarball goes to the registries its manifest names: npm with provenance and no token (trusted publishing, which the owner of the npm scope sets up once for this workflow's file), and", "the GitHub package registry with this workflow's own token.").trimEnd(),
475
- on: { push: { tags: [`${l.name}-v*`] }, workflowDispatch: true },
476
- permissions: { contents: "read" },
477
- jobs: {
478
- build: job({
479
- runsOn: "ubuntu-latest",
480
- timeoutMinutes: 15,
481
- steps: [
482
- checkout(),
483
- bun(),
484
- setupNode(),
485
- tools(folder),
486
- run(lines(`version=$(node -p "require('./package.json').version")`, `if [ "$GITHUB_REF_TYPE" = tag ]; then`, ` test "$GITHUB_REF_NAME" = "${l.name}-v$version" || { echo "the tag $GITHUB_REF_NAME is not ${l.name}-v$version"; exit 1; }`, `else`, ` test "$GITHUB_REF" = refs/heads/main || { echo "a run by hand publishes only from main, not $GITHUB_REF"; exit 1; }`, `fi`), {
487
- name: "The tag, or main for a run by hand, is the version of the package",
488
- workingDirectory: folder,
489
- shell: "bash",
490
- }),
491
- run("bun run verify", { name: "verify", workingDirectory: folder }),
492
- run("bun tools/pack.ts", { name: "The package that is published", workingDirectory: folder }),
493
- use(PIN.uploadArtifact, {
494
- name: "The tarball, kept for the jobs that publish it",
495
- with: { name: `${l.name}-package`, path: `${folder}/dist/*.tgz`, "if-no-files-found": "error" },
496
- }),
497
- ],
498
- }),
499
- ...(sendNpm
500
- ? {
501
- "publish-npm": job({
502
- needs: ["build"],
503
- runsOn: "ubuntu-latest",
504
- timeoutMinutes: 10,
505
- permissions: { contents: "read", "id-token": "write" },
506
- environment: { name: "npm" },
507
- steps: [
508
- use(PIN.downloadArtifact, { name: "The tarball", with: { name: `${l.name}-package`, path: "package" } }),
509
- use(PIN.setupNode, { with: { "node-version": expr("env.NODE_VERSION"), "registry-url": "https://registry.npmjs.org" } }),
510
- run(HAVE_NPM, {
511
- name: "Is the version already on npm (published by hand, or by an earlier run)?",
512
- id: "have",
513
- shell: "bash",
514
- workingDirectory: "package",
515
- }),
516
- run(tarball + " --access public --provenance", {
517
- name: "Published to npm, with provenance and no token",
518
- when: "steps.have.outputs.have != 'true'",
519
- workingDirectory: "package",
520
- shell: "bash",
521
- }),
522
- ],
523
- }),
524
- }
525
- : {}),
526
- "publish-github": job({
527
- needs: ["build"],
528
- runsOn: "ubuntu-latest",
529
- timeoutMinutes: 10,
530
- permissions: { contents: "read", packages: "write" },
531
- steps: [
532
- use(PIN.downloadArtifact, { name: "The tarball", with: { name: `${l.name}-package`, path: "package" } }),
533
- use(PIN.setupNode, {
534
- with: {
535
- "node-version": expr("env.NODE_VERSION"),
536
- "registry-url": "https://npm.pkg.github.com",
537
- scope: "@intellectual-frontiers",
538
- },
539
- }),
540
- run(HAVE_GITHUB, {
541
- name: "Is the version already on the GitHub package registry?",
542
- id: "have",
543
- shell: "bash",
544
- workingDirectory: "package",
545
- env: { NODE_AUTH_TOKEN: expr("secrets.GITHUB_TOKEN") },
546
- }),
547
- run(tarball, {
548
- name: "Published to the GitHub package registry",
549
- when: "steps.have.outputs.have != 'true'",
550
- workingDirectory: "package",
551
- shell: "bash",
552
- env: { NODE_AUTH_TOKEN: expr("secrets.GITHUB_TOKEN") },
553
- }),
554
- ],
555
- }),
556
- // a run by hand from main makes the tag that a push of one would have, where the runner's token may and a person's sandbox may not; it tags a version that is on its registry,
557
- // however it got there (this workflow's jobs, or a person's first publish of a package that has no trusted publisher yet), and never fails on a tag that is there
558
- tag: job({
559
- needs: ["build", ...(sendNpm ? ["publish-npm"] : []), "publish-github"],
560
- when: "always() && needs.build.result == 'success' && github.ref_type == 'branch'",
561
- runsOn: "ubuntu-latest",
562
- timeoutMinutes: 5,
563
- permissions: { contents: "write" },
564
- steps: [
565
- checkout(),
566
- use(PIN.setupNode, {
567
- with: {
568
- "node-version": expr("env.NODE_VERSION"),
569
- ...(sendNpm ? {} : { "registry-url": "https://npm.pkg.github.com", scope: "@intellectual-frontiers" }),
570
- },
571
- }),
572
- run(lines(`version=$(node -p "require('./package.json').version")`, `tag="${l.name}-v$version"`, sendNpm
573
- ? `npm view "@intellectual-frontiers/${l.name}@$version" version >/dev/null 2>&1 || { echo "$version is not on npm: no tag"; exit 1; }`
574
- : `npm view "@intellectual-frontiers/${l.name}@$version" version >/dev/null 2>&1 || { echo "$version is not on the GitHub package registry: no tag"; exit 1; }`, 'if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$tag" >/dev/null 2>&1; then', ' echo "$tag is already there"', "else", ' gh api "repos/$GITHUB_REPOSITORY/git/refs" -f "ref=refs/tags/$tag" -f "sha=$GITHUB_SHA"', "fi"), {
575
- name: "The tag of the version that is published, made once",
576
- shell: "bash",
577
- workingDirectory: folder,
578
- env: { GH_TOKEN: expr("secrets.GITHUB_TOKEN"), ...(sendNpm ? {} : { NODE_AUTH_TOKEN: expr("secrets.GITHUB_TOKEN") }) },
579
- }),
580
- ],
581
- }),
439
+ const release = {
440
+ file: "release",
441
+ name: "release",
442
+ comment: lines("The release of the libraries (commons 0001-libraries FR-014, FR-015): by hand, from main, after `bun run release apply` (commons/libraries/src/releasing.ts) has written the versions and the record `commons/generated/release.auto.json` and they are pushed.", "`plan` reads the record and leaves out what is tagged; `build` proves and packs each library (`verify`, `tools/pack.ts`); `publish`, where asked, sends the tarballs in dependency order to npm with provenance, by npm's trusted", "publishing (the owner sets a trusted publisher once for each package on npmjs.com: this repository, this workflow's file, the environment `npm`) or, where the repository has the secret INFRO_NPMJS_TOKEN, by that token,", "and to the GitHub package registry, and makes the tag of each. A version that is on a registry is skipped and a tag that is there is kept, so a run again continues where one stopped.").trimEnd(),
443
+ on: {
444
+ workflowDispatch: {
445
+ inputs: { publish: { description: "Publish and tag; without it the run only plans, proves and packs", type: "boolean", default: false } },
582
446
  },
583
- env: { NODE_VERSION },
584
- };
585
- }
447
+ },
448
+ permissions: { contents: "read" },
449
+ env: { NODE_VERSION },
450
+ concurrency: { group: "release", cancelInProgress: false },
451
+ jobs: {
452
+ plan: job({
453
+ runsOn: "ubuntu-latest",
454
+ timeoutMinutes: 10,
455
+ outputs: {
456
+ "has-build": expr("steps.plan.outputs.has-build"),
457
+ build: expr("steps.plan.outputs.build"),
458
+ sequence: expr("steps.plan.outputs.sequence"),
459
+ },
460
+ steps: [
461
+ checkout({ fetchDepth: 0, comment: "the whole history and its tags: the plan leaves out what is tagged" }),
462
+ bun(),
463
+ run("bun install --frozen-lockfile", { name: "The packages the plan reads, from the root's bun.lock" }),
464
+ run("bun commons/libraries/src/link.ts", { name: "The libraries, linked by name before any of them is imported (the root's packages are old copies from npm)" }),
465
+ run(lines('test "$GITHUB_REF" = refs/heads/main || { echo "a release is made from main, not $GITHUB_REF"; exit 1; }', 'bun commons/libraries/src/releasing.ts matrix --github-output "$GITHUB_OUTPUT"'), { name: "The libraries to release, in dependency order, from the record", id: "plan", shell: "bash" }),
466
+ ],
467
+ }),
468
+ build: job({
469
+ name: "build (${{ matrix.slug }} ${{ matrix.version }})",
470
+ needs: ["plan"],
471
+ when: "needs.plan.outputs.has-build == 'true'",
472
+ runsOn: "ubuntu-latest",
473
+ timeoutMinutes: 20,
474
+ strategy: { failFast: true, matrix: expr("fromJSON(needs.plan.outputs.build)") },
475
+ steps: [
476
+ checkout(),
477
+ bun(),
478
+ tools(expr("matrix.folder")),
479
+ run("bun run verify", { name: "verify, which includes the packing", workingDirectory: expr("matrix.folder") }),
480
+ run("bun tools/pack.ts", { name: "The package that is published", workingDirectory: expr("matrix.folder") }),
481
+ use(PIN.uploadArtifact, {
482
+ name: "The tarball, kept for the job that publishes it",
483
+ with: { name: "package-${{ matrix.slug }}", path: "${{ matrix.folder }}/dist/*.tgz", "if-no-files-found": "error" },
484
+ }),
485
+ ],
486
+ }),
487
+ publish: job({
488
+ needs: ["plan", "build"],
489
+ when: "inputs.publish && needs.plan.outputs.has-build == 'true'",
490
+ runsOn: "ubuntu-latest",
491
+ timeoutMinutes: 60,
492
+ permissions: { contents: "write", "id-token": "write", packages: "write" },
493
+ environment: { name: "npm" },
494
+ steps: [
495
+ checkout({ fetchDepth: 0, comment: "the tags: what is tagged is left out" }),
496
+ bun(),
497
+ run("bun install --frozen-lockfile", { name: "The packages the command reads, from the root's bun.lock" }),
498
+ run("bun commons/libraries/src/link.ts", { name: "The libraries, linked by name before any of them is imported" }),
499
+ use(PIN.setupNode, { with: { "node-version": expr("env.NODE_VERSION"), "registry-url": "https://registry.npmjs.org" } }),
500
+ use(PIN.downloadArtifact, { name: "The tarballs", with: { pattern: "package-*", path: "package" } }),
501
+ run(PUBLISH_COMMAND, {
502
+ name: "Published in dependency order to npm and to the GitHub package registry, and tagged: each release by itself, a version already on npm is only tagged",
503
+ shell: "bash",
504
+ env: {
505
+ NPM_TOKEN: expr("secrets.INFRO_NPMJS_TOKEN"),
506
+ GITHUB_TOKEN: expr("secrets.GITHUB_TOKEN"),
507
+ GH_TOKEN: expr("secrets.GITHUB_TOKEN"),
508
+ },
509
+ }),
510
+ ],
511
+ }),
512
+ },
513
+ };
586
514
  /** Every workflow, the libraries'' made from their manifests, in the order of their files' names. */
587
- export function workflows(libraries) {
515
+ export function workflows() {
588
516
  return [
589
- ...libraries.map(libraryWorkflow),
590
- ...libraries.filter((l) => l.distribution.includes("npm")).map(publishWorkflow),
517
+ ci,
518
+ release,
591
519
  docs,
592
520
  ifcTypescript,
593
521
  tests,
@@ -73,17 +73,27 @@ export type Filter = {
73
73
  readonly paths?: readonly string[];
74
74
  readonly tags?: readonly string[];
75
75
  };
76
+ /** A question a run by hand asks: a yes or no with its default. */
77
+ export type DispatchInput = {
78
+ readonly description: string;
79
+ readonly type: "boolean";
80
+ readonly default: boolean;
81
+ };
76
82
  export type Triggers = {
77
83
  readonly push?: Filter;
78
84
  readonly pullRequest?: Filter;
79
- /** Run by hand from the Actions page. */
80
- readonly workflowDispatch?: true;
85
+ /** Run by hand from the Actions page, with the inputs it asks for (true asks for none). */
86
+ readonly workflowDispatch?: true | {
87
+ readonly inputs: Readonly<Record<string, DispatchInput>>;
88
+ };
81
89
  /** Called by another workflow. */
82
90
  readonly workflowCall?: true;
83
91
  };
92
+ /** The cells of a matrix: the values of each axis, or an expression that gives the whole matrix (`expr("fromJSON(needs.plan.outputs.linux)")`), which a job reads from the output of another. */
93
+ export type Matrix = Readonly<Record<string, readonly (string | number)[]>> | Expr;
84
94
  export type Strategy = {
85
95
  readonly failFast?: boolean;
86
- readonly matrix: Readonly<Record<string, readonly (string | number)[]>>;
96
+ readonly matrix: Matrix;
87
97
  };
88
98
  export type Job = {
89
99
  readonly name?: string;
@@ -98,6 +108,8 @@ export type Job = {
98
108
  readonly url?: string;
99
109
  };
100
110
  readonly env?: Readonly<Record<string, Scalar>>;
111
+ /** What the job gives the jobs that need it, by name: an expression of its steps' outputs. */
112
+ readonly outputs?: Readonly<Record<string, Expr>>;
101
113
  readonly strategy?: Strategy;
102
114
  readonly steps: readonly [Step, ...Step[]];
103
115
  /** A comment written above the job. */
@@ -128,11 +128,13 @@ function jobLines(id, j) {
128
128
  out.push(...entry("url", j.environment.url, 6));
129
129
  }
130
130
  out.push(...mapping("env", j.env, 4));
131
+ out.push(...mapping("outputs", j.outputs, 4));
131
132
  if (j.strategy !== undefined) {
132
133
  out.push(" strategy:");
133
134
  if (j.strategy.failFast !== undefined)
134
135
  out.push(...entry("fail-fast", j.strategy.failFast, 6));
135
- out.push(" matrix:", ...Object.entries(j.strategy.matrix).flatMap(([k, v]) => flowList(k, v, 8)));
136
+ const m = j.strategy.matrix;
137
+ out.push(...(typeof m === "string" ? entry("matrix", m, 6) : [" matrix:", ...Object.entries(m).flatMap(([k, v]) => flowList(k, v, 8))]));
136
138
  }
137
139
  out.push(" steps:", ...j.steps.flatMap((s) => step(s, 6)));
138
140
  return out;
@@ -144,8 +146,14 @@ export function renderWorkflow(w) {
144
146
  out.push(...comment(w.comment, 0));
145
147
  out.push("on:");
146
148
  out.push(...filter("push", w.on.push, 2), ...filter("pull_request", w.on.pullRequest, 2));
147
- if (w.on.workflowDispatch === true)
149
+ const dispatch = w.on.workflowDispatch;
150
+ if (dispatch === true)
148
151
  out.push(" workflow_dispatch:");
152
+ else if (dispatch !== undefined) {
153
+ out.push(" workflow_dispatch:", " inputs:");
154
+ for (const [k, v] of Object.entries(dispatch.inputs))
155
+ out.push(` ${key(k)}:`, ...entry("description", v.description, 8), ...entry("type", v.type, 8), ...entry("default", v.default, 8));
156
+ }
149
157
  if (w.on.workflowCall === true)
150
158
  out.push(" workflow_call:");
151
159
  out.push("");