IF Commons GitHub

config

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.

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

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

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

MemberTypeWhat 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.
CitationsConfiginterfaceno test imports it
interface CitationsConfig

How the repository's specifications are cited, and which other repositories' citations are links (commons 0011-documentation FR-025).

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

MemberTypeWhat 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

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

MemberTypeWhat it is
id"no-blocking-issues" | "ran" | "requirements-proved" | "tests-pass"
min?number
IssueLikeinterfaceno 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.

MemberTypeWhat it is
idnumber
slugstring
titlestring
summarystring
severitystring
prioritystring
goals?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?string
cites?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
IssuesOfinterfaceno test imports it
interface IssuesOf

The issues of one library, as typed code.

MemberTypeWhat 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[]
PageSelectorinterfaceno 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.

MemberTypeWhat 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.
PresentationIdtypeno test imports it
type PresentationId = (typeof PRESENTATION_IDS)[number];

The name of a presentation.

Configinterfaceno test imports it
interface Config

The configuration checked (commons 0011-documentation FR-023): every path absolute or from the root, every default filled.

MemberTypeWhat 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.
DocsConfiginterfaceno test imports it
interface DocsConfig

The configuration a repository gives (commons 0011-documentation FR-023), as its docs.config.ts exports it.

MemberTypeWhat 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.
HomeConfiginterfaceno test imports it
interface HomeConfig

The home page's source: a folder and its About.

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

MemberTypeWhat 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.
PackageConfiginterfaceno test imports it
interface PackageConfig

A package the site shows: its folder, its name in the site's addresses, and its About.

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

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

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

DEFAULT_PRESENTATIONSconst
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

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

normalDirfunction
function normalDir(dir: string): string

A folder from the root, as the build writes it: no ./, no trailing /, and "" for the root.

ParameterWhat it is
dirthe folder as written

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

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

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

ParameterWhat 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

underfunction
function under(dir: string, rel: string): string

A path inside a folder from the root, where the folder may be the root ("").

ParameterWhat 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

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