Information Architecture skill for Claude Code

#!/usr/bin/env python3
"""Audit a sitemap / navigation outline for structural IA problems.

Usage:
    python3 scripts/sitemap_audit.py sitemap.md [--max-depth 3] [--max-top 7] [--strict]

Input: an indented outline, one label per line. Markdown bullets ("- ", "* ", "1. ")
and plain indentation (2 or 4 spaces, or tabs) both work. An optional URL may follow
the label after " | " or " -> ", e.g. "  - Invoices | /billing/invoices".
Lines starting with "#" are treated as comments.

Reports depth, breadth, single-child parents, duplicate and vague labels, long labels,
inconsistent sibling casing, and URL paths that disagree with the hierarchy.
Exits 1 on errors (or on warnings too with --strict). Standard library only.
"""
from __future__ import annotations

import argparse
import re
import sys
from collections import defaultdict
from dataclasses import dataclass, field

VAGUE = {
    "more", "misc", "miscellaneous", "other", "others", "general", "resources", "solutions",
    "stuff", "info", "information", "tools", "explore", "discover", "hub", "center", "centre",
    "overview", "home page", "learn", "things", "items", "content", "extras", "advanced",
}
BULLET_RE = re.compile(r"^(\s*)(?:[-*+]\s+|\d+[.)]\s+)?(.*)$")


@dataclass
class Node:
    label: str
    url: str | None
    depth: int
    line: int
    parent: "Node | None" = None
    children: list["Node"] = field(default_factory=list)

    def path(self) -> str:
        parts, n = [], self
        while n is not None:
            parts.append(n.label)
            n = n.parent
        return " > ".join(reversed(parts))


def parse(text: str) -> list[Node]:
    roots: list[Node] = []
    stack: list[tuple[int, Node]] = []
    for lineno, raw in enumerate(text.splitlines(), 1):
        if not raw.strip() or raw.lstrip().startswith("#"):
            continue
        expanded = raw.replace("\t", "    ")
        m = BULLET_RE.match(expanded)
        indent, body = len(m.group(1)), m.group(2).strip()
        url = None
        for sep in (" | ", " -> "):
            if sep in body:
                body, url = (s.strip() for s in body.split(sep, 1))
                break
        while stack and stack[-1][0] >= indent:
            stack.pop()
        parent = stack[-1][1] if stack else None
        node = Node(body, url, (parent.depth + 1) if parent else 1, lineno, parent)
        (parent.children if parent else roots).append(node)
        stack.append((indent, node))
    return roots


def walk(nodes: list[Node]):
    for n in nodes:
        yield n
        yield from walk(n.children)


def case_style(label: str) -> str:
    words = [w for w in re.findall(r"[A-Za-z][A-Za-z']*", label)]
    if len(words) < 2:
        return "single"
    caps = sum(1 for w in words[1:] if w[0].isupper() and w.lower() not in {"and", "of", "the", "for", "to", "in", "a"})
    if caps == 0:
        return "sentence"
    if caps == len([w for w in words[1:] if w.lower() not in {"and", "of", "the", "for", "to", "in", "a"}]):
        return "title"
    return "mixed"


def audit(roots: list[Node], max_depth: int, max_top: int) -> list[tuple[str, int, str]]:
    out: list[tuple[str, int, str]] = []
    nodes = list(walk(roots))
    if len(roots) > max_top + 2:
        out.append(("ERROR", 0, f"{len(roots)} top-level items; keep primary navigation to about {max_top} or fewer"))
    elif len(roots) > max_top:
        out.append(("WARN", 0, f"{len(roots)} top-level items; above the {max_top}-item target for primary navigation"))

    by_label: dict[str, list[Node]] = defaultdict(list)
    for n in nodes:
        by_label[n.label.strip().lower()].append(n)
        if n.depth > max_depth + 1:
            out.append(("ERROR", n.line, f"depth {n.depth}: '{n.path()}' is buried; flatten or add a cross-link/hub"))
        elif n.depth > max_depth:
            out.append(("WARN", n.line, f"depth {n.depth}: '{n.path()}' is below the {max_depth}-level target"))
        if len(n.children) == 1:
            out.append(("WARN", n.line, f"'{n.label}' has a single child '{n.children[0].label}'; merge the levels"))
        if len(n.children) > 12:
            out.append(("WARN", n.line, f"'{n.label}' has {len(n.children)} children; group them or use a filterable index"))
        if n.label.lower() in VAGUE:
            out.append(("WARN", n.line, f"vague label '{n.label}' ('{n.path()}'); name what is inside"))
        if len(n.label) > 28 or len(n.label.split()) > 4:
            out.append(("WARN", n.line, f"long label '{n.label}'; navigation labels work best at 1-3 words"))
        if n.url and n.parent and n.parent.url and not n.url.startswith("http"):
            parent_url = n.parent.url.rstrip("/")
            if parent_url and not n.url.startswith(parent_url + "/") and n.url != parent_url:
                out.append(("INFO", n.line, f"URL {n.url} is not under parent {n.parent.url}; fine if intentional, else breadcrumbs and URLs disagree"))

    for label, group in by_label.items():
        if len(group) < 2:
            continue
        parents = defaultdict(list)
        for g in group:
            parents[id(g.parent)].append(g)
        for same in parents.values():
            if len(same) > 1:
                out.append(("ERROR", same[1].line, f"duplicate sibling label '{same[0].label}' under '{same[0].parent.label if same[0].parent else '(root)'}'"))
        if len(parents) > 1 and not group[0].children:
            locs = "; ".join(g.path() for g in group[:4])
            out.append(("WARN", group[1].line, f"label '{group[0].label}' appears in {len(group)} places ({locs}); one home + cross-links, or disambiguate"))

    for parent_children in [roots] + [n.children for n in nodes if n.children]:
        styles = {case_style(c.label) for c in parent_children} - {"single"}
        if len(styles) > 1:
            names = ", ".join(c.label for c in parent_children[:6])
            out.append(("WARN", parent_children[0].line, f"mixed label casing among siblings ({names}); pick sentence or title case"))
    order = {"ERROR": 0, "WARN": 1, "INFO": 2}
    out.sort(key=lambda f: (order[f[0]], f[1]))
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("file")
    ap.add_argument("--max-depth", type=int, default=3, help="target maximum depth (default 3)")
    ap.add_argument("--max-top", type=int, default=7, help="target top-level item count (default 7)")
    ap.add_argument("--strict", action="store_true", help="exit 1 on warnings as well")
    args = ap.parse_args()
    try:
        with open(args.file, encoding="utf-8") as fh:
            roots = parse(fh.read())
    except OSError as exc:
        print(f"ERROR cannot read {args.file}: {exc}", file=sys.stderr)
        return 1
    if not roots:
        print("ERROR no outline items found")
        return 1
    nodes = list(walk(roots))
    depth_counts = defaultdict(int)
    for n in nodes:
        depth_counts[n.depth] += 1
    leaves = [n for n in nodes if not n.children]
    print(f"== {args.file}")
    print(f"  {len(nodes)} items, {len(roots)} top-level, {len(leaves)} leaves, max depth {max(depth_counts)}")
    print("  per level: " + ", ".join(f"L{d}={c}" for d, c in sorted(depth_counts.items())))
    findings = audit(roots, args.max_depth, args.max_top)
    for level, line, msg in findings:
        print(f"  {level:<5} {('L' + str(line)) if line else 'doc':<6} {msg}")
    errors = sum(f[0] == "ERROR" for f in findings)
    warns = sum(f[0] == "WARN" for f in findings)
    print(f"  -> {errors} error(s), {warns} warning(s)")
    return 1 if errors or (args.strict and warns) else 0


if __name__ == "__main__":
    sys.exit(main())