refactor(docs): derive SECTION_ORDER and add build-time assertion

[jonathanperis]

Summary

• Derive SECTION_ORDER from SECTION_CATEGORIES.flatMap(({ ids }) => ids) — eliminates duplicate hardcoded array
• Add build-time assertion validating all category IDs exist as wiki/*.md files
• Replace hardcoded ORDER with pagesBySlug lookup pattern (was direct wikiPages file lookup)
• Update sectionsToRender to use {slug, page} tuple pattern
• Fix search clear to reset item.style.display and parent display
• Replace hardcoded order array in getStaticPaths() with SECTION_ORDER

Changes

• docs/src/pages/docs/[...slug].astro: Derive order, add assertion, fix content rendering + search

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed search filter to properly restore navigation visibility when clearing the search query.

• Chores

  • Enhanced documentation system reliability with build-time validation to ensure all documentation categories have corresponding content pages.

[coderabbitai]

📝 Walkthrough

Walkthrough

Refactored docs/src/pages/docs/[...slug].astro to derive page ordering and slug mappings from SECTION_CATEGORIES configuration and glob-discovered wiki/*.md files, with build-time validation. Enhanced search filtering to reset nav visibility when query is cleared.

Changes

Documentation Page Structure Refactoring

Layer / File(s)	Summary
Data Structure Derivation docs/src/pages/docs/[...slug].astro	Compute SECTION_ORDER from SECTION_CATEGORIES.ids array, replacing hardcoded ORDER.
Build-time Setup & Validation docs/src/pages/docs/[...slug].astro	Import wikiPages via glob, build pagesBySlug map, and assert that each SECTION_CATEGORIES id has a corresponding wiki/<id>.md file; throw error if missing.
Page Resolution docs/src/pages/docs/[...slug].astro	Refactor sectionsToRender to use pagesBySlug and SECTION_ORDER instead of reconstructing wiki paths; resolve requested page from the discovered map.
Static Path Generation docs/src/pages/docs/[...slug].astro	Update getStaticPaths() to generate route params from SECTION_ORDER (excluding 'home').
Content Rendering docs/src/pages/docs/[...slug].astro	Change main content loop to iterate over { slug, page } pairs from sectionsToRender, using the discovered wikiPage directly rather than dynamic path construction.
Search Filter Enhancement docs/src/pages/docs/[...slug].astro	Add logic to fully reset nav and category visibility when search query is cleared (if (!q)), restoring previously hidden items.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• docs: migrate wiki content to wiki/ folder #48 — Migrates and adds wiki/*.md files that this PR depends on via glob discovery and build-time validation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main refactoring changes: deriving SECTION_ORDER from SECTION_CATEGORIES and adding a build-time assertion to validate category IDs.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-derive-section-order-and-assert

---

_{Review rate limit: 3/10 reviews remaining, refill in 37 minutes and 2 seconds.}

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

[coderabbitai]

🧹 Nitpick comments (1)

docs/src/pages/docs/[...slug].astro (1)

11-41: ⚡ Quick win

Add a duplicate-ID assertion for SECTION_CATEGORIES

You already validate existence; add a uniqueness check too. Duplicate ids can produce duplicate <section id> values and duplicate entries in getStaticPaths().

Suggested patch

 const SECTION_ORDER = SECTION_CATEGORIES.flatMap(({ ids }) => ids);
+
+const duplicateIds = SECTION_ORDER.filter((id, index) => SECTION_ORDER.indexOf(id) !== index);
+if (duplicateIds.length > 0) {
+  throw new Error(
+    `SECTION_CATEGORIES contains duplicate ids: ${Array.from(new Set(duplicateIds)).join(', ')}`
+  );
+}
 
 // Build-time assertion: validate SECTION_CATEGORIES IDs against discovered slugs
 const availableSlugs = new Set(Object.keys(pagesBySlug));

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/src/pages/docs/`[...slug].astro around lines 11 - 41, Add a uniqueness
assertion for SECTION_CATEGORIES by scanning all cat.ids and detecting
duplicates before building SECTION_ORDER; e.g., iterate SECTION_CATEGORIES and
count occurrences of each id (or track a Set) and if any id appears more than
once throw an Error listing the duplicate ids and their categories for clarity.
Ensure you reference SECTION_CATEGORIES and SECTION_ORDER (and optionally
SECTION_CATEGORIES[].ids and SECTION_CATEGORIES[].label) so the check runs at
build time alongside the existing availability check and prevents duplicate
<section id> and static path entries.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/src/pages/docs/`[...slug].astro:
- Around line 11-41: Add a uniqueness assertion for SECTION_CATEGORIES by
scanning all cat.ids and detecting duplicates before building SECTION_ORDER;
e.g., iterate SECTION_CATEGORIES and count occurrences of each id (or track a
Set) and if any id appears more than once throw an Error listing the duplicate
ids and their categories for clarity. Ensure you reference SECTION_CATEGORIES
and SECTION_ORDER (and optionally SECTION_CATEGORIES[].ids and
SECTION_CATEGORIES[].label) so the check runs at build time alongside the
existing availability check and prevents duplicate <section id> and static path
entries.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6115c383-ec06-4c6a-92f6-e4ea8e57831e

📥 Commits

Reviewing files that changed from the base of the PR and between 28b0321 and 27f7645.

📒 Files selected for processing (1)

• docs/src/pages/docs/[...slug].astro

[jonathanperis]

Fix: Extracted SECTION_CATEGORIES/SECTION_ORDER to sidebar.config.ts. Astro hoists getStaticPaths — only imports survive hoisting. Frontmatter variables were invisible to getStaticPaths causing 'SECTION_ORDER is not defined' build error.