@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/LICENSE +75 -21
- package/dist/dev.d.ts +2 -0
- package/dist/dev.js +13 -1
- package/dist/family.js +1 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +5 -0
- package/dist/libraries.js +12 -2
- package/dist/license/standard.d.ts +46 -0
- package/dist/license/standard.js +43 -0
- package/dist/license/third-party.d.ts +25 -0
- package/dist/license/third-party.js +71 -0
- package/dist/license.d.ts +61 -0
- package/dist/license.js +204 -0
- package/dist/pack-library.d.ts +2 -0
- package/dist/pack-library.js +15 -2
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/readme.d.ts +59 -0
- package/dist/readme.js +272 -0
- package/dist/workflows/definitions.js +1 -1
- package/dist/workflows/model.d.ts +4 -0
- package/package.json +24 -14
- package/src/dev.ts +12 -1
- package/src/family.ts +1 -0
- package/src/generate-ontology.ts +4 -0
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +14 -2
- package/src/license/standard.ts +67 -0
- package/src/license/third-party.ts +87 -0
- package/src/license.ts +222 -0
- package/src/pack-library.ts +15 -2
- package/src/pins.ts +55 -10
- package/src/readme.ts +278 -0
- package/src/workflows/definitions.ts +2 -2
- package/src/workflows/model.ts +4 -0
package/src/readme.ts
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
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, type Brand, err, ok, refine, type Result, string } from "@intellectual-frontiers/core";
|
|
30
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
31
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
32
|
+
import { type Library, type Registry, readLibraries } from "./libraries.ts";
|
|
33
|
+
|
|
34
|
+
/** The marker that opens the generated table, and the one that closes it. */
|
|
35
|
+
export const BEGIN = "<!-- libraries-map:begin -->";
|
|
36
|
+
export const END = "<!-- libraries-map:end -->";
|
|
37
|
+
|
|
38
|
+
/** What a library is for in the whole: a closed union. */
|
|
39
|
+
export const ROLES = ["foundation", "pattern", "program", "standard"] as const;
|
|
40
|
+
/** A role a reader of the README may be in, as the generated library map names them. */
|
|
41
|
+
export type Role = (typeof ROLES)[number];
|
|
42
|
+
|
|
43
|
+
/** The heading of a role in the table. */
|
|
44
|
+
export const ROLE_TITLE: Readonly<Record<Role, string>> = {
|
|
45
|
+
foundation: "Foundation",
|
|
46
|
+
pattern: "Pattern",
|
|
47
|
+
program: "Program",
|
|
48
|
+
standard: "Standard",
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
/** A library's name (its folder), made only by {@link parseLibraryName}. */
|
|
52
|
+
export type LibraryName = Brand<string, "library name">;
|
|
53
|
+
const nameDecoder = refine(string, "library name", (t) => /^[a-z][a-z0-9-]*$/.test(t));
|
|
54
|
+
|
|
55
|
+
/** A library name from text, or why the text is not one. */
|
|
56
|
+
export function parseLibraryName(text: string): Result<LibraryName, string> {
|
|
57
|
+
const r = nameDecoder(text, "name");
|
|
58
|
+
return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a library name`);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The role of each library, by name. A new library is classified here, or the check names it. */
|
|
62
|
+
export const ROLE_OF: ReadonlyMap<string, Role> = new Map<string, Role>([
|
|
63
|
+
["core", "foundation"],
|
|
64
|
+
["crypto", "foundation"],
|
|
65
|
+
["formats", "foundation"],
|
|
66
|
+
["githost", "foundation"],
|
|
67
|
+
["lint", "foundation"],
|
|
68
|
+
["net", "foundation"],
|
|
69
|
+
["rdf", "foundation"],
|
|
70
|
+
["system", "foundation"],
|
|
71
|
+
["telemetry", "foundation"],
|
|
72
|
+
["terminal", "foundation"],
|
|
73
|
+
["test", "foundation"],
|
|
74
|
+
["headless", "pattern"],
|
|
75
|
+
["kanon", "pattern"],
|
|
76
|
+
["archon", "program"],
|
|
77
|
+
["toolchain", "program"],
|
|
78
|
+
["data", "program"],
|
|
79
|
+
["ergonex", "program"],
|
|
80
|
+
["grc", "program"],
|
|
81
|
+
["integrations", "program"],
|
|
82
|
+
["integrations-github", "program"],
|
|
83
|
+
["libraries", "program"],
|
|
84
|
+
["integrations-fhir", "standard"],
|
|
85
|
+
["integrations-x12", "standard"],
|
|
86
|
+
["mizan", "standard"],
|
|
87
|
+
["ontology", "standard"],
|
|
88
|
+
["quality", "standard"],
|
|
89
|
+
]);
|
|
90
|
+
|
|
91
|
+
const roleRank = (r: Role): number => {
|
|
92
|
+
switch (r) {
|
|
93
|
+
case "foundation":
|
|
94
|
+
return 0;
|
|
95
|
+
case "pattern":
|
|
96
|
+
return 1;
|
|
97
|
+
case "program":
|
|
98
|
+
return 2;
|
|
99
|
+
case "standard":
|
|
100
|
+
return 3;
|
|
101
|
+
default:
|
|
102
|
+
return absurd(r);
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
/** One row of the table. */
|
|
107
|
+
export type Row = {
|
|
108
|
+
readonly name: LibraryName;
|
|
109
|
+
readonly role: Role;
|
|
110
|
+
readonly purpose: string;
|
|
111
|
+
readonly shape: string;
|
|
112
|
+
readonly level: string;
|
|
113
|
+
readonly distribution: readonly Registry[];
|
|
114
|
+
readonly published: boolean;
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
|
|
119
|
+
* An error where the file has no summary or it is not literals.
|
|
120
|
+
*/
|
|
121
|
+
export function summaryOf(source: string): Result<string, string> {
|
|
122
|
+
const m = /\bsummary:\s*/.exec(source);
|
|
123
|
+
if (m === null) return err("it has no summary");
|
|
124
|
+
let at = m.index + m[0].length;
|
|
125
|
+
const parts: string[] = [];
|
|
126
|
+
for (;;) {
|
|
127
|
+
const lit = /^"(?:[^"\\\n]|\\.)*"/.exec(source.slice(at));
|
|
128
|
+
if (lit === null) return err("its summary is not a string literal");
|
|
129
|
+
try {
|
|
130
|
+
const v: unknown = JSON.parse(lit[0]);
|
|
131
|
+
if (typeof v !== "string") return err("its summary is not a string literal");
|
|
132
|
+
parts.push(v);
|
|
133
|
+
} catch {
|
|
134
|
+
return err("its summary is not a string literal");
|
|
135
|
+
}
|
|
136
|
+
at += lit[0].length;
|
|
137
|
+
const plus = /^\s*\+\s*/.exec(source.slice(at));
|
|
138
|
+
if (plus === null) break;
|
|
139
|
+
at += plus[0].length;
|
|
140
|
+
}
|
|
141
|
+
return ok(parts.join(""));
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** 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. */
|
|
145
|
+
export function firstSentence(text: string): string {
|
|
146
|
+
let depth = 0;
|
|
147
|
+
let tick = false;
|
|
148
|
+
for (let i = 0; i < text.length; i++) {
|
|
149
|
+
const c = text.charAt(i);
|
|
150
|
+
if (c === "`") tick = !tick;
|
|
151
|
+
else if (tick) continue;
|
|
152
|
+
else if (c === "(") depth++;
|
|
153
|
+
else if (c === ")") depth = Math.max(0, depth - 1);
|
|
154
|
+
else if (c === "." && depth === 0 && (i + 1 === text.length || /\s/.test(text.charAt(i + 1)))) return text.slice(0, i);
|
|
155
|
+
}
|
|
156
|
+
return text.trim();
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* 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
|
|
161
|
+
* outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
|
|
162
|
+
*/
|
|
163
|
+
export function firstClause(text: string): string {
|
|
164
|
+
const sentence = firstSentence(text).replace(/\s+/g, " ").trim();
|
|
165
|
+
if (sentence.length <= 110) return sentence;
|
|
166
|
+
let depth = 0;
|
|
167
|
+
let tick = false;
|
|
168
|
+
for (let i = 0; i < sentence.length; i++) {
|
|
169
|
+
const c = sentence.charAt(i);
|
|
170
|
+
if (c === "`") tick = !tick;
|
|
171
|
+
else if (tick) continue;
|
|
172
|
+
else if (c === "(") depth++;
|
|
173
|
+
else if (c === ")") depth = Math.max(0, depth - 1);
|
|
174
|
+
else if (depth === 0 && i >= 25 && (c === ":" || c === ";" || c === ",")) return sentence.slice(0, i);
|
|
175
|
+
}
|
|
176
|
+
return sentence;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
|
|
180
|
+
export function shapeOf(l: Library): string {
|
|
181
|
+
const t = l.kanon;
|
|
182
|
+
if (t === undefined) return "-";
|
|
183
|
+
const parts = ["layers", ...(t.instances.length > 0 ? ["instances"] : []), ...(t.plugins.length > 0 ? ["plugins"] : []), ...(t.extends === undefined ? [] : ["extension"])];
|
|
184
|
+
return parts.join(", ");
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** A row of the table for a library and its summary, or why there is none. */
|
|
188
|
+
export function rowOf(l: Library, summary: string): Result<Row, string> {
|
|
189
|
+
const name = parseLibraryName(l.name);
|
|
190
|
+
if (name.kind === "err") return name;
|
|
191
|
+
const role = ROLE_OF.get(l.name);
|
|
192
|
+
if (role === undefined) 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`);
|
|
193
|
+
return ok({
|
|
194
|
+
name: name.value,
|
|
195
|
+
role,
|
|
196
|
+
purpose: firstClause(summary).replace(/\|/g, "\\|"),
|
|
197
|
+
shape: shapeOf(l),
|
|
198
|
+
level: l.level,
|
|
199
|
+
distribution: l.distribution,
|
|
200
|
+
published: l.distribution.includes("npm"),
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
const REGISTRY_TITLE: Readonly<Record<Registry, string>> = { github: "GitHub", npm: "npm" };
|
|
205
|
+
|
|
206
|
+
/** The table, as Markdown, for the rows given: sorted by role, then by name. */
|
|
207
|
+
export function tableOf(rows: readonly Row[]): string {
|
|
208
|
+
const sorted = [...rows].sort((a, b) => roleRank(a.role) - roleRank(b.role) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
209
|
+
const head = ["| Library | Role | What it is | Kanon | Level | Published to |", "| --- | --- | --- | --- | --- | --- |"];
|
|
210
|
+
const body = sorted.map((r) => {
|
|
211
|
+
const pkg = `@intellectual-frontiers/${r.name}`;
|
|
212
|
+
const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
|
|
213
|
+
return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ")} |`;
|
|
214
|
+
});
|
|
215
|
+
return [...head, ...body].join("\n");
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/** The rows of a repository, and what is wrong with reading them. */
|
|
219
|
+
export function rowsOf(repo: string): { readonly rows: readonly Row[]; readonly problems: readonly string[] } {
|
|
220
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
221
|
+
const rows: Row[] = [];
|
|
222
|
+
const problems: string[] = [];
|
|
223
|
+
for (const f of readLibraries(root)) {
|
|
224
|
+
if ("problem" in f) {
|
|
225
|
+
problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
|
|
226
|
+
continue;
|
|
227
|
+
}
|
|
228
|
+
const file = `${root}/commons/${f.dir}/about.ts`;
|
|
229
|
+
if (!existsSync(file)) {
|
|
230
|
+
problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
|
|
231
|
+
continue;
|
|
232
|
+
}
|
|
233
|
+
const s = summaryOf(readTextFileSync(file));
|
|
234
|
+
if (s.kind === "err") {
|
|
235
|
+
problems.push(`commons/${f.dir}/about.ts: ${s.error}`);
|
|
236
|
+
continue;
|
|
237
|
+
}
|
|
238
|
+
const r = rowOf(f.library, s.value);
|
|
239
|
+
if (r.kind === "err") problems.push(r.error);
|
|
240
|
+
else rows.push(r.value);
|
|
241
|
+
}
|
|
242
|
+
return { rows, problems };
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** 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. */
|
|
246
|
+
export function withTable(readme: string, table: string): Result<string, string> {
|
|
247
|
+
const from = readme.indexOf(`\n${BEGIN}\n`);
|
|
248
|
+
const to = readme.indexOf(`\n${END}\n`, from);
|
|
249
|
+
if (from < 0 || to < 0) return err(`README.md has no ${BEGIN} and ${END}, each on a line of its own, around the table of the libraries`);
|
|
250
|
+
return ok(`${readme.slice(0, from + 1 + BEGIN.length)}\n\n${table}\n\n${readme.slice(to + 1)}`);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
|
|
254
|
+
export function synchronize(repo: string, write: boolean): { readonly stale: boolean; readonly problems: readonly string[] } {
|
|
255
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
256
|
+
const file = `${root}/README.md`;
|
|
257
|
+
const { rows, problems } = rowsOf(root);
|
|
258
|
+
if (!existsSync(file)) return { stale: false, problems: [...problems, "README.md is missing"] };
|
|
259
|
+
const text = readTextFileSync(file).replace(/\r\n/g, "\n");
|
|
260
|
+
const made = withTable(text, tableOf(rows));
|
|
261
|
+
if (made.kind === "err") return { stale: false, problems: [...problems, made.error] };
|
|
262
|
+
const stale = made.value !== text;
|
|
263
|
+
if (stale && write && problems.length === 0) writeTextFileSync(file, made.value);
|
|
264
|
+
return { stale, problems };
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
|
|
268
|
+
export function main(argv: readonly string[]): number {
|
|
269
|
+
const at = argv.indexOf("--repo");
|
|
270
|
+
const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
|
|
271
|
+
const check = argv.includes("--check");
|
|
272
|
+
const r = synchronize(repo, !check);
|
|
273
|
+
for (const p of r.problems) stdio.stderr.writeSync(`${p}\n`);
|
|
274
|
+
if (r.stale) stdio.stderr.writeSync(check ? "README.md is not what the manifests make; run: bun commons/libraries/src/readme.ts\n" : "wrote README.md\n");
|
|
275
|
+
return r.problems.length > 0 || (check && r.stale) ? 1 : 0;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
if (import.meta.main) process.exitCode = main(process.argv.slice(2));
|
|
@@ -326,11 +326,11 @@ const ifcTypescript: Workflow = {
|
|
|
326
326
|
tools("commons/telemetry"),
|
|
327
327
|
run(
|
|
328
328
|
lines(
|
|
329
|
-
"
|
|
329
|
+
"url=$(sed -n 's/^OTELCOL_CONTRIB_URL_X86_64=//p' commons/generated/pins.auto.env)",
|
|
330
330
|
"sum=$(sed -n 's/^OTELCOL_CONTRIB_SHA256_X86_64=//p' commons/generated/pins.auto.env)",
|
|
331
331
|
'dir="$RUNNER_TEMP/otelcol"',
|
|
332
332
|
'mkdir -p "$dir"',
|
|
333
|
-
'curl -fsSL -o "$dir/otelcol.tar.gz" "
|
|
333
|
+
'curl -fsSL -o "$dir/otelcol.tar.gz" "$url"',
|
|
334
334
|
'echo "$sum $dir/otelcol.tar.gz" | sha256sum -c -',
|
|
335
335
|
'tar -xzf "$dir/otelcol.tar.gz" -C "$dir" otelcol-contrib',
|
|
336
336
|
'echo "IFC_OTELCOL=$dir/otelcol-contrib" >>"$GITHUB_ENV"',
|
package/src/workflows/model.ts
CHANGED
|
@@ -88,6 +88,7 @@ export type Filter = { readonly branches?: readonly string[]; readonly paths?: r
|
|
|
88
88
|
/** A question a run by hand asks: a yes or no with its default. */
|
|
89
89
|
export type DispatchInput = { readonly description: string; readonly type: "boolean"; readonly default: boolean };
|
|
90
90
|
|
|
91
|
+
/** What starts a generated workflow: pushes, pull requests, dispatch and schedule. */
|
|
91
92
|
export type Triggers = {
|
|
92
93
|
readonly push?: Filter;
|
|
93
94
|
readonly pullRequest?: Filter;
|
|
@@ -100,11 +101,13 @@ export type Triggers = {
|
|
|
100
101
|
/** 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. */
|
|
101
102
|
export type Matrix = Readonly<Record<string, readonly (string | number)[]>> | Expr;
|
|
102
103
|
|
|
104
|
+
/** The matrix strategy of a job of a generated workflow. */
|
|
103
105
|
export type Strategy = {
|
|
104
106
|
readonly failFast?: boolean;
|
|
105
107
|
readonly matrix: Matrix;
|
|
106
108
|
};
|
|
107
109
|
|
|
110
|
+
/** A job of a generated workflow. */
|
|
108
111
|
export type Job = {
|
|
109
112
|
readonly name?: string;
|
|
110
113
|
readonly runsOn: Runner;
|
|
@@ -126,6 +129,7 @@ export type Job = {
|
|
|
126
129
|
/** A job, written as a function so that its steps are read as a non-empty tuple. */
|
|
127
130
|
export const job = (j: Job): Job => j;
|
|
128
131
|
|
|
132
|
+
/** A generated workflow: its name, triggers, permissions and jobs. */
|
|
129
133
|
export type Workflow = {
|
|
130
134
|
/** The file's name without its directory and extension: `data` is `.github/workflows/data.auto.yml`. */
|
|
131
135
|
readonly file: string;
|