Skip to content

docs(mysql): replace 13 stale line-number citations with named citations - #582

Merged
cevheri merged 2 commits into
libredb:mainfrom
dchaudhari7177:docs/mysql-named-citations
Sep 6, 2026
Merged

docs(mysql): replace 13 stale line-number citations with named citations#582
cevheri merged 2 commits into
libredb:mainfrom
dchaudhari7177:docs/mysql-named-citations

Conversation

@dchaudhari7177

Copy link
Copy Markdown
Contributor

Closes #564. Follows #563 as the model.

All 13 citations re-anchored, no .ts:N left in the file:

$ grep -cE '\.ts:[0-9]+' docs/providers/mysql.md
0

The three that cite an expression, not a method — the ones the issue calls out — resolved to the enclosing declaration:

citation landed on now names
mysql.ts:114 "the pool config" (cited twice) docblock of an unrelated row interface buildPoolConfig()
mysql.ts:41 transaction rollback timer a comment the TX_TIMEOUT_MS constant
mysql.ts:346 "one monitoring field" a comment slowQueriesEmptyState, returned by getLabels()

The factory citation names createDatabaseProvider(), matching mssql.md.

Every name was checked against the source before writing it, not just against the issue text — including that each matches the visibility-prefixed form declarationLine() looks for, since a name that exists but is declared differently would pass review and fail the guard. All eleven do.

mysql.md added to NAMED_CITATIONS with getCapabilities, getLabels, validate, buildPoolConfig, buildSSLConfig, query, cancelQuery, beginTransaction, getSchema, runMaintenance, getAllTablesForMaintenance. I left out getPoolStats and prepareQuery — the doc mentions both, but neither is declared in mysql.ts (they come from SQLBaseProvider), so listing them would make the guard assert something false.

Verification:

  • bun test tests/unit/provider-docs-monitoring-citations.test.ts16 pass on main, 18 pass here, the two new ones being the mysql.md entry. Zero fail.
  • bun test tests/integration/db/mysql-provider.test.ts — 115 pass, 0 fail.
  • Mutation-checked: putting mysql.ts:142 back on the buildSSLConfig() line fails the guard, so the file is genuinely covered now rather than merely listed.

Docs plus one test-list change; no product code touched.

@cevheri

cevheri commented Sep 6, 2026

Copy link
Copy Markdown
Member

Thanks, the substance checks out. I verified every name against mysql.ts myself:
all eleven are declared in the visibility-prefixed form the guard looks for, the file has no .ts:N left, and leaving out getPoolStats and prepareQuery was the right call since neither is declared there. Both mutations bite: restoring mysql.ts:142 fails the guard, and renaming buildPoolConfig in the source fails it too. 20 pass on my tree.

Two things:

  1. The red check is not yours. Lint, Typecheck and Build fails on its first step,the chart version sync guard, because your branch predates the 0.14.0 release and CI fetches main at depth 1, so it compares your Chart.yaml against main's tip.
    Chart 0.1.58 already has a released tag. Merge origin/main into your branch and it clears. I tried it: the guard then prints OK for 0.1.59 / 0.14.0, and the merge is clean. Worth doing anyway, because that step failing means eleven later gates never ran at all: format, lint, typecheck, knip, build, build:lib, attw and the Go launcher tests are unmeasured rather than green.

  2. One line below a sentence you rewrote, mysql.md still quotes the old slowQueriesEmptyState string, "enable the Performance Schema to see them".
    fix(agent): the agent's foreign-key read was empty for the role we prescribe, plus seven more #463 changed it to "An empty list means it recorded nothing - the Performance Schema is off, or nothing has run against this database yet", and getLabels()'s docblock explains why.
    Not something you introduced, and not what docs/providers/mysql.md: replace 13 stale line-number citations with named citations #564 asked for, so take it or leave it. But it is the same kind of stale citation this PR is fixing, and nothing in the guard catches a quoted value.

Same defect and same fix as libredb#542 (oracle.md, merged in libredb#563) applied to
docs/providers/mysql.md: 12 citations into mysql.ts and 1 into factory.ts, all
rotted.

Each is re-anchored to the named declaration it describes and the line number
dropped, so the citation cannot go stale on an edit above it. Where the prose
cited an expression rather than a method, the enclosing method or the constant
is named instead:

- 'the pool config' (mysql.ts:114, now inside an unrelated row interface) ->
  buildPoolConfig()
- the transaction rollback timer (mysql.ts:41, a comment) -> the TX_TIMEOUT_MS
  constant
- 'one monitoring field' (mysql.ts:346, a comment) -> slowQueriesEmptyState,
  returned by getLabels()
- the factory citation -> createDatabaseProvider(), as mssql.md does

Every named declaration was confirmed to exist in the source and to match the
visibility-prefixed form the guard's declarationLine() looks for.

mysql.md is added to NAMED_CITATIONS with its eleven methods, so the file is
now guarded against both a reintroduced line number and a renamed method.

Closes libredb#564
@dchaudhari7177
dchaudhari7177 force-pushed the docs/mysql-named-citations branch from 76379ab to bc0d8ec Compare September 6, 2026 14:17
@dchaudhari7177

Copy link
Copy Markdown
Contributor Author

Rebased onto main. The red check was chart:checkcharts/libredb-studio/Chart.yaml still carried 0.1.58, which has since been tagged, so the gate correctly refused it. That's branch age rather than anything in this diff; the rebase picks up 0.1.59 and the docs change itself conflicts with nothing.

Re-verified on the rebased head: provider-docs-monitoring-citations is 20 passed / 179 assertions, and biome format is clean across the tree. The diff is still just the 13 citations in docs/providers/mysql.md plus the test that keeps them honest.

Section 8 of this doc says the sentence had to stop naming a cause. Section
10 went on quoting the version that named it: "enable the Performance
Schema to see them", the wording libredb#463 (e8b0056) replaced. One file
asserted both that the label had changed and that it had not.

Pinned rather than hand-corrected, because a quoted value rots the way a
line number does and the named citations this branch introduced do not
reach it. The guard reads the string literal out of getLabels() and looks
for it in the doc with whitespace collapsed on both sides, so wrapped prose
still matches. It asserts presence only, never absence of the old wording,
because section 8 quotes that deliberately in the past tense.

Both directions measured: editing the label in mysql.ts fails the guard,
and restoring the pre-libredb#463 quotation in the doc fails it too.
@cevheri

cevheri commented Sep 6, 2026

Copy link
Copy Markdown
Member

Merging this once the checks come back. I took the optional item myself rather than hold the PR for it, and pushed it onto your branch as 9b3d0e99 so you can see exactly what changed.

docs/providers/mysql.md §10 still quoted slowQueriesEmptyState as "enable the Performance Schema to see them", the wording #463 replaced, while §8 of the same file explains in the past tense that the sentence had to stop naming a cause. The file asserted both that the label had changed and that it had not.

I pinned the value rather than hand-correcting it, because a quoted value rots the way a line number does and the named citations you added do not reach it. The guard reads the string literal out of getLabels() and looks for it in the doc with whitespace collapsed on both sides, so wrapped prose still matches. It asserts presence only, never absence of the old wording, because §8 quotes that deliberately.

Both directions measured: editing the label in mysql.ts fails the guard, and restoring the pre-#463 quotation in the doc fails it too. 21 pass on that file, and format, lint, typecheck, knip and the four drift guards are clean.

Your part is untouched. The 13 named citations and the test that keeps them honest are as you wrote them, and the rebase was the right call: chart 0.1.59 / appVersion 0.14.0 now match package.json, so the eleven gates that never ran on the old head have run. Thanks for diagnosing that check yourself instead of guessing at it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs/providers/mysql.md: replace 13 stale line-number citations with named citations

2 participants