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

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,160 @@
+import * as ts from 'typescript';
+import { createSourceFile } from './shared.js';
+const REFRESH_CONFIG_KEYS = new Set([
+    'queryCreator',
+    'responseAdapter',
+    'requestArgsAdapter',
+    'cookieName',
+    'cookieDomain',
+    'cookieExpiresInDays',
+    'expiresInPropertyName',
+    'cookiePath',
+    'cookieSameSite',
+    'cookieEnabled',
+    'refreshBuffer',
+]);
+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) => {
+        const isShorthand = ts.isShorthandPropertyAssignment(property);
+        if ((!ts.isPropertyAssignment(property) && !isShorthand) || !ts.isIdentifier(property.name)) {
+            return;
+        }
+        const key = property.name.text;
+        if (!REFRESH_CONFIG_KEYS.has(key)) {
+            return;
+        }
+        const value = isShorthand ? property.name : property.initializer;
+        const text = value.getText(sourceFile);
+        if (key === 'queryCreator') {
+            if (ts.isIdentifier(value)) {
+                config.refreshCreatorName = value.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) => {
+    const warnings = [];
+    if (!config?.refreshCreatorName) {
+        return {
+            queries: '  queries: [],',
+            features: '',
+            importsNeeded: [],
+            isScaffolded: false,
+            warnings,
+        };
+    }
+    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},`);
+    }
+    if (config.refreshBuffer) {
+        refreshEntries.push(`      refreshStrategy: ${renderRefreshStrategy(config.refreshBuffer)},`);
+    }
+    if (config.cookieName && config.cookieEnabled && config.cookieEnabled !== 'true') {
+        warnings.push({
+            title: 'Replace the v2 cookieEnabled switch',
+            summary: `The v2 provider set \`cookieEnabled: ${config.cookieEnabled}\`. \`withPersistentAuth\` has no switch for it: it always keeps the refresh token in the cookie, and \`setRememberMe(false)\` only turns that cookie into a session cookie. v2's \`enableCookie()\` / \`disableCookie()\` have no v3 counterpart either.`,
+            action: 'If the cookie was only written after an opt-in (a "remember me" box), drive `setRememberMe()` from it. If it was never written, remove `withPersistentAuth` from the scaffold.',
+        });
+    }
+    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, warnings };
+    }
+    const cookieEntries = [`      name: ${config.cookieName},`];
+    if (config.cookieDomain)
+        cookieEntries.push(`      domain: ${config.cookieDomain},`);
+    if (config.cookieExpiresInDays)
+        cookieEntries.push(`      expiresInDays: ${config.cookieExpiresInDays},`);
+    if (config.cookiePath)
+        cookieEntries.push(`      path: ${config.cookiePath},`);
+    if (config.cookieSameSite)
+        cookieEntries.push(`      sameSite: ${config.cookieSameSite},`);
+    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, warnings };
+};
+// A v3 `refreshStrategy` number from 0 to 1 is a fraction of the token lifetime, not milliseconds.
+const renderRefreshStrategy = (refreshBuffer) => {
+    const value = Number(refreshBuffer.replace(/_/g, ''));
+    return Number.isFinite(value) && value > 1
+        ? refreshBuffer
+        : `{ minBufferMs: ${refreshBuffer}, maxBufferMs: ${refreshBuffer} }`;
+};
+//# sourceMappingURL=auth-provider-scaffold.js.map