An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file A section read on a namespace (spec:AST-046 FR6): `astryx docs
* <namespace> <section>` answers from the one guide below the namespace that
* has the section, exactly as that guide's own section read does, so a section
* read that worked before a topic became a namespace still works.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {Project} from '../../foundation/config/project.mjs';
import {docs} from './docs.mjs';
import {oneGuide} from './detail/section/section.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';
const SLOW = 60_000;
/** @type {string} */
let tmpDir;
/** @param {Record<string, object>} files the integration's doc 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'};\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`,
);
}
}
/**
* @param {string} name
* @param {number} order
* @param {Array<{title: string, id?: string}>} sections
*/
function guide(name, order, sections) {
return {
type: 'generic',
name,
title: `Acme ${name}`,
description: `The ${name} guide.`,
placement: {parent: 'namespace:acme', slot: 'guides', order},
sections: sections.map(section => ({
...section,
content: [{type: 'prose', text: `${section.title} text.`}],
})),
};
}
/** A namespace of two guides that both have a section titled "...setup". */
function kit() {
return {
'acme.doc.mjs': {
type: 'namespace',
name: 'acme',
title: 'Acme',
summary: 'Everything about the Acme kit.',
slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
},
'install.doc.mjs': guide('install', 1, [
{title: 'Package setup', id: 'package-setup'},
{title: 'Verify'},
]),
'theme.doc.mjs': guide('theme', 2, [
{title: 'Theme setup'},
{title: 'Dark mode'},
]),
};
}
beforeEach(() => {
tmpDir = fs.mkdtempSync(
path.join(REPO_ROOT, '.astryx-namespace-section-test-'),
);
});
afterEach(() => {
fs.rmSync(tmpDir, {recursive: true, force: true});
});
describe('a section read on a namespace', () => {
it(
'ignores a catalog key a caller passes: the read loads its own project',
async () => {
const reference = await docs('authoring/field-reference', undefined, {
index: true,
});
const key = reference.data.sections[0].id;
const expected = await docs('authoring', key);
// An undeclared option is not a control (spec:AST-017 FR14).
expect(
await docs('authoring', key, /** @type {any} */ ({catalog: 'npm'})),
).toEqual(expected);
expect(
await docs('tokens', undefined, /** @type {any} */ ({catalog: 'npm'})),
).toEqual(await docs('tokens'));
},
SLOW,
);
it(
"loads the project once: every guide below the namespace reads from the read's own catalog",
async () => {
const reference = await docs('authoring/field-reference', undefined, {
index: true,
});
const key = reference.data.sections[0].id;
const load = vi.spyOn(Project, 'load');
try {
const read = await docs('authoring', key);
expect(read).toMatchObject({
type: 'docs.detail.section',
data: {id: key},
});
// One load for the read, not one more for each of the dozens of
// guides below `authoring`.
expect(load).toHaveBeenCalledTimes(1);
} finally {
load.mockRestore();
}
},
SLOW,
);
it(
'returns the one guide section, by key and by title, as the guide read does',
async () => {
for (const query of ['side-panels', 'Side panels', 'side panels']) {
const read = await docs('layout', query);
expect(read).toEqual(await docs('layout/side-panels', 'side-panels'));
expect(read).toMatchObject({
type: 'docs.detail.section',
package: '@astryxdesign/cli',
data: {id: 'side-panels', title: 'Side panels'},
});
}
// A section in a guide of its own, and a section past a guide's first.
expect((await docs('layout', 'shell')).data.id).toBe('shell');
expect((await docs('layout', 'responsive-contract')).data.id).toBe(
'responsive-contract',
);
},
SLOW,
);
it(
'reads dense and Chinese the way the guide read does',
async () => {
for (const options of [{dense: true}, {zh: true}, {lang: 'dense'}]) {
expect(await docs('layout', 'side-panels', options)).toEqual(
await docs('layout/side-panels', 'side-panels', options),
);
}
},
SLOW,
);
it(
"prefers the guide whose section key is the query over another guide's title match",
async () => {
scaffold(kit());
const read = await docs('acme', 'package-setup', {cwd: tmpDir});
expect(read.data).toMatchObject({
id: 'package-setup',
title: 'Package setup',
});
expect(read.data.links.up).toBe('astryx docs acme/install --index');
expect((await docs('acme', 'dark mode', {cwd: tmpDir})).data.title).toBe(
'Dark mode',
);
},
SLOW,
);
it(
'fails on a miss, naming every guide below the namespace',
async () => {
const err = await docs('layout', 'zzzz-nope').catch(e => e);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
const names = err.suggestions.map(s => s.name);
expect(names).toContain('layout/scaffold');
expect(names).toContain('layout/side-panels');
expect(names.every(name => name.startsWith('layout/'))).toBe(true);
// At any depth: guides under nested namespaces are named, namespaces are not.
const authoring = await docs('authoring', 'zzzz-nope').catch(e => e);
expect(authoring.code).toBe('ERR_UNKNOWN_SECTION');
expect(authoring.suggestions.map(s => s.name)).toContain(
'authoring/building-blocks/components/add-a-component',
);
expect(authoring.suggestions.map(s => s.name)).not.toContain(
'authoring/building-blocks',
);
},
SLOW,
);
it(
'still fails a section on a typed doc, naming the doc',
async () => {
const err = await docs('cli/commands/docs', 'anything').catch(e => e);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
expect(err.suggestions.map(s => s.name)).toEqual(['cli/commands/docs']);
},
SLOW,
);
});
describe('a namespace read answers what the guide read answers', () => {
/** A guide with a title match before a key match, and a second guide. */
function competing() {
return {
...kit(),
'install.doc.mjs': guide('install', 1, [
{title: 'Shell contract'},
{title: 'Shell'},
]),
'theme.doc.mjs': guide('theme', 2, [{title: 'Setup', id: 'setup'}]),
'extra.doc.mjs': guide('extra', 3, [{title: 'Theme setup'}]),
};
}
it(
'returns the section the guide read returns, even when a later section has the key',
async () => {
scaffold(competing());
const own = await docs('acme/install', 'shell', {cwd: tmpDir});
const read = await docs('acme', 'shell', {cwd: tmpDir});
expect(read).toEqual(own);
expect(read.data.title).toBe('Shell contract');
},
SLOW,
);
it(
"prefers the guide whose own match is the query's key over another guide's title match",
async () => {
scaffold(competing());
const read = await docs('acme', 'setup', {cwd: tmpDir});
expect(read).toEqual(await docs('acme/theme', 'setup', {cwd: tmpDir}));
expect(read.data).toMatchObject({id: 'setup', title: 'Setup'});
},
SLOW,
);
it(
'names the children of a namespace with no guide below it',
async () => {
const err = await docs('cli/api', 'anything').catch(e => e);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
const api = (await docs('cli/api')).data;
expect(err.suggestions.map(s => s.name)).toEqual(
api.slots.flatMap(slot => slot.children.map(child => child.route)),
);
expect(err.suggestions.length).toBeGreaterThan(0);
expect(err.message).toContain('Open one of its children');
},
SLOW,
);
});
describe('a section query that matches sections in several guides', () => {
// It used to guess; now it asks. A flat topic's section read returns its
// first title match; across guides, the read names each guide instead.
it(
'asks which guide, naming each guide that matches',
async () => {
scaffold(kit());
const err = await docs('acme', 'setup', {cwd: tmpDir}).catch(e => e);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
expect(err.suggestions).toEqual([
{name: 'acme/install', reason: 'has "Package setup"'},
{name: 'acme/theme', reason: 'has "Theme setup"'},
]);
},
SLOW,
);
it('decides in one place: oneGuide answers only a single match', () => {
const a = /** @type {any} */ ({guide: {route: 'acme/install'}});
const b = /** @type {any} */ ({guide: {route: 'acme/theme'}});
expect(oneGuide([a])).toBe(a);
expect(oneGuide([a, b])).toBeNull();
expect(oneGuide([])).toBeNull();
});
});