specfact-cli 0.6.3__py3-none-any.whl

specfact_cli/enrichers/plan_enricher.py

@@ -0,0 +1,268 @@
+"""
+Plan bundle enricher for automatic enhancement of vague acceptance criteria,
+incomplete requirements, and generic tasks.
+
+This module provides automatic enrichment capabilities that can be triggered
+during plan review to improve plan quality without manual intervention.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.models.plan import PlanBundle
+
+
+class PlanEnricher:
+    """
+    Enricher for automatically enhancing plan bundles.
+
+    Detects and fixes vague acceptance criteria, incomplete requirements,
+    and generic tasks using pattern-based improvements.
+    """
+
+    @beartype
+    @require(lambda plan_bundle: isinstance(plan_bundle, PlanBundle), "Plan bundle must be PlanBundle")
+    @ensure(lambda result: isinstance(result, dict), "Must return dict with enrichment summary")
+    def enrich_plan(self, plan_bundle: PlanBundle) -> dict[str, Any]:
+        """
+        Enrich plan bundle by enhancing vague acceptance criteria, incomplete requirements, and generic tasks.
+
+        Args:
+            plan_bundle: Plan bundle to enrich
+
+        Returns:
+            Dictionary with enrichment summary (features_updated, stories_updated, tasks_updated, etc.)
+        """
+        summary: dict[str, Any] = {
+            "features_updated": 0,
+            "stories_updated": 0,
+            "acceptance_criteria_enhanced": 0,
+            "requirements_enhanced": 0,
+            "tasks_enhanced": 0,
+            "changes": [],
+        }
+
+        for feature in plan_bundle.features:
+            feature_updated = False
+
+            # Enhance incomplete requirements in outcomes
+            enhanced_outcomes = []
+            for outcome in feature.outcomes:
+                enhanced = self._enhance_incomplete_requirement(outcome, feature.title)
+                if enhanced != outcome:
+                    enhanced_outcomes.append(enhanced)
+                    summary["requirements_enhanced"] += 1
+                    summary["changes"].append(f"Feature {feature.key}: Enhanced requirement '{outcome}' → '{enhanced}'")
+                    feature_updated = True
+                else:
+                    enhanced_outcomes.append(outcome)
+
+            if feature_updated:
+                feature.outcomes = enhanced_outcomes
+                summary["features_updated"] += 1
+
+            # Enhance stories
+            for story in feature.stories:
+                story_updated = False
+
+                # Enhance vague acceptance criteria
+                enhanced_acceptance = []
+                for acc in story.acceptance:
+                    enhanced = self._enhance_vague_acceptance_criteria(acc, story.title, feature.title)
+                    if enhanced != acc:
+                        enhanced_acceptance.append(enhanced)
+                        summary["acceptance_criteria_enhanced"] += 1
+                        summary["changes"].append(
+                            f"Story {story.key}: Enhanced acceptance criteria '{acc}' → '{enhanced}'"
+                        )
+                        story_updated = True
+                    else:
+                        enhanced_acceptance.append(acc)
+
+                if story_updated:
+                    story.acceptance = enhanced_acceptance
+                    summary["stories_updated"] += 1
+
+                # Enhance generic tasks
+                if story.tasks:
+                    enhanced_tasks = []
+                    for task in story.tasks:
+                        enhanced = self._enhance_generic_task(task, story.title, feature.title)
+                        if enhanced != task:
+                            enhanced_tasks.append(enhanced)
+                            summary["tasks_enhanced"] += 1
+                            summary["changes"].append(f"Story {story.key}: Enhanced task '{task}' → '{enhanced}'")
+                            story_updated = True
+                        else:
+                            enhanced_tasks.append(task)
+
+                    if story_updated and enhanced_tasks:
+                        story.tasks = enhanced_tasks
+
+        return summary
+
+    @beartype
+    @require(lambda requirement: isinstance(requirement, str), "Requirement must be string")
+    @require(lambda feature_title: isinstance(feature_title, str), "Feature title must be string")
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    @ensure(lambda result: len(result) > 0, "Result must be non-empty")
+    def _enhance_incomplete_requirement(self, requirement: str, feature_title: str) -> str:
+        """
+        Enhance incomplete requirement (e.g., "System MUST Helper class" → "System MUST provide a Helper class").
+
+        Args:
+            requirement: Requirement text to enhance
+            feature_title: Feature title for context
+
+        Returns:
+            Enhanced requirement text
+        """
+        requirement_lower = requirement.lower()
+        incomplete_patterns = [
+            ("system must", "System MUST provide"),
+            ("system should", "System SHOULD provide"),
+            ("must", "MUST provide"),
+            ("should", "SHOULD provide"),
+        ]
+
+        for pattern, replacement_prefix in incomplete_patterns:
+            if requirement_lower.startswith(pattern):
+                remaining = requirement[len(pattern) :].strip()
+                # Check if it's incomplete (just a noun phrase without verb)
+                if (
+                    remaining
+                    and len(remaining.split()) < 3
+                    and any(
+                        keyword in remaining.lower()
+                        for keyword in ["class", "helper", "module", "component", "service", "function"]
+                    )
+                ):
+                    # Enhance: "System MUST Helper class" → "System MUST provide a Helper class for [feature]"
+                    # Extract the component name
+                    component_name = remaining.strip()
+                    # Capitalize first letter if needed
+                    if component_name and component_name[0].islower():
+                        component_name = component_name[0].upper() + component_name[1:]
+                    # Generate enhanced requirement
+                    if "class" in component_name.lower():
+                        return f"{replacement_prefix} a {component_name} for {feature_title.lower()} operations"
+                    if "helper" in component_name.lower():
+                        return f"{replacement_prefix} a {component_name} class for {feature_title.lower()} operations"
+                    return f"{replacement_prefix} a {component_name} for {feature_title.lower()}"
+
+        return requirement
+
+    @beartype
+    @require(lambda acceptance: isinstance(acceptance, str), "Acceptance must be string")
+    @require(lambda story_title: isinstance(story_title, str), "Story title must be string")
+    @require(lambda feature_title: isinstance(feature_title, str), "Feature title must be string")
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    @ensure(lambda result: len(result) > 0, "Result must be non-empty")
+    def _enhance_vague_acceptance_criteria(self, acceptance: str, story_title: str, feature_title: str) -> str:
+        """
+        Enhance vague acceptance criteria (e.g., "is implemented" → "Given [state], When [action], Then [outcome]").
+
+        Args:
+            acceptance: Acceptance criteria text to enhance
+            story_title: Story title for context
+            feature_title: Feature title for context
+
+        Returns:
+            Enhanced acceptance criteria in Given/When/Then format
+        """
+        acceptance_lower = acceptance.lower()
+        vague_patterns = [
+            (
+                "is implemented",
+                "Given a developer wants to use {story}, When they interact with the system, Then {story} is functional and verified",
+            ),
+            (
+                "is functional",
+                "Given a user wants to use {story}, When they perform the action, Then {story} works as expected",
+            ),
+            (
+                "works",
+                "Given a user wants to use {story}, When they interact with the system, Then {story} works correctly",
+            ),
+            (
+                "is done",
+                "Given a user wants to complete {story}, When they perform the action, Then {story} is completed successfully",
+            ),
+            (
+                "is complete",
+                "Given a user wants to complete {story}, When they perform the action, Then {story} is completed successfully",
+            ),
+            (
+                "is ready",
+                "Given a user wants to use {story}, When they access the system, Then {story} is ready and available",
+            ),
+        ]
+
+        for pattern, template in vague_patterns:
+            if pattern in acceptance_lower:
+                # Replace placeholder with story title
+                return template.format(story=story_title.lower())
+
+        # If no vague pattern found, check if it's already in Given/When/Then format
+        if "given" in acceptance_lower and "when" in acceptance_lower and "then" in acceptance_lower:
+            return acceptance
+
+        # If it's a simple statement without testable keywords, enhance it
+        testable_keywords = ["must", "should", "will", "verify", "validate", "check", "ensure"]
+        if not any(keyword in acceptance_lower for keyword in testable_keywords):
+            # Convert to testable format
+            if acceptance_lower.startswith(("user can", "system can")):
+                return f"Must verify {acceptance.lower()}"
+            # Generate Given/When/Then from simple statement
+            return f"Given a user wants to use {story_title.lower()}, When they perform the action, Then {acceptance}"
+
+        return acceptance
+
+    @beartype
+    @require(lambda task: isinstance(task, str), "Task must be string")
+    @require(lambda story_title: isinstance(story_title, str), "Story title must be string")
+    @require(lambda feature_title: isinstance(feature_title, str), "Feature title must be string")
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    @ensure(lambda result: len(result) > 0, "Result must be non-empty")
+    def _enhance_generic_task(self, task: str, story_title: str, feature_title: str) -> str:
+        """
+        Enhance generic task (e.g., "Implement [story]" → "Implement [story] in src/... with methods for ...").
+
+        Args:
+            task: Task description to enhance
+            story_title: Story title for context
+            feature_title: Feature title for context
+
+        Returns:
+            Enhanced task with implementation details
+        """
+        task_lower = task.lower()
+        generic_patterns = [
+            ("implement", "Implement {story} in src/specfact_cli/... with methods for {feature} operations"),
+            ("create", "Create {story} component in src/specfact_cli/... with {feature} functionality"),
+            ("add", "Add {story} functionality to src/specfact_cli/... with {feature} support"),
+            ("set up", "Set up {story} infrastructure in src/specfact_cli/... for {feature} operations"),
+        ]
+
+        # Check if task is generic (has pattern but no implementation details)
+        has_details = any(
+            detail in task_lower
+            for detail in ["file", "path", "method", "class", "component", "module", "function", "src/", "tests/"]
+        )
+
+        if not has_details:
+            for pattern, template in generic_patterns:
+                if pattern in task_lower:
+                    # Extract the story/feature name from task
+                    remaining = task_lower.replace(pattern, "").strip()
+                    if not remaining or remaining == story_title.lower():
+                        # Use template with story and feature
+                        return template.format(story=story_title, feature=feature_title.lower())
+                    # Keep original but add implementation details
+                    return f"{task} in src/specfact_cli/... with methods and tests"
+
+        return task

specfact_cli/generators/__init__.py

@@ -0,0 +1,14 @@
+"""Generators for plan bundles, protocols, reports, and workflows."""
+
+from specfact_cli.generators.plan_generator import PlanGenerator
+from specfact_cli.generators.protocol_generator import ProtocolGenerator
+from specfact_cli.generators.report_generator import ReportGenerator
+from specfact_cli.generators.workflow_generator import WorkflowGenerator
+
+
+__all__ = [
+    "PlanGenerator",
+    "ProtocolGenerator",
+    "ReportGenerator",
+    "WorkflowGenerator",
+]

specfact_cli/generators/plan_generator.py

@@ -0,0 +1,105 @@
+"""Plan bundle generator using direct YAML serialization."""
+
+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.plan import PlanBundle
+from specfact_cli.utils.yaml_utils import dump_yaml, yaml_to_string
+
+
+class PlanGenerator:
+    """
+    Generator for plan bundle YAML files.
+
+    Uses direct YAML serialization for reliable output.
+    """
+
+    @beartype
+    def __init__(self, templates_dir: Path | None = None) -> None:
+        """
+        Initialize plan 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 plan_bundle: isinstance(plan_bundle, PlanBundle), "Must be PlanBundle instance")
+    @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(self, plan_bundle: PlanBundle, output_path: Path) -> None:
+        """
+        Generate plan bundle YAML file from model.
+
+        Args:
+            plan_bundle: PlanBundle model to generate from
+            output_path: Path to write the generated YAML file
+
+        Raises:
+            IOError: If unable to write output file
+        """
+        # Convert model to dict, excluding None values
+        plan_data = plan_bundle.model_dump(exclude_none=True)
+
+        # Write to file using YAML dump
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        dump_yaml(plan_data, output_path)
+
+    @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 plan_bundle: isinstance(plan_bundle, PlanBundle), "Must be PlanBundle instance")
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    @ensure(lambda result: len(result) > 0, "Result must be non-empty")
+    def render_string(self, plan_bundle: PlanBundle) -> str:
+        """
+        Render plan bundle to YAML string without writing to file.
+
+        Args:
+            plan_bundle: PlanBundle model to render
+
+        Returns:
+            Rendered YAML string
+        """
+        plan_data = plan_bundle.model_dump(exclude_none=True)
+        return yaml_to_string(plan_data)

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)