Documentation Audit skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Documentation Audit"
  short_description: "Find the wrong docs before the broken links"
  default_prompt: "$documentation-audit Audit our docs folder and tell me what is outdated or missing"

#!/usr/bin/env python3
"""Mechanical audit of a Markdown/MDX docs folder.

Finds broken relative links and anchors, pages nothing links to, pages without a
title, stale pages (by last git commit, falling back to file mtime), TODO/FIXME
markers, duplicate titles and very long pages. Standard library only; works offline.

Usage:
  python3 docs_audit.py DOCS_DIR [--stale-days 365] [--max-lines 800] [--json OUT.json]
                                 [--ignore GLOB ...]

Exit code: 0 no broken links, 1 broken links or anchors found, 2 bad input.
"""
from __future__ import annotations

import argparse
import fnmatch
import json
import os
import re
import subprocess
import sys
import time
from collections import Counter, defaultdict
from pathlib import Path

EXTS = (".md", ".mdx")
INDEX_NAMES = ("index.md", "index.mdx", "README.md", "readme.md", "_index.md")
LINK = re.compile(r"(?<!!)\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+\"[^\"]*\")?\s*\)")
IMAGE = re.compile(r"!\[[^\]]*\]\(\s*<?([^)\s>]+)>?")
REFDEF = re.compile(r"^\s*\[[^\]]+\]:\s*(\S+)", re.M)
HREF = re.compile(r"""href=["']([^"']+)["']""")
HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$", re.M)
EXPLICIT_ID = re.compile(r"\{#([\w-]+)\}\s*$")
FENCE = re.compile(r"^(```|~~~).*?^\1", re.M | re.S)
FRONTMATTER = re.compile(r"\A---\n(.*?)\n---\n", re.S)
TODO = re.compile(r"\b(TODO|FIXME|TBD|XXX)\b")


def slugify(text: str) -> str:
    text = re.sub(r"`|\*|_{2,}|\[|\]\([^)]*\)", "", text)  # strip inline markup
    text = re.sub(r"<[^>]+>", "", text).strip().lower()
    text = re.sub(r"[^\w\- ]", "", text)
    return text.replace(" ", "-")


def anchors_for(body: str) -> set[str]:
    seen: Counter = Counter()
    out = set()
    for _, title in HEADING.findall(body):
        m = EXPLICIT_ID.search(title)
        if m:
            out.add(m.group(1))
            title = EXPLICIT_ID.sub("", title)
        slug = slugify(title)
        out.add(slug if seen[slug] == 0 else f"{slug}-{seen[slug]}")
        seen[slug] += 1
    out.update(re.findall(r"""<a\s+(?:name|id)=["']([^"']+)["']""", body))
    return out


def git_dates(root: Path) -> dict[str, float]:
    try:
        top = subprocess.run(["git", "-C", str(root), "rev-parse", "--show-toplevel"],
                             capture_output=True, text=True, check=True).stdout.strip()
        log = subprocess.run(["git", "-C", top, "log", "--name-only", "--format=@@%ct", "--", str(root.resolve())],
                             capture_output=True, text=True, check=True).stdout
    except (OSError, subprocess.CalledProcessError):
        return {}
    dates: dict[str, float] = {}
    ts = None
    for line in log.splitlines():
        if line.startswith("@@"):
            ts = float(line[2:])
        elif line.strip() and ts is not None:
            dates.setdefault(str((Path(top) / line.strip()).resolve()), ts)  # newest first
    return dates


def resolve(src: Path, target: str, root: Path) -> Path | None:
    base = root if target.startswith("/") else src.parent
    cand = (base / target.lstrip("/")).resolve()
    tries = [cand]
    if not cand.suffix:
        tries += [cand.with_suffix(e) for e in EXTS] + [cand / n for n in INDEX_NAMES]
    elif cand.suffix == ".html":
        tries += [cand.with_suffix(e) for e in EXTS]
    for t in tries:
        if t.is_file():
            return t
    return None


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("docs_dir", type=Path)
    ap.add_argument("--stale-days", type=int, default=365)
    ap.add_argument("--max-lines", type=int, default=800)
    ap.add_argument("--json", type=Path, help="also write findings as JSON")
    ap.add_argument("--ignore", action="append", default=["**/node_modules/**", "**/_build/**"])
    args = ap.parse_args()

    root = args.docs_dir.resolve()
    if not root.is_dir():
        print(f"error: {root} is not a directory", file=sys.stderr)
        return 2
    pages = sorted(p.resolve() for p in root.rglob("*") if p.suffix in EXTS and p.is_file()
                   and not any(fnmatch.fnmatch(str(p), g) for g in args.ignore))
    if not pages:
        print(f"error: no .md/.mdx files under {root}", file=sys.stderr)
        return 2

    dates = git_dates(root)
    now = time.time()
    texts, anchors, titles = {}, {}, {}
    for p in pages:
        raw = p.read_text(encoding="utf-8", errors="replace")
        fm = FRONTMATTER.match(raw)
        body = FENCE.sub("", raw[fm.end():] if fm else raw)
        texts[p] = (raw, body)
        anchors[p] = anchors_for(body)
        title = None
        if fm:
            m = re.search(r"^title:\s*['\"]?(.+?)['\"]?\s*$", fm.group(1), re.M)
            title = m.group(1) if m else None
        if not title:
            m = re.search(r"^#\s+(.+)$", body, re.M)
            title = m.group(1).strip() if m else None
        titles[p] = title

    broken, unresolved_abs, inbound = [], [], defaultdict(set)
    findings = defaultdict(list)
    for p in pages:
        raw, body = texts[p]
        targets = LINK.findall(body) + IMAGE.findall(body) + REFDEF.findall(body) + HREF.findall(body)
        for t in targets:
            if re.match(r"^[a-z][a-z0-9+.-]*:", t, re.I) or t.startswith("//"):
                continue  # external, mailto:, tel:, etc. Not checked offline.
            path_part, _, frag = t.partition("#")
            if not path_part:
                if frag and frag not in anchors[p]:
                    broken.append((p, t, "anchor not found on this page"))
                continue
            dest = resolve(p, path_part.split("?")[0], root)
            if dest is None:
                (unresolved_abs if path_part.startswith("/") else broken).append((p, t, "file not found"))
                continue
            if dest != p:
                inbound[dest].add(p)
            if frag and dest in anchors and frag not in anchors[dest]:
                broken.append((p, t, f"anchor #{frag} not in {dest.relative_to(root)}"))

        rel = str(p.relative_to(root))
        lines = raw.count("\n") + 1
        if not titles[p]:
            findings["no_title"].append(rel)
        if lines > args.max_lines:
            findings["long_pages"].append(f"{rel} ({lines} lines)")
        todos = len(TODO.findall(body))
        if todos:
            findings["todo_markers"].append(f"{rel} ({todos})")
        ts = dates.get(str(p)) or p.stat().st_mtime
        age = int((now - ts) / 86400)
        if age > args.stale_days:
            findings["stale"].append((age, rel))

    for p in pages:
        if p.name in INDEX_NAMES or p.parent == root and p.stem.lower() in ("index", "readme"):
            continue
        if not inbound[p]:
            findings["orphans"].append(str(p.relative_to(root)))
    dupes = [t for t, c in Counter(t for t in titles.values() if t).items() if c > 1]
    findings["duplicate_titles"] = [f"{t}: " + ", ".join(str(p.relative_to(root)) for p in pages if titles[p] == t)
                                    for t in dupes]
    findings["stale"] = [f"{rel} ({age} days)" for age, rel in sorted(findings["stale"], reverse=True)]

    src = "git history" if dates else "file mtime (no git history found)"
    print(f"Docs audit: {root}\n{len(pages)} pages; staleness from {src}\n")
    print(f"Broken links/anchors: {len(broken)}")
    for p, t, why in broken:
        print(f"  {p.relative_to(root)} -> {t}  ({why})")
    if unresolved_abs:
        print(f"\nSite-absolute links not found under docs root (check site routing): {len(unresolved_abs)}")
        for p, t, _ in unresolved_abs[:50]:
            print(f"  {p.relative_to(root)} -> {t}")
    labels = {
        "orphans": "Pages with no inbound links (check sidebar/nav config before deleting)",
        "stale": f"Not changed in > {args.stale_days} days",
        "no_title": "Pages without a title (frontmatter title or H1)",
        "duplicate_titles": "Duplicate titles",
        "todo_markers": "Pages with TODO/FIXME/TBD markers",
        "long_pages": f"Pages over {args.max_lines} lines",
    }
    for key, label in labels.items():
        items = findings.get(key, [])
        print(f"\n{label}: {len(items)}")
        for item in items[:50]:
            print(f"  {item}")
        if len(items) > 50:
            print(f"  ... {len(items) - 50} more (see --json)")

    if args.json:
        out = {k: v for k, v in findings.items()}
        out["broken"] = [{"page": str(p.relative_to(root)), "target": t, "reason": w} for p, t, w in broken]
        out["unresolved_absolute"] = [{"page": str(p.relative_to(root)), "target": t} for p, t, _ in unresolved_abs]
        out["pages"] = len(pages)
        args.json.write_text(json.dumps(out, indent=2), encoding="utf-8")
        print(f"\nJSON written to {args.json}")
    return 1 if broken else 0


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