Skip to content

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

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

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {performance} from 'node:perf_hooks';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {checkBuilt, scanBuilt} from './built-checks.mjs';
import {builtIntegrationPackages} from './_adapter.mjs';
import {runChecks} from './doctor.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';

/** @type {string} */
let dir;

/**
 * @param {Record<string, string>} files relative path → contents
 */
function write(files) {
  for (const [rel, text] of Object.entries(files)) {
    const file = path.join(dir, rel);
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, text);
  }
}

/**
 * @param {string} target
 * @param {string[]} [packages]
 * @param {{fileLimit?: number}} [options]
 */
function check(target, packages = [], options = {}) {
  const [usage, purity] = checkBuilt(target, {cwd: dir, packages, ...options});
  return {usage, purity};
}

beforeEach(() => {
  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-built-'));
});

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

describe('built-astryx-usage', () => {
  it('fails a hand-written page with no Astryx at all, with the way to rebuild it', () => {
    write({
      'out/index.html':
        '<!doctype html><html><head><style>.cat{display:flex}</style></head><body><div class="cat"><h1>Cats</h1></div></body></html>',
    });

    for (const target of ['out', 'out/index.html']) {
      const {usage, purity} = check(target);
      expect(usage.status).toBe('fail');
      expect(usage.message).toContain('does not use Astryx');
      expect(usage.fix).toContain('build "<what the page is>"');
      expect(usage.fix).toContain('Do not deliver');
      // Built HTML is not source: the purity check says it did not run.
      expect(purity.status).toBe('info');
    }
  });

  it('passes source that imports Astryx components and uses them', () => {
    write({
      'src/Page.tsx':
        'import {Button} from \'@astryxdesign/core/Button\';\nexport const Page = () => <Button label="Go" />;\n',
    });

    const {usage} = check('.');
    expect(usage.status).toBe('pass');
    expect(usage.message).toContain('1 import from @astryxdesign/core');
    expect(usage.message).toContain('1 component use');
  });

  it("counts an integration's components as Astryx, by the package names the project loads", () => {
    write({
      'app/page.tsx':
        'import {AcmeBadge} from \'@acme/ui/Badge\';\nexport default () => <AcmeBadge label="New" />;\n',
    });

    expect(check('.').usage.status).toBe('fail');
    const {usage} = check('.', ['@acme/ui']);
    expect(usage.status).toBe('pass');
    expect(usage.message).toContain('@acme/ui');
  });

  it('passes built output that carries Astryx styles, minified', () => {
    write({
      'dist/assets/app.css':
        '@layer reset,astryx-base,astryx-theme;@layer astryx-base{.x1{color:red}}',
    });

    const {usage, purity} = check('dist');
    expect(usage.status).toBe('pass');
    expect(usage.message).toContain('Astryx styles in assets/app.css');
    expect(purity.status).toBe('info');
  });

  it('reads a build folder inside a project for styles but never as source', () => {
    write({
      'src/page.tsx': '<div />',
      '.next/static/chunk.js': 'var a="<div className=x>";',
      '.next/static/app.css': ':root{--astryx-layer-modal:10}',
      'node_modules/@astryxdesign/core/index.js':
        "import '@astryxdesign/core';",
    });

    const scan = scanBuilt(dir, []);
    expect(scan.sourceFiles).toBe(1);
    expect(scan.stylesheets).toEqual(['.next/static/app.css']);
    expect(scan.imports).toBe(0);
  });

  it('fails a path that does not exist, saying nothing was checked', () => {
    const [usage, ...rest] = checkBuilt('missing', {cwd: dir, packages: []});
    expect(usage.status).toBe('fail');
    expect(usage.message).toContain('does not exist');
    expect(rest).toEqual([]);
  });
});

describe('built-astryx-purity', () => {
  it("names each finding of the rubric's source check with its file and line", () => {
    write({
      'src/Page.tsx': [
        "import {VStack} from '@astryxdesign/core/VStack';",
        "import {Search} from 'lucide-react';",
        "import './page.css';",
        '// <div> in a comment is not a finding',
        'export function Page() {',
        '  return (',
        '    <VStack>',
        '      <div className="row" style={{gap: 4}}>',
        '        <Search />',
        '        <svg viewBox="0 0 1 1"><path d="M0 0" /></svg>',
        '        <input type="hidden" name="x" />',
        '      </div>',
        '    </VStack>',
        '  );',
        '}',
        '',
      ].join('\n'),
    });

    const {usage, purity} = check('.');
    expect(usage.status).toBe('pass');
    expect(purity.status).toBe('warn');
    expect(purity.message).toMatch(/^6 findings/);
    expect(purity.message).toContain(
      'src/Page.tsx:3 imports the stylesheet `./page.css`',
    );
    expect(purity.message).toContain('src/Page.tsx:8 raw `<div>`');
    expect(purity.message).toContain(
      'src/Page.tsx:9 `<Search>` from an icon library',
    );
    // The message names the first five and counts the rest.
    expect(purity.message).toContain('and 1 more');
    const all = scanBuilt(dir, [])
      .findings.map(f => `${f.file}:${f.line} ${f.message}`)
      .join('\n');
    expect(all).toContain('src/Page.tsx:10 raw `<svg>`');
    // A helper's SVG counts once, and hidden form state keeps its element.
    expect(all).not.toContain('`<path>`');
    expect(all).not.toContain('`<input>`');
    expect(purity.fix).toContain('docs is-my-code-good');
  });

  it('passes source with no raw element, icon or custom style', () => {
    write({
      'src/Page.tsx':
        "import {Text} from '@astryxdesign/core/Text';\nimport type {ReactNode} from 'react';\nexport const Page = (): ReactNode => <Text>Hi</Text>;\n",
    });

    expect(check('src').purity.status).toBe('pass');
  });
});

describe('what a --built path counts', () => {
  it('reads a bundle as build output: the source check says it was not inspected', () => {
    write({
      'dist/assets/index.js':
        'import "./a.css";import{jsx as e}from"react/jsx-runtime";export default()=>e("div",{className:"x"});',
    });
    const {purity} = check('dist');
    expect(purity.status).toBe('info');
    expect(purity.message).toContain('Not inspected');
    expect(purity.fix).toContain('doctor --built <project folder>');
  });

  it('inspects JSX in a .js source file and a .tsx file inside a folder named build', () => {
    write({
      'src/page.js':
        'export default function Page() {\n  return <div>Hi</div>;\n}\n',
      'src/build/Form.tsx': 'export const Form = () => <button>Go</button>;\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.jsxFiles).toBe(2);
    expect(scan.findings.map(f => `${f.file}:${f.message}`)).toEqual([
      'build/Form.tsx:raw `<button>`: use `Button` or `IconButton`',
      'page.js:raw `<div>`: use `VStack`, `HStack`, `Grid`, `Card`, `Section` or `Center`',
    ]);
  });

  it('keeps a side-effect import apart from the import after it', () => {
    write({
      'src/Page.tsx':
        "import './page.css';\nimport {Button} from '@astryxdesign/core/Button';\nexport const Page = () => <Button label=\"Go\" />;\n",
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.imports).toBe(1);
    expect(scan.componentUses).toBe(1);
    expect(scan.findings.map(f => f.message)).toContain(
      'imports the stylesheet `./page.css`: use component props and tokens',
    );
  });

  it('names the integrations by the declared dependencies that ship a manifest, running nothing', () => {
    write({
      'package.json': JSON.stringify({
        name: 'app',
        dependencies: {'@acme/ui': '1.0.0', 'left-pad': '1.0.0'},
      }),
      'astryx.config.mjs':
        "import fs from 'node:fs';\nfs.writeFileSync(new URL('./ran.txt', import.meta.url), 'ran');\nexport default {};\n",
      'node_modules/@acme/ui/package.json': '{"name":"@acme/ui"}',
      'node_modules/@acme/ui/astryx.integration.mjs': 'export default {};\n',
      'node_modules/left-pad/package.json': '{"name":"left-pad"}',
      'out/index.html': '<p>x</p>',
    });
    expect(builtIntegrationPackages('out', dir)).toEqual(['@acme/ui']);
    expect(fs.existsSync(path.join(dir, 'ran.txt'))).toBe(false);
  });
});

describe('--built limits and speed', () => {
  it('finds an integration hoisted to the workspace root', () => {
    write({
      'package.json': JSON.stringify({name: 'root', workspaces: ['apps/*']}),
      'node_modules/@acme/ui/package.json': '{"name":"@acme/ui"}',
      'node_modules/@acme/ui/astryx.integration.mjs': 'export default {};\n',
      'apps/web/package.json': JSON.stringify({
        name: 'web',
        dependencies: {'@acme/ui': '1.0.0'},
      }),
      'apps/web/out/index.html': '<p>x</p>',
    });
    expect(builtIntegrationPackages('apps/web/out', dir)).toEqual(['@acme/ui']);
  });

  it('says not fully inspected when a source file is over the size limit', () => {
    write({
      'src/Page.tsx':
        "import {Text} from '@astryxdesign/core/Text';\nexport const Page = () => <Text>Hi</Text>;\n",
      'src/Huge.tsx': `export const Huge = () => null;\n${'// x\n'.repeat(1_100_000)}`,
    });
    const {purity} = check('src');
    expect(purity.status).toBe('info');
    expect(purity.message).toContain('Not fully inspected');
    expect(purity.message).toContain('over 5 MB');
  });

  it('places findings in a large JSX file quickly', () => {
    const body = '<div>row</div>\n'.repeat(60_000);
    write({'src/Big.tsx': `export const Big = () => (\n<>\n${body}</>);\n`});
    const started = performance.now();
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.findings.length).toBe(60_000);
    expect(scan.findings.at(-1)?.line).toBe(60_002);
    expect(performance.now() - started).toBeLessThan(5_000);
  });
});

describe('--built edge cases', () => {
  it('reads the stylesheet a built page links when given the page alone', () => {
    write({
      'dist/index.html':
        '<!doctype html><html><head><link rel="stylesheet" href="/assets/index.css"><script type="module" src="./assets/index.js"></script></head><body><div id="root"></div></body></html>',
      'dist/assets/index.css': '@layer astryx-base{.x{color:red}}',
      'dist/assets/index.js': 'console.log(1)',
    });
    const {usage} = check('dist/index.html');
    expect(usage.status).toBe('pass');
    expect(usage.message).toContain('Astryx styles in assets/index.css');
  });

  it('inspects a .js page whose JSX starts with a fragment', () => {
    write({
      'src/page.js':
        'export default function Page() {\n  return (\n    <>\n      <div>Hi</div>\n    </>\n  );\n}\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.jsxFiles).toBe(1);
    expect(scan.findings).toHaveLength(1);
  });

  it('warns, not fails, when the file limit ends the read before any Astryx', () => {
    // One more file than a read of 50 takes, spread over 5 folders. The
    // default limit reads the same way, so a small one keeps the folder small.
    for (let i = 0; i < 51; i++) {
      write({[`a/${i % 5}/${i}.txt`]: ''});
    }
    const {usage} = check('.', [], {fileLimit: 50});
    expect(usage.status).toBe('warn');
    expect(usage.message).toContain('went unread');
    expect(usage.message).toContain('the first 50 files');
  });

  it('finds a root-relative asset from the build root for a page in a subfolder', () => {
    write({
      'dist/about/index.html':
        '<!doctype html><link rel="stylesheet" href="/assets/app.css"><div id="root"></div>',
      'dist/assets/app.css': '@layer astryx-theme{.x{color:red}}',
    });
    expect(check('dist/about/index.html').usage.status).toBe('pass');
  });

  it('warns, not fails, when a page links a file that is not there', () => {
    write({
      'out/index.html': '<link rel="stylesheet" href="./missing.css"><p>x</p>',
    });
    const {usage} = check('out/index.html');
    expect(usage.status).toBe('warn');
    expect(usage.message).toContain('not there');
  });

  it('inspects JSX in a .js file wherever it opens', () => {
    write({
      'src/page.js':
        'export const a = x || <div>A</div>;\nexport const b = [<span key="b">B</span>];\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.jsxFiles).toBe(1);
    expect(scan.findings).toHaveLength(2);
  });

  it('fails an empty folder as nothing checked, and warns when the only source is too big to read', () => {
    fs.mkdirSync(path.join(dir, 'empty'));
    expect(check('empty').usage.message).toContain('nothing was checked');
    write({
      'big/Page.tsx': `import {Text} from '@astryxdesign/core/Text';\n${'// x\n'.repeat(1_100_000)}`,
    });
    const {usage} = check('big');
    expect(usage.status).toBe('warn');
    expect(usage.message).toContain('over 5 MB');
  });

  it('fails a page with no Astryx that links only a missing favicon', () => {
    write({
      'out/index.html':
        '<link rel="icon" href="/favicon.ico"><link rel="manifest" href="/site.webmanifest"><p>x</p>',
    });
    expect(check('out/index.html').usage.status).toBe('fail');
  });

  it('survives a .js file with a huge array literal', () => {
    write({
      'src/data.js': `export const rows = [${'0,'.repeat(200_000)}];\nexport const A = () => <p>x</p>;\n`,
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.jsxFiles).toBe(1);
  });

  it('counts a .js file the parser cannot read as not inspected', () => {
    write({
      'src/page.js':
        'export default function Page() {\n  return <div>{</div>;\n}\n@@@\n',
    });
    const {purity} = check('src');
    expect(purity.status).toBe('info');
    expect(purity.status).not.toBe('pass');
  });

  it('keeps JSX after a "/*" string, such as a splat route', () => {
    write({
      'src/App.tsx':
        'export const App = () => (\n  <Route path="/*" element={<div>Home</div>} />\n);\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.findings.map(f => f.line)).toContain(2);
  });

  it('keeps JSX after a URL or a glob in JSX text', () => {
    write({
      'src/page.js':
        'export const A = () => (\n  <section>\n    <p>See https://example.com and src/*</p>\n    <div>Box</div>\n  </section>\n);\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.unread).toBe(0);
    expect(scan.findings.map(f => f.line)).toEqual(
      expect.arrayContaining([3, 4]),
    );
  });

  it('reads a page whose link attributes are unquoted', () => {
    write({
      'dist/index.html':
        '<!doctype html><link rel=stylesheet href=/assets/index.css><div id=root></div>',
      'dist/assets/index.css': '@layer astryx-base{.x{color:red}}',
    });
    expect(check('dist/index.html').usage.status).toBe('pass');
  });

  it('counts a barrel re-export and a CSS @import of an Astryx package', () => {
    write({
      'src/ui.ts': "export {Button, Card} from '@astryxdesign/core';\n",
      'src/index.css': "@import '@astryxdesign/core/styles.css';\n",
    });
    const {usage} = check('src');
    expect(usage.status).toBe('pass');
    expect(usage.message).toContain('@astryxdesign/core');
  });

  it('reads a .tsx with TypeScript and legacy decorators, and counts one nothing parses as unread', () => {
    write({
      'src/Ok.tsx':
        'function track(t: any) { return t; }\n@track\nclass Store { value!: string; }\nexport const A = () => <div>Hi</div>;\n',
      'src/Broken.tsx': 'export const B = () => <div>{</div>;\n@@ enum ;\n',
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.findings.filter(f => f.file === 'Ok.tsx')).toHaveLength(1);
    expect(scan.unread).toBe(1);
    expect(check('src').purity.status).not.toBe('pass');
  });

  it('does not count commented-out CSS as Astryx', () => {
    write({
      'dist/index.css':
        "/* @import '@astryxdesign/core/styles.css'; */\n/* --astryx-color: red; */\n.x { color: red; }\n",
    });
    expect(check('dist').usage.status).toBe('fail');
  });

  it('does not count a type-only Astryx import as use', () => {
    write({
      'src/Page.tsx': [
        "import type {ButtonProps} from '@astryxdesign/core/Button';",
        "import {type TextProps} from '@astryxdesign/core/Text';",
        "export type {CardProps} from '@astryxdesign/core/Card';",
        "export {type BadgeProps} from '@astryxdesign/core/Badge';",
        'export const Page = (props: ButtonProps & TextProps) => null;',
        '',
      ].join('\n'),
    });
    expect(check('src').usage.status).toBe('fail');
  });

  it('does not count a type-only import in a file the parser cannot read', () => {
    write({
      'src/Broken.tsx': [
        "import type {ButtonProps} from '@astryxdesign/core/Button';",
        "import {type TextProps} from '@astryxdesign/core/Text';",
        "export type {CardProps} from '@astryxdesign/core/Card';",
        "export {type BadgeProps} from '@astryxdesign/core/Badge';",
        'export const B = () => <div>{</div>;',
        '@@ enum ;',
        '',
      ].join('\n'),
    });
    expect(check('src').usage.status).not.toBe('pass');
  });

  it('does not count an import written only in a string or JSX text', () => {
    write({
      'src/Page.tsx': [
        "const sample = `import {Button} from '@astryxdesign/core/Button';`;",
        'export const Page = () => (',
        "  <pre>import {Text} from '@astryxdesign/core/Text';</pre>",
        ');',
        '',
      ].join('\n'),
    });
    expect(check('src').usage.status).toBe('fail');
  });

  it('ignores a stylesheet link inside an HTML comment', () => {
    write({
      'out/index.html':
        '<!-- <link rel="stylesheet" href="./astryx.css"> --><!-- <link rel="stylesheet" href="./gone.css"> --><p>x</p>',
      'out/astryx.css': '@layer astryx-base{.x{color:red}}',
    });
    expect(check('out/index.html').usage.status).toBe('fail');
  });

  it('names unread source files in purity, with findings and without JSX', () => {
    write({
      'src/Page.tsx': 'export const Page = () => <div>Hi</div>;\n',
      'src/Broken.tsx': 'export const B = () => <div>{</div>;\n@@ enum ;\n',
    });
    const withFindings = check('src').purity;
    expect(withFindings.status).toBe('warn');
    expect(withFindings.message).toContain('not inspected: Broken.tsx');
    fs.rmSync(path.join(dir, 'src', 'Page.tsx'));
    const none = check('src').purity;
    expect(none.status).toBe('info');
    expect(none.message).toContain('Broken.tsx');
  });

  it('survives a file with more findings than a call can spread', () => {
    write({
      'src/Rows.tsx': `export const Rows = () => (\n<>\n${'<p/>\n'.repeat(200_000)}</>);\n`,
    });
    const scan = scanBuilt(path.join(dir, 'src'), []);
    expect(scan.findings.length).toBe(200_000);
  });
});

describe('doctor --built', () => {
  it('composes with --json: one envelope with the two checks last, exit 1 on a failed build', async () => {
    write({'out/index.html': '<div>no astryx</div>'});
    const result = await runCli(['--json', 'doctor', '--built', 'out'], dir);
    const envelope = JSON.parse(result.stdout);
    const ids = envelope.data.checks.map(
      (/** @type {{id: string}} */ c) => c.id,
    );
    expect(ids.slice(-2)).toEqual([
      'built-astryx-usage',
      'built-astryx-purity',
    ]);
    expect(result.status).toBe(1);
  }, 60_000);

  it('adds the two checks after the others, and plain doctor runs without them', async () => {
    write({'out/index.html': '<div>no astryx</div>'});

    const plain = await runChecks({cwd: dir});
    const built = await runChecks({cwd: dir, built: 'out'});

    expect(plain.checks.some(c => c.id.startsWith('built-'))).toBe(false);
    expect(built.checks.map(c => c.id)).toEqual([
      ...plain.checks.map(c => c.id),
      'built-astryx-usage',
      'built-astryx-purity',
    ]);
    expect(built.summary.fail).toBe(plain.summary.fail + 1);
  });
});