chipgraph 0.1.0__py3-none-any.whl

chipgraph/adapters/parser/generic_regex.py

@@ -0,0 +1,75 @@
+"""A configurable regex-based log parser, for tools with no dedicated parser.
+
+The pattern must define named groups ``file``, ``line`` and ``msg``; ``rule`` and
+``severity`` are optional. One `Issue` is produced per match, found with
+`re.finditer` over the whole log text (so `pattern` may itself be multi-line).
+"""
+
+from __future__ import annotations
+
+import re
+
+from chipgraph.core.contracts import Issue
+from chipgraph.core.contracts.types import Severity
+
+_REQUIRED_GROUPS = ("file", "line", "msg")
+_SEVERITY_PREFIXES: tuple[tuple[str, Severity], ...] = (
+    ("err", "error"),
+    ("warn", "warning"),
+    ("info", "info"),
+)
+
+
+class GenericRegexParser:
+    """A `LogParser` driven entirely by a user-supplied regex pattern."""
+
+    name = "generic-regex"
+
+    def __init__(
+        self,
+        pattern: str,
+        severity_group: str | None = None,
+        default_severity: Severity = "error",
+    ) -> None:
+        try:
+            self._regex = re.compile(pattern, re.MULTILINE)
+        except re.error as exc:
+            raise ValueError(f"invalid regex pattern {pattern!r}: {exc}") from exc
+
+        group_names = set(self._regex.groupindex)
+        missing = [name for name in _REQUIRED_GROUPS if name not in group_names]
+        if missing:
+            raise ValueError(f"pattern {pattern!r} is missing required named group(s): {missing}")
+        if severity_group is not None and severity_group not in group_names:
+            raise ValueError(
+                f"severity_group {severity_group!r} is not a named group in {pattern!r}"
+            )
+
+        self._severity_group = severity_group
+        self._default_severity = default_severity
+
+    def parse(self, log: str) -> tuple[Issue, ...]:
+        issues: list[Issue] = []
+        for match in self._regex.finditer(log):
+            groups = match.groupdict()
+            issues.append(
+                Issue(
+                    file=groups.get("file") or None,
+                    line=int(groups["line"]) if groups.get("line") else None,
+                    rule=groups.get("rule") or "",
+                    severity=self._severity(groups),
+                    msg=(groups.get("msg") or "").strip(),
+                )
+            )
+        return tuple(issues)
+
+    def _severity(self, groups: dict[str, str | None]) -> Severity:
+        group_name = self._severity_group or "severity"
+        raw = groups.get(group_name)
+        if not raw:
+            return self._default_severity
+        lowered = raw.strip().lower()
+        for prefix, severity in _SEVERITY_PREFIXES:
+            if lowered.startswith(prefix):
+                return severity
+        return self._default_severity

chipgraph/adapters/parser/verible.py

@@ -0,0 +1,55 @@
+"""Log parser for `verible-verilog-lint` output.
+
+Handles both the column-range shape (``file:line:col1-col2: msg [rule]``) and the
+single-column shape (``file:line:col: msg [rule]``). A lint finding is always a style
+warning; a `syntax error at token ...` line (verible reports these the same way, with
+no trailing `[rule]` bracket) is treated as an error with rule ``syntax``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from chipgraph.core.contracts import Issue
+from chipgraph.core.contracts.types import Severity
+
+_LINE_RE = re.compile(
+    r"^(?P<file>[^\s:]+):(?P<line>\d+):(?P<col1>\d+)(-(?P<col2>\d+))?:\s*(?P<msg>.*)$"
+)
+_TRAILING_RULE_RE = re.compile(r"\s*\[(?P<rule>[^\[\]]+)\]\s*$")
+
+
+class VeribleParser:
+    """Parses `verible-verilog-lint` logs into `Issue`s."""
+
+    name = "verible"
+
+    def parse(self, log: str) -> tuple[Issue, ...]:
+        issues: list[Issue] = []
+        for raw_line in log.splitlines():
+            match = _LINE_RE.match(raw_line)
+            if match is None:
+                continue
+            msg = match.group("msg").strip()
+            severity: Severity
+            rule_match = _TRAILING_RULE_RE.search(msg)
+            if rule_match is not None:
+                rule = rule_match.group("rule")
+                msg = msg[: rule_match.start()].rstrip()
+                severity = "warning"
+            elif "syntax error" in msg:
+                rule = "syntax"
+                severity = "error"
+            else:
+                rule = ""
+                severity = "warning"
+            issues.append(
+                Issue(
+                    file=match.group("file"),
+                    line=int(match.group("line")),
+                    rule=rule,
+                    severity=severity,
+                    msg=msg,
+                )
+            )
+        return tuple(issues)

chipgraph/adapters/parser/verilator.py

@@ -0,0 +1,46 @@
+"""Log parser for Verilator (`--lint-only` and simulation build) output.
+
+Handles both the 5.0xx line shape with a column (``%Error-CODE: file:line:col: msg``)
+and the older shape without one (``%Warning-CODE: file:line: msg``), across the
+Verilator versions this project has fixtures for (5.020 and 5.052). Continuation
+lines (indented source context, ``... For warning description ...`` hints) and the
+final summary line (``%Error: Exiting due to N error(s)``, which names no file) are
+ignored.
+"""
+
+from __future__ import annotations
+
+import re
+
+from chipgraph.core.contracts import Issue
+from chipgraph.core.contracts.types import Severity
+
+_LINE_RE = re.compile(
+    r"^\s*%(?P<kind>Error|Warning)(-(?P<rule>[A-Za-z0-9_]+))?:\s+"
+    r"(?P<file>[^\s:]+):(?P<line>\d+)(:(?P<col>\d+))?:\s*(?P<msg>.*)$"
+)
+
+
+class VerilatorParser:
+    """Parses Verilator lint/build logs into `Issue`s."""
+
+    name = "verilator"
+
+    def parse(self, log: str) -> tuple[Issue, ...]:
+        issues: list[Issue] = []
+        for raw_line in log.splitlines():
+            match = _LINE_RE.match(raw_line)
+            if match is None:
+                continue  # continuation line, source context, or summary line
+            kind = match.group("kind")
+            severity: Severity = "error" if kind == "Error" else "warning"
+            issues.append(
+                Issue(
+                    file=match.group("file"),
+                    line=int(match.group("line")),
+                    rule=match.group("rule") or "",
+                    severity=severity,
+                    msg=match.group("msg").strip(),
+                )
+            )
+        return tuple(issues)

chipgraph/adapters/review/__init__.py

@@ -0,0 +1,7 @@
+"""Review adapters: record and retrieve human approvals, behind `ReviewAdapter`."""
+
+from __future__ import annotations
+
+from chipgraph.adapters.review.file import FileReview, ReviewError
+
+__all__ = ["FileReview", "ReviewError"]

chipgraph/adapters/review/file.py

@@ -0,0 +1,123 @@
+"""The `file` review adapter: one small YAML decision file per approval.
+
+Implements `chipgraph.core.plugin_api.protocols.ReviewAdapter`. Every recorded
+decision (approve, reject, baseline, waive) is written as its own file under a
+`decisions_dir` (typically `.chipgraph/decisions/`), so two people approving at the
+same time never conflict on the same file (DESIGN.md 6.1).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from chipgraph.core.contracts import Approval
+
+_UNSAFE_ID_CHARS = re.compile(r"[^A-Za-z0-9._-]")
+_MAX_NAME_ATTEMPTS = 8
+
+
+class ReviewError(Exception):
+    """Raised when a decision file cannot be recorded or a decision file is malformed."""
+
+
+def _safe_id(gate_id: str) -> str:
+    """Replace any character outside `[A-Za-z0-9._-]` in `gate_id` with `_`."""
+    return _UNSAFE_ID_CHARS.sub("_", gate_id)
+
+
+class FileReview:
+    """Records approvals as one YAML file per decision under `decisions_dir`."""
+
+    name = "file"
+
+    def __init__(self, decisions_dir: Path | None = None) -> None:
+        # The registry builds adapters with no arguments; the default is the current
+        # project's `.chipgraph/decisions/`, and callers that know the root pass it.
+        self.decisions_dir = (
+            decisions_dir
+            if decisions_dir is not None
+            else (Path.cwd() / ".chipgraph" / "decisions")
+        )
+
+    def record(self, approval: Approval) -> None:
+        """Write `approval` to a new file in `decisions_dir`.
+
+        The file name is `<safe gate id>--<UTC YYYYmmddTHHMMSSZ>-<6 hex>.yml`. The
+        write is atomic (a temp file is written first, then moved into place with
+        `os.replace`), and an existing file is never overwritten: on the vanishingly
+        unlikely chance of a name collision, a fresh random suffix is tried again.
+        """
+        self.decisions_dir.mkdir(parents=True, exist_ok=True)
+        safe_id = _safe_id(approval.gate_id)
+        ts = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+        content = yaml.safe_dump(approval.model_dump(mode="json"), sort_keys=True)
+
+        for _ in range(_MAX_NAME_ATTEMPTS):
+            suffix = secrets.token_hex(3)
+            target = self.decisions_dir / f"{safe_id}--{ts}-{suffix}.yml"
+            if target.exists():
+                continue
+
+            fd, tmp_name = tempfile.mkstemp(
+                dir=self.decisions_dir, prefix=".tmp-decision-", suffix=".yml"
+            )
+            tmp_path = Path(tmp_name)
+            try:
+                with os.fdopen(fd, "w") as handle:
+                    handle.write(content)
+                if target.exists():
+                    tmp_path.unlink(missing_ok=True)
+                    continue
+                os.replace(tmp_path, target)
+            except BaseException:
+                tmp_path.unlink(missing_ok=True)
+                raise
+            return
+
+        raise ReviewError(
+            f"could not allocate a unique decision file name for gate {approval.gate_id!r} "
+            f"in {self.decisions_dir}"
+        )
+
+    def approvals(self, gate_id: str) -> tuple[Approval, ...]:
+        """Return every approval recorded for `gate_id`, sorted by `at` then file name.
+
+        Every `*.yml`/`*.yaml` file in `decisions_dir` (except temp files left behind
+        by an interrupted write, which start with `.`) is parsed. A file that is not
+        valid YAML, not a mapping, or does not validate as an `Approval` raises
+        `ReviewError` naming that file; it is never silently skipped.
+        """
+        if not self.decisions_dir.is_dir():
+            return ()
+
+        matches: list[tuple[Approval, str]] = []
+        paths = sorted({*self.decisions_dir.glob("*.yml"), *self.decisions_dir.glob("*.yaml")})
+        for path in paths:
+            if path.name.startswith("."):
+                continue
+            try:
+                raw = yaml.safe_load(path.read_text())
+            except yaml.YAMLError as exc:
+                raise ReviewError(f"malformed decision file {path}: invalid YAML: {exc}") from exc
+
+            if not isinstance(raw, dict):
+                raise ReviewError(f"malformed decision file {path}: not a YAML mapping")
+            if raw.get("gate_id") != gate_id:
+                continue
+
+            try:
+                approval = Approval.model_validate(raw)
+            except ValidationError as exc:
+                raise ReviewError(f"malformed decision file {path}: {exc}") from exc
+            matches.append((approval, path.name))
+
+        matches.sort(key=lambda pair: (pair[0].at, pair[1]))
+        return tuple(approval for approval, _ in matches)