Skip to content

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

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

/**
 * @file Colocated tests for the upgrade.run leaf — the --path scan dir must be
 * confined to cwd (upgrade rewrites source in place with --apply, so an escaping
 * or out-of-tree path must be rejected), the receipt must say whether that
 * dir existed at all, a run from any folder in a project upgrades that
 * project (the nearest folder whose package.json declares Astryx, never the
 * home folder) and names files relative to the folder it ran in, and the
 * target Core is the project's own.
 */

import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {upgrade} from '../upgrade.mjs';
import {relativeToOrigin} from '../_adapter.mjs';
import {logger} from '../../logger.mjs';
import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';

const SLOW = 30_000;

/**
 * Run `fn` with `home` as the home folder.
 * @template T
 * @param {string} home @param {() => Promise<T>} fn
 * @returns {Promise<T>}
 */
async function withHome(home, fn) {
  const previous = process.env.HOME;
  process.env.HOME = home;
  try {
    return await fn();
  } finally {
    if (previous === undefined) delete process.env.HOME;
    else process.env.HOME = previous;
  }
}

function seedProject(dir) {
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    JSON.stringify({name: 'x', version: '1.0.0', dependencies: {'@astryxdesign/core': '0.1.8'}}),
  );
  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
  fs.mkdirSync(core, {recursive: true});
  fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.1.8'}));
  fs.mkdirSync(path.join(dir, 'src'), {recursive: true});
  fs.writeFileSync(path.join(dir, 'src', 'index.ts'), 'const x = 1;\n');
}

describe('upgrade.run — --path confinement', () => {
  let dir;
  beforeEach(() => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-path-'));
    seedProject(dir);
  });
  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));

  it('accepts a normal in-tree --path (dry run)', async () => {
    const res = await upgrade({from: '0.0.1', path: 'src'}, {cwd: dir});
    expect(res.type).toBe('upgrade.run');
  }, SLOW);

  it('rejects a ../-escaping --path with ERR_PATH_TRAVERSAL', async () => {
    await expect(
      upgrade({from: '0.0.1', path: '../../../../etc'}, {cwd: dir}),
    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
  }, SLOW);

  it('rejects an absolute --path outside cwd with ERR_PATH_TRAVERSAL', async () => {
    await expect(
      upgrade({from: '0.0.1', path: os.tmpdir()}, {cwd: dir}),
    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
  }, SLOW);
});

describe('upgrade.run — sourcePathFound', () => {
  let dir;
  beforeEach(() => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-srcpath-'));
    seedProject(dir);
  });
  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));

  // The receipt for a project whose source lives somewhere other than ./src was
  // byte-identical to a fully migrated one: exit 0, filesChanged 0, errors [].
  // The only signal was a human log line --json suppresses by design.
  it('reports false when the resolved source directory is missing, and still counts nothing', async () => {
    fs.rmSync(path.join(dir, 'src'), {recursive: true, force: true});
    fs.mkdirSync(path.join(dir, 'app'), {recursive: true});
    fs.writeFileSync(path.join(dir, 'app', 'index.ts'), 'const x = 1;\n');

    const res = await upgrade({from: '0.0.1', apply: true}, {cwd: dir});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.sourcePathFound).toBe(false);
    expect(res.data.filesChanged).toBe(0);
    expect(res.data.errors).toEqual([]);
  }, SLOW);

  it('reports true for a source directory that exists', async () => {
    const res = await upgrade({from: '0.0.1', apply: true}, {cwd: dir});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.sourcePathFound).toBe(true);
  }, SLOW);

  it('follows --path, so the right directory under another name reports true', async () => {
    fs.rmSync(path.join(dir, 'src'), {recursive: true, force: true});
    fs.mkdirSync(path.join(dir, 'app'), {recursive: true});
    fs.writeFileSync(path.join(dir, 'app', 'index.ts'), 'const x = 1;\n');

    const res = await upgrade({from: '0.0.1', path: 'app'}, {cwd: dir});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.sourcePathFound).toBe(true);
  }, SLOW);
});

/** Core 0.7.0 renamed this prop; its codemod renames it on Typeahead. */
const OLD_PROP_SOURCE =
  "import {Typeahead} from '@astryxdesign/core';\n" +
  'export const App = () => <Typeahead label="Fruit" emptySearchResultsText="None" />;\n';

/**
 * A project with Core 0.7.0 installed and src/App.tsx using a prop that 0.7.0
 * renamed.
 * @param {string} dir
 */
function seedOldPropProject(dir) {
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
  );
  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
  fs.mkdirSync(core, {recursive: true});
  fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}));
  fs.mkdirSync(path.join(dir, 'src', 'l1', 'l2'), {recursive: true});
  fs.writeFileSync(path.join(dir, 'src', 'App.tsx'), OLD_PROP_SOURCE);
}

describe('upgrade.run — a run from a subfolder upgrades the project', () => {
  let dir;
  beforeEach(() => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-scope-'));
    seedOldPropProject(dir);
  });
  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));

  const appSource = () => fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8');

  it.each([['src', 'App.tsx'], ['src/l1/l2', '../../App.tsx']])(
    'scans the project src by default when run from %s',
    async (folder, reported) => {
      const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(dir, folder)});

      expect(res.type).toBe('upgrade.run');
      expect(res.data.sourcePathFound).toBe(true);
      expect(res.data.filesChanged).toBe(1);
      expect(res.data.modifiedFiles).toEqual([reported]);
      expect(appSource()).toContain('emptySearchText="None"');
    },
    SLOW,
  );

  it('reads a path you name relative to the folder you ran in', async () => {
    const res = await upgrade({from: '0.6.8', path: '../..', apply: true}, {cwd: path.join(dir, 'src', 'l1', 'l2')});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.filesChanged).toBe(1);
    expect(appSource()).toContain('emptySearchText="None"');
  }, SLOW);

  it('still rejects a path outside the project', async () => {
    await expect(
      upgrade({from: '0.6.8', path: '../../..'}, {cwd: path.join(dir, 'src', 'l1')}),
    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
    expect(appSource()).toBe(OLD_PROP_SOURCE);
  }, SLOW);

  it("refreshes the agent docs at the project root, not the folder it ran in", async () => {
    fs.writeFileSync(
      path.join(dir, 'AGENTS.md'),
      `# Agents\n\n${generateCompressedIndex('0.6.8')}\n`,
    );

    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(dir, 'src', 'l1')});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.agentDocs.action).toBe('refreshed');
    expect(res.data.agentDocs.files).toEqual(['../../AGENTS.md']);
    expect(fs.existsSync(path.join(dir, 'src', 'l1', 'AGENTS.md'))).toBe(false);
  }, SLOW);
});

describe('upgrade.run — the result names files relative to the folder it ran in', () => {
  let dir;
  beforeEach(() => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-receipt-'));
    seedOldPropProject(dir);
    fs.writeFileSync(path.join(dir, 'src', 'Generated.tsx'), `// @generated\n${OLD_PROP_SOURCE}`);
    fs.writeFileSync(path.join(dir, 'src', 'Vendored.tsx'), OLD_PROP_SOURCE);
    fs.writeFileSync(path.join(dir, '.gitattributes'), 'src/Vendored.tsx linguist-generated\n');
    fs.writeFileSync(path.join(dir, 'AGENTS.md'), `# Agents\n\n${generateCompressedIndex('0.6.8')}\n`);
    fs.mkdirSync(path.join(dir, 'frontend'), {recursive: true});
  });
  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));

  it.each([
    ['frontend', '../'],
    ['.', ''],
  ])('from %s, every file path resolves from that folder', async (folder, up) => {
    const cwd = path.join(dir, folder);

    const res = await upgrade({from: '0.6.8'}, {cwd});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.modifiedFiles).toEqual([`${up}src/App.tsx`]);
    expect(res.data.protectedFiles.map(item => item.file)).toEqual([
      `${up}src/Generated.tsx`,
      `${up}src/Vendored.tsx`,
    ]);
    for (const file of [...res.data.modifiedFiles, ...res.data.protectedFiles.map(item => item.file)]) {
      expect(fs.existsSync(path.join(cwd, file))).toBe(true);
    }
    // The file a declaration names resolves from that folder too.
    const vendored = res.data.protectedFiles.find(item => item.file.endsWith('Vendored.tsx'));
    expect(vendored?.declarations).toEqual([`linguist-generated in ${up}.gitattributes:1`]);
    expect(fs.existsSync(path.join(cwd, `${up}.gitattributes`))).toBe(true);
  }, SLOW);

  it('leaves a result from a run at the project root as it is', () => {
    const result = {type: 'upgrade.run', data: {modifiedFiles: ['src/App.tsx']}};

    expect(relativeToOrigin(result, {cwd: dir})).toBe(result);
  });

  it('rewrites every project-relative path and passes the copied-composition summary through', () => {
    const registryCompositions = {items: [{item: 'example', path: 'components/Example.tsx', files: []}]};
    const result = relativeToOrigin(
      {
        type: 'upgrade.run',
        data: {
          agentDocs: {status: 'stale', files: ['AGENTS.md']},
          modifiedFiles: ['src/App.tsx'],
          protectedFiles: [
            {
              file: 'src/Generated.tsx',
              codemods: ['a'],
              declarations: [
                '@generated marker',
                'excluded by .gitignore',
                'excluded by src/.hgignore:3',
                'linguist-generated in .gitattributes:1',
                'symbolic link at src/linked',
                'installed dependency metadata node_modules/x',
              ],
            },
          ],
          declinedCandidates: [{file: 'src/Loose.tsx', reason: 'unproven'}],
          errors: [{file: '.', codemod: 'post-codemod-hook', error: 'failed'}],
          registryCompositions,
        },
      },
      {cwd: dir, origin: path.join(dir, 'apps', 'web')},
    );

    expect(result.data).toEqual({
      agentDocs: {status: 'stale', files: ['../../AGENTS.md']},
      modifiedFiles: ['../../src/App.tsx'],
      protectedFiles: [
        {
          file: '../../src/Generated.tsx',
          codemods: ['a'],
          declarations: [
            '@generated marker',
            'excluded by ../../.gitignore',
            'excluded by ../../src/.hgignore:3',
            'linguist-generated in ../../.gitattributes:1',
            'symbolic link at ../../src/linked',
            'installed dependency metadata node_modules/x',
          ],
        },
      ],
      declinedCandidates: [{file: '../../src/Loose.tsx', reason: 'unproven'}],
      errors: [{file: '../..', codemod: 'post-codemod-hook', error: 'failed'}],
      registryCompositions,
    });
  });
});

describe("upgrade.run — the target Core is the project's own", () => {
  let dir;
  beforeEach(() => {
    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-own-core-'));
    seedOldPropProject(dir);
  });
  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));

  /**
   * A project nested in `dir`, with src/App.tsx using the renamed prop.
   * @param {Record<string, string>} dependencies
   */
  function nestedProject(dependencies) {
    const nested = path.join(dir, 'apps', 'web');
    fs.mkdirSync(path.join(nested, 'src'), {recursive: true});
    fs.writeFileSync(path.join(nested, 'package.json'), JSON.stringify({name: 'web', dependencies}));
    fs.writeFileSync(path.join(nested, 'src', 'App.tsx'), OLD_PROP_SOURCE);
    return nested;
  }

  it.each([
    ['declares no Astryx package', {}],
    ['declares a Core it has not installed', {'@astryxdesign/core': '0.6.8'}],
  ])(
    'does not upgrade a project that %s to the Core of the home folder above it',
    async (_label, dependencies) => {
      const nested = nestedProject(dependencies);

      await withHome(dir, () =>
        expect(
          upgrade({from: '0.6.8', apply: true}, {cwd: nested}),
        ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'}),
      );
      expect(fs.readFileSync(path.join(nested, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
      expect(fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
    },
    SLOW,
  );

  it('names the folder it searched before stopping on a missing Core, from a subfolder (AST-040 FR12)', async () => {
    fs.rmSync(path.join(dir, 'node_modules'), {recursive: true, force: true});
    const sub = path.join(dir, 'src', 'l1');
    const log = vi.spyOn(logger, 'log');
    try {
      await expect(upgrade({from: '0.6.8'}, {cwd: sub})).rejects.toMatchObject({
        code: 'ERR_VERSION_DETECT',
      });
      const lines = log.mock.calls.map(([line]) => String(line));
      expect(lines).toContain('Project root: ../..');
      expect(lines.indexOf('Project root: ../..')).toBeLessThan(
        lines.indexOf('Aborted\n'),
      );
    } finally {
      log.mockRestore();
    }
  }, SLOW);

  it('does not upgrade a nested project that declares a Core it has not installed to the Core above it', async () => {
    const nested = nestedProject({'@astryxdesign/core': '0.6.8'});

    await expect(
      upgrade({from: '0.6.8', apply: true}, {cwd: nested}),
    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
    expect(fs.readFileSync(path.join(nested, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
  }, SLOW);

  it.each([
    ['an override at the workspace root forces', {overrides: {'@astryxdesign/core': '0.7.0'}}, {'@astryxdesign/core': '~0.6.8'}],
    ['a resolution at the workspace root forces', {resolutions: {'@astryxdesign/core': '0.7.0'}}, {'@astryxdesign/core': '0.6.8'}],
    ['only a stale peer range names', {}, null],
    ['the member declares another version of, not yet installed', {}, {'@astryxdesign/core': '0.9.0'}],
  ])(
    'upgrades a workspace member to a hoisted Core that %s',
    async (_label, rootFields, dependencies) => {
      fs.writeFileSync(
        path.join(dir, 'package.json'),
        JSON.stringify({name: 'root', private: true, workspaces: ['apps/*'], ...rootFields}),
      );
      const member = dependencies
        ? nestedProject(dependencies)
        : nestedProject({});
      if (!dependencies) {
        fs.writeFileSync(
          path.join(member, 'package.json'),
          JSON.stringify({name: 'web', peerDependencies: {'@astryxdesign/core': '^0.6.8'}}),
        );
      }

      const res = await upgrade({from: '0.6.8', apply: true}, {cwd: member});

      expect(res.type).toBe('upgrade.run');
      expect(res.data.to).toBe('0.7.0');
      expect(res.data.modifiedFiles).toEqual(['src/App.tsx']);
      expect(fs.readFileSync(path.join(member, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
    },
    SLOW,
  );

  it('does not upgrade a project its workspace does not list to the hoisted Core', async () => {
    fs.writeFileSync(
      path.join(dir, 'package.json'),
      JSON.stringify({name: 'root', private: true, workspaces: ['packages/*']}),
    );
    const project = nestedProject({'@astryxdesign/core': '0.9.0'});

    await expect(
      upgrade({from: '0.6.8', apply: true}, {cwd: project}),
    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
    expect(fs.readFileSync(path.join(project, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
  }, SLOW);

  it.each([[['apps/*']], [['{apps/*,tools/*}']]])('upgrades a member that declares no Astryx package, in its own src, when the workspace lists %j', async workspaces => {
    fs.writeFileSync(
      path.join(dir, 'package.json'),
      JSON.stringify({name: 'root', private: true, workspaces, dependencies: {'@astryxdesign/core': '0.7.0'}}),
    );
    const member = nestedProject({});

    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(member, 'src')});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.modifiedFiles).toEqual(['App.tsx']);
    expect(fs.readFileSync(path.join(member, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
    expect(fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
  }, SLOW);
});

describe('upgrade.run — the project is the nearest folder that declares Astryx', () => {
  let home;
  beforeEach(() => {
    home = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-home-'));
  });
  afterEach(() => fs.rmSync(home, {recursive: true, force: true}));

  // Astryx installed in a home folder whose src holds loose files and another
  // project, run from a folder with no package.json.
  it('does not upgrade the home folder from a folder inside it', async () => {
    seedOldPropProject(home);
    fs.mkdirSync(path.join(home, 'src', 'repoA', 'src'), {recursive: true});
    fs.writeFileSync(
      path.join(home, 'src', 'repoA', 'package.json'),
      JSON.stringify({name: 'repoA', dependencies: {'@astryxdesign/core': '0.6.8'}}),
    );
    fs.writeFileSync(path.join(home, 'src', 'repoA', 'src', 'a.tsx'), OLD_PROP_SOURCE);
    const desktop = path.join(home, 'Desktop');
    fs.mkdirSync(desktop, {recursive: true});

    await withHome(home, () =>
      expect(
        upgrade({from: '0.6.8', apply: true}, {cwd: desktop}),
      ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'}),
    );
    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
    expect(fs.readFileSync(path.join(home, 'src', 'repoA', 'src', 'a.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
  }, SLOW);

  // Installing Core does not make a folder a project.
  it('treats a folder that installs Core without declaring it as part of the project above it', async () => {
    seedOldPropProject(home);
    const tool = path.join(home, 'tools', 'codegen');
    const core = path.join(tool, 'node_modules', '@astryxdesign', 'core');
    fs.mkdirSync(core, {recursive: true});
    fs.writeFileSync(path.join(tool, 'package.json'), JSON.stringify({name: 'codegen'}));
    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.9.0'}));

    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: tool});

    expect(res.type).toBe('upgrade.run');
    expect(res.data.to).toBe('0.7.0');
    expect(res.data.modifiedFiles).toEqual(['../../src/App.tsx']);
  }, SLOW);

  it('names the project root and the folder it scans before a dry run in a folder that installs Core without declaring it', async () => {
    seedOldPropProject(home);
    const tool = path.join(home, 'tools', 'codegen');
    const core = path.join(tool, 'node_modules', '@astryxdesign', 'core');
    fs.mkdirSync(core, {recursive: true});
    fs.writeFileSync(path.join(tool, 'package.json'), JSON.stringify({name: 'codegen'}));
    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.9.0'}));
    const log = vi.spyOn(logger, 'log');
    try {
      const res = await upgrade({from: '0.6.8'}, {cwd: tool});

      expect(res.type).toBe('upgrade.run');
      const lines = log.mock.calls.map(([line]) => String(line));
      expect(lines).toContain('Project root: ../..');
      expect(lines).toContain(`Source folder: ${path.join('..', '..', 'src')}`);
      expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
    } finally {
      log.mockRestore();
    }
  }, SLOW);

  it('upgrades the home folder as a folder outside any project, when run there', async () => {
    seedOldPropProject(home);

    const res = await withHome(home, () => upgrade({from: '0.6.8', apply: true}, {cwd: home}));

    expect(res.type).toBe('upgrade.run');
    expect(res.data.modifiedFiles).toEqual(['src/App.tsx']);
    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
  }, SLOW);

  it('does not leave a repository for the project around it', async () => {
    seedOldPropProject(home);
    const repo = path.join(home, 'vendor', 'repo');
    fs.mkdirSync(path.join(repo, '.git'), {recursive: true});
    fs.mkdirSync(path.join(repo, 'src'), {recursive: true});
    fs.writeFileSync(path.join(repo, 'package.json'), JSON.stringify({name: 'repo'}));
    fs.writeFileSync(path.join(repo, 'src', 'App.tsx'), OLD_PROP_SOURCE);

    await expect(
      upgrade({from: '0.6.8', apply: true}, {cwd: repo}),
    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
    expect(fs.readFileSync(path.join(repo, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
  }, SLOW);
});