devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/codeintel/query/engine.py

@@ -0,0 +1,289 @@
+"""Generation-consistent search, exploration, path, and impact queries."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from pathlib import Path
+from typing import Any, Iterable
+
+from devcouncil.codeintel.service import CodeIntelService, get_codeintel_service
+from devcouncil.indexing.graph.schema import CodeGraph, Confidence, GraphEdge, GraphNode
+
+
+class CodeIntelQueryEngine:
+    def __init__(self, root: Path | CodeIntelService):
+        self.service = root if isinstance(root, CodeIntelService) else get_codeintel_service(root)
+
+    def _graph(self) -> CodeGraph:
+        graph = self.service.load()
+        if graph is None:
+            raise FileNotFoundError("no code-intelligence index; run `dev graph init`")
+        # Fingerprinting shells out to git (diff + untracked hashing) — only pay
+        # that per-query cost when runtime evidence actually exists to match.
+        if not self.service.store.has_runtime_observations():
+            return graph
+        from devcouncil.codeintel.debug.fingerprint import source_fingerprint
+
+        fingerprint = source_fingerprint(self.service.project_root)
+        runtime = self.service.store.runtime_observations(source_fingerprint=fingerprint)
+        existing = {(edge.source, edge.target, edge.kind) for edge in graph.edges}
+        for observation in runtime:
+            kind = str(observation["kind"])
+            key = (str(observation["source"]), str(observation["target"]), kind)
+            if key in existing:
+                continue
+            sampled = kind in {"sampled_calls", "sampled_stack"}
+            graph.edges.append(GraphEdge(
+                source=key[0],
+                target=key[1],
+                kind=kind,
+                confidence=Confidence.INFERRED if sampled else Confidence.EXTRACTED,
+                reason="fingerprint-matched runtime observation",
+                extras={
+                    "provenance": "runtime",
+                    "confidence_score": 0.75 if sampled else 1.0,
+                    "source_fingerprint": fingerprint,
+                    "runtime_session": observation["session_id"],
+                    "count": observation["count"],
+                    "evidence": observation["evidence"],
+                },
+            ))
+            existing.add(key)
+        return graph
+
+    def _envelope(self, payload: dict[str, Any]) -> dict[str, Any]:
+        from devcouncil.codeintel.sync import get_sync_coordinator
+
+        status = self.service.status()
+        sync = get_sync_coordinator(self.service.project_root).status().as_dict()
+        graph_degraded = False
+        graph_degraded_reason = ""
+        try:
+            from devcouncil.utils.json_persist import read_json
+
+            map_path = self.service.project_root / ".devcouncil" / "repo_map.json"
+            if map_path.is_file():
+                data = read_json(map_path)
+                if isinstance(data, dict) and data.get("graph_degraded"):
+                    graph_degraded = True
+                    graph_degraded_reason = str(data.get("graph_degraded_reason") or "")
+        except Exception:
+            pass
+        return {
+            "ok": True,
+            "project_root": str(self.service.project_root),
+            "generation": status.get("generation"),
+            "schema_version": status.get("schema_version"),
+            "analyzer_version": status.get("analyzer_version"),
+            "sync": sync,
+            "graph_degraded": graph_degraded,
+            "graph_degraded_reason": graph_degraded_reason,
+            **payload,
+        }
+
+    def search(self, query: str, *, limit: int = 50) -> dict[str, Any]:
+        rows = self.service.cached_query(
+            "search", f"{query}\0{limit}", lambda: self.service.store.search(query, limit=limit)
+        )
+        return self._envelope({"query": query, "matches": rows})
+
+    def explore(self, query: str, *, limit: int = 20) -> dict[str, Any]:
+        graph = self._graph()
+        matches = self._match(graph, query)[:limit]
+        inbound, outbound = self._relations(graph.edges)
+        definitions: list[dict[str, Any]] = []
+        for node in matches:
+            content = self.service.store.content_for_path(node.path)
+            snippet = self._snippet(content, node.line, node.end_line)
+            callers = [self._edge_dict(edge) for edge in inbound.get(node.id, [])[:50]]
+            callees = [self._edge_dict(edge) for edge in outbound.get(node.id, [])[:50]]
+            definitions.append({
+                "id": node.id,
+                "kind": node.kind.value if hasattr(node.kind, "value") else str(node.kind),
+                "path": node.path,
+                "name": node.name,
+                "line": node.line,
+                "end_line": node.end_line,
+                "language": node.language,
+                "source": snippet,
+                "callers": callers,
+                "callees": callees,
+            })
+        impacted = self._impact_for_ids(graph, [node.id for node in matches], max_depth=3)
+        return self._envelope({
+            "query": query,
+            "match_count": len(matches),
+            "definitions": definitions,
+            "blast_radius": impacted,
+        })
+
+    def path(self, start: str, end: str, *, max_depth: int = 32) -> dict[str, Any]:
+        graph = self._graph()
+        starts = {node.id for node in self._match(graph, start)}
+        ends = {node.id for node in self._match(graph, end)}
+        if not starts or not ends:
+            return self._envelope({"from": start, "to": end, "found": False, "path": [], "reason": "endpoint not found"})
+        adjacency: dict[str, list[tuple[str, GraphEdge]]] = defaultdict(list)
+        for edge in graph.edges:
+            adjacency[edge.source].append((edge.target, edge))
+            if edge.kind in {"imports", "contains", "defines", "inherits", "implements", "overrides"}:
+                adjacency[edge.target].append((edge.source, edge))
+        queue = deque((node_id, 0) for node_id in starts)
+        parent: dict[str, tuple[str | None, GraphEdge | None]] = {node_id: (None, None) for node_id in starts}
+        found: str | None = None
+        while queue:
+            current, depth = queue.popleft()
+            if current in ends:
+                found = current
+                break
+            if depth >= max_depth:
+                continue
+            for target, edge in adjacency.get(current, []):
+                if target not in parent:
+                    parent[target] = (current, edge)
+                    queue.append((target, depth + 1))
+        if found is None:
+            return self._envelope({"from": start, "to": end, "found": False, "path": []})
+        steps: list[dict[str, Any]] = []
+        walk = found
+        while True:
+            previous, path_edge = parent[walk]
+            steps.append({"node": walk, "via": self._edge_dict(path_edge) if path_edge else None})
+            if previous is None:
+                break
+            walk = previous
+        steps.reverse()
+        return self._envelope({"from": start, "to": end, "found": True, "length": len(steps) - 1, "path": steps})
+
+    def impact(self, targets: Iterable[str], *, max_depth: int = 3) -> dict[str, Any]:
+        graph = self._graph()
+        ids: list[str] = []
+        for target in targets:
+            ids.extend(node.id for node in self._match(graph, target))
+        return self._envelope({"targets": list(targets), "blast_radius": self._impact_for_ids(graph, ids, max_depth=max_depth)})
+
+    def dead(self, *, minimum_confidence: str = "inferred") -> dict[str, Any]:
+        graph = self._graph()
+        ranks = {"ambiguous": 0, "inferred": 1, "extracted": 2}
+        floor = ranks.get(minimum_confidence, 1)
+        runtime_live = {
+            edge.target
+            for edge in graph.edges
+            if edge.extras.get("provenance") == "runtime"
+        }
+        rows = []
+        for entry in graph.dead_code:
+            confidence = entry.confidence.value if hasattr(entry.confidence, "value") else str(entry.confidence)
+            if ranks.get(confidence, 0) < floor:
+                continue
+            if entry.id in runtime_live:
+                continue
+            tier = "high-confidence dead candidate" if confidence == "extracted" else "unconfirmed/unwired"
+            rows.append({**entry.model_dump(mode="json"), "tier": tier})
+        return self._envelope({
+            "minimum_confidence": minimum_confidence,
+            "dead_code": rows,
+            "runtime_proven_live": sorted(runtime_live),
+        })
+
+    def affected_tests(self, targets: Iterable[str], *, max_depth: int = 3) -> dict[str, Any]:
+        graph = self._graph()
+        target_list = list(targets)
+        ids = [node.id for target in target_list for node in self._match(graph, target)]
+        impact = self._impact_for_ids(graph, ids, max_depth=max_depth)
+        impacted_ids = {node_id for layer in impact["layers"] for node_id in layer["nodes"]} | set(ids)
+        nodes = graph.node_by_id()
+        tests = sorted({
+            node.path
+            for node_id in impacted_ids
+            if (node := nodes.get(node_id)) is not None and self._is_test_path(node.path)
+        })
+        return self._envelope({"targets": target_list, "tests": tests, "blast_radius": impact})
+
+    @staticmethod
+    def _match(graph: CodeGraph, query: str) -> list[GraphNode]:
+        normalized = query.replace("\\", "/").lower()
+        exact: list[GraphNode] = []
+        partial: list[GraphNode] = []
+        for node in graph.nodes:
+            values = (node.id.lower(), node.path.lower(), node.name.lower())
+            if normalized in values or node.id.lower().endswith(f"::{normalized}"):
+                exact.append(node)
+            elif any(normalized in value for value in values):
+                partial.append(node)
+        return exact + partial
+
+    @staticmethod
+    def _relations(edges: Iterable[GraphEdge]) -> tuple[dict[str, list[GraphEdge]], dict[str, list[GraphEdge]]]:
+        inbound: dict[str, list[GraphEdge]] = defaultdict(list)
+        outbound: dict[str, list[GraphEdge]] = defaultdict(list)
+        for edge in edges:
+            inbound[edge.target].append(edge)
+            outbound[edge.source].append(edge)
+        return inbound, outbound
+
+    @staticmethod
+    def _edge_dict(edge: GraphEdge | None) -> dict[str, Any]:
+        if edge is None:
+            return {}
+        confidence = edge.confidence.value if hasattr(edge.confidence, "value") else str(edge.confidence)
+        return {
+            "source": edge.source,
+            "target": edge.target,
+            "kind": edge.kind,
+            "confidence": confidence,
+            "confidence_score": edge.extras.get("confidence_score", {"extracted": 1.0, "inferred": 0.7, "ambiguous": 0.4}.get(confidence, 0.4)),
+            "provenance": edge.extras.get("provenance", "extracted" if confidence == "extracted" else "inferred"),
+            "reason": edge.reason,
+            "evidence": edge.extras.get("evidence", []),
+        }
+
+    @staticmethod
+    def _snippet(content: bytes | None, start: int, end: int) -> str:
+        if content is None:
+            return ""
+        lines = content.decode("utf-8", errors="replace").splitlines()
+        if start <= 0:
+            return ""
+        final = end if end >= start else start
+        return "\n".join(f"{line_no}: {lines[line_no - 1]}" for line_no in range(start, min(final, len(lines)) + 1))
+
+    def _impact_for_ids(self, graph: CodeGraph, ids: Iterable[str], *, max_depth: int) -> dict[str, Any]:
+        seeds = list(dict.fromkeys(ids))
+        inbound, _ = self._relations(graph.edges)
+        visited = set(seeds)
+        frontier = set(seeds)
+        layers: list[dict[str, Any]] = []
+        for depth in range(1, max(1, min(8, max_depth)) + 1):
+            next_frontier: set[str] = set()
+            confidences: list[str] = []
+            for node_id in frontier:
+                for edge in inbound.get(node_id, []):
+                    if edge.source in visited:
+                        continue
+                    next_frontier.add(edge.source)
+                    confidence = edge.confidence.value if hasattr(edge.confidence, "value") else str(edge.confidence)
+                    confidences.append(confidence)
+            visited.update(next_frontier)
+            layers.append({
+                "depth": depth,
+                "nodes": sorted(next_frontier),
+                "confidence": self._lowest_confidence(confidences),
+                "count": len(next_frontier),
+            })
+            frontier = next_frontier
+            if not frontier:
+                break
+        return {"seeds": seeds, "layers": layers, "total_impacted": len(visited - set(seeds))}
+
+    @staticmethod
+    def _lowest_confidence(values: Iterable[str]) -> str:
+        ranks = {"extracted": 2, "inferred": 1, "ambiguous": 0}
+        values = list(values)
+        return min(values, key=lambda value: ranks.get(value, 0)) if values else "extracted"
+
+    @staticmethod
+    def _is_test_path(path: str) -> bool:
+        normalized = f"/{path.lower().replace('\\', '/')}"
+        name = Path(path).name.lower()
+        return "/test" in normalized or "/tests/" in normalized or name.startswith("test_") or ".test." in name or ".spec." in name

package/src/devcouncil/codeintel/resolution/__init__.py

@@ -0,0 +1,6 @@
+"""Semantic synthesis beyond direct syntax edges."""
+
+from devcouncil.codeintel.resolution.abstract_state import AbstractState, AbstractValue
+from devcouncil.codeintel.resolution.semantic import enrich_semantic_edges
+
+__all__ = ["AbstractState", "AbstractValue", "enrich_semantic_edges"]

package/src/devcouncil/codeintel/resolution/abstract_state.py

@@ -0,0 +1,301 @@
+"""Bounded abstract values for computed names, imports, and paths."""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, Mapping
+
+MAX_STRINGS = 32
+MAX_CALLABLES = 32
+MAX_TYPES = 16
+
+
+@dataclass(frozen=True)
+class AbstractValue:
+    scalars: frozenset[str | int | float | bool | None] = frozenset()
+    callables: frozenset[str] = frozenset()
+    types: frozenset[str] = frozenset()
+    unknown: bool = False
+
+    @classmethod
+    def unknown_value(cls) -> "AbstractValue":
+        return cls(unknown=True)
+
+    @classmethod
+    def scalar(cls, value: str | int | float | bool | None) -> "AbstractValue":
+        return cls(scalars=frozenset({value}))
+
+    @classmethod
+    def callable(cls, name: str) -> "AbstractValue":
+        return cls(callables=frozenset({name}))
+
+    @classmethod
+    def type_name(cls, name: str) -> "AbstractValue":
+        return cls(types=frozenset({name}))
+
+    def merge(self, other: "AbstractValue") -> "AbstractValue":
+        scalars = self.scalars | other.scalars
+        callables = self.callables | other.callables
+        types = self.types | other.types
+        overflow = len(scalars) > MAX_STRINGS or len(callables) > MAX_CALLABLES or len(types) > MAX_TYPES
+        if overflow:
+            return AbstractValue.unknown_value()
+        return AbstractValue(scalars, callables, types, self.unknown or other.unknown)
+
+    def strings(self) -> frozenset[str]:
+        return frozenset(value for value in self.scalars if isinstance(value, str))
+
+
+@dataclass
+class AbstractState:
+    values: dict[str, AbstractValue] = field(default_factory=dict)
+    functions: dict[str, tuple[tuple[str, ...], str]] = field(default_factory=dict)
+
+    def assign(self, name: str, value: AbstractValue) -> None:
+        self.values[name] = value
+
+    def get(self, name: str) -> AbstractValue:
+        return self.values.get(name, AbstractValue.unknown_value())
+
+    def analyze(
+        self,
+        source: str,
+        *,
+        callable_names: Iterable[str] = (),
+        type_names: Iterable[str] = (),
+        callable_aliases: Mapping[str, str] | None = None,
+        type_aliases: Mapping[str, str] | None = None,
+    ) -> "AbstractState":
+        """Collect bounded constants, aliases, object properties, and wrappers."""
+        for name in callable_names:
+            self.assign(name, AbstractValue.callable(name))
+        for name in type_names:
+            self.assign(name, AbstractValue.type_name(name))
+        for local, remote in (callable_aliases or {}).items():
+            self.assign(local, AbstractValue.callable(remote))
+        for local, remote in (type_aliases or {}).items():
+            self.assign(local, AbstractValue.type_name(remote))
+
+        for match in re.finditer(
+            r"^\s*function\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*"
+            r"\{\s*return\s+(.+)\s*;\s*\}\s*$",
+            source,
+            re.MULTILINE,
+        ):
+            params = tuple(
+                value.strip()
+                for value in match.group(2).split(",")
+                if value.strip()
+            )
+            self.functions[match.group(1)] = (params, match.group(3).rstrip("; "))
+
+        for line in source.splitlines():
+            assignment_match = re.match(
+                r"^\s*(?:(?:const|let|var)\s+)?"
+                r"([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)\s*=\s*(.+?)\s*;?\s*$",
+                line,
+            )
+            if assignment_match is None or "==" in line or "=>" in line:
+                continue
+            name, expression = assignment_match.groups()
+            expression = expression.rstrip("; ")
+            if expression.startswith("{") and expression.endswith("}"):
+                for key, value in re.findall(
+                    r"([A-Za-z_$][\w$]*)\s*:\s*([^,}]+)", expression
+                ):
+                    self.assign(f"{name}.{key}", self.evaluate(value.strip()))
+                continue
+            self.assign(name, self.evaluate(expression))
+        return self
+
+    def evaluate(self, expression: str) -> AbstractValue:
+        """Evaluate Python or JS-like scalar/callable/type expressions."""
+        expression = expression.strip().rstrip(";")
+        python_value = self.evaluate_python(expression)
+        if not python_value.unknown:
+            return python_value
+        return self._eval_text(expression)
+
+    def evaluate_python(self, expression: str | ast.AST) -> AbstractValue:
+        try:
+            node = ast.parse(expression, mode="eval").body if isinstance(expression, str) else expression
+        except SyntaxError:
+            return AbstractValue.unknown_value()
+        return self._eval(node)
+
+    def _eval(self, node: ast.AST) -> AbstractValue:
+        if isinstance(node, ast.Constant) and isinstance(node.value, (str, int, float, bool, type(None))):
+            return AbstractValue.scalar(node.value)
+        if isinstance(node, ast.Name):
+            return self.get(node.id)
+        if isinstance(node, ast.IfExp):
+            return self._eval(node.body).merge(self._eval(node.orelse))
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+            return self._combine_strings(self._eval(node.left).strings(), self._eval(node.right).strings(), "")
+        if isinstance(node, ast.JoinedStr):
+            choices: set[str] = {""}
+            for part in node.values:
+                if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                    values = {part.value}
+                elif isinstance(part, ast.FormattedValue):
+                    values = set(self._eval(part.value).strings())
+                else:
+                    return AbstractValue.unknown_value()
+                choices = {left + right for left in choices for right in values}
+                if len(choices) > MAX_STRINGS:
+                    return AbstractValue.unknown_value()
+            return AbstractValue(scalars=frozenset(choices))
+        if isinstance(node, (ast.Tuple, ast.List, ast.Set)):
+            value = AbstractValue()
+            for item in node.elts:
+                value = value.merge(self._eval(item))
+            return value
+        if isinstance(node, ast.Call):
+            name = self._call_name(node.func)
+            if name in {"str", "os.fspath"} and node.args:
+                return self._eval(node.args[0])
+            if name in {"os.path.join", "pathlib.Path", "Path"}:
+                parts = [self._eval(arg).strings() for arg in node.args]
+                if not parts or any(not part for part in parts):
+                    return AbstractValue.unknown_value()
+                path_values: set[str] = {""}
+                for path_part in parts:
+                    path_values = {
+                        os.path.join(left, right) if left else right
+                        for left in path_values
+                        for right in path_part
+                    }
+                    if len(path_values) > MAX_STRINGS:
+                        return AbstractValue.unknown_value()
+                return AbstractValue(scalars=frozenset(value.replace("\\", "/") for value in path_values))
+        return AbstractValue.unknown_value()
+
+    def _eval_text(self, expression: str) -> AbstractValue:
+        expression = expression.strip().rstrip(";")
+        while expression.startswith("(") and expression.endswith(")"):
+            expression = expression[1:-1].strip()
+        if not expression:
+            return AbstractValue.unknown_value()
+        if re.fullmatch(r"[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*", expression):
+            return self.get(expression)
+        if (
+            len(expression) >= 2
+            and expression[0] == expression[-1]
+            and expression[0] in {"'", '"'}
+        ):
+            try:
+                return AbstractValue.scalar(ast.literal_eval(expression))
+            except (SyntaxError, ValueError):
+                return AbstractValue.unknown_value()
+        if expression.startswith("`") and expression.endswith("`"):
+            values = {expression[1:-1]}
+            for nested in re.findall(r"\$\{([^}]+)\}", expression):
+                replacements = self.evaluate(nested).strings()
+                if not replacements:
+                    return AbstractValue.unknown_value()
+                values = {
+                    value.replace(f"${{{nested}}}", replacement)
+                    for value in values
+                    for replacement in replacements
+                }
+                if len(values) > MAX_STRINGS:
+                    return AbstractValue.unknown_value()
+            return AbstractValue(scalars=frozenset(values))
+        conditional = re.match(r"^.+?\?\s*(.+?)\s*:\s*(.+)$", expression)
+        if conditional is not None:
+            return self.evaluate(conditional.group(1)).merge(
+                self.evaluate(conditional.group(2))
+            )
+        parts = self._split_top_level(expression, "+")
+        if len(parts) > 1:
+            value = self.evaluate(parts[0])
+            for part in parts[1:]:
+                value = self._combine_strings(
+                    value.strings(), self.evaluate(part).strings(), ""
+                )
+            return value
+        if expression.startswith("[") and expression.endswith("]"):
+            value = AbstractValue()
+            for part in self._split_top_level(expression[1:-1], ","):
+                value = value.merge(self.evaluate(part))
+            return value
+        call = re.match(r"^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\((.*)\)$", expression)
+        if call is not None:
+            name, raw_args = call.groups()
+            args = [self.evaluate(part) for part in self._split_top_level(raw_args, ",")]
+            if name in {"path.join", "path.resolve", "os.path.join", "Path", "pathlib.Path"}:
+                choices = [arg.strings() for arg in args]
+                if not choices or any(not choice for choice in choices):
+                    return AbstractValue.unknown_value()
+                values = {""}
+                for choice in choices:
+                    values = {
+                        os.path.join(left, right) if left else right
+                        for left in values
+                        for right in choice
+                    }
+                    if len(values) > MAX_STRINGS:
+                        return AbstractValue.unknown_value()
+                return AbstractValue(
+                    scalars=frozenset(value.replace("\\", "/") for value in values)
+                )
+            bound = self.get(name)
+            if bound.types or bound.callables:
+                return bound
+            wrapper = self.functions.get(name)
+            if wrapper is not None:
+                params, body = wrapper
+                previous = {param: self.values.get(param) for param in params}
+                try:
+                    for param, value in zip(params, args):
+                        self.assign(param, value)
+                    return self.evaluate(body)
+                finally:
+                    for param, previous_value in previous.items():
+                        if previous_value is None:
+                            self.values.pop(param, None)
+                        else:
+                            self.values[param] = previous_value
+        return AbstractValue.unknown_value()
+
+    @staticmethod
+    def _split_top_level(expression: str, separator: str) -> list[str]:
+        parts: list[str] = []
+        start = 0
+        depth = 0
+        quote = ""
+        for index, char in enumerate(expression):
+            if quote:
+                if char == quote and (index == 0 or expression[index - 1] != "\\"):
+                    quote = ""
+                continue
+            if char in {"'", '"', "`"}:
+                quote = char
+            elif char in "([{":
+                depth += 1
+            elif char in ")]}":
+                depth = max(0, depth - 1)
+            elif char == separator and depth == 0:
+                parts.append(expression[start:index].strip())
+                start = index + 1
+        parts.append(expression[start:].strip())
+        return [part for part in parts if part]
+
+    @staticmethod
+    def _call_name(node: ast.AST) -> str:
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            prefix = AbstractState._call_name(node.value)
+            return f"{prefix}.{node.attr}" if prefix else node.attr
+        return ""
+
+    @staticmethod
+    def _combine_strings(left: Iterable[str], right: Iterable[str], separator: str) -> AbstractValue:
+        values = {f"{a}{separator}{b}" for a in left for b in right}
+        if not values or len(values) > MAX_STRINGS:
+            return AbstractValue.unknown_value()
+        return AbstractValue(scalars=frozenset(values))

package/src/devcouncil/codeintel/resolution/frameworks/__init__.py

@@ -0,0 +1,33 @@
+"""Manifest for independently testable framework semantic augmenters."""
+
+from devcouncil.codeintel.resolution.frameworks.base import FrameworkSpec
+from devcouncil.codeintel.resolution.frameworks.di import (
+    DI_SPECS,
+    iter_provider_matches,
+)
+from devcouncil.codeintel.resolution.frameworks.events import (
+    EVENT_SPECS,
+    iter_event_matches,
+)
+from devcouncil.codeintel.resolution.frameworks.routes import (
+    COMPUTED_ROUTE_PATTERN,
+    ROUTE_SPECS,
+    iter_route_matches,
+)
+
+FRAMEWORK_MANIFEST: tuple[FrameworkSpec, ...] = (
+    *ROUTE_SPECS,
+    *DI_SPECS,
+    *EVENT_SPECS,
+)
+
+__all__ = [
+    "COMPUTED_ROUTE_PATTERN",
+    "DI_SPECS",
+    "EVENT_SPECS",
+    "FRAMEWORK_MANIFEST",
+    "ROUTE_SPECS",
+    "iter_event_matches",
+    "iter_provider_matches",
+    "iter_route_matches",
+]

package/src/devcouncil/codeintel/resolution/frameworks/base.py

@@ -0,0 +1,46 @@
+"""Shared records for isolated framework semantic augmenters."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Pattern
+
+
+@dataclass(frozen=True)
+class FrameworkSpec:
+    """A framework matcher advertised by the semantic resolver."""
+
+    name: str
+    family: str
+    pattern: Pattern[str]
+
+
+@dataclass(frozen=True)
+class RouteMatch:
+    framework: str
+    verb: str
+    path: str
+    handler_expression: str
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class EventMatch:
+    operation: str
+    event: str
+    callback_expression: str
+    start: int
+
+
+@dataclass(frozen=True)
+class ProviderMatch:
+    framework: str
+    target_expression: str
+    start: int
+
+
+def compile_pattern(pattern: str, *, multiline: bool = False) -> Pattern[str]:
+    flags = re.IGNORECASE | (re.MULTILINE if multiline else 0)
+    return re.compile(pattern, flags)