Skip to content

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

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

/**
 * @file The provider ledger property: over seeded, generated projects, the
 * real Project.load and the real `upgrade` context account for every candidate
 * exactly once, and agree on the winner of every provider ID except where the
 * codemod policy says otherwise.
 *
 * The expected candidates come from the scenario description, never from the
 * resolver. Fixtures live under the system temp folder, so TMPDIR chooses the
 * filesystem that takes each seed's writes and removals.
 */

import {afterAll, beforeAll, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {
  expectedProjectInputs,
  generateScenario,
  isRunnable,
  writeScenario,
} from '../../test-utils/provider-scenarios.mjs';
import {requireNatively} from '../../test-utils/native-require.mjs';

// The code under test loads natively, so each seed's fixture modules load as
// Node loads them, not as one Vitest request each.
const require = requireNatively(import.meta.url);
/** @type {typeof import('../config/project.mjs')} */
const {Project, providerLedgerOf} = require('../config/project.mjs');
/** @type {typeof import('../../api/upgrade/_adapter.mjs')} */
const {loadProjectContext} = require('../../api/upgrade/_adapter.mjs');

// 200 seeds keep this near 4 s; any seed range must hold.
const SEEDS = Array.from({length: 200}, (_, index) => index + 1);
const OUTCOMES = ['contributes', 'set-aside', 'load-failed', 'alias-of'];

/** @type {string} */
let root;
/** @type {string} */
let originalCwd;

beforeAll(() => {
  originalCwd = process.cwd();
  root = fs.mkdtempSync(path.join(os.tmpdir(), '.astryx-provider-ledger-'));
});

// Only a seed that failed before removing its folder leaves one here.
afterAll(() => {
  process.chdir(originalCwd);
  fs.rmSync(root, {recursive: true, force: true});
});

/**
 * The contributing package for each provider ID. Fails when two contribute
 * under one ID.
 * @param {Map<string, any>} ledger
 * @returns {Map<string, any>}
 */
function winners(ledger) {
  /** @type {Map<string, any>} */
  const byProvider = new Map();
  for (const entry of ledger.values()) {
    if (entry.outcome !== 'contributes' || entry.providerId == null) continue;
    expect(byProvider.has(entry.providerId)).toBe(false);
    byProvider.set(entry.providerId, entry);
  }
  return byProvider;
}

/**
 * Assert the ledger records one outcome for exactly the given inputs.
 * @param {Map<string, any>} ledger
 * @param {Array<{source: string, spec: string, key: string}>} inputs
 */
function expectAccounted(ledger, inputs) {
  const refs = [...ledger.values()].flatMap(entry =>
    entry.refs.map(ref => ({entry, ref})),
  );
  for (const input of inputs) {
    const holders = refs.filter(
      ({ref}) => ref.source === input.source && ref.spec === input.spec,
    );
    expect(holders.map(({entry}) => entry.key)).toEqual([input.key]);
  }
  expect(refs).toHaveLength(inputs.length);
  expect(new Set(ledger.keys())).toEqual(
    new Set(inputs.map(input => input.key)),
  );
  for (const [key, entry] of ledger) {
    expect(entry.key).toBe(key);
    expect(OUTCOMES).toContain(entry.outcome);
    if (entry.outcome === 'set-aside') {
      expect(ledger.has(entry.winner)).toBe(true);
      expect(entry.reason).toEqual(expect.any(String));
    }
    if (entry.outcome === 'alias-of') {
      expect(ledger.has(entry.aliasOf)).toBe(true);
    }
  }
}

describe('provider ledger over generated projects', () => {
  it('accounts for every candidate once and agrees across Project and upgrade', async () => {
    const coverage = {
      scenarios: 0,
      setAside: 0,
      aliasOf: 0,
      loadFailed: 0,
      replaced: 0,
      agreed: 0,
      standIn: 0,
      extraReordered: 0,
    };

    for (const seed of SEEDS) {
      const scenario = generateScenario(seed);
      if (!isRunnable(scenario)) continue;
      coverage.scenarios++;
      const dir = path.join(root, `seed-${seed}`);
      fs.mkdirSync(dir);
      writeScenario(dir, scenario);
      const context = `seed ${seed}: ${JSON.stringify(scenario)}`;

      const project = await Project.load(dir, {fresh: true});
      const ledger = providerLedgerOf(project);
      const inputs = expectedProjectInputs(dir, scenario);
      try {
        expectAccounted(ledger, inputs);

        // Nothing leaves the list without a recorded reason.
        const listed = new Set(project.loadedIntegrations);
        for (const integration of project.loadedIntegrations) {
          expect(ledger.has(fs.realpathSync(integration.__packageDir))).toBe(
            true,
          );
        }
        for (const entry of ledger.values()) {
          if (entry.integration != null) {
            expect(listed.has(entry.integration)).toBe(true);
            continue;
          }
          expect(entry.outcome).not.toBe('contributes');
          if (entry.outcome === 'set-aside') {
            expect(entry.reason).toBe('replaced-by-authored');
          }
          if (entry.outcome === 'load-failed') {
            expect(entry.error).toEqual(expect.any(String));
          }
        }
      } catch (error) {
        throw new Error(`${context}\n${error}`, {cause: error});
      }

      for (const entry of ledger.values()) {
        if (entry.outcome === 'set-aside') coverage.setAside++;
        if (entry.outcome === 'alias-of') coverage.aliasOf++;
        if (entry.outcome === 'load-failed') coverage.loadFailed++;
        if (entry.reason === 'replaced-by-authored') coverage.replaced++;
      }

      // `--integration` specs resolve from the process cwd.
      process.chdir(dir);
      const upgrade = await loadProjectContext(dir, scenario.extras);
      process.chdir(originalCwd);

      const modules = path.join(dir, 'node_modules');
      /** @param {string} spec */
      const installedKey = spec =>
        fs.realpathSync(path.join(modules, ...spec.split('/')));
      /** @param {string} spec */
      const installedName = spec =>
        JSON.parse(
          fs.readFileSync(
            path.join(modules, ...spec.split('/'), 'package.json'),
            'utf8',
          ),
        ).name;
      const configured = new Set(scenario.config ?? []);
      const extras = [...new Set(scenario.extras)].filter(
        spec => !configured.has(spec),
      );
      const {local} = scenario;
      const localKey = fs.realpathSync(dir);
      const selfListed = local != null && configured.has(local.name);
      // The codemod policy: the installed copy stands in for the package being
      // authored when it lists itself or is named with --integration.
      const localStandsIn =
        local != null &&
        (selfListed || extras.some(spec => installedName(spec) === local.name));

      try {
        // Upgrade accounts for everything Project did, plus its own inputs.
        expectAccounted(upgrade.ledger, [
          ...inputs,
          ...(selfListed
            ? [
                {
                  source: 'installed',
                  spec: local.name,
                  key: installedKey(local.name),
                },
              ]
            : []),
          ...extras.map(spec => ({
            source: 'extra',
            spec,
            key: installedKey(spec),
          })),
        ]);
      } catch (error) {
        throw new Error(`${context}\n${error}`, {cause: error});
      }

      const projectWinners = winners(ledger);
      const upgradeWinners = winners(upgrade.ledger);
      for (const providerId of new Set([
        ...projectWinners.keys(),
        ...upgradeWinners.keys(),
      ])) {
        const inProject = projectWinners.get(providerId);
        const inUpgrade = upgradeWinners.get(providerId);
        const same =
          inProject != null &&
          inUpgrade != null &&
          (inProject.key === inUpgrade.key ||
            upgrade.ledger.get(inProject.key)?.aliasOf === inUpgrade.key);
        if (same) {
          coverage.agreed++;
          continue;
        }
        // The one documented exception, asserted explicitly: an installed
        // copy took the authored package's place, so either upgrade's winner
        // is an installed copy of that package, or Project's winner is the
        // authored package it replaced.
        const upgradeName =
          inUpgrade?.integration?.name ??
          inUpgrade?.candidate.integration?.name;
        const standInWins =
          localStandsIn && inUpgrade != null && upgradeName === local?.name;
        const localReplaced =
          localStandsIn && inProject != null && inProject.key === localKey;
        // Project never saw an extra, so an ID only an extra claims has no
        // Project winner to agree with.
        const extraOnly =
          inProject == null && inUpgrade?.candidate.source === 'extra';
        // Known disagreement, pinned by the `it.fails` repros in
        // api/upgrade/provider-agreement.test.mjs: upgrade replaces an
        // autolinked winner with any extra of the same name@version, from
        // any directory, and orders it with the extras. Another extra can
        // then win, or nothing does, in upgrade only.
        const projectWinnerInUpgrade =
          inProject == null ? undefined : upgrade.ledger.get(inProject.key);
        const repeatedByExtra =
          projectWinnerInUpgrade != null &&
          (projectWinnerInUpgrade.refs.some(ref => ref.source === 'extra') ||
            (projectWinnerInUpgrade.outcome === 'alias-of' &&
              upgrade.ledger
                .get(projectWinnerInUpgrade.aliasOf)
                ?.refs.some(ref => ref.source === 'extra')));
        const extraReordered =
          inProject?.candidate.source === 'autolinked' && repeatedByExtra;
        if (extraReordered) {
          coverage.extraReordered++;
          continue;
        }
        expect(
          standInWins || localReplaced || extraOnly,
          `${context}\nprovider ${providerId}: Project ${inProject?.label ?? 'none'} vs upgrade ${inUpgrade?.label ?? 'none'}`,
        ).toBe(true);
        if (standInWins || localReplaced) coverage.standIn++;
      }
      // The seed's folder is read, so it goes now: inside this case's budget,
      // not with every other seed's folder at once after the file.
      fs.rmSync(dir, {recursive: true, force: true});
    }

    // The generator must keep reaching every shape, or the property is vacuous.
    expect(coverage.scenarios).toBeGreaterThanOrEqual(190);
    expect(coverage.setAside).toBeGreaterThan(0);
    expect(coverage.aliasOf).toBeGreaterThan(0);
    expect(coverage.loadFailed).toBeGreaterThan(0);
    expect(coverage.replaced).toBeGreaterThan(0);
    expect(coverage.agreed).toBeGreaterThan(0);
    expect(coverage.standIn).toBeGreaterThan(0);
  }, 120_000);
});