shannon-codebase-insight 0.4.0__py3-none-any.whl

shannon_insight/exceptions/config.py

@@ -0,0 +1,48 @@
+"""Configuration and security exceptions: paths, settings, access control."""
+
+from pathlib import Path
+from typing import Optional, Any
+
+from .base import ShannonInsightError
+
+
+class ConfigurationError(ShannonInsightError):
+    """Base class for configuration-related errors."""
+    pass
+
+
+class InvalidPathError(ConfigurationError):
+    """Raised when a provided path is invalid."""
+
+    def __init__(self, path: Path, reason: str):
+        super().__init__(
+            f"Invalid path: {path}", details={"path": str(path), "reason": reason}
+        )
+        self.path = path
+        self.reason = reason
+
+
+class InvalidConfigError(ConfigurationError):
+    """Raised when configuration values are invalid."""
+
+    def __init__(self, key: str, value: Any, reason: str):
+        super().__init__(
+            f"Invalid configuration for {key}: {value}",
+            details={"key": key, "value": str(value), "reason": reason},
+        )
+        self.key = key
+        self.value = value
+        self.reason = reason
+
+
+class SecurityError(ConfigurationError):
+    """Raised when a security violation is detected."""
+
+    def __init__(self, reason: str, filepath: Optional[Path] = None):
+        details = {"reason": reason}
+        if filepath:
+            details["filepath"] = str(filepath)
+
+        super().__init__(f"Security violation: {reason}", details=details)
+        self.reason = reason
+        self.filepath = filepath

shannon_insight/file_ops.py

@@ -0,0 +1,218 @@
+"""
+Safe file operations for Shannon Insight.
+
+Provides timeout-protected and size-limited file operations.
+"""
+
+import signal
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, List, Optional
+
+from .exceptions import FileAccessError, SecurityError
+from .security import PathValidator, ResourceLimiter
+
+
+class TimeoutError(Exception):
+    """Raised when an operation times out."""
+    pass
+
+
+def _timeout_handler(signum, frame):
+    """Signal handler for timeout."""
+    raise TimeoutError("Operation timed out")
+
+
+@contextmanager
+def timeout(seconds: int):
+    """
+    Context manager for timeout protection.
+
+    Args:
+        seconds: Timeout in seconds
+
+    Raises:
+        TimeoutError: If operation exceeds timeout
+    """
+    # Set up signal handler
+    old_handler = signal.signal(signal.SIGALRM, _timeout_handler)
+    signal.alarm(seconds)
+
+    try:
+        yield
+    finally:
+        # Restore old handler and cancel alarm
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, old_handler)
+
+
+def safe_read_file(
+    filepath: Path,
+    validator: Optional[PathValidator] = None,
+    limiter: Optional[ResourceLimiter] = None,
+    timeout_seconds: int = 10,
+    encoding: str = 'utf-8',
+    errors: str = 'replace'
+) -> str:
+    """
+    Safely read a file with security checks and timeout protection.
+
+    Args:
+        filepath: File to read
+        validator: Path validator (if None, skips path validation)
+        limiter: Resource limiter (if None, skips size check)
+        timeout_seconds: Timeout in seconds
+        encoding: Text encoding
+        errors: How to handle encoding errors
+
+    Returns:
+        File contents as string
+
+    Raises:
+        FileAccessError: If file cannot be read
+        SecurityError: If security checks fail
+        TimeoutError: If read operation times out
+    """
+    # Validate path
+    if validator:
+        filepath = validator.validate_path(filepath)
+
+    # Check file size
+    if limiter:
+        limiter.check_file_size(filepath)
+
+    # Read with timeout protection
+    try:
+        with timeout(timeout_seconds):
+            with open(filepath, 'r', encoding=encoding, errors=errors) as f:
+                return f.read()
+    except TimeoutError:
+        raise FileAccessError(filepath, f"Read operation timed out after {timeout_seconds}s")
+    except UnicodeDecodeError as e:
+        raise FileAccessError(filepath, f"Encoding error: {e}")
+    except OSError as e:
+        raise FileAccessError(filepath, f"OS error: {e}")
+    except Exception as e:
+        raise FileAccessError(filepath, f"Unexpected error: {e}")
+
+
+def safe_scan_directory(
+    root_dir: Path,
+    pattern: str = "**/*",
+    validator: Optional[PathValidator] = None,
+    limiter: Optional[ResourceLimiter] = None,
+    follow_symlinks: bool = False
+) -> Generator[Path, None, None]:
+    """
+    Safely scan a directory with security checks.
+
+    Args:
+        root_dir: Directory to scan
+        pattern: Glob pattern
+        validator: Path validator
+        limiter: Resource limiter
+        follow_symlinks: Whether to follow symbolic links
+
+    Yields:
+        Safe file paths
+
+    Raises:
+        SecurityError: If resource limits are exceeded
+    """
+    # Validate root directory
+    if validator:
+        root_dir = validator.validate_path(root_dir)
+
+    try:
+        for path in root_dir.glob(pattern):
+            # Skip symlinks if not following them
+            if path.is_symlink() and not follow_symlinks:
+                continue
+
+            # Skip directories
+            if path.is_dir():
+                continue
+
+            # Check file count limit
+            if limiter:
+                limiter.increment_file_count()
+
+            # Validate path
+            if validator:
+                try:
+                    path = validator.validate_path(path)
+                except (SecurityError, Exception):
+                    # Skip files that fail validation
+                    continue
+
+            # Check file size
+            if limiter:
+                try:
+                    limiter.check_file_size(path)
+                except SecurityError:
+                    # Skip files that exceed size limit
+                    continue
+
+            yield path
+
+    except OSError as e:
+        raise FileAccessError(root_dir, f"Directory scan failed: {e}")
+
+
+def safe_write_file(
+    filepath: Path,
+    content: str,
+    validator: Optional[PathValidator] = None,
+    encoding: str = 'utf-8'
+) -> None:
+    """
+    Safely write to a file with validation.
+
+    Args:
+        filepath: File to write
+        content: Content to write
+        validator: Path validator
+        encoding: Text encoding
+
+    Raises:
+        FileAccessError: If file cannot be written
+        SecurityError: If security checks fail
+    """
+    # Validate path (parent directory)
+    if validator:
+        parent = filepath.parent
+        if parent.exists():
+            validator.validate_path(parent)
+
+    try:
+        # Create parent directory if it doesn't exist
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write file
+        with open(filepath, 'w', encoding=encoding) as f:
+            f.write(content)
+
+    except OSError as e:
+        raise FileAccessError(filepath, f"Write failed: {e}")
+    except Exception as e:
+        raise FileAccessError(filepath, f"Unexpected error: {e}")
+
+
+def should_skip_file(
+    filepath: Path,
+    exclude_patterns: List[str]
+) -> bool:
+    """
+    Check if a file should be skipped based on exclusion patterns.
+
+    Args:
+        filepath: File to check
+        exclude_patterns: List of glob patterns to exclude
+
+    Returns:
+        True if file should be skipped
+    """
+    for pattern in exclude_patterns:
+        if filepath.match(pattern):
+            return True
+    return False

shannon_insight/logging_config.py

@@ -0,0 +1,98 @@
+"""
+Logging configuration for Shannon Insight.
+
+Provides structured logging with rich formatting for beautiful terminal output.
+"""
+
+import logging
+import sys
+from typing import Optional
+
+from rich.logging import RichHandler
+from rich.console import Console
+
+
+def setup_logging(
+    verbose: bool = False,
+    quiet: bool = False,
+    log_file: Optional[str] = None
+) -> logging.Logger:
+    """
+    Configure logging with rich handler for colored output.
+
+    Args:
+        verbose: Enable DEBUG level logging
+        quiet: Suppress all but ERROR level logging
+        log_file: Optional file path to write logs to
+
+    Returns:
+        Configured logger instance for shannon_insight
+    """
+    # Determine log level
+    if quiet:
+        level = logging.ERROR
+    elif verbose:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+
+    # Create rich console for logging
+    console = Console(stderr=True)
+
+    # Configure handlers
+    handlers = [
+        RichHandler(
+            console=console,
+            rich_tracebacks=True,
+            tracebacks_show_locals=verbose,
+            markup=True,
+            show_time=True,
+            show_path=verbose,
+        )
+    ]
+
+    # Add file handler if specified
+    if log_file:
+        file_handler = logging.FileHandler(log_file, mode='a')
+        file_handler.setFormatter(
+            logging.Formatter(
+                '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                datefmt='%Y-%m-%d %H:%M:%S'
+            )
+        )
+        handlers.append(file_handler)
+
+    # Configure root logger
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=handlers
+    )
+
+    # Get shannon_insight logger
+    logger = logging.getLogger("shannon_insight")
+    logger.setLevel(level)
+
+    return logger
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Get a logger instance for a specific module.
+
+    Args:
+        name: Module name (e.g., 'shannon_insight.core')
+              If None, returns the root shannon_insight logger
+
+    Returns:
+        Logger instance
+    """
+    if name is None:
+        return logging.getLogger("shannon_insight")
+
+    # Ensure name starts with shannon_insight
+    if not name.startswith("shannon_insight"):
+        name = f"shannon_insight.{name}"
+
+    return logging.getLogger(name)

shannon_insight/math/__init__.py

@@ -0,0 +1,15 @@
+"""Mathematical utilities for codebase analysis."""
+
+from .entropy import Entropy
+from .graph import GraphMetrics
+from .statistics import Statistics
+from .robust import RobustStatistics
+from .fusion import SignalFusion
+
+__all__ = [
+    "Entropy",
+    "GraphMetrics",
+    "Statistics",
+    "SignalFusion",
+    "RobustStatistics",
+]

shannon_insight/math/entropy.py

@@ -0,0 +1,133 @@
+"""Information theory: Shannon entropy, KL divergence, joint entropy."""
+
+import math
+from typing import List, Mapping, Union
+
+
+class Entropy:
+    """Information entropy calculations."""
+
+    @staticmethod
+    def shannon(distribution: Mapping[str, Union[int, float]]) -> float:
+        """
+        Compute Shannon entropy H(X) = -Σ p(x) log₂ p(x).
+
+        Args:
+            distribution: Dictionary with event -> count mapping
+
+        Returns:
+            Entropy in bits
+        """
+        total = sum(distribution.values())
+        if total == 0:
+            return 0.0
+
+        entropy = 0.0
+        for count in distribution.values():
+            p = count / total
+            if p > 0:
+                entropy -= p * math.log2(p)
+
+        return entropy
+
+    @staticmethod
+    def normalized(distribution: Mapping[str, Union[int, float]]) -> float:
+        """
+        Normalize entropy by maximum possible entropy.
+
+        H_norm = H / log₂(N) where N is number of unique events
+
+        Returns:
+            Normalized entropy in [0, 1]
+        """
+        h = Entropy.shannon(distribution)
+        n = len(distribution)
+        if n <= 1:
+            return 0.0
+        max_h = math.log2(n)
+        return h / max_h if max_h > 0 else 0.0
+
+    @staticmethod
+    def kl_divergence(
+        p: Mapping[str, Union[int, float]], q: Mapping[str, Union[int, float]]
+    ) -> float:
+        """
+        Compute Kullback-Leibler divergence D_KL(P || Q).
+
+        D_KL(P || Q) = Σ P(x) log₂(P(x) / Q(x))
+
+        Args:
+            p: Observed distribution
+            q: Expected distribution
+
+        Returns:
+            KL divergence in bits (lower = more similar)
+        """
+        total_p = sum(p.values())
+        total_q = sum(q.values())
+
+        if total_p == 0 or total_q == 0:
+            return 0.0
+
+        kl_div = 0.0
+        for key, count_p in p.items():
+            prob_p = count_p / total_p
+            prob_q = q.get(key, 0) / total_q if key in q else 0
+
+            if prob_p > 0 and prob_q == 0:
+                # D_KL is undefined (infinite) when P(x)>0 but Q(x)=0
+                return float("inf")
+            if prob_p > 0 and prob_q > 0:
+                kl_div += prob_p * math.log2(prob_p / prob_q)
+
+        return kl_div
+
+    @staticmethod
+    def joint_entropy(
+        joint_distribution: Mapping[tuple, Union[int, float]]
+    ) -> float:
+        """
+        Compute joint entropy H(X, Y, ...) from a joint distribution.
+
+        H(X,Y) = -Σ_x Σ_y p(x,y) log₂ p(x,y)
+
+        The joint distribution must be keyed by tuples representing
+        joint outcomes, e.g. {("a", "b"): 5, ("a", "c"): 3, ...}.
+
+        Args:
+            joint_distribution: Dictionary mapping outcome tuples to counts
+
+        Returns:
+            Joint entropy in bits
+
+        Reference:
+            Cover & Thomas, *Elements of Information Theory*, 2nd ed.,
+            Chapter 2 (Theorem 2.6.6).
+        """
+        # Delegate to shannon() — the formula is identical, only the
+        # sample space changes from singleton events to joint events.
+        return Entropy.shannon(joint_distribution)
+
+    @staticmethod
+    def pooled_entropy(*distributions: Mapping[str, Union[int, float]]) -> float:
+        """
+        Compute entropy of the pooled (merged) sample from multiple distributions.
+
+        This is NOT the same as joint entropy. It merges all counts into a
+        single distribution and computes H of the mixture. Useful when you
+        want the entropy of the combined observation set.
+
+        H_pooled = H(merge(X₁, X₂, ...))
+
+        Args:
+            *distributions: Multiple count distributions to pool
+
+        Returns:
+            Entropy of the pooled distribution in bits
+        """
+        merged: dict = {}
+        for dist in distributions:
+            for key, count in dist.items():
+                merged[key] = merged.get(key, 0) + count
+
+        return Entropy.shannon(merged)

shannon_insight/math/fusion.py

@@ -0,0 +1,109 @@
+"""Evidence fusion: Bayesian combination, Dempster-Shafer theory."""
+
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+class SignalFusion:
+    """Evidence-theoretic signal fusion methods."""
+
+    @staticmethod
+    def bayesian_fusion(
+        priors: List[float], likelihoods: List[float]
+    ) -> Tuple[float, float]:
+        """
+        Bayesian evidence combination: P(H|E) = P(E|H) * P(H) / P(E).
+
+        Computes the posterior for each hypothesis, normalizes by total
+        evidence, and returns the maximum posterior along with an
+        entropy-based confidence measure.
+
+        Args:
+            priors: Prior probabilities for each hypothesis (should sum to 1)
+            likelihoods: Likelihoods P(E|H_i) for each hypothesis
+
+        Returns:
+            Tuple of (max_posterior, confidence)
+            confidence is 1 - normalized_entropy of the posterior distribution,
+            bounded in [0, 1].
+
+        Reference:
+            Bayes' theorem; Bishop, "Pattern Recognition and Machine Learning"
+            (2006), Chapter 1.2.
+        """
+        import math as _math
+
+        if len(priors) != len(likelihoods):
+            raise ValueError("priors and likelihoods must have the same length")
+
+        # Unnormalized posteriors: P(E|H_i) * P(H_i)
+        unnormalized = [p * l for p, l in zip(priors, likelihoods)]
+        evidence = sum(unnormalized)
+
+        if evidence <= 0:
+            n = len(priors)
+            return 1.0 / n if n > 0 else 0.0, 0.0
+
+        posteriors = [u / evidence for u in unnormalized]
+        max_posterior = max(posteriors)
+
+        # Confidence = 1 - normalized entropy of the posterior distribution.
+        # When all mass is on one hypothesis, entropy = 0 -> confidence = 1.
+        # When posteriors are uniform, entropy = log2(n) -> confidence = 0.
+        n = len(posteriors)
+        if n <= 1:
+            confidence = 1.0
+        else:
+            entropy = -sum(p * _math.log2(p) for p in posteriors if p > 0)
+            max_entropy = _math.log2(n)
+            confidence = 1.0 - (entropy / max_entropy) if max_entropy > 0 else 1.0
+
+        return float(max_posterior), float(confidence)
+
+    @staticmethod
+    def dempster_shafer_combination(
+        mass_functions: List[Dict[frozenset, float]]
+    ) -> Dict[frozenset, float]:
+        """
+        Combine evidence using Dempster-Shafer theory.
+
+        m(A) = Σ(B∩C=A) m1(B) * m2(C) / (1 - K)
+
+        Where K is conflict coefficient.
+
+        Keys must be frozensets representing hypothesis sets.
+
+        Args:
+            mass_functions: List of mass functions {frozenset(hypotheses): mass}
+
+        Returns:
+            Combined mass function
+        """
+        if not mass_functions:
+            return {}
+
+        combined = mass_functions[0].copy()
+
+        for i in range(1, len(mass_functions)):
+            m2 = mass_functions[i]
+            new_combined: Dict[frozenset, float] = {}
+            total_conflict = 0.0
+
+            for a, ma in combined.items():
+                for b, mb in m2.items():
+                    intersection = a & b  # proper set intersection
+                    if intersection:
+                        new_combined[intersection] = (
+                            new_combined.get(intersection, 0.0) + ma * mb
+                        )
+                    else:
+                        total_conflict += ma * mb
+
+            normalization = 1.0 - total_conflict
+            if normalization > 0:
+                new_combined = {k: v / normalization for k, v in new_combined.items()}
+
+            combined = new_combined
+
+        return combined