ci(*): generate reference docs in autofix and fail on TypeDoc conversion errors by sukvvon · Pull Request #11522 · TanStack/query

sukvvon · 2026-09-17T01:06:28Z

🎯 Changes

Runs pnpm run generate-docs in autofix.ci, next to the existing pnpm run format, so regenerated reference docs are committed back to the PR automatically. Two supporting fixes make that safe.

Reference docs under docs/framework/*/reference are generated from source by TypeDoc, but nothing keeps them in sync: the script runs in no workflow and CONTRIBUTING.md does not mention it. Drift accumulated twice in two days:

PR	Pages regenerated	Caused by
#11520	42	#11347, #11502, #11508
#11521	28	#11512

None of the causing PRs touched JSDoc. #11512 was a four-line bug fix in utils.ts; that was enough to shift every symbol below it and break Defined in: links on 28 pages across all seven frameworks. An author fixing a bug has no signal that reference docs need regenerating, so this cannot reasonably be caught by review or a checklist item.

`generate-docs` now builds the project it references

angular-query-experimental reaches @tanstack/query-devtools through a TypeScript project reference, so it consumes that package's emitted .d.ts rather than its source — the source is solid-js JSX and cannot be compiled under Angular's tsconfig. It is the only one of the seven documented packages with a references entry; the rest resolve entirely from src.

dist-ts is gitignored, so it is absent on a fresh clone and in CI, and TypeDoc then reports TS6305 and converts nothing. Rather than adding a build step to the workflow, generate-docs now builds it itself:

"generate-docs": "tsc -b packages/query-devtools/tsconfig.json && node scripts/generate-docs.ts"

That keeps local runs and CI identical — pnpm run generate-docs works on a fresh clone with no extra step to remember.

Failing loudly instead of emptying the output

generatePackageReferenceDocs empties outputDir before conversion, then guards the rest with if (project). A failed conversion therefore left the directory empty and exited 0 — indistinguishable from "every page was intentionally deleted".

The first push on this branch demonstrated it: the run went green and autofix committed the deletion of all 203 Angular pages. The script now throws instead, so CI stops rather than committing a destructive result. The follow-up push proved the fix end to end — autofix regenerated and restored all 203 pages, and docs/ is now identical to main.

Verified locally by deleting packages/query-devtools/dist-ts: pnpm run generate-docs rebuilds it, reports no TS6305, and leaves docs/ unchanged.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Documentation
- Reference documentation is now generated automatically as part of the formatting workflow.
- Documentation generation now builds the relevant package first, helping ensure reference content reflects current code.
- Documentation generation reports a clear error when reference content cannot be produced, rather than silently completing without output.

…docs current

nx-cloud · 2026-09-17T01:06:51Z

View your CI Pipeline Execution ↗ for commit c8bcf22

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	7m 26s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1s	View ↗

☁️ Nx Cloud last updated this comment at 2026-09-17 01:36:19 UTC

coderabbitai · 2026-09-17T01:06:55Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 67366c46-e3cf-4839-99de-08103485a9b4

📥 Commits

Reviewing files that changed from the base of the PR and between 00059b8 and 85d2b69.

📒 Files selected for processing (3)

.github/workflows/autofix.yml
package.json
scripts/generate-docs.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

Walkthrough

The autofix workflow now builds packages/query-devtools and generates reference documentation before formatting fixes. Documentation generation now throws an error when TypeDoc returns no project.

Changes

Autofix documentation generation

Layer / File(s)	Summary
Add documentation generation step `.github/workflows/autofix.yml`, `package.json`	The `generate-docs` script builds `packages/query-devtools` before running the generator. The autofix workflow runs this script after setup and before formatting fixes.
Fail fast on TypeDoc conversion failure `scripts/generate-docs.ts`	`generatePackageReferenceDocs` throws an error when TypeDoc conversion returns no project. Successful conversions retain the existing output, whitespace, and redirect handling.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: tkdodo

Merge Risk: ⚪ Minimal · up to 85d2b

The documentation workflow should generate and commit only the intended reference documentation updates. No merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes both main changes: automatic reference documentation generation in autofix and failure on TypeDoc conversion errors.
Description check	✅ Passed	The description explains the motivation, implementation, verification, checklist status, and release impact. It matches the required template and provides sufficient technical detail.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (2 skipped: 2 unsupported.)

Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch ci/autofix-generate-reference-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-09-17T01:07:34Z

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

pkg-pr-new · 2026-09-17T01:10:49Z

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@11522

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@11522

@tanstack/lit-query

npm i https://pkg.pr.new/@tanstack/lit-query@11522

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@11522

@tanstack/preact-query-devtools

npm i https://pkg.pr.new/@tanstack/preact-query-devtools@11522

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@11522

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@11522

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@11522

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@11522

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@11522

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@11522

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@11522

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@11522

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@11522

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@11522

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@11522

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@11522

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@11522

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@11522

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@11522

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@11522

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@11522

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@11522

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@11522

commit: 85d2b69

github-actions · 2026-09-17T01:11:04Z

size-limit report 📦

Path	Size
react full	11.87 KB (0%)
react minimal	8.85 KB (0%)

…eDoc conversion errors

ci(.github/workflows/autofix): run 'generate-docs' to keep reference …

c8bcf22

…docs current

sukvvon requested a review from a team as a code owner September 17, 2026 01:06

sukvvon requested a review from TkDodo September 17, 2026 01:06

sukvvon self-assigned this Sep 17, 2026

ci: apply automated fixes

b0e14df

sukvvon removed the request for review from TkDodo September 17, 2026 01:09

sukvvon marked this pull request as draft September 17, 2026 01:09

fix(scripts/generate-docs): build referenced packages and fail on Typ…

f58e80e

…eDoc conversion errors

sukvvon changed the title ~~ci(.github/workflows/autofix): run 'generate-docs' to keep reference docs current~~ ci(.github/workflows/autofix): generate reference docs and fail on TypeDoc conversion errors Sep 17, 2026

autofix-ci Bot and others added 2 commits September 17, 2026 01:20

ci: apply automated fixes

0b93311

fix(package.json): build referenced packages as part of 'generate-docs'

85d2b69

sukvvon changed the title ~~ci(.github/workflows/autofix): generate reference docs and fail on TypeDoc conversion errors~~ ci(*): generate reference docs in autofix and fail on TypeDoc conversion errors Sep 17, 2026

sukvvon marked this pull request as ready for review September 17, 2026 01:46

sukvvon requested a review from TkDodo September 17, 2026 01:49

Navigation Menu

Uh oh!

Uh oh!

ci(*): generate reference docs in autofix and fail on TypeDoc conversion errors - #11522

ci(*): generate reference docs in autofix and fail on TypeDoc conversion errors#11522
sukvvon wants to merge 5 commits into
mainfrom
ci/autofix-generate-reference-docs

sukvvon commented Sep 17, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

nx-cloud Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 17, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Sep 17, 2026

Uh oh!

pkg-pr-new Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

sukvvon commented Sep 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

generate-docs now builds the project it references

Failing loudly instead of emptying the output

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

nx-cloud Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Sep 17, 2026

🚀 Changeset Version Preview

Uh oh!

pkg-pr-new Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 17, 2026

size-limit report 📦

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sukvvon commented Sep 17, 2026 •

edited by coderabbitai Bot

Loading

`generate-docs` now builds the project it references

nx-cloud Bot commented Sep 17, 2026 •

edited

Loading

coderabbitai Bot commented Sep 17, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 17, 2026 •

edited

Loading