@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 +21 -0
- package/README.md +207 -0
- package/bin/atlas.ts +6 -0
- package/examples/atlas-config/README.md +26 -0
- package/examples/atlas-config/concepts.ts +35 -0
- package/examples/atlas-config/config.ts +54 -0
- package/examples/atlas-config/kinds.ts +7 -0
- package/examples/ci/README.md +75 -0
- package/examples/ci/github-actions-incremental.yml +32 -0
- package/examples/ci/github-actions.yml +43 -0
- package/examples/ci/pre-commit +19 -0
- package/package.json +57 -0
- package/src/analyze.ts +24 -0
- package/src/cli.ts +281 -0
- package/src/commands/check.ts +71 -0
- package/src/commands/coverage.ts +86 -0
- package/src/commands/generate.ts +54 -0
- package/src/commands/graph.ts +38 -0
- package/src/commands/query.ts +33 -0
- package/src/commands/report.ts +0 -0
- package/src/commands/stamp.ts +74 -0
- package/src/config/defineConfig.ts +59 -0
- package/src/config/glob.ts +83 -0
- package/src/config/load.ts +56 -0
- package/src/config/stamp.ts +84 -0
- package/src/fs/concurrent.ts +19 -0
- package/src/fs/walk.ts +26 -0
- package/src/index.ts +16 -0
- package/src/parse/parseAtlasBlock.ts +104 -0
- package/src/registry/invert.ts +21 -0
- package/src/registry/types.ts +21 -0
- package/src/render/html.ts +109 -0
- package/src/render/markdown.ts +86 -0
- package/src/stamp/patcher.ts +111 -0
- package/src/vocab/kinds.ts +52 -0
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,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
|
+
};
|