Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
13.4 KB
Raw Blame
// 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';
import {formatCliCommand} from '../../foundation/env/package-manager.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/tokens-and-setup',
      '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(['authoring', 'calendars', 'cli', 'foundations', 'global', 'guides', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
    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(
      formatCliCommand('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'}],
      // Its one block points to the host entry's guide.
      content: [
        {
          type: 'prose',
          text: expect.stringContaining('`astryx docs cli/host-entry`'),
        },
      ],
    });
    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 () => {
    // authoring is a namespace of short guides; each guide reads like a topic.
    const integrations = await docs('authoring');
    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('authoring')).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 authoring',
      ...(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 level for its category, and it moves across it.
    const flat = (await docs('principles')).data.links;
    expect(flat.up).toBe('astryx docs guides');
    expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
    expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
    const guides = (await docs('guides')).data;
    expect(guides).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
    const foundations = (await docs('foundations')).data;
    expect(foundations).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
    // Between them the two levels hold every flat topic, each in list order.
    const topics = (await docs()).data.map(entry => entry.topic);
    const held = [guides, foundations].map(level => level.slots[0].children.map(child => child.route));
    for (const routes of held) {
      expect(routes).toEqual(topics.filter(topic => routes.includes(topic)));
    }
    expect(held.flat().sort()).toEqual([...topics].sort());
  }, 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 () => {
    const error = await docs('cli-integrations').catch(e => e);
    expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
    expect(error.suggestions[0]).toMatchObject({name: 'authoring'});
    expect((await docs()).data.map(entry => entry.topic)).not.toContain(
      'cli-integrations',
    );
  }, SLOW);

  it('an unknown route keeps every child of its namespace, closest first', async () => {
    // `tokens/usage` names the one child whose name repeats the namespace, so
    // it opens it now; a route no child answers to still lists them all.
    const error = await docs('tokens/colour').catch(e => e);
    expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
    const names = error.suggestions.map(s => s.name);
    expect(names[0]).toBe('tokens/tokens-color');
    const none = await docs('tokens/zzzz-nope').catch(e => e);
    expect([...names].sort()).toEqual(none.suggestions.map(s => s.name).sort());
  }, SLOW);

  it('an unknown flat topic is cut where the matches get weaker', async () => {
    const error = await docs('authoring-at-meta').catch(e => e);
    expect(error.suggestions.map(s => s.name)).toEqual(['authoring']);
    // One-letter words do not narrow it: `a11y` keeps the whole browse list.
    const browse = await docs('zzzz-nope').catch(e => e);
    const a11y = await docs('a11y').catch(e => e);
    expect(a11y.suggestions.length).toBe(browse.suggestions.length);
  }, SLOW);

  it('a section no guide of a namespace has -> ERR_UNKNOWN_SECTION, naming its guides', async () => {
    const err = await docs('cli', 'zzzz-nope').catch(e => e);
    expect(err).toBeInstanceOf(AstryxError);
    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
    const names = err.suggestions.map(s => s.name);
    expect(names).toContain('cli/component-lookups');
    expect(names.every(name => name.startsWith('cli/'))).toBe(true);
    // It names every guide below the namespace, at any depth.
    const deep = await docs('authoring', 'zzzz-nope').catch(e => e);
    expect(deep.code).toBe('ERR_UNKNOWN_SECTION');
    const below = deep.suggestions.map(s => s.name);
    expect(below).toContain('authoring/quick-start');
    expect(below).toContain('authoring/building-blocks/components/add-a-component');
    expect(below.every(name => name.startsWith('authoring/'))).toBe(true);
  }, 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);
});