Skip to content

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

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

/**
 * @file The import specifier an integration component is reported under has to
 * be the SAME at every surface, and it has to resolve.
 *
 * `component` reports it as ownership metadata and `search` reports it on every
 * hit. Each used to resolve it independently, and they disagreed: `component`
 * honored a doc-authored `import` and otherwise derived the subpath from the
 * doc's directory against the owning package's `exports`, while `search` handed
 * back the bare package name — a specifier that does not resolve for a package
 * whose components live behind subpaths. An agent that searched and then
 * imported what it was told got a broken file.
 *
 * The two now share one resolver and one precedence rule, so the agreement is
 * structural. These tests pin the property rather than the implementation: ask
 * both surfaces about the same component and require the same answer, across
 * every shape a real package's `exports` takes.
 *
 * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
 * dynamically import a module from outside the project root.
 */

import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {requireNatively} from '../../test-utils/native-require.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

const require = requireNatively(import.meta.url);
/** @type {typeof import('./component.mjs')} */
const {component} = require('./component.mjs');
/** @type {typeof import('../search/search.mjs')} */
const {search} = require('../search/search.mjs');
/** @type {typeof import('../../foundation/discovery/component-discovery.mjs')} */
const {
  resolveIntegrationImportPath,
} = require('../../foundation/discovery/component-discovery.mjs');

const SLOW = 30_000;

let tmpDir;

/**
 * A consumer project with one configured integration that ships a single
 * component, `AcmeCarousel`, in a directory named after the concept rather
 * than after the component — the shape real packages use when one entry point
 * exports several components, and the case the bare-package answer got wrong.
 *
 * @param {object} [options]
 * @param {Record<string, string>} [options.exports] the owning package's
 *   `exports` map; omit it for a package that publishes no subpaths.
 * @param {string} [options.docImport] an `import` the component's doc states
 *   for itself, which is canonical and must win over any resolved subpath.
 */
function scaffold({exports: exportsMap, docImport} = {}) {
  fs.writeFileSync(
    path.join(tmpDir, 'package.json'),
    JSON.stringify({name: 'consumer', version: '1.0.0'}),
  );
  fs.writeFileSync(
    path.join(tmpDir, 'astryx.config.mjs'),
    "export default {integrations: ['@acme/widgets']};\n",
  );

  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
  const componentDir = path.join(pkgDir, 'src', 'Carousel');
  fs.mkdirSync(componentDir, {recursive: true});

  fs.writeFileSync(
    path.join(pkgDir, 'package.json'),
    JSON.stringify({
      name: '@acme/widgets',
      version: '1.0.0',
      ...(exportsMap ? {exports: exportsMap} : {}),
    }),
  );
  fs.writeFileSync(
    path.join(pkgDir, 'astryx.integration.mjs'),
    "export default {components: './src'};\n",
  );
  fs.writeFileSync(
    path.join(componentDir, 'AcmeCarousel.tsx'),
    'export const AcmeCarousel = () => null;\n',
  );
  fs.writeFileSync(
    path.join(componentDir, 'AcmeCarousel.doc.mjs'),
    `export const docs = ${JSON.stringify(
      {
        type: 'component',
        name: 'AcmeCarousel',
        displayName: 'Acme Carousel',
        keywords: ['carousel', 'slides'],
        usage: {description: 'A carousel that cycles through slides.'},
        props: [],
        ...(docImport ? {import: docImport} : {}),
      },
      null,
      2,
    )};\n`,
  );
}

/** The import `search` reports for a named component, or null. */
function searchImportFor(result, name) {
  for (const group of Object.values(result.data ?? {})) {
    if (!Array.isArray(group)) continue;
    const hit = group.find(entry => entry?.name === name);
    if (hit) return hit.import ?? null;
  }
  return null;
}

/** Both surfaces' answer for AcmeCarousel, as `{detail, found}`. */
async function bothSurfaces() {
  const detail = await component('AcmeCarousel', {cwd: tmpDir});
  const found = await search('carousel', {cwd: tmpDir});
  return {
    detail: detail.data.import,
    found: searchImportFor(found, 'AcmeCarousel'),
  };
}

const SUBPATH_EXPORTS = {
  '.': './src/index.js',
  './Carousel': './src/Carousel/index.js',
};

beforeEach(() => {
  tmpDir = fs.mkdtempSync(
    path.join(REPO_ROOT, '.astryx-import-agreement-test-'),
  );
});

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

describe('integration component import specifiers', () => {
  it(
    'component and search report the same import for the same component',
    async () => {
      scaffold({exports: SUBPATH_EXPORTS});
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'neither surface reports the bare package when a subpath is exported',
    async () => {
      scaffold({exports: SUBPATH_EXPORTS});
      const {detail, found} = await bothSurfaces();

      expect(detail).not.toBe('@acme/widgets');
      expect(found).not.toBe('@acme/widgets');
    },
    SLOW,
  );

  it(
    'both fall back to the package root when it exports no matching subpath',
    async () => {
      scaffold();
      const {detail, found} = await bothSurfaces();

      // The bare package is the honest answer here: it is what a consumer
      // would have to write by hand. What matters is that both agree on it.
      expect(detail).toBe('@acme/widgets');
      expect(found).toBe('@acme/widgets');
    },
    SLOW,
  );

  it(
    'a doc-authored import wins at both surfaces, over any resolved subpath',
    async () => {
      // The alias case: the package canonically publishes this component under
      // a name that is not its directory, and says so in its doc. Resolving the
      // directory would produce `/Carousel`, which is why the two surfaces have
      // to share the precedence rule and not just the resolver.
      scaffold({exports: SUBPATH_EXPORTS, docImport: '@acme/widgets/Alias'});
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Alias');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'a doc-authored import is honored even with no exports map at all',
    async () => {
      scaffold({docImport: '@acme/widgets/Alias'});
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Alias');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'a wildcard exports map resolves to the exported subpath at both surfaces',
    async () => {
      // `./*` publishes `./Carousel` exactly as a literal key would, so the
      // subpath is the correct answer. An earlier version of this test asserted
      // only that the two surfaces AGREED, and both agreed on the bare package
      // — a specifier that need not resolve at all here, since this package
      // publishes no `.` export. Agreement is necessary and not sufficient.
      scaffold({exports: {'./*': './src/*/index.js'}});
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'a wildcard whose target is null does not publish the subpath',
    async () => {
      // `null` blocks a subpath rather than publishing it, so the honest answer
      // is the package root at both surfaces.
      scaffold({exports: {'.': './src/index.js', './*': null}});
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'a prefixed wildcard only matches the subpaths it covers',
    async () => {
      // `./components/*` does not cover `./Carousel`, so this falls back.
      scaffold({
        exports: {'.': './src/index.js', './components/*': './src/*/index.js'},
      });
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'an exact key still wins where a wildcard would also match',
    async () => {
      scaffold({
        exports: {
          '.': './src/index.js',
          './Carousel': './src/Carousel/index.js',
          './*': './src/*/index.js',
        },
      });
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'one matching pattern among several is enough',
    async () => {
      scaffold({
        exports: {
          '.': './src/index.js',
          './blocks/*': './src/blocks/*.js',
          './*': './src/*/index.js',
          './themes/*': './themes/*.css',
        },
      });
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'a conditional export object still counts as published',
    async () => {
      // The target may be a conditions object rather than a string; what
      // matters for a specifier is that the subpath is published at all.
      scaffold({
        exports: {
          '.': './src/index.js',
          './Carousel': {
            import: './src/Carousel/index.js',
            require: './cjs/Carousel.js',
          },
        },
      });
      const {detail, found} = await bothSurfaces();

      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it('resolves from disk for a record that carries no parsed exports map', () => {
    // `loadIntegrations` parses the map onto every integration it loads, but a
    // record built by hand — as several tests and callers do — has no such
    // field. Resolution must read the manifest rather than quietly reporting
    // the bare package, because a silent degradation is how the original bug
    // reached users. `undefined` means "nobody parsed it"; `null` means the
    // loader looked and there was none.
    scaffold({exports: SUBPATH_EXPORTS});
    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
    const docPath = path.join(
      pkgDir,
      'src',
      'Carousel',
      'AcmeCarousel.doc.mjs',
    );

    expect(
      resolveIntegrationImportPath(
        {packageDir: pkgDir, docPath, packageName: '@acme/widgets'},
        'AcmeCarousel',
      ),
    ).toBe('@acme/widgets/Carousel');

    // A parsed `null` is an answer, not a gap: it must not fall back to a read.
    expect(
      resolveIntegrationImportPath(
        {
          exportsMap: null,
          packageDir: pkgDir,
          docPath,
          packageName: '@acme/widgets',
        },
        'AcmeCarousel',
      ),
    ).toBe('@acme/widgets');
  });
});

/**
 * Scaffold a default-export component doc (the shape `integration add component`
 * generates). This is a separate function because the existing scaffold writes
 * a named `export const docs`, and we need to test both.
 */
function scaffoldDefaultExport({exports: exportsMap, docImport} = {}) {
  fs.writeFileSync(
    path.join(tmpDir, 'package.json'),
    JSON.stringify({name: 'consumer', version: '1.0.0'}),
  );
  fs.writeFileSync(
    path.join(tmpDir, 'astryx.config.mjs'),
    "export default {integrations: ['@acme/widgets']};\n",
  );

  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
  const componentDir = path.join(pkgDir, 'src', 'Carousel');
  fs.mkdirSync(componentDir, {recursive: true});

  fs.writeFileSync(
    path.join(pkgDir, 'package.json'),
    JSON.stringify({
      name: '@acme/widgets',
      version: '1.0.0',
      ...(exportsMap ? {exports: exportsMap} : {}),
    }),
  );
  fs.writeFileSync(
    path.join(pkgDir, 'astryx.integration.mjs'),
    "export default {components: './src'};\n",
  );
  fs.writeFileSync(
    path.join(componentDir, 'AcmeCarousel.tsx'),
    'export const AcmeCarousel = () => null;\n',
  );
  // Default export — the shape integration add component writes
  fs.writeFileSync(
    path.join(componentDir, 'AcmeCarousel.doc.mjs'),
    `export default ${JSON.stringify(
      {
        type: 'component',
        name: 'AcmeCarousel',
        displayName: 'Acme Carousel',
        keywords: ['carousel', 'slides'],
        usage: {description: 'A carousel that cycles through slides.'},
        props: [],
        ...(docImport ? {import: docImport} : {}),
      },
      null,
      2,
    )};\n`,
  );
}

describe('default-export component doc agreement', () => {
  it(
    'component detail loads a default-export doc without crashing',
    async () => {
      scaffoldDefaultExport({exports: SUBPATH_EXPORTS});
      const result = await component('AcmeCarousel', {cwd: tmpDir});
      expect(result.type).toBe('component.detail');
      expect(result.data.name).toBe('AcmeCarousel');
      expect(result.data.import).toBe('@acme/widgets/Carousel');
      expect(result.data.package).toBe('@acme/widgets');
    },
    SLOW,
  );

  it(
    'a doc-authored import in a default export wins over the resolved subpath',
    async () => {
      scaffoldDefaultExport({
        exports: SUBPATH_EXPORTS,
        docImport: '@acme/widgets/Alias',
      });
      const result = await component('AcmeCarousel', {cwd: tmpDir});
      expect(result.data.import).toBe('@acme/widgets/Alias');
    },
    SLOW,
  );

  it(
    'search finds a default-export component with the correct import',
    async () => {
      scaffoldDefaultExport({exports: SUBPATH_EXPORTS});
      const found = await search('carousel', {cwd: tmpDir});
      const hit = searchImportFor(found, 'AcmeCarousel');
      expect(hit).toBe('@acme/widgets/Carousel');
    },
    SLOW,
  );

  it(
    'component and search agree on a default-export component',
    async () => {
      scaffoldDefaultExport({exports: SUBPATH_EXPORTS});
      const {detail, found} = await bothSurfaces();
      expect(detail).toBe('@acme/widgets/Carousel');
      expect(found).toBe(detail);
    },
    SLOW,
  );

  it(
    'list includes the integration import for a default-export component',
    async () => {
      scaffoldDefaultExport({exports: SUBPATH_EXPORTS});
      const result = await component(undefined, {cwd: tmpDir, list: true});
      expect(result.type).toBe('component.list');
      const allEntries = Object.values(result.data.components).flat();
      const entry = allEntries.find(e => e.name === 'AcmeCarousel');
      expect(entry).toBeDefined();
      expect(entry.package).toBe('@acme/widgets');
      // The import must be the integration subpath, not a core path.
      expect(/** @type {any} */ (entry).import).toBe('@acme/widgets/Carousel');
    },
    SLOW,
  );

  it(
    'list honors a default-export component doc import alias',
    async () => {
      scaffoldDefaultExport({
        exports: SUBPATH_EXPORTS,
        docImport: '@acme/widgets/Alias',
      });
      const result = await component(undefined, {cwd: tmpDir, list: true});
      expect(result.type).toBe('component.list');
      const allEntries = Object.values(result.data.components).flat();
      const entry = allEntries.find(e => e.name === 'AcmeCarousel');
      expect(/** @type {any} */ (entry).import).toBe('@acme/widgets/Alias');
    },
    SLOW,
  );
});