@ethlete/query 6.0.0-next.54 → 6.0.0-next.56

package/generators/generators.json

@@ -29,6 +29,16 @@
       "factory": "./migrate-from-ngrx-toolkit/migration",
       "schema": "./migrate-from-ngrx-toolkit/schema.json",
       "description": "Move @tomtomb/ngrx-toolkit features onto v3 query creators and the @ethlete/query/ngrx-toolkit interop"
+    },
+    "report-legacy-query-apis": {
+      "factory": "./report-legacy-query-apis/migration",
+      "schema": "./report-legacy-query-apis/schema.json",
+      "description": "Write a task to query-v3-migration-tasks.md for every legacy query collection, infinity query, *etQuery template and entity store"
+    },
+    "move-devtools-contract-imports": {
+      "factory": "./move-devtools-contract-imports/migration",
+      "schema": "./move-devtools-contract-imports/schema.json",
+      "description": "Import the devtools contract from @ethlete/query/devtools-contract instead of @ethlete/query"
     }
   }
 }

package/generators/migrate-query-client-features/migration.js

@@ -47,14 +47,16 @@ const collectClientEdits = (filePath, sourceFile, report) => {
                 const persistenceProperty = named('persistence');
                 const featuresProperty = named('features');
                 if (featuresProperty) {
-                    report.addManualReview({
-                        title: 'createQueryClient already has a features array',
-                        summary: 'The client was left untouched so an existing `features` array is not overwritten.',
-                        action: 'Fold the removed `multiTabSync` / `persistence` options into the existing `features` array.',
-                        locations: [{ filePath, line }],
-                        source: SOURCE,
-                        dedupeKey: 'existing-features',
-                    });
+                    if (syncProperty || persistenceProperty) {
+                        report.addManualReview({
+                            title: 'createQueryClient already has a features array',
+                            summary: 'The client was left untouched so an existing `features` array is not overwritten.',
+                            action: 'Fold the removed `multiTabSync` / `persistence` options into the existing `features` array.',
+                            locations: [{ filePath, line }],
+                            source: SOURCE,
+                            dedupeKey: 'existing-features',
+                        });
+                    }
                 }
                 else {
                     for (const property of [syncProperty, persistenceProperty]) {

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

@@ -350,7 +350,7 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                     report.addFollowUp({
                         title: `Check the entity config carried onto ${toLegacyName(creatorName)}`,
                         summary: `${creatorName} had an \`entity\` config. It was moved onto the \`${toLegacyName(creatorName)}\` interop wrapper, which still writes to the EntityStore; the v3 creator \`${creatorName}\` does not, and v3 has no EntityStore.`,
-                        action: 'Keep the call sites that rely on the store on the legacy wrapper. `set` now only runs on a real response, never on `prepare()` or a failure.',
+                        action: 'Keep the call sites that rely on the store on the legacy wrapper. `set` now only runs on a real response, never on `prepare()` or a failure. To leave the store, declare `invalidates` on the mutation creators that change the entity and `tags` on the reads that show it, and add `withOptimisticUpdate` where the UI must change before the response - see https://ethlete-sdk-docs.web.app/query/migrating-from-v2#entitystore-becomes-invalidates-and-tags.',
                         locations: [
                             { filePath, line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 },
                         ],

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

@@ -109,7 +109,7 @@ export const renderMigrationReportMarkdown = (tasks, scopeLabel) => {
         '- `Source`: which migration phase raised the task.',
         '',
     ].join('\n');
-    return `${header}${renderTasksSection(tasks, scopeLabel)}\n`;
+    return `${header}\n${renderTasksSection(tasks, scopeLabel)}\n`;
 };
 const renderTasksSection = (tasks, scopeLabel) => {
     const heading = scopeLabel ? `## Tasks (scope: ${scopeLabel})` : '## Tasks';

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

package/generators/move-devtools-contract-imports/moved-names.js

@@ -0,0 +1,153 @@
+export const MOVED_DEVTOOLS_CONTRACT_NAMES = new Set([
+    'addQueryDevtoolsAuthAccount',
+    'applyQueryDevtoolsOverrides',
+    'applyQueryDevtoolsTokenTtl',
+    'armAllQueryDevtoolsMocks',
+    'armQueryDevtoolsMock',
+    'armQueryDevtoolsOverrideTransfer',
+    'canOverrideQueryDevtoolsTokenTtl',
+    'clearQueryDevtoolsArmedMocks',
+    'clearQueryDevtoolsAuthCredentials',
+    'clearQueryDevtoolsAuthSessions',
+    'clearQueryDevtoolsFaults',
+    'clearQueryDevtoolsMockStore',
+    'clearQueryDevtoolsOverrideStore',
+    'clearQueryDevtoolsStore',
+    'clearQueryDevtoolsTombstones',
+    'clearRestoredQueryDevtoolsOverrides',
+    'collectLeafPaths',
+    'collectQueryDevtoolsSchemaComponents',
+    'countUnresolvedQueryDevtoolsOverrides',
+    'createQueryDevtoolsOverrides',
+    'deleteQueryDevtoolsMock',
+    'DescribableFeature',
+    'detectPaginationShape',
+    'EMPTY_QUERY_DEVTOOLS_FAULT',
+    'forgetQueryDevtoolsAuthSession',
+    'forgetQueryDevtoolsAuthSessionsFor',
+    'generateQueryDevtoolsNumberPreset',
+    'generateQueryDevtoolsSampleNumber',
+    'generateQueryDevtoolsStringPreset',
+    'hasQueryDevtoolsOverridesAtPath',
+    'isDateShapedLeaf',
+    'isQueryDevtoolsEnabled',
+    'isQueryDevtoolsFaultArmed',
+    'isQueryDevtoolsRepositoryLive',
+    'JsonPath',
+    'loadQueryDevtoolsSchema',
+    'loginQueryDevtoolsAuthAccount',
+    'logoutQueryDevtoolsAuthSession',
+    'matchesQueryDevtoolsMockPattern',
+    'matchesQueryDevtoolsMockQuery',
+    'MAX_QUERY_BATCH_TOMBSTONE_BUCKETS',
+    'MAX_QUERY_BATCH_TOMBSTONES',
+    'MAX_QUERY_DEVTOOLS_TOMBSTONES',
+    'measureQueryDevtoolsPayload',
+    'OverrideOp',
+    'parseQueryDevtoolsOverrideTransfer',
+    'QUERY_DEVTOOLS_FAULT_STATUSES',
+    'QUERY_DEVTOOLS_TOKEN_TTL_LIMIT',
+    'queryDevtoolsAbout',
+    'QueryDevtoolsAbout',
+    'queryDevtoolsAllowsLocalAuthSessions',
+    'queryDevtoolsApiEnvIds',
+    'queryDevtoolsApiEnvIsProduction',
+    'queryDevtoolsApiEnvs',
+    'queryDevtoolsApiEnvScope',
+    'queryDevtoolsApiEnvValues',
+    'queryDevtoolsArmedMocks',
+    'queryDevtoolsArmedMocksRestored',
+    'queryDevtoolsAuthAccountsFor',
+    'QueryDevtoolsAuthAccountView',
+    'queryDevtoolsAuthActive',
+    'queryDevtoolsAuthFieldsFor',
+    'QueryDevtoolsAuthLocalAccount',
+    'queryDevtoolsAuthOtherScopeCount',
+    'QueryDevtoolsAuthProviderHandle',
+    'QueryDevtoolsAuthProviderRegistration',
+    'QueryDevtoolsAuthQuery',
+    'QueryDevtoolsAuthSeed',
+    'QueryDevtoolsAuthSession',
+    'queryDevtoolsAuthSessions',
+    'queryDevtoolsAuthSessionsFor',
+    'queryDevtoolsAuthTabLocal',
+    'queryDevtoolsEntries',
+    'QueryDevtoolsEntry',
+    'QueryDevtoolsEntryKind',
+    'QueryDevtoolsEntryMeta',
+    'QueryDevtoolsFault',
+    'queryDevtoolsFaults',
+    'queryDevtoolsFaultsRestored',
+    'QueryDevtoolsFaultTarget',
+    'QueryDevtoolsFeature',
+    'QueryDevtoolsFormField',
+    'QueryDevtoolsFormHandle',
+    'QueryDevtoolsFormLinksHandle',
+    'QueryDevtoolsFormLinksRecorder',
+    'QueryDevtoolsMock',
+    'queryDevtoolsMockId',
+    'queryDevtoolsMocks',
+    'QueryDevtoolsMockTarget',
+    'QueryDevtoolsOverrideEntry',
+    'queryDevtoolsOverridePersistence',
+    'QueryDevtoolsOverridesHandle',
+    'QueryDevtoolsOverridesRecorder',
+    'QueryDevtoolsOverrideTransfer',
+    'QueryDevtoolsOverrideTransferParse',
+    'QueryDevtoolsPayload',
+    'QueryDevtoolsRegistrar',
+    'QueryDevtoolsRegistration',
+    'queryDevtoolsRequestPath',
+    'QueryDevtoolsResolvedFault',
+    'QueryDevtoolsResolvedMock',
+    'queryDevtoolsResponseHistory',
+    'queryDevtoolsRestoredOverridesScope',
+    'QueryDevtoolsRoutePart',
+    'QueryDevtoolsRun',
+    'QueryDevtoolsRunError',
+    'QueryDevtoolsRunStatus',
+    'QueryDevtoolsSchemaComponents',
+    'queryDevtoolsSchemaNames',
+    'QueryDevtoolsSchemaRoute',
+    'queryDevtoolsSchemaRoutes',
+    'QueryDevtoolsSchemaSeed',
+    'queryDevtoolsSchemaState',
+    'QueryDevtoolsSchemaState',
+    'QueryDevtoolsSeedStyle',
+    'queryDevtoolsSettings',
+    'QueryDevtoolsSettings',
+    'QueryDevtoolsStats',
+    'QueryDevtoolsStatsHandle',
+    'QueryDevtoolsStatsRecorder',
+    'queryDevtoolsStorage',
+    'QueryDevtoolsStorageScope',
+    'queryDevtoolsTokenTtls',
+    'readQueryDevtoolsStore',
+    'registerEthleteVersion',
+    'removeQueryDevtoolsAuthAccount',
+    'renameQueryDevtoolsAuthSession',
+    'restoredQueryDevtoolsOverrides',
+    'RestoredQueryDevtoolsOverrides',
+    'saveQueryDevtoolsMock',
+    'seedQueryDevtoolsSchemaBody',
+    'seedQueryDevtoolsSchemaRoute',
+    'serializeQueryDevtoolsOverrideTransfer',
+    'setQueryDevtoolsApiEnv',
+    'setQueryDevtoolsAppInfo',
+    'setQueryDevtoolsArmedMocksScope',
+    'setQueryDevtoolsAuthCredentials',
+    'setQueryDevtoolsAuthTabLocal',
+    'setQueryDevtoolsFault',
+    'setQueryDevtoolsFaultsScope',
+    'setQueryDevtoolsOverridePersistence',
+    'setQueryDevtoolsOverridesScope',
+    'setQueryDevtoolsSettings',
+    'smartDuplicateArrayItem',
+    'snapshotQueryDevtoolsHandle',
+    'stringifyQueryRouteParts',
+    'sumQueryDevtoolsStats',
+    'switchQueryDevtoolsAuthSession',
+    'tombstoneOf',
+    'writeQueryDevtoolsStore',
+]);
+//# sourceMappingURL=moved-names.js.map

package/generators/move-devtools-contract-imports/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "move-devtools-contract-imports",
+  "title": "Move devtools contract imports to @ethlete/query/devtools-contract",
+  "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"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators/report-legacy-query-apis/migration.js

@@ -0,0 +1,256 @@
+import { joinPathFragments } from '@nx/devkit';
+import { writeFileSync } from 'fs';
+import { dirname } from 'path';
+import * as ts from 'typescript';
+import { createMigrationScope } from '../migrate-to-query-v3/migration-scope.js';
+import { QUERY_V3_MIGRATION_REPORT_PATH, QueryV3MigrationReport, } from '../migrate-to-query-v3/report.js';
+import { createSourceFile, getLineNumber, getLineNumberFromPosition } from '../migrate-to-query-v3/shared.js';
+const SOURCE = 'report-legacy-query-apis';
+const SCAN_FILE_ENV = 'ETHLETE_SCAN_FILE';
+const QUERY_PACKAGE = '@ethlete/query';
+const DOCS_URL = 'https://ethlete-sdk-docs.web.app';
+const GROUPS_DOCS = `${DOCS_URL}/query/groups`;
+const COLLECTIONS_GUIDE = `${DOCS_URL}/query/migrating-from-v2#query-collections`;
+const INFINITY_GUIDE = `${DOCS_URL}/query/migrating-from-v2#infinity-queries`;
+const TRIGGER_DOCS = `${DOCS_URL}/components/paged-query-trigger`;
+const ENTITY_GUIDE = `${DOCS_URL}/query/migrating-from-v2#entitystore-becomes-invalidates-and-tags`;
+const CACHING_DOCS = `${DOCS_URL}/query/caching`;
+const TEMPLATES_GUIDE = `${DOCS_URL}/query/migrating-from-v2#templates-read-signals-not-directives`;
+const COLLECTION_FNS = ['createQueryCollection', 'createQueryCollectionSignal', 'createQueryCollectionSubject'];
+const COLLECTION_STATE_FN = 'switchQueryCollectionState';
+const INFINITY_CONFIG_FN = 'createInfinityQueryConfig';
+const ENTITY_STORE_CLASS = 'EntityStore';
+const LEGACY_CREATOR_FN = 'createLegacyQueryCreator';
+const INFINITY_DIRECTIVE = 'InfinityQueryDirective';
+const INFINITY_TRIGGER_DIRECTIVE = 'InfinityQueryTriggerDirective';
+const QUERY_DIRECTIVE = 'QueryDirective';
+const QUERY_DIRECTIVE_PATTERN = /\*etQuery(?![\w-])|\[etQuery\](?=\s*=)/g;
+const INFINITY_DIRECTIVE_PATTERN = /\*etInfinityQuery(?![\w-])/g;
+const INFINITY_TRIGGER_PATTERN = /(?<![\w-])etInfinityQueryTrigger(?![\w-])|<et-infinity-query-trigger(?![\w-])/g;
+const ENTITY_ACTION = `Move every write into the store to \`invalidates\` on the mutation creator (${CACHING_DOCS}#invalidating-from-the-mutation) ` +
+    `and \`tags\` on the reads it changes (${CACHING_DOCS}#tags), and add \`withOptimisticUpdate\` where the UI must change ` +
+    `before the response (${CACHING_DOCS}#optimistic-updates) - see ${ENTITY_GUIDE}.`;
+const isScannableFile = (filePath) => /\.(ts|mts|cts)$/.test(filePath) && !filePath.endsWith('.d.ts');
+const collectQueryImports = (sourceFile) => {
+    const named = new Map();
+    const namespaces = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== QUERY_PACKAGE) {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings)) {
+            namespaces.add(bindings.name.text);
+            continue;
+        }
+        for (const element of bindings.elements) {
+            named.set(element.name.text, (element.propertyName ?? element.name).text);
+        }
+    }
+    return { named, namespaces };
+};
+const importedNameOf = (expression, imports) => {
+    if (ts.isIdentifier(expression))
+        return imports.named.get(expression.text);
+    if (ts.isPropertyAccessExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        imports.namespaces.has(expression.expression.text)) {
+        return expression.name.text;
+    }
+    return undefined;
+};
+const hasImported = (imports, exportName) => imports.namespaces.size > 0 || [...imports.named.values()].includes(exportName);
+const declaredNameOf = (node) => {
+    const parent = node.parent;
+    if ((ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) &&
+        parent.initializer === node &&
+        (ts.isIdentifier(parent.name) || ts.isPrivateIdentifier(parent.name))) {
+        return parent.name.text;
+    }
+    return undefined;
+};
+const propertyNamed = (literal, name) => literal.properties.find((property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) &&
+    ts.isIdentifier(property.name) &&
+    property.name.text === name);
+const isEntityConfigCall = (call, config, imports) => importedNameOf(call.expression, imports) === LEGACY_CREATOR_FN ||
+    (ts.isPropertyAccessExpression(call.expression) && propertyNamed(config, 'route') !== undefined);
+const scanSource = (options) => {
+    const { tree, filePath, sourceFile, imports, report } = options;
+    const at = (node) => [{ filePath, line: getLineNumber(node, sourceFile) }];
+    const keyOf = (kind, node) => `${SOURCE}:${kind}:${filePath}:${node.getStart(sourceFile)}`;
+    const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const importedName = importedNameOf(node.expression, imports);
+            const name = declaredNameOf(node);
+            if (importedName && COLLECTION_FNS.includes(importedName)) {
+                report.addFollowUp({
+                    title: `Replace the query collection ${name ?? importedName}`,
+                    summary: `${name ? `\`${name}\` is built with` : 'This call is'} \`${importedName}\`, a legacy query collection. v3 has no query collections.`,
+                    action: `Move an action set where the latest run wins to \`createQueryGroup\` (${GROUPS_DOCS}), a query picked by context to a \`computed\`, and an auth collection to \`createBearerAuthProvider\` - see ${COLLECTIONS_GUIDE}.`,
+                    locations: at(node),
+                    source: SOURCE,
+                    dedupeKey: keyOf('collection', node),
+                });
+            }
+            if (importedName === COLLECTION_STATE_FN) {
+                report.addFollowUp({
+                    title: `Replace switchQueryCollectionState()`,
+                    summary: `\`switchQueryCollectionState()\` reads the state of the query collection member that ran last.`,
+                    action: `Read \`succeeded$\`, \`loading()\` or \`error()\` of the query group that replaces the collection (${GROUPS_DOCS}) - see ${COLLECTIONS_GUIDE}.`,
+                    locations: at(node),
+                    source: SOURCE,
+                    dedupeKey: keyOf('collection-state', node),
+                });
+            }
+            if (importedName === INFINITY_CONFIG_FN) {
+                report.addFollowUp({
+                    title: `Replace the infinity query ${name ?? importedName}`,
+                    summary: `${name ? `\`${name}\` is built with` : 'This call is'} \`createInfinityQueryConfig\`, the legacy infinite query.`,
+                    action: `Move it to \`createPagedQueryStack\` and bind \`[etPagedQueryTrigger]\` to the stack (${TRIGGER_DOCS}) - see ${INFINITY_GUIDE}.`,
+                    locations: at(node),
+                    source: SOURCE,
+                    dedupeKey: keyOf('infinity-config', node),
+                });
+            }
+            const [config] = node.arguments;
+            if (config && ts.isObjectLiteralExpression(config) && isEntityConfigCall(node, config, imports)) {
+                const entity = propertyNamed(config, 'entity');
+                if (entity) {
+                    report.addFollowUp({
+                        title: `Replace the entity config of ${name ?? 'the query creator'}`,
+                        summary: `${name ? `\`${name}\` has` : 'This query creator has'} an \`entity\` config that writes its response into a legacy EntityStore. v3 has no entity store.`,
+                        action: ENTITY_ACTION,
+                        locations: at(entity),
+                        source: SOURCE,
+                        dedupeKey: keyOf('entity-config', entity),
+                    });
+                }
+            }
+        }
+        if (ts.isNewExpression(node) && importedNameOf(node.expression, imports) === ENTITY_STORE_CLASS) {
+            const name = declaredNameOf(node);
+            report.addFollowUp({
+                title: `Replace the entity store ${name ?? ENTITY_STORE_CLASS}`,
+                summary: `${name ? `\`${name}\` is` : 'This is'} a legacy \`EntityStore\`. v3 has no entity store.`,
+                action: ENTITY_ACTION,
+                locations: at(node),
+                source: SOURCE,
+                dedupeKey: keyOf('entity-store', node),
+            });
+        }
+        if (ts.isDecorator(node)) {
+            scanComponentTemplate({ tree, filePath, sourceFile, decorator: node, imports, report });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+};
+const scanComponentTemplate = (options) => {
+    const { tree, filePath, sourceFile, decorator, imports, report } = options;
+    const usesDirective = hasImported(imports, INFINITY_DIRECTIVE);
+    const usesTrigger = hasImported(imports, INFINITY_TRIGGER_DIRECTIVE);
+    const usesQueryDirective = hasImported(imports, QUERY_DIRECTIVE);
+    if (!usesDirective && !usesTrigger && !usesQueryDirective)
+        return;
+    const call = decorator.expression;
+    if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== 'Component')
+        return;
+    const [metadata] = call.arguments;
+    if (!metadata || !ts.isObjectLiteralExpression(metadata))
+        return;
+    const template = propertyNamed(metadata, 'template');
+    const templateUrl = propertyNamed(metadata, 'templateUrl');
+    let scanned;
+    if (template &&
+        ts.isPropertyAssignment(template) &&
+        (ts.isStringLiteral(template.initializer) || ts.isNoSubstitutionTemplateLiteral(template.initializer))) {
+        scanned = { text: template.initializer.text, filePath, firstLine: getLineNumber(template.initializer, sourceFile) };
+    }
+    if (templateUrl &&
+        ts.isPropertyAssignment(templateUrl) &&
+        (ts.isStringLiteral(templateUrl.initializer) || ts.isNoSubstitutionTemplateLiteral(templateUrl.initializer))) {
+        const templatePath = joinPathFragments(dirname(filePath), templateUrl.initializer.text);
+        const text = tree.read(templatePath, 'utf-8');
+        if (text !== null)
+            scanned = { text, filePath: templatePath, firstLine: 1 };
+    }
+    if (!scanned)
+        return;
+    const { text, firstLine } = scanned;
+    const templatePath = scanned.filePath;
+    const matches = (pattern) => Array.from(text.matchAll(pattern), (match) => ({
+        line: firstLine + getLineNumberFromPosition(text, match.index) - 1,
+    }));
+    if (usesDirective) {
+        for (const { line } of matches(INFINITY_DIRECTIVE_PATTERN)) {
+            report.addFollowUp({
+                title: 'Replace *etInfinityQuery',
+                summary: 'The template renders a legacy infinite query through `*etInfinityQuery`.',
+                action: `Render the items of the paged query stack that replaces the config with \`@for (item of stack.items(); track item.id)\` - see ${INFINITY_GUIDE}.`,
+                locations: [{ filePath: templatePath, line }],
+                source: SOURCE,
+                dedupeKey: `${SOURCE}:infinity-directive:${templatePath}:${line}`,
+            });
+        }
+    }
+    if (usesQueryDirective) {
+        for (const { line } of matches(QUERY_DIRECTIVE_PATTERN)) {
+            report.addFollowUp({
+                title: 'Replace *etQuery',
+                summary: 'The template renders a query through `*etQuery`, which accepts only legacy queries. Moving its creator off the interop breaks this template.',
+                action: `Read the query's \`loading()\`, \`error()\` and \`response()\` signals in \`@if\` / \`@switch\` blocks - see ${TEMPLATES_GUIDE}.`,
+                locations: [{ filePath: templatePath, line }],
+                source: SOURCE,
+                dedupeKey: `${SOURCE}:query-directive:${templatePath}:${line}`,
+            });
+        }
+    }
+    if (usesTrigger) {
+        for (const { line } of matches(INFINITY_TRIGGER_PATTERN)) {
+            report.addFollowUp({
+                title: 'Replace etInfinityQueryTrigger with etPagedQueryTrigger',
+                summary: '`etInfinityQueryTrigger` loads the next page of a legacy infinite query.',
+                action: `Bind \`[etPagedQueryTrigger]\` to the paged query stack and drop the \`@if (canLoadMore && !loading)\` around it; a trigger on a button becomes \`(click)="stack.fetchNextPage()"\` with \`[etQueryButton]\` - see ${TRIGGER_DOCS}.`,
+                locations: [{ filePath: templatePath, line }],
+                source: SOURCE,
+                dedupeKey: `${SOURCE}:infinity-trigger:${templatePath}:${line}`,
+            });
+        }
+    }
+};
+export const reportLegacyQueryApis = (tree, scope) => {
+    const report = new QueryV3MigrationReport();
+    scope.visit(tree, (filePath) => {
+        if (!isScannableFile(filePath))
+            return;
+        const content = tree.read(filePath, 'utf-8');
+        if (!content || (!content.includes(QUERY_PACKAGE) && !content.includes('entity')))
+            return;
+        const sourceFile = createSourceFile(content, filePath);
+        scanSource({ tree, filePath, sourceFile, imports: collectQueryImports(sourceFile), report });
+    });
+    return report;
+};
+export default async function migrate(tree, schema) {
+    console.log('\n🔄 Reporting legacy query collections, infinity queries, *etQuery templates and entity stores...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const report = reportLegacyQueryApis(tree, scope);
+    const scanFile = process.env[SCAN_FILE_ENV];
+    if (scanFile) {
+        const files = new Set(report.tasks.flatMap((task) => task.locations.map((location) => location.filePath)));
+        writeFileSync(scanFile, JSON.stringify([...files].sort()), 'utf8');
+        return;
+    }
+    if (report.tasks.length === 0 && !tree.exists(QUERY_V3_MIGRATION_REPORT_PATH)) {
+        console.log('   Nothing found.');
+        return;
+    }
+    report.writeToTree(tree, `${SOURCE} in ${scope.describe()}`);
+    report.printSummary();
+}
+//# sourceMappingURL=migration.js.map