@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing_scripts/migration/skill.py

@@ -1,188 +0,0 @@
-"""
-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

@@ -1,229 +0,0 @@
-"""
-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

@@ -1,282 +0,0 @@
-"""
-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