@inixiative/atlas 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 inixiative
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,207 @@
1
+ # atlas
2
+
3
+ **The map of the codebase.** atlas reads `@atlas` annotations declared at the top of each file,
4
+ validates them against a repo-owned **concept registry**, and generates a `MAP.md` that *cannot drift
5
+ on the structural facts* — because atlas only ever asserts what is mechanically true (what exists,
6
+ how it connects), never maturity or correctness.
7
+
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.**
10
+
11
+ ```ts
12
+ /**
13
+ * @atlas
14
+ * @kind controller
15
+ * @partOf feature:tenancy
16
+ * @uses primitive:authz, infrastructure:redis
17
+ */
18
+ ```
19
+
20
+ ## Why
21
+
22
+ Hand-maintained maps (FEATURES.md, docs, prose) drift from the code. atlas makes the map a
23
+ *projection* of the code: every file declares traversable **concepts** — what it is, what it's part
24
+ of, what it uses — so the repo is explorable by **concept** instead of by crawling folders.
25
+ "Show me everything that touches caching" becomes one traversal.
26
+
27
+ The core discipline: **meaning emerges from the intersection of several true edges**, not from one
28
+ hyper-specific label. Keep the vocabulary broad but closed; apply it liberally.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ bun add -d @inixiative/atlas
34
+ ```
35
+
36
+ atlas is Bun-native (it imports your `.atlas/*.ts` config directly).
37
+
38
+ ## Configure
39
+
40
+ A consuming repo gets a `.atlas/` folder. atlas ships a sensible default `kinds` vocab; the
41
+ repo **owns** its concept registry.
42
+
43
+ ```
44
+ .atlas/
45
+ config.ts // stamp rules (path → tags) + ignore + reference resolvers
46
+ kinds.ts // @kind vocab — extends atlas's defaults
47
+ concepts.ts // the concept registry — repo-OWNED, structure only
48
+ ```
49
+
50
+ ```ts
51
+ // .atlas/concepts.ts — structure only, no status/note. YOU define the concept classes
52
+ // (feature/primitive/…) and the constituent categories (module/package/…).
53
+ import type { ConceptRegistry } from '@inixiative/atlas';
54
+
55
+ export const CONCEPTS: ConceptRegistry = {
56
+ 'feature:tenancy': { module: ['organization', 'space'], docs: ['AUTH.md'] },
57
+ 'infrastructure:redis': { docs: ['REDIS.md'] },
58
+ };
59
+ ```
60
+
61
+ ```ts
62
+ // .atlas/config.ts — stamp rules compose; explicit always wins.
63
+ import { defineConfig, partOfFor } from '@inixiative/atlas/config';
64
+
65
+ export default defineConfig({
66
+ include: ['apps/**/*.ts', 'packages/**/*.ts'],
67
+ ignore: ['**/*.test.ts', '**/index.ts'],
68
+ stamp: [
69
+ { include: '**/controllers/**', kind: 'controller' }, // @kind from a structural glob
70
+ { include: 'apps/api/src/modules/$1/**', partOf: partOfFor('module', '$1') }, // @partOf from a capture
71
+ ],
72
+ references: { docs: (v) => `docs/${v}` }, // for reference-existence checks
73
+ });
74
+ ```
75
+
76
+ A complete, commented set you can copy into your repo's `.atlas/` is in
77
+ [`examples/atlas-config/`](./examples/atlas-config/) (`kinds.ts`, `concepts.ts`, `config.ts`).
78
+
79
+ ## CLI
80
+
81
+ ```bash
82
+ atlas graph # reverse indexes: concept → files, file → concepts, doc → concepts
83
+ atlas check # presence + vocab existence + reference existence (the CI command)
84
+ atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
85
+ atlas generate # write MAP.md from the annotated tree
86
+ atlas report # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)
87
+ atlas stamp [dir] # write/refresh @atlas blocks from the rules (the patcher; dry-run by default)
88
+ ```
89
+
90
+ Common flags: `--root <dir>`, `--json`, `generate --stdout`, `stamp --write`, `stamp --overwrite`,
91
+ `coverage --min/--ratchet`, `report --out <dir>/--md/--html`.
92
+
93
+ ## For AI agents
94
+
95
+ atlas exists largely so agents stop grab-bagging files and answering from stale labels. Drop this
96
+ line into your agent's system prompt / `CLAUDE.md` / `AGENTS.md` so it navigates by **concept**
97
+ instead of crawling folders:
98
+
99
+ > This repo is mapped by **atlas**. To find code by concept instead of by filename: read `MAP.md`
100
+ > for the concept overview; run `bunx atlas graph --json` for the reverse indexes (concept → files via
101
+ > `@partOf`, concept → consumers via `@uses`); and read a file's top-of-file `@atlas` block
102
+ > (`@kind` / `@partOf` / `@uses`) before its body. Prefer these over `grep` for "what touches X" /
103
+ > "what's part of Y" questions.
104
+
105
+ Why it helps: the agent gets the high-altitude map without reading the tree, answers "everything
106
+ that touches caching" in **one** `graph --json` call, and learns a file's role/edges from its block
107
+ before opening it. In an A/B test on a repo with a transitive dependency, agents given this line
108
+ used `atlas graph` and solved a "what reaches redis (directly or transitively)" question in ~2 tool
109
+ calls; agents left to `grep` took 2–3× as many and risk missing the transitive edge entirely.
110
+
111
+ ## Visualize
112
+
113
+ `atlas report` emits two artifacts:
114
+
115
+ - **`COVERAGE.md`** — diffable, GitHub-native: a totals table, a Mermaid coverage pie, a per-category
116
+ gap table (required `@kind`/`@partOf` gaps split from the `@uses` curation buckets), and a Mermaid
117
+ concept-dependency graph. Categories group by **effective concept** — a file's declared `@partOf`, or the
118
+ rules' *predicted* concept when unannotated — so you get a per-concept work plan even at 0% coverage.
119
+ - **`atlas.html`** — a self-contained interactive graph ([Cytoscape.js](https://js.cytoscape.org/)):
120
+ concepts grouped by class (compound nodes), coloured by coverage; click a concept to drill into its file
121
+ list, click to highlight its dependencies (traverse). No build step — open it in a browser.
122
+
123
+ ## The annotation model
124
+
125
+ | Question | Tag | Value | Notes |
126
+ |----------|-----|-------|-------|
127
+ | What is this? | `@kind` | closed enum | 1+, e.g. `entrypoint, route` (a role, not a layer) |
128
+ | What is it part of? | `@partOf` | `class:name` concept(s) | membership; multi is normal |
129
+ | What does it use? | `@uses` | `class:name` concept(s) | dependency, load-bearing only |
130
+ | What does it build? | `@constructs` | factory output | constructors only |
131
+
132
+ All axes are multi-valued (comma-separated on one line). `@atlas` opens the block.
133
+
134
+ ### Writing a block (for agents & humans)
135
+
136
+ A top-of-file JSDoc block, above the imports (below a shebang if present):
137
+
138
+ ```ts
139
+ /**
140
+ * @atlas
141
+ * @kind controller
142
+ * @partOf feature:billing, superadmin
143
+ * @uses primitive:authz, infrastructure:redis
144
+ */
145
+ ```
146
+
147
+ Rules of thumb:
148
+ - **`@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`).
149
+ - **`@partOf` is membership** — the concept(s) this file *composes* (remove it and the concept breaks). Multiple is normal and expected: a feature has **many** controllers/routes/**entrypoints**; a file can be part of a feature *and* a cross-cutting tag (`feature:inquiry, superadmin`). The reusable helpers that build something belong to it — e.g. `makeController` and the route-template helper services are all `@partOf primitive:routeTemplates`.
150
+ - **`@uses` is dependency, LOAD-BEARING only** — a concept this file depends on but isn't part of, where someone reasoning about that concept's blast radius needs this file. Not every import. Skip incidental touches (one `db.x.update()` through the request context is not "using" the database). Write `@uses none` only after a human/agent looked and it genuinely uses nothing load-bearing; otherwise omit the line (= uncurated).
151
+ - **Validate names against the repo's `.atlas/`** — `@kind` ∈ `kinds.ts`; `@partOf`/`@uses` must name a concept that exists in `concepts.ts`.
152
+ - **Prefer several broad-true tags over one narrow tag** — meaning emerges from the intersection of true edges, not from one hyper-specific label.
153
+
154
+ ### `@uses` is never auto-stamped
155
+
156
+ Absence is meaningful, so atlas leaves `@uses` out of stamping entirely:
157
+
158
+ - **no `@uses` line** = *uncurated* (nobody filled it in)
159
+ - **`@uses none`** = *curated-empty* (a human looked; it uses nothing load-bearing)
160
+ - **`@uses? x`** = *proposed* (a patcher suggestion awaiting acceptance)
161
+
162
+ `coverage` reports these as distinct buckets.
163
+
164
+ ## The patcher: `atlas stamp`
165
+
166
+ Blanks are fillable on demand — the `eslint --fix` shape. Always **dry-run by default**; pass
167
+ `--write` to apply.
168
+
169
+ - **Targeting** — `all` (default), a folder, or a single file.
170
+ - **Additive (default)** — fill only what's absent; never modify an existing tag; never touch `@uses`.
171
+ - **Overwrite (`--overwrite`)** — resync the derivable axes (`@kind`/`@partOf`) to the current
172
+ rules; **never** overwrites curated `@uses`. A `@atlas pin` block is exempt.
173
+
174
+ ## CI
175
+
176
+ `atlas check` is the CI primitive — it exits non-zero on any problem, so wiring it in is just
177
+ running it in a workflow (no separate package needed). Copy-paste examples live in
178
+ [`examples/ci/`](./examples/ci/): a full-repo GitHub Actions workflow with a `MAP.md` freshness
179
+ gate, an incremental PR variant, and a pre-commit hook. The recommended rollout on an existing
180
+ codebase is **warn-only → incremental enforcing → fully enforcing**:
181
+
182
+ ```bash
183
+ atlas check --warn-only # prints problems, never fails CI (rollout start)
184
+ atlas check <path> # enforce only changed paths (skips registry-wide reference checks)
185
+ atlas check # enforce the whole repo
186
+ ```
187
+
188
+ Gate **coverage** the same way — a percentage floor or a ratchet that forbids regressions
189
+ (ideal for a repo starting near 0%):
190
+
191
+ ```bash
192
+ atlas coverage --min 80 # fail below 80% annotated
193
+ atlas coverage --ratchet # fail if unannotated count exceeds .atlas/coverage-baseline.json
194
+ atlas coverage --update-baseline # record the current count (commit the baseline)
195
+ ```
196
+
197
+ ## Enforcement: existence, NOT correctness
198
+
199
+ `atlas check` verifies annotations **exist and use valid vocabulary** — presence of a block, that
200
+ `@kind` is in the vocab, that `@partOf`/`@uses` name a concept that exists, and that a
201
+ concept's doc references resolve. It explicitly does **not** reconcile the import graph, judge
202
+ whether a `@partOf` is "really true," or derive any status. Those are fool's errands that trade a
203
+ clear structural guarantee for a fragile proxy.
204
+
205
+ ## License
206
+
207
+ MIT
package/bin/atlas.ts ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env bun
2
+ import { runCli } from '../src/cli.ts';
3
+
4
+ const { code, out } = await runCli(process.argv.slice(2), { cwd: process.cwd() });
5
+ if (out) (code === 0 ? console.log : console.error)(out);
6
+ process.exit(code);
@@ -0,0 +1,26 @@
1
+ # Example `.atlas/` config
2
+
3
+ Copy these three 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
5
+ owns the concept registry.**
6
+
7
+ ```
8
+ .atlas/
9
+ kinds.ts # @kind vocab — atlas's defaults, extended with any roles you add
10
+ concepts.ts # the concept registry — repo-OWNED, structure only (the one you'll edit most)
11
+ config.ts # stamp rules (path → tags), ignore globs, and reference resolvers
12
+ ```
13
+
14
+ The key idea: atlas hardcodes **no** concept classes (`feature`/`primitive`/…) and **no** constituent
15
+ categories (`module`/`package`/`integration`/…). *You* define them — they're just the keys you use
16
+ in `concepts.ts` and reference from `config.ts`. atlas only validates that a `@partOf`/`@uses` names a
17
+ concept that exists, that a `@kind` is in your vocab, and that referenced docs resolve.
18
+
19
+ | File | You edit it… | Notes |
20
+ |------|--------------|-------|
21
+ | [`concepts.ts`](./concepts.ts) | constantly | add a concept when you add a feature/primitive; list its constituent folders so `@partOf` auto-fills |
22
+ | [`config.ts`](./config.ts) | rarely | structural globs → `@kind`; capture globs → `@partOf` via membership |
23
+ | [`kinds.ts`](./kinds.ts) | rarely | only when a role the defaults don't cover shows up |
24
+
25
+ After copying, `bunx atlas stamp --write` fills `@kind`/`@partOf` from the rules, `bunx atlas check`
26
+ gates it, and `bunx atlas generate` writes `MAP.md`.
@@ -0,0 +1,35 @@
1
+ import type { ConceptRegistry } from '@inixiative/atlas';
2
+
3
+ // The concept registry — the single source of valid concepts, repo-OWNED, STRUCTURE
4
+ // ONLY (no status, no notes — those rot). Keyed `class:name`; the class prefix
5
+ // (here: feature / primitive / infrastructure — the architectural layers) is your
6
+ // choice, derived from these keys, not hardcoded by atlas.
7
+ //
8
+ // Each entry is a bag of named string lists you define:
9
+ // - reference fields (docs) — where to read about the concept; checked for
10
+ // existence by `atlas check` if you wire a resolver in config.ts, and
11
+ // invertible (doc → concepts). Keep references in-repo and stable — don't
12
+ // point at fast-moving external IDs (e.g. ticket numbers) that rot.
13
+ // - constituent fields (module, package, integration) — the code that COMPOSES
14
+ // the concept. These fill @partOf during `atlas stamp` via partOfFor(...).
15
+ //
16
+ // A module/package routinely belongs to several concepts — multi-@partOf is normal.
17
+ export const CONCEPTS: ConceptRegistry = {
18
+ // ── features (user-facing capabilities) ───────────────────────────────────
19
+ 'feature:tenancy': { module: ['organization', 'space', 'membership'], docs: ['AUTH.md'] },
20
+ 'feature:billing': { module: ['billing', 'invoicing'], docs: ['BILLING.md'] },
21
+ 'feature:users': { module: ['user', 'profile'] },
22
+ 'feature:email': { package: ['email'], integration: ['sendgrid'], docs: ['COMMUNICATIONS.md'] },
23
+ // feature-flags is a feature; the flags table inside it is a file `@kind registry`.
24
+ 'feature:featureFlags': { module: ['flags'] },
25
+
26
+ // ── primitives (reusable building blocks features are made of) ─────────────
27
+ 'primitive:authz': { package: ['permissions'], docs: ['PERMISSIONS.md'] },
28
+ 'primitive:caching': { module: ['cache'], docs: ['REDIS.md'] },
29
+ 'primitive:jobs': { module: ['jobs'], docs: ['JOBS.md'] },
30
+
31
+ // ── infrastructure (external dependencies consumed via @uses) ──────────────
32
+ 'infrastructure:postgres': { package: ['db'], docs: ['DATABASE.md'] },
33
+ 'infrastructure:redis': { docs: ['REDIS.md'] },
34
+ 'infrastructure:s3': {},
35
+ };
@@ -0,0 +1,54 @@
1
+ import { defineConfig, partOfFor } from '@inixiative/atlas/config';
2
+
3
+ export default defineConfig({
4
+ // Files atlas considers (everything else is invisible to it).
5
+ include: ['apps/**/*.ts', 'apps/**/*.tsx', 'packages/**/*.ts'],
6
+
7
+ // Files exempt from the presence check and from stamping (barrels, tests, generated).
8
+ ignore: ['**/*.test.ts', '**/*.test.tsx', '**/tests/**', '**/index.ts', '**/*.d.ts', '**/*.gen.ts'],
9
+
10
+ // Stamp rules COMPOSE (not first-match-wins) — every matching rule contributes.
11
+ // `@uses` is never auto-stamped (its absence is a signal), so there are no @uses rules.
12
+ stamp: [
13
+ // @kind from structural globs (no capture). Rules compose, so a file can pick
14
+ // up several — e.g. a file in components/ AND matching *.types.ts.
15
+ { include: '**/controllers/**', kind: 'controller' },
16
+ { include: 'apps/api/**/routes/**', kind: 'route' }, // backend HTTP routes
17
+ { include: '**/services/**', kind: 'service' },
18
+ { include: '**/queries/**', kind: 'query' },
19
+ { include: '**/schemas/**', kind: 'schema' },
20
+ { include: '**/handlers/**', kind: 'handler' },
21
+ { include: '**/jobs/**', kind: 'job' },
22
+ { include: ['**/constants/**', '**/constants.ts'], kind: 'constant' },
23
+ { include: ['**/utils/**', '**/utils.ts'], kind: 'utils' },
24
+ { include: ['**/types/**', '**/*.types.ts'], kind: 'type' },
25
+ { include: '**/factories/**', kind: 'factory' },
26
+ { include: ['**/client.ts', '**/*.client.ts'], kind: 'client' },
27
+ { include: '**/*.config.ts', kind: 'config' },
28
+ { include: ['**/seed.ts', '**/*.seed.ts', '**/seeds/**'], kind: 'seed' },
29
+ { include: '**/bridges/**', kind: 'bridge' },
30
+ { include: '**/defs/**', kind: 'definition' },
31
+ { include: '**/*Error.ts', kind: 'error' },
32
+ { include: '**/generate*.ts', kind: 'generator' },
33
+ // frontend (UI library + apps): components, hooks, file-based routes (pages), stores, bootstrap
34
+ { include: '**/components/**', kind: 'component' },
35
+ { include: ['packages/ui/**/hooks/**', 'apps/*/**/hooks/**'], kind: 'hook' }, // React hooks (not api db-hooks)
36
+ { include: ['apps/*/**/routes/**'], kind: 'page' }, // TanStack file-based routes are pages
37
+ { include: ['**/store/**', '**/*.store.ts'], kind: 'store' },
38
+ { include: ['apps/*/app/main.tsx', 'apps/*/app/client.tsx', 'apps/*/app/router.tsx'], kind: 'entrypoint' },
39
+
40
+ // @partOf from a captured path segment, resolved through your constituent
41
+ // categories in concepts.ts. `$1` captures one segment; `partOfFor('module', '$1')`
42
+ // looks the captured folder up across every concept's `module` list (→ multi-@partOf).
43
+ { include: 'apps/api/src/modules/$1/**', partOf: partOfFor('module', '$1') },
44
+ { include: 'apps/api/src/integrations/$1/**', partOf: partOfFor('integration', '$1') },
45
+ { include: 'packages/$1/**', partOf: partOfFor('package', '$1') },
46
+ ],
47
+
48
+ // Resolve a reference field's value to a repo-relative path so `atlas check`
49
+ // can verify it exists. Keep references in-repo and stable (docs), not
50
+ // fast-moving external IDs that rot.
51
+ references: {
52
+ docs: (v) => `docs/${v}`,
53
+ },
54
+ });
@@ -0,0 +1,7 @@
1
+ import { DEFAULT_KINDS } from '@inixiative/atlas';
2
+
3
+ // atlas ships a near-universal `@kind` vocab (controller, route, service, schema,
4
+ // handler, factory, registry, primitive, infrastructure, entrypoint, component,
5
+ // page, hook, store, …). Extend it with any roles specific to your codebase —
6
+ // adding a kind is a one-line edit. Keep it broad-but-closed.
7
+ export const KINDS = [...DEFAULT_KINDS, 'job', 'migration', 'seedScript'] as const;
@@ -0,0 +1,75 @@
1
+ # atlas in CI
2
+
3
+ atlas needs no separate "ci-rules" package — `atlas check` *is* the CI primitive (it exits non-zero
4
+ on any problem). These are copy-paste examples for wiring it in. Pick the ones you need.
5
+
6
+ | File | What it does |
7
+ |------|--------------|
8
+ | [`github-actions.yml`](./github-actions.yml) | Full-repo check + coverage ratchet + `MAP.md` freshness gate (push/PR) |
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 |
11
+
12
+ ## Rollout (DEV-003 Phase 4): warn-only → enforcing
13
+
14
+ `atlas check` is binary (any problem fails). On an existing codebase that starts at ~0% annotated,
15
+ flip the switch gradually:
16
+
17
+ 1. **Warn-only** — `atlas check --warn-only` prints problems but always exits 0. Wire it into CI so
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
20
+ registry-wide reference check, so it's about the changed files only). New code must be annotated;
21
+ legacy code is grandfathered.
22
+ 3. **Fully enforcing** — once coverage is high, drop to plain `atlas check` on the whole repo.
23
+
24
+ Track progress between phases with `atlas coverage`.
25
+
26
+ ## Coverage gate
27
+
28
+ `atlas coverage` exits non-zero when a gate fails, so it drops into CI like `check`. Two styles:
29
+
30
+ ```bash
31
+ atlas coverage --min 80 # percentage floor — fail below 80% annotated
32
+ atlas coverage --ratchet # backslide guard — unannotated count may not exceed the baseline
33
+ ```
34
+
35
+ The **ratchet** is the right gate for a repo starting near 0%: instead of demanding an unreachable
36
+ percentage, it forbids regressions. Commit a baseline, then tighten it as you back-fill:
37
+
38
+ ```bash
39
+ atlas coverage --update-baseline # writes .atlas/coverage-baseline.json (commit this)
40
+ git add .atlas/coverage-baseline.json
41
+ ```
42
+
43
+ In CI, `atlas coverage --ratchet` then fails any PR that adds unannotated files. Re-run
44
+ `--update-baseline` and commit whenever you lower the count, so it only moves one direction.
45
+ Switch to `--min` once coverage is high enough to hold a percentage.
46
+
47
+ ## Keep `MAP.md` honest
48
+
49
+ The map is a projection of the code, so a stale `MAP.md` in a PR is a bug. Regenerate and diff:
50
+
51
+ ```bash
52
+ atlas generate
53
+ git diff --exit-code MAP.md # fails CI if the committed map is out of date
54
+ ```
55
+
56
+ ## package.json scripts
57
+
58
+ ```jsonc
59
+ {
60
+ "scripts": {
61
+ "atlas:check": "atlas check",
62
+ "atlas:map": "atlas generate",
63
+ "atlas:coverage": "atlas coverage",
64
+ "atlas:stamp": "atlas stamp --write"
65
+ }
66
+ }
67
+ ```
68
+
69
+ ## Why not a standalone `@inixiative/atlas-ci` package?
70
+
71
+ The "rules" that vary per repo (stamp rules, vocab, the concept registry) already live in the consumer's
72
+ `.atlas/` folder — there is no shared executable logic to extract; a package would contain only the
73
+ YAML above. The only future case that justifies a separate artifact is a rich **GitHub Action**
74
+ (inline PR annotations, caching) — and that ships as its own action repo, not an npm package. Until
75
+ then, these examples are enough.
@@ -0,0 +1,32 @@
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):
3
+ # new/edited code must be annotated; legacy code is grandfathered.
4
+ name: atlas (incremental)
5
+
6
+ on: pull_request
7
+
8
+ jobs:
9
+ atlas:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ with:
14
+ fetch-depth: 0
15
+
16
+ - uses: oven-sh/setup-bun@v2
17
+ with:
18
+ bun-version: latest
19
+
20
+ - run: bun install --frozen-lockfile
21
+
22
+ - name: atlas check (changed paths)
23
+ 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
@@ -0,0 +1,43 @@
1
+ # Example — copy to .github/workflows/atlas.yml in your repo.
2
+ # Full-repo annotation check + MAP.md freshness gate.
3
+ name: atlas
4
+
5
+ on:
6
+ pull_request:
7
+ push:
8
+ branches: [main]
9
+
10
+ jobs:
11
+ atlas:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - uses: oven-sh/setup-bun@v2
17
+ with:
18
+ bun-version: latest
19
+
20
+ - run: bun install --frozen-lockfile
21
+
22
+ # ── Annotation check ────────────────────────────────────────────────
23
+ # Rollout (DEV-003 Phase 4) — start warn-only, flip to enforcing later:
24
+ # warn-only: bunx atlas check --warn-only # prints, never fails CI
25
+ # enforcing: bunx atlas check # fails CI on any problem
26
+ - name: atlas check
27
+ run: bunx atlas check
28
+
29
+ # ── Coverage gate ───────────────────────────────────────────────────
30
+ # Ratchet: the unannotated count may not exceed the committed baseline
31
+ # (.atlas/coverage-baseline.json), so coverage can only hold or improve.
32
+ # Bump the baseline as you back-fill: atlas coverage --update-baseline
33
+ - name: atlas coverage (ratchet)
34
+ run: bunx atlas coverage --ratchet
35
+ # Or, once coverage is high, swap the ratchet for a percentage floor:
36
+ # run: bunx atlas coverage --min 80
37
+
38
+ # ── MAP.md freshness ────────────────────────────────────────────────
39
+ # The committed map must match the annotated tree, or the PR is stale.
40
+ - name: MAP.md is current
41
+ run: |
42
+ bunx atlas generate
43
+ git diff --exit-code MAP.md
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env sh
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.
5
+
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
15
+
16
+ if [ "$status" -ne 0 ]; then
17
+ echo "atlas: fix the annotations above, or run 'bunx atlas stamp <dir> --write' to fill them."
18
+ fi
19
+ exit "$status"
package/package.json ADDED
@@ -0,0 +1,57 @@
1
+ {
2
+ "name": "@inixiative/atlas",
3
+ "version": "0.0.0",
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
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "inixiative",
8
+ "homepage": "https://github.com/inixiative/atlas#readme",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/inixiative/atlas.git"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/inixiative/atlas/issues"
15
+ },
16
+ "keywords": [
17
+ "atlas",
18
+ "codebase-map",
19
+ "annotations",
20
+ "architecture",
21
+ "seams",
22
+ "documentation",
23
+ "static-analysis"
24
+ ],
25
+ "bin": {
26
+ "atlas": "./bin/atlas.ts"
27
+ },
28
+ "exports": {
29
+ ".": "./src/index.ts",
30
+ "./config": "./src/config/defineConfig.ts"
31
+ },
32
+ "files": [
33
+ "src",
34
+ "bin",
35
+ "examples",
36
+ "README.md",
37
+ "LICENSE"
38
+ ],
39
+ "scripts": {
40
+ "test": "bun test",
41
+ "typecheck": "tsc --noEmit",
42
+ "atlas": "bun run ./bin/atlas.ts"
43
+ },
44
+ "engines": {
45
+ "bun": ">=1.0.0"
46
+ },
47
+ "publishConfig": {
48
+ "access": "public"
49
+ },
50
+ "devDependencies": {
51
+ "@types/bun": "latest",
52
+ "typescript": "^5.6.0"
53
+ },
54
+ "dependencies": {
55
+ "@inixiative/json-rules": "^2.6.0"
56
+ }
57
+ }
package/src/analyze.ts ADDED
@@ -0,0 +1,24 @@
1
+ import { resolve } from 'node:path';
2
+ import type { LoadedConfig } from './config/defineConfig.ts';
3
+ import { loadConfig } from './config/load.ts';
4
+ import { mapLimit } from './fs/concurrent.ts';
5
+ import { walkFiles } from './fs/walk.ts';
6
+ import { type AtlasAnnotation, parseAtlasBlock } from './parse/parseAtlasBlock.ts';
7
+
8
+ export type FileRecord = { path: string; annotation: AtlasAnnotation | null };
9
+ export type Analysis = { root: string; config: LoadedConfig; files: FileRecord[] };
10
+
11
+ // Bound open file descriptors so a repo with thousands of files can't hit EMFILE.
12
+ const READ_CONCURRENCY = 64;
13
+
14
+ // One pass: load the consumer's .atlas/ config, walk the considered files, and
15
+ // parse each into its @atlas annotation (or null). Every command consumes this.
16
+ export const analyze = async (root: string): Promise<Analysis> => {
17
+ 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 };
24
+ };