@intellectual-frontiers/libraries 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/LICENSE +75 -21
  2. package/dist/affected.d.ts +1 -1
  3. package/dist/dev.d.ts +2 -0
  4. package/dist/dev.js +14 -2
  5. package/dist/family.js +1 -0
  6. package/dist/generate-ontology.js +4 -0
  7. package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  8. package/dist/imports/schema-org.auto.prov.ttl +22 -0
  9. package/dist/install-bun.js +19 -14
  10. package/dist/libraries.d.ts +39 -2
  11. package/dist/libraries.js +80 -9
  12. package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  13. package/dist/license/standard.d.ts +46 -0
  14. package/dist/license/standard.js +43 -0
  15. package/dist/license/third-party.d.ts +25 -0
  16. package/dist/license/third-party.js +71 -0
  17. package/dist/license.d.ts +61 -0
  18. package/dist/license.js +204 -0
  19. package/dist/link.d.ts +1 -1
  20. package/dist/link.js +4 -4
  21. package/dist/metapackages.d.ts +62 -0
  22. package/dist/metapackages.js +190 -0
  23. package/dist/mod.d.ts +1 -1
  24. package/dist/mod.js +1 -1
  25. package/dist/pack-library.d.ts +9 -0
  26. package/dist/pack-library.js +46 -58
  27. package/dist/pack-metapackage.d.ts +22 -0
  28. package/dist/pack-metapackage.js +147 -0
  29. package/dist/pins.d.ts +34 -7
  30. package/dist/pins.js +36 -9
  31. package/dist/readme.d.ts +71 -0
  32. package/dist/readme.js +310 -0
  33. package/dist/releasing.d.ts +8 -1
  34. package/dist/releasing.js +44 -14
  35. package/dist/workflows/definitions.d.ts +2 -2
  36. package/dist/workflows/definitions.js +32 -114
  37. package/dist/workflows/model.d.ts +6 -0
  38. package/dist/workflows/render.js +2 -0
  39. package/dist/workflows/schema/github-workflow.schema.json +2290 -0
  40. package/package.json +39 -14
  41. package/src/affected.ts +1 -1
  42. package/src/dev.ts +13 -2
  43. package/src/family.ts +1 -0
  44. package/src/generate-ontology.ts +4 -0
  45. package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  46. package/src/imports/schema-org.auto.prov.ttl +22 -0
  47. package/src/install-bun.ts +16 -13
  48. package/src/libraries.ts +100 -8
  49. package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  50. package/src/license/standard.ts +67 -0
  51. package/src/license/third-party.ts +87 -0
  52. package/src/license.ts +222 -0
  53. package/src/link.ts +4 -4
  54. package/src/metapackages.ts +206 -0
  55. package/src/mod.ts +1 -1
  56. package/src/pack-library.ts +52 -55
  57. package/src/pack-metapackage.ts +137 -0
  58. package/src/pins.ts +55 -10
  59. package/src/readme.ts +320 -0
  60. package/src/releasing.ts +47 -16
  61. package/src/workflows/definitions.ts +36 -133
  62. package/src/workflows/model.ts +6 -0
  63. package/src/workflows/render.ts +1 -0
  64. package/src/workflows/schema/github-workflow.schema.json +2290 -0
@@ -0,0 +1,87 @@
1
+ /**
2
+ * What is really vendored in this repository: the files that are not ours and the license each is under, as data (commons 0035-licensing FR-008). `../license.ts` makes `THIRD_PARTY_NOTICES.md` from it, and its check names an
3
+ * item whose path is gone. Where a license was not checked against its source the item says `unverified: <what to check>` and never a guess.
4
+ *
5
+ * @remarks
6
+ * Packages installed from a registry (TypeScript, fast-check, `@types/node` and the others in `bun.lock`) are not vendored: nothing of them is in this repository, and a package's license is its own. Mermaid is
7
+ * copied into a built site and not into this repository, so its item has no path.
8
+ *
9
+ * Spec: 0001-libraries FR-019
10
+ *
11
+ * @module
12
+ */
13
+
14
+ /** One third-party item: what it is, where it came from, whose it is and the license it is under. */
15
+ export type ThirdPartyItem = {
16
+ /** The path in the repository, or `undefined` for an item that is copied only into a built output. */
17
+ readonly path: string | undefined;
18
+ readonly what: string;
19
+ readonly source: string;
20
+ readonly owner: string;
21
+ readonly license: string;
22
+ /** What was checked, or `unverified: <what to check>`. */
23
+ readonly checked: string;
24
+ };
25
+
26
+ /** The items, in the order the notices list them. */
27
+ export const THIRD_PARTY: readonly ThirdPartyItem[] = [
28
+ {
29
+ path: "commons/libraries/src/workflows/schema/github-workflow.schema.json",
30
+ what: "The JSON Schema of GitHub Actions workflows, the copy fetched on 2026-11-19, which the tests validate the generated workflows against",
31
+ source: "https://json.schemastore.org/github-workflow.json (the SchemaStore project, https://github.com/SchemaStore/schemastore)",
32
+ owner: "The SchemaStore authors",
33
+ license: "Apache-2.0",
34
+ checked:
35
+ "The license is that of the SchemaStore repository (its LICENSE is the Apache License 2.0, read on 2026-11-20). unverified: whether the Apache-2.0 text must travel with this one file, which is named here by its address; ask counsel",
36
+ },
37
+ {
38
+ path: "commons/data/sql/extensions/osquery/schema/osquery-5.24.1.auto.json",
39
+ what: "The tables of osquery 5.24.1 (names, columns, types, descriptions), trimmed to the fields the importer reads",
40
+ source: "https://github.com/osquery/osquery-site, commit 055097f8d8fb45c0c33a83c9ed7c56a7df3d7b5f, path src/data/osquery_schema_versions/5.24.1.json",
41
+ owner: "The osquery authors",
42
+ license: "CC-BY-4.0, as the file's own `source.license` records for the osquery-site documentation data; the osquery project is Apache-2.0 OR GPL-2.0-only",
43
+ checked:
44
+ "Taken from the record in the file itself. unverified: the license file of osquery-site at that commit (the address of a LICENSE file at the root returned 404), so check where the CC-BY-4.0 statement comes from and the attribution it asks for",
45
+ },
46
+ {
47
+ path: "commons/ontology/src/standards/nist-sp-800-53/controls.auto.ts",
48
+ what: "The titles and groups of twelve controls of NIST SP 800-53 Rev. 5.2.0, imported from the OSCAL catalog and held to its SHA-256",
49
+ source: "https://github.com/usnistgov/oscal-content, commit f0de6d8d8c059d374f15e0ae07508d82e370fc1d (import manifest commons/libraries/src/imports/nist-sp-800-53.import.ts)",
50
+ owner: "The National Institute of Standards and Technology",
51
+ license: "Public domain (a work of the United States Government, 17 U.S.C. 105)",
52
+ checked: "Taken from the import manifest, which records it with the SHA-256 of the source.",
53
+ },
54
+ {
55
+ path: "commons/ontology/src/supply-chain/packaging/schema.auto.ts",
56
+ what: "The slice of schema.org 30.1 that the packaging ontology specializes, imported and held to its SHA-256",
57
+ source: "https://schema.org/version/30.1/schemaorg-current-https.ttl (import manifest commons/libraries/src/imports/schema-org.import.ts)",
58
+ owner: "The Schema.org Community Group and contributors",
59
+ license: "CC-BY-SA-3.0",
60
+ checked:
61
+ "Taken from the import manifest. unverified: whether the ShareAlike term of CC-BY-SA-3.0 reaches this generated module and what it asks of the files that use it; ask counsel",
62
+ },
63
+ {
64
+ path: "commons/ontology/src/supply-chain/packaging/managers.ts",
65
+ what: "The table of package managers, seeded from the tables of upt (the families file, `families.ts`, is seeded from the same)",
66
+ source: "https://github.com/sigoden/upt, kept as a fixture in tests/fixtures/upt/",
67
+ owner: "The authors of upt",
68
+ license: "MIT OR Apache-2.0, at the user's option",
69
+ checked: "Taken from the files' own headers and from tests/fixtures/upt/README.md. unverified: the license files of the pinned upt commit, which are not kept in this repository",
70
+ },
71
+ {
72
+ path: "commons/ontology/src/supply-chain/packaging/families.ts",
73
+ what: "The families of package managers, seeded from the tables of upt",
74
+ source: "https://github.com/sigoden/upt, kept as a fixture in tests/fixtures/upt/",
75
+ owner: "The authors of upt",
76
+ license: "MIT OR Apache-2.0, at the user's option",
77
+ checked: "Taken from the file's own header and from tests/fixtures/upt/README.md. unverified: the license files of the pinned upt commit, which are not kept in this repository",
78
+ },
79
+ {
80
+ path: undefined,
81
+ what: "Mermaid 11.17.2, the script the generated documentation site serves on a page with a diagram; it is copied into the built site from the package `mermaid` and is not in this repository",
82
+ source: "https://www.npmjs.com/package/mermaid",
83
+ owner: "Knut Sveidqvist and contributors",
84
+ license: "MIT",
85
+ checked: "The LICENSE of the installed package 11.17.2 was read on 2026-11-20: The MIT License (MIT), Copyright (c) 2014 - 2022 Knut Sveidqvist.",
86
+ },
87
+ ] as const;
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 CHANGED
@@ -6,7 +6,7 @@
6
6
  * bun commons/libraries/src/link.ts link what is not linked, from the repository above this folder (or --repo DIR)
7
7
  *
8
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
9
+ * A folder of `commons/` whose `package.json` is named `@intellectual-frontiers/<name>` is linked as that name (the metapackage `commons/commons` bears `@intellectual-frontiers/commons`). A link
10
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
11
  *
12
12
  * @limits
@@ -15,7 +15,7 @@
15
15
  * @example
16
16
  * ```ts
17
17
  * import { linksOf } from "./link.ts";
18
- * linksOf(".").get("@intellectual-frontiers/commons"); // the path of commons/ts
18
+ * linksOf(".").get("@intellectual-frontiers/commons"); // the path of commons/commons
19
19
  * ```
20
20
  *
21
21
  * Spec: 0001-libraries FR-011
@@ -38,13 +38,13 @@ const nameOf = (file: string): string | undefined => {
38
38
  }
39
39
  };
40
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`. */
41
+ /** The packages of commons by name and the folder of each. */
42
42
  export function linksOf(repo: string): ReadonlyMap<string, string> {
43
43
  const links = new Map<string, string>();
44
44
  const dirs = readdirSync(join(repo, "commons"), { withFileTypes: true })
45
45
  .filter((e) => e.isDirectory() && e.name !== "node_modules")
46
46
  .map((e) => e.name)
47
- .sort((a, b) => (a === "ts" ? -1 : b === "ts" ? 1 : a < b ? -1 : 1));
47
+ .sort((a, b) => (a < b ? -1 : 1));
48
48
  for (const d of dirs) {
49
49
  const name = nameOf(join(repo, "commons", d, "package.json"));
50
50
  if (name !== undefined && name.startsWith(SCOPE) && !links.has(name)) links.set(name, join(repo, "commons", d));
@@ -0,0 +1,206 @@
1
+ /**
2
+ * The metapackages of commons (commons 0036-distribution FR-005 to FR-008): five packages with no code of their own, each a set of libraries at the exact versions of one release. `@intellectual-frontiers/commons` is every
3
+ * consumer-facing library; `foundation`, `patterns`, `programs` and `standards` are the four roles of the libraries. A repository other than `.github` installs commons by installing one of them, or a library, from a registry.
4
+ *
5
+ * @remarks
6
+ * Pure: the libraries as data give the members of a set, the exact dependencies of its package, the file that records them, the `package.json` and the README that are published. The role of a library is read from `ROLE_OF` of
7
+ * `readme.ts`, the one place that says it, and the set of a role is the role's: `foundation`, `pattern` (`patterns`), `program` (`programs`) and `standard` (`standards`). A library is consumer-facing where its distribution
8
+ * names npm and it is not a metapackage and not held back ({@link HELD_BACK}); the package of a member is the package it publishes ({@link publishedPackage}). A member whose role is not known is a problem and never a member
9
+ * of no set. The effects (writing the files, packing) are `pack-metapackage.ts`.
10
+ *
11
+ * @limits
12
+ * It reads no file and knows no registry. It does not know what is published: a release that has not published a member makes the set refer to a version npm does not hold yet, which the release's order prevents.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * import { dependenciesOf } from "./metapackages.ts";
17
+ * dependenciesOf([{ library: "core", package: "@intellectual-frontiers/core", version: "0.1.5" }]); // { "@intellectual-frontiers/core": "0.1.5" }
18
+ * ```
19
+ *
20
+ * Spec: 0001-libraries FR-023
21
+ *
22
+ * @module
23
+ */
24
+ import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
25
+ import { type BundleName, BUNDLES, type Library, publishedPackage } from "./libraries.ts";
26
+ import { DEFAULT_LICENSE } from "./license/standard.ts";
27
+ import { ROLE_OF, type Role } from "./readme.ts";
28
+
29
+ /** The libraries that are not in any set yet, each with why: they declare npm and are not ready to be installed (commons 0036-distribution FR-006). A library leaves this list when its owner releases it. */
30
+ export const HELD_BACK: ReadonlyMap<string, string> = new Map([
31
+ ["archon", "the Archon library is not released yet"],
32
+ ["archon-dialect-apt", "a dialect of Archon, which is not released yet"],
33
+ ["archon-dialect-homebrew", "a dialect of Archon, which is not released yet"],
34
+ ["archon-dialect-mise", "a dialect of Archon, which is not released yet"],
35
+ ["archon-dialect-native-pinned", "a dialect of Archon, which is not released yet"],
36
+ ["archon-dialect-winget", "a dialect of Archon, which is not released yet"],
37
+ ["package-managers", "the kit of the dialects of Archon and Toolchain, which are not released yet"],
38
+ ["toolchain", "the Toolchain library is not released yet"],
39
+ ]);
40
+
41
+ /** The roles' sets: a role is in exactly one. */
42
+ export const BUNDLE_OF_ROLE: Readonly<Record<Role, Exclude<BundleName, "commons">>> = {
43
+ foundation: "foundation",
44
+ pattern: "patterns",
45
+ program: "programs",
46
+ standard: "standards",
47
+ };
48
+
49
+ /** A member of a set: the library, the package it publishes and the version of this release. */
50
+ export type Member = { readonly library: string; readonly package: string; readonly version: string };
51
+
52
+ /** The exact dependencies of a package: the name of each member and its version, nothing else. */
53
+ export type Dependencies = Readonly<Record<string, string>>;
54
+
55
+ /** Whether a library is installed by a set: it names npm, it is no metapackage and it is not held back. */
56
+ export function isConsumerFacing(l: Pick<Library, "name" | "bundle" | "distribution" | "held">): boolean {
57
+ return l.held === undefined && l.bundle === undefined && l.distribution.includes("npm") && !HELD_BACK.has(l.name);
58
+ }
59
+
60
+ /** Whether a set holds a library of this role. */
61
+ function holds(bundle: BundleName, role: Role): boolean {
62
+ switch (bundle) {
63
+ case "commons":
64
+ return true;
65
+ case "foundation":
66
+ case "patterns":
67
+ case "programs":
68
+ case "standards":
69
+ return BUNDLE_OF_ROLE[role] === bundle;
70
+ default:
71
+ return absurd(bundle);
72
+ }
73
+ }
74
+
75
+ /** The members of a set, in the order of their packages' names; the problem where a consumer-facing library has no role in `ROLE_OF`. */
76
+ export function membersOf(bundle: BundleName, libraries: readonly Library[]): Result<readonly Member[], string> {
77
+ const out: Member[] = [];
78
+ for (const l of libraries) {
79
+ if (!isConsumerFacing(l)) continue;
80
+ const role = ROLE_OF.get(l.name);
81
+ if (role === undefined) return err(`commons/${l.name} has no role in ROLE_OF (commons/libraries/src/readme.ts), so no set can hold it`);
82
+ if (holds(bundle, role)) out.push({ library: l.name, package: publishedPackage(l), version: l.version });
83
+ }
84
+ return ok(out.sort((a, b) => (a.package < b.package ? -1 : a.package > b.package ? 1 : 0)));
85
+ }
86
+
87
+ /** The exact dependencies of the package of a set: each member's package at its version, no range. */
88
+ export function dependenciesOf(members: readonly Member[]): Dependencies {
89
+ return Object.fromEntries(members.map((m) => [m.package, m.version]));
90
+ }
91
+
92
+ /** What the generated file of a set holds: the set and its exact dependencies. */
93
+ export function setFileText(bundle: BundleName, members: readonly Member[]): string {
94
+ return `${JSON.stringify({ generated: "bun commons/libraries/src/pack-metapackage.ts; do not edit (commons 0036-distribution FR-007)", set: bundle, dependencies: dependenciesOf(members) }, null, 2)}\n`;
95
+ }
96
+
97
+ /** The generated file of a set, from its folder. */
98
+ export const SET_FILE = "dependencies.auto.json";
99
+
100
+ /** The dependencies a generated file holds, or why its text is not one. */
101
+ export function readSetFile(text: string): Result<Dependencies, string> {
102
+ let json: unknown;
103
+ try {
104
+ json = JSON.parse(text);
105
+ } catch {
106
+ return err(`${SET_FILE} is not JSON`);
107
+ }
108
+ const deps = typeof json === "object" && json !== null && "dependencies" in json ? json.dependencies : undefined;
109
+ if (typeof deps !== "object" || deps === null || Array.isArray(deps)) return err(`${SET_FILE} has no dependencies`);
110
+ const out: Record<string, string> = {};
111
+ for (const [k, v] of Object.entries(deps)) {
112
+ if (typeof v !== "string") return err(`${SET_FILE}: ${k} has no version`);
113
+ out[k] = v;
114
+ }
115
+ return ok(out);
116
+ }
117
+
118
+ /** What a set is for, in words, for its README. */
119
+ const PURPOSE: Readonly<Record<BundleName, string>> = {
120
+ commons: "Every consumer-facing library of Intellectual Frontiers Commons, at the versions of one release.",
121
+ foundation: "The foundation libraries: errors as values and decoders, formats, cryptography, the system, the terminal, telemetry, the network, the test runtime, RDF, the Git host and the lint rules.",
122
+ patterns: "The pattern libraries: the headless program pattern and the layers of Kanon.",
123
+ programs: "The program libraries: the operations program of a repository, workspaces, data, integrations and the rest of the programs.",
124
+ standards: "The standards libraries: Mizan, the ontologies, the quality standards and the standards of integrations.",
125
+ };
126
+
127
+ /** The text of a set's own `description`, which the package carries. */
128
+ export function descriptionOf(bundle: BundleName): string {
129
+ return `${PURPOSE[bundle]} No code of its own: it depends on each library at one exact version.`;
130
+ }
131
+
132
+ /** The scope of the packages. */
133
+ const SCOPE = "@intellectual-frontiers";
134
+
135
+ /** The README of a set's package: what it holds, how to install it from npm and from the GitHub package registry, and how to keep one copy of each library. */
136
+ export function readmeOf(bundle: BundleName, members: readonly Member[]): string {
137
+ const name = `${SCOPE}/${bundle}`;
138
+ const rows = members.map((m) => `| \`${m.package}\` | \`${m.version}\` |`);
139
+ return [
140
+ `# ${name}`,
141
+ "",
142
+ descriptionOf(bundle),
143
+ "",
144
+ "```sh",
145
+ `bun add ${name}@<version> # or: npm install --save-exact ${name}@<version>`,
146
+ "```",
147
+ "",
148
+ `The package has no code of its own. Its dependencies are the libraries below, each at one exact version, so that one version of \`${name}\` is one coherent set. Pin it exactly, and import the libraries by their own names.`,
149
+ "",
150
+ "| Library | Version |",
151
+ "| --- | --- |",
152
+ ...rows,
153
+ "",
154
+ "## One copy of each library",
155
+ "",
156
+ "Where another package of your tree depends on one of these libraries at a range, make the tree hold one copy: add",
157
+ "",
158
+ "```json",
159
+ `{ "overrides": { "${SCOPE}/core": "<the version above>" } }`,
160
+ "```",
161
+ "",
162
+ "to your `package.json` for each library you find twice (`bun pm ls --all`, `npm ls @intellectual-frontiers/core`). `repoctl hygiene` names the library that is installed twice.",
163
+ "",
164
+ "## From the GitHub package registry",
165
+ "",
166
+ "The same package is on the GitHub package registry of the organization. Put the scoped line in `.npmrc` and a token that may read packages in the environment:",
167
+ "",
168
+ "```sh",
169
+ "@intellectual-frontiers:registry=https://npm.pkg.github.com",
170
+ "//npm.pkg.github.com/:_authToken=${ERGONEX_GITHUB_TOKEN}",
171
+ "```",
172
+ "",
173
+ `License: ${DEFAULT_LICENSE}. Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/${bundle}`,
174
+ "",
175
+ ].join("\n");
176
+ }
177
+
178
+ /** The `package.json` that is published for a set: no code, one empty entry, the exact dependencies. */
179
+ export function publishedManifest(bundle: BundleName, version: string, dependencies: Dependencies, license: string): Readonly<Record<string, unknown>> {
180
+ return {
181
+ name: `${SCOPE}/${bundle}`,
182
+ version,
183
+ description: descriptionOf(bundle),
184
+ license,
185
+ type: "module",
186
+ engines: { node: ">=26" },
187
+ sideEffects: false,
188
+ types: "./index.d.ts",
189
+ exports: { ".": { types: "./index.d.ts", default: "./index.js" } },
190
+ dependencies,
191
+ files: ["index.js", "index.d.ts", "README.md", "LICENSE"],
192
+ repository: { type: "git", url: "git+https://github.com/intellectual-frontiers/.github.git", directory: `commons/${bundle}` },
193
+ homepage: `https://github.com/intellectual-frontiers/.github/tree/main/commons/${bundle}`,
194
+ bugs: { url: "https://github.com/intellectual-frontiers/.github/issues" },
195
+ keywords: ["intellectual-frontiers", "commons", bundle],
196
+ publishConfig: { access: "public" },
197
+ };
198
+ }
199
+
200
+ /** The one file of code of a set's package, and its declaration: an empty module, so that the entry imports. */
201
+ export const ENTRY_JS = "export {};\n";
202
+ /** The declaration of {@link ENTRY_JS}. */
203
+ export const ENTRY_DTS = "export {};\n";
204
+
205
+ /** Every set, in the order the README lists them. */
206
+ export const ALL_BUNDLES: readonly BundleName[] = BUNDLES;
package/src/mod.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * What of Mizan is still in this package (commons 0032-lifting-libraries): the commands that need the whole repository. `check.ts` holds a repository's spec kit and ontologies, `versions.ts` and
2
+ * What of Mizan is still in this package (commons 0032-libraries-by-concern): the commands that need the whole repository. `check.ts` holds a repository's spec kit and ontologies, `versions.ts` and
3
3
  * `changes.ts` are the commands of the release check and the change-control check, `libraries.ts` reads the manifests of the libraries, `newer.ts` reports a standard newer than its pin, `generate-ontology.ts` writes the Turtle of the ontologies and
4
4
  * `oscal-register.ts` the register of proofs as OSCAL. The harness, the rules, the levels, the integrations, the change-control and release rules as plugins, and the trace of requirements are the
5
5
  * library `mizan` (`@intellectual-frontiers/mizan`), and the ontologies are the library `ontology` (`@intellectual-frontiers/ontology`).