lucidscan 0.5.12__py3-none-any.whl

lucidscan/plugins/coverage/istanbul.py

@@ -0,0 +1,411 @@
+"""Istanbul/NYC coverage plugin.
+
+Istanbul (via NYC) is a JavaScript code coverage tool.
+https://istanbul.js.org/
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from lucidscan.core.logging import get_logger
+from lucidscan.core.models import (
+    ScanContext,
+    Severity,
+    ToolDomain,
+    UnifiedIssue,
+)
+from lucidscan.plugins.coverage.base import (
+    CoveragePlugin,
+    CoverageResult,
+    FileCoverage,
+)
+
+LOGGER = get_logger(__name__)
+
+
+class IstanbulPlugin(CoveragePlugin):
+    """Istanbul/NYC coverage plugin for JavaScript/TypeScript coverage analysis."""
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize IstanbulPlugin.
+
+        Args:
+            project_root: Optional project root for finding NYC installation.
+        """
+        self._project_root = project_root
+
+    @property
+    def name(self) -> str:
+        """Plugin identifier."""
+        return "istanbul"
+
+    @property
+    def languages(self) -> List[str]:
+        """Supported languages."""
+        return ["javascript", "typescript"]
+
+    def get_version(self) -> str:
+        """Get NYC version.
+
+        Returns:
+            Version string or 'unknown' if unable to determine.
+        """
+        try:
+            binary = self.ensure_binary()
+            result = subprocess.run(
+                [str(binary), "--version"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            # Output is just the version number like "15.1.0"
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            pass
+        return "unknown"
+
+    def ensure_binary(self) -> Path:
+        """Ensure NYC is available.
+
+        Checks for NYC in:
+        1. Project's node_modules/.bin/nyc
+        2. System PATH (globally installed)
+
+        Returns:
+            Path to NYC binary.
+
+        Raises:
+            FileNotFoundError: If NYC is not installed.
+        """
+        # Check project node_modules first
+        if self._project_root:
+            node_nyc = self._project_root / "node_modules" / ".bin" / "nyc"
+            if node_nyc.exists():
+                return node_nyc
+
+        # Check system PATH
+        nyc_path = shutil.which("nyc")
+        if nyc_path:
+            return Path(nyc_path)
+
+        raise FileNotFoundError(
+            "NYC (Istanbul) is not installed. Install it with:\n"
+            "  npm install nyc --save-dev\n"
+            "  OR\n"
+            "  npm install -g nyc"
+        )
+
+    def measure_coverage(
+        self,
+        context: ScanContext,
+        threshold: float = 80.0,
+        run_tests: bool = True,
+    ) -> CoverageResult:
+        """Run coverage analysis on the specified paths.
+
+        Args:
+            context: Scan context with paths and configuration.
+            threshold: Coverage percentage threshold (default 80%).
+            run_tests: Whether to run tests if no existing coverage data exists.
+
+        Returns:
+            CoverageResult with coverage statistics and issues if below threshold.
+        """
+        try:
+            binary = self.ensure_binary()
+        except FileNotFoundError as e:
+            LOGGER.warning(str(e))
+            return CoverageResult(threshold=threshold)
+
+        # Always run tests fresh when run_tests=True to ensure accurate coverage
+        if run_tests:
+            LOGGER.info("Running tests with coverage...")
+            if not self._run_tests_with_coverage(binary, context):
+                LOGGER.warning("Failed to run tests with coverage")
+                return CoverageResult(threshold=threshold)
+
+        # Generate JSON report from coverage data
+        result = self._generate_and_parse_report(binary, context, threshold)
+
+        return result
+
+    def _run_tests_with_coverage(
+        self,
+        binary: Path,
+        context: ScanContext,
+    ) -> bool:
+        """Run tests with NYC coverage.
+
+        Args:
+            binary: Path to NYC binary.
+            context: Scan context.
+
+        Returns:
+            True if tests ran successfully.
+        """
+        # Check for jest or npm test
+        jest_path = None
+        if self._project_root:
+            node_jest = self._project_root / "node_modules" / ".bin" / "jest"
+            if node_jest.exists():
+                jest_path = node_jest
+
+        if not jest_path:
+            jest_which = shutil.which("jest")
+            if jest_which:
+                jest_path = Path(jest_which)
+
+        if jest_path:
+            # Run nyc jest
+            cmd = [str(binary), str(jest_path), "--passWithNoTests"]
+        else:
+            # Fall back to npm test
+            cmd = [str(binary), "npm", "test"]
+
+        LOGGER.debug(f"Running: {' '.join(cmd)}")
+
+        try:
+            subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=str(context.project_root),
+            )
+            return True
+        except Exception as e:
+            LOGGER.error(f"Failed to run tests with coverage: {e}")
+            return False
+
+    def _generate_and_parse_report(
+        self,
+        binary: Path,
+        context: ScanContext,
+        threshold: float,
+    ) -> CoverageResult:
+        """Generate JSON report and parse it.
+
+        Args:
+            binary: Path to NYC binary.
+            context: Scan context.
+            threshold: Coverage percentage threshold.
+
+        Returns:
+            CoverageResult with parsed data.
+        """
+        with tempfile.TemporaryDirectory() as tmpdir:
+            report_dir = Path(tmpdir)
+
+            cmd = [
+                str(binary),
+                "report",
+                "--reporter=json-summary",
+                f"--report-dir={report_dir}",
+            ]
+
+            LOGGER.debug(f"Running: {' '.join(cmd)}")
+
+            try:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    cwd=str(context.project_root),
+                )
+
+                if result.returncode != 0:
+                    LOGGER.warning(f"NYC report failed: {result.stderr}")
+                    return CoverageResult(threshold=threshold)
+
+            except Exception as e:
+                LOGGER.error(f"Failed to generate coverage report: {e}")
+                return CoverageResult(threshold=threshold)
+
+            # Parse JSON report
+            report_file = report_dir / "coverage-summary.json"
+            if report_file.exists():
+                return self._parse_json_report(report_file, context.project_root, threshold)
+            else:
+                LOGGER.warning("Coverage JSON report not generated")
+                return CoverageResult(threshold=threshold)
+
+    def _parse_json_report(
+        self,
+        report_file: Path,
+        project_root: Path,
+        threshold: float,
+    ) -> CoverageResult:
+        """Parse Istanbul JSON summary report.
+
+        Args:
+            report_file: Path to JSON report file.
+            project_root: Project root directory.
+            threshold: Coverage percentage threshold.
+
+        Returns:
+            CoverageResult with parsed data.
+        """
+        try:
+            with open(report_file) as f:
+                report = json.load(f)
+        except Exception as e:
+            LOGGER.error(f"Failed to parse Istanbul JSON report: {e}")
+            return CoverageResult(threshold=threshold)
+
+        # Get total statistics
+        total = report.get("total", {})
+        lines = total.get("lines", {})
+        statements = total.get("statements", {})
+        branches = total.get("branches", {})
+        functions = total.get("functions", {})
+
+        # Calculate overall coverage (use lines as primary metric)
+        total_lines = lines.get("total", 0)
+        covered_lines = lines.get("covered", 0)
+        percent_covered = lines.get("pct", 0.0)
+
+        result = CoverageResult(
+            total_lines=total_lines,
+            covered_lines=covered_lines,
+            missing_lines=total_lines - covered_lines,
+            excluded_lines=0,
+            threshold=threshold,
+        )
+
+        # Parse per-file coverage (all keys except "total")
+        for file_path, file_data in report.items():
+            if file_path == "total":
+                continue
+
+            file_lines = file_data.get("lines", {})
+            file_total = file_lines.get("total", 0)
+            file_covered = file_lines.get("covered", 0)
+
+            file_coverage = FileCoverage(
+                file_path=project_root / file_path,
+                total_lines=file_total,
+                covered_lines=file_covered,
+                missing_lines=[],  # Istanbul doesn't provide specific line numbers in summary
+                excluded_lines=0,
+            )
+            result.files[file_path] = file_coverage
+
+        # Generate issue if below threshold
+        if percent_covered < threshold:
+            issue = self._create_coverage_issue(
+                percent_covered,
+                threshold,
+                total_lines,
+                covered_lines,
+                total_lines - covered_lines,
+                statements,
+                branches,
+                functions,
+            )
+            result.issues.append(issue)
+
+        LOGGER.info(
+            f"Coverage: {percent_covered:.1f}% ({covered_lines}/{total_lines} lines) "
+            f"- threshold: {threshold}%"
+        )
+
+        return result
+
+    def _create_coverage_issue(
+        self,
+        percentage: float,
+        threshold: float,
+        total_lines: int,
+        covered_lines: int,
+        missing_lines: int,
+        statements: Dict[str, Any],
+        branches: Dict[str, Any],
+        functions: Dict[str, Any],
+    ) -> UnifiedIssue:
+        """Create a UnifiedIssue for coverage below threshold.
+
+        Args:
+            percentage: Actual coverage percentage.
+            threshold: Required coverage threshold.
+            total_lines: Total number of lines.
+            covered_lines: Number of covered lines.
+            missing_lines: Number of missing lines.
+            statements: Statement coverage data.
+            branches: Branch coverage data.
+            functions: Function coverage data.
+
+        Returns:
+            UnifiedIssue for coverage failure.
+        """
+        # Determine severity based on how far below threshold
+        if percentage < 50:
+            severity = Severity.HIGH
+        elif percentage < threshold - 10:
+            severity = Severity.MEDIUM
+        else:
+            severity = Severity.LOW
+
+        # Generate deterministic ID
+        issue_id = self._generate_issue_id(percentage, threshold)
+
+        gap = threshold - percentage
+
+        return UnifiedIssue(
+            id=issue_id,
+            domain=ToolDomain.COVERAGE,
+            source_tool="istanbul",
+            severity=severity,
+            rule_id="coverage_below_threshold",
+            title=f"Coverage {percentage:.1f}% is below threshold {threshold}%",
+            description=(
+                f"Project coverage is {percentage:.1f}%, which is {gap:.1f}% below "
+                f"the required threshold of {threshold}%. "
+                f"Lines: {covered_lines}/{total_lines} ({percentage:.1f}%), "
+                f"Statements: {statements.get('covered', 0)}/{statements.get('total', 0)} ({statements.get('pct', 0):.1f}%), "
+                f"Branches: {branches.get('covered', 0)}/{branches.get('total', 0)} ({branches.get('pct', 0):.1f}%), "
+                f"Functions: {functions.get('covered', 0)}/{functions.get('total', 0)} ({functions.get('pct', 0):.1f}%)"
+            ),
+            recommendation=f"Add tests to cover at least {gap:.1f}% more of the codebase.",
+            file_path=None,  # Project-level issue
+            line_start=None,
+            line_end=None,
+            fixable=False,
+            metadata={
+                "coverage_percentage": round(percentage, 2),
+                "threshold": threshold,
+                "total_lines": total_lines,
+                "covered_lines": covered_lines,
+                "missing_lines": missing_lines,
+                "gap_percentage": round(gap, 2),
+                "statements": statements,
+                "branches": branches,
+                "functions": functions,
+            },
+        )
+
+    def _generate_issue_id(self, percentage: float, threshold: float) -> str:
+        """Generate deterministic issue ID.
+
+        Args:
+            percentage: Coverage percentage.
+            threshold: Coverage threshold.
+
+        Returns:
+            Unique issue ID.
+        """
+        # ID based on rounded percentage and threshold for stability
+        content = f"istanbul:{round(percentage)}:{threshold}"
+        hash_val = hashlib.sha256(content.encode()).hexdigest()[:12]
+        return f"istanbul-{hash_val}"

lucidscan/plugins/discovery.py

@@ -0,0 +1,107 @@
+"""Plugin discovery via Python entry points.
+
+Supports discovering different plugin types:
+- Scanner plugins: lucidscan.scanners
+- Enricher plugins: lucidscan.enrichers (future)
+- Reporter plugins: lucidscan.reporters (future)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from typing import Dict, List, Type, TypeVar
+
+from lucidscan.core.logging import get_logger
+
+LOGGER = get_logger(__name__)
+
+# Entry point group names for different plugin types
+SCANNER_ENTRY_POINT_GROUP = "lucidscan.scanners"
+ENRICHER_ENTRY_POINT_GROUP = "lucidscan.enrichers"
+REPORTER_ENTRY_POINT_GROUP = "lucidscan.reporters"
+
+# New plugin groups for v0.2+ quality pipeline
+LINTER_ENTRY_POINT_GROUP = "lucidscan.linters"
+TYPE_CHECKER_ENTRY_POINT_GROUP = "lucidscan.type_checkers"
+TEST_RUNNER_ENTRY_POINT_GROUP = "lucidscan.test_runners"
+COVERAGE_ENTRY_POINT_GROUP = "lucidscan.coverage"
+
+T = TypeVar("T")
+
+
+def discover_plugins(group: str, base_class: Type[T] | None = None) -> Dict[str, Type[T]]:
+    """Discover all installed plugins for a given entry point group.
+
+    Plugins register themselves in their pyproject.toml:
+
+        [project.entry-points."lucidscan.scanners"]
+        trivy = "lucidscan.scanners.trivy:TrivyScanner"
+
+    Args:
+        group: Entry point group name (e.g., 'lucidscan.scanners').
+        base_class: Optional base class to validate plugins against.
+
+    Returns:
+        Dictionary mapping plugin names to plugin classes.
+    """
+    plugins: Dict[str, Type[T]] = {}
+
+    try:
+        eps = entry_points(group=group)
+    except TypeError:
+        # Python 3.9 compatibility
+        all_eps = entry_points()
+        eps = getattr(all_eps, group, [])  # type: ignore[assignment]
+
+    for ep in eps:
+        try:
+            plugin_class = ep.load()
+            if base_class is not None and not issubclass(plugin_class, base_class):
+                LOGGER.warning(
+                    f"Plugin '{ep.name}' does not inherit from {base_class.__name__}, skipping"
+                )
+                continue
+            plugins[ep.name] = plugin_class
+            LOGGER.debug(f"Discovered plugin: {ep.name} (group: {group})")
+        except Exception as e:
+            LOGGER.warning(f"Failed to load plugin '{ep.name}': {e}")
+
+    return plugins
+
+
+def get_plugin(
+    group: str,
+    name: str,
+    base_class: Type[T] | None = None,
+    **kwargs,
+) -> T | None:
+    """Get an instantiated plugin by name.
+
+    Args:
+        group: Entry point group name.
+        name: Plugin name (e.g., 'trivy').
+        base_class: Optional base class to validate against.
+        **kwargs: Additional arguments to pass to the plugin constructor.
+                  Common kwargs include:
+                  - project_root: Path to project root for tool installation.
+
+    Returns:
+        Instantiated plugin or None if not found.
+    """
+    plugins = discover_plugins(group, base_class)
+    plugin_class = plugins.get(name)
+    if plugin_class:
+        return plugin_class(**kwargs)
+    return None
+
+
+def list_available_plugins(group: str) -> List[str]:
+    """List names of all available plugins in a group.
+
+    Args:
+        group: Entry point group name.
+
+    Returns:
+        List of plugin names.
+    """
+    return list(discover_plugins(group).keys())

lucidscan/plugins/enrichers/__init__.py

@@ -0,0 +1,61 @@
+"""Enricher plugins for lucidscan post-processing.
+
+Enricher plugins process scan results after scanner execution,
+adding context, metadata, or performing transformations like
+deduplication or AI-powered explanations.
+
+Plugins are discovered via Python entry points (lucidscan.enrichers group).
+
+Example registration in pyproject.toml:
+    [project.entry-points."lucidscan.enrichers"]
+    dedup = "lucidscan_dedup:DedupEnricher"
+    epss = "lucidscan_epss:EPSSEnricher"
+"""
+
+from typing import Dict, List, Optional, Type
+
+from lucidscan.plugins.enrichers.base import EnricherPlugin
+from lucidscan.plugins.discovery import (
+    ENRICHER_ENTRY_POINT_GROUP,
+    discover_plugins,
+    get_plugin,
+    list_available_plugins as _list_plugins,
+)
+
+
+def discover_enricher_plugins() -> Dict[str, Type[EnricherPlugin]]:
+    """Discover all installed enricher plugins via entry points.
+
+    Returns:
+        Dictionary mapping plugin names to plugin classes.
+    """
+    return discover_plugins(ENRICHER_ENTRY_POINT_GROUP, EnricherPlugin)
+
+
+def get_enricher_plugin(name: str) -> Optional[EnricherPlugin]:
+    """Get an instantiated enricher plugin by name.
+
+    Args:
+        name: Plugin name (e.g., 'dedup', 'epss').
+
+    Returns:
+        Instantiated EnricherPlugin or None if not found.
+    """
+    return get_plugin(ENRICHER_ENTRY_POINT_GROUP, name, EnricherPlugin)
+
+
+def list_available_enrichers() -> List[str]:
+    """List names of all available enricher plugins.
+
+    Returns:
+        List of enricher plugin names.
+    """
+    return _list_plugins(ENRICHER_ENTRY_POINT_GROUP)
+
+
+__all__ = [
+    "EnricherPlugin",
+    "discover_enricher_plugins",
+    "get_enricher_plugin",
+    "list_available_enrichers",
+]

lucidscan/plugins/enrichers/base.py

@@ -0,0 +1,63 @@
+"""Base class for enricher plugins."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from lucidscan.core.models import ScanContext, UnifiedIssue
+
+
+class EnricherPlugin(ABC):
+    """Base class for all enricher plugins.
+
+    Enricher plugins process issues after scanning, adding additional
+    context, metadata, or performing transformations. They run sequentially
+    in the configured order, with each enricher receiving the output of
+    the previous one.
+
+    Example enrichers:
+    - Deduplication: Remove duplicate issues across scanners
+    - EPSS scoring: Add exploit prediction scores
+    - KEV tagging: Mark known exploited vulnerabilities
+    - AI explanation: Add LLM-generated explanations
+
+    Enricher constraints:
+    - Enrichers MUST NOT modify severity levels set by scanners
+    - Enrichers MUST NOT affect exit codes (that's the CLI's responsibility)
+    - Enrichers MAY filter, augment, or reorder issues
+    - Enrichers SHOULD preserve scanner_metadata from original issues
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Enricher identifier (e.g., 'dedup', 'epss', 'kev').
+
+        This name is used for:
+        - Plugin discovery via entry points
+        - Configuration in .lucidscan.yml
+        - Logging and error messages
+        """
+
+    @abstractmethod
+    def enrich(
+        self,
+        issues: List["UnifiedIssue"],
+        context: "ScanContext",
+    ) -> List["UnifiedIssue"]:
+        """Process and enrich issues.
+
+        Args:
+            issues: List of issues from scanner execution (or previous enricher).
+            context: Scan context with project info and configuration.
+
+        Returns:
+            Enriched list of issues. May be modified, filtered, augmented,
+            or returned unchanged.
+
+        Raises:
+            Any exception raised will be logged and the enricher skipped,
+            with the pipeline continuing with unenriched issues.
+        """

lucidscan/plugins/linters/__init__.py

@@ -0,0 +1,26 @@
+"""Linter plugins for lucidscan.
+
+This module provides linter integrations for the quality pipeline.
+Linters are discovered via the lucidscan.linters entry point group.
+"""
+
+from lucidscan.plugins.linters.base import LinterPlugin
+from lucidscan.plugins.discovery import (
+    discover_plugins,
+    LINTER_ENTRY_POINT_GROUP,
+)
+
+
+def discover_linter_plugins():
+    """Discover all installed linter plugins.
+
+    Returns:
+        Dictionary mapping plugin names to plugin classes.
+    """
+    return discover_plugins(LINTER_ENTRY_POINT_GROUP, LinterPlugin)
+
+
+__all__ = [
+    "LinterPlugin",
+    "discover_linter_plugins",
+]