@intellectual-frontiers/libraries 0.2.1 → 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/affected.d.ts +15 -2
- package/dist/affected.js +51 -20
- package/dist/dev.d.ts +83 -0
- package/dist/dev.js +359 -0
- package/dist/family.d.ts +58 -0
- package/dist/family.js +125 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/generate-workflows.js +2 -10
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +8 -0
- package/dist/libraries.js +24 -3
- 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/link.d.ts +12 -0
- package/dist/link.js +98 -0
- package/dist/pack-library.d.ts +2 -0
- package/dist/pack-library.js +21 -3
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/plan.d.ts +28 -0
- package/dist/plan.js +135 -0
- package/dist/readme.d.ts +59 -0
- package/dist/readme.js +272 -0
- package/dist/releasing.d.ts +176 -0
- package/dist/releasing.js +680 -0
- package/dist/versions.js +4 -7
- package/dist/workflows/definitions.d.ts +33 -30
- package/dist/workflows/definitions.js +201 -278
- package/dist/workflows/model.d.ts +19 -3
- package/dist/workflows/render.js +10 -2
- package/package.json +44 -14
- package/src/affected.ts +56 -17
- package/src/dev.ts +379 -0
- package/src/family.ts +144 -0
- package/src/generate-ontology.ts +4 -0
- package/src/generate-workflows.ts +3 -11
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +27 -3
- package/src/license/standard.ts +67 -0
- package/src/license/third-party.ts +87 -0
- package/src/license.ts +222 -0
- package/src/link.ts +97 -0
- package/src/pack-library.ts +21 -3
- package/src/pins.ts +55 -10
- package/src/plan.ts +143 -0
- package/src/readme.ts +278 -0
- package/src/releasing.ts +735 -0
- package/src/versions.ts +3 -7
- package/src/workflows/definitions.ts +262 -397
- package/src/workflows/model.ts +15 -3
- package/src/workflows/render.ts +10 -2
package/src/license.ts
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The license of the repository and of every library in it, written and checked from one place (commons 0035-licensing). One official text, the PolyForm Noncommercial License 1.0.0
|
|
3
|
+
* (`license/PolyForm-Noncommercial-1.0.0.md`, held to the SHA-256 of its standard), and one `Required Notice:` line for the licensor make the `LICENSE` of the root and of each library folder; the third-party
|
|
4
|
+
* notices are made from the record of what is vendored.
|
|
5
|
+
*
|
|
6
|
+
* bun commons/libraries/src/license.ts write every LICENSE and THIRD_PARTY_NOTICES.md again
|
|
7
|
+
* bun commons/libraries/src/license.ts --check write nothing and exit 1 where any file is not what the manifests and the official text make
|
|
8
|
+
* other flags: --repo DIR (the repository, the working folder by default)
|
|
9
|
+
*
|
|
10
|
+
* @remarks
|
|
11
|
+
* What is written: `LICENSE` at the root and in each `commons/<name>/` that holds a manifest (`library.ts`), and `THIRD_PARTY_NOTICES.md`. What is only checked, because a person writes it: `LICENSING.md`, `COMMERCIAL.md`,
|
|
12
|
+
* `NOTICE`, `CONTRIBUTING.md`, `CITATION.cff`, the License section of `README.md` and the `license` of the root `package.json`. A library with a folder and no `LICENSE` is a finding that names the command above, so a new
|
|
13
|
+
* library runs it once. The packer writes the same identifier into the `package.json` it publishes ({@link licenseOf}).
|
|
14
|
+
*
|
|
15
|
+
* @limits
|
|
16
|
+
* It does not fetch anything: the official text is the copy in `license/`, checked against the SHA-256 its standard records. It does not judge what the hand-written files say beyond the few facts named in {@link Finding}.
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```ts
|
|
20
|
+
* import { licenseFileText } from "./license.ts";
|
|
21
|
+
* licenseFileText("TEXT\n").startsWith("Required Notice: Copyright Intellectual Frontiers LLC"); // true
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* Spec: 0001-libraries FR-019
|
|
25
|
+
*
|
|
26
|
+
* @module
|
|
27
|
+
*/
|
|
28
|
+
import process from "node:process";
|
|
29
|
+
import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
|
|
30
|
+
import { sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
31
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
32
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
33
|
+
import { fromFileUrl, join, resolve } from "@intellectual-frontiers/system/path";
|
|
34
|
+
import { type Library, readLibraries } from "./libraries.ts";
|
|
35
|
+
import { COMMERCIAL_ISSUES_URL, DEFAULT_LICENSE, LICENSE_STANDARDS, LICENSOR, REPOSITORY_URL, type SpdxId } from "./license/standard.ts";
|
|
36
|
+
import { THIRD_PARTY, type ThirdPartyItem } from "./license/third-party.ts";
|
|
37
|
+
|
|
38
|
+
/** The command that writes what the check finds wrong. */
|
|
39
|
+
export const COMMAND = "bun commons/libraries/src/license.ts";
|
|
40
|
+
|
|
41
|
+
/** The license of a library: its manifest's `license`, else the default of the repository. */
|
|
42
|
+
export function licenseOf(library: Pick<Library, "license"> | undefined): SpdxId {
|
|
43
|
+
return library?.license ?? DEFAULT_LICENSE;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The line every `LICENSE` begins with, as the license asks of its licensor (its section Notices). */
|
|
47
|
+
export const REQUIRED_NOTICE = `Required Notice: Copyright ${LICENSOR} (${REPOSITORY_URL})`;
|
|
48
|
+
|
|
49
|
+
/** The text of a `LICENSE`: the required notice, a blank line and the official text exactly as it is. */
|
|
50
|
+
export function licenseFileText(official: string): string {
|
|
51
|
+
return `${REQUIRED_NOTICE}\n\n${official}`;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** What is wrong, one case for each sentence. */
|
|
55
|
+
export type Finding =
|
|
56
|
+
| { readonly kind: "text-missing"; readonly id: SpdxId; readonly file: string }
|
|
57
|
+
| { readonly kind: "text-changed"; readonly id: SpdxId; readonly want: string; readonly have: string }
|
|
58
|
+
| { readonly kind: "manifest"; readonly dir: string; readonly problem: string }
|
|
59
|
+
| { readonly kind: "missing"; readonly path: string; readonly why: string }
|
|
60
|
+
| { readonly kind: "stale"; readonly path: string }
|
|
61
|
+
| { readonly kind: "lacks"; readonly path: string; readonly what: string }
|
|
62
|
+
| { readonly kind: "vendored-gone"; readonly path: string };
|
|
63
|
+
|
|
64
|
+
/** The one sentence of a finding. */
|
|
65
|
+
export function sentence(f: Finding): string {
|
|
66
|
+
switch (f.kind) {
|
|
67
|
+
case "text-missing":
|
|
68
|
+
return `the official text of ${f.id} is not at commons/libraries/src/license/${f.file}`;
|
|
69
|
+
case "text-changed":
|
|
70
|
+
return `commons/libraries/src/license/ is not the official text of the standard: its SHA-256 is ${f.have} and the standard records ${f.want}`;
|
|
71
|
+
case "manifest":
|
|
72
|
+
return `commons/${f.dir}/library.ts cannot be read: ${f.problem}`;
|
|
73
|
+
case "missing":
|
|
74
|
+
return `${f.path} is missing: ${f.why}`;
|
|
75
|
+
case "stale":
|
|
76
|
+
return `${f.path} is not what the official text and the manifest make; run: ${COMMAND}`;
|
|
77
|
+
case "lacks":
|
|
78
|
+
return `${f.path} does not ${f.what}`;
|
|
79
|
+
case "vendored-gone":
|
|
80
|
+
return `${f.path} is named as vendored in commons/libraries/src/license/third-party.ts and is not in the repository`;
|
|
81
|
+
default:
|
|
82
|
+
return absurd(f);
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** A file this module writes: its path from the repository and its whole text. */
|
|
87
|
+
export type Made = { readonly path: string; readonly text: string };
|
|
88
|
+
|
|
89
|
+
const lf = (t: string): string => t.replaceAll("\r\n", "\n");
|
|
90
|
+
const here = resolve(fromFileUrl(new URL(".", import.meta.url)));
|
|
91
|
+
|
|
92
|
+
/** The official text of a license, held to the SHA-256 of its standard. */
|
|
93
|
+
export async function officialText(id: SpdxId, folder: string = join(here, "license")): Promise<Result<string, Finding>> {
|
|
94
|
+
const std = LICENSE_STANDARDS[id];
|
|
95
|
+
const file = join(folder, std.file);
|
|
96
|
+
if (!existsSync(file)) return err({ kind: "text-missing", id, file: std.file });
|
|
97
|
+
const text = lf(readTextFileSync(file));
|
|
98
|
+
const have = await sha256(text);
|
|
99
|
+
return have === std.sha256 ? ok(text) : err({ kind: "text-changed", id, want: std.sha256, have });
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** `THIRD_PARTY_NOTICES.md` made from the items. */
|
|
103
|
+
export function thirdPartyNotices(items: readonly ThirdPartyItem[]): string {
|
|
104
|
+
const body = items.map((i) =>
|
|
105
|
+
[
|
|
106
|
+
`## ${i.path === undefined ? i.what.split(",")[0] ?? i.what : `\`${i.path}\``}`,
|
|
107
|
+
"",
|
|
108
|
+
`- **What**: ${i.what}.`,
|
|
109
|
+
`- **Source**: ${i.source}.`,
|
|
110
|
+
`- **Owner**: ${i.owner}.`,
|
|
111
|
+
`- **License**: ${i.license}.`,
|
|
112
|
+
`- **Checked**: ${i.checked}`,
|
|
113
|
+
"",
|
|
114
|
+
].join("\n"),
|
|
115
|
+
);
|
|
116
|
+
return [
|
|
117
|
+
"# Third-party notices",
|
|
118
|
+
"",
|
|
119
|
+
"<!-- Generated by `bun commons/libraries/src/license.ts` from `commons/libraries/src/license/third-party.ts`: change that file and run the command, never this one. -->",
|
|
120
|
+
"",
|
|
121
|
+
"Intellectual Frontiers LLC owns the code of this repository, which is under the PolyForm Noncommercial License 1.0.0 (see [`LICENSE`](LICENSE)). The items below are not its own: each is under the license named, which is not changed by this repository's.",
|
|
122
|
+
"Where an item says `unverified:` the license was recorded from a secondary source and has not been checked against the original; that is for the owner to settle, and nothing here is a statement that it is settled.",
|
|
123
|
+
"",
|
|
124
|
+
"Packages installed from a registry (listed in `bun.lock`) are not vendored: nothing of them is in this repository, and each package carries its own license.",
|
|
125
|
+
"",
|
|
126
|
+
...body,
|
|
127
|
+
].join("\n");
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** The result of looking at a repository: what it should hold and what is wrong. */
|
|
131
|
+
export type Judged = { readonly made: readonly Made[]; readonly findings: readonly Finding[] };
|
|
132
|
+
|
|
133
|
+
const read = (repo: string, path: string): string | undefined => (existsSync(join(repo, path)) ? lf(readTextFileSync(join(repo, path))) : undefined);
|
|
134
|
+
|
|
135
|
+
const HAND_WRITTEN: readonly { readonly path: string; readonly why: string }[] = [
|
|
136
|
+
{ path: "LICENSING.md", why: "it says in plain words what is free and what needs a commercial license" },
|
|
137
|
+
{ path: "COMMERCIAL.md", why: "it says what a commercial license covers and how it is obtained" },
|
|
138
|
+
{ path: "NOTICE", why: "it carries the copyright of the licensor" },
|
|
139
|
+
{ path: "CONTRIBUTING.md", why: "it carries the sign-off and the contributor's agreement" },
|
|
140
|
+
{ path: "CITATION.cff", why: "it says how to cite the software and under what license" },
|
|
141
|
+
];
|
|
142
|
+
|
|
143
|
+
/** Whether `text` contains `needle`, as a finding where it does not. */
|
|
144
|
+
const must = (path: string, text: string | undefined, needle: string, what: string): readonly Finding[] =>
|
|
145
|
+
text === undefined || text.includes(needle) ? [] : [{ kind: "lacks", path, what }];
|
|
146
|
+
|
|
147
|
+
/** The files this module makes for a repository and what is wrong with the rest, read from the files and the manifests; nothing is written. */
|
|
148
|
+
export async function judge(repo: string, folder?: string): Promise<Judged> {
|
|
149
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
150
|
+
const findings: Finding[] = [];
|
|
151
|
+
const made: Made[] = [];
|
|
152
|
+
const texts = new Map<SpdxId, string>();
|
|
153
|
+
const reported = new Set<SpdxId>();
|
|
154
|
+
const textOf = async (id: SpdxId): Promise<string | undefined> => {
|
|
155
|
+
const have = texts.get(id);
|
|
156
|
+
if (have !== undefined) return have;
|
|
157
|
+
const r = await officialText(id, folder);
|
|
158
|
+
if (r.kind === "err") {
|
|
159
|
+
if (!reported.has(id)) findings.push(r.error);
|
|
160
|
+
reported.add(id);
|
|
161
|
+
return undefined;
|
|
162
|
+
}
|
|
163
|
+
texts.set(id, r.value);
|
|
164
|
+
return r.value;
|
|
165
|
+
};
|
|
166
|
+
const rootText = await textOf(DEFAULT_LICENSE);
|
|
167
|
+
if (rootText !== undefined) made.push({ path: "LICENSE", text: licenseFileText(rootText) });
|
|
168
|
+
for (const f of readLibraries(root)) {
|
|
169
|
+
if ("problem" in f) {
|
|
170
|
+
findings.push({ kind: "manifest", dir: f.dir, problem: f.problem });
|
|
171
|
+
continue;
|
|
172
|
+
}
|
|
173
|
+
const t = await textOf(licenseOf(f.library));
|
|
174
|
+
if (t !== undefined) made.push({ path: `commons/${f.dir}/LICENSE`, text: licenseFileText(t) });
|
|
175
|
+
}
|
|
176
|
+
made.push({ path: "THIRD_PARTY_NOTICES.md", text: thirdPartyNotices(THIRD_PARTY) });
|
|
177
|
+
for (const m of made) {
|
|
178
|
+
const have = read(root, m.path);
|
|
179
|
+
if (have === undefined) findings.push({ kind: "missing", path: m.path, why: m.path === "THIRD_PARTY_NOTICES.md" ? "it lists what is vendored and its licenses" : `it is the license of ${m.path === "LICENSE" ? "the repository" : "the library"}; run: ${COMMAND}` });
|
|
180
|
+
else if (have !== m.text) findings.push({ kind: "stale", path: m.path });
|
|
181
|
+
}
|
|
182
|
+
for (const h of HAND_WRITTEN) {
|
|
183
|
+
const t = read(root, h.path);
|
|
184
|
+
if (t === undefined || t.trim() === "") findings.push({ kind: "missing", path: h.path, why: h.why });
|
|
185
|
+
}
|
|
186
|
+
findings.push(...must("NOTICE", read(root, "NOTICE"), `Copyright ${LICENSOR}`, `name the copyright of ${LICENSOR}`));
|
|
187
|
+
findings.push(...must("CONTRIBUTING.md", read(root, "CONTRIBUTING.md"), "git commit -s", "ask for a sign-off with `git commit -s`"));
|
|
188
|
+
findings.push(...must("LICENSING.md", read(root, "LICENSING.md"), DEFAULT_LICENSE, `name ${DEFAULT_LICENSE}`));
|
|
189
|
+
findings.push(...must("LICENSING.md", read(root, "LICENSING.md"), COMMERCIAL_ISSUES_URL, `say where to ask for a commercial license (${COMMERCIAL_ISSUES_URL})`));
|
|
190
|
+
findings.push(...must("CITATION.cff", read(root, "CITATION.cff"), `license: ${DEFAULT_LICENSE}`, `carry \`license: ${DEFAULT_LICENSE}\``));
|
|
191
|
+
const readme = read(root, "README.md");
|
|
192
|
+
if (readme !== undefined) {
|
|
193
|
+
const at = readme.indexOf("\n## License\n");
|
|
194
|
+
const rest = at < 0 ? "" : readme.slice(at + 1);
|
|
195
|
+
const next = rest.indexOf("\n## ", 1);
|
|
196
|
+
const section = next < 0 ? rest : rest.slice(0, next);
|
|
197
|
+
if (at < 0 || !section.includes(DEFAULT_LICENSE)) findings.push({ kind: "lacks", path: "README.md", what: `have a License section that names ${DEFAULT_LICENSE}` });
|
|
198
|
+
}
|
|
199
|
+
const pkg = read(root, "package.json");
|
|
200
|
+
if (pkg !== undefined && !pkg.includes(`"license": "${DEFAULT_LICENSE}"`)) findings.push({ kind: "lacks", path: "package.json", what: `declare "license": "${DEFAULT_LICENSE}"` });
|
|
201
|
+
for (const i of THIRD_PARTY) if (i.path !== undefined && !existsSync(join(root, i.path))) findings.push({ kind: "vendored-gone", path: i.path });
|
|
202
|
+
return { made, findings };
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** The command line: 0, or 1 where a finding exists (with `--check`) or a file could not be made. Without `--check` the files are written. */
|
|
206
|
+
export async function main(argv: readonly string[]): Promise<number> {
|
|
207
|
+
const at = argv.indexOf("--repo");
|
|
208
|
+
const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
|
|
209
|
+
const check = argv.includes("--check");
|
|
210
|
+
let j = await judge(repo);
|
|
211
|
+
if (!check) {
|
|
212
|
+
for (const m of j.made) {
|
|
213
|
+
const have = read(repo, m.path);
|
|
214
|
+
if (have !== m.text) writeTextFileSync(join(repo.replace(/[\\/]$/, ""), m.path), m.text);
|
|
215
|
+
}
|
|
216
|
+
j = await judge(repo);
|
|
217
|
+
}
|
|
218
|
+
for (const f of j.findings) stdio.stderr.writeSync(`${sentence(f)}\n`);
|
|
219
|
+
return j.findings.length > 0 ? 1 : 0;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
if (import.meta.main) process.exitCode = await main(process.argv.slice(2));
|
package/src/link.ts
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The links of the libraries (commons 0001-libraries FR-011): every package of commons linked under `commons/node_modules/@intellectual-frontiers`, so that a library imports another by its package name and reads the checkout's
|
|
3
|
+
* source. It is the first command of every script that imports a library of commons (`dev:check`, `release`, the plan of CI), and it imports none: a fresh checkout has no link yet, and the command that makes them cannot
|
|
4
|
+
* itself need one.
|
|
5
|
+
*
|
|
6
|
+
* bun commons/libraries/src/link.ts link what is not linked, from the repository above this folder (or --repo DIR)
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* A folder of `commons/` whose `package.json` is named `@intellectual-frontiers/<name>` is linked as that name, and `commons/ts` as `@intellectual-frontiers/commons` (`commons/docs` bears the same name and is not linked). A link
|
|
10
|
+
* that is there is left as it is. Only the built-ins of Node are used, so it runs on Bun and on Node 26 before anything is installed.
|
|
11
|
+
*
|
|
12
|
+
* @limits
|
|
13
|
+
* It links and nothing else: the packages the root and a library install are `bun install`'s.
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```ts
|
|
17
|
+
* import { linksOf } from "./link.ts";
|
|
18
|
+
* linksOf(".").get("@intellectual-frontiers/commons"); // the path of commons/ts
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* Spec: 0001-libraries FR-011
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync } from "node:fs";
|
|
26
|
+
import { dirname, join, resolve } from "node:path";
|
|
27
|
+
import process from "node:process";
|
|
28
|
+
import { fileURLToPath } from "node:url";
|
|
29
|
+
|
|
30
|
+
const SCOPE = "@intellectual-frontiers/";
|
|
31
|
+
|
|
32
|
+
const nameOf = (file: string): string | undefined => {
|
|
33
|
+
try {
|
|
34
|
+
const x: unknown = JSON.parse(readFileSync(file, "utf8"));
|
|
35
|
+
return typeof x === "object" && x !== null && "name" in x && typeof x.name === "string" ? x.name : undefined;
|
|
36
|
+
} catch {
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** The packages of commons by name and the folder of each; `commons/ts` comes first, so that it is the one that bears `@intellectual-frontiers/commons`. */
|
|
42
|
+
export function linksOf(repo: string): ReadonlyMap<string, string> {
|
|
43
|
+
const links = new Map<string, string>();
|
|
44
|
+
const dirs = readdirSync(join(repo, "commons"), { withFileTypes: true })
|
|
45
|
+
.filter((e) => e.isDirectory() && e.name !== "node_modules")
|
|
46
|
+
.map((e) => e.name)
|
|
47
|
+
.sort((a, b) => (a === "ts" ? -1 : b === "ts" ? 1 : a < b ? -1 : 1));
|
|
48
|
+
for (const d of dirs) {
|
|
49
|
+
const name = nameOf(join(repo, "commons", d, "package.json"));
|
|
50
|
+
if (name !== undefined && name.startsWith(SCOPE) && !links.has(name)) links.set(name, join(repo, "commons", d));
|
|
51
|
+
}
|
|
52
|
+
return links;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Links each package that is not linked yet, and gives how many it linked, or why it could not. */
|
|
56
|
+
export function linkAll(repo: string): { readonly made: number } | { readonly problem: string } {
|
|
57
|
+
try {
|
|
58
|
+
const scope = join(repo, "commons", "node_modules", "@intellectual-frontiers");
|
|
59
|
+
let made = 0;
|
|
60
|
+
for (const [name, dir] of linksOf(repo)) {
|
|
61
|
+
const at = join(scope, name.slice(SCOPE.length));
|
|
62
|
+
if (existsSync(at)) continue;
|
|
63
|
+
if (made === 0) mkdirSync(scope, { recursive: true });
|
|
64
|
+
symlinkSync(dir, at, "junction");
|
|
65
|
+
made += 1;
|
|
66
|
+
}
|
|
67
|
+
return { made };
|
|
68
|
+
} catch (e) {
|
|
69
|
+
return { problem: `the libraries could not be linked under commons/node_modules: ${e instanceof Error ? e.message : String(e)}` };
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The repository above a folder: the nearest one that has `commons/libraries/library.ts`. */
|
|
74
|
+
export function rootAbove(from: string): string | undefined {
|
|
75
|
+
for (let d = resolve(from); ; d = dirname(d)) {
|
|
76
|
+
if (existsSync(join(d, "commons", "libraries", "library.ts"))) return d;
|
|
77
|
+
if (dirname(d) === d) return undefined;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The command line: 0, or 1 where it could not link. */
|
|
82
|
+
export function main(argv: readonly string[]): number {
|
|
83
|
+
const at = argv.indexOf("--repo");
|
|
84
|
+
const repo = at >= 0 ? resolve(argv[at + 1] ?? ".") : rootAbove(dirname(fileURLToPath(import.meta.url)));
|
|
85
|
+
if (repo === undefined) {
|
|
86
|
+
process.stderr.write("link: no repository with commons/libraries here; give --repo DIR\n");
|
|
87
|
+
return 1;
|
|
88
|
+
}
|
|
89
|
+
const r = linkAll(repo);
|
|
90
|
+
if ("problem" in r) {
|
|
91
|
+
process.stderr.write(`link: ${r.problem}\n`);
|
|
92
|
+
return 1;
|
|
93
|
+
}
|
|
94
|
+
return 0;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (import.meta.main) process.exitCode = main(process.argv.slice(2));
|
package/src/pack-library.ts
CHANGED
|
@@ -24,8 +24,10 @@
|
|
|
24
24
|
*/
|
|
25
25
|
import { chmod, readTextFile, writeTextFile } from "@intellectual-frontiers/system/fs";
|
|
26
26
|
import { existsSync, mkdirSync, readDirSync, readTextFileSync, removeSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
27
|
+
import { decodeLibrarySource, type Library, LIBRARY_FILE } from "./libraries.ts";
|
|
28
|
+
import { COMMAND as LICENSE_COMMAND, licenseOf } from "./license.ts";
|
|
27
29
|
import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
|
|
28
|
-
import { run, which } from "@intellectual-frontiers/system/proc";
|
|
30
|
+
import { env, run, which } from "@intellectual-frontiers/system/proc";
|
|
29
31
|
|
|
30
32
|
/** The scope of the packages of commons. */
|
|
31
33
|
export const SCOPE = "@intellectual-frontiers";
|
|
@@ -277,6 +279,7 @@ function commonsPaths(commons: string, dist: string): Record<string, readonly st
|
|
|
277
279
|
return out;
|
|
278
280
|
}
|
|
279
281
|
|
|
282
|
+
/** What packing a library made: the staging folder, the tarball, the findings and the manifest. */
|
|
280
283
|
export type Packed = { readonly stage: string; readonly tarball: string | undefined; readonly findings: Findings; readonly manifest: Json };
|
|
281
284
|
|
|
282
285
|
/** What a package adds to the common form. */
|
|
@@ -292,6 +295,7 @@ function namesNodeTypes(folder: string): boolean {
|
|
|
292
295
|
return false;
|
|
293
296
|
}
|
|
294
297
|
|
|
298
|
+
/** What packing a library is told: its folder, where to stage it and whether to make the tarball. */
|
|
295
299
|
export type PackOptions = {
|
|
296
300
|
/** Types the compiler is given (`["node"]` for a library that names Node's). */
|
|
297
301
|
readonly types?: readonly string[];
|
|
@@ -307,6 +311,14 @@ export type PackOptions = {
|
|
|
307
311
|
};
|
|
308
312
|
};
|
|
309
313
|
|
|
314
|
+
/** The manifest of the library at `root`, where it has one that can be read. */
|
|
315
|
+
function manifestOf(root: string): Library | undefined {
|
|
316
|
+
const file = join(root, LIBRARY_FILE);
|
|
317
|
+
if (!existsSync(file)) return undefined;
|
|
318
|
+
const r = decodeLibrarySource(readTextFileSync(file));
|
|
319
|
+
return r.kind === "ok" ? r.value : undefined;
|
|
320
|
+
}
|
|
321
|
+
|
|
310
322
|
/** Builds and stages the package of the library at `root` (a folder `commons/<name>/` with a `package.json` and sources in `src/`), inspects it and, where nothing is wrong, packs it. */
|
|
311
323
|
export async function packLibrary(root: string, options: PackOptions = {}): Promise<Packed> {
|
|
312
324
|
const own = JSON.parse(readTextFileSync(join(root, "package.json"))) as Json;
|
|
@@ -461,7 +473,7 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
|
|
|
461
473
|
name,
|
|
462
474
|
version: text(own["version"]),
|
|
463
475
|
description: text(own["description"]),
|
|
464
|
-
license:
|
|
476
|
+
license: licenseOf(manifestOf(root)),
|
|
465
477
|
type: "module",
|
|
466
478
|
engines: { node: ">=26" },
|
|
467
479
|
sideEffects: false,
|
|
@@ -503,7 +515,8 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
|
|
|
503
515
|
"",
|
|
504
516
|
].join("\n"),
|
|
505
517
|
);
|
|
506
|
-
|
|
518
|
+
if (existsSync(join(root, "LICENSE"))) copyFileSync(join(root, "LICENSE"), join(stage, "LICENSE"));
|
|
519
|
+
else findings.push(`commons/${short} has no LICENSE; run: ${LICENSE_COMMAND}`);
|
|
507
520
|
findings.push(...inspectPackage(stage));
|
|
508
521
|
if (findings.length > 0) return { stage, tarball: undefined, findings, manifest };
|
|
509
522
|
const packed = await run([bun, "pm", "pack", "--destination", dist], { cwd: stage });
|
|
@@ -514,6 +527,11 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
|
|
|
514
527
|
|
|
515
528
|
/** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
|
|
516
529
|
export async function main(root: string, argv: readonly string[], options: PackOptions = {}): Promise<number> {
|
|
530
|
+
// the check inside `verify` is left out where CI says the exports did not change (`IFC_SKIP_PACK`); the packing for a publication is never skipped
|
|
531
|
+
if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
|
|
532
|
+
console.log("pack check skipped: the exports of this library did not change in this push (IFC_SKIP_PACK); the release packs it");
|
|
533
|
+
return 0;
|
|
534
|
+
}
|
|
517
535
|
const r = await packLibrary(root, options);
|
|
518
536
|
for (const f of r.findings) console.error(f);
|
|
519
537
|
if (r.tarball === undefined) return 1;
|
package/src/pins.ts
CHANGED
|
@@ -1,20 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026): the `KEY=value` lines of `pins.auto.env`,
|
|
3
|
-
*
|
|
2
|
+
* Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026, 0002-packaging FR-019): the `KEY=value` lines of `pins.auto.env`, the suffix of a platform's
|
|
3
|
+
* variables, and the download of a pin on a platform (its version, address, SHA-256, format and folder), all taken from the file and written nowhere else.
|
|
4
4
|
*
|
|
5
5
|
* Spec: 0001-libraries FR-006
|
|
6
6
|
*
|
|
7
7
|
* @module
|
|
8
8
|
*/
|
|
9
|
+
import { err, ok, type Result } from "@intellectual-frontiers/core";
|
|
9
10
|
|
|
10
|
-
/** The
|
|
11
|
-
export function
|
|
12
|
-
const table: Readonly<Record<string,
|
|
13
|
-
"linux/x86_64":
|
|
14
|
-
"linux/aarch64":
|
|
15
|
-
"darwin/x86_64":
|
|
16
|
-
"darwin/aarch64":
|
|
17
|
-
"windows/x86_64":
|
|
11
|
+
/** The suffix of commons' pin variables for a platform (by the names `proc.build` gives); undefined where commons pins no download for it. */
|
|
12
|
+
export function pinSuffix(os: string, arch: string): string | undefined {
|
|
13
|
+
const table: Readonly<Record<string, string>> = {
|
|
14
|
+
"linux/x86_64": "X86_64",
|
|
15
|
+
"linux/aarch64": "AARCH64",
|
|
16
|
+
"darwin/x86_64": "MACOS_X64",
|
|
17
|
+
"darwin/aarch64": "MACOS_ARM64",
|
|
18
|
+
"windows/x86_64": "WINDOWS_X64",
|
|
18
19
|
};
|
|
19
20
|
return Object.hasOwn(table, `${os}/${arch}`) ? table[`${os}/${arch}`] : undefined;
|
|
20
21
|
}
|
|
@@ -28,3 +29,47 @@ export function readEnvFile(text: string): ReadonlyMap<string, string> {
|
|
|
28
29
|
}
|
|
29
30
|
return out;
|
|
30
31
|
}
|
|
32
|
+
|
|
33
|
+
/** The formats of what a pinned address gives. */
|
|
34
|
+
export type PinFormat = "zip" | "tar" | "file";
|
|
35
|
+
|
|
36
|
+
/** What a download of a pin on a platform needs. */
|
|
37
|
+
export type PinDownload = {
|
|
38
|
+
readonly version: string;
|
|
39
|
+
readonly url: string;
|
|
40
|
+
readonly sha256: string;
|
|
41
|
+
readonly format: PinFormat;
|
|
42
|
+
/** The folder of the programs inside the unpacked artifact; empty for the root. */
|
|
43
|
+
readonly binPath: string;
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** Why a pin has no download on a platform. */
|
|
47
|
+
export type PinProblem =
|
|
48
|
+
| { readonly kind: "no-version"; readonly key: string }
|
|
49
|
+
| { readonly kind: "not-pinned"; readonly key: string; readonly suffix: string }
|
|
50
|
+
| { readonly kind: "bad-format"; readonly key: string; readonly suffix: string; readonly format: string };
|
|
51
|
+
|
|
52
|
+
/** The sentence a problem is told in. */
|
|
53
|
+
export function describePinProblem(p: PinProblem): string {
|
|
54
|
+
switch (p.kind) {
|
|
55
|
+
case "no-version":
|
|
56
|
+
return `commons pins no ${p.key}`;
|
|
57
|
+
case "not-pinned":
|
|
58
|
+
return `commons pins no download of ${p.key} for ${p.suffix}`;
|
|
59
|
+
case "bad-format":
|
|
60
|
+
return `commons pins ${p.key} for ${p.suffix} as ${JSON.stringify(p.format)}, which is no format (zip, tar, file)`;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The download of the pin `key` (`BUN`) for the platform `suffix` (`X86_64`) as `pins.auto.env` states it, or why it has none. */
|
|
65
|
+
export function pinDownload(env: ReadonlyMap<string, string>, key: string, suffix: string): Result<PinDownload, PinProblem> {
|
|
66
|
+
const version = env.get(`${key}_VERSION`);
|
|
67
|
+
if (version === undefined) return err({ kind: "no-version", key });
|
|
68
|
+
const url = env.get(`${key}_URL_${suffix}`);
|
|
69
|
+
const sha256 = env.get(`${key}_SHA256_${suffix}`);
|
|
70
|
+
const format = env.get(`${key}_FORMAT_${suffix}`);
|
|
71
|
+
const binPath = env.get(`${key}_BINPATH_${suffix}`);
|
|
72
|
+
if (url === undefined || sha256 === undefined || format === undefined || binPath === undefined) return err({ kind: "not-pinned", key, suffix });
|
|
73
|
+
if (format !== "zip" && format !== "tar" && format !== "file") return err({ kind: "bad-format", key, suffix, format });
|
|
74
|
+
return ok({ version, url, sha256, format, binPath });
|
|
75
|
+
}
|
package/src/plan.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The plan of CI (commons 0001-libraries FR-012): the libraries a push or a pull request affects, and for each the cells that the one workflow `ci` runs, so that a change proves what it touches and nothing else.
|
|
3
|
+
*
|
|
4
|
+
* bun commons/libraries/src/plan.ts --base origin/main the plan for what changed since the merge base with origin/main, as JSON
|
|
5
|
+
* bun commons/libraries/src/plan.ts --all every library
|
|
6
|
+
* bun commons/libraries/src/plan.ts --files a.ts,b/c.ts the libraries these files affect
|
|
7
|
+
* bun commons/libraries/src/plan.ts --base REF --github-output "$GITHUB_OUTPUT" the same, written as the outputs of a step: has-linux, linux, has-systems, systems
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* The libraries are those of `affected.ts` (the same code the development loop and every check read), with the reach of `verify`: what a library's `verify` reads, and what depends on it. Each library has a cell on Linux; a
|
|
11
|
+
* library whose record of CI (`LIBRARY_CI`) names Windows or macOS has a cell on each of them too, because it has code of its own for them. A matrix with no cell is not written as a matrix (a workflow cannot run
|
|
12
|
+
* one): `has-linux` and `has-systems` say whether there is one.
|
|
13
|
+
*
|
|
14
|
+
* @limits
|
|
15
|
+
* It decides nothing about a version, a tag or a release; those are the release's. It cannot say what changed where Git cannot: it plans every library then, and says why.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { planOf } from "./plan.ts";
|
|
20
|
+
* planOf([{ name: "net", folder: "commons/net", verify: "bun run verify" }]).systems.include.map((c) => c.os); // ["windows-latest", "macos-latest"]
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* Spec: 0001-libraries FR-012
|
|
24
|
+
*
|
|
25
|
+
* @module
|
|
26
|
+
*/
|
|
27
|
+
import process from "node:process";
|
|
28
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
29
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
30
|
+
import { join } from "@intellectual-frontiers/system/path";
|
|
31
|
+
import { run } from "@intellectual-frontiers/system/proc";
|
|
32
|
+
import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
|
|
33
|
+
import { affectedBy, changedSince, everyLibrary } from "./affected.ts";
|
|
34
|
+
import { type Cell, cellOf, LIBRARY_CI } from "./workflows/definitions.ts";
|
|
35
|
+
|
|
36
|
+
/** A library as the plan reads it. */
|
|
37
|
+
export type Planned = { readonly name: string; readonly folder: string; readonly verify: string };
|
|
38
|
+
|
|
39
|
+
/** The cells of a job: what `strategy.matrix` reads as `{"include": [...]}`. */
|
|
40
|
+
export type Include = { readonly include: readonly Cell[] };
|
|
41
|
+
|
|
42
|
+
/** What CI runs for a change: the cells on Linux, and the cells on the other systems. */
|
|
43
|
+
export type Plan = { readonly linux: Include; readonly systems: Include };
|
|
44
|
+
|
|
45
|
+
/** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
|
|
46
|
+
export function planOf(libs: readonly Planned[], packs: ReadonlySet<string> = new Set()): Plan {
|
|
47
|
+
return {
|
|
48
|
+
linux: { include: libs.map((l) => cellOf(l, undefined, packs.has(l.name))) },
|
|
49
|
+
systems: { include: libs.flatMap((l) => (LIBRARY_CI[l.name]?.systems ?? []).map((os) => cellOf(l, os, packs.has(l.name)))) },
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
|
|
54
|
+
export function exportsLine(packageJson: string): string {
|
|
55
|
+
try {
|
|
56
|
+
const x: unknown = JSON.parse(packageJson);
|
|
57
|
+
const e = typeof x === "object" && x !== null && "exports" in x ? x.exports : undefined;
|
|
58
|
+
const sorted = (v: unknown): unknown =>
|
|
59
|
+
typeof v === "object" && v !== null && !Array.isArray(v)
|
|
60
|
+
? Object.fromEntries(
|
|
61
|
+
Object.entries(v)
|
|
62
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
63
|
+
.map(([k, n]) => [k, sorted(n)]),
|
|
64
|
+
)
|
|
65
|
+
: v;
|
|
66
|
+
return JSON.stringify(sorted(e ?? null));
|
|
67
|
+
} catch {
|
|
68
|
+
return "unreadable";
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
|
|
74
|
+
*/
|
|
75
|
+
export async function packsFor(repo: string, base: string, libs: readonly Planned[]): Promise<ReadonlySet<string>> {
|
|
76
|
+
const all = new Set(libs.map((l) => l.name));
|
|
77
|
+
const mb = await run(["git", "-C", repo, "merge-base", base, "HEAD"]);
|
|
78
|
+
if (mb.code !== 0) return all;
|
|
79
|
+
const packer = await run(["git", "-C", repo, "diff", "--name-only", mb.stdout.trim(), "--", "commons/libraries/src/pack-library.ts"]);
|
|
80
|
+
if (packer.code !== 0 || packer.stdout.trim() !== "") return all;
|
|
81
|
+
const out = new Set<string>();
|
|
82
|
+
for (const l of libs) {
|
|
83
|
+
const before = await run(["git", "-C", repo, "show", `${mb.stdout.trim()}:${l.folder}/package.json`]);
|
|
84
|
+
const now = join(repo, l.folder, "package.json");
|
|
85
|
+
if (before.code !== 0 || !existsSync(now) || exportsLine(before.stdout) !== exportsLine(readTextFileSync(now))) out.add(l.name);
|
|
86
|
+
}
|
|
87
|
+
return out;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
|
|
91
|
+
export function outputsOf(p: Plan): string {
|
|
92
|
+
return [
|
|
93
|
+
`has-linux=${p.linux.include.length > 0}`,
|
|
94
|
+
`linux=${JSON.stringify(p.linux)}`,
|
|
95
|
+
`has-systems=${p.systems.include.length > 0}`,
|
|
96
|
+
`systems=${JSON.stringify(p.systems)}`,
|
|
97
|
+
].join("\n");
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const OPTIONS = {
|
|
101
|
+
base: value({ help: "The revision the change starts at (the merge base with it is compared with the head).", valueName: "REF" }),
|
|
102
|
+
files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
|
|
103
|
+
all: flag({ help: "Every library." }),
|
|
104
|
+
repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
|
|
105
|
+
githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read.", valueName: "FILE" }),
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
/** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
|
|
109
|
+
export async function main(argv: readonly string[]): Promise<number> {
|
|
110
|
+
const parsed = parseArgs(argv, OPTIONS);
|
|
111
|
+
if (parsed.kind === "err") {
|
|
112
|
+
stdio.stderr.writeSync(`${formatUsageError(parsed.error, "plan")}\n`);
|
|
113
|
+
return 2;
|
|
114
|
+
}
|
|
115
|
+
if (parsed.value.kind === "help") {
|
|
116
|
+
stdio.stdout.writeSync(`${helpText("plan", "The libraries a change affects and the cells CI runs for them.", OPTIONS)}\n`);
|
|
117
|
+
return 0;
|
|
118
|
+
}
|
|
119
|
+
const o = parsed.value.options;
|
|
120
|
+
const files = (o.files ?? []).flatMap((f) => f.split(",")).filter((f) => f !== "");
|
|
121
|
+
let libs: readonly Planned[];
|
|
122
|
+
let packs: ReadonlySet<string> = new Set();
|
|
123
|
+
if (o.all) {
|
|
124
|
+
libs = everyLibrary(o.repo);
|
|
125
|
+
packs = new Set(libs.map((l) => l.name));
|
|
126
|
+
} else if (files.length > 0) libs = affectedBy(o.repo, files);
|
|
127
|
+
else if (o.base !== undefined) {
|
|
128
|
+
const changed = await changedSince(o.repo, o.base);
|
|
129
|
+
if (changed === undefined) stdio.stderr.writeSync(`plan: git cannot say what changed since ${o.base}; every library is planned\n`);
|
|
130
|
+
libs = changed === undefined ? everyLibrary(o.repo) : affectedBy(o.repo, changed);
|
|
131
|
+
packs = changed === undefined ? new Set(libs.map((l) => l.name)) : await packsFor(o.repo, o.base, libs);
|
|
132
|
+
} else {
|
|
133
|
+
stdio.stderr.writeSync("plan: give --base REF, --files a,b or --all\n");
|
|
134
|
+
return 2;
|
|
135
|
+
}
|
|
136
|
+
const plan = planOf(libs, packs);
|
|
137
|
+
if (o.githubOutput === undefined) stdio.stdout.writeSync(`${JSON.stringify(plan)}\n`);
|
|
138
|
+
else writeTextFileSync(o.githubOutput, `${outputsOf(plan)}\n`, { append: true });
|
|
139
|
+
stdio.stderr.writeSync(`plan: ${libs.length} libraries: ${libs.map((l) => l.name).join(", ") || "none"}\n`);
|
|
140
|
+
return 0;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
if (import.meta.main) process.exitCode = await main(process.argv.slice(2));
|