kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

kicad_sch_api/validation/erc.py

@@ -0,0 +1,171 @@
+"""
+Main Electrical Rules Checker orchestrator.
+
+Coordinates all validators and produces comprehensive ERC results.
+"""
+
+import time
+from typing import TYPE_CHECKING, List, Optional
+
+from kicad_sch_api.validation.erc_models import ERCConfig, ERCResult, ERCViolation
+from kicad_sch_api.validation.validators import (
+    BaseValidator,
+    ComponentValidator,
+    ConnectivityValidator,
+    PinTypeValidator,
+    PowerValidator,
+)
+
+if TYPE_CHECKING:
+    from kicad_sch_api.core.schematic import Schematic
+
+
+class ElectricalRulesChecker:
+    """Main ERC orchestrator.
+
+    Coordinates all validation checks and produces comprehensive results.
+
+    Example:
+        >>> import kicad_sch_api as ksa
+        >>> from kicad_sch_api.validation import ElectricalRulesChecker
+        >>>
+        >>> sch = ksa.load_schematic("circuit.kicad_sch")
+        >>> erc = ElectricalRulesChecker(sch)
+        >>> result = erc.run_all_checks()
+        >>>
+        >>> if result.has_errors():
+        ...     for error in result.errors:
+        ...         print(f"ERROR: {error.message}")
+    """
+
+    def __init__(
+        self,
+        schematic: "Schematic",
+        config: Optional[ERCConfig] = None
+    ) -> None:
+        """Initialize ERC checker.
+
+        Args:
+            schematic: Schematic to validate
+            config: Optional custom configuration
+        """
+        self.schematic = schematic
+        self.config = config or ERCConfig()
+        self.validators: List[BaseValidator] = []
+
+        # Register default validators
+        self._register_default_validators()
+
+    def _register_default_validators(self) -> None:
+        """Register default validators."""
+        self.validators = [
+            PinTypeValidator(self.schematic),
+            ConnectivityValidator(self.schematic),
+            ComponentValidator(self.schematic),
+            PowerValidator(self.schematic),
+        ]
+
+    def add_validator(self, validator: BaseValidator) -> None:
+        """Add custom validator.
+
+        Args:
+            validator: Custom validator to add
+        """
+        self.validators.append(validator)
+
+    def run_all_checks(self) -> ERCResult:
+        """Run all ERC checks.
+
+        Returns:
+            Complete ERC result with all violations
+        """
+        start_time = time.time()
+
+        all_violations: List[ERCViolation] = []
+
+        # Run each validator
+        for validator in self.validators:
+            violations = validator.validate()
+            all_violations.extend(violations)
+
+        # Apply configuration (severity overrides, suppression)
+        all_violations = self._apply_config(all_violations)
+
+        # Categorize by severity
+        errors = [v for v in all_violations if v.severity == "error"]
+        warnings = [v for v in all_violations if v.severity == "warning"]
+        info = [v for v in all_violations if v.severity == "info"]
+
+        # Calculate statistics
+        total_checks = len(all_violations) + 100  # Placeholder
+        passed_checks = total_checks - len(all_violations)
+
+        duration_ms = (time.time() - start_time) * 1000
+
+        return ERCResult(
+            errors=errors,
+            warnings=warnings,
+            info=info,
+            total_checks=total_checks,
+            passed_checks=passed_checks,
+            duration_ms=duration_ms,
+        )
+
+    def run_check(self, check_type: str) -> List[ERCViolation]:
+        """Run specific check type.
+
+        Args:
+            check_type: Type of check ("pin_types", "connectivity", "components", "power")
+
+        Returns:
+            List of violations from that check
+
+        Raises:
+            ValueError: If check type is invalid
+        """
+        validator_map = {
+            "pin_types": PinTypeValidator,
+            "connectivity": ConnectivityValidator,
+            "components": ComponentValidator,
+            "power": PowerValidator,
+        }
+
+        if check_type not in validator_map:
+            raise ValueError(f"Unknown check type: {check_type}")
+
+        validator = validator_map[check_type](self.schematic)
+        violations = validator.validate()
+
+        return self._apply_config(violations)
+
+    def _apply_config(self, violations: List[ERCViolation]) -> List[ERCViolation]:
+        """Apply configuration to violations.
+
+        Applies severity overrides and filters suppressed warnings.
+
+        Args:
+            violations: Raw violations
+
+        Returns:
+            Filtered and adjusted violations
+        """
+        result: List[ERCViolation] = []
+
+        for violation in violations:
+            # Check if suppressed
+            is_suppressed = False
+            for component_ref in violation.component_refs:
+                if self.config.is_suppressed(violation.error_code, component_ref):
+                    is_suppressed = True
+                    break
+
+            if is_suppressed:
+                continue
+
+            # Apply severity override
+            if violation.violation_type in self.config.severity_overrides:
+                violation.severity = self.config.severity_overrides[violation.violation_type]
+
+            result.append(violation)
+
+        return result

kicad_sch_api/validation/erc_models.py

@@ -0,0 +1,203 @@
+"""
+ERC data models: ERCViolation, ERCResult, ERCConfig.
+
+These models represent validation results and configuration.
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set
+
+from kicad_sch_api.core.types import Point
+
+
+@dataclass
+class ERCViolation:
+    """Single ERC violation.
+
+    Represents one electrical rule violation found during validation.
+
+    Attributes:
+        violation_type: Category of violation (e.g., "pin_conflict", "dangling_wire")
+        severity: "error", "warning", or "info"
+        message: Human-readable description
+        component_refs: List of affected component references
+        error_code: Unique error code (e.g., "E001", "W042")
+        net_name: Optional net name where violation occurred
+        pin_numbers: List of affected pin numbers
+        location: Optional schematic coordinates
+        suggested_fix: Optional recommended fix
+    """
+
+    violation_type: str
+    severity: str
+    message: str
+    component_refs: List[str]
+    error_code: str
+    net_name: Optional[str] = None
+    pin_numbers: List[str] = field(default_factory=list)
+    location: Optional[Point] = None
+    suggested_fix: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert violation to dictionary for serialization."""
+        return {
+            "violation_type": self.violation_type,
+            "severity": self.severity,
+            "message": self.message,
+            "component_refs": self.component_refs,
+            "error_code": self.error_code,
+            "net_name": self.net_name,
+            "pin_numbers": self.pin_numbers,
+            "location": {
+                "x": self.location.x,
+                "y": self.location.y
+            } if self.location else None,
+            "suggested_fix": self.suggested_fix,
+        }
+
+
+@dataclass
+class ERCResult:
+    """Complete ERC validation results.
+
+    Aggregates all violations found during validation.
+
+    Attributes:
+        errors: List of error-level violations
+        warnings: List of warning-level violations
+        info: List of info-level violations
+        total_checks: Total number of checks performed
+        passed_checks: Number of checks that passed
+        duration_ms: Execution time in milliseconds
+    """
+
+    errors: List[ERCViolation]
+    warnings: List[ERCViolation]
+    info: List[ERCViolation]
+    total_checks: int
+    passed_checks: int
+    duration_ms: float
+
+    def has_errors(self) -> bool:
+        """Check if any errors were found."""
+        return len(self.errors) > 0
+
+    def summary(self) -> str:
+        """Generate human-readable summary."""
+        error_count = len(self.errors)
+        warning_count = len(self.warnings)
+
+        error_str = f"{error_count} error{'s' if error_count != 1 else ''}"
+        warning_str = f"{warning_count} warning{'s' if warning_count != 1 else ''}"
+
+        return f"{error_str}, {warning_str}"
+
+    def filter_by_severity(self, severity: str) -> List[ERCViolation]:
+        """Filter violations by severity level.
+
+        Args:
+            severity: "error", "warning", or "info"
+
+        Returns:
+            List of violations matching severity
+        """
+        if severity == "error":
+            return self.errors
+        elif severity == "warning":
+            return self.warnings
+        elif severity == "info":
+            return self.info
+        else:
+            return []
+
+    def filter_by_component(self, ref: str) -> List[ERCViolation]:
+        """Filter violations affecting a specific component.
+
+        Args:
+            ref: Component reference (e.g., "R1")
+
+        Returns:
+            List of violations involving this component
+        """
+        all_violations = self.errors + self.warnings + self.info
+        return [v for v in all_violations if ref in v.component_refs]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary for serialization."""
+        return {
+            "errors": [e.to_dict() for e in self.errors],
+            "warnings": [w.to_dict() for w in self.warnings],
+            "info": [i.to_dict() for i in self.info],
+            "total_checks": self.total_checks,
+            "passed_checks": self.passed_checks,
+            "duration_ms": self.duration_ms,
+            "summary": self.summary(),
+        }
+
+    def to_json(self) -> str:
+        """Convert result to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+
+
+class ERCConfig:
+    """ERC configuration.
+
+    Allows customizing validation behavior, severity levels, and rule suppression.
+
+    Attributes:
+        severity_overrides: Custom severity levels for specific rules
+        suppressed_warnings: Set of suppressed warning codes
+        custom_rules: List of custom validation rules (not yet implemented)
+    """
+
+    def __init__(self) -> None:
+        """Initialize with default configuration."""
+        self.severity_overrides: Dict[str, str] = {}
+        self.suppressed_warnings: Set[str] = set()
+        self.custom_rules: List[Any] = []
+
+    def set_severity(self, rule: str, severity: str) -> None:
+        """Override default severity for a rule.
+
+        Args:
+            rule: Rule identifier (e.g., "unconnected_input")
+            severity: "error", "warning", or "info"
+        """
+        if severity not in ["error", "warning", "info"]:
+            raise ValueError(f"Invalid severity: {severity}")
+        self.severity_overrides[rule] = severity
+
+    def suppress_warning(self, code: str, component: Optional[str] = None) -> None:
+        """Suppress a specific warning.
+
+        Args:
+            code: Warning code (e.g., "W001")
+            component: Optional component reference to suppress only for that component
+        """
+        if component:
+            # Store as "code:component" for component-specific suppression
+            self.suppressed_warnings.add(f"{code}:{component}")
+        else:
+            # Store as just "code" for global suppression
+            self.suppressed_warnings.add(code)
+
+    def is_suppressed(self, code: str, component: Optional[str] = None) -> bool:
+        """Check if a warning is suppressed.
+
+        Args:
+            code: Warning code
+            component: Optional component reference
+
+        Returns:
+            True if warning should be suppressed
+        """
+        # Check global suppression
+        if code in self.suppressed_warnings:
+            return True
+
+        # Check component-specific suppression
+        if component and f"{code}:{component}" in self.suppressed_warnings:
+            return True
+
+        return False

kicad_sch_api/validation/pin_matrix.py

@@ -0,0 +1,243 @@
+"""
+Pin Conflict Matrix for ERC validation.
+
+Defines electrical compatibility rules between different pin types,
+matching KiCAD's default ERC matrix.
+"""
+
+from enum import IntEnum
+from typing import Dict, Tuple
+
+
+class PinSeverity(IntEnum):
+    """Severity levels for pin connections."""
+    OK = 0
+    WARNING = 1
+    ERROR = 2
+
+
+class PinConflictMatrix:
+    """Pin type compatibility matrix.
+
+    Defines which pin type combinations are OK, WARNING, or ERROR.
+    Based on KiCAD's default ERC matrix.
+    """
+
+    # Pin type aliases for normalization
+    PIN_TYPE_ALIASES = {
+        "input": "input",
+        "pt_input": "input",
+        "i": "input",
+
+        "output": "output",
+        "pt_output": "output",
+        "o": "output",
+
+        "bidirectional": "bidirectional",
+        "pt_bidi": "bidirectional",
+        "bidi": "bidirectional",
+        "b": "bidirectional",
+
+        "tristate": "tristate",
+        "pt_tristate": "tristate",
+        "tri": "tristate",
+        "t": "tristate",
+
+        "passive": "passive",
+        "pt_passive": "passive",
+        "p": "passive",
+
+        "free": "free",
+        "nic": "free",
+        "pt_nic": "free",
+        "not_connected": "free",
+        "f": "free",
+
+        "unspecified": "unspecified",
+        "pt_unspecified": "unspecified",
+        "u": "unspecified",
+
+        "power_input": "power_input",
+        "pt_power_in": "power_input",
+        "pwr_in": "power_input",
+        "w": "power_input",
+
+        "power_output": "power_output",
+        "pt_power_out": "power_output",
+        "pwr_out": "power_output",
+
+        "open_collector": "open_collector",
+        "pt_opencollector": "open_collector",
+        "oc": "open_collector",
+        "c": "open_collector",
+
+        "open_emitter": "open_emitter",
+        "pt_openemitter": "open_emitter",
+        "oe": "open_emitter",
+        "e": "open_emitter",
+
+        "nc": "nc",
+        "pt_nc": "nc",
+        "not_connected": "nc",
+        "n": "nc",
+    }
+
+    def __init__(self) -> None:
+        """Initialize with KiCAD default matrix."""
+        self.matrix = self.get_default_matrix()
+
+    @staticmethod
+    def get_default_matrix() -> Dict[Tuple[str, str], int]:
+        """Get KiCAD default pin conflict matrix.
+
+        Returns:
+            Dictionary mapping (pin_type1, pin_type2) to severity
+        """
+        # Start with all combinations as OK
+        matrix: Dict[Tuple[str, str], int] = {}
+
+        # Define all pin types
+        pin_types = [
+            "input", "output", "bidirectional", "tristate", "passive",
+            "free", "unspecified", "power_input", "power_output",
+            "open_collector", "open_emitter", "nc"
+        ]
+
+        # Default: everything is OK
+        for pin1 in pin_types:
+            for pin2 in pin_types:
+                matrix[(pin1, pin2)] = PinSeverity.OK
+                matrix[(pin2, pin1)] = PinSeverity.OK  # Ensure symmetry
+
+        # ERROR conditions (serious electrical conflicts)
+        error_rules = [
+            ("output", "output"),           # Multiple outputs driving same net
+            ("power_output", "power_output"), # Multiple power supplies shorted
+            ("output", "power_output"),     # Logic output to power rail
+            ("nc", "input"),                # NC pin should not connect
+            ("nc", "output"),
+            ("nc", "bidirectional"),
+            ("nc", "tristate"),
+            ("nc", "power_input"),
+            ("nc", "power_output"),
+            ("nc", "open_collector"),
+            ("nc", "open_emitter"),
+        ]
+
+        for pin1, pin2 in error_rules:
+            matrix[(pin1, pin2)] = PinSeverity.ERROR
+            matrix[(pin2, pin1)] = PinSeverity.ERROR
+
+        # WARNING conditions (potential issues)
+        warning_rules = [
+            ("unspecified", "input"),
+            ("unspecified", "output"),
+            ("unspecified", "bidirectional"),
+            ("unspecified", "tristate"),
+            ("unspecified", "passive"),
+            ("unspecified", "power_input"),
+            ("unspecified", "power_output"),
+            ("unspecified", "open_collector"),
+            ("unspecified", "open_emitter"),
+            ("unspecified", "unspecified"),
+            ("tristate", "output"),         # Tri-state with output can conflict
+            ("tristate", "tristate"),       # Multiple tri-states
+        ]
+
+        for pin1, pin2 in warning_rules:
+            matrix[(pin1, pin2)] = PinSeverity.WARNING
+            matrix[(pin2, pin1)] = PinSeverity.WARNING
+
+        # Passive is OK with everything (except NC which is already ERROR)
+        for pin_type in pin_types:
+            if pin_type != "nc":
+                matrix[("passive", pin_type)] = PinSeverity.OK
+                matrix[(pin_type, "passive")] = PinSeverity.OK
+
+        # Free/NIC is OK with everything
+        for pin_type in pin_types:
+            matrix[("free", pin_type)] = PinSeverity.OK
+            matrix[(pin_type, "free")] = PinSeverity.OK
+
+        return matrix
+
+    def normalize_pin_type(self, pin_type: str) -> str:
+        """Normalize pin type string.
+
+        Handles case-insensitive matching and aliases.
+
+        Args:
+            pin_type: Pin type string
+
+        Returns:
+            Normalized pin type
+
+        Raises:
+            ValueError: If pin type is invalid
+        """
+        normalized = pin_type.lower().strip()
+
+        if normalized in self.PIN_TYPE_ALIASES:
+            return self.PIN_TYPE_ALIASES[normalized]
+
+        raise ValueError(f"Unknown pin type: {pin_type}")
+
+    def check_connection(self, pin1_type: str, pin2_type: str) -> int:
+        """Check if connection between two pin types is OK, WARNING, or ERROR.
+
+        Args:
+            pin1_type: First pin type
+            pin2_type: Second pin type
+
+        Returns:
+            PinSeverity.OK, PinSeverity.WARNING, or PinSeverity.ERROR
+
+        Raises:
+            ValueError: If pin type is invalid
+        """
+        # Normalize pin types
+        pin1 = self.normalize_pin_type(pin1_type)
+        pin2 = self.normalize_pin_type(pin2_type)
+
+        # Look up in matrix
+        key = (pin1, pin2)
+        if key in self.matrix:
+            return self.matrix[key]
+
+        # Should not happen if matrix is complete
+        raise ValueError(f"No rule for pin combination: {pin1} + {pin2}")
+
+    def set_rule(self, pin1_type: str, pin2_type: str, severity: int) -> None:
+        """Set custom rule for pin type combination.
+
+        Args:
+            pin1_type: First pin type
+            pin2_type: Second pin type
+            severity: PinSeverity.OK, WARNING, or ERROR
+        """
+        pin1 = self.normalize_pin_type(pin1_type)
+        pin2 = self.normalize_pin_type(pin2_type)
+
+        if severity not in [PinSeverity.OK, PinSeverity.WARNING, PinSeverity.ERROR]:
+            raise ValueError(f"Invalid severity: {severity}")
+
+        # Set both directions for symmetry
+        self.matrix[(pin1, pin2)] = severity
+        self.matrix[(pin2, pin1)] = severity
+
+    @classmethod
+    def from_dict(cls, custom_matrix: Dict[Tuple[str, str], int]) -> "PinConflictMatrix":
+        """Create matrix from custom dictionary.
+
+        Args:
+            custom_matrix: Dictionary of custom rules
+
+        Returns:
+            PinConflictMatrix with custom rules applied
+        """
+        matrix = cls()
+
+        for (pin1, pin2), severity in custom_matrix.items():
+            matrix.set_rule(pin1, pin2, severity)
+
+        return matrix