@inixiative/atlas 0.0.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/examples/atlas-config/config.ts +12 -2
- package/package.json +14 -6
- package/src/cli.ts +68 -22
- package/src/commands/check.ts +29 -6
- package/src/commands/coverage.ts +16 -3
- package/src/commands/generate.ts +10 -3
- package/src/commands/graph.ts +2 -1
- package/src/commands/report.ts +0 -0
- package/src/commands/stamp.ts +5 -2
- package/src/config/defineConfig.ts +7 -1
- package/src/config/load.ts +9 -3
- package/src/config/stamp.ts +12 -2
- package/src/index.ts +9 -3
- package/src/parse/parseAtlasBlock.ts +10 -2
- package/src/registry/invert.ts +2 -1
- package/src/registry/types.ts +7 -1
- package/src/render/html.ts +1 -1
- package/src/render/markdown.ts +19 -7
- package/src/stamp/patcher.ts +12 -3
|
@@ -5,7 +5,14 @@ export default defineConfig({
|
|
|
5
5
|
include: ['apps/**/*.ts', 'apps/**/*.tsx', 'packages/**/*.ts'],
|
|
6
6
|
|
|
7
7
|
// Files exempt from the presence check and from stamping (barrels, tests, generated).
|
|
8
|
-
ignore: [
|
|
8
|
+
ignore: [
|
|
9
|
+
'**/*.test.ts',
|
|
10
|
+
'**/*.test.tsx',
|
|
11
|
+
'**/tests/**',
|
|
12
|
+
'**/index.ts',
|
|
13
|
+
'**/*.d.ts',
|
|
14
|
+
'**/*.gen.ts',
|
|
15
|
+
],
|
|
9
16
|
|
|
10
17
|
// Stamp rules COMPOSE (not first-match-wins) — every matching rule contributes.
|
|
11
18
|
// `@uses` is never auto-stamped (its absence is a signal), so there are no @uses rules.
|
|
@@ -35,7 +42,10 @@ export default defineConfig({
|
|
|
35
42
|
{ include: ['packages/ui/**/hooks/**', 'apps/*/**/hooks/**'], kind: 'hook' }, // React hooks (not api db-hooks)
|
|
36
43
|
{ include: ['apps/*/**/routes/**'], kind: 'page' }, // TanStack file-based routes are pages
|
|
37
44
|
{ include: ['**/store/**', '**/*.store.ts'], kind: 'store' },
|
|
38
|
-
{
|
|
45
|
+
{
|
|
46
|
+
include: ['apps/*/app/main.tsx', 'apps/*/app/client.tsx', 'apps/*/app/router.tsx'],
|
|
47
|
+
kind: 'entrypoint',
|
|
48
|
+
},
|
|
39
49
|
|
|
40
50
|
// @partOf from a captured path segment, resolved through your constituent
|
|
41
51
|
// categories in concepts.ts. `$1` captures one segment; `partOfFor('module', '$1')`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@inixiative/atlas",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1",
|
|
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",
|
|
@@ -39,7 +39,11 @@
|
|
|
39
39
|
"scripts": {
|
|
40
40
|
"test": "bun test",
|
|
41
41
|
"typecheck": "tsc --noEmit",
|
|
42
|
-
"
|
|
42
|
+
"check": "bun run typecheck && bun run lint && bun run test",
|
|
43
|
+
"atlas": "bun run ./bin/atlas.ts",
|
|
44
|
+
"prepublishOnly": "bun run check && bun run test",
|
|
45
|
+
"lint": "biome check .",
|
|
46
|
+
"prepare": "lefthook install"
|
|
43
47
|
},
|
|
44
48
|
"engines": {
|
|
45
49
|
"bun": ">=1.0.0"
|
|
@@ -48,10 +52,14 @@
|
|
|
48
52
|
"access": "public"
|
|
49
53
|
},
|
|
50
54
|
"devDependencies": {
|
|
51
|
-
"@types/bun": "
|
|
52
|
-
"typescript": "
|
|
55
|
+
"@types/bun": "1.3.14",
|
|
56
|
+
"typescript": "6.0.3",
|
|
57
|
+
"@biomejs/biome": "2.5.2",
|
|
58
|
+
"@inixiative/config": "^0.2.1",
|
|
59
|
+
"lefthook": "2.1.9"
|
|
53
60
|
},
|
|
54
61
|
"dependencies": {
|
|
55
|
-
"@inixiative/json-rules": "^2.
|
|
56
|
-
}
|
|
62
|
+
"@inixiative/json-rules": "^2.13.0"
|
|
63
|
+
},
|
|
64
|
+
"packageManager": "bun@1.3.14"
|
|
57
65
|
}
|
package/src/cli.ts
CHANGED
|
@@ -5,7 +5,7 @@ import { coverage, evaluateCoverageGate, readBaseline } from './commands/coverag
|
|
|
5
5
|
import { generate } from './commands/generate.ts';
|
|
6
6
|
import { graph } from './commands/graph.ts';
|
|
7
7
|
import { flagsToRule, type QueryRule, queryFiles, toQueryRecords } from './commands/query.ts';
|
|
8
|
-
import {
|
|
8
|
+
import { buildConceptGraph, buildCoverageReport } from './commands/report.ts';
|
|
9
9
|
import { inScope, runStamp } from './commands/stamp.ts';
|
|
10
10
|
import { renderCoverageHtml } from './render/html.ts';
|
|
11
11
|
import { renderCoverageMarkdown } from './render/markdown.ts';
|
|
@@ -59,7 +59,10 @@ const parseArgs = (args: string[]): { flags: Flags; positionals: string[] } => {
|
|
|
59
59
|
// Don't swallow the next flag as a value: `--min --json` leaves min empty
|
|
60
60
|
// (caught downstream) rather than silently capturing '--json'.
|
|
61
61
|
const next = args[i + 1];
|
|
62
|
-
|
|
62
|
+
if (next !== undefined && !next.startsWith('--')) {
|
|
63
|
+
flags[key] = next;
|
|
64
|
+
i++;
|
|
65
|
+
} else flags[key] = '';
|
|
63
66
|
} else flags[key] = true;
|
|
64
67
|
} else positionals.push(a);
|
|
65
68
|
}
|
|
@@ -67,11 +70,17 @@ const parseArgs = (args: string[]): { flags: Flags; positionals: string[] } => {
|
|
|
67
70
|
};
|
|
68
71
|
|
|
69
72
|
const version = async (): Promise<string> => {
|
|
70
|
-
const pkg = (await import('../package.json')) as {
|
|
73
|
+
const pkg = (await import('../package.json')) as {
|
|
74
|
+
version?: string;
|
|
75
|
+
default?: { version?: string };
|
|
76
|
+
};
|
|
71
77
|
return pkg.version ?? pkg.default?.version ?? '0.0.0';
|
|
72
78
|
};
|
|
73
79
|
|
|
74
|
-
export const runCli = async (
|
|
80
|
+
export const runCli = async (
|
|
81
|
+
argv: string[],
|
|
82
|
+
env: { cwd: string },
|
|
83
|
+
): Promise<{ code: number; out: string }> => {
|
|
75
84
|
const out: string[] = [];
|
|
76
85
|
const log = (s = ''): void => void out.push(s);
|
|
77
86
|
const done = (code: number) => ({ code, out: out.join('\n') });
|
|
@@ -82,7 +91,8 @@ export const runCli = async (argv: string[], env: { cwd: string }): Promise<{ co
|
|
|
82
91
|
const json = flags.json === true;
|
|
83
92
|
|
|
84
93
|
if (flags.version === true) return { code: 0, out: await version() };
|
|
85
|
-
if (flags.help === true || command === undefined || command === 'help')
|
|
94
|
+
if (flags.help === true || command === undefined || command === 'help')
|
|
95
|
+
return { code: 0, out: HELP };
|
|
86
96
|
|
|
87
97
|
// Error boundary: any thrown error (bad config, IO, corrupt baseline) becomes a
|
|
88
98
|
// clean one-line message + exit 1, never an unhandled rejection / stack trace.
|
|
@@ -111,24 +121,35 @@ const dispatch = async (
|
|
|
111
121
|
const target = positionals[1];
|
|
112
122
|
const warnOnly = flags['warn-only'] === true;
|
|
113
123
|
const full = await analyze(root);
|
|
114
|
-
const scoped = target
|
|
124
|
+
const scoped = target
|
|
125
|
+
? { ...full, files: full.files.filter((f) => inScope(f.path, target)) }
|
|
126
|
+
: full;
|
|
115
127
|
const result = await runCheck(scoped, { references: target === undefined });
|
|
116
128
|
|
|
117
129
|
if (json) log(JSON.stringify({ ...result, warnOnly }, null, 2));
|
|
118
130
|
else if (result.ok) log('✓ atlas check passed');
|
|
119
131
|
else {
|
|
120
|
-
log(
|
|
121
|
-
|
|
132
|
+
log(
|
|
133
|
+
`${warnOnly ? '⚠' : '✗'} atlas check: ${result.problems.length} problem(s)${warnOnly ? ' — warn-only' : ''}`,
|
|
134
|
+
);
|
|
135
|
+
for (const p of result.problems)
|
|
136
|
+
log(` [${p.kind}] ${p.file ?? p.concept ?? ''} — ${p.message}`);
|
|
122
137
|
}
|
|
123
138
|
return done(result.ok || warnOnly ? 0 : 1);
|
|
124
139
|
}
|
|
125
140
|
|
|
126
141
|
case 'coverage': {
|
|
127
142
|
const c = coverage(await analyze(root));
|
|
128
|
-
const baselinePath = resolve(
|
|
143
|
+
const baselinePath = resolve(
|
|
144
|
+
root,
|
|
145
|
+
(flags.baseline as string) || '.atlas/coverage-baseline.json',
|
|
146
|
+
);
|
|
129
147
|
|
|
130
148
|
if (flags['update-baseline'] === true) {
|
|
131
|
-
await Bun.write(
|
|
149
|
+
await Bun.write(
|
|
150
|
+
baselinePath,
|
|
151
|
+
`${JSON.stringify({ unannotated: c.unannotated.length }, null, 2)}\n`,
|
|
152
|
+
);
|
|
132
153
|
log(`✓ wrote coverage baseline: ${c.unannotated.length} unannotated`);
|
|
133
154
|
return done(0);
|
|
134
155
|
}
|
|
@@ -157,9 +178,17 @@ const dispatch = async (
|
|
|
157
178
|
log(JSON.stringify({ ...c, percent: gate.percent, gate }, null, 2));
|
|
158
179
|
} else {
|
|
159
180
|
log(`Coverage: ${c.annotated}/${c.total} files annotated (${gate.percent.toFixed(1)}%)`);
|
|
160
|
-
if (c.unannotated.length)
|
|
161
|
-
|
|
162
|
-
|
|
181
|
+
if (c.unannotated.length)
|
|
182
|
+
log(
|
|
183
|
+
` unannotated (${c.unannotated.length}):\n${c.unannotated.map((f) => ` ${f}`).join('\n')}`,
|
|
184
|
+
);
|
|
185
|
+
log(
|
|
186
|
+
` @uses — curated ${c.uses.curated.length}, curated-empty ${c.uses.curatedEmpty.length}, proposed ${c.uses.proposed.length}, uncurated ${c.uses.uncurated.length}`,
|
|
187
|
+
);
|
|
188
|
+
if (c.unresolved.length)
|
|
189
|
+
log(
|
|
190
|
+
` unresolved memberships (${c.unresolved.length}):\n${c.unresolved.map((u) => ` ${u.file}: ${u.category}:${u.value}`).join('\n')}`,
|
|
191
|
+
);
|
|
163
192
|
if (!gate.ok) for (const r of gate.reasons) log(`✗ ${r}`);
|
|
164
193
|
else if (gating) log('✓ coverage gate passed');
|
|
165
194
|
}
|
|
@@ -171,9 +200,11 @@ const dispatch = async (
|
|
|
171
200
|
if (json) log(JSON.stringify(g, null, 2));
|
|
172
201
|
else {
|
|
173
202
|
log('concept → files (@partOf):');
|
|
174
|
-
for (const concept of Object.keys(g.conceptToFiles).sort())
|
|
203
|
+
for (const concept of Object.keys(g.conceptToFiles).sort())
|
|
204
|
+
log(` ${concept} (${g.conceptToFiles[concept]!.length})`);
|
|
175
205
|
log('concept → consumers (@uses):');
|
|
176
|
-
for (const concept of Object.keys(g.usesConsumers).sort())
|
|
206
|
+
for (const concept of Object.keys(g.usesConsumers).sort())
|
|
207
|
+
log(` ${concept} (${g.usesConsumers[concept]!.length})`);
|
|
177
208
|
}
|
|
178
209
|
return done(0);
|
|
179
210
|
}
|
|
@@ -197,14 +228,19 @@ const dispatch = async (
|
|
|
197
228
|
const wantHtml = flags.md !== true || flags.html === true;
|
|
198
229
|
const written: string[] = [];
|
|
199
230
|
if (wantMd) {
|
|
200
|
-
await Bun.write(
|
|
231
|
+
await Bun.write(
|
|
232
|
+
resolve(outDir, 'COVERAGE.md'),
|
|
233
|
+
renderCoverageMarkdown(report, conceptGraph),
|
|
234
|
+
);
|
|
201
235
|
written.push('COVERAGE.md');
|
|
202
236
|
}
|
|
203
237
|
if (wantHtml) {
|
|
204
238
|
await Bun.write(resolve(outDir, 'atlas.html'), renderCoverageHtml(report, conceptGraph));
|
|
205
239
|
written.push('atlas.html');
|
|
206
240
|
}
|
|
207
|
-
log(
|
|
241
|
+
log(
|
|
242
|
+
`✓ wrote ${written.join(', ')} (${report.total.files - report.total.missingBlock}/${report.total.files} annotated)`,
|
|
243
|
+
);
|
|
208
244
|
return done(0);
|
|
209
245
|
}
|
|
210
246
|
|
|
@@ -237,9 +273,13 @@ const dispatch = async (
|
|
|
237
273
|
}
|
|
238
274
|
}
|
|
239
275
|
const rule: QueryRule | null =
|
|
240
|
-
flagRule && jsonRule
|
|
276
|
+
flagRule && jsonRule
|
|
277
|
+
? ({ all: [flagRule, jsonRule] } as QueryRule)
|
|
278
|
+
: (jsonRule ?? flagRule);
|
|
241
279
|
if (!rule) {
|
|
242
|
-
log(
|
|
280
|
+
log(
|
|
281
|
+
'query needs a json-rules predicate and/or at least one of --kind/--partOf/--uses/--path',
|
|
282
|
+
);
|
|
243
283
|
return done(1);
|
|
244
284
|
}
|
|
245
285
|
const hits = queryFiles(records, rule);
|
|
@@ -256,17 +296,23 @@ const dispatch = async (
|
|
|
256
296
|
const write = flags.write === true;
|
|
257
297
|
const { changes, unresolved } = await runStamp(root, { mode, target: positionals[1], write });
|
|
258
298
|
if (json) {
|
|
259
|
-
log(
|
|
299
|
+
log(
|
|
300
|
+
JSON.stringify({ changes: changes.map((c) => ({ path: c.path })), unresolved }, null, 2),
|
|
301
|
+
);
|
|
260
302
|
} else {
|
|
261
303
|
if (!changes.length) log('✓ nothing to stamp — already up to date');
|
|
262
304
|
else {
|
|
263
|
-
log(
|
|
305
|
+
log(
|
|
306
|
+
`${write ? 'Wrote' : 'Would change'} ${changes.length} file(s)${write ? '' : ' (dry-run — pass --write to apply)'}:`,
|
|
307
|
+
);
|
|
264
308
|
for (const c of changes) log(` ${c.path}`);
|
|
265
309
|
}
|
|
266
310
|
// A capture that resolves to no concept leaves the file without @partOf —
|
|
267
311
|
// surface it here so the registry gap isn't invisible at write time.
|
|
268
312
|
if (unresolved.length) {
|
|
269
|
-
log(
|
|
313
|
+
log(
|
|
314
|
+
`⚠ ${unresolved.length} unresolved membership(s) — left unstamped (add the concept to .atlas/concepts.ts):`,
|
|
315
|
+
);
|
|
270
316
|
for (const u of unresolved) log(` ${u.file}: ${u.category}:${u.value}`);
|
|
271
317
|
}
|
|
272
318
|
}
|
package/src/commands/check.ts
CHANGED
|
@@ -27,11 +27,23 @@ export const checkVocab = (a: Analysis): Problem[] => {
|
|
|
27
27
|
const problems: Problem[] = [];
|
|
28
28
|
for (const { path, annotation } of a.files) {
|
|
29
29
|
if (!annotation) continue;
|
|
30
|
-
for (const k of annotation.kind)
|
|
30
|
+
for (const k of annotation.kind)
|
|
31
|
+
if (!kinds.has(k))
|
|
32
|
+
problems.push({ kind: 'vocab', file: path, message: `unknown @kind '${k}'` });
|
|
31
33
|
for (const p of annotation.partOf)
|
|
32
|
-
if (!concepts.has(p))
|
|
34
|
+
if (!concepts.has(p))
|
|
35
|
+
problems.push({
|
|
36
|
+
kind: 'vocab',
|
|
37
|
+
file: path,
|
|
38
|
+
message: `@partOf '${p}' is not a registered concept`,
|
|
39
|
+
});
|
|
33
40
|
for (const u of annotation.uses)
|
|
34
|
-
if (!concepts.has(u))
|
|
41
|
+
if (!concepts.has(u))
|
|
42
|
+
problems.push({
|
|
43
|
+
kind: 'vocab',
|
|
44
|
+
file: path,
|
|
45
|
+
message: `@uses '${u}' is not a registered concept`,
|
|
46
|
+
});
|
|
35
47
|
}
|
|
36
48
|
return problems;
|
|
37
49
|
};
|
|
@@ -49,11 +61,19 @@ export const checkReferences = async (a: Analysis): Promise<Problem[]> => {
|
|
|
49
61
|
rel = resolver(value);
|
|
50
62
|
} catch (err) {
|
|
51
63
|
const msg = err instanceof Error ? err.message : String(err);
|
|
52
|
-
problems.push({
|
|
64
|
+
problems.push({
|
|
65
|
+
kind: 'reference',
|
|
66
|
+
concept,
|
|
67
|
+
message: `${concept}: ${field} resolver threw on '${value}': ${msg}`,
|
|
68
|
+
});
|
|
53
69
|
continue;
|
|
54
70
|
}
|
|
55
71
|
if (!(await Bun.file(resolve(a.root, rel)).exists())) {
|
|
56
|
-
problems.push({
|
|
72
|
+
problems.push({
|
|
73
|
+
kind: 'reference',
|
|
74
|
+
concept,
|
|
75
|
+
message: `${concept}: ${field} reference '${value}' → ${rel} does not exist`,
|
|
76
|
+
});
|
|
57
77
|
}
|
|
58
78
|
}
|
|
59
79
|
}
|
|
@@ -64,7 +84,10 @@ export const checkReferences = async (a: Analysis): Promise<Problem[]> => {
|
|
|
64
84
|
// Reference existence is a registry-wide concern, so it is skipped when a run is
|
|
65
85
|
// scoped to a subset of files (incremental PR checks) — only the file-level
|
|
66
86
|
// presence/vocab checks make sense there.
|
|
67
|
-
export const runCheck = async (
|
|
87
|
+
export const runCheck = async (
|
|
88
|
+
a: Analysis,
|
|
89
|
+
opts: { references?: boolean } = {},
|
|
90
|
+
): Promise<CheckResult> => {
|
|
68
91
|
const problems = [...checkPresence(a), ...checkVocab(a)];
|
|
69
92
|
if (opts.references !== false) problems.push(...(await checkReferences(a)));
|
|
70
93
|
return { ok: problems.length === 0, problems };
|
package/src/commands/coverage.ts
CHANGED
|
@@ -53,14 +53,21 @@ export const readBaseline = async (path: string): Promise<number | null> => {
|
|
|
53
53
|
try {
|
|
54
54
|
data = (await file.json()) as { unannotated?: number };
|
|
55
55
|
} catch {
|
|
56
|
-
throw new Error(
|
|
56
|
+
throw new Error(
|
|
57
|
+
`baseline at ${path} is not valid JSON — re-run: atlas coverage --update-baseline`,
|
|
58
|
+
);
|
|
57
59
|
}
|
|
58
60
|
return typeof data.unannotated === 'number' ? data.unannotated : null;
|
|
59
61
|
};
|
|
60
62
|
|
|
61
63
|
export const coverage = (a: Analysis): Coverage => {
|
|
62
64
|
const unannotated: string[] = [];
|
|
63
|
-
const uses = {
|
|
65
|
+
const uses = {
|
|
66
|
+
uncurated: [] as string[],
|
|
67
|
+
curatedEmpty: [] as string[],
|
|
68
|
+
proposed: [] as string[],
|
|
69
|
+
curated: [] as string[],
|
|
70
|
+
};
|
|
64
71
|
const unresolved: Coverage['unresolved'] = [];
|
|
65
72
|
|
|
66
73
|
for (const { path, annotation } of a.files) {
|
|
@@ -82,5 +89,11 @@ export const coverage = (a: Analysis): Coverage => {
|
|
|
82
89
|
}
|
|
83
90
|
}
|
|
84
91
|
|
|
85
|
-
return {
|
|
92
|
+
return {
|
|
93
|
+
total: a.files.length,
|
|
94
|
+
annotated: a.files.length - unannotated.length,
|
|
95
|
+
unannotated,
|
|
96
|
+
uses,
|
|
97
|
+
unresolved,
|
|
98
|
+
};
|
|
86
99
|
};
|
package/src/commands/generate.ts
CHANGED
|
@@ -15,10 +15,16 @@ export const generate = (a: Analysis): string => {
|
|
|
15
15
|
const byClass: Record<string, string[]> = {};
|
|
16
16
|
for (const concept of Object.keys(a.config.concepts)) {
|
|
17
17
|
const cls = conceptClass(concept) ?? 'other';
|
|
18
|
-
|
|
18
|
+
byClass[cls] ??= [];
|
|
19
|
+
byClass[cls].push(concept);
|
|
19
20
|
}
|
|
20
21
|
|
|
21
|
-
const lines: string[] = [
|
|
22
|
+
const lines: string[] = [
|
|
23
|
+
'# MAP',
|
|
24
|
+
'',
|
|
25
|
+
'_Generated by `atlas generate`. Do not edit by hand._',
|
|
26
|
+
'',
|
|
27
|
+
];
|
|
22
28
|
|
|
23
29
|
for (const cls of Object.keys(byClass).sort()) {
|
|
24
30
|
lines.push(`## ${cls}`, '');
|
|
@@ -33,7 +39,8 @@ export const generate = (a: Analysis): string => {
|
|
|
33
39
|
|
|
34
40
|
const members = g.conceptToFiles[concept] ?? [];
|
|
35
41
|
const counts: Record<string, number> = {};
|
|
36
|
-
for (const file of members)
|
|
42
|
+
for (const file of members)
|
|
43
|
+
for (const k of fileKinds[file] ?? []) counts[k] = (counts[k] ?? 0) + 1;
|
|
37
44
|
const breakdown = Object.keys(counts)
|
|
38
45
|
.sort()
|
|
39
46
|
.map((k) => `${k}(${counts[k]})`)
|
package/src/commands/graph.ts
CHANGED
package/src/commands/report.ts
CHANGED
|
Binary file
|
package/src/commands/stamp.ts
CHANGED
|
@@ -55,7 +55,9 @@ export const runStamp = async (
|
|
|
55
55
|
opts: { mode: StampMode; target?: string; write: boolean },
|
|
56
56
|
): Promise<StampResult> => {
|
|
57
57
|
const config = await loadConfig(root);
|
|
58
|
-
const paths = (await walkFiles(root, config.include, config.ignore)).filter((p) =>
|
|
58
|
+
const paths = (await walkFiles(root, config.include, config.ignore)).filter((p) =>
|
|
59
|
+
inScope(p, opts.target),
|
|
60
|
+
);
|
|
59
61
|
const files = await mapLimit(paths, IO_CONCURRENCY, async (path) => ({
|
|
60
62
|
path,
|
|
61
63
|
source: await Bun.file(resolve(root, path)).text(),
|
|
@@ -69,6 +71,7 @@ export const runStamp = async (
|
|
|
69
71
|
}
|
|
70
72
|
}
|
|
71
73
|
|
|
72
|
-
if (opts.write)
|
|
74
|
+
if (opts.write)
|
|
75
|
+
await mapLimit(changes, IO_CONCURRENCY, (c) => Bun.write(resolve(root, c.path), c.after));
|
|
73
76
|
return { changes, unresolved };
|
|
74
77
|
};
|
|
@@ -18,7 +18,9 @@ export const partOfFor = (category: string, capture: string): PartOfForDescripto
|
|
|
18
18
|
export const isPartOfFor = (v: unknown): v is PartOfForDescriptor => {
|
|
19
19
|
if (typeof v !== 'object' || v === null) return false;
|
|
20
20
|
const d = v as Partial<PartOfForDescriptor>;
|
|
21
|
-
return
|
|
21
|
+
return (
|
|
22
|
+
d.__atlasPartOfFor === true && typeof d.category === 'string' && typeof d.capture === 'string'
|
|
23
|
+
);
|
|
22
24
|
};
|
|
23
25
|
|
|
24
26
|
// A tag value is a literal string (with optional `$n` interpolation), a list of
|
|
@@ -27,6 +29,10 @@ export type TagValue = string | string[] | PartOfForDescriptor;
|
|
|
27
29
|
|
|
28
30
|
export type StampRule = {
|
|
29
31
|
include: string | string[];
|
|
32
|
+
// paths matching `exclude` are skipped by this rule — for positional overlaps
|
|
33
|
+
// where a broad capture (e.g. `modules/$1/**`) must not claim a nested grouping
|
|
34
|
+
// (e.g. `modules/admin/**`, which has its own rules).
|
|
35
|
+
exclude?: string | string[];
|
|
30
36
|
kind?: TagValue;
|
|
31
37
|
partOf?: TagValue;
|
|
32
38
|
constructs?: TagValue;
|
package/src/config/load.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { resolve } from 'node:path';
|
|
2
|
-
import { DEFAULT_KINDS } from '../vocab/kinds.ts';
|
|
3
2
|
import { DEFAULT_INCLUDE } from '../fs/walk.ts';
|
|
4
3
|
import type { ConceptRegistry } from '../registry/types.ts';
|
|
4
|
+
import { DEFAULT_KINDS } from '../vocab/kinds.ts';
|
|
5
5
|
import type { AtlasConfigInput, LoadedConfig } from './defineConfig.ts';
|
|
6
6
|
|
|
7
7
|
// Import a `.atlas/` file if it exists; missing files are optional (atlas ships
|
|
@@ -14,7 +14,11 @@ const loadModule = async (path: string): Promise<Record<string, unknown> | null>
|
|
|
14
14
|
// Pull a named export. A file that is PRESENT but exports none of `names` is a
|
|
15
15
|
// misconfiguration, not an "absent → use default" — throw loudly rather than
|
|
16
16
|
// silently degrading (e.g. an empty concept registry that passes CI against nothing).
|
|
17
|
-
const named = <T>(
|
|
17
|
+
const named = <T>(
|
|
18
|
+
mod: Record<string, unknown> | null,
|
|
19
|
+
file: string,
|
|
20
|
+
...names: string[]
|
|
21
|
+
): T | undefined => {
|
|
18
22
|
if (!mod) return undefined;
|
|
19
23
|
for (const n of names) if (mod[n] !== undefined) return mod[n] as T;
|
|
20
24
|
throw new Error(`.atlas/${file} exists but exports none of: ${names.join(', ')}`);
|
|
@@ -41,7 +45,9 @@ export const loadConfig = async (root: string): Promise<LoadedConfig> => {
|
|
|
41
45
|
for (const key of Object.keys(concepts)) {
|
|
42
46
|
const colon = key.indexOf(':');
|
|
43
47
|
if (key.length === 0 || colon === 0 || colon === key.length - 1) {
|
|
44
|
-
throw new Error(
|
|
48
|
+
throw new Error(
|
|
49
|
+
`.atlas/concepts.ts: malformed concept key '${key}' — use 'class:name' or a bare tag`,
|
|
50
|
+
);
|
|
45
51
|
}
|
|
46
52
|
}
|
|
47
53
|
|
package/src/config/stamp.ts
CHANGED
|
@@ -55,13 +55,22 @@ const resolveTag = (
|
|
|
55
55
|
};
|
|
56
56
|
|
|
57
57
|
// Compose EVERY matching rule's contributions for a file (not first-match-wins).
|
|
58
|
-
export const stampFor = (
|
|
58
|
+
export const stampFor = (
|
|
59
|
+
path: string,
|
|
60
|
+
rules: StampRule[],
|
|
61
|
+
registry: ConceptRegistry,
|
|
62
|
+
): ResolvedStamp => {
|
|
59
63
|
const kind: string[] = [];
|
|
60
64
|
const partOf: string[] = [];
|
|
61
65
|
const constructs: string[] = [];
|
|
62
66
|
const unresolved: { category: string; value: string }[] = [];
|
|
63
67
|
|
|
64
68
|
for (const rule of rules) {
|
|
69
|
+
if (rule.exclude) {
|
|
70
|
+
const excludes = Array.isArray(rule.exclude) ? rule.exclude : [rule.exclude];
|
|
71
|
+
if (excludes.some((pattern) => matchGlob(pattern, path))) continue;
|
|
72
|
+
}
|
|
73
|
+
|
|
65
74
|
const patterns = Array.isArray(rule.include) ? rule.include : [rule.include];
|
|
66
75
|
let caps: Captures | null = null;
|
|
67
76
|
for (const pattern of patterns) {
|
|
@@ -72,7 +81,8 @@ export const stampFor = (path: string, rules: StampRule[], registry: ConceptRegi
|
|
|
72
81
|
|
|
73
82
|
if (rule.kind) kind.push(...resolveTag(rule.kind, caps, registry, unresolved));
|
|
74
83
|
if (rule.partOf) partOf.push(...resolveTag(rule.partOf, caps, registry, unresolved));
|
|
75
|
-
if (rule.constructs)
|
|
84
|
+
if (rule.constructs)
|
|
85
|
+
constructs.push(...resolveTag(rule.constructs, caps, registry, unresolved));
|
|
76
86
|
}
|
|
77
87
|
|
|
78
88
|
return {
|
package/src/index.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
// Public API — what a consuming repo's `.atlas/` config imports.
|
|
2
|
-
|
|
3
|
-
export { type ConceptEntry, type ConceptRegistry, conceptClass, conceptClasses } from './registry/types.ts';
|
|
4
|
-
export { invert } from './registry/invert.ts';
|
|
2
|
+
|
|
5
3
|
export {
|
|
6
4
|
type AtlasConfigInput,
|
|
7
5
|
defineConfig,
|
|
@@ -14,3 +12,11 @@ export {
|
|
|
14
12
|
type TagValue,
|
|
15
13
|
} from './config/defineConfig.ts';
|
|
16
14
|
export { type AtlasAnnotation, parseAtlasBlock, type UsesState } from './parse/parseAtlasBlock.ts';
|
|
15
|
+
export { invert } from './registry/invert.ts';
|
|
16
|
+
export {
|
|
17
|
+
type ConceptEntry,
|
|
18
|
+
type ConceptRegistry,
|
|
19
|
+
conceptClass,
|
|
20
|
+
conceptClasses,
|
|
21
|
+
} from './registry/types.ts';
|
|
22
|
+
export { DEFAULT_KINDS, type DefaultKind } from './vocab/kinds.ts';
|
|
@@ -35,7 +35,9 @@ const OPENS_ATLAS = /(^|\n)\s*\*?\s*@atlas\b/;
|
|
|
35
35
|
|
|
36
36
|
// Locate the first block comment that opens with `@atlas`, returning its text
|
|
37
37
|
// and character span so the patcher can splice a regenerated block in place.
|
|
38
|
-
export const locateAtlasBlock = (
|
|
38
|
+
export const locateAtlasBlock = (
|
|
39
|
+
source: string,
|
|
40
|
+
): { start: number; end: number; text: string } | null => {
|
|
39
41
|
BLOCK_COMMENT.lastIndex = 0;
|
|
40
42
|
for (let m = BLOCK_COMMENT.exec(source); m !== null; m = BLOCK_COMMENT.exec(source)) {
|
|
41
43
|
if (OPENS_ATLAS.test(m[0])) {
|
|
@@ -89,7 +91,13 @@ export const parseAtlasBlock = (source: string): AtlasAnnotation | null => {
|
|
|
89
91
|
// from curated-empty (`@uses none` / a bare `@uses`).
|
|
90
92
|
const uses = dedupe(usesValues);
|
|
91
93
|
const usesState: UsesState =
|
|
92
|
-
uses.length > 0
|
|
94
|
+
uses.length > 0
|
|
95
|
+
? usesProposed
|
|
96
|
+
? 'proposed'
|
|
97
|
+
: 'values'
|
|
98
|
+
: usesNone || usesSeen
|
|
99
|
+
? 'none'
|
|
100
|
+
: 'absent';
|
|
93
101
|
if (usesSeen) axes.uses = uses;
|
|
94
102
|
|
|
95
103
|
return {
|
package/src/registry/invert.ts
CHANGED
|
@@ -13,7 +13,8 @@ export const invert = (registry: ConceptRegistry, field: string): Record<string,
|
|
|
13
13
|
const values = entry[field];
|
|
14
14
|
if (!values) continue;
|
|
15
15
|
for (const value of values) {
|
|
16
|
-
|
|
16
|
+
out[value] ??= [];
|
|
17
|
+
out[value].push(conceptKey);
|
|
17
18
|
}
|
|
18
19
|
}
|
|
19
20
|
for (const value of Object.keys(out)) out[value]!.sort();
|
package/src/registry/types.ts
CHANGED
|
@@ -18,4 +18,10 @@ export const conceptClass = (key: string): string | null => {
|
|
|
18
18
|
|
|
19
19
|
// The set of concept classes present in a registry (sorted, unique).
|
|
20
20
|
export const conceptClasses = (registry: ConceptRegistry): string[] =>
|
|
21
|
-
[
|
|
21
|
+
[
|
|
22
|
+
...new Set(
|
|
23
|
+
Object.keys(registry)
|
|
24
|
+
.map(conceptClass)
|
|
25
|
+
.filter((c): c is string => c !== null),
|
|
26
|
+
),
|
|
27
|
+
].sort();
|
package/src/render/html.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { ConceptGraph, CoverageReport } from '../commands/report.ts';
|
|
2
2
|
|
|
3
3
|
// JSON embedded in a <script> tag must not contain a literal </script> or a
|
|
4
4
|
// raw '<'; escaping '<' is sufficient and keeps it valid JSON.
|
package/src/render/markdown.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
|
-
import type { CoverageReport, Gaps
|
|
1
|
+
import type { ConceptGraph, CoverageReport, Gaps } from '../commands/report.ts';
|
|
2
2
|
|
|
3
3
|
// Injective sanitizer for Mermaid node ids: distinct concept ids never collide
|
|
4
4
|
// (encoding the char code keeps `feature:billing` and `feature.billing` apart).
|
|
5
|
-
export const safeId = (id: string): string =>
|
|
5
|
+
export const safeId = (id: string): string =>
|
|
6
|
+
id.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
|
|
6
7
|
|
|
7
8
|
// Escape a Mermaid quoted-label so a `"` in a concept id can't break the diagram
|
|
8
9
|
// or inject directives.
|
|
@@ -23,9 +24,13 @@ const totalsTable = (t: Gaps): string =>
|
|
|
23
24
|
].join('\n');
|
|
24
25
|
|
|
25
26
|
const pie = (t: Gaps): string =>
|
|
26
|
-
[
|
|
27
|
-
'
|
|
28
|
-
|
|
27
|
+
[
|
|
28
|
+
'```mermaid',
|
|
29
|
+
'pie title Annotation coverage',
|
|
30
|
+
` "annotated" : ${t.files - t.missingBlock}`,
|
|
31
|
+
` "missing block" : ${t.missingBlock}`,
|
|
32
|
+
'```',
|
|
33
|
+
].join('\n');
|
|
29
34
|
|
|
30
35
|
const categoryTable = (report: CoverageReport): string => {
|
|
31
36
|
const head = [
|
|
@@ -42,7 +47,11 @@ const categoryTable = (report: CoverageReport): string => {
|
|
|
42
47
|
const conceptGraph = (graph: ConceptGraph): string => {
|
|
43
48
|
const lines = ['```mermaid', 'graph LR'];
|
|
44
49
|
const byClass: Record<string, typeof graph.nodes> = {};
|
|
45
|
-
for (const n of graph.nodes)
|
|
50
|
+
for (const n of graph.nodes) {
|
|
51
|
+
const bucket = byClass[n.cls] ?? [];
|
|
52
|
+
byClass[n.cls] = bucket;
|
|
53
|
+
bucket.push(n);
|
|
54
|
+
}
|
|
46
55
|
for (const cls of Object.keys(byClass).sort()) {
|
|
47
56
|
lines.push(` subgraph ${cls}`);
|
|
48
57
|
for (const n of byClass[cls]!) lines.push(` ${safeId(n.id)}["${safeLabel(n.id)}"]`);
|
|
@@ -72,7 +81,10 @@ export const renderCoverageMarkdown = (report: CoverageReport, graph: ConceptGra
|
|
|
72
81
|
'Grouped by effective concept (declared `@partOf`, else the rules’ predicted concept). `@uses` columns',
|
|
73
82
|
'are curation signals, not failures.',
|
|
74
83
|
...(report.filesInMultipleConcepts > 0
|
|
75
|
-
? [
|
|
84
|
+
? [
|
|
85
|
+
'',
|
|
86
|
+
`> ${report.filesInMultipleConcepts} file(s) belong to multiple concepts, so the per-category file counts sum to more than the total.`,
|
|
87
|
+
]
|
|
76
88
|
: []),
|
|
77
89
|
'',
|
|
78
90
|
categoryTable(report),
|
package/src/stamp/patcher.ts
CHANGED
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
type AtlasAnnotation,
|
|
3
|
+
locateAtlasBlock,
|
|
4
|
+
parseAtlasBlock,
|
|
5
|
+
type UsesState,
|
|
6
|
+
} from '../parse/parseAtlasBlock.ts';
|
|
2
7
|
|
|
3
8
|
export type BlockSpec = {
|
|
4
9
|
kind?: string[];
|
|
@@ -82,7 +87,8 @@ export const applyStamp = (
|
|
|
82
87
|
// Overwrite is exempt on a pinned block — the hand-curated overload wins.
|
|
83
88
|
if (mode === 'overwrite' && existing.pinned) return { content: source, changed: false };
|
|
84
89
|
|
|
85
|
-
const pick = (next: string[] | undefined, prev: string[]): string[] =>
|
|
90
|
+
const pick = (next: string[] | undefined, prev: string[]): string[] =>
|
|
91
|
+
next && next.length ? next : prev;
|
|
86
92
|
|
|
87
93
|
const merged: BlockSpec =
|
|
88
94
|
mode === 'overwrite'
|
|
@@ -107,5 +113,8 @@ export const applyStamp = (
|
|
|
107
113
|
|
|
108
114
|
const block = renderWithEol(merged, eol);
|
|
109
115
|
if (block === located.text) return { content: source, changed: false };
|
|
110
|
-
return {
|
|
116
|
+
return {
|
|
117
|
+
content: source.slice(0, located.start) + block + source.slice(located.end),
|
|
118
|
+
changed: true,
|
|
119
|
+
};
|
|
111
120
|
};
|