IF Commons GitHub

Docs

0001Draft

0001-docs · owner if · domain commons

Requirements

FR-001checkpassing

Docs MUST be a library of commons: the folder commons/docs/ with a spec kit of its own, a manifest library.ts, an about.ts and a package named @intellectual-frontiers/docs, its sources in src/, proved by bun run verify in its folder.

Enforced (check): .github: cd commons/docs && bun run verify — library.test.ts: the folder, the manifest, the package and the spec kit agree

Proved by: docs/suite/library.test.ts

Written in: docs/about.ts, docs/library.ts, docs/src/build.ts, docs/src/check.ts, docs/src/emit/html.ts, docs/src/emit/markdown.ts and 16 more

Tests: passed: suite/library.test.ts the manifest, the package and the folder agree: the name, the version, the exports, the sp

FR-002checkpassing

The package MUST export, by package name, the entry of the generator (.: the types of the configuration, DocsConfig, About, Lens, Page, Block and the functions that build and check a site) and the factories of the lenses a configuration passes: ./lens/layered, ./lens/program, ./lens/guides, ./lens/releases and ./lens/repo-ops, so that a repository's docs.config.ts imports them and nothing else of this library.

Enforced (check): .github: cd commons/docs && bun run verify — package.test.ts: the entries a configuration imports are exported by name

Proved by: docs/suite/library.test.ts

Written in: docs/src/lens/guides.ts, docs/src/lens/layered.ts, docs/src/lens/program.ts, docs/src/lens/releases.ts, docs/src/mod.ts

Tests: passed: suite/library.test.ts a configuration can import by name the entry, which exports the configuration's types and

Cited by: Documentation

FR-003checkpassing

The package MUST have the command ifc-docs (bin): ifc-docs build [--out DIR] [--config FILE] writes the site, ifc-docs check builds it into a temporary folder and exits 1 where there is a finding, and both find the first docs.config.ts from the folder they run in up to the root of the repository.

Enforced (check): .github: cd commons/docs && bun run verify — package.test.ts: the launcher runs build and check on a fixture and finds the configuration upward

Proved by: docs/suite/pack.test.ts

Written in: docs/src/cli.ts, docs/src/main.ts

Tests: passed: suite/pack.test.ts the package is packed with compiled modules, declarations, theme files, a launcher for ifc

Cited by: Documentation

FR-004checkpassing

The package MUST be built, inspected and packed by tools/pack.ts through the packer of commons: compiled modules and their declarations beside the sources (which Bun reads), the files of the theme beside the modules that read them, the command as a launcher of the compiled module, a LICENSE, and dependencies that are all real packages of npm (typescript at 7.1.0-beta, shiki, beautiful-mermaid and the libraries of commons that are published) and none that is a link.

Enforced (check): .github: cd commons/docs && bun run verify — pack.test.ts: the package is packed with compiled modules, theme files, a launcher, a LICENSE and no link dependency

Proved by: docs/suite/pack.test.ts

Written in: docs/tools/pack.ts

Tests: passed: suite/pack.test.ts the package is packed with compiled modules, declarations, theme files, a launcher for ifc

FR-005checkpassing

The packed package, installed into an empty project beside a small repository (a spec kit in the form of Mizan or of Spec Kit and a docs.config.ts that imports the package by its name), MUST build that repository's site with ifc-docs build and with ifc-docs check, with no finding, with every page a static file whose links are relative and that asks nothing of another host. In single distribution (commons 0036-distribution FR-019 to FR-024), the mode of the repository, Docs is a library of the one package @intellectual-frontiers/commons and not a package of its own: the package that is installed is that one, packed by commons/commons, the configuration imports @intellectual-frontiers/commons/docs and the command is its bin/ifc-docs.mjs; in per-library mode it is the package of Docs by itself.

Enforced (check): .github: cd commons/docs && bun run verify — consumer.test.ts: the packed package installed into an empty project builds and checks a small repository

Proved by: docs/suite/consumer.test.ts

Tests: passed: suite/consumer.test.ts the packed package installed into an empty project builds and checks a small repository at

Cited by: Documentation

FR-006checkpassing

A configuration MUST give the address and the branch of the repository (repository, branch), and the generator MUST make every link to a source file from those and from nothing else, so that a repository that is private, or hosted anywhere, has a site whose links go where its configuration says and whose pages name no other host.

Enforced (check): .github: cd commons/docs && bun run verify — consumer.test.ts: a repository at another address has links to that address and names no other host

Proved by: docs/suite/consumer.test.ts

Written in: docs/src/config.ts, docs/tools/check.ts

Tests: passed: suite/consumer.test.ts the packed package installed into an empty project builds and checks a small repository at

Cited by: config, Documentation generator

FR-007checkpassing

The pages MUST be one model that more than one presentation writes: web (the static site), markdown (the Markdown twin of each page and llms.txt), data (the JSON the lenses add) and book (FR-008). Each presentation makes its files in memory as a list, so that the same list is written by ifc-docs build into the output folder, or compared with the folder by ifc-docs build --check, which writes nothing and exits 1 where a file is missing or differs. A configuration names the presentations it writes (presentations; web, markdown and data by default, which is the site as it has always been) and the command line overrides them with --presentation NAME[,NAME]; a name that is not one, book with no volume configured, and --presentation or --check with check are refused. The folder is emptied before a write only where web is written, so that a book is written into a folder that holds other things.

Enforced (check): .github: cd commons/docs && bun run verify — book.test.ts: the presentations are web, markdown, data and book, the site is what is written without a choice, and a book needs its volumes; the command line takes --presentation (one or several, by name) and --check for build, and refuses them for check; the files of a presentation are written, a book into a folder that holds other things leaves them, and a file that is not what a build writes is found; build --presentation book without a volume is refused, and the book is written and checked from the command line

Proved by: docs/suite/book.test.ts

Written in: docs/src/presentation.ts

Tests: passed: suite/book.test.ts the files of a presentation are written, a book into a folder that holds other things leav; passed: suite/book.test.ts build --presentation book without a volume is refused, and the book is written and checked; passed: suite/book.test.ts the command line takes --presentation (one or several, by name) and --check for build, and; passed: suite/book.test.ts the presentations are web, markdown, data and book, the site is what is written without a

Cited by: config, Documentation generator, presentation

FR-008checkpassing

The book presentation MUST write each volume that the configuration's books names as one AsciiDoc file, <volume>/generated/<volume>.adoc, which a book of erga (kind book) includes as a generated chapter source, and books.json, which lists the volumes, their parts and their page counts. A volume has parts, and a part selects pages by section, group and path prefix (exclude leaves some out; perGroup makes a part of each group); a page is in the first part that selects it, is a chapter of its part, and is a section of its parent's chapter where its parent is in the part. The file MUST begin with the line that says it is generated and how to write it again, hold no date and no revision (the same pages give the same bytes), and use only what AsciidoctorJ reads as it is: parts and chapters with anchors that no volume has twice, source blocks, admonitions, tables, lists, cross references to pages of the volume and, for a page that is not in it, a link to the site where books.site names one and its text where it does not. Text that AsciiDoc would read as markup is passed through, and a diagram is shown as its source. A part that selects no page is a finding.

Enforced (check): .github: cd commons/docs && bun run verify — book.test.ts: text that AsciiDoc would read as markup is passed through, a line that would be a list or a title begins safely, and a bracket is an attribute; every block is written: headings with anchors, lists, tables, code, callouts, entries, tabs, diagrams, cards and trees; a link to a page of the volume is a cross reference, to another is a link to the site where the book names one and its text where it does not; a volume is its parts' pages in the order of the navigation: a page is a chapter, a page under it a section, a page once, a part of each group, and a part that takes nothing is found; the files of a presentation are written, a book into a folder that holds other things leaves them, and a file that is not what a build writes is found

Proved by: docs/suite/book.test.ts

Written in: docs/src/book.ts, docs/src/emit/asciidoc.ts

Tests: passed: suite/book.test.ts the files of a presentation are written, a book into a folder that holds other things leav; passed: suite/book.test.ts a link to a page of the volume is a cross reference, to another is a link to the site wher; passed: suite/book.test.ts a volume is its parts' pages in the order of the navigation: a page is a chapter, a page u; passed: suite/book.test.ts every block is written: headings with anchors, lists, tables, code, callouts, entries, tab; passed: suite/book.test.ts text that AsciiDoc would read as markup is passed through, a line that would be a list or

Cited by: book, config, emit/asciidoc, Documentation generator, presentation, Documentation

FR-009checkpassing

A configuration MAY give evidence: a folder of test results (results: CTRF, one <library>.ctrf.json for each library, with the requirements each test proves in extra.requirements, and meta.json with the commit and when), a snapshot of the GitHub issues of the repository (github: the JSON of the API, pull requests left out) and the issues of the libraries kept as typed code (issues: a library and its issues, with a scope where a library keeps more than one set). The generator MUST read them as files, import no library that makes them and reach no network; a folder that is not there MUST be no run recorded, a file that is not JSON or not CTRF a finding, a test's path a path from the repository's root made with the library's folder, and a ticket tied to a library by a label lib:<name> or a path commons/<name>/ and to requirements by the ids in its words.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: CTRF is read into tests with their requirements, a file that is not CTRF or not JSON is said so, and tickets of GitHub are read without pull requests and are tied to a library and requirements by label, path and words; evidence.test.ts: a configuration's evidence is checked, and a folder that is missing is no run, and a file that cannot be read is a finding

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/evidence.ts

Tests: passed: suite/evidence.test.ts CTRF is read into tests with their requirements, a file that is not CTRF or not JSON is sa; passed: suite/evidence.test.ts a configuration's evidence is checked, and a folder that is missing is no run, and a file

Cited by: build, config, evidence, Documentation generator, Documentation

FR-010checkpassing

Where evidence is configured, the site MUST have a Quality section: a dashboard with a row for each library (tests, passed, failed, skipped, requirements proved, open issues, open tickets) that says which commit and when the results are of, and a banner where a test failed; a page for each library (its failing tests with why, its skipped or planned, its slowest, the requirements no passing test proves, its open issues and tickets); the register of the issues and tickets; and a page for each issue kept as typed code (its facts, the requirements it cites as links where a specification of the kits has them and as code where none does, its evidence, its related issues). With no run recorded the pages MUST say so and nothing MUST be shown as passed; with no evidence there MUST be no section.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: with a run recorded, the site has the Quality section, a line on each requirement, library and module, a finding for a test of a requirement that is not there, and the numbers in quality.json; evidence.test.ts: with no run recorded, no requirement is shown as passing, the pages say so, and a build with no evidence configured has no Quality section

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/quality.ts

Tests: passed: suite/evidence.test.ts with a run recorded, the site has the Quality section, a line on each requirement, library; passed: suite/evidence.test.ts with no run recorded, no requirement is shown as passing, the pages say so, and a build wi

FR-011checkpassing

The evidence MUST also be beside the code: each requirement of a specification with a badge (passing where every test that names it passed, failing, partly run, no test run), its tests with their results and the open issues and tickets that name it; each library's page with its tests, requirements proved and open issues; each area's and module's page with the requirements its code is written to and what the tests of them say; and the numbers as quality.json. A test that names a requirement that its specification does not have MUST be a finding. A failing test MUST NOT be a finding of check: it is what the site is to show.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: with a run recorded, the site has the Quality section, a line on each requirement, library and module, a finding for a test of a requirement that is not there, and the numbers in quality.json; evidence.test.ts: with no run recorded, no requirement is shown as passing, the pages say so, and a build with no evidence configured has no Quality section; evidence.test.ts: the runs of the workflows are read from runs.json, and the Workflows page says how each ended, the last runs as marks, how long a run takes, which jobs failed, and what flaps; evidence.test.ts: the dashboard says which build this is and how the generator's own check ended, and a library with no report says why from what its job says; evidence.test.ts: the findings page says what the generator found while it made the site, by library, and that it found nothing where it did

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/quality.ts

Tests: passed: suite/evidence.test.ts with a run recorded, the site has the Quality section, a line on each requirement, library; passed: suite/evidence.test.ts with no run recorded, no requirement is shown as passing, the pages say so, and a build wi; passed: suite/evidence.test.ts the dashboard says which build this is and how the generator's own check ended, and a libr; passed: suite/evidence.test.ts the findings page says what the generator found while it made the site, by library, and th; passed: suite/evidence.test.ts the runs of the workflows are read from runs.json, and the Workflows page says how each en

Cited by: evidence, Documentation generator

FR-012checkpassing

The package MUST have a tool, tools/evidence.ts (bun tools/evidence.ts --library NAME [--out DIR]), that runs a library's suite with ifc test run, as a program and not as an import, and keeps its CTRF report as <DIR>/<library>.ctrf.json with a meta.json where there is none, whether the tests pass or fail; it MUST refuse, with exit status 2, a library with no suite.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the evidence tool runs a library's suite into CTRF the site reads, leaves meta.json, and refuses a library with no suite

Proved by: docs/suite/evidence.test.ts

Written in: docs/tools/evidence.ts

Tests: passed: suite/evidence.test.ts the evidence tool runs a library's suite into CTRF the site reads, leaves meta.json, and r

Cited by: Documentation

FR-013checkpassing

The package MUST have a tool, tools/ci-runs.ts, that asks the GitHub API (through gh) for the last runs of each workflow of the repository on main and, for the latest failed ones, which jobs failed and at which step, and writes them as runs.json; where the API cannot be reached it MUST write a file that says so and exit 0.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the runs of the workflows are read from runs.json, and the Workflows page says how each ended, the last runs as marks, how long a run takes, which jobs failed, and what flaps; evidence.test.ts: the tool that reads the runs writes a file that says so where the API cannot be reached, and the emergency page is made from the evidence alone

Proved by: docs/suite/evidence.test.ts

Written in: docs/tools/ci-runs.ts

Tests: passed: suite/evidence.test.ts the runs of the workflows are read from runs.json, and the Workflows page says how each en; passed: suite/evidence.test.ts the tool that reads the runs writes a file that says so where the API cannot be reached, a

FR-014checkpassing

The package MUST have a tool, tools/status-site.ts, that writes one self-contained page from the evidence alone (the end of the build's log, the commit and when, the tests library by library, why a library has no report, the workflows' latest runs), for a build that failed; it MUST use no part of the generator and exit 0 whatever is missing.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the tool that reads the runs writes a file that says so where the API cannot be reached, and the emergency page is made from the evidence alone

Proved by: docs/suite/evidence.test.ts

Written in: docs/tools/status-site.ts

Tests: passed: suite/evidence.test.ts the tool that reads the runs writes a file that says so where the API cannot be reached, a

FR-015checkpassing

A configuration MAY give problems (what could not be read while it was made) and the generator MUST make each a finding, and a lens that throws, in its reading, its pages or its files, MUST be a finding and not stop the site: one library or one lens MUST NOT keep the site from being made.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: a configuration's problems and a lens that throws are findings and the site is made without them

Proved by: docs/suite/evidence.test.ts

Tests: passed: suite/evidence.test.ts a configuration's problems and a lens that throws are findings and the site is made withou

Cited by: config

FR-016checkpassing

The site MUST show how quality moved, from a history of the evidence: the package MUST have a tool, tools/history.ts, that adds one run (for each library the counts of its tests, how long they took, and the identity and name of each test that failed, and the libraries that left no report) to the files history/runs/<time>-<run>.json, adds a run once, keeps the newest and refuses evidence with no time; the generator MUST read those files beside the results and show, on each library's page, trends of its tests, pass rate and time as lines drawn in the page, the tests that began to fail in the latest run with the range of commits since the run before, the tests that were fixed, those that failed in more than one separate stretch and pass in the latest (flapping), and its failures grouped by cause; and, on the dashboard, a pass-rate trend and the count of flapping tests for each library.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the history says how a library's tests moved over its runs: what began to fail, what was fixed, what keeps failing and what flaps, with trends, causes and the range of commits; evidence.test.ts: the history tool adds a run once, keeps the newest, and refuses evidence with no time

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/history.ts, docs/tools/history.ts

Tests: passed: suite/evidence.test.ts the history says how a library's tests moved over its runs: what began to fail, what was f; passed: suite/evidence.test.ts the history tool adds a run once, keeps the newest, and refuses evidence with no time

Cited by: evidence

FR-017checkpassing

A configuration MAY give a gate (evidence.gate: ran, tests-pass, no-blocking-issues, and requirements-proved with a minimum percent; the first three where none is given), and the site MUST show for each library which conditions it holds and why not, and a mark for it on the dashboard, and MUST enforce nothing: the gate is shown and the site is published whatever it says. The site MUST also have a page of the requirements by specification (how many are proved, partly, failing, with no test) and, for each library, a JSON file of its quality (quality/<library>.json: tests, failing tests, requirements not proved, gate, history, what began to fail, was fixed or flaps, open issues and tickets).

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: each library is held to the gate of the configuration, shown and enforced nowhere, and the requirements page says how each specification stands

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/insight.ts

Tests: passed: suite/evidence.test.ts each library is held to the gate of the configuration, shown and enforced nowhere, and the

Cited by: config

FR-018checkfailing

The site MUST have a page of the dependencies of the libraries, read from their package.json files (what each imports of the others and of npm, who imports it, its licence, and the external packages with who uses each), and an SBOM, sbom.cdx.json, in CycloneDX 1.5 with a component for each library and each external package version and the dependencies between them, the same for the same files; and a page of the TODO, FIXME, XXX and HACK notes left in the sources, with the file and line as a link.

Enforced (check): .github: cd commons/docs && bun run verify — check.test.ts: the site of commons builds with no finding, the same twice, with its sections, the Quality section and the issues of data

Proved by: docs/suite/check.test.ts

Written in: docs/src/pages/insight.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality

FR-019checkfailing

The site MUST have a page of the acceptance kits of the libraries (a folder acceptance, oat, uat or aat with kits that have a README), with each kit's kind and its known and fixed findings from its FINDINGS.md; and the page of the workflows MUST say for each workflow the share of runs that passed, the median minutes a run takes and the median time from a failure to the next pass, from the runs it reads.

Enforced (check): .github: cd commons/docs && bun run verify — check.test.ts: the site of commons builds with no finding, the same twice, with its sections, the Quality section and the issues of data

Proved by: docs/suite/check.test.ts

Written in: docs/src/pages/insight.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality

FR-020checkpassing

The site MUST have a page of hotspots and ownership read from git log at the build in one pass: for each library its commits and authors in the last 90 days and its bus factor (how few authors made half of its commits), counted and never named; the files changed in the most commits; and the specifications changed after the newest test that proves them, with the days between. Where the history is not there the page MUST say so and show nothing made up, and a short history MUST be said to be short.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the log of git is read into commits, the bus factor is how few authors made half of the commits, a file's last change is its newest commit, and a repository with no history is said to have none

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/git.ts

Tests: passed: suite/evidence.test.ts the log of git is read into commits, the bus factor is how few authors made half of the co

FR-021checkfailing

The site MUST have a page of the repository's health made from its own files, naming for each check the OpenSSF Scorecard check it answers: whether the workflows declare their token's permissions, how many outside actions are pinned to a commit, that none runs untrusted code with secrets, the security policy, the licence, a tool that updates dependencies, a lockfile, CODEOWNERS, contributing guidance and tests in CI; it MUST say that settings of the host (branch protection, required reviews) are not shown by files.

Enforced (check): .github: cd commons/docs && bun run verify — check.test.ts: the site of commons builds with no finding, the same twice, with its sections, the Quality section and the issues of data

Proved by: docs/suite/check.test.ts

Written in: docs/src/pages/insight.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality

FR-022checkpassing

Where the evidence has the line coverage of a library (<library>.coverage.json, kept by tools/evidence.ts --coverage from the LCOV of the library's tests, source files only), the Quality dashboard MUST show its percent beside the pass rate and the library's page MUST show the percent, the number of lines and the least covered files; a library with no coverage shows none, and a coverage run that fails MUST NOT lose the test report.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: line coverage is read from the lcov of bun, left to the library's source files, shown as a percent on the dashboard and as the least covered files on the library's page

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/coverage.ts, docs/src/evidence.ts, docs/src/pages/quality.ts, docs/tools/evidence.ts

Tests: passed: suite/evidence.test.ts line coverage is read from the lcov of bun, left to the library's source files, shown as a

Cited by: coverage, evidence, Documentation generator

FR-023checkpassing

The workflows page MUST give, from the runs of the workflow that publishes the site, the four measures of DORA (deployment frequency, lead time, change failure rate, time to restore), saying what each is taken from; cancelled and skipped runs are left out, and with fewer than two runs it shows none.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the four measures of DORA are taken from the runs of the publishing workflow: publishes a day, the median minutes of a successful run, the share of runs that failed and the minutes from a failure to the next pass, and fewer than two runs give none

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/quality.ts

Tests: passed: suite/evidence.test.ts the four measures of DORA are taken from the runs of the publishing workflow: publishes a

FR-024checkpassing

Code of the language sql MUST be coloured by the lexer of the SQL language library (lang-sql/aide/text highlight, in the PostgreSQL dialect) where it reads the text with no error, so that a word is a keyword where the dialect says so, a function is a word followed by (, a word in a string or a comment is none of them and a dollar quote is one string, with the same colours the other languages give a keyword, a call, a number, a string and a comment; where the lexer cannot read the text (a stray character, a string that is not closed) it MUST be coloured by the grammar of Shiki as before; no run of text is lost or changed.

Enforced (check): .github: cd commons/docs && bun run verify — highlight.test.ts: SQL is coloured by the lexer of the SQL language library

Proved by: docs/suite/highlight.test.ts

Tests: passed: suite/highlight.test.ts SQL is coloured by the lexer of the SQL language library: a keyword, a call, a string with

FR-025checkpassing

Where a run is recorded, the entry of an export on its API page MUST say how many tests of the run, of its package, import it and how many of them failed (naming up to three failing ones), and link the library's results; an export no test imports MUST say so, and the module's page MUST say how many of its exports are imported by a test. It MUST say that importing is not calling.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the tests that exercise an export are those of its package whose files import it, by the name it is exported under, and the API page of an export says how many there are and whether any fails

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/exercise.ts, docs/src/pages/api.ts

Tests: passed: suite/evidence.test.ts the tests that exercise an export are those of its package whose files import it, by the n

FR-026checkpassing

The API page of a source file MUST list the open issues (kept as typed code, naming the file or a test of it in their evidence) and the open tickets (naming its path in their title or words) that name it, with a badge that counts them, and the file evidence of an issue MUST link to the file's page where it has one; a path that is only the beginning of another is another file, and with none the page says nothing of it.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the open issues and tickets that name a file are on the page of the file, with a badge, and an issue's file evidence links back to the page of the file

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/api.ts, docs/src/pages/quality.ts

Tests: passed: suite/evidence.test.ts the open issues and tickets that name a file are on the page of the file, with a badge, an

FR-027checkpassing

Where the evidence has the mutation run of a library (<library>.mutation.json, kept by tools/mutation.ts from Stryker's report: the mutants of each source file that were killed, timed out, survived or were not run), the Quality dashboard MUST show its score (the share the tests detected, errors and ignored mutants not counted), the library's page MUST show the score, its weakest files and the changes no test noticed, and the API page of a mutated file MUST show the file's score; a library with no run shows none. The tool MUST leave the working tree as it found it.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the report of Stryker is read into the mutants killed, surviving and not run of each source file, the score is the share the tests detected, and the dashboard, the library's page and the file's API page show it

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/evidence.ts, docs/src/mutation.ts, docs/src/pages/api.ts, docs/src/pages/quality.ts, docs/tools/mutation.ts

Tests: passed: suite/evidence.test.ts the report of Stryker is read into the mutants killed, surviving and not run of each sourc

Cited by: evidence, Documentation generator, mutation

FR-028checkpassing

The site MUST have a page of what changed since the commit the tests of the evidence ran on (or, where that commit is not in the history, in the last thirty commits): the changed files by library, and for each changed source file its line coverage, its mutation score and the open issues that name it, least covered first, with a file added since the tests ran shown as new; and the specifications changed. Without history it MUST say so and show nothing made up.

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the changes since the tests ran are read from git's name-status, each path is source, test, specification or other, and with no history the page says so

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/pages/impact.ts

Tests: passed: suite/evidence.test.ts the changes since the tests ran are read from git's name-status, each path is source, test

FR-029checkfailing

The site MUST have a section Repo Ops that explains how the repository is operated, made by a lens (repoOpsLens, ./lens/repo-ops) from pages people write in Markdown and from typed facts the configuration passes, so that what can be generated stays true: a page of the workflows (each one's file, its triggers, its jobs and what it is for, read from the typed definitions the workflow files are made from), a page of the commands of the repository's operations program (each verb's words, summary, effect, tier, whether it previews, checks and is safe to repeat, its options and its examples, read from the program's own typed verb definitions, with a link to the page of the verb in Programs), and a page of the facts of the release (the distribution mode and its targets). The pages written by people link to the details elsewhere in the site and do not copy them (a Markdown link written site:<path> goes to that page of the site, and the check of the links finds it where the page is not there). A page the lens cannot read is a finding and the other pages are made; a section with no page is not in the top bar.

Enforced (check): .github: cd commons/docs && bun run verify — repo-ops.test.ts: the lens makes the Repo Ops pages from guides and typed facts, a page that cannot be read is a finding, and commons' site has the section with the workflows and every verb of repoctl

Proved by: docs/suite/repo-ops.test.ts

Written in: docs/src/lens/repo-ops.ts

Tests: passed: suite/repo-ops.test.ts a Markdown link written site:<path> goes to that page of the site, with its anchor, and an; passed: suite/repo-ops.test.ts a page with no typed facts given says there are none and makes no row up; passed: suite/repo-ops.test.ts the lens makes its pages from a guide and the facts it is given, and a page that cannot be; failed: suite/repo-ops.test.ts the site of commons has the section Repo Ops with every workflow and every verb read from

Cited by: Documentation generator, lens/repo-ops

FR-030checkno test run

The Quality section MUST have a page of the build's findings, quality/build-findings.html, made from the findings of the runs of the workflows that the evidence holds (findings-history/runs/**/*.json, the files of commons 0038-build-policy FR-006, laid out from the history branch by the workflow site) and from the accepted risks (accepted-findings.json, read from the typed files by ci/accepted.ts --json): the policy it states MUST be written from the typed values the workflows are made from (the red causes with their reasons and the release policy with its day), so that the page and the pipeline cannot disagree; it MUST show the counts (open, new in the latest run, fixed in it, accepted), the findings by module with the age of the oldest, the trend by workflow, each open finding with its tool, code, place, severity, age and stable id, and each accepted risk with its owner, reason, end and approver, an acceptance that has ended being shown as ended and its finding as open again; it MUST carry the banner Owner review due where the release policy has ended on the day of the latest run; it MUST give every row as quality/build-findings.json and quality/build-findings.csv; and where no run has kept findings it MUST say so and show nothing as a pass.

Enforced (check): .github: cd commons/docs && bun test suite/ — findings.test.ts: the page, the counts, the accepted risks, the exports and the banner, from findings kept as the workflows write them

Proved by: docs/suite/findings.test.ts

Written in: docs/src/pages/findings.ts

Cited by: evidence

FR-032checkno test run

The site MUST have a page quality/package about the package @intellectual-frontiers/commons, made from the evidence: package.report.json (what the packer reports when it packs the package: the files and bytes of the package, of each library and of each kind of file, its dependencies and its optional peers with their ranges, and its budget) and usage.<consumer>.json (the answer of repoctl usage --json for a consumer repository). It MUST show the package against its budget with the share used, the sizes by kind of file and by library (filterable), what the package installs and what it asks of the consumer, and, for each consumer kept, the libraries imported, those reached through them and those never touched with their sizes; it MUST work out nothing but the share of the budget; a file that is not what its name says MUST be a finding of the generator and MUST NOT stop the page; and where no report is kept the page MUST say how to make one and show nothing as measured (commons 0036-distribution FR-032, FR-034).

Enforced (check): .github: cd commons/docs && bun run verify — evidence.test.ts: the package page shows the report against its budget, by kind and by library, the peers and each consumer, a file that is no report is a finding, and no report says how to make one

Proved by: docs/suite/evidence.test.ts

Written in: docs/src/package.ts, docs/src/pages/package.ts

Cited by: evidence

Out of scope

  • Publishing the site (GitHub Pages, a private artifact store): the consumer's; this library writes a folder.
  • What the site of commons shows: commons 0011-documentation.

Edge cases

  • A repository with no spec kit: a site with its API reference and its overview, and no Specifications section, per FR-005.
  • A configuration whose repository is not a GitHub address: links to files are made from it as given, per FR-006.
  • ifc-docs build run in a folder with no docs.config.ts up to the root: a message that says what to write, and the exit status 2, per FR-003.

Assumptions

  • The consumer has Bun, or Node 26 (which reads TypeScript for the configuration), and installs the package from a registry.

Open questions

OQ-1open question

Whether the command should also serve the site for a reader (ifc-docs serve), or leave that to repoctl docs serve.

Key entities

  • Configuration - what a repository says about its packages, specifications, citations and lenses.
  • Lens - a function that turns what a library says about itself into pages.

Success criteria

SC-001success criterion

A repository that has never seen commons installs @intellectual-frontiers/docs and builds a checked static site from a configuration of a dozen lines.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

book, build, config, coverage, emit/asciidoc, evidence, Documentation generator, lens/repo-ops, mutation, presentation, Documentation generator, Documentation, Distribution

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