enginehall 2.0.0__py3-none-any.whl

pcba/adapters/cubemx_drive.py

@@ -0,0 +1,248 @@
+"""Drive STM32CubeMX's script mode non-interactively.
+
+Why this exists
+---------------
+CubeMX's `-q <script>` looks like a CLI and is not one. Two things bite, and both present as
+"the tool is just slow":
+
+1. **It always builds a GUI.** `MicroXplorer.run()` constructs a JFrame before it reads the
+   script, so `-Djava.awt.headless=true` throws HeadlessException and a plain shell launch
+   (no WindowServer) blocks forever at 0% CPU with no error at all. Launching through
+   LaunchServices (`open -a … --args -q script`) puts it in the logged-in GUI session and the
+   script runs.
+
+2. **It stops on modal dialogs.** Even in script mode CubeMX raises dialogs ("Memory
+   Protection Unit for Cortex-M7", migration prompts, code-gen warnings) and waits for a
+   human. That is what a "hang" almost always is. This answers them.
+
+Buttons are matched on the accessibility **description**, not the title: Swing exposes
+`AXTitle` as `missing value` for every button, but sets a usable `AXDescription` ("Yes",
+"No", "OK", …).
+
+The ceiling, stated plainly
+---------------------------
+macOS only, and it needs a logged-in GUI session plus Accessibility permission. It cannot run
+over ssh, in CI, or on Windows/Linux. That is a property of CubeMX, not of this code, and no
+amount of engineering here removes it — so this is a workstation convenience, never a build
+step. Anything that must run in CI has to read CubeMX's *data* instead of driving its *UI*,
+which is what the rest of the engine does.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+
+APP_CANDIDATES = (
+    "/Applications/STMicroelectronics/STM32CubeMX.app",
+    "/Applications/STM32CubeMX.app",
+    str(Path.home() / "Applications/STMicroelectronics/STM32CubeMX.app"),
+)
+
+# Dialogs CubeMX raises in script mode, and the answer that is safe by default.
+#
+# The MPU prompt defaults to "No" because accepting it generates a CubeMX-owned MPU_Config()
+# that competes with, and renumbers the regions of, any MPU setup the project already has.
+# Declining leaves the project's own configuration intact, which is the recoverable choice.
+DEFAULT_ANSWERS: tuple[tuple[str, str], ...] = (("Memory Protection Unit*", "No"),)
+
+POLL_SECONDS = 2
+
+FileSignature = tuple[int, int, int, int]
+
+
+# How macOS words a denied Accessibility request; the error number alone is ambiguous.
+ACCESS_DENIED = ("not allowed assistive access", "-25211")
+ACCESS_DENIED_MESSAGE = (
+    "no Accessibility permission — osascript cannot see CubeMX's windows.\n"
+    "Grant it in System Settings > Privacy & Security > Accessibility to the "
+    "app running this (Terminal, iTerm, your IDE), then retry."
+)
+
+
+class DriveError(RuntimeError):
+    """A controlled failure while driving CubeMX."""
+
+
+@dataclass(frozen=True, slots=True)
+class Result:
+    ok: bool
+    detail: str
+
+
+def _file_signature(path: Path | None) -> FileSignature | None:
+    """Metadata that changes when CubeMX creates or rewrites an expected file."""
+    if path is None:
+        return None
+    try:
+        stat = path.stat()
+    except FileNotFoundError:
+        return None
+    return (stat.st_ino, stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns)
+
+
+def find_app(explicit: str | None = None) -> Path:
+    if explicit:
+        path = Path(explicit)
+        if not path.exists():
+            raise DriveError(f"STM32CubeMX not found at {path}")
+        return path
+    for candidate in APP_CANDIDATES:
+        if Path(candidate).is_dir():
+            return Path(candidate)
+    raise DriveError(
+        "STM32CubeMX.app not found. Pass --app, or install CubeMX.\nTried:\n  "
+        + "\n  ".join(APP_CANDIDATES)
+    )
+
+
+def preflight() -> None:
+    """Fail early and specifically, rather than after a 300 s timeout."""
+    if sys.platform != "darwin":
+        raise DriveError(
+            "`enginehall cubemx drive` is macOS-only: it drives CubeMX's GUI through "
+            "LaunchServices and the Accessibility API. This is a CubeMX limitation — its "
+            "script mode is not headless. Read the .ioc with `enginehall cubemx` instead."
+        )
+    if not shutil.which("osascript"):
+        raise DriveError("osascript not found — cannot answer CubeMX's modal dialogs.")
+    # Asked directly rather than inferred from an error later: the denial's wording is
+    # localized, while "UI elements enabled" answers true or false in every language.
+    if _osascript('tell application "System Events" to get UI elements enabled') == "false":
+        raise DriveError(ACCESS_DENIED_MESSAGE)
+
+
+def _osascript(script: str) -> str:
+    """Run AppleScript. Empty string for transient errors; raise on the fatal one.
+
+    A missing Accessibility permission is fatal and worth a clear message: without it we
+    cannot even see the dialogs, so every run would silently time out. preflight() asks for
+    it directly; here an English "not allowed assistive access" or -25211 is caught as well.
+    Everything else means "nothing to see": -1728 (cannot get the process) when CubeMX exits
+    between the process check and the query, or before its window exists; -1719 (invalid
+    index) while it is still loading its MCU database and has no window yet.
+    """
+    proc = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
+    if proc.returncode != 0:
+        if any(marker in proc.stderr for marker in ACCESS_DENIED):
+            raise DriveError(ACCESS_DENIED_MESSAGE)
+        return ""
+    return proc.stdout.strip()
+
+
+def _running() -> bool:
+    return subprocess.run(["pgrep", "-f", "STM32CubeMX"], capture_output=True).returncode == 0
+
+
+def _front_window() -> str:
+    return _osascript(
+        'tell application "System Events" to tell process "STM32CubeMX" '
+        "to get name of front window"
+    )
+
+
+def _buttons() -> list[str]:
+    raw = _osascript(
+        'tell application "System Events" to tell process "STM32CubeMX" to tell front window '
+        "to get description of every button"
+    )
+    return [b.strip() for b in raw.split(",") if b.strip() and b.strip() != "missing value"]
+
+
+def _click(description: str) -> bool:
+    out = _osascript(
+        'tell application "System Events" to tell process "STM32CubeMX" to tell front window '
+        f'to click (first button whose description is "{description}")'
+    )
+    return "error" not in out.lower()
+
+
+def drive(
+    script: Path,
+    expect: Path | None = None,
+    answers: tuple[tuple[str, str], ...] = (),
+    timeout: int = 300,
+    app: str | None = None,
+    log=sys.stderr,
+) -> Result:
+    """Run a CubeMX `.mx` script, answering dialogs, gated on `expect` appearing."""
+    preflight()
+    bundle = find_app(app)
+    script = Path(script).resolve()
+    if not script.is_file():
+        raise DriveError(f"script not found: {script}")
+
+    all_answers = tuple(DEFAULT_ANSWERS) + tuple(answers)
+    target = Path(expect).resolve() if expect else None
+    target_before = _file_signature(target)
+
+    if _running():
+        raise DriveError("CubeMX is already running; close it after saving your work")
+
+    subprocess.run(["open", "-a", str(bundle), "--args", "-q", str(script)], check=True)
+    print(f"launched CubeMX with {script.name}", file=log)
+
+    deadline = time.time() + timeout
+    answered: set[str] = set()
+    while time.time() < deadline:
+        target_after = _file_signature(target)
+        if target_after is not None and target_after != target_before:
+            time.sleep(POLL_SECONDS)  # the file appears before CubeMX finishes flushing it
+            return Result(True, f"{target} produced or updated")
+        if not _running():
+            if target:
+                return Result(False, f"CubeMX exited without producing or updating {target}")
+            return Result(True, "CubeMX exited")
+
+        window = _front_window()
+        # The main window is titled "STM32CubeMX*"; anything else is a modal in the way.
+        if window and not window.startswith("STM32CubeMX") and window not in answered:
+            buttons = _buttons()
+            choice = next((b for pattern, b in all_answers if fnmatch(window, pattern)), None)
+            if choice and choice in buttons:
+                print(f"dialog {window!r} -> clicking {choice!r}", file=log)
+                _click(choice)
+                answered.add(window)
+            elif buttons:
+                # Guessing here could silently accept a destructive migration. Stop and say
+                # exactly what to pass.
+                return Result(
+                    False,
+                    f"unhandled dialog {window!r}; buttons={buttons}\n"
+                    f'       pass --answer "{window}=<button>" to answer it',
+                )
+        time.sleep(POLL_SECONDS)
+
+    return Result(False, f"timed out after {timeout}s (front window: {_front_window()!r})")
+
+
+def parse_answer(raw: str) -> tuple[str, str]:
+    if "=" not in raw:
+        raise DriveError(f"--answer needs GLOB=BUTTON, got {raw!r}")
+    pattern, button = raw.split("=", 1)
+    return pattern, button
+
+
+def make_script(load: str | None = None, config: Path | None = None, generate: bool = False) -> str:
+    """Build a `.mx` script.
+
+    `load` takes the **RefName**, not the orderable part number: it resolves to
+    `db/mcu/<arg>.xml`, so `STM32H745IITx` works and `STM32H745IIT6` raises "Can't create …".
+    Only the x-wildcard file exists.
+    """
+    lines = []
+    if load:
+        lines.append(f"load {load}")
+    if config:
+        lines.append(f'config load "{Path(config).resolve()}"')
+    if generate:
+        lines.append("project generate")
+    elif config:
+        lines.append("config save")
+    lines.append("exit")
+    return "\n".join(lines) + "\n"

pcba/baseline.py

@@ -0,0 +1,151 @@
+"""Versioned finding suppressions for an established project baseline."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from pcba.model.finding import Finding
+
+
+class BaselineError(ValueError):
+    """A baseline cannot be read or does not match the published format."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Suppression:
+    finding_id: str
+    reason: str
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Baseline:
+    path: Path
+    suppressions: tuple[Suppression, ...]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class AppliedBaseline:
+    path: Path
+    suppressed: tuple[Finding, ...]
+    stale_ids: tuple[str, ...]
+    root: Path | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "path": _reported_path(self.path, self.root),
+            "suppressed": len(self.suppressed),
+            "stale": list(self.stale_ids),
+        }
+
+
+def _reported_path(path: Path, root: Path | None) -> str:
+    """Project-relative POSIX path, or the filename if the baseline is outside."""
+    resolved = path.resolve()
+    if root is not None:
+        try:
+            return resolved.relative_to(Path(root).resolve()).as_posix()
+        except ValueError:
+            return resolved.name
+    return resolved.name if path.is_absolute() else path.as_posix()
+
+
+def load(path: Path | str) -> Baseline:
+    source = Path(path)
+    try:
+        payload = json.loads(source.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise BaselineError(f"cannot read baseline {source}: {exc}") from exc
+    except UnicodeDecodeError as exc:
+        raise BaselineError(f"baseline {source} is not UTF-8: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise BaselineError(f"invalid baseline JSON in {source}: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise BaselineError("baseline must be a JSON object")
+    unknown = sorted(set(payload) - {"schema_version", "suppressions"})
+    if unknown:
+        raise BaselineError(f"unknown baseline fields: {', '.join(unknown)}")
+    if payload.get("schema_version") != 1:
+        raise BaselineError("baseline schema_version must be 1")
+    entries = payload.get("suppressions")
+    if not isinstance(entries, list):
+        raise BaselineError("baseline suppressions must be a list")
+
+    suppressions: list[Suppression] = []
+    seen: set[str] = set()
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise BaselineError(f"baseline suppression {index} must be an object")
+        unknown = sorted(set(entry) - {"id", "reason"})
+        if unknown:
+            raise BaselineError(
+                f"unknown fields in baseline suppression {index}: {', '.join(unknown)}"
+            )
+        finding_id = entry.get("id")
+        reason = entry.get("reason")
+        if not isinstance(finding_id, str) or not finding_id:
+            raise BaselineError(f"baseline suppression {index} needs a non-empty id")
+        if not isinstance(reason, str) or not reason.strip():
+            raise BaselineError(f"baseline suppression {finding_id!r} needs a reason")
+        if finding_id in seen:
+            raise BaselineError(f"duplicate baseline suppression id: {finding_id}")
+        seen.add(finding_id)
+        suppressions.append(Suppression(finding_id=finding_id, reason=reason.strip()))
+    return Baseline(path=source.resolve(), suppressions=tuple(suppressions))
+
+
+def apply(
+    findings: list[Finding],
+    saved: Baseline,
+    root: Path | str | None = None,
+) -> tuple[list[Finding], AppliedBaseline]:
+    by_id = {finding.id: finding for finding in findings}
+    suppressed_ids = {entry.finding_id for entry in saved.suppressions}
+    active = [finding for finding in findings if finding.id not in suppressed_ids]
+    suppressed = tuple(finding for finding in findings if finding.id in suppressed_ids)
+    stale = tuple(sorted(suppressed_ids - by_id.keys()))
+    return active, AppliedBaseline(
+        path=saved.path,
+        suppressed=suppressed,
+        stale_ids=stale,
+        root=Path(root) if root is not None else None,
+    )
+
+
+def write(
+    path: Path | str,
+    findings: list[Finding],
+    *,
+    reason: str = "Present when the project baseline was created.",
+) -> Path:
+    """Atomically write a deterministic baseline for the supplied findings."""
+    if not reason.strip():
+        raise BaselineError("baseline reason must not be empty")
+    target = Path(path).resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schema_version": 1,
+        "suppressions": [
+            {"id": finding.id, "reason": reason.strip()}
+            for finding in sorted(findings, key=lambda item: item.id)
+        ],
+    }
+    text = json.dumps(payload, indent=2) + "\n"
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{target.name}.", suffix=".tmp", dir=target.parent
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(target)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+    return target

pcba/changes.py

@@ -0,0 +1,81 @@
+"""Git-backed filtering for findings affected by a change set."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import subprocess
+from pathlib import Path
+
+from pcba.model.finding import Finding
+
+
+class ChangeSetError(RuntimeError):
+    """Git could not resolve the requested change set."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class AppliedChangeFilter:
+    base: str
+    files: tuple[str, ...]
+    omitted: int
+
+    def to_dict(self) -> dict:
+        return {"base": self.base, "files": list(self.files), "omitted": self.omitted}
+
+
+def _git(root: Path, *args: str) -> list[str]:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=root,
+            check=True,
+            capture_output=True,
+        )
+    except FileNotFoundError as exc:
+        raise ChangeSetError("git is required for --changed-only") from exc
+    except subprocess.CalledProcessError as exc:
+        output = exc.stderr.strip() or exc.stdout.strip()
+        raise ChangeSetError(output.decode(errors="replace") or "git command failed") from exc
+    # Names are bytes as git stored them, decoded the way Python decodes file names: the console
+    # locale (cp1252 on many Windows machines) would turn "mäin.c" into "mäin.c".
+    return [os.fsdecode(name) for name in completed.stdout.split(b"\0") if name]
+
+
+def changed_files(root: Path | str, base: str) -> tuple[str, ...]:
+    """Return tracked and untracked paths relative to the project root."""
+    if not base or base.startswith("-"):
+        raise ChangeSetError("git revision must not look like a command option")
+    project = Path(root).resolve()
+    # -z: without it git quotes names with non-ASCII bytes, spaces or quotes ("m\303\244in.c"),
+    # and a quoted name never matches a finding's artifact.
+    tracked = _git(project, "diff", "--name-only", "-z", "--relative", base, "--")
+    untracked = _git(project, "ls-files", "-z", "--others", "--exclude-standard")
+    return tuple(sorted({Path(name).as_posix() for name in tracked + untracked}))
+
+
+def _finding_artifacts(finding: Finding) -> set[str]:
+    artifacts = {finding.location.artifact}
+    for evidence in finding.evidence:
+        if not evidence.source:
+            continue
+        source, separator, line = evidence.source.rpartition(":")
+        artifacts.add(source if separator and line.isdigit() else evidence.source)
+    return artifacts
+
+
+def apply(
+    findings: list[Finding], root: Path | str, base: str
+) -> tuple[list[Finding], AppliedChangeFilter]:
+    files = changed_files(root, base)
+    changed = set(files)
+    selected = (
+        findings
+        if "pcba-studio.toml" in changed
+        else [finding for finding in findings if _finding_artifacts(finding) & changed]
+    )
+    return selected, AppliedChangeFilter(
+        base=base,
+        files=files,
+        omitted=len(findings) - len(selected),
+    )