feat(core): feed migration docs to agents in nx migrate#35835
Merged
Conversation
✅ Deploy Preview for nx-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for nx-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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.
…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.
Contributor
|
View your CI Pipeline Execution ↗ for commit d06e919
☁️ Nx Cloud last updated this comment at |
FrozenPandaz
requested changes
Jun 1, 2026
FrozenPandaz
left a comment
FrozenPandaz
left a comment
Contributor
There was a problem hiding this comment.
Add a regression test that documentation survives into the generated migrations.json — it's the one type-unsafe seam (GeneratedMigrationDetails omits docs + an as any cast), so a future refactor could silently drop it with no test
failing. An analogous prompt test already exists at migrate.spec.ts:3628.
FrozenPandaz
requested changes
Jun 1, 2026
…ve 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
…ve it from the collection [Self-Healing CI Rerun]
![nx-cloud[bot]](https://avatars.githubusercontent.com/in/80458?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Nx Cloud has identified a flaky task in your failed CI:
🔂 Since the failure was identified as flaky, we triggered a CI rerun by adding an empty commit to this branch.
🎓 Learn more about Self-Healing CI on nx.dev
FrozenPandaz
approved these changes
Jun 2, 2026
vrxj81
pushed a commit
to vrxj81/nx
that referenced
this pull request
Jun 7, 2026
## Current Behavior A migration's documentation (the co-located markdown explaining what it does) is not referenced in `migrations.json`, so when `nx migrate --run-migrations --agentic` drives an AI agent, the agent has no access to it. ## Expected Behavior Migration entries can declare a `docs` markdown path. `nx migrate` carries it into the generated `migrations.json`, and under `--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. Existing first-party migrations with co-located docs are wired up via the new field and published with their packages. <!-- polygraph-session-start --> --- [View session information ↗](https://snapshot.app.trypolygraph.com/orgs/69cdc268b6aa527e4129c2b4/sessions/nxc-4495-6c420036) <!-- polygraph-session-end --> --------- Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Current Behavior
A migration's documentation (the co-located markdown explaining what it does) is not referenced in
migrations.json, so whennx migrate --run-migrations --agenticdrives an AI agent, the agent has no access to it.Expected Behavior
Migration entries can declare a
docsmarkdown path.nx migratecarries it into the generatedmigrations.json, and under--agenticthe 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. Existing first-party migrations with co-located docs are wired up via the new field and published with their packages.View session information ↗