@intellectual-frontiers/libraries 0.2.1 → 0.4.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.
- package/dist/affected.d.ts +15 -2
- package/dist/affected.js +51 -20
- package/dist/dev.d.ts +81 -0
- package/dist/dev.js +347 -0
- package/dist/family.d.ts +58 -0
- package/dist/family.js +124 -0
- package/dist/generate-workflows.js +2 -10
- package/dist/libraries.d.ts +3 -0
- package/dist/libraries.js +14 -3
- package/dist/link.d.ts +12 -0
- package/dist/link.js +98 -0
- package/dist/pack-library.js +6 -1
- package/dist/plan.d.ts +28 -0
- package/dist/plan.js +135 -0
- package/dist/releasing.d.ts +176 -0
- package/dist/releasing.js +680 -0
- package/dist/versions.js +4 -7
- package/dist/workflows/definitions.d.ts +33 -30
- package/dist/workflows/definitions.js +200 -277
- package/dist/workflows/model.d.ts +15 -3
- package/dist/workflows/render.js +10 -2
- package/package.json +23 -3
- package/src/affected.ts +56 -17
- package/src/dev.ts +368 -0
- package/src/family.ts +143 -0
- package/src/generate-workflows.ts +3 -11
- package/src/libraries.ts +15 -3
- package/src/link.ts +97 -0
- package/src/pack-library.ts +6 -1
- package/src/plan.ts +143 -0
- package/src/releasing.ts +735 -0
- package/src/versions.ts +3 -7
- package/src/workflows/definitions.ts +260 -395
- package/src/workflows/model.ts +11 -3
- package/src/workflows/render.ts +10 -2
package/src/family.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
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
|
+
];
|
|
46
|
+
|
|
47
|
+
/** Whether a library name is one a match holds. */
|
|
48
|
+
export function matches(match: Match, name: string): boolean {
|
|
49
|
+
switch (match.kind) {
|
|
50
|
+
case "exact":
|
|
51
|
+
return name === match.name;
|
|
52
|
+
case "prefix":
|
|
53
|
+
return name.startsWith(match.prefix);
|
|
54
|
+
default:
|
|
55
|
+
return absurd(match);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** The family field of a manifest, from what it says: the host's name and the role, or why it is not one. */
|
|
60
|
+
export function decodeFamily(input: { readonly host: string; readonly role: Role }): Result<LibraryFamily, string> {
|
|
61
|
+
return /^[a-z][a-z0-9-]*$/.test(input.host)
|
|
62
|
+
? ok({ host: input.host, role: input.role })
|
|
63
|
+
: err(`library.family.host ${JSON.stringify(input.host)} is not a library name`);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** What the check reads of a library: its name, its family and its table. */
|
|
67
|
+
export type Entry = { readonly name: string; readonly family?: LibraryFamily; readonly kanon?: Table };
|
|
68
|
+
|
|
69
|
+
/** 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. */
|
|
70
|
+
export function reservationFindings(libraries: readonly Entry[], reserved: readonly Reservation[] = RESERVED): readonly string[] {
|
|
71
|
+
const out: string[] = [];
|
|
72
|
+
for (const l of libraries)
|
|
73
|
+
for (const r of reserved) {
|
|
74
|
+
if (!matches(r.match, l.name)) continue;
|
|
75
|
+
if (l.family?.host !== r.host)
|
|
76
|
+
out.push(`commons/${l.name}: the name is ${r.reason}, so the manifest declares family: { host: "${r.host}", role } (0033-kanon FR-024)`);
|
|
77
|
+
break;
|
|
78
|
+
}
|
|
79
|
+
return out;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** 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). */
|
|
83
|
+
export function familyFindings(libraries: readonly Entry[]): readonly string[] {
|
|
84
|
+
const out: string[] = [];
|
|
85
|
+
const by = new Map(libraries.map((l) => [l.name, l]));
|
|
86
|
+
for (const l of libraries) {
|
|
87
|
+
const f = l.family;
|
|
88
|
+
if (f === undefined) {
|
|
89
|
+
for (const h of libraries) {
|
|
90
|
+
const rule = h.kanon?.family;
|
|
91
|
+
const pkg = parsePackageName(`${SCOPE}${l.name}`);
|
|
92
|
+
if (rule !== undefined && h.kanon !== undefined && pkg.kind === "ok" && h.name !== l.name) {
|
|
93
|
+
const member = classify(rule, h.kanon.package, pkg.value);
|
|
94
|
+
if (member !== undefined && member.kind !== "host")
|
|
95
|
+
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)`);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
switch (f.role) {
|
|
101
|
+
case "host":
|
|
102
|
+
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)`);
|
|
103
|
+
break;
|
|
104
|
+
case "dialect":
|
|
105
|
+
case "plugin": {
|
|
106
|
+
const host = by.get(f.host);
|
|
107
|
+
if (host === undefined || host.family?.role !== "host" || host.kanon === undefined) {
|
|
108
|
+
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)`);
|
|
109
|
+
break;
|
|
110
|
+
}
|
|
111
|
+
const rule = host.kanon.family;
|
|
112
|
+
const pkg = parsePackageName(`${SCOPE}${l.name}`);
|
|
113
|
+
const member = rule === undefined || pkg.kind === "err" ? undefined : classify(rule, host.kanon.package, pkg.value);
|
|
114
|
+
if (member === undefined || member.kind !== f.role)
|
|
115
|
+
out.push(`commons/${l.name}: the family rule of ${f.host} does not read the name as a ${f.role} (0033-kanon FR-021)`);
|
|
116
|
+
const declared =
|
|
117
|
+
f.role === "dialect"
|
|
118
|
+
? host.kanon.instances.some((i) => i.kind === "package" && i.package === `${SCOPE}${l.name}`)
|
|
119
|
+
: host.kanon.plugins.some((p) => p.package === `${SCOPE}${l.name}`);
|
|
120
|
+
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)`);
|
|
121
|
+
if (l.kanon === undefined || l.kanon.extends !== host.kanon.package)
|
|
122
|
+
out.push(`commons/${l.name}: a ${f.role} of ${f.host} declares a kanon table with extends: "${host.kanon.package}" (0033-kanon FR-020)`);
|
|
123
|
+
break;
|
|
124
|
+
}
|
|
125
|
+
default:
|
|
126
|
+
return absurd(f.role);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
for (const h of libraries) {
|
|
130
|
+
if (h.kanon === undefined) continue;
|
|
131
|
+
const members = [
|
|
132
|
+
...h.kanon.instances.flatMap((i) => (i.kind === "package" ? [{ role: "dialect" as const, pkg: i.package }] : [])),
|
|
133
|
+
...h.kanon.plugins.map((p) => ({ role: "plugin" as const, pkg: p.package })),
|
|
134
|
+
];
|
|
135
|
+
for (const m of members) {
|
|
136
|
+
const name = m.pkg.slice(SCOPE.length);
|
|
137
|
+
const l = by.get(name);
|
|
138
|
+
if (l === undefined || l.family?.host !== h.name || l.family.role !== m.role)
|
|
139
|
+
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)`);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return out;
|
|
143
|
+
}
|
|
@@ -19,10 +19,9 @@
|
|
|
19
19
|
* @module
|
|
20
20
|
*/
|
|
21
21
|
import process from "node:process";
|
|
22
|
-
import { ACTIONS,
|
|
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
|
|
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(
|
|
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
|
}
|
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
|
*
|
|
@@ -47,6 +47,7 @@ import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@i
|
|
|
47
47
|
import { stdio } from "@intellectual-frontiers/system";
|
|
48
48
|
import { spawn } from "@intellectual-frontiers/system/proc";
|
|
49
49
|
import { DEFAULT_LIBRARY_LEVEL, LEVELS, type LevelKey, rankOf } from "@intellectual-frontiers/mizan/levels";
|
|
50
|
+
import { decodeFamily, familyFindings, type LibraryFamily, reservationFindings, ROLES } from "./family.ts";
|
|
50
51
|
|
|
51
52
|
/** The name of a library's manifest in its folder. */
|
|
52
53
|
export const LIBRARY_FILE = "library.ts";
|
|
@@ -86,6 +87,8 @@ export type Library = {
|
|
|
86
87
|
readonly distribution: readonly Registry[];
|
|
87
88
|
/** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
|
|
88
89
|
readonly kanon?: Table;
|
|
90
|
+
/** 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). */
|
|
91
|
+
readonly family?: LibraryFamily;
|
|
89
92
|
};
|
|
90
93
|
|
|
91
94
|
/** 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. */
|
|
@@ -111,9 +114,9 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
|
|
|
111
114
|
};
|
|
112
115
|
const body = object(
|
|
113
116
|
{ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
|
|
114
|
-
{ level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue },
|
|
117
|
+
{ level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }) },
|
|
115
118
|
);
|
|
116
|
-
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"] as const;
|
|
119
|
+
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family"] as const;
|
|
117
120
|
|
|
118
121
|
/** 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
122
|
export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
@@ -143,6 +146,12 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
|
143
146
|
if (t.kind === "err") return err(`library.${t.error} (0033-kanon FR-010)`);
|
|
144
147
|
kanon = t.value;
|
|
145
148
|
}
|
|
149
|
+
let family: LibraryFamily | undefined;
|
|
150
|
+
if (v.family !== undefined) {
|
|
151
|
+
const f = decodeFamily(v.family);
|
|
152
|
+
if (f.kind === "err") return f;
|
|
153
|
+
family = f.value;
|
|
154
|
+
}
|
|
146
155
|
return ok({
|
|
147
156
|
name: v.name,
|
|
148
157
|
level: v.level ?? DEFAULT_LIBRARY_LEVEL,
|
|
@@ -153,6 +162,7 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
|
|
|
153
162
|
...(v.summary === undefined ? {} : { summary: v.summary }),
|
|
154
163
|
distribution,
|
|
155
164
|
...(kanon === undefined ? {} : { kanon }),
|
|
165
|
+
...(family === undefined ? {} : { family }),
|
|
156
166
|
});
|
|
157
167
|
}
|
|
158
168
|
|
|
@@ -252,6 +262,8 @@ export function manifestFindings(repo: string): readonly string[] {
|
|
|
252
262
|
if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
|
|
253
263
|
found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
|
|
254
264
|
}
|
|
265
|
+
const known = have.flatMap((f) => ("library" in f ? [f.library] : []));
|
|
266
|
+
found.push(...reservationFindings(known), ...familyFindings(known));
|
|
255
267
|
return found;
|
|
256
268
|
}
|
|
257
269
|
|
package/src/link.ts
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The links of the libraries (commons 0001-libraries FR-011): every package of commons linked under `commons/node_modules/@intellectual-frontiers`, so that a library imports another by its package name and reads the checkout's
|
|
3
|
+
* source. It is the first command of every script that imports a library of commons (`dev:check`, `release`, the plan of CI), and it imports none: a fresh checkout has no link yet, and the command that makes them cannot
|
|
4
|
+
* itself need one.
|
|
5
|
+
*
|
|
6
|
+
* bun commons/libraries/src/link.ts link what is not linked, from the repository above this folder (or --repo DIR)
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* A folder of `commons/` whose `package.json` is named `@intellectual-frontiers/<name>` is linked as that name, and `commons/ts` as `@intellectual-frontiers/commons` (`commons/docs` bears the same name and is not linked). A link
|
|
10
|
+
* that is there is left as it is. Only the built-ins of Node are used, so it runs on Bun and on Node 26 before anything is installed.
|
|
11
|
+
*
|
|
12
|
+
* @limits
|
|
13
|
+
* It links and nothing else: the packages the root and a library install are `bun install`'s.
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```ts
|
|
17
|
+
* import { linksOf } from "./link.ts";
|
|
18
|
+
* linksOf(".").get("@intellectual-frontiers/commons"); // the path of commons/ts
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* Spec: 0001-libraries FR-011
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync } from "node:fs";
|
|
26
|
+
import { dirname, join, resolve } from "node:path";
|
|
27
|
+
import process from "node:process";
|
|
28
|
+
import { fileURLToPath } from "node:url";
|
|
29
|
+
|
|
30
|
+
const SCOPE = "@intellectual-frontiers/";
|
|
31
|
+
|
|
32
|
+
const nameOf = (file: string): string | undefined => {
|
|
33
|
+
try {
|
|
34
|
+
const x: unknown = JSON.parse(readFileSync(file, "utf8"));
|
|
35
|
+
return typeof x === "object" && x !== null && "name" in x && typeof x.name === "string" ? x.name : undefined;
|
|
36
|
+
} catch {
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** The packages of commons by name and the folder of each; `commons/ts` comes first, so that it is the one that bears `@intellectual-frontiers/commons`. */
|
|
42
|
+
export function linksOf(repo: string): ReadonlyMap<string, string> {
|
|
43
|
+
const links = new Map<string, string>();
|
|
44
|
+
const dirs = readdirSync(join(repo, "commons"), { withFileTypes: true })
|
|
45
|
+
.filter((e) => e.isDirectory() && e.name !== "node_modules")
|
|
46
|
+
.map((e) => e.name)
|
|
47
|
+
.sort((a, b) => (a === "ts" ? -1 : b === "ts" ? 1 : a < b ? -1 : 1));
|
|
48
|
+
for (const d of dirs) {
|
|
49
|
+
const name = nameOf(join(repo, "commons", d, "package.json"));
|
|
50
|
+
if (name !== undefined && name.startsWith(SCOPE) && !links.has(name)) links.set(name, join(repo, "commons", d));
|
|
51
|
+
}
|
|
52
|
+
return links;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Links each package that is not linked yet, and gives how many it linked, or why it could not. */
|
|
56
|
+
export function linkAll(repo: string): { readonly made: number } | { readonly problem: string } {
|
|
57
|
+
try {
|
|
58
|
+
const scope = join(repo, "commons", "node_modules", "@intellectual-frontiers");
|
|
59
|
+
let made = 0;
|
|
60
|
+
for (const [name, dir] of linksOf(repo)) {
|
|
61
|
+
const at = join(scope, name.slice(SCOPE.length));
|
|
62
|
+
if (existsSync(at)) continue;
|
|
63
|
+
if (made === 0) mkdirSync(scope, { recursive: true });
|
|
64
|
+
symlinkSync(dir, at, "junction");
|
|
65
|
+
made += 1;
|
|
66
|
+
}
|
|
67
|
+
return { made };
|
|
68
|
+
} catch (e) {
|
|
69
|
+
return { problem: `the libraries could not be linked under commons/node_modules: ${e instanceof Error ? e.message : String(e)}` };
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The repository above a folder: the nearest one that has `commons/libraries/library.ts`. */
|
|
74
|
+
export function rootAbove(from: string): string | undefined {
|
|
75
|
+
for (let d = resolve(from); ; d = dirname(d)) {
|
|
76
|
+
if (existsSync(join(d, "commons", "libraries", "library.ts"))) return d;
|
|
77
|
+
if (dirname(d) === d) return undefined;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The command line: 0, or 1 where it could not link. */
|
|
82
|
+
export function main(argv: readonly string[]): number {
|
|
83
|
+
const at = argv.indexOf("--repo");
|
|
84
|
+
const repo = at >= 0 ? resolve(argv[at + 1] ?? ".") : rootAbove(dirname(fileURLToPath(import.meta.url)));
|
|
85
|
+
if (repo === undefined) {
|
|
86
|
+
process.stderr.write("link: no repository with commons/libraries here; give --repo DIR\n");
|
|
87
|
+
return 1;
|
|
88
|
+
}
|
|
89
|
+
const r = linkAll(repo);
|
|
90
|
+
if ("problem" in r) {
|
|
91
|
+
process.stderr.write(`link: ${r.problem}\n`);
|
|
92
|
+
return 1;
|
|
93
|
+
}
|
|
94
|
+
return 0;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (import.meta.main) process.exitCode = main(process.argv.slice(2));
|
package/src/pack-library.ts
CHANGED
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
import { chmod, readTextFile, writeTextFile } from "@intellectual-frontiers/system/fs";
|
|
26
26
|
import { existsSync, mkdirSync, readDirSync, readTextFileSync, removeSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
27
27
|
import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
|
|
28
|
-
import { run, which } from "@intellectual-frontiers/system/proc";
|
|
28
|
+
import { env, run, which } from "@intellectual-frontiers/system/proc";
|
|
29
29
|
|
|
30
30
|
/** The scope of the packages of commons. */
|
|
31
31
|
export const SCOPE = "@intellectual-frontiers";
|
|
@@ -514,6 +514,11 @@ export async function packLibrary(root: string, options: PackOptions = {}): Prom
|
|
|
514
514
|
|
|
515
515
|
/** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
|
|
516
516
|
export async function main(root: string, argv: readonly string[], options: PackOptions = {}): Promise<number> {
|
|
517
|
+
// the check inside `verify` is left out where CI says the exports did not change (`IFC_SKIP_PACK`); the packing for a publication is never skipped
|
|
518
|
+
if (argv.includes("--check") && (env.get("IFC_SKIP_PACK") ?? "") !== "") {
|
|
519
|
+
console.log("pack check skipped: the exports of this library did not change in this push (IFC_SKIP_PACK); the release packs it");
|
|
520
|
+
return 0;
|
|
521
|
+
}
|
|
517
522
|
const r = await packLibrary(root, options);
|
|
518
523
|
for (const f of r.findings) console.error(f);
|
|
519
524
|
if (r.tarball === undefined) return 1;
|
package/src/plan.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The plan of CI (commons 0001-libraries FR-012): the libraries a push or a pull request affects, and for each the cells that the one workflow `ci` runs, so that a change proves what it touches and nothing else.
|
|
3
|
+
*
|
|
4
|
+
* bun commons/libraries/src/plan.ts --base origin/main the plan for what changed since the merge base with origin/main, as JSON
|
|
5
|
+
* bun commons/libraries/src/plan.ts --all every library
|
|
6
|
+
* bun commons/libraries/src/plan.ts --files a.ts,b/c.ts the libraries these files affect
|
|
7
|
+
* bun commons/libraries/src/plan.ts --base REF --github-output "$GITHUB_OUTPUT" the same, written as the outputs of a step: has-linux, linux, has-systems, systems
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* The libraries are those of `affected.ts` (the same code the development loop and every check read), with the reach of `verify`: what a library's `verify` reads, and what depends on it. Each library has a cell on Linux; a
|
|
11
|
+
* library whose record of CI (`LIBRARY_CI`) names Windows or macOS has a cell on each of them too, because it has code of its own for them. A matrix with no cell is not written as a matrix (a workflow cannot run
|
|
12
|
+
* one): `has-linux` and `has-systems` say whether there is one.
|
|
13
|
+
*
|
|
14
|
+
* @limits
|
|
15
|
+
* It decides nothing about a version, a tag or a release; those are the release's. It cannot say what changed where Git cannot: it plans every library then, and says why.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { planOf } from "./plan.ts";
|
|
20
|
+
* planOf([{ name: "net", folder: "commons/net", verify: "bun run verify" }]).systems.include.map((c) => c.os); // ["windows-latest", "macos-latest"]
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* Spec: 0001-libraries FR-012
|
|
24
|
+
*
|
|
25
|
+
* @module
|
|
26
|
+
*/
|
|
27
|
+
import process from "node:process";
|
|
28
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
29
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
30
|
+
import { join } from "@intellectual-frontiers/system/path";
|
|
31
|
+
import { run } from "@intellectual-frontiers/system/proc";
|
|
32
|
+
import { flag, formatUsageError, helpText, many, parseArgs, value } from "@intellectual-frontiers/terminal/args";
|
|
33
|
+
import { affectedBy, changedSince, everyLibrary } from "./affected.ts";
|
|
34
|
+
import { type Cell, cellOf, LIBRARY_CI } from "./workflows/definitions.ts";
|
|
35
|
+
|
|
36
|
+
/** A library as the plan reads it. */
|
|
37
|
+
export type Planned = { readonly name: string; readonly folder: string; readonly verify: string };
|
|
38
|
+
|
|
39
|
+
/** The cells of a job: what `strategy.matrix` reads as `{"include": [...]}`. */
|
|
40
|
+
export type Include = { readonly include: readonly Cell[] };
|
|
41
|
+
|
|
42
|
+
/** What CI runs for a change: the cells on Linux, and the cells on the other systems. */
|
|
43
|
+
export type Plan = { readonly linux: Include; readonly systems: Include };
|
|
44
|
+
|
|
45
|
+
/** The plan for these libraries: a cell on Linux for each, and one on each system its record names, in the order of the libraries; the packing is checked in the cells of the libraries named in `packs`. */
|
|
46
|
+
export function planOf(libs: readonly Planned[], packs: ReadonlySet<string> = new Set()): Plan {
|
|
47
|
+
return {
|
|
48
|
+
linux: { include: libs.map((l) => cellOf(l, undefined, packs.has(l.name))) },
|
|
49
|
+
systems: { include: libs.flatMap((l) => (LIBRARY_CI[l.name]?.systems ?? []).map((os) => cellOf(l, os, packs.has(l.name)))) },
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The exports of a package.json as one line, the keys in order, so that two of them are the same where the entries are. */
|
|
54
|
+
export function exportsLine(packageJson: string): string {
|
|
55
|
+
try {
|
|
56
|
+
const x: unknown = JSON.parse(packageJson);
|
|
57
|
+
const e = typeof x === "object" && x !== null && "exports" in x ? x.exports : undefined;
|
|
58
|
+
const sorted = (v: unknown): unknown =>
|
|
59
|
+
typeof v === "object" && v !== null && !Array.isArray(v)
|
|
60
|
+
? Object.fromEntries(
|
|
61
|
+
Object.entries(v)
|
|
62
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
63
|
+
.map(([k, n]) => [k, sorted(n)]),
|
|
64
|
+
)
|
|
65
|
+
: v;
|
|
66
|
+
return JSON.stringify(sorted(e ?? null));
|
|
67
|
+
} catch {
|
|
68
|
+
return "unreadable";
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The libraries whose packing a push checks (FR-013): those that changed their `exports` since the base (a new library included), and every library where the packer itself changed. Git that cannot say gives every library.
|
|
74
|
+
*/
|
|
75
|
+
export async function packsFor(repo: string, base: string, libs: readonly Planned[]): Promise<ReadonlySet<string>> {
|
|
76
|
+
const all = new Set(libs.map((l) => l.name));
|
|
77
|
+
const mb = await run(["git", "-C", repo, "merge-base", base, "HEAD"]);
|
|
78
|
+
if (mb.code !== 0) return all;
|
|
79
|
+
const packer = await run(["git", "-C", repo, "diff", "--name-only", mb.stdout.trim(), "--", "commons/libraries/src/pack-library.ts"]);
|
|
80
|
+
if (packer.code !== 0 || packer.stdout.trim() !== "") return all;
|
|
81
|
+
const out = new Set<string>();
|
|
82
|
+
for (const l of libs) {
|
|
83
|
+
const before = await run(["git", "-C", repo, "show", `${mb.stdout.trim()}:${l.folder}/package.json`]);
|
|
84
|
+
const now = join(repo, l.folder, "package.json");
|
|
85
|
+
if (before.code !== 0 || !existsSync(now) || exportsLine(before.stdout) !== exportsLine(readTextFileSync(now))) out.add(l.name);
|
|
86
|
+
}
|
|
87
|
+
return out;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The outputs of a step that a workflow reads: the matrices as one line of JSON each and whether each has a cell. */
|
|
91
|
+
export function outputsOf(p: Plan): string {
|
|
92
|
+
return [
|
|
93
|
+
`has-linux=${p.linux.include.length > 0}`,
|
|
94
|
+
`linux=${JSON.stringify(p.linux)}`,
|
|
95
|
+
`has-systems=${p.systems.include.length > 0}`,
|
|
96
|
+
`systems=${JSON.stringify(p.systems)}`,
|
|
97
|
+
].join("\n");
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const OPTIONS = {
|
|
101
|
+
base: value({ help: "The revision the change starts at (the merge base with it is compared with the head).", valueName: "REF" }),
|
|
102
|
+
files: many({ help: "A file that changed (from the repository's root); the libraries it affects. Repeat or separate with commas.", valueName: "FILE" }),
|
|
103
|
+
all: flag({ help: "Every library." }),
|
|
104
|
+
repo: value({ help: "The repository (the working folder by default).", valueName: "DIR", default: "." }),
|
|
105
|
+
githubOutput: value({ help: "Append the outputs to this file, as a step's `$GITHUB_OUTPUT` is read.", valueName: "FILE" }),
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
/** The command line. Returns the exit status: 0, or 2 for a command line that does not fit. */
|
|
109
|
+
export async function main(argv: readonly string[]): Promise<number> {
|
|
110
|
+
const parsed = parseArgs(argv, OPTIONS);
|
|
111
|
+
if (parsed.kind === "err") {
|
|
112
|
+
stdio.stderr.writeSync(`${formatUsageError(parsed.error, "plan")}\n`);
|
|
113
|
+
return 2;
|
|
114
|
+
}
|
|
115
|
+
if (parsed.value.kind === "help") {
|
|
116
|
+
stdio.stdout.writeSync(`${helpText("plan", "The libraries a change affects and the cells CI runs for them.", OPTIONS)}\n`);
|
|
117
|
+
return 0;
|
|
118
|
+
}
|
|
119
|
+
const o = parsed.value.options;
|
|
120
|
+
const files = (o.files ?? []).flatMap((f) => f.split(",")).filter((f) => f !== "");
|
|
121
|
+
let libs: readonly Planned[];
|
|
122
|
+
let packs: ReadonlySet<string> = new Set();
|
|
123
|
+
if (o.all) {
|
|
124
|
+
libs = everyLibrary(o.repo);
|
|
125
|
+
packs = new Set(libs.map((l) => l.name));
|
|
126
|
+
} else if (files.length > 0) libs = affectedBy(o.repo, files);
|
|
127
|
+
else if (o.base !== undefined) {
|
|
128
|
+
const changed = await changedSince(o.repo, o.base);
|
|
129
|
+
if (changed === undefined) stdio.stderr.writeSync(`plan: git cannot say what changed since ${o.base}; every library is planned\n`);
|
|
130
|
+
libs = changed === undefined ? everyLibrary(o.repo) : affectedBy(o.repo, changed);
|
|
131
|
+
packs = changed === undefined ? new Set(libs.map((l) => l.name)) : await packsFor(o.repo, o.base, libs);
|
|
132
|
+
} else {
|
|
133
|
+
stdio.stderr.writeSync("plan: give --base REF, --files a,b or --all\n");
|
|
134
|
+
return 2;
|
|
135
|
+
}
|
|
136
|
+
const plan = planOf(libs, packs);
|
|
137
|
+
if (o.githubOutput === undefined) stdio.stdout.writeSync(`${JSON.stringify(plan)}\n`);
|
|
138
|
+
else writeTextFileSync(o.githubOutput, `${outputsOf(plan)}\n`, { append: true });
|
|
139
|
+
stdio.stderr.writeSync(`plan: ${libs.length} libraries: ${libs.map((l) => l.name).join(", ") || "none"}\n`);
|
|
140
|
+
return 0;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
if (import.meta.main) process.exitCode = await main(process.argv.slice(2));
|