Unverified Commit 43cb38c7 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

fix(codemod): find bundled docs via workspace packages in agents-md (#100017)

### What?

When `npx @next/codemod agents-md` runs from the root of a monorepo with
isolated installs (pnpm), it now uses the docs bundled in a workspace
package's `next` install. Before, it downloaded a second copy into
`.next-docs` and edited `.gitignore`. Part 2 of 2 for #99771, stacked on
#100016.

Example: from a pnpm root where only `apps/web` depends on
`next@16.4.0`, it now writes `root:
./apps/web/node_modules/next/dist/docs` and logs:

```
Using the docs bundled with Next.js 16.4.0 from workspace package apps/web at ./apps/web/node_modules/next/dist/docs (no download needed).
```

### Why?

`getNextjsVersion` already falls back to scanning workspace packages, so
the version was detected (16.4.0). But `getBundledDocsInfo` only
resolved `next` from the cwd. Under pnpm, `next` isn't resolvable from
the root, so the codemod fell through to downloading.

### How?

`getBundledDocsInfo(cwd, version)` now takes the requested version:
- It uses the install resolved from the cwd if that install's version
matches.
- Otherwise it walks the workspace packages with the same
`detectWorkspace` and `expandWorkspacePatterns` discovery
`getNextjsVersion` uses, and returns the **first package in workspace
order** whose bundled docs match that version.
- When nothing matches, the existing download path is unchanged.

The CLI logs which workspace package it picked.

### Verification

New offline e2e tests:
- A pnpm root uses the bundled docs: no download, no `.gitignore`.
- With several versions and no `--version`, the highest (detected)
version's package is indexed.
- With duplicate matches, the first in workspace order is used and
logged (patterns are listed in non-alphabetical order).
- A matching install resolved from the cwd wins.
- `--version` selects a workspace package even when the cwd resolves
another version.
- With no match, it still downloads.

Results:
- The full agents-md e2e suite passes: 28/28, also with `FORCE_COLOR=1`.
- Manually reproduced the issue's step 3 against a simulated pnpm
workspace: it now uses the bundled docs.

Fixes #99771

<!-- NEXT_JS_LLM -->


<!-- fleet c69f306a-7676-4b84-8d3a-927ca1ab5f43 -->
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
parent 8a63e04f
...@@ -81,12 +81,12 @@ export async function runAgentsMd(options: AgentsMdOptions): Promise<void> { ...@@ -81,12 +81,12 @@ export async function runAgentsMd(options: AgentsMdOptions): Promise<void> {
// so every link written into it is relative to that directory, not the cwd. // so every link written into it is relative to that directory, not the cwd.
const outputDir = path.dirname(agentsMdPath) const outputDir = path.dirname(agentsMdPath)
// Next.js >= 16.2.0 ships its docs inside the published package. When the // Next.js >= 16.2.0 ships its docs inside the published package. When an
// installed version matches the requested one, index the bundled docs // installed version (from the cwd or, in a monorepo, a workspace package)
// directly instead of downloading a copy into .next-docs. // matches the requested one, index the bundled docs directly instead of
const bundledDocs = getBundledDocsInfo(cwd) // downloading a copy into .next-docs.
const useBundledDocs = const bundledDocs = getBundledDocsInfo(cwd, nextjsVersion)
bundledDocs !== null && bundledDocs.version === nextjsVersion const useBundledDocs = bundledDocs !== null
const docsPath = useBundledDocs const docsPath = useBundledDocs
? bundledDocs.docsPath ? bundledDocs.docsPath
...@@ -110,8 +110,14 @@ export async function runAgentsMd(options: AgentsMdOptions): Promise<void> { ...@@ -110,8 +110,14 @@ export async function runAgentsMd(options: AgentsMdOptions): Promise<void> {
} }
if (useBundledDocs) { if (useBundledDocs) {
const fromWorkspacePackage =
path.resolve(bundledDocs.resolvedFrom) !== path.resolve(cwd)
? ` from workspace package ${pc.cyan(
path.relative(cwd, bundledDocs.resolvedFrom).replace(/\\/g, '/')
)}`
: ''
console.log( console.log(
`\nUsing the docs bundled with Next.js ${pc.cyan(nextjsVersion)} at ${pc.cyan(docsLinkPath)} (no download needed).` `\nUsing the docs bundled with Next.js ${pc.cyan(nextjsVersion)}${fromWorkspacePackage} at ${pc.cyan(docsLinkPath)} (no download needed).`
) )
} else { } else {
console.log( console.log(
......
...@@ -682,6 +682,140 @@ This is my project documentation. ...@@ -682,6 +682,140 @@ This is my project documentation.
'./..docs' './..docs'
) )
}) })
// In a pnpm monorepo `next` is usually not resolvable from the repo root,
// so the bundled docs have to be found through the workspace packages.
describe('bundled docs from workspace packages', () => {
function setupWorkspace(patterns, packages) {
fs.writeFileSync(
path.join(testProjectDir, 'package.json'),
JSON.stringify({ name: 'root', private: true })
)
fs.writeFileSync(
path.join(testProjectDir, 'pnpm-workspace.yaml'),
`packages:\n${patterns.map((p) => ` - '${p}'`).join('\n')}\n`
)
for (const [pkg, version] of Object.entries(packages)) {
const pkgDir = path.join(testProjectDir, pkg)
fs.mkdirSync(pkgDir, { recursive: true })
fs.writeFileSync(
path.join(pkgDir, 'package.json'),
JSON.stringify({ name: path.basename(pkg) })
)
if (version) installNextIsolated(testProjectDir, pkgDir, version)
}
}
function output() {
// Package names are colored; strip ANSI so FORCE_COLOR doesn't matter.
return require('strip-ansi')(consoleOutput.join('\n'))
}
it('uses the bundled docs of a workspace package when run from the root', async () => {
setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
process.chdir(testProjectDir)
await runAgentsMd({ output: 'AGENTS.md' })
const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
expect(readIndex(agentsMdPath).root).toBe(
'./apps/web/node_modules/next/dist/docs'
)
expect(
fs.existsSync(path.join(resolveRoot(agentsMdPath), '01-app'))
).toBe(true)
expect(pullDocsSpy).not.toHaveBeenCalled()
expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
false
)
expect(fs.existsSync(path.join(testProjectDir, '.gitignore'))).toBe(
false
)
expect(output()).toContain('workspace package apps/web')
})
it('indexes the package with the highest Next.js version', async () => {
setupWorkspace(['apps/a', 'apps/b'], {
'apps/a': '16.3.0',
'apps/b': '16.4.0',
})
process.chdir(testProjectDir)
await runAgentsMd({ output: 'AGENTS.md' })
const { root, content } = readIndex(
path.join(testProjectDir, 'AGENTS.md')
)
expect(root).toBe('./apps/b/node_modules/next/dist/docs')
expect(content).toContain('docs-16.4.0.md')
expect(pullDocsSpy).not.toHaveBeenCalled()
})
it('picks the first matching package in workspace order and logs it', async () => {
// Listed b before a, so the choice follows the workspace patterns
// rather than alphabetical order.
setupWorkspace(['apps/b', 'apps/a'], {
'apps/a': '16.4.0',
'apps/b': '16.4.0',
})
process.chdir(testProjectDir)
await runAgentsMd({ output: 'AGENTS.md' })
expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
'./apps/b/node_modules/next/dist/docs'
)
expect(output()).toContain('workspace package apps/b')
expect(output()).not.toContain('workspace package apps/a')
})
it('prefers a matching install resolved from the cwd', async () => {
setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
writeBundledNextPackage(
path.join(testProjectDir, 'node_modules', 'next'),
'16.4.0'
)
process.chdir(testProjectDir)
await runAgentsMd({ output: 'AGENTS.md' })
expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
'./node_modules/next/dist/docs'
)
expect(output()).not.toContain('workspace package')
})
it('uses a workspace package matching --version when the cwd resolves another version', async () => {
setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
writeBundledNextPackage(
path.join(testProjectDir, 'node_modules', 'next'),
'16.3.0'
)
process.chdir(testProjectDir)
await runAgentsMd({ version: '16.4.0', output: 'AGENTS.md' })
const { root, content } = readIndex(
path.join(testProjectDir, 'AGENTS.md')
)
expect(root).toBe('./apps/web/node_modules/next/dist/docs')
expect(content).toContain('docs-16.4.0.md')
expect(pullDocsSpy).not.toHaveBeenCalled()
})
it('still downloads when no workspace package has matching bundled docs', async () => {
setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
process.chdir(testProjectDir)
await runAgentsMd({ version: '15.0.0', output: 'AGENTS.md' })
expect(pullDocsSpy).toHaveBeenCalled()
expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
'./.next-docs'
)
expect(output()).not.toContain('workspace package')
})
})
}) })
describe('getNextjsVersion', () => { describe('getNextjsVersion', () => {
......
...@@ -94,19 +94,48 @@ interface BundledDocsInfo { ...@@ -94,19 +94,48 @@ interface BundledDocsInfo {
/** /**
* Next.js ships its documentation inside the published package (at * Next.js ships its documentation inside the published package (at
* `dist/docs`) since 16.2.0. When the install resolved from `cwd` has * `dist/docs`) since 16.2.0. When an installed `next` of the requested
* bundled docs, the index can point at them directly instead of * `version` has bundled docs, the index can point at them directly instead
* downloading a copy into `.next-docs`. * of downloading a copy into `.next-docs`.
*
* The install resolved from `cwd` wins; otherwise the workspace packages are
* searched.
*/ */
export function getBundledDocsInfo(cwd: string): BundledDocsInfo | null { export function getBundledDocsInfo(
cwd: string,
version: string
): BundledDocsInfo | null {
const fromCwd = getBundledDocsInfoFrom(cwd)
if (fromCwd?.version === version) {
return fromCwd
}
// Mirror getNextjsVersion: with isolated installs (pnpm), `next` is often
// only resolvable from the workspace package that depends on it, not from
// the repo root. Use the first package, in workspace order, that ships
// bundled docs for the requested version.
const workspace = detectWorkspace(cwd)
if (workspace.isMonorepo) {
for (const pkgPath of expandWorkspacePatterns(cwd, workspace.packages)) {
const info = getBundledDocsInfoFrom(pkgPath)
if (info?.version === version) {
return info
}
}
}
return null
}
function getBundledDocsInfoFrom(dir: string): BundledDocsInfo | null {
try { try {
const nextPkgPath = require.resolve('next/package.json', { paths: [cwd] }) const nextPkgPath = require.resolve('next/package.json', { paths: [dir] })
const pkg = JSON.parse(fs.readFileSync(nextPkgPath, 'utf-8')) const pkg = JSON.parse(fs.readFileSync(nextPkgPath, 'utf-8'))
const docsPath = path.join(path.dirname(nextPkgPath), 'dist', 'docs') const docsPath = path.join(path.dirname(nextPkgPath), 'dist', 'docs')
if (!pkg.version || collectDocFiles(docsPath).length === 0) { if (!pkg.version || collectDocFiles(docsPath).length === 0) {
return null return null
} }
return { docsPath, version: pkg.version, resolvedFrom: cwd } return { docsPath, version: pkg.version, resolvedFrom: dir }
} catch { } catch {
return null return null
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment