@atom63/cli 0.0.0-stage → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/core.mjs ADDED
@@ -0,0 +1,502 @@
1
+ /**
2
+ * The query core behind the `atom63` CLI and MCP server. Pure functions over
3
+ * the generated agent index; each returns a typed envelope `{ type, data }`
4
+ * or throws an AtomError with a stable, append-only `code`.
5
+ */
6
+ import { readFileSync } from 'node:fs'
7
+ import { fileURLToPath } from 'node:url'
8
+
9
+ import { rules as ruleTable } from './rules.mjs'
10
+ import { grounds, synonyms, topics } from './synonyms.mjs'
11
+
12
+ const defaultIndexPath = fileURLToPath(new URL('../generated/agent-index.json', import.meta.url))
13
+
14
+ let cached
15
+ /** The agent index, read once per process. */
16
+ export function loadIndex(path = defaultIndexPath) {
17
+ if (path !== defaultIndexPath) return JSON.parse(readFileSync(path, 'utf8'))
18
+ cached ??= JSON.parse(readFileSync(path, 'utf8'))
19
+ return cached
20
+ }
21
+
22
+ /** A failure an agent can branch on: `code` never changes meaning once shipped. */
23
+ export class AtomError extends Error {
24
+ constructor(code, message, suggestions = []) {
25
+ super(message)
26
+ this.name = 'AtomError'
27
+ this.code = code
28
+ this.suggestions = suggestions
29
+ }
30
+
31
+ toEnvelope() {
32
+ return {
33
+ type: 'error',
34
+ data: { code: this.code, message: this.message, suggestions: this.suggestions },
35
+ }
36
+ }
37
+ }
38
+
39
+ /* ── Text matching ───────────────────────────────────────────────────────── */
40
+
41
+ const normalize = text =>
42
+ text
43
+ .toLowerCase()
44
+ .replace(/[^a-z0-9]+/g, ' ')
45
+ .trim()
46
+ const words = text => normalize(text).split(' ').filter(Boolean)
47
+
48
+ /** Levenshtein distance, stopping early past `max`. */
49
+ export function editDistance(left, right, max = 3) {
50
+ if (Math.abs(left.length - right.length) > max) return max + 1
51
+ let previous = Array.from({ length: right.length + 1 }, (_, index) => index)
52
+ for (let i = 1; i <= left.length; i++) {
53
+ const current = [i]
54
+ let rowMin = i
55
+ for (let j = 1; j <= right.length; j++) {
56
+ const cost = left[i - 1] === right[j - 1] ? 0 : 1
57
+ current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost)
58
+ rowMin = Math.min(rowMin, current[j])
59
+ }
60
+ if (rowMin > max) return max + 1
61
+ previous = current
62
+ }
63
+ return previous[right.length]
64
+ }
65
+
66
+ /** Closest names to `wanted`, for "did you mean" suggestions. */
67
+ export function closest(wanted, names, limit = 3) {
68
+ const target = normalize(wanted)
69
+ return names
70
+ .map(name => ({ name, distance: editDistance(target, normalize(name), 4) }))
71
+ .filter(({ name, distance }) => distance <= 3 || normalize(name).includes(target))
72
+ .sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name))
73
+ .slice(0, limit)
74
+ .map(({ name }) => name)
75
+ }
76
+
77
+ /**
78
+ * Score a candidate: exact name 100, name prefix 70, name containing the query
79
+ * 50, then per query term 20 for a name word, 8 for a keyword and 2 for prose.
80
+ * Terms that came from a synonym count half. A name within two edits of the
81
+ * query scores 40 when nothing better matched. `aliases` (export names) only
82
+ * count as an exact match: most components export a `…Popup` or `…Trigger`,
83
+ * so partial matches on them are noise.
84
+ */
85
+ export function score(query, terms, { names, aliases = [], keywords = [], prose = '' }) {
86
+ const q = normalize(query)
87
+ const nameTexts = names.map(normalize)
88
+ let total = 0
89
+ if (nameTexts.includes(q)) total += 100
90
+ else if (aliases.some(alias => normalize(alias) === q)) total += 90
91
+ else if (nameTexts.some(name => name.startsWith(q))) total += 70
92
+ else if (q.length >= 3 && nameTexts.some(name => name.includes(q))) total += 50
93
+
94
+ const nameWords = new Set(nameTexts.flatMap(words))
95
+ const keywordWords = new Set(keywords.flatMap(words))
96
+ const proseText = normalize(prose)
97
+ for (const { term, weight } of terms) {
98
+ if (nameWords.has(term) || nameTexts.includes(term)) total += 20 * weight
99
+ else if (keywordWords.has(term)) total += 8 * weight
100
+ else if (term.length >= 4 && proseText.includes(term)) total += 2 * weight
101
+ }
102
+
103
+ if (total === 0 && q.length >= 4) {
104
+ const distance = Math.min(...nameTexts.map(name => editDistance(q, name, 2)))
105
+ if (distance <= 2) total += 40 - distance * 10
106
+ }
107
+ return total
108
+ }
109
+
110
+ export function queryTerms(query) {
111
+ const terms = new Map(words(query).map(term => [term, 1]))
112
+ for (const term of [...terms.keys()]) {
113
+ for (const slug of synonyms[term] ?? []) {
114
+ if (slug.startsWith('--')) continue
115
+ for (const word of words(slug)) if (!terms.has(word)) terms.set(word, 0.5)
116
+ }
117
+ }
118
+ return [...terms].map(([term, weight]) => ({ term, weight }))
119
+ }
120
+
121
+ /** Boost for components a query term names through a synonym: 30 for the first, then less. */
122
+ function synonymBoost(query, slug) {
123
+ let best = 0
124
+ for (const term of words(query)) {
125
+ const rank = (synonyms[term] ?? []).indexOf(slug)
126
+ if (rank !== -1) best = Math.max(best, 30 - rank * 8)
127
+ }
128
+ return best
129
+ }
130
+
131
+ /**
132
+ * The entries a query's topics point at (see `topics`), by `kind:id`, each
133
+ * with its score and the note that replaces its summary. They rank above
134
+ * every scored match, in the order the topic lists them: 200 for the first,
135
+ * then 10 less each.
136
+ */
137
+ export function topicHits(query) {
138
+ const text = ` ${normalize(query)} `
139
+ const hits = new Map()
140
+ for (const [key, entries] of Object.entries(topics)) {
141
+ if (!text.includes(` ${key} `)) continue
142
+ entries.forEach(({ id, note }, rank) => {
143
+ const score = 200 - rank * 10
144
+ if ((hits.get(id)?.score ?? 0) < score) hits.set(id, { score, note })
145
+ })
146
+ }
147
+ return hits
148
+ }
149
+
150
+ /** The ground (neutral family and page color) an idea names (see `grounds`), or undefined. */
151
+ export function groundFor(idea) {
152
+ const text = ` ${normalize(idea)} `
153
+ const match = grounds.find(({ key }) => text.includes(` ${key} `))
154
+ if (!match) return undefined
155
+ const { surface, page, note } = match
156
+ return { surface, page, note }
157
+ }
158
+
159
+ /** Tokens a query term names through a synonym, with the same boost as components. */
160
+ function synonymTokens(query) {
161
+ const named = new Map()
162
+ for (const term of words(query)) {
163
+ for (const [rank, id] of (synonyms[term] ?? []).entries()) {
164
+ if (id.startsWith('--')) named.set(id, Math.max(named.get(id) ?? 0, 30 - rank * 8))
165
+ }
166
+ }
167
+ return named
168
+ }
169
+
170
+ /* ── Commands ────────────────────────────────────────────────────────────── */
171
+
172
+ export const searchKinds = ['component', 'template', 'token', 'doc', 'example']
173
+
174
+ /**
175
+ * One ranked list across components, templates, tokens, docs pages and story
176
+ * examples.
177
+ * Tokens only join when the query looks like one (`--…`), kind is `token`, a
178
+ * topic names them, or a query term names them through a synonym ("gradient"),
179
+ * so a thousand variables cannot bury the components.
180
+ */
181
+ export function search(index, query, { kind, limit = 10 } = {}) {
182
+ if (!query?.trim()) throw new AtomError('search.empty_query', 'Pass something to search for.')
183
+ if (kind && !searchKinds.includes(kind)) {
184
+ throw new AtomError('search.unknown_kind', `Unknown kind "${kind}".`, searchKinds)
185
+ }
186
+ const terms = queryTerms(query)
187
+ const wants = candidateKind => !kind || kind === candidateKind
188
+ const hits = topicHits(query)
189
+ const topic = (candidateKind, id) => hits.get(`${candidateKind}:${id}`)
190
+ const results = []
191
+
192
+ if (wants('component')) {
193
+ for (const component of index.components) {
194
+ const value = score(query, terms, {
195
+ names: [component.slug, component.label],
196
+ aliases: [...component.exports.values, ...component.exports.types],
197
+ keywords: [
198
+ component.summary,
199
+ component.group?.title ?? '',
200
+ ...component.exports.values,
201
+ ...(component.contract?.axes.flatMap(axis => axis.values) ?? []),
202
+ ],
203
+ prose: `${component.usage} ${component.guidance.join(' ')}`,
204
+ })
205
+ const hit = topic('component', component.slug)
206
+ const total = hit?.score ?? value + synonymBoost(query, component.slug)
207
+ if (total > 0) {
208
+ results.push({
209
+ kind: 'component',
210
+ id: component.slug,
211
+ label: component.label,
212
+ summary: hit?.note ?? component.summary,
213
+ score: total,
214
+ next: `atom63 component ${component.slug}`,
215
+ })
216
+ }
217
+ }
218
+ }
219
+
220
+ if (wants('template')) {
221
+ for (const template of index.templates) {
222
+ const hit = topic('template', template.id)
223
+ const total =
224
+ hit?.score ??
225
+ score(query, terms, {
226
+ names: [template.id, template.title],
227
+ keywords: [...template.tags, template.category, ...template.componentsUsed],
228
+ prose: template.description,
229
+ })
230
+ if (total > 0) {
231
+ results.push({
232
+ kind: 'template',
233
+ id: template.id,
234
+ label: template.title,
235
+ summary: hit?.note ?? template.description,
236
+ score: total,
237
+ next: `atom63 template ${template.id}`,
238
+ })
239
+ }
240
+ }
241
+ }
242
+
243
+ if (wants('doc')) {
244
+ for (const doc of index.docs) {
245
+ const hit = topic('doc', doc.slug)
246
+ const total = score(query, terms, { names: [doc.slug, doc.label], prose: doc.markdown })
247
+ if (total > 0 || hit) {
248
+ results.push({
249
+ kind: 'doc',
250
+ id: doc.slug,
251
+ label: doc.label,
252
+ summary: hit?.note ?? doc.route,
253
+ score: hit?.score ?? total * 0.8,
254
+ next: `atom63 docs ${doc.slug}`,
255
+ })
256
+ }
257
+ }
258
+ }
259
+
260
+ if (wants('example')) {
261
+ for (const component of index.components) {
262
+ for (const story of component.stories?.names ?? []) {
263
+ const hit = topic('example', `${component.slug}/${story}`)
264
+ const total = score(query, terms, { names: [`${component.slug} ${story}`, story] })
265
+ if (total >= 50 || hit) {
266
+ results.push({
267
+ kind: 'example',
268
+ id: `${component.slug}/${story}`,
269
+ label: `${component.label} — ${story}`,
270
+ summary: hit?.note ?? component.stories.file,
271
+ // Below components unless examples are what was asked for.
272
+ score: hit?.score ?? total * (kind === 'example' ? 1 : 0.4),
273
+ next: `atom63 example ${component.slug} ${story}`,
274
+ })
275
+ }
276
+ }
277
+ }
278
+ }
279
+
280
+ const allTokens = kind === 'token' || (!kind && query.trim().startsWith('--'))
281
+ if (wants('token')) {
282
+ for (const token of index.tokens) {
283
+ const hit = topic('token', token.cssVar)
284
+ // Other tokens join only when every token is in play.
285
+ if (!allTokens && !hit) continue
286
+ const bare = token.cssVar.replace(/^--(a63-)?/, '')
287
+ const total =
288
+ hit?.score ??
289
+ score(query.replace(/^--(a63-)?/, ''), terms, {
290
+ names: [token.cssVar, bare, token.figma?.path ?? ''],
291
+ keywords: [token.layer, token.type],
292
+ })
293
+ if (total > 0) {
294
+ results.push({
295
+ kind: 'token',
296
+ id: token.cssVar,
297
+ label: token.cssVar,
298
+ summary: hit?.note ?? `${token.type}, ${token.layer} layer`,
299
+ score: total,
300
+ next: `atom63 token ${token.cssVar}`,
301
+ })
302
+ }
303
+ }
304
+ }
305
+
306
+ if (wants('token')) {
307
+ for (const [cssVar, boost] of synonymTokens(query)) {
308
+ const listed = results.find(result => result.kind === 'token' && result.id === cssVar)
309
+ const token = index.tokens.find(candidate => candidate.cssVar === cssVar)
310
+ if (listed) listed.score += boost
311
+ else if (token) {
312
+ results.push({
313
+ kind: 'token',
314
+ id: token.cssVar,
315
+ label: token.cssVar,
316
+ summary: `${token.type}, ${token.layer} layer`,
317
+ score: boost,
318
+ next: `atom63 token ${token.cssVar}`,
319
+ })
320
+ }
321
+ }
322
+ }
323
+
324
+ results.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
325
+ return { type: 'search.results', data: { query, results: results.slice(0, limit) } }
326
+ }
327
+
328
+ function findComponent(index, slug) {
329
+ const component = index.components.find(candidate => candidate.slug === slug)
330
+ if (!component) {
331
+ throw new AtomError(
332
+ 'component.not_found',
333
+ `No component "${slug}".`,
334
+ closest(
335
+ slug,
336
+ index.components.map(candidate => candidate.slug)
337
+ )
338
+ )
339
+ }
340
+ return component
341
+ }
342
+
343
+ /**
344
+ * Everything an agent needs to use a component: what it is for, how to import
345
+ * it, its contract (and the shared web + iOS contract), related components and
346
+ * the names of its story examples. A hand-written docs page, when there is
347
+ * one, comes back as `docsMarkdown`.
348
+ */
349
+ export function component(index, slug) {
350
+ const found = findComponent(index, slug)
351
+ const page = index.docs.find(doc => doc.slug === `component-${slug}`)
352
+ return {
353
+ type: 'component.detail',
354
+ data: {
355
+ slug: found.slug,
356
+ label: found.label,
357
+ status: found.status,
358
+ group: found.group,
359
+ summary: found.summary,
360
+ usage: found.usage,
361
+ guidance: found.guidance,
362
+ axisGuidance: found.axisGuidance ?? null,
363
+ import: `import { ${found.usageExports.join(', ')} } from '${found.importPath}'`,
364
+ exports: found.exports,
365
+ contract: found.contract,
366
+ related: found.related,
367
+ examples: found.stories?.names ?? [],
368
+ docsMarkdown: page?.markdown ?? found.markdown,
369
+ },
370
+ }
371
+ }
372
+
373
+ const DECLARATION =
374
+ /^(?:export\s+)?(?:const|let|function|type|interface|class)\s+([A-Za-z_$][\w$]*)/
375
+
376
+ /**
377
+ * Split a module into its top-level declarations, keyed by name, in source
378
+ * order. A comment directly above a declaration belongs to it. Imports and the
379
+ * default export are left out.
380
+ */
381
+ function topLevelBlocks(source) {
382
+ const blocks = new Map()
383
+ let current = null
384
+ let pendingComment = []
385
+ let inComment = false
386
+ for (const line of source.split('\n')) {
387
+ const declaration = DECLARATION.exec(line)
388
+ const startsComment = /^\/\*|^\/\//.test(line)
389
+ if (declaration) {
390
+ current = { name: declaration[1], lines: [...pendingComment, line] }
391
+ blocks.set(current.name, current)
392
+ pendingComment = []
393
+ } else if (inComment || (startsComment && !line.startsWith(' '))) {
394
+ pendingComment.push(line)
395
+ inComment = inComment ? !line.includes('*/') : line.startsWith('/*') && !line.includes('*/')
396
+ current = null
397
+ } else if (/^(?:import\b|export default\b)/.test(line)) {
398
+ current = null
399
+ pendingComment = []
400
+ } else if (current) {
401
+ current.lines.push(line)
402
+ }
403
+ }
404
+ return new Map(
405
+ [...blocks].map(([blockName, block]) => [blockName, block.lines.join('\n').trimEnd()])
406
+ )
407
+ }
408
+
409
+ /** The local declarations `name` uses, transitively, in source order. */
410
+ function localDependencies(blocks, name) {
411
+ const needed = new Set()
412
+ const visit = blockName => {
413
+ for (const [candidate] of blocks) {
414
+ if (candidate === name || needed.has(candidate)) continue
415
+ if (new RegExp(`\\b${candidate.replace(/\$/g, '\\$')}\\b`).test(blocks.get(blockName))) {
416
+ needed.add(candidate)
417
+ visit(candidate)
418
+ }
419
+ }
420
+ }
421
+ visit(name)
422
+ return [...blocks.keys()]
423
+ .filter(blockName => needed.has(blockName))
424
+ .map(blockName => blocks.get(blockName))
425
+ }
426
+
427
+ /**
428
+ * A story's code as a known-good usage sample, with the file's imports and the
429
+ * local helpers (components, data, types) the story uses.
430
+ */
431
+ export function example(index, slug, story) {
432
+ const found = findComponent(index, slug)
433
+ if (!found.stories) {
434
+ throw new AtomError('example.none', `${found.label} has no story examples.`)
435
+ }
436
+ const name = story ?? found.stories.names[0]
437
+ if (!found.stories.names.includes(name)) {
438
+ throw new AtomError(
439
+ 'example.not_found',
440
+ `${found.label} has no story "${name}".`,
441
+ closest(name, found.stories.names)
442
+ )
443
+ }
444
+ const source = found.stories.source
445
+ const blocks = topLevelBlocks(source)
446
+ const code = [...localDependencies(blocks, name), blocks.get(name)].join('\n\n')
447
+ // Whole statements, including ones that span lines (`import {\n a,\n} from 'x'`).
448
+ const imports = [...source.matchAll(/^import\b[^;'"]*?(?:from\s*)?['"][^'"]+['"];?$/gms)]
449
+ .map(match => match[0])
450
+ .join('\n')
451
+ return {
452
+ type: 'example.source',
453
+ data: {
454
+ slug: found.slug,
455
+ story: name,
456
+ stories: found.stories.names,
457
+ file: found.stories.file,
458
+ imports,
459
+ code,
460
+ },
461
+ }
462
+ }
463
+
464
+ /**
465
+ * A token by CSS variable (with or without the leading `--`), or a ranked
466
+ * list when the query is not an exact variable name.
467
+ */
468
+ export function token(index, query) {
469
+ if (!query?.trim()) throw new AtomError('token.empty_query', 'Pass a token name or words.')
470
+ const wanted = query.startsWith('--') ? query : `--${query}`
471
+ const exact =
472
+ index.tokens.find(candidate => candidate.cssVar === wanted) ??
473
+ index.tokens.find(candidate => candidate.cssVar === `--a63-${query.replace(/^--/, '')}`)
474
+ if (exact) return { type: 'token.detail', data: exact }
475
+
476
+ const { data } = search(index, query, { kind: 'token', limit: 15 })
477
+ if (data.results.length === 0) {
478
+ throw new AtomError('token.not_found', `No token matches "${query}".`)
479
+ }
480
+ return { type: 'token.results', data }
481
+ }
482
+
483
+ /** A docs page's Markdown by slug. */
484
+ export function docsPage(index, slug) {
485
+ const page = index.docs.find(doc => doc.slug === slug)
486
+ if (!page) {
487
+ throw new AtomError(
488
+ 'docs.not_found',
489
+ `No docs page "${slug}".`,
490
+ closest(
491
+ slug,
492
+ index.docs.map(doc => doc.slug)
493
+ )
494
+ )
495
+ }
496
+ return { type: 'docs.page', data: page }
497
+ }
498
+
499
+ /** The rules an agent follows when it builds UI with Atom63. */
500
+ export function rules() {
501
+ return { type: 'rules', data: { rules: ruleTable } }
502
+ }