oc_chat.testing.static_scan Namespace Reference

Functions
bool	_is_fixture_decorated (ast.AST node)
list[tuple[int, int]]	_fixture_spans (ast.Module tree)
bool	_in_spans (int lineno, list[tuple[int, int]] spans)
bool	_is_os_environ (ast.AST node)
bool	_is_string_literal (ast.AST node)
list[dict]	_scan_tree (ast.Module tree, str file_str)
list[dict]	scan_files (Iterable[Path|str] files)

Variables
tuple	_WRITE_MODES = ("w", "a", "x")

Detailed Description

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)

Function Documentation

_fixture_spans()

list[tuple[int, int]] oc_chat.testing.static_scan._fixture_spans ( ast.Module tree )

protected

Line spans of every fixture-decorated function (approved
containers).

Definition at line 74 of file static_scan.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_in_spans()

bool oc_chat.testing.static_scan._in_spans ( int lineno, list[tuple[int, int]] spans )

protected

Definition at line 85 of file static_scan.py.

Here is the caller graph for this function:

_is_fixture_decorated()

bool oc_chat.testing.static_scan._is_fixture_decorated ( ast.AST node )

protected

True when *node* is a function decorated with pytest.fixture.

Definition at line 61 of file static_scan.py.

Here is the caller graph for this function:

_is_os_environ()

bool oc_chat.testing.static_scan._is_os_environ ( ast.AST node )

protected

Definition at line 89 of file static_scan.py.

Here is the caller graph for this function:

_is_string_literal()

bool oc_chat.testing.static_scan._is_string_literal ( ast.AST node )

protected

Definition at line 98 of file static_scan.py.

Here is the caller graph for this function:

_scan_tree()

list[dict] oc_chat.testing.static_scan._scan_tree ( ast.Module tree, str file_str )

protected

Definition at line 102 of file static_scan.py.

Here is the call graph for this function:

Here is the caller graph for this function:

scan_files()

list[dict] oc_chat.testing.static_scan.scan_files

(

Iterable[Path | str]

files

)

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.

Definition at line 205 of file static_scan.py.

Here is the call graph for this function:

Variable Documentation

_WRITE_MODES

tuple oc_chat.testing.static_scan._WRITE_MODES = ("w", "a", "x")

protected

Definition at line 58 of file static_scan.py.