xtrm-tools 0.6.0 → 0.7.1

package/plugins/xtrm-tools/skills/sync-docs/scripts/validate_doc.py

@@ -1,365 +0,0 @@
-#!/usr/bin/env python3
-"""
-Validate and generate schema-compliant docs/ files.
-
-Schema for docs/ files:
-  Required: title, scope, category, version, updated
-  Optional: description, source_of_truth_for (glob list), domain (tag list)
-
-Usage:
-  validate_doc.py <file_or_dir>           # validate one file or all *.md in dir
-  validate_doc.py --generate <path>       # generate scaffold + required flags below
-    --title="..."
-    --scope="..."
-    --category="reference|guide|architecture|api"
-    --source-for="glob1,glob2"            # optional
-    --description="..."                   # optional
-"""
-
-import sys
-import re
-import json
-from pathlib import Path
-from datetime import date
-
-# ── Schema ────────────────────────────────────────────────────────────────────
-
-REQUIRED_FIELDS = ["title", "scope", "category", "version", "updated"]
-VALID_CATEGORIES = ["reference", "guide", "architecture", "api", "plan", "overview"]
-
-CATEGORY_DESCRIPTIONS = {
-    "reference": "Look-up table, cheat sheet, or technical specification",
-    "guide": "How-to documentation with step-by-step instructions",
-    "architecture": "System design, component relationships, high-level overview",
-    "api": "API contracts, interfaces, or data schemas",
-    "plan": "Implementation plan or roadmap",
-    "overview": "Summary introduction to a subsystem",
-}
-
-
-# ── Frontmatter helpers ───────────────────────────────────────────────────────
-
-def extract_frontmatter(content: str) -> dict | None:
-    """Parse simple YAML frontmatter without external dependencies.
-
-    Handles scalar values, quoted strings, and list fields (- item syntax).
-    """
-    m = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
-    if not m:
-        return None
-
-    result: dict[str, object] = {}
-    current_key: str | None = None
-    current_list: list[str] | None = None
-
-    for line in m.group(1).splitlines():
-        # List item under current key
-        if current_list is not None and re.match(r"^\s+-\s+", line):
-            current_list.append(re.sub(r"^\s+-\s+", "", line).strip().strip('"\''))
-            continue
-
-        # New key: value line
-        kv = re.match(r'^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)', line)
-        if kv:
-            # Flush previous list
-            if current_key is not None and current_list is not None:
-                result[current_key] = current_list
-
-            current_key = kv.group(1)
-            raw_val = kv.group(2).strip()
-
-            if raw_val == "" or raw_val == ">-":
-                # Value on following lines (list or multiline) — start list
-                current_list = []
-            elif raw_val.startswith("["):
-                # Inline list: [a, b, c]
-                current_list = None
-                inner = raw_val.strip("[]")
-                result[current_key] = [v.strip().strip('"\'') for v in inner.split(",") if v.strip()]
-            else:
-                current_list = None
-                result[current_key] = raw_val.strip('"\'')
-        else:
-            # Continuation line for multiline scalar — ignore for our purposes
-            pass
-
-    # Flush trailing list
-    if current_key is not None and current_list is not None:
-        result[current_key] = current_list
-
-    return result
-
-
-def extract_headings(content: str) -> list[tuple[str, str]]:
-    """Return (heading, first_sentence) for every ## section."""
-    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):
-                ln = lines[j].strip()
-                if ln.startswith("```"):
-                    in_code = not in_code
-                    j += 1
-                    continue
-                if not in_code and ln and not ln.startswith("#"):
-                    summary = ln.split(".")[0].strip()[:120]
-                    break
-                j += 1
-            results.append((heading, summary))
-        i += 1
-    return results
-
-
-def make_anchor(heading: str) -> str:
-    """Generate a GitHub-compatible anchor from a heading string."""
-    anchor = heading.lower()
-    anchor = re.sub(r"\s+", "-", anchor)          # spaces → hyphens
-    anchor = re.sub(r"[^a-z0-9\-]", "", anchor)   # strip non-alphanumeric (except -)
-    anchor = re.sub(r"-+", "-", anchor)            # collapse runs
-    return anchor.strip("-")
-
-
-def generate_index_table(headings: list[tuple[str, str]]) -> str:
-    rows = ["| Section | Summary |", "|---|---|"]
-    for heading, summary in headings:
-        rows.append(f"| [{heading}](#{make_anchor(heading)}) | {summary or '_no summary_'} |")
-    return "\n".join(rows) + "\n"
-
-
-def inject_index(content: str, table: str) -> str:
-    header = "<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->\n"
-    footer = "<!-- END INDEX -->"
-    block = f"{header}{table}{footer}"
-
-    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
-    if existing:
-        return content[: existing.start()] + block + content[existing.end() :]
-
-    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
-
-
-# ── Validation ────────────────────────────────────────────────────────────────
-
-def validate_file(path: Path) -> tuple[bool, list[str], list[str]]:
-    """Returns (passed, errors, warnings)."""
-    errors: list[str] = []
-    warnings: list[str] = []
-
-    if not path.exists():
-        return False, [f"File not found: {path}"], []
-
-    content = path.read_text(encoding="utf-8")
-    fm = extract_frontmatter(content)
-
-    if fm is None:
-        errors.append("Missing or invalid YAML frontmatter (wrap in --- markers)")
-        return False, errors, warnings
-
-    # Required fields
-    for field in REQUIRED_FIELDS:
-        if field not in fm:
-            errors.append(f"Missing required field: {field}")
-
-    # version format
-    if "version" in fm:
-        if not re.match(r"^\d+\.\d+\.\d+$", str(fm["version"])):
-            errors.append(f"version must be semver (x.y.z), got: {fm['version']}")
-
-    # updated format
-    if "updated" in fm:
-        if not re.match(r"^\d{4}-\d{2}-\d{2}", str(fm["updated"])):
-            warnings.append(f"updated should be ISO date (YYYY-MM-DD), got: {fm['updated']}")
-
-    # category valid
-    if "category" in fm and fm["category"] not in VALID_CATEGORIES:
-        errors.append(
-            f"category '{fm['category']}' not valid. Choose from: {', '.join(VALID_CATEGORIES)}"
-        )
-
-    # domain is list
-    if "domain" in fm and not isinstance(fm["domain"], list):
-        errors.append("domain must be a list, e.g. [hooks, claude]")
-
-    # source_of_truth_for and tracks are lists of globs
-    if "source_of_truth_for" in fm and not isinstance(fm["source_of_truth_for"], list):
-        errors.append("source_of_truth_for must be a list of glob patterns")
-    if "tracks" in fm and not isinstance(fm["tracks"], list):
-        errors.append("tracks must be a list of glob patterns")
-
-    # Regenerate INDEX if valid
-    if not errors:
-        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")
-                warnings.append("INDEX regenerated")
-
-    return len(errors) == 0, errors, warnings
-
-
-def validate_directory(docs_dir: Path) -> dict:
-    results = {}
-    for md_file in sorted(docs_dir.glob("*.md")):
-        passed, errors, warnings = validate_file(md_file)
-        results[str(md_file.relative_to(docs_dir.parent))] = {
-            "passed": passed,
-            "errors": errors,
-            "warnings": warnings,
-        }
-    return results
-
-
-def print_file_result(path: str, passed: bool, errors: list[str], warnings: list[str]) -> None:
-    status = "PASS" if passed else "FAIL"
-    mark = "" if passed else ""
-    print(f"\n{mark} {path} [{status}]")
-    for e in errors:
-        print(f"    ERROR: {e}")
-    for w in warnings:
-        print(f"    WARN:  {w}")
-    if passed and not warnings:
-        print("    All checks passed.")
-
-
-# ── Generator ─────────────────────────────────────────────────────────────────
-
-SCAFFOLD_TEMPLATE = """\
----
-title: {title}
-scope: {scope}
-category: {category}
-version: 1.0.0
-updated: {today}
-{source_field}{tracks_field}{description_field}domain: []
----
-
-<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
-<!-- END INDEX -->
-
-# {title}
-
-> {category_desc}
-
-## Overview
-
-_Describe what this document covers._
-
-"""
-
-
-def generate_scaffold(output_path: Path, title: str, scope: str, category: str,
-                      source_for: list[str], description: str) -> None:
-    source_field = ""
-    tracks_field = ""
-    if source_for:
-        items = "\n".join(f'  - "{g}"' for g in source_for)
-        source_field = f"source_of_truth_for:\n{items}\n"
-        # tracks: mirrors source_of_truth_for so drift_detector.py picks up changes
-        tracks_field = f"tracks:\n{items}\n"
-
-    desc_field = f'description: "{description}"\n' if description else ""
-    category_desc = CATEGORY_DESCRIPTIONS.get(category, category)
-
-    content = SCAFFOLD_TEMPLATE.format(
-        title=title,
-        scope=scope,
-        category=category,
-        today=date.today().isoformat(),
-        source_field=source_field,
-        tracks_field=tracks_field,
-        description_field=desc_field,
-        category_desc=category_desc,
-    )
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(content, encoding="utf-8")
-    print(f"Generated: {output_path}")
-
-
-# ── Entry point ───────────────────────────────────────────────────────────────
-
-def main() -> None:
-    args = sys.argv[1:]
-
-    if not args:
-        print("Usage:")
-        print("  validate_doc.py <file_or_dir>")
-        print("  validate_doc.py --generate <path> --title=... --scope=... --category=...")
-        sys.exit(1)
-
-    # Generate mode
-    if "--generate" in args:
-        idx = args.index("--generate")
-        if idx + 1 >= len(args):
-            print("ERROR: --generate requires a path argument")
-            sys.exit(1)
-        output_path = Path(args[idx + 1])
-
-        kw: dict[str, str] = {}
-        source_for: list[str] = []
-        for arg in args:
-            if arg.startswith("--title="):
-                kw["title"] = arg.split("=", 1)[1]
-            elif arg.startswith("--scope="):
-                kw["scope"] = arg.split("=", 1)[1]
-            elif arg.startswith("--category="):
-                kw["category"] = arg.split("=", 1)[1]
-            elif arg.startswith("--source-for="):
-                source_for = [g.strip() for g in arg.split("=", 1)[1].split(",")]
-            elif arg.startswith("--description="):
-                kw["description"] = arg.split("=", 1)[1]
-
-        for req in ["title", "scope", "category"]:
-            if req not in kw:
-                print(f"ERROR: --{req} is required for --generate")
-                sys.exit(1)
-
-        generate_scaffold(
-            output_path,
-            title=kw["title"],
-            scope=kw["scope"],
-            category=kw["category"],
-            source_for=source_for,
-            description=kw.get("description", ""),
-        )
-        sys.exit(0)
-
-    # Validate mode
-    target = Path(args[0])
-    all_passed = True
-
-    if target.is_dir():
-        results = validate_directory(target)
-        for path_str, res in results.items():
-            print_file_result(path_str, res["passed"], res["errors"], res["warnings"])
-            if not res["passed"]:
-                all_passed = False
-        if results:
-            total = len(results)
-            passed = sum(1 for r in results.values() if r["passed"])
-            print(f"\nResult: {passed}/{total} files passed")
-        else:
-            print(f"No .md files found in {target}")
-    else:
-        passed, errors, warnings = validate_file(target)
-        print_file_result(str(target), passed, errors, warnings)
-        all_passed = passed
-
-    sys.exit(0 if all_passed else 1)
-
-
-if __name__ == "__main__":
-    main()

package/plugins/xtrm-tools/skills/sync-docs/scripts/validate_metadata.py

@@ -1,185 +0,0 @@
-#!/usr/bin/env python3
-"""
-Validate docs/ markdown metadata compliance.
-
-Checks frontmatter schema for docs/*.md files and regenerates INDEX tables.
-Runs as a local sync-docs validator (no external skill dependencies).
-"""
-
-import sys
-import re
-from pathlib import Path
-
-try:
-    import yaml
-except ImportError:
-    yaml = None
-
-REQUIRED_FIELDS = ["title", "scope", "category", "version", "updated"]
-VALID_CATEGORIES = {"reference", "guide", "architecture", "api", "plan", "overview"}
-
-
-def extract_headings(content: str) -> list[tuple[str, str]]:
-    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):
-                text = lines[j].strip()
-                if text.startswith("```"):
-                    in_code = not in_code
-                    j += 1
-                    continue
-                if not in_code and text and not text.startswith("#") and not text.startswith("|") and not text.startswith("-"):
-                    summary = text.split(".")[0].strip()[:120]
-                    break
-                j += 1
-            results.append((heading, summary))
-        i += 1
-    return results
-
-
-def generate_index_table(headings: list[tuple[str, str]]) -> str:
-    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).strip("-")
-        rows.append(f"| [{heading}](#{anchor}) | {summary or '_no summary_'} |")
-    return "\n".join(rows) + "\n"
-
-
-def inject_index(content: str, table: str) -> str:
-    header = "<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->\n"
-    footer = "<!-- END INDEX -->"
-    block = f"{header}{table}{footer}"
-
-    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
-    if existing:
-        return content[: existing.start()] + block + content[existing.end() :]
-
-    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
-
-
-def extract_frontmatter(content: str) -> dict:
-    match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
-    if not match:
-        return {}
-
-    raw = match.group(1)
-    if yaml is not None:
-        try:
-            return yaml.safe_load(raw) or {}
-        except Exception:
-            return {}
-
-    data = {}
-    for line in raw.splitlines():
-        if ":" in line:
-            key, value = line.split(":", 1)
-            data[key.strip()] = value.strip().strip('"')
-    return data
-
-
-def validate_semver(value: str) -> bool:
-    return bool(re.match(r"^\d+\.\d+\.\d+$", str(value)))
-
-
-def validate_date(value: str) -> bool:
-    return bool(re.match(r"^\d{4}-\d{2}-\d{2}$", str(value)))
-
-
-def validate_metadata_file(path: Path) -> bool:
-    if not path.exists():
-        print(f"ERROR: File not found: {path}")
-        return False
-
-    content = path.read_text(encoding="utf-8")
-    fm = extract_frontmatter(content)
-
-    errors = []
-    warnings = []
-
-    if not fm:
-        errors.append("Missing or invalid YAML frontmatter")
-    else:
-        missing = [k for k in REQUIRED_FIELDS if k not in fm]
-        if missing:
-            errors.append(f"Missing required fields: {', '.join(missing)}")
-
-        if "category" in fm and fm["category"] not in VALID_CATEGORIES:
-            errors.append(
-                f"Invalid category '{fm['category']}'. Valid: {', '.join(sorted(VALID_CATEGORIES))}"
-            )
-
-        if "version" in fm and not validate_semver(str(fm["version"])):
-            errors.append(f"Invalid version format: {fm['version']} (expected x.y.z)")
-
-        if "updated" in fm and not validate_date(str(fm["updated"])):
-            errors.append(f"Invalid updated format: {fm['updated']} (expected YYYY-MM-DD)")
-
-        if "source_of_truth_for" in fm and not isinstance(fm["source_of_truth_for"], list):
-            warnings.append("source_of_truth_for should be a list")
-
-    print(f"Validating: {path}")
-    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!")
-
-    headings = extract_headings(content)
-    if headings:
-        table = generate_index_table(headings)
-        updated_content = inject_index(content, table)
-        if updated_content != content:
-            path.write_text(updated_content, encoding="utf-8")
-            print("  ✏️  INDEX regenerated.")
-
-    return not errors
-
-
-def iter_targets(target: Path) -> list[Path]:
-    if target.is_dir():
-        return sorted(target.glob("*.md"))
-    return [target]
-
-
-def main() -> None:
-    if len(sys.argv) < 2:
-        print("Usage: validate_metadata.py <docs-file-or-directory>")
-        sys.exit(1)
-
-    target = Path(sys.argv[1])
-    paths = iter_targets(target)
-    if not paths:
-        print(f"No markdown files found at: {target}")
-        sys.exit(1)
-
-    all_ok = True
-    for path in paths:
-        if not validate_metadata_file(path):
-            all_ok = False
-
-    sys.exit(0 if all_ok else 1)
-
-
-if __name__ == "__main__":
-    main()