lucidscan 0.5.12__py3-none-any.whl

lucidscan/core/models.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Union
+
+if TYPE_CHECKING:
+    from lucidscan.config.ignore import IgnorePatterns
+    from lucidscan.config.models import LucidScanConfig
+    from lucidscan.core.streaming import StreamHandler
+
+
+class ScanDomain(str, Enum):
+    """Scanning domains supported by lucidscan (security-focused)."""
+
+    SCA = "sca"
+    CONTAINER = "container"
+    IAC = "iac"
+    SAST = "sast"
+
+
+class ToolDomain(str, Enum):
+    """All tool domains supported by lucidscan pipeline.
+
+    This enum covers all types of tools in the quality pipeline:
+    linting, type checking, security scanning, testing, and coverage.
+    """
+
+    LINTING = "linting"
+    TYPE_CHECKING = "type_checking"
+    SECURITY = "security"
+    TESTING = "testing"
+    COVERAGE = "coverage"
+
+
+# Type alias for any domain type (ScanDomain or ToolDomain)
+DomainType = Union[ScanDomain, ToolDomain]
+
+
+class Severity(str, Enum):
+    """Unified severity levels used across all scanners."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+@dataclass
+class UnifiedIssue:
+    """Normalized issue representation shared by all tools.
+
+    This unified schema handles issues from all domains:
+    - Linting: code style and quality issues
+    - Type checking: type errors and warnings
+    - Security (SAST/SCA/IaC/Container): vulnerabilities and misconfigurations
+    - Testing: test failures
+    - Coverage: coverage gaps
+    """
+
+    # Core identification
+    id: str
+    domain: DomainType  # The domain category (linting, sast, sca, etc.)
+    source_tool: str  # The actual tool (ruff, trivy, mypy, etc.)
+    severity: Severity
+
+    # Content
+    rule_id: str  # Rule identifier (E501, CVE-2024-1234, CKV_AWS_1)
+    title: str
+    description: str
+    recommendation: Optional[str] = None
+    documentation_url: Optional[str] = None
+
+    # Location
+    file_path: Optional[Path] = None
+    line_start: Optional[int] = None
+    line_end: Optional[int] = None
+    column_start: Optional[int] = None
+    column_end: Optional[int] = None
+    code_snippet: Optional[str] = None
+
+    # Fix information
+    fixable: bool = False
+    suggested_fix: Optional[str] = None
+
+    # Domain-specific fields
+    dependency: Optional[str] = None  # For SCA (e.g., "lodash@4.17.20")
+    iac_resource: Optional[str] = None  # For IaC (e.g., "aws_s3_bucket.public")
+
+    # Extensibility
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ScanContext:
+    """Context provided to scanner plugins during scan execution.
+
+    Contains target paths, configuration, and scan settings needed
+    by plugins to execute their scans.
+    """
+
+    project_root: Path
+    paths: List[Path]
+    enabled_domains: Sequence[DomainType]
+    config: "LucidScanConfig" = None  # type: ignore[assignment]
+    ignore_patterns: Optional["IgnorePatterns"] = None
+    stream_handler: Optional["StreamHandler"] = None
+    # Coverage result populated after coverage analysis (for MCP/CLI access)
+    coverage_result: Any = None
+
+    def get_scanner_options(self, domain: str) -> Dict[str, Any]:
+        """Get plugin-specific options for a domain.
+
+        Args:
+            domain: Domain name (sca, sast, iac, container).
+
+        Returns:
+            Dictionary of plugin-specific options.
+        """
+        if self.config is None:
+            return {}
+        # Handle legacy dict-based config for backwards compatibility
+        if isinstance(self.config, dict):
+            return self.config
+        return self.config.get_scanner_options(domain)
+
+    def get_exclude_patterns(self) -> List[str]:
+        """Get ignore patterns for scanner exclude flags.
+
+        Returns:
+            List of patterns suitable for --exclude flags.
+        """
+        if self.ignore_patterns is None:
+            return []
+        return self.ignore_patterns.get_exclude_patterns()
+
+
+@dataclass
+class ScanMetadata:
+    """Metadata about the scan execution."""
+
+    lucidscan_version: str
+    scan_started_at: str
+    scan_finished_at: str
+    duration_ms: int
+    project_root: str
+    scanners_used: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class ScanSummary:
+    """Summary statistics for scan results."""
+
+    total: int = 0
+    by_severity: Dict[str, int] = field(default_factory=dict)
+    by_scanner: Dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class CoverageSummary:
+    """Summary of coverage analysis results."""
+
+    coverage_percentage: float = 0.0
+    threshold: float = 80.0
+    total_lines: int = 0
+    covered_lines: int = 0
+    missing_lines: int = 0
+    passed: bool = True
+    # Test statistics
+    tests_total: int = 0
+    tests_passed: int = 0
+    tests_failed: int = 0
+    tests_skipped: int = 0
+    tests_errors: int = 0
+
+
+@dataclass
+class ScanResult:
+    """Aggregated result for a scan over one project or path set."""
+
+    issues: List[UnifiedIssue] = field(default_factory=list)
+    schema_version: str = "1.0"
+    metadata: Optional[ScanMetadata] = None
+    summary: Optional[ScanSummary] = None
+    coverage_summary: Optional[CoverageSummary] = None
+
+    def compute_summary(self) -> ScanSummary:
+        """Compute summary statistics from issues."""
+        by_severity: Dict[str, int] = {}
+        by_domain: Dict[str, int] = {}
+
+        for issue in self.issues:
+            sev = issue.severity.value
+            by_severity[sev] = by_severity.get(sev, 0) + 1
+
+            domain = issue.domain.value
+            by_domain[domain] = by_domain.get(domain, 0) + 1
+
+        return ScanSummary(
+            total=len(self.issues),
+            by_severity=by_severity,
+            by_scanner=by_domain,  # Keep field name for backwards compatibility
+        )
+
+

lucidscan/core/streaming.py

@@ -0,0 +1,340 @@
+"""Stream handler abstraction for live output during scans.
+
+Provides a unified interface for streaming tool output to different targets:
+- CLI: Print to console with optional Rich formatting
+- MCP: Send notifications to AI agents
+- Null: No-op for backward compatibility
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Coroutine, Optional, TextIO, Any
+
+
+class StreamType(str, Enum):
+    """Type of stream output."""
+
+    STDOUT = "stdout"
+    STDERR = "stderr"
+    STATUS = "status"
+
+
+@dataclass
+class StreamEvent:
+    """A streaming event from a tool execution."""
+
+    tool_name: str
+    stream_type: StreamType
+    content: str
+    line_number: Optional[int] = None
+
+
+class StreamHandler(ABC):
+    """Abstract base class for stream handlers.
+
+    Implementations must be thread-safe as multiple tools may emit
+    events concurrently from different threads.
+    """
+
+    @abstractmethod
+    def emit(self, event: StreamEvent) -> None:
+        """Emit a stream event.
+
+        Args:
+            event: The stream event to emit.
+        """
+
+    @abstractmethod
+    def start_tool(self, tool_name: str) -> None:
+        """Signal that a tool has started execution.
+
+        Args:
+            tool_name: Name of the tool that started.
+        """
+
+    @abstractmethod
+    def end_tool(self, tool_name: str, success: bool) -> None:
+        """Signal that a tool has finished execution.
+
+        Args:
+            tool_name: Name of the tool that finished.
+            success: Whether the tool completed successfully.
+        """
+
+
+class NullStreamHandler(StreamHandler):
+    """No-op handler for backward compatibility.
+
+    Use this when streaming is not needed - all methods are no-ops.
+    """
+
+    def emit(self, event: StreamEvent) -> None:
+        """No-op emit."""
+        pass
+
+    def start_tool(self, tool_name: str) -> None:
+        """No-op start."""
+        pass
+
+    def end_tool(self, tool_name: str, success: bool) -> None:
+        """No-op end."""
+        pass
+
+
+class CLIStreamHandler(StreamHandler):
+    """Thread-safe CLI stream handler.
+
+    Streams tool output to the console with optional Rich formatting.
+    Shows both raw tool output and formatted status messages.
+    """
+
+    def __init__(
+        self,
+        output: TextIO = sys.stderr,
+        show_output: bool = True,
+        use_rich: bool = False,
+    ):
+        """Initialize CLIStreamHandler.
+
+        Args:
+            output: Output stream to write to (default: stderr).
+            show_output: Whether to show raw tool output lines.
+            use_rich: Whether to use Rich for formatted output.
+        """
+        self._output = output
+        self._show_output = show_output
+        self._use_rich = use_rich
+        self._lock = threading.Lock()
+        self._console = None
+
+        if use_rich:
+            try:
+                from rich.console import Console  # type: ignore[import-not-found]
+
+                self._console = Console(file=output, force_terminal=True)
+            except ImportError:
+                self._use_rich = False
+
+    def emit(self, event: StreamEvent) -> None:
+        """Emit a stream event to the console.
+
+        Args:
+            event: The stream event to emit.
+        """
+        if not self._show_output:
+            return
+
+        with self._lock:
+            if event.stream_type == StreamType.STATUS:
+                self._print_status(f"[{event.tool_name}] {event.content}")
+            else:
+                # Show raw output with tool prefix
+                prefix = f"  {event.tool_name}: "
+                self._print_line(prefix, event.content)
+
+    def start_tool(self, tool_name: str) -> None:
+        """Signal that a tool has started.
+
+        Args:
+            tool_name: Name of the tool that started.
+        """
+        with self._lock:
+            self._print_status(f"[{tool_name}] Starting...")
+
+    def end_tool(self, tool_name: str, success: bool) -> None:
+        """Signal that a tool has finished.
+
+        Args:
+            tool_name: Name of the tool that finished.
+            success: Whether the tool completed successfully.
+        """
+        with self._lock:
+            if success:
+                self._print_status(f"[{tool_name}] Done")
+            else:
+                self._print_status(f"[{tool_name}] Failed")
+
+    def _print_status(self, message: str) -> None:
+        """Print a status message.
+
+        Args:
+            message: The status message to print.
+        """
+        if self._console:
+            self._console.print(f"[bold cyan]{message}[/bold cyan]")
+        else:
+            print(message, file=self._output, flush=True)
+
+    def _print_line(self, prefix: str, content: str) -> None:
+        """Print a line of tool output.
+
+        Args:
+            prefix: Prefix to add before the content.
+            content: The content to print.
+        """
+        if self._console:
+            self._console.print(f"[dim]{prefix}[/dim]{content}")
+        else:
+            print(f"{prefix}{content}", file=self._output, flush=True)
+
+
+class CallbackStreamHandler(StreamHandler):
+    """Handler that invokes callbacks for stream events.
+
+    Useful for MCP or async contexts where events need to be
+    forwarded to another system.
+    """
+
+    def __init__(
+        self,
+        on_event: Optional[Callable[[StreamEvent], None]] = None,
+        on_start: Optional[Callable[[str], None]] = None,
+        on_end: Optional[Callable[[str, bool], None]] = None,
+    ):
+        """Initialize CallbackStreamHandler.
+
+        Args:
+            on_event: Callback for stream events.
+            on_start: Callback when a tool starts.
+            on_end: Callback when a tool ends.
+        """
+        self._on_event = on_event
+        self._on_start = on_start
+        self._on_end = on_end
+        self._lock = threading.Lock()
+
+    def emit(self, event: StreamEvent) -> None:
+        """Emit a stream event via callback.
+
+        Args:
+            event: The stream event to emit.
+        """
+        if self._on_event:
+            with self._lock:
+                self._on_event(event)
+
+    def start_tool(self, tool_name: str) -> None:
+        """Signal that a tool has started via callback.
+
+        Args:
+            tool_name: Name of the tool that started.
+        """
+        if self._on_start:
+            with self._lock:
+                self._on_start(tool_name)
+        # Also emit as event if callback registered
+        if self._on_event:
+            self.emit(
+                StreamEvent(
+                    tool_name=tool_name,
+                    stream_type=StreamType.STATUS,
+                    content="started",
+                )
+            )
+
+    def end_tool(self, tool_name: str, success: bool) -> None:
+        """Signal that a tool has finished via callback.
+
+        Args:
+            tool_name: Name of the tool that finished.
+            success: Whether the tool completed successfully.
+        """
+        if self._on_end:
+            with self._lock:
+                self._on_end(tool_name, success)
+        # Also emit as event if callback registered
+        if self._on_event:
+            status = "completed" if success else "failed"
+            self.emit(
+                StreamEvent(
+                    tool_name=tool_name,
+                    stream_type=StreamType.STATUS,
+                    content=status,
+                )
+            )
+
+
+# Type alias for async callbacks
+AsyncEventCallback = Callable[[StreamEvent], Coroutine[Any, Any, None]]
+
+
+class MCPStreamHandler(StreamHandler):
+    """Handler that streams events via async MCP notifications.
+
+    This handler bridges synchronous tool execution (running in thread pool)
+    with async MCP notification delivery. It captures the event loop at
+    construction time and uses run_coroutine_threadsafe to schedule
+    async callbacks from synchronous contexts.
+    """
+
+    def __init__(
+        self,
+        on_event: AsyncEventCallback,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ):
+        """Initialize MCPStreamHandler.
+
+        Args:
+            on_event: Async callback for stream events.
+            loop: Event loop to use. If None, uses the running loop.
+        """
+        self._on_event = on_event
+        self._loop = loop or asyncio.get_running_loop()
+        self._lock = threading.Lock()
+
+    def _schedule_async(self, coro: Coroutine[Any, Any, None]) -> None:
+        """Schedule an async coroutine from a sync context.
+
+        Args:
+            coro: Coroutine to schedule.
+        """
+        try:
+            asyncio.run_coroutine_threadsafe(coro, self._loop)
+        except RuntimeError:
+            # Loop might be closed, ignore
+            pass
+
+    def emit(self, event: StreamEvent) -> None:
+        """Emit a stream event via async MCP callback.
+
+        Args:
+            event: The stream event to emit.
+        """
+        with self._lock:
+            self._schedule_async(self._on_event(event))
+
+    def start_tool(self, tool_name: str) -> None:
+        """Signal that a tool has started.
+
+        Args:
+            tool_name: Name of the tool that started.
+        """
+        self.emit(
+            StreamEvent(
+                tool_name=tool_name,
+                stream_type=StreamType.STATUS,
+                content="started",
+            )
+        )
+
+    def end_tool(self, tool_name: str, success: bool) -> None:
+        """Signal that a tool has finished.
+
+        Args:
+            tool_name: Name of the tool that finished.
+            success: Whether the tool completed successfully.
+        """
+        status = "completed" if success else "failed"
+        self.emit(
+            StreamEvent(
+                tool_name=tool_name,
+                stream_type=StreamType.STATUS,
+                content=status,
+            )
+        )

lucidscan/core/subprocess_runner.py

@@ -0,0 +1,164 @@
+"""Subprocess runner with streaming support.
+
+Provides utilities for running external tools with real-time output streaming.
+"""
+
+from __future__ import annotations
+
+import queue
+import subprocess
+import threading
+from pathlib import Path
+from typing import List, Optional, Union
+
+from lucidscan.core.streaming import (
+    NullStreamHandler,
+    StreamEvent,
+    StreamHandler,
+    StreamType,
+)
+
+
+def run_with_streaming(
+    cmd: List[str],
+    cwd: Union[str, Path],
+    tool_name: str,
+    stream_handler: Optional[StreamHandler] = None,
+    timeout: int = 120,
+    capture_output: bool = True,
+) -> subprocess.CompletedProcess:
+    """Run a command with optional streaming output.
+
+    This function runs a subprocess and optionally streams its output
+    line-by-line to a StreamHandler. When streaming is enabled, output
+    is still captured and returned in the CompletedProcess for parsing.
+
+    Args:
+        cmd: Command and arguments to run.
+        cwd: Working directory for the command.
+        tool_name: Name of the tool (used in stream events).
+        stream_handler: Handler for streaming output. If None or NullStreamHandler,
+            uses regular subprocess.run for efficiency.
+        timeout: Timeout in seconds (default: 120).
+        capture_output: Whether to capture output (default: True). If False and
+            streaming is enabled, output goes only to the stream handler.
+
+    Returns:
+        CompletedProcess with stdout/stderr captured (if capture_output=True).
+
+    Raises:
+        subprocess.TimeoutExpired: If the command times out.
+        subprocess.SubprocessError: If the command fails to start.
+    """
+    handler = stream_handler or NullStreamHandler()
+    cwd_str = str(cwd)
+
+    # If no streaming requested, use simple subprocess.run for efficiency
+    if isinstance(handler, NullStreamHandler):
+        return subprocess.run(
+            cmd,
+            capture_output=capture_output,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=cwd_str,
+            timeout=timeout,
+        )
+
+    # Streaming mode with Popen
+    handler.start_tool(tool_name)
+
+    stdout_lines: List[str] = []
+    stderr_lines: List[str] = []
+
+    try:
+        with subprocess.Popen(  # nosemgrep: python36-compatibility-Popen1, python36-compatibility-Popen2
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=cwd_str,
+        ) as proc:
+            # Use a queue to collect output from both streams
+            output_queue: queue.Queue = queue.Queue()
+
+            def read_stream(
+                stream,
+                stream_type: StreamType,
+                lines_list: List[str],
+            ) -> None:
+                """Read lines from a stream and put them in the queue."""
+                try:
+                    for line_num, line in enumerate(stream, 1):
+                        line = line.rstrip("\n\r")
+                        lines_list.append(line)
+                        output_queue.put((stream_type, line, line_num))
+                except Exception:
+                    pass
+                finally:
+                    # Signal EOF for this stream
+                    output_queue.put((stream_type, None, None))
+
+            # Start reader threads for stdout and stderr
+            stdout_thread = threading.Thread(
+                target=read_stream,
+                args=(proc.stdout, StreamType.STDOUT, stdout_lines),
+                daemon=True,
+            )
+            stderr_thread = threading.Thread(
+                target=read_stream,
+                args=(proc.stderr, StreamType.STDERR, stderr_lines),
+                daemon=True,
+            )
+
+            stdout_thread.start()
+            stderr_thread.start()
+
+            # Process output as it arrives
+            streams_closed = 0
+            while streams_closed < 2:
+                try:
+                    stream_type, line, line_num = output_queue.get(timeout=timeout)
+                    if line is None:
+                        streams_closed += 1
+                    else:
+                        handler.emit(
+                            StreamEvent(
+                                tool_name=tool_name,
+                                stream_type=stream_type,
+                                content=line,
+                                line_number=line_num,
+                            )
+                        )
+                except queue.Empty:
+                    # Timeout waiting for output
+                    proc.kill()
+                    handler.end_tool(tool_name, False)
+                    raise subprocess.TimeoutExpired(cmd, timeout)
+
+            # Wait for reader threads to finish
+            stdout_thread.join(timeout=1)
+            stderr_thread.join(timeout=1)
+
+            # Wait for process to complete
+            proc.wait()
+
+            success = proc.returncode == 0
+            handler.end_tool(tool_name, success)
+
+            # Return CompletedProcess with captured output
+            return subprocess.CompletedProcess(
+                args=cmd,
+                returncode=proc.returncode,
+                stdout="\n".join(stdout_lines) if capture_output else "",
+                stderr="\n".join(stderr_lines) if capture_output else "",
+            )
+
+    except subprocess.TimeoutExpired:
+        handler.end_tool(tool_name, False)
+        raise
+    except Exception as e:
+        handler.end_tool(tool_name, False)
+        raise subprocess.SubprocessError(f"Failed to run {tool_name}: {e}") from e