stack/src/sem/__init__.py

"""Semantic coverage orchestration.

AST-based coverage tracking that attaches Ruff diagnostics, ty type
signals, and runtime coverage data to semantic nodes (functions, branches,
exception handlers) rather than raw line numbers.

Architecture
------------

::

    source .py
        → ast.parse
            → SemanticNode[] (stable IDs, no line numbers)
                → attach ruff diagnostics
                → attach ty diagnostics
                → attach coverage.py runtime data
                    → rank by priority heuristic
                        → next_targets()

Layers
------

1. **parse** — Walk AST, emit a ``SemanticNode`` for every function,
   method, class, branch (if/elif/else), match case, exception handler,
   loop, return, raise, assert, and with block.

2. **enrich** — Run ``ruff check --output-format=json`` and
   ``ty check --output-format=json`` as subprocesses, map each diagnostic
   to the tightest-span semantic node.

3. **runtime** — Read a ``coverage.py`` JSON report and mark which nodes
   were hit/missed.  Attach per-test execution contexts when available.

4. **plan** — Score each uncovered node using a weighted heuristic
   (branches > ty signals > partial functions > exception paths > ruff)
   and return a ranked list of test targets.

5. **state** — Persist node-level tracking across runs in a JSON file.
   Nodes whose source hash changes are automatically reset.  Stale
   entries (removed from the AST) are pruned on sync.

6. **hooks** — Pre-commit hook orchestration.  Smart test selection
   based on staged files: ``src/<mod>/`` changes → ``tests/<mod>/``
   runs.  Falls back to full suite on infrastructure changes.

Node identity
-------------

Every node has a stable ID built from its module path, qualified symbol
name, kind, and ordinal position::

    aco.express.pharmacy::pharmacy_claims::branch_if[0]
    sem.parse::_Collector::visit_If::branch_else[0]

Line numbers are stored as metadata in ``Span`` but never appear in the
ID.  A SHA-1 hash of the source fragment detects edits — the state layer
resets a node's history when its hash changes.

Usage
-----

::

    from sem import parse_module, attach_ruff, attach_coverage
    from sem import rank_nodes, next_targets

    nodes = parse_module(Path("src/aco/express/pharmacy.py"))
    attach_ruff(nodes, Path("src/aco/express/pharmacy.py"))
    attach_coverage(nodes, Path("coverage.json"), "src/aco/express/pharmacy.py")

    for target in next_targets(nodes, limit=5):
        print(target.node_id, target.priority, target.kind)
"""

from sem.enrich import attach_ruff, attach_ty
from sem.nodes import NodeKind, SemanticNode
from sem.parse import parse_module, parse_tree
from sem.plan import next_targets, rank_nodes
from sem.runtime import attach_coverage

__all__ = [
    "NodeKind",
    "SemanticNode",
    "parse_module",
    "parse_tree",
    "attach_ruff",
    "attach_ty",
    "attach_coverage",
    "rank_nodes",
    "next_targets",
]