Skip to content

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

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

/**
 * @file check-fully-specified.test.mjs
 * Unit tests for the fully-specified-dist gate: every relative specifier in
 * emitted ESM must carry an explicit extension (#4569 shipped a dist whose
 * dynamic `import()` specifiers had none, breaking strict-ESM consumers).
 */

import {spawnSync} from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {describe, it, expect, beforeAll, afterAll} from 'vitest';
import {
  scanSource,
  findOffenders,
  failureGuidance,
} from './check-fully-specified.mjs';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');

/** Escape a literal string for embedding in a RegExp source. */
const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

describe('scanSource', () => {
  it('flags an extensionless static import specifier', () => {
    expect(scanSource(`import {x} from './XDSButton';`)).toEqual([
      './XDSButton',
    ]);
  });

  it('flags an extensionless re-export specifier', () => {
    expect(scanSource(`export * from '../utils';`)).toEqual(['../utils']);
  });

  it('flags an extensionless side-effect import', () => {
    expect(scanSource(`import './componentStyles';`)).toEqual([
      './componentStyles',
    ]);
  });

  it('flags an extensionless dynamic import() specifier', () => {
    // The exact emitted shape that broke Rspack consumers in #4569.
    const line = `const LazyXDSTooltip = /*#__PURE__*/lazy(async () => import("../Tooltip/Tooltip").then(mod => ({`;
    expect(scanSource(line)).toEqual(['../Tooltip/Tooltip']);
  });

  it('flags double-quoted specifiers (the shape babel emits)', () => {
    expect(scanSource(`import {mergeProps} from "../utils";`)).toEqual([
      '../utils',
    ]);
  });

  it('flags extensions outside the allowlist, e.g. .stylex', () => {
    // Source says './tokens.stylex' but the built file is tokens.stylex.js —
    // an emitted .stylex specifier is exactly as unresolvable as no extension.
    expect(scanSource(`import {vars} from './theme/tokens.stylex';`)).toEqual([
      './theme/tokens.stylex',
    ]);
  });

  it('handles CRLF line endings', () => {
    const source =
      `// import {x} from './commented-out';\r\n` +
      `import {x} from './nope';\r\n`;
    expect(scanSource(source)).toEqual(['./nope']);
  });

  it('accepts fully specified and non-relative specifiers', () => {
    const source = [
      `import {jsx} from "react/jsx-runtime";`,
      `import {Tooltip} from "../Tooltip/Tooltip.js";`,
      `import "./reset.css";`,
      `import data from "./data.json";`,
      `const p = import("../Tooltip/Tooltip.js");`,
      `const q = import(someVariable);`,
    ].join('\n');
    expect(scanSource(source)).toEqual([]);
  });

  it('flags an extensionless backtick dynamic import() specifier', () => {
    // A no-substitution template literal is a static specifier in disguise —
    // it escapes babel-plugin-add-extensions (which rewrites only string
    // literals), so the gate must catch it.
    expect(scanSource('const p = import(`../Tooltip/Tooltip`);')).toEqual([
      '../Tooltip/Tooltip',
    ]);
  });

  it('accepts backtick specifiers that are fully specified or computed', () => {
    const source = [
      'const p = import(`../Tooltip/Tooltip.js`);',
      'const q = (n) => import(`./locales/${n}`);',
    ].join('\n');
    expect(scanSource(source)).toEqual([]);
  });

  it('ignores specifiers on comment lines', () => {
    // dist keeps JSDoc usage examples, e.g. layerAnimations.stylex.js and
    // globalIconRegistry.js — those must not fail the gate.
    const source = [
      `/**`,
      ` * import {layerAnimations} from '../Layer/layerAnimations.stylex';`,
      ` * import { brandIcons } from './brand-icons';`,
      ` */`,
      `// import {x} from './commented-out';`,
      `export const ok = 1;`,
    ].join('\n');
    expect(scanSource(source)).toEqual([]);
  });
});

describe('findOffenders', () => {
  let distDir;

  beforeAll(() => {
    distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fully-specified-'));
    fs.writeFileSync(
      path.join(distDir, 'clean.js'),
      `import {x} from './other.js';\nexport const y = 1;\n`,
    );
    fs.mkdirSync(path.join(distDir, 'Text'));
    fs.writeFileSync(
      path.join(distDir, 'Text', 'Text.js'),
      `const L = lazy(() => import('../Tooltip/Tooltip'));\n`,
    );
    // Declarations are scanned too: NodeNext consumers need the extension
    // (#7702). Other non-runtime files are not scanned.
    fs.writeFileSync(
      path.join(distDir, 'Text', 'Text.d.ts'),
      `export * from '../types';\nexport * from '.';\n`,
    );
    fs.writeFileSync(
      path.join(distDir, 'Text', 'Text.d.ts.map'),
      `{"sources":["../types"]}\n`,
    );
  });

  afterAll(() => {
    fs.rmSync(distDir, {recursive: true, force: true});
  });

  it('reports offending runtime and declaration files with their bad specifiers', () => {
    const {checked, offenders} = findOffenders(distDir);
    // clean.js + Text/Text.js + Text/Text.d.ts — the source map is not scanned.
    expect(checked).toBe(3);
    expect(offenders).toHaveLength(2);
    expect(offenders).toContainEqual({
      file: path.join('Text', 'Text.js'),
      specifiers: ['../Tooltip/Tooltip'],
    });
    expect(offenders).toContainEqual({
      file: path.join('Text', 'Text.d.ts'),
      specifiers: ['../types', '.'],
    });
  });

  it('aggregates offenders across files, several per file', () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fully-specified-agg-'));
    try {
      fs.writeFileSync(
        path.join(dir, 'a.js'),
        `import {x} from './one';\nconst p = import('./two');\n`,
      );
      fs.writeFileSync(path.join(dir, 'b.mjs'), `export * from '../three';\n`);
      fs.writeFileSync(path.join(dir, 'ok.js'), `import './fine.css';\n`);
      const {checked, offenders} = findOffenders(dir);
      expect(checked).toBe(3);
      expect(offenders).toHaveLength(2);
      expect(offenders).toContainEqual({
        file: 'a.js',
        specifiers: ['./one', './two'],
      });
      expect(offenders).toContainEqual({
        file: 'b.mjs',
        specifiers: ['../three'],
      });
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });
});

describe('declaration scan by package type', () => {
  const SCRIPT = path.join(ROOT, 'scripts', 'check-fully-specified.mjs');

  /** Run the check in a package of `type` whose only dist file is a .d.ts. */
  const runIn = type => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fully-specified-pkg-'));
    try {
      fs.writeFileSync(
        path.join(dir, 'package.json'),
        JSON.stringify(type ? {name: 'example', type} : {name: 'example'}),
      );
      fs.mkdirSync(path.join(dir, 'dist'));
      fs.writeFileSync(
        path.join(dir, 'dist', 'index.d.ts'),
        `export * from './theme';\n`,
      );
      return spawnSync(process.execPath, [SCRIPT], {
        cwd: dir,
        encoding: 'utf-8',
      });
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  };

  it('passes extensionless declarations in a CommonJS package', () => {
    expect(runIn(undefined).status).toBe(0);
  });

  it('fails extensionless declarations in an ESM package', () => {
    const result = runIn('module');
    expect(result.status).toBe(1);
    expect(result.stderr).toContain('dist/index.d.ts: ./theme');
    expect(result.stderr).toContain('add-declaration-extensions.mjs');
  });
});

describe('failureGuidance', () => {
  it('points maintained themes at --icons-specifier', () => {
    const dir = fs.mkdtempSync(
      path.join(os.tmpdir(), 'fully-specified-theme-'),
    );
    try {
      fs.writeFileSync(
        path.join(dir, 'package.json'),
        JSON.stringify({name: '@astryxdesign/theme-example'}),
      );
      expect(failureGuidance(dir)).toContain('--icons-specifier');
      expect(failureGuidance(dir)).not.toContain(
        'babel-plugin-add-extensions.cjs',
      );
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });

  it('retains the Babel hint for packages that use the extension plugin', () => {
    const dir = fs.mkdtempSync(
      path.join(os.tmpdir(), 'fully-specified-babel-'),
    );
    try {
      fs.writeFileSync(path.join(dir, 'package.json'), '{}');
      fs.writeFileSync(path.join(dir, 'babel-plugin-add-extensions.cjs'), '');
      expect(failureGuidance(dir)).toContain('babel-plugin-add-extensions.cjs');
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });

  it('gives package-neutral guidance for other build pipelines', () => {
    const dir = fs.mkdtempSync(
      path.join(os.tmpdir(), 'fully-specified-generic-'),
    );
    try {
      fs.writeFileSync(
        path.join(dir, 'package.json'),
        JSON.stringify({name: '@astryxdesign/example'}),
      );
      expect(failureGuidance(dir)).toContain('build step');
      expect(failureGuidance(dir)).not.toContain('--icons-specifier');
      expect(failureGuidance(dir)).not.toContain(
        'babel-plugin-add-extensions.cjs',
      );
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });

  it('falls back to neutral guidance when the manifest is unreadable', () => {
    const dir = fs.mkdtempSync(
      path.join(os.tmpdir(), 'fully-specified-no-manifest-'),
    );
    try {
      expect(failureGuidance(dir)).toContain('build step');
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });
});

describe('maintained-theme build wiring', () => {
  it('keeps the fully-specified gate wired into every maintained-theme build', () => {
    const themesRoot = path.join(ROOT, 'packages', 'themes');
    const gate = path.join(ROOT, 'scripts', 'check-fully-specified.mjs');
    const packages = fs
      .readdirSync(themesRoot, {withFileTypes: true})
      .filter(entry => entry.isDirectory())
      .map(entry => path.join(themesRoot, entry.name))
      .filter(dir => fs.existsSync(path.join(dir, 'package.json')))
      .map(dir => ({
        dir,
        pkg: JSON.parse(
          fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
        ),
      }))
      .filter(({pkg}) => pkg.name?.startsWith('@astryxdesign/theme-'));

    expect(packages.length).toBeGreaterThan(0);
    for (const {dir, pkg} of packages) {
      // Derive the specifier so a move of packages/themes fails loudly here
      // instead of silently matching nothing. Any trailing build step or flag
      // is fine — what matters is that the gate still runs.
      const specifier = path.relative(dir, gate).split(path.sep).join('/');
      const invocation = new RegExp(
        `\\bnode\\s+${escapeRegExp(specifier)}(?:\\s|$)`,
      );
      expect(pkg.scripts?.build ?? '', pkg.name).toMatch(invocation);
    }
  });
});