enginehall 2.0.0__py3-none-any.whl

pcba/publish.py

@@ -0,0 +1,269 @@
+"""Publish a review report to a development project's check runs (`enginehall review --publish`).
+
+Only the report leaves the machine: findings, their locations and evidence, and coverage. No
+design file, firmware source or absolute local path is sent (principle 3): the project paths in
+the report are made project-relative, and the local root and home folder are scrubbed from every
+other string. Stdlib only, like the rest of the engine.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path, PurePath
+
+from pcba import __version__
+
+DEFAULT_TOKEN_ENV = "PCBA_WORKSPACE_TOKEN"
+MAX_BODY_BYTES = 8 * 1024 * 1024
+TIMEOUT_SECONDS = 30
+MAX_REF = 255
+
+_KEY = re.compile(r"^[A-Za-z][A-Za-z0-9]{1,9}$")
+_SHA = re.compile(r"^[0-9a-fA-F]{7,64}$")
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+_UUID = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+# `git@github.com:owner/name.git`, the scp-like form `git remote` reports for SSH clones.
+_SCP_REMOTE = re.compile(r"^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9.-]+):(?!//)([^\s]+)$")
+MAX_REPOSITORY = 500
+GIT_TIMEOUT_SECONDS = 5
+
+
+class PublishError(Exception):
+    """A publish that could not be prepared or delivered; the CLI reports it with exit 2."""
+
+
+@dataclass(frozen=True, slots=True)
+class Target:
+    project: str
+    url: str
+    token: str
+    commit: str | None
+    ref: str | None
+    source: str
+    repository: str | None = None
+
+    @property
+    def endpoint(self) -> str:
+        return f"{self.url}/api/p/{urllib.parse.quote(self.project)}/check-runs"
+
+
+def _truthy(value: str | None) -> bool:
+    return (value or "").strip().lower() not in ("", "0", "false", "no")
+
+
+def _origin(value: str) -> str:
+    url = value.strip().rstrip("/")
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme not in ("https", "http") or not parsed.hostname:
+        raise PublishError(f"--url must be an http(s) origin such as https://enginehall.com, not {value!r}")
+    if parsed.scheme == "http" and parsed.hostname not in _LOCAL_HOSTS:
+        raise PublishError("--url must use https (plain http is accepted only for localhost)")
+    if parsed.query or parsed.fragment or parsed.username or parsed.password:
+        raise PublishError("--url must be the workspace origin, without credentials, query or fragment")
+    return url
+
+
+def repository_url(value: str | None) -> str | None:
+    """A repository id, or a clone URL as https without credentials, `.git` or query; None if unusable.
+
+    `git@host:owner/name.git`, `ssh://git@host:22/owner/name` and `https://user:token@host/owner/name`
+    all become `https://host/owner/name`, so no credential embedded in a remote ever leaves the machine.
+    """
+    text = (value or "").strip()
+    if not text:
+        return None
+    if _UUID.match(text):
+        return text.lower()
+    scp = _SCP_REMOTE.match(text)
+    if scp and "://" not in text:
+        host, path = scp.group(1), scp.group(2)
+    else:
+        try:
+            parsed = urllib.parse.urlsplit(text)
+        except ValueError:
+            return None
+        if parsed.scheme not in ("https", "http", "ssh", "git", "git+ssh") or not parsed.hostname:
+            return None
+        host, path = parsed.hostname, parsed.path
+    path = re.sub(r"\.git$", "", path.strip("/").rstrip("/"))
+    # A dotted host only: `C:/repo` or a single-label name is a local path or a LAN host, never a match.
+    if not path or not re.match(r"^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$", host or ""):
+        return None
+    url = f"https://{host.lower()}/{path}"
+    return url if len(url) <= MAX_REPOSITORY and " " not in url else None
+
+
+def _git(root: Path, *args: str) -> str | None:
+    """One `git` answer for the reviewed folder, or None: no git, no repository, or no answer in time."""
+    try:
+        done = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True,
+                              timeout=GIT_TIMEOUT_SECONDS, check=False)
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None
+    out = done.stdout.strip() if done.returncode == 0 else ""
+    return out or None
+
+
+def detect_commit(root: Path) -> str | None:
+    head = _git(root, "rev-parse", "HEAD")
+    return head.lower() if head and _SHA.match(head) else None
+
+
+def detect_repository(root: Path) -> str | None:
+    return repository_url(_git(root, "remote", "get-url", "origin"))
+
+
+def target(
+    project: str | None,
+    url: str | None,
+    token_env: str | None,
+    commit: str | None,
+    environ: dict[str, str] | None = None,
+    repository: str | None = None,
+    root: Path | None = None,
+) -> Target:
+    """Check every publish argument before the review runs, so a typo never costs a full review.
+
+    Without `commit` the commit is `$GITHUB_SHA`, else `git rev-parse HEAD` in `root`; without
+    `repository` it is the `origin` remote's URL. A folder without git publishes without them.
+    """
+    env = os.environ if environ is None else environ
+    if not project or not _KEY.match(project):
+        raise PublishError("--publish needs --project KEY: the development project's key (2 to 10 letters or digits)")
+    if not url:
+        raise PublishError("--publish needs --url, the workspace origin (e.g. https://enginehall.com)")
+    name = token_env or DEFAULT_TOKEN_ENV
+    if not _ENV_NAME.match(name):
+        raise PublishError(f"--token-env must name an environment variable, not {name!r}")
+    token = (env.get(name) or "").strip()
+    if not token:
+        raise PublishError(f"--publish needs a project token in the environment variable {name}")
+    if commit is not None and not _SHA.match(commit):
+        raise PublishError("--commit must be a commit hash (7 to 64 hex digits)")
+    if commit is None and _SHA.match(env.get("GITHUB_SHA", "")):
+        commit = env["GITHUB_SHA"]
+    if repository is not None:
+        named = repository_url(repository)
+        if named is None:
+            raise PublishError("--repository must be a repository id or its URL (https, ssh or git@host:path)")
+        repository = named
+    if root is not None:
+        if commit is None:
+            commit = detect_commit(root)
+        if repository is None:
+            repository = detect_repository(root)
+    ref = (env.get("GITHUB_REF_NAME") or "").strip()[:MAX_REF] or None
+    source = "ci" if _truthy(env.get("CI")) or _truthy(env.get("GITHUB_ACTIONS")) else "cli"
+    return Target(project.upper(), _origin(url), token, commit.lower() if commit else None, ref, source, repository)
+
+
+def _relative(value: str | None, root: Path) -> str | None:
+    if not value:
+        return None
+    path = Path(value)
+    try:
+        return path.resolve().relative_to(root).as_posix() or "."
+    except ValueError:
+        return PurePath(os.path.relpath(path.resolve(), root)).as_posix()
+
+
+def _scrubber(root: Path):
+    """Replace the local root, then the home folder, in a string."""
+    pairs = []
+    for base, label in ((root, "."), (Path.home(), "~")):
+        for form in {str(base), base.as_posix()}:
+            if len(form) > 1:
+                pairs.append((form, label))
+    pairs.sort(key=lambda pair: -len(pair[0]))
+
+    def scrub(text: str) -> str:
+        for old, new in pairs:
+            text = text.replace(old, new)
+        return text
+
+    return scrub
+
+
+def _scrub(value, scrub):
+    if isinstance(value, str):
+        return scrub(value)
+    if isinstance(value, list):
+        return [_scrub(item, scrub) for item in value]
+    if isinstance(value, dict):
+        return {key: _scrub(item, scrub) for key, item in value.items()}
+    return value
+
+
+def report(result) -> dict:
+    """The JSON report of a review, with no absolute local path in it."""
+    payload = json.loads(result.render("json"))
+    root = Path(result.discovery.root).resolve()
+    project = payload.get("project") or {}
+    project["root"] = "."
+    for key in ("schematic_dir", "kicad_project", "ioc"):
+        project[key] = _relative(project.get(key), root)
+    project["firmware_roots"] = [_relative(p, root) for p in project.get("firmware_roots") or []]
+    payload["project"] = project
+    return _scrub(payload, _scrubber(root))
+
+
+def body(result, destination: Target) -> bytes:
+    data: dict = {"report": report(result), "source": destination.source}
+    if destination.commit:
+        data["commit_sha"] = destination.commit
+    if destination.ref:
+        data["ref"] = destination.ref
+    if destination.repository:
+        data["repository"] = destination.repository
+    encoded = json.dumps(data, separators=(",", ":")).encode("utf-8")
+    if len(encoded) > MAX_BODY_BYTES:
+        raise PublishError(f"the report is larger than {MAX_BODY_BYTES // (1024 * 1024)} MiB and was not published")
+    return encoded
+
+
+def _reason(error: urllib.error.HTTPError) -> str:
+    try:
+        detail = json.loads(error.read().decode("utf-8", "replace") or "{}")
+    except (ValueError, OSError):
+        detail = {}
+    message = detail.get("statusMessage") or detail.get("message") if isinstance(detail, dict) else None
+    return f"HTTP {error.code}" + (f" ({message})" if isinstance(message, str) and message else "")
+
+
+def publish(result, destination: Target) -> dict:
+    """POST the report; returns the server's answer (`id`, `url`). Raises PublishError."""
+    request = urllib.request.Request(
+        destination.endpoint,
+        data=body(result, destination),
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {destination.token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"pcba/{__version__}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as exc:
+        raise PublishError(f"could not publish the report: {_reason(exc)}") from None
+    except urllib.error.URLError as exc:
+        raise PublishError(f"could not publish the report: {exc.reason}") from None
+    except (TimeoutError, OSError) as exc:
+        raise PublishError(f"could not publish the report: {exc}") from None
+    try:
+        answer = json.loads(raw.decode("utf-8"))
+    except ValueError:
+        raise PublishError("could not publish the report: the server's answer is not JSON") from None
+    if not isinstance(answer, dict) or not isinstance(answer.get("id"), str):
+        raise PublishError("could not publish the report: the server's answer has no check run id")
+    return answer

pcba/report/__init__.py

@@ -0,0 +1,7 @@
+"""Rendering findings: text for humans, JSON for agents, SARIF for CI."""
+
+from pcba.report.json_report import to_json
+from pcba.report.sarif import to_sarif
+from pcba.report.text import to_markdown, to_text
+
+__all__ = ["to_json", "to_markdown", "to_sarif", "to_text"]

pcba/report/json_report.py

@@ -0,0 +1,39 @@
+"""Machine-readable output.
+
+Every consumer that is not a human reads this: the MCP server, CI, and any agent. It
+validates against `schemas/finding.schema.json`.
+"""
+
+from __future__ import annotations
+
+import json
+
+from pcba import __version__
+from pcba.model.finding import Finding, Severity
+
+
+def to_json(
+    findings: list[Finding],
+    coverage: dict[str, list[str]] | None = None,
+    project: dict | None = None,
+    indent: int | None = 2,
+    *,
+    baseline: dict | None = None,
+    changes: dict | None = None,
+) -> str:
+    counts = {str(s): sum(1 for f in findings if f.severity is s) for s in Severity}
+    payload = {
+        "schema_version": 1,
+        "tool": {"name": "pcba", "version": __version__},
+        "project": project or {},
+        "summary": {"total": len(findings), **counts},
+        # Callers gate on this. It is not the same as "no findings" and must not be
+        # inferred from an empty list.
+        "coverage": coverage or {},
+        "findings": [f.to_dict() for f in findings],
+    }
+    if baseline is not None:
+        payload["baseline"] = baseline
+    if changes is not None:
+        payload["changes"] = changes
+    return json.dumps(payload, indent=indent, sort_keys=False)

pcba/report/sarif.py

@@ -0,0 +1,128 @@
+"""SARIF 2.1.0 output.
+
+Cheap to emit and it unlocks the VS Code Problems panel, GitHub code scanning, and most CI
+annotators for free — which is why it ships in v1 rather than waiting for a bespoke UI.
+
+The awkward part is that SARIF assumes findings live at a line in a text file, and ours
+often live at a pin on a schematic sheet inside a binary container. Rather than fake a line
+number, artifacts get `region` only when we genuinely have one, and the schematic location
+travels in the message and in `properties`.
+
+Artifact URIs are the project-relative paths every finding already carries, declared
+relative to `%SRCROOT%` so a viewer opens the right file no matter where the report was
+produced or which directory the consumer runs in.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from urllib.parse import quote
+
+from pcba import __version__
+from pcba.model.finding import Finding, Severity
+
+_LEVEL = {Severity.ERROR: "error", Severity.WARNING: "warning", Severity.INFO: "note"}
+_ROOT_ID = "%SRCROOT%"
+
+
+def _artifact_location(artifact: str, windows: bool = os.name == "nt") -> dict:
+    """A URI reference for a finding's artifact: percent-encoded, so a space, `#` or `%` in a
+    file name cannot cut the path short; relative to `%SRCROOT%` unless it lies outside the
+    project, where the absolute path becomes a file URI. That path is read with the rules of
+    the machine that wrote it: `//server/share` is a UNC share on Windows and a plain path
+    elsewhere."""
+    flavours = (PureWindowsPath, PurePosixPath) if windows else (PurePosixPath, PureWindowsPath)
+    for flavour in flavours:
+        path = flavour(artifact)
+        if path.is_absolute():
+            return {"uri": path.as_uri()}
+    return {"uri": quote(artifact, safe="/"), "uriBaseId": _ROOT_ID}
+
+
+def to_sarif(
+    findings: list[Finding],
+    root: Path | None = None,
+    indent: int | None = 2,
+    *,
+    coverage: dict | None = None,
+    discovery: dict | None = None,
+    baseline: dict | None = None,
+    changes: dict | None = None,
+) -> str:
+    rules: dict[str, dict] = {}
+    results: list[dict] = []
+
+    for f in findings:
+        rules.setdefault(
+            f.rule_id,
+            {
+                "id": f.rule_id,
+                "name": f.rule_id,
+                "shortDescription": {"text": f.title},
+                "fullDescription": {"text": f.explanation},
+                "help": {"text": f"{f.consequence}\n\n{f.recommendation}"},
+                "defaultConfiguration": {"level": _LEVEL[f.severity]},
+                "properties": {"detector": str(f.detector), "domain": str(f.domain)},
+            },
+        )
+
+        location: dict = {
+            "physicalLocation": {"artifactLocation": _artifact_location(f.location.artifact)}
+        }
+        if f.location.line:
+            location["physicalLocation"]["region"] = {"startLine": f.location.line}
+
+        evidence = "  ".join(e.value for e in f.evidence)
+        results.append(
+            {
+                "ruleId": f.rule_id,
+                "level": _LEVEL[f.severity],
+                "message": {"text": f"{f.title}. {f.explanation} {evidence}".strip()},
+                "locations": [location],
+                "partialFingerprints": {"pcbaFindingId": f.id},
+                "properties": {
+                    "detector": str(f.detector),
+                    "confidence": f.confidence,
+                    "pin": f.location.pin,
+                    "sheet": f.location.sheet,
+                    "component": f.location.component,
+                    "recommendation": f.recommendation,
+                },
+            }
+        )
+
+    run: dict = {
+        "tool": {
+            "driver": {
+                "name": "EngineHall",
+                "version": __version__,
+                "informationUri": "https://enginehall.com",
+                "rules": list(rules.values()),
+            }
+        },
+        "results": results,
+    }
+    if root:
+        run["originalUriBaseIds"] = {_ROOT_ID: {"uri": Path(root).resolve().as_uri() + "/"}}
+    properties = {}
+    if coverage is not None:
+        properties["coverage"] = coverage
+    if discovery is not None:
+        properties["discovery"] = discovery
+    if baseline is not None:
+        properties["baseline"] = baseline
+    if changes is not None:
+        properties["changes"] = changes
+    if properties:
+        run["properties"] = properties
+
+    return json.dumps(
+        {
+            "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+            "version": "2.1.0",
+            "runs": [run],
+        },
+        indent=indent,
+    )