@ethlete/core 5.0.0-next.6 → 5.0.0-next.60

package/generators/devtools-about/generator.js

@@ -0,0 +1,122 @@
+import { formatFiles, joinPathFragments, logger, readProjectConfiguration, updateProjectConfiguration, visitNotIgnoredFiles, } from '@nx/devkit';
+const SCRIPT_PATH = 'tools/generate-build-info.cjs';
+const SCRIPT = `const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const [, , outputPath, packageJsonPath] = process.argv;
+
+const read = (command) => {
+  try {
+    return execSync(command, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+};
+
+const version = fs.existsSync(packageJsonPath)
+  ? JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8')).version
+  : null;
+
+const info = {
+  version: version ?? 'unknown',
+  sha: read('git rev-parse --short HEAD') ?? 'unknown',
+  branch: read('git rev-parse --abbrev-ref HEAD') ?? 'unknown',
+  builtAt: new Date().toISOString(),
+};
+
+const contents =
+  '// Generated by ' +
+  ${JSON.stringify(SCRIPT_PATH)} +
+  ' - do not edit.\\n\\nexport const APP_BUILD_INFO = ' +
+  JSON.stringify(info, null, 2) +
+  ' as const;\\n';
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, contents);
+`;
+const PLACEHOLDER = `// Generated by ${SCRIPT_PATH} - do not edit.
+
+export const APP_BUILD_INFO = {
+  version: 'unknown',
+  sha: 'unknown',
+  branch: 'unknown',
+  builtAt: '1970-01-01T00:00:00.000Z',
+} as const;
+`;
+const relativeImport = (from, to) => {
+    const fromParts = from.split('/').slice(0, -1);
+    const toParts = to.replace(/\.ts$/, '').split('/');
+    while (fromParts.length && toParts.length && fromParts[0] === toParts[0]) {
+        fromParts.shift();
+        toParts.shift();
+    }
+    const up = fromParts.length ? fromParts.map(() => '..') : ['.'];
+    return [...up, ...toParts].join('/');
+};
+/** Wires the `provideQueryDevtools({ about })` call up to the generated constant, if it can be found. */
+const wireProvider = (tree, projectRoot, outputPath) => {
+    const candidates = [];
+    visitNotIgnoredFiles(tree, projectRoot, (file) => {
+        if (!file.endsWith('.ts') ||
+            file.endsWith('.spec.ts') ||
+            file.endsWith('.test.ts') ||
+            file.endsWith('.stories.ts')) {
+            return;
+        }
+        const contents = tree.read(file, 'utf-8');
+        if (!contents?.includes('provideQueryDevtools('))
+            return;
+        candidates.push({ file, contents });
+    });
+    const alreadyWired = candidates.some(({ contents }) => /provideQueryDevtools\(\s*{[\s\S]*?about\s*:\s*APP_BUILD_INFO/.test(contents));
+    if (alreadyWired)
+        return true;
+    const candidate = candidates.find(({ contents }) => contents.includes('provideQueryDevtools()'));
+    if (!candidate) {
+        for (const { file } of candidates) {
+            logger.warn(`${file} already passes options to provideQueryDevtools() - add \`about: APP_BUILD_INFO\` to them yourself.`);
+        }
+        return candidates.length > 0;
+    }
+    const importPath = relativeImport(candidate.file, outputPath);
+    tree.write(candidate.file, `import { APP_BUILD_INFO } from '${importPath}';\n` +
+        candidate.contents.replace('provideQueryDevtools()', 'provideQueryDevtools({ about: APP_BUILD_INFO })'));
+    return true;
+};
+export const devtoolsAboutGenerator = async (tree, options) => {
+    const project = readProjectConfiguration(tree, options.project);
+    const outputPath = options.outputPath ?? joinPathFragments(project.sourceRoot ?? project.root, 'build-info.ts');
+    if (!tree.exists(SCRIPT_PATH))
+        tree.write(SCRIPT_PATH, SCRIPT);
+    if (!tree.exists(outputPath))
+        tree.write(outputPath, PLACEHOLDER);
+    const gitignore = tree.read('.gitignore', 'utf-8') ?? '';
+    // Regenerated on every build, and its SHA changes with every commit - committing it would put a
+    // one-line diff in every commit that says nothing about the change.
+    if (!gitignore.includes(outputPath)) {
+        tree.write('.gitignore', `${gitignore.trimEnd()}${gitignore.trim() ? '\n' : ''}${outputPath}\n`);
+    }
+    project.targets ??= {};
+    project.targets['build-info'] = {
+        executor: 'nx:run-commands',
+        options: {
+            commands: [`node ${SCRIPT_PATH} ${outputPath} ${joinPathFragments(project.root, 'package.json')}`],
+        },
+    };
+    for (const target of ['build', 'serve']) {
+        const config = project.targets[target];
+        if (!config)
+            continue;
+        config.dependsOn ??= [];
+        if (!config.dependsOn.includes('build-info'))
+            config.dependsOn.push('build-info');
+    }
+    updateProjectConfiguration(tree, options.project, project);
+    if (!wireProvider(tree, project.root, outputPath)) {
+        logger.warn(`No provideQueryDevtools() call found in ${project.root} - pass \`about: APP_BUILD_INFO\` to it yourself.`);
+    }
+    if (!options.skipFormat)
+        await formatFiles(tree);
+};
+export default devtoolsAboutGenerator;

package/generators/devtools-about/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "devtools-about",
+  "title": "Query devtools About generator",
+  "description": "Generates the application's build info (version, commit SHA, branch, build time) and wires it into provideQueryDevtools({ about })",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The application to wire up",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which application should report its build info?"
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Where to write the generated build-info file. Defaults to `<sourceRoot>/build-info.ts`."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after generation",
+      "default": false
+    }
+  },
+  "required": ["project"]
+}

package/generators/generators.json

@@ -1,14 +1,35 @@
 {
+  "$schema": "https://json.schemastore.org/nx-generators",
   "generators": {
     "migrate-to-v5": {
-      "factory": "./migrate-to-v5/migration",
+      "implementation": "./migrate-to-v5/migration",
       "schema": "./migrate-to-v5/schema.json",
       "description": "Migrate to v5"
     },
-    "tailwind-4-theme": {
-      "factory": "./tailwind-4-theme/generator",
-      "schema": "./tailwind-4-theme/schema.json",
-      "description": "Generate theming for Tailwind CSS v4"
+    "migrate-provider-shape": {
+      "implementation": "./migrate-provider-shape/migration",
+      "schema": "./migrate-provider-shape/schema.json",
+      "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape"
+    },
+    "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"
+    },
+    "tailwind-4-color-theme": {
+      "implementation": "./tailwind-4-color-theme/generator",
+      "schema": "./tailwind-4-color-theme/schema.json",
+      "description": "Generate color theming for Tailwind CSS v4"
+    },
+    "tailwind-4-surface-theme": {
+      "implementation": "./tailwind-4-surface-theme/generator",
+      "schema": "./tailwind-4-surface-theme/schema.json",
+      "description": "Generate surface theming for Tailwind CSS v4"
+    },
+    "devtools-about": {
+      "implementation": "./devtools-about/generator",
+      "schema": "./devtools-about/schema.json",
+      "description": "Generate the app's build info and wire it into provideQueryDevtools({ about })"
     }
   }
 }

package/generators/migrate-provider-shape/migration-scope.js

@@ -0,0 +1,35 @@
+import { getProjects, visitNotIgnoredFiles } from '@nx/devkit';
+const stripTrailingSlash = (value) => (value.endsWith('/') ? value.slice(0, -1) : value);
+/**
+ * Limits the migration to a set of projects or paths. Unlike the query v3 migration there is no
+ * cross-file coupling here - every provider declaration is rewritten on its own - so any scope is safe;
+ * this exists to keep the diff reviewable.
+ */
+export const createMigrationScope = (tree, options) => {
+    const roots = [];
+    for (const projectName of options.projects ?? []) {
+        const project = getProjects(tree).get(projectName);
+        if (!project) {
+            throw new Error(`Unknown project "${projectName}". Pass names as they appear in \`nx show projects\`, or use --include with a path prefix.`);
+        }
+        roots.push(stripTrailingSlash(project.root));
+    }
+    for (const includePath of options.include ?? []) {
+        roots.push(stripTrailingSlash(includePath));
+    }
+    if (roots.length === 0) {
+        return {
+            visit: (targetTree, callback) => visitNotIgnoredFiles(targetTree, '', callback),
+            describe: () => 'the whole workspace',
+        };
+    }
+    const uniqueRoots = [...new Set(roots)].filter((root) => !roots.some((candidate) => candidate !== root && (root === candidate || root.startsWith(`${candidate}/`))));
+    return {
+        visit: (targetTree, callback) => {
+            for (const root of uniqueRoots) {
+                visitNotIgnoredFiles(targetTree, root, callback);
+            }
+        },
+        describe: () => uniqueRoots.join(', '),
+    };
+};

package/generators/migrate-provider-shape/migration.js

@@ -0,0 +1,50 @@
+import { formatFiles } from '@nx/devkit';
+import { createMigrationScope } from './migration-scope.js';
+import { migrateProviderShapeInFile } from './provider-shape.js';
+export const PROVIDER_SHAPE_REPORT_PATH = 'provider-shape-migration-tasks.md';
+const renderReport = (tasks) => [
+    '# Provider-shape migration tasks',
+    '',
+    'The codemod rewrote every destructured provider declaration into a definition plus one extractor per',
+    'binding. The sites below are **not** plain module-scope declarations, so they were left alone - each',
+    'needs a decision a codemod cannot make.',
+    '',
+    'Recipes:',
+    '',
+    '- A factory of your own that returned a `[provide, inject, token]` tuple: return the definition from',
+    '  `define*Provider(…)` directly, and let its callers use the extractors.',
+    '- A call inside a function: read `.provide` / `.inject` / `.token` off the definition.',
+    '',
+    ...tasks.map((task) => [`## \`${task.id}\``, '', `- ${task.file}:${task.line}`, `- ${task.message}`, ''].join('\n')),
+].join('\n');
+export default async function migrateProviderShape(tree, schema) {
+    console.log('\n🔄 Migrating provider tuples to the definition shape...');
+    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 = migrateProviderShapeInFile(filePath, before);
+        tasks.push(...result.tasks);
+        if (result.changed) {
+            tree.write(filePath, result.content);
+            filesChanged++;
+            console.log(`   ✓ ${filePath}`);
+        }
+    });
+    if (tasks.length > 0) {
+        tree.write(PROVIDER_SHAPE_REPORT_PATH, renderReport(tasks));
+    }
+    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 ${PROVIDER_SHAPE_REPORT_PATH}.`);
+    }
+}

package/generators/migrate-provider-shape/provider-shape.js

@@ -0,0 +1,284 @@
+import * as ts from 'typescript';
+/**
+ * `export const [provideX, injectX] = createRootProvider(…)` is undroppable by construction: array
+ * destructuring invokes the iterator protocol, so no bundler will remove the statement, and everything
+ * the factory's closure names is retained with it. The definition shape is droppable per binding.
+ *
+ * Two families need rewriting. The `create*Provider` / `createLabels` helpers were replaced by
+ * `define*`, and their declarations take a pure annotation because they sit in library source. The
+ * runtime factories below kept their names - only their return shape changed from tuple to definition -
+ * and their call sites are application code, where an annotation would be noise.
+ */
+const FACTORY_TO_DEFINE = {
+    createProvider: 'defineProvider',
+    createRootProvider: 'defineRootProvider',
+    createStaticProvider: 'defineStaticProvider',
+    createStaticRootProvider: 'defineStaticRootProvider',
+    createLabels: 'defineLabels',
+};
+const REF_FACTORIES = new Set([
+    'createQueryClient',
+    'createBearerAuthProvider',
+    'createWebSocketClient',
+    'createQueryContext',
+]);
+const isKnownFactory = (name) => FACTORY_TO_DEFINE[name] !== undefined || REF_FACTORIES.has(name);
+/** Which extractor names the three tuple positions become. */
+const POSITION_TO_EXTRACTOR = ['toProvideFn', 'toInjectFn', 'toToken'];
+const PURE = '/* @__PURE__ */';
+/** `injectFooBar` / `provideFooBar` / `FOO_BAR_TOKEN` → `FOO_BAR`. */
+const toDefinitionBaseName = (bindingName) => {
+    const withoutPrefix = bindingName
+        .replace(/^ɵ/, '')
+        .replace(/^(provide|inject)/i, '')
+        .replace(/_TOKEN$/, '');
+    const screaming = withoutPrefix
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .toUpperCase();
+    return screaming.replace(/^_+|_+$/g, '') || 'PROVIDER';
+};
+const uniqueDefinitionName = (bindingNames, taken) => {
+    const base = `${toDefinitionBaseName(bindingNames[1] ?? bindingNames[0] ?? bindingNames[2] ?? 'provider')}_DEF`;
+    let candidate = base;
+    let suffix = 2;
+    while (taken.has(candidate)) {
+        candidate = `${base}_${suffix++}`;
+    }
+    taken.add(candidate);
+    return candidate;
+};
+const collectImportedFactories = (sourceFile) => {
+    const importedFactories = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (!statement.moduleSpecifier.text.startsWith('@ethlete/'))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            const importedName = element.propertyName?.text ?? element.name.text;
+            if (isKnownFactory(importedName))
+                importedFactories.set(element.name.text, importedName);
+        }
+    }
+    return importedFactories;
+};
+const findTupleSites = (sourceFile) => {
+    const sites = [];
+    const importedFactories = collectImportedFactories(sourceFile);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || statement.declarationList.declarations.length !== 1)
+            continue;
+        const declaration = statement.declarationList.declarations[0];
+        if (!declaration || !ts.isArrayBindingPattern(declaration.name))
+            continue;
+        const call = declaration.initializer;
+        if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression))
+            continue;
+        const factory = importedFactories.get(call.expression.text);
+        if (!factory)
+            continue;
+        const bindings = declaration.name.elements.map((element) => {
+            if (ts.isOmittedExpression(element) || !ts.isIdentifier(element.name))
+                return null;
+            return element.name.text;
+        });
+        if (bindings.length > POSITION_TO_EXTRACTOR.length)
+            continue;
+        sites.push({
+            statement,
+            call,
+            factory,
+            bindings,
+            isExported: !!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword),
+        });
+    }
+    return sites;
+};
+/** The offset the replacement starts at: before the declaration's own JSDoc, if it has one. */
+const declarationStart = (content, statement, sourceFile) => {
+    const start = statement.getStart(sourceFile);
+    const comments = ts.getLeadingCommentRanges(content, statement.getFullStart());
+    const first = comments?.[0];
+    // Only treat comments as the declaration's own when nothing but whitespace separates them from it.
+    if (!first || /\S/.test(content.slice(comments[comments.length - 1].end, start)))
+        return start;
+    return first.pos;
+};
+const rewriteSite = (content, sourceFile, site, definitionName) => {
+    const start = declarationStart(content, site.statement, sourceFile);
+    const statementStart = site.statement.getStart(sourceFile);
+    const doc = content.slice(start, statementStart);
+    const replacement = FACTORY_TO_DEFINE[site.factory];
+    const annotation = replacement ? `${PURE} ` : '';
+    const callTail = content.slice(site.call.expression.getEnd(), site.call.getEnd());
+    const definition = `const ${definitionName} = ${annotation}${replacement ?? site.factory}${callTail};`;
+    const exportKeyword = site.isExported ? 'export ' : '';
+    const extractions = site.bindings
+        .map((binding, index) => binding === null
+        ? null
+        : `${exportKeyword}const ${binding} = ${annotation}${POSITION_TO_EXTRACTOR[index]}(${definitionName});`)
+        .filter((line) => line !== null);
+    // The JSDoc documented the pair, so it belongs on the first binding a consumer can reach.
+    const documented = extractions.length > 0 ? [definition, '', doc + extractions[0], ...extractions.slice(1)] : [doc + definition];
+    return { start, end: site.statement.getEnd(), text: documented.join('\n') };
+};
+const rewriteImports = (sourceFile, factoriesUsed, extractorsUsed) => {
+    const rewrites = [];
+    const imports = sourceFile.statements.filter(ts.isImportDeclaration);
+    const replacementsUsed = new Set([...factoriesUsed].flatMap((factory) => (FACTORY_TO_DEFINE[factory] ? [FACTORY_TO_DEFINE[factory]] : [])));
+    const extractorHost = imports.find((statement) => namedImportsOf(statement, sourceFile)?.some((name) => extractorsUsed.has(name))) ??
+        imports.find(isCoreImport);
+    for (const statement of imports) {
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        const elements = bindings.elements.map((element) => ({
+            text: element.getText(sourceFile),
+            importedName: element.propertyName?.text ?? element.name.text,
+        }));
+        const replaced = elements.filter((element) => factoriesUsed.has(element.importedName) && FACTORY_TO_DEFINE[element.importedName] !== undefined);
+        const additions = statement === extractorHost ? [...replacementsUsed, ...extractorsUsed] : [];
+        if (replaced.length === 0 && additions.length === 0)
+            continue;
+        const kept = elements.filter((element) => !replaced.includes(element)).map((element) => element.text);
+        const merged = [...new Set([...kept, ...additions])].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+        rewrites.push({
+            start: bindings.getStart(sourceFile),
+            end: bindings.getEnd(),
+            text: `{ ${merged.join(', ')} }`,
+        });
+    }
+    if (extractorHost)
+        return rewrites;
+    // Nothing to join - the file only imported a ref factory from another package, so add a core import.
+    const anchor = imports[imports.length - 1];
+    const position = anchor ? anchor.getEnd() : 0;
+    const statement = `import { ${[...replacementsUsed, ...extractorsUsed].sort().join(', ')} } from '@ethlete/core';`;
+    rewrites.push({ start: position, end: position, text: anchor ? `\n${statement}` : `${statement}\n` });
+    return rewrites;
+};
+const namedImportsOf = (statement, sourceFile) => {
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings))
+        return undefined;
+    return bindings.elements.map((element) => element.getText(sourceFile));
+};
+const isCoreImport = (statement) => ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === '@ethlete/core';
+/**
+ * Rewrites every top-level destructured provider tuple in one file into a descriptor plus one pure
+ * extractor per exported binding. Returns the file unchanged when there is nothing to do.
+ */
+export const migrateProviderShapeInFile = (filePath, content) => {
+    if (![...Object.keys(FACTORY_TO_DEFINE), ...REF_FACTORIES].some((factory) => content.includes(factory))) {
+        return { content, changed: false, tasks: [] };
+    }
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const sites = findTupleSites(sourceFile);
+    const tasks = collectTasks(filePath, sourceFile, sites);
+    if (sites.length === 0)
+        return { content, changed: false, tasks };
+    const taken = collectTopLevelNames(sourceFile);
+    const factoriesUsed = new Set(sites.map((site) => site.factory));
+    const extractorsUsed = new Set(sites.flatMap((site) => site.bindings.flatMap((binding, index) => (binding === null ? [] : [POSITION_TO_EXTRACTOR[index]]))));
+    const edits = [
+        ...sites.map((site) => rewriteSite(content, sourceFile, site, uniqueDefinitionName(site.bindings.filter((b) => b !== null), taken))),
+        ...rewriteImports(sourceFile, factoriesUsed, extractorsUsed),
+    ].sort((a, b) => b.start - a.start);
+    let updated = content;
+    for (const edit of edits) {
+        updated = updated.slice(0, edit.start) + edit.text + updated.slice(edit.end);
+    }
+    return { content: updated, changed: updated !== content, tasks };
+};
+/** Call sites the codemod cannot safely rewrite - a factory result that is not a plain tuple binding. */
+const collectTasks = (filePath, sourceFile, sites) => {
+    const rewritten = new Set(sites.map((site) => site.statement));
+    const tasks = [];
+    const importedFactories = collectImportedFactories(sourceFile);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        if (!statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (!statement.moduleSpecifier.text.startsWith('@ethlete/') || !statement.exportClause)
+            continue;
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const element of statement.exportClause.elements) {
+            const exportedName = element.propertyName?.text ?? element.name.text;
+            if (!isKnownFactory(exportedName))
+                continue;
+            const { line } = sourceFile.getLineAndCharacterOfPosition(element.getStart(sourceFile));
+            tasks.push({
+                id: `provider-shape:${filePath}:${line + 1}`,
+                file: filePath,
+                line: line + 1,
+                message: `The \`${exportedName}\` re-export must be migrated manually because the replacement API returns a provider definition.`,
+            });
+        }
+    }
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const importedFactory = importedFactories.get(node.expression.text);
+            if (!importedFactory || FACTORY_TO_DEFINE[importedFactory] === undefined) {
+                ts.forEachChild(node, visit);
+                return;
+            }
+            const statement = enclosingStatement(node);
+            if (!statement || !rewritten.has(statement)) {
+                const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                const factory = importedFactory;
+                const replacement = FACTORY_TO_DEFINE[factory];
+                tasks.push({
+                    id: `provider-shape:${filePath}:${line + 1}`,
+                    file: filePath,
+                    line: line + 1,
+                    message: replacement
+                        ? `\`${factory}\` is gone. Replace it with \`${replacement}\` and read the halves with \`toProvideFn\` / \`toInjectFn\` / \`toToken\`.`
+                        : `\`${factory}\` returns a provider definition now, not a \`[provide, inject, token]\` tuple. Read the halves with \`toProvideFn\` / \`toInjectFn\` / \`toToken\`, or \`.provide\` / \`.inject\` / \`.token\` inside a function.`,
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return tasks;
+};
+const collectTopLevelNames = (sourceFile) => {
+    const names = new Set();
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const clause = statement.importClause;
+            if (clause?.name)
+                names.add(clause.name.text);
+            const bindings = clause?.namedBindings;
+            if (bindings && ts.isNamedImports(bindings))
+                bindings.elements.forEach((element) => names.add(element.name.text));
+            if (bindings && ts.isNamespaceImport(bindings))
+                names.add(bindings.name.text);
+        }
+        else if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    names.add(declaration.name.text);
+            }
+        }
+        else if ((ts.isClassDeclaration(statement) || ts.isFunctionDeclaration(statement)) && statement.name) {
+            names.add(statement.name.text);
+        }
+    }
+    return names;
+};
+const enclosingStatement = (node) => {
+    let current = node;
+    while (current && !ts.isSourceFile(current)) {
+        if (ts.isVariableStatement(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+};

package/generators/migrate-provider-shape/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-provider-shape",
+  "title": "Migrate provider tuples to the definition shape",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace. Every declaration is rewritten independently, so any scope is safe - use this to keep the diff reviewable.",
+      "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-surface-interaction-swatch/interaction-swatch.js

@@ -0,0 +1,63 @@
+import { Project, SyntaxKind } from 'ts-morph';
+const INTERACTION_KEYS = ['default', 'hover', 'focus', 'active', 'disabled'];
+const createProject = () => new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+        target: 99,
+        module: 99,
+    },
+});
+const isFlatInteractionColor = (initializer) => initializer
+    .getProperties()
+    .some((property) => property.isKind(SyntaxKind.PropertyAssignment) && INTERACTION_KEYS.includes(property.getName()));
+const findFlatInteractionColor = (sourceFile) => {
+    for (const property of sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+        if (property.getName() !== 'interactionColor')
+            continue;
+        const initializer = property.getInitializer();
+        if (initializer?.isKind(SyntaxKind.ObjectLiteralExpression) && isFlatInteractionColor(initializer)) {
+            return initializer;
+        }
+        if (initializer?.isKind(SyntaxKind.Identifier)) {
+            const declaration = sourceFile
+                .getVariableDeclarations()
+                .find((candidate) => candidate.getName() === initializer.getText());
+            const referencedInitializer = declaration?.getInitializer();
+            if (referencedInitializer?.isKind(SyntaxKind.ObjectLiteralExpression) &&
+                isFlatInteractionColor(referencedInitializer)) {
+                return referencedInitializer;
+            }
+        }
+    }
+    return null;
+};
+/**
+ * Rewrites `interactionColor: { default, hover, … }` into `interactionColor: { color: { default, … } }`,
+ * the swatch shape that also carries the optional `onColor` and `inkColor` maps.
+ */
+export const migrateInteractionSwatchInFile = (filePath, content) => {
+    if (!content.includes('interactionColor')) {
+        return { changed: false, content };
+    }
+    const sourceFile = createProject().createSourceFile(filePath, content);
+    let changed = false;
+    // Re-queried after every rewrite: manipulating the AST forgets the nodes a single up-front
+    // collection would have handed us.
+    for (let initializer = findFlatInteractionColor(sourceFile); initializer;) {
+        initializer.replaceWithText(`{ color: ${initializer.getText()} }`);
+        changed = true;
+        initializer = findFlatInteractionColor(sourceFile);
+    }
+    const unresolved = sourceFile
+        .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
+        .filter((property) => property.getName() === 'interactionColor')
+        .flatMap((property) => {
+        const initializer = property.getInitializer();
+        return initializer && !initializer.isKind(SyntaxKind.ObjectLiteralExpression) ? [initializer.getText()] : [];
+    });
+    return {
+        changed,
+        content: changed ? sourceFile.getFullText() : content,
+        ...(unresolved.length > 0 ? { unresolved } : {}),
+    };
+};