IF Commons GitHub

readme

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

bun commons/libraries/src/readme.ts write the table again from the manifests bun commons/libraries/src/readme.ts --check write nothing and exit 1 where README.md is not what the manifests make other flags: --repo DIR (the repository, the working folder by default)

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 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 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 held in 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.

import { firstClause } from "./readme.ts";
firstClause("Mizan, the IF Spec Profile, as code. The harness holds the rules."); // "Mizan, the IF Spec Profile, as code"

Spec: 0001-libraries FR-017

Source: commons/libraries/src/readme.ts

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

ROLE_TITLEconstno test imports it
const ROLE_TITLE: Readonly<Record<"foundation" | "pattern" | "program" | "standard", string>>

The heading of a role in the table.

LibraryNametypeno test imports it
type LibraryName = Brand<string, "library name">;

A library's name (its folder), made only by parseLibraryName.

parseLibraryNamefunction
function parseLibraryName(text: string): Result<LibraryName, string>

A library name from text, or why the text is not one.

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

ROLE_OFconst
const ROLE_OF: ReadonlyMap<string, "foundation" | "pattern" | "program" | "standard">

The role of each library, by name. A new library is classified here, or the check names it.

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

summaryOffunction
function summaryOf(source: string): Result<string, string>

The summary of an about.ts, read as data: the double-quoted string literals after summary:, joined by +, and nothing run. An error where the file has no summary or it is not literals.

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

firstSentencefunction
function firstSentence(text: string): string

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.

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

firstClausefunction
function firstClause(text: string): string

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 outside parentheses and backticks and at least 25 characters in; the whole sentence where it has no such place.

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

shapeOffunctionno test imports it
function shapeOf(l: Library): string

The Kanon shape of a library: what its manifest declares, in words, or a dash where it declares no table.

tableOffunction
function tableOf(rows: readonly Row[]): string

The table, as Markdown, for the rows given: sorted by role, then by name.

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

rowsOffunction
function rowsOf(repo: string): { readonly rows: readonly Row[]; readonly problems: readonly string[]; }

The rows of a repository, and what is wrong with reading them.

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

BundleRowtypeno test imports it
type BundleRow = { readonly name: string; readonly purpose: string };

One row of the table of the metapackages: the package and what it is.

bundlesOffunctionno test imports it
function bundlesOf(repo: string): readonly BundleRow[]

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.

bundlesTableOffunctionno test imports it
function bundlesTableOf(rows: readonly BundleRow[], mode?: "per-library" | "single"): string

The table of the package or packages that install commons, as Markdown, with the sentence that introduces it: in single mode the one package that holds every library, in per-library mode the metapackages; nothing where a repository has none.

withTablefunction
function withTable(readme: string, table: string): Result<string, string>

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.

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

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