codegraph-py 1.0.1__tar.gz → 1.1.0__tar.gz

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-py
-Version: 1.0.1
+Version: 1.1.0
 Summary: Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.
 Author-email: mading <martin98@bu.edu>
 License-Expression: MIT

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/__init__.py

@@ -5,7 +5,7 @@ A local-first code intelligence system that builds a semantic
 knowledge graph from any codebase.
 """
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 from codegraph.codegraph import CodeGraph
 

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/cli.py

@@ -106,13 +106,24 @@ def resolve_project_path(path_arg: Optional[str] = None) -> str:
 # CLI Commands
 # =============================================================================
 
-@click.group()
+@click.group(context_settings=dict(help_option_names=['-h', '--help']))
 @click.version_option(version='1.0.1', prog_name='codegraph')
 def main():
-    """CodeGraph - Semantic code intelligence for AI coding agents.
-
-    Build a knowledge graph of your codebase for surgical context,
-    fewer tool calls, and faster answers.
+    """CodeGraph — Semantic code intelligence for AI coding agents.
+
+    Build a knowledge graph of your codebase for instant symbol lookup,
+    call-chain analysis, and surgical context extraction.
+
+    \b
+    Common workflows:
+      codegraph init            Initialize and index current project
+      codegraph status          View index statistics
+      codegraph query "class"   Search for symbols matching "class"
+      codegraph query --kind class   List all classes in the project
+      codegraph explore "main"  Show source code and call paths for "main"
+      codegraph callers "func"  Show what calls the function "func"
+      codegraph callees "func"  Show what "func" calls
+      codegraph files           List all indexed files
     """
     pass
 
@@ -308,7 +319,13 @@ def sync(path: Optional[str], quiet: bool):
 @click.argument('path', required=False, default=None)
 @click.option('-j', '--json', 'json_output', is_flag=True, help='Output as JSON')
 def status(path: Optional[str], json_output: bool):
-    """Show index status and statistics."""
+    """Show index status, statistics, and pending changes.
+
+    Displays file count, node/edge counts, node breakdown by kind,
+    and any pending changes since the last index.
+
+    Use --json/-j for machine-readable output.
+    """
     project_path = resolve_project_path(path)
 
     if not is_initialized(project_path):
@@ -403,14 +420,21 @@ def status(path: Optional[str], json_output: bool):
 
 
 @main.command()
-@click.argument('search')
+@click.argument('search', required=False, default='')
 @click.option('-p', '--path', 'path_arg', help='Project path')
-@click.option('-l', '--limit', default=10, type=int, help='Maximum results')
+@click.option('-l', '--limit', default=20, type=int, help='Maximum results')
 @click.option('-k', '--kind', help='Filter by node kind (function, class, etc.)')
+@click.option('--exact', is_flag=True, help='Exact name match (instead of fuzzy/prefix)')
+@click.option('--fuzzy', is_flag=True, help='Force fuzzy name matching (default)')
 @click.option('-j', '--json', 'json_output', is_flag=True, help='Output as JSON')
 def query(search: str, path_arg: Optional[str], limit: int,
-           kind: Optional[str], json_output: bool):
-    """Search for symbols in the codebase."""
+           kind: Optional[str], exact: bool, fuzzy: bool,
+           json_output: bool):
+    """Search for symbols in the codebase.
+
+    If SEARCH is omitted and --kind is provided, lists all symbols of that kind.
+    Use --exact for precise symbol name lookup.
+    """
     project_path = resolve_project_path(path_arg)
 
     if not is_initialized(project_path):
@@ -424,7 +448,15 @@ def query(search: str, path_arg: Optional[str], limit: int,
         if kind:
             opts.kinds = [kind]
 
-        results = cg.search_nodes(search, opts)
+        if exact:
+            opts.exact_match = True
+
+        if not search.strip() and kind:
+            # No search term — list by kind only
+            nodes = cg._queries.get_nodes_by_kind(kind) if kind else []
+            results = [SearchResult(node=n, score=1.0) for n in nodes]
+        else:
+            results = cg.search_nodes(search, opts)
 
         if json_output:
             output = []
@@ -447,9 +479,15 @@ def query(search: str, path_arg: Optional[str], limit: int,
             return
 
         if not results:
-            click.echo(f'No results found for "{search}"')
+            if search:
+                click.echo(f'No results found for "{search}"')
+            elif kind:
+                click.echo(f'No symbols of kind "{kind}" found')
+            else:
+                click.echo('No search term provided. Use --kind to browse by type.')
         else:
-            click.echo(bold(f'\nSearch Results for "{search}":\n'))
+            title = f'\nSearch Results for "{search}":' if search else f'\nAll {kind}s:' if kind else '\nResults:'
+            click.echo(bold(title + '\n'))
             for r in results:
                 node = r.node
                 location = f'{node.file_path}:{node.start_line}'
@@ -473,6 +511,14 @@ def query(search: str, path_arg: Optional[str], limit: int,
 def explore(query_parts: List[str], path_arg: Optional[str], max_files: int):
     """Explore code: relevant symbols' source + call paths in one shot.
 
+    QUERY_PARTS is one or more search terms for symbol lookup.
+    Combines search, callers/callees, and source display in a single view.
+
+    \b
+    Examples:
+      codegraph explore main          Find "main" and show source + call context
+      codegraph explore ChatBackend   Explore ChatBackend class and its relationships
+
     Same output as the codegraph_explore MCP tool.
     """
     query = ' '.join(query_parts)
@@ -524,9 +570,14 @@ def explore(query_parts: List[str], path_arg: Optional[str], max_files: int):
 @main.command()
 @click.argument('symbol')
 @click.option('-p', '--path', 'path_arg', help='Project path')
-@click.option('-d', '--depth', default=1, type=int, help='Traversal depth')
+@click.option('-d', '--depth', default=1, type=int, help='Traversal depth (1=direct, 2=indirect)')
 def callers(symbol: str, path_arg: Optional[str], depth: int):
-    """Find what calls a function/method."""
+    """Find what calls a function/method.
+
+    SYMBOL is the symbol name to find callers for (e.g. "ChatBackend", "main").
+
+    Use -d 2 to include indirect callers (callers of callers).
+    """
     project_path = resolve_project_path(path_arg)
 
     if not is_initialized(project_path):
@@ -569,9 +620,14 @@ def callers(symbol: str, path_arg: Optional[str], depth: int):
 @main.command()
 @click.argument('symbol')
 @click.option('-p', '--path', 'path_arg', help='Project path')
-@click.option('-d', '--depth', default=1, type=int, help='Traversal depth')
+@click.option('-d', '--depth', default=1, type=int, help='Traversal depth (1=direct, 2=indirect)')
 def callees(symbol: str, path_arg: Optional[str], depth: int):
-    """Find what a function/method calls."""
+    """Find what a function/method calls.
+
+    SYMBOL is the symbol name to find callees for (e.g. "run", "process").
+
+    Use -d 2 to include indirect callees (callees of callees).
+    """
     project_path = resolve_project_path(path_arg)
 
     if not is_initialized(project_path):
@@ -730,12 +786,14 @@ def node(name: str, path_arg: Optional[str]):
         return
 
     try:
-        cg = CodeGraph(project_path)
+        cg = CodeGraph.open_sync(project_path)
 
         # Search for nodes by name
-        results = cg.search(name)
+        opts = SearchOptions(limit=20)
+        results = cg.search_nodes(name, opts)
         if not results:
             click.echo(yellow(f'No nodes found matching "{name}"'))
+            cg.destroy()
             return
 
         # If exact match, show details
@@ -758,18 +816,18 @@ def node(name: str, path_arg: Optional[str]):
         click.echo(f'  {dim("Exported:")} {green("yes") if target.is_exported else "no"}')
 
         # Show callers
-        callers = cg.get_callers(target.id)
-        if callers:
-            click.echo(bold(f'\n  Callers ({len(callers)}):'))
-            for c in callers:
-                click.echo(f'    ← {c.name} ({c.file_path}:{c.start_line})')
+        caller_pairs = cg.get_callers(target.id)
+        if caller_pairs:
+            click.echo(bold(f'\n  Callers ({len(caller_pairs)}):'))
+            for c_node, c_edge in caller_pairs:
+                click.echo(f'    ← {c_node.name} ({c_node.file_path}:{c_node.start_line})')
 
         # Show callees
-        callees = cg.get_callees(target.id)
-        if callees:
-            click.echo(bold(f'\n  Callees ({len(callees)}):'))
-            for c in callees:
-                click.echo(f'    → {c.name} ({c.file_path}:{c.start_line})')
+        callee_pairs = cg.get_callees(target.id)
+        if callee_pairs:
+            click.echo(bold(f'\n  Callees ({len(callee_pairs)}):'))
+            for c_node, c_edge in callee_pairs:
+                click.echo(f'    → {c_node.name} ({c_node.file_path}:{c_node.start_line})')
 
         cg.destroy()
 
@@ -781,7 +839,9 @@ def node(name: str, path_arg: Optional[str]):
 @main.command()
 @click.option('--path', '-p', 'path_arg', default=None, help='Project path')
 @click.option('--json-output', 'json_output', is_flag=True, help='Output as JSON')
-def files(path_arg: Optional[str], json_output: bool):
+@click.option('--by-directory', 'by_directory', is_flag=True, help='Group files by directory')
+@click.option('--stats', 'show_stats', is_flag=True, help='Show per-file symbol stats (default when no flags)')
+def files(path_arg: Optional[str], json_output: bool, by_directory: bool, show_stats: bool):
     """List indexed files with language and symbol statistics."""
     project_path = resolve_project_path(path_arg)
 
@@ -791,44 +851,69 @@ def files(path_arg: Optional[str], json_output: bool):
         return
 
     try:
-        cg = CodeGraph(project_path)
+        cg = CodeGraph.open_sync(project_path)
         stats = cg.get_stats()
-        all_files = cg.db.get_all_file_paths()
+        all_files = cg._queries.get_all_file_paths()
 
         if json_output:
-            result = {
-                'total_files': len(all_files),
-                'total_nodes': stats.node_count,
-                'total_edges': stats.edge_count,
-                'files': [],
-            }
-            for f in all_files:
-                nodes = cg.db.get_nodes_by_file(f)
+            file_list = []
+            for f in sorted(all_files):
+                nodes = cg.get_nodes_by_file(f)
                 langs = set(n.language for n in nodes if n.language)
-                result['files'].append({
+                kinds = {}
+                for n in nodes:
+                    kinds[n.kind] = kinds.get(n.kind, 0) + 1
+                file_list.append({
                     'path': f,
                     'node_count': len(nodes),
                     'languages': list(langs),
+                    'node_kinds': kinds,
                 })
+            result = {
+                'total_files': len(all_files),
+                'total_nodes': stats.node_count,
+                'total_edges': stats.edge_count,
+                'files': file_list,
+            }
             click.echo(json.dumps(result, indent=2))
+            cg.destroy()
+            return
+
+        show_stats = show_stats or not by_directory
+
+        if by_directory:
+            # Group files by directory
+            dirs: Dict[str, List[str]] = {}
+            for f in sorted(all_files):
+                d = os.path.dirname(f) or '.'
+                dirs.setdefault(d, []).append(f)
+            click.echo(bold(f'\n📁 Indexed Files ({len(all_files)} total, {len(dirs)} directories)\n'))
+            for directory in sorted(dirs):
+                click.echo(blue(f'  {directory}/'))
+                for f in dirs[directory]:
+                    click.echo(f'    {os.path.basename(f)}')
+            click.echo()
         else:
             click.echo(bold(f'\n📁 Indexed Files ({len(all_files)} total)\n'))
             for f in sorted(all_files):
-                nodes = cg.db.get_nodes_by_file(f)
+                nodes = cg.get_nodes_by_file(f)
                 lang = ''
                 for n in nodes:
                     if n.language and n.language != 'unknown':
                         lang = n.language
                         break
-                kinds = {}
-                for n in nodes:
-                    k = n.kind
-                    kinds[k] = kinds.get(k, 0) + 1
-                kind_str = ', '.join(f'{v} {k}' for k, v in sorted(kinds.items()) if k != 'file')
-                if kind_str:
-                    click.echo(f'  {dim(lang+"  ") if lang else ""}{f}  {dim("("+kind_str+")")}')
+                if show_stats:
+                    kinds = {}
+                    for n in nodes:
+                        k = n.kind
+                        kinds[k] = kinds.get(k, 0) + 1
+                    kind_str = ', '.join(f'{v} {k}' for k, v in sorted(kinds.items()) if k != 'file')
+                    if kind_str:
+                        click.echo(f'  {dim(lang+"  ") if lang else ""}{f}  {dim("("+kind_str+")")}')
+                    else:
+                        click.echo(f'  {f}')
                 else:
-                    click.echo(f'  {f}')
+                    click.echo(f'  {dim(lang+"  ") if lang else ""}{f}')
 
         cg.destroy()
 

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/codegraph.py

@@ -31,7 +31,7 @@ from codegraph.graph import GraphTraverser, GraphQueryManager
 from codegraph.context import ContextBuilder, create_context_builder
 from codegraph.sync import FileWatcher, WatchOptions, PendingFile
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 
 @dataclass
@@ -357,25 +357,93 @@ class CodeGraph:
         return self._queries.get_nodes_by_file(file_path)
 
     def get_callers(self, node_id: str, max_depth: int = 1) -> List[Tuple[Node, Edge]]:
-        """Find what calls a function/method."""
-        nodes = self._traverser.getCallers(node_id, max_depth > 1)
-        result = []
+        """Find what calls a function/method.
+
+        First tries edge-based lookup (resolved references), then falls back
+        to name-based matching on unresolved references for maximum coverage.
+        """
+        result: List[Tuple[Node, Edge]] = []
+
+        # ── Phase 1: edge-based (resolved references) ──
+        nodes = self._traverser.getCallers(node_id, max_depth)
         for n in nodes:
             edges = self._queries.get_outgoing_edges(n.id, ['calls', 'references'])
             for e in edges:
                 if e.target == node_id:
                     result.append((n, e))
+
+        if result:
+            return result
+
+        # ── Phase 2: fallback via UnresolvedReference name matching ──
+        target = self._queries.get_node_by_id(node_id)
+        if target:
+            target_name = target.name
+            # Collect all refs whose name matches the target name (or any dotted suffix)
+            refs = self._queries.get_unresolved_refs()
+            seen: Set[str] = set()
+            for ref in refs:
+                ref_name = ref.reference_name
+                # Exact match, or last component of dotted name matches
+                if ref_name == target_name or (
+                    '.' in ref_name and ref_name.rsplit('.', 1)[-1] == target_name
+                ):
+                    caller = self._queries.get_node_by_id(ref.from_node_id)
+                    if caller and caller.id not in seen:
+                        seen.add(caller.id)
+                        fake_edge = Edge(
+                            source=caller.id, target=node_id,
+                            kind=ref.reference_kind or 'references',
+                            line=ref.line, column=ref.column,
+                            provenance='unresolved',
+                        )
+                        result.append((caller, fake_edge))
+
         return result
 
     def get_callees(self, node_id: str, max_depth: int = 1) -> List[Tuple[Node, Edge]]:
-        """Find what a function/method calls."""
-        nodes = self._traverser.getCallees(node_id, max_depth > 1)
-        result = []
+        """Find what a function/method calls.
+
+        First tries edge-based lookup (resolved references), then falls back
+        to name-based matching on unresolved references for maximum coverage.
+        """
+        result: List[Tuple[Node, Edge]] = []
+
+        # ── Phase 1: edge-based (resolved references) ──
+        nodes = self._traverser.getCallees(node_id, max_depth)
         for n in nodes:
             edges = self._queries.get_incoming_edges(n.id, ['calls', 'references'])
             for e in edges:
                 if e.source == node_id:
                     result.append((n, e))
+
+        if result:
+            return result
+
+        # ── Phase 2: fallback via UnresolvedReference name matching ──
+        source = self._queries.get_node_by_id(node_id)
+        if source:
+            refs = self._queries.get_unresolved_refs_by_from_node(node_id)
+            seen: Set[str] = set()
+            for ref in refs:
+                # Try to resolve the referenced name to a real node
+                callees_found = self._queries.get_nodes_by_name(ref.reference_name)
+                # Also try last component of dotted names
+                if not callees_found and '.' in ref.reference_name:
+                    simple = ref.reference_name.rsplit('.', 1)[-1]
+                    callees_found = self._queries.get_nodes_by_name(simple)
+
+                for callee in callees_found:
+                    if callee.id not in seen:
+                        seen.add(callee.id)
+                        fake_edge = Edge(
+                            source=node_id, target=callee.id,
+                            kind=ref.reference_kind or 'references',
+                            line=ref.line, column=ref.column,
+                            provenance='unresolved',
+                        )
+                        result.append((callee, fake_edge))
+
         return result
 
     def get_impact_radius(self, node_id: str, max_depth: int = 3) -> Subgraph:

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/db/queries.py

@@ -443,6 +443,13 @@ class QueryBuilder:
         )
         return [self._row_to_unresolved(row) for row in cur.fetchall()]
 
+    def get_unresolved_refs_by_from_node(self, from_node_id: str) -> List[UnresolvedReference]:
+        """Get unresolved references by originating node ID."""
+        cur = self._db.execute(
+            'SELECT * FROM unresolved_refs WHERE from_node_id = ?', (from_node_id,)
+        )
+        return [self._row_to_unresolved(row) for row in cur.fetchall()]
+
     def clear_unresolved_refs(self) -> None:
         """Clear all unresolved references."""
         self._db.execute('DELETE FROM unresolved_refs')
@@ -453,12 +460,32 @@ class QueryBuilder:
 
     def search_nodes(self, query: str,
                      options: Optional[SearchOptions] = None) -> List[SearchResult]:
-        """Search nodes using FTS5 full-text search."""
+        """Search nodes in the codebase.
+
+        Supports three modes:
+        - Exact match (opts.exact_match=True): precise name lookup via SQL
+        - FTS5 full-text: prefix-based ranking search
+        - LIKE fallback: substring matching when FTS returns nothing
+        """
         opts = options or SearchOptions()
         results: List[SearchResult] = []
 
+        # ── Exact match mode ──
+        if opts.exact_match and query.strip():
+            cur = self._db.execute(
+                '''SELECT * FROM nodes WHERE name = ?
+                   ORDER BY file_path, start_line
+                   LIMIT ?''',
+                (query.strip(), opts.limit)
+            )
+            for row in cur.fetchall():
+                node = self._row_to_node(row)
+                if self._matches_filters(node, opts):
+                    results.append(SearchResult(node=node, score=1.0))
+            return results
+
+        # ── FTS5 full-text search ──
         try:
-            # FTS5 query with prefix matching
             fts_query = ' OR '.join(
                 f'"{word}"*' if len(word) > 1 else word
                 for word in query.split()
@@ -484,7 +511,7 @@ class QueryBuilder:
         except Exception:
             pass
 
-        # Fallback: LIKE search if FTS returns nothing
+        # ── LIKE fallback ──
         if not results:
             for word in query.split():
                 if not word.strip():

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/graph/__init__.py

@@ -174,62 +174,70 @@ class GraphTraverser:
         dfs(start_id, 0)
         return result
 
-    def getCallers(self, node_id: str, include_indirect: bool = False) -> List[Node]:
+    def getCallers(self, node_id: str, max_depth: int = 1) -> List[Node]:
         """Get nodes that call/ reference the given node.
-        
+
         Args:
             node_id: Target node ID
-            include_indirect: If True, include indirect callers through the call chain
-            
+            max_depth: How many levels up to traverse.
+                        1 = direct callers only,
+                        2 = callers + their callers, etc.
+
         Returns:
             List of caller nodes
         """
         callers: List[Node] = []
         seen: Set[str] = set()
 
-        def collect_callers(nid: str) -> None:
+        def collect_callers(nid: str, depth: int) -> None:
             if nid in seen:
                 return
             seen.add(nid)
 
+            if depth >= max_depth:
+                return
+
             edges = self._qb.get_incoming_edges(nid, [EdgeKind.CALLS, EdgeKind.REFERENCES])
             for edge in edges:
                 caller_node = self._qb.get_node_by_id(edge.source)
                 if caller_node and edge.source not in seen:
                     callers.append(caller_node)
-                    if include_indirect:
-                        collect_callers(edge.source)
+                    collect_callers(edge.source, depth + 1)
 
-        collect_callers(node_id)
+        collect_callers(node_id, 0)
         return callers
 
-    def getCallees(self, node_id: str, include_indirect: bool = False) -> List[Node]:
+    def getCallees(self, node_id: str, max_depth: int = 1) -> List[Node]:
         """Get nodes that the given node calls/ references.
-        
+
         Args:
             node_id: Source node ID
-            include_indirect: If True, include indirect callees through the call chain
-            
+            max_depth: How many levels down to traverse.
+                        1 = direct callees only,
+                        2 = callees + their callees, etc.
+
         Returns:
             List of callee nodes
         """
         callees: List[Node] = []
         seen: Set[str] = set()
 
-        def collect_callees(nid: str) -> None:
+        def collect_callees(nid: str, depth: int) -> None:
             if nid in seen:
                 return
             seen.add(nid)
 
+            if depth >= max_depth:
+                return
+
             edges = self._qb.get_outgoing_edges(nid, [EdgeKind.CALLS, EdgeKind.REFERENCES])
             for edge in edges:
                 callee_node = self._qb.get_node_by_id(edge.target)
                 if callee_node and edge.target not in seen:
                     callees.append(callee_node)
-                    if include_indirect:
-                        collect_callees(edge.target)
+                    collect_callees(edge.target, depth + 1)
 
-        collect_callees(node_id)
+        collect_callees(node_id, 0)
         return callees
 
     def getImpactRadius(

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph/types.py

@@ -241,6 +241,7 @@ class SearchOptions:
     limit: int = 20
     offset: int = 0
     case_sensitive: bool = False
+    exact_match: bool = False
 
 
 @dataclass

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/codegraph_py.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-py
-Version: 1.0.1
+Version: 1.1.0
 Summary: Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.
 Author-email: mading <martin98@bu.edu>
 License-Expression: MIT

codegraph_py-1.1.0/codegraph_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+codegraph

{codegraph_py-1.0.1 → codegraph_py-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codegraph-py"
-version = "1.0.1"
+version = "1.1.0"
 description = "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local."
 readme = "README.md"
 license = "MIT"

codegraph_py-1.0.1/codegraph_py.egg-info/top_level.txt

@@ -1,2 +0,0 @@
-codegraph
-codegraph-main