0
# Core Analysis Engine
1

2
The LitAnalyzer class is the main entry point for performing static analysis of Lit templates. It provides comprehensive analysis capabilities including diagnostics, code completion, hover information, definitions, rename support, and code fixes.
3

4
## Capabilities
5

6
### LitAnalyzer Class
7

8
Main analyzer class providing comprehensive static analysis capabilities for Lit templates.
9

10
```typescript { .api }
11
/**
12
 * Main analyzer class for Lit template static analysis
13
 * Provides diagnostics, completions, definitions, and code fixes
14
 */
15
class LitAnalyzer {
16
  /**
17
   * Creates a new LitAnalyzer instance
18
   * @param context - The analyzer context containing TypeScript program and configuration
19
   */
20
  constructor(context: LitAnalyzerContext);
21
}
22
```
23

24
### Diagnostic Analysis
25

26
Get all diagnostics (errors and warnings) for a source file containing Lit templates.
27

28
```typescript { .api }
29
/**
30
 * Get all diagnostics for a source file
31
 * Analyzes template literals for binding errors, type mismatches, and rule violations
32
 * @param file - TypeScript source file to analyze
33
 * @returns Array of diagnostic messages with locations and severity
34
 */
35
getDiagnosticsInFile(file: SourceFile): LitDiagnostic[];
36
```
37

38
**Usage Example:**
39

40
```typescript
41
import { LitAnalyzer, DefaultLitAnalyzerContext, makeConfig, type LitPluginContextHandler } from "lit-analyzer";
42
import * as ts from "typescript";
43

44
const program = ts.createProgram(["src/my-component.ts"], {});
45
const handler: LitPluginContextHandler = {
46
  ts: ts,
47
  getProgram: () => program
48
};
49
const context = new DefaultLitAnalyzerContext(handler);
50
const config = makeConfig({ strict: true });
51
context.updateConfig(config);
52
const analyzer = new LitAnalyzer(context);
53

54
const sourceFile = program.getSourceFile("src/my-component.ts")!;
55
const diagnostics = analyzer.getDiagnosticsInFile(sourceFile);
56

57
diagnostics.forEach(diagnostic => {
58
  const severity = diagnostic.severity;
59
  const message = diagnostic.message;
60
  const line = diagnostic.location.start;
61
  console.log(`${severity} at line ${line}: ${message}`);
62
});
63
```
64

65
### Code Completion
66

67
Get code completions at a specific position within a Lit template.
68

69
```typescript { .api }
70
/**
71
 * Get code completions at a specific position
72
 * Provides attribute names, property names, event names, and element names
73
 * @param file - TypeScript source file containing the template
74
 * @param position - Character position within the file
75
 * @returns Array of completion items or undefined if not in a template
76
 */
77
getCompletionsAtPosition(file: SourceFile, position: SourceFilePosition): LitCompletion[] | undefined;
78

79
/**
80
 * Get detailed information about a specific completion item
81
 * @param file - TypeScript source file containing the template
82
 * @param position - Character position within the file
83
 * @param name - Name of the completion item
84
 * @returns Detailed completion information or undefined
85
 */
86
getCompletionDetailsAtPosition(file: SourceFile, position: SourceFilePosition, name: string): LitCompletionDetails | undefined;
87
```
88

89
### Definition and Navigation
90

91
Get definition information and navigation capabilities for template elements.
92

93
```typescript { .api }
94
/**
95
 * Get definition information at a specific position
96
 * Finds the definition of attributes, properties, events, or elements
97
 * @param file - TypeScript source file containing the template
98
 * @param position - Character position within the file
99
 * @returns Definition information or undefined if no definition found
100
 */
101
getDefinitionAtPosition(file: SourceFile, position: SourceFilePosition): LitDefinition | undefined;
102

103
/**
104
 * Get hover information at a specific position
105
 * Provides type information and documentation for template elements
106
 * @param file - TypeScript source file containing the template
107
 * @param position - Character position within the file
108
 * @returns Quick info object or undefined
109
 */
110
getQuickInfoAtPosition(file: SourceFile, position: SourceFilePosition): LitQuickInfo | undefined;
111
```
112

113
### Rename Support
114

115
Get rename information and locations for template elements.
116

117
```typescript { .api }
118
/**
119
 * Get rename information at a specific position
120
 * Determines if the element at the position can be renamed
121
 * @param file - TypeScript source file containing the template
122
 * @param position - Character position within the file
123
 * @returns Rename information or undefined if element cannot be renamed
124
 */
125
getRenameInfoAtPosition(file: SourceFile, position: SourceFilePosition): LitRenameInfo | undefined;
126

127
/**
128
 * Get all rename locations for an element
129
 * Finds all occurrences of the element that would be renamed
130
 * @param file - TypeScript source file containing the template
131
 * @param position - Character position within the file
132
 * @returns Array of rename locations
133
 */
134
getRenameLocationsAtPosition(file: SourceFile, position: SourceFilePosition): LitRenameLocation[];
135
```
136

137
### Code Fixes
138

139
Get available code fixes for diagnostic issues.
140

141
```typescript { .api }
142
/**
143
 * Get available code fixes for a specific range
144
 * Provides automatic fixes for common template issues
145
 * @param file - TypeScript source file containing the template
146
 * @param sourceFileRange - Range where the issue occurs
147
 * @returns Array of available code fixes
148
 */
149
getCodeFixesAtPositionRange(file: SourceFile, sourceFileRange: Range): LitCodeFix[];
150
```
151

152
### Code Formatting
153

154
Get formatting edits for template content.
155

156
```typescript { .api }
157
/**
158
 * Get format edits for templates in a file
159
 * Provides formatting corrections for HTML and CSS within templates
160
 * @param file - TypeScript source file containing templates
161
 * @param settings - TypeScript format code settings
162
 * @returns Array of format edit operations
163
 */
164
getFormatEditsInFile(file: SourceFile, settings: FormatCodeSettings): LitFormatEdit[];
165
```
166

167
### Code Folding and Structure
168

169
Get outlining spans for code folding and structural information.
170

171
```typescript { .api }
172
/**
173
 * Get outlining spans for code folding
174
 * Identifies template regions that can be collapsed
175
 * @param file - TypeScript source file containing templates
176
 * @returns Array of outlining spans
177
 */
178
getOutliningSpansInFile(file: SourceFile): LitOutliningSpan[];
179

180
/**
181
 * Get closing tag information for auto-completion
182
 * Determines the appropriate closing tag at a position
183
 * @param file - TypeScript source file containing the template
184
 * @param position - Character position within the file
185
 * @returns Closing tag information or undefined
186
 */
187
getClosingTagAtPosition(file: SourceFile, position: SourceFilePosition): LitClosingTagInfo | undefined;
188
```
189

190
### Static Analysis Indexing
191

192
Generate static analysis index entries for external indexing systems.
193

194
```typescript { .api }
195
/**
196
 * Generate index entries for static analysis systems
197
 * Useful for Kythe, Language Server Index Format, or custom indexing
198
 * @param file - TypeScript source file to index
199
 * @returns Iterator of index entries describing template regions
200
 */
201
indexFile(file: SourceFile): IterableIterator<LitIndexEntry>;
202
```
203

204
## Return Types
205

206
### LitDiagnostic
207

208
```typescript { .api }
209
interface LitDiagnostic {
210
  /** Location of the diagnostic in the source file */
211
  location: SourceFileRange;
212
  /** Optional diagnostic code number */
213
  code?: number;
214
  /** Human-readable diagnostic message */
215
  message: string;
216
  /** Optional fix message suggesting a solution */
217
  fixMessage?: string;
218
  /** Optional suggestion for improvement */
219
  suggestion?: string;
220
  /** Rule ID that generated this diagnostic */
221
  source: LitAnalyzerRuleId;
222
  /** Severity level of the diagnostic */
223
  severity: LitDiagnosticSeverity;
224
  /** Source file containing the diagnostic */
225
  file: SourceFile;
226
}
227
```
228

229
### LitCompletion
230

231
```typescript { .api }
232
interface LitCompletion {
233
  /** Name of the completion item */
234
  name: string;
235
  /** Type/kind of the completion */
236
  kind: LitTargetKind;
237
  /** Optional modifiers (e.g., "color" for CSS color values) */
238
  kindModifiers?: "color";
239
  /** Text to insert when completion is selected */
240
  insert: string;
241
  /** Optional range to replace */
242
  range?: SourceFileRange;
243
  /** Priority for sorting completions */
244
  importance?: "high" | "medium" | "low";
245
  /** Custom sort text for ordering */
246
  sortText?: string;
247
  /** Function to get documentation for this completion */
248
  documentation?(): string | undefined;
249
}
250
```
251

252
### LitDefinition
253

254
```typescript { .api }
255
interface LitDefinition {
256
  /** Name of the definition */
257
  name: string;
258
  /** Location of the definition */
259
  location: SourceFileRange;
260
  /** Source file containing the definition */
261
  file: SourceFile;
262
  /** Type of the definition */
263
  kind: LitTargetKind;
264
}
265
```
266

267
### LitQuickInfo
268

269
```typescript { .api }
270
interface LitQuickInfo {
271
  /** Range of the element being described */
272
  range: SourceFileRange;
273
  /** Display name of the element */
274
  displayName: string;
275
  /** Documentation text */
276
  documentation?: string;
277
  /** Type information */
278
  type?: string;
279
}
280
```
281

282
### LitIndexEntry
283

284
```typescript { .api }
285
type LitIndexEntry = HtmlNodeIndexEntry | HtmlNodeAttrIndexEntry;
286

287
interface HtmlNodeIndexEntry {
288
  /** Type of index entry */
289
  kind: "NODE-REFERENCE";
290
  /** HTML node being referenced */
291
  node: HtmlNode;
292
  /** Document containing the node */
293
  document: HtmlDocument;
294
  /** Definition information for the node */
295
  definition: LitDefinition;
296
}
297

298
interface HtmlNodeAttrIndexEntry {
299
  /** Type of index entry */
300
  kind: "ATTRIBUTE-REFERENCE";
301
  /** HTML attribute being referenced */
302
  attribute: HtmlNodeAttr;
303
  /** Document containing the attribute */
304
  document: HtmlDocument;
305
  /** Definition information for the attribute */
306
  definition: LitDefinition;
307
}
308
```