codegraph-network 0.1.0__tar.gz → 0.2.0__tar.gz

{codegraph_network-0.1.0/src/codegraph_network.egg-info → codegraph_network-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-network
-Version: 0.1.0
+Version: 0.2.0
 Summary: Graph-based code understanding for LLM agents: fewer tokens, better answers
 Author: Oviing
 License-Expression: MIT
@@ -25,6 +25,7 @@ Requires-Dist: mcp>=1.2
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
 Provides-Extra: embed
 Requires-Dist: fastembed>=0.4; extra == "embed"
 Requires-Dist: numpy>=1.24; extra == "embed"
@@ -62,6 +63,17 @@ Or in any MCP client config:
 The index lives in `<repo>/.codegraph/graph.db` and updates incrementally on every server start;
 `reindex` re-scans after edits made outside the session. `.gitignore` it.
 
+## Explore visually
+
+    codegraph -r /path/to/repo ui
+
+Opens an interactive map of the repo in your browser (served from `127.0.0.1` only, nothing leaves your machine).
+You start from the file-level network: lines are calls and imports between files, colour is community (or folder).
+Drag nodes to rearrange and pin them, scroll to zoom, drag the background to pan. Double-click a file to open it
+into its functions and classes; double-click a symbol to pull in everything it calls and everything that calls it.
+The side panel shows the source, callers and callees (click to jump), and **Show impact** highlights the transitive
+callers, i.e. what breaks if the symbol changes. Press `/` to search.
+
 ## Tools
 
 | Tool | Use it to |

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/README.md

@@ -26,6 +26,17 @@ Or in any MCP client config:
 The index lives in `<repo>/.codegraph/graph.db` and updates incrementally on every server start;
 `reindex` re-scans after edits made outside the session. `.gitignore` it.
 
+## Explore visually
+
+    codegraph -r /path/to/repo ui
+
+Opens an interactive map of the repo in your browser (served from `127.0.0.1` only, nothing leaves your machine).
+You start from the file-level network: lines are calls and imports between files, colour is community (or folder).
+Drag nodes to rearrange and pin them, scroll to zoom, drag the background to pan. Double-click a file to open it
+into its functions and classes; double-click a symbol to pull in everything it calls and everything that calls it.
+The side panel shows the source, callers and callees (click to jump), and **Show impact** highlights the transitive
+callers, i.e. what breaks if the symbol changes. Press `/` to search.
+
 ## Tools
 
 | Tool | Use it to |

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/pyproject.toml

@@ -31,7 +31,8 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "ruff>=0.6"]
+# numpy: the semantic tests run on a fake embedder (tests/fake_embed.py) that needs it
+dev = ["pytest>=8", "ruff>=0.6", "numpy>=1.24"]
 # semantic search: local embeddings (fastembed runs a small ONNX model, no network at query time)
 embed = ["fastembed>=0.4", "numpy>=1.24"]
 bench = ["pyyaml>=6"]
@@ -51,7 +52,7 @@ version = { attr = "codegraph.__version__" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-codegraph = ["py.typed"]
+codegraph = ["py.typed", "ui.html"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

codegraph_network-0.2.0/src/codegraph/__init__.py

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

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/src/codegraph/cli.py

@@ -44,6 +44,9 @@ def build_parser() -> argparse.ArgumentParser:
     ap.add_argument("-r", "--root", default=".", help="repository root (default: cwd)")
     sub = ap.add_subparsers(dest="cmd", required=True)
     sub.add_parser("serve", help="run the MCP server over stdio")
+    ui = sub.add_parser("ui", help="open an interactive graph explorer in the browser (local only)")
+    ui.add_argument("--port", type=int, default=0, help="port to listen on (default: any free port)")
+    ui.add_argument("--no-open", action="store_true", help="print the URL instead of opening a browser")
     bench = sub.add_parser("bench", help="measure tokens and recall (lexical vs hybrid) on a tasks file")
     bench.add_argument("tasks", help="YAML/JSON list of {task: ..., expect: [symbols]}")
     bench.add_argument("-k", type=int, default=10, help="results per search (default 10)")
@@ -94,6 +97,10 @@ def main(argv=None):
         from .server import main as serve
         return serve(args.root)
 
+    if args.cmd == "ui":
+        from .ui import serve as ui_serve
+        return ui_serve(args.root, args.port, not args.no_open)
+
     if args.cmd == "bench":
         from .bench import run as bench
         print(bench(args.root, args.tasks, args.k))

codegraph_network-0.2.0/src/codegraph/ui.html

@@ -0,0 +1,262 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Codegraph Explorer</title>
+<style>
+:root{--bg:#fafafa;--panel:#fff;--fg:#1a1a1a;--mute:#6b7280;--line:#d1d5db;--edge:#9ca3af;--acc:#2563eb;--hot:#dc2626;--code:#f3f4f6}
+@media (prefers-color-scheme:dark){:root{--bg:#0f1115;--panel:#171a21;--fg:#e5e7eb;--mute:#9ca3af;--line:#2d333d;--edge:#6b7280;--acc:#60a5fa;--hot:#f87171;--code:#0b0d11}}
+*{box-sizing:border-box}
+html,body{margin:0;height:100%;background:var(--bg);color:var(--fg);font:13px/1.4 system-ui,sans-serif;overflow:hidden}
+#top{position:fixed;left:0;right:0;top:0;height:44px;display:flex;gap:8px;align-items:center;padding:0 12px;background:var(--panel);border-bottom:1px solid var(--line);z-index:5}
+#top b{margin-right:4px}
+input,select,button{font:inherit;color:var(--fg);background:var(--bg);border:1px solid var(--line);border-radius:6px;padding:5px 9px}
+button{cursor:pointer}button:hover{border-color:var(--acc)}
+button.on{border-color:var(--acc);color:var(--acc)}
+#q{width:260px}
+#res{position:fixed;top:44px;left:96px;width:380px;max-height:60vh;overflow:auto;background:var(--panel);border:1px solid var(--line);border-radius:6px;display:none;z-index:6}
+#res div{padding:6px 10px;cursor:pointer;border-bottom:1px solid var(--line)}#res div:hover{background:var(--code)}
+#res small,.mute{color:var(--mute)}
+#wrap{position:fixed;left:0;top:44px;bottom:0;right:380px}
+canvas{display:block;width:100%;height:100%;cursor:grab}
+canvas.drag{cursor:grabbing}
+#side{position:fixed;top:44px;right:0;bottom:0;width:380px;background:var(--panel);border-left:1px solid var(--line);overflow:auto;padding:14px}
+#side h3{margin:0 0 2px;word-break:break-all}
+#side pre{background:var(--code);padding:10px;border-radius:6px;overflow:auto;max-height:340px;font:12px/1.45 ui-monospace,Menlo,monospace}
+#side .btns{display:flex;flex-wrap:wrap;gap:6px;margin:10px 0}
+#side .nb{padding:3px 0;cursor:pointer;word-break:break-all}#side .nb:hover{color:var(--acc)}
+#side h4{margin:14px 0 4px;color:var(--mute);font-weight:600;text-transform:uppercase;font-size:11px;letter-spacing:.04em}
+#hud{position:fixed;left:12px;bottom:10px;color:var(--mute);background:var(--bg);padding:4px 8px;border-radius:6px;opacity:.92;pointer-events:none}
+#tip{position:fixed;pointer-events:none;background:var(--panel);border:1px solid var(--line);padding:3px 8px;border-radius:5px;display:none;z-index:7;max-width:50ch;word-break:break-all}
+@media (max-width:800px){#side{width:100%;top:auto;height:45%}#wrap{right:0;bottom:45%}}
+</style></head><body>
+<div id="top"><b>Codegraph</b>
+ <input id="q" placeholder="Search a symbol and add it to the graph" autocomplete="off">
+ <button id="fit" title="Zoom to fit everything">Fit</button>
+ <button id="unpin" title="Release all dragged nodes">Unpin all</button>
+ <button id="reset" title="Back to the file overview">Reset</button>
+ <select id="color" title="Colour by"><option value="c">colour: community</option><option value="d">colour: folder</option></select>
+ <button id="lbl" class="on" title="Show labels">Labels</button>
+</div>
+<div id="res"></div>
+<div id="wrap"><canvas id="c"></canvas></div>
+<div id="side"></div>
+<div id="hud"></div><div id="tip"></div>
+<script>
+"use strict";
+const $=id=>document.getElementById(id), cv=$('c'), cx=cv.getContext('2d'), side=$('side'), tip=$('tip'), hud=$('hud');
+const api=(p,q={})=>fetch('/api/'+p+'?'+new URLSearchParams(q)).then(r=>r.json());
+const el=(t,props={},...kids)=>{const e=document.createElement(t);Object.assign(e,props);kids.forEach(k=>e.append(k));return e};
+
+// ---- state ------------------------------------------------------------------------------------
+let nodes=new Map(), links=[], fileLinks=[], symEdges=new Map(), symInfo=new Map(), total=0;
+let sel=null, hov=null, impact=new Set(), alpha=1, ticks=0, auto=true, showLabels=true, colorBy='c', dirty=true;
+const cam={x:0,y:0,k:1}; let W=0,H=0;
+const dpr=devicePixelRatio||1;
+let css={};
+function readCss(){const s=getComputedStyle(document.documentElement);['bg','fg','mute','edge','acc','hot','line'].forEach(k=>css[k]=s.getPropertyValue('--'+k).trim())}
+matchMedia('(prefers-color-scheme:dark)').addEventListener('change',()=>{readCss();dirty=true});readCss();
+
+function resize(){const r=cv.getBoundingClientRect();W=r.width;H=r.height;cv.width=W*dpr;cv.height=H*dpr;dirty=true}
+addEventListener('resize',resize);resize();
+
+// ---- colours ----------------------------------------------------------------------------------
+const hue=n=>`hsl(${(n*137.5)%360},62%,52%)`;
+function hash(s){let h=0;for(let i=0;i<s.length;i++)h=(h*31+s.charCodeAt(i))|0;return Math.abs(h)}
+const dir=f=>f.split('/').slice(0,-1).slice(0,2).join('/')||'.';
+function colorOf(n){
+  if(colorBy==='d')return hue(hash(dir(n.file)));
+  return n.c<0?'#9ca3af':hue(n.c)}
+
+// ---- graph building ---------------------------------------------------------------------------
+const rnd=()=>(Math.random()-.5);
+function addFile(f){
+  nodes.set('f:'+f.id,{key:'f:'+f.id,t:'f',label:f.id.split('/').pop(),file:f.id,c:f.c,n:f.n,loc:f.loc,rank:f.rank,
+    r:7+Math.sqrt(f.n)*1.7,x:rnd()*W*.8,y:rnd()*H*.8,vx:0,vy:0})}
+function symNode(s,ax,ay){
+  const k='s:'+s.id;symInfo.set(s.id,s);
+  if(nodes.has(k))return nodes.get(k);
+  const n={key:k,t:'s',id:s.id,label:s.name,file:s.file,c:s.c,kind:s.kind,rank:s.rank,
+    r:3.5+Math.min(14,Math.sqrt(s.rank*2500)),x:ax+rnd()*40,y:ay+rnd()*40,vx:0,vy:0};
+  nodes.set(k,n);return n}
+const touched=f=>{for(const n of nodes.values())if(n.t==='s'&&n.file===f)return true;return false};
+function entity(id){
+  const k='s:'+id;if(nodes.has(k))return nodes.get(k);
+  const s=symInfo.get(id);return s&&nodes.get('f:'+s.file)||null}
+function rebuild(){
+  const m=new Map(), tf=new Set();
+  for(const n of nodes.values())if(n.t==='s')tf.add(n.file);
+  const add=(a,b,w,k,q)=>{if(!a||!b||a===b)return;const key=a.key+'>'+b.key,o=m.get(key);
+    if(o){o.w+=w;if(q==='extracted')o.q=q}else m.set(key,{a,b,w,k,q})};
+  for(const l of fileLinks)if(!tf.has(l.s)&&!tf.has(l.t))add(nodes.get('f:'+l.s),nodes.get('f:'+l.t),l.w,l.k,l.k==='import'?'import':'extracted');
+  for(const e of symEdges.values())add(entity(e.s),entity(e.t),1,e.k,e.q);
+  links=[...m.values()];dirty=true}
+function reheat(a=.5){alpha=Math.max(alpha,a);dirty=true}
+
+async function loadOverview(){
+  nodes=new Map();symEdges=new Map();symInfo=new Map();sel=null;impact=new Set();auto=true;ticks=0;
+  hud.textContent='loading...';
+  const d=await api('overview');
+  total=d.total;fileLinks=d.links;d.files.forEach(f=>{fileMeta.set(f.id,f);addFile(f)});rebuild();reheat(1);panel();status()}
+function status(){
+  const ns=[...nodes.values()].filter(n=>n.t==='s').length, nf=nodes.size-ns;
+  hud.textContent=`${nf} files, ${ns} symbols shown · ${total} files indexed · drag a node to pin it · double-click to expand · wheel to zoom · drag background to pan`}
+
+async function expandFile(path){
+  const d=await api('file',{path});const fn=nodes.get('f:'+path);
+  const ax=fn?fn.x:0, ay=fn?fn.y:0;
+  d.symbols.forEach(s=>symNode(s,ax,ay));d.far.forEach(s=>symInfo.set(s.id,s));
+  d.edges.forEach(e=>symEdges.set(e.s+'>'+e.t+e.k,e));
+  nodes.delete('f:'+path);rebuild();reheat(.8);status();return d}
+function collapseFile(path){
+  let x=0,y=0,c=0;
+  for(const [k,n] of nodes)if(n.t==='s'&&n.file===path){x+=n.x;y+=n.y;c++;nodes.delete(k)}
+  if(!c)return;
+  const info=fileMeta.get(path)||{id:path,n:c,loc:0,rank:0,c:-1};
+  addFile(info);const n=nodes.get('f:'+path);n.x=x/c;n.y=y/c;
+  if(sel&&!nodes.has(sel))sel='f:'+path;
+  rebuild();reheat(.5);status();panel()}
+const fileMeta=new Map();
+async function expandSymbol(id){
+  const d=await api('symbol',{id});if(d.error)return;
+  const me=symNode(d,W/2,H/2);
+  d.far.sort((a,b)=>b.rank-a.rank).slice(0,40).forEach(s=>symNode(s,me.x,me.y));
+  d.edges.forEach(e=>symEdges.set(e.s+'>'+e.t+e.k,e));
+  rebuild();reheat(.7);status();return d}
+async function showImpact(id){
+  const d=await api('impact',{id});impact=new Set([id]);
+  d.symbols.forEach(s=>{symNode(s,nodes.get('s:'+id).x,nodes.get('s:'+id).y);impact.add(s.id)});
+  d.edges.forEach(e=>symEdges.set(e.s+'>'+e.t+e.k,e));
+  rebuild();reheat(.7);status();panel()}
+
+// ---- force layout -----------------------------------------------------------------------------
+function step(){
+  const arr=[...nodes.values()], n=arr.length;
+  const cen=new Map();  // symbols of one file are pulled together so an expanded file reads as a cluster
+  for(const a of arr)if(a.t==='s'){const c=cen.get(a.file)||(cen.set(a.file,{x:0,y:0,n:0}),cen.get(a.file));c.x+=a.x;c.y+=a.y;c.n++}
+  for(let i=0;i<n;i++){const a=arr[i];
+    for(let j=i+1;j<n;j++){const b=arr[j];let dx=a.x-b.x,dy=a.y-b.y,d2=dx*dx+dy*dy+.01;
+      if(d2<90000){const f=(1400+(a.r+b.r)*30)/d2;dx*=f;dy*=f;a.vx+=dx;a.vy+=dy;b.vx-=dx;b.vy-=dy}}
+    a.vx-=a.x*.004;a.vy-=a.y*.004;
+    if(a.t==='s'){const c=cen.get(a.file);if(c.n>1){a.vx+=(c.x/c.n-a.x)*.01;a.vy+=(c.y/c.n-a.y)*.01}}}
+  for(const l of links){const a=l.a,b=l.b;let dx=b.x-a.x,dy=b.y-a.y,d=Math.hypot(dx,dy)||1;
+    const rest=a.r+b.r+(a.t==='s'&&a.file===b.file?22:70),f=(d-rest)*.012*(l.q==='extracted'?1:.6);
+    dx*=f/d;dy*=f/d;a.vx+=dx;a.vy+=dy;b.vx-=dx;b.vy-=dy}
+  for(const a of arr){
+    if(a.pin){a.vx=a.vy=0;continue}
+    a.vx*=.8;a.vy*=.8;a.x+=a.vx*alpha;a.y+=a.vy*alpha}
+  alpha=Math.max(.0,alpha*.985);ticks++;
+  if(auto&&nodes.size&&(ticks===60||alpha<.013)){fit()}}
+
+// ---- drawing ----------------------------------------------------------------------------------
+const toS=(x,y)=>[(x-cam.x)*cam.k+W/2,(y-cam.y)*cam.k+H/2], toW=(x,y)=>[(x-W/2)/cam.k+cam.x,(y-H/2)/cam.k+cam.y];
+function fit(){
+  if(!nodes.size)return;let x0=1e9,y0=1e9,x1=-1e9,y1=-1e9;
+  for(const n of nodes.values()){x0=Math.min(x0,n.x-n.r);x1=Math.max(x1,n.x+n.r);y0=Math.min(y0,n.y-n.r);y1=Math.max(y1,n.y+n.r)}
+  cam.k=Math.min(2.5,.9*Math.min(W/(x1-x0||1),H/(y1-y0||1)));cam.x=(x0+x1)/2;cam.y=(y0+y1)/2;dirty=true}
+function neighbours(key){const s=new Set([key]);for(const l of links){if(l.a.key===key)s.add(l.b.key);if(l.b.key===key)s.add(l.a.key)}return s}
+function arrow(x,y,ang,sz){cx.beginPath();cx.moveTo(x,y);cx.lineTo(x-sz*Math.cos(ang-.45),y-sz*Math.sin(ang-.45));
+  cx.lineTo(x-sz*Math.cos(ang+.45),y-sz*Math.sin(ang+.45));cx.closePath();cx.fill()}
+function draw(){
+  cx.setTransform(dpr,0,0,dpr,0,0);cx.clearRect(0,0,W,H);
+  const focus=sel&&nodes.has(sel)?neighbours(sel):null, k=cam.k;
+  // soft hulls around expanded files
+  const groups=new Map();
+  for(const n of nodes.values())if(n.t==='s'){const g=groups.get(n.file)||(groups.set(n.file,{x:0,y:0,n:0,m:[]}),groups.get(n.file));g.x+=n.x;g.y+=n.y;g.n++;g.m.push(n)}
+  for(const [f,g] of groups){const mx=g.x/g.n,my=g.y/g.n;let r=0;g.m.forEach(m=>r+=Math.hypot(m.x-mx,m.y-my));r=r/g.n*1.5+10;
+    const [sx,sy]=toS(mx,my);cx.globalAlpha=.07;cx.fillStyle=colorOf(g.m[0]);cx.beginPath();cx.arc(sx,sy,(r+14)*k,0,6.3);cx.fill();
+    cx.globalAlpha=.7;cx.fillStyle=css.mute;cx.font='11px system-ui';cx.textAlign='center';cx.fillText(f.split('/').pop(),sx,sy-(r+18)*k)}
+  for(const l of links){
+    const on=!focus||(focus.has(l.a.key)&&focus.has(l.b.key)), imp=impact.size&&l.a.id!==undefined&&impact.has(l.a.id)&&impact.has(l.b.id);
+    const [ax,ay]=toS(l.a.x,l.a.y),[bx,by]=toS(l.b.x,l.b.y);
+    cx.globalAlpha=on?(imp?.9:focus?.6:.3):.04;cx.strokeStyle=cx.fillStyle=imp?css.hot:css.edge;
+    cx.lineWidth=Math.min(5,1+Math.log2(l.w))*(imp?1.6:1);
+    cx.setLineDash(l.k==='import'?[1,4]:l.q==='extracted'?[]:[5,4]);
+    cx.beginPath();cx.moveTo(ax,ay);cx.lineTo(bx,by);cx.stroke();
+    if(l.k!=='import'&&k>.35){cx.setLineDash([]);const ang=Math.atan2(by-ay,bx-ax),rr=l.b.r*k+1;arrow(bx-Math.cos(ang)*rr,by-Math.sin(ang)*rr,ang,6)}}
+  cx.setLineDash([]);
+  for(const n of nodes.values()){
+    const [sx,sy]=toS(n.x,n.y), r=n.r*k, dim=focus&&!focus.has(n.key);
+    cx.globalAlpha=dim?.12:1;cx.fillStyle=colorOf(n);
+    cx.beginPath();
+    if(n.t==='f'){const s=Math.max(r*1.6,4);cx.roundRect(sx-s/2,sy-s/2,s,s,s*.22)}else cx.arc(sx,sy,Math.max(r,1.5),0,6.3);
+    cx.fill();
+    if(n.pin){cx.strokeStyle=css.fg;cx.lineWidth=1.2;cx.stroke()}
+    if(n.key===sel||n.key===hov||(n.t==='s'&&impact.has(n.id))){cx.strokeStyle=n.key===sel?css.acc:css.hot;cx.lineWidth=2.5;cx.beginPath();
+      cx.arc(sx,sy,Math.max(r,3)+(n.t==='f'?r*.4:2)+2,0,6.3);cx.stroke()}
+    const show=showLabels&&!dim&&(n.key===sel||n.key===hov||(focus&&focus.has(n.key))||k>1.5||(n.t==='f'&&(n.r>13||nodes.size<80))||(n.t==='s'&&k>.9&&n.r>7));
+    if(show){cx.globalAlpha=1;cx.fillStyle=css.fg;cx.font=(n.key===sel?'bold ':'')+'12px system-ui';cx.textAlign='left';cx.fillText(n.label,sx+Math.max(r,3)+4,sy+4)}}
+  cx.globalAlpha=1}
+(function loop(){if(alpha>.012){step();dirty=true}if(dirty){draw();dirty=false}requestAnimationFrame(loop)})();
+
+// ---- interaction ------------------------------------------------------------------------------
+function pick(ev){const r=cv.getBoundingClientRect(),[wx,wy]=toW(ev.clientX-r.left,ev.clientY-r.top);let best=null,bd=1e9;
+  for(const n of nodes.values()){const d=Math.hypot(n.x-wx,n.y-wy),rr=Math.max(n.r,4/cam.k)+3/cam.k;if(d<rr&&d<bd){bd=d;best=n}}return best}
+let drag=null, pan=null, moved=false;
+cv.addEventListener('pointerdown',e=>{cv.setPointerCapture(e.pointerId);moved=false;const n=pick(e);
+  if(n){drag=n;cv.classList.add('drag')}else{pan={x:e.clientX,y:e.clientY,cx:cam.x,cy:cam.y};cv.classList.add('drag')}});
+cv.addEventListener('pointermove',e=>{const r=cv.getBoundingClientRect();
+  if(drag){moved=true;auto=false;const [wx,wy]=toW(e.clientX-r.left,e.clientY-r.top);drag.x=wx;drag.y=wy;drag.pin=true;reheat(.25);return}
+  if(pan){moved=true;auto=false;cam.x=pan.cx-(e.clientX-pan.x)/cam.k;cam.y=pan.cy-(e.clientY-pan.y)/cam.k;dirty=true;return}
+  const n=pick(e);if(n&&n.key!==hov||!n&&hov){hov=n?n.key:null;dirty=true}
+  if(n){tip.textContent=n.t==='f'?`${n.file}  (${n.n} symbols, ${n.loc} loc)`:`${n.kind} ${symInfo.get(n.id).qn}  ${n.file}`;
+    tip.style.display='block';tip.style.left=e.clientX+14+'px';tip.style.top=e.clientY+14+'px'}else tip.style.display='none'});
+cv.addEventListener('pointerup',e=>{cv.classList.remove('drag');
+  if(drag&&!moved){select(drag.key)}else if(!drag&&pan&&!moved){select(null)}
+  drag=pan=null});
+cv.addEventListener('dblclick',async e=>{const n=pick(e);if(!n)return;n.pin=false;
+  if(n.t==='f')await expandFile(n.file);else await expandSymbol(n.id);select(n.t==='f'?null:n.key)});
+cv.addEventListener('wheel',e=>{e.preventDefault();auto=false;const r=cv.getBoundingClientRect(),mx=e.clientX-r.left,my=e.clientY-r.top;
+  const [wx,wy]=toW(mx,my);cam.k=Math.min(8,Math.max(.05,cam.k*Math.exp(-e.deltaY*.0015)));
+  cam.x=wx-(mx-W/2)/cam.k;cam.y=wy-(my-H/2)/cam.k;dirty=true},{passive:false});
+$('fit').onclick=()=>{auto=true;fit()};
+$('unpin').onclick=()=>{nodes.forEach(n=>n.pin=false);reheat(.6)};
+$('reset').onclick=()=>loadOverview();
+$('color').onchange=e=>{colorBy=e.target.value;dirty=true};
+$('lbl').onclick=e=>{showLabels=!showLabels;e.target.classList.toggle('on',showLabels);dirty=true};
+
+// ---- side panel -------------------------------------------------------------------------------
+function select(key){sel=key;dirty=true;panel()}
+function btn(text,fn,title=''){return el('button',{textContent:text,title,onclick:fn})}
+async function focusSymbol(id,s){  // bring any symbol into the graph and select it
+  if(!nodes.has('s:'+id)){if(s)symInfo.set(id,s);await expandSymbol(id)}
+  const n=nodes.get('s:'+id);if(n){cam.x=n.x;cam.y=n.y;cam.k=Math.max(cam.k,1);select(n.key)}}
+async function panel(){
+  side.replaceChildren();const n=sel&&nodes.get(sel);
+  if(!n){side.append(el('h3',{textContent:'Explore'}),el('p',{className:'mute',textContent:
+    'Each square is a file, sized by symbol count; lines are calls and imports between files. Double-click a file to open it into its functions and classes, double-click a function to pull in everything it calls and everything that calls it. Drag nodes to rearrange and pin them. Search to jump straight to a symbol.'}));return}
+  if(n.t==='f'){
+    side.append(el('h3',{textContent:n.file}),el('div',{className:'mute',textContent:`${n.n} symbols · ${n.loc} lines`}),
+      el('div',{className:'btns'},btn('Expand into symbols',async()=>{await expandFile(n.file);select(null)}),
+        btn(n.pin?'Unpin':'Pin',()=>{n.pin=!n.pin;reheat(.1);panel()})));
+    const near=[];links.forEach(l=>{if(l.a===n)near.push([l.b,'→',l.w]);else if(l.b===n)near.push([l.a,'←',l.w])});
+    if(near.length){side.append(el('h4',{textContent:'Connected files'}));
+      near.sort((a,b)=>b[2]-a[2]).slice(0,25).forEach(([o,d,w])=>side.append(el('div',{className:'nb',textContent:`${d} ${o.file||o.label}  ×${w}`,onclick:()=>{if(o.t==='f'||o.t==='s')select(o.key)}})))}
+    return}
+  const d=await api('symbol',{id:n.id});if(sel!==n.key)return;
+  side.append(el('h3',{textContent:d.qn}),el('div',{className:'mute',textContent:`${d.kind} · ${d.file}:${d.l1}-${d.l2}`}));
+  if(d.sig)side.append(el('div',{style:'margin-top:6px;font-family:ui-monospace,Menlo,monospace;word-break:break-all',textContent:d.sig}));
+  if(d.doc)side.append(el('p',{className:'mute',textContent:d.doc.slice(0,400)}));
+  side.append(el('div',{className:'btns'},
+    btn('Expand neighbours',async()=>{await expandSymbol(n.id);panel()},'pull in callers and callees'),
+    btn(impact.has(n.id)&&impact.size>1?'Hide impact':'Show impact',async()=>{if(impact.size>1){impact=new Set();dirty=true;panel()}else await showImpact(n.id)},'transitive callers: what breaks if this changes'),
+    btn('Collapse file',()=>collapseFile(n.file),'fold this file back into one node'),
+    btn(n.pin?'Unpin':'Pin',()=>{n.pin=!n.pin;reheat(.1);panel()})));
+  const info=id=>symInfo.get(id)||d.far.find(s=>s.id===id);
+  const callers=d.edges.filter(e=>e.t===n.id).map(e=>[info(e.s),e]), callees=d.edges.filter(e=>e.s===n.id).map(e=>[info(e.t),e]);
+  const list=(title,rows)=>{if(!rows.length)return;side.append(el('h4',{textContent:`${title} (${rows.length})`}));
+    rows.slice(0,40).forEach(([s,e])=>s&&side.append(el('div',{className:'nb',onclick:()=>focusSymbol(s.id,s),
+      textContent:`${s.qn}${e.q&&e.q!=='extracted'?'  ?':''}   ${s.file}`})))};
+  list('Called by',callers);list('Calls / uses',callees);
+  side.append(el('h4',{textContent:'Source'}),el('pre',{textContent:d.source||'(no source)'}))}
+
+// ---- search -----------------------------------------------------------------------------------
+let tm;const res=$('res');
+$('q').addEventListener('input',e=>{clearTimeout(tm);const v=e.target.value.trim();
+  if(!v){res.style.display='none';return}
+  tm=setTimeout(async()=>{const d=await api('search',{q:v});res.replaceChildren();
+    d.symbols.forEach(s=>res.append(el('div',{onclick:()=>{res.style.display='none';focusSymbol(s.id,s)}},
+      el('span',{textContent:s.qn}),el('small',{textContent:`  ${s.kind} · ${s.file}`}))));
+    if(!d.symbols.length)res.append(el('div',{className:'mute',textContent:'no matches'}));res.style.display='block'},180)});
+addEventListener('keydown',e=>{if(e.key==='Escape'){res.style.display='none';select(null)}if(e.key==='/'&&document.activeElement!==$('q')){e.preventDefault();$('q').focus()}});
+
+loadOverview();
+</script></body></html>

codegraph_network-0.2.0/src/codegraph/ui.py

@@ -0,0 +1,196 @@
+"""`codegraph ui`: an interactive, local-only graph explorer served from the existing index.
+
+Stdlib only. The page (ui.html) starts from the file-level network and lets you drag nodes, expand a
+file into its symbols, pull in a symbol's neighbours and read source, all through the JSON API below.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import webbrowser
+from collections import Counter, defaultdict, deque
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from urllib.parse import parse_qs, urlparse
+
+from .indexer import index_repo
+from .queries import Graph
+
+OVERVIEW_FILES = 500  # a force layout in a browser canvas stays smooth up to roughly this many nodes
+IMPACT_LIMIT = 80
+HIDDEN = ("module", "impl", "namespace")
+
+
+def _sym(r) -> dict:
+    return {"id": r["id"], "name": r["name"], "qn": r["qualname"], "kind": r["kind"], "file": r["file"],
+            "l1": r["line_start"], "l2": r["line_end"], "rank": r["rank"], "c": r["community"]}
+
+
+class Api:
+    """Read-only queries over one Graph. Every method returns JSON-serialisable data."""
+
+    def __init__(self, graph: Graph):
+        self.g = graph
+
+    def overview(self, limit: int = OVERVIEW_FILES) -> dict:
+        with self.g._lock:
+            db = self.g.db
+            files = {}
+            for r in db.execute(
+                    f"SELECT file, COUNT(*) n, SUM(rank) rank FROM symbols WHERE kind NOT IN {HIDDEN!r} GROUP BY file"):
+                files[r["file"]] = {"id": r["file"], "n": r["n"], "rank": r["rank"] or 0.0, "loc": 0, "c": -1}
+            for r in db.execute("SELECT path, loc, lang FROM files"):
+                if r["path"] in files:
+                    files[r["path"]].update(loc=r["loc"] or 0, lang=r["lang"])
+            votes: dict[str, Counter] = defaultdict(Counter)
+            for r in db.execute(f"SELECT file, community FROM symbols WHERE community>=0 AND kind NOT IN {HIDDEN!r}"):
+                votes[r["file"]][r["community"]] += 1
+            for f, v in votes.items():
+                if f in files:
+                    files[f]["c"] = v.most_common(1)[0][0]
+            keep = {f["id"] for f in sorted(files.values(), key=lambda f: -f["rank"])[:limit]}
+            pair: Counter = Counter()
+            for r in db.execute("SELECT a.file fa, b.file fb FROM edges e JOIN symbols a ON a.id=e.src "
+                                "JOIN symbols b ON b.id=e.dst WHERE a.file != b.file"):
+                if r["fa"] in keep and r["fb"] in keep:
+                    pair[(r["fa"], r["fb"])] += 1
+            links = [{"s": a, "t": b, "w": w, "k": "call"} for (a, b), w in pair.items()]
+            seen = set(pair)
+            for r in db.execute("SELECT file, dst FROM imports"):
+                k = (r["file"], r["dst"])
+                if r["file"] in keep and r["dst"] in keep and k not in seen and r["file"] != r["dst"]:
+                    seen.add(k)
+                    links.append({"s": k[0], "t": k[1], "w": 1, "k": "import"})
+            return {"files": [files[f] for f in keep], "links": links, "total": len(files)}
+
+    def file(self, path: str) -> dict:
+        """Symbols of one file plus every edge that touches them (the far end is described too)."""
+        with self.g._lock:
+            db = self.g.db
+            syms = [_sym(r) for r in db.execute(
+                f"SELECT * FROM symbols WHERE file=? AND kind NOT IN {HIDDEN!r} ORDER BY line_start", (path,))]
+            ids = [s["id"] for s in syms]
+            return {"symbols": syms, **self._edges_of(ids)}
+
+    def _edges_of(self, ids) -> dict:
+        db = self.g.db
+        edges, far = [], {}
+        if not ids:
+            return {"edges": edges, "far": []}
+        mark = ",".join("?" * len(ids))
+        mine = set(ids)
+        for r in db.execute(f"SELECT src, dst, kind, conf FROM edges WHERE src IN ({mark}) OR dst IN ({mark})",
+                            (*ids, *ids)):
+            edges.append({"s": r["src"], "t": r["dst"], "k": r["kind"], "q": r["conf"]})
+            for o in (r["src"], r["dst"]):
+                if o not in mine:
+                    far[o] = None
+        if far:
+            m2 = ",".join("?" * len(far))
+            far_rows = db.execute(f"SELECT * FROM symbols WHERE id IN ({m2}) AND kind NOT IN {HIDDEN!r}",
+                                  tuple(far)).fetchall()
+            ok = {r["id"] for r in far_rows}
+            edges = [e for e in edges if (e["s"] in mine or e["s"] in ok) and (e["t"] in mine or e["t"] in ok)]
+            return {"edges": edges, "far": [_sym(r) for r in far_rows]}
+        return {"edges": edges, "far": []}
+
+    def symbol(self, sid: int) -> dict:
+        with self.g._lock:
+            db = self.g.db
+            r = db.execute("SELECT * FROM symbols WHERE id=?", (sid,)).fetchone()
+            if r is None:
+                return {"error": "unknown symbol"}
+            out = _sym(r)
+            out.update(sig=r["sig"] or "", doc=r["doc"] or "", source=self.g._read(r)[:12000])
+            nb = self._edges_of([sid])
+            out["edges"], out["far"] = nb["edges"], nb["far"]
+            return out
+
+    def impact(self, sid: int, depth: int = 3) -> dict:
+        """Transitive callers (what breaks if this changes), nearest first."""
+        with self.g._lock:
+            seen, q, order = {sid}, deque([(sid, 0)]), []
+            while q and len(order) < IMPACT_LIMIT:
+                u, d = q.popleft()
+                if d >= depth:
+                    continue
+                for v in self.g._in.get(u, ()):
+                    if v not in seen:
+                        seen.add(v)
+                        order.append(v)
+                        q.append((v, d + 1))
+            order = order[:IMPACT_LIMIT]
+            if not order:
+                return {"symbols": [], "edges": []}
+            mark = ",".join("?" * len(order))
+            rows = self.g.db.execute(f"SELECT * FROM symbols WHERE id IN ({mark}) AND kind NOT IN {HIDDEN!r}",
+                                     tuple(order)).fetchall()
+            ids = {r["id"] for r in rows} | {sid}
+            edges = [{"s": u, "t": v, "k": "call", "q": "inferred"} for u in ids for v in self.g._out.get(u, ())
+                     if v in ids]
+            return {"symbols": [_sym(r) for r in rows], "edges": edges}
+
+    def search(self, q: str) -> dict:
+        with self.g._lock:
+            rows = self.g._search_rows(q, 25) if q.strip() else []
+            return {"symbols": [_sym(r) for r in rows if r["kind"] not in HIDDEN]}
+
+
+class Handler(BaseHTTPRequestHandler):
+    api: Api
+    port: int
+    page: bytes
+
+    def log_message(self, *a):  # keep the terminal quiet
+        pass
+
+    def _send(self, body: bytes, ctype: str, code: int = 200):
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        # DNS-rebinding guard: the source of your repo must only reach pages served from this host:port
+        if self.headers.get("Host", "").split(":")[0] not in ("127.0.0.1", "localhost"):
+            return self._send(b"forbidden", "text/plain", 403)
+        u = urlparse(self.path)
+        a = {k: v[0] for k, v in parse_qs(u.query).items()}
+        try:
+            if u.path == "/":
+                return self._send(self.page, "text/html; charset=utf-8")
+            routes = {
+                "/api/overview": lambda: self.api.overview(int(a.get("limit", OVERVIEW_FILES))),
+                "/api/file": lambda: self.api.file(a["path"]),
+                "/api/symbol": lambda: self.api.symbol(int(a["id"])),
+                "/api/impact": lambda: self.api.impact(int(a["id"]), int(a.get("depth", 3))),
+                "/api/search": lambda: self.api.search(a.get("q", "")),
+            }
+            if u.path not in routes:
+                return self._send(b"not found", "text/plain", 404)
+            return self._send(json.dumps(routes[u.path]()).encode(), "application/json")
+        except (KeyError, ValueError):
+            return self._send(b'{"error":"bad request"}', "application/json", 400)
+
+
+def serve(root: str, port: int = 0, open_browser: bool = True) -> None:
+    print(f"codegraph: indexing {root} ...", file=sys.stderr, flush=True)
+    index_repo(root)
+    graph = Graph(root)
+    Handler.api = Api(graph)
+    Handler.page = resources.files("codegraph").joinpath("ui.html").read_bytes()
+    server = ThreadingHTTPServer(("127.0.0.1", port), Handler)  # loopback only: never expose source on the LAN
+    url = f"http://127.0.0.1:{server.server_address[1]}/"
+    print(f"codegraph ui: {url}  (Ctrl+C to stop)", flush=True)
+    if open_browser:
+        threading.Timer(0.3, webbrowser.open, (url,)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+        graph.close()

{codegraph_network-0.1.0 → codegraph_network-0.2.0/src/codegraph_network.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-network
-Version: 0.1.0
+Version: 0.2.0
 Summary: Graph-based code understanding for LLM agents: fewer tokens, better answers
 Author: Oviing
 License-Expression: MIT
@@ -25,6 +25,7 @@ Requires-Dist: mcp>=1.2
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
 Provides-Extra: embed
 Requires-Dist: fastembed>=0.4; extra == "embed"
 Requires-Dist: numpy>=1.24; extra == "embed"
@@ -62,6 +63,17 @@ Or in any MCP client config:
 The index lives in `<repo>/.codegraph/graph.db` and updates incrementally on every server start;
 `reindex` re-scans after edits made outside the session. `.gitignore` it.
 
+## Explore visually
+
+    codegraph -r /path/to/repo ui
+
+Opens an interactive map of the repo in your browser (served from `127.0.0.1` only, nothing leaves your machine).
+You start from the file-level network: lines are calls and imports between files, colour is community (or folder).
+Drag nodes to rearrange and pin them, scroll to zoom, drag the background to pan. Double-click a file to open it
+into its functions and classes; double-click a symbol to pull in everything it calls and everything that calls it.
+The side panel shows the source, callers and callees (click to jump), and **Show impact** highlights the transitive
+callers, i.e. what breaks if the symbol changes. Press `/` to search.
+
 ## Tools
 
 | Tool | Use it to |

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/src/codegraph_network.egg-info/SOURCES.txt

@@ -20,6 +20,8 @@ src/codegraph/review.py
 src/codegraph/server.py
 src/codegraph/store.py
 src/codegraph/tools.py
+src/codegraph/ui.html
+src/codegraph/ui.py
 src/codegraph_network.egg-info/PKG-INFO
 src/codegraph_network.egg-info/SOURCES.txt
 src/codegraph_network.egg-info/dependency_links.txt
@@ -38,4 +40,5 @@ tests/test_queries.py
 tests/test_rank.py
 tests/test_semantic.py
 tests/test_server_cli.py
-tests/test_store.py
+tests/test_store.py
+tests/test_ui.py

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/src/codegraph_network.egg-info/requires.txt

@@ -8,6 +8,7 @@ pyyaml>=6
 [dev]
 pytest>=8
 ruff>=0.6
+numpy>=1.24
 
 [embed]
 fastembed>=0.4

{codegraph_network-0.1.0 → codegraph_network-0.2.0}/tests/test_server_cli.py

@@ -90,7 +90,7 @@ def test_cli_exposes_every_tool():
     assert subactions, "no subcommands registered"
     names = set(subactions[0].choices)
     from codegraph.cli import CLI_SPELLINGS
-    expected = {"serve", "bench", "install", "hook"} | {spelling for spellings in CLI_SPELLINGS.values() for spelling in spellings}
+    expected = {"serve", "ui", "bench", "install", "hook"} | {spelling for spellings in CLI_SPELLINGS.values() for spelling in spellings}
     assert names == expected
     # documented aliases must keep working
     assert {"map"} <= names

codegraph_network-0.2.0/tests/test_ui.py

@@ -0,0 +1,60 @@
+import json
+import threading
+import urllib.error
+import urllib.request
+from http.server import ThreadingHTTPServer
+
+import pytest
+
+from codegraph import ui
+
+from .conftest import FIXTURES, build_graph
+
+
+@pytest.fixture(scope="module")
+def base():
+    graph = build_graph(FIXTURES / "py")
+    ui.Handler.api = ui.Api(graph)
+    ui.Handler.page = b"<html>page</html>"
+    server = ThreadingHTTPServer(("127.0.0.1", 0), ui.Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{server.server_address[1]}"
+    server.shutdown()
+    graph.close()
+
+
+def get(base, path, host=None):
+    req = urllib.request.Request(base + path, headers={"Host": host} if host else {})
+    with urllib.request.urlopen(req) as r:
+        return r.read()
+
+
+def test_page_and_overview(base):
+    assert b"page" in get(base, "/")
+    d = json.loads(get(base, "/api/overview"))
+    assert d["files"] and d["total"] >= len(d["files"])
+    assert any(f["id"].endswith("service.py") for f in d["files"])
+    assert d["links"]
+
+
+def test_file_symbol_impact_search(base):
+    path = next(f["id"] for f in json.loads(get(base, "/api/overview"))["files"] if f["id"].endswith("core.py"))
+    d = json.loads(get(base, f"/api/file?path={path}"))
+    assert d["symbols"]
+    ids = {s["id"] for s in d["symbols"]} | {s["id"] for s in d["far"]}
+    assert all(e["s"] in ids and e["t"] in ids for e in d["edges"])
+    sid = d["symbols"][0]["id"]
+    sym = json.loads(get(base, f"/api/symbol?id={sid}"))
+    assert sym["qn"] and "source" in sym
+    assert "symbols" in json.loads(get(base, f"/api/impact?id={sid}"))
+    hits = json.loads(get(base, f"/api/search?q={d['symbols'][0]['name']}"))["symbols"]
+    assert hits
+
+
+def test_rejects_foreign_host_and_bad_input(base):
+    with pytest.raises(urllib.error.HTTPError) as e:
+        get(base, "/", host="evil.example")
+    assert e.value.code == 403
+    with pytest.raises(urllib.error.HTTPError) as e:
+        get(base, "/api/symbol?id=abc")
+    assert e.value.code == 400

codegraph_network-0.1.0/src/codegraph/__init__.py

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