context-mcp-server 1.0.1

package/codegraph/graph/query.py

@@ -0,0 +1,283 @@
+"""
+graph/query.py — natural language graph traversal for codegraph_query.
+
+No LLM call on query — pure graph + keyword matching.
+"""
+
+import re
+from typing import Any
+
+
+def answer(question: str, graph_dict: dict, token_budget: int = 2000) -> dict:
+    """
+    Answer a natural language question about the codebase using graph traversal.
+
+    Returns { answer, nodes, confidence, tokens_used }
+    Output is truncated to token_budget (approx 4 chars = 1 token).
+    """
+    nodes = graph_dict.get("nodes", [])
+    edges = graph_dict.get("edges", [])
+    communities = graph_dict.get("communities", [])
+    god_nodes = graph_dict.get("god_nodes", [])
+
+    q_lower = question.lower()
+    terms = _extract_terms(q_lower)
+
+    # 1. Find relevant nodes by name/file match
+    matched = _match_nodes(nodes, terms)
+
+    # 2. Detect query intent
+    intent = _detect_intent(q_lower)
+
+    if intent == "depends_on" and matched:
+        result = _depends_on(matched[0], edges, nodes)
+    elif intent == "used_by" and matched:
+        result = _used_by(matched[0], edges, nodes)
+    elif intent == "path" and len(matched) >= 2:
+        result = _shortest_path(matched[0], matched[1], edges, nodes)
+    elif intent == "list":
+        result = _list_nodes(nodes, terms)
+    elif intent == "god_nodes":
+        result = _describe_god_nodes(god_nodes, nodes)
+    elif intent == "community" and matched:
+        result = _describe_community(matched[0], communities, nodes)
+    else:
+        result = _general_search(matched, nodes, edges)
+
+    # Render subgraph as structured text, truncated to token_budget
+    subgraph_text = _render_subgraph(result.get("nodes", []), edges, token_budget)
+    answer_text = result.get("text", "No answer found.")
+    if subgraph_text:
+        answer_text = f"{answer_text}\n\n{subgraph_text}"
+
+    # Truncate to budget (4 chars ≈ 1 token)
+    char_limit = token_budget * 4
+    truncated = len(answer_text) > char_limit
+    if truncated:
+        answer_text = answer_text[:char_limit] + "\n…(truncated to token budget)"
+
+    return {
+        "question":   question,
+        "answer":     answer_text,
+        "nodes":      result.get("nodes", []),
+        "confidence": result.get("confidence", "low"),
+        "tokens_used": len(answer_text) // 4,
+        "truncated":  truncated,
+    }
+
+
+def find_path(from_name: str, to_name: str, graph_dict: dict) -> dict:
+    """Find shortest relationship path between two concepts."""
+    nodes = graph_dict.get("nodes", [])
+    edges = graph_dict.get("edges", [])
+    from_node = _find_by_name(nodes, from_name)
+    to_node   = _find_by_name(nodes, to_name)
+    if not from_node or not to_node:
+        return {"path": [], "found": False, "message": f"Could not find '{from_name}' or '{to_name}' in graph."}
+    result = _shortest_path(from_node, to_node, edges, nodes)
+    return {"path": result.get("nodes", []), "found": bool(result.get("nodes")), "text": result.get("text", "")}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _extract_terms(q: str) -> list[str]:
+    stop = {"what", "does", "how", "where", "is", "the", "a", "an", "to", "do",
+            "does", "which", "files", "modules", "functions", "classes", "list",
+            "show", "find", "get", "all", "me", "about"}
+    return [w for w in re.findall(r"\w+", q) if w not in stop and len(w) > 2]
+
+
+def _match_nodes(nodes: list, terms: list) -> list:
+    scored = []
+    for n in nodes:
+        name  = (n.get("name", "") or "").lower()
+        fpath = (n.get("file", "") or "").lower()
+        score = sum(1 for t in terms if t in name or t in fpath)
+        if score:
+            scored.append((score, n))
+    scored.sort(key=lambda x: -x[0])
+    return [n for _, n in scored]
+
+
+def _find_by_name(nodes: list, name: str) -> dict | None:
+    name_l = name.lower()
+    for n in nodes:
+        if (n.get("name", "") or "").lower() == name_l:
+            return n
+    # partial match
+    for n in nodes:
+        if name_l in (n.get("name", "") or "").lower():
+            return n
+    return None
+
+
+def _detect_intent(q: str) -> str:
+    if any(w in q for w in ("depend", "import", "use", "require")):
+        return "depends_on"
+    if any(w in q for w in ("used by", "who calls", "caller")):
+        return "used_by"
+    if any(w in q for w in ("path", "connect", "relate", "between")):
+        return "path"
+    if any(w in q for w in ("list", "all", "show all", "every")):
+        return "list"
+    if any(w in q for w in ("god", "central", "most connected", "hub")):
+        return "god_nodes"
+    if any(w in q for w in ("community", "cluster", "group", "module")):
+        return "community"
+    return "general"
+
+
+def _depends_on(node: dict, edges: list, nodes: list) -> dict:
+    nid = node["id"]
+    targets = [e["to"] for e in edges if e["from"] == nid]
+    target_nodes = [n for n in nodes if n["id"] in targets]
+    names = [n["name"] for n in target_nodes]
+    return {
+        "text": f"{node['name']} depends on: {', '.join(names) or 'nothing found'}.",
+        "nodes": [node] + target_nodes,
+        "confidence": "high" if targets else "low",
+    }
+
+
+def _used_by(node: dict, edges: list, nodes: list) -> dict:
+    nid = node["id"]
+    sources = [e["from"] for e in edges if e["to"] == nid]
+    source_nodes = [n for n in nodes if n["id"] in sources]
+    names = [n["name"] for n in source_nodes]
+    return {
+        "text": f"{node['name']} is used by: {', '.join(names) or 'nothing found'}.",
+        "nodes": [node] + source_nodes,
+        "confidence": "high" if sources else "low",
+    }
+
+
+def _shortest_path(from_node: dict, to_node: dict, edges: list, nodes: list) -> dict:
+    # BFS
+    adj: dict[str, list[str]] = {}
+    for e in edges:
+        adj.setdefault(e["from"], []).append(e["to"])
+        adj.setdefault(e["to"], []).append(e["from"])  # undirected for path finding
+
+    start, end = from_node["id"], to_node["id"]
+    visited = {start: None}
+    queue = [start]
+    while queue:
+        cur = queue.pop(0)
+        if cur == end:
+            break
+        for nb in adj.get(cur, []):
+            if nb not in visited:
+                visited[nb] = cur
+                queue.append(nb)
+
+    if end not in visited:
+        return {"text": f"No path found between {from_node['name']} and {to_node['name']}.", "nodes": []}
+
+    path_ids = []
+    cur = end
+    while cur:
+        path_ids.append(cur)
+        cur = visited[cur]
+    path_ids.reverse()
+
+    node_map = {n["id"]: n for n in nodes}
+    path_nodes = [node_map[i] for i in path_ids if i in node_map]
+    names = [n["name"] for n in path_nodes]
+    return {
+        "text": f"Path: {' → '.join(names)}",
+        "nodes": path_nodes,
+        "confidence": "medium",
+    }
+
+
+def _list_nodes(nodes: list, terms: list) -> dict:
+    matched = _match_nodes(nodes, terms) if terms else nodes[:20]
+    names = [f"{n['name']} ({n.get('type','?')} in {n.get('file','?')})" for n in matched[:20]]
+    return {
+        "text": "\n".join(names) or "No matching nodes.",
+        "nodes": matched[:20],
+        "confidence": "medium",
+    }
+
+
+def _describe_god_nodes(god_node_ids: list, nodes: list) -> dict:
+    node_map = {n["id"]: n for n in nodes}
+    god = [node_map[i] for i in god_node_ids if i in node_map]
+    names = [f"{n['name']} ({n.get('file','')})" for n in god]
+    return {
+        "text": f"God nodes (highest connectivity): {', '.join(names) or 'none identified'}.",
+        "nodes": god,
+        "confidence": "high",
+    }
+
+
+def _describe_community(node: dict, communities: list, nodes: list) -> dict:
+    comm_id = node.get("community")
+    comm = next((c for c in communities if c["id"] == comm_id), None)
+    if not comm:
+        return {"text": f"{node['name']} has no community assignment.", "nodes": [node], "confidence": "low"}
+    node_map = {n["id"]: n for n in nodes}
+    members = [node_map[m] for m in comm["members"] if m in node_map]
+    return {
+        "text": f"{node['name']} is in community '{comm['label']}' with {len(members)} members.",
+        "nodes": members[:10],
+        "confidence": "high",
+    }
+
+
+def _general_search(matched: list, nodes: list, edges: list) -> dict:
+    if not matched:
+        return {"text": "No matching nodes found.", "nodes": [], "confidence": "low"}
+    top = matched[:5]
+    lines = [f"• {n['name']} ({n.get('type','?')}) in {n.get('file','?')} line {n.get('line','?')}" for n in top]
+    return {
+        "text": "\n".join(lines),
+        "nodes": top,
+        "confidence": "medium",
+    }
+
+
+def _render_subgraph(result_nodes: list, all_edges: list, token_budget: int) -> str:
+    """
+    Render a subgraph as structured plain text (graphify-style).
+    Format:
+      NODE  name  [type]  src=file  desc=...
+      EDGE  from → to  [relation]
+    Sorted by degree descending. Truncated to token_budget.
+    """
+    if not result_nodes:
+        return ""
+
+    node_ids = {n["id"] for n in result_nodes}
+    # Degree within subgraph
+    degree: dict[str, int] = {n["id"]: 0 for n in result_nodes}
+    subedges = []
+    for e in all_edges:
+        if e.get("from") in node_ids and e.get("to") in node_ids:
+            subedges.append(e)
+            degree[e["from"]] = degree.get(e["from"], 0) + 1
+            degree[e["to"]]   = degree.get(e["to"],   0) + 1
+
+    sorted_nodes = sorted(result_nodes, key=lambda n: -degree.get(n["id"], 0))
+
+    char_limit = token_budget * 4
+    lines = []
+    chars = 0
+
+    for n in sorted_nodes:
+        desc = n.get("description", "")
+        desc_part = f"  desc={desc[:80]}" if desc else ""
+        line = f"NODE  {n.get('name','?')}  [{n.get('type','?')}]  src={n.get('file','?')}{desc_part}"
+        if chars + len(line) > char_limit:
+            break
+        lines.append(line)
+        chars += len(line)
+
+    for e in subedges:
+        line = f"EDGE  {e.get('from','')} → {e.get('to','')}  [{e.get('relation','?')}]"
+        if chars + len(line) > char_limit:
+            break
+        lines.append(line)
+        chars += len(line)
+
+    return "\n".join(lines)

package/codegraph/report.py

@@ -0,0 +1,115 @@
+"""
+report.py — generate REPORT.md from the built graph.
+"""
+
+from pathlib import Path
+
+
+def generate(graph_dict: dict, project_root: str) -> str:
+    """Write REPORT.md to project_root and return its content."""
+    content = _build_report(graph_dict)
+    cache_dir = Path(project_root) / "codegraph-cache"
+    cache_dir.mkdir(exist_ok=True)
+    out = cache_dir / "CODEGRAPH_REPORT.md"
+    out.write_text(content, encoding="utf-8")
+    return content
+
+
+def _build_report(g: dict) -> str:
+    nodes      = g.get("nodes", [])
+    edges      = g.get("edges", [])
+    communities = g.get("communities", [])
+    god_nodes  = g.get("god_nodes", [])
+    generated  = g.get("generated_at", "")
+
+    node_map = {n["id"]: n for n in nodes}
+
+    lines = [
+        "# CodeGraph Report",
+        f"_Generated: {generated}_",
+        "",
+        f"**{len(nodes)} nodes** · **{len(edges)} edges** · **{len(communities)} communities**",
+        "",
+    ]
+
+    # God nodes
+    lines += ["## God Nodes", "", "_Highest-degree concepts everything flows through:_", ""]
+    if god_nodes:
+        for nid in god_nodes:
+            n = node_map.get(nid, {})
+            name = n.get("name", nid)
+            fpath = n.get("file", "")
+            deg = sum(1 for e in edges if e.get("from") == nid or e.get("to") == nid)
+            lines.append(f"- **{name}** `{fpath}` — {deg} connections")
+    else:
+        lines.append("_No god nodes identified._")
+    lines.append("")
+
+    # Communities
+    lines += ["## Community Clusters", ""]
+    if communities:
+        for c in communities[:10]:
+            members = c.get("members", [])
+            names = [node_map.get(m, {}).get("name", m) for m in members[:5]]
+            cluster_label = c.get("label") or f"Cluster {c['id']}"
+            lines.append(f"### {cluster_label} ({len(members)} nodes)")
+            lines.append(f"Members: {', '.join(names)}{' …' if len(members) > 5 else ''}")
+            lines.append("")
+    else:
+        lines.append("_No communities detected._")
+        lines.append("")
+
+    # Surprising cross-module connections
+    lines += ["## Surprising Connections", ""]
+    cross = _cross_module_edges(edges, node_map)
+    if cross:
+        for u_name, v_name, rel in cross[:8]:
+            lines.append(f"- **{u_name}** →({rel})→ **{v_name}**")
+    else:
+        lines.append("_None found._")
+    lines.append("")
+
+    # Suggested questions
+    lines += ["## Suggested Questions", ""]
+    questions = _suggest_questions(nodes, god_nodes, node_map)
+    for q in questions:
+        lines.append(f"- {q}")
+    lines.append("")
+
+    # Confidence breakdown
+    conf_counts = {}
+    for e in edges:
+        c = e.get("confidence", "UNKNOWN")
+        conf_counts[c] = conf_counts.get(c, 0) + 1
+    lines += ["## Confidence Breakdown", ""]
+    for label, count in sorted(conf_counts.items()):
+        lines.append(f"- **{label}**: {count} edges")
+
+    return "\n".join(lines)
+
+
+def _cross_module_edges(edges: list, node_map: dict) -> list[tuple]:
+    results = []
+    for e in edges:
+        u = node_map.get(e.get("from", ""), {})
+        v = node_map.get(e.get("to", ""), {})
+        u_file = (u.get("file", "") or "").split("/")[0]
+        v_file = (v.get("file", "") or "").split("/")[0]
+        if u_file and v_file and u_file != v_file:
+            results.append((u.get("name", "?"), v.get("name", "?"), e.get("relation", "?")))
+    return results[:8]
+
+
+def _suggest_questions(nodes: list, god_node_ids: list, node_map: dict) -> list[str]:
+    questions = []
+    if god_node_ids:
+        name = node_map.get(god_node_ids[0], {}).get("name", "")
+        if name:
+            questions.append(f"What does {name} depend on?")
+            questions.append(f"What uses {name}?")
+    classes = [n for n in nodes if n.get("type") == "class"][:2]
+    for c in classes:
+        questions.append(f"What is the relationship between {c['name']} and other modules?")
+    questions.append("Which files have the most connections?")
+    questions.append("Are there any circular dependencies?")
+    return questions[:5]

package/codegraph/scanner.py

@@ -0,0 +1,92 @@
+"""
+scanner.py — walk a project directory, hash every file, detect what changed.
+"""
+
+import os
+from pathlib import Path
+from typing import Iterator
+
+from .cache import file_hash, get_cached_nodes, set_cached_nodes, remove_deleted, load_cache, save_cache
+from .config import (
+    DEFAULT_IGNORE, MAX_FILE_BYTES,
+    CODE_EXTENSIONS, SQL_EXTENSIONS, CONFIG_EXTENSIONS,
+    DOC_EXTENSIONS, PDF_EXTENSIONS, IMAGE_EXTENSIONS,
+    AUDIO_EXTENSIONS, VIDEO_EXTENSIONS,
+)
+
+
+def _should_ignore(name: str, ignore: set) -> bool:
+    return name.startswith(".") and name != ".env" or name in ignore
+
+
+def walk_files(root: str, extra_ignore: set | None = None) -> Iterator[str]:
+    """Yield absolute paths to all non-ignored files under root."""
+    ignore = DEFAULT_IGNORE | (extra_ignore or set())
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune ignored dirs in-place so os.walk doesn't descend
+        dirnames[:] = [d for d in dirnames if d not in ignore and not d.startswith(".")]
+        for fname in filenames:
+            abs_path = os.path.join(dirpath, fname)
+            try:
+                if os.path.getsize(abs_path) > MAX_FILE_BYTES:
+                    continue
+            except OSError:
+                continue
+            yield abs_path
+
+
+def classify_file(path: str) -> str:
+    """Return extraction category for a file."""
+    ext = Path(path).suffix.lower()
+    if ext in CODE_EXTENSIONS:    return "code"
+    if ext in SQL_EXTENSIONS:     return "sql"
+    if ext in CONFIG_EXTENSIONS:  return "config"
+    if ext in DOC_EXTENSIONS:     return "doc"
+    if ext in PDF_EXTENSIONS:     return "pdf"
+    if ext in IMAGE_EXTENSIONS:   return "image"
+    if ext in AUDIO_EXTENSIONS:   return "audio"
+    if ext in VIDEO_EXTENSIONS:   return "video"
+    return "unknown"
+
+
+def scan(project_root: str, extra_ignore: set | None = None) -> dict:
+    """
+    Walk project, diff against cache.
+
+    Returns:
+        {
+          "cached":  { rel_path: [nodes] },   # unchanged — load from cache
+          "changed": { rel_path: abs_path },  # hash changed — need re-extraction
+          "deleted": [rel_path],              # in cache but file gone
+          "cache":   dict,                    # current cache (mutated in place)
+        }
+    """
+    root = os.path.abspath(project_root)
+    cache = load_cache(root)
+
+    cached = {}
+    changed = {}
+    existing_rel = set()
+
+    for abs_path in walk_files(root, extra_ignore):
+        rel_path = os.path.relpath(abs_path, root).replace("\\", "/")
+        existing_rel.add(rel_path)
+        category = classify_file(abs_path)
+        if category == "unknown":
+            continue
+        h = file_hash(abs_path)
+        nodes = get_cached_nodes(cache, rel_path, h)
+        if nodes is not None:
+            cached[rel_path] = nodes
+        else:
+            changed[rel_path] = abs_path
+
+    deleted = remove_deleted(cache, existing_rel)
+
+    return {
+        "cached":  cached,
+        "changed": changed,
+        "deleted": deleted,
+        "cache":   cache,
+        "root":    root,
+    }