@sentry/warden 0.22.0 → 0.24.0

package/src/internal-skills/skill-writer/scripts/quick_validate.py

@@ -0,0 +1,158 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml"]
+# ///
+"""
+Quick validation script for Agent Skills.
+
+Validates only mechanical SKILL.md frontmatter and identity requirements.
+Qualitative content, reference depth, routing, and prose structure belong to
+human/agent review, not this script.
+
+Usage:
+    uv run quick_validate.py <skill_directory> [--skill-class <class>] [--strict-depth]
+
+Returns exit code 0 on success, 1 on failure. Outputs JSON with validation results.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+MAX_NAME_LENGTH = 64
+MAX_DESCRIPTION_LENGTH = 1024
+
+SKILL_CLASSES = {
+    "auto",
+    "workflow-process",
+    "integration-documentation",
+    "security-review",
+    "skill-authoring",
+    "generic",
+}
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate agent skill frontmatter and identity fields.",
+    )
+    parser.add_argument("skill_directory")
+    parser.add_argument("--skill-class", choices=sorted(SKILL_CLASSES), default="auto")
+    parser.add_argument("--strict-depth", action="store_true")
+    return parser.parse_args(argv)
+
+
+def validate_skill(
+    skill_path: Path,
+    selected_skill_class: str = "auto",
+    strict_depth: bool = False,
+) -> tuple[bool, list[str], list[str], str]:
+    """Validate a skill directory. Returns (valid, errors, warnings, resolved_skill_class)."""
+    # Keep the flag for CLI compatibility; depth/content checks belong to review.
+    _ = strict_depth
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Check SKILL.md exists.
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, ["SKILL.md not found"], [], "generic"
+
+    content = skill_md.read_text()
+
+    # Check frontmatter exists and is first.
+    if not content.startswith("---"):
+        errors.append("No YAML frontmatter found (file must start with ---)")
+        return False, errors, warnings, "generic"
+
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        errors.append("Invalid frontmatter format (missing closing ---)")
+        return False, errors, warnings, "generic"
+
+    # Parse frontmatter.
+    frontmatter_text = match.group(1)
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            errors.append("Frontmatter must be a YAML mapping")
+            return False, errors, warnings, "generic"
+    except yaml.YAMLError as exc:
+        errors.append(f"Invalid YAML in frontmatter: {exc}")
+        return False, errors, warnings, "generic"
+
+    # Validate frontmatter keys without hardcoding provider-specific optional fields.
+    invalid_keys = [key for key in frontmatter.keys() if not isinstance(key, str) or not key.strip()]
+    if invalid_keys:
+        errors.append("Frontmatter keys must be non-empty strings")
+
+    # Validate name.
+    if "name" not in frontmatter:
+        errors.append("Missing required field: name")
+    else:
+        name = frontmatter["name"]
+        if not isinstance(name, str):
+            errors.append(f"name must be a string, got {type(name).__name__}")
+        else:
+            name = name.strip()
+            if not name:
+                errors.append("name must not be empty")
+            elif len(name) > MAX_NAME_LENGTH:
+                errors.append(f"name is too long ({len(name)} chars, max {MAX_NAME_LENGTH})")
+            elif not re.match(r"^[a-z0-9-]+$", name):
+                errors.append(f"name '{name}' must contain only lowercase letters, digits, and hyphens")
+            elif name.startswith("-") or name.endswith("-"):
+                errors.append(f"name '{name}' must not start or end with a hyphen")
+            elif "--" in name:
+                errors.append(f"name '{name}' must not contain consecutive hyphens")
+            elif name != skill_path.name:
+                errors.append(f"name '{name}' does not match directory name '{skill_path.name}'")
+
+    # Validate description.
+    if "description" not in frontmatter:
+        errors.append("Missing required field: description")
+    else:
+        description = frontmatter["description"]
+        if not isinstance(description, str):
+            errors.append(f"description must be a string, got {type(description).__name__}")
+        else:
+            description = description.strip()
+            if not description:
+                errors.append("description must not be empty")
+            elif len(description) > MAX_DESCRIPTION_LENGTH:
+                errors.append(f"description is too long ({len(description)} chars, max {MAX_DESCRIPTION_LENGTH})")
+
+    resolved_skill_class = selected_skill_class if selected_skill_class != "auto" else "generic"
+
+    return len(errors) == 0, errors, warnings, resolved_skill_class
+
+
+def main() -> None:
+    args = parse_args(sys.argv[1:])
+    skill_path = Path(args.skill_directory).resolve()
+    if not skill_path.is_dir():
+        print(json.dumps({"valid": False, "errors": [f"Not a directory: {skill_path}"]}))
+        sys.exit(1)
+
+    valid, errors, warnings, resolved_skill_class = validate_skill(
+        skill_path,
+        selected_skill_class=args.skill_class,
+        strict_depth=args.strict_depth,
+    )
+    result = {
+        "valid": valid,
+        "skill_class": resolved_skill_class,
+        "strict_depth": args.strict_depth,
+        "errors": errors,
+        "warnings": warnings,
+    }
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if valid else 1)
+
+
+if __name__ == "__main__":
+    main()

package/src/internal-skills/skill-writer/scripts/quick_validate_test.py

@@ -0,0 +1,79 @@
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).with_name("quick_validate.py")
+SPEC = importlib.util.spec_from_file_location("quick_validate", SCRIPT_PATH)
+assert SPEC is not None
+quick_validate = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(quick_validate)
+
+
+class QuickValidateTest(unittest.TestCase):
+    def test_ignores_markdown_content_and_supporting_files(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            skill_path = Path(temp_dir) / "example-skill"
+            skill_path.mkdir()
+            (skill_path / "SKILL.md").write_text(
+                """---
+name: example-skill
+description: I can review <example> content.
+---
+
+This intentionally references missing content that review may care about:
+
+- references/missing.md
+- scripts/missing.py
+- SOURCES.md
+
+/Users/example/private/path should not be script-validated.
+""",
+                encoding="utf-8",
+            )
+            (skill_path / "SPEC.md").write_text(
+                """# Example Skill Spec
+
+## Evaluation
+
+Run the local checks for this skill.
+""",
+                encoding="utf-8",
+            )
+
+            valid, errors, warnings, _skill_class = quick_validate.validate_skill(
+                skill_path,
+                selected_skill_class="integration-documentation",
+                strict_depth=True,
+            )
+
+        self.assertTrue(valid)
+        self.assertEqual(errors, [])
+        self.assertEqual(warnings, [])
+
+    def test_rejects_invalid_frontmatter_yaml(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            skill_path = Path(temp_dir) / "example-skill"
+            skill_path.mkdir()
+            (skill_path / "SKILL.md").write_text(
+                """---
+name: [example-skill
+description: Use when reviewing example code.
+---
+
+Review example code.
+""",
+                encoding="utf-8",
+            )
+
+            valid, errors, warnings, _skill_class = quick_validate.validate_skill(skill_path)
+
+        self.assertFalse(valid)
+        self.assertEqual(warnings, [])
+        self.assertTrue(any("Invalid YAML in frontmatter" in message for message in errors), errors)
+
+
+if __name__ == "__main__":
+    unittest.main()