@ethlete/query 6.0.0-next.2 → 6.0.0-next.20

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

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

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

@@ -0,0 +1,136 @@
+export const QUERY_V3_MIGRATION_REPORT_PATH = 'query-v3-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) => {
+        const lineSuffix = location.line ? `:${location.line}` : '';
+        return `- ${location.filePath}${lineSuffix}`;
+    })
+        .join('\n');
+};
+export class QueryV3MigrationReport {
+    constructor() {
+        this.tasks = [];
+    }
+    addTask(input) {
+        const dedupeKey = input.dedupeKey ?? `${input.kind}:${input.title}:${input.summary}:${input.action}`;
+        if (this.tasks.some((task) => task.dedupeKey === dedupeKey)) {
+            return;
+        }
+        const nextTask = {
+            id: `QV3-${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,
+        };
+        this.tasks.push(nextTask);
+    }
+    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_V3_MIGRATION_REPORT_PATH} for the AI-ready follow-up list.`);
+    }
+    writeToTree(tree) {
+        tree.write(QUERY_V3_MIGRATION_REPORT_PATH, renderMigrationReportMarkdown(this.tasks));
+    }
+}
+export const renderMigrationReportMarkdown = (tasks) => {
+    const header = [
+        '# Query V3 Migration Follow-Up',
+        '',
+        'This file is generated by the `migrate-to-query-v3` generator.',
+        '',
+        '## 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.',
+        '5. Preserve unrelated user changes. Do not rewrite generated files wholesale unless required.',
+        '',
+        '## 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) => {
+        return [
+            `### ${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 locationLines = task.locations.length === 0 ? ['      []'] : [];
+            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 : locationLines),
+            ];
+        }),
+        '```',
+        '',
+    ].join('\n');
+    return `${header}## Tasks\n\n${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

@@ -0,0 +1,97 @@
+import * as ts from 'typescript';
+const TEMP_SOURCE_FILE = 'temp.ts';
+export const createSourceFile = (content, filePath = TEMP_SOURCE_FILE) => ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+export const capitalizeFirstLetter = (value) => {
+    if (value.length === 0) {
+        return value;
+    }
+    return `${value[0].toUpperCase()}${value.slice(1)}`;
+};
+export const ensureConfigSuffix = (name) => {
+    if (/Config$/i.test(name)) {
+        return name;
+    }
+    return `${name}Config`;
+};
+export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier }) => {
+    const sourceFile = createSourceFile(content);
+    let importNode;
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isImportDeclaration(node) &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            node.moduleSpecifier.text === moduleSpecifier) {
+            importNode = node;
+        }
+    });
+    const missingImports = new Set(importsNeeded);
+    if (importNode?.importClause?.namedBindings && ts.isNamedImports(importNode.importClause.namedBindings)) {
+        const namedBindings = importNode.importClause.namedBindings;
+        namedBindings.elements.forEach((element) => {
+            missingImports.delete(element.name.text);
+        });
+        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}';`;
+        return content.slice(0, importNode.getStart(sourceFile)) + nextImportStatement + content.slice(importNode.getEnd());
+    }
+    let lastImportEnd = 0;
+    ts.forEachChild(sourceFile, (node) => {
+        if (!ts.isImportDeclaration(node)) {
+            return;
+        }
+        const end = node.getEnd();
+        if (end > lastImportEnd) {
+            lastImportEnd = end;
+        }
+    });
+    const nextImportStatement = `\nimport { ${Array.from(missingImports).sort().join(', ')} } from '${moduleSpecifier}';`;
+    if (lastImportEnd > 0) {
+        return content.slice(0, lastImportEnd) + nextImportStatement + content.slice(lastImportEnd);
+    }
+    return `import { ${Array.from(missingImports).sort().join(', ')} } from '${moduleSpecifier}';\n\n${content}`;
+};
+export const ensureImportFromQuery = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@ethlete/query' });
+export const ensureAngularCoreImports = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@angular/core' });
+export const getVariableStatementEnd = (sourceFile, variableName, initializerName) => {
+    let variableStatementEnd;
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text === variableName &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            ts.isIdentifier(node.initializer.expression) &&
+            node.initializer.expression.text === initializerName) {
+            let parent = node.parent;
+            while (parent && !ts.isVariableStatement(parent)) {
+                parent = parent.parent;
+            }
+            if (parent && ts.isVariableStatement(parent)) {
+                variableStatementEnd = parent.getEnd();
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return variableStatementEnd;
+};
+export const getIndentation = (content, position) => {
+    let lineStart = position;
+    while (lineStart > 0 && content[lineStart - 1] !== '\n') {
+        lineStart -= 1;
+    }
+    let indentation = '';
+    for (let index = lineStart; index < position && /\s/.test(content[index]); index += 1) {
+        indentation += content[index];
+    }
+    return indentation || '  ';
+};
+export const getLineNumber = (node, sourceFile) => {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    return line + 1;
+};
+export const getLineNumberFromPosition = (content, position) => content.slice(0, position).split('\n').length;
+//# sourceMappingURL=shared.js.map

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

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

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.2",
+  "version": "6.0.0-next.20",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
-    "@analogjs/vite-plugin-angular": "2.3.1",
-    "@angular/common": "21.2.1",
-    "@angular/core": "21.2.1",
-    "@angular/forms": "21.2.1",
-    "@angular/router": "21.2.1",
-    "@ethlete/core": "^5.0.0-next.0",
-    "@ethlete/types": "^2.0.0-next.0",
-    "@nx/devkit": "22.5.4",
-    "@nx/vite": "22.5.4",
+    "@analogjs/vite-plugin-angular": "2.6.3",
+    "@angular/common": "22.0.7",
+    "@angular/core": "22.0.7",
+    "@angular/forms": "22.0.7",
+    "@angular/router": "22.0.7",
+    "@ethlete/core": "^5.0.0-beta.11",
+    "@ethlete/types": "^2.0.0-beta.4",
+    "@nx/devkit": "23.1.0",
     "rxjs": "7.8.2",
     "socket.io-client": "4.8.3",
-    "typescript": "5.9.3",
-    "vite": "^7.0.0"
+    "typescript": "6.0.3",
+    "vite": "8.1.5"
   },
   "generators": "./generators/generators.json",
   "module": "fesm2022/ethlete-query.mjs",
@@ -34,6 +33,7 @@
       "default": "./fesm2022/ethlete-query-testing.mjs"
     }
   },
+  "type": "module",
   "dependencies": {
     "tslib": "^2.3.0"
   }