test(provider-docs): derive the named citations and assert them in declaration order (#641) - #1194
Merged
Merged
Conversation
…libredb#641) `NAMED_CITATIONS` was a hand-written literal and nothing measured that it still held every name the doc cites. Add a citation to a guarded doc and the guard said nothing. Derive the population inside the test — the names the doc cites as `` `name( `` intersected with the members `declarationLine` can match — and assert the checked-in list equals it. The literal stays the reviewed expectation; the derivation is what goes red when a doc changes what it cites. A guard over nothing passes, so the derived set is asserted non-empty first (libredb#620). Compared with `toEqual`, which also measures the "in declaration order" claim the clickhouse, druid and couchbase comments make and which four entries did not honour. Inline notes moved with their names. Widened every entry to the derivation, not just the seven subsets: the three "tracks the doc" entries are subsets, so all eleven were red regardless of scope. Each added name was read in its own doc first — no name is cited while talking about another file. Verified: `bun test tests/unit/provider-docs-monitoring-citations.test.ts` 76 pass, `expect() calls` 480 -> 818 (+338). Mutation-checked both directions: dropping a citation from `trino.md` fails the entry, and citing a declared-but-unlisted member fails only the new assertion while "names methods that ... really declares" stays green.
…g citations TypeScript accepts only `public override async`, and the derivation expected `async` before `override`, so a member declared that way was dropped: a legal refactor of a guarded source went red, and a newly cited name would have gone unmeasured. None of the eleven sources declares one today.
Member
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
NAMED_CITATIONSwas a hand-written literal, and nothing measured that it still held every name the doc cites. Adding a citation to a guarded doc changed nothing; the guard was only as wide as whoever last edited the array. This derives the population inside the test and asserts the checked-in list equals it, then widens the array to what the derivation returns.Type of Change
Related Issue
Closes #641
Changes Made
citedNames()(every`name(a doc cites, in document order),declaredMembers()(the class membersdeclarationLinecan match, in declaration order, deduplicated) andderivedCitation()(their intersection).NAMED_CITATIONSentry: assert the derived set is non-empty first — a guard over nothing passes, the way tests: the factory-citation guard can go vacuous, and 7 provider docs still cite a line inside factory.ts #620 shed four assertions and stayed green — thentoEqualthe literal against it.mssql.md§12 abovequeryReadOnly,redis.mdobject surface abovelistContainers) moved with their names.main, the three "tracks the doc" entries are subsets too, so the assertion went red on all eleven regardless of scope.sqlite7 -> 24,mssql13 -> 30,trino2 -> 20,mysql11 -> 29,oracle13 -> 32,mongodb10 -> 24,redis14 -> 36,postgres9 -> 36,clickhouse20 -> 23,druid18 -> 19,couchbase24 -> 26.getHealth,getOverview,getPerformanceMetrics,getSlowQueries,getActiveSessions,getTableStats,getIndexStats,getStorageStats) plus the object surface (readObjectSource,describeObjects,buildObjectEdit/applyObjectEdit,scanKeyGroups/scanKeysPage,objectDetailFrom,keyspaceDetail,readDatabaseSizeBytes,getDatabaseName,getPgStatActivity,buildQueryResult) and the transaction surface (commitTransaction,rollbackTransaction,isInTransaction,endOpenQueryTransaction,expireTransaction,queryReadOnly,queryWithMaterializedFallback).Testing
bun test tests/unit/provider-docs-monitoring-citations.test.ts— 76 pass, 0 fail,expect() calls480 -> 818 (+338), which is the delta the issue asks to report. 65 tests before, 76 after (the 11 new per-entry assertions); the widened literals account for the rest.Mutation-checked in both directions, so the new assertion is doing work:
docs/providers/trino.mdfails both the entry's existing assertion and the new one.describeConnectFailure()intrino.md) leaves "names methods that ... really declares" green and fails only the new assertion — which is the gap in the issue, reproduced and then closed.Also run:
bun run typecheckclean,bunx biome formatreports no changes.Test Environment
mainat9d9d1eeChecklist
bun run test:coverageandbun run coverage:check)src/lib/db/providers/, I updated the matchingdocs/providers/documentation andtests/integration/db/tests in the same PR (provider triad)Additional Notes
No
src/change, so the provider triad does not apply. The coverage checkbox is left unmarked because I did not run the full coverage gate locally; this diff adds test-file lines only.