codecortex 0.11.0__tar.gz → 0.11.1__tar.gz

{codecortex-0.11.0/src/codecortex.egg-info → codecortex-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.0
+Version: 0.11.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -38,6 +38,22 @@ Dynamic: license-file
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:

{codecortex-0.11.0 → codecortex-0.11.1}/README.md

@@ -4,6 +4,22 @@
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:

{codecortex-0.11.0 → codecortex-0.11.1/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.0
+Version: 0.11.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -38,6 +38,22 @@ Dynamic: license-file
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:

codecortex-0.11.1/src/codeintel/__init__.py

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

{codecortex-0.11.0 → codecortex-0.11.1}/src/codeintel/viewer/graph_template.html

@@ -108,8 +108,8 @@
   .detail .dhead .sym{font-size:13.5px; font-weight:600; word-break:break-word; line-height:1.3}
   .detail .dhead .path{font-size:11px; color:var(--muted); margin-top:3px; word-break:break-all}
   .detail .metrics{display:grid; grid-template-columns:1fr 1fr; gap:1px; background:var(--line)}
-  .detail .m{background:var(--panel); padding:10px 13px}
-  .detail .m .k{font-size:10px; text-transform:uppercase; letter-spacing:.06em; color:var(--faint)}
+  .detail .m{background:var(--panel); padding:10px 13px; cursor:help}
+  .detail .m .k{font-size:10px; text-transform:uppercase; letter-spacing:.06em; color:var(--faint); border-bottom:1px dotted currentColor; display:inline-block; padding-bottom:1px}
   .detail .m .v{font-size:17px; font-weight:600; font-variant-numeric:tabular-nums; margin-top:2px}
   .detail .m .v.hi{color:var(--accent)}
   .detail .rel{padding:11px 15px 14px; font-size:11.5px; color:var(--muted)}
@@ -138,6 +138,8 @@
   .btn-primary:hover{filter:brightness(1.06); color:var(--accent-ink)}
   .toast{position:fixed; left:50%; bottom:26px; transform:translateX(-50%) translateY(20px); background:var(--ink); color:var(--bg); font-size:12.5px; font-weight:550; padding:9px 15px; border-radius:9px; opacity:0; transition:opacity .2s,transform .2s; z-index:30; pointer-events:none}
   .toast.show{opacity:1; transform:translateX(-50%) translateY(0)}
+  #tip{position:fixed; z-index:40; max-width:252px; background:var(--ink); color:var(--bg); font-size:11.5px; line-height:1.5; padding:9px 12px; border-radius:9px; box-shadow:var(--shadow); opacity:0; pointer-events:none; transition:opacity .12s}
+  #tip.show{opacity:1}
 
   @media (max-width:640px){
     .detail{width:auto; left:16px; right:16px; top:auto; bottom:16px}
@@ -191,10 +193,10 @@
       <button class="close" id="dclose" aria-label="Close">×</button>
       <div class="dhead"><div class="sym mono" id="d-sym"></div><div class="path mono" id="d-path"></div></div>
       <div class="metrics">
-        <div class="m"><div class="k">Complexity</div><div class="v hi" id="d-cx">—</div></div>
-        <div class="m"><div class="k">Cognitive</div><div class="v" id="d-cog">—</div></div>
-        <div class="m"><div class="k">Callers (in)</div><div class="v" id="d-in">—</div></div>
-        <div class="m"><div class="k">Calls (out)</div><div class="v" id="d-out">—</div></div>
+        <div class="m" data-tip="Cyclomatic complexity — the number of independent paths through the code (each if / for / while / case / && adds one). Higher = more branches to test and reason about. 0 = no branching, or it isn't a function body (e.g. a decorator, import, or class name)."><div class="k">Complexity</div><div class="v hi" id="d-cx">—</div></div>
+        <div class="m" data-tip="Cognitive complexity — how hard the code is for a human to follow. Nested and broken control flow costs more than flat code; higher = harder to read."><div class="k">Cognitive</div><div class="v" id="d-cog">—</div></div>
+        <div class="m" data-tip="Fan-in — how many other symbols call or reference this one. High fan-in = widely depended on, so a change here ripples out to many places."><div class="k">Callers (in)</div><div class="v" id="d-in">—</div></div>
+        <div class="m" data-tip="Fan-out — how many distinct symbols this one calls. High fan-out = it coordinates or depends on a lot of other code."><div class="k">Calls (out)</div><div class="v" id="d-out">—</div></div>
       </div>
       <div class="rel" id="d-rel"></div>
     </div>
@@ -430,6 +432,21 @@ const DATA = __DATA__;
   document.querySelectorAll(".seg-btn").forEach(b=>b.onclick=()=>setLayout(b.dataset.layout));
   $("relayout").onclick=()=>setLayout(curLayout);
 
+  // ---- metric tooltips (custom + reliable — native `title` only re-fires after a fresh mouse "rest",
+  // so it silently skips adjacent cells; a per-cell mouseenter handler always fires) ----
+  const tipEl=document.createElement("div"); tipEl.id="tip"; document.body.appendChild(tipEl);
+  function showTip(el){
+    const t=el.getAttribute("data-tip"); if(!t) return;
+    tipEl.textContent=t; tipEl.classList.add("show"); tipEl.style.left="0px"; tipEl.style.top="0px";
+    const r=el.getBoundingClientRect(), tr=tipEl.getBoundingClientRect();
+    tipEl.style.left=Math.max(8, Math.min(innerWidth-tr.width-8, r.left+r.width/2-tr.width/2))+"px";
+    const y=r.top-tr.height-9; tipEl.style.top=(y<8 ? r.bottom+9 : y)+"px";
+  }
+  document.querySelectorAll(".metrics .m").forEach(m=>{
+    m.addEventListener("mouseenter",()=>showTip(m));
+    m.addEventListener("mouseleave",()=>tipEl.classList.remove("show"));
+  });
+
   // ---- exports ----
   function download(name,text,mime){ try{ const b=new Blob([text],{type:mime||"text/plain"}); const u=URL.createObjectURL(b); const a=document.createElement("a"); a.href=u; a.download=name; document.body.appendChild(a); a.click(); a.remove(); setTimeout(()=>URL.revokeObjectURL(u),1500); toast("Downloaded "+name); }catch(e){ toast("Download blocked here — use Copy"); } }
   function toMarkdown(){

codecortex-0.11.0/src/codeintel/__init__.py

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