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