enginehall 2.0.0__py3-none-any.whl

pcba/model/design.py

@@ -0,0 +1,232 @@
+"""The connectivity and board model a KiCad project is read into.
+
+`pinmap.py` holds what the STM32 cross-domain rules need: one MCU's pins. A KiCad project is
+read completely, because the KiCad rules judge every part and every net: rails, decoupling,
+pull-ups, fiducials, test points. These entities are what the KiCad reader
+(`pcba/parsers/kicad/`) produces and what `pcba/rules/kicad_*.py` consume; nothing else.
+
+Coordinates are millimetres in the file's own frame: schematic y down, board y down.
+Paths are absolute; rules turn them into project-relative locations.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SchPin:
+    """One electrical pin of a placed symbol, after rotation and mirroring."""
+
+    ref: str               # reference of the symbol instance ("R1", "#PWR03")
+    number: str            # pin number ("1", "A3")
+    name: str              # pin name ("VDD", "~" when unnamed)
+    type: str              # KiCad electrical type: input, output, bidirectional, power_in, ...
+    sheet_file: str        # absolute path of the .kicad_sch it is drawn on
+    sheet_path: str        # hierarchical sheet path, "/" for the root, "/Power/" below it
+    x: float
+    y: float
+    line: int = 0          # line of the placed symbol in sheet_file
+    hidden: bool = False
+    no_connect: bool = False  # a no-connect flag sits on its end
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SchLabel:
+    """A net label, global label, hierarchical label, sheet pin or power symbol."""
+
+    kind: str              # local | global | hierarchical | sheet_pin | power | local_power
+    text: str
+    sheet_file: str
+    sheet_path: str
+    x: float
+    y: float
+    line: int = 0
+    connections: int = 0   # pins on the cluster it is drawn on (filled by the reader)
+
+
+@dataclasses.dataclass(slots=True)
+class Component:
+    """One placed symbol (all its units merged under one reference)."""
+
+    ref: str
+    value: str
+    lib_id: str
+    footprint: str
+    sheet_file: str
+    sheet_path: str
+    line: int
+    properties: dict[str, str] = dataclasses.field(default_factory=dict)
+    pins: list[SchPin] = dataclasses.field(default_factory=list)
+    power: bool = False    # a power symbol (#PWR, PWR_FLAG): names a net, is not a part
+    dnp: bool = False
+    in_bom: bool = True
+    on_board: bool = True
+
+    def pin(self, number: str) -> SchPin | None:
+        return next((p for p in self.pins if p.number == number), None)
+
+
+@dataclasses.dataclass(slots=True)
+class Net:
+    """One electrical net of the whole hierarchy."""
+
+    name: str              # KiCad-style name: "GND", "/SDA", "/Power/VIN", "Net-(R1-Pad2)"
+    label: str | None      # the name a designer gave it, without sheet path; None if unnamed
+    pins: list[SchPin] = dataclasses.field(default_factory=list)
+    labels: list[SchLabel] = dataclasses.field(default_factory=list)
+    power: bool = False    # named by a power symbol or a hidden power-input pin
+    no_connect: bool = False
+
+    @property
+    def parts(self) -> list[SchPin]:
+        """The pins of real parts (power symbols excluded)."""
+        return [p for p in self.pins if not p.ref.startswith("#")]
+
+
+@dataclasses.dataclass(slots=True)
+class Schematic:
+    """A KiCad schematic hierarchy, flattened into components and nets."""
+
+    project_file: str | None
+    root_file: str
+    sheet_files: list[str] = dataclasses.field(default_factory=list)
+    sheet_paths: dict[str, str] = dataclasses.field(default_factory=dict)  # sheet path -> file
+    components: dict[str, Component] = dataclasses.field(default_factory=dict)
+    nets: list[Net] = dataclasses.field(default_factory=list)
+    labels: list[SchLabel] = dataclasses.field(default_factory=list)
+    notes: list[str] = dataclasses.field(default_factory=list)
+    _by_pin: dict[tuple[str, str], Net] = dataclasses.field(default_factory=dict, repr=False)
+
+    def index(self) -> None:
+        self._by_pin = {(p.ref, p.number): net for net in self.nets for p in net.pins}
+
+    def net_of(self, ref: str, number: str) -> Net | None:
+        if not self._by_pin:
+            self.index()
+        return self._by_pin.get((ref, number))
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Pad:
+    ref: str
+    number: str
+    kind: str              # smd | thru_hole | np_thru_hole | connect
+    shape: str             # circle | rect | roundrect | oval | trapezoid | custom
+    x: float               # absolute board coordinates
+    y: float
+    w: float
+    h: float
+    rotation: float
+    layers: tuple[str, ...]
+    net: str | None
+    drill: float = 0.0
+    mask_margin: float | None = None   # pad, footprint or board solder-mask expansion (mm)
+    line: int = 0
+
+    @property
+    def copper_layers(self) -> tuple[str, ...]:
+        return tuple(layer for layer in self.layers if layer.endswith(".Cu"))
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Graphic:
+    """A drawn primitive on a non-copper layer (outline, silkscreen, courtyard)."""
+
+    layer: str
+    kind: str              # line | arc | circle | rect | poly | text
+    points: tuple[tuple[float, float], ...]  # absolute; arcs and circles as polylines
+    text: str = ""
+    size: float = 0.0      # text height (mm)
+    hidden: bool = False
+    ref: str | None = None  # owning footprint, None for board graphics
+    line: int = 0
+
+
+@dataclasses.dataclass(slots=True)
+class Footprint:
+    ref: str
+    value: str
+    lib: str
+    layer: str             # F.Cu or B.Cu
+    x: float
+    y: float
+    rotation: float
+    attributes: tuple[str, ...] = ()
+    pads: list[Pad] = dataclasses.field(default_factory=list)
+    models: list[str] = dataclasses.field(default_factory=list)  # model paths as written
+    graphics: list[Graphic] = dataclasses.field(default_factory=list)
+    properties: dict[str, str] = dataclasses.field(default_factory=dict)
+    line: int = 0
+
+    @property
+    def side(self) -> str:
+        return "bottom" if self.layer.startswith("B.") else "top"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Track:
+    start: tuple[float, float]
+    end: tuple[float, float]
+    width: float
+    layer: str
+    net: str | None
+    arc: bool = False
+    line: int = 0
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Via:
+    x: float
+    y: float
+    size: float
+    drill: float
+    layers: tuple[str, ...]
+    net: str | None
+    line: int = 0
+
+
+@dataclasses.dataclass(slots=True)
+class Board:
+    path: str
+    version: int
+    footprints: list[Footprint] = dataclasses.field(default_factory=list)
+    tracks: list[Track] = dataclasses.field(default_factory=list)
+    vias: list[Via] = dataclasses.field(default_factory=list)
+    zones: list[dict[str, Any]] = dataclasses.field(default_factory=list)
+    graphics: list[Graphic] = dataclasses.field(default_factory=list)
+    nets: set[str] = dataclasses.field(default_factory=set)
+    notes: list[str] = dataclasses.field(default_factory=list)
+
+    @property
+    def outline(self) -> list[tuple[tuple[float, float], tuple[float, float]]]:
+        """Every Edge.Cuts edge as a segment (arcs and circles already as polylines)."""
+        segments = []
+        for g in self.graphics:
+            if g.layer != "Edge.Cuts" or g.kind == "text":
+                continue
+            points = list(g.points)
+            closed = g.kind in ("rect", "poly", "circle")
+            pairs = zip(points, points[1:] + points[:1]) if closed else zip(points, points[1:])
+            segments.extend((a, b) for a, b in pairs if a != b)
+        return segments
+
+
+@dataclasses.dataclass(slots=True)
+class Design:
+    """Everything read from one KiCad project, plus what external tools reported about it.
+
+    `external` holds kicad-cli and ngspice results keyed by run name ("erc", "drc", "netlist",
+    "spice"); each value says whether the tool ran and what it returned, so a rule can tell
+    "the tool found nothing" from "the tool did not run".
+    """
+
+    root: str                          # directory of the KiCad project
+    project_file: str | None = None
+    schematic: Schematic | None = None
+    board: Board | None = None
+    requirements: Any = None           # pcba.requirements.Requirements
+    components: Any = None             # pcba.components.Library
+    external: dict[str, dict[str, Any]] = dataclasses.field(default_factory=dict)
+    notes: list[str] = dataclasses.field(default_factory=list)

pcba/model/finding.py

@@ -0,0 +1,148 @@
+"""The finding schema — one format for every rule in every domain.
+
+A finding is a claim about the design. Engineers only trust claims they can check, so the
+schema forces every field needed to check one: what artifact, where exactly in it, what
+evidence, which rule, and — critically — *how* it was detected.
+
+`detector` is the field that keeps this product honest. A deterministic parser result and a
+language model's hunch are both "findings", and presenting them identically is how a review
+tool loses an engineer's trust permanently. Shipped rules are deterministic except for the
+explicitly `HEURISTIC` open-circuit detector; no rule emits `AI_INFERRED` findings.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import Any
+
+
+class Severity(enum.StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class Detector(enum.StrEnum):
+    """How a finding was produced. Never blur these together in output."""
+
+    DETERMINISTIC = "deterministic"  # a parser or rule proved it from the files
+    HEURISTIC = "heuristic"          # a tuned threshold decided it; may cry wolf
+    AI_INFERRED = "ai_inferred"      # a language model suggested it; unverified
+    EXTERNAL = "external"            # came from an external service (e.g. parts data)
+    MANUAL = "manual"                # a human wrote it
+
+
+class Domain(enum.StrEnum):
+    SCHEMATIC = "schematic"
+    IOC = "ioc"
+    FIRMWARE = "firmware"
+    CROSS_DOMAIN = "cross_domain"
+    BOARD = "board"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Location:
+    """Where in the artifact. At least one field beyond `artifact` must be set.
+
+    A finding an engineer cannot navigate to is a finding they will not act on.
+
+    `artifact` is always a project-relative POSIX path (see `Project.relative`). SARIF
+    consumers resolve it against the project root, and the finding id is built from it.
+    """
+
+    artifact: str
+    sheet: str | None = None
+    component: str | None = None
+    pin: str | None = None
+    line: int | None = None
+    key: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in dataclasses.asdict(self).items() if v is not None}
+
+    def describe(self) -> str:
+        bits = [self.artifact]
+        if self.sheet and not self.artifact.endswith(self.sheet):
+            bits.append(f"sheet {self.sheet}")
+        if self.component:
+            bits.append(self.component + (f".{self.pin}" if self.pin else ""))
+        elif self.pin:
+            bits.append(self.pin)
+        if self.key:
+            bits.append(self.key)
+        if self.line:
+            bits.append(f":{self.line}")
+        return "  ".join(bits)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Evidence:
+    """A single verifiable fact the finding rests on.
+
+    `value` is what we actually read out of the file — quoted, not paraphrased, so the
+    engineer can grep for it.
+    """
+
+    kind: str
+    value: str
+    source: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in dataclasses.asdict(self).items() if v is not None}
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Finding:
+    rule_id: str
+    title: str
+    severity: Severity
+    domain: Domain
+    location: Location
+    explanation: str
+    consequence: str
+    recommendation: str
+    evidence: tuple[Evidence, ...] = ()
+    detector: Detector = Detector.DETERMINISTIC
+    confidence: float = 1.0
+    rule_version: str = "1.0.0"
+    # What the id is derived from when that is not `location`. Only the firmware drift
+    # finding sets it: its location is the first firmware reference, which moves when a file
+    # that sorts earlier names the same pin, so its id comes from the `.ioc`, the pin and the
+    # pin's `.ioc` key instead. Not part of the report; `location` stays the navigable place.
+    identity: Location | None = None
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError(f"confidence must be in [0,1], got {self.confidence}")
+        if not self.rule_id:
+            raise ValueError("rule_id is required")
+
+    @property
+    def id(self) -> str:
+        """Stable across runs, so a baseline can suppress this exact finding.
+
+        Deliberately derived from rule + location (or `identity`, where a rule sets one) and
+        *not* from the explanation text: rewording a message must not resurrect a finding
+        somebody already waived.
+        """
+        loc = self.identity or self.location
+        parts = [self.rule_id, loc.artifact, loc.sheet, loc.component, loc.pin, loc.key]
+        return "PCBA-" + "-".join(p for p in parts if p).replace(" ", "_")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "rule_id": self.rule_id,
+            "title": self.title,
+            "severity": str(self.severity),
+            "domain": str(self.domain),
+            "location": self.location.to_dict(),
+            "evidence": [e.to_dict() for e in self.evidence],
+            "explanation": self.explanation,
+            "consequence": self.consequence,
+            "recommendation": self.recommendation,
+            "detector": str(self.detector),
+            "confidence": self.confidence,
+            "rule_version": self.rule_version,
+        }

pcba/model/pinmap.py

@@ -0,0 +1,200 @@
+"""The normalized model — six entities and the Project that holds them, derived from what the
+parsers actually produce. A KiCad project's full netlist and board live beside it in
+`pcba/model/design.py`, which only the KiCad reader fills and only the KiCad rules read.
+
+This is deliberately small. The temptation is to design a grand ontology of the whole
+embedded product (Product, Revision, Board, Net, Interface, PowerRail, Clock, Connector,
+TestPoint, MemoryRegion, ...) before any parser can populate it. That gets the abstraction
+wrong, because the shape of engineering data is not knowable in advance — it is discovered
+by parsing real files and finding out what they actually contain.
+
+So: an entity earns its place here when a working parser emits it AND a rule consumes it.
+Nothing here is speculative. Grow it when a third parser demands it, not before.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pcba.model.design import Design
+
+
+class Resolution(enum.StrEnum):
+    """How confidently a schematic pin was traced to a net.
+
+    Distinguishing these matters: `DIRECT` is a fact, `SERIES_R` is an inference through a
+    two-pin part, `AMBIGUOUS` reached several named nets, and `NONE` reached none. A rule
+    that treats all four alike produces confident nonsense.
+    """
+
+    DIRECT = "direct"
+    SERIES_R = "series R"
+    AMBIGUOUS = "ambig"
+    NONE = "none"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Pin:
+    """A physical pin of a part, as drawn on a schematic sheet."""
+
+    name: str              # the MCU's name for it, e.g. "PD8" or "VDD3"
+    package_pin: str       # the pad designator: "12" on a QFP, "A1" on a BGA
+    net: str | None        # the net it resolves to, if any
+    resolution: Resolution
+    sheet: str             # path of the .SchDoc the pin is drawn on
+    component: str | None = None   # designator, e.g. "U1"
+    connected: bool = False  # wire, direct pin contact, or a named anchor at the hot end
+
+    @property
+    def port_pin(self) -> str:
+        """Return the primary GPIO name before Altium's alternate-name suffixes."""
+        primary = re.match(r"^P[A-KN-Q]\d{1,2}(?:_C)?(?=$|[\s/\-\[(])", self.name)
+        return primary.group() if primary else re.split(r"[-/(]", self.name)[0]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PinAssignment:
+    """What an MCU configuration tool says a pin does."""
+
+    pin: str               # "PD8"
+    signal: str | None     # "USART3_TX"
+    label: str | None      # user label
+    mode: str | None = None
+    signal_key: str | None = None  # original CubeMX key, including escaped alternate names
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class FirmwareReference:
+    """A place in firmware source that names a pin or a peripheral."""
+
+    symbol: str            # "PD8" or "USART3"
+    kind: str              # "pin" | "peripheral"
+    path: str              # absolute path of the source file
+    line: int
+    text: str
+    operation: str = "unknown"  # read | write | configure | unknown
+
+
+@dataclasses.dataclass(slots=True)
+class SchematicPinMap:
+    """What the schematic says. The board gets built from this, so it wins ties."""
+
+    part: str
+    source: str
+    pins: dict[str, Pin] = dataclasses.field(default_factory=dict)
+    near_misses: list[dict[str, Any]] = dataclasses.field(default_factory=list)
+    exact_landings: int = 0
+
+    def by_pin_name(self) -> dict[str, Pin]:
+        """Indexed by port pin, e.g. {'PD8': Pin(...)}. Power pins are excluded.
+
+        Two schematic pins claiming the same port name would be a defect in its own right;
+        first-wins here, and the mislabel rule reports the conflict separately.
+        """
+        out: dict[str, Pin] = {}
+        for pin in self.pins.values():
+            if is_power_pin(pin.name):
+                continue
+            out.setdefault(pin.port_pin, pin)
+        return out
+
+
+@dataclasses.dataclass(slots=True)
+class McuConfig:
+    """What the MCU configuration tool says."""
+
+    part: str | None      # None when the .ioc names no part
+    source: str
+    assignments: dict[str, PinAssignment] = dataclasses.field(default_factory=dict)
+    peripherals: tuple[str, ...] = ()
+    raw: dict[str, str] = dataclasses.field(default_factory=dict)
+
+
+@dataclasses.dataclass(slots=True)
+class FirmwareIndex:
+    """What the firmware source references."""
+
+    root: str
+    references: list[FirmwareReference] = dataclasses.field(default_factory=list)
+
+    def pins(self) -> dict[str, list[FirmwareReference]]:
+        out: dict[str, list[FirmwareReference]] = {}
+        for ref in self.references:
+            if ref.kind == "pin":
+                out.setdefault(ref.symbol, []).append(ref)
+        return out
+
+
+@dataclasses.dataclass(slots=True)
+class Project:
+    """Everything we managed to read. Any part may be absent.
+
+    Rules must degrade honestly: with no .ioc there is no schematic-vs-.ioc finding, and
+    saying nothing is correct. Silently passing a check that never ran is the failure mode
+    this model exists to prevent.
+    """
+
+    root: str
+    schematic: SchematicPinMap | None = None
+    mcu: McuConfig | None = None
+    firmware: FirmwareIndex | None = None
+    # Populated only when one schematic MCU part can be identified and it conflicts
+    # with the CubeMX part. The source is a sheet, so the rule can cite both files.
+    part_conflict: tuple[str, str] | None = None
+    # A KiCad project read completely (nets, board, requirements, kicad-cli and ngspice
+    # results) for the KiCad rules; None for an Altium-only project.
+    design: Design | None = None
+    # The schematic format discovery found: "altium", "kicad" or None. Rules written for one
+    # format are "not applicable" on the other, rather than "not checked".
+    formats: tuple[str, ...] = ()
+
+    def relative(self, path: str | Path) -> str:
+        """A project-relative POSIX path, for finding locations and evidence.
+
+        Parsers record files wherever they found them. A finding, though, has to name its
+        artifact the same way on every machine — its id is derived from that name, and a
+        baseline built on one engineer's absolute paths would silently reopen on the next
+        engineer's checkout. Anything outside the project keeps its own path.
+        """
+        candidate = Path(path)
+        try:
+            return candidate.resolve().relative_to(Path(self.root).resolve()).as_posix()
+        except ValueError:
+            return candidate.as_posix()
+
+
+# ST names every port pin P<letter><number>. Ports run A..K on most families (LQFP-176
+# exposes PJ/PK); the STM32N6 skips L and M and continues with PN..PQ.
+_PORT_PIN = re.compile(r"^P([A-KN-Q])(\d{1,2})(_C)?$")
+
+# Supply and reference pins carry no signal net, so cross-domain pin rules must skip them.
+# Kept vendor-neutral-ish but STM32-shaped; a second vendor will want its own table rather
+# than an extension of this regex.
+_POWER_PIN = re.compile(r"^(VSS|VDD|VBAT|VCAP|VREF|NC|VLX|VFB|BOOT|NRST|PDR)")
+
+
+def is_port_pin(name: str) -> bool:
+    return bool(_PORT_PIN.match(name or ""))
+
+
+def is_power_pin(name: str) -> bool:
+    return bool(_POWER_PIN.match(name or ""))
+
+
+def port_sort_key(name: str) -> tuple[str, int]:
+    """Sort PA0..PA15, PB0.. rather than lexically (which puts PA10 before PA2)."""
+    m = _PORT_PIN.match(name or "")
+    return (m.group(1), int(m.group(2))) if m else ("Z", 0)
+
+
+def natural_key(text: str) -> tuple:
+    """Sort pad designators the way a human reads them: 2 before 10, A2 before A10, A before B.
+
+    `int` alone was the previous key, which raised on the first BGA part it met.
+    """
+    return tuple(int(t) if t.isdigit() else t for t in re.split(r"(\d+)", text or ""))

pcba/parsers/altium/__init__.py

@@ -0,0 +1,37 @@
+"""Binary Altium schematic reading.
+
+Read-only. Nothing here writes a `.SchDoc`; a write path would go through an Altium adapter
+and the change-plan workflow.
+
+Note for anyone tempted to consolidate: the VS Code extension (`extension/src/schdoc/`)
+also parses this format, in TypeScript, for viewing and a heuristic netlist. This module is
+the review engine's extractor: it resolves MCU pins only, from geometry, and is what the
+rules are tested against. Two parsers, two jobs; keep the format notes in `records.py` in
+sync with the extension's parser when either learns something new.
+"""
+
+from pcba.parsers.altium.pinmap import (
+    claimed_pin,
+    detect_part,
+    detect_parts,
+    extract,
+    mislabelled,
+    suspected_opens,
+    to_dict,
+    uses_pin_prefix_convention,
+)
+from pcba.parsers.altium.records import SchDocError, contains_part, load_records
+
+__all__ = [
+    "SchDocError",
+    "claimed_pin",
+    "contains_part",
+    "detect_part",
+    "detect_parts",
+    "extract",
+    "load_records",
+    "mislabelled",
+    "suspected_opens",
+    "to_dict",
+    "uses_pin_prefix_convention",
+]