ctxgraph 0.1.0__py3-none-any.whl

ctxgraph/analyzers/python/importer.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+from ctxgraph.graph.models import Edge, Graph, Node
+
+
+def analyze_imports(file_path: Path, root_path: Path) -> Graph:
+    graph = Graph()
+    rel_path = _relative_path(file_path, root_path)
+    file_node_id = f"file:{rel_path}"
+
+    graph.add_node(
+        Node(
+            id=file_node_id,
+            type="file",
+            name=file_path.name,
+            path=rel_path,
+            summary=None,
+            importance=0.5,
+            size_bytes=file_path.stat().st_size,
+        )
+    )
+
+    try:
+        tree = ast.parse(file_path.read_text(encoding="utf-8", errors="replace"))
+    except SyntaxError:
+        return graph
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                target = _resolve_import_target(alias.name, root_path)
+                if target:
+                    _add_import_edge(graph, rel_path, file_node_id, target, alias.name)
+
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None:
+                continue
+            if node.level and node.level > 0:
+                target = _resolve_relative_import(
+                    node.module, node.level, rel_path, root_path
+                )
+            else:
+                target = _resolve_import_target(node.module, root_path)
+
+            if target:
+                for alias in node.names:
+                    symbol_name = alias.asname or alias.name
+                    edge_label = f"{node.module}.{alias.name}"
+                    _add_import_edge(
+                        graph, rel_path, file_node_id, target, edge_label
+                    )
+
+    return graph
+
+
+def _add_import_edge(
+    graph: Graph,
+    source_rel: str,
+    source_id: str,
+    target_rel: str,
+    label: str,
+):
+    target_id = f"file:{target_rel}"
+    if target_id not in graph.nodes:
+        graph.add_node(
+            Node(
+                id=target_id,
+                type="file",
+                name=Path(target_rel).name,
+                path=target_rel,
+                summary=None,
+                importance=0.3,
+                size_bytes=0,
+            )
+        )
+    graph.add_edge(
+        Edge(
+            source_id=source_id,
+            target_id=target_id,
+            relation="imports",
+            weight=1.0,
+        )
+    )
+
+
+def _resolve_import_target(module_name: str, root_path: Path) -> Optional[str]:
+    package_path = module_name.replace(".", "/")
+    root_name = root_path.name
+    extensions = [".py", ".pyw"]
+
+    candidates = [package_path]
+    parts = module_name.split(".")
+    if len(parts) > 1 and parts[0] == root_name:
+        candidates.append("/".join(parts[1:]))
+
+    for base in candidates:
+        for ext in extensions:
+            candidate = f"{base}{ext}"
+            if _exists_in_project(candidate, root_path):
+                return candidate
+            init_candidate = f"{base}/__init__{ext}"
+            if _exists_in_project(init_candidate, root_path):
+                return init_candidate
+    return None
+
+
+def _resolve_relative_import(
+    module_name: str, level: int, source_rel: str, root_path: Path
+) -> Optional[str]:
+    parts = Path(source_rel).parts
+    if level > len(parts):
+        return None
+    base = "/".join(parts[: len(parts) - level])
+    if module_name:
+        base = f"{base}/{module_name.replace('.', '/')}"
+    extensions = [".py", ".pyw"]
+    for ext in extensions:
+        candidate = f"{base}{ext}"
+        if _exists_in_project(candidate, root_path):
+            return candidate
+        init_candidate = f"{base}/__init__{ext}"
+        if _exists_in_project(init_candidate, root_path):
+            return init_candidate
+    return None
+
+
+def _exists_in_project(candidate_path: str, root_path: Path) -> bool:
+    full = root_path / candidate_path
+    return full.exists()
+
+
+def _relative_path(file_path: Path, root_path: Path) -> str:
+    try:
+        return str(file_path.relative_to(root_path)).replace("\\", "/")
+    except ValueError:
+        return file_path.name

ctxgraph/analyzers/python/semantic.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from ctxgraph.graph.models import Node
+
+
+def enrich_node_summary(node: Node, file_path: Path) -> str:
+    if node.summary:
+        return node.summary
+
+    try:
+        source = file_path.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except (SyntaxError, FileNotFoundError):
+        return node.summary or ""
+
+    if node.type == "file":
+        return _summarize_file(tree, file_path)
+    elif node.type == "class":
+        return _summarize_class(tree, node.name)
+    elif node.type == "function":
+        return _summarize_function(tree, node.name)
+
+    return node.summary or ""
+
+
+def _summarize_file(tree: ast.AST, file_path: Path) -> str:
+    doc = ast.get_docstring(tree)
+    if doc:
+        return doc.split("\n\n")[0][:200]
+
+    classes = []
+    funcs = []
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            classes.append(node.name)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            funcs.append(node.name)
+
+    parts = []
+    if classes:
+        parts.append(f"Defines classes: {', '.join(classes)}")
+    if funcs:
+        parts.append(f"Defines functions: {', '.join(funcs)}")
+    return "; ".join(parts) if parts else ""
+
+
+def _summarize_class(tree: ast.AST, class_name: str) -> str:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            doc = ast.get_docstring(node)
+            if doc:
+                return doc.split("\n\n")[0][:200]
+            methods = [
+                c.name
+                for c in ast.iter_child_nodes(node)
+                if isinstance(c, (ast.FunctionDef, ast.AsyncFunctionDef))
+            ]
+            if methods:
+                return f"Methods: {', '.join(methods)}"
+    return ""
+
+
+def _summarize_function(tree: ast.AST, func_name: str) -> str:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == func_name:
+            doc = ast.get_docstring(node)
+            if doc:
+                return doc.split("\n\n")[0][:200]
+            args = [a.arg for a in node.args.args]
+            if args:
+                return f"Args: {', '.join(args)}"
+    return ""

ctxgraph/analyzers/python/symbols.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+from ctxgraph.graph.models import Edge, Graph, Node
+
+
+def analyze_symbols(file_path: Path, root_path: Path) -> Graph:
+    graph = Graph()
+    rel_path = _relative_path(file_path, root_path)
+    file_node_id = f"file:{rel_path}"
+
+    try:
+        source = file_path.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except SyntaxError:
+        return graph
+
+    lines = source.split("\n")
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            _process_class(node, graph, file_node_id, rel_path, lines)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            _process_function(node, graph, file_node_id, rel_path, lines)
+
+    _process_calls(tree, graph, rel_path)
+
+    return graph
+
+
+def _process_class(
+    node: ast.ClassDef,
+    graph: Graph,
+    file_node_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    class_id = f"class:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+    bases = _get_base_names(node)
+
+    graph.add_node(
+        Node(
+            id=class_id,
+            type="class",
+            name=node.name,
+            path=rel_path,
+            parent_id=file_node_id,
+            summary=summary,
+            importance=0.6,
+            lineno=node.lineno,
+        )
+    )
+    graph.add_edge(
+        Edge(
+            source_id=file_node_id,
+            target_id=class_id,
+            relation="defines",
+            weight=1.0,
+        )
+    )
+
+    for base in bases:
+        graph.add_edge(
+            Edge(
+                source_id=class_id,
+                target_id=base,
+                relation="extends",
+                weight=0.8,
+            )
+        )
+
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            _process_method(child, graph, class_id, rel_path, lines)
+
+
+def _process_function(
+    node: (ast.FunctionDef | ast.AsyncFunctionDef),
+    graph: Graph,
+    file_node_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    func_id = f"func:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+
+    graph.add_node(
+        Node(
+            id=func_id,
+            type="function",
+            name=node.name,
+            path=rel_path,
+            parent_id=file_node_id,
+            summary=summary,
+            importance=0.5,
+            lineno=node.lineno,
+        )
+    )
+    graph.add_edge(
+        Edge(
+            source_id=file_node_id,
+            target_id=func_id,
+            relation="defines",
+            weight=1.0,
+        )
+    )
+
+
+def _process_method(
+    node: (ast.FunctionDef | ast.AsyncFunctionDef),
+    graph: Graph,
+    class_id: str,
+    rel_path: str,
+    lines: list[str],
+):
+    method_id = f"func:{rel_path}::{node.name}"
+    summary = _extract_docstring(node)
+
+    graph.add_node(
+        Node(
+            id=method_id,
+            type="function",
+            name=node.name,
+            path=rel_path,
+            parent_id=class_id,
+            summary=summary,
+            importance=0.5,
+            lineno=node.lineno,
+        )
+    )
+    graph.add_edge(
+        Edge(
+            source_id=class_id,
+            target_id=method_id,
+            relation="defines",
+            weight=1.0,
+        )
+    )
+
+
+def _process_calls(tree: ast.AST, graph: Graph, rel_path: str):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            func_name = _get_call_name(node.func)
+            if func_name:
+                caller_id = _find_enclosing_symbol(tree, node, rel_path)
+                if caller_id:
+                    callee_node = _find_target_node(func_name, graph)
+                    if callee_node:
+                        graph.add_edge(
+                            Edge(
+                                source_id=caller_id,
+                                target_id=callee_node.id,
+                                relation="calls",
+                                weight=0.7,
+                            )
+                        )
+
+
+def _get_call_name(node: ast.AST) -> Optional[str]:
+    if isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _find_enclosing_symbol(
+    tree: ast.AST, target_node: ast.AST, rel_path: str
+) -> Optional[str]:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _contains_node(node, target_node):
+                return f"func:{rel_path}::{node.name}"
+        elif isinstance(node, ast.ClassDef):
+            for child in ast.iter_child_nodes(node):
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if _contains_node(child, target_node):
+                        return f"func:{rel_path}::{child.name}"
+    return None
+
+
+def _contains_node(container: ast.AST, target: ast.AST) -> bool:
+    for node in ast.walk(container):
+        if node is target:
+            return True
+    return False
+
+
+def _find_target_node(name: str, graph: Graph) -> Optional[Node]:
+    for node in graph.nodes.values():
+        if node.type in ("function", "class") and node.name == name:
+            return node
+    return None
+
+
+def _extract_docstring(node: ast.AST) -> Optional[str]:
+    if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+        doc = ast.get_docstring(node)
+        if doc:
+            return doc.split("\n\n")[0][:200]
+    return None
+
+
+def _get_base_names(node: ast.ClassDef) -> list[str]:
+    bases = []
+    for base in node.bases:
+        if isinstance(base, ast.Name):
+            bases.append(f"class:{base.id}")
+    return bases
+
+
+def _relative_path(file_path: Path, root_path: Path) -> str:
+    try:
+        return str(file_path.relative_to(root_path)).replace("\\", "/")
+    except ValueError:
+        return file_path.name

ctxgraph/capsule/renderer.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Optional
+
+from ctxgraph.graph.models import Node
+from ctxgraph.graph.storage import Storage
+
+
+def render_capsule(
+    storage: Storage,
+    query: str,
+    max_nodes: int = 15,
+    include_deps: bool = True,
+) -> str:
+    from ctxgraph.graph.query import generate_context_subgraph
+
+    nodes, edges = generate_context_subgraph(storage, query, max_nodes)
+    if not nodes:
+        return _empty_capsule(query)
+
+    return _build_dsl(nodes, edges, storage, query)
+
+
+def render_project_overview(
+    storage: Storage,
+    max_files: int = 30,
+) -> str:
+    all_nodes = storage.get_all_nodes()
+    file_nodes = [n for n in all_nodes if n.type == "file"][:max_files]
+
+    lines = ["[CTX]Project Overview", ""]
+    for node in file_nodes:
+        summary = node.summary or ""
+        lines.append(f"[F]{node.path or node.name}")
+        if summary:
+            lines.append(f"  D:{summary}")
+
+        children = [
+            n for n in all_nodes
+            if n.parent_id == node.id and n.type in ("class", "function")
+        ]
+        if children:
+            names = [c.name for c in children[:8]]
+            lines.append(f"  S:{', '.join(names)}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _build_dsl(
+    nodes: list[Node],
+    edges: list[tuple[str, str, str]],
+    storage: Storage,
+    query: str,
+) -> str:
+    lines = [f"[CTX]{query}", ""]
+
+    type_order = {"file": 0, "module": 1, "class": 2, "function": 3}
+    nodes_sorted = sorted(nodes, key=lambda n: type_order.get(n.type, 9))
+
+    file_nodes = [n for n in nodes_sorted if n.type == "file"]
+    symbol_nodes = [n for n in nodes_sorted if n.type != "file"]
+
+    deps_by_file: dict[str, list[str]] = defaultdict(list)
+    calls_by_file: dict[str, list[str]] = defaultdict(list)
+    for src, tgt, rel in edges:
+        src_file = _find_file_for(src, nodes)
+        if rel == "imports":
+            deps_by_file[src].append(tgt)
+        elif rel == "calls":
+            calls_by_file[src].append(tgt)
+
+    seen_files = set()
+    for node in file_nodes:
+        if node.path in seen_files:
+            continue
+        seen_files.add(node.path or node.name)
+        _render_file_node(lines, node, deps_by_file, storage)
+
+    seen_symbols = set()
+    for node in symbol_nodes:
+        if node.id in seen_symbols:
+            continue
+        seen_symbols.add(node.id)
+        _render_symbol_node(lines, node)
+
+    dep_lines = _render_dependency_edges(edges, nodes)
+    lines.extend(dep_lines)
+
+    return "\n".join(lines)
+
+
+def _render_file_node(
+    lines: list[str],
+    node: Node,
+    deps_by_file: dict[str, list[str]],
+    storage: Optional[Storage] = None,
+):
+    path = node.path or node.name
+    lines.append(f"[F]{path}")
+
+    if node.summary:
+        lines.append(f"  D:{node.summary}")
+
+    if storage:
+        children = [
+            n
+            for n in storage.get_all_nodes()
+            if n.parent_id == node.id and n.type in ("class", "function")
+        ]
+        if children:
+            symbol_names = [c.name for c in children[:10]]
+            lines.append(f"  S:{', '.join(symbol_names)}")
+
+    lines.append("")
+
+
+def _render_symbol_node(lines: list[str], node: Node):
+    type_tag = {"class": "[C]", "function": "[M]"}
+    tag = type_tag.get(node.type, "[S]")
+    name = node.name
+
+    if node.parent_id and "::" not in node.parent_id:
+        parent_short = node.parent_id.split(":")[-1] if ":" in node.parent_id else node.parent_id
+        name = f"{parent_short}.{node.name}"
+
+    lines.append(f"{tag}{name}")
+    if node.summary:
+        lines.append(f"  D:{node.summary}")
+    lines.append("")
+
+
+def _render_dependency_edges(
+    edges: list[tuple[str, str, str]],
+    nodes: list[Node],
+) -> list[str]:
+    node_map = {n.id: n for n in nodes}
+    dep_lines = []
+
+    import_edges = [(s, t) for s, t, r in edges if r == "imports"]
+    if import_edges:
+        dep_lines.append("[DEP]")
+        for src, tgt in import_edges[:10]:
+            src_name = _short_name(src, node_map)
+            tgt_name = _short_name(tgt, node_map)
+            if src_name and tgt_name:
+                dep_lines.append(f"  {src_name} -> {tgt_name}")
+
+    call_edges = [(s, t) for s, t, r in edges if r == "calls"]
+    if call_edges:
+        dep_lines.append("[CAL]")
+        for src, tgt in call_edges[:10]:
+            src_name = _short_name(src, node_map)
+            tgt_name = _short_name(tgt, node_map)
+            if src_name and tgt_name:
+                dep_lines.append(f"  {src_name} -> {tgt_name}")
+
+    return dep_lines
+
+
+def _short_name(node_id: str, node_map: dict[str, Node]) -> Optional[str]:
+    if node_id in node_map:
+        n = node_map[node_id]
+        if n.type == "file":
+            return n.path or n.name
+        return f"{n.path}:{n.name}" if n.path else n.name
+    return node_id.split(":")[-1] if ":" in node_id else node_id
+
+
+def _find_file_for(node_id: str, nodes: list[Node]) -> str:
+    for n in nodes:
+        if n.id == node_id or (n.parent_id and n.parent_id == node_id):
+            return n.path or n.name
+    return node_id
+
+
+def _empty_capsule(query: str) -> str:
+    return (
+        f"[CTX]{query}\n\n"
+        "[INFO]No relevant context found in the graph.\n"
+        "[INFO]Run `ctx build` first to generate the knowledge graph.\n"
+    )