alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/weave/resolver.py

@@ -0,0 +1,544 @@
+"""alter_runtime.weave.resolver — Semantic-unit resolver for the Weave coordination plane.
+
+D-WEAVE-VC-2 §2(a), §3, §7 precondition 1 (RATIFIED 2026-05-21).
+
+This module resolves a file + line-range to the enclosing code symbol (a function,
+method, class, or export).  It is the load-bearing primitive consumed by:
+
+  - S2 ``weave_intent_writer`` (enriches intent records with semantic-unit context)
+  - S4 ``weave-validate.py`` (affected-set computation for incremental local CI)
+
+Implementation decisions (from the Phase-0 plan):
+
+- **Embedded tree-sitter, not the serena MCP.**  Serena runs as a cold ``uvx``
+  subprocess; the weave hot path cannot afford the spawn latency.  tree-sitter
+  parses in-process, sub-millisecond per file, and is robust to partially-written
+  / syntactically-broken files — tree-sitter's error-recovery is the reason it is
+  chosen over ``ast``.
+
+- **Pure observation.** No blocking, no locks, no winner-picking.  Resolution
+  failure degrades to ``None`` (file-level intent) — never raises, never blocks.
+
+- **Python only (Phase 0).** The plan targets ``backend/app/`` and
+  ``alter_runtime/`` in Phase 0.  Extending to TypeScript / Rust is a Phase-1
+  concern.
+
+Public interface is a FROZEN CONTRACT (S4 codes against it verbatim):
+
+    resolve(file_path, line_range) -> SemanticUnit | None
+    import_graph(roots)            -> dict[str, set[str]]
+    reverse_dependents(changed, roots) -> set[str]
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # pragma: no cover — type-only import; never executed at runtime
+    import tree_sitter
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# tree-sitter language singleton (initialised once, never re-created)
+# ---------------------------------------------------------------------------
+
+_PARSER: Optional["tree_sitter.Parser"] = None
+_LANGUAGE: Optional["tree_sitter.Language"] = None
+
+
+def _get_parser() -> Optional["tree_sitter.Parser"]:
+    """Return (or lazily initialise) the shared tree-sitter Python parser.
+
+    Returns ``None`` if tree-sitter is not installed — callers degrade
+    gracefully rather than raising ImportError at module import time.
+    """
+    global _PARSER, _LANGUAGE
+    if _PARSER is not None:
+        return _PARSER
+    try:
+        import tree_sitter_python as tspython
+        from tree_sitter import Language, Parser
+
+        _LANGUAGE = Language(tspython.language())
+        _PARSER = Parser(_LANGUAGE)
+        return _PARSER
+    except Exception as exc:  # pragma: no cover — only hit if dep is absent
+        log.warning("tree-sitter unavailable; resolver will return None for all calls: %s", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Public data class
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SemanticUnit:
+    """A resolved code symbol — function, method, class, module, or export.
+
+    Attributes
+    ----------
+    symbol:
+        Short name of the symbol, e.g. ``"login"``.
+    kind:
+        One of ``"function"`` | ``"method"`` | ``"class"`` | ``"module"`` |
+        ``"export"``.  Python ``@decorated`` symbols carry the kind of the
+        underlying definition, not ``"decorated"``.
+    qualified_name:
+        Dot-separated fully-qualified name derived from the file path and
+        enclosing symbol hierarchy, e.g.
+        ``"backend.app.api.auth.login"``.
+    file_path:
+        Absolute (or as-supplied) path to the source file.
+    start_line:
+        1-based first line of the symbol body.
+    end_line:
+        1-based last line of the symbol body (inclusive).
+    """
+
+    symbol: str
+    kind: str
+    qualified_name: str
+    file_path: str
+    start_line: int
+    end_line: int
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _file_to_module(file_path: str) -> str:
+    """Derive a dotted module name from a file path.
+
+    Strategy: walk ``sys.path`` entries looking for the longest prefix that
+    contains the file; use the relative sub-path as the dotted name.  Falls
+    back to a sanitised version of the absolute path when nothing in
+    ``sys.path`` matches.
+
+    Examples
+    --------
+    ``/repo/backend/app/api/auth.py`` with ``/repo`` in ``sys.path``
+    → ``"backend.app.api.auth"``.
+    """
+    p = Path(file_path).resolve()
+
+    # Strip .py suffix
+    if p.suffix == ".py":
+        p = p.with_suffix("")
+    # __init__ → package name (strip the trailing __init__ segment)
+    if p.name == "__init__":
+        p = p.parent
+
+    # Try each sys.path entry from longest to shortest so the most-specific
+    # match wins.
+    candidates = sorted(
+        [Path(s).resolve() for s in sys.path if s],
+        key=lambda x: len(str(x)),
+        reverse=True,
+    )
+    for base in candidates:
+        try:
+            rel = p.relative_to(base)
+            return str(rel).replace(os.sep, ".")
+        except ValueError:
+            continue
+
+    # Fallback: sanitise the absolute path
+    return str(p).lstrip("/").replace(os.sep, ".").replace("-", "_")
+
+
+def _build_scope_stack(
+    root_node: "tree_sitter.Node",
+    target_line: int,
+) -> list[tuple[str, str]]:
+    """Return the ordered list of (name, kind) enclosing symbols for ``target_line``.
+
+    ``target_line`` is 0-based (tree-sitter convention).
+    Traverses the AST depth-first; pushes (name, kind) pairs for
+    ``function_definition``, ``class_definition``, and ``decorated_definition``
+    nodes whose span contains ``target_line``.
+    """
+    stack: list[tuple[str, str]] = []
+
+    def _kind_for(node_type: str, parent_kind: str | None) -> str:
+        if node_type == "class_definition":
+            return "class"
+        if node_type == "function_definition":
+            return "method" if parent_kind == "class" else "function"
+        return "function"
+
+    def _walk(node: "tree_sitter.Node", current_class: str | None = None) -> None:
+        for child in node.children:
+            start = child.start_point[0]
+            end = child.end_point[0]
+
+            # Only descend into nodes whose span contains the target line
+            if not (start <= target_line <= end):
+                continue
+
+            effective_child = child
+            # Unwrap decorated_definition → look at the inner function/class
+            if child.type == "decorated_definition":
+                # The actual definition is the last child of a decorated_definition
+                inner = child.child_by_field_name("definition")
+                if inner is None:
+                    # Fallback: last non-decorator child
+                    for c in reversed(child.children):
+                        if c.type in ("function_definition", "class_definition"):
+                            inner = c
+                            break
+                if inner is not None:
+                    effective_child = inner
+
+            if effective_child.type in ("function_definition", "class_definition"):
+                name_node = effective_child.child_by_field_name("name")
+                if name_node:
+                    name = name_node.text.decode("utf-8", errors="replace")
+                    kind = _kind_for(
+                        effective_child.type,
+                        stack[-1][1] if stack else None,
+                    )
+                    stack.append((name, kind))
+                    _walk(
+                        effective_child,
+                        current_class=name
+                        if effective_child.type == "class_definition"
+                        else current_class,
+                    )
+                    return  # Found a containing symbol — stop scanning siblings
+
+            # Recurse into non-symbol-boundary nodes (e.g. block, if_statement)
+            _walk(child, current_class=current_class)
+
+    _walk(root_node)
+    return stack
+
+
+def _parse_bytes(source: bytes) -> Optional["tree_sitter.Tree"]:
+    """Parse ``source`` bytes with the shared parser.  Returns ``None`` on failure."""
+    parser = _get_parser()
+    if parser is None:
+        return None
+    try:
+        return parser.parse(source)
+    except Exception as exc:
+        log.debug("tree-sitter parse error: %s", exc)
+        return None
+
+
+def _node_span(
+    root_node: "tree_sitter.Node",
+    symbol_stack: list[tuple[str, str]],
+) -> tuple[int, int]:
+    """Locate the innermost symbol in ``symbol_stack`` and return its 1-based line span."""
+    if not symbol_stack:
+        return (1, root_node.end_point[0] + 1)
+
+    def _unwrap_decorated(
+        node: "tree_sitter.Node",
+    ) -> "tree_sitter.Node":
+        """Unwrap a decorated_definition to its inner function/class."""
+        if node.type == "decorated_definition":
+            inner = node.child_by_field_name("definition")
+            if inner is not None:
+                return inner
+            for c in reversed(node.children):
+                if c.type in ("function_definition", "class_definition"):
+                    return c
+        return node
+
+    def _find_named_descendant(
+        node: "tree_sitter.Node",
+        target_name: str,
+    ) -> Optional["tree_sitter.Node"]:
+        """DFS search for a function/class node with ``target_name`` anywhere
+        in the subtree rooted at ``node``.  Returns the first match."""
+        for child in node.children:
+            effective = _unwrap_decorated(child)
+            if effective.type in ("function_definition", "class_definition"):
+                name_node = effective.child_by_field_name("name")
+                if name_node and name_node.text.decode("utf-8", errors="replace") == target_name:
+                    return effective
+            # Recurse into all children (including block, suite, etc.)
+            found = _find_named_descendant(child, target_name)
+            if found is not None:
+                return found
+        return None
+
+    # Walk the symbol stack from outermost to innermost, narrowing the search
+    # scope at each level.
+    current_scope: "tree_sitter.Node" = root_node
+    for name, _ in symbol_stack:
+        found = _find_named_descendant(current_scope, name)
+        if found is None:
+            # Could not locate symbol — fall back to module span
+            return (1, root_node.end_point[0] + 1)
+        current_scope = found
+
+    return (current_scope.start_point[0] + 1, current_scope.end_point[0] + 1)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def resolve(file_path: str, line_range: tuple[int, int]) -> SemanticUnit | None:
+    """Resolve a file + line range to the enclosing semantic unit.
+
+    Parameters
+    ----------
+    file_path:
+        Path to the Python source file.  May be absolute or relative; may
+        not exist on disk (edit-in-flight case — then ``None`` is returned).
+    line_range:
+        ``(start_line, end_line)`` — 1-based, inclusive.
+
+    Returns
+    -------
+    SemanticUnit
+        The innermost function / method / class whose span contains the
+        given line range.  When the range falls outside all symbol
+        boundaries the module itself is returned as a ``"module"`` unit.
+    None
+        Returned on any unrecoverable error (missing file, unreadable bytes,
+        irrecoverable parse failure) so callers can degrade gracefully to
+        file-level intent.
+
+    Notes
+    -----
+    - tree-sitter's error-recovery is leveraged for partially-written files:
+      even if the file contains syntax errors, tree-sitter produces a partial
+      AST and this function returns the best enclosing symbol it can find.
+    - This function is pure observation — it never writes to disk, never
+      blocks on I/O beyond reading the source file, and never raises.
+    """
+    try:
+        p = Path(file_path)
+        if not p.exists():
+            return None
+
+        source = p.read_bytes()
+        tree = _parse_bytes(source)
+        if tree is None:
+            return None
+
+        root = tree.root_node
+
+        # Use the midpoint of the range as the query line (0-based)
+        start_1, end_1 = line_range
+        mid_line_0 = ((start_1 - 1) + (end_1 - 1)) // 2
+
+        # Check if file is completely unparseable (root is ERROR with no useful children)
+        if root.has_error and all(c.type == "ERROR" for c in root.children if not c.is_extra):
+            # File is garbage — return module-level unit
+            module_name = _file_to_module(file_path)
+            short = module_name.split(".")[-1] if module_name else Path(file_path).stem
+            return SemanticUnit(
+                symbol=short,
+                kind="module",
+                qualified_name=module_name or short,
+                file_path=file_path,
+                start_line=1,
+                end_line=root.end_point[0] + 1,
+            )
+
+        symbol_stack = _build_scope_stack(root, mid_line_0)
+        module_qname = _file_to_module(file_path)
+
+        if not symbol_stack:
+            # Line falls in module scope — return module unit
+            short = module_qname.split(".")[-1] if module_qname else Path(file_path).stem
+            return SemanticUnit(
+                symbol=short,
+                kind="module",
+                qualified_name=module_qname or short,
+                file_path=file_path,
+                start_line=1,
+                end_line=root.end_point[0] + 1,
+            )
+
+        innermost_name, innermost_kind = symbol_stack[-1]
+        qualified_name = ".".join([module_qname] + [name for name, _ in symbol_stack])
+        start_l, end_l = _node_span(root, symbol_stack)
+
+        return SemanticUnit(
+            symbol=innermost_name,
+            kind=innermost_kind,
+            qualified_name=qualified_name,
+            file_path=file_path,
+            start_line=start_l,
+            end_line=end_l,
+        )
+
+    except Exception as exc:
+        log.debug("resolve(%r, %r) failed: %s", file_path, line_range, exc)
+        return None
+
+
+def import_graph(roots: list[str]) -> dict[str, set[str]]:
+    """Build an import dependency graph for all Python files under ``roots``.
+
+    Parameters
+    ----------
+    roots:
+        List of root directories (or individual ``.py`` files) to scan.
+
+    Returns
+    -------
+    dict mapping each module's qualified name to the set of qualified names
+    it imports.  Only modules discovered within ``roots`` appear as keys;
+    the imported-name values may reference stdlib or third-party modules.
+
+    Notes
+    -----
+    - Parsed with tree-sitter for robustness on in-flight / broken files.
+    - Falls back to an empty import set for any file that cannot be parsed.
+    - Relative imports (``from . import x``) are resolved against the
+      containing package where possible; unresolvable ones are stored as
+      the dotted relative form (``".x"``).
+    - This function is pure observation — no blocking, no side-effects.
+    """
+    graph: dict[str, set[str]] = {}
+
+    def _collect_files(root: str) -> list[Path]:
+        p = Path(root)
+        if p.is_file() and p.suffix == ".py":
+            return [p]
+        if p.is_dir():
+            return list(p.rglob("*.py"))
+        return []
+
+    all_files: list[Path] = []
+    for r in roots:
+        all_files.extend(_collect_files(r))
+
+    for file_path in all_files:
+        module_qname = _file_to_module(str(file_path))
+        imports = _extract_imports(file_path, module_qname)
+        graph[module_qname] = imports
+
+    return graph
+
+
+def _extract_imports(file_path: Path, module_qname: str) -> set[str]:
+    """Return the set of module names imported by ``file_path``."""
+    try:
+        source = file_path.read_bytes()
+    except OSError:
+        return set()
+
+    tree = _parse_bytes(source)
+    if tree is None:
+        return set()
+
+    imports: set[str] = set()
+    root = tree.root_node
+
+    def _walk(node: "tree_sitter.Node") -> None:
+        if node.type == "import_statement":
+            # import a.b.c  (possibly comma-separated)
+            for child in node.children:
+                if child.type == "dotted_name":
+                    imports.add(child.text.decode("utf-8", errors="replace"))
+                elif child.type == "aliased_import":
+                    # import a.b as x — the dotted_name is the first child
+                    dn = child.child_by_field_name("name")
+                    if dn:
+                        imports.add(dn.text.decode("utf-8", errors="replace"))
+
+        elif node.type == "import_from_statement":
+            # from <module> import <names>
+            # The module part may be a dotted_name or a relative_import
+            module_part = ""
+            relative_dots = 0
+
+            for child in node.children:
+                if child.type == "relative_import":
+                    # Count dots for relative resolution
+                    relative_dots = child.text.decode("utf-8", errors="replace").count(".")
+                elif child.type == "dotted_name" and not module_part:
+                    module_part = child.text.decode("utf-8", errors="replace")
+
+            if relative_dots > 0:
+                # Resolve relative to the containing package
+                pkg_parts = module_qname.split(".")
+                # Go up <relative_dots> levels
+                base_parts = pkg_parts[: max(0, len(pkg_parts) - relative_dots)]
+                if module_part:
+                    resolved = ".".join(base_parts + [module_part])
+                else:
+                    resolved = ".".join(base_parts) if base_parts else "."
+                imports.add(resolved)
+            elif module_part:
+                imports.add(module_part)
+
+        for child in node.children:
+            _walk(child)
+
+    _walk(root)
+    return imports
+
+
+def reverse_dependents(changed_modules: set[str], roots: list[str]) -> set[str]:
+    """Return all modules that transitively import any module in ``changed_modules``.
+
+    Parameters
+    ----------
+    changed_modules:
+        Qualified names of the modules that have changed.
+    roots:
+        Root directories to build the import graph from (same as
+        ``import_graph``).
+
+    Returns
+    -------
+    Set of qualified module names that (directly or transitively) depend on
+    any changed module.  The changed modules themselves are NOT included
+    unless they transitively import each other.
+
+    Notes
+    -----
+    - This is the **affected-set** computation that S4 (``weave-validate.py``)
+      uses to select which tests to run.
+    - Pure observation — no side effects.
+    - Under-approximation is possible (dynamic imports, ``importlib`` calls)
+      and is by design: the §5 agreement-rate metric measures the gap; the
+      GHA periodic audit remains the backstop.
+    """
+    graph = import_graph(roots)
+
+    # Build reverse map: module -> set of modules that import it
+    reverse: dict[str, set[str]] = {m: set() for m in graph}
+    for importer, imported_set in graph.items():
+        for imported in imported_set:
+            if imported not in reverse:
+                reverse[imported] = set()
+            reverse[imported].add(importer)
+
+    # BFS / iterative expansion from changed_modules
+    visited: set[str] = set()
+    frontier = set(changed_modules)
+    while frontier:
+        next_frontier: set[str] = set()
+        for mod in frontier:
+            if mod in visited:
+                continue
+            visited.add(mod)
+            dependents = reverse.get(mod, set())
+            for dep in dependents:
+                if dep not in visited:
+                    next_frontier.add(dep)
+        frontier = next_frontier
+
+    # Return dependents only (exclude the changed modules themselves unless
+    # they form a cycle)
+    return visited - changed_modules