@pmaddire/gcie 0.1.2

package/embeddings/faiss_index.py

@@ -0,0 +1,72 @@
+"""FAISS-compatible vector index with in-memory fallback."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SearchHit:
+    idx: int
+    score: float
+
+
+def _dot(a: list[float], b: list[float]) -> float:
+    return sum(x * y for x, y in zip(a, b))
+
+
+class VectorIndex:
+    """Vector index that prefers FAISS and falls back to brute-force cosine."""
+
+    def __init__(self) -> None:
+        self._faiss = None
+        self._index = None
+        self._vectors: list[list[float]] = []
+
+        try:
+            import faiss  # type: ignore
+
+            self._faiss = faiss
+        except Exception:
+            self._faiss = None
+
+    def add(self, vectors: list[list[float]]) -> None:
+        if not vectors:
+            return
+
+        if self._faiss is None:
+            self._vectors.extend(vectors)
+            return
+
+        import numpy as np
+
+        arr = np.array(vectors, dtype="float32")
+        if self._index is None:
+            dim = arr.shape[1]
+            self._index = self._faiss.IndexFlatIP(dim)
+        self._index.add(arr)
+
+    def search(self, query: list[float], top_k: int = 5) -> tuple[SearchHit, ...]:
+        if top_k <= 0:
+            return ()
+
+        if self._faiss is None:
+            scored = [SearchHit(idx=i, score=_dot(query, vec)) for i, vec in enumerate(self._vectors)]
+            scored.sort(key=lambda h: h.score, reverse=True)
+            return tuple(scored[:top_k])
+
+        import numpy as np
+
+        if self._index is None or self._index.ntotal == 0:
+            return ()
+
+        q = np.array([query], dtype="float32")
+        scores, indices = self._index.search(q, top_k)
+
+        hits: list[SearchHit] = []
+        for score, idx in zip(scores[0], indices[0]):
+            if idx < 0:
+                continue
+            hits.append(SearchHit(idx=int(idx), score=float(score)))
+        return tuple(hits)

package/git_integration/__init__.py

@@ -0,0 +1 @@
+"""Git integration package."""

package/git_integration/git_miner.py

@@ -0,0 +1,78 @@
+"""Git history miner using GitPython."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from git import Repo
+from git.exc import GitCommandError
+
+
+@dataclass(frozen=True, slots=True)
+class FileChange:
+    """Single file-level change in a commit."""
+
+    path: str
+    change_type: str
+
+
+@dataclass(frozen=True, slots=True)
+class CommitRecord:
+    """Normalized commit metadata."""
+
+    hexsha: str
+    author: str
+    committed_date: int
+    summary: str
+    files: tuple[FileChange, ...]
+
+
+def mine_commit_history(repo_path: str | Path, *, max_count: int | None = None) -> tuple[CommitRecord, ...]:
+    """Return normalized commit history from a git repository."""
+    repo = Repo(Path(repo_path))
+    if repo.bare:
+        repo.close()
+        return ()
+
+    try:
+        try:
+            commits = list(repo.iter_commits("HEAD", max_count=max_count))
+        except (ValueError, GitCommandError):
+            # No commits/HEAD yet.
+            return ()
+
+        out: list[CommitRecord] = []
+
+        for commit in commits:
+            file_changes: list[FileChange] = []
+
+            if commit.parents:
+                parent = commit.parents[0]
+                diffs = parent.diff(commit, create_patch=False)
+                for diff in diffs:
+                    new_path = diff.b_path or diff.a_path or ""
+                    file_changes.append(
+                        FileChange(
+                            path=new_path,
+                            change_type=(diff.change_type or "M").upper(),
+                        )
+                    )
+            else:
+                for path in commit.stats.files.keys():
+                    file_changes.append(FileChange(path=path, change_type="A"))
+
+            out.append(
+                CommitRecord(
+                    hexsha=commit.hexsha,
+                    author=str(commit.author),
+                    committed_date=int(commit.committed_date),
+                    summary=commit.summary,
+                    files=tuple(file_changes),
+                )
+            )
+
+        return tuple(out)
+    finally:
+        repo.git.clear_cache()
+        repo.close()

package/graphs/__init__.py

@@ -0,0 +1,17 @@
+"""Graph package for GCIE."""
+
+from .call_graph import build_call_graph
+from .code_graph import build_code_structure_graph
+from .execution_graph import build_execution_graph
+from .git_graph import build_git_graph
+from .test_graph import build_test_coverage_graph
+from .variable_graph import build_variable_graph
+
+__all__ = [
+    "build_call_graph",
+    "build_code_structure_graph",
+    "build_execution_graph",
+    "build_git_graph",
+    "build_test_coverage_graph",
+    "build_variable_graph",
+]

package/graphs/call_graph.py

@@ -0,0 +1,70 @@
+"""Call graph builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import networkx as nx
+
+from parser.call_resolver import resolve_calls
+from parser.models import ModuleParseResult
+
+from .node_factory import function_node_id
+
+
+def _normalize_path(file_path: Path, root: Path | None) -> Path:
+    if root is None:
+        return file_path
+    try:
+        return file_path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return file_path
+
+
+def build_call_graph(modules: Iterable[ModuleParseResult], *, root: Path | None = None) -> nx.DiGraph:
+    """Build caller-callee graph with unresolved external call nodes preserved."""
+    graph = nx.DiGraph()
+
+    module_list = list(modules)
+    for module in module_list:
+        rel_file = _normalize_path(module.file, root)
+        for fn in module.functions:
+            node_id = function_node_id(rel_file, fn.name)
+            graph.add_node(
+                node_id,
+                type="function",
+                label=fn.name,
+                file=rel_file.as_posix(),
+                qualified_name=f"{rel_file.as_posix()}::{fn.name}",
+            )
+
+    local_name_to_node: dict[tuple[str, str], str] = {}
+    for module in module_list:
+        rel_file = _normalize_path(module.file, root)
+        for fn in module.functions:
+            local_name_to_node[(rel_file.as_posix(), fn.name)] = function_node_id(rel_file, fn.name)
+
+    for module in module_list:
+        rel_file = _normalize_path(module.file, root)
+        for resolved in resolve_calls(module):
+            caller_id = local_name_to_node[(rel_file.as_posix(), resolved.caller)]
+
+            if resolved.resolved:
+                callee_id = local_name_to_node.get((rel_file.as_posix(), resolved.callee))
+                if callee_id is None:
+                    # Should not happen for local resolution, but keep graph robust.
+                    callee_id = f"external:{resolved.callee}"
+                    graph.add_node(callee_id, type="external_function", label=resolved.callee)
+            else:
+                callee_id = f"external:{resolved.callee}"
+                graph.add_node(callee_id, type="external_function", label=resolved.callee)
+
+            graph.add_edge(
+                caller_id,
+                callee_id,
+                type="CALLS",
+                resolved=resolved.resolved,
+            )
+
+    return graph

package/graphs/code_graph.py

@@ -0,0 +1,81 @@
+"""Code structure graph builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import networkx as nx
+
+from parser.models import ModuleParseResult
+
+from .node_factory import (
+    class_node_id,
+    file_node_id,
+    function_node_id,
+    module_node_id,
+)
+
+
+def _normalize_path(file_path: Path, root: Path | None) -> Path:
+    if root is None:
+        return file_path
+    try:
+        return file_path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return file_path
+
+
+def build_code_structure_graph(
+    modules: Iterable[ModuleParseResult],
+    *,
+    root: Path | None = None,
+) -> nx.DiGraph:
+    """Build file/class/function/import structural graph from parsed modules."""
+    graph = nx.DiGraph()
+
+    for module in modules:
+        rel_file = _normalize_path(module.file, root)
+        file_id = file_node_id(rel_file)
+        graph.add_node(
+            file_id,
+            type="file",
+            label=rel_file.as_posix(),
+            path=rel_file.as_posix(),
+        )
+
+        for cls in module.classes:
+            class_id = class_node_id(rel_file, cls.name)
+            graph.add_node(
+                class_id,
+                type="class",
+                label=cls.name,
+                file=rel_file.as_posix(),
+                start_line=cls.start_line,
+                end_line=cls.end_line,
+            )
+            graph.add_edge(file_id, class_id, type="DEFINES")
+            graph.add_edge(file_id, class_id, type="CONTAINS")
+
+        for fn in module.functions:
+            function_id = function_node_id(rel_file, fn.name)
+            graph.add_node(
+                function_id,
+                type="function",
+                label=fn.name,
+                file=rel_file.as_posix(),
+                start_line=fn.start_line,
+                end_line=fn.end_line,
+            )
+            graph.add_edge(file_id, function_id, type="DEFINES")
+            graph.add_edge(file_id, function_id, type="CONTAINS")
+
+        for imp in module.imports:
+            import_targets = imp.names if imp.names else ((imp.module,) if imp.module else ())
+            for symbol in import_targets:
+                module_name = f"{imp.module}.{symbol}" if imp.module else symbol
+                module_id = module_node_id(module_name)
+                graph.add_node(module_id, type="module", label=module_name)
+                graph.add_edge(file_id, module_id, type="IMPORTS")
+
+    return graph

package/graphs/execution_graph.py

@@ -0,0 +1,35 @@
+"""Execution trace graph builder."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import networkx as nx
+
+from tracing.runtime_tracer import TraceEvent
+
+
+def build_execution_graph(events: Iterable[TraceEvent]) -> nx.DiGraph:
+    """Build ordered runtime execution graph from trace events."""
+    graph = nx.DiGraph()
+    ordered = list(events)
+
+    for idx, event in enumerate(ordered):
+        node_id = f"event:{idx}:{event.function_name}:{event.event}"
+        graph.add_node(
+            node_id,
+            type="execution_event",
+            label=f"{event.function_name}:{event.event}",
+            function=event.function_name,
+            event=event.event,
+            file=event.file_path,
+            line=event.line_no,
+            timestamp=event.timestamp,
+            order=idx,
+        )
+
+        if idx > 0:
+            prev = f"event:{idx - 1}:{ordered[idx - 1].function_name}:{ordered[idx - 1].event}"
+            graph.add_edge(prev, node_id, type="EXECUTES")
+
+    return graph

package/graphs/git_graph.py

@@ -0,0 +1,43 @@
+"""Git history graph builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import networkx as nx
+
+from git_integration.git_miner import CommitRecord
+
+
+def _commit_node_id(hexsha: str) -> str:
+    return f"commit:{hexsha}"
+
+
+def _file_node_id(path: str) -> str:
+    return f"file:{Path(path).as_posix()}"
+
+
+def build_git_graph(records: Iterable[CommitRecord]) -> nx.DiGraph:
+    """Build commit-file change graph using CHANGED_IN edges."""
+    graph = nx.DiGraph()
+
+    for record in records:
+        commit_id = _commit_node_id(record.hexsha)
+        graph.add_node(
+            commit_id,
+            type="commit",
+            label=record.hexsha[:10],
+            author=record.author,
+            committed_date=record.committed_date,
+            summary=record.summary,
+        )
+
+        for change in record.files:
+            if not change.path:
+                continue
+            file_id = _file_node_id(change.path)
+            graph.add_node(file_id, type="file", label=Path(change.path).as_posix(), path=Path(change.path).as_posix())
+            graph.add_edge(file_id, commit_id, type="CHANGED_IN", change_type=change.change_type)
+
+    return graph

package/graphs/graph_store.py

@@ -0,0 +1,25 @@
+"""Graph storage utilities for incremental workflows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import networkx as nx
+
+
+@dataclass(slots=True)
+class GraphStore:
+    _snapshots: dict[str, nx.DiGraph]
+
+    def __init__(self) -> None:
+        self._snapshots = {}
+
+    def put(self, key: str, graph: nx.DiGraph) -> None:
+        self._snapshots[key] = graph.copy()
+
+    def get(self, key: str) -> nx.DiGraph | None:
+        graph = self._snapshots.get(key)
+        return None if graph is None else graph.copy()
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(sorted(self._snapshots.keys()))

package/graphs/node_factory.py

@@ -0,0 +1,21 @@
+"""Node identity and attribute helpers for graph construction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def file_node_id(path: Path) -> str:
+    return f"file:{path.as_posix()}"
+
+
+def class_node_id(file_path: Path, class_name: str) -> str:
+    return f"class:{file_path.as_posix()}::{class_name}"
+
+
+def function_node_id(file_path: Path, function_name: str) -> str:
+    return f"function:{file_path.as_posix()}::{function_name}"
+
+
+def module_node_id(module_name: str) -> str:
+    return f"module:{module_name}"

package/graphs/test_graph.py

@@ -0,0 +1,65 @@
+"""Test coverage graph builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import networkx as nx
+
+from coverage_integration.coverage_loader import CoverageReport
+from parser.models import ModuleParseResult
+
+
+def _test_node_id(test_name: str) -> str:
+    return f"test:{test_name}"
+
+
+def _file_node_id(path: str) -> str:
+    return f"file:{Path(path).as_posix()}"
+
+
+def _function_node_id(path: str, fn_name: str) -> str:
+    return f"function:{Path(path).as_posix()}::{fn_name}"
+
+
+def build_test_coverage_graph(
+    report: CoverageReport,
+    *,
+    test_name: str,
+    parsed_modules: Iterable[ModuleParseResult] = (),
+) -> nx.DiGraph:
+    """Build coverage graph linking tests to covered files/functions."""
+    graph = nx.DiGraph()
+
+    test_id = _test_node_id(test_name)
+    graph.add_node(test_id, type="test", label=test_name)
+
+    module_map = {Path(m.file).as_posix(): m for m in parsed_modules}
+
+    for rec in report.files:
+        file_id = _file_node_id(rec.path)
+        graph.add_node(
+            file_id,
+            type="file",
+            label=rec.path,
+            coverage_percent=rec.percent_covered,
+            num_statements=rec.num_statements,
+            num_branches=rec.num_branches,
+            num_partial_branches=rec.num_partial_branches,
+        )
+        graph.add_edge(test_id, file_id, type="COVERED_BY")
+
+        mod = module_map.get(rec.path)
+        if mod is None:
+            continue
+
+        executed = set(rec.executed_lines)
+        for fn in mod.functions:
+            line_span = set(range(fn.start_line, fn.end_line + 1))
+            if executed.intersection(line_span):
+                fn_id = _function_node_id(rec.path, fn.name)
+                graph.add_node(fn_id, type="function", label=fn.name, file=rec.path)
+                graph.add_edge(test_id, fn_id, type="COVERED_BY")
+
+    return graph

package/graphs/validators.py

@@ -0,0 +1,28 @@
+"""Graph validation helpers."""
+
+from __future__ import annotations
+
+import networkx as nx
+
+
+REQUIRED_NODE_ATTRS = {"type", "label"}
+
+
+def validate_graph_integrity(graph: nx.DiGraph) -> list[str]:
+    """Return a list of graph integrity errors, empty when valid."""
+    errors: list[str] = []
+
+    for node, attrs in graph.nodes(data=True):
+        missing = REQUIRED_NODE_ATTRS.difference(attrs.keys())
+        if missing:
+            errors.append(f"node {node} missing attrs: {', '.join(sorted(missing))}")
+
+    for source, target, attrs in graph.edges(data=True):
+        if source not in graph.nodes:
+            errors.append(f"edge source missing: {source}")
+        if target not in graph.nodes:
+            errors.append(f"edge target missing: {target}")
+        if "type" not in attrs:
+            errors.append(f"edge {source}->{target} missing type")
+
+    return errors

package/graphs/variable_graph.py

@@ -0,0 +1,51 @@
+"""Variable dependency graph builder."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import networkx as nx
+
+from parser.models import ModuleParseResult
+from parser.variable_extractor import extract_variable_dependencies
+
+from .node_factory import function_node_id
+
+
+def _normalize_path(file_path: Path, root: Path | None) -> Path:
+    if root is None:
+        return file_path
+    try:
+        return file_path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return file_path
+
+
+def _variable_node_id(name: str) -> str:
+    return f"variable:{name}"
+
+
+def build_variable_graph(modules: Iterable[ModuleParseResult], *, root: Path | None = None) -> nx.DiGraph:
+    """Build function-variable dependency graph with READS/WRITES/MODIFIES edges."""
+    graph = nx.DiGraph()
+
+    for module in modules:
+        rel_file = _normalize_path(module.file, root)
+
+        for fn in module.functions:
+            fn_id = function_node_id(rel_file, fn.name)
+            graph.add_node(
+                fn_id,
+                type="function",
+                label=fn.name,
+                file=rel_file.as_posix(),
+            )
+
+        for dep in extract_variable_dependencies(module):
+            fn_id = function_node_id(rel_file, dep.function_name)
+            var_id = _variable_node_id(dep.variable_name)
+            graph.add_node(var_id, type="variable", label=dep.variable_name)
+            graph.add_edge(fn_id, var_id, type=dep.access_type)
+
+    return graph

package/knowledge_index/__init__.py

@@ -0,0 +1 @@
+"""Knowledge index package."""

package/knowledge_index/index_builder.py

@@ -0,0 +1,60 @@
+"""Build knowledge index from parsed modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from parser.models import ModuleParseResult
+
+from .models import ClassIndexEntry, FileIndexEntry, FunctionIndexEntry
+from .store import InMemoryKnowledgeStore
+
+
+def build_knowledge_index(modules: Iterable[ModuleParseResult]) -> InMemoryKnowledgeStore:
+    """Build in-memory knowledge index from parse outputs."""
+    store = InMemoryKnowledgeStore()
+
+    for module in modules:
+        file_path = Path(module.file).as_posix()
+        imports = tuple(sorted({
+            f"{imp.module}.{name}" if imp.module else name
+            for imp in module.imports
+            for name in (imp.names or ())
+        }))
+
+        file_entry = FileIndexEntry(
+            path=file_path,
+            imports=imports,
+            classes_defined=tuple(sorted(cls.name for cls in module.classes)),
+            functions_defined=tuple(sorted(fn.name for fn in module.functions)),
+        )
+        store.add_file(file_entry)
+
+        for cls in module.classes:
+            store.add_class(
+                ClassIndexEntry(
+                    name=cls.name,
+                    file=file_path,
+                    methods=cls.methods,
+                    attributes=cls.attributes,
+                    base_classes=cls.base_classes,
+                )
+            )
+
+        for fn in module.functions:
+            store.add_function(
+                FunctionIndexEntry(
+                    name=fn.name,
+                    file=file_path,
+                    start_line=fn.start_line,
+                    end_line=fn.end_line,
+                    parameters=fn.parameters,
+                    variables_read=fn.variables_read,
+                    variables_written=fn.variables_written,
+                    functions_called=fn.functions_called,
+                    docstring=fn.docstring,
+                )
+            )
+
+    return store