chore: repository setup

Author: t

.github/scripts/check-docs.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Documentation consistency checks.
+
+Run locally from the repository root:
+
+    python .github/scripts/check-docs.py
+
+Verifies three things that would otherwise rot silently:
+
+  1. every relative link and heading anchor resolves
+  2. every module on disk is linked exactly once from a family guide
+  3. every module count written in prose matches what is on disk
+
+Exits non-zero on the first category that fails.
+"""
+
+import os
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+MODULES_DIR = ROOT / "src" / "modules"
+FAMILIES = ("azure", "entra", "fortios", "github")
+
+failures = []
+
+
+def note(category, message):
+    failures.append("%s: %s" % (category, message))
+
+
+def doc_files():
+    files = sorted((ROOT / "docs").rglob("*.md"))
+    for extra in ("README.md", "CLAUDE.md"):
+        path = ROOT / extra
+        if path.exists():
+            files.append(path)
+    return files
+
+
+def slugify(heading):
+    text = heading.strip().lower().replace("`", "")
+    text = re.sub(r"[^\w\s-]", "", text)
+    return re.sub(r"\s+", "-", text).strip("-")
+
+
+def rel(path):
+    return os.path.relpath(path, ROOT).replace(os.sep, "/")
+
+
+# ---------------------------------------------------------------------------
+# 1. links and anchors
+# ---------------------------------------------------------------------------
+
+def check_links(files):
+    anchors = {}
+    for path in files:
+        text = path.read_text(encoding="utf-8")
+        anchors[rel(path)] = {
+            slugify(m.group(2)) for m in re.finditer(r"^(#{1,6})\s+(.*)$", text, re.M)
+        }
+
+    checked = 0
+    link_re = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)")
+    for path in files:
+        text = path.read_text(encoding="utf-8")
+        for match in link_re.finditer(text):
+            target = match.group(2)
+            if target.startswith(("http://", "https://", "mailto:")):
+                continue
+            checked += 1
+            file_part, _, anchor = target.partition("#")
+            if file_part:
+                resolved = (path.parent / file_part).resolve()
+                if not resolved.exists():
+                    note("links", "%s -> missing path %s" % (rel(path), target))
+                    continue
+                key = rel(resolved)
+            else:
+                key = rel(path)
+            if anchor:
+                if key not in anchors:
+                    note("links", "%s -> anchor on non-doc %s" % (rel(path), target))
+                elif anchor not in anchors[key]:
+                    note("links", "%s -> missing anchor %s" % (rel(path), target))
+    return checked
+
+
+# ---------------------------------------------------------------------------
+# 2. inventory
+# ---------------------------------------------------------------------------
+
+def check_inventory(on_disk):
+    linked = Counter()
+    for guide in sorted((ROOT / "docs" / "modules").glob("*.md")):
+        text = guide.read_text(encoding="utf-8")
+        for match in re.finditer(r"\(\.\./\.\./src/modules/([^/)]+)/\)", text):
+            linked[match.group(1)] += 1
+
+    for name in sorted(on_disk - set(linked)):
+        note("inventory", "%s is not linked from any family guide" % name)
+    for name in sorted(set(linked) - on_disk):
+        note("inventory", "%s is linked but does not exist on disk" % name)
+    for name, count in sorted(linked.items()):
+        if count > 1:
+            note("inventory", "%s is linked %d times (expected once)" % (name, count))
+    return len(linked)
+
+
+# ---------------------------------------------------------------------------
+# 3. counts written in prose
+# ---------------------------------------------------------------------------
+
+def expect(label, pattern, text, source, actual):
+    """Assert the single capture group of `pattern` equals `actual`."""
+    match = re.search(pattern, text, re.M)
+    if not match:
+        note("counts", "%s: pattern for %s no longer matches — update the checker "
+                       "or restore the sentence" % (source, label))
+        return
+    found = int(match.group(1))
+    if found != actual:
+        note("counts", "%s: %s says %d, disk says %d" % (source, label, found, actual))
+
+
+def check_counts(on_disk):
+    per_family = {f: len([m for m in on_disk if m.startswith(f + "-")]) for f in FAMILIES}
+    total = len(on_disk)
+    submodules = len([
+        p for p in MODULES_DIR.glob("*/**/versions.tf")
+        if p.parent != MODULES_DIR / p.relative_to(MODULES_DIR).parts[0]
+    ])
+
+    for family in FAMILIES:
+        guide = ROOT / "docs" / "modules" / ("%s.md" % family)
+        expect("header count", r"^(\d+) modules on ", guide.read_text(encoding="utf-8"),
+               rel(guide), per_family[family])
+
+    docs_index = (ROOT / "docs" / "README.md").read_text(encoding="utf-8")
+    root_readme = (ROOT / "README.md").read_text(encoding="utf-8")
+    for family in FAMILIES:
+        expect("%s row" % family,
+               r"\[[^\]]+\]\(modules/%s\.md\)[^|]*\|[^|]*\|\s*(\d+)\s*\|" % family,
+               docs_index, "docs/README.md", per_family[family])
+        expect("%s row" % family,
+               r"\|[^|]*\|[^|]*\|\s*(\d+)\s*\|[^|]*docs/modules/%s\.md" % family,
+               root_readme, "README.md", per_family[family])
+
+    expect("module total", r"^(\d+) modules plus \d+ nested submodules",
+           root_readme, "README.md", total)
+    expect("submodule total", r"^\d+ modules plus (\d+) nested submodules",
+           root_readme, "README.md", submodules)
+
+    claude = (ROOT / "CLAUDE.md").read_text(encoding="utf-8")
+    expect("module total", r"\*\*(\d+)\*\* modules plus", claude, "CLAUDE.md", total)
+    expect("submodule total", r"\*\*\d+\*\* modules plus (\d+)\s*\n?nested submodules",
+           claude, "CLAUDE.md", submodules)
+    expect("directory total", r"\*\*(\d+) module directories\*\*",
+           claude, "CLAUDE.md", total + submodules)
+
+
+def main():
+    if not MODULES_DIR.is_dir():
+        print("error: %s not found — run from the repository root" % rel(MODULES_DIR))
+        return 2
+
+    on_disk = {p.name for p in MODULES_DIR.iterdir() if p.is_dir()}
+
+    files = doc_files()
+    checked = check_links(files)
+    linked = check_inventory(on_disk)
+    check_counts(on_disk)
+
+    print("docs checked      : %d" % len(files))
+    print("links resolved    : %d" % checked)
+    print("modules on disk   : %d" % len(on_disk))
+    print("modules linked    : %d" % linked)
+
+    if failures:
+        print("\n%d problem(s):\n" % len(failures))
+        for line in failures:
+            print("  %s" % line)
+        return 1
+
+    print("\nall documentation checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())