@inixiative/atlas 0.3.0 → 0.4.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/README.md CHANGED
@@ -44,7 +44,8 @@ repo **owns** its concept registry.
44
44
  .atlas/
45
45
  config.ts // stamp rules (path → tags) + ignore + reference resolvers
46
46
  kinds.ts // @kind vocab — extends atlas's defaults
47
- concepts.ts // the concept registry — repo-OWNED, structure only
47
+ concepts.ts // the concept registry — repo-OWNED, structure only
48
+ thesaurus.ts // optional: per concept, the phrases people search with + its doc (see Thesaurus)
48
49
  ```
49
50
 
50
51
  ```ts
@@ -74,13 +75,14 @@ export default defineConfig({
74
75
  ```
75
76
 
76
77
  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
+ [`examples/atlas-config/`](./examples/atlas-config/) (`kinds.ts`, `concepts.ts`, `config.ts`,
79
+ `thesaurus.ts`).
78
80
 
79
81
  ## CLI
80
82
 
81
83
  ```bash
82
84
  atlas graph # reverse indexes: concept → files, file → concepts, doc → concepts
83
- atlas check # presence + vocab existence + reference existence (the CI command)
85
+ atlas check # presence + vocab + reference + thesaurus existence (the CI command)
84
86
  atlas coverage # unannotated files; @uses curation buckets; unresolved memberships
85
87
  atlas generate # write MAP.md from the annotated tree
86
88
  atlas report # coverage gaps + concept graph → COVERAGE.md (Mermaid) and atlas.html (Cytoscape)
@@ -132,8 +134,9 @@ primitive:testFactories — 2 other file(s), 1 consumer(s) via @uses; `bunx atla
132
134
  ```
133
135
 
134
136
  A file of `@kind factory` or `@kind constructor` also gets a line counting that kind in its
135
- concept (`REACH_KINDS`). On Grep, the pattern's longest identifier is matched against concept
136
- names and the matching concepts' files are listed.
137
+ concept (`REACH_KINDS`). On Grep, the pattern is matched first against the
138
+ [thesaurus](#thesaurus), then its longest identifier against concept names, and the matching
139
+ concepts' files are listed.
137
140
 
138
141
  Install them with `atlas setup` (asks first; `atlas setup --yes` for scripts and agents). It
139
142
  merges two `PostToolUse` entries into `.claude/settings.json`, leaves every other key and hook as it
@@ -177,13 +180,84 @@ How they behave:
177
180
  - **The owning `.atlas/` is the one above the file**, so a file in a worktree maps against that
178
181
  worktree's config even when the session runs from the main checkout.
179
182
  - **Cached graph.** The graph is built with atlas's own `analyze` and cached per repo root in the
180
- OS temp dir for 10 minutes, keyed by atlas version and rebuilt early when a `.atlas/` file
181
- changes.
183
+ OS temp dir for 10 minutes, keyed by atlas version and rebuilt early when any `.atlas/` file
184
+ (`thesaurus.ts` included) changes.
182
185
  - **Harness-agnostic core.** `renderNeighbourhood(graph, relPath)` and
183
186
  `renderConceptMatches(graph, pattern)` return plain text; `runClaudeCodeHook` is the Claude Code
184
187
  adapter (stdin JSON in, `hookSpecificOutput.additionalContext` out). Another harness needs only
185
188
  its own adapter.
186
189
 
190
+ ### Thesaurus
191
+
192
+ A grep for the job ("seed a user", "lock", "factory") names no concept, so the grep hook used to
193
+ say nothing at exactly the moment an agent was looking for something that already exists. The
194
+ thesaurus sits beside the registry and makes those searches land. Like a book's thesaurus it is
195
+ keyed by the thing, not the word: each concept lists the phrases people search with when they mean
196
+ it, and where its doc is, so a hit also says where to read.
197
+
198
+ ```ts
199
+ // .atlas/thesaurus.ts — optional. Keyed by concept id from concepts.ts.
200
+ import type { Thesaurus } from '@inixiative/atlas';
201
+
202
+ export const THESAURUS: Thesaurus = {
203
+ 'primitive:testFactories': {
204
+ phrases: ['seed a user', 'factory', 'fixture'],
205
+ doc: 'TESTING.md#factories', // optional: a `docs:` value + optional #section
206
+ },
207
+ 'primitive:mutex': { phrases: ['lock', 'serialize'] }, // doc defaults to the concept's first `docs:`
208
+ };
209
+ ```
210
+
211
+ `doc` takes the same value a `docs:` entry in `concepts.ts` does and goes through the same
212
+ `references.docs` resolver (as written when there is none); a `#section` is kept on the end. Leave
213
+ it out and the concept's first `docs:` entry is used, so a doc is never written twice.
214
+
215
+ Matching is case-insensitive and on whole words or phrases:
216
+
217
+ - **Words, in order.** One alternative of the pattern spells the phrase in consecutive whole words,
218
+ compared joined: camelCase and `snake_case` split, `a`/`an`/`the`/`to`/`of`/`for` ignored.
219
+ `seedUser` and `seed_user` match "seed a user", `acquireLock` matches "lock",
220
+ `createGitHubClient` matches "github". `unlock`, `lockfile` and `seed|user` (two alternatives)
221
+ match nothing. Only an unescaped `|`, `(` or `)` separates alternatives.
222
+ - **Conjugations.** Each phrase word also matches its simple English inflections: `-s`, `-es`,
223
+ `-ing`, `-ed`, `-er`; a final `e` dropped before `-ing`/`-ed`/`-er`; a final consonant after a
224
+ single vowel doubled (`log` → `logging`, `logger`; `stop` → `stopped`); a consonant + `y` becoming
225
+ `-ies`/`-ied`. So "lock" matches `locks`, `locking`, `locked`, `locker`; "serialize" matches
226
+ `serializing`, `serialized`; "factory" matches `factories`. A three-letter word keeps its `e`
227
+ before `-er`, so "use" matches `using` and `used` but not `user`. It is a suffix rule, not a
228
+ stemmer, and stays whole-word: `unlocked`, `blocking` and `serializable` don't match. Write
229
+ phrases in their base form.
230
+ - **The pattern as a regex.** The pattern matches the whole phrase (`seed.*user`, `factor(y|ies)`),
231
+ provided one of its own literal words of three or more letters starts a word of the phrase, so
232
+ `.*` matches nothing and `lock|.*` reaches "lock the door" but not "unlock the door". This
233
+ reading follows regex semantics rather than whole words, and is skipped for patterns over 200
234
+ characters, nested quantifiers, more than four unbounded quantifiers, and syntax JavaScript can't
235
+ parse.
236
+
237
+ Thesaurus hits are listed first, labelled with the phrase so the agent knows a person made the
238
+ mapping, with a `read:` line pointing at the doc; past eight concepts the rest are counted, not
239
+ listed. Then come the concept-name matches not already shown:
240
+
241
+ ```
242
+ atlas concept(s) matching "seeding.*users?":
243
+
244
+ primitive:testFactories (thesaurus "seed a user") — 3 file(s), 1 consumer(s) via @uses; `bunx atlas query --partOf primitive:testFactories` lists all
245
+ read: docs/claude/TESTING.md#factories
246
+ src/test/factories/buildFactory.ts
247
+ src/test/factories/organizationFactory.ts
248
+ src/test/factories/userFactory.ts
249
+ ```
250
+
251
+ `atlas check` flags an entry for a concept the registry doesn't have, an empty phrase list, an empty
252
+ phrase (one with no letter or digit), and a `doc` whose file doesn't resolve to a real file; a
253
+ scoped `atlas check <target>` skips the doc check like the other reference checks. `loadConfig`
254
+ refuses an entry with any key besides `phrases` and `doc`, so a `docs:` typo can't silently fall
255
+ back to the default doc. Whether a phrase is apt is the curator's call.
256
+
257
+ **Keeping it up:** when a search misses and you later find the thing, add the words you searched
258
+ with to that concept's phrases. Phrases come from how people describe the job, never from a test
259
+ case's expected answer: a thesaurus tuned to its tests only teaches the tests.
260
+
187
261
  ## Visualize
188
262
 
189
263
  `atlas report` emits two artifacts:
@@ -1,6 +1,6 @@
1
1
  # Example `.atlas/` config
2
2
 
3
- Copy these three files into a **`.atlas/`** folder at your repo root, then adjust them to your
3
+ Copy these files into a **`.atlas/`** folder at your repo root, then adjust them to your
4
4
  layout. This is the entire configuration surface — atlas ships the `@kind` defaults; **your repo
5
5
  owns the concept registry.**
6
6
 
@@ -9,6 +9,7 @@ owns the concept registry.**
9
9
  kinds.ts # @kind vocab — atlas's defaults, extended with any roles you add
10
10
  concepts.ts # the concept registry — repo-OWNED, structure only (the one you'll edit most)
11
11
  config.ts # stamp rules (path → tags), ignore globs, and reference resolvers
12
+ thesaurus.ts # optional: per concept, the phrases people search with + its doc, for `atlas hook grep`
12
13
  ```
13
14
 
14
15
  The key idea: atlas hardcodes **no** concept classes (`feature`/`primitive`/…) and **no** constituent
@@ -21,6 +22,7 @@ concept that exists, that a `@kind` is in your vocab, and that referenced docs r
21
22
  | [`concepts.ts`](./concepts.ts) | constantly | add a concept when you add a feature/primitive; list its constituent folders so `@partOf` auto-fills |
22
23
  | [`config.ts`](./config.ts) | rarely | structural globs → `@kind`; capture globs → `@partOf` via membership |
23
24
  | [`kinds.ts`](./kinds.ts) | rarely | only when a role the defaults don't cover shows up |
25
+ | [`thesaurus.ts`](./thesaurus.ts) | when a search misses | add the words you searched with to the concept you found |
24
26
 
25
27
  After copying, `bunx atlas stamp --write` fills `@kind`/`@partOf` from the rules, `bunx atlas check`
26
28
  gates it, and `bunx atlas generate` writes `MAP.md`.
@@ -0,0 +1,21 @@
1
+ import type { Thesaurus } from '@inixiative/atlas';
2
+
3
+ // The thesaurus — optional, keyed by concept. Each concept lists the phrases people search
4
+ // with when they mean it, so `atlas hook grep` lands on it for "send an email" or "queue"
5
+ // even though no concept is named that, and points the agent at where to read.
6
+ //
7
+ // `doc` is a `docs:` value as concepts.ts writes it (run through `references.docs`) plus an
8
+ // optional `#section`. Leave it out to use the concept's first `docs:` entry.
9
+ // Write phrases in their base form: "lock" also matches locks, locking, locked.
10
+ //
11
+ // Upkeep: when a search misses and you later find the thing, add the words you searched
12
+ // with to that concept's phrases. Phrases come from how people describe the job, never from
13
+ // a test's expected answer.
14
+ export const THESAURUS: Thesaurus = {
15
+ 'feature:email': { phrases: ['send an email', 'mail'], doc: 'COMMUNICATIONS.md#sending' },
16
+ 'feature:billing': { phrases: ['invoice', 'charge a customer'] },
17
+ 'feature:featureFlags': { phrases: ['feature flag', 'toggle'] },
18
+ 'primitive:authz': { phrases: ['permission', 'authorize'] },
19
+ 'primitive:caching': { phrases: ['memoize', 'cache'] },
20
+ 'primitive:jobs': { phrases: ['background job', 'queue', 'schedule'] },
21
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inixiative/atlas",
3
- "version": "0.3.0",
3
+ "version": "0.4.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",
@@ -53,7 +53,7 @@
53
53
  },
54
54
  "devDependencies": {
55
55
  "@biomejs/biome": "2.5.2",
56
- "@inixiative/config": "^0.5.102",
56
+ "@inixiative/config": "^0.5.115",
57
57
  "@types/bun": "1.4.2",
58
58
  "lefthook": "2.1.9",
59
59
  "typescript": "6.0.3"
package/src/cli.ts CHANGED
@@ -18,7 +18,7 @@ Usage: atlas <command> [target] [flags]
18
18
 
19
19
  Commands:
20
20
  graph reverse indexes: concept → files, file → concepts, doc → concepts
21
- check [target] presence + vocab + reference existence (the CI command);
21
+ check [target] presence + vocab + reference + thesaurus existence (the CI command);
22
22
  a target scopes to a path and skips registry-wide reference checks
23
23
  coverage unannotated files; @uses curation buckets; unresolved memberships
24
24
  gate with --min <pct> and/or --ratchet (vs a committed baseline)
@@ -1,11 +1,14 @@
1
1
  import { resolve } from 'node:path';
2
2
  import type { Analysis } from '../analyze.ts';
3
+ import type { ReferenceResolver } from '../config/defineConfig.ts';
4
+ import { splitDoc } from './graph.ts';
3
5
 
4
6
  // Enforcement is EXISTENCE, not correctness: presence of a block, validity of
5
- // the vocabulary used, and existence of referenced docs. atlas never
7
+ // the vocabulary used, existence of referenced docs, and thesaurus entries that
8
+ // name real concepts. atlas never
6
9
  // checks "is this @partOf actually true" or any derived status — fool's errands.
7
10
  export type Problem = {
8
- kind: 'presence' | 'vocab' | 'reference';
11
+ kind: 'presence' | 'vocab' | 'reference' | 'thesaurus';
9
12
  file?: string;
10
13
  concept?: string;
11
14
  message: string;
@@ -48,47 +51,91 @@ export const checkVocab = (a: Analysis): Problem[] => {
48
51
  return problems;
49
52
  };
50
53
 
54
+ // Resolve one reference value and confirm the file exists. The resolver is consumer code — a
55
+ // throw is reported, never an unhandled crash of the whole check.
56
+ type MissingReference = { rel: string } | { threw: string } | undefined;
57
+
58
+ const missingReference = async (
59
+ root: string,
60
+ resolver: ReferenceResolver,
61
+ value: string,
62
+ ): Promise<MissingReference> => {
63
+ let rel: string;
64
+ try {
65
+ rel = resolver(value);
66
+ } catch (err) {
67
+ return { threw: err instanceof Error ? err.message : String(err) };
68
+ }
69
+ return (await Bun.file(resolve(root, rel)).exists()) ? undefined : { rel };
70
+ };
71
+
51
72
  // reference existence — a concept's doc paths resolve to real files.
52
73
  export const checkReferences = async (a: Analysis): Promise<Problem[]> => {
53
74
  const problems: Problem[] = [];
54
75
  for (const [concept, entry] of Object.entries(a.config.concepts)) {
55
76
  for (const [field, resolver] of Object.entries(a.config.references)) {
56
77
  for (const value of entry[field] ?? []) {
57
- // The resolver is consumer code — a throw becomes a structured problem,
58
- // never an unhandled crash of the whole check.
59
- let rel: string;
60
- try {
61
- rel = resolver(value);
62
- } catch (err) {
63
- const msg = err instanceof Error ? err.message : String(err);
64
- problems.push({
65
- kind: 'reference',
66
- concept,
67
- message: `${concept}: ${field} resolver threw on '${value}': ${msg}`,
68
- });
69
- continue;
70
- }
71
- if (!(await Bun.file(resolve(a.root, rel)).exists())) {
72
- problems.push({
73
- kind: 'reference',
74
- concept,
75
- message: `${concept}: ${field} reference '${value}' → ${rel} does not exist`,
76
- });
77
- }
78
+ const missing = await missingReference(a.root, resolver, value);
79
+ if (!missing) continue;
80
+ problems.push({
81
+ kind: 'reference',
82
+ concept,
83
+ message:
84
+ 'threw' in missing
85
+ ? `${concept}: ${field} resolver threw on '${value}': ${missing.threw}`
86
+ : `${concept}: ${field} reference '${value}' → ${missing.rel} does not exist`,
87
+ });
78
88
  }
79
89
  }
80
90
  }
81
91
  return problems;
82
92
  };
83
93
 
94
+ const THESAURUS_FILE = '.atlas/thesaurus.ts';
95
+
96
+ // thesaurus existence — every entry is a registered concept with at least one non-blank
97
+ // phrase, and its own `doc` (the file part, before any `#section`) resolves to a real file
98
+ // through the same `references.docs` resolver. The doc check is a reference check, so a
99
+ // scoped run skips it like the others. A defaulted doc is a `docs:` entry that
100
+ // checkReferences already covers. Whether a phrase is *apt* is the curator's call.
101
+ export const checkThesaurus = async (
102
+ a: Analysis,
103
+ opts: { references?: boolean } = {},
104
+ ): Promise<Problem[]> => {
105
+ const concepts = new Set(Object.keys(a.config.concepts));
106
+ const resolver = a.config.references.docs ?? ((value: string) => value);
107
+ const problems: Problem[] = [];
108
+ const flag = (concept: string, message: string) =>
109
+ problems.push({ kind: 'thesaurus', file: THESAURUS_FILE, concept, message });
110
+ for (const [concept, { phrases, doc }] of Object.entries(a.config.thesaurus)) {
111
+ if (!concepts.has(concept))
112
+ flag(concept, `thesaurus names '${concept}', which is not a registered concept`);
113
+ if (phrases.length === 0) flag(concept, `thesaurus entry '${concept}' has no phrases`);
114
+ // A phrase with no letter or digit can never match a search.
115
+ if (phrases.some((phrase) => !/[\p{L}\p{N}]/u.test(phrase)))
116
+ flag(concept, `thesaurus entry '${concept}' has an empty phrase`);
117
+ if (doc !== undefined && opts.references !== false) {
118
+ const missing = await missingReference(a.root, resolver, splitDoc(doc).file);
119
+ if (missing)
120
+ flag(
121
+ concept,
122
+ 'threw' in missing
123
+ ? `thesaurus entry '${concept}': docs resolver threw on doc '${doc}': ${missing.threw}`
124
+ : `thesaurus entry '${concept}': doc '${doc}' → ${missing.rel} does not exist`,
125
+ );
126
+ }
127
+ }
128
+ return problems;
129
+ };
130
+
84
131
  // Reference existence is a registry-wide concern, so it is skipped when a run is
85
- // scoped to a subset of files (incremental PR checks) — only the file-level
86
- // presence/vocab checks make sense there.
132
+ // scoped to a subset of files (incremental PR checks). The thesaurus shape checks stay on:
133
+ // they read only `.atlas/` config, which is whole in every run.
87
134
  export const runCheck = async (
88
135
  a: Analysis,
89
136
  opts: { references?: boolean } = {},
90
137
  ): Promise<CheckResult> => {
91
- const problems = [...checkPresence(a), ...checkVocab(a)];
138
+ const problems = [...checkPresence(a), ...checkVocab(a), ...(await checkThesaurus(a, opts))];
92
139
  if (opts.references !== false) problems.push(...(await checkReferences(a)));
93
140
  return { ok: problems.length === 0, problems };
94
141
  };
@@ -38,12 +38,12 @@ export const generate = (a: Analysis): string => {
38
38
  }
39
39
 
40
40
  const members = g.conceptToFiles[concept] ?? [];
41
- const counts: Record<string, number> = {};
41
+ const counts = new Map<string, number>();
42
42
  for (const file of members)
43
- for (const k of fileKinds[file] ?? []) counts[k] = (counts[k] ?? 0) + 1;
44
- const breakdown = Object.keys(counts)
43
+ for (const k of fileKinds[file] ?? []) counts.set(k, (counts.get(k) ?? 0) + 1);
44
+ const breakdown = [...counts.keys()]
45
45
  .sort()
46
- .map((k) => `${k}(${counts[k]})`)
46
+ .map((k) => `${k}(${counts.get(k)})`)
47
47
  .join(', ');
48
48
  lines.push(`- files (${members.length})${breakdown ? `: ${breakdown}` : ''}`);
49
49
  for (const file of members) lines.push(` - ${file} — ${(fileKinds[file] ?? []).join(', ')}`);
@@ -9,6 +9,7 @@ export type Graph = {
9
9
  usesConsumers: Record<string, string[]>; // via @uses (dependency)
10
10
  fileToConcepts: Record<string, { kind: string[]; partOf: string[]; uses: string[] }>;
11
11
  docToConcepts: Record<string, string[]>;
12
+ thesaurus: Record<string, { phrases: string[]; doc?: string }>; // doc resolved to a repo path
12
13
  };
13
14
 
14
15
  const push = (rec: Record<string, string[]>, key: string, val: string): void => {
@@ -16,6 +17,31 @@ const push = (rec: Record<string, string[]>, key: string, val: string): void =>
16
17
  rec[key].push(val);
17
18
  };
18
19
 
20
+ // Split `FILE.md#section` so only the file goes through the `references.docs` resolver.
21
+ export const splitDoc = (doc: string): { file: string; section?: string } => {
22
+ const hash = doc.indexOf('#');
23
+ return hash < 0 ? { file: doc } : { file: doc.slice(0, hash), section: doc.slice(hash + 1) };
24
+ };
25
+
26
+ // The doc a thesaurus entry points at, as a repo path: its own `doc`, else the concept's first
27
+ // `docs:` entry, through the same resolver `atlas check` uses (identity when none is set).
28
+ const resolvedThesaurus = (a: Analysis): Graph['thesaurus'] => {
29
+ const resolver = a.config.references.docs ?? ((value: string) => value);
30
+ return Object.fromEntries(
31
+ Object.entries(a.config.thesaurus).map(([concept, entry]) => {
32
+ const doc = entry.doc ?? a.config.concepts[concept]?.docs?.[0];
33
+ if (doc === undefined) return [concept, { phrases: entry.phrases }];
34
+ const { file, section } = splitDoc(doc);
35
+ try {
36
+ const path = resolver(file);
37
+ return [concept, { phrases: entry.phrases, doc: section ? `${path}#${section}` : path }];
38
+ } catch {
39
+ return [concept, { phrases: entry.phrases }]; // `atlas check` reports the throw
40
+ }
41
+ }),
42
+ );
43
+ };
44
+
19
45
  export const graph = (a: Analysis): Graph => {
20
46
  const conceptToFiles: Record<string, string[]> = {};
21
47
  const usesConsumers: Record<string, string[]> = {};
@@ -39,5 +65,6 @@ export const graph = (a: Analysis): Graph => {
39
65
  usesConsumers,
40
66
  fileToConcepts,
41
67
  docToConcepts: invert(a.config.concepts, 'docs'),
68
+ thesaurus: resolvedThesaurus(a),
42
69
  };
43
70
  };
@@ -1,4 +1,4 @@
1
- import type { ConceptRegistry } from '../registry/types.ts';
1
+ import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
2
2
 
3
3
  // `partOfFor` is a LAZY descriptor, not a value. The consumer's config.ts can
4
4
  // reference it before the concept registry is loaded; the stamp engine resolves it
@@ -62,4 +62,5 @@ export const defineConfig = (config: AtlasConfigInput): AtlasConfigInput => conf
62
62
  export type LoadedConfig = ConfigDefaults & {
63
63
  kinds: readonly string[];
64
64
  concepts: ConceptRegistry;
65
+ thesaurus: Thesaurus;
65
66
  };
@@ -1,6 +1,6 @@
1
1
  import { resolve } from 'node:path';
2
2
  import { DEFAULT_INCLUDE } from '../fs/walk.ts';
3
- import type { ConceptRegistry } from '../registry/types.ts';
3
+ import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
4
4
  import { DEFAULT_KINDS } from '../vocab/kinds.ts';
5
5
  import type { AtlasConfigInput, LoadedConfig } from './defineConfig.ts';
6
6
 
@@ -24,19 +24,21 @@ const named = <T>(
24
24
  throw new Error(`.atlas/${file} exists but exports none of: ${names.join(', ')}`);
25
25
  };
26
26
 
27
- // Load the consumer's `.atlas/` config: kinds → concepts → config (no
27
+ // Load the consumer's `.atlas/` config: kinds → concepts → thesaurus → config (no
28
28
  // evaluation-order coupling, since partOfFor is a lazy descriptor). atlas ships
29
- // the kinds defaults; the repo OWNS concepts.ts.
29
+ // the kinds defaults; the repo OWNS concepts.ts and the optional thesaurus.ts.
30
30
  export const loadConfig = async (root: string): Promise<LoadedConfig> => {
31
31
  const dir = resolve(root, '.atlas');
32
- const [kindsMod, conceptsMod, configMod] = await Promise.all([
32
+ const [kindsMod, conceptsMod, thesaurusMod, configMod] = await Promise.all([
33
33
  loadModule(resolve(dir, 'kinds.ts')),
34
34
  loadModule(resolve(dir, 'concepts.ts')),
35
+ loadModule(resolve(dir, 'thesaurus.ts')),
35
36
  loadModule(resolve(dir, 'config.ts')),
36
37
  ]);
37
38
 
38
39
  const kinds = named<readonly string[]>(kindsMod, 'kinds.ts', 'KINDS', 'default') ?? DEFAULT_KINDS;
39
40
  const concepts = named<ConceptRegistry>(conceptsMod, 'concepts.ts', 'CONCEPTS', 'default') ?? {};
41
+ const thesaurus = named<Thesaurus>(thesaurusMod, 'thesaurus.ts', 'THESAURUS', 'default') ?? {};
40
42
  const cfg = named<AtlasConfigInput>(configMod, 'config.ts', 'default', 'config') ?? {};
41
43
 
42
44
  // Concept keys are either `class:name` (a layer member) or a bare classless
@@ -51,9 +53,27 @@ export const loadConfig = async (root: string): Promise<LoadedConfig> => {
51
53
  }
52
54
  }
53
55
 
56
+ // A malformed entry would be read character by character downstream; refuse it here.
57
+ for (const [concept, entry] of Object.entries(thesaurus)) {
58
+ const { phrases, doc, ...rest } = (entry ?? {}) as Partial<Record<string, unknown>>;
59
+ if (
60
+ typeof entry !== 'object' ||
61
+ entry === null ||
62
+ Object.keys(rest).length > 0 || // a `docs:` typo would silently fall back to the default doc
63
+ !Array.isArray(phrases) ||
64
+ phrases.some((phrase) => typeof phrase !== 'string') ||
65
+ (doc !== undefined && typeof doc !== 'string')
66
+ ) {
67
+ throw new Error(
68
+ `.atlas/thesaurus.ts: '${concept}' must be { phrases: string[]; doc?: string }`,
69
+ );
70
+ }
71
+ }
72
+
54
73
  return {
55
74
  kinds,
56
75
  concepts,
76
+ thesaurus,
57
77
  stamp: cfg.stamp ?? [],
58
78
  ignore: cfg.ignore ?? [],
59
79
  include: cfg.include ?? DEFAULT_INCLUDE,
@@ -14,6 +14,8 @@ export const REACH_KINDS: readonly string[] = ['factory', 'constructor'];
14
14
  const SIBLING_SAMPLE = 12;
15
15
  const MAX_CONCEPT_FILES = 20;
16
16
  const MIN_TOKEN = 4;
17
+ const MAX_THESAURUS_CONCEPTS = 8;
18
+ const MAX_QUOTED_PATTERN = 80;
17
19
 
18
20
  // The owning `.atlas/` is the one above the file, not the session cwd: the file may
19
21
  // live in a worktree while the session runs from the main checkout.
@@ -97,34 +99,191 @@ export const identifierToken = (pattern: string): string | undefined => {
97
99
  return longest && longest.length >= MIN_TOKEN ? longest : undefined;
98
100
  };
99
101
 
100
- // The grep-side lookup: concepts whose name the pattern's identifier names (exactly,
101
- // or as a prefix either way once both are long enough to mean something).
102
+ // Words a phrase carries no meaning in: "seed a user" and `seedUser` are the same search.
103
+ const FILLER = new Set(['a', 'an', 'the', 'to', 'of', 'for']);
104
+
105
+ // The lowercase words of a phrase or identifier: camelCase and regex escapes (`\b`, `\w`)
106
+ // split, punctuation and regex syntax dropped. Filler words go unless they are all there is.
107
+ const wordsOf = (text: string): string[] => {
108
+ const words = (
109
+ text
110
+ .replace(/\\[A-Za-z]/g, ' ')
111
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
112
+ .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
113
+ .match(/[\p{L}\p{N}]+/gu) ?? []
114
+ ).map((word) => word.toLowerCase());
115
+ const meaningful = words.filter((word) => !FILLER.has(word));
116
+ return meaningful.length > 0 ? meaningful : words;
117
+ };
118
+
119
+ // The conjugations a search may use for a word, by a small suffix rule (no stemmer): plural
120
+ // `-s`/`-es`, `-ing`, `-ed`, `-er`; a final `e` drops before a vowel suffix (serialize →
121
+ // serializing, serialized, serializer); a final consonant after a single vowel doubles (log →
122
+ // logging, logger; stop → stopped); a consonant + `y` becomes `-ies`/`-ied` (factory →
123
+ // factories). Words under three letters are taken as written, and a 3-letter word keeps its
124
+ // `e` before `-er`, so "use" reaches `using` and `used` but never `user`.
125
+ const conjugations = (word: string): string[] => {
126
+ if (word.length < 3) return [word];
127
+ const forms = [word, `${word}s`, `${word}es`, `${word}ing`, `${word}ed`, `${word}er`];
128
+ const stem = word.slice(0, -1);
129
+ if (word.endsWith('e'))
130
+ forms.push(`${stem}ing`, `${stem}ed`, ...(word.length >= 4 ? [`${stem}er`] : []));
131
+ if (/[^aeiou][aeiou][^aeiouwxy]$/.test(word))
132
+ forms.push(...['ing', 'ed', 'er'].map((suffix) => word + word.slice(-1) + suffix));
133
+ if (/[^aeiou]y$/.test(word)) forms.push(`${stem}ies`, `${stem}ied`);
134
+ return forms;
135
+ };
136
+
137
+ // A phrase, prepared once per hook call: its words, each word's conjugations, and the longest
138
+ // text a match could span (so a long pattern is only scanned that far from each start).
139
+ type PreparedPhrase = { phrase: string; words: string[]; forms: string[][]; maxLength: number };
140
+
141
+ const preparePhrase = (phrase: string): PreparedPhrase => {
142
+ const words = wordsOf(phrase);
143
+ const forms = words.map(conjugations);
144
+ const maxLength = forms.reduce((sum, list) => sum + Math.max(...list.map((f) => f.length)), 0);
145
+ return { phrase, words, forms, maxLength };
146
+ };
147
+
148
+ // One alternative of the pattern: its words joined, and where each word ends in that text.
149
+ type Segment = { text: string; ends: number[] };
150
+
151
+ // The pattern's alternatives, each read on its own: `seed|user` searches "seed" or "user",
152
+ // never the phrase "seed a user". An escaped `\(`, `\)` or `\|` is a literal, not a boundary.
153
+ const segmentsOf = (pattern: string): Segment[] =>
154
+ pattern
155
+ .replace(/\\[|()]/g, ' ')
156
+ .split(/[|()]/)
157
+ .map(wordsOf)
158
+ .filter((words) => words.length > 0)
159
+ .map((words) => {
160
+ let at = 0;
161
+ return { text: words.join(''), ends: words.map((word) => (at += word.length)) };
162
+ });
163
+
164
+ // Does a run of consecutive pattern words spell the phrase, each phrase word in one of its
165
+ // conjugations? Compared joined, so the split doesn't matter: `seedingUsers` spells "seed a
166
+ // user", `createGitHubClient` spells "github", `github` spells "GitHub". The run starts and ends
167
+ // on word boundaries, so `unlock` never spells "lock" and `lockfile` never does either.
168
+ const spells = ({ text, ends }: Segment, { words, forms, maxLength }: PreparedPhrase): boolean => {
169
+ if (words.length === 0) return false;
170
+ const boundaries = new Set(ends);
171
+ const walk = (i: number, at: number, limit: number): boolean =>
172
+ i === forms.length
173
+ ? boundaries.has(at)
174
+ : (forms[i] ?? []).some(
175
+ (form) =>
176
+ at + form.length <= limit &&
177
+ text.startsWith(form, at) &&
178
+ walk(i + 1, at + form.length, limit),
179
+ );
180
+ return [0, ...ends.slice(0, -1)].some((start) => walk(0, start, start + maxLength));
181
+ };
182
+
183
+ const MAX_REGEX_PATTERN = 200;
184
+ const MAX_UNBOUNDED_QUANTIFIERS = 4;
185
+
186
+ // The pattern read as a regex over a whole phrase, compiled once per hook call, or not at all
187
+ // for long patterns, nested or piled-up quantifiers (they backtrack for seconds in JavaScript),
188
+ // and syntax JavaScript can't parse (the word reading still applies).
189
+ type RegexReading = { regex: RegExp; literals: string[] } | undefined;
190
+
191
+ const regexReadingOf = (pattern: string): RegexReading => {
192
+ if (pattern.length > MAX_REGEX_PATTERN || /\)[+*{]/.test(pattern)) return undefined;
193
+ if ((pattern.match(/[*+]|\{\d+,\}/g) ?? []).length > MAX_UNBOUNDED_QUANTIFIERS) return undefined;
194
+ // A quantifier after a run binds only its last letter (`fixtures?`), so that letter is optional.
195
+ const literals = [...pattern.replace(/\\[A-Za-z]/g, ' ').matchAll(/(\p{L}{3,})([?*{])?/gu)]
196
+ .map(([, run = '', quantifier]) => (quantifier ? run.slice(0, -1) : run).toLowerCase())
197
+ .filter((literal) => literal.length >= 3);
198
+ if (literals.length === 0) return undefined;
199
+ try {
200
+ new RegExp(pattern); // on its own first: `a)|(b` must not escape the anchors below
201
+ return { regex: new RegExp(`^(?:${pattern})$`, 'i'), literals };
202
+ } catch {
203
+ return undefined;
204
+ }
205
+ };
206
+
207
+ // Does a grep pattern search for this thesaurus phrase? Either one alternative of the pattern
208
+ // spells it (see `spells`), or the pattern, read as a regex, matches the whole phrase
209
+ // (`seed.*user`, `factor(y|ies)`). The regex reading also needs one of the pattern's own
210
+ // literal words to start a word of the phrase, so `.*` matches nothing and `lock|.*` reaches
211
+ // "lock" but not "unlock".
212
+ const searchesFor = (
213
+ segments: Segment[],
214
+ reading: RegexReading,
215
+ phrase: PreparedPhrase,
216
+ ): boolean => {
217
+ if (segments.some((segment) => spells(segment, phrase))) return true;
218
+ if (!reading) return false;
219
+ const { regex, literals } = reading;
220
+ if (!literals.some((literal) => phrase.words.some((word) => word.startsWith(literal))))
221
+ return false;
222
+ return regex.test(phrase.phrase.trim());
223
+ };
224
+
225
+ const conceptBlock = (graph: Graph, concept: string, label: string): string => {
226
+ const files = graph.conceptToFiles[concept] ?? [];
227
+ const sample = files.slice(0, MAX_CONCEPT_FILES).map((file) => ` ${file}`);
228
+ const more =
229
+ files.length > MAX_CONCEPT_FILES ? [` … ${files.length - MAX_CONCEPT_FILES} more`] : [];
230
+ const consumers = graph.usesConsumers[concept]?.length ?? 0;
231
+ const doc = graph.thesaurus[concept]?.doc;
232
+ return [
233
+ `${concept}${label} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
234
+ ...(doc ? [` read: ${doc}`] : []),
235
+ ...sample,
236
+ ...more,
237
+ ].join('\n');
238
+ };
239
+
240
+ // The grep-side lookup. First the thesaurus (`.atlas/thesaurus.ts`): each concept's phrases,
241
+ // the words people search with when they mean it; a hit is labelled with the phrase so the
242
+ // agent knows a person made that mapping, and points at the concept's doc. Then concepts
243
+ // whose name the pattern's identifier names (exactly, or as a prefix either way once both are
244
+ // long enough to mean something), skipping any the thesaurus already showed.
102
245
  export const renderConceptMatches = (graph: Graph, pattern: string): string | undefined => {
246
+ const segments = segmentsOf(pattern);
247
+ const reading = regexReadingOf(pattern);
248
+ const viaThesaurus = new Map<string, string[]>();
249
+ for (const [concept, { phrases }] of Object.entries(graph.thesaurus)) {
250
+ const hits = [...new Set(phrases)].filter((phrase) =>
251
+ searchesFor(segments, reading, preparePhrase(phrase)),
252
+ );
253
+ if (hits.length > 0) viaThesaurus.set(concept, hits);
254
+ }
255
+
103
256
  const token = identifierToken(pattern);
104
- if (!token) return undefined;
105
- const lower = token.toLowerCase();
106
- const hits = Object.keys(graph.conceptToFiles)
107
- .sort()
108
- .filter((concept) => {
109
- const name = concept.split(':')[1]?.toLowerCase() ?? '';
110
- return (
111
- name === lower ||
112
- (name.length >= 5 && lower.startsWith(name)) ||
113
- (lower.length >= 5 && name.startsWith(lower))
114
- );
115
- });
116
- if (hits.length === 0) return undefined;
117
- const blocks = hits.map((concept) => {
118
- const files = graph.conceptToFiles[concept] ?? [];
119
- const sample = files.slice(0, MAX_CONCEPT_FILES).map((file) => ` ${file}`);
120
- const more =
121
- files.length > MAX_CONCEPT_FILES ? [` … ${files.length - MAX_CONCEPT_FILES} more`] : [];
122
- const consumers = graph.usesConsumers[concept]?.length ?? 0;
123
- return [
124
- `${concept} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
125
- ...sample,
126
- ...more,
127
- ].join('\n');
128
- });
129
- return `atlas concept(s) matching "${token}":\n\n${blocks.join('\n\n')}`;
257
+ const lower = token?.toLowerCase();
258
+ const byName = lower
259
+ ? Object.keys(graph.conceptToFiles).filter((concept) => {
260
+ if (viaThesaurus.has(concept)) return false;
261
+ const name = concept.split(':')[1]?.toLowerCase() ?? '';
262
+ return (
263
+ name === lower ||
264
+ (name.length >= 5 && lower.startsWith(name)) ||
265
+ (lower.length >= 5 && name.startsWith(lower))
266
+ );
267
+ })
268
+ : [];
269
+
270
+ // A broad phrase on many concepts must not crowd out the rest of the answer.
271
+ const thesaurusHits = [...viaThesaurus.entries()].sort(([a], [b]) => a.localeCompare(b));
272
+ const shown = thesaurusHits.slice(0, MAX_THESAURUS_CONCEPTS);
273
+ const hidden = thesaurusHits.length - shown.length;
274
+ const blocks = [
275
+ ...shown.map(([concept, hits]) =>
276
+ conceptBlock(
277
+ graph,
278
+ concept,
279
+ ` (thesaurus ${hits.map((phrase) => `"${phrase}"`).join(', ')})`,
280
+ ),
281
+ ),
282
+ ...(hidden > 0 ? [`… ${hidden} more concept(s) via the thesaurus; narrow the pattern`] : []),
283
+ ...byName.sort().map((concept) => conceptBlock(graph, concept, '')),
284
+ ];
285
+ if (blocks.length === 0) return undefined;
286
+ const quoted =
287
+ pattern.length > MAX_QUOTED_PATTERN ? `${pattern.slice(0, MAX_QUOTED_PATTERN)}…` : pattern;
288
+ return `atlas concept(s) matching "${quoted}":\n\n${blocks.join('\n\n')}`;
130
289
  };
package/src/index.ts CHANGED
@@ -42,5 +42,7 @@ export {
42
42
  type ConceptRegistry,
43
43
  conceptClass,
44
44
  conceptClasses,
45
+ type Thesaurus,
46
+ type ThesaurusEntry,
45
47
  } from './registry/types.ts';
46
48
  export { DEFAULT_KINDS, type DefaultKind } from './vocab/kinds.ts';
@@ -10,6 +10,14 @@ export type ConceptEntry = Record<string, string[]>;
10
10
  // from these keys, never an enum atlas ships.
11
11
  export type ConceptRegistry = Record<string, ConceptEntry>;
12
12
 
13
+ // The thesaurus: each concept's phrases, the words people search with when they mean it,
14
+ // and where its doc is. Curated by hand from how people describe the job, so a grep for
15
+ // "seed a user" lands on `primitive:testFactories` and points at the doc to read.
16
+ // `doc` is a `docs:` value as concepts.ts writes it (run through `references.docs`), with an
17
+ // optional `#section`; it defaults to the concept's first `docs:` entry.
18
+ export type ThesaurusEntry = { phrases: string[]; doc?: string };
19
+ export type Thesaurus = Record<string, ThesaurusEntry>;
20
+
13
21
  // `class:name` → its class (the prefix). Returns null for a malformed key.
14
22
  export const conceptClass = (key: string): string | null => {
15
23
  const idx = key.indexOf(':');