oc_chat.testing.package_walk Namespace Reference

Classes
class	WalkResult

Functions
dict	_read_pyproject (Path root)
tuple[list[str], str|None]	_read_pytest_ini (Path root)
tuple[WalkResult|None, dict|None]	walk_for_package (Path cwd)
bool	_matches_any (str name, list[str] patterns)
list[Path]	scan_undeclared_roots (Path root, list[Path] declared, str python_files="test_*.py")

Variables
int	_WALK_LEVELS = 4
tuple	_CONFIG_NAMES = ("pyproject.toml", "pytest.ini")
tuple	_BOUNDARY_NAMES = ("pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg")
dict	_SKIP_DIR_NAMES = {"__pycache__", "node_modules"}
tuple	_CWD_RESOLUTION_MESSAGE

Detailed Description

Single-package fallback discovery + the undeclared-root scan (Plan 184).

Purpose
-------
Implement ADR-T-12 (walk upward from cwd for ``pyproject.toml`` or
``pytest.ini``, cwd plus up to four ancestors; basename package-id with
the ``[tool.oct.test].package_id`` override) and the spec-10 §10
undeclared-root scan that kills the A-18 testpaths trap: a directory
holding test files outside the effective roots is a finding — fatal in
strict, warning in smoke/full.

Responsibilities
----------------
- ``walk_for_package`` — discovery; testpaths from ``pytest.ini`` (or
  ``[tool.pytest.ini_options]``), package-root fallback when absent.
- ``scan_undeclared_roots`` — the §10 filesystem scan with the
  nested-package boundary rule: a directory carrying its own
  ``pytest.ini``/``pyproject.toml``/``tox.ini``/``setup.cfg`` is a
  DIFFERENT package and is skipped, unless a declared root lies within
  it (the live-tree shape: the product dir carries ``pyproject.toml``
  AND contains the declared roots).

Diagnostics
-----------
Domain: OC_TESTING
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Discovery is read-only; nothing is created or mutated.
- Hidden directories, ``__pycache__``, and ``node_modules`` are never
  scanned.
- The scan honours the package's ``python_files`` pattern (default
  ``test_*.py``).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.testing.report (error constructors)

Function Documentation

_matches_any()

bool oc_chat.testing.package_walk._matches_any ( str name, list[str] patterns )

protected

Definition at line 182 of file package_walk.py.

Here is the caller graph for this function:

_read_pyproject()

dict oc_chat.testing.package_walk._read_pyproject ( Path root )

protected

Parse ``pyproject.toml`` at *root*; empty dict on absence/error.

Definition at line 88 of file package_walk.py.

Here is the caller graph for this function:

_read_pytest_ini()

tuple[list[str], str | None] oc_chat.testing.package_walk._read_pytest_ini ( Path root )

protected

Return (testpaths, python_files) declared in ``pytest.ini``.

Definition at line 102 of file package_walk.py.

Here is the caller graph for this function:

scan_undeclared_roots()

list[Path] oc_chat.testing.package_walk.scan_undeclared_roots	(	Path	root,
		list[Path]	declared,
		str	python_files = "test_*.py" )

§10 scan: directories under *root* holding test files outside the
*declared* roots.

The nested-package boundary rule: a non-root directory carrying its
own package config is a different package and is pruned, unless a
declared root lies at-or-under it.

Definition at line 186 of file package_walk.py.

Here is the call graph for this function:

walk_for_package()

tuple[WalkResult | None, dict | None] oc_chat.testing.package_walk.walk_for_package

(

Path

cwd

)

ADR-T-12 discovery: walk upward from *cwd* for a package config.

Returns ``(result, None)`` or ``(None, error)`` where *error* is the
``CWD_RESOLUTION_FAILED`` entry with the pinned message.

Definition at line 121 of file package_walk.py.

Here is the call graph for this function:

Variable Documentation

_BOUNDARY_NAMES

tuple oc_chat.testing.package_walk._BOUNDARY_NAMES = ("pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg")

protected

Definition at line 65 of file package_walk.py.

_CONFIG_NAMES

tuple oc_chat.testing.package_walk._CONFIG_NAMES = ("pyproject.toml", "pytest.ini")

protected

Definition at line 64 of file package_walk.py.

_CWD_RESOLUTION_MESSAGE

tuple oc_chat.testing.package_walk._CWD_RESOLUTION_MESSAGE

protected

Initial value:

=  (
    "oct test: no pyproject.toml or pytest.ini found within 4 parent "
    "levels of cwd. Run from inside a workspace or package, or pass "
    "--package NAME to disambiguate."
)

Definition at line 68 of file package_walk.py.

_SKIP_DIR_NAMES

dict oc_chat.testing.package_walk._SKIP_DIR_NAMES = {"__pycache__", "node_modules"}

protected

Definition at line 66 of file package_walk.py.

_WALK_LEVELS

int oc_chat.testing.package_walk._WALK_LEVELS = 4

protected

Definition at line 62 of file package_walk.py.