specfact-cli 0.4.0__py3-none-any.whl

specfact_cli/generators/protocol_generator.py

@@ -0,0 +1,115 @@
+"""Protocol generator using Jinja2 templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from beartype import beartype
+from icontract import ensure, require
+from jinja2 import Environment, FileSystemLoader
+
+from specfact_cli.models.protocol import Protocol
+
+
+class ProtocolGenerator:
+    """
+    Generator for protocol YAML files.
+
+    Uses Jinja2 templates to render protocols from Protocol models.
+    """
+
+    @beartype
+    def __init__(self, templates_dir: Path | None = None) -> None:
+        """
+        Initialize protocol generator.
+
+        Args:
+            templates_dir: Directory containing Jinja2 templates (default: resources/templates)
+        """
+        if templates_dir is None:
+            # Default to resources/templates relative to project root
+            templates_dir = Path(__file__).parent.parent.parent.parent / "resources" / "templates"
+
+        self.templates_dir = Path(templates_dir)
+        self.env = Environment(
+            loader=FileSystemLoader(self.templates_dir),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    @beartype
+    @require(lambda protocol: isinstance(protocol, Protocol), "Must be Protocol instance")
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @require(lambda protocol: len(protocol.states) > 0, "Protocol must have at least one state")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    def generate(self, protocol: Protocol, output_path: Path) -> None:
+        """
+        Generate protocol YAML file from model.
+
+        Args:
+            protocol: Protocol model to generate from
+            output_path: Path to write the generated YAML file
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            IOError: If unable to write output file
+        """
+        # Convert model to dict, excluding None values
+        protocol_data = protocol.model_dump(exclude_none=True, mode="json")
+
+        # Render template
+        template = self.env.get_template("protocol.yaml.j2")
+        rendered = template.render(**protocol_data)
+
+        # Write to file
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+
+    @beartype
+    @require(
+        lambda template_name: isinstance(template_name, str) and len(template_name) > 0,
+        "Template name must be non-empty string",
+    )
+    @require(lambda context: isinstance(context, dict), "Context must be dictionary")
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    def generate_from_template(self, template_name: str, context: dict, output_path: Path) -> None:
+        """
+        Generate file from custom template.
+
+        Args:
+            template_name: Name of the template file
+            context: Context dictionary for template rendering
+            output_path: Path to write the generated file
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            IOError: If unable to write output file
+        """
+        template = self.env.get_template(template_name)
+        rendered = template.render(**context)
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+
+    @beartype
+    @require(lambda protocol: isinstance(protocol, Protocol), "Must be Protocol instance")
+    @require(lambda protocol: len(protocol.states) > 0, "Protocol must have at least one state")
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    @ensure(lambda result: len(result) > 0, "Result must be non-empty")
+    def render_string(self, protocol: Protocol) -> str:
+        """
+        Render protocol to YAML string without writing to file.
+
+        Args:
+            protocol: Protocol model to render
+
+        Returns:
+            Rendered YAML string
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+        """
+        protocol_data = protocol.model_dump(exclude_none=True, mode="json")
+        template = self.env.get_template("protocol.yaml.j2")
+        return template.render(**protocol_data)

specfact_cli/generators/report_generator.py

@@ -0,0 +1,200 @@
+"""Report generator for validation reports and deviation reports."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from pathlib import Path
+
+from beartype import beartype
+from icontract import ensure, require
+from jinja2 import Environment, FileSystemLoader
+
+from specfact_cli.models.deviation import DeviationReport, ValidationReport
+from specfact_cli.utils.yaml_utils import dump_yaml
+
+
+class ReportFormat(str, Enum):
+    """Report output format."""
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+    YAML = "yaml"
+
+
+class ReportGenerator:
+    """
+    Generator for validation and deviation reports.
+
+    Supports multiple output formats: Markdown, JSON, YAML.
+    """
+
+    @beartype
+    def __init__(self, templates_dir: Path | None = None) -> None:
+        """
+        Initialize report generator.
+
+        Args:
+            templates_dir: Directory containing Jinja2 templates (default: resources/templates)
+        """
+        if templates_dir is None:
+            # Default to resources/templates relative to project root
+            templates_dir = Path(__file__).parent.parent.parent.parent / "resources" / "templates"
+
+        self.templates_dir = Path(templates_dir)
+        self.env = Environment(
+            loader=FileSystemLoader(self.templates_dir),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    @beartype
+    @require(lambda report: isinstance(report, ValidationReport), "Must be ValidationReport instance")
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @require(lambda format: format in ReportFormat, "Format must be valid ReportFormat")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    def generate_validation_report(
+        self, report: ValidationReport, output_path: Path, format: ReportFormat = ReportFormat.MARKDOWN
+    ) -> None:
+        """
+        Generate validation report file.
+
+        Args:
+            report: ValidationReport model to generate from
+            output_path: Path to write the generated report file
+            format: Output format (markdown, json, yaml)
+
+        Raises:
+            ValueError: If format is unsupported
+            IOError: If unable to write output file
+        """
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if format == ReportFormat.MARKDOWN:
+            self._generate_markdown_report(report, output_path)
+        elif format == ReportFormat.JSON:
+            self._generate_json_report(report, output_path)
+        elif format == ReportFormat.YAML:
+            self._generate_yaml_report(report, output_path)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+    @beartype
+    @require(lambda report: isinstance(report, DeviationReport), "Must be DeviationReport instance")
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @require(lambda format: format in ReportFormat, "Format must be valid ReportFormat")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    def generate_deviation_report(
+        self, report: DeviationReport, output_path: Path, format: ReportFormat = ReportFormat.MARKDOWN
+    ) -> None:
+        """
+        Generate deviation report file.
+
+        Args:
+            report: DeviationReport model to generate from
+            output_path: Path to write the generated report file
+            format: Output format (markdown, json, yaml)
+
+        Raises:
+            ValueError: If format is unsupported
+            IOError: If unable to write output file
+        """
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if format == ReportFormat.MARKDOWN:
+            self._generate_deviation_markdown(report, output_path)
+        elif format == ReportFormat.JSON:
+            self._generate_json_report(report, output_path)
+        elif format == ReportFormat.YAML:
+            self._generate_yaml_report(report, output_path)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+    def _generate_markdown_report(self, report: ValidationReport, output_path: Path) -> None:
+        """Generate markdown validation report."""
+        lines = []
+        lines.append("# Validation Report\n")
+        lines.append(f"**Status**: {'✅ PASSED' if report.passed else '❌ FAILED'}\n")
+        total_count = len(report.deviations)
+        lines.append(f"**Total Deviations**: {total_count}\n")
+
+        if total_count > 0:
+            lines.append("\n## Deviations by Severity\n")
+            lines.append(f"- 🔴 **HIGH**: {report.high_count}")
+            lines.append(f"- 🟡 **MEDIUM**: {report.medium_count}")
+            lines.append(f"- 🔵 **LOW**: {report.low_count}\n")
+
+            lines.append("\n## Detailed Deviations\n")
+            for deviation in report.deviations:
+                lines.append(f"### {deviation.severity.value.upper()}: {deviation.description}\n")
+                if deviation.location:
+                    lines.append(f"**Location**: `{deviation.location}`\n")
+                if deviation.fix_hint:
+                    lines.append(f"**Fix Hint**: {deviation.fix_hint}\n")
+                lines.append("")
+
+        output_path.write_text("\n".join(lines), encoding="utf-8")
+
+    def _generate_deviation_markdown(self, report: DeviationReport, output_path: Path) -> None:
+        """Generate markdown deviation report."""
+        lines = []
+        lines.append("# Deviation Report\n")
+        lines.append(f"**Manual Plan**: {report.manual_plan}")
+        lines.append(f"**Auto Plan**: {report.auto_plan}")
+        lines.append(f"**Total Deviations**: {len(report.deviations)}\n")
+
+        # Group by type
+        by_type: dict = {}
+        for deviation in report.deviations:
+            type_key = deviation.type.value
+            if type_key not in by_type:
+                by_type[type_key] = []
+            by_type[type_key].append(deviation)
+
+        lines.append("\n## Deviations by Type\n")
+        for type_key, devs in by_type.items():
+            lines.append(f"### {type_key} ({len(devs)} issues)\n")
+            for dev in devs:
+                lines.append(f"- **{dev.severity.value.upper()}**: {dev.description}")
+                if dev.location:
+                    lines.append(f"  - Location: `{dev.location}`")
+                if dev.fix_hint:
+                    lines.append(f"  - Fix: {dev.fix_hint}")
+                lines.append("")
+
+        output_path.write_text("\n".join(lines), encoding="utf-8")
+
+    def _generate_json_report(self, report: ValidationReport | DeviationReport, output_path: Path) -> None:
+        """Generate JSON report."""
+        report_data = report.model_dump(mode="json")
+        output_path.write_text(json.dumps(report_data, indent=2), encoding="utf-8")
+
+    def _generate_yaml_report(self, report: ValidationReport | DeviationReport, output_path: Path) -> None:
+        """Generate YAML report."""
+        dump_yaml(report.model_dump(mode="json"), output_path)
+
+    def render_markdown_string(self, report: ValidationReport | DeviationReport) -> str:
+        """
+        Render report to markdown string without writing to file.
+
+        Args:
+            report: ValidationReport or DeviationReport model to render
+
+        Returns:
+            Rendered markdown string
+        """
+        from io import StringIO
+
+        output = StringIO()
+
+        if isinstance(report, ValidationReport):
+            output.write("# Validation Report\n\n")
+            output.write(f"**Status**: {'✅ PASSED' if report.passed else '❌ FAILED'}\n\n")
+            output.write(f"**Total Deviations**: {len(report.deviations)}\n\n")
+        elif isinstance(report, DeviationReport):
+            output.write("# Deviation Report\n\n")
+            output.write(f"**Manual Plan**: {report.manual_plan}\n")
+            output.write(f"**Auto Plan**: {report.auto_plan}\n")
+            output.write(f"**Total Deviations**: {len(report.deviations)}\n\n")
+
+        return output.getvalue()

specfact_cli/generators/workflow_generator.py

@@ -0,0 +1,111 @@
+"""Workflow generator for GitHub Actions and Semgrep rules."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+from jinja2 import Environment, FileSystemLoader
+
+
+class WorkflowGenerator:
+    """
+    Generator for GitHub Actions workflows and Semgrep rules.
+
+    Uses Jinja2 templates to render workflows and copies Semgrep rules.
+    """
+
+    @beartype
+    def __init__(self, templates_dir: Path | None = None) -> None:
+        """
+        Initialize workflow generator.
+
+        Args:
+            templates_dir: Directory containing Jinja2 templates (default: resources/templates)
+        """
+        if templates_dir is None:
+            # Default to resources/templates relative to project root
+            templates_dir = Path(__file__).parent.parent.parent.parent / "resources" / "templates"
+
+        self.templates_dir = Path(templates_dir)
+        self.env = Environment(
+            loader=FileSystemLoader(self.templates_dir),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    @beartype
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @require(lambda budget: budget > 0, "Budget must be positive")
+    @require(lambda python_version: python_version.startswith("3."), "Python version must be 3.x")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    @ensure(lambda output_path: output_path.suffix == ".yml", "Output must be YAML file")
+    def generate_github_action(
+        self,
+        output_path: Path,
+        repo_name: str | None = None,
+        budget: int = 90,
+        python_version: str = "3.12",
+    ) -> None:
+        """
+        Generate GitHub Action workflow for SpecFact validation.
+
+        Args:
+            output_path: Path to write the workflow file (e.g., .github/workflows/specfact-gate.yml)
+            repo_name: Repository name for context
+            budget: Time budget in seconds for validation (must be > 0)
+            python_version: Python version for workflow (must be 3.x)
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            IOError: If unable to write output file
+        """
+        # Prepare context
+        context: dict[str, Any] = {
+            "repo_name": repo_name or "specfact-project",
+            "budget": budget,
+            "python_version": python_version,
+        }
+
+        # Render template
+        template = self.env.get_template("github-action.yml.j2")
+        rendered = template.render(**context)
+
+        # Ensure output directory exists
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write workflow file
+        output_path.write_text(rendered, encoding="utf-8")
+
+    @beartype
+    @require(lambda output_path: output_path is not None, "Output path must not be None")
+    @ensure(lambda output_path: output_path.exists(), "Output file must exist after generation")
+    @ensure(lambda output_path: output_path.suffix in (".yml", ".yaml"), "Output must be YAML file")
+    def generate_semgrep_rules(self, output_path: Path, source_rules: Path | None = None) -> None:
+        """
+        Generate Semgrep async rules for the repository.
+
+        Args:
+            output_path: Path to write Semgrep rules (e.g., .semgrep/async-anti-patterns.yml)
+            source_rules: Path to source Semgrep rules (default: tools/semgrep/async.yml)
+
+        Raises:
+            FileNotFoundError: If source rules file doesn't exist
+            IOError: If unable to write output file
+        """
+        if source_rules is None:
+            # Default to tools/semgrep/async.yml relative to project root
+            source_rules = Path(__file__).parent.parent.parent.parent / "tools" / "semgrep" / "async.yml"
+
+        source_rules = Path(source_rules)
+        if not source_rules.exists():
+            raise FileNotFoundError(f"Source Semgrep rules not found: {source_rules}")
+
+        # Ensure output directory exists
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Copy source rules to output path
+        shutil.copy2(source_rules, output_path)

specfact_cli/importers/__init__.py

@@ -0,0 +1,6 @@
+"""Importers for converting external formats to SpecFact format."""
+
+from specfact_cli.importers.speckit_converter import SpecKitConverter
+from specfact_cli.importers.speckit_scanner import SpecKitScanner
+
+__all__ = ["SpecKitConverter", "SpecKitScanner"]