discovery.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/testing/discovery.py
 
"""
Purpose
-------
The spec-10 §9 discovery-precedence layer for the ``oct test`` v1.0
seed (Plan 189): workspace / ``--package P`` / bare selection over the
workspace manifest, plus the ADR-T-12 single-package fallback walk
(cwd upward for ``pyproject.toml``/``pytest.ini``, four-parent-level
cap, basename inference with the ``[tool.oct.test].package_id``
cross-check override).
 
Responsibilities
----------------
- :func:`discover` - the §9 precedence table, row for row. Flags are
  plain keyword arguments (this is a LIBRARY: no CLI, no flag
  parsing, no ``sys.exit``); every exit-4 table branch raises
  :class:`oct.testing.errors.OctTestError` with its §12.4 code.
- :func:`walk_for_package` - the ADR-T-12 walk with the ADR's pinned
  diagnostic message, verbatim.
- OUT of scope (future slices): pytest collection and the §4
  collection-check routing (``COLLECTION_ERROR`` /
  ``NO_TESTS_COLLECTED``), runners, schedulers, reports.
 
Diagnostics
-----------
Domain: OCT-TESTING
Levels:
    L2: lifecycle (discovery start / resolution failures)
    L3: semantic details (resolved mode, selection, walk result)
    L4: deep tracing
 
Contracts
---------
- Discovery is READ-ONLY: nothing is created or mutated.
- Mutual exclusion (``workspace`` + ``package``) is checked before
  any filesystem access - a fully valid workspace does not rescue
  the call (§9 row 7, "Either").
- The ``--package`` fallback (no manifest found) does NOT walk: the
  package roots at cwd and ``P`` must equal the cwd basename (§9
  row 6); the ADR-T-12 walk belongs to the bare row only.
- A corrupt ``pyproject.toml`` at a discovered root degrades to
  basename inference - the file's existence marks the package root;
  only the optional override read is tolerant.
 
Dependencies
------------
- oct.core.workspace (read-only: find_workspace_root)
- oct.core.diagnostics (_dbg)
- oct.testing.errors (the §12.4 taxonomy as data)
- oct.testing.manifest (the §9 manifest test view)
"""
 
from __future__ import annotations
 
import tomllib
from dataclasses import dataclass, field
from pathlib import Path
 
from oct.core.diagnostics import _dbg
from oct.core.workspace import WORKSPACE_MANIFEST, find_workspace_root
from oct.testing.errors import (
    CWD_RESOLUTION_FAILED,
    OctTestError,
    PACKAGE_UNKNOWN,
    WORKSPACE_AND_PACKAGE_BOTH_PASSED,
    WORKSPACE_FILE_NOT_FOUND,
)
from oct.testing.manifest import (
    PackageTestConfig,
    TestManifest,
    load_test_manifest,
)
 
 
#: Workspace mode: selection comes from the manifest test blocks.
MODE_WORKSPACE: str = "workspace"
 
#: Single-package fallback mode (§9 rows 2 and 6).
MODE_SINGLE_PACKAGE: str = "single_package"
 
#: ADR-T-12 cap: cwd plus up to four parent levels.
WALK_LEVELS: int = 4
 
#: Config files the ADR-T-12 walk recognises, preference order -
#: ``pyproject.toml`` first, so the clause-5 ``package_id``
#: cross-check always reads the discovered file.
_CONFIG_FILE_NAMES: tuple[str, ...] = ("pyproject.toml", "pytest.ini")
 
#: The ADR-T-12 diagnostic message, pinned VERBATIM by the ADR
#: (message recut in spec v0.4, review B P3-01).
CWD_RESOLUTION_MESSAGE: str = (
    "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(frozen=True)
class SinglePackage:
    """The resolved single-package fallback target.
 
    Attributes
    ----------
    root
        Absolute package root: the config file's directory (ADR-T-12
        walk, §9 row 2) or cwd itself (``--package`` fallback, row 6).
    package_id
        Basename of *root*, unless the discovered ``pyproject.toml``
        carries a ``[tool.oct.test].package_id`` override (clause 5),
        or ``--package`` supplied the id (row 6).
    config_file
        The discovered config file; ``None`` in the ``--package``
        fallback, which performs no walk.
    """
 
    root: Path
    package_id: str
    config_file: Path | None = None
 
 
@dataclass(frozen=True)
class DiscoveryResult:
    """Outcome of the §9 discovery precedence.
 
    Attributes
    ----------
    mode
        :data:`MODE_WORKSPACE` or :data:`MODE_SINGLE_PACKAGE`.
    workspace_root
        Resolved workspace root (workspace mode only).
    manifest
        The parsed :class:`~oct.testing.manifest.TestManifest`
        (workspace mode only).
    selected
        The selected packages, manifest order: every test-enabled
        package, or exactly the ``--package`` target. Empty in
        single-package mode.
    single
        The :class:`SinglePackage` target (single-package mode only).
    """
 
    mode: str
    workspace_root: Path | None = None
    manifest: TestManifest | None = None
    selected: tuple[PackageTestConfig, ...] = field(default_factory=tuple)
    single: SinglePackage | None = None
 
 
def discover(
    cwd: Path,
    *,
    workspace: bool = False,
    package: str | None = None,
) -> DiscoveryResult:
    """Resolve the §9 discovery precedence from *cwd*.
 
    Parameters
    ----------
    cwd
        Directory the (future) invocation runs from; the upward
        manifest search and the ADR-T-12 walk both start here.
    workspace
        Library mirror of the ``--workspace`` flag.
    package
        Library mirror of the ``--package P`` flag.
 
    Returns
    -------
    :class:`DiscoveryResult`
 
    Raises
    ------
    OctTestError
        Every exit-4 branch of the §9 table:
        ``WORKSPACE_AND_PACKAGE_BOTH_PASSED`` (row 7, checked before
        any IO), ``WORKSPACE_FILE_NOT_FOUND`` (row 4),
        ``PACKAGE_UNKNOWN`` (rows 5 and 6),
        ``CWD_RESOLUTION_FAILED`` (row 2), and the manifest ``9101``/
        ``9102`` codes when a found workspace file is invalid
        (rows 1/3/5).
    """
    func = "discover"
    if workspace and package is not None:
        raise OctTestError(
            WORKSPACE_AND_PACKAGE_BOTH_PASSED,
            "--workspace and --package are mutually exclusive",
        )
 
    start = Path(cwd)
    _dbg(
        "OCT-TESTING", func,
        f"cwd={start} workspace={workspace} package={package!r}", 2,
    )
    workspace_root = find_workspace_root(start)
 
    if workspace:
        if workspace_root is None:
            raise OctTestError(
                WORKSPACE_FILE_NOT_FOUND,
                f"--workspace passed but no {WORKSPACE_MANIFEST} "
                f"exists in {start} or any parent",
            )
        return _workspace_result(workspace_root, None)
 
    if package is not None:
        if workspace_root is not None:
            return _workspace_result(workspace_root, package)
        resolved = start.resolve()
        if package != resolved.name:
            raise OctTestError(
                PACKAGE_UNKNOWN,
                f"--package {package!r} does not match the cwd "
                f"basename {resolved.name!r} and no "
                f"{WORKSPACE_MANIFEST} was found",
            )
        _dbg("OCT-TESTING", func, f"single-package at cwd {resolved}", 3)
        return DiscoveryResult(
            mode=MODE_SINGLE_PACKAGE,
            single=SinglePackage(
                root=resolved, package_id=package, config_file=None,
            ),
        )
 
    if workspace_root is not None:
        return _workspace_result(workspace_root, None)
    return DiscoveryResult(
        mode=MODE_SINGLE_PACKAGE,
        single=walk_for_package(start),
    )
 
 
def _workspace_result(
    workspace_root: Path,
    package: str | None,
) -> DiscoveryResult:
    """Build the workspace-mode result (§9 rows 1, 3, 5)."""
    func = "_workspace_result"
    manifest = load_test_manifest(workspace_root)
 
    if package is None:
        selected = manifest.enabled_packages
    else:
        target = manifest.packages_by_name.get(package)
        if target is None or not target.enabled:
            raise OctTestError(
                PACKAGE_UNKNOWN,
                f"package {package!r} is not listed and test-enabled "
                f"in {manifest.workspace.root / WORKSPACE_MANIFEST}",
            )
        selected = (target,)
 
    _dbg(
        "OCT-TESTING", func,
        f"workspace mode: {len(selected)} package(s) selected", 3,
    )
    return DiscoveryResult(
        mode=MODE_WORKSPACE,
        workspace_root=manifest.workspace.root,
        manifest=manifest,
        selected=selected,
    )
 
 
def walk_for_package(cwd: Path) -> SinglePackage:
    """ADR-T-12: walk upward from *cwd* for a package config file.
 
    Checks *cwd* plus up to :data:`WALK_LEVELS` ancestors for
    ``pyproject.toml`` or ``pytest.ini`` (preference order within a
    directory); the nearest hit wins. The package id is the config
    directory's basename unless the discovered ``pyproject.toml``
    carries a ``[tool.oct.test].package_id`` override (clause 5).
 
    Raises
    ------
    OctTestError
        ``CWD_RESOLUTION_FAILED`` with the ADR's pinned message when
        the walk exhausts its levels.
    """
    func = "walk_for_package"
    current = Path(cwd).resolve()
    candidates = [current, *current.parents[:WALK_LEVELS]]
    for candidate in candidates:
        for name in _CONFIG_FILE_NAMES:
            config_file = candidate / name
            if config_file.is_file():
                package_id = _package_id_for(candidate, config_file)
                _dbg(
                    "OCT-TESTING", func,
                    f"root={candidate} id={package_id!r} "
                    f"config={name}",
                    3,
                )
                return SinglePackage(
                    root=candidate,
                    package_id=package_id,
                    config_file=config_file,
                )
    _dbg("OCT-TESTING", func, f"resolution failed from {cwd}", 2)
    raise OctTestError(CWD_RESOLUTION_FAILED, CWD_RESOLUTION_MESSAGE)
 
 
def _package_id_for(root: Path, config_file: Path) -> str:
    """Infer the package id for *root* (ADR-T-12 clauses 4-5)."""
    func = "_package_id_for"
    if config_file.name != "pyproject.toml":
        return root.name
    try:
        with config_file.open("rb") as fh:
            data = tomllib.load(fh)
    except (OSError, tomllib.TOMLDecodeError) as exc:
        _dbg(
            "OCT-TESTING", func,
            f"unreadable pyproject at {root}: {exc}; basename stands",
            2,
        )
        return root.name
 
    node: object = data
    for key in ("tool", "oct", "test"):
        if not isinstance(node, dict):
            return root.name
        node = node.get(key)
    if not isinstance(node, dict):
        return root.name
    override = node.get("package_id")
    if isinstance(override, str) and override.strip():
        _dbg(
            "OCT-TESTING", func,
            f"package_id override {override!r} at {root}", 4,
        )
        return override
    return root.name
 
 
__all__ = [
    "CWD_RESOLUTION_MESSAGE",
    "DiscoveryResult",
    "MODE_SINGLE_PACKAGE",
    "MODE_WORKSPACE",
    "SinglePackage",
    "WALK_LEVELS",
    "discover",
    "walk_for_package",
]