Skip to content

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

TypeScript
20.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Colocated tests for component-discovery, run against the real
 * @astryxdesign/core source tree plus throwaway fixtures. Complements
 * component-discovery.importpath.test.mjs (which covers the .ts-source
 * import-path derivation) by pinning the discovery/grouping/resolution
 * behavior and the crash-on-missing-src surface.
 */

import {describe, it, expect, afterAll} 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 {withListingCache} from '../fs/listing-cache.mjs';
import {
  CORE_PACKAGE,
  discoverComponents,
  familyMember,
  findComponentReadme,
  findComponentSource,
  resolveImportPath,
  discoverExternalComponentsGrouped,
  findExternalComponentDoc,
  discoverIntegrationComponents,
  findIntegrationComponentDoc,
  findIntegrationComponentSource,
  discoverOwnedComponents,
} from './component-discovery.mjs';

// packages/cli/foundation/discovery/ -> up 4 = repo root (has packages/core).
const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
const CORE = path.join(REPO, 'packages', 'core');

const SLOW = 30_000;

const tmpDirs = [];
function mkTmp(prefix) {
  const d = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
  tmpDirs.push(d);
  return d;
}
afterAll(() => {
  for (const d of tmpDirs) {
    fs.rmSync(d, {recursive: true, force: true});
  }
});

describe('discoverComponents (real core)', () => {
  it('discovers and groups real components', () => {
    const comps = discoverComponents(CORE);
    const keys = Object.keys(comps);
    expect(keys.length).toBeGreaterThan(20);
    for (const members of Object.values(comps)) {
      expect(Array.isArray(members)).toBe(true);
      expect(members.length).toBeGreaterThan(0);
      expect([...members].sort()).toEqual(members);
    }
    expect([...keys].sort((a, b) => a.localeCompare(b))).toEqual(keys);
    expect(keys).toContain('Button');
    expect(comps.Button).toContain('Button');
    expect(comps.Button).toContain('IconButton');
    expect(comps.Button.length).toBeGreaterThan(1);
  }, SLOW);

  it('never emits a non-ASCII (translated) group key', () => {
    // Regression: a `group:` prop inside a docsZh propDescriptions block leaked
    // a Chinese string as a group key in the default (English) listing.
    const comps = discoverComponents(CORE);
    for (const key of Object.keys(comps)) {
      expect([...key].every(ch => ch.charCodeAt(0) < 128)).toBe(true);
    }
  }, SLOW);

  it('honors group, hidden, and hiddenComponents from a directory doc', () => {
    const core = mkTmp('as-cd-group-');
    const dir = path.join(core, 'src', 'Foo');
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(path.join(dir, 'XDSFoo.tsx'), 'x');
    fs.writeFileSync(path.join(dir, 'XDSFooInternal.tsx'), 'x');
    fs.writeFileSync(
      path.join(dir, 'Foo.doc.mjs'),
      "export default {\n  group: 'Widgets',\n  hiddenComponents: ['FooInternal'],\n};\n",
    );
    expect(discoverComponents(core)).toEqual({Widgets: ['Foo']});
  });

  it('does not read a group: nested in a propDescriptions block', () => {
    // The ChatMessageBubble bug: a `group:` at 4-space indent inside
    // propDescriptions must NOT be picked up as the component's group.
    const core = mkTmp('as-cd-nested-');
    const dir = path.join(core, 'src', 'Bubble');
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(path.join(dir, 'XDSBubble.tsx'), 'x');
    fs.writeFileSync(
      path.join(dir, 'Bubble.doc.mjs'),
      'export default {\n' +
        "  displayName: 'Bubble',\n" +
        '  propDescriptions: {\n' +
        "    group: 'position within a multi-bubble group',\n" +
        '  },\n' +
        '};\n',
    );
    // No top-level group -> falls back to the component name, NOT the prop text.
    expect(discoverComponents(core)).toEqual({Bubble: ['Bubble']});
  });

  it('skips an entire directory whose doc is hidden: true', () => {
    const core = mkTmp('as-cd-hidden-');
    const dir = path.join(core, 'src', 'Bar');
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(path.join(dir, 'XDSBar.tsx'), 'x');
    fs.writeFileSync(path.join(dir, 'Bar.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
    expect(discoverComponents(core)).toEqual({});
  });

  it('omits component source files that have no sibling doc file', () => {
    const core = mkTmp('as-cd-nodoc-');
    const dir = path.join(core, 'src', 'Naked');
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(path.join(dir, 'XDSNaked.tsx'), 'x');
    expect(discoverComponents(core)).toEqual({});
  });

  it('reads the docs once per operation and fresh outside one', () => {
    const core = mkTmp('as-cd-once-');
    const dir = path.join(core, 'src', 'Foo');
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(path.join(dir, 'XDSFoo.tsx'), 'x');
    const doc = path.join(dir, 'Foo.doc.mjs');
    fs.writeFileSync(doc, 'export default {};\n');
    withListingCache(() => {
      const first = discoverComponents(core);
      expect(first).toEqual({Foo: ['Foo']});
      first.Foo.push('Bar');
      fs.writeFileSync(doc, "export default {\n  group: 'Widgets',\n};\n");
      // The operation read the doc once, so the edit does not reach it. A
      // change to one caller's result does not reach the next caller.
      expect(discoverComponents(core)).toEqual({Foo: ['Foo']});
    });
    expect(discoverComponents(core)).toEqual({Widgets: ['Foo']});
  });

  it('lists HStack, VStack and Heading, whose docs live in their family folders', () => {
    // Each has its own folder and import path; Stack's doc documents HStack and
    // VStack as members, and Heading's own doc sits in the Text folder.
    const comps = discoverComponents(CORE);
    expect(comps.Layout).toEqual(expect.arrayContaining(['HStack', 'Stack', 'VStack']));
    expect(comps.Heading).toEqual(['Heading']);
    expect(findComponentReadme(CORE, 'VStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
    expect(findComponentReadme(CORE, 'HStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
    expect(findComponentReadme(CORE, 'Heading')).toMatch(/[\\/]Text[\\/]Heading\.doc\.mjs$/);
    expect(resolveImportPath(CORE, 'VStack')).toBe('@astryxdesign/core/VStack');
    expect(resolveImportPath(CORE, 'Heading')).toBe('@astryxdesign/core/Heading');
  }, SLOW);

  it('lists a component folder with no doc when its family doc lists it as a member', () => {
    const core = mkTmp('as-cd-family-');
    const write = (rel, text) => {
      fs.mkdirSync(path.dirname(path.join(core, 'src', rel)), {recursive: true});
      fs.writeFileSync(path.join(core, 'src', rel), text);
    };
    write('Stack/Stack.tsx', 'x');
    write('VStack/VStack.tsx', "import {Stack} from '../Stack/Stack';\n");
    write('Prose/Prose.tsx', "import {Stack} from '../Stack/Stack';\n");
    // Listed by Stack's doc, but builds on nothing in Stack's folder.
    write('Orphan/Orphan.tsx', "import {x} from '../utils';\n");
    write(
      'Stack/Stack.doc.mjs',
      'export const docs = {\n' +
        "  name: 'Stack',\n" +
        "  group: 'Layout',\n" +
        "  relatedComponents: ['Prose'],\n" +
        "  usage: {description: 'Pair with Prose.', examples: [{code: \"<Prose label='Prose' />\"}]},\n" +
        "  components: [{name: 'Stack'}, {name: 'VStack', description: 'Vertical.'}, {name: 'Orphan'}],\n" +
        '};\n',
    );
    expect(discoverComponents(core)).toEqual({Layout: ['Stack', 'VStack']});
    expect(findComponentReadme(core, 'VStack')).toBe(
      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
    );
    // Named only in relatedComponents, prose, and an example: not documented.
    expect(findComponentReadme(core, 'Prose')).toBeNull();
    // A family doc is read only from the folders the component imports.
    expect(findComponentReadme(core, 'Orphan')).toBeNull();
  });

  it('lists a component folder with no doc when its own doc sits in a family folder', () => {
    const core = mkTmp('as-cd-sibling-');
    for (const dir of ['Text', 'Heading']) {
      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
    }
    fs.writeFileSync(path.join(core, 'src', 'Text', 'Text.tsx'), 'x');
    fs.writeFileSync(path.join(core, 'src', 'Heading', 'Heading.tsx'), 'x');
    fs.writeFileSync(
      path.join(core, 'src', 'Text', 'Text.doc.mjs'),
      "export const docs = {name: 'Text', components: [{name: 'Heading'}]};\n",
    );
    fs.writeFileSync(
      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
      "export const docs = {name: 'Heading'};\n",
    );
    expect(discoverComponents(core)).toEqual({Heading: ['Heading'], Text: ['Text']});
    expect(findComponentReadme(core, 'Heading')).toBe(
      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
    );
  });

  it('keeps a member its family hides, and a context folder, unlisted', () => {
    const core = mkTmp('as-cd-family-hidden-');
    for (const dir of ['Stack', 'VStack', 'SizeContext']) {
      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
      fs.writeFileSync(
        path.join(core, 'src', dir, `${dir}.tsx`),
        "import {Stack} from '../Stack/Stack';\n",
      );
    }
    fs.writeFileSync(
      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
      'export const docs = {\n' +
        "  name: 'Stack',\n" +
        "  hiddenComponents: ['VStack'],\n" +
        "  components: [{name: 'Stack'}, {name: 'VStack'}, {name: 'SizeContext'}],\n" +
        '};\n',
    );
    expect(discoverComponents(core)).toEqual({Stack: ['Stack']});
  });

  it('returns {} for an empty src/ dir', () => {
    const core = mkTmp('as-cd-emptysrc-');
    fs.mkdirSync(path.join(core, 'src'));
    expect(discoverComponents(core)).toEqual({});
  });

  it('throws when src/ is missing (no existsSync guard on the top readdir)', () => {
    const core = mkTmp('as-cd-nosrc-');
    expect(() => discoverComponents(core)).toThrow(/ENOENT/);
  });
});

describe('familyMember', () => {
  it("returns a family doc's entry for a member, and null for a component's own doc", () => {
    const stack = {name: 'Stack', components: [{name: 'Stack'}, {name: 'VStack', description: 'v'}]};
    expect(familyMember(stack, 'VStack')).toEqual({name: 'VStack', description: 'v'});
    expect(familyMember(stack, 'Stack')).toBeNull();
    expect(familyMember({name: 'Button'}, 'Button')).toBeNull();
    expect(familyMember(stack, 'HStack')).toBeNull();
  });
});

describe('a component name in another case is that component (spec:AST-083 FR7)', () => {
  /**
   * @param {string} core
   * @returns {(rel: string, text: string) => void}
   */
  const writer = core => (rel, text) => {
    const file = path.join(core, 'src', rel);
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, text);
  };

  it('never resolves through a module that only shares the spelling', () => {
    const core = mkTmp('as-cd-case-');
    const write = writer(core);
    write('Button/Button.tsx', 'export function Button() {}\n');
    write('Button/Button.doc.mjs', "export const docs = {name: 'Button'};\n");
    write('Tokenizer/Tokenizer.tsx', 'export function Tokenizer() {}\n');
    write(
      'Tokenizer/Tokenizer.doc.mjs',
      "export const docs = {name: 'Tokenizer'};\n",
    );
    // A motion table below a hook's doc.
    write('motion/useAnimator.ts', 'export function useAnimator() {}\n');
    write(
      'motion/useAnimator.doc.mjs',
      "export const docs = {name: 'useAnimator'};\n",
    );
    write('motion/uikit/button.ts', 'export const button = {};\n');
    // A helper module in another component's folder.
    write('CodeBlock/CodeBlock.tsx', 'export function CodeBlock() {}\n');
    write(
      'CodeBlock/CodeBlock.doc.mjs',
      "export const docs = {name: 'CodeBlock'};\n",
    );
    write('CodeBlock/tokenizer.ts', 'export function tokenize() {}\n');
    write('CodeBlock/grammar.ts', 'export const grammar = {};\n');
    for (const name of ['button', 'tokenizer']) {
      expect(findComponentReadme(core, name), name).toBeNull();
      expect(findComponentSource(core, name), name).toBeNull();
    }
    // A module's own name keeps resolving through the nearest doc.
    expect(findComponentReadme(core, 'grammar')).toBe(
      path.join(core, 'src', 'CodeBlock', 'CodeBlock.doc.mjs'),
    );
    expect(findComponentSource(core, 'Button')).toBe(
      path.join(core, 'src', 'Button', 'Button.tsx'),
    );
  });

  it('protects a sub-component too: a module spelled like Tab in another case never resolves for it', () => {
    const core = mkTmp('as-cd-sub-case-');
    const write = writer(core);
    write('TabList/TabList.tsx', 'export function TabList() {}\n');
    write('TabList/Tab.tsx', 'export function Tab() {}\n');
    write(
      'TabList/TabList.doc.mjs',
      "export const docs = {name: 'TabList'};\n",
    );
    write('motion/useAnimator.ts', 'export function useAnimator() {}\n');
    write(
      'motion/useAnimator.doc.mjs',
      "export const docs = {name: 'useAnimator'};\n",
    );
    write('motion/uikit/tab.ts', 'export const tab = {};\n');
    expect(findComponentSource(core, 'tab')).toBeNull();
    expect(findComponentReadme(core, 'tab')).toBeNull();
    expect(findComponentSource(core, 'Tab')).toBe(
      path.join(core, 'src', 'TabList', 'Tab.tsx'),
    );
  });

  it('takes a folder in another case for a component only when a file there exports its name', () => {
    const core = mkTmp('as-cd-folder-case-');
    const write = writer(core);
    write('animator/animator.ts', 'export function createAnimator() {}\n');
    write('hooks/Animator.ts', 'export function Animator() {}\n');
    write('hooks/hooks.doc.mjs', "export const docs = {name: 'hooks'};\n");
    expect(findComponentSource(core, 'Animator')).toBe(
      path.join(core, 'src', 'hooks', 'Animator.ts'),
    );
  });
});

describe('findComponentReadme / findComponentSource / resolveImportPath', () => {
  it('finds the doc + source for a top-level component', () => {
    expect(findComponentReadme(CORE, 'Button')).toMatch(/Button\.doc\.mjs$/);
    expect(findComponentSource(CORE, 'Button')).toMatch(/\.tsx$/);
    expect(resolveImportPath(CORE, 'Button')).toBe('@astryxdesign/core/Button');
  }, SLOW);

  it('returns null for an unknown component (no fuzzy fallback, unlike hooks)', () => {
    expect(findComponentReadme(CORE, 'Buton')).toBeNull();
    expect(findComponentSource(CORE, 'Buton')).toBeNull();
  }, SLOW);

  it('falls back to the bare package root when no source is found', () => {
    const core = mkTmp('as-rip-empty-');
    fs.mkdirSync(path.join(core, 'src'));
    expect(resolveImportPath(core, 'Nope')).toBe('@astryxdesign/core');
  });

  it('reads the exports map once per operation and fresh outside one', () => {
    const core = mkTmp('as-rip-once-');
    fs.mkdirSync(path.join(core, 'src'));
    const pkgPath = path.join(core, 'package.json');
    const writeExports = exports =>
      fs.writeFileSync(pkgPath, JSON.stringify({exports}));
    writeExports({'./Card': './dist/Card.js'});
    withListingCache(() => {
      expect(resolveImportPath(core, 'Card')).toBe('@astryxdesign/core/Card');
      writeExports({});
      // The operation read the map once, so the edit does not reach it.
      expect(resolveImportPath(core, 'Card')).toBe('@astryxdesign/core/Card');
    });
    expect(resolveImportPath(core, 'Card')).toBe('@astryxdesign/core');
  });

  it('throws when src/ is missing', () => {
    const core = mkTmp('as-fcr-nosrc-');
    expect(() => findComponentReadme(core, 'Button')).toThrow(/ENOENT/);
    expect(() => findComponentSource(core, 'Button')).toThrow(/ENOENT/);
    expect(() => resolveImportPath(core, 'Button')).toThrow(/ENOENT/);
  });
});

describe('external package discovery', () => {
  function buildExternalDocs() {
    const root = mkTmp('as-ext-');
    const docs = path.join(root, 'docs');
    fs.mkdirSync(path.join(docs, 'sub'), {recursive: true});
    fs.writeFileSync(path.join(docs, 'AppShell.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
    fs.writeFileSync(path.join(docs, 'sub', 'SideNav.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
    fs.writeFileSync(path.join(docs, 'Diff.doc.mjs'), 'export default {};\n');
    fs.writeFileSync(path.join(docs, 'Secret.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
    return docs;
  }


  it('discoverExternalComponentsGrouped groups + drops hidden', () => {
    expect(discoverExternalComponentsGrouped(buildExternalDocs())).toEqual({
      'App Chrome': ['AppShell', 'SideNav'],
      Diff: ['Diff'],
    });
  });

  it('findExternalComponentDoc locates a nested doc by name', () => {
    const docs = buildExternalDocs();
    expect(findExternalComponentDoc(docs, 'SideNav')).toMatch(/SideNav\.doc\.mjs$/);
    expect(findExternalComponentDoc(docs, 'Nope')).toBeNull();
  });

  it('returns empty for a missing docs dir (guarded)', () => {
    expect(discoverExternalComponentsGrouped('/no/such/dir')).toEqual({});
    expect(findExternalComponentDoc('/no/such/dir', 'X')).toBeNull();
  });
});

describe('integration component discovery (ownership-aware)', () => {
  function buildIntegration() {
    const root = mkTmp('as-integ-');
    const cdir = path.join(root, 'components');
    fs.mkdirSync(path.join(cdir, 'sub'), {recursive: true});
    fs.writeFileSync(path.join(cdir, 'MetaAppShell.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
    fs.writeFileSync(path.join(cdir, 'MetaAppShell.tsx'), 'x');
    fs.writeFileSync(path.join(cdir, 'sub', 'MetaDiff.doc.ts'), 'export default {};\n');
    fs.writeFileSync(path.join(cdir, 'MetaSecret.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
    return {name: '@acme/astryx-meta', components: cdir, issuesUrl: 'https://example.com/issues'};
  }

  it('records owner package, issuesUrl, group, and source presence; drops hidden', () => {
    const recs = discoverIntegrationComponents(buildIntegration()).sort((a, b) => a.name.localeCompare(b.name));
    expect(recs.map(r => r.name)).toEqual(['MetaAppShell', 'MetaDiff']);
    const shell = recs.find(r => r.name === 'MetaAppShell');
    expect(shell.package).toBe('@acme/astryx-meta');
    expect(shell.issuesUrl).toBe('https://example.com/issues');
    expect(shell.group).toBe('App Chrome');
    expect(shell.sourcePath).toMatch(/MetaAppShell\.tsx$/);
    expect(recs.find(r => r.name === 'MetaDiff').sourcePath).toBeNull();
  });

  it('finds an integration doc + source by name', () => {
    const integ = buildIntegration();
    expect(findIntegrationComponentDoc(integ, 'MetaAppShell')).toMatch(/MetaAppShell\.doc\.mjs$/);
    expect(findIntegrationComponentSource(integ, 'MetaAppShell')).toMatch(/MetaAppShell\.tsx$/);
    expect(findIntegrationComponentDoc(integ, 'MetaDiff')).toMatch(/MetaDiff\.doc\.ts$/);
    expect(findIntegrationComponentSource(integ, 'MetaDiff')).toBeNull();
    expect(findIntegrationComponentDoc(integ, 'Nope')).toBeNull();
  });

  it('gracefully handles a broken/missing integration components dir', () => {
    expect(discoverIntegrationComponents({name: 'x'})).toEqual([]);
    expect(discoverIntegrationComponents({name: 'x', components: '/no/such/dir'})).toEqual([]);
    expect(findIntegrationComponentDoc({name: 'x', components: '/no/such/dir'}, 'A')).toBeNull();
  });

  it('discoverOwnedComponents merges core + integration records', () => {
    const recs = discoverOwnedComponents(CORE, [buildIntegration()]);
    const button = recs.find(r => r.name === 'Button');
    expect(button).toBeDefined();
    expect(button.package).toBe(CORE_PACKAGE);
    expect(button.sourcePath).toMatch(/\.tsx$/);
    expect(recs.find(r => r.name === 'MetaAppShell').package).toBe('@acme/astryx-meta');
  }, SLOW);
});

describe('findComponentSource reads names from the folders it lists', () => {
  /** A Core folder with these files; a value of `{link}` is a symbolic link. */
  function core(files) {
    const dir = mkTmp('astryx-core-source-');
    for (const [rel, contents] of Object.entries(files)) {
      const file = path.join(dir, 'src', rel);
      fs.mkdirSync(path.dirname(file), {recursive: true});
      if (typeof contents === 'object') {
        fs.symlinkSync(path.join(dir, 'src', contents.link), file);
      } else {
        fs.writeFileSync(file, contents);
      }
    }
    return dir;
  }

  it('finds the prefixed source before the bare one, in a nested folder', () => {
    const dir = core({
      'Layout/Card/Card.tsx': '',
      'Layout/Card/XDSCard.tsx': '',
    });
    expect(findComponentSource(dir, 'Card')).toBe(
      path.join(dir, 'src', 'Layout', 'Card', 'XDSCard.tsx'),
    );
  });

  it('passes over a case variant and a link to a missing file', () => {
    const dir = core({
      'Card/card.tsx': '',
      'Card/XDSCard.tsx': {link: 'Card/Gone.tsx'},
      'Card/inner/Card.tsx': '',
    });
    expect(findComponentSource(dir, 'Card')).toBe(
      path.join(dir, 'src', 'Card', 'inner', 'Card.tsx'),
    );
  });

  it('follows a link to a file that is there', () => {
    const dir = core({
      'shared/Card.tsx': '',
      'Card/Card.tsx': {link: 'shared/Card.tsx'},
    });
    expect(findComponentSource(dir, 'Card')).toBe(
      path.join(dir, 'src', 'Card', 'Card.tsx'),
    );
  });
});