[ajitpratap0]

Summary

Doc follow-ups deferred from the v1.16.0 release audit. Docs and comments only: no version bumps, no post-tag items, no CHANGELOG.md edits.

• Website docs nav (website/src/lib/constants.ts): new pages for

  • Syntax Highlighting (/docs/guides/syntax-highlighting/, HIGHLIGHTING.md)
  • ChatGPT App (/docs/integrations/chatgpt/, CHATGPT_APP.md)
  • Upgrading GoSQLX (/docs/migration/upgrading/, MIGRATION.md)
  • highlight package (/docs/reference/api/highlight/)

  docs/README.md now links to them, and to MCP_GUIDE.md, which was missing from the index.

• check-docs-content.mjs: MIGRATION.md is exempt from the "per-release heading label" rule only, because the guide is organised by release (## v1.13.0 → v1.14.0). Every other rule still applies to it.

• New docs/api/highlight.md: moved out of API_REFERENCE.md, which keeps a "Moved to" stub so the #highlight-package anchor still works. I checked every signature against pkg/highlight and pkg/gosqlx/highlight.go, and compiled the examples.

• docs/api/linter.md: documents (*Linter).SetDialect and gosqlx.LintWithDialect. The examples were compiled and run. The Linter struct is now shown with unexported fields only.

• docs/api/lsp.md:

  • The semantic tokens section has the legend and a category → token type table, taken from semanticTokenSpecs and the legend unit test.
  • New SQL Dialect section covering initializationOptions.dialect and workspace/didChangeConfiguration (settings.gosqlx.dialect). It explains how missing and invalid values are handled, the diagnostics re-publish and workspace/semanticTokens/refresh.

• cmd/gosqlx/cmd/doc.go: adds highlight (alias hl) to the command list, the file tree and the command reference. Adds --dialect notes (11 names; unknown names are rejected) and the lint SetDialect wiring. I kept these edits away from the Version = line that docs(release): prepare v1.16.0 #845 changes.

• pkg/models/location.go (comment only): the example now says "byte column" instead of "20th character". The LSP conversion now re-measures in UTF-16, replacing Column - 1, which is only correct for ASCII-only lines (fix(tokenizer): one column per tab and token Start after trivia (#797) #826/fix(linter): report L006 column as a byte offset; tighten comment span test #840).

• docs/MCP_GUIDE.md:

  • Rate Limits now says the limits come from the gosqlx-mcp binary's NewRateLimitMiddleware, not from Server.Start or Server.Handler.
  • The Embedding section has a warning and a compiled example that wraps Handler in NewRateLimitMiddleware.
  • lint_sql is described as running only the ten style rules L001–L010, with L005 capped at 100 characters, and not L011–L030.

• README.md / docs/README.md: 8 dialects have dedicated grammar support. The 11 accepted names add generic, bigquery and redshift, the last two with keyword recognition and basic parsing only. This matches DIALECT_NAMES (8), keywords.DialectNames() (11) and the BigQuery/Redshift rows docs(release): prepare v1.16.0 #845 adds to SQL_COMPATIBILITY.md. The README headline still says "8 dialects", consistent with metrics.ts, llms.txt and CLAUDE.md.

• Backfills: MIGRATION.md gets a v1.14.0 → v1.15.0 section and vscode-extension/CHANGELOG.md gets [1.15.0].

  • Both were missing. All facts come from CHANGELOG [1.15.0] and the v1.15.0 tag. I checked the API names with git grep at the tag.
  • At the tag, the Version constants in pkg/gosqlx and the CLI still read 1.14.0, and the integrations required v1.14.0.

Decisions made (conservative)

• I left llms.txt and CLAUDE.md alone. They already say "8 dialects", which is accurate. docs(release): prepare v1.16.0 #845 edits lines next to theirs.
• The VS Code [1.15.0] entry is dated 2026-07-30, the library release date, as earlier entries are. The Marketplace build for v1.15.0 was published later, through a manual vscode-publish dispatch.
• The Python row is left out of the v1.15.0 companion table. Its version at the tag (__version__ = "0.1.0") disagrees with the v1.14.0 table (0.2.0), so it could not be verified.

Merge note for #845

git merge-tree against docs/v1.16.0-release shows two expected textual conflicts. Both PRs insert a section at the top of docs/MIGRATION.md and of vscode-extension/CHANGELOG.md. To resolve, keep both sections, with v1.16.0 above v1.15.0. No other file conflicts.

Test Plan

• cd website && npm ci && npm run lint: 0 errors. The 7 warnings were already there.
• npm run build: the four new docs pages prerender.
• npm run check:docs, check:docs-links (54 files), check:anchors, check:metrics, check:seo (97 pages), check:contrast, check:rendered, check:layout and npm test (34 passing).
• Throwaway programs compiling the highlight, SetDialect/LintWithDialect and MCP embedding examples.
• gofmt, go vet, golangci-lint (0 issues) and go test -race on ./pkg/models/... and ./cmd/gosqlx/cmd/....

Breaking Changes

None. Docs, comments and a docs-check exemption only.

Release note

### Documentation
- New docs pages on gosqlx.dev: Syntax Highlighting, ChatGPT App, Upgrading GoSQLX (migration guide) and a `highlight` package API reference.
- `docs/api/lsp.md` documents semantic tokens and switching the dialect at runtime through `workspace/didChangeConfiguration`. `docs/api/linter.md` documents `Linter.SetDialect` and `gosqlx.LintWithDialect`.
- `MCP_GUIDE.md` now states that `Server.Start`/`Server.Handler` apply no rate limiting unless you wrap the handler in `NewRateLimitMiddleware`, and that `lint_sql` runs only the style rules L001–L010.
- The migration guide and the VS Code extension changelog gain the missing v1.15.0 sections.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RkzVu3JY9Y6BRWfjesWts9

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
gosqlx-website	Ignored	Preview	Oct 21, 2026 6:27pm UTC

[github-actions]

Claude finished @ajitpratap0's task in 20s —— View job

---

Review of PR #848 (docs follow-ups)

I read the non-docs diffs and the docs changes to README.md, docs/README.md and MCP_GUIDE.md. I did not re-run the website checks or compile the examples. I also did not read docs/api/highlight.md, docs/api/linter.md, docs/api/lsp.md, MIGRATION.md or the VS Code changelog line by line. The PR body says you verified those with compiled examples and the website checks.

Verdict: looks good. I found no blocking issues.

What I checked

• check-docs-content.mjs: the new skip hook matches how the other rules use skip(file, line). join is already imported. join('docs','MIGRATION.md') gives the right separator on each OS. The skip applies only to the per-release heading rule, as described.
• constants.ts: the four new entries use the same shape as their neighbours. Slugs and files match the PR description. The Migration category summary is updated to fit the new page.
• MCP_GUIDE.md: the rate-limit wording is clearer now. The embedding example gives NewRateLimitMiddleware the same cfg that the Handler was built from.
• location.go (comment only): the byte-column wording is accurate. In the LSP snippet, lineText[:location.Column-1] assumes Column is at most len(lineText)+1, and the comment doesn't say so. Real code needs a bounds check. That's fine for an illustration.
• doc.go: the edits stay clear of the Version = line that docs(release): prepare v1.16.0 #845 changes, as you intended.

Minor suggestions (non-blocking)

1. pkg/models/location.go: add a short "clamp Column-1 to len(lineText)" remark, or a bounds check in the snippet, so readers don't copy a possible panic.
2. README.md Multi-dialect bullet: it is now long. Consider moving the "11 accepted names" detail to the compatibility page and keeping the README to one sentence. This is a style choice.
3. docs/README.md still has an older "Multi-Dialect" bullet further down that now lists 8 dialects. The first bullet names generic, bigquery and redshift and the later one doesn't. That is acceptable, but the two are inconsistent.
4. The README headline says "8 dialects" and the flag accepts 11 names. The PR explains why, so I'd keep the new sentence prominent.
5. Merge note: the expected MIGRATION.md and vscode-extension/CHANGELOG.md conflicts with docs(release): prepare v1.16.0 #845 are easy to resolve. Merge docs(release): prepare v1.16.0 #845 first, or rebase this PR afterwards and keep both sections with v1.16.0 above v1.15.0.

Performance, security and tests

• No runtime code changes. Performance is unaffected.
• No security concerns. The docs now state that embedded MCP servers have no rate limiting by default. That is a useful warning.
• No test changes. The docs checks and compiled examples in your test plan cover the PR.

[github-actions]

Claude finished @ajitpratap0's task in 15s —— View job

---

Review of PR #848 (docs follow-ups)

I re-read the non-docs diffs after the latest push: doc.go, location.go, check-docs-content.mjs and constants.ts. I did not re-run the website checks or compile the examples. I also did not read the large docs pages line by line (highlight.md, linter.md, lsp.md, MIGRATION.md, the VS Code changelog). The PR body says you verified those.

Verdict: no blocking issues.

What I checked

• constants.ts: the four new entries follow the existing shape. Slugs and files match the PR description. The Migration summary now covers the upgrade page.
• check-docs-content.mjs: the skip applies only to the per-release heading rule. It uses join('docs','MIGRATION.md'), so it is portable across OSes. The template literal ${join(...)} is redundant. You can pass join(...) directly.
• doc.go: the highlight / hl entries and the --dialect notes are consistent with each other. The edits stay clear of the Version = line that docs(release): prepare v1.16.0 #845 changes.
• location.go (comment only): the byte-column wording is accurate.

Minor suggestions (non-blocking)

1. pkg/models/location.go: lineText[:location.Column-1] will panic if Column-1 > len(lineText). The snippet doesn't say so. Add a note to clamp, or a one-line bounds check, so readers don't copy a possible panic.
2. check-docs-content.mjs: simplify to skip: (file) => file.endsWith(join('docs', 'MIGRATION.md')).
3. docs/README.md and README.md: the multi-dialect wording is now long and inconsistent between the two places. One bullet names the 11 accepted names and an older bullet lists only 8. Consider keeping one sentence in the READMEs and moving the "11 accepted names" detail to SQL_COMPATIBILITY.md.
4. Merge order: the conflicts with docs(release): prepare v1.16.0 #845 in MIGRATION.md and vscode-extension/CHANGELOG.md are easy to resolve. Keep both sections, with v1.16.0 above v1.15.0.

Performance, security and tests

• There are no runtime changes, so performance is unaffected.
• There are no security concerns. The new MCP warning that embedded servers have no rate limiting by default is useful.
• No test changes are needed. The website checks and compiled examples in your test plan cover the PR.