Unverified Commit 26824378 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

[ts-plugin] Preserve TypeScript quick info metadata (#95863)

### Why?

VS Code passes a maximum hover length and verbosity level to
TypeScript's `getQuickInfoAtPosition` API when a user expands a hover.
The Next.js TypeScript plugin intercepted that call and forwarded the
file name and position, dropping the remaining arguments. The plugin
also replaced TypeScript's `QuickInfo` object when it added config
documentation, which discarded native fields such as
`canIncreaseVerbosityLevel`. As a result, hovers for Next.js config
exports could not expand and lost native type information.

This supersedes #86290 with a narrower behavior change. The plugin
preserves native `QuickInfo` when it adds documentation to valid config
values and config identifiers. Invalid config values keep the existing
synthesized override, and hovers inside function initializers retain
TypeScript's existing behavior.

x-ref:
https://github.com/microsoft/vscode/issues/232685#issuecomment-3484167019

| Before | After |
|--------|-------|
| <img width="1656" height="390" alt="Config hover without expandable
metadata"
src="https://github.com/user-attachments/assets/ed39a851-7096-448b-bffe-55c5320c1713"
/> | <img width="1668" height="384" alt="Config hover with expandable
metadata"
src="https://github.com/user-attachments/assets/0a3a0cbc-5c75-4b6f-90fc-bbcef028d06b"
/> |

### How?

The plugin forwards all QuickInfo arguments to TypeScript and passes the
native result into the config hover rules. For valid config values and
identifiers, those rules copy the native `QuickInfo` fields and append
the Next.js documentation. They synthesize the existing fallback when
TypeScript returns no QuickInfo.

Focused tests cover argument forwarding, metadata preservation, missing
native QuickInfo, invalid config values, and function config boundaries.

### Test plan

Open a minimal Next.js app in Cursor with workspace TypeScript 6.0.2 and
the package built from this PR. Hover `export const metadata: Metadata`,
then select the expansion control. The hover expands from `Metadata` to
its full property type while the Next.js config documentation and link
remain visible.

<!-- NEXT_JS_LLM -->
parent 29b39663
...@@ -135,11 +135,18 @@ export const createTSPlugin: tsModule.server.PluginModuleFactory = ({ ...@@ -135,11 +135,18 @@ export const createTSPlugin: tsModule.server.PluginModuleFactory = ({
} }
// Quick info // Quick info
proxy.getQuickInfoAtPosition = (fileName: string, position: number) => { proxy.getQuickInfoAtPosition = (
const prior = info.languageService.getQuickInfoAtPosition( fileName: string,
fileName, position: number,
position ...args: any[]
) ) => {
const prior = (
info.languageService.getQuickInfoAtPosition as (
fileName: string,
position: number,
...args: any[]
) => tsModule.QuickInfo | undefined
)(fileName, position, ...args)
if (!isAppEntryFile(fileName)) return prior if (!isAppEntryFile(fileName)) return prior
// Remove type suggestions for disallowed APIs in server components. // Remove type suggestions for disallowed APIs in server components.
...@@ -157,7 +164,11 @@ export const createTSPlugin: tsModule.server.PluginModuleFactory = ({ ...@@ -157,7 +164,11 @@ export const createTSPlugin: tsModule.server.PluginModuleFactory = ({
} }
} }
const overridden = entryConfig.getQuickInfoAtPosition(fileName, position) const overridden = entryConfig.getQuickInfoAtPosition(
fileName,
position,
prior
)
if (overridden) return overridden if (overridden) return overridden
return prior return prior
......
...@@ -321,7 +321,11 @@ const config = { ...@@ -321,7 +321,11 @@ const config = {
}, },
// Show docs when hovering on the exported configs. // Show docs when hovering on the exported configs.
getQuickInfoAtPosition(fileName: string, position: number) { getQuickInfoAtPosition(
fileName: string,
position: number,
prior?: tsModule.QuickInfo
) {
const ts = getTs() const ts = getTs()
let overridden: tsModule.QuickInfo | undefined let overridden: tsModule.QuickInfo | undefined
...@@ -389,25 +393,30 @@ const config = { ...@@ -389,25 +393,30 @@ const config = {
: !!API_DOCS[entryConfig].options?.[key] : !!API_DOCS[entryConfig].options?.[key]
if (isValid) { if (isValid) {
overridden = { const documentation: tsModule.SymbolDisplayPart[] = [
kind: ts.ScriptElementKind.enumElement, ...(prior?.documentation || []),
kindModifiers: ts.ScriptElementKindModifier.none, {
textSpan: { kind: 'text',
start: value.getStart(), text:
length: value.getWidth(), API_DOCS[entryConfig].options?.[key] ||
API_DOCS[entryConfig].getHint?.(key) ||
'',
}, },
displayParts: [], docsLink,
documentation: [ ]
{
kind: 'text', overridden = prior
text: ? { ...prior, documentation }
API_DOCS[entryConfig].options?.[key] || : {
API_DOCS[entryConfig].getHint?.(key) || kind: ts.ScriptElementKind.enumElement,
'', kindModifiers: ts.ScriptElementKindModifier.none,
}, textSpan: {
docsLink, start: value.getStart(),
], length: value.getWidth(),
} },
displayParts: [],
documentation,
}
} else { } else {
// Wrong value: still show the docs link, and when available, the // Wrong value: still show the docs link, and when available, the
// inferred type for non-literal (i.e. non-direct) exports. // inferred type for non-literal (i.e. non-direct) exports.
...@@ -436,22 +445,27 @@ const config = { ...@@ -436,22 +445,27 @@ const config = {
return return
} }
// Hovers the name of the config // Hovers the name of the config
overridden = { const documentation: tsModule.SymbolDisplayPart[] = [
kind: ts.ScriptElementKind.enumElement, ...(prior?.documentation || []),
kindModifiers: ts.ScriptElementKindModifier.none, {
textSpan: { kind: 'text',
start: name.getStart(), text: getAPIDescription(entryConfig),
length: name.getWidth(),
}, },
displayParts, docsLink,
documentation: [ ]
{
kind: 'text', overridden = prior
text: getAPIDescription(entryConfig), ? { ...prior, documentation }
}, : {
docsLink, kind: ts.ScriptElementKind.enumElement,
], kindModifiers: ts.ScriptElementKindModifier.none,
} textSpan: {
start: name.getStart(),
length: name.getWidth(),
},
displayParts,
documentation,
}
} }
}) })
return overridden return overridden
......
export const dynamic = 'force-static'
export const dynamicParams = true
export const runtime = 'invalid-runtime'
export const generateMetadata = async () => {
const metadataTitle = 'Expandable hover'
return { title: metadataTitle }
}
export default function Page() {
return null
}
import type { PluginLanguageService } from './test-utils' import { readFileSync } from 'node:fs'
import { getPluginLanguageService } from './test-utils' import { join } from 'node:path'
import ts from 'typescript'
import type { PluginLanguageService, QuickInfoTestAdapter } from './test-utils'
import { getQuickInfoTestAdapter } from './test-utils'
const nativeDocumentation = 'Native quick info documentation.'
const quickInfoFile = join(__dirname, 'app/quick-info/page.tsx')
const quickInfoSource = readFileSync(quickInfoFile, 'utf8')
function positionOf(text: string, occurrence = 0) {
let position = -1
for (let index = 0; index <= occurrence; index++) {
position = quickInfoSource.indexOf(text, position + 1)
}
if (position === -1) {
throw new Error(`Could not find quick info fixture text: ${text}`)
}
return position
}
function documentationText(quickInfo: ts.QuickInfo | undefined) {
return quickInfo?.documentation?.map((part) => part.text) || []
}
const noNativeQuickInfoPosition = positionOf('true')
describe('typescript-plugin', () => { describe('typescript-plugin', () => {
let languageService: PluginLanguageService let languageService: PluginLanguageService
let quickInfo: QuickInfoTestAdapter
beforeAll(() => { beforeAll(() => {
languageService = getPluginLanguageService(__dirname) quickInfo = getQuickInfoTestAdapter(__dirname, (prior, args) => {
if (args[1] === noNativeQuickInfoPosition) return
const nativeQuickInfo: ts.QuickInfo = prior || {
kind: ts.ScriptElementKind.unknown,
kindModifiers: ts.ScriptElementKindModifier.none,
textSpan: { start: args[1], length: 1 },
displayParts: [],
}
return {
...nativeQuickInfo,
canIncreaseVerbosityLevel: true,
documentation: [
{ kind: 'text', text: nativeDocumentation },
...(nativeQuickInfo.documentation || []),
],
}
})
languageService = quickInfo.languageService
}) })
it('should be able to get the language service', () => { it('should be able to get the language service', () => {
...@@ -15,4 +59,105 @@ describe('typescript-plugin', () => { ...@@ -15,4 +59,105 @@ describe('typescript-plugin', () => {
'[next] Initialized Next.js TypeScript plugin' '[next] Initialized Next.js TypeScript plugin'
) )
}) })
it('forwards all quick info arguments and preserves native fields for valid config values', () => {
const position = positionOf("'force-static'") + 1
const result = quickInfo.getQuickInfoAtPosition(
quickInfoFile,
position,
120,
2
)
expect(quickInfo.getCapturedQuickInfoArgs()).toEqual([
quickInfoFile,
position,
120,
2,
])
expect(result?.canIncreaseVerbosityLevel).toBe(true)
const documentation = documentationText(result)
expect(documentation[0]).toBe(nativeDocumentation)
expect(documentation.slice(1).join(' ')).toContain(
'forces caching of all fetches'
)
expect(documentation.slice(1).join(' ')).toContain(
'Read more about the "dynamic" option'
)
})
it('preserves native fields and appends Next.js docs for config names', () => {
const result = quickInfo.getQuickInfoAtPosition(
quickInfoFile,
positionOf('dynamic')
)
expect(result?.canIncreaseVerbosityLevel).toBe(true)
const documentation = documentationText(result)
expect(documentation[0]).toBe(nativeDocumentation)
expect(documentation.slice(1).join(' ')).toContain(
'The `dynamic` option provides'
)
expect(documentation.slice(1).join(' ')).toContain(
'Read more about the "dynamic" option'
)
})
it('keeps synthesized quick info when TypeScript has none', () => {
const result = quickInfo.getQuickInfoAtPosition(
quickInfoFile,
noNativeQuickInfoPosition
)
expect(result?.kind).toBe(ts.ScriptElementKind.enumElement)
expect(result?.canIncreaseVerbosityLevel).toBeUndefined()
expect(documentationText(result).join(' ')).toContain(
'Allow rendering dynamic params'
)
})
it('keeps the synthesized override for invalid config values', () => {
const position = positionOf("'invalid-runtime'") + 1
const result = quickInfo.getQuickInfoAtPosition(quickInfoFile, position)
expect(result?.kind).toBe(ts.ScriptElementKind.enumElement)
expect(result?.textSpan).toEqual({
start: position - 1,
length: "'invalid-runtime'".length,
})
expect(result?.canIncreaseVerbosityLevel).toBeUndefined()
const documentation = documentationText(result)
expect(documentation.includes(nativeDocumentation)).toBe(false)
expect(documentation.join(' ')).toContain(
'Read more about the "runtime" option'
)
})
it('keeps native quick info inside function config initializers', () => {
const result = quickInfo.getQuickInfoAtPosition(
quickInfoFile,
positionOf('metadataTitle', 1)
)
expect(result?.canIncreaseVerbosityLevel).toBe(true)
expect(documentationText(result)).toEqual([nativeDocumentation])
})
it('enhances the function config identifier', () => {
const result = quickInfo.getQuickInfoAtPosition(
quickInfoFile,
positionOf('generateMetadata')
)
expect(result?.canIncreaseVerbosityLevel).toBe(true)
const documentation = documentationText(result)
expect(documentation[0]).toBe(nativeDocumentation)
expect(documentation.slice(1).join(' ')).toContain(
'Next.js generateMetadata configurations'
)
})
}) })
...@@ -6,7 +6,35 @@ export type PluginLanguageService = ts.LanguageService & { ...@@ -6,7 +6,35 @@ export type PluginLanguageService = ts.LanguageService & {
getCapturedLogs: () => string getCapturedLogs: () => string
} }
export function getPluginLanguageService(dir: string): PluginLanguageService { export type QuickInfoAtPositionArgs = [
fileName: string,
position: number,
maximumLength?: number,
verbosityLevel?: number,
]
type RuntimeQuickInfoAtPosition = (
...args: QuickInfoAtPositionArgs
) => ts.QuickInfo | undefined
export type QuickInfoTestAdapter = {
languageService: PluginLanguageService
getQuickInfoAtPosition: RuntimeQuickInfoAtPosition
getCapturedQuickInfoArgs: () => QuickInfoAtPositionArgs | undefined
}
type QuickInfoInterceptor = {
capture: (args: QuickInfoAtPositionArgs) => void
transform: (
quickInfo: ts.QuickInfo | undefined,
args: QuickInfoAtPositionArgs
) => ts.QuickInfo | undefined
}
function createPluginLanguageService(
dir: string,
quickInfoInterceptor?: QuickInfoInterceptor
): PluginLanguageService {
const files = ts.sys.readDirectory(dir) const files = ts.sys.readDirectory(dir)
const compilerOptions = ts.getDefaultCompilerOptions() const compilerOptions = ts.getDefaultCompilerOptions()
...@@ -40,6 +68,18 @@ export function getPluginLanguageService(dir: string): PluginLanguageService { ...@@ -40,6 +68,18 @@ export function getPluginLanguageService(dir: string): PluginLanguageService {
const languageService = ts.createLanguageService(languageServiceHost) const languageService = ts.createLanguageService(languageServiceHost)
if (quickInfoInterceptor) {
const getQuickInfoAtPosition = languageService.getQuickInfoAtPosition.bind(
languageService
) as RuntimeQuickInfoAtPosition
languageService.getQuickInfoAtPosition = ((...args) => {
quickInfoInterceptor.capture(args)
const quickInfo = getQuickInfoAtPosition(...args)
return quickInfoInterceptor.transform(quickInfo, args)
}) as ts.LanguageService['getQuickInfoAtPosition']
}
const pluginCreateInfo: ts.server.PluginCreateInfo = { const pluginCreateInfo: ts.server.PluginCreateInfo = {
project: { project: {
projectService: { projectService: {
...@@ -65,6 +105,33 @@ export function getPluginLanguageService(dir: string): PluginLanguageService { ...@@ -65,6 +105,33 @@ export function getPluginLanguageService(dir: string): PluginLanguageService {
return service return service
} }
export function getPluginLanguageService(dir: string): PluginLanguageService {
return createPluginLanguageService(dir)
}
export function getQuickInfoTestAdapter(
dir: string,
transform: QuickInfoInterceptor['transform']
): QuickInfoTestAdapter {
let capturedQuickInfoArgs: QuickInfoAtPositionArgs | undefined
const languageService = createPluginLanguageService(dir, {
capture: (args) => {
capturedQuickInfoArgs = [...args]
},
transform,
})
const getQuickInfoAtPosition = languageService.getQuickInfoAtPosition.bind(
languageService
) as RuntimeQuickInfoAtPosition
return {
languageService,
getQuickInfoAtPosition,
getCapturedQuickInfoArgs: () => capturedQuickInfoArgs,
}
}
export function getTsFiles(dir: string): string[] { export function getTsFiles(dir: string): string[] {
return ts.sys.readDirectory(dir) return ts.sys.readDirectory(dir)
} }
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