@inixiative/atlas 0.4.1 → 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,12 +1,15 @@
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
9
- repo defines its own vocabulary.**
11
+ repo defines its own vocabulary**, in any language: the block is written in the file's own comment
12
+ syntax, and a file that can't hold a comment is tagged by its path.
10
13
 
11
14
  ```ts
12
15
  /**
@@ -17,11 +20,17 @@ repo defines its own vocabulary.**
17
20
  */
18
21
  ```
19
22
 
23
+ ```py
24
+ # @atlas
25
+ # @kind service
26
+ # @partOf feature:signing
27
+ ```
28
+
20
29
  ## Why
21
30
 
22
31
  Hand-maintained maps (FEATURES.md, docs, prose) drift from the code. atlas makes the map a
23
- *projection* of the code: every file declares traversable **concepts** — what it is, what it's part
24
- 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.
25
34
  "Show me everything that touches caching" becomes one traversal.
26
35
 
27
36
  The core discipline: **meaning emerges from the intersection of several true edges**, not from one
@@ -30,10 +39,80 @@ hyper-specific label. Keep the vocabulary broad but closed; apply it liberally.
30
39
  ## Install
31
40
 
32
41
  ```bash
33
- bun add -d @inixiative/atlas
42
+ bun add -d @inixiative/atlas # a JavaScript/TypeScript repo
43
+ bunx @inixiative/atlas init # any repo: no package.json or node_modules needed
34
44
  ```
35
45
 
36
- atlas is Bun-native (it imports your `.atlas/*.ts` config directly).
46
+ atlas runs on Bun (it imports your `.atlas/*.ts` config directly). The config's own
47
+ `@inixiative/atlas` imports (in any file under `.atlas/`) are bound to the atlas that is running,
48
+ so a Python, Go or docs repo needs nothing installed besides Bun.
49
+
50
+ **A repo you don't trust.** Running atlas runs that repo's code: it imports `.atlas/**/*.ts`, and
51
+ Bun applies the `bunfig.toml` of the directory you run it from (a `preload` there runs first).
52
+ Read `.atlas/` before running atlas on such a repo, run it from a neutral directory with
53
+ `--root <repo>`, or use a sandbox. atlas itself can't block a preload; Bun runs it before atlas
54
+ starts.
55
+
56
+ ## Any language
57
+
58
+ atlas reads one table of comment styles, grouped by how a language writes a comment, and
59
+ `check`, `stamp`, `graph` and the hooks all use it:
60
+
61
+ | Style | Block | Files |
62
+ |---|---|---|
63
+ | `c` | `/* … */` (JS/TS: `/** … */`) | `.ts` `.tsx` `.mts` `.cts` `.js` `.jsx` `.mjs` `.cjs` `.go` `.java` `.kt` `.kts` `.rs` `.c` `.h` `.cc` `.cpp` `.hpp` `.cs` `.swift` `.scala` `.dart` `.groovy` `.proto` `.css` `.scss` `.less` `.php` |
64
+ | `html` | `<!-- … -->` | `.md` `.markdown` `.html` `.htm` `.xml` `.vue` `.svelte` |
65
+ | `mdx` | `{/* … */}` | `.mdx` |
66
+ | `hash` | `# ` lines | `.py` `.pyi` `.rb` `.sh` `.bash` `.zsh` `.fish` `.yaml` `.yml` `.toml` `.ex` `.exs` `.r` `.pl` `.pm` `.tf` `.nix` `.cmake` `.ps1` `.dockerfile` `Dockerfile` `Containerfile` `Makefile` `GNUmakefile` `Gemfile` `Rakefile` `Justfile` `Procfile` |
67
+ | `slash` | `// ` lines | `.zig` |
68
+ | `dash` | `-- ` lines | `.sql` `.lua` `.hs` `.elm` |
69
+ | `semicolon` | `;; ` lines | `.clj` `.cljs` `.cljc` `.edn` `.lisp` `.el` `.scm` `.rkt` |
70
+ | `dotdot` | `.. ` lines | `.rst` |
71
+
72
+ Add files to a style in `.atlas/config.ts`: `comments: { hash: ['.nix', 'Tiltfile'] }` (`.ext` or
73
+ an exact file name; listing one under another style moves it there).
74
+
75
+ - **Line styles** (`#`, `//`, `--`, `;;`, `..`): the block is the `@atlas` line plus the
76
+ `@kind`/`@partOf`/`@uses`/`@constructs` lines right after it (repeated prefixes like `;;` and
77
+ `##` read as one; an empty comment line between them is bridged). Any other line ends it, so a
78
+ prose comment or a doc tag next to the block (LuaLS `---@class`, YARD `# @deprecated`) is never
79
+ part of it and never rewritten.
80
+ - **Placement.** A fresh block goes at the top, below what must stay first: a shebang (not Rust's
81
+ `#![…]`), an Emacs `-*- … -*-` line, Python's or Ruby's encoding line, Go build constraints,
82
+ Dockerfile parser directives, Markdown front matter, an XML prolog, `<?php`, CSS `@charset`. Language rules on
83
+ top of the style:
84
+ - the C family writes plain `/* */`, because `/**` is a doc comment in Rust (an error before
85
+ `//!`), C#, Dart, Java and Go; JS/TS keep `/**`;
86
+ - Go and reST get a blank line after the block (in Go a comment touching `package` becomes the
87
+ package doc; reST ends a comment only at a blank line);
88
+ - a PHP file gets a block only below `<?php`; one that starts as HTML is left alone.
89
+ - **Stamp never hides a block.** A file with an `@atlas` comment atlas can't read (a block a
90
+ formatter collapsed onto one line) gets no second block; `stamp` lists it, and any file it
91
+ can't place a block in, for a hand fix. A one-line opener (`<!-- @atlas -->`, `/** @atlas */`)
92
+ is filled in place.
93
+ - **No comment syntax** (`.json`, `.txt`, `.csv`, images): the file is never edited. The stamp
94
+ rules that match its path are its tags (`@kind`/`@partOf`; such a file has no `@uses`), and it
95
+ appears in the graph and the hooks like any other. `coverage` counts these files as "tagged by
96
+ path".
97
+ - **Which files.** With `include` unset, atlas considers every file in a known comment style
98
+ plus every file a stamp rule tags by path. Files come from git (tracked, plus untracked files not
99
+ in `.gitignore`), so generated output and nested worktrees stay out. Outside a git work tree
100
+ every file is listed, and so is a root the enclosing repo ignores; any other git failure is an
101
+ error. Dot-directories are walked (`.github/`, `.claude/`); `.git`, `.atlas` (at any depth),
102
+ `node_modules` and `dist` never are, and neither are submodules, symlinks, atlas's own outputs
103
+ (`MAP.md` at the root; `COVERAGE.md` and `atlas.html` at any depth, wherever `report --out`
104
+ put them) or `pnpm-lock.yaml`. A file named like source but
105
+ holding binary (NUL bytes and not valid UTF-8), or stored as UTF-32 or as UTF-16 without a
106
+ byte-order mark, is skipped. A UTF-16 file with a byte-order mark is read,
107
+ and stamping writes a file back in its own encoding (UTF-8, UTF-8 with a byte-order mark,
108
+ UTF-16). A file whose bytes aren't valid in its encoding (a Windows-1252 `.ps1`) is read for
109
+ `check` and `graph`, but `stamp` leaves it alone and lists it under `skipped`: writing it back
110
+ would corrupt those bytes.
111
+ - **Limits.** atlas reads comments, not the language around them, so an `@atlas` block inside a
112
+ string (a Python string, a shell heredoc, a JS template literal) reads as the file's block, and
113
+ `stamp` (`--overwrite` included) rewrites it, which changes that string. Matching ignores case.
114
+
115
+ atlas maps files, not the functions inside them, in every language.
37
116
 
38
117
  ## Configure
39
118
 
@@ -81,28 +160,40 @@ A complete, commented set you can copy into your repo's `.atlas/` is in
81
160
  ## CLI
82
161
 
83
162
  ```bash
84
- atlas graph # reverse indexes: concept → files, file → concepts, doc → concepts
85
- atlas check # presence + vocab + reference + thesaurus existence (the CI command)
86
- atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
87
- atlas generate # write MAP.md from the annotated tree
88
- atlas report # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)
89
- atlas stamp [dir] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)
90
- atlas hook read # Claude Code PostToolUse hook: the concept neighbourhood of the file just read
91
- atlas hook grep # Claude Code PostToolUse hook: the concepts a grep pattern names
92
- atlas setup # offer to add both hooks to .claude/settings.json (--yes: no prompt)
163
+ atlas init # start a .atlas/: include list for the languages found, kinds, empty concepts
164
+ atlas graph # reverse indexes: concept → files, file → concepts, doc → concepts
165
+ atlas check [paths…] # presence + vocab + reference + thesaurus existence (the CI command)
166
+ atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
167
+ atlas generate # write MAP.md from the annotated tree
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
170
+ atlas stamp [paths…] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)
171
+ atlas hook read # Claude Code PostToolUse hook: the concept neighbourhood of the file just read
172
+ atlas hook grep # Claude Code PostToolUse hook: the concepts a grep pattern names
173
+ atlas setup # offer to add both hooks to .claude/settings.json (--yes: no prompt)
93
174
  ```
94
175
 
95
176
  Common flags: `--root <dir>`, `--json`, `generate --stdout`, `stamp --write`, `stamp --overwrite`,
96
- `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
+ ```
97
188
 
98
189
  ## For AI agents
99
190
 
100
191
  atlas exists largely so agents stop grab-bagging files and answering from stale labels. Drop this
101
- 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**
102
193
  instead of crawling folders:
103
194
 
104
195
  > This repo is mapped by **atlas**. To find code by concept instead of by filename: read `MAP.md`
105
- > for the concept overview; run `bunx atlas graph --json` for the reverse indexes (concept → files via
196
+ > for the concept overview; run `bunx @inixiative/atlas graph --json` for the reverse indexes (concept → files via
106
197
  > `@partOf`, concept → consumers via `@uses`); and read a file's top-of-file `@atlas` block
107
198
  > (`@kind` / `@partOf` / `@uses`) before its body. Prefer these over `grep` for "what touches X" /
108
199
  > "what's part of Y" questions.
@@ -113,7 +204,7 @@ before opening it. In an A/B test on a repo with a transitive dependency, agents
113
204
  used `atlas graph` and solved a "what reaches redis (directly or transitively)" question in ~2 tool
114
205
  calls; agents left to `grep` took 2–3× as many and risk missing the transitive edge entirely.
115
206
 
116
- ### Hooks: the neighbourhood on every Read and Grep
207
+ ## Hooks: the neighbourhood on every Read and Grep
117
208
 
118
209
  The map only helps if the agent looks at it. `atlas hook read` and `atlas hook grep` put it in
119
210
  front of the agent without asking: when it reads a file, it sees which concepts the file is part
@@ -126,11 +217,11 @@ atlas neighbourhood of src/test/factories/userFactory.ts:
126
217
 
127
218
  factory, 1 of 2 factories in primitive:testFactories
128
219
 
129
- primitive:testFactories — 2 other file(s), 1 consumer(s) via @uses; `bunx atlas query --partOf primitive:testFactories` lists all
220
+ primitive:testFactories — 2 other file(s), 1 consumer(s) via @uses; `bunx @inixiative/atlas query --partOf primitive:testFactories` lists all
130
221
  src/test/factories/buildFactory.ts
131
222
  src/test/factories/organizationFactory.ts
132
223
 
133
- @uses feature:users — load-bearing dependencies; `bunx atlas query --partOf <concept>` shows what implements each
224
+ @uses feature:users — load-bearing dependencies; `bunx @inixiative/atlas query --partOf <concept>` shows what implements each
134
225
  ```
135
226
 
136
227
  A file of `@kind factory` or `@kind constructor` also gets a line counting that kind in its
@@ -140,7 +231,10 @@ concepts' files are listed.
140
231
 
141
232
  Install them with `atlas setup` (asks first; `atlas setup --yes` for scripts and agents). It
142
233
  merges two `PostToolUse` entries into `.claude/settings.json`, leaves every other key and hook as it
143
- was, and adds nothing on a second run:
234
+ was, and adds nothing on a second run. A repo whose `package.json` depends on
235
+ `@inixiative/atlas` runs its own install, as below. Any other repo gets
236
+ `cd "$CLAUDE_PROJECT_DIR" && bunx @inixiative/atlas@<version> hook read || true`,
237
+ pinned to the atlas that wrote it.
144
238
 
145
239
  ```json
146
240
  {
@@ -187,7 +281,7 @@ How they behave:
187
281
  adapter (stdin JSON in, `hookSpecificOutput.additionalContext` out). Another harness needs only
188
282
  its own adapter.
189
283
 
190
- ### Thesaurus
284
+ ## Thesaurus
191
285
 
192
286
  A grep for the job ("seed a user", "lock", "factory") names no concept, so the grep hook used to
193
287
  say nothing at exactly the moment an agent was looking for something that already exists. The
@@ -241,7 +335,7 @@ listed. Then come the concept-name matches not already shown:
241
335
  ```
242
336
  atlas concept(s) matching "seeding.*users?":
243
337
 
244
- primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) via @uses; `bunx atlas query --partOf primitive:testFactories` lists all
338
+ primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) via @uses; `bunx @inixiative/atlas query --partOf primitive:testFactories` lists all
245
339
  read: docs/claude/TESTING.md#factories
246
340
  src/test/factories/buildFactory.ts
247
341
  src/test/factories/organizationFactory.ts
@@ -250,7 +344,7 @@ primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) v
250
344
 
251
345
  `atlas check` flags an entry for a concept the registry doesn't have, an empty phrase list, an empty
252
346
  phrase (one with no letter or digit), and a `doc` whose file doesn't resolve to a real file; a
253
- scoped `atlas check <target>` skips the doc check like the other reference checks. `loadConfig`
347
+ scoped `atlas check <paths…>` skips the doc check like the other reference checks. `loadConfig`
254
348
  refuses an entry with any key besides `phrases` and `doc`, so a `docs:` typo can't silently fall
255
349
  back to the default doc. Whether a phrase is apt is the curator's call.
256
350
 
@@ -262,13 +356,13 @@ case's expected answer: a thesaurus tuned to its tests only teaches the tests.
262
356
 
263
357
  `atlas report` emits two artifacts:
264
358
 
265
- - **`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
266
360
  gap table (required `@kind`/`@partOf` gaps split from the `@uses` curation buckets), and a Mermaid
267
- concept-dependency graph. Categories group by **effective concept** — a file's declared `@partOf`, or the
268
- rules' *predicted* concept when unannotated — so you get a per-concept work plan even at 0% coverage.
269
- - **`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/)):
270
364
  concepts grouped by class (compound nodes), coloured by coverage; click a concept to drill into its file
271
- 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.
272
366
 
273
367
  ## The annotation model
274
368
 
@@ -276,7 +370,7 @@ case's expected answer: a thesaurus tuned to its tests only teaches the tests.
276
370
  |----------|-----|-------|-------|
277
371
  | What is this? | `@kind` | closed enum | 1+, e.g. `entrypoint, route` (a role, not a layer) |
278
372
  | What is it part of? | `@partOf` | `class:name` concept(s) | membership; multi is normal |
279
- | 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 |
280
374
  | What does it build? | `@constructs` | factory output | constructors only |
281
375
 
282
376
  All axes are multi-valued (comma-separated on one line). `@atlas` opens the block.
@@ -295,35 +389,36 @@ A top-of-file JSDoc block, above the imports (below a shebang if present):
295
389
  ```
296
390
 
297
391
  Rules of thumb:
298
- - **`@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`).
299
- - **`@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`.
300
- - **`@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).
301
- - **Validate names against the repo's `.atlas/`** — `@kind` ∈ `kinds.ts`; `@partOf`/`@uses` must name a concept that exists in `concepts.ts`.
302
- - **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.
303
397
 
304
398
  ### `@uses` is never auto-stamped
305
399
 
306
400
  Absence is meaningful, so atlas leaves `@uses` out of stamping entirely:
307
401
 
308
402
  - **no `@uses` line** = *uncurated* (nobody filled it in)
309
- - **`@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)
310
404
  - **`@uses? x`** = *proposed* (a patcher suggestion awaiting acceptance)
311
405
 
312
406
  `coverage` reports these as distinct buckets.
313
407
 
314
408
  ## The patcher: `atlas stamp`
315
409
 
316
- 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
317
411
  `--write` to apply.
318
412
 
319
- - **Targeting** — `all` (default), a folder, or a single file.
320
- - **Additive (default)** — fill only what's absent; never modify an existing tag; never touch `@uses`.
321
- - **Overwrite (`--overwrite`)** — resync the derivable axes (`@kind`/`@partOf`) to the current
413
+ - **Targeting:** the whole repo by default, or any number of files and folders (`src/`, `./src`, `.`),
414
+ each resolved against the repo root; a target that doesn't exist or lies outside it is an error.
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
322
417
  rules; **never** overwrites curated `@uses`. A `@atlas pin` block is exempt.
323
418
 
324
419
  ## CI
325
420
 
326
- `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
327
422
  running it in a workflow (no separate package needed). Copy-paste examples live in
328
423
  [`examples/ci/`](./examples/ci/): a full-repo GitHub Actions workflow with a `MAP.md` freshness
329
424
  gate, an incremental PR variant, and a pre-commit hook. The recommended rollout on an existing
@@ -331,11 +426,11 @@ codebase is **warn-only → incremental enforcing → fully enforcing**:
331
426
 
332
427
  ```bash
333
428
  atlas check --warn-only # prints problems, never fails CI (rollout start)
334
- atlas check <path> # enforce only changed paths (skips registry-wide reference checks)
429
+ atlas check <paths…> # enforce only the files a PR changes (skips registry-wide reference checks)
335
430
  atlas check # enforce the whole repo
336
431
  ```
337
432
 
338
- 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
339
434
  (ideal for a repo starting near 0%):
340
435
 
341
436
  ```bash
@@ -346,10 +441,10 @@ atlas coverage --update-baseline # record the current count (commit the baseline
346
441
 
347
442
  ## Enforcement: existence, NOT correctness
348
443
 
349
- `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
350
445
  `@kind` is in the vocab, that `@partOf`/`@uses` name a concept that exists, and that a
351
446
  concept's doc references resolve. It explicitly does **not** reconcile the import graph, judge
352
- 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
353
448
  clear structural guarantee for a fragile proxy.
354
449
 
355
450
  ## License
@@ -1,7 +1,8 @@
1
1
  # Example `.atlas/` config
2
2
 
3
3
  Copy these files into a **`.atlas/`** folder at your repo root, then adjust them to your
4
- layout. This is the entire configuration surface — atlas ships the `@kind` defaults; **your repo
4
+ layout. `bunx @inixiative/atlas init` writes a starter from them: `config.ts` with an include list
5
+ for the languages your repo has, this `kinds.ts`, and `concepts.ts` with no concepts yet. This is the entire configuration surface — atlas ships the `@kind` defaults; **your repo
5
6
  owns the concept registry.**
6
7
 
7
8
  ```
@@ -24,5 +25,5 @@ concept that exists, that a `@kind` is in your vocab, and that referenced docs r
24
25
  | [`kinds.ts`](./kinds.ts) | rarely | only when a role the defaults don't cover shows up |
25
26
  | [`thesaurus.ts`](./thesaurus.ts) | when a search misses | add the words you searched with to the concept you found |
26
27
 
27
- After copying, `bunx atlas stamp --write` fills `@kind`/`@partOf` from the rules, `bunx atlas check`
28
- gates it, and `bunx atlas generate` writes `MAP.md`.
28
+ After copying, `bunx @inixiative/atlas stamp --write` fills `@kind`/`@partOf` from the rules, `bunx @inixiative/atlas check`
29
+ gates it, and `bunx @inixiative/atlas generate` writes `MAP.md`.
@@ -1,8 +1,12 @@
1
1
  import { defineConfig, partOfFor } from '@inixiative/atlas/config';
2
2
 
3
3
  export default defineConfig({
4
- // Files atlas considers (everything else is invisible to it).
5
- include: ['apps/**/*.ts', 'apps/**/*.tsx', 'packages/**/*.ts'],
4
+ // Files atlas considers (everything else is invisible to it). Leave it unset to consider every
5
+ // file in a comment style atlas knows, plus every file a stamp rule tags by its path.
6
+ include: ['apps/**/*.ts', 'apps/**/*.tsx', 'packages/**/*.ts', 'apps/*/package.json'],
7
+
8
+ // More files per comment style, by `.ext` or exact name (atlas's table covers the common ones).
9
+ comments: { hash: ['Tiltfile'] },
6
10
 
7
11
  // Files exempt from the presence check and from stamping (barrels, tests, generated).
8
12
  ignore: [
@@ -53,6 +57,10 @@ export default defineConfig({
53
57
  { include: 'apps/api/src/modules/$1/**', partOf: partOfFor('module', '$1') },
54
58
  { include: 'apps/api/src/integrations/$1/**', partOf: partOfFor('integration', '$1') },
55
59
  { include: 'packages/$1/**', partOf: partOfFor('package', '$1') },
60
+
61
+ // A file with no comment syntax (.json, .txt, images) is never edited: the rules that match
62
+ // its path are its tags. Add its glob to `include` (or leave `include` unset).
63
+ { include: 'apps/*/package.json', kind: 'config' },
56
64
  ],
57
65
 
58
66
  // Resolve a reference field's value to a repo-relative path so `atlas check`
@@ -7,16 +7,16 @@ on any problem). These are copy-paste examples for wiring it in. Pick the ones y
7
7
  |------|--------------|
8
8
  | [`github-actions.yml`](./github-actions.yml) | Full-repo check + coverage ratchet + `MAP.md` freshness gate (push/PR) |
9
9
  | [`github-actions-incremental.yml`](./github-actions-incremental.yml) | Check only the paths changed in a PR |
10
- | [`pre-commit`](./pre-commit) | Local git hook: check staged source dirs before commit |
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:
16
16
 
17
17
  1. **Warn-only** — `atlas check --warn-only` prints problems but always exits 0. Wire it into CI so
18
18
  the signal is visible without blocking merges while you back-fill annotations.
19
- 2. **Incremental enforcing** — gate only the paths a PR touches with `atlas check <path>` (skips the
19
+ 2. **Incremental enforcing** — gate only the files a PR touches with `atlas check <paths…>` (skips the
20
20
  registry-wide reference check, so it's about the changed files only). New code must be annotated;
21
21
  legacy code is grandfathered.
22
22
  3. **Fully enforcing** — once coverage is high, drop to plain `atlas check` on the whole repo.
@@ -1,5 +1,5 @@
1
1
  # Example — copy to .github/workflows/atlas-incremental.yml in your repo.
2
- # Enforce annotations only on the paths a PR changes (Phase 2 of the rollout):
2
+ # Enforce annotations only on the files a PR changes (Phase 2 of the rollout):
3
3
  # new/edited code must be annotated; legacy code is grandfathered.
4
4
  name: atlas (incremental)
5
5
 
@@ -17,16 +17,18 @@ jobs:
17
17
  with:
18
18
  bun-version: latest
19
19
 
20
- - run: bun install --frozen-lockfile
20
+ # A JS/TS repo installs its pinned atlas; any other repo runs it through bunx as-is.
21
+ - run: if [ -f package.json ]; then bun install --frozen-lockfile; fi
21
22
 
22
- - name: atlas check (changed paths)
23
+ - name: atlas check (changed files)
24
+ # The files the PR adds or changes; a file atlas doesn't consider is ignored. NUL-separated
25
+ # and unquoted so spaces and non-ASCII names survive. The list goes through a file and the
26
+ # shell fails on any error, so a failed diff fails the step instead of checking nothing.
27
+ # (A very long list is split by xargs into several atlas runs; any failing run fails it.)
28
+ shell: bash
23
29
  run: |
24
- git fetch origin "${{ github.base_ref }}" --depth=1
25
- changed=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" \
26
- | grep -E '\.(ts|tsx)$' | xargs -r -n1 dirname | sort -u)
27
- [ -z "$changed" ] && { echo "no source changes"; exit 0; }
28
- status=0
29
- for dir in $changed; do
30
- bunx atlas check "$dir" || status=1
31
- done
32
- exit $status
30
+ set -euo pipefail
31
+ git fetch origin "${{ github.base_ref }}"
32
+ git -c core.quotePath=false diff --name-only -z --diff-filter=ACMR \
33
+ "origin/${{ github.base_ref }}...HEAD" > "$RUNNER_TEMP/changed"
34
+ xargs -0 -r bunx @inixiative/atlas check < "$RUNNER_TEMP/changed"
@@ -17,27 +17,28 @@ jobs:
17
17
  with:
18
18
  bun-version: latest
19
19
 
20
- - run: bun install --frozen-lockfile
20
+ # A JS/TS repo installs its pinned atlas; any other repo runs it through bunx as-is.
21
+ - run: if [ -f package.json ]; then bun install --frozen-lockfile; fi
21
22
 
22
23
  # ── Annotation check ────────────────────────────────────────────────
23
- # Rollout (DEV-003 Phase 4) — start warn-only, flip to enforcing later:
24
- # warn-only: bunx atlas check --warn-only # prints, never fails CI
25
- # enforcing: bunx atlas check # fails CI on any problem
24
+ # Rollout — start warn-only, flip to enforcing later:
25
+ # warn-only: bunx @inixiative/atlas check --warn-only # prints, never fails CI
26
+ # enforcing: bunx @inixiative/atlas check # fails CI on any problem
26
27
  - name: atlas check
27
- run: bunx atlas check
28
+ run: bunx @inixiative/atlas check
28
29
 
29
30
  # ── Coverage gate ───────────────────────────────────────────────────
30
31
  # Ratchet: the unannotated count may not exceed the committed baseline
31
32
  # (.atlas/coverage-baseline.json), so coverage can only hold or improve.
32
33
  # Bump the baseline as you back-fill: atlas coverage --update-baseline
33
34
  - name: atlas coverage (ratchet)
34
- run: bunx atlas coverage --ratchet
35
+ run: bunx @inixiative/atlas coverage --ratchet
35
36
  # Or, once coverage is high, swap the ratchet for a percentage floor:
36
- # run: bunx atlas coverage --min 80
37
+ # run: bunx @inixiative/atlas coverage --min 80
37
38
 
38
39
  # ── MAP.md freshness ────────────────────────────────────────────────
39
40
  # The committed map must match the annotated tree, or the PR is stale.
40
41
  - name: MAP.md is current
41
42
  run: |
42
- bunx atlas generate
43
+ bunx @inixiative/atlas generate
43
44
  git diff --exit-code MAP.md
@@ -1,19 +1,21 @@
1
1
  #!/usr/bin/env sh
2
2
  # Example local hook — copy to .husky/pre-commit (or .git/hooks/pre-commit; chmod +x).
3
- # Checks the source directories you're about to commit (presence + vocab).
4
- # Scoped per-path, so it's fast and skips the registry-wide reference check.
3
+ # Checks the files you're about to commit (presence + vocab); a staged file atlas doesn't
4
+ # consider is ignored. Scoped runs skip the registry-wide reference check. It reads the working
5
+ # tree, not the staged blobs, so stage what you check.
6
+ # NUL-separated and unquoted (core.quotePath=false) so spaces and non-ASCII names survive. The
7
+ # list goes through a file, not a pipe, so a git failure fails the hook instead of checking
8
+ # nothing. A very long list is split by xargs into several atlas runs; any failing run fails it.
5
9
 
6
- staged=$(git diff --cached --name-only --diff-filter=ACM \
7
- | grep -E '\.(ts|tsx)$' | xargs -r -n1 dirname | sort -u)
8
-
9
- [ -z "$staged" ] && exit 0
10
-
11
- status=0
12
- for dir in $staged; do
13
- bunx atlas check "$dir" || status=1
14
- done
10
+ set -e
11
+ files=$(mktemp)
12
+ trap 'rm -f "$files"' EXIT
13
+ git -c core.quotePath=false diff --cached --name-only -z --diff-filter=ACMR > "$files"
14
+ set +e
15
+ xargs -0 -r bunx @inixiative/atlas check < "$files"
16
+ status=$?
15
17
 
16
18
  if [ "$status" -ne 0 ]; then
17
- echo "atlas: fix the annotations above, or run 'bunx atlas stamp <dir> --write' to fill them."
19
+ echo "atlas: fix the annotations above, or run 'bunx @inixiative/atlas stamp <file> --write' to fill them."
18
20
  fi
19
21
  exit "$status"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@inixiative/atlas",
3
- "version": "0.4.1",
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.115",
57
- "@types/bun": "1.4.2",
56
+ "@inixiative/config": "^0.5.227",
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.5.4"
62
+ "@inixiative/json-rules": "^4.2.0"
63
63
  },
64
- "packageManager": "bun@1.4.2"
64
+ "packageManager": "bun@1.4.4"
65
65
  }