validate.py

#!/usr/bin/env python3
"""Structural validation for the prd-engine plugin.

Three checks, all static:

1. .claude-plugin/plugin.json and .claude-plugin/marketplace.json parse as JSON
   and carry the fields Claude Code needs to resolve `prd-engine@addiplus`.
2. Every agents/**/*.md and skills/**/SKILL.md opens with a YAML frontmatter
   block that parses and declares a non-empty `name` and `description`.
3. No .md or .json file contains an em dash, en dash, or related long dash.
   House style is plain ASCII punctuation.

Nothing here executes the pipeline or calls a model. It only proves the
manifests and agent definitions are well formed.

Dependencies: Python standard library plus PyYAML.
"""

import json
import re
import sys
from pathlib import Path

import yaml

ROOT = Path(__file__).resolve().parents[2]

# U+2012 figure dash through U+2015 horizontal bar, plus U+2212 minus sign.
# Built from code points so this file stays pure ASCII and never trips its own check.
DASH_NAMES = {
    chr(0x2012): "U+2012 figure dash",
    chr(0x2013): "U+2013 en dash",
    chr(0x2014): "U+2014 em dash",
    chr(0x2015): "U+2015 horizontal bar",
    chr(0x2212): "U+2212 minus sign",
}
DASH_PATTERN = re.compile("[" + "".join(DASH_NAMES) + "]")

SKIP_DIRS = {".git"}
DASH_SUFFIXES = {".md", ".json"}

# utf-8-sig so a stray byte order mark from a Windows editor is not reported as
# a parse failure or as a broken frontmatter fence.
ENCODING = "utf-8-sig"

errors = []
counts = {"manifests": 0, "definitions": 0, "scanned": 0}


def rel(path):
    return path.relative_to(ROOT).as_posix()


def fail(path, message):
    errors.append("{}: {}".format(rel(path), message))


def require_text(path, container, field, where):
    value = container.get(field)
    if not isinstance(value, str) or not value.strip():
        fail(path, "{} is missing a non-empty '{}'".format(where, field))
        return None
    return value


def load_json(relpath):
    path = ROOT / relpath
    if not path.is_file():
        errors.append("{}: file not found".format(relpath))
        return None, None
    try:
        data = json.loads(path.read_text(encoding=ENCODING))
    except json.JSONDecodeError as exc:
        fail(path, "does not parse as JSON ({})".format(exc))
        return path, None
    if not isinstance(data, dict):
        fail(path, "top level value must be a JSON object")
        return path, None
    counts["manifests"] += 1
    return path, data


def check_manifests():
    """Validate both plugin manifests and the link between them."""
    plugin_path, plugin = load_json(".claude-plugin/plugin.json")
    market_path, market = load_json(".claude-plugin/marketplace.json")

    plugin_name = None
    if plugin is not None:
        plugin_name = require_text(plugin_path, plugin, "name", "plugin.json")
        require_text(plugin_path, plugin, "version", "plugin.json")
        require_text(plugin_path, plugin, "description", "plugin.json")

    if market is None:
        return

    require_text(market_path, market, "name", "marketplace.json")

    entries = market.get("plugins")
    if not isinstance(entries, list) or not entries:
        fail(market_path, "'plugins' must be a non-empty array")
        return
    first = entries[0]
    if not isinstance(first, dict):
        fail(market_path, "plugins[0] must be a JSON object")
        return

    entry_name = require_text(market_path, first, "name", "plugins[0]")
    require_text(market_path, first, "source", "plugins[0]")

    if plugin_name and entry_name and plugin_name != entry_name:
        fail(
            market_path,
            "plugins[0].name '{}' does not match plugin.json name '{}', so the "
            "documented install would not resolve".format(entry_name, plugin_name),
        )


def split_frontmatter(text):
    """Return the YAML body of a leading --- fenced block, or None."""
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None
    for index in range(1, len(lines)):
        if lines[index].strip() == "---":
            return "\n".join(lines[1:index])
    return None


def check_definition(path):
    body = split_frontmatter(path.read_text(encoding=ENCODING))
    if body is None:
        fail(path, "does not open with a '---' fenced YAML frontmatter block")
        return
    try:
        meta = yaml.safe_load(body)
    except yaml.YAMLError as exc:
        fail(path, "frontmatter is not valid YAML ({})".format(exc))
        return
    if not isinstance(meta, dict):
        fail(path, "frontmatter must parse to a mapping of keys to values")
        return
    require_text(path, meta, "name", "frontmatter")
    require_text(path, meta, "description", "frontmatter")
    counts["definitions"] += 1


def check_definitions():
    paths = sorted(ROOT.glob("agents/**/*.md")) + sorted(ROOT.glob("skills/**/SKILL.md"))
    if not paths:
        errors.append("no agent definitions or SKILL.md files were found to validate")
        return
    for path in paths:
        check_definition(path)


def iter_scannable():
    for path in sorted(ROOT.rglob("*")):
        if not path.is_file() or path.suffix not in DASH_SUFFIXES:
            continue
        if SKIP_DIRS.intersection(path.relative_to(ROOT).parts):
            continue
        yield path


def check_dashes():
    for path in iter_scannable():
        counts["scanned"] += 1
        for number, line in enumerate(path.read_text(encoding=ENCODING).splitlines(), 1):
            for match in DASH_PATTERN.finditer(line):
                fail(
                    path,
                    "line {} column {} contains {}, use ASCII punctuation".format(
                        number, match.start() + 1, DASH_NAMES[match.group()]
                    ),
                )


def main():
    check_manifests()
    check_definitions()
    check_dashes()

    print("manifests parsed:       {}".format(counts["manifests"]))
    print("definitions validated:  {}".format(counts["definitions"]))
    print("files scanned for dash: {}".format(counts["scanned"]))

    if errors:
        print("\n{} problem(s) found:".format(len(errors)))
        for item in errors:
            print("  - {}".format(item))
        return 1

    print("\nOK: manifests and agent definitions are well formed.")
    return 0


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