0
# Configuration System
1

2
The configuration system provides comprehensive control over analyzer behavior, rule severities, validation modes, and template recognition patterns.
3

4
## Capabilities
5

6
### Configuration Creation
7

8
Create configuration objects from partial options with intelligent defaults.
9

10
```typescript { .api }
11
import { HTMLDataV1 } from "vscode-html-languageservice";
12

13
/**
14
 * Create a complete configuration from partial options
15
 * Applies intelligent defaults for unspecified options
16
 * @param userOptions - Partial configuration options
17
 * @returns Complete LitAnalyzerConfig with all defaults applied
18
 */
19
function makeConfig(userOptions?: Partial<LitAnalyzerConfig>): LitAnalyzerConfig;
20

21
/**
22
 * Create rules configuration from partial analyzer config
23
 * Extracts and processes rule-specific configuration
24
 * @param userOptions - Partial configuration containing rules
25
 * @returns Processed rules configuration
26
 */
27
function makeRules(userOptions: Partial<LitAnalyzerConfig>): LitAnalyzerRules;
28
```
29

30
**Usage Example:**
31

32
```typescript
33
import { makeConfig } from "lit-analyzer";
34

35
// Create strict configuration with custom rules
36
const config = makeConfig({
37
  strict: true,
38
  rules: {
39
    "no-unknown-tag-name": "error",
40
    "no-missing-import": "warn",
41
    "no-incompatible-type-binding": "off"
42
  },
43
  logging: "debug"
44
});
45
```
46

47
### Rule Management
48

49
Utilities for managing rule severities and checking rule states.
50

51
```typescript { .api }
52
/**
53
 * Get the severity level for a specific rule
54
 * @param rules - Rules configuration or full config
55
 * @param ruleId - ID of the rule to check
56
 * @returns The severity level for the rule
57
 */
58
function ruleSeverity(rules: LitAnalyzerConfig | LitAnalyzerRules, ruleId: LitAnalyzerRuleId): LitAnalyzerRuleSeverity;
59

60
/**
61
 * Check if a rule is disabled
62
 * @param config - Analyzer configuration
63
 * @param ruleId - ID of the rule to check
64
 * @returns True if the rule is disabled
65
 */
66
function isRuleDisabled(config: LitAnalyzerConfig, ruleId: LitAnalyzerRuleId): boolean;
67

68
/**
69
 * Check if a rule is enabled
70
 * @param config - Analyzer configuration
71
 * @param ruleId - ID of the rule to check
72
 * @returns True if the rule is enabled
73
 */
74
function isRuleEnabled(config: LitAnalyzerConfig, ruleId: LitAnalyzerRuleId): boolean;
75

76
/**
77
 * Convert rule severity to diagnostic severity
78
 * @param config - Analyzer configuration
79
 * @param ruleId - ID of the rule
80
 * @returns Diagnostic severity level
81
 */
82
function litDiagnosticRuleSeverity(config: LitAnalyzerConfig, ruleId: LitAnalyzerRuleId): LitDiagnosticSeverity;
83
```
84

85
### Rule Information
86

87
Access rule metadata and numeric codes.
88

89
```typescript { .api }
90
/**
91
 * Get numeric code for a rule ID
92
 * @param ruleId - ID of the rule
93
 * @returns Numeric code associated with the rule
94
 */
95
function ruleIdCode(ruleId: LitAnalyzerRuleId): number;
96

97
/** Array of all available rule IDs in alphabetical order */
98
const ALL_RULE_IDS: readonly LitAnalyzerRuleId[];
99

100
/** Map of rule IDs to their numeric codes */
101
const RULE_ID_CODE_MAP: Record<LitAnalyzerRuleId, number>;
102
```
103

104
## Configuration Types
105

106
### Main Configuration Interface
107

108
```typescript { .api }
109
interface LitAnalyzerConfig {
110
  /** Enable strict mode (changes default rule severities) */
111
  strict: boolean;
112
  /** Rule configuration mapping rule IDs to severities */
113
  rules: LitAnalyzerRules;
114
  /** Security system configuration */
115
  securitySystem: LitSecuritySystem;
116
  /** Disable analyzer functionality completely */
117
  disable: boolean;
118
  /** Logging level for analyzer output */
119
  logging: LitAnalyzerLogging;
120
  /** Current working directory */
121
  cwd: string;
122
  /** Format configuration */
123
  format: { disable: boolean };
124
  /** Disable suggestion messages in diagnostics */
125
  dontShowSuggestions: boolean;
126
  /** Disable configuration change suggestions */
127
  dontSuggestConfigChanges: boolean;
128
  /** Maximum depth for node_modules import traversal */
129
  maxNodeModuleImportDepth: number;
130
  /** Maximum depth for project import traversal */
131
  maxProjectImportDepth: number;
132
  /** Template tag names that contain HTML templates */
133
  htmlTemplateTags: string[];
134
  /** Template tag names that contain CSS templates */
135
  cssTemplateTags: string[];
136
  /** Global tag names that are always considered valid */
137
  globalTags: string[];
138
  /** Global attribute names that are always considered valid */
139
  globalAttributes: string[];
140
  /** Global event names that are always considered valid */
141
  globalEvents: string[];
142
  /** Custom HTML data for additional element/attribute definitions */
143
  customHtmlData: (string | HTMLDataV1)[] | string | HTMLDataV1;
144
}
145
```
146

147
### Rules Configuration
148

149
```typescript { .api }
150
type LitAnalyzerRules = Partial<Record<LitAnalyzerRuleId, LitAnalyzerRuleSeverity>>;
151

152
type LitAnalyzerRuleSeverity = 
153
  | "on" 
154
  | "off" 
155
  | "warn" 
156
  | "warning" 
157
  | "error" 
158
  | 0 
159
  | 1 
160
  | 2 
161
  | true 
162
  | false;
163

164
type LitAnalyzerRuleId = 
165
  | "no-unknown-tag-name"
166
  | "no-missing-import"
167
  | "no-unclosed-tag"
168
  | "no-unknown-attribute"
169
  | "no-unknown-property"
170
  | "no-unknown-event"
171
  | "no-unknown-slot"
172
  | "no-unintended-mixed-binding"
173
  | "no-invalid-boolean-binding"
174
  | "no-expressionless-property-binding"
175
  | "no-noncallable-event-binding"
176
  | "no-boolean-in-attribute-binding"
177
  | "no-complex-attribute-binding"
178
  | "no-nullable-attribute-binding"
179
  | "no-incompatible-type-binding"
180
  | "no-invalid-directive-binding"
181
  | "no-incompatible-property-type"
182
  | "no-invalid-attribute-name"
183
  | "no-invalid-tag-name"
184
  | "no-invalid-css"
185
  | "no-property-visibility-mismatch"
186
  | "no-legacy-attribute"
187
  | "no-missing-element-type-definition";
188
```
189

190
### Logging Configuration
191

192
```typescript { .api }
193
type LitAnalyzerLogging = "off" | "error" | "warn" | "debug" | "verbose";
194
```
195

196
### Security Configuration
197

198
```typescript { .api }
199
type LitSecuritySystem = "off" | "ClosureSafeTypes";
200
```
201

202
## Rule Categories
203

204
### Custom Element Validation Rules
205

206
Rules for validating custom element usage and definitions:
207

208
- `no-unknown-tag-name` - Check for unknown custom element tags
209
- `no-missing-import` - Ensure custom elements are imported
210
- `no-unclosed-tag` - Check for unclosed tags
211
- `no-missing-element-type-definition` - Ensure proper TypeScript definitions
212

213
### Binding Name Validation Rules
214

215
Rules for validating attribute, property, and event names:
216

217
- `no-unknown-attribute` - Check for unknown attributes
218
- `no-unknown-property` - Check for unknown properties
219
- `no-unknown-event` - Check for unknown events
220
- `no-unknown-slot` - Check for unknown slots
221
- `no-legacy-attribute` - Disallow legacy Polymer syntax
222

223
### Binding Type Validation Rules
224

225
Rules for validating binding type compatibility:
226

227
- `no-incompatible-type-binding` - Check type compatibility in bindings
228
- `no-boolean-in-attribute-binding` - Check boolean attribute usage
229
- `no-expressionless-property-binding` - Ensure property bindings have expressions
230
- `no-noncallable-event-binding` - Check event handler callability
231
- `no-nullable-attribute-binding` - Check nullable attribute bindings
232

233
### Advanced Validation Rules
234

235
Rules for advanced template validation:
236

237
- `no-invalid-attribute-name` - Validate attribute name syntax
238
- `no-invalid-tag-name` - Validate tag name syntax
239
- `no-property-visibility-mismatch` - Check property visibility
240
- `no-invalid-directive-binding` - Validate directive usage
241
- `no-unintended-mixed-binding` - Check for mixed binding types
242
- `no-invalid-boolean-binding` - Validate boolean binding syntax
243
- `no-complex-attribute-binding` - Check complex attribute expressions
244
- `no-attribute-default-value` - Check attribute default values
245
- `no-invalid-css` - Validate CSS within template literals
246
- `no-incompatible-property-type` - Check property type compatibility
247
- `no-unknown-property-converter` - Check property converter usage
248
- `no-duplicate-slot-names` - Check for duplicate slot names
249
- `no-template-bind` - Check template binding usage
250

251
## Configuration Examples
252

253
### Basic Configuration
254

255
```typescript
256
import { makeConfig } from "lit-analyzer";
257

258
const config = makeConfig({
259
  rules: {
260
    "no-unknown-tag-name": "warn",
261
    "no-missing-import": "error"
262
  }
263
});
264
```
265

266
### Strict Mode Configuration
267

268
```typescript
269
const strictConfig = makeConfig({
270
  strict: true,
271
  logging: "debug",
272
  rules: {
273
    "no-unknown-tag-name": "error",
274
    "no-incompatible-type-binding": "error"
275
  }
276
});
277
```
278

279
### Custom Template Tags
280

281
```typescript
282
const customConfig = makeConfig({
283
  htmlTemplateTags: ["html", "template", "render"],
284
  cssTemplateTags: ["css", "styles"],
285
  globalTags: ["my-custom-element"],
286
  globalAttributes: ["data-testid"]
287
});
288
```