adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/graph/cfg.py

@@ -0,0 +1,461 @@
+"""Intra-function Control Flow Graph + Reaching Definitions analysis (P2.18,
+generalized to a per-language seam in P4.6 — see PROBLEMS.md P4.6).
+
+Two sub-components, both language-agnostic:
+  A. CFGBuilderBase — shared block/def bookkeeping (block+def id allocation,
+     the `_link`/`_new_block`/`_new_def` primitives) that a per-language
+     subclass drives to walk a function CST into basic blocks. Python's is
+     `lang/python/cfg.py::PythonCFGBuilder`; Java's is
+     `lang/java/cfg.py::JavaCFGBuilder`. Neither this base class nor
+     `ReachingDefinitions` below ever inspects a tree-sitter node type —
+     that CST-coupled dispatch (which statement kinds branch/loop/terminate,
+     what counts as a literal or a taint source) lives entirely in the
+     subclass, driven by the `CFGConfig` a `LanguageBackend.cfg_config()`
+     supplies (mirrors how P4.4 split `ResolverConfig`'s declarative policy
+     from `CallResolver`'s CST-coupled mechanics).
+  B. ReachingDefinitions — runs the standard GEN/KILL fixpoint over the
+     CFGBlock graph any language's builder produces, and sweeps each block
+     to emit DefUseFact triples. Fully generic: it only ever touches
+     CFGBlock/CFGDef, never a CST node.
+
+Facts are stored in SQLite (CortexMemory.store_def_use_facts) and queried by
+SecurityDetector to promote/demote severity and by DynamicPatternDetector to
+tighten the resolvable= signal for getattr/exec dynamic patterns (both
+Python-only consumers).
+
+Key design choices (unchanged from P2.18):
+  - MAX_DEF_USE_FACTS_PER_FUNCTION = 10_000 cap (spec requirement).
+  - Conservative handling of unrecognised statement types: all identifiers
+    are treated as uses (never missed), no defs emitted (may miss some defs
+    in unusual syntax — safe to overapproximate in both directions).
+  - Parameters are defs in the entry block with is_literal=False and
+    taint_source=None (a parameter *could* be tainted; callers decide) —
+    except where a language's own source table marks a parameter as always
+    tainted (Java's `@RequestParam` et al.; see `lang/java/cfg.py`).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set, Tuple, Any
+
+from tree_sitter import Node
+
+from adl_drift.lang.base import CFGConfig
+from adl_drift.utils.types import SourcePosition
+
+
+# ─── tuning constants ─────────────────────────────────────────────────────────
+
+MAX_DEF_USE_FACTS_PER_FUNCTION = 10_000
+
+# ─── Python-only literal check, used by detectors/security.py's P2.18 eval/exec
+# severity refinement. Deliberately NOT part of the generic CFGConfig-driven
+# engine below — it is a standalone text/node-type check unrelated to CFG
+# construction, kept here unchanged so that pre-existing import stays valid:
+# `from adl_drift.graph.cfg import _is_literal as cfg_is_literal`. Java has
+# no equivalent consumer (JavaSecurityDetector does not do def-use severity
+# refinement), so this is not generalized.
+
+_LITERAL_TYPES: frozenset = frozenset({
+    "integer", "float", "string", "concatenated_string",
+    "true", "false", "none",
+})
+
+
+def _is_literal(node: Node) -> bool:
+    """True when node represents a compile-time constant (Python literals)."""
+    if node.type in _LITERAL_TYPES:
+        return True
+    if node.type == "unary_operator":
+        op = node.child_by_field_name("operator")
+        arg = node.child_by_field_name("argument")
+        if op and _text(op, b"-") == "-" and arg and arg.type in {"integer", "float"}:
+            return True
+    if node.type == "parenthesized_expression" and node.child_count >= 3:
+        inner = node.children[1]
+        return _is_literal(inner)
+    return False
+
+
+# ─── generic tree-sitter helpers (grammar-agnostic byte/position math) ───────
+
+def _node_pos(node: Node) -> SourcePosition:
+    return SourcePosition(
+        line=node.start_point[0] + 1,
+        column=node.start_point[1],
+        end_line=node.end_point[0] + 1,
+        end_column=node.end_point[1],
+    )
+
+
+def _text(node: Node, source: bytes) -> str:
+    try:
+        return source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+# ─── public data types ────────────────────────────────────────────────────────
+
+@dataclass
+class DefUseFact:
+    """A reaching-definition relationship within one function body.
+
+    Interpretation:
+      ``def_site`` is an assignment of ``binding_name``, and there exists a
+      control-flow path from ``def_site`` to ``use_site`` along which no other
+      assignment to ``binding_name`` occurs (standard reaching-definition).
+
+    ``is_literal``   — the RHS at ``def_site`` is a compile-time constant.
+    ``taint_source`` — the RHS is derived from a known user-input source.
+    """
+
+    function_id: str
+    binding_name: str
+    def_site: SourcePosition
+    use_site: SourcePosition
+    is_literal: bool = False
+    taint_source: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "function_id": self.function_id,
+            "binding_name": self.binding_name,
+            "def_site": self.def_site.to_dict(),
+            "use_site": self.use_site.to_dict(),
+            "is_literal": self.is_literal,
+            "taint_source": self.taint_source,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "DefUseFact":
+        return cls(
+            function_id=d["function_id"],
+            binding_name=d["binding_name"],
+            def_site=SourcePosition.from_dict(d["def_site"]),
+            use_site=SourcePosition.from_dict(d["use_site"]),
+            is_literal=d.get("is_literal", False),
+            taint_source=d.get("taint_source"),
+        )
+
+
+# ─── internal CFG types (shared by every language's builder) ─────────────────
+
+@dataclass
+class CFGDef:
+    idx: int                      # global index within this function
+    name: str
+    position: SourcePosition
+    is_literal: bool
+    taint_source: Optional[str]
+
+
+@dataclass
+class CFGUse:
+    name: str
+    position: SourcePosition
+
+
+@dataclass
+class CFGBlock:
+    id: int
+    # events: interleaved CFGDef / CFGUse objects in textual order.
+    # Preserving order lets the sweep correctly pair uses with their
+    # preceding defs (a use only sees defs from earlier in the same block).
+    events: List[Any] = field(default_factory=list)
+    succs: List[int] = field(default_factory=list)
+    preds: List[int] = field(default_factory=list)
+    # Dataflow sets (def indices)
+    gen: Set[int] = field(default_factory=set)
+    kill: Set[int] = field(default_factory=set)
+    inn: Set[int] = field(default_factory=set)
+    out: Set[int] = field(default_factory=set)
+
+    # Convenience views (populated lazily by _compute_gen_kill)
+    @property
+    def defs(self) -> List[CFGDef]:
+        return [e for e in self.events if isinstance(e, CFGDef)]
+
+    @property
+    def uses(self) -> List[CFGUse]:
+        return [e for e in self.events if isinstance(e, CFGUse)]
+
+
+# ─── CFG builder base (shared bookkeeping; CST dispatch is per-language) ─────
+
+class CFGBuilderBase:
+    """Shared block/def bookkeeping for CFG construction (P4.6).
+
+    Owns nothing CST-coupled: block/def id allocation and the block-graph
+    edge primitives (`_new_block`/`_new_def`/`_link`). `build()` — walking a
+    function CST node into basic blocks — is implemented by a per-language
+    subclass driven by `self.config` (a `CFGConfig`): `lang/python/cfg.py::
+    PythonCFGBuilder` (the original P2.18 Python dispatch, ported unchanged
+    behavior) and `lang/java/cfg.py::JavaCFGBuilder`.
+    """
+
+    def __init__(self, config: CFGConfig) -> None:
+        self.config = config
+        self._block_id: int = 0
+        self._def_id: int = 0
+        self._blocks: Dict[int, CFGBlock] = {}
+        self._all_defs: List[CFGDef] = []
+
+    def build(
+        self, func_node: Node, source: bytes
+    ) -> Tuple[int, int, Dict[int, CFGBlock], List[CFGDef]]:
+        """Return ``(entry_id, exit_id, blocks, all_defs)`` for `func_node`.
+
+        ``entry_id`` is the entry basic block. ``exit_id`` is the synthetic
+        sink block (all returns/raises/throws connect here). ``all_defs`` is
+        every `CFGDef`, indexed by `CFGDef.idx`. Implemented per language.
+        """
+        raise NotImplementedError
+
+    # ── shared bookkeeping ────────────────────────────────────────────────
+
+    def _reset(self) -> None:
+        self._block_id = 0
+        self._def_id = 0
+        self._blocks = {}
+        self._all_defs = []
+
+    def _new_block(self) -> CFGBlock:
+        b = CFGBlock(id=self._block_id)
+        self._block_id += 1
+        self._blocks[b.id] = b
+        return b
+
+    def _new_def(
+        self, name: str, pos: SourcePosition, is_lit: bool, taint: Optional[str]
+    ) -> CFGDef:
+        d = CFGDef(idx=self._def_id, name=name, position=pos,
+                   is_literal=is_lit, taint_source=taint)
+        self._def_id += 1
+        self._all_defs.append(d)
+        return d
+
+    def _link(self, src: CFGBlock, dst: CFGBlock) -> None:
+        if dst.id not in src.succs:
+            src.succs.append(dst.id)
+        if src.id not in dst.preds:
+            dst.preds.append(src.id)
+
+
+# ─── reaching definitions (100% generic — never touches a CST node) ─────────
+
+class ReachingDefinitions:
+    """Runs the GEN/KILL fixpoint over a CFG and emits DefUseFact triples."""
+
+    def analyze(
+        self,
+        entry_id: int,
+        exit_id: int,
+        blocks: Dict[int, CFGBlock],
+        all_defs: List[CFGDef],
+        function_id: str,
+    ) -> List[DefUseFact]:
+        """Return all reaching-definition facts for the function.
+
+        Capped at MAX_DEF_USE_FACTS_PER_FUNCTION; functions that overflow are
+        tagged by returning an empty list (the overflow is reported via the
+        *overflow* flag on the exit block — callers can detect it via
+        ``blocks[exit_id].gen``).
+        """
+        if not blocks:
+            return []
+
+        # ── Step 1: build per-name def index ─────────────────────────────
+        # defs_by_name[name] = sorted list of def indices for that name
+        defs_by_name: Dict[str, List[int]] = {}
+        for d in all_defs:
+            defs_by_name.setdefault(d.name, []).append(d.idx)
+
+        # ── Step 2: compute GEN and KILL per block ────────────────────────
+        for b in blocks.values():
+            seen_names: Dict[str, int] = {}  # name → last def idx seen in block
+            for d in b.defs:
+                seen_names[d.name] = d.idx
+            b.gen = set(seen_names.values())
+
+            # KILL[B] = all defs from *other* blocks for names defined in B
+            for name in seen_names:
+                for idx in defs_by_name.get(name, []):
+                    if idx not in b.gen:
+                        b.kill.add(idx)
+
+        # ── Step 3: fixpoint (worklist, reverse post-order approx) ───────
+        # OUT[B] = GEN[B] ∪ (IN[B] − KILL[B])
+        # IN[B]  = ∪ OUT[P]  for all predecessors P
+
+        # Initialise
+        for b in blocks.values():
+            b.inn = set()
+            b.out = set(b.gen)
+
+        worklist: deque = deque(blocks.keys())
+        seen_in_wl: Set[int] = set(blocks.keys())
+
+        while worklist:
+            bid = worklist.popleft()
+            seen_in_wl.discard(bid)
+            b = blocks[bid]
+
+            new_in: Set[int] = set()
+            for pred_id in b.preds:
+                new_in |= blocks[pred_id].out
+
+            new_out = b.gen | (new_in - b.kill)
+
+            if new_out != b.out or new_in != b.inn:
+                b.inn = new_in
+                b.out = new_out
+                for succ_id in b.succs:
+                    if succ_id not in seen_in_wl:
+                        worklist.append(succ_id)
+                        seen_in_wl.add(succ_id)
+
+        # ── Step 4: sweep each block and emit DefUseFacts ─────────────────
+        # Walk the interleaved events list in textual order so that a def on
+        # line N is visible only to uses on line N+1+, not to earlier uses.
+        def_by_idx: Dict[int, CFGDef] = {d.idx: d for d in all_defs}
+
+        facts: List[DefUseFact] = []
+        overflow = False
+
+        for b in blocks.values():
+            reaching: Set[int] = set(b.inn)
+
+            for event in b.events:
+                if isinstance(event, CFGUse):
+                    for idx in list(reaching):
+                        d = def_by_idx.get(idx)
+                        if d is None or d.name != event.name:
+                            continue
+                        facts.append(DefUseFact(
+                            function_id=function_id,
+                            binding_name=event.name,
+                            def_site=d.position,
+                            use_site=event.position,
+                            is_literal=d.is_literal,
+                            taint_source=d.taint_source,
+                        ))
+                        if len(facts) >= MAX_DEF_USE_FACTS_PER_FUNCTION:
+                            overflow = True
+                            break
+                elif isinstance(event, CFGDef):
+                    # Kill previous defs of same name, then add this one
+                    for prev_idx in list(reaching):
+                        prev = def_by_idx.get(prev_idx)
+                        if prev and prev.name == event.name:
+                            reaching.discard(prev_idx)
+                    reaching.add(event.idx)
+
+                if overflow:
+                    break
+            if overflow:
+                blocks[exit_id].gen.add(-1)
+                return facts
+
+        return facts
+
+
+# ─── public entry points ──────────────────────────────────────────────────────
+
+def _default_python_cfg_config() -> CFGConfig:
+    from adl_drift.lang.python.cfg import default_python_cfg_config
+    return default_python_cfg_config()
+
+
+def analyze_function(
+    func_node: Node,
+    source: bytes,
+    function_id: str,
+    cfg_config: Optional[CFGConfig] = None,
+) -> List[DefUseFact]:
+    """Build CFG + run reaching-definitions for one function. Returns facts.
+
+    ``cfg_config`` defaults to Python's (`lang/python/cfg.py::
+    default_python_cfg_config`) when omitted — every pre-P4.6 call site
+    (which never passes one) is unaffected."""
+    if cfg_config is None:
+        cfg_config = _default_python_cfg_config()
+    if cfg_config.cfg_builder_factory is None:
+        raise ValueError(
+            "CFGConfig.cfg_builder_factory must be set "
+            "(see lang/python/cfg.py::default_python_cfg_config)."
+        )
+    builder = cfg_config.cfg_builder_factory(cfg_config)
+    entry_id, exit_id, blocks, all_defs = builder.build(func_node, source)
+    rd = ReachingDefinitions()
+    return rd.analyze(entry_id, exit_id, blocks, all_defs, function_id)
+
+
+def analyze_file(
+    root_node: Node,
+    source: bytes,
+    module_name: str,
+    node_id_map: Dict[str, str],
+    cfg_config: Optional[CFGConfig] = None,
+) -> List[DefUseFact]:
+    """Analyze all top-level and class-method functions in a file.
+
+    ``node_id_map`` maps ``(module.Class.func)`` → graph node id.
+    Used to set ``DefUseFact.function_id`` correctly.
+    Falls back to a simple qualified-name heuristic when the map doesn't
+    contain an entry.
+
+    Python-specific: the module-level walk (``_walk_for_functions``) looks
+    for `function_definition`/`class_definition` CST nodes, so this
+    convenience entry point only makes sense for Python sources today — the
+    CLI/server def-use pass (P4.10, not this issue's scope) only ever calls
+    it on Python files. Java callers should build their own file-level walk
+    (or call `analyze_function` directly per method, as
+    `lang/java/cfg.py`'s tests do) rather than reusing this function.
+    """
+    facts: List[DefUseFact] = []
+    _walk_for_functions(root_node, source, module_name, [], node_id_map, facts, cfg_config)
+    return facts
+
+
+def _walk_for_functions(
+    node: Node,
+    source: bytes,
+    module: str,
+    scope: List[str],
+    node_id_map: Dict[str, str],
+    out: List[DefUseFact],
+    cfg_config: Optional[CFGConfig],
+) -> None:
+    """DFS: find function_definition nodes and analyze them."""
+    t = node.type
+
+    if t in ("function_definition", "async_function_definition"):
+        name_node = node.child_by_field_name("name")
+        fname = _text(name_node, source) if name_node else "<anon>"
+        full_scope = scope + [fname]
+        fid_key = module + "." + ".".join(full_scope)
+        fid = node_id_map.get(fid_key, fid_key)
+        try:
+            facts = analyze_function(node, source, fid, cfg_config)
+        except Exception:
+            facts = []
+        out.extend(facts)
+        # Recurse into body for nested functions (closures)
+        body = node.child_by_field_name("body")
+        if body:
+            _walk_for_functions(body, source, module, full_scope, node_id_map, out, cfg_config)
+        return
+
+    if t in ("class_definition",):
+        name_node = node.child_by_field_name("name")
+        cname = _text(name_node, source) if name_node else "<anon_cls>"
+        body = node.child_by_field_name("body")
+        if body:
+            _walk_for_functions(body, source, module, scope + [cname], node_id_map, out, cfg_config)
+        return
+
+    for child in node.children:
+        _walk_for_functions(child, source, module, scope, node_id_map, out, cfg_config)

package/adl_drift/graph/cluster.py

@@ -0,0 +1,40 @@
+"""Community detection over the call graph.
+
+Louvain runs on the directed graph (no `to_undirected()` cast). networkx's
+`louvain_communities` accepts DiGraph natively and treats edges as directed,
+so caller/callee semantics are preserved — a utility called by many should
+land in a different community than its callers.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+import networkx as nx
+
+
+def detect_communities(graph: nx.DiGraph, seed: int = 42) -> Dict[str, int]:
+    """Run Louvain on `graph`; return {node_id: community_id}.
+
+    Deterministic via fixed `seed`. Returns empty dict for empty graphs.
+    Community ids are zero-based ints, dense.
+    """
+    if graph.number_of_nodes() == 0:
+        return {}
+    if graph.is_multigraph():
+        # Louvain doesn't accept multigraphs — collapse parallel edges
+        # (direction preserved; edge multiplicity is irrelevant for clustering)
+        graph = nx.DiGraph(graph)
+    try:
+        communities = nx.algorithms.community.louvain_communities(
+            graph, seed=seed, weight=None
+        )
+    except Exception:
+        # Pathological graphs (e.g., disconnected singletons) -> fallback:
+        # each weakly-connected component gets its own community.
+        communities = list(nx.weakly_connected_components(graph))
+    out: Dict[str, int] = {}
+    for idx, members in enumerate(communities):
+        for nid in members:
+            out[nid] = idx
+    return out

package/adl_drift/graph/edges.py

@@ -0,0 +1,86 @@
+"""Edge definitions for call graph.
+
+Represents calls, imports, inheritance, and other relationships.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Optional, Dict, Any
+
+
+class EdgeType(Enum):
+    """Types of edges in the graph."""
+    CALLS = auto()           # function A calls function B
+    IMPORTS = auto()       # module A imports module B
+    INHERITS = auto()      # class A inherits from class B
+    IMPLEMENTS = auto()    # class A implements interface B
+    CONTAINS = auto()      # module/class A contains function B
+    DECORATED_BY = auto()  # function A is decorated by decorator B
+    AWAITS = auto()        # async function A awaits function B
+    REFERENCES = auto()    # function A reads variable/constant B (P1.8)
+    TYPE_OF = auto()       # function A has a parameter annotated with class B (P1.8)
+    RETURNS = auto()       # function A's return annotation is class B (P1.8)
+    INSTANTIATES = auto()  # function A constructs class B, i.e. B(...) (P2.8)
+    OVERRIDES = auto()     # method A overrides ancestor method B (P2.8)
+    DYNAMIC_ATTR = auto()  # caller reads a dynamic attr on a __getattr__ class (P2.14)
+    CALLABLE_REF = auto()  # Java method/constructor reference (P4.13)
+
+
+@dataclass
+class GraphEdge:
+    """An edge in the call graph."""
+    source: str            # Source node ID
+    target: str            # Target node ID
+    edge_type: EdgeType
+    file_path: Optional[str] = None
+    line: Optional[int] = None
+    # 0-indexed column of the call-site node itself (tree-sitter `start_point[1]`).
+    # Disambiguates two calls to the same simple name that resolve to different
+    # targets but land on the same source line, e.g. `good.process(q); bad.process("x");`
+    # — see `detectors/taint.py::TaintAnalyzer._resolve_callees` (F-03, PROBLEMS.md P4.6).
+    column: Optional[int] = None
+    # Exact CST byte range for call-site identity. Nested fluent invocations
+    # can share the same begin line/column, while their end byte remains
+    # distinct (`builder.step().step()`). Optional for structural/legacy
+    # edges and old persisted graphs.
+    start_byte: Optional[int] = None
+    end_byte: Optional[int] = None
+
+    # For call edges: arguments passed
+    call_args: Optional[str] = None
+
+    # Resolver confidence in [0.0, 1.0]. Structural edges (CONTAINS, INHERITS,
+    # IMPLEMENTS, DECORATED_BY, IMPORTS) are exact -> 1.0. CALLS / AWAITS are populated
+    # from CallGraphBuilder._resolve_target() strategy scores (0.3-0.95).
+    confidence: float = 1.0
+    strategy: Optional[str] = None
+
+    # Optional per-edge provenance. P4.12 (Java abstract-type dispatch fan-out)
+    # populates it with `strategy` (why the edge exists — e.g. "single_implementor",
+    # "interface_fanout", "spring_qualifier") and `declared_receiver_type` (the
+    # interface/abstract type the call was statically typed as), so impact/MCP can
+    # explain a fanned-out CALLS edge to a concrete implementor (deep-dive §8.4).
+    # Empty for every edge the other resolvers emit — additive, never required.
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "source": self.source,
+            "target": self.target,
+            "type": self.edge_type.name,
+            "position": (
+                {"file": self.file_path, "line": self.line, "column": self.column}
+                if self.file_path else None
+            ),
+            "confidence": self.confidence,
+            "metadata": self.metadata,
+        }
+        if self.start_byte is not None:
+            result["start_byte"] = self.start_byte
+        if self.end_byte is not None:
+            result["end_byte"] = self.end_byte
+        if self.strategy:
+            result["strategy"] = self.strategy
+        return result

package/adl_drift/graph/node.py

@@ -0,0 +1,90 @@
+"""Graph node definitions for call graph analysis.
+
+Represents functions, classes, modules as nodes in the dependency graph.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any, Set
+from enum import Enum, auto
+
+
+class NodeType(Enum):
+    """Types of nodes in the call graph."""
+    FUNCTION = auto()
+    CLASS = auto()
+    MODULE = auto()
+    VARIABLE = auto()
+    IMPORT = auto()
+
+
+@dataclass
+class GraphNode:
+    """A node in the call graph.
+
+    Equivalent to a node in Rust's petgraph or similar graph library.
+    """
+    id: str                            # Unique identifier: "module:Class.method" (P1.10: ':' splits module from qualname; module nodes have no ':')
+    name: str
+    node_type: NodeType
+    module: str                        # Python module path
+    file_path: str
+    line: int
+    column: int
+    end_line: int = 0  # 0 = unknown (synthetic/module nodes; symbols set it from parse position)
+
+    # P1.10 step 3: human-readable dotted name used by search and display.
+    # The id is an opaque internal handle (it may contain <locals> markers);
+    # qualified_name is the CPython-style dotted form without them. Derived
+    # in __post_init__ when not supplied (e.g. loading pre-P1.10 rows).
+    qualified_name: str = ""
+
+    # Relationships
+    calls: Set[str] = field(default_factory=set)       # IDs of nodes this calls
+    called_by: Set[str] = field(default_factory=set)    # IDs of nodes that call this
+    contains: Set[str] = field(default_factory=set)     # For classes/modules containing functions
+    contained_in: Optional[str] = None                  # Parent container
+
+    # Metadata
+    is_async: bool = False
+    is_decorated: bool = False
+    decorators: List[str] = field(default_factory=list)
+    docstring: Optional[str] = None
+    signature: Optional[str] = None
+    language: str = "python"
+
+    # Analysis flags
+    is_entry_point: bool = False        # e.g., route handlers, main()
+    is_test: bool = False               # test_* or *_test functions
+    metadata: Dict[str, Any] = field(default_factory=dict)  # arbitrary tags (e.g. synthetic=exec)
+
+    def __post_init__(self) -> None:
+        if not self.qualified_name:
+            # ':' module/qualname split → dotted display form; <locals>
+            # markers dropped. Two distinct ids (a:b.c vs a.b:c) may share a
+            # qualified_name — that is the ambiguity search reports honestly.
+            display_id = re.sub(
+                r"\([^)]*\)", "", self.id.split("::", 1)[-1]
+            ).rstrip(".")
+            self.qualified_name = display_id.replace(":", ".").replace(".<locals>", "")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "qualified_name": self.qualified_name,
+            "name": self.name,
+            "type": self.node_type.name,
+            "module": self.module.split("::", 1)[-1],
+            "file": self.file_path,
+            "position": {"line": self.line, "column": self.column, "end_line": self.end_line},
+            "calls": list(self.calls),
+            "called_by": list(self.called_by),
+            "is_async": self.is_async,
+            "is_entry_point": self.is_entry_point,
+            "is_test": self.is_test,
+            "language": self.language,
+            "signature": self.signature,
+            "metadata": self.metadata,
+        }

package/adl_drift/harness/__init__.py

@@ -0,0 +1,10 @@
+"""Harness layer: gets the MCP tools into the agent's hands.
+
+`setup`  — write/merge client configs (.mcp.json, .cursor/mcp.json,
+           .codex/config.toml, ~/.gemini/.../mcp_config.json) and install
+           the skill file;
+           `doctor` verifies the wiring end-to-end.
+`watch`  — hash-based polling loop that keeps the index fresh while editing.
+
+See HARNESS.md for the design rationale.
+"""