@ethlete/query 6.0.0-next.6 → 6.0.0-next.61

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

@@ -0,0 +1,233 @@
+import * as ts from 'typescript';
+import { createSourceFile, printImportDeclaration } 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.
+ */
+export 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.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))
+        return true;
+    if (ts.isExportSpecifier(parent) &&
+        (parent.parent.parent.moduleSpecifier || (parent.propertyName && parent.name === node))) {
+        return true;
+    }
+    if (ts.isImportClause(parent) || ts.isNamespaceImport(parent))
+        return true;
+    return false;
+};
+export const renamedReference = (node, nextName) => {
+    const parent = node.parent;
+    if (ts.isShorthandPropertyAssignment(parent))
+        return `${node.text}: ${nextName}`;
+    if (ts.isExportSpecifier(parent) && !parent.propertyName)
+        return `${nextName} as ${node.text}`;
+    return nextName;
+};
+const bindingDeclares = (name, text) => ts.isIdentifier(name)
+    ? name.text === text
+    : name.elements.some((element) => !ts.isOmittedExpression(element) && bindingDeclares(element.name, text));
+const statementDeclares = (statement, text) => (ts.isVariableStatement(statement) &&
+    statement.declarationList.declarations.some((declaration) => bindingDeclares(declaration.name, text))) ||
+    ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement)) &&
+        statement.name?.text === text);
+export const isShadowedInNestedScope = (identifier) => {
+    const text = identifier.text;
+    for (let scope = identifier.parent; scope && !ts.isSourceFile(scope); scope = scope.parent) {
+        if (ts.isFunctionLike(scope) && scope.parameters.some((parameter) => bindingDeclares(parameter.name, text))) {
+            return true;
+        }
+        if ((ts.isFunctionExpression(scope) || ts.isClassExpression(scope)) && scope.name?.text === text) {
+            return true;
+        }
+        if ((ts.isBlock(scope) || ts.isModuleBlock(scope) || ts.isCaseClause(scope) || ts.isDefaultClause(scope)) &&
+            scope.statements.some((statement) => statementDeclares(statement, text))) {
+            return true;
+        }
+        if ((ts.isForStatement(scope) || ts.isForInStatement(scope) || ts.isForOfStatement(scope)) &&
+            scope.initializer &&
+            ts.isVariableDeclarationList(scope.initializer) &&
+            scope.initializer.declarations.some((declaration) => bindingDeclares(declaration.name, text))) {
+            return true;
+        }
+        if (ts.isCatchClause(scope) && scope.variableDeclaration && bindingDeclares(scope.variableDeclaration.name, text)) {
+            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: renamedReference(node, 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) => {
+    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) ||
+            !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 nextImport = printImportDeclaration(node, sourceFile, kept.map((element) => element.getText(sourceFile)));
+        if (!nextImport) {
+            const end = content[node.getEnd()] === '\n' ? node.getEnd() + 1 : node.getEnd();
+            replacements.push({ start: node.getStart(sourceFile), end, replacement: '' });
+            continue;
+        }
+        replacements.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement: nextImport });
+    }
+    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/report.js

@@ -25,7 +25,7 @@ export class QueryV3MigrationReport {
             return;
         }
         const nextTask = {
-            id: `QV3-${String(this.tasks.length + 1).padStart(3, '0')}`,
+            id: formatTaskId(this.tasks.length + 1),
             kind: input.kind,
             title: input.title,
             summary: input.summary,
@@ -58,11 +58,37 @@ export class QueryV3MigrationReport {
         });
         console.warn(`\n📄 See ${QUERY_V3_MIGRATION_REPORT_PATH} for the AI-ready follow-up list.`);
     }
-    writeToTree(tree) {
-        tree.write(QUERY_V3_MIGRATION_REPORT_PATH, renderMigrationReportMarkdown(this.tasks));
+    /**
+     * Writes the report. A scoped run (`scopeLabel` set) replaces its own section of an existing report
+     * or appends one, so the tasks of earlier runs over other projects survive.
+     */
+    writeToTree(tree, scopeLabel) {
+        const existing = scopeLabel ? tree.read(QUERY_V3_MIGRATION_REPORT_PATH, 'utf-8') : null;
+        if (!scopeLabel || !existing) {
+            tree.write(QUERY_V3_MIGRATION_REPORT_PATH, renderMigrationReportMarkdown(this.tasks, scopeLabel));
+            return;
+        }
+        tree.write(QUERY_V3_MIGRATION_REPORT_PATH, mergeScopedSection(existing, this.tasks, scopeLabel));
     }
 }
-export const renderMigrationReportMarkdown = (tasks) => {
+const sectionStart = (scopeLabel) => `<!-- migrate-to-query-v3 scope: ${scopeLabel} -->`;
+const SECTION_END = '<!-- /migrate-to-query-v3 scope -->';
+const mergeScopedSection = (existing, tasks, scopeLabel) => {
+    const start = sectionStart(scopeLabel);
+    const startIndex = existing.indexOf(start);
+    const endIndex = startIndex === -1 ? -1 : existing.indexOf(SECTION_END, startIndex);
+    const [before, after] = startIndex === -1 || endIndex === -1
+        ? [existing.trimEnd(), '']
+        : [existing.slice(0, startIndex).trimEnd(), existing.slice(endIndex + SECTION_END.length).trimStart()];
+    const highestId = Math.max(0, ...Array.from(`${before}\n${after}`.matchAll(/QV3-(\d+)/g), (match) => Number(match[1])));
+    const renumbered = tasks.map((task, index) => ({ ...task, id: formatTaskId(highestId + index + 1) }));
+    return [before, renderTasksSection(renumbered, scopeLabel), after]
+        .filter((part) => part.length > 0)
+        .join('\n\n')
+        .concat('\n');
+};
+const formatTaskId = (index) => `QV3-${String(index).padStart(3, '0')}`;
+export const renderMigrationReportMarkdown = (tasks, scopeLabel) => {
     const header = [
         '# Query V3 Migration Follow-Up',
         '',
@@ -83,8 +109,16 @@ export const renderMigrationReportMarkdown = (tasks) => {
         '- `Source`: which migration phase raised the task.',
         '',
     ].join('\n');
+    return `${header}\n${renderTasksSection(tasks, scopeLabel)}\n`;
+};
+const renderTasksSection = (tasks, scopeLabel) => {
+    const heading = scopeLabel ? `## Tasks (scope: ${scopeLabel})` : '## Tasks';
+    const body = renderTasksBody(tasks);
+    return scopeLabel ? `${sectionStart(scopeLabel)}\n${heading}\n\n${body}\n${SECTION_END}` : `${heading}\n\n${body}`;
+};
+const renderTasksBody = (tasks) => {
     if (tasks.length === 0) {
-        return `${header}## Tasks\n\nNo open follow-up tasks were recorded during this migration run.\n`;
+        return 'No open follow-up tasks were recorded during this migration run.';
     }
     const tasksSection = tasks
         .map((task) => {
@@ -129,8 +163,7 @@ export const renderMigrationReportMarkdown = (tasks) => {
             ];
         }),
         '```',
-        '',
     ].join('\n');
-    return `${header}## Tasks\n\n${tasksSection}${machineSection}`;
+    return `${tasksSection}${machineSection}`;
 };
 //# sourceMappingURL=report.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

@@ -13,13 +13,34 @@ export const ensureConfigSuffix = (name) => {
     }
     return `${name}Config`;
 };
+const importSpecifierText = (element) => element.propertyName ? `${element.propertyName.text} as ${element.name.text}` : element.name.text;
+/**
+ * Prints `node` with `namedElements` as its named bindings, keeping the default import, the
+ * `import type` modifier, the quote style and any import attributes. Returns an empty string when
+ * nothing would be left to import.
+ */
+export const printImportDeclaration = (node, sourceFile, namedElements) => {
+    const clause = node.importClause;
+    const defaultName = clause?.name?.text;
+    const bindings = [defaultName, namedElements.length > 0 ? `{ ${namedElements.join(', ')} }` : undefined].filter((part) => !!part);
+    if (bindings.length === 0) {
+        return '';
+    }
+    const typePrefix = clause?.isTypeOnly ? 'type ' : '';
+    const attributes = node.attributes ? ` ${node.attributes.getText(sourceFile)}` : '';
+    return `import ${typePrefix}${bindings.join(', ')} from ${node.moduleSpecifier.getText(sourceFile)}${attributes};`;
+};
 export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier }) => {
     const sourceFile = createSourceFile(content);
     let importNode;
     ts.forEachChild(sourceFile, (node) => {
-        if (ts.isImportDeclaration(node) &&
+        if (!importNode &&
+            ts.isImportDeclaration(node) &&
             ts.isStringLiteral(node.moduleSpecifier) &&
-            node.moduleSpecifier.text === moduleSpecifier) {
+            node.moduleSpecifier.text === moduleSpecifier &&
+            !node.importClause?.isTypeOnly &&
+            node.importClause?.namedBindings &&
+            ts.isNamedImports(node.importClause.namedBindings)) {
             importNode = node;
         }
     });
@@ -28,13 +49,14 @@ export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier })
         const namedBindings = importNode.importClause.namedBindings;
         namedBindings.elements.forEach((element) => {
             missingImports.delete(element.name.text);
+            missingImports.delete(importSpecifierText(element));
         });
         if (missingImports.size === 0) {
             return content;
         }
         const existingImports = namedBindings.elements.map((element) => element.getText(sourceFile));
         const nextImports = [...existingImports, ...Array.from(missingImports).sort()].sort();
-        const nextImportStatement = `import { ${nextImports.join(', ')} } from '${moduleSpecifier}';`;
+        const nextImportStatement = printImportDeclaration(importNode, sourceFile, nextImports);
         return content.slice(0, importNode.getStart(sourceFile)) + nextImportStatement + content.slice(importNode.getEnd());
     }
     let lastImportEnd = 0;
@@ -55,6 +77,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 +118,74 @@ 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));
+};
+const TUPLE_PROVIDER_ACTION = 'Delete the call: a v3 client, auth provider or socket is root-provided the moment something injects it. For a test or an override, provide it with `toProvideFn(ref)` from `@ethlete/core`.';
+export const REMOVED_EXPERIMENTAL_QUERY_HELPERS = {
+    createQueryClientConfig: 'Replace it with `createQueryClient({ name, baseUrl })`, which returns the provider tuple, and derive `toProvideFn` / `toInjectFn` from it.',
+    createBearerAuthProviderConfig: 'Replace it with `createBearerAuthProvider({ name, queryClientRef, queries, features })`, which returns the provider tuple, and derive `toProvideFn` / `toInjectFn` from it.',
+    provideQueryClient: TUPLE_PROVIDER_ACTION,
+    provideBearerAuthProvider: TUPLE_PROVIDER_ACTION,
+    provideWebSocketClient: `Build the socket with \`createWebSocketClient({ name, url, io })\`. ${TUPLE_PROVIDER_ACTION}`,
+};
+export const findRemovedExperimentalQueryHelpers = (sourceFile) => {
+    const found = [];
+    sourceFile.statements.forEach((statement) => {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== '@ethlete/query' ||
+            !statement.importClause?.namedBindings ||
+            !ts.isNamedImports(statement.importClause.namedBindings)) {
+            return;
+        }
+        statement.importClause.namedBindings.elements.forEach((element) => {
+            const name = (element.propertyName ?? element.name).text;
+            if (name in REMOVED_EXPERIMENTAL_QUERY_HELPERS) {
+                found.push({ name, line: getLineNumber(element, sourceFile) });
+            }
+        });
+    });
+    return found;
+};
 //# sourceMappingURL=shared.js.map

package/generators/move-devtools-contract-imports/migration.js

@@ -0,0 +1,155 @@
+import { formatFiles } from '@nx/devkit';
+import * as ts from 'typescript';
+import { createMigrationScope } from '../migrate-to-query-v3/migration-scope.js';
+import { createSourceFile } from '../migrate-to-query-v3/shared.js';
+import { MOVED_DEVTOOLS_CONTRACT_NAMES } from './moved-names.js';
+const QUERY_MODULE = '@ethlete/query';
+const CONTRACT_MODULE = '@ethlete/query/devtools-contract';
+const isMigratableFile = (filePath) => /\.(ts|mts|cts|tsx)$/.test(filePath) && !filePath.endsWith('.d.ts');
+const specifierName = (specifier) => (specifier.propertyName ?? specifier.name).text;
+const isMoved = (specifier) => MOVED_DEVTOOLS_CONTRACT_NAMES.has(specifierName(specifier));
+const moduleOf = (statement) => {
+    if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+        return undefined;
+    const specifier = statement.moduleSpecifier;
+    return specifier && ts.isStringLiteral(specifier) ? specifier : undefined;
+};
+const namedBindingsOf = (statement) => {
+    if (ts.isExportDeclaration(statement)) {
+        return statement.exportClause && ts.isNamedExports(statement.exportClause) ? statement.exportClause : undefined;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    return bindings && ts.isNamedImports(bindings) ? bindings : undefined;
+};
+const isTypeOnlyDeclaration = (statement) => ts.isExportDeclaration(statement) ? statement.isTypeOnly : !!statement.importClause?.isTypeOnly;
+const declarationKey = (statement) => `${ts.isImportDeclaration(statement) ? 'import' : 'export'}${isTypeOnlyDeclaration(statement) ? ' type' : ''}`;
+const findNamespaceUses = (sourceFile, content) => {
+    const uses = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || moduleOf(statement)?.text !== QUERY_MODULE)
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamespaceImport(bindings))
+            continue;
+        for (const name of MOVED_DEVTOOLS_CONTRACT_NAMES) {
+            if (content.includes(`${bindings.name.text}.${name}`))
+                uses.push(`${bindings.name.text}.${name}`);
+        }
+    }
+    return uses;
+};
+export const moveDevtoolsContractImportsInFile = (content, filePath) => {
+    if (!content.includes(QUERY_MODULE))
+        return null;
+    const sourceFile = createSourceFile(content, filePath);
+    const edits = [];
+    const contractTargets = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+            continue;
+        if (moduleOf(statement)?.text !== CONTRACT_MODULE)
+            continue;
+        const bindings = namedBindingsOf(statement);
+        const key = declarationKey(statement);
+        if (bindings && !contractTargets.has(key))
+            contractTargets.set(key, { bindings, added: [] });
+    }
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+            continue;
+        const moduleSpecifier = moduleOf(statement);
+        if (moduleSpecifier?.text !== QUERY_MODULE)
+            continue;
+        const bindings = namedBindingsOf(statement);
+        if (!bindings)
+            continue;
+        const elements = bindings.elements;
+        const moved = elements.filter(isMoved);
+        if (moved.length === 0)
+            continue;
+        const kept = elements.filter((specifier) => !isMoved(specifier));
+        const movedText = moved.map((specifier) => specifier.getText(sourceFile));
+        const hasDefaultImport = ts.isImportDeclaration(statement) && !!statement.importClause?.name;
+        const target = contractTargets.get(declarationKey(statement));
+        if (target) {
+            target.added.push(...movedText);
+        }
+        if (kept.length === 0 && !hasDefaultImport) {
+            if (target) {
+                edits.push({ start: statement.getFullStart(), end: statement.getEnd(), text: '' });
+            }
+            else {
+                const quote = moduleSpecifier.getText(sourceFile)[0];
+                edits.push({
+                    start: moduleSpecifier.getStart(sourceFile),
+                    end: moduleSpecifier.getEnd(),
+                    text: `${quote}${CONTRACT_MODULE}${quote}`,
+                });
+            }
+            continue;
+        }
+        edits.push({
+            start: bindings.getStart(sourceFile),
+            end: bindings.getEnd(),
+            text: kept.length ? `{ ${kept.map((specifier) => specifier.getText(sourceFile)).join(', ')} }` : '{}',
+        });
+        if (!target) {
+            const quote = moduleSpecifier.getText(sourceFile)[0];
+            edits.push({
+                start: statement.getEnd(),
+                end: statement.getEnd(),
+                text: `\n${declarationKey(statement)} { ${movedText.join(', ')} } from ${quote}${CONTRACT_MODULE}${quote};`,
+            });
+        }
+    }
+    for (const { bindings, added } of contractTargets.values()) {
+        if (added.length === 0)
+            continue;
+        const last = bindings.elements.at(-1);
+        const position = last ? last.getEnd() : bindings.getStart(sourceFile) + 1;
+        edits.push({ start: position, end: position, text: last ? `, ${added.join(', ')}` : ` ${added.join(', ')} ` });
+    }
+    if (edits.length === 0)
+        return null;
+    return edits
+        .sort((a, b) => b.start - a.start)
+        .reduce((text, edit) => text.slice(0, edit.start) + edit.text + text.slice(edit.end), content);
+};
+export const moveDevtoolsContractImports = (tree, scope) => {
+    const touchedFiles = [];
+    const manualUses = [];
+    scope.visit(tree, (filePath) => {
+        if (!isMigratableFile(filePath))
+            return;
+        const content = tree.read(filePath, 'utf-8');
+        if (!content?.includes(QUERY_MODULE))
+            return;
+        for (const use of findNamespaceUses(createSourceFile(content, filePath), content)) {
+            manualUses.push(`${filePath}: ${use}`);
+        }
+        const next = moveDevtoolsContractImportsInFile(content, filePath);
+        if (next === null)
+            return;
+        tree.write(filePath, next);
+        touchedFiles.push(filePath);
+    });
+    return { touchedFiles, manualUses };
+};
+export default async function migrate(tree, schema) {
+    console.log(`\n🔄 Moving devtools contract imports to ${CONTRACT_MODULE}...`);
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const { touchedFiles, manualUses } = moveDevtoolsContractImports(tree, scope);
+    console.log(`   Rewrote imports in ${touchedFiles.length} file${touchedFiles.length === 1 ? '' : 's'}.`);
+    if (manualUses.length > 0) {
+        console.log(`\n⚠️  Namespace imports of ${QUERY_MODULE} use names that moved to ${CONTRACT_MODULE}:`);
+        for (const use of manualUses) {
+            console.log(`   ${use}`);
+        }
+    }
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    console.log('\n✅ Devtools contract imports moved.');
+}
+//# sourceMappingURL=migration.js.map