tessl/npm-cspell

A comprehensive spell checking tool specifically designed for source code with CLI interface and programmatic API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CSpell

Name: tessl/npm-cspell
Author: tessl

CSpell is a comprehensive spell checking tool specifically designed for source code. It provides fast and accurate spell checking across multiple programming languages and file types, with intelligent parsing that handles CamelCase, snake_case, and compound word naming conventions.

Package Information

Package Name: cspell
Package Type: npm
Language: TypeScript
Installation: npm install -g cspell (CLI) or npm install cspell (library)

Core Imports

ESM:

import { lint, trace, checkText, suggestions, createInit } from "cspell";
import { run } from "cspell/app";

CommonJS:

const { lint, trace, checkText, suggestions, createInit } = require("cspell");
const { run } = require("cspell/app");

CLI usage:

cspell "**/*.js"
npx cspell lint "src/**/*.ts"

Basic Usage

CLI spell checking:

# Check all JavaScript files recursively
cspell "src/**/*.js"

# Check specific files with custom config
cspell lint "*.md" --config ./custom-cspell.json

# Interactive spell checking with color highlighting
cspell check README.md

# Get suggestions for misspelled words
cspell suggestions "teh" "recieve"

Programmatic usage:

import { lint, createInit } from "cspell";

// Initialize a configuration file first
await createInit({
  output: "./cspell.json",
  format: "json",
  locale: ["en-US"],
  dictionary: ["typescript", "node"]
});

// Spell check files programmatically
const result = await lint(
  ["src/**/*.js", "docs/**/*.md"],
  {
    verbose: true,
    showSuggestions: true,
    config: "./cspell.json"
  }
);

console.log(`Found ${result.issues} spelling issues`);
console.log(`Checked ${result.files} files`);

Architecture

CSpell is built around several key components:

CLI Interface: Complete command-line tool with 8 major commands for different spell checking workflows
Programmatic API: Core functions for lint, trace, check, and suggestions that can be integrated into other tools
Configuration System: Flexible configuration management with JSON/YAML support and global/local settings
Dictionary Engine: Integration with specialized dictionaries for different programming languages and domains
Reporter System: Extensible reporting with custom output formats, templates, and styling
Cache System: Performance optimization through intelligent file caching

Capabilities

CLI Commands

Complete command-line interface with comprehensive spell checking commands including lint, check, trace, suggestions, init, config, link, and dictionaries management.

# Primary commands
cspell [options] [globs...]           # Default lint command
cspell lint [options] [globs...]      # Explicit lint command
cspell check [files...]               # Interactive checking with colors
cspell trace [words...]               # Debug word lookup
cspell suggestions [words...]         # Get spelling suggestions
cspell init [options]                 # Initialize configuration
cspell config [options]               # Update configuration
cspell link <subcommand>              # Manage global links
cspell dictionaries [options]         # List dictionaries

CLI Commands

Programmatic API

Core spell checking functions for integration into Node.js applications, providing lint, trace, check, and suggestion capabilities with full TypeScript support.

function lint(
  fileGlobs: string[], 
  options: LinterCliOptions, 
  reporter?: CSpellReporter
): Promise<RunResult>;

function trace(words: string[], options: TraceOptions): AsyncIterableIterator<TraceWordResult>;

function checkText(filename: string, options: BaseOptions & LegacyOptions): Promise<CheckTextResult>;

function suggestions(words: string[], options: SuggestionOptions): AsyncIterable<TimedSuggestionsForWordResult>;

function createInit(options: InitOptions): Promise<void>;

Programmatic API

Configuration Management

Configuration initialization and management system for creating and updating CSpell configuration files with support for multiple formats and import/export capabilities.

function createInit(options: InitOptions): Promise<void>;

interface InitOptions {
  config?: string;
  output?: string;
  format?: string;
  import?: string[];
  locale?: string[];
  dictionary?: string[];
  comments?: boolean;
  schema?: boolean;
  stdout?: boolean;
}

Configuration

Reporter System

Extensible reporting system with built-in reporters and support for custom reporter modules, template-based output formatting, and color styling.

function getDefaultReporter(options: ReporterOptions, config?: CSpellReporterConfiguration): CSpellReporter;

interface CSpellReporterConfiguration extends ReporterConfiguration, LinterCliOptions {
  readonly console?: ReporterConsole;
}

interface CSpellReporterModule {
  getReporter: <T>(settings: T, config: CSpellReporterConfiguration) => CSpellReporter;
}

Reporter System

Core Types

interface RunResult {
  files: number;
  filesWithIssues: Set<string>;
  issues: number;
  errors: number;
  cachedFiles: number;
}

interface TraceWordResult {
  word: string;
  found: boolean;
  foundWord?: string;
  forbidden?: boolean;
  noSuggest?: boolean;
  dictionaries: DictionaryTraceResult[];
}

interface CheckTextResult {
  document: TextDocument;
  options: CSpellSettings;
  issues: TextIssue[];
}

interface TimedSuggestionsForWordResult extends SuggestionsForWordResult {
  elapsedTimeMs?: number;
}

interface LinterCliOptions extends BaseOptions, CacheOptions, ReporterConfiguration {
  verbose?: boolean;
  debug?: boolean;
  exclude?: string[] | string;
  wordsOnly?: boolean;
  unique?: boolean;
  root?: string;
  dot?: boolean;
  showContext?: boolean | number;
  showSuggestions?: boolean;
  cache?: boolean;
  cacheLocation?: string;
  gitignore?: boolean;
  reporter?: string[];
  issueTemplate?: string;
}

interface BaseOptions {
  config?: string;
  locale?: string;
  languageId?: string;
  defaultConfiguration?: boolean;
}

interface TraceOptions extends BaseOptions {
  allowCompoundWords?: boolean;
  ignoreCase?: boolean;
  dictionary?: string[];
  stdin?: boolean;
}

interface SuggestionOptions extends BaseOptions {
  numChanges?: number;
  numSuggestions?: number;
  includeTies?: boolean;
  repl?: boolean;
  useStdin?: boolean;
  ignoreCase?: boolean;
}

Error Handling

CSpell uses custom error classes for different failure scenarios:

class ApplicationError extends Error {
  readonly exitCode: number;
  readonly cause?: Error | undefined;
  constructor(message: string, exitCode?: number, cause?: Error | undefined);
}

class CheckFailed extends Error {
  readonly exitCode: number;
  constructor(message: string, exitCode?: number);
}

Common error scenarios:

Node.js version compatibility: Throws ApplicationError for unsupported Node.js versions
Configuration errors: Invalid or missing configuration files
Dictionary loading errors: Missing or corrupted dictionary files
File access errors: Permission or path issues when reading files
Spell check failures: When files contain spelling errors (uses exit codes)