0
# Extended Features
1

2
Advanced Language Server Protocol features including semantic tokens, call hierarchy, type hierarchy, and diagnostics. These features provide enhanced code intelligence and navigation capabilities.
3

4
## Capabilities
5

6
### Semantic Tokens
7

8
Provides semantic syntax highlighting with detailed token classification and modifiers.
9

10
```typescript { .api }
11
/**
12
 * Semantic tokens feature providing enhanced syntax highlighting
13
 */
14
interface SemanticTokensFeatureShape {
15
    semanticTokens: {
16
        /** Refresh semantic tokens in the client */
17
        refresh(): void;
18
        /** Register handler for semantic tokens requests */
19
        on(handler: ServerRequestHandler<SemanticTokensParams, SemanticTokens, SemanticTokensPartialResult, void>): Disposable;
20
        /** Register handler for semantic tokens delta requests */
21
        onDelta(handler: ServerRequestHandler<SemanticTokensDeltaParams, SemanticTokensDelta | SemanticTokens, SemanticTokensDeltaPartialResult | SemanticTokensPartialResult, void>): Disposable;
22
        /** Register handler for semantic tokens range requests */
23
        onRange(handler: ServerRequestHandler<SemanticTokensRangeParams, SemanticTokens, SemanticTokensPartialResult, void>): Disposable;
24
    };
25
}
26

27
interface SemanticTokensParams extends WorkDoneProgressParams, PartialResultParams {
28
    /** The text document */
29
    textDocument: TextDocumentIdentifier;
30
}
31

32
interface SemanticTokensRangeParams extends WorkDoneProgressParams, PartialResultParams {
33
    /** The text document */
34
    textDocument: TextDocumentIdentifier;
35
    /** The range to tokenize */
36
    range: Range;
37
}
38

39
interface SemanticTokensDeltaParams extends WorkDoneProgressParams, PartialResultParams {
40
    /** The text document */
41
    textDocument: TextDocumentIdentifier;
42
    /** The result id of a previous response */
43
    previousResultId: string;
44
}
45

46
interface SemanticTokens {
47
    /** An optional result id */
48
    resultId?: string;
49
    /** The actual tokens */
50
    data: number[];
51
}
52

53
interface SemanticTokensPartialResult {
54
    data: number[];
55
}
56

57
interface SemanticTokensDelta {
58
    /** An optional result id */
59
    resultId?: string;
60
    /** The semantic token edits to transform a previous result into a new result */
61
    edits: SemanticTokensEdit[];
62
}
63

64
interface SemanticTokensEdit {
65
    /** The start offset of the edit */
66
    start: number;
67
    /** The count of elements to remove */
68
    deleteCount: number;
69
    /** The elements to insert */
70
    data?: number[];
71
}
72
```
73

74
**Usage Example:**
75

76
```typescript
77
// Access via connection.languages.semanticTokens
78
connection.languages.semanticTokens.on((params) => {
79
    const document = documents.get(params.textDocument.uri);
80
    if (!document) return null;
81
    
82
    const builder = new SemanticTokensBuilder();
83
    
84
    // Add tokens (line, character, length, tokenType, tokenModifiers)
85
    builder.push(0, 0, 8, TokenTypes.keyword, TokenModifiers.declaration);
86
    builder.push(0, 9, 4, TokenTypes.function, TokenModifiers.definition);
87
    
88
    return builder.build();
89
});
90

91
// Refresh tokens when needed
92
connection.languages.semanticTokens.refresh();
93
```
94

95
### Semantic Tokens Builder
96

97
Helper class for building semantic tokens responses.
98

99
```typescript { .api }
100
/**
101
 * Helper class for building semantic tokens
102
 */
103
class SemanticTokensBuilder {
104
    /** Create a new semantic tokens builder */
105
    constructor();
106
    
107
    /**
108
     * Add a semantic token
109
     * @param line Line number (0-based)
110
     * @param char Character offset on line (0-based)
111
     * @param length Length of the token
112
     * @param tokenType Token type index
113
     * @param tokenModifiers Token modifiers as bit flags
114
     */
115
    push(line: number, char: number, length: number, tokenType: number, tokenModifiers?: number): void;
116
    
117
    /** Build the final semantic tokens */
118
    build(): SemanticTokens;
119
    
120
    /** Build semantic tokens edits */
121
    buildEdits(): SemanticTokensEdits;
122
}
123
```
124

125
### Call Hierarchy
126

127
Provides call hierarchy navigation for functions and methods.
128

129
```typescript { .api }
130
/**
131
 * Call hierarchy feature for navigating function calls
132
 */
133
interface CallHierarchyFeatureShape {
134
    callHierarchy: {
135
        /** Register handler for call hierarchy prepare requests */
136
        onPrepare(handler: ServerRequestHandler<CallHierarchyPrepareParams, CallHierarchyItem[] | null, void>): Disposable;
137
        /** Register handler for incoming calls requests */
138
        onIncomingCalls(handler: ServerRequestHandler<CallHierarchyIncomingCallsParams, CallHierarchyIncomingCall[] | null, void>): Disposable;
139
        /** Register handler for outgoing calls requests */
140
        onOutgoingCalls(handler: ServerRequestHandler<CallHierarchyOutgoingCallsParams, CallHierarchyOutgoingCall[] | null, void>): Disposable;
141
    };
142
}
143

144
interface CallHierarchyPrepareParams extends TextDocumentPositionParams, WorkDoneProgressParams {
145
}
146

147
interface CallHierarchyIncomingCallsParams extends WorkDoneProgressParams, PartialResultParams {
148
    item: CallHierarchyItem;
149
}
150

151
interface CallHierarchyOutgoingCallsParams extends WorkDoneProgressParams, PartialResultParams {
152
    item: CallHierarchyItem;
153
}
154

155
interface CallHierarchyItem {
156
    /** The name of this item */
157
    name: string;
158
    /** The kind of this item */
159
    kind: SymbolKind;
160
    /** Tags for this item */
161
    tags?: SymbolTag[];
162
    /** More detail for this item */
163
    detail?: string;
164
    /** The resource identifier of this item */
165
    uri: DocumentUri;
166
    /** The range enclosing this symbol */
167
    range: Range;
168
    /** The range that should be selected and revealed when this symbol is being picked */
169
    selectionRange: Range;
170
    /** A data entry field that is preserved during call hierarchy prepare and call hierarchy incoming/outgoing calls requests */
171
    data?: any;
172
}
173

174
interface CallHierarchyIncomingCall {
175
    /** The item that makes the call */
176
    from: CallHierarchyItem;
177
    /** The ranges at which the calls appear */
178
    fromRanges: Range[];
179
}
180

181
interface CallHierarchyOutgoingCall {
182
    /** The item that is called */
183
    to: CallHierarchyItem;
184
    /** The range at which this item is called */
185
    fromRanges: Range[];
186
}
187
```
188

189
### Type Hierarchy
190

191
Provides type hierarchy navigation for classes and interfaces.
192

193
```typescript { .api }
194
/**
195
 * Type hierarchy feature for navigating type relationships
196
 */
197
interface TypeHierarchyFeatureShape {
198
    typeHierarchy: {
199
        /** Register handler for type hierarchy prepare requests */
200
        onPrepare(handler: ServerRequestHandler<TypeHierarchyPrepareParams, TypeHierarchyItem[] | null, void>): Disposable;
201
        /** Register handler for supertypes requests */
202
        onSupertypes(handler: ServerRequestHandler<TypeHierarchySupertypesParams, TypeHierarchyItem[] | null, void>): Disposable;
203
        /** Register handler for subtypes requests */
204
        onSubtypes(handler: ServerRequestHandler<TypeHierarchySubtypesParams, TypeHierarchyItem[] | null, void>): Disposable;
205
    };
206
}
207

208
interface TypeHierarchyPrepareParams extends TextDocumentPositionParams, WorkDoneProgressParams {
209
}
210

211
interface TypeHierarchySupertypesParams extends WorkDoneProgressParams, PartialResultParams {
212
    item: TypeHierarchyItem;
213
}
214

215
interface TypeHierarchySubtypesParams extends WorkDoneProgressParams, PartialResultParams {
216
    item: TypeHierarchyItem;
217
}
218

219
interface TypeHierarchyItem {
220
    /** The name of this item */
221
    name: string;
222
    /** The kind of this item */
223
    kind: SymbolKind;
224
    /** Tags for this item */
225
    tags?: SymbolTag[];
226
    /** More detail for this item */
227
    detail?: string;
228
    /** The resource identifier of this item */
229
    uri: DocumentUri;
230
    /** The range enclosing this symbol */
231
    range: Range;
232
    /** The range that should be selected and revealed when this symbol is being picked */
233
    selectionRange: Range;
234
    /** A data entry field that is preserved during type hierarchy prepare and type hierarchy super-/sub-types requests */
235
    data?: any;
236
}
237
```
238

239
### Diagnostics
240

241
Provides pull-based diagnostics for documents and workspace.
242

243
```typescript { .api }
244
/**
245
 * Diagnostics feature for pull-based diagnostic reporting
246
 */
247
interface DiagnosticFeatureShape {
248
    diagnostics: {
249
        /** Register handler for diagnostic requests */
250
        on(handler: ServerRequestHandler<DocumentDiagnosticParams, DocumentDiagnosticReport, DocumentDiagnosticReportPartialResult, void>): Disposable;
251
        /** Refresh diagnostics in the client */
252
        refresh(): void;
253
    };
254
}
255

256
interface DocumentDiagnosticParams extends WorkDoneProgressParams, PartialResultParams {
257
    /** The text document */
258
    textDocument: TextDocumentIdentifier;
259
    /** The additional identifier provided during registration */
260
    identifier?: string;
261
    /** The result id of a previous response if provided */
262
    previousResultId?: string;
263
}
264

265
type DocumentDiagnosticReport = RelatedFullDocumentDiagnosticReport | RelatedUnchangedDocumentDiagnosticReport;
266

267
interface RelatedFullDocumentDiagnosticReport extends FullDocumentDiagnosticReport {
268
    /** Diagnostics of related documents */
269
    relatedDocuments?: { [uri: DocumentUri]: FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport };
270
}
271

272
interface FullDocumentDiagnosticReport {
273
    /** A full document diagnostic report */
274
    kind: 'full';
275
    /** An optional result id */
276
    resultId?: string;
277
    /** The actual items */
278
    items: Diagnostic[];
279
}
280

281
interface UnchangedDocumentDiagnosticReport {
282
    /** A document diagnostic report indicating no changes to the last result */
283
    kind: 'unchanged';
284
    /** A result id which will be sent on the next diagnostic request for the same document */
285
    resultId: string;
286
}
287

288
interface Diagnostic {
289
    /** The range at which the message applies */
290
    range: Range;
291
    /** The diagnostic's severity */
292
    severity?: DiagnosticSeverity;
293
    /** The diagnostic's code */
294
    code?: number | string;
295
    /** An optional property to describe the error code */
296
    codeDescription?: CodeDescription;
297
    /** A human-readable string describing the source of this diagnostic */
298
    source?: string;
299
    /** The diagnostic's message */
300
    message: string;
301
    /** Additional metadata about the diagnostic */
302
    tags?: DiagnosticTag[];
303
    /** An array of related diagnostic information */
304
    relatedInformation?: DiagnosticRelatedInformation[];
305
    /** A data entry field that is preserved during diagnostic resolution */
306
    data?: any;
307
}
308

309
enum DiagnosticSeverity {
310
    Error = 1,
311
    Warning = 2,
312
    Information = 3,
313
    Hint = 4
314
}
315
```
316

317
### Inlay Hints
318

319
Provides inlay hints for parameter names, type annotations, and other inline information.
320

321
```typescript { .api }
322
/**
323
 * Inlay hint feature for inline code annotations
324
 */
325
interface InlayHintFeatureShape {
326
    inlayHint: {
327
        /** Register handler for inlay hint requests */
328
        on(handler: ServerRequestHandler<InlayHintParams, InlayHint[] | null, void>): Disposable;
329
        /** Register handler for inlay hint resolve requests */
330
        onResolve(handler: ServerRequestHandler<InlayHint, InlayHint, void>): Disposable;
331
        /** Refresh inlay hints in the client */
332
        refresh(): void;
333
    };
334
}
335

336
interface InlayHintParams extends WorkDoneProgressParams {
337
    /** The text document */
338
    textDocument: TextDocumentIdentifier;
339
    /** The visible document range for which inlay hints should be computed */
340
    range: Range;
341
}
342

343
interface InlayHint {
344
    /** The position of this hint */
345
    position: Position;
346
    /** The label of this hint */
347
    label: string | InlayHintLabelPart[];
348
    /** The kind of this hint */
349
    kind?: InlayHintKind;
350
    /** Optional text edits that are performed when accepting this inlay hint */
351
    textEdits?: TextEdit[];
352
    /** The tooltip text when you hover over this item */
353
    tooltip?: string | MarkupContent;
354
    /** Render padding before the hint */
355
    paddingLeft?: boolean;
356
    /** Render padding after the hint */
357
    paddingRight?: boolean;
358
    /** A data entry field that is preserved during resolve */
359
    data?: any;
360
}
361

362
interface InlayHintLabelPart {
363
    /** The value of this label part */
364
    value: string;
365
    /** The tooltip text when you hover over this label part */
366
    tooltip?: string | MarkupContent;
367
    /** An optional source code location that represents this label part */
368
    location?: Location;
369
    /** An optional command for this label part */
370
    command?: Command;
371
}
372

373
enum InlayHintKind {
374
    Type = 1,
375
    Parameter = 2
376
}
377
```
378

379
### Inline Values
380

381
Provides inline value information during debugging sessions.
382

383
```typescript { .api }
384
/**
385
 * Inline value feature for debugging support
386
 */
387
interface InlineValueFeatureShape {
388
    inlineValue: {
389
        /** Register handler for inline value requests */
390
        on(handler: ServerRequestHandler<InlineValueParams, InlineValue[] | null, void>): Disposable;
391
        /** Refresh inline values in the client */
392
        refresh(): void;
393
    };
394
}
395

396
interface InlineValueParams extends WorkDoneProgressParams {
397
    /** The text document */
398
    textDocument: TextDocumentIdentifier;
399
    /** The document range for which inline values should be computed */
400
    range: Range;
401
    /** Additional information about the context in which inline values were requested */
402
    context: InlineValueContext;
403
}
404

405
interface InlineValueContext {
406
    /** The stack frame (as a DAP Id) where the execution has stopped */
407
    frameId: number;
408
    /** The document range where execution has stopped */
409
    stoppedLocation: Range;
410
}
411

412
type InlineValue = InlineValueText | InlineValueVariableLookup | InlineValueEvaluatableExpression;
413

414
interface InlineValueText {
415
    /** The document range for which the inline value applies */
416
    range: Range;
417
    /** The text of the inline value */
418
    text: string;
419
}
420

421
interface InlineValueVariableLookup {
422
    /** The document range for which the inline value applies */
423
    range: Range;
424
    /** If specified the name of the variable to look up */
425
    variableName?: string;
426
    /** How to perform the lookup */
427
    caseSensitiveLookup: boolean;
428
}
429

430
interface InlineValueEvaluatableExpression {
431
    /** The document range for which the inline value applies */
432
    range: Range;
433
    /** If specified the expression overrides the extracted expression */
434
    expression?: string;
435
}
436
```
437

438
### Monikers
439

440
Provides moniker information for cross-reference and navigation purposes.
441

442
```typescript { .api }
443
/**
444
 * Moniker feature for cross-reference support
445
 */
446
interface MonikerFeatureShape {
447
    moniker: {
448
        /** Register handler for moniker requests */
449
        on(handler: ServerRequestHandler<MonikerParams, Moniker[] | null, void>): Disposable;
450
    };
451
}
452

453
interface MonikerParams extends TextDocumentPositionParams, WorkDoneProgressParams, PartialResultParams {
454
}
455

456
interface Moniker {
457
    /** The scheme of the moniker */
458
    scheme: string;
459
    /** The identifier of the moniker */
460
    identifier: string;
461
    /** The scope in which the moniker is unique */
462
    unique: UniquenessLevel;
463
    /** The moniker kind if known */
464
    kind?: MonikerKind;
465
}
466

467
enum UniquenessLevel {
468
    /** The moniker is only unique inside a document */
469
    document = 'document',
470
    /** The moniker is unique inside a project for which a dump got created */
471
    project = 'project',
472
    /** The moniker is unique inside the group to which a project belongs */
473
    group = 'group',
474
    /** The moniker is unique inside the moniker scheme */
475
    scheme = 'scheme',
476
    /** The moniker is globally unique */
477
    global = 'global'
478
}
479

480
enum MonikerKind {
481
    /** The moniker represent a symbol that is imported into a project */
482
    import = 'import',
483
    /** The moniker represents a symbol that is exported from a project */
484
    export = 'export',
485
    /** The moniker represents a symbol that is local to a project */
486
    local = 'local'
487
}
488
```
489

490
## Core Types
491

492
```typescript { .api }
493
type ServerRequestHandler<P, R, PR, E> = (
494
    params: P,
495
    token: CancellationToken,
496
    workDoneProgress: WorkDoneProgressReporter,
497
    partialResultProgress: ResultProgressReporter<PR>
498
) => HandlerResult<R, E>;
499

500
type HandlerResult<R, E> = R | ResponseError<E> | Promise<R> | Promise<ResponseError<E>>;
501

502
interface WorkDoneProgressReporter {
503
    begin(title: string, percentage?: number, message?: string, cancellable?: boolean): void;
504
    report(percentage: number): void;
505
    report(message: string): void;
506
    report(percentage: number, message?: string): void;
507
    done(): void;
508
}
509

510
interface ResultProgressReporter<T> {
511
    report(data: T): void;
512
}
513

514
enum SymbolTag {
515
    Deprecated = 1
516
}
517

518
interface ResponseError<D> {
519
    code: number;
520
    message: string;
521
    data?: D;
522
}
523

524
interface Disposable {
525
    dispose(): void;
526
}
527
```