0
# Programmatic API
1

2
The sass-lint programmatic API provides full access to linting functionality for integration with build tools, editors, and custom applications.
3

4
## Capabilities
5

6
### Main Constructor
7

8
Initialize sass-lint with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Main sass-lint constructor function
13
 * @param {Object} config - User specified rules/options
14
 * @returns {void}
15
 */
16
function sassLint(config);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const sassLint = require('sass-lint');
23

24
// Initialize with default config
25
sassLint();
26

27
// Initialize with custom config
28
sassLint({
29
  rules: {
30
    'indentation': [2, { size: 2 }],
31
    'no-ids': 1
32
  }
33
});
34
```
35

36
### Configuration Management
37

38
Retrieve and compile configuration from various sources.
39

40
```javascript { .api }
41
/**
42
 * Get compiled configuration object
43
 * @param {Object} config - User specified rules/options
44
 * @param {string} configPath - Path to config file
45
 * @returns {Object} Compiled config object
46
 */
47
function sassLint.getConfig(config, configPath);
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
// Get default configuration
54
const defaultConfig = sassLint.getConfig();
55

56
// Get config with overrides
57
const customConfig = sassLint.getConfig({
58
  rules: { 'no-ids': 2 }
59
});
60

61
// Get config from specific file
62
const fileConfig = sassLint.getConfig(null, './.sass-lint.yml');
63

64
// Combine custom config with file
65
const combinedConfig = sassLint.getConfig(
66
  { rules: { 'indentation': [2, { size: 4 }] } },
67
  './.sass-lint.yml'
68
);
69
```
70

71
### Text Linting
72

73
Lint text content directly without file system access.
74

75
```javascript { .api }
76
/**
77
 * Lint text content against rules
78
 * @param {Object} file - File object with text, format, and filename
79
 * @param {Object} options - User specified rules/options
80
 * @param {string} configPath - Path to config file
81
 * @returns {Object} Lint results with error/warning counts and messages
82
 */
83
function sassLint.lintText(file, options, configPath);
84
```
85

86
**File Object Structure:**
87
```javascript { .api }
88
interface FileObject {
89
  text: string;    // File content to lint
90
  format: string;  // 'sass' or 'scss'
91
  filename: string; // File path for reporting
92
}
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
// Basic text linting
99
const file = {
100
  text: '.foo { color: red; }',
101
  format: 'scss',
102
  filename: 'test.scss'
103
};
104

105
const results = sassLint.lintText(file);
106
console.log(results);
107
// Output: { filePath: 'test.scss', warningCount: 0, errorCount: 0, messages: [] }
108

109
// Lint with custom options
110
const options = {
111
  rules: { 'no-color-literals': 2 }
112
};
113

114
const strictResults = sassLint.lintText(file, options);
115

116
// Lint with config file
117
const configResults = sassLint.lintText(file, null, './.sass-lint.yml');
118

119
// Complex example with Sass syntax
120
const sassFile = {
121
  text: `
122
$primary: blue
123
.header
124
  color: $primary
125
  margin: 0
126
`,
127
  format: 'sass',
128
  filename: 'header.sass'
129
};
130

131
const sassResults = sassLint.lintText(sassFile);
132
```
133

134
### File Text Linting with Ignore Patterns
135

136
Lint text content while respecting ignore patterns from configuration.
137

138
```javascript { .api }
139
/**
140
 * Lint file text with ignore pattern checking
141
 * @param {Object} file - File object with text, format, and filename
142
 * @param {Object} options - User specified rules/options
143
 * @param {string} configPath - Path to config file
144
 * @returns {Object} Lint results or empty results if ignored
145
 */
146
function sassLint.lintFileText(file, options, configPath);
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
// File that might be ignored
153
const file = {
154
  text: '.foo { color: red; }',
155
  format: 'scss',
156
  filename: 'vendor/bootstrap.scss'
157
};
158

159
// With ignore patterns in config
160
const options = {
161
  files: {
162
    ignore: ['vendor/**']
163
  }
164
};
165

166
const results = sassLint.lintFileText(file, options);
167
// Returns empty results if file matches ignore pattern
168
```
169

170
### File System Linting
171

172
Lint files from the file system using glob patterns.
173

174
```javascript { .api }
175
/**
176
 * Lint multiple files using glob patterns
177
 * @param {string} files - Glob pattern or file path
178
 * @param {Object} options - User specified rules/options
179
 * @param {string} configPath - Path to config file
180
 * @returns {Array} Array of lint results for each file
181
 */
182
function sassLint.lintFiles(files, options, configPath);
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
// Lint all SCSS files
189
const results = sassLint.lintFiles('**/*.scss');
190

191
// Lint with custom options
192
const options = {
193
  syntax: 'scss',
194
  rules: { 'indentation': [2, { size: 2 }] }
195
};
196
const customResults = sassLint.lintFiles('src/**/*.scss', options);
197

198
// Multiple patterns (comma-separated string)
199
const multiResults = sassLint.lintFiles('src/**/*.scss, components/**/*.sass');
200

201
// Use config from file
202
const configResults = sassLint.lintFiles('**/*.scss', null, './.sass-lint.yml');
203

204
// No pattern (uses config file patterns)
205
const configFileResults = sassLint.lintFiles();
206
```
207

208
### Result Analysis
209

210
Analyze linting results to extract error and warning information.
211

212
```javascript { .api }
213
/**
214
 * Count errors in results
215
 * @param {Array} results - Array of lint results
216
 * @returns {Object} Error count and file paths with errors
217
 */
218
function sassLint.errorCount(results);
219

220
/**
221
 * Count warnings in results  
222
 * @param {Array} results - Array of lint results
223
 * @returns {Object} Warning count and file paths with warnings
224
 */
225
function sassLint.warningCount(results);
226

227
/**
228
 * Get total count of all issues
229
 * @param {Array} results - Array of lint results
230
 * @returns {number} Total count of errors and warnings
231
 */
232
function sassLint.resultCount(results);
233
```
234

235
**Result Count Objects:**
236
```javascript { .api }
237
interface CountResult {
238
  count: number;   // Total count of issues
239
  files: string[]; // Array of file paths with issues
240
}
241
```
242

243
**Usage Examples:**
244

245
```javascript
246
const results = sassLint.lintFiles('**/*.scss');
247

248
// Get error information
249
const errors = sassLint.errorCount(results);
250
console.log(`Found ${errors.count} errors in ${errors.files.length} files`);
251
console.log('Files with errors:', errors.files);
252

253
// Get warning information
254
const warnings = sassLint.warningCount(results);
255
console.log(`Found ${warnings.count} warnings`);
256

257
// Get total issue count
258
const totalIssues = sassLint.resultCount(results);
259
console.log(`Total issues: ${totalIssues}`);
260

261
// Check if any issues found
262
if (sassLint.resultCount(results) > 0) {
263
  console.log('Issues found!');
264
}
265
```
266

267
### Output Formatting
268

269
Format results using ESLint-compatible formatters.
270

271
```javascript { .api }
272
/**
273
 * Format results using specified formatter
274
 * @param {Array} results - Array of lint results
275
 * @param {Object} options - User specified rules/options
276
 * @param {string} configPath - Path to config file
277
 * @returns {string} Formatted results string
278
 */
279
function sassLint.format(results, options, configPath);
280
```
281

282
**Usage Examples:**
283

284
```javascript
285
const results = sassLint.lintFiles('**/*.scss');
286

287
// Format with default formatter (stylish)
288
const formatted = sassLint.format(results);
289
console.log(formatted);
290

291
// Format as JSON
292
const jsonFormatted = sassLint.format(results, {
293
  options: { formatter: 'json' }
294
});
295

296
// Format as compact
297
const compactFormatted = sassLint.format(results, {
298
  options: { formatter: 'compact' }
299
});
300

301
// Available formatters: stylish, compact, json, junit, checkstyle, tap, unix
302
```
303

304
### Output Results
305

306
Output formatted results to console or file.
307

308
```javascript { .api }
309
/**
310
 * Output results to console or file
311
 * @param {Array} results - Array of lint results
312
 * @param {Object} options - User specified rules/options
313
 * @param {string} configPath - Path to config file
314
 * @returns {Array} Original results array
315
 */
316
function sassLint.outputResults(results, options, configPath);
317
```
318

319
**Usage Examples:**
320

321
```javascript
322
const results = sassLint.lintFiles('**/*.scss');
323

324
// Output to console (default)
325
sassLint.outputResults(results);
326

327
// Output to file
328
sassLint.outputResults(results, {
329
  options: {
330
    'output-file': 'lint-results.txt',
331
    formatter: 'stylish'
332
  }
333
});
334

335
// JSON output to file
336
sassLint.outputResults(results, {
337
  options: {
338
    'output-file': 'results.json',
339
    formatter: 'json'
340
  }
341
});
342
```
343

344
### Error Handling
345

346
Throw errors based on linting results and thresholds.
347

348
```javascript { .api }
349
/**
350
 * Throw error if issues exceed thresholds
351
 * @param {Array} results - Array of lint results
352
 * @param {Object} options - Extra options including max-warnings
353
 * @param {string} configPath - Path to config file
354
 * @returns {void}
355
 * @throws {SassLintFailureError} When errors are found
356
 * @throws {MaxWarningsExceededError} When warnings exceed max-warnings
357
 */
358
function sassLint.failOnError(results, options, configPath);
359
```
360

361
**Usage Examples:**
362

363
```javascript
364
const results = sassLint.lintFiles('**/*.scss');
365

366
try {
367
  // Throw on any errors
368
  sassLint.failOnError(results);
369
  console.log('No errors found!');
370
} catch (error) {
371
  console.error('Linting failed:', error.message);
372
  process.exit(1);
373
}
374

375
// Set maximum warnings threshold
376
try {
377
  sassLint.failOnError(results, {
378
    options: { 'max-warnings': 5 }
379
  });
380
} catch (error) {
381
  if (error.name === 'MaxWarningsExceededError') {
382
    console.error('Too many warnings:', error.message);
383
  }
384
}
385
```
386

387
### Complete Workflow Example
388

389
```javascript
390
const sassLint = require('sass-lint');
391
const fs = require('fs');
392

393
// Complete linting workflow
394
function lintProject(pattern, configFile) {
395
  try {
396
    // Get configuration
397
    const config = sassLint.getConfig(null, configFile);
398
    console.log('Using config:', config.options.formatter);
399
    
400
    // Lint files
401
    const results = sassLint.lintFiles(pattern, null, configFile);
402
    
403
    // Analyze results
404
    const errorCount = sassLint.errorCount(results);
405
    const warningCount = sassLint.warningCount(results);
406
    
407
    console.log(`Found ${errorCount.count} errors and ${warningCount.count} warnings`);
408
    
409
    // Output results if issues found
410
    if (sassLint.resultCount(results) > 0) {
411
      sassLint.outputResults(results, null, configFile);
412
      
413
      // Save JSON report
414
      const jsonResults = sassLint.format(results, {
415
        options: { formatter: 'json' }
416
      });
417
      fs.writeFileSync('lint-report.json', jsonResults);
418
    }
419
    
420
    // Fail on errors
421
    sassLint.failOnError(results, null, configFile);
422
    
423
    return results;
424
  } catch (error) {
425
    console.error('Linting failed:', error.message);
426
    throw error;
427
  }
428
}
429

430
// Usage
431
lintProject('src/**/*.scss', './.sass-lint.yml');
432
```