package_walk.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/testing/package_walk.py
 
"""
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)
"""
from __future__ import annotations
 
import configparser
from dataclasses import dataclass, field
import fnmatch
import os
from pathlib import Path
import tomllib
 
from oc_diagnostics import _dbg
 
from oc_chat.testing.report import make_error
 
_WALK_LEVELS = 4  # cwd plus up to four ancestors (ADR-T-12)
 
_CONFIG_NAMES = ("pyproject.toml", "pytest.ini")
_BOUNDARY_NAMES = ("pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg")
_SKIP_DIR_NAMES = {"__pycache__", "node_modules"}
 
_CWD_RESOLUTION_MESSAGE = (
    "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."
)
 
 
@dataclass
class WalkResult:
    """The resolved single-package fallback discovery."""
 
    root: Path
    config_file: Path
    package_id: str
    testpaths: list[str] = field(default_factory=list)
    roots: list[Path] = field(default_factory=list)
    python_files: str = "test_*.py"
    profile_pin: str | None = None
 
 
def _read_pyproject(root: Path) -> dict:
    """Parse ``pyproject.toml`` at *root*; empty dict on absence/error."""
    func = "_read_pyproject"
    path = root / "pyproject.toml"
    if not path.is_file():
        return {}
    try:
        with path.open("rb") as fh:
            return tomllib.load(fh)
    except (OSError, tomllib.TOMLDecodeError) as exc:
        _dbg("OC_TESTING", func, f"unreadable pyproject: {exc}", 2)
        return {}
 
 
def _read_pytest_ini(root: Path) -> tuple[list[str], str | None]:
    """Return (testpaths, python_files) declared in ``pytest.ini``."""
    func = "_read_pytest_ini"
    path = root / "pytest.ini"
    if not path.is_file():
        return [], None
    parser = configparser.ConfigParser()
    try:
        parser.read(path, encoding="utf-8")
    except (OSError, configparser.Error) as exc:
        _dbg("OC_TESTING", func, f"unreadable pytest.ini: {exc}", 2)
        return [], None
    if not parser.has_section("pytest"):
        return [], None
    testpaths = parser.get("pytest", "testpaths", fallback="").split()
    python_files = parser.get("pytest", "python_files", fallback=None)
    return testpaths, python_files
 
 
def walk_for_package(cwd: Path) -> tuple[WalkResult | None, dict | None]:
    """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.
    """
    func = "walk_for_package"
    current = Path(cwd).resolve()
    candidates = [current, *current.parents[:_WALK_LEVELS]]
    root: Path | None = None
    config_file: Path | None = None
    for candidate in candidates:
        for name in _CONFIG_NAMES:
            if (candidate / name).is_file():
                root = candidate
                config_file = candidate / name
                break
        if root is not None:
            break
    if root is None or config_file is None:
        _dbg("OC_TESTING", func, f"resolution failed from {cwd}", 2)
        return None, make_error(
            "configuration", "CWD_RESOLUTION_FAILED", "fatal",
            _CWD_RESOLUTION_MESSAGE,
        )
 
    testpaths, python_files = _read_pytest_ini(root)
    pyproject = _read_pyproject(root)
    if not testpaths:
        ini_options = pyproject.get("tool", {}).get("pytest", {}).get(
            "ini_options", {})
        declared = ini_options.get("testpaths", [])
        if isinstance(declared, str):
            declared = declared.split()
        testpaths = [str(p) for p in declared]
        if python_files is None:
            pf = ini_options.get("python_files")
            if isinstance(pf, list):
                python_files = " ".join(pf)
            elif isinstance(pf, str):
                python_files = pf
 
    oct_test = pyproject.get("tool", {}).get("oct", {}).get("test", {})
    package_id = str(oct_test.get("package_id") or root.name)
    profile_pin = oct_test.get("profile")
 
    roots = [root / p for p in testpaths] if testpaths else [root]
    result = WalkResult(
        root=root,
        config_file=config_file,
        package_id=package_id,
        testpaths=testpaths,
        roots=roots,
        python_files=python_files or "test_*.py",
        profile_pin=str(profile_pin) if profile_pin else None,
    )
    _dbg("OC_TESTING", func,
         f"root={root} id={package_id} roots={len(roots)}", 3)
    return result, None
 
 
def _matches_any(name: str, patterns: list[str]) -> bool:
    return any(fnmatch.fnmatch(name, pat) for pat in patterns)
 
 
def scan_undeclared_roots(
    root: Path,
    declared: list[Path],
    python_files: str = "test_*.py",
) -> list[Path]:
    """§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.
    """
    func = "scan_undeclared_roots"
    root = Path(root).resolve()
    declared_resolved = [Path(d).resolve() for d in declared]
    patterns = python_files.split()
    findings: set[Path] = set()
 
    def _under(path: Path, ancestor: Path) -> bool:
        return path == ancestor or ancestor in path.parents
 
    for dirpath, dirnames, filenames in os.walk(root):
        current = Path(dirpath)
        keep: list[str] = []
        for name in sorted(dirnames):
            child = current / name
            if name.startswith(".") or name in _SKIP_DIR_NAMES:
                continue
            if child != root and any(
                (child / marker).is_file() for marker in _BOUNDARY_NAMES
            ) and not any(_under(d, child) for d in declared_resolved):
                _dbg("OC_TESTING", func, f"boundary pruned: {child}", 4)
                continue
            keep.append(name)
        dirnames[:] = keep
 
        if any(_under(current, d) for d in declared_resolved):
            continue
        if any(_matches_any(f, patterns) for f in filenames):
            findings.add(current)
 
    result = sorted(findings)
    _dbg("OC_TESTING", func, f"{len(result)} undeclared root(s)", 3)
    return result
 
 
_dbg("OC_TESTING", "module", "loaded", 4)
 
__all__ = ["WalkResult", "walk_for_package", "scan_undeclared_roots"]