@intellectual-frontiers/libraries 0.0.0-stage → 0.1.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 (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/affected.d.ts +28 -0
  4. package/dist/affected.js +250 -0
  5. package/dist/changes.d.ts +27 -0
  6. package/dist/changes.js +470 -0
  7. package/dist/check.d.ts +15 -0
  8. package/dist/check.js +198 -0
  9. package/dist/generate-ontology.d.ts +37 -0
  10. package/dist/generate-ontology.js +293 -0
  11. package/dist/generate-workflows.d.ts +12 -0
  12. package/dist/generate-workflows.js +102 -0
  13. package/dist/imports/nist-sp-800-53.import.d.ts +33 -0
  14. package/dist/imports/nist-sp-800-53.import.js +34 -0
  15. package/dist/imports/schema-org.import.d.ts +33 -0
  16. package/dist/imports/schema-org.import.js +31 -0
  17. package/dist/install-bun.d.ts +1 -0
  18. package/dist/install-bun.js +58 -0
  19. package/dist/libraries.d.ts +79 -0
  20. package/dist/libraries.js +386 -0
  21. package/dist/mod.d.ts +16 -0
  22. package/dist/mod.js +16 -0
  23. package/dist/newer.d.ts +27 -0
  24. package/dist/newer.js +147 -0
  25. package/dist/oscal-register.d.ts +65 -0
  26. package/dist/oscal-register.js +344 -0
  27. package/dist/pack-library.d.ts +47 -0
  28. package/dist/pack-library.js +498 -0
  29. package/dist/pins.d.ts +15 -0
  30. package/dist/pins.js +29 -0
  31. package/dist/publish-ontology.d.ts +160 -0
  32. package/dist/publish-ontology.js +227 -0
  33. package/dist/versions.d.ts +26 -0
  34. package/dist/versions.js +556 -0
  35. package/dist/workflows/definitions.d.ts +65 -0
  36. package/dist/workflows/definitions.js +614 -0
  37. package/dist/workflows/mod.d.ts +10 -0
  38. package/dist/workflows/mod.js +10 -0
  39. package/dist/workflows/model.d.ts +143 -0
  40. package/dist/workflows/model.js +81 -0
  41. package/dist/workflows/render.d.ts +9 -0
  42. package/dist/workflows/render.js +179 -0
  43. package/package.json +129 -4
  44. package/src/affected.ts +265 -0
  45. package/src/changes.ts +546 -0
  46. package/src/check.ts +223 -0
  47. package/src/generate-ontology.ts +350 -0
  48. package/src/generate-workflows.ts +103 -0
  49. package/src/imports/nist-sp-800-53.import.ts +36 -0
  50. package/src/imports/schema-org.import.ts +31 -0
  51. package/src/install-bun.ts +53 -0
  52. package/src/libraries.ts +385 -0
  53. package/src/mod.ts +16 -0
  54. package/src/newer.ts +154 -0
  55. package/src/oscal-register.ts +443 -0
  56. package/src/pack-library.ts +522 -0
  57. package/src/pins.ts +30 -0
  58. package/src/publish-ontology.ts +354 -0
  59. package/src/versions.ts +594 -0
  60. package/src/workflows/definitions.ts +847 -0
  61. package/src/workflows/mod.ts +30 -0
  62. package/src/workflows/model.ts +187 -0
  63. package/src/workflows/render.ts +176 -0
@@ -0,0 +1,522 @@
1
+ /**
2
+ * The package of a library of commons (commons 0032-lifting-libraries FR-005, FR-013): the library's sources compiled by the TypeScript 7 compiler into ECMAScript modules and their declarations, the
3
+ * `package.json` that is published (each `exports` entry naming its `types`, the source for Bun and the compiled file for everything else), and the tarball. The same inspection that the packer makes before it
4
+ * packs is `inspectPackage`, which a test runs again on the tarball it unpacks.
5
+ *
6
+ * bun tools/pack.ts of a library: pack `dist/<scope>-<name>-<version>.tgz`
7
+ * bun tools/pack.ts --check the same, and print what was found; exit 1 where anything was
8
+ *
9
+ * @remarks
10
+ * A library's own `package.json` stays private and names its entries by their sources (`"./src/mod.ts"`); nothing is published from it by hand. A library that depends on another library of commons imports it by package
11
+ * name, and the published package depends on it at the version that library has in this repository. The declarations are written with `.js` specifiers (the compiler leaves `.ts` in a `.d.ts`, which a consumer's
12
+ * compiler cannot read), and only the declarations that the entries reach are published in a bundle. A package is refused where an entry has no declaration, where a declaration reached imports a file that is not in
13
+ * the package or a package that is not a dependency, or where the code imports a package that is not on npm.
14
+ *
15
+ * A package that is also a command, or whose code imports what is not yet on npm, is packed with `bundle`: each entry's code and the command's are one bundle (`bun build`), the declarations are emitted from the
16
+ * sources and only those the entries reach are published, and whatever they import must be a package of npm that the package depends on.
17
+ *
18
+ * @limits
19
+ * It builds a library whose sources are under `src/`, one tarball with one `exports` map.
20
+ *
21
+ * Spec: 0001-libraries FR-007
22
+ *
23
+ * @module
24
+ */
25
+ import { chmod, readTextFile, writeTextFile } from "@intellectual-frontiers/system/fs";
26
+ import { existsSync, mkdirSync, readDirSync, readTextFileSync, removeSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
27
+ import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
28
+ import { run, which } from "@intellectual-frontiers/system/proc";
29
+
30
+ /** The scope of the packages of commons. */
31
+ export const SCOPE = "@intellectual-frontiers";
32
+
33
+ /** What is wrong with a package, one sentence each. */
34
+ export type Findings = readonly string[];
35
+
36
+ type Json = Readonly<Record<string, unknown>>;
37
+
38
+ const obj = (v: unknown): Json => (isObject(v) ? v : {});
39
+ const isObject = (v: unknown): v is Json => typeof v === "object" && v !== null && !Array.isArray(v);
40
+ const text = (v: unknown): string => (typeof v === "string" ? v : "");
41
+ /** A text file copied: every file of a package is text. */
42
+ const copyFileSync = (from: string, to: string): void => writeTextFileSync(to, readTextFileSync(from));
43
+ const noDot = (p: string): string => toPosix(p).replace(/^\.\//, "");
44
+
45
+ /** The files under a folder, from the folder, in order (`node_modules` is not looked into). */
46
+ export function filesUnder(root: string, dir = ""): readonly string[] {
47
+ const out: string[] = [];
48
+ for (const e of readDirSync(join(root, dir)).sort((a, b) => (a.name < b.name ? -1 : 1))) {
49
+ if (e.name === "node_modules") continue;
50
+ const rel = dir === "" ? e.name : `${dir}/${e.name}`;
51
+ if (e.isDirectory) out.push(...filesUnder(root, rel));
52
+ else if (e.isFile) out.push(rel);
53
+ }
54
+ return out;
55
+ }
56
+
57
+ const SPECIFIER = /(?:\bfrom\s+|\bimport\s+|\bimport\(\s*)["']([^"']+)["']/g;
58
+
59
+ /** The documentation blocks of a source (a block comment that begins a line): an example in one names what a reader may write, not what the module imports. */
60
+ const DOC_BLOCK = /^[ \t]*\/\*[\s\S]*?\*\//gm;
61
+
62
+ /** The specifiers a source names, outside its documentation blocks. */
63
+ export const specifiersOf = (source: string): readonly string[] =>
64
+ [...source.replace(DOC_BLOCK, "").matchAll(SPECIFIER)].map((m) => m[1] ?? "").filter((s) => s !== "");
65
+
66
+ /** The package a bare specifier names (`@scope/name/sub` is `@scope/name`), or undefined for a relative path, a `node:` builtin or a `data:` URL. */
67
+ export function packageOf(specifier: string): string | undefined {
68
+ if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("node:") || specifier.startsWith("data:"))
69
+ return undefined;
70
+ const parts = specifier.split("/");
71
+ return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
72
+ }
73
+
74
+ /** The target of an export entry for each condition: the string, or the `types`, `bun` or `default` of an object. */
75
+ function targetsOf(entry: unknown): Readonly<Record<string, string>> {
76
+ if (typeof entry === "string") return { default: entry };
77
+ if (!isObject(entry)) return {};
78
+ return Object.fromEntries(Object.entries(entry).flatMap(([k, v]) => (typeof v === "string" ? [[k, v] as const] : [])));
79
+ }
80
+
81
+ /** The declaration file that a relative specifier of a declaration names, from the package's root: `./x.js` is `x.d.ts`. */
82
+ function declarationFor(from: string, specifier: string): string {
83
+ const base = toPosix(join(dirname(from), specifier));
84
+ return base.replace(/\.(?:js|ts|mjs)$/, "") + ".d.ts";
85
+ }
86
+
87
+ /** The declarations that the entries of a package reach, by relative imports from the `types` of each entry, and what is wrong on the way (a declaration that is not there). */
88
+ export function reachableDeclarations(
89
+ stage: string,
90
+ manifest: Json,
91
+ ): { readonly reached: ReadonlySet<string>; readonly findings: Findings } {
92
+ const found: string[] = [];
93
+ const name = text(manifest["name"]);
94
+ const files = new Set(filesUnder(stage));
95
+ const entries: string[] = [];
96
+ for (const [key, entry] of Object.entries(isObject(manifest["exports"]) ? manifest["exports"] : {})) {
97
+ const types = targetsOf(entry)["types"];
98
+ if (types === undefined) found.push(`${name}: the export ${key} names no \`types\` file`);
99
+ else if (!files.has(noDot(types))) found.push(`${name}: the export ${key} names ${types}, which is not in the package`);
100
+ else entries.push(noDot(types));
101
+ }
102
+ if (typeof manifest["types"] === "string" && !files.has(noDot(manifest["types"])))
103
+ found.push(`${name}: types names ${manifest["types"]}, which is not in the package`);
104
+ const reached = new Set<string>();
105
+ const todo = [...entries];
106
+ while (todo.length > 0) {
107
+ const d = todo.pop() ?? "";
108
+ if (reached.has(d)) continue;
109
+ reached.add(d);
110
+ for (const s of specifiersOf(readTextFileSync(join(stage, d)))) {
111
+ if (!s.startsWith(".")) continue;
112
+ const next = declarationFor(d, s);
113
+ if (!files.has(next)) found.push(`${d} imports ${s}, whose declaration ${next} is not in the package`);
114
+ else todo.push(next);
115
+ }
116
+ }
117
+ return { reached, findings: found };
118
+ }
119
+
120
+ /** What is wrong with the package staged in a folder (the files of the tarball, `package/` unpacked): see the remarks of this module. */
121
+ export function inspectPackage(stage: string): Findings {
122
+ const found: string[] = [];
123
+ const manifestFile = join(stage, "package.json");
124
+ if (!existsSync(manifestFile)) return ["package.json is not in the package"];
125
+ const manifest = JSON.parse(readTextFileSync(manifestFile)) as Json;
126
+ const name = text(manifest["name"]);
127
+ const files = new Set(filesUnder(stage));
128
+ const declared = new Set<string>([
129
+ ...Object.keys(isObject(manifest["dependencies"]) ? manifest["dependencies"] : {}),
130
+ ...Object.keys(isObject(manifest["peerDependencies"]) ? manifest["peerDependencies"] : {}),
131
+ ...Object.keys(isObject(manifest["optionalDependencies"]) ? manifest["optionalDependencies"] : {}),
132
+ ]);
133
+ const exportsMap = isObject(manifest["exports"]) ? manifest["exports"] : {};
134
+ const bin = isObject(manifest["bin"]) ? manifest["bin"] : {};
135
+ if (Object.keys(exportsMap).length === 0 && Object.keys(bin).length === 0) found.push(`${name}: the package has no exports and no bin`);
136
+ for (const [cmd, target] of Object.entries(bin))
137
+ if (typeof target !== "string" || !files.has(noDot(target)))
138
+ found.push(`${name}: the command ${cmd} names ${String(target)}, which is not in the package`);
139
+ // every entry has declarations and the files its conditions name
140
+ for (const [key, entry] of Object.entries(exportsMap)) {
141
+ for (const [cond, target] of Object.entries(targetsOf(entry))) {
142
+ if (cond !== "types" && !files.has(noDot(target)))
143
+ found.push(`${name}: the export ${key} (${cond}) names ${target}, which is not in the package`);
144
+ }
145
+ }
146
+ // the declarations that the entries reach: each import is a file of the package or a package the manifest depends on
147
+ const { reached, findings } = reachableDeclarations(stage, manifest);
148
+ found.push(...findings);
149
+ for (const d of reached) {
150
+ for (const s of specifiersOf(readTextFileSync(join(stage, d)))) {
151
+ const pkg = packageOf(s);
152
+ if (pkg === undefined) continue;
153
+ if (pkg === `${SCOPE}/commons`) found.push(`${d} imports ${s}: the package ${pkg} is not on npm`);
154
+ else if (pkg !== name && !declared.has(pkg)) found.push(`${d} imports ${pkg}, which is not a dependency of ${name}`);
155
+ }
156
+ }
157
+ // the compiled code of a library (files under dist/ other than bundles) imports no package that is not a dependency, and none that is not on npm; a declaration never imports a `.ts` path
158
+ for (const f of files) {
159
+ if (!/\.(?:js|mjs|d\.ts)$/.test(f) || !f.startsWith("dist/")) continue;
160
+ const source = readTextFileSync(join(stage, f));
161
+ if (/\.d\.ts$/.test(f)) {
162
+ if (/(?:from\s+|import\(\s*)["']\.[^"']*\.ts["']/.test(source))
163
+ found.push(`${f} imports a \`.ts\` path, which a consumer's compiler cannot read`);
164
+ continue;
165
+ }
166
+ if (isBundle(source)) continue;
167
+ for (const s of specifiersOf(source)) {
168
+ const pkg = packageOf(s);
169
+ if (pkg === undefined) continue;
170
+ if (pkg === `${SCOPE}/commons`) found.push(`${f} imports ${s}: the package ${pkg} is not on npm`);
171
+ else if (pkg !== name && !declared.has(pkg)) found.push(`${f} imports ${pkg}, which is not a dependency of ${name}`);
172
+ }
173
+ }
174
+ return found;
175
+ }
176
+
177
+ /** Whether a compiled file is a bundle (`bun build` marks its output): its imports are what it holds, so it is not read for them. */
178
+ const isBundle = (source: string): boolean =>
179
+ /^\/\/ @bun\b|^\/\/ @bun\s*$/m.test(source.slice(0, 400)) || source.startsWith("#!") || /\/\/ \.\.\/\.\.\//.test(source.slice(0, 2000));
180
+
181
+ /** Writes the declarations with `.js` in the place of `.ts` in their relative specifiers. */
182
+ export function rewriteDeclarationSpecifiers(source: string): string {
183
+ return source.replace(/((?:from\s+|import\(\s*|import\s+)["'])(\.[^"']*?)\.ts(["'])/g, "$1$2.js$3");
184
+ }
185
+
186
+ /** The tarball's name for a package: `@scope/name` at a version is `scope-name-version.tgz`. */
187
+ export const tarballName = (name: string, version: string): string => `${name.replace(/^@/, "").replace("/", "-")}-${version}.tgz`;
188
+
189
+ /** The version of a library of commons, from its `package.json`, and whether it is published to npm (its manifest names that). */
190
+ function libraryOf(commons: string, name: string): { readonly version: string; readonly npm: boolean } | undefined {
191
+ const pkg = join(commons, name, "package.json");
192
+ if (!existsSync(pkg)) return undefined;
193
+ const lib = join(commons, name, "library.ts");
194
+ const npm = existsSync(lib) && /distribution:\s*\[[^\]]*"npm"/.test(readTextFileSync(lib));
195
+ return { version: text((JSON.parse(readTextFileSync(pkg)) as Json)["version"]), npm };
196
+ }
197
+
198
+ /**
199
+ * The declarations of a bundle: from the entries' declarations in the compiler's output, every declaration reached by a relative import is published, and so is every declaration that a package of commons that is not
200
+ * on npm (`@intellectual-frontiers/commons/ts/...`) gives to them, vendored under `dist/vendor/` with the specifiers that name it rewritten to relative ones. It is the way for a package to publish its API while what
201
+ * its types are made of is still lifted out of `commons/ts` a library at a time (commons 0032-lifting-libraries); a library that has been lifted is a dependency and is not vendored.
202
+ */
203
+ function vendorDeclarations(
204
+ outRoot: string,
205
+ lib: string,
206
+ entries: readonly string[],
207
+ commonsPkg: { readonly folder: string; readonly exports: ReadonlyMap<string, string> },
208
+ stageDist: string,
209
+ ): Findings {
210
+ const found: string[] = [];
211
+ const placed = new Map<string, string>(); // a file of the compiler's output, and where it goes under the stage's dist/
212
+ const place = (file: string): string => {
213
+ const rel = toPosix(relative(outRoot, file));
214
+ const own = `${lib}/src/`;
215
+ return rel.startsWith(own) ? rel.slice(own.length) : `vendor/${rel}`;
216
+ };
217
+ const todo = [...entries];
218
+ while (todo.length > 0) {
219
+ const file = todo.pop() ?? "";
220
+ if (placed.has(file)) continue;
221
+ if (!existsSync(file)) {
222
+ found.push(`the compiler wrote no declaration ${toPosix(relative(outRoot, file))}`);
223
+ continue;
224
+ }
225
+ const dest = place(file);
226
+ placed.set(file, dest);
227
+ for (const s of specifiersOf(readTextFileSync(file))) {
228
+ if (s.startsWith(".")) todo.push(join(dirname(file), s.replace(/\.(?:js|ts|mjs)$/, "") + ".d.ts"));
229
+ else if (s.startsWith(`${SCOPE}/commons/`)) {
230
+ const target = commonsPkg.exports.get(`./${s.slice(`${SCOPE}/commons/`.length)}`);
231
+ if (target === undefined) found.push(`${dest} imports ${s}, which the exports of commons do not name`);
232
+ else todo.push(join(outRoot, commonsPkg.folder, target.replace(/^\.\//, "").replace(/\.ts$/, "") + ".d.ts"));
233
+ }
234
+ }
235
+ }
236
+ for (const [file, dest] of placed) {
237
+ let source = rewriteDeclarationSpecifiers(readTextFileSync(file));
238
+ source = source.replace(
239
+ new RegExp(`((?:from\\s+|import\\(\\s*|import\\s+)["'])${SCOPE}/commons/([^"']+)(["'])`, "g"),
240
+ (whole, pre: string, sub: string, post: string) => {
241
+ const target = commonsPkg.exports.get(`./${sub}`);
242
+ if (target === undefined) return whole;
243
+ const there = place(join(outRoot, commonsPkg.folder, target.replace(/^\.\//, "").replace(/\.ts$/, "") + ".d.ts"));
244
+ let rel = toPosix(relative(dirname(dest), there)).replace(/\.d\.ts$/, ".js");
245
+ if (!rel.startsWith(".")) rel = `./${rel}`;
246
+ return `${pre}${rel}${post}`;
247
+ },
248
+ );
249
+ // a relative import that leaves the library's own tree (a type the compiler named by its path in commons) goes to where that declaration was placed
250
+ source = source.replace(
251
+ /((?:from\s+|import\(\s*|import\s+)["'])(\.[^"']+)(["'])/g,
252
+ (whole, pre: string, spec: string, post: string) => {
253
+ const target = join(dirname(file), spec.replace(/\.(?:js|ts|mjs)$/, "") + ".d.ts");
254
+ const there = placed.get(target);
255
+ if (there === undefined) return whole;
256
+ let rel = toPosix(relative(dirname(dest), there)).replace(/\.d\.ts$/, ".js");
257
+ if (!rel.startsWith(".")) rel = `./${rel}`;
258
+ return `${pre}${rel}${post}`;
259
+ },
260
+ );
261
+ const out = join(stageDist, dest);
262
+ mkdirSync(dirname(out), { recursive: true });
263
+ writeTextFileSync(out, source);
264
+ }
265
+ return found;
266
+ }
267
+
268
+ /** The compiler's `paths` for the packages of commons that are not on npm: each entry of `commons/ts/package.json` (`./ts/kernel`) names the source that the specifier `@intellectual-frontiers/commons/ts/kernel` is. */
269
+ function commonsPaths(commons: string, dist: string): Record<string, readonly string[]> {
270
+ const file = join(commons, "ts", "package.json");
271
+ const out: Record<string, readonly string[]> = {};
272
+ if (!existsSync(file)) return out;
273
+ for (const [k, v] of Object.entries(obj(obj(JSON.parse(readTextFileSync(file)) as unknown)["exports"]))) {
274
+ if (typeof v === "string" && v.endsWith(".ts"))
275
+ out[`${SCOPE}/commons/${k.replace(/^\.\//, "")}`] = [toPosix(relative(dist, join(commons, "ts", v)))];
276
+ }
277
+ return out;
278
+ }
279
+
280
+ export type Packed = { readonly stage: string; readonly tarball: string | undefined; readonly findings: Findings; readonly manifest: Json };
281
+
282
+ /** What a package adds to the common form. */
283
+ /** Whether a declaration of the package names a `node:` module: a package whose types name Node's needs `@types/node` where it is type-checked (a peer dependency, FR-013 of 0032-lifting-libraries). */
284
+ function namesNodeTypes(folder: string): boolean {
285
+ if (!existsSync(folder)) return false;
286
+ for (const e of readDirSync(folder)) {
287
+ const p = join(folder, e.name);
288
+ if (e.isDirectory) {
289
+ if (namesNodeTypes(p)) return true;
290
+ } else if (e.name.endsWith(".d.ts") && /(?:from\s+|import\()"node:/.test(readTextFileSync(p))) return true;
291
+ }
292
+ return false;
293
+ }
294
+
295
+ export type PackOptions = {
296
+ /** Types the compiler is given (`["node"]` for a library that names Node's). */
297
+ readonly types?: readonly string[];
298
+ /** A bundled package: the code of each entry and of each command is one file (`bun build`), and only the declarations the entries reach are published. */
299
+ readonly bundle?: {
300
+ /** The commands: their name, and the source that is the command's entry from the library's folder. */
301
+ readonly bin?: Readonly<Record<string, string>>;
302
+ /** The README that is published, where it is more than the common one. */
303
+ readonly readme?: string;
304
+ readonly keywords?: readonly string[];
305
+ /** Files of the library's folder that are published beside the others (`CREDITS.md`). */
306
+ readonly extraFiles?: readonly string[];
307
+ };
308
+ };
309
+
310
+ /** Builds and stages the package of the library at `root` (a folder `commons/<name>/` with a `package.json` and sources in `src/`), inspects it and, where nothing is wrong, packs it. */
311
+ export async function packLibrary(root: string, options: PackOptions = {}): Promise<Packed> {
312
+ const own = JSON.parse(readTextFileSync(join(root, "package.json"))) as Json;
313
+ const name = text(own["name"]);
314
+ const short = name.replace(`${SCOPE}/`, "");
315
+ const commons = dirname(resolve(root));
316
+ const dist = join(root, "dist");
317
+ const stage = join(dist, "package");
318
+ const bundle = options.bundle;
319
+ if (existsSync(dist)) removeSync(dist, { recursive: true });
320
+ mkdirSync(stage, { recursive: true });
321
+ // the compiler's configuration for this build: the base of commons, emitting modules and declarations of src/ and nothing else
322
+ const base = relative(dist, join(commons, "ts", "tsconfig.json"));
323
+ writeTextFileSync(
324
+ join(dist, "tsconfig.build.json"),
325
+ JSON.stringify(
326
+ {
327
+ extends: toPosix(base),
328
+ compilerOptions: {
329
+ noEmit: false,
330
+ declaration: true,
331
+ rewriteRelativeImportExtensions: true,
332
+ rootDir: toPosix(relative(dist, commons)),
333
+ outDir: "out",
334
+ types: options.types ?? [],
335
+ skipLibCheck: true,
336
+ // another library of commons is read where the package manager linked it (under node_modules), so that a declaration names it by its package and its entry and never by the path of its sources
337
+ preserveSymlinks: true,
338
+ // a bundle's declarations are made from the sources of the packages of commons that are not on npm, which the compiler emits only when it reads them as sources and not through node_modules
339
+ ...(bundle === undefined ? {} : { paths: commonsPaths(commons, dist) }),
340
+ },
341
+ include: [toPosix(relative(dist, join(root, "src"))) + "/**/*.ts"],
342
+ },
343
+ null,
344
+ 2,
345
+ ),
346
+ );
347
+ const bun = which("bun") ?? "bun";
348
+ const built = await run([bun, "x", "tsc", "-p", join(dist, "tsconfig.build.json")], { cwd: root });
349
+ if (built.code !== 0)
350
+ return { stage, tarball: undefined, findings: [`the compiler stopped: ${built.stdout || built.stderr}`.trim()], manifest: {} };
351
+ // what src/ became is in out/<name>/src/: the declarations go to dist/, and the compiled files too unless the package is a bundle
352
+ const out = join(dist, "out", basename(resolve(root)), "src");
353
+ const findings: string[] = [];
354
+ const ownExports = isObject(own["exports"]) ? own["exports"] : {};
355
+ if (bundle === undefined) {
356
+ for (const f of filesUnder(out)) {
357
+ const target = join(stage, "dist", f);
358
+ mkdirSync(dirname(target), { recursive: true });
359
+ if (f.endsWith(".d.ts")) writeTextFileSync(target, rewriteDeclarationSpecifiers(readTextFileSync(join(out, f))));
360
+ else if (f.endsWith(".js")) copyFileSync(join(out, f), target);
361
+ }
362
+ } else {
363
+ const commonsPkgFile = join(commons, "ts", "package.json");
364
+ const commonsExports = new Map<string, string>();
365
+ if (existsSync(commonsPkgFile)) {
366
+ const declared = obj(obj(JSON.parse(readTextFileSync(commonsPkgFile)) as unknown)["exports"]);
367
+ for (const [k, v] of Object.entries(declared)) if (typeof v === "string") commonsExports.set(k, v);
368
+ }
369
+ const entryFiles = Object.values(ownExports).map((e) =>
370
+ join(out, (targetsOf(e)["default"] ?? text(e)).replace(/^\.\/src\//, "").replace(/\.ts$/, "") + ".d.ts"),
371
+ );
372
+ findings.push(
373
+ ...vendorDeclarations(
374
+ join(dist, "out"),
375
+ basename(resolve(root)),
376
+ entryFiles,
377
+ { folder: "ts", exports: commonsExports },
378
+ join(stage, "dist"),
379
+ ),
380
+ );
381
+ }
382
+ // the sources, for the `bun` condition (a bundle has no source to offer: what it imports is not on npm)
383
+ if (bundle === undefined) {
384
+ for (const f of filesUnder(join(root, "src"))) {
385
+ if (!f.endsWith(".ts")) continue;
386
+ const target = join(stage, "src", f);
387
+ mkdirSync(dirname(target), { recursive: true });
388
+ copyFileSync(join(root, "src", f), target);
389
+ }
390
+ }
391
+ // the entries: each names its declarations, its source (Bun) and its compiled file
392
+ const exportsOut: Record<string, unknown> = {};
393
+ for (const [key, entry] of Object.entries(ownExports)) {
394
+ const source = targetsOf(entry)["default"] ?? text(entry);
395
+ const rel = toPosix(source)
396
+ .replace(/^\.\/src\//, "")
397
+ .replace(/\.ts$/, "");
398
+ exportsOut[key] =
399
+ bundle === undefined
400
+ ? { types: `./dist/${rel}.d.ts`, bun: `./src/${rel}.ts`, default: `./dist/${rel}.js` }
401
+ : { types: `./dist/${rel}.d.ts`, default: `./dist/${rel}.js` };
402
+ if (bundle !== undefined) {
403
+ const bundled = await run(
404
+ [bun, "build", join(root, source), "--target=node", "--format=esm", "--outfile", join(stage, "dist", `${rel}.js`)],
405
+ { cwd: root },
406
+ );
407
+ if (bundled.code !== 0) findings.push(`bun build stopped on ${source}: ${bundled.stderr || bundled.stdout}`.trim());
408
+ }
409
+ }
410
+ // the commands of a bundle: one file each, with the line that runs it under Node
411
+ const binOut: Record<string, string> = {};
412
+ for (const [cmd, source] of Object.entries(bundle?.bin ?? {})) {
413
+ const file = join(stage, `${cmd}.mjs`);
414
+ const bundled = await run([bun, "build", join(root, source), "--target=node", "--format=esm", "--outfile", file], { cwd: root });
415
+ if (bundled.code !== 0) {
416
+ findings.push(`bun build stopped on ${source}: ${bundled.stderr || bundled.stdout}`.trim());
417
+ continue;
418
+ }
419
+ const code = await readTextFile(file);
420
+ await writeTextFile(file, code.startsWith("#!") ? code : `#!/usr/bin/env node\n${code}`);
421
+ await chmod(file, 0o755);
422
+ binOut[cmd] = `./${cmd}.mjs`;
423
+ }
424
+ // the dependencies: the packages that the compiled code names (of a bundle, the declarations the entries reach), the libraries of commons at the version they have here, the others as the library declares them
425
+ const declaredDeps = isObject(own["dependencies"]) ? own["dependencies"] : {};
426
+ const dependencies: Record<string, string> = {};
427
+ const scanned: { readonly file: string; readonly source: string }[] = [];
428
+ if (bundle === undefined)
429
+ for (const f of filesUnder(join(stage, "dist"))) scanned.push({ file: `dist/${f}`, source: readTextFileSync(join(stage, "dist", f)) });
430
+ else {
431
+ const draft = {
432
+ name,
433
+ exports: exportsOut,
434
+ ...(typeof exportsOut["."] === "object" ? { types: (exportsOut["."] as Json)["types"] } : {}),
435
+ } as Json;
436
+ const { reached } = reachableDeclarations(stage, draft);
437
+ for (const d of reached) scanned.push({ file: d, source: readTextFileSync(join(stage, d)) });
438
+ // only the declarations the entries reach are published
439
+ for (const f of filesUnder(join(stage, "dist")))
440
+ if (f.endsWith(".d.ts") && !reached.has(`dist/${f}`)) removeSync(join(stage, "dist", f));
441
+ }
442
+ for (const { file, source } of scanned) {
443
+ for (const s of specifiersOf(source)) {
444
+ const pkg = packageOf(s);
445
+ if (pkg === undefined || pkg === name) continue;
446
+ if (pkg.startsWith(`${SCOPE}/`) && pkg !== `${SCOPE}/commons`) {
447
+ const lib = libraryOf(commons, pkg.slice(SCOPE.length + 1));
448
+ if (lib === undefined) findings.push(`${file} imports ${pkg}, which is no library of commons`);
449
+ else if (!lib.npm) findings.push(`${file} imports ${pkg}, which is not published to npm`);
450
+ else dependencies[pkg] = lib.version;
451
+ } else if (pkg !== `${SCOPE}/commons`) {
452
+ const v = declaredDeps[pkg];
453
+ if (typeof v === "string") dependencies[pkg] = v;
454
+ else findings.push(`${file} imports ${pkg}, which the package.json of ${short} does not list under dependencies`);
455
+ }
456
+ }
457
+ }
458
+ const extraFiles = bundle?.extraFiles ?? [];
459
+ for (const f of extraFiles) copyFileSync(join(root, f), join(stage, f));
460
+ const manifest: Json = {
461
+ name,
462
+ version: text(own["version"]),
463
+ description: text(own["description"]),
464
+ license: "MIT",
465
+ type: "module",
466
+ engines: { node: ">=26" },
467
+ sideEffects: false,
468
+ ...(Object.keys(binOut).length === 0 ? {} : { bin: binOut }),
469
+ ...(exportsOut["."] === undefined ? {} : { types: (exportsOut["."] as Json)["types"] }),
470
+ ...(Object.keys(exportsOut).length === 0 ? {} : { exports: exportsOut }),
471
+ ...(Object.keys(dependencies).length === 0
472
+ ? {}
473
+ : { dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => (a < b ? -1 : 1))) }),
474
+ ...(namesNodeTypes(join(stage, "dist")) ? { peerDependencies: { "@types/node": ">=26" } } : {}),
475
+ files: [
476
+ ...(Object.keys(exportsOut).length === 0 ? [] : ["dist"]),
477
+ ...(bundle === undefined ? ["src"] : []),
478
+ ...Object.values(binOut).map(noDot),
479
+ "README.md",
480
+ "LICENSE",
481
+ ...extraFiles,
482
+ ],
483
+ repository: { type: "git", url: "git+https://github.com/intellectual-frontiers/.github.git", directory: `commons/${short}` },
484
+ homepage: `https://github.com/intellectual-frontiers/.github/tree/main/commons/${short}`,
485
+ bugs: { url: "https://github.com/intellectual-frontiers/.github/issues" },
486
+ ...(bundle?.keywords === undefined ? {} : { keywords: bundle.keywords }),
487
+ publishConfig: { access: "public" },
488
+ };
489
+ writeTextFileSync(join(stage, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
490
+ writeTextFileSync(
491
+ join(stage, "README.md"),
492
+ bundle?.readme ??
493
+ [
494
+ `# ${name}`,
495
+ "",
496
+ text(own["description"]),
497
+ "",
498
+ "```sh",
499
+ `bun add ${name} # or: npm install ${name}`,
500
+ "```",
501
+ "",
502
+ `Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/${short}`,
503
+ "",
504
+ ].join("\n"),
505
+ );
506
+ copyFileSync(existsSync(join(root, "LICENSE")) ? join(root, "LICENSE") : join(commons, "ergonex", "LICENSE"), join(stage, "LICENSE"));
507
+ findings.push(...inspectPackage(stage));
508
+ if (findings.length > 0) return { stage, tarball: undefined, findings, manifest };
509
+ const packed = await run([bun, "pm", "pack", "--destination", dist], { cwd: stage });
510
+ if (packed.code !== 0)
511
+ return { stage, tarball: undefined, findings: [`bun pm pack stopped: ${packed.stderr || packed.stdout}`.trim()], manifest };
512
+ return { stage, tarball: join(dist, tarballName(name, text(own["version"]))), findings: [], manifest };
513
+ }
514
+
515
+ /** The command line of a library's `tools/pack.ts`: pack, print what was found (or the tarball) and the exit status. */
516
+ export async function main(root: string, argv: readonly string[], options: PackOptions = {}): Promise<number> {
517
+ const r = await packLibrary(root, options);
518
+ for (const f of r.findings) console.error(f);
519
+ if (r.tarball === undefined) return 1;
520
+ console.log(argv.includes("--check") ? `packed ${r.tarball}: nothing wrong` : r.tarball);
521
+ return 0;
522
+ }
package/src/pins.ts ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Commons' pins as the tools read them (commons 0005-typescript-runtime FR-026): the `KEY=value` lines of `pins.auto.env`, and which of
3
+ * Bun's release assets and pin keys belong to a platform.
4
+ *
5
+ * Spec: 0001-libraries FR-006
6
+ *
7
+ * @module
8
+ */
9
+
10
+ /** The target name of Bun's release asset and the suffix of commons' pin key for a platform (by the names `proc.build` gives); undefined where Bun has no build. */
11
+ export function bunTarget(os: string, arch: string): { readonly target: string; readonly key: string } | undefined {
12
+ const table: Readonly<Record<string, { readonly target: string; readonly key: string }>> = {
13
+ "linux/x86_64": { target: "linux-x64", key: "X86_64" },
14
+ "linux/aarch64": { target: "linux-aarch64", key: "AARCH64" },
15
+ "darwin/x86_64": { target: "darwin-x64", key: "MACOS_X64" },
16
+ "darwin/aarch64": { target: "darwin-aarch64", key: "MACOS_ARM64" },
17
+ "windows/x86_64": { target: "windows-x64", key: "WINDOWS_X64" },
18
+ };
19
+ return Object.hasOwn(table, `${os}/${arch}`) ? table[`${os}/${arch}`] : undefined;
20
+ }
21
+
22
+ /** The `KEY=value` lines of an env file; comments and blank lines left out. */
23
+ export function readEnvFile(text: string): ReadonlyMap<string, string> {
24
+ const out = new Map<string, string>();
25
+ for (const line of text.split(/\r?\n/)) {
26
+ const m = /^([A-Z0-9_]+)=(.*)$/.exec(line);
27
+ if (m?.[1] !== undefined && m[2] !== undefined) out.set(m[1], m[2]);
28
+ }
29
+ return out;
30
+ }