docs(clickhouse): cite code by name, not by line

[7487]

Description

docs/providers/clickhouse.md cited code by line number in 16 places (the 17th in #588, factory.ts:87, already went with #629), and on today's main 13 of them are stale — the four that name a method beside the line all miss, and both index.ts:637 cites now land on a closing brace:

---

Cited	Declared today	Names now
prepareQuery() index.ts:562	:596	prepareQuery()
resolveConnection() index.ts:402	:420	resolveConnection()
getCapabilities() index.ts:461	:503	getCapabilities()
getLabels() index.ts:489	:553	getLabels()
query() index.ts:593	:674	query()
runMaintenance() index.ts:920	:1013	runMaintenance()
index.ts:637 (×2, error classification by exception code)	}	mapClickHouseError()
RAW_TEXT_COLUMN index.ts:102	:105	RAW_TEXT_COLUMN
transport.ts:114 (ClickHouseTransport)	:127	ClickHouseTransport
transport.ts:178 (ClickHouseTransportError)	:191	ClickHouseTransportError
introspect.ts:290 (declared type kept verbatim)	readColumn() at :327	readColumn()
connection-string-parser.ts:66	parseConnectionString() at :96	parseConnectionString()
transport.ts:37, transport.ts:69, introspect.ts:186	still right	ClickHouseQueryResult, ClickHouseQueryResult.mutationCount, isNullableType()

Every citation now names the declaration and links the file without a coordinate, the shape mssql.md, mongodb.md and postgres.md (#636) already have. grep -oE '\.ts:[0-9]+' docs/providers/clickhouse.md returns nothing.

The doc joins NAMED_CITATIONS with src/lib/db/providers/sql/clickhouse/index.ts as its source and the twenty class methods it cites by name — every name( the doc cites that index.ts declares with an access modifier, in declaration order — so the guard's two tests now assert the doc carries no .ts:<line> and that each of those is really declared. The names in transport.ts, introspect.ts and the parser, and resolveConnection() in index.ts itself, are module-level declarations the guard's declarationLine does not read, so they are cited but not measured — the same standing as postgres.md's sql-base.ts names.

---

Type of Change

• Documentation update
• Test addition or update

---

Related Issue

Fixes #588

---

Changes Made

• docs/providers/clickhouse.md: 16 citations rewritten; §2.3's getPlaceholder() row (the method went with fix(sql): bind the inline row edit's values, and quote the remaining interpolated ones (#290) #304) is replaced by a sentence under the table that keeps the named-parameters-only point
• tests/unit/provider-docs-monitoring-citations.test.ts: one NAMED_CITATIONS entry

---

Testing

• I have tested this locally
• I have added/updated tests
• All existing tests pass

	pass	fail
bun test tests/unit/provider-docs-monitoring-citations.test.ts	31	0
same, with only the doc reverted to main	29	2 (cites no line number anywhere, names methods that … really declares)

biome check, oxlint, eslint on the test file and tsc --noEmit are clean. Run under Bun 1.3.11 (the repo pins 1.4.2); this test only reads files.

[cevheri]

Thanks for this. Replacing line-number citations with named ones is exactly the right direction: line numbers go stale on the next edit to the provider, names do not, and the new guard entry turns the doc into something CI can keep honest. I verified all 16 rewritten citations resolve against the head commit, confirmed no .ts:NNN citations remain in the file, checked every relative link, and ran the guard test at PR head (31/31 pass). Formatting is clean.

Two things I would like updated before this lands. Neither is a correctness problem with what you wrote, they are both about the doc and the guard agreeing with each other.

1. getPlaceholder() in section 2.3 (line 123) does not exist any more.

That row is outside the diff, so I could not leave an inline note on it. It lists getPlaceholder() as an inherited SQLBaseProvider member, but the method was deleted in #304 (commit 02578ff, "had no callers") and is not present anywhere under src/. It is pre-existing, and the same stale name appears in mssql.md, oracle.md, druid.md, elasticsearch.md and opensearch.md, so fixing all of them is not your job here. But it is a name-based citation that fails to resolve, in the one file this PR rewrote to make name-based citations trustworthy, so it fits naturally in this change. The nuance the row was making (ClickHouse binds only named {name:Type} parameters, so a positional ? never applies) is worth keeping. It just needs to stop attributing that to a method that no longer exists. The other five docs can follow in a separate PR if you would like to take them.

2. The guard entry measures 6 methods, and the doc names about 20.

See the inline note. The PR body says "every method it names must really be declared", and that is the promise worth making. Right now the entry is narrower than the doc, which is why the getPlaceholder case above slips through unmeasured. Widening the list closes both findings at once.

Happy to take a second look as soon as you push. If you would rather split item 1 out, say so and I will file it separately, but the two really do belong together: item 2 is what makes item 1 impossible to reintroduce.

[cevheri]

The doc names roughly 20 symbols from index.ts (validate, connect, disconnect, getSchema, getHealth, getOverview, getSlowQueries, getActiveSessions, getPerformanceMetrics, getTableStats, getStorageStats, getIndexStats, and more), and every one of them is declared with an access modifier, so declarationLine() can match them exactly the way it matches the six listed here. Nothing is blocking the wider list.

That gap is what lets the stale getPlaceholder() row in section 2.3 sit unnoticed: the guard never looks at it. Could you extend methods to cover the symbols the doc actually cites? A short comment above the entry saying that the list is meant to track the doc, not a hand-picked subset, would help whoever adds the next provider entry keep the same bar.

Worth knowing for the follow-up: getPlaceholder() lives on the base class rather than in index.ts, so a widened list here will not catch inherited-member rows on its own. Naming only what index.ts declares is the correct scope for this entry. Item 1 in my summary is the manual fix for the inherited-member table.

[7487]

Widened to all 20 in 4e1edc8: every name( the doc cites that index.ts declares with an access modifier, in declaration order, with a comment above the entry saying the list tracks the doc rather than a subset. I recomputed that intersection from the doc and the source with a throwaway script and compared it against the entry: 20/20, same order.

One cited index.ts name is deliberately not in it: resolveConnection() is a module-level function (index.ts:420), so declarationLine() has nothing to match. The comment names it so the next person does not add it and wonder why the test goes red.

31/31 pass, biome / oxlint / eslint clean on the file.

[7487]

Both in 4e1edc8.

1. §2.3: the getPlaceholder() row is gone. Its point survives as a sentence under the table: SQLBaseProvider has had no placeholder helper since fix(sql): bind the inline row edit's values, and quote the remaining interpolated ones (#290) #304, and ClickHouse would not use one anyway — named {name:Type} only, and query() throws its QueryError before anything positional reaches the wire. I can take the same row in mssql / oracle / druid / elasticsearch / opensearch in a separate PR.

2. Guard entry: 6 → 20, every name( the doc cites that index.ts declares with an access modifier, in declaration order, plus the comment. Details in the inline reply.

bun test tests/unit/provider-docs-monitoring-citations.test.ts: 31 pass, 0 fail. PR body updated to say twenty rather than six.

[cevheri]

Merging this. The update closes both points, and I measured the claims rather than taking them:

• The list is exactly the doc-by-source intersection. I derived it independently and got the same 20 names in the same declaration order, with resolveConnection() the only cited index.ts name left out, for the reason your comment gives.
• The widening is measured, not decorative: assertions in this file go 269 -> 297, exactly 14 new methods times 2. The test count stays at 31, so "31/31 pass" on its own would not have shown that.
• The removed row kept the part that mattered. getPlaceholder appears nowhere in src/ today (grep -rn getPlaceholder src/ is empty), fix(sql): bind the inline row edit's values, and quote the remaining interpolated ones (#290) #304 is the commit that removed it, and the sentence you kept matches query(), which throws instead of sending an unbound ?.
• No .ts:<line> left anywhere in the doc, every relative link and in-doc anchor resolves, biome and tsc --noEmit clean.

Two follow-ups, both filed and neither required for this PR:

1. Seven of eight NAMED_CITATIONS entries are hand-picked subsets, so a doc can add a citation nothing measures #641: nothing measures that a methods list is still the full set of names its doc cites. Your entry is the only one of the eight that is the full intersection rather than a subset, which is what made the gap visible. The "in declaration order" phrase is folded in there too, since four of the eight entries do not satisfy it today.
2. docs(providers): five docs cite getPlaceholder(), a method deleted in #304 #640: the same stale getPlaceholder() claim is still in five sibling docs. Your fix here is cited as the model, specifically for keeping the point the row carried instead of just deleting it.

Thanks for the write-up on both rounds. The intersection rule you put in the comment is the part that makes this hard to reintroduce.

---

Edited: the third bullet originally cited git log -S getPlaceholder -- src/ as returning 02578ff alone. It returns two commits, the initial one that added the method and 02578ff that removed it, since -S counts both directions. The grep above is the claim I should have made. The follow-up bullets now point at the filed issues.