static_scan.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/testing/static_scan.py
 
"""
The §20.2 static AST guard for selected test files (Plan 184).
 
Purpose
-------
Implement the stand-in's static contract subset (spec-10 §10/§20.2):
raw ``os.chdir`` calls (rule ``cwd_chdir``) and the four raw
environment-mutation forms §6.4 names — subscript assignment, ``del``,
``os.environ.update(...)``, ``os.putenv(...)`` — (rule
``env_mutation``), both error severity; plus the advisory literal-path
owned-write pre-check (rule ``owned_writes_outside_tmp``).
 
Responsibilities
----------------
- ``scan_files`` — parse each selected test file and return §11-shaped
  violation entries (``nodeid`` is ``None`` for static findings; the
  line number is carried in the message).
- The approved-container exemption: calls inside a function decorated
  with ``@pytest.fixture`` (bare or called form) are exempt — the
  stand-in's reading of §6.1/§6.4 "approved fixtures"; v1.0 refines
  this with config-declared fixture inventories.
 
Diagnostics
-----------
Domain: OC_TESTING
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- The scan covers exactly the four §6.4-named env forms; other mapping
  mutators (``pop``, ``setdefault``, ``clear``) are v1.0 scope.
- String/docstring mentions never match (AST, not grep).
- Advisory findings never drive an exit code (§11: only error-severity
  entries produce exit 2).
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.testing.report (violation constructor)
"""
from __future__ import annotations
 
import ast
from collections.abc import Iterable
from pathlib import Path
 
from oc_diagnostics import _dbg
 
from oc_chat.testing.report import make_violation
 
_WRITE_MODES = ("w", "a", "x")
 
 
def _is_fixture_decorated(node: ast.AST) -> bool:
    """True when *node* is a function decorated with pytest.fixture."""
    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
        return False
    for decorator in node.decorator_list:
        target = decorator.func if isinstance(decorator, ast.Call) else decorator
        if isinstance(target, ast.Attribute) and target.attr == "fixture":
            return True
        if isinstance(target, ast.Name) and target.id == "fixture":
            return True
    return False
 
 
def _fixture_spans(tree: ast.Module) -> list[tuple[int, int]]:
    """Line spans of every fixture-decorated function (approved
    containers)."""
    spans: list[tuple[int, int]] = []
    for node in ast.walk(tree):
        if _is_fixture_decorated(node):
            end = getattr(node, "end_lineno", node.lineno)
            spans.append((node.lineno, end))
    return spans
 
 
def _in_spans(lineno: int, spans: list[tuple[int, int]]) -> bool:
    return any(start <= lineno <= end for start, end in spans)
 
 
def _is_os_environ(node: ast.AST) -> bool:
    return (
        isinstance(node, ast.Attribute)
        and node.attr == "environ"
        and isinstance(node.value, ast.Name)
        and node.value.id == "os"
    )
 
 
def _is_string_literal(node: ast.AST) -> bool:
    return isinstance(node, ast.Constant) and isinstance(node.value, str)
 
 
def _scan_tree(tree: ast.Module, file_str: str) -> list[dict]:
    func = "_scan_tree"
    spans = _fixture_spans(tree)
    findings: list[dict] = []
 
    def _error(rule: str, lineno: int, detail: str) -> None:
        findings.append(make_violation(
            rule, file_str, None, "error",
            f"{detail} (line {lineno}); use monkeypatch or an approved "
            "fixture (spec-10 section 6)",
        ))
 
    def _advisory(lineno: int, detail: str) -> None:
        findings.append(make_violation(
            "owned_writes_outside_tmp", file_str, None, "advisory",
            f"{detail} (line {lineno}); prefer tmp_path-derived targets "
            "(spec-10 section 6.2 advisory pre-check)",
        ))
 
    for node in ast.walk(tree):
        lineno = getattr(node, "lineno", None)
        if lineno is None or _in_spans(lineno, spans):
            continue
 
        if isinstance(node, ast.Call):
            callee = node.func
            # os.chdir(...)
            if (
                isinstance(callee, ast.Attribute)
                and callee.attr == "chdir"
                and isinstance(callee.value, ast.Name)
                and callee.value.id == "os"
            ):
                _error("cwd_chdir", lineno, "raw os.chdir call")
            # os.environ.update(...)
            elif (
                isinstance(callee, ast.Attribute)
                and callee.attr == "update"
                and _is_os_environ(callee.value)
            ):
                _error("env_mutation", lineno, "raw os.environ.update call")
            # os.putenv(...)
            elif (
                isinstance(callee, ast.Attribute)
                and callee.attr == "putenv"
                and isinstance(callee.value, ast.Name)
                and callee.value.id == "os"
            ):
                _error("env_mutation", lineno, "raw os.putenv call")
            # open("literal", "w"/"a"/"x")
            elif (
                isinstance(callee, ast.Name)
                and callee.id == "open"
                and node.args
                and _is_string_literal(node.args[0])
            ):
                mode = None
                if len(node.args) >= 2 and _is_string_literal(node.args[1]):
                    mode = node.args[1].value
                for kw in node.keywords:
                    if kw.arg == "mode" and _is_string_literal(kw.value):
                        mode = kw.value.value
                if mode and any(ch in mode for ch in _WRITE_MODES):
                    _advisory(lineno, "literal-path write via open()")
            # Path("literal").write_text(...) / .write_bytes(...)
            elif (
                isinstance(callee, ast.Attribute)
                and callee.attr in ("write_text", "write_bytes")
                and isinstance(callee.value, ast.Call)
                and isinstance(callee.value.func, ast.Name)
                and callee.value.func.id == "Path"
                and callee.value.args
                and _is_string_literal(callee.value.args[0])
            ):
                _advisory(lineno, "literal-path write via Path().write_*")
        elif isinstance(node, ast.Assign):
            for target in node.targets:
                if (
                    isinstance(target, ast.Subscript)
                    and _is_os_environ(target.value)
                ):
                    _error("env_mutation", lineno,
                           "raw os.environ[...] assignment")
        elif isinstance(node, ast.AugAssign):
            if (
                isinstance(node.target, ast.Subscript)
                and _is_os_environ(node.target.value)
            ):
                _error("env_mutation", lineno,
                       "raw os.environ[...] augmented assignment")
        elif isinstance(node, ast.Delete):
            for target in node.targets:
                if (
                    isinstance(target, ast.Subscript)
                    and _is_os_environ(target.value)
                ):
                    _error("env_mutation", lineno,
                           "raw del os.environ[...]")
 
    _dbg("OC_TESTING", func, f"{file_str}: {len(findings)} finding(s)", 4)
    return findings
 
 
def scan_files(files: Iterable[Path | str]) -> list[dict]:
    """Run the static guard over *files*; return §11 violation entries.
 
    Unparseable files are skipped here — pytest collection reports the
    syntax error itself as ``COLLECTION_ERROR`` (section 4 case 1), so
    the scan never double-reports it.
    """
    func = "scan_files"
    findings: list[dict] = []
    for entry in files:
        path = Path(entry)
        try:
            tree = ast.parse(path.read_text(encoding="utf-8"))
        except (OSError, SyntaxError) as exc:
            _dbg("OC_TESTING", func, f"skip unparseable {path}: {exc}", 2)
            continue
        findings.extend(_scan_tree(tree, str(path)))
    _dbg("OC_TESTING", func, f"total findings: {len(findings)}", 3)
    return findings
 
 
_dbg("OC_TESTING", "module", "loaded", 4)
 
__all__ = ["scan_files"]