wordle/.claude/skills/bmad-module-builder/scripts/validate-module.py

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# ///
"""Validate a BMad module's structure and help CSV integrity.

Supports two module types:
- Multi-skill modules with a dedicated setup skill (*-setup directory)
- Standalone single-skill modules with self-registration (assets/module-setup.md)

Performs deterministic structural checks:
- Required files exist (setup skill or standalone structure)
- All skill folders have at least one capability entry in the CSV
- No orphan CSV entries pointing to nonexistent skills
- Menu codes are unique
- preceded-by/followed-by references point to real capability entries
- Required module.yaml fields are present
- CSV column count is consistent
"""

import argparse
import csv
import json
import sys
from io import StringIO
from pathlib import Path

REQUIRED_YAML_FIELDS = {"code", "name", "description"}
CSV_HEADER = [
    "module", "skill", "display-name", "menu-code", "description",
    "action", "args", "phase", "preceded-by", "followed-by", "required",
    "output-location", "outputs",
]


def find_setup_skill(module_dir: Path) -> Path | None:
    """Find the setup skill folder (*-setup)."""
    for d in module_dir.iterdir():
        if d.is_dir() and d.name.endswith("-setup"):
            return d
    return None


def find_skill_folders(module_dir: Path, exclude_name: str = "") -> list[str]:
    """Find all skill folders (directories with SKILL.md), optionally excluding one."""
    skills = []
    for d in module_dir.iterdir():
        if d.is_dir() and d.name != exclude_name and (d / "SKILL.md").is_file():
            skills.append(d.name)
    return sorted(skills)


def detect_standalone_module(module_dir: Path) -> Path | None:
    """Detect a standalone module: a single skill folder with assets/module.yaml.

    Works whether ``module_dir`` is the parent folder that contains the skill, or
    the standalone skill directory itself (the path a user is most likely to hand
    over for a single-skill module).
    """
    # Given the skill directory directly.
    if (module_dir / "SKILL.md").is_file() and (module_dir / "assets" / "module.yaml").is_file():
        return module_dir
    # Given the parent folder containing exactly one skill.
    skill_dirs = [
        d for d in module_dir.iterdir()
        if d.is_dir() and (d / "SKILL.md").is_file()
    ]
    if len(skill_dirs) == 1:
        candidate = skill_dirs[0]
        if (candidate / "assets" / "module.yaml").is_file():
            return candidate
    return None


def parse_yaml_minimal(text: str) -> dict[str, str]:
    """Parse top-level YAML key-value pairs (no nested structures)."""
    result = {}
    for line in text.splitlines():
        line = line.strip()
        if ":" in line and not line.startswith("#") and not line.startswith("-"):
            key, _, value = line.partition(":")
            key = key.strip()
            value = value.strip().strip('"').strip("'")
            if value and not value.startswith(">"):
                result[key] = value
    return result


def parse_csv_rows(csv_text: str) -> tuple[list[str], list[dict[str, str]], list[int]]:
    """Parse CSV text into (header, row dicts, raw column count per data row).

    ``restval=""`` fills missing trailing fields in a short row with empty strings
    instead of ``None``, so downstream ``.strip()`` calls stay safe on malformed
    rows. DictReader pads short rows to the header width, so ``len(row)`` cannot
    reveal a field shortfall; the raw per-row column counts from ``csv.reader``
    (blank lines skipped, to stay aligned with DictReader) are returned separately
    for the column-count consistency check.
    """
    reader = csv.DictReader(StringIO(csv_text), restval="")
    header = reader.fieldnames or []
    rows = list(reader)
    raw_rows = list(csv.reader(StringIO(csv_text)))
    col_counts = [len(r) for r in raw_rows[1:] if r != []]
    return header, rows, col_counts


def validate(module_dir: Path, verbose: bool = False) -> dict:
    """Run all structural validations. Returns JSON-serializable result."""
    findings: list[dict] = []
    info: dict = {}

    def finding(severity: str, category: str, message: str, detail: str = ""):
        findings.append({
            "severity": severity,
            "category": category,
            "message": message,
            "detail": detail,
        })

    # 1. Find setup skill or detect standalone module
    setup_dir = find_setup_skill(module_dir)
    standalone_dir = None

    if not setup_dir:
        standalone_dir = detect_standalone_module(module_dir)
        if not standalone_dir:
            finding("critical", "structure",
                    "No setup skill found (*-setup directory) and no standalone module detected")
            return {"status": "fail", "findings": findings, "info": info}

    # Branch: standalone vs multi-skill
    if standalone_dir:
        info["standalone"] = True
        info["skill_dir"] = standalone_dir.name
        skill_dir = standalone_dir

        # 2s. Check required files for standalone module
        required_files = {
            "assets/module.yaml": skill_dir / "assets" / "module.yaml",
            "assets/module-help.csv": skill_dir / "assets" / "module-help.csv",
            "assets/module-setup.md": skill_dir / "assets" / "module-setup.md",
        }
        # Merge scripts: accept either the dash form the scaffolder emits
        # (merge-config.py) or the importable underscore form (merge_config.py).
        # Both are valid — a module may rename them to be importable from
        # module-setup.md without that being a structural defect.
        required_any = {
            "scripts/merge-config.py (or merge_config.py)": [
                skill_dir / "scripts" / "merge-config.py",
                skill_dir / "scripts" / "merge_config.py",
            ],
            "scripts/merge-help-csv.py (or merge_help_csv.py)": [
                skill_dir / "scripts" / "merge-help-csv.py",
                skill_dir / "scripts" / "merge_help_csv.py",
            ],
        }
        ok = True
        for label, path in required_files.items():
            if not path.is_file():
                finding("critical", "structure", f"Missing required file: {label}")
                ok = False
        for label, candidates in required_any.items():
            if not any(p.is_file() for p in candidates):
                finding("critical", "structure", f"Missing required file: {label}")
                ok = False

        if not ok:
            return {"status": "fail", "findings": findings, "info": info}

        yaml_dir = skill_dir
        csv_dir = skill_dir
    else:
        info["setup_skill"] = setup_dir.name

        # 2. Check required files in setup skill
        required_files = {
            "SKILL.md": setup_dir / "SKILL.md",
            "assets/module.yaml": setup_dir / "assets" / "module.yaml",
            "assets/module-help.csv": setup_dir / "assets" / "module-help.csv",
        }
        for label, path in required_files.items():
            if not path.is_file():
                finding("critical", "structure", f"Missing required file: {label}")

        if not all(p.is_file() for p in required_files.values()):
            return {"status": "fail", "findings": findings, "info": info}

        yaml_dir = setup_dir
        csv_dir = setup_dir

    # 3. Validate module.yaml
    yaml_text = (yaml_dir / "assets" / "module.yaml").read_text(encoding="utf-8")
    yaml_data = parse_yaml_minimal(yaml_text)
    info["module_code"] = yaml_data.get("code", "")
    info["module_name"] = yaml_data.get("name", "")

    for field in REQUIRED_YAML_FIELDS:
        if not yaml_data.get(field):
            finding("high", "yaml", f"module.yaml missing or empty required field: {field}")

    # 4. Parse and validate CSV
    csv_text = (csv_dir / "assets" / "module-help.csv").read_text(encoding="utf-8")
    header, rows, col_counts = parse_csv_rows(csv_text)

    # Check header
    if header != CSV_HEADER:
        missing = set(CSV_HEADER) - set(header)
        extra = set(header) - set(CSV_HEADER)
        detail_parts = []
        if missing:
            detail_parts.append(f"missing: {', '.join(sorted(missing))}")
        if extra:
            detail_parts.append(f"extra: {', '.join(sorted(extra))}")
        finding("high", "csv-header", f"CSV header mismatch: {'; '.join(detail_parts)}")

    if not rows:
        finding("high", "csv-empty", "module-help.csv has no capability entries")
        return {"status": "fail", "findings": findings, "info": info}

    info["csv_entries"] = len(rows)

    # 5. Check column count consistency (using raw field counts: DictReader pads
    #    short rows to the header width, so len(row) alone can't detect a shortfall)
    expected_cols = len(CSV_HEADER)
    for i, (row, n_cols) in enumerate(zip(rows, col_counts)):
        if n_cols != expected_cols:
            finding("medium", "csv-columns", f"Row {i + 2} has {n_cols} columns, expected {expected_cols}",
                    f"skill={row.get('skill', '?')}")

    # 6. Collect skills from CSV and filesystem
    csv_skills = {row.get("skill", "") for row in rows}
    if standalone_dir:
        # The only valid skill is the standalone skill itself, whether we were
        # handed the module's parent folder or the skill directory directly.
        skill_folders = [standalone_dir.name]
    else:
        skill_folders = find_skill_folders(module_dir, setup_dir.name)
    info["skill_folders"] = skill_folders
    info["csv_skills"] = sorted(csv_skills)

    # 7. Skills without CSV entries
    for skill in skill_folders:
        if skill not in csv_skills:
            finding("high", "missing-entry", f"Skill '{skill}' has no capability entries in the CSV")

    # 8. Orphan CSV entries
    setup_name = setup_dir.name if setup_dir else ""
    for skill in csv_skills:
        if skill in skill_folders or skill == setup_name:
            continue
        # For a standalone module, skill_folders already enumerates every valid
        # skill, so any other CSV skill is an orphan — never look at the parent
        # folder (which may hold unrelated sibling skills when validating a skill
        # dir directly). For a multi-skill module, re-check the filesystem: the
        # setup skill lives alongside the others and is excluded from skill_folders.
        if standalone_dir or not (module_dir / skill / "SKILL.md").is_file():
            finding("high", "orphan-entry", f"CSV references skill '{skill}' which does not exist in the module folder")

    # 9. Unique menu codes
    menu_codes: dict[str, list[str]] = {}
    for row in rows:
        code = row.get("menu-code", "").strip()
        if code:
            menu_codes.setdefault(code, []).append(row.get("display-name", "?"))

    for code, names in menu_codes.items():
        if len(names) > 1:
            finding("high", "duplicate-menu-code", f"Menu code '{code}' used by multiple entries: {', '.join(names)}")

    # 10. preceded-by/followed-by reference validation
    # Build set of valid capability references (skill:action)
    valid_refs = set()
    for row in rows:
        skill = row.get("skill", "").strip()
        action = row.get("action", "").strip()
        if skill and action:
            valid_refs.add(f"{skill}:{action}")

    for row in rows:
        display = row.get("display-name", "?")
        for field in ("preceded-by", "followed-by"):
            value = row.get(field, "").strip()
            if not value:
                continue
            # Can be comma-separated
            for ref in value.split(","):
                ref = ref.strip()
                if not ref:
                    continue
                # A colon-less ref is a cross-module positional reference (a bare
                # sibling-module skill name, e.g. "bmad-sprint-planning"). Other
                # installed modules aren't visible here, so it can't be resolved
                # and isn't a defect — only validate intra-module skill:action refs.
                if ":" not in ref:
                    continue
                if ref not in valid_refs:
                    finding("medium", "invalid-ref",
                            f"'{display}' {field} references '{ref}' which is not a valid capability",
                            "Expected format: skill-name:action-name")

    # 11. Required fields in each row
    for row in rows:
        display = row.get("display-name", "?")
        for field in ("skill", "display-name", "menu-code", "description"):
            if not row.get(field, "").strip():
                finding("high", "missing-field", f"Entry '{display}' is missing required field: {field}")

    # Summary
    severity_counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
    for f in findings:
        severity_counts[f["severity"]] = severity_counts.get(f["severity"], 0) + 1

    status = "pass" if severity_counts["critical"] == 0 and severity_counts["high"] == 0 else "fail"

    return {
        "status": status,
        "info": info,
        "findings": findings,
        "summary": {
            "total_findings": len(findings),
            "by_severity": severity_counts,
        },
    }


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Validate a BMad module's setup skill structure and help CSV integrity"
    )
    parser.add_argument(
        "module_dir",
        help="Path to the module's skills folder (containing the setup skill and other skills)",
    )
    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
    args = parser.parse_args()

    module_path = Path(args.module_dir)
    if not module_path.is_dir():
        print(json.dumps({"status": "error", "message": f"Not a directory: {module_path}"}))
        return 2

    result = validate(module_path, verbose=args.verbose)
    print(json.dumps(result, indent=2))
    return 0 if result["status"] == "pass" else 1


if __name__ == "__main__":
    sys.exit(main())