ReviewOS

stacks/bun-query-builder

Add a docs-lint test so broken documentation fails CI

#1069
Closed glennmichael123 opened this 22 days ago · 0 comments
22 days ago

#1066 fixed ~40 documented calls to methods that do not exist, six pages that began mid-code-block, and 132 identifiers whose _ had been rewritten to *. All three classes were introduced silently by earlier commits and survived months because nothing checks documentation mechanically.

An offline test would catch every one of them, needs no database, and runs in milliseconds:

  • fence parity — every docs/**/*.md has an even number of ``` fences. Catches the six truncated pages.
  • no mangled identifiers — no [A-Za-z0-9]\*[A-Za-z0-9], and no _ between operands. Catches the created*at / 7 _ 24 _ 60 class, while leaving SELECT *, COUNT(*) and **bold** alone.
  • every db./trx./tx. receiver names a real method — compare against Object.keys(createQueryBuilder({ schema })). This is the check that would have caught db.update, and it is the cheapest of the four.
  • every DB_* env var mentioned in docs is one src/ actually reads — currently DB_USER, DB_TIMEOUT, DB_RETRY_ATTEMPTS, DB_HEALTH_CHECK_INTERVAL and DB_WAIT_READY_ATTEMPTS appear in docs and are read nowhere (see #1070).

It fails today on the env-var item even after #1066, so it has immediate value beyond regression cover.

Found while auditing after #1001.

Sign in to comment on this issue.