osscodeiq 0.0.0__py3-none-any.whl

osscodeiq/graph/builder.py

@@ -0,0 +1,297 @@
+"""Graph builder that aggregates detector results and runs cross-file linkers."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from osscodeiq.graph.backend import GraphBackend
+from osscodeiq.graph.store import GraphStore
+from osscodeiq.models.graph import GraphEdge, GraphNode, EdgeKind, NodeKind
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LinkResult:
+    """Result returned by a Linker: new nodes and edges to add to the graph."""
+
+    nodes: list[GraphNode] = field(default_factory=list)
+    edges: list[GraphEdge] = field(default_factory=list)
+
+
+@runtime_checkable
+class Linker(Protocol):
+    """Cross-file relationship inferencer."""
+
+    def link(self, store: GraphStore) -> LinkResult:
+        ...
+
+
+class TopicLinker:
+    """Links Kafka/RabbitMQ producers to consumers via shared topic names.
+
+    Scans for TOPIC/QUEUE nodes and matches PRODUCES edges with CONSUMES
+    edges on the same topic label to create direct producer-to-consumer edges.
+    """
+
+    def link(self, store: GraphStore) -> LinkResult:
+        edges: list[GraphEdge] = []
+
+        # Collect topic/queue nodes by label for matching
+        topic_nodes = store.nodes_by_kind(NodeKind.TOPIC) + store.nodes_by_kind(
+            NodeKind.QUEUE
+        )
+        topic_ids_by_label: dict[str, list[str]] = {}
+        for node in topic_nodes:
+            topic_ids_by_label.setdefault(node.label, []).append(node.id)
+
+        # For each topic label, find producers and consumers
+        produces_edges = store.edges_by_kind(EdgeKind.PRODUCES)
+        consumes_edges = store.edges_by_kind(EdgeKind.CONSUMES)
+
+        # Map topic_id -> list of producer node ids
+        producers_by_topic: dict[str, list[str]] = {}
+        for edge in produces_edges:
+            producers_by_topic.setdefault(edge.target, []).append(edge.source)
+
+        # Map topic_id -> list of consumer node ids
+        consumers_by_topic: dict[str, list[str]] = {}
+        for edge in consumes_edges:
+            consumers_by_topic.setdefault(edge.target, []).append(edge.source)
+
+        # Create CALLS edges from producers to consumers on the same topic
+        for label, topic_ids in topic_ids_by_label.items():
+            producers: set[str] = set()
+            consumers: set[str] = set()
+            for tid in topic_ids:
+                producers.update(producers_by_topic.get(tid, []))
+                consumers.update(consumers_by_topic.get(tid, []))
+
+            for prod in sorted(producers):
+                for cons in sorted(consumers):
+                    if prod != cons:
+                        edges.append(
+                            GraphEdge(
+                                source=prod,
+                                target=cons,
+                                kind=EdgeKind.CALLS,
+                                label=f"via topic '{label}'",
+                                properties={"inferred": True, "topic": label},
+                            )
+                        )
+
+        if edges:
+            logger.debug("TopicLinker created %d edges", len(edges))
+        return LinkResult(edges=edges)
+
+
+class EntityLinker:
+    """Links JPA entities to repositories that query them.
+
+    Scans for ENTITY and REPOSITORY nodes and creates QUERIES edges
+    from repositories to the entities they manage, matching by naming
+    conventions and existing MAPS_TO relationships.
+    """
+
+    def link(self, store: GraphStore) -> LinkResult:
+        edges: list[GraphEdge] = []
+
+        entities = store.nodes_by_kind(NodeKind.ENTITY)
+        repositories = store.nodes_by_kind(NodeKind.REPOSITORY)
+
+        if not entities or not repositories:
+            return LinkResult(edges=edges)
+
+        # Build entity lookup by simple name (last part of FQN or label)
+        entity_by_name: dict[str, GraphNode] = {}
+        for entity in entities:
+            # Use label as the simple class name
+            entity_by_name[entity.label.lower()] = entity
+            if entity.fqn:
+                simple = entity.fqn.rsplit(".", 1)[-1]
+                entity_by_name[simple.lower()] = entity
+
+        # Check existing QUERIES edges to avoid duplicates
+        existing_queries = {
+            (e.source, e.target) for e in store.edges_by_kind(EdgeKind.QUERIES)
+        }
+
+        for repo in repositories:
+            # Try to match repository name to entity name
+            # Convention: FooRepository -> Foo entity
+            repo_name = repo.label
+            for suffix in ("Repository", "Repo", "Dao", "DAO"):
+                if repo_name.endswith(suffix):
+                    entity_name = repo_name[: -len(suffix)].lower()
+                    if entity_name in entity_by_name:
+                        entity = entity_by_name[entity_name]
+                        if (repo.id, entity.id) not in existing_queries:
+                            edges.append(
+                                GraphEdge(
+                                    source=repo.id,
+                                    target=entity.id,
+                                    kind=EdgeKind.QUERIES,
+                                    label=f"{repo.label} queries {entity.label}",
+                                    properties={"inferred": True},
+                                )
+                            )
+                    break
+
+        if edges:
+            logger.debug("EntityLinker created %d edges", len(edges))
+        return LinkResult(edges=edges)
+
+
+class ModuleContainmentLinker:
+    """Links classes to their owning modules via CONTAINS edges.
+
+    Groups nodes by their ``module`` field and creates MODULE nodes
+    with CONTAINS edges pointing to each member node.
+    """
+
+    def link(self, store: GraphStore) -> LinkResult:
+        edges: list[GraphEdge] = []
+        new_nodes: list[GraphNode] = []
+
+        # Collect existing module nodes
+        existing_modules = {n.id for n in store.nodes_by_kind(NodeKind.MODULE)}
+
+        # Group nodes by module name
+        nodes_by_module: dict[str, list[GraphNode]] = {}
+        for node in store.all_nodes():
+            if node.module and node.kind != NodeKind.MODULE:
+                nodes_by_module.setdefault(node.module, []).append(node)
+
+        # Check existing CONTAINS edges to avoid duplicates
+        existing_contains = {
+            (e.source, e.target) for e in store.edges_by_kind(EdgeKind.CONTAINS)
+        }
+
+        for module_name, members in nodes_by_module.items():
+            module_id = f"module:{module_name}"
+
+            # Create module node if it doesn't exist
+            if module_id not in existing_modules:
+                new_nodes.append(
+                    GraphNode(
+                        id=module_id,
+                        kind=NodeKind.MODULE,
+                        label=module_name,
+                        fqn=module_name,
+                    )
+                )
+
+            for member in members:
+                if (module_id, member.id) not in existing_contains:
+                    edges.append(
+                        GraphEdge(
+                            source=module_id,
+                            target=member.id,
+                            kind=EdgeKind.CONTAINS,
+                            label=f"{module_name} contains {member.label}",
+                            properties={"inferred": True},
+                        )
+                    )
+
+        if edges:
+            logger.debug("ModuleContainmentLinker created %d edges", len(edges))
+        return LinkResult(nodes=new_nodes, edges=edges)
+
+
+class GraphBuilder:
+    """Aggregates detector results and runs cross-file linkers to build a graph.
+
+    Edges are buffered and flushed after all nodes are added to ensure
+    consistent behavior across all storage backends. Some backends
+    (NetworkX, SQLite, KuzuDB) reject edges referencing non-existent
+    nodes, so all nodes must be present before edges are inserted.
+    """
+
+    def __init__(self, backend: GraphBackend | None = None) -> None:
+        self._store = GraphStore(backend=backend)
+        self._pending_nodes: list[GraphNode] = []
+        self._pending_edges: list[GraphEdge] = []
+        self._linkers: list[Linker] = [
+            TopicLinker(),
+            EntityLinker(),
+            ModuleContainmentLinker(),
+        ]
+
+    def add_nodes(self, nodes: list[GraphNode]) -> None:
+        """Buffer nodes for deferred insertion."""
+        self._pending_nodes.extend(nodes)
+
+    def add_edges(self, edges: list[GraphEdge]) -> None:
+        """Buffer edges for deferred insertion."""
+        self._pending_edges.extend(edges)
+
+    def flush(self) -> None:
+        """Insert all buffered nodes then edges into the store.
+
+        Nodes first, then edges — ensures backends that validate node
+        existence won't reject valid cross-file edges. Uses bulk insert
+        when the backend supports it (e.g. KuzuDB CSV COPY FROM).
+        """
+        backend = self._store._backend
+
+        # Flush nodes
+        if self._pending_nodes:
+            if hasattr(backend, "bulk_add_nodes"):
+                backend.bulk_add_nodes(self._pending_nodes)
+            else:
+                for node in self._pending_nodes:
+                    self._store.add_node(node)
+            self._pending_nodes.clear()
+
+        # Flush edges
+        if self._pending_edges:
+            if hasattr(backend, "bulk_add_edges"):
+                backend.bulk_add_edges(self._pending_edges)
+            else:
+                for edge in self._pending_edges:
+                    self._store.add_edge(edge)
+            self._pending_edges.clear()
+
+    def merge_detector_result(self, result: object) -> None:
+        """Merge a DetectorResult into the graph.
+
+        Accepts any object with ``nodes`` and ``edges`` attributes
+        (duck-typed to avoid circular imports with DetectorResult).
+        """
+        nodes: list[GraphNode] = getattr(result, "nodes", [])
+        edges: list[GraphEdge] = getattr(result, "edges", [])
+        self.add_nodes(nodes)
+        self.add_edges(edges)  # buffered, not inserted yet
+
+    def run_linkers(self) -> None:
+        """Flush pending nodes and edges, then run all registered linkers."""
+        # Flush all buffered detector data so linkers see the full graph
+        self.flush()
+
+        for linker in self._linkers:
+            try:
+                result = linker.link(self._store)
+
+                if result.nodes:
+                    self.add_nodes(result.nodes)
+
+                if result.edges:
+                    self._pending_edges.extend(result.edges)
+            except Exception:
+                logger.warning(
+                    "Linker %s failed",
+                    type(linker).__name__,
+                    exc_info=True,
+                )
+
+        # Flush linker-produced nodes and edges
+        self.flush()
+
+    def build(self) -> GraphStore:
+        """Return the assembled graph store."""
+        # Safety: flush any remaining edges
+        if self._pending_edges:
+            self.flush()
+        return self._store

osscodeiq/graph/query.py

@@ -0,0 +1,228 @@
+"""Composable query builder for the OSSCodeIQ graph."""
+
+from __future__ import annotations
+
+import fnmatch
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from osscodeiq.graph.store import GraphStore
+from osscodeiq.models.graph import (
+    EdgeKind,
+    GraphEdge,
+    GraphNode,
+    NodeKind,
+)
+
+
+@dataclass(frozen=True)
+class _FocusSpec:
+    """Describes a neighbourhood-focus operation."""
+
+    node_id: str
+    hops: int
+    direction: str
+
+
+@dataclass(frozen=True)
+class GraphQuery:
+    """Immutable, composable query builder over a :class:`GraphStore`.
+
+    Every filter method returns a **new** ``GraphQuery``; the original
+    is never mutated.  Call :meth:`execute` to materialise the result
+    as a new :class:`GraphStore`.
+    """
+
+    _store: GraphStore
+    _module_filters: tuple[list[str], ...] = ()
+    _node_kind_filters: tuple[list[NodeKind], ...] = ()
+    _edge_kind_filters: tuple[list[EdgeKind], ...] = ()
+    _path_filters: tuple[str, ...] = ()
+    _annotation_filters: tuple[str, ...] = ()
+    _focus_specs: tuple[_FocusSpec, ...] = ()
+    _node_predicates: tuple[Callable[[GraphNode], bool], ...] = ()
+    _edge_predicates: tuple[Callable[[GraphEdge], bool], ...] = ()
+
+    # -- convenience constructor ------------------------------------
+
+    def __init__(self, store: GraphStore) -> None:  # noqa: D107
+        object.__setattr__(self, "_store", store)
+        object.__setattr__(self, "_module_filters", ())
+        object.__setattr__(self, "_node_kind_filters", ())
+        object.__setattr__(self, "_edge_kind_filters", ())
+        object.__setattr__(self, "_path_filters", ())
+        object.__setattr__(self, "_annotation_filters", ())
+        object.__setattr__(self, "_focus_specs", ())
+        object.__setattr__(self, "_node_predicates", ())
+        object.__setattr__(self, "_edge_predicates", ())
+
+    def _copy(self, **overrides: object) -> GraphQuery:
+        """Return a shallow copy with selected field overrides."""
+        new = object.__new__(GraphQuery)
+        for attr in (
+            "_store",
+            "_module_filters",
+            "_node_kind_filters",
+            "_edge_kind_filters",
+            "_path_filters",
+            "_annotation_filters",
+            "_focus_specs",
+            "_node_predicates",
+            "_edge_predicates",
+        ):
+            object.__setattr__(new, attr, overrides.get(attr, getattr(self, attr)))
+        return new
+
+    # -- filter methods (each returns a new GraphQuery) -------------
+
+    def filter_modules(self, modules: list[str]) -> GraphQuery:
+        """Keep only nodes belonging to one of the listed modules."""
+        return self._copy(_module_filters=self._module_filters + (modules,))
+
+    def filter_node_kinds(self, kinds: list[NodeKind]) -> GraphQuery:
+        """Keep only nodes whose kind is in *kinds*."""
+        return self._copy(_node_kind_filters=self._node_kind_filters + (kinds,))
+
+    def filter_edge_kinds(self, kinds: list[EdgeKind]) -> GraphQuery:
+        """Keep only edges whose kind is in *kinds*."""
+        return self._copy(_edge_kind_filters=self._edge_kind_filters + (kinds,))
+
+    def filter_path(self, glob_pattern: str) -> GraphQuery:
+        """Keep only nodes whose source file path matches *glob_pattern*."""
+        return self._copy(_path_filters=self._path_filters + (glob_pattern,))
+
+    def filter_annotation(self, annotation: str) -> GraphQuery:
+        """Keep only nodes that carry *annotation*."""
+        return self._copy(_annotation_filters=self._annotation_filters + (annotation,))
+
+    def focus(self, node_id: str, hops: int = 2, direction: str = "both") -> GraphQuery:
+        """Restrict to the *hops*-neighbourhood around *node_id*."""
+        spec = _FocusSpec(node_id=node_id, hops=hops, direction=direction)
+        return self._copy(_focus_specs=self._focus_specs + (spec,))
+
+    # -- semantic queries -------------------------------------------
+
+    def consumers_of(self, target_id: str) -> GraphQuery:
+        """Find nodes that consume from *target_id*."""
+        def _pred(edge: GraphEdge) -> bool:
+            return edge.target == target_id and edge.kind in {
+                EdgeKind.CONSUMES,
+                EdgeKind.LISTENS,
+            }
+        return self._copy(_edge_predicates=self._edge_predicates + (_pred,))
+
+    def producers_of(self, target_id: str) -> GraphQuery:
+        """Find nodes that produce to *target_id*."""
+        def _pred(edge: GraphEdge) -> bool:
+            return edge.target == target_id and edge.kind in {
+                EdgeKind.PRODUCES,
+                EdgeKind.PUBLISHES,
+            }
+        return self._copy(_edge_predicates=self._edge_predicates + (_pred,))
+
+    def callers_of(self, target_id: str) -> GraphQuery:
+        """Find nodes that call *target_id*."""
+        def _pred(edge: GraphEdge) -> bool:
+            return edge.target == target_id and edge.kind == EdgeKind.CALLS
+        return self._copy(_edge_predicates=self._edge_predicates + (_pred,))
+
+    def dependencies_of(self, module_id: str) -> GraphQuery:
+        """Find modules that *module_id* depends on."""
+        def _pred(edge: GraphEdge) -> bool:
+            return edge.source == module_id and edge.kind in {
+                EdgeKind.DEPENDS_ON,
+                EdgeKind.IMPORTS,
+                EdgeKind.CALLS,
+                EdgeKind.INJECTS,
+            }
+        return self._copy(_edge_predicates=self._edge_predicates + (_pred,))
+
+    def dependents_of(self, module_id: str) -> GraphQuery:
+        """Find modules that depend on *module_id*."""
+        def _pred(edge: GraphEdge) -> bool:
+            return edge.target == module_id and edge.kind in {
+                EdgeKind.DEPENDS_ON,
+                EdgeKind.IMPORTS,
+                EdgeKind.CALLS,
+                EdgeKind.INJECTS,
+            }
+        return self._copy(_edge_predicates=self._edge_predicates + (_pred,))
+
+    # -- execution --------------------------------------------------
+
+    def execute(self) -> GraphStore:
+        """Apply all accumulated filters and return a new :class:`GraphStore`."""
+        store = self._store
+
+        # 1. Apply focus specs first (they restrict the working set)
+        if self._focus_specs:
+            focused_ids: set[str] = set()
+            for spec in self._focus_specs:
+                ego_store = store.ego(spec.node_id, spec.hops)
+                focused_ids.update(n.id for n in ego_store.all_nodes())
+            store = store.subgraph(focused_ids)
+
+        # 2. Build composite node filter
+        def _node_ok(node: GraphNode) -> bool:
+            # Module filters (OR within a single call, AND across calls)
+            for mod_list in self._module_filters:
+                if node.module not in mod_list and node.id not in mod_list:
+                    return False
+
+            # Node-kind filters
+            for kind_list in self._node_kind_filters:
+                if node.kind not in kind_list:
+                    return False
+
+            # Path filters (any pattern match)
+            if self._path_filters:
+                loc = node.location
+                if loc is None:
+                    return False
+                if not any(fnmatch.fnmatch(loc.file_path, p) for p in self._path_filters):
+                    return False
+
+            # Annotation filters (all must be present)
+            for ann in self._annotation_filters:
+                if ann not in node.annotations:
+                    return False
+
+            # Custom node predicates
+            for pred in self._node_predicates:
+                if not pred(node):
+                    return False
+
+            return True
+
+        # 3. Build composite edge filter
+        def _edge_ok(edge: GraphEdge) -> bool:
+            for kind_list in self._edge_kind_filters:
+                if edge.kind not in kind_list:
+                    return False
+            # Edge predicates are OR-combined: if any are set, at least
+            # one must match.  This allows semantic queries to union.
+            if self._edge_predicates:
+                if not any(pred(edge) for pred in self._edge_predicates):
+                    return False
+            return True
+
+        # When we have edge predicates but no node filters, we should
+        # also include nodes referenced by matching edges.
+        if self._edge_predicates and not (
+            self._module_filters
+            or self._node_kind_filters
+            or self._path_filters
+            or self._annotation_filters
+            or self._node_predicates
+        ):
+            # Collect node IDs from matching edges
+            keep_ids: set[str] = set()
+            for edge in store.all_edges():
+                if _edge_ok(edge):
+                    keep_ids.add(edge.source)
+                    keep_ids.add(edge.target)
+            store = store.subgraph(keep_ids)
+            # Re-filter edges only
+            return store.filter(edge_filter=_edge_ok)
+
+        return store.filter(node_filter=_node_ok, edge_filter=_edge_ok)