xtrm-tools 0.5.0

package/skills/sync-docs/scripts/drift_detector.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""
+Detect documentation drift between docs/ files and git-modified files.
+
+A docs file is considered stale when it declares source globs in frontmatter
+(`source_of_truth_for` or `tracks`) and recent commits modified matching files.
+
+Subcommands:
+  scan [--since N] [--json]  — scan all docs files (default N=30 commits)
+  check <docs-file> [--since N] [--json]  — check one docs file
+  hook [--json]              — check current uncommitted changes
+"""
+
+import sys
+import re
+import json
+import fnmatch
+import subprocess
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+
+def find_project_root() -> Path:
+    """Walk up from cwd looking for docs/ and .git."""
+    p = Path.cwd()
+    for parent in [p, *p.parents]:
+        if (parent / ".git").exists():
+            return parent
+    return p
+
+
+def get_docs_files(project_root: Path) -> list[Path]:
+    docs_dir = project_root / "docs"
+    if not docs_dir.exists():
+        return []
+    return sorted(docs_dir.rglob("*.md"))
+
+
+def extract_frontmatter(content: str) -> dict[str, Any]:
+    match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
+    if not match:
+        return {}
+
+    raw = match.group(1)
+    if yaml is not None:
+        try:
+            return yaml.safe_load(raw) or {}
+        except Exception:
+            return {}
+
+    # Minimal fallback parser for environments without pyyaml
+    fm: dict[str, Any] = {}
+    current_key: str | None = None
+    for line in raw.splitlines():
+        if not line.strip() or line.strip().startswith("#"):
+            continue
+        if re.match(r"^[A-Za-z0-9_\-]+:\s*", line):
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+            if not value:
+                fm[key] = []
+                current_key = key
+            else:
+                fm[key] = value.strip('"')
+                current_key = None
+        elif current_key and line.strip().startswith("-"):
+            item = line.strip()[1:].strip().strip('"')
+            if isinstance(fm.get(current_key), list):
+                fm[current_key].append(item)
+    return fm
+
+
+def extract_globs(content: str) -> list[str]:
+    fm = extract_frontmatter(content)
+    source = fm.get("source_of_truth_for", [])
+    tracks = fm.get("tracks", [])
+
+    globs: list[str] = []
+    if isinstance(source, list):
+        globs.extend(str(x) for x in source)
+    if isinstance(tracks, list):
+        for item in tracks:
+            s = str(item)
+            if s not in globs:
+                globs.append(s)
+
+    return [g for g in globs if g.strip()]
+
+
+def extract_updated(content: str) -> str:
+    fm = extract_frontmatter(content)
+    return str(fm.get("updated", ""))
+
+
+def _match_glob(path: str, pattern: str) -> bool:
+    path_parts = Path(path).as_posix().split("/")
+    pattern_parts = Path(pattern).as_posix().split("/")
+
+    def _match(pp: list[str], pat: list[str]) -> bool:
+        if not pat:
+            return not pp
+        if pat[0] == "**":
+            for i in range(len(pp) + 1):
+                if _match(pp[i:], pat[1:]):
+                    return True
+            return False
+        if not pp:
+            return False
+        return fnmatch.fnmatch(pp[0], pat[0]) and _match(pp[1:], pat[1:])
+
+    return _match(path_parts, pattern_parts)
+
+
+def match_files_to_globs(files: list[str], globs: list[str]) -> list[str]:
+    matched: list[str] = []
+    for file_path in files:
+        for pattern in globs:
+            if _match_glob(file_path, pattern):
+                matched.append(file_path)
+                break
+    return matched
+
+
+def get_recent_modified_files(project_root: Path, since_n_commits: int = 30) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "log", f"-{since_n_commits}", "--name-only", "--format="],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return []
+        return [l.strip() for l in result.stdout.splitlines() if l.strip()]
+    except Exception:
+        return []
+
+
+def get_session_written_files(project_root: Path) -> list[str]:
+    try:
+        unstaged = subprocess.run(
+            ["git", "diff", "HEAD", "--name-only"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        staged = subprocess.run(
+            ["git", "diff", "--cached", "--name-only"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        files = unstaged.stdout.splitlines() + staged.stdout.splitlines()
+        return sorted({f.strip() for f in files if f.strip()})
+    except Exception:
+        return []
+
+
+def scan_docs(project_root: Path, changed_files: list[str]) -> list[dict[str, Any]]:
+    stale: list[dict[str, Any]] = []
+    for doc_path in get_docs_files(project_root):
+        content = doc_path.read_text(encoding="utf-8", errors="replace")
+        globs = extract_globs(content)
+        if not globs:
+            continue
+
+        matched = match_files_to_globs(changed_files, globs)
+        if matched:
+            stale.append(
+                {
+                    "doc": str(doc_path.relative_to(project_root)),
+                    "updated": extract_updated(content),
+                    "matched_files": matched[:10],
+                    "globs": globs,
+                }
+            )
+    return stale
+
+
+def print_human_report(stale: list[dict[str, Any]], source: str) -> None:
+    if not stale:
+        print(f"[Docs Drift] All docs up to date ({source}).")
+        return
+
+    print(f"[Drift Report] {len(stale)} stale doc(s) detected from {source}:\n")
+    for item in stale:
+        print(f"  {item['doc']}")
+        print(f"    Last updated: {item['updated'] or 'unknown'}")
+        for file_path in item["matched_files"][:3]:
+            print(f"    Modified: {file_path}")
+        print("")
+    print("Run /sync-docs to review and update stale docs.")
+
+
+def cmd_scan(args: list[str]) -> None:
+    since = 30
+    as_json = "--json" in args
+    if "--since" in args:
+        idx = args.index("--since")
+        if idx + 1 < len(args):
+            since = int(args[idx + 1])
+
+    project_root = find_project_root()
+    changed = get_recent_modified_files(project_root, since)
+    stale = scan_docs(project_root, changed)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "mode": "scan",
+                    "since": since,
+                    "count": len(stale),
+                    "stale": stale,
+                },
+                indent=2,
+            )
+        )
+    else:
+        print_human_report(stale, f"last {since} commits")
+
+    sys.exit(1 if stale else 0)
+
+
+def cmd_check(args: list[str]) -> None:
+    if not args:
+        print("Usage: drift_detector.py check <docs-file> [--since N] [--json]")
+        sys.exit(1)
+
+    target = args[0]
+    as_json = "--json" in args
+    since = 30
+    if "--since" in args:
+        idx = args.index("--since")
+        if idx + 1 < len(args):
+            since = int(args[idx + 1])
+
+    project_root = find_project_root()
+    doc_path = (project_root / target).resolve()
+    if not doc_path.exists():
+        print(f"Doc not found: {target}")
+        sys.exit(1)
+
+    changed = get_recent_modified_files(project_root, since)
+    content = doc_path.read_text(encoding="utf-8")
+    globs = extract_globs(content)
+    matched = match_files_to_globs(changed, globs) if globs else []
+
+    payload = {
+        "mode": "check",
+        "doc": str(doc_path.relative_to(project_root)),
+        "since": since,
+        "stale": bool(matched),
+        "matched_files": matched[:10],
+        "globs": globs,
+    }
+
+    if as_json:
+        print(json.dumps(payload, indent=2))
+    else:
+        if matched:
+            print(f"{payload['doc']}: STALE")
+            for f in matched[:5]:
+                print(f"  Modified: {f}")
+        else:
+            print(f"{payload['doc']}: up to date")
+
+    sys.exit(1 if matched else 0)
+
+
+def cmd_hook(args: list[str]) -> None:
+    as_json = "--json" in args
+    project_root = find_project_root()
+    changed = get_session_written_files(project_root)
+    if not changed:
+        sys.exit(0)
+
+    stale = scan_docs(project_root, changed)
+    if not stale:
+        sys.exit(0)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "Stop",
+                        "additionalContext": (
+                            f"[Docs Drift] {len(stale)} docs may need updates. "
+                            "Run /sync-docs to review."
+                        ),
+                    }
+                }
+            )
+        )
+    else:
+        print_human_report(stale, "current session changes")
+
+    sys.exit(1)
+
+
+SUBCOMMANDS = {"scan": cmd_scan, "check": cmd_check, "hook": cmd_hook}
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if not args or args[0] not in SUBCOMMANDS:
+        print("Usage: drift_detector.py <scan|check|hook> [options]")
+        print("  scan [--since N] [--json]          scan all docs files")
+        print("  check <docs-file> [--since N]      check one docs file")
+        print("  hook [--json]                      stop-hook mode")
+        sys.exit(1)
+
+    SUBCOMMANDS[args[0]](args[1:])
+
+
+if __name__ == "__main__":
+    main()

package/skills/sync-docs/scripts/validate_doc.py

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+"""
+Validate and generate schema-compliant docs/ files.
+
+Schema for docs/ files:
+  Required: title, scope, category, version, updated
+  Optional: description, source_of_truth_for (glob list), domain (tag list)
+
+Usage:
+  validate_doc.py <file_or_dir>           # validate one file or all *.md in dir
+  validate_doc.py --generate <path>       # generate scaffold + required flags below
+    --title="..."
+    --scope="..."
+    --category="reference|guide|architecture|api"
+    --source-for="glob1,glob2"            # optional
+    --description="..."                   # optional
+"""
+
+import sys
+import re
+import json
+from pathlib import Path
+from datetime import date
+
+# ── Schema ────────────────────────────────────────────────────────────────────
+
+REQUIRED_FIELDS = ["title", "scope", "category", "version", "updated"]
+VALID_CATEGORIES = ["reference", "guide", "architecture", "api", "plan", "overview"]
+
+CATEGORY_DESCRIPTIONS = {
+    "reference": "Look-up table, cheat sheet, or technical specification",
+    "guide": "How-to documentation with step-by-step instructions",
+    "architecture": "System design, component relationships, high-level overview",
+    "api": "API contracts, interfaces, or data schemas",
+    "plan": "Implementation plan or roadmap",
+    "overview": "Summary introduction to a subsystem",
+}
+
+
+# ── Frontmatter helpers ───────────────────────────────────────────────────────
+
+def extract_frontmatter(content: str) -> dict | None:
+    """Parse simple YAML frontmatter without external dependencies.
+
+    Handles scalar values, quoted strings, and list fields (- item syntax).
+    """
+    m = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
+    if not m:
+        return None
+
+    result: dict[str, object] = {}
+    current_key: str | None = None
+    current_list: list[str] | None = None
+
+    for line in m.group(1).splitlines():
+        # List item under current key
+        if current_list is not None and re.match(r"^\s+-\s+", line):
+            current_list.append(re.sub(r"^\s+-\s+", "", line).strip().strip('"\''))
+            continue
+
+        # New key: value line
+        kv = re.match(r'^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)', line)
+        if kv:
+            # Flush previous list
+            if current_key is not None and current_list is not None:
+                result[current_key] = current_list
+
+            current_key = kv.group(1)
+            raw_val = kv.group(2).strip()
+
+            if raw_val == "" or raw_val == ">-":
+                # Value on following lines (list or multiline) — start list
+                current_list = []
+            elif raw_val.startswith("["):
+                # Inline list: [a, b, c]
+                current_list = None
+                inner = raw_val.strip("[]")
+                result[current_key] = [v.strip().strip('"\'') for v in inner.split(",") if v.strip()]
+            else:
+                current_list = None
+                result[current_key] = raw_val.strip('"\'')
+        else:
+            # Continuation line for multiline scalar — ignore for our purposes
+            pass
+
+    # Flush trailing list
+    if current_key is not None and current_list is not None:
+        result[current_key] = current_list
+
+    return result
+
+
+def extract_headings(content: str) -> list[tuple[str, str]]:
+    """Return (heading, first_sentence) for every ## section."""
+    results = []
+    lines = content.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.startswith("## ") and not line.startswith("### "):
+            heading = line[3:].strip()
+            summary = ""
+            j = i + 1
+            in_code = False
+            while j < len(lines):
+                ln = lines[j].strip()
+                if ln.startswith("```"):
+                    in_code = not in_code
+                    j += 1
+                    continue
+                if not in_code and ln and not ln.startswith("#"):
+                    summary = ln.split(".")[0].strip()[:120]
+                    break
+                j += 1
+            results.append((heading, summary))
+        i += 1
+    return results
+
+
+def make_anchor(heading: str) -> str:
+    """Generate a GitHub-compatible anchor from a heading string."""
+    anchor = heading.lower()
+    anchor = re.sub(r"\s+", "-", anchor)          # spaces → hyphens
+    anchor = re.sub(r"[^a-z0-9\-]", "", anchor)   # strip non-alphanumeric (except -)
+    anchor = re.sub(r"-+", "-", anchor)            # collapse runs
+    return anchor.strip("-")
+
+
+def generate_index_table(headings: list[tuple[str, str]]) -> str:
+    rows = ["| Section | Summary |", "|---|---|"]
+    for heading, summary in headings:
+        rows.append(f"| [{heading}](#{make_anchor(heading)}) | {summary or '_no summary_'} |")
+    return "\n".join(rows) + "\n"
+
+
+def inject_index(content: str, table: str) -> str:
+    header = "<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->\n"
+    footer = "<!-- END INDEX -->"
+    block = f"{header}{table}{footer}"
+
+    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
+    if existing:
+        return content[: existing.start()] + block + content[existing.end() :]
+
+    fm_match = re.match(r"^(---\n.*?\n---\n)(.*)", content, re.DOTALL)
+    if fm_match:
+        return fm_match.group(1) + "\n" + block + "\n" + fm_match.group(2)
+
+    return block + "\n" + content
+
+
+# ── Validation ────────────────────────────────────────────────────────────────
+
+def validate_file(path: Path) -> tuple[bool, list[str], list[str]]:
+    """Returns (passed, errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not path.exists():
+        return False, [f"File not found: {path}"], []
+
+    content = path.read_text(encoding="utf-8")
+    fm = extract_frontmatter(content)
+
+    if fm is None:
+        errors.append("Missing or invalid YAML frontmatter (wrap in --- markers)")
+        return False, errors, warnings
+
+    # Required fields
+    for field in REQUIRED_FIELDS:
+        if field not in fm:
+            errors.append(f"Missing required field: {field}")
+
+    # version format
+    if "version" in fm:
+        if not re.match(r"^\d+\.\d+\.\d+$", str(fm["version"])):
+            errors.append(f"version must be semver (x.y.z), got: {fm['version']}")
+
+    # updated format
+    if "updated" in fm:
+        if not re.match(r"^\d{4}-\d{2}-\d{2}", str(fm["updated"])):
+            warnings.append(f"updated should be ISO date (YYYY-MM-DD), got: {fm['updated']}")
+
+    # category valid
+    if "category" in fm and fm["category"] not in VALID_CATEGORIES:
+        errors.append(
+            f"category '{fm['category']}' not valid. Choose from: {', '.join(VALID_CATEGORIES)}"
+        )
+
+    # domain is list
+    if "domain" in fm and not isinstance(fm["domain"], list):
+        errors.append("domain must be a list, e.g. [hooks, claude]")
+
+    # source_of_truth_for and tracks are lists of globs
+    if "source_of_truth_for" in fm and not isinstance(fm["source_of_truth_for"], list):
+        errors.append("source_of_truth_for must be a list of glob patterns")
+    if "tracks" in fm and not isinstance(fm["tracks"], list):
+        errors.append("tracks must be a list of glob patterns")
+
+    # Regenerate INDEX if valid
+    if not errors:
+        headings = extract_headings(content)
+        if headings:
+            table = generate_index_table(headings)
+            new_content = inject_index(content, table)
+            if new_content != content:
+                path.write_text(new_content, encoding="utf-8")
+                warnings.append("INDEX regenerated")
+
+    return len(errors) == 0, errors, warnings
+
+
+def validate_directory(docs_dir: Path) -> dict:
+    results = {}
+    for md_file in sorted(docs_dir.glob("*.md")):
+        passed, errors, warnings = validate_file(md_file)
+        results[str(md_file.relative_to(docs_dir.parent))] = {
+            "passed": passed,
+            "errors": errors,
+            "warnings": warnings,
+        }
+    return results
+
+
+def print_file_result(path: str, passed: bool, errors: list[str], warnings: list[str]) -> None:
+    status = "PASS" if passed else "FAIL"
+    mark = "" if passed else ""
+    print(f"\n{mark} {path} [{status}]")
+    for e in errors:
+        print(f"    ERROR: {e}")
+    for w in warnings:
+        print(f"    WARN:  {w}")
+    if passed and not warnings:
+        print("    All checks passed.")
+
+
+# ── Generator ─────────────────────────────────────────────────────────────────
+
+SCAFFOLD_TEMPLATE = """\
+---
+title: {title}
+scope: {scope}
+category: {category}
+version: 1.0.0
+updated: {today}
+{source_field}{tracks_field}{description_field}domain: []
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+<!-- END INDEX -->
+
+# {title}
+
+> {category_desc}
+
+## Overview
+
+_Describe what this document covers._
+
+"""
+
+
+def generate_scaffold(output_path: Path, title: str, scope: str, category: str,
+                      source_for: list[str], description: str) -> None:
+    source_field = ""
+    tracks_field = ""
+    if source_for:
+        items = "\n".join(f'  - "{g}"' for g in source_for)
+        source_field = f"source_of_truth_for:\n{items}\n"
+        # tracks: mirrors source_of_truth_for so drift_detector.py picks up changes
+        tracks_field = f"tracks:\n{items}\n"
+
+    desc_field = f'description: "{description}"\n' if description else ""
+    category_desc = CATEGORY_DESCRIPTIONS.get(category, category)
+
+    content = SCAFFOLD_TEMPLATE.format(
+        title=title,
+        scope=scope,
+        category=category,
+        today=date.today().isoformat(),
+        source_field=source_field,
+        tracks_field=tracks_field,
+        description_field=desc_field,
+        category_desc=category_desc,
+    )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content, encoding="utf-8")
+    print(f"Generated: {output_path}")
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if not args:
+        print("Usage:")
+        print("  validate_doc.py <file_or_dir>")
+        print("  validate_doc.py --generate <path> --title=... --scope=... --category=...")
+        sys.exit(1)
+
+    # Generate mode
+    if "--generate" in args:
+        idx = args.index("--generate")
+        if idx + 1 >= len(args):
+            print("ERROR: --generate requires a path argument")
+            sys.exit(1)
+        output_path = Path(args[idx + 1])
+
+        kw: dict[str, str] = {}
+        source_for: list[str] = []
+        for arg in args:
+            if arg.startswith("--title="):
+                kw["title"] = arg.split("=", 1)[1]
+            elif arg.startswith("--scope="):
+                kw["scope"] = arg.split("=", 1)[1]
+            elif arg.startswith("--category="):
+                kw["category"] = arg.split("=", 1)[1]
+            elif arg.startswith("--source-for="):
+                source_for = [g.strip() for g in arg.split("=", 1)[1].split(",")]
+            elif arg.startswith("--description="):
+                kw["description"] = arg.split("=", 1)[1]
+
+        for req in ["title", "scope", "category"]:
+            if req not in kw:
+                print(f"ERROR: --{req} is required for --generate")
+                sys.exit(1)
+
+        generate_scaffold(
+            output_path,
+            title=kw["title"],
+            scope=kw["scope"],
+            category=kw["category"],
+            source_for=source_for,
+            description=kw.get("description", ""),
+        )
+        sys.exit(0)
+
+    # Validate mode
+    target = Path(args[0])
+    all_passed = True
+
+    if target.is_dir():
+        results = validate_directory(target)
+        for path_str, res in results.items():
+            print_file_result(path_str, res["passed"], res["errors"], res["warnings"])
+            if not res["passed"]:
+                all_passed = False
+        if results:
+            total = len(results)
+            passed = sum(1 for r in results.values() if r["passed"])
+            print(f"\nResult: {passed}/{total} files passed")
+        else:
+            print(f"No .md files found in {target}")
+    else:
+        passed, errors, warnings = validate_file(target)
+        print_file_result(str(target), passed, errors, warnings)
+        all_passed = passed
+
+    sys.exit(0 if all_passed else 1)
+
+
+if __name__ == "__main__":
+    main()