An open source design system that's fully customizable and agent ready
TypeScript
test(cli): restore the docs, search, and agent-docs behavior tests (#6953)
Joey5d39f31f8ca5
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjsnew file mode 100644index 0000000000..97da2eac76--- /dev/null+++ b/packages/cli/api/docs/docs.test.mjs@@ -0,0 +1,279 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Dispatcher-level tests for docs() — the argument-shape routing that+ * sits above the list/detail/section leaves. The leaves have their own tests;+ * this pins the router: docs() -> list, docs(topic) -> detail,+ * docs(topic, section) -> section, plus the unknown-topic/section error codes.+ * Runs against the real CLI-bundled docs (no cwd/project needed).+ */++import {describe, it, expect} from 'vitest';+import {docs} from './docs.mjs';+import {AstryxError} from '../error.mjs';++const SLOW = 30_000;++/**+ * The first guide a namespace places, read from the tree rather than named,+ * so a restructure of the guides does not break the reads under test.+ * @param {any} node the data of a docs.node read+ * @returns {string}+ */+function placedGuide(node) {+ const guide = node.slots+ .flatMap((/** @type {any} */ slot) => slot.children)+ .find((/** @type {any} */ child) => child.kind === 'generic');+ if (guide == null) throw new Error(`${node.route} places no guide`);+ return guide.route;+}++describe('docs() dispatcher routing', () => {+ it('no topic -> docs.list', async () => {+ const r = await docs();+ expect(r.type).toBe('docs.list');+ expect(Array.isArray(r.data)).toBe(true);+ expect(r.data.length).toBeGreaterThan(0);+ }, SLOW);++ it('empty topic -> docs.list (falsy topic routes to list)', async () => {+ expect((await docs('')).type).toBe('docs.list');+ }, SLOW);++ it('topic only -> docs.detail, the whole doc', async () => {+ const {data} = await docs();+ expect((await docs(data[0].topic)).type).toBe('docs.detail');+ }, SLOW);++ it('topic + index -> docs.index', async () => {+ const {data} = await docs();+ const r = await docs(data[0].topic, undefined, {index: true});+ expect(r.type).toBe('docs.index');+ }, SLOW);++ it('reads a shortened section by its old key, which its title still derives', async () => {+ const r = await docs(+ 'styling',+ 'stylex-build-setup-required-for-swizzled-components',+ );+ expect(r.type).toBe('docs.detail.section');+ expect(r.data).toMatchObject({id: 'stylex-setup'});+ }, SLOW);++ it('topic + section -> docs.detail.section', async () => {+ const {data} = await docs();+ let routed = null;+ for (const {topic} of data) {+ const detail = await docs(topic);+ const sections = detail.data.sections;+ if (Array.isArray(sections) && sections.length > 0) {+ routed = await docs(topic, sections[0].title);+ break;+ }+ }+ expect(routed).not.toBeNull();+ expect(routed.type).toBe('docs.detail.section');+ }, SLOW);++ it('unknown topic -> ERR_UNKNOWN_TOPIC', async () => {+ await expect(docs('zzz-not-a-real-topic')).rejects.toBeInstanceOf(AstryxError);+ await expect(docs('zzz-not-a-real-topic')).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_TOPIC',+ });+ }, SLOW);++ it('known topic + unknown section -> ERR_UNKNOWN_SECTION', async () => {+ const {data} = await docs();+ const topic = data[0].topic;+ await expect(docs(topic, 'zzz-not-a-real-section')).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_SECTION',+ });+ }, SLOW);++ it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {+ const res = await docs();+ expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'unorganized']);+ for (const entry of res.data) {+ expect((await docs(entry.topic)).type).toBe('docs.detail');+ }+ }, SLOW);++ it('opens a route typed in another case', async () => {+ const r = await docs('CLI/API');+ expect(r.type).toBe('docs.node');+ expect(r.data).toMatchObject({route: 'cli/api', links: {up: 'astryx docs cli'}});+ }, SLOW);++ it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {+ const err = await docs('cli/api/functions/search', 'x').catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ expect(err.message).toContain('astryx docs cli/api/functions/search');+ expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);+ }, SLOW);++ it('a namespace route -> docs.node, one level of children', async () => {+ const r = await docs('cli/api');+ expect(r.type).toBe('docs.node');+ expect(r.data).toMatchObject({+ id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/namespace/api',+ route: 'cli/api',+ kind: 'namespace',+ package: '@astryxdesign/cli',+ breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],+ content: [],+ });+ expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([+ 'cli/api/functions',+ 'cli/api/schemas',+ 'cli/api/enums',+ ]);+ }, SLOW);++ it('a typed doc route -> docs.node with its content', async () => {+ const r = await docs('cli/api/functions/search');+ expect(r.type).toBe('docs.node');+ expect(r.data).toMatchObject({+ id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/function/search',+ kind: 'function',+ title: 'search()',+ slots: [],+ });+ expect(r.data.breadcrumb.map(link => link.route)).toEqual([+ 'cli',+ 'cli/api',+ 'cli/api/functions',+ ]);+ expect(JSON.stringify(r.data.content)).toContain(+ '`astryx search` runs it. Read it with `astryx docs cli/commands/search`.',+ );+ }, SLOW);++ it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {+ // cli/integrations is a namespace of short guides; each guide reads like a topic.+ const integrations = await docs('cli/integrations');+ expect(integrations.type).toBe('docs.node');+ const guide = placedGuide(integrations.data);+ expect((await docs(guide)).type).toBe('docs.detail');+ const index = await docs(guide, undefined, {index: true});+ expect(index).toMatchObject({type: 'docs.index', data: {name: guide}});+ expect(index.data.sections.length).toBeGreaterThan(1);+ expect((await docs(guide, index.data.sections[0].id)).type).toBe(+ 'docs.detail.section',+ );+ }, SLOW);++ it('every read carries its moves (spec:AST-047)', async () => {+ const root = (await docs('cli')).data;+ expect(root.links).toEqual({up: 'astryx docs'});+ const leaf = (await docs('cli/api/functions/search')).data;+ expect(leaf.links.up).toBe('astryx docs cli/api/functions');+ expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);+ expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);+ const integrations = (await docs('cli/integrations')).data;+ const guide = placedGuide(integrations);+ const siblings = integrations.slots+ .find(slot => slot.children.some(child => child.route === guide))+ .children.map(child => child.route);+ const at = siblings.indexOf(guide);+ const index = await docs(guide, undefined, {index: true});+ // A guide moves across its namespace's slot, as any tree node does.+ expect(index.data.links).toEqual({+ up: 'astryx docs cli/integrations',+ ...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),+ ...(at < siblings.length - 1+ ? {next: `astryx docs ${siblings[at + 1]}`}+ : {}),+ });+ const first = (await docs(guide, index.data.sections[0].id)).data;+ expect(first.links).toEqual({+ up: `astryx docs ${guide} --index`,+ next: `astryx docs ${guide} ${index.data.sections[1].id}`,+ });+ const last = index.data.sections.at(-1).id;+ const end = (await docs(guide, last)).data;+ expect(end.links.next).toBeUndefined();+ expect(end.links.previous).toBe(+ `astryx docs ${guide} ${index.data.sections.at(-2).id}`,+ );+ // A flat topic's home is the Unorganized level, and it moves across it.+ const flat = (await docs('principles')).data.links;+ expect(flat.up).toBe('astryx docs unorganized');+ expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);+ expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);+ const home = (await docs('unorganized')).data;+ expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});+ expect(home.slots[0].children.map(child => child.route)).toEqual(+ (await docs()).data.map(entry => entry.topic),+ );+ }, SLOW);++ it('names a node by its doc identity; a generated level has id null', async () => {+ const level = (await docs('cli/api/functions')).data;+ expect(level).toHaveProperty('id', null);+ expect(level.route).toBe('cli/api/functions');+ }, SLOW);++ it("offers a typed doc's related docs as moves", async () => {+ const fn = (await docs('cli/api/functions/search')).data;+ expect(fn.links.related).toContain('astryx docs cli/commands/search');+ const cmd = (await docs('cli/commands/search')).data;+ expect(cmd.links.related).toContain('astryx docs cli/api/functions/search');+ }, SLOW);++ it('a topic read returns the whole doc; index returns its sections', async () => {+ expect((await docs('principles')).type).toBe('docs.detail');+ const index = await docs('principles', undefined, {index: true});+ expect(index.type).toBe('docs.index');+ expect(index.data.sections.length).toBeGreaterThan(1);+ expect((await docs('principles', undefined, {dense: true})).type).toBe(+ 'docs.detail',+ );+ }, SLOW);++ it("the guide's old flat name is gone, and its error names the new route", async () => {+ await expect(docs('cli-integrations')).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_TOPIC',+ suggestions: [expect.objectContaining({name: 'cli/integrations'})],+ });+ expect((await docs()).data.map(entry => entry.topic)).not.toContain(+ 'cli-integrations',+ );+ }, SLOW);++ it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {+ const err = await docs('cli', 'commands').catch(e => e);+ expect(err).toBeInstanceOf(AstryxError);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ // It names the namespace's children, in the order its slots list them.+ const cli = (await docs('cli')).data;+ expect(err.suggestions.map(s => s.name)).toEqual(+ cli.slots.flatMap(slot => slot.children.map(child => child.route)),+ );+ expect(err.suggestions.map(s => s.name)).toContain('cli/commands');+ }, SLOW);++ it('an unknown route suggests the children of the deepest namespace it reaches', async () => {+ const err = await docs('cli/api/functions/serch').catch(e => e);+ expect(err.code).toBe('ERR_UNKNOWN_TOPIC');+ expect(err.suggestions.map(s => s.name)).toContain('cli/api/functions/search');+ expect(err.suggestions.every(s => s.name.startsWith('cli/api/functions/'))).toBe(true);+ }, SLOW);++ it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {+ for (const bad of [123, {}, ['tokens'], true]) {+ const err = await docs(/** @type {any} */ (bad)).catch(e => e);+ expect(err).toBeInstanceOf(AstryxError);+ expect(err.code).toBe('ERR_UNKNOWN_TOPIC');+ }+ }, SLOW);++ it('non-string section -> ERR_UNKNOWN_SECTION (not a raw TypeError)', async () => {+ const {data} = await docs();+ const topic = data[0].topic;+ for (const bad of [456, {}, ['x']]) {+ const err = await docs(topic, /** @type {any} */ (bad)).catch(e => e);+ expect(err).toBeInstanceOf(AstryxError);+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');+ }+ }, SLOW);+});diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjsnew file mode 100644index 0000000000..f422ce7f43--- /dev/null+++ b/packages/cli/api/docs/integration-tree.test.mjs@@ -0,0 +1,572 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Integration docs in the docs tree (spec:AST-046, spec:AST-047): an+ * integration's namespace docs and placed guides join the CLI's tree with the+ * same moves, links, search, and doctor checks, named by its provider id.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {docs} from './docs.mjs';+import {loadDocsCatalog} from './_adapter.mjs';+import {search} from '../search/search.mjs';+import {checkDocsTree} from '../doctor/doctor.mjs';+import {integrationDocConflicts} from '../integration/authoring-checks.mjs';++const SLOW = 60_000;++/** @type {string} */+let tmpDir;++const NAMESPACE = {+ type: 'namespace',+ name: 'acme',+ title: 'Acme',+ summary: 'Everything about the Acme kit.',+ slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},+};++/**+ * A guide placed in the acme namespace.+ * @param {string} name+ * @param {object} [fields]+ */+function guide(name, fields = {}) {+ return {+ type: 'generic',+ name,+ title: `Acme ${name}`,+ description: `How to ${name} the Acme kit.`,+ placement: {parent: 'namespace:acme', slot: 'guides'},+ sections: [+ {title: 'Overview', content: [{type: 'prose', text: `Do ${name}.`}]},+ ],+ ...fields,+ };+}++/** The docs of a small integration: a namespace, two guides, and a topic. */+function kit() {+ return {+ 'acme.doc.mjs': NAMESPACE,+ 'setup.doc.mjs': guide('setup', {+ placement: {parent: 'namespace:acme', slot: 'guides', order: 1},+ sections: [+ {+ title: 'Install',+ content: [+ {+ type: 'prose',+ text: 'Frobnicate the kit, then check it with {@link @astryxdesign/cli:command:doctor}.',+ },+ {type: 'prose', text: 'Next: {@link generic:deploy}.'},+ ],+ },+ {+ title: 'Configure',+ content: [{type: 'prose', text: 'Add it to astryx.config.'}],+ },+ ],+ }),+ 'deploy.doc.mjs': guide('deploy', {+ placement: {parent: 'namespace:acme', slot: 'guides', order: 2},+ }),+ 'notes.doc.mjs': {+ type: 'generic',+ name: 'acme-notes',+ title: 'Acme notes',+ description: 'Notes about the kit.',+ sections: [+ {+ title: 'Start',+ content: [{type: 'prose', text: 'Start at {@link generic:setup}.'}],+ },+ ],+ },+ };+}++/** A guide whose only link names no doc. */+const broken = () =>+ guide('broken', {+ sections: [+ {+ title: 'Overview',+ content: [{type: 'prose', text: 'See {@link generic:nope}.'}],+ },+ ],+ });++/**+ * A consumer project that configures `@acme/kit`, whose manifest names a+ * provider id that differs from its package name.+ * @param {Record<string, object>} files+ */+function scaffold(files) {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: 'consumer'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit']};\n",+ );+ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'kit');+ fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});+ fs.writeFileSync(+ path.join(pkgDir, 'package.json'),+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(pkgDir, 'astryx.integration.mjs'),+ "export default {docs: './docs', providerId: '@acme/tree-provider'};\n",+ );+ for (const [file, doc] of Object.entries(files)) {+ fs.writeFileSync(+ path.join(pkgDir, 'docs', file),+ `export const docs = ${JSON.stringify(doc, null, 2)};\n`,+ );+ }+}++beforeEach(() => {+ tmpDir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-integration-tree-test-'),+ );+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('integration docs in the docs tree', () => {+ it('names a package whose docs did not load, instead of dropping them silently', async () => {+ scaffold({+ ...kit(),+ 'broken.doc.mjs': {+ type: 'generic',+ name: 'broken',+ title: 'Broken',+ description: 'A topic whose block no topic may hold.',+ sections: [+ {+ title: 'Only',+ content: [+ {+ type: 'workflow',+ steps: [{title: 'Set up', references: ['generic:setup']}],+ },+ ],+ },+ ],+ },+ });+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.meta?.notLoaded).toEqual([+ expect.objectContaining({package: '@acme/kit', message: expect.any(String)}),+ ]);+ }, 60_000);++ it('lists an integration namespace beside the CLI, named by its provider id', async () => {+ scaffold(kit());+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.meta.namespaces).toContainEqual({+ topic: 'acme',+ description: 'Everything about the Acme kit.',+ package: '@acme/kit',+ });+ const top = await docs('acme', undefined, {cwd: tmpDir});+ expect(top.type).toBe('docs.node');+ expect(top.data).toMatchObject({+ id: 'astryx:artifact:v1/%40acme%2Ftree-provider/namespace/acme',+ package: '@acme/kit',+ links: {up: 'astryx docs'},+ });+ expect(+ top.data.slots[0].children.map((/** @type {any} */ c) => c.route),+ ).toEqual(['acme/setup', 'acme/deploy']);+ }, SLOW);++ it('reads a placed guide one level at a time, with its links resolved', async () => {+ scaffold(kit());+ const index = await docs('acme/setup', undefined, {cwd: tmpDir, index: true});+ expect(index.type).toBe('docs.index');+ expect(index.data.links.up).toBe('astryx docs acme');+ const install = await docs('acme/setup', 'install', {cwd: tmpDir});+ const [prose, next] = install.data.content;+ expect(prose.text).toBe(+ 'Frobnicate the kit, then check it with `astryx docs cli/commands/doctor`.',+ );+ expect(next.text).toBe('Next: `astryx docs acme/deploy`.');+ const notes = await docs('acme-notes', undefined, {cwd: tmpDir});+ expect(notes.data.sections[0].content[0].text).toBe(+ 'Start at `astryx docs acme/setup`.',+ );+ }, SLOW);++ it('finds a section of the guide by search, with its package and parent', async () => {+ scaffold(kit());+ const {data} = await search('frobnicate', {cwd: tmpDir, type: 'doc'});+ expect(data.results[0]).toMatchObject({+ name: 'acme/setup',+ section: 'install',+ command: 'astryx docs acme/setup install',+ parent: 'astryx docs acme/setup --index',+ package: '@acme/kit',+ });+ }, SLOW);++ it('passes doctor, and warns on a link that names no doc', async () => {+ scaffold(kit());+ const ok = await checkDocsTree({+ docsCatalog: await loadDocsCatalog(tmpDir),+ });+ expect(ok).toMatchObject({id: 'docs-tree', status: 'pass'});+ scaffold({...kit(), 'broken.doc.mjs': broken()});+ const bad = await checkDocsTree({+ docsCatalog: await loadDocsCatalog(tmpDir),+ });+ expect(bad.status).toBe('warn');+ expect(bad.message).toContain('acme/broken');+ expect(bad.message).toContain('"generic:nope" names no doc');+ }, SLOW);++ it("keeps the CLI's routes: an integration namespace or topic that claims one is withdrawn, and both doctors say so", async () => {+ const flat = (/** @type {string} */ name) => ({+ type: 'generic',+ name,+ title: `Acme ${name}`,+ description: `Acme's ${name} notes.`,+ sections: [+ {title: 'One', content: [{type: 'prose', text: 'One.'}]},+ {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},+ ],+ });+ scaffold({+ ...kit(),+ 'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},+ 'tokens.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Acme tokens', summary: 'Acme tokens.'},+ 'cli.doc.mjs': flat('cli'),+ });+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.meta.namespaces).toEqual(+ expect.arrayContaining([+ expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),+ expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),+ ]),+ );+ expect(listed.meta.namespaces.filter(n => ['tokens', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);+ expect(listed.data.map(entry => entry.topic)).not.toContain('cli');+ // Each name opens the CLI's doc, and a CLI topic keeps its home.+ expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});+ expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});+ const tokens = await docs('tokens', undefined, {cwd: tmpDir});+ expect(tokens.type).toBe('docs.detail');+ expect(tokens.data.links.up).toBe('astryx docs unorganized');+ // The project doctor and the package doctor both name the claims.+ const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});+ expect(check.status).toBe('warn');+ expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');+ expect(check.message).toContain('takes the route "tokens"');+ expect(check.message).toContain('both have the route "cli"');+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');+ expect(graph).toContain('takes the route "unorganized"');+ expect(graph).toContain('takes the route "tokens"');+ expect(graph).toContain('route "cli"');+ }, SLOW);++ it("keeps the CLI's routes from a claim that differs only in case", async () => {+ const flat = (/** @type {string} */ name) => ({+ type: 'generic',+ name,+ title: `Acme ${name}`,+ description: `Acme's ${name} notes.`,+ sections: [+ {title: 'One', content: [{type: 'prose', text: 'One.'}]},+ {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},+ ],+ });+ scaffold({...kit(), 'caps-cli.doc.mjs': flat('CLI')});+ // Another spelling, in a nested folder of the package's docs.+ const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');+ fs.mkdirSync(nested, {recursive: true});+ fs.writeFileSync(+ path.join(nested, 'caps-unorganized.doc.mjs'),+ `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,+ );+ fs.writeFileSync(+ path.join(nested, 'caps-tokens.doc.mjs'),+ `export const docs = ${JSON.stringify(flat('TOKENS'), null, 2)};\n`,+ );+ expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});+ expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});+ expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');+ // Search does not offer a topic whose route another doc owns.+ const found = await search("Acme's CLI notes", {cwd: tmpDir, type: 'doc', limit: 20});+ expect(+ found.data.results.filter(hit => hit.package === '@acme/kit' && /^cli$/i.test(hit.name)),+ ).toEqual([]);+ const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});+ expect(check.status).toBe('warn');+ expect(check.message).toContain('route "CLI"');+ expect(check.message).toContain('takes the route "Unorganized"');+ // `TOKENS` is the CLI's topic `tokens` in another spelling: the CLI's wins.+ const tokens = await docs('TOKENS', undefined, {cwd: tmpDir, index: true});+ expect(tokens.data).toMatchObject({name: 'tokens', links: {up: 'astryx docs unorganized'}});+ expect(tokens.data.title).not.toBe('Acme TOKENS');+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ const graph = result.data.issues+ .filter(issue => issue.code === 'invalid_doc_graph')+ .map(issue => issue.message)+ .join('\n');+ expect(graph).toContain('route "CLI"');+ expect(graph).toContain('takes the route "Unorganized"');+ }, SLOW);++ it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {+ scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});+ const two = path.join(tmpDir, 'node_modules', '@acme', 'two');+ fs.mkdirSync(path.join(two, 'docs'), {recursive: true});+ fs.writeFileSync(path.join(two, 'package.json'), JSON.stringify({name: '@acme/two', version: '1.0.0'}));+ fs.writeFileSync(path.join(two, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");+ fs.writeFileSync(+ path.join(two, 'docs', 'acme-tokens.doc.mjs'),+ `export const docs = ${JSON.stringify({+ type: 'generic',+ name: 'acme-tokens',+ title: 'Acme tokens',+ description: 'Acme tokens.',+ replaces: 'tokens',+ sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}],+ }, null, 2)};\n`,+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit', '@acme/two']};\n",+ );+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');+ const read = await docs('tokens', undefined, {cwd: tmpDir, index: true});+ expect(read.data.name).toBe('acme-tokens');+ const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});+ expect(check.status).toBe('warn');+ expect(check.message).toContain('which the topic "acme-tokens" also answers to');+ }, SLOW);++ it('keeps every name a topic replaced twice answers to, and the CLI\'s links to it still open', async () => {+ scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});+ /** @param {string} pkg @param {string} name @param {string} replaces */+ const replacement = (pkg, name, replaces) => {+ const dir = path.join(tmpDir, 'node_modules', '@acme', pkg);+ fs.mkdirSync(path.join(dir, 'docs'), {recursive: true});+ fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: `@acme/${pkg}`, version: '1.0.0'}));+ fs.writeFileSync(path.join(dir, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");+ fs.writeFileSync(+ path.join(dir, 'docs', `${name}.doc.mjs`),+ `export const docs = ${JSON.stringify({+ type: 'generic',+ name,+ title: `Tokens by ${pkg}`,+ description: `Tokens by ${pkg}.`,+ replaces,+ sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}],+ }, null, 2)};\n`,+ );+ };+ replacement('two', 'acme-tokens', 'tokens');+ replacement('three', 'b-tokens', 'tokens');+ replacement('four', 'super-tokens', 'b-tokens');+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit', '@acme/two', '@acme/three', '@acme/four']};\n",+ );+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');+ for (const name of ['tokens', 'acme-tokens', 'b-tokens', 'super-tokens']) {+ expect((await docs(name, undefined, {cwd: tmpDir, index: true})).data.name).toBe('super-tokens');+ }+ // A walk over every topic: the CLI's own links to `tokens` still open it.+ /** @type {string[]} */+ const raw = [];+ for (const entry of listed.data) {+ const read = await docs(entry.topic, undefined, {cwd: tmpDir});+ if (/\{@link [^}]*tokens\}/.test(JSON.stringify(read.data))) raw.push(entry.topic);+ }+ expect(raw).toEqual([]);+ const principles = await docs('principles', undefined, {cwd: tmpDir});+ expect(JSON.stringify(principles.data)).toContain('astryx docs super-tokens');+ const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});+ expect(check.message).toContain('takes the route "tokens", which the topic "super-tokens" also answers to');+ expect(check.message).not.toContain('names no doc');+ }, SLOW);++ it("keeps the CLI's routes from a replacement that answers to one, in one package or across a chain", async () => {+ const flat = (/** @type {string} */ name, /** @type {object} */ extra = {}) => ({+ type: 'generic',+ name,+ title: `Acme ${name}`,+ description: `Acme's ${name} notes.`,+ sections: [+ {title: 'One', content: [{type: 'prose', text: 'One.'}]},+ {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},+ ],+ ...extra,+ });+ scaffold({+ ...kit(),+ 'a-cli.doc.mjs': flat('cli'),+ 'a-unorganized.doc.mjs': flat('Unorganized'),+ 'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),+ 'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),+ });+ // Another package carries the chain on: c3 replaces b2, which replaced cli.+ const three = path.join(tmpDir, 'node_modules', '@acme', 'three');+ fs.mkdirSync(path.join(three, 'docs'), {recursive: true});+ fs.writeFileSync(path.join(three, 'package.json'), JSON.stringify({name: '@acme/three', version: '1.0.0'}));+ fs.writeFileSync(path.join(three, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");+ fs.writeFileSync(+ path.join(three, 'docs', 'c3.doc.mjs'),+ `export const docs = ${JSON.stringify(flat('c3', {replaces: 'b2'}), null, 2)};\n`,+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit', '@acme/three']};\n",+ );+ for (const name of ['cli', 'CLI']) {+ expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});+ }+ for (const name of ['unorganized', 'UNORGANIZED']) {+ expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});+ }+ // The replacement still answers to its own names.+ for (const name of ['b2', 'c3']) {+ expect((await docs(name, undefined, {cwd: tmpDir, index: true})).data.name).toBe('c3');+ }+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ for (const entry of listed.data) {+ const read = await docs(entry.topic, undefined, {cwd: tmpDir});+ expect(read.type).toBe('docs.detail');+ expect(read.data.name).toBe(entry.topic);+ }+ const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});+ expect(check.status).toBe('warn');+ expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');+ expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');+ const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ const graph = inPackage.data.issues+ .filter(issue => issue.code === 'invalid_doc_graph')+ .map(issue => issue.message)+ .join('\n');+ expect(graph).toContain('answers to "cli" through replaces');+ }, SLOW);++ it('runs the same checks inside the package: doctor integration docs', async () => {+ scaffold({...kit(), 'broken.doc.mjs': broken()});+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ expect(result.data.issues).toContainEqual(+ expect.objectContaining({+ code: 'invalid_doc_graph',+ severity: 'warning',+ message: expect.stringContaining('"generic:nope" names no doc'),+ }),+ );+ }, SLOW);++ it('fails doctor integration docs on a placement that hides a guide, and only warns on a link', async () => {+ scaffold({+ ...kit(),+ 'lost.doc.mjs': guide('lost', {+ placement: {parent: 'namespace:nope', slot: 'guides'},+ }),+ });+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ expect(result.data.issues).toContainEqual(+ expect.objectContaining({+ code: 'invalid_doc_graph',+ severity: 'error',+ message: expect.stringContaining('namespace:nope'),+ }),+ );+ }, SLOW);++ it("resolves an extension's links against the extension's provider, not the base topic's", async () => {+ scaffold({+ ...kit(),+ 'integrations.doc.mjs': guide('integrations'),+ 'theme-acme.doc.mjs': {+ type: 'generic',+ name: 'theme-acme',+ title: 'Acme theming',+ description: 'Acme notes on theming.',+ extends: 'theme',+ sections: [+ {+ title: 'Acme theming notes',+ content: [+ {+ type: 'prose',+ text: 'See {@link generic:integrations}, and {@link @astryxdesign/cli:generic:tokens} for the tokens.',+ },+ ],+ },+ ],+ },+ });+ const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});+ // `generic:integrations` is the extension's own guide, never the CLI's+ // `cli/integrations`; a provider-qualified link reaches the CLI's topic.+ expect(data.content[0].text).toBe(+ 'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',+ );+ // The CLI's own sections of the topic still resolve against the CLI.+ const full = await docs('theme', undefined, {cwd: tmpDir});+ expect(JSON.stringify(full.data)).not.toContain('{@link');+ }, SLOW);++ it("warns, in the project and in the package, on an extension link that names no doc of its provider", async () => {+ scaffold({+ ...kit(),+ 'theme-acme.doc.mjs': {+ type: 'generic',+ name: 'theme-acme',+ title: 'Acme theming',+ description: 'Acme notes on theming.',+ extends: 'theme',+ sections: [+ {+ title: 'Acme theming notes',+ content: [{type: 'prose', text: 'See {@link generic:tokens}.'}],+ },+ ],+ },+ });+ const check = await checkDocsTree({+ docsCatalog: await loadDocsCatalog(tmpDir),+ });+ expect(check.status).toBe('warn');+ expect(check.message).toContain('"generic:tokens" names no doc');+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ expect(result.data.issues).toContainEqual(+ expect.objectContaining({+ code: 'invalid_doc_graph',+ message: expect.stringContaining('"generic:tokens" names no doc'),+ }),+ );+ }, SLOW);++ it('keeps the CLI route when an integration claims it, and names the claim', async () => {+ scaffold({'cli.doc.mjs': {...NAMESPACE, name: 'cli', title: 'Not the CLI'}});+ const top = await docs('cli', undefined, {cwd: tmpDir});+ expect(top.data.package).toBe('@astryxdesign/cli');+ const check = await checkDocsTree({+ docsCatalog: await loadDocsCatalog(tmpDir),+ });+ expect(check.status).toBe('warn');+ expect(check.message).toContain('both have the route "cli"');+ }, SLOW);+});diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjsnew file mode 100644index 0000000000..148570ca5d--- /dev/null+++ b/packages/cli/api/docs/integrationDocs.test.mjs@@ -0,0 +1,336 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file End-to-end tests for integration-contributed doc topics: a scaffolded+ * consumer project whose configured integration ships a `docs` root, read back+ * through the public surfaces — `docs()`, `search()`, and the agent-docs block.+ *+ * The unit-level rules (what a docs root contributes, what the catalog does+ * with `replaces`/`extends`) are covered in+ * foundation/discovery/docs-discovery.test.mjs. What is pinned here is that a+ * contributed topic is indistinguishable from a built-in one at the surfaces+ * an agent actually reads.+ *+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to+ * dynamically import a module from outside the project root.+ */++import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {docs} from './docs.mjs';+import {search} from '../search/search.mjs';+import {loadDocsCatalog} from './_adapter.mjs';+import {AstryxError} from '../error.mjs';++const SLOW = 30_000;++let tmpDir;++/** A minimal, valid topic. */+function topic(fields) {+ return {+ type: 'generic',+ name: 'deploying',+ title: 'Deploying',+ description: 'How to ship an app built with Acme widgets.',+ category: 'guide',+ sections: [+ {title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]},+ ],+ ...fields,+ };+}++/**+ * A consumer project that configures one integration, optionally with a docs+ * root holding the given topics.+ * @param {Record<string, object|string>} [topics] file name → doc+ * @param {{config?: string}} [options]+ */+function scaffold(topics, {config} = {}) {+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ config ?? "export default {integrations: ['@acme/widgets']};\n",+ );++ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');+ fs.mkdirSync(pkgDir, {recursive: true});+ fs.writeFileSync(+ path.join(pkgDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(pkgDir, 'astryx.integration.mjs'),+ `export default ${JSON.stringify(topics ? {docs: './docs'} : {})};\n`,+ );++ if (topics) {+ const docsDir = path.join(pkgDir, 'docs');+ fs.mkdirSync(docsDir, {recursive: true});+ for (const [file, doc] of Object.entries(topics)) {+ fs.writeFileSync(+ path.join(docsDir, file),+ typeof doc === 'string'+ ? doc+ : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,+ );+ }+ }+}++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-integration-docs-test-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('integration-contributed topics', () => {+ it('lists and reads like a built-in topic, naming its owner', async () => {+ scaffold({'deploying.doc.mjs': topic()});++ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ const entry = listed.data.find(t => t.topic === 'deploying');+ expect(entry).toMatchObject({+ topic: 'deploying',+ description: 'How to ship an app built with Acme widgets.',+ package: '@acme/widgets',+ });+ // The built-in topics keep their own owner.+ expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');++ const detail = await docs('deploying', undefined, {cwd: tmpDir, full: true});+ expect(detail.type).toBe('docs.detail');+ expect(detail.data.sections[0].content[0].text).toBe('Push the button.');++ const section = await docs('deploying', 'overview', {cwd: tmpDir});+ expect(section.data.title).toBe('Overview');+ }, SLOW);++ it('is invisible to a project that does not configure the integration', async () => {+ scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});+ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ expect(listed.data.some(t => t.topic === 'deploying')).toBe(false);+ }, SLOW);++ it('serves the replacement of a built-in topic, and says what it replaced', async () => {+ scaffold({+ 'getting-started.doc.mjs': topic({+ name: 'getting-started',+ replaces: 'getting-started',+ title: 'Getting started',+ description: 'Install Acme widgets.',+ sections: [+ {title: 'Install', content: [{type: 'prose', text: 'yarn add @acme/widgets'}]},+ ],+ }),+ });++ const detail = await docs('getting-started', undefined, {cwd: tmpDir, full: true});+ expect(detail.data.sections.map(s => s.title)).toEqual(['Install']);+ expect(detail.data.sections[0].content[0].text).toBe('yarn add @acme/widgets');++ const listed = await docs(undefined, undefined, {cwd: tmpDir});+ const entries = listed.data.filter(t => t.topic === 'getting-started');+ expect(entries).toHaveLength(1);+ expect(entries[0]).toMatchObject({+ package: '@acme/widgets',+ replaces: 'getting-started',+ });+ }, SLOW);++ it('keeps the replaced name resolving when the replacement renames it', async () => {+ scaffold({+ 'setup.doc.mjs': topic({name: 'setup', replaces: 'getting-started'}),+ });+ const byOldName = await docs('getting-started', undefined, {cwd: tmpDir, full: true});+ const byNewName = await docs('setup', undefined, {cwd: tmpDir, full: true});+ expect(byOldName.data.name).toBe('setup');+ expect(byNewName.data.name).toBe('setup');+ }, SLOW);++ it('merges an extension into the topic it extends', async () => {+ const builtin = await docs('theme', undefined, {full: true});+ const baseSectionTitle = builtin.data.sections[0].title;+ scaffold({+ 'theme-internal.doc.mjs': topic({+ name: 'theme-internal',+ extends: 'theme',+ sections: [+ {title: baseSectionTitle, content: [{type: 'prose', text: 'Use the Acme theme.'}]},+ {title: 'Acme themes', content: [{type: 'prose', text: 'Three of them.'}]},+ ],+ }),+ });++ const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});+ // The extension is not a topic of its own.+ expect((await docs(undefined, undefined, {cwd: tmpDir})).data.some(+ t => t.topic === 'theme-internal',+ )).toBe(false);+ expect(extended.data.sections[0].content[0].text).toBe('Use the Acme theme.');+ expect(extended.data.sections.at(-1).title).toBe('Acme themes');+ // Everything the extension did not name is still the base doc's.+ expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);+ }, SLOW);++ it('migrates a real built-in section to a stable ID without duplicating it', async () => {+ const builtin = await docs('theme', undefined, {full: true});+ // Readers see a key on every section; the migration case is one whose+ // source authors no id.+ const {docs: authored} = await import('../../assets/docs/theme.doc.mjs');+ const target = authored.sections.find(section => section.id == null);+ expect(target).toBeDefined();+ scaffold({+ 'theme-internal.doc.mjs': topic({+ name: 'theme-internal',+ extends: 'theme',+ sections: [+ {+ id: 'acme-theme-setup',+ title: target.title,+ content: [{type: 'prose', text: 'Use the Acme theme.'}],+ },+ ],+ }),+ });++ const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});+ expect(extended.data.sections).toHaveLength(builtin.data.sections.length);+ const matches = extended.data.sections.filter(+ section => section.title === target.title,+ );+ expect(matches).toEqual([+ expect.objectContaining({+ id: 'acme-theme-setup',+ content: [{type: 'prose', text: 'Use the Acme theme.'}],+ }),+ ]);+ }, SLOW);++ it('replaces a real built-in section by the key its index shows', async () => {+ const index = await docs('theme', undefined, {index: true});+ const target = index.data.sections[0];+ scaffold({+ 'theme-internal.doc.mjs': topic({+ name: 'theme-internal',+ extends: 'theme',+ sections: [+ {+ id: target.id,+ title: `${target.title} with Acme`,+ content: [{type: 'prose', text: 'Acme first.'}],+ },+ ],+ }),+ });++ const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});+ expect(extended.data.sections).toHaveLength(index.data.sections.length);+ expect(extended.data.sections.filter(s => s.id === target.id)).toEqual([+ expect.objectContaining({content: [{type: 'prose', text: 'Acme first.'}]}),+ ]);+ const read = await docs('theme', target.id, {cwd: tmpDir});+ expect(read.data.title).toBe(`${target.title} with Acme`);+ }, SLOW);++ it.each(['zh', 'dense'])(+ 'replaces translated real sections by their authored titles under --%s',+ async lang => {+ const english = await docs('theme', undefined, {full: true});+ const englishTitles = english.data.sections.map(section => section.title);+ expect(englishTitles).toEqual(+ expect.arrayContaining(['Available Themes', 'Theme Props']),+ );+ scaffold({+ 'theme-internal.doc.mjs': topic({+ name: 'theme-internal',+ extends: 'theme',+ sections: [+ {+ id: 'acme-available-themes',+ title: 'Available Themes',+ content: [{type: 'prose', text: 'Acme themes.'}],+ },+ {+ title: 'Theme Props',+ content: [{type: 'prose', text: 'Acme props.'}],+ },+ ],+ }),+ });++ const base = await docs('theme', undefined, {lang, full: true});+ expect(base.data.sections.map(section => section.title)).not.toEqual(+ englishTitles,+ );+ const extended = await docs('theme', undefined, {cwd: tmpDir, lang, full: true});+ expect(extended.data.sections).toHaveLength(base.data.sections.length);+ expect(+ extended.data.sections.filter(+ section => section.id === 'acme-available-themes',+ ),+ ).toHaveLength(1);+ expect(+ extended.data.sections.filter(+ section => section.content[0]?.text === 'Acme props.',+ ),+ ).toHaveLength(1);+ },+ SLOW,+ );++ it('offers the contributed topics as suggestions on an unknown one', async () => {+ scaffold({'deploying.doc.mjs': topic()});+ await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true})).rejects.toBeInstanceOf(+ AstryxError,+ );+ try {+ await docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true});+ } catch (err) {+ expect(err.suggestions.map(s => s.name)).toContain('deploying');+ }+ }, SLOW);++ it('indexes a contributed topic in search', async () => {+ scaffold({'deploying.doc.mjs': topic()});+ const {data} = await search('deploying', {cwd: tmpDir, type: 'doc'});+ expect(data.results[0]).toMatchObject({+ domain: 'doc',+ name: 'deploying',+ command: 'astryx docs deploying',+ });+ }, SLOW);++ it('ranks the topics that match every word of the query first', async () => {+ // Dozens of CLI docs match `integration` alone, by name or in a code+ // tick; the topics that hold both words, this one and the CLI's own+ // troubleshooting guide, must still come first.+ scaffold({+ 'troubleshooting.doc.mjs': topic({+ name: 'troubleshooting',+ title: 'Troubleshooting',+ description: 'What to check when an integration does not load.',+ }),+ });+ const {data} = await search('troubleshoot integration', {cwd: tmpDir, type: 'doc'});+ const top = data.results.slice(0, 2).map(result => result.name);+ // This topic, and the CLI's own troubleshooting guide wherever the tree+ // places it.+ expect(top).toContain('troubleshooting');+ expect(+ top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),+ top.join(', '),+ ).toBe(true);+ }, SLOW);++ it("falls back to the CLI's own topics when the project config is unreadable", async () => {+ scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});+ const catalog = await loadDocsCatalog(tmpDir);+ expect(catalog.resolve('tokens')).toBeTruthy();+ expect(catalog.resolve('deploying')).toBeUndefined();+ }, SLOW);+});diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjsnew file mode 100644index 0000000000..f5734963c4--- /dev/null+++ b/packages/cli/api/search/search.test.mjs@@ -0,0 +1,710 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Colocated tests for the `search` leaf (api/search/search.mjs), run+ * against the real @astryxdesign/core registry. `search` had no api-level tests;+ * this locks the envelope, ranking invariants, the `--type`/limit handling, and+ * the error paths.+ *+ * The API validates its own inputs (not just the CLI): a non-positive/non-integer+ * `limit`, an empty query, and a bad `--type` all throw AstryxError with the+ * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the+ * same contract as `astryx search` on the command line.+ *+ * The last describe block covers integration-contributed components, using the+ * same temp-consumer harness as template-integration.test.mjs. Before this,+ * `search`/`build` only ever scanned @astryxdesign/core — an integration's own+ * components were invisible to both, even though `component --list` and+ * `component <Name>` already resolved them. The two discovery paths silently+ * disagreed.+ */++import {describe, it, expect} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {docs} from '../docs/docs.mjs';+import {+ headingWithPhrase,+ titleInQuery,+ search,+ scoreCandidate,+ scoreQuery,+ tokenizeQuery,+ SEARCH_DOMAINS,+} from './search.mjs';++const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const cwd = REPO;+const SLOW = 30_000;++describe('search leaf — envelope + ranking', () => {+ it('returns a `search` envelope with query + results', async () => {+ const r = await search('button', {cwd});+ expect(r.type).toBe('search');+ expect(r.data.query).toBe('button');+ expect(Array.isArray(r.data.results)).toBe(true);+ expect(r.data.results.length).toBeGreaterThan(0);+ }, SLOW);++ it('keeps tokenizer coverage out of the public result shape', async () => {+ const r = await search('table of contents', {cwd});+ expect(r.data.results.length).toBeGreaterThan(0);+ for (const result of r.data.results) {+ expect(result).not.toHaveProperty('matchedTerms');+ expect(result).not.toHaveProperty('queryTerms');+ }+ }, SLOW);++ it('returns an empty result set (not an error) for a no-match query', async () => {+ const r = await search('zzznomatch99', {cwd});+ expect(r.type).toBe('search');+ expect(r.data.results).toEqual([]);+ }, SLOW);++ it('defaults to at most 20 results', async () => {+ const r = await search('button', {cwd});+ expect(r.data.results.length).toBeLessThanOrEqual(20);+ }, SLOW);++ it('caps results to a positive limit', async () => {+ const r = await search('button', {cwd, limit: 2});+ expect(r.data.results.length).toBeLessThanOrEqual(2);+ }, SLOW);+});++describe('search leaf — per-domain result fields', () => {+ it('carries import for components and hooks, title for docs, displayName and kind for templates', async () => {+ const r = await search('theme', {cwd, limit: 60});+ expect(new Set(r.data.results.map(res => res.domain))).toEqual(+ new Set(SEARCH_DOMAINS),+ );+ for (const res of r.data.results) {+ expect(typeof res.command).toBe('string');+ expect(typeof res.description).toBe('string');+ if (res.domain === 'component' || res.domain === 'hook') {+ expect(res.import).toMatch(/\S/);+ } else if (res.domain === 'doc') {+ expect(res.title).toMatch(/\S/);+ const read = `astryx docs ${res.name}`;+ expect([read, `${read} --index`, `${read} ${res.section}`]).toContain(res.command);+ } else {+ expect(res.displayName).toMatch(/\S/);+ expect(['page', 'block']).toContain(res.kind);+ }+ }+ }, SLOW);+});++describe('search leaf — docs at the grain a reader reads them', () => {+ it(+ 'finds one section of a guide, and a docs-tree leaf by its own name',+ async () => {+ const guide = await search('when a codemod runs', {cwd, type: 'doc'});+ // Found by the section's own title, wherever the guide sits in the tree.+ const hit = guide.data.results+ .slice(0, 3)+ .find(result => result.section === 'which-codemods-run');+ expect(hit).toMatchObject({+ domain: 'doc',+ name: expect.stringMatching(/^cli\/integrations\/(?:.+\/)?codemods$/),+ title: expect.stringMatching(/ › Codemods › Choose when a codemod runs$/),+ });+ expect(hit.parent).toBe(`astryx docs ${hit.name} --index`);+ expect(hit.command).toBe(`astryx docs ${hit.name} which-codemods-run`);+ const block = await search('token-ref', {cwd});+ expect(block.data.results[0]).toMatchObject({+ name: 'authoring',+ section: 'reference-doc',+ command: 'astryx docs authoring reference-doc',+ });+ const fn = await search('assertResponse', {cwd, type: 'doc'});+ expect(fn.data.results[0]).toMatchObject({+ name: 'cli/api/functions/assert-response',+ title: 'Astryx CLI › API › Functions › assertResponse()',+ parent: 'astryx docs cli/api/functions',+ command: 'astryx docs cli/api/functions/assert-response',+ });+ expect(fn.data.results[0]).not.toHaveProperty('section');+ },+ SLOW,+ );++ it(+ 'finds the integration guides for the ways people ask to make one',+ async () => {+ // "make", "build", and "an" are stopwords, so each of the first three+ // tokenizes to `integration` alone; the phrase still matches the+ // keywords and the title the guides declare. A namespace's own+ // keywords count, and a plural name is the name.+ for (const [query, route] of [+ ['make an integration', /^cli\/integrations$/],+ ['build an integration', /^cli\/integrations$/],+ ['create an integration', /^cli\/integrations$/],+ ['integration', /^cli\/integrations$/],+ ['publish an integration', /^cli\/integrations$/],+ // The troubleshooting guide, wherever the tree places it.+ ['troubleshoot integration', /^cli\/integrations\/(?:.+\/)?troubleshooting$/],+ ]) {+ const r = await search(query, {cwd, type: 'doc'});+ const names = r.data.results.slice(0, 3).map(result => result.name);+ expect(names.some(name => route.test(name)), `${query}: ${names.join(', ')}`).toBe(true);+ }+ },+ SLOW,+ );++ it(+ 'gives a top-level namespace hit the topic list as its parent',+ async () => {+ for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {+ const r = await search(query, {cwd, type: 'doc'});+ expect(r.data.results).toContainEqual(+ expect.objectContaining({+ name: route,+ command: `astryx docs ${route}`,+ parent: 'astryx docs',+ }),+ );+ }+ },+ SLOW,+ );++ it(+ 'points a topic hit at its index, never a whole-topic read',+ async () => {+ // A guide the tree places, read from the tree rather than named.+ const {data: integrations} = await docs('cli/integrations');+ const guide = integrations.slots+ .flatMap(slot => slot.children)+ .find(child => child.kind === 'generic').route;+ const r = await search(guide, {cwd, type: 'doc'});+ expect(r.data.results[0]).toMatchObject({+ name: guide,+ command: `astryx docs ${guide} --index`,+ });+ expect(r.data.results[0]).not.toHaveProperty('section');+ },+ SLOW,+ );++ it(+ 'searches docs where @astryxdesign/core is not installed',+ async () => {+ const bare = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-search-bare-'),+ );+ try {+ const r = await search('assertResponse', {cwd: bare, type: 'doc'});+ expect(r.data.results[0].name).toBe(+ 'cli/api/functions/assert-response',+ );+ } finally {+ fs.rmSync(bare, {recursive: true, force: true});+ }+ },+ SLOW,+ );+});++describe('search leaf — matchCount is the total, not the cap', () => {+ it('reports every match while `results` stays bounded by the limit', async () => {+ // The regression: `matchCount` used to be `results.length`, so a query+ // matching 57 things reported 20 — the cap read back as the answer. Any+ // consumer counting matches (the recorded run, a caller paginating) then+ // could not tell a capped answer from an exactly-cap-sized one.+ const capped = await search('button', {cwd, limit: 2});+ expect(capped.data.results.length).toBe(2);+ expect(capped.data.matchCount).toBeGreaterThan(2);++ // Same query, no meaningful cap: the count is stable across limits, which+ // is what makes it a count of MATCHES rather than of what was returned.+ const full = await search('button', {cwd, limit: 500});+ expect(full.data.matchCount).toBe(capped.data.matchCount);+ expect(full.data.results.length).toBe(full.data.matchCount);+ }, SLOW);++ it('reports 0 for a no-match query', async () => {+ const r = await search('zzznomatch99', {cwd});+ expect(r.data.matchCount).toBe(0);+ }, SLOW);++ it('counts only the requested domain under --type', async () => {+ const all = await search('button', {cwd, limit: 500});+ const components = await search('button', {+ cwd,+ type: 'component',+ limit: 500,+ });+ expect(components.data.matchCount).toBe(components.data.results.length);+ expect(components.data.matchCount).toBeLessThanOrEqual(all.data.matchCount);+ }, SLOW);+});++describe('search leaf — --type filter', () => {+ it('restricts results to the requested domain', async () => {+ const r = await search('button', {cwd, type: 'component'});+ expect(r.data.results.every(x => x.domain === 'component')).toBe(true);+ }, SLOW);++ it('exposes the valid domain list', () => {+ expect(SEARCH_DOMAINS).toEqual(expect.arrayContaining(['component', 'hook', 'doc', 'template']));+ });+});++describe('search leaf — exact keyword phrase outranks incidental token matches (issue #5239)', () => {+ it('surfaces Outline for its own declared keyword "table of contents", ranked first', async () => {+ // Before the fix, "table" and "contents" each separately matched dozens+ // of unrelated Table-related templates by coincidence, and their+ // combined token-sum score outranked Outline's single exact match,+ // pushing it out of the results entirely at the default limit.+ const r = await search('table of contents', {cwd});+ expect(r.data.results[0]?.name).toBe('Outline');+ }, SLOW);++ it('surfaces Outline for its own declared keyword "heading navigation", ranked first', async () => {+ const r = await search('heading navigation', {cwd});+ expect(r.data.results[0]?.name).toBe('Outline');+ }, SLOW);++ it('preserves query coverage metadata on the promoted exact phrase', () => {+ const query = 'table of contents';+ const tokens = tokenizeQuery(query);+ expect(+ scoreQuery(query, tokens, {+ name: 'Outline',+ keywords: [query],+ }),+ ).toMatchObject({matched: tokens.length, total: tokens.length});+ });++ it('still returns no results for a nonsense query (the fix does not loosen matching)', async () => {+ const r = await search('zzzzqqqx', {cwd});+ expect(r.data.results).toEqual([]);+ }, SLOW);+});++describe('search leaf — a whole-query phrase in a title or heading is top tier', () => {+ /**+ * @param {string} q+ * @param {object} candidate+ * @returns {number}+ */+ const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;++ it('finds the whole query, in order, inside a title or heading', () => {+ expect(headingWithPhrase('dark mode', ['Light/Dark Mode'])).toBe('Light/Dark Mode');+ expect(headingWithPhrase('nested theme', ['Theme Props', 'Nested themes'])).toBe(+ 'Nested themes',+ );+ // A plural on either side is the same word.+ expect(headingWithPhrase('data attributes selector', ['Data attribute selectors'])).toBe(+ 'Data attribute selectors',+ );+ // Out of order, split up, or one word: not a phrase.+ expect(headingWithPhrase('mode dark', ['Light/Dark Mode'])).toBeNull();+ expect(headingWithPhrase('dark mode', ['Dark sidebar and mode toggle'])).toBeNull();+ expect(headingWithPhrase('dark', ['Light/Dark Mode'])).toBeNull();+ expect(headingWithPhrase('dark mode', undefined)).toBeNull();+ });++ it('ranks a section titled with the phrase above an exact code-tick match of one word', () => {+ // The reported miss: `search "dark mode"` put "Light/Dark Mode" at #28,+ // under API enum docs that name `mode` in code ticks.+ const section = {name: 'light-dark-mode', titles: ['Light/Dark Mode'], keywords: ['Light/Dark Mode']};+ const enumDoc = {name: 'response-types', keywords: ['mode', 'dark'], description: 'mode'};+ expect(score('dark mode', section)).toBe(170);+ expect(score('dark mode', section)).toBeGreaterThan(score('dark mode', enumDoc));+ });++ it('ranks a question that names a whole title just below that', () => {+ expect(titleInQuery('how do i add dark mode', ['Dark mode'])).toBe('Dark mode');+ expect(titleInQuery('how do nested themes work', ['Nested themes'])).toBe('Nested themes');+ // One-word titles are too common to count, and order still matters.+ expect(titleInQuery('how do i theme my app', ['Theme'])).toBeNull();+ expect(titleInQuery('mode dark please', ['Dark mode'])).toBeNull();+ const section = {name: 'light-dark-mode', titles: ['Dark mode'], keywords: ['Dark mode']};+ const named = score('how do i add dark mode', section);+ expect(named).toBeGreaterThanOrEqual(160);+ expect(named).toBeLessThan(170);+ // Sections that share a title are ordered by how much of the rest of the+ // question they answer.+ const spacing = {name: 'best-practices', titles: ['Best Practices'], prose: ['Use spacing tokens']};+ const color = {name: 'best-practices', titles: ['Best Practices'], prose: ['Use color tokens']};+ expect(score('best practices for spacing', spacing)).toBeGreaterThan(+ score('best practices for spacing', color),+ );+ });++ it('reads a plural of a name as the name, and only a real plural', () => {+ // One point under the exact spelling, so the doc named `tokens` outranks+ // the Token component for `tokens`.+ expect(scoreCandidate('integration', {name: 'integrations'})?.score).toBe(99);+ expect(scoreCandidate('box', {name: 'boxes'})?.score).toBe(99);+ expect(scoreCandidate('tabs', {name: 'tab'})?.score).toBe(99);+ expect(scoreCandidate('tokens', {name: 'tokens'})?.score).toBe(100);+ // `es` only follows s, x, z, ch, or sh.+ expect(scoreCandidate('not', {name: 'notes'})?.score ?? 0).toBeLessThan(100);+ expect(scoreCandidate('mod', {name: 'modes'})?.score ?? 0).toBeLessThan(100);+ });++ it('keeps an exact name or keyword above a title phrase', () => {+ const titled = {name: 'x', titles: ['Table of contents for long pages']};+ const keyword = {name: 'Outline', keywords: ['table of contents']};+ expect(score('table of contents', keyword)).toBeGreaterThan(score('table of contents', titled));+ });++ it('puts the dark mode section first for a docs search', async () => {+ for (const query of ['dark mode', 'how do I add dark mode']) {+ const r = await search(query, {cwd, type: 'doc'});+ expect(r.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});+ }+ }, SLOW);+});++describe('search leaf — a candidate that matches every word outranks a partial match', () => {+ /**+ * @param {string} q+ * @param {object} candidate+ * @returns {number}+ */+ const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;++ it('ranks a doc with both words above a doc named after one of them', () => {+ // The reported regression: `search troubleshoot integration` put the+ // troubleshooting guide 30th, under docs that each match `integration`+ // alone (by name, 108; in a code tick, 98).+ const guide = {+ name: 'troubleshooting',+ keywords: ['Troubleshooting'],+ description: 'What to check when an integration does not load.',+ };+ const byName = {name: 'integration', keywords: ['integration-add']};+ const byCodeTick = {name: 'integration-add', keywords: ['integration']};+ const q = 'troubleshoot integration';+ expect(score(q, guide)).toBeGreaterThan(score(q, byName));+ expect(score(q, guide)).toBeGreaterThan(score(q, byCodeTick));+ expect(scoreQuery(q, tokenizeQuery(q), guide)).toMatchObject({matched: 2, total: 2});+ });++ it('holds for longer queries too, and stays below the title tiers', () => {+ const all = {name: 'x', keywords: ['alphas'], description: 'alpha beta gamma delta'};+ const threeOfFour = {name: 'alpha', keywords: ['beta', 'gamma']};+ const q = 'alpha beta gamma delta';+ expect(score(q, all)).toBeGreaterThan(score(q, threeOfFour));+ expect(score(q, all)).toBeLessThan(160);+ });++ // Among candidates that match every word, the stronger match should come+ // first. Today every all-word match with a keyword hit gets the same score,+ // so this records the order without enforcing it: it fails, as expected,+ // until the scoring tells the two apart.+ it.fails('ranks the stronger of two all-word matches first', () => {+ const all = {name: 'x', keywords: ['alphas'], description: 'alpha beta gamma delta'};+ const q = 'alpha beta gamma delta';+ expect(score(q, {name: 'y', keywords: ['alpha'], description: 'beta gamma delta'})).toBeGreaterThan(+ score(q, all),+ );+ });++ it('keeps passing mentions of every word below an exact hit on one word', () => {+ // Mentions in prose, or the components a page happens to render, are+ // breadth: a page that says "empty state" is not the EmptyState answer.+ const mentions = {name: 'ai-chat-landing', description: 'A landing page with an empty state.'};+ const keyword = {name: 'x', keywords: ['empty']};+ expect(score('empty state', mentions)).toBeLessThan(score('empty state', keyword));+ });++ it('finds a component by its name typed as words, and a guide by its route', async () => {+ for (const [query, name] of [+ ['command palette', 'CommandPalette'],+ ['empty state', 'EmptyState'],+ ]) {+ const r = await search(query, {cwd});+ expect(r.data.results[0], query).toMatchObject({domain: 'component', name});+ }+ const tokens = await search('tokens', {cwd});+ expect(tokens.data.results[0]).toMatchObject({domain: 'doc', name: 'tokens'});+ for (const [query, route] of [+ ['codemods', /^cli\/integrations\/(?:.+\/)?codemods$/],+ ['quick start', /^cli\/integrations\/(?:.+\/)?quick-start$/],+ ['test in an app', /^cli\/integrations\/(?:.+\/)?test-in-an-app$/],+ ]) {+ const r = await search(query, {cwd, type: 'doc'});+ // The guide is among the hits that share the top score: two guides+ // that both declare the phrase tie, and the tie's order is not pinned.+ const top = r.data.results+ .filter(result => result.score === r.data.results[0].score)+ .map(result => result.name);+ expect(top.some(name => route.test(name)), `${query}: ${top.join(', ')}`).toBe(true);+ }+ }, SLOW);+});++describe('search leaf — error paths (pinned)', () => {+ it('throws ERR_INVALID_ARGUMENT when the query is empty/whitespace', async () => {+ await expect(search(' ', {cwd})).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ message: expect.stringMatching(/query is required/i),+ });+ }, SLOW);++ it('throws ERR_INVALID_ARGUMENT for an unknown --type', async () => {+ await expect(+ search('button', {cwd, type: /** @type {any} */ ('bogus')}),+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});+ }, SLOW);++ it('searches the docs without @astryxdesign/core, and throws for a domain that needs it', async () => {+ const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-no-core-'));+ try {+ // An open search outside an app covers the docs, as `astryx docs` does.+ const open = await search('make an integration', {cwd: empty});+ expect(open.data.results.length).toBeGreaterThan(0);+ expect(new Set(open.data.results.map(r => r.domain))).toEqual(+ new Set(['doc']),+ );+ for (const type of ['component', 'hook', 'template']) {+ await expect(+ search('button', {cwd: empty, type: /** @type {any} */ (type)}),+ ).rejects.toMatchObject({code: 'ERR_CORE_NOT_FOUND'});+ }+ } finally {+ fs.rmSync(empty, {recursive: true, force: true});+ }+ }, SLOW);+});++describe('search leaf — limit validation (API matches the CLI contract)', () => {+ it('throws ERR_INVALID_ARGUMENT for a limit of 0 (no longer returns everything)', async () => {+ await expect(search('button', {cwd, limit: 0})).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ });+ }, SLOW);++ it('throws ERR_INVALID_ARGUMENT for a negative limit', async () => {+ await expect(search('button', {cwd, limit: -5})).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ });+ }, SLOW);++ it('throws ERR_INVALID_ARGUMENT for a non-integer limit', async () => {+ await expect(search('button', {cwd, limit: 2.5})).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ });+ }, SLOW);+});++describe('search leaf — integration components', () => {+ /**+ * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`+ * resolves without needing the real package) plus an installed+ * `@acme/widgets` integration that contributes one component.+ */+ function makeConsumerWithIntegrationComponent() {+ const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));+ fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: 'consumer'}));+ fs.writeFileSync(+ path.join(dir, 'astryx.config.mjs'),+ `export default { integrations: ['@acme/widgets'] };\n`,+ );++ // Stub core: just needs to exist with an (empty) src/ so discoverComponents+ // doesn't throw. Its own component list is irrelevant to this test.+ const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');+ fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});++ const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');+ fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});+ fs.writeFileSync(+ path.join(widgetsDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(widgetsDir, 'astryx.integration.mjs'),+ `export default { components: './components' };\n`,+ );+ fs.writeFileSync(+ path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),+ `export default {+ type: 'component',+ name: 'FancyGizmo',+ keywords: ['gizmo', 'widget'],+ usage: {description: 'A fancy gizmo widget.'},+ props: [],+ };\n`,+ );+ fs.writeFileSync(+ path.join(widgetsDir, 'components', 'FancyGizmo.tsx'),+ `export function FancyGizmo() { return null; }\n`,+ );++ return dir;+ }++ it('includes a component contributed by a configured integration', async () => {+ const dir = makeConsumerWithIntegrationComponent();+ try {+ const r = await search('gizmo', {cwd: dir, type: 'component'});+ expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ }, SLOW);++ it('reports the contributing package as the import hint', async () => {+ const dir = makeConsumerWithIntegrationComponent();+ try {+ const r = await search('FancyGizmo', {cwd: dir, type: 'component'});+ const hit = r.data.results.find(x => x.name === 'FancyGizmo');+ expect(hit?.import).toBe('@acme/widgets');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ }, SLOW);+});++describe('search scoring — multi-token aggregation is monotonic', () => {+ /**+ * @param {string} q+ * @param {object} candidate+ * @returns {number}+ */+ const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;++ it('ranks matching both terms above matching only the stronger one', () => {+ // The shipped regression: scoring averaged over MATCHED tokens, so the+ // weaker second hit pulled the mean down further than the coverage bonus+ // pushed it up. `build "file browser"` put two form wizards that matched+ // only "file" (98) above the actual file browser that matched both (97),+ // and 98 clears the confident-match gate.+ const partial = {name: 'form-wizard-vertical', keywords: ['file']};+ const complete = {+ name: 'file-explorer',+ keywords: ['file'],+ description: 'Column browser for nested folders',+ };+ expect(score('file browser', complete)).toBeGreaterThan(score('file browser', partial));+ });++ it('never scores a superset of matched terms below a subset', () => {+ const subset = {name: 'zzz-none', keywords: ['alpha']};+ const supersets = [+ {name: 'zzz-none', keywords: ['alpha'], description: 'beta things'},+ {name: 'zzz-none', keywords: ['alpha', 'beta']},+ {name: 'zzz-none', keywords: ['alpha'], weakKeywords: ['beta']},+ ];+ for (const superset of supersets) {+ expect(score('alpha beta', superset)).toBeGreaterThanOrEqual(score('alpha beta', subset));+ }+ });++ it('still scores a verbose prompt on the concepts it did hit', () => {+ // Guards the reason the mean was used: a long prompt matching one concept+ // strongly must not be crushed by dividing across every query token.+ const candidate = {name: 'kanban', keywords: ['kanban']};+ expect(score('i need a kanban somewhere in this rambling request', candidate))+ .toBeGreaterThanOrEqual(90);+ });+});++describe('search scoring — derived keywords rank below authored ones', () => {+ it('scores an authored keyword above a derived one', () => {+ const authored = scoreCandidate('dialog', {name: 'x', keywords: ['Dialog']});+ const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});+ expect(authored?.score).toBe(90);+ expect(derived?.score).toBe(60);+ });++ it('keeps one incidental derived match below the confident-match gate', () => {+ // PAGE_DIRECT in api/build/kit is 95: at full keyword strength a page that+ // renders one of everything got a 90-point shot per component and was+ // returned as a confident match for queries it had nothing to do with.+ const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});+ expect(derived?.score).toBeLessThan(95);+ });++ it('still surfaces a derived match above the page floor', () => {+ // PAGE_FLOOR is 50 — weakening the signal must not make it invisible.+ const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});+ expect(derived?.score).toBeGreaterThanOrEqual(50);+ });++ it('explains a derived hit as something the template renders', () => {+ const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});+ expect(derived?.reason).toMatch(/renders Dialog/);+ });+});++describe('search — usage guidance is indexed, a tier below description', () => {+ // The vocabulary a reader types usually lives in a component's guidance, not+ // in its one-line description. Banner calls itself "a persistent message";+ // only its best practices name "caution", "problems", "form errors". Before+ // this, none of those words found it.+ const banner = {+ name: 'Banner',+ keywords: ['alert', 'notification'],+ description: 'A persistent message shown above content.',+ guidance: [+ 'Pick a status that matches the message: info for updates, warning for caution.',+ 'Use error for problems the reader must resolve before continuing.',+ ],+ };++ it('finds a term that appears ONLY in guidance', () => {+ // Red before this change: guidance was never read, so this scored null.+ const hit = scoreCandidate('caution', banner);+ expect(hit).not.toBeNull();+ expect(hit?.reason).toMatch(/guidance mentions "caution"/);+ });++ it('scores guidance BELOW description, so a component about X outranks one that merely mentions X', () => {+ const own = scoreCandidate('persistent', banner);+ const mention = scoreCandidate('caution', banner);+ expect(own?.score).toBe(50);+ expect(mention?.score).toBe(45);+ expect(mention.score).toBeLessThan(own.score);+ });++ it('never lets guidance outrank a name or keyword hit', () => {+ expect(scoreCandidate('banner', banner)?.score).toBe(100);+ expect(scoreCandidate('notification', banner)?.score).toBe(90);+ });++ it('prefers the stronger signal when a term is in both description and guidance', () => {+ const both = scoreCandidate('message', banner);+ expect(both?.score).toBe(50);+ expect(both?.reason).toMatch(/description mentions/);+ });++ it('stays below MIN_TOKEN_SCORE, so guidance never counts as a matched CONCEPT', () => {+ // Measured regression this prevents: counting guidance as a matched term+ // moved `nested menu` from SideNav to List, and `explain why a field is+ // required` from Field to TextInput — in both cases a component whose+ // guidance happens to mention the other word displaced the real answer.+ // Guidance decides single-word queries; it must not win multi-word ones on+ // breadth. Same reason weakKeywords are capped.+ expect(scoreCandidate('caution', banner)?.score).toBeLessThan(50);+ // Both words are in this candidate's guidance and nowhere else, so if+ // guidance counted as a concept this would come back as a 2/2 match.+ const multi = scoreQuery('caution problems', tokenizeQuery('caution problems'), banner);+ expect(multi).toBeNull();+ });++ it('lets a real description hit still win the multi-word pass', () => {+ // The floor must exclude guidance without muting the tiers above it.+ const hit = scoreQuery('persistent message', tokenizeQuery('persistent message'), banner);+ expect(hit?.reason).toMatch(/matches 2\/2 terms/);+ });++ it('tolerates the object-shaped bestPractices entries core actually ships', () => {+ // Core writes `{guidance: true, description: '...'}`, not plain strings.+ const hit = scoreCandidate('resolve', {+ name: 'X',+ guidance: ['Use error for problems the reader must resolve.'],+ });+ expect(hit?.score).toBe(45);+ });+});diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjsnew file mode 100644index 0000000000..50faea28d0--- /dev/null+++ b/packages/cli/clients/cli/commands/docs.test.mjs@@ -0,0 +1,383 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {Command} from 'commander';+import {formatBlock, registerDocs} from './docs.mjs';+import {runCli} from '../../../test-utils/run-cli.mjs';+import {displayWidth} from '../formatters/index.mjs';++let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));+ vi.spyOn(console, 'log').mockImplementation(() => {});+ vi.spyOn(console, 'error').mockImplementation(() => {});+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ vi.restoreAllMocks();+});++function createProgram() {+ const program = new Command();+ program.exitOverride(); // Throw instead of calling process.exit+ registerDocs(program);+ return program;+}++describe('registerDocs', () => {+ it('lists available topics when no topic given', async () => {+ const program = createProgram();+ await program.parseAsync(['node', 'astryx', 'docs']);++ const output = console.log.mock.calls.map(c => c[0]).join('\n');+ expect(output).toContain('principles');+ expect(output).toContain('tokens');+ expect(output).not.toContain('shadcn-compatibility');+ });++ it('errors for unknown topic', async () => {+ const program = createProgram();+ vi.spyOn(process, 'exit').mockImplementation(code => {+ throw new Error(`exit ${code}`);+ });++ await expect(+ program.parseAsync(['node', 'astryx', 'docs', 'nonexistent']),+ ).rejects.toThrow('exit 1');++ const errorOutput = console.error.mock.calls.map(c => c[0]).join('\n');+ expect(errorOutput).toContain('Unknown topic');+ });+});++describe('hyphenated doc filenames', () => {+ it('lists hyphenated topics like getting-started', async () => {+ const program = createProgram();+ await program.parseAsync(['node', 'astryx', 'docs']);++ const output = console.log.mock.calls.map(c => c[0]).join('\n');+ expect(output).toContain('getting-started');+ });++ it('loads a hyphenated topic by name', async () => {+ const program = createProgram();+ await program.parseAsync(['node', 'astryx', 'docs', 'getting-started']);++ const output = console.log.mock.calls.map(c => c[0]).join('\n');+ expect(output.length).toBeGreaterThan(0);+ expect(console.error).not.toHaveBeenCalled();+ });++ it('returns docs.detail via API for hyphenated topic', async () => {+ const {docs: docsApi} = await import('../../../api/docs/docs.mjs');+ const result = await docsApi('getting-started', undefined, {full: true});+ expect(result.type).toBe('docs.detail');+ expect(result.data).toBeDefined();+ expect(result.data.description).toBeDefined();+ });+});++describe('migration docs', () => {+ it('lists the migration topic', async () => {+ const program = createProgram();+ await program.parseAsync(['node', 'astryx', 'docs']);++ const output = console.log.mock.calls.map(c => c[0]).join('\n');+ expect(output).toContain('migration');+ expect(output).toContain('Tailwind');+ });++ it('loads migration docs by topic name', async () => {+ const program = createProgram();+ await program.parseAsync(['node', 'astryx', 'docs', 'migration']);++ const output = console.log.mock.calls.map(c => c[0]).join('\n');+ expect(output).toContain('Migration Guide');+ expect(output).toContain('Recommended Order');+ expect(output).toContain('Map shadcn and Radix Primitives');+ });+});++describe('progressive reads', () => {+ const SLOW = 60_000;+ /** @param {string} out */+ const widest = out => Math.max(...out.split('\n').map(line => line.length));++ it('lists every topic on one line each', async () => {+ const {status, stdout} = await runCli(['docs']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^principles +\S/m);+ expect(widest(stdout)).toBeLessThanOrEqual(120);+ expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');+ }, SLOW);++ it("prints a topic's section index with the keys to read by", async () => {+ const {status, stdout} = await runCli(['docs', 'theme', '--index']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^quick-start +Wrap your app in a theme/m);+ expect(stdout).toContain('docs theme <section>');+ expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);+ expect(widest(stdout)).toBeLessThanOrEqual(120);+ }, SLOW);++ it('prints one section by its key', async () => {+ const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^## Wrap your app in a theme/m);+ }, SLOW);++ it("lists a topic's sections by default; --full prints the whole topic", async () => {+ const index = await runCli(['docs', 'theme', '--index']);+ expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);+ const full = await runCli(['docs', 'theme', '--full']);+ expect(full.status).toBe(0);+ expect(full.stdout).toMatch(/^## Wrap your app in a theme/m);+ expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);+ expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(+ full.stdout,+ );+ }, SLOW);++ it('returns the matching envelopes as JSON', async () => {+ const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);+ // JSON keeps docs(): a bare read is the whole topic.+ expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');+ expect((await envelope(['docs', 'theme', '--full'])).type).toBe('docs.detail');+ expect((await envelope(['docs', 'theme', '--index'])).type).toBe(+ 'docs.index',+ );+ expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(+ 'docs.detail.section',+ );+ }, SLOW);+});++describe('blocks as text', () => {+ const SLOW = 60_000;++ it('prints a code label above the fence, never inside it', () => {+ for (const lang of ['bash', 'css', 'json', 'html', 'text', 'tsx']) {+ expect(+ formatBlock({type: 'code', lang, label: 'Terminal', code: 'x'}, 'full'),+ ).toBe(`Terminal:\n\`\`\`${lang}\nx\n\`\`\``);+ }+ expect(formatBlock({type: 'code', lang: 'bash', code: 'x'}, 'full')).toBe(+ '```bash\nx\n```',+ );+ // A label that already ends in a colon does not get a second one.+ expect(+ formatBlock({type: 'code', lang: 'css', label: 'globals.css:', code: 'x'}, 'full'),+ ).toBe('globals.css:\n```css\nx\n```');+ });++ it('escapes pipes in table cells, so a union type stays one column', () => {+ const table = {+ type: /** @type {const} */ ('table'),+ headers: ['Prop', 'Type', 'Default'],+ rows: [+ ['mode', "'system' | 'light' | 'dark'", "'system'"],+ ['theme', 'DefinedTheme', '-'],+ ],+ };+ const lines = /** @type {string} */ (formatBlock(table, 'full')).split('\n');+ expect(lines).toHaveLength(4);+ // Every line has exactly two column separators, all at the same place.+ for (const line of lines) expect(line.split(' | ')).toHaveLength(3);+ expect(new Set(lines.map(line => line.indexOf(' | '))).size).toBe(1);+ expect(lines[2]).toContain("'system' \\| 'light' \\| 'dark'");+ expect(formatBlock(table, 'brief')).toBe(+ "mode='system' \\| 'light' \\| 'dark' | theme=DefinedTheme",+ );+ });++ it('prints the labels of a real section above their fences', async () => {+ const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);+ expect(status).toBe(0);+ expect(stdout).toContain('Install a theme package:\n```bash\nnpm install');+ expect(stdout).not.toContain('// Install a theme package');+ }, SLOW);+});++describe('the docs tree, one level at a time', () => {+ const SLOW = 60_000;+ /** @param {string} out */+ const widest = out => Math.max(...out.split('\n').map(line => line.length));++ it('lists the docs tree first, under its own heading, then the topics', async () => {+ const {status, stdout} = await runCli(['docs']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^Docs tree$/m);+ expect(stdout).toMatch(/^Topics$/m);+ expect(stdout).toMatch(/^cli +Commands, programmatic APIs/m);+ expect(stdout.indexOf('\ncli ')).toBeLessThan(stdout.indexOf('\nprinciples '));+ expect(stdout).not.toMatch(/^cli-integrations /m);+ }, SLOW);++ it("shows a child's own name when its route name does not spell it", async () => {+ const {status, stdout} = await runCli(['docs', 'cli/api/functions']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^assert-response +assertResponse\(\): \S/m);+ expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);+ }, SLOW);++ it('wraps namespace summaries without discarding searchable words', async () => {+ const {status, stdout} = await runCli([+ 'docs',+ 'cli/integrations/building-blocks/templates',+ ]);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);+ expect(stdout).not.toMatch(/^start-a-template +Start a template:/m);+ expect(stdout).toMatch(/full page or page\s+section\./);+ expect(widest(stdout)).toBeLessThanOrEqual(120);+ }, SLOW);++ it('prints a namespace: each slot, its children, and how to go down and up', async () => {+ const {status, stdout} = await runCli(['docs', 'cli/api']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^API$/m);+ expect(stdout).toMatch(/^Reference$/m);+ expect(stdout).toMatch(/^functions +Every function/m);+ expect(stdout).toMatch(/^schemas +/m);+ expect(stdout).toMatch(/^enums +/m);+ // One level only: no function is listed on the api page.+ expect(stdout).not.toMatch(/^search +/m);+ expect(stdout).toMatch(/Open one: .*docs cli\/api\/<name>$/m);+ expect(stdout).toMatch(/Up: .*docs cli$/m);+ expect(widest(stdout)).toBeLessThanOrEqual(120);+ }, SLOW);++ it('prints a typed doc and the way back up', async () => {+ const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);+ expect(status).toBe(0);+ expect(stdout).toMatch(/^## search\(\)/m);+ expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');+ expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);+ }, SLOW);++ it('reads the dense variant whole, asked with --dense or with --lang dense', async () => {+ for (const args of [['--dense', 'docs', 'theme'], ['--lang', 'dense', 'docs', 'theme']]) {+ const {status, stdout} = await runCli(args);+ expect(status).toBe(0);+ expect(stdout).not.toContain('Read one section:');+ }+ }, SLOW);++ it('refuses --index with --full', async () => {+ const both = await runCli(['docs', 'theme', '--index', '--full', '--json']);+ expect(both.status).toBe(1);+ expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');+ }, SLOW);++ it('reads the integration guides by their routes, and not by the old name', async () => {+ // cli/integrations is a namespace: one level, its guides by slot.+ const level = await runCli(['docs', 'cli/integrations']);+ expect(level.status).toBe(0);+ expect(level.stdout).toMatch(+ /^quick-start +Create a new integration package/m,+ );+ expect(level.stdout).toMatch(/^building-blocks +/m);+ const guide = await runCli([+ 'docs',+ 'cli/integrations/building-blocks/codemods',+ '--index',+ ]);+ expect(guide.status).toBe(0);+ expect(guide.stdout).toMatch(+ /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,+ );+ // A bare read is one level too: the sections, and how to read it all.+ const bare = await runCli([+ 'docs',+ 'cli/integrations/building-blocks/codemods',+ ]);+ expect(bare.status).toBe(0);+ expect(bare.stdout).toBe(guide.stdout);+ expect(bare.stdout).toMatch(+ /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,+ );+ const one = await runCli([+ 'docs',+ 'cli/integrations/building-blocks/codemods',+ 'which-codemods-run',+ ]);+ expect(one.status).toBe(0);+ expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);+ expect(one.stdout).toMatch(+ /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,+ );+ expect(one.stdout).toMatch(+ /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,+ );+ expect(one.stdout).toMatch(+ /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,+ );+ const full = await runCli([+ 'docs',+ 'cli/integrations/building-blocks/codemods',+ '--full',+ ]);+ expect(full.status).toBe(0);+ expect(full.stdout).toMatch(/^## Add a codemod$/m);+ expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 2);+ const old = await runCli(['docs', 'cli-integrations']);+ expect(old.status).toBe(1);+ expect(old.stderr).toContain('Unknown topic "cli-integrations"');+ }, SLOW);++ it('returns docs.node as JSON, and fails a section of a namespace', async () => {+ const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);+ expect(node).toMatchObject({+ type: 'docs.node',+ data: {route: 'cli', kind: 'namespace', breadcrumb: []},+ });+ expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);+ const section = await runCli(['docs', 'cli', 'commands', '--json']);+ expect(section.status).toBe(1);+ const error = JSON.parse(section.stdout);+ expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});+ // It names the namespace's children, in the order its slots list them.+ expect(error.suggestions.map(s => s.name)).toEqual(+ node.data.slots.flatMap(slot => slot.children.map(child => child.route)),+ );+ expect(error.suggestions.map(s => s.name)).toContain('cli/commands');+ }, SLOW);+});++describe('text width in every language', () => {+ const SLOW = 60_000;+ /** Widest line outside code blocks, in terminal columns. */+ const widest = out => {+ let inCode = false;+ let max = 0;+ for (const line of out.split('\n')) {+ if (/^\s*```/.test(line)) {+ inCode = !inCode;+ continue;+ }+ // A single unbreakable token (a long URL) cannot wrap without breaking it.+ const oneToken = !/\s/.test(line.trim());+ if (!inCode && !line.startsWith('#') && !oneToken) {+ max = Math.max(max, displayWidth(line));+ }+ }+ return max;+ };++ it('keeps the additive section index within 120 columns', async () => {+ const {status, stdout} = await runCli([+ 'docs',+ 'theme',+ '--index',+ '--lang',+ 'zh',+ ]);+ expect(status).toBe(0);+ expect(widest(stdout)).toBeLessThanOrEqual(120);+ }, SLOW);+});diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjsnew file mode 100644index 0000000000..6413db590c--- /dev/null+++ b/packages/cli/foundation/agent-docs/agent-docs.test.mjs@@ -0,0 +1,1160 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {+ generateCompressedIndex,+ detectStylingSystem,+ getXdsVersion,+ installAgentDocs,+ injectAgentsMd,+ injectClaudeMd,+ injectXdsBlock,+ removeAgentDocs,+ removeXdsBlock,+ discoverAgentDocs,+ resolveAgentPaths,+ parseBlockVersion,+ renderAgentDocsBlock,+ inspectAgentDocs,+ isAstryxInitialized,+} from './agent-docs.mjs';++let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ vi.restoreAllMocks();+});++describe('generateCompressedIndex', () => {+ it('includes the version number', () => {+ const result = generateCompressedIndex('1.2.3');+ expect(result).toContain('Astryx v1.2.3');+ expect(result).toContain('<!-- ASTRYX:START -->');+ expect(result).toContain('<!-- ASTRYX:END -->');+ });++ it('includes theme nudge rule', () => {+ const result = generateCompressedIndex('1.0.0');+ expect(result).toMatch(/astryx theme/);+ expect(result).toMatch(/never override --color-/);+ });++ it('sends frame choice to the layout doc rather than naming a shell', () => {+ const result = generateCompressedIndex('1.0.0');+ const frameRule = result.split('\n').find(l => l.includes('Frame first'));+ expect(frameRule).toContain('astryx docs layout');+ expect(result).not.toMatch(/AppShell/);+ expect(frameRule).not.toMatch(/https?:/);+ });++ it('starts every page from a template before any component', () => {+ const lines = generateCompressedIndex('1.0.0').split('\n');+ const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));+ expect(lines[workflow]).toMatch(/start every page from a template/);+ expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);+ expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);+ expect(lines.join('\n')).not.toMatch(/reference code/);+ });++ it('includes the post-generation self-check rule', () => {+ const result = generateCompressedIndex('1.0.0');+ expect(result).toContain('SELF-CHECK before you finish');+ expect(result).toMatch(/re-read the file/);+ expect(result).toMatch(/don't hand-roll CSS/);+ });++ it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {+ // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token+ const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});+ const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));+ expect(stylexSelfCheck).toMatch(/xstyle/);+ expect(stylexSelfCheck).toMatch(/className=/);+ // className IS the system in Tailwind — it must NOT be flagged+ const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});+ const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));+ expect(tailwindSelfCheck).toBeDefined();+ expect(tailwindSelfCheck).not.toMatch(/className=/);+ });++ it('defaults to the CSS-variable styling path (no compiler)', () => {+ const result = generateCompressedIndex('1.0.0');+ expect(result).toMatch(/style\/className with tokens/);+ expect(result).toMatch(/var\(--color-\*/);+ // Must NOT push xstyle when no StyleX compiler is present.+ expect(result).not.toMatch(/xstyle prop/);+ });++ it('recommends xstyle when StyleX is configured', () => {+ const result = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});+ expect(result).toMatch(/xstyle prop \/ StyleX tokens/);+ });++ it('recommends Tailwind utilities when Tailwind is configured', () => {+ const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});+ expect(result).toMatch(/Tailwind utilities backed by tokens/);+ expect(result).toMatch(/tailwind-theme\.css/);+ });++ it('includes upgrade command and migration rule', () => {+ const result = generateCompressedIndex('1.0.0');+ // `upgrade --apply` alone stops with "Missing required --from".+ expect(result).toContain('upgrade --from <old version> --apply');+ expect(result).toMatch(/after any Astryx or integration dependency bump/);+ });++ it('states the invocation once in the CLI header (yarn)', () => {+ const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});+ expect(result).toContain('yarn astryx <cmd>');+ expect(result).not.toContain('npx astryx');+ });++ it('uses the pnpm exec invocation', () => {+ const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});+ expect(result).toContain('pnpm exec astryx <cmd>');+ expect(result).not.toContain('npx astryx');+ });++ it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {+ const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});+ expect(result).toContain('npx @astryxdesign/cli <cmd>');+ // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.+ expect(result).not.toContain('npx astryx <cmd>');+ });++ /** The `docs <topic> a, b, c` line of the block. */+ function topicLine(block) {+ return (+ block.split('\n').find(line => line.trimStart().startsWith('docs <topic>')) ?? ''+ );+ }++ it('names the hyphenated topics, which the scan used to drop', () => {+ // The fallback scan matched `\w+`, which does not match `-`, so five real+ // topics were missing from every block ever written. An agent cannot ask+ // for a topic it was never told about, and `getting-started` — the one it+ // should reach for first — was one of them.+ const line = topicLine(generateCompressedIndex('1.0.0'));+ for (const topic of [+ 'getting-started',+ 'browser-support',+ 'styling-libraries',+ 'working-with-ai',+ ]) {+ expect(line).toContain(topic);+ }+ });++ it('points to the CLI docs tree on a line of its own', () => {+ // The integration guide lives in the docs tree now (cli/integrations), so+ // the topic line no longer names it; the tree's entry point does.+ const block = generateCompressedIndex('1.0.0');+ expect(block).toContain(+ ' docs cli commands, API reference, integration authoring (one level at a time)',+ );+ expect(topicLine(block)).not.toContain('cli-integrations');+ });++ it('lists the topics it is given, so an integration’s reach the agent', () => {+ const line = topicLine(+ generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),+ );+ expect(line).toContain('tokens, deploying');+ // The project's catalog replaces the built-in scan rather than adding to it:+ // a topic an integration replaced must not also be listed under its old name.+ expect(line).not.toContain('typography');+ });++ it('omits the line entirely when the project has no topics', () => {+ expect(topicLine(generateCompressedIndex('1.0.0', {topics: []}))).toBe('');+ });++ it('is byte-identical when integrations contribute no lines', () => {+ const options = {+ invocation: 'npx @astryxdesign/cli',+ stylingSystem: 'css',+ topics: ['tokens', 'working-with-ai'],+ };+ expect(generateCompressedIndex('1.0.0', {...options, agentDocs: []})).toBe(+ generateCompressedIndex('1.0.0', options),+ );+ });++ it('appends package-labeled lines after core guidance in config order', () => {+ const result = generateCompressedIndex('1.0.0', {+ topics: [],+ agentDocs: [+ {+ package: '@acme/second',+ append: ['second one', 'second two'],+ },+ {+ package: '@acme/first',+ append: ['first one'],+ },+ ],+ });++ expect(result.indexOf('upgrade --from <old version> --apply')).toBeLessThan(+ result.indexOf('INTEGRATIONS:'),+ );+ expect(result.indexOf('INTEGRATIONS:')).toBeLessThan(+ result.indexOf('<!-- ASTRYX:END -->'),+ );+ expect(result).toContain(+ 'INTEGRATIONS:\n' ++ '- `@acme/second`: second one\n' ++ '- `@acme/second`: second two\n' ++ '- `@acme/first`: first one',+ );+ });++ it('caps the configured project at 32 integration lines', () => {+ const agentDocs = Array.from({length: 5}, (_, packageIndex) => ({+ package: `@acme/package-${packageIndex}`,+ append: Array.from(+ {length: packageIndex === 4 ? 1 : 8},+ (_, lineIndex) => `line ${lineIndex}`,+ ),+ }));+ expect(() => generateCompressedIndex('1.0.0', {agentDocs})).toThrow(+ /32-line project limit/,+ );+ });+});++describe('renderAgentDocsBlock', () => {+ it('produces repeatable target bytes from configured manifests', async () => {+ const projectDir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-agent-doc-render-'),+ );+ try {+ fs.writeFileSync(+ path.join(projectDir, 'package.json'),+ JSON.stringify({name: 'consumer'}),+ );+ fs.writeFileSync(+ path.join(projectDir, 'astryx.config.mjs'),+ `export default {integrations: ['@acme/second', '@acme/first']};\n`,+ );+ const coreDir = path.join(+ projectDir,+ 'node_modules',+ '@astryxdesign',+ 'core',+ );+ fs.mkdirSync(coreDir, {recursive: true});+ fs.writeFileSync(+ path.join(coreDir, 'package.json'),+ JSON.stringify({name: '@astryxdesign/core', version: '1.0.0'}),+ );+ for (const [name, agentDocs] of [+ ['@acme/second', {append: ['second one', 'second two']}],+ ['@acme/first', {append: ['first one']}],+ ]) {+ const packageDir = path.join(+ projectDir,+ 'node_modules',+ ...name.split('/'),+ );+ fs.mkdirSync(packageDir, {recursive: true});+ fs.writeFileSync(+ path.join(packageDir, 'package.json'),+ JSON.stringify({name}),+ );+ fs.writeFileSync(+ path.join(packageDir, 'astryx.integration.mjs'),+ `export default {agentDocs: ${JSON.stringify(agentDocs)}};\n`,+ );+ }+ fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), '# Agents\n');+ fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Claude\n');++ const renderedBlock = await renderAgentDocsBlock(projectDir);+ expect(renderedBlock.indexOf('second one')).toBeLessThan(+ renderedBlock.indexOf('second two'),+ );+ expect(renderedBlock.indexOf('second two')).toBeLessThan(+ renderedBlock.indexOf('first one'),+ );++ installAgentDocs(projectDir, {renderedBlock});+ const firstAgents = fs.readFileSync(+ path.join(projectDir, 'AGENTS.md'),+ 'utf-8',+ );+ const firstClaude = fs.readFileSync(+ path.join(projectDir, 'CLAUDE.md'),+ 'utf-8',+ );+ expect(firstAgents).toContain(renderedBlock);+ expect(firstClaude).toContain(renderedBlock);++ installAgentDocs(projectDir, {renderedBlock});+ expect(fs.readFileSync(path.join(projectDir, 'AGENTS.md'), 'utf-8')).toBe(+ firstAgents,+ );+ expect(fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8')).toBe(+ firstClaude,+ );+ } finally {+ fs.rmSync(projectDir, {recursive: true, force: true});+ }+ });+ it('rejects a package label that could alter managed block structure', async () => {+ const projectDir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-agent-doc-label-'),+ );+ try {+ fs.writeFileSync(+ path.join(projectDir, 'package.json'),+ JSON.stringify({name: 'consumer'}),+ );+ fs.writeFileSync(+ path.join(projectDir, 'astryx.config.mjs'),+ `export default {integrations: ['@acme/widgets']};\n`,+ );+ const packageDir = path.join(+ projectDir,+ 'node_modules',+ '@acme',+ 'widgets',+ );+ fs.mkdirSync(packageDir, {recursive: true});+ fs.writeFileSync(+ path.join(packageDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets\nASTRYX:END'}),+ );+ fs.writeFileSync(+ path.join(packageDir, 'astryx.integration.mjs'),+ `export default {agentDocs: {append: ['safe line']}};\n`,+ );++ await expect(renderAgentDocsBlock(projectDir)).rejects.toThrow(+ /not safe to render/,+ );+ } finally {+ fs.rmSync(projectDir, {recursive: true, force: true});+ }+ });+});++describe('detectStylingSystem', () => {+ function writePkg(deps) {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: 'x', devDependencies: deps}),+ );+ }++ it('defaults to css when no package.json', () => {+ expect(detectStylingSystem(tmpDir)).toBe('css');+ });++ it('returns css for a plain project', () => {+ writePkg({react: '19.0.0', vite: '6.0.0'});+ expect(detectStylingSystem(tmpDir)).toBe('css');+ });++ it('detects stylex when the compiler plugin is present', () => {+ writePkg({'@stylexjs/babel-plugin': '0.0.1'});+ expect(detectStylingSystem(tmpDir)).toBe('stylex');+ });++ it('detects tailwind when tailwindcss is present', () => {+ writePkg({tailwindcss: '4.0.0'});+ expect(detectStylingSystem(tmpDir)).toBe('tailwind');+ });++ it('does NOT treat the StyleX runtime alone as a compiler', () => {+ // Only the runtime, no compiler plugin → must stay on the safe css path.+ writePkg({'@stylexjs/stylex': '0.0.1'});+ expect(detectStylingSystem(tmpDir)).toBe('css');+ });++ it('prefers stylex over tailwind when both are configured', () => {+ writePkg({'@stylexjs/babel-plugin': '0.0.1', tailwindcss: '4.0.0'});+ expect(detectStylingSystem(tmpDir)).toBe('stylex');+ });+});++describe('getXdsVersion', () => {+ it('reads version from core package.json', () => {+ const coreDir = path.join(tmpDir, 'core');+ fs.mkdirSync(coreDir, {recursive: true});+ fs.writeFileSync(+ path.join(coreDir, 'package.json'),+ JSON.stringify({version: '3.4.5'}),+ );++ expect(getXdsVersion(coreDir)).toBe('3.4.5');+ });+});++describe('injectXdsBlock', () => {+ it('injects into an existing file without markers', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, '# Existing content\n');++ const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');++ expect(result).toBe(true);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('# Existing content');+ expect(content).toContain('<!-- ASTRYX:START -->');+ });++ it('replaces existing markers', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');++ injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');++ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('new');+ expect(content).not.toContain('old');+ expect(content).toContain('before');+ expect(content).toContain('after');+ });++ it('returns false and does not create file when createIfMissing is false', () => {+ const filePath = path.join(tmpDir, 'nonexistent.md');++ const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->');++ expect(result).toBe(false);+ expect(fs.existsSync(filePath)).toBe(false);+ });++ it('skips files without markers when onlyReplace is true', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');++ const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});++ expect(result).toBe(false);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).not.toContain('<!-- ASTRYX:START -->');+ expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');+ });++ it('replaces existing markers even when onlyReplace is true', () => {+ const filePath = path.join(tmpDir, 'test.md');+ fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');++ const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});++ expect(result).toBe(true);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('new');+ expect(content).not.toContain('old');+ });++ it('creates file when createIfMissing is true', () => {+ const filePath = path.join(tmpDir, 'new.md');++ const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->', {+ createIfMissing: true,+ header: '# Header',+ });++ expect(result).toBe(true);+ const content = fs.readFileSync(filePath, 'utf-8');+ expect(content).toContain('# Header');+ expect(content).toContain('<!-- ASTRYX:START -->');+ });+});++describe('injectAgentsMd', () => {+ it('creates new AGENTS.md when none exists', () => {+ injectAgentsMd(tmpDir, '1.0.0');++ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('# AGENTS.md');+ expect(content).toContain('<!-- ASTRYX:START -->');+ expect(content).toContain('Astryx v1.0.0');+ expect(content).toContain('<!-- ASTRYX:END -->');+ });++ it('updates existing AGENTS.md by replacing XDS markers', () => {+ const existing = `# My Project++Some content.++<!-- XDS:START -->+old content+<!-- XDS:END -->++More stuff.+`;+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);++ injectAgentsMd(tmpDir, '2.0.0');++ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('Astryx v2.0.0');+ expect(content).not.toContain('old content');+ expect(content).toContain('Some content.');+ expect(content).toContain('More stuff.');+ });++ it('appends to existing AGENTS.md without markers', () => {+ const existing = `# My Project++Existing agent docs.+`;+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);++ injectAgentsMd(tmpDir, '1.0.0');++ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('Existing agent docs.');+ expect(content).toContain('<!-- ASTRYX:START -->');+ expect(content).toContain('Astryx v1.0.0');+ });+});++describe('injectClaudeMd', () => {+ it('injects into existing CLAUDE.md', () => {+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude Config\n\nExisting rules.\n');++ const result = injectClaudeMd(tmpDir, '1.0.0');++ expect(result).toBe(true);+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('# Claude Config');+ expect(content).toContain('Existing rules.');+ expect(content).toContain('<!-- ASTRYX:START -->');+ expect(content).toContain('Astryx v1.0.0');+ });++ it('does not create CLAUDE.md when it does not exist', () => {+ const result = injectClaudeMd(tmpDir, '1.0.0');++ expect(result).toBe(false);+ expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);+ });++ it('updates existing markers in CLAUDE.md', () => {+ const existing = `# Claude Config++<!-- XDS:START -->+old content+<!-- XDS:END -->++Other rules.+`;+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), existing);++ injectClaudeMd(tmpDir, '2.0.0');++ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('Astryx v2.0.0');+ expect(content).not.toContain('old content');+ expect(content).toContain('Other rules.');+ });+});++describe('removeAgentDocs', () => {+ it('removes XDS section from AGENTS.md', () => {+ const content = `# My Project++Custom content here.++<!-- XDS:START -->+XDS index stuff+<!-- XDS:END -->++More custom content.+`;+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);+ vi.spyOn(console, 'log').mockImplementation(() => {});++ removeAgentDocs(tmpDir);++ const result = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(result).toContain('Custom content here.');+ expect(result).toContain('More custom content.');+ expect(result).not.toContain('<!-- XDS:START -->');+ expect(result).not.toContain('XDS index stuff');+ });++ it('removes the file entirely when only XDS content remains', () => {+ const content = `# AGENTS.md++Project-specific guidance for AI coding agents.++<!-- XDS:START -->+XDS index stuff+<!-- XDS:END -->+`;+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);+ vi.spyOn(console, 'log').mockImplementation(() => {});++ removeAgentDocs(tmpDir);++ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);+ });++ it('removes XDS section from CLAUDE.md when present', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ '# AGENTS.md\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n',+ );+ fs.writeFileSync(+ path.join(tmpDir, 'CLAUDE.md'),+ '# Claude\n\nRules.\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n\nMore rules.\n',+ );+ vi.spyOn(console, 'log').mockImplementation(() => {});++ removeAgentDocs(tmpDir);++ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(claudeContent).toContain('Rules.');+ expect(claudeContent).toContain('More rules.');+ expect(claudeContent).not.toContain('<!-- XDS:START -->');+ });+});++describe('installAgentDocs', () => {+ function setupCorePackage(dir, version = '1.0.0') {+ // Create a minimal @astryxdesign/core so getXdsVersion works+ const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');+ fs.mkdirSync(coreDir, {recursive: true});+ fs.writeFileSync(+ path.join(coreDir, 'package.json'),+ JSON.stringify({version}),+ );+ }++ it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);+ // Must NOT create the Claude-specific file by default.+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);+ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('# AGENTS.md');+ expect(content).toContain('<!-- ASTRYX:START -->');+ });++ it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {+ // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.+ setupCorePackage(tmpDir);+ expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);++ // Explicit Claude: the Claude-specific file, in a fresh project.+ const claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-claude-'));+ setupCorePackage(claudeDir);+ try {+ expect(installAgentDocs(claudeDir, {agent: 'claude'})).toEqual(['.claude/CLAUDE.md']);+ expect(fs.existsSync(path.join(claudeDir, 'AGENTS.md'))).toBe(false);+ } finally {+ fs.rmSync(claudeDir, {recursive: true, force: true});+ }+ });++ it('injects into CLAUDE.md at root when it exists', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['CLAUDE.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);+ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(claudeContent).toContain('<!-- ASTRYX:START -->');+ expect(claudeContent).toContain('Project rules.');+ });++ it('injects into all existing agent doc files', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toContain('AGENTS.md');+ expect(written).toContain('CLAUDE.md');+ const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(agentsContent).toContain('<!-- ASTRYX:START -->');+ expect(claudeContent).toContain('<!-- ASTRYX:START -->');+ });++ it('preserves import wrappers while initializing standalone files', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');+ const wrapper = '@../AGENTS.md\n';+ fs.writeFileSync(wrapperPath, wrapper);+ fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['AGENTS.md', '.cursorrules']);+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);+ expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ expect(fs.readFileSync(path.join(tmpDir, '.cursorrules'), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ });++ it('keeps cyclic imports standalone when another file exists', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '@CLAUDE.md\n');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '@AGENTS.md\n');+ fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', '.cursorrules']);+ for (const rel of written) {+ expect(fs.readFileSync(path.join(tmpDir, rel), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ }+ });++ it('removes a managed block previously expanded into an import wrapper', () => {+ setupCorePackage(tmpDir);+ installAgentDocs(tmpDir, {agent: 'codex'});+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');+ const wrapper = '@../AGENTS.md\n';+ fs.writeFileSync(wrapperPath, wrapper);+ installAgentDocs(tmpDir, {agent: 'claude'});+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );++ const written = installAgentDocs(tmpDir, {onlyReplace: true});++ expect(written).toContain('AGENTS.md');+ expect(written).toContain('.claude/CLAUDE.md');+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);+ });++ it('refuses a malformed managed block inside an import wrapper', () => {+ setupCorePackage(tmpDir);+ installAgentDocs(tmpDir, {agent: 'codex'});+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, '.claude', 'CLAUDE.md'),+ '@../AGENTS.md\n<!-- ASTRYX:START -->\nincomplete\n',+ );++ expect(() => installAgentDocs(tmpDir)).toThrow(/malformed|no matching/i);+ });++ it('updates existing .claude/CLAUDE.md', () => {+ setupCorePackage(tmpDir);+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Project\n\nExisting content.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['.claude/CLAUDE.md']);+ const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('Existing content.');+ expect(content).toContain('<!-- ASTRYX:START -->');+ });++ it('respects --agent claude preset: finds existing CLAUDE.md', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nRules.\n');++ const written = installAgentDocs(tmpDir, {agent: 'claude'});++ expect(written).toEqual(['CLAUDE.md']);+ });++ it('respects --agent claude preset: creates .claude/CLAUDE.md when nothing exists', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'claude'});++ expect(written).toEqual(['.claude/CLAUDE.md']);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);+ });++ it('respects --agent codex preset: creates AGENTS.md', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'codex'});++ expect(written).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);+ });++ it('respects --agent hermes preset: creates AGENTS.md', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'hermes'});++ expect(written).toEqual(['AGENTS.md']);+ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('<!-- ASTRYX:START -->');+ expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);+ });++ it('respects --agent muse preset: creates AGENTS.md', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {agent: 'muse'});++ expect(written).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);+ });++ it('respects explicit --paths', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {paths: ['custom/AGENT.md']});++ expect(written).toEqual(['custom/AGENT.md']);+ expect(fs.existsSync(path.join(tmpDir, 'custom', 'AGENT.md'))).toBe(true);+ });++ it('onlyReplace: skips files without XDS markers', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules only.\n');++ const written = installAgentDocs(tmpDir, {onlyReplace: true});++ expect(written).toEqual([]);+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).not.toContain('<!-- ASTRYX:START -->');+ expect(content).toBe('# Claude\n\nProject rules only.\n');+ });++ it('onlyReplace: updates files that have XDS markers', () => {+ setupCorePackage(tmpDir, '2.0.0');+ fs.writeFileSync(+ path.join(tmpDir, 'CLAUDE.md'),+ '# Claude\n\n<!-- XDS:START -->\nPLACEHOLDER_STALE_CONTENT\n<!-- XDS:END -->\n\nOther rules.\n',+ );++ const written = installAgentDocs(tmpDir, {onlyReplace: true});++ expect(written).toEqual(['CLAUDE.md']);+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');+ expect(content).toContain('Astryx v2.0.0');+ expect(content).not.toContain('PLACEHOLDER_STALE_CONTENT');+ expect(content).toContain('Other rules.');+ });++ it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {+ setupCorePackage(tmpDir);++ const written = installAgentDocs(tmpDir, {onlyReplace: true});++ expect(written).toEqual([]);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);+ });+});++describe('discoverAgentDocs', () => {+ it('finds AGENTS.md and CLAUDE.md at root', () => {+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');++ const found = discoverAgentDocs(tmpDir);++ expect(found).toContain('AGENTS.md');+ expect(found).toContain('CLAUDE.md');+ });++ it('finds .claude/CLAUDE.md', () => {+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '');++ const found = discoverAgentDocs(tmpDir);++ expect(found).toContain('.claude/CLAUDE.md');+ });++ it('returns empty when nothing exists', () => {+ expect(discoverAgentDocs(tmpDir)).toEqual([]);+ });+});++describe('resolveAgentPaths', () => {+ it('claude preset finds existing CLAUDE.md at root', () => {+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');+ const result = resolveAgentPaths(tmpDir, 'claude');+ expect(result).toEqual({inject: ['CLAUDE.md'], create: []});+ });++ it('claude preset falls back to .claude/CLAUDE.md', () => {+ const result = resolveAgentPaths(tmpDir, 'claude');+ expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});+ });++ it('all preset discovers existing files', () => {+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');+ const result = resolveAgentPaths(tmpDir, 'all');+ expect(result.inject).toContain('AGENTS.md');+ expect(result.inject).toContain('CLAUDE.md');+ expect(result.create).toEqual([]);+ });++ it('all preset creates defaults when nothing exists', () => {+ const result = resolveAgentPaths(tmpDir, 'all');+ expect(result.inject).toEqual([]);+ expect(result.create).toContain('AGENTS.md');+ expect(result.create).toContain('.claude/CLAUDE.md');+ });++ it('hermes preset creates AGENTS.md when nothing exists', () => {+ const result = resolveAgentPaths(tmpDir, 'hermes');+ expect(result).toEqual({inject: [], create: ['AGENTS.md']});+ });++ it('hermes preset finds existing .hermes.md', () => {+ fs.writeFileSync(path.join(tmpDir, '.hermes.md'), '');+ const result = resolveAgentPaths(tmpDir, 'hermes');+ expect(result).toEqual({inject: ['.hermes.md'], create: []});+ });++ it('hermes preset finds existing HERMES.md when no .hermes.md', () => {+ fs.writeFileSync(path.join(tmpDir, 'HERMES.md'), '');+ const result = resolveAgentPaths(tmpDir, 'hermes');+ expect(result).toEqual({inject: ['HERMES.md'], create: []});+ });++ it('muse preset creates AGENTS.md when nothing exists', () => {+ const result = resolveAgentPaths(tmpDir, 'muse');+ expect(result).toEqual({inject: [], create: ['AGENTS.md']});+ });++ it('claude preset still creates .claude/CLAUDE.md when nothing exists (hermes is additive)', () => {+ const result = resolveAgentPaths(tmpDir, 'claude');+ expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});+ });+});++describe('parseBlockVersion', () => {+ it('reads the version from the header of a generated block', () => {+ expect(parseBlockVersion(generateCompressedIndex('1.2.3'))).toBe('1.2.3');+ });++ it('reads prerelease versions', () => {+ expect(parseBlockVersion('Astryx v1.2.3-beta.4 · 10 components')).toBe(+ '1.2.3-beta.4',+ );+ });++ it('returns null when no versioned header is present', () => {+ expect(parseBlockVersion('<!-- XDS:START -->\nold\n<!-- XDS:END -->')).toBeNull();+ expect(parseBlockVersion('')).toBeNull();+ expect(parseBlockVersion(undefined)).toBeNull();+ });+});++describe('inspectAgentDocs', () => {+ function writeBlock(rel, version) {+ const filePath = path.join(tmpDir, rel);+ fs.mkdirSync(path.dirname(filePath), {recursive: true});+ fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);+ }++ it('reports missing when no agent docs exist at all', () => {+ const res = inspectAgentDocs(tmpDir, '1.0.0');+ expect(res.status).toBe('missing');+ expect(res.files).toEqual([]);+ expect(res.staleFiles).toEqual([]);+ });++ it('reports missing when agent files exist but carry no Astryx marker', () => {+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written notes.\n');+ expect(inspectAgentDocs(tmpDir, '1.0.0').status).toBe('missing');+ });++ it('reports current when the only block matches the installed version', () => {+ writeBlock('AGENTS.md', '1.0.0');+ const res = inspectAgentDocs(tmpDir, '1.0.0');+ expect(res.status).toBe('current');+ expect(res.staleFiles).toEqual([]);+ expect(res.blockVersions).toEqual([]);+ });++ it.each([+ ['append addition', [], [{package: '@acme/a', append: ['added']}]],+ ['append removal', [{package: '@acme/a', append: ['removed']}], []],+ [+ 'integration reorder',+ [+ {package: '@acme/a', append: ['a']},+ {package: '@acme/b', append: ['b']},+ ],+ [+ {package: '@acme/b', append: ['b']},+ {package: '@acme/a', append: ['a']},+ ],+ ],+ [+ 'line content change',+ [{package: '@acme/a', append: ['old']}],+ [{package: '@acme/a', append: ['new']}],+ ],+ ])(+ 'reports stale at the same Core version after %s',+ (_label, current, expected) => {+ const actualBlock = generateCompressedIndex('1.0.0', {+ agentDocs: current,+ });+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ `# Doc\n\n${actualBlock}\n`,+ );+ const expectedBlock = generateCompressedIndex('1.0.0', {+ agentDocs: expected,+ });++ expect(inspectAgentDocs(tmpDir, '1.0.0', expectedBlock)).toMatchObject({+ status: 'stale',+ staleFiles: ['AGENTS.md'],+ });+ },+ );++ it('reports stale (with the old version) when the block is behind', () => {+ writeBlock('AGENTS.md', '1.0.0');+ const res = inspectAgentDocs(tmpDir, '2.0.0');+ expect(res.status).toBe('stale');+ expect(res.staleFiles).toEqual(['AGENTS.md']);+ expect(res.blockVersions).toEqual(['1.0.0']);+ expect(res.installedVersion).toBe('2.0.0');+ });++ it('treats a legacy XDS block as stale even with no parseable version', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'CLAUDE.md'),+ '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n',+ );+ const res = inspectAgentDocs(tmpDir, '1.0.0');+ expect(res.status).toBe('stale');+ expect(res.files[0].legacy).toBe(true);+ expect(res.blockVersions).toEqual([]);+ });++ it('is stale if ANY marked file is behind (mixed current + stale)', () => {+ writeBlock('AGENTS.md', '2.0.0');+ writeBlock('CLAUDE.md', '1.0.0');+ const res = inspectAgentDocs(tmpDir, '2.0.0');+ expect(res.status).toBe('stale');+ expect(res.staleFiles).toEqual(['CLAUDE.md']);+ });++ it('defaults the installed version to the core package when omitted', () => {+ const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');+ fs.mkdirSync(coreDir, {recursive: true});+ fs.writeFileSync(path.join(coreDir, 'package.json'), JSON.stringify({version: '3.0.0'}));+ writeBlock('AGENTS.md', '3.0.0');+ const res = inspectAgentDocs(tmpDir);+ expect(res.installedVersion).toBe('3.0.0');+ expect(res.status).toBe('current');+ });+});++describe('injectXdsBlock / removeXdsBlock — malformed managed blocks (no user-content loss)', () => {+ const S = '<!-- ASTRYX:START -->';+ const E = '<!-- ASTRYX:END -->';+ const BLOCK = `${S}\nNEW\n${E}`;++ it('does not duplicate user content when END precedes START', () => {+ const f = path.join(tmpDir, 'a.md');+ fs.writeFileSync(f, `# Doc\nUSER-A\n${E}\nUSER-B\n${S}\nUSER-C\n`);+ removeXdsBlock(f);+ const c = fs.readFileSync(f, 'utf-8');+ expect((c.match(/USER-B/g) || []).length).toBeLessThanOrEqual(1);+ });++ it('refuses (throws) instead of orphaning a second block when duplicates exist', () => {+ const f = path.join(tmpDir, 'b.md');+ fs.writeFileSync(f, `# Doc\n${S}\nB1\n${E}\nMID\n${S}\nB2\n${E}\nTAIL\n`);+ expect(() => injectXdsBlock(f, BLOCK)).toThrow(/multiple|malformed/i);+ // file left untouched for the user to fix+ expect(fs.readFileSync(f, 'utf-8')).toContain('MID');+ expect(fs.readFileSync(f, 'utf-8')).toContain('TAIL');+ });++ it('refuses to append a second block when a START has no matching END', () => {+ const f = path.join(tmpDir, 'c.md');+ fs.writeFileSync(f, `# Doc\nUSER1\n${S}\nOLD (no end)\nUSER2\n`);+ expect(() => injectXdsBlock(f, BLOCK)).toThrow(/end marker|malformed|no matching/i);+ expect((fs.readFileSync(f, 'utf-8').match(/ASTRYX:START/g) || []).length).toBe(1);+ });++ it('replaces a single well-formed block idempotently, preserving surrounding content', () => {+ const f = path.join(tmpDir, 'ok.md');+ fs.writeFileSync(f, `# Doc\nUSER\n${S}\nOLD\n${E}\nTAIL\n`);+ injectXdsBlock(f, BLOCK);+ const c = fs.readFileSync(f, 'utf-8');+ expect((c.match(/ASTRYX:START/g) || []).length).toBe(1);+ expect(c).toContain('NEW');+ expect(c).toContain('USER');+ expect(c).toContain('TAIL');+ expect(c).not.toContain('OLD');+ });+});++describe('isAstryxInitialized — resilient to malformed markers (postinstall hot path)', () => {+ // isAstryxInitialized runs on every consumer `npm install` (via postinstall).+ // It must never throw — even on a half-written or garbage-marker file — so it+ // uses a plain `.includes(MARKER_START)`, never the strict findManagedBlock.+ const START = '<!-- ASTRYX:START -->';+ const END = '<!-- ASTRYX:END -->';++ it('returns true (never throws) on duplicate START markers', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ `${START}\na\n${START}\nb\n${END}\n`,+ );+ expect(() => isAstryxInitialized(tmpDir)).not.toThrow();+ expect(isAstryxInitialized(tmpDir)).toBe(true);+ });++ it('returns true on an END-before-START file without throwing', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ `${END}\nuser\n${START}\nblock\n`,+ );+ expect(() => isAstryxInitialized(tmpDir)).not.toThrow();+ expect(isAstryxInitialized(tmpDir)).toBe(true);+ });++ it('returns true on a START with no END (half-written block)', () => {+ fs.writeFileSync(+ path.join(tmpDir, 'AGENTS.md'),+ `# Doc\nuser\n${START}\ntruncated block, no end\n`,+ );+ expect(() => isAstryxInitialized(tmpDir)).not.toThrow();+ expect(isAstryxInitialized(tmpDir)).toBe(true);+ });++ it('returns false for a directory with no agent docs', () => {+ expect(isAstryxInitialized(tmpDir)).toBe(false);+ });++ it('returns false for a nonexistent directory', () => {+ expect(isAstryxInitialized(path.join(tmpDir, 'does-not-exist'))).toBe(false);+ });+});diff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjsnew file mode 100644index 0000000000..ed3102756c--- /dev/null+++ b/packages/cli/foundation/doc-compiler/tree.test.mjs@@ -0,0 +1,649 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Tests for the docs tree (spec:AST-046): one home per doc, decided by+ * explicit placement, then one adoption rule; every way a placement can fail;+ * generated kind levels; deterministic order; and the CLI's own tree.+ *+ * @input Plain fixture inputs for the pure builder, and this package's own+ * tree files and typed docs for the loader.+ * @output Assertions on routes, parents, slots, children order, and+ * diagnostics.+ * @position packages/cli/foundation/doc-compiler — tests for tree.mjs.+ */++import {describe, expect, it} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {+ buildDocsTree,+ KIND_GROUPS,+ loadDocsTree,+ loadTreeInputs,+ routeSegment,+} from './tree.mjs';+import {loadCliSelfDocs} from '../discovery/cli-self-docs.mjs';+import * as api from '../../api/index.mjs';+import {createDocId} from '../identity/provider-identity.mjs';+import {CLI_PROVIDER_ID} from '../identity/providers.mjs';++const SLOW = 60_000;+const P = '@acme/kit';++/**+ * @param {string} name+ * @param {object} [extra]+ * @returns {import('./tree.mjs').TreeNamespaceInput}+ */+const ns = (name, extra = {}) => ({+ provider: P,+ providerId: P,+ source: `${P}/tree/${name}.doc.mjs`,+ doc: /** @type {any} */ ({+ type: 'namespace',+ name,+ title: name.toUpperCase(),+ summary: `The ${name} level.`,+ slots: {+ items: {title: 'Items', accepts: {kinds: ['generic', 'namespace']}},+ },+ ...extra,+ }),+});++/**+ * @param {string} name+ * @param {object} [extra]+ * @returns {import('./tree.mjs').TreeDocInput}+ */+const guide = (name, extra = {}) => ({+ provider: P,+ providerId: P,+ source: `${P}/tree/${name}.doc.mjs`,+ kind: 'generic',+ name,+ title: `Guide ${name}`,+ summary: `About ${name}.`,+ group: null,+ placement: undefined,+ ...extra,+});++/**+ * @param {string} kind+ * @param {string} name+ * @param {string} group+ * @returns {import('./tree.mjs').TreeDocInput}+ */+const typed = (kind, name, group) => ({+ provider: P,+ providerId: P,+ source: `${P}/api/${name}.doc.mjs`,+ kind,+ name,+ title: name,+ summary: `The ${name} ${kind}.`,+ group,+ placement: undefined,+});++/** @param {ReturnType<typeof buildDocsTree>} tree */+const routes = tree => [...tree.nodes.keys()];++/** @param {ReturnType<typeof buildDocsTree>} tree */+const problems = tree => tree.diagnostics.map(d => [d.code, d.message]);++describe('buildDocsTree', () => {++ it('withdraws a namespace placed in a withdrawn namespace, and what is placed in it', () => {+ const CLI = '@astryxdesign/cli';+ const tree = buildDocsTree({+ namespaces: [+ ns('tokens'),+ ns('alpha', {placement: {parent: 'namespace:tokens', slot: 'items'}}),+ ],+ docs: [guide('deep', {placement: {parent: 'namespace:alpha', slot: 'items'}})],+ topics: [+ {provider: CLI, providerId: CLI, name: 'tokens', title: 'Tokens', summary: 'Tokens.', source: `${CLI}/tokens.doc.mjs`},+ ],+ });+ expect(tree.get('tokens')?.provider).toBe(CLI);+ expect(routes(tree).filter(route => route.startsWith('tokens/'))).toEqual([]);+ expect(problems(tree)).toEqual(+ expect.arrayContaining([+ ['duplicate_route', expect.stringContaining('takes the route "tokens"')],+ ['invalid_placement', 'Namespace "alpha" has no route: the namespace it is placed in was withdrawn.'],+ ['invalid_placement', expect.stringContaining('names a namespace that has no route')],+ ]),+ );+ });++ it("keeps a name a topic answers to through replaces as that topic's route", () => {+ const tree = buildDocsTree({+ namespaces: [ns('tokens')],+ docs: [],+ topics: [+ {provider: '@acme/a', providerId: '@acme/a', name: 'acme-tokens', title: 'Acme tokens', summary: 'Acme tokens.', source: '@acme/a:acme-tokens', aliases: ['tokens', 'old-tokens']},+ ],+ });+ expect(tree.get('tokens')).toBeUndefined();+ expect(tree.get('acme-tokens')?.provider).toBe('@acme/a');+ expect(problems(tree)).toEqual([+ ['duplicate_route', expect.stringContaining('takes the route "tokens", which the topic "acme-tokens" also answers to')],+ ]);+ // Every name it answers to is reserved, not only the last one it replaced.+ const older = buildDocsTree({+ namespaces: [ns('old-tokens')],+ docs: [],+ topics: [+ {provider: '@acme/a', providerId: '@acme/a', name: 'acme-tokens', title: 'Acme tokens', summary: 'Acme tokens.', source: '@acme/a:acme-tokens', aliases: ['tokens', 'old-tokens']},+ ],+ });+ expect(older.get('old-tokens')).toBeUndefined();+ });++ it("keeps the CLI's own routes from an integration, compared without case", () => {+ const CLI = '@astryxdesign/cli';+ /** @param {string} name @param {string} [provider] */+ const topic = (name, provider = P) => ({+ provider,+ providerId: provider,+ name,+ title: name,+ summary: `The ${name} topic.`,+ source: `${provider}/${name}.doc.mjs`,+ });+ const cliNs = {...ns('cli'), provider: CLI, providerId: CLI, source: `${CLI}/tree/cli.doc.mjs`};+ // An integration's topics named `CLI` and `UNORGANIZED` claim the CLI's+ // namespace and the generated level; both are withdrawn.+ const tree = buildDocsTree({+ namespaces: [cliNs],+ docs: [],+ topics: [topic('theme', CLI), topic('CLI'), topic('UNORGANIZED')],+ });+ expect(tree.get('cli')?.provider).toBe(CLI);+ expect(tree.get('unorganized')?.provider).toBe(CLI);+ expect(routes(tree)).not.toContain('CLI');+ expect(routes(tree)).not.toContain('UNORGANIZED');+ expect(problems(tree)).toEqual(+ expect.arrayContaining([+ ['duplicate_route', expect.stringContaining('both have the route "CLI"')],+ ['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],+ ]),+ );+ expect(tree.getFolded('THEME')?.provider).toBe(CLI);+ // A CLI topic whose own name has capitals keeps its route against a+ // lowercase namespace, although namespaces go into the tree first.+ const caps = buildDocsTree({namespaces: [ns('tokens')], docs: [], topics: [topic('Tokens', CLI)]});+ expect(caps.get('Tokens')?.provider).toBe(CLI);+ expect(caps.get('tokens')).toBeUndefined();+ expect(problems(caps)).toEqual([+ ['duplicate_route', expect.stringContaining('takes the route "tokens", which the CLI\'s own docs keep')],+ ]);+ });+ it('builds three authored levels and a guide below them', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('top'),+ ns('middle', {placement: {parent: 'namespace:top', slot: 'items'}}),+ ns('bottom', {placement: {parent: 'namespace:middle'}}),+ ],+ docs: [+ guide('deep', {placement: {parent: 'namespace:bottom', order: 1}}),+ ],+ });+ expect(problems(tree)).toEqual([]);+ expect(routes(tree)).toEqual([+ 'top',+ 'top/middle',+ 'top/middle/bottom',+ 'top/middle/bottom/deep',+ ]);+ const deep = /** @type {any} */ (tree.get('top/middle/bottom/deep'));+ expect(deep).toMatchObject({+ id: 'astryx:artifact:v1/%40acme%2Fkit/generic/deep',+ parent: 'top/middle/bottom',+ slot: 'items',+ order: 1,+ generated: false,+ });+ expect(tree.ancestors(deep).map(node => node.route)).toEqual([+ 'top',+ 'top/middle',+ 'top/middle/bottom',+ ]);+ expect(tree.roots().map(node => node.route)).toEqual(['top']);+ });++ it('adopts typed docs by group, with one generated level per kind', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('api', {+ slots: {kinds: {title: 'Reference', accepts: {kinds: ['namespace']}}},+ adopts: [+ {+ source: {group: 'kit/api', kinds: ['function', 'enum']},+ into: 'kinds',+ groupBy: 'kind',+ },+ ],+ }),+ ],+ docs: [+ typed('enum', 'errorCodes', 'kit/api'),+ typed('function', 'search', 'kit/api'),+ typed('function', 'build', 'kit/api'),+ typed('schema', 'config', 'kit/api'),+ typed('function', 'other', 'kit/elsewhere'),+ ],+ });+ expect(problems(tree)).toEqual([]);+ expect(routes(tree)).toEqual([+ 'api',+ 'api/enums',+ 'api/enums/error-codes',+ 'api/functions',+ 'api/functions/build',+ 'api/functions/search',+ ]);+ const functions = /** @type {any} */ (tree.get('api/functions'));+ expect(functions).toMatchObject({+ id: null,+ kind: 'namespace',+ title: KIND_GROUPS.function.title,+ generated: true,+ parent: 'api',+ slot: 'kinds',+ });+ // Kind levels follow the rule's kind order; docs inside sort by title.+ expect(tree.get('api')?.slots[0].children).toEqual([+ 'api/functions',+ 'api/enums',+ ]);+ expect(functions.slots[0].children).toEqual([+ 'api/functions/build',+ 'api/functions/search',+ ]);+ });++ it('adopts without grouping straight into the named slot', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('commands', {+ slots: {all: {title: 'All', accepts: {kinds: ['command']}}},+ adopts: [{source: {group: 'kit/commands'}, into: 'all'}],+ }),+ ],+ docs: [typed('command', 'theme add', 'kit/commands')],+ });+ expect(routes(tree)).toEqual(['commands', 'commands/theme-add']);+ expect(tree.get('commands')?.slots[0].children).toEqual([+ 'commands/theme-add',+ ]);+ });++ it('prefers explicit placement over adoption, and never falls back', () => {+ const namespaces = [+ ns('guides'),+ ns('api', {+ slots: {all: {title: 'All', accepts: {kinds: ['generic']}}},+ adopts: [{source: {group: 'kit/api'}, into: 'all'}],+ }),+ ];+ const placed = buildDocsTree({+ namespaces,+ docs: [+ guide('intro', {+ group: 'kit/api',+ placement: {parent: 'namespace:guides'},+ }),+ ],+ });+ expect(routes(placed)).toContain('guides/intro');+ expect(routes(placed)).not.toContain('api/intro');++ const broken = buildDocsTree({+ namespaces,+ docs: [+ guide('intro', {+ group: 'kit/api',+ placement: {parent: 'namespace:nope'},+ }),+ ],+ });+ expect(routes(broken).some(route => route.endsWith('/intro'))).toBe(false);+ expect(problems(broken)).toEqual([+ [+ 'invalid_placement',+ 'placement.parent "namespace:nope" names no namespace; @acme/kit declares "api", "guides".',+ ],+ ]);+ });++ it('reports every way a placement can fail', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('home', {+ slots: {+ one: {title: 'One', accepts: {kinds: ['generic']}},+ two: {title: 'Two', accepts: {kinds: ['command']}},+ },+ }),+ ],+ docs: [+ guide('no-slot', {placement: {parent: 'namespace:home'}}),+ guide('bad-slot', {+ placement: {parent: 'namespace:home', slot: 'three'},+ }),+ guide('wrong-kind', {+ placement: {parent: 'namespace:home', slot: 'two'},+ }),+ guide('other-package', {+ placement: {parent: '@other/pkg/namespace/home'},+ }),+ guide('not-a-ref', {placement: {parent: 'home'}}),+ ],+ });+ expect(routes(tree)).toEqual(['home']);+ expect(+ problems(tree)+ .map(([, message]) => message)+ .sort(),+ ).toEqual(+ [+ 'placement names no slot, and namespace "home" has 2 (one, two). Name one with placement.slot.',+ 'placement.slot "three" is not a slot of namespace "home"; it declares one, two.',+ 'slot "two" of namespace "home" does not accept generic docs; it accepts command.',+ 'placement.parent "@other/pkg/namespace/home" belongs to @other/pkg. A doc can only be placed in a namespace of its own package (@acme/kit).',+ 'placement.parent "home" is not a namespace reference. Write "namespace:<name>".',+ ].sort(),+ );+ expect(tree.diagnostics.every(d => d.code === 'invalid_placement')).toBe(+ true,+ );+ expect(tree.diagnostics.every(d => d.severity === 'error')).toBe(true);+ });++ it('fails a doc two namespaces adopt, naming both', () => {+ const rule = {source: {group: 'kit/api'}, into: 'items'};+ const tree = buildDocsTree({+ namespaces: [ns('a', {adopts: [rule]}), ns('b', {adopts: [rule]})],+ docs: [guide('shared', {group: 'kit/api'})],+ });+ expect(routes(tree)).toEqual(['a', 'b']);+ expect(problems(tree)).toEqual([+ [+ 'overlapping_adoption',+ '@acme/kit/generic/shared is adopted by "a" and "b"; exactly one namespace may adopt a doc.',+ ],+ ]);+ });++ it('fails two docs at one route, keeping the first by identity', () => {+ const tree = buildDocsTree({+ namespaces: [ns('home')],+ docs: [+ guide('fooBar', {placement: {parent: 'namespace:home'}}),+ guide('foo_bar', {placement: {parent: 'namespace:home'}}),+ ],+ });+ expect(routes(tree)).toEqual(['home', 'home/foo-bar']);+ expect(tree.get('home/foo-bar')?.id).toBe(+ 'astryx:artifact:v1/%40acme%2Fkit/generic/fooBar',+ );+ expect(problems(tree)).toEqual([+ [+ 'duplicate_route',+ 'astryx:artifact:v1/%40acme%2Fkit/generic/foo_bar and astryx:artifact:v1/%40acme%2Fkit/generic/fooBar both have the route "home/foo-bar". Rename or move one of them.',+ ],+ ]);+ });++ it('fails a namespace cycle and everything under it', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('a', {placement: {parent: 'namespace:b'}}),+ ns('b', {placement: {parent: 'namespace:a'}}),+ ],+ docs: [guide('lost', {placement: {parent: 'namespace:a'}})],+ });+ expect(routes(tree)).toEqual([]);+ expect(problems(tree).map(([code]) => code)).toEqual([+ 'invalid_placement',+ 'invalid_placement',+ 'invalid_placement',+ ]);+ });++ it('fails a duplicate or unsafe namespace name', () => {+ const tree = buildDocsTree({+ namespaces: [+ ns('twice'),+ {...ns('twice'), source: `${P}/other.doc.mjs`},+ ns('Bad Name'),+ ],+ docs: [],+ });+ expect(routes(tree)).toEqual(['twice']);+ expect(tree.diagnostics.map(d => d.code)).toEqual([+ 'invalid_namespace',+ 'invalid_namespace',+ ]);+ });++ it('leaves a doc with no placement and no adoption out, in phase 1', () => {+ const tree = buildDocsTree({+ namespaces: [ns('home')],+ docs: [guide('loose'), typed('function', 'free', 'kit/nowhere')],+ });+ expect(routes(tree)).toEqual(['home']);+ expect(tree.diagnostics).toEqual([]);+ });++ it('is the same tree whatever order its inputs arrive in', () => {+ const namespaces = [+ ns('top'),+ ns('child', {placement: {parent: 'namespace:top'}}),+ ];+ const docs = [+ guide('b', {placement: {parent: 'namespace:child'}}),+ guide('a', {placement: {parent: 'namespace:child'}}),+ ];+ const one = buildDocsTree({namespaces, docs});+ const two = buildDocsTree({+ namespaces: [...namespaces].reverse(),+ docs: [...docs].reverse(),+ });+ expect(JSON.stringify([...two.nodes])).toBe(JSON.stringify([...one.nodes]));+ });++ it('orders children by order, then title', () => {+ const tree = buildDocsTree({+ namespaces: [ns('home')],+ docs: [+ guide('z', {+ title: 'Zed',+ placement: {parent: 'namespace:home', order: 1},+ }),+ guide('b', {title: 'Beta', placement: {parent: 'namespace:home'}}),+ guide('a', {title: 'Alpha', placement: {parent: 'namespace:home'}}),+ ],+ });+ expect(tree.get('home')?.slots[0].children).toEqual([+ 'home/z',+ 'home/a',+ 'home/b',+ ]);+ });+});++describe('routeSegment', () => {+ it('joins lowercase words with hyphens, whatever the name looks like', () => {+ expect(routeSegment('integrationPackCheck')).toBe('integration-pack-check');+ expect(routeSegment('doctor integration validate')).toBe(+ 'doctor-integration-validate',+ );+ expect(routeSegment('error-codes')).toBe('error-codes');+ expect(routeSegment('isError')).toBe('is-error');+ expect(routeSegment('!!')).toBe('');+ });+});++describe("the CLI's own docs tree", () => {+ it(+ 'builds with no diagnostic, rooted at cli',+ async () => {+ const tree = await loadDocsTree({fresh: true});+ expect(tree.diagnostics).toEqual([]);+ expect(tree.roots().map(node => node.route)).toEqual(['cli']);+ // Every slot child is a node one level below the namespace that places+ // it, and every node but the root is placed. Read from the tree, so a+ // restructure of the guides does not need this test edited.+ const nodes = [...tree.nodes.values()];+ const placed = new Set();+ const misplaced = [];+ for (const node of nodes) {+ for (const slot of node.slots ?? []) {+ for (const child of slot.children) {+ placed.add(child);+ const rest = child.slice(node.route.length + 1);+ if (+ tree.get(child) == null ||+ !child.startsWith(`${node.route}/`) ||+ rest.includes('/')+ ) {+ misplaced.push(`${node.route} › ${slot.name} › ${child}`);+ }+ }+ }+ }+ expect(misplaced).toEqual([]);+ expect(+ nodes+ .map(node => node.route)+ .filter(route => route !== 'cli' && !placed.has(route)),+ ).toEqual([]);+ // The reference groups the CLI generates from its own typed docs.+ expect(+ tree.get('cli')?.slots.find(slot => slot.name === 'reference')+ ?.children,+ ).toEqual(['cli/commands', 'cli/api']);+ expect(tree.get('cli/api')?.slots[0].children).toEqual([+ 'cli/api/functions',+ 'cli/api/schemas',+ 'cli/api/enums',+ ]);+ },+ SLOW,+ );++ it(+ 'gives every CLI typed doc in a cli group one route, by its kind',+ async () => {+ const tree = await loadDocsTree();+ const {loaded} = await loadCliSelfDocs();+ const inTree = loaded.filter(({doc}) =>+ String(doc.namespace).startsWith('cli/'),+ );+ expect(inTree.length).toBeGreaterThan(0);+ const expected = inTree.map(({doc}) =>+ doc.type === 'command'+ ? `cli/commands/${routeSegment(doc.name)}`+ : `cli/api/${KIND_GROUPS[doc.type].segment}/${routeSegment(doc.name)}`,+ );+ expect(expected.filter(route => tree.get(route) == null)).toEqual([]);+ // A doc in the authoring group stays a section of `astryx docs authoring`.+ const authoring = loaded.filter(({doc}) => doc.namespace === 'authoring');+ expect(authoring.length).toBeGreaterThan(0);+ const ids = new Set([...tree.nodes.values()].map(node => node.id));+ expect(+ authoring.filter(({doc}) =>+ ids.has(createDocId(CLI_PROVIDER_ID, doc.type, doc.name)),+ ),+ ).toEqual([]);+ },+ SLOW,+ );++ it(+ 'gives every function @astryxdesign/cli/api exports a route',+ async () => {+ const tree = await loadDocsTree();+ const exported = Object.entries(api)+ .filter(+ ([, value]) =>+ typeof value === 'function' &&+ Object.getOwnPropertyDescriptor(value, 'prototype')?.writable !==+ false,+ )+ .map(([name]) => `cli/api/functions/${routeSegment(name)}`);+ expect(exported.length).toBeGreaterThan(0);+ expect(exported.filter(route => tree.get(route) == null)).toEqual([]);+ },+ SLOW,+ );++ it(+ 'reads only namespace and generic docs from the tree directory, each named after its file',+ async () => {+ const inputs = await loadTreeInputs({selfDocs: false});+ expect(inputs.diagnostics).toEqual([]);+ // Every doc file in the tree directory is read, as a namespace or a+ // guide, and named after its file.+ const records = [+ ...inputs.namespaces.map(n => ({name: n.doc.name, source: n.source})),+ ...inputs.docs.map(d => ({name: d.name, source: d.source})),+ ];+ const files = fs+ .readdirSync(new URL('../../assets/docs/tree/', import.meta.url))+ .filter(file => file.endsWith('.doc.mjs'))+ .sort();+ expect(+ records.map(record => path.basename(String(record.source))).sort(),+ ).toEqual(files);+ expect(+ records.filter(+ record =>+ path.basename(String(record.source)) !== `${record.name}.doc.mjs`,+ ),+ ).toEqual([]);+ expect(new Set(inputs.docs.map(d => d.kind))).toEqual(+ new Set(['generic']),+ );+ // Every guide's parent is a namespace from the same directory.+ const namespaces = new Set(+ inputs.namespaces.map(n => `namespace:${n.doc.name}`),+ );+ expect(+ inputs.docs+ .filter(d => d.placement?.parent != null)+ .filter(d => !namespaces.has(d.placement.parent))+ .map(d => d.name),+ ).toEqual([]);+ },+ SLOW,+ );+});++describe('doc identity', () => {+ it('builds each id from the provider id, never the package name', () => {+ const provider = '@acme/tree-provider';+ const tree = buildDocsTree({+ namespaces: [{...ns('home'), providerId: provider}],+ docs: [+ {+ ...guide('intro', {placement: {parent: 'namespace:home'}}),+ providerId: provider,+ },+ ],+ });+ expect(problems(tree)).toEqual([]);+ expect(tree.get('home')?.id).toBe(+ 'astryx:artifact:v1/%40acme%2Ftree-provider/namespace/home',+ );+ expect(tree.get('home/intro')).toMatchObject({+ id: 'astryx:artifact:v1/%40acme%2Ftree-provider/generic/intro',+ provider: P,+ });+ });+});diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjsnew file mode 100644index 0000000000..5551ea8981--- /dev/null+++ b/packages/cli/test/docs-graph.test.mjs@@ -0,0 +1,602 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The docs graph stays walkable (spec:AST-047, spec:AST-046).+ *+ * The walk starts at the topic list and opens every topic, topic index,+ * section, namespace, and typed doc the CLI ships, the way a reader would: it+ * follows each child and each move a read offers (`up`, `previous`, `next`),+ * and fails on any move that does not open. It then checks the moves agree+ * with each other, opens every `astryx docs ...` command written in a doc's+ * own text, and opens every search hit's command and parent. Nothing stores+ * the moves, so this is what proves they stay right as docs are added, moved,+ * or removed.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, it, expect, beforeAll} from 'vitest';+import {docs} from '../api/docs/docs.mjs';+import {typedEdges} from '../api/docs/node/node.mjs';+import {+ builtinCatalog,+ docsLinkProblems,+ projectTree,+} from '../api/docs/_adapter.mjs';+import {loadDocsCatalog} from '../api/docs/_adapter.mjs';+import {search} from '../api/search/search.mjs';+import {loadDocsTree} from '../foundation/doc-compiler/tree.mjs';+import {+ discoverCliSelfDocSources,+ loadCliSelfDocs,+} from '../foundation/discovery/cli-self-docs.mjs';+import {routeSegment} from '../foundation/discovery/docs-section-key.mjs';+import {generateCompressedIndex} from '../foundation/agent-docs/agent-docs.mjs';+import {program, JSON_SUPPORTED} from '../clients/cli/index.mjs';+import {buildManifest} from '../clients/cli/lib/manifest.mjs';+import {runCli} from '../test-utils/run-cli.mjs';++const CLI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');++const SLOW = 180_000;+const TOP = 'astryx docs';++/**+ * Open one `astryx docs ...` command through the API, as the CLI would.+ * @param {string} command+ */+function open(command) {+ const words = command.trim().split(/\s+/);+ if (words[0] !== 'astryx' || words[1] !== 'docs') {+ throw new Error(`not a docs command: ${command}`);+ }+ const rest = words.slice(2);+ const [topic, section] = rest.filter(w => !w.startsWith('--'));+ return docs(topic, section, {+ index: rest.includes('--index'),+ full: rest.includes('--full'),+ });+}++/**+ * Every place a read leads: its children, and its moves.+ * @param {any} res+ * @returns {Array<[string, string]>} [kind of move, command]+ */+function movesOf(res) {+ /** @type {Array<[string, string]>} */+ const out = [];+ const {type, data} = res;+ if (type === 'docs.list') {+ for (const entry of data) {+ out.push(['down', `${TOP} ${entry.topic}`]);+ out.push(['down', `${TOP} ${entry.topic} --index`]);+ }+ for (const entry of res.meta?.namespaces ?? []) {+ out.push(['down', `${TOP} ${entry.topic}`]);+ }+ }+ if (type === 'docs.node') {+ for (const slot of data.slots) {+ for (const child of slot.children) out.push(['down', `${TOP} ${child.route}`]);+ }+ }+ if (type === 'docs.index') {+ for (const section of data.sections) {+ out.push(['down', `${TOP} ${data.name} ${section.id}`]);+ }+ }+ for (const [kind, value] of Object.entries(data?.links ?? {})) {+ for (const command of [value].flat()) {+ out.push([kind, /** @type {string} */ (command)]);+ }+ }+ // Links between docs are moves too: each reference block, and each+ // workflow step's references.+ const blocks = [+ ...(data?.content ?? []),+ ...(data?.sections ?? []).flatMap((/** @type {any} */ s) => s.content ?? []),+ ];+ for (const block of blocks) {+ if (block?.type === 'reference' && block.link) {+ out.push(['reference', block.link.command]);+ }+ for (const step of block?.type === 'workflow' ? block.steps : []) {+ for (const link of step.links ?? []) {+ if (link) out.push(['reference', link.command]);+ }+ }+ }+ return out;+}++/**+ * The words a read says: prose, list items, and table cells.+ * @param {any} res+ * @returns {string[]}+ */+function textOf(res) {+ /** @type {string[]} */+ const out = [];+ /** @param {any[]} blocks */+ const scan = blocks => {+ for (const block of blocks ?? []) {+ if (block.type === 'prose' && block.text) out.push(block.text);+ if (block.type === 'list') {+ for (const item of block.items ?? []) {+ out.push(typeof item === 'string' ? item : (item?.text ?? ''));+ }+ }+ if (block.type === 'table') {+ for (const row of block.rows ?? []) out.push(...row.map(String));+ }+ if (block.type === 'code' && typeof block.code === 'string') {+ out.push(block.code);+ }+ }+ };+ const {type, data} = res;+ if (type === 'docs.detail') {+ out.push(data.description ?? '');+ for (const section of data.sections ?? []) scan(section.content);+ }+ if (type === 'docs.index') out.push(data.description ?? '');+ if (type === 'docs.detail.section') scan(data.content);+ if (type === 'docs.node') scan(data.content);+ return out;+}++/**+ * Every `astryx ...` command a text shows: in code ticks, or on a line of its+ * own (a code block line, or a hint line such as `Up: npx astryx docs cli`).+ * A hint's description, after two spaces or a `#`, is cut off.+ * @param {string} text+ * @returns {string[]}+ */+function shownCommands(text) {+ const RUN = '(?:npx |pnpm exec |pnpm dlx |yarn |bunx )?astryx(?: [^`\\n]*)?';+ /** @param {string} s */+ const clean = s => s.replace(/\s{2,}.*$/, '').replace(/\s+#.*$/, '').trim();+ /** @type {Set<string>} */+ const out = new Set();+ // A chain such as `astryx a && astryx b` is two commands; each is checked+ // on its own, so a flag of the second is never read as the first's.+ /** @param {string} s */+ const add = s => {+ for (const part of clean(s).split(/\s*(?:&&|\|\||;)\s*|\s+\|\s+/)) {+ if (new RegExp('^' + RUN + '$').test(part.trim())) out.add(part.trim());+ }+ };+ for (const m of text.matchAll(new RegExp('`(' + RUN + ')`', 'g'))) {+ add(m[1]);+ }+ for (const line of text.split('\n')) {+ const m = new RegExp('^\\s*(?:\\$\\s+|[A-Z][A-Za-z ]*:\\s+)?(' + RUN + ')$').exec(line);+ if (m) add(m[1]);+ }+ return [...out];+}++/**+ * The CLI's commands and options, from the live manifest: nothing here is a+ * list someone keeps.+ */+function cliSurface() {+ const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED});+ /** @param {Array<{flag: string}>} options */+ const flagsOf = options => {+ /** @type {Map<string, boolean>} flag -> takes a value */+ const flags = new Map();+ for (const option of options ?? []) {+ const takes = /[<[]/.test(option.flag);+ for (const flag of option.flag.split(/[\s,]+/)) {+ if (flag.startsWith('-')) flags.set(flag, takes);+ }+ }+ return flags;+ };+ /** @type {Map<string, Map<string, boolean>>} */+ const commands = new Map();+ /** @type {Set<string>} groups that take a subcommand and no argument */+ const groups = new Set();+ /** @param {any[]} list */+ const add = list => {+ for (const command of list ?? []) {+ commands.set(command.name, flagsOf(command.options));+ if (command.subcommands?.length && !command.arguments?.length) {+ groups.add(command.name);+ }+ add(command.subcommands);+ }+ };+ add(manifest.commands);+ return {commands, groups, global: flagsOf(manifest.globalOptions)};+}++/**+ * What is wrong with one shown command, or null: an unknown command, or an+ * option its command does not take. Positional arguments are not checked+ * here; `astryx docs` routes are, by the walk.+ * @param {string} shown+ * @param {ReturnType<typeof cliSurface>} surface+ * @returns {string | null}+ */+function problemWith(shown, {commands, groups, global}) {+ const words = shown.split(/\s+/);+ const rest = words.slice(words.indexOf('astryx') + 1).filter(Boolean);+ /** @param {Map<string, boolean>} flags @param {string} token */+ const known = (flags, token) => {+ const flag = token.split('=')[0];+ return (+ flag === '--help' ||+ flag === '-h' ||+ flags.has(flag) ||+ (flag.startsWith('--no-') && flags.has(`--${flag.slice(5)}`))+ );+ };+ let i = 0;+ while (i < rest.length && rest[i].startsWith('-')) {+ if (!known(global, rest[i])) return `unknown global option ${rest[i]}`;+ if (global.get(rest[i]) && !rest[i].includes('=')) i++;+ i++;+ }+ // `help` is Commander's own command; a placeholder names no command.+ if (i >= rest.length || rest[i] === 'help' || /^(?:[<[]|\.\.\.|…)/.test(rest[i])) return null;+ let name = null;+ for (let n = rest.length - i; n > 0; n--) {+ const candidate = rest.slice(i, i + n).join(' ');+ if (commands.has(candidate)) {+ name = candidate;+ i += n;+ break;+ }+ }+ if (name == null) return `unknown command "${rest[i]}"`;+ // A group takes a subcommand, so a word after it names one it lacks:+ // `astryx integration bogus` names a subcommand `integration` lacks.+ if (groups.has(name) && i < rest.length && /^[a-z]/.test(rest[i])) {+ return `\`astryx ${name}\` has no subcommand ${rest[i]}`;+ }+ const flags = new Map([...global, ...(commands.get(name) ?? [])]);+ for (; i < rest.length; i++) {+ const token = rest[i];+ if (!/^--?[a-zA-Z]/.test(token)) continue;+ if (!known(flags, token)) {+ return `\`astryx ${name}\` has no option ${token.split('=')[0]}`;+ }+ if (flags.get(token) && !token.includes('=')) i++;+ }+ return null;+}++/**+ * Commands a doc shows on purpose as wrong: the error codes they trigger. Each+ * must still appear in a doc, or the entry is stale.+ */+const WRONG_ON_PURPOSE = new Map([+ ['astryx bogus', 'the ERR_UNKNOWN_COMMAND example'],+ ['astryx theme bogus', 'the ERR_UNKNOWN_SUBCOMMAND example'],+]);++/**+ * Commands a doc shows that the CLI does not accept yet, each waiting on a+ * decision. An entry fails once the command works or no doc shows it, so it+ * cannot outlive the decision.+ */+const AWAITING_DECISION = new Map([+ [+ 'astryx integration add theme ocean --from neutral',+ 'the add-a-theme guide shows a fork option the CLI does not have: build it, or drop the paragraph',+ ],+]);++/** The CLI's own reads whose hint lines show commands. */+const HINT_READS = [+ ['docs'],+ ['docs', 'cli'],+ ['docs', 'cli/api/functions/search'],+ ['docs', 'theme'],+ ['docs', 'cli/integrations', 'codemods'],+ ['search', 'token-ref', '--type', 'doc'],+ ['--help'],+ ['docs', '--help'],+];++/** The `astryx docs ...` commands written in text, placeholders skipped. */+function docsCommandsIn(text) {+ /** @type {string[]} */+ const out = [];+ for (const m of text.matchAll(/`(?:npx |pnpm exec |yarn |bunx )?astryx docs( [^`]*)?`/g)) {+ const args = (m[1] ?? '').trim();+ if (/[<>…]|\.\.\.|\|/.test(args)) continue;+ out.push(args ? `${TOP} ${args}` : TOP);+ }+ // A code block line or a chain opens too, for the CLI's own tree. Other+ // routes there are an integration's topics, shown as examples.+ for (const shown of shownCommands(text)) {+ const m = /^(?:npx |pnpm exec |pnpm dlx |yarn |bunx )?astryx docs (cli(?:\/\S*)?(?: .*)?)$/.exec(shown);+ if (!m) continue;+ const args = m[1].replace(/\s--(?:detail|lang)\s+\S+/g, '').trim();+ if (/[<>…[\]]|\.\.\.|\|/.test(args)) continue;+ out.push(`${TOP} ${args}`);+ }+ return out;+}++describe('the docs graph', () => {+ /** @type {Map<string, any>} */+ const reads = new Map();+ /** @type {Array<[string, string, string]>} */+ const moves = [];+ /** @type {string[]} */+ const dead = [];++ beforeAll(async () => {+ const queue = [TOP];+ while (queue.length > 0) {+ const command = /** @type {string} */ (queue.shift());+ if (reads.has(command)) continue;+ let res;+ try {+ res = await open(command);+ } catch (e) {+ dead.push(`${command}: ${/** @type {Error} */ (e).message}`);+ reads.set(command, null);+ continue;+ }+ reads.set(command, res);+ for (const [kind, to] of movesOf(res)) {+ moves.push([command, kind, to]);+ if (!reads.has(to)) queue.push(to);+ }+ }+ }, SLOW);++ it('opens every move a read offers, from the top down', () => {+ expect(dead).toEqual([]);+ expect(reads.size).toBeGreaterThan(200);+ });++ it('reaches every node of the tree', async () => {+ const tree = await loadDocsTree();+ const missed = [...tree.nodes.values()]+ .map(node => `${TOP} ${node.route}`)+ .filter(command => !reads.get(command));+ expect(missed).toEqual([]);+ });++ it('reaches every doc file the CLI ships, and every doc file is one the CLI reads', async () => {+ const tree = await loadDocsTree();+ const reached = (/** @type {string} */ command) => Boolean(reads.get(command));+ /** @type {string[]} */+ const unreached = [];+ // Command, API, schema, enum, and authoring docs: a tree leaf, or a section+ // of `astryx docs authoring`.+ const {loaded, failed} = await loadCliSelfDocs(discoverCliSelfDocSources(CLI), CLI);+ expect(failed).toEqual([]);+ const authoring = reads.get(`${TOP} authoring --index`)?.data.sections ?? [];+ for (const {source, doc} of loaded) {+ const leaf = [...tree.nodes.values()].find(+ node => node.kind === doc.type && node.name === doc.name,+ );+ const section = authoring.find(+ (/** @type {any} */ s) => s.id === routeSegment(doc.name) || s.title === doc.displayName,+ );+ const ok = leaf+ ? reached(`${TOP} ${leaf.route}`)+ : section+ ? reached(`${TOP} authoring ${section.id}`)+ : false;+ if (!ok) unreached.push(source);+ }+ // Topics, and the tree's own files.+ const catalog = await loadDocsCatalog(CLI);+ const topicFiles = new Set();+ for (const entry of catalog.entries()) {+ topicFiles.add(path.resolve(entry.path));+ if (!reached(`${TOP} ${entry.name}`)) unreached.push(`topic ${entry.name}`);+ }+ const treeFiles = fs+ .readdirSync(path.join(CLI, 'assets/docs/tree'))+ .filter(name => name.endsWith('.doc.mjs'))+ .map(name => `assets/docs/tree/${name}`);+ for (const file of treeFiles) {+ const node = [...tree.nodes.values()].find(n =>+ [n.source, n.ref?.topicFile].some(s => String(s ?? '').endsWith(file)),+ );+ if (!node || !reached(`${TOP} ${node.route}`)) unreached.push(file);+ }+ expect(unreached).toEqual([]);++ // Every doc file under the docs directory is a topic, an overlay of one+ // (`.doc.<variant>.mjs`), or a tree file: none sits where nothing reads it.+ const orphans = fs+ .readdirSync(path.join(CLI, 'assets/docs'))+ .filter(name => /\.doc\.mjs$/.test(name))+ .filter(name => !topicFiles.has(path.resolve(CLI, 'assets/docs', name)));+ expect(orphans).toEqual([]);+ expect(loaded.length).toBeGreaterThan(90);+ });++ it('resolves every typed edge a doc declares: command, fn, and related', async () => {+ const tree = await loadDocsTree();+ /** @type {string[]} */+ const broken = [];+ for (const node of tree.nodes.values()) {+ for (const edge of typedEdges(tree, node).unresolved) {+ broken.push(`${node.route}: ${edge}`);+ }+ }+ expect(broken).toEqual([]);+ });++ it('resolves every link written in a doc: inline, reference, and workflow', async () => {+ // The walk opens each resolved link as a move; a link that names no doc+ // has no command to open, so it is caught here, by the same resolver+ // `astryx doctor` uses.+ const catalog = builtinCatalog();+ expect(await docsLinkProblems(catalog, await projectTree(catalog))).toEqual(+ [],+ );+ for (const [command, res] of reads) {+ const blocks = [+ ...(res?.data?.content ?? []),+ ...(res?.data?.sections ?? []).flatMap(+ (/** @type {any} */ s) => s.content ?? [],+ ),+ ];+ for (const block of blocks) {+ if (block?.type === 'reference') {+ expect(block.link, `${command}: ${block.target}`).toBeTruthy();+ }+ for (const text of [block?.text, ...(block?.items ?? [])]) {+ if (typeof text === 'string') {+ expect(+ text.replace(/`[^`]*`/g, ''),+ `${command} shows an unresolved link`,+ ).not.toMatch(/\{@link /);+ }+ }+ }+ }+ }, SLOW);++ it('offers a way up from every read but the top, and up always ends at the top', () => {+ const noUp = [...reads]+ .filter(([command, res]) => res && command !== TOP && !res.data?.links?.up)+ .map(([command]) => command);+ expect(noUp).toEqual([]);+ /** @type {string[]} */+ const lost = [];+ for (const [command, res] of reads) {+ let at = res;+ let steps = 0;+ while (at?.data?.links?.up && steps < 10) {+ at = reads.get(at.data.links.up);+ steps++;+ }+ if (at?.type !== 'docs.list') lost.push(command);+ }+ expect(lost).toEqual([]);+ });++ it('agrees on neighbors: the next read names this one as its previous', async () => {+ /** @type {string[]} */+ const broken = [];+ // A topic's section list and its whole read are one place.+ /** @param {string | undefined} command */+ const place = command => command?.replace(/ --index$/, '');+ for (const [from, kind, to] of moves) {+ if (kind !== 'next') continue;+ const back = reads.get(to)?.data?.links?.previous;+ if (place(back) !== place(from)) broken.push(`${from} -> ${to} <- ${back}`);+ }+ expect(broken).toEqual([]);+ });++ it('opens every `astryx docs ...` command written in a doc', async () => {+ /** @type {string[]} */+ const stale = [];+ const checked = new Set();+ for (const [command, res] of reads) {+ if (!res) continue;+ for (const text of textOf(res)) {+ for (const link of docsCommandsIn(text)) {+ if (checked.has(link)) continue;+ checked.add(link);+ try {+ await open(link);+ } catch (e) {+ stale.push(`${command} names \`${link}\`: ${/** @type {Error} */ (e).message}`);+ }+ }+ }+ }+ expect(stale).toEqual([]);+ expect(checked.size).toBeGreaterThan(10);+ }, SLOW);++ it('shows only real commands with real options, in docs, hints, and the agent prompt', async () => {+ const surface = cliSurface();+ /** @type {Map<string, string>} command -> where it is shown */+ const shown = new Map();+ for (const [command, res] of reads) {+ if (!res) continue;+ for (const text of textOf(res)) {+ for (const each of shownCommands(text)) {+ if (!shown.has(each)) shown.set(each, command);+ }+ }+ }+ for (const args of HINT_READS) {+ const {stdout} = await runCli(args);+ for (const each of shownCommands(stdout)) {+ if (!shown.has(each)) shown.set(each, `astryx ${args.join(' ')}`);+ }+ }+ const prompt = fs.readFileSync(path.join(CLI, '..', '..', 'AGENTS.md'), 'utf8');+ const block = /<!-- ASTRYX-CLI:START -->([\s\S]*?)<!-- ASTRYX-CLI:END -->/.exec(prompt)?.[1] ?? '';+ for (const each of shownCommands(block)) {+ if (!shown.has(each)) shown.set(each, 'the agent prompt in AGENTS.md');+ }+ // The block `astryx init` writes into an app's AGENTS.md. Its MORE CLI+ // lines are bare subcommands, each followed by its description.+ const appBlock = generateCompressedIndex('0.0.0', {invocation: 'npx astryx'});+ for (const each of shownCommands(appBlock)) {+ if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');+ }+ const more = (appBlock.split('MORE CLI:')[1] ?? '').split(/\n\s*\n/)[0];+ const bare = [...more.matchAll(/^ {2}(\S.*?)(?: {3,}|$)/gm)].map(m => `astryx ${m[1]}`);+ expect(bare.length).toBeGreaterThan(3);+ for (const each of bare) {+ if (!shown.has(each)) shown.set(each, 'the agent block astryx init writes');+ }+ // The examples `astryx manifest --json` gives agents for each command.+ /** @param {any[]} list @returns {string[]} */+ const examplesOf = list =>+ (list ?? []).flatMap(c => [...(c.examples ?? []), ...examplesOf(c.subcommands)]);+ const examples = examplesOf(buildManifest(program, {jsonSupported: JSON_SUPPORTED}).commands);+ expect(examples.length).toBeGreaterThan(10);+ for (const each of examples) {+ if (!shown.has(each)) shown.set(each, 'the manifest examples');+ }+ /** @type {string[]} */+ const wrong = [];+ for (const [command, where] of shown) {+ const bare = command.replace(/^(?:npx |pnpm exec |yarn |bunx )/, '');+ if (WRONG_ON_PURPOSE.has(bare)) continue;+ const problem = problemWith(command, surface);+ if (AWAITING_DECISION.has(bare)) {+ if (!problem) wrong.push(`${where} shows \`${command}\`, which now works: drop it from AWAITING_DECISION`);+ continue;+ }+ if (problem) wrong.push(`${where} shows \`${command}\`: ${problem}`);+ }+ expect(wrong).toEqual([]);+ const stale = [...WRONG_ON_PURPOSE.keys(), ...AWAITING_DECISION.keys()].filter(+ command => ![...shown.keys()].some(each => each.endsWith(command)),+ );+ expect(stale).toEqual([]);+ expect(shown.size).toBeGreaterThan(50);+ }, SLOW);++ it("opens every search hit's command and parent", async () => {+ /** @type {string[]} */+ const broken = [];+ for (const query of ['assertResponse', 'token-ref', 'codemod protected files', 'agent docs', 'ERR_UNKNOWN_SECTION', 'theme', 'unorganized', 'Astryx CLI']) {+ const {data} = await search(query, {type: 'doc', limit: 20});+ for (const hit of data.results) {+ if (!hit.parent) broken.push(`"${query}": ${hit.name} has no parent`);+ for (const command of [hit.command, hit.parent].filter(Boolean)) {+ try {+ await open(command);+ } catch (e) {+ broken.push(`"${query}": ${command}: ${/** @type {Error} */ (e).message}`);+ }+ }+ }+ }+ expect(broken).toEqual([]);+ }, SLOW);+});