Skip to content

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

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

/**
 * Component replacement end to end (spec:AST-035 FR10–FR15): a consumer
 * project with real integration packages on disk, loaded through the real
 * Project, read through every component surface.
 */

import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {component} from './component.mjs';
import {componentKeywords, search} from '../search/search.mjs';
import {swizzleCopy} from '../swizzle/copy/copy.mjs';
import {swizzle} from '../swizzle/swizzle.mjs';
import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';
import {GAP_REPORT_CATEGORIES, gapReport} from '../gap-report/gap-report.mjs';
import {Project} from '../../foundation/config/project.mjs';
import {COMPONENT_REPLACES_CLI} from '../../foundation/integrations/cli-requirement.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

const SLOW = 60_000;
const FLOOR = {'@astryxdesign/cli': `>=${COMPONENT_REPLACES_CLI}`};

let tmpDir;

beforeEach(() => {
  // Under the repository so the project resolves the workspace's Core.
  tmpDir = fs.mkdtempSync(
    path.join(REPO_ROOT, '.astryx-component-replacement-'),
  );
});

afterEach(() => {
  fs.rmSync(tmpDir, {recursive: true, force: true});
});

/**
 * An integration package in the consumer's node_modules.
 * @param {string} name
 * @param {Array<{name: string, replaces?: string}>} components
 * @param {Record<string, string>} [peers]
 */
function writeIntegration(name, components, peers) {
  const pkgDir = path.join(tmpDir, 'node_modules', ...name.split('/'));
  const componentsDir = path.join(pkgDir, 'components');
  fs.mkdirSync(componentsDir, {recursive: true});
  fs.writeFileSync(
    path.join(pkgDir, 'package.json'),
    JSON.stringify({
      name,
      version: '1.0.0',
      exports: {'./components/*': './components/*.tsx'},
      ...(peers ? {peerDependencies: peers} : {}),
    }),
  );
  fs.writeFileSync(
    path.join(pkgDir, 'astryx.integration.mjs'),
    "export default {components: './components'};\n",
  );
  for (const {name: componentName, replaces} of components) {
    fs.writeFileSync(
      path.join(componentsDir, `${componentName}.doc.mjs`),
      `export default ${JSON.stringify({
        type: 'component',
        name: componentName,
        displayName: componentName,
        import: `${name}/components/${componentName}`,
        ...(replaces ? {replaces} : {}),
        keywords: ['acme'],
        usage: {description: `${componentName} for Acme apps.`},
        props: [],
      })};\n`,
    );
    fs.writeFileSync(
      path.join(componentsDir, `${componentName}.tsx`),
      `export function ${componentName}() { return null; }\n`,
    );
  }
}

/**
 * The consumer: its dependencies autolink every integration; `configured`
 * names the ones astryx.config lists, in order.
 * @param {string[]} dependencies
 * @param {string[]} [configured]
 */
function writeConsumer(dependencies, configured) {
  fs.writeFileSync(
    path.join(tmpDir, 'package.json'),
    JSON.stringify({
      name: 'consumer',
      version: '1.0.0',
      dependencies: Object.fromEntries(dependencies.map(dep => [dep, '1.0.0'])),
    }),
  );
  if (configured) {
    fs.writeFileSync(
      path.join(tmpDir, 'astryx.config.mjs'),
      `export default {integrations: ${JSON.stringify(configured)}};\n`,
    );
  }
}

/** Every entry of a component.list payload, flattened. */
function listEntries(result) {
  return Object.values(result.data.components).flat();
}

describe('a package that declares the CLI floor', () => {
  beforeEach(() => {
    writeIntegration(
      '@acme/nav',
      [{name: 'AcmeSideNav', replaces: 'SideNav'}],
      FLOOR,
    );
    writeConsumer(['@acme/nav']);
  });

  it(
    'answers to the Core name in component detail, naming its own package',
    async () => {
      const detail = await component('SideNav', {cwd: tmpDir});
      expect(detail.type).toBe('component.detail');
      expect(detail.package).toBe('@acme/nav');
      expect(detail.data).toMatchObject({
        name: 'AcmeSideNav',
        package: '@acme/nav',
      });

      const own = await component('AcmeSideNav', {cwd: tmpDir});
      expect(own.data).toEqual(detail.data);

      const props = await component('SideNav', {cwd: tmpDir, props: true});
      expect(props.package).toBe('@acme/nav');
    },
    SLOW,
  );

  it(
    'keeps the Core original behind an explicit Core selection',
    async () => {
      const core = await component('SideNav', {
        cwd: tmpDir,
        package: '@astryxdesign/core',
      });
      expect(core.package).toBe('@astryxdesign/core');
      expect(core.data.name).toBe('SideNav');

      const qualified = await component('@astryxdesign/core/SideNav', {
        cwd: tmpDir,
      });
      expect(qualified.package).toBe('@astryxdesign/core');

      const batch = await component(['SideNav', '@astryxdesign/core/SideNav'], {
        cwd: tmpDir,
      });
      expect(batch.data.results.map(result => result.result.package)).toEqual([
        '@acme/nav',
        '@astryxdesign/core',
      ]);
    },
    SLOW,
  );

  it(
    'takes the Core slot at every list detail level, once',
    async () => {
      for (const detail of /** @type {const} */ ([
        'brief',
        'compact',
        'full',
      ])) {
        const entries = listEntries(
          await component(undefined, {cwd: tmpDir, list: true, detail}),
        );
        const named = entries.filter(
          entry =>
            /SideNav$/.test(entry.name) && !/SideNav[A-Z]/.test(entry.name),
        );
        expect(named, detail).toHaveLength(1);
        expect(named[0], detail).toMatchObject({
          name: 'AcmeSideNav',
          package: '@acme/nav',
        });
      }
      const navigation = await component(undefined, {
        cwd: tmpDir,
        category: 'Navigation',
      });
      expect(navigation.data.components.Navigation).toContainEqual(
        expect.objectContaining({name: 'AcmeSideNav', package: '@acme/nav'}),
      );
      expect(
        navigation.data.components.Navigation.map(entry => entry.name),
      ).not.toContain('SideNav');
    },
    SLOW,
  );

  it(
    'is the component search returns for the Core name',
    async () => {
      const found = await search('SideNav', {cwd: tmpDir, type: 'component'});
      const results = found.data.results ?? Object.values(found.data).flat();
      const components = results.filter(
        result => result.domain === 'component',
      );
      expect(components[0]).toMatchObject({
        name: 'AcmeSideNav',
        package: '@acme/nav',
        score: 100,
      });
      expect(
        components.some(
          result =>
            result.name === 'SideNav' &&
            result.package === '@astryxdesign/core',
        ),
      ).toBe(false);
    },
    SLOW,
  );

  it(
    'is what an unqualified swizzle copies; Core stays one selection away',
    async () => {
      const copied = await swizzleCopy('SideNav', {
        cwd: tmpDir,
        output: './out',
      });
      expect(copied.package).toBe('@acme/nav');
      expect(copied.data).toMatchObject({
        component: 'AcmeSideNav',
        package: '@acme/nav',
      });
      expect(
        fs.existsSync(
          path.join(tmpDir, 'out', 'AcmeSideNav', 'AcmeSideNav.tsx'),
        ),
      ).toBe(true);

      const core = await swizzleCopy('SideNav', {
        cwd: tmpDir,
        output: './core',
        package: '@astryxdesign/core',
      });
      expect(core.data.package).toBe('@astryxdesign/core');
      expect(fs.existsSync(path.join(tmpDir, 'core', 'SideNav'))).toBe(true);
    },
    SLOW,
  );

  it(
    'leaves the swizzle list naming Core components, the replaced one included',
    async () => {
      const listed = await swizzle(undefined, {cwd: tmpDir, list: true});
      expect(listed.type).toBe('swizzle.list');
      expect(listed.data).toContain('SideNav');
      expect(listed.data).not.toContain('AcmeSideNav');
    },
    SLOW,
  );

  it(
    'routes issues and reports no findings for a valid replacement',
    async () => {
      const project = await Project.load(tmpDir);
      expect(
        (await project.componentReplacements()).forTarget('SideNav')?.package,
      ).toBe('@acme/nav');
      expect(
        (await project.issues()).filter(issue => /component/.test(issue.code)),
      ).toEqual([]);
      const checked = await integrationComponentConflicts('@acme/nav', {
        cwd: tmpDir,
      });
      expect(checked.data.issues).toEqual([]);
      expect(checked.data.conflicts).toEqual([]);
    },
    SLOW,
  );
});

describe('every surface reads the same replacement', () => {
  beforeEach(() => {
    writeIntegration(
      '@acme/nav',
      [{name: 'AcmeSideNav', replaces: 'SideNav'}],
      FLOOR,
    );
    writeConsumer(['@acme/nav']);
  });

  it(
    'routes a gap report to the replacing package, and to Core when asked',
    async () => {
      fs.writeFileSync(
        path.join(
          tmpDir,
          'node_modules',
          '@acme',
          'nav',
          'astryx.integration.mjs',
        ),
        "export default {components: './components', issuesUrl: 'https://example.com/acme/nav/issues'};\n",
      );
      const category = GAP_REPORT_CATEGORIES[0].value;
      const routed = await gapReport('SideNav', {
        cwd: tmpDir,
        category,
        reason: 'Needs a compact variant',
      });
      expect(routed.data.package).toBe('@acme/nav');
      const core = await gapReport('SideNav', {
        cwd: tmpDir,
        category,
        reason: 'Needs a compact variant',
        package: '@astryxdesign/core',
      });
      expect(core.data.package).toBe('@astryxdesign/core');
    },
    SLOW,
  );

  it.each(/** @type {const} */ (['compact', 'full']))(
    'takes the Core slot in a category list at %s detail',
    async detail => {
      const listed = await component(undefined, {
        cwd: tmpDir,
        category: 'Navigation',
        detail,
      });
      const entries = listed.data.components.Navigation;
      expect(entries).toContainEqual(
        expect.objectContaining({name: 'AcmeSideNav', package: '@acme/nav'}),
      );
      expect(entries.map(entry => entry.name)).not.toContain('SideNav');
    },
    SLOW,
  );

  it(
    'gives build the replacement keywords, not the Core original',
    async () => {
      const coreDir = path.resolve(
        import.meta.dirname,
        '..',
        '..',
        '..',
        'core',
      );
      const names = (await componentKeywords(coreDir, tmpDir)).map(
        entry => entry.name,
      );
      expect(names).toContain('AcmeSideNav');
      expect(names).not.toContain('SideNav');
    },
    SLOW,
  );

  it(
    'answers to the Core name qualified by its own package',
    async () => {
      const scoped = await component('SideNav', {
        cwd: tmpDir,
        package: '@acme/nav',
      });
      expect(scoped.package).toBe('@acme/nav');
      expect(scoped.data.name).toBe('AcmeSideNav');
      const copied = await swizzleCopy('SideNav', {
        cwd: tmpDir,
        output: './scoped',
        package: '@acme/nav',
      });
      expect(copied.data).toMatchObject({
        component: 'AcmeSideNav',
        package: '@acme/nav',
      });
    },
    SLOW,
  );

  it(
    'matches the Core name exactly, as Core lookups do',
    async () => {
      await expect(component('sidenav', {cwd: tmpDir})).rejects.toMatchObject({
        code: 'ERR_UNKNOWN_COMPONENT',
      });
    },
    SLOW,
  );
});

describe('a replacement that keeps the Core name', () => {
  it(
    'is intentional, so it is not a conflict, and it wins the bare name',
    async () => {
      writeIntegration(
        '@acme/nav',
        [{name: 'SideNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeConsumer(['@acme/nav']);
      const checked = await integrationComponentConflicts('@acme/nav', {
        cwd: tmpDir,
      });
      expect(checked.data.conflicts).toEqual([]);
      expect(checked.data.issues).toEqual([]);
      const detail = await component('SideNav', {cwd: tmpDir});
      expect(detail.package).toBe('@acme/nav');
    },
    SLOW,
  );

  it(
    'stays a conflict when the package has not opted in',
    async () => {
      writeIntegration('@acme/nav', [{name: 'SideNav', replaces: 'SideNav'}]);
      writeConsumer(['@acme/nav']);
      const checked = await integrationComponentConflicts('@acme/nav', {
        cwd: tmpDir,
      });
      expect(checked.data.conflicts.map(conflict => conflict.name)).toEqual([
        'SideNav',
      ]);
    },
    SLOW,
  );
});

describe('a component the replacement shadows', () => {
  it(
    'keeps a search hit whose command names its own package',
    async () => {
      writeIntegration('@acme/native', [{name: 'SideNav'}]);
      writeIntegration(
        '@acme/nav',
        [{name: 'AcmeSideNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeConsumer(['@acme/native', '@acme/nav']);
      const found = await search('SideNav', {cwd: tmpDir, type: 'component'});
      const results = found.data.results ?? Object.values(found.data).flat();
      const shadowed = results.find(
        result =>
          result.name === 'SideNav' && result.package === '@acme/native',
      );
      expect(shadowed?.command).toBe(
        'astryx component SideNav --package @acme/native',
      );
      const native = await component('SideNav', {
        cwd: tmpDir,
        package: '@acme/native',
      });
      expect(native.package).toBe('@acme/native');
    },
    SLOW,
  );
});

describe('a package published without the CLI floor', () => {
  beforeEach(() => {
    writeIntegration('@acme/old', [
      {name: 'OldTopNav', replaces: 'TopNav'},
      {name: 'Missing', replaces: 'NoSuchComponent'},
    ]);
    writeConsumer(['@acme/old']);
  });

  it(
    'keeps the component under its own name and Core selected',
    async () => {
      const topNav = await component('TopNav', {cwd: tmpDir});
      expect(topNav.package).toBe('@astryxdesign/core');
      expect(topNav.data.name).toBe('TopNav');

      const own = await component('OldTopNav', {cwd: tmpDir});
      expect(own.package).toBe('@acme/old');

      const entries = listEntries(
        await component(undefined, {cwd: tmpDir, list: true}),
      );
      expect(entries).toContainEqual({
        name: 'TopNav',
        package: '@astryxdesign/core',
      });
      expect(entries).toContainEqual(
        expect.objectContaining({name: 'OldTopNav', package: '@acme/old'}),
      );

      const found = await search('TopNav', {cwd: tmpDir, type: 'component'});
      const results = found.data.results ?? Object.values(found.data).flat();
      expect(results[0]).toMatchObject({
        name: 'TopNav',
        package: '@astryxdesign/core',
      });
    },
    SLOW,
  );

  it(
    'reports every finding to its author as a warning, and nothing to the app',
    async () => {
      const checked = await integrationComponentConflicts('@acme/old', {
        cwd: tmpDir,
      });
      expect(
        checked.data.issues
          .map(issue => `${issue.severity}:${issue.code}`)
          .sort(),
      ).toEqual(
        [
          'warning:inactive_component_replacement',
          'warning:inactive_component_replacement',
          'warning:missing_component_replacement_target',
        ].sort(),
      );
      // Project issues feed project Doctor and the everyday-command nudge: an
      // app that loads a package without the floor sees nothing new.
      const project = await Project.load(tmpDir);
      expect(
        (await project.issues()).filter(issue =>
          /replacement/.test(issue.code),
        ),
      ).toEqual([]);
    },
    SLOW,
  );
});

describe('an opted-in package with an invalid declaration', () => {
  it(
    'is an error and never replaces Core',
    async () => {
      writeIntegration(
        '@acme/bad',
        [
          {name: 'BadThing', replaces: 'NoSuchComponent'},
          {name: 'Button', replaces: 'Card'},
        ],
        FLOOR,
      );
      writeConsumer(['@acme/bad']);
      const checked = await integrationComponentConflicts('@acme/bad', {
        cwd: tmpDir,
      });
      expect(
        checked.data.issues
          .map(issue => `${issue.severity}:${issue.code}`)
          .sort(),
      ).toEqual(
        [
          'error:invalid_component_replacement',
          'error:missing_component_replacement_target',
        ].sort(),
      );
      const card = await component('Card', {cwd: tmpDir});
      expect(card.package).toBe('@astryxdesign/core');
    },
    SLOW,
  );
});

describe('several packages replacing one Core component', () => {
  it(
    'lets the later configured package win, and Doctor warns',
    async () => {
      writeIntegration(
        '@acme/first',
        [{name: 'FirstNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeIntegration(
        '@acme/second',
        [{name: 'SecondNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeConsumer(
        ['@acme/first', '@acme/second'],
        ['@acme/first', '@acme/second'],
      );
      const detail = await component('SideNav', {cwd: tmpDir});
      expect(detail.package).toBe('@acme/second');
      const project = await Project.load(tmpDir);
      const issues = (await project.issues()).filter(
        issue => issue.code === 'ambiguous_component_replacement',
      );
      expect(issues).toHaveLength(1);
      expect(issues[0]).toMatchObject({
        package: '@acme/second',
        severity: 'warning',
      });
    },
    SLOW,
  );

  it(
    'lets an explicitly configured package beat an autolinked one',
    async () => {
      writeIntegration(
        '@acme/explicit',
        [{name: 'ExplicitNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeIntegration(
        '@acme/auto',
        [{name: 'AutoNav', replaces: 'SideNav'}],
        FLOOR,
      );
      writeConsumer(['@acme/explicit', '@acme/auto'], ['@acme/explicit']);
      const detail = await component('SideNav', {cwd: tmpDir});
      expect(detail.package).toBe('@acme/explicit');
    },
    SLOW,
  );
});