@inixiative/atlas 0.1.0 → 0.2.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.
@@ -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: ['**/*.test.ts', '**/*.test.tsx', '**/tests/**', '**/index.ts', '**/*.d.ts', '**/*.gen.ts'],
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
- { include: ['apps/*/app/main.tsx', 'apps/*/app/client.tsx', 'apps/*/app/router.tsx'], kind: 'entrypoint' },
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.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "The map of the codebase — @atlas code annotations + a seam registry + a drift-proof MAP.md. A map that can only assert what is mechanically true.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -23,7 +23,7 @@
23
23
  "static-analysis"
24
24
  ],
25
25
  "bin": {
26
- "atlas": "./bin/atlas.ts"
26
+ "atlas": "bin/atlas.ts"
27
27
  },
28
28
  "exports": {
29
29
  ".": "./src/index.ts",
@@ -39,7 +39,11 @@
39
39
  "scripts": {
40
40
  "test": "bun test",
41
41
  "typecheck": "tsc --noEmit",
42
- "atlas": "bun run ./bin/atlas.ts"
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": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi"
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": "latest",
52
- "typescript": "^5.6.0"
55
+ "@biomejs/biome": "2.5.2",
56
+ "@inixiative/config": "^0.5.57",
57
+ "@types/bun": "1.4.2",
58
+ "lefthook": "2.1.9",
59
+ "typescript": "6.0.3"
53
60
  },
54
61
  "dependencies": {
55
- "@inixiative/json-rules": "^2.6.0"
56
- }
62
+ "@inixiative/json-rules": "^3.3.1"
63
+ },
64
+ "packageManager": "bun@1.4.2"
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 { buildCoverageReport, buildConceptGraph } from './commands/report.ts';
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
- flags[key] = next !== undefined && !next.startsWith('--') ? (i++, next) : '';
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 { version?: string; default?: { version?: string } };
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 (argv: string[], env: { cwd: string }): Promise<{ code: number; out: string }> => {
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') return { code: 0, out: 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 ? { ...full, files: full.files.filter((f) => inScope(f.path, target)) } : full;
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(`${warnOnly ? '⚠' : '✗'} atlas check: ${result.problems.length} problem(s)${warnOnly ? ' — warn-only' : ''}`);
121
- for (const p of result.problems) log(` [${p.kind}] ${p.file ?? p.concept ?? ''} — ${p.message}`);
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(root, (flags.baseline as string) || '.atlas/coverage-baseline.json');
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(baselinePath, `${JSON.stringify({ unannotated: c.unannotated.length }, null, 2)}\n`);
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) log(` unannotated (${c.unannotated.length}):\n${c.unannotated.map((f) => ` ${f}`).join('\n')}`);
161
- log(` @uses — curated ${c.uses.curated.length}, curated-empty ${c.uses.curatedEmpty.length}, proposed ${c.uses.proposed.length}, uncurated ${c.uses.uncurated.length}`);
162
- if (c.unresolved.length) log(` unresolved memberships (${c.unresolved.length}):\n${c.unresolved.map((u) => ` ${u.file}: ${u.category}:${u.value}`).join('\n')}`);
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()) log(` ${concept} (${g.conceptToFiles[concept]!.length})`);
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()) log(` ${concept} (${g.usesConsumers[concept]!.length})`);
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(resolve(outDir, 'COVERAGE.md'), renderCoverageMarkdown(report, conceptGraph));
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(`✓ wrote ${written.join(', ')} (${report.total.files - report.total.missingBlock}/${report.total.files} annotated)`);
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 ? ({ all: [flagRule, jsonRule] } as QueryRule) : (jsonRule ?? flagRule);
276
+ flagRule && jsonRule
277
+ ? ({ all: [flagRule, jsonRule] } as QueryRule)
278
+ : (jsonRule ?? flagRule);
241
279
  if (!rule) {
242
- log('query needs a json-rules predicate and/or at least one of --kind/--partOf/--uses/--path');
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(JSON.stringify({ changes: changes.map((c) => ({ path: c.path })), unresolved }, null, 2));
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(`${write ? 'Wrote' : 'Would change'} ${changes.length} file(s)${write ? '' : ' (dry-run — pass --write to apply)'}:`);
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(`⚠ ${unresolved.length} unresolved membership(s) — left unstamped (add the concept to .atlas/concepts.ts):`);
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
  }
@@ -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) if (!kinds.has(k)) problems.push({ kind: 'vocab', file: path, message: `unknown @kind '${k}'` });
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)) problems.push({ kind: 'vocab', file: path, message: `@partOf '${p}' is not a registered concept` });
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)) problems.push({ kind: 'vocab', file: path, message: `@uses '${u}' is not a registered concept` });
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({ kind: 'reference', concept, message: `${concept}: ${field} resolver threw on '${value}': ${msg}` });
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({ kind: 'reference', concept, message: `${concept}: ${field} reference '${value}' → ${rel} does not exist` });
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 (a: Analysis, opts: { references?: boolean } = {}): Promise<CheckResult> => {
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 };
@@ -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(`baseline at ${path} is not valid JSON — re-run: atlas coverage --update-baseline`);
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 = { uncurated: [] as string[], curatedEmpty: [] as string[], proposed: [] as string[], curated: [] as string[] };
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 { total: a.files.length, annotated: a.files.length - unannotated.length, unannotated, uses, unresolved };
92
+ return {
93
+ total: a.files.length,
94
+ annotated: a.files.length - unannotated.length,
95
+ unannotated,
96
+ uses,
97
+ unresolved,
98
+ };
86
99
  };
@@ -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
- (byClass[cls] ??= []).push(concept);
18
+ byClass[cls] ??= [];
19
+ byClass[cls].push(concept);
19
20
  }
20
21
 
21
- const lines: string[] = ['# MAP', '', '_Generated by `atlas generate`. Do not edit by hand._', ''];
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) for (const k of fileKinds[file] ?? []) counts[k] = (counts[k] ?? 0) + 1;
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]})`)
@@ -12,7 +12,8 @@ export type Graph = {
12
12
  };
13
13
 
14
14
  const push = (rec: Record<string, string[]>, key: string, val: string): void => {
15
- (rec[key] ??= []).push(val);
15
+ rec[key] ??= [];
16
+ rec[key].push(val);
16
17
  };
17
18
 
18
19
  export const graph = (a: Analysis): Graph => {
Binary file
@@ -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) => inScope(p, opts.target));
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) await mapLimit(changes, IO_CONCURRENCY, (c) => Bun.write(resolve(root, c.path), c.after));
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 d.__atlasPartOfFor === true && typeof d.category === 'string' && typeof d.capture === 'string';
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
@@ -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>(mod: Record<string, unknown> | null, file: string, ...names: string[]): T | undefined => {
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(`.atlas/concepts.ts: malformed concept key '${key}' — use 'class:name' or a bare tag`);
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
 
@@ -55,7 +55,11 @@ 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 = (path: string, rules: StampRule[], registry: ConceptRegistry): ResolvedStamp => {
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[] = [];
@@ -77,7 +81,8 @@ export const stampFor = (path: string, rules: StampRule[], registry: ConceptRegi
77
81
 
78
82
  if (rule.kind) kind.push(...resolveTag(rule.kind, caps, registry, unresolved));
79
83
  if (rule.partOf) partOf.push(...resolveTag(rule.partOf, caps, registry, unresolved));
80
- if (rule.constructs) constructs.push(...resolveTag(rule.constructs, caps, registry, unresolved));
84
+ if (rule.constructs)
85
+ constructs.push(...resolveTag(rule.constructs, caps, registry, unresolved));
81
86
  }
82
87
 
83
88
  return {
package/src/index.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  // Public API — what a consuming repo's `.atlas/` config imports.
2
- export { DEFAULT_KINDS, type DefaultKind } from './vocab/kinds.ts';
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 = (source: string): { start: number; end: number; text: string } | null => {
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 ? (usesProposed ? 'proposed' : 'values') : usesNone || usesSeen ? 'none' : 'absent';
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 {
@@ -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
- (out[value] ??= []).push(conceptKey);
16
+ out[value] ??= [];
17
+ out[value].push(conceptKey);
17
18
  }
18
19
  }
19
20
  for (const value of Object.keys(out)) out[value]!.sort();
@@ -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
- [...new Set(Object.keys(registry).map(conceptClass).filter((c): c is string => c !== null))].sort();
21
+ [
22
+ ...new Set(
23
+ Object.keys(registry)
24
+ .map(conceptClass)
25
+ .filter((c): c is string => c !== null),
26
+ ),
27
+ ].sort();
@@ -1,4 +1,4 @@
1
- import type { CoverageReport, ConceptGraph } from '../commands/report.ts';
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.
@@ -1,8 +1,9 @@
1
- import type { CoverageReport, Gaps, ConceptGraph } from '../commands/report.ts';
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 => id.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
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
- ['```mermaid', 'pie title Annotation coverage', ` "annotated" : ${t.files - t.missingBlock}`, ` "missing block" : ${t.missingBlock}`, '```'].join(
27
- '\n',
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) (byClass[n.cls] ??= []).push(n);
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
- ? ['', `> ${report.filesInMultipleConcepts} file(s) belong to multiple concepts, so the per-category file counts sum to more than the total.`]
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),
@@ -1,4 +1,9 @@
1
- import { type AtlasAnnotation, locateAtlasBlock, parseAtlasBlock, type UsesState } from '../parse/parseAtlasBlock.ts';
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[] => (next && next.length ? next : prev);
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 { content: source.slice(0, located.start) + block + source.slice(located.end), changed: true };
116
+ return {
117
+ content: source.slice(0, located.start) + block + source.slice(located.end),
118
+ changed: true,
119
+ };
111
120
  };