xtrm-tools 2.0.0

package/skills/documenting/scripts/validate_metadata.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+Validate SSOT memory metadata compliance.
+
+Checks if a memory file has all required frontmatter fields and follows
+the naming conventions defined in the SSOT guidelines.
+"""
+
+import sys
+import re
+from pathlib import Path
+import yaml
+
+
+def extract_headings(content: str) -> list:
+    """Extract (heading, first_sentence) for every ## section (not ###)."""
+    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):
+                l = lines[j].strip()
+                if l.startswith("```"):
+                    in_code = not in_code
+                    j += 1
+                    continue
+                if not in_code and l and not l.startswith("#") and not l.startswith("|") and not l.startswith("-"):
+                    # Take up to first period, strip trailing period
+                    sentence = l.split(".")[0].strip()
+                    summary = sentence[:120]
+                    break
+                j += 1
+            results.append((heading, summary))
+        i += 1
+    return results
+
+
+def generate_index_table(headings: list) -> str:
+    """Generate a full markdown table string from headings list."""
+    rows = ["| Section | Summary |", "|---|---|"]
+    for heading, summary in headings:
+        anchor = heading.lower()
+        for ch in "/()":
+            anchor = anchor.replace(ch, "")
+        anchor = re.sub(r"[\s_]+", "-", anchor)
+        anchor = re.sub(r"-+", "-", anchor)
+        anchor = anchor.strip("-")
+        rows.append(f"| [{heading}](#{anchor}) | {summary or '_no summary_'} |")
+    return "\n".join(rows) + "\n"
+
+
+def inject_index(content: str, table: str) -> str:
+    """Replace existing INDEX block or insert one after frontmatter closing ---."""
+    header = "<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->\n"
+    footer = "<!-- END INDEX -->"
+    block = f"{header}{table}{footer}"
+
+    # Replace existing block
+    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
+    if existing:
+        return content[:existing.start()] + block + content[existing.end():]
+
+    # Insert after second --- (end of frontmatter)
+    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
+
+
+REQUIRED_FIELDS = {
+    "ssot": ["title", "version", "updated", "scope", "category", "subcategory", "domain"],
+    "pattern": ["title", "version", "updated", "scope", "category", "domain"],
+    "plan": ["title", "version", "updated", "scope", "category"],
+    "reference": ["title", "scope", "category"],
+    "archive": ["title", "version", "updated", "scope", "category", "archived_date"],
+}
+
+CATEGORY_SUFFIXES = ["ssot", "pattern", "plan", "reference", "archive", "troubleshoot", "commit_log"]
+
+
+def extract_frontmatter(content):
+    """Extract YAML frontmatter from markdown content."""
+    match = re.match(r'^---\n(.*?)\n---\n', content, re.DOTALL)
+    if not match:
+        return None
+    try:
+        return yaml.safe_load(match.group(1))
+    except yaml.YAMLError as e:
+        print(f"ERROR: Invalid YAML frontmatter: {e}")
+        return None
+
+
+def validate_naming(filename):
+    """Validate filename follows naming conventions."""
+    errors = []
+
+    # Check if ends with .md
+    if not filename.endswith('.md'):
+        errors.append("Filename should end with .md")
+        return errors
+
+    stem = filename[:-3]  # Remove .md
+    
+    # Check if ends with known category suffix
+    has_suffix = any(stem.endswith(f"_{suffix}") for suffix in CATEGORY_SUFFIXES)
+    if not has_suffix:
+        errors.append(f"Filename should end with one of: {', '.join(['_' + s + '.md' for s in CATEGORY_SUFFIXES])}")
+
+    return errors
+
+
+def validate_version(version):
+    """Validate semantic version format (x.y.z)."""
+    if not version:
+        return False
+    pattern = r'^\d+\.\d+\.\d+$'
+    return bool(re.match(pattern, str(version)))
+
+
+def validate_metadata(filepath):
+    """Validate memory metadata."""
+    path = Path(filepath)
+
+    if not path.exists():
+        print(f"ERROR: File not found: {filepath}")
+        return False
+
+    print(f"Validating: {path.name}")
+    print("=" * 60)
+
+    errors = []
+    warnings = []
+
+    # Check naming convention
+    naming_errors = validate_naming(path.name)
+    errors.extend(naming_errors)
+
+    # Read content
+    content = path.read_text(encoding='utf-8')
+
+    # Extract frontmatter
+    metadata = extract_frontmatter(content)
+    if metadata is None:
+        errors.append("Missing or invalid YAML frontmatter (should be between --- markers)")
+        print_results(errors, warnings)
+        return False
+
+    # Determine category from filename suffix
+    category = None
+    stem = path.name[:-3]
+    for suffix in CATEGORY_SUFFIXES:
+        if stem.endswith(f"_{suffix}"):
+            category = suffix
+            break
+
+    # Check required fields based on category
+    # If category is troubleshoot or commit_log, they might not have strict requirements yet
+    if category in REQUIRED_FIELDS:
+        required = REQUIRED_FIELDS[category]
+        missing_fields = [field for field in required if field not in metadata]
+        if missing_fields:
+            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
+    else:
+        # Default to ssot requirements if unknown but has suffix
+        required = REQUIRED_FIELDS["ssot"]
+        missing_fields = [field for field in required if field not in metadata]
+        if missing_fields:
+            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
+
+    # Validate version format (if present)
+    if "version" in metadata:
+        if not validate_version(metadata["version"]):
+            errors.append(f"Invalid version format: {metadata['version']} (should be x.y.z)")
+
+    # Validate updated timestamp (if present)
+    if "updated" in metadata:
+        updated = str(metadata["updated"])
+        # Check for ISO8601-ish format (basic validation)
+        if not re.match(r'^\d{4}-\d{2}-\d{2}', updated):
+            warnings.append(f"Updated timestamp should be ISO8601 format: {updated}")
+
+    # Check for domain field (should be array)
+    if "domain" in metadata:
+        if not isinstance(metadata["domain"], list):
+            errors.append("Domain field should be an array/list")
+
+    # Check for changelog in SSOT files
+    if category == "ssot" and "changelog" not in metadata:
+        warnings.append("SSOT files should include a changelog section in frontmatter")
+
+    print_results(errors, warnings)
+
+    # Regenerate INDEX block unconditionally (navigation aid, independent of schema validity)
+    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")
+            print("  ✏️  INDEX regenerated.")
+
+    return len(errors) == 0
+
+
+def print_results(errors, warnings):
+    """Print validation results."""
+    if errors:
+        print("\n❌ ERRORS:")
+        for error in errors:
+            print(f"  - {error}")
+
+    if warnings:
+        print("\n⚠️  WARNINGS:")
+        for warning in warnings:
+            print(f"  - {warning}")
+
+    if not errors and not warnings:
+        print("\n✅ VALID: All checks passed!")
+
+    print("=" * 60)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: validate_metadata.py <memory-file.md>")
+        print("Example: validate_metadata.py analytics_volatility_ssot.md")
+        sys.exit(1)
+
+    filepath = sys.argv[1]
+    success = validate_metadata(filepath)
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/documenting/templates/CHANGELOG.md.template

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [{initial_version}] - {release_date}
+
+### Added
+- Initial release

package/skills/documenting/tests/integration_test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Integration test for documenting skill workflows
+
+set -e  # Exit on error
+
+TEST_DIR=$(mktemp -d)
+echo "Test directory: $TEST_DIR"
+
+# Ensure we are in the skill root (skills/documenting)
+cd "$(dirname "$0")/.."
+SKILL_ROOT=$(pwd)
+echo "Skill root: $SKILL_ROOT"
+
+# Test 1: Initialize CHANGELOG
+echo "Test 1: Initialize CHANGELOG"
+python3 -m scripts.changelog.init_changelog "$TEST_DIR/CHANGELOG.md"
+python3 -m scripts.changelog.validate_changelog "$TEST_DIR/CHANGELOG.md"
+echo "✅ CHANGELOG initialization passed"
+
+# Test 2: Add entries
+echo ""
+echo "Test 2: Add entries to CHANGELOG"
+python3 -m scripts.changelog.add_entry "$TEST_DIR/CHANGELOG.md" Added "Feature A"
+python3 -m scripts.changelog.add_entry "$TEST_DIR/CHANGELOG.md" Fixed "Bug B"
+python3 -m scripts.changelog.add_entry "$TEST_DIR/CHANGELOG.md" Changed "Refactor C"
+python3 -m scripts.changelog.validate_changelog "$TEST_DIR/CHANGELOG.md"
+echo "✅ Entry addition passed"
+
+# Test 3: Bump release
+echo ""
+echo "Test 3: Bump release version"
+python3 -m scripts.changelog.bump_release "$TEST_DIR/CHANGELOG.md" "1.0.0"
+python3 -m scripts.changelog.validate_changelog "$TEST_DIR/CHANGELOG.md"
+
+# Verify [Unreleased] is empty and [1.0.0] has entries
+# Check 3 lines after Unreleased (header, empty line, next header)
+if grep -A 2 "\[Unreleased\]" "$TEST_DIR/CHANGELOG.md" | grep -q "^- "; then
+    echo "❌ [Unreleased] should be empty after bump"
+    cat "$TEST_DIR/CHANGELOG.md"
+    exit 1
+fi
+
+if ! grep -A 10 "\[1.0.0\]" "$TEST_DIR/CHANGELOG.md" | grep -q "Feature A"; then
+    echo "❌ [1.0.0] should contain Feature A"
+    exit 1
+fi
+echo "✅ Release bump passed"
+
+# Test 4: Orchestrator
+echo ""
+echo "Test 4: Orchestrator workflow"
+mkdir -p "$TEST_DIR/.serena/memories"
+cp "$TEST_DIR/CHANGELOG.md" "$TEST_DIR/CHANGELOG.md.backup"
+
+python3 -m scripts.orchestrator "$TEST_DIR" feature "Orchestrator test feature" --scope=test --category=testing
+
+# Verify CHANGELOG updated
+if ! grep -q "Orchestrator test feature" "$TEST_DIR/CHANGELOG.md"; then
+    echo "❌ Orchestrator should have updated CHANGELOG"
+    exit 1
+fi
+echo "✅ Orchestrator passed"
+
+# Cleanup
+rm -rf "$TEST_DIR"
+
+echo ""
+echo "========================================="
+echo "✅ All integration tests passed!"
+echo "========================================="

package/skills/documenting/tests/test_changelog.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Tests for CHANGELOG management scripts."""
+
+import pytest
+from pathlib import Path
+from scripts.changelog.validate_changelog import validate_changelog
+from scripts.changelog.add_entry import add_entry, ChangeCategory
+from scripts.changelog.bump_release import bump_release
+from datetime import date
+import tempfile
+
+
+def test_valid_changelog_passes():
+    """Valid Keep a Changelog format should pass validation."""
+    valid_content = """# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New feature description
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+    result = validate_changelog(valid_content)
+    assert result["valid"] is True
+    assert len(result["errors"]) == 0
+
+
+def test_missing_unreleased_section_fails():
+    """CHANGELOG without [Unreleased] section should fail."""
+    invalid_content = """# Changelog
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+    result = validate_changelog(invalid_content)
+    assert result["valid"] is False
+    assert any("Unreleased" in err for err in result["errors"])
+
+
+def test_invalid_semver_fails():
+    """CHANGELOG with invalid semver should fail."""
+    invalid_content = """# Changelog
+
+## [Unreleased]
+
+## [1.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+    result = validate_changelog(invalid_content)
+    assert result["valid"] is False
+    assert any("semantic version" in err.lower() for err in result["errors"])
+
+
+def test_invalid_category_fails():
+    """CHANGELOG with invalid category should fail."""
+    invalid_content = """# Changelog
+
+## [Unreleased]
+
+### InvalidCategory
+- Some change
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+    result = validate_changelog(invalid_content)
+    assert result["valid"] is False
+    assert any("category" in err.lower() for err in result["errors"])
+
+
+def test_add_entry_to_unreleased():
+    """Adding entry should place it under [Unreleased] in correct category."""
+    changelog_content = """# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+
+    result = add_entry(
+        changelog_content,
+        category=ChangeCategory.ADDED,
+        description="New feature X"
+    )
+
+    assert "### Added" in result
+    assert "- New feature X" in result
+    # Should be under [Unreleased], not under [1.0.0]
+    unreleased_section = result.split("## [1.0.0]")[0]
+    assert "- New feature X" in unreleased_section
+
+
+def test_add_entry_creates_category_if_missing():
+    """Adding entry should create category section if it doesn't exist."""
+    changelog_content = """# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-01
+
+### Added
+- Initial release
+"""
+
+    result = add_entry(
+        changelog_content,
+        category=ChangeCategory.FIXED,
+        description="Bug fix Y"
+    )
+
+    assert "### Fixed" in result
+    assert "- Bug fix Y" in result
+
+
+def test_add_entry_maintains_category_order():
+    """Categories should be ordered: Added, Changed, Deprecated, Removed, Fixed, Security."""
+    changelog_content = """# Changelog
+
+## [Unreleased]
+
+### Added
+- Feature A
+
+### Fixed
+- Bug B
+
+## [1.0.0] - 2026-02-01
+"""
+
+    result = add_entry(
+        changelog_content,
+        category=ChangeCategory.CHANGED,
+        description="Change C"
+    )
+
+    # Changed should appear between Added and Fixed
+    lines = result.split('\n')
+    added_idx = next(i for i, line in enumerate(lines) if "### Added" in line)
+    changed_idx = next(i for i, line in enumerate(lines) if "### Changed" in line)
+    fixed_idx = next(i for i, line in enumerate(lines) if "### Fixed" in line)
+
+    assert added_idx < changed_idx < fixed_idx
+
+
+def test_bump_release_moves_unreleased():
+    """Bumping release should move [Unreleased] to [X.Y.Z] - DATE."""
+    changelog_content = """# Changelog
+
+## [Unreleased]
+
+### Added
+- New feature
+
+## [1.0.0] - 2026-01-01
+
+### Added
+- Initial release
+"""
+
+    result = bump_release(changelog_content, "1.1.0")
+
+    # Should have new version section
+    assert "## [1.1.0]" in result
+    assert f"## [1.1.0] - {date.today().strftime('%Y-%m-%d')}" in result
+
+    # New feature should be under 1.1.0 now
+    version_section = result.split("## [1.0.0]")[0]
+    assert "- New feature" in version_section
+
+    # [Unreleased] should be empty
+    unreleased_section = result.split("## [1.1.0]")[0]
+    assert "## [Unreleased]" in unreleased_section
+    # No ### categories under [Unreleased]
+    unreleased_lines = unreleased_section.split("## [Unreleased]")[1].split('\\n')
+    assert not any(line.startswith("###") for line in unreleased_lines)
+
+
+def test_bump_release_validates_semver():
+    """Bumping with invalid semver should raise error."""
+    changelog_content = "## [Unreleased]"
+
+    with pytest.raises(ValueError, match="semantic version"):
+        bump_release(changelog_content, "1.0")

package/skills/documenting/tests/test_drift_detector.py

@@ -0,0 +1,80 @@
+import pytest
+from pathlib import Path
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+from drift_detector import extract_tracks, match_files_to_tracks, format_scan_report
+
+
+MEMORY_WITH_TRACKS = """---
+title: Test SSOT
+version: 1.0.0
+updated: 2026-02-01
+tracks:
+  - "cli/src/**/*.ts"
+  - "hooks/**/*.py"
+---
+
+## Purpose
+Test memory.
+"""
+
+MEMORY_NO_TRACKS = """---
+title: No Tracks
+version: 1.0.0
+updated: 2026-02-01
+---
+
+## Purpose
+No tracking.
+"""
+
+
+def test_extract_tracks_finds_globs():
+    tracks = extract_tracks(MEMORY_WITH_TRACKS)
+    assert tracks == ["cli/src/**/*.ts", "hooks/**/*.py"]
+
+
+def test_extract_tracks_empty_when_missing():
+    tracks = extract_tracks(MEMORY_NO_TRACKS)
+    assert tracks == []
+
+
+def test_match_files_to_tracks_hit():
+    files = ["cli/src/core/diff.ts", "hooks/skill-suggestion.py"]
+    tracks = ["cli/src/**/*.ts", "hooks/**/*.py"]
+    matched = match_files_to_tracks(files, tracks)
+    assert "cli/src/core/diff.ts" in matched
+    assert "hooks/skill-suggestion.py" in matched
+
+
+def test_match_files_to_tracks_miss():
+    files = ["docs/README.md"]
+    tracks = ["cli/src/**/*.ts"]
+    assert match_files_to_tracks(files, tracks) == []
+
+
+def test_format_scan_report_stale():
+    stale = {"my_memory": {"files": ["cli/src/core/diff.ts"], "updated": "2026-02-01"}}
+    report = format_scan_report(stale)
+    assert "my_memory" in report
+    assert "cli/src/core/diff.ts" in report
+
+
+def test_format_scan_report_clean():
+    report = format_scan_report({})
+    assert any(word in report.lower() for word in ["clean", "no stale", "up to date"])
+
+
+def test_match_files_to_tracks_no_false_positive():
+    """A .py file in an unrelated dir must NOT match hooks/**/*.py"""
+    files = ["cli/src/transform.py", "docs/something.py"]
+    tracks = ["hooks/**/*.py"]
+    assert match_files_to_tracks(files, tracks) == []
+
+
+def test_match_files_to_tracks_direct_child():
+    """hooks/**/*.py must match files directly under hooks/ (no subdir)"""
+    files = ["hooks/skill-suggestion.py"]
+    tracks = ["hooks/**/*.py"]
+    matched = match_files_to_tracks(files, tracks)
+    assert "hooks/skill-suggestion.py" in matched

package/skills/documenting/tests/test_orchestrator.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Tests for documentation orchestrator."""
+
+import pytest
+from pathlib import Path
+from scripts.orchestrator import DocumentingOrchestrator, ChangeType
+
+
+def test_orchestrator_routes_to_correct_docs(tmp_path):
+    """Orchestrator should update relevant docs based on change type."""
+    # Setup test project
+    project_root = tmp_path / "test_project"
+    project_root.mkdir()
+
+    changelog = project_root / "CHANGELOG.md"
+    changelog.write_text("""# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-01
+
+### Added
+- Initial release
+""", encoding="utf-8")
+
+    serena_memories = project_root / ".serena" / "memories"
+    serena_memories.mkdir(parents=True)
+
+    orchestrator = DocumentingOrchestrator(project_root)
+
+    result = orchestrator.document_change(
+        change_type=ChangeType.FEATURE,
+        description="Add new API endpoint",
+        details={
+            "scope": "api-endpoints",
+            "category": "backend",
+            "files_changed": ["server.py", "routes/api.py"]
+        }
+    )
+
+    # Should update CHANGELOG
+    assert result["changelog_updated"] is True
+    # Should create/update SSOT
+    assert result["ssot_updated"] is False # Placeholder impl in plan returns False
+    # Should suggest README update
+    assert "readme_suggestions" in result
+
+
+def test_orchestrator_validates_all_docs():
+    """Orchestrator should validate all documentation after updates."""
+    # Test validation integration
+    pass