orchestrata_ultimate.refactor.codemod.review_context

Reference › orchestrata_ultimate › refactor › codemod › review_context

A leaf module holding what a review check may know besides the module it reads, kept separate so review_catalogue, review_checks and review_engine can share it without a cycle. ReviewableWorkspace is a protocol for the parts of a workspace a review needs: forest, cig, root, include_roots and unparsable. ReviewContext is a frozen record built per file: the path under review, the mutated forest, the CodeIntelligenceGraph, the project's top-level module names, the workspace file list, the dependency names declared in pyproject.toml, the root, whether the file is a test or an entry file, the banned library names and the include roots.

At a glance

Class diagram

Dependency diagram

API

Classes

ReviewableWorkspace (protocol)

Bases: Protocol · Line 25

What the review engine reads from a workspace.

ReviewContext (dataclass)

Decorators: traces(spec='110', story='US-110-004', reqs=['REQ-110-033', 'REQ-110-035']), dataclass(frozen=True, slots=True) · Line 56

What a check may know besides the module it reads.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/refactor/codemod/review_context.py

"""SPEC-110 FR-012 -- the review-context leaf module.

``ReviewContext`` (what a check may know besides the module it reads), the
``_SIBLING_ROOTS`` constant and the ``ReviewableWorkspace`` Protocol live
here so that ``review_engine``, ``review_catalogue`` and ``review_checks``
can all depend on them without depending on each other (no import cycle).
"""

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Protocol

from orchestrata_ultimate.core.base.traces import traces

if TYPE_CHECKING:
    from orchestrata_ultimate.refactor.codemod._cig import CodeIntelligenceGraph
    from orchestrata_ultimate.refactor.ctok import LosslessModule

_SIBLING_ROOTS = frozenset({"scripts", "tests", "claude"})


class ReviewableWorkspace(Protocol):
    """What the review engine reads from a workspace."""

    @property
    def forest(self) -> Mapping[str, LosslessModule]:
        """The loaded forest."""
        ...

    @property
    def cig(self) -> CodeIntelligenceGraph:
        """The workspace's CodeIntelligenceGraph."""
        ...

    @property
    def root(self) -> Path:
        """Workspace root."""
        ...

    @property
    def include_roots(self) -> tuple[str, ...]:
        """Repo-relative roots the workspace was loaded from."""
        ...

    @property
    def unparsable(self) -> tuple[tuple[str, str], ...]:
        """(path, error_message) for files that failed to parse."""
        ...


@traces(spec="110", story="US-110-004", reqs=["REQ-110-033", "REQ-110-035"])
@dataclass(frozen=True, slots=True)
class ReviewContext:
    """What a check may know besides the module it reads.

    Attributes:
        path: Forest-relative path of the module under review.
        forest: The mutated forest (changed modules overlaid on the load).
        cig: The workspace's CodeIntelligenceGraph.
        project_modules: Top-level module names the forest defines.
        workspace_files: Forest-relative paths, parsed and unparsable.
        declared_deps: Normalised dependency names from ``pyproject.toml``.
        root: Workspace root.
        is_test: Whether ``path`` is a test file.
        is_main_file: Whether ``path`` is a CLI/entry file.
        banned_libraries: Names from ``.claude/banned-libraries.txt``.
        include_roots: Repo-relative roots the workspace was loaded from
            (empty: no restriction).
    """

    path: str
    forest: Mapping[str, LosslessModule]
    cig: CodeIntelligenceGraph
    project_modules: frozenset[str]
    workspace_files: frozenset[str]
    declared_deps: frozenset[str]
    root: Path
    is_test: bool
    is_main_file: bool
    banned_libraries: frozenset[str]
    include_roots: tuple[str, ...] = ()