From dd2d6e1ce1479c0a28264c41ae2c5e1b3ced2800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leosvel=20P=C3=A9rez=20Espinosa?= Date: Fri, 29 May 2026 18:30:59 +0200 Subject: [PATCH 1/4] feat(core): feed migration docs to agents in nx migrate Migration entries can now declare a `docs` markdown path. Under `nx migrate --run-migrations --agentic`, the resolved path is surfaced to the agent for prompt, hybrid, and validation steps so it has context on what the migration is meant to do. The path resolves like implementation/factory and is non-fatal when absent. --- .../prompts/generic-validation.spec.ts | 11 +++ .../agentic/prompts/generic-validation.ts | 5 ++ .../prompts/hybrid-prompt-migration.spec.ts | 11 +++ .../prompts/hybrid-prompt-migration.ts | 5 ++ .../agentic/prompts/prompt-migration.spec.ts | 18 +++++ .../agentic/prompts/prompt-migration.ts | 4 + .../agentic/prompts/shared-rendering.spec.ts | 24 ++++++ .../agentic/prompts/shared-rendering.ts | 15 ++++ .../command-line/migrate/agentic/run-step.ts | 9 +++ .../src/command-line/migrate/migrate.spec.ts | 79 +++++++++++++++++++ .../nx/src/command-line/migrate/migrate.ts | 60 +++++++++++++- packages/nx/src/config/misc-interfaces.ts | 7 ++ 12 files changed, 247 insertions(+), 1 deletion(-) diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts index 93ac0dfc08c..1d9d9924dc2 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts @@ -42,6 +42,17 @@ describe('buildGenericValidationUserPrompt', () => { expect(out).not.toContain(''); }); + it('renders the block when a docs path is provided, and omits it otherwise', () => { + const docsPath = + 'node_modules/@nx/react/dist/src/migrations/update-21-1-0/rewrite-config.md'; + const withDocs = buildGenericValidationUserPrompt({ ...baseCtx, docsPath }); + expect(withDocs).toContain(docsPath); + expect(withDocs).toMatch(//); + expect(buildGenericValidationUserPrompt(baseCtx)).not.toContain( + ' { it('points the agent at git (no ) when hasDiffContext is true', () => { const out = buildGenericValidationUserPrompt({ diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.ts b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.ts index a5a78577b41..0329b8f4799 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.ts @@ -8,6 +8,7 @@ import { renderGitInspectInstruction, renderHandoffPathFooter, renderMigrationBlock, + renderMigrationDocsBlock, stripAnsi, } from './shared-rendering'; @@ -18,6 +19,8 @@ export interface GenericValidationPromptContext { description?: string; /** Absolute path the agent must write its handoff file to. */ handoffFileAbsolutePath: string; + /** Workspace-relative path to the migration's documentation file, if any. */ + docsPath?: string; /** Context captured from the deterministic generator phase. */ impl: { /** Raw output from the generator (devkit logger + console). */ @@ -70,6 +73,8 @@ export function buildGenericValidationUserPrompt( ...renderMigrationBlock(ctx), ]; + lines.push(...renderMigrationDocsBlock(ctx.docsPath)); + const logs = escapeXmlBody(stripAnsi(ctx.impl.logs ?? '').trim()); lines.push(...renderGeneratorOutputBlock(logs)); diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.spec.ts index b46037d713a..6aaa48f3fe5 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.spec.ts @@ -39,6 +39,17 @@ describe('buildHybridPromptUserPrompt', () => { expect(out).not.toContain(' block when a docs path is provided, and omits it otherwise', () => { + const docsPath = + 'node_modules/@nx/react/dist/src/migrations/update-21-1-0/rewrite-config.md'; + const withDocs = buildHybridPromptUserPrompt({ ...baseCtx, docsPath }); + expect(withDocs).toContain(docsPath); + expect(withDocs).toMatch(//); + expect(buildHybridPromptUserPrompt(baseCtx)).not.toContain( + ' block when provided', () => { const out = buildHybridPromptUserPrompt({ ...baseCtx, diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.ts b/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.ts index b55b1fc2292..934548adcea 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.ts @@ -8,6 +8,7 @@ import { renderGitInspectInstruction, renderHandoffPathFooter, renderMigrationBlock, + renderMigrationDocsBlock, stripAnsi, } from './shared-rendering'; @@ -20,6 +21,8 @@ export interface HybridPromptMigrationContext { promptPath: string; /** Absolute path the agent must write its handoff file to. */ handoffFileAbsolutePath: string; + /** Workspace-relative path to the migration's documentation file, if any. */ + docsPath?: string; /** Context captured from the deterministic generator phase. */ impl?: { /** Raw output from the generator (devkit logger + console). */ @@ -62,6 +65,8 @@ export function buildHybridPromptUserPrompt( ...renderMigrationBlock(ctx), ]; + lines.push(...renderMigrationDocsBlock(ctx.docsPath)); + const logs = escapeXmlBody(stripAnsi(ctx.impl?.logs ?? '').trim()); const agentContext = filterNonEmptyStrings(ctx.impl?.agentContext ?? []); const hasDiffContext = !!ctx.impl?.hasDiffContext; diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.spec.ts index 04893d8b1e2..05a53cb6101 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.spec.ts @@ -36,6 +36,24 @@ describe('buildPromptMigrationUserPrompt', () => { expect(buildPromptMigrationUserPrompt(base)).not.toContain('description:'); }); + it('renders the block when a docs path is provided', () => { + const result = buildPromptMigrationUserPrompt({ + ...base, + docsPath: + 'node_modules/@nx/storybook/src/migrations/9-2-0/migrate-css-imports.md', + }); + expect(result).toContain( + 'node_modules/@nx/storybook/src/migrations/9-2-0/migrate-css-imports.md' + ); + expect(result).toMatch(//); + }); + + it('omits the block when no docs path is provided', () => { + expect(buildPromptMigrationUserPrompt(base)).not.toContain( + ' { const result = buildPromptMigrationUserPrompt({ package: '@evil/pkg', diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.ts b/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.ts index fe56beee3e7..e02235183d8 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/prompt-migration.ts @@ -2,6 +2,7 @@ import { escapeXmlBody, renderHandoffPathFooter, renderMigrationBlock, + renderMigrationDocsBlock, } from './shared-rendering'; export interface PromptMigrationContext { @@ -13,6 +14,8 @@ export interface PromptMigrationContext { promptPath: string; /** Absolute path the agent must write its handoff file to. */ handoffFileAbsolutePath: string; + /** Workspace-relative path to the migration's documentation file, if any. */ + docsPath?: string; } /** @@ -31,6 +34,7 @@ export function buildPromptMigrationUserPrompt( const lines = [ `Apply one prompt-based migration to this Nx workspace.`, ...renderMigrationBlock(ctx), + ...renderMigrationDocsBlock(ctx.docsPath), ``, `${escapeXmlBody(ctx.promptPath)}`, ``, diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts index 4cf130d1ab7..caa4c15a537 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts @@ -3,6 +3,7 @@ import { renderGitInspectInstruction, renderKeyMultilineValue, renderListItem, + renderMigrationDocsBlock, stripAnsi, } from './shared-rendering'; @@ -56,6 +57,29 @@ describe('shared-rendering', () => { }); }); + describe('renderMigrationDocsBlock', () => { + it('returns an empty array when no docs path is provided', () => { + expect(renderMigrationDocsBlock(undefined)).toEqual([]); + }); + + it('renders a reference-framed block pointing at the docs path', () => { + const out = renderMigrationDocsBlock( + 'node_modules/@nx/webpack/src/migrations/update-21-0-0/remove-isolated-config.md' + ); + expect(out).toEqual([ + ``, + ``, + `node_modules/@nx/webpack/src/migrations/update-21-0-0/remove-isolated-config.md`, + ``, + ]); + }); + + it('escapes the docs path so a hostile path cannot break out of the block', () => { + const out = renderMigrationDocsBlock('a { it('points the agent at the workspace-scoped git commands and explains the working-tree guarantee', () => { const out = renderGitInspectInstruction(); diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.ts b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.ts index 11f8cafd13e..a2d0e4ada29 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.ts @@ -144,3 +144,18 @@ export function renderAdvisoryContext( ``, ]; } + +// Points the agent at the migration's doc file (reference, not instructions). +// Returns `[]` when there's no doc so callers can spread without guarding; the +// path is escaped like other user-authored values interpolated into the prompt. +export function renderMigrationDocsBlock( + docsPath: string | undefined +): string[] { + if (!docsPath) return []; + return [ + ``, + ``, + escapeXmlBody(docsPath), + ``, + ]; +} diff --git a/packages/nx/src/command-line/migrate/agentic/run-step.ts b/packages/nx/src/command-line/migrate/agentic/run-step.ts index d6c30866615..74f75bbe848 100644 --- a/packages/nx/src/command-line/migrate/agentic/run-step.ts +++ b/packages/nx/src/command-line/migrate/agentic/run-step.ts @@ -49,6 +49,12 @@ export interface RunAgenticPromptStepInput { description?: string; prompt?: string; }; + /** + * Workspace-relative path to the migration's docs file, resolved by the + * orchestrator; omitted when the migration declares no `docs` or it can't be + * resolved. + */ + docsPath?: string; agentic: EnabledResolvedAgentic; runDir: string; installDepsIfChanged: () => Promise; @@ -77,6 +83,7 @@ export async function runAgenticPromptStep( runDir, installDepsIfChanged, implContext, + docsPath, mode = 'author', } = input; @@ -110,6 +117,7 @@ export async function runAgenticPromptStep( version: migration.version, description: migration.description, handoffFileAbsolutePath: handoffFilePath, + docsPath, impl: implContext, }); } else { @@ -120,6 +128,7 @@ export async function runAgenticPromptStep( description: migration.description, promptPath: migration.prompt!, handoffFileAbsolutePath: handoffFilePath, + docsPath, }; userPrompt = implContext ? buildHybridPromptUserPrompt({ ...promptCtx, impl: implContext }) diff --git a/packages/nx/src/command-line/migrate/migrate.spec.ts b/packages/nx/src/command-line/migrate/migrate.spec.ts index 10285ab1bb7..3778bea5b68 100644 --- a/packages/nx/src/command-line/migrate/migrate.spec.ts +++ b/packages/nx/src/command-line/migrate/migrate.spec.ts @@ -35,6 +35,7 @@ import { ResolvedMigrationConfiguration, resolveCanonicalNxPackage, resolveCreateCommits, + resolveMigrationDocsPath, resolveMode, } from './migrate'; import { @@ -47,6 +48,7 @@ import { mkdirSync, mkdtempSync, readFileSync, + realpathSync, rmSync, writeFileSync, } from 'fs'; @@ -4236,4 +4238,81 @@ describe('Migration', () => { }); }); }); + + describe('resolveMigrationDocsPath', () => { + let tmpRoot: string; + + const writeInstalledPackage = ( + pkgName: string, + docsRelToMigrationsDir: string | null + ) => { + const pkgDir = join(tmpRoot, 'node_modules', pkgName); + mkdirSync(pkgDir, { recursive: true }); + writeFileSync( + join(pkgDir, 'package.json'), + JSON.stringify({ + name: pkgName, + version: '1.0.0', + 'nx-migrations': './migrations.json', + }) + ); + writeFileSync( + join(pkgDir, 'migrations.json'), + JSON.stringify({ generators: {} }) + ); + if (docsRelToMigrationsDir) { + const docAbs = join(pkgDir, docsRelToMigrationsDir); + mkdirSync(dirname(docAbs), { recursive: true }); + writeFileSync(docAbs, '# doc'); + } + }; + + beforeEach(() => { + // realpath so the workspace-relative assertion isn't defeated by the + // macOS /tmp -> /private/tmp symlink (require.resolve returns realpaths). + tmpRoot = realpathSync(mkdtempSync(join(tmpdir(), 'nx-migration-docs-'))); + }); + + afterEach(() => { + rmSync(tmpRoot, { recursive: true, force: true }); + }); + + it('returns undefined when the migration declares no docs', () => { + writeInstalledPackage('@nx/foo', null); + expect( + resolveMigrationDocsPath(tmpRoot, { package: '@nx/foo' }) + ).toBeUndefined(); + }); + + it('resolves the docs file to a workspace-relative node_modules path', () => { + writeInstalledPackage('@nx/foo', './src/migrations/update-1-0-0/do.md'); + expect( + resolveMigrationDocsPath(tmpRoot, { + package: '@nx/foo', + docs: './src/migrations/update-1-0-0/do.md', + }) + ).toBe( + join('node_modules', '@nx/foo', 'src/migrations/update-1-0-0/do.md') + ); + }); + + it('returns undefined when the docs file is not present in the installed package', () => { + writeInstalledPackage('@nx/foo', null); + expect( + resolveMigrationDocsPath(tmpRoot, { + package: '@nx/foo', + docs: './src/migrations/update-1-0-0/missing.md', + }) + ).toBeUndefined(); + }); + + it('returns undefined when the package cannot be resolved', () => { + expect( + resolveMigrationDocsPath(tmpRoot, { + package: '@nx/not-installed', + docs: './x.md', + }) + ).toBeUndefined(); + }); + }); }); diff --git a/packages/nx/src/command-line/migrate/migrate.ts b/packages/nx/src/command-line/migrate/migrate.ts index 69663e9809f..78349ec30f4 100644 --- a/packages/nx/src/command-line/migrate/migrate.ts +++ b/packages/nx/src/command-line/migrate/migrate.ts @@ -2,7 +2,7 @@ import * as pc from 'picocolors'; import { exec, execSync, spawn, type StdioOptions } from 'child_process'; import { migratePrompt } from './safe-prompt'; import { handleImport } from '../../utils/handle-import'; -import { dirname, join } from 'path'; +import { dirname, join, relative } from 'path'; import { createRequire } from 'module'; import { joinPathFragments } from '../../utils/path'; import { @@ -2374,6 +2374,7 @@ type ExecutableMigration = { implementation?: string; factory?: string; prompt?: string; + docs?: string; }; export { isPromptOnlyMigration, isHybridMigration }; @@ -2652,6 +2653,9 @@ export async function executeMigrations( // Content-sensitive so a dirty→dirty case (this migration mutating an // already-dirty shared file like `package.json`) doesn't collapse. const baselineWorkingTreeSnapshot = getUncommittedChangesSnapshot(root); + // Resolve the migration's docs file once per iteration, only when an + // agentic step may consume it (skips the node_modules lookup otherwise). + const docsPath = agenticRun ? resolveMigrationDocsPath(root, m) : undefined; try { let outcome: MigrationOutcomeKind; let commit: CommitState = { kind: 'none' }; @@ -2663,6 +2667,7 @@ export async function executeMigrations( agentic: agenticRun.agentic, runDir: agenticRun.runDir, installDepsIfChanged, + docsPath, }); commit = await attemptMigrationCommit(m); logAgenticSuccessOutcome( @@ -2700,6 +2705,7 @@ export async function executeMigrations( agentic: agenticRun.agentic, runDir: agenticRun.runDir, installDepsIfChanged, + docsPath, implContext: { logs, changes, @@ -2774,6 +2780,7 @@ export async function executeMigrations( agentic: validationRun.agentic, runDir: validationRun.runDir, installDepsIfChanged, + docsPath, implContext: { logs, changes, @@ -3451,6 +3458,57 @@ export function getImplementationPath( return { path: implPath, fnSymbol }; } +/** + * Resolves a migration's `docs` file to a workspace-relative path for the + * agentic prompt. The authored `docs` path is relative to the package's + * `migrations.json` and resolved against the installed package, the same way + * `implementation` / `factory` are resolved in `getImplementationPath`. + * + * Returns `undefined` when the migration declares no `docs` or the file can't + * be resolved. Docs are supplementary context, so a missing file is non-fatal + * here (unlike a missing implementation, which aborts the migration). + */ +export function resolveMigrationDocsPath( + root: string, + migration: { package: string; docs?: string } +): string | undefined { + if (!migration.docs) { + return undefined; + } + + let migrationsFilePath: string | null; + try { + migrationsFilePath = readPackageMigrationConfig( + migration.package, + root + ).migrations; + } catch { + return undefined; + } + if (!migrationsFilePath) { + return undefined; + } + + const migrationsDir = dirname(migrationsFilePath); + let docsPath: string; + try { + docsPath = require.resolve(migration.docs, { paths: [migrationsDir] }); + } catch { + try { + // workaround for a bug in node 12 + docsPath = require.resolve(`${migrationsDir}/${migration.docs}`); + } catch { + return undefined; + } + } + + // The agent runs with cwd = workspace root, so prefer a workspace-relative + // path. Fall back to the absolute path if the doc resolves outside root + // (e.g. an unusual hoisted/symlinked node_modules layout). + const relativePath = relative(root, docsPath); + return relativePath.startsWith('..') ? docsPath : relativePath; +} + class MigrationImplementationMissingError extends Error { constructor( baseMessage: string, diff --git a/packages/nx/src/config/misc-interfaces.ts b/packages/nx/src/config/misc-interfaces.ts index a9a6bdfefb0..7e34dcd2405 100644 --- a/packages/nx/src/config/misc-interfaces.ts +++ b/packages/nx/src/config/misc-interfaces.ts @@ -108,6 +108,13 @@ export interface MigrationsJsonEntry { factory?: string; prompt?: string; requires?: Record; + /** + * Path to a markdown doc describing the migration, relative to the + * `migrations.json` and resolved like `implementation`/`factory`. Always + * supplementary; never stands in for them. Under `--run-migrations + * --agentic` the resolved path is passed to the agent as extra context. + */ + docs?: string; } export type MigrationDetailsWithId = GeneratedMigrationDetails & { From 0c3e220090df5ec2fb77d0c94cf8c2db604d3f87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leosvel=20P=C3=A9rez=20Espinosa?= Date: Fri, 29 May 2026 18:31:20 +0200 Subject: [PATCH 2/4] chore(misc): publish migration docs and reference them in migrations.json Add a `src/migrations/**/*.md` asset glob to the plugins that lacked it so co-located migration docs are published, and reference each existing migration's doc via the new `docs` field. --- packages/angular/assets.json | 1 + packages/angular/migrations.json | 93 +++++++++++++++++++++----------- packages/cypress/assets.json | 1 + packages/cypress/migrations.json | 27 ++++++---- packages/devkit/migrations.json | 3 +- packages/eslint/migrations.json | 6 ++- packages/gradle/assets.json | 1 + packages/gradle/migrations.json | 69 ++++++++++++++++-------- packages/jest/migrations.json | 24 ++++++--- packages/js/migrations.json | 9 ++-- packages/nx/migrations.json | 27 ++++++---- packages/react/assets.json | 1 + packages/react/migrations.json | 18 ++++--- packages/rollup/assets.json | 1 + packages/rollup/migrations.json | 3 +- packages/rspack/migrations.json | 9 ++-- packages/vite/migrations.json | 21 +++++--- packages/vitest/migrations.json | 6 ++- packages/webpack/assets.json | 1 + packages/webpack/migrations.json | 6 ++- 20 files changed, 220 insertions(+), 107 deletions(-) diff --git a/packages/angular/assets.json b/packages/angular/assets.json index 6edbba600e2..1d3c2b9248f 100644 --- a/packages/angular/assets.json +++ b/packages/angular/assets.json @@ -6,6 +6,7 @@ { "glob": "@(package|executors|generators|migrations).json" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, "LICENSE" ] } diff --git a/packages/angular/migrations.json b/packages/angular/migrations.json index ca7a530614a..c8c2b5aa2e5 100644 --- a/packages/angular/migrations.json +++ b/packages/angular/migrations.json @@ -43,13 +43,15 @@ "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the ModuleFederationConfig import use @nx/module-federation.", - "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package" + "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package", + "docs": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" }, "update-20-2-0-update-with-module-federation-import": { "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the withModuleFederation import use @nx/module-federation/angular.", - "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package" + "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", + "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "update-angular-cli-version-19-0-0": { "cli": "nx", @@ -58,7 +60,8 @@ "@angular/core": ">=19.0.0" }, "description": "Update the @angular/cli package version to ~19.0.0.", - "factory": "./src/migrations/update-20-2-0/update-angular-cli" + "factory": "./src/migrations/update-20-2-0/update-angular-cli", + "docs": "./src/migrations/update-20-2-0/update-angular-cli.md" }, "add-localize-polyfill-to-targets": { "cli": "nx", @@ -67,7 +70,8 @@ "@angular/core": ">=19.0.0" }, "description": "Add the '@angular/localize/init' polyfill to the 'polyfills' option of targets using esbuild-based executors.", - "factory": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets" + "factory": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets", + "docs": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets.md" }, "update-angular-ssr-imports-to-use-node-entry-point": { "cli": "nx", @@ -76,7 +80,8 @@ "@angular/core": ">=19.0.0" }, "description": "Update '@angular/ssr' import paths to use the new '/node' entry point when 'CommonEngine' is detected.", - "factory": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point" + "factory": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point", + "docs": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point.md" }, "disable-angular-eslint-prefer-standalone": { "cli": "nx", @@ -85,7 +90,8 @@ "@angular/core": ">=19.0.0" }, "description": "Disable the Angular ESLint prefer-standalone rule if not set.", - "factory": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone" + "factory": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone", + "docs": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone.md" }, "remove-angular-eslint-rules": { "cli": "nx", @@ -94,7 +100,8 @@ "@angular/core": ">=19.0.0" }, "description": "Remove Angular ESLint rules that were removed in v19.0.0.", - "factory": "./src/migrations/update-20-2-0/remove-angular-eslint-rules" + "factory": "./src/migrations/update-20-2-0/remove-angular-eslint-rules", + "docs": "./src/migrations/update-20-2-0/remove-angular-eslint-rules.md" }, "remove-tailwind-config-from-ng-packagr-executors": { "cli": "nx", @@ -103,13 +110,15 @@ "@angular/core": ">=19.0.0" }, "description": "Remove the deprecated 'tailwindConfig' option from ng-packagr executors. Tailwind CSS configurations located at the project or workspace root will be picked up automatically.", - "factory": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors" + "factory": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors", + "docs": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", - "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package" + "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", + "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "update-angular-cli-version-19-1-0": { "cli": "nx", @@ -118,7 +127,8 @@ "@angular/core": ">=19.1.0" }, "description": "Update the @angular/cli package version to ~19.1.0.", - "factory": "./src/migrations/update-20-4-0/update-angular-cli" + "factory": "./src/migrations/update-20-4-0/update-angular-cli", + "docs": "./src/migrations/update-20-4-0/update-angular-cli.md" }, "update-angular-cli-version-19-2-0": { "cli": "nx", @@ -127,13 +137,15 @@ "@angular/core": ">=19.2.0" }, "description": "Update the @angular/cli package version to ~19.2.0.", - "factory": "./src/migrations/update-20-5-0/update-angular-cli" + "factory": "./src/migrations/update-20-5-0/update-angular-cli", + "docs": "./src/migrations/update-20-5-0/update-angular-cli.md" }, "set-continuous-option": { "cli": "nx", "version": "21.0.0-beta.3", "description": "Set the `continuous` option to `true` for continuous tasks.", - "factory": "./src/migrations/update-21-0-0/set-continuous-option" + "factory": "./src/migrations/update-21-0-0/set-continuous-option", + "docs": "./src/migrations/update-21-0-0/set-continuous-option.md" }, "change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence": { "cli": "nx", @@ -142,7 +154,8 @@ "@ngrx/store": ">=16.0.0" }, "description": "Change the data persistence operator imports to '@ngrx/router-store/data-persistence'.", - "factory": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence" + "factory": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence", + "docs": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence.md" }, "update-angular-cli-version-20-0-0": { "cli": "nx", @@ -151,7 +164,8 @@ "@angular/core": ">=20.0.0" }, "description": "Update the @angular/cli package version to ~20.0.0.", - "factory": "./src/migrations/update-21-2-0/update-angular-cli" + "factory": "./src/migrations/update-21-2-0/update-angular-cli", + "docs": "./src/migrations/update-21-2-0/update-angular-cli.md" }, "migrate-provide-server-rendering-import": { "version": "21.2.0-beta.3", @@ -159,7 +173,8 @@ "@angular/core": ">=20.0.0" }, "description": "Migrate imports of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`.", - "factory": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import" + "factory": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import", + "docs": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import.md" }, "replace-provide-server-routing": { "version": "21.2.0-beta.3", @@ -167,7 +182,8 @@ "@angular/core": ">=20.0.0" }, "description": "Replace `provideServerRouting` and `provideServerRoutesConfig` with `provideServerRendering` using `withRoutes`.", - "factory": "./src/migrations/update-21-2-0/replace-provide-server-routing" + "factory": "./src/migrations/update-21-2-0/replace-provide-server-routing", + "docs": "./src/migrations/update-21-2-0/replace-provide-server-routing.md" }, "set-generator-defaults-for-previous-style-guide": { "version": "21.2.0-beta.3", @@ -175,7 +191,8 @@ "@angular/core": ">=20.0.0" }, "description": "Update the generator defaults to maintain the previous style guide behavior.", - "factory": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide" + "factory": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide", + "docs": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide.md" }, "update-module-resolution": { "version": "21.2.0-beta.3", @@ -183,7 +200,8 @@ "@angular/core": ">=20.0.0" }, "description": "Update 'moduleResolution' to 'bundler' in TypeScript configurations. You can read more about this here: https://www.typescriptlang.org/tsconfig/#moduleResolution.", - "factory": "./src/migrations/update-21-2-0/update-module-resolution" + "factory": "./src/migrations/update-21-2-0/update-module-resolution", + "docs": "./src/migrations/update-21-2-0/update-module-resolution.md" }, "update-angular-cli-version-20-1-0": { "cli": "nx", @@ -192,12 +210,14 @@ "@angular/core": ">=20.1.0" }, "description": "Update the @angular/cli package version to ~20.1.0.", - "factory": "./src/migrations/update-21-3-0/update-angular-cli" + "factory": "./src/migrations/update-21-3-0/update-angular-cli", + "docs": "./src/migrations/update-21-3-0/update-angular-cli.md" }, "set-tsconfig-option": { "version": "21.5.0-beta.0", "description": "Set the 'tsConfig' option to build and test targets to help with Angular migration issues.", - "factory": "./src/migrations/update-21-5-0/set-tsconfig-option" + "factory": "./src/migrations/update-21-5-0/set-tsconfig-option", + "docs": "./src/migrations/update-21-5-0/set-tsconfig-option.md" }, "update-angular-cli-version-20-2-0": { "cli": "nx", @@ -206,7 +226,8 @@ "@angular/core": ">=20.2.0" }, "description": "Update the @angular/cli package version to ~20.2.0.", - "factory": "./src/migrations/update-21-5-0/update-angular-cli" + "factory": "./src/migrations/update-21-5-0/update-angular-cli", + "docs": "./src/migrations/update-21-5-0/update-angular-cli.md" }, "remove-default-karma-configuration-files": { "version": "21.5.0-beta.2", @@ -214,7 +235,8 @@ "@angular/core": ">=20.2.0" }, "description": "Remove any Karma configuration files that only contain the default content. The default configuration is automatically available without a specific project configurationfile.", - "factory": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files" + "factory": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files", + "docs": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files.md" }, "update-angular-cli-version-20-3-0": { "cli": "nx", @@ -223,7 +245,8 @@ "@angular/core": ">=20.3.0" }, "description": "Update the @angular/cli package version to ~20.3.0.", - "factory": "./src/migrations/update-21-6-1/update-angular-cli" + "factory": "./src/migrations/update-21-6-1/update-angular-cli", + "docs": "./src/migrations/update-21-6-1/update-angular-cli.md" }, "update-ssr-webpack-config-22-2-0": { "version": "22.3.0-beta.0", @@ -231,7 +254,8 @@ "@angular/core": ">=21.0.0" }, "description": "Updates webpack-based SSR configuration to use preserve module format and bundler module resolution.", - "factory": "./src/migrations/update-22-3-0/update-ssr-webpack-config" + "factory": "./src/migrations/update-22-3-0/update-ssr-webpack-config", + "docs": "./src/migrations/update-22-3-0/update-ssr-webpack-config.md" }, "update-module-resolution-22-2-0": { "version": "22.3.0-beta.0", @@ -239,7 +263,8 @@ "@angular/core": ">=21.0.0-rc.3" }, "description": "Update 'module' to 'preserve' and 'moduleResolution' to 'bundler' in TypeScript configurations for Angular projects.", - "factory": "./src/migrations/update-22-3-0/update-module-resolution" + "factory": "./src/migrations/update-22-3-0/update-module-resolution", + "docs": "./src/migrations/update-22-3-0/update-module-resolution.md" }, "update-typescript-lib-22-2-0": { "version": "22.3.0-beta.0", @@ -247,12 +272,14 @@ "@angular/core": ">=21.0.0" }, "description": "Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version.", - "factory": "./src/migrations/update-22-3-0/update-typescript-lib" + "factory": "./src/migrations/update-22-3-0/update-typescript-lib", + "docs": "./src/migrations/update-22-3-0/update-typescript-lib.md" }, "update-unit-test-runner-option": { "version": "22.3.0-beta.0", "description": "Update 'vitest' unit test runner option to 'vitest-analog' in generator defaults.", - "factory": "./src/migrations/update-22-3-0/update-unit-test-runner-option" + "factory": "./src/migrations/update-22-3-0/update-unit-test-runner-option", + "docs": "./src/migrations/update-22-3-0/update-unit-test-runner-option.md" }, "set-isolated-modules-22-3-0": { "version": "22.3.0-beta.3", @@ -260,7 +287,8 @@ "@angular/core": ">=21.0.0" }, "description": "Set 'isolatedModules' to 'true' in TypeScript test configurations for Angular projects.", - "factory": "./src/migrations/update-22-3-0/set-isolated-modules" + "factory": "./src/migrations/update-22-3-0/set-isolated-modules", + "docs": "./src/migrations/update-22-3-0/set-isolated-modules.md" }, "update-jest-preset-angular-setup": { "version": "22.3.0-beta.3", @@ -268,17 +296,20 @@ "@angular/core": ">=21.0.0" }, "description": "Replace 'jest-preset-angular/setup-jest' imports with the new 'setupZoneTestEnv' function.", - "factory": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup" + "factory": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup", + "docs": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup.md" }, "update-23-0-0-update-with-module-federation-import": { "version": "23.0.0-beta.0", "description": "Update the @nx/angular/module-federation import to use @nx/module-federation/angular.", - "factory": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package" + "factory": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package", + "docs": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package.md" }, "update-23-0-0-migrate-ngrx-generator-defaults": { "version": "23.0.0-beta.7", "description": "Split @nx/angular:ngrx generator defaults in nx.json across the @nx/angular:ngrx-root-store and @nx/angular:ngrx-feature-store generators.", - "factory": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults" + "factory": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults", + "docs": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults.md" } }, "packageJsonUpdates": { diff --git a/packages/cypress/assets.json b/packages/cypress/assets.json index bf786672705..0937a8f4c52 100644 --- a/packages/cypress/assets.json +++ b/packages/cypress/assets.json @@ -4,6 +4,7 @@ { "glob": "**/files/**" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, { "glob": "PLUGIN.md" }, "LICENSE" ] diff --git a/packages/cypress/migrations.json b/packages/cypress/migrations.json index 5111b26c84e..83de8761490 100644 --- a/packages/cypress/migrations.json +++ b/packages/cypress/migrations.json @@ -7,7 +7,8 @@ "cypress": ">=14.0.0" }, "description": "Replaces the `experimentalSkipDomainInjection` configuration option with the new `injectDocumentDomain` configuration option.", - "implementation": "./dist/src/migrations/update-20-8-0/set-inject-document-domain" + "implementation": "./dist/src/migrations/update-20-8-0/set-inject-document-domain", + "docs": "./dist/src/migrations/update-20-8-0/set-inject-document-domain.md" }, "remove-experimental-fetch-polyfill": { "cli": "nx", @@ -16,7 +17,8 @@ "cypress": ">=14.0.0" }, "description": "Removes the `experimentalFetchPolyfill` configuration option.", - "implementation": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill" + "implementation": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill", + "docs": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill.md" }, "replace-experimental-just-in-time-compile": { "cli": "nx", @@ -25,7 +27,8 @@ "cypress": ">=14.0.0" }, "description": "Replaces the `experimentalJustInTimeCompile` configuration option with the new `justInTimeCompile` configuration option.", - "implementation": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile" + "implementation": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile", + "docs": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile.md" }, "update-component-testing-mount-imports": { "cli": "nx", @@ -34,12 +37,14 @@ "cypress": ">=14.0.0" }, "description": "Updates the module specifier for the Component Testing `mount` function.", - "implementation": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports" + "implementation": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports", + "docs": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports.md" }, "remove-tsconfig-and-copy-files-options-from-cypress-executor": { "version": "21.0.0-beta.10", "description": "Removes the `tsConfig` and `copyFiles` options from the `@nx/cypress:cypress` executor.", - "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor" + "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor", + "docs": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor.md" }, "rename-cy-exec-code-property": { "version": "22.1.0-beta.6", @@ -47,7 +52,8 @@ "cypress": ">=15.0.0" }, "description": "Renames `cy.exec().its('code')` usages to the new `exitCode` property introduced in Cypress v15.", - "implementation": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property" + "implementation": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property", + "docs": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property.md" }, "update-selector-playground-api": { "version": "22.1.0-beta.6", @@ -55,7 +61,8 @@ "cypress": ">=15.0.0" }, "description": "Updates the deprecated `Cypress.SelectorPlayground` API to `Cypress.ElementSelector` and removes the unsupported `onElement` option.", - "implementation": "./dist/src/migrations/update-22-1-0/update-selector-playground-api" + "implementation": "./dist/src/migrations/update-22-1-0/update-selector-playground-api", + "docs": "./dist/src/migrations/update-22-1-0/update-selector-playground-api.md" }, "update-angular-component-testing-support": { "version": "22.1.0-beta.6", @@ -63,7 +70,8 @@ "cypress": ">=15.0.0" }, "description": "For Angular component testing projects below v18, switches to the fallback `@cypress/angular` harness required by Cypress v15.", - "implementation": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support" + "implementation": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support", + "docs": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support.md" }, "remove-experimental-prompt-command": { "version": "23.0.0-beta.10", @@ -71,7 +79,8 @@ "cypress": ">=15.13.0" }, "description": "Removes the `experimentalPromptCommand` flag from `cypress.config.{ts,js,mjs,cjs}`. The flag was removed in Cypress 15.13.0; `cy.prompt` is now in beta without configuration.", - "implementation": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command" + "implementation": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command", + "docs": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command.md" }, "rewrite-internal-subpath-imports": { "version": "23.0.0-beta.19", diff --git a/packages/devkit/migrations.json b/packages/devkit/migrations.json index 90740997ee3..b8508d20233 100644 --- a/packages/devkit/migrations.json +++ b/packages/devkit/migrations.json @@ -3,7 +3,8 @@ "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" + "implementation": "./dist/src/migrations/update-23-0-0/update-deep-imports", + "docs": "./dist/src/migrations/update-23-0-0/update-deep-imports.md" } }, "packageJsonUpdates": {}, diff --git a/packages/eslint/migrations.json b/packages/eslint/migrations.json index 189d130601f..314ffe50675 100644 --- a/packages/eslint/migrations.json +++ b/packages/eslint/migrations.json @@ -6,7 +6,8 @@ "implementation": "./dist/src/migrations/update-20-2-0/update-typescript-eslint-v8-13-0", "requires": { "@typescript-eslint/parser": ">=8.0.0" - } + }, + "docs": "./dist/src/migrations/update-20-2-0/update-typescript-eslint-v8-13-0.md" }, "add-file-extensions-to-overrides": { "version": "20.3.0-beta.1", @@ -14,7 +15,8 @@ "implementation": "./dist/src/migrations/update-20-3-0/add-file-extensions-to-overrides", "requires": { "eslint": ">=8.57.0" - } + }, + "docs": "./dist/src/migrations/update-20-3-0/add-file-extensions-to-overrides.md" }, "update-executor-lint-inputs": { "version": "22.7.0-beta.12", diff --git a/packages/gradle/assets.json b/packages/gradle/assets.json index 1e8e095814a..402691f14e3 100644 --- a/packages/gradle/assets.json +++ b/packages/gradle/assets.json @@ -8,6 +8,7 @@ { "glob": "migrations.json" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, { "glob": "**/*.jar", "input": "packages/gradle/batch-runner", diff --git a/packages/gradle/migrations.json b/packages/gradle/migrations.json index 515a188111d..bfb8624a1c3 100644 --- a/packages/gradle/migrations.json +++ b/packages/gradle/migrations.json @@ -4,139 +4,162 @@ "version": "20.2.0-beta.4", "cli": "nx", "description": "Add includeSubprojectsTasks to build.gradle file", - "factory": "./src/migrations/20-2-0/add-include-subprojects-tasks" + "factory": "./src/migrations/20-2-0/add-include-subprojects-tasks", + "docs": "./src/migrations/20-2-0/add-include-subprojects-tasks.md" }, "change-plugin-to-v1": { "version": "21.0.0-beta.5", "cli": "nx", "description": "Change @nx/gradle plugin to version 1", - "factory": "./src/migrations/21-0-0/change-plugin-to-v1" + "factory": "./src/migrations/21-0-0/change-plugin-to-v1", + "docs": "./src/migrations/21-0-0/change-plugin-to-v1.md" }, "change-ciTargetName-to-ciTestTargetName": { "version": "21.0.0-beta.13", "cli": "nx", "description": "Change @nx/gradle option from ciTargetName to ciTestTargetName", - "factory": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName" + "factory": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName", + "docs": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.md" }, "change-plugin-version-0-1-0": { "version": "21.1.2-beta.1", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.0 in build file", - "factory": "./src/migrations/21-1-2/change-plugin-version-0-1-0" + "factory": "./src/migrations/21-1-2/change-plugin-version-0-1-0", + "docs": "./src/migrations/21-1-2/change-plugin-version-0-1-0.md" }, "change-plugin-version-0-1-2": { "version": "21.3.0-beta.0", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.2 in build file", - "factory": "./src/migrations/21-3-0/change-plugin-version-0-1-2" + "factory": "./src/migrations/21-3-0/change-plugin-version-0-1-2", + "docs": "./src/migrations/21-3-0/change-plugin-version-0-1-2.md" }, "change-plugin-version-0-1-4": { "version": "21.3.11-beta.0", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.4 in build file", - "factory": "./src/migrations/21-3-11/change-plugin-version-0-1-4" + "factory": "./src/migrations/21-3-11/change-plugin-version-0-1-4", + "docs": "./src/migrations/21-3-11/change-plugin-version-0-1-4.md" }, "change-plugin-version-0-1-5": { "version": "21.4.0-beta.12", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.5 in build file", - "factory": "./src/migrations/21-4-0/change-plugin-version-0-1-5" + "factory": "./src/migrations/21-4-0/change-plugin-version-0-1-5", + "docs": "./src/migrations/21-4-0/change-plugin-version-0-1-5.md" }, "change-plugin-version-0-1-6": { "version": "21.4.1-beta.1", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.6 in build file", - "factory": "./src/migrations/21-4-1/change-plugin-version-0-1-6" + "factory": "./src/migrations/21-4-1/change-plugin-version-0-1-6", + "docs": "./src/migrations/21-4-1/change-plugin-version-0-1-6.md" }, "change-plugin-version-0-1-7": { "version": "21.5.1-beta.5", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.7 in build file", - "factory": "./src/migrations/21-5-1/change-plugin-version-0-1-7" + "factory": "./src/migrations/21-5-1/change-plugin-version-0-1-7", + "docs": "./src/migrations/21-5-1/change-plugin-version-0-1-7.md" }, "change-plugin-version-0-1-8": { "version": "21.6.1-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.8 in build file", - "factory": "./src/migrations/21-6-1/change-plugin-version-0-1-8" + "factory": "./src/migrations/21-6-1/change-plugin-version-0-1-8", + "docs": "./src/migrations/21-6-1/change-plugin-version-0-1-8.md" }, "change-plugin-version-0-1-9": { "version": "22.1.0-rc.3", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.9 in build file", - "factory": "./src/migrations/22-1-0/change-plugin-version-0-1-9" + "factory": "./src/migrations/22-1-0/change-plugin-version-0-1-9", + "docs": "./src/migrations/22-1-0/change-plugin-version-0-1-9.md" }, "change-plugin-version-0-1-10": { "version": "22.2.0-beta.4", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.10 in build file", - "factory": "./src/migrations/22-2-0/change-plugin-version-0-1-10" + "factory": "./src/migrations/22-2-0/change-plugin-version-0-1-10", + "docs": "./src/migrations/22-2-0/change-plugin-version-0-1-10.md" }, "change-plugin-version-0-1-11": { "version": "22.4.0-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.11 in build file", - "factory": "./src/migrations/22-3-0/change-plugin-version-0-1-11" + "factory": "./src/migrations/22-3-0/change-plugin-version-0-1-11", + "docs": "./src/migrations/22-3-0/change-plugin-version-0-1-11.md" }, "change-plugin-version-0-1-12": { "version": "22.5.0-beta.5", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.12 in build file", - "factory": "./src/migrations/22-5-0/change-plugin-version-0-1-12" + "factory": "./src/migrations/22-5-0/change-plugin-version-0-1-12", + "docs": "./src/migrations/22-5-0/change-plugin-version-0-1-12.md" }, "change-plugin-version-0-1-13": { "version": "22.5.3", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.13 in build file", - "factory": "./src/migrations/22-5-3/change-plugin-version-0-1-13" + "factory": "./src/migrations/22-5-3/change-plugin-version-0-1-13", + "docs": "./src/migrations/22-5-3/change-plugin-version-0-1-13.md" }, "change-plugin-version-0-1-14": { "version": "22.6.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.14 in build file", - "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-14" + "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-14", + "docs": "./src/migrations/22-6-0/change-plugin-version-0-1-14.md" }, "change-plugin-version-0-1-15": { "version": "22.6.0-beta.13", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.15 in build file", - "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-15" + "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-15", + "docs": "./src/migrations/22-6-0/change-plugin-version-0-1-15.md" }, "change-plugin-version-0-1-16": { "version": "22.7.0-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.16 in build file", - "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-16" + "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-16", + "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-16.md" }, "change-plugin-version-0-1-17": { "version": "22.7.0-beta.4", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.17 in build file", - "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-17" + "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-17", + "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-17.md" }, "change-plugin-version-0-1-18": { "version": "22.7.0-beta.9", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.18 in build file", - "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-18" + "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-18", + "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-18.md" }, "change-plugin-version-0-1-19": { "version": "22.7.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.19 in build file", - "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-19" + "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-19", + "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-19.md" }, "change-plugin-version-0-1-20": { "version": "22.7.0-beta.16", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.20 in build file", - "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-20" + "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-20", + "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-20.md" }, "change-plugin-version-0-1-21": { "version": "23.0.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.21 in build file", - "factory": "./src/migrations/23-0-0/change-plugin-version-0-1-21" + "factory": "./src/migrations/23-0-0/change-plugin-version-0-1-21", + "docs": "./src/migrations/23-0-0/change-plugin-version-0-1-21.md" } }, "packageJsonUpdates": {} diff --git a/packages/jest/migrations.json b/packages/jest/migrations.json index 4a71ff6af5f..444996f6244 100644 --- a/packages/jest/migrations.json +++ b/packages/jest/migrations.json @@ -4,23 +4,27 @@ "cli": "nx", "version": "20.0.0-beta.5", "description": "Replace usage of `getJestProjects` with `getJestProjectsAsync`.", - "implementation": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync" + "implementation": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync", + "docs": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" }, "replace-getJestProjects-with-getJestProjectsAsync-v21": { "cli": "nx", "version": "21.0.0-beta.9", "description": "Replace usage of `getJestProjects` with `getJestProjectsAsync`.", - "implementation": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync" + "implementation": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync", + "docs": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" }, "remove-tsconfig-option-from-jest-executor": { "version": "21.0.0-beta.10", "description": "Remove the previously deprecated and unused `tsConfig` option from the `@nx/jest:jest` executor.", - "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor" + "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor", + "docs": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor.md" }, "rename-test-path-pattern": { "version": "21.3.0-beta.3", "description": "Rename the CLI option `testPathPattern` to `testPathPatterns`.", - "implementation": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern" + "implementation": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern", + "docs": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern.md" }, "replace-removed-matcher-aliases": { "version": "21.3.0-beta.3", @@ -28,12 +32,14 @@ "jest": ">=30.0.0" }, "description": "Replace removed matcher aliases in Jest v30 with their corresponding matcher", - "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases" + "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases", + "docs": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" }, "convert-jest-config-to-cjs": { "version": "22.2.0-beta.2", "description": "Convert jest.config.ts files from ESM to CJS syntax (export default -> module.exports, import -> require) for projects using CommonJS resolution to ensure correct loading under Node.js type-stripping.", - "implementation": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs" + "implementation": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs", + "docs": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs.md" }, "replace-removed-matcher-aliases-v22-3": { "version": "22.3.2-beta.0", @@ -41,7 +47,8 @@ "jest": ">=30.0.0" }, "description": "Replace removed matcher aliases in Jest v30 with their corresponding matcher", - "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases" + "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases", + "docs": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" }, "update-snapshot-guide-link": { "version": "23.0.0-beta.10", @@ -49,7 +56,8 @@ "jest": ">=30.0.0" }, "description": "Update the Jest snapshot guide link in `.snap` files from the legacy `https://goo.gl/fbAQLP` URL to `https://jestjs.io/docs/snapshot-testing`, which Jest v30 now requires.", - "implementation": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link" + "implementation": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link", + "docs": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link.md" }, "rewrite-jest-internal-subpath-imports": { "version": "23.0.0-beta.16", diff --git a/packages/js/migrations.json b/packages/js/migrations.json index 5ca1827cf20..0e5e56ff929 100644 --- a/packages/js/migrations.json +++ b/packages/js/migrations.json @@ -3,17 +3,20 @@ "migrate-development-custom-condition": { "version": "21.5.0-beta.2", "description": "Migrate the legacy 'development' custom condition to a workspace-unique custom condition name.", - "factory": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition" + "factory": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition", + "docs": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition.md" }, "remove-external-options-from-js-executors": { "version": "22.0.0-beta.0", "description": "Remove the deprecated `external` and `externalBuildTargets` options from the `@nx/js:swc` and `@nx/js:tsc` executors.", - "factory": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors" + "factory": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors", + "docs": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors.md" }, "remove-redundant-ts-project-references": { "version": "22.1.0-rc.1", "description": "Removes redundant TypeScript project references from project's tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist.", - "factory": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references" + "factory": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references", + "docs": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references.md" }, "23-0-0-rewrite-internal-subpath-imports": { "version": "23.0.0-beta.14", diff --git a/packages/nx/migrations.json b/packages/nx/migrations.json index 39ccf267a8a..433584b0180 100644 --- a/packages/nx/migrations.json +++ b/packages/nx/migrations.json @@ -41,7 +41,8 @@ "cli": "nx", "version": "17.0.0-beta.1", "description": "Updates the default cache directory to .nx/cache", - "implementation": "./dist/src/migrations/update-17-0-0/move-cache-directory" + "implementation": "./dist/src/migrations/update-17-0-0/move-cache-directory", + "docs": "./dist/src/migrations/update-17-0-0/move-cache-directory.md" }, "17.0.0-use-minimal-config-for-tasks-runner-options": { "cli": "nx", @@ -93,33 +94,39 @@ "move-use-daemon-process": { "version": "20.0.0-beta.7", "description": "Migration for v20.0.0-beta.7", - "implementation": "./dist/src/migrations/update-20-0-0/move-use-daemon-process" + "implementation": "./dist/src/migrations/update-20-0-0/move-use-daemon-process", + "docs": "./dist/src/migrations/update-20-0-0/move-use-daemon-process.md" }, "use-legacy-cache": { "version": "20.0.1", "description": "Set `useLegacyCache` to true for migrating workspaces", "implementation": "./dist/src/migrations/update-20-0-1/use-legacy-cache", - "x-repair-skip": true + "x-repair-skip": true, + "docs": "./dist/src/migrations/update-20-0-1/use-legacy-cache.md" }, "remove-legacy-cache": { "version": "21.0.0-beta.8", "description": "Removes the legacy cache configuration from nx.json", - "implementation": "./dist/src/migrations/update-21-0-0/remove-legacy-cache" + "implementation": "./dist/src/migrations/update-21-0-0/remove-legacy-cache", + "docs": "./dist/src/migrations/update-21-0-0/remove-legacy-cache.md" }, "remove-custom-tasks-runner": { "version": "21.0.0-beta.8", "description": "Removes the legacy cache configuration from nx.json", - "implementation": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner" + "implementation": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner", + "docs": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner.md" }, "release-version-config-changes": { "version": "21.0.0-beta.11", "description": "Updates release version config based on the breaking changes in Nx v21", - "implementation": "./dist/src/migrations/update-21-0-0/release-version-config-changes" + "implementation": "./dist/src/migrations/update-21-0-0/release-version-config-changes", + "docs": "./dist/src/migrations/update-21-0-0/release-version-config-changes.md" }, "release-changelog-config-changes": { "version": "21.0.0-beta.11", "description": "Updates release changelog config based on the breaking changes in Nx v21", - "implementation": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes" + "implementation": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes", + "docs": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes.md" }, "22-0-0-release-version-config-changes": { "version": "22.0.0-beta.1", @@ -159,7 +166,8 @@ "cli": "nx", "version": "22.7.0-beta.0", "description": "Adds .nx/self-healing to .gitignore", - "implementation": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore" + "implementation": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore", + "docs": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore.md" }, "23-0-0-consolidate-release-tag-config": { "version": "23.0.0-beta.16", @@ -170,7 +178,8 @@ "cli": "nx", "version": "23.0.0-beta.13", "description": "Converts nx.json `targetDefaults` from the legacy record shape to the new filtered array shape.", - "implementation": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array" + "implementation": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array", + "docs": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array.md" }, "23-0-0-add-migrate-runs-to-git-ignore": { "version": "23.0.0-beta.18", diff --git a/packages/react/assets.json b/packages/react/assets.json index 83799c0979f..b2830067456 100644 --- a/packages/react/assets.json +++ b/packages/react/assets.json @@ -6,6 +6,7 @@ { "glob": "@(package|executors|generators|migrations).json" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, { "glob": "typings/**/*.d.ts" }, "LICENSE" ] diff --git a/packages/react/migrations.json b/packages/react/migrations.json index 3bc91c3facb..fd6b0b7ef7f 100644 --- a/packages/react/migrations.json +++ b/packages/react/migrations.json @@ -4,31 +4,36 @@ "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the ModuleFederationConfig import use @nx/module-federation.", - "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package" + "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package", + "docs": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" }, "update-20-2-0-update-with-module-federation-import": { "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the withModuleFederation import use @nx/module-federation/webpack.", - "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package" + "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", + "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", - "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package" + "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", + "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "add-mf-env-var-to-target-defaults": { "cli": "nx", "version": "20.4.0-beta.0", "description": "Add NX_MF_DEV_REMOTES to inputs for task hashing when '@nx/webpack:webpack' or '@nx/rspack:rspack' is used for Module Federation.", - "factory": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults" + "factory": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults", + "docs": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults.md" }, "update-21-0-0-update-babel-loose": { "cli": "nx", "version": "21.0.0-beta.11", "description": "Replaces `classProperties.loose` option with `loose`.", - "factory": "./src/migrations/update-21-0-0/update-babel-loose" + "factory": "./src/migrations/update-21-0-0/update-babel-loose", + "docs": "./src/migrations/update-21-0-0/update-babel-loose.md" }, "update-22-0-0-add-svgr-to-webpack-config": { "cli": "nx", @@ -40,7 +45,8 @@ "cli": "nx", "version": "23.0.0-beta.10", "description": "Rewrites imports of NxReactWebpackPlugin from '@nx/react' to the sub-path '@nx/react/webpack-plugin'.", - "factory": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import" + "factory": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import", + "docs": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import.md" } }, "packageJsonUpdates": { diff --git a/packages/rollup/assets.json b/packages/rollup/assets.json index aa39269f2ad..7654cbf83ff 100644 --- a/packages/rollup/assets.json +++ b/packages/rollup/assets.json @@ -6,6 +6,7 @@ { "glob": "@(package|executors|generators|migrations).json" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, { "glob": "src/plugins/postcss/types/concat-with-sourcemaps.d.ts" }, "LICENSE" ] diff --git a/packages/rollup/migrations.json b/packages/rollup/migrations.json index 07606c17e05..2602b7f5e8f 100644 --- a/packages/rollup/migrations.json +++ b/packages/rollup/migrations.json @@ -4,7 +4,8 @@ "cli": "nx", "version": "23.0.0-beta.4", "description": "Remove deprecated useLegacyTypescriptPlugin option from @nx/rollup:rollup", - "implementation": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin" + "implementation": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin", + "docs": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin.md" } }, "packageJsonUpdates": {} diff --git a/packages/rspack/migrations.json b/packages/rspack/migrations.json index 0aa166d6d8a..8d188f5029c 100644 --- a/packages/rspack/migrations.json +++ b/packages/rspack/migrations.json @@ -4,13 +4,15 @@ "cli": "nx", "version": "20.2.0-beta.3", "description": "Update the withModuleFederation import use @nx/module-federation/rspack.", - "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package" + "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", + "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", - "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package" + "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", + "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "remove-deprecated-rspack-options": { "cli": "nx", @@ -22,7 +24,8 @@ "cli": "nx", "version": "23.0.0-beta.9", "description": "Updates rspack configs using React to use the new withSvgr composable function instead of the svgr option in withReact or NxReactRspackPlugin.", - "factory": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config" + "factory": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config", + "docs": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config.md" } }, "packageJsonUpdates": { diff --git a/packages/vite/migrations.json b/packages/vite/migrations.json index 819bf0336da..ef45258742b 100644 --- a/packages/vite/migrations.json +++ b/packages/vite/migrations.json @@ -3,27 +3,32 @@ "update-20-0-4": { "version": "20.0.4-beta.0", "description": "Add gitignore entry for temporary vite config files.", - "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore" + "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore", + "docs": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" }, "update-20-0-6": { "version": "20.0.6-beta.0", "description": "Add gitignore entry for temporary vite config files and remove previous incorrect glob.", - "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore" + "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore", + "docs": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" }, "update-20-5-0-install-jiti": { "version": "20.5.0-beta.2", "description": "Install jiti as a devDependency to allow vite to parse TS postcss files.", - "implementation": "./dist/src/migrations/update-20-5-0/install-jiti" + "implementation": "./dist/src/migrations/update-20-5-0/install-jiti", + "docs": "./dist/src/migrations/update-20-5-0/install-jiti.md" }, "update-20-5-0-update-resolve-conditions": { "version": "20.5.0-beta.3", "description": "Update resolve.conditions to include defaults that are no longer provided by Vite.", - "implementation": "./dist/src/migrations/update-20-5-0/update-resolve-conditions" + "implementation": "./dist/src/migrations/update-20-5-0/update-resolve-conditions", + "docs": "./dist/src/migrations/update-20-5-0/update-resolve-conditions.md" }, "eslint-ignore-vite-temp-files": { "version": "20.5.0-beta.3", "description": "Add vite config temporary files to the ESLint configuration ignore patterns if ESLint is used.", - "implementation": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files" + "implementation": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files", + "docs": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files.md" }, "update-22-2-0": { "version": "22.2.0-beta.1", @@ -41,7 +46,8 @@ "ensure-vitest-package-migration-23": { "version": "23.0.0-beta.10", "description": "Safety net: ensure any remaining @nx/vite:test executor usages are swapped to @nx/vitest:test and @nx/vitest is installed.", - "implementation": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration" + "implementation": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration", + "docs": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration.md" }, "rename-rollup-options-to-rolldown-options": { "version": "23.0.0-beta.10", @@ -49,7 +55,8 @@ "vite": ">=8.0.0" }, "description": "Rename `rollupOptions` to `rolldownOptions` in vite config files (top-level and inside `environments`). Vite 8 replaced Rollup with Rolldown.", - "implementation": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options" + "implementation": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options", + "docs": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options.md" }, "create-ai-instructions-for-vite-8": { "version": "23.0.0-beta.10", diff --git a/packages/vitest/migrations.json b/packages/vitest/migrations.json index 5fe664065c3..e174769cc03 100644 --- a/packages/vitest/migrations.json +++ b/packages/vitest/migrations.json @@ -3,7 +3,8 @@ "update-20-3-0": { "version": "20.3.0-beta.2", "description": "Add gitignore entry for temporary vitest config files.", - "implementation": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore" + "implementation": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore", + "docs": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore.md" }, "update-22-1-0": { "version": "22.1.0-beta.8", @@ -21,7 +22,8 @@ "update-22-6-0-prefix-reports-directory": { "version": "22.6.0-beta.11", "description": "Prefix reportsDirectory with {projectRoot} to maintain correct resolution after workspace-root-relative behavior change.", - "implementation": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root" + "implementation": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root", + "docs": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root.md" } }, "packageJsonUpdates": { diff --git a/packages/webpack/assets.json b/packages/webpack/assets.json index 39fd9cb360a..db9a7b64342 100644 --- a/packages/webpack/assets.json +++ b/packages/webpack/assets.json @@ -6,6 +6,7 @@ { "glob": "@(package|executors|generators|migrations).json" }, { "glob": "src/**/schema.json" }, { "glob": "src/**/schema.d.ts" }, + { "glob": "src/migrations/**/*.md" }, { "glob": "src/utils/webpack/deprecated-less-loader.js" }, "LICENSE" ] diff --git a/packages/webpack/migrations.json b/packages/webpack/migrations.json index b4a20a2433c..d9ec8adffc0 100644 --- a/packages/webpack/migrations.json +++ b/packages/webpack/migrations.json @@ -4,7 +4,8 @@ "cli": "nx", "version": "21.0.0-beta.11", "description": "Remove isolatedConfig option for @nx/webpack:webpack", - "implementation": "./src/migrations/update-21-0-0/remove-isolated-config" + "implementation": "./src/migrations/update-21-0-0/remove-isolated-config", + "docs": "./src/migrations/update-21-0-0/remove-isolated-config.md" }, "update-22-0-0-remove-deprecated-options": { "cli": "nx", @@ -16,7 +17,8 @@ "cli": "nx", "version": "23.0.0-beta.10", "description": "Rewrites imports of NxTsconfigPathsWebpackPlugin from '@nx/webpack' to the sub-path '@nx/webpack/tsconfig-paths-plugin'.", - "factory": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import" + "factory": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import", + "docs": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import.md" } }, "packageJsonUpdates": { From b401e4f2cf362477d8b1d7705b6bedd45fc1121e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leosvel=20P=C3=A9rez=20Espinosa?= Date: Tue, 2 Jun 2026 16:49:35 +0200 Subject: [PATCH 3/4] cleanup(core): rename migration docs field to documentation and resolve it from the collection - rename the migration entry `docs` field to `documentation` across the config interface, the agentic prompt plumbing (XML tag included), and every migrations.json entry - resolve a migration's `documentation` once from its collection - the same read used for the implementation - instead of re-reading the package config separately - validate `documentation` paths in the per-package migration specs, and add the missing rspack migrations spec - correct the resolved-path JSDoc to note the path can be absolute when the file resolves outside the workspace --- packages/angular/migrations.json | 62 +++--- packages/cypress/migrations.json | 18 +- packages/devkit/migrations.json | 2 +- packages/eslint/migrations.json | 4 +- packages/gradle/migrations.json | 46 ++--- packages/jest/migrations.json | 16 +- packages/js/migrations.json | 6 +- packages/nx/migrations.json | 18 +- .../prompts/generic-validation.spec.ts | 17 +- .../agentic/prompts/generic-validation.ts | 11 +- .../prompts/hybrid-prompt-migration.spec.ts | 17 +- .../prompts/hybrid-prompt-migration.ts | 11 +- .../agentic/prompts/prompt-migration.spec.ts | 12 +- .../agentic/prompts/prompt-migration.ts | 11 +- .../agentic/prompts/shared-rendering.spec.ts | 20 +- .../agentic/prompts/shared-rendering.ts | 19 +- .../command-line/migrate/agentic/run-step.ts | 15 +- .../src/command-line/migrate/migrate.spec.ts | 191 +++++++++++++++--- .../nx/src/command-line/migrate/migrate.ts | 144 ++++++++----- packages/nx/src/config/misc-interfaces.ts | 3 +- .../assert-valid-migrations.ts | 12 ++ packages/react/migrations.json | 12 +- packages/rollup/migrations.json | 2 +- packages/rspack/migrations.json | 6 +- packages/rspack/migrations.spec.ts | 8 + packages/vite/migrations.json | 14 +- packages/vitest/migrations.json | 4 +- packages/webpack/migrations.json | 4 +- 28 files changed, 463 insertions(+), 242 deletions(-) create mode 100644 packages/rspack/migrations.spec.ts diff --git a/packages/angular/migrations.json b/packages/angular/migrations.json index c8c2b5aa2e5..fcd5f13e126 100644 --- a/packages/angular/migrations.json +++ b/packages/angular/migrations.json @@ -44,14 +44,14 @@ "version": "20.2.0-beta.2", "description": "Update the ModuleFederationConfig import use @nx/module-federation.", "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package", - "docs": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" + "documentation": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" }, "update-20-2-0-update-with-module-federation-import": { "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the withModuleFederation import use @nx/module-federation/angular.", "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", - "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" + "documentation": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "update-angular-cli-version-19-0-0": { "cli": "nx", @@ -61,7 +61,7 @@ }, "description": "Update the @angular/cli package version to ~19.0.0.", "factory": "./src/migrations/update-20-2-0/update-angular-cli", - "docs": "./src/migrations/update-20-2-0/update-angular-cli.md" + "documentation": "./src/migrations/update-20-2-0/update-angular-cli.md" }, "add-localize-polyfill-to-targets": { "cli": "nx", @@ -71,7 +71,7 @@ }, "description": "Add the '@angular/localize/init' polyfill to the 'polyfills' option of targets using esbuild-based executors.", "factory": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets", - "docs": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets.md" + "documentation": "./src/migrations/update-20-2-0/add-localize-polyfill-to-targets.md" }, "update-angular-ssr-imports-to-use-node-entry-point": { "cli": "nx", @@ -81,7 +81,7 @@ }, "description": "Update '@angular/ssr' import paths to use the new '/node' entry point when 'CommonEngine' is detected.", "factory": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point", - "docs": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point.md" + "documentation": "./src/migrations/update-20-2-0/update-angular-ssr-imports-to-use-node-entry-point.md" }, "disable-angular-eslint-prefer-standalone": { "cli": "nx", @@ -91,7 +91,7 @@ }, "description": "Disable the Angular ESLint prefer-standalone rule if not set.", "factory": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone", - "docs": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone.md" + "documentation": "./src/migrations/update-20-2-0/disable-angular-eslint-prefer-standalone.md" }, "remove-angular-eslint-rules": { "cli": "nx", @@ -101,7 +101,7 @@ }, "description": "Remove Angular ESLint rules that were removed in v19.0.0.", "factory": "./src/migrations/update-20-2-0/remove-angular-eslint-rules", - "docs": "./src/migrations/update-20-2-0/remove-angular-eslint-rules.md" + "documentation": "./src/migrations/update-20-2-0/remove-angular-eslint-rules.md" }, "remove-tailwind-config-from-ng-packagr-executors": { "cli": "nx", @@ -111,14 +111,14 @@ }, "description": "Remove the deprecated 'tailwindConfig' option from ng-packagr executors. Tailwind CSS configurations located at the project or workspace root will be picked up automatically.", "factory": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors", - "docs": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors.md" + "documentation": "./src/migrations/update-20-2-0/remove-tailwind-config-from-ng-packagr-executors.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", - "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" + "documentation": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "update-angular-cli-version-19-1-0": { "cli": "nx", @@ -128,7 +128,7 @@ }, "description": "Update the @angular/cli package version to ~19.1.0.", "factory": "./src/migrations/update-20-4-0/update-angular-cli", - "docs": "./src/migrations/update-20-4-0/update-angular-cli.md" + "documentation": "./src/migrations/update-20-4-0/update-angular-cli.md" }, "update-angular-cli-version-19-2-0": { "cli": "nx", @@ -138,14 +138,14 @@ }, "description": "Update the @angular/cli package version to ~19.2.0.", "factory": "./src/migrations/update-20-5-0/update-angular-cli", - "docs": "./src/migrations/update-20-5-0/update-angular-cli.md" + "documentation": "./src/migrations/update-20-5-0/update-angular-cli.md" }, "set-continuous-option": { "cli": "nx", "version": "21.0.0-beta.3", "description": "Set the `continuous` option to `true` for continuous tasks.", "factory": "./src/migrations/update-21-0-0/set-continuous-option", - "docs": "./src/migrations/update-21-0-0/set-continuous-option.md" + "documentation": "./src/migrations/update-21-0-0/set-continuous-option.md" }, "change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence": { "cli": "nx", @@ -155,7 +155,7 @@ }, "description": "Change the data persistence operator imports to '@ngrx/router-store/data-persistence'.", "factory": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence", - "docs": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence.md" + "documentation": "./src/migrations/update-21-0-0/change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence.md" }, "update-angular-cli-version-20-0-0": { "cli": "nx", @@ -165,7 +165,7 @@ }, "description": "Update the @angular/cli package version to ~20.0.0.", "factory": "./src/migrations/update-21-2-0/update-angular-cli", - "docs": "./src/migrations/update-21-2-0/update-angular-cli.md" + "documentation": "./src/migrations/update-21-2-0/update-angular-cli.md" }, "migrate-provide-server-rendering-import": { "version": "21.2.0-beta.3", @@ -174,7 +174,7 @@ }, "description": "Migrate imports of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`.", "factory": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import", - "docs": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import.md" + "documentation": "./src/migrations/update-21-2-0/migrate-provide-server-rendering-import.md" }, "replace-provide-server-routing": { "version": "21.2.0-beta.3", @@ -183,7 +183,7 @@ }, "description": "Replace `provideServerRouting` and `provideServerRoutesConfig` with `provideServerRendering` using `withRoutes`.", "factory": "./src/migrations/update-21-2-0/replace-provide-server-routing", - "docs": "./src/migrations/update-21-2-0/replace-provide-server-routing.md" + "documentation": "./src/migrations/update-21-2-0/replace-provide-server-routing.md" }, "set-generator-defaults-for-previous-style-guide": { "version": "21.2.0-beta.3", @@ -192,7 +192,7 @@ }, "description": "Update the generator defaults to maintain the previous style guide behavior.", "factory": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide", - "docs": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide.md" + "documentation": "./src/migrations/update-21-2-0/set-generator-defaults-for-previous-style-guide.md" }, "update-module-resolution": { "version": "21.2.0-beta.3", @@ -201,7 +201,7 @@ }, "description": "Update 'moduleResolution' to 'bundler' in TypeScript configurations. You can read more about this here: https://www.typescriptlang.org/tsconfig/#moduleResolution.", "factory": "./src/migrations/update-21-2-0/update-module-resolution", - "docs": "./src/migrations/update-21-2-0/update-module-resolution.md" + "documentation": "./src/migrations/update-21-2-0/update-module-resolution.md" }, "update-angular-cli-version-20-1-0": { "cli": "nx", @@ -211,13 +211,13 @@ }, "description": "Update the @angular/cli package version to ~20.1.0.", "factory": "./src/migrations/update-21-3-0/update-angular-cli", - "docs": "./src/migrations/update-21-3-0/update-angular-cli.md" + "documentation": "./src/migrations/update-21-3-0/update-angular-cli.md" }, "set-tsconfig-option": { "version": "21.5.0-beta.0", "description": "Set the 'tsConfig' option to build and test targets to help with Angular migration issues.", "factory": "./src/migrations/update-21-5-0/set-tsconfig-option", - "docs": "./src/migrations/update-21-5-0/set-tsconfig-option.md" + "documentation": "./src/migrations/update-21-5-0/set-tsconfig-option.md" }, "update-angular-cli-version-20-2-0": { "cli": "nx", @@ -227,7 +227,7 @@ }, "description": "Update the @angular/cli package version to ~20.2.0.", "factory": "./src/migrations/update-21-5-0/update-angular-cli", - "docs": "./src/migrations/update-21-5-0/update-angular-cli.md" + "documentation": "./src/migrations/update-21-5-0/update-angular-cli.md" }, "remove-default-karma-configuration-files": { "version": "21.5.0-beta.2", @@ -236,7 +236,7 @@ }, "description": "Remove any Karma configuration files that only contain the default content. The default configuration is automatically available without a specific project configurationfile.", "factory": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files", - "docs": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files.md" + "documentation": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files.md" }, "update-angular-cli-version-20-3-0": { "cli": "nx", @@ -246,7 +246,7 @@ }, "description": "Update the @angular/cli package version to ~20.3.0.", "factory": "./src/migrations/update-21-6-1/update-angular-cli", - "docs": "./src/migrations/update-21-6-1/update-angular-cli.md" + "documentation": "./src/migrations/update-21-6-1/update-angular-cli.md" }, "update-ssr-webpack-config-22-2-0": { "version": "22.3.0-beta.0", @@ -255,7 +255,7 @@ }, "description": "Updates webpack-based SSR configuration to use preserve module format and bundler module resolution.", "factory": "./src/migrations/update-22-3-0/update-ssr-webpack-config", - "docs": "./src/migrations/update-22-3-0/update-ssr-webpack-config.md" + "documentation": "./src/migrations/update-22-3-0/update-ssr-webpack-config.md" }, "update-module-resolution-22-2-0": { "version": "22.3.0-beta.0", @@ -264,7 +264,7 @@ }, "description": "Update 'module' to 'preserve' and 'moduleResolution' to 'bundler' in TypeScript configurations for Angular projects.", "factory": "./src/migrations/update-22-3-0/update-module-resolution", - "docs": "./src/migrations/update-22-3-0/update-module-resolution.md" + "documentation": "./src/migrations/update-22-3-0/update-module-resolution.md" }, "update-typescript-lib-22-2-0": { "version": "22.3.0-beta.0", @@ -273,13 +273,13 @@ }, "description": "Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version.", "factory": "./src/migrations/update-22-3-0/update-typescript-lib", - "docs": "./src/migrations/update-22-3-0/update-typescript-lib.md" + "documentation": "./src/migrations/update-22-3-0/update-typescript-lib.md" }, "update-unit-test-runner-option": { "version": "22.3.0-beta.0", "description": "Update 'vitest' unit test runner option to 'vitest-analog' in generator defaults.", "factory": "./src/migrations/update-22-3-0/update-unit-test-runner-option", - "docs": "./src/migrations/update-22-3-0/update-unit-test-runner-option.md" + "documentation": "./src/migrations/update-22-3-0/update-unit-test-runner-option.md" }, "set-isolated-modules-22-3-0": { "version": "22.3.0-beta.3", @@ -288,7 +288,7 @@ }, "description": "Set 'isolatedModules' to 'true' in TypeScript test configurations for Angular projects.", "factory": "./src/migrations/update-22-3-0/set-isolated-modules", - "docs": "./src/migrations/update-22-3-0/set-isolated-modules.md" + "documentation": "./src/migrations/update-22-3-0/set-isolated-modules.md" }, "update-jest-preset-angular-setup": { "version": "22.3.0-beta.3", @@ -297,19 +297,19 @@ }, "description": "Replace 'jest-preset-angular/setup-jest' imports with the new 'setupZoneTestEnv' function.", "factory": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup", - "docs": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup.md" + "documentation": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup.md" }, "update-23-0-0-update-with-module-federation-import": { "version": "23.0.0-beta.0", "description": "Update the @nx/angular/module-federation import to use @nx/module-federation/angular.", "factory": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package", - "docs": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package.md" + "documentation": "./src/migrations/update-23-0-0/migrate-with-mf-import-to-new-package.md" }, "update-23-0-0-migrate-ngrx-generator-defaults": { "version": "23.0.0-beta.7", "description": "Split @nx/angular:ngrx generator defaults in nx.json across the @nx/angular:ngrx-root-store and @nx/angular:ngrx-feature-store generators.", "factory": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults", - "docs": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults.md" + "documentation": "./src/migrations/update-23-0-0/migrate-ngrx-generator-defaults.md" } }, "packageJsonUpdates": { diff --git a/packages/cypress/migrations.json b/packages/cypress/migrations.json index 83de8761490..f7a8fd3ac91 100644 --- a/packages/cypress/migrations.json +++ b/packages/cypress/migrations.json @@ -8,7 +8,7 @@ }, "description": "Replaces the `experimentalSkipDomainInjection` configuration option with the new `injectDocumentDomain` configuration option.", "implementation": "./dist/src/migrations/update-20-8-0/set-inject-document-domain", - "docs": "./dist/src/migrations/update-20-8-0/set-inject-document-domain.md" + "documentation": "./dist/src/migrations/update-20-8-0/set-inject-document-domain.md" }, "remove-experimental-fetch-polyfill": { "cli": "nx", @@ -18,7 +18,7 @@ }, "description": "Removes the `experimentalFetchPolyfill` configuration option.", "implementation": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill", - "docs": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill.md" + "documentation": "./dist/src/migrations/update-20-8-0/remove-experimental-fetch-polyfill.md" }, "replace-experimental-just-in-time-compile": { "cli": "nx", @@ -28,7 +28,7 @@ }, "description": "Replaces the `experimentalJustInTimeCompile` configuration option with the new `justInTimeCompile` configuration option.", "implementation": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile", - "docs": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile.md" + "documentation": "./dist/src/migrations/update-20-8-0/replace-experimental-just-in-time-compile.md" }, "update-component-testing-mount-imports": { "cli": "nx", @@ -38,13 +38,13 @@ }, "description": "Updates the module specifier for the Component Testing `mount` function.", "implementation": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports", - "docs": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports.md" + "documentation": "./dist/src/migrations/update-20-8-0/update-component-testing-mount-imports.md" }, "remove-tsconfig-and-copy-files-options-from-cypress-executor": { "version": "21.0.0-beta.10", "description": "Removes the `tsConfig` and `copyFiles` options from the `@nx/cypress:cypress` executor.", "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor", - "docs": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor.md" + "documentation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-and-copy-files-options-from-cypress-executor.md" }, "rename-cy-exec-code-property": { "version": "22.1.0-beta.6", @@ -53,7 +53,7 @@ }, "description": "Renames `cy.exec().its('code')` usages to the new `exitCode` property introduced in Cypress v15.", "implementation": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property", - "docs": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property.md" + "documentation": "./dist/src/migrations/update-22-1-0/rename-cy-exec-code-property.md" }, "update-selector-playground-api": { "version": "22.1.0-beta.6", @@ -62,7 +62,7 @@ }, "description": "Updates the deprecated `Cypress.SelectorPlayground` API to `Cypress.ElementSelector` and removes the unsupported `onElement` option.", "implementation": "./dist/src/migrations/update-22-1-0/update-selector-playground-api", - "docs": "./dist/src/migrations/update-22-1-0/update-selector-playground-api.md" + "documentation": "./dist/src/migrations/update-22-1-0/update-selector-playground-api.md" }, "update-angular-component-testing-support": { "version": "22.1.0-beta.6", @@ -71,7 +71,7 @@ }, "description": "For Angular component testing projects below v18, switches to the fallback `@cypress/angular` harness required by Cypress v15.", "implementation": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support", - "docs": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support.md" + "documentation": "./dist/src/migrations/update-22-1-0/update-angular-component-testing-support.md" }, "remove-experimental-prompt-command": { "version": "23.0.0-beta.10", @@ -80,7 +80,7 @@ }, "description": "Removes the `experimentalPromptCommand` flag from `cypress.config.{ts,js,mjs,cjs}`. The flag was removed in Cypress 15.13.0; `cy.prompt` is now in beta without configuration.", "implementation": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command", - "docs": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command.md" + "documentation": "./dist/src/migrations/update-23-0-0/remove-experimental-prompt-command.md" }, "rewrite-internal-subpath-imports": { "version": "23.0.0-beta.19", diff --git a/packages/devkit/migrations.json b/packages/devkit/migrations.json index b8508d20233..861158ddc86 100644 --- a/packages/devkit/migrations.json +++ b/packages/devkit/migrations.json @@ -4,7 +4,7 @@ "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", - "docs": "./dist/src/migrations/update-23-0-0/update-deep-imports.md" + "documentation": "./dist/src/migrations/update-23-0-0/update-deep-imports.md" } }, "packageJsonUpdates": {}, diff --git a/packages/eslint/migrations.json b/packages/eslint/migrations.json index 314ffe50675..2926f0ba78a 100644 --- a/packages/eslint/migrations.json +++ b/packages/eslint/migrations.json @@ -7,7 +7,7 @@ "requires": { "@typescript-eslint/parser": ">=8.0.0" }, - "docs": "./dist/src/migrations/update-20-2-0/update-typescript-eslint-v8-13-0.md" + "documentation": "./dist/src/migrations/update-20-2-0/update-typescript-eslint-v8-13-0.md" }, "add-file-extensions-to-overrides": { "version": "20.3.0-beta.1", @@ -16,7 +16,7 @@ "requires": { "eslint": ">=8.57.0" }, - "docs": "./dist/src/migrations/update-20-3-0/add-file-extensions-to-overrides.md" + "documentation": "./dist/src/migrations/update-20-3-0/add-file-extensions-to-overrides.md" }, "update-executor-lint-inputs": { "version": "22.7.0-beta.12", diff --git a/packages/gradle/migrations.json b/packages/gradle/migrations.json index bfb8624a1c3..15b5c266222 100644 --- a/packages/gradle/migrations.json +++ b/packages/gradle/migrations.json @@ -5,161 +5,161 @@ "cli": "nx", "description": "Add includeSubprojectsTasks to build.gradle file", "factory": "./src/migrations/20-2-0/add-include-subprojects-tasks", - "docs": "./src/migrations/20-2-0/add-include-subprojects-tasks.md" + "documentation": "./src/migrations/20-2-0/add-include-subprojects-tasks.md" }, "change-plugin-to-v1": { "version": "21.0.0-beta.5", "cli": "nx", "description": "Change @nx/gradle plugin to version 1", "factory": "./src/migrations/21-0-0/change-plugin-to-v1", - "docs": "./src/migrations/21-0-0/change-plugin-to-v1.md" + "documentation": "./src/migrations/21-0-0/change-plugin-to-v1.md" }, "change-ciTargetName-to-ciTestTargetName": { "version": "21.0.0-beta.13", "cli": "nx", "description": "Change @nx/gradle option from ciTargetName to ciTestTargetName", "factory": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName", - "docs": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.md" + "documentation": "./src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.md" }, "change-plugin-version-0-1-0": { "version": "21.1.2-beta.1", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.0 in build file", "factory": "./src/migrations/21-1-2/change-plugin-version-0-1-0", - "docs": "./src/migrations/21-1-2/change-plugin-version-0-1-0.md" + "documentation": "./src/migrations/21-1-2/change-plugin-version-0-1-0.md" }, "change-plugin-version-0-1-2": { "version": "21.3.0-beta.0", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.2 in build file", "factory": "./src/migrations/21-3-0/change-plugin-version-0-1-2", - "docs": "./src/migrations/21-3-0/change-plugin-version-0-1-2.md" + "documentation": "./src/migrations/21-3-0/change-plugin-version-0-1-2.md" }, "change-plugin-version-0-1-4": { "version": "21.3.11-beta.0", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.4 in build file", "factory": "./src/migrations/21-3-11/change-plugin-version-0-1-4", - "docs": "./src/migrations/21-3-11/change-plugin-version-0-1-4.md" + "documentation": "./src/migrations/21-3-11/change-plugin-version-0-1-4.md" }, "change-plugin-version-0-1-5": { "version": "21.4.0-beta.12", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.5 in build file", "factory": "./src/migrations/21-4-0/change-plugin-version-0-1-5", - "docs": "./src/migrations/21-4-0/change-plugin-version-0-1-5.md" + "documentation": "./src/migrations/21-4-0/change-plugin-version-0-1-5.md" }, "change-plugin-version-0-1-6": { "version": "21.4.1-beta.1", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.6 in build file", "factory": "./src/migrations/21-4-1/change-plugin-version-0-1-6", - "docs": "./src/migrations/21-4-1/change-plugin-version-0-1-6.md" + "documentation": "./src/migrations/21-4-1/change-plugin-version-0-1-6.md" }, "change-plugin-version-0-1-7": { "version": "21.5.1-beta.5", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.7 in build file", "factory": "./src/migrations/21-5-1/change-plugin-version-0-1-7", - "docs": "./src/migrations/21-5-1/change-plugin-version-0-1-7.md" + "documentation": "./src/migrations/21-5-1/change-plugin-version-0-1-7.md" }, "change-plugin-version-0-1-8": { "version": "21.6.1-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.8 in build file", "factory": "./src/migrations/21-6-1/change-plugin-version-0-1-8", - "docs": "./src/migrations/21-6-1/change-plugin-version-0-1-8.md" + "documentation": "./src/migrations/21-6-1/change-plugin-version-0-1-8.md" }, "change-plugin-version-0-1-9": { "version": "22.1.0-rc.3", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.9 in build file", "factory": "./src/migrations/22-1-0/change-plugin-version-0-1-9", - "docs": "./src/migrations/22-1-0/change-plugin-version-0-1-9.md" + "documentation": "./src/migrations/22-1-0/change-plugin-version-0-1-9.md" }, "change-plugin-version-0-1-10": { "version": "22.2.0-beta.4", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.10 in build file", "factory": "./src/migrations/22-2-0/change-plugin-version-0-1-10", - "docs": "./src/migrations/22-2-0/change-plugin-version-0-1-10.md" + "documentation": "./src/migrations/22-2-0/change-plugin-version-0-1-10.md" }, "change-plugin-version-0-1-11": { "version": "22.4.0-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.11 in build file", "factory": "./src/migrations/22-3-0/change-plugin-version-0-1-11", - "docs": "./src/migrations/22-3-0/change-plugin-version-0-1-11.md" + "documentation": "./src/migrations/22-3-0/change-plugin-version-0-1-11.md" }, "change-plugin-version-0-1-12": { "version": "22.5.0-beta.5", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.12 in build file", "factory": "./src/migrations/22-5-0/change-plugin-version-0-1-12", - "docs": "./src/migrations/22-5-0/change-plugin-version-0-1-12.md" + "documentation": "./src/migrations/22-5-0/change-plugin-version-0-1-12.md" }, "change-plugin-version-0-1-13": { "version": "22.5.3", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.13 in build file", "factory": "./src/migrations/22-5-3/change-plugin-version-0-1-13", - "docs": "./src/migrations/22-5-3/change-plugin-version-0-1-13.md" + "documentation": "./src/migrations/22-5-3/change-plugin-version-0-1-13.md" }, "change-plugin-version-0-1-14": { "version": "22.6.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.14 in build file", "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-14", - "docs": "./src/migrations/22-6-0/change-plugin-version-0-1-14.md" + "documentation": "./src/migrations/22-6-0/change-plugin-version-0-1-14.md" }, "change-plugin-version-0-1-15": { "version": "22.6.0-beta.13", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.15 in build file", "factory": "./src/migrations/22-6-0/change-plugin-version-0-1-15", - "docs": "./src/migrations/22-6-0/change-plugin-version-0-1-15.md" + "documentation": "./src/migrations/22-6-0/change-plugin-version-0-1-15.md" }, "change-plugin-version-0-1-16": { "version": "22.7.0-beta.2", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.16 in build file", "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-16", - "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-16.md" + "documentation": "./src/migrations/22-7-0/change-plugin-version-0-1-16.md" }, "change-plugin-version-0-1-17": { "version": "22.7.0-beta.4", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.17 in build file", "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-17", - "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-17.md" + "documentation": "./src/migrations/22-7-0/change-plugin-version-0-1-17.md" }, "change-plugin-version-0-1-18": { "version": "22.7.0-beta.9", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.18 in build file", "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-18", - "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-18.md" + "documentation": "./src/migrations/22-7-0/change-plugin-version-0-1-18.md" }, "change-plugin-version-0-1-19": { "version": "22.7.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.19 in build file", "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-19", - "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-19.md" + "documentation": "./src/migrations/22-7-0/change-plugin-version-0-1-19.md" }, "change-plugin-version-0-1-20": { "version": "22.7.0-beta.16", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.20 in build file", "factory": "./src/migrations/22-7-0/change-plugin-version-0-1-20", - "docs": "./src/migrations/22-7-0/change-plugin-version-0-1-20.md" + "documentation": "./src/migrations/22-7-0/change-plugin-version-0-1-20.md" }, "change-plugin-version-0-1-21": { "version": "23.0.0-beta.11", "cli": "nx", "description": "Change dev.nx.gradle.project-graph to version 0.1.21 in build file", "factory": "./src/migrations/23-0-0/change-plugin-version-0-1-21", - "docs": "./src/migrations/23-0-0/change-plugin-version-0-1-21.md" + "documentation": "./src/migrations/23-0-0/change-plugin-version-0-1-21.md" } }, "packageJsonUpdates": {} diff --git a/packages/jest/migrations.json b/packages/jest/migrations.json index 444996f6244..5ad9db8d49d 100644 --- a/packages/jest/migrations.json +++ b/packages/jest/migrations.json @@ -5,26 +5,26 @@ "version": "20.0.0-beta.5", "description": "Replace usage of `getJestProjects` with `getJestProjectsAsync`.", "implementation": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync", - "docs": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" + "documentation": "./dist/src/migrations/update-20-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" }, "replace-getJestProjects-with-getJestProjectsAsync-v21": { "cli": "nx", "version": "21.0.0-beta.9", "description": "Replace usage of `getJestProjects` with `getJestProjectsAsync`.", "implementation": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync", - "docs": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" + "documentation": "./dist/src/migrations/update-21-0-0/replace-getJestProjects-with-getJestProjectsAsync.md" }, "remove-tsconfig-option-from-jest-executor": { "version": "21.0.0-beta.10", "description": "Remove the previously deprecated and unused `tsConfig` option from the `@nx/jest:jest` executor.", "implementation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor", - "docs": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor.md" + "documentation": "./dist/src/migrations/update-21-0-0/remove-tsconfig-option-from-jest-executor.md" }, "rename-test-path-pattern": { "version": "21.3.0-beta.3", "description": "Rename the CLI option `testPathPattern` to `testPathPatterns`.", "implementation": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern", - "docs": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern.md" + "documentation": "./dist/src/migrations/update-21-3-0/rename-test-path-pattern.md" }, "replace-removed-matcher-aliases": { "version": "21.3.0-beta.3", @@ -33,13 +33,13 @@ }, "description": "Replace removed matcher aliases in Jest v30 with their corresponding matcher", "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases", - "docs": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" + "documentation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" }, "convert-jest-config-to-cjs": { "version": "22.2.0-beta.2", "description": "Convert jest.config.ts files from ESM to CJS syntax (export default -> module.exports, import -> require) for projects using CommonJS resolution to ensure correct loading under Node.js type-stripping.", "implementation": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs", - "docs": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs.md" + "documentation": "./dist/src/migrations/update-22-2-0/convert-jest-config-to-cjs.md" }, "replace-removed-matcher-aliases-v22-3": { "version": "22.3.2-beta.0", @@ -48,7 +48,7 @@ }, "description": "Replace removed matcher aliases in Jest v30 with their corresponding matcher", "implementation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases", - "docs": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" + "documentation": "./dist/src/migrations/update-21-3-0/replace-removed-matcher-aliases.md" }, "update-snapshot-guide-link": { "version": "23.0.0-beta.10", @@ -57,7 +57,7 @@ }, "description": "Update the Jest snapshot guide link in `.snap` files from the legacy `https://goo.gl/fbAQLP` URL to `https://jestjs.io/docs/snapshot-testing`, which Jest v30 now requires.", "implementation": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link", - "docs": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link.md" + "documentation": "./dist/src/migrations/update-23-0-0/update-snapshot-guide-link.md" }, "rewrite-jest-internal-subpath-imports": { "version": "23.0.0-beta.16", diff --git a/packages/js/migrations.json b/packages/js/migrations.json index 0e5e56ff929..65571b9e1cb 100644 --- a/packages/js/migrations.json +++ b/packages/js/migrations.json @@ -4,19 +4,19 @@ "version": "21.5.0-beta.2", "description": "Migrate the legacy 'development' custom condition to a workspace-unique custom condition name.", "factory": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition", - "docs": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition.md" + "documentation": "./dist/src/migrations/update-21-5-0/migrate-development-custom-condition.md" }, "remove-external-options-from-js-executors": { "version": "22.0.0-beta.0", "description": "Remove the deprecated `external` and `externalBuildTargets` options from the `@nx/js:swc` and `@nx/js:tsc` executors.", "factory": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors", - "docs": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors.md" + "documentation": "./dist/src/migrations/update-22-0-0/remove-external-options-from-js-executors.md" }, "remove-redundant-ts-project-references": { "version": "22.1.0-rc.1", "description": "Removes redundant TypeScript project references from project's tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist.", "factory": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references", - "docs": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references.md" + "documentation": "./dist/src/migrations/update-22-1-0/remove-redundant-ts-project-references.md" }, "23-0-0-rewrite-internal-subpath-imports": { "version": "23.0.0-beta.14", diff --git a/packages/nx/migrations.json b/packages/nx/migrations.json index 433584b0180..fd0e5765239 100644 --- a/packages/nx/migrations.json +++ b/packages/nx/migrations.json @@ -42,7 +42,7 @@ "version": "17.0.0-beta.1", "description": "Updates the default cache directory to .nx/cache", "implementation": "./dist/src/migrations/update-17-0-0/move-cache-directory", - "docs": "./dist/src/migrations/update-17-0-0/move-cache-directory.md" + "documentation": "./dist/src/migrations/update-17-0-0/move-cache-directory.md" }, "17.0.0-use-minimal-config-for-tasks-runner-options": { "cli": "nx", @@ -95,38 +95,38 @@ "version": "20.0.0-beta.7", "description": "Migration for v20.0.0-beta.7", "implementation": "./dist/src/migrations/update-20-0-0/move-use-daemon-process", - "docs": "./dist/src/migrations/update-20-0-0/move-use-daemon-process.md" + "documentation": "./dist/src/migrations/update-20-0-0/move-use-daemon-process.md" }, "use-legacy-cache": { "version": "20.0.1", "description": "Set `useLegacyCache` to true for migrating workspaces", "implementation": "./dist/src/migrations/update-20-0-1/use-legacy-cache", "x-repair-skip": true, - "docs": "./dist/src/migrations/update-20-0-1/use-legacy-cache.md" + "documentation": "./dist/src/migrations/update-20-0-1/use-legacy-cache.md" }, "remove-legacy-cache": { "version": "21.0.0-beta.8", "description": "Removes the legacy cache configuration from nx.json", "implementation": "./dist/src/migrations/update-21-0-0/remove-legacy-cache", - "docs": "./dist/src/migrations/update-21-0-0/remove-legacy-cache.md" + "documentation": "./dist/src/migrations/update-21-0-0/remove-legacy-cache.md" }, "remove-custom-tasks-runner": { "version": "21.0.0-beta.8", "description": "Removes the legacy cache configuration from nx.json", "implementation": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner", - "docs": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner.md" + "documentation": "./dist/src/migrations/update-21-0-0/remove-custom-tasks-runner.md" }, "release-version-config-changes": { "version": "21.0.0-beta.11", "description": "Updates release version config based on the breaking changes in Nx v21", "implementation": "./dist/src/migrations/update-21-0-0/release-version-config-changes", - "docs": "./dist/src/migrations/update-21-0-0/release-version-config-changes.md" + "documentation": "./dist/src/migrations/update-21-0-0/release-version-config-changes.md" }, "release-changelog-config-changes": { "version": "21.0.0-beta.11", "description": "Updates release changelog config based on the breaking changes in Nx v21", "implementation": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes", - "docs": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes.md" + "documentation": "./dist/src/migrations/update-21-0-0/release-changelog-config-changes.md" }, "22-0-0-release-version-config-changes": { "version": "22.0.0-beta.1", @@ -167,7 +167,7 @@ "version": "22.7.0-beta.0", "description": "Adds .nx/self-healing to .gitignore", "implementation": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore", - "docs": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore.md" + "documentation": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore.md" }, "23-0-0-consolidate-release-tag-config": { "version": "23.0.0-beta.16", @@ -179,7 +179,7 @@ "version": "23.0.0-beta.13", "description": "Converts nx.json `targetDefaults` from the legacy record shape to the new filtered array shape.", "implementation": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array", - "docs": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array.md" + "documentation": "./dist/src/migrations/update-23-0-0/convert-target-defaults-to-array.md" }, "23-0-0-add-migrate-runs-to-git-ignore": { "version": "23.0.0-beta.18", diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts index 1d9d9924dc2..6502afacd67 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/generic-validation.spec.ts @@ -42,14 +42,19 @@ describe('buildGenericValidationUserPrompt', () => { expect(out).not.toContain(''); }); - it('renders the block when a docs path is provided, and omits it otherwise', () => { - const docsPath = + it('renders the block when a documentation path is provided, and omits it otherwise', () => { + const documentationPath = 'node_modules/@nx/react/dist/src/migrations/update-21-1-0/rewrite-config.md'; - const withDocs = buildGenericValidationUserPrompt({ ...baseCtx, docsPath }); - expect(withDocs).toContain(docsPath); - expect(withDocs).toMatch(//); + const withDocumentation = buildGenericValidationUserPrompt({ + ...baseCtx, + documentationPath, + }); + expect(withDocumentation).toContain(documentationPath); + expect(withDocumentation).toMatch( + // + ); expect(buildGenericValidationUserPrompt(baseCtx)).not.toContain( - ' { expect(out).not.toContain(' block when a docs path is provided, and omits it otherwise', () => { - const docsPath = + it('renders the block when a documentation path is provided, and omits it otherwise', () => { + const documentationPath = 'node_modules/@nx/react/dist/src/migrations/update-21-1-0/rewrite-config.md'; - const withDocs = buildHybridPromptUserPrompt({ ...baseCtx, docsPath }); - expect(withDocs).toContain(docsPath); - expect(withDocs).toMatch(//); + const withDocumentation = buildHybridPromptUserPrompt({ + ...baseCtx, + documentationPath, + }); + expect(withDocumentation).toContain(documentationPath); + expect(withDocumentation).toMatch( + // + ); expect(buildHybridPromptUserPrompt(baseCtx)).not.toContain( - ' { expect(buildPromptMigrationUserPrompt(base)).not.toContain('description:'); }); - it('renders the block when a docs path is provided', () => { + it('renders the block when a documentation path is provided', () => { const result = buildPromptMigrationUserPrompt({ ...base, - docsPath: + documentationPath: 'node_modules/@nx/storybook/src/migrations/9-2-0/migrate-css-imports.md', }); expect(result).toContain( 'node_modules/@nx/storybook/src/migrations/9-2-0/migrate-css-imports.md' ); - expect(result).toMatch(//); + expect(result).toMatch( + // + ); }); - it('omits the block when no docs path is provided', () => { + it('omits the block when no documentation path is provided', () => { expect(buildPromptMigrationUserPrompt(base)).not.toContain( - '${escapeXmlBody(ctx.promptPath)}`, ``, diff --git a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts index caa4c15a537..1ab711d7c78 100644 --- a/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts +++ b/packages/nx/src/command-line/migrate/agentic/prompts/shared-rendering.spec.ts @@ -3,7 +3,7 @@ import { renderGitInspectInstruction, renderKeyMultilineValue, renderListItem, - renderMigrationDocsBlock, + renderMigrationDocumentationBlock, stripAnsi, } from './shared-rendering'; @@ -57,25 +57,25 @@ describe('shared-rendering', () => { }); }); - describe('renderMigrationDocsBlock', () => { - it('returns an empty array when no docs path is provided', () => { - expect(renderMigrationDocsBlock(undefined)).toEqual([]); + describe('renderMigrationDocumentationBlock', () => { + it('returns an empty array when no documentation path is provided', () => { + expect(renderMigrationDocumentationBlock(undefined)).toEqual([]); }); - it('renders a reference-framed block pointing at the docs path', () => { - const out = renderMigrationDocsBlock( + it('renders a reference-framed block pointing at the documentation path', () => { + const out = renderMigrationDocumentationBlock( 'node_modules/@nx/webpack/src/migrations/update-21-0-0/remove-isolated-config.md' ); expect(out).toEqual([ ``, - ``, + ``, `node_modules/@nx/webpack/src/migrations/update-21-0-0/remove-isolated-config.md`, - ``, + ``, ]); }); - it('escapes the docs path so a hostile path cannot break out of the block', () => { - const out = renderMigrationDocsBlock('a { + const out = renderMigrationDocumentationBlock('a`, - escapeXmlBody(docsPath), - ``, + ``, + escapeXmlBody(documentationPath), + ``, ]; } diff --git a/packages/nx/src/command-line/migrate/agentic/run-step.ts b/packages/nx/src/command-line/migrate/agentic/run-step.ts index 74f75bbe848..38a4988a5e0 100644 --- a/packages/nx/src/command-line/migrate/agentic/run-step.ts +++ b/packages/nx/src/command-line/migrate/agentic/run-step.ts @@ -50,11 +50,12 @@ export interface RunAgenticPromptStepInput { prompt?: string; }; /** - * Workspace-relative path to the migration's docs file, resolved by the - * orchestrator; omitted when the migration declares no `docs` or it can't be - * resolved. + * Path to the migration's documentation file, resolved by the orchestrator - + * workspace-relative, or absolute when the file resolves outside the + * workspace. Omitted when the migration declares no `documentation` or it + * can't be resolved. */ - docsPath?: string; + documentationPath?: string; agentic: EnabledResolvedAgentic; runDir: string; installDepsIfChanged: () => Promise; @@ -83,7 +84,7 @@ export async function runAgenticPromptStep( runDir, installDepsIfChanged, implContext, - docsPath, + documentationPath, mode = 'author', } = input; @@ -117,7 +118,7 @@ export async function runAgenticPromptStep( version: migration.version, description: migration.description, handoffFileAbsolutePath: handoffFilePath, - docsPath, + documentationPath, impl: implContext, }); } else { @@ -128,7 +129,7 @@ export async function runAgenticPromptStep( description: migration.description, promptPath: migration.prompt!, handoffFileAbsolutePath: handoffFilePath, - docsPath, + documentationPath, }; userPrompt = implContext ? buildHybridPromptUserPrompt({ ...promptCtx, impl: implContext }) diff --git a/packages/nx/src/command-line/migrate/migrate.spec.ts b/packages/nx/src/command-line/migrate/migrate.spec.ts index 3778bea5b68..e37d7ec05d7 100644 --- a/packages/nx/src/command-line/migrate/migrate.spec.ts +++ b/packages/nx/src/command-line/migrate/migrate.spec.ts @@ -35,7 +35,8 @@ import { ResolvedMigrationConfiguration, resolveCanonicalNxPackage, resolveCreateCommits, - resolveMigrationDocsPath, + resolveDocumentationFileToWorkspacePath, + resolveMigrationForRun, resolveMode, } from './migrate'; import { @@ -54,6 +55,7 @@ import { } from 'fs'; import { tmpdir } from 'os'; import { dirname, join } from 'path'; +import { logger } from '../../utils/logger'; const createPackageJson = ( overrides: Partial = {} @@ -3639,6 +3641,38 @@ describe('Migration', () => { }); }); + // Regression guard: `documentation` rides through `createMigrateJson`'s + // spread untyped (GeneratedMigrationDetails treats it as optional and the + // generated migrations.json is written via an `as any` cast), so a future + // refactor could silently drop it from the generated file with no type + // error. This test fails if that happens. + it('should preserve the documentation field on migration entries', async () => { + const migrator = new Migrator({ + packageJson: createPackageJson({ dependencies: { pkg: '1.0.0' } }), + getInstalledPackageVersion: () => '1.0.0', + fetch: () => + Promise.resolve({ + version: '2.0.0', + generators: { + documented: { + version: '2.0.0', + description: 'documented migration', + implementation: './migrations/documented', + documentation: './src/migrations/update-2-0-0/documented.md', + }, + }, + } as ResolvedMigrationConfiguration), + from: {}, + to: {}, + }); + + const result = await migrator.migrate('pkg', '2.0.0'); + expect(result.migrations[0]).toMatchObject({ + name: 'documented', + documentation: './src/migrations/update-2-0-0/documented.md', + }); + }); + it('should preserve both prompt and implementation on hybrid entries', async () => { const migrator = new Migrator({ packageJson: createPackageJson({ dependencies: { pkg: '1.0.0' } }), @@ -4239,12 +4273,13 @@ describe('Migration', () => { }); }); - describe('resolveMigrationDocsPath', () => { + describe('resolveMigrationForRun', () => { let tmpRoot: string; + let warnSpy: jest.SpyInstance; const writeInstalledPackage = ( pkgName: string, - docsRelToMigrationsDir: string | null + documentationRelToMigrationsDir: string | null ) => { const pkgDir = join(tmpRoot, 'node_modules', pkgName); mkdirSync(pkgDir, { recursive: true }); @@ -4260,8 +4295,8 @@ describe('Migration', () => { join(pkgDir, 'migrations.json'), JSON.stringify({ generators: {} }) ); - if (docsRelToMigrationsDir) { - const docAbs = join(pkgDir, docsRelToMigrationsDir); + if (documentationRelToMigrationsDir) { + const docAbs = join(pkgDir, documentationRelToMigrationsDir); mkdirSync(dirname(docAbs), { recursive: true }); writeFileSync(docAbs, '# doc'); } @@ -4271,47 +4306,149 @@ describe('Migration', () => { // realpath so the workspace-relative assertion isn't defeated by the // macOS /tmp -> /private/tmp symlink (require.resolve returns realpaths). tmpRoot = realpathSync(mkdtempSync(join(tmpdir(), 'nx-migration-docs-'))); + warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => {}); }); afterEach(() => { + warnSpy.mockRestore(); rmSync(tmpRoot, { recursive: true, force: true }); }); - it('returns undefined when the migration declares no docs', () => { + it('resolves the documentation file to a workspace-relative node_modules path', () => { + writeInstalledPackage('@nx/foo', './src/migrations/update-1-0-0/do.md'); + const { documentationPath } = resolveMigrationForRun( + tmpRoot, + { + package: '@nx/foo', + name: 'update-1-0-0', + implementation: './src/migrations/update-1-0-0/do', + documentation: './src/migrations/update-1-0-0/do.md', + }, + true + ); + expect(documentationPath).toBe( + join('node_modules', '@nx/foo', 'src/migrations/update-1-0-0/do.md') + ); + expect(warnSpy).not.toHaveBeenCalled(); + }); + + it('returns no documentation path (and does not warn) when none is declared', () => { writeInstalledPackage('@nx/foo', null); - expect( - resolveMigrationDocsPath(tmpRoot, { package: '@nx/foo' }) - ).toBeUndefined(); + const { documentationPath } = resolveMigrationForRun( + tmpRoot, + { + package: '@nx/foo', + name: 'update-1-0-0', + implementation: './src/migrations/update-1-0-0/do', + }, + true + ); + expect(documentationPath).toBeUndefined(); + expect(warnSpy).not.toHaveBeenCalled(); }); - it('resolves the docs file to a workspace-relative node_modules path', () => { + it('does not resolve documentation for non-agentic runs', () => { writeInstalledPackage('@nx/foo', './src/migrations/update-1-0-0/do.md'); - expect( - resolveMigrationDocsPath(tmpRoot, { + const { documentationPath } = resolveMigrationForRun( + tmpRoot, + { package: '@nx/foo', - docs: './src/migrations/update-1-0-0/do.md', - }) - ).toBe( - join('node_modules', '@nx/foo', 'src/migrations/update-1-0-0/do.md') + name: 'update-1-0-0', + implementation: './src/migrations/update-1-0-0/do', + documentation: './src/migrations/update-1-0-0/do.md', + }, + false ); + expect(documentationPath).toBeUndefined(); + expect(warnSpy).not.toHaveBeenCalled(); }); - it('returns undefined when the docs file is not present in the installed package', () => { + it('warns and skips when a declared documentation file is not present', () => { writeInstalledPackage('@nx/foo', null); - expect( - resolveMigrationDocsPath(tmpRoot, { + const { documentationPath } = resolveMigrationForRun( + tmpRoot, + { package: '@nx/foo', - docs: './src/migrations/update-1-0-0/missing.md', - }) - ).toBeUndefined(); + name: 'update-1-0-0', + implementation: './src/migrations/update-1-0-0/do', + documentation: './src/migrations/update-1-0-0/missing.md', + }, + true + ); + expect(documentationPath).toBeUndefined(); + expect(warnSpy).toHaveBeenCalledTimes(1); + expect(warnSpy.mock.calls[0][0]).toContain( + './src/migrations/update-1-0-0/missing.md' + ); }); - it('returns undefined when the package cannot be resolved', () => { - expect( - resolveMigrationDocsPath(tmpRoot, { + it('throws when an implementation migration package cannot be resolved', () => { + expect(() => + resolveMigrationForRun( + tmpRoot, + { + package: '@nx/not-installed', + name: 'update-1-0-0', + implementation: './x', + documentation: './x.md', + }, + true + ) + ).toThrow(); + }); + + it('is non-fatal for prompt-only migrations when the package cannot be resolved', () => { + const { documentationPath } = resolveMigrationForRun( + tmpRoot, + { package: '@nx/not-installed', - docs: './x.md', - }) + name: 'update-1-0-0', + prompt: './x.md', + documentation: './x.md', + }, + true + ); + expect(documentationPath).toBeUndefined(); + expect(warnSpy).toHaveBeenCalledTimes(1); + }); + }); + + describe('resolveDocumentationFileToWorkspacePath', () => { + let tmpRoot: string; + + beforeEach(() => { + tmpRoot = realpathSync(mkdtempSync(join(tmpdir(), 'nx-doc-resolve-'))); + }); + + afterEach(() => { + rmSync(tmpRoot, { recursive: true, force: true }); + }); + + it('resolves a package-relative documentation path to a workspace-relative path', () => { + const migrationsDir = join(tmpRoot, 'node_modules', '@nx/foo'); + const docAbs = join(migrationsDir, 'src/migrations/update-1-0-0/do.md'); + mkdirSync(dirname(docAbs), { recursive: true }); + writeFileSync(docAbs, '# doc'); + expect( + resolveDocumentationFileToWorkspacePath( + tmpRoot, + migrationsDir, + './src/migrations/update-1-0-0/do.md' + ) + ).toBe( + join('node_modules', '@nx/foo', 'src/migrations/update-1-0-0/do.md') + ); + }); + + it('returns undefined when the documentation file does not exist', () => { + const migrationsDir = join(tmpRoot, 'node_modules', '@nx/foo'); + mkdirSync(migrationsDir, { recursive: true }); + expect( + resolveDocumentationFileToWorkspacePath( + tmpRoot, + migrationsDir, + './missing.md' + ) ).toBeUndefined(); }); }); diff --git a/packages/nx/src/command-line/migrate/migrate.ts b/packages/nx/src/command-line/migrate/migrate.ts index 78349ec30f4..6f09253c704 100644 --- a/packages/nx/src/command-line/migrate/migrate.ts +++ b/packages/nx/src/command-line/migrate/migrate.ts @@ -2374,7 +2374,7 @@ type ExecutableMigration = { implementation?: string; factory?: string; prompt?: string; - docs?: string; + documentation?: string; }; export { isPromptOnlyMigration, isHybridMigration }; @@ -2653,10 +2653,16 @@ export async function executeMigrations( // Content-sensitive so a dirty→dirty case (this migration mutating an // already-dirty shared file like `package.json`) doesn't collapse. const baselineWorkingTreeSnapshot = getUncommittedChangesSnapshot(root); - // Resolve the migration's docs file once per iteration, only when an - // agentic step may consume it (skips the node_modules lookup otherwise). - const docsPath = agenticRun ? resolveMigrationDocsPath(root, m) : undefined; try { + // Read this migration's collection once and derive everything from it: + // the implementation context (passed to runNxOrAngularMigration) and the + // documentation path (passed to the agent). Read fresh per iteration so a + // prior migration's reinstall is reflected. + const { resolvedCollection, documentationPath } = resolveMigrationForRun( + root, + m, + !!agenticRun + ); let outcome: MigrationOutcomeKind; let commit: CommitState = { kind: 'none' }; if (isPromptOnlyMigration(m)) { @@ -2667,7 +2673,7 @@ export async function executeMigrations( agentic: agenticRun.agentic, runDir: agenticRun.runDir, installDepsIfChanged, - docsPath, + documentationPath, }); commit = await attemptMigrationCommit(m); logAgenticSuccessOutcome( @@ -2690,7 +2696,8 @@ export async function executeMigrations( root, m, isVerbose, - /* captureGeneratorOutput: */ !!agenticRun + /* captureGeneratorOutput: */ !!agenticRun, + resolvedCollection ); migrationEmittedNextSteps.push(...nextSteps); @@ -2705,7 +2712,7 @@ export async function executeMigrations( agentic: agenticRun.agentic, runDir: agenticRun.runDir, installDepsIfChanged, - docsPath, + documentationPath, implContext: { logs, changes, @@ -2765,7 +2772,8 @@ export async function executeMigrations( root, m, isVerbose, - /* captureGeneratorOutput: */ !!validationRun + /* captureGeneratorOutput: */ !!validationRun, + resolvedCollection ); migrationEmittedNextSteps.push(...nextSteps); const canRunValidation = !!validationRun && changes.length > 0; @@ -2780,7 +2788,7 @@ export async function executeMigrations( agentic: validationRun.agentic, runDir: validationRun.runDir, installDepsIfChanged, - docsPath, + documentationPath, implContext: { logs, changes, @@ -2949,7 +2957,8 @@ export async function runNxOrAngularMigration( version: string; }, isVerbose: boolean, - captureGeneratorOutput = false + captureGeneratorOutput = false, + resolvedCollection?: { collection: MigrationsJson; collectionPath: string } ): Promise<{ changes: FileChange[]; nextSteps: string[]; @@ -2957,10 +2966,8 @@ export async function runNxOrAngularMigration( logs: string; madeChanges: boolean; }> { - const { collection, collectionPath } = readMigrationCollection( - migration.package, - root - ); + const { collection, collectionPath } = + resolvedCollection ?? readMigrationCollection(migration.package, root); let changes: FileChange[] = []; let nextSteps: string[] = []; let agentContext: string[] = []; @@ -3459,54 +3466,87 @@ export function getImplementationPath( } /** - * Resolves a migration's `docs` file to a workspace-relative path for the - * agentic prompt. The authored `docs` path is relative to the package's - * `migrations.json` and resolved against the installed package, the same way - * `implementation` / `factory` are resolved in `getImplementationPath`. + * Resolves a migration's collection once and derives everything the run loop + * needs from that single read: the implementation context (`collection` + + * `collectionPath`, handed to `runNxOrAngularMigration`) and, for agentic runs, + * the workspace-relative documentation path handed to the agent. * - * Returns `undefined` when the migration declares no `docs` or the file can't - * be resolved. Docs are supplementary context, so a missing file is non-fatal - * here (unlike a missing implementation, which aborts the migration). + * Read fresh per migration (not cached across the loop) so a prior migration's + * reinstall is reflected, exactly as before. Error handling matches each field's + * role: + * - Migrations that run an implementation REQUIRE the collection; an unreadable + * collection throws and aborts that migration (caught by the run loop). + * - Prompt-only migrations don't run an implementation, so the collection is + * read only to resolve documentation - a failure there is non-fatal: the + * prompt still runs and the supplementary doc is skipped with a warning. */ -export function resolveMigrationDocsPath( +export function resolveMigrationForRun( root: string, - migration: { package: string; docs?: string } -): string | undefined { - if (!migration.docs) { - return undefined; + migration: { + package: string; + name: string; + documentation?: string; + implementation?: string; + factory?: string; + prompt?: string; + }, + resolveDocumentation: boolean +): { + resolvedCollection?: { collection: MigrationsJson; collectionPath: string }; + documentationPath?: string; +} { + let resolvedCollection: + | { collection: MigrationsJson; collectionPath: string } + | undefined; + if (!isPromptOnlyMigration(migration)) { + resolvedCollection = readMigrationCollection(migration.package, root); + } else if (resolveDocumentation && migration.documentation) { + try { + resolvedCollection = readMigrationCollection(migration.package, root); + } catch { + // Non-fatal: documentation is supplementary; the warning below fires. + } } - let migrationsFilePath: string | null; - try { - migrationsFilePath = readPackageMigrationConfig( - migration.package, - root - ).migrations; - } catch { - return undefined; - } - if (!migrationsFilePath) { - return undefined; + let documentationPath: string | undefined; + if (resolveDocumentation && migration.documentation) { + documentationPath = resolvedCollection + ? resolveDocumentationFileToWorkspacePath( + root, + dirname(resolvedCollection.collectionPath), + migration.documentation + ) + : undefined; + if (!documentationPath) { + logger.warn( + `Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped as additional context for the AI agent.` + ); + } } - const migrationsDir = dirname(migrationsFilePath); - let docsPath: string; + return { resolvedCollection, documentationPath }; +} + +// Resolves a `documentation` path (relative to the package's migrations dir) to +// a workspace-relative path - or the absolute path when it resolves outside the +// workspace (unusual hoisted/symlinked layouts). The agent runs with cwd = +// workspace root, so the workspace-relative form is preferred. Returns +// undefined when the file can't be resolved. +export function resolveDocumentationFileToWorkspacePath( + root: string, + migrationsDir: string, + documentation: string +): string | undefined { + let documentationFile: string; try { - docsPath = require.resolve(migration.docs, { paths: [migrationsDir] }); + documentationFile = require.resolve(documentation, { + paths: [migrationsDir], + }); } catch { - try { - // workaround for a bug in node 12 - docsPath = require.resolve(`${migrationsDir}/${migration.docs}`); - } catch { - return undefined; - } + return undefined; } - - // The agent runs with cwd = workspace root, so prefer a workspace-relative - // path. Fall back to the absolute path if the doc resolves outside root - // (e.g. an unusual hoisted/symlinked node_modules layout). - const relativePath = relative(root, docsPath); - return relativePath.startsWith('..') ? docsPath : relativePath; + const relativePath = relative(root, documentationFile); + return relativePath.startsWith('..') ? documentationFile : relativePath; } class MigrationImplementationMissingError extends Error { diff --git a/packages/nx/src/config/misc-interfaces.ts b/packages/nx/src/config/misc-interfaces.ts index 7e34dcd2405..e992c666c46 100644 --- a/packages/nx/src/config/misc-interfaces.ts +++ b/packages/nx/src/config/misc-interfaces.ts @@ -114,7 +114,7 @@ export interface MigrationsJsonEntry { * supplementary; never stands in for them. Under `--run-migrations * --agentic` the resolved path is passed to the agent as extra context. */ - docs?: string; + documentation?: string; } export type MigrationDetailsWithId = GeneratedMigrationDetails & { @@ -127,6 +127,7 @@ export interface GeneratedMigrationDetails { description: string; implementation?: string; prompt?: string; + documentation?: string; } export interface MigrationsJson { diff --git a/packages/nx/src/internal-testing-utils/assert-valid-migrations.ts b/packages/nx/src/internal-testing-utils/assert-valid-migrations.ts index 574feef3515..f938bc1fa46 100644 --- a/packages/nx/src/internal-testing-utils/assert-valid-migrations.ts +++ b/packages/nx/src/internal-testing-utils/assert-valid-migrations.ts @@ -29,6 +29,9 @@ export function assertValidMigrationPaths(json: MigrationsJson, root: string) { if (m.prompt) { knownDirs.add(path.basename(path.dirname(m.prompt))); } + if (m.documentation) { + knownDirs.add(path.basename(path.dirname(m.documentation))); + } } for (const dir of dirs) { expect(knownDirs).toContain(dir); @@ -58,4 +61,13 @@ function validateMigration(m: MigrationsJsonEntry, root: string) { const promptSourcePath = m.prompt.replace(/^\.?\/?dist\//, ''); expect(fs.existsSync(path.join(root, promptSourcePath))).toBe(true); } + if (m.documentation) { + // Same published-shape mapping as `prompt`: documentation paths point at + // the built `./dist/src/.../foo.md`, so map back to the source tree. + const documentationSourcePath = m.documentation.replace( + /^\.?\/?dist\//, + '' + ); + expect(fs.existsSync(path.join(root, documentationSourcePath))).toBe(true); + } } diff --git a/packages/react/migrations.json b/packages/react/migrations.json index fd6b0b7ef7f..80a7ecf6a5f 100644 --- a/packages/react/migrations.json +++ b/packages/react/migrations.json @@ -5,35 +5,35 @@ "version": "20.2.0-beta.2", "description": "Update the ModuleFederationConfig import use @nx/module-federation.", "factory": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package", - "docs": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" + "documentation": "./src/migrations/update-20-2-0/migrate-mf-imports-to-new-package.md" }, "update-20-2-0-update-with-module-federation-import": { "cli": "nx", "version": "20.2.0-beta.2", "description": "Update the withModuleFederation import use @nx/module-federation/webpack.", "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", - "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" + "documentation": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", - "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" + "documentation": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "add-mf-env-var-to-target-defaults": { "cli": "nx", "version": "20.4.0-beta.0", "description": "Add NX_MF_DEV_REMOTES to inputs for task hashing when '@nx/webpack:webpack' or '@nx/rspack:rspack' is used for Module Federation.", "factory": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults", - "docs": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults.md" + "documentation": "./src/migrations/update-18-0-0/add-mf-env-var-to-target-defaults.md" }, "update-21-0-0-update-babel-loose": { "cli": "nx", "version": "21.0.0-beta.11", "description": "Replaces `classProperties.loose` option with `loose`.", "factory": "./src/migrations/update-21-0-0/update-babel-loose", - "docs": "./src/migrations/update-21-0-0/update-babel-loose.md" + "documentation": "./src/migrations/update-21-0-0/update-babel-loose.md" }, "update-22-0-0-add-svgr-to-webpack-config": { "cli": "nx", @@ -46,7 +46,7 @@ "version": "23.0.0-beta.10", "description": "Rewrites imports of NxReactWebpackPlugin from '@nx/react' to the sub-path '@nx/react/webpack-plugin'.", "factory": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import", - "docs": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import.md" + "documentation": "./src/migrations/update-23-0-0/remove-nx-react-webpack-plugin-import.md" } }, "packageJsonUpdates": { diff --git a/packages/rollup/migrations.json b/packages/rollup/migrations.json index 2602b7f5e8f..c9d651d3294 100644 --- a/packages/rollup/migrations.json +++ b/packages/rollup/migrations.json @@ -5,7 +5,7 @@ "version": "23.0.0-beta.4", "description": "Remove deprecated useLegacyTypescriptPlugin option from @nx/rollup:rollup", "implementation": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin", - "docs": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin.md" + "documentation": "./src/migrations/update-23-0-0/remove-use-legacy-typescript-plugin.md" } }, "packageJsonUpdates": {} diff --git a/packages/rspack/migrations.json b/packages/rspack/migrations.json index 8d188f5029c..91739cdd9df 100644 --- a/packages/rspack/migrations.json +++ b/packages/rspack/migrations.json @@ -5,14 +5,14 @@ "version": "20.2.0-beta.3", "description": "Update the withModuleFederation import use @nx/module-federation/rspack.", "factory": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package", - "docs": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" + "documentation": "./src/migrations/update-20-2-0/migrate-with-mf-import-to-new-package.md" }, "ensure-nx-module-federation-package": { "cli": "nx", "version": "20.3.0-beta.2", "description": "If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.", "factory": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package", - "docs": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" + "documentation": "./src/migrations/update-20-3-0/ensure-nx-module-federation-package.md" }, "remove-deprecated-rspack-options": { "cli": "nx", @@ -25,7 +25,7 @@ "version": "23.0.0-beta.9", "description": "Updates rspack configs using React to use the new withSvgr composable function instead of the svgr option in withReact or NxReactRspackPlugin.", "factory": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config", - "docs": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config.md" + "documentation": "./src/migrations/update-23-0-0/add-svgr-to-rspack-config.md" } }, "packageJsonUpdates": { diff --git a/packages/rspack/migrations.spec.ts b/packages/rspack/migrations.spec.ts new file mode 100644 index 00000000000..20077a96855 --- /dev/null +++ b/packages/rspack/migrations.spec.ts @@ -0,0 +1,8 @@ +import json = require('./migrations.json'); + +import { assertValidMigrationPaths } from '@nx/devkit/internal-testing-utils'; +import { MigrationsJson } from '@nx/devkit'; + +describe('rspack migrations', () => { + assertValidMigrationPaths(json as MigrationsJson, __dirname); +}); diff --git a/packages/vite/migrations.json b/packages/vite/migrations.json index ef45258742b..acfd15cd2fe 100644 --- a/packages/vite/migrations.json +++ b/packages/vite/migrations.json @@ -4,31 +4,31 @@ "version": "20.0.4-beta.0", "description": "Add gitignore entry for temporary vite config files.", "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore", - "docs": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" + "documentation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" }, "update-20-0-6": { "version": "20.0.6-beta.0", "description": "Add gitignore entry for temporary vite config files and remove previous incorrect glob.", "implementation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore", - "docs": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" + "documentation": "./dist/src/migrations/update-20-0-4/add-vite-temp-files-to-git-ignore.md" }, "update-20-5-0-install-jiti": { "version": "20.5.0-beta.2", "description": "Install jiti as a devDependency to allow vite to parse TS postcss files.", "implementation": "./dist/src/migrations/update-20-5-0/install-jiti", - "docs": "./dist/src/migrations/update-20-5-0/install-jiti.md" + "documentation": "./dist/src/migrations/update-20-5-0/install-jiti.md" }, "update-20-5-0-update-resolve-conditions": { "version": "20.5.0-beta.3", "description": "Update resolve.conditions to include defaults that are no longer provided by Vite.", "implementation": "./dist/src/migrations/update-20-5-0/update-resolve-conditions", - "docs": "./dist/src/migrations/update-20-5-0/update-resolve-conditions.md" + "documentation": "./dist/src/migrations/update-20-5-0/update-resolve-conditions.md" }, "eslint-ignore-vite-temp-files": { "version": "20.5.0-beta.3", "description": "Add vite config temporary files to the ESLint configuration ignore patterns if ESLint is used.", "implementation": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files", - "docs": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files.md" + "documentation": "./dist/src/migrations/update-20-5-0/eslint-ignore-vite-temp-files.md" }, "update-22-2-0": { "version": "22.2.0-beta.1", @@ -47,7 +47,7 @@ "version": "23.0.0-beta.10", "description": "Safety net: ensure any remaining @nx/vite:test executor usages are swapped to @nx/vitest:test and @nx/vitest is installed.", "implementation": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration", - "docs": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration.md" + "documentation": "./dist/src/migrations/update-23-0-0/ensure-vitest-package-migration.md" }, "rename-rollup-options-to-rolldown-options": { "version": "23.0.0-beta.10", @@ -56,7 +56,7 @@ }, "description": "Rename `rollupOptions` to `rolldownOptions` in vite config files (top-level and inside `environments`). Vite 8 replaced Rollup with Rolldown.", "implementation": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options", - "docs": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options.md" + "documentation": "./dist/src/migrations/update-23-0-0/rename-rollup-options-to-rolldown-options.md" }, "create-ai-instructions-for-vite-8": { "version": "23.0.0-beta.10", diff --git a/packages/vitest/migrations.json b/packages/vitest/migrations.json index e174769cc03..711e33d5ac2 100644 --- a/packages/vitest/migrations.json +++ b/packages/vitest/migrations.json @@ -4,7 +4,7 @@ "version": "20.3.0-beta.2", "description": "Add gitignore entry for temporary vitest config files.", "implementation": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore", - "docs": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore.md" + "documentation": "./dist/src/migrations/update-20-3-0/add-vitest-temp-files-to-git-ignore.md" }, "update-22-1-0": { "version": "22.1.0-beta.8", @@ -23,7 +23,7 @@ "version": "22.6.0-beta.11", "description": "Prefix reportsDirectory with {projectRoot} to maintain correct resolution after workspace-root-relative behavior change.", "implementation": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root", - "docs": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root.md" + "documentation": "./dist/src/migrations/update-22-6-0/prefix-reports-directory-with-project-root.md" } }, "packageJsonUpdates": { diff --git a/packages/webpack/migrations.json b/packages/webpack/migrations.json index d9ec8adffc0..d0ea787a3aa 100644 --- a/packages/webpack/migrations.json +++ b/packages/webpack/migrations.json @@ -5,7 +5,7 @@ "version": "21.0.0-beta.11", "description": "Remove isolatedConfig option for @nx/webpack:webpack", "implementation": "./src/migrations/update-21-0-0/remove-isolated-config", - "docs": "./src/migrations/update-21-0-0/remove-isolated-config.md" + "documentation": "./src/migrations/update-21-0-0/remove-isolated-config.md" }, "update-22-0-0-remove-deprecated-options": { "cli": "nx", @@ -18,7 +18,7 @@ "version": "23.0.0-beta.10", "description": "Rewrites imports of NxTsconfigPathsWebpackPlugin from '@nx/webpack' to the sub-path '@nx/webpack/tsconfig-paths-plugin'.", "factory": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import", - "docs": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import.md" + "documentation": "./src/migrations/update-23-0-0/remove-nx-tsconfig-paths-webpack-plugin-import.md" } }, "packageJsonUpdates": { From d06e9191892c61843b75f6abf9c0dbfd224ec794 Mon Sep 17 00:00:00 2001 From: "nx-cloud[bot]" <71083854+nx-cloud[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 15:37:16 +0000 Subject: [PATCH 4/4] cleanup(core): rename migration docs field to documentation and resolve it from the collection [Self-Healing CI Rerun]