specfact-cli 0.4.0__py3-none-any.whl

specfact_cli/models/__init__.py

@@ -0,0 +1,32 @@
+"""
+SpecFact CLI data models.
+
+This package contains Pydantic models for plan bundles, protocols,
+features, stories, and validation results.
+"""
+
+from specfact_cli.models.deviation import Deviation, DeviationReport, DeviationSeverity, DeviationType, ValidationReport
+from specfact_cli.models.enforcement import EnforcementAction, EnforcementConfig, EnforcementPreset
+from specfact_cli.models.plan import Business, Feature, Idea, Metadata, PlanBundle, Product, Release, Story
+from specfact_cli.models.protocol import Protocol, Transition
+
+__all__ = [
+    "Business",
+    "Deviation",
+    "DeviationReport",
+    "DeviationSeverity",
+    "DeviationType",
+    "EnforcementAction",
+    "EnforcementConfig",
+    "EnforcementPreset",
+    "Feature",
+    "Idea",
+    "Metadata",
+    "PlanBundle",
+    "Product",
+    "Protocol",
+    "Release",
+    "Story",
+    "Transition",
+    "ValidationReport",
+]

specfact_cli/models/deviation.py

@@ -0,0 +1,105 @@
+"""
+Deviation tracking models.
+
+This module defines models for tracking deviations between plans,
+protocols, and actual implementation following the CLI-First specification.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from beartype import beartype
+from icontract import ensure, require
+from pydantic import BaseModel, Field
+
+
+class DeviationSeverity(str, Enum):
+    """Deviation severity level."""
+
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+
+
+class DeviationType(str, Enum):
+    """Type of deviation."""
+
+    MISSING_FEATURE = "missing_feature"
+    MISSING_STORY = "missing_story"
+    MISSING_BUSINESS_CONTEXT = "missing_business_context"
+    EXTRA_FEATURE = "extra_feature"
+    EXTRA_STORY = "extra_story"
+    EXTRA_IMPLEMENTATION = "extra_implementation"
+    MISMATCH = "mismatch"
+    ACCEPTANCE_DRIFT = "acceptance_drift"
+    FSM_MISMATCH = "fsm_mismatch"
+    RISK_OMISSION = "risk_omission"
+
+
+class Deviation(BaseModel):
+    """Deviation model."""
+
+    type: DeviationType = Field(..., description="Deviation type")
+    severity: DeviationSeverity = Field(..., description="Severity level")
+    description: str = Field(..., description="Deviation description")
+    location: str = Field(..., description="File/module location")
+    fix_hint: str | None = Field(None, description="Fix suggestion")
+
+
+class DeviationReport(BaseModel):
+    """Deviation report model."""
+
+    manual_plan: str = Field(..., description="Path to manual plan bundle")
+    auto_plan: str = Field(..., description="Path to auto-generated plan bundle")
+    deviations: list[Deviation] = Field(default_factory=list, description="All deviations")
+    summary: dict[str, int] = Field(default_factory=dict, description="Deviation counts by type")
+
+    @property
+    def total_deviations(self) -> int:
+        """Total number of deviations."""
+        return len(self.deviations)
+
+    @property
+    def high_count(self) -> int:
+        """Number of high severity deviations."""
+        return sum(1 for d in self.deviations if d.severity == DeviationSeverity.HIGH)
+
+    @property
+    def medium_count(self) -> int:
+        """Number of medium severity deviations."""
+        return sum(1 for d in self.deviations if d.severity == DeviationSeverity.MEDIUM)
+
+    @property
+    def low_count(self) -> int:
+        """Number of low severity deviations."""
+        return sum(1 for d in self.deviations if d.severity == DeviationSeverity.LOW)
+
+
+class ValidationReport(BaseModel):
+    """Validation report model (for backward compatibility)."""
+
+    deviations: list[Deviation] = Field(default_factory=list, description="All deviations")
+    high_count: int = Field(default=0, description="Number of high severity deviations")
+    medium_count: int = Field(default=0, description="Number of medium severity deviations")
+    low_count: int = Field(default=0, description="Number of low severity deviations")
+    passed: bool = Field(default=True, description="Whether validation passed")
+
+    @beartype
+    @require(lambda deviation: isinstance(deviation, Deviation), "Must be Deviation instance")
+    @ensure(
+        lambda self: self.high_count + self.medium_count + self.low_count == len(self.deviations),
+        "Counts must match deviations",
+    )
+    @ensure(lambda self: self.passed == (self.high_count == 0), "Must fail if high severity deviations exist")
+    def add_deviation(self, deviation: Deviation) -> None:
+        """Add a deviation and update counts."""
+        self.deviations.append(deviation)
+
+        if deviation.severity == DeviationSeverity.HIGH:
+            self.high_count += 1
+            self.passed = False
+        elif deviation.severity == DeviationSeverity.MEDIUM:
+            self.medium_count += 1
+        elif deviation.severity == DeviationSeverity.LOW:
+            self.low_count += 1

specfact_cli/models/enforcement.py

@@ -0,0 +1,150 @@
+"""Enforcement configuration models for quality gates."""
+
+from enum import Enum
+
+from beartype import beartype
+from icontract import ensure, require
+from pydantic import BaseModel, Field
+
+
+class EnforcementAction(str, Enum):
+    """Actions that can be taken when a deviation is detected."""
+
+    BLOCK = "BLOCK"  # Fail the validation (exit code 1)
+    WARN = "WARN"  # Show warning but continue (exit code 0)
+    LOG = "LOG"  # Only log, no warning (exit code 0)
+
+
+class EnforcementPreset(str, Enum):
+    """Predefined enforcement presets."""
+
+    MINIMAL = "minimal"  # Log everything, never block
+    BALANCED = "balanced"  # Block HIGH, warn MEDIUM, log LOW
+    STRICT = "strict"  # Block HIGH+MEDIUM, warn LOW
+
+
+class EnforcementConfig(BaseModel):
+    """Configuration for contract enforcement and quality gates."""
+
+    preset: EnforcementPreset = Field(default=EnforcementPreset.BALANCED, description="Enforcement preset mode")
+    high_action: EnforcementAction = Field(
+        default=EnforcementAction.BLOCK, description="Action for HIGH severity deviations"
+    )
+    medium_action: EnforcementAction = Field(
+        default=EnforcementAction.WARN, description="Action for MEDIUM severity deviations"
+    )
+    low_action: EnforcementAction = Field(
+        default=EnforcementAction.LOG, description="Action for LOW severity deviations"
+    )
+    enabled: bool = Field(default=True, description="Whether enforcement is enabled")
+
+    @classmethod
+    @beartype
+    @require(lambda preset: preset in EnforcementPreset, "Preset must be valid EnforcementPreset")
+    @ensure(lambda result: isinstance(result, EnforcementConfig), "Must return EnforcementConfig")
+    @ensure(lambda result: result.enabled is True, "Config must be enabled")
+    def from_preset(cls, preset: EnforcementPreset) -> "EnforcementConfig":
+        """
+        Create an enforcement config from a preset.
+
+        Args:
+            preset: The preset to use
+
+        Returns:
+            EnforcementConfig with preset values
+        """
+        if preset == EnforcementPreset.MINIMAL:
+            return cls(
+                preset=preset,
+                high_action=EnforcementAction.WARN,
+                medium_action=EnforcementAction.WARN,
+                low_action=EnforcementAction.LOG,
+                enabled=True,
+            )
+        if preset == EnforcementPreset.BALANCED:
+            return cls(
+                preset=preset,
+                high_action=EnforcementAction.BLOCK,
+                medium_action=EnforcementAction.WARN,
+                low_action=EnforcementAction.LOG,
+                enabled=True,
+            )
+        if preset == EnforcementPreset.STRICT:
+            return cls(
+                preset=preset,
+                high_action=EnforcementAction.BLOCK,
+                medium_action=EnforcementAction.BLOCK,
+                low_action=EnforcementAction.WARN,
+                enabled=True,
+            )
+        # Default to balanced
+        return cls.from_preset(EnforcementPreset.BALANCED)
+
+    @beartype
+    @require(lambda severity: isinstance(severity, str) and len(severity) > 0, "Severity must be non-empty string")
+    @require(lambda severity: severity.upper() in ("HIGH", "MEDIUM", "LOW"), "Severity must be HIGH/MEDIUM/LOW")
+    @ensure(lambda result: isinstance(result, bool), "Must return boolean")
+    def should_block_deviation(self, severity: str) -> bool:
+        """
+        Determine if a deviation should block execution.
+
+        Args:
+            severity: Deviation severity (HIGH, MEDIUM, LOW)
+
+        Returns:
+            True if this deviation should cause a failure (exit 1)
+        """
+        if not self.enabled:
+            return False
+
+        severity_upper = severity.upper()
+        if severity_upper == "HIGH":
+            return self.high_action == EnforcementAction.BLOCK
+        if severity_upper == "MEDIUM":
+            return self.medium_action == EnforcementAction.BLOCK
+        if severity_upper == "LOW":
+            return self.low_action == EnforcementAction.BLOCK
+        return False
+
+    @beartype
+    @require(lambda severity: isinstance(severity, str) and len(severity) > 0, "Severity must be non-empty string")
+    @require(lambda severity: severity.upper() in ("HIGH", "MEDIUM", "LOW"), "Severity must be HIGH/MEDIUM/LOW")
+    @ensure(lambda result: isinstance(result, EnforcementAction), "Must return EnforcementAction")
+    def get_action(self, severity: str) -> EnforcementAction:
+        """
+        Get the action for a given severity level.
+
+        Args:
+            severity: Deviation severity (HIGH, MEDIUM, LOW)
+
+        Returns:
+            The enforcement action to take
+        """
+        severity_upper = severity.upper()
+        if severity_upper == "HIGH":
+            return self.high_action
+        if severity_upper == "MEDIUM":
+            return self.medium_action
+        if severity_upper == "LOW":
+            return self.low_action
+        return EnforcementAction.LOG
+
+    @beartype
+    @ensure(lambda result: isinstance(result, dict), "Must return dictionary")
+    @ensure(
+        lambda result: all(isinstance(k, str) and isinstance(v, str) for k, v in result.items()),
+        "All keys and values must be strings",
+    )
+    @ensure(lambda result: set(result.keys()) == {"HIGH", "MEDIUM", "LOW"}, "Must have all three severity levels")
+    def to_summary_dict(self) -> dict[str, str]:
+        """
+        Convert config to a summary dictionary for display.
+
+        Returns:
+            Dictionary mapping severity to action
+        """
+        return {
+            "HIGH": self.high_action.value,
+            "MEDIUM": self.medium_action.value,
+            "LOW": self.low_action.value,
+        }

specfact_cli/models/plan.py

@@ -0,0 +1,97 @@
+"""
+Plan bundle data models.
+
+This module defines Pydantic models for development plans, features,
+and stories following the CLI-First specification.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Story(BaseModel):
+    """User story model following Scrum/Agile practices."""
+
+    key: str = Field(..., description="Story key (e.g., STORY-001)")
+    title: str = Field(..., description="Story title (user-facing value statement)")
+    acceptance: list[str] = Field(default_factory=list, description="Acceptance criteria")
+    tags: list[str] = Field(default_factory=list, description="Story tags")
+    story_points: int | None = Field(None, ge=0, le=100, description="Story points (complexity: 1,2,3,5,8,13,21...)")
+    value_points: int | None = Field(
+        None, ge=0, le=100, description="Value points (business value: 1,2,3,5,8,13,21...)"
+    )
+    tasks: list[str] = Field(default_factory=list, description="Implementation tasks (methods, functions)")
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Confidence score (0.0-1.0)")
+    draft: bool = Field(default=False, description="Whether this is a draft story")
+
+
+class Feature(BaseModel):
+    """Feature model."""
+
+    key: str = Field(..., description="Feature key (e.g., FEATURE-001)")
+    title: str = Field(..., description="Feature title")
+    outcomes: list[str] = Field(default_factory=list, description="Expected outcomes")
+    acceptance: list[str] = Field(default_factory=list, description="Acceptance criteria")
+    constraints: list[str] = Field(default_factory=list, description="Constraints")
+    stories: list[Story] = Field(default_factory=list, description="User stories")
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Confidence score (0.0-1.0)")
+    draft: bool = Field(default=False, description="Whether this is a draft feature")
+
+
+class Release(BaseModel):
+    """Release model."""
+
+    name: str = Field(..., description="Release name")
+    objectives: list[str] = Field(default_factory=list, description="Release objectives")
+    scope: list[str] = Field(default_factory=list, description="Features in scope")
+    risks: list[str] = Field(default_factory=list, description="Release risks")
+
+
+class Product(BaseModel):
+    """Product definition model."""
+
+    themes: list[str] = Field(default_factory=list, description="Product themes")
+    releases: list[Release] = Field(default_factory=list, description="Product releases")
+
+
+class Business(BaseModel):
+    """Business context model."""
+
+    segments: list[str] = Field(default_factory=list, description="Market segments")
+    problems: list[str] = Field(default_factory=list, description="Problems being solved")
+    solutions: list[str] = Field(default_factory=list, description="Proposed solutions")
+    differentiation: list[str] = Field(default_factory=list, description="Differentiation points")
+    risks: list[str] = Field(default_factory=list, description="Business risks")
+
+
+class Idea(BaseModel):
+    """Initial idea model."""
+
+    title: str = Field(..., description="Idea title")
+    narrative: str = Field(..., description="Idea narrative")
+    target_users: list[str] = Field(default_factory=list, description="Target user personas")
+    value_hypothesis: str = Field(default="", description="Value hypothesis")
+    constraints: list[str] = Field(default_factory=list, description="Idea constraints")
+    metrics: dict[str, Any] | None = Field(None, description="Success metrics")
+
+
+class Metadata(BaseModel):
+    """Plan bundle metadata."""
+
+    stage: str = Field(default="draft", description="Plan stage (draft, review, approved, released)")
+    promoted_at: str | None = Field(None, description="ISO timestamp of last promotion")
+    promoted_by: str | None = Field(None, description="User who performed last promotion")
+
+
+class PlanBundle(BaseModel):
+    """Complete plan bundle model."""
+
+    version: str = Field(default="1.0", description="Plan bundle version")
+    idea: Idea | None = Field(None, description="Initial idea")
+    business: Business | None = Field(None, description="Business context")
+    product: Product = Field(..., description="Product definition")
+    features: list[Feature] = Field(default_factory=list, description="Product features")
+    metadata: Metadata | None = Field(None, description="Plan bundle metadata")

specfact_cli/models/protocol.py

@@ -0,0 +1,28 @@
+"""
+Protocol data models.
+
+This module defines Pydantic models for FSM protocols, states,
+and transitions following the CLI-First specification.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class Transition(BaseModel):
+    """State machine transition."""
+
+    from_state: str = Field(..., description="Source state")
+    on_event: str = Field(..., description="Triggering event")
+    to_state: str = Field(..., description="Target state")
+    guard: str | None = Field(None, description="Guard function name")
+
+
+class Protocol(BaseModel):
+    """FSM protocol definition."""
+
+    states: list[str] = Field(..., description="State names")
+    start: str = Field(..., description="Initial state")
+    transitions: list[Transition] = Field(..., description="State transitions")
+    guards: dict[str, str] = Field(default_factory=dict, description="Guard definitions")

specfact_cli/modes/__init__.py

@@ -0,0 +1,18 @@
+"""
+Mode detection and routing for SpecFact CLI.
+
+This package provides operational mode detection (CI/CD vs CoPilot) and command routing.
+"""
+
+from __future__ import annotations
+
+from specfact_cli.modes.detector import OperationalMode, detect_mode
+from specfact_cli.modes.router import CommandRouter, RoutingResult, get_router
+
+__all__ = [
+    "CommandRouter",
+    "OperationalMode",
+    "RoutingResult",
+    "detect_mode",
+    "get_router",
+]

specfact_cli/modes/detector.py

@@ -0,0 +1,126 @@
+"""
+Mode detection for SpecFact CLI.
+
+This module provides automatic detection of operational mode (CI/CD vs CoPilot)
+based on environment and explicit flags.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+
+from beartype import beartype
+from icontract import ensure, require
+
+
+class OperationalMode(str, Enum):
+    """Operational modes for SpecFact CLI."""
+
+    CICD = "cicd"
+    COPILOT = "copilot"
+
+
+@beartype
+@require(lambda explicit_mode: explicit_mode is None or isinstance(explicit_mode, OperationalMode))
+@ensure(lambda result: isinstance(result, OperationalMode))
+def detect_mode(explicit_mode: OperationalMode | None = None) -> OperationalMode:
+    """
+    Auto-detect operational mode or use explicit override.
+
+    Priority:
+    1. Explicit mode flag (highest)
+    2. CoPilot API availability
+    3. IDE integration (VS Code/Cursor with CoPilot)
+    4. Default to CI/CD mode
+
+    Args:
+        explicit_mode: Explicitly specified mode (overrides auto-detection)
+
+    Returns:
+        Detected or explicit operational mode
+
+    Raises:
+        ValueError: If explicit_mode is invalid OperationalMode value
+    """
+    # 1. Check explicit flag (highest priority)
+    if explicit_mode is not None:
+        return explicit_mode
+
+    # 2. Check environment variable (SPECFACT_MODE)
+    env_mode = os.environ.get("SPECFACT_MODE", "").lower()
+    if env_mode == "copilot":
+        return OperationalMode.COPILOT
+    if env_mode == "cicd":
+        return OperationalMode.CICD
+
+    # 3. Check CoPilot API availability
+    if copilot_api_available():
+        return OperationalMode.COPILOT
+
+    # 4. Check IDE integration
+    if ide_detected() and ide_has_copilot():
+        return OperationalMode.COPILOT
+
+    # 5. Default to CI/CD
+    return OperationalMode.CICD
+
+
+@beartype
+@ensure(lambda result: isinstance(result, bool))
+def copilot_api_available() -> bool:
+    """
+    Check if CoPilot API is available.
+
+    Returns:
+        True if CoPilot API is available, False otherwise
+    """
+    # Check environment variables
+    if os.environ.get("COPILOT_API_URL"):
+        return True
+
+    # Check for CoPilot token or credentials
+    return bool(os.environ.get("COPILOT_API_TOKEN") or os.environ.get("GITHUB_COPILOT_TOKEN"))
+
+
+@beartype
+@ensure(lambda result: isinstance(result, bool))
+def ide_detected() -> bool:
+    """
+    Check if running in IDE (VS Code/Cursor).
+
+    Returns:
+        True if running in IDE, False otherwise
+    """
+    # Check VS Code
+    if os.environ.get("VSCODE_PID") or os.environ.get("VSCODE_INJECTION"):
+        return True
+
+    # Check Cursor
+    if os.environ.get("CURSOR_PID") or os.environ.get("CURSOR_MODE"):
+        return True
+
+    # Check for common IDE environment variables
+    return os.environ.get("TERM_PROGRAM") == "vscode"
+
+
+@beartype
+@ensure(lambda result: isinstance(result, bool))
+def ide_has_copilot() -> bool:
+    """
+    Check if IDE has CoPilot extension enabled.
+
+    Returns:
+        True if IDE has CoPilot enabled, False otherwise
+    """
+    # Check for CoPilot extension environment variables
+    if os.environ.get("COPILOT_ENABLED") == "true":
+        return True
+
+    # Check for VS Code/Cursor Copilot settings
+    if os.environ.get("VSCODE_COPILOT_ENABLED") == "true":
+        return True
+
+    # Placeholder: Future implementation may check IDE configuration files
+    # For now, we only check environment variables
+    return os.environ.get("CURSOR_COPILOT_ENABLED") == "true"