xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/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/.xtrm/skills/default/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()

package/.xtrm/skills/default/documenting/scripts/generate_template.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""
+Generate SSOT memory template with boilerplate metadata.
+
+Creates a new memory file with proper frontmatter structure based on category type.
+"""
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+TEMPLATES = {
+    "ssot": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: {category}
+subcategory: {subcategory}
+domain: [{domain}]
+applicability: {applicability}
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial creation.
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Overview
+{overview}
+
+## Key Components
+
+### Component 1
+Description...
+
+### Component 2
+Description...
+
+## Current State
+
+### What Works
+- Item 1
+- Item 2
+
+### Known Limitations
+- Limitation 1
+- Limitation 2
+
+## Related SSOTs
+- `related_ssot_1.md` - Description
+- `related_ssot_2.md` - Description
+
+## Next Steps
+- [ ] Task 1
+- [ ] Task 2
+
+## References
+- Internal doc references
+- External resources
+""",
+
+    "pattern": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: pattern
+subcategory: {subcategory}
+domain: [{domain}]
+applicability: {applicability}
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial creation.
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Pattern Description
+{description}
+
+## When to Apply
+- Scenario 1
+- Scenario 2
+
+## Implementation
+
+### Approach
+Steps to implement this pattern...
+
+### Example
+```python
+# Code example
+```
+
+## Trade-offs
+
+### Benefits
+- Benefit 1
+- Benefit 2
+
+### Costs
+- Cost 1
+- Cost 2
+
+## Related Patterns
+- `related_pattern_1.md`
+- `related_pattern_2.md`
+""",
+
+    "reference": """---
+title: {title}
+scope: {scope}
+category: reference
+subcategory: {subcategory}
+domain: [{domain}]
+tracks: []
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Quick Reference
+
+### Category 1
+| Item | Description | Example |
+|------|-------------|---------|
+| Item1 | Desc | `example` |
+
+### Category 2
+Details...
+
+## Detailed Documentation
+
+### Section 1
+Content...
+
+### Section 2
+Content...
+
+## Examples
+
+### Example 1: {example_name}
+```
+Code or configuration example
+```
+
+### Example 2: {example_name}
+```
+Code or configuration example
+```
+
+## Additional Resources
+- Link 1
+- Link 2
+""",
+
+    "plan": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: plan
+subcategory: {subcategory}
+status: draft
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial plan creation.
+tracks: []
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Objective
+{objective}
+
+## Background
+{background}
+
+## Proposed Approach
+
+### Phase 1: {phase_name}
+- Task 1
+- Task 2
+
+### Phase 2: {phase_name}
+- Task 1
+- Task 2
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Risks & Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | High | Mitigation strategy |
+
+## Timeline
+- Phase 1: Dates
+- Phase 2: Dates
+
+## Related Docs
+- `related_ssot.md`
+- `related_pattern.md`
+""",
+}
+
+
+def generate_timestamp():
+    """Generate ISO8601 timestamp with timezone."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def generate_date():
+    """Generate YYYY-MM-DD date."""
+    return datetime.now().strftime("%Y-%m-%d")
+
+
+def generate_template(category, **kwargs):
+    """Generate memory template from category."""
+    if category not in TEMPLATES:
+        print(f"ERROR: Invalid category: {category}")
+        print(f"Valid categories: {', '.join(TEMPLATES.keys())}")
+        sys.exit(1)
+
+    # Merge defaults with user-provided values
+    params = {
+        "title": "New Memory",
+        "timestamp": generate_timestamp(),
+        "date": generate_date(),
+        "scope": "to-be-defined",
+        "category": category,
+        "subcategory": "general",
+        "domain": "domain1, domain2",
+        "applicability": "specific area or 'all'",
+        "purpose": "Brief statement of purpose...",
+        "overview": "High-level overview...",
+        "description": "Detailed description...",
+        "objective": "What this plan aims to achieve...",
+        "background": "Context and motivation...",
+        "phase_name": "Phase Name",
+        "example_name": "Example Name",
+    }
+    params.update(kwargs)
+
+    return TEMPLATES[category].format(**params)
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: generate_template.py <category> <output_filename> [key=value ...]")
+        print("")
+        print("Categories: ssot, pattern, reference, plan")
+        print("")
+        print("Examples:")
+        print("  generate_template.py ssot analytics_new_ssot.md \\")
+        print("      title='New Analytics SSOT' domain='analytics' subcategory='metrics'")
+        print("")
+        print("  generate_template.py pattern caching_strategy_pattern.md \\")
+        print("      title='Caching Strategy Pattern' domain='performance'")
+        sys.exit(1)
+
+    category = sys.argv[1]
+    output_file = sys.argv[2]
+
+    # Parse optional key=value parameters
+    params = {}
+    for arg in sys.argv[3:]:
+        if '=' in arg:
+            key, value = arg.split('=', 1)
+            params[key] = value.strip("'\"")
+
+    # Generate template
+    content = generate_template(category, **params)
+
+    # Write to file
+    output_path = Path(output_file)
+    if output_path.exists():
+        print(f"ERROR: File already exists: {output_file}")
+        print("Use a different filename or remove the existing file first.")
+        sys.exit(1)
+
+    output_path.write_text(content, encoding='utf-8')
+    print(f"✅ Created {category} memory: {output_file}")
+    print(f"📝 Edit the file to fill in placeholders and add content.")
+
+
+if __name__ == "__main__":
+    main()