feat: add transform for useMergerefs

packages/migrator/docs/CLI_REFERENCE.md

@@ -109,6 +109,21 @@ npx @coinbase/cds-migrator ./src -t button-variant -t input-size
 
 **Transforms are standalone files** in `src/transforms/` that run independently.
 
+#### `-ps, --package-scope <scope>`
+
+Limit scope-aware transforms (for example `button-variant-values`, `migrate-use-merge-refs`) to imports under a single npm scope. Omit this flag to rewrite every scope (for example both `@coinbase/cds-web` and `@acme/cds-web`).
+
+```bash
+# Only rewrite @coinbase/cds-* imports
+npx @coinbase/cds-migrator ./src -t button-variant-values --package-scope coinbase
+
+# Shorthand
+npx @coinbase/cds-migrator ./src -t button-variant-values -ps coinbase
+
+# Equivalent
+npx @coinbase/cds-migrator ./src -t button-variant-values --package-scope @coinbase
+```
+
 #### `--clear-history`
 
 Clear migration history for a path.

packages/migrator/jest.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  displayName: 'migrator',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+};

packages/migrator/project.json

@@ -7,6 +7,12 @@
     "build": {
       "command": "rm -rf cjs && babel ./src --out-dir cjs --extensions .ts,.tsx,.js,.jsx --copy-files --no-copy-ignored"
     },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "{projectRoot}/jest.config.mjs"
+      }
+    },
     "lint": {
       "executor": "@nx/eslint:lint"
     },

packages/migrator/src/cli-args.ts

@@ -12,6 +12,8 @@ export type CliArgs = {
   clearHistory?: boolean;
   partial?: boolean;
   transform?: string[];
+  /** When set, only rewrite imports from this npm scope (e.g. coinbase or @coinbase). */
+  packageScope?: string;
 };
 
 export function parseCliArgs(): CliArgs {
@@ -30,6 +32,10 @@ export function parseCliArgs(): CliArgs {
     .option(
       '-t, --transform <transforms...>',
       'Migrate specific transforms by name (preset auto-detected)',
+    )
+    .option(
+      '-ps, --package-scope <scope>',
+      'Only rewrite imports from this npm scope (e.g. coinbase or @coinbase). Omit to include every scope',
     );
 
   program.parse();
@@ -45,5 +51,6 @@ export function parseCliArgs(): CliArgs {
     clearHistory: options.clearHistory,
     partial: options.partial,
     transform: options.transform,
+    packageScope: options.packageScope,
   };
 }

packages/migrator/src/cli.ts

@@ -216,13 +216,17 @@ async function setupMigration(args: CliArgs) {
     console.log('\n📋 Migration Summary:');
     console.log(`  Path: ${targetPath}`);
     console.log(`  Mode: ${args.dryRun ? 'Dry Run' : 'Apply Changes'}`);
+    if (args.packageScope) {
+      console.log(`  Package scope: ${args.packageScope}`);
+    }
     console.log(`  Transforms: ${filtered.length}\n`);
 
     return {
       preset: 'direct-transform',
       path: targetPath,
       dryRun: args.dryRun || false,
       transformsToRun: filtered,
+      packageScope: args.packageScope,
     };
   }
 
@@ -294,13 +298,17 @@ async function setupMigration(args: CliArgs) {
   console.log(`  Preset: ${preset}`);
   console.log(`  Path: ${targetPath}`);
   console.log(`  Mode: ${args.dryRun ? 'Dry Run' : 'Apply Changes'}`);
+  if (args.packageScope) {
+    console.log(`  Package scope: ${args.packageScope}`);
+  }
   console.log(`  Transforms: ${filtered.length}\n`);
 
   return {
     preset,
     path: targetPath,
     dryRun: args.dryRun || false,
     transformsToRun: filtered,
+    packageScope: args.packageScope,
   };
 }
 

packages/migrator/src/presets/v8-to-v9/manifest.json

@@ -2,25 +2,15 @@
   "preset": "v8-to-v9",
   "description": "Migration from CDS v8 to v9",
   "transforms": [
-    {
-      "name": "input-size-values",
-      "description": "Update Input size prop values from sm/md/lg to small/medium/large (@coinbase/cds-web)",
-      "file": "example-transform"
-    },
-    {
-      "name": "use-theme-return-type",
-      "description": "Update useTheme hook destructured return values (@coinbase/cds-common)",
-      "file": "example-transform"
-    },
-    {
-      "name": "format-currency-options",
-      "description": "Update formatCurrency options parameter (@coinbase/cds-utils)",
-      "file": "example-transform"
-    },
     {
       "name": "button-variant-values",
       "description": "Remap Button/IconButton variant values: tertiary -> inverse, foregroundMuted -> secondary",
-      "file": "button-variant-values"
+      "file": "v9/button-variant-values"
+    },
+    {
+      "name": "migrate-use-merge-refs-import",
+      "description": "Migrate useMergeRefs: @coinbase/cds-common/hooks/useMergeRefs → utils/mergeRefs, rename binding to mergeRefs, merge duplicate imports",
+      "file": "v9/migrate-use-merge-refs"
     }
   ]
 }

packages/migrator/src/runner.ts

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 
 import { createLogger, recordTransformRun } from './utils/index';
+import { normalizePackageScope } from './utils/package-scope';
 import type { Transform } from './types';
 
 // In CommonJS, __dirname is automatically available
@@ -19,10 +20,19 @@ type RunMigrationOptions = {
   path: string;
   dryRun: boolean;
   transformsToRun: Transform[];
+  /** Forwarded to jscodeshift as `--packageScope` for scope-targeted transforms. */
+  packageScope?: string;
 };
 
 export async function runMigration(options: RunMigrationOptions): Promise<void> {
-  const { preset, path: targetPath, dryRun, transformsToRun } = options;
+  const {
+    preset,
+    path: targetPath,
+    dryRun,
+    transformsToRun,
+    packageScope: packageScopeRaw,
+  } = options;
+  const packageScope = packageScopeRaw ? normalizePackageScope(packageScopeRaw) : undefined;
 
   console.log(`\n🔄 Running migration...\n`);
 
@@ -31,6 +41,9 @@ export async function runMigration(options: RunMigrationOptions): Promise<void>
   logger.info(`Starting migration${preset ? ` (${preset})` : ''}`);
   logger.info(`Target path: ${targetPath}`);
   logger.info(`Mode: ${dryRun ? 'Dry Run' : 'Apply Changes'}`);
+  if (packageScope) {
+    logger.info(`Package scope: ${packageScope} (only matching imports are rewritten)`);
+  }
 
   if (transformsToRun.length === 0) {
     console.log('ℹ️  No transforms to run.');
@@ -87,6 +100,7 @@ export async function runMigration(options: RunMigrationOptions): Promise<void>
         '--ignore-pattern=**/dist/**',
         '--ignore-pattern=**/build/**',
         `--transform=${fullTransformPath}`,
+        ...(packageScope ? [`--packageScope=${packageScope}`] : []),
         targetPath,
       ];
 

packages/migrator/src/test-utils/readTransformFixture.ts

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Read a fixture file from `…/__testfixtures__/<suite>/<relativePath>` relative to a transform’s
+ * `__tests__` directory (sibling of `__testfixtures__`).
+ *
+ * @param testFileDir - `__dirname` from the test file (the `__tests__` folder).
+ * @param suite - Subfolder under `__testfixtures__` (e.g. `migrate-use-merge-refs`).
+ * @param relativePath - File name within that folder, including extension (e.g. `basic.input.tsx`).
+ */
+export function readTransformFixture(
+  testFileDir: string,
+  suite: string,
+  relativePath: string,
+): string {
+  return fs.readFileSync(
+    path.join(testFileDir, '..', '__testfixtures__', suite, relativePath),
+    'utf8',
+  );
+}

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/alternate-scope-basic.input.tsx

@@ -0,0 +1,6 @@
+import { useMergeRefs } from '@example/cds-common/hooks/useMergeRefs';
+
+export const X = () => {
+  const ref = useMergeRefs(a, b);
+  return ref;
+};

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/alternate-scope-basic.output.tsx

@@ -0,0 +1,6 @@
+import { mergeRefs } from "@example/cds-common/utils/mergeRefs";
+
+export const X = () => {
+  const ref = mergeRefs(a, b);
+  return ref;
+};

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/basic.input.tsx

@@ -0,0 +1,6 @@
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';
+
+export const X = () => {
+  const ref = useMergeRefs(a, b);
+  return ref;
+};

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/basic.output.tsx

@@ -0,0 +1,6 @@
+import { mergeRefs } from "@coinbase/cds-common/utils/mergeRefs";
+
+export const X = () => {
+  const ref = mergeRefs(a, b);
+  return ref;
+};

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/import-alias.input.tsx

@@ -0,0 +1,2 @@
+import { useMergeRefs as combineRefs } from '@coinbase/cds-common/hooks/useMergeRefs';
+combineRefs(r1, r2);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/import-alias.output.tsx

@@ -0,0 +1,2 @@
+import { mergeRefs as combineRefs } from "@coinbase/cds-common/utils/mergeRefs";
+combineRefs(r1, r2);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/jest-mock.input.tsx

@@ -0,0 +1,3 @@
+jest.mock('@coinbase/cds-common/hooks/useMergeRefs');
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';
+useMergeRefs(x);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/jest-mock.output.tsx

@@ -0,0 +1,3 @@
+jest.mock("@coinbase/cds-common/utils/mergeRefs");
+import { mergeRefs } from "@coinbase/cds-common/utils/mergeRefs";
+mergeRefs(x);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/merge-duplicate-imports.input.tsx

@@ -0,0 +1,4 @@
+import { mergeRefs } from '@coinbase/cds-common/utils/mergeRefs';
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';
+
+const cb = mergeRefs(useMergeRefs(a));

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/merge-duplicate-imports.output.tsx

@@ -0,0 +1,3 @@
+import { mergeRefs } from '@coinbase/cds-common/utils/mergeRefs';
+
+const cb = mergeRefs(mergeRefs(a));

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/nothing-to-migrate.input.tsx

@@ -0,0 +1,2 @@
+import React from 'react';
+export const x = 1;

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/object-literal-key.input.tsx

@@ -0,0 +1,3 @@
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';
+const o = { useMergeRefs: 1 };
+useMergeRefs(r);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/object-literal-key.output.tsx

@@ -0,0 +1,3 @@
+import { mergeRefs } from "@coinbase/cds-common/utils/mergeRefs";
+const o = { useMergeRefs: 1 };
+mergeRefs(r);

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/re-export.input.tsx

@@ -0,0 +1 @@
+export { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/re-export.output.tsx

@@ -0,0 +1 @@
+export { mergeRefs } from "@coinbase/cds-common/utils/mergeRefs";

packages/migrator/src/transforms/v9/__testfixtures__/migrate-use-merge-refs/third-party-import.input.tsx

@@ -0,0 +1,5 @@
+import { useMergeRefs } from 'some-other-library';
+
+export function f() {
+  return useMergeRefs(a, b);
+}

packages/migrator/src/transforms/__tests__/button-variant-values.test.ts → packages/migrator/src/transforms/v9/__tests__/button-variant-values.test.ts

@@ -1,21 +1,19 @@
-import fs from 'fs';
-import path from 'path';
+import { applyTransform } from 'jscodeshift/src/testUtils';
 
-const { applyTransform } = require('jscodeshift/src/testUtils');
+import { readTransformFixture } from '../../../test-utils/readTransformFixture';
+import transform from '../button-variant-values';
 
-const transform = require('../button-variant-values');
+const FIXTURE_SUITE = 'button-variant-values';
 
-const PARSER_OPTIONS = { parser: 'tsx' };
-
-function applyButtonVariantTransform(source: string) {
-  return applyTransform(transform, {}, { source }, PARSER_OPTIONS);
+function applyButtonVariantTransform(
+  source: string,
+  jscodeshiftOptions: Record<string, unknown> = {},
+) {
+  return applyTransform(transform, jscodeshiftOptions, { source }, { parser: 'tsx' });
 }
 
 function readFixture(name: string) {
-  return fs.readFileSync(
-    path.join(__dirname, '..', '__testfixtures__', 'button-variant-values', `${name}.tsx`),
-    'utf8',
-  );
+  return readTransformFixture(__dirname, FIXTURE_SUITE, `${name}.tsx`);
 }
 
 describe('button-variant-values', () => {
@@ -40,6 +38,24 @@ const App = () => <Button variant="foregroundMuted">Click</Button>;
       expect(output).not.toContain('variant="foregroundMuted"');
     });
 
+    it('rewrites variant="tertiary" to variant="inverse" on Button from a non-@coinbase scope', () => {
+      const input = `
+import { Button } from '@example/cds-web';
+const App = () => <Button variant="tertiary">Click</Button>;
+`;
+      const output = applyButtonVariantTransform(input);
+      expect(output).toContain('variant="inverse"');
+      expect(output).not.toContain('variant="tertiary"');
+    });
+
+    it('skips non-matching scope when --package-scope is set', () => {
+      const input = `
+import { Button } from '@example/cds-web';
+const App = () => <Button variant="tertiary">Click</Button>;
+`;
+      expect(applyButtonVariantTransform(input, { packageScope: '@coinbase' })).toBe('');
+    });
+
     it('rewrites variant="tertiary" to variant="inverse" on IconButton from @coinbase/cds-mobile', () => {
       const input = `
 import { IconButton } from '@coinbase/cds-mobile';