Skip to content

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

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

/**
 * @file Tests for the API report generator and the API changes renderer.
 * @input  `__fixtures__/repo`: a built fixture package with every row kind,
 *         overloaded components, hooks and functions, an `./internal/*` entry
 *         point, a stylesheet, a component doc with theming targets, a
 *         private package, and a public-attribute record
 * @output Vitest assertions on report content, order, determinism, and change rows
 * @position scripts/api-report — guards architecture:public-component-api INV24
 */

import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {beforeAll, describe, expect, it} from 'vitest';
import {
  computeChanges,
  diffReports,
  parseReport,
  renderChanges,
  staleReportWarnings,
  usageFor,
} from './changes.mjs';
import {chooseBase, publishedPackages} from './cli.mjs';
import {generateReport} from './generate.mjs';

const FIXTURE_ROOT = path.join(
  path.dirname(fileURLToPath(import.meta.url)),
  '__fixtures__/repo',
);
const run = () =>
  generateReport({repoRoot: FIXTURE_ROOT, packageDir: 'packages/demo'});

// Building the TypeScript program is the slow part; build the report once.
let report = '';
beforeAll(async () => {
  report = await run();
}, 120_000);

const fencedRows = section =>
  report
    .split(`### ${section}`)[1]
    .split('```')[1]
    .split('\n')
    .slice(1)
    .filter(line => /^\S/.test(line));

describe('generateReport', () => {
  it('is byte-identical across runs', async () => {
    expect(await run()).toBe(report);
  }, 120_000);

  it('lists exports, props, hooks, types, custom properties, theme targets, and public attributes', () => {
    expect(report).toContain('component Chip(props: ChipProps)');
    expect(report).toContain("  prop size?: ChipSize = 'md'");
    expect(report).toContain('  prop label: string');
    expect(report).toContain('  prop onSelect?: (id: string) => void');
    expect(report).toContain(
      'hook useChipState: (initial?: boolean) => readonly [boolean, (next: boolean) => void]',
    );
    expect(report).toContain(
      '  overload (label: string, size: ChipSize) => string',
    );
    expect(report).toContain('const CHIP_SIZES: readonly ChipSize[]');
    expect(report).toContain("type ChipSize = 'sm' | 'md'");
    expect(report).toContain('interface ChipProps (props of Chip)');
    expect(report).toContain('var --demo-accent (./demo.css)');
    expect(report).toContain(
      'target chip (Chip) props [isSelected, size] states [pressed]',
    );
    expect(report).toContain(
      'attr data-is-selected (theme reflection on 1 target)',
    );
    expect(report).toContain('attr data-astryx-theme (public data attribute)');
  });

  it('reports a CommonJS entry and what a subpath pattern reaches', () => {
    expect(report).toContain('function greet: (name: string) => string');
    expect(report).toContain('pattern ./lib/locales/*.json\n  en-US\n  fr-FR');
  });

  it('marks reachable internal and experimental members instead of hiding them', () => {
    expect(report).toContain('function resetChips @internal: () => void');
    expect(report).toContain('internal resetChips via .');
    expect(report).toContain('interface ChipExperimentalOptions @experimental');
  });

  it('reads an overloaded component as ComponentProps does, and lists its other signatures as tagged overloads', () => {
    expect(report).toMatch(/^component Badge\(props: BadgeProps\)$/m);
    expect(report).toContain(
      '  overload (props: BadgeProps & { color: string }) => ReactNode @deprecated',
    );
    expect(report).toContain(
      "  overload (props: Omit<BadgeProps, 'tone'> & { experimental: { glow?: boolean } }) => ReactNode @experimental",
    );
    expect(report).toContain('interface BadgeProps (props of Badge)');
    expect(report).not.toContain('BadgeColorProps');
    expect(report).not.toContain('BadgeExperimentalProps');
  });

  it('keeps the statement tags of an overloaded component declared as a const', () => {
    expect(report).toMatch(/^component Tag\(props: TagProps\) @deprecated$/m);
    expect(report).toMatch(
      /^ {2}overload \(props: TagProps & \{color: string\}\) => ReactNode$/m,
    );
    expect(report).toContain('interface TagProps (props of Tag)');
  });

  it('lists an overloaded component as internal when its row is', () => {
    expect(report).toMatch(/^component Pill\(props: PillProps\) @internal$/m);
    expect(report).toContain('internal Pill via .');
  });

  it("tags each overload of a hook or a function with its own declaration's tags", () => {
    expect(report).toContain(
      [
        'hook useChipMode',
        "  overload (mode: 'a') => string",
        '  overload () => string @deprecated',
        "  overload (mode: 'b') => number",
      ].join('\n'),
    );
    expect(report).toContain(
      [
        'function parseChip',
        '  overload (label: string, legacy: true) => string @deprecated',
        '  overload (label: string) => string',
      ].join('\n'),
    );
  });

  it('tags the row of an overloaded hook or function only with the tags every overload has', () => {
    expect(report).toMatch(/^function parseChip$/m);
    expect(report).toContain(
      [
        'function legacyChip @deprecated',
        '  overload (label: string) => string @deprecated',
        '  overload (label: string, size: ChipSize) => string @deprecated',
      ].join('\n'),
    );
  });

  it('leaves out ./internal/*, commented-out custom properties, and unlisted attributes', () => {
    expect(report).not.toContain('secret');
    expect(report).not.toContain('--commented-out');
    expect(report).not.toContain('data-astryx-private');
  });

  it('leaves out a private --_* custom property', () => {
    expect(report).not.toContain('--_demo-private');
  });

  it('leaves out a custom property name that StyleX hashed', () => {
    expect(report).not.toContain('--x1ue0wla');
  });

  it('still lists a public --astryx-* custom property', () => {
    expect(report).toContain('var --astryx-demo-offset (./demo.css)');
  });

  it('still lists a short authored name in the StyleX prefix form', () => {
    expect(report).toContain('var --xl (./demo.css)');
  });

  it('details a declaration once and points later entry points at it', () => {
    expect(report.match(/^component Chip\(/gm)).toHaveLength(1);
    expect(report).toContain('Chip (.)');
    expect(report).toContain('function chipOnly: () => number');
  });

  it('sorts entry points and rows', () => {
    const entries = [...report.matchAll(/^## `([^`]+)`/gm)].map(m => m[1]);
    expect(entries).toEqual([
      '.',
      './chip',
      './cjs',
      './demo.css',
      './locales/*.json',
      './theme.css',
    ]);
    const names = fencedRows('Types').map(line => line.split(' ')[1]);
    expect(names).toEqual([...names].sort());
  });
});

describe('publishedPackages', () => {
  it('keeps the packages a stable release publishes', () => {
    expect(publishedPackages(FIXTURE_ROOT).map(p => p.name)).toEqual([
      '@astryxdesign/demo',
    ]);
  });
});

describe('API changes', () => {
  const resize = text =>
    text.replace(
      "  prop size?: ChipSize = 'md'",
      "  prop size?: ChipSize = 'sm'",
    );

  it('keys rows by entry point, section, item, and member', () => {
    expect(
      parseReport(report).get('.\0Components\0component Chip\0size')?.line,
    ).toBe("prop size?: ChipSize = 'md'");
  });

  it('reports added, changed, and removed rows, folding a wholly removed item', () => {
    const head = resize(report)
      .replace(/^function formatChip\n(?: {2}overload .*\n)+/m, '')
      .replace(
        '### Types\n\n```text\n',
        "### Types\n\n```text\ntype ChipTone = 'neutral' | 'accent'\n",
      );
    const {added, changed, removed} = diffReports(report, head);
    expect(added.map(r => r.line)).toEqual([
      "type ChipTone = 'neutral' | 'accent'",
    ]);
    expect(changed.map(r => [r.before, r.line])).toEqual([
      ["prop size?: ChipSize = 'md'", "prop size?: ChipSize = 'sm'"],
    ]);
    expect(removed.map(r => r.item)).toEqual(['function formatChip']);
  });

  it('tells apart one custom property declared in two stylesheets', () => {
    expect(report).toContain('var --demo-accent (./theme.css)');
    const head = report.replace('var --demo-accent (./demo.css)\n', '');
    const {added, changed, removed} = diffReports(report, head);
    expect([added, changed]).toEqual([[], []]);
    expect(removed.map(r => r.line)).toEqual([
      'var --demo-accent (./demo.css)',
    ]);
  });

  it('renders one summary line, keeps the rows in a closed disclosure, and flags a stale report in one line', () => {
    const md = renderChanges(
      computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: report,
          head: resize(report),
          committed: report,
          baseSource: 'build',
        },
      ]),
    );
    expect(md.split('\n').slice(0, 3)).toEqual([
      '**API changes:** `demo` +0 · ~1 · −0',
      '',
      'Committed API report behind this build: `demo` 1 row; run `pnpm api:report`.',
    ]);
    expect(md).toContain('<details><summary>1 API change (advisory)</summary>');
    expect(md).toContain('`<Chip size="sm" />`');
  });

  // Main changed the API without regenerating its report; this pull request
  // adds one type. Only the type is this pull request's.
  const addTone = text =>
    text.replace(
      '### Types\n\n```text\n',
      "### Types\n\n```text\ntype ChipTone = 'neutral' | 'accent'\n",
    );

  it("lists only the pull request's rows when the committed report is behind main", () => {
    const [change] = computeChanges([
      {
        pkg: '@astryxdesign/demo',
        base: resize(report),
        head: addTone(resize(report)),
        committed: report,
        baseSource: 'build',
      },
    ]);
    expect(change.rows.map(r => r.line)).toEqual([
      "type ChipTone = 'neutral' | 'accent'",
    ]);
    expect(change).toMatchObject({stale: true, staleRows: 2});
    const md = renderChanges([change]);
    expect(md).toContain('**API changes:** `demo` +1 · ~0 · −0\n');
    expect(md).toContain(
      'Committed API report behind this build: `demo` 2 rows; run `pnpm api:report`.',
    );
    expect(md).toContain('<details><summary>1 API change (advisory)</summary>');
    expect(md).not.toContain("prop size?: ChipSize = 'sm'");
  });

  describe('a warning when this pull request leaves its own rows out of the report', () => {
    const file = () => 'packages/demo/api-report.md';
    const warn = input => staleReportWarnings(computeChanges([input]), file);

    it('warns when the pull request changes a row and does not regenerate the report', () => {
      const [change] = computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: report,
          head: resize(report),
          committed: report,
          baseSource: 'build',
        },
      ]);
      expect(change.staleOwnRows).toBe(1);
      expect(staleReportWarnings([change], file)).toEqual([
        '::warning file=packages/demo/api-report.md,title=API report not regenerated::' +
          "This pull request changes 1 row of @astryxdesign/demo's public API " +
          'that its committed api-report.md does not show. Run pnpm api:report and commit the report.',
      ]);
    });

    it('counts only its own rows when the report was already behind main', () => {
      const [change] = computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: resize(report),
          head: addTone(resize(report)),
          committed: report,
          baseSource: 'build',
        },
      ]);
      expect(change).toMatchObject({
        stale: true,
        staleRows: 2,
        staleOwnRows: 1,
      });
      expect(staleReportWarnings([change], file)[0]).toContain(
        'changes 1 row of',
      );
    });

    it('counts a wholly added component as one row, as the pull request report does', () => {
      const withChip2 = text =>
        text.replace(
          '### Components\n\n```text\n',
          '### Components\n\n```text\ncomponent Chip2\n  prop a?: string\n  prop b?: string\n  prop c?: string\n  prop d?: string\n  prop e?: string\n',
        );
      const head = withChip2(report);
      expect(head).not.toBe(report);
      const [change] = computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: report,
          head,
          committed: report,
          baseSource: 'build',
        },
      ]);
      expect(change.counts.added).toBe(1);
      expect(change).toMatchObject({staleRows: 1, staleOwnRows: 1});
      expect(staleReportWarnings([change], file)[0]).toContain(
        'changes 1 row of',
      );
    });

    // Small hand-written reports: one component with two props.
    const tiny = ({
      item = 'component Chip',
      size = "'md'",
      tone = "'neutral'",
      chip = true,
    } = {}) =>
      '## `.`\n\n### Components\n\n```text\n' +
      (chip
        ? `${item}\n  prop size?: ChipSize = ${size}\n  prop tone?: ChipTone = ${tone}\n`
        : '') +
      '```\n';

    it('warns for a prop change to a component the committed report lacks entirely', () => {
      const [change] = computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: tiny(),
          head: tiny({size: "'sm'"}),
          committed: tiny({chip: false}),
          baseSource: 'build',
        },
      ]);
      expect(change.rows.map(r => r.member)).toEqual(['size']);
      expect(change.staleOwnRows).toBe(1);
    });

    it('does not count a changed item line the report already shows, when another member is behind', () => {
      const head = tiny({item: 'component Chip<T>'});
      const [change] = computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: tiny(),
          head,
          committed: tiny({item: 'component Chip<T>', tone: "'accent'"}),
          baseSource: 'build',
        },
      ]);
      expect(change.rows.map(r => [r.item, r.member])).toEqual([
        ['component Chip', null],
      ]);
      expect(change).toMatchObject({
        stale: true,
        staleRows: 1,
        staleOwnRows: 0,
      });
    });

    it('does not warn for a report that was stale before the pull request', () => {
      expect(
        warn({
          pkg: '@astryxdesign/demo',
          base: resize(report),
          head: resize(report),
          committed: report,
          baseSource: 'build',
        }),
      ).toEqual([]);
    });

    it('does not warn when the pull request regenerated its report', () => {
      expect(
        warn({
          pkg: '@astryxdesign/demo',
          base: report,
          head: resize(report),
          committed: resize(report),
          baseSource: 'build',
        }),
      ).toEqual([]);
    });

    it("does not warn against the merge base's committed report, which cannot tell the rows apart", () => {
      expect(
        warn({
          pkg: '@astryxdesign/demo',
          base: report,
          head: resize(report),
          committed: report,
          baseSource: 'committed',
        }),
      ).toEqual([]);
    });

    it('does not warn for a new package with no report at the merge base', () => {
      expect(
        warn({
          pkg: '@astryxdesign/demo',
          base: null,
          head: report,
          committed: null,
          baseSource: 'build',
        }),
      ).toEqual([]);
    });
  });

  it('renders a stale report with no API change as one line', () => {
    const md = renderChanges(
      computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: resize(report),
          head: resize(report),
          committed: report,
          baseSource: 'build',
        },
        {
          pkg: '@astryxdesign/other',
          base: report,
          head: report,
          committed: report,
          baseSource: 'build',
        },
      ]),
    );
    expect(md).toBe(
      '**API changes:** none in this pull request\n\nCommitted API report behind this build: `demo` 1 row; run `pnpm api:report`.\n',
    );
  });

  it("says when rows were compared with the merge base's committed report", () => {
    const md = renderChanges(
      computeChanges([
        {
          pkg: '@astryxdesign/demo',
          base: report,
          head: resize(report),
          committed: resize(report),
          baseSource: 'committed',
        },
      ]),
    );
    expect(md.split('\n')[0]).toBe(
      "**API changes:** `demo` +0 · ~1 · −0 (against the merge base's committed report)",
    );
    expect(md).not.toContain('Committed API report behind');
  });

  it('renders version 1 changes as before', () => {
    const md = renderChanges([
      {
        pkg: '@astryxdesign/demo',
        baseline: false,
        stale: true,
        missing: false,
        counts: {added: 0, changed: 0, removed: 0},
        rows: [],
      },
    ]);
    expect(md).toBe(
      '**API changes:** `demo` no changes (report stale: run `pnpm api:report`)\n',
    );
  });

  it('summarizes a package with no report at the merge base as a new report', () => {
    const [change] = computeChanges([
      {pkg: '@astryxdesign/demo', base: null, head: report, committed: report},
    ]);
    expect(change).toMatchObject({
      baseline: true,
      rows: [],
      counts: {added: 0, changed: 0, removed: 0},
    });
    expect(renderChanges([change])).toBe(
      '**API changes:** `demo` new report\n',
    );
  });

  it.each([
    [
      'its built surface',
      {surface: 'S', haveSurface: true, unchanged: false},
      {base: 'S', baseSource: 'build'},
    ],
    [
      'this build for a package the built merge base lacks and this pull request leaves unchanged',
      {surface: null, haveSurface: true, unchanged: true},
      {base: 'H', baseSource: 'head'},
    ],
    [
      'the committed report for a changed package the built merge base lacks',
      {surface: null, haveSurface: true, unchanged: false},
      {base: 'C', baseSource: 'committed'},
    ],
    [
      'the committed report when no build of the merge base was kept',
      {surface: null, haveSurface: false, unchanged: true},
      {base: 'C', baseSource: 'committed'},
    ],
  ])("takes the merge base's report from %s", (_label, input, expected) => {
    expect(chooseBase({...input, head: 'H', committedAtBase: 'C'})).toEqual(
      expected,
    );
  });

  it('gives package-level rows a usage example of their own kind', () => {
    const rows = [...parseReport(report).values()];
    const usage = item =>
      usageFor(
        '@astryxdesign/demo',
        rows.find(r => r.item === item),
      );
    expect(usage('var --demo-accent (./demo.css)')).toBe(
      '.my-scope { --demo-accent: …; }',
    );
    expect(usage('target chip (Chip)')).toBe(
      "defineTheme({components: {'chip': {…}}})",
    );
    expect(usage('attr data-astryx-theme')).toBe('[data-astryx-theme] { … }');
    expect(usage('internal resetChips')).toBe(
      "import {resetChips} from '@astryxdesign/demo'",
    );
    expect(usage('function chipOnly')).toBe(
      "import {chipOnly} from '@astryxdesign/demo/chip'; chipOnly(…)",
    );
  });

  it("gives a component's overload line the component's usage example", () => {
    const overloads = [...parseReport(report).values()].filter(
      r => r.item === 'component Badge' && r.member?.startsWith('overload '),
    );
    expect(overloads).toHaveLength(2);
    for (const row of overloads)
      expect(usageFor('@astryxdesign/demo', row)).toBe('<Badge … />');
  });

  it('renders nothing when the API is unchanged and the committed report is current', () => {
    const changes = computeChanges([
      {
        pkg: '@astryxdesign/demo',
        base: report,
        head: report,
        committed: report,
      },
    ]);
    expect(renderChanges(changes)).toBe('');
  });
});

describe('--surface', () => {
  const surface = (repoRoot, out) => {
    execFileSync(
      process.execPath,
      [
        path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs'),
        '--surface',
        out,
        '--root',
        repoRoot,
      ],
      {encoding: 'utf8'},
    );
    return JSON.parse(fs.readFileSync(path.join(out, 'surface.json'), 'utf8'));
  };

  it('writes each built package report under the directory and lists it', () => {
    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'api-surface-'));
    try {
      // The fixture carries only what the report reads; complete its build.
      const repo = path.join(tmp, 'repo');
      fs.cpSync(FIXTURE_ROOT, repo, {recursive: true});
      for (const f of [
        'lib/index.js',
        'lib/chip.js',
        'lib/internal/secret.js',
        'src/demo.css.d.ts',
      ])
        fs.writeFileSync(path.join(repo, 'packages/demo', f), '');
      const out = path.join(tmp, 'surface');
      expect(surface(repo, out)).toMatchObject({
        packages: [{name: '@astryxdesign/demo', dir: 'packages/demo'}],
        skipped: [],
      });
      expect(
        fs.readFileSync(path.join(out, 'packages/demo/api-report.md'), 'utf8'),
      ).toBe(report);
      // The checkout's committed reports are left alone.
      expect(
        fs.existsSync(path.join(repo, 'packages/demo/api-report.md')),
      ).toBe(false);
    } finally {
      fs.rmSync(tmp, {recursive: true, force: true});
    }
  }, 120_000);

  it('lists a package whose build is incomplete as skipped, with no report', () => {
    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'api-surface-'));
    try {
      const {packages, skipped} = surface(FIXTURE_ROOT, out);
      expect(packages).toEqual([]);
      expect(skipped).toMatchObject([
        {
          name: '@astryxdesign/demo',
          missing: expect.arrayContaining(['packages/demo/lib/index.js']),
        },
      ]);
      expect(fs.existsSync(path.join(out, 'packages/demo'))).toBe(false);
    } finally {
      fs.rmSync(out, {recursive: true, force: true});
    }
  }, 120_000);
});