@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.
Files changed (56) hide show
  1. package/LICENSE +75 -21
  2. package/dist/affected.d.ts +15 -2
  3. package/dist/affected.js +51 -20
  4. package/dist/dev.d.ts +83 -0
  5. package/dist/dev.js +359 -0
  6. package/dist/family.d.ts +58 -0
  7. package/dist/family.js +125 -0
  8. package/dist/generate-ontology.js +4 -0
  9. package/dist/generate-workflows.js +2 -10
  10. package/dist/install-bun.js +19 -14
  11. package/dist/libraries.d.ts +8 -0
  12. package/dist/libraries.js +24 -3
  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 +12 -0
  20. package/dist/link.js +98 -0
  21. package/dist/pack-library.d.ts +2 -0
  22. package/dist/pack-library.js +21 -3
  23. package/dist/pins.d.ts +34 -7
  24. package/dist/pins.js +36 -9
  25. package/dist/plan.d.ts +28 -0
  26. package/dist/plan.js +135 -0
  27. package/dist/readme.d.ts +59 -0
  28. package/dist/readme.js +272 -0
  29. package/dist/releasing.d.ts +176 -0
  30. package/dist/releasing.js +680 -0
  31. package/dist/versions.js +4 -7
  32. package/dist/workflows/definitions.d.ts +33 -30
  33. package/dist/workflows/definitions.js +201 -278
  34. package/dist/workflows/model.d.ts +19 -3
  35. package/dist/workflows/render.js +10 -2
  36. package/package.json +44 -14
  37. package/src/affected.ts +56 -17
  38. package/src/dev.ts +379 -0
  39. package/src/family.ts +144 -0
  40. package/src/generate-ontology.ts +4 -0
  41. package/src/generate-workflows.ts +3 -11
  42. package/src/install-bun.ts +16 -13
  43. package/src/libraries.ts +27 -3
  44. package/src/license/standard.ts +67 -0
  45. package/src/license/third-party.ts +87 -0
  46. package/src/license.ts +222 -0
  47. package/src/link.ts +97 -0
  48. package/src/pack-library.ts +21 -3
  49. package/src/pins.ts +55 -10
  50. package/src/plan.ts +143 -0
  51. package/src/readme.ts +278 -0
  52. package/src/releasing.ts +735 -0
  53. package/src/versions.ts +3 -7
  54. package/src/workflows/definitions.ts +262 -397
  55. package/src/workflows/model.ts +15 -3
  56. package/src/workflows/render.ts +10 -2
package/src/family.ts ADDED
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The families of the libraries of commons and the names held for them (commons 0027-commons-libraries FR-023, FR-024; commons 0033-kanon FR-021, FR-024): what the `family` field of a manifest
3
+ * says, the reservations (names no library may take unless it is of the family they are held for), and the findings of the two sides of a family held together, the host's table and each member's
4
+ * manifest.
5
+ *
6
+ * @remarks
7
+ * Pure: it takes the libraries as data and returns one sentence for each finding. A library names its host and its role (`host`, `dialect` or `plugin`); the host's `kanon` table says what its
8
+ * dialects and plugins are and how their packages are named (`@intellectual-frontiers/kanon`: `family`, `instances`, `plugins`), so the name of a member is checked against the host's rule and
9
+ * never against a rule written here. A reservation is data: an exact name or a prefix, and the host that may hold it. It reserves a name without a folder, so that no empty library is created to hold one.
10
+ *
11
+ * Spec: 0001-libraries FR-016
12
+ *
13
+ * @module
14
+ */
15
+ import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
16
+ import { classify, parsePackageName, type Table } from "@intellectual-frontiers/kanon";
17
+
18
+ /** The roles a library has in a family: a closed union. */
19
+ export const ROLES = ["host", "dialect", "plugin"] as const;
20
+ /** The role of a library in a family. */
21
+ export type Role = (typeof ROLES)[number];
22
+
23
+ /** What a manifest says of its family: the host's library name and its own role. */
24
+ export type LibraryFamily = { readonly host: string; readonly role: Role };
25
+
26
+ /** The scope of the packages of commons. */
27
+ const SCOPE = "@intellectual-frontiers/";
28
+
29
+ /** How a reservation holds names: one exact name, or every name that begins with a prefix. */
30
+ export type Match = { readonly kind: "exact"; readonly name: string } | { readonly kind: "prefix"; readonly prefix: string };
31
+
32
+ /** A held name: what it matches, the host whose family may use it and why it is held. */
33
+ export type Reservation = { readonly match: Match; readonly host: string; readonly reason: string };
34
+
35
+ /** The reason the names of the retired fleet engine are held (intellectual-frontiers/.github#11). */
36
+ const ARCHON = "held for the fleet library and its dialects and plugins, which replace the retired fleet engine (intellectual-frontiers/.github#11)";
37
+
38
+ /** The names held, as data: the check reads them and no folder holds them. */
39
+ export const RESERVED: readonly Reservation[] = [
40
+ { match: { kind: "exact", name: "archon" }, host: "archon", reason: ARCHON },
41
+ { match: { kind: "prefix", prefix: "archon-" }, host: "archon", reason: ARCHON },
42
+ { match: { kind: "exact", name: "signing" }, host: "signing", reason: "held for the signing library of the fleet libraries (intellectual-frontiers/.github#11)" },
43
+ { match: { kind: "exact", name: "gitops" }, host: "gitops", reason: "held for the gitops library of the fleet libraries (intellectual-frontiers/.github#11)" },
44
+ { match: { kind: "exact", name: "estate" }, host: "estate", reason: "held for the estate library of the fleet libraries (intellectual-frontiers/.github#11)" },
45
+ { match: { kind: "exact", name: "toolchain" }, host: "toolchain", reason: "held for the toolchain library of the fleet libraries (intellectual-frontiers/.github#11)" },
46
+ ];
47
+
48
+ /** Whether a library name is one a match holds. */
49
+ export function matches(match: Match, name: string): boolean {
50
+ switch (match.kind) {
51
+ case "exact":
52
+ return name === match.name;
53
+ case "prefix":
54
+ return name.startsWith(match.prefix);
55
+ default:
56
+ return absurd(match);
57
+ }
58
+ }
59
+
60
+ /** The family field of a manifest, from what it says: the host's name and the role, or why it is not one. */
61
+ export function decodeFamily(input: { readonly host: string; readonly role: Role }): Result<LibraryFamily, string> {
62
+ return /^[a-z][a-z0-9-]*$/.test(input.host)
63
+ ? ok({ host: input.host, role: input.role })
64
+ : err(`library.family.host ${JSON.stringify(input.host)} is not a library name`);
65
+ }
66
+
67
+ /** What the check reads of a library: its name, its family and its table. */
68
+ export type Entry = { readonly name: string; readonly family?: LibraryFamily; readonly kanon?: Table };
69
+
70
+ /** The findings of the names held: a library whose name a reservation holds and that is not of the family the name is held for. */
71
+ export function reservationFindings(libraries: readonly Entry[], reserved: readonly Reservation[] = RESERVED): readonly string[] {
72
+ const out: string[] = [];
73
+ for (const l of libraries)
74
+ for (const r of reserved) {
75
+ if (!matches(r.match, l.name)) continue;
76
+ if (l.family?.host !== r.host)
77
+ out.push(`commons/${l.name}: the name is ${r.reason}, so the manifest declares family: { host: "${r.host}", role } (0033-kanon FR-024)`);
78
+ break;
79
+ }
80
+ return out;
81
+ }
82
+
83
+ /** The findings of a family held together: each member's name against the host's rule, each declared member registered, and each registered member declared (0033-kanon FR-021). */
84
+ export function familyFindings(libraries: readonly Entry[]): readonly string[] {
85
+ const out: string[] = [];
86
+ const by = new Map(libraries.map((l) => [l.name, l]));
87
+ for (const l of libraries) {
88
+ const f = l.family;
89
+ if (f === undefined) {
90
+ for (const h of libraries) {
91
+ const rule = h.kanon?.family;
92
+ const pkg = parsePackageName(`${SCOPE}${l.name}`);
93
+ if (rule !== undefined && h.kanon !== undefined && pkg.kind === "ok" && h.name !== l.name) {
94
+ const member = classify(rule, h.kanon.package, pkg.value);
95
+ if (member !== undefined && member.kind !== "host")
96
+ out.push(`commons/${l.name}: the name is a ${member.kind} of ${h.name} by its family rule, and the manifest declares no family (0033-kanon FR-021)`);
97
+ }
98
+ }
99
+ continue;
100
+ }
101
+ switch (f.role) {
102
+ case "host":
103
+ if (l.name !== f.host) out.push(`commons/${l.name}: it declares itself the host of the family ${f.host}, and a host is named as its family (0033-kanon FR-021)`);
104
+ break;
105
+ case "dialect":
106
+ case "plugin": {
107
+ const host = by.get(f.host);
108
+ if (host === undefined || host.family?.role !== "host" || host.kanon === undefined) {
109
+ out.push(`commons/${l.name}: its family host ${f.host} is not a library that declares family role host and a kanon table (0033-kanon FR-021)`);
110
+ break;
111
+ }
112
+ const rule = host.kanon.family;
113
+ const pkg = parsePackageName(`${SCOPE}${l.name}`);
114
+ const member = rule === undefined || pkg.kind === "err" ? undefined : classify(rule, host.kanon.package, pkg.value);
115
+ if (member === undefined || member.kind !== f.role)
116
+ out.push(`commons/${l.name}: the family rule of ${f.host} does not read the name as a ${f.role} (0033-kanon FR-021)`);
117
+ const declared =
118
+ f.role === "dialect"
119
+ ? host.kanon.instances.some((i) => i.kind === "package" && i.package === `${SCOPE}${l.name}`)
120
+ : host.kanon.plugins.some((p) => p.package === `${SCOPE}${l.name}`);
121
+ if (!declared) out.push(`commons/${l.name}: the kanon table of ${f.host} does not declare it as a ${f.role} (0033-kanon FR-020)`);
122
+ if (l.kanon === undefined || l.kanon.extends !== host.kanon.package)
123
+ out.push(`commons/${l.name}: a ${f.role} of ${f.host} declares a kanon table with extends: "${host.kanon.package}" (0033-kanon FR-020)`);
124
+ break;
125
+ }
126
+ default:
127
+ return absurd(f.role);
128
+ }
129
+ }
130
+ for (const h of libraries) {
131
+ if (h.kanon === undefined) continue;
132
+ const members = [
133
+ ...h.kanon.instances.flatMap((i) => (i.kind === "package" ? [{ role: "dialect" as const, pkg: i.package }] : [])),
134
+ ...h.kanon.plugins.map((p) => ({ role: "plugin" as const, pkg: p.package })),
135
+ ];
136
+ for (const m of members) {
137
+ const name = m.pkg.slice(SCOPE.length);
138
+ const l = by.get(name);
139
+ if (l === undefined || l.family?.host !== h.name || l.family.role !== m.role)
140
+ out.push(`commons/${h.name}: its kanon table declares ${m.pkg} as a ${m.role}, and no library of that name declares family: { host: "${h.name}", role: "${m.role}" } (0033-kanon FR-021)`);
141
+ }
142
+ }
143
+ return out;
144
+ }
@@ -75,6 +75,8 @@ export const MIZAN: OntologyPublication = {
75
75
  ["dcterms", "http://purl.org/dc/terms/"],
76
76
  ["pm", "https://www.intellectualfrontiers.com/ontology/packaging#"],
77
77
  ["schema", "https://schema.org/"],
78
+ ["dcat", "http://www.w3.org/ns/dcat#"],
79
+ ["purl", "https://github.com/package-url/purl-spec#"],
78
80
  ],
79
81
  files,
80
82
  ontology: mizanOntology,
@@ -97,6 +99,8 @@ export const MIZAN: OntologyPublication = {
97
99
  dcterms: "http://purl.org/dc/terms/",
98
100
  pm: "https://www.intellectualfrontiers.com/ontology/packaging#",
99
101
  schema: "https://schema.org/",
102
+ dcat: "http://www.w3.org/ns/dcat#",
103
+ purl: "https://github.com/package-url/purl-spec#",
100
104
  },
101
105
  viewTitle: "Mizan: the shared ontology",
102
106
  license: CC0,
@@ -19,10 +19,9 @@
19
19
  * @module
20
20
  */
21
21
  import process from "node:process";
22
- import { ACTIONS, type LibraryFacts, workflows } from "./workflows/definitions.ts";
22
+ import { ACTIONS, workflows } from "./workflows/definitions.ts";
23
23
  import { validateAction, validateWorkflow } from "./workflows/model.ts";
24
24
  import { renderAction, renderWorkflow } from "./workflows/render.ts";
25
- import { inputsOf } from "./affected.ts";
26
25
  import { readLibraries } from "./libraries.ts";
27
26
  import { existsSync, readDirSync, readTextFileSync, writeTextFileSync, mkdirSync } from "@intellectual-frontiers/system/fs";
28
27
  import { stdio } from "@intellectual-frontiers/system";
@@ -34,24 +33,17 @@ const FOLDER = ".github/workflows";
34
33
  export function outputs(repo: string): { readonly files: ReadonlyMap<string, string>; readonly problems: readonly string[] } {
35
34
  const root = repo.replace(/[\\/]$/, "");
36
35
  const problems: string[] = [];
37
- const libraries: LibraryFacts[] = [];
38
36
  for (const f of readLibraries(root)) {
39
37
  if ("problem" in f) problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
40
38
  else {
41
39
  if (f.library.distribution.includes("npm") && !existsSync(`${root}/commons/${f.library.name}/tools/pack.ts`))
42
40
  problems.push(
43
- `commons/${f.library.name} is published to npm and has no tools/pack.ts, which its publish workflow runs (0030-generated-workflows FR-009)`,
41
+ `commons/${f.library.name} is published to npm and has no tools/pack.ts, which the release workflow runs (0030-generated-workflows FR-009)`,
44
42
  );
45
- libraries.push({
46
- name: f.library.name,
47
- verify: f.library.verify,
48
- paths: inputsOf(root, f.library.name).paths,
49
- distribution: f.library.distribution,
50
- });
51
43
  }
52
44
  }
53
45
  const files = new Map<string, string>();
54
- for (const w of workflows(libraries)) {
46
+ for (const w of workflows()) {
55
47
  problems.push(...validateWorkflow(w));
56
48
  files.set(`${FOLDER}/${w.file}.auto.yml`, renderWorkflow(w));
57
49
  }
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Bun at the version commons pins (`BUN_VERSION` and its SHA-256 per platform in `commons/generated/pins.auto.env`, commons
3
- * 0005-typescript-runtime FR-026), fetched from Bun's release with retries, kept only where its SHA-256 is the pinned one, unpacked by the
2
+ * Bun at the version commons pins (its version, address, SHA-256, format and folder per platform in `commons/generated/pins.auto.env`, commons
3
+ * 0005-typescript-runtime FR-026, 0002-packaging FR-019), fetched from that address with retries, kept only where its SHA-256 is the pinned one, unpacked by the
4
4
  * kernel's own zip reader and put in a folder; nothing but IFC TypeScript itself, so it runs on Node 26 (or Bun) on Linux, macOS
5
5
  * and Windows with no shell, no Python and no unzip. CI's `.github/actions/bun` runs it.
6
6
  *
@@ -17,7 +17,7 @@ import { chmod, ensureDir, readFile, readTextFile, writeFile, writeTextFile } fr
17
17
  import { downloadVerified, Retries } from "@intellectual-frontiers/net/net";
18
18
  import { dirname, fromFileUrl, join, resolve } from "@intellectual-frontiers/system/path";
19
19
  import { args, build, env, exit } from "@intellectual-frontiers/system/proc";
20
- import { bunTarget, readEnvFile } from "./pins.ts";
20
+ import { describePinProblem, pinDownload, pinSuffix, readEnvFile } from "./pins.ts";
21
21
 
22
22
  /** Stop with a message and status 1. */
23
23
  function stop(message: string): never {
@@ -30,21 +30,24 @@ const given = args[0];
30
30
  if (given === undefined) stop("give the folder to put Bun in");
31
31
  const dest = resolve(given);
32
32
  const pins = readEnvFile(await readTextFile(join(ROOT, "commons", "generated", "pins.auto.env")));
33
- const platform = bunTarget(build.os, build.arch);
34
- if (platform === undefined) stop(`Bun has no build for ${build.os} on ${build.arch}`);
35
- const version = pins.get("BUN_VERSION");
36
- const sum = sha256Of(pins.get(`BUN_SHA256_${platform.key}`) ?? "");
37
- if (version === undefined || sum === undefined) stop(`commons pins no Bun for ${platform.key}`);
33
+ const suffix = pinSuffix(build.os, build.arch);
34
+ if (suffix === undefined) stop(`Bun has no build for ${build.os} on ${build.arch}`);
35
+ const pin = pinDownload(pins, "BUN", suffix);
36
+ if (pin.kind === "err") stop(describePinProblem(pin.error));
37
+ const download = pin.value;
38
+ if (download.format !== "zip") stop(`commons pins Bun as ${download.format}, and this installer unpacks a zip`);
39
+ const sum = sha256Of(download.sha256);
40
+ if (sum === undefined) stop(`commons pins no SHA-256 of Bun for ${suffix}`);
38
41
  const retries = new Retries({ tries: 5, base: 2, cap: 30 }, (line) => console.error(line));
39
- const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/bun-${platform.target}.zip`;
40
- const zip = await downloadVerified(retries, url, sum, join(dest, "cache"));
42
+ const zip = await downloadVerified(retries, download.url, sum, join(dest, "cache"));
41
43
  if (zip.kind === "err") stop(zip.error);
42
44
  const files = await unzip(await readFile(zip.value));
43
45
  if (files.kind === "err") stop(formatArchiveError(files.error));
44
46
  const exe = build.os === "windows" ? "bun.exe" : "bun";
45
- const bytes = files.value.get(`bun-${platform.target}/${exe}`);
46
- if (bytes === undefined) stop(`the zip holds no bun-${platform.target}/${exe}`);
47
- const bin = join(dest, `bun-${version}`);
47
+ const inside = download.binPath === "" ? exe : `${download.binPath}/${exe}`;
48
+ const bytes = files.value.get(inside);
49
+ if (bytes === undefined) stop(`the zip holds no ${inside}`);
50
+ const bin = join(dest, `bun-${download.version}`);
48
51
  await ensureDir(bin);
49
52
  await writeFile(join(bin, exe), bytes);
50
53
  await chmod(join(bin, exe), 0o755);
package/src/libraries.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  *
10
10
  * @remarks
11
11
  * A manifest declares the library's `name` (its folder), its conformance `level` (`L1` where it declares none, 0028-conformance-levels), the path of its spec kit, its `verify` command, its
12
- * `version`, its `exports` (the keys of the package's `exports`) and its `distribution` (the registries it is published to: `github`, the default, and `npm` as well where a decision about that package has made it so; FR-015 to FR-018). The section "The libraries" of the specification is between the markers `<!-- libraries:begin -->` and `<!-- libraries:end -->`,
12
+ * `version`, its `exports` (the keys of the package's `exports`) its `family` (a host and a role in a family of libraries, FR-023) and its `distribution` (the registries it is published to: `github`, the default, and `npm` as well where a decision about that package has made it so; FR-015 to FR-018). The section "The libraries" of the specification is between the markers `<!-- libraries:begin -->` and `<!-- libraries:end -->`,
13
13
  * one requirement for each library numbered from FR-101, an id kept for the life of the library; the rows of those requirements are in `enforcement.tsv`. Adding a library is adding a folder with a manifest and
14
14
  * running this command.
15
15
  *
@@ -41,12 +41,14 @@ import {
41
41
  ok,
42
42
  type Result,
43
43
  } from "@intellectual-frontiers/core";
44
+ import { parseSpdxId, type SpdxId } from "./license/standard.ts";
44
45
  import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
45
46
  import { decodeTable, type Table } from "@intellectual-frontiers/kanon";
46
47
  import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
47
48
  import { stdio } from "@intellectual-frontiers/system";
48
49
  import { spawn } from "@intellectual-frontiers/system/proc";
49
50
  import { DEFAULT_LIBRARY_LEVEL, LEVELS, type LevelKey, rankOf } from "@intellectual-frontiers/mizan/levels";
51
+ import { decodeFamily, familyFindings, type LibraryFamily, reservationFindings, ROLES } from "./family.ts";
50
52
 
51
53
  /** The name of a library's manifest in its folder. */
52
54
  export const LIBRARY_FILE = "library.ts";
@@ -57,6 +59,7 @@ export const LIBRARIES_SPEC = "0027-commons-libraries";
57
59
  export const FIRST_GENERATED = 101;
58
60
  /** The marker that opens the generated section, and the one that closes it. */
59
61
  export const BEGIN = "<!-- libraries:begin -->";
62
+ /** The marker that ends the generated section of the libraries in a document. */
60
63
  export const END = "<!-- libraries:end -->";
61
64
 
62
65
  /** Where the generated section begins and ends: the markers on lines of their own (a requirement may name them in its text). */
@@ -86,6 +89,10 @@ export type Library = {
86
89
  readonly distribution: readonly Registry[];
87
90
  /** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
88
91
  readonly kanon?: Table;
92
+ /** Its host and its role where it is of a family (a host, a dialect of it or a plugin of it; 0033-kanon FR-021, 0027-commons-libraries FR-023). */
93
+ readonly family?: LibraryFamily;
94
+ /** The license its `LICENSE` and its packed `package.json` carry, where it is not the default of the repository (`license/standard.ts`; commons 0035-licensing FR-003). */
95
+ readonly license?: SpdxId;
89
96
  };
90
97
 
91
98
  /** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
@@ -93,6 +100,7 @@ export const KANON_REQUIRED_FROM: LevelKey | undefined = undefined;
93
100
 
94
101
  /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
95
102
  export const REGISTRIES = ["github", "npm"] as const;
103
+ /** A registry a library is distributed to: github or npm. */
96
104
  export type Registry = (typeof REGISTRIES)[number];
97
105
  /** Where a manifest that declares no distribution is published. */
98
106
  export const DEFAULT_DISTRIBUTION: readonly Registry[] = ["github"];
@@ -111,9 +119,9 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
111
119
  };
112
120
  const body = object(
113
121
  { name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
114
- { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue },
122
+ { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }), license: nonEmpty },
115
123
  );
116
- const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"] as const;
124
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family", "license"] as const;
117
125
 
118
126
  /** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
119
127
  export function decodeLibrarySource(source: string): Result<Library, string> {
@@ -143,6 +151,18 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
143
151
  if (t.kind === "err") return err(`library.${t.error} (0033-kanon FR-010)`);
144
152
  kanon = t.value;
145
153
  }
154
+ let family: LibraryFamily | undefined;
155
+ if (v.family !== undefined) {
156
+ const f = decodeFamily(v.family);
157
+ if (f.kind === "err") return f;
158
+ family = f.value;
159
+ }
160
+ let license: SpdxId | undefined;
161
+ if (v.license !== undefined) {
162
+ const l = parseSpdxId(v.license);
163
+ if (l.kind === "err") return err(`library.license: ${l.error}`);
164
+ license = l.value;
165
+ }
146
166
  return ok({
147
167
  name: v.name,
148
168
  level: v.level ?? DEFAULT_LIBRARY_LEVEL,
@@ -153,6 +173,8 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
153
173
  ...(v.summary === undefined ? {} : { summary: v.summary }),
154
174
  distribution,
155
175
  ...(kanon === undefined ? {} : { kanon }),
176
+ ...(family === undefined ? {} : { family }),
177
+ ...(license === undefined ? {} : { license }),
156
178
  });
157
179
  }
158
180
 
@@ -252,6 +274,8 @@ export function manifestFindings(repo: string): readonly string[] {
252
274
  if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
253
275
  found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
254
276
  }
277
+ const known = have.flatMap((f) => ("library" in f ? [f.library] : []));
278
+ found.push(...reservationFindings(known), ...familyFindings(known));
255
279
  return found;
256
280
  }
257
281
 
@@ -0,0 +1,67 @@
1
+ /**
2
+ * The license of this repository as data: the one license every library and every part of the repository is under, the one place its identifier is written, and the standard its text is taken from
3
+ * (commons 0035-licensing FR-001 to FR-004, 0018-standards-first FR-006 and FR-007). The text is the official PolyForm Noncommercial License 1.0.0, copied byte for byte into
4
+ * `PolyForm-Noncommercial-1.0.0.md` beside this file from the tag `1.0.0` of the official repository, and held to the SHA-256 recorded here.
5
+ *
6
+ * @remarks
7
+ * Read as data by `../license.ts` (which writes and checks every `LICENSE`), by the packer (the `license` of a package) and by the decoder of the manifest (its optional `license`). The identifier is a closed union:
8
+ * a license is added to {@link SPDX_IDS} together with its text, never as a free string.
9
+ *
10
+ * Spec: 0001-libraries FR-019
11
+ *
12
+ * @module
13
+ */
14
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
15
+
16
+ /** The SPDX identifiers of the licenses this repository can carry: each has its official text in this folder. */
17
+ export const SPDX_IDS = ["PolyForm-Noncommercial-1.0.0"] as const;
18
+ /** An SPDX license identifier of {@link SPDX_IDS}. */
19
+ export type SpdxId = (typeof SPDX_IDS)[number];
20
+
21
+ /** The license of every library and of the repository, unless a manifest's `license` says another of {@link SPDX_IDS}. */
22
+ export const DEFAULT_LICENSE: SpdxId = "PolyForm-Noncommercial-1.0.0";
23
+
24
+ /** An SPDX identifier from text, or why the text is none of the licenses this repository can carry. */
25
+ export function parseSpdxId(text: string): Result<SpdxId, string> {
26
+ const found = SPDX_IDS.find((id) => id === text);
27
+ return found === undefined ? err(`${JSON.stringify(text)} is not a license of this repository (${SPDX_IDS.join(", ")})`) : ok(found);
28
+ }
29
+
30
+ /** A standard imported as data (0018-standards-first FR-006): its issuer, name, version, location, license and the SHA-256 of what was imported. */
31
+ export type Standard = {
32
+ readonly id: string;
33
+ readonly issuer: string;
34
+ readonly name: string;
35
+ readonly version: string;
36
+ /** Where the imported text is, at the tag that is pinned. */
37
+ readonly location: string;
38
+ /** What the text may be copied under (an SPDX identifier where there is one). */
39
+ readonly license: string;
40
+ readonly redistributable: boolean;
41
+ /** The SHA-256 of the file in this folder, line ends as they are (they are `\n`). */
42
+ readonly sha256: string;
43
+ /** The file of this folder that holds the text. */
44
+ readonly file: string;
45
+ };
46
+
47
+ /** The official text of each license, as a standard of 0018-standards-first. */
48
+ export const LICENSE_STANDARDS: Readonly<Record<SpdxId, Standard>> = {
49
+ "PolyForm-Noncommercial-1.0.0": {
50
+ id: "polyform-noncommercial-1.0.0",
51
+ issuer: "The PolyForm Project",
52
+ name: "PolyForm Noncommercial License 1.0.0",
53
+ version: "1.0.0",
54
+ location: "https://raw.githubusercontent.com/polyformproject/polyform-licenses/1.0.0/PolyForm-Noncommercial-1.0.0.md",
55
+ license: "The terms of LICENSE.md of polyformproject/polyform-licenses at tag 1.0.0: a PolyForm license is copied as it is, and a change removes the name PolyForm",
56
+ redistributable: true,
57
+ sha256: "c0ea4a896d2c8c394b29f9427589996db826cd501c512279ff0ed3ef48fabbe5",
58
+ file: "PolyForm-Noncommercial-1.0.0.md",
59
+ },
60
+ };
61
+
62
+ /** The licensor named in the `Required Notice:` line of every `LICENSE` and in `NOTICE`. */
63
+ export const LICENSOR = "Intellectual Frontiers LLC";
64
+ /** The repository the `Required Notice:` line names. */
65
+ export const REPOSITORY_URL = "https://github.com/intellectual-frontiers/.github";
66
+ /** Where a commercial license is asked for. */
67
+ export const COMMERCIAL_ISSUES_URL = "https://github.com/intellectual-frontiers/.github/issues";
@@ -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;