rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/gdsfactory/results.py

@@ -0,0 +1,181 @@
+"""Gdsfactory v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``generate_views`` parse shape (``measurements[]`` with
+per-cell polygon/port/area counts plus ``mappings[]`` and
+``violations[]``) onto a typed cell mappings table, a bound
+view, PASS measurements, and findings. Pure function of the
+parsed output: no I/O, no tool calls, deterministic ids derived
+from the run id. Artifact paths stay in the table as evidence;
+no bundle artifact is fabricated without a recorded digest.
+"""
+
+TASK = "generate_views"
+
+_DIAG_CAP = 240
+
+_SEVERITY = {"error": "error", "warning": "warning"}
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _quantity(value, unit):
+    """Build one v1 Quantity, mapping unitless to dimensionless.
+
+    Args:
+        value: Numeric value.
+        unit: Unit string, possibly empty for unitless measures.
+
+    Returns:
+        Quantity mapping with an explicit unit.
+    """
+    return {"value": float(value), "unit": unit if unit else "1"}
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one gdsfactory views parse output to a ResultBundle.
+
+    Cell mappings become a table dataset (component, ports,
+    polygons, bbox area) plus a bound table view; per-cell
+    counts ride PASS measurements; violations become findings
+    with capped messages.
+
+    Args:
+        parsed: v0 parse mapping with ``measurements[]``,
+            ``mappings[]``, and ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    measurements_in = parsed.get("measurements") or []
+    mappings = parsed.get("mappings") or []
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:cells"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(mappings),
+            "columns": [
+                {
+                    "id": f"{table_id}:component",
+                    "name": "component",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [m.get("component", "") for m in mappings],
+                },
+                {
+                    "id": f"{table_id}:ports",
+                    "name": "ports",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(len(m.get("ports") or [])) for m in mappings],
+                },
+                {
+                    "id": f"{table_id}:polygons",
+                    "name": "polygons",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(m.get("n_polygons", 0)) for m in mappings],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:cells",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "cell mappings",
+        }
+    ]
+    measurements = [
+        {
+            "name": item["name"],
+            "value": _quantity(item["value"], item.get("unit", "")),
+            "status": "PASS",
+        }
+        for item in measurements_in
+    ]
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": _SEVERITY.get(v.get("severity"), "info"),
+            "code": v.get("rule", "views.failed"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "not_applicable",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": measurements,
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/hdl_sim/README.md

@@ -0,0 +1,7 @@
+# Icarus HDL simulation adapter
+
+HdlSimAdapter serves run_hdl_test. It compiles project testbench and design sources with iverilog, runs them with vvp under a timeout, and parses compile diagnostics, FATAL, and ERROR output into normalized findings.
+
+The adapter is registered in Engine as the icarus solver. Tool resolution uses PATH or an explicit job tool_dir. When a BwrapRunner is supplied, compile and simulation processes run inside the configured isolation boundary.
+
+Some HDL failures can exit with status zero. Verdicts come from parsed diagnostics and simulation output, never the exit code alone.

rocket_engine/adapters/hdl_sim/__init__.py

@@ -0,0 +1,369 @@
+"""Icarus HDL sim solver adapter: run_hdl_test behind the ToolAdapter port.
+
+Protocol, verified against iverilog 14.0 + vvp: compile the sources
+(exit 2 + `file:line: msg` diagnostics on failure), run the sim under
+a timeout, and parse `FATAL:`/`ERROR:` lines for the verdict. `$error`
+exits 0, so the verdict always comes from parsed output, never from
+the exit code alone. Hangs raise instead of hanging the engine.
+
+Tool resolution: an explicit job `tool_dir` wins, else PATH. Where
+the tools live on disk is B10 integration scope — this adapter only
+requires them resolvable, and refuses loudly when they are not.
+"""
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...execution.runner import tool_roots
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_hdl_test"
+_TIMEOUT_S = 120
+_LOG_NAME = "sim.log"
+
+_COMPILE_RE = re.compile(r"^([^:\s][^:]*):(\d+):\s*(.+)$", re.M)
+_SIM_RE = re.compile(r"^(FATAL|ERROR):\s*(\S+):(\d+):\s*(.*)$")
+_TIME_RE = re.compile(r"Time:\s*(\d+)")
+# Verilog `define names, with an optional =value (no whitespace or
+# shell metacharacters; argv is never shelled, belt and suspenders).
+_DEFINE_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(=[A-Za-z0-9_.+-]+)?")
+
+
+def _parse_compile(text):
+    violations = []
+    for match in _COMPILE_RE.finditer(text):
+        file, line, message = match.group(1), match.group(2), match.group(3)
+        warning = message.lower().startswith("warning")
+        violations.append(
+            {
+                "rule": "compile",
+                "severity": "warning" if warning else "error",
+                "message": message,
+                "file": file,
+                "line": int(line),
+            }
+        )
+    return violations
+
+
+def _block_text(block):
+    """(text, source) for one compile/run block, log-first.
+
+    MIGRATE-STDIO-FILE: the `vvp -l sim.log` file is the parse
+    channel; stdio survives only as a loud fallback for natives
+    recorded before the file channel existed.
+
+    Args:
+        block: Native block with optional `log` plus
+            stdout/stderr.
+
+    Returns:
+        (text, source) with source `log` or `stdio_fallback`.
+    """
+    log = (block or {}).get("log") or ""
+    if log.strip():
+        return log, "log"
+    return (
+        (block or {}).get("stdout", "") + "\n" + (block or {}).get("stderr", ""),
+        "stdio_fallback",
+    )
+
+
+def _parse_sim(text):
+    violations = []
+    lines = text.splitlines()
+    for index, line in enumerate(lines):
+        match = _SIM_RE.match(line)
+        if match is None:
+            continue
+        kind, file, lineno, message = match.groups()
+        violation = {
+            "rule": "assert_fatal" if kind == "FATAL" else "assert_error",
+            "severity": "error",
+            "message": message,
+            "file": file,
+            "line": int(lineno),
+        }
+        if index + 1 < len(lines):
+            timed = _TIME_RE.search(lines[index + 1])
+            if timed:
+                violation["sim_time"] = int(timed.group(1))
+        violations.append(violation)
+    return violations
+
+
+class HdlSimAdapter(ToolAdapter):
+    """run_hdl_test via Icarus: compile plus timed Verilog sim.
+
+    Serves the run_hdl_test operation with deck.tool `icarus` (the
+    only tool). Compiles the sources with iverilog, runs the sim
+    under vvp with a timeout, and parses compile diagnostics plus
+    FATAL/ERROR assertion lines.
+
+    Job keys:
+        sources (required): Verilog source paths, bench included.
+        defines: Verilog `define list, optional =value each.
+        timeout_s: Sim budget in seconds (default 120).
+        tool_dir: Directory holding iverilog/vvp; PATH otherwise.
+        deck: Optional mapping; deck.tool must be icarus here.
+        workdir: Run directory (default ".").
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+
+    Caution: $error exits 0 and hangs raise instead of hanging the
+        engine — the verdict always comes from parsed output, never
+        the exit code alone.
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation, tool, sim, and defines.
+
+        Args:
+            target: Target the capabilities are reported for
+                (accepted, unused — one bench per job).
+
+        Returns:
+            Capability mapping with operations, tool, sim, and
+                defines.
+        """
+        return {"operations": [OPERATION], "tool": "icarus", "sim": "vvp", "defines": True}
+
+    def preflight(self, job):
+        """Check operation, timeout, sources, defines, and tools.
+
+        Cheap deterministic checks first, tool resolution last.
+
+        Args:
+            job: Solver job with operation run_hdl_test plus
+                sources, defines, and timeout inputs.
+
+        Returns:
+            Checked mapping with resolved iverilog/vvp paths,
+                sources, timeout_s, and defines.
+
+        Raises:
+            AdapterError: unsupported_operation for another
+                operation, invalid_command for a bad timeout or
+                defines, invalid_reference for missing sources,
+                missing_dependency for unresolvable tools.
+        """
+        # Cheap deterministic checks first: operation, timeout, sources.
+        # Tool resolution last, since it depends on the machine.
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"HDL sim handles {OPERATION}, got {job.get('operation')}.",
+            )
+        timeout = job.get("timeout_s", _TIMEOUT_S)
+        if (
+            not isinstance(timeout, (int, float))
+            or isinstance(timeout, bool)
+            or not timeout > 0
+        ):
+            raise AdapterError("invalid_command", f"Bad timeout_s: {timeout!r}.")
+        sources = job.get("sources") or []
+        missing = [s for s in sources if not Path(s).is_file()]
+        if not sources or missing:
+            raise AdapterError(
+                "invalid_reference", f"Sources not found: {missing or sources}."
+            )
+        defines = job.get("defines") or []
+        if not isinstance(defines, list) or any(
+            not isinstance(d, str) or not _DEFINE_RE.fullmatch(d) for d in defines
+        ):
+            raise AdapterError("invalid_command", f"Bad defines: {defines!r}.")
+        checked = {
+            "iverilog": self._resolve(job, "iverilog"),
+            "vvp": self._resolve(job, "vvp"),
+            "sources": list(sources),
+            "timeout_s": timeout,
+            "defines": list(defines),
+        }
+        if self._runner is not None:
+            try:
+                self._runner.preflight()
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        return checked
+
+    def execute(self, job):
+        """Compile with iverilog, then run the sim under vvp.
+
+        A failed compile returns its block with no run; the verdict
+        still comes from parse, never the exit code alone. The sim
+        runs with `vvp -l sim.log` so assertion lines land in a
+        file first (MIGRATE-STDIO-FILE; live-verified
+        byte-identical to stdio on vvp 14.0).
+
+        Args:
+            job: Solver job with operation run_hdl_test plus
+                sources, defines, and timeout inputs.
+
+        Returns:
+            Native output with exit_code plus compile and run
+                blocks (run is None when the build failed; the
+                run block carries the vvp log text under `log`).
+
+        Raises:
+            AdapterError: invalid_reference for a missing workdir,
+                runner_unavailable on a sim timeout, plus the
+                preflight codes (execute re-checks first).
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}."
+            )
+        roots = tool_roots([checked["iverilog"], checked["vvp"]])
+        build = self._run(
+            [
+                checked["iverilog"],
+                "-o",
+                "sim.vvp",
+                *[f"-D{d}" for d in checked["defines"]],
+                *checked["sources"],
+            ],
+            workdir,
+            checked["timeout_s"],
+            roots,
+        )
+        if build.returncode != 0:
+            return {
+                "exit_code": build.returncode,
+                "compile": _block(build),
+                "run": None,
+            }
+        run = self._run(
+            [checked["vvp"], "-l", _LOG_NAME, "sim.vvp"],
+            workdir,
+            checked["timeout_s"],
+            roots,
+        )
+        log_path = Path(workdir) / _LOG_NAME
+        run_block = _block(run)
+        run_block["log"] = (
+            log_path.read_text(encoding="utf-8", errors="replace")
+            if log_path.is_file()
+            else ""
+        )
+        return {
+            "exit_code": run.returncode,
+            "compile": _block(build),
+            "run": run_block,
+        }
+
+    def parse(self, native_output):
+        """Parse compile diagnostics plus sim assertion lines.
+
+        Failed compiles and crashed sims with nothing parseable
+        synthesize error violations rather than going clean. The
+        decisive block reads from the vvp log file, falling back
+        to stdio only for older natives (loudly marked).
+
+        Args:
+            native_output: Native output with compile and run blocks.
+
+        Returns:
+            {total, violations[], source} with file/line
+                locations and sim_time where the sim reports it;
+                source is `log` or `stdio_fallback`.
+
+        Raises:
+            AdapterError: runner_unavailable when a compiled run
+                has no run block.
+        """
+        compile_block = native_output.get("compile") or {}
+        compile_text, compile_source = _block_text(compile_block)
+        diags = _parse_compile(compile_text)
+        if compile_block.get("exit_code", 0) != 0:
+            if not diags:
+                # Defensive: a failed compile must never parse as clean.
+                diags = [
+                    {
+                        "rule": "compile",
+                        "severity": "error",
+                        "message": f"iverilog exited {compile_block.get('exit_code')}",
+                    }
+                ]
+            return {
+                "total": len(diags),
+                "violations": diags,
+                "source": compile_source,
+            }
+        run_block = native_output.get("run")
+        if run_block is None:
+            raise AdapterError(
+                "runner_unavailable", "Native output has no run block."
+            )
+        run_text, run_source = _block_text(run_block)
+        sim = _parse_sim(run_text)
+        if run_block.get("exit_code", 0) != 0 and not sim:
+            # Defensive: crashes print nothing parseable; the nonzero
+            # exit is the only signal, and it must fail loudly.
+            sim = [
+                {
+                    "rule": "sim_fail",
+                    "severity": "error",
+                    "message": f"vvp exited {run_block.get('exit_code')}",
+                }
+            ]
+        violations = diags + sim
+        return {
+            "total": len(violations),
+            "violations": violations,
+            "source": run_source,
+        }
+
+    @staticmethod
+    def _resolve(job, binary):
+        tool_dir = job.get("tool_dir")
+        if tool_dir:
+            candidate = Path(tool_dir) / binary
+            if candidate.is_file():
+                return str(candidate)
+            raise AdapterError(
+                "missing_dependency", f"{binary} not found in {tool_dir}."
+            )
+        found = shutil.which(binary)
+        if found is None:
+            raise AdapterError(
+                "missing_dependency",
+                f"{binary} not on PATH (pass tool_dir or integrate via B10).",
+            )
+        return found
+
+    def _run(self, argv, workdir, timeout_s, extra_binds=()):
+        if self._runner is not None:
+            try:
+                return self._runner.run(argv, workdir, timeout_s, extra_binds)
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        try:
+            return subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=timeout_s,
+                cwd=workdir,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", f"sim timed out after {timeout_s}s."
+            ) from exc
+
+
+def _block(proc):
+    return {
+        "exit_code": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+    }