Skip to content

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

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

/**
 * @file Playground scope coverage test.
 *
 * Validates that the generated playground scope includes every public
 * component exported from @astryxdesign/core/package.json, plus the expected
 * non-component scope entries and editor declarations used by page templates
 * and the imports needed by registered integration example blocks.
 *
 * This test reads the generated file as text (rather than importing it)
 * because the scope imports @astryxdesign/core/* which requires a prior build step.
 * Instead we verify the generator produced the correct import/scope lines.
 *
 * Run: pnpm -F @astryxdesign/docsite test
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {describe, it, expect, beforeAll} from 'vitest';
import docsiteConfig from '../../astryx.config.mjs';
import {blocks} from '../generated/blockRegistry';

const GENERATED_SCOPE_PATH = path.resolve(
  __dirname,
  '../generated/playground-scope.ts',
);

const PLAYGROUND_TYPES_PATH = path.resolve(
  __dirname,
  '../../public/playground-types.json',
);
const MONACO_SETUP_PATH = path.resolve(
  __dirname,
  '../app/playground/monacoSetup.ts',
);

const CORE_PKG_PATH = path.resolve(
  __dirname,
  '../../../../packages/core/package.json',
);

const TEMPLATE_PAGES_DIR = path.resolve(
  __dirname,
  '../../../../packages/cli/assets/templates/pages',
);

/** Mirrors the runner's asset list — those are stubbed, not scoped. */
const ASSET_RE =
  /\.(png|jpe?g|gif|svg|webp|ico|bmp|css|scss|less|sass|woff2?|ttf|eot|otf|mp4|webm|ogg|mp3|wav)$/i;

/**
 * Real import statements only. Anchored to the start of a line and required to
 * end there, so the `from '...'` inside a code sample a template renders as a
 * string — documentation-technical has one — is not mistaken for a dependency.
 * The `}` branch catches the closing line of a multi-line import.
 */
const IMPORT_RE = /^\s*(?:import\b[^'"]*?|\}\s*)from\s+'([^']+)';?\s*$/gm;

/**
 * Top-level keys of the generated `scope` object. Quoted for anything with a
 * slash or dash, bare where the name is a valid identifier. Lowercased to
 * match how the runner builds `scopeLookup`.
 */
function getScopeKeys(content: string): Set<string> {
  const keys = new Set<string>();
  for (const match of content.matchAll(/^ {2}'([^']+)':/gm)) {
    keys.add(match[1].toLowerCase());
  }
  for (const match of content.matchAll(/^ {2}([A-Za-z][\w-]*):/gm)) {
    keys.add(match[1].toLowerCase());
  }
  return keys;
}

/**
 * Same skip pattern as generate-scope.mjs — non-component exports like
 * CSS files, utils, hooks, theme, etc.
 */
const SKIP =
  /\.(css|stylex)$|\/utils$|^\.\/(theme|hooks|utils|syntax|docs|groups|reset)|\.$/;

const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*$/;
const NESTED_MODULE_NAME = /^[A-Z][A-Za-z0-9]*(?:\/[A-Za-z0-9][A-Za-z0-9-]*)+$/;

function getExpectedComponents(): string[] {
  const pkg = JSON.parse(fs.readFileSync(CORE_PKG_PATH, 'utf-8'));
  return Object.keys(pkg.exports ?? {})
    .filter(k => {
      if (SKIP.test(k)) {
        return false;
      }
      const name = k.replace('./', '');
      return COMPONENT_NAME.test(name);
    })
    .map(k => k.replace('./', ''));
}

function getExpectedNestedModules(): string[] {
  const pkg = JSON.parse(fs.readFileSync(CORE_PKG_PATH, 'utf-8'));
  return Object.keys(pkg.exports ?? {})
    .filter(k => {
      if (SKIP.test(k)) {
        return false;
      }
      return NESTED_MODULE_NAME.test(k.replace('./', ''));
    })
    .map(k => k.replace('./', ''));
}

function nestedModuleIdentifier(name: string): string {
  return `Core_${name.replace(/[^A-Za-z0-9_$]/g, '_')}`;
}

describe('playground-scope', () => {
  let expectedComponents: string[];
  let scopeContent: string;

  beforeAll(() => {
    expectedComponents = getExpectedComponents();
    if (!fs.existsSync(GENERATED_SCOPE_PATH)) {
      throw new Error(
        `Generated scope file not found at ${GENERATED_SCOPE_PATH}. ` +
          'Run `pnpm generate` (or `node scripts/generate-scope.mjs`) first.',
      );
    }
    scopeContent = fs.readFileSync(GENERATED_SCOPE_PATH, 'utf-8');
  });

  it('generated file exists and has the codegen header', () => {
    expect(scopeContent).toContain('@generated by scripts/generate-scope.mjs');
  });

  // ── Component coverage ─────────────────────────────────────────────────

  it('imports every PascalCase component from @astryxdesign/core', () => {
    const missing = expectedComponents.filter(
      name =>
        !scopeContent.includes(
          `import * as ${name} from '@astryxdesign/core/${name}';`,
        ),
    );
    expect(missing).toEqual([]);
  });

  it('imports nested modules with valid local identifiers', () => {
    const missing = getExpectedNestedModules().filter(name => {
      const identifier = nestedModuleIdentifier(name);
      return (
        !scopeContent.includes(
          `import * as ${identifier} from '@astryxdesign/core/${name}';`,
        ) ||
        !scopeContent.includes(`'@astryxdesign/core/${name}': ${identifier},`)
      );
    });
    expect(missing).toEqual([]);
    expect(scopeContent).not.toMatch(/^import \* as [^\s;]*\//m);
  });

  it('has a scope entry for every component', () => {
    const missing = expectedComponents.filter(
      name => !scopeContent.includes(`'@astryxdesign/core/${name}': ${name},`),
    );
    expect(missing).toEqual([]);
  });

  it('has a barrel @astryxdesign/core entry that spreads all components', () => {
    expect(scopeContent).toContain("'@astryxdesign/core': {");
    const missing = expectedComponents.filter(
      name => !scopeContent.includes(`...${name},`),
    );
    expect(missing).toEqual([]);
  });

  it('component count matches core exports', () => {
    const importLines = scopeContent
      .split('\n')
      .filter(l =>
        l.match(
          /^import \* as [A-Z][A-Za-z0-9]* from '@astryxdesign\/core\/[A-Z][A-Za-z0-9]*';$/,
        ),
      );
    expect(importLines.length).toBe(expectedComponents.length);
  });

  // ── Non-component scope entries ────────────────────────────────────────

  it('includes react scope with hooks', () => {
    expect(scopeContent).toContain('react: {');
    expect(scopeContent).toContain('useState');
    expect(scopeContent).toContain('useCallback');
    expect(scopeContent).toContain('useMemo');
    expect(scopeContent).toContain('useEffect');
    expect(scopeContent).toContain('useRef');
  });

  it('includes stylex mock under both specifiers', () => {
    expect(scopeContent).toContain("'@stylexjs/stylex':");
    expect(scopeContent).toContain('stylex:');
    expect(scopeContent).toContain('stylexMock');
  });

  it('includes all theme entries (bare and /built subpath)', () => {
    expect(scopeContent).toContain("'@astryxdesign/theme-neutral':");
    expect(scopeContent).toContain("'@astryxdesign/theme-neutral/built':");
    expect(scopeContent).toContain("'@astryxdesign/theme-matcha':");
    expect(scopeContent).toContain("'@astryxdesign/theme-matcha/built':");
  });

  it('includes Theme controlled wrapper and tokens', () => {
    expect(scopeContent).toContain("'@astryxdesign/core/theme': {Theme:");
    expect(scopeContent).toContain(
      "'@astryxdesign/core/theme/tokens.stylex': astryxTokens,",
    );
    expect(scopeContent).toContain('ControlledTheme');
    expect(scopeContent).toContain('SCOPE_THEMES');
  });

  it('includes lucide-react icons', () => {
    expect(scopeContent).toContain("'lucide-react': LucideIcons,");
    expect(scopeContent).toContain(
      "import * as LucideIcons from 'lucide-react';",
    );
  });

  it('includes Recharts for template previews', () => {
    expect(scopeContent).toContain("import * as Recharts from 'recharts';");
    expect(scopeContent).toContain('recharts: Recharts,');

    const playgroundTypes = JSON.parse(
      fs.readFileSync(PLAYGROUND_TYPES_PATH, 'utf-8'),
    );
    expect(playgroundTypes.recharts['index.d.ts']).toContain(
      "declare module 'recharts'",
    );
    expect(playgroundTypes.recharts['index.d.ts']).toContain(
      'export const LineChart: any;',
    );
    expect(fs.readFileSync(MONACO_SETUP_PATH, 'utf-8')).toContain(
      'packages.recharts',
    );
  });

  it('includes all heroicon variants', () => {
    expect(scopeContent).toContain(
      "'@heroicons/react/16/solid': Heroicons16Solid,",
    );
    expect(scopeContent).toContain(
      "'@heroicons/react/20/solid': Heroicons20Solid,",
    );
    expect(scopeContent).toContain(
      "'@heroicons/react/24/outline': Heroicons24Outline,",
    );
    expect(scopeContent).toContain(
      "'@heroicons/react/24/solid': Heroicons24Solid,",
    );
  });

  it('includes next/image stub', () => {
    expect(scopeContent).toContain("'next/image':");
    expect(scopeContent).toContain("React.createElement('img', props)");
  });

  // ── What the editor can type-check ─────────────────────────────────────

  it('declares every module in the preview scope for the editor', () => {
    // The scope says what the preview can require; the types bundle says
    // what Monaco can resolve. They are generated by two scripts, and a
    // module present in one but not the other shows up as a red squiggle on
    // an import that renders fine (lucide-react, the theme packages and
    // next/image all sat in that state). Model the editor's registration:
    // ambient `declare module` blocks resolve by name; core files resolve
    // by path, mounted by monacoSetup at `@astryxdesign/core/<rel>`, so a
    // subpath resolves to `<rel>.d.ts` or `<rel>/index.d.ts`.
    const playgroundTypes: Record<string, Record<string, string>> = JSON.parse(
      fs.readFileSync(PLAYGROUND_TYPES_PATH, 'utf-8'),
    );
    const declared = new Set<string>(['@astryxdesign/core']);
    for (const [pkg, files] of Object.entries(playgroundTypes)) {
      for (const [fileName, content] of Object.entries(files)) {
        if (pkg === '@astryxdesign/core') {
          declared.add(`${pkg}/${fileName.replace(/(\/index)?\.d\.ts$/, '')}`);
          continue;
        }
        for (const match of content.matchAll(/declare module '([^']+)'/g)) {
          declared.add(match[1]);
        }
      }
    }

    // Only the `scope` object's own keys: other top-level consts (the StyleX
    // mock, the theme table) also indent their members by two spaces.
    const scopeBody = scopeContent.slice(
      scopeContent.indexOf('export const scope'),
    );
    const scopeKeys = [
      ...[...scopeBody.matchAll(/^ {2}'([^']+)':/gm)].map(m => m[1]),
      ...[...scopeBody.matchAll(/^ {2}([A-Za-z][\w-]*):/gm)].map(m => m[1]),
    ];
    expect(scopeKeys.length).toBeGreaterThan(100);
    const missing = scopeKeys.filter(key => !declared.has(key)).sort();
    expect(missing).toEqual([]);

    // The path model above is only true while monacoSetup mounts each core
    // file at the package root; mounting index files alone left flat
    // subpaths such as `BaseProps` unreachable.
    expect(fs.readFileSync(MONACO_SETUP_PATH, 'utf-8')).toContain(
      'file:///node_modules/@astryxdesign/core/${relPath}',
    );
  });

  it('exposes lucide-react icons as named exports in the editor', () => {
    const playgroundTypes = JSON.parse(
      fs.readFileSync(PLAYGROUND_TYPES_PATH, 'utf-8'),
    );
    const lucide = playgroundTypes['lucide-react']['index.d.ts'];
    expect(lucide).toContain("declare module 'lucide-react'");
    // An index-signature stub gives TypeScript no named members, so every
    // `import {Smartphone} from 'lucide-react'` was TS2305. Pin one icon,
    // its `*Icon` alias, and that no such stub is left in monacoSetup.
    expect(lucide).toContain('export const Smartphone: LucideIcon;');
    expect(lucide).toContain('export const SmartphoneIcon: LucideIcon;');
    expect(fs.readFileSync(MONACO_SETUP_PATH, 'utf-8')).not.toContain(
      'Record<string, React.ComponentType',
    );
  });

  // ── Integration packages (canary whole-package bridge) ─────────────────

  it('maps every configured integration package under its own namespace', () => {
    // Whole-package admission is the contract: a NEW component exported by a
    // configured integration is playground-importable with no scope edits.
    // Each package gets a DISTINCT namespace import, so qualified imports
    // (`import {Chart} from '@astryxdesign/charts'`) keep package identity
    // even where packages share export names (@astryxdesign/lab and
    // @astryxdesign/charts currently share 14, e.g. Chart/ChartAxis/useChart).
    docsiteConfig.integrations.forEach((pkg: string, index: number) => {
      expect(scopeContent).toContain(
        `import * as Integration${index} from '${pkg}';`,
      );
      expect(scopeContent).toContain(`'${pkg}': Integration${index},`);
    });
  });

  it('orders integration scope entries after recharts, in config order, before Core', () => {
    // The preview runner builds UNQUALIFIED globals by iterating the scope
    // map in insertion order with later-wins (runner.ts buildGlobalScope),
    // so this order IS the collision policy: among integrations the
    // later-configured package owns a shared unqualified name (charts
    // shadows lab for their 14 shared exports), and Core's entries shadow
    // every integration. Qualified imports are unaffected.
    const mapStart = scopeContent.indexOf('export const scope');
    expect(mapStart).toBeGreaterThan(-1);
    const scopeMap = scopeContent.slice(mapStart);

    const integrationPositions = docsiteConfig.integrations.map(
      (pkg: string, index: number) =>
        scopeMap.indexOf(`'${pkg}': Integration${index},`),
    );
    for (const position of integrationPositions) {
      expect(position).toBeGreaterThan(-1);
    }
    expect([...integrationPositions].sort((a, b) => a - b)).toEqual(
      integrationPositions,
    );

    const rechartsPosition = scopeMap.indexOf('recharts: Recharts,');
    expect(rechartsPosition).toBeGreaterThan(-1);
    expect(Math.min(...integrationPositions)).toBeGreaterThan(rechartsPosition);

    const firstCorePosition = scopeMap.indexOf("'@astryxdesign/core");
    expect(firstCorePosition).toBeGreaterThan(-1);
    expect(firstCorePosition).toBeGreaterThan(
      Math.max(...integrationPositions),
    );
  });

  // ── What the templates actually import ─────────────────────────────────

  it('resolves every bare import in registered integration example blocks', () => {
    const scopedModules = getScopeKeys(scopeContent);
    const missing = new Set<string>();
    for (const block of blocks.filter(entry => entry.sourcePackage)) {
      for (const match of block.source.matchAll(IMPORT_RE)) {
        const id = match[1];
        if (
          !id.startsWith('.') &&
          !ASSET_RE.test(id) &&
          !scopedModules.has(id.toLowerCase())
        ) {
          missing.add(id);
        }
      }
    }
    expect([...missing].sort()).toEqual([]);
  });

  it('resolves every bare import in the page templates', () => {
    // The assertions above are an allowlist, and an allowlist only covers what
    // someone remembered to add. Recharts was missing from the scope for as
    // long as the dashboard templates existed, and nothing here noticed,
    // because nothing asked the templates what they need. The runner's
    // fallback makes that silent: an unresolved module yields a proxy whose
    // every export is `() => null`, so the charts vanished while the legends
    // around them kept painting. Ask the templates instead.
    const specifiers = new Set<string>();
    for (const dir of fs.readdirSync(TEMPLATE_PAGES_DIR)) {
      const page = path.join(TEMPLATE_PAGES_DIR, dir, 'page.tsx');
      if (!fs.existsSync(page)) {
        continue;
      }
      const source = fs.readFileSync(page, 'utf-8');
      for (const match of source.matchAll(IMPORT_RE)) {
        const id = match[1];
        // Relative paths resolve within the template, and assets are stubbed
        // by the runner on purpose.
        if (id.startsWith('.') || ASSET_RE.test(id)) {
          continue;
        }
        specifiers.add(id);
      }
    }

    expect(specifiers.size).toBeGreaterThan(5);
    // The runner lowercases both sides when resolving, so '@astryxdesign/
    // core/Theme' finds the 'theme' entry. Match that here or the test
    // reports gaps the playground does not actually have.
    const keys = getScopeKeys(scopeContent);
    const missing = [...specifiers]
      .filter(id => !keys.has(id.toLowerCase()))
      .sort();
    expect(missing).toEqual([]);
  });
});