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
```