v0.1.0 · early preview · MIT

Bring your code to light

Codiluce maps your repository like a city: every page, request, command and table, linked by evidence, through its whole Git history.

npx codiluce@latest start .
Read the docsView on GitHub

Node.js 22.12 or newer. Run it in the repository you want to see.

Codiluce map of the BookStack repository at file level: isometric blocks for PHP files in app/Entities, with the PageRepo class selected and its details in the inspector.
BookStack, an open-source Laravel app, at file level. Blocks are files sized by their code; the inspector shows the selected class.

Goal

A codebase is a city nobody has a map of.

Codiluce exists to make three questions answerable from one picture, for the person who joined last week and for the one who wrote half of it.

01

What does this code do?

Every file, symbol, route and table sits in one zoomable map, from the whole repository down to a line of source.

02

Which flow is it part of?

Pages, requests, commands and scheduled tasks are traced end to end, so each file says which flows reach it.

03

Who changed it, and when?

Every commit is a snapshot on a timeline. Compare any two and see what moved, with authors and churn per file.

Flows

From the click to the table.

Codiluce resolves calls across both stacks. It follows a frontend request through axios instances and wrapper functions, even when the base URL is built in code, to the Laravel handler and the tables it reads.

  • One list of every flow: pages, requests, commands, scheduled tasks
  • A flow plays on the map itself, branch by branch
  • Coverage shows the code that no flow reaches
FlowPOST /auth/loginbranch /account
  1. Frontendpage /accountpage
  2. AccountPanelcomponentrenders
  3. handleSavefunctiononClick
  4. AccountService.signIn()methodcalls
  5. HTTPPOST /auth/loginrequestrequests · base URL from NEXT_PUBLIC_API_URL
  6. BackendAuthController::loginendpointhandles
  7. AuthService::authenticatemethodcalls
  8. Databaseuserstablereads · model User

Each link opens its evidence: analyzer, file and line.

History

Watch the architecture change.

Codiluce indexes every commit of a branch as a snapshot. Scrub the timeline and nothing jumps: the layout keeps each entity in its place. Compare any two commits and the map splits into an overview plus a view on each place that changed.

  • Added, removed, modified and moved, drawn in place
  • Source diffs and the history of any entity
  • A time-lapse of the whole branch
History compare view: an overview of the repository plus four zoomed views on the places a commit changed, with the timeline below.

Data

See the code by the data it touches.

Codiluce reads the schema from your migrations. Tables group into families by their foreign keys, and code takes the family of the tables it reads and writes. The Data view arranges the whole map that way, with no model required.

  • Blast radius of any entity, hop by hop
  • Steps: what a page or function sets in motion
  • Large folders grouped by data or by name
The Data view: BookStack's code arranged by data family, such as Roles, Entities, Images and Attachments, each in its own color.

Principles

Correct first, then useful.

Evidenced, not guessed

Every relationship carries its evidence: analyzer, file and line. What the analyzers cannot prove stays a visible finding, never a silent guess.

Local and read-only

Codiluce reads your repository and Git objects. It never runs your application, installs its dependencies or writes to your checkout.

A layout that holds still

Coordinates are deterministic and slots persist, so the map you learned stays the map you know, from commit to commit.

Models are optional

Language models can describe files, flows and commits on request. The cost is estimated and capped first, and the text stays apart from the facts.

Status

Early, and already useful.

Version 0.1.0 is the first public release. It is built and measured against a production Next.js + Laravel app, so the depth is there. The breadth is still growing.

Analyzed in depth

Symbols, calls, routes, requests, effects, tables.

  • Next.js (App Router)
  • Laravel
  • Inertia
  • TypeScript & JavaScript in any app

Detected and mapped

Files, languages, lines and Git metrics. Calls come next.

  • Python
  • Go
  • Rust
  • Java & Kotlin
  • C# & F#
  • Ruby
  • Swift
  • C & C++
  • Vue
  • Svelte
  • Astro
  • Liquid

On a 5,000-entity app

~10 s
first index, with type-checked calls
~3.5 s
re-index from cache
~3 min
315 commits of history, 6 processes
60 fps
while panning the map

Roadmap

Where it goes next.

Depth first, then breadth: the next steps bring other languages and frameworks to the same level of evidence that Next.js and Laravel have today. Later items are ideas, not commitments.

  1. Done

    • Evidenced graph for Next.js + Laravel: calls, renders, HTTP requests across stacks, tables from migrations
    • Isometric map with semantic zoom, inspector and evidence to source
    • Flows from pages, requests, Artisan commands and scheduled tasks, with coverage
    • Git history: snapshots, compare, split view and time-lapse
    • Blast radius and “what happens from here”
    • Data families, grouped folders and the Data view
    • Optional model descriptions and the Features view
    • Application detection across 12 ecosystems

  2. Now

    • First npm release: npx codiluce with a prebuilt map
    • Website and documentation

  3. Later

    • More split views: a flow across stacks, blast radius, before and after
    • Laravel events, listeners, observers and Eloquent relationships
    • Optional runtime ingestion

Contribute

Help map more of the world’s code.

Codiluce is MIT-licensed and young. These help the most right now:

  • Run it on your repository and tell us what it gets wrong. Unresolved calls are reported as findings: codiluce inspect diagnostics is the best start for an issue. Remove private paths first.
  • Language and framework packs. The roadmap lists the order. Each pack brings routes, entry points and calls with evidence, and fixtures that prove them.
  • The map itself: themes, interactions, performance on very large repositories.
Open an issueStar on GitHub

Develop locally

# get the source
$ git clone https://github.com/ojoven/codiluce.git
$ cd codiluce && npm ci

# map any repository from the checkout
$ npm start -- /path/to/repository

# before a pull request
$ npm test && npm run typecheck
$ npm run test:e2e

One rule for analyzers: name-only matching never creates an edge. Prove it, or report it.

See your repository in a minute.

npx codiluce@latest start .
Getting started →