Configuration Types

/**
 * Main user-facing configuration interface for CSpell
 * Extends all base settings with version tracking
 */
interface CSpellUserSettings extends CSpellSettings {}

/**
 * Core CSpell settings interface
 * Combines file settings with legacy support
 */
interface CSpellSettings extends FileSettings, LegacySettings {
  readonly version?: Version;
}

/**
 * User settings with comment support for configuration files
 */
interface CSpellUserSettingsWithComments extends CSpellUserSettings {
  // Allows any additional comment fields
  [key: string]: any;
}

/**
 * Settings for file-based configuration
 * Extends base settings with extensibility
 */
interface FileSettings extends BaseSetting, ExtendableSettings {}

/**
 * Core setting properties that control spell checking behavior
 */
interface BaseSetting {
  /** Enable/disable spell checking */
  enabled?: boolean;
  
  /** Words to include in spell checking */
  words?: string[];
  
  /** Words to ignore during spell checking */
  ignoreWords?: string[];
  
  /** Flag words as forbidden/incorrect */
  flagWords?: string[];
  
  /** Dictionary references to use */
  dictionaries?: DictionaryReference[];
  
  /** Dictionary definitions */
  dictionaryDefinitions?: DictionaryDefinition[];
  
  /** Language-specific settings */
  languageSettings?: LanguageSetting[];
  
  /** Local language/region identifier */
  language?: LocaleId;
  
  /** Locale identifier */
  local?: LocalId;
  
  /** File patterns to include */
  files?: Glob[];
  
  /** File patterns to ignore */
  ignorePaths?: Glob[];
  
  /** Patterns to ignore in content */
  ignoreRegExpList?: RegExpPatternList;
  
  /** Pattern definitions */
  patterns?: RegExpPatternDefinition[];
  
  /** Reporter configurations */
  reporters?: ReporterSettings[];
  
  /** Additional configuration options */
  [key: string]: any;
}

/**
 * Settings that support file-specific overrides
 */
interface ExtendableSettings {
  /** File-specific setting overrides */
  overrides?: OverrideSettings[];
}

/**
 * Override settings for specific file patterns
 */
interface OverrideSettings extends Settings, OverrideFilterFields {
  /** File patterns to apply overrides to */
  filename: Glob | Glob[];
}

/**
 * Fields used for filtering override applications
 */
interface OverrideFilterFields extends LanguageSettingFilterFields {
  /** File patterns to apply overrides to */
  filename?: Glob | Glob[];
}

/**
 * Language-specific configuration settings
 */
interface LanguageSetting extends BaseSetting, LanguageSettingFilterFields {}

/**
 * Fields for filtering when language settings apply
 */
interface LanguageSettingFilterFields extends LanguageSettingFilterFieldsPreferred {
  /** Language identifiers this setting applies to */
  languageId?: LanguageId | LanguageId[];
  
  /** Local/region identifiers */
  local?: LocaleId | LocaleId[];
  
  /** Locale identifiers */
  locale?: LocaleId | LocaleId[];
}

/**
 * Preferred language setting filter fields
 */
interface LanguageSettingFilterFieldsPreferred {
  /** Language identifiers this setting applies to */
  languageId?: LanguageId | LanguageId[];
  
  /** Locale identifiers */
  locale?: LocaleId | LocaleId[];
}

/**
 * Deprecated language setting filter fields (use LanguageSettingFilterFieldsPreferred)
 */
interface LanguageSettingFilterFieldsDeprecated {
  /** @deprecated Use locale instead */
  local?: LocaleId | LocaleId[];
}

/**
 * Advanced CSpell settings with experimental features
 */
interface AdvancedCSpellSettings extends CSpellSettings, ExperimentalFileSettings {}

/**
 * Advanced settings with source tracking metadata
 */
interface AdvancedCSpellSettingsWithSourceTrace extends AdvancedCSpellSettings {
  readonly source?: Source;
}

/**
 * Experimental file-based settings
 */
interface ExperimentalFileSettings extends FileSettings, ExperimentalBaseSettings {}

/**
 * Experimental base configuration options
 */
interface ExperimentalBaseSettings {
  /** Experimental feature configurations */
  experimental?: Record<string, any>;
  
  /** Advanced caching options */
  cache?: CacheSettings;
  
  /** Plugin configurations */
  plugins?: Plugin[];
}

/**
 * Cache configuration settings
 */
interface CacheSettings {
  /** Cache strategy to use */
  strategy?: CacheStrategy;
  
  /** Cache format */
  cacheFormat?: CacheFormat;
  
  /** Cache location */
  cacheLocation?: string;
  
  /** Use cache */
  useCache?: boolean;
}

/**
 * Available cache strategies
 */
type CacheStrategy = "metadata" | "content";

/**
 * Available cache formats  
 */
type CacheFormat = "json" | "legacy";

/**
 * Command-line specific configuration options
 */
interface CommandLineSettings {
  /** Configuration file paths */
  config?: string[];
  
  /** Root directory for relative paths */
  root?: string;
  
  /** Show progress information */
  progress?: boolean;
  
  /** Verbose output */
  verbose?: boolean;
  
  /** Debug output */  
  debug?: boolean;
  
  /** Quiet mode */
  quiet?: boolean;
  
  /** Exit with error code on issues */
  exitCode?: boolean;
  
  /** Show summary */
  summary?: boolean;
  
  /** Additional CLI-specific options */
  [key: string]: any;
}

/**
 * Workspace trust and security settings
 */
interface WorkspaceTrustSettings {
  /** Trust level for the workspace */
  trustLevel?: TrustLevel;
  
  /** Trusted workspace patterns */
  trustedWorkspaces?: string[];
  
  /** Allow untrusted files */
  allowUntrustedFiles?: boolean;
}

/**
 * Available trust levels
 */
type TrustLevel = "none" | "low" | "medium" | "high" | "trusted";

/**
 * Settings with source tracking for debugging configuration
 */
interface CSpellSettingsWithSourceTrace extends CSpellSettings {
  readonly source?: Source;
}

/**
 * Base interface for configuration source tracking
 */
interface Source {
  /** Name of the configuration source */
  name: string;
  
  /** Source location or identifier */
  filename?: string;
}

/**
 * File-based configuration source
 */
interface FileSource extends Source {
  /** File path of the configuration */
  filename: string;
}

/**
 * Merged configuration source tracking
 */
interface MergeSource extends Source {
  /** Sources that were merged */
  sources: Source[];
}

/**
 * In-memory configuration source
 */
interface InMemorySource extends Source {
  /** Source content */
  content?: any;
}

/**
 * Import file reference for configuration includes
 */
interface ImportFileRef {
  /** Import filename or pattern */
  filename: string;
  
  /** Error if import failed */
  error?: Error;
}

/** Configuration version identifier */
type Version = VersionLatest | VersionLegacy;

/** Latest configuration version */
type VersionLatest = "0.2";

/** Legacy configuration version */
type VersionLegacy = "0.1";

/** Language identifier (single or multiple) */
type LanguageId = LanguageIdSingle | LanguageIdMultiple;

/** Single language identifier */
type LanguageIdSingle = string;

/** Multiple language identifiers */
type LanguageIdMultiple = LanguageIdSingle[];

/** Multiple language identifiers with negation support */
type LanguageIdMultipleNeg = (LanguageIdSingle | `!${LanguageIdSingle}`)[];

/** Locale identifier */
type LocaleId = string;

/** Local identifier (deprecated, use LocaleId) */
type LocalId = LocaleId;

/** File glob pattern (simple string or detailed definition) */
type Glob = SimpleGlob | GlobDef;

/** Simple glob pattern string */
type SimpleGlob = string;

/** Detailed glob definition with root */
interface GlobDef {
  /** Glob pattern */
  glob: string;
  
  /** Root directory for pattern matching */
  root?: string;
}

/** File system path */
type FsPath = string;

/** File system path that can be resolved */
type FSPathResolvable = FsPath;