orchestrata_ast.scope

Reference › orchestrata_ast › scope

This module narrows a wide AST snapshot, one that covers the production package plus extra trees such as tests and scripts, back to the primary source tree. It is used by scripts.serialize_codebase_ast, the entry point behind the deployed ast command in /opt/orchestrata-tools/bin, and it is exercised by tests/test_orchestrata_ast_scope.py.

The serializer prefixes every module of an extra tree with that tree's directory name, so membership needs no heuristics. extra_tree_names reads the snapshot's extra_roots and returns the final path segment of each. is_primary_module is true when the first dotted segment of a module id is not one of those names. primary_root_only returns a shallow copy of the snapshot whose modules, inheritance_graph, dependency_graph and file_meta hold only primary entries, with extra_roots emptied. When the snapshot has no extra roots it returns the snapshot itself, so callers need no guard. See models for the snapshot layout.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ast/scope.py

"""Narrowing a wide snapshot back to the production package.

``plans/ast-ultimate.json`` covered ``src/orchestrata_ultimate`` alone until
2026-08-08, when it was widened to see ``tests`` and ``scripts`` as well. Every
consumer written before that date asked for "the snapshot" and MEANT "our
production source" — the two were the same object, so nobody had to say which.

Widening made them different, and the consumers kept their old question. The
coverage analyzer started reporting that test modules were untested; the port
comparison counted 1,688 test modules as unmapped and invented ``scripts`` as
a new external dependency.

This module is where a consumer says which one it wants. Consumers that reason
about the SHIPPED PACKAGE (coverage, port comparison, requirement attribution)
call :func:`primary_root_only`; consumers that reason about the REPOSITORY
(the gate's file-class rules, affected-test selection) take the snapshot whole.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any

__all__ = ["extra_tree_names", "is_primary_module", "primary_root_only"]


def extra_tree_names(snapshot: dict[str, Any]) -> frozenset[str]:
    """The leading dotted segment each extra tree contributes.

    Modules from an extra tree are identifiable without heuristics: the
    serializer prefixes them with that tree's own directory name, so
    ``tests/gates/test_gate_rules.py`` is ``tests.gates.test_gate_rules``.
    """
    return frozenset(
        Path(str(root)).name for root in snapshot.get("extra_roots", []) or []
    )


def is_primary_module(dotted: str, extras: frozenset[str]) -> bool:
    """Does *dotted* name a module of the primary tree rather than an extra?"""
    return dotted.split(".")[0] not in extras


def primary_root_only(snapshot: dict[str, Any]) -> dict[str, Any]:
    """*snapshot* narrowed to its PRIMARY source tree.

    A shallow copy: the caller gets narrowed ``modules``, graphs and
    ``file_meta``, and shares every other key with the original. Returns the
    snapshot unchanged when it has no extra roots, so callers need no guard.
    """
    extras = extra_tree_names(snapshot)
    if not extras:
        return snapshot

    narrowed = dict(snapshot)
    narrowed["modules"] = [
        module
        for module in snapshot.get("modules", []) or []
        if is_primary_module(str(module.get("path", "")), extras)
    ]
    for graph in ("inheritance_graph", "dependency_graph"):
        narrowed[graph] = {
            key: value
            for key, value in (snapshot.get(graph) or {}).items()
            if is_primary_module(str(key), extras)
        }
    # file_meta is keyed by the same dotted module path. Leaving it wide let a
    # narrowed snapshot still answer questions about tests/ and scripts/ files.
    narrowed["file_meta"] = {
        key: value
        for key, value in (snapshot.get("file_meta") or {}).items()
        if is_primary_module(str(key), extras)
    }
    narrowed["extra_roots"] = []
    return narrowed