IF Commons GitHub

Repoctl docs verbs

0011Active

0011-repoctl-docs · owner if · domain commons

Requirements

FR-001checkpassing

A configuration with docs: { config, out } (docs.config.ts and _site where it names none) MUST turn on the verbs docs build (a mutation that previews with --dry-run), docs check (a report of the public tier that writes nothing in the repository) and docs serve; a configuration with no docs has none of them.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/docs.test.ts: the verbs are there only with docs settings

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

Written in: repoctl/src/logical/docs.ts, repoctl/src/physical/verbs/docs.ts

Tests: passed: suite/docs.test.ts the docs verbs are in the help with docs settings and not without, and build previews with

Cited by: Repoctl, logical/docs, physical/verbs/docs

FR-002checkpassing

The generator MUST be loaded where it is installed (the node_modules of the repository or above it, else by its package name) as an optional peer, its main called with the arguments of build or check as ifc-docs reads them (build --out DIR --config FILE, check --config FILE, paths absolute from the repository's root); where it cannot be loaded the verb MUST end with 1 and the problem E-DOCS-GENERATOR-MISSING, whose explanation says how to install it.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/docs.test.ts: the generator is loaded from the repository and missing is its typed problem

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

Tests: passed: suite/docs.test.ts the generator is loaded from the repository's own dependencies and is asked for build and

Cited by: Repoctl in your repository

FR-003checkpassing

A generator that ends with a status other than 0 MUST be the problem E-DOCS-FAILED and the status 1; docs build MUST say the folder it built and docs check MUST say there is no finding where there is none.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/docs.test.ts: a failing generator is E-DOCS-FAILED

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

Tests: passed: suite/docs.test.ts a generator that ends with a status other than 0 is E-DOCS-FAILED

FR-004checkpassing

docs serve MUST build the site and then serve the folder on a loopback port only (127.0.0.1, the port of --port, 4173 by default, 0 for one the system chooses) until it is interrupted or --for SECONDS has passed; it MUST NOT send the site anywhere and MUST answer a path that is not there with 404.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/docs.test.ts: serve answers on loopback only

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

Tests: passed: suite/docs.test.ts serve builds the site and serves it on a loopback port: the index, a 404 for a missing pat

Cited by: Repoctl, logical/docs, physical/verbs/docs, Repoctl in your repository

Acceptance scenarios

  1. Given a configuration with docs, When the help is read, Then docs build, serve and check are listed, per FR-001.
  2. Given a repository with no installed generator, When docs check runs, Then it ends with 1 and E-DOCS-GENERATOR-MISSING, per FR-002.
  3. Given a generator installed in the fixture repository, When docs build runs, Then it is asked for build --out <root>/_site --config <root>/docs.config.ts and the site is there, per FR-002.
  4. Given a generator that ends with 3, When docs check runs, Then E-DOCS-FAILED, per FR-003.
  5. Given a built folder, When it is served on port 0, Then / answers its index.html, a missing path 404, and the address is a loopback one, per FR-004.

Out of scope

Edge cases

  • A port that is not a number from 0 to 65535: a usage error (2), per FR-004.
  • A build that fails before serving: nothing is served, per FR-004.

Assumptions

  • The generator package exports main(argv) that returns the exit status of the ifc-docs command line.

Open questions

  • None.

Key entities

  • Docs settings - the configuration file of the generator and the folder of the site.

Success criteria

SC-001success criterion

A repository that installs the generator builds, checks and previews its site with one command.

Review & acceptance checklist

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

Cited by

Repoctl, logical/docs, physical/verbs/docs, Repoctl in your repository

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