Skip to content

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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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);
+});