Reporter System

/**
 * Main reporter interface for CSpell spell checking events
 */
interface CSpellReporter {
  /** Handle spelling issues */
  issue: (issue: Issue) => void;
  
  /** Emit informational messages */
  info: MessageEmitter;
  
  /** Emit debug messages */
  debug: DebugEmitter;
  
  /** Emit error messages */
  error: ErrorEmitter;
  
  /** Emit progress events */
  progress: ProgressEmitter;
  
  /** Emit final results */
  result: ResultEmitter;
}

/**
 * Collection of reporter emitter functions
 */
interface CSpellReporterEmitters {
  /** Issue emitter */
  issue?: SpellingErrorEmitter;
  
  /** Information message emitter */
  info?: MessageEmitter;
  
  /** Debug message emitter */
  debug?: DebugEmitter;
  
  /** Error message emitter */
  error?: ErrorEmitter;
  
  /** Progress event emitter */
  progress?: ProgressEmitter;
  
  /** Result emitter */
  result?: ResultEmitter;
}

/**
 * Reporter module interface for loadable reporters
 */
interface CSpellReporterModule {
  /** Create reporter instance */
  getReporter: (settings: ReporterConfiguration, config: CSpellSettings) => CSpellReporter;
}

/**
 * Spelling issue with location and context information
 */
interface Issue extends TextDocumentOffset {
  /** The misspelled text */
  text: string;
  
  /** Suggested corrections */
  suggestions?: Suggestion[];
  
  /** Type of issue (spelling or directive) */
  issueType: IssueType;
  
  /** Issue context information */
  context?: {
    /** Text before the issue */
    before: string;
    
    /** Text after the issue */
    after: string;
  };
  
  /** Rule that triggered the issue */
  rule?: string;
  
  /** Additional issue metadata */
  data?: Record<string, any>;
}

/**
 * Spelling suggestion with preference and confidence
 */
interface Suggestion {
  /** Suggested word */
  word: string;
  
  /** Suggestion preference/confidence (0-1) */
  cost: number;
  
  /** Whether suggestion adjusts case */
  adjustedCase?: boolean;
  
  /** Whether suggestion is preferred */
  isPreferred?: boolean;
}

/**
 * Issue type enumeration
 */
enum IssueType {
  /** Spelling issue */
  spelling = 0,
  
  /** Directive issue */
  directive = 1
}

/**
 * Base progress event interface
 */
interface ProgressBase {
  /** Progress type identifier */
  type: ProgressTypes;
  
  /** Timestamp of progress event */
  timestamp: number;
  
  /** Current progress value */
  current: number;
  
  /** Total expected items */
  total: number;
  
  /** Progress message */
  message?: string;
}

/**
 * File-based progress event base
 */
interface ProgressFileBase extends ProgressBase {
  /** File being processed */
  filename: string;
  
  /** File size in bytes */
  fileSize?: number;
  
  /** Processing stage */
  stage?: string;
}

/**
 * File processing start event
 */
interface ProgressFileBegin extends ProgressFileBase {
  type: "ProgressFileBegin";
  
  /** Number of files remaining */
  remaining: number;
}

/**
 * File processing completion event
 */
interface ProgressFileComplete extends ProgressFileBase {
  type: "ProgressFileComplete";
  
  /** Number of issues found */
  numErrors: number;
  
  /** Processing was successful */
  success: boolean;
  
  /** Processing duration in milliseconds */
  elapsedTimeMs: number;
}

/**
 * Individual progress item
 */
interface ProgressItem {
  /** Item identifier */
  id: string;
  
  /** Item description */
  description: string;
  
  /** Item completion status */
  completed: boolean;
  
  /** Item progress percentage (0-100) */
  progress: number;
}

/**
 * Progress event type identifiers
 */
type ProgressTypes = 
  | "ProgressFileBegin"
  | "ProgressFileComplete"
  | "Progress"
  | "ProgressIssues";

/**
 * Results of a spell checking run
 */
interface RunResult {
  /** Total number of files processed */
  files: number;
  
  /** Set of files that had issues */
  filesWithIssues: Set<string>;
  
  /** Total number of issues found */
  issues: number;
  
  /** Number of errors encountered */
  errors: number;
  
  /** Processing was successful */
  success?: boolean;
  
  /** Total processing time in milliseconds */
  elapsedTimeMs?: number;
  
  /** Additional result metadata */
  [key: string]: any;
}

/**
 * Reporter configuration settings
 */
interface ReporterConfiguration {
  /** Reporter module name or path */
  reporter: string;
  
  /** Reporter-specific options */
  options?: Record<string, any>;
  
  /** Output file path */
  outFile?: string;
  
  /** Output format */
  format?: string;
}

/**
 * Reporting system configuration
 */
interface ReportingConfiguration {
  /** Unique unknown words reporting */
  unique?: boolean;
  
  /** Unknown words configuration */
  unknownWords?: UnknownWordsConfiguration;
  
  /** Report suggestions */
  suggestions?: boolean;
  
  /** Report context around issues */
  context?: boolean | number;
  
  /** Additional reporting options */
  [key: string]: any;
}

/**
 * Configuration for handling unknown words
 */
interface UnknownWordsConfiguration {
  /** How to handle unknown words */
  choice: UnknownWordsChoices;
  
  /** Output file for unknown words */
  output?: string;
  
  /** Include suggestions in unknown words report */
  suggestions?: boolean;
}

/**
 * Unknown words handling choices
 */
type UnknownWordsChoices = "ignore" | "warn" | "error" | "save";

/** Constants for unknown words choices */
declare const unknownWordsChoices: {
  ignore: "ignore";
  warn: "warn";  
  error: "error";
  save: "save";
};

/**
 * Features supported by a reporter implementation
 */
interface FeaturesSupportedByReporter {
  /** Supports issue reporting */
  issues?: boolean;
  
  /** Supports progress reporting */
  progress?: boolean;
  
  /** Supports debug output */
  debug?: boolean;
  
  /** Supports informational messages */
  info?: boolean;
  
  /** Supports error reporting */
  errors?: boolean;
  
  /** Supports result summaries */
  results?: boolean;
  
  /** Additional feature flags */
  [feature: string]: boolean | undefined;
}

/**
 * Options for reporting individual issues
 */
interface ReportIssueOptions {
  /** Include suggestions in report */
  includeSuggestions?: boolean;
  
  /** Maximum number of suggestions */
  maxSuggestions?: number;
  
  /** Include context around issue */
  includeContext?: boolean;
  
  /** Number of context characters */
  contextLength?: number;
  
  /** Format suggestions */
  formatSuggestions?: boolean;
  
  /** Additional reporting options */
  [key: string]: any;
}

/**
 * Generic message emitter function
 */
type MessageEmitter = (message: string, msgType?: MessageType) => void;

/**
 * Debug message emitter function
 */
type DebugEmitter = (message: string) => void;

/**
 * Error emitter function  
 */
type ErrorEmitter = (message: string, error: ErrorLike) => void;

/**
 * Progress event emitter function
 */
type ProgressEmitter = (progress: ProgressBase) => void;

/**
 * Result emitter function
 */
type ResultEmitter = (result: RunResult) => void;

/**
 * Spelling error emitter function
 */
type SpellingErrorEmitter = (issue: Issue) => void;

/**
 * Error-like object interface
 */
interface ErrorLike {
  /** Error message */
  message: string;
  
  /** Error name */
  name?: string;
  
  /** Error stack trace */
  stack?: string;
  
  /** Additional error properties */
  [key: string]: any;
}

/**
 * Message type identifier
 */
type MessageType = keyof MessageTypeLookup;

/**
 * Message type lookup interface
 */
interface MessageTypeLookup {
  /** Informational message */
  info: "Info";
  
  /** Warning message */
  warning: "Warning";
  
  /** Error message */
  error: "Error";
  
  /** Debug message */
  debug: "Debug";
}

/** Message type lookup object */
declare const MessageTypes: MessageTypeLookup;

/**
 * Basic text offset information
 */
interface TextOffset {
  /** Character offset in text */
  offset: number;
  
  /** Length of text segment */
  length: number;
}

/**  
 * Text offset with document location information
 */
interface TextDocumentOffset extends TextOffset {
  /** Document URI or filename */
  uri?: string;
  
  /** Document filename */
  filename?: string;
  
  /** Line number (1-based) */
  line: number;
  
  /** Column number (1-based) */
  col: number;
  
  /** Row number (alias for line) */
  row?: number;
  
  /** Document text content */
  text?: string;
}

import type { 
  CSpellReporter, 
  Issue, 
  RunResult, 
  ProgressBase 
} from "@cspell/cspell-types";

class CustomReporter implements CSpellReporter {
  private issues: Issue[] = [];
  
  issue = (issue: Issue): void => {
    this.issues.push(issue);
    console.log(`Issue in ${issue.filename}: ${issue.text}`);
    
    if (issue.suggestions?.length) {
      console.log(`  Suggestions: ${issue.suggestions.map(s => s.word).join(", ")}`);
    }
  };
  
  info = (message: string): void => {
    console.log(`INFO: ${message}`);
  };
  
  debug = (message: string): void => {
    if (process.env.DEBUG) {
      console.log(`DEBUG: ${message}`);
    }
  };
  
  error = (message: string, error: ErrorLike): void => {
    console.error(`ERROR: ${message}`, error);
  };
  
  progress = (progress: ProgressBase): void => {
    console.log(`Progress: ${progress.current}/${progress.total} - ${progress.message}`);
  };
  
  result = (result: RunResult): void => {
    console.log(`\nSpell check complete:`);
    console.log(`  Files: ${result.files}`);
    console.log(`  Issues: ${result.issues}`);
    console.log(`  Errors: ${result.errors}`);
    console.log(`  Success: ${result.success ?? result.errors === 0}`);
  };
}

import type { ReporterConfiguration, CSpellUserSettings } from "@cspell/cspell-types";

// Built-in reporter configuration
const reporterConfig: ReporterConfiguration = {
  reporter: "@cspell/cspell-json-reporter",
  options: {
    verbose: true,
    progress: true
  },
  outFile: "./spell-check-results.json"
};

// CSpell configuration with custom reporter
const config: CSpellUserSettings = {
  reporters: [
    ["@cspell/cspell-json-reporter", { outFile: "results.json" }],
    ["./custom-reporter.js", { format: "detailed" }]
  ]
};