stack/src/sem/nodes.py

"""Semantic node model.

Each meaningful AST construct becomes a ``SemanticNode`` with a stable
identity derived from its module path, qualified symbol name, node kind,
and ordinal position — never from line numbers.
"""

from __future__ import annotations

import enum
import hashlib
from dataclasses import dataclass, field


class NodeKind(enum.Enum):
    """Taxonomy of tracked AST constructs."""

    FUNCTION = "function"
    METHOD = "method"
    CLASS = "class"
    BRANCH_IF = "branch_if"
    BRANCH_ELSE = "branch_else"
    BRANCH_ELIF = "branch_elif"
    MATCH_CASE = "match_case"
    EXCEPT_HANDLER = "except_handler"
    FOR_LOOP = "for_loop"
    WHILE_LOOP = "while_loop"
    WITH_BLOCK = "with_block"
    RETURN = "return"
    RAISE = "raise"
    ASSERT = "assert"


def _make_node_id(
    module: str,
    symbol_context: list[str],
    kind: NodeKind,
    ordinal: int,
) -> str:
    """Build a stable, human-readable node identity string.

    Example: ``app.config::load_settings::branch_if[1]``
    """
    parts = [module]
    if symbol_context:
        parts.append("::".join(symbol_context))
    parts.append(f"{kind.value}[{ordinal}]")
    return "::".join(parts)


@dataclass
class Span:
    """Byte-offset span within a source file (line numbers as metadata only)."""

    start_line: int
    end_line: int
    start_col: int = 0
    end_col: int = 0


@dataclass
class RuntimeInfo:
    """Runtime coverage data attached after test execution."""

    hit: bool = False
    hit_count: int = 0
    tests_seen: list[str] = field(default_factory=list)


@dataclass
class SemanticNode:
    """A single tracked semantic unit in the codebase."""

    node_id: str
    kind: NodeKind
    span: Span
    module: str
    symbol_context: list[str] = field(default_factory=list)
    source_hash: str = ""

    # Enrichment: Ruff diagnostics
    ruff_codes: list[str] = field(default_factory=list)

    # Enrichment: ty diagnostics
    ty_codes: list[str] = field(default_factory=list)

    # Runtime coverage
    runtime: RuntimeInfo = field(default_factory=RuntimeInfo)

    # Planner state
    status: str = "unexplored"
    priority: float = 0.0
    attempts: int = 0
    intent_tags: list[str] = field(default_factory=list)

    @staticmethod
    def build(
        module: str,
        symbol_context: list[str],
        kind: NodeKind,
        ordinal: int,
        span: Span,
        source_fragment: str = "",
    ) -> SemanticNode:
        """Construct a node with a stable ID and optional source hash."""
        node_id = _make_node_id(module, symbol_context, kind, ordinal)
        src_hash = ""
        if source_fragment:
            src_hash = hashlib.sha1(
                source_fragment.encode(), usedforsecurity=False
            ).hexdigest()[:12]
        return SemanticNode(
            node_id=node_id,
            kind=kind,
            span=span,
            module=module,
            symbol_context=list(symbol_context),
            source_hash=src_hash,
        )