libredb / libredb/libredb-studio

Seven of eight NAMED_CITATIONS entries are hand-picked subsets, so a doc can add a citation nothing measures

Open
#641 1 comment 0 reactions 1 assignee Claimed by @shafaqub View on GitHub
enhancement good first issue hacktoberfest
Dominant language
TypeScript
Stars
726
Forks
119
Avg merge
7h 47m
Merged PRs (30d)
265

Description

`tests/unit/provider-docs-monitoring-citations.test.ts` holds a `NAMED_CITATIONS` list. Each entry names a provider doc, its source file, and the methods the doc cites by name, and two tests then assert the doc carries no `.ts:` anywhere and that every listed name is really declared in the source. That is what keeps a named citation from rotting the way a line number does.

The `methods` list is a hand-written literal, and **nothing measures that it is still the full set of names the doc cites.** Add a citation to a guarded doc and the guard says nothing. Rename a method the list does not happen to mention and the doc goes wrong while the suite stays green. The guard is only as wide as whoever last edited the array.

Measured on `main` at 53090b0d, as the intersection of the names the doc cites as `` `name( `` and the members the source declares with an access modifier (what the test's own `declarationLine` can match):

| Entry | listed | citable | uncovered |
| --- | --- | --- | --- |
| `docs/providers/clickhouse.md` | 20 | 20 | 0 |
| `docs/providers/mongodb.md` | 10 | 20 | 10 |
| `docs/providers/mssql.md` | 12 | 25 | 13 |
| `docs/providers/oracle.md` | 13 | 26 | 13 |
| `docs/providers/mysql.md` | 11 | 25 | 14 |
| `docs/providers/redis.md` | 11 | 26 | 15 |
| `docs/providers/postgres.md` | 9 | 32 | 23 |
| `docs/providers/trino.md` | 2 | 16 | 14 |

`clickhouse.md` (#639) is the only entry that is the full intersection rather than a subset, and it is the model to copy. The other seven are missing mostly the monitoring surface: `getHealth`, `getOverview`, `getPerformanceMetrics`, `getSlowQueries`, `getActiveSessions`, `getTableStats`, `getIndexStats` and `getStorageStats` are cited by name in doc after doc and measured in none of them.

**The fix.** Derive the intersection inside the test and assert the checked-in list equals it, so the literal stays the reviewed expectation and the derivation is what goes red when a doc changes what it cites. Then widen the seven subsets to what the derivation returns.

Two things to get right, both of which this repo has been bitten by before:

1. **A derived population can derive to nothing, and a loop over nothing passes.** #620 shed four assertions and stayed green exactly that way. Assert the derived set is non-empty before comparing, the way the `createDatabaseProvider()` test in this same file does with `expect(docs.length).toBeGreaterThan(0)`.
2. **Read the names before pasting them.** A name can be declared in the source and yet be cited by the doc while talking about a different file, in which case it does not belong to that entry. The derivation is a starting point for the list, not an oracle. Sanity-check each name you add.

There is a smaller loose end in the same array, and this is the natural change to fold it into: the `clickhouse.md` entry's comment says its methods are listed "in declaration order", but nothing asserts that, and four of the eight entries (`oracle`, `mongodb`, `redis`, `postgres`) are not in declaration order today. Either drop the phrase or assert the ordering and reorder those four. The search seam tests further down the same file already assert ordering, with `expect(lines).toEqual([...lines].sort((a, b) => a - b))`, so there is a pattern to copy if you want it measured.

**Before you start**, read the header comment at the top of the test file. It explains why the policy is pinned rather than the coordinates, and it states the guard's deliberately narrow scope. This issue widens that scope; it does not change the policy.

**Verifying.** `bun test tests/unit/provider-docs-monitoring-citations.test.ts` must be green, and the assertion count must go up, not just the pass count. The test count in that file does not change when a `methods` list grows, so `31 pass` on its own proves nothing: `bun test` prints `expect() calls`, and that is the number to report. For reference, widening the clickhouse entry from 6 names to 20 in #639 moved it from 269 to 297, which is exactly 14 names times 2 assertions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.