@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/api/upgrade/_adapter.d.mts

@@ -104,18 +104,27 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
     totalValidationBlocked: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;
@@ -139,13 +148,21 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
 /**
  * Load the consumer project's config + integrations. Throws on invalid config;
  * the run leaf decides between the config_fixable preview and a hard abort.
+ *
+ * Provider identity is resolved by the same resolver Project uses, on top of
+ * Project's ledger, under the codemod policy: a package that lists itself runs
+ * its installed copy's released codemods, never the work in progress being
+ * authored, and autolinked and local packages claim provider IDs without
+ * running codemods.
+ *
  * @param {string} cwd
  * @param {string[]} [extraIntegrationSpecs] explicit `--integration` specs
- * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]}>}
+ * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], ledger: import('../../foundation/integrations/provider-resolution.mjs').ProviderLedger}>}
  */
 export function loadProjectContext(cwd: string, extraIntegrationSpecs?: string[]): Promise<{
     postCodemodHooks: import("../../authoring/config/type").PostCodemodHook[];
     integrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[];
+    ledger: import("../../foundation/integrations/provider-resolution.mjs").ProviderLedger;
 }>;
 /**
  * Non-blocking nudge for integration validation issues. Never throws (a broken
@@ -171,20 +188,30 @@ export function selectIntegrationCodemodsFor(integrations: Array<import("../../f
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
 export function runIntegrationCodemodsStep(versionGroups: Array<{
     version: string;
     codemods: import("../../authoring/codemod/type").CodemodEntry[];
-}>, { apply, path: srcPath, codemod, skipCodemods }: {
+}>, { apply, path: srcPath, codemod, skipCodemods, root, protection, contents, silent, }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    contents?: Map<string, string>;
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;

package/api/upgrade/_adapter.mjs

@@ -19,7 +19,10 @@ import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import {ensureJscodeshift} from '../../assets/codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../../assets/codemods/registry.mjs';
+import {
+  getTransformsBetween,
+  latestVersion,
+} from '../../assets/codemods/registry.mjs';
 import {runCodemods} from '../../assets/codemods/runner.mjs';
 import {
   discoverIntegrationCodemods,
@@ -32,17 +35,15 @@ import {
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
-import {Project} from '../../foundation/config/project.mjs';
-import {
-  loadIntegrations,
-  markProviderConflicts,
-} from '../../foundation/integrations/integrations.mjs';
+import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
+import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
+import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
 import {warnOnIntegrationIssues} from '../../foundation/integrations/integration-warnings.mjs';
 import {logger} from '../logger.mjs';
 
 // Re-exported for the run leaf's lightweight agent-docs inspection path
 // (config_fixable short-circuit, where the full render cannot load config).
-export { inspectAgentDocs };
+export {inspectAgentDocs};
 
 const execFileAsync = promisify(execFile);
 
@@ -291,7 +292,13 @@ export async function collectAllCodemods() {
   );
   for (const {version, transforms} of manifests) {
     for (const {name, meta, optional} of transforms) {
-      codemods.push({name, title: meta.title, version, pr: meta.pr, optional: !!optional});
+      codemods.push({
+        name,
+        title: meta.title,
+        version,
+        pr: meta.pr,
+        optional: !!optional,
+      });
     }
   }
   return codemods;
@@ -322,33 +329,36 @@ export async function ensureCodemodDeps({installDeps} = {}) {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
-export async function runCoreCodemods(versionManifests, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runCoreCodemods(
+  versionManifests,
+  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+) {
   return runCodemods(versionManifests, {
     apply,
     path: srcPath,
     codemod,
     skipCodemods,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
   });
 }
 
-/**
- * One installed package at one version; two specs that reach it share this.
- * @param {{name: string, version?: string}} integration
- * @returns {string}
- */
-function packageIdentity(integration) {
-  return `${integration.name}\u0000${integration.version ?? ''}`;
-}
-
 /**
  * Load the consumer project's config + integrations. Throws on invalid config;
  * the run leaf decides between the config_fixable preview and a hard abort.
+ *
+ * Provider identity is resolved by the same resolver Project uses, on top of
+ * Project's ledger, under the codemod policy: a package that lists itself runs
+ * its installed copy's released codemods, never the work in progress being
+ * authored, and autolinked and local packages claim provider IDs without
+ * running codemods.
+ *
  * @param {string} cwd
  * @param {string[]} [extraIntegrationSpecs] explicit `--integration` specs
- * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]}>}
+ * @returns {Promise<{postCodemodHooks: import('../../authoring/config/type').PostCodemodHook[], integrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], ledger: import('../../foundation/integrations/provider-resolution.mjs').ProviderLedger}>}
  */
 export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
@@ -360,23 +370,38 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // Configured packages come from Project, which has already resolved provider
   // identity over configured, autolinked, and local packages. Loading them
   // again here would let upgrade run codemods from a package Project set aside.
-  const configured = project.loadedIntegrations.filter(
-    integration =>
-      !integration.__autolinked && configuredSpecs.has(integration.__spec),
-  );
+  // Autolinked packages and the package being authored join only as claimants:
+  // every other command uses them for their provider IDs, but upgrade has
+  // never run their codemods.
+  const candidates = project.loadedIntegrations.flatMap(integration => {
+    const source =
+      !integration.__autolinked && configuredSpecs.has(integration.__spec)
+        ? /** @type {const} */ ('configured')
+        : integration.__autolinked
+          ? /** @type {const} */ ('autolinked')
+          : integration.__local
+            ? /** @type {const} */ ('local')
+            : null;
+    return source == null
+      ? []
+      : [{source, integration, spec: integration.__spec}];
+  });
   // A package that lists itself runs its installed copy's released codemods,
-  // never the work in progress being authored, so that copy stands in for it.
+  // never the work in progress being authored; the resolver puts that copy in
+  // its place. Naming the package being authored with --integration asks for
+  // the installed copy too.
   const local = project.loadedIntegrations.find(
     integration => integration.__local,
   );
-  const selfListed = local != null && configured.includes(local);
-  if (local != null && selfListed && project.configPath) {
-    const installed = await loadIntegrations([local.__spec], {
-      cwd: path.dirname(project.configPath),
-      resolveProviders: false,
-    });
-    configured.splice(configured.indexOf(local), 1, ...installed);
-  }
+  const selfListed =
+    local != null && !local.__autolinked && configuredSpecs.has(local.__spec);
+  const installed =
+    local != null && selfListed && project.configPath
+      ? await loadIntegrations([local.__spec], {
+          cwd: path.dirname(project.configPath),
+          resolveProviders: false,
+        })
+      : [];
   const extraSpecs = uniqueFiles(extraIntegrationSpecs ?? []).filter(
     spec => !configuredSpecs.has(spec),
   );
@@ -384,38 +409,23 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
     extraSpecs.length === 0
       ? []
       : await loadIntegrations(extraSpecs, {resolveProviders: false});
-  // Naming the package being authored with --integration asks for its
-  // installed copy too, so the local package must not claim against it.
-  const localStandsIn =
-    local != null &&
-    (selfListed || extras.some(extra => extra.name === local.name));
-  // Autolinked packages and the package being authored join the pass only as
-  // claimants: every other command uses them for their provider IDs, but
-  // upgrade has never run their codemods and still does not. An extra that
-  // names one of them opts it in, so the extra stands in for that claimant.
-  const extraIdentities = new Set(extras.map(packageIdentity));
-  const claimantsOnly = project.loadedIntegrations.filter(
-    integration =>
-      (integration.__autolinked || (integration.__local && !localStandsIn)) &&
-      !extraIdentities.has(packageIdentity(integration)),
-  );
-  const resolved = markProviderConflicts([
-    ...configured,
-    ...claimantsOnly,
-    ...extras,
-  ]);
-  // Claimants leave by package directory, not object identity: the pass can
-  // return one as a new conflict entry, and upgrade must not warn that a
-  // package every other command uses contributes nothing.
-  const claimantDirs = new Set(
-    claimantsOnly.map(integration => integration.__packageDir),
+  const {integrations, ledger} = resolveProviders(
+    [
+      ...candidates,
+      ...installed.map(integration => ({
+        source: /** @type {const} */ ('installed'),
+        integration,
+        spec: integration.__spec,
+      })),
+      ...extras.map(integration => ({
+        source: /** @type {const} */ ('extra'),
+        integration,
+        spec: integration.__spec,
+      })),
+    ],
+    {codemods: true, prior: providerLedgerOf(project)},
   );
-  const integrations = resolved.filter(
-    integration =>
-      integration.__packageDir == null ||
-      !claimantDirs.has(integration.__packageDir),
-  );
-  return {postCodemodHooks, integrations};
+  return {postCodemodHooks, integrations, ledger};
 }
 
 /**
@@ -450,7 +460,10 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
     try {
       const byVersion = await discoverIntegrationCodemods([integration]);
       for (const [version, rawList] of byVersion) {
-        const list = /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (/** @type {unknown} */ (rawList));
+        const list =
+          /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */ (
+            /** @type {unknown} */ (rawList)
+          );
         const existing = integrationCodemodsByVersion.get(version);
         if (existing) existing.push(...list);
         else integrationCodemodsByVersion.set(version, [...list]);
@@ -467,9 +480,21 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
-export async function runIntegrationCodemodsStep(versionGroups, {apply, path: srcPath, codemod, skipCodemods}) {
+export async function runIntegrationCodemodsStep(
+  versionGroups,
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    contents,
+    silent,
+  },
+) {
   const jscodeshift = (await import('jscodeshift')).default;
   return runIntegrationCodemods(versionGroups, {
     apply,
@@ -477,6 +502,9 @@ export async function runIntegrationCodemodsStep(versionGroups, {apply, path: sr
     codemod,
     skipCodemods,
     jscodeshift,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
+    contents,
   });
 }

package/api/upgrade/provider-agreement.test.mjs

@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Where `upgrade` and Project still disagree on a provider ID's winner.
+ *
+ * Both repros are `it.fails`: each asserts the agreeing result, and fails
+ * today. `upgrade` lets an `--integration` extra of the same name@version stand
+ * in for an autolinked package, from any directory, and orders that extra with
+ * the extras. So another extra can take the provider ID in `upgrade` while
+ * every other command gives it to the autolinked package. The provider ledger
+ * property test carves out exactly this shape.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadProjectContext} from './_adapter.mjs';
+import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-upgrade-agreement-'),
+  );
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Install a package under node_modules/<dir>.
+ * @param {string} dir
+ * @param {{name: string, version: string}} pkg
+ * @param {string} manifest manifest module source
+ */
+function install(dir, pkg, manifest) {
+  const pkgDir = path.join(tmpDir, 'node_modules', ...dir.split('/'));
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(pkg));
+  fs.writeFileSync(path.join(pkgDir, 'astryx.integration.mjs'), manifest);
+}
+
+/** An autolinked `@acme/a` and an `@acme/other` that claims its provider ID. */
+function autolinkedWithRival() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+  );
+  install(
+    '@acme/a',
+    {name: '@acme/a', version: '1.0.0'},
+    'export default {};\n',
+  );
+  install(
+    '@acme/other',
+    {name: '@acme/other', version: '1.0.0'},
+    "export default {providerId: '@acme/a'};\n",
+  );
+}
+
+/**
+ * The package each resolution lets contribute under a provider ID.
+ * @param {Map<string, any>} ledger
+ * @param {string} providerId
+ */
+function winnerOf(ledger, providerId) {
+  return [...ledger.values()].find(
+    entry => entry.outcome === 'contributes' && entry.providerId === providerId,
+  )?.key;
+}
+
+/** @param {Array<import('../../foundation/integrations/integrations.mjs').LoadedIntegration>} integrations */
+function claims(integrations) {
+  return integrations.map(integration => [
+    integration.name,
+    integration.__providerConflict?.claimedBy ?? null,
+  ]);
+}
+
+describe('upgrade and Project on an autolinked package named with --integration', () => {
+  it('agree when the autolinked package is named first', async () => {
+    autolinkedWithRival();
+    const project = await Project.load(tmpDir, {fresh: true});
+    const upgrade = await loadProjectContext(tmpDir, [
+      '@acme/a',
+      '@acme/other',
+    ]);
+
+    expect(claims(upgrade.integrations)).toEqual([
+      ['@acme/a', null],
+      ['@acme/other', '@acme/a'],
+    ]);
+    expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+      winnerOf(providerLedgerOf(project), '@acme/a'),
+    );
+  });
+
+  it.fails(
+    'agree when an extra that claims its ID is named first',
+    async () => {
+      autolinkedWithRival();
+      const project = await Project.load(tmpDir, {fresh: true});
+      // Today upgrade runs @acme/other and reports @acme/a, which every other
+      // command uses, as contributing nothing.
+      const upgrade = await loadProjectContext(tmpDir, [
+        '@acme/other',
+        '@acme/a',
+      ]);
+
+      expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+        winnerOf(providerLedgerOf(project), '@acme/a'),
+      );
+      expect(claims(upgrade.integrations)).toEqual([
+        ['@acme/other', '@acme/a'],
+        ['@acme/a', null],
+      ]);
+    },
+  );
+
+  it.fails(
+    'agree when a copy of it in another directory is named',
+    async () => {
+      autolinkedWithRival();
+      // The same name@version in another directory, with a manifest that fails.
+      install(
+        '@acme/a-copy',
+        {name: '@acme/a', version: '1.0.0'},
+        "throw new Error('broken copy');\n",
+      );
+      const project = await Project.load(tmpDir, {fresh: true});
+      // Today the broken copy stands in for @acme/a by name@version, so upgrade
+      // has no claimant left for the ID and @acme/other takes it.
+      const upgrade = await loadProjectContext(tmpDir, [
+        '@acme/a-copy',
+        '@acme/other',
+      ]);
+
+      expect(winnerOf(upgrade.ledger, '@acme/a')).toBe(
+        winnerOf(providerLedgerOf(project), '@acme/a'),
+      );
+    },
+  );
+});