@intellectual-frontiers/libraries 0.2.1 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -21
- package/dist/affected.d.ts +15 -2
- package/dist/affected.js +51 -20
- package/dist/dev.d.ts +83 -0
- package/dist/dev.js +359 -0
- package/dist/family.d.ts +58 -0
- package/dist/family.js +125 -0
- package/dist/generate-ontology.js +4 -0
- package/dist/generate-workflows.js +2 -10
- package/dist/install-bun.js +19 -14
- package/dist/libraries.d.ts +8 -0
- package/dist/libraries.js +24 -3
- 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 +12 -0
- package/dist/link.js +98 -0
- package/dist/pack-library.d.ts +2 -0
- package/dist/pack-library.js +21 -3
- package/dist/pins.d.ts +34 -7
- package/dist/pins.js +36 -9
- package/dist/plan.d.ts +28 -0
- package/dist/plan.js +135 -0
- package/dist/readme.d.ts +59 -0
- package/dist/readme.js +272 -0
- package/dist/releasing.d.ts +176 -0
- package/dist/releasing.js +680 -0
- package/dist/versions.js +4 -7
- package/dist/workflows/definitions.d.ts +33 -30
- package/dist/workflows/definitions.js +201 -278
- package/dist/workflows/model.d.ts +19 -3
- package/dist/workflows/render.js +10 -2
- package/package.json +44 -14
- package/src/affected.ts +56 -17
- package/src/dev.ts +379 -0
- package/src/family.ts +144 -0
- package/src/generate-ontology.ts +4 -0
- package/src/generate-workflows.ts +3 -11
- package/src/install-bun.ts +16 -13
- package/src/libraries.ts +27 -3
- 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 +97 -0
- package/src/pack-library.ts +21 -3
- package/src/pins.ts +55 -10
- package/src/plan.ts +143 -0
- package/src/readme.ts +278 -0
- package/src/releasing.ts +735 -0
- package/src/versions.ts +3 -7
- package/src/workflows/definitions.ts +262 -397
- package/src/workflows/model.ts +15 -3
- package/src/workflows/render.ts +10 -2
package/dist/libraries.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type SpdxId } from "./license/standard.js";
|
|
2
3
|
import { type Table } from "@intellectual-frontiers/kanon";
|
|
3
4
|
import { type LevelKey } from "@intellectual-frontiers/mizan/levels";
|
|
5
|
+
import { type LibraryFamily } from "./family.js";
|
|
4
6
|
/** The name of a library's manifest in its folder. */
|
|
5
7
|
export declare const LIBRARY_FILE = "library.ts";
|
|
6
8
|
/** The specification that holds the requirements of the libraries, and the first number of the requirements it generates. */
|
|
@@ -9,6 +11,7 @@ export declare const LIBRARIES_SPEC = "0027-commons-libraries";
|
|
|
9
11
|
export declare const FIRST_GENERATED = 101;
|
|
10
12
|
/** The marker that opens the generated section, and the one that closes it. */
|
|
11
13
|
export declare const BEGIN = "<!-- libraries:begin -->";
|
|
14
|
+
/** The marker that ends the generated section of the libraries in a document. */
|
|
12
15
|
export declare const END = "<!-- libraries:end -->";
|
|
13
16
|
/** A library's manifest. */
|
|
14
17
|
export type Library = {
|
|
@@ -30,11 +33,16 @@ export type Library = {
|
|
|
30
33
|
readonly distribution: readonly Registry[];
|
|
31
34
|
/** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
|
|
32
35
|
readonly kanon?: Table;
|
|
36
|
+
/** Its host and its role where it is of a family (a host, a dialect of it or a plugin of it; 0033-kanon FR-021, 0027-commons-libraries FR-023). */
|
|
37
|
+
readonly family?: LibraryFamily;
|
|
38
|
+
/** The license its `LICENSE` and its packed `package.json` carry, where it is not the default of the repository (`license/standard.ts`; commons 0035-licensing FR-003). */
|
|
39
|
+
readonly license?: SpdxId;
|
|
33
40
|
};
|
|
34
41
|
/** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
|
|
35
42
|
export declare const KANON_REQUIRED_FROM: LevelKey | undefined;
|
|
36
43
|
/** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
|
|
37
44
|
export declare const REGISTRIES: readonly ["github", "npm"];
|
|
45
|
+
/** A registry a library is distributed to: github or npm. */
|
|
38
46
|
export type Registry = (typeof REGISTRIES)[number];
|
|
39
47
|
/** Where a manifest that declares no distribution is published. */
|
|
40
48
|
export declare const DEFAULT_DISTRIBUTION: readonly Registry[];
|
package/dist/libraries.js
CHANGED
|
@@ -61,7 +61,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
|
|
|
61
61
|
*
|
|
62
62
|
* @remarks
|
|
63
63
|
* A manifest declares the library's `name` (its folder), its conformance `level` (`L1` where it declares none, 0028-conformance-levels), the path of its spec kit, its `verify` command, its
|
|
64
|
-
* `version`, its `exports` (the keys of the package's `exports`) and its `distribution` (the registries it is published to: `github`, the default, and `npm` as well where a decision about that package has made it so; FR-015 to FR-018). The section "The libraries" of the specification is between the markers `<!-- libraries:begin -->` and `<!-- libraries:end -->`,
|
|
64
|
+
* `version`, its `exports` (the keys of the package's `exports`) its `family` (a host and a role in a family of libraries, FR-023) and its `distribution` (the registries it is published to: `github`, the default, and `npm` as well where a decision about that package has made it so; FR-015 to FR-018). The section "The libraries" of the specification is between the markers `<!-- libraries:begin -->` and `<!-- libraries:end -->`,
|
|
65
65
|
* one requirement for each library numbered from FR-101, an id kept for the life of the library; the rows of those requirements are in `enforcement.tsv`. Adding a library is adding a folder with a manifest and
|
|
66
66
|
* running this command.
|
|
67
67
|
*
|
|
@@ -81,12 +81,14 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
|
|
|
81
81
|
*/
|
|
82
82
|
import process from "node:process";
|
|
83
83
|
import { array, describe, formatDecodeError, literal, object, unknownValue, string, err, ok, } from "@intellectual-frontiers/core";
|
|
84
|
+
import { parseSpdxId } from "./license/standard.js";
|
|
84
85
|
import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
|
|
85
86
|
import { decodeTable } from "@intellectual-frontiers/kanon";
|
|
86
87
|
import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
|
|
87
88
|
import { stdio } from "@intellectual-frontiers/system";
|
|
88
89
|
import { spawn } from "@intellectual-frontiers/system/proc";
|
|
89
90
|
import { DEFAULT_LIBRARY_LEVEL, LEVELS, rankOf } from "@intellectual-frontiers/mizan/levels";
|
|
91
|
+
import { decodeFamily, familyFindings, reservationFindings, ROLES } from "./family.js";
|
|
90
92
|
/** The name of a library's manifest in its folder. */
|
|
91
93
|
export const LIBRARY_FILE = "library.ts";
|
|
92
94
|
/** The specification that holds the requirements of the libraries, and the first number of the requirements it generates. */
|
|
@@ -95,6 +97,7 @@ export const LIBRARIES_SPEC = "0027-commons-libraries";
|
|
|
95
97
|
export const FIRST_GENERATED = 101;
|
|
96
98
|
/** The marker that opens the generated section, and the one that closes it. */
|
|
97
99
|
export const BEGIN = "<!-- libraries:begin -->";
|
|
100
|
+
/** The marker that ends the generated section of the libraries in a document. */
|
|
98
101
|
export const END = "<!-- libraries:end -->";
|
|
99
102
|
/** Where the generated section begins and ends: the markers on lines of their own (a requirement may name them in its text). */
|
|
100
103
|
function bounds(spec) {
|
|
@@ -122,8 +125,8 @@ const nameDecoder = (input, path = "$") => {
|
|
|
122
125
|
? r
|
|
123
126
|
: err({ kind: "decode", path, expected: "a name of lower-case letters, digits and hyphens", found: describe(input) });
|
|
124
127
|
};
|
|
125
|
-
const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue });
|
|
126
|
-
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"];
|
|
128
|
+
const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue, family: object({ host: nonEmpty, role: literal(...ROLES) }), license: nonEmpty });
|
|
129
|
+
const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon", "family", "license"];
|
|
127
130
|
/** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
|
|
128
131
|
export function decodeLibrarySource(source) {
|
|
129
132
|
const exports = source.split("\n").filter((l) => /^export\s/.test(l));
|
|
@@ -155,6 +158,20 @@ export function decodeLibrarySource(source) {
|
|
|
155
158
|
return err(`library.${t.error} (0033-kanon FR-010)`);
|
|
156
159
|
kanon = t.value;
|
|
157
160
|
}
|
|
161
|
+
let family;
|
|
162
|
+
if (v.family !== undefined) {
|
|
163
|
+
const f = decodeFamily(v.family);
|
|
164
|
+
if (f.kind === "err")
|
|
165
|
+
return f;
|
|
166
|
+
family = f.value;
|
|
167
|
+
}
|
|
168
|
+
let license;
|
|
169
|
+
if (v.license !== undefined) {
|
|
170
|
+
const l = parseSpdxId(v.license);
|
|
171
|
+
if (l.kind === "err")
|
|
172
|
+
return err(`library.license: ${l.error}`);
|
|
173
|
+
license = l.value;
|
|
174
|
+
}
|
|
158
175
|
return ok({
|
|
159
176
|
name: v.name,
|
|
160
177
|
level: v.level ?? DEFAULT_LIBRARY_LEVEL,
|
|
@@ -165,6 +182,8 @@ export function decodeLibrarySource(source) {
|
|
|
165
182
|
...(v.summary === undefined ? {} : { summary: v.summary }),
|
|
166
183
|
distribution,
|
|
167
184
|
...(kanon === undefined ? {} : { kanon }),
|
|
185
|
+
...(family === undefined ? {} : { family }),
|
|
186
|
+
...(license === undefined ? {} : { license }),
|
|
168
187
|
});
|
|
169
188
|
}
|
|
170
189
|
/** The manifests of `commons/*`, in the order of the folders' names: every folder that holds a `library.ts`. */
|
|
@@ -248,6 +267,8 @@ export function manifestFindings(repo) {
|
|
|
248
267
|
if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
|
|
249
268
|
found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
|
|
250
269
|
}
|
|
270
|
+
const known = have.flatMap((f) => ("library" in f ? [f.library] : []));
|
|
271
|
+
found.push(...reservationFindings(known), ...familyFindings(known));
|
|
251
272
|
return found;
|
|
252
273
|
}
|
|
253
274
|
/** A field of a value read from JSON, `undefined` where the value is not an object or has no such field. */
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The license of this repository as data: the one license every library and every part of the repository is under, the one place its identifier is written, and the standard its text is taken from
|
|
3
|
+
* (commons 0035-licensing FR-001 to FR-004, 0018-standards-first FR-006 and FR-007). The text is the official PolyForm Noncommercial License 1.0.0, copied byte for byte into
|
|
4
|
+
* `PolyForm-Noncommercial-1.0.0.md` beside this file from the tag `1.0.0` of the official repository, and held to the SHA-256 recorded here.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Read as data by `../license.ts` (which writes and checks every `LICENSE`), by the packer (the `license` of a package) and by the decoder of the manifest (its optional `license`). The identifier is a closed union:
|
|
8
|
+
* a license is added to {@link SPDX_IDS} together with its text, never as a free string.
|
|
9
|
+
*
|
|
10
|
+
* Spec: 0001-libraries FR-019
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
15
|
+
/** The SPDX identifiers of the licenses this repository can carry: each has its official text in this folder. */
|
|
16
|
+
export declare const SPDX_IDS: readonly ["PolyForm-Noncommercial-1.0.0"];
|
|
17
|
+
/** An SPDX license identifier of {@link SPDX_IDS}. */
|
|
18
|
+
export type SpdxId = (typeof SPDX_IDS)[number];
|
|
19
|
+
/** The license of every library and of the repository, unless a manifest's `license` says another of {@link SPDX_IDS}. */
|
|
20
|
+
export declare const DEFAULT_LICENSE: SpdxId;
|
|
21
|
+
/** An SPDX identifier from text, or why the text is none of the licenses this repository can carry. */
|
|
22
|
+
export declare function parseSpdxId(text: string): Result<SpdxId, string>;
|
|
23
|
+
/** A standard imported as data (0018-standards-first FR-006): its issuer, name, version, location, license and the SHA-256 of what was imported. */
|
|
24
|
+
export type Standard = {
|
|
25
|
+
readonly id: string;
|
|
26
|
+
readonly issuer: string;
|
|
27
|
+
readonly name: string;
|
|
28
|
+
readonly version: string;
|
|
29
|
+
/** Where the imported text is, at the tag that is pinned. */
|
|
30
|
+
readonly location: string;
|
|
31
|
+
/** What the text may be copied under (an SPDX identifier where there is one). */
|
|
32
|
+
readonly license: string;
|
|
33
|
+
readonly redistributable: boolean;
|
|
34
|
+
/** The SHA-256 of the file in this folder, line ends as they are (they are `\n`). */
|
|
35
|
+
readonly sha256: string;
|
|
36
|
+
/** The file of this folder that holds the text. */
|
|
37
|
+
readonly file: string;
|
|
38
|
+
};
|
|
39
|
+
/** The official text of each license, as a standard of 0018-standards-first. */
|
|
40
|
+
export declare const LICENSE_STANDARDS: Readonly<Record<SpdxId, Standard>>;
|
|
41
|
+
/** The licensor named in the `Required Notice:` line of every `LICENSE` and in `NOTICE`. */
|
|
42
|
+
export declare const LICENSOR = "Intellectual Frontiers LLC";
|
|
43
|
+
/** The repository the `Required Notice:` line names. */
|
|
44
|
+
export declare const REPOSITORY_URL = "https://github.com/intellectual-frontiers/.github";
|
|
45
|
+
/** Where a commercial license is asked for. */
|
|
46
|
+
export declare const COMMERCIAL_ISSUES_URL = "https://github.com/intellectual-frontiers/.github/issues";
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The license of this repository as data: the one license every library and every part of the repository is under, the one place its identifier is written, and the standard its text is taken from
|
|
3
|
+
* (commons 0035-licensing FR-001 to FR-004, 0018-standards-first FR-006 and FR-007). The text is the official PolyForm Noncommercial License 1.0.0, copied byte for byte into
|
|
4
|
+
* `PolyForm-Noncommercial-1.0.0.md` beside this file from the tag `1.0.0` of the official repository, and held to the SHA-256 recorded here.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Read as data by `../license.ts` (which writes and checks every `LICENSE`), by the packer (the `license` of a package) and by the decoder of the manifest (its optional `license`). The identifier is a closed union:
|
|
8
|
+
* a license is added to {@link SPDX_IDS} together with its text, never as a free string.
|
|
9
|
+
*
|
|
10
|
+
* Spec: 0001-libraries FR-019
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { err, ok } from "@intellectual-frontiers/core";
|
|
15
|
+
/** The SPDX identifiers of the licenses this repository can carry: each has its official text in this folder. */
|
|
16
|
+
export const SPDX_IDS = ["PolyForm-Noncommercial-1.0.0"];
|
|
17
|
+
/** The license of every library and of the repository, unless a manifest's `license` says another of {@link SPDX_IDS}. */
|
|
18
|
+
export const DEFAULT_LICENSE = "PolyForm-Noncommercial-1.0.0";
|
|
19
|
+
/** An SPDX identifier from text, or why the text is none of the licenses this repository can carry. */
|
|
20
|
+
export function parseSpdxId(text) {
|
|
21
|
+
const found = SPDX_IDS.find((id) => id === text);
|
|
22
|
+
return found === undefined ? err(`${JSON.stringify(text)} is not a license of this repository (${SPDX_IDS.join(", ")})`) : ok(found);
|
|
23
|
+
}
|
|
24
|
+
/** The official text of each license, as a standard of 0018-standards-first. */
|
|
25
|
+
export const LICENSE_STANDARDS = {
|
|
26
|
+
"PolyForm-Noncommercial-1.0.0": {
|
|
27
|
+
id: "polyform-noncommercial-1.0.0",
|
|
28
|
+
issuer: "The PolyForm Project",
|
|
29
|
+
name: "PolyForm Noncommercial License 1.0.0",
|
|
30
|
+
version: "1.0.0",
|
|
31
|
+
location: "https://raw.githubusercontent.com/polyformproject/polyform-licenses/1.0.0/PolyForm-Noncommercial-1.0.0.md",
|
|
32
|
+
license: "The terms of LICENSE.md of polyformproject/polyform-licenses at tag 1.0.0: a PolyForm license is copied as it is, and a change removes the name PolyForm",
|
|
33
|
+
redistributable: true,
|
|
34
|
+
sha256: "c0ea4a896d2c8c394b29f9427589996db826cd501c512279ff0ed3ef48fabbe5",
|
|
35
|
+
file: "PolyForm-Noncommercial-1.0.0.md",
|
|
36
|
+
},
|
|
37
|
+
};
|
|
38
|
+
/** The licensor named in the `Required Notice:` line of every `LICENSE` and in `NOTICE`. */
|
|
39
|
+
export const LICENSOR = "Intellectual Frontiers LLC";
|
|
40
|
+
/** The repository the `Required Notice:` line names. */
|
|
41
|
+
export const REPOSITORY_URL = "https://github.com/intellectual-frontiers/.github";
|
|
42
|
+
/** Where a commercial license is asked for. */
|
|
43
|
+
export const COMMERCIAL_ISSUES_URL = "https://github.com/intellectual-frontiers/.github/issues";
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What is really vendored in this repository: the files that are not ours and the license each is under, as data (commons 0035-licensing FR-008). `../license.ts` makes `THIRD_PARTY_NOTICES.md` from it, and its check names an
|
|
3
|
+
* item whose path is gone. Where a license was not checked against its source the item says `unverified: <what to check>` and never a guess.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Packages installed from a registry (TypeScript, fast-check, `@types/node` and the others in `bun.lock`) are not vendored: nothing of them is in this repository, and a package's license is its own. Mermaid is
|
|
7
|
+
* copied into a built site and not into this repository, so its item has no path.
|
|
8
|
+
*
|
|
9
|
+
* Spec: 0001-libraries FR-019
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** One third-party item: what it is, where it came from, whose it is and the license it is under. */
|
|
14
|
+
export type ThirdPartyItem = {
|
|
15
|
+
/** The path in the repository, or `undefined` for an item that is copied only into a built output. */
|
|
16
|
+
readonly path: string | undefined;
|
|
17
|
+
readonly what: string;
|
|
18
|
+
readonly source: string;
|
|
19
|
+
readonly owner: string;
|
|
20
|
+
readonly license: string;
|
|
21
|
+
/** What was checked, or `unverified: <what to check>`. */
|
|
22
|
+
readonly checked: string;
|
|
23
|
+
};
|
|
24
|
+
/** The items, in the order the notices list them. */
|
|
25
|
+
export declare const THIRD_PARTY: readonly ThirdPartyItem[];
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What is really vendored in this repository: the files that are not ours and the license each is under, as data (commons 0035-licensing FR-008). `../license.ts` makes `THIRD_PARTY_NOTICES.md` from it, and its check names an
|
|
3
|
+
* item whose path is gone. Where a license was not checked against its source the item says `unverified: <what to check>` and never a guess.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Packages installed from a registry (TypeScript, fast-check, `@types/node` and the others in `bun.lock`) are not vendored: nothing of them is in this repository, and a package's license is its own. Mermaid is
|
|
7
|
+
* copied into a built site and not into this repository, so its item has no path.
|
|
8
|
+
*
|
|
9
|
+
* Spec: 0001-libraries FR-019
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** The items, in the order the notices list them. */
|
|
14
|
+
export const THIRD_PARTY = [
|
|
15
|
+
{
|
|
16
|
+
path: "commons/libraries/src/workflows/schema/github-workflow.schema.json",
|
|
17
|
+
what: "The JSON Schema of GitHub Actions workflows, the copy fetched on 2026-11-19, which the tests validate the generated workflows against",
|
|
18
|
+
source: "https://json.schemastore.org/github-workflow.json (the SchemaStore project, https://github.com/SchemaStore/schemastore)",
|
|
19
|
+
owner: "The SchemaStore authors",
|
|
20
|
+
license: "Apache-2.0",
|
|
21
|
+
checked: "The license is that of the SchemaStore repository (its LICENSE is the Apache License 2.0, read on 2026-11-20). unverified: whether the Apache-2.0 text must travel with this one file, which is named here by its address; ask counsel",
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
path: "commons/data/sql/extensions/osquery/schema/osquery-5.24.1.auto.json",
|
|
25
|
+
what: "The tables of osquery 5.24.1 (names, columns, types, descriptions), trimmed to the fields the importer reads",
|
|
26
|
+
source: "https://github.com/osquery/osquery-site, commit 055097f8d8fb45c0c33a83c9ed7c56a7df3d7b5f, path src/data/osquery_schema_versions/5.24.1.json",
|
|
27
|
+
owner: "The osquery authors",
|
|
28
|
+
license: "CC-BY-4.0, as the file's own `source.license` records for the osquery-site documentation data; the osquery project is Apache-2.0 OR GPL-2.0-only",
|
|
29
|
+
checked: "Taken from the record in the file itself. unverified: the license file of osquery-site at that commit (the address of a LICENSE file at the root returned 404), so check where the CC-BY-4.0 statement comes from and the attribution it asks for",
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
path: "commons/ontology/src/standards/nist-sp-800-53/controls.auto.ts",
|
|
33
|
+
what: "The titles and groups of twelve controls of NIST SP 800-53 Rev. 5.2.0, imported from the OSCAL catalog and held to its SHA-256",
|
|
34
|
+
source: "https://github.com/usnistgov/oscal-content, commit f0de6d8d8c059d374f15e0ae07508d82e370fc1d (import manifest commons/libraries/src/imports/nist-sp-800-53.import.ts)",
|
|
35
|
+
owner: "The National Institute of Standards and Technology",
|
|
36
|
+
license: "Public domain (a work of the United States Government, 17 U.S.C. 105)",
|
|
37
|
+
checked: "Taken from the import manifest, which records it with the SHA-256 of the source.",
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
path: "commons/ontology/src/supply-chain/packaging/schema.auto.ts",
|
|
41
|
+
what: "The slice of schema.org 30.1 that the packaging ontology specializes, imported and held to its SHA-256",
|
|
42
|
+
source: "https://schema.org/version/30.1/schemaorg-current-https.ttl (import manifest commons/libraries/src/imports/schema-org.import.ts)",
|
|
43
|
+
owner: "The Schema.org Community Group and contributors",
|
|
44
|
+
license: "CC-BY-SA-3.0",
|
|
45
|
+
checked: "Taken from the import manifest. unverified: whether the ShareAlike term of CC-BY-SA-3.0 reaches this generated module and what it asks of the files that use it; ask counsel",
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
path: "commons/ontology/src/supply-chain/packaging/managers.ts",
|
|
49
|
+
what: "The table of package managers, seeded from the tables of upt (the families file, `families.ts`, is seeded from the same)",
|
|
50
|
+
source: "https://github.com/sigoden/upt, kept as a fixture in tests/fixtures/upt/",
|
|
51
|
+
owner: "The authors of upt",
|
|
52
|
+
license: "MIT OR Apache-2.0, at the user's option",
|
|
53
|
+
checked: "Taken from the files' own headers and from tests/fixtures/upt/README.md. unverified: the license files of the pinned upt commit, which are not kept in this repository",
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
path: "commons/ontology/src/supply-chain/packaging/families.ts",
|
|
57
|
+
what: "The families of package managers, seeded from the tables of upt",
|
|
58
|
+
source: "https://github.com/sigoden/upt, kept as a fixture in tests/fixtures/upt/",
|
|
59
|
+
owner: "The authors of upt",
|
|
60
|
+
license: "MIT OR Apache-2.0, at the user's option",
|
|
61
|
+
checked: "Taken from the file's own header and from tests/fixtures/upt/README.md. unverified: the license files of the pinned upt commit, which are not kept in this repository",
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
path: undefined,
|
|
65
|
+
what: "Mermaid 11.17.2, the script the generated documentation site serves on a page with a diagram; it is copied into the built site from the package `mermaid` and is not in this repository",
|
|
66
|
+
source: "https://www.npmjs.com/package/mermaid",
|
|
67
|
+
owner: "Knut Sveidqvist and contributors",
|
|
68
|
+
license: "MIT",
|
|
69
|
+
checked: "The LICENSE of the installed package 11.17.2 was read on 2026-11-20: The MIT License (MIT), Copyright (c) 2014 - 2022 Knut Sveidqvist.",
|
|
70
|
+
},
|
|
71
|
+
];
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
2
|
+
import { type Library } from "./libraries.js";
|
|
3
|
+
import { type SpdxId } from "./license/standard.js";
|
|
4
|
+
import { type ThirdPartyItem } from "./license/third-party.js";
|
|
5
|
+
/** The command that writes what the check finds wrong. */
|
|
6
|
+
export declare const COMMAND = "bun commons/libraries/src/license.ts";
|
|
7
|
+
/** The license of a library: its manifest's `license`, else the default of the repository. */
|
|
8
|
+
export declare function licenseOf(library: Pick<Library, "license"> | undefined): SpdxId;
|
|
9
|
+
/** The line every `LICENSE` begins with, as the license asks of its licensor (its section Notices). */
|
|
10
|
+
export declare const REQUIRED_NOTICE = "Required Notice: Copyright Intellectual Frontiers LLC (https://github.com/intellectual-frontiers/.github)";
|
|
11
|
+
/** The text of a `LICENSE`: the required notice, a blank line and the official text exactly as it is. */
|
|
12
|
+
export declare function licenseFileText(official: string): string;
|
|
13
|
+
/** What is wrong, one case for each sentence. */
|
|
14
|
+
export type Finding = {
|
|
15
|
+
readonly kind: "text-missing";
|
|
16
|
+
readonly id: SpdxId;
|
|
17
|
+
readonly file: string;
|
|
18
|
+
} | {
|
|
19
|
+
readonly kind: "text-changed";
|
|
20
|
+
readonly id: SpdxId;
|
|
21
|
+
readonly want: string;
|
|
22
|
+
readonly have: string;
|
|
23
|
+
} | {
|
|
24
|
+
readonly kind: "manifest";
|
|
25
|
+
readonly dir: string;
|
|
26
|
+
readonly problem: string;
|
|
27
|
+
} | {
|
|
28
|
+
readonly kind: "missing";
|
|
29
|
+
readonly path: string;
|
|
30
|
+
readonly why: string;
|
|
31
|
+
} | {
|
|
32
|
+
readonly kind: "stale";
|
|
33
|
+
readonly path: string;
|
|
34
|
+
} | {
|
|
35
|
+
readonly kind: "lacks";
|
|
36
|
+
readonly path: string;
|
|
37
|
+
readonly what: string;
|
|
38
|
+
} | {
|
|
39
|
+
readonly kind: "vendored-gone";
|
|
40
|
+
readonly path: string;
|
|
41
|
+
};
|
|
42
|
+
/** The one sentence of a finding. */
|
|
43
|
+
export declare function sentence(f: Finding): string;
|
|
44
|
+
/** A file this module writes: its path from the repository and its whole text. */
|
|
45
|
+
export type Made = {
|
|
46
|
+
readonly path: string;
|
|
47
|
+
readonly text: string;
|
|
48
|
+
};
|
|
49
|
+
/** The official text of a license, held to the SHA-256 of its standard. */
|
|
50
|
+
export declare function officialText(id: SpdxId, folder?: string): Promise<Result<string, Finding>>;
|
|
51
|
+
/** `THIRD_PARTY_NOTICES.md` made from the items. */
|
|
52
|
+
export declare function thirdPartyNotices(items: readonly ThirdPartyItem[]): string;
|
|
53
|
+
/** The result of looking at a repository: what it should hold and what is wrong. */
|
|
54
|
+
export type Judged = {
|
|
55
|
+
readonly made: readonly Made[];
|
|
56
|
+
readonly findings: readonly Finding[];
|
|
57
|
+
};
|
|
58
|
+
/** 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. */
|
|
59
|
+
export declare function judge(repo: string, folder?: string): Promise<Judged>;
|
|
60
|
+
/** 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. */
|
|
61
|
+
export declare function main(argv: readonly string[]): Promise<number>;
|
package/dist/license.js
ADDED
|
@@ -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));
|
package/dist/link.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** The packages of commons by name and the folder of each; `commons/ts` comes first, so that it is the one that bears `@intellectual-frontiers/commons`. */
|
|
2
|
+
export declare function linksOf(repo: string): ReadonlyMap<string, string>;
|
|
3
|
+
/** Links each package that is not linked yet, and gives how many it linked, or why it could not. */
|
|
4
|
+
export declare function linkAll(repo: string): {
|
|
5
|
+
readonly made: number;
|
|
6
|
+
} | {
|
|
7
|
+
readonly problem: string;
|
|
8
|
+
};
|
|
9
|
+
/** The repository above a folder: the nearest one that has `commons/libraries/library.ts`. */
|
|
10
|
+
export declare function rootAbove(from: string): string | undefined;
|
|
11
|
+
/** The command line: 0, or 1 where it could not link. */
|
|
12
|
+
export declare function main(argv: readonly string[]): number;
|