xtrm-tools 0.5.0

package/skills/documenting/scripts/changelog/init_changelog.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Initialize a new CHANGELOG.md file."""
+
+import sys
+from datetime import date
+from pathlib import Path
+
+
+def init_changelog(output_path: Path, initial_version: str = "0.1.0") -> None:
+    """Create new CHANGELOG.md from template."""
+    # Assuming the script is in skills/documenting/scripts/changelog/
+    # And template is in skills/documenting/templates/
+    # script path: .../skills/documenting/scripts/changelog/init_changelog.py
+    # parent: .../skills/documenting/scripts/changelog
+    # parent.parent: .../skills/documenting/scripts
+    # parent.parent.parent: .../skills/documenting
+    
+    template_path = Path(__file__).resolve().parent.parent.parent / "templates" / "CHANGELOG.md.template"
+
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_path}")
+
+    if output_path.exists():
+        raise FileExistsError(f"CHANGELOG already exists: {output_path}")
+
+    template = template_path.read_text(encoding='utf-8')
+    content = template.format(
+        release_date=date.today().strftime('%Y-%m-%d'),
+        initial_version=initial_version
+    )
+
+    output_path.write_text(content, encoding='utf-8')
+    print(f"✅ Created {output_path}")
+    print(f"📝 Initial version: {initial_version}")
+
+
+def main():
+    """CLI entry point."""
+    if len(sys.argv) < 2:
+        print("Usage: init_changelog.py <output_path> [initial_version]")
+        print("")
+        print("Example:")
+        print("  init_changelog.py ./CHANGELOG.md")
+        print("  init_changelog.py ./CHANGELOG.md 1.0.0")
+        sys.exit(1)
+
+    output_path = Path(sys.argv[1])
+    initial_version = sys.argv[2] if len(sys.argv) > 2 else "0.1.0"
+
+    init_changelog(output_path, initial_version)
+
+
+if __name__ == "__main__":
+    main()

package/skills/documenting/scripts/changelog/validate_changelog.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+Validate CHANGELOG.md follows Keep a Changelog 1.0.0 format.
+
+Checks:
+- Required header with Keep a Changelog link
+- [Unreleased] section exists
+- Version sections use semantic versioning
+- Valid categories: Added, Changed, Deprecated, Removed, Fixed, Security
+- Proper date format: YYYY-MM-DD
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+VALID_CATEGORIES = {"Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"}
+SEMVER_PATTERN = r"^\d+\.\d+\.\d+$"
+DATE_PATTERN = r"^\d{4}-\d{2}-\d{2}$"
+
+
+def validate_changelog(content: str) -> Dict[str, any]:
+    """
+    Validate CHANGELOG content.
+
+    Returns:
+        {
+            "valid": bool,
+            "errors": List[str],
+            "warnings": List[str]
+        }
+    """
+    errors = []
+    warnings = []
+
+    # Check header
+    if "Keep a Changelog" not in content:
+        errors.append("Missing 'Keep a Changelog' link in header")
+
+    if "Semantic Versioning" not in content:
+        warnings.append("Missing 'Semantic Versioning' link in header")
+
+    # Check for [Unreleased] section
+    if not re.search(r"^## \[Unreleased\]", content, re.MULTILINE):
+        errors.append("Missing required [Unreleased] section")
+
+    # Find all version sections
+    version_pattern = r"^## \[(.+?)\](?: - (\d{4}-\d{2}-\d{2}))?$"
+    versions = re.findall(version_pattern, content, re.MULTILINE)
+
+    for version, date in versions:
+        if version == "Unreleased":
+            if date:
+                warnings.append("[Unreleased] section should not have a date")
+            continue
+
+        # Validate semver
+        if not re.match(SEMVER_PATTERN, version):
+            errors.append(f"Invalid semantic version: [{version}] (expected X.Y.Z)")
+
+        # Validate date
+        if not date:
+            errors.append(f"Version [{version}] missing release date")
+        elif not re.match(DATE_PATTERN, date):
+            errors.append(f"Invalid date format for [{version}]: {date} (expected YYYY-MM-DD)")
+
+    # Find all categories
+    category_pattern = r"^### (.+?)$"
+    categories = re.findall(category_pattern, content, re.MULTILINE)
+
+    for category in categories:
+        if category not in VALID_CATEGORIES:
+            errors.append(f"Invalid category: '{category}' (must be one of {VALID_CATEGORIES})")
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings
+    }
+
+
+def validate_file(filepath: Path) -> Dict[str, any]:
+    """Validate a CHANGELOG.md file."""
+    if not filepath.exists():
+        return {
+            "valid": False,
+            "errors": [f"File not found: {filepath}"],
+            "warnings": []
+        }
+
+    content = filepath.read_text(encoding='utf-8')
+    return validate_changelog(content)
+
+
+def main():
+    """CLI entry point."""
+    import sys
+
+    if len(sys.argv) != 2:
+        print("Usage: validate_changelog.py <CHANGELOG.md>")
+        sys.exit(1)
+
+    filepath = Path(sys.argv[1])
+    result = validate_file(filepath)
+
+    print(f"Validating: {filepath.name}")
+    print("=" * 60)
+
+    if result["warnings"]:
+        print("\n⚠️  WARNINGS:")
+        for warning in result["warnings"]:
+            print(f"  - {warning}")
+
+    if result["errors"]:
+        print("\n❌ ERRORS:")
+        for error in result["errors"]:
+            print(f"  - {error}")
+        print("=" * 60)
+        sys.exit(1)
+
+    print("\n✅ VALID: All checks passed!")
+    print("=" * 60)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/documenting/scripts/drift_detector.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+Detect documentation drift between Serena memories and git-modified files.
+
+Subcommands:
+  scan [--since N]   — scan all memories, report stale ones (default N=30 commits)
+  check <memory>     — check a single memory by name
+  hook               — Stop hook mode: check session writes, output JSON if stale
+"""
+
+import sys
+import re
+import json
+import fnmatch
+import subprocess
+from pathlib import Path
+
+import yaml
+
+
+# ── Path resolution ───────────────────────────────────────────────────────────
+
+def find_project_root() -> Path:
+    """Walk up from cwd looking for .serena/memories/."""
+    p = Path.cwd()
+    for parent in [p, *p.parents]:
+        if (parent / ".serena" / "memories").exists():
+            return parent
+    print(f"Warning: no .serena/memories/ found in ancestors of {p}; using cwd", file=sys.stderr)
+    return p
+
+
+def get_memories_dir(project_root: Path) -> Path:
+    return project_root / ".serena" / "memories"
+
+
+# ── Frontmatter parsing ───────────────────────────────────────────────────────
+
+def extract_frontmatter(content: str) -> dict:
+    match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
+    if not match:
+        return {}
+    try:
+        return yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def extract_tracks(content: str) -> list:
+    """Return tracks: glob list from memory frontmatter."""
+    fm = extract_frontmatter(content)
+    tracks = fm.get("tracks", [])
+    return tracks if isinstance(tracks, list) else []
+
+
+def extract_updated(content: str) -> str:
+    fm = extract_frontmatter(content)
+    return str(fm.get("updated", ""))
+
+
+# ── File matching ─────────────────────────────────────────────────────────────
+
+def _match_glob(path: str, pattern: str) -> bool:
+    """Match a file path against a glob pattern with proper ** support."""
+    path_parts = Path(path).as_posix().split("/")
+    pattern_parts = Path(pattern).as_posix().split("/")
+
+    def _match(pp, pat):
+        if not pat:
+            return not pp
+        if pat[0] == "**":
+            # ** matches zero or more segments
+            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_tracks(files: list, tracks: list) -> list:
+    """Return files that match any of the tracks globs (supports **)."""
+    matched = []
+    for f in files:
+        for pattern in tracks:
+            if _match_glob(f, pattern):
+                matched.append(f)
+                break
+    return matched
+
+
+# ── Git helpers ───────────────────────────────────────────────────────────────
+
+def get_recent_modified_files(project_root: Path, since_n_commits: int = 30) -> list:
+    """Get files modified in the last N commits."""
+    try:
+        result = subprocess.run(
+            ["git", "log", f"-{since_n_commits}", "--name-only", "--format="],
+            cwd=project_root, capture_output=True, text=True
+        )
+        return [l.strip() for l in result.stdout.splitlines() if l.strip()]
+    except Exception:
+        return []
+
+
+def get_session_written_files(project_root: Path) -> list:
+    """Get files with uncommitted or staged changes."""
+    try:
+        r1 = subprocess.run(
+            ["git", "diff", "HEAD", "--name-only"],
+            cwd=project_root, capture_output=True, text=True
+        )
+        r2 = subprocess.run(
+            ["git", "diff", "--cached", "--name-only"],
+            cwd=project_root, capture_output=True, text=True
+        )
+        files = r1.stdout.splitlines() + r2.stdout.splitlines()
+        return list({f.strip() for f in files if f.strip()})
+    except Exception:
+        return []
+
+
+# ── Core logic ────────────────────────────────────────────────────────────────
+
+def scan_memories(project_root: Path, since_n_commits: int = 30) -> dict:
+    """Return {memory_stem: {files, updated}} for stale memories."""
+    memories_dir = get_memories_dir(project_root)
+    if not memories_dir.exists():
+        return {}
+
+    modified_files = get_recent_modified_files(project_root, since_n_commits)
+    stale = {}
+
+    for md_file in sorted(memories_dir.glob("*.md")):
+        content = md_file.read_text(encoding="utf-8")
+        tracks = extract_tracks(content)
+        if not tracks:
+            continue
+        matched = match_files_to_tracks(modified_files, tracks)
+        if matched:
+            stale[md_file.stem] = {
+                "files": matched[:5],
+                "updated": extract_updated(content),
+            }
+
+    return stale
+
+
+def format_scan_report(stale: dict) -> str:
+    if not stale:
+        return "[Docs Drift] All memories up to date. No action needed."
+
+    n = len(stale)
+    lines = [f"[Drift Report] {n} memor{'y' if n == 1 else 'ies'} stale:\n"]
+    for name, info in stale.items():
+        lines.append(f"  {name}")
+        lines.append(f"    Last updated: {info['updated']}")
+        for f in info["files"][:3]:
+            lines.append(f"    Modified: {f}")
+        lines.append("")
+    lines.append("Run /documenting to update.")
+    return "\n".join(lines)
+
+
+# ── Subcommands ───────────────────────────────────────────────────────────────
+
+def cmd_scan(args: list):
+    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()
+    stale = scan_memories(project_root, since)
+    print(format_scan_report(stale))
+    sys.exit(1 if stale else 0)
+
+
+def cmd_check(args: list):
+    if not args:
+        print("Usage: drift_detector.py check <memory-name>")
+        sys.exit(1)
+
+    memory_name = args[0]
+    project_root = find_project_root()
+    md_file = get_memories_dir(project_root) / f"{memory_name}.md"
+
+    if not md_file.exists():
+        print(f"Memory not found: {memory_name}")
+        sys.exit(1)
+
+    content = md_file.read_text(encoding="utf-8")
+    tracks = extract_tracks(content)
+    if not tracks:
+        print(f"{memory_name}: no tracks: field — skipping drift check.")
+        sys.exit(0)
+
+    modified = get_recent_modified_files(project_root, 30)
+    matched = match_files_to_tracks(modified, tracks)
+    if matched:
+        print(f"{memory_name}: STALE — matched: {', '.join(matched[:3])}")
+        sys.exit(1)
+    else:
+        print(f"{memory_name}: up to date.")
+        sys.exit(0)
+
+
+def cmd_hook(_args: list):
+    """Stop hook mode — outputs JSON reminder only if session files touch any tracks."""
+    project_root = find_project_root()
+    session_files = get_session_written_files(project_root)
+    if not session_files:
+        sys.exit(0)
+
+    memories_dir = get_memories_dir(project_root)
+    if not memories_dir.exists():
+        sys.exit(0)
+
+    stale_names = []
+    for md_file in sorted(memories_dir.glob("*.md")):
+        content = md_file.read_text(encoding="utf-8")
+        tracks = extract_tracks(content)
+        if not tracks:
+            continue
+        if match_files_to_tracks(session_files, tracks):
+            stale_names.append(md_file.stem)
+
+    if stale_names:
+        names = ", ".join(stale_names[:3])
+        suffix = f" (+{len(stale_names) - 3} more)" if len(stale_names) > 3 else ""
+        msg = (
+            f"[Docs Drift] {len(stale_names)} memor{'y' if len(stale_names) == 1 else 'ies'} "
+            f"may need updating: {names}{suffix}. Run /documenting to review."
+        )
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "Stop",
+                "additionalContext": msg,
+            }
+        }))
+
+    sys.exit(0)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+SUBCOMMANDS = {"scan": cmd_scan, "check": cmd_check, "hook": cmd_hook}
+
+
+def main():
+    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]   scan all memories (default N=30 commits)")
+        print("  check <memory>     check a single memory")
+        print("  hook               Stop hook mode (outputs JSON if stale)")
+        sys.exit(1)
+    SUBCOMMANDS[args[0]](args[1:])
+
+
+if __name__ == "__main__":
+    main()