{ "schema": "leumas.docs.page/1", "id": "skill:leumas-atlas", "slug": "skills/leumas-atlas", "kind": "tools", "bucket": "skill", "title": "leumas-atlas", "name": "Leumas Atlas", "eyebrow": null, "chip": null, "summary": "Ask whether a helper, hook, client, formatter or util already exists before writing it, and what is worth refactoring next. Answers in ~150 tokens.", "keywords": [ "leumas-atlas", "formatter", "util", "emits patch applies", "helper", "leumas atlas architecture", "hook", "map sending somebody" ], "audience": "both", "funnel": { "product": null, "cta": null }, "body": "\n# The Codebase Atlas, from the command line\n\n**The most expensive mistake in this repo is rebuilding something that already works, and the new\ncode never looks wrong.** This is the cheap check against that. One command, ~150 tokens, before you\nwrite.\n\n```sh\npnpm atlas find \"format bytes\"\n```\n\n```\nsnapshot 12m old @ be43b9d\n\"format bytes\" — 2 existing:\n formatBytes ui …/kit/format.js:41 name:format name:bytes\n formatBytesSI web …/lib/units.js:12 name:format name:bytes\n```\n\nThat is the whole interaction. If it returns prior art, import it or extend it. If it returns\n`nothing like it. Writing it fresh looks safe.`, write it.\n\n## When to reach for this\n\n**Before writing** any of: a helper, a hook, a formatter, a parser, a validator, an API client, a\ncache, a debounce, a path/JSON accessor, a clamp/round/slug/date utility, a small React presentational\ncomponent. These are exactly what gets rewritten — the repo currently has `clamp` in six places,\n`slugify` in eight, and four separate JSON-path readers.\n\n**When asked** what to clean up, what to refactor next, which packages overlap, why two things are\nflagged as duplicates, or how well a package declares its props.\n\n**Not** for finding where a symbol is defined — that is `grep`, and it is cheaper. This answers\n\"does something LIKE this exist\", which grep cannot.\n\n## The verbs\n\n| Command | Answers | ~tokens |\n|---|---|---|\n| `pnpm atlas find \"\"` | **does this already exist?** | 150 |\n| `pnpm atlas next [n]` | what to fix first, ranked by consequence | 350 |\n| `pnpm atlas next [n] --effort` | the same list, quickest first | 350 |\n| `pnpm atlas next [n] --kind ` | **one kind of edit only** — see the census line | 350 |\n| `pnpm atlas names [n]` | names declared in more than one place | 300 |\n| `pnpm atlas shapes [n]` | functions taking and returning the same things | 300 |\n| `pnpm atlas pkg ` | one package: size, coverage, its findings | 250 |\n| `pnpm atlas why [b]` | the evidence behind one finding — **and every file that imports it** | 200 |\n| `pnpm atlas uses ` | **who imports it — every copy, with its real usage** | 200 |\n| `pnpm atlas brief ` | **everything wrong with one package, in one read** | 250 |\n| `pnpm atlas fix unexport [unit]` | the exact diff for the mechanical ones — **writes nothing** | 200 |\n| `pnpm atlas sources` | **which codebases this install has indexed** | 60 |\n| `pnpm atlas status` | what the snapshot knows, and how stale | 60 |\n\n### `uses` is what turns a duplicate into a decision\n\nTwo identical functions are not one problem. Ask before proposing anything:\n\n```\n$ pnpm atlas uses clamp\nclamp() @leumas/inputs shared/packages/inputs/src/util.js:12\n used by 24 file(s) across 1 unit(s)\nclamp() @leumas/adapter-video shared/engines/.../shorts/utils/timing.js:25\n used by 0 file(s) across 0 unit(s)\n```\n\nThe first is load-bearing; the second is a dead copy to delete. Proposing \"extract a shared clamp\"\nwithout this reads as reasonable and is the wrong move.\n\n**A zero is not proof of death.** It counts static named imports, so a route file, a CLI entry, a\nNode loader or anything reached by config legitimately shows zero. `import * as x` counts as a use\nof the whole module, and a name re-exported through more than one barrel is not followed.\n\n## `brief` first, when you are about to work in a package\n\n```sh\npnpm atlas brief @leumas/ui\n```\n\nOne read gives that unit's size, its declared-props coverage, its health flags, its queued findings\nwith the named edit for each, and how many exports are used only inside their own file. It replaces\nfive separate queries, and it is the cheapest way to know what you are walking into.\n\n## What the detectors look for, beyond duplication\n\nExports nothing imports (`over-export`, `unreferenced`), code reachable only dynamically\n(`dynamic-only`), heavily-used functions with no declared props (`hot-undeclared`), unstated results,\nunstable hubs, over-wide signatures, and architecture inversions (`layering`). Each lands in\n`atlas next` if it clears the confidence floor, and each has its own lens for browsing.\n\n## The census line, and why you usually want `--kind`\n\nEvery `next` run opens with what the whole queue is made of:\n\n```\n791 queued: over-export 208 · clone 206 · unstated-result 135 · hot-undeclared 129 ·\ncontract-twin 88 · identical 10 · unstable-hub 5 (--kind to filter)\n```\n\n**Read it from the run, never from this page** — the tree moves, and a count in prose is stale the\nday after it is written. `pnpm atlas next 1` prints it for two hundred tokens.\n\n**One detector can legitimately own the head of the list**, because the queue ranks by consequence\nrather than alphabetically — so read the census first, then filter to the kind of work you are\nactually doing. A mechanical un-export and a nineteen-`@param` documentation job are both one \"item\".\n\n```sh\npnpm atlas next 20 --kind over-export # the safe mechanical pass\npnpm atlas next 20 --kind clone # the duplication pass\n```\n\n`--effort` is the other cut: fewest edits first. An `over-export` is one keyword; documenting\n`AdminSurface` is nineteen `@param` lines. Both are one \"item\", and only `--effort` tells them apart.\n\n## Read `confidence` before acting — this is the important part\n\nEvery finding carries a **confidence** (0..1) and a **`whyNot`**: what would explain it away.\n\n- **≥ 0.6 reaches the queue**, and this is now enforced on every source rather than described. A\n `name-clash` (0.35–0.5) and a `shape-group` (0.35–0.56) are LEADS: they never appear in `next`, and\n you reach them on purpose with `pnpm atlas names` / `pnpm atlas shapes`. So is `parallel` (0.5) —\n \"worth reading both\" is not an instruction.\n- **`over-export` is 0.85** — mechanical and reversible, but not free: removing an `export` drops the\n function from the props/outputs coverage corpus and can degrade a route's generated run form. Check\n who reads it before running the diff in.\n- **Below the floor is a LEAD, not an instruction.** `unreferenced` is 0.4 on purpose: deleting a\n function on static evidence is the one action here that a diff cannot undo, and this detector was\n measurably wrong about most of its own candidates before it was graded. **Check for a registry\n entry, a config string or a route table before deleting anything it names.**\n- **`dynamic-only` is not a defect at all.** It exists so dynamically-imported code is never mistaken\n for dead code.\n\n## `atlas fix` emits a patch and never applies one\n\n```sh\npnpm atlas fix unexport @leumas/ui # prints a unified diff; writes nothing\n```\n\nThe `export` token is located by parsing, not by regex — `export` also appears in strings, comments\nand `export default`. Anything it cannot resolve exactly is skipped and counted as skipped, never\nguessed at. Apply the diff yourself, or don't.\n\n## More than one codebase\n\n**An install indexes the workspace AND every folder its operator registered** through Codex\nProjects — their own repos, their Flux projects — with one snapshot each. Every verb takes\n`--source `, and without one you are reading `leumas`, this repo.\n\n```sh\npnpm atlas sources # what this machine actually has\npnpm atlas find \"format bytes\" --source project:a1b2 # search THEIR code\n```\n\nTwo rules that matter when you are working on somebody else's install:\n\n- **`atlas sources` first, always.** \"Leumas has X\" and \"this operator has X\" are different claims,\n and only the second one is useful to them. On their machine the source list is theirs, not this\n repo's.\n- **A source with no snapshot is not an empty codebase.** It has never been swept. `sources` shows\n what is indexed; anything absent needs `pnpm atlas:snapshot --source --root ` (or the\n Index button in `/admin/atlas`) before any verb can answer about it.\n\n## Reading a `next` row\n\n```\n 1 !! clone formatBytes()/formatBytesSI() — 87% of the code is the same web<->ui 12L extract → shared/packages/*\n ↳ wired: 14 files · 3 units · 2 via namespace\n │ │ │ │ │ │\n │ │ what it is where LOC THE ACTION\n │ weight: !! cross-package (a shared contract has forked) · ! cross-file · blank same file\n rank by impact\n```\n\n**The `↳ wired` line is how far the edit reaches** — every file that imports the function this row is\nabout. `rename`, `extract`, `unexport` and `delete-one` all reach past the file they name, so a row\nwithout it is half an instruction. `0 files` is itself the finding for `over-export`. `via namespace`\ncounts `import * as` sites, which may never touch the symbol — read those before editing.\n\n**`pnpm atlas why ` prints the paths**, not `next`: this table is scanned twelve rows at a time\nand every path in it is paid again on every later turn. Ask for them when you have an edit in hand.\n\n[warning] The index follows **static named imports, one barrel hop**. Names behind `await import()`, chains\nthrough a second barrel, and anything reached by config, a route table or a loader are invisible to\nit — a zero is not proof of death, and the list is a floor on the work, never a ceiling.\n\n**The action is not a suggestion I invented — it is part of the finding.** Propose *that*, with the\nsurvivor it names. `delete-one` already tells you which copy to keep and why (the one with more\nimporters); `extract` already names the destination bucket.\n\n`identical` and `clone` are facts about the code; `parallel`, `shape-group` and `name-clash` are\nleads. That is now the floor's job rather than yours — only the facts reach `next`.\n\n**Two things a `clone` row will and will not tell you.** *\"100% of the code is the same\"* means the\ntoken streams match once locals are renamed; the comparator deliberately ignores literal VALUES, so\na pair that differs only in a threshold or a coordinate is titled *\"the same code … with different\nconstants\"* instead. Read that phrase as \"copy-paste, then tuned\" — the difference is usually\nload-bearing. And `identical` now requires the bodies to have actually been compared: a name-and-\ncontract match with a body too short to compare is a `parallel`, not a licence to delete.\n\n## Two things that will mislead you if you do not know them\n\n**1. It reads a SNAPSHOT, not the live tree.** Every command prints its age and the sha it was taken\nat, and shouts when HEAD has moved:\n\n```\nsnapshot 3d old @ 9834361 [warning] STALE: HEAD has moved since — rerun `pnpm atlas:snapshot`\n```\n\nRebuilding is `pnpm atlas:snapshot` and takes **about a minute** on this repo — it reads every file\nin the tree. Do not run it casually mid-task, and never assume it happened. If a finding looks\nwrong, check the staleness line before doubting the engine.\n\n**2. `find` is lexical, not semantic.** It matches names, then camelCase words, then doc text, then\npaths — every term you give must land somewhere. So it is excellent at `clamp`, `slugify`, \"format\nbytes\", \"read json path\", and **blind to a synonym nobody wrote**: a `throttle` will not surface if\nyou search \"rate limit\". When the stakes are high, search twice with different words.\n\n## What it will not do\n\n- It does not edit anything. Every verb is read-only.\n- It does not need the API, a server, or a login — it is a file read.\n- It does not rank its own test fixture (`test/fixtures/mini-repo` holds planted duplicates on\n purpose, and would otherwise top every list).\n\n## Where the answers come from\n\n`shared/engines/codebase-atlas` composes the two scanners that already existed —\n`@leumas/repo-graph` for imports and `@leumas/function-index` for functions and their declared props\n— and weighs every exported function against every other one across seven signals. Full reasoning in\nthat package's `SIMILARITY.md`; the data shapes in its `CONTRACT.md`.\n\nThe same findings are browsable at **`/admin/atlas`** in Studio (packages · ecosystem graph ·\nfindings), and `pnpm check:redundancy` is the ratchet that fails the build when duplication rises.\n`pnpm dup:report` writes the long-form ledger to `ops/todos/redundancy-report.md`.\n\n## The map, if you are sending somebody there\n\n`/admin/atlas` → **Ecosystem** draws three grains, folded until asked: ~32 semantic regions → files →\n**the functions they declare**. Four kinds of edge, each its own colour and each independently\nswitchable at the legend:\n\n| Edge | Means |\n|---|---|\n| `contains` | this file declares that function |\n| `imports` | this file imports that one |\n| **`uses`** | this file calls **that exact function** — the 15,731 symbol edges `atlas uses` answers one name at a time |\n| `redundancy` | the same code in two places; not a dependency at all |\n\nHovering lights a node and its neighbours, dims the rest, and fills the right rail with what is in\nthe focus — which packages, which roles, how many findings. **Every view is a URL**, so a filtered,\ndrilled-in map is a link you can send. `?layout=package` or `?layout=folder` re-anchors the same\nnodes by owner or by directory instead of by meaning.\n\n`GET /api/atlas/graph/symbols` serves the function grain if you want it without a browser.\n", "source": { "path": ".claude/skills/leumas-atlas/SKILL.md", "blobSha": "", "commit": "", "committedAt": "", "provenance": "no-git", "bytes": 13533, "hash": "1e81dc0626e315d77c1e9e7caa774c3340b5f3ea" }, "urls": { "html": "/p/skills/leumas-atlas", "json": "/docs/skills/leumas-atlas.json", "md": "/docs/skills/leumas-atlas.md" }, "links": { "composes": [], "usedBy": [], "product": [], "howTo": [], "skills": [] } }