@inixiative/atlas 0.4.1 → 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 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 is Bun-native (it imports your `.atlas/*.ts` config directly).
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 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)
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 <target>` skips the doc check like the other reference checks. `loadConfig`
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** — `all` (default), a folder, or a single file.
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 <path> # enforce only changed paths (skips registry-wide reference checks)
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. 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,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 source dirs before commit |
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 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
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
@@ -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,6 +1,6 @@
1
1
  {
2
2
  "name": "@inixiative/atlas",
3
- "version": "0.4.1",
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.115",
57
- "@types/bun": "1.4.2",
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.5.4"
62
+ "@inixiative/json-rules": "^3.16.0"
63
63
  },
64
- "packageManager": "bun@1.4.2"
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
- export type FileRecord = { path: string; annotation: AtlasAnnotation | null };
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 paths = await walkFiles(root, config.include, config.ignore);
19
- const files: FileRecord[] = await mapLimit(paths, READ_CONCURRENCY, async (path) => ({
20
- path,
21
- annotation: parseAtlasBlock(await Bun.file(resolve(root, path)).text()),
22
- }));
23
- return { root, config, files };
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
  };