@intellectual-frontiers/libraries 0.4.1 → 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 (49) hide show
  1. package/dist/affected.d.ts +1 -1
  2. package/dist/dev.js +1 -1
  3. package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  4. package/dist/imports/schema-org.auto.prov.ttl +22 -0
  5. package/dist/install-bun.js +1 -1
  6. package/dist/libraries.d.ts +34 -2
  7. package/dist/libraries.js +70 -9
  8. package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  9. package/dist/link.d.ts +1 -1
  10. package/dist/link.js +4 -4
  11. package/dist/metapackages.d.ts +62 -0
  12. package/dist/metapackages.js +190 -0
  13. package/dist/mod.d.ts +1 -1
  14. package/dist/mod.js +1 -1
  15. package/dist/pack-library.d.ts +7 -0
  16. package/dist/pack-library.js +31 -56
  17. package/dist/pack-metapackage.d.ts +22 -0
  18. package/dist/pack-metapackage.js +147 -0
  19. package/dist/pins.d.ts +1 -1
  20. package/dist/pins.js +1 -1
  21. package/dist/readme.d.ts +13 -1
  22. package/dist/readme.js +42 -4
  23. package/dist/releasing.d.ts +8 -1
  24. package/dist/releasing.js +44 -14
  25. package/dist/workflows/definitions.d.ts +2 -2
  26. package/dist/workflows/definitions.js +31 -113
  27. package/dist/workflows/model.d.ts +2 -0
  28. package/dist/workflows/render.js +2 -0
  29. package/dist/workflows/schema/github-workflow.schema.json +2290 -0
  30. package/package.json +28 -13
  31. package/src/affected.ts +1 -1
  32. package/src/dev.ts +1 -1
  33. package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
  34. package/src/imports/schema-org.auto.prov.ttl +22 -0
  35. package/src/install-bun.ts +1 -1
  36. package/src/libraries.ts +88 -8
  37. package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
  38. package/src/link.ts +4 -4
  39. package/src/metapackages.ts +206 -0
  40. package/src/mod.ts +1 -1
  41. package/src/pack-library.ts +37 -53
  42. package/src/pack-metapackage.ts +137 -0
  43. package/src/pins.ts +1 -1
  44. package/src/readme.ts +46 -4
  45. package/src/releasing.ts +47 -16
  46. package/src/workflows/definitions.ts +34 -131
  47. package/src/workflows/model.ts +2 -0
  48. package/src/workflows/render.ts +1 -0
  49. package/src/workflows/schema/github-workflow.schema.json +2290 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/libraries",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "The libraries of a repository of commons as code: the manifest of a library and the check that it and its folder agree, which libraries a change affects, the typed workflows of GitHub Actions and their generator, the pinned Bun, the packer that builds, inspects and packs a library for npm with its declarations, and the commands that hold a whole repository to Mizan (check, change control, versions, the register and the ontologies).",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "type": "module",
@@ -35,6 +35,11 @@
35
35
  "bun": "./src/dev.ts",
36
36
  "default": "./dist/dev.js"
37
37
  },
38
+ "./family": {
39
+ "types": "./dist/family.d.ts",
40
+ "bun": "./src/family.ts",
41
+ "default": "./dist/family.js"
42
+ },
38
43
  "./generate-ontology": {
39
44
  "types": "./dist/generate-ontology.d.ts",
40
45
  "bun": "./src/generate-ontology.ts",
@@ -60,6 +65,11 @@
60
65
  "bun": "./src/link.ts",
61
66
  "default": "./dist/link.js"
62
67
  },
68
+ "./metapackages": {
69
+ "types": "./dist/metapackages.d.ts",
70
+ "bun": "./src/metapackages.ts",
71
+ "default": "./dist/metapackages.js"
72
+ },
63
73
  "./newer": {
64
74
  "types": "./dist/newer.d.ts",
65
75
  "bun": "./src/newer.ts",
@@ -75,6 +85,11 @@
75
85
  "bun": "./src/pack-library.ts",
76
86
  "default": "./dist/pack-library.js"
77
87
  },
88
+ "./pack-metapackage": {
89
+ "types": "./dist/pack-metapackage.d.ts",
90
+ "bun": "./src/pack-metapackage.ts",
91
+ "default": "./dist/pack-metapackage.js"
92
+ },
78
93
  "./pins": {
79
94
  "types": "./dist/pins.d.ts",
80
95
  "bun": "./src/pins.ts",
@@ -127,18 +142,18 @@
127
142
  }
128
143
  },
129
144
  "dependencies": {
130
- "@intellectual-frontiers/core": "0.1.5",
131
- "@intellectual-frontiers/crypto": "0.1.5",
132
- "@intellectual-frontiers/formats": "0.1.5",
133
- "@intellectual-frontiers/githost": "0.1.3",
134
- "@intellectual-frontiers/kanon": "0.2.1",
135
- "@intellectual-frontiers/mizan": "0.1.2",
136
- "@intellectual-frontiers/net": "0.1.6",
137
- "@intellectual-frontiers/ontology": "0.3.1",
138
- "@intellectual-frontiers/quality": "0.2.1",
139
- "@intellectual-frontiers/rdf": "0.1.5",
140
- "@intellectual-frontiers/system": "0.1.7",
141
- "@intellectual-frontiers/terminal": "0.1.7"
145
+ "@intellectual-frontiers/core": "0.2.0",
146
+ "@intellectual-frontiers/crypto": "0.2.0",
147
+ "@intellectual-frontiers/formats": "0.2.0",
148
+ "@intellectual-frontiers/githost": "0.2.0",
149
+ "@intellectual-frontiers/kanon": "0.3.0",
150
+ "@intellectual-frontiers/mizan": "0.2.0",
151
+ "@intellectual-frontiers/net": "0.2.0",
152
+ "@intellectual-frontiers/ontology": "0.4.0",
153
+ "@intellectual-frontiers/quality": "0.3.0",
154
+ "@intellectual-frontiers/rdf": "0.2.0",
155
+ "@intellectual-frontiers/system": "0.2.0",
156
+ "@intellectual-frontiers/terminal": "0.2.0"
142
157
  },
143
158
  "files": [
144
159
  "dist",
package/src/affected.ts CHANGED
@@ -37,7 +37,7 @@ import { type Library, readLibraries } from "./libraries.ts";
37
37
 
38
38
  /** What a library reads: its folder, the folders and files it takes from others, what it depends on, and the files it imports one by one. */
39
39
  export type Inputs = {
40
- /** The paths of the library's inputs: `commons/<name>/` and each folder (`commons/ts/kernel/**`) or file the library takes from another. */
40
+ /** The paths of the library's inputs: `commons/<name>/` and each folder (`commons/core/src/**`) or file the library takes from another. */
41
41
  readonly paths: readonly string[];
42
42
  /** The folders of commons that the library depends on through its package. */
43
43
  readonly dependsOn: readonly string[];
package/src/dev.ts CHANGED
@@ -11,7 +11,7 @@
11
11
  *
12
12
  * @remarks
13
13
  * Nothing is installed per library. The repository's root installs the packages every library shares (`bun install`, once), the libraries are linked under `commons/node_modules` (a link for each folder whose package
14
- * name is `@intellectual-frontiers/<folder>`, and `@intellectual-frontiers/commons` for `commons/ts`), so that a library that imports another by its package name reads the checkout's source, never a copy from a
14
+ * name is `@intellectual-frontiers/<folder>`), so that a library that imports another by its package name reads the checkout's source, never a copy from a
15
15
  * registry: the `exports` of each package are the sources. A library with a package of its own outside the shared set (a database driver) is installed in its folder, once. The affected libraries are those of
16
16
  * `affected.ts` (the same code the workflow of CI runs); TypeScript 7 checks each library's own `tsconfig.json`, several at a time, and the tests of each run in a `bun test` process of its own, from its folder as `verify` runs them, several at a time.
17
17
  *
@@ -0,0 +1,22 @@
1
+ # AUTO-GENERATED with ../../../ontology/src/standards/nist-sp-800-53/controls.auto.ts by commons/mizan/src/integrations/pure/import-oscal-catalog.ts (commons 0019-mizan-integrations FR-009). Do not edit.
2
+
3
+ @prefix dcterms: <http://purl.org/dc/terms/> .
4
+ @prefix prov: <http://www.w3.org/ns/prov#> .
5
+
6
+ <urn:ifc:mizan:module:nist-sp-800-53> a prov:Entity ;
7
+ dcterms:source "../../../ontology/src/standards/nist-sp-800-53/controls.auto.ts" ;
8
+ prov:wasGeneratedBy <urn:ifc:mizan:import:nist-sp-800-53:64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb> ;
9
+ prov:wasDerivedFrom <urn:sha256:64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb> .
10
+
11
+ <urn:ifc:mizan:import:nist-sp-800-53:64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb> a prov:Activity ;
12
+ prov:used <urn:sha256:64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb> ;
13
+ prov:wasAssociatedWith <urn:ifc:mizan:generator:commons:mizan:src:integrations:pure:import-oscal-catalog.ts> .
14
+
15
+ <urn:ifc:mizan:generator:commons:mizan:src:integrations:pure:import-oscal-catalog.ts> a prov:SoftwareAgent .
16
+
17
+ <urn:sha256:64ca6b4161de51ab6af098a7d101d326f14c95e1abf721396cd8a049e8115eeb> a prov:Entity ;
18
+ dcterms:title "NIST SP 800-53 Rev. 5.2.0 (OSCAL catalog)" ;
19
+ dcterms:publisher "National Institute of Standards and Technology" ;
20
+ dcterms:hasVersion "5.2.0" ;
21
+ dcterms:source <https://raw.githubusercontent.com/usnistgov/oscal-content/f0de6d8d8c059d374f15e0ae07508d82e370fc1d/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json> ;
22
+ dcterms:license <https://spdx.org/licenses/Public domain (a work of the United States Government, 17 U.S.C. 105).html> .
@@ -0,0 +1,22 @@
1
+ # AUTO-GENERATED with ../../../ontology/src/supply-chain/packaging/schema.auto.ts by commons/mizan/src/integrations/pure/import-vocabulary.ts (commons 0019-mizan-integrations FR-009). Do not edit.
2
+
3
+ @prefix dcterms: <http://purl.org/dc/terms/> .
4
+ @prefix prov: <http://www.w3.org/ns/prov#> .
5
+
6
+ <urn:ifc:mizan:module:schema-org> a prov:Entity ;
7
+ dcterms:source "../../../ontology/src/supply-chain/packaging/schema.auto.ts" ;
8
+ prov:wasGeneratedBy <urn:ifc:mizan:import:schema-org:7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f> ;
9
+ prov:wasDerivedFrom <urn:sha256:7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f> .
10
+
11
+ <urn:ifc:mizan:import:schema-org:7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f> a prov:Activity ;
12
+ prov:used <urn:sha256:7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f> ;
13
+ prov:wasAssociatedWith <urn:ifc:mizan:generator:commons:mizan:src:integrations:pure:import-vocabulary.ts> .
14
+
15
+ <urn:ifc:mizan:generator:commons:mizan:src:integrations:pure:import-vocabulary.ts> a prov:SoftwareAgent .
16
+
17
+ <urn:sha256:7f15ca89398c4f235f478a4b3b8d1f975d63c5a860b77c8a8fce01f791b7ae2f> a prov:Entity ;
18
+ dcterms:title "schema.org" ;
19
+ dcterms:publisher "Schema.org Community Group" ;
20
+ dcterms:hasVersion "30.1" ;
21
+ dcterms:source <https://schema.org/version/30.1/schemaorg-current-https.ttl> ;
22
+ dcterms:license <https://spdx.org/licenses/CC-BY-SA-3.0.html> .
@@ -1,6 +1,6 @@
1
1
  /**
2
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
3
+ * 0005-typescript-practice 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
  *
package/src/libraries.ts CHANGED
@@ -39,6 +39,8 @@ import {
39
39
  string,
40
40
  err,
41
41
  ok,
42
+ refine,
43
+ type Brand,
42
44
  type Result,
43
45
  } from "@intellectual-frontiers/core";
44
46
  import { parseSpdxId, type SpdxId } from "./license/standard.ts";
@@ -93,8 +95,52 @@ export type Library = {
93
95
  readonly family?: LibraryFamily;
94
96
  /** 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
97
  readonly license?: SpdxId;
98
+ /** The constants of its sources that say its own version (`ERGONEX_VERSION`), each a file from the library's folder and the name of the constant: the release rewrites them with the version, and a check finds one that disagrees. */
99
+ readonly versionConstants?: readonly VersionConstant[];
100
+ /** The package the library publishes where it is not `@intellectual-frontiers/<name>` (the `data` library publishes `@intellectual-frontiers/arcactl`; commons 0036-distribution FR-009). */
101
+ readonly publishes?: PackageName;
102
+ /** Why the library is kept out of the release: it is verified and packed like any other, and has no release record entry, no tag, no set and no registry (FR-0xx of 0001-libraries). */
103
+ readonly held?: HeldReason;
104
+ /** The set the library is, where it is a metapackage: a folder with no code of its own whose package depends on the libraries of the set at exact versions (commons 0036-distribution FR-005). */
105
+ readonly bundle?: BundleName;
96
106
  };
97
107
 
108
+ /** The reason a library is held out of the release: a non-empty sentence, made only by {@link parseHeldReason}. */
109
+ export type HeldReason = Brand<string, "held reason">;
110
+ const heldDecoder = refine(string, "held reason", (t) => t.trim() !== "" && t.trim() === t && !t.includes("\n"));
111
+
112
+ /** A held reason from text, or why the text is not one. */
113
+ export function parseHeldReason(text: string): Result<HeldReason, string> {
114
+ const r = heldDecoder(text, "held");
115
+ return r.kind === "ok" ? ok(r.value) : err("library.held is one non-empty line that says why the library is kept out of the release");
116
+ }
117
+
118
+ /** The scope of the packages of commons. */
119
+ export const PACKAGE_SCOPE = "@intellectual-frontiers/";
120
+
121
+ /** The sets that a metapackage is: the whole of commons, and the four roles of the libraries; a closed union, and the name of the folder and of the package of each. */
122
+ export const BUNDLES = ["commons", "foundation", "patterns", "programs", "standards"] as const;
123
+ /** The name of a set of libraries a metapackage is. */
124
+ export type BundleName = (typeof BUNDLES)[number];
125
+
126
+ /** The name of a package of commons: `@intellectual-frontiers/` and a name, made only by {@link parsePackageName}. */
127
+ export type PackageName = Brand<string, "package name">;
128
+ const packageNameDecoder = refine(string, "package name", (t) => /^@intellectual-frontiers\/[a-z][a-z0-9-]*$/.test(t));
129
+
130
+ /** A package name of commons from text, or why the text is not one. */
131
+ export function parsePackageName(text: string): Result<PackageName, string> {
132
+ const r = packageNameDecoder(text, "package");
133
+ return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a package of commons (@intellectual-frontiers/ and a name of lower-case letters, digits and hyphens)`);
134
+ }
135
+
136
+ /** The package a library publishes: the one its manifest names in `publishes`, else `@intellectual-frontiers/<name>` (commons 0036-distribution FR-009). */
137
+ export function publishedPackage(l: Pick<Library, "name" | "publishes">): string {
138
+ return l.publishes ?? `${PACKAGE_SCOPE}${l.name}`;
139
+ }
140
+
141
+ /** A constant of a library's sources that holds the library's version: the file (from the library's folder) and the constant's name. */
142
+ export type VersionConstant = { readonly file: string; readonly name: string };
143
+
98
144
  /** 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. */
99
145
  export const KANON_REQUIRED_FROM: LevelKey | undefined = undefined;
100
146
 
@@ -117,11 +163,18 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
117
163
  ? r
118
164
  : err({ kind: "decode", path, expected: "a name of lower-case letters, digits and hyphens", found: describe(input) });
119
165
  };
166
+ const constantName: Decoder<string> = (input, path = "$") => {
167
+ const r = string(input, path);
168
+ if (r.kind === "err") return r;
169
+ return /^[A-Za-z_][A-Za-z0-9_]*$/.test(r.value)
170
+ ? r
171
+ : err({ kind: "decode", path, expected: "the name of a constant: letters, digits and underscores", found: describe(input) });
172
+ };
120
173
  const body = object(
121
174
  { name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
122
- { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }), license: nonEmpty },
175
+ { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }), license: nonEmpty, versionConstants: array(object({ file: nonEmpty, name: constantName })), publishes: nonEmpty, bundle: literal(...BUNDLES), held: string },
123
176
  );
124
- const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family", "license"] as const;
177
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family", "license", "versionConstants", "publishes", "bundle", "held"] as const;
125
178
 
126
179
  /** 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). */
127
180
  export function decodeLibrarySource(source: string): Result<Library, string> {
@@ -139,9 +192,16 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
139
192
  if (r.kind === "err") return err(formatDecodeError(r.error));
140
193
  const v = r.value;
141
194
  const distribution = v.distribution ?? DEFAULT_DISTRIBUTION;
142
- if (distribution.length === 0 || new Set(distribution).size !== distribution.length)
195
+ let held: HeldReason | undefined;
196
+ if (v.held !== undefined) {
197
+ const h = parseHeldReason(v.held);
198
+ if (h.kind === "err") return err(h.error);
199
+ held = h.value;
200
+ if (v.publishes !== undefined || v.bundle !== undefined) return err("library.held is not given with library.publishes or library.bundle: a held library is published nowhere");
201
+ }
202
+ if (held === undefined && (distribution.length === 0 || new Set(distribution).size !== distribution.length))
143
203
  return err("library.distribution lists each registry once and at least one (FR-015)");
144
- if (!distribution.includes("github"))
204
+ if (held === undefined && !distribution.includes("github"))
145
205
  return err(
146
206
  "library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)",
147
207
  );
@@ -163,6 +223,15 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
163
223
  if (l.kind === "err") return err(`library.license: ${l.error}`);
164
224
  license = l.value;
165
225
  }
226
+ let publishes: PackageName | undefined;
227
+ if (v.publishes !== undefined) {
228
+ const p = parsePackageName(v.publishes);
229
+ if (p.kind === "err") return err(`library.publishes: ${p.error}`);
230
+ publishes = p.value;
231
+ }
232
+ if (v.bundle !== undefined && v.bundle !== v.name)
233
+ return err(`library.bundle ${v.bundle} is the set of the metapackage of that name: the folder is named ${v.bundle}, and this one is ${v.name} (0036-distribution FR-005)`);
234
+ if (v.bundle !== undefined && publishes !== undefined) return err("library.bundle and library.publishes are not both given: a metapackage publishes the package of its folder (0036-distribution FR-005)");
166
235
  return ok({
167
236
  name: v.name,
168
237
  level: v.level ?? DEFAULT_LIBRARY_LEVEL,
@@ -175,6 +244,10 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
175
244
  ...(kanon === undefined ? {} : { kanon }),
176
245
  ...(family === undefined ? {} : { family }),
177
246
  ...(license === undefined ? {} : { license }),
247
+ ...(v.versionConstants === undefined ? {} : { versionConstants: v.versionConstants }),
248
+ ...(publishes === undefined ? {} : { publishes }),
249
+ ...(v.bundle === undefined ? {} : { bundle: v.bundle }),
250
+ ...(held === undefined ? {} : { held }),
178
251
  });
179
252
  }
180
253
 
@@ -305,8 +378,10 @@ const list = (items: readonly string[]): string => {
305
378
  export function requirementOf(id: string, l: Library): string {
306
379
  const kit = l.specKit === undefined ? "" : `, its spec kit at \`commons/${l.name}/${l.specKit}\``;
307
380
  const summary = l.summary === undefined ? "" : ` ${l.summary}`;
308
- const where = l.distribution.map((r) => REGISTRY_NAME[r]).join(" and ");
309
- return `- **${id}**: \`commons/${l.name}\` MUST be a library at conformance level ${l.level} (\`${LEVEL_TERM[l.level]}\`): the package \`@intellectual-frontiers/${l.name}\` at version \`${l.version}\`${kit}, exporting ${list(l.exports)}, published to ${where}, proved by \`cd commons/${l.name} && ${l.verify}\`.${summary}`;
381
+ const where = l.held === undefined ? l.distribution.map((r) => REGISTRY_NAME[r]).join(" and ") : `no registry (held out of the release: ${l.held})`;
382
+ const own = l.publishes === undefined ? `@intellectual-frontiers/${l.name}` : l.publishes;
383
+ const sets = l.bundle === undefined ? "" : `, a metapackage with no code of its own (the set ${l.bundle}, 0036-distribution FR-005)`;
384
+ return `- **${id}**: \`commons/${l.name}\` MUST be a library at conformance level ${l.level} (\`${LEVEL_TERM[l.level]}\`): the package \`${own}\`${sets} at version \`${l.version}\`${kit}, exporting ${list(l.exports)}, published to ${where}, proved by \`cd commons/${l.name} && ${l.verify}\`.${summary}`;
310
385
  }
311
386
 
312
387
  /** The row of `enforcement.tsv` of a library's requirement. */
@@ -327,13 +402,18 @@ export function idsIn(spec: string): ReadonlyMap<string, string> {
327
402
  return out;
328
403
  }
329
404
 
330
- /** The id each library has: the one it had, or the next number after the greatest. */
405
+ /**
406
+ * The id each library has: the one it had, or the next number after the greatest. A number belongs to the first library that holds it in the specification: where a second one holds it (two branches each gave the next number to a
407
+ * library, and a merge kept both), the second is given the next number after the greatest, so that the generator makes the section again with one number for each library.
408
+ */
331
409
  export function idsFor(libraries: readonly Library[], had: ReadonlyMap<string, string>): ReadonlyMap<string, string> {
332
410
  const out = new Map<string, string>();
411
+ const first = new Map<string, string>();
412
+ for (const [name, id] of had) if (!first.has(id)) first.set(id, name);
333
413
  let next = Math.max(FIRST_GENERATED - 1, ...[...had.values()].map((id) => Number(id.slice(3)))) + 1;
334
414
  for (const l of libraries) {
335
415
  const id = had.get(l.name);
336
- if (id !== undefined) out.set(l.name, id);
416
+ if (id !== undefined && first.get(id) === l.name) out.set(l.name, id);
337
417
  else out.set(l.name, `FR-${String(next++).padStart(3, "0")}`);
338
418
  }
339
419
  return out;
@@ -0,0 +1,73 @@
1
+ # PolyForm Noncommercial License 1.0.0
2
+
3
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
4
+
5
+ ## Acceptance
6
+
7
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
8
+
9
+ ## Copyright License
10
+
11
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
12
+
13
+ ## Distribution License
14
+
15
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
16
+
17
+ ## Notices
18
+
19
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
20
+
21
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
22
+
23
+ ## Changes and New Works License
24
+
25
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
26
+
27
+ ## Patent License
28
+
29
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
30
+
31
+ ## Noncommercial Purposes
32
+
33
+ Any noncommercial purpose is a permitted purpose.
34
+
35
+ ## Personal Uses
36
+
37
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
38
+
39
+ ## Noncommercial Organizations
40
+
41
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
42
+
43
+ ## Fair Use
44
+
45
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
46
+
47
+ ## No Other Rights
48
+
49
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
50
+
51
+ ## Patent Defense
52
+
53
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
54
+
55
+ ## Violations
56
+
57
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
58
+
59
+ ## No Liability
60
+
61
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
62
+
63
+ ## Definitions
64
+
65
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
66
+
67
+ **You** refers to the individual or entity agreeing to these terms.
68
+
69
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
70
+
71
+ **Your licenses** are all the licenses granted to you for the software under these terms.
72
+
73
+ **Use** means anything you do with the software requiring one of your licenses.
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`).