0
# Lit Analyzer
1
2
Lit Analyzer is a comprehensive CLI tool and TypeScript library that performs static analysis and type checking of lit-html templates and LitElement web components. It provides diagnostics, code completion, hover information, definitions, rename support, and code fixes for Lit templates.
3
4
## Package Information
5
6
- **Package Name**: lit-analyzer
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install lit-analyzer -g`
10
11
## Core Imports
12
13
```typescript
14
import { LitAnalyzer, DefaultLitAnalyzerContext, makeConfig } from "lit-analyzer";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { LitAnalyzer, DefaultLitAnalyzerContext, makeConfig } = require("lit-analyzer");
21
```
22
23
## Basic Usage
24
25
### CLI Usage
26
27
```bash
28
# Analyze all TypeScript/JavaScript files in src directory
29
lit-analyzer src
30
31
# Analyze specific files with glob patterns
32
lit-analyzer "src/**/*.{js,ts}"
33
34
# Analyze with custom rules and output format
35
lit-analyzer --format markdown --rules.no-unknown-tag-name off src
36
```
37
38
### Programmatic Usage
39
40
```typescript
41
import { LitAnalyzer, DefaultLitAnalyzerContext, makeConfig, type LitPluginContextHandler } from "lit-analyzer";
42
import * as ts from "typescript";
43
44
// Create TypeScript program
45
const program = ts.createProgram(["src/my-component.ts"], {});
46
47
// Create plugin context handler
48
const handler: LitPluginContextHandler = {
49
ts: ts,
50
getProgram: () => program
51
};
52
53
// Create analyzer context and update configuration
54
const context = new DefaultLitAnalyzerContext(handler);
55
const config = makeConfig({ strict: true });
56
context.updateConfig(config);
57
58
// Create analyzer and get diagnostics
59
const analyzer = new LitAnalyzer(context);
60
const sourceFile = program.getSourceFile("src/my-component.ts");
61
const diagnostics = analyzer.getDiagnosticsInFile(sourceFile!);
62
63
// Process diagnostics
64
diagnostics.forEach(diagnostic => {
65
console.log(`${diagnostic.severity}: ${diagnostic.message}`);
66
});
67
```
68
69
## Architecture
70
71
Lit Analyzer is built around several core components:
72
73
- **LitAnalyzer**: Main analyzer class providing comprehensive static analysis capabilities
74
- **Context System**: Manages TypeScript integration, configuration, and analysis state
75
- **Rule System**: 29 built-in validation rules with configurable severities
76
- **Document Analysis**: Specialized analyzers for HTML and CSS within template literals
77
- **Type Integration**: Deep TypeScript integration for accurate type checking
78
- **CLI Interface**: Command-line tool with multiple output formats and configuration options
79
80
## Capabilities
81
82
### Core Analysis Engine
83
84
Main analyzer class providing comprehensive static analysis capabilities for Lit templates including diagnostics, completions, definitions, and code fixes.
85
86
```typescript { .api }
87
class LitAnalyzer {
88
constructor(context: LitAnalyzerContext);
89
getDiagnosticsInFile(file: SourceFile): LitDiagnostic[];
90
getCompletionsAtPosition(file: SourceFile, position: SourceFilePosition): LitCompletion[] | undefined;
91
getDefinitionAtPosition(file: SourceFile, position: SourceFilePosition): LitDefinition | undefined;
92
getQuickInfoAtPosition(file: SourceFile, position: SourceFilePosition): LitQuickInfo | undefined;
93
}
94
```
95
96
[Core Analysis Engine](./core-analysis.md)
97
98
### Configuration System
99
100
Comprehensive configuration system for controlling analyzer behavior, rule severities, and validation modes.
101
102
```typescript { .api }
103
interface LitAnalyzerConfig {
104
rules: LitAnalyzerRules;
105
strict?: boolean;
106
logging?: LitAnalyzerLogging;
107
securitySystem?: LitSecuritySystem;
108
dontShowSuggestions?: boolean;
109
htmlTemplateTags?: string[];
110
cssTemplateTags?: string[];
111
globalTags?: string[];
112
globalAttributes?: string[];
113
globalEvents?: string[];
114
customHtmlData?: any;
115
}
116
117
function makeConfig(userOptions?: Partial<LitAnalyzerConfig>): LitAnalyzerConfig;
118
```
119
120
[Configuration System](./configuration.md)
121
122
### Context and Integration
123
124
Context system managing TypeScript integration, analysis state, and component stores for comprehensive template analysis.
125
126
```typescript { .api }
127
interface LitAnalyzerContext {
128
readonly ts: typeof import("typescript");
129
readonly program: Program;
130
readonly config: LitAnalyzerConfig;
131
readonly logger: LitAnalyzerLogger;
132
updateComponents(file: SourceFile): void;
133
updateDependencies(file: SourceFile): void;
134
}
135
136
class DefaultLitAnalyzerContext implements LitAnalyzerContext {
137
constructor(handler: LitPluginContextHandler);
138
}
139
```
140
141
[Context and Integration](./context-integration.md)
142
143
### CLI Interface
144
145
Command-line interface providing analysis capabilities with multiple output formats and extensive configuration options.
146
147
```typescript { .api }
148
function cli(): Promise<void>;
149
150
interface LitAnalyzerCliConfig extends LitAnalyzerConfig {
151
help: boolean;
152
format: "code" | "list" | "markdown";
153
maxWarnings: number;
154
quiet: boolean;
155
failFast: boolean;
156
noColor: boolean;
157
outFile?: string;
158
}
159
```
160
161
[CLI Interface](./cli-interface.md)
162
163
## Types
164
165
### Core Types
166
167
```typescript { .api }
168
type SourceFilePosition = number;
169
type DocumentOffset = number;
170
171
interface Range {
172
start: number;
173
end: number;
174
}
175
176
type SourceFileRange = Range & { __brand: "SourceFileRange" };
177
type DocumentRange = Range & { __brand: "DocumentRange" };
178
```
179
180
### Diagnostic Types
181
182
```typescript { .api }
183
type LitDiagnosticSeverity = "error" | "warning";
184
185
interface LitDiagnostic {
186
location: SourceFileRange;
187
code?: number;
188
message: string;
189
fixMessage?: string;
190
suggestion?: string;
191
source: LitAnalyzerRuleId;
192
severity: LitDiagnosticSeverity;
193
file: SourceFile;
194
}
195
```
196
197
### Completion Types
198
199
```typescript { .api }
200
interface LitCompletion {
201
name: string;
202
kind: LitTargetKind;
203
kindModifiers?: "color";
204
insert: string;
205
range?: SourceFileRange;
206
importance?: "high" | "medium" | "low";
207
sortText?: string;
208
documentation?(): string | undefined;
209
}
210
211
type LitTargetKind =
212
| "memberFunctionElement"
213
| "functionElement"
214
| "constructorImplementationElement"
215
| "variableElement"
216
| "classElement"
217
| "interfaceElement"
218
| "moduleElement"
219
| "memberVariableElement"
220
| "constElement"
221
| "enumElement"
222
| "keyword"
223
| "alias"
224
| "member"
225
| "label"
226
| "unknown";
227
```
228
229
### Code Fix Types
230
231
```typescript { .api }
232
interface LitCodeFix {
233
name: string;
234
message: string;
235
actions: LitCodeFixAction[];
236
}
237
238
interface LitCodeFixAction {
239
range: SourceFileRange;
240
newText: string;
241
}
242
```