xtrm-tools 0.7.0 → 0.7.2

package/plugins/xtrm-tools/skills/documenting/scripts/validate_metadata.py

@@ -1,242 +0,0 @@
-#!/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/plugins/xtrm-tools/skills/documenting/templates/CHANGELOG.md.template

@@ -1,13 +0,0 @@
-# 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/plugins/xtrm-tools/skills/documenting/tests/integration_test.sh

@@ -1,70 +0,0 @@
-#!/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/plugins/xtrm-tools/skills/documenting/tests/test_changelog.py

@@ -1,201 +0,0 @@
-#!/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/plugins/xtrm-tools/skills/documenting/tests/test_drift_detector.py

@@ -1,80 +0,0 @@
-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/plugins/xtrm-tools/skills/documenting/tests/test_orchestrator.py

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