Language-agnostic code formatter with configurable rules and plugin support

📚 Documentation • 🚀 Getting Started • 🔌 Plugins • 📖 API Reference

🚀 Features

• Language-agnostic: Works with any kind of text file
• SOLID architecture: Modular and extensible design
• Plugin system: Extend functionality without changing the core code
• Interactive CLI: Command-line interface with interactive mode
• Configurable rules: Customize formatting to fit your needs
• High test coverage: Over 80% code coverage

📦 Installation

npm install @codewaveinnovation/formatter

For global CLI usage:

npm install -g @codewaveinnovation/formatter

🎯 Usage

CLI

Format files

Format a single file:

cwf format file.txt

Format multiple files with glob patterns:

cwf format "src/**/*.ts"        # All TypeScript files in src/
cwf format "*.js" "*.ts"        # All JS and TS files in current dir
cwf format src/ test/           # All files in src/ and test/ directories

Interactive mode

cwf format file.txt --interactive

Use a configuration file

cwf format file.txt --config .cwfrc.json

Auto-discovery of configuration

The CLI automatically searches for configuration files in the current directory:

cwf format file.txt
# Looks for .cwfrc.json, .cwfrc, or package.json (formatter key)

Supported config locations (in order of priority):

• .cwfrc.json
• .cwfrc
• package.json under "formatter" key

Check formatting without modifying

cwf check file.txt

Create a default configuration file

cwf init

Programmatic API

import { createFormatter, getDefaultConfig } from '@codewaveinnovation/formatter';

// Create a formatter with default rules
const formatter = createFormatter();
const config = getDefaultConfig();

// Format content
const result = await formatter.format('  hello world  ', config);
console.log(result.content); // 'hello world\n'
console.log(result.changed); // true
console.log(result.appliedRules); // ['trailing-whitespace', 'final-newline']

Custom configuration

import { createFormatter, FormatterConfig } from '@codewaveinnovation/formatter';

const formatter = createFormatter();

const customConfig: FormatterConfig = {
  rules: [
    { 
      name: 'indentation', 
      enabled: true, 
      options: { style: 'space', size: 4 } 
    },
    { 
      name: 'line-ending', 
      enabled: true, 
      options: { style: 'lf' } 
    },
    { 
      name: 'trailing-whitespace', 
      enabled: true 
    },
    { 
      name: 'final-newline', 
      enabled: true, 
      options: { insert: true } 
    },
  ],
};

const result = await formatter.format(code, customConfig);

📋 Available Rules

indentation

Normalizes indentation to spaces or tabs.

Options:

• style: 'space' | 'tab' (default: 'space')
• size: number of spaces per level (default: 2)

line-ending

Normalizes line endings.

Options:

• style: 'lf' | 'crlf' | 'cr' (default: 'lf')

trailing-whitespace

Removes trailing whitespace at the end of lines.

final-newline

Ensures the file ends with a newline.

Options:

• insert: boolean (default: true)

max-line-length

Controls the maximum length of lines.

Options:

• length: number of characters (default: 80)
• action: 'warn' | 'wrap' (default: 'warn')

🔌 Plugin System

Create your own plugin to extend functionality:

import { BasePlugin, IFormattingRule } from '@codewaveinnovation/formatter';
import { MyCustomRule } from './my-custom-rule';

export class MyPlugin extends BasePlugin {
  readonly name = 'my-plugin';
  readonly version = '1.0.0';

  getRules(): IFormattingRule[] {
    return [new MyCustomRule()];
  }
}

Load the plugin:

import { RuleRegistry, PluginManager, CodeFormatter } from '@codewaveinnovation/formatter';
import { MyPlugin } from './my-plugin';

const registry = new RuleRegistry();
const pluginManager = new PluginManager(registry);
const myPlugin = new MyPlugin();

pluginManager.loadPlugin(myPlugin);

const formatter = new CodeFormatter(registry);

🏗️ SOLID Architecture

The project follows the SOLID principles:

• Single Responsibility: Each class has a single responsibility
• Open/Closed: Open for extension (plugins), closed for modification
• Liskov Substitution: Implementations can be substituted by their interfaces
• Interface Segregation: Specific interfaces instead of general ones
• Dependency Inversion: Depend on abstractions, not concretions

🧪 Tests

Run tests:

npm test

View coverage:

npm run test:coverage

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Run linter
npm run lint

# Run tests
npm test

📄 License

MIT © CodeWave Innovation

🤝 Contributing

Contributions are welcome. Please open an issue or pull request for suggestions or improvements.

📚 Additional documentation

Configuration file (.cwfrc.json)

{
  "rules": [
    {
      "name": "indentation",
      "enabled": true,
      "options": {
        "style": "space",
        "size": 2
      }
    },
    {
      "name": "line-ending",
      "enabled": true,
      "options": {
        "style": "lf"
      }
    },
    {
      "name": "trailing-whitespace",
      "enabled": true
    },
    {
      "name": "final-newline",
      "enabled": true,
      "options": {
        "insert": true
      }
    }
  ]
}