telchines 1.0.0__py3-none-any.whl

telchines/__init__.py

@@ -0,0 +1,5 @@
+"""Telchines package."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

telchines/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from telchines.cli import app
+
+
+if __name__ == "__main__":
+    app()

telchines/adapters/__init__.py

@@ -0,0 +1 @@
+"""Tool adapters for supported verification tools."""

telchines/adapters/base.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from telchines.adapters.parsing import parse_common_output
+from telchines.errors import AdapterExecutionError
+from telchines.models import AdapterDescriptor, Observation, ToolReference
+from telchines.utils import ensure_directory, utc_now
+
+
+@dataclass(slots=True)
+class AdapterExecution:
+    command: list[str]
+    cwd: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    log_path: str
+    started_at: str
+    finished_at: str
+    observations: list[Observation]
+    summary: str
+    artifacts: dict[str, str] = field(default_factory=dict)
+    result: dict[str, Any] = field(default_factory=dict)
+
+
+class ToolAdapter:
+    name = "base"
+    kind = "tool"
+    category = "tool"
+    validation_mode = "compile_only"
+    binary_names: tuple[str, ...] = ()
+    required_binaries: tuple[str, ...] = ()
+    supported_workflows: tuple[str, ...] = ()
+    artifact_types: tuple[str, ...] = ("log",)
+
+    def is_available(self) -> bool:
+        required = self.required_binaries or self.binary_names
+        if not required:
+            return True
+        return all(shutil.which(binary) for binary in required)
+
+    def version(self) -> str:
+        return "unknown"
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        raise NotImplementedError
+
+    def parse_output(self, run_id: str, text: str) -> list[Observation]:
+        return parse_common_output(run_id, text)
+
+    def parse_result(self, project_root: Path, files: list[str], stdout: str, stderr: str, combined: str) -> dict[str, Any]:
+        return {}
+
+    def collect_artifacts(
+        self,
+        project_root: Path,
+        files: list[str],
+        artifacts_dir: Path,
+        run_id: str,
+        stdout: str,
+        stderr: str,
+        combined: str,
+    ) -> dict[str, str]:
+        return {}
+
+    def describe(self, *, enabled: bool = False) -> AdapterDescriptor:
+        return AdapterDescriptor(
+            name=self.name,
+            kind=self.kind,
+            category=self.category,
+            validation_mode=self.validation_mode,
+            binary_names=list(self.binary_names),
+            required_binaries=list(self.required_binaries or self.binary_names),
+            supported_workflows=list(self.supported_workflows),
+            artifact_types=list(self.artifact_types),
+            available=self.is_available(),
+            enabled=enabled,
+            version=self.version(),
+        )
+
+    def run(self, run_id: str, project_root: Path, files: list[str], artifacts_dir: Path, extra_args: list[str] | None = None) -> AdapterExecution:
+        command = self.build_command(project_root, files, extra_args)
+        if not files:
+            raise AdapterExecutionError(f"{self.name} requires at least one input file")
+        if not self.is_available():
+            binaries = ", ".join(self.binary_names) or self.name
+            raise AdapterExecutionError(f"{self.name} is not available on PATH; expected one of: {binaries}")
+        started_at = utc_now()
+        try:
+            process = subprocess.run(command, cwd=project_root, capture_output=True, text=True, check=False)
+        except OSError as exc:
+            raise AdapterExecutionError(f"failed to execute {self.name}: {exc}") from exc
+        finished_at = utc_now()
+        ensure_directory(artifacts_dir)
+        log_path = artifacts_dir / f"{run_id}.log"
+        combined = process.stdout + process.stderr
+        log_path.write_text(combined, encoding="utf-8")
+        observations = self.parse_output(run_id, combined)
+        result = self.parse_result(project_root, files, process.stdout, process.stderr, combined)
+        artifacts = {"log_path": str(log_path)}
+        artifacts.update(self.collect_artifacts(project_root, files, artifacts_dir, run_id, process.stdout, process.stderr, combined))
+        summary = f"{self.name} exited with code {process.returncode}"
+        normalized_status = str(result.get("status", "")).strip()
+        if normalized_status:
+            summary = f"{summary}; status: {normalized_status}"
+        if observations:
+            summary = f"{summary}; first observation: {observations[0].signature}"
+        return AdapterExecution(
+            command=command,
+            cwd=str(project_root),
+            exit_code=process.returncode,
+            stdout=process.stdout,
+            stderr=process.stderr,
+            log_path=str(log_path),
+            started_at=started_at,
+            finished_at=finished_at,
+            observations=observations,
+            summary=summary,
+            artifacts=artifacts,
+            result=result,
+        )
+
+    @property
+    def tool_reference(self) -> ToolReference:
+        return ToolReference(kind=self.kind, name=self.name, version=self.version())

telchines/adapters/open_tools.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from telchines.adapters.base import AdapterExecution, ToolAdapter
+from telchines.errors import AdapterExecutionError
+from telchines.utils import ensure_directory, utc_now
+
+
+class VerilatorAdapter(ToolAdapter):
+    name = "verilator"
+    kind = "simulator"
+    category = "simulation"
+    binary_names = ("verilator",)
+    supported_workflows = ("repair_validation",)
+    artifact_types = ("log", "stdout", "stderr")
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        return ["verilator", "--lint-only", *(extra_args or []), *files]
+
+
+class IcarusAdapter(ToolAdapter):
+    name = "iverilog"
+    kind = "simulator"
+    category = "simulation"
+    validation_mode = "compile_and_run"
+    binary_names = ("iverilog", "vvp")
+    required_binaries = ("iverilog", "vvp")
+    supported_workflows = ("repair_validation",)
+    artifact_types = ("log", "stdout", "stderr", "executable")
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        return ["iverilog", "-g2012", *(extra_args or []), *files]
+
+    def run(self, run_id: str, project_root: Path, files: list[str], artifacts_dir: Path, extra_args: list[str] | None = None) -> AdapterExecution:
+        if not files:
+            raise AdapterExecutionError(f"{self.name} requires at least one input file")
+        if not self.is_available():
+            binaries = ", ".join(self.required_binaries or self.binary_names) or self.name
+            raise AdapterExecutionError(f"{self.name} is not available on PATH; expected: {binaries}")
+
+        ensure_directory(artifacts_dir)
+        executable_path = artifacts_dir / f"{run_id}.out"
+        compile_command = ["iverilog", "-g2012", "-o", str(executable_path), *(extra_args or []), *files]
+        compile_started_at = utc_now()
+        try:
+            compile_process = subprocess.run(compile_command, cwd=project_root, capture_output=True, text=True, check=False)
+        except OSError as exc:
+            raise AdapterExecutionError(f"failed to execute {self.name} compile step: {exc}") from exc
+
+        run_command = ["vvp", str(executable_path)]
+        run_stdout = ""
+        run_stderr = ""
+        run_exit_code: int | None = None
+        if compile_process.returncode == 0:
+            try:
+                run_process = subprocess.run(run_command, cwd=project_root, capture_output=True, text=True, check=False)
+            except OSError as exc:
+                raise AdapterExecutionError(f"failed to execute {self.name} run step: {exc}") from exc
+            run_stdout = run_process.stdout
+            run_stderr = run_process.stderr
+            run_exit_code = run_process.returncode
+
+        finished_at = utc_now()
+        combined = compile_process.stdout + compile_process.stderr + run_stdout + run_stderr
+        log_path = artifacts_dir / f"{run_id}.log"
+        log_path.write_text(combined, encoding="utf-8")
+        observations = self.parse_output(run_id, combined)
+        overall_exit_code = compile_process.returncode if compile_process.returncode != 0 else (run_exit_code or 0)
+        result = {
+            "status": "passed" if overall_exit_code == 0 else "failed",
+            "validation_mode": self.validation_mode,
+            "compile_command": compile_command,
+            "run_command": run_command if compile_process.returncode == 0 else [],
+            "compile_exit_code": compile_process.returncode,
+            "run_exit_code": run_exit_code,
+            "artifact_path": str(executable_path),
+        }
+        summary = f"{self.name} compile+run exited with code {overall_exit_code}"
+        if observations:
+            summary = f"{summary}; first observation: {observations[0].signature}"
+        return AdapterExecution(
+            command=compile_command,
+            cwd=str(project_root),
+            exit_code=overall_exit_code,
+            stdout=compile_process.stdout + run_stdout,
+            stderr=compile_process.stderr + run_stderr,
+            log_path=str(log_path),
+            started_at=compile_started_at,
+            finished_at=finished_at,
+            observations=observations,
+            summary=summary,
+            artifacts={"log_path": str(log_path), "compiled_executable": str(executable_path)},
+            result=result,
+        )
+
+
+class SlangAdapter(ToolAdapter):
+    name = "slang"
+    kind = "simulator"
+    category = "simulation"
+    binary_names = ("slang",)
+    supported_workflows = ("repair_validation", "generation_validation")
+    artifact_types = ("log", "stdout", "stderr")
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        return ["slang", "--lint-only", *(extra_args or []), *files]
+
+
+class VeribleAdapter(ToolAdapter):
+    name = "verible"
+    kind = "linter"
+    category = "lint"
+    binary_names = ("verible-verilog-lint",)
+    supported_workflows = ("repair_validation",)
+    artifact_types = ("log", "stdout", "stderr")
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        return ["verible-verilog-lint", *(extra_args or []), *files]
+
+
+class SymbiYosysAdapter(ToolAdapter):
+    name = "symbiyosys"
+    kind = "formal"
+    category = "formal"
+    binary_names = ("sby",)
+    supported_workflows = ("formal_validation",)
+    artifact_types = ("log", "report", "counterexample")
+
+    def build_command(self, project_root: Path, files: list[str], extra_args: list[str] | None = None) -> list[str]:
+        return ["sby", *(extra_args or []), *files]
+
+    def parse_result(self, project_root: Path, files: list[str], stdout: str, stderr: str, combined: str) -> dict[str, Any]:
+        return _parse_symbiyosys_result(project_root, combined)
+
+
+def _parse_symbiyosys_result(project_root: Path, combined: str) -> dict[str, Any]:
+    lowered = combined.lower()
+    status = "unknown"
+    if re.search(r"\b(status|summary)\s*:\s*passed\b", lowered):
+        status = "passed"
+    elif re.search(r"\b(status|summary)\s*:\s*failed\b", lowered):
+        status = "failed"
+    elif "assert failed" in lowered or "counterexample" in lowered:
+        status = "failed"
+
+    property_ids = sorted(
+        {
+            match.group("name")
+            for match in re.finditer(
+                r"(?P<name>[A-Za-z_][A-Za-z0-9_$]*)\s+(?:proved|failed|covered|unreached)",
+                combined,
+                flags=re.IGNORECASE,
+            )
+        }
+    )
+    referenced_artifacts = _existing_artifacts(project_root, combined)
+    counterexample_paths = [path for path in referenced_artifacts if path.endswith((".vcd", ".fst"))]
+    report_paths = [path for path in referenced_artifacts if path.endswith((".json", ".txt", ".log"))]
+    return {
+        "status": status,
+        "property_ids": property_ids,
+        "counterexample_paths": counterexample_paths,
+        "report_paths": report_paths,
+        "referenced_artifacts": referenced_artifacts,
+    }
+
+
+def _existing_artifacts(project_root: Path, combined: str) -> list[str]:
+    candidates = re.findall(r"([A-Za-z0-9_./\\\\-]+\.(?:vcd|fst|json|txt|log))", combined)
+    artifacts: list[str] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        path = Path(candidate)
+        resolved = path if path.is_absolute() else (project_root / path)
+        try:
+            normalized = str(resolved.resolve().relative_to(project_root.resolve())).replace("\\", "/")
+        except ValueError:
+            normalized = str(resolved.resolve()).replace("\\", "/")
+        if not resolved.exists() or normalized in seen:
+            continue
+        seen.add(normalized)
+        artifacts.append(normalized)
+    return artifacts

telchines/adapters/parsing.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from telchines.models import Observation
+from telchines.utils import stable_id
+
+GENERIC_PATTERNS = [
+    re.compile(r"ERROR:\s+(?P<file>.+?):(?P<line>\d+):\s+(?P<message>.+)"),
+    re.compile(r"(?P<file>[^:\n]+):(?P<line>\d+):\s*(?P<severity>error|warning):\s*(?P<message>.+)", re.IGNORECASE),
+]
+
+
+def normalize_signature(message: str) -> str:
+    text = message.lower()
+    if "semicolon" in text:
+        return "SV_PARSE_EXPECTED_SEMICOLON"
+    if "endmodule" in text:
+        return "SV_EXPECTED_ENDMODULE"
+    if ("missing end" in text) or ("expecting 'end'" in text) or ("expected end before" in text):
+        return "SV_EXPECTED_END"
+    if "syntax error" in text:
+        return "SV_GENERIC_SYNTAX_ERROR"
+    if "undeclared" in text or "unknown identifier" in text:
+        return "SV_UNKNOWN_IDENTIFIER"
+    if "cannot open" in text or "no such file" in text:
+        return "FILE_NOT_FOUND"
+    if "timeout" in text:
+        return "SIM_TIMEOUT"
+    if "assert" in text and "fail" in text:
+        return "ASSERTION_FAILURE"
+    compact = re.sub(r"[^a-z0-9]+", "_", text.upper()).strip("_")
+    return compact[:64] or "UNKNOWN_TOOL_ERROR"
+
+
+def parse_common_output(run_id: str, text: str, default_type: str = "tool_error") -> list[Observation]:
+    observations: list[Observation] = []
+    for line_text in text.splitlines():
+        for pattern in GENERIC_PATTERNS:
+            match = pattern.search(line_text)
+            if not match:
+                continue
+            message = match.group("message").strip()
+            observations.append(
+                Observation(
+                    observation_id=stable_id("obs", run_id, line_text),
+                    run_id=run_id,
+                    type=default_type,
+                    signature=normalize_signature(message),
+                    file=str(Path(match.group("file"))),
+                    line=int(match.group("line")),
+                    message=message,
+                    severity=match.groupdict().get("severity", "error").lower(),
+                )
+            )
+            break
+    return observations

telchines/adapters/registry.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from telchines.adapters.base import ToolAdapter
+from telchines.adapters.open_tools import IcarusAdapter, SlangAdapter, SymbiYosysAdapter, VeribleAdapter, VerilatorAdapter
+
+
+class AdapterRegistry:
+    def __init__(self) -> None:
+        self._adapters: dict[str, ToolAdapter] = {
+            "verilator": VerilatorAdapter(),
+            "iverilog": IcarusAdapter(),
+            "slang": SlangAdapter(),
+            "verible": VeribleAdapter(),
+            "symbiyosys": SymbiYosysAdapter(),
+        }
+
+    def get(self, name: str) -> ToolAdapter:
+        try:
+            return self._adapters[name]
+        except KeyError as exc:
+            raise KeyError(f"unknown adapter: {name}") from exc
+
+    def list(self, *, category: str | None = None) -> list[ToolAdapter]:
+        adapters = list(self._adapters.values())
+        if category is not None:
+            adapters = [adapter for adapter in adapters if adapter.category == category or adapter.kind == category]
+        return sorted(adapters, key=lambda adapter: adapter.name)