025ebc88d6
* feat(resolution): close dynamic-dispatch coverage holes (callback synthesis + django ORM)
Static tree-sitter extraction misses calls whose target is computed or indirect,
so flows through callbacks, observers, and descriptors were absent from the graph.
- callback-synthesizer.ts: whole-graph pass after base resolution. Detects
registrar/dispatcher channels (field-backed observers + string-keyed
EventEmitters), correlates registration sites, and synthesizes
dispatcher->callback `calls` edges (provenance:'heuristic'). Records the
registration site (registeredAt) in edge metadata. Precision guards: named
handlers only, registrar-name match, event fan-out cap.
- frameworks/python.ts + resolution/{index,types}.ts: claimsReference hook +
django ORM resolver (_iterable_class -> ModelIterable.__iter__).
- extraction/tree-sitter.ts: extract named nested functions so inline named
handlers become linkable nodes.
trace(mutateElement, triggerRender) and trace(_fetch_all, execute_sql) now
connect; node count stable (no explosion).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): self-sufficient flow output + fix explore budget regression
- Surface synthesized-edge evidence in trace, the node trail, and context call
paths: a dynamic-dispatch hop now shows "callback via onUpdate @App.tsx:3148"
with the registration site inline (and trace inlines each hop's call-site
source line) -- the exact glue agents previously Read/Grep'd to reconstruct.
- Fix non-monotonic explore output budget: the 500-5000 file tier capped
maxCharsPerFile at 2500, BELOW the <500 tier's 3800, so on god-file projects
(excalidraw's 415 KB App.tsx) one explore returned <1% of the file and forced
a Read. Raised to 6500/file, 28000 total.
- Stop explore from inviting Read: truncation/trim notes said "use Read for
more"; they now steer to another codegraph_explore and treat returned source
as already Read.
Measured on excalidraw: best-case flow answer went from 5 reads / 131s to
0 reads / 73s with ~3-4 codegraph calls.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(agent-eval): coverage probes, block-read hook, and design docs
Dev-only validation harness for the dynamic-dispatch coverage work:
- probe-{trace,node,context,explore}.mjs: drive MCP tools against a built index
without a full agent run.
- block-read-hook.sh + hook-settings.json: PreToolUse experiment that denies
source Reads to measure codegraph sufficiency (forced Read-0).
- docs/design/: callback-edge-synthesis + dynamic-dispatch-coverage playbook.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): bridge React boundaries — re-render + JSX child synthesis
Closes the two dynamic-dispatch hops that broke "state mutation -> on-screen
render" flows in React apps. Both are call-invisible (React-internal) but the
code between them is fully call-connected, so one synthesized edge each makes the
whole flow trace end-to-end.
- reactRenderEdges: setState(...) re-runs the component's render(). For each
class with a render method, link sibling methods calling this.setState ->
render. The setState gate keeps it to React class components.
- reactJsxChildEdges: a component that returns <Child .../> mounts Child. Link
parent -> each capitalized JSX child, resolved to a component/function/class
node (the resolution gate drops TS generics like Array<Foo>). File-oriented,
capped per parent.
- Surface both in synthEdgeNote (trace + node trail) and context call-paths.
Validated on excalidraw: trace(mutateElement, renderStaticScene) now connects in
6 hops across callback -> react-render -> jsx-child; 1 + 46 + 280 synthesized
edges, node count stable (no explosion). Partial coverage is worse than none:
react-render alone raised agent reads (revealed a hop it then drilled); adding
the jsx hop closed the flow and dropped reads to 0-1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(claude): retrieval performance contract + coverage validation methodology
Add a "Retrieval performance & dynamic-dispatch coverage" section so future
changes/PRs don't silently regress agent retrieval:
- the explore call+output budget table by repo size, with the monotonic-per-file
invariant (the bug that started this: <5000 tier's 2500 < <500 tier's 3800).
- the "partial coverage is worse than none" principle.
- the required validation methodology (small/medium/large x >=3 prompts per
language x framework; deterministic probes + agent A/B; pass bar).
- the Excalidraw worked example (before/after numbers) as the template to
replicate for every language/framework.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(claude): use full n=4 measured range in Excalidraw worked example
Best run 0 Read/3 cg/76s; typical ~1 Read/~4 cg; occasional over-drill outlier.
Report the range, not a single run — run-to-run variance is large.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): steer flow questions to codegraph_trace first (tightens variance)
codegraph_trace was absent from every steering intent map — all three guidance
files routed "how does X reach Y" to context+explore, never to the trace tool.
So agents used trace only by chance; when one didn't, it floundered
reconstructing the path with search+callers (an 18-call run vs ~6 for trace-users).
Add codegraph_trace to the intent map + a "flow" common chain (trace from->to
FIRST = the whole path in one call, then ONE explore for bodies) across all three
synced files (server-instructions, instructions-template, .cursor rule).
Validated on excalidraw (hard "to the screen" Q, n=4 before/after):
- call count 3-10 -> 3-4 (over-drill outlier gone)
- duration 64-112s -> 51-74s
- trace adoption 3/4 -> 4/4; search+callers path-reconstruction -> 0
- fully-clean runs (0 Read, 0 Grep) 0/4 -> 2/4; best 3 cg / 0 / 0 / 51s
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Vue SFC template coverage (events + kebab components)
The .vue extractor only parses <script>, so template usage is invisible —
handlers and kebab child components used only in <template> have no edge. Add a
vueTemplateEdges channel (scoped to the <template> block of .vue files):
- event bindings: @click="onClick" / v-on:submit="save" -> handler method/function
(skips inline arrows and $emit; resolves same-file first to avoid cross-app
mis-match in monorepos).
- kebab child components: <el-button> -> ElButton (PascalCase children like
<VPNav/> are already caught by the JSX channel via the SFC component node).
Surface vue-handler in synthEdgeNote (trace/node trail) + context call-paths.
Validated on vue repos (reindex, no node explosion):
- vue-handler edges: vitepress 15, vben 404, element-plus 603 — all precise
(code-login @submit -> handleLogin, register @submit -> handleSubmit, ...).
- callers(handleLogin) now includes the login component (was 0); each monorepo
app's login resolves to its own same-file handler.
- composition: PascalCase + kebab work; element-plus's el-/filename naming
(el-button -> button.vue) is a known library-prefix limitation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Vue validation in coverage matrix + limits
Vue / Nuxt row → ✅ template events + composition (vitepress S / vben M /
element-plus L); 🔬 reactive→render (vue-core Proxy runtime, deferred).
§7: Vue results + the two real limits — composable-destructure handlers
(@click="closeSidebar" from useSidebarControl, a data-flow frontier) and
prefix-convention kebab (el-button→button.vue). Agent reads dropped in every
size; strongest where handlers are local functions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): resolve Vue composable-destructure template handlers
@click="closeSidebar" where `const { close: closeSidebar } = useSidebarControl()`
previously didn't resolve — the handler is a destructured composable return, not a
local fn node. Now: parse the SFC's `use*()` destructures into alias→{composable,
key}, and for an unresolved template handler follow alias → composable → the
returned member (`close`) defined in the composable's file. Precise-only: no
fallback to the composable itself (the component already has a static useX() call
edge), so we add an edge only when the specific returned fn is found.
Validated: vitepress Layout @click→close / @open-menu→open (in composables/
sidebar.ts); sidebar-flow agent run dropped 6→0 reads (best case). element-plus's
fallback-only matches correctly drop to 0; node counts stable; direct handlers
(vben handleLogin) unaffected.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): composable-destructure handlers now resolved (Vue)
@click="closeSidebar" → composable returned fn; vitepress sidebar 6→0 reads.
Remaining Vue limits: prefix-convention kebab + reactive→render frontier.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(extraction): extract function-valued properties of exported-const objects
`export const actions = { default: async () => {...} }` (SvelteKit form actions,
and general JS handler/route/reducer maps) left the arrow functions unextracted —
the walker skips object-literal functions (deliberately, to avoid inline-object
noise like `ctx.set({...})`). So an action's body (and its calls) was invisible.
Now: for an EXPORTED const whose initializer is an object literal, extract each
function-valued property (arrow / function expression) as a function named by its
key and walk its body. extractFunction gains a nameOverride so ONLY this explicit
path names pair-arrows — inline-object arrows reached by the general walker still
fall through to the <anonymous> skip, so no noise returns. JS/TS-gated.
Validated: fixtures extract the actions + walk bodies (default→helper, default→
api.post resolve); SvelteKit detection doesn't break it. Blast radius tiny:
excalidraw +1 node, Python (django) +0, Vue repos +0, realworld +11 (the actions).
Known residual: a `$lib`-alias namespace-member call (`api.post`) from an extracted
action node doesn't resolve even though the same alias resolves for `load` — a
deeper resolver interaction, separate from this extraction change. Local/relative
calls from actions connect fine.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Svelte validation (already well-covered) + actions fix
Svelte/SvelteKit row → already strong (template calls/composition/namespace/load);
+ exported-const object-of-functions extraction. Lesson: measure before assuming
a hole — modern Svelte barely uses on:click={fn}; Svelte needed far less than Vue.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): connect Express inline arrow route handlers to their services
The Express resolver created route nodes but linked handlers via a single regex
whose `[^)]+` broke on inline arrows — so `router.post('/x', async (req,res) =>
{...})` (the dominant modern pattern) connected to NOTHING, and the anonymous
handler's body (the actual request→service flow) was lost. The whole inline-handler
API was unreachable: e.g. realworld's `POST /users/login` route → 0 edges.
Now: match the route head, span the full call with a string-aware balanced-paren
scan, and for an inline arrow handler extract its body's calls (string-aware brace
scan) and attribute them to the route node as `calls` edges. A RESERVED denylist
drops res/req/builtin methods (json, next, status, ...) to keep only business calls.
Named-handler routes keep the existing reference behavior.
Validated: realworld POST /users/login → login (auth.service); 19 precise
route→service edges (was 0) — POST /articles→createArticle, .../favorite→
favoriteArticle, etc., no json/next noise. ghost +65 inline-handler edges. No node
explosion (ghost 40767, parse 3394 unchanged). Framework-scoped: zero blast radius
off Express.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Express validation (inline-handler fix)
Express/Koa row → resolver already handled named handlers; the real hole was
inline arrow route handlers (router.post('/x', async (req,res)=>{...})) — fixed:
route→service body calls (realworld 19 / ghost 65 edges, no explosion). Agent A/B
muddied by repo size (realworld tiny) / complexity (ghost layered API). Lesson
inverse of Svelte: Express's dominant pattern WAS the uncovered one.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record NestJS validation (already well-covered)
NestJS row → resolver handles @decorator routes; DI controller→service
(this.svc.method) resolves correctly at scale (immich: addUsersToAlbum→addUsers,
etc.). Agent A/B: codegraph eliminated Grep (0 vs 3). No dynamic-dispatch hole.
Surfaced a general hygiene gap (not NestJS): committed dist/ build output gets
indexed (no default build-dir ignore) — narrow (real apps gitignore dist/),
deferred as a core-indexer follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Rails RESTful resources routing → controller#action
The rails resolver only saw explicit `get '/x' => 'c#a'` routes, so apps using
the dominant `resources :articles` / `resource :user` RESTful routing had ZERO
route nodes (realworld + spree: 0 routes despite full routes.rb files). The whole
request→controller flow was disconnected.
Fix (frameworks/ruby.ts):
- extract: expand `resources`/`resource` into their REST actions (only/except
filters; pluralize the singular `resource :user` → users_controller), emit a
precise `controller#action` ref per action. Explicit routes now also reference
`controller#action` instead of a bare ambiguous `action`.
- resolve: new `controller#action` pattern → the action method in
<ctrl>_controller.rb (file convention + controller-class fallback).
- claimsReference: claim `controller#action` refs so resolveOne's pre-filter
doesn't drop them before resolve() runs (same hook the django ORM work needed —
these refs name no declared symbol).
Validated: realworld 0→16, forem 0→635 precise route→action edges (GET /articles→
index, resource :user→users#show, etc.), pluralization correct, no node explosion
(route nodes proportional to resources). Agent A/B (forem, large): with codegraph
1-4 reads / 0 grep / 47-53s vs without 4-5 reads / 2-3 grep / 66-85s. Framework-
scoped (zero blast radius off Rails). Residuals: Rails Engine routing (spree
mounts an engine), ActiveRecord dynamic finders (metaprogramming frontier).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Spring bare + class-prefixed route mappings → controller method
The Spring resolver required a string path in the mapping regex, so BARE method
mappings (`@PostMapping` with the path on the class-level `@RequestMapping`) were
missed — the dominant multi-method-controller pattern. realworld's two-action
ArticleFavoriteApi only linked one method; halo had 28 routes for 2444 files.
Fix (frameworks/java.ts):
- Treat class-level `@RequestMapping` as a PREFIX (not a bogus route) and join it
onto each method's path.
- Match verb-specific mappings (@GetMapping/@PostMapping/...) BARE or with a path.
- Also handle method-level `@RequestMapping(value=..., method=RequestMethod.X)`
(older style) — restored after an initial cut dropped it (mall regressed 292→1;
caught by the regression check).
Validated: realworld 13→19, mall 246 (all precise, class prefix joined:
GET /subject/listAll→listAll, POST /articles/{slug}/favorite→favoriteArticle +
DELETE→unfavoriteArticle), no node explosion. DI controller→service resolves
(article→findBySlug, updateArticle→canWriteArticle). Agent A/B (mall cart flow):
with codegraph 0 reads/0 grep vs without 2/2. Residuals: halo's complex custom
patterns (9/29 resolve); Spring Data JPA derived queries (metaprogramming frontier).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Spring validation (bare-mapping routing fix)
Spring row → bare @GetMapping/@PostMapping + class @RequestMapping prefix join →
route→method (realworld 13→19, mall →246); DI controller→service resolves. A
first cut regressed mall 292→1 (dropped @RequestMapping-on-method), caught by the
route-count regression check. Residuals: halo custom patterns, JPA derived queries.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Django DRF router.register → ViewSet
Django's ORM (_iterable_class, prior work) and URL routing (path/url/as_view→view)
were already covered. The remaining hole: DRF `router.register(r'articles',
ArticleViewSet)` — the core CRUD endpoints — wasn't extracted (only path()/url()),
so a DRF API's main resources connected to nothing (realworld's ArticleViewSet:
0 callers).
Fix (frameworks/python.ts): match `.register(r'prefix', XViewSet)` → route→ViewSet
class. The STRING first arg distinguishes DRF router.register from
`admin.site.register(Model, Admin)` (model class first arg); View/ViewSet suffix
keeps it to viewsets. The ViewSet class resolves via the existing View/ViewSet
pattern.
Validated: realworld VIEWSET /articles → ArticleViewSet (was 0). Narrow in corpus
(realworld 1 router; wagtail=path, saleor=GraphQL) but real for DRF-router APIs.
Agent A/B (wagtail Page flow, medium): with codegraph 4-7 reads / 1-4 grep / 58-81s
vs without 7-9 reads / 6 grep / 82-86s. No regression (wagtail/saleor route counts
unchanged — purely additive). Residuals: signals, DRF inherited viewset actions,
GraphQL resolvers.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Laravel route → precise Controller@method (not bare action)
extractLaravelHandler discarded the controller: `Route::get([UserController::class,
'index'])` and `'UserController@index'` both emitted a BARE `index` ref. With the
route in routes/api.php (not the controller file), name-matching mis-resolved every
common action to the WRONG controller — realworld's GET user → ArticleController.index
(should be UserController), GET articles/feed → ArticleController (should be
FeedController), etc. The routes existed but pointed at the wrong handler.
Fix (frameworks/laravel.ts): emit precise `Controller@method` (array + string
syntax, namespace-stripped) and `claimsReference` it so resolveOne's pre-filter
doesn't drop it before Pattern-4 resolveControllerMethod runs (the recurring hook,
also needed by django ORM + Rails routing).
Validated: realworld all routes now resolve to the correct controller; bookstack
267/332 precise (GET pages → PageApiController.list, array syntax). No node
explosion. Agent A/B (bookstack page-view, large): with codegraph 2-3 reads / 1-2
grep / 51-60s vs without 4-6 / 3-5 / 60-74s. Residuals: firefly's fluent
->uses()/['uses'=>...] handler format (3/568 resolve), Eloquent dynamic finders.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Gin/chi routes on group vars (any receiver, not just r/router)
The route regex matched only `(router|r|mux|app|e).METHOD(...)`, but real Gin/chi
apps route on GROUP variables — `v1.GET`, `PublicGroup.GET`, `userRouter.POST` —
so group-routed apps connected almost nothing: gin-vue-admin had 4 routes for 625
files. Broaden the receiver to ANY identifier; the verb + string-path + handler-arg
gates keep it route-specific (e.g. `http.Get(url)` has no handler arg, so it's
excluded).
Validated: gin-vue-admin 4→259 routes, 257 resolve precisely (POST createInfo→
CreateInfo, GET getInfoList→GetInfoList); realworld stable 24→25 (no regression);
no garbage (257/259 resolve, not false positives), node count proportional. gitness
(chi, custom handlers) is a residual (26/321). Inline `func(c *gin.Context){...}`
handlers still lose their body (anonymous, like Express was) — separate residual.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Gin validation (group-var routing fix)
Gin/chi row → routes on ANY group var (v1.GET/PublicGroup.GET), not just r/router
(gin-vue-admin 4→259 routes). Agent A/B: 0 reads/0 grep/26-30s vs 3/3/52-53s —
cleanest backend win yet. Residuals: inline func handlers, gitness chi custom.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): ASP.NET feature-folder detection + bare attribute routes
Two holes left ASP.NET apps disconnected:
1. detect() only fired on a /Controllers/ dir, root Program.cs/Startup.cs, or a
.csproj (which often isn't in the indexed source set). Feature-folder apps
(realworld: Features/*/FooController.cs, subdir Program.cs) were never detected
→ 0 routes despite a full set of controllers. Broaden: scan Controller/Program/
Startup .cs source for ASP.NET signatures ([ApiController]/[Route]/[Http*],
ControllerBase, MapControllers, WebApplication, Microsoft.AspNetCore).
2. The attribute regex required a string path, so BARE [HttpGet] (route on the
class [Route("[controller]")]) was missed — eShopOnWeb was 24 bare / 2 string.
Match bare-or-with-path + join the class [Route] prefix (like the Spring fix).
No claimsReference needed: ASP.NET attribute routes are co-located IN the controller
with the action, so the bare method-name ref resolves same-file.
Validated: realworld 0→19 routes (all precise: GET /articles→Get, POST /articles→
Create, class prefix joined), eShopOnWeb 9→33. Route→action correct + co-located.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record ASP.NET validation (detection + bare-attribute fix)
ASP.NET Core row → feature-folder detection (realworld 0→19, was undetected) +
bare [HttpGet] / class [Route] prefix (eShopOnWeb 9→33, jellyfin 362→399). No
claimsReference needed (routes co-located in controller). Agent A/B (eShop): 1-2
reads/0 grep vs 6-7/1-6. Residual: EF Core LINQ.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Flask/FastAPI route holes + Python builtin-name handler guard
Three fixes that connect the request→route→handler flow for Flask and
FastAPI. Validated S/L: fastapi-realworld 12→20, flask-microblog 6→27,
Netflix dispatch 290/290 (100%), redash decorator routes 6/6; canonical
flows trace end-to-end (login→get_user_by_email, create_user→from_dict).
- Flask: the route regex required `def` immediately after `@x.route(...)`,
so an intervening decorator (@login_required, @cache.cached) or stacked
@x.route lines (one view bound to several URLs) dropped the route.
Switch to the findHandler scan (match the decorator, then find the next
def) like FastAPI — skips intervening decorators.
- FastAPI: the path regex `[^'"]+` rejected the empty path `@router.get("")`
(router/prefix-root routes, frequently multi-line). Allow empty path +
guard the route name against a trailing space.
- Python builtin-name guard (src/resolution/index.ts): a handler named
after a Python builtin method (index/get/update/count…) was filtered by
isBuiltInOrExternal and lost its route→handler edge. Mirror the
dotted-method branch's knownNames guard onto the bare branch — a bare
name a declared symbol owns is a real target, not a builtin call.
+2 legit edges on realworld, 0 change on the django control (precision held).
Tests: new Flask (intervening/stacked decorator) and FastAPI (empty-path,
multi-line) extractor cases + a Flask end-to-end integration test (a view
named `index` behind @login_required). Also corrects 6 pre-existing stale
Laravel/Rails route-ref assertions surfaced by the suite — they expected
the old bare action name, but the resolvers now emit precise
controller@action / controller#action (from earlier precision commits).
Full suite green (781 passed).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Flask/FastAPI validation (decorator + builtin-name fixes)
Matrix row Python/Flask+FastAPI 🔬→✅ and a §7 note: Flask intervening/
stacked decorators, FastAPI empty-path routes, the Python builtin-name
handler guard, S/L numbers, the login-auth A/B (0–1 read/0 grep with vs
3 read/2 grep without), and residuals (Flask-RESTful class-based
add_resource; redash JS file-route false-positives).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Drupal route-handler resolution (claimsReference, single-colon controllers, contrib detection)
The *.routing.yml extractor and _controller/_form resolver existed but two
gaps left most routes unlinked. Validated S/M/L: admin_toolbar 0→14 (14/14),
webform 144/208, drupal-core 536→731/836 (87%); canonical flow traverses
(getAnnouncements ← /admin/announcements_feed); node count unchanged.
- claimsReference: Drupal handler refs are FQCNs (\Drupal\…\Class::method),
bare form classes (\…\SettingsForm), or single-colon controller-services
(\…\Controller:method). Only the ::method shape survived resolveOne's
pre-filter (its member is a known method name); the bare-FQCN forms and
single-colon controllers were dropped before resolve() ran. Claim FQCN /
Class:method / hook_* refs (same pattern as Rails controller#action).
- Single-colon controller match: broaden the controller regex from :: to
:{1,2} and tighten the _form branch to !name.includes(':').
- Detection: detect() only checked composer `require` for a drupal/* dep, but
a contrib module often has an empty require and is identified only by
"name":"drupal/<m>" + "type":"drupal-module" (admin_toolbar → 0 routes).
Broaden to composer name/type + a *.info.yml fallback.
Remaining unresolved is the entity-annotation handler frontier
(_entity_form: type.op) and OOP #[Hook] attributes (Drupal 11 moved ~all
procedural hooks to attribute methods — out of scope here). Tests: contrib
detection, *.info.yml fallback, claimsReference, single-colon controller.
Full suite green (787 passed).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Drupal validation (claimsReference + contrib detection)
Add the PHP/Drupal matrix row (✅) and a §7 note: the claimsReference
pre-filter fix for FQCN/single-colon handlers, broadened contrib detection,
S/M/L numbers (admin_toolbar 0→14, webform 144/208, core 536→731), the
route→controller A/B (0 read/1 grep with vs 1 read/2 grep+glob without), and
the frontier residuals (entity-annotation handlers, OOP #[Hook] attributes).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Axum chained methods + namespaced handlers
The Axum route extractor used a flat regex that captured only the first
method(handler) of a .route() call and only a bare \w+ handler, so two
dominant Axum idioms broke:
- method chains: .route("/user", get(get_current_user).put(update_user))
emitted no node for the .put arm — half the API was missing.
- namespaced handlers: get(listing::feed_articles) captured `listing`
(the module), so the route resolved to nothing.
Rewrite with a balanced-paren scan of each .route(...) call, a route node
per chained method, and last-::-segment handler names. realworld-axum
12→19 routes, 19/19 resolved (every chained PUT/DELETE/POST now present,
feed_articles resolves). Rocket needed nothing (550/556, 99%, attribute
macros); crates.io confirms namespaced axum handlers resolve.
Residual frontier: actix runtime routing web::get().to(handler) (the
dominant actix style, unextracted; attribute macros 35/51). Fix is
Axum-scoped — the attribute/actix/Rocket path is untouched. Tests: chained
methods + multi-line namespaced handler. Full suite green (789 passed).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Rust/Axum validation (chained methods + namespaced handlers)
Update the Rust matrix row 🔬→✅ and add a §7 note: the Axum chained-method
+ namespaced-handler fix (realworld-axum 12→19, 19/19), Rocket already 99%,
crates.io (utoipa routes! macro frontier + SvelteKit frontend routes), the
update-user A/B, and the actix runtime-routing frontier.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Vapor grouped/RouteCollection routing (was 0 routes on real apps)
The Vapor extractor only matched (app|router|routes).METHOD("path", use:
handler), but real Vapor apps route on a grouped builder inside
RouteCollection.boot(routes:): `let todos = routes.grouped("todos");
todos.get(use: index)` — any var receiver, no path arg (the path is the
group prefix). Every real app tested extracted 0 routes (template,
SteamPress, SwiftPackageIndex-Server, penny-bot, Feather).
Rewrite the extractor:
- any receiver (\w+), not just app/router/routes;
- optional path segments that may be non-string (User.parameter, :id, a
path constant) — the `use:` keyword discriminates a route from
Environment.get("X") / req.parameters.get("X");
- a group-prefix map from `let X = Y.grouped("a")` and
`Y.group("a") { X in }` so a grouped/nested route gets its full path
(todo.delete(use: delete) -> DELETE /todos/:todoID).
Result: vapor-template 0→3 (3/3, nested path exact), SteamPress 0→27
(27/27), SwiftPackageIndex-Server 0→14 (14/14 handler resolution).
Canonical flow traverses (createPostHandler <- GET /createPost ->
createPostView). Route names now carry a leading slash (GET /users),
consistent with the other frameworks.
Frontier: typed-route enums (SPI's SiteURL.x.pathComponents — handler
resolves, path label only) and closure handlers (app.get("x"){ } —
anonymous). Tests: grouped RouteCollection, self.handler + non-string
segments, use:-discriminator. Full suite green (792 passed).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Vapor validation (grouped RouteCollection routing)
Update the Swift/Vapor matrix row ⬜→✅ and add a §7 note: the extractor was
dead on real apps (0 routes everywhere); rewrote for any receiver, optional
non-string paths, .grouped/.group{} prefix tracking, and the use:
discriminator. S/M/L all 100% handler resolution (template 0→3, SteamPress
0→27, SPI 0→14), the create-post A/B (0 read/0 grep with vs 1–4 read
without), and frontiers (typed-route enums, closure handlers).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): React Router <Route> JSX route extraction
react.ts extracted components/hooks and Next.js file routes but returned
references: [], so React Router <Route> declarations produced no route
nodes or route→component edges. Add <Route> JSX extraction: scan a window
after each <Route (so the nested > in element={<Comp/>} doesn't truncate
the match), pull path="…" + component={C} (v5) or element={<C/>} (v6) in
any attribute order, emit a route node + component reference (resolved by
the existing PascalCase resolveComponent). The <Routes> container is
excluded via the \b boundary.
react-realworld 0→10 routes, 10/10 resolved (/login→Login,
/editor/:slug→Editor, /@:username→Profile). No regression on excalidraw
(9,290 nodes, 46 react-render synth edges intact, 0 false routes). Tests:
v5 component=, v6 element=, <Routes>-container guard. Suite green (794).
Frontier: object data-router createBrowserRouter([{path,element}]) (modern
v6) is object-based not JSX — not covered.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record React Router routing (the React row's routing half)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): actix-web builder-API routing (web::resource / .to(handler))
Actix's attribute macros were covered, but the dominant actix style is the
builder API — web::resource("/path").route(web::get().to(handler)),
web::resource("/").to(handler) (all methods), and App .route("/path",
web::get().to(handler)). The handler is in .to(handler), not get(handler),
so the Axum .route scan extracted nothing — actix-examples had 80
web::resource calls all unlinked.
Add an actix block: scan each web::resource("/path") (bounding its method
chain at the next resource) for web::METHOD().to(h) pairs, fall back to a
direct .to(h) (method ANY), plus the App-level .route("/x",
web::METHOD().to(h)) form. actix-examples 51→128 routes, 35→112 resolved
(GET /user/{name}→with_param, POST /user→add_user). No regression on Axum
(realworld-axum still 19/19). Tests: resource+route, resource direct .to,
App-level route. Suite green (797).
Frontier: web::scope("/api") prefixes not prepended; anonymous .to(|req|…)
closures have no named target.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record actix builder-API routing validation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(extraction): Flutter setState→build synthesis + Dart method body ranges
Two changes that connect Flutter's reactive dispatch:
- Dart method ranges (foundational): Dart models a method body as a SIBLING
of the method_signature node, so every Dart method node had endLine ==
startLine (signature only) — body-level analysis (callees, context slices,
the synthesizer's body scan) saw only `void f() {`. Extend endLine to the
resolved body in the shared createNode, guarded to only ever extend
(child-body grammars are a no-op; controls excalidraw 9,290 / django 302
unchanged).
- Flutter setState→build synthesizer channel (the Dart analog of react-render):
for each Dart class with a `build` method, link sibling methods whose body
calls setState( → build. setState re-runs build (Flutter-internal, no static
edge), so "tap → handler → setState → rebuilt UI" dead-ended at setState.
counter initState→build, books build→BookDetail/BookForm. Widget composition
needs no synthesis — Dart widgets are explicit constructor calls, already
static (compass_app build→ErrorIndicator/HomeButton). Tests: Dart method
spans its body; Flutter handler→build synthesis end-to-end. Suite green (798).
Frontier: MVVM Command/ChangeNotifier dispatch (no setState) + Navigator.push
route-as-widget navigation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Dart/Flutter validation (setState→build + method ranges)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Spring Boot Kotlin routing (.kt + fun handlers)
Kotlin had zero framework coverage — no resolver listed kotlin, and the
Spring resolver was languages:['java'] with a .java-only extract gate and a
Java-syntax handler regex (public X name()). Spring Boot Kotlin apps (same
@GetMapping/@RestController annotations, .kt files) extracted 0 routes.
Extend the Spring resolver: languages ['java','kotlin'], accept .kt, and add
a Kotlin `fun name(` alternative to the handler-method regex (Kotlin has no
access modifier; the return type follows the name). Also allow Kotlin class
modifiers (open/data/sealed) in the class @RequestMapping-prefix detection,
and tag route/ref language per file.
spring-petclinic-kotlin 0→18 routes, 18/18 resolved; class @RequestMapping
prefixes join, stacked annotations skipped, DI controller→repo resolves
(showOwner ← GET /owners/{ownerId} → OwnerRepository.findById). Java Spring
unchanged (realworld 19/19 — the Kotlin fun and Java public-X alternatives
are disjoint per language). Jetpack Compose composition already works
(@Composable→child are plain function calls). Tests: Kotlin @GetMapping+fun,
class-prefix + stacked annotation. Suite green (800).
Frontier: Ktor inline-lambda routing, Compose recomposition, coroutines/Flow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Kotlin validation (Spring Boot Kotlin + Compose)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Lua/Luau validation (module dispatch already covered)
Measure-first: Neovim/Roblox dispatch is module-heavy (require + cross-file
mod.fn calls), already resolved by general import+name resolution
(telescope.nvim 220 imports + 335 cross-file calls; traces end-to-end). The
matrix's assumed "callback synthesizer" hole isn't real — event-callback
registration (keymap/autocmd/:Connect) is predominantly inline anonymous
closures (corpus ~12 inline vs ~2 named), too rare to synthesize. A/B: 0
read/0 grep with codegraph vs 1 read without. No code change; validated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Play Framework conf/routes → controller routing (Scala/Java)
Play declares routes in an extensionless conf/routes file (GET /computers
controllers.Application.list(p: Int ?= 0)) the file walk never indexed
(isSourceFile requires an extension), so Play apps had 0 route nodes.
- grammars.ts: add isPlayRoutesFile (conf/routes + *.routes), opt it into
isSourceFile, and map it to the no-grammar (yaml-style) path in
detectLanguage so the framework resolver extracts it. Narrow match — only
ADDS Play routes files, never affects other indexing.
- play.ts: a Play resolver — detect (build.sbt/conf), extract (parse each
METHOD /path Controller.action(args) line, drop package + args), resolve
(Controller.action → the action method in that controller class),
claimsReference for the dotted Controller.action handler.
computer-database 0→8 routes, 7/8 resolved (the 1 unresolved is
controllers.Assets.versioned — Play's framework controller, external);
starter 0→4 (3/4). Flow connects request→route→controller→DAO. No-regression
(excalidraw 9,290 / suite unchanged). Tests: routes parse + `->` include
skipped, conf/routes file detection.
Frontier: SIRD programmatic routers (-> include + case GET(p"/x")) + Akka
actor message→handler.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Scala/Play validation (conf/routes → controller)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(extraction): C++ inheritance (base_class_clause) + virtual-override synthesis
C/C++ direct dispatch already resolves well (redis 29k / leveldb 1.4k
cross-file calls). Two changes close the C++ virtual-dispatch gap:
- extractInheritance handled base_clause (PHP) but not C++'s
base_class_clause, so C++ `extends` edges were missing/partial. Add the
C++ branch (emit an extends ref per base type, skipping access
specifiers) — leveldb extends 219→298.
- cpp-override synthesizer channel (the C++ analog of react-render): for
each extends edge, link each base method → the subclass override of the
same name, so trace/callees from a virtual/interface method reach the
implementation. Gated to C++, capped per class. leveldb 12 precise edges
(Iterator::Next/Seek/Prev → MergingIterator), 0 on C (redis) and TS
(excalidraw). Test: base virtual → subclass override bridge.
Frontier: C callback structs (cmd->proc() → 422-way fan-out, too noisy)
and C++ pure-virtual base methods (declarations aren't nodes, so those
overrides can't bridge). Suite green (804).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record C/C++ validation (inheritance fix + override synthesis)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): React Router object data-router + Next.js route precision
- Object data-router (v6.4+): createBrowserRouter([{ path, element: <Comp/> }])
/ { path, Component: Comp } — extract route + component (gated to files using
the data-router API; requires a component so a stray `path:` field isn't a route).
- Next.js precision: filePathToRoute treated config files (next.config.mjs,
vite.config.ts) and a `nextjs-pages/` dir (substring of "pages/") as routes.
Require a real page extension (.tsx/.ts/.jsx/.js), exclude *.config.* and
_app/_document, and match pages/ + app/ as path SEGMENTS. bulletproof-react
4 bogus config "routes" → 0.
Frontier: lazy data-router routes (path: paths.x.path + lazy: () => import())
use variable paths + lazily-imported modules — no literal path/named component.
Tests: object-router literal form, config/nextjs-pages exclusion. Suite 806.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Flask-RESTful add_resource + tuple methods + broader detection
Three Flask gaps closed (redash Flask-RESTful 6→77 py routes; flask-realworld 0→19):
- Flask-RESTful: api.add_resource(ResourceClass, '/path') (+ redash's
add_org_resource) now extracts a route per path referencing the Resource
class, whose get/post verb methods resolve as the handlers.
- Tuple methods: @x.route('/p', methods=('POST',)) — the method regex only
accepted a list [...]; now accepts a tuple (...) too, so POST/DELETE routes
aren't mislabeled GET.
- Detection: detect() only checked root app.py for the literal Flask(__name__);
broadened to requirements/pyproject/Pipfile/setup.py + any entrypoint file
(root or subdir, e.g. conduit/app.py) that imports flask and instantiates
Flask(...). flask-realworld (subdir app-factory) 0→19; django not falsely
detected.
Tests: tuple methods, add_resource. Suite green (808).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record frontier pass; test(go): gorilla/mux subrouter coverage
Frontier triage after the main sweep — tractable partials closed (React object
data-router, Next.js false-positive fix, Flask-RESTful add_resource, Flask
tuple methods + detection, gorilla/mux confirmed), and the genuinely
hard/low-precision ones (C callback fan-out, metaprogramming finders, reactive
runtimes, Akka, anonymous closures, lazy data-router, C++ pure-virtual) left
documented with rationale. Adds a gorilla/mux subrouter-var HandleFunc test
(confirms the any-receiver handling already covers it).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(benchmarks): A/B with/without codegraph across every language (S/M/L)
37-cell matrix (every flow-relevant language × small/medium/large indexed
repos): a headless agent answers one canonical flow question per repo, with the
codegraph MCP vs without any MCP. Fresh re-index per cell so the with-arm
reflects current resolvers.
Result: 75% fewer file reads with codegraph (40 vs 158 across cells), ~70%
fewer greps, never more reads in any cell. Biggest wins on medium/large
backends (excalidraw 0R vs 9R, spring-halo 0R vs 9R+8 Bash, jellyfin 4R vs 13R+
21 Bash + a spawned sub-agent); tie zone on tiny repos where the flow fits in
1-2 files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): self-sufficient codegraph_trace + CODEGRAPH_MCP_TOOLS allowlist
codegraph_trace now returns a complete flow dossier in one call: each hop with its full body inlined (not just the call-site line), plus the destination's own outgoing calls — the last mile agents otherwise explore/Read to get. Validated by A/B (arm I, 6 repos x 2): >= baseline on reads/turns/cost with no wall-clock regression, because one richer trace call displaces the explore+node+Read follow-ups. Sufficiency, not steering: complete context is what stops further investigation.
Also adds CODEGRAPH_MCP_TOOLS, an optional comma-separated allowlist that trims the exposed MCP tool surface (inert when unset); used to run the tool-ablation experiment cleanly, and useful for constraining an agent to a minimal surface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(benchmarks): call-sequence + tool-ablation analysis; agent-eval arms harness
Records why codegraph read savings (-75%) under-convert to wall-clock (-16%): the bottleneck is round-trips + the synthesis turn, not reads. Ablation (arms A-I) shows explore is 68% of payload but load-bearing, trace is path-scoped but under-adopted, instruction/description steering cannot match an append-prompt's salience (and regresses), and the shippable win is making the trace output sufficient (arm I). Adds harness: seq-matrix, run-arms/arms-*, parse-arms.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): line-number codegraph_node + codegraph_trace source output
node's code block and trace's inlined hop/destination bodies now carry cat -n line numbers (reusing numberSourceLines, matching codegraph_explore and Read), so the agent can cite or edit exact lines without re-Reading the file just to get them. Consistency across the code-returning tools + edit-workflow sufficiency.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolution): Java/Kotlin interface & abstract dispatch synthesis
A call through an injected interface (Spring @Autowired svc.list()) or an abstract base dead-ended at the interface method — no static edge to the implementation — so request->service->impl flows broke at the DI boundary. Adds interfaceOverrideEdges: for each class implementing an interface (or extending an abstract base), synthesize interface/base-method -> same-name override 'calls' edges (JVM-gated, capped per class, overload-aware), with an 'interface-impl' trace label. trace + callees now follow the flow into the implementation.
Validated on spring-mall: 310 synth edges, node count unchanged (edges only); trace(PmsProductController.getList, PmsProductServiceImpl.list) connects in 3 hops (controller -> service interface -> impl) where it previously dead-ended at the interface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(playbook): record Java/Kotlin interface-DI synthesizer (probe-validated; agent A/B adoption-gated)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): codegraph_explore surfaces the execution flow from its named symbols
Agents call explore far more than trace and pass a bag of symbol names that spans the flow they're after. explore now resolves those names and surfaces the longest call path AMONG them — riding synthesized dynamic-dispatch edges (callback/react-render/jsx/interface-impl) — leading the output with it, so a flow question answered via explore gets the trace-quality path without switching tools.
Precision: ambiguous tokens disambiguated by CO-NAMING (keep candidates whose qualifiedName SEGMENT matches another named token, so 'list' resolves to PmsProductServiceImpl::list not OmsOrderService::list); BFS anchored at named symbols on both ends with <=1 consecutive unnamed bridge (crosses a missing intermediate, never wanders a god-function's fan-out). Validated by probe: spring-mall getList->service-interface->impl (3 hops); excalidraw mutateElement->triggerUpdate->[callback]->triggerRender->[react-render]->render->[jsx]->StaticCanvas (full re-render chain). No flow section on fuzzy queries (safe). Suite green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(mcp): explore-flow resolves qualified Class.method query tokens
The agent often passes fully-qualified names to explore (PostEndpoint.publishPost, PmsProductServiceImpl.list) — its most precise input. The tokenizer's file-extension strip mangled Class.method into Class (treating .method as an extension), then the identifier filter dropped anything with a dot, throwing the method away. Now strips only REAL file extensions and keeps qualified tokens, which findAllSymbols resolves exactly; disambiguates ambiguous SIMPLE names by whether their container class is also named (segment match). Validated: 'PmsProductController.getList PmsProductServiceImpl.list' now surfaces getList->interface->impl. (spring-halo's publish flow stays absent — it's reactive/reconciler dispatch with no static edges, a coverage frontier, not an explore-flow gap.)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(claude): record the 'adapt the tool to the agent' retrieval principle
The lever that decides whether a retrieval change lands: make a tool the agent already calls do more with the input it already gives; changes that need the agent to behave differently (different tool, query, examples) hit codegraph's low-salience channels and don't land. Captures the validated evidence (sufficiency + explore-flow pass; steering + new-tools + context-fuzzy-flow fail) and points coverage as the remaining lever.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: correct 'cost stays flat' → neutral-to-lower (excalidraw with/without A/B)
Fresh with-vs-without A/B on excalidraw (current build, n=3): 3x faster (49s vs 145s), 15x fewer tool calls, ~0 vs 23 reads, and -40% cost ($0.41 vs $0.68). Cost is neutral-to-lower, not flat — compact codegraph answers cache across turns while the without-arm's read/grep thrash is fresh, poorly-cacheable input. Recorded in call-sequence-analysis.md; corrected the CLAUDE.md optimization-target note (still: don't optimize for cost; target wall-clock + tool-call count).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(benchmarks): current-build A/B on all 7 README repos + fix token-measurement bug
Re-ran the README benchmark on the current build (7 repos reindexed, median of 4): avg 35% cost / 57% tokens / 46% time / 71% tool calls saved — reproduces the published README (35/59/49/70), no regression. Adds bench-readme.sh + parse-bench-readme.mjs harness.
Fixes a token-measurement bug: result.usage is last-turn-only in current Claude Code; must sum per-turn assistant usage for cumulative tokens. Corrects the earlier excalidraw note (its '-34% tokens' was off this bug; real ~90%) and the cost MECHANISM (volume/fewer-turns, not cache-ability — the without-arm's huge token volume is mostly cheap cache-reads, so token savings 57% > cost savings 35%). Cost/time were always correct.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: finalize 0.9.4 — consolidate CHANGELOG + re-validate README benchmark
Folds the framework sweep + retrieval work into [0.9.4] (2026-05-24). README benchmark table refreshed with current-build medians (avg 35% cost / 57% tokens / 46% time / 71% tool calls) + a v0.9.4 re-validation note.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(readme): add codegraph_trace to the MCP Tools table
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
648 lines
40 KiB
Markdown
648 lines
40 KiB
Markdown
# Changelog
|
||
|
||
All notable changes to CodeGraph are documented here. Each entry also ships as
|
||
a [GitHub Release](https://github.com/colbymchenry/codegraph/releases) tagged
|
||
`vX.Y.Z`, which is where most people will look.
|
||
|
||
This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
||
and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||
|
||
## [0.9.4] - 2026-05-24
|
||
|
||
### Added
|
||
- **Framework-aware route resolution — `request → route → handler → service`
|
||
flows now resolve end-to-end across the supported stacks.** Added or fixed
|
||
routing for Express (inline arrow handlers → services), Rails, Spring (Java +
|
||
Kotlin; bare and class-prefixed mappings), Django/DRF (`router.register` →
|
||
ViewSet), Laravel (`Controller@method`), Flask/FastAPI (decorator stacks,
|
||
empty-path routers, Flask-RESTful `add_resource`), Gin/chi (group-var routing),
|
||
ASP.NET (feature-folder + bare attribute routes), Drupal, Rust (Axum chained
|
||
methods, actix builder API), Vapor (Swift grouped routes), Play (`conf/routes`),
|
||
Vue/Nuxt SFC templates, Svelte/SvelteKit, and React Router (`<Route>` JSX +
|
||
object data-router).
|
||
- **Dynamic-dispatch flow synthesis — `codegraph_trace`, `codegraph_callees`, and
|
||
`codegraph_explore` now follow flows that have no static call edge.** Bridged
|
||
channels: callback/observer registration, EventEmitter (`on`/`emit`), React
|
||
re-render (`setState` → `render`) and JSX children, Flutter `setState` → `build`,
|
||
C++ virtual overrides, and Java/Kotlin interface → implementation dispatch
|
||
(e.g. Spring `@Autowired svc.list()` → the impl). Each synthesized hop is
|
||
labeled inline in `trace` with where it was wired up.
|
||
- **`CODEGRAPH_MCP_TOOLS` — trim the exposed MCP tool surface.** Set it to a
|
||
comma-separated list of tool names (e.g. `trace,search,node,context`) to expose
|
||
only those codegraph tools over MCP; unset exposes all of them. Names match on
|
||
the short form, so `trace` and `codegraph_trace` are equivalent. Lets you
|
||
constrain an agent to a minimal surface (or A/B-test tool selection) without
|
||
editing the client's MCP config. Inert by default.
|
||
- **Release archives now ship with a `SHA256SUMS` file**, and the npm launcher
|
||
verifies the bundle it downloads against it — a mismatch aborts before anything
|
||
runs. Releases published before this change have no checksum file, so the
|
||
verification is skipped (not failed) when none is available.
|
||
|
||
### Changed
|
||
- **`codegraph_trace` now returns a self-contained flow dossier.** Each hop on
|
||
the path is shown with its full body inline (previously just the call-site
|
||
line), and the destination's own outgoing calls are appended — so one trace
|
||
call usually answers a "how does X reach Y" flow question without a follow-up
|
||
`codegraph_explore`/`codegraph_node`/Read. Measured across real repos: fewer
|
||
tool calls and lower cost than the prior path-only output, with no wall-clock
|
||
regression.
|
||
- **`codegraph_node` and `codegraph_trace` now emit line-numbered source**
|
||
(`cat -n` style, matching `codegraph_explore` and Read), so an agent can cite
|
||
or edit exact lines without re-reading the file just to recover line numbers.
|
||
- **`codegraph_explore` now leads with the execution flow** when its query names
|
||
the symbols of a flow. Agents call `explore` far more than `trace`, passing a
|
||
bag of symbol names that usually spans the flow they're investigating
|
||
(`PmsProductController getList PmsProductService list PmsProductServiceImpl`);
|
||
`explore` now finds the call path *among those named symbols* — riding
|
||
synthesized dynamic-dispatch edges (callback / React re-render / JSX child /
|
||
interface→impl) — and shows it first. So a flow question answered through
|
||
`explore` gets the trace-quality path without the agent having to switch tools.
|
||
Scoped to the named symbols (no wrong-feature wandering) and bridge-capped (no
|
||
god-function fan-out); absent when the query is fuzzy or has no connected chain.
|
||
|
||
### Fixed
|
||
- **Static-extraction & resolution correctness fixes** underpinning the framework
|
||
work above: C++ inheritance (`base_class_clause` was unhandled, so C++ `extends`
|
||
edges were missing), Dart method body ranges (methods were extracted
|
||
signature-only), a Python builtin-name handler guard (handlers named
|
||
`index`/`get`/`update` were silently dropped), and an explore output-budget
|
||
regression that under-returned source on god-file repos.
|
||
- **Orphaned `codegraph serve --mcp` processes after a parent SIGKILL.** When
|
||
the MCP host (Claude Code, opencode, …) was force-killed — OOM killer, a
|
||
`kill -9`, a container teardown — the child kept running indefinitely on
|
||
Linux, holding inotify watches, file descriptors, and the SQLite WAL. The
|
||
kernel doesn't propagate parent death to children, and the stdin
|
||
`end`/`close` handlers we relied on don't always fire. The MCP server now
|
||
polls `process.ppid` and shuts down the moment it changes from the value
|
||
observed at startup; the poll interval is `CODEGRAPH_PPID_POLL_MS` (default
|
||
`5000`, `0` disables). Resolves
|
||
[#277](https://github.com/colbymchenry/codegraph/issues/277).
|
||
|
||
- **`codegraph: no prebuilt bundle for <platform>` after installing through a
|
||
registry mirror.** Installing `@colbymchenry/codegraph` from a registry that
|
||
hadn't mirrored the matching per-platform package — most often the
|
||
npmmirror/cnpm mirrors, but any lazily-syncing mirror or corporate proxy can
|
||
do it — left every command failing with `no prebuilt bundle for <platform>`.
|
||
The runtime ships as a per-platform `optionalDependency`, and npm treats an
|
||
optional package it can't fetch as a success and silently skips it, so the
|
||
bundle simply went missing. The launcher now self-heals: when the platform
|
||
bundle isn't installed, it downloads the same archive from GitHub Releases
|
||
(cached under `~/.codegraph/bundles/` for next time) and runs that — so a
|
||
global install works even on a mirror that never carried the platform package.
|
||
Set `CODEGRAPH_NO_DOWNLOAD=1` to disable the network fallback, or
|
||
`CODEGRAPH_DOWNLOAD_BASE=<url>` to point it at your own mirror of the release
|
||
archives; the standalone `install.sh` remains the no-Node alternative. Resolves
|
||
[#303](https://github.com/colbymchenry/codegraph/issues/303).
|
||
- **`install.sh` failing with `403` / "could not resolve latest version" on
|
||
shared or cloud hosts.** The standalone installer resolved the latest release
|
||
through the GitHub API, whose unauthenticated limit is 60 requests/hour per IP
|
||
— routinely exhausted on cloud devboxes and CI where many users share an
|
||
address, returning `403` (issue #325). It now resolves the version from the
|
||
`releases/latest` web redirect, which isn't rate-limited (and still falls back
|
||
to the API). `CODEGRAPH_VERSION` also accepts a bare `0.9.4` in addition to
|
||
`v0.9.4`. Resolves
|
||
[#325](https://github.com/colbymchenry/codegraph/issues/325).
|
||
|
||
## [0.9.3] - 2026-05-22
|
||
|
||
### Added
|
||
- **`codegraph uninstall` command.** Cleanly removes CodeGraph from every agent
|
||
it's configured on — Claude Code, Cursor, Codex CLI, opencode, and Hermes
|
||
Agent — in one step. It asks up front whether to remove the global config
|
||
(`~/.claude`, `~/.codex`, …) or just this project's local config (no flags
|
||
required), then prints exactly which agents it touched so you can see what
|
||
changed. `--location`, `--target`, and `--yes` are accepted for scripted /
|
||
non-interactive use. It removes only what `install` wrote (MCP server entry,
|
||
instructions block, permissions) and leaves your `.codegraph/` index alone
|
||
(use `codegraph uninit` for that). Resolves
|
||
[#313](https://github.com/colbymchenry/codegraph/issues/313) — previously the
|
||
only cleanup path was an npm `preuninstall` hook that the published bundle
|
||
never shipped, so `npm uninstall -g` left every agent pointing at a CodeGraph
|
||
MCP server that no longer existed.
|
||
|
||
### Fixed
|
||
- **`Fatal process out of memory: Zone` crash while indexing large projects.**
|
||
On Node.js 22 and 24 — including CodeGraph's own bundled runtime — running
|
||
`codegraph index` / `codegraph init` on a large multi-language repo could
|
||
abort the entire process partway through parsing with
|
||
`Fatal process out of memory: Zone`, even with tens of GB of RAM free (the
|
||
failure is in a V8-internal compilation arena, not the JS heap). The cause is
|
||
V8's "turboshaft" optimizing WASM compiler exhausting its Zone budget while
|
||
compiling tree-sitter's large WebAssembly grammars on a background thread.
|
||
CodeGraph now runs with V8's `--liftoff-only`, which keeps grammar compilation
|
||
on the baseline compiler and never reaches the optimizing tier, eliminating
|
||
the crash; indexing output is otherwise unchanged. The bundled launcher passes
|
||
the flag directly, and any other launch path (from source, `npx`, a globally
|
||
linked dev build) re-execs once with it automatically. Resolves
|
||
[#298](https://github.com/colbymchenry/codegraph/issues/298) and
|
||
[#293](https://github.com/colbymchenry/codegraph/issues/293). (Node 25 stays
|
||
blocked — its variant of this V8 bug is not resolved by `--liftoff-only`.)
|
||
- **Cursor uninstall left an orphaned `.cursor/rules/codegraph.mdc`.** It
|
||
stripped the rule body but left the file and its `description: CodeGraph …`
|
||
frontmatter behind. The dedicated rules file is now deleted outright on
|
||
uninstall, while any content you added outside CodeGraph's markers is kept.
|
||
|
||
## [0.9.2] - 2026-05-21
|
||
|
||
### Added
|
||
- **Installer target: Hermes Agent (Nous Research).** `codegraph install` now
|
||
supports Hermes Agent — it writes the `mcp_servers.codegraph` entry and ensures
|
||
`platform_toolsets.cli` includes `mcp-codegraph` in `$HERMES_HOME/config.yaml`,
|
||
so Hermes can drive the CodeGraph knowledge graph like the other agents.
|
||
- **Framework support: Drupal 8/9/10/11** — CodeGraph now detects Drupal
|
||
projects (via a `drupal/*` dependency in `composer.json`) and adds three
|
||
levels of intelligence:
|
||
- **Route extraction**: `*.routing.yml` files emit a `route` node per route,
|
||
linked by a `references` edge to the `_controller`, `_form`, or
|
||
entity-handler class/method, so querying a controller method surfaces the
|
||
URL route that binds it.
|
||
- **Hook detection**: hook implementations in `.module`, `.install`, `.theme`,
|
||
and `.inc` files are detected via docblock (`Implements hook_X()`) with a
|
||
module-name-prefix fallback. Each emits a `references` edge to the canonical
|
||
`hook_X` name so `codegraph_callers("hook_form_alter")` returns every
|
||
implementation across modules.
|
||
- **Resolution**: `_controller`/`_form` FQCNs resolve to their PHP
|
||
class/method nodes.
|
||
New `yaml`/`twig` languages are tracked at the file level, the Drupal PHP
|
||
extensions (`.module`/`.install`/`.theme`/`.inc`) are indexed with the PHP
|
||
grammar, and `web/core`, `web/modules/contrib`, `web/themes/contrib` are
|
||
excluded by default. Resolves [#268](https://github.com/colbymchenry/codegraph/issues/268).
|
||
|
||
### Changed
|
||
- **Zero-config indexing that respects `.gitignore`.** CodeGraph no longer has a
|
||
config file. It indexes every file whose extension maps to a supported language
|
||
and honors your `.gitignore` everywhere: in git repos via git itself, and in
|
||
non-git projects (e.g. a freshly-scaffolded app before `git init`) by reading
|
||
`.gitignore` files directly — root and nested, the same way git does (via the
|
||
`ignore` library, so negation/anchoring/nested rules all behave correctly). To
|
||
keep something out of the graph, add it to `.gitignore`. **Behavior change:**
|
||
committed files that are *not* gitignored are now indexed even under `vendor/`,
|
||
`Pods/`, or a committed `dist/` — previously a hardcoded exclude list skipped
|
||
those names; now `.gitignore` is the single source of truth. Resolves
|
||
[#283](https://github.com/colbymchenry/codegraph/issues/283).
|
||
|
||
### Fixed
|
||
- **Windows: `npm i -g @colbymchenry/codegraph` then any `codegraph` command
|
||
failed with `spawnSync …\codegraph.cmd EINVAL`.** The npm launcher spawned the
|
||
bundle's `.cmd` file directly, which modern Node refuses to do on Windows
|
||
(the CVE-2024-27980 hardening — seen on Node 24). The launcher now invokes the
|
||
bundled `node.exe` against the app directly, so `codegraph` works on Windows
|
||
regardless of your Node version. Resolves
|
||
[#289](https://github.com/colbymchenry/codegraph/issues/289).
|
||
|
||
### Removed
|
||
- **`.codegraph/config.json` and the entire config surface.** Every field was
|
||
either inert or now redundant with `.gitignore`:
|
||
- `languages`/`frameworks` never affected indexing (languages are detected per
|
||
file from extensions; frameworks are auto-detected). `languages` was also
|
||
broken — its validator only knew the original 8 languages, so setting it to
|
||
anything newer (C#, PHP, Ruby, C/C++, Swift, Kotlin, Dart, Vue, Scala, Lua, …)
|
||
threw `Invalid configuration format`.
|
||
- `extractDocstrings`/`trackCallSites`/`customPatterns` were never read by any
|
||
extractor.
|
||
- `include` is now derived from the supported language extensions, `exclude` is
|
||
replaced by `.gitignore`, and `maxFileSize` (1 MB) is a constant.
|
||
|
||
**Breaking (library API):** the `CodeGraphConfig` type, the `config` option on
|
||
`CodeGraph.init()`, and the `getConfig()`/`updateConfig()`/`getConfigPath`
|
||
exports are gone. Existing `.codegraph/config.json` files are simply ignored.
|
||
The `.codegraphignore` marker is no longer supported — use `.gitignore`.
|
||
|
||
### Security
|
||
- **MCP session marker no longer follows symlinks** (CWE-59). Every
|
||
`codegraph_context` call writes a `codegraph-consulted-*` marker into the
|
||
system temp dir; the previous write followed symlinks, so on a multi-user
|
||
system another local user could pre-plant that path as a symlink and redirect
|
||
the write onto a victim-writable file. The marker is now opened with
|
||
`O_NOFOLLOW` and mode `0600`, and a planted symlink is refused rather than
|
||
followed. Resolves [#280](https://github.com/colbymchenry/codegraph/issues/280).
|
||
|
||
## [0.9.1] - 2026-05-21
|
||
|
||
### Fixed
|
||
- **Standalone installers** (`curl … | sh`, `irm … | iex`): the bundled launcher
|
||
failed with `exec: …/node: not found` because it didn't resolve the symlink the
|
||
installer puts on your PATH. Installing on a machine with **no Node** now works.
|
||
- **npm**: `@colbymchenry/codegraph-linux-x64` is now published — the 0.9.0
|
||
release silently shipped 6 of 7 packages, so `npm i -g` on linux-x64 couldn't
|
||
find its bundle. The release pipeline now verifies every package reached the
|
||
registry (and is idempotent), so a release can't pass green-but-broken again.
|
||
|
||
[0.9.4]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.4
|
||
[0.9.3]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.3
|
||
[0.9.2]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.2
|
||
[0.9.1]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.1
|
||
|
||
## [0.9.0] - 2026-05-21
|
||
|
||
### 🎉 Self-contained: CodeGraph bundles its own runtime — install anywhere, on any Node (or none)
|
||
|
||
**No more `database is locked`. No more native build failures. No more "WASM fallback active."**
|
||
|
||
CodeGraph used to need `better-sqlite3`, a native module compiled against your exact
|
||
Node version. When that build failed (common on Windows and locked-down machines) it
|
||
silently dropped to a slow WASM SQLite build with **no WAL** — the root cause of the
|
||
intermittent `database is locked` errors on concurrent MCP tool calls
|
||
([#238](https://github.com/colbymchenry/codegraph/issues/238)). That entire class of
|
||
problem is **gone**: CodeGraph now ships a self-contained Node runtime and uses Node's
|
||
built-in `node:sqlite` (real SQLite, full WAL + FTS5).
|
||
|
||
- ✅ **Zero native compilation** — nothing to build, ever; nothing to rebuild when Node changes.
|
||
- ✅ **Runs on any Node version — or with no Node at all.** Install via the standalone installers with no Node present, or keep using `npm`/`npx` on any version (your Node only launches the bundled runtime).
|
||
- ✅ **`database is locked` fixed at the root** — real WAL means readers never block on a writer.
|
||
- ⚡ **5–10× faster** than the old WASM fallback for anyone who was stuck on it.
|
||
|
||
```bash
|
||
# macOS / Linux — no Node required
|
||
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
|
||
# Windows (PowerShell) — no Node required
|
||
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
|
||
# or, if you have Node (any version):
|
||
npm i -g @colbymchenry/codegraph
|
||
```
|
||
|
||
### Added
|
||
- **Standalone installers** — one-line install with no Node.js required:
|
||
`curl -fsSL .../install.sh | sh` (macOS/Linux) and `irm .../install.ps1 | iex`
|
||
(Windows). They fetch the matching self-contained bundle from GitHub Releases
|
||
and put `codegraph` on your PATH.
|
||
- **Lua**: CodeGraph now indexes Lua (`.lua`) — functions, methods (table `t.f`
|
||
and `t:m` definitions become methods with a `t::f` receiver-qualified name),
|
||
local variables, `require(...)` imports, and the call edges between them.
|
||
Querying a Lua project (Neovim plugins, Kong, OpenResty, game code) now
|
||
surfaces its modules, methods, and call graph.
|
||
- **Luau** ([#232](https://github.com/colbymchenry/codegraph/issues/232)):
|
||
CodeGraph now indexes Luau (`.luau`), Roblox's typed superset of Lua —
|
||
everything Lua extracts, plus `type` / `export type` aliases, typed function
|
||
signatures, generics, and Roblox instance-path `require(script.Parent.X)`
|
||
imports.
|
||
|
||
### Changed
|
||
- **SQLite backend is now Node's built-in `node:sqlite`** (real SQLite, WAL +
|
||
FTS5), shipped inside a bundled Node runtime. This fixes the concurrent-read
|
||
`database is locked` errors ([#238](https://github.com/colbymchenry/codegraph/issues/238))
|
||
at the root and removes the native build step entirely.
|
||
- **`npm i -g` / `npx` now install a self-contained bundle.** The main package is
|
||
a tiny shim; the runtime ships as per-platform `optionalDependencies`, so the
|
||
install works on any Node version (your Node only launches the bundle).
|
||
- **`codegraph status`** now reports the effective journal mode (`wal` vs not),
|
||
so a `database is locked` report is triageable at a glance.
|
||
|
||
### Removed
|
||
- **`better-sqlite3`** (optional native dependency) and **`node-sqlite3-wasm`**
|
||
(WASM fallback) — along with the native-build banner, the WASM fallback path,
|
||
and the no-WAL lock retries they required. The dependency tree now has zero
|
||
native addons.
|
||
|
||
### Fixed
|
||
- **Installer**: re-running `codegraph install` now removes the broken
|
||
auto-sync hooks that pre-0.8 versions wrote to Claude Code's
|
||
`settings.json`. Those builds added a `Stop → codegraph sync-if-dirty`
|
||
hook (and a `PostToolUse → codegraph mark-dirty` partner); both
|
||
subcommands were later removed from the CLI, so Claude Code reported
|
||
`Stop hook error: ... unknown command 'sync-if-dirty'` on every turn.
|
||
The cleanup is surgical — only codegraph's own hook entries are
|
||
stripped, so unrelated hooks sharing the same file or event (e.g. a
|
||
GitKraken `gk ai hook run` hook) are left untouched — and it also runs
|
||
on uninstall, so the npm `preuninstall` step fully reverses a legacy
|
||
install. Re-run `codegraph install` once on an affected machine to
|
||
clear the error.
|
||
|
||
[0.9.0]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.0
|
||
|
||
## [0.8.0] - 2026-05-20
|
||
|
||
### Added
|
||
- **Framework routes (NestJS)**: CodeGraph now recognises NestJS projects and
|
||
emits `route` nodes — each linked by a `references` edge to its handler
|
||
method — across all four transport layers: HTTP controllers (the
|
||
`@Controller` prefix joined with `@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`/
|
||
`@Head`/`@Options`/`@All`, including empty `@Controller()`/`@Get()`),
|
||
GraphQL resolvers (`@Query`/`@Mutation`/`@Subscription`), microservice
|
||
handlers (`@MessagePattern`/`@EventPattern`), and WebSocket gateways
|
||
(`@SubscribeMessage`, prefixed with the gateway namespace). Detected
|
||
automatically from any `@nestjs/*` dependency in `package.json`. Querying a
|
||
controller method or resolver now surfaces the route that binds it.
|
||
Resolves [#220](https://github.com/colbymchenry/codegraph/issues/220).
|
||
- **MCP / explore**: `codegraph_explore` source sections now carry line
|
||
numbers (cat -n style `<num>\t<code>`, matching the Read tool). This lets
|
||
the agent cite `file:line` straight from the explore payload instead of
|
||
re-opening the file just to find a line number — the dominant residual
|
||
cost on precise-tracing questions. In an isolated A/B (answer a
|
||
"which exact line" question with the relevant code already in the
|
||
payload), the no-line-numbers arm spent 2 file Reads + a grep recovering
|
||
the line number while the line-numbered arm answered with zero follow-up
|
||
tool calls. Payload cost is small (~3-5%). Set
|
||
`CODEGRAPH_EXPLORE_LINENUMS=0` to disable.
|
||
- **MCP / watcher**: CodeGraph now skips the live file watcher on WSL2
|
||
`/mnt/*` drives, where recursive `fs.watch` is slow enough to break MCP
|
||
startup (see Fixed). When the watcher is off, `codegraph init` /
|
||
`codegraph install` offer to keep the index fresh via git hooks
|
||
(`post-commit`, `post-merge`, `post-checkout`) that run `codegraph sync`
|
||
in the background — accept for automatic refresh on commit / pull /
|
||
checkout, or decline and sync by hand. Either way you're told the index
|
||
stays frozen until it's re-synced. New controls: `CODEGRAPH_NO_WATCH=1`
|
||
(or `codegraph serve --mcp --no-watch`) forces the watcher off anywhere;
|
||
`CODEGRAPH_FORCE_WATCH=1` overrides the WSL auto-detect when your `/mnt`
|
||
setup is actually fast. `codegraph uninit` removes any hooks it installed.
|
||
|
||
### Changed
|
||
- **MCP / agent guidance**: CodeGraph now tells agents to answer "how does X
|
||
work" / architecture questions *directly* — `codegraph_context`, then one
|
||
`codegraph_explore` for the surfaced symbols — instead of delegating to a
|
||
file-reading sub-agent or a grep+read loop. The server instructions and the
|
||
installed instruction files (`CLAUDE.md`, `.cursor/rules/codegraph.mdc`,
|
||
`AGENTS.md`) previously suggested *spawning a sub-agent* for explore-class
|
||
questions, which produced the opposite, more expensive behavior: the
|
||
sub-agent reads files regardless of the index, so CodeGraph became overhead
|
||
stacked on top of the reads. In rigorous N≥4-per-arm benchmarks this cut the
|
||
cost of an architecture question by ~42–47% versus a no-CodeGraph agent on
|
||
medium and large repos (Excalidraw ~600 files, VS Code ~10k), with
|
||
equal-or-better, `file:line`-cited answers and ~6× fewer tool calls; on a
|
||
tiny repo (~25 files) it's a wash, since native grep is already trivially
|
||
cheap there.
|
||
- **MCP / codegraph_node**: `includeCode=true` on a class/interface/struct/enum
|
||
now returns a compact member outline (fields + method signatures + line
|
||
numbers) instead of the entire class body — which could be thousands of
|
||
characters and was rarely needed in full. Functions and methods still return
|
||
their full body; request a specific member for its source.
|
||
- **Minimum Node.js is now 20** (was 18). Node 18 is end-of-life and the
|
||
native SQLite binding (`better-sqlite3` 12.x) no longer ships a Node 18
|
||
prebuilt binary. Node 22 LTS and Node 24 get the native backend out of the
|
||
box; on other Node versions CodeGraph still runs via the WASM fallback
|
||
(slower, but functional). Node 25+ remains blocked (V8 WASM JIT crash, see
|
||
[#81](https://github.com/colbymchenry/codegraph/issues/81)).
|
||
- **MCP / explore**: `codegraph_explore` output is now adaptive to project
|
||
size. The tool used to apply a fixed 35KB cap regardless of how large the
|
||
codebase was, which on small projects (~100 files) produced bigger
|
||
responses than the agent's native grep+Read flow would have — exactly the
|
||
scenario reported in
|
||
[#185](https://github.com/colbymchenry/codegraph/issues/185). The budget
|
||
now scales with indexed file count: small projects (<500 files) cap at
|
||
~18KB and skip the "Additional relevant files" / completeness / explore-
|
||
budget reminders that earn their keep on bigger codebases; medium
|
||
(<5,000) caps at ~13KB; large (<15,000) keeps the historical ~35KB; very
|
||
large goes up to ~38KB. A new per-file char cap also prevents a single
|
||
file with many adjacent symbols from collapsing into one whole-file dump
|
||
(the Alamofire `Session.swift` case from #185). Per-file cluster
|
||
selection ranks clusters that contain a query entry point ahead of dense
|
||
declaration blocks, and whole-file "envelope" nodes (a class/struct that
|
||
spans most of the file) are excluded from clustering so the methods the
|
||
query asked about aren't buried under the container's opening lines.
|
||
Measured against the same repos used in the README benchmark, end state
|
||
with line numbers on: Alamofire ~60% smaller per call, Excalidraw ~32%,
|
||
VS Code ~12%. Agent-trust floor still holds — the Relationships section,
|
||
scored cluster selection, and structured-source output are all retained.
|
||
Thanks to [@essopsp](https://github.com/essopsp) for the repro.
|
||
- **Search ranking (Kotlin / Swift / Scala / C#)**: test files in these
|
||
languages are now correctly de-prioritized in `codegraph_search`,
|
||
`codegraph_context`, and `codegraph affected`. Detection previously only
|
||
recognized `snake_case`/`.test.`-style names plus a handful of Java
|
||
suffixes, so CamelCase test files (`FooTest.kt`, `BarTests.swift`,
|
||
`BazSpec.scala`, `QuxTestCase.cs`) and Gradle / Kotlin-Multiplatform /
|
||
Xcode test source-set directories (`jvmTest/`, `commonTest/`,
|
||
`androidTest/`, `iosTest/`, `integrationTest/`) were treated as production
|
||
code and could outrank the real implementation. Detection now matches
|
||
capital-led `*Test` / `*Tests` / `*Spec` / `*TestCase` filenames and
|
||
source-set directories — deliberately capital-led so lowercase look-alikes
|
||
like `latest.kt` and `manifest.kt` are not misclassified.
|
||
|
||
### Fixed
|
||
- **MCP / explore**: `codegraph_explore` output is now hard-capped to its
|
||
adaptive size budget. It could previously overrun (e.g. ~30K against a 28K
|
||
cap) once the relationship map and trailer sections were appended; the
|
||
oversized payload then sat in the agent's context and was re-read on every
|
||
later turn.
|
||
- **Sync / status**: git-untracked files are no longer reported as pending
|
||
"Added" forever. After `codegraph sync` indexed a newly-created untracked
|
||
source file, `codegraph status` kept listing it under Pending Changes and
|
||
every subsequent `sync` re-indexed it from scratch — even though its symbols
|
||
were already queryable. Change detection trusted `git status` and counted
|
||
every untracked (`??`) entry as new without checking the index, but indexing
|
||
a file doesn't make git track it, so the file stayed `??` and got re-added on
|
||
each run. CodeGraph now hash-compares untracked files against the index the
|
||
same way it does tracked files: a file counts as "added" only if it's missing
|
||
from the index, "modified" if its contents changed, and is skipped otherwise.
|
||
Closes [#206](https://github.com/colbymchenry/codegraph/issues/206). Thanks to
|
||
[@15290391025](https://github.com/15290391025) for the report.
|
||
- **Indexing**: `codegraph init -i` now finds source inside nested, independent
|
||
git repositories — separate clones living inside the workspace that are **not**
|
||
git submodules (common in CMake "super-repo" layouts). When the top-level
|
||
workspace is itself a git repo, `git ls-files` reports an embedded repo only as
|
||
an opaque `subdir/` entry and never lists its files, so indexing from the
|
||
workspace root reported "No files found to index" even though indexing each
|
||
sub-repo individually worked. CodeGraph now detects these embedded repos and
|
||
indexes their tracked and untracked source, honoring each repo's own
|
||
`.gitignore`. Closes
|
||
[#193](https://github.com/colbymchenry/codegraph/issues/193). Thanks to
|
||
[@timxx](https://github.com/timxx) for the report.
|
||
- **Native SQLite backend on Node 24**: indexing on Node 24 always dropped to
|
||
the 5-10x-slower WASM backend, printing a `better-sqlite3 unavailable`
|
||
warning that `npm rebuild better-sqlite3` / `xcode-select --install` could
|
||
not clear ([#203](https://github.com/colbymchenry/codegraph/issues/203)).
|
||
The bundled `better-sqlite3` was pinned to a v11 release that ships no
|
||
prebuilt binary for Node 24's ABI (`node-v137`), so every Node 24 install
|
||
silently degraded — and because CodeGraph is usually installed globally, the
|
||
`npm install` / `npm rebuild` people ran in their own project never touched
|
||
CodeGraph's copy. CodeGraph now requires `better-sqlite3` `^12.4.1`, whose
|
||
prebuilds include Node 24, so a fresh install on Node 22 or Node 24 gets the
|
||
native backend with no compiler. On an already-broken install, reinstall
|
||
CodeGraph (e.g. `npm install -g @colbymchenry/codegraph`) to pull the new
|
||
binding; `codegraph status` should then report `Backend: native`. Thanks to
|
||
[@Finndersen](https://github.com/Finndersen) for the report.
|
||
- **MCP**: tools no longer fail with "CodeGraph not initialized" when the index
|
||
actually exists. This hit clients that launch the MCP server from a directory
|
||
other than your project and don't report a workspace root in `initialize`
|
||
(some IDE/JetBrains-family integrations) — the server fell back to its own
|
||
working directory, missed the project's `.codegraph/`, and returned the
|
||
misleading "Run 'codegraph init' first" on every call. The only workaround
|
||
was passing `projectPath` to each tool by hand. Now, when no project path is
|
||
supplied, the server asks the client for its workspace root via the standard
|
||
MCP `roots/list` request (when the client advertises the `roots` capability)
|
||
before falling back to the working directory — so detection just works for
|
||
spec-compliant clients. When it still can't resolve a project, the error is
|
||
now actionable: it names the directory it searched and tells you to pass
|
||
`projectPath` or add `--path /abs/project` to the server's MCP config args,
|
||
instead of pointing you at a re-init you don't need. Closes
|
||
[#196](https://github.com/colbymchenry/codegraph/issues/196). Thanks to
|
||
[@zhangyu1197](https://github.com/zhangyu1197) for the report and the
|
||
`projectPath` workaround.
|
||
- **MCP**: the server no longer hangs on startup under WSL2 when the project
|
||
lives on an NTFS `/mnt/*` mount. Setting up the recursive file watcher
|
||
there took tens of seconds — every directory read crosses the Windows/9p
|
||
boundary — which blew past the host's initialization timeout (opencode's
|
||
30s), so the codegraph tools silently never appeared, even on small
|
||
projects. This is the file-watcher half of the
|
||
[#172](https://github.com/colbymchenry/codegraph/issues/172) startup fix:
|
||
that one moved the database/WASM open off the handshake, but the watcher
|
||
setup was still on the critical path. CodeGraph now auto-skips the watcher
|
||
on those mounts, with manual and git-hook sync fallbacks (see Added).
|
||
Closes [#199](https://github.com/colbymchenry/codegraph/issues/199).
|
||
Thanks to [@mengfanbo123](https://github.com/mengfanbo123) for the precise
|
||
root-cause analysis and workaround.
|
||
- **Installer (Claude Code)**: project-local installs (`Just this project`)
|
||
now write the MCP server to `.mcp.json` in the project root — the file
|
||
Claude Code actually reads for project-scoped servers. Previously they
|
||
wrote `.claude.json`, which Claude Code ignores, so the codegraph tools
|
||
silently never appeared and you had to rename the file by hand to make it
|
||
work. Re-running `codegraph install` (or `codegraph init`) on an affected
|
||
project migrates the stale `.claude.json` entry into `.mcp.json`
|
||
automatically; uninstall cleans up both. Global (`All projects`) installs
|
||
were unaffected — they correctly target `~/.claude.json`. Closes
|
||
[#207](https://github.com/colbymchenry/codegraph/issues/207). Thanks to
|
||
[@Jhsmit](https://github.com/Jhsmit) for the report and the workaround.
|
||
- **MCP**: source-omission markers in `codegraph_explore` and
|
||
`codegraph_context` output are now language-neutral (`... (gap) ...`,
|
||
`... (trimmed) ...`, `... (truncated) ...`) instead of C-style `//`
|
||
comments, which were misleading inside Python, Ruby, and other non-C
|
||
fenced source blocks.
|
||
|
||
## [0.7.10] - 2026-05-19
|
||
|
||
### Fixed
|
||
- **MCP**: tools no longer silently fail to appear in clients on slow
|
||
filesystems (Docker Desktop VirtioFS on macOS, WSL2). The `initialize`
|
||
handshake was blocking on opening the SQLite database and bootstrapping
|
||
the tree-sitter WASM runtime, which on slow I/O could exceed Claude
|
||
Code's ~30s handshake timeout — leaving the codegraph process alive but
|
||
unresponsive and no tools visible. The handshake now returns immediately
|
||
and defers project open to the background; tool calls wait on the
|
||
in-flight init rather than racing it with a second open. Closes
|
||
[#172](https://github.com/colbymchenry/codegraph/issues/172). Thanks to
|
||
[@sashanclrp](https://github.com/sashanclrp) for the original report and
|
||
detailed reproduction, and [@sgrimm](https://github.com/sgrimm) for the
|
||
decisive wire capture that isolated the actual root cause.
|
||
- **CLI**: terminal output no longer mojibakes on Windows PowerShell /
|
||
cmd.exe during `codegraph index` and `codegraph sync`. The shimmer
|
||
progress renderer writes from a worker thread via `fs.writeSync(1, …)`
|
||
to keep the animation smooth while the main thread is busy in SQLite,
|
||
which bypasses Node's TTY-aware UTF-8→codepage conversion — so glyphs
|
||
like `│ ◆ —` were emitted as raw UTF-8 bytes and reinterpreted as the
|
||
console's OEM codepage (CP437, CP936, …), producing strings like
|
||
`鋍?[0m 鉒?[0m Scanning files 鈥?N found`. CodeGraph now picks an ASCII
|
||
glyph set on Windows by default (`| * -` instead of `│ ◆ —`); set
|
||
`CODEGRAPH_UNICODE=1` to opt back into the Unicode glyphs (e.g. on
|
||
pwsh 7 with UTF-8 codepage), or `CODEGRAPH_ASCII=1` on any platform to
|
||
force ASCII (useful for log collectors / non-TTY pipelines). Closes
|
||
[#168](https://github.com/colbymchenry/codegraph/issues/168). Thanks to
|
||
[@starkleek](https://github.com/starkleek) for the report and to
|
||
[@Bortlesboat](https://github.com/Bortlesboat) for the initial PR.
|
||
- **MCP / search**: module-qualified symbol lookups now resolve. The
|
||
MCP tools (`codegraph_node`, `codegraph_callees`, `codegraph_impact`,
|
||
…) accept `module::symbol` (Rust / C++ / Ruby), `Module.symbol`
|
||
(TS / JS / Python), and `module/symbol` (path-style) — multi-level
|
||
forms (`crate::configurator::stage_apply::run`) and Rust path
|
||
prefixes (`crate`, `super`, `self`) are handled. Closes
|
||
[#173](https://github.com/colbymchenry/codegraph/issues/173). Thanks
|
||
to [@joselhurtado](https://github.com/joselhurtado) for the detailed
|
||
reproduction. Three underlying fixes:
|
||
- The FTS5 query builder now treats `::` as a token separator
|
||
instead of stripping it to nothing, so `stage_apply::run` no
|
||
longer collapses to the unsearchable `stage_applyrun`.
|
||
- `matchesSymbol` falls back to a file-path containment check when
|
||
`qualifiedName` doesn't carry the module hierarchy (Rust
|
||
file-level functions, Python free functions in a package): a
|
||
`run` in `src/configurator/stage_apply.rs` now matches
|
||
`stage_apply::run` because `stage_apply` appears as a path
|
||
segment.
|
||
- Qualified lookups that don't match the qualifier no longer fall
|
||
through to fuzzy text matches — `stage_apply::nonexistent_fn`
|
||
returns `null` instead of resolving to an unrelated `rollback`
|
||
in the same file.
|
||
|
||
[0.8.0]: https://github.com/colbymchenry/codegraph/releases/tag/v0.8.0
|
||
[0.7.10]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.10
|
||
|
||
## [0.7.8] - 2026-05-17
|
||
|
||
### Fixed
|
||
- **opencode**: install actually wires up the MCP server now. v0.7.7 wrote
|
||
`~/.config/opencode/opencode.json`, but opencode reads `opencode.jsonc` by
|
||
default — so the `codegraph` entry never showed up in any opencode session.
|
||
The installer now prefers an existing `.jsonc`, falls back to `.json` when
|
||
only that exists, and creates `.jsonc` for greenfield installs. **Re-run
|
||
`codegraph install --target=opencode` after upgrading** so the entry lands
|
||
in the file opencode actually reads.
|
||
|
||
### Added
|
||
- **opencode**: installer now writes `AGENTS.md` (global
|
||
`~/.config/opencode/AGENTS.md`, local `./AGENTS.md`) with the same
|
||
codegraph usage guidance the other agents already received. Without it,
|
||
opencode's model would call native `Grep` instead of the `codegraph_*`
|
||
tools it could see in its MCP list.
|
||
- User comments and formatting in `opencode.jsonc` survive install /
|
||
re-install / uninstall round-trips — surgical edits via `jsonc-parser`
|
||
rather than full-file rewrites.
|
||
|
||
[0.7.8]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.8
|
||
|
||
## [0.7.7] - 2026-05-17
|
||
|
||
### Added
|
||
- **Multi-agent installer** (closes [#137](https://github.com/colbymchenry/codegraph/issues/137)).
|
||
`codegraph install` now opens with a multi-select prompt for **Claude Code**,
|
||
**Cursor**, **Codex CLI**, and **opencode** — detected agents are pre-checked.
|
||
Each writes its native MCP config + instructions file (e.g. `~/.cursor/mcp.json`
|
||
+ `.cursor/rules/codegraph.mdc`, `~/.codex/config.toml` + `~/.codex/AGENTS.md`,
|
||
`~/.config/opencode/opencode.json`). The runtime MCP server was already
|
||
agent-agnostic; this brings the installer to parity.
|
||
- Non-interactive install flags for scripting / CI:
|
||
`--target=<csv|auto|all|none>`, `--location=<global|local>`, `--yes`,
|
||
`--no-permissions`, `--print-config <id>`.
|
||
- `codegraph init` now auto-wires project-local agent surfaces for any agent
|
||
configured globally. In practice: Cursor's `.cursor/rules/codegraph.mdc`
|
||
is dropped on `init` so a single global `codegraph install` works in every
|
||
project you open — no per-project re-install needed.
|
||
|
||
### Fixed
|
||
- **Cursor**: globally-installed codegraph reported "not initialized" in every
|
||
workspace because Cursor launches MCP-server subprocesses with the wrong
|
||
working directory and doesn't pass `rootUri` in the MCP initialize call.
|
||
We now inject `--path` into Cursor's MCP args — absolute path for local
|
||
installs, `${workspaceFolder}` for global installs.
|
||
|
||
### Changed
|
||
- Agent-instructions template is now agent-agnostic. The previous template was
|
||
inherited from the Claude-only era and prescribed "spawn an Explore agent" —
|
||
a Claude Code-specific concept that confused Cursor's and Codex's agents and
|
||
caused them to fall back to native grep even with codegraph available. The
|
||
new template adds explicit "trust codegraph results, don't re-verify with
|
||
grep" guidance and a clear tool-by-question matrix. Applies to
|
||
`~/.claude/CLAUDE.md`, `.cursor/rules/codegraph.mdc`, and `~/.codex/AGENTS.md`.
|
||
- `codegraph install` prompt order: agent picker is now step 1, before the
|
||
PATH-install and location prompts.
|
||
- Disambiguated "global" wording in install prompts ("Install codegraph CLI on
|
||
your PATH?" vs "Apply agent configs to all your projects, or just this one?")
|
||
— both used to say "Global" and read as duplicates.
|
||
|
||
### Internal
|
||
- New `AgentTarget` interface in `src/installer/targets/` — adding a 5th agent
|
||
(Continue, Zed, Windsurf, …) is a new file + one entry in `registry.ts`.
|
||
- Hand-rolled TOML serializer for Codex (`src/installer/targets/toml.ts`) — no
|
||
new dependency, scoped to the `[mcp_servers.codegraph]` table only, sibling
|
||
tables and `[[array_of_tables]]` preserved verbatim.
|
||
- +47 parameterized contract tests across the 4 targets — install idempotency,
|
||
sibling preservation, uninstall reverses install, byte-equal re-runs return
|
||
`unchanged`, partial-state recovery for Codex.
|
||
|
||
Based on substantive draft by [@andreinknv](https://github.com/andreinknv)
|
||
([fork commit `c5165e4`](https://github.com/andreinknv/codegraph/commit/c5165e4)).
|
||
Thank you.
|
||
|
||
[0.7.7]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.7
|
||
|
||
## [0.7.6] - 2026-05-13
|
||
|
||
### Fixed
|
||
- `codegraph` CLI failing with `zsh: permission denied: codegraph` after a fresh
|
||
global install. The published 0.7.5 tarball shipped `dist/bin/codegraph.js`
|
||
without the executable bit, so the shell refused to run it through the npm
|
||
symlink. The build now `chmod +x`'s the binary before packing.
|
||
|
||
Already on 0.7.5? Either upgrade to 0.7.6, or unblock yourself in place:
|
||
```bash
|
||
chmod +x "$(npm root -g)/@colbymchenry/codegraph/dist/bin/codegraph.js"
|
||
```
|
||
|
||
[0.7.6]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.6
|