Skip to content

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

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

/**
 * @file i18n-english-fallback.test.mjs
 * @input scripts/i18n-english-fallback.mjs, temporary source fixtures, and
 *   the built @astryxdesign/core (built once by the node project's globalSetup)
 * @output Unit tests for key collection and wiring, and the import-cost check
 *   that a component's bundle carries its own English, not the whole catalog
 * @position Verifies architecture:internationalization's per-module English
 *   fallback. Resolution parity lives in
 *   packages/core/src/i18n/__tests__/englishFallback.test.ts.
 */

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {createRequire} from 'node:module';
import {fileURLToPath} from 'node:url';
import {afterEach, describe, expect, it} from 'vitest';
import {
  collectCatalogKeys,
  collectEnglishFallbackSlices,
  findWiringProblems,
  getSliceImportSpecifier,
  getSliceModuleName,
  isShippedSourceModule,
  renderEnglishFallbackModule,
} from './i18n-english-fallback.mjs';

const require = createRequire(import.meta.url);
const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
const CORE_DIST = path.join(REPO_ROOT, 'packages', 'core', 'dist');

const CATALOG = {
  '@astryx.button.loading': 'Loading',
  '@astryx.kbd.key.control': 'Control',
  '@astryx.pagination.next': 'Go to next page',
};

const temps = [];
function fixture(files) {
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-en-fallback-'));
  temps.push(dir);
  for (const [rel, text] of Object.entries(files)) {
    fs.mkdirSync(path.dirname(path.join(dir, rel)), {recursive: true});
    fs.writeFileSync(path.join(dir, rel), text);
  }
  return dir;
}
afterEach(() => {
  for (const dir of temps.splice(0)) {
    fs.rmSync(dir, {recursive: true, force: true});
  }
});

const FULL_FALLBACK_FILES = {
  'i18n/useTranslator.ts': 'registerFullEnglishFallback();\n',
  'i18n/publicContext.ts': 'registerFullEnglishFallback();\n',
  'PowerSearch/resolveOperatorLabel.ts': 'registerFullEnglishFallback();\n',
};

describe('collectCatalogKeys', () => {
  it('collects every string literal that is a catalog key, including keys kept in local maps', () => {
    const source = [
      `const LABEL = new Map([['ctrl', '@astryx.kbd.key.control']]);`,
      'const t = (key: string) => key;',
      't(`@astryx.button.loading`);',
      `t('@astryx.button.loading');`,
    ].join('\n');
    expect(collectCatalogKeys(source, 'A.ts', CATALOG)).toEqual([
      '@astryx.button.loading',
      '@astryx.kbd.key.control',
    ]);
  });

  it('ignores comments and strings that are not catalog keys', () => {
    const source = [
      `// t('@astryx.pagination.next')`,
      `/** t('@astryx.pagination.next') */`,
      `const other = '@astryx.not.inCatalog';`,
    ].join('\n');
    expect(collectCatalogKeys(source, 'A.tsx', CATALOG)).toEqual([]);
  });
});

describe('module paths', () => {
  it('mirrors the source path under i18n/generated-english', () => {
    expect(getSliceModuleName('Button/Button.tsx')).toBe(
      'Button/Button.generated.ts',
    );
    expect(getSliceImportSpecifier('Button/Button.tsx')).toBe(
      '../i18n/generated-english/Button/Button.generated',
    );
    expect(getSliceImportSpecifier('Table/plugins/tree/useTree.tsx')).toBe(
      '../../../i18n/generated-english/Table/plugins/tree/useTree.generated',
    );
  });

  it('derives maps only for shipped modules', () => {
    expect(isShippedSourceModule('Button/Button.tsx')).toBe(true);
    expect(isShippedSourceModule('Button/Button.test.tsx')).toBe(false);
    expect(isShippedSourceModule('Button/Button.stories.tsx')).toBe(false);
    expect(isShippedSourceModule('i18n/__tests__/resolve.test.ts')).toBe(false);
    expect(
      isShippedSourceModule('i18n/generated-locales/en.generated.ts'),
    ).toBe(false);
    expect(
      isShippedSourceModule(
        'i18n/generated-english/Button/Button.generated.ts',
      ),
    ).toBe(false);
  });

  it('renders the English for exactly the named keys', () => {
    const output = renderEnglishFallbackModule(
      CATALOG,
      ['@astryx.button.loading'],
      'Button/Button.tsx',
    );
    expect(output).toContain('"@astryx.button.loading": "Loading"');
    expect(output).not.toContain('@astryx.pagination.next');
    expect(output).toContain('@generated');
  });
});

describe('findWiringProblems', () => {
  const WIRED = [
    `import english from '../i18n/generated-english/Button/Button.generated';`,
    '',
    'registerEnglishFallback(english);',
    `t('@astryx.button.loading');`,
    '',
  ].join('\n');

  it('accepts a module that imports and registers its own map', () => {
    const dir = fixture({...FULL_FALLBACK_FILES, 'Button/Button.tsx': WIRED});
    const slices = collectEnglishFallbackSlices(CATALOG, dir);
    expect([...slices.keys()]).toEqual(['Button/Button.tsx']);
    expect(findWiringProblems(slices, dir)).toEqual([]);
  });

  it('rejects a module that names keys without its map, or never registers it', () => {
    const dir = fixture({
      ...FULL_FALLBACK_FILES,
      'Button/Button.tsx': `t('@astryx.button.loading');\n`,
      'Kbd/Kbd.tsx': [
        `import english from '../i18n/generated-english/Kbd/Kbd.generated';`,
        `t('@astryx.kbd.key.control');`,
        '',
      ].join('\n'),
    });
    const problems = findWiringProblems(
      collectEnglishFallbackSlices(CATALOG, dir),
      dir,
    );
    expect(problems).toEqual([
      expect.stringMatching(/^Button\/Button\.tsx: .*does not import/),
      expect.stringMatching(/^Kbd\/Kbd\.tsx: .*does not register/),
    ]);
  });

  it("rejects another module's map, the whole catalog, and unlisted full-catalog registration", () => {
    const dir = fixture({
      ...FULL_FALLBACK_FILES,
      'Button/Button.tsx': WIRED,
      'Link/Link.tsx': [
        `import english from '../i18n/generated-english/Button/Button.generated';`,
        `import enCatalog from '../i18n/generated-locales/en.generated';`,
        'registerFullEnglishFallback();',
        '',
      ].join('\n'),
    });
    const problems = findWiringProblems(
      collectEnglishFallbackSlices(CATALOG, dir),
      dir,
    );
    expect(problems).toEqual([
      expect.stringMatching(/^Link\/Link\.tsx: .*not its own/),
      expect.stringMatching(/^Link\/Link\.tsx: imports the whole English/),
      expect.stringMatching(/^Link\/Link\.tsx: registers the whole English/),
    ]);
  });

  it('rejects a Core module that imports the public useTranslator or context export', () => {
    const dir = fixture({
      ...FULL_FALLBACK_FILES,
      'Table/Table.tsx': [
        `import {useLocale, useTranslator} from '../i18n';`,
        `t('@astryx.pagination.next');`,
        '',
      ].join('\n'),
      'Button/Button.tsx': `import {useTranslator} from '../i18n/useTranslator';\n${WIRED}`,
      'Link/Link.tsx': `import {InternationalizationContext} from '../i18n';\n`,
    });
    expect(
      findWiringProblems(collectEnglishFallbackSlices(CATALOG, dir), dir),
    ).toEqual([
      expect.stringMatching(
        /^Button\/Button\.tsx: imports the public useTranslator/,
      ),
      expect.stringMatching(
        /^Link\/Link\.tsx: imports the public InternationalizationContext/,
      ),
      expect.stringMatching(
        /^Table\/Table\.tsx: imports the public useTranslator/,
      ),
      expect.stringMatching(
        /^Table\/Table\.tsx: .*does not import its English/,
      ),
    ]);
  });

  it('requires every public path that resolves arbitrary keys to register the whole catalog', () => {
    const dir = fixture({
      ...FULL_FALLBACK_FILES,
      'i18n/useTranslator.ts': 'export {};\n',
    });
    expect(findWiringProblems(new Map(), dir)).toEqual([
      expect.stringMatching(/^i18n\/useTranslator\.ts: must register/),
    ]);
  });
});

describe('import cost', () => {
  // What each component's import loads eagerly, from one build over all six.
  const {
    bundleImportsByEntry,
  } = require('../.github/scripts/lib/component-size.js');
  const enCatalogFile = path.join(
    CORE_DIST,
    'i18n',
    'generated-locales',
    'en.generated.js',
  );

  function catalogKeysIn(text, keys) {
    return keys.filter(key => text.includes(JSON.stringify(key)));
  }

  function loadCatalogKeys() {
    const source = fs.readFileSync(enCatalogFile, 'utf8');
    return [...source.matchAll(/["'](@astryx\.[^"']+)["']\s*:/g)].map(
      match => match[1],
    );
  }

  it('bundles only the English a component names, not the whole catalog', () => {
    const keys = loadCatalogKeys();
    expect(keys.length).toBeGreaterThan(100);
    const entries = new Map(
      ['Button', 'TreeList', 'SideNav', 'Selector', 'Table', 'DateInput'].map(
        name => [name, path.join(CORE_DIST, name, `${name}.js`)],
      ),
    );
    // Each text holds at least what the component's own import keeps, so the
    // upper bound is sound. The lower bound counts only the component's own
    // keys, which no other component's code can supply.
    const texts = bundleImportsByEntry([...entries.values()]);
    expect(texts).not.toBeNull();
    for (const [name, entry] of entries) {
      const text = texts?.get(entry);
      expect(text, name).toBeDefined();
      const bundled = catalogKeysIn(text ?? '', keys);
      const own = `@astryx.${name[0].toLowerCase()}${name.slice(1)}.`;
      expect(
        bundled.filter(key => key.startsWith(own)).length,
        name,
      ).toBeGreaterThan(0);
      expect(bundled.length, name).toBeLessThan(keys.length / 4);
    }
  });

  // Application code imports the package entry; bundlers drop the modules
  // whose exports it does not use, so check what each public export keeps.
  function bundlePackageExport(exportName) {
    const esbuild = require('esbuild');
    const entry = JSON.stringify(path.join(CORE_DIST, 'index.js'));
    const result = esbuild.buildSync({
      stdin: {
        contents: `import {${exportName}} from ${entry}; export const value = ${exportName};`,
        resolveDir: REPO_ROOT,
        loader: 'js',
      },
      bundle: true,
      minify: true,
      format: 'esm',
      platform: 'browser',
      write: false,
      external: ['react', 'react-dom', '@stylexjs/stylex'],
      define: {'process.env.NODE_ENV': '"production"'},
      loader: {'.css': 'empty'},
      logLevel: 'silent',
    });
    return result.outputFiles[0].text;
  }

  it('keeps the whole catalog on the public paths that resolve any Astryx key', () => {
    const keys = loadCatalogKeys();
    for (const exportName of ['useTranslator', 'InternationalizationContext']) {
      expect(
        catalogKeysIn(bundlePackageExport(exportName), keys),
        exportName,
      ).toHaveLength(keys.length);
    }
    // A public export that resolves no keys carries none.
    expect(catalogKeysIn(bundlePackageExport('useLocale'), keys)).toEqual([]);
  });
});