Skip to content

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

TypeScript
23.3 KB
Raw Blame
// 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 `GUIDES` claim the CLI's
    // namespace and a generated level; both are withdrawn.
    const tree = buildDocsTree({
      namespaces: [cliNs],
      docs: [],
      topics: [topic('theme', CLI), topic('CLI'), topic('GUIDES')],
    });
    expect(tree.get('cli')?.provider).toBe(CLI);
    expect(tree.get('guides')?.provider).toBe(CLI);
    expect(routes(tree)).not.toContain('CLI');
    expect(routes(tree)).not.toContain('GUIDES');
    expect(problems(tree)).toEqual(
      expect.arrayContaining([
        ['duplicate_route', expect.stringContaining('both have the route "CLI"')],
        ['duplicate_route', expect.stringContaining('takes the route "GUIDES", which the CLI\'s own docs keep')],
      ]),
    );
    // It names both docs as their authors know them, never by artifact id,
    // and says what to change.
    const taken = problems(tree).find(([, message]) => message.includes('route "CLI"'))?.[1];
    expect(taken).toBe(
      `The topic "CLI" from ${P} and Astryx's own namespace "cli" both have the route "CLI", so \`astryx docs CLI\` cannot open both. Fix: rename "CLI" (its \`name\` and its file), such as \`name: 'kit-cli'\`.`,
    );
    expect(taken).not.toContain('astryx:artifact');
    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('adopts from every package only on an experimental CLI namespace', () => {
    const CLI = '@astryxdesign/cli';
    /** @param {object} extra */
    const shared = extra => ({
      ...ns('words', {
        slots: {all: {title: 'All', accepts: {kinds: ['generic']}}},
        adopts: [
          {
            source: {group: 'words', kinds: ['generic'], packages: 'all'},
            into: 'all',
          },
        ],
        ...extra,
      }),
      provider: CLI,
      providerId: CLI,
      source: `${CLI}/tree/words.doc.mjs`,
    });
    const docs = [
      guide('mine', {group: 'words', provider: CLI, providerId: CLI}),
      guide('theirs', {group: 'words'}),
    ];
    const stable = buildDocsTree({namespaces: [shared({})], docs});
    expect(stable.get('words')?.slots[0].children).toEqual(['words/mine']);
    const experimental = buildDocsTree({
      namespaces: [shared({stability: 'experimental'})],
      docs,
    });
    expect(experimental.get('words')?.slots[0].children).toEqual([
      'words/mine',
      'words/theirs',
    ]);
  });

  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(['authoring', 'calendars', 'cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
      // 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([]);
      const roots = new Set(tree.roots().map(node => node.route));
      expect(
        nodes
          .map(node => node.route)
          .filter(route => !roots.has(route) && !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,
    });
  });
});