0
# Linting System
1

2
Extension validation using Mozilla's addons-linter with configurable output formats, validation rules, and comprehensive error reporting for WebExtension compliance.
3

4
## Capabilities
5

6
### Lint Function
7

8
Validate extension source code against WebExtension standards and Mozilla's addon policies.
9

10
```javascript { .api }
11
/**
12
 * Lint an extension using Mozilla's addons-linter
13
 * @param params - Linting configuration parameters
14
 * @param options - Optional linter dependencies and settings
15
 * @returns Promise that resolves when linting completes
16
 */
17
function lint(params: LintParams, options?: LintOptions): Promise<void>;
18

19
interface LintParams {
20
  /** Source directory containing the extension */
21
  sourceDir: string;
22
  /** Directory for artifacts (used for file filtering) */
23
  artifactsDir: string;
24
  /** Output format for linting results */
25
  output?: 'text' | 'json';
26
  /** Output only metadata as JSON */
27
  metadata?: boolean;
28
  /** Treat warnings as errors (exit with non-zero code) */
29
  warningsAsErrors?: boolean;
30
  /** Prettify JSON output */
31
  pretty?: boolean;
32
  /** Treat extension as privileged (fewer restrictions) */
33
  privileged?: boolean;
34
  /** Extension will be self-hosted (disables AMO-specific messages) */
35
  selfHosted?: boolean;
36
  /** Disable colorful shell output */
37
  boring?: boolean;
38
  /** Array of glob patterns for files to ignore */
39
  ignoreFiles?: string[];
40
  /** Enable verbose logging output */
41
  verbose?: boolean;
42
}
43

44
interface LintOptions {
45
  /** Custom linter factory function */
46
  createLinter?: Function;
47
  /** Custom file filter factory */
48
  createFileFilter?: Function;
49
  /** Should exit process after linting */
50
  shouldExitProgram?: boolean;
51
}
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
import { cmd } from "web-ext";
58

59
// Basic linting with text output
60
await cmd.lint({
61
  sourceDir: './my-extension'
62
});
63

64
// Lint with JSON output and detailed formatting
65
await cmd.lint({
66
  sourceDir: './extension',
67
  output: 'json',
68
  pretty: true,
69
  verbose: true
70
});
71

72
// Strict linting (treat warnings as errors)
73
await cmd.lint({
74
  sourceDir: './extension',
75
  warningsAsErrors: true,
76
  privileged: false,
77
  selfHosted: false
78
});
79

80
// Lint with custom file filtering
81
await cmd.lint({
82
  sourceDir: './src',
83
  artifactsDir: './build',
84
  ignoreFiles: ['*.log', 'node_modules/**', 'test/**'],
85
  output: 'json'
86
});
87
```
88

89
### Linter Configuration
90

91
Advanced configuration options for customizing the linting process.
92

93
```javascript { .api }
94
interface LinterConfig {
95
  /** Log level for linter output */
96
  logLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
97
  /** Include stack traces in output */
98
  stack: boolean;
99
  /** Pretty print JSON output */
100
  pretty: boolean;
101
  /** Treat extension as privileged */
102
  privileged: boolean;
103
  /** Treat warnings as errors */
104
  warningsAsErrors: boolean;
105
  /** Output only metadata */
106
  metadata: boolean;
107
  /** Output format */
108
  output: 'text' | 'json';
109
  /** Disable colors in output */
110
  boring: boolean;
111
  /** Extension is self-hosted */
112
  selfHosted: boolean;
113
  /** Function to determine if file should be scanned */
114
  shouldScanFile: (fileName: string) => boolean;
115
  /** Minimum supported manifest version */
116
  minManifestVersion: number;
117
  /** Maximum supported manifest version */
118
  maxManifestVersion: number;
119
  /** Command line arguments (for context) */
120
  _: string[];
121
}
122
```
123

124
### File Filtering Integration
125

126
The linting system integrates with web-ext's file filtering to exclude unwanted files from validation.
127

128
```javascript { .api }
129
interface FileFilter {
130
  /** Determine if a file should be included in linting */
131
  wantFile(fileName: string): boolean;
132
}
133
```
134

135
**Default Excluded Files:**
136
- `**/*.xpi` - Firefox extension packages
137
- `**/*.zip` - Zip archives
138
- `**/.*` - Hidden files and directories
139
- `**/node_modules` - Node.js dependencies
140
- Build artifacts and temporary files
141

142
### Linter Factory
143

144
Create custom linter instances with specific configurations.
145

146
```javascript { .api }
147
/**
148
 * Create an addons-linter instance
149
 * @param config - Linter configuration
150
 * @returns Configured linter instance
151
 */
152
function createLinter(config: LinterConfig): AddonLinter;
153

154
interface AddonLinter {
155
  /** Run the linter and return results */
156
  run(): Promise<LintResult>;
157
}
158

159
interface LintResult {
160
  /** Total number of errors found */
161
  errorCount: number;
162
  /** Total number of warnings found */
163
  warningCount: number;
164
  /** Array of error and warning messages */
165
  messages: LintMessage[];
166
  /** Extension metadata */
167
  metadata: ExtensionMetadata;
168
  /** Summary information */
169
  summary: LintSummary;
170
}
171
```
172

173
### Lint Results
174

175
Detailed structure of linting results for programmatic processing.
176

177
```javascript { .api }
178
interface LintMessage {
179
  /** Unique identifier for the message type */
180
  code: string;
181
  /** Severity level */
182
  type: 'error' | 'warning' | 'notice';
183
  /** Human-readable message */
184
  message: string;
185
  /** File where the issue was found */
186
  file?: string;
187
  /** Line number of the issue */
188
  line?: number;
189
  /** Column number of the issue */
190
  column?: number;
191
  /** Additional context or description */
192
  description?: string;
193
}
194

195
interface ExtensionMetadata {
196
  /** Extension name */
197
  name: string;
198
  /** Extension version */
199
  version: string;
200
  /** Manifest version */
201
  manifestVersion: number;
202
  /** Extension type */
203
  type: string;
204
  /** Extension ID */
205
  id?: string;
206
  /** Required permissions */
207
  permissions?: string[];
208
  /** Content scripts information */
209
  contentScripts?: object[];
210
}
211

212
interface LintSummary {
213
  /** Total files scanned */
214
  totalFiles: number;
215
  /** Total errors found */
216
  errors: number;
217
  /** Total warnings found */
218
  warnings: number;
219
  /** Total notices */
220
  notices: number;
221
}
222
```
223

224
### Output Formats
225

226
The linter supports multiple output formats for different use cases.
227

228
#### Text Output
229

230
Human-readable console output with colors and formatting:
231

232
```
233
Validation Summary:
234

235
errors          0
236
notices         0
237
warnings        1
238

239
Code               Message                                    File:Line
240
MANIFEST_UNUSED_   /permissions/storage is unused            manifest.json:15:1
241
UPDATE
242

243
Your add-on uses deprecated functionality that has been removed from Firefox 71+...
244
```
245

246
#### JSON Output
247

248
Machine-readable JSON format for automated processing:
249

250
```json
251
{
252
  "count": {
253
    "errors": 0,
254
    "notices": 0,
255
    "warnings": 1
256
  },
257
  "summary": {
258
    "errors": 0,
259
    "notices": 0,
260
    "warnings": 1
261
  },
262
  "metadata": {
263
    "name": "My Extension",
264
    "version": "1.0.0",
265
    "manifestVersion": 2
266
  },
267
  "messages": [
268
    {
269
      "code": "MANIFEST_UNUSED_UPDATE",
270
      "message": "/permissions/storage is unused",
271
      "description": "Your extension uses...",
272
      "file": "manifest.json",
273
      "line": 15,
274
      "column": 1,
275
      "type": "warning"
276
    }
277
  ]
278
}
279
```
280

281
### Validation Rules
282

283
The linter validates extensions against comprehensive rule sets:
284

285
#### Manifest Validation
286
- Required fields (name, version, manifest_version)
287
- Permission usage and requirements
288
- API compatibility across manifest versions
289
- File references and resource validation
290

291
#### Code Analysis
292
- JavaScript syntax and best practices
293
- Content Security Policy compliance
294
- API usage validation
295
- Deprecated API detection
296

297
#### Asset Validation
298
- Icon file formats and sizes
299
- Locale file structure and content
300
- HTML file validation
301
- CSS compatibility
302

303
#### Security Checks
304
- Potentially dangerous patterns
305
- External resource usage
306
- Permission scope validation
307
- Content script injection safety
308

309
## Error Handling
310

311
The linting system provides detailed error reporting:
312

313
- **Manifest errors**: Invalid JSON, missing required fields, malformed values
314
- **File errors**: Missing referenced files, invalid file formats
315
- **Code errors**: Syntax errors, deprecated API usage, security issues
316
- **Permission errors**: Unused permissions, insufficient permissions for API usage
317
- **Compatibility errors**: Features not supported in target Firefox versions
318

319
**Usage Example for Error Handling:**
320

321
```javascript
322
try {
323
  await cmd.lint({
324
    sourceDir: './extension',
325
    warningsAsErrors: true
326
  });
327
  console.log('Extension passed all validation checks!');
328
} catch (error) {
329
  console.error('Linting failed:', error.message);
330
  // Linter will have already output detailed validation results
331
}
332
```