From 942d7a54f91aed84820d9831501016cfb9830f31 Mon Sep 17 00:00:00 2001 From: 7487 <1042653432@qq.com> Date: Mon, 7 Sep 2026 22:05:18 +0800 Subject: [PATCH] docs(providers): cite factory.ts by its entry point, not a line Seven provider docs cited a line inside factory.ts, and all seven were stale: postgres.md's `:62` is the end of a docblock, druid.md's `:95` is the libsql import, libredb.md's `:100` the oracle import. They now name `createDatabaseProvider()` and link the file, the way mssql.md, mysql.md, mongodb.md and redis.md already do. The factory test built its population by filtering NAMED_CITATIONS, so renaming the phrase in every doc shed four assertions and stayed green. The population now comes from a sorted walk of docs/providers/, selected on the entry point's name (oracle.md links the file without naming it and owes no such sentence), and asserts non-empty rather than pinning a count. Every provider doc is also checked for a `factory.ts:`. Fixes #620 Co-Authored-By: Claude Fable 5.1 --- docs/providers/clickhouse.md | 4 +-- docs/providers/couchbase.md | 4 +-- docs/providers/druid.md | 3 +- docs/providers/elasticsearch.md | 4 +-- docs/providers/libredb.md | 4 +-- docs/providers/opensearch.md | 4 +-- docs/providers/postgres.md | 3 +- ...provider-docs-monitoring-citations.test.ts | 28 ++++++++++++++----- 8 files changed, 35 insertions(+), 19 deletions(-) diff --git a/docs/providers/clickhouse.md b/docs/providers/clickhouse.md index 76c93476..e7d081a5 100644 --- a/docs/providers/clickhouse.md +++ b/docs/providers/clickhouse.md @@ -126,8 +126,8 @@ is overridden, for the trailing-clause trap in [§3.8](#38-the-preparequery-over ### 2.4 Registration & lifecycle -The factory wires ClickHouse in via a dynamic import -([`factory.ts:87`](../../src/lib/db/factory.ts)): +The factory wires ClickHouse in via a dynamic import inside `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case 'clickhouse': { diff --git a/docs/providers/couchbase.md b/docs/providers/couchbase.md index 513fa3a7..6b1452e8 100644 --- a/docs/providers/couchbase.md +++ b/docs/providers/couchbase.md @@ -119,8 +119,8 @@ a SQL dialect is expressed through `queryLanguage: "sql"`, not through the class ### 2.4 Registration & lifecycle -The factory wires Couchbase in via a dynamic import -([`factory.ts:93`](../../src/lib/db/factory.ts)): +The factory wires Couchbase in via a dynamic import inside `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case 'couchbase': { diff --git a/docs/providers/druid.md b/docs/providers/druid.md index 7f1ad8b3..e04c17a0 100644 --- a/docs/providers/druid.md +++ b/docs/providers/druid.md @@ -131,7 +131,8 @@ the case [`docs/ADDING_A_PROVIDER.md`](../ADDING_A_PROVIDER.md) names ClickHouse ### 2.4 Registration & lifecycle -The factory wires Druid in via a dynamic import ([`factory.ts:95`](../../src/lib/db/factory.ts)): +The factory wires Druid in via a dynamic import inside `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case "druid": { diff --git a/docs/providers/elasticsearch.md b/docs/providers/elasticsearch.md index abfa1a4d..5a4e875e 100644 --- a/docs/providers/elasticsearch.md +++ b/docs/providers/elasticsearch.md @@ -129,8 +129,8 @@ both exports honestly thin (each one names its product and nothing else). ### 2.4 Registration & lifecycle -The factory wires the type-id in via a dynamic import -([factory.ts:118](../../src/lib/db/factory.ts)): +The factory wires the type-id in via a dynamic import inside `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case "elasticsearch": { diff --git a/docs/providers/libredb.md b/docs/providers/libredb.md index 33de39e0..d5a947da 100644 --- a/docs/providers/libredb.md +++ b/docs/providers/libredb.md @@ -106,8 +106,8 @@ out in parallel. ### 2.4 Registration & lifecycle The factory wires LibreDB in via a dynamic import so the `@libredb/libredb` driver is only loaded -when a LibreDB connection is actually opened -([`factory.ts:100`](../../src/lib/db/factory.ts)): +when a LibreDB connection is actually opened by `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case 'libredb': { diff --git a/docs/providers/opensearch.md b/docs/providers/opensearch.md index c311a76d..9980a50d 100644 --- a/docs/providers/opensearch.md +++ b/docs/providers/opensearch.md @@ -134,8 +134,8 @@ OpenSearchProvider (search/index.ts:967) ElasticsearchProvider (search/i ### 2.4 Registration & lifecycle -The factory wires the type-id in via a dynamic import -([factory.ts:123](../../src/lib/db/factory.ts)): +The factory wires the type-id in via a dynamic import inside `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case "opensearch": { diff --git a/docs/providers/postgres.md b/docs/providers/postgres.md index 5afe0956..fda75621 100644 --- a/docs/providers/postgres.md +++ b/docs/providers/postgres.md @@ -88,7 +88,8 @@ rather than reimplementing them: ### 2.3 Registration & lifecycle The factory loads the provider via dynamic import so the `pg` driver is only pulled in when a -PostgreSQL connection is opened ([`factory.ts:62`](../../src/lib/db/factory.ts)): +PostgreSQL connection is opened by `createDatabaseProvider()` +([`factory.ts`](../../src/lib/db/factory.ts)): ```ts case 'postgres': { diff --git a/tests/unit/provider-docs-monitoring-citations.test.ts b/tests/unit/provider-docs-monitoring-citations.test.ts index 8043f360..44130bb8 100644 --- a/tests/unit/provider-docs-monitoring-citations.test.ts +++ b/tests/unit/provider-docs-monitoring-citations.test.ts @@ -25,13 +25,14 @@ * same eight, and the docs in scope carry no `:` suffix. * * SCOPE, deliberately narrow: the whole of every document in `NAMED_CITATIONS`, plus the - * monitoring seam of the two search docs. The rest of `docs/providers/` still cites code by line - * in quantity — a pre-existing backlog this round did not open — and the two search docs are - * guarded only inside their monitoring section. Nothing here asserts that the uncovered + * monitoring seam of the two search docs, plus one file across every provider doc: `factory.ts` + * is cited by its entry point and never by a line. The rest of `docs/providers/` still cites code + * by line in quantity — a pre-existing backlog this round did not open — and the two search docs + * are guarded only inside their monitoring section. Nothing here asserts that the uncovered * citations are correct; they are simply not measured yet. */ import { describe, expect, test } from "bun:test"; -import { readFileSync } from "node:fs"; +import { readdirSync, readFileSync } from "node:fs"; import path from "node:path"; const ROOT = path.resolve(import.meta.dir, "../.."); @@ -43,6 +44,12 @@ const BASE_PROVIDER = "src/lib/db/base-provider.ts"; const MIGRATION_GENERATOR = "src/lib/schema-diff/migration-generator.ts"; const FACTORY = "src/lib/db/factory.ts"; +/** Sorted: `readdirSync` returns filesystem order — green here, red on the next machine. */ +const PROVIDER_DOCS = readdirSync(path.join(ROOT, "docs/providers")) + .filter((entry) => entry.endsWith(".md")) + .sort() + .map((entry) => `docs/providers/${entry}`); + /** * The docs this round rewrote, the source their prose links to, and the method names that now * stand where a line number used to. The list is the point: renaming any of these breaks the @@ -238,13 +245,20 @@ describe("provider docs rewritten this round: code cited by name, whole file", ( } test("provider docs name the factory's entry point rather than a line inside it", () => { - for (const { doc } of NAMED_CITATIONS.filter((citation) => - read(citation.doc).includes("`createDatabaseProvider()`"), - )) { + // Selected on the entry point's NAME, not on the link: fourteen docs link `factory.ts`, and + // one of them (oracle.md) does so without naming the function — prose it does not owe. + const docs = PROVIDER_DOCS.filter((doc) => read(doc).includes("`createDatabaseProvider()`")); + // A derived population can derive to nothing, and a loop over nothing passes; renaming the + // phrase everywhere used to shed four assertions and stay green (#620). + expect(docs.length).toBeGreaterThan(0); + for (const doc of docs) { expect(read(doc)).toMatch( /`createDatabaseProvider\(\)`\s*\(\[`factory\.ts`\]\(\.\.\/\.\.\/src\/lib\/db\/factory\.ts\)\)/, ); } + for (const doc of PROVIDER_DOCS) { + expect(read(doc), `${doc} cites a line inside factory.ts`).not.toMatch(/factory\.ts:\d/); + } expect(read(FACTORY)).toMatch(/^export async function createDatabaseProvider\(/m); }); });