@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/integrations/provider-ledger.test.mjs

@@ -0,0 +1,275 @@
+// 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 a repo-local temp dir, not /tmp, because Vite
+ * refuses to dynamically import a module from outside the project root.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {Project, providerLedgerOf} from '../config/project.mjs';
+import {loadProjectContext} from '../../api/upgrade/_adapter.mjs';
+import {
+  expectedProjectInputs,
+  generateScenario,
+  isRunnable,
+  writeScenario,
+} from '../../test-utils/provider-scenarios.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(process.cwd(), '.astryx-provider-ledger-'));
+});
+
+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 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);
+});

package/foundation/integrations/provider-resolution.d.mts

@@ -0,0 +1,152 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The identity of a package directory: its real path, so every symlinked
+ * spelling of one pnpm store entry is one package.
+ * @param {string} packageDir
+ * @returns {string}
+ */
+export function packageKey(packageDir: string): string;
+/**
+ * Resolve provider identity over candidates in precedence order.
+ *
+ * Returns the resolved integration list every command reads, and a ledger
+ * with one outcome for every real package directory among the candidates:
+ * `contributes`, `set-aside` (with the winner and a reason), `load-failed`, or
+ * `alias-of` (the same published package already loaded from another
+ * directory, or another input for a directory already reached).
+ *
+ * @param {ProviderCandidate[]} candidates in precedence order
+ * @param {ProviderPolicy} [policy]
+ * @returns {{integrations: LoadedIntegration[], ledger: ProviderLedger}}
+ */
+export function resolveProviders(candidates: ProviderCandidate[], policy?: ProviderPolicy): {
+    integrations: LoadedIntegration[];
+    ledger: ProviderLedger;
+};
+export type LoadedIntegration = import("./integrations.mjs").LoadedIntegration;
+/**
+ * Where a candidate came from. Precedence follows candidate order; the source
+ * selects which rules apply.
+ *   - `configured`: named by astryx.config; listed even when its manifest fails
+ *   - `autolinked`: a declared dependency that ships one root manifest
+ *   - `local`: the package being authored, loaded from its working bytes
+ *   - `installed`: codemod policy — the installed copy of a package being
+ *     authored that lists itself
+ *   - `extra`: codemod policy — a package named with `upgrade --integration`
+ */
+export type CandidateSource = "configured" | "autolinked" | "local" | "installed" | "extra";
+/**
+ * One package reached by one input. A candidate without `integration` failed
+ * to load (`error`) or reached a directory an earlier candidate already
+ * reached (`repeat`).
+ */
+export type ProviderCandidate = {
+    source: CandidateSource;
+    integration?: import("./integrations.mjs").LoadedIntegration | undefined;
+    /**
+     * the input that reached the package
+     */
+    spec?: string | undefined;
+    /**
+     * required when `integration` is absent
+     */
+    packageDir?: string | undefined;
+    /**
+     * why loading threw
+     */
+    error?: string | undefined;
+    /**
+     * another input for a directory already reached
+     */
+    repeat?: boolean | undefined;
+};
+export type ProviderOutcome = "contributes" | "set-aside" | "load-failed" | "alias-of";
+/**
+ * Why a package is set aside.
+ *   - `claimed-earlier`: a package earlier in precedence claims its provider ID
+ *   - `authored-claims`: the package being authored claims its provider ID
+ *   - `replaced-by-authored`: it is the installed copy of the package being
+ *     authored, whose working bytes are used instead
+ *   - `installed-stands-in`: codemod policy — the package being authored is
+ *     represented by its installed copy
+ */
+export type SetAsideReason = "claimed-earlier" | "authored-claims" | "replaced-by-authored" | "installed-stands-in";
+/**
+ * The one outcome for one real package directory.
+ */
+export type ProviderLedgerEntry = {
+    /**
+     * real package directory
+     */
+    key: string;
+    /**
+     * `name@version`, for display only
+     */
+    label: string;
+    outcome: ProviderOutcome;
+    /**
+     * the candidate this outcome belongs to
+     */
+    candidate: ProviderCandidate;
+    /**
+     * every candidate that reached this
+     * directory, in order
+     */
+    refs: ProviderCandidate[];
+    providerId?: string | undefined;
+    /**
+     * set-aside: key of the package used instead
+     */
+    winner?: string | undefined;
+    /**
+     * set-aside: why
+     */
+    reason?: SetAsideReason | undefined;
+    /**
+     * alias-of: key of the package this one repeats
+     */
+    aliasOf?: string | undefined;
+    /**
+     * the record this package left in
+     * the resolved list, when it left one
+     */
+    integration?: import("./integrations.mjs").LoadedIntegration | undefined;
+    /**
+     * load-failed: the load error
+     */
+    error?: string | undefined;
+};
+export type ProviderLedger = Map<string, ProviderLedgerEntry>;
+export type ProviderPolicy = {
+    /**
+     * upgrade's codemod rule. Candidates are an
+     * already resolved Project list plus `installed` and `extra` candidates. The
+     * installed copy stands in for a package being authored that lists itself or
+     * is named as an extra, and an extra stands in for the autolinked package it
+     * repeats. Autolinked and local packages still claim provider IDs, but they
+     * are not listed: upgrade has never run their codemods.
+     */
+    codemods?: boolean | undefined;
+    /**
+     * the ledger this resolution builds on. A
+     * record it already set aside keeps that winner, and its entries this
+     * resolution never reaches are carried over unchanged.
+     */
+    prior?: ProviderLedger | undefined;
+};
+export type CandidateState = {
+    candidate: ProviderCandidate;
+    record: LoadedIntegration | undefined;
+    key: string;
+    outcome?: ProviderOutcome | undefined;
+    winner?: CandidateState | undefined;
+    reason?: SetAsideReason | undefined;
+    aliasOf?: CandidateState | undefined;
+    listed?: import("./integrations.mjs").LoadedIntegration | undefined;
+};
+export type Slot = {
+    state: CandidateState;
+    record: LoadedIntegration;
+};