0
# Sass Lint
1
2
Sass Lint is a Node.js-based linting tool for Sass and SCSS files that provides comprehensive code quality enforcement through 73 configurable rules. It offers both command-line interface and programmatic API with extensive configuration options, multiple output formats, and integration support for build systems and editors.
3
4
## Package Information
5
6
- **Package Name**: sass-lint
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install sass-lint`
10
11
## Core Imports
12
13
```javascript
14
const sassLint = require('sass-lint');
15
```
16
17
For ES modules:
18
19
```javascript
20
import sassLint from 'sass-lint';
21
```
22
23
## Basic Usage
24
25
### CLI Usage
26
27
```bash
28
# Lint all Sass/SCSS files in current directory
29
sass-lint '**/*.scss' -v
30
31
# Use custom config file
32
sass-lint -c .sass-lint.yml 'src/**/*.scss'
33
34
# Output results to file
35
sass-lint '**/*.scss' -f json -o results.json
36
```
37
38
### Programmatic Usage
39
40
```javascript
41
const sassLint = require('sass-lint');
42
43
// Get configuration
44
const config = sassLint.getConfig();
45
46
// Lint text content
47
const file = {
48
text: '.foo { color: red; }',
49
format: 'scss',
50
filename: 'test.scss'
51
};
52
53
const results = sassLint.lintText(file);
54
console.log(results);
55
56
// Lint multiple files
57
const fileResults = sassLint.lintFiles('src/**/*.scss');
58
sassLint.outputResults(fileResults);
59
```
60
61
## Architecture
62
63
Sass Lint is built around several key components:
64
65
- **Rule System**: 73 rules covering syntax, formatting, best practices, and Sass-specific concerns
66
- **Configuration Engine**: YAML/JSON configuration with inheritance and rule customization
67
- **AST Parser**: Integration with gonzales-pe-sl for Sass/SCSS syntax tree generation
68
- **CLI Interface**: Command-line tool with extensive options and output formats
69
- **Programmatic API**: Full Node.js API for integration with build tools and editors
70
- **Formatter Integration**: ESLint-compatible formatters for various output formats
71
72
## Capabilities
73
74
### Command Line Interface
75
76
Complete CLI tool for linting Sass/SCSS files with configurable options, output formats, and ignore patterns.
77
78
```bash { .api }
79
sass-lint [options] [pattern]
80
```
81
82
**Options:**
83
- `-c, --config [path]` - path to custom config file
84
- `-i, --ignore [pattern]` - pattern to ignore files
85
- `-q, --no-exit` - do not exit on errors
86
- `-v, --verbose` - verbose output
87
- `-f, --format [format]` - output format (stylish, compact, json, etc.)
88
- `-o, --output [output]` - output file path
89
- `-s, --syntax [syntax]` - syntax type (sass or scss)
90
- `--max-warnings [integer]` - max warnings before exit code
91
92
[CLI Usage](./cli.md)
93
94
### Programmatic API
95
96
Core Node.js API for integrating sass-lint into applications, build tools, and editors with full configuration and result processing.
97
98
```javascript { .api }
99
// Main constructor
100
function sassLint(config);
101
102
// Configuration
103
function sassLint.getConfig(config, configPath);
104
105
// Linting functions
106
function sassLint.lintText(file, options, configPath);
107
function sassLint.lintFileText(file, options, configPath);
108
function sassLint.lintFiles(files, options, configPath);
109
110
// Result processing
111
function sassLint.errorCount(results);
112
function sassLint.warningCount(results);
113
function sassLint.resultCount(results);
114
function sassLint.format(results, options, configPath);
115
function sassLint.outputResults(results, options, configPath);
116
function sassLint.failOnError(results, options, configPath);
117
```
118
119
[Programmatic API](./api.md)
120
121
### Linting Rules
122
123
Comprehensive rule system with 73 rules covering indentation, spacing, naming conventions, selector complexity, property ordering, and Sass-specific concerns.
124
125
```javascript { .api }
126
// Rule categories include:
127
// - Extends and Mixins rules
128
// - Line spacing and formatting rules
129
// - Disallow/restriction rules
130
// - Nesting depth and structure rules
131
// - Name format convention rules
132
// - Style guide enforcement rules
133
// - Spacing and punctuation rules
134
// - Final formatting rules
135
```
136
137
[Linting Rules](./rules.md)
138
139
### Configuration System
140
141
Flexible configuration system supporting YAML/JSON files, package.json integration, rule inheritance, and custom property sort orders.
142
143
```javascript { .api }
144
// Configuration sources
145
// - .sass-lint.yml (primary config file)
146
// - .sasslintrc (alternative config file)
147
// - package.json sasslintConfig property
148
// - Command-line options
149
// - Programmatic config objects
150
```
151
152
[Configuration](./configuration.md)
153
154
## Types
155
156
```javascript { .api }
157
interface LintResult {
158
filePath: string;
159
warningCount: number;
160
errorCount: number;
161
messages: LintMessage[];
162
}
163
164
interface LintMessage {
165
ruleId: string;
166
line: number;
167
column: number;
168
message: string;
169
severity: number; // 1 = warning, 2 = error
170
}
171
172
interface FileObject {
173
text: string;
174
format: string; // 'sass' or 'scss'
175
filename: string;
176
}
177
178
interface ConfigObject {
179
rules: { [ruleName: string]: RuleConfig };
180
files: {
181
include: string | string[];
182
ignore: string | string[];
183
};
184
options: {
185
formatter: string;
186
'merge-default-rules': boolean;
187
'cache-config': boolean;
188
'max-warnings': number;
189
'output-file'?: string;
190
};
191
}
192
193
interface RuleConfig {
194
severity: number; // 0 = off, 1 = warning, 2 = error
195
[option: string]: any; // Rule-specific options
196
}
197
198
interface CountResult {
199
count: number;
200
files: string[];
201
}
202
203
class SassLintFailureError extends Error {
204
name: 'SassLintFailureError';
205
message: string;
206
}
207
208
class MaxWarningsExceededError extends Error {
209
name: 'MaxWarningsExceededError';
210
message: string;
211
}
212
```