fix(codemod): make agents-md docs root relative to the output file (#100016)
### What?
`npx @next/codemod agents-md` now writes every path in the generated
docs index relative to the directory of the `--output` file, not the
current working directory. Part 1 of 2 for #99771; the stacked follow-up
handles running from a monorepo root.
- **`root`**:
- **Bundled docs:** links the install that was actually indexed, through
its stable `node_modules/next` symlink path, relative to the output
file. Example: running from `apps/web` with `--output ../../AGENTS.md`
now writes `root: ./apps/web/node_modules/next/dist/docs` instead of a
broken `./node_modules/next/dist/docs`.
- **Downloaded docs:** `.next-docs` is linked the same way
(`./apps/web/.next-docs`).
- **Regeneration hint**: now `run this command from this file's
directory: … --output AGENTS.md`. It used to embed the raw cwd-relative
`--output ../../AGENTS.md`.
- **Absolute `--output`**: now resolved with `path.resolve`. Previously
`path.join` appended it to the cwd.
- **Prefixes**: links always start with `./` or `../`. The old
`startsWith('.')` check would have emitted `.next-docs`.
### Why?
Agents resolve `root` from the `AGENTS.md` file's location, the same
convention as the `agentRules` block ("resolved from this file's
directory"). Monorepos that keep a single root `AGENTS.md` had to run
the codemod from the app, and that produced a `root` that doesn't exist
from the repo root.
Simply switching the base to the output directory isn't enough. The
conventional-path shortcut would then check the output directory's
`node_modules`. If the root hoists a different `next` (e.g. 16.3.0 while
the app has 16.4.0), the link would point at a different version's docs
than the one indexed. That case is covered by a test.
### How?
- `getBundledDocsInfo` now returns `resolvedFrom`, the directory `next`
was resolved from.
- `getBundledDocsLinkPath(fromDir, docsPath, resolvedFrom)` prefers
`<resolvedFrom>/node_modules/next/dist/docs`, but only if it is the same
install. Otherwise it falls back to the realpath.
- A new `getRelativeLinkPath` helper builds the `./`/`../`-prefixed,
forward-slash link for both branches.
- Paths are compared and related in canonical form
(`fs.realpathSync.native`). On Windows, `process.cwd()` can keep an 8.3
short name (`C:\Users\RUNNER~1\…`) while module resolution returns the
long name; mixing the two produced a broken root. The parent directory
is canonicalized before `node_modules/next/dist/docs` is appended, so
the stable symlink path is kept.
### Verification
- New offline e2e tests in `lib/__tests__/agents-md-e2e.test.js`, using
a pnpm-style isolated fixture and a stubbed `pullDocs`:
- output outside the cwd (bundled and downloaded);
- mixed hoisted versions;
- the hint;
- absolute `--output`;
- `./` and `../` boundaries;
- a cwd spelled differently from the realpath: a symlinked alias, and a
mock in which only the native realpath canonicalizes, as with Windows
8.3 names. Both failed before the canonical-path change.
- The existing agents-md e2e suite passes, including its network
download tests: 22/22.
- Manually reproduced both of the issue's scenarios against a simulated
pnpm workspace:
- Running from the app now writes a `root` that resolves.
- Running from the root still downloads; the stacked follow-up fixes
that.
Part of #99771
<!-- NEXT_JS_LLM -->
<!-- fleet c69f306a-7676-4b84-8d3a-927ca1ab5f43 -->
---------
Co-authored-by:
vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by:
Tobias Koppers <1365881+sokra@users.noreply.github.com>
Showing
This diff is collapsed.
Please
register
or
sign in
to comment