xtrm-tools 0.7.0 → 0.7.2

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

@@ -1,54 +0,0 @@
-#!/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

@@ -1,128 +0,0 @@
-#!/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

@@ -1,266 +0,0 @@
-#!/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()