@inixiative/atlas 0.4.0 → 0.5.0
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 +102 -20
- package/examples/atlas-config/README.md +4 -3
- package/examples/atlas-config/config.ts +10 -2
- package/examples/ci/README.md +2 -2
- package/examples/ci/github-actions-incremental.yml +14 -12
- package/examples/ci/github-actions.yml +8 -7
- package/examples/ci/pre-commit +14 -12
- package/package.json +5 -5
- 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/generate.ts +4 -4
- 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
|
@@ -6,7 +6,8 @@ on the structural facts* — because atlas only ever asserts what is mechanicall
|
|
|
6
6
|
how it connects), never maturity or correctness.
|
|
7
7
|
|
|
8
8
|
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
|
|
9
|
+
repo defines its own vocabulary**, in any language: the block is written in the file's own comment
|
|
10
|
+
syntax, and a file that can't hold a comment is tagged by its path.
|
|
10
11
|
|
|
11
12
|
```ts
|
|
12
13
|
/**
|
|
@@ -17,6 +18,12 @@ repo defines its own vocabulary.**
|
|
|
17
18
|
*/
|
|
18
19
|
```
|
|
19
20
|
|
|
21
|
+
```py
|
|
22
|
+
# @atlas
|
|
23
|
+
# @kind service
|
|
24
|
+
# @partOf feature:signing
|
|
25
|
+
```
|
|
26
|
+
|
|
20
27
|
## Why
|
|
21
28
|
|
|
22
29
|
Hand-maintained maps (FEATURES.md, docs, prose) drift from the code. atlas makes the map a
|
|
@@ -30,10 +37,80 @@ hyper-specific label. Keep the vocabulary broad but closed; apply it liberally.
|
|
|
30
37
|
## Install
|
|
31
38
|
|
|
32
39
|
```bash
|
|
33
|
-
bun add -d @inixiative/atlas
|
|
40
|
+
bun add -d @inixiative/atlas # a JavaScript/TypeScript repo
|
|
41
|
+
bunx @inixiative/atlas init # any repo: no package.json or node_modules needed
|
|
34
42
|
```
|
|
35
43
|
|
|
36
|
-
atlas
|
|
44
|
+
atlas runs on Bun (it imports your `.atlas/*.ts` config directly). The config's own
|
|
45
|
+
`@inixiative/atlas` imports (in any file under `.atlas/`) are bound to the atlas that is running,
|
|
46
|
+
so a Python, Go or docs repo needs nothing installed besides Bun.
|
|
47
|
+
|
|
48
|
+
**A repo you don't trust.** Running atlas runs that repo's code: it imports `.atlas/**/*.ts`, and
|
|
49
|
+
Bun applies the `bunfig.toml` of the directory you run it from (a `preload` there runs first).
|
|
50
|
+
Read `.atlas/` before running atlas on such a repo, run it from a neutral directory with
|
|
51
|
+
`--root <repo>`, or use a sandbox. atlas itself can't block a preload; Bun runs it before atlas
|
|
52
|
+
starts.
|
|
53
|
+
|
|
54
|
+
## Any language
|
|
55
|
+
|
|
56
|
+
atlas reads one table of comment styles, grouped by how a language writes a comment, and
|
|
57
|
+
`check`, `stamp`, `graph` and the hooks all use it:
|
|
58
|
+
|
|
59
|
+
| Style | Block | Files |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `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` |
|
|
62
|
+
| `html` | `<!-- … -->` | `.md` `.markdown` `.html` `.htm` `.xml` `.vue` `.svelte` |
|
|
63
|
+
| `mdx` | `{/* … */}` | `.mdx` |
|
|
64
|
+
| `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` |
|
|
65
|
+
| `slash` | `// ` lines | `.zig` |
|
|
66
|
+
| `dash` | `-- ` lines | `.sql` `.lua` `.hs` `.elm` |
|
|
67
|
+
| `semicolon` | `;; ` lines | `.clj` `.cljs` `.cljc` `.edn` `.lisp` `.el` `.scm` `.rkt` |
|
|
68
|
+
| `dotdot` | `.. ` lines | `.rst` |
|
|
69
|
+
|
|
70
|
+
Add files to a style in `.atlas/config.ts`: `comments: { hash: ['.nix', 'Tiltfile'] }` (`.ext` or
|
|
71
|
+
an exact file name; listing one under another style moves it there).
|
|
72
|
+
|
|
73
|
+
- **Line styles** (`#`, `//`, `--`, `;;`, `..`): the block is the `@atlas` line plus the
|
|
74
|
+
`@kind`/`@partOf`/`@uses`/`@constructs` lines right after it (repeated prefixes like `;;` and
|
|
75
|
+
`##` read as one; an empty comment line between them is bridged). Any other line ends it, so a
|
|
76
|
+
prose comment or a doc tag next to the block (LuaLS `---@class`, YARD `# @deprecated`) is never
|
|
77
|
+
part of it and never rewritten.
|
|
78
|
+
- **Placement.** A fresh block goes at the top, below what must stay first: a shebang (not Rust's
|
|
79
|
+
`#![…]`), an Emacs `-*- … -*-` line, Python's or Ruby's encoding line, Go build constraints,
|
|
80
|
+
Dockerfile parser directives, Markdown front matter, an XML prolog, `<?php`, CSS `@charset`. Language rules on
|
|
81
|
+
top of the style:
|
|
82
|
+
- the C family writes plain `/* */`, because `/**` is a doc comment in Rust (an error before
|
|
83
|
+
`//!`), C#, Dart, Java and Go; JS/TS keep `/**`;
|
|
84
|
+
- Go and reST get a blank line after the block (in Go a comment touching `package` becomes the
|
|
85
|
+
package doc; reST ends a comment only at a blank line);
|
|
86
|
+
- a PHP file gets a block only below `<?php`; one that starts as HTML is left alone.
|
|
87
|
+
- **Stamp never hides a block.** A file with an `@atlas` comment atlas can't read (a block a
|
|
88
|
+
formatter collapsed onto one line) gets no second block; `stamp` lists it, and any file it
|
|
89
|
+
can't place a block in, for a hand fix. A one-line opener (`<!-- @atlas -->`, `/** @atlas */`)
|
|
90
|
+
is filled in place.
|
|
91
|
+
- **No comment syntax** (`.json`, `.txt`, `.csv`, images): the file is never edited. The stamp
|
|
92
|
+
rules that match its path are its tags (`@kind`/`@partOf`; such a file has no `@uses`), and it
|
|
93
|
+
appears in the graph and the hooks like any other. `coverage` counts these files as "tagged by
|
|
94
|
+
path".
|
|
95
|
+
- **Which files.** With `include` unset, atlas considers every file in a known comment style
|
|
96
|
+
plus every file a stamp rule tags by path. Files come from git (tracked, plus untracked files not
|
|
97
|
+
in `.gitignore`), so generated output and nested worktrees stay out. Outside a git work tree
|
|
98
|
+
every file is listed, and so is a root the enclosing repo ignores; any other git failure is an
|
|
99
|
+
error. Dot-directories are walked (`.github/`, `.claude/`); `.git`, `.atlas` (at any depth),
|
|
100
|
+
`node_modules` and `dist` never are, and neither are submodules, symlinks, atlas's own outputs
|
|
101
|
+
(`MAP.md` at the root; `COVERAGE.md` and `atlas.html` at any depth, wherever `report --out`
|
|
102
|
+
put them) or `pnpm-lock.yaml`. A file named like source but
|
|
103
|
+
holding binary (NUL bytes and not valid UTF-8), or stored as UTF-32 or as UTF-16 without a
|
|
104
|
+
byte-order mark, is skipped. A UTF-16 file with a byte-order mark is read,
|
|
105
|
+
and stamping writes a file back in its own encoding (UTF-8, UTF-8 with a byte-order mark,
|
|
106
|
+
UTF-16). A file whose bytes aren't valid in its encoding (a Windows-1252 `.ps1`) is read for
|
|
107
|
+
`check` and `graph`, but `stamp` leaves it alone and lists it under `skipped`: writing it back
|
|
108
|
+
would corrupt those bytes.
|
|
109
|
+
- **Limits.** atlas reads comments, not the language around them, so an `@atlas` block inside a
|
|
110
|
+
string (a Python string, a shell heredoc, a JS template literal) reads as the file's block, and
|
|
111
|
+
`stamp` (`--overwrite` included) rewrites it, which changes that string. Matching ignores case.
|
|
112
|
+
|
|
113
|
+
atlas maps files, not the functions inside them, in every language.
|
|
37
114
|
|
|
38
115
|
## Configure
|
|
39
116
|
|
|
@@ -81,15 +158,16 @@ A complete, commented set you can copy into your repo's `.atlas/` is in
|
|
|
81
158
|
## CLI
|
|
82
159
|
|
|
83
160
|
```bash
|
|
84
|
-
atlas
|
|
85
|
-
atlas
|
|
86
|
-
atlas
|
|
87
|
-
atlas
|
|
88
|
-
atlas
|
|
89
|
-
atlas
|
|
90
|
-
atlas
|
|
91
|
-
atlas hook
|
|
92
|
-
atlas
|
|
161
|
+
atlas init # start a .atlas/: include list for the languages found, kinds, empty concepts
|
|
162
|
+
atlas graph # reverse indexes: concept → files, file → concepts, doc → concepts
|
|
163
|
+
atlas check [paths…] # presence + vocab + reference + thesaurus existence (the CI command)
|
|
164
|
+
atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
|
|
165
|
+
atlas generate # write MAP.md from the annotated tree
|
|
166
|
+
atlas report # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)
|
|
167
|
+
atlas stamp [paths…] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)
|
|
168
|
+
atlas hook read # Claude Code PostToolUse hook: the concept neighbourhood of the file just read
|
|
169
|
+
atlas hook grep # Claude Code PostToolUse hook: the concepts a grep pattern names
|
|
170
|
+
atlas setup # offer to add both hooks to .claude/settings.json (--yes: no prompt)
|
|
93
171
|
```
|
|
94
172
|
|
|
95
173
|
Common flags: `--root <dir>`, `--json`, `generate --stdout`, `stamp --write`, `stamp --overwrite`,
|
|
@@ -102,7 +180,7 @@ line into your agent's system prompt / `CLAUDE.md` / `AGENTS.md` so it navigates
|
|
|
102
180
|
instead of crawling folders:
|
|
103
181
|
|
|
104
182
|
> 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
|
|
183
|
+
> for the concept overview; run `bunx @inixiative/atlas graph --json` for the reverse indexes (concept → files via
|
|
106
184
|
> `@partOf`, concept → consumers via `@uses`); and read a file's top-of-file `@atlas` block
|
|
107
185
|
> (`@kind` / `@partOf` / `@uses`) before its body. Prefer these over `grep` for "what touches X" /
|
|
108
186
|
> "what's part of Y" questions.
|
|
@@ -126,11 +204,11 @@ atlas neighbourhood of src/test/factories/userFactory.ts:
|
|
|
126
204
|
|
|
127
205
|
factory, 1 of 2 factories in primitive:testFactories
|
|
128
206
|
|
|
129
|
-
primitive:testFactories — 2 other file(s), 1 consumer(s) via @uses; `bunx atlas query --partOf primitive:testFactories` lists all
|
|
207
|
+
primitive:testFactories — 2 other file(s), 1 consumer(s) via @uses; `bunx @inixiative/atlas query --partOf primitive:testFactories` lists all
|
|
130
208
|
src/test/factories/buildFactory.ts
|
|
131
209
|
src/test/factories/organizationFactory.ts
|
|
132
210
|
|
|
133
|
-
@uses feature:users — load-bearing dependencies; `bunx atlas query --partOf <concept>` shows what implements each
|
|
211
|
+
@uses feature:users — load-bearing dependencies; `bunx @inixiative/atlas query --partOf <concept>` shows what implements each
|
|
134
212
|
```
|
|
135
213
|
|
|
136
214
|
A file of `@kind factory` or `@kind constructor` also gets a line counting that kind in its
|
|
@@ -140,7 +218,10 @@ concepts' files are listed.
|
|
|
140
218
|
|
|
141
219
|
Install them with `atlas setup` (asks first; `atlas setup --yes` for scripts and agents). It
|
|
142
220
|
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
|
|
221
|
+
was, and adds nothing on a second run. A repo whose `package.json` depends on
|
|
222
|
+
`@inixiative/atlas` runs its own install, as below. Any other repo gets
|
|
223
|
+
`cd "$CLAUDE_PROJECT_DIR" && bunx @inixiative/atlas@<version> hook read || true`,
|
|
224
|
+
pinned to the atlas that wrote it.
|
|
144
225
|
|
|
145
226
|
```json
|
|
146
227
|
{
|
|
@@ -241,7 +322,7 @@ listed. Then come the concept-name matches not already shown:
|
|
|
241
322
|
```
|
|
242
323
|
atlas concept(s) matching "seeding.*users?":
|
|
243
324
|
|
|
244
|
-
primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) via @uses; `bunx atlas query --partOf primitive:testFactories` lists all
|
|
325
|
+
primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) via @uses; `bunx @inixiative/atlas query --partOf primitive:testFactories` lists all
|
|
245
326
|
read: docs/claude/TESTING.md#factories
|
|
246
327
|
src/test/factories/buildFactory.ts
|
|
247
328
|
src/test/factories/organizationFactory.ts
|
|
@@ -250,7 +331,7 @@ primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) v
|
|
|
250
331
|
|
|
251
332
|
`atlas check` flags an entry for a concept the registry doesn't have, an empty phrase list, an empty
|
|
252
333
|
phrase (one with no letter or digit), and a `doc` whose file doesn't resolve to a real file; a
|
|
253
|
-
scoped `atlas check <
|
|
334
|
+
scoped `atlas check <paths…>` skips the doc check like the other reference checks. `loadConfig`
|
|
254
335
|
refuses an entry with any key besides `phrases` and `doc`, so a `docs:` typo can't silently fall
|
|
255
336
|
back to the default doc. Whether a phrase is apt is the curator's call.
|
|
256
337
|
|
|
@@ -316,7 +397,8 @@ Absence is meaningful, so atlas leaves `@uses` out of stamping entirely:
|
|
|
316
397
|
Blanks are fillable on demand — the `eslint --fix` shape. Always **dry-run by default**; pass
|
|
317
398
|
`--write` to apply.
|
|
318
399
|
|
|
319
|
-
- **Targeting** —
|
|
400
|
+
- **Targeting** — the whole repo by default, or any number of files and folders (`src/`, `./src`, `.`),
|
|
401
|
+
each resolved against the repo root; a target that doesn't exist or lies outside it is an error.
|
|
320
402
|
- **Additive (default)** — fill only what's absent; never modify an existing tag; never touch `@uses`.
|
|
321
403
|
- **Overwrite (`--overwrite`)** — resync the derivable axes (`@kind`/`@partOf`) to the current
|
|
322
404
|
rules; **never** overwrites curated `@uses`. A `@atlas pin` block is exempt.
|
|
@@ -331,7 +413,7 @@ codebase is **warn-only → incremental enforcing → fully enforcing**:
|
|
|
331
413
|
|
|
332
414
|
```bash
|
|
333
415
|
atlas check --warn-only # prints problems, never fails CI (rollout start)
|
|
334
|
-
atlas check <
|
|
416
|
+
atlas check <paths…> # enforce only the files a PR changes (skips registry-wide reference checks)
|
|
335
417
|
atlas check # enforce the whole repo
|
|
336
418
|
```
|
|
337
419
|
|
|
@@ -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,7 +7,7 @@ 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
12
|
## Rollout (DEV-003 Phase 4): warn-only → enforcing
|
|
13
13
|
|
|
@@ -16,7 +16,7 @@ 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
24
|
# 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
|
|
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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@inixiative/atlas",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -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.169",
|
|
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.
|
|
62
|
+
"@inixiative/json-rules": "^3.16.0"
|
|
63
63
|
},
|
|
64
|
-
"packageManager": "bun@1.4.
|
|
64
|
+
"packageManager": "bun@1.4.4"
|
|
65
65
|
}
|
package/src/analyze.ts
CHANGED
|
@@ -1,24 +1,137 @@
|
|
|
1
1
|
import { resolve } from 'node:path';
|
|
2
2
|
import type { LoadedConfig } from './config/defineConfig.ts';
|
|
3
|
+
import { matchesAny } from './config/glob.ts';
|
|
3
4
|
import { loadConfig } from './config/load.ts';
|
|
5
|
+
import { type ResolvedStamp, stampFor } from './config/stamp.ts';
|
|
4
6
|
import { mapLimit } from './fs/concurrent.ts';
|
|
5
7
|
import { walkFiles } from './fs/walk.ts';
|
|
6
8
|
import { type AtlasAnnotation, parseAtlasBlock } from './parse/parseAtlasBlock.ts';
|
|
9
|
+
import { type CommentStyle, styleFor } from './syntax/comments.ts';
|
|
7
10
|
|
|
8
|
-
|
|
11
|
+
// `inline`: the file carries its own @atlas block. `path`: the file can't hold a comment (.json,
|
|
12
|
+
// .txt, an image), so its tags are the ones the stamp rules give its path; it has no @uses.
|
|
13
|
+
export type Tagging = 'inline' | 'path';
|
|
14
|
+
export type FileRecord = { path: string; tagging: Tagging; annotation: AtlasAnnotation | null };
|
|
9
15
|
export type Analysis = { root: string; config: LoadedConfig; files: FileRecord[] };
|
|
10
16
|
|
|
17
|
+
// A file atlas considers, and the comment style it is written in (null: tagged by path, with
|
|
18
|
+
// what its rules give it).
|
|
19
|
+
export type ConsideredFile =
|
|
20
|
+
| { path: string; style: CommentStyle }
|
|
21
|
+
| { path: string; style: null; stamp: ResolvedStamp };
|
|
22
|
+
|
|
11
23
|
// Bound open file descriptors so a repo with thousands of files can't hit EMFILE.
|
|
12
24
|
const READ_CONCURRENCY = 64;
|
|
13
25
|
|
|
26
|
+
const hasTags = (s: ResolvedStamp): boolean =>
|
|
27
|
+
s.kind.length > 0 || s.partOf.length > 0 || s.constructs.length > 0;
|
|
28
|
+
|
|
29
|
+
// The files atlas considers: those `include` names, or by default every file in a comment
|
|
30
|
+
// style atlas knows plus every file a stamp rule tags by its path. A path-tagged file carries
|
|
31
|
+
// the rules' result, so it is resolved once.
|
|
32
|
+
export const consideredFiles = async (
|
|
33
|
+
root: string,
|
|
34
|
+
config: LoadedConfig,
|
|
35
|
+
): Promise<ConsideredFile[]> => {
|
|
36
|
+
const { include } = config;
|
|
37
|
+
const resolved = new Map<string, ResolvedStamp>();
|
|
38
|
+
const tagsOf = (path: string): ResolvedStamp => {
|
|
39
|
+
let stamp = resolved.get(path);
|
|
40
|
+
if (!stamp) {
|
|
41
|
+
stamp = stampFor(path, config.stamp, config.concepts);
|
|
42
|
+
resolved.set(path, stamp);
|
|
43
|
+
}
|
|
44
|
+
return stamp;
|
|
45
|
+
};
|
|
46
|
+
const keep = include
|
|
47
|
+
? (path: string) => matchesAny(include, path)
|
|
48
|
+
: (path: string) => styleFor(path, config.comments) !== null || hasTags(tagsOf(path));
|
|
49
|
+
const paths = await walkFiles(root, config.ignore, keep);
|
|
50
|
+
return paths.map((path) => {
|
|
51
|
+
const style = styleFor(path, config.comments);
|
|
52
|
+
return style ? { path, style } : { path, style, stamp: tagsOf(path) };
|
|
53
|
+
});
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
// How a file's text is stored, so the stamper writes it back the same way. Bun's decoder drops
|
|
57
|
+
// a byte-order mark, and Windows tools depend on it: PowerShell 5.1 reads a .ps1 without one as
|
|
58
|
+
// ANSI, and writes UTF-16 by default.
|
|
59
|
+
export type TextEncoding = 'utf-8' | 'utf-8-bom' | 'utf-16le' | 'utf-16be';
|
|
60
|
+
|
|
61
|
+
const BOMS: Record<Exclude<TextEncoding, 'utf-8'>, number[]> = {
|
|
62
|
+
'utf-8-bom': [0xef, 0xbb, 0xbf],
|
|
63
|
+
'utf-16le': [0xff, 0xfe],
|
|
64
|
+
'utf-16be': [0xfe, 0xff],
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
const nulCount = (bytes: Uint8Array): number => bytes.reduce((n, b) => (b === 0 ? n + 1 : n), 0);
|
|
68
|
+
|
|
69
|
+
const startsWith = (bytes: Uint8Array, prefix: number[]): boolean =>
|
|
70
|
+
prefix.every((byte, i) => bytes[i] === byte);
|
|
71
|
+
|
|
72
|
+
// A file's text and encoding, or null for a file named like source but holding binary (a `.ts`
|
|
73
|
+
// video stream: NUL bytes and not valid UTF-8) or stored as UTF-32 or as UTF-16 without a BOM. A NUL alone isn't binary:
|
|
74
|
+
// valid UTF-8 source may hold one. `exact` is false when the bytes aren't valid in their
|
|
75
|
+
// encoding (a Windows-1252 `.ps1`): the text is still read, with U+FFFD for the bad bytes, so
|
|
76
|
+
// check and graph work, but the stamper must not write it back.
|
|
77
|
+
export const readText = async (
|
|
78
|
+
root: string,
|
|
79
|
+
path: string,
|
|
80
|
+
): Promise<{ text: string; encoding: TextEncoding; exact: boolean } | null> => {
|
|
81
|
+
const bytes = await Bun.file(resolve(root, path)).bytes();
|
|
82
|
+
if (startsWith(bytes, [0xff, 0xfe, 0, 0]) || startsWith(bytes, [0, 0, 0xfe, 0xff])) return null;
|
|
83
|
+
let encoding: TextEncoding = startsWith(bytes, BOMS['utf-8-bom']) ? 'utf-8-bom' : 'utf-8';
|
|
84
|
+
for (const utf16 of ['utf-16le', 'utf-16be'] as const)
|
|
85
|
+
if (startsWith(bytes, BOMS[utf16])) encoding = utf16;
|
|
86
|
+
// UTF-16 without a byte-order mark: every other byte of ASCII-range text is NUL, which is
|
|
87
|
+
// valid UTF-8, so it would be stamped as UTF-8 and mixed. Text holds at most a stray NUL.
|
|
88
|
+
if (encoding === 'utf-8' && nulCount(bytes) * 10 > bytes.length) return null;
|
|
89
|
+
const label = encoding === 'utf-8-bom' ? 'utf-8' : encoding;
|
|
90
|
+
try {
|
|
91
|
+
return { text: new TextDecoder(label, { fatal: true }).decode(bytes), encoding, exact: true };
|
|
92
|
+
} catch {
|
|
93
|
+
if (label === 'utf-8' && bytes.includes(0)) return null;
|
|
94
|
+
return { text: new TextDecoder(label).decode(bytes), encoding, exact: false };
|
|
95
|
+
}
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
// The bytes to write for `text` in `encoding`, byte-order mark included.
|
|
99
|
+
export const encodeText = (text: string, encoding: TextEncoding): Uint8Array => {
|
|
100
|
+
if (encoding === 'utf-8') return new TextEncoder().encode(text);
|
|
101
|
+
if (encoding === 'utf-8-bom')
|
|
102
|
+
return new Uint8Array([...BOMS[encoding], ...new TextEncoder().encode(text)]);
|
|
103
|
+
const out = new Uint8Array(2 + text.length * 2);
|
|
104
|
+
out.set(BOMS[encoding]);
|
|
105
|
+
for (let i = 0; i < text.length; i++) {
|
|
106
|
+
const unit = text.charCodeAt(i);
|
|
107
|
+
const [first, second] =
|
|
108
|
+
encoding === 'utf-16le' ? [unit & 0xff, unit >> 8] : [unit >> 8, unit & 0xff];
|
|
109
|
+
out[2 + i * 2] = first;
|
|
110
|
+
out[3 + i * 2] = second;
|
|
111
|
+
}
|
|
112
|
+
return out;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
// A path-tagged file's annotation: what the rules say, or null when they say nothing.
|
|
116
|
+
const pathAnnotation = ({ kind, partOf, constructs }: ResolvedStamp): AtlasAnnotation | null => {
|
|
117
|
+
if (kind.length + partOf.length + constructs.length === 0) return null;
|
|
118
|
+
const axes: Record<string, string[]> = { kind, partOf };
|
|
119
|
+
if (constructs.length) axes.constructs = constructs;
|
|
120
|
+
return { kind, partOf, constructs, uses: [], usesState: 'absent', pinned: false, axes };
|
|
121
|
+
};
|
|
122
|
+
|
|
14
123
|
// One pass: load the consumer's .atlas/ config, walk the considered files, and
|
|
15
124
|
// parse each into its @atlas annotation (or null). Every command consumes this.
|
|
16
125
|
export const analyze = async (root: string): Promise<Analysis> => {
|
|
17
126
|
const config = await loadConfig(root);
|
|
18
|
-
const
|
|
19
|
-
const files
|
|
20
|
-
path
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
127
|
+
const considered = await consideredFiles(root, config);
|
|
128
|
+
const files = await mapLimit(considered, READ_CONCURRENCY, async (file) => {
|
|
129
|
+
const { path } = file;
|
|
130
|
+
if (file.style === null)
|
|
131
|
+
return { path, tagging: 'path' as const, annotation: pathAnnotation(file.stamp) };
|
|
132
|
+
const read = await readText(root, path);
|
|
133
|
+
if (read === null) return null;
|
|
134
|
+
return { path, tagging: 'inline' as const, annotation: parseAtlasBlock(read.text, file.style) };
|
|
135
|
+
});
|
|
136
|
+
return { root, config, files: files.filter((f): f is FileRecord => f !== null) };
|
|
24
137
|
};
|