or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-api.mderror-reporting.mdindex.mdrule-management.md
tile.json

configuration.mddocs/

Configuration System

CoffeeLint's configuration system provides flexible ways to customize linting behavior through hierarchical configuration discovery, rule customization, and specialized utilities for configuration management.

Capabilities

Configuration Trimming

Remove default values from configuration objects to create minimal, focused configurations.

/**
 * Remove default values from config to produce minimal configuration
 * @param userConfig - User configuration object
 * @returns Minimal configuration object with only non-default values
 */
function trimConfig(userConfig);

Usage Example:

const coffeelint = require('coffeelint');

// Configuration with both custom and default values
const fullConfig = {
  'max_line_length': {
    'level': 'error',  // default level
    'value': 80        // default value
  },
  'no_tabs': {
    'level': 'warn'    // non-default level
  },
  'indentation': {
    'level': 'error',  // default level
    'value': 2         // default value
  }
};

// Trim to only non-default values
const minimalConfig = coffeelint.trimConfig(fullConfig);
console.log(minimalConfig);
// Result: { 'no_tabs': { 'level': 'warn' } }

// Use for generating configuration files
const fs = require('fs');
fs.writeFileSync('coffeelint.json', JSON.stringify(minimalConfig, null, 2));

Literate CoffeeScript Conversion

Convert literate CoffeeScript to regular CoffeeScript format for processing.

/**
 * Convert literate CoffeeScript to regular CoffeeScript format
 * @param source - Literate CoffeeScript source code
 * @returns Regular CoffeeScript source string
 */
function invertLiterate(source);

Usage Example:

const coffeelint = require('coffeelint');

const literateSource = `
# My Application

This is a literate CoffeeScript file that documents itself.

    class Person
      constructor: (@name) ->
        @greeting = "Hello"

The Person class provides a simple greeting mechanism.

    greet: ->
      console.log "#{@greeting}, #{@name}!"

The greet method outputs a friendly message.
`;

// Convert to regular CoffeeScript
const regularSource = coffeelint.invertLiterate(literateSource);
console.log('Converted source:');
console.log(regularSource);

// Now lint the converted source
const errors = coffeelint.lint(regularSource);

Configuration Discovery

CoffeeLint automatically discovers configuration from multiple sources in a hierarchical manner:

Configuration Sources (in order of precedence)

  1. Explicit configuration - Passed directly to lint() function
  2. Project-level configuration - coffeelint.json in current or parent directories
  3. Package.json configuration - coffeelintConfig field in package.json
  4. User-level configuration - ~/.coffeelint.json in user's home directory
  5. Default configuration - Built-in rule defaults

Usage Example:

const coffeelint = require('coffeelint');

// Method 1: Explicit configuration
const explicitConfig = {
  'max_line_length': { 'level': 'error', 'value': 120 },
  'no_tabs': { 'level': 'warn' }
};
const errors1 = coffeelint.lint(source, explicitConfig);

// Method 2: Automatic discovery (searches for coffeelint.json)
const errors2 = coffeelint.lint(source); // Uses discovered config

Configuration Format

Configuration objects map rule names to rule-specific settings:

/**
 * Complete configuration structure
 */
interface CoffeeLintConfig {
  /** Rule-specific configurations */
  [ruleName: string]: RuleConfig;
  
  /** Global CoffeeLint settings */
  coffeelint?: {
    /** Source transformers to apply before linting */
    transforms?: string[];
    /** Custom CoffeeScript compiler module to use */
    coffeescript?: string;
  };
}

/**
 * Individual rule configuration
 */
interface RuleConfig {
  /** Severity level for violations */
  level: 'error' | 'warn' | 'ignore';
  /** Custom message override */
  message?: string;
  /** Rule-specific options */
  [key: string]: any;
}

Common Configuration Examples:

// Basic configuration with common rules
const basicConfig = {
  'max_line_length': {
    'level': 'error',
    'value': 100,
    'message': 'Lines should not exceed 100 characters'
  },
  'no_tabs': {
    'level': 'error'
  },
  'indentation': {
    'level': 'error',
    'value': 2
  },
  'no_trailing_whitespace': {
    'level': 'warn'
  }
};

// Advanced configuration with transformers
const advancedConfig = {
  'max_line_length': { 'level': 'error', 'value': 120 },
  'no_debugger': { 'level': 'warn' },
  
  // Global settings
  'coffeelint': {
    'transforms': ['transform-include-files'],
    'coffeescript': 'coffeescript/register'
  }
};

// Disable specific rules
const lenientConfig = {
  'no_implicit_braces': { 'level': 'ignore' },
  'no_implicit_parens': { 'level': 'ignore' },
  'max_line_length': { 'level': 'ignore' }
};

Configuration File Examples

coffeelint.json:

{
  "max_line_length": {
    "level": "error",
    "value": 120
  },
  "no_tabs": {
    "level": "error"
  },
  "indentation": {
    "level": "error", 
    "value": 2
  },
  "coffeelint": {
    "transforms": ["coffeelint-stylish"]
  }
}

package.json with coffeelintConfig:

{
  "name": "my-project",
  "version": "1.0.0",
  "coffeelintConfig": {
    "max_line_length": {
      "level": "warn",
      "value": 100
    },
    "no_trailing_whitespace": {
      "level": "error"
    }
  }
}

Environment-Specific Configuration

// Development vs Production configurations
const developmentConfig = {
  'no_debugger': { 'level': 'warn' },      // Allow debugger in dev
  'no_console': { 'level': 'ignore' },     // Allow console.log in dev
  'max_line_length': { 'level': 'warn' }   // Lenient line length
};

const productionConfig = {
  'no_debugger': { 'level': 'error' },     // Strict no debugger
  'no_console': { 'level': 'error' },      // No console output
  'max_line_length': { 'level': 'error' }  // Strict line length
};

// Conditional configuration
const config = process.env.NODE_ENV === 'production' 
  ? productionConfig 
  : developmentConfig;

const errors = coffeelint.lint(source, config);