Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-docs FR-006
The configuration a repository gives the generator (commons 0011-documentation FR-023 to FR-027 , and 0001-docs FR-006 ), and the one place it is checked: a docs.config.ts exports a value of DocsConfig (its default export, or config), and resolveConfig checks it once into a Config, whose paths are absolute (the root, the output) or relative to the root (everything else), with every default filled. Nothing else reads the raw value. The About types are Core's (@intellectual-frontiers/core/about), re-exported here so that a repository's about.ts and its configuration are typed by this package alone.
import type { DocsConfig } from "@intellectual-frontiers/commons/docs" ;
export default {
name: "Example" ,
repository: "https://github.com/example/example" ,
home: { dir: "." , about: { title: "Example" , summary: "What the repository is." } },
packages: [{ dir: "." , slug: "example" , about: { title: "Example" , summary: "Its one package." , areas: [{ title: "Core" , slug: "core" , entryPoints: ["src/mod.ts" ] }] } }],
specKits: [{ layout: "spec-kit" , dir: "specs" }],
citations: { prefix: "example" , digits: 3 },
} satisfies DocsConfig ;Source: commons/docs/src/config.ts
5 of 24 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.
BookPartinterface no test imports it interface BookPart A part of a volume: a title, a line, and the pages it takes (a page is in the first part that takes it).
Member Type What it is titlestringIts title. about?stringWhat it holds, in a sentence. selectreadonly PageSelector[]The pages, selector by selector, each in the order of the site's navigation. perGroup?booleanMake a part of each group of the pages it takes, titled by the group, in place of one part (the API, library by library).
BookVolumeinterface no test imports it interface BookVolume A volume of a book: the slug of the book of erga it is a chapter source of, and its parts.
Member Type What it is idstringIts slug: the book's folder, and the name of the file it is written to. titlestringIts title. aboutstringWhat it is, in a sentence. partsreadonly BookPart[]Its parts, in order.
BooksConfiginterface no test imports it interface BooksConfig What the book presentation writes (docs 0001-docs FR-008 ): the volumes, and where a link to a page outside the volume goes.
Member Type What it is site?stringThe address of the site, ending in /: a link to a page that is not in the volume goes there; with none it is only its text. volumesreadonly BookVolume[]The volumes.
CitationsConfiginterface no test imports it interface CitationsConfig How the repository's specifications are cited, and which other repositories' citations are links (commons 0011-documentation FR-025 ).
Member Type What it is prefixstringThe repository's own prefix: commons 0011-documentation. digitsnumberThe digits of its specifications' numbers: 4 in commons, 3 in a plain Spec Kit. linked?readonly LinkedRepository[]The public repositories whose citations become links to their sites. text?readonly string[]The repositories whose citations are only shown as text.
interface EvidenceSource What the site shows of quality (docs 0001-docs FR-009 ): the folder of test results (CTRF, one <library>.ctrf.json for each, and meta.json), the issues of the libraries as typed code, and a snapshot of the tickets of GitHub.
Member Type What it is results?stringThe folder of results, from the root; where it is not there, no run is recorded. github?stringThe snapshot of the GitHub issues (a JSON array as the API gives it), from the root. issues?readonly IssuesOf[]The issues kept as typed code. gate?readonly GateCondition[]The conditions of the quality gate each library is held to, shown and never enforced; ran, tests-pass and no-blocking-issues where none are given.
Imported by 21 tests of the run (21 passed, 0 failed): the library's results
GateConditioninterface no test imports it interface GateCondition A condition of a quality gate (docs 0001-docs FR-017 ): ran (the library's tests were in the run), tests-pass (none failed), no-blocking-issues (no open issue of severity critical or high), requirements-proved (at least min percent of its requirements are proved; 100 where not said).
Member Type What it is id"no-blocking-issues" | "ran" | "requirements-proved" | "tests-pass"min?number
IssueLikeinterface no test imports it interface IssueLike An issue kept as typed code (commons data 0044-issues ), as far as the site reads it: the package depends on no library, so it names the fields and not the type.
Member Type What it is idnumberslugstringtitlestringsummarystringseveritystringprioritystringgoals?readonly string[]status{ readonly kind: string; readonly reason?: string | undefined; readonly by?: string | undefined; readonly of?: number | undefined; readonly until?: string | undefined; readonly proof?: readonly { readonly [k: string]: unknown; readonly kind: string; }[] | undefined; }size?stringcites?readonly string[]The requirements it is about, as 0043-sql-invariants FR-002. evidence?readonly { readonly [k: string]: unknown; readonly kind: string; }[]links?readonly { readonly kind: string; readonly to: number; }[]raisedstring
IssuesOfinterface no test imports it interface IssuesOf The issues of one library, as typed code.
Member Type What it is librarystringThe library, by the name of its folder. scope?stringWhere in the library the set is (its path), where a library keeps more than one set: the numbers of two sets may be alike. issuesreadonly IssueLike[]
PageSelectorinterface no test imports it interface PageSelector Which pages a part of a volume takes (docs 0001-docs FR-008 ): those of a section, of a group of it, under a path, and not under another.
Member Type What it is section?SectionThe section. group?stringThe group of the section's navigation. prefix?stringA path from the site's root that the page's path begins with. exclude?readonly string[]Paths from the site's root that the page's path must not begin with.
PresentationIdtype no test imports it type PresentationId = (typeof PRESENTATION_IDS )[number ];The name of a presentation.
Configinterface no test imports it interface Config The configuration checked (commons 0011-documentation FR-023 ): every path absolute or from the root, every default filled.
Member Type What it is filestringThe configuration's file, absolute. fileFromRootstringThe configuration's file, from the root, for findings. rootstringThe repository's root, absolute. namestringThe site's name. subjectstringHow the prose names the repository. repositorystringThe repository's address on GitHub. branchstringThe branch of links to files. homePackageSourceThe home page's source; its slug is unused. packagesreadonly PackageSource[]The packages. specKitsreadonly SpecKitSource[]The spec kits. citations{ readonly prefix: string; readonly digits: number; readonly linked: readonly LinkedRepository[]; readonly text: readonly string[]; }How specifications are cited. lensesreadonly Lens[]The lenses. lintRulesstring | undefinedThe folder of the lint rules, from the root. retiredreadonly string[]Names that must not appear on any page. forbiddenInGuidesreadonly string[]Words that must not appear on the pages people write. outstringWhere build writes the site, absolute. presentationsreadonly ("book" | "data" | "markdown" | "web")[]The presentations written by default. booksBooksConfigThe volumes of the book presentation. evidenceEvidenceSource | undefinedThe evidence the site shows. problemsreadonly { readonly where: string; readonly error: string; }[]What could not be read while the configuration was made.
DocsConfiginterface no test imports it interface DocsConfig The configuration a repository gives (commons 0011-documentation FR-023 ), as its docs.config.ts exports it.
Member Type What it is namestringThe site's name, at the top of every page. subject?stringHow the site's prose names the repository (commons); the site's name by default. root?stringThe repository's root, from the configuration's folder; . by default. repositorystringThe repository's address on GitHub, for the top bar and the links to files the site does not show. branch?stringThe branch the links to files name; main by default. homeHomeConfigWhere the home page comes from. packagesreadonly PackageConfig[]The packages, in the order the site shows them. specKits?readonly SpecKitConfig[]The spec kits; none by default. citationsCitationsConfigHow specifications are cited. lenses?readonly Lens[]The lenses (commons 0011-documentation FR-026 ); none by default. lintRules?stringThe folder of the lint rules an about may name, as <rule>.ts, from the root; a lint rule is not checked without it. retired?readonly string[]Names that must not appear on any page of the site (a retired library, a product that is gone): a page that names one is a finding. forbiddenInGuides?readonly string[]Words that must not appear on the pages that people write (the sections Start here, Concepts and How-to): a page that has one is a finding. out?stringWhere build writes the site, from the root; _site by default. presentations?readonly ("book" | "data" | "markdown" | "web")[]The presentations build writes when the command line names none; the site, the Markdown and the data by default. books?BooksConfigThe volumes of the book presentation (docs 0001-docs FR-008 ); none by default. evidence?EvidenceSourceThe evidence the site shows beside the code: test results, issues, tickets (docs 0001-docs FR-009 ); none by default. problems?readonly { readonly where: string; readonly error: string; }[]What could not be read while the configuration was made, each a finding of the site (docs 0001-docs FR-015 ): the configuration goes on without it, so that one library does not stop the site.
HomeConfiginterface no test imports it interface HomeConfig The home page's source: a folder and its About.
Member Type What it is dirstringIts folder, from the repository's root (. for the root itself). about?string | AboutThe path of its about.ts from its folder (about.ts by default), or its About value itself.
LinkedRepositoryinterface no test imports it interface LinkedRepository A repository whose specifications may be linked: a public one whose site this generator makes (commons 0011-documentation FR-025 ).
Member Type What it is repostringIts name, as a citation's qualifier (commons). sitestringThe address of its site, ending in /: a specification is <site>specs/<id>.html. digitsnumberThe digits of its specifications' numbers.
PackageConfiginterface no test imports it interface PackageConfig A package the site shows: its folder, its name in the site's addresses, and its About.
Member Type What it is dirstringIts folder, from the repository's root (. for the root itself). slugstringIts name in the site's addresses: lower-case words joined by hyphens. about?string | AboutThe path of its about.ts from its folder (about.ts by default), or its About value itself (commons 0011-documentation FR-027 ).
PackageSourceinterface no test imports it interface PackageSource A package as the build reads it: its folder from the root ("" for the root), its name, and where its About is.
Member Type What it is dirstringIts folder, from the root: "" for the root itself. slugstringIts name in the site's addresses. about{ readonly kind: "file"; readonly file: string; } | { readonly kind: "value"; readonly value: About; }Its about.ts, from the root, or its About value.
SpecKitConfigtype no test imports it type SpecKitConfig =
| {
/** Commons' layout. */
readonly layout: "commons";
/** The folder that holds `re… (569 characters) type SpecKitConfig =
| {
/** Commons' layout. */
readonly layout : "commons" ;
/** The folder that holds `registry.tsv`, from the repository's root. */
readonly dir : string ;
}
| {
/** The plain layout of Spec Kit. */
readonly layout : "spec-kit" ;
/** The folder that holds the specifications' folders, from the repository's root (`specs`). */
readonly dir : string ;
/** The constitution, from the repository's root: `.specify/memory/constitution.md` by default, `false` for none. */
readonly constitution ?: string | false ;
};A spec kit and its layout (commons 0011-documentation FR-024 ): commons' (registry.tsv, enforcement.tsv, specs/NNNN-slug/spec.md under dir), or the plain layout of Spec Kit (dir holds NNN-slug/spec.md, each with an optional reviewed.tsv, and a constitution).
SpecKitSourcetype no test imports it type SpecKitSource =
| { readonly layout : "commons" ; readonly dir : string }
| { readonly layout : "spec-kit" ; readonly dir : string ; readonly constitution : string | undefined };A spec kit as the build reads it, its folders from the root.
const DEFAULT_PRESENTATIONS : readonly ("book" | "data" | "markdown" | "web" )[]The presentations build writes when none is named: the site as it has always been.
Imported by 9 tests of the run (9 passed, 0 failed): the library's results
isAboutfunction no test imports it function isAbout (v : unknown ): v is About Whether a value has the fields every About has, and areas of the right shape where it has them.
function normalDir (dir : string ): string A folder from the root, as the build writes it: no ./, no trailing /, and "" for the root.
Parameter What it is dirthe folder as written
Imported by 5 tests of the run (5 passed, 0 failed): the library's results
PRESENTATION_IDSconst no test imports it const PRESENTATION_IDS : readonly ["web" , "markdown" , "data" , "book" ]The presentations of the pages (docs 0001-docs FR-007 ): the static site, the Markdown twins with llms.txt, the JSON a lens adds, and the AsciiDoc of the volumes of a book.
function resolveConfig (value : unknown , file : string ): Result <Config , string []>A configuration checked into its resolved form, or every problem with it (commons 0011-documentation FR-023 ).
Parameter What it is valuewhat the configuration's module exports filethe configuration's file, absolute
Imported by 35 tests of the run (35 passed, 0 failed): the library's results
function under (dir : string , rel : string ): string A path inside a folder from the root, where the folder may be the root ("").
Parameter What it is dirthe folder, from the root relthe path inside it
Imported by 5 tests of the run (5 passed, 0 failed): the library's results