Asterlas

A file tree is a filing cabinet, not a map

The sidebar in your editor sorts folders alphabetically. That ordering carries no information about the system — auth sits next to billing because of the letter a, and the thing that actually connects them is three directories away under a name neither of them mentions.

This works fine when you already know the codebase. You’re not really reading the tree at that point; you’re using it as an index into a model you already hold in your head. The problem is everything before that. A new repository, a service you touch twice a year, a corner of your own project you wrote eight months ago — in all three cases the file tree gives you names and nesting, and you reconstruct the actual shape by opening files and following imports until the picture assembles.

That reconstruction is the expensive part, and you pay it again every time the model fades.

Text and pictures are not the same effort

Reading code to understand structure is serial work. You hold a call site in your head, jump to the definition, lose some of the original context, jump back. The structure exists, but it’s distributed across dozens of files and you’re rebuilding it one hop at a time in working memory.

A diagram hands you the same structure in parallel. You see the clusters, the thing everything points at, the module that should be a leaf but somehow has six inbound arrows. None of that requires a jump. Spatial relationships are something you perceive rather than assemble, and it’s a different and much cheaper kind of attention than tracing imports.

Asterlas exists because I kept drawing these diagrams by hand on paper, using them for a week, and then throwing them away when they went stale.

Relationships, not dependency order

This is the part I care about most, and it’s what separates Asterlas from the dependency graphs you can already generate.

A dependency graph shows you what imports what. It’s mechanical and completely derivable from the source, which sounds like a virtue until you generate one for a real project and get a hairball. Every utility import is an edge. Every type-only import is an edge. The graph is correct and it tells you almost nothing, because import order is an artifact of how the language resolves modules, not a description of how the system is arranged.

What you actually want to know is different. Which module owns this concept. What the boundary is. Which thing decides and which thing merely stores. Where the data enters and where it leaves. Those are relationships, and most of them are invisible to the compiler — two modules can have an important architectural relationship and never import each other at all.

So Asterlas builds its diagram from determined nodes: the points in the codebase that are worth being nodes, connected by the relationships that actually hold between them. The result is a picture of the system rather than a picture of the module resolver. It’s smaller than a dependency graph, and it’s smaller on purpose — a diagram you can hold in one glance is the whole point, and an exhaustive one fails that test immediately.

The tradeoff is real and worth stating: this information isn’t free the way import edges are. The diagram reflects a deliberate description of the architecture, which means it’s more useful than a dependency graph and it’s also something you have to keep honest.

Just a dev dependency

The library does one thing and stays out of the way while doing it. It’s a dev dependency — it never ships, it isn’t in your bundle, and it has no opinion about your runtime, your framework, or how you build. Install it, generate the diagram, and the shape of your production artifact is exactly what it was before.

It supports TypeScript 5 through 7, which was a deliberate range rather than a convenience. A tool that reads your codebase is only useful if it can be adopted by codebases that already exist, and those are spread across several major versions. Pinning to the newest compiler would have made it a tool for greenfield projects, which are the projects that least need a map.

The extension is where it becomes navigation

A generated diagram you look at is a document. A generated diagram you can move through is a different tool, and that’s what the VS Code extension on the marketplace is for.

It renders the diagram inside the editor, and interacting with the diagram drives the editor. Click a node, the editor navigates there. The picture stops being a reference you consult in another window and becomes the surface you’re actually working from — you orient yourself spatially and then open the file, rather than opening files until you’re oriented.

It also runs the other direction, which is the part I use most. With configuration, you can go from code to diagram: you’re deep in a file, you’ve lost the thread of where this sits in the whole, and instead of scrolling the file tree you jump straight to this file’s position in the map. That’s the move that used to cost me the most — not finding a file, but recovering the context around a file I’d already found.

Between the two directions, the diagram stops being a thing you generate occasionally and becomes part of how you move around the project.