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

package/generators/migrate-query-opt-in-features/report.js

@@ -0,0 +1,143 @@
+export const QUERY_OPT_IN_FEATURES_REPORT_PATH = 'query-opt-in-features-migration-tasks.md';
+export const MIGRATION_TASK_KIND = {
+    WARNING: 'warning',
+    MANUAL_REVIEW: 'manual-review',
+    FOLLOW_UP: 'follow-up',
+};
+const renderTaskLocations = (locations) => {
+    if (locations.length === 0) {
+        return '- None recorded';
+    }
+    return locations.map((location) => `- ${location.filePath}${location.line ? `:${location.line}` : ''}`).join('\n');
+};
+export class QueryOptInFeaturesMigrationReport {
+    constructor() {
+        this.tasks = [];
+    }
+    addTask(input) {
+        const dedupeKey = input.dedupeKey ?? `${input.kind}:${input.title}:${input.summary}:${input.action}`;
+        const existing = this.tasks.find((task) => task.dedupeKey === dedupeKey);
+        if (existing) {
+            existing.locations.push(...(input.locations ?? []));
+            return;
+        }
+        this.tasks.push({
+            id: `QOF-${String(this.tasks.length + 1).padStart(3, '0')}`,
+            kind: input.kind,
+            title: input.title,
+            summary: input.summary,
+            action: input.action,
+            locations: input.locations ?? [],
+            source: input.source,
+            dedupeKey,
+        });
+    }
+    addWarning(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.WARNING });
+    }
+    addManualReview(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.MANUAL_REVIEW });
+    }
+    addFollowUp(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.FOLLOW_UP });
+    }
+    printSummary() {
+        if (this.tasks.length === 0) {
+            return;
+        }
+        console.warn(`\n⚠️ Generated ${this.tasks.length} follow-up task${this.tasks.length === 1 ? '' : 's'}:`);
+        this.tasks.forEach((task) => {
+            const locations = task.locations
+                .map((location) => `${location.filePath}${location.line ? `:${location.line}` : ''}`)
+                .join(', ');
+            console.warn(` - ${task.id} [${task.kind}] ${task.title}${locations ? ` (${locations})` : ''}`);
+        });
+        console.warn(`\n📄 See ${QUERY_OPT_IN_FEATURES_REPORT_PATH} for the AI-ready follow-up list.`);
+    }
+    writeToTree(tree) {
+        tree.write(QUERY_OPT_IN_FEATURES_REPORT_PATH, renderMigrationReportMarkdown(this.tasks));
+    }
+}
+export const renderMigrationReportMarkdown = (tasks) => {
+    const header = [
+        '# Query Opt-In Features Migration Follow-Up',
+        '',
+        'This file is generated by the `migrate-query-opt-in-features` generator.',
+        '',
+        '## Context',
+        '',
+        'Two things that used to be on by default are now opt-in features:',
+        '',
+        '- error-response parsing (HTML error pages, Symfony / class-validator violation lists) and the',
+        '  default retry policy, now `withEthleteApiErrors()` on `createQueryClient`,',
+        '- bearer-auth multi-tab sync and leader election, now `withBearerAuthMultiTabSync()` on',
+        '  `createBearerAuthProvider` (the `multiTabSync` config option is gone).',
+        '',
+        'The codemod is **behavior preserving**: it adds the features every call site used to get for free.',
+        'That is rarely what an app wants long term — an API that never answers with an HTML error page, or',
+        'an app that is only ever open in one tab, ships that code for nothing. Review each added feature',
+        'and delete the ones you do not need; `withEthleteApiErrors()` in particular splits into',
+        '`withHtmlErrorParsing()`, `withSymfonyErrors()` and `withDefaultRetry()`.',
+        '',
+        '## AI Instructions',
+        '',
+        '1. Re-read the referenced files before changing anything. The migration output is only a starting point.',
+        '2. Prefer minimal fixes that align with the current runtime APIs in `@ethlete/query`.',
+        '3. Update or remove a task only after the code and tests confirm that it is resolved.',
+        '4. If a task is still ambiguous after inspection, keep it open and append a short note instead of guessing.',
+        '',
+        '## Task Format',
+        '',
+        '- `Status`: always treat generated tasks as `open` until verified manually or by tests.',
+        '- `Kind`: `warning`, `manual-review`, or `follow-up`.',
+        '- `Source`: which migration phase raised the task.',
+        '',
+    ].join('\n');
+    if (tasks.length === 0) {
+        return `${header}## Tasks\n\nNo open follow-up tasks were recorded during this migration run.\n`;
+    }
+    const tasksSection = tasks
+        .map((task) => [
+        `### ${task.id} - ${task.title}`,
+        '',
+        '- Status: open',
+        `- Kind: ${task.kind}`,
+        `- Source: ${task.source}`,
+        `- Summary: ${task.summary}`,
+        `- Suggested action: ${task.action}`,
+        '- Locations:',
+        renderTaskLocations(task.locations),
+        '',
+    ].join('\n'))
+        .join('');
+    const machineSection = [
+        '## Machine Summary',
+        '',
+        '```yaml',
+        'tasks:',
+        ...tasks.flatMap((task) => {
+            const nestedLocations = task.locations.flatMap((location) => {
+                const lines = [`      - filePath: ${location.filePath}`];
+                if (location.line) {
+                    lines.push(`        line: ${location.line}`);
+                }
+                return lines;
+            });
+            return [
+                `  - id: ${task.id}`,
+                `    status: open`,
+                `    kind: ${task.kind}`,
+                `    source: ${task.source}`,
+                `    title: ${task.title}`,
+                `    summary: ${task.summary}`,
+                `    action: ${task.action}`,
+                `    locations:`,
+                ...(nestedLocations.length > 0 ? nestedLocations : ['      []']),
+            ];
+        }),
+        '```',
+        '',
+    ].join('\n');
+    return `${header}## Tasks\n\n${tasksSection}${machineSection}`;
+};
+//# sourceMappingURL=report.js.map

package/generators/migrate-query-opt-in-features/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-query-opt-in-features",
+  "title": "Migrate query clients and auth providers to opt-in features",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace.",
+      "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"
+    },
+    "reportOnly": {
+      "type": "boolean",
+      "description": "Only list the affected call sites in the report file, without changing any code.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators/migrate-to-query-v3/auth-provider-scaffold.js

@@ -0,0 +1,131 @@
+import * as ts from 'typescript';
+import { createSourceFile } from './shared.js';
+const REFRESH_CONFIG_KEYS = new Set([
+    'queryCreator',
+    'responseAdapter',
+    'requestArgsAdapter',
+    'cookieName',
+    'cookieDomain',
+    'cookieExpiresInDays',
+    'expiresInPropertyName',
+]);
+export const collectV2BearerAuthConfigs = (tree, scope) => {
+    const configs = [];
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
+            return;
+        }
+        const content = tree.read(filePath, 'utf-8');
+        if (!content || !content.includes('V2BearerAuthProvider')) {
+            return;
+        }
+        const sourceFile = createSourceFile(content, filePath);
+        const visit = (node) => {
+            if (ts.isNewExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                node.expression.text === 'V2BearerAuthProvider') {
+                const configArgument = node.arguments?.[0];
+                if (configArgument && ts.isObjectLiteralExpression(configArgument)) {
+                    configs.push(readConfig(configArgument, sourceFile, filePath, node));
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+    });
+    return configs;
+};
+const readConfig = (configArgument, sourceFile, filePath, node) => {
+    const config = {
+        filePath,
+        line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+    };
+    const refreshConfig = configArgument.properties.find((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'refreshConfig');
+    if (!refreshConfig ||
+        !ts.isPropertyAssignment(refreshConfig) ||
+        !ts.isObjectLiteralExpression(refreshConfig.initializer)) {
+        return config;
+    }
+    refreshConfig.initializer.properties.forEach((property) => {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
+            return;
+        }
+        const key = property.name.text;
+        if (!REFRESH_CONFIG_KEYS.has(key)) {
+            return;
+        }
+        const text = property.initializer.getText(sourceFile);
+        if (key === 'queryCreator') {
+            if (ts.isIdentifier(property.initializer)) {
+                config.refreshCreatorName = property.initializer.text;
+            }
+            return;
+        }
+        config[key] = text;
+    });
+    return config;
+};
+const REFRESH_QUERY_KEY = 'tokenRefresh';
+/**
+ * Renders the `queries` / `features` arguments of a v3 provider from a v2 config.
+ *
+ * The mapping is close to 1:1 - `queryCreator` → `withRefreshQuery`, `responseAdapter` →
+ * `extractTokens`, `cookieName` → `withPersistentAuth({ cookie })` - but the adapters are copied
+ * verbatim from v2 and their parameter shapes differ, so each one is emitted with a TODO rather
+ * than presented as finished.
+ */
+export const renderAuthProviderBody = (config) => {
+    if (!config?.refreshCreatorName) {
+        return {
+            queries: '  queries: [],',
+            features: '',
+            importsNeeded: [],
+            isScaffolded: false,
+        };
+    }
+    const refreshEntries = [`      queryCreator: ${config.refreshCreatorName},`];
+    if (config.responseAdapter) {
+        refreshEntries.push(`      // TODO(query-v3): v2 responseAdapter. It must return { accessToken, refreshToken } - v2 returned { token, refreshToken }.`, `      extractTokens: ${config.responseAdapter},`);
+    }
+    if (config.requestArgsAdapter) {
+        refreshEntries.push(`      // TODO(query-v3): v2 requestArgsAdapter took { token, refreshToken }; buildArgs takes the refresh token alone.`, `      buildArgs: ${config.requestArgsAdapter},`);
+    }
+    if (config.expiresInPropertyName) {
+        refreshEntries.push(`      expiresInPropertyName: ${config.expiresInPropertyName},`);
+    }
+    const queries = [
+        '  queries: [',
+        `    // Derived from the v2 BearerAuthProvider in ${config.filePath}:${config.line}. Verify before shipping.`,
+        `    withRefreshQuery('${REFRESH_QUERY_KEY}', {`,
+        ...refreshEntries,
+        '    }),',
+        `    // TODO(query-v3): add withAuthenticationQuery('login', { queryCreator: … }) for the login query.`,
+        '  ],',
+    ].join('\n');
+    const importsNeeded = ['withRefreshQuery'];
+    if (!config.cookieName) {
+        return { queries, features: '', importsNeeded, isScaffolded: true };
+    }
+    const cookieEntries = [`      name: ${config.cookieName},`];
+    if (config.cookieDomain)
+        cookieEntries.push(`      domain: ${config.cookieDomain},`);
+    if (config.cookieExpiresInDays)
+        cookieEntries.push(`      expiresInDays: ${config.cookieExpiresInDays},`);
+    const features = [
+        '  features: [',
+        '    withPersistentAuth({',
+        '      cookie: {',
+        ...cookieEntries,
+        '      },',
+        '      autoLogin: {',
+        `        queryKey: '${REFRESH_QUERY_KEY}',`,
+        `        // TODO(query-v3): shape the auto-login request from the cookie value.`,
+        '        buildArgs: (token) => ({ body: { refreshToken: token } }),',
+        '      },',
+        '    }),',
+        '  ],',
+    ].join('\n');
+    importsNeeded.push('withPersistentAuth');
+    return { queries, features, importsNeeded, isScaffolded: true };
+};
+//# sourceMappingURL=auth-provider-scaffold.js.map

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

@@ -1,45 +1,56 @@
-import { visitNotIgnoredFiles } from '@nx/devkit';
 import * as ts from 'typescript';
-import { createSourceFile, getLineNumberFromPosition } from './shared.js';
-export const removeDevtoolsUsage = (tree) => {
+import { createSourceFile, ensureImportFromQuery, ensureNamedImports, getLineNumberFromPosition } from './shared.js';
+/**
+ * Points existing devtools usage at the v3 components instead of deleting it.
+ *
+ * Both versions render `<et-query-devtools>`, so templates need no change at all - only the provider
+ * call and the component's import move. Stripping the markup (as this phase used to) threw away
+ * something that would have kept working, and left every migrated app without devtools until someone
+ * noticed they were gone.
+ */
+export const migrateDevtoolsUsage = (tree, scope, report) => {
     const updatedFiles = [];
-    visitNotIgnoredFiles(tree, '', (filePath) => {
-        if (!filePath.endsWith('.ts') && !filePath.endsWith('.html')) {
+    const filesNeedingComponentsPackage = [];
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts')) {
             return;
         }
         const content = tree.read(filePath, 'utf-8');
-        if (!content) {
+        if (!content ||
+            (!content.includes('provideQueryClientForDevtools') && !content.includes('QueryDevtoolsComponent'))) {
             return;
         }
-        if (filePath.endsWith('.ts')) {
-            if (!content.includes('provideQueryClientForDevtools') && !content.includes('QueryDevtoolsComponent')) {
-                return;
-            }
-            const withoutProviders = removeProvideQueryClientForDevtools(content);
-            const nextContent = removeQueryDevtoolsComponent(withoutProviders);
-            if (nextContent !== content) {
-                tree.write(filePath, nextContent);
-                updatedFiles.push(filePath);
-            }
+        const { content: nextContent, importsComponent } = migrateDevtoolsInFile(content);
+        if (nextContent === content) {
             return;
         }
-        if (!content.includes('et-query-devtools')) {
-            return;
-        }
-        const nextContent = removeDevtoolsFromHtml(content);
-        if (nextContent !== content) {
-            tree.write(filePath, nextContent);
-            updatedFiles.push(filePath);
+        tree.write(filePath, nextContent);
+        updatedFiles.push(filePath);
+        if (importsComponent) {
+            filesNeedingComponentsPackage.push(filePath);
         }
     });
-    if (updatedFiles.length > 0) {
-        console.log('\n✅ Removed legacy query devtools usage in:');
-        updatedFiles.forEach((filePath) => console.log(`   - ${filePath}`));
+    if (updatedFiles.length === 0) {
+        return;
+    }
+    console.log('\n✅ Migrated query devtools usage to v3 in:');
+    updatedFiles.forEach((filePath) => console.log(`   - ${filePath}`));
+    if (filesNeedingComponentsPackage.length > 0) {
+        // The component moved packages, which is the one part of this rewrite that can fail outside the
+        // file being edited: an app that only ever depended on `@ethlete/query` now needs `@ethlete/components`.
+        report.addManualReview({
+            title: 'Add @ethlete/components for the query devtools',
+            summary: '`QueryDevtoolsComponent` now lives in `@ethlete/components`. The imports were rewritten, but the package may not be a dependency of these projects yet.',
+            action: 'Run `yarn add @ethlete/components` where needed, then `yarn install` and re-lint the affected libs so the `@nx/dependency-checks` rule sees the new dependency.',
+            locations: filesNeedingComponentsPackage.map((filePath) => ({ filePath })),
+            source: 'cleanup-migration',
+            dedupeKey: 'devtools-components-dependency',
+        });
     }
 };
-export const replaceAnyQueryWithLegacy = (tree) => {
+export const replaceAnyQueryWithLegacy = (tree, scope) => {
     const updatedFiles = [];
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
             return;
         }
@@ -57,9 +68,9 @@ export const replaceAnyQueryWithLegacy = (tree) => {
         console.log(`\n✅ Replaced legacy AnyV2Query aliases in ${updatedFiles.length} files`);
     }
 };
-export const migrateEmptyPrepareCalls = (tree) => {
+export const migrateEmptyPrepareCalls = (tree, scope) => {
     const updatedFiles = [];
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
             return;
         }
@@ -77,42 +88,63 @@ export const migrateEmptyPrepareCalls = (tree) => {
         console.log(`\n✅ Migrated empty .prepare() calls in ${updatedFiles.length} files`);
     }
 };
-const removeProvideQueryClientForDevtools = (content) => {
-    return content
-        .replace(/,?\s*provideQueryClientForDevtools\([^)]*\)/g, '')
-        .replace(/\[\s*,/g, '[')
-        .replace(/,\s*\]/g, ']')
-        .replace(/\n\s*\n\s*\n/g, '\n\n');
+const migrateDevtoolsInFile = (content) => {
+    const importsComponent = importsFromQuery(content, 'QueryDevtoolsComponent');
+    let result = replaceDevtoolsProviderCalls(content);
+    const hasProvider = result.includes('provideQueryDevtools()');
+    result = dropLegacyDevtoolsImports(result);
+    if (hasProvider) {
+        result = ensureImportFromQuery(result, ['provideQueryDevtools']);
+    }
+    if (importsComponent) {
+        result = ensureNamedImports({
+            content: result,
+            importsNeeded: ['QueryDevtoolsComponent'],
+            moduleSpecifier: '@ethlete/components',
+        });
+    }
+    return { content: result, importsComponent };
 };
-const removeQueryDevtoolsComponent = (content) => {
-    const withoutImportsArray = removeQueryDevtoolsImportsFromMetadata(content);
-    return removeDevtoolsImports(withoutImportsArray);
+const importsFromQuery = (content, name) => {
+    const sourceFile = createSourceFile(content);
+    return sourceFile.statements.some((node) => ts.isImportDeclaration(node) &&
+        ts.isStringLiteral(node.moduleSpecifier) &&
+        node.moduleSpecifier.text === '@ethlete/query' &&
+        !!node.importClause?.namedBindings &&
+        ts.isNamedImports(node.importClause.namedBindings) &&
+        node.importClause.namedBindings.elements.some((element) => element.name.text === name));
 };
-const removeQueryDevtoolsImportsFromMetadata = (content) => {
+/**
+ * Turns every `provideQueryClientForDevtools({ client, displayName })` into a single
+ * `provideQueryDevtools()`.
+ *
+ * v3 registers every client and auth provider at once, so N per-client calls collapse to one. The
+ * first call site keeps its position - it is already where the app wanted its devtools - and the
+ * rest are removed along with the comma that separated them.
+ */
+const replaceDevtoolsProviderCalls = (content) => {
     const sourceFile = createSourceFile(content);
-    const replacements = [];
+    const calls = [];
     const visit = (node) => {
-        if (ts.isPropertyAssignment(node) &&
-            ts.isIdentifier(node.name) &&
-            node.name.text === 'imports' &&
-            ts.isArrayLiteralExpression(node.initializer)) {
-            const nextElements = node.initializer.elements.filter((element) => {
-                return !(ts.isIdentifier(element) && element.text === 'QueryDevtoolsComponent');
-            });
-            if (nextElements.length === node.initializer.elements.length) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            const replacement = `imports: [${nextElements.map((element) => element.getText(sourceFile)).join(', ')}]`;
-            replacements.push({
-                start: node.getStart(sourceFile),
-                end: node.getEnd(),
-                replacement,
-            });
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'provideQueryClientForDevtools') {
+            calls.push(node);
         }
         ts.forEachChild(node, visit);
     };
     visit(sourceFile);
+    if (calls.length === 0) {
+        return content;
+    }
+    const replacements = calls.map((call, index) => {
+        const start = call.getStart(sourceFile);
+        const end = call.getEnd();
+        if (index === 0) {
+            return { start, end, replacement: 'provideQueryDevtools()' };
+        }
+        return { ...withSurroundingComma(content, start, end), replacement: '' };
+    });
     let result = content;
     replacements.sort((left, right) => right.start - left.start);
     replacements.forEach(({ start, end, replacement }) => {
@@ -120,7 +152,24 @@ const removeQueryDevtoolsImportsFromMetadata = (content) => {
     });
     return result;
 };
-const removeDevtoolsImports = (content) => {
+/** Widens a range to swallow the comma that separated the element from its neighbours. */
+const withSurroundingComma = (content, start, end) => {
+    let nextEnd = end;
+    while (nextEnd < content.length && /\s/.test(content[nextEnd]))
+        nextEnd += 1;
+    if (content[nextEnd] === ',') {
+        return { start, end: nextEnd + 1 };
+    }
+    let nextStart = start;
+    while (nextStart > 0 && /\s/.test(content[nextStart - 1]))
+        nextStart -= 1;
+    if (content[nextStart - 1] === ',') {
+        return { start: nextStart - 1, end };
+    }
+    return { start, end };
+};
+/** Drops the v2 devtools names from the `@ethlete/query` import; both moved or were renamed. */
+const dropLegacyDevtoolsImports = (content) => {
     const sourceFile = createSourceFile(content);
     let importNode;
     ts.forEachChild(sourceFile, (node) => {
@@ -133,9 +182,7 @@ const removeDevtoolsImports = (content) => {
     if (!importNode?.importClause?.namedBindings || !ts.isNamedImports(importNode.importClause.namedBindings)) {
         return content;
     }
-    const nextElements = importNode.importClause.namedBindings.elements.filter((element) => {
-        return element.name.text !== 'QueryDevtoolsComponent' && element.name.text !== 'provideQueryClientForDevtools';
-    });
+    const nextElements = importNode.importClause.namedBindings.elements.filter((element) => element.name.text !== 'QueryDevtoolsComponent' && element.name.text !== 'provideQueryClientForDevtools');
     if (nextElements.length === importNode.importClause.namedBindings.elements.length) {
         return content;
     }
@@ -146,12 +193,6 @@ const removeDevtoolsImports = (content) => {
     const nextImport = `import { ${nextElements.map((element) => element.getText(sourceFile)).join(', ')} } from '@ethlete/query';`;
     return content.slice(0, importNode.getStart(sourceFile)) + nextImport + content.slice(importNode.getEnd());
 };
-const removeDevtoolsFromHtml = (content) => {
-    return content
-        .replace(/<et-query-devtools\s*\/>/g, '')
-        .replace(/<et-query-devtools[^>]*>[\s\S]*?<\/et-query-devtools>/g, '')
-        .replace(/\n\s*\n\s*\n/g, '\n\n');
-};
 const replaceAnyQueryInFile = (content) => {
     const sourceFile = createSourceFile(content);
     const replacements = [];
@@ -195,17 +236,27 @@ const removeAnyQueryFromImports = (content) => {
     if (!importNode?.importClause?.namedBindings || !ts.isNamedImports(importNode.importClause.namedBindings)) {
         return content;
     }
-    const nextElements = importNode.importClause.namedBindings.elements.filter((element) => {
-        return element.name.text !== 'AnyV2Query' && element.name.text !== 'AnyV2QueryCreator';
+    const replaced = new Map([
+        ['AnyV2Query', 'AnyLegacyQuery'],
+        ['AnyV2QueryCreator', 'AnyLegacyQueryCreator'],
+    ]);
+    const names = new Set();
+    let changed = false;
+    importNode.importClause.namedBindings.elements.forEach((element) => {
+        const replacement = replaced.get(element.name.text);
+        if (!replacement) {
+            names.add(element.getText(sourceFile));
+            return;
+        }
+        // Only add the alias that was actually imported. Adding both unconditionally is what put
+        // `AnyLegacyQuery` / `AnyLegacyQueryCreator` into hundreds of files that never referenced them.
+        changed = true;
+        names.add(replacement);
     });
-    const names = nextElements.map((element) => element.getText(sourceFile));
-    if (!names.includes('AnyLegacyQuery')) {
-        names.push('AnyLegacyQuery');
-    }
-    if (!names.includes('AnyLegacyQueryCreator')) {
-        names.push('AnyLegacyQueryCreator');
+    if (!changed) {
+        return content;
     }
-    const nextImport = `import { ${names.sort().join(', ')} } from '@ethlete/query';`;
+    const nextImport = `import { ${Array.from(names).sort().join(', ')} } from '@ethlete/query';`;
     return content.slice(0, importNode.getStart(sourceFile)) + nextImport + content.slice(importNode.getEnd());
 };
 const transformEmptyPrepareCalls = (content) => {

package/generators/migrate-to-query-v3/http-client-check.js

@@ -0,0 +1,93 @@
+import { getLineNumberFromPosition } from './shared.js';
+const APP_CONFIG_MARKERS = ['bootstrapApplication(', 'ApplicationConfig', 'provideServerRendering('];
+/**
+ * Flags the v2 default-header APIs, which the client migration drops on the floor.
+ *
+ * `setDefaultHeaders` is not cosmetic - an API token or a preview credential lives there, so losing
+ * it means every request goes out unauthenticated. v3 has a home for it (`headers` on
+ * `createQueryClient`), but the call sites are imperative and scattered, so this is a pointer rather
+ * than a rewrite.
+ */
+export const reportDefaultHeaderUsages = (tree, report, scope) => {
+    const locations = [];
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts')) {
+            return;
+        }
+        const content = tree.read(filePath, 'utf-8');
+        if (!content) {
+            return;
+        }
+        for (const marker of ['setDefaultHeaders', 'globalHeaders']) {
+            const index = content.indexOf(marker);
+            if (index >= 0) {
+                locations.push({ filePath, line: getLineNumberFromPosition(content, index) });
+            }
+        }
+    });
+    if (locations.length === 0) {
+        return;
+    }
+    report.addWarning({
+        title: 'Move default headers onto the query client',
+        summary: 'This workspace sets client-wide headers through the v2 `setDefaultHeaders` / `globalHeaders` API, which `createQueryClient` does not have. Left as is, those headers are simply not sent.',
+        action: 'Pass `headers` to `createQueryClient` - a function form re-reads on every request, so a signal can drive it. `refreshQueriesInUse: true` becomes `injectMyClient().refreshQueriesInUse()` after the value changes.',
+        locations,
+        source: 'http-client-check',
+        dedupeKey: 'default-headers',
+    });
+};
+/**
+ * Flags applications that will build cleanly and then fail on their first request.
+ *
+ * The v2 client shipped its own transport; v3 does `inject(HttpClient)`. An app that never needed
+ * `provideHttpClient()` therefore keeps compiling after the migration and dies at runtime instead -
+ * the one failure mode a codemod should never leave behind silently.
+ */
+export const reportMissingHttpClientProviders = (tree, report, scope) => {
+    const appConfigFiles = [];
+    const filesWithProvider = [];
+    const filesWithUploadProgress = [];
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts')) {
+            return;
+        }
+        const content = tree.read(filePath, 'utf-8');
+        if (!content) {
+            return;
+        }
+        if (content.includes('provideHttpClient(')) {
+            filesWithProvider.push(filePath);
+        }
+        const markerIndex = APP_CONFIG_MARKERS.map((marker) => content.indexOf(marker)).find((index) => index >= 0);
+        if (markerIndex !== undefined) {
+            appConfigFiles.push({ filePath, line: getLineNumberFromPosition(content, markerIndex) });
+        }
+        const progressIndex = content.indexOf('reportProgress');
+        if (progressIndex >= 0) {
+            filesWithUploadProgress.push({ filePath, line: getLineNumberFromPosition(content, progressIndex) });
+        }
+    });
+    if (appConfigFiles.length > 0 && filesWithProvider.length === 0) {
+        report.addWarning({
+            title: 'Add provideHttpClient() to the application providers',
+            summary: 'v3 queries run on Angular’s `HttpClient`, but no `provideHttpClient()` was found. The app compiles and then throws on the first request - `@ethlete/query` never provides it, that is the application’s job.',
+            action: 'Add `provideHttpClient()` to every app config that uses a query client. If anything relies on upload progress, use `provideHttpClient(withXhr())` - on Angular ≥ 22 the default is fetch, which emits no upload progress events.',
+            locations: appConfigFiles,
+            source: 'http-client-check',
+            dedupeKey: 'missing-provide-http-client',
+        });
+        return;
+    }
+    if (filesWithUploadProgress.length > 0) {
+        report.addManualReview({
+            title: 'Confirm the HttpClient backend supports upload progress',
+            summary: 'Queries in this workspace set `reportProgress`. On Angular ≥ 22 `provideHttpClient()` defaults to the fetch backend, which never emits upload progress events, so those queries would report download progress only.',
+            action: 'Switch the affected app to `provideHttpClient(withXhr())`, or drop `reportProgress` where it is unused.',
+            locations: filesWithUploadProgress,
+            source: 'http-client-check',
+            dedupeKey: 'upload-progress-backend',
+        });
+    }
+};
+//# sourceMappingURL=http-client-check.js.map