specfact-cli 0.4.2__py3-none-any.whl

specfact_cli/modes/router.py

@@ -0,0 +1,153 @@
+"""
+Command Router - Route commands based on operational mode.
+
+This module provides routing logic to execute commands differently based on
+the operational mode (CI/CD vs CoPilot).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.agents.registry import get_agent
+from specfact_cli.modes.detector import OperationalMode, detect_mode
+
+
+@dataclass
+class RoutingResult:
+    """Result of command routing."""
+
+    execution_mode: str  # "direct" or "agent"
+    mode: OperationalMode
+    command: str
+
+
+class CommandRouter:
+    """Routes commands based on operational mode."""
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @require(lambda mode: isinstance(mode, OperationalMode), "Mode must be OperationalMode")
+    @ensure(lambda result: result.execution_mode in ("direct", "agent"), "Execution mode must be direct or agent")
+    @ensure(lambda result: result.mode in (OperationalMode.CICD, OperationalMode.COPILOT), "Mode must be valid")
+    def route(self, command: str, mode: OperationalMode, context: dict[str, Any] | None = None) -> RoutingResult:
+        """
+        Route a command based on operational mode.
+
+        Args:
+            command: Command name (e.g., "import from-code")
+            mode: Operational mode (CI/CD or CoPilot)
+            context: Optional context dictionary for command execution
+
+        Returns:
+            RoutingResult with execution mode and mode information
+
+        Examples:
+            >>> router = CommandRouter()
+            >>> result = router.route("import from-code", OperationalMode.CICD)
+            >>> result.execution_mode
+            'direct'
+            >>> result = router.route("import from-code", OperationalMode.COPILOT)
+            >>> result.execution_mode
+            'agent'
+        """
+        if mode == OperationalMode.CICD:
+            return RoutingResult(execution_mode="direct", mode=mode, command=command)
+        # CoPilot mode uses agent routing (Phase 4.1)
+        # Check if agent is available for this command
+        agent = get_agent(command)
+        if agent:
+            return RoutingResult(execution_mode="agent", mode=mode, command=command)
+        # Fallback to direct execution if no agent available
+        return RoutingResult(execution_mode="direct", mode=mode, command=command)
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: result.mode in (OperationalMode.CICD, OperationalMode.COPILOT), "Mode must be valid")
+    def route_with_auto_detect(
+        self, command: str, explicit_mode: OperationalMode | None = None, context: dict[str, Any] | None = None
+    ) -> RoutingResult:
+        """
+        Route a command with automatic mode detection.
+
+        Args:
+            command: Command name (e.g., "import from-code")
+            explicit_mode: Optional explicit mode override
+            context: Optional context dictionary for command execution
+
+        Returns:
+            RoutingResult with execution mode and detected mode information
+
+        Examples:
+            >>> router = CommandRouter()
+            >>> result = router.route_with_auto_detect("import from-code")
+            >>> result.execution_mode in ("direct", "agent")
+            True
+        """
+        mode = detect_mode(explicit_mode=explicit_mode)
+        return self.route(command, mode, context)
+
+    @beartype
+    @require(lambda mode: isinstance(mode, OperationalMode), "Mode must be OperationalMode")
+    def should_use_agent(self, mode: OperationalMode) -> bool:
+        """
+        Check if command should use agent routing.
+
+        Args:
+            mode: Operational mode
+
+        Returns:
+            True if agent routing should be used, False for direct execution
+
+        Examples:
+            >>> router = CommandRouter()
+            >>> router.should_use_agent(OperationalMode.CICD)
+            False
+            >>> router.should_use_agent(OperationalMode.COPILOT)
+            True
+        """
+        return mode == OperationalMode.COPILOT
+
+    @beartype
+    @require(lambda mode: isinstance(mode, OperationalMode), "Mode must be OperationalMode")
+    def should_use_direct(self, mode: OperationalMode) -> bool:
+        """
+        Check if command should use direct execution.
+
+        Args:
+            mode: Operational mode
+
+        Returns:
+            True if direct execution should be used, False for agent routing
+
+        Examples:
+            >>> router = CommandRouter()
+            >>> router.should_use_direct(OperationalMode.CICD)
+            True
+            >>> router.should_use_direct(OperationalMode.COPILOT)
+            False
+        """
+        return mode == OperationalMode.CICD
+
+
+def get_router() -> CommandRouter:
+    """
+    Get the global command router instance.
+
+    Returns:
+        CommandRouter instance
+
+    Examples:
+        >>> router = get_router()
+        >>> isinstance(router, CommandRouter)
+        True
+    """
+    return _router
+
+
+# Global router instance
+_router = CommandRouter()

specfact_cli/resources/semgrep/async.yml

@@ -0,0 +1,285 @@
+rules:
+  - id: asyncio-create-task-not-awaited
+    patterns:
+      - pattern: asyncio.create_task(...)
+      - pattern-not-inside: await asyncio.create_task(...)
+      - pattern-not-inside: $TASK = asyncio.create_task(...)
+    message: |
+      Fire-and-forget task created without storing reference or awaiting.
+      This can lead to tasks being garbage collected before completion.
+      Either await the task or store the reference.
+    languages: [python]
+    severity: ERROR
+    metadata:
+      category: correctness
+      subcategory: [async]
+      likelihood: HIGH
+      impact: HIGH
+      confidence: HIGH
+
+  - id: blocking-sleep-in-async
+    patterns:
+      - pattern-either:
+          - pattern: time.sleep(...)
+          - pattern: time.wait(...)
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Blocking sleep in async function. Use asyncio.sleep() instead.
+      Blocking calls prevent other coroutines from running.
+    languages: [python]
+    severity: ERROR
+    metadata:
+      category: correctness
+      subcategory: [async]
+      likelihood: HIGH
+      impact: HIGH
+      confidence: HIGH
+    fix: asyncio.sleep(...)
+
+  - id: missing-await-on-coroutine
+    patterns:
+      - pattern: $FUNC(...)
+      - pattern-not: await $FUNC(...)
+      - pattern-not: asyncio.create_task($FUNC(...))
+      - pattern-not: asyncio.gather($FUNC(...), ...)
+      - pattern-inside: |
+          async def $OUTER(...):
+            ...
+    message: |
+      Coroutine call without await. This creates a coroutine object but never executes it.
+      Add 'await' keyword or use asyncio.create_task() for background execution.
+    languages: [python]
+    severity: ERROR
+    metadata:
+      category: correctness
+      subcategory: [async]
+      likelihood: HIGH
+      impact: HIGH
+      confidence: MEDIUM
+
+  - id: bare-except-in-async
+    patterns:
+      - pattern-either:
+          - pattern: |
+              try:
+                ...
+              except:
+                ...
+          - pattern: |
+              try:
+                ...
+              except Exception:
+                pass
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Bare except or silent exception handling in async function.
+      This can hide errors in coroutines and make debugging difficult.
+      Use specific exception types and log errors.
+    languages: [python]
+    severity: WARNING
+    metadata:
+      category: correctness
+      subcategory: [async, error-handling]
+      likelihood: MEDIUM
+      impact: MEDIUM
+      confidence: HIGH
+
+  - id: missing-timeout-on-wait
+    patterns:
+      - pattern-either:
+          - pattern: await asyncio.wait_for($CORO, None)
+          - pattern: await $CORO
+      - pattern-not: await asyncio.wait_for($CORO, timeout=...)
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Async wait without timeout. Long-running operations should have timeouts
+      to prevent indefinite hangs. Use asyncio.wait_for(coro, timeout=...).
+    languages: [python]
+    severity: WARNING
+    metadata:
+      category: correctness
+      subcategory: [async, timeout]
+      likelihood: MEDIUM
+      impact: MEDIUM
+      confidence: LOW
+
+  - id: blocking-file-io-in-async
+    patterns:
+      - pattern-either:
+          - pattern: open(...)
+          - pattern: $FILE.read(...)
+          - pattern: $FILE.write(...)
+      - pattern-not-inside: |
+          with aiofiles.open(...) as $F:
+            ...
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Blocking file I/O in async function. Use aiofiles or run_in_executor()
+      for file operations to avoid blocking the event loop.
+    languages: [python]
+    severity: WARNING
+    metadata:
+      category: performance
+      subcategory: [async, io]
+      likelihood: MEDIUM
+      impact: MEDIUM
+      confidence: MEDIUM
+
+  - id: asyncio-gather-without-error-handling
+    patterns:
+      - pattern: await asyncio.gather(...)
+      - pattern-not-inside: |
+          try:
+            await asyncio.gather(...)
+          except ...:
+            ...
+      - pattern-not: await asyncio.gather(..., return_exceptions=True)
+    message: |
+      asyncio.gather() without error handling. If any coroutine raises an exception,
+      gather() will raise it immediately. Use return_exceptions=True or wrap in try/except.
+    languages: [python]
+    severity: WARNING
+    metadata:
+      category: correctness
+      subcategory: [async, error-handling]
+      likelihood: MEDIUM
+      impact: MEDIUM
+      confidence: HIGH
+
+  - id: event-loop-in-async-context
+    patterns:
+      - pattern-either:
+          - pattern: asyncio.get_event_loop().run_until_complete(...)
+          - pattern: asyncio.run(...)
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Running event loop inside async context. This creates a nested event loop
+      which can cause deadlocks. Use 'await' instead of run_until_complete().
+    languages: [python]
+    severity: ERROR
+    metadata:
+      category: correctness
+      subcategory: [async]
+      likelihood: HIGH
+      impact: HIGH
+      confidence: HIGH
+
+  - id: missing-async-context-manager
+    patterns:
+      - pattern: |
+          async with $RESOURCE:
+            ...
+      - pattern-not: |
+          async with $RESOURCE as $VAR:
+            ...
+    message: |
+      Async context manager without variable binding. Consider binding the resource
+      to a variable for explicit resource management.
+    languages: [python]
+    severity: INFO
+    metadata:
+      category: best-practice
+      subcategory: [async]
+      likelihood: LOW
+      impact: LOW
+      confidence: MEDIUM
+
+  - id: sync-lock-in-async
+    patterns:
+      - pattern-either:
+          - pattern: threading.Lock()
+          - pattern: threading.RLock()
+          - pattern: threading.Semaphore()
+      - pattern-inside: |
+          async def $FUNC(...):
+            ...
+    message: |
+      Using synchronous lock in async function. Use asyncio.Lock() or
+      asyncio.Semaphore() instead to avoid blocking the event loop.
+    languages: [python]
+    severity: ERROR
+    metadata:
+      category: correctness
+      subcategory: [async, concurrency]
+      likelihood: HIGH
+      impact: HIGH
+      confidence: HIGH
+
+  - id: sequential-await-could-be-parallel
+    patterns:
+      - pattern: |
+          await $FUNC1(...)
+          await $FUNC2(...)
+      - pattern-not-inside: |
+          results = await asyncio.gather(
+            $FUNC1(...),
+            $FUNC2(...),
+          )
+    message: |
+      Sequential awaits that could be parallelized. If these operations are
+      independent, use asyncio.gather() to run them concurrently.
+    languages: [python]
+    severity: INFO
+    metadata:
+      category: performance
+      subcategory: [async]
+      likelihood: LOW
+      impact: LOW
+      confidence: LOW
+
+  - id: missing-cancellation-handling
+    patterns:
+      - pattern: |
+          async def $FUNC(...):
+            ...
+      - pattern-not-inside: |
+          try:
+            ...
+          except asyncio.CancelledError:
+            ...
+    message: |
+      Async function without cancellation handling. Long-running tasks should
+      handle CancelledError to clean up resources properly.
+    languages: [python]
+    severity: INFO
+    metadata:
+      category: best-practice
+      subcategory: [async, cleanup]
+      likelihood: LOW
+      impact: MEDIUM
+      confidence: LOW
+
+  - id: task-result-not-checked
+    patterns:
+      - pattern: |
+          $TASK = asyncio.create_task(...)
+          ...
+      - pattern-not: |
+          $TASK = asyncio.create_task(...)
+          ...
+          $RESULT = await $TASK
+      - pattern-not: |
+          $TASK = asyncio.create_task(...)
+          ...
+          $TASK.result()
+    message: |
+      Task created but result never checked. Background tasks may fail silently.
+      Await the task or check its result/exception.
+    languages: [python]
+    severity: WARNING
+    metadata:
+      category: correctness
+      subcategory: [async]
+      likelihood: MEDIUM
+      impact: MEDIUM
+      confidence: LOW

specfact_cli/sync/__init__.py

@@ -0,0 +1,12 @@
+"""
+Sync operations for SpecFact CLI.
+
+This module provides bidirectional synchronization between Spec-Kit artifacts,
+repository changes, and SpecFact plans.
+"""
+
+from specfact_cli.sync.repository_sync import RepositorySync, RepositorySyncResult
+from specfact_cli.sync.speckit_sync import SpecKitSync, SyncResult
+
+
+__all__ = ["RepositorySync", "RepositorySyncResult", "SpecKitSync", "SyncResult"]