Skip to content

Commit 385ca0f

Browse files
machtymachty
authored
docs: clean up and document createLanguageServicePlugin and createAsyncLanguageServicePlugin (#261)
1 parent 59d2177 commit 385ca0f

File tree

6 files changed

+274
-218
lines changed

6 files changed

+274
-218
lines changed

‎packages/language-core/lib/types.ts‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,17 +56,44 @@ export interface VirtualCode {
5656
linkedCodeMappings?: Mapping[];
5757
}
5858

59+
/**
60+
* CodeInformation is a configuration object attached to each CodeMapping (between source code and generated code,
61+
* e.g. between the template code in a .vue file and the type-checkable TS code generated from it) that
62+
* determines what code/language features are expected to be available for the mapping.
63+
*
64+
* Due to the dynamic nature of code generation and the fact that, for example, things like Code Actions
65+
* and auto-complete shouldn't be triggerable on certain "in-between" regions of generated code, we need
66+
* a way to shut off certain features in certain regions, while leaving them enabled in others.
67+
*/
5968
export interface CodeInformation {
60-
/** virtual code is expected to support verification */
69+
/** virtual code is expected to support verification, where verification includes:
70+
*
71+
* - diagnostics (syntactic, semantic, and others, such as those generated by the TypeScript language service on generated TS code)
72+
* - code actions (refactorings, quick fixes,etc.)
73+
*/
6174
verification?: boolean | {
75+
/**
76+
* when present, `shouldReport` callback is invoked to determine whether a diagnostic
77+
* raised in the generated code should be propagated back to the original source code.
78+
* Note that when this callback is present, diagnostic processing (e.g. typechecking) will
79+
* still be performed, but the results will not be reported back to the original source code. */
6280
shouldReport?(source: string | undefined, code: string | number | undefined): boolean;
6381
};
6482
/** virtual code is expected to support assisted completion */
6583
completion?: boolean | {
6684
isAdditional?: boolean;
6785
onlyImport?: boolean;
6886
};
69-
/** virtual code is expected correctly reflect semantic of the source code */
87+
/** virtual code is expected correctly reflect semantic of the source code. Specifically this controls the following langauge features:
88+
*
89+
* - hover
90+
* - inlay hints
91+
* - code lens
92+
* - semantic tokens
93+
* - others
94+
*
95+
* Note that semantic diagnostics (e.g. TS type-checking) are covered by the `verification` property above.
96+
*/
7097
semantic?: boolean | {
7198
shouldHighlight?(): boolean;
7299
};

‎packages/typescript/lib/node/proxyLanguageService.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,18 @@ import { getServiceScript } from './utils';
3838

3939
const windowsPathReg = /\\/g;
4040

41+
/**
42+
* Creates and returns a Proxy around the base TypeScript LanguageService.
43+
*
44+
* This is used by the Volar TypeScript Plugin (which can be created by `createLanguageServicePlugin`
45+
* and `createAsyncLanguageServicePlugin`) as an adapter layer between the TypeScript Language Service
46+
* plugin API (see https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin)
47+
* and a Volar `Language`.
48+
*
49+
* Once the `initialize` method is called, the proxy will begin intercepting requests and
50+
* enhancing the default behavior of the LanguageService with enhancements based on
51+
* the Volar `Language` that has been passed to `initialize`.
52+
*/
4153
export function createProxyLanguageService(languageService: ts.LanguageService) {
4254
const proxyCache = new Map<string | symbol, Function | undefined>();
4355
let getProxyMethod: ((target: ts.LanguageService, p: string | symbol) => Function | undefined) | undefined;

‎packages/typescript/lib/node/transform.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ import { getServiceScript } from './utils';
88
const transformedDiagnostics = new WeakMap<ts.Diagnostic, ts.Diagnostic | undefined>();
99
const transformedSourceFile = new WeakSet<ts.SourceFile>();
1010

11+
/**
12+
* This file contains a number of facilities for transforming `ts.Diagnostic`s returned
13+
* from the base TypeScript LanguageService, which reference locations in generated
14+
* TS code (e.g. the TypeScript codegen'd from the script portion of a .vue file) into locations
15+
* in the script portion of the .vue file.
16+
*/
1117
export function transformCallHierarchyItem(
1218
language: Language<string>,
1319
item: ts.CallHierarchyItem,

‎packages/typescript/lib/quickstart/createAsyncLanguageServicePlugin.ts‎

Lines changed: 92 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,121 @@
1-
import { FileMap, Language, LanguagePlugin, createLanguage } from '@volar/language-core';
21
import type * as ts from 'typescript';
3-
import { resolveFileLanguageId } from '../common';
42
import { createProxyLanguageService } from '../node/proxyLanguageService';
5-
import { decorateLanguageServiceHost, searchExternalFiles } from '../node/decorateLanguageServiceHost';
6-
import { arrayItemsEqual, decoratedLanguageServiceHosts, decoratedLanguageServices, externalFiles } from './createLanguageServicePlugin';
3+
import { createLanguageCommon, isHasAlreadyDecoratedLanguageService, makeGetExternalFiles, makeGetScriptInfoWithLargeFileFailsafe } from './languageServicePluginCommon';
4+
import type { createPluginCallbackAsync } from './languageServicePluginCommon';
75

6+
/**
7+
* Creates and returns a TS Service Plugin that supports async initialization.
8+
* Essentially, this functions the same as `createLanguageServicePlugin`, but supports
9+
* use cases in which the plugin callback must be async. For example in mdx-analyzer
10+
* and Glint, this async variant is required because Glint + mdx-analyzer are written
11+
* in ESM and get transpiled to CJS, which requires usage of `await import()` to load
12+
* the necessary dependencies and fully initialize the plugin.
13+
*
14+
* To handle the period of time in which the plugin is initializing, this async
15+
* variant stubs a number of methods on the LanguageServiceHost to handle the uninitialized state.
16+
*
17+
* Additionally, this async variant requires a few extra args pertaining to
18+
* file extensions intended to be handled by the TS Plugin. In the synchronous variant,
19+
* these can be synchronously inferred from elsewhere but for the async variant, they
20+
* need to be passed in.
21+
*
22+
* See https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin for
23+
* more information.
24+
*/
825
export function createAsyncLanguageServicePlugin(
926
extensions: string[],
1027
getScriptKindForExtraExtensions: ts.ScriptKind | ((fileName: string) => ts.ScriptKind),
11-
create: (
12-
ts: typeof import('typescript'),
13-
info: ts.server.PluginCreateInfo
14-
) => Promise<{
15-
languagePlugins: LanguagePlugin<string>[],
16-
setup?: (language: Language<string>) => void;
17-
}>
28+
createPluginCallbackAsync: createPluginCallbackAsync
1829
): ts.server.PluginModuleFactory {
1930
return modules => {
2031
const { typescript: ts } = modules;
32+
2133
const pluginModule: ts.server.PluginModule = {
2234
create(info) {
23-
if (
24-
!decoratedLanguageServices.has(info.languageService)
25-
&& !decoratedLanguageServiceHosts.has(info.languageServiceHost)
26-
) {
27-
decoratedLanguageServices.add(info.languageService);
28-
decoratedLanguageServiceHosts.add(info.languageServiceHost);
29-
30-
const emptySnapshot = ts.ScriptSnapshot.fromString('');
31-
const getScriptSnapshot = info.languageServiceHost.getScriptSnapshot.bind(info.languageServiceHost);
32-
const getScriptVersion = info.languageServiceHost.getScriptVersion.bind(info.languageServiceHost);
33-
const getScriptKind = info.languageServiceHost.getScriptKind?.bind(info.languageServiceHost);
34-
const getProjectVersion = info.languageServiceHost.getProjectVersion?.bind(info.languageServiceHost);
35-
36-
let initialized = false;
37-
38-
info.languageServiceHost.getScriptSnapshot = fileName => {
39-
if (!initialized) {
40-
if (extensions.some(ext => fileName.endsWith(ext))) {
41-
return emptySnapshot;
42-
}
43-
if (getScriptInfo(fileName)?.isScriptOpen()) {
44-
return emptySnapshot;
45-
}
46-
}
47-
return getScriptSnapshot(fileName);
48-
};
49-
info.languageServiceHost.getScriptVersion = fileName => {
50-
if (!initialized) {
51-
if (extensions.some(ext => fileName.endsWith(ext))) {
52-
return 'initializing...';
53-
}
54-
if (getScriptInfo(fileName)?.isScriptOpen()) {
55-
return getScriptVersion(fileName) + ',initializing...';
56-
}
57-
}
58-
return getScriptVersion(fileName);
59-
};
60-
if (getScriptKind) {
61-
info.languageServiceHost.getScriptKind = fileName => {
62-
if (!initialized && extensions.some(ext => fileName.endsWith(ext))) {
63-
// bypass upstream bug https://github.com/microsoft/TypeScript/issues/57631
64-
// TODO: check if the bug is fixed in 5.5
65-
if (typeof getScriptKindForExtraExtensions === 'function') {
66-
return getScriptKindForExtraExtensions(fileName);
67-
}
68-
else {
69-
return getScriptKindForExtraExtensions;
70-
}
71-
}
72-
return getScriptKind(fileName);
73-
};
74-
}
75-
if (getProjectVersion) {
76-
info.languageServiceHost.getProjectVersion = () => {
77-
if (!initialized) {
78-
return getProjectVersion() + ',initializing...';
79-
}
80-
return getProjectVersion();
81-
};
82-
}
35+
if (!isHasAlreadyDecoratedLanguageService(info)) {
36+
const state = decorateWithAsyncInitializationHandling(ts, info, extensions, getScriptKindForExtraExtensions);
8337

8438
const { proxy, initialize } = createProxyLanguageService(info.languageService);
8539
info.languageService = proxy;
8640

87-
create(ts, info).then(({ languagePlugins, setup }) => {
88-
const language = createLanguage<string>(
89-
[
90-
...languagePlugins,
91-
{ getLanguageId: resolveFileLanguageId },
92-
],
93-
new FileMap(ts.sys.useCaseSensitiveFileNames),
94-
(fileName, _, shouldRegister) => {
95-
let snapshot: ts.IScriptSnapshot | undefined;
96-
if (shouldRegister) {
97-
// We need to trigger registration of the script file with the project, see #250
98-
snapshot = getScriptSnapshot(fileName);
99-
}
100-
else {
101-
snapshot = getScriptInfo(fileName)?.getSnapshot();
102-
if (!snapshot) {
103-
// trigger projectService.getOrCreateScriptInfoNotOpenedByClient
104-
info.project.getScriptVersion(fileName);
105-
snapshot = getScriptInfo(fileName)?.getSnapshot();
106-
}
107-
}
108-
if (snapshot) {
109-
language.scripts.set(fileName, snapshot);
110-
}
111-
else {
112-
language.scripts.delete(fileName);
113-
}
114-
}
115-
);
41+
createPluginCallbackAsync(ts, info).then((createPluginResult) => {
42+
createLanguageCommon(createPluginResult, ts, info, initialize);
11643

117-
initialize(language);
118-
decorateLanguageServiceHost(ts, language, info.languageServiceHost);
119-
setup?.(language);
44+
state.initialized = true;
12045

121-
initialized = true;
12246
if ('markAsDirty' in info.project && typeof info.project.markAsDirty === 'function') {
47+
// This is an attempt to mark the project as dirty so that in case the IDE/tsserver
48+
// already finished a first pass of generating diagnostics (or other things), another
49+
// pass will be triggered which should hopefully make use of this now-initialized plugin.
12350
info.project.markAsDirty();
12451
}
12552
});
12653
}
12754

12855
return info.languageService;
129-
130-
function getScriptInfo(fileName: string) {
131-
// getSnapshot could be crashed if the file is too large
132-
try {
133-
return info.project.getScriptInfo(fileName);
134-
} catch { }
135-
}
136-
},
137-
getExternalFiles(project, updateLevel = 0) {
138-
if (
139-
updateLevel >= (1 satisfies ts.ProgramUpdateLevel.RootNamesAndUpdate)
140-
|| !externalFiles.has(project)
141-
) {
142-
const oldFiles = externalFiles.get(project);
143-
const newFiles = extensions.length ? searchExternalFiles(ts, project, extensions) : [];
144-
externalFiles.set(project, newFiles);
145-
if (oldFiles && !arrayItemsEqual(oldFiles, newFiles)) {
146-
project.refreshDiagnostics();
147-
}
148-
}
149-
return externalFiles.get(project)!;
15056
},
57+
getExternalFiles: makeGetExternalFiles(ts),
15158
};
15259
return pluginModule;
15360
};
15461
}
62+
63+
function decorateWithAsyncInitializationHandling(ts: typeof import('typescript'), info: ts.server.PluginCreateInfo, extensions: string[], getScriptKindForExtraExtensions: ts.ScriptKind | ((fileName: string) => ts.ScriptKind)) {
64+
const emptySnapshot = ts.ScriptSnapshot.fromString('');
65+
const getScriptSnapshot = info.languageServiceHost.getScriptSnapshot.bind(info.languageServiceHost);
66+
const getScriptVersion = info.languageServiceHost.getScriptVersion.bind(info.languageServiceHost);
67+
const getScriptKind = info.languageServiceHost.getScriptKind?.bind(info.languageServiceHost);
68+
const getProjectVersion = info.languageServiceHost.getProjectVersion?.bind(info.languageServiceHost);
69+
70+
const getScriptInfo = makeGetScriptInfoWithLargeFileFailsafe(info);
71+
72+
const state = { initialized: false };
73+
74+
info.languageServiceHost.getScriptSnapshot = fileName => {
75+
if (!state.initialized) {
76+
if (extensions.some(ext => fileName.endsWith(ext))) {
77+
return emptySnapshot;
78+
}
79+
if (getScriptInfo(fileName)?.isScriptOpen()) {
80+
return emptySnapshot;
81+
}
82+
}
83+
return getScriptSnapshot(fileName);
84+
};
85+
info.languageServiceHost.getScriptVersion = fileName => {
86+
if (!state.initialized) {
87+
if (extensions.some(ext => fileName.endsWith(ext))) {
88+
return 'initializing...';
89+
}
90+
if (getScriptInfo(fileName)?.isScriptOpen()) {
91+
return getScriptVersion(fileName) + ',initializing...';
92+
}
93+
}
94+
return getScriptVersion(fileName);
95+
};
96+
if (getScriptKind) {
97+
info.languageServiceHost.getScriptKind = fileName => {
98+
if (!state.initialized && extensions.some(ext => fileName.endsWith(ext))) {
99+
// bypass upstream bug https://github.com/microsoft/TypeScript/issues/57631
100+
// TODO: check if the bug is fixed in 5.5
101+
if (typeof getScriptKindForExtraExtensions === 'function') {
102+
return getScriptKindForExtraExtensions(fileName);
103+
}
104+
else {
105+
return getScriptKindForExtraExtensions;
106+
}
107+
}
108+
return getScriptKind(fileName);
109+
};
110+
}
111+
if (getProjectVersion) {
112+
info.languageServiceHost.getProjectVersion = () => {
113+
if (!state.initialized) {
114+
return getProjectVersion() + ',initializing...';
115+
}
116+
return getProjectVersion();
117+
};
118+
}
119+
120+
return state;
121+
}

0 commit comments

Comments
 (0)