threadcheck 0.0.1.1__py3-none-win_amd64.whl

threadcheck/dynamic/tracker.py

@@ -0,0 +1,177 @@
+import threading
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+
+from .clock import VectorClock
+from .._tid import current_tid as _current_tid
+
+
+@dataclass
+class AccessRecord:
+    var_name: str
+    operation: str
+    thread_id: int
+    clock: VectorClock = field(default_factory=VectorClock)
+    location: tuple = ("", 0)
+
+
+class ThreadCheckTracker:
+    _lock = threading.Lock()
+    _access_log: dict[str, list[AccessRecord]] = defaultdict(list)
+    _thread_clocks: dict[int, VectorClock] = {}
+    _lock_clocks: dict[str, VectorClock] = {}
+    _active = False
+
+    @classmethod
+    def start(cls):
+        cls._active = True
+
+    @classmethod
+    def stop(cls):
+        cls._active = False
+
+    @classmethod
+    def _get_clock(cls) -> tuple[VectorClock, int]:
+        tid = _current_tid()
+        if tid not in cls._thread_clocks:
+            with cls._lock:
+                if tid not in cls._thread_clocks:
+                    cls._thread_clocks[tid] = VectorClock()
+        return cls._thread_clocks[tid], tid
+
+    @classmethod
+    def write_before(cls, var_name: str, file: str = "", line: int = 0):
+        if not cls._active:
+            return
+        clock, tid = cls._get_clock()
+        clock.tick(tid)
+        record = AccessRecord(
+            var_name=var_name,
+            operation="write",
+            thread_id=tid,
+            clock=clock.copy(),
+            location=(file, line),
+        )
+        with cls._lock:
+            cls._access_log[var_name].append(record)
+
+    @classmethod
+    def read_before(cls, var_name: str, file: str = "", line: int = 0):
+        if not cls._active:
+            return
+        clock, tid = cls._get_clock()
+        clock.tick(tid)
+        record = AccessRecord(
+            var_name=var_name,
+            operation="read",
+            thread_id=tid,
+            clock=clock.copy(),
+            location=(file, line),
+        )
+        with cls._lock:
+            cls._access_log[var_name].append(record)
+
+    @classmethod
+    def lock_acquire(cls, lock_name: str, file: str = "", line: int = 0):
+        if not cls._active:
+            return
+        clock, tid = cls._get_clock()
+        with cls._lock:
+            if lock_name in cls._lock_clocks:
+                clock.merge(cls._lock_clocks[lock_name])
+        clock.tick(tid)
+
+    @classmethod
+    def lock_release(cls, lock_name: str, file: str = "", line: int = 0):
+        if not cls._active:
+            return
+        clock, tid = cls._get_clock()
+        with cls._lock:
+            cls._lock_clocks[lock_name] = clock.copy()
+
+    @classmethod
+    def reset(cls):
+        with cls._lock:
+            cls._access_log.clear()
+            cls._thread_clocks.clear()
+            cls._lock_clocks.clear()
+        cls._active = False
+
+    @classmethod
+    def reset_logs(cls):
+        with cls._lock:
+            cls._access_log.clear()
+            cls._thread_clocks.clear()
+            cls._lock_clocks.clear()
+
+    @classmethod
+    def _race_key(cls, r1: AccessRecord, r2: AccessRecord) -> tuple:
+        tid1, tid2 = sorted([r1.thread_id, r2.thread_id])
+        loc1, loc2 = sorted([r1.location, r2.location])
+        return (r1.var_name, tid1, tid2, loc1, loc2)
+
+    @classmethod
+    def detect_races(cls) -> list[tuple[str, AccessRecord, AccessRecord]]:
+        raw: list[tuple[str, AccessRecord, AccessRecord]] = []
+        with cls._lock:
+            for var_name, records in cls._access_log.items():
+                for i, r1 in enumerate(records):
+                    for r2 in records[i + 1 :]:
+                        if r1.thread_id != r2.thread_id:
+                            if r1.operation == "write" or r2.operation == "write":
+                                if r1.clock.conflicts_with(r2.clock):
+                                    raw.append((var_name, r1, r2))
+
+        seen: set[tuple] = set()
+        races: list[tuple[str, AccessRecord, AccessRecord]] = []
+        for entry in raw:
+            _, r1, r2 = entry
+            key = cls._race_key(r1, r2)
+            if key not in seen:
+                seen.add(key)
+                races.append(entry)
+        return races
+
+    @classmethod
+    def format_races(cls) -> str:
+        races = cls.detect_races()
+        if not races:
+            return "No data races detected"
+
+        overlap = Counter()
+        with cls._lock:
+            for var_name, records in cls._access_log.items():
+                for i, r1 in enumerate(records):
+                    for r2 in records[i + 1 :]:
+                        if r1.thread_id != r2.thread_id:
+                            if r1.operation == "write" or r2.operation == "write":
+                                if r1.clock.conflicts_with(r2.clock):
+                                    key = cls._race_key(r1, r2)
+                                    overlap[key] += 1
+
+        lines = ["Data races detected:", ""]
+        for var_name, r1, r2 in races:
+            f1, l1 = r1.location
+            f2, l2 = r2.location
+            key = cls._race_key(r1, r2)
+            count = overlap.get(key, 0)
+            lines.append(f"  [!] `{var_name}`")
+            lines.append(
+                f"      Thread-{r1.thread_id} ({r1.operation})"
+                f" at {f1}:{l1}"
+            )
+            lines.append(
+                f"      Thread-{r2.thread_id} ({r2.operation})"
+                f" at {f2}:{l2}"
+            )
+            if count > 1:
+                lines.append(f"      ({count} overlapping accesses)")
+            lines.append("")
+
+        total_unique = len(races)
+        total_overlap = sum(overlap.values())
+        lines.append(
+            f"Summary: {total_unique} unique race pair(s), "
+            f"{total_overlap} total overlapping access(es)"
+        )
+        return "\n".join(lines)

threadcheck/dynamic/transform.py

@@ -0,0 +1,192 @@
+import ast
+
+
+_LOCK_NAMES = frozenset({"Lock", "RLock", "Semaphore", "BoundedSemaphore"})
+
+
+_TRACKER_IMPORT = ast.parse(
+    "from threadcheck.dynamic.tracker import ThreadCheckTracker as _threadcheck_tracker"
+).body[0]
+
+
+class TrackInjector:
+    def __init__(self, filename: str = "<unknown>"):
+        self.filename = filename
+
+    def transform(self, tree: ast.Module) -> ast.Module:
+        tree.body.insert(0, _TRACKER_IMPORT)
+        scopes = {}
+        self._collect_scopes(tree, scopes)
+        self._inject(tree, scopes)
+        return tree
+
+    def _collect_scopes(self, node, scopes):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            func_id = id(node)
+            info = {"globals": set(), "nonlocals": set()}
+            for child in ast.walk(node):
+                if isinstance(child, ast.Global):
+                    info["globals"].update(child.names)
+                elif isinstance(child, ast.Nonlocal):
+                    info["nonlocals"].update(child.names)
+            scopes[func_id] = info
+            for child in ast.iter_child_nodes(node):
+                self._collect_scopes(child, scopes)
+        else:
+            for child in ast.iter_child_nodes(node):
+                self._collect_scopes(child, scopes)
+
+    def _inject(self, node, scopes, func_id=None):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            func_id = id(node)
+
+        for field in ("body", "orelse", "finalbody"):
+            old = getattr(node, field, None)
+            if isinstance(old, list):
+                setattr(node, field, self._transform_list(old, scopes, func_id))
+
+        for handler in getattr(node, "handlers", []):
+            handler.body = self._transform_list(handler.body, scopes, func_id)
+
+        for child in ast.iter_child_nodes(node):
+            self._inject(child, scopes, func_id)
+
+    def _transform_list(self, stmts, scopes, func_id):
+        if func_id is None or func_id not in scopes:
+            return stmts
+
+        info = scopes[func_id]
+        shared = info["globals"] | info["nonlocals"]
+
+        new: list[ast.stmt] = []
+        for stmt in stmts:
+            if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                new.append(stmt)
+                continue
+
+            if isinstance(stmt, ast.Assign):
+                targets = [
+                    t
+                    for t in stmt.targets
+                    if isinstance(t, ast.Name) and t.id in shared
+                ]
+                for t in targets:
+                    new.append(_make_write_before(t.id, self.filename, stmt.lineno))
+                new.append(stmt)
+
+            elif isinstance(stmt, ast.AugAssign):
+                if isinstance(stmt.target, ast.Name) and stmt.target.id in shared:
+                    new.append(
+                        _make_write_before(
+                            stmt.target.id, self.filename, stmt.lineno
+                        )
+                    )
+                new.append(stmt)
+
+            elif isinstance(stmt, ast.Delete):
+                targets = [
+                    t
+                    for t in stmt.targets
+                    if isinstance(t, ast.Name) and t.id in shared
+                ]
+                for t in targets:
+                    new.append(
+                        _make_write_before(t.id, self.filename, stmt.lineno)
+                    )
+                new.append(stmt)
+
+            elif isinstance(stmt, ast.With):
+                lock_name = _resolve_lock_name(stmt)
+                new.append(stmt)
+                if lock_name:
+                    stmt.body.insert(
+                        0,
+                        _make_lock_acquire(lock_name, self.filename, stmt.lineno),
+                    )
+                    stmt.body.append(
+                        _make_lock_release(lock_name, self.filename, stmt.lineno),
+                    )
+            else:
+                new.append(stmt)
+
+        return new
+
+
+def _make_write_before(var_name: str, filename: str, lineno: int) -> ast.Expr:
+    return ast.Expr(
+        value=ast.Call(
+            func=ast.Attribute(
+                value=ast.Name(id="_threadcheck_tracker", ctx=ast.Load()),
+                attr="write_before",
+                ctx=ast.Load(),
+            ),
+            args=[
+                ast.Constant(value=var_name),
+                ast.Constant(value=filename),
+                ast.Constant(value=lineno),
+            ],
+            keywords=[],
+        ),
+    )
+
+
+def _make_lock_acquire(lock_name: str, filename: str, lineno: int) -> ast.Expr:
+    return ast.Expr(
+        value=ast.Call(
+            func=ast.Attribute(
+                value=ast.Name(id="_threadcheck_tracker", ctx=ast.Load()),
+                attr="lock_acquire",
+                ctx=ast.Load(),
+            ),
+            args=[
+                ast.Constant(value=lock_name),
+                ast.Constant(value=filename),
+                ast.Constant(value=lineno),
+            ],
+            keywords=[],
+        ),
+    )
+
+
+def _make_lock_release(lock_name: str, filename: str, lineno: int) -> ast.Expr:
+    return ast.Expr(
+        value=ast.Call(
+            func=ast.Attribute(
+                value=ast.Name(id="_threadcheck_tracker", ctx=ast.Load()),
+                attr="lock_release",
+                ctx=ast.Load(),
+            ),
+            args=[
+                ast.Constant(value=lock_name),
+                ast.Constant(value=filename),
+                ast.Constant(value=lineno),
+            ],
+            keywords=[],
+        ),
+    )
+
+
+def _resolve_lock_name(with_stmt: ast.With) -> str | None:
+    for item in with_stmt.items:
+        expr = item.context_expr
+        if isinstance(expr, ast.Name):
+            return expr.id
+        if isinstance(expr, ast.Call):
+            if isinstance(expr.func, ast.Name) and expr.func.id in _LOCK_NAMES:
+                return ast.unparse(expr)
+            if isinstance(expr.func, ast.Attribute) and expr.func.attr in _LOCK_NAMES:
+                return ast.unparse(expr)
+    return None
+
+
+def transform_source(source: str, filename: str = "<unknown>") -> str:
+    tree = ast.parse(source, filename=filename)
+    TrackInjector(filename=filename).transform(tree)
+    return ast.unparse(tree)
+
+
+def transform_and_compile(source: str, filename: str = "<unknown>") -> str:
+    tree = ast.parse(source, filename=filename)
+    TrackInjector(filename=filename).transform(tree)
+    ast.fix_missing_locations(tree)
+    return compile(tree, filename, "exec")

threadcheck/pytest_plugin.py

@@ -0,0 +1,60 @@
+import pytest
+
+from .dynamic.hook import install_hook, uninstall_hook
+from .dynamic.tracker import ThreadCheckTracker
+
+_hook_instance = None
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("threadcheck")
+    group.addoption(
+        "--threadcheck",
+        action="store_true",
+        default=False,
+        help="Run dynamic race detection via AST instrumentation",
+    )
+
+
+def pytest_configure(config):
+    global _hook_instance
+    if config.getoption("--threadcheck"):
+        _hook_instance = install_hook(include_paths=[config.rootpath])
+        ThreadCheckTracker.start()
+        import sys
+        print(f"[threadcheck] hook installed, rootpath={config.rootpath}", flush=True)
+        print(f"[threadcheck] include_paths={[str(p) for p in _hook_instance._include_paths]}", flush=True)
+
+
+def pytest_unconfigure(config):
+    global _hook_instance
+    if config.getoption("--threadcheck"):
+        ThreadCheckTracker.stop()
+        if _hook_instance is not None:
+            uninstall_hook(_hook_instance)
+            _hook_instance = None
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_call(item):
+    if item.config.getoption("--threadcheck"):
+        ThreadCheckTracker.reset_logs()
+    yield
+    if item.config.getoption("--threadcheck"):
+        races = ThreadCheckTracker.detect_races()
+        if races:
+            item._threadcheck_race_report = ThreadCheckTracker.format_races()
+        ThreadCheckTracker.reset_logs()
+
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    if call.when == "call" and not call.excinfo:
+        report = getattr(item, "_threadcheck_race_report", None)
+        if report:
+            from _pytest._code import ExceptionInfo
+            try:
+                raise pytest.fail.Exception(report)
+            except pytest.fail.Exception:
+                call.excinfo = ExceptionInfo.from_current()
+    yield

threadcheck/reporting/__init__.py

@@ -0,0 +1,10 @@
+from .formatter import format_report, format_dynamic_races, format_warnings_json, format_dynamic_json
+from .sarif import format_sarif
+
+__all__ = [
+    "format_report",
+    "format_dynamic_races",
+    "format_warnings_json",
+    "format_dynamic_json",
+    "format_sarif",
+]

threadcheck/reporting/formatter.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import Counter
+from typing import Any
+
+from ..static.models import RaceWarning, Severity, Confidence
+
+
+def _use_color() -> bool:
+    if not sys.stdout.isatty():
+        return False
+    term = os.environ.get("TERM", "")
+    if "dumb" in term.lower():
+        return False
+    return True
+
+
+_COLOR = _use_color()
+
+_STYLES: dict[str, str] = {}
+if _COLOR:
+    _STYLES["reset"] = "\033[0m"
+    _STYLES["bold"] = "\033[1m"
+    _STYLES["red"] = "\033[91m"
+    _STYLES["green"] = "\033[92m"
+    _STYLES["yellow"] = "\033[93m"
+    _STYLES["blue"] = "\033[94m"
+    _STYLES["magenta"] = "\033[95m"
+    _STYLES["cyan"] = "\033[96m"
+    _STYLES["dim"] = "\033[2m"
+
+
+def _s(name: str, text: str = "") -> str:
+    s = _STYLES.get(name, "")
+    r = _STYLES.get("reset", "")
+    return f"{s}{text}{r}"
+
+
+_SEVERITY_COLOR = {
+    Severity.ERROR: "red",
+    Severity.WARNING: "yellow",
+    Severity.INFO: "cyan",
+}
+
+_CONFIDENCE_TAG = {
+    Confidence.HIGH: "HIGH",
+    Confidence.MEDIUM: "MED",
+    Confidence.LOW: "LOW",
+}
+
+_SEVERITY_TAG = {
+    Severity.ERROR: "ERROR",
+    Severity.WARNING: "WARNING",
+    Severity.INFO: "INFO",
+}
+
+
+def format_report(warnings: list[RaceWarning]) -> str:
+    if not warnings:
+        return _s("green", "No data-race issues detected") if _COLOR else "No data-race issues detected"
+
+    lines: list[str] = []
+    for w in warnings:
+        sc = _SEVERITY_COLOR.get(w.severity, "")
+        lines.append(
+            f"  {_s(sc, _SEVERITY_TAG.get(w.severity, '?'))} "
+            f"{_s('bold', _CONFIDENCE_TAG.get(w.confidence, ''))} "
+            f"[{w.category.value}] {w.file}:{w.line}:{w.col}"
+        )
+        lines.append(f"       {w.message}")
+        if w.suggestion:
+            lines.append(f"       {_s('dim', 'suggestion:')} {w.suggestion}")
+        lines.append("")
+
+    lines.append(f"{_s('dim', '---')}")
+    total = len(warnings)
+    errors = sum(1 for w in warnings if w.severity == Severity.ERROR)
+    warns = sum(1 for w in warnings if w.severity == Severity.WARNING)
+    infos = sum(1 for w in warnings if w.severity == Severity.INFO)
+    lines.append(f"Total: {total} issue(s) ({errors} error(s), {warns} warning(s), {infos} info(s))")
+    return "\n".join(lines)
+
+
+def format_dynamic_races(
+    races: list[tuple[str, Any, Any]],
+    access_log: dict[str, list] | None = None,
+) -> str:
+    if not races:
+        return _s("green", "No data races detected") if _COLOR else "No data races detected"
+
+    overlap = Counter()
+    if access_log:
+        for var_name, records in access_log.items():
+            for i, r1 in enumerate(records):
+                for r2 in records[i + 1 :]:
+                    if r1.thread_id != r2.thread_id:
+                        if r1.operation == "write" or r2.operation == "write":
+                            if r1.clock.conflicts_with(r2.clock):
+                                key = _race_key(r1, r2)
+                                overlap[key] += 1
+
+    lines: list[str] = [
+        _s("red", _s("bold", "Data races detected:")) if _COLOR else "Data races detected:",
+        "",
+    ]
+
+    for var_name, r1, r2 in races:
+        f1, l1 = r1.location
+        f2, l2 = r2.location
+        key = _race_key(r1, r2)
+        count = overlap.get(key, 0)
+        marker = _s("red", " [!]") if _COLOR else " [!]"
+
+        lines.append(f"{marker} {_s('bold', f'`{var_name}`')}")
+        lines.append(
+            f"  {'├─' if count > 0 else '└─'} "
+            f"Thread-{r1.thread_id} ({_s('magenta', r1.operation)}) "
+            f"at {f1}:{l1}"
+        )
+        lines.append(
+            f"  {'├─' if count > 1 else '└─'} "
+            f"Thread-{r2.thread_id} ({_s('magenta', r2.operation)}) "
+            f"at {f2}:{l2}"
+        )
+        lines.append(
+            f"  └─ No happens-before relationship between accesses"
+        )
+        if count > 1:
+            lines.append(f"     ({count} overlapping accesses)")
+        lines.append("")
+
+    total_unique = len(races)
+    total_overlap = sum(overlap.values())
+    summary = f"Summary: {total_unique} unique race pair(s), {total_overlap} total overlapping access(es)"
+    lines.append(_s("dim", summary) if _COLOR else summary)
+    return "\n".join(lines)
+
+
+def _race_key(r1, r2) -> tuple:
+    tid1, tid2 = sorted([r1.thread_id, r2.thread_id])
+    loc1, loc2 = sorted([r1.location, r2.location])
+    return (r1.var_name, tid1, tid2, loc1, loc2)
+
+
+def format_warnings_json(warnings: list[RaceWarning]) -> str:
+    return json.dumps(
+        [w.to_dict() for w in warnings],
+        indent=2,
+        ensure_ascii=False,
+    )
+
+
+def format_dynamic_json(
+    races: list[tuple[str, Any, Any]],
+) -> str:
+    entries = []
+    for var_name, r1, r2 in races:
+        entries.append({
+            "var_name": var_name,
+            "thread_1": {
+                "id": r1.thread_id,
+                "operation": r1.operation,
+                "location": f"{r1.location[0]}:{r1.location[1]}",
+            },
+            "thread_2": {
+                "id": r2.thread_id,
+                "operation": r2.operation,
+                "location": f"{r2.location[0]}:{r2.location[1]}",
+            },
+        })
+    return json.dumps(entries, indent=2, ensure_ascii=False)