@inixiative/atlas 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # atlas
2
2
 
3
+ > One of the [inixiative](https://www.inixiative.com) building blocks. Stop rediscovering what you need to build. See [all the projects](https://github.com/inixiative).
4
+
3
5
  **The map of the codebase.** atlas reads `@atlas` annotations declared at the top of each file,
4
6
  validates them against a repo-owned **concept registry**, and generates a `MAP.md` that *cannot drift
5
- on the structural facts* — because atlas only ever asserts what is mechanically true (what exists,
7
+ on the structural facts*, because atlas only asserts what is mechanically true (what exists,
6
8
  how it connects), never maturity or correctness.
7
9
 
8
10
  It's a Biome-shaped tool: a small CLI plus a `.atlas/` config folder. The tool is generic; **your
@@ -27,8 +29,8 @@ syntax, and a file that can't hold a comment is tagged by its path.
27
29
  ## Why
28
30
 
29
31
  Hand-maintained maps (FEATURES.md, docs, prose) drift from the code. atlas makes the map a
30
- *projection* of the code: every file declares traversable **concepts** — what it is, what it's part
31
- of, what it uses — so the repo is explorable by **concept** instead of by crawling folders.
32
+ *projection* of the code: every file declares traversable **concepts** (what it is, what it's part
33
+ of, what it uses), so the repo is explorable by **concept** instead of by crawling folders.
32
34
  "Show me everything that touches caching" becomes one traversal.
33
35
 
34
36
  The core discipline: **meaning emerges from the intersection of several true edges**, not from one
@@ -164,6 +166,7 @@ atlas check [paths…] # presence + vocab + reference + thesaurus existence (t
164
166
  atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
165
167
  atlas generate # write MAP.md from the annotated tree
166
168
  atlas report # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)
169
+ atlas query [rule] # files by axis: --kind/--partOf/--uses/--path and/or a json-rules predicate
167
170
  atlas stamp [paths…] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)
168
171
  atlas hook read # Claude Code PostToolUse hook: the concept neighbourhood of the file just read
169
172
  atlas hook grep # Claude Code PostToolUse hook: the concepts a grep pattern names
@@ -171,12 +174,22 @@ atlas setup # offer to add both hooks to .claude/settings.json (--yes:
171
174
  ```
172
175
 
173
176
  Common flags: `--root <dir>`, `--json`, `generate --stdout`, `stamp --write`, `stamp --overwrite`,
174
- `coverage --min/--ratchet`, `report --out <dir>/--md/--html`.
177
+ `check --warn-only`, `coverage --min/--ratchet`, `report --out <dir>/--md/--html`.
178
+
179
+ `atlas query` filters files by their tags. Each flag is a `contains` test on one axis and the flags
180
+ AND together; a [json-rules](https://github.com/inixiative/json-rules) predicate, passed as one JSON
181
+ argument, ANDs with them. Fields are `path`, `kind`, `partOf` and `uses`; an unannotated file has
182
+ empty lists.
183
+
184
+ ```bash
185
+ atlas query --partOf feature:billing --kind controller
186
+ atlas query '{"field":"uses","operator":"contains","value":"infrastructure:redis"}' --json
187
+ ```
175
188
 
176
189
  ## For AI agents
177
190
 
178
191
  atlas exists largely so agents stop grab-bagging files and answering from stale labels. Drop this
179
- line into your agent's system prompt / `CLAUDE.md` / `AGENTS.md` so it navigates by **concept**
192
+ line into your agent's system prompt / `CLAUDE.md` / `AGENTS.md` so it finds code by **concept**
180
193
  instead of crawling folders:
181
194
 
182
195
  > This repo is mapped by **atlas**. To find code by concept instead of by filename: read `MAP.md`
@@ -191,7 +204,7 @@ before opening it. In an A/B test on a repo with a transitive dependency, agents
191
204
  used `atlas graph` and solved a "what reaches redis (directly or transitively)" question in ~2 tool
192
205
  calls; agents left to `grep` took 2–3× as many and risk missing the transitive edge entirely.
193
206
 
194
- ### Hooks: the neighbourhood on every Read and Grep
207
+ ## Hooks: the neighbourhood on every Read and Grep
195
208
 
196
209
  The map only helps if the agent looks at it. `atlas hook read` and `atlas hook grep` put it in
197
210
  front of the agent without asking: when it reads a file, it sees which concepts the file is part
@@ -268,7 +281,7 @@ How they behave:
268
281
  adapter (stdin JSON in, `hookSpecificOutput.additionalContext` out). Another harness needs only
269
282
  its own adapter.
270
283
 
271
- ### Thesaurus
284
+ ## Thesaurus
272
285
 
273
286
  A grep for the job ("seed a user", "lock", "factory") names no concept, so the grep hook used to
274
287
  say nothing at exactly the moment an agent was looking for something that already exists. The
@@ -343,13 +356,13 @@ case's expected answer: a thesaurus tuned to its tests only teaches the tests.
343
356
 
344
357
  `atlas report` emits two artifacts:
345
358
 
346
- - **`COVERAGE.md`** — diffable, GitHub-native: a totals table, a Mermaid coverage pie, a per-category
359
+ - **`COVERAGE.md`**: a diffable, GitHub-native file with a totals table, a Mermaid coverage pie, a per-category
347
360
  gap table (required `@kind`/`@partOf` gaps split from the `@uses` curation buckets), and a Mermaid
348
- concept-dependency graph. Categories group by **effective concept** — a file's declared `@partOf`, or the
349
- rules' *predicted* concept when unannotated — so you get a per-concept work plan even at 0% coverage.
350
- - **`atlas.html`** — a self-contained interactive graph ([Cytoscape.js](https://js.cytoscape.org/)):
361
+ concept-dependency graph. Categories group by **effective concept** (a file's declared `@partOf`, or the
362
+ rules' *predicted* concept when unannotated), so you get a per-concept work plan even at 0% coverage.
363
+ - **`atlas.html`**: a self-contained interactive graph ([Cytoscape.js](https://js.cytoscape.org/)):
351
364
  concepts grouped by class (compound nodes), coloured by coverage; click a concept to drill into its file
352
- list, click to highlight its dependencies (traverse). No build step — open it in a browser.
365
+ list, click to highlight its dependencies (traverse). No build step: open it in a browser.
353
366
 
354
367
  ## The annotation model
355
368
 
@@ -357,7 +370,7 @@ case's expected answer: a thesaurus tuned to its tests only teaches the tests.
357
370
  |----------|-----|-------|-------|
358
371
  | What is this? | `@kind` | closed enum | 1+, e.g. `entrypoint, route` (a role, not a layer) |
359
372
  | What is it part of? | `@partOf` | `class:name` concept(s) | membership; multi is normal |
360
- | What does it use? | `@uses` | `class:name` concept(s) | dependency, load-bearing only |
373
+ | What does it use? | `@uses` | `class:name` concept(s) | real dependencies only |
361
374
  | What does it build? | `@constructs` | factory output | constructors only |
362
375
 
363
376
  All axes are multi-valued (comma-separated on one line). `@atlas` opens the block.
@@ -376,36 +389,36 @@ A top-of-file JSDoc block, above the imports (below a shebang if present):
376
389
  ```
377
390
 
378
391
  Rules of thumb:
379
- - **`@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`).
380
- - **`@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`.
381
- - **`@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).
382
- - **Validate names against the repo's `.atlas/`** — `@kind` ∈ `kinds.ts`; `@partOf`/`@uses` must name a concept that exists in `concepts.ts`.
383
- - **Prefer several broad-true tags over one narrow tag** — meaning emerges from the intersection of true edges, not from one hyper-specific label.
392
+ - **`@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`).
393
+ - **`@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: `makeController` and the route-template helper services are all `@partOf primitive:routeTemplates`.
394
+ - **`@uses` is a real dependency 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 found no such dependency; otherwise omit the line (= uncurated).
395
+ - **Validate names against the repo's `.atlas/`:** `@kind` ∈ `kinds.ts`; `@partOf`/`@uses` must name a concept that exists in `concepts.ts`.
396
+ - **Prefer several broad-true tags over one narrow tag:** meaning emerges from the intersection of true edges, not from one hyper-specific label.
384
397
 
385
398
  ### `@uses` is never auto-stamped
386
399
 
387
400
  Absence is meaningful, so atlas leaves `@uses` out of stamping entirely:
388
401
 
389
402
  - **no `@uses` line** = *uncurated* (nobody filled it in)
390
- - **`@uses none`** = *curated-empty* (a human looked; it uses nothing load-bearing)
403
+ - **`@uses none`** = *curated-empty* (a human looked; it has no real dependency)
391
404
  - **`@uses? x`** = *proposed* (a patcher suggestion awaiting acceptance)
392
405
 
393
406
  `coverage` reports these as distinct buckets.
394
407
 
395
408
  ## The patcher: `atlas stamp`
396
409
 
397
- Blanks are fillable on demand — the `eslint --fix` shape. Always **dry-run by default**; pass
410
+ Blanks are fillable on demand, in the `eslint --fix` shape. Always **dry-run by default**; pass
398
411
  `--write` to apply.
399
412
 
400
- - **Targeting** — the whole repo by default, or any number of files and folders (`src/`, `./src`, `.`),
413
+ - **Targeting:** the whole repo by default, or any number of files and folders (`src/`, `./src`, `.`),
401
414
  each resolved against the repo root; a target that doesn't exist or lies outside it is an error.
402
- - **Additive (default)** — fill only what's absent; never modify an existing tag; never touch `@uses`.
403
- - **Overwrite (`--overwrite`)** — resync the derivable axes (`@kind`/`@partOf`) to the current
415
+ - **Additive (default):** fill only what's absent; never modify an existing tag; never touch `@uses`.
416
+ - **Overwrite (`--overwrite`):** resync the derivable axes (`@kind`/`@partOf`) to the current
404
417
  rules; **never** overwrites curated `@uses`. A `@atlas pin` block is exempt.
405
418
 
406
419
  ## CI
407
420
 
408
- `atlas check` is the CI primitive — it exits non-zero on any problem, so wiring it in is just
421
+ `atlas check` is the CI primitive. It exits non-zero on any problem, so wiring it in means
409
422
  running it in a workflow (no separate package needed). Copy-paste examples live in
410
423
  [`examples/ci/`](./examples/ci/): a full-repo GitHub Actions workflow with a `MAP.md` freshness
411
424
  gate, an incremental PR variant, and a pre-commit hook. The recommended rollout on an existing
@@ -417,7 +430,7 @@ atlas check <paths…> # enforce only the files a PR changes (skips registr
417
430
  atlas check # enforce the whole repo
418
431
  ```
419
432
 
420
- Gate **coverage** the same way — a percentage floor or a ratchet that forbids regressions
433
+ Gate **coverage** the same way, with a percentage floor or a ratchet that forbids regressions
421
434
  (ideal for a repo starting near 0%):
422
435
 
423
436
  ```bash
@@ -428,10 +441,10 @@ atlas coverage --update-baseline # record the current count (commit the baseline
428
441
 
429
442
  ## Enforcement: existence, NOT correctness
430
443
 
431
- `atlas check` verifies annotations **exist and use valid vocabulary** — presence of a block, that
444
+ `atlas check` verifies annotations **exist and use valid vocabulary**: presence of a block, that
432
445
  `@kind` is in the vocab, that `@partOf`/`@uses` name a concept that exists, and that a
433
446
  concept's doc references resolve. It explicitly does **not** reconcile the import graph, judge
434
- whether a `@partOf` is "really true," or derive any status. Those are fool's errands that trade a
447
+ whether a `@partOf` is true, or derive any status. Those are fool's errands that trade a
435
448
  clear structural guarantee for a fragile proxy.
436
449
 
437
450
  ## License
@@ -9,7 +9,7 @@ on any problem). These are copy-paste examples for wiring it in. Pick the ones y
9
9
  | [`github-actions-incremental.yml`](./github-actions-incremental.yml) | Check only the paths changed in a PR |
10
10
  | [`pre-commit`](./pre-commit) | Local git hook: check the staged files before commit |
11
11
 
12
- ## Rollout (DEV-003 Phase 4): warn-only → enforcing
12
+ ## Rollout: warn-only → enforcing
13
13
 
14
14
  `atlas check` is binary (any problem fails). On an existing codebase that starts at ~0% annotated,
15
15
  flip the switch gradually:
@@ -21,7 +21,7 @@ jobs:
21
21
  - run: if [ -f package.json ]; then bun install --frozen-lockfile; fi
22
22
 
23
23
  # ── Annotation check ────────────────────────────────────────────────
24
- # Rollout (DEV-003 Phase 4) — start warn-only, flip to enforcing later:
24
+ # Rollout — start warn-only, flip to enforcing later:
25
25
  # warn-only: bunx @inixiative/atlas check --warn-only # prints, never fails CI
26
26
  # enforcing: bunx @inixiative/atlas check # fails CI on any problem
27
27
  - name: atlas check
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@inixiative/atlas",
3
- "version": "0.5.0",
4
- "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.",
3
+ "version": "0.5.1",
4
+ "description": "The map of the codebase: @atlas code annotations, a concept registry and a MAP.md that asserts only what is mechanically true, so it cannot drift",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "inixiative",
@@ -53,13 +53,13 @@
53
53
  },
54
54
  "devDependencies": {
55
55
  "@biomejs/biome": "2.5.2",
56
- "@inixiative/config": "^0.5.169",
56
+ "@inixiative/config": "^0.5.227",
57
57
  "@types/bun": "1.4.4",
58
58
  "lefthook": "2.1.9",
59
59
  "typescript": "6.0.3"
60
60
  },
61
61
  "dependencies": {
62
- "@inixiative/json-rules": "^3.16.0"
62
+ "@inixiative/json-rules": "^4.2.0"
63
63
  },
64
64
  "packageManager": "bun@1.4.4"
65
65
  }