@intellectual-frontiers/libraries 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -21
- package/dist/affected.d.ts +1 -1
- package/dist/dev.d.ts +2 -0
- package/dist/dev.js +14 -2
- package/dist/family.js +1 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/imports/nist-sp-800-53.auto.prov.ttl +22 -0
- package/dist/imports/schema-org.auto.prov.ttl +22 -0
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +39 -2
- package/dist/libraries.js +80 -9
- package/dist/license/PolyForm-Noncommercial-1.0.0.md +73 -0
- package/dist/license/standard.d.ts +46 -0
- package/dist/license/standard.js +43 -0
- package/dist/license/third-party.d.ts +25 -0
- package/dist/license/third-party.js +71 -0
- package/dist/license.d.ts +61 -0
- package/dist/license.js +204 -0
- package/dist/link.d.ts +1 -1
- package/dist/link.js +4 -4
- package/dist/metapackages.d.ts +62 -0
- package/dist/metapackages.js +190 -0
- package/dist/mod.d.ts +1 -1
- package/dist/mod.js +1 -1
- package/dist/pack-library.d.ts +9 -0
- package/dist/pack-library.js +46 -58
- package/dist/pack-metapackage.d.ts +22 -0
- package/dist/pack-metapackage.js +147 -0
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/readme.d.ts +71 -0
- package/dist/readme.js +310 -0
- package/dist/releasing.d.ts +8 -1
- package/dist/releasing.js +44 -14
- package/dist/workflows/definitions.d.ts +2 -2
- package/dist/workflows/definitions.js +32 -114
- package/dist/workflows/model.d.ts +6 -0
- package/dist/workflows/render.js +2 -0
- package/dist/workflows/schema/github-workflow.schema.json +2290 -0
- package/package.json +39 -14
- package/src/affected.ts +1 -1
- package/src/dev.ts +13 -2
- package/src/family.ts +1 -0
- package/src/generate-ontology.ts +4 -0
- package/src/imports/nist-sp-800-53.auto.prov.ttl +22 -0
- package/src/imports/schema-org.auto.prov.ttl +22 -0
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +100 -8
- package/src/license/PolyForm-Noncommercial-1.0.0.md +73 -0
- package/src/license/standard.ts +67 -0
- package/src/license/third-party.ts +87 -0
- package/src/license.ts +222 -0
- package/src/link.ts +4 -4
- package/src/metapackages.ts +206 -0
- package/src/mod.ts +1 -1
- package/src/pack-library.ts +52 -55
- package/src/pack-metapackage.ts +137 -0
- package/src/pins.ts +55 -10
- package/src/readme.ts +320 -0
- package/src/releasing.ts +47 -16
- package/src/workflows/definitions.ts +36 -133
- package/src/workflows/model.ts +6 -0
- package/src/workflows/render.ts +1 -0
- package/src/workflows/schema/github-workflow.schema.json +2290 -0
package/dist/pins.d.ts
CHANGED
|
@@ -1,15 +1,42 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Commons' pins as the tools read them (commons 0005-typescript-
|
|
3
|
-
*
|
|
2
|
+
* Commons' pins as the tools read them (commons 0005-typescript-practice FR-026, 0002-packaging FR-019): the `KEY=value` lines of `pins.auto.env`, the suffix of a platform's
|
|
3
|
+
* variables, and the download of a pin on a platform (its version, address, SHA-256, format and folder), all taken from the file and written nowhere else.
|
|
4
4
|
*
|
|
5
5
|
* Spec: 0001-libraries FR-006
|
|
6
6
|
*
|
|
7
7
|
* @module
|
|
8
8
|
*/
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
readonly key: string;
|
|
13
|
-
} | undefined;
|
|
9
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
10
|
+
/** The suffix of commons' pin variables for a platform (by the names `proc.build` gives); undefined where commons pins no download for it. */
|
|
11
|
+
export declare function pinSuffix(os: string, arch: string): string | undefined;
|
|
14
12
|
/** The `KEY=value` lines of an env file; comments and blank lines left out. */
|
|
15
13
|
export declare function readEnvFile(text: string): ReadonlyMap<string, string>;
|
|
14
|
+
/** The formats of what a pinned address gives. */
|
|
15
|
+
export type PinFormat = "zip" | "tar" | "file";
|
|
16
|
+
/** What a download of a pin on a platform needs. */
|
|
17
|
+
export type PinDownload = {
|
|
18
|
+
readonly version: string;
|
|
19
|
+
readonly url: string;
|
|
20
|
+
readonly sha256: string;
|
|
21
|
+
readonly format: PinFormat;
|
|
22
|
+
/** The folder of the programs inside the unpacked artifact; empty for the root. */
|
|
23
|
+
readonly binPath: string;
|
|
24
|
+
};
|
|
25
|
+
/** Why a pin has no download on a platform. */
|
|
26
|
+
export type PinProblem = {
|
|
27
|
+
readonly kind: "no-version";
|
|
28
|
+
readonly key: string;
|
|
29
|
+
} | {
|
|
30
|
+
readonly kind: "not-pinned";
|
|
31
|
+
readonly key: string;
|
|
32
|
+
readonly suffix: string;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: "bad-format";
|
|
35
|
+
readonly key: string;
|
|
36
|
+
readonly suffix: string;
|
|
37
|
+
readonly format: string;
|
|
38
|
+
};
|
|
39
|
+
/** The sentence a problem is told in. */
|
|
40
|
+
export declare function describePinProblem(p: PinProblem): string;
|
|
41
|
+
/** The download of the pin `key` (`BUN`) for the platform `suffix` (`X86_64`) as `pins.auto.env` states it, or why it has none. */
|
|
42
|
+
export declare function pinDownload(env: ReadonlyMap<string, string>, key: string, suffix: string): Result<PinDownload, PinProblem>;
|
package/dist/pins.js
CHANGED
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Commons' pins as the tools read them (commons 0005-typescript-
|
|
3
|
-
*
|
|
2
|
+
* Commons' pins as the tools read them (commons 0005-typescript-practice FR-026, 0002-packaging FR-019): the `KEY=value` lines of `pins.auto.env`, the suffix of a platform's
|
|
3
|
+
* variables, and the download of a pin on a platform (its version, address, SHA-256, format and folder), all taken from the file and written nowhere else.
|
|
4
4
|
*
|
|
5
5
|
* Spec: 0001-libraries FR-006
|
|
6
6
|
*
|
|
7
7
|
* @module
|
|
8
8
|
*/
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
import { err, ok } from "@intellectual-frontiers/core";
|
|
10
|
+
/** The suffix of commons' pin variables for a platform (by the names `proc.build` gives); undefined where commons pins no download for it. */
|
|
11
|
+
export function pinSuffix(os, arch) {
|
|
11
12
|
const table = {
|
|
12
|
-
"linux/x86_64":
|
|
13
|
-
"linux/aarch64":
|
|
14
|
-
"darwin/x86_64":
|
|
15
|
-
"darwin/aarch64":
|
|
16
|
-
"windows/x86_64":
|
|
13
|
+
"linux/x86_64": "X86_64",
|
|
14
|
+
"linux/aarch64": "AARCH64",
|
|
15
|
+
"darwin/x86_64": "MACOS_X64",
|
|
16
|
+
"darwin/aarch64": "MACOS_ARM64",
|
|
17
|
+
"windows/x86_64": "WINDOWS_X64",
|
|
17
18
|
};
|
|
18
19
|
return Object.hasOwn(table, `${os}/${arch}`) ? table[`${os}/${arch}`] : undefined;
|
|
19
20
|
}
|
|
@@ -27,3 +28,29 @@ export function readEnvFile(text) {
|
|
|
27
28
|
}
|
|
28
29
|
return out;
|
|
29
30
|
}
|
|
31
|
+
/** The sentence a problem is told in. */
|
|
32
|
+
export function describePinProblem(p) {
|
|
33
|
+
switch (p.kind) {
|
|
34
|
+
case "no-version":
|
|
35
|
+
return `commons pins no ${p.key}`;
|
|
36
|
+
case "not-pinned":
|
|
37
|
+
return `commons pins no download of ${p.key} for ${p.suffix}`;
|
|
38
|
+
case "bad-format":
|
|
39
|
+
return `commons pins ${p.key} for ${p.suffix} as ${JSON.stringify(p.format)}, which is no format (zip, tar, file)`;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/** The download of the pin `key` (`BUN`) for the platform `suffix` (`X86_64`) as `pins.auto.env` states it, or why it has none. */
|
|
43
|
+
export function pinDownload(env, key, suffix) {
|
|
44
|
+
const version = env.get(`${key}_VERSION`);
|
|
45
|
+
if (version === undefined)
|
|
46
|
+
return err({ kind: "no-version", key });
|
|
47
|
+
const url = env.get(`${key}_URL_${suffix}`);
|
|
48
|
+
const sha256 = env.get(`${key}_SHA256_${suffix}`);
|
|
49
|
+
const format = env.get(`${key}_FORMAT_${suffix}`);
|
|
50
|
+
const binPath = env.get(`${key}_BINPATH_${suffix}`);
|
|
51
|
+
if (url === undefined || sha256 === undefined || format === undefined || binPath === undefined)
|
|
52
|
+
return err({ kind: "not-pinned", key, suffix });
|
|
53
|
+
if (format !== "zip" && format !== "tar" && format !== "file")
|
|
54
|
+
return err({ kind: "bad-format", key, suffix, format });
|
|
55
|
+
return ok({ version, url, sha256, format, binPath });
|
|
56
|
+
}
|
package/dist/readme.d.ts
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { type Brand, type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type Library, type Registry } from "./libraries.js";
|
|
3
|
+
/** The marker that opens the generated table. */
|
|
4
|
+
export declare const BEGIN = "<!-- libraries-map:begin -->";
|
|
5
|
+
/** The marker that closes the generated table. */
|
|
6
|
+
export declare const END = "<!-- libraries-map:end -->";
|
|
7
|
+
/** What a library is for in the whole: a closed union. */
|
|
8
|
+
export declare const ROLES: readonly ["foundation", "pattern", "program", "standard"];
|
|
9
|
+
/** A role a reader of the README may be in, as the generated library map names them. */
|
|
10
|
+
export type Role = (typeof ROLES)[number];
|
|
11
|
+
/** The heading of a role in the table. */
|
|
12
|
+
export declare const ROLE_TITLE: Readonly<Record<Role, string>>;
|
|
13
|
+
/** A library's name (its folder), made only by {@link parseLibraryName}. */
|
|
14
|
+
export type LibraryName = Brand<string, "library name">;
|
|
15
|
+
/** A library name from text, or why the text is not one. */
|
|
16
|
+
export declare function parseLibraryName(text: string): Result<LibraryName, string>;
|
|
17
|
+
/** The role of each library, by name. A new library is classified here, or the check names it. */
|
|
18
|
+
export declare const ROLE_OF: ReadonlyMap<string, Role>;
|
|
19
|
+
/** One row of the table. */
|
|
20
|
+
export type Row = {
|
|
21
|
+
readonly name: LibraryName;
|
|
22
|
+
readonly role: Role;
|
|
23
|
+
readonly purpose: string;
|
|
24
|
+
readonly shape: string;
|
|
25
|
+
readonly level: string;
|
|
26
|
+
readonly distribution: readonly Registry[];
|
|
27
|
+
readonly published: boolean;
|
|
28
|
+
/** Why the library is held out of the release, where it is. */
|
|
29
|
+
readonly held: string | undefined;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
|
|
33
|
+
* An error where the file has no summary or it is not literals.
|
|
34
|
+
*/
|
|
35
|
+
export declare function summaryOf(source: string): Result<string, string>;
|
|
36
|
+
/** The first sentence of a text: up to the first full stop that is followed by a space or the end, outside parentheses and backticks. */
|
|
37
|
+
export declare function firstSentence(text: string): string;
|
|
38
|
+
/**
|
|
39
|
+
* The first clause of a text's first sentence: the sentence where it is short (110 characters or fewer), else the sentence cut at its first `:`, `;` or comma that is
|
|
40
|
+
* outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
|
|
41
|
+
*/
|
|
42
|
+
export declare function firstClause(text: string): string;
|
|
43
|
+
/** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
|
|
44
|
+
export declare function shapeOf(l: Library): string;
|
|
45
|
+
/** A row of the table for a library and its summary, or why there is none. */
|
|
46
|
+
export declare function rowOf(l: Library, summary: string): Result<Row, string>;
|
|
47
|
+
/** The table, as Markdown, for the rows given: sorted by role, then by name. */
|
|
48
|
+
export declare function tableOf(rows: readonly Row[]): string;
|
|
49
|
+
/** The rows of a repository, and what is wrong with reading them. */
|
|
50
|
+
export declare function rowsOf(repo: string): {
|
|
51
|
+
readonly rows: readonly Row[];
|
|
52
|
+
readonly problems: readonly string[];
|
|
53
|
+
};
|
|
54
|
+
/** One row of the table of the metapackages: the package and what it is. */
|
|
55
|
+
export type BundleRow = {
|
|
56
|
+
readonly name: string;
|
|
57
|
+
readonly purpose: string;
|
|
58
|
+
};
|
|
59
|
+
/** The rows of the metapackages of a repository, in the order of their folders' names: each the package and the first clause of the summary its manifest gives. */
|
|
60
|
+
export declare function bundlesOf(repo: string): readonly BundleRow[];
|
|
61
|
+
/** The table of the metapackages, as Markdown, with the sentence that introduces it; nothing where a repository has none. */
|
|
62
|
+
export declare function bundlesTableOf(rows: readonly BundleRow[]): string;
|
|
63
|
+
/** The README made again from its text and the table: the text between the markers (on lines of their own) replaced; an error where the markers are missing. */
|
|
64
|
+
export declare function withTable(readme: string, table: string): Result<string, string>;
|
|
65
|
+
/** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
|
|
66
|
+
export declare function synchronize(repo: string, write: boolean): {
|
|
67
|
+
readonly stale: boolean;
|
|
68
|
+
readonly problems: readonly string[];
|
|
69
|
+
};
|
|
70
|
+
/** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
|
|
71
|
+
export declare function main(argv: readonly string[]): number;
|
package/dist/readme.js
ADDED
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The map of the libraries in the root `README.md`: the table between the markers `<!-- libraries-map:begin -->` and `<!-- libraries-map:end -->`, one row for each library of `commons/`, made from
|
|
3
|
+
* the manifests (`library.ts`) and the `summary` of each library's `about.ts`, so that the first page of the repository cannot name a library that is gone or miss one that is new.
|
|
4
|
+
*
|
|
5
|
+
* bun commons/libraries/src/readme.ts write the table again from the manifests
|
|
6
|
+
* bun commons/libraries/src/readme.ts --check write nothing and exit 1 where README.md is not what the manifests make
|
|
7
|
+
* other flags: --repo DIR (the repository, the working folder by default)
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Both files are read as data and no library is run: the manifest by `readLibraries`, the summary of `about.ts` by reading the string literals that follow `summary:` (joined by `+`). A row has the library's package
|
|
11
|
+
* as a link (to npm where the library is published there, else to its folder), the first clause of the first sentence of its summary, its Kanon shape where the manifest declares a table (`layers`, and
|
|
12
|
+
* `instances` and `plugins` where it declares those), its conformance level and the registries it is published to. Rows are sorted by role, then by name; the role of a library is a closed union
|
|
13
|
+
* held in {@link ROLE_OF}, and a library with no entry there is a problem, never a row of no role. A version is not in the table: versions grow at the release, and a table that held them would be stale at every release.
|
|
14
|
+
*
|
|
15
|
+
* @limits
|
|
16
|
+
* It writes one file, README.md, and only between the markers; it does not judge the prose around them (the test of the README does).
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```ts
|
|
20
|
+
* import { firstClause } from "./readme.ts";
|
|
21
|
+
* firstClause("Mizan, the IF Spec Profile, as code. The harness holds the rules."); // "Mizan, the IF Spec Profile, as code"
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* Spec: 0001-libraries FR-017
|
|
25
|
+
*
|
|
26
|
+
* @module
|
|
27
|
+
*/
|
|
28
|
+
import process from "node:process";
|
|
29
|
+
import { absurd, err, ok, refine, string } from "@intellectual-frontiers/core";
|
|
30
|
+
import { stdio } from "@intellectual-frontiers/system";
|
|
31
|
+
import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
32
|
+
import { readLibraries } from "./libraries.js";
|
|
33
|
+
/** The marker that opens the generated table. */
|
|
34
|
+
export const BEGIN = "<!-- libraries-map:begin -->";
|
|
35
|
+
/** The marker that closes the generated table. */
|
|
36
|
+
export const END = "<!-- libraries-map:end -->";
|
|
37
|
+
/** What a library is for in the whole: a closed union. */
|
|
38
|
+
export const ROLES = ["foundation", "pattern", "program", "standard"];
|
|
39
|
+
/** The heading of a role in the table. */
|
|
40
|
+
export const ROLE_TITLE = {
|
|
41
|
+
foundation: "Foundation",
|
|
42
|
+
pattern: "Pattern",
|
|
43
|
+
program: "Program",
|
|
44
|
+
standard: "Standard",
|
|
45
|
+
};
|
|
46
|
+
const nameDecoder = refine(string, "library name", (t) => /^[a-z][a-z0-9-]*$/.test(t));
|
|
47
|
+
/** A library name from text, or why the text is not one. */
|
|
48
|
+
export function parseLibraryName(text) {
|
|
49
|
+
const r = nameDecoder(text, "name");
|
|
50
|
+
return r.kind === "ok" ? ok(r.value) : err(`${JSON.stringify(text)} is not a library name`);
|
|
51
|
+
}
|
|
52
|
+
/** The role of each library, by name. A new library is classified here, or the check names it. */
|
|
53
|
+
export const ROLE_OF = new Map([
|
|
54
|
+
["core", "foundation"],
|
|
55
|
+
["crypto", "foundation"],
|
|
56
|
+
["formats", "foundation"],
|
|
57
|
+
["githost", "foundation"],
|
|
58
|
+
["lint", "foundation"],
|
|
59
|
+
["net", "foundation"],
|
|
60
|
+
["rdf", "foundation"],
|
|
61
|
+
["system", "foundation"],
|
|
62
|
+
["telemetry", "foundation"],
|
|
63
|
+
["terminal", "foundation"],
|
|
64
|
+
["test", "foundation"],
|
|
65
|
+
["headless", "pattern"],
|
|
66
|
+
["kanon", "pattern"],
|
|
67
|
+
["archon", "program"],
|
|
68
|
+
["toolchain", "program"],
|
|
69
|
+
["archon-dialect-native-pinned", "program"],
|
|
70
|
+
["package-managers", "program"],
|
|
71
|
+
["archon-dialect-apt", "program"],
|
|
72
|
+
["archon-dialect-homebrew", "program"],
|
|
73
|
+
["archon-dialect-mise", "program"],
|
|
74
|
+
["archon-dialect-winget", "program"],
|
|
75
|
+
["archon-tool", "program"],
|
|
76
|
+
["estate", "program"],
|
|
77
|
+
["data", "program"],
|
|
78
|
+
["docs", "program"],
|
|
79
|
+
["ergonex", "program"],
|
|
80
|
+
["grc", "program"],
|
|
81
|
+
["integrations", "program"],
|
|
82
|
+
["integrations-github", "program"],
|
|
83
|
+
["libraries", "program"],
|
|
84
|
+
["repoctl", "program"],
|
|
85
|
+
["integrations-fhir", "standard"],
|
|
86
|
+
["integrations-x12", "standard"],
|
|
87
|
+
["mizan", "standard"],
|
|
88
|
+
["ontology", "standard"],
|
|
89
|
+
["quality", "standard"],
|
|
90
|
+
]);
|
|
91
|
+
const roleRank = (r) => {
|
|
92
|
+
switch (r) {
|
|
93
|
+
case "foundation":
|
|
94
|
+
return 0;
|
|
95
|
+
case "pattern":
|
|
96
|
+
return 1;
|
|
97
|
+
case "program":
|
|
98
|
+
return 2;
|
|
99
|
+
case "standard":
|
|
100
|
+
return 3;
|
|
101
|
+
default:
|
|
102
|
+
return absurd(r);
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
|
|
107
|
+
* An error where the file has no summary or it is not literals.
|
|
108
|
+
*/
|
|
109
|
+
export function summaryOf(source) {
|
|
110
|
+
const m = /\bsummary:\s*/.exec(source);
|
|
111
|
+
if (m === null)
|
|
112
|
+
return err("it has no summary");
|
|
113
|
+
let at = m.index + m[0].length;
|
|
114
|
+
const parts = [];
|
|
115
|
+
for (;;) {
|
|
116
|
+
const lit = /^"(?:[^"\\\n]|\\.)*"/.exec(source.slice(at));
|
|
117
|
+
if (lit === null)
|
|
118
|
+
return err("its summary is not a string literal");
|
|
119
|
+
try {
|
|
120
|
+
const v = JSON.parse(lit[0]);
|
|
121
|
+
if (typeof v !== "string")
|
|
122
|
+
return err("its summary is not a string literal");
|
|
123
|
+
parts.push(v);
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return err("its summary is not a string literal");
|
|
127
|
+
}
|
|
128
|
+
at += lit[0].length;
|
|
129
|
+
const plus = /^\s*\+\s*/.exec(source.slice(at));
|
|
130
|
+
if (plus === null)
|
|
131
|
+
break;
|
|
132
|
+
at += plus[0].length;
|
|
133
|
+
}
|
|
134
|
+
return ok(parts.join(""));
|
|
135
|
+
}
|
|
136
|
+
/** The first sentence of a text: up to the first full stop that is followed by a space or the end, outside parentheses and backticks. */
|
|
137
|
+
export function firstSentence(text) {
|
|
138
|
+
let depth = 0;
|
|
139
|
+
let tick = false;
|
|
140
|
+
for (let i = 0; i < text.length; i++) {
|
|
141
|
+
const c = text.charAt(i);
|
|
142
|
+
if (c === "`")
|
|
143
|
+
tick = !tick;
|
|
144
|
+
else if (tick)
|
|
145
|
+
continue;
|
|
146
|
+
else if (c === "(")
|
|
147
|
+
depth++;
|
|
148
|
+
else if (c === ")")
|
|
149
|
+
depth = Math.max(0, depth - 1);
|
|
150
|
+
else if (c === "." && depth === 0 && (i + 1 === text.length || /\s/.test(text.charAt(i + 1))))
|
|
151
|
+
return text.slice(0, i);
|
|
152
|
+
}
|
|
153
|
+
return text.trim();
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* The first clause of a text's first sentence: the sentence where it is short (110 characters or fewer), else the sentence cut at its first `:`, `;` or comma that is
|
|
157
|
+
* outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
|
|
158
|
+
*/
|
|
159
|
+
export function firstClause(text) {
|
|
160
|
+
const sentence = firstSentence(text).replace(/\s+/g, " ").trim();
|
|
161
|
+
if (sentence.length <= 110)
|
|
162
|
+
return sentence;
|
|
163
|
+
let depth = 0;
|
|
164
|
+
let tick = false;
|
|
165
|
+
for (let i = 0; i < sentence.length; i++) {
|
|
166
|
+
const c = sentence.charAt(i);
|
|
167
|
+
if (c === "`")
|
|
168
|
+
tick = !tick;
|
|
169
|
+
else if (tick)
|
|
170
|
+
continue;
|
|
171
|
+
else if (c === "(")
|
|
172
|
+
depth++;
|
|
173
|
+
else if (c === ")")
|
|
174
|
+
depth = Math.max(0, depth - 1);
|
|
175
|
+
else if (depth === 0 && i >= 25 && (c === ":" || c === ";" || c === ","))
|
|
176
|
+
return sentence.slice(0, i);
|
|
177
|
+
}
|
|
178
|
+
return sentence;
|
|
179
|
+
}
|
|
180
|
+
/** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
|
|
181
|
+
export function shapeOf(l) {
|
|
182
|
+
const t = l.kanon;
|
|
183
|
+
if (t === undefined)
|
|
184
|
+
return "-";
|
|
185
|
+
const parts = ["layers", ...(t.instances.length > 0 ? ["instances"] : []), ...(t.plugins.length > 0 ? ["plugins"] : []), ...(t.extends === undefined ? [] : ["extension"])];
|
|
186
|
+
return parts.join(", ");
|
|
187
|
+
}
|
|
188
|
+
/** A row of the table for a library and its summary, or why there is none. */
|
|
189
|
+
export function rowOf(l, summary) {
|
|
190
|
+
const name = parseLibraryName(l.name);
|
|
191
|
+
if (name.kind === "err")
|
|
192
|
+
return name;
|
|
193
|
+
const role = ROLE_OF.get(l.name);
|
|
194
|
+
if (role === undefined)
|
|
195
|
+
return err(`commons/${l.name} has no role in ROLE_OF (commons/libraries/src/readme.ts): say whether it is a foundation, a pattern, a program or a standard`);
|
|
196
|
+
return ok({
|
|
197
|
+
name: name.value,
|
|
198
|
+
role,
|
|
199
|
+
purpose: firstClause(summary).replace(/\|/g, "\\|"),
|
|
200
|
+
shape: shapeOf(l),
|
|
201
|
+
level: l.level,
|
|
202
|
+
distribution: l.distribution,
|
|
203
|
+
published: l.held === undefined && l.distribution.includes("npm"),
|
|
204
|
+
held: l.held,
|
|
205
|
+
});
|
|
206
|
+
}
|
|
207
|
+
const REGISTRY_TITLE = { github: "GitHub", npm: "npm" };
|
|
208
|
+
/** The table, as Markdown, for the rows given: sorted by role, then by name. */
|
|
209
|
+
export function tableOf(rows) {
|
|
210
|
+
const sorted = [...rows].sort((a, b) => roleRank(a.role) - roleRank(b.role) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
211
|
+
const head = ["| Library | Role | What it is | Kanon | Level | Published to |", "| --- | --- | --- | --- | --- | --- |"];
|
|
212
|
+
const body = sorted.map((r) => {
|
|
213
|
+
const pkg = `@intellectual-frontiers/${r.name}`;
|
|
214
|
+
const href = r.published ? `https://www.npmjs.com/package/${pkg}` : `commons/${r.name}`;
|
|
215
|
+
return `| [\`${pkg}\`](${href}) | ${ROLE_TITLE[r.role]} | ${r.purpose} | ${r.shape} | ${r.level} | ${r.held === undefined ? r.distribution.map((d) => REGISTRY_TITLE[d]).join(", ") : "held"} |`;
|
|
216
|
+
});
|
|
217
|
+
return [...head, ...body].join("\n");
|
|
218
|
+
}
|
|
219
|
+
/** The rows of a repository, and what is wrong with reading them. */
|
|
220
|
+
export function rowsOf(repo) {
|
|
221
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
222
|
+
const rows = [];
|
|
223
|
+
const problems = [];
|
|
224
|
+
for (const f of readLibraries(root)) {
|
|
225
|
+
if ("problem" in f) {
|
|
226
|
+
problems.push(`commons/${f.dir}/library.ts: ${f.problem}`);
|
|
227
|
+
continue;
|
|
228
|
+
}
|
|
229
|
+
if (f.library.bundle !== undefined)
|
|
230
|
+
continue; // a metapackage has no about.ts and is listed by {@link bundlesOf}
|
|
231
|
+
const file = `${root}/commons/${f.dir}/about.ts`;
|
|
232
|
+
if (!existsSync(file)) {
|
|
233
|
+
problems.push(`commons/${f.dir}/about.ts is missing: the table takes its purpose from the summary there`);
|
|
234
|
+
continue;
|
|
235
|
+
}
|
|
236
|
+
const s = summaryOf(readTextFileSync(file));
|
|
237
|
+
if (s.kind === "err") {
|
|
238
|
+
problems.push(`commons/${f.dir}/about.ts: ${s.error}`);
|
|
239
|
+
continue;
|
|
240
|
+
}
|
|
241
|
+
const r = rowOf(f.library, s.value);
|
|
242
|
+
if (r.kind === "err")
|
|
243
|
+
problems.push(r.error);
|
|
244
|
+
else
|
|
245
|
+
rows.push(r.value);
|
|
246
|
+
}
|
|
247
|
+
return { rows, problems };
|
|
248
|
+
}
|
|
249
|
+
/** The rows of the metapackages of a repository, in the order of their folders' names: each the package and the first clause of the summary its manifest gives. */
|
|
250
|
+
export function bundlesOf(repo) {
|
|
251
|
+
const rows = [];
|
|
252
|
+
for (const f of readLibraries(repo.replace(/[\\/]$/, ""))) {
|
|
253
|
+
if ("problem" in f || f.library.bundle === undefined)
|
|
254
|
+
continue;
|
|
255
|
+
rows.push({ name: f.library.name, purpose: firstClause(f.library.summary ?? "").replace(/\|/g, "\\|") });
|
|
256
|
+
}
|
|
257
|
+
return rows;
|
|
258
|
+
}
|
|
259
|
+
/** The table of the metapackages, as Markdown, with the sentence that introduces it; nothing where a repository has none. */
|
|
260
|
+
export function bundlesTableOf(rows) {
|
|
261
|
+
if (rows.length === 0)
|
|
262
|
+
return "";
|
|
263
|
+
const body = rows.map((r) => `| [\`@intellectual-frontiers/${r.name}\`](https://www.npmjs.com/package/@intellectual-frontiers/${r.name}) | ${r.purpose} |`);
|
|
264
|
+
return [
|
|
265
|
+
"Metapackages: no code of their own, each depends on a set of the libraries above at exact versions (commons 0036-distribution). Install one of them, or a library.",
|
|
266
|
+
"",
|
|
267
|
+
"| Metapackage | What it holds |",
|
|
268
|
+
"| --- | --- |",
|
|
269
|
+
...body,
|
|
270
|
+
].join("\n");
|
|
271
|
+
}
|
|
272
|
+
/** The README made again from its text and the table: the text between the markers (on lines of their own) replaced; an error where the markers are missing. */
|
|
273
|
+
export function withTable(readme, table) {
|
|
274
|
+
const from = readme.indexOf(`\n${BEGIN}\n`);
|
|
275
|
+
const to = readme.indexOf(`\n${END}\n`, from);
|
|
276
|
+
if (from < 0 || to < 0)
|
|
277
|
+
return err(`README.md has no ${BEGIN} and ${END}, each on a line of its own, around the table of the libraries`);
|
|
278
|
+
return ok(`${readme.slice(0, from + 1 + BEGIN.length)}\n\n${table}\n\n${readme.slice(to + 1)}`);
|
|
279
|
+
}
|
|
280
|
+
/** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
|
|
281
|
+
export function synchronize(repo, write) {
|
|
282
|
+
const root = repo.replace(/[\\/]$/, "");
|
|
283
|
+
const file = `${root}/README.md`;
|
|
284
|
+
const { rows, problems } = rowsOf(root);
|
|
285
|
+
if (!existsSync(file))
|
|
286
|
+
return { stale: false, problems: [...problems, "README.md is missing"] };
|
|
287
|
+
const text = readTextFileSync(file).replace(/\r\n/g, "\n");
|
|
288
|
+
const bundles = bundlesTableOf(bundlesOf(root));
|
|
289
|
+
const made = withTable(text, bundles === "" ? tableOf(rows) : `${tableOf(rows)}\n\n${bundles}`);
|
|
290
|
+
if (made.kind === "err")
|
|
291
|
+
return { stale: false, problems: [...problems, made.error] };
|
|
292
|
+
const stale = made.value !== text;
|
|
293
|
+
if (stale && write && problems.length === 0)
|
|
294
|
+
writeTextFileSync(file, made.value);
|
|
295
|
+
return { stale, problems };
|
|
296
|
+
}
|
|
297
|
+
/** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
|
|
298
|
+
export function main(argv) {
|
|
299
|
+
const at = argv.indexOf("--repo");
|
|
300
|
+
const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
|
|
301
|
+
const check = argv.includes("--check");
|
|
302
|
+
const r = synchronize(repo, !check);
|
|
303
|
+
for (const p of r.problems)
|
|
304
|
+
stdio.stderr.writeSync(`${p}\n`);
|
|
305
|
+
if (r.stale)
|
|
306
|
+
stdio.stderr.writeSync(check ? "README.md is not what the manifests make; run: bun commons/libraries/src/readme.ts\n" : "wrote README.md\n");
|
|
307
|
+
return r.problems.length > 0 || (check && r.stale) ? 1 : 0;
|
|
308
|
+
}
|
|
309
|
+
if (import.meta.main)
|
|
310
|
+
process.exitCode = main(process.argv.slice(2));
|
package/dist/releasing.d.ts
CHANGED
|
@@ -2,12 +2,15 @@ import { type Result } from "@intellectual-frontiers/core";
|
|
|
2
2
|
import { type Look } from "@intellectual-frontiers/system/tty";
|
|
3
3
|
import { type Slug } from "@intellectual-frontiers/mizan/versions/record";
|
|
4
4
|
import { type Impact } from "@intellectual-frontiers/mizan/versions/scheme";
|
|
5
|
+
import { type VersionConstant } from "./libraries.js";
|
|
5
6
|
/** The record of the release, from the repository's root. */
|
|
6
7
|
export declare const RECORD_PATH = "commons/generated/release.auto.json";
|
|
7
8
|
/** What the plan knows of a library: its version, what it imports, the last tag of it, whether its files changed since, and the impact the commits since state. */
|
|
8
9
|
export type Facts = {
|
|
9
10
|
readonly slug: Slug;
|
|
10
11
|
readonly folder: string;
|
|
12
|
+
/** The package the library publishes: `@intellectual-frontiers/<slug>`, or the one its manifest names in `publishes` (commons 0036-distribution FR-009). */
|
|
13
|
+
readonly package: string;
|
|
11
14
|
readonly version: string;
|
|
12
15
|
/** The libraries (by slug) whose package its own sources import. */
|
|
13
16
|
readonly imports: readonly Slug[];
|
|
@@ -55,6 +58,7 @@ export type Decision = {
|
|
|
55
58
|
export type Step = {
|
|
56
59
|
readonly slug: Slug;
|
|
57
60
|
readonly folder: string;
|
|
61
|
+
readonly package: string;
|
|
58
62
|
readonly from: string;
|
|
59
63
|
readonly to: string;
|
|
60
64
|
readonly tag: string;
|
|
@@ -80,6 +84,7 @@ export declare function recordText(plan: Plan): string;
|
|
|
80
84
|
/** One entry of the record, as the workflow reads it. */
|
|
81
85
|
export type Entry = {
|
|
82
86
|
readonly slug: string;
|
|
87
|
+
readonly package: string;
|
|
83
88
|
readonly version: string;
|
|
84
89
|
readonly folder: string;
|
|
85
90
|
readonly tag: string;
|
|
@@ -91,6 +96,8 @@ export declare function readRecord(text: string): Result<readonly Entry[], strin
|
|
|
91
96
|
export declare function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string;
|
|
92
97
|
/** Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not. */
|
|
93
98
|
export declare function writeVersion(repo: string, step: Step): Result<readonly string[], string>;
|
|
99
|
+
/** Writes the new version into a constant of the library's sources that holds it (`export const NAME = "1.2.3"`); the file's path from the root, or the problem where the file or the constant is not there. */
|
|
100
|
+
export declare function writeConstant(repo: string, step: Step, c: VersionConstant): Result<string, string>;
|
|
94
101
|
/** What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder `package/`), and the text of its `package.json`. */
|
|
95
102
|
export type Tarball = {
|
|
96
103
|
readonly hashes: ReadonlyMap<string, string>;
|
|
@@ -107,7 +114,7 @@ export declare function driftOf(published: Tarball, local: {
|
|
|
107
114
|
readonly packageJson: string;
|
|
108
115
|
}): "same" | "differs";
|
|
109
116
|
/** Compares a library's version with what npm holds of it. */
|
|
110
|
-
export type Registry = (
|
|
117
|
+
export type Registry = (pkg: string, version: string, folder: string) => Promise<Drift>;
|
|
111
118
|
/** The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under `repo`; anything that goes wrong is `unknown`, never a guess. */
|
|
112
119
|
export declare function realRegistry(repo: string): Registry;
|
|
113
120
|
/** What the host gives the plan: the facts of the libraries from the tags and the tree. */
|