@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 +40 -27
- package/examples/ci/README.md +1 -1
- package/examples/ci/github-actions.yml +1 -1
- package/package.json +4 -4
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
|
|
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**
|
|
31
|
-
of, what it uses
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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**
|
|
349
|
-
rules' *predicted* concept when unannotated
|
|
350
|
-
- **`atlas.html
|
|
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
|
|
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) |
|
|
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
|
|
380
|
-
- **`@partOf` is membership
|
|
381
|
-
- **`@uses` is dependency
|
|
382
|
-
- **Validate names against the repo's `.atlas
|
|
383
|
-
- **Prefer several broad-true tags over one narrow tag
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
403
|
-
- **Overwrite (`--overwrite`)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
package/examples/ci/README.md
CHANGED
|
@@ -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
|
|
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
|
|
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.
|
|
4
|
-
"description": "The map of the codebase
|
|
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.
|
|
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": "^
|
|
62
|
+
"@inixiative/json-rules": "^4.2.0"
|
|
63
63
|
},
|
|
64
64
|
"packageManager": "bun@1.4.4"
|
|
65
65
|
}
|