[Karibhou]

📌 Fixes

Fixes #400

📝 Summary of Changes

• Parse nav categories and nested folders structurally so the link checker accepts only sidebar routes emitted by the page map.
• Drop invented bare, cross-section, and cross-project nav aliases; cover valid nested ADR URLs and invalid aliases in tests.
• Remove the stale v4 Hive intro and redirect its old URL to the synced introduction.

Checklist

• Reviewed the contribution guidelines and changes.
• Added regression tests and a changelog fragment.
• Ran local validation: 1,157 Vitest tests with coverage, type-check, check-links (271 links), ESLint, Markdown lint, and Prettier check.
• CI checks are passing (pending).

Security Considerations

No security-sensitive files changed.

Reviewer Notes

The local production build was interrupted after it stopped producing output during optimization; CI will run the production build.

— hive: backend=codex

[netlify]

👷 Deploy request for hivecommons-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	d5a618e

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hivecommons-hive]

Read the new parser against src/app/docs/page-map.ts at this head rather than the diff alone. Looks correct to me.

What I verified

• scripts/check-internal-links-helpers.ts:140-227 now walks NAV_STRUCTURE_* with the TypeScript AST and emits exactly one route per leaf: category slug → nested folder slugs → leaf slug. That is the same rule buildPageMap applies at src/app/docs/page-map.ts:339-376 and :396-404 (category slug, newParentSlug for arrays, slugify'd title for project leaves). slugify (helpers.ts:23-28) is character-for-character the same regex pair page-map uses.
• General-section handling matches too: contributing|community|news leaves use the file basename and base: "docs" (helpers.ts:181-186 ↔ page-map.ts:345-350).
• docs/content/hive/overview/intro.md was not referenced by any nav block, and the netlify.toml:53-56 301 covers its old URL; the redirects consistency test was updated to pin it.
• Ran locally at d5a618e: vitest run on scripts/ + the two touched src/__tests__ files → 336/336 pass; npm run check-links → Checked 271 internal links … against 140 routes. ✅ No broken internal links. So dropping the invented cross-section/bare aliases did not surface any real link that had been relying on them.

Per #400 this is the requested change (one sidebar route per entry, nested folders accepted, aliases rejected). typescript is already a devDependency (package.json:62), so the new import adds no dependency.

One non-blocking note: isGeneral is recomputed from the file prefix per leaf, whereas page-map.ts:364-371 also promotes a folder to /docs when any child is a general file. There is no such nested general folder in any current nav, so behaviour is identical today; just worth knowing if one is ever added.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Read the new parser against the site's route builder; this looks correct to me.

Verified:

• scripts/check-internal-links-helpers.ts:146-230 (new parseNavStructures) walks NAV_STRUCTURE_* with the TS AST and emits one route per leaf: category slug + nested folder slugs + leaf slug, with general-section leaves (contributing/|community/|news/) using the file basename and base docs. That is exactly what buildPageMap does at src/app/docs/page-map.ts:339-350 (leaf slug/base), :353-355 (folder slug chaining) and :394-396 (category slug). slugify (helpers.ts:22-27) matches the inline regex in page-map.
• navEntryRoute (helpers.ts:239-241) now always includes sectionSlug, so the bare and cross-section aliases #400 describes are gone; the nested ADR route is produced.
• check-internal-links.ts:83 drops the kubestellar alt lookup — nothing in PROJECT_FOR_NAV needs it, and for GENERAL entries base.replace(/^docs\/?/, "") resolves to docs/content/<section>/... as before.
• docs/content/hive/overview/intro.md is not referenced by NAV_STRUCTURE_HIVE or by scripts/sync-hive-docs.ts, so the sync will not recreate it; the 301 in netlify.toml:53-56 covers the old URL.
• Ran on head d5a618e: the four touched Vitest files (113 tests) pass and npm run check-links reports 271 links / 140 routes, no breaks.

One low-priority style note (not blocking): src/__tests__/netlify-redirects.consistency.test.ts:97-99 hard-codes /docs/hive/overview/intro as an exception in the "no redirect for a project that no longer exists" test. The next page-level redirect will need another literal. Restricting that check to project-root sources (e.g. from with no segment after /docs/<project>) would keep the intent without a per-page allowlist. Fine to leave for a follow-up.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Reviewed — no findings from this perspective.

— hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Reviewed — no findings from this perspective.

— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Hive filed review findings that do not block this PR as backlog items:

• Review backlog (correctness): intro.md removal is outside the #400 contract #402 — Review backlog (correctness): intro.md removal is outside the [scanner] check-internal-links accepts cross-section/bare nav routes that 404 (and rejects real nested sidebar URLs) #400 contract (Review backlog (correctness): intro.md removal is outside the #400 contract #402)

Cap: 10 backlog item(s) per PR per day.

[hivecommons-hive]

Intent alignment (vs #400) — the checker change satisfies the issue's "Expected": parseNavStructures now walks each category/folder structurally and emits one route per leaf (scripts/check-internal-links-helpers.ts:150-196), navEntryRoute is /${base}/${sectionSlug}/${slug} with no bare form (:240), and scripts/check-internal-links.main.test.ts:271-292 locks in the two example URLs the issue names. General-section handling mirrors page-map.ts:345-351.

Unrelated scope (advisory, non-blocking): deleting docs/content/hive/overview/intro.md, the new 301 in netlify.toml:53-56, and the hard-coded exception in src/__tests__/netlify-redirects.consistency.test.ts:98 are not part of #400 (the issue does not mention intro.md, and nothing in the repo links to it). It is a harmless orphan cleanup, but it belongs in its own PR/changelog line rather than riding on a link-checker fix — and the test exception special-cases one path in a test whose purpose is "project that no longer exists".

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Evidence bundle `#401d5a618e` sha256:3234db9840c02fa15fc2fa1ab429e69d517aabea34647a6253c26c6f95e11352 — download from the dashboard or `hivectl review evidence #401`.