tessl/npm-sass-lint

Node.js-based linting tool for Sass and SCSS files with 75+ configurable rules and both CLI and programmatic APIs.

—

Pending

Overview

Eval results

Files

Programmatic API

Name: tessl/npm-sass-lint
Author: tessl

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

Capabilities

Main Constructor

Initialize sass-lint with optional configuration.

/**
 * Main sass-lint constructor function
 * @param {Object} config - User specified rules/options
 * @returns {void}
 */
function sassLint(config);

Usage Examples:

const sassLint = require('sass-lint');

// Initialize with default config
sassLint();

// Initialize with custom config
sassLint({
  rules: {
    'indentation': [2, { size: 2 }],
    'no-ids': 1
  }
});

Configuration Management

Retrieve and compile configuration from various sources.

/**
 * Get compiled configuration object
 * @param {Object} config - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {Object} Compiled config object
 */
function sassLint.getConfig(config, configPath);

Usage Examples:

// Get default configuration
const defaultConfig = sassLint.getConfig();

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

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

// Combine custom config with file
const combinedConfig = sassLint.getConfig(
  { rules: { 'indentation': [2, { size: 4 }] } },
  './.sass-lint.yml'
);

Text Linting

Lint text content directly without file system access.

/**
 * Lint text content against rules
 * @param {Object} file - File object with text, format, and filename
 * @param {Object} options - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {Object} Lint results with error/warning counts and messages
 */
function sassLint.lintText(file, options, configPath);

File Object Structure:

interface FileObject {
  text: string;    // File content to lint
  format: string;  // 'sass' or 'scss'
  filename: string; // File path for reporting
}

Usage Examples:

// Basic text linting
const file = {
  text: '.foo { color: red; }',
  format: 'scss',
  filename: 'test.scss'
};

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

// Lint with custom options
const options = {
  rules: { 'no-color-literals': 2 }
};

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

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

// Complex example with Sass syntax
const sassFile = {
  text: `
$primary: blue
.header
  color: $primary
  margin: 0
`,
  format: 'sass',
  filename: 'header.sass'
};

const sassResults = sassLint.lintText(sassFile);

File Text Linting with Ignore Patterns

Lint text content while respecting ignore patterns from configuration.

/**
 * Lint file text with ignore pattern checking
 * @param {Object} file - File object with text, format, and filename
 * @param {Object} options - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {Object} Lint results or empty results if ignored
 */
function sassLint.lintFileText(file, options, configPath);

Usage Examples:

// File that might be ignored
const file = {
  text: '.foo { color: red; }',
  format: 'scss',
  filename: 'vendor/bootstrap.scss'
};

// With ignore patterns in config
const options = {
  files: {
    ignore: ['vendor/**']
  }
};

const results = sassLint.lintFileText(file, options);
// Returns empty results if file matches ignore pattern

File System Linting

Lint files from the file system using glob patterns.

/**
 * Lint multiple files using glob patterns
 * @param {string} files - Glob pattern or file path
 * @param {Object} options - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {Array} Array of lint results for each file
 */
function sassLint.lintFiles(files, options, configPath);

Usage Examples:

// Lint all SCSS files
const results = sassLint.lintFiles('**/*.scss');

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

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

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

// No pattern (uses config file patterns)
const configFileResults = sassLint.lintFiles();

Result Analysis

Analyze linting results to extract error and warning information.

/**
 * Count errors in results
 * @param {Array} results - Array of lint results
 * @returns {Object} Error count and file paths with errors
 */
function sassLint.errorCount(results);

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

/**
 * Get total count of all issues
 * @param {Array} results - Array of lint results
 * @returns {number} Total count of errors and warnings
 */
function sassLint.resultCount(results);

Result Count Objects:

interface CountResult {
  count: number;   // Total count of issues
  files: string[]; // Array of file paths with issues
}

Usage Examples:

const results = sassLint.lintFiles('**/*.scss');

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

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

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

// Check if any issues found
if (sassLint.resultCount(results) > 0) {
  console.log('Issues found!');
}

Output Formatting

Format results using ESLint-compatible formatters.

/**
 * Format results using specified formatter
 * @param {Array} results - Array of lint results
 * @param {Object} options - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {string} Formatted results string
 */
function sassLint.format(results, options, configPath);

Usage Examples:

const results = sassLint.lintFiles('**/*.scss');

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

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

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

// Available formatters: stylish, compact, json, junit, checkstyle, tap, unix

Output Results

Output formatted results to console or file.

/**
 * Output results to console or file
 * @param {Array} results - Array of lint results
 * @param {Object} options - User specified rules/options
 * @param {string} configPath - Path to config file
 * @returns {Array} Original results array
 */
function sassLint.outputResults(results, options, configPath);

Usage Examples:

const results = sassLint.lintFiles('**/*.scss');

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

// Output to file
sassLint.outputResults(results, {
  options: {
    'output-file': 'lint-results.txt',
    formatter: 'stylish'
  }
});

// JSON output to file
sassLint.outputResults(results, {
  options: {
    'output-file': 'results.json',
    formatter: 'json'
  }
});

Error Handling

Throw errors based on linting results and thresholds.

/**
 * Throw error if issues exceed thresholds
 * @param {Array} results - Array of lint results
 * @param {Object} options - Extra options including max-warnings
 * @param {string} configPath - Path to config file
 * @returns {void}
 * @throws {SassLintFailureError} When errors are found
 * @throws {MaxWarningsExceededError} When warnings exceed max-warnings
 */
function sassLint.failOnError(results, options, configPath);

Usage Examples:

const results = sassLint.lintFiles('**/*.scss');

try {
  // Throw on any errors
  sassLint.failOnError(results);
  console.log('No errors found!');
} catch (error) {
  console.error('Linting failed:', error.message);
  process.exit(1);
}

// Set maximum warnings threshold
try {
  sassLint.failOnError(results, {
    options: { 'max-warnings': 5 }
  });
} catch (error) {
  if (error.name === 'MaxWarningsExceededError') {
    console.error('Too many warnings:', error.message);
  }
}

Complete Workflow Example

const sassLint = require('sass-lint');
const fs = require('fs');

// Complete linting workflow
function lintProject(pattern, configFile) {
  try {
    // Get configuration
    const config = sassLint.getConfig(null, configFile);
    console.log('Using config:', config.options.formatter);
    
    // Lint files
    const results = sassLint.lintFiles(pattern, null, configFile);
    
    // Analyze results
    const errorCount = sassLint.errorCount(results);
    const warningCount = sassLint.warningCount(results);
    
    console.log(`Found ${errorCount.count} errors and ${warningCount.count} warnings`);
    
    // Output results if issues found
    if (sassLint.resultCount(results) > 0) {
      sassLint.outputResults(results, null, configFile);
      
      // Save JSON report
      const jsonResults = sassLint.format(results, {
        options: { formatter: 'json' }
      });
      fs.writeFileSync('lint-report.json', jsonResults);
    }
    
    // Fail on errors
    sassLint.failOnError(results, null, configFile);
    
    return results;
  } catch (error) {
    console.error('Linting failed:', error.message);
    throw error;
  }
}

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

Install with Tessl CLI