enginehall 2.0.0__py3-none-any.whl

pcba/review.py

@@ -0,0 +1,177 @@
+"""Review orchestration shared by the CLI and MCP server.
+
+Discovery locates inputs, parsers build the normalized project, and rules evaluate it. Keeping
+that sequence here prevents each interface from quietly assembling a different review.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+
+from pcba import baseline as baseline_file
+from pcba import changes as change_set
+from pcba import config, discover, report, rules
+from pcba.model.finding import Finding
+from pcba.model.pinmap import Project
+
+
+@dataclasses.dataclass(slots=True)
+class ReviewResult:
+    discovery: discover.Discovery
+    project: Project
+    findings: list[Finding]
+    coverage: dict
+    baseline: baseline_file.AppliedBaseline | None = None
+    changes: change_set.AppliedChangeFilter | None = None
+
+    def render(self, fmt: str, *, findings: list[Finding] | None = None, sarif_root: bool = True) -> str:
+        """The report as `json`, `sarif`, `markdown` or `text`. The CLI, the review MCP server and
+        the browser worker all render here, so a new report field reaches every interface.
+
+        `findings` replaces the full list (the MCP server caps it). `sarif_root` declares the
+        project folder as `%SRCROOT%`; the browser has no folder worth naming."""
+        shown = self.findings if findings is None else findings
+        baseline_info = self.baseline.to_dict() if self.baseline else None
+        changes_info = self.changes.to_dict() if self.changes else None
+        if fmt == "json":
+            return report.to_json(shown, self.coverage, self.discovery.to_dict(),
+                                  baseline=baseline_info, changes=changes_info)
+        if fmt == "sarif":
+            return report.to_sarif(shown, root=self.discovery.root if sarif_root else None,
+                                   coverage=self.coverage, discovery=self.discovery.to_dict(),
+                                   baseline=baseline_info, changes=changes_info)
+        if fmt == "markdown":
+            return report.to_markdown(shown, self.coverage, baseline_info, changes_info)
+        if fmt == "text":
+            return report.to_text(shown, self.coverage, baseline_info, changes_info)
+        raise ValueError(f"unknown report format: {fmt}")
+
+
+def explicit_path(root: Path, value: Path | str, label: str, *, directory: bool) -> Path:
+    """Resolve an input path the caller named, the same way for the CLI, MCP and the action.
+
+    A relative path is taken from the project root first, as `pcba-studio.toml` paths are;
+    the working directory is the fallback, so `enginehall review proj --ioc proj/board.ioc` keeps
+    working. A path the caller named explicitly and that does not exist is an error: a note
+    would let the review pass without the rules that input was given for.
+    """
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        in_project = root / path
+        if in_project.exists() or not path.exists():
+            path = in_project
+    path = path.resolve()
+    if not (path.is_dir() if directory else path.is_file()):
+        kind = "directory" if directory else "file"
+        raise config.ProjectConfigError(
+            f"{label} is not an existing {kind}: {value} (looked in {root} and the working "
+            "directory)"
+        )
+    return path
+
+
+def load_project(
+    root: Path | str,
+    *,
+    part: str | None = None,
+    schematic_component: str | None = None,
+    ioc: Path | str | None = None,
+    schematic_dir: Path | str | None = None,
+    target: str | None = None,
+    kicad_project: Path | str | None = None,
+    tools: bool = True,
+) -> tuple[discover.Discovery, Project]:
+    """Discover and parse a project without evaluating rules.
+
+    `tools=False` skips kicad-cli and ngspice, which only the review needs."""
+    selection = config.select(root, target)
+    project_root = Path(root).resolve()
+    if ioc:
+        ioc = explicit_path(project_root, ioc, "explicit .ioc", directory=False)
+    if schematic_dir:
+        schematic_dir = explicit_path(
+            project_root, schematic_dir, "explicit schematic directory", directory=True
+        )
+    if kicad_project:
+        named = Path(kicad_project)
+        kicad_project = explicit_path(
+            project_root, kicad_project, "explicit KiCad project",
+            directory=not named.suffix or (project_root / named).is_dir() or named.is_dir(),
+        )
+    selected_part = part or (selection.part if selection else None)
+    selected_ioc = ioc or (selection.ioc if selection else None)
+    selected_schematic = schematic_dir or (selection.schematic_dir if selection else None)
+    selected_firmware = selection.firmware_roots if selection else None
+    selected_kicad = kicad_project or (selection.kicad_project if selection else None)
+    found = discover.discover(
+        Path(root),
+        ioc=Path(selected_ioc) if selected_ioc else None,
+        schematic_dir=Path(selected_schematic) if selected_schematic else None,
+        firmware_roots=selected_firmware,
+        kicad_project=Path(selected_kicad) if selected_kicad else None,
+    )
+    found.target = selection.name if selection else None
+    if selected_part:
+        found.part = selected_part
+    component = schematic_component or (selection.schematic_component if selection else None)
+    return found, discover.build_project(found, part=selected_part, component=component, tools=tools)
+
+
+def run(
+    root: Path | str,
+    *,
+    part: str | None = None,
+    schematic_component: str | None = None,
+    ioc: Path | str | None = None,
+    schematic_dir: Path | str | None = None,
+    baseline: Path | str | None = None,
+    changed_only: str | None = None,
+    target: str | None = None,
+    required_rules: tuple[str, ...] = (),
+    kicad_project: Path | str | None = None,
+) -> ReviewResult:
+    """Run the complete deterministic review pipeline."""
+    found, project = load_project(
+        root, part=part, schematic_component=schematic_component, ioc=ioc,
+        schematic_dir=schematic_dir, target=target, kicad_project=kicad_project,
+    )
+    unknown = set(required_rules) - set(rules.REQUIREMENTS)
+    if unknown:
+        raise config.ProjectConfigError("unknown required rules: " + ", ".join(sorted(unknown)))
+    coverage = rules.coverage(project)
+    if required_rules:
+        unmet = set(required_rules) - set(coverage["ran"])
+        if "cross_domain.pin.mismatch" in required_rules and not coverage["statistics"]["compared_signals"]:
+            unmet.add("cross_domain.pin.mismatch")
+        coverage.update(required=sorted(set(required_rules)), unmet=sorted(unmet))
+    findings = rules.run(project)
+    coverage["rules"] = rules.rule_status(project, coverage, findings)
+    applied = None
+    if baseline:
+        findings, applied = baseline_file.apply(
+            findings, baseline_file.load(baseline), root=found.root
+        )
+    applied_changes = None
+    if changed_only:
+        findings, applied_changes = change_set.apply(findings, found.root, changed_only)
+    return ReviewResult(
+        discovery=found,
+        project=project,
+        findings=findings,
+        coverage=coverage,
+        baseline=applied,
+        changes=applied_changes,
+    )
+
+
+def summary(found: discover.Discovery, project: Project) -> dict:
+    """Payload shared by `enginehall inspect --format json` and the MCP inspect tool."""
+    return {
+        **found.to_dict(),
+        "schematic_pins": len(project.schematic.pins) if project.schematic else 0,
+        "ioc_pins": len(project.mcu.assignments) if project.mcu else 0,
+        "ioc_peripherals": list(project.mcu.peripherals) if project.mcu else [],
+        "firmware_references": len(project.firmware.references) if project.firmware else 0,
+        "coverage": rules.coverage(project),
+    }

pcba/rules/__init__.py

@@ -0,0 +1,312 @@
+"""The rule registry.
+
+A rule is a plain function `(Project) -> Iterator[Finding]`. No base class, no plugin
+manifest, no declarative DSL — those are worth adding once the model has stopped moving, and
+it has not.
+
+Rules must degrade honestly. A rule whose inputs are missing yields nothing; it never
+guesses, and it never reports a pass it did not earn. `coverage()` exists so the CLI can
+tell the user which checks did not run, because a green result from a check that never
+executed is the worst output this tool could produce.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import replace
+
+from pcba.model.finding import Detector, Finding
+from pcba.model.pinmap import Project, Resolution
+from pcba.rules import cross_domain, kicad_board, kicad_components, kicad_schematic, schematic, spice, stm32
+
+Rule = Callable[[Project], Iterator[Finding]]
+
+ALL_RULES: tuple[Rule, ...] = (schematic.RULES + stm32.RULES + cross_domain.RULES + kicad_schematic.RULES
+                               + kicad_components.RULES + kicad_board.RULES + spice.RULES)
+
+# What each rule family needs in order to say anything at all.
+REQUIREMENTS: dict[str, tuple[str, ...]] = {
+    "cross_domain.mcu.part_mismatch": ("mcu", "schematic_identity"),
+    "schematic.net.mislabelled": ("schematic",),
+    "schematic.net.open_circuit": ("schematic",),
+    "stm32.pin.alternate_function_impossible": ("schematic", "mcu_database", "matching_part"),
+    "cross_domain.pin.mismatch": ("schematic", "mcu", "matching_part"),
+    "cross_domain.pin.signal_conflict": ("schematic", "mcu", "matching_part"),
+    "cross_domain.pin.unconfigured": ("schematic", "mcu", "matching_part"),
+    "cross_domain.mcu_config.incomplete": ("schematic", "mcu", "matching_part"),
+    "cross_domain.peripheral.unconnected": ("schematic", "mcu", "matching_part"),
+    "cross_domain.firmware.hardcoded_pin_drift": ("firmware", "mcu"),
+    # KiCad schematic
+    "kicad.erc.violation": ("kicad_schematic", "kicad_cli_erc"),
+    "kicad.netlist.parity": ("kicad_schematic", "kicad_cli_netlist"),
+    "kicad.power.rail_without_source": ("kicad_schematic",),
+    "kicad.power.pin_without_dc_path": ("kicad_schematic",),
+    "kicad.power.decoupling_missing": ("kicad_schematic",),
+    "kicad.part.shorted": ("kicad_schematic",),
+    "kicad.pin.input_floating": ("kicad_schematic",),
+    "kicad.net.pull_up_missing": ("kicad_schematic",),
+    "kicad.label.global_single_sheet": ("kicad_schematic",),
+    "kicad.label.single_connection": ("kicad_schematic",),
+    "kicad.net.name_hygiene": ("kicad_schematic",),
+    # KiCad parts against component data and the requirements file
+    "kicad.component.supply_range": ("kicad_schematic",),
+    "kicad.component.capacitor_derating": ("kicad_schematic",),
+    "kicad.component.resistor_power": ("kicad_schematic",),
+    "kicad.component.logic_level": ("kicad_schematic",),
+    "kicad.component.required_connection": ("kicad_schematic",),
+    "kicad.connector.pin_assignment": ("kicad_schematic", "connector_specs"),
+    # KiCad board
+    "kicad.drc.violation": ("kicad_board", "kicad_cli_drc"),
+    "kicad.drc.schematic_parity": ("kicad_board", "kicad_schematic", "kicad_cli_drc"),
+    "kicad.dfm.fiducials": ("kicad_board",),
+    "kicad.dfm.track_angle": ("kicad_board",),
+    "kicad.dfm.via_in_pad": ("kicad_board",),
+    "kicad.dfm.via_spacing": ("kicad_board",),
+    "kicad.dfm.model_missing": ("kicad_board",),
+    "kicad.dfm.silkscreen_outside": ("kicad_board", "board_outline"),
+    "kicad.dfm.barcode_field": ("kicad_board",),
+    "kicad.dfm.bottom_side_smd": ("kicad_board", "single_sided_assembly"),
+    "kicad.dfm.smd_edge_clearance": ("kicad_board", "board_outline", "smd_edge_requirement"),
+    "kicad.dfm.test_point_coverage": ("kicad_board", "test_points_enabled"),
+    "kicad.dfm.courtyard_overlap": ("kicad_board",),
+    # Simulation
+    "simulation.spice.testbench": ("kicad_project", "simulations", "ngspice"),
+}
+
+# Rules written for one schematic format. On a project of the other format they are "not
+# applicable" (a different statement from "not checked"): KiCad rules need a KiCad project, and
+# the Altium open-circuit heuristic needs Altium sheets.
+FORMATS: dict[str, str] = {rule_id: "kicad" for rule_id in REQUIREMENTS
+                           if rule_id.startswith(("kicad.", "simulation."))}
+FORMATS["schematic.net.open_circuit"] = "altium"
+
+# Rules that know how many items they could judge, and which they could not (a part without
+# component data, a capacitor without a rating). `rule_status` reports a rule that judged
+# nothing as not checked, and lists the items it skipped.
+SCOPE: dict[str, Callable[[Project], tuple[int, list[str]]]] = {
+    **kicad_schematic.SCOPE, **kicad_components.SCOPE, **kicad_board.SCOPE, **spice.SCOPE,
+}
+
+
+def run(project: Project, rules: tuple[Rule, ...] = ALL_RULES) -> list[Finding]:
+    """Run every rule and return findings, worst first."""
+    order = {"error": 0, "warning": 1, "info": 2}
+    findings: list[Finding] = []
+    for rule in rules:
+        for finding in rule(project):
+            if project.schematic and any(
+                p.resolution == Resolution.SERIES_R
+                and finding.location.artifact == project.relative(p.sheet)
+                and finding.location.pin == p.port_pin
+                for p in project.schematic.pins.values()
+            ):
+                finding = replace(finding, detector=Detector.HEURISTIC,
+                                  confidence=min(finding.confidence, 0.8))
+            findings.append(finding)
+    return sorted(
+        findings,
+        key=lambda f: (order.get(str(f.severity), 9), f.rule_id, f.location.describe()),
+    )
+
+
+def _external(project: Project, name: str) -> dict:
+    return (project.design.external.get(name) or {}) if project.design else {}
+
+
+def _ran(project: Project, name: str) -> bool:
+    """The tool ran (a review), or would run (`inspect` marks it planned without running it)."""
+    run = _external(project, name)
+    return bool(run.get("ran") or run.get("planned"))
+
+
+def _availability(project: Project) -> tuple[dict[str, bool], dict[str, str]]:
+    """What each requirement token needs, and a sentence for when it is missing."""
+    design = project.design
+    requirements = design.requirements if design else None
+    board = design.board if design else None
+    available = {
+        "schematic": project.schematic is not None,
+        "schematic_identity": project.schematic is not None or project.part_conflict is not None,
+        "matching_part": project.part_conflict is None,
+        "mcu": project.mcu is not None,
+        "firmware": project.firmware is not None,
+        "mcu_database": stm32.af_table(project) is not None,
+        "kicad_project": design is not None,
+        "kicad_schematic": bool(design and design.schematic),
+        "kicad_board": board is not None,
+        "board_outline": bool(board and len(board.outline) >= 3),
+        "kicad_cli_erc": _ran(project, "erc"),
+        "kicad_cli_netlist": _ran(project, "netlist"),
+        "kicad_cli_drc": _ran(project, "drc"),
+        "connector_specs": bool(requirements and requirements.connectors),
+        "single_sided_assembly": bool(requirements and requirements.assembly == "single-sided"),
+        "smd_edge_requirement": bool(requirements and requirements.smd_edge_clearance_mm is not None),
+        "test_points_enabled": bool(requirements is None or requirements.test_points != "off"),
+        "simulations": bool(requirements and requirements.simulations),
+        "ngspice": _ran(project, "spice"),
+    }
+    reasons = {
+        "schematic": "no MCU pin map was extracted from the schematic",
+        "schematic_identity": "no schematic MCU could be identified",
+        "matching_part": "the schematic and the .ioc name different MCU parts",
+        "mcu": "no .ioc was read",
+        "firmware": "no firmware tree was read",
+        "mcu_database": "STM32CubeMX's MCU database was not found (PCBA_CUBEMX_DB)",
+        "kicad_project": "no KiCad project was found",
+        "kicad_schematic": "no KiCad schematic was read",
+        "kicad_board": "no .kicad_pcb was read",
+        "board_outline": "the board has no closed Edge.Cuts outline",
+        "kicad_cli_erc": _external(project, "erc").get("reason") or "kicad-cli did not run",
+        "kicad_cli_netlist": _external(project, "netlist").get("reason") or "kicad-cli did not run",
+        "kicad_cli_drc": _external(project, "drc").get("reason") or "kicad-cli did not run",
+        "connector_specs": "no [[connectors]] in pcba-requirements.toml",
+        "single_sided_assembly": 'pcba-requirements.toml does not declare board.assembly = "single-sided"',
+        "smd_edge_requirement": "no board.smd_edge_clearance_mm in pcba-requirements.toml",
+        "test_points_enabled": 'board.test_points = "off" in pcba-requirements.toml',
+        "simulations": "no [[simulations]] in pcba-requirements.toml",
+        "ngspice": _external(project, "spice").get("reason") or "ngspice did not run",
+    }
+    return available, reasons
+
+
+def applicable(project: Project, rule_id: str) -> bool:
+    """Whether a rule concerns this project's schematic format at all."""
+    form = FORMATS.get(rule_id)
+    if form == "kicad":
+        return "kicad" in project.formats
+    if form == "altium":
+        return project.formats != ("kicad",)
+    return True
+
+
+def coverage(project: Project) -> dict:
+    """Which rules could run, and which could not — with the reason.
+
+    Surfaced by the CLI so "0 findings" never gets confused with "nothing was checked".
+    """
+    available, reasons = _availability(project)
+    ran: list[str] = []
+    skipped: list[str] = []
+    not_applicable: list[str] = []
+    for rule_id, needs in REQUIREMENTS.items():
+        if not applicable(project, rule_id):
+            not_applicable.append(f"{rule_id} (applies to {FORMATS[rule_id]} projects)")
+            continue
+        missing = [n for n in needs if not available[n]]
+        if missing:
+            skipped.append(f"{rule_id} (no {', '.join(missing)})")
+        else:
+            ran.append(rule_id)
+    # The same signal sets pin_mismatch compares, so "compared" cannot overstate the rule.
+    schematic_pins = cross_domain.schematic_signal_pins(project) \
+        if project.schematic else {}
+    ioc_pins = cross_domain.ioc_signal_pins(project) \
+        if project.mcu else {}
+    schematic_signals = {s: len(p) for s, p in schematic_pins.items()}
+    ioc_signals = {s: len(p) for s, p in ioc_pins.items()}
+    comparable = {s for s, n in schematic_signals.items() if n == 1 and ioc_signals.get(s) == 1} \
+        if not project.part_conflict else set()
+    ambiguous = sorted(s for s in set(schematic_signals) | set(ioc_signals)
+                       if schematic_signals.get(s, 0) > 1 or ioc_signals.get(s, 0) > 1)
+    # Each configured placement is compared by name when both sides name the signal, else
+    # on its pad (see cross_domain.pin_placements). Either counts; the reasons below are why
+    # neither was possible.
+    at_pad = {placed[0]: placed for placed in cross_domain.pin_placements(project)}
+    compared = 0
+    uncompared = []
+    for signal, placements in sorted(ioc_pins.items()):
+        for port_pin, assignment in placements:
+            placed = at_pad.get(port_pin)
+            status = placed[4] if placed else None
+            if signal in comparable or status in cross_domain.COMPARED_AT_PIN:
+                compared += 1
+                continue
+            detail = {"signal": signal, "ioc_pin": port_pin,
+                      "ioc_key": assignment.signal_key or f"{port_pin}.Signal"}
+            if project.part_conflict:
+                detail["reason"] = "part_conflict"
+            elif not project.schematic:
+                detail["reason"] = "no_schematic"
+            else:
+                pin = placed[3] if placed else None
+                if pin is not None:
+                    detail["schematic_artifact"] = project.relative(pin.sheet)
+                    if pin.net:
+                        detail["schematic_net"] = pin.net
+                detail["reason"] = status or "pin_not_in_schematic"
+            uncompared.append(detail)
+    statistics = {"schematic_signals": sum(schematic_signals.values()),
+                  "ioc_signals": sum(ioc_signals.values()), "compared_signals": compared,
+                  "ambiguous_signals": ambiguous, "uncompared_signals": uncompared}
+    out = {"ran": sorted(ran), "skipped": sorted(skipped), "statistics": statistics}
+    if not_applicable:
+        out["not_applicable"] = sorted(not_applicable)
+    if project.design is not None:
+        out["tools"] = _tools(project)
+        spice_results = _external(project, "spice").get("results")
+        if spice_results:
+            out["simulations"] = [
+                {k: v for k, v in r.items() if k in ("name", "status", "value", "reason", "measure", "pass", "warn")}
+                | {"netlist": project.relative(r["netlist"])} for r in spice_results]
+    return out
+
+
+def _tools(project: Project) -> dict:
+    """Which external tools ran for this review, their versions, or why they did not."""
+    out = {}
+    for name in ("erc", "netlist", "drc", "spice"):
+        run = _external(project, name)
+        if not run:
+            continue
+        entry = {"ran": bool(run.get("ran"))}
+        for key in ("tool", "version", "reason"):
+            if run.get(key):
+                entry[key] = run[key]
+        out[name] = entry
+    return out
+
+
+def rule_status(project: Project, coverage_data: dict, findings: list[Finding]) -> list[dict]:
+    """Every rule as passed, failed, info (only informational findings), not checked (with the
+    reason) or not applicable. A rule that ran but had nothing to judge is not checked, and the
+    items a rule skipped (a part without component data) are listed under `unchecked`.
+
+    Computed from the unfiltered findings, like the rest of coverage: a baseline hides findings,
+    it does not turn a failed rule into a passed one.
+    """
+    _available, reasons = _availability(project)
+    counts: dict[str, int] = {}
+    serious: set[str] = set()
+    for finding in findings:
+        counts[finding.rule_id] = counts.get(finding.rule_id, 0) + 1
+        if str(finding.severity) != "info":
+            serious.add(finding.rule_id)
+    skipped = {entry.split(" ")[0]: entry for entry in coverage_data.get("skipped", [])}
+    not_applicable = {entry.split(" ")[0] for entry in coverage_data.get("not_applicable", [])}
+    out = []
+    for rule_id, needs in sorted(REQUIREMENTS.items()):
+        entry: dict = {"rule_id": rule_id}
+        if rule_id in not_applicable:
+            entry.update(status="not_applicable", reason=f"applies to {FORMATS[rule_id]} projects only")
+        elif rule_id in skipped:
+            missing = [n for n in needs if not _available[n]]
+            entry.update(status="not_checked", reason="; ".join(reasons[n] for n in missing))
+        else:
+            checked, unchecked = SCOPE[rule_id](project) if rule_id in SCOPE else (None, [])
+            if counts.get(rule_id):
+                entry.update(status="failed" if rule_id in serious else "info", findings=counts[rule_id])
+            elif checked == 0:
+                entry.update(status="not_checked",
+                             reason="nothing this rule could judge" + (f": {unchecked[0]}" if unchecked else ""))
+            elif (rule_id == "cross_domain.pin.mismatch"
+                  and not coverage_data.get("statistics", {}).get("compared_signals")):
+                entry.update(status="not_checked", reason="no configured signal could be compared")
+            else:
+                entry.update(status="passed")
+            if unchecked:
+                entry["unchecked"] = unchecked
+        out.append(entry)
+    return out
+
+
+__all__ = ["ALL_RULES", "FORMATS", "REQUIREMENTS", "Rule", "applicable", "coverage", "rule_status", "run"]