@intellectual-frontiers/libraries 0.4.0 → 0.4.1

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.
package/dist/readme.js ADDED
@@ -0,0 +1,272 @@
1
+ /**
2
+ * The map of the libraries in the root `README.md`: the table between the markers `<!-- libraries-map:begin -->` and `<!-- libraries-map:end -->`, one row for each library of `commons/`, made from
3
+ * the manifests (`library.ts`) and the `summary` of each library's `about.ts`, so that the first page of the repository cannot name a library that is gone or miss one that is new.
4
+ *
5
+ * bun commons/libraries/src/readme.ts write the table again from the manifests
6
+ * bun commons/libraries/src/readme.ts --check write nothing and exit 1 where README.md is not what the manifests make
7
+ * other flags: --repo DIR (the repository, the working folder by default)
8
+ *
9
+ * @remarks
10
+ * Both files are read as data and no library is run: the manifest by `readLibraries`, the summary of `about.ts` by reading the string literals that follow `summary:` (joined by `+`). A row has the library's package
11
+ * as a link (to npm where the library is published there, else to its folder), the first clause of the first sentence of its summary, its Kanon shape where the manifest declares a table (`layers`, and
12
+ * `instances` and `plugins` where it declares those), its conformance level and the registries it is published to. Rows are sorted by role, then by name; the role of a library is a closed union
13
+ * held in {@link ROLE_OF}, and a library with no entry there is a problem, never a row of no role. A version is not in the table: versions grow at the release, and a table that held them would be stale at every release.
14
+ *
15
+ * @limits
16
+ * It writes one file, README.md, and only between the markers; it does not judge the prose around them (the test of the README does).
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * import { firstClause } from "./readme.ts";
21
+ * firstClause("Mizan, the IF Spec Profile, as code. The harness holds the rules."); // "Mizan, the IF Spec Profile, as code"
22
+ * ```
23
+ *
24
+ * Spec: 0001-libraries FR-017
25
+ *
26
+ * @module
27
+ */
28
+ import process from "node:process";
29
+ import { absurd, err, ok, refine, string } from "@intellectual-frontiers/core";
30
+ import { stdio } from "@intellectual-frontiers/system";
31
+ import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
32
+ import { readLibraries } from "./libraries.js";
33
+ /** The marker that opens the generated table, and the one that closes it. */
34
+ export const BEGIN = "<!-- libraries-map:begin -->";
35
+ export const END = "<!-- libraries-map:end -->";
36
+ /** What a library is for in the whole: a closed union. */
37
+ export const ROLES = ["foundation", "pattern", "program", "standard"];
38
+ /** The heading of a role in the table. */
39
+ export const ROLE_TITLE = {
40
+ foundation: "Foundation",
41
+ pattern: "Pattern",
42
+ program: "Program",
43
+ standard: "Standard",
44
+ };
45
+ const nameDecoder = refine(string, "library name", (t) => /^[a-z][a-z0-9-]*$/.test(t));
46
+ /** A library name from text, or why the text is not one. */
47
+ export function parseLibraryName(text) {
48
+ const r = nameDecoder(text, "name");
49
+ return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a library name`);
50
+ }
51
+ /** The role of each library, by name. A new library is classified here, or the check names it. */
52
+ export const ROLE_OF = new Map([
53
+ ["core", "foundation"],
54
+ ["crypto", "foundation"],
55
+ ["formats", "foundation"],
56
+ ["githost", "foundation"],
57
+ ["lint", "foundation"],
58
+ ["net", "foundation"],
59
+ ["rdf", "foundation"],
60
+ ["system", "foundation"],
61
+ ["telemetry", "foundation"],
62
+ ["terminal", "foundation"],
63
+ ["test", "foundation"],
64
+ ["headless", "pattern"],
65
+ ["kanon", "pattern"],
66
+ ["archon", "program"],
67
+ ["toolchain", "program"],
68
+ ["data", "program"],
69
+ ["ergonex", "program"],
70
+ ["grc", "program"],
71
+ ["integrations", "program"],
72
+ ["integrations-github", "program"],
73
+ ["libraries", "program"],
74
+ ["integrations-fhir", "standard"],
75
+ ["integrations-x12", "standard"],
76
+ ["mizan", "standard"],
77
+ ["ontology", "standard"],
78
+ ["quality", "standard"],
79
+ ]);
80
+ const roleRank = (r) => {
81
+ switch (r) {
82
+ case "foundation":
83
+ return 0;
84
+ case "pattern":
85
+ return 1;
86
+ case "program":
87
+ return 2;
88
+ case "standard":
89
+ return 3;
90
+ default:
91
+ return absurd(r);
92
+ }
93
+ };
94
+ /**
95
+ * The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
96
+ * An error where the file has no summary or it is not literals.
97
+ */
98
+ export function summaryOf(source) {
99
+ const m = /\bsummary:\s*/.exec(source);
100
+ if (m === null)
101
+ return err("it has no summary");
102
+ let at = m.index + m[0].length;
103
+ const parts = [];
104
+ for (;;) {
105
+ const lit = /^"(?:[^"\\\n]|\\.)*"/.exec(source.slice(at));
106
+ if (lit === null)
107
+ return err("its summary is not a string literal");
108
+ try {
109
+ const v = JSON.parse(lit[0]);
110
+ if (typeof v !== "string")
111
+ return err("its summary is not a string literal");
112
+ parts.push(v);
113
+ }
114
+ catch {
115
+ return err("its summary is not a string literal");
116
+ }
117
+ at += lit[0].length;
118
+ const plus = /^\s*\+\s*/.exec(source.slice(at));
119
+ if (plus === null)
120
+ break;
121
+ at += plus[0].length;
122
+ }
123
+ return ok(parts.join(""));
124
+ }
125
+ /** The first sentence of a text: up to the first full stop that is followed by a space or the end, outside parentheses and backticks. */
126
+ export function firstSentence(text) {
127
+ let depth = 0;
128
+ let tick = false;
129
+ for (let i = 0; i < text.length; i++) {
130
+ const c = text.charAt(i);
131
+ if (c === "`")
132
+ tick = !tick;
133
+ else if (tick)
134
+ continue;
135
+ else if (c === "(")
136
+ depth++;
137
+ else if (c === ")")
138
+ depth = Math.max(0, depth - 1);
139
+ else if (c === "." && depth === 0 && (i + 1 === text.length || /\s/.test(text.charAt(i + 1))))
140
+ return text.slice(0, i);
141
+ }
142
+ return text.trim();
143
+ }
144
+ /**
145
+ * The first clause of a text's first sentence: the sentence where it is short (110 characters or fewer), else the sentence cut at its first `:`, `;` or comma that is
146
+ * outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
147
+ */
148
+ export function firstClause(text) {
149
+ const sentence = firstSentence(text).replace(/\s+/g, " ").trim();
150
+ if (sentence.length <= 110)
151
+ return sentence;
152
+ let depth = 0;
153
+ let tick = false;
154
+ for (let i = 0; i < sentence.length; i++) {
155
+ const c = sentence.charAt(i);
156
+ if (c === "`")
157
+ tick = !tick;
158
+ else if (tick)
159
+ continue;
160
+ else if (c === "(")
161
+ depth++;
162
+ else if (c === ")")
163
+ depth = Math.max(0, depth - 1);
164
+ else if (depth === 0 && i >= 25 && (c === ":" || c === ";" || c === ","))
165
+ return sentence.slice(0, i);
166
+ }
167
+ return sentence;
168
+ }
169
+ /** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
170
+ export function shapeOf(l) {
171
+ const t = l.kanon;
172
+ if (t === undefined)
173
+ return "-";
174
+ const parts = ["layers", ...(t.instances.length > 0 ? ["instances"] : []), ...(t.plugins.length > 0 ? ["plugins"] : []), ...(t.extends === undefined ? [] : ["extension"])];
175
+ return parts.join(", ");
176
+ }
177
+ /** A row of the table for a library and its summary, or why there is none. */
178
+ export function rowOf(l, summary) {
179
+ const name = parseLibraryName(l.name);
180
+ if (name.kind === "err")
181
+ return name;
182
+ const role = ROLE_OF.get(l.name);
183
+ if (role === undefined)
184
+ return err(`commons/${l.name} has no role in ROLE_OF (commons/libraries/src/readme.ts): say whether it is a foundation, a pattern, a program or a standard`);
185
+ return ok({
186
+ name: name.value,
187
+ role,
188
+ purpose: firstClause(summary).replace(/\|/g, "\\|"),
189
+ shape: shapeOf(l),
190
+ level: l.level,
191
+ distribution: l.distribution,
192
+ published: l.distribution.includes("npm"),
193
+ });
194
+ }
195
+ const REGISTRY_TITLE = { github: "GitHub", npm: "npm" };
196
+ /** The table, as Markdown, for the rows given: sorted by role, then by name. */
197
+ export function tableOf(rows) {
198
+ const sorted = [...rows].sort((a, b) => roleRank(a.role) - roleRank(b.role) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
199
+ const head = ["| Library | Role | What it is | Kanon | Level | Published to |", "| --- | --- | --- | --- | --- | --- |"];
200
+ const body = sorted.map((r) => {
201
+ const pkg = `@intellectual-frontiers/${r.name}`;
202
+ 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(", ")} |`;
204
+ });
205
+ return [...head, ...body].join("\n");
206
+ }
207
+ /** The rows of a repository, and what is wrong with reading them. */
208
+ export function rowsOf(repo) {
209
+ const root = repo.replace(/[\\/]$/, "");
210
+ const rows = [];
211
+ const problems = [];
212
+ for (const f of readLibraries(root)) {
213
+ if ("problem" in f) {
214
+ problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
215
+ continue;
216
+ }
217
+ const file = `${root}/commons/${f.dir}/about.ts`;
218
+ if (!existsSync(file)) {
219
+ problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
220
+ continue;
221
+ }
222
+ const s = summaryOf(readTextFileSync(file));
223
+ if (s.kind === "err") {
224
+ problems.push(`commons/${f.dir}/about.ts: ${s.error}`);
225
+ continue;
226
+ }
227
+ const r = rowOf(f.library, s.value);
228
+ if (r.kind === "err")
229
+ problems.push(r.error);
230
+ else
231
+ rows.push(r.value);
232
+ }
233
+ return { rows, problems };
234
+ }
235
+ /** 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
+ export function withTable(readme, table) {
237
+ const from = readme.indexOf(`\n${BEGIN}\n`);
238
+ const to = readme.indexOf(`\n${END}\n`, from);
239
+ if (from < 0 || to < 0)
240
+ return err(`README.md has no ${BEGIN} and ${END}, each on a line of its own, around the table of the libraries`);
241
+ return ok(`${readme.slice(0, from + 1 + BEGIN.length)}\n\n${table}\n\n${readme.slice(to + 1)}`);
242
+ }
243
+ /** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
244
+ export function synchronize(repo, write) {
245
+ const root = repo.replace(/[\\/]$/, "");
246
+ const file = `${root}/README.md`;
247
+ const { rows, problems } = rowsOf(root);
248
+ if (!existsSync(file))
249
+ return { stale: false, problems: [...problems, "README.md is missing"] };
250
+ const text = readTextFileSync(file).replace(/\r\n/g, "\n");
251
+ const made = withTable(text, tableOf(rows));
252
+ if (made.kind === "err")
253
+ return { stale: false, problems: [...problems, made.error] };
254
+ const stale = made.value !== text;
255
+ if (stale && write && problems.length === 0)
256
+ writeTextFileSync(file, made.value);
257
+ return { stale, problems };
258
+ }
259
+ /** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
260
+ export function main(argv) {
261
+ const at = argv.indexOf("--repo");
262
+ const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
263
+ const check = argv.includes("--check");
264
+ const r = synchronize(repo, !check);
265
+ for (const p of r.problems)
266
+ stdio.stderr.writeSync(`${p}\n`);
267
+ if (r.stale)
268
+ stdio.stderr.writeSync(check ? "README.md is not what the manifests make; run: bun commons/libraries/src/readme.ts\n" : "wrote README.md\n");
269
+ return r.problems.length > 0 || (check && r.stale) ? 1 : 0;
270
+ }
271
+ if (import.meta.main)
272
+ process.exitCode = main(process.argv.slice(2));
@@ -242,7 +242,7 @@ const ifcTypescript = {
242
242
  checkout(),
243
243
  bun(),
244
244
  tools("commons/telemetry"),
245
- run(lines("v=$(sed -n 's/^OTELCOL_CONTRIB_VERSION=//p' commons/generated/pins.auto.env)", "sum=$(sed -n 's/^OTELCOL_CONTRIB_SHA256_X86_64=//p' commons/generated/pins.auto.env)", 'dir="$RUNNER_TEMP/otelcol"', 'mkdir -p "$dir"', 'curl -fsSL -o "$dir/otelcol.tar.gz" "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v$v/otelcol-contrib_${v}_linux_amd64.tar.gz"', 'echo "$sum $dir/otelcol.tar.gz" | sha256sum -c -', 'tar -xzf "$dir/otelcol.tar.gz" -C "$dir" otelcol-contrib', 'echo "IFC_OTELCOL=$dir/otelcol-contrib" >>"$GITHUB_ENV"'), { name: "The OpenTelemetry Collector, verified against commons' pins", shell: "bash" }),
245
+ run(lines("url=$(sed -n 's/^OTELCOL_CONTRIB_URL_X86_64=//p' commons/generated/pins.auto.env)", "sum=$(sed -n 's/^OTELCOL_CONTRIB_SHA256_X86_64=//p' commons/generated/pins.auto.env)", 'dir="$RUNNER_TEMP/otelcol"', 'mkdir -p "$dir"', 'curl -fsSL -o "$dir/otelcol.tar.gz" "$url"', 'echo "$sum $dir/otelcol.tar.gz" | sha256sum -c -', 'tar -xzf "$dir/otelcol.tar.gz" -C "$dir" otelcol-contrib', 'echo "IFC_OTELCOL=$dir/otelcol-contrib" >>"$GITHUB_ENV"'), { name: "The OpenTelemetry Collector, verified against commons' pins", shell: "bash" }),
246
246
  run(lines("bun test suite/otel-conformance.test.ts", "node --test suite/otel-conformance.test.ts"), {
247
247
  name: "The conformance test, on Bun and on Node",
248
248
  workingDirectory: "commons/telemetry",
@@ -79,6 +79,7 @@ export type DispatchInput = {
79
79
  readonly type: "boolean";
80
80
  readonly default: boolean;
81
81
  };
82
+ /** What starts a generated workflow: pushes, pull requests, dispatch and schedule. */
82
83
  export type Triggers = {
83
84
  readonly push?: Filter;
84
85
  readonly pullRequest?: Filter;
@@ -91,10 +92,12 @@ export type Triggers = {
91
92
  };
92
93
  /** 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
94
  export type Matrix = Readonly<Record<string, readonly (string | number)[]>> | Expr;
95
+ /** The matrix strategy of a job of a generated workflow. */
94
96
  export type Strategy = {
95
97
  readonly failFast?: boolean;
96
98
  readonly matrix: Matrix;
97
99
  };
100
+ /** A job of a generated workflow. */
98
101
  export type Job = {
99
102
  readonly name?: string;
100
103
  readonly runsOn: Runner;
@@ -117,6 +120,7 @@ export type Job = {
117
120
  };
118
121
  /** A job, written as a function so that its steps are read as a non-empty tuple. */
119
122
  export declare const job: (j: Job) => Job;
123
+ /** A generated workflow: its name, triggers, permissions and jobs. */
120
124
  export type Workflow = {
121
125
  /** The file's name without its directory and extension: `data` is `.github/workflows/data.auto.yml`. */
122
126
  readonly file: string;
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/libraries",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "The libraries of a repository of commons as code: the manifest of a library and the check that it and its folder agree, which libraries a change affects, the typed workflows of GitHub Actions and their generator, the pinned Bun, the packer that builds, inspects and packs a library for npm with its declarations, and the commands that hold a whole repository to Mizan (check, change control, versions, the register and the ontologies).",
5
- "license": "MIT",
5
+ "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "type": "module",
7
7
  "engines": {
8
8
  "node": ">=26"
@@ -50,6 +50,11 @@
50
50
  "bun": "./src/libraries.ts",
51
51
  "default": "./dist/libraries.js"
52
52
  },
53
+ "./license": {
54
+ "types": "./dist/license.d.ts",
55
+ "bun": "./src/license.ts",
56
+ "default": "./dist/license.js"
57
+ },
53
58
  "./link": {
54
59
  "types": "./dist/link.d.ts",
55
60
  "bun": "./src/link.ts",
@@ -90,6 +95,11 @@
90
95
  "bun": "./src/publish-ontology.ts",
91
96
  "default": "./dist/publish-ontology.js"
92
97
  },
98
+ "./readme": {
99
+ "types": "./dist/readme.d.ts",
100
+ "bun": "./src/readme.ts",
101
+ "default": "./dist/readme.js"
102
+ },
93
103
  "./versions": {
94
104
  "types": "./dist/versions.d.ts",
95
105
  "bun": "./src/versions.ts",
@@ -117,18 +127,18 @@
117
127
  }
118
128
  },
119
129
  "dependencies": {
120
- "@intellectual-frontiers/core": "0.1.4",
121
- "@intellectual-frontiers/crypto": "0.1.4",
122
- "@intellectual-frontiers/formats": "0.1.4",
123
- "@intellectual-frontiers/githost": "0.1.2",
124
- "@intellectual-frontiers/kanon": "0.2.0",
125
- "@intellectual-frontiers/mizan": "0.1.1",
126
- "@intellectual-frontiers/net": "0.1.5",
127
- "@intellectual-frontiers/ontology": "0.3.0",
128
- "@intellectual-frontiers/quality": "0.2.0",
129
- "@intellectual-frontiers/rdf": "0.1.4",
130
- "@intellectual-frontiers/system": "0.1.6",
131
- "@intellectual-frontiers/terminal": "0.1.6"
130
+ "@intellectual-frontiers/core": "0.1.5",
131
+ "@intellectual-frontiers/crypto": "0.1.5",
132
+ "@intellectual-frontiers/formats": "0.1.5",
133
+ "@intellectual-frontiers/githost": "0.1.3",
134
+ "@intellectual-frontiers/kanon": "0.2.1",
135
+ "@intellectual-frontiers/mizan": "0.1.2",
136
+ "@intellectual-frontiers/net": "0.1.6",
137
+ "@intellectual-frontiers/ontology": "0.3.1",
138
+ "@intellectual-frontiers/quality": "0.2.1",
139
+ "@intellectual-frontiers/rdf": "0.1.5",
140
+ "@intellectual-frontiers/system": "0.1.7",
141
+ "@intellectual-frontiers/terminal": "0.1.7"
132
142
  },
133
143
  "files": [
134
144
  "dist",
package/src/dev.ts CHANGED
@@ -7,7 +7,7 @@
7
7
  * bun run dev:check --files a.ts,b/c.ts the libraries these files affect (paths from the repository's root)
8
8
  * bun run dev:check --all every library
9
9
  * bun run dev:check --list say what is affected and run nothing
10
- * other flags: --base REF (origin/main by default), --no-types, --no-tests, --bail (stop at the first failing test), --repo DIR
10
+ * other flags: --base REF (origin/main by default), --no-types, --no-tests, --no-license, --bail (stop at the first failing test), --repo DIR
11
11
  *
12
12
  * @remarks
13
13
  * Nothing is installed per library. The repository's root installs the packages every library shares (`bun install`, once), the libraries are linked under `commons/node_modules` (a link for each folder whose package
@@ -40,6 +40,7 @@ import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intel
40
40
  import { label, paint } from "@intellectual-frontiers/terminal/palette";
41
41
  import { affectedBy, changedSince, everyLibrary } from "./affected.ts";
42
42
  import { linkAll } from "./link.ts";
43
+ import { judge as judgeLicense, sentence as licenseSentence } from "./license.ts";
43
44
  import type { Library } from "./libraries.ts";
44
45
 
45
46
  /** What the loop is asked about: what changed since a revision, a list of files, named libraries or everything. */
@@ -217,6 +218,14 @@ export async function typeCheck(repo: string, libs: readonly Lib[], width: numbe
217
218
  };
218
219
  }
219
220
 
221
+ /** The license of the repository and of each library, as the check of `license.ts` finds it: a library with no `LICENSE` fails here, and the sentence says the command that writes it. */
222
+ export async function licenseStage(repo: string): Promise<Outcome> {
223
+ const t0 = performance.now();
224
+ const { findings } = await judgeLicense(repo);
225
+ if (findings.length === 0) return { kind: "passed", detail: `every LICENSE is the official text in ${seconds(t0)}` };
226
+ return { kind: "failed", detail: plural(findings.length, "finding", "findings"), output: findings.map(licenseSentence) };
227
+ }
228
+
220
229
  /** The sum of counts. */
221
230
  export const addCounts = (a: Counts, b: Counts): Counts => ({ pass: a.pass + b.pass, skip: a.skip + b.skip, fail: a.fail + b.fail, files: a.files + b.files });
222
231
 
@@ -291,6 +300,7 @@ const OPTIONS = {
291
300
  list: flag({ help: "Say what is affected and run nothing." }),
292
301
  types: flag({ help: "Type-check the libraries (on by default).", negatable: true, default: true }),
293
302
  tests: flag({ help: "Run their tests (on by default).", negatable: true, default: true }),
303
+ license: flag({ help: "Check the license files of the repository (on by default).", negatable: true, default: true }),
294
304
  bail: flag({ help: "Stop the tests at the first one that fails." }),
295
305
  repo: value({ help: "The repository (the working folder, or the one above it that has commons/, by default).", valueName: "DIR" }),
296
306
  };
@@ -361,6 +371,7 @@ export async function main(argv: readonly string[]): Promise<number> {
361
371
  ]);
362
372
  stages.push({ name: "types", outcome: types }, { name: "tests", outcome: tests });
363
373
  }
374
+ if (!o.list && o.license) stages.push({ name: "license", outcome: await licenseStage(repo) });
364
375
  for (const l of summaryLines(look, { why, libs: names }, stages, notes, seconds(t0))) stdio.stdout.writeSync(`${l}\n`);
365
376
  return stages.some((s) => s.outcome.kind === "failed") ? 1 : 0;
366
377
  }
package/src/family.ts CHANGED
@@ -42,6 +42,7 @@ export const RESERVED: readonly Reservation[] = [
42
42
  { match: { kind: "exact", name: "signing" }, host: "signing", reason: "held for the signing library of the fleet libraries (intellectual-frontiers/.github#11)" },
43
43
  { match: { kind: "exact", name: "gitops" }, host: "gitops", reason: "held for the gitops library of the fleet libraries (intellectual-frontiers/.github#11)" },
44
44
  { match: { kind: "exact", name: "estate" }, host: "estate", reason: "held for the estate library of the fleet libraries (intellectual-frontiers/.github#11)" },
45
+ { match: { kind: "exact", name: "toolchain" }, host: "toolchain", reason: "held for the toolchain library of the fleet libraries (intellectual-frontiers/.github#11)" },
45
46
  ];
46
47
 
47
48
  /** Whether a library name is one a match holds. */
@@ -75,6 +75,8 @@ export const MIZAN: OntologyPublication = {
75
75
  ["dcterms", "http://purl.org/dc/terms/"],
76
76
  ["pm", "https://www.intellectualfrontiers.com/ontology/packaging#"],
77
77
  ["schema", "https://schema.org/"],
78
+ ["dcat", "http://www.w3.org/ns/dcat#"],
79
+ ["purl", "https://github.com/package-url/purl-spec#"],
78
80
  ],
79
81
  files,
80
82
  ontology: mizanOntology,
@@ -97,6 +99,8 @@ export const MIZAN: OntologyPublication = {
97
99
  dcterms: "http://purl.org/dc/terms/",
98
100
  pm: "https://www.intellectualfrontiers.com/ontology/packaging#",
99
101
  schema: "https://schema.org/",
102
+ dcat: "http://www.w3.org/ns/dcat#",
103
+ purl: "https://github.com/package-url/purl-spec#",
100
104
  },
101
105
  viewTitle: "Mizan: the shared ontology",
102
106
  license: CC0,
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Bun at the version commons pins (`BUN_VERSION` and its SHA-256 per platform in `commons/generated/pins.auto.env`, commons
3
- * 0005-typescript-runtime FR-026), fetched from Bun's release with retries, kept only where its SHA-256 is the pinned one, unpacked by the
2
+ * Bun at the version commons pins (its version, address, SHA-256, format and folder per platform in `commons/generated/pins.auto.env`, commons
3
+ * 0005-typescript-runtime FR-026, 0002-packaging FR-019), fetched from that address with retries, kept only where its SHA-256 is the pinned one, unpacked by the
4
4
  * kernel's own zip reader and put in a folder; nothing but IFC TypeScript itself, so it runs on Node 26 (or Bun) on Linux, macOS
5
5
  * and Windows with no shell, no Python and no unzip. CI's `.github/actions/bun` runs it.
6
6
  *
@@ -17,7 +17,7 @@ import { chmod, ensureDir, readFile, readTextFile, writeFile, writeTextFile } fr
17
17
  import { downloadVerified, Retries } from "@intellectual-frontiers/net/net";
18
18
  import { dirname, fromFileUrl, join, resolve } from "@intellectual-frontiers/system/path";
19
19
  import { args, build, env, exit } from "@intellectual-frontiers/system/proc";
20
- import { bunTarget, readEnvFile } from "./pins.ts";
20
+ import { describePinProblem, pinDownload, pinSuffix, readEnvFile } from "./pins.ts";
21
21
 
22
22
  /** Stop with a message and status 1. */
23
23
  function stop(message: string): never {
@@ -30,21 +30,24 @@ const given = args[0];
30
30
  if (given === undefined) stop("give the folder to put Bun in");
31
31
  const dest = resolve(given);
32
32
  const pins = readEnvFile(await readTextFile(join(ROOT, "commons", "generated", "pins.auto.env")));
33
- const platform = bunTarget(build.os, build.arch);
34
- if (platform === undefined) stop(`Bun has no build for ${build.os} on ${build.arch}`);
35
- const version = pins.get("BUN_VERSION");
36
- const sum = sha256Of(pins.get(`BUN_SHA256_${platform.key}`) ?? "");
37
- if (version === undefined || sum === undefined) stop(`commons pins no Bun for ${platform.key}`);
33
+ const suffix = pinSuffix(build.os, build.arch);
34
+ if (suffix === undefined) stop(`Bun has no build for ${build.os} on ${build.arch}`);
35
+ const pin = pinDownload(pins, "BUN", suffix);
36
+ if (pin.kind === "err") stop(describePinProblem(pin.error));
37
+ const download = pin.value;
38
+ if (download.format !== "zip") stop(`commons pins Bun as ${download.format}, and this installer unpacks a zip`);
39
+ const sum = sha256Of(download.sha256);
40
+ if (sum === undefined) stop(`commons pins no SHA-256 of Bun for ${suffix}`);
38
41
  const retries = new Retries({ tries: 5, base: 2, cap: 30 }, (line) => console.error(line));
39
- const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/bun-${platform.target}.zip`;
40
- const zip = await downloadVerified(retries, url, sum, join(dest, "cache"));
42
+ const zip = await downloadVerified(retries, download.url, sum, join(dest, "cache"));
41
43
  if (zip.kind === "err") stop(zip.error);
42
44
  const files = await unzip(await readFile(zip.value));
43
45
  if (files.kind === "err") stop(formatArchiveError(files.error));
44
46
  const exe = build.os === "windows" ? "bun.exe" : "bun";
45
- const bytes = files.value.get(`bun-${platform.target}/${exe}`);
46
- if (bytes === undefined) stop(`the zip holds no bun-${platform.target}/${exe}`);
47
- const bin = join(dest, `bun-${version}`);
47
+ const inside = download.binPath === "" ? exe : `${download.binPath}/${exe}`;
48
+ const bytes = files.value.get(inside);
49
+ if (bytes === undefined) stop(`the zip holds no ${inside}`);
50
+ const bin = join(dest, `bun-${download.version}`);
48
51
  await ensureDir(bin);
49
52
  await writeFile(join(bin, exe), bytes);
50
53
  await chmod(join(bin, exe), 0o755);
package/src/libraries.ts CHANGED
@@ -41,6 +41,7 @@ import {
41
41
  ok,
42
42
  type Result,
43
43
  } from "@intellectual-frontiers/core";
44
+ import { parseSpdxId, type SpdxId } from "./license/standard.ts";
44
45
  import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
45
46
  import { decodeTable, type Table } from "@intellectual-frontiers/kanon";
46
47
  import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
@@ -58,6 +59,7 @@ export const LIBRARIES_SPEC = "0027-commons-libraries";
58
59
  export const FIRST_GENERATED = 101;
59
60
  /** The marker that opens the generated section, and the one that closes it. */
60
61
  export const BEGIN = "<!-- libraries:begin -->";
62
+ /** The marker that ends the generated section of the libraries in a document. */
61
63
  export const END = "<!-- libraries:end -->";
62
64
 
63
65
  /** Where the generated section begins and ends: the markers on lines of their own (a requirement may name them in its text). */
@@ -89,6 +91,8 @@ export type Library = {
89
91
  readonly kanon?: Table;
90
92
  /** Its host and its role where it is of a family (a host, a dialect of it or a plugin of it; 0033-kanon FR-021, 0027-commons-libraries FR-023). */
91
93
  readonly family?: LibraryFamily;
94
+ /** The license its `LICENSE` and its packed `package.json` carry, where it is not the default of the repository (`license/standard.ts`; commons 0035-licensing FR-003). */
95
+ readonly license?: SpdxId;
92
96
  };
93
97
 
94
98
  /** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
@@ -96,6 +100,7 @@ export const KANON_REQUIRED_FROM: LevelKey | undefined = undefined;
96
100
 
97
101
  /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
98
102
  export const REGISTRIES = ["github", "npm"] as const;
103
+ /** A registry a library is distributed to: github or npm. */
99
104
  export type Registry = (typeof REGISTRIES)[number];
100
105
  /** Where a manifest that declares no distribution is published. */
101
106
  export const DEFAULT_DISTRIBUTION: readonly Registry[] = ["github"];
@@ -114,9 +119,9 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
114
119
  };
115
120
  const body = object(
116
121
  { name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
117
- { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }) },
122
+ { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }), license: nonEmpty },
118
123
  );
119
- const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family"] as const;
124
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family", "license"] as const;
120
125
 
121
126
  /** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
122
127
  export function decodeLibrarySource(source: string): Result<Library, string> {
@@ -152,6 +157,12 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
152
157
  if (f.kind === "err") return f;
153
158
  family = f.value;
154
159
  }
160
+ let license: SpdxId | undefined;
161
+ if (v.license !== undefined) {
162
+ const l = parseSpdxId(v.license);
163
+ if (l.kind === "err") return err(`library.license: ${l.error}`);
164
+ license = l.value;
165
+ }
155
166
  return ok({
156
167
  name: v.name,
157
168
  level: v.level ?? DEFAULT_LIBRARY_LEVEL,
@@ -163,6 +174,7 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
163
174
  distribution,
164
175
  ...(kanon === undefined ? {} : { kanon }),
165
176
  ...(family === undefined ? {} : { family }),
177
+ ...(license === undefined ? {} : { license }),
166
178
  });
167
179
  }
168
180
 
@@ -0,0 +1,67 @@
1
+ /**
2
+ * The license of this repository as data: the one license every library and every part of the repository is under, the one place its identifier is written, and the standard its text is taken from
3
+ * (commons 0035-licensing FR-001 to FR-004, 0018-standards-first FR-006 and FR-007). The text is the official PolyForm Noncommercial License 1.0.0, copied byte for byte into
4
+ * `PolyForm-Noncommercial-1.0.0.md` beside this file from the tag `1.0.0` of the official repository, and held to the SHA-256 recorded here.
5
+ *
6
+ * @remarks
7
+ * Read as data by `../license.ts` (which writes and checks every `LICENSE`), by the packer (the `license` of a package) and by the decoder of the manifest (its optional `license`). The identifier is a closed union:
8
+ * a license is added to {@link SPDX_IDS} together with its text, never as a free string.
9
+ *
10
+ * Spec: 0001-libraries FR-019
11
+ *
12
+ * @module
13
+ */
14
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
15
+
16
+ /** The SPDX identifiers of the licenses this repository can carry: each has its official text in this folder. */
17
+ export const SPDX_IDS = ["PolyForm-Noncommercial-1.0.0"] as const;
18
+ /** An SPDX license identifier of {@link SPDX_IDS}. */
19
+ export type SpdxId = (typeof SPDX_IDS)[number];
20
+
21
+ /** The license of every library and of the repository, unless a manifest's `license` says another of {@link SPDX_IDS}. */
22
+ export const DEFAULT_LICENSE: SpdxId = "PolyForm-Noncommercial-1.0.0";
23
+
24
+ /** An SPDX identifier from text, or why the text is none of the licenses this repository can carry. */
25
+ export function parseSpdxId(text: string): Result<SpdxId, string> {
26
+ const found = SPDX_IDS.find((id) => id === text);
27
+ return found === undefined ? err(`${JSON.stringify(text)} is not a license of this repository (${SPDX_IDS.join(", ")})`) : ok(found);
28
+ }
29
+
30
+ /** A standard imported as data (0018-standards-first FR-006): its issuer, name, version, location, license and the SHA-256 of what was imported. */
31
+ export type Standard = {
32
+ readonly id: string;
33
+ readonly issuer: string;
34
+ readonly name: string;
35
+ readonly version: string;
36
+ /** Where the imported text is, at the tag that is pinned. */
37
+ readonly location: string;
38
+ /** What the text may be copied under (an SPDX identifier where there is one). */
39
+ readonly license: string;
40
+ readonly redistributable: boolean;
41
+ /** The SHA-256 of the file in this folder, line ends as they are (they are `\n`). */
42
+ readonly sha256: string;
43
+ /** The file of this folder that holds the text. */
44
+ readonly file: string;
45
+ };
46
+
47
+ /** The official text of each license, as a standard of 0018-standards-first. */
48
+ export const LICENSE_STANDARDS: Readonly<Record<SpdxId, Standard>> = {
49
+ "PolyForm-Noncommercial-1.0.0": {
50
+ id: "polyform-noncommercial-1.0.0",
51
+ issuer: "The PolyForm Project",
52
+ name: "PolyForm Noncommercial License 1.0.0",
53
+ version: "1.0.0",
54
+ location: "https://raw.githubusercontent.com/polyformproject/polyform-licenses/1.0.0/PolyForm-Noncommercial-1.0.0.md",
55
+ license: "The terms of LICENSE.md of polyformproject/polyform-licenses at tag 1.0.0: a PolyForm license is copied as it is, and a change removes the name PolyForm",
56
+ redistributable: true,
57
+ sha256: "c0ea4a896d2c8c394b29f9427589996db826cd501c512279ff0ed3ef48fabbe5",
58
+ file: "PolyForm-Noncommercial-1.0.0.md",
59
+ },
60
+ };
61
+
62
+ /** The licensor named in the `Required Notice:` line of every `LICENSE` and in `NOTICE`. */
63
+ export const LICENSOR = "Intellectual Frontiers LLC";
64
+ /** The repository the `Required Notice:` line names. */
65
+ export const REPOSITORY_URL = "https://github.com/intellectual-frontiers/.github";
66
+ /** Where a commercial license is asked for. */
67
+ export const COMMERCIAL_ISSUES_URL = "https://github.com/intellectual-frontiers/.github/issues";