feat(devkit): migrate @nx/devkit/src/... deep imports (#35541)

## Current Behavior

After #34946, `@nx/devkit` ships a strict `exports` map. Deep imports
like `@nx/devkit/src/utils/...` and `@nx/devkit/src/generators/...` are
no longer reachable through Node module resolution. Workspaces upgrading
to `23.x` that reference those paths break with module-resolution errors
at runtime / type-check time.

## Expected Behavior

`nx migrate` runs an automated rewrite that covers the realistic shapes
of these deep imports.

The migration walks every `.ts`/`.tsx`/`.cts`/`.mts` file in the
workspace and:

1. **Buckets named imports by symbol.** Each `@nx/devkit/src/...` import
declaration is parsed via the TypeScript compiler API (lazy-loaded with
`ensurePackage`). Specifiers in the `internal.ts` re-export list go to
`@nx/devkit/internal`; all others go to `@nx/devkit`. Mixed imports
split into two declarations.
2. **Falls back for non-named shapes.** Default imports, namespace
imports, side-effect imports, `require(...)` calls, and dynamic
`import(...)` get the specifier swapped to `@nx/devkit/internal` (the
safe default — it re-exports every previously deep-importable symbol).
3. **Collapses duplicate imports.** A second AST pass groups `import {
... } from '@nx/devkit'` and `import { ... } from '@nx/devkit/internal'`
declarations by `(specifier, isTypeOnly)`, merging each 2+ group into
one declaration with deduplicated specifiers. This handles both the
duplicates the rewrite produced and any pre-existing devkit imports the
user already had.

Edits are stacked via `applyChangesToString` (devkit's offset-tracking
text-mutation helper), then `formatFiles` normalizes formatting.

### Example

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';
```

### Tests

29 unit tests cover: single-bucket and mixed-bucket rewrites, `as`
aliases, `import type` and inline `type` modifiers, multi-line imports,
side-effect / default / namespace fallbacks, `require()` and dynamic
`import()` fallbacks, quote-style preservation, pre-existing-import
merge, public/internal independence, value-vs-type segregation,
specifier deduplication, and a sanity test that every name in
`DEVKIT_INTERNAL_SYMBOLS` is bucketed as internal.

A user-facing `update-deep-imports.md` lives next to the implementation;
the astro-docs build picks it up via the existing
`packages/*/src/migrations/**/*.md` input glob.

## Related Issue(s)

Follow-up to #34946.

Author: FrozenPandaz

packages/devkit/migrations.json

@@ -1,5 +1,11 @@
 {
-  "generators": {},
+  "generators": {
+    "update-devkit-deep-imports": {
+      "version": "23.0.0-beta.6",
+      "description": "Rewrite imports from `@nx/devkit/src/...` to `@nx/devkit` (for public symbols) or `@nx/devkit/internal` (for the rest), since deep imports are no longer reachable through the package's `exports` map.",
+      "implementation": "./dist/src/migrations/update-23-0-0/update-deep-imports"
+    }
+  },
   "packageJsonUpdates": {},
   "version": "0.1"
 }

packages/devkit/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, and dynamic `import(...)` — 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.

packages/devkit/src/migrations/update-23-0-0/update-deep-imports.spec.ts

@@ -0,0 +1,296 @@
+import { type Tree } from '@nx/devkit';
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import migration, {
+  DEVKIT_INTERNAL_SYMBOLS,
+  rewriteDevkitDeepImports,
+} from './update-deep-imports';
+
+describe('update-deep-imports migration', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+  });
+
+  describe('rewriteDevkitDeepImports', () => {
+    it('routes a single internal symbol to @nx/devkit/internal', () => {
+      const input = `import { dasherize } from '@nx/devkit/src/utils/string-utils';\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(
+        `import { dasherize } from '@nx/devkit/internal';\n`
+      );
+    });
+
+    it('routes a single public symbol to @nx/devkit', () => {
+      const input = `import { names } from '@nx/devkit/src/utils/names';\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(
+        `import { names } from '@nx/devkit';\n`
+      );
+    });
+
+    it('splits mixed public and internal symbols across two declarations', () => {
+      const input = `import { dasherize, names } from '@nx/devkit/src/utils/string-utils';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { names } from '@nx/devkit';`);
+      expect(output).toContain(
+        `import { dasherize } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('preserves `as` aliases', () => {
+      const input = `import { dasherize as toKebab } from '@nx/devkit/src/utils/string-utils';\n`;
+      expect(rewriteDevkitDeepImports(input)).toContain(
+        `import { dasherize as toKebab } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('handles `import type` declarations', () => {
+      const input = `import type { FileExtensionType } from '@nx/devkit/src/generators/artifact-name-and-directory-utils';\n`;
+      expect(rewriteDevkitDeepImports(input)).toContain(
+        `import type { FileExtensionType } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('preserves inline `type` modifiers on individual specifiers', () => {
+      const input = `import { type FileExtensionType, addPlugin } from '@nx/devkit/src/x';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import { type FileExtensionType, addPlugin } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('drops redundant inline `type` when the whole import is already type-only', () => {
+      const input = `import type { type FileExtensionType } from '@nx/devkit/src/x';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import type { FileExtensionType } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('handles multi-line named imports', () => {
+      const input = `import {\n  dasherize,\n  names,\n  classify,\n} from '@nx/devkit/src/utils/string-utils';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { names } from '@nx/devkit';`);
+      expect(output).toContain(
+        `import { dasherize, classify } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('rewrites multiple deep imports in one file', () => {
+      const input =
+        `import { dasherize } from '@nx/devkit/src/utils/string-utils';\n` +
+        `import { names } from '@nx/devkit/src/utils/names';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import { dasherize } from '@nx/devkit/internal';`
+      );
+      expect(output).toContain(`import { names } from '@nx/devkit';`);
+    });
+
+    it('falls back to /internal for side-effect imports', () => {
+      const input = `import '@nx/devkit/src/utils/some-side-effect';\n`;
+      expect(rewriteDevkitDeepImports(input)).toContain(
+        `import '@nx/devkit/internal';`
+      );
+    });
+
+    it('falls back to /internal for default imports', () => {
+      const input = `import x from '@nx/devkit/src/utils/foo';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`'@nx/devkit/internal'`);
+      expect(output).toContain(`import x from`);
+    });
+
+    it('falls back to /internal for namespace imports', () => {
+      const input = `import * as devkit from '@nx/devkit/src/utils/foo';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import * as devkit from '@nx/devkit/internal';`
+      );
+    });
+
+    it('falls back to /internal for require()', () => {
+      const input = `const x = require('@nx/devkit/src/utils/foo');\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(
+        `const x = require('@nx/devkit/internal');\n`
+      );
+    });
+
+    it('falls back to /internal for dynamic import()', () => {
+      const input = `const x = await import('@nx/devkit/src/utils/foo');\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(
+        `const x = await import('@nx/devkit/internal');\n`
+      );
+    });
+
+    it('preserves quote style on fallback paths', () => {
+      const input = `const x = require("@nx/devkit/src/utils/foo");\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(
+        `const x = require("@nx/devkit/internal");\n`
+      );
+    });
+
+    it('does not touch unrelated @nx/devkit imports', () => {
+      const input = `import { Tree } from '@nx/devkit';\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(input);
+    });
+
+    it('does not touch unrelated @nx/devkit/internal imports', () => {
+      const input = `import { dasherize } from '@nx/devkit/internal';\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(input);
+    });
+  });
+
+  describe('migration runner', () => {
+    it('rewrites deep imports across .ts/.tsx/.cts/.mts files', async () => {
+      tree.write(
+        'libs/foo/src/a.ts',
+        `import { dasherize } from '@nx/devkit/src/utils/string-utils';\n`
+      );
+      tree.write(
+        'libs/foo/src/b.tsx',
+        `import { addPlugin } from '@nx/devkit/src/utils/add-plugin';\n`
+      );
+      tree.write(
+        'libs/foo/src/c.cts',
+        `const { classify } = require('@nx/devkit/src/utils/string-utils');\n`
+      );
+      tree.write(
+        'libs/foo/src/d.mts',
+        `import { camelize } from '@nx/devkit/src/utils/string-utils';\n`
+      );
+
+      await migration(tree);
+
+      expect(tree.read('libs/foo/src/a.ts', 'utf-8')).toContain(
+        `'@nx/devkit/internal'`
+      );
+      expect(tree.read('libs/foo/src/b.tsx', 'utf-8')).toContain(
+        `'@nx/devkit/internal'`
+      );
+      expect(tree.read('libs/foo/src/c.cts', 'utf-8')).toContain(
+        `'@nx/devkit/internal'`
+      );
+      expect(tree.read('libs/foo/src/d.mts', 'utf-8')).toContain(
+        `'@nx/devkit/internal'`
+      );
+    });
+
+    it('does not rewrite deep-import strings inside non-TS files', async () => {
+      const md = `Example: \`import { x } from '@nx/devkit/src/utils/foo';\`\n`;
+      tree.write('docs/example.md', md);
+
+      await migration(tree);
+
+      // The deep-import literal must survive untouched in markdown — only TS
+      // sources should be rewritten. (formatFiles may normalize trailing
+      // whitespace, so we assert on substring rather than full equality.)
+      expect(tree.read('docs/example.md', 'utf-8')).toContain(
+        `'@nx/devkit/src/utils/foo'`
+      );
+    });
+
+    it('does not touch files that do not contain the deep prefix', async () => {
+      const content = `import { Tree } from '@nx/devkit';\n`;
+      tree.write('libs/foo/src/index.ts', content);
+
+      await migration(tree);
+
+      expect(tree.read('libs/foo/src/index.ts', 'utf-8')).toBe(content);
+    });
+  });
+
+  describe('collapse', () => {
+    it('merges a rewritten import into a pre-existing @nx/devkit import', () => {
+      const input =
+        `import { Tree } from '@nx/devkit';\n` +
+        `import { names } from '@nx/devkit/src/utils/names';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { Tree, names } from '@nx/devkit';`);
+      expect(output).not.toMatch(
+        /import \{[^}]*\} from '@nx\/devkit';[\s\S]*import \{[^}]*\} from '@nx\/devkit';/
+      );
+    });
+
+    it('merges a rewritten import into a pre-existing @nx/devkit/internal import', () => {
+      const input =
+        `import { dasherize } from '@nx/devkit/internal';\n` +
+        `import { classify } from '@nx/devkit/src/utils/string-utils';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import { dasherize, classify } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('merges multiple rewritten imports that target the same specifier', () => {
+      const input =
+        `import { dasherize } from '@nx/devkit/src/utils/string-utils';\n` +
+        `import { classify } from '@nx/devkit/src/utils/string-utils';\n` +
+        `import { camelize } from '@nx/devkit/src/utils/string-utils';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(
+        `import { dasherize, classify, camelize } from '@nx/devkit/internal';`
+      );
+      // Only one /internal declaration in the output.
+      expect((output.match(/from '@nx\/devkit\/internal'/g) ?? []).length).toBe(
+        1
+      );
+    });
+
+    it('keeps public and internal collapses independent', () => {
+      const input =
+        `import { Tree } from '@nx/devkit';\n` +
+        `import { dasherize, names } from '@nx/devkit/src/utils/string-utils';\n` +
+        `import { classify } from '@nx/devkit/src/utils/string-utils';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { Tree, names } from '@nx/devkit';`);
+      expect(output).toContain(
+        `import { dasherize, classify } from '@nx/devkit/internal';`
+      );
+    });
+
+    it('does not merge value imports with type-only imports', () => {
+      const input =
+        `import type { Tree } from '@nx/devkit';\n` +
+        `import { names } from '@nx/devkit/src/utils/names';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import type { Tree } from '@nx/devkit';`);
+      expect(output).toContain(`import { names } from '@nx/devkit';`);
+    });
+
+    it('merges duplicate specifiers without repeating them', () => {
+      const input =
+        `import { Tree } from '@nx/devkit';\n` +
+        `import { Tree, names } from '@nx/devkit';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { Tree, names } from '@nx/devkit';`);
+      expect((output.match(/Tree/g) ?? []).length).toBe(1);
+    });
+
+    it('does not touch a file that already has a single canonical import', () => {
+      const input = `import { Tree, names } from '@nx/devkit';\n`;
+      expect(rewriteDevkitDeepImports(input)).toBe(input);
+    });
+
+    it('leaves unrelated imports between merged declarations alone', () => {
+      const input =
+        `import { Tree } from '@nx/devkit';\n` +
+        `import { readFileSync } from 'node:fs';\n` +
+        `import { names } from '@nx/devkit/src/utils/names';\n`;
+      const output = rewriteDevkitDeepImports(input);
+      expect(output).toContain(`import { Tree, names } from '@nx/devkit';`);
+      expect(output).toContain(`import { readFileSync } from 'node:fs';`);
+    });
+  });
+
+  describe('symbol set sanity', () => {
+    it('treats every name in DEVKIT_INTERNAL_SYMBOLS as internal', () => {
+      for (const name of DEVKIT_INTERNAL_SYMBOLS) {
+        const input = `import { ${name} } from '@nx/devkit/src/x';\n`;
+        const output = rewriteDevkitDeepImports(input);
+        expect(output).toContain(
+          `import { ${name} } from '@nx/devkit/internal';`
+        );
+      }
+    });
+  });
+});