# leumas-atlas Ask whether a helper, hook, client, formatter or util already exists before writing it, and what is worth refactoring next. Answers in ~150 tokens. # 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. ```sh 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 | Command | Answers | ~tokens | |---|---|---| | `pnpm atlas find ""` | **does this already exist?** | 150 | | `pnpm atlas next [n]` | what to fix first, ranked by consequence | 350 | | `pnpm atlas next [n] --effort` | the same list, quickest first | 350 | | `pnpm atlas next [n] --kind ` | **one kind of edit only** — see the census line | 350 | | `pnpm atlas names [n]` | names declared in more than one place | 300 | | `pnpm atlas shapes [n]` | functions taking and returning the same things | 300 | | `pnpm atlas pkg ` | one package: size, coverage, its findings | 250 | | `pnpm atlas why [b]` | the evidence behind one finding — **and every file that imports it** | 200 | | `pnpm atlas uses ` | **who imports it — every copy, with its real usage** | 200 | | `pnpm atlas brief ` | **everything wrong with one package, in one read** | 250 | | `pnpm atlas fix unexport [unit]` | the exact diff for the mechanical ones — **writes nothing** | 200 | | `pnpm atlas sources` | **which codebases this install has indexed** | 60 | | `pnpm atlas status` | what the snapshot knows, and how stale | 60 | ### `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 ```sh 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 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". ```sh 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 ```sh 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 `, and without one you are reading `leumas`, this repo. ```sh 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 --root ` (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 ` 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: | Edge | Means | |---|---| | `contains` | this file declares that function | | `imports` | this file imports that one | | **`uses`** | this file calls **that exact function** — the 15,731 symbol edges `atlas uses` answers one name at a time | | `redundancy` | the same code in two places; not a dependency at all | 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. --- Source: .claude/skills/leumas-atlas/SKILL.md Canonical: https://docs.leumas.tech/p/skills/leumas-atlas