The Codebase Atlas, from the command line

The most expensive mistake in this repo is rebuilding something that already works, and the new code never looks wrong. This is the cheap check against that. One command, ~150 tokens, before you write.

pnpm atlas find "format bytes"

snapshot 12m old @ be43b9d
"format bytes" — 2 existing:
  formatBytes      ui        …/kit/format.js:41    name:format name:bytes
  formatBytesSI    web       …/lib/units.js:12     name:format name:bytes

That is the whole interaction. If it returns prior art, import it or extend it. If it returns nothing like it. Writing it fresh looks safe., write it.

When to reach for this

Before writing any of: a helper, a hook, a formatter, a parser, a validator, an API client, a cache, a debounce, a path/JSON accessor, a clamp/round/slug/date utility, a small React presentational component. These are exactly what gets rewritten — the repo currently has clamp in six places, slugify in eight, and four separate JSON-path readers.

When asked what to clean up, what to refactor next, which packages overlap, why two things are flagged as duplicates, or how well a package declares its props.

Not for finding where a symbol is defined — that is grep, and it is cheaper. This answers "does something LIKE this exist", which grep cannot.

The verbs

uses is what turns a duplicate into a decision

Two identical functions are not one problem. Ask before proposing anything:

$ pnpm atlas uses clamp
clamp()  @leumas/inputs        shared/packages/inputs/src/util.js:12
  used by 24 file(s) across 1 unit(s)
clamp()  @leumas/adapter-video shared/engines/.../shorts/utils/timing.js:25
  used by 0 file(s) across 0 unit(s)

The first is load-bearing; the second is a dead copy to delete. Proposing "extract a shared clamp" without this reads as reasonable and is the wrong move.

A zero is not proof of death. It counts static named imports, so a route file, a CLI entry, a Node loader or anything reached by config legitimately shows zero. import * as x counts as a use of the whole module, and a name re-exported through more than one barrel is not followed.

brief first, when you are about to work in a package

pnpm atlas brief @leumas/ui

One read gives that unit's size, its declared-props coverage, its health flags, its queued findings with the named edit for each, and how many exports are used only inside their own file. It replaces five separate queries, and it is the cheapest way to know what you are walking into.

What the detectors look for, beyond duplication

Exports nothing imports (over-export, unreferenced), code reachable only dynamically (dynamic-only), heavily-used functions with no declared props (hot-undeclared), unstated results, unstable hubs, over-wide signatures, and architecture inversions (layering). Each lands in atlas next if it clears the confidence floor, and each has its own lens for browsing.

The census line, and why you usually want --kind

Every next run opens with what the whole queue is made of:

791 queued: over-export 208 · clone 206 · unstated-result 135 · hot-undeclared 129 ·
contract-twin 88 · identical 10 · unstable-hub 5   (--kind <name> to filter)

Read it from the run, never from this page — the tree moves, and a count in prose is stale the day after it is written. pnpm atlas next 1 prints it for two hundred tokens.

One detector can legitimately own the head of the list, because the queue ranks by consequence rather than alphabetically — so read the census first, then filter to the kind of work you are actually doing. A mechanical un-export and a nineteen-@param documentation job are both one "item".

pnpm atlas next 20 --kind over-export    # the safe mechanical pass
pnpm atlas next 20 --kind clone          # the duplication pass

--effort is the other cut: fewest edits first. An over-export is one keyword; documenting AdminSurface is nineteen @param lines. Both are one "item", and only --effort tells them apart.

Read confidence before acting — this is the important part

Every finding carries a confidence (0..1) and a whyNot: what would explain it away.

• ≥ 0.6 reaches the queue, and this is now enforced on every source rather than described. A

name-clash (0.35–0.5) and a shape-group (0.35–0.56) are LEADS: they never appear in next, and you reach them on purpose with pnpm atlas names / pnpm atlas shapes. So is parallel (0.5) — "worth reading both" is not an instruction.

• over-export is 0.85 — mechanical and reversible, but not free: removing an export drops the

function from the props/outputs coverage corpus and can degrade a route's generated run form. Check who reads it before running the diff in.

• Below the floor is a LEAD, not an instruction. unreferenced is 0.4 on purpose: deleting a

function on static evidence is the one action here that a diff cannot undo, and this detector was measurably wrong about most of its own candidates before it was graded. Check for a registry entry, a config string or a route table before deleting anything it names.

• dynamic-only is not a defect at all. It exists so dynamically-imported code is never mistaken

for dead code.

atlas fix emits a patch and never applies one

pnpm atlas fix unexport @leumas/ui     # prints a unified diff; writes nothing

The export token is located by parsing, not by regex — export also appears in strings, comments and export default. Anything it cannot resolve exactly is skipped and counted as skipped, never guessed at. Apply the diff yourself, or don't.

More than one codebase

An install indexes the workspace AND every folder its operator registered through Codex Projects — their own repos, their Flux projects — with one snapshot each. Every verb takes --source <id>, and without one you are reading leumas, this repo.

pnpm atlas sources                      # what this machine actually has
pnpm atlas find "format bytes" --source project:a1b2   # search THEIR code

Two rules that matter when you are working on somebody else's install:

• atlas sources first, always. "Leumas has X" and "this operator has X" are different claims,

and only the second one is useful to them. On their machine the source list is theirs, not this repo's.

• A source with no snapshot is not an empty codebase. It has never been swept. sources shows

what is indexed; anything absent needs pnpm atlas:snapshot --source <id> --root <dir> (or the Index button in /admin/atlas) before any verb can answer about it.

Reading a next row

 1 !! clone formatBytes()/formatBytesSI() — 87% of the code is the same web<->ui 12L extract → shared/packages/*
      ↳ wired: 14 files · 3 units · 2 via namespace
   │  │            │                                                            │         │    │
   │  │            what it is                                                   where     LOC  THE ACTION
   │  weight: !! cross-package (a shared contract has forked) · ! cross-file · blank same file
   rank by impact

The ↳ wired line is how far the edit reaches — every file that imports the function this row is about. rename, extract, unexport and delete-one all reach past the file they name, so a row without it is half an instruction. 0 files is itself the finding for over-export. via namespace counts import * as sites, which may never touch the symbol — read those before editing.

pnpm atlas why <fn> prints the paths, not next: this table is scanned twelve rows at a time and every path in it is paid again on every later turn. Ask for them when you have an edit in hand.

[warning] The index follows static named imports, one barrel hop. Names behind await import(), chains through a second barrel, and anything reached by config, a route table or a loader are invisible to it — a zero is not proof of death, and the list is a floor on the work, never a ceiling.

The action is not a suggestion I invented — it is part of the finding. Propose that, with the survivor it names. delete-one already tells you which copy to keep and why (the one with more importers); extract already names the destination bucket.

identical and clone are facts about the code; parallel, shape-group and name-clash are leads. That is now the floor's job rather than yours — only the facts reach next.

Two things a clone row will and will not tell you. "100% of the code is the same" means the token streams match once locals are renamed; the comparator deliberately ignores literal VALUES, so a pair that differs only in a threshold or a coordinate is titled "the same code … with different constants" instead. Read that phrase as "copy-paste, then tuned" — the difference is usually load-bearing. And identical now requires the bodies to have actually been compared: a name-and- contract match with a body too short to compare is a parallel, not a licence to delete.

Two things that will mislead you if you do not know them

1. It reads a SNAPSHOT, not the live tree. Every command prints its age and the sha it was taken at, and shouts when HEAD has moved:

snapshot 3d old @ 9834361 [warning] STALE: HEAD has moved since — rerun `pnpm atlas:snapshot`

Rebuilding is pnpm atlas:snapshot and takes about a minute on this repo — it reads every file in the tree. Do not run it casually mid-task, and never assume it happened. If a finding looks wrong, check the staleness line before doubting the engine.

2. find is lexical, not semantic. It matches names, then camelCase words, then doc text, then paths — every term you give must land somewhere. So it is excellent at clamp, slugify, "format bytes", "read json path", and blind to a synonym nobody wrote: a throttle will not surface if you search "rate limit". When the stakes are high, search twice with different words.

What it will not do

• It does not edit anything. Every verb is read-only.
• It does not need the API, a server, or a login — it is a file read.
• It does not rank its own test fixture (test/fixtures/mini-repo holds planted duplicates on

purpose, and would otherwise top every list).

Where the answers come from

shared/engines/codebase-atlas composes the two scanners that already existed — @leumas/repo-graph for imports and @leumas/function-index for functions and their declared props — and weighs every exported function against every other one across seven signals. Full reasoning in that package's SIMILARITY.md; the data shapes in its CONTRACT.md.

The same findings are browsable at /admin/atlas in Studio (packages · ecosystem graph · findings), and pnpm check:redundancy is the ratchet that fails the build when duplication rises. pnpm dup:report writes the long-form ledger to ops/todos/redundancy-report.md.

The map, if you are sending somebody there

/admin/atlas → Ecosystem draws three grains, folded until asked: ~32 semantic regions → files → the functions they declare. Four kinds of edge, each its own colour and each independently switchable at the legend:

Hovering lights a node and its neighbours, dims the rest, and fills the right rail with what is in the focus — which packages, which roles, how many findings. Every view is a URL, so a filtered, drilled-in map is a link you can send. ?layout=package or ?layout=folder re-anchors the same nodes by owner or by directory instead of by meaning.

GET /api/atlas/graph/symbols serves the function grain if you want it without a browser.