@ethlete/query 6.0.0-next.5 → 6.0.0-next.51

package/generators/migrate-to-query-v3/legacy-query-creator-migration.js

@@ -1,6 +1,8 @@
-import { visitNotIgnoredFiles } from '@nx/devkit';
 import * as ts from 'typescript';
-import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromQuery } from './shared.js';
+import { collectV2BearerAuthConfigs, renderAuthProviderBody } from './auth-provider-scaffold.js';
+import { createModuleGraph } from './module-graph.js';
+import { pruneUnusedNamedImports, renameImportedReferences } from './rename-symbols.js';
+import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromEthleteCore, ensureImportFromQuery, legacyQueryDeprecationTag, } from './shared.js';
 const LEGACY_HTTP_METHOD = {
     GET: 'get',
     POST: 'post',
@@ -8,19 +10,21 @@ const LEGACY_HTTP_METHOD = {
     PATCH: 'patch',
     DELETE: 'delete',
 };
+const HTTP_OPTION_NAMES = ['reportProgress', 'responseType', 'transferCache', 'withCredentials'];
 const isLegacyHttpMethod = (value) => {
     return Object.values(LEGACY_HTTP_METHOD).includes(value);
 };
-export const createNewQueryCreators = (tree, queryClientFiles, report) => {
+export const createNewQueryCreators = (tree, queryClientFiles, report, scope) => {
     const createdFiles = [];
     const authProvidersNeeded = new Map();
     const clientNameToFilePath = new Map();
+    const creatorToClient = new Map();
     queryClientFiles.forEach((configNames, filePath) => {
         configNames.forEach((configName) => {
             clientNameToFilePath.set(configName, filePath);
         });
     });
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
             return;
         }
@@ -33,6 +37,7 @@ export const createNewQueryCreators = (tree, queryClientFiles, report) => {
             return;
         }
         legacyCreators.forEach((creator) => {
+            creatorToClient.set(creator.name, creator.clientName);
             if (!creator.secure) {
                 return;
             }
@@ -48,17 +53,23 @@ export const createNewQueryCreators = (tree, queryClientFiles, report) => {
         }
     });
     if (authProvidersNeeded.size > 0) {
-        createAuthProviders(tree, authProvidersNeeded, report);
+        createAuthProviders({
+            tree,
+            authProvidersNeeded,
+            report,
+            v2Configs: collectV2BearerAuthConfigs(tree, scope),
+            creatorToClient,
+        });
     }
     if (createdFiles.length > 0) {
         console.log('\n✅ Created new query creators in:');
         createdFiles.forEach((filePath) => console.log(`   - ${filePath}`));
     }
 };
-export const updateLegacyCreatorImportsAndUsages = (tree) => {
+export const updateLegacyCreatorImportsAndUsages = (tree, scope, report) => {
     const legacyCreators = new Map();
     const updatedFiles = [];
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
             return;
         }
@@ -66,16 +77,17 @@ export const updateLegacyCreatorImportsAndUsages = (tree) => {
         if (!content) {
             return;
         }
-        const wrappers = findLegacyWrappers(content);
-        wrappers.forEach((legacyName, originalName) => {
-            legacyCreators.set(originalName, legacyName);
+        findLegacyWrappers(content).forEach((legacyName, originalName) => {
+            legacyCreators.set(originalName, { legacyName, definedIn: filePath });
         });
     });
     if (legacyCreators.size === 0) {
         return;
     }
     console.log(`\n✅ Found ${legacyCreators.size} legacy query creator wrappers`);
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    const moduleGraph = createModuleGraph(tree);
+    const pendingWrites = new Map();
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
             return;
         }
@@ -83,18 +95,110 @@ export const updateLegacyCreatorImportsAndUsages = (tree) => {
         if (!content || containsLegacyWrapperDefinitions(content)) {
             return;
         }
-        const nextImports = updateLegacyCreatorImports(content, legacyCreators);
-        const nextContent = updateLegacyCreatorUsages(nextImports, legacyCreators);
+        const nextContent = pointFileAtLegacyWrappers({
+            content,
+            filePath,
+            legacyCreators,
+            moduleGraph,
+            report,
+        });
         if (nextContent !== content) {
-            tree.write(filePath, nextContent);
-            updatedFiles.push(filePath);
+            pendingWrites.set(filePath, nextContent);
         }
     });
+    // Writing a barrel mid-pass would hide its original re-exports from consumers visited after it.
+    pendingWrites.forEach((nextContent, filePath) => {
+        tree.write(filePath, nextContent);
+        updatedFiles.push(filePath);
+    });
     if (updatedFiles.length > 0) {
         console.log('\n✅ Updated legacy creator imports and usages in:');
         updatedFiles.forEach((filePath) => console.log(`   - ${filePath}`));
     }
 };
+/**
+ * Rewrites this file's imports of migrated creators to the `legacy*` wrappers.
+ *
+ * Two rules keep the rewrite honest, and both exist because the first version of this pass did not
+ * have them:
+ *
+ * - An import is only touched when the module it comes from really does resolve to the file that
+ *   defines the wrapper. A same-named export from an unrelated package stays as it is.
+ * - An alias is preserved (`legacyGetPerson as getPersonQuery`) instead of being dropped, so the
+ *   call sites using that alias keep compiling.
+ */
+const pointFileAtLegacyWrappers = ({ content, filePath, legacyCreators, moduleGraph, report, }) => {
+    const sourceFile = createSourceFile(content, filePath);
+    const replacements = [];
+    const referenceRenames = new Map();
+    const resolvesToWrapper = (specifier, importedName, registration) => moduleGraph.findDeclaringFile(filePath, specifier, importedName) === registration.definedIn;
+    const rewriteSpecifiers = (elements, moduleSpecifier) => {
+        let changed = false;
+        const nextElements = elements.map((element) => {
+            const importedName = element.propertyName?.text ?? element.name.text;
+            const registration = legacyCreators.get(importedName);
+            if (!registration || !resolvesToWrapper(moduleSpecifier, importedName, registration)) {
+                return element.getText(sourceFile);
+            }
+            changed = true;
+            // Aliased: only the imported half changes, so nothing in the file body has to move.
+            if (element.propertyName) {
+                return `${registration.legacyName} as ${element.name.text}`;
+            }
+            referenceRenames.set(element.name.text, registration.legacyName);
+            return registration.legacyName;
+        });
+        return changed ? nextElements : null;
+    };
+    for (const node of sourceFile.statements) {
+        if (ts.isImportDeclaration(node) &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            node.importClause?.namedBindings &&
+            ts.isNamedImports(node.importClause.namedBindings)) {
+            const nextElements = rewriteSpecifiers(node.importClause.namedBindings.elements, node.moduleSpecifier.text);
+            if (nextElements) {
+                replacements.push({
+                    start: node.getStart(sourceFile),
+                    end: node.getEnd(),
+                    replacement: `import { ${nextElements.join(', ')} } from '${node.moduleSpecifier.text}';`,
+                });
+            }
+            continue;
+        }
+        // Re-exports need the same treatment, or a barrel keeps pointing at the v3 creator.
+        if (ts.isExportDeclaration(node) &&
+            node.moduleSpecifier &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            node.exportClause &&
+            ts.isNamedExports(node.exportClause)) {
+            const nextElements = rewriteSpecifiers(node.exportClause.elements, node.moduleSpecifier.text);
+            if (nextElements) {
+                replacements.push({
+                    start: node.getStart(sourceFile),
+                    end: node.getEnd(),
+                    replacement: `export { ${nextElements.join(', ')} } from '${node.moduleSpecifier.text}';`,
+                });
+            }
+        }
+    }
+    let result = content;
+    replacements.sort((left, right) => right.start - left.start);
+    replacements.forEach(({ start, end, replacement }) => {
+        result = result.slice(0, start) + replacement + result.slice(end);
+    });
+    const renamed = renameImportedReferences(result, referenceRenames);
+    renamed.shadowed.forEach((name) => {
+        report.addManualReview({
+            title: `Point ${name} at its legacy wrapper by hand`,
+            summary: `${filePath} imports the migrated creator \`${name}\` but also declares something with that name, so the migration left its usages alone to avoid rewriting the wrong symbol.`,
+            action: `Rename the local declaration or the import alias, then point the query usages at \`${legacyCreators.get(name)?.legacyName ?? `legacy${capitalizeFirstLetter(name)}`}\`.`,
+            locations: [{ filePath }],
+            source: 'legacy-query-creator-migration',
+            dedupeKey: `shadowed-rename:${filePath}:${name}`,
+        });
+    });
+    return renamed.content;
+};
 const toLegacyName = (name) => `legacy${capitalizeFirstLetter(name)}`;
 const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report) => {
     const sourceFile = createSourceFile(content, filePath);
@@ -128,17 +232,62 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                 secure: false,
                 httpOptions: new Map(),
             };
+            const warnUnreadableConfigValue = (property, passedAs) => {
+                const propertyName = property.name.getText(sourceFile);
+                report.addWarning({
+                    title: `Carry over \`${propertyName}\` of ${creatorName}`,
+                    summary: `${creatorName} passes \`${propertyName}\` ${passedAs} in its v2 config. The migration cannot read its value, so it was not carried over to the v3 creator.`,
+                    action: propertyName === 'secure'
+                        ? 'If the value is true, switch the generated creator to the matching *Secure creator of the client by hand.'
+                        : 'Move what it configures onto the generated creator by hand.',
+                    locations: [
+                        { filePath, line: sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile)).line + 1 },
+                    ],
+                    source: 'legacy-query-creator-migration',
+                    dedupeKey: `unreadable-config:${filePath}:${creatorName}:${propertyName}`,
+                });
+            };
             const configObject = node.initializer.arguments[0];
             if (configObject && ts.isObjectLiteralExpression(configObject)) {
                 configObject.properties.forEach((property) => {
+                    if (ts.isSpreadAssignment(property)) {
+                        report.addWarning({
+                            title: `Restore the spread config of ${creatorName}`,
+                            summary: `${creatorName} spreads \`${property.expression.getText(sourceFile)}\` into its v2 config. The migration cannot see what it contains, so none of it was carried over to the v3 creator.`,
+                            action: 'Move the route, secure flag, types and http options it provides onto the generated creator by hand.',
+                            locations: [
+                                { filePath, line: sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile)).line + 1 },
+                            ],
+                            source: 'legacy-query-creator-migration',
+                            dedupeKey: `spread-config:${filePath}:${creatorName}`,
+                        });
+                        return;
+                    }
+                    if (ts.isShorthandPropertyAssignment(property)) {
+                        if (property.name.text === 'route') {
+                            info.route = property.name.text;
+                        }
+                        if (HTTP_OPTION_NAMES.includes(property.name.text)) {
+                            info.httpOptions.set(property.name.text, property.name.text);
+                        }
+                        if (property.name.text !== 'route' && !HTTP_OPTION_NAMES.includes(property.name.text)) {
+                            warnUnreadableConfigValue(property, 'as a shorthand property');
+                        }
+                        return;
+                    }
                     if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
                         return;
                     }
                     if (property.name.text === 'route') {
                         info.route = property.initializer.getText(sourceFile);
                     }
-                    if (property.name.text === 'secure' && property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
-                        info.secure = true;
+                    if (property.name.text === 'secure') {
+                        if (property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                            info.secure = true;
+                        }
+                        else if (property.initializer.kind !== ts.SyntaxKind.FalseKeyword) {
+                            warnUnreadableConfigValue(property, 'with a value that is not a literal');
+                        }
                     }
                     if (property.name.text === 'types' && ts.isObjectLiteralExpression(property.initializer)) {
                         property.initializer.properties.forEach((typeProperty) => {
@@ -173,7 +322,7 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                             }
                         });
                     }
-                    if (['reportProgress', 'responseType', 'transferCache', 'withCredentials'].includes(property.name.text)) {
+                    if (HTTP_OPTION_NAMES.includes(property.name.text)) {
                         info.httpOptions.set(property.name.text, property.initializer.getText(sourceFile));
                     }
                 });
@@ -205,27 +354,42 @@ const transformLegacyQueryCreators = (content, legacyCreators) => {
         }
         creatorsByClient.get(creator.clientName).push(creator);
     });
+    const wrappersByStatement = new Map();
     legacyCreators.forEach((creator) => {
-        const nextCreator = generateNewQueryCreator(creator);
-        const legacyWrapper = generateLegacyWrapper(creator);
         let variableStatement;
+        let declaration;
         const visit = (node) => {
+            if (variableStatement)
+                return;
             if (ts.isVariableStatement(node)) {
-                const declaration = node.declarationList.declarations[0];
-                if (declaration && ts.isIdentifier(declaration.name) && declaration.name.text === creator.name) {
+                declaration = node.declarationList.declarations.find((candidate) => ts.isIdentifier(candidate.name) && candidate.name.text === creator.name);
+                if (declaration) {
                     variableStatement = node;
+                    return;
                 }
             }
             ts.forEachChild(node, visit);
         };
         visit(sourceFile);
-        if (variableStatement) {
+        if (!variableStatement || !declaration)
+            return;
+        const isTopLevel = ts.isSourceFile(variableStatement.parent);
+        const exportPrefix = isTopLevel ? 'export ' : '';
+        const nextCreator = `${creator.name} = ${generateNewQueryCreator(creator)}`;
+        const legacyWrapper = generateLegacyWrapper(creator, exportPrefix);
+        if (variableStatement.declarationList.declarations.length === 1) {
             replacements.push({
                 start: variableStatement.getStart(sourceFile),
                 end: variableStatement.getEnd(),
-                replacement: `${nextCreator}\n${legacyWrapper}`,
+                replacement: `${exportPrefix}const ${nextCreator};\n${legacyWrapper}`,
             });
+            return;
         }
+        replacements.push({ start: declaration.getStart(sourceFile), end: declaration.getEnd(), replacement: nextCreator });
+        wrappersByStatement.set(variableStatement, [...(wrappersByStatement.get(variableStatement) ?? []), legacyWrapper]);
+    });
+    wrappersByStatement.forEach((wrappers, statement) => {
+        replacements.push({ start: statement.getEnd(), end: statement.getEnd(), replacement: `\n${wrappers.join('\n')}` });
     });
     let result = content;
     replacements.sort((left, right) => right.start - left.start);
@@ -233,7 +397,10 @@ const transformLegacyQueryCreators = (content, legacyCreators) => {
         result = result.slice(0, start) + replacement + result.slice(end);
     });
     result = ensureImportFromQuery(result, ['createLegacyQueryCreator']);
-    return addCreatorImports(result, creatorsByClient);
+    result = addCreatorImports(result, creatorsByClient);
+    // The rewritten creators no longer go through `def<T>()` or the v2 client object, so whatever is
+    // left over from those constructs would land as a lint error the moment `formatFiles` runs.
+    return pruneUnusedNamedImports(result);
 };
 const addCreatorImports = (content, creatorsByClient) => {
     const sourceFile = createSourceFile(content);
@@ -311,7 +478,7 @@ const generateNewQueryCreator = (creator) => {
     const typeParameter = getTypeParameter(creator);
     const options = Array.from(creator.httpOptions.entries()).map(([key, value]) => `${key}: ${value}`);
     const optionsBlock = options.length > 0 ? `, {\n  ${options.join(',\n  ')}\n}` : '';
-    return `export const ${creator.name} = ${creatorFunction}${typeParameter}(${creator.route}${optionsBlock});`;
+    return `${creatorFunction}${typeParameter}(${creator.route}${optionsBlock})`;
 };
 const getTypeParameter = (creator) => {
     if (creator.typeArgs && (creator.typeBody || creator.typeResponse)) {
@@ -339,10 +506,12 @@ const getTypeParameter = (creator) => {
     }
     return '';
 };
-const generateLegacyWrapper = (creator) => {
-    return `export const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ creator: ${creator.name} });`;
+const generateLegacyWrapper = (creator, exportPrefix) => {
+    // `name` is what lets a `prepare()` called outside an injection context name itself in the error
+    // instead of surfacing as a bare NG0203.
+    return `/**\n * ${legacyQueryDeprecationTag(creator.name)}\n */\n${exportPrefix}const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ name: '${toLegacyName(creator.name)}', creator: ${creator.name} });`;
 };
-const createAuthProviders = (tree, authProvidersNeeded, report) => {
+const createAuthProviders = ({ tree, authProvidersNeeded, report, v2Configs, creatorToClient, }) => {
     const createdProviders = [];
     authProvidersNeeded.forEach((filePath, clientName) => {
         const content = tree.read(filePath, 'utf-8');
@@ -353,19 +522,46 @@ const createAuthProviders = (tree, authProvidersNeeded, report) => {
         if (content.includes(`export const ${authProviderName} = createBearerAuthProvider(`)) {
             return;
         }
-        const nextContent = generateSecureQueryCreators(addAuthProviderToFile(content, clientName), clientName);
+        // Match on the refresh creator: it is the one thing a v2 provider config always names, and it
+        // belongs to exactly one client.
+        const v2Config = v2Configs.find((candidate) => candidate.refreshCreatorName && creatorToClient.get(candidate.refreshCreatorName) === clientName);
+        const body = renderAuthProviderBody(v2Config);
+        const nextContent = generateSecureQueryCreators(addAuthProviderToFile(content, clientName, body), clientName);
         if (nextContent === content) {
             return;
         }
         tree.write(filePath, nextContent);
         createdProviders.push(filePath);
-        report.addFollowUp({
-            title: `Configure auth queries for ${authProviderName}`,
-            summary: `The migration created ${authProviderName} with an empty \`queries\` array because it cannot infer login or refresh builders safely.`,
-            action: 'Add authQuery/tokenRefreshQuery builders, verify token extraction, and remove the placeholder empty array once the provider is configured.',
+        if (body.isScaffolded) {
+            report.addFollowUp({
+                title: `Finish the scaffolded auth provider ${authProviderName}`,
+                summary: `${authProviderName} was scaffolded from the v2 BearerAuthProvider at ${v2Config?.filePath}:${v2Config?.line}. The refresh query and cookie config carried over; the adapters were copied verbatim and their parameter shapes changed between v2 and v3.`,
+                action: 'Resolve the TODO(query-v3) comments in the generated provider, add the login query via withAuthenticationQuery, and delete the v2 provider once the app logs in again.',
+                locations: [{ filePath }, ...(v2Config ? [{ filePath: v2Config.filePath, line: v2Config.line }] : [])],
+                source: 'legacy-query-creator-migration',
+                dedupeKey: `auth-provider:${filePath}:${authProviderName}`,
+            });
+        }
+        else {
+            report.addFollowUp({
+                title: `Configure auth queries for ${authProviderName}`,
+                summary: `The migration created ${authProviderName} with an empty \`queries\` array because no v2 BearerAuthProvider config could be matched to this client.`,
+                action: 'Add authQuery/tokenRefreshQuery builders, verify token extraction, and remove the placeholder empty array once the provider is configured.',
+                locations: [{ filePath }],
+                source: 'legacy-query-creator-migration',
+                dedupeKey: `auth-provider:${filePath}:${authProviderName}`,
+            });
+        }
+        // The generated layout only works if the auth queries live next to the provider: the provider
+        // needs the login/refresh creators, and the secure creators need the provider. Leaving them in
+        // an `auth.queries.ts` that imports the client's `post` creator closes the loop.
+        report.addManualReview({
+            title: `Keep the auth queries in ${filePath}`,
+            summary: `${authProviderName} needs the login and refresh creators, and the secure creators below it need the provider. If those creators stay in a separate auth queries file that imports this client, the two files form an import cycle.`,
+            action: `Move the login/refresh creators into ${filePath} above the provider, and have the auth queries file import them back for its legacy* wrappers.`,
             locations: [{ filePath }],
             source: 'legacy-query-creator-migration',
-            dedupeKey: `auth-provider:${filePath}:${authProviderName}`,
+            dedupeKey: `auth-provider-cycle:${filePath}`,
         });
     });
     if (createdProviders.length > 0) {
@@ -373,8 +569,8 @@ const createAuthProviders = (tree, authProvidersNeeded, report) => {
         createdProviders.forEach((filePath) => console.log(`   - ${filePath}`));
     }
 };
-const addAuthProviderToFile = (content, clientName) => {
-    const nextContent = ensureImportFromQuery(content, ['createBearerAuthProvider']);
+const addAuthProviderToFile = (content, clientName, body) => {
+    const nextContent = ensureImportFromEthleteCore(ensureImportFromQuery(content, ['createBearerAuthProvider', ...body.importsNeeded]), ['toInjectFn', 'toProvideFn']);
     const sourceFile = createSourceFile(nextContent);
     const configName = ensureConfigSuffix(clientName);
     const configPosition = findVariableStatementEnd(sourceFile, configName, 'createQueryClient');
@@ -388,10 +584,12 @@ const addAuthProviderToFile = (content, clientName) => {
         `export const ${authProviderName} = createBearerAuthProvider({`,
         `  name: '${clientName}',`,
         `  queryClientRef: ${configName},`,
-        `  queries: [],`,
+        body.queries,
+        ...(body.features ? [body.features] : []),
         '});',
         '',
-        `export const [provide${capitalizedClientName}AuthProvider, inject${capitalizedClientName}AuthProvider] = ${authProviderName};`,
+        `export const provide${capitalizedClientName}AuthProvider = toProvideFn(${authProviderName});`,
+        `export const inject${capitalizedClientName}AuthProvider = toInjectFn(${authProviderName});`,
     ].join('\n');
     return nextContent.slice(0, configPosition) + authProviderBlock + nextContent.slice(configPosition);
 };
@@ -473,117 +671,4 @@ const findLegacyWrappers = (content) => {
     visit(sourceFile);
     return wrappers;
 };
-const updateLegacyCreatorImports = (content, legacyCreators) => {
-    const sourceFile = createSourceFile(content);
-    const replacements = [];
-    const visit = (node) => {
-        if (ts.isImportDeclaration(node) &&
-            node.importClause?.namedBindings &&
-            ts.isNamedImports(node.importClause.namedBindings)) {
-            const nextElements = node.importClause.namedBindings.elements.map((element) => {
-                const importedName = element.propertyName ? element.propertyName.text : element.name.text;
-                const legacyName = legacyCreators.get(importedName);
-                return legacyName ?? element.getText(sourceFile);
-            });
-            const hasChanges = node.importClause.namedBindings.elements.some((element) => {
-                const importedName = element.propertyName ? element.propertyName.text : element.name.text;
-                return legacyCreators.has(importedName);
-            });
-            if (hasChanges) {
-                replacements.push({
-                    start: node.getStart(sourceFile),
-                    end: node.getEnd(),
-                    replacement: `import { ${nextElements.join(', ')} } from '${node.moduleSpecifier.text}';`,
-                });
-            }
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(sourceFile);
-    let result = content;
-    replacements.sort((left, right) => right.start - left.start);
-    replacements.forEach(({ start, end, replacement }) => {
-        result = result.slice(0, start) + replacement + result.slice(end);
-    });
-    return result;
-};
-const updateLegacyCreatorUsages = (content, legacyCreators) => {
-    const sourceFile = createSourceFile(content);
-    const replacements = [];
-    const visit = (node) => {
-        if (ts.isObjectLiteralExpression(node)) {
-            node.properties.forEach((property) => {
-                if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) {
-                    const nextName = legacyCreators.get(property.initializer.text);
-                    if (nextName) {
-                        replacements.push({
-                            start: property.initializer.getStart(sourceFile),
-                            end: property.initializer.getEnd(),
-                            replacement: nextName,
-                        });
-                    }
-                }
-                if (ts.isShorthandPropertyAssignment(property) && legacyCreators.has(property.name.text)) {
-                    replacements.push({
-                        start: property.getStart(sourceFile),
-                        end: property.getEnd(),
-                        replacement: `${property.name.text}: ${legacyCreators.get(property.name.text)}`,
-                    });
-                }
-            });
-        }
-        if (ts.isIdentifier(node) && legacyCreators.has(node.text)) {
-            const parent = node.parent;
-            if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isPropertyAssignment(parent) && (parent.name === node || parent.initializer === node)) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isVariableDeclaration(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isImportSpecifier(parent)) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isFunctionDeclaration(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isMethodDeclaration(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isParameter(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            if (ts.isPropertyDeclaration(parent) && parent.name === node) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            replacements.push({
-                start: node.getStart(sourceFile),
-                end: node.getEnd(),
-                replacement: legacyCreators.get(node.text),
-            });
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(sourceFile);
-    let result = content;
-    replacements.sort((left, right) => right.start - left.start);
-    replacements.forEach(({ start, end, replacement }) => {
-        result = result.slice(0, start) + replacement + result.slice(end);
-    });
-    return result;
-};
 //# sourceMappingURL=legacy-query-creator-migration.js.map

package/generators/migrate-to-query-v3/migration-scope.js

@@ -0,0 +1,38 @@
+import { getProjects, visitNotIgnoredFiles } from '@nx/devkit';
+const stripTrailingSlash = (value) => (value.endsWith('/') ? value.slice(0, -1) : value);
+/**
+ * Limits the migration to a set of projects or paths.
+ *
+ * Rewriting every app in a monorepo in one run is rarely how adoption actually goes, and a 300-file
+ * diff is not reviewable. Note the one coupling that cannot be split: a query client and the
+ * creators built on it have to be migrated together, because the creators are rewritten in terms of
+ * the client's generated `xGet` / `xPostSecure` helpers.
+ */
+export const createMigrationScope = (tree, options) => {
+    const roots = [];
+    for (const projectName of options.projects ?? []) {
+        const project = getProjects(tree).get(projectName);
+        if (!project) {
+            throw new Error(`Unknown project "${projectName}". Pass names as they appear in \`nx show projects\`, or use --include with a path prefix.`);
+        }
+        roots.push(stripTrailingSlash(project.root));
+    }
+    for (const includePath of options.include ?? []) {
+        roots.push(stripTrailingSlash(includePath));
+    }
+    if (roots.length === 0) {
+        return {
+            visit: (targetTree, callback) => visitNotIgnoredFiles(targetTree, '', callback),
+            describe: () => 'the whole workspace',
+        };
+    }
+    return {
+        visit: (targetTree, callback) => {
+            for (const root of roots) {
+                visitNotIgnoredFiles(targetTree, root, callback);
+            }
+        },
+        describe: () => roots.join(', '),
+    };
+};
+//# sourceMappingURL=migration-scope.js.map

package/generators/migrate-to-query-v3/migration.js

@@ -1,26 +1,34 @@
 import { formatFiles } from '@nx/devkit';
-import { migrateEmptyPrepareCalls, removeDevtoolsUsage, replaceAnyQueryWithLegacy } from './cleanup-migration.js';
+import { migrateDevtoolsUsage, migrateEmptyPrepareCalls, replaceAnyQueryWithLegacy } from './cleanup-migration.js';
+import { reportDefaultHeaderUsages, reportMissingHttpClientProviders } from './http-client-check.js';
 import { migrateLegacyPrepareCalls } from './legacy-prepare-migration.js';
 import { createNewQueryCreators, updateLegacyCreatorImportsAndUsages } from './legacy-query-creator-migration.js';
+import { createMigrationScope } from './migration-scope.js';
 import { generateProviderAliases, generateQueryCreators, migrateQueryClients, updateImportsAcrossWorkspace, } from './query-client-migration.js';
 import { QueryV3MigrationReport } from './report.js';
 export default async function migrate(tree, schema) {
     console.log('\n🔄 Starting query v3 migration...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
     const report = new QueryV3MigrationReport();
-    const { queryClientFiles, variableRenames } = migrateQueryClients(tree, report);
+    const { queryClientFiles, variableRenames } = migrateQueryClients(tree, report, scope);
     if (queryClientFiles.size > 0) {
         generateProviderAliases(tree, queryClientFiles);
         generateQueryCreators(tree, queryClientFiles);
-        createNewQueryCreators(tree, queryClientFiles, report);
-        updateLegacyCreatorImportsAndUsages(tree);
+        createNewQueryCreators(tree, queryClientFiles, report, scope);
+        updateLegacyCreatorImportsAndUsages(tree, scope, report);
     }
     if (variableRenames.size > 0) {
-        updateImportsAcrossWorkspace(tree, variableRenames);
+        updateImportsAcrossWorkspace(tree, variableRenames, scope);
+    }
+    replaceAnyQueryWithLegacy(tree, scope);
+    migrateDevtoolsUsage(tree, scope, report);
+    migrateEmptyPrepareCalls(tree, scope);
+    migrateLegacyPrepareCalls(tree, report, scope);
+    if (queryClientFiles.size > 0) {
+        reportMissingHttpClientProviders(tree, report, scope);
+        reportDefaultHeaderUsages(tree, report, scope);
     }
-    replaceAnyQueryWithLegacy(tree);
-    removeDevtoolsUsage(tree);
-    migrateEmptyPrepareCalls(tree);
-    migrateLegacyPrepareCalls(tree, report);
     report.writeToTree(tree);
     report.printSummary();
     if (!schema.skipFormat) {