@pennyfarthing/core 10.0.2 → 10.0.3

package/pennyfarthing_scripts/migration/skill.py

@@ -0,0 +1,188 @@
+"""
+Skill file auditing tools.
+
+Audits skill files for conformance to guides/skill-schema.md.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# Tag requirements
+REQUIRED_TAGS = ["run", "output"]
+RECOMMENDED_TAGS = ["args", "example", "when"]
+OPTIONAL_TAGS = ["critical", "agent-activation"]
+
+
+@dataclass
+class SkillAuditResult:
+    """Result of auditing a skill file."""
+
+    skill_name: str
+    file_path: Path
+    has_frontmatter: bool = False
+    missing_required: list[str] = field(default_factory=list)
+    missing_recommended: list[str] = field(default_factory=list)
+    present_tags: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if skill passes validation (has all required)."""
+        return len(self.missing_required) == 0
+
+    @property
+    def status(self) -> str:
+        """Get status string."""
+        if not self.is_valid:
+            return "NEEDS UPDATE"
+        if self.missing_recommended:
+            return "PARTIAL"
+        return "OK"
+
+
+def _has_frontmatter(content: str) -> bool:
+    """Check if file has YAML frontmatter."""
+    return content.startswith("---\n")
+
+
+def _has_tag(content: str, tag: str) -> bool:
+    """Check if content contains a specific XML tag."""
+    return f"<{tag}>" in content or f"<{tag} " in content
+
+
+def _get_present_tags(content: str) -> list[str]:
+    """Get list of XML tags present in content."""
+    # Find all opening tags
+    tags = re.findall(r"<([a-z][a-z0-9-]*)(?:\s|>)", content)
+    return list(set(tags))
+
+
+def audit_skill_file(file_path: Path) -> SkillAuditResult:
+    """Audit a single skill file.
+
+    Args:
+        file_path: Path to SKILL.md file
+
+    Returns:
+        SkillAuditResult with findings
+    """
+    skill_name = file_path.parent.name
+    content = file_path.read_text()
+
+    result = SkillAuditResult(skill_name=skill_name, file_path=file_path)
+
+    # Check frontmatter
+    result.has_frontmatter = _has_frontmatter(content)
+    if not result.has_frontmatter:
+        result.missing_required.append("frontmatter")
+
+    # Check required tags
+    for tag in REQUIRED_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+        else:
+            result.missing_required.append(tag)
+
+    # Check recommended tags
+    for tag in RECOMMENDED_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+        else:
+            result.missing_recommended.append(tag)
+
+    # Check optional tags (just track presence)
+    for tag in OPTIONAL_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+
+    return result
+
+
+def find_skill_files(root: Path) -> list[Path]:
+    """Find all skill files in a project.
+
+    Args:
+        root: Project root directory
+
+    Returns:
+        List of SKILL.md file paths
+    """
+    # Try multiple locations
+    skill_dirs = [
+        root / ".pennyfarthing" / "skills",
+        root / "pennyfarthing" / "pennyfarthing-dist" / "skills",
+        root / "pennyfarthing-dist" / "skills",
+    ]
+
+    for skills_dir in skill_dirs:
+        if skills_dir.exists():
+            return sorted(skills_dir.glob("*/SKILL.md"))
+
+    return []
+
+
+def audit_skills(
+    root: Path, *, skill_name: str | None = None
+) -> dict[str, SkillAuditResult | list[SkillAuditResult] | dict]:
+    """Audit skill files in a project.
+
+    Args:
+        root: Project root directory
+        skill_name: Optional specific skill to audit
+
+    Returns:
+        Dict with 'results', 'summary' keys
+    """
+    if skill_name:
+        # Find specific skill
+        skill_dirs = [
+            root / ".pennyfarthing" / "skills" / skill_name / "SKILL.md",
+            root / "pennyfarthing" / "pennyfarthing-dist" / "skills" / skill_name / "SKILL.md",
+            root / "pennyfarthing-dist" / "skills" / skill_name / "SKILL.md",
+        ]
+
+        for skill_path in skill_dirs:
+            if skill_path.exists():
+                result = audit_skill_file(skill_path)
+                return {
+                    "results": [result],
+                    "summary": {
+                        "total": 1,
+                        "valid": 1 if result.is_valid else 0,
+                        "partial": 1 if result.status == "PARTIAL" else 0,
+                        "needs_update": 1 if not result.is_valid else 0,
+                        "missing_required": len(result.missing_required),
+                        "missing_recommended": len(result.missing_recommended),
+                    },
+                }
+
+        return {
+            "results": [],
+            "summary": {"total": 0, "error": f"Skill not found: {skill_name}"},
+        }
+
+    # Audit all skills
+    skill_files = find_skill_files(root)
+    results = [audit_skill_file(f) for f in skill_files]
+
+    # Calculate summary
+    valid = sum(1 for r in results if r.is_valid and not r.missing_recommended)
+    partial = sum(1 for r in results if r.is_valid and r.missing_recommended)
+    needs_update = sum(1 for r in results if not r.is_valid)
+    total_missing_required = sum(len(r.missing_required) for r in results)
+    total_missing_recommended = sum(len(r.missing_recommended) for r in results)
+
+    return {
+        "results": results,
+        "summary": {
+            "total": len(results),
+            "valid": valid,
+            "partial": partial,
+            "needs_update": needs_update,
+            "missing_required": total_missing_required,
+            "missing_recommended": total_missing_recommended,
+        },
+    }

package/pennyfarthing_scripts/migration/step.py

@@ -0,0 +1,229 @@
+"""
+Workflow step file auditing tools.
+
+Audits workflow step files for conformance to guides/workflow-step-schema.md.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# Tag requirements
+REQUIRED_TAGS = ["step-meta", "purpose", "instructions", "output"]
+RECOMMENDED_TAGS = ["prerequisites", "actions", "collaboration-menu", "next-step"]
+OPTIONAL_TAGS = ["gate"]
+
+# step-meta required fields
+STEP_META_FIELDS = ["number", "name", "gate"]
+
+
+@dataclass
+class StepAuditResult:
+    """Result of auditing a workflow step file."""
+
+    workflow_name: str
+    step_name: str
+    file_path: Path
+    missing_required: list[str] = field(default_factory=list)
+    missing_recommended: list[str] = field(default_factory=list)
+    missing_meta_fields: list[str] = field(default_factory=list)
+    present_tags: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if step passes validation (has all required)."""
+        return len(self.missing_required) == 0 and len(self.missing_meta_fields) == 0
+
+    @property
+    def status(self) -> str:
+        """Get status string."""
+        if not self.is_valid:
+            return "NEEDS UPDATE"
+        if self.missing_recommended:
+            return "PARTIAL"
+        return "OK"
+
+
+def _has_tag(content: str, tag: str) -> bool:
+    """Check if content contains a specific XML tag."""
+    return f"<{tag}>" in content or f"<{tag} " in content
+
+
+def _check_step_meta_fields(content: str) -> list[str]:
+    """Check which step-meta fields are missing."""
+    # Extract step-meta section
+    meta_match = re.search(r"<step-meta>(.+?)</step-meta>", content, re.DOTALL)
+    if not meta_match:
+        return STEP_META_FIELDS.copy()
+
+    meta_content = meta_match.group(1)
+    missing = []
+
+    for field_name in STEP_META_FIELDS:
+        if f"{field_name}:" not in meta_content:
+            missing.append(field_name)
+
+    return missing
+
+
+def audit_step_file(file_path: Path) -> StepAuditResult:
+    """Audit a single workflow step file.
+
+    Args:
+        file_path: Path to step-*.md file
+
+    Returns:
+        StepAuditResult with findings
+    """
+    # Determine workflow name from path
+    # Could be workflows/{name}/steps/step-*.md
+    # or workflows/{name}/steps-{mode}/step-*.md
+    steps_dir = file_path.parent
+    workflow_dir = steps_dir.parent
+    workflow_name = workflow_dir.name
+    step_name = file_path.stem
+
+    content = file_path.read_text()
+
+    result = StepAuditResult(
+        workflow_name=workflow_name, step_name=step_name, file_path=file_path
+    )
+
+    # Check required tags
+    for tag in REQUIRED_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+        else:
+            result.missing_required.append(tag)
+
+    # Check step-meta fields if tag exists
+    if "step-meta" in result.present_tags:
+        result.missing_meta_fields = _check_step_meta_fields(content)
+        if result.missing_meta_fields:
+            # Add to required as "step-meta fields: x, y"
+            missing_str = ", ".join(result.missing_meta_fields)
+            result.missing_required.append(f"step-meta fields ({missing_str})")
+
+    # Check recommended tags
+    for tag in RECOMMENDED_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+        else:
+            result.missing_recommended.append(tag)
+
+    # Check optional tags (just track presence)
+    for tag in OPTIONAL_TAGS:
+        if _has_tag(content, tag):
+            result.present_tags.append(tag)
+
+    return result
+
+
+def find_step_files(root: Path) -> list[Path]:
+    """Find all workflow step files in a project.
+
+    Args:
+        root: Project root directory
+
+    Returns:
+        List of step-*.md file paths
+    """
+    # Try multiple locations
+    workflow_dirs = [
+        root / ".pennyfarthing" / "workflows",
+        root / "pennyfarthing" / "pennyfarthing-dist" / "workflows",
+        root / "pennyfarthing-dist" / "workflows",
+    ]
+
+    step_files = []
+
+    for workflows_dir in workflow_dirs:
+        if workflows_dir.exists():
+            # Find step files in steps/ and steps-*/ directories
+            for workflow_dir in workflows_dir.iterdir():
+                if not workflow_dir.is_dir():
+                    continue
+
+                for steps_dir in workflow_dir.iterdir():
+                    if steps_dir.is_dir() and steps_dir.name.startswith("steps"):
+                        step_files.extend(steps_dir.glob("step-*.md"))
+
+            break  # Only use first found workflows dir
+
+    return sorted(step_files)
+
+
+@dataclass
+class WorkflowAuditResult:
+    """Result of auditing a workflow's step files."""
+
+    workflow_name: str
+    step_results: list[StepAuditResult] = field(default_factory=list)
+
+    @property
+    def total_steps(self) -> int:
+        return len(self.step_results)
+
+    @property
+    def valid_steps(self) -> int:
+        return sum(1 for r in self.step_results if r.is_valid)
+
+    @property
+    def needs_update(self) -> int:
+        return sum(1 for r in self.step_results if not r.is_valid)
+
+
+def audit_workflow_steps(
+    root: Path, *, workflow_name: str | None = None
+) -> dict[str, list | dict]:
+    """Audit workflow step files in a project.
+
+    Args:
+        root: Project root directory
+        workflow_name: Optional specific workflow to audit
+
+    Returns:
+        Dict with 'workflows', 'summary' keys
+    """
+    step_files = find_step_files(root)
+
+    # Group by workflow
+    workflows: dict[str, WorkflowAuditResult] = {}
+
+    for file_path in step_files:
+        result = audit_step_file(file_path)
+
+        if workflow_name and result.workflow_name != workflow_name:
+            continue
+
+        if result.workflow_name not in workflows:
+            workflows[result.workflow_name] = WorkflowAuditResult(
+                workflow_name=result.workflow_name
+            )
+
+        workflows[result.workflow_name].step_results.append(result)
+
+    # Calculate summary
+    workflow_list = list(workflows.values())
+    total_files = sum(w.total_steps for w in workflow_list)
+    total_valid = sum(w.valid_steps for w in workflow_list)
+    total_needs_update = sum(w.needs_update for w in workflow_list)
+
+    all_results = [r for w in workflow_list for r in w.step_results]
+    total_missing_required = sum(len(r.missing_required) for r in all_results)
+    total_missing_recommended = sum(len(r.missing_recommended) for r in all_results)
+
+    return {
+        "workflows": workflow_list,
+        "summary": {
+            "total_workflows": len(workflow_list),
+            "total_files": total_files,
+            "valid": total_valid,
+            "needs_update": total_needs_update,
+            "missing_required": total_missing_required,
+            "missing_recommended": total_missing_recommended,
+        },
+    }

package/pennyfarthing_scripts/migration/validate.py

@@ -0,0 +1,282 @@
+"""
+XML schema validation for Pennyfarthing files.
+
+Validates files against their respective schemas:
+- Session files -> guides/session-schema.md
+- Skill files -> guides/skill-schema.md
+- Workflow step files -> guides/workflow-step-schema.md
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from pennyfarthing_scripts.migration.session import (
+    find_session_files,
+    is_xml_format,
+)
+from pennyfarthing_scripts.migration.skill import (
+    RECOMMENDED_TAGS as SKILL_RECOMMENDED,
+    REQUIRED_TAGS as SKILL_REQUIRED,
+    find_skill_files,
+)
+from pennyfarthing_scripts.migration.step import (
+    RECOMMENDED_TAGS as STEP_RECOMMENDED,
+    REQUIRED_TAGS as STEP_REQUIRED,
+    STEP_META_FIELDS,
+    find_step_files,
+)
+
+
+@dataclass
+class ValidationResult:
+    """Result of validating a single file."""
+
+    file_path: Path
+    file_type: Literal["session", "skill", "step"]
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.errors) == 0
+
+    @property
+    def status(self) -> str:
+        if self.errors:
+            return "ERROR"
+        if self.warnings:
+            return "WARN"
+        return "PASS"
+
+
+def _has_tag(content: str, tag: str) -> bool:
+    """Check if content contains a specific XML tag."""
+    return f"<{tag}>" in content or f"<{tag} " in content
+
+
+def validate_session_file(file_path: Path) -> ValidationResult:
+    """Validate a session file against the schema.
+
+    Args:
+        file_path: Path to session file
+
+    Returns:
+        ValidationResult with errors/warnings
+    """
+    result = ValidationResult(file_path=file_path, file_type="session")
+    content = file_path.read_text()
+
+    # Check for XML format
+    if not is_xml_format(content):
+        result.errors.append("Not in XML format - needs migration")
+        return result
+
+    # Validate <session> root with attributes
+    if not re.search(r'<session\s+story="[^"]+"', content):
+        result.errors.append("Missing story attribute on <session>")
+
+    if not re.search(r'<session[^>]+workflow="[^"]+"', content):
+        result.errors.append("Missing workflow attribute on <session>")
+
+    # Validate <meta> section
+    if not _has_tag(content, "meta"):
+        result.errors.append("Missing <meta> section")
+    else:
+        if "<jira>" not in content:
+            result.errors.append("Missing <jira> in <meta>")
+        if "<started>" not in content:
+            result.errors.append("Missing <started> in <meta>")
+
+    # Validate <status> element
+    if not _has_tag(content, "status"):
+        result.errors.append("Missing <status> element")
+    else:
+        if 'phase="' not in content:
+            result.errors.append("Missing phase attribute on <status>")
+        if 'next-agent="' not in content:
+            result.warnings.append("Missing next-agent attribute on <status>")
+
+    # Validate optional sections
+    if not _has_tag(content, "acceptance-criteria"):
+        result.warnings.append("Missing <acceptance-criteria> section")
+
+    if not _has_tag(content, "work-log"):
+        result.warnings.append("Missing <work-log> section")
+
+    return result
+
+
+def validate_skill_file(file_path: Path) -> ValidationResult:
+    """Validate a skill file against the schema.
+
+    Args:
+        file_path: Path to SKILL.md file
+
+    Returns:
+        ValidationResult with errors/warnings
+    """
+    skill_name = file_path.parent.name
+    result = ValidationResult(file_path=file_path, file_type="skill")
+    content = file_path.read_text()
+
+    # Check YAML frontmatter
+    if not content.startswith("---\n"):
+        result.errors.append("Missing YAML frontmatter")
+    else:
+        if "name:" not in content.split("---")[1]:
+            result.errors.append("Missing 'name' in frontmatter")
+        if "description:" not in content.split("---")[1]:
+            result.errors.append("Missing 'description' in frontmatter")
+
+    # Check required tags
+    for tag in SKILL_REQUIRED:
+        if not _has_tag(content, tag):
+            result.errors.append(f"Missing <{tag}> tag (required)")
+
+    # Check recommended tags
+    for tag in SKILL_RECOMMENDED:
+        if not _has_tag(content, tag):
+            result.warnings.append(f"Missing <{tag}> tag (recommended)")
+
+    return result
+
+
+def validate_step_file(file_path: Path) -> ValidationResult:
+    """Validate a workflow step file against the schema.
+
+    Args:
+        file_path: Path to step-*.md file
+
+    Returns:
+        ValidationResult with errors/warnings
+    """
+    result = ValidationResult(file_path=file_path, file_type="step")
+    content = file_path.read_text()
+
+    # Determine workflow/step names from path
+    workflow_name = file_path.parent.parent.name
+    step_name = file_path.stem
+
+    # Check required tags
+    for tag in STEP_REQUIRED:
+        if not _has_tag(content, tag):
+            result.errors.append(f"Missing <{tag}> tag")
+
+    # Check step-meta fields if tag exists
+    if _has_tag(content, "step-meta"):
+        meta_match = re.search(r"<step-meta>(.+?)</step-meta>", content, re.DOTALL)
+        if meta_match:
+            meta_content = meta_match.group(1)
+            for field_name in STEP_META_FIELDS:
+                if f"{field_name}:" not in meta_content:
+                    result.errors.append(f"Missing '{field_name}' in step-meta")
+
+    # Check recommended tags
+    for tag in STEP_RECOMMENDED:
+        if not _has_tag(content, tag):
+            result.warnings.append(f"Missing <{tag}> tag")
+
+    return result
+
+
+def validate_file(file_path: Path) -> ValidationResult:
+    """Validate a file, auto-detecting its type.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        ValidationResult
+    """
+    name = file_path.name
+
+    if name.endswith("-session.md"):
+        return validate_session_file(file_path)
+    elif name == "SKILL.md":
+        return validate_skill_file(file_path)
+    elif name.startswith("step-") and name.endswith(".md"):
+        return validate_step_file(file_path)
+    else:
+        result = ValidationResult(file_path=file_path, file_type="session")
+        result.errors.append(f"Unknown file type: {name}")
+        return result
+
+
+@dataclass
+class ValidationSummary:
+    """Summary of validation results."""
+
+    results: list[ValidationResult] = field(default_factory=list)
+    passed: int = 0
+    warnings: int = 0
+    errors: int = 0
+
+    def add(self, result: ValidationResult) -> None:
+        """Add a result to the summary."""
+        self.results.append(result)
+        if result.status == "PASS":
+            self.passed += 1
+        elif result.status == "WARN":
+            self.warnings += 1
+        else:
+            self.errors += 1
+
+    @property
+    def total(self) -> int:
+        return len(self.results)
+
+    @property
+    def success(self) -> bool:
+        return self.errors == 0
+
+
+def validate_all(
+    root: Path,
+    *,
+    file_type: Literal["session", "skill", "step", "all"] = "all",
+    strict: bool = False,
+) -> ValidationSummary:
+    """Validate all files of specified type(s).
+
+    Args:
+        root: Project root directory
+        file_type: Type to validate (session, skill, step, or all)
+        strict: If True, treat warnings as errors
+
+    Returns:
+        ValidationSummary with all results
+    """
+    summary = ValidationSummary()
+
+    # Validate sessions
+    if file_type in ("session", "all"):
+        for file_path in find_session_files(root):
+            result = validate_session_file(file_path)
+            if strict and result.warnings:
+                result.errors.extend(result.warnings)
+                result.warnings = []
+            summary.add(result)
+
+    # Validate skills
+    if file_type in ("skill", "all"):
+        for file_path in find_skill_files(root):
+            result = validate_skill_file(file_path)
+            if strict and result.warnings:
+                result.errors.extend(result.warnings)
+                result.warnings = []
+            summary.add(result)
+
+    # Validate steps
+    if file_type in ("step", "all"):
+        for file_path in find_step_files(root):
+            result = validate_step_file(file_path)
+            if strict and result.warnings:
+                result.errors.extend(result.warnings)
+                result.warnings = []
+            summary.add(result)
+
+    return summary