docs(nx-dev): render migration docs from the documentation key (#36377)

> [!NOTE]
> `@nx/react-native` declares a `documentation` file that its build
never copies into the published package. That is a packaging bug rather
than a rendering one, and it is fixed separately in #36378. The two PRs
are independent and can merge in any order.

## Current Behavior

The migrations reference pages inline `<implementation>.md` whenever a
file with that name happens to sit next to a migration's implementation,
instead of reading the `documentation` key the entry declares.

Two things fall out of that guess:

- The eslint `update-23-1-0-convert-to-flat-config` migration ships a
`prompt` file whose basename matches its implementation, so its LLM
runbook ("ESLint v9 Flat Config Migration Instructions for LLM") renders
as public documentation on the eslint migrations page.
- Prompt-only migrations never match the guess, since it keys off the
implementation path. The docs declared by
`update-23-1-0-create-ai-instructions-for-next-15` and
`update-23-1-0-create-ai-instructions-for-react-19` therefore never
render, even though both entries separate their agent `prompt` from a
user-facing `documentation` file.

## Expected Behavior

The pages read the `documentation` key and no longer guess from the
implementation basename. The runbook is gone from the eslint page, and
the two prompt-only migrations render the docs they declare.

The two jest setup-file migrations relied on the guess to render their
docs, so they now declare `documentation` explicitly. Every other
migration that rendered through the guess declares the key, so the
runbook is the only content any page loses.

## Related Issue(s)

Fixes NXC-4712

<!-- polygraph-session-start -->
---
[View session information
↗](https://app.trypolygraph.com/orgs/6a061dcb561c062131116eca/sessions/fix-migration-docs-3961141b)
<!-- polygraph-session-end -->

---------

Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>

Author: leosvelperez

astro-docs/src/plugins/utils/generate-plugin-markdown.ts

@@ -29,12 +29,8 @@ export function generateMigrationItem(name: string, item: any): string {
     }
   }
 
-  if (config.fullPath) {
-    const maybeExampleMdFile = config.fullPath + '.md';
-    if (existsSync(maybeExampleMdFile)) {
-      const rawContent = readFileSync(maybeExampleMdFile, 'utf-8');
-      markdown += `${rawContent}\n\n`;
-    }
+  if (config.documentationPath && existsSync(config.documentationPath)) {
+    markdown += `${readFileSync(config.documentationPath, 'utf-8')}\n\n`;
   }
 
   return markdown;

astro-docs/src/plugins/utils/plugin-schema-parser.ts

@@ -133,10 +133,10 @@ export function parseMigrations(pluginPath: string): Map<string, any> | null {
   for (const [name, config] of Object.entries(
     migrationsJson.generators || {}
   ) as [string, any][]) {
-    if (config.implementation || config.factory) {
-      config['fullPath'] = resolvePath(
+    if (config.documentation) {
+      config['documentationPath'] = resolvePath(
         pluginPath,
-        config.implementation || config.factory
+        config.documentation
       );
     }
 

packages/jest/migrations.json

@@ -65,12 +65,14 @@
     "migrate-jest-executor-setup-file": {
       "version": "23.0.0-beta.22",
       "description": "Migrate the deprecated `setupFile` option of the `@nx/jest:jest` executor: push the file path into `setupFilesAfterEnv` in the project's Jest config and remove the option from `project.json` and `nx.json` target defaults.",
-      "implementation": "./dist/src/migrations/update-23-0-0/migrate-jest-executor-setup-file"
+      "implementation": "./dist/src/migrations/update-23-0-0/migrate-jest-executor-setup-file",
+      "documentation": "./dist/src/migrations/update-23-0-0/migrate-jest-executor-setup-file.md"
     },
     "migrate-jest-configuration-skip-setup-file": {
       "version": "23.0.0-beta.22",
       "description": "Migrate the deprecated `skipSetupFile` option of the `@nx/jest:configuration` generator stored as a default in `nx.json` or per-project `project.json` to `setupFile: 'none'` (when `true`) or remove it (when `false`).",
-      "implementation": "./dist/src/migrations/update-23-0-0/migrate-jest-configuration-skip-setup-file"
+      "implementation": "./dist/src/migrations/update-23-0-0/migrate-jest-configuration-skip-setup-file",
+      "documentation": "./dist/src/migrations/update-23-0-0/migrate-jest-configuration-skip-setup-file.md"
     },
     "update-23-0-0-migrate-create-nodes-v2-import": {
       "version": "23.0.0-beta.24",

packages/jest/src/migrations/update-23-0-0/migrate-jest-configuration-skip-setup-file.md

@@ -5,7 +5,7 @@ Migrates the previously deprecated `skipSetupFile` option of the `@nx/jest:confi
 - `skipSetupFile: true` becomes `setupFile: 'none'` (preserving the original behavior of skipping the setup file). Existing `setupFile` values are left untouched.
 - `skipSetupFile: false` is dropped (it was a no-op).
 
-Both flat (`@nx/jest:configuration`) and nested (`@nx/jest` → `configuration`) forms are handled.
+Both flat (`@nx/jest:configuration`) and nested (`@nx/jest` -> `configuration`) forms are handled.
 
 #### Examples
 
@@ -88,4 +88,4 @@ Rewrite a per-project generator default:
 }
 ```
 
-The nested form (`@nx/jest` → `configuration`) is handled the same way.
+The nested form (`@nx/jest` -> `configuration`) is handled the same way.

packages/jest/src/migrations/update-23-0-0/migrate-jest-executor-setup-file.md

@@ -2,7 +2,7 @@
 
 Migrates the previously deprecated `setupFile` option of the `@nx/jest:jest` executor. The setup file path is appended to the `setupFilesAfterEnv` array in the project's Jest configuration (using `<rootDir>/...` form), and the deprecated option is removed from `project.json` and `nx.json` target defaults.
 
-If the Jest configuration cannot be parsed automatically (e.g. it exports a factory function or assigns `setupFilesAfterEnv` to a non-array value), the deprecated option is still removed and a warning is logged listing the affected projects so the setup file path can be moved manually.
+If the setup file cannot be migrated automatically (e.g. the Jest configuration cannot be parsed because it exports a factory function or assigns `setupFilesAfterEnv` to a non-array value, it sets `rootDir` to a non-literal value, or the target shares a Jest configuration with another target using a different setup file), the deprecated option is still removed and a warning is logged listing the affected targets so the setup file path can be moved manually.
 
 #### Examples
 
@@ -135,7 +135,7 @@ Remove the option from a target default using the `@nx/jest:jest` executor:
 }
 ```
 
-Per-project paths don't make sense as workspace defaults, so the option is removed without rewriting individual project Jest configs. A warning is logged so the setup file path can be added to each project's Jest config manually if needed.
+Per-project paths don't make sense as workspace defaults, so the option is removed from `nx.json`. Base targets that inherited it don't lose their setup file: the inherited path is expanded and added to `setupFilesAfterEnv` in each project's Jest config, the same as if the target had declared the option itself. A warning is logged noting the removal from `nx.json`.
 
 Remove the option from a target default entry matching on the `@nx/jest:jest` executor:
 

packages/nx/src/internal-testing-utils/assert-valid-migrations.ts

@@ -61,6 +61,28 @@ export function assertValidMigrationPaths(json: MigrationsJson, root: string) {
 
     expect(orphans).toEqual([]);
   });
+
+  it('should not have orphaned .md files under ./src/migrations', () => {
+    const migrationsPath = path.join(root, 'src/migrations');
+    if (!fs.existsSync(migrationsPath)) return;
+
+    const referenced = new Set<string>();
+    const entries = { ...json.generators, ...(json.schematics ?? {}) };
+    for (const m of Object.values(entries)) {
+      if (m.prompt) {
+        referenced.add(toMigrationMarkdownSourcePath(m.prompt));
+      }
+      if (m.documentation) {
+        referenced.add(toMigrationMarkdownSourcePath(m.documentation));
+      }
+    }
+
+    const orphans = collectMarkdownFiles(migrationsPath)
+      .map((file) => path.relative(root, file).replace(/\\/g, '/'))
+      .filter((rel) => !referenced.has(rel));
+
+    expect(orphans).toEqual([]);
+  });
 }
 
 function validateMigration(m: MigrationsJsonEntry, root: string) {
@@ -140,6 +162,33 @@ function collectMigrationEntryPointFiles(migrationsPath: string): string[] {
   return files;
 }
 
+function collectMarkdownFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectMarkdownFiles(entryPath));
+    } else if (entry.name.endsWith('.md')) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Maps a published markdown path from migrations.json back to its source
+ * location. Most packages build with rootDir "." and publish
+ * `./dist/src/migrations/foo.md`, but packages with rootDir "src" publish
+ * `./dist/migrations/foo.md`, so the stripped `src/` segment is added back.
+ */
+function toMigrationMarkdownSourcePath(publishedPath: string): string {
+  const sourcePath = publishedPath
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^dist\//, '');
+  return sourcePath.startsWith('src/') ? sourcePath : `src/${sourcePath}`;
+}
+
 function normalizeMigrationImplPath(implPath: string): string {
   return implPath
     .split('#')[0]