@intellectual-frontiers/libraries 0.4.1 → 0.5.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.
Files changed (49) hide show
  1. package/dist/affected.d.ts +1 -1
  2. package/dist/dev.js +1 -1
  3. package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  4. package/dist/imports/schema-org.auto.prov.ttl +22 -0
  5. package/dist/install-bun.js +1 -1
  6. package/dist/libraries.d.ts +34 -2
  7. package/dist/libraries.js +70 -9
  8. package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  9. package/dist/link.d.ts +1 -1
  10. package/dist/link.js +4 -4
  11. package/dist/metapackages.d.ts +62 -0
  12. package/dist/metapackages.js +190 -0
  13. package/dist/mod.d.ts +1 -1
  14. package/dist/mod.js +1 -1
  15. package/dist/pack-library.d.ts +7 -0
  16. package/dist/pack-library.js +31 -56
  17. package/dist/pack-metapackage.d.ts +22 -0
  18. package/dist/pack-metapackage.js +147 -0
  19. package/dist/pins.d.ts +1 -1
  20. package/dist/pins.js +1 -1
  21. package/dist/readme.d.ts +13 -1
  22. package/dist/readme.js +42 -4
  23. package/dist/releasing.d.ts +8 -1
  24. package/dist/releasing.js +44 -14
  25. package/dist/workflows/definitions.d.ts +2 -2
  26. package/dist/workflows/definitions.js +31 -113
  27. package/dist/workflows/model.d.ts +2 -0
  28. package/dist/workflows/render.js +2 -0
  29. package/dist/workflows/schema/github-workflow.schema.json +2290 -0
  30. package/package.json +28 -13
  31. package/src/affected.ts +1 -1
  32. package/src/dev.ts +1 -1
  33. package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  34. package/src/imports/schema-org.auto.prov.ttl +22 -0
  35. package/src/install-bun.ts +1 -1
  36. package/src/libraries.ts +88 -8
  37. package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  38. package/src/link.ts +4 -4
  39. package/src/metapackages.ts +206 -0
  40. package/src/mod.ts +1 -1
  41. package/src/pack-library.ts +37 -53
  42. package/src/pack-metapackage.ts +137 -0
  43. package/src/pins.ts +1 -1
  44. package/src/readme.ts +46 -4
  45. package/src/releasing.ts +47 -16
  46. package/src/workflows/definitions.ts +34 -131
  47. package/src/workflows/model.ts +2 -0
  48. package/src/workflows/render.ts +1 -0
  49. package/src/workflows/schema/github-workflow.schema.json +2290 -0
package/src/releasing.ts CHANGED
@@ -16,7 +16,7 @@
16
16
  *
17
17
  * @limits
18
18
  * The plan reads the tags of this repository, so a clone without its tags plans a first release of everything. It cannot know what a registry holds: the workflow asks it, and skips a version that is there. A work that is not a library
19
- * (`commons/ts`, `commons/docs`) is a Git dependency and is not released here.
19
+ * (`commons/docs`) is not released here.
20
20
  *
21
21
  * @example
22
22
  * ```ts
@@ -47,6 +47,8 @@ import { compareVersions, greaterImpact, type Impact, nextSemVer, parseVersion }
47
47
  import { scopeOf, workFolders } from "@intellectual-frontiers/mizan/versions/works";
48
48
  import { inputsOf } from "./affected.ts";
49
49
  import { exportsLine } from "./plan.ts";
50
+ import { decodeLibrarySource, LIBRARY_FILE, publishedPackage, type VersionConstant } from "./libraries.ts";
51
+ import { membersOf } from "./metapackages.ts";
50
52
  import { everyLibrary } from "./affected.ts";
51
53
 
52
54
  /** The record of the release, from the repository's root. */
@@ -56,6 +58,8 @@ export const RECORD_PATH = "commons/generated/release.auto.json";
56
58
  export type Facts = {
57
59
  readonly slug: Slug;
58
60
  readonly folder: string;
61
+ /** The package the library publishes: `@intellectual-frontiers/<slug>`, or the one its manifest names in `publishes` (commons 0036-distribution FR-009). */
62
+ readonly package: string;
59
63
  readonly version: string;
60
64
  /** The libraries (by slug) whose package its own sources import. */
61
65
  readonly imports: readonly Slug[];
@@ -90,6 +94,7 @@ export type Decision =
90
94
  export type Step = {
91
95
  readonly slug: Slug;
92
96
  readonly folder: string;
97
+ readonly package: string;
93
98
  readonly from: string;
94
99
  readonly to: string;
95
100
  readonly tag: string;
@@ -195,7 +200,7 @@ export function planRelease(facts: readonly Facts[], raise: ReadonlyMap<string,
195
200
  const d = decided.get(slug);
196
201
  if (f === undefined || d === undefined || d.kind === "unchanged") continue;
197
202
  const to = d.kind === "as-is" ? f.version : d.to;
198
- steps.push({ slug, folder: f.folder, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
203
+ steps.push({ slug, folder: f.folder, package: f.package, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
199
204
  }
200
205
  return ok({ steps, unchanged: facts.filter((f) => decided.get(f.slug)?.kind === "unchanged").map((f) => f.slug) });
201
206
  }
@@ -208,12 +213,12 @@ function compare(a: string, b: string): number | undefined {
208
213
 
209
214
  /** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
210
215
  export function recordText(plan: Plan): string {
211
- const releases = plan.steps.map((s) => ({ slug: s.slug, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
216
+ const releases = plan.steps.map((s) => ({ slug: s.slug, package: s.package, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
212
217
  return `${JSON.stringify({ generated: "bun commons/libraries/src/releasing.ts apply; do not edit (commons 0001-libraries FR-014)", releases }, null, 2)}\n`;
213
218
  }
214
219
 
215
220
  /** One entry of the record, as the workflow reads it. */
216
- export type Entry = { readonly slug: string; readonly version: string; readonly folder: string; readonly tag: string; readonly publish: boolean };
221
+ export type Entry = { readonly slug: string; readonly package: string; readonly version: string; readonly folder: string; readonly tag: string; readonly publish: boolean };
217
222
 
218
223
  /** The entries of a record's text, or why it is not one. */
219
224
  export function readRecord(text: string): Result<readonly Entry[], string> {
@@ -230,9 +235,10 @@ export function readRecord(text: string): Result<readonly Entry[], string> {
230
235
  if (typeof e !== "object" || e === null) return err(`${RECORD_PATH}: an entry is not an object`);
231
236
  const o = Object.fromEntries(Object.entries(e));
232
237
  const { slug, version, folder, tag, publish } = o;
233
- if (typeof slug !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
234
- return err(`${RECORD_PATH}: an entry lacks its slug, version, folder, tag or publish`);
235
- out.push({ slug, version, folder, tag, publish });
238
+ const pkg = o["package"];
239
+ if (typeof slug !== "string" || typeof pkg !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
240
+ return err(`${RECORD_PATH}: an entry lacks its slug, package, version, folder, tag or publish`);
241
+ out.push({ slug, package: pkg, version, folder, tag, publish });
236
242
  }
237
243
  return ok(out);
238
244
  }
@@ -269,9 +275,30 @@ export function writeVersion(repo: string, step: Step): Result<readonly string[]
269
275
  writeTextFileSync(at, changed);
270
276
  files.push(file);
271
277
  }
278
+ const manifest = decodeLibrarySource(readTextFileSync(join(repo, step.folder, LIBRARY_FILE)));
279
+ if (manifest.kind === "err") return err(`${step.folder}/${LIBRARY_FILE}: ${manifest.error}`);
280
+ for (const c of manifest.value.versionConstants ?? []) {
281
+ const done = writeConstant(repo, step, c);
282
+ if (done.kind === "err") return done;
283
+ files.push(done.value);
284
+ }
272
285
  return ok(files);
273
286
  }
274
287
 
288
+ /** Escapes the characters of a name that a regular expression reads as syntax. */
289
+ const quoted = (name: string): string => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
290
+
291
+ /** Writes the new version into a constant of the library's sources that holds it (`export const NAME = "1.2.3"`); the file's path from the root, or the problem where the file or the constant is not there. */
292
+ export function writeConstant(repo: string, step: Step, c: VersionConstant): Result<string, string> {
293
+ const path = `${step.folder}/${c.file}`;
294
+ const at = join(repo, path);
295
+ if (!existsSync(at)) return err(`${path} is missing: the manifest names it as holding the version in ${c.name}`);
296
+ const changed = set(readTextFileSync(at), new RegExp(`(\\b${quoted(c.name)}\\b[^=\\n]*=\\s*)"[^"]*"`), `$1"${step.to}"`);
297
+ if (changed === undefined) return err(`${path} does not say ${c.name} = "<version>"`);
298
+ writeTextFileSync(at, changed);
299
+ return ok(path);
300
+ }
301
+
275
302
  /** What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder `package/`), and the text of its `package.json`. */
276
303
  export type Tarball = { readonly hashes: ReadonlyMap<string, string>; readonly packageJson: string };
277
304
 
@@ -309,13 +336,13 @@ export function driftOf(published: Tarball, local: { readonly hash: (path: strin
309
336
  }
310
337
 
311
338
  /** Compares a library's version with what npm holds of it. */
312
- export type Registry = (slug: string, version: string, folder: string) => Promise<Drift>;
339
+ export type Registry = (pkg: string, version: string, folder: string) => Promise<Drift>;
313
340
 
314
341
  /** The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under `repo`; anything that goes wrong is `unknown`, never a guess. */
315
342
  export function realRegistry(repo: string): Registry {
316
- return async (slug, version, folder) => {
343
+ return async (name, version, folder) => {
317
344
  try {
318
- const meta = await fetch(`https://registry.npmjs.org/@intellectual-frontiers%2F${slug}/${version}`, { signal: AbortSignal.timeout(30_000) });
345
+ const meta = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2F")}/${version}`, { signal: AbortSignal.timeout(30_000) });
319
346
  if (meta.status === 404) return "absent";
320
347
  if (!meta.ok) return "unknown";
321
348
  const json: unknown = await meta.json();
@@ -348,7 +375,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
348
375
  const head = await resolveCommit(repo, "HEAD");
349
376
  if (head.kind === "err") return err(formatGitError(head.error));
350
377
  const folders = workFolders(tree.value.paths);
351
- const libs = everyLibrary(repo);
378
+ const libs = everyLibrary(repo).filter((l) => l.held === undefined);
352
379
  const slugs = new Map<string, Slug>();
353
380
  for (const l of libs) {
354
381
  const s = slugOf(l.name);
@@ -386,7 +413,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
386
413
  let drift: Drift = "unknown";
387
414
  let sinceVersion = { changed: false, impact: "patch" as Impact };
388
415
  if (ahead) {
389
- if (l.distribution.includes("npm")) drift = await registry(slug, l.version, l.folder);
416
+ if (l.distribution.includes("npm")) drift = await registry(publishedPackage(l), l.version, l.folder);
390
417
  const raisedAt = await run(["git", "-C", repo, "log", "-1", "--format=%H", '-G"version"', "--", `${l.folder}/package.json`]);
391
418
  const commit = raisedAt.code === 0 ? raisedAt.stdout.trim() : "";
392
419
  if (commit !== "") {
@@ -400,13 +427,16 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
400
427
  };
401
428
  }
402
429
  }
403
- const imports = inputsOf(repo, l.name).imports.flatMap((n) => {
430
+ // a metapackage has no code to import: it depends on each member of its set, which is what raises it where a member is raised (0036-distribution FR-008)
431
+ const members = l.bundle === undefined ? undefined : membersOf(l.bundle, libs);
432
+ const imports = (members?.kind === "ok" ? members.value.map((m) => m.library) : inputsOf(repo, l.name).imports).flatMap((n) => {
404
433
  const s = slugs.get(n);
405
434
  return s === undefined ? [] : [s];
406
435
  });
407
436
  out.push({
408
437
  slug,
409
438
  folder: l.folder,
439
+ package: publishedPackage(l),
410
440
  version: l.version,
411
441
  imports,
412
442
  last: last === undefined ? undefined : { version: last.version, tag: last.tag },
@@ -423,6 +453,7 @@ export async function factsOf(repo: string, registry: Registry = realRegistry(re
423
453
  /** The commands that make the generated files, in the order they are made: the section of the libraries first, the register last. Each is run once, by `apply`. */
424
454
  export const GENERATORS: readonly (readonly string[])[] = [
425
455
  ["commons/libraries/src/libraries.ts"],
456
+ ["commons/libraries/src/pack-metapackage.ts"],
426
457
  ["commons/tools/generate-packaging.ts"],
427
458
  ["commons/libraries/src/generate-ontology.ts"],
428
459
  ["commons/libraries/src/generate-workflows.ts"],
@@ -527,7 +558,7 @@ export async function publishAll(entries: readonly Entry[], tools: Tools): Promi
527
558
  let npm: Outcome["npm"] = "not-published";
528
559
  let registry: Outcome["registry"] = "not-published";
529
560
  if (e.publish) {
530
- if (await tools.onNpm(`@intellectual-frontiers/${e.slug}`, e.version)) npm = "present";
561
+ if (await tools.onNpm(e.package, e.version)) npm = "present";
531
562
  else {
532
563
  const sent = await tools.npm(e);
533
564
  npm = sent.kind === "ok" ? "published" : "failed";
@@ -589,11 +620,11 @@ export function realTools(dir: string): Tools {
589
620
  });
590
621
  return r.code === 0
591
622
  ? ok(undefined)
592
- : err(`${e.slug} ${e.version} is not on npm and could not be published (${token === "" ? "no INFRO_NPMJS_TOKEN, so trusted publishing was tried" : "with INFRO_NPMJS_TOKEN"}; configure a trusted publisher for @intellectual-frontiers/${e.slug} or publish it by hand): ${tail(`${r.stderr}${r.stdout}`)}`);
623
+ : err(`${e.slug} ${e.version} is not on npm and could not be published (${token === "" ? "no INFRO_NPMJS_TOKEN, so trusted publishing was tried" : "with INFRO_NPMJS_TOKEN"}; configure a trusted publisher for ${e.package} or publish it by hand): ${tail(`${r.stderr}${r.stdout}`)}`);
593
624
  },
594
625
  github: async (e) => {
595
626
  const auth = [`--registry=https://npm.pkg.github.com`, `--//npm.pkg.github.com/:_authToken=${github}`];
596
- if (await view(`@intellectual-frontiers/${e.slug}`, e.version, auth)) return ok(undefined);
627
+ if (await view(e.package, e.version, auth)) return ok(undefined);
597
628
  const f = tarball(e.slug);
598
629
  if (f === undefined) return err(`${e.slug}: no tarball was built for it`);
599
630
  const r = await run(["npm", "publish", join(dir, `package-${e.slug}`, f), ...auth]);
@@ -27,9 +27,9 @@ export const PIN = {
27
27
  bun: "./.github/actions/bun",
28
28
  } as const;
29
29
 
30
- /** The Node that is the backup runtime (commons 0005-typescript-runtime). */
30
+ /** The Node that is the backup runtime (commons 0005-typescript-practice FR-018). */
31
31
  export const NODE_VERSION = "26.13.1";
32
- /** The canary of Bun that runs the linter until a release does (FR-028 of 0005-typescript-runtime). */
32
+ /** The canary of Bun that runs the linter until a release does (commons 0005-typescript-practice FR-028). */
33
33
  export const BUN_LINT_VERSION = "1.4.4-canary.20261115.1";
34
34
 
35
35
  const checkout = (o: { readonly fetchDepth?: number; readonly comment?: string } = {}): Step =>
@@ -39,8 +39,6 @@ const checkout = (o: { readonly fetchDepth?: number; readonly comment?: string }
39
39
  });
40
40
  const bun = (o: { readonly nodeVersion?: string } = {}): Step =>
41
41
  use(PIN.bun, o.nodeVersion === undefined ? {} : { with: { "node-version": o.nodeVersion } });
42
- const setupNode = (when?: string): Step =>
43
- use(PIN.setupNode, { ...(when === undefined ? {} : { when }), with: { "node-version": expr("env.NODE_VERSION") } });
44
42
  const tools = (workingDirectory: string, name = "The development tools, from bun.lock"): Step =>
45
43
  run("bun install --frozen-lockfile", { name, workingDirectory });
46
44
 
@@ -140,7 +138,7 @@ const CI_PATHS = ["commons/**", "package.json", "bun.lock", BUN_ACTION, own("ci"
140
138
  const cellSteps = (): readonly [Step, ...Step[]] => [
141
139
  checkout(),
142
140
  bun(),
143
- tools(expr("matrix.folder"), "The development tools, from bun.lock (the kernel is linked from commons/ts)"),
141
+ tools(expr("matrix.folder"), "The development tools, from bun.lock (the libraries it imports are linked)"),
144
142
  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' || ''") } }),
145
143
  run(expr("matrix.after"), { name: "After verify", when: "matrix.after != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
146
144
  run(expr("matrix.node"), { name: "The tests on Node 26", when: "matrix.node != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
@@ -160,7 +158,7 @@ const ci: Workflow = {
160
158
  "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",
161
159
  "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.",
162
160
  ).trimEnd(),
163
- on: { push: { paths: CI_PATHS }, pullRequest: { paths: CI_PATHS }, workflowDispatch: true },
161
+ on: { push: { paths: CI_PATHS }, pullRequest: { paths: CI_PATHS }, workflowDispatch: true, schedule: ["17 3 * * *"] },
164
162
  permissions: { contents: "read" },
165
163
  env: { NODE_VERSION },
166
164
  concurrency: {
@@ -189,8 +187,10 @@ const ci: Workflow = {
189
187
  'elif [ "$GITHUB_REF" = refs/heads/main ]; then base="${{ github.event.before }}"',
190
188
  "else base=origin/main; fi",
191
189
  'case "$base" in ""|0000000000000000000000000000000000000000) base=origin/main ;; esac',
192
- 'if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then scope=--all; else scope="--base $base"; fi',
190
+ 'if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] || [ "$GITHUB_EVENT_NAME" = schedule ]; then scope=--all; else scope="--base $base"; fi',
193
191
  'bun commons/libraries/src/plan.ts $scope --github-output "$GITHUB_OUTPUT"',
192
+ "# the proof plan of the same change (commons repoctl 0008-repoctl-prove), written to the summary of the run: what a person would run, and why each skipped proof is safe; it gates nothing, the matrices above do",
193
+ "{ echo '### Proof plan'; echo '```'; bun commons/repoctl/src/repoctl.ts prove --tier 6 --why $scope 2>&1 || true; echo '```'; } >> \"$GITHUB_STEP_SUMMARY\"",
194
194
  ),
195
195
  { name: "The libraries this change affects, and the systems each runs on", id: "plan", shell: "bash" },
196
196
  ),
@@ -234,87 +234,20 @@ const ci: Workflow = {
234
234
  },
235
235
  };
236
236
 
237
- const ifcTypescriptPaths = [
238
- "commons/ts/**",
239
- "commons/docs/**",
240
- "commons/generated/pins.auto.env",
241
- "package.json",
242
- "bun.lock",
243
- BUN_ACTION,
244
- own("ifc-typescript"),
245
- ];
237
+ const conformancePaths = ["commons/telemetry/**", "commons/system/**", "commons/generated/pins.auto.env", BUN_ACTION, own("conformance")];
246
238
 
247
- const ifcTypescript: Workflow = {
248
- file: "ifc-typescript",
249
- name: "ifc-typescript",
239
+ const conformance: Workflow = {
240
+ file: "conformance",
241
+ name: "conformance",
250
242
  comment: lines(
251
- "IFC TypeScript (commons 0005-typescript-runtime FR-017, FR-018, FR-026 to FR-030, FR-070). TypeScript 7 checks; Bun, pinned in commons' pins, installs, formats",
252
- "and lints; the same tests run unchanged on Bun, the default runtime, and Node 26, the backup, on Linux, macOS and Windows; and the commit is installed as a Git dependency of an empty project,",
253
- "as a consumer installs it, and used there on Bun and Node 26 (through the hook), IFC Docs too (0011-documentation FR-021, FR-022). Nothing is released.",
243
+ "What a library's own tests cannot run alone: the OTLP of the telemetry library sent to the pinned OpenTelemetry Collector and read back from its file exporter (telemetry 0001-telemetry FR-020),",
244
+ "and a program built into one binary by the pinned Bun on each system, then run, and Windows built from Linux (system 0001-system FR-013). Nothing is released.",
254
245
  ).trimEnd(),
255
- on: { push: { paths: ifcTypescriptPaths }, pullRequest: { paths: ifcTypescriptPaths } },
246
+ on: { push: { paths: conformancePaths }, pullRequest: { paths: conformancePaths } },
256
247
  permissions: { contents: "read" },
257
- env: { NODE_VERSION, BUN_LINT_VERSION },
248
+ env: { NODE_VERSION },
258
249
  concurrency: supersedable,
259
250
  jobs: {
260
- check: job({
261
- runsOn: "ubuntu-latest",
262
- timeoutMinutes: 10,
263
- steps: [
264
- checkout(),
265
- bun(),
266
- tools("commons/ts"),
267
- run("bun x tsc --version && bun run check", {
268
- name: "TypeScript 7 on everything, then the kernel with no host types",
269
- workingDirectory: "commons/ts",
270
- }),
271
- run("bun fmt --check", { name: "The formatter", workingDirectory: "commons/ts" }),
272
- run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 kernel runtime tests tools', {
273
- name: "The linter, type-aware, no warning allowed",
274
- workingDirectory: "commons/ts",
275
- }),
276
- ],
277
- }),
278
- test: job({
279
- runsOn: expr("matrix.os"),
280
- timeoutMinutes: 15,
281
- strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"], runtime: ["bun", "node"] } },
282
- steps: [
283
- checkout(),
284
- bun(),
285
- tools("commons/ts"),
286
- setupNode("matrix.runtime == 'node'"),
287
- run('bun x "bun@$BUN_LINT_VERSION" --version', {
288
- name: "The linter's canary, so the lint plugin's tests run rather than skip",
289
- shell: "bash",
290
- }),
291
- run(
292
- lines(
293
- `grep -E '^000[5-8]-' ../spec-kit/enforcement.tsv >"$RUNNER_TEMP/requirements.tsv"`,
294
- "bun ../quality/src/test-cli.ts run --runtime ${{ matrix.runtime }} --out test-results \\",
295
- " --report tap,junit,ctrf,sarif,md,html,oscal \\",
296
- ' --requirements "$RUNNER_TEMP/requirements.tsv" --reviewed ci-reviewed.tsv \\',
297
- " --ledger test-results/ledger.jsonl tests",
298
- ),
299
- {
300
- name: "The suite on ${{ matrix.runtime }}, recorded as evidence (commons 0008-test-evidence FR-014)",
301
- comment: "A hang ends here, so the record of what ran is still kept below.",
302
- timeoutMinutes: 10,
303
- workingDirectory: "commons/ts",
304
- shell: "bash",
305
- },
306
- ),
307
- use(PIN.uploadArtifact, {
308
- name: "The record, its reports and the ledger, kept with the run",
309
- when: "always()",
310
- with: {
311
- name: "test-evidence-${{ matrix.os }}-${{ matrix.runtime }}",
312
- path: "commons/ts/test-results/",
313
- "if-no-files-found": "error",
314
- },
315
- }),
316
- ],
317
- }),
318
251
  "otel-conformance": job({
319
252
  comment:
320
253
  "commons 0006-signals FR-020: the suite's OTLP sent to the pinned OpenTelemetry Collector, read back from its file exporter.",
@@ -345,7 +278,7 @@ const ifcTypescript: Workflow = {
345
278
  }),
346
279
  compile: job({
347
280
  comment:
348
- "commons 0005-typescript-runtime FR-062: a program built into one binary by the pinned Bun on each system, then run; and Windows built from Linux.",
281
+ "commons system 0001-system FR-013: a program built into one binary by the pinned Bun on each system, then run; and Windows built from Linux.",
349
282
  runsOn: expr("matrix.os"),
350
283
  timeoutMinutes: 10,
351
284
  strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"] } },
@@ -380,47 +313,15 @@ const ifcTypescript: Workflow = {
380
313
  ),
381
314
  ],
382
315
  }),
383
- "git-dependency": job({
384
- comment: lines(
385
- "commons 0005-typescript-runtime FR-030 and 0011-documentation FR-022: the commit checked, installed into an empty project by a",
386
- "git+file: URL of this checkout, as a consumer installs it by github:intellectual-frontiers/.github#<commit>, and used there.",
387
- ).trimEnd(),
388
- runsOn: expr("matrix.os"),
389
- timeoutMinutes: 15,
390
- strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"] } },
391
- steps: [
392
- checkout({
393
- fetchDepth: 0,
394
- comment: "Bun clones the checkout as a Git repository; a whole one, so that nothing depends on how a shallow clone is cloned.",
395
- }),
396
- bun({ nodeVersion: expr("env.NODE_VERSION") }),
397
- run("bun install --frozen-lockfile", {
398
- name: "The root package's lockfile, which the consumer does not read but this repository keeps",
399
- }),
400
- run(
401
- lines("bun install --frozen-lockfile", "node --version", 'bun tools/smoke.ts --repo "$GITHUB_WORKSPACE" --commit "$GITHUB_SHA"'),
402
- {
403
- name: "IFC TypeScript as a Git dependency, on Bun and Node 26, with ifc test and tsc 7",
404
- workingDirectory: "commons/ts",
405
- shell: "bash",
406
- },
407
- ),
408
- run(lines("bun install --frozen-lockfile", 'bun tools/smoke.ts --repo "$GITHUB_WORKSPACE" --commit "$GITHUB_SHA"'), {
409
- name: "IFC Docs as a Git dependency, ifc-docs check and build on a fixture repository on Bun and Node 26",
410
- workingDirectory: "commons/docs",
411
- shell: "bash",
412
- }),
413
- ],
414
- }),
415
316
  },
416
317
  };
417
318
 
418
- const docsPaths = ["commons/**", "package.json", own("docs"), BUN_ACTION];
319
+ const docsPaths = ["commons/**", "package.json", own("site"), BUN_ACTION];
419
320
  const onMainPush = "github.event_name != 'pull_request' && github.ref == 'refs/heads/main'";
420
321
 
421
- const docs: Workflow = {
422
- file: "docs",
423
- name: "docs",
322
+ const site: Workflow = {
323
+ file: "site",
324
+ name: "site",
424
325
  comment: lines(
425
326
  "The documentation site of commons (commons 0011-documentation FR-020): made by commons/docs, from commons' TypeScript and spec kit alone,",
426
327
  "as commons' configuration (commons/docs.config.ts) says. Every pull request and push that touches commons tests the generator and checks",
@@ -429,7 +330,7 @@ const docs: Workflow = {
429
330
  ).trimEnd(),
430
331
  on: { push: { paths: docsPaths }, pullRequest: { paths: docsPaths }, workflowDispatch: true },
431
332
  permissions: { contents: "read" },
432
- concurrency: { group: "docs-${{ github.ref }}", cancelInProgress: true },
333
+ concurrency: { group: "site-${{ github.ref }}", cancelInProgress: true },
433
334
  jobs: {
434
335
  check: job({
435
336
  runsOn: "ubuntu-24.04",
@@ -439,10 +340,10 @@ const docs: Workflow = {
439
340
  bun(),
440
341
  tools(
441
342
  "commons/docs",
442
- "TypeScript 7.1 (beta), Mermaid and @types/node, exactly as bun.lock pins them (IFC TypeScript is ../ts, by relative path)",
343
+ "TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them",
443
344
  ),
444
345
  run("bun run verify", { name: "The compiler, the generator's tests, then check on commons", workingDirectory: "commons/docs" }),
445
- run('bun main.ts build --out "$GITHUB_WORKSPACE/_site"', {
346
+ run('bun src/main.ts build --out "$GITHUB_WORKSPACE/_site"', {
446
347
  name: "The site, built",
447
348
  when: onMainPush,
448
349
  workingDirectory: "commons/docs",
@@ -505,12 +406,14 @@ const tests: Workflow = {
505
406
  "the whole history and its tags: `versions check` compares each work with the merge base, and its ledger reads the tags (commons 0026-works-versioning FR-022, FR-035)",
506
407
  }),
507
408
  bun(),
508
- tools("commons/ts"),
509
- run("bun run check", { name: "TypeScript 7 on commons' tools and on these tests", workingDirectory: "commons/ts" }),
510
- run("bun fmt --check . ../tools ../../tests", { name: "The formatter", workingDirectory: "commons/ts" }),
511
- run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 ../tools ../../tests', {
409
+ tools(".", "The root's development tools, from bun.lock"),
410
+ tools("commons/docs", "The documentation generator's dependencies, which the tests of the root import"),
411
+ run("bun commons/libraries/src/link.ts && bun x tsc -p tests/tsconfig.json && bun x tsc -p commons/tools/tsconfig.json", {
412
+ name: "TypeScript 7 on the tests of the root and on commons' tools",
413
+ }),
414
+ run("bun fmt --check commons/tools tests", { name: "The formatter" }),
415
+ run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 commons/tools tests', {
512
416
  name: "The linter, type-aware, no warning allowed",
513
- workingDirectory: "commons/ts",
514
417
  }),
515
418
  run(lines(...checkScripts(false)), {
516
419
  name: "Commons' generated files and specifications, as a person checks them, on Bun and on Node 26",
@@ -524,7 +427,7 @@ const tests: Workflow = {
524
427
  steps: [
525
428
  checkout(),
526
429
  bun(),
527
- tools("commons/ts"),
430
+ tools(".", "The root's development tools, from bun.lock"),
528
431
  run("sudo apt-get update -qq && sudo apt-get install -y -qq shellcheck", {
529
432
  name: "ShellCheck, which the packaging test uses where it is installed",
530
433
  when: "runner.os == 'Linux'",
@@ -692,8 +595,8 @@ export function workflows(): readonly Workflow[] {
692
595
  return [
693
596
  ci,
694
597
  release,
695
- docs,
696
- ifcTypescript,
598
+ site,
599
+ conformance,
697
600
  tests,
698
601
  ].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
699
602
  }
@@ -704,7 +607,7 @@ export const ACTIONS: readonly CompositeAction[] = [
704
607
  folder: "bun",
705
608
  name: "Pinned Bun",
706
609
  description:
707
- "Bun at the version commons pins (commons/generated/pins.auto.env, commons 0005-typescript-runtime FR-026), fetched with retries, kept only where its SHA-256 is the pinned one, unpacked by IFC TypeScript's own zip reader (commons/libraries/src/install-bun.ts, run by Node) and put on the PATH. Linux, macOS and Windows; no shell script, no Python, no unzip.",
610
+ "Bun at the version commons pins (commons/generated/pins.auto.env, commons 0005-typescript-practice FR-026), fetched with retries, kept only where its SHA-256 is the pinned one, unpacked by IFC TypeScript's own zip reader (commons/libraries/src/install-bun.ts, run by Node) and put on the PATH. Linux, macOS and Windows; no shell script, no Python, no unzip.",
708
611
  inputs: { "node-version": { description: "The Node that runs the installer.", default: NODE_VERSION } },
709
612
  steps: [
710
613
  use(PIN.setupNode, { with: { "node-version": expr("inputs.node-version") } }),
@@ -94,6 +94,8 @@ export type Triggers = {
94
94
  readonly pullRequest?: Filter;
95
95
  /** Run by hand from the Actions page, with the inputs it asks for (true asks for none). */
96
96
  readonly workflowDispatch?: true | { readonly inputs: Readonly<Record<string, DispatchInput>> };
97
+ /** Run on a schedule: each entry is a cron expression of five fields, in UTC. */
98
+ readonly schedule?: readonly string[];
97
99
  /** Called by another workflow. */
98
100
  readonly workflowCall?: true;
99
101
  };
@@ -150,6 +150,7 @@ export function renderWorkflow(w: Workflow): string {
150
150
  for (const [k, v] of Object.entries(dispatch.inputs))
151
151
  out.push(` ${key(k)}:`, ...entry("description", v.description, 8), ...entry("type", v.type, 8), ...entry("default", v.default, 8));
152
152
  }
153
+ if (w.on.schedule !== undefined && w.on.schedule.length > 0) out.push(" schedule:", ...w.on.schedule.map((c) => ` - cron: ${scalar(c)}`));
153
154
  if (w.on.workflowCall === true) out.push(" workflow_call:");
154
155
  out.push("");
155
156
  if (w.permissions !== undefined) out.push(...permissions(w.permissions, 0), "");