threadcheck 0.0.1__py3-none-any.whl

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/formatter.py

@@ -0,0 +1,33 @@
+from ..static.models import RaceWarning, Severity, Confidence
+
+_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 "No data-race issues detected"
+
+    lines: list[str] = []
+
+    for w in warnings:
+        sev = _SEVERITY_TAG.get(w.severity, "[?]")
+        conf = _CONFIDENCE_TAG.get(w.confidence, "")
+        lines.append(
+            f"{sev} {conf} [{w.category.value}] {w.file}:{w.line}:{w.col}"
+        )
+        lines.append(f"       {w.message}")
+        if w.suggestion:
+            lines.append(f"       suggestion: {w.suggestion}")
+        lines.append("")
+
+    return "\n".join(lines)

threadcheck/reporting/sarif.py

@@ -0,0 +1,100 @@
+import json
+from pathlib import Path
+
+from ..static.models import RaceWarning, Severity, WarningCategory, Confidence
+from .._version import __version__
+
+_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"
+_TOOL_INFO_URI = "https://github.com/ChidcGithub/Threadcheck"
+
+_SEVERITY_TO_LEVEL = {
+    Severity.ERROR: "error",
+    Severity.WARNING: "warning",
+    Severity.INFO: "note",
+}
+
+_CATEGORY_LABELS = {
+    WarningCategory.UNSAFE_GLOBAL: ("Global variable modified without lock", "Detects modifications of `global` variables inside functions without lock protection."),
+    WarningCategory.UNSAFE_NONLOCAL: ("Nonlocal variable modified without lock", "Detects modifications of `nonlocal` variables inside nested functions without lock protection."),
+    WarningCategory.UNPROTECTED_ACCESS: ("Unprotected shared access", "Detects shared variable access without synchronization."),
+    WarningCategory.THREAD_USAGE: ("Thread creation detected", "Reports sites where `threading.Thread` objects are created."),
+    WarningCategory.SHARED_MUTABLE: ("Module-level mutable object modified", "Detects modification of module-level mutable objects (lists, dicts, sets) inside functions."),
+    WarningCategory.CLASS_ATTRIBUTE: ("Class attribute modified without lock", "Detects unsafe modification of instance attributes (`self.x`) without lock protection."),
+}
+
+
+def format_sarif(
+    warnings: list[RaceWarning],
+    tool_version: str = __version__,
+) -> str:
+    rules = _build_rules(warnings)
+    results = [_warning_to_result(w) for w in warnings]
+
+    doc = {
+        "$schema": _SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "threadcheck",
+                        "version": tool_version,
+                        "informationUri": _TOOL_INFO_URI,
+                        "rules": rules,
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+
+    return json.dumps(doc, indent=2, ensure_ascii=False)
+
+
+def _build_rules(warnings: list[RaceWarning]) -> list[dict]:
+    seen: set[str] = set()
+    rules: list[dict] = []
+    for w in warnings:
+        rid = w.category.value
+        if rid in seen:
+            continue
+        seen.add(rid)
+        label, desc = _CATEGORY_LABELS.get(
+            w.category, (rid.replace("_", " ").title(), "")
+        )
+        level = _SEVERITY_TO_LEVEL.get(w.severity, "warning")
+        rules.append(
+            {
+                "id": rid,
+                "shortDescription": {"text": label},
+                "fullDescription": {"text": desc},
+                "defaultConfiguration": {"level": level},
+                "properties": {
+                    "category": "Concurrency",
+                    "confidence": w.confidence.value,
+                },
+            }
+        )
+    return rules
+
+
+def _warning_to_result(w: RaceWarning) -> dict:
+    return {
+        "ruleId": w.category.value,
+        "level": _SEVERITY_TO_LEVEL.get(w.severity, "warning"),
+        "message": {"text": w.message},
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": w.file.resolve().as_uri(),
+                    },
+                    "region": {
+                        "startLine": w.line,
+                        "startColumn": w.col,
+                    },
+                }
+            }
+        ],
+        "properties": {},
+    }

threadcheck/reporting/types.py

@@ -0,0 +1,3 @@
+from ..static.models import Severity, WarningCategory
+
+__all__ = ["Severity", "WarningCategory"]

threadcheck/static/analyzer.py

@@ -0,0 +1,104 @@
+import ast
+from pathlib import Path
+
+from .models import RaceWarning
+from .lock_tracker import LockTracker
+from .visitors import (
+    GlobalVisitor,
+    NonlocalVisitor,
+    ThreadVisitor,
+    SharedMutableVisitor,
+    ClassAttributeVisitor,
+)
+
+_SKIP_DIRS = frozenset({
+    ".git", "__pycache__", ".venv", "venv", "env", ".env",
+    ".mypy_cache", ".pytest_cache", "node_modules", ".tox",
+    "dist", "build", ".eggs", "site-packages",
+})
+
+
+class AnalysisContext:
+    def __init__(self, filepath: Path, tree: ast.Module):
+        self.filepath = filepath
+        self._thread_targets: set[str] = set()
+        self._has_thread = False
+        self._find_thread_targets(tree)
+        self.lock_tracker = LockTracker()
+        self.lock_tracker.visit(tree)
+
+    def is_protected(self, line: int) -> bool:
+        return self.lock_tracker.is_protected_by_lock(line)
+
+    def is_thread_target(self, func_name: str) -> bool:
+        return func_name in self._thread_targets
+
+    def has_any_thread(self) -> bool:
+        return self._has_thread
+
+    def _find_thread_targets(self, tree):
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Attribute) and node.func.attr == "Thread":
+                    self._has_thread = True
+                    for kw in node.keywords:
+                        if kw.arg == "target":
+                            if isinstance(kw.value, ast.Name):
+                                self._thread_targets.add(kw.value.id)
+                            elif isinstance(kw.value, ast.Attribute):
+                                self._thread_targets.add(kw.value.attr)
+                attr_name = getattr(node.func, "attr", None)
+                if attr_name in ("submit", "map"):
+                    self._has_thread = True
+
+
+def analyze_file(filepath: Path) -> list[RaceWarning]:
+    try:
+        source = filepath.read_text(encoding="utf-8")
+    except Exception:
+        return []
+
+    try:
+        tree = ast.parse(source, filename=str(filepath))
+    except SyntaxError:
+        return []
+
+    context = AnalysisContext(filepath, tree)
+
+    all_warnings: list[RaceWarning] = []
+
+    for visitor_cls in (
+        GlobalVisitor,
+        NonlocalVisitor,
+        ThreadVisitor,
+        SharedMutableVisitor,
+        ClassAttributeVisitor,
+    ):
+        visitor = visitor_cls(filepath, context)
+        visitor.visit(tree)
+        all_warnings.extend(visitor.warnings)
+
+    return all_warnings
+
+
+def analyze_path(path: str) -> list[RaceWarning]:
+    p = Path(path).resolve()
+    all_warnings: list[RaceWarning] = []
+
+    if p.is_file():
+        if p.suffix == ".py":
+            all_warnings.extend(analyze_file(p))
+    elif p.is_dir():
+        for py_file in sorted(p.rglob("*.py")):
+            if _should_skip(py_file):
+                continue
+            all_warnings.extend(analyze_file(py_file))
+
+    return all_warnings
+
+
+def _should_skip(path: Path) -> bool:
+    for part in path.parts:
+        if part in _SKIP_DIRS or part.startswith("."):
+            return True
+    return False

threadcheck/static/lock_tracker.py

@@ -0,0 +1,42 @@
+import ast
+
+_LOCK_CLASSES = frozenset({"Lock", "RLock", "Semaphore", "BoundedSemaphore"})
+
+
+class LockTracker(ast.NodeVisitor):
+    def __init__(self):
+        self.protected_regions: list[ast.With] = []
+        self.lock_exprs: set[str] = set()
+
+    def visit_With(self, node):
+        for item in node.items:
+            expr_name = ast.unparse(item.context_expr)
+            if expr_name in self.lock_exprs or self._is_lock_creation(item.context_expr):
+                self.lock_exprs.add(expr_name)
+                self.protected_regions.append(node)
+        self.generic_visit(node)
+
+    def visit_Assign(self, node):
+        for target in node.targets:
+            if isinstance(node.value, ast.Call) and self._is_lock_creation(node.value):
+                self.lock_exprs.add(ast.unparse(target))
+        self.generic_visit(node)
+
+    def is_protected_by_lock(self, line: int) -> bool:
+        for region in self.protected_regions:
+            start = getattr(region, "lineno", 0)
+            end = getattr(region, "end_lineno", start)
+            if start <= line <= end:
+                return True
+        return False
+
+    @staticmethod
+    def _is_lock_creation(node) -> bool:
+        if not isinstance(node, ast.Call):
+            return False
+        func = node.func
+        if isinstance(func, ast.Name):
+            return func.id in _LOCK_CLASSES
+        if isinstance(func, ast.Attribute):
+            return func.attr in _LOCK_CLASSES
+        return False

threadcheck/static/models.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class Severity(Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class WarningCategory(Enum):
+    UNSAFE_GLOBAL = "unsafe_global"
+    UNSAFE_NONLOCAL = "unsafe_nonlocal"
+    UNPROTECTED_ACCESS = "unprotected_access"
+    THREAD_USAGE = "thread_usage"
+    SHARED_MUTABLE = "shared_mutable"
+    CLASS_ATTRIBUTE = "class_attribute"
+
+
+class Confidence(Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class RaceWarning:
+    file: Path
+    line: int
+    col: int
+    severity: Severity
+    category: WarningCategory
+    message: str
+    suggestion: str | None = None
+    confidence: Confidence = Confidence.MEDIUM
+
+    def to_dict(self) -> dict:
+        return {
+            "file": str(self.file),
+            "line": self.line,
+            "col": self.col,
+            "severity": self.severity.value,
+            "category": self.category.value,
+            "message": self.message,
+            "suggestion": self.suggestion,
+            "confidence": self.confidence.value,
+        }