{"_id":"@inixiative/atlas","_rev":"4-9517ee7d66d88d90955d56a15c77a39f","name":"@inixiative/atlas","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.0":{"name":"@inixiative/atlas","version":"0.0.0","keywords":["atlas","codebase-map","annotations","architecture","seams","documentation","static-analysis"],"author":{"name":"inixiative"},"license":"MIT","_id":"@inixiative/atlas@0.0.0","maintainers":[{"name":"inixiative","email":"aron.greenspan@inixiative.com"}],"homepage":"https://github.com/inixiative/atlas#readme","bugs":{"url":"https://github.com/inixiative/atlas/issues"},"bin":{"atlas":"bin/atlas.ts"},"dist":{"shasum":"b98b056f46aa6984a722f76bdc3b13662b98ad23","tarball":"https://registry.npmjs.org/@inixiative/atlas/-/atlas-0.0.0.tgz","fileCount":35,"integrity":"sha512-8LTdOYrkuMqyJ411eKpehYZH8df+SyWH3JBZWXl2fPFzLBCfodi2OWVvcI2FLgOHKlZum6EXANnRZkfO2UJHuQ==","signatures":[{"sig":"MEYCIQDpVxyd0j+hegX2vakL9UdSf4eZoZg7uld6q/Qr3DsCCQIhAMfcyXRZFgZD/B/+aIM5xcqfV8cLg4EiVhN40WliEPLG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97131},"type":"module","engines":{"bun":">=1.0.0"},"exports":{".":"./src/index.ts","./config":"./src/config/defineConfig.ts"},"gitHead":"b7502da1eaa40ec348e53a31001ae046ea98eddf","scripts":{"test":"bun test","atlas":"bun run ./bin/atlas.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"inixiative","email":"aron.greenspan@inixiative.com"},"repository":{"url":"git+https://github.com/inixiative/atlas.git","type":"git"},"_npmVersion":"10.9.3","description":"The map of the codebase — @atlas code annotations + a seam registry + a drift-proof MAP.md. A map that can only assert what is mechanically true.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@inixiative/json-rules":"^2.6.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/atlas_0.0.0_1781235557053_0.5236307396626814","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@inixiative/atlas","version":"0.1.0","keywords":["atlas","codebase-map","annotations","architecture","seams","documentation","static-analysis"],"author":{"name":"inixiative"},"license":"MIT","_id":"@inixiative/atlas@0.1.0","maintainers":[{"name":"inixiative","email":"aron.greenspan@inixiative.com"}],"homepage":"https://github.com/inixiative/atlas#readme","bugs":{"url":"https://github.com/inixiative/atlas/issues"},"bin":{"atlas":"bin/atlas.ts"},"dist":{"shasum":"a38d6dfc035fab5c2e15e073d7b9d1a87d96be43","tarball":"https://registry.npmjs.org/@inixiative/atlas/-/atlas-0.1.0.tgz","fileCount":35,"integrity":"sha512-vHLSVVmMmPZcGCMIcO3ojoR6k1Eu0u+xuzlMMB/CaAwX6SaF8seoviRVqWbAuorGrrbuD9V5/y0lL81JPWcDxg==","signatures":[{"sig":"MEUCIQCBbsuTy9X2j6Kb4MRHTZg8smniZA5QqbLBjjrZlIKfiAIgb+Pn6eo360nBg7fTWc4jjdTkBeYY4To14kJNrZrcrzw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97574},"type":"module","engines":{"bun":">=1.0.0"},"exports":{".":"./src/index.ts","./config":"./src/config/defineConfig.ts"},"gitHead":"227bcd2da63633a6c2485c022f125a85be108005","scripts":{"test":"bun test","atlas":"bun run ./bin/atlas.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"inixiative","email":"aron.greenspan@inixiative.com"},"repository":{"url":"git+https://github.com/inixiative/atlas.git","type":"git"},"_npmVersion":"10.9.3","description":"The map of the codebase — @atlas code annotations + a seam registry + a drift-proof MAP.md. A map that can only assert what is mechanically true.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@inixiative/json-rules":"^2.6.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/atlas_0.1.0_1781317491890_0.7270430437272668","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@inixiative/atlas","version":"0.1.1","description":"The map of the codebase — @atlas code annotations + a seam registry + a drift-proof MAP.md. A map that can only assert what is mechanically true.","type":"module","license":"MIT","author":{"name":"inixiative"},"homepage":"https://github.com/inixiative/atlas#readme","repository":{"type":"git","url":"git+https://github.com/inixiative/atlas.git"},"bugs":{"url":"https://github.com/inixiative/atlas/issues"},"keywords":["atlas","codebase-map","annotations","architecture","seams","documentation","static-analysis"],"bin":{"atlas":"bin/atlas.ts"},"exports":{".":"./src/index.ts","./config":"./src/config/defineConfig.ts"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit","check":"bun run typecheck && bun run lint && bun run test","atlas":"bun run ./bin/atlas.ts","prepublishOnly":"bun run check && bun run test","lint":"biome check .","prepare":"lefthook install"},"engines":{"bun":">=1.0.0"},"publishConfig":{"access":"public"},"devDependencies":{"@types/bun":"1.3.14","typescript":"6.0.3","@biomejs/biome":"2.5.2","@inixiative/config":"^0.2.1","lefthook":"2.1.9"},"dependencies":{"@inixiative/json-rules":"^2.13.0"},"packageManager":"bun@1.3.14","_id":"@inixiative/atlas@0.1.1","gitHead":"23b799d822ed5afc10751be35d268bd07a07b46f","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-vEXZ3mFKAoEW8lk9NjumMcgLpG57qX813Z0X+xXXBPYZXrEUgRXdqJiLZTEEmntZddo4J28UfUGU7BERmOFyBQ==","shasum":"2d582036b52e8416cbe286ad7ea516a6a7f95a5d","tarball":"https://registry.npmjs.org/@inixiative/atlas/-/atlas-0.1.1.tgz","fileCount":35,"unpackedSize":99060,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAfJmYscBeigG841aldelnTUKSFpr/tjFIijhVHKt3TLAiA1lCNoKkqf0lHwtD1+oHyOb8kGiPoqd/5rTbMdalXpqQ=="}]},"_npmUser":{"name":"aron.inixiative","email":"aron.greenspan@inixiative.com"},"directories":{},"maintainers":[{"name":"aron.inixiative","email":"aron.greenspan@inixiative.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/atlas_0.1.1_1783046233267_0.03331690556635336"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T03:39:16.903Z","modified":"2026-07-03T02:37:13.548Z","0.0.0":"2026-06-12T03:39:17.182Z","0.1.0":"2026-06-13T02:24:52.036Z","0.1.1":"2026-07-03T02:37:13.408Z"},"bugs":{"url":"https://github.com/inixiative/atlas/issues"},"author":{"name":"inixiative"},"license":"MIT","homepage":"https://github.com/inixiative/atlas#readme","keywords":["atlas","codebase-map","annotations","architecture","seams","documentation","static-analysis"],"repository":{"type":"git","url":"git+https://github.com/inixiative/atlas.git"},"description":"The map of the codebase — @atlas code annotations + a seam registry + a drift-proof MAP.md. A map that can only assert what is mechanically true.","maintainers":[{"name":"aron.inixiative","email":"aron.greenspan@inixiative.com"}],"readme":"# atlas\n\n**The map of the codebase.** atlas reads `@atlas` annotations declared at the top of each file,\nvalidates them against a repo-owned **concept registry**, and generates a `MAP.md` that *cannot drift\non the structural facts* — because atlas only ever asserts what is mechanically true (what exists,\nhow it connects), never maturity or correctness.\n\nIt's a Biome-shaped tool: a small CLI plus a `.atlas/` config folder. The tool is generic; **your\nrepo defines its own vocabulary.**\n\n```ts\n/**\n * @atlas\n * @kind controller\n * @partOf feature:tenancy\n * @uses primitive:authz, infrastructure:redis\n */\n```\n\n## Why\n\nHand-maintained maps (FEATURES.md, docs, prose) drift from the code. atlas makes the map a\n*projection* of the code: every file declares traversable **concepts** — what it is, what it's part\nof, what it uses — so the repo is explorable by **concept** instead of by crawling folders.\n\"Show me everything that touches caching\" becomes one traversal.\n\nThe core discipline: **meaning emerges from the intersection of several true edges**, not from one\nhyper-specific label. Keep the vocabulary broad but closed; apply it liberally.\n\n## Install\n\n```bash\nbun add -d @inixiative/atlas\n```\n\natlas is Bun-native (it imports your `.atlas/*.ts` config directly).\n\n## Configure\n\nA consuming repo gets a `.atlas/` folder. atlas ships a sensible default `kinds` vocab; the\nrepo **owns** its concept registry.\n\n```\n.atlas/\n  config.ts     // stamp rules (path → tags) + ignore + reference resolvers\n  kinds.ts      // @kind vocab — extends atlas's defaults\n  concepts.ts      // the concept registry — repo-OWNED, structure only\n```\n\n```ts\n// .atlas/concepts.ts — structure only, no status/note. YOU define the concept classes\n// (feature/primitive/…) and the constituent categories (module/package/…).\nimport type { ConceptRegistry } from '@inixiative/atlas';\n\nexport const CONCEPTS: ConceptRegistry = {\n  'feature:tenancy': { module: ['organization', 'space'], docs: ['AUTH.md'] },\n  'infrastructure:redis': { docs: ['REDIS.md'] },\n};\n```\n\n```ts\n// .atlas/config.ts — stamp rules compose; explicit always wins.\nimport { defineConfig, partOfFor } from '@inixiative/atlas/config';\n\nexport default defineConfig({\n  include: ['apps/**/*.ts', 'packages/**/*.ts'],\n  ignore: ['**/*.test.ts', '**/index.ts'],\n  stamp: [\n    { include: '**/controllers/**', kind: 'controller' },          // @kind from a structural glob\n    { include: 'apps/api/src/modules/$1/**', partOf: partOfFor('module', '$1') }, // @partOf from a capture\n  ],\n  references: { docs: (v) => `docs/${v}` },                         // for reference-existence checks\n});\n```\n\nA complete, commented set you can copy into your repo's `.atlas/` is in\n[`examples/atlas-config/`](./examples/atlas-config/) (`kinds.ts`, `concepts.ts`, `config.ts`).\n\n## CLI\n\n```bash\natlas graph       # reverse indexes: concept → files, file → concepts, doc → concepts\natlas check       # presence + vocab existence + reference existence  (the CI command)\natlas coverage    # unannotated files; @uses curation buckets; unresolved memberships\natlas generate    # write MAP.md from the annotated tree\natlas report      # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)\natlas stamp [dir] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)\n```\n\nCommon flags: `--root <dir>`, `--json`, `generate --stdout`, `stamp --write`, `stamp --overwrite`,\n`coverage --min/--ratchet`, `report --out <dir>/--md/--html`.\n\n## For AI agents\n\natlas exists largely so agents stop grab-bagging files and answering from stale labels. Drop this\nline into your agent's system prompt / `CLAUDE.md` / `AGENTS.md` so it navigates by **concept**\ninstead of crawling folders:\n\n> This repo is mapped by **atlas**. To find code by concept instead of by filename: read `MAP.md`\n> for the concept overview; run `bunx atlas graph --json` for the reverse indexes (concept → files via\n> `@partOf`, concept → consumers via `@uses`); and read a file's top-of-file `@atlas` block\n> (`@kind` / `@partOf` / `@uses`) before its body. Prefer these over `grep` for \"what touches X\" /\n> \"what's part of Y\" questions.\n\nWhy it helps: the agent gets the high-altitude map without reading the tree, answers \"everything\nthat touches caching\" in **one** `graph --json` call, and learns a file's role/edges from its block\nbefore opening it. In an A/B test on a repo with a transitive dependency, agents given this line\nused `atlas graph` and solved a \"what reaches redis (directly or transitively)\" question in ~2 tool\ncalls; agents left to `grep` took 2–3× as many and risk missing the transitive edge entirely.\n\n## Visualize\n\n`atlas report` emits two artifacts:\n\n- **`COVERAGE.md`** — diffable, GitHub-native: a totals table, a Mermaid coverage pie, a per-category\n  gap table (required `@kind`/`@partOf` gaps split from the `@uses` curation buckets), and a Mermaid\n  concept-dependency graph. Categories group by **effective concept** — a file's declared `@partOf`, or the\n  rules' *predicted* concept when unannotated — so you get a per-concept work plan even at 0% coverage.\n- **`atlas.html`** — a self-contained interactive graph ([Cytoscape.js](https://js.cytoscape.org/)):\n  concepts grouped by class (compound nodes), coloured by coverage; click a concept to drill into its file\n  list, click to highlight its dependencies (traverse). No build step — open it in a browser.\n\n## The annotation model\n\n| Question | Tag | Value | Notes |\n|----------|-----|-------|-------|\n| What is this? | `@kind` | closed enum | 1+, e.g. `entrypoint, route` (a role, not a layer) |\n| What is it part of? | `@partOf` | `class:name` concept(s) | membership; multi is normal |\n| What does it use? | `@uses` | `class:name` concept(s) | dependency, load-bearing only |\n| What does it build? | `@constructs` | factory output | constructors only |\n\nAll axes are multi-valued (comma-separated on one line). `@atlas` opens the block.\n\n### Writing a block (for agents & humans)\n\nA top-of-file JSDoc block, above the imports (below a shebang if present):\n\n```ts\n/**\n * @atlas\n * @kind controller\n * @partOf feature:billing, superadmin\n * @uses primitive:authz, infrastructure:redis\n */\n```\n\nRules of thumb:\n- **`@kind` is a ROLE, never a layer.** Use the file's role(s) from the vocab. Never put `feature`/`primitive`/`infrastructure` in `@kind` — those are concept *classes*, expressed via `@partOf`. A file can hold several roles (`constructor, registry`).\n- **`@partOf` is membership** — the concept(s) this file *composes* (remove it and the concept breaks). Multiple is normal and expected: a feature has **many** controllers/routes/**entrypoints**; a file can be part of a feature *and* a cross-cutting tag (`feature:inquiry, superadmin`). The reusable helpers that build something belong to it — e.g. `makeController` and the route-template helper services are all `@partOf primitive:routeTemplates`.\n- **`@uses` is dependency, LOAD-BEARING only** — a concept this file depends on but isn't part of, where someone reasoning about that concept's blast radius needs this file. Not every import. Skip incidental touches (one `db.x.update()` through the request context is not \"using\" the database). Write `@uses none` only after a human/agent looked and it genuinely uses nothing load-bearing; otherwise omit the line (= uncurated).\n- **Validate names against the repo's `.atlas/`** — `@kind` ∈ `kinds.ts`; `@partOf`/`@uses` must name a concept that exists in `concepts.ts`.\n- **Prefer several broad-true tags over one narrow tag** — meaning emerges from the intersection of true edges, not from one hyper-specific label.\n\n### `@uses` is never auto-stamped\n\nAbsence is meaningful, so atlas leaves `@uses` out of stamping entirely:\n\n- **no `@uses` line** = *uncurated* (nobody filled it in)\n- **`@uses none`** = *curated-empty* (a human looked; it uses nothing load-bearing)\n- **`@uses? x`** = *proposed* (a patcher suggestion awaiting acceptance)\n\n`coverage` reports these as distinct buckets.\n\n## The patcher: `atlas stamp`\n\nBlanks are fillable on demand — the `eslint --fix` shape. Always **dry-run by default**; pass\n`--write` to apply.\n\n- **Targeting** — `all` (default), a folder, or a single file.\n- **Additive (default)** — fill only what's absent; never modify an existing tag; never touch `@uses`.\n- **Overwrite (`--overwrite`)** — resync the derivable axes (`@kind`/`@partOf`) to the current\n  rules; **never** overwrites curated `@uses`. A `@atlas pin` block is exempt.\n\n## CI\n\n`atlas check` is the CI primitive — it exits non-zero on any problem, so wiring it in is just\nrunning it in a workflow (no separate package needed). Copy-paste examples live in\n[`examples/ci/`](./examples/ci/): a full-repo GitHub Actions workflow with a `MAP.md` freshness\ngate, an incremental PR variant, and a pre-commit hook. The recommended rollout on an existing\ncodebase is **warn-only → incremental enforcing → fully enforcing**:\n\n```bash\natlas check --warn-only   # prints problems, never fails CI (rollout start)\natlas check <path>        # enforce only changed paths (skips registry-wide reference checks)\natlas check               # enforce the whole repo\n```\n\nGate **coverage** the same way — a percentage floor or a ratchet that forbids regressions\n(ideal for a repo starting near 0%):\n\n```bash\natlas coverage --min 80          # fail below 80% annotated\natlas coverage --ratchet         # fail if unannotated count exceeds .atlas/coverage-baseline.json\natlas coverage --update-baseline # record the current count (commit the baseline)\n```\n\n## Enforcement: existence, NOT correctness\n\n`atlas check` verifies annotations **exist and use valid vocabulary** — presence of a block, that\n`@kind` is in the vocab, that `@partOf`/`@uses` name a concept that exists, and that a\nconcept's doc references resolve. It explicitly does **not** reconcile the import graph, judge\nwhether a `@partOf` is \"really true,\" or derive any status. Those are fool's errands that trade a\nclear structural guarantee for a fragile proxy.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}