Test docs index-file fallback

[Mohith26]

What changed

main already shipped the runtime fix in 1e23c84b: loadDocs retries a missing <path>.md as <path>/index.md.

After resolving the conflict, this PR now keeps that implementation and adds focused regression coverage for:

• canonical root and framework reference paths loading their index files
• ordinary docs loading with one request and no fallback
• non-404 fallback failures propagating

The only production-code addition is a typed optional fetch function so the loader can be tested without changing its default runtime behavior.

Evidence

This covers the root cause reported in TanStack/pacer#237 and tracked in #1069. The affected live root and framework reference URLs now return 200 responses.

Validation

• pnpm test
• 119 tests: 118 passed, 1 skipped
• TypeScript and type-aware lint clean

Risk

Low. Runtime path resolution remains the implementation already on main; this PR primarily pins its behavior with tests.

Summary by CodeRabbit

• Bug Fixes

  • Improved loading for index-style documentation pages (including framework-specific reference sections) by retrying with an index.md fallback when the direct document isn’t found.
  • Updated route redirect behavior to resolve redirects directly after a not-found result, without the previous extra canonicalization step.

• Tests

  • Reworked the test suite to validate the document-loading flow directly, including the requested path sequence, direct non-index loading, successful index fallback, and correct error propagation when fallback fails.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Docs loading now accepts an optional injected document fetcher and retries missing document paths with index.md. Route resolution no longer threads injected manifest or redirect fetchers, and tests focus on document loading, canonical index paths, direct files, and error propagation.

Docs loading and route resolution

Layer / File(s)	Summary
Document fetch and index fallback src/utils/docs.ts	Adds optional document-fetch injection, retries not-found document paths with index.md, and rethrows other errors.
Direct route and redirect resolution src/utils/docs.ts	Removes fetcher parameters from route resolution and uses direct manifest and redirect functions.
Document fallback tests tests/docs-route-index-fallback.test.ts	Tests canonical index loading, direct document loading, fetch order, and non-not-found error propagation.

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

Suggested reviewers: tannerlinsley

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches a real part of the change: adding coverage for docs index-file fallback.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (2)

tests/docs-route-index-fallback.test.ts (1)

29-61: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Consider a test for non-404 errors propagating instead of being swallowed.

All current tests exercise the {isNotFound: true} path. Nothing verifies that a genuine error (e.g. a network failure) from fetchDocs during the index-fallback attempt still propagates via throw error in loadDocsIndexFile/loadDocsRoute rather than being treated as "not found". A regression that widens the isDocsNotFoundError check would silently swallow real errors and this suite wouldn't catch it.

Example addition

test('non-404 errors from fetchDocs are not swallowed by the index fallback', async () => {
  const { fetchers } = createFetchers()
  const boomFetchers: LoadDocsRouteFetchers = {
    ...fetchers,
    fetchDocs: async () => {
      throw new Error('boom')
    },
  }

  await assert.rejects(() => loadRoute('reference', boomFetchers), /boom/)
})

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/docs-route-index-fallback.test.ts` around lines 29 - 61, Add a test
alongside the existing index-fallback tests that overrides
createFetchers().fetchDocs to throw a genuine Error, invokes loadRoute for the
fallback scenario, and asserts the error is rejected with its original message.
Ensure the test verifies non-404 failures propagate through
loadDocsIndexFile/loadDocsRoute rather than being treated as missing documents.

src/utils/docs.ts (1)

211-246: 🚀 Performance & Scalability | 🔵 Trivial

Index-fallback logic is correct but adds a guaranteed extra round-trip for every canonical index page.

For any resolved path backed by <path>/index.md (e.g. reference, framework/react/reference), every load now does two sequential fetchDocs calls: a guaranteed-miss on <path>.md followed by the successful <path>/index.md retry. If fetchDocs hits GitHub's API/raw content (uncached), this doubles latency and request volume for what looks like it will be a common page (Core API Reference is linked from nav). Worth confirming there's caching in front of fetchDocs, or consider whether the manifest could flag index-backed paths to avoid the guaranteed-miss request — though that would revisit the "no manifest changes" constraint called out in the PR objective.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/utils/docs.ts` around lines 211 - 246, Review the loadDocs and
loadDocsIndexFile flow to avoid an uncached sequential miss for canonical paths
backed by index.md. Confirm whether fetchers.fetchDocs is cached; if not, use
existing resolution information to select the index file before attempting the
.md path, without changing the manifest format or altering fallback behavior for
non-index pages.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/utils/docs.ts`:
- Around line 211-246: Review the loadDocs and loadDocsIndexFile flow to avoid
an uncached sequential miss for canonical paths backed by index.md. Confirm
whether fetchers.fetchDocs is cached; if not, use existing resolution
information to select the index file before attempting the .md path, without
changing the manifest format or altering fallback behavior for non-index pages.

In `@tests/docs-route-index-fallback.test.ts`:
- Around line 29-61: Add a test alongside the existing index-fallback tests that
overrides createFetchers().fetchDocs to throw a genuine Error, invokes loadRoute
for the fallback scenario, and asserts the error is rejected with its original
message. Ensure the test verifies non-404 failures propagate through
loadDocsIndexFile/loadDocsRoute rather than being treated as missing documents.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c2b196bd-e754-4d3b-90b5-3e7f636da262

📥 Commits

Reviewing files that changed from the base of the PR and between c406373 and 7775a40.

📒 Files selected for processing (2)

• src/utils/docs.ts
• tests/docs-route-index-fallback.test.ts

[coderabbitai]

🧹 Nitpick comments (1)

tests/docs-route-index-fallback.test.ts (1)

3-5: 🎯 Functional Correctness | 🔵 Trivial | 🏗️ Heavy lift

Retain route-level regression coverage.

These tests only exercise loadDocs, while this PR also changes loadDocsRoute and redirect resolution. Add root/framework loadDocsRoute cases proving reference indexes render, plus a section-index redirect case, so the reported routing regression is covered end-to-end.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/docs-route-index-fallback.test.ts` around lines 3 - 5, Add end-to-end
regression cases around loadDocsRoute, covering root and framework routes that
render reference indexes and a section-index route that resolves to the expected
redirect. Keep the existing loadDocs coverage, and exercise route handling and
redirect resolution rather than testing only the lower-level loader.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/docs-route-index-fallback.test.ts`:
- Around line 3-5: Add end-to-end regression cases around loadDocsRoute,
covering root and framework routes that render reference indexes and a
section-index route that resolves to the expected redirect. Keep the existing
loadDocs coverage, and exercise route handling and redirect resolution rather
than testing only the lower-level loader.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a0a67178-8154-41d6-918d-09f5afc8947d

📥 Commits

Reviewing files that changed from the base of the PR and between 7775a40 and f4a82ca.

📒 Files selected for processing (2)

• src/utils/docs.ts
• tests/docs-route-index-fallback.test.ts

[tannerlinsley]

Thanks for the work on this. The runtime fix has already shipped on main, and we’ve reverified that the affected Form and Pacer reference routes are returning 200. Since the remaining value here is regression coverage rather than an unshipped fix, we’re going to close this PR and keep the review queue focused. Appreciate the contribution.