tests: the factory-citation guard can go vacuous, and 7 provider docs still cite a line inside factory.ts

[cevheri]

Follow-up to #604. Both halves of this are my debt rather than the contributor's: the one-line filter I suggested on that PR carries the first gap, and the second is the factory-link slice of DOC4.

#604 replaced a hand-listed pair with a derived population, which was the right move and is measurably stronger: reintroducing factory.ts:63 into either mysql.md or mongodb.md now turns the suite red, and the hand-listed pair caught neither.

for (const { doc } of NAMED_CITATIONS.filter((citation) =>
  read(citation.doc).includes("`createDatabaseProvider()`"),
)) {

Gap 1: the guard can empty itself and stay green

A derived population can derive to nothing, and a for loop over nothing passes. Measured on the #604 head commit, renaming the cited phrase in all four docs at once:

	pass	fail	assertions
baseline	23	0	207
phrase renamed in all four docs	23	0	203

Four assertions disappear and nothing goes red. The four missing assertions are the only trace.

The fix is not to pin the count. expect(docs.length).toBe(4) is just another hand-copied number in a test whose whole subject is hand-copied numbers, and it would go red on the fifth doc for no good reason. Derive the population from the filesystem and assert only that it is not empty.

Gap 2: seven provider docs still cite a line inside factory.ts

Measured 2026-09-07 against src/lib/db/factory.ts, where createDatabaseProvider() is declared at line 63 and each engine's dynamic import sits in its own case. All seven are wrong today, and none of them is off by a little:

Doc	Cites	What is actually there
postgres.md	factory.ts:62	*/, the end of a docblock (case "postgres" is at 74)
clickhouse.md	factory.ts:87	a closing } (case at 109)
couchbase.md	factory.ts:93	a blank line (case at 161)
druid.md	factory.ts:95	the libsql import (case at 117)
libredb.md	factory.ts:100	the oracle import (case at 176)
elasticsearch.md	factory.ts:118	a comment line (case at 145)
opensearch.md	factory.ts:123	a closing } (case at 150)

redis.md was the eighth and #604 fixed it.

Fix

1. Rewrite the seven citations to name the entry point instead of a coordinate, keeping the link to the file. mssql.md, mysql.md and mongodb.md are the model:

   Loaded on demand by `createDatabaseProvider()` ([`factory.ts`](../../src/lib/db/factory.ts)):
   

2. In tests/unit/provider-docs-monitoring-citations.test.ts, build the factory test's population by walking docs/providers/ and selecting the docs that name the entry point, instead of filtering NAMED_CITATIONS. Sort the walk: readdirSync returns filesystem order, so an unsorted list is green here and red on the next machine. tests/unit/theme-token-usage.test.ts has that walk already; tests/unit/agent-documentation.test.ts has the non-empty idiom.

One trap worth knowing before you start. Select on the entry-point name, not on the link to factory.ts. Fourteen provider docs link that file, and oracle.md:78 reads Loaded on demand by the factory ([factory.ts](../../src/lib/db/factory.ts)): without ever naming createDatabaseProvider(). A link-based population would demand prose that doc does not owe, and the test would fail for a doc that is already correct. This is the difference between a guard that measures a policy and one that dictates a sentence.

Done when

• grep -rn 'factory\.ts:[0-9]' docs/providers/ returns nothing
• the factory test's population comes from the filesystem, with a derived non-empty assertion and no pinned count
• the probe from Gap 1 is red: rename createDatabaseProvider() in every doc that cites it, and the suite must fail rather than quietly shed assertions
• bun run test green

Two docs' worth of prose plus one test, no product code.

Tracked in docs/BACKLOG.md under DOC4, which is the wider remainder this is one slice of.

---

Curated for Hacktoberfest 2026. Comment to claim it before you start so two people do not work on the same issue. A PR must reference this issue and land with its tests in the same change; see CONTRIBUTING.md. Repo rules that apply: run bun run test (never bare bun test), and the 100% line-coverage gate must stay green. Local bun run test also needs the helm binary on PATH for unrelated chart tests, see #570 if it bites.