feat(guides): add sections option for grouped Redoc sidebar layout#3771
Conversation
Promote-up from trawl_node: mergeGuidesIntoSpec gains an optional
{ sections } argument that groups guides under H1 section dividers
(each guide rendered as H2) using filename numeric prefix ranges.
Adds prefixFromPath helper (exported). Flat mode unchanged when
sections is absent (backward-compatible).
Closes #3767
…ertion Addresses DeepSeek Phase 0 medium finding: prefixFromPath is a new public export but had only indirect coverage. Adds 6 direct tests (dash separator, underscore separator, no-prefix, pure-digit, octal radix-10 correctness, empty input). Also adds orphan-position assertion (orphan appended after section markdown, per JSDoc spec).
|
Warning Review limit reached
More reviews will be available in 46 minutes and 18 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 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 |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #3771 +/- ##
===========================================
+ Coverage 59.43% 90.18% +30.74%
===========================================
Files 151 151
Lines 4970 5000 +30
Branches 1577 1588 +11
===========================================
+ Hits 2954 4509 +1555
+ Misses 1491 386 -1105
+ Partials 525 105 -420
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR extends the Redoc guide-merging helper to support an optional “sectioned” sidebar layout by grouping guides under H1 section dividers (with each guide as an H2) based on numeric filename prefixes, while keeping the existing flat (backward-compatible) behavior unchanged when sections is not provided.
Changes:
- Add
prefixFromPath(filePath)(exported) to extract a numeric ordering prefix from guide filenames. - Extend
mergeGuidesIntoSpec(spec, guides, options?)to support{ sections }grouping with orphan guides appended at the end. - Add unit tests covering flat mode compatibility, section grouping behavior, orphan handling, and
prefixFromPathedge cases.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| lib/helpers/guides.js | Adds prefixFromPath and sectioned grouping logic to mergeGuidesIntoSpec while preserving flat mode behavior. |
| lib/helpers/tests/guides.sections.unit.tests.js | Introduces unit coverage for the new { sections } mode and prefixFromPath parsing behavior. |
Address Copilot review threads:
- options null-safety: `(options != null ? options : {})` prevents
TypeError when null is passed explicitly as third arg
- JSDoc: `path?` optional in guides entries (only needed for sections mode)
- JSDoc: @returns reflects actual passthrough of falsy/non-object spec
- Test: null options falls back to flat mode without throwing
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Summary
Promote-up from trawl_node (production-validated):
mergeGuidesIntoSpecgains an optional{ sections }option for grouped Redoc sidebar layout.prefixFromPath(filePath)helper (exported) — extracts the numeric ordering prefix from a guide filename (e.g.07-scheduling.md→ 7, underscore or dash separator, radix-10 safe)mergeGuidesIntoSpec(spec, guides, options?)with a{ sections }third argument — array of{ title, prefixMin, prefixMax }objects that group guides under H1 section dividers with each guide rendered as H2sectionspassed) — fully backward-compatible; existing callers are unaffectedWhy generic
Every devkit downstream with a structured doc tree (18+ guides) gets Redoc sidebar grouping for free. When
sectionsis not passed, behavior is byte-identical to the current devkit.Test coverage
15 unit tests in
lib/helpers/tests/guides.sections.unit.tests.js:prefixFromPathdirect: dash separator, underscore separator, no-prefix, pure-digit, octal-safe (radix 10 on08-/09-), empty input (6 tests)References
2026-06-01-trawl-promote-up-followups.mdTask 2Test plan
NODE_ENV=test npm run test:unit -- guides.sections)prefixFromPathcoverage in the follow-up commit)1127e36f54ed47ef43a2f3f04d84b2cebba48dfc