IF Commons GitHub

libraries

The manifest of a library of commons (commons 0027-commons-libraries FR-011 to FR-014) and the requirements it makes: a library is a folder commons/<name>/ that holds library.ts, an object literal read as data and never run, and this repository knows it from that file alone. The decoder of the manifest, the check that a manifest and its folder agree, and the generator of the section "The libraries" of 0027-commons-libraries and of its rows of enforcement.tsv.

bun commons/libraries/src/libraries.ts write the section and the rows again from the manifests bun commons/libraries/src/libraries.ts --check write nothing and exit 1 where a file is not what the manifests make, or where a manifest and its folder disagree other flags: --repo DIR (the repository, the working folder by default)

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 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 -->, 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 running this command.

import { decodeLibrarySource } from "./libraries.ts";
const r = decodeLibrarySource('export const library = { name: "x", verify: "bun run verify", version: "0.1.0", exports: [] };');
r.kind; // "ok"

Spec: 0001-libraries FR-001

Source: commons/libraries/src/libraries.ts

15 of 37 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

decodeLibrarySourcefunction
function decodeLibrarySource(source: string): Result<Library, string>

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).

Imported by 38 tests of the run (38 passed, 0 failed): the library's results

Librarytype
type Library = { /** The folder's name, and the package's: `@intellectual-frontiers/<name>`. */ readonly name: strin… (2473 characters)
type Library = {
  /** The folder's name, and the package's: `@intellectual-frontiers/<name>`. */
  readonly name: string;
  /** The conformance level the library is held to (`L1` where the manifest declares none). */
  readonly level: LevelKey;
  /** The path of its spec kit from its folder; none at L0. */
  readonly specKit?: string;
  /** The command that proves it, run from its folder with no argument. */
  readonly verify: string;
  /** Its version: the package's. */
  readonly version: string;
  /** The keys of the package's `exports`. */
  readonly exports: readonly string[];
  /** What it is, in a sentence, for the requirement made of it. */
  readonly summary?: string;
  /** Where it is published: always `github` (the GitHub package registry of the organization), and `npm` as well where a decision about that package has made it so (FR-015 and FR-016). */
  readonly distribution: readonly Registry[];
  /** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
  readonly kanon?: Table;
  /** 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). */
  readonly family?: LibraryFamily;
  /** 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). */
  readonly license?: SpdxId;
  /** The constants of its sources that say its own version (`ERGONEX_VERSION`), each a file from the library's folder and the name of the constant: the release rewrites them with the version, and a check finds one that disagrees. */
  readonly versionConstants?: readonly VersionConstant[];
  /** The package the library publishes where it is not `@intellectual-frontiers/<name>` (the `data` library publishes `@intellectual-frontiers/arcactl`; commons 0036-distribution FR-009). */
  readonly publishes?: PackageName;
  /** The typed reason the library is not released, where there is one: a library with none is released (0001-libraries FR-024); a held library is verified and packed like any other, and has no release record entry, no tag, no set and no registry. */
  readonly held?: Hold;
  /** The set the library is, where it is a metapackage: a folder with no code of its own whose package depends on the libraries of the set at exact versions (commons 0036-distribution FR-005). */
  readonly bundle?: BundleName;
};

A library's manifest.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

LIBRARY_FILEconst
const LIBRARY_FILE: "library.ts"

The name of a library's manifest in its folder.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

manifestFindingsfunction
function manifestFindings(repo: string): readonly string[]

What is wrong where a manifest and its folder disagree (0027-commons-libraries FR-013), one sentence each: a folder with a spec kit and no manifest, a manifest that cannot be read, that names another folder, a level above L0 with no spec kit, a spec kit that is not there, a package of another name, a version that is not the package's, exports that are not the package's, and a verify that is no script of the package.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

readLibrariesfunction
function readLibraries(repo: string): readonly Found[]

The manifests of commons/*, in the order of the folders' names: every folder that holds a library.ts.

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

verifyAllfunctionno test imports it
function verifyAll(repo: string): Promise<readonly Verified[]>

Runs the verify of every library a manifest declares, each from its own folder, and gives each status (0028-conformance-levels FR-012).

LIBRARIES_SPECconstno test imports it
const LIBRARIES_SPEC: "0027-commons-libraries"

The specification that holds the requirements of the libraries, and the first number of the requirements it generates.

FIRST_GENERATEDconst
const FIRST_GENERATED: 101

The first requirement number of the section "The libraries", which is generated (0027-commons-libraries FR-011).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

BEGINconstno test imports it
const BEGIN: "<!-- libraries:begin -->"

The marker that opens the generated section, and the one that closes it.

ENDconstno test imports it
const END: "<!-- libraries:end -->"

The marker that ends the generated section of the libraries in a document.

HOLD_KINDSconst
const HOLD_KINDS: readonly ["tests-only", "unfinished", "owner-blocked"]

The kinds of reason not to release a library: a closed union, and the only reasons there are (0001-libraries FR-024).

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

HoldKindtypeno test imports it
type HoldKind = (typeof HOLD_KINDS)[number];

A kind of reason not to release a library.

HoldTexttypeno test imports it
type HoldText = Brand<string, "hold text">;

One line of text of a hold: non-empty, trimmed, on one line, made only by parseHoldText.

parseHoldTextfunctionno test imports it
function parseHoldText(text: string, where: string): Result<HoldText, string>

A line of a hold from text, or why the text is not one.

Holdtype
type Hold =
  | { readonly kind: "tests-only"; readonly reason: HoldText }
  | { readonly kind: "unfinished"; readonly reason: HoldText; readonly missing: readonly [HoldText, ...HoldText[]]; readonly liftedWhen: HoldText }
  | { readonly kind: "owner-blocked"; readonly reason: HoldText };

The reason a library is not released (0001-libraries FR-024): a library is released unless its manifest carries one, and every one has its text. A library that is tests-only is a tool of tests that nothing depends on at run time; an unfinished one names what is missing and the condition that lifts the hold; an owner-blocked one is held by a decision of the owner that the text states.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

decodeHoldfunction
function decodeHold(input: unknown): Result<Hold, string>

The hold of a manifest from its value, or why it is not one.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

holdSentencefunction
function holdSentence(h: Hold): string

The hold in one sentence, for a plan, a table and the register: its kind, its reason and, where it has them, what is missing and what lifts it.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

PACKAGE_SCOPEconstno test imports it
const PACKAGE_SCOPE: "@intellectual-frontiers/"

The scope of the packages of commons.

BUNDLESconst
const BUNDLES: readonly ["commons", "foundation", "patterns", "programs", "standards"]

The sets that a metapackage is: the whole of commons, and the four roles of the libraries; a closed union, and the name of the folder and of the package of each.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

BundleNametypeno test imports it
type BundleName = (typeof BUNDLES)[number];

The name of a set of libraries a metapackage is.

PackageNametypeno test imports it
type PackageName = Brand<string, "package name">;

The name of a package of commons: @intellectual-frontiers/ and a name, made only by parsePackageName.

parsePackageNamefunctionno test imports it
function parsePackageName(text: string): Result<PackageName, string>

A package name of commons from text, or why the text is not one.

publishedPackagefunctionno test imports it
function publishedPackage(l: Pick<Library, "name" | "publishes">): string

The package a library publishes: the one its manifest names in publishes, else @intellectual-frontiers/<name> (commons 0036-distribution FR-009).

VersionConstanttypeno test imports it
type VersionConstant = { readonly file: string; readonly name: string };

A constant of a library's sources that holds the library's version: the file (from the library's folder) and the constant's name.

KANON_REQUIRED_FROMconstno test imports it
const KANON_REQUIRED_FROM: LevelKey | undefined

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.

REGISTRIESconstno test imports it
const REGISTRIES: readonly ["github", "npm"]

The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018).

Registrytypeno test imports it
type Registry = (typeof REGISTRIES)[number];

A registry a library is distributed to: github or npm.

DEFAULT_DISTRIBUTIONconstno test imports it
const DEFAULT_DISTRIBUTION: readonly ("github" | "npm")[]

Where a manifest that declares no distribution is published.

Foundtypeno test imports it
type Found = { readonly dir: string; readonly library: Library } | { readonly dir: string; readonly problem: string };

A library found in the folder of commons: its folder and what its manifest says, or why it cannot be read.

DOCS_CONFIGconstno test imports it
const DOCS_CONFIG: "docs.config.ts"

The file of the documentation site's configuration, from commons/, which names the spec kit of every library that has one.

docsConfigFindingsfunctionno test imports it
function docsConfigFindings(root: string, libraries: readonly Library[]): readonly string[]

The libraries with a spec kit that the configuration of the site does not name (0001-libraries FR-025), one sentence each with the fix: a spec kit that commons/docs.config.ts does not list is a section of the site and of the books that is missing, which has turned the site and the tests red after a push. Read as text, never run; where the repository has no such file nothing is asked.

requirementOffunctionno test imports it
function requirementOf(id: string, l: Library): string

The requirement of a library, as the section "The libraries" holds it (FR-014): one line.

rowOffunction
function rowOf(id: string, l: Library): string

The row of enforcement.tsv of a library's requirement.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

idsInfunction
function idsIn(spec: string): ReadonlyMap<string, string>

The ids the section already gives each library, by name, read from its text between the markers.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

idsForfunction
function idsFor(libraries: readonly Library[], had: ReadonlyMap<string, string>): ReadonlyMap<string, string>

The id each library has: the one it had, or the next number after the greatest. A number belongs to the first library that holds it in the specification: where a second one holds it (two branches each gave the next number to a library, and a merge kept both), the second is given the next number after the greatest, so that the generator makes the section again with one number for each library.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

generatedfunction
function generated(spec: string, enforcement: string, libraries: readonly Library[]): Result<{ readonly spec: string; readonly enforcement: string; }, string>

The text of the specification and of the register, made again from the libraries: nothing where the specification has no markers.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Verifiedtypeno test imports it
type Verified = { readonly name: string; readonly code: number };

The result of one library's verify.

Titles, headings, exports, tables, columns and requirements. Esc closes.