How codebase maps are built: symbols, layers, token budgets

Parsing, not guessing

A map is only as good as its parser. ContextBridge compiles your code with tree-sitter — the same incremental parser family that code editors use — running as WebAssembly inside your browser tab, across 15 languages. Every symbol comes from a real parse tree, which is why the line ranges are exact rather than estimated.

The precision has deliberate limits. Files above 512 KB are truncated, binaries are skipped, and dependency trees, build output and lockfiles are pruned before parsing. The hard cap is 4,000 files — chosen so an analysis finishes in seconds on a laptop, not minutes.

Layers, hubs, entry points

On top of the symbol table the analyser classifies. Files cluster into layers — API, service, data, UI, infrastructure — inferred from paths, imports and naming. The most-imported files surface as hubs; bootstraps, mains and route tables surface as entry points. This is the layer table of a real (small) sample project, verbatim from the generated map:

| Layer         | Files | Lines | Notable                               |
|---------------|-------|-------|---------------------------------------|
| Core          | 4     | 60    | order-repo.ts, server.ts              |
| API Layer     | 3     | 53    | orders.ts, customers.ts, routes.ts    |
| Service Layer | 2     | 50    | order-service.ts, customer-service.ts |
| UI Layer      | 2     | 23    | order-list.tsx, format.ts             |
| Data Layer    | 1     | 13    | 001_init.sql                          |
| Test Layer    | 1     | 8     | order-service.test.ts                 |

The token budget decides what survives

Every artefact is generated against a token budget you choose, from a quick sketch to a no-limit dump. The ranker scores files by relevance to your stated question — with cross-language term expansion, so a question in Vietnamese or Chinese still matches English code — and by structural importance: hubs, entry points, and the files on the import paths of the matched symbols.

What does not fit is not silently dropped: the artefact lists what it omitted and states its own limits at the top. A budgeted map that admits its edges is worth more to you — and to the model — than an unbounded dump that hides them.

What static analysis cannot know

Honesty matters more than impressiveness here. A static map never sees runtime behaviour: dependency-injected implementations, reflection, dynamic dispatch, feature flags and environment-specific wiring are all invisible to it. Layer labels are heuristics, and heuristics can be wrong in a codebase that enjoys breaking conventions.

So treat a map as what it is: orientation, not ground truth. The generated artefacts are built around the same idea — they instruct the model to answer from the structure it was given, to name the files it does not have, and to never invent implementations. A map that is allowed to say "I don't know" is a map you can trust to tell you where to look next.