@intellectual-frontiers/libraries 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,204 @@
1
+ /**
2
+ * The license of the repository and of every library in it, written and checked from one place (commons 0035-licensing). One official text, the PolyForm Noncommercial License 1.0.0
3
+ * (`license/PolyForm-Noncommercial-1.0.0.md`, held to the SHA-256 of its standard), and one `Required Notice:` line for the licensor make the `LICENSE` of the root and of each library folder; the third-party
4
+ * notices are made from the record of what is vendored.
5
+ *
6
+ * bun commons/libraries/src/license.ts write every LICENSE and THIRD_PARTY_NOTICES.md again
7
+ * bun commons/libraries/src/license.ts --check write nothing and exit 1 where any file is not what the manifests and the official text make
8
+ * other flags: --repo DIR (the repository, the working folder by default)
9
+ *
10
+ * @remarks
11
+ * What is written: `LICENSE` at the root and in each `commons/<name>/` that holds a manifest (`library.ts`), and `THIRD_PARTY_NOTICES.md`. What is only checked, because a person writes it: `LICENSING.md`, `COMMERCIAL.md`,
12
+ * `NOTICE`, `CONTRIBUTING.md`, `CITATION.cff`, the License section of `README.md` and the `license` of the root `package.json`. A library with a folder and no `LICENSE` is a finding that names the command above, so a new
13
+ * library runs it once. The packer writes the same identifier into the `package.json` it publishes ({@link licenseOf}).
14
+ *
15
+ * @limits
16
+ * It does not fetch anything: the official text is the copy in `license/`, checked against the SHA-256 its standard records. It does not judge what the hand-written files say beyond the few facts named in {@link Finding}.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * import { licenseFileText } from "./license.ts";
21
+ * licenseFileText("TEXT\n").startsWith("Required Notice: Copyright Intellectual Frontiers LLC"); // true
22
+ * ```
23
+ *
24
+ * Spec: 0001-libraries FR-019
25
+ *
26
+ * @module
27
+ */
28
+ import process from "node:process";
29
+ import { absurd, err, ok } from "@intellectual-frontiers/core";
30
+ import { sha256 } from "@intellectual-frontiers/crypto/sha256";
31
+ import { stdio } from "@intellectual-frontiers/system";
32
+ import { existsSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
33
+ import { fromFileUrl, join, resolve } from "@intellectual-frontiers/system/path";
34
+ import { readLibraries } from "./libraries.js";
35
+ import { COMMERCIAL_ISSUES_URL, DEFAULT_LICENSE, LICENSE_STANDARDS, LICENSOR, REPOSITORY_URL } from "./license/standard.js";
36
+ import { THIRD_PARTY } from "./license/third-party.js";
37
+ /** The command that writes what the check finds wrong. */
38
+ export const COMMAND = "bun commons/libraries/src/license.ts";
39
+ /** The license of a library: its manifest's `license`, else the default of the repository. */
40
+ export function licenseOf(library) {
41
+ return library?.license ?? DEFAULT_LICENSE;
42
+ }
43
+ /** The line every `LICENSE` begins with, as the license asks of its licensor (its section Notices). */
44
+ export const REQUIRED_NOTICE = `Required Notice: Copyright ${LICENSOR} (${REPOSITORY_URL})`;
45
+ /** The text of a `LICENSE`: the required notice, a blank line and the official text exactly as it is. */
46
+ export function licenseFileText(official) {
47
+ return `${REQUIRED_NOTICE}\n\n${official}`;
48
+ }
49
+ /** The one sentence of a finding. */
50
+ export function sentence(f) {
51
+ switch (f.kind) {
52
+ case "text-missing":
53
+ return `the official text of ${f.id} is not at commons/libraries/src/license/${f.file}`;
54
+ case "text-changed":
55
+ return `commons/libraries/src/license/ is not the official text of the standard: its SHA-256 is ${f.have} and the standard records ${f.want}`;
56
+ case "manifest":
57
+ return `commons/${f.dir}/library.ts cannot be read: ${f.problem}`;
58
+ case "missing":
59
+ return `${f.path} is missing: ${f.why}`;
60
+ case "stale":
61
+ return `${f.path} is not what the official text and the manifest make; run: ${COMMAND}`;
62
+ case "lacks":
63
+ return `${f.path} does not ${f.what}`;
64
+ case "vendored-gone":
65
+ return `${f.path} is named as vendored in commons/libraries/src/license/third-party.ts and is not in the repository`;
66
+ default:
67
+ return absurd(f);
68
+ }
69
+ }
70
+ const lf = (t) => t.replaceAll("\r\n", "\n");
71
+ const here = resolve(fromFileUrl(new URL(".", import.meta.url)));
72
+ /** The official text of a license, held to the SHA-256 of its standard. */
73
+ export async function officialText(id, folder = join(here, "license")) {
74
+ const std = LICENSE_STANDARDS[id];
75
+ const file = join(folder, std.file);
76
+ if (!existsSync(file))
77
+ return err({ kind: "text-missing", id, file: std.file });
78
+ const text = lf(readTextFileSync(file));
79
+ const have = await sha256(text);
80
+ return have === std.sha256 ? ok(text) : err({ kind: "text-changed", id, want: std.sha256, have });
81
+ }
82
+ /** `THIRD_PARTY_NOTICES.md` made from the items. */
83
+ export function thirdPartyNotices(items) {
84
+ const body = items.map((i) => [
85
+ `## ${i.path === undefined ? i.what.split(",")[0] ?? i.what : `\`${i.path}\``}`,
86
+ "",
87
+ `- **What**: ${i.what}.`,
88
+ `- **Source**: ${i.source}.`,
89
+ `- **Owner**: ${i.owner}.`,
90
+ `- **License**: ${i.license}.`,
91
+ `- **Checked**: ${i.checked}`,
92
+ "",
93
+ ].join("\n"));
94
+ return [
95
+ "# Third-party notices",
96
+ "",
97
+ "<!-- Generated by `bun commons/libraries/src/license.ts` from `commons/libraries/src/license/third-party.ts`: change that file and run the command, never this one. -->",
98
+ "",
99
+ "Intellectual Frontiers LLC owns the code of this repository, which is under the PolyForm Noncommercial License 1.0.0 (see [`LICENSE`](LICENSE)). The items below are not its own: each is under the license named, which is not changed by this repository's.",
100
+ "Where an item says `unverified:` the license was recorded from a secondary source and has not been checked against the original; that is for the owner to settle, and nothing here is a statement that it is settled.",
101
+ "",
102
+ "Packages installed from a registry (listed in `bun.lock`) are not vendored: nothing of them is in this repository, and each package carries its own license.",
103
+ "",
104
+ ...body,
105
+ ].join("\n");
106
+ }
107
+ const read = (repo, path) => (existsSync(join(repo, path)) ? lf(readTextFileSync(join(repo, path))) : undefined);
108
+ const HAND_WRITTEN = [
109
+ { path: "LICENSING.md", why: "it says in plain words what is free and what needs a commercial license" },
110
+ { path: "COMMERCIAL.md", why: "it says what a commercial license covers and how it is obtained" },
111
+ { path: "NOTICE", why: "it carries the copyright of the licensor" },
112
+ { path: "CONTRIBUTING.md", why: "it carries the sign-off and the contributor's agreement" },
113
+ { path: "CITATION.cff", why: "it says how to cite the software and under what license" },
114
+ ];
115
+ /** Whether `text` contains `needle`, as a finding where it does not. */
116
+ const must = (path, text, needle, what) => text === undefined || text.includes(needle) ? [] : [{ kind: "lacks", path, what }];
117
+ /** The files this module makes for a repository and what is wrong with the rest, read from the files and the manifests; nothing is written. */
118
+ export async function judge(repo, folder) {
119
+ const root = repo.replace(/[\\/]$/, "");
120
+ const findings = [];
121
+ const made = [];
122
+ const texts = new Map();
123
+ const reported = new Set();
124
+ const textOf = async (id) => {
125
+ const have = texts.get(id);
126
+ if (have !== undefined)
127
+ return have;
128
+ const r = await officialText(id, folder);
129
+ if (r.kind === "err") {
130
+ if (!reported.has(id))
131
+ findings.push(r.error);
132
+ reported.add(id);
133
+ return undefined;
134
+ }
135
+ texts.set(id, r.value);
136
+ return r.value;
137
+ };
138
+ const rootText = await textOf(DEFAULT_LICENSE);
139
+ if (rootText !== undefined)
140
+ made.push({ path: "LICENSE", text: licenseFileText(rootText) });
141
+ for (const f of readLibraries(root)) {
142
+ if ("problem" in f) {
143
+ findings.push({ kind: "manifest", dir: f.dir, problem: f.problem });
144
+ continue;
145
+ }
146
+ const t = await textOf(licenseOf(f.library));
147
+ if (t !== undefined)
148
+ made.push({ path: `commons/${f.dir}/LICENSE`, text: licenseFileText(t) });
149
+ }
150
+ made.push({ path: "THIRD_PARTY_NOTICES.md", text: thirdPartyNotices(THIRD_PARTY) });
151
+ for (const m of made) {
152
+ const have = read(root, m.path);
153
+ if (have === undefined)
154
+ findings.push({ kind: "missing", path: m.path, why: m.path === "THIRD_PARTY_NOTICES.md" ? "it lists what is vendored and its licenses" : `it is the license of ${m.path === "LICENSE" ? "the repository" : "the library"}; run: ${COMMAND}` });
155
+ else if (have !== m.text)
156
+ findings.push({ kind: "stale", path: m.path });
157
+ }
158
+ for (const h of HAND_WRITTEN) {
159
+ const t = read(root, h.path);
160
+ if (t === undefined || t.trim() === "")
161
+ findings.push({ kind: "missing", path: h.path, why: h.why });
162
+ }
163
+ findings.push(...must("NOTICE", read(root, "NOTICE"), `Copyright ${LICENSOR}`, `name the copyright of ${LICENSOR}`));
164
+ findings.push(...must("CONTRIBUTING.md", read(root, "CONTRIBUTING.md"), "git commit -s", "ask for a sign-off with `git commit -s`"));
165
+ findings.push(...must("LICENSING.md", read(root, "LICENSING.md"), DEFAULT_LICENSE, `name ${DEFAULT_LICENSE}`));
166
+ findings.push(...must("LICENSING.md", read(root, "LICENSING.md"), COMMERCIAL_ISSUES_URL, `say where to ask for a commercial license (${COMMERCIAL_ISSUES_URL})`));
167
+ findings.push(...must("CITATION.cff", read(root, "CITATION.cff"), `license: ${DEFAULT_LICENSE}`, `carry \`license: ${DEFAULT_LICENSE}\``));
168
+ const readme = read(root, "README.md");
169
+ if (readme !== undefined) {
170
+ const at = readme.indexOf("\n## License\n");
171
+ const rest = at < 0 ? "" : readme.slice(at + 1);
172
+ const next = rest.indexOf("\n## ", 1);
173
+ const section = next < 0 ? rest : rest.slice(0, next);
174
+ if (at < 0 || !section.includes(DEFAULT_LICENSE))
175
+ findings.push({ kind: "lacks", path: "README.md", what: `have a License section that names ${DEFAULT_LICENSE}` });
176
+ }
177
+ const pkg = read(root, "package.json");
178
+ if (pkg !== undefined && !pkg.includes(`"license": "${DEFAULT_LICENSE}"`))
179
+ findings.push({ kind: "lacks", path: "package.json", what: `declare "license": "${DEFAULT_LICENSE}"` });
180
+ for (const i of THIRD_PARTY)
181
+ if (i.path !== undefined && !existsSync(join(root, i.path)))
182
+ findings.push({ kind: "vendored-gone", path: i.path });
183
+ return { made, findings };
184
+ }
185
+ /** The command line: 0, or 1 where a finding exists (with `--check`) or a file could not be made. Without `--check` the files are written. */
186
+ export async function main(argv) {
187
+ const at = argv.indexOf("--repo");
188
+ const repo = at >= 0 ? (argv[at + 1] ?? ".") : ".";
189
+ const check = argv.includes("--check");
190
+ let j = await judge(repo);
191
+ if (!check) {
192
+ for (const m of j.made) {
193
+ const have = read(repo, m.path);
194
+ if (have !== m.text)
195
+ writeTextFileSync(join(repo.replace(/[\\/]$/, ""), m.path), m.text);
196
+ }
197
+ j = await judge(repo);
198
+ }
199
+ for (const f of j.findings)
200
+ stdio.stderr.writeSync(`${sentence(f)}\n`);
201
+ return j.findings.length > 0 ? 1 : 0;
202
+ }
203
+ if (import.meta.main)
204
+ process.exitCode = await main(process.argv.slice(2));
@@ -20,12 +20,14 @@ export declare function inspectPackage(stage: string): Findings;
20
20
  export declare function rewriteDeclarationSpecifiers(source: string): string;
21
21
  /** The tarball's name for a package: `@scope/name` at a version is `scope-name-version.tgz`. */
22
22
  export declare const tarballName: (name: string, version: string) => string;
23
+ /** What packing a library made: the staging folder, the tarball, the findings and the manifest. */
23
24
  export type Packed = {
24
25
  readonly stage: string;
25
26
  readonly tarball: string | undefined;
26
27
  readonly findings: Findings;
27
28
  readonly manifest: Json;
28
29
  };
30
+ /** What packing a library is told: its folder, where to stage it and whether to make the tarball. */
29
31
  export type PackOptions = {
30
32
  /** Types the compiler is given (`["node"]` for a library that names Node's). */
31
33
  readonly types?: readonly string[];
@@ -24,6 +24,8 @@
24
24
  */
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
+ import { decodeLibrarySource, LIBRARY_FILE } from "./libraries.js";
28
+ import { COMMAND as LICENSE_COMMAND, licenseOf } from "./license.js";
27
29
  import { basename, dirname, join, relative, resolve, toPosix } from "@intellectual-frontiers/system/path";
28
30
  import { env, run, which } from "@intellectual-frontiers/system/proc";
29
31
  /** The scope of the packages of commons. */
@@ -285,6 +287,14 @@ function namesNodeTypes(folder) {
285
287
  }
286
288
  return false;
287
289
  }
290
+ /** The manifest of the library at `root`, where it has one that can be read. */
291
+ function manifestOf(root) {
292
+ const file = join(root, LIBRARY_FILE);
293
+ if (!existsSync(file))
294
+ return undefined;
295
+ const r = decodeLibrarySource(readTextFileSync(file));
296
+ return r.kind === "ok" ? r.value : undefined;
297
+ }
288
298
  /** 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. */
289
299
  export async function packLibrary(root, options = {}) {
290
300
  const own = JSON.parse(readTextFileSync(join(root, "package.json")));
@@ -438,7 +448,7 @@ export async function packLibrary(root, options = {}) {
438
448
  name,
439
449
  version: text(own["version"]),
440
450
  description: text(own["description"]),
441
- license: "MIT",
451
+ license: licenseOf(manifestOf(root)),
442
452
  type: "module",
443
453
  engines: { node: ">=26" },
444
454
  sideEffects: false,
@@ -477,7 +487,10 @@ export async function packLibrary(root, options = {}) {
477
487
  `Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/${short}`,
478
488
  "",
479
489
  ].join("\n"));
480
- copyFileSync(existsSync(join(root, "LICENSE")) ? join(root, "LICENSE") : join(commons, "ergonex", "LICENSE"), join(stage, "LICENSE"));
490
+ if (existsSync(join(root, "LICENSE")))
491
+ copyFileSync(join(root, "LICENSE"), join(stage, "LICENSE"));
492
+ else
493
+ findings.push(`commons/${short} has no LICENSE; run: ${LICENSE_COMMAND}`);
481
494
  findings.push(...inspectPackage(stage));
482
495
  if (findings.length > 0)
483
496
  return { stage, tarball: undefined, findings, manifest };
package/dist/pins.d.ts CHANGED
@@ -1,15 +1,42 @@
1
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.
2
+ * Commons' pins as the tools read them (commons 0005-typescript-runtime 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
- /** 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. */
10
- export declare function bunTarget(os: string, arch: string): {
11
- readonly target: string;
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-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.
2
+ * Commons' pins as the tools read them (commons 0005-typescript-runtime 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
- /** 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. */
10
- export function bunTarget(os, arch) {
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": { target: "linux-x64", key: "X86_64" },
13
- "linux/aarch64": { target: "linux-aarch64", key: "AARCH64" },
14
- "darwin/x86_64": { target: "darwin-x64", key: "MACOS_X64" },
15
- "darwin/aarch64": { target: "darwin-aarch64", key: "MACOS_ARM64" },
16
- "windows/x86_64": { target: "windows-x64", key: "WINDOWS_X64" },
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
+ }
@@ -0,0 +1,59 @@
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, and the one that closes it. */
4
+ export declare const BEGIN = "<!-- libraries-map:begin -->";
5
+ export declare const END = "<!-- libraries-map:end -->";
6
+ /** What a library is for in the whole: a closed union. */
7
+ export declare const ROLES: readonly ["foundation", "pattern", "program", "standard"];
8
+ /** A role a reader of the README may be in, as the generated library map names them. */
9
+ export type Role = (typeof ROLES)[number];
10
+ /** The heading of a role in the table. */
11
+ export declare const ROLE_TITLE: Readonly<Record<Role, string>>;
12
+ /** A library's name (its folder), made only by {@link parseLibraryName}. */
13
+ export type LibraryName = Brand<string, "library name">;
14
+ /** A library name from text, or why the text is not one. */
15
+ export declare function parseLibraryName(text: string): Result<LibraryName, string>;
16
+ /** The role of each library, by name. A new library is classified here, or the check names it. */
17
+ export declare const ROLE_OF: ReadonlyMap<string, Role>;
18
+ /** One row of the table. */
19
+ export type Row = {
20
+ readonly name: LibraryName;
21
+ readonly role: Role;
22
+ readonly purpose: string;
23
+ readonly shape: string;
24
+ readonly level: string;
25
+ readonly distribution: readonly Registry[];
26
+ readonly published: boolean;
27
+ };
28
+ /**
29
+ * The `summary` of an `about.ts`, read as data: the double-quoted string literals after `summary:`, joined by `+`, and nothing run.
30
+ * An error where the file has no summary or it is not literals.
31
+ */
32
+ export declare function summaryOf(source: string): Result<string, string>;
33
+ /** 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. */
34
+ export declare function firstSentence(text: string): string;
35
+ /**
36
+ * 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
37
+ * outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.
38
+ */
39
+ export declare function firstClause(text: string): string;
40
+ /** The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table. */
41
+ export declare function shapeOf(l: Library): string;
42
+ /** A row of the table for a library and its summary, or why there is none. */
43
+ export declare function rowOf(l: Library, summary: string): Result<Row, string>;
44
+ /** The table, as Markdown, for the rows given: sorted by role, then by name. */
45
+ export declare function tableOf(rows: readonly Row[]): string;
46
+ /** The rows of a repository, and what is wrong with reading them. */
47
+ export declare function rowsOf(repo: string): {
48
+ readonly rows: readonly Row[];
49
+ readonly problems: readonly string[];
50
+ };
51
+ /** 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. */
52
+ export declare function withTable(readme: string, table: string): Result<string, string>;
53
+ /** The result of a run: whether README.md is stale, and the problems found. With `write`, the file is written where it is stale. */
54
+ export declare function synchronize(repo: string, write: boolean): {
55
+ readonly stale: boolean;
56
+ readonly problems: readonly string[];
57
+ };
58
+ /** The command line: 0, or 1 where a problem was found or, with `--check`, README.md is not what the manifests make. */
59
+ export declare function main(argv: readonly string[]): number;