@ethlete/core 5.0.0-next.61 → 5.0.0-next.63

package/generators/generators.json

@@ -11,11 +11,21 @@
       "schema": "./migrate-provider-shape/schema.json",
       "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape"
     },
+    "migrate-create-destroy": {
+      "implementation": "./migrate-create-destroy/migration",
+      "schema": "./migrate-create-destroy/schema.json",
+      "description": "Rewrite takeUntil(this.destroy$) on a createDestroy() field into takeUntilDestroyed()"
+    },
     "migrate-surface-interaction-swatch": {
       "implementation": "./migrate-surface-interaction-swatch/migration",
       "schema": "./migrate-surface-interaction-swatch/schema.json",
       "description": "Rewrite surface theme interactionColor maps into the { color, onColor, inkColor } swatch shape"
     },
+    "migrate-legacy-color-themes": {
+      "implementation": "./migrate-legacy-color-themes/migration",
+      "schema": "./migrate-legacy-color-themes/schema.json",
+      "description": "Rewrite provideColorThemes into provideColorThemesWithTailwind4 and list the Tailwind 4 setup that is left"
+    },
     "tailwind-4-color-theme": {
       "implementation": "./tailwind-4-color-theme/generator",
       "schema": "./tailwind-4-color-theme/schema.json",

package/generators/migrate-create-destroy/create-destroy.js

@@ -0,0 +1,317 @@
+import * as ts from 'typescript';
+const isEthleteModule = (specifier) => specifier.startsWith('@ethlete/');
+const isRxjsModule = (specifier) => specifier === 'rxjs' || specifier === 'rxjs/operators';
+const importedLocalNames = (sourceFile, accepts, importedName) => {
+    const names = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (!accepts(statement.moduleSpecifier.text))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if ((element.propertyName ?? element.name).text === importedName)
+                names.add(element.name.text);
+        }
+    }
+    return names;
+};
+const lineOf = (sourceFile, node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+const isCallTo = (node, names) => !!node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && names.has(node.expression.text);
+const hasModifier = (node, kind) => !!node.modifiers?.some((m) => m.kind === kind);
+const rebindsThis = (node) => ts.isClassLike(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isFunctionDeclaration(node) ||
+    ((ts.isMethodDeclaration(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node)) &&
+        ts.isObjectLiteralExpression(node.parent));
+const collectThisAccesses = (cls, names) => {
+    const uses = new Map();
+    const visit = (node, injection) => {
+        if (rebindsThis(node))
+            return;
+        if (ts.isArrowFunction(node))
+            injection = false;
+        if (ts.isPropertyAccessExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ThisKeyword &&
+            names.has(node.name.text)) {
+            const list = uses.get(node.name.text) ?? [];
+            list.push({ node, injection });
+            uses.set(node.name.text, list);
+        }
+        ts.forEachChild(node, (child) => visit(child, injection));
+    };
+    for (const member of cls.members) {
+        if (hasModifier(member, ts.SyntaxKind.StaticKeyword))
+            continue;
+        if (ts.isPropertyDeclaration(member)) {
+            if (member.initializer)
+                visit(member.initializer, true);
+        }
+        else if (ts.isConstructorDeclaration(member)) {
+            if (member.body)
+                visit(member.body, true);
+        }
+        else {
+            ts.forEachChild(member, (child) => visit(child, false));
+        }
+    }
+    return uses;
+};
+const memberName = (member) => member.name && (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name)) ? member.name.text : null;
+const lineRange = (content, node, sourceFile) => {
+    let start = node.getStart(sourceFile, true);
+    let end = node.getEnd();
+    while (start > 0 && content[start - 1] !== '\n')
+        start--;
+    while (end < content.length && content[end] !== '\n')
+        end++;
+    if (content[end] === '\n')
+        end++;
+    return { start, end };
+};
+const migrateClass = (cls, ctx) => {
+    const destroyFields = [];
+    const takenNames = new Set();
+    let existingRefName = null;
+    for (const member of cls.members) {
+        const name = memberName(member);
+        if (name)
+            takenNames.add(name);
+        if (!ts.isPropertyDeclaration(member) || !name || hasModifier(member, ts.SyntaxKind.StaticKeyword))
+            continue;
+        const initializer = member.initializer;
+        if (isCallTo(initializer, ctx.destroyFns) && initializer.arguments.length === 0) {
+            destroyFields.push(member);
+            ctx.handledCalls.add(initializer);
+        }
+        else if (initializer &&
+            ts.isCallExpression(initializer) &&
+            ts.isIdentifier(initializer.expression) &&
+            initializer.expression.text === 'inject' &&
+            initializer.arguments.length === 1 &&
+            ts.isIdentifier(initializer.arguments[0]) &&
+            initializer.arguments[0].text === 'DestroyRef' &&
+            existingRefName === null &&
+            !ts.isPrivateIdentifier(member.name)) {
+            existingRefName = name;
+        }
+    }
+    if (destroyFields.length === 0)
+        return;
+    const uses = collectThisAccesses(cls, new Set(destroyFields.map((field) => memberName(field))));
+    const isTakeUntilArg = (use) => isCallTo(use.node.parent, ctx.takeUntilFns) &&
+        use.node.parent.arguments.length === 1 &&
+        use.node.parent.arguments[0] === use.node;
+    const needsRef = [...uses.values()].some((list) => list.some((use) => isTakeUntilArg(use) && !use.injection));
+    let refName = existingRefName;
+    if (needsRef && !refName) {
+        const first = memberName(destroyFields[0]);
+        const base = first.startsWith('_') || first.startsWith('#') ? '_destroyRef' : 'destroyRef';
+        let candidate = base;
+        let suffix = 2;
+        while (takenNames.has(candidate))
+            candidate = `${base}${suffix++}`;
+        refName = candidate;
+    }
+    let refDeclared = existingRefName !== null || !needsRef;
+    for (const field of destroyFields) {
+        const name = memberName(field);
+        const fieldUses = uses.get(name) ?? [];
+        const takeUntilUses = fieldUses.filter(isTakeUntilArg);
+        const otherUses = fieldUses.filter((use) => !isTakeUntilArg(use));
+        const isPrivate = hasModifier(field, ts.SyntaxKind.PrivateKeyword) || ts.isPrivateIdentifier(field.name);
+        const removable = isPrivate && otherUses.length === 0;
+        for (const use of takeUntilUses) {
+            const call = use.node.parent;
+            ctx.edits.push({
+                start: call.getStart(ctx.sourceFile),
+                end: call.getEnd(),
+                text: `takeUntilDestroyed(${use.injection ? '' : `this.${refName}`})`,
+            });
+            ctx.needs.takeUntilDestroyed = true;
+        }
+        for (const use of otherUses) {
+            ctx.tasks.push({
+                id: `create-destroy:${ctx.filePath}:${lineOf(ctx.sourceFile, use.node)}`,
+                file: ctx.filePath,
+                line: lineOf(ctx.sourceFile, use.node),
+                message: `\`this.${name}\` is used other than as \`takeUntil(this.${name})\`, so the field stays. Replace the use by hand.`,
+            });
+        }
+        if (!isPrivate) {
+            ctx.tasks.push({
+                id: `create-destroy:${ctx.filePath}:${lineOf(ctx.sourceFile, field)}`,
+                file: ctx.filePath,
+                line: lineOf(ctx.sourceFile, field),
+                message: `\`${name}\` is not private, so it may be used outside this class and the field stays.`,
+            });
+        }
+        const readonly = hasModifier(field, ts.SyntaxKind.ReadonlyKeyword) ? 'readonly ' : '';
+        const refDeclaration = `private ${readonly}${refName} = inject(DestroyRef);`;
+        const placesRef = !refDeclared;
+        if (placesRef) {
+            refDeclared = true;
+            ctx.needs.destroyRef = true;
+        }
+        if (removable && placesRef) {
+            ctx.edits.push({
+                start: field.getStart(ctx.sourceFile),
+                end: field.getEnd(),
+                text: refDeclaration,
+            });
+        }
+        else if (removable) {
+            const { start, end } = lineRange(ctx.content, field, ctx.sourceFile);
+            ctx.edits.push({ start, end, text: '' });
+        }
+        else if (placesRef) {
+            ctx.edits.push({ start: field.getEnd(), end: field.getEnd(), text: `\n${refDeclaration}` });
+        }
+    }
+};
+const countIdentifier = (sourceFile, name) => {
+    let count = 0;
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node))
+            return;
+        if (ts.isIdentifier(node) && node.text === name)
+            count++;
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return count;
+};
+const applyEdits = (content, edits) => [...edits]
+    .sort((a, b) => b.start - a.start)
+    .reduce((text, edit) => text.slice(0, edit.start) + edit.text + text.slice(edit.end), content);
+const removeUnusedImports = (filePath, content) => {
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const edits = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const module = statement.moduleSpecifier.text;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        const removeName = isEthleteModule(module) ? 'createDestroy' : isRxjsModule(module) ? 'takeUntil' : null;
+        if (!removeName)
+            continue;
+        const unused = bindings.elements.filter((element) => (element.propertyName ?? element.name).text === removeName &&
+            countIdentifier(sourceFile, element.name.text) === 0);
+        if (unused.length === 0)
+            continue;
+        const kept = bindings.elements.filter((element) => !unused.includes(element));
+        if (kept.length === 0 && !statement.importClause?.name) {
+            const { start, end } = lineRange(content, statement, sourceFile);
+            edits.push({ start, end, text: '' });
+        }
+        else {
+            edits.push({
+                start: bindings.getStart(sourceFile),
+                end: bindings.getEnd(),
+                text: `{ ${kept.map((element) => element.getText(sourceFile)).join(', ')} }`,
+            });
+        }
+    }
+    return applyEdits(content, edits);
+};
+const addImports = (filePath, content, wanted) => {
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const edits = [];
+    const fresh = new Map();
+    const joined = new Map();
+    for (const { module, name } of wanted) {
+        const declaration = sourceFile.statements.find((statement) => ts.isImportDeclaration(statement) &&
+            ts.isStringLiteral(statement.moduleSpecifier) &&
+            statement.moduleSpecifier.text === module &&
+            !statement.importClause?.isTypeOnly &&
+            !!statement.importClause?.namedBindings &&
+            ts.isNamedImports(statement.importClause.namedBindings));
+        const bindings = declaration?.importClause?.namedBindings;
+        if (!declaration || !bindings) {
+            fresh.set(module, [...(fresh.get(module) ?? []), name]);
+            continue;
+        }
+        if (bindings.elements.some((element) => element.name.text === name && !element.propertyName))
+            continue;
+        joined.set(declaration, [...(joined.get(declaration) ?? []), name]);
+    }
+    for (const [declaration, names] of joined) {
+        const bindings = declaration.importClause.namedBindings;
+        const texts = bindings.elements.map((element) => element.getText(sourceFile));
+        const sorted = [...texts].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+        const wasSorted = texts.every((text, index) => text === sorted[index]);
+        const merged = wasSorted
+            ? [...texts, ...names].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))
+            : [...texts, ...names];
+        edits.push({ start: bindings.getStart(sourceFile), end: bindings.getEnd(), text: `{ ${merged.join(', ')} }` });
+    }
+    if (fresh.size > 0) {
+        const anchor = sourceFile.statements.filter(ts.isImportDeclaration).at(-1);
+        const position = anchor ? anchor.getEnd() : 0;
+        const lines = [...fresh].map(([module, names]) => `import { ${[...new Set(names)].join(', ')} } from '${module}';`);
+        edits.push({
+            start: position,
+            end: position,
+            text: anchor ? `\n${lines.join('\n')}` : `${lines.join('\n')}\n`,
+        });
+    }
+    return applyEdits(content, edits);
+};
+/**
+ * Rewrites `takeUntil(this.<createDestroy field>)` into `takeUntilDestroyed(…)` in one file and drops
+ * the field once nothing else uses it. Every other use of the field is reported, never rewritten.
+ */
+export const migrateCreateDestroyInFile = (filePath, content) => {
+    if (!content.includes('createDestroy'))
+        return { content, changed: false, tasks: [] };
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const destroyFns = importedLocalNames(sourceFile, isEthleteModule, 'createDestroy');
+    if (destroyFns.size === 0)
+        return { content, changed: false, tasks: [] };
+    const ctx = {
+        sourceFile,
+        content,
+        filePath,
+        destroyFns,
+        takeUntilFns: importedLocalNames(sourceFile, isRxjsModule, 'takeUntil'),
+        edits: [],
+        tasks: [],
+        handledCalls: new Set(),
+        needs: { takeUntilDestroyed: false, destroyRef: false },
+    };
+    const visit = (node) => {
+        if (ts.isClassLike(node))
+            migrateClass(node, ctx);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const visitCalls = (node) => {
+        if (isCallTo(node, destroyFns) && !ctx.handledCalls.has(node)) {
+            ctx.tasks.push({
+                id: `create-destroy:${filePath}:${lineOf(sourceFile, node)}`,
+                file: filePath,
+                line: lineOf(sourceFile, node),
+                message: 'This `createDestroy()` call is not a plain class field, so it was left alone.',
+            });
+        }
+        ts.forEachChild(node, visitCalls);
+    };
+    visitCalls(sourceFile);
+    if (ctx.edits.length === 0)
+        return { content, changed: false, tasks: ctx.tasks };
+    const wanted = [
+        ...(ctx.needs.takeUntilDestroyed ? [{ module: '@angular/core/rxjs-interop', name: 'takeUntilDestroyed' }] : []),
+        ...(ctx.needs.destroyRef
+            ? [
+                { module: '@angular/core', name: 'DestroyRef' },
+                { module: '@angular/core', name: 'inject' },
+            ]
+            : []),
+    ];
+    const updated = addImports(filePath, removeUnusedImports(filePath, applyEdits(content, ctx.edits)), wanted);
+    return { content: updated, changed: updated !== content, tasks: ctx.tasks };
+};

package/generators/migrate-create-destroy/migration.js

@@ -0,0 +1,46 @@
+import { formatFiles } from '@nx/devkit';
+import { createMigrationScope } from '../migrate-provider-shape/migration-scope.js';
+import { migrateCreateDestroyInFile } from './create-destroy.js';
+export const CREATE_DESTROY_REPORT_PATH = 'create-destroy-migration-tasks.md';
+const renderReport = (tasks) => [
+    '# createDestroy migration tasks',
+    '',
+    'The codemod rewrote every `takeUntil(this.<destroy field>)` into `takeUntilDestroyed(…)`. The sites below',
+    'use the field in another way (`.next()`, passed on, piped), so they were left alone and the field stays.',
+    '',
+    ...tasks.map((task) => [`## \`${task.id}\``, '', `- ${task.file}:${task.line}`, `- ${task.message}`, ''].join('\n')),
+].join('\n');
+export default async function migrateCreateDestroy(tree, schema) {
+    console.log('\n🔄 Migrating createDestroy to takeUntilDestroyed...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const tasks = [];
+    let filesChanged = 0;
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.d.ts'))
+            return;
+        const before = tree.read(filePath, 'utf-8');
+        if (!before)
+            return;
+        const result = migrateCreateDestroyInFile(filePath, before);
+        tasks.push(...result.tasks);
+        if (result.changed) {
+            tree.write(filePath, result.content);
+            filesChanged++;
+            console.log(`   ✓ ${filePath}`);
+        }
+    });
+    if (tasks.length > 0) {
+        tree.write(CREATE_DESTROY_REPORT_PATH, renderReport(tasks));
+        for (const task of tasks) {
+            console.warn(`   ⚠️  ${task.file}:${task.line} ${task.message}`);
+        }
+    }
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    console.log(`\n✅ Rewrote ${filesChanged} file(s).`);
+    if (tasks.length > 0) {
+        console.log(`⚠️  ${tasks.length} site(s) need a manual decision - see ${CREATE_DESTROY_REPORT_PATH}.`);
+    }
+}

package/generators/migrate-create-destroy/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-create-destroy",
+  "title": "Migrate createDestroy to takeUntilDestroyed",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace. Every class is rewritten independently, so any scope is safe.",
+      "alias": "project"
+    },
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path prefixes to migrate, relative to the workspace root (e.g. 'libs/ui'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators/migrate-legacy-color-themes/legacy-color-themes.js

@@ -0,0 +1,123 @@
+import { Node, Project, SyntaxKind } from 'ts-morph';
+const CORE_PACKAGE = '@ethlete/core';
+const LEGACY_PROVIDER = 'provideColorThemes';
+const TAILWIND_4_PROVIDER = 'provideColorThemesWithTailwind4';
+const SURFACE_PROVIDER = 'provideSurfaceThemesWithTailwind4';
+const TAILWIND_3_HELPERS = ['createTailwindColorThemes', 'createTailwindCssVar', 'createTailwindRgbVar'];
+const createProject = () => new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+        target: 99,
+        module: 99,
+    },
+});
+const coreImports = (sourceFile) => sourceFile.getImportDeclarations().filter((declaration) => declaration.getModuleSpecifierValue() === CORE_PACKAGE);
+const namespaceNames = (imports) => imports.flatMap((declaration) => {
+    const namespace = declaration.getNamespaceImport();
+    return namespace ? [namespace.getText()] : [];
+});
+const isNamespaceMember = (identifier, namespaces) => {
+    const parent = identifier.getParent();
+    return (Node.isPropertyAccessExpression(parent) &&
+        parent.getNameNode() === identifier &&
+        namespaces.includes(parent.getExpression().getText()));
+};
+const isBareReference = (identifier) => {
+    const parent = identifier.getParent();
+    if (Node.isImportSpecifier(parent))
+        return false;
+    if (Node.isPropertyAccessExpression(parent) && parent.getNameNode() === identifier)
+        return false;
+    if (Node.isPropertyAssignment(parent) && parent.getNameNode() === identifier)
+        return false;
+    if (Node.isPropertyDeclaration(parent) || Node.isMethodDeclaration(parent))
+        return false;
+    return true;
+};
+const localNameOf = (specifier) => (specifier.getAliasNode() ?? specifier.getNameNode()).getText();
+const importSourceOf = (sourceFile, name) => sourceFile
+    .getImportDeclarations()
+    .find((declaration) => declaration.getNamedImports().some((specifier) => localNameOf(specifier) === name))
+    ?.getModuleSpecifierValue();
+const collectProviderSite = (filePath, sourceFile, identifier) => {
+    const reference = Node.isPropertyAccessExpression(identifier.getParent()) ? identifier.getParent() : identifier;
+    const call = reference.getParent();
+    const site = { file: filePath, line: identifier.getStartLineNumber() };
+    if (Node.isCallExpression(call) && call.getExpression() === reference) {
+        const [argument] = call.getArguments();
+        if (argument) {
+            site.themes = argument.getText();
+            if (Node.isIdentifier(argument))
+                site.themesFrom = importSourceOf(sourceFile, argument.getText());
+        }
+    }
+    return site;
+};
+/**
+ * Rewrites `provideColorThemes(X)` from `@ethlete/core` into `provideColorThemesWithTailwind4(X)`, fixing the
+ * import, and reports the sites plus the Tailwind 3 helpers that still need the Tailwind 4 setup by hand.
+ */
+export const migrateLegacyColorThemesInFile = (filePath, content) => {
+    const unchanged = { changed: false, content, providerSites: [], helperSites: [], providesSurfaceThemes: false };
+    if (!content.includes(CORE_PACKAGE))
+        return unchanged;
+    const sourceFile = createProject().createSourceFile(filePath, content);
+    const imports = coreImports(sourceFile);
+    if (imports.length === 0)
+        return unchanged;
+    const namespaces = namespaceNames(imports);
+    const specifiers = imports.flatMap((declaration) => declaration.getNamedImports());
+    const specifierOf = (name) => specifiers.find((specifier) => specifier.getNameNode().getText() === name);
+    const importedName = (name) => {
+        const specifier = specifierOf(name);
+        return specifier ? localNameOf(specifier) : undefined;
+    };
+    const helperSites = TAILWIND_3_HELPERS.flatMap((helper) => {
+        const local = importedName(helper);
+        return sourceFile
+            .getDescendantsOfKind(SyntaxKind.Identifier)
+            .filter((identifier) => (local !== undefined && identifier.getText() === local && isBareReference(identifier)) ||
+            (identifier.getText() === helper && isNamespaceMember(identifier, namespaces)))
+            .map((identifier) => ({ file: filePath, line: identifier.getStartLineNumber(), helper }));
+    });
+    const providesSurfaceThemes = importedName(SURFACE_PROVIDER) !== undefined ||
+        sourceFile
+            .getDescendantsOfKind(SyntaxKind.Identifier)
+            .some((identifier) => identifier.getText() === SURFACE_PROVIDER && isNamespaceMember(identifier, namespaces));
+    const legacySpecifier = specifierOf(LEGACY_PROVIDER);
+    const legacyLocal = legacySpecifier ? localNameOf(legacySpecifier) : undefined;
+    const isAliased = legacySpecifier?.getAliasNode() !== undefined;
+    const references = sourceFile
+        .getDescendantsOfKind(SyntaxKind.Identifier)
+        .filter((identifier) => (identifier.getText() === legacyLocal && isBareReference(identifier)) ||
+        (identifier.getText() === LEGACY_PROVIDER && isNamespaceMember(identifier, namespaces)));
+    if (!legacySpecifier && references.length === 0) {
+        return { ...unchanged, helperSites, providesSurfaceThemes };
+    }
+    const providerSites = references.map((identifier) => collectProviderSite(filePath, sourceFile, identifier));
+    const renamed = references.filter((identifier) => !isAliased || identifier.getText() !== legacyLocal);
+    for (const identifier of renamed.reverse()) {
+        const parent = identifier.getParent();
+        if (Node.isShorthandPropertyAssignment(parent)) {
+            parent.replaceWithText(`${identifier.getText()}: ${TAILWIND_4_PROVIDER}`);
+        }
+        else if (Node.isExportSpecifier(parent) && !parent.getAliasNode()) {
+            parent.replaceWithText(`${TAILWIND_4_PROVIDER} as ${identifier.getText()}`);
+        }
+        else {
+            identifier.replaceWithText(TAILWIND_4_PROVIDER);
+        }
+    }
+    if (legacySpecifier) {
+        if (!isAliased && importedName(TAILWIND_4_PROVIDER) === TAILWIND_4_PROVIDER) {
+            const declaration = legacySpecifier.getImportDeclaration();
+            legacySpecifier.remove();
+            if (declaration.getNamedImports().length === 0 && !declaration.getDefaultImport())
+                declaration.remove();
+        }
+        else {
+            legacySpecifier.setName(TAILWIND_4_PROVIDER);
+        }
+    }
+    return { changed: true, content: sourceFile.getFullText(), providerSites, helperSites, providesSurfaceThemes };
+};

package/generators/migrate-legacy-color-themes/migration.js

@@ -0,0 +1,93 @@
+import { formatFiles } from '@nx/devkit';
+import { writeFileSync } from 'fs';
+import { createMigrationScope } from '../migrate-provider-shape/migration-scope.js';
+import { migrateLegacyColorThemesInFile, } from './legacy-color-themes.js';
+export const LEGACY_COLOR_THEMES_REPORT_PATH = 'legacy-color-themes-migration-tasks.md';
+export const LEGACY_COLOR_THEMES_GUIDE = 'https://ethlete-sdk-docs.web.app/core/theming#migrating-from-runtime-theming';
+const SCAN_FILE_ENV = 'ETHLETE_SCAN_FILE';
+const generatorCommand = (site) => site.themesFrom
+    ? `nx g @ethlete/core:tailwind-4-color-theme --themesPath=<the file behind '${site.themesFrom}'>`
+    : 'nx g @ethlete/core:tailwind-4-color-theme --themesPath=<the file that exports the themes>';
+export const renderLegacyColorThemesReport = (findings) => [
+    '# Legacy color themes migration tasks',
+    '',
+    `The codemod rewrote \`provideColorThemes(…)\` into \`provideColorThemesWithTailwind4(…)\`. The new provider no`,
+    'longer injects the theme CSS at runtime, so the steps below finish the move to Tailwind 4. The guide is',
+    `${LEGACY_COLOR_THEMES_GUIDE}.`,
+    '',
+    '## Generate and import the color theme CSS',
+    '',
+    'Run the color generator once per themes file, with the prefix the Tailwind 3 config used, and import the',
+    'generated `.css` in the global stylesheet of every app below:',
+    '',
+    ...findings.providerSites.map((site) => `- ${site.file}:${site.line}${site.themes ? ` - themes \`${site.themes}\`` : ''}: \`${generatorCommand(site)}\``),
+    '',
+    ...(findings.helperSites.length > 0
+        ? [
+            '## Remove the Tailwind 3 color config',
+            '',
+            'These Tailwind 3 helpers build the color utilities the generated CSS now emits through `@theme`. Delete',
+            'the color block and move the config to Tailwind 4:',
+            '',
+            ...findings.helperSites.map((site) => `- ${site.file}:${site.line} - \`${site.helper}\``),
+            '',
+        ]
+        : []),
+    ...(findings.providesSurfaceThemes
+        ? []
+        : [
+            '## Add surface themes',
+            '',
+            'No app in scope calls `provideSurfaceThemesWithTailwind4()`, and every component reads its backgrounds,',
+            'text and borders from a surface theme. Build a first set from the app’s existing colors: one `light`',
+            'surface (`isDefault: true`, elevation 0) from the page background, text, muted text and border colors,',
+            'and a `light-elevated` one for cards and overlays; add `dark` surfaces only if the app has a dark mode.',
+            'Generate them with `nx g @ethlete/core:tailwind-4-surface-theme`, import the generated `.css`, and',
+            'register them next to the color themes with `provideSurfaceThemesWithTailwind4(SURFACE_THEMES)`.',
+            '',
+        ]),
+    '## Check the app’s own CSS',
+    '',
+    '`--et-color-primary` and its states keep working. `--et-color-alt-*` is gone: put the region in its own',
+    '`etProvideColor` scope and read `--et-color-primary` there.',
+    '',
+].join('\n');
+export default async function migrateLegacyColorThemes(tree, schema) {
+    console.log('\n🔄 Migrating provideColorThemes to provideColorThemesWithTailwind4...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const findings = { providerSites: [], helperSites: [], providesSurfaceThemes: false };
+    const rewrites = new Map();
+    scope.visit(tree, (filePath) => {
+        if (!/\.[cm]?[jt]s$/.test(filePath) || filePath.endsWith('.d.ts'))
+            return;
+        const before = tree.read(filePath, 'utf-8');
+        if (!before)
+            return;
+        const result = migrateLegacyColorThemesInFile(filePath, before);
+        findings.providerSites.push(...result.providerSites);
+        findings.helperSites.push(...result.helperSites);
+        findings.providesSurfaceThemes ||= result.providesSurfaceThemes;
+        if (result.changed)
+            rewrites.set(filePath, result.content);
+    });
+    const scanFile = process.env[SCAN_FILE_ENV];
+    if (scanFile) {
+        writeFileSync(scanFile, JSON.stringify([...rewrites.keys()].sort()), 'utf8');
+        return;
+    }
+    if (rewrites.size === 0) {
+        console.log('   Nothing to migrate.\n');
+        return;
+    }
+    for (const [filePath, content] of rewrites) {
+        tree.write(filePath, content);
+        console.log(`   ✓ ${filePath}`);
+    }
+    tree.write(LEGACY_COLOR_THEMES_REPORT_PATH, renderLegacyColorThemesReport(findings));
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    console.log(`\n✅ Rewrote ${rewrites.size} file(s).`);
+    console.log(`⚠️  The Tailwind 4 setup is not done yet - see ${LEGACY_COLOR_THEMES_REPORT_PATH}.`);
+}

package/generators/migrate-legacy-color-themes/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-legacy-color-themes",
+  "title": "Migrate provideColorThemes to provideColorThemesWithTailwind4",
+  "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. 'apps/web'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}