Configuration

# Configuration file discovery order (highest to lowest priority):
1. Path specified by -c/--config CLI option or configPath parameter
2. .sass-lint.yml in current directory or parent directories
3. .sasslintrc in current directory or parent directories
4. sasslintConfig property in package.json
5. Default built-in configuration

# Explicit config file
sass-lint -c custom-config.yml

# Auto-discovery (searches up directory tree)
.sass-lint.yml      # Found first
../sass-lint.yml    # Searched if not found locally
../../.sasslintrc    # Searched if .sass-lint.yml not found

# Supported configuration files:
.sass-lint.yml       # Primary YAML format
.sasslintrc         # Alternative YAML format (no extension)
.sass-lint.json     # JSON format (if YAML parsing fails)
package.json        # sasslintConfig property

# Global options
options:
  formatter: stylish
  merge-default-rules: true
  cache-config: false
  max-warnings: 50

# File inclusion/exclusion patterns
files:
  include: '**/*.s+(a|c)ss'
  ignore:
    - 'node_modules/**'
    - 'vendor/**'
    - '**/*.min.scss'

# Rule configuration
rules:
  indentation:
    - 2  # error severity
    - size: 2  # 2 spaces
  
  no-ids: 2
  
  class-name-format:
    - 1  # warning severity
    - convention: hyphenatedlowercase
      allow-leading-underscore: true

{
  "options": {
    "formatter": "stylish",
    "merge-default-rules": true,
    "cache-config": false
  },
  "files": {
    "include": "**/*.s+(a|c)ss",
    "ignore": ["node_modules/**", "vendor/**"]
  },
  "rules": {
    "indentation": [2, {"size": 2}],
    "no-ids": 2,
    "class-name-format": [1, {
      "convention": "hyphenatedlowercase",
      "allow-leading-underscore": true
    }]
  }
}

{
  "name": "my-project",
  "sasslintConfig": {
    "rules": {
      "indentation": [2, {"size": 4}],
      "no-ids": 2
    },
    "files": {
      "ignore": ["dist/**"]
    }
  }
}

options:
  # Output formatter (uses ESLint formatters)
  formatter: stylish  # stylish, compact, json, junit, checkstyle, tap, unix
  
  # Rule inheritance behavior
  merge-default-rules: true   # Merge with built-in rules (true) or replace (false)
  
  # Configuration caching
  cache-config: false         # Cache parsed config for performance
  
  # Warning threshold
  max-warnings: 50           # Maximum warnings before error exit code
  
  # Output file path
  output-file: results.txt   # Write results to file instead of console

files:
  # Files to include (glob patterns)
  include: '**/*.s+(a|c)ss'  # Single pattern
  include:                   # Multiple patterns
    - 'src/**/*.scss'
    - 'components/**/*.sass'
  
  # Files to exclude (glob patterns)
  ignore: 'node_modules/**'  # Single pattern
  ignore:                    # Multiple patterns
    - 'node_modules/**'
    - 'vendor/**'
    - 'dist/**'
    - '**/*.min.scss'

files:
  include:
    - 'src/**/*.scss'           # All SCSS files in src directory
    - 'components/**/*.sass'    # All Sass files in components directory
    - '**/*.s+(a|c)ss'         # All Sass and SCSS files anywhere
  
  ignore:
    - 'node_modules/**'        # Exclude node_modules
    - 'vendor/**'              # Exclude vendor directory
    - '**/temp/**'             # Exclude any temp directories
    - '**/*.min.{scss,sass}'   # Exclude minified files
    - 'legacy/**'              # Exclude legacy code

rules:
  # Simple rule with severity only
  rule-name: 0  # 0 = off, 1 = warning, 2 = error
  
  # Rule with severity and options
  rule-name:
    - 2          # severity level
    - option1: value1
      option2: value2

# Rule severity options
0  # Off - rule is completely disabled
1  # Warning - rule violation generates warning (exit code 0)
2  # Error - rule violation generates error (exit code 1)

rules:
  # Indentation with spaces
  indentation:
    - 2
    - size: 2  # 2 spaces
  
  # Indentation with tabs
  indentation:
    - 2
    - size: tab
  
  # Class naming convention
  class-name-format:
    - 1
    - convention: hyphenatedlowercase  # or camelcase, snakecase, strictbem
      allow-leading-underscore: true
      ignore: ['js-*']  # Ignore classes starting with 'js-'
  
  # Property sort order
  property-sort-order:
    - 1
    - order: alphabetical  # or smacss, recess, concentric, or custom array
  
  # Custom property order
  property-sort-order:
    - 1
    - order:
        - display
        - position
        - top
        - right
        - bottom
        - left
        # ... etc

property-sort-order:
  - 1
  - order: alphabetical  # Built-in orders
  # Built-in options: alphabetical, smacss, recess, concentric

property-sort-order:
  - 1
  - order:
      # Positioning
      - position
      - top
      - right
      - bottom
      - left
      - z-index
      
      # Display & Box Model
      - display
      - flex
      - flex-direction
      - justify-content
      - align-items
      
      # Dimensions
      - width
      - height
      - padding
      - margin
      
      # Visual
      - background
      - color
      - font-family
      - font-size

# Extend built-in configurations
extends: sass-lint:recommended  # Use built-in recommended rules

# Override specific rules after extending
rules:
  indentation:
    - 2
    - size: 4  # Override default indentation
  no-ids: 0   # Disable no-ids rule

// sass-lint:disable rule-name
.exception {
  color: red !important;  // !important allowed here
}
// sass-lint:enable rule-name

// Disable multiple rules
// sass-lint:disable no-important, no-color-literals
.special {
  color: red !important;
}
// sass-lint:enable no-important, no-color-literals

// Disable rule for single line
color: red !important; // sass-lint:disable-line no-important

// Disable all rules for block
// sass-lint:disable-all
.legacy-code {
  // Any violations ignored
}
// sass-lint:enable-all

# Base configuration
options:
  formatter: stylish

# Stricter rules for production
rules: &strict-rules
  no-important: 2
  no-color-literals: 2
  max-nesting-depth: [2, {max-depth: 2}]

# Development overrides
rules:
  <<: *strict-rules
  no-important: 1      # Warnings only in development
  no-color-literals: 1

# Priority order (highest to lowest):
1. CLI options (--format, --config, etc.)
2. Configuration file rules
3. Default configuration

# Override formatter
sass-lint --format json  # Overrides config formatter

# Override config file
sass-lint --config strict.yml  # Uses strict.yml instead of .sass-lint.yml

# Override ignore patterns
sass-lint --ignore 'vendor/**, temp/**'

# Common configuration errors:
# - Invalid YAML syntax
# - Unknown rule names
# - Invalid rule options
# - Invalid severity levels (not 0, 1, or 2)
# - Invalid file patterns

# Invalid severity level
rules:
  no-ids: 3  # Error: severity must be 0, 1, or 2

# Unknown rule name
rules:
  no-typo: 2  # Error: unknown rule 'no-typo'

# Invalid rule option
rules:
  indentation:
    - 2
    - invalid-option: true  # Error: unknown option

# Complete .sass-lint.yml example
options:
  formatter: stylish
  merge-default-rules: true
  cache-config: false
  max-warnings: 25

files:
  include: 
    - 'src/**/*.scss'
    - 'components/**/*.sass'
  ignore:
    - 'node_modules/**'
    - 'vendor/**'
    - 'dist/**'
    - '**/*.min.scss'

rules:
  # Extends
  extends-before-mixins: 2
  extends-before-declarations: 2
  placeholder-in-extend: 2
  
  # Mixins
  mixins-before-declarations: 2
  
  # Line Spacing
  one-declaration-per-line: 2
  empty-line-between-blocks: 1
  single-line-per-selector: 2
  
  # Naming Conventions
  class-name-format:
    - 2
    - convention: hyphenatedlowercase
      allow-leading-underscore: true
  
  variable-name-format:
    - 2
    - convention: hyphenatedlowercase
      allow-leading-underscore: true
  
  # Style Guide
  indentation:
    - 2
    - size: 2
  
  quotes:
    - 2
    - style: single
  
  property-sort-order:
    - 1
    - order: smacss
  
  # Restrictions
  no-ids: 2
  no-important: 1
  no-color-literals:
    - 2
    - allow-rgba: true
      allow-variable-identifiers: true
  
  nesting-depth:
    - 2
    - max-depth: 3
  
  # Spacing
  space-after-colon: 2
  space-before-brace: 2
  space-after-comma: 2
  
  # Final formatting
  trailing-semicolon: 2
  final-newline: 2