@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/dist/readme.js CHANGED
@@ -30,8 +30,9 @@ import { absurd, err, ok, refine, string } from "@intellectual-frontiers/core";
30
30
  import { stdio } from "@intellectual-frontiers/system";
31
31
  import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
32
32
  import { readLibraries } from "./libraries.js";
33
- /** The marker that opens the generated table, and the one that closes it. */
33
+ /** The marker that opens the generated table. */
34
34
  export const BEGIN = "<!-- libraries-map:begin -->";
35
+ /** The marker that closes the generated table. */
35
36
  export const END = "<!-- libraries-map:end -->";
36
37
  /** What a library is for in the whole: a closed union. */
37
38
  export const ROLES = ["foundation", "pattern", "program", "standard"];
@@ -65,12 +66,22 @@ export const ROLE_OF = new Map([
65
66
  ["kanon", "pattern"],
66
67
  ["archon", "program"],
67
68
  ["toolchain", "program"],
69
+ ["archon-dialect-native-pinned", "program"],
70
+ ["package-managers", "program"],
71
+ ["archon-dialect-apt", "program"],
72
+ ["archon-dialect-homebrew", "program"],
73
+ ["archon-dialect-mise", "program"],
74
+ ["archon-dialect-winget", "program"],
75
+ ["archon-tool", "program"],
76
+ ["estate", "program"],
68
77
  ["data", "program"],
78
+ ["docs", "program"],
69
79
  ["ergonex", "program"],
70
80
  ["grc", "program"],
71
81
  ["integrations", "program"],
72
82
  ["integrations-github", "program"],
73
83
  ["libraries", "program"],
84
+ ["repoctl", "program"],
74
85
  ["integrations-fhir", "standard"],
75
86
  ["integrations-x12", "standard"],
76
87
  ["mizan", "standard"],
@@ -189,7 +200,8 @@ export function rowOf(l, summary) {
189
200
  shape: shapeOf(l),
190
201
  level: l.level,
191
202
  distribution: l.distribution,
192
- published: l.distribution.includes("npm"),
203
+ published: l.held === undefined && l.distribution.includes("npm"),
204
+ held: l.held,
193
205
  });
194
206
  }
195
207
  const REGISTRY_TITLE = { github: "GitHub", npm: "npm" };
@@ -200,7 +212,7 @@ export function tableOf(rows) {
200
212
  const body = sorted.map((r) => {
201
213
  const pkg = `@intellectual-frontiers/${r.name}`;
202
214
  const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
203
- return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ")} |`;
215
+ return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.held === undefined ? r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ") : "held"} |`;
204
216
  });
205
217
  return [...head, ...body].join("\n");
206
218
  }
@@ -214,6 +226,8 @@ export function rowsOf(repo) {
214
226
  problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
215
227
  continue;
216
228
  }
229
+ if (f.library.bundle !== undefined)
230
+ continue; // a metapackage has no about.ts and is listed by {@link bundlesOf}
217
231
  const file = `${root}/commons/${f.dir}/about.ts`;
218
232
  if (!existsSync(file)) {
219
233
  problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
@@ -232,6 +246,29 @@ export function rowsOf(repo) {
232
246
  }
233
247
  return { rows, problems };
234
248
  }
249
+ /** The rows of the metapackages of a repository, in the order of their folders' names: each the package and the first clause of the summary its manifest gives. */
250
+ export function bundlesOf(repo) {
251
+ const rows = [];
252
+ for (const f of readLibraries(repo.replace(/[\\/]$/, ""))) {
253
+ if ("problem" in f || f.library.bundle === undefined)
254
+ continue;
255
+ rows.push({ name: f.library.name, purpose: firstClause(f.library.summary ?? "").replace(/\|/g, "\\|") });
256
+ }
257
+ return rows;
258
+ }
259
+ /** The table of the metapackages, as Markdown, with the sentence that introduces it; nothing where a repository has none. */
260
+ export function bundlesTableOf(rows) {
261
+ if (rows.length === 0)
262
+ return "";
263
+ const body = rows.map((r) => `| [\`@intellectual-frontiers/${r.name}\`](https://www.npmjs.com/package/@intellectual-frontiers/${r.name}) | ${r.purpose} |`);
264
+ return [
265
+ "Metapackages: no code of their own, each depends on a set of the libraries above at exact versions (commons 0036-distribution). Install one of them, or a library.",
266
+ "",
267
+ "| Metapackage | What it holds |",
268
+ "| --- | --- |",
269
+ ...body,
270
+ ].join("\n");
271
+ }
235
272
  /** The README made again from its text and the table: the text between the markers (on lines of their own) replaced; an error where the markers are missing. */
236
273
  export function withTable(readme, table) {
237
274
  const from = readme.indexOf(`\n${BEGIN}\n`);
@@ -248,7 +285,8 @@ export function synchronize(repo, write) {
248
285
  if (!existsSync(file))
249
286
  return { stale: false, problems: [...problems, "README.md is missing"] };
250
287
  const text = readTextFileSync(file).replace(/\r\n/g, "\n");
251
- const made = withTable(text, tableOf(rows));
288
+ const bundles = bundlesTableOf(bundlesOf(root));
289
+ const made = withTable(text, bundles === "" ? tableOf(rows) : `${tableOf(rows)}\n\n${bundles}`);
252
290
  if (made.kind === "err")
253
291
  return { stale: false, problems: [...problems, made.error] };
254
292
  const stale = made.value !== text;
@@ -2,12 +2,15 @@ import { type Result } from "@intellectual-frontiers/core";
2
2
  import { type Look } from "@intellectual-frontiers/system/tty";
3
3
  import { type Slug } from "@intellectual-frontiers/mizan/versions/record";
4
4
  import { type Impact } from "@intellectual-frontiers/mizan/versions/scheme";
5
+ import { type VersionConstant } from "./libraries.js";
5
6
  /** The record of the release, from the repository's root. */
6
7
  export declare const RECORD_PATH = "commons/generated/release.auto.json";
7
8
  /** What the plan knows of a library: its version, what it imports, the last tag of it, whether its files changed since, and the impact the commits since state. */
8
9
  export type Facts = {
9
10
  readonly slug: Slug;
10
11
  readonly folder: string;
12
+ /** The package the library publishes: `@intellectual-frontiers/<slug>`, or the one its manifest names in `publishes` (commons 0036-distribution FR-009). */
13
+ readonly package: string;
11
14
  readonly version: string;
12
15
  /** The libraries (by slug) whose package its own sources import. */
13
16
  readonly imports: readonly Slug[];
@@ -55,6 +58,7 @@ export type Decision = {
55
58
  export type Step = {
56
59
  readonly slug: Slug;
57
60
  readonly folder: string;
61
+ readonly package: string;
58
62
  readonly from: string;
59
63
  readonly to: string;
60
64
  readonly tag: string;
@@ -80,6 +84,7 @@ export declare function recordText(plan: Plan): string;
80
84
  /** One entry of the record, as the workflow reads it. */
81
85
  export type Entry = {
82
86
  readonly slug: string;
87
+ readonly package: string;
83
88
  readonly version: string;
84
89
  readonly folder: string;
85
90
  readonly tag: string;
@@ -91,6 +96,8 @@ export declare function readRecord(text: string): Result<readonly Entry[], strin
91
96
  export declare function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string;
92
97
  /** Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not. */
93
98
  export declare function writeVersion(repo: string, step: Step): Result<readonly string[], string>;
99
+ /** 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. */
100
+ export declare function writeConstant(repo: string, step: Step, c: VersionConstant): Result<string, string>;
94
101
  /** 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`. */
95
102
  export type Tarball = {
96
103
  readonly hashes: ReadonlyMap<string, string>;
@@ -107,7 +114,7 @@ export declare function driftOf(published: Tarball, local: {
107
114
  readonly packageJson: string;
108
115
  }): "same" | "differs";
109
116
  /** Compares a library's version with what npm holds of it. */
110
- export type Registry = (slug: string, version: string, folder: string) => Promise<Drift>;
117
+ export type Registry = (pkg: string, version: string, folder: string) => Promise<Drift>;
111
118
  /** 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. */
112
119
  export declare function realRegistry(repo: string): Registry;
113
120
  /** What the host gives the plan: the facts of the libraries from the tags and the tree. */
package/dist/releasing.js 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, nextSemVer, parseVersion } from "@intel
47
47
  import { scopeOf, workFolders } from "@intellectual-frontiers/mizan/versions/works";
48
48
  import { inputsOf } from "./affected.js";
49
49
  import { exportsLine } from "./plan.js";
50
+ import { decodeLibrarySource, LIBRARY_FILE, publishedPackage } from "./libraries.js";
51
+ import { membersOf } from "./metapackages.js";
50
52
  import { everyLibrary } from "./affected.js";
51
53
  /** The record of the release, from the repository's root. */
52
54
  export const RECORD_PATH = "commons/generated/release.auto.json";
@@ -155,7 +157,7 @@ export function planRelease(facts, raise = new Map()) {
155
157
  if (f === undefined || d === undefined || d.kind === "unchanged")
156
158
  continue;
157
159
  const to = d.kind === "as-is" ? f.version : d.to;
158
- steps.push({ slug, folder: f.folder, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
160
+ steps.push({ slug, folder: f.folder, package: f.package, from: f.version, to, tag: tagOf(slug, to), publish: f.publish, decision: d });
159
161
  }
160
162
  return ok({ steps, unchanged: facts.filter((f) => decided.get(f.slug)?.kind === "unchanged").map((f) => f.slug) });
161
163
  }
@@ -166,7 +168,7 @@ function compare(a, b) {
166
168
  }
167
169
  /** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
168
170
  export function recordText(plan) {
169
- const releases = plan.steps.map((s) => ({ slug: s.slug, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
171
+ const releases = plan.steps.map((s) => ({ slug: s.slug, package: s.package, version: s.to, folder: s.folder, tag: s.tag, publish: s.publish }));
170
172
  return `${JSON.stringify({ generated: "bun commons/libraries/src/releasing.ts apply; do not edit (commons 0001-libraries FR-014)", releases }, null, 2)}\n`;
171
173
  }
172
174
  /** The entries of a record's text, or why it is not one. */
@@ -187,9 +189,10 @@ export function readRecord(text) {
187
189
  return err(`${RECORD_PATH}: an entry is not an object`);
188
190
  const o = Object.fromEntries(Object.entries(e));
189
191
  const { slug, version, folder, tag, publish } = o;
190
- if (typeof slug !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
191
- return err(`${RECORD_PATH}: an entry lacks its slug, version, folder, tag or publish`);
192
- out.push({ slug, version, folder, tag, publish });
192
+ const pkg = o["package"];
193
+ if (typeof slug !== "string" || typeof pkg !== "string" || typeof version !== "string" || typeof folder !== "string" || typeof tag !== "string" || typeof publish !== "boolean")
194
+ return err(`${RECORD_PATH}: an entry lacks its slug, package, version, folder, tag or publish`);
195
+ out.push({ slug, package: pkg, version, folder, tag, publish });
193
196
  }
194
197
  return ok(out);
195
198
  }
@@ -226,8 +229,31 @@ export function writeVersion(repo, step) {
226
229
  writeTextFileSync(at, changed);
227
230
  files.push(file);
228
231
  }
232
+ const manifest = decodeLibrarySource(readTextFileSync(join(repo, step.folder, LIBRARY_FILE)));
233
+ if (manifest.kind === "err")
234
+ return err(`${step.folder}/${LIBRARY_FILE}: ${manifest.error}`);
235
+ for (const c of manifest.value.versionConstants ?? []) {
236
+ const done = writeConstant(repo, step, c);
237
+ if (done.kind === "err")
238
+ return done;
239
+ files.push(done.value);
240
+ }
229
241
  return ok(files);
230
242
  }
243
+ /** Escapes the characters of a name that a regular expression reads as syntax. */
244
+ const quoted = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
245
+ /** 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. */
246
+ export function writeConstant(repo, step, c) {
247
+ const path = `${step.folder}/${c.file}`;
248
+ const at = join(repo, path);
249
+ if (!existsSync(at))
250
+ return err(`${path} is missing: the manifest names it as holding the version in ${c.name}`);
251
+ const changed = set(readTextFileSync(at), new RegExp(`(\\b${quoted(c.name)}\\b[^=\\n]*=\\s*)"[^"]*"`), `$1"${step.to}"`);
252
+ if (changed === undefined)
253
+ return err(`${path} does not say ${c.name} = "<version>"`);
254
+ writeTextFileSync(at, changed);
255
+ return ok(path);
256
+ }
231
257
  /** The files of a gzipped tar, as a registry serves it: each regular file's path and SHA-256. A header it cannot read ends the list there. */
232
258
  export function tarballOf(gz) {
233
259
  const bytes = gunzipSync(gz);
@@ -266,9 +292,9 @@ export function driftOf(published, local) {
266
292
  }
267
293
  /** 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. */
268
294
  export function realRegistry(repo) {
269
- return async (slug, version, folder) => {
295
+ return async (name, version, folder) => {
270
296
  try {
271
- const meta = await fetch(`https://registry.npmjs.org/@intellectual-frontiers%2F${slug}/${version}`, { signal: AbortSignal.timeout(30_000) });
297
+ const meta = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2F")}/${version}`, { signal: AbortSignal.timeout(30_000) });
272
298
  if (meta.status === 404)
273
299
  return "absent";
274
300
  if (!meta.ok)
@@ -308,7 +334,7 @@ export async function factsOf(repo, registry = realRegistry(repo)) {
308
334
  if (head.kind === "err")
309
335
  return err(formatGitError(head.error));
310
336
  const folders = workFolders(tree.value.paths);
311
- const libs = everyLibrary(repo);
337
+ const libs = everyLibrary(repo).filter((l) => l.held === undefined);
312
338
  const slugs = new Map();
313
339
  for (const l of libs) {
314
340
  const s = slugOf(l.name);
@@ -355,7 +381,7 @@ export async function factsOf(repo, registry = realRegistry(repo)) {
355
381
  let sinceVersion = { changed: false, impact: "patch" };
356
382
  if (ahead) {
357
383
  if (l.distribution.includes("npm"))
358
- drift = await registry(slug, l.version, l.folder);
384
+ drift = await registry(publishedPackage(l), l.version, l.folder);
359
385
  const raisedAt = await run(["git", "-C", repo, "log", "-1", "--format=%H", '-G"version"', "--", `${l.folder}/package.json`]);
360
386
  const commit = raisedAt.code === 0 ? raisedAt.stdout.trim() : "";
361
387
  if (commit !== "") {
@@ -371,13 +397,16 @@ export async function factsOf(repo, registry = realRegistry(repo)) {
371
397
  };
372
398
  }
373
399
  }
374
- const imports = inputsOf(repo, l.name).imports.flatMap((n) => {
400
+ // 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)
401
+ const members = l.bundle === undefined ? undefined : membersOf(l.bundle, libs);
402
+ const imports = (members?.kind === "ok" ? members.value.map((m) => m.library) : inputsOf(repo, l.name).imports).flatMap((n) => {
375
403
  const s = slugs.get(n);
376
404
  return s === undefined ? [] : [s];
377
405
  });
378
406
  out.push({
379
407
  slug,
380
408
  folder: l.folder,
409
+ package: publishedPackage(l),
381
410
  version: l.version,
382
411
  imports,
383
412
  last: last === undefined ? undefined : { version: last.version, tag: last.tag },
@@ -393,6 +422,7 @@ export async function factsOf(repo, registry = realRegistry(repo)) {
393
422
  /** 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`. */
394
423
  export const GENERATORS = [
395
424
  ["commons/libraries/src/libraries.ts"],
425
+ ["commons/libraries/src/pack-metapackage.ts"],
396
426
  ["commons/tools/generate-packaging.ts"],
397
427
  ["commons/libraries/src/generate-ontology.ts"],
398
428
  ["commons/libraries/src/generate-workflows.ts"],
@@ -463,7 +493,7 @@ export async function publishAll(entries, tools) {
463
493
  let npm = "not-published";
464
494
  let registry = "not-published";
465
495
  if (e.publish) {
466
- if (await tools.onNpm(`@intellectual-frontiers/${e.slug}`, e.version))
496
+ if (await tools.onNpm(e.package, e.version))
467
497
  npm = "present";
468
498
  else {
469
499
  const sent = await tools.npm(e);
@@ -528,11 +558,11 @@ export function realTools(dir) {
528
558
  });
529
559
  return r.code === 0
530
560
  ? ok(undefined)
531
- : 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}`)}`);
561
+ : 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}`)}`);
532
562
  },
533
563
  github: async (e) => {
534
564
  const auth = [`--registry=https://npm.pkg.github.com`, `--//npm.pkg.github.com/:_authToken=${github}`];
535
- if (await view(`@intellectual-frontiers/${e.slug}`, e.version, auth))
565
+ if (await view(e.package, e.version, auth))
536
566
  return ok(undefined);
537
567
  const f = tarball(e.slug);
538
568
  if (f === undefined)
@@ -25,9 +25,9 @@ export declare const PIN: {
25
25
  readonly deployPages: "actions/deploy-pages@v4";
26
26
  readonly bun: "./.github/actions/bun";
27
27
  };
28
- /** The Node that is the backup runtime (commons 0005-typescript-runtime). */
28
+ /** The Node that is the backup runtime (commons 0005-typescript-practice FR-018). */
29
29
  export declare const NODE_VERSION = "26.13.1";
30
- /** The canary of Bun that runs the linter until a release does (FR-028 of 0005-typescript-runtime). */
30
+ /** The canary of Bun that runs the linter until a release does (commons 0005-typescript-practice FR-028). */
31
31
  export declare const BUN_LINT_VERSION = "1.4.4-canary.20261115.1";
32
32
  /** The systems other than Linux that a library's CI may ask for: only a library with code of its own for one of them (paths, processes, sockets, scheduled jobs) names it. */
33
33
  export type OtherSystem = "windows-latest" | "macos-latest";
@@ -25,16 +25,15 @@ export const PIN = {
25
25
  deployPages: "actions/deploy-pages@v4",
26
26
  bun: "./.github/actions/bun",
27
27
  };
28
- /** The Node that is the backup runtime (commons 0005-typescript-runtime). */
28
+ /** The Node that is the backup runtime (commons 0005-typescript-practice FR-018). */
29
29
  export const NODE_VERSION = "26.13.1";
30
- /** The canary of Bun that runs the linter until a release does (FR-028 of 0005-typescript-runtime). */
30
+ /** The canary of Bun that runs the linter until a release does (commons 0005-typescript-practice FR-028). */
31
31
  export const BUN_LINT_VERSION = "1.4.4-canary.20261115.1";
32
32
  const checkout = (o = {}) => use(PIN.checkout, {
33
33
  ...(o.fetchDepth === undefined ? {} : { with: { "fetch-depth": o.fetchDepth } }),
34
34
  ...(o.comment === undefined ? {} : { comment: o.comment }),
35
35
  });
36
36
  const bun = (o = {}) => use(PIN.bun, o.nodeVersion === undefined ? {} : { with: { "node-version": o.nodeVersion } });
37
- const setupNode = (when) => use(PIN.setupNode, { ...(when === undefined ? {} : { when }), with: { "node-version": expr("env.NODE_VERSION") } });
38
37
  const tools = (workingDirectory, name = "The development tools, from bun.lock") => run("bun install --frozen-lockfile", { name, workingDirectory });
39
38
  /**
40
39
  * A run that a newer push to the same branch replaces is stopped, except on main, where each commit keeps its own result.
@@ -97,7 +96,7 @@ const CI_PATHS = ["commons/**", "package.json", "bun.lock", BUN_ACTION, own("ci"
97
96
  const cellSteps = () => [
98
97
  checkout(),
99
98
  bun(),
100
- tools(expr("matrix.folder"), "The development tools, from bun.lock (the kernel is linked from commons/ts)"),
99
+ tools(expr("matrix.folder"), "The development tools, from bun.lock (the libraries it imports are linked)"),
101
100
  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
101
  run(expr("matrix.after"), { name: "After verify", when: "matrix.after != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
103
102
  run(expr("matrix.node"), { name: "The tests on Node 26", when: "matrix.node != ''", workingDirectory: expr("matrix.folder"), shell: "bash" }),
@@ -112,7 +111,7 @@ const ci = {
112
111
  file: "ci",
113
112
  name: "ci",
114
113
  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 },
114
+ on: { push: { paths: CI_PATHS }, pullRequest: { paths: CI_PATHS }, workflowDispatch: true, schedule: ["17 3 * * *"] },
116
115
  permissions: { contents: "read" },
117
116
  env: { NODE_VERSION },
118
117
  concurrency: {
@@ -134,7 +133,7 @@ const ci = {
134
133
  bun(),
135
134
  run("bun install --frozen-lockfile", { name: "The packages the plan reads, from the root's bun.lock" }),
136
135
  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" }),
136
+ 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 ] || [ "$GITHUB_EVENT_NAME" = schedule ]; then scope=--all; else scope="--base $base"; fi', 'bun commons/libraries/src/plan.ts $scope --github-output "$GITHUB_OUTPUT"', "# 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", "{ echo '### Proof plan'; echo '```'; bun commons/repoctl/src/repoctl.ts prove --tier 6 --why $scope 2>&1 || true; echo '```'; } >> \"$GITHUB_STEP_SUMMARY\""), { name: "The libraries this change affects, and the systems each runs on", id: "plan", shell: "bash" }),
138
137
  ],
139
138
  }),
140
139
  verify: job({
@@ -167,73 +166,16 @@ const ci = {
167
166
  }),
168
167
  },
169
168
  };
170
- const ifcTypescriptPaths = [
171
- "commons/ts/**",
172
- "commons/docs/**",
173
- "commons/generated/pins.auto.env",
174
- "package.json",
175
- "bun.lock",
176
- BUN_ACTION,
177
- own("ifc-typescript"),
178
- ];
179
- const ifcTypescript = {
180
- file: "ifc-typescript",
181
- name: "ifc-typescript",
182
- comment: lines("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", "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,", "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.").trimEnd(),
183
- on: { push: { paths: ifcTypescriptPaths }, pullRequest: { paths: ifcTypescriptPaths } },
169
+ const conformancePaths = ["commons/telemetry/**", "commons/system/**", "commons/generated/pins.auto.env", BUN_ACTION, own("conformance")];
170
+ const conformance = {
171
+ file: "conformance",
172
+ name: "conformance",
173
+ comment: lines("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),", "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.").trimEnd(),
174
+ on: { push: { paths: conformancePaths }, pullRequest: { paths: conformancePaths } },
184
175
  permissions: { contents: "read" },
185
- env: { NODE_VERSION, BUN_LINT_VERSION },
176
+ env: { NODE_VERSION },
186
177
  concurrency: supersedable,
187
178
  jobs: {
188
- check: job({
189
- runsOn: "ubuntu-latest",
190
- timeoutMinutes: 10,
191
- steps: [
192
- checkout(),
193
- bun(),
194
- tools("commons/ts"),
195
- run("bun x tsc --version && bun run check", {
196
- name: "TypeScript 7 on everything, then the kernel with no host types",
197
- workingDirectory: "commons/ts",
198
- }),
199
- run("bun fmt --check", { name: "The formatter", workingDirectory: "commons/ts" }),
200
- run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 kernel runtime tests tools', {
201
- name: "The linter, type-aware, no warning allowed",
202
- workingDirectory: "commons/ts",
203
- }),
204
- ],
205
- }),
206
- test: job({
207
- runsOn: expr("matrix.os"),
208
- timeoutMinutes: 15,
209
- strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"], runtime: ["bun", "node"] } },
210
- steps: [
211
- checkout(),
212
- bun(),
213
- tools("commons/ts"),
214
- setupNode("matrix.runtime == 'node'"),
215
- run('bun x "bun@$BUN_LINT_VERSION" --version', {
216
- name: "The linter's canary, so the lint plugin's tests run rather than skip",
217
- shell: "bash",
218
- }),
219
- run(lines(`grep -E '^000[5-8]-' ../spec-kit/enforcement.tsv >"$RUNNER_TEMP/requirements.tsv"`, "bun ../quality/src/test-cli.ts run --runtime ${{ matrix.runtime }} --out test-results \\", " --report tap,junit,ctrf,sarif,md,html,oscal \\", ' --requirements "$RUNNER_TEMP/requirements.tsv" --reviewed ci-reviewed.tsv \\', " --ledger test-results/ledger.jsonl tests"), {
220
- name: "The suite on ${{ matrix.runtime }}, recorded as evidence (commons 0008-test-evidence FR-014)",
221
- comment: "A hang ends here, so the record of what ran is still kept below.",
222
- timeoutMinutes: 10,
223
- workingDirectory: "commons/ts",
224
- shell: "bash",
225
- }),
226
- use(PIN.uploadArtifact, {
227
- name: "The record, its reports and the ledger, kept with the run",
228
- when: "always()",
229
- with: {
230
- name: "test-evidence-${{ matrix.os }}-${{ matrix.runtime }}",
231
- path: "commons/ts/test-results/",
232
- "if-no-files-found": "error",
233
- },
234
- }),
235
- ],
236
- }),
237
179
  "otel-conformance": job({
238
180
  comment: "commons 0006-signals FR-020: the suite's OTLP sent to the pinned OpenTelemetry Collector, read back from its file exporter.",
239
181
  runsOn: "ubuntu-latest",
@@ -250,7 +192,7 @@ const ifcTypescript = {
250
192
  ],
251
193
  }),
252
194
  compile: job({
253
- comment: "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.",
195
+ comment: "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.",
254
196
  runsOn: expr("matrix.os"),
255
197
  timeoutMinutes: 10,
256
198
  strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"] } },
@@ -271,43 +213,17 @@ const ifcTypescript = {
271
213
  }),
272
214
  ],
273
215
  }),
274
- "git-dependency": job({
275
- comment: lines("commons 0005-typescript-runtime FR-030 and 0011-documentation FR-022: the commit checked, installed into an empty project by a", "git+file: URL of this checkout, as a consumer installs it by github:intellectual-frontiers/.github#<commit>, and used there.").trimEnd(),
276
- runsOn: expr("matrix.os"),
277
- timeoutMinutes: 15,
278
- strategy: { failFast: false, matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"] } },
279
- steps: [
280
- checkout({
281
- fetchDepth: 0,
282
- comment: "Bun clones the checkout as a Git repository; a whole one, so that nothing depends on how a shallow clone is cloned.",
283
- }),
284
- bun({ nodeVersion: expr("env.NODE_VERSION") }),
285
- run("bun install --frozen-lockfile", {
286
- name: "The root package's lockfile, which the consumer does not read but this repository keeps",
287
- }),
288
- run(lines("bun install --frozen-lockfile", "node --version", 'bun tools/smoke.ts --repo "$GITHUB_WORKSPACE" --commit "$GITHUB_SHA"'), {
289
- name: "IFC TypeScript as a Git dependency, on Bun and Node 26, with ifc test and tsc 7",
290
- workingDirectory: "commons/ts",
291
- shell: "bash",
292
- }),
293
- run(lines("bun install --frozen-lockfile", 'bun tools/smoke.ts --repo "$GITHUB_WORKSPACE" --commit "$GITHUB_SHA"'), {
294
- name: "IFC Docs as a Git dependency, ifc-docs check and build on a fixture repository on Bun and Node 26",
295
- workingDirectory: "commons/docs",
296
- shell: "bash",
297
- }),
298
- ],
299
- }),
300
216
  },
301
217
  };
302
- const docsPaths = ["commons/**", "package.json", own("docs"), BUN_ACTION];
218
+ const docsPaths = ["commons/**", "package.json", own("site"), BUN_ACTION];
303
219
  const onMainPush = "github.event_name != 'pull_request' && github.ref == 'refs/heads/main'";
304
- const docs = {
305
- file: "docs",
306
- name: "docs",
220
+ const site = {
221
+ file: "site",
222
+ name: "site",
307
223
  comment: lines("The documentation site of commons (commons 0011-documentation FR-020): made by commons/docs, from commons' TypeScript and spec kit alone,", "as commons' configuration (commons/docs.config.ts) says. Every pull request and push that touches commons tests the generator and checks", "the site (no finding, every link and anchor resolves); a push to main builds the site and publishes it to GitHub Pages with GitHub's own", "actions. The site is never committed.").trimEnd(),
308
224
  on: { push: { paths: docsPaths }, pullRequest: { paths: docsPaths }, workflowDispatch: true },
309
225
  permissions: { contents: "read" },
310
- concurrency: { group: "docs-${{ github.ref }}", cancelInProgress: true },
226
+ concurrency: { group: "site-${{ github.ref }}", cancelInProgress: true },
311
227
  jobs: {
312
228
  check: job({
313
229
  runsOn: "ubuntu-24.04",
@@ -315,9 +231,9 @@ const docs = {
315
231
  steps: [
316
232
  checkout(),
317
233
  bun(),
318
- tools("commons/docs", "TypeScript 7.1 (beta), Mermaid and @types/node, exactly as bun.lock pins them (IFC TypeScript is ../ts, by relative path)"),
234
+ tools("commons/docs", "TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them"),
319
235
  run("bun run verify", { name: "The compiler, the generator's tests, then check on commons", workingDirectory: "commons/docs" }),
320
- run('bun main.ts build --out "$GITHUB_WORKSPACE/_site"', {
236
+ run('bun src/main.ts build --out "$GITHUB_WORKSPACE/_site"', {
321
237
  name: "The site, built",
322
238
  when: onMainPush,
323
239
  workingDirectory: "commons/docs",
@@ -372,12 +288,14 @@ const tests = {
372
288
  comment: "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)",
373
289
  }),
374
290
  bun(),
375
- tools("commons/ts"),
376
- run("bun run check", { name: "TypeScript 7 on commons' tools and on these tests", workingDirectory: "commons/ts" }),
377
- run("bun fmt --check . ../tools ../../tests", { name: "The formatter", workingDirectory: "commons/ts" }),
378
- run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 ../tools ../../tests', {
291
+ tools(".", "The root's development tools, from bun.lock"),
292
+ tools("commons/docs", "The documentation generator's dependencies, which the tests of the root import"),
293
+ run("bun commons/libraries/src/link.ts && bun x tsc -p tests/tsconfig.json && bun x tsc -p commons/tools/tsconfig.json", {
294
+ name: "TypeScript 7 on the tests of the root and on commons' tools",
295
+ }),
296
+ run("bun fmt --check commons/tools tests", { name: "The formatter" }),
297
+ run('bun x "bun@$BUN_LINT_VERSION" lint --type-aware --max-warnings 0 commons/tools tests', {
379
298
  name: "The linter, type-aware, no warning allowed",
380
- workingDirectory: "commons/ts",
381
299
  }),
382
300
  run(lines(...checkScripts(false)), {
383
301
  name: "Commons' generated files and specifications, as a person checks them, on Bun and on Node 26",
@@ -391,7 +309,7 @@ const tests = {
391
309
  steps: [
392
310
  checkout(),
393
311
  bun(),
394
- tools("commons/ts"),
312
+ tools(".", "The root's development tools, from bun.lock"),
395
313
  run("sudo apt-get update -qq && sudo apt-get install -y -qq shellcheck", {
396
314
  name: "ShellCheck, which the packaging test uses where it is installed",
397
315
  when: "runner.os == 'Linux'",
@@ -516,8 +434,8 @@ export function workflows() {
516
434
  return [
517
435
  ci,
518
436
  release,
519
- docs,
520
- ifcTypescript,
437
+ site,
438
+ conformance,
521
439
  tests,
522
440
  ].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
523
441
  }
@@ -526,7 +444,7 @@ export const ACTIONS = [
526
444
  {
527
445
  folder: "bun",
528
446
  name: "Pinned Bun",
529
- description: "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.",
447
+ description: "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.",
530
448
  inputs: { "node-version": { description: "The Node that runs the installer.", default: NODE_VERSION } },
531
449
  steps: [
532
450
  use(PIN.setupNode, { with: { "node-version": expr("inputs.node-version") } }),
@@ -87,6 +87,8 @@ export type Triggers = {
87
87
  readonly workflowDispatch?: true | {
88
88
  readonly inputs: Readonly<Record<string, DispatchInput>>;
89
89
  };
90
+ /** Run on a schedule: each entry is a cron expression of five fields, in UTC. */
91
+ readonly schedule?: readonly string[];
90
92
  /** Called by another workflow. */
91
93
  readonly workflowCall?: true;
92
94
  };
@@ -154,6 +154,8 @@ export function renderWorkflow(w) {
154
154
  for (const [k, v] of Object.entries(dispatch.inputs))
155
155
  out.push(` ${key(k)}:`, ...entry("description", v.description, 8), ...entry("type", v.type, 8), ...entry("default", v.default, 8));
156
156
  }
157
+ if (w.on.schedule !== undefined && w.on.schedule.length > 0)
158
+ out.push(" schedule:", ...w.on.schedule.map((c) => ` - cron: ${scalar(c)}`));
157
159
  if (w.on.workflowCall === true)
158
160
  out.push(" workflow_call:");
159
161
  out.push("");