learning-website-framework1-5  Exercise 1: Find Folders Missing from the Menu
==============================================================================

The current top menu is a hand-written list (NAV_CATEGORIES and STANDALONE_SLUGS
in astro-site/src/lib/nav-groups.ts). Write a script that compares it with the
real top-level folders and reports the folders that have no menu entry and menu
entries that point at nothing.

Save as nav_gap.py:

import os, re, sys

NAV_TS, CONTENT = sys.argv[1], sys.argv[2]
text = open(NAV_TS, encoding="utf-8").read()

# every quoted slug inside subjectSlugs: [...] arrays, plus STANDALONE_SLUGS
slugs = set()
for arr in re.findall(r"subjectSlugs:\s*\[(.*?)\]", text, re.S):
    slugs.update(re.findall(r"'([^']+)'", arr))
standalone = re.search(r"STANDALONE_SLUGS\s*=\s*\[(.*?)\]", text, re.S)
slugs.update(re.findall(r"'([^']+)'", standalone.group(1)))

on_disk = sorted(d for d in os.listdir(CONTENT) if os.path.isdir(os.path.join(CONTENT, d)))
missing = [d for d in on_disk if d not in slugs]
stale = sorted(s for s in slugs if s not in on_disk)

print(f"top-level folders on disk: {len(on_disk)}")
print(f"slugs listed in the nav:   {len(slugs)}")
print(f"on disk but NOT in the top nav ({len(missing)}):")
for m in missing:
    print("  " + m)
print(f"in the nav but not on disk ({len(stale)}): {stale if stale else 'none'}")

Run it:

  python nav_gap.py "<path to>/astro-site/src/lib/nav-groups.ts" "<path to>/content"

Output (checked by running it on the real files):

top-level folders on disk: 49
slugs listed in the nav:   36
on disk but NOT in the top nav (13):
  blockchain-and-web3
  classic-literature
  cookery
  culture
  football
  ios-development
  music
  philosophy
  politics
  sci-fi-project
  science
  science-fiction
  study-methodologies
in the nav but not on disk (0): none

What it means
-------------
13 of the 49 folders are not in the top menu, including whole subject areas such
as cookery, politics, music, philosophy and science-fiction. They are NOT
unreachable: the home page lists every subject as a card, and the Course Index
lists every course. The menu is simply out of date, and nothing warns about
it, because nav-groups.ts says itself that a folder left out of the list just
does not appear in the nav.

The lesson for the new sites: a menu that is typed by hand drifts. Either derive
it from the folder tree (as the sidebar already is) or run a check like this
one in the build and fail when a folder is missing.

WHY THIS WORKS AS AN ANSWER
---------------------------
It turns a vague worry ("is the menu complete?") into a list. Because the
script reads the real files, it keeps being right as folders are added, and it
can be reused per site once the map from Learning Website: Framework &
Architecture 2 assigns folders to sites.