codecompass-mcp 2.4.0__tar.gz → 2.5.0__tar.gz

{codecompass_mcp-2.4.0 → codecompass_mcp-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 2.4.0
+Version: 2.5.0
 Summary: Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing
 Author: CodeCompass contributors
 License: MIT

{codecompass_mcp-2.4.0 → codecompass_mcp-2.5.0}/codecompass_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 2.4.0
+Version: 2.5.0
 Summary: Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing
 Author: CodeCompass contributors
 License: MIT

{codecompass_mcp-2.4.0 → codecompass_mcp-2.5.0}/codecompass_mcp.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ ingestion/__init__.py
 ingestion/chunker.py
 ingestion/code_normalizer.py
 ingestion/code_parser.py
+ingestion/description_enricher.py
 ingestion/entity_resolver.py
 ingestion/file_watcher.py
 ingestion/graph_writer.py
@@ -30,6 +31,7 @@ models/types.py
 tests/test_batch_impact.py
 tests/test_blast_radius.py
 tests/test_code_parser.py
+tests/test_description_enricher.py
 tests/test_ingestion.py
 tests/test_lit_css_parser.py
 tests/test_php_parser.py

codecompass_mcp-2.5.0/ingestion/description_enricher.py

@@ -0,0 +1,189 @@
+"""Description enrichment for the code knowledge graph — agent-swarm edition.
+
+Tree-sitter gives us structure; this pass fills in the meaning. Rather than
+calling any single vendor's API directly, it stages the work as plain files
+and hands control back to whichever coding agent is driving the CLI (Claude
+Code, Codex, Gemini, or anything else). That agent dispatches its own native
+sub-agents — one per batch — to write descriptions, then `describe --apply`
+merges the results into the graph. No API key, no vendor lock-in.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from graph.code_graph_client import get_client
+from ingestion.source_context import extract_entity_context
+
+DEFAULT_BATCH_SIZE = 15
+DESCRIBE_SUBDIR = os.path.join(".codecompass", "describe")
+
+_INSTRUCTIONS_TEMPLATE = """\
+# Description enrichment — agent swarm task
+
+{num_entities} entities across {num_batches} batch file(s) in this directory
+need a one-sentence description written for the code knowledge graph.
+
+## What to do
+
+1. For each `batch_XXXX.json` file here, dispatch one sub-agent (in parallel).
+   Give each sub-agent this task:
+
+   > Read `{describe_dir}/batch_XXXX.json`. It is a JSON list of entities,
+   > each with `id`, `name`, `kind`, `file`, `signature`, `docstring`, and
+   > `snippet`. For every entity, write ONE clear sentence describing what
+   > it does or its role in the codebase. If signature/docstring/snippet are
+   > empty, infer a sensible description from the name, kind, and file path.
+   > Write the result to `{describe_dir}/batch_XXXX.result.json` as a JSON
+   > object mapping each entity's `id` to its description string. Output
+   > nothing else — no markdown fences, no commentary, just the file.
+
+2. Once every `batch_XXXX.result.json` file exists, run:
+
+   ```
+   codecompass describe {repo_path} --apply
+   ```
+
+   This merges every result file into the graph and cleans up this directory.
+
+## Batches
+
+{batch_list}
+"""
+
+
+def _entity_context(repo_path: str, node_id: str, attr: dict[str, Any]) -> dict[str, Any]:
+    """Build the sub-agent payload for a single entity."""
+    name = attr.get("name", "")
+    file = attr.get("file", "")
+    ctx = extract_entity_context(repo_path, file, name) if file else {}
+    return {
+        "id": node_id,
+        "name": name,
+        "kind": attr.get("kind", ""),
+        "file": file,
+        "signature": ctx.get("signature", ""),
+        "docstring": ctx.get("docstring", ""),
+        "snippet": ctx.get("snippet", ""),
+    }
+
+
+def _describe_dir(repo_path: str) -> str:
+    return os.path.join(os.path.abspath(repo_path), DESCRIBE_SUBDIR)
+
+
+def prepare_describe_batches(
+    repo_path: str, batch_size: int = DEFAULT_BATCH_SIZE, force: bool = False
+) -> dict[str, Any]:
+    """Stage entities needing descriptions into batch files plus an instructions doc.
+
+    Returns {"num_entities", "num_batches", "describe_dir", "instructions_path"}.
+    Writing no batches (num_entities == 0) leaves no files behind.
+
+    Raises RuntimeError if a previous run already has result files staged —
+    re-running would silently discard that in-progress work. Pass force=True
+    to overwrite anyway.
+    """
+    repo_path = os.path.abspath(repo_path)
+    project = os.path.basename(repo_path)
+    describe_dir = _describe_dir(repo_path)
+
+    if not force and os.path.isdir(describe_dir):
+        existing_results = [f for f in os.listdir(describe_dir) if f.endswith(".result.json")]
+        if existing_results:
+            raise RuntimeError(
+                f"{len(existing_results)} result file(s) already staged at {describe_dir} "
+                "from a previous describe run. Run `codecompass describe "
+                f"{repo_path} --apply` to finish it first, or re-run with force=True "
+                "to discard them and restage."
+            )
+
+    client = get_client(repo_path)
+    try:
+        entities = [
+            (node_id, attr)
+            for node_id, attr in client.graph.nodes(data=True)
+            if attr.get("type") == "Entity"
+            and attr.get("project") == project
+            and attr.get("file")
+        ]
+    finally:
+        client.close()
+
+    result = {
+        "num_entities": len(entities),
+        "num_batches": 0,
+        "describe_dir": describe_dir,
+        "instructions_path": None,
+    }
+    if not entities:
+        return result
+
+    os.makedirs(describe_dir, exist_ok=True)
+
+    batches = [entities[i : i + batch_size] for i in range(0, len(entities), batch_size)]
+    batch_names = []
+    for idx, batch in enumerate(batches):
+        batch_name = f"batch_{idx:04d}.json"
+        payload = [_entity_context(repo_path, node_id, attr) for node_id, attr in batch]
+        with open(os.path.join(describe_dir, batch_name), "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+        batch_names.append(batch_name)
+
+    instructions_path = os.path.join(describe_dir, "INSTRUCTIONS.md")
+    with open(instructions_path, "w", encoding="utf-8") as f:
+        f.write(
+            _INSTRUCTIONS_TEMPLATE.format(
+                num_entities=len(entities),
+                num_batches=len(batches),
+                describe_dir=describe_dir,
+                repo_path=repo_path,
+                batch_list="\n".join(f"- {name}" for name in batch_names),
+            )
+        )
+
+    result["num_batches"] = len(batches)
+    result["instructions_path"] = instructions_path
+    return result
+
+
+def apply_describe_results(repo_path: str) -> int:
+    """Merge every `batch_*.result.json` file into the graph and clean up.
+
+    Returns the number of nodes updated. Raises FileNotFoundError if no
+    staged batch directory exists (nothing to apply).
+    """
+    repo_path = os.path.abspath(repo_path)
+    describe_dir = _describe_dir(repo_path)
+    if not os.path.isdir(describe_dir):
+        raise FileNotFoundError(
+            f"No staged description batches found at {describe_dir}. "
+            "Run `codecompass describe <repo_path>` first."
+        )
+
+    descriptions: dict[str, str] = {}
+    result_files = sorted(f for f in os.listdir(describe_dir) if f.endswith(".result.json"))
+    for name in result_files:
+        with open(os.path.join(describe_dir, name), encoding="utf-8") as f:
+            try:
+                descriptions.update(json.load(f))
+            except json.JSONDecodeError:
+                continue
+
+    client = get_client(repo_path)
+    try:
+        updated = 0
+        for node_id, description in descriptions.items():
+            if node_id in client.graph:
+                client.graph.nodes[node_id]["description"] = description
+                updated += 1
+        client.save()
+    finally:
+        client.close()
+
+    import shutil
+
+    shutil.rmtree(describe_dir, ignore_errors=True)
+    return updated

{codecompass_mcp-2.4.0 → codecompass_mcp-2.5.0}/main.py

@@ -92,32 +92,41 @@ def init_project(repo_path: str) -> None:
     _register_project_agents_md(repo_path)
 
 
+_GITIGNORE_ENTRIES = [
+    (".codecompass/describe/", "# CodeCompass transient describe-swarm staging dir"),
+]
+
+
 def _ensure_gitignore(repo_path: str) -> None:
-    """Add the generated graph to .gitignore so it isn't committed (notes are)."""
-    entry = ".codecompass/graph.json"
+    """Add generated/transient CodeCompass artifacts to .gitignore (notes are kept)."""
     gitignore_path = os.path.join(repo_path, ".gitignore")
 
     lines = []
     if os.path.exists(gitignore_path):
         with open(gitignore_path) as f:
             lines = f.read().splitlines()
-        if any(line.strip() == entry for line in lines):
-            return
+
+    missing = [(entry, comment) for entry, comment in _GITIGNORE_ENTRIES
+               if not any(line.strip() == entry for line in lines)]
+    if not missing:
+        return
 
     with open(gitignore_path, "a") as f:
         if lines and lines[-1].strip():
             f.write("\n")
-        f.write("# CodeCompass generated graph (regenerated by ingest-code)\n")
-        f.write(entry + "\n")
+        for entry, comment in missing:
+            f.write(comment + "\n")
+            f.write(entry + "\n")
 
 
-def ingest_code(repo_path: str, normalize: bool = False, dump_triples: str | None = None) -> None:
+def ingest_code(repo_path: str, normalize: bool = False, dump_triples: str | None = None, describe: bool = False) -> None:
     """Ingest a codebase into the local code knowledge graph.
 
     Phase 1: Walk the repo and write the Project → Folder → File skeleton.
     Phase 2: Parse every source file with tree-sitter into CodeTriples.
     Phase 3: Normalize entity names via Haiku (only if --normalize is passed).
     Phase 4: Write all triples to the local graph.json.
+    Phase 5 (optional): Stage entity descriptions for an agent swarm to fill in.
     """
     import json
 
@@ -185,6 +194,20 @@ def ingest_code(repo_path: str, normalize: bool = False, dump_triples: str | Non
     )
     _register_project_agents_md(repo_path)
 
+    if describe:
+        from ingestion.description_enricher import prepare_describe_batches
+        console.print("[dim]Phase 5/5 — Staging descriptions for the agent swarm…[/]")
+        staged = prepare_describe_batches(repo_path)
+        if staged["num_entities"] == 0:
+            console.print("[dim]  Nothing to describe.[/]")
+        else:
+            console.print(
+                f"[bold green]Staged[/] {staged['num_entities']} entities in "
+                f"{staged['num_batches']} batch(es). Read {staged['instructions_path']} "
+                "and dispatch a sub-agent per batch, then run "
+                f"`codecompass describe {repo_path} --apply`."
+            )
+
 
 def _register_project_agents_md(repo_path: str) -> None:
     """Write or update the Code graph section in the project's AGENTS.md."""
@@ -286,6 +309,18 @@ doc → `memory.md`; code-comment warning to the next person → `learnings.md`.
 - After adding, renaming, or deleting source files
 - After major refactors (moved functions, renamed classes)
 - If query results look stale or incomplete
+
+### Description enrichment — user-triggered ONLY
+
+`codecompass describe` (and `ingest-code --describe`) stage entity descriptions
+for an agent swarm to fill in (see `.codecompass/describe/INSTRUCTIONS.md` when
+staged). This is expensive and **must only run when the user explicitly asks**
+for descriptions to be added or refreshed (e.g. "describe this codebase",
+"add descriptions", "enrich the graph").
+
+**Do NOT run `describe` automatically** after re-ingesting, editing files, or
+any other routine step — routine re-ingestion is `codecompass ingest-code`
+with no `--describe` flag.
 {_CODECOMPASS_END}"""
 
     agents_md_path = os.path.join(repo_path, "AGENTS.md")
@@ -356,7 +391,8 @@ def main():
     usage = (
         f"[bold]Usage:[/]\n"
         f"  {prog} init [italic]<repo_path>[/]\n"
-        f"  {prog} ingest-code [italic]<repo_path>[/] [--normalize] [--dump-triples [italic]<out.json>[/]]\n"
+        f"  {prog} ingest-code [italic]<repo_path>[/] [--normalize] [--dump-triples [italic]<out.json>[/]] [--describe]\n"
+        f"  {prog} describe [italic]<repo_path>[/] [--batch-size N] [--force] [--apply]\n"
         f"  {prog} query [italic]<--flag> <arg> <repo_path>[/]\n"
         f"  {prog} load-triples [italic]<triples.json> <repo_path>[/]\n"
         f"  {prog} watch [italic]<repo_path>[/]"
@@ -377,12 +413,48 @@ def main():
         non_flag_args = [a for a in args if not a.startswith("--")]
         repo_path = non_flag_args[0] if non_flag_args else "."
         normalize = "--normalize" in args
+        describe = "--describe" in args
         dump_triples = None
         if "--dump-triples" in args:
             idx = args.index("--dump-triples")
             if idx + 1 < len(args):
                 dump_triples = args[idx + 1]
-        ingest_code(repo_path, normalize=normalize, dump_triples=dump_triples)
+        ingest_code(repo_path, normalize=normalize, dump_triples=dump_triples, describe=describe)
+
+    elif command == "describe":
+        args = sys.argv[2:]
+        repo_path = "."
+        batch_size = 15
+        apply = "--apply" in args
+        force = "--force" in args
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--batch-size" and i + 1 < len(args):
+                batch_size = int(args[i + 1])
+                i += 2
+            elif a in ("--apply", "--force"):
+                i += 1
+            else:
+                repo_path = a
+                i += 1
+
+        if apply:
+            from ingestion.description_enricher import apply_describe_results
+            updated = apply_describe_results(repo_path)
+            console.print(f"[bold green]Applied[/] descriptions for {updated} entities.")
+        else:
+            from ingestion.description_enricher import prepare_describe_batches
+            staged = prepare_describe_batches(repo_path, batch_size=batch_size, force=force)
+            if staged["num_entities"] == 0:
+                console.print("[dim]Nothing to describe.[/]")
+            else:
+                console.print(
+                    f"[bold green]Staged[/] {staged['num_entities']} entities in "
+                    f"{staged['num_batches']} batch(es) at {staged['describe_dir']}.\n"
+                    f"Read {staged['instructions_path']} and dispatch a sub-agent per "
+                    f"batch, then run `codecompass describe {repo_path} --apply`."
+                )
 
     elif command == "load-triples":
         args = sys.argv[2:]

{codecompass_mcp-2.4.0 → codecompass_mcp-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codecompass-mcp"
-version = "2.4.0"
+version = "2.5.0"
 description = "Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing"
 readme = "README.md"
 license = {text = "MIT"}

codecompass_mcp-2.5.0/tests/test_description_enricher.py

@@ -0,0 +1,95 @@
+import json
+
+import pytest
+
+from graph.code_graph_client import get_client
+from ingestion.description_enricher import apply_describe_results, prepare_describe_batches
+from models.code_types import FileNode
+
+
+def _seed_entity(repo_path, project, entity_id, name="greet"):
+    src_dir = repo_path / "src"
+    src_dir.mkdir(exist_ok=True)
+    (src_dir / "greet.py").write_text('def greet(name):\n    return f"Hello {name}"\n')
+
+    client = get_client(str(repo_path))
+    client.merge_project_node(f"{project}:project", project, str(repo_path))
+    file_node = FileNode(path="src/greet.py", name="greet.py", extension=".py", depth=1)
+    client.merge_file_node(f"{project}:file:src/greet.py", file_node, project)
+    client.graph.add_node(
+        entity_id,
+        type="Entity",
+        name=name,
+        kind="function:python",
+        entity_type="function",
+        language="python",
+        file="src/greet.py",
+        project=project,
+        description="old generic description",
+    )
+    client.save()
+    client.close()
+
+
+def test_prepare_describe_batches_writes_batch_and_instructions(tmp_path):
+    project = "demo"
+    repo_path = tmp_path / project
+    repo_path.mkdir()
+    entity_id = f"{project}:greet"
+    _seed_entity(repo_path, project, entity_id)
+
+    staged = prepare_describe_batches(str(repo_path), batch_size=15)
+
+    assert staged["num_entities"] == 1
+    assert staged["num_batches"] == 1
+    describe_dir = repo_path / ".codecompass" / "describe"
+    assert (describe_dir / "batch_0000.json").exists()
+    assert (describe_dir / "INSTRUCTIONS.md").exists()
+
+    batch = json.loads((describe_dir / "batch_0000.json").read_text())
+    assert batch[0]["id"] == entity_id
+    assert batch[0]["name"] == "greet"
+
+
+def test_prepare_describe_batches_noop_when_nothing_to_describe(tmp_path):
+    project = "empty"
+    repo_path = tmp_path / project
+    repo_path.mkdir()
+    client = get_client(str(repo_path))
+    client.merge_project_node(f"{project}:project", project, str(repo_path))
+    client.save()
+    client.close()
+
+    staged = prepare_describe_batches(str(repo_path))
+
+    assert staged["num_entities"] == 0
+    assert not (repo_path / ".codecompass" / "describe").exists()
+
+
+def test_apply_describe_results_updates_nodes_and_cleans_up(tmp_path):
+    project = "demo"
+    repo_path = tmp_path / project
+    repo_path.mkdir()
+    entity_id = f"{project}:greet"
+    _seed_entity(repo_path, project, entity_id)
+
+    staged = prepare_describe_batches(str(repo_path), batch_size=15)
+    describe_dir = repo_path / ".codecompass" / "describe"
+    result_path = describe_dir / "batch_0000.result.json"
+    result_path.write_text(json.dumps({entity_id: "Greets a user by name."}))
+
+    updated = apply_describe_results(str(repo_path))
+    assert updated == 1
+
+    client = get_client(str(repo_path))
+    assert client.graph.nodes[entity_id]["description"] == "Greets a user by name."
+    client.close()
+
+    assert not describe_dir.exists()
+
+
+def test_apply_describe_results_without_staged_batches_raises(tmp_path):
+    repo_path = tmp_path / "nothing-staged"
+    repo_path.mkdir()
+    with pytest.raises(FileNotFoundError, match="No staged description batches"):
+        apply_describe_results(str(repo_path))