codebeacon 0.1.6__tar.gz → 0.1.8__tar.gz

{codebeacon-0.1.6 → codebeacon-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.1.6
+Version: 0.1.8
 Summary: Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph
 Project-URL: Homepage, https://github.com/codebeacon/codebeacon
 Project-URL: Repository, https://github.com/codebeacon/codebeacon

codebeacon-0.1.8/codebeacon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.8"

{codebeacon-0.1.6 → codebeacon-0.1.8}/codebeacon/cli.py

@@ -127,7 +127,7 @@ def _run_pipeline(projects, output_dir: str, args) -> int:
         from codebeacon.cache import Cache
         from codebeacon.wave import auto_wave
         from codebeacon.graph.build import build_graph
-        from codebeacon.graph.enrich import enrich_http_api, enrich_shared_db
+        from codebeacon.graph.enrich import enrich_http_api, enrich_shared_db, enrich_ipc_invoke
         from codebeacon.graph.cluster import cluster, apply_communities, score_all
 
         cache = Cache(output_dir)
@@ -176,8 +176,13 @@ def _run_pipeline(projects, output_dir: str, args) -> int:
         # Enrichment
         api_edges = enrich_http_api(G)
         db_edges = enrich_shared_db(G)
-        if api_edges or db_edges:
-            print(f"    Enriched: +{api_edges} calls_api, +{db_edges} shares_db_entity edges")
+        ipc_edges = enrich_ipc_invoke(G)
+        enriched_parts = []
+        if api_edges: enriched_parts.append(f"+{api_edges} calls_api")
+        if db_edges: enriched_parts.append(f"+{db_edges} shares_db_entity")
+        if ipc_edges: enriched_parts.append(f"+{ipc_edges} invokes_command")
+        if enriched_parts:
+            print(f"    Enriched: {', '.join(enriched_parts)} edges")
 
         # Community detection
         print("  Detecting communities ...")
@@ -188,7 +193,7 @@ def _run_pipeline(projects, output_dir: str, args) -> int:
         print(f"    {n_communities} communities detected")
 
         # Analysis
-        report = analyze(G, communities, cohesion)
+        report = analyze(G, communities, cohesion, project_paths={p.name: p.path for p in projects})
 
         # Save outputs
         import networkx.readwrite.json_graph as nxjson
@@ -249,7 +254,7 @@ def _run_deep_dive_pipeline(projects, workspace_output_dir: str, args) -> int:
     from pathlib import Path
     from codebeacon.graph.analyze import analyze, report_to_markdown
     from codebeacon.graph.build import build_graph
-    from codebeacon.graph.enrich import enrich_http_api, enrich_shared_db
+    from codebeacon.graph.enrich import enrich_http_api, enrich_shared_db, enrich_ipc_invoke
     from codebeacon.graph.cluster import cluster, apply_communities, score_all
     from codebeacon.wiki.generator import generate_wiki
     from codebeacon.export.obsidian import generate_obsidian_vault
@@ -364,7 +369,7 @@ def _run_deep_dive_pipeline(projects, workspace_output_dir: str, args) -> int:
             n_communities = len(set(communities.values())) if communities else 0
             print(f"    {n_communities} communities")
 
-            report = analyze(G, communities, cohesion)
+            report = analyze(G, communities, cohesion, project_paths={project.name: project.path})
 
             beacon_path = Path(proj_output_dir) / "beacon.json"
             beacon_path.write_text(
@@ -418,7 +423,7 @@ def _run_deep_dive_pipeline(projects, workspace_output_dir: str, args) -> int:
         n_communities_all = len(set(communities_all.values())) if communities_all else 0
         print(f"    {n_communities_all} communities detected")
 
-        report_all = analyze(G_all, communities_all, cohesion_all)
+        report_all = analyze(G_all, communities_all, cohesion_all, project_paths={p.name: p.path for p in projects})
 
         beacon_path = workspace_path / "beacon.json"
         beacon_path.write_text(

{codebeacon-0.1.6 → codebeacon-0.1.8}/codebeacon/contextmap/generator.py

@@ -273,40 +273,42 @@ def _build_content(
         lines = [
             "# CLAUDE.md",
             "",
-            "## MANDATORY: Lookup Strategy",
+            "## Lookup strategy",
             "",
-            "> **Read these before ANY code exploration. No exceptions.**",
-            ">",
-            "> Skipping these steps and reading source files directly is a rule violation.",
+            "> This repo ships a pre-built index in `.codebeacon/`. Check it first —",
+            "> most \"where is X\" questions resolve in one read without a full-repo search.",
             "",
         ]
     elif tool == "cursor":
         lines = [
             "# Project Context",
             "",
-            "## Lookup Strategy",
+            "## Lookup strategy",
             "",
-            "> Always follow this 3-step lookup before editing code.",
+            "> A pre-built index lives in `.codebeacon/`. Use the 3-step lookup below",
+            "> before reaching for Glob or Grep.",
             "",
         ]
     else:  # agents
         lines = [
             "# AGENTS.md",
             "",
-            "## Context Lookup Protocol",
+            "## Lookup strategy",
             "",
-            "> All agents MUST follow this 3-step lookup before writing or modifying code.",
+            "> A pre-built index lives in `.codebeacon/`. Follow the 3-step lookup below",
+            "> so parallel agents converge on the same answer.",
             "",
         ]
 
     # ── Step 1: wiki ──
     lines += [
-        "### Step 1 → codebeacon wiki (routes, controllers, services, entities) — ALWAYS",
+        "### Step 1 — codebeacon wiki",
+        "Routes, controllers, services, entities.",
         "```",
-        f"{codebeacon_dir}/wiki/index.md                    ← MUST read at session start",
-        f"{codebeacon_dir}/wiki/{{project}}/controllers/{{Name}}.md  ← for controller logic",
-        f"{codebeacon_dir}/wiki/{{project}}/services/{{Name}}.md     ← for service methods",
-        f"{codebeacon_dir}/wiki/{{project}}/entities/{{Name}}.md     ← for data models",
+        f"{codebeacon_dir}/wiki/index.md                    ← global index",
+        f"{codebeacon_dir}/wiki/{{project}}/controllers/{{Name}}.md  ← controller logic",
+        f"{codebeacon_dir}/wiki/{{project}}/services/{{Name}}.md     ← service methods",
+        f"{codebeacon_dir}/wiki/{{project}}/entities/{{Name}}.md     ← data models",
         f"{codebeacon_dir}/wiki/routes.md                   ← all API routes across projects",
         "```",
         "",
@@ -314,11 +316,9 @@ def _build_content(
 
     # ── Step 2: obsidian ──
     lines += [
-        "### Step 2 → codebeacon obsidian (methods, fields, connections) — ALWAYS",
-        "**MUST read even if Step 1 found results.** Obsidian notes contain method lists,",
-        "field definitions, and class-level connections that wiki articles do not have.",
-        "",
-        f"Look up by class name — replace `{{project}}` with the relevant folder:",
+        "### Step 2 — obsidian notes",
+        "Class-level detail (methods, fields, incoming/outgoing edges) the wiki omits.",
+        "Look up by class name — replace `{project}` with the relevant folder:",
         "```",
         f"{obsidian_path}/{{project}}/{{ClassName}}.md",
         "```",
@@ -351,21 +351,17 @@ def _build_content(
 
     # ── Step 3 ──
     lines += [
-        "### Step 3 → source file (ONLY files identified in Steps 1-2)",
-        "Read only the specific source files whose paths were found in Steps 1-2.",
-        "No directory exploration, no Glob scans, no broad Grep searches.",
+        "### Step 3 — source file",
+        "Open the paths surfaced by Steps 1–2.",
         "",
     ]
 
     if tool == "claude":
         lines += [
-            "### Prohibited actions (before completing Steps 1-2)",
-            "- **DO NOT use Explore agent**",
-            "- **DO NOT use Glob for directory scans**",
-            "- **DO NOT use Grep for broad searches**",
-            "- **DO NOT Read source files directly without checking Steps 1-2 first**",
-            "",
-            "Proceed to Step 3 only when Steps 1-2 are insufficient.",
+            "### Fall back to direct search",
+            "Reach for Glob, Grep, or the Explore agent when the index does not cover",
+            "what you need — new files, deep implementation details, or cross-cutting",
+            "searches that span projects.",
             "",
         ]
 

{codebeacon-0.1.6 → codebeacon-0.1.8}/codebeacon/graph/analyze.py

@@ -3,15 +3,18 @@
 These metrics help users understand their codebase structure at a glance.
 
 Public API:
-    god_nodes(G, top_n, min_degree)          → list[GodNode]
-    surprising_connections(G, communities)    → list[SurprisingConnection]
-    hub_files(G, top_n)                       → list[HubFile]
-    analyze(G, communities, cohesion_scores)  → GraphReport
-    report_to_markdown(report)                → str
+    god_nodes(G, top_n, min_degree, project_paths)  → list[GodNode]
+    surprising_connections(G, communities)           → list[SurprisingConnection]
+    hub_files(G, top_n)                              → list[HubFile]
+    analyze(G, communities, cohesion_scores,
+            project_paths)                           → GraphReport
+    report_to_markdown(report)                       → str
 """
 
 from __future__ import annotations
 
+import os
+from collections import defaultdict
 from dataclasses import dataclass, field
 from typing import Optional
 
@@ -22,15 +25,15 @@ import networkx as nx
 
 @dataclass
 class GodNode:
-    """A node with unusually high degree (hub / bottleneck)."""
-    node_id: str
-    label: str
-    type: str
-    in_degree: int
-    out_degree: int
-    degree: int
-    centrality: float
-    source_file: str
+    """A directory with unusually high cross-boundary coupling."""
+    folder_path: str    # relative path within project: "lib/utils" or "src-tauri/src"
+    label: str          # folder name: "utils"
+    project: str        # owning project: "desktop"
+    child_count: int    # number of nodes inside this folder
+    in_degree: int      # external → folder edges
+    out_degree: int     # folder → external edges
+    degree: int         # total cross-boundary edges
+    centrality: float   # degree / (total_nodes - child_count)
 
 
 @dataclass
@@ -70,37 +73,123 @@ class GraphReport:
 
 # ── Analysis functions ────────────────────────────────────────────────────────
 
+def _infer_project_paths(G: nx.DiGraph) -> dict[str, str]:
+    """Infer project root paths from source_file attributes in the graph.
+
+    Groups nodes by their ``project`` attribute, then finds the common path
+    prefix of all source_file directories within each project.
+    """
+    project_dirs: dict[str, list[str]] = defaultdict(list)
+    for _node_id, data in G.nodes(data=True):
+        sf = data.get("source_file", "")
+        proj = data.get("project", "")
+        if sf and proj:
+            project_dirs[proj].append(os.path.dirname(os.path.abspath(sf)))
+
+    result: dict[str, str] = {}
+    for proj, dirs in project_dirs.items():
+        if dirs:
+            result[proj] = os.path.commonpath(dirs)
+    return result
+
+
 def god_nodes(
     G: nx.DiGraph,
     top_n: int = 20,
     min_degree: int = 5,
+    project_paths: Optional[dict[str, str]] = None,
 ) -> list[GodNode]:
-    """Find nodes with the highest degree (potential god classes / bottlenecks).
+    """Find directories with the highest cross-boundary coupling.
+
+    Counts only edges that cross folder boundaries (cross-boundary edges).
+    Intra-folder edges are ignored, so a single large wrapper file can no
+    longer dominate solely because of its high node-level degree.
 
     Args:
         G: the knowledge graph
-        top_n: return at most this many nodes
-        min_degree: minimum total degree to qualify
+        top_n: return at most this many folders
+        min_degree: minimum cross-boundary edge count to qualify
+        project_paths: optional dict mapping project name → absolute project
+                       root path.  When None, paths are inferred automatically
+                       from source_file attributes via ``_infer_project_paths``.
 
     Returns:
-        List of GodNode sorted by degree descending.
+        List of GodNode (folder-level) sorted by degree descending.
     """
-    centrality = nx.degree_centrality(G)
+    if project_paths is None:
+        project_paths = _infer_project_paths(G)
+
+    total_nodes = G.number_of_nodes()
+
+    # Step 1: build node → (folder_key, folder_path, project) mapping.
+    # folder_key uses "{project}/{rel}" for cross-project uniqueness.
+    # folder_path stores only the relative portion shown in the report.
+    node_folder_key: dict[str, str] = {}
+    key_to_rel: dict[str, str] = {}
+    key_to_project: dict[str, str] = {}
 
-    results: list[GodNode] = []
     for node_id, data in G.nodes(data=True):
-        deg = G.degree(node_id)
-        if deg < min_degree:
+        sf = data.get("source_file", "")
+        proj = data.get("project", "")
+        if not sf:
+            continue
+        dirname = os.path.dirname(os.path.abspath(sf))
+        if proj and proj in project_paths:
+            try:
+                rel = os.path.relpath(dirname, project_paths[proj])
+            except ValueError:
+                rel = dirname
+            # Skip nodes whose source lives outside the project root
+            if rel.startswith(".."):
+                rel = dirname
+        else:
+            rel = dirname
+        key = f"{proj}/{rel}" if proj else rel
+        node_folder_key[node_id] = key
+        key_to_rel[key] = rel
+        key_to_project[key] = proj
+
+    # Step 2: count cross-boundary edges in a single pass.
+    folder_in: dict[str, int] = defaultdict(int)
+    folder_out: dict[str, int] = defaultdict(int)
+    folder_children: dict[str, set] = defaultdict(set)
+
+    for node_id in G.nodes():
+        fk = node_folder_key.get(node_id)
+        if fk:
+            folder_children[fk].add(node_id)
+
+    for src, tgt in G.edges():
+        src_key = node_folder_key.get(src)
+        tgt_key = node_folder_key.get(tgt)
+        if src_key is None or tgt_key is None:
             continue
+        if src_key != tgt_key:
+            folder_out[src_key] += 1
+            folder_in[tgt_key] += 1
+
+    # Step 3: filter, build GodNode list, sort.
+    results: list[GodNode] = []
+    for folder_key in folder_children:
+        in_d = folder_in.get(folder_key, 0)
+        out_d = folder_out.get(folder_key, 0)
+        degree = in_d + out_d
+        if degree < min_degree:
+            continue
+        child_count = len(folder_children[folder_key])
+        centrality = degree / max(1, total_nodes - child_count)
+        rel = key_to_rel.get(folder_key, folder_key)
+        proj = key_to_project.get(folder_key, "")
+        label = os.path.basename(rel) if rel not in (".", "") else "(root)"
         results.append(GodNode(
-            node_id=node_id,
-            label=data.get("label", node_id),
-            type=data.get("type", "unknown"),
-            in_degree=G.in_degree(node_id),
-            out_degree=G.out_degree(node_id),
-            degree=deg,
-            centrality=centrality.get(node_id, 0.0),
-            source_file=data.get("source_file", ""),
+            folder_path=rel,
+            label=label,
+            project=proj,
+            child_count=child_count,
+            in_degree=in_d,
+            out_degree=out_d,
+            degree=degree,
+            centrality=centrality,
         ))
 
     results.sort(key=lambda n: n.degree, reverse=True)
@@ -207,6 +296,7 @@ def analyze(
     G: nx.DiGraph,
     communities: Optional[dict[str, int]] = None,
     cohesion_scores: Optional[dict[int, float]] = None,
+    project_paths: Optional[dict[str, str]] = None,
 ) -> GraphReport:
     """Run all analyses and return a unified GraphReport.
 
@@ -214,6 +304,8 @@ def analyze(
         G: built knowledge graph (output of build.py + optional enrich.py)
         communities: optional community mapping from cluster.py
         cohesion_scores: optional per-community cohesion scores from cluster.score_all()
+        project_paths: optional dict mapping project name → absolute project root path.
+                       When None, paths are inferred automatically from the graph.
     """
     report = GraphReport(
         node_count=G.number_of_nodes(),
@@ -224,7 +316,7 @@ def analyze(
         isolated_nodes=sum(1 for n in G.nodes() if G.degree(n) == 0),
     )
 
-    report.god_nodes = god_nodes(G)
+    report.god_nodes = god_nodes(G, project_paths=project_paths)
     report.hub_files = hub_files(G)
 
     if communities:
@@ -248,12 +340,14 @@ def report_to_markdown(report: GraphReport) -> str:
     ]
 
     if report.god_nodes:
-        lines += ["## God Nodes (High Coupling)", ""]
-        lines.append(f"{'Node':<40} {'Type':<12} {'Degree':>6} {'Centrality':>10}")
-        lines.append("-" * 72)
+        lines += ["## God Nodes (High-Coupling Directories)", ""]
+        lines.append(
+            f"{'Folder':<44} {'Project':<12} {'Cross-Edges':>11} {'Children':>8} {'Centrality':>10}"
+        )
+        lines.append("-" * 89)
         for gn in report.god_nodes[:10]:
             lines.append(
-                f"{gn.label:<40} {gn.type:<12} {gn.degree:>6} {gn.centrality:>10.4f}"
+                f"{gn.folder_path:<44} {gn.project:<12} {gn.degree:>11} {gn.child_count:>8} {gn.centrality:>10.4f}"
             )
         lines.append("")
 

{codebeacon-0.1.6 → codebeacon-0.1.8}/codebeacon/graph/enrich.py

@@ -1,8 +1,10 @@
-"""Graph enrichment: HTTP API cross-service edges + shared DB entity edges.
+"""Graph enrichment: HTTP/IPC cross-service edges + shared DB entity edges.
 
-Two enrichment passes run AFTER the base graph is built by build.py:
-  1. enrich_http_api()  — frontend URL calls → backend controller routes (calls_api edges)
-  2. enrich_shared_db() — same DAO/Entity used by multiple services (shares_db_entity edges)
+Three enrichment passes run AFTER the base graph is built by build.py:
+  1. enrich_http_api()    — frontend URL calls → backend routes (calls_api edges)
+  2. enrich_shared_db()   — same DAO/Entity across services (shares_db_entity edges)
+  3. enrich_ipc_invoke()  — frontend invoke("cmd") → IPC command routes (invokes_command edges)
+     Covers Tauri, Electron ipcRenderer, and any invoke()-pattern IPC framework.
 """
 
 from __future__ import annotations
@@ -191,6 +193,91 @@ def enrich_shared_db(G: nx.DiGraph) -> int:
     return added
 
 
+# ── IPC invoke enrichment (Tauri, Electron, etc.) ────────────────────────────
+
+# Regexes for IPC invoke patterns across desktop/hybrid frameworks:
+#   Tauri:    invoke("cmd")  invoke<T>("cmd")
+#   Electron: ipcRenderer.invoke("cmd")  ipcRenderer.send("cmd")
+_IPC_INVOKE_RES = [
+    re.compile(r"""invoke\s*(?:<[^>]*>)?\s*\(\s*["'](\w+)["']"""),
+    re.compile(r"""ipcRenderer\.(?:invoke|send)\s*\(\s*["']([^"']+)["']"""),
+]
+
+
+def _extract_ipc_commands(source_file: str) -> list[str]:
+    """Extract IPC invoke/send command names from a frontend source file."""
+    try:
+        content = Path(source_file).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    commands: set[str] = set()
+    for pat in _IPC_INVOKE_RES:
+        for m in pat.finditer(content):
+            commands.add(m.group(1))
+    return list(commands)
+
+
+def enrich_ipc_invoke(G: nx.DiGraph) -> int:
+    """Add invokes_command edges: frontend invoke("cmd") → backend IPC command route.
+
+    Framework-agnostic — works with any route whose method is INVOKE,
+    regardless of backend framework (Tauri, Electron, etc.).
+
+    Strategy:
+    - Collect all 'route' nodes where method == "INVOKE"
+    - Extract the command name from the route handler
+    - For each frontend component, scan for invoke()/ipcRenderer.invoke() calls
+    - Match command names across projects
+
+    Returns:
+        Number of new invokes_command edges added.
+    """
+    added = 0
+
+    # Build command lookup: handler_name → (node_id, project)
+    cmd_map: dict[str, tuple[str, str]] = {}
+    for node_id, data in G.nodes(data=True):
+        if data.get("type") != "route":
+            continue
+        method = data.get("method", "")
+        if method != "INVOKE":
+            continue
+        handler = data.get("label", "").split(" ")[0]  # "handler [INVOKE /...]" → "handler"
+        if handler:
+            cmd_map[handler] = (node_id, data.get("project", ""))
+
+    if not cmd_map:
+        return 0
+
+    # Find frontend component nodes and scan for IPC calls
+    for node_id, data in G.nodes(data=True):
+        if data.get("type") != "component":
+            continue
+        src_proj = data.get("project", "")
+        src_file = data.get("source_file", "")
+        if not src_file:
+            continue
+
+        commands = _extract_ipc_commands(src_file)
+        for cmd in commands:
+            if cmd not in cmd_map:
+                continue
+            target_id, target_proj = cmd_map[cmd]
+            if target_proj == src_proj:
+                continue
+            if not G.has_edge(node_id, target_id):
+                G.add_edge(
+                    node_id, target_id,
+                    relation="invokes_command",
+                    confidence="EXTRACTED",
+                    confidence_score=1.0,
+                    source_file=src_file,
+                )
+                added += 1
+
+    return added
+
+
 # ── URL / path utilities ──────────────────────────────────────────────────────
 
 def _normalize_path(path: str) -> str:

{codebeacon-0.1.6 → codebeacon-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codebeacon"
-version = "0.1.6"
+version = "0.1.8"
 description = "Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph"
 readme = "README.md"
 license = { text = "MIT" }

codebeacon-0.1.6/codebeacon/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.6"