@ethlete/query 6.0.0-next.4 → 6.0.0-next.41

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

@@ -0,0 +1,41 @@
+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),
+            includes: () => true,
+            describe: () => 'the whole workspace',
+        };
+    }
+    const includes = (filePath) => roots.some((root) => filePath === root || filePath.startsWith(`${root}/`));
+    return {
+        visit: (targetTree, callback) => {
+            for (const root of roots) {
+                visitNotIgnoredFiles(targetTree, root, callback);
+            }
+        },
+        includes,
+        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) {

package/generators/migrate-to-query-v3/module-graph.js

@@ -0,0 +1,153 @@
+import * as ts from 'typescript';
+import { createSourceFile } from './shared.js';
+const MAX_BARREL_DEPTH = 8;
+const normalizePath = (path) => {
+    const segments = [];
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.join('/');
+};
+const dirName = (path) => path.slice(0, Math.max(0, path.lastIndexOf('/')));
+const readTsConfigPaths = (tree) => {
+    const paths = new Map();
+    for (const configPath of ['tsconfig.base.json', 'tsconfig.json']) {
+        const raw = tree.read(configPath, 'utf-8');
+        if (!raw)
+            continue;
+        try {
+            // tsconfig files are JSONC in practice; the TS parser is the only thing that reliably reads
+            // them, comments and trailing commas included.
+            const parsed = ts.parseConfigFileTextToJson(configPath, raw).config;
+            Object.entries(parsed?.compilerOptions?.paths ?? {}).forEach(([key, targets]) => {
+                if (!paths.has(key))
+                    paths.set(key, targets);
+            });
+        }
+        catch {
+            // A tsconfig we cannot parse just means fewer resolvable aliases, not a failed migration.
+        }
+    }
+    return paths;
+};
+/** The files a specifier could point at, most specific first. */
+const candidateFiles = (base) => [
+    base.endsWith('.ts') ? base : `${base}.ts`,
+    `${base}/index.ts`,
+    `${base}.d.ts`,
+];
+export const createModuleGraph = (tree) => {
+    const tsConfigPaths = readTsConfigPaths(tree);
+    const declaringFileCache = new Map();
+    const resolveEntryFile = (fromFile, specifier) => {
+        if (specifier.startsWith('.')) {
+            const base = normalizePath(`${dirName(fromFile)}/${specifier}`);
+            return candidateFiles(base).find((candidate) => tree.exists(candidate)) ?? null;
+        }
+        for (const [pattern, targets] of tsConfigPaths.entries()) {
+            const wildcardIndex = pattern.indexOf('*');
+            let suffix;
+            if (wildcardIndex === -1) {
+                if (pattern !== specifier)
+                    continue;
+                suffix = '';
+            }
+            else {
+                const prefix = pattern.slice(0, wildcardIndex);
+                const patternSuffix = pattern.slice(wildcardIndex + 1);
+                if (!specifier.startsWith(prefix) || !specifier.endsWith(patternSuffix))
+                    continue;
+                suffix = specifier.slice(prefix.length, specifier.length - patternSuffix.length);
+            }
+            for (const target of targets) {
+                const resolvedTarget = normalizePath(target.replace('*', suffix));
+                const candidate = candidateFiles(resolvedTarget).find((option) => tree.exists(option));
+                if (candidate)
+                    return candidate;
+            }
+        }
+        return null;
+    };
+    const declaresSymbol = (sourceFile, symbolName) => {
+        let declares = false;
+        const isExported = (node) => ts.canHaveModifiers(node) &&
+            ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+        ts.forEachChild(sourceFile, (node) => {
+            if (declares)
+                return;
+            if (ts.isVariableStatement(node) && isExported(node)) {
+                declares = node.declarationList.declarations.some((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === symbolName);
+                return;
+            }
+            if ((ts.isFunctionDeclaration(node) ||
+                ts.isClassDeclaration(node) ||
+                ts.isInterfaceDeclaration(node) ||
+                ts.isTypeAliasDeclaration(node) ||
+                ts.isEnumDeclaration(node)) &&
+                isExported(node) &&
+                node.name?.text === symbolName) {
+                declares = true;
+            }
+        });
+        return declares;
+    };
+    const findDeclaringFileIn = (entryFile, symbolName, depth, seen) => {
+        if (depth > MAX_BARREL_DEPTH || seen.has(`${entryFile}#${symbolName}`))
+            return null;
+        seen.add(`${entryFile}#${symbolName}`);
+        const content = tree.read(entryFile, 'utf-8');
+        if (!content)
+            return null;
+        const sourceFile = createSourceFile(content, entryFile);
+        if (declaresSymbol(sourceFile, symbolName))
+            return entryFile;
+        const starExports = [];
+        for (const node of sourceFile.statements) {
+            if (!ts.isExportDeclaration(node) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier)) {
+                continue;
+            }
+            const nextEntry = resolveEntryFile(entryFile, node.moduleSpecifier.text);
+            if (!nextEntry)
+                continue;
+            if (!node.exportClause) {
+                starExports.push(nextEntry);
+                continue;
+            }
+            if (!ts.isNamedExports(node.exportClause))
+                continue;
+            for (const element of node.exportClause.elements) {
+                if (element.name.text !== symbolName)
+                    continue;
+                const originalName = element.propertyName?.text ?? symbolName;
+                const found = findDeclaringFileIn(nextEntry, originalName, depth + 1, seen);
+                if (found)
+                    return found;
+            }
+        }
+        for (const starExport of starExports) {
+            const found = findDeclaringFileIn(starExport, symbolName, depth + 1, seen);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    return {
+        findDeclaringFile: (fromFile, specifier, symbolName) => {
+            const cacheKey = `${fromFile}|${specifier}|${symbolName}`;
+            const cached = declaringFileCache.get(cacheKey);
+            if (cached !== undefined)
+                return cached;
+            const entryFile = resolveEntryFile(fromFile, specifier);
+            const declaringFile = entryFile ? findDeclaringFileIn(entryFile, symbolName, 0, new Set()) : null;
+            declaringFileCache.set(cacheKey, declaringFile);
+            return declaringFile;
+        },
+    };
+};
+//# sourceMappingURL=module-graph.js.map

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

@@ -1,10 +1,9 @@
-import { visitNotIgnoredFiles } from '@nx/devkit';
 import * as ts from 'typescript';
-import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
-export const migrateQueryClients = (tree, report) => {
+import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromEthleteCore, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
+export const migrateQueryClients = (tree, report, scope) => {
     const queryClientFiles = new Map();
     const variableRenames = new Map();
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts')) {
             return;
         }
@@ -69,11 +68,11 @@ export const generateQueryCreators = (tree, queryClientFiles) => {
         generatedFiles.forEach((filePath) => console.log(`   - ${filePath}`));
     }
 };
-export const updateImportsAcrossWorkspace = (tree, renames) => {
+export const updateImportsAcrossWorkspace = (tree, renames, scope) => {
     if (renames.size === 0) {
         return;
     }
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts')) {
             return;
         }
@@ -143,6 +142,7 @@ const migrateQueryClientToConfig = ({ content, filePath, renamesOut, report }) =
                         renamesOut.set(oldVariableName, newVariableName);
                     }
                 }
+                reportDroppedClientOptions({ configArgument, sourceFile, filePath, report });
                 replacements.push({
                     start: node.getStart(sourceFile),
                     end: node.getEnd(),
@@ -241,6 +241,54 @@ const renameVariables = (content, renames) => {
     });
     return result;
 };
+/**
+ * What each v2 client option turns into, or why it has nowhere to go.
+ *
+ * Silently dropping these is how two apps here lost their default headers without a single warning.
+ * A dropped option that shows up in the report is a five-minute fix; one that doesn't is a bug
+ * report from production.
+ */
+const DROPPED_CLIENT_OPTIONS = {
+    'request.autoRefreshQueriesOnWindowFocus': 'No direct equivalent. Re-run the affected queries yourself - `withAutoRefresh({ onSignalChanges: [windowFocusSignal] })` per query, or `injectMyClient().refreshQueriesInUse()` from a focus listener.',
+    'request.enableSmartPolling': 'No direct equivalent. `withPolling({ interval })` polls unconditionally; pause it yourself when the tab is hidden if that matters.',
+    'logging.preparedQuerySubscriptions': 'Removed. Use the v3 devtools (`provideQueryDevtools()`) or `withLogging({ logFn })` on the queries you want to trace.',
+    'logging.queryStateChanges': 'Removed. Use the v3 devtools (`provideQueryDevtools()`) or `withLogging({ logFn })` on the queries you want to trace.',
+    'request.autoRefreshOn': 'No direct equivalent. Re-run the affected queries yourself with `withAutoRefresh` or `refreshQueriesInUse()`.',
+};
+const reportDroppedClientOptions = ({ configArgument, sourceFile, filePath, report, }) => {
+    const migrated = new Set(['baseRoute', 'queryParams', 'cacheAdapter', 'retryFn', 'request', 'logging']);
+    const raise = (optionPath, node) => {
+        report.addWarning({
+            title: `Reconfigure dropped query client option "${optionPath}"`,
+            summary: `The v2 client option \`${optionPath}\` has no place in \`createQueryClient\` and was dropped by the migration.`,
+            action: DROPPED_CLIENT_OPTIONS[optionPath] ?? 'Check whether the behaviour is still needed and reimplement it.',
+            locations: [{ filePath, line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 }],
+            source: 'query-client-migration',
+            dedupeKey: `dropped-client-option:${filePath}:${optionPath}`,
+        });
+    };
+    configArgument.properties.forEach((property) => {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
+            return;
+        }
+        const name = property.name.text;
+        if ((name === 'request' || name === 'logging') && ts.isObjectLiteralExpression(property.initializer)) {
+            property.initializer.properties.forEach((nested) => {
+                if (!ts.isPropertyAssignment(nested) || !ts.isIdentifier(nested.name)) {
+                    return;
+                }
+                if (name === 'request' && ['queryParams', 'cacheAdapter', 'retryFn'].includes(nested.name.text)) {
+                    return;
+                }
+                raise(`${name}.${nested.name.text}`, nested);
+            });
+            return;
+        }
+        if (!migrated.has(name)) {
+            raise(name, property);
+        }
+    });
+};
 const migrateConfigObject = (configArgument, node, sourceFile) => {
     const variableName = getVariableNameForQueryClient(node);
     const nextConfig = [];
@@ -326,19 +374,20 @@ const addProviderAliasesToFile = (content, configNames) => {
             return;
         }
         const { injectName, provideName } = getProviderAliasNames(variableName);
-        if (result.includes(`export const [${provideName}, ${injectName}] = ${variableName};`)) {
+        if (result.includes(`export const ${injectName} = toInjectFn(${variableName});`)) {
             return;
         }
         insertions.push({
             position,
-            text: `\n\nexport const [${provideName}, ${injectName}] = ${variableName};`,
+            text: `\n\nexport const ${provideName} = toProvideFn(${variableName});` +
+                `\nexport const ${injectName} = toInjectFn(${variableName});`,
         });
     });
     insertions.sort((left, right) => right.position - left.position);
     insertions.forEach(({ position, text }) => {
         result = result.slice(0, position) + text + result.slice(position);
     });
-    return result;
+    return insertions.length > 0 ? ensureImportFromEthleteCore(result, ['toInjectFn', 'toProvideFn']) : result;
 };
 const getProviderAliasNames = (configVariableName) => {
     const baseName = configVariableName.replace(/Config$/, '');

package/generators/migrate-to-query-v3/rename-symbols.js

@@ -0,0 +1,193 @@
+import * as ts from 'typescript';
+import { createSourceFile } from './shared.js';
+/**
+ * Whether an identifier is a *name* rather than a *reference* - a declaration, a property key, the
+ * right-hand side of a member access. Renaming those is what turned `PeopleDetailDataSource.getPerson`
+ * and the `postLogin` property of a config type into `legacy…` during the first migration run.
+ */
+const isNamePosition = (node) => {
+    const parent = node.parent;
+    if (!parent)
+        return false;
+    // `foo.bar` / `Foo.Bar` - the part after the dot is never the imported binding.
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node)
+        return true;
+    if (ts.isQualifiedName(parent) && parent.right === node)
+        return true;
+    // Object literal / type member keys, enum members, JSX-ish attribute names.
+    if (ts.isPropertyAssignment(parent) && parent.name === node)
+        return true;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === node)
+        return true;
+    if (ts.isPropertySignature(parent) && parent.name === node)
+        return true;
+    if (ts.isMethodSignature(parent) && parent.name === node)
+        return true;
+    if (ts.isEnumMember(parent) && parent.name === node)
+        return true;
+    if (ts.isBindingElement(parent) && parent.propertyName === node)
+        return true;
+    // Declarations of any kind.
+    if (ts.isVariableDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isFunctionDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isClassDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isInterfaceDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isTypeAliasDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isEnumDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isModuleDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isMethodDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isPropertyDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isGetAccessorDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isSetAccessorDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isParameter(parent) && parent.name === node)
+        return true;
+    if (ts.isTypeParameterDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isLabeledStatement(parent) && parent.label === node)
+        return true;
+    // Import / export clauses are rewritten by the caller, never by the reference pass.
+    if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent))
+        return true;
+    if (ts.isImportClause(parent) || ts.isNamespaceImport(parent))
+        return true;
+    return false;
+};
+/** Every name the file declares itself - a local by the same name means the import is shadowed. */
+const collectLocalDeclarations = (sourceFile) => {
+    const declared = new Set();
+    const add = (name) => {
+        if (name && ts.isIdentifier(name))
+            declared.add(name.text);
+    };
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node))
+            add(node.name);
+        if (ts.isFunctionDeclaration(node))
+            add(node.name);
+        if (ts.isClassDeclaration(node))
+            add(node.name);
+        if (ts.isInterfaceDeclaration(node))
+            add(node.name);
+        if (ts.isTypeAliasDeclaration(node))
+            add(node.name);
+        if (ts.isEnumDeclaration(node))
+            add(node.name);
+        if (ts.isParameter(node))
+            add(node.name);
+        if (ts.isBindingElement(node))
+            add(node.name);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return declared;
+};
+/**
+ * Renames references to imported bindings, and only those.
+ *
+ * `renames` maps a *local binding name* to its new name. The caller is responsible for having
+ * verified that the binding really is the symbol being migrated (see `ModuleGraph`); this pass only
+ * makes sure the rewrite lands on references rather than on same-named properties, declarations or
+ * type members. A name the file also declares locally is skipped entirely and reported back, since
+ * a rename there would silently change which value the code reads.
+ */
+export const renameImportedReferences = (content, renames) => {
+    if (renames.size === 0)
+        return { content, shadowed: [] };
+    const sourceFile = createSourceFile(content);
+    const declaredLocally = collectLocalDeclarations(sourceFile);
+    const shadowed = Array.from(renames.keys()).filter((name) => declaredLocally.has(name));
+    const applicable = new Map(Array.from(renames.entries()).filter(([name]) => !declaredLocally.has(name)));
+    if (applicable.size === 0)
+        return { content, shadowed };
+    const replacements = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node)) {
+            const nextName = applicable.get(node.text);
+            if (nextName && !isNamePosition(node)) {
+                replacements.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement: nextName });
+            }
+        }
+        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 { content: result, shadowed };
+};
+/**
+ * Drops named imports whose local name no longer appears anywhere else in the file.
+ *
+ * The migration rewrites away the constructs that needed `def`, `AnyLegacyQueryCreator` and friends;
+ * leaving the imports behind turns every touched file into a lint error, and `formatFiles` runs in
+ * the same generator invocation so they land that way. Identifiers inside template strings count as
+ * usage too - a component referenced only from an inline template must not be pruned.
+ */
+export const pruneUnusedNamedImports = (content, moduleSpecifiers) => {
+    const sourceFile = createSourceFile(content);
+    const used = new Set();
+    const addWordsFrom = (text) => {
+        for (const word of text.match(/[A-Za-z_$][\w$]*/g) ?? []) {
+            used.add(word);
+        }
+    };
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && !ts.isImportSpecifier(node.parent) && !ts.isImportClause(node.parent)) {
+            used.add(node.text);
+        }
+        // A symbol referenced only from an inline template or a `styleUrl`-style string is still used.
+        if (ts.isStringLiteralLike(node) && !ts.isImportDeclaration(node.parent)) {
+            addWordsFrom(node.text);
+        }
+        if (ts.isTemplateLiteralToken(node)) {
+            addWordsFrom(node.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const replacements = [];
+    for (const node of sourceFile.statements) {
+        if (!ts.isImportDeclaration(node) ||
+            !ts.isStringLiteral(node.moduleSpecifier) ||
+            (moduleSpecifiers !== 'all' && !moduleSpecifiers.includes(node.moduleSpecifier.text)) ||
+            !node.importClause?.namedBindings ||
+            !ts.isNamedImports(node.importClause.namedBindings)) {
+            continue;
+        }
+        const kept = node.importClause.namedBindings.elements.filter((element) => used.has(element.name.text));
+        if (kept.length === node.importClause.namedBindings.elements.length)
+            continue;
+        const hasDefaultImport = !!node.importClause.name;
+        if (kept.length === 0 && !hasDefaultImport) {
+            const end = content[node.getEnd()] === '\n' ? node.getEnd() + 1 : node.getEnd();
+            replacements.push({ start: node.getStart(sourceFile), end, replacement: '' });
+            continue;
+        }
+        const defaultPart = hasDefaultImport ? `${node.importClause.name.text}, ` : '';
+        replacements.push({
+            start: node.getStart(sourceFile),
+            end: node.getEnd(),
+            replacement: `import ${defaultPart}{ ${kept.map((element) => element.getText(sourceFile)).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);
+    });
+    return result;
+};
+//# sourceMappingURL=rename-symbols.js.map

package/generators/migrate-to-query-v3/schema.json

@@ -4,6 +4,18 @@
   "title": "Migrate to Query v3",
   "type": "object",
   "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace. Use this to adopt v3 one app or library at a time instead of rewriting the whole monorepo in one run - but keep a query client and the creators built from it in the same run, since they are migrated together.",
+      "alias": "project"
+    },
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path prefixes to migrate, relative to the workspace root (e.g. 'libs/queries'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
     "skipFormat": {
       "type": "boolean",
       "description": "Skip formatting files after migration",

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

@@ -55,6 +55,8 @@ export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier })
 };
 export const ensureImportFromQuery = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@ethlete/query' });
 export const ensureAngularCoreImports = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@angular/core' });
+/** `toProvideFn` / `toInjectFn` - the provider-definition extractors every generated ref pair needs. */
+export const ensureImportFromEthleteCore = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@ethlete/core' });
 export const getVariableStatementEnd = (sourceFile, variableName, initializerName) => {
     let variableStatementEnd;
     const visit = (node) => {
@@ -94,4 +96,47 @@ export const getLineNumber = (node, sourceFile) => {
     return line + 1;
 };
 export const getLineNumberFromPosition = (content, position) => content.slice(0, position).split('\n').length;
+const MIGRATION_GUIDE_URL = 'https://ethlete-sdk-docs.web.app/query/migrating-from-v2';
+/**
+ * The tag every `createLegacyQueryCreator(…)` wrapper carries. The wrapper is a migration
+ * scaffold, so marking it is what turns "which call sites are still on v2" from a grep into
+ * strikethrough in the editor.
+ */
+export const legacyQueryDeprecationTag = (creatorName) => `@deprecated Legacy (v2) query wrapper. Migrate the call sites to ${creatorName ? `\`${creatorName}\`` : 'the query creator it wraps'} and delete this wrapper - see ${MIGRATION_GUIDE_URL}.`;
+/**
+ * Adds a tag to `node`'s JSDoc, creating the block when there is none. Returns `null` when the
+ * tag is already there, so a caller can tell "nothing to do" from "rewritten".
+ *
+ * Leading `//` comments stay glued to the node - an `eslint-disable-next-line` only works from
+ * the line directly above.
+ */
+export const addJsDocTag = (content, sourceFile, node, tag) => {
+    const jsDocs = node.jsDoc ?? [];
+    const existing = jsDocs[jsDocs.length - 1];
+    const tagName = /^@\w+/.exec(tag)?.[0];
+    if (existing && tagName && new RegExp(`${tagName}\\b`).test(existing.getText())) {
+        return null;
+    }
+    if (existing) {
+        const start = existing.getStart(sourceFile);
+        const indentation = ' '.repeat(sourceFile.getLineAndCharacterOfPosition(start).character);
+        const text = existing.getText();
+        const body = text.slice(0, text.lastIndexOf('*/')).replace(/\s+$/, '');
+        // A one-line `/** … */` has to become a block before a tag line can be appended to it.
+        const opened = body.includes('\n') ? body : `/**\n${indentation} * ${body.slice(3).trim()}`;
+        return (content.slice(0, start) +
+            `${opened}\n${indentation} *\n${indentation} * ${tag}\n${indentation} */` +
+            content.slice(existing.getEnd()));
+    }
+    let start = node.getStart(sourceFile, false);
+    for (const comment of (ts.getLeadingCommentRanges(content, node.getFullStart()) ?? []).reverse()) {
+        if (comment.kind !== ts.SyntaxKind.SingleLineCommentTrivia)
+            break;
+        if (!/^\n[ \t]*$/.test(content.slice(comment.end, start)))
+            break;
+        start = comment.pos;
+    }
+    const indentation = ' '.repeat(sourceFile.getLineAndCharacterOfPosition(start).character);
+    return (content.slice(0, start) + `/**\n${indentation} * ${tag}\n${indentation} */\n${indentation}` + content.slice(start));
+};
 //# sourceMappingURL=shared.js.map

package/generators/prep-for-query-v3/migration.js

@@ -58,7 +58,7 @@ function renameConflictingSymbols(tree) {
     // Log statistics
     if (updatedFiles.length > 0) {
         console.log(`\n📊 Renamed symbols in ${updatedFiles.length} files:`);
-        const hasRenames = Array.from(symbolUsageCounts.entries()).filter(([_, count]) => count > 0);
+        const hasRenames = Array.from(symbolUsageCounts.entries()).filter(([, count]) => count > 0);
         if (hasRenames.length > 0) {
             console.log('\n   Symbol usage counts:');
             hasRenames.forEach(([symbol, count]) => {
@@ -123,7 +123,7 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     }
     visit(sourceFile);
     // Update imports in @ethlete/query import declarations
-    const importReplacements = updateImports(sourceFile, content);
+    const importReplacements = updateImports(sourceFile);
     replacements.push(...importReplacements);
     // Count usages
     replacements.forEach((r) => {
@@ -138,7 +138,7 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     }
     return result;
 }
-function updateImports(sourceFile, content) {
+function updateImports(sourceFile) {
     const replacements = [];
     function visit(node) {
         if (ts.isImportDeclaration(node)) {