@nx/devkit 23.0.0-pr.35465.2bc2643 → 23.0.0-rc.1

package/{src → dist/src}/generators/to-js.js

@@ -8,21 +8,26 @@ const package_json_1 = require("../utils/package-json");
  */
 function toJS(tree, options) {
     const { JsxEmit, ScriptTarget, transpile, ModuleKind } = (0, package_json_1.ensurePackage)('typescript', versions_1.typescriptVersion);
+    // Match `.ts`, `.mts`, `.cts`, `.tsx`. The optional `[cm]` keeps native
+    // ESM (`.mts`) and CommonJS (`.cts`) TypeScript extensions in the rename
+    // path so `--js` generators that emit `.mts`/`.cts` templates get
+    // converted instead of silently left as TypeScript on disk.
+    const tsExtRegex = /\.([cm]?ts|tsx)$/;
     for (const c of tree.listChanges()) {
-        if ((c.path.endsWith('.ts') || c.path.endsWith('tsx')) &&
-            c.type === 'CREATE') {
+        if (tsExtRegex.test(c.path) && c.type === 'CREATE') {
             tree.write(c.path, transpile(c.content.toString('utf-8'), {
                 allowJs: true,
                 jsx: JsxEmit.Preserve,
                 target: options?.target ?? ScriptTarget.ESNext,
                 module: options?.module ?? ModuleKind.ESNext,
             }));
-            tree.rename(c.path, c.path.replace(/\.ts$/, options?.extension ?? '.js'));
+            const targetExt = options?.extension ?? '.js';
+            tree.rename(c.path, c.path.replace(/\.([cm]?ts)$/, targetExt));
             if (options?.useJsx) {
                 tree.rename(c.path, c.path.replace(/\.tsx$/, '.jsx'));
             }
             else {
-                tree.rename(c.path, c.path.replace(/\.tsx$/, options?.extension ?? '.js'));
+                tree.rename(c.path, c.path.replace(/\.tsx$/, targetExt));
             }
         }
     }

package/{src → dist/src}/generators/typescript/insert-import.d.ts

@@ -1,2 +1 @@
 export declare function insertImport(): void;
-//# sourceMappingURL=insert-import.d.ts.map

package/{src → dist/src}/generators/typescript/insert-statement.d.ts

@@ -1,2 +1 @@
 export declare function insertImport(): void;
-//# sourceMappingURL=insert-statement.d.ts.map

package/{src → dist/src}/generators/update-ts-configs-to-js.d.ts

@@ -2,4 +2,3 @@ import { Tree } from 'nx/src/devkit-exports';
 export declare function updateTsConfigsToJs(tree: Tree, options: {
     projectRoot: string;
 }): void;
-//# sourceMappingURL=update-ts-configs-to-js.d.ts.map

package/{src → dist/src}/generators/visit-not-ignored-files.d.ts

@@ -3,4 +3,3 @@ import type { Tree } from 'nx/src/devkit-exports';
  * Utility to act on all files in a tree that are not ignored by git.
  */
 export declare function visitNotIgnoredFiles(tree: Tree, dirPath: string, visitor: (path: string) => void): void;
-//# sourceMappingURL=visit-not-ignored-files.d.ts.map

package/dist/src/migrations/update-23-0-0/rename-create-nodes-v2-types.d.ts

@@ -0,0 +1,10 @@
+import { type Tree } from 'nx/src/devkit-exports';
+export declare const CREATE_NODES_V2_TYPE_RENAMES: ReadonlyMap<string, string>;
+export default function renameCreateNodesV2Types(tree: Tree): Promise<void>;
+/**
+ * Rewrites named imports and re-exports of the deprecated `*V2` plugin types
+ * from `@nx/devkit` to their canonical names. Only the named bindings are
+ * touched — the module specifier, the `import`/`export` keyword, any `type`
+ * modifier, and any default import are left untouched.
+ */
+export declare function rewriteCreateNodesV2Types(source: string): string;

package/dist/src/migrations/update-23-0-0/rename-create-nodes-v2-types.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREATE_NODES_V2_TYPE_RENAMES = void 0;
+exports.default = renameCreateNodesV2Types;
+exports.rewriteCreateNodesV2Types = rewriteCreateNodesV2Types;
+const devkit_exports_1 = require("nx/src/devkit-exports");
+const format_files_1 = require("../../generators/format-files");
+const visit_not_ignored_files_1 = require("../../generators/visit-not-ignored-files");
+const package_json_1 = require("../../utils/package-json");
+const string_change_1 = require("../../utils/string-change");
+const versions_1 = require("../../utils/versions");
+const TS_EXTENSIONS = ['.ts', '.tsx', '.cts', '.mts'];
+const DEVKIT_SPECIFIER = '@nx/devkit';
+// The `*V2` plugin types were renamed to their canonical un-suffixed names in
+// Nx 23. The `V2` names remain as `@deprecated` aliases, so this migration only
+// moves callers onto the canonical names. (`CreateNodesResultV2` is renamed to
+// `CreateNodesResultArray`, not `CreateNodesResult`, which is an unrelated type.)
+exports.CREATE_NODES_V2_TYPE_RENAMES = new Map([
+    ['CreateNodesV2', 'CreateNodes'],
+    ['CreateNodesContextV2', 'CreateNodesContext'],
+    ['CreateNodesResultV2', 'CreateNodesResultArray'],
+    ['CreateNodesFunctionV2', 'CreateNodesFunction'],
+    ['NxPluginV2', 'NxPlugin'],
+]);
+let ts;
+async function renameCreateNodesV2Types(tree) {
+    let touchedCount = 0;
+    (0, visit_not_ignored_files_1.visitNotIgnoredFiles)(tree, '.', (filePath) => {
+        if (!TS_EXTENSIONS.some((ext) => filePath.endsWith(ext))) {
+            return;
+        }
+        const original = tree.read(filePath, 'utf-8');
+        if (!original || !original.includes('V2')) {
+            return;
+        }
+        const updated = rewriteCreateNodesV2Types(original);
+        if (updated !== original) {
+            tree.write(filePath, updated);
+            touchedCount += 1;
+        }
+    });
+    if (touchedCount > 0) {
+        devkit_exports_1.logger.info(`Renamed deprecated CreateNodes V2 type imports from @nx/devkit in ${touchedCount} file(s).`);
+    }
+    await (0, format_files_1.formatFiles)(tree);
+}
+/**
+ * Rewrites named imports and re-exports of the deprecated `*V2` plugin types
+ * from `@nx/devkit` to their canonical names. Only the named bindings are
+ * touched — the module specifier, the `import`/`export` keyword, any `type`
+ * modifier, and any default import are left untouched.
+ */
+function rewriteCreateNodesV2Types(source) {
+    ts ??= (0, package_json_1.ensurePackage)('typescript', versions_1.typescriptVersion);
+    const sourceFile = ts.createSourceFile('tmp.ts', source, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, ts.ScriptKind.TSX);
+    const changes = [];
+    // Local bindings whose name changes as a result of rewriting a non-aliased
+    // import specifier (e.g. `import { CreateNodesV2 }` -> `import { CreateNodes }`).
+    // Every in-body reference to such a binding must be renamed too, otherwise the
+    // rewritten import leaves a dangling reference to the old name.
+    const localRenames = new Map();
+    for (const stmt of sourceFile.statements) {
+        if (ts.isImportDeclaration(stmt)) {
+            collectImportRewrite(sourceFile, stmt, changes, localRenames);
+        }
+        else if (ts.isExportDeclaration(stmt)) {
+            collectExportRewrite(sourceFile, stmt, changes);
+        }
+    }
+    if (localRenames.size > 0) {
+        collectUsageRewrites(sourceFile, localRenames, changes);
+    }
+    return changes.length > 0 ? (0, string_change_1.applyChangesToString)(source, changes) : source;
+}
+function isDevkitSpecifier(node) {
+    return ts.isStringLiteral(node) && node.text === DEVKIT_SPECIFIER;
+}
+function collectImportRewrite(sourceFile, stmt, changes, localRenames) {
+    if (!isDevkitSpecifier(stmt.moduleSpecifier)) {
+        return;
+    }
+    const namedBindings = stmt.importClause?.namedBindings;
+    if (!namedBindings || !ts.isNamedImports(namedBindings)) {
+        return;
+    }
+    // A non-aliased specifier (`{ CreateNodesV2 }`) renames the local binding, so
+    // its in-body references must be rewritten as well. An aliased specifier
+    // (`{ CreateNodesV2 as Foo }`) keeps the local name `Foo`, so it does not.
+    for (const el of namedBindings.elements) {
+        if (el.propertyName) {
+            continue;
+        }
+        const canonical = exports.CREATE_NODES_V2_TYPE_RENAMES.get(el.name.text);
+        if (canonical) {
+            localRenames.set(el.name.text, canonical);
+        }
+    }
+    rewriteNamedBindings(sourceFile, namedBindings, changes);
+}
+/**
+ * Renames in-body references (type annotations, value usages) of bindings that
+ * were renamed by an import rewrite. References inside import/export
+ * declarations are left to the binding rewrite, and member positions
+ * (`foo.CreateNodesV2`, `NS.CreateNodesV2`) are not standalone references to the
+ * imported binding, so they are skipped.
+ */
+function collectUsageRewrites(sourceFile, localRenames, changes) {
+    const visit = (node) => {
+        if (ts.isIdentifier(node) &&
+            localRenames.has(node.text) &&
+            isRenameableReference(node)) {
+            const start = node.getStart(sourceFile);
+            changes.push({ type: string_change_1.ChangeType.Delete, start, length: node.getEnd() - start }, {
+                type: string_change_1.ChangeType.Insert,
+                index: start,
+                text: localRenames.get(node.text),
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+}
+function isRenameableReference(id) {
+    const parent = id.parent;
+    // `foo.CreateNodesV2` — the member name is not the imported binding.
+    if (ts.isPropertyAccessExpression(parent) && parent.name === id) {
+        return false;
+    }
+    // `NS.CreateNodesV2` in a type position — same reasoning.
+    if (ts.isQualifiedName(parent) && parent.right === id) {
+        return false;
+    }
+    // Anything inside an import/export declaration is handled by the binding
+    // rewrite; skip it here to avoid touching the specifier twice.
+    for (let n = id; n; n = n.parent) {
+        if (ts.isImportDeclaration(n) || ts.isExportDeclaration(n)) {
+            return false;
+        }
+    }
+    return true;
+}
+function collectExportRewrite(sourceFile, stmt, changes) {
+    if (!stmt.moduleSpecifier || !isDevkitSpecifier(stmt.moduleSpecifier)) {
+        return;
+    }
+    if (!stmt.exportClause || !ts.isNamedExports(stmt.exportClause)) {
+        return;
+    }
+    rewriteNamedBindings(sourceFile, stmt.exportClause, changes);
+}
+/**
+ * Re-renders the `{ ... }` of a named import/export, renaming any deprecated
+ * `*V2` type to its canonical name. If renaming would collide with a canonical
+ * name that is already present, the duplicate is dropped. Returns without
+ * recording a change when the binding list contains none of the renamed types.
+ */
+function rewriteNamedBindings(sourceFile, namedBindings, changes) {
+    const elements = namedBindings.elements;
+    const hasRenamed = elements.some((el) => exports.CREATE_NODES_V2_TYPE_RENAMES.has((el.propertyName ?? el.name).text));
+    if (!hasRenamed) {
+        return;
+    }
+    const seen = new Set();
+    const rendered = [];
+    for (const el of elements) {
+        const text = renderSpecifier(el);
+        if (!seen.has(text)) {
+            seen.add(text);
+            rendered.push(text);
+        }
+    }
+    const start = namedBindings.getStart(sourceFile);
+    changes.push({
+        type: string_change_1.ChangeType.Delete,
+        start,
+        length: namedBindings.getEnd() - start,
+    }, {
+        type: string_change_1.ChangeType.Insert,
+        index: start,
+        text: `{ ${rendered.join(', ')} }`,
+    });
+}
+function renderSpecifier(el) {
+    const typePrefix = el.isTypeOnly ? 'type ' : '';
+    const rename = (name) => exports.CREATE_NODES_V2_TYPE_RENAMES.get(name) ?? name;
+    // `{ name }` — no alias, so the local binding follows the rename.
+    if (!el.propertyName) {
+        return `${typePrefix}${rename(el.name.text)}`;
+    }
+    // `{ propertyName as name }` — only the imported (left) side is renamed; the
+    // local alias is preserved. A now-redundant alias such as
+    // `CreateNodesV2 as CreateNodes` collapses to `CreateNodes`.
+    const canonicalImported = rename(el.propertyName.text);
+    const localName = el.name.text;
+    return canonicalImported === localName
+        ? `${typePrefix}${localName}`
+        : `${typePrefix}${canonicalImported} as ${localName}`;
+}

package/dist/src/migrations/update-23-0-0/rename-create-nodes-v2-types.md

@@ -0,0 +1,29 @@
+#### Rename deprecated CreateNodes `V2` types from `@nx/devkit`
+
+The canonical plugin API types lost their `V2` suffix in Nx 23. The `V2` names are kept as `@deprecated` aliases, but new code should use the canonical names:
+
+| Deprecated (`@nx/devkit`) | Canonical                |
+| ------------------------- | ------------------------ |
+| `CreateNodesV2`           | `CreateNodes`            |
+| `CreateNodesContextV2`    | `CreateNodesContext`     |
+| `CreateNodesResultV2`     | `CreateNodesResultArray` |
+| `CreateNodesFunctionV2`   | `CreateNodesFunction`    |
+| `NxPluginV2`              | `NxPlugin`               |
+
+This migration scans every `.ts`, `.tsx`, `.cts`, and `.mts` file in your workspace and rewrites named imports and re-exports of these types from `@nx/devkit` to their canonical names.
+
+#### Sample Code Changes
+
+##### Before
+
+```ts
+import type { CreateNodesV2, CreateNodesContextV2 } from '@nx/devkit';
+```
+
+##### After
+
+```ts
+import type { CreateNodes, CreateNodesContext } from '@nx/devkit';
+```
+
+Aliases are preserved (`CreateNodesV2 as CN` becomes `CreateNodes as CN`), and if a file already imports both names (`{ CreateNodes, CreateNodesV2 }`) the redundant binding is dropped. The unrelated `CreateNodesResult` type is left untouched.

package/dist/src/migrations/update-23-0-0/update-deep-imports.d.ts

@@ -0,0 +1,4 @@
+import { type Tree } from 'nx/src/devkit-exports';
+export declare const DEVKIT_INTERNAL_SYMBOLS: ReadonlySet<string>;
+export default function updateDevkitDeepImports(tree: Tree): Promise<void>;
+export declare function rewriteDevkitDeepImports(source: string): string;

package/dist/src/migrations/update-23-0-0/update-deep-imports.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEVKIT_INTERNAL_SYMBOLS = void 0;
+exports.default = updateDevkitDeepImports;
+exports.rewriteDevkitDeepImports = rewriteDevkitDeepImports;
+const devkit_exports_1 = require("nx/src/devkit-exports");
+const format_files_1 = require("../../generators/format-files");
+const visit_not_ignored_files_1 = require("../../generators/visit-not-ignored-files");
+const package_json_1 = require("../../utils/package-json");
+const string_change_1 = require("../../utils/string-change");
+const versions_1 = require("../../utils/versions");
+const TS_EXTENSIONS = ['.ts', '.tsx', '.cts', '.mts'];
+const DEEP_IMPORT_PREFIX = '@nx/devkit/src/';
+const PUBLIC_SPECIFIER = '@nx/devkit';
+const INTERNAL_SPECIFIER = '@nx/devkit/internal';
+// Names re-exported from `@nx/devkit/internal` (see packages/devkit/internal.ts
+// at the time this migration was authored). Anything imported from a
+// `@nx/devkit/src/...` path whose name is NOT in this set is assumed to be
+// part of the stable public `@nx/devkit` API.
+exports.DEVKIT_INTERNAL_SYMBOLS = new Set([
+    'signalToCode',
+    'createProjectRootMappingsFromProjectConfigurations',
+    'PluginCache',
+    'safeWriteFileCache',
+    'determineArtifactNameAndDirectoryOptions',
+    'getRelativeCwd',
+    'FileExtensionType',
+    'getE2EWebServerInfo',
+    'E2EWebServerDetails',
+    'forEachExecutorOptions',
+    'AggregatedLog',
+    'migrateProjectExecutorsToPlugin',
+    'migrateProjectExecutorsToPluginV1',
+    'NoTargetsToMigrateError',
+    'InferredTargetConfiguration',
+    'processTargetOutputs',
+    'deleteMatchingProperties',
+    'toProjectRelativePath',
+    'determineProjectNameAndRootOptions',
+    'ensureRootProjectName',
+    'resolveImportPath',
+    'promptWhenInteractive',
+    'addBuildTargetDefaults',
+    'addE2eCiTargetDefaults',
+    'addPlugin',
+    'createAsyncIterable',
+    'combineAsyncIterables',
+    'mapAsyncIterable',
+    'calculateHashForCreateNodes',
+    'calculateHashesForCreateNodes',
+    'getCatalogManager',
+    'loadConfigFile',
+    'clearRequireCache',
+    'findPluginForConfigFile',
+    'getNamedInputs',
+    'logShowProjectCommand',
+    'eachValueFrom',
+    'checkAndCleanWithSemver',
+    'camelize',
+    'capitalize',
+    'classify',
+    'dasherize',
+    'emitPluginWorkerLog',
+    'throwForUnsupportedVersion',
+]);
+// Methods on `jest` and `vi` that take a module specifier as their first
+// argument. Calls like `jest.mock('@nx/devkit/src/...')` are rewritten so the
+// mock target lines up with the rewritten import.
+const MOCK_HELPER_METHODS = new Set([
+    'mock',
+    'unmock',
+    'doMock',
+    'dontMock',
+    'requireActual',
+    'requireMock',
+    'importActual',
+    'importMock',
+]);
+let ts;
+async function updateDevkitDeepImports(tree) {
+    let touchedCount = 0;
+    (0, visit_not_ignored_files_1.visitNotIgnoredFiles)(tree, '.', (filePath) => {
+        if (!TS_EXTENSIONS.some((ext) => filePath.endsWith(ext))) {
+            return;
+        }
+        const original = tree.read(filePath, 'utf-8');
+        if (!original || !original.includes(DEEP_IMPORT_PREFIX)) {
+            return;
+        }
+        const updated = rewriteDevkitDeepImports(original);
+        if (updated !== original) {
+            tree.write(filePath, updated);
+            touchedCount += 1;
+        }
+    });
+    if (touchedCount > 0) {
+        devkit_exports_1.logger.info(`Rewrote @nx/devkit deep imports in ${touchedCount} file(s).`);
+    }
+    await (0, format_files_1.formatFiles)(tree);
+}
+function rewriteDevkitDeepImports(source) {
+    ts ??= (0, package_json_1.ensurePackage)('typescript', versions_1.typescriptVersion);
+    const sourceFile = ts.createSourceFile('tmp.ts', source, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, ts.ScriptKind.TSX);
+    const changes = [];
+    for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        if (!ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        if (!stmt.moduleSpecifier.text.startsWith(DEEP_IMPORT_PREFIX))
+            continue;
+        const replacement = buildReplacement(stmt, sourceFile);
+        changes.push({
+            type: string_change_1.ChangeType.Delete,
+            start: stmt.getStart(sourceFile),
+            length: stmt.getEnd() - stmt.getStart(sourceFile),
+        }, {
+            type: string_change_1.ChangeType.Insert,
+            index: stmt.getStart(sourceFile),
+            text: replacement,
+        });
+    }
+    // Pass 2: rewrite `require('@nx/devkit/src/...')`, dynamic
+    // `import('@nx/devkit/src/...')`, and `jest.mock(...)` / `vi.mock(...)`-style
+    // calls. We can't bucket these by symbol (no named binding to inspect), so
+    // we route them at `/internal` as a best guess. Walking the AST instead of
+    // string-replacing keeps us out of unrelated string literals — template
+    // strings, `typeof import('...')` type queries, comments, etc.
+    collectCallExpressionRewrites(sourceFile, changes);
+    let updated = changes.length > 0 ? (0, string_change_1.applyChangesToString)(source, changes) : source;
+    // Final pass: collapse any duplicate `@nx/devkit` and `@nx/devkit/internal`
+    // named-only imports into a single declaration. This handles both the
+    // imports we just emitted AND any that the user already had, so we never
+    // leave the file with two `from '@nx/devkit'` lines.
+    updated = collapseDevkitImports(updated);
+    return updated;
+}
+function collapseDevkitImports(source) {
+    const sourceFile = ts.createSourceFile('tmp.ts', source, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, ts.ScriptKind.TSX);
+    const groups = new Map();
+    for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        if (!ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        const specifier = stmt.moduleSpecifier.text;
+        if (specifier !== PUBLIC_SPECIFIER && specifier !== INTERNAL_SPECIFIER) {
+            continue;
+        }
+        const importClause = stmt.importClause;
+        if (!importClause)
+            continue; // skip side-effect imports
+        if (importClause.name)
+            continue; // skip default imports
+        const namedBindings = importClause.namedBindings;
+        if (!namedBindings || !ts.isNamedImports(namedBindings))
+            continue;
+        const typeOnly = !!importClause.isTypeOnly;
+        const key = `${specifier}\x00${typeOnly ? 'type' : 'value'}`;
+        if (!groups.has(key)) {
+            groups.set(key, { decls: [], specifier, typeOnly });
+        }
+        groups.get(key).decls.push(stmt);
+    }
+    const changes = [];
+    for (const { decls, specifier, typeOnly } of groups.values()) {
+        if (decls.length < 2)
+            continue;
+        const seen = new Set();
+        const merged = [];
+        for (const decl of decls) {
+            const named = decl.importClause.namedBindings;
+            for (const el of named.elements) {
+                const text = renderSpecifierFromNode(el, typeOnly);
+                if (!seen.has(text)) {
+                    seen.add(text);
+                    merged.push(text);
+                }
+            }
+        }
+        // Replace the first declaration with the merged one in place.
+        const first = decls[0];
+        changes.push({
+            type: string_change_1.ChangeType.Delete,
+            start: first.getStart(sourceFile),
+            length: first.getEnd() - first.getStart(sourceFile),
+        }, {
+            type: string_change_1.ChangeType.Insert,
+            index: first.getStart(sourceFile),
+            text: renderImport(merged, specifier, typeOnly),
+        });
+        // Delete every other declaration in this group (and consume one trailing
+        // newline so we don't leave behind a blank line that prettier has to clean
+        // up later).
+        for (let i = 1; i < decls.length; i++) {
+            const decl = decls[i];
+            const start = decl.getStart(sourceFile);
+            let end = decl.getEnd();
+            if (source[end] === '\n') {
+                end += 1;
+            }
+            else if (source[end] === '\r' && source[end + 1] === '\n') {
+                end += 2;
+            }
+            changes.push({
+                type: string_change_1.ChangeType.Delete,
+                start,
+                length: end - start,
+            });
+        }
+    }
+    return changes.length > 0 ? (0, string_change_1.applyChangesToString)(source, changes) : source;
+}
+function renderSpecifierFromNode(el, parentIsTypeOnly) {
+    const aliasText = el.propertyName ? ` as ${el.name.text}` : '';
+    const typePrefix = !parentIsTypeOnly && el.isTypeOnly ? 'type ' : '';
+    return `${typePrefix}${(el.propertyName ?? el.name).text}${aliasText}`;
+}
+function buildReplacement(decl, sourceFile) {
+    const importClause = decl.importClause;
+    // `import '@nx/devkit/src/...';` (side-effect) — no clause to bucket.
+    if (!importClause) {
+        return `import '${INTERNAL_SPECIFIER}';`;
+    }
+    const namedBindings = importClause.namedBindings;
+    const isNamedImport = namedBindings && ts.isNamedImports(namedBindings) && !importClause.name;
+    // Default / namespace / mixed-default-and-named — can't bucket reliably.
+    // Preserve the import shape, swap the specifier.
+    if (!isNamedImport) {
+        const before = source(decl, sourceFile).slice(0, decl.moduleSpecifier.getStart(sourceFile) - decl.getStart(sourceFile));
+        const after = source(decl, sourceFile).slice(decl.moduleSpecifier.getEnd() - decl.getStart(sourceFile));
+        return `${before}'${INTERNAL_SPECIFIER}'${after}`;
+    }
+    const isTypeOnlyImport = importClause.isTypeOnly;
+    const elements = namedBindings.elements;
+    const publik = [];
+    const internal = [];
+    for (const el of elements) {
+        bucketSpecifier(el, isTypeOnlyImport, publik, internal);
+    }
+    const lines = [];
+    if (publik.length > 0) {
+        lines.push(renderImport(publik, PUBLIC_SPECIFIER, isTypeOnlyImport));
+    }
+    if (internal.length > 0) {
+        lines.push(renderImport(internal, INTERNAL_SPECIFIER, isTypeOnlyImport));
+    }
+    if (lines.length === 0) {
+        // Defensive: empty `import {} from '...'` — point at /internal.
+        lines.push(`import {} from '${INTERNAL_SPECIFIER}';`);
+    }
+    return lines.join('\n');
+}
+function bucketSpecifier(el, parentIsTypeOnly, publik, internal) {
+    const lookupName = (el.propertyName ?? el.name).text;
+    const elementIsTypeOnly = el.isTypeOnly;
+    const aliasText = el.propertyName ? ` as ${el.name.text}` : '';
+    // Inline `type` is illegal when the parent import is already `import type`.
+    const typePrefix = !parentIsTypeOnly && elementIsTypeOnly ? 'type ' : '';
+    const text = `${typePrefix}${(el.propertyName ?? el.name).text}${aliasText}`;
+    if (exports.DEVKIT_INTERNAL_SYMBOLS.has(lookupName)) {
+        internal.push(text);
+    }
+    else {
+        publik.push(text);
+    }
+}
+function renderImport(specifiers, from, typeOnly) {
+    const prefix = typeOnly ? 'import type' : 'import';
+    return `${prefix} { ${specifiers.join(', ')} } from '${from}';`;
+}
+function source(decl, sourceFile) {
+    return sourceFile.text.slice(decl.getStart(sourceFile), decl.getEnd());
+}
+function collectCallExpressionRewrites(sourceFile, changes) {
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            shouldRewriteCallExpression(node) &&
+            node.arguments.length >= 1 &&
+            ts.isStringLiteral(node.arguments[0]) &&
+            node.arguments[0].text.startsWith(DEEP_IMPORT_PREFIX)) {
+            const arg = node.arguments[0];
+            const start = arg.getStart(sourceFile);
+            const end = arg.getEnd();
+            const quote = sourceFile.text.charAt(start);
+            changes.push({
+                type: string_change_1.ChangeType.Delete,
+                start,
+                length: end - start,
+            }, {
+                type: string_change_1.ChangeType.Insert,
+                index: start,
+                text: `${quote}${INTERNAL_SPECIFIER}${quote}`,
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+}
+function shouldRewriteCallExpression(call) {
+    const callee = call.expression;
+    // `require('...')`
+    if (ts.isIdentifier(callee) && callee.text === 'require')
+        return true;
+    // dynamic `import('...')` — the runtime form parses as a CallExpression
+    // whose callee is the `import` keyword. The type-position form
+    // (`typeof import('...')`) parses as `ImportTypeNode`, not a CallExpression,
+    // so we don't touch it.
+    if (callee.kind === ts.SyntaxKind.ImportKeyword)
+        return true;
+    // `jest.mock(...)` / `vi.mock(...)` and friends.
+    if (ts.isPropertyAccessExpression(callee)) {
+        const obj = callee.expression;
+        if (ts.isIdentifier(obj) &&
+            (obj.text === 'jest' || obj.text === 'vi') &&
+            MOCK_HELPER_METHODS.has(callee.name.text)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/src/migrations/update-23-0-0/update-deep-imports.md

@@ -0,0 +1,43 @@
+#### Update `@nx/devkit` deep imports
+
+`@nx/devkit` now ships a strict `exports` map, so deep imports like `@nx/devkit/src/utils/...` and `@nx/devkit/src/generators/...` are no longer reachable through Node module resolution.
+
+This migration scans every `.ts`, `.tsx`, `.cts`, and `.mts` file in your workspace and rewrites those deep imports to one of the supported entry points:
+
+- Symbols that are part of the stable `@nx/devkit` public API are routed to `@nx/devkit`.
+- Symbols that were previously only reachable through deep imports are routed to `@nx/devkit/internal`.
+
+After rewriting, the migration **collapses duplicate imports** so a file never ends up with two `import ... from '@nx/devkit'` (or `@nx/devkit/internal`) lines — including merging into any matching import you already had.
+
+#### Sample Code Changes
+
+##### Before
+
+```ts
+import { Tree } from '@nx/devkit';
+import { dasherize, names } from '@nx/devkit/src/utils/string-utils';
+import { addPlugin } from '@nx/devkit/src/utils/add-plugin';
+```
+
+##### After
+
+```ts
+import { Tree, names } from '@nx/devkit';
+import { dasherize, addPlugin } from '@nx/devkit/internal';
+```
+
+`names` was already in the public API, so it joins the existing `@nx/devkit` import. `dasherize` and `addPlugin` move to `@nx/devkit/internal`, and the two `/internal` imports are collapsed into one.
+
+#### Fallback for non-named imports
+
+For deep-import shapes that can't be split by symbol — default imports, namespace imports, side-effect imports, `require(...)` calls, dynamic `import(...)`, and `jest.mock(...)` / `vi.mock(...)`-style mock-helper calls — the migration rewrites the specifier to `@nx/devkit/internal` as a best guess, since most symbols that previously lived under `@nx/devkit/src/...` ended up there.
+
+```ts
+// Before
+const { dasherize } = require('@nx/devkit/src/utils/string-utils');
+
+// After
+const { dasherize } = require('@nx/devkit/internal');
+```
+
+If the symbol you're after is part of the stable public API instead, the rewritten import will fail to resolve against `@nx/devkit/internal` — switch it to `@nx/devkit` by hand. The migration also leaves `typeof import('@nx/devkit/src/...')` type queries and any deep-import strings inside template literals or comments untouched, so you'll need to update those by hand.

package/{src → dist/src}/tasks/install-packages-task.d.ts

@@ -8,4 +8,3 @@ import { PackageManager, Tree } from 'nx/src/devkit-exports';
  * unless install already ran this generator cycle.
  */
 export declare function installPackagesTask(tree: Tree, ensureInstall?: boolean, cwd?: string, packageManager?: PackageManager): void;
-//# sourceMappingURL=install-packages-task.d.ts.map