@ethlete/core 5.0.0-next.36 → 5.0.0-next.38

package/generators/generators.json

@@ -5,6 +5,11 @@
       "schema": "./migrate-to-v5/schema.json",
       "description": "Migrate to v5"
     },
+    "migrate-provider-shape": {
+      "factory": "./migrate-provider-shape/migration",
+      "schema": "./migrate-provider-shape/schema.json",
+      "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape"
+    },
     "tailwind-4-color-theme": {
       "factory": "./tailwind-4-color-theme/generator",
       "schema": "./tailwind-4-color-theme/schema.json",

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',
+        };
+    }
+    return {
+        visit: (targetTree, callback) => {
+            for (const root of roots) {
+                visitNotIgnoredFiles(targetTree, root, callback);
+            }
+        },
+        describe: () => roots.join(', '),
+    };
+};
+//# sourceMappingURL=migration-scope.js.map

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

@@ -0,0 +1,51 @@
+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}.`);
+    }
+}
+//# sourceMappingURL=migration.js.map

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

@@ -0,0 +1,217 @@
+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 findTupleSites = (sourceFile) => {
+    const sites = [];
+    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 = call.expression.text;
+        if (!isKnownFactory(factory))
+            continue;
+        const bindings = declaration.name.elements.map((element) => {
+            if (ts.isOmittedExpression(element) || !ts.isIdentifier(element.name))
+                return null;
+            return element.name.text;
+        });
+        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 = (content, sourceFile, factoriesUsed, extractorsUsed) => {
+    const rewrites = [];
+    const imports = sourceFile.statements.filter(ts.isImportDeclaration);
+    /** The declaration the extractors join: the one that already provides them, else any core import. */
+    const extractorHost = imports.find((statement) => namedImportsOf(statement, sourceFile)?.some((name) => extractorsUsed.has(name))) ??
+        imports.find((statement) => {
+            const names = namedImportsOf(statement, sourceFile);
+            return names?.some((name) => FACTORY_TO_DEFINE[name] !== undefined) || isCoreImport(statement);
+        });
+    for (const statement of imports) {
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        const names = bindings.elements.map((element) => element.getText(sourceFile));
+        // A ref factory keeps its name and its import; only a replaced factory is swapped out.
+        const replaced = names.filter((name) => factoriesUsed.has(name) && FACTORY_TO_DEFINE[name] !== undefined);
+        const extractors = statement === extractorHost ? [...extractorsUsed] : [];
+        if (replaced.length === 0 && extractors.length === 0)
+            continue;
+        const kept = names.filter((name) => !replaced.includes(name));
+        const merged = [
+            ...new Set([...kept, ...replaced.map((factory) => FACTORY_TO_DEFINE[factory]), ...extractors]),
+        ].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 { ${[...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 = new Set(sourceFile.statements
+        .filter(ts.isVariableStatement)
+        .flatMap((statement) => statement.declarationList.declarations)
+        .flatMap((declaration) => (ts.isIdentifier(declaration.name) ? [declaration.name.text] : [])));
+    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(content, 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 visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isKnownFactory(node.expression.text)) {
+            const statement = enclosingStatement(node);
+            if (!statement || !rewritten.has(statement)) {
+                const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                const factory = node.expression.text;
+                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 enclosingStatement = (node) => {
+    let current = node;
+    while (current && !ts.isSourceFile(current)) {
+        if (ts.isVariableStatement(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+};
+//# sourceMappingURL=provider-shape.js.map

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/tailwind-4-color-theme/generator.js

@@ -38,7 +38,7 @@ export default async function generate(tree, schema) {
     }
     // Step 4: Apply the generation-time default override, if any. The shared theme
     // definitions may mark a default via isDefault, but in a monorepo each app picks its
-    // own default at its generation invocation — the option wins over the definitions.
+    // own default at its generation invocation - the option wins over the definitions.
     if (schema.defaultTheme) {
         try {
             const defaultName = applyDefaultThemeOverride(themes, schema.defaultTheme);
@@ -411,7 +411,7 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
     // Collect the dynamic theme colors once. They are emitted in `@theme` (so Tailwind generates
     // the utilities) and ALSO re-declared on every color selector in the alias block below. A
     // Tailwind `@theme` variable only lands on `:root`, so `rgb(var(--<runtime>-color-*))` resolves
-    // once against the root color scope and inherits that concrete color into descendants — which
+    // once against the root color scope and inherits that concrete color into descendants - which
     // means `bg-<prefix>-theme-*` utilities would ignore nested `.<runtime>-color--*` scopes.
     // Re-declaring them per color selector makes the utilities resolve against the nearest scope.
     const dynamicColorVars = [];
@@ -449,7 +449,7 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
     while (dynamicColorAliasLines.length && dynamicColorAliasLines[dynamicColorAliasLines.length - 1] === '') {
         dynamicColorAliasLines.pop();
     }
-    // Convenience var aliases — available on any element with a color class (or root for default)
+    // Convenience var aliases - available on any element with a color class (or root for default)
     const aliasBlock = `/* Convenience aliases (rgb + solid + opacity variants) */
 @layer base {
   :root, :where([class*="${runtimePrefix}-color--"]) {
@@ -468,7 +468,7 @@ function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema)
     --${runtimePrefix}-theme-color-ink-solid: rgb(var(--${runtimePrefix}-theme-color-ink-rgb) / var(--${runtimePrefix}-theme-color-ink-opacity));
     --${runtimePrefix}-theme-color-ink: rgb(var(--${runtimePrefix}-theme-color-ink-rgb) / var(--${runtimePrefix}-theme-color-ink-opacity));
 
-    /* Dynamic Tailwind theme colors — re-declared per color scope so that
+    /* Dynamic Tailwind theme colors - re-declared per color scope so that
        bg-${utilityPrefix}-theme-* utilities resolve against the nearest .${runtimePrefix}-color--*
        scope instead of the value computed once at :root. */
 ${dynamicColorAliasLines.join('\n')}

package/generators/tailwind-4-surface-theme/generator.js

@@ -35,7 +35,7 @@ export default async function generate(tree, schema) {
     }
     // Apply the generation-time default overrides, if any. The shared theme definitions may
     // mark defaults via isDefault, but in a monorepo each app picks its own defaults at its
-    // generation invocation — the options win over the definitions (per surface type).
+    // generation invocation - the options win over the definitions (per surface type).
     try {
         if (schema.defaultLightTheme) {
             const name = applyDefaultSurfaceThemeOverride(themes, schema.defaultLightTheme, 'light');
@@ -304,7 +304,7 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
 `;
     const defaultThemes = themes.filter((t) => t.isDefault);
     const regularThemes = themes.filter((t) => !t.isDefault);
-    // Static Tailwind @theme block — one color set per surface theme
+    // Static Tailwind @theme block - one color set per surface theme
     for (const theme of themes) {
         const name = createCssSurfaceName(theme.name);
         tailwindVars.push(`  /* ${theme.name} surface */`);
@@ -325,14 +325,14 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
     // Dynamic surface colors (reference runtime CSS variables).
     // These are ALSO re-declared on every surface selector in the alias block below. A Tailwind
     // `@theme` variable only lands on `:root`, so `rgb(var(--<runtime>-surface-*))` resolves once
-    // against the root surface and inherits that concrete color into descendants — which means
+    // against the root surface and inherits that concrete color into descendants - which means
     // `bg-<prefix>-surface-*` utilities would ignore nested surface scopes (e.g. an elevated
     // surface). Re-declaring them per surface selector makes the utilities resolve against the
     // nearest surface instead.
     const dynamicSurfaceColors = buildDynamicSurfaceColors(utilityPrefix, runtimePrefix);
     tailwindVars.push('  /* Dynamic surface colors (references runtime CSS variables) */');
     tailwindVars.push(...dynamicSurfaceColors.map((decl) => `  ${decl}`));
-    // Runtime CSS — theme selector classes
+    // Runtime CSS - theme selector classes
     for (const theme of themes) {
         const name = createCssSurfaceName(theme.name);
         const isDefault = theme.isDefault;
@@ -346,7 +346,7 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
         pushSurfaceVars(themeVars, runtimePrefix, theme, '  ');
         themeVars.push('}\n');
     }
-    // Media query defaults — apply surface vars to :root based on prefers-color-scheme
+    // Media query defaults - apply surface vars to :root based on prefers-color-scheme
     const defaultLight = themes.find((t) => t.isDefault && t.type === 'light');
     const defaultDark = themes.find((t) => t.isDefault && t.type === 'dark');
     if (defaultLight) {
@@ -363,7 +363,7 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
         themeVars.push(`  }`);
         themeVars.push(`}\n`);
     }
-    // Convenience var aliases — available on any element with a surface class or :root (via media queries)
+    // Convenience var aliases - available on any element with a surface class or :root (via media queries)
     const aliasBlock = `/* Convenience aliases (rgb + solid variants) */
 @layer base {
   :root, :where([class*="${runtimePrefix}-surface--"]) {
@@ -397,7 +397,7 @@ function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
     --${runtimePrefix}-surface-interaction-disabled-rgb: var(--${runtimePrefix}-surface-interaction-disabled);
     --${runtimePrefix}-surface-interaction-disabled-solid: rgb(var(--${runtimePrefix}-surface-interaction-disabled-rgb));
 
-    /* Dynamic Tailwind surface colors — re-declared per surface scope so that
+    /* Dynamic Tailwind surface colors - re-declared per surface scope so that
        bg-${utilityPrefix}-surface-* utilities resolve against the nearest surface
        (e.g. a nested elevated surface) instead of the value computed once at :root. */
 ${dynamicSurfaceColors.map((decl) => `    ${decl}`).join('\n')}

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@ethlete/core",
-  "version": "5.0.0-next.36",
+  "version": "5.0.0-next.38",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
     "@analogjs/vite-plugin-angular": "2.6.3",
-    "@angular/cdk": "22.0.5",
     "@angular/common": "22.0.7",
     "@angular/core": "22.0.7",
     "@angular/forms": "22.0.7",
@@ -19,6 +18,23 @@
     "typescript": "6.0.3",
     "vite": "8.1.5"
   },
+  "peerDependenciesMeta": {
+    "@analogjs/vite-plugin-angular": {
+      "optional": true
+    },
+    "@nx/devkit": {
+      "optional": true
+    },
+    "ts-morph": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
   "generators": "./generators/generators.json",
   "module": "fesm2022/ethlete-core.mjs",
   "typings": "types/ethlete-core.d.ts",