@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/LICENSE CHANGED
@@ -1,21 +1,75 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Intellectual Frontiers
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ Required Notice: Copyright Intellectual Frontiers LLC (https://github.com/intellectual-frontiers/.github)
2
+
3
+ # PolyForm Noncommercial License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ 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).
14
+
15
+ ## Distribution License
16
+
17
+ 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).
18
+
19
+ ## Notices
20
+
21
+ 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:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ 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.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ 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.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ 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.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ 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.
52
+
53
+ ## Patent Defense
54
+
55
+ 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.
56
+
57
+ ## Violations
58
+
59
+ 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.
60
+
61
+ ## No Liability
62
+
63
+ ***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.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **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.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
@@ -7,6 +7,10 @@ export type Inputs = {
7
7
  readonly dependsOn: readonly string[];
8
8
  /** Every file of another folder that it reads, from the repository's root, in order. */
9
9
  readonly files: readonly string[];
10
+ /** The libraries whose package its sources import by name: what its types and its tests read, which its scripts do not add. */
11
+ readonly imports: readonly string[];
12
+ /** The paths its types and its tests read: its folder and what its imports reach (no tool its scripts run, no workflow). */
13
+ readonly codePaths: readonly string[];
10
14
  };
11
15
  /** The folders whose change is every library's change: the tools that check a library and the action that installs Bun. */
12
16
  export declare const SHARED: readonly ["commons/tools/**", ".github/actions/**"];
@@ -14,11 +18,20 @@ export declare const SHARED: readonly ["commons/tools/**", ".github/actions/**"]
14
18
  export declare function inputsOf(repo: string, name: string): Inputs;
15
19
  /** Whether a path of the repository is among the paths of an input: `dir/**` is the folder and what is under it, anything else the file. */
16
20
  export declare function matches(paths: readonly string[], file: string): boolean;
21
+ /** Every library of the repository, with its folder. */
22
+ export declare function everyLibrary(repo: string): readonly (Library & {
23
+ readonly folder: string;
24
+ })[];
25
+ /**
26
+ * What a change reaches: `verify`, everything the library's `verify` reads (its scripts' tools, the shared tools, its workflow: what CI runs), or `code`, what its types and its tests read (its folder and the
27
+ * packages its sources import, which is what the development loop runs).
28
+ */
29
+ export type Reach = "verify" | "code";
17
30
  /** The libraries that a list of changed files affects (FR-021): those with a changed file among their inputs, and those that depend on one of these, in order of their names. */
18
- export declare function affectedBy(repo: string, changed: readonly string[]): readonly (Library & {
31
+ export declare function affectedBy(repo: string, changed: readonly string[], reach?: Reach): readonly (Library & {
19
32
  readonly folder: string;
20
33
  })[];
21
- /** The files changed since the merge base of `base` and the head, tracked files of the working tree included; undefined where Git cannot say. */
34
+ /** The files changed since the merge base of `base` and the head, the working tree's tracked and new files included; undefined where Git cannot say. */
22
35
  export declare function changedSince(repo: string, base: string): Promise<readonly string[] | undefined>;
23
36
  /** The matrix a workflow reads: `{"include":[{"name","folder","verify"}]}`. */
24
37
  export declare function matrixOf(libs: readonly (Library & {
package/dist/affected.js CHANGED
@@ -134,8 +134,11 @@ export function inputsOf(repo, name) {
134
134
  const sources = sourcesUnder(root, folder);
135
135
  const texts = sources.map((f) => ({ f, text: readTextFileSync(join(root, f)) }));
136
136
  const entries = new Set();
137
+ const codeEntries = new Set();
137
138
  const whole = new Set();
139
+ const codeWhole = new Set();
138
140
  const dependsOn = new Set();
141
+ const imports = new Set();
139
142
  // a dependency by path: its folder, what the library's sources import from it, and the entries it maps them to
140
143
  for (const [dep, spec] of pkg?.dependencies ?? []) {
141
144
  const m = /^(?:link|file|workspace):(.+)$/.exec(spec);
@@ -146,18 +149,30 @@ export function inputsOf(repo, name) {
146
149
  continue;
147
150
  const depPkg = readPackage(join(root, dir));
148
151
  dependsOn.add(dir.split("/")[1] ?? dir);
149
- const imported = new Set();
150
- for (const { text } of texts)
151
- for (const s of specifiersOf(text))
152
- if (s === dep || s.startsWith(`${dep}/`))
153
- imported.add(s === dep ? "." : `.${s.slice(dep.length)}`);
154
- for (const key of imported) {
155
- const target = depPkg?.exports.get(key);
156
- if (target === undefined)
157
- whole.add(`${dir}/**`);
158
- else
159
- entries.add(posix(join(dir, target)));
160
- }
152
+ const importedBy = (own) => {
153
+ const found = new Set();
154
+ for (const { text } of own)
155
+ for (const s of specifiersOf(text))
156
+ if (s === dep || s.startsWith(`${dep}/`))
157
+ found.add(s === dep ? "." : `.${s.slice(dep.length)}`);
158
+ return found;
159
+ };
160
+ // what its types and tests read is what its own code (`about.ts` and `src/`) imports; its suite and its tools also read the packages their scripts run
161
+ const imported = importedBy(texts);
162
+ const ownCode = importedBy(texts.filter((t) => t.f === `${folder}/about.ts` || t.f.startsWith(`${folder}/src/`)));
163
+ if (ownCode.size > 0 && existsSync(join(root, dir, "library.ts")))
164
+ imports.add(dir.split("/")[1] ?? dir);
165
+ for (const [keys, into, all] of [
166
+ [imported, entries, whole],
167
+ [ownCode, codeEntries, codeWhole],
168
+ ])
169
+ for (const key of keys) {
170
+ const target = depPkg?.exports.get(key);
171
+ if (target === undefined)
172
+ all.add(`${dir}/**`);
173
+ else
174
+ into.add(posix(join(dir, target)));
175
+ }
161
176
  }
162
177
  // a path to another folder in a script of the package: `bun ../libraries/src/check.ts`
163
178
  for (const script of pkg?.scripts ?? [])
@@ -167,28 +182,41 @@ export function inputsOf(repo, name) {
167
182
  entries.add(p);
168
183
  }
169
184
  const files = [...closure(root, [...entries])].filter((f) => !f.startsWith(`${folder}/`)).sort();
170
- const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, `.github/workflows/${name}.auto.yml`])].sort();
185
+ const paths = [`${folder}/**`, ...new Set([...files.map(folderOf), ...whole, ...SHARED, ".github/workflows/ci.auto.yml"])].sort();
171
186
  for (const f of files) {
172
187
  const d = f.split("/")[1];
173
188
  if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts")))
174
189
  dependsOn.add(d);
175
190
  }
176
- return { paths, dependsOn: [...dependsOn].sort(), files };
191
+ const codeFiles = [...closure(root, [...codeEntries])].filter((f) => !f.startsWith(`${folder}/`));
192
+ for (const f of codeFiles) {
193
+ const d = f.split("/")[1];
194
+ if (d !== undefined && d !== name && existsSync(join(root, "commons", d, "library.ts")))
195
+ imports.add(d);
196
+ }
197
+ const codePaths = [`${folder}/**`, ...new Set([...codeFiles.map(folderOf), ...codeWhole])].sort();
198
+ return { paths, dependsOn: [...dependsOn].sort(), files, imports: [...imports].sort(), codePaths };
177
199
  }
178
200
  /** Whether a path of the repository is among the paths of an input: `dir/**` is the folder and what is under it, anything else the file. */
179
201
  export function matches(paths, file) {
180
202
  return paths.some((p) => (p.endsWith("/**") ? file.startsWith(p.slice(0, -2)) : p === file));
181
203
  }
204
+ /** Every library of the repository, with its folder. */
205
+ export function everyLibrary(repo) {
206
+ return readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
207
+ }
182
208
  /** The libraries that a list of changed files affects (FR-021): those with a changed file among their inputs, and those that depend on one of these, in order of their names. */
183
- export function affectedBy(repo, changed) {
209
+ export function affectedBy(repo, changed, reach = "verify") {
184
210
  const root = repo.replace(/[\\/]$/, "");
185
211
  const libs = readLibraries(root).flatMap((f) => ("library" in f ? [f.library] : []));
186
212
  const inputs = new Map(libs.map((l) => [l.name, inputsOf(root, l.name)]));
187
- const hit = new Set(libs.filter((l) => changed.some((c) => matches(inputs.get(l.name)?.paths ?? [], c))).map((l) => l.name));
213
+ const pathsOf = (n) => (reach === "verify" ? inputs.get(n)?.paths : inputs.get(n)?.codePaths) ?? [];
214
+ const depsOf = (n) => (reach === "verify" ? inputs.get(n)?.dependsOn : inputs.get(n)?.imports) ?? [];
215
+ const hit = new Set(libs.filter((l) => changed.some((c) => matches(pathsOf(l.name), c))).map((l) => l.name));
188
216
  for (let grew = true; grew;) {
189
217
  grew = false;
190
218
  for (const l of libs) {
191
- if (!hit.has(l.name) && (inputs.get(l.name)?.dependsOn ?? []).some((d) => hit.has(d))) {
219
+ if (!hit.has(l.name) && depsOf(l.name).some((d) => hit.has(d))) {
192
220
  hit.add(l.name);
193
221
  grew = true;
194
222
  }
@@ -196,7 +224,7 @@ export function affectedBy(repo, changed) {
196
224
  }
197
225
  return libs.filter((l) => hit.has(l.name)).map((l) => ({ ...l, folder: `commons/${l.name}` }));
198
226
  }
199
- /** The files changed since the merge base of `base` and the head, tracked files of the working tree included; undefined where Git cannot say. */
227
+ /** The files changed since the merge base of `base` and the head, the working tree's tracked and new files included; undefined where Git cannot say. */
200
228
  export async function changedSince(repo, base) {
201
229
  const root = resolve(repo);
202
230
  try {
@@ -204,7 +232,10 @@ export async function changedSince(repo, base) {
204
232
  if (mb.code !== 0)
205
233
  return undefined;
206
234
  const d = await run(["git", "-C", root, "diff", "--name-only", mb.stdout.trim()]);
207
- return d.code === 0 ? d.stdout.split("\n").filter((l) => l !== "") : undefined;
235
+ const fresh = await run(["git", "-C", root, "ls-files", "--others", "--exclude-standard"]);
236
+ if (d.code !== 0 || fresh.code !== 0)
237
+ return undefined;
238
+ return [...new Set([...d.stdout.split("\n"), ...fresh.stdout.split("\n")])].filter((l) => l !== "");
208
239
  }
209
240
  catch {
210
241
  return undefined;
@@ -227,7 +258,7 @@ export async function main(argv) {
227
258
  stdio.stdout.writeSync(`${[...i.paths, ...i.files.map((f) => ` ${f}`)].join("\n")}\n`);
228
259
  return 0;
229
260
  }
230
- const everything = readLibraries(repo).flatMap((f) => ("library" in f ? [{ ...f.library, folder: `commons/${f.dir}` }] : []));
261
+ const everything = everyLibrary(repo);
231
262
  const files = arg("--files");
232
263
  const base = arg("--base");
233
264
  if (argv.includes("--all"))
package/dist/dev.d.ts ADDED
@@ -0,0 +1,83 @@
1
+ import { type Result } from "@intellectual-frontiers/core";
2
+ import { type Look } from "@intellectual-frontiers/system/tty";
3
+ import type { Library } from "./libraries.js";
4
+ /** What the loop is asked about: what changed since a revision, a list of files, named libraries or everything. */
5
+ export type Scope = {
6
+ readonly kind: "since";
7
+ readonly base: string;
8
+ } | {
9
+ readonly kind: "files";
10
+ readonly files: readonly string[];
11
+ } | {
12
+ readonly kind: "only";
13
+ readonly names: readonly string[];
14
+ } | {
15
+ readonly kind: "all";
16
+ };
17
+ /** A library of the repository with its folder, as `affected.ts` gives it. */
18
+ export type Lib = Library & {
19
+ readonly folder: string;
20
+ };
21
+ /** How one stage of the loop ended. */
22
+ export type Outcome = {
23
+ readonly kind: "passed";
24
+ readonly detail: string;
25
+ } | {
26
+ readonly kind: "failed";
27
+ readonly detail: string;
28
+ readonly output: readonly string[];
29
+ } | {
30
+ readonly kind: "skipped";
31
+ readonly detail: string;
32
+ };
33
+ /** The counts of one `bun test` run. */
34
+ export type Counts = {
35
+ readonly pass: number;
36
+ readonly skip: number;
37
+ readonly fail: number;
38
+ readonly files: number;
39
+ };
40
+ /** The counts in the end of what `bun test` printed, or undefined where it printed none. */
41
+ export declare function bunCounts(text: string): Counts | undefined;
42
+ /** The lines of `bun test`'s output that say what failed: the failing tests and the error lines above each, in order. */
43
+ export declare function failureLines(text: string): readonly string[];
44
+ /** The first lines of a compiler's output, so a long one does not bury the summary. */
45
+ export declare function head(lines: readonly string[], n: number): readonly string[];
46
+ /** The packages a library declares that neither are libraries of the repository nor are installed at the root: the ones it must install itself. */
47
+ export declare function ownPackages(pkg: Readonly<Record<string, unknown>>, shared: ReadonlySet<string>): readonly string[];
48
+ /** Links the libraries under `commons/node_modules` where they are not linked yet (`link.ts`, which `bun run dev:check` runs before this command can import any of them). */
49
+ export declare function linkLibraries(repo: string): Result<number, string>;
50
+ /** The revision a loop compares with where none is given: `origin/main`, else `main`, else `HEAD` (the working tree alone). */
51
+ export declare function defaultBase(repo: string): Promise<string>;
52
+ /** What a scope affects: the libraries and why, or why it cannot be said. */
53
+ export declare function affectedOf(repo: string, scope: Scope): Promise<Result<{
54
+ readonly libs: readonly Lib[];
55
+ readonly why: string;
56
+ }, string>>;
57
+ /** Runs `job` over `items`, at most `width` at a time, and gives the results in the order of the items. */
58
+ export declare function pool<T, R>(items: readonly T[], width: number, job: (item: T) => Promise<R>): Promise<readonly R[]>;
59
+ /** What the loop needs installed: the root's packages, the links, and the packages of a library that has its own. */
60
+ export declare function prepare(repo: string, libs: readonly Lib[]): Promise<Result<readonly string[], string>>;
61
+ /** TypeScript on the libraries, several at a time. */
62
+ export declare function typeCheck(repo: string, libs: readonly Lib[], width: number): Promise<Outcome>;
63
+ /** The license of the repository and of each library, as the check of `license.ts` finds it: a library with no `LICENSE` fails here, and the sentence says the command that writes it. */
64
+ export declare function licenseStage(repo: string): Promise<Outcome>;
65
+ /** The sum of counts. */
66
+ export declare const addCounts: (a: Counts, b: Counts) => Counts;
67
+ /**
68
+ * The tests of the libraries: one `bun test suite/` process for each library, from its folder as its `verify` runs it, several at a time and the largest suites first. One process for all of them would be fewer, but a
69
+ * test may set what is global to its process (the tracer of a process, a working folder), and what it sets must not reach the tests of another library.
70
+ */
71
+ export declare function runTests(repo: string, libs: readonly Lib[], width: number, bail: boolean): Promise<Outcome>;
72
+ /** The summary the loop prints: one line for what it looked at, one for each stage, and what failed under it. */
73
+ export declare function summaryLines(look: Look, what: {
74
+ readonly why: string;
75
+ readonly libs: readonly string[];
76
+ }, stages: readonly {
77
+ readonly name: string;
78
+ readonly outcome: Outcome;
79
+ }[], notes: readonly string[], took: string): readonly string[];
80
+ /** The root of the repository that holds `from`: the nearest folder above it that has `commons/libraries/library.ts`. */
81
+ export declare function repoRootOf(from: string): string | undefined;
82
+ /** The command line. Returns the exit status: 0 where what is affected passed, 1 where a stage failed, 2 for a command line that does not fit. */
83
+ export declare function main(argv: readonly string[]): Promise<number>;