@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 +141 -46
- package/examples/atlas-config/README.md +4 -3
- package/examples/atlas-config/config.ts +10 -2
- package/examples/ci/README.md +3 -3
- package/examples/ci/github-actions-incremental.yml +14 -12
- package/examples/ci/github-actions.yml +9 -8
- package/examples/ci/pre-commit +14 -12
- package/package.json +6 -6
- package/src/analyze.ts +120 -7
- package/src/cli.ts +72 -17
- package/src/commands/check.ts +10 -2
- package/src/commands/coverage.ts +8 -1
- package/src/commands/init.ts +78 -0
- package/src/commands/report.ts +0 -0
- package/src/commands/setup.ts +66 -22
- package/src/commands/stamp.ts +99 -31
- package/src/config/defineConfig.ts +10 -2
- package/src/config/load.ts +58 -2
- package/src/fs/walk.ts +90 -17
- package/src/hook/cachedGraph.ts +4 -1
- package/src/hook/claudeCode.ts +1 -1
- package/src/hook/neighbourhood.ts +3 -3
- package/src/index.ts +21 -1
- package/src/parse/parseAtlasBlock.ts +102 -20
- package/src/stamp/patcher.ts +46 -31
- package/src/syntax/comments.ts +260 -0
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
|
|
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**
|
|
24
|
-
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.
|
|
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
|
|
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
|
|
85
|
-
atlas
|
|
86
|
-
atlas
|
|
87
|
-
atlas
|
|
88
|
-
atlas
|
|
89
|
-
atlas
|
|
90
|
-
atlas
|
|
91
|
-
atlas
|
|
92
|
-
atlas
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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 <
|
|
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
|
|
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**
|
|
268
|
-
rules' *predicted* concept when unannotated
|
|
269
|
-
- **`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/)):
|
|
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
|
|
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) |
|
|
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
|
|
299
|
-
- **`@partOf` is membership
|
|
300
|
-
- **`@uses` is dependency
|
|
301
|
-
- **Validate names against the repo's `.atlas
|
|
302
|
-
- **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.
|
|
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
|
|
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
|
|
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
|
|
320
|
-
|
|
321
|
-
- **
|
|
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
|
|
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 <
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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`
|
package/examples/ci/README.md
CHANGED
|
@@ -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
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
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
|
|
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
|
package/examples/ci/pre-commit
CHANGED
|
@@ -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
|
|
4
|
-
#
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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 <
|
|
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
|
-
"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.
|
|
57
|
-
"@types/bun": "1.4.
|
|
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": "^
|
|
62
|
+
"@inixiative/json-rules": "^4.2.0"
|
|
63
63
|
},
|
|
64
|
-
"packageManager": "bun@1.4.
|
|
64
|
+
"packageManager": "bun@1.4.4"
|
|
65
65
|
}
|