fix(public): resolve duplicate guide slugs by precedence, not scan order - #4011
Conversation
An application-level guide (any module other than home) now deterministically overrides a framework-provided (home) guide on a slug collision, silently. A same-tier collision (two framework or two application guides) keeps a deterministic tiebreak and warns with the actual remedy instead of "rename one" as the only option. buildDocsTree and the bySlug index are now built from the SAME deduped entry list (resolveGuideEntries), so the listing (/api/public/docs) and the fetch endpoint (/api/public/docs/:slug.md) can never disagree, and the tree never shows a duplicate nav entry. Closes #3979
…k map - precedenceTier now reuses the stack's existing framework-module set (lib/helpers/config.js CORE_MODULES) instead of a new single-module constant — same classification filterByActivation already relies on. - Drop PRECEDENCE_RANK: with only two tiers and same-tier collisions already handled earlier, the remaining branch is just "challenger is application".
|
Warning Review limit reached
Next review available in: 22 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
WalkthroughThe public docs system now applies configuration-aware guide slug precedence. Application guides override framework guides. Same-tier collisions keep the later deterministic entry with a warning. The resolved entries feed both the documentation tree and slug index. ChangesGuide slug precedence
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant DocsService as public.docs.service.compute
participant Resolver as docsTree.resolveGuideEntries
participant Tree as buildDocsTree
participant SlugIndex as bySlug
DocsService->>Resolver: Resolve loaded guide entries
Resolver-->>DocsService: Return deduplicated entries
DocsService->>Tree: Build tree from resolved entries
DocsService->>SlugIndex: Index the same resolved entries
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
|
@coderabbitai review |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4011 +/- ##
==========================================
+ Coverage 93.52% 93.54% +0.01%
==========================================
Files 170 170
Lines 5744 5759 +15
Branches 1842 1847 +5
==========================================
+ Hits 5372 5387 +15
Misses 302 302
Partials 70 70
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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.
Inline comments:
In `@modules/public/tests/public.docs.integration.tests.js`:
- Line 143: Update the fixture setup at config.files.guides so appGuidePath is
placed before the framework’s original guide sources, ensuring the test fails
under old later-entry-wins scan behavior and verifies application precedence
independently of file order.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 056fe5aa-7c99-494d-85e3-656a7335344b
📒 Files selected for processing (6)
modules/public/helpers/public.docs.tree.jsmodules/public/services/public.docs.service.jsmodules/public/tests/public.docs.integration.tests.jsmodules/public/tests/public.docs.service.fallback.unit.tests.jsmodules/public/tests/public.docs.service.unit.tests.jsmodules/public/tests/public.docs.tree.unit.tests.js
The welcome-slug fixture used an absolute OS-tmpdir path, which always sorts before the relative modules/home/... path loadGuideEntries scans — so it only proved the override when the app guide is scanned FIRST. Add a second fixture (quickstart slug) at a relative path that sorts AFTER modules/home/..., proving the override also holds when the app guide is scanned LAST — end-to-end, not just via the mocked orderings already covered in public.docs.tree.unit.tests.js. Addresses CodeRabbit review on PR #4011.
path.join(process.cwd(), ...) is always absolute, so the "opposite scan-order direction" fixture was in fact absolute too — both integration fixtures sorted before modules/home/..., meaning the app guide was the incumbent in both collisions and the explicit "challenger overrides incumbent" branch in resolveGuideEntries was never exercised at the integration level (verified by execution: a debug-spy showed zero calls, and reverting the source made both "opposite direction" assertions fail identically). Push a real relative path (path.relative(process.cwd(), ...)) into config.files.guides for the quickstart fixture instead, so it sorts AFTER modules/home/... and the framework guide is genuinely incumbent. Add a logger.debug spy proving the override branch fires only for that case, and scope the "welcome" test's assertion to its own slug (the same compute() pass also resolves the quickstart collision, so a blanket "not called" would be a false negative).
* fix(public): make docs integration tests consumer-independent The public docs integration suite still read real on-disk guide content/counts in several places (tree grouping, the raw-markdown :slug.md test, the front-matter leak check). A consumer shipping its own guide at a globally-shared slug (welcome/quickstart) now deterministically wins that slug by design (#4011), so any assertion pinned to which real guide wins is a consumer-dependence bug. Split the file's first describe block into a shape/status-only block (no fixture needed, content is irrelevant) and a controlled-fixture block that fully replaces config.files.guides with self-authored guides (the #4014 pattern), restored in afterAll. The raw-markdown test now targets a fixture guide at a unique slug and asserts its own content. The slug-collision precedence block is untouched. Verified the invariant holds by running the suite with a synthetic extra guide file injected at the welcome/quickstart slugs from a fake non-core module — identical green result with or without it. Closes #4015 * fix(public): scope the unknown-slug 404 test to the controlled fixture CodeRabbit review on #4016: the 404-for-unknown-slug test lived in the shape/status-only block and queried a hardcoded slug against whatever config.files.guides resolves to at boot. A consumer could in principle configure a guide at that exact slug, making the test consumer-dependent again. Move it into the controlled-fixture block (config.files.guides fully replaced there) and query a slug guaranteed absent from that fixture set.
1 participant
Summary
CORE_MODULESset) always overrides a framework-provided one (core/auth/users/home) on a slug collision — deterministic, regardless of scan order.buildDocsTreeand thebySlugindex are now built from the SAME deduped entry list, soGET /api/public/docs(listing) andGET /api/public/docs/:slug.md(fetch) can never disagree, and the tree never shows a duplicate nav entry. A same-tier collision (two framework or two application guides) keeps the existing deterministic tiebreak and logs a warning naming the actual remedy, instead of "rename one" as the only option.compute()warns and keeps the last-scanned guide, butbuildDocsTreekeeps BOTH entries — the listing shows a duplicate while the fetch endpoint can return a different guide than what's listed. Worse, a consumer colliding with a framework-shipped sample guide (e.g. its own00-welcome) has no actionable remedy: renaming a framework file isn't possible, and the only escape (config.docs.excludeModules) isn't discoverable without readingconfig/index.js.Scope
modules/public(docs service + tree helper)none(reuses the existinglib/helpers/config.jsCORE_MODULESexport, does not modify it)lowValidation
npm run lintnpm test(unit: 2316/2316 passing; integration: 597/597 passing, incl. new collision-precedence cases)Guardrails check
.env*,secrets/**, keys, tokens)Notes for reviewers
modules/publiconly, no shared/config file touched.Summary by CodeRabbit