Issues and Filtering

/**
 * Represents a TypeScript issue/diagnostic
 */
interface Issue {
  /** Severity level of the issue */
  severity: IssueSeverity;
  
  /** TypeScript diagnostic code (e.g. "TS2304", "TS2322") */
  code: string;
  
  /** Human-readable issue message */
  message: string;
  
  /** File path where the issue occurred (optional for global issues) */
  file?: string;
  
  /** Location range within the file (optional) */
  location?: IssueLocation;
}

/**
 * Type guard to check if value is a valid Issue
 * @param value - Value to check
 * @returns True if value is an Issue
 */
function isIssue(value: unknown): value is Issue;

/**
 * Sort and deduplicate array of issues
 * @param issues - Array of issues to process
 * @returns Sorted and deduplicated issues
 */
function deduplicateAndSortIssues(issues: Issue[]): Issue[];

/**
 * Issue severity levels
 */
type IssueSeverity = 'error' | 'warning';

/**
 * Type guard for issue severity
 * @param value - Value to check
 * @returns True if value is a valid IssueSeverity
 */
function isIssueSeverity(value: unknown): value is IssueSeverity;

/**
 * Compare two issue severities for sorting
 * @param severityA - First severity
 * @param severityB - Second severity  
 * @returns Comparison result (-1, 0, 1)
 */
function compareIssueSeverities(severityA: IssueSeverity, severityB: IssueSeverity): number;

// Filter by severity
const errors = issues.filter(issue => issue.severity === 'error');
const warnings = issues.filter(issue => issue.severity === 'warning');

// Sort by severity (errors first)
const sorted = issues.sort((a, b) => compareIssueSeverities(a.severity, b.severity));

/**
 * Location range in source file
 */
interface IssueLocation {
  /** Start position of the issue */
  start: IssuePosition;
  
  /** End position of the issue */
  end: IssuePosition;
}

/**
 * Position within a source file
 */
interface IssuePosition {
  /** Line number (1-based) */
  line: number;
  
  /** Column number (0-based) */
  column: number;
}

/**
 * Compare two issue locations for sorting
 * @param locationA - First location
 * @param locationB - Second location
 * @returns Comparison result (-1, 0, 1)
 */
function compareIssueLocations(locationA?: IssueLocation, locationB?: IssueLocation): number;

/**
 * Format issue location as human-readable string
 * @param location - Location to format
 * @returns Formatted location string (e.g. "12:5")
 */
function formatIssueLocation(location: IssueLocation): string;

// Create issue with location
const issue: Issue = {
  severity: 'error',
  code: 'TS2304',
  message: "Cannot find name 'foo'",
  file: 'src/index.ts',
  location: {
    start: { line: 10, column: 5 },
    end: { line: 10, column: 8 }
  }
};

// Format location for display
const locationStr = formatIssueLocation(issue.location!); // "10:5"

/**
 * Issue filtering configuration
 */
interface IssueOptions {
  /** 
   * Issues to include (whitelist)
   * If specified, only matching issues are reported
   */
  include?: IssuePredicateOption;
  
  /**
   * Issues to exclude (blacklist)
   * Matching issues are filtered out from results
   */
  exclude?: IssuePredicateOption;
}

/**
 * Flexible predicate option for issue filtering
 */
type IssuePredicateOption = 
  | IssuePredicate 
  | IssueMatch 
  | (IssuePredicate | IssueMatch)[];

/**
 * Function-based issue predicate
 */
type IssuePredicate = (issue: Issue) => boolean;

/**
 * Object-based issue matching pattern
 * Partial match against Issue properties (severity, code, file)
 */
interface IssueMatch {
  /** Match by file path (glob pattern supported) */
  file?: string;
  
  /** Match by TypeScript diagnostic code */
  code?: string;
  
  /** Match by severity level */
  severity?: IssueSeverity;
}

// Exclude test files and specific error codes
new ForkTsCheckerWebpackPlugin({
  issue: {
    exclude: [
      { file: '**/*.test.ts' },
      { file: '**/*.spec.ts' },
      { code: ['TS2722', 'TS7006'] }, // Ignore specific TypeScript errors
      { message: /deprecated/i }       // Ignore deprecation warnings
    ]
  }
})

// Include only errors (exclude warnings)
new ForkTsCheckerWebpackPlugin({
  issue: {
    include: { severity: 'error' }
  }
})

// Complex filtering with functions
new ForkTsCheckerWebpackPlugin({
  issue: {
    exclude: [
      // Exclude vendor files
      { file: /node_modules/ },
      
      // Custom predicate function
      (issue: Issue) => {
        // Exclude issues in generated files
        return issue.file?.includes('.generated.') || false;
      }
    ]
  }
})

// File-specific filtering
new ForkTsCheckerWebpackPlugin({
  issue: {
    exclude: [
      { 
        file: 'src/legacy/**/*',
        severity: 'warning' // Only exclude warnings in legacy code
      },
      {
        file: '**/*.d.ts',
        code: 'TS2300' // Ignore specific issues in declaration files
      }
    ]
  }
})

// Only check specific packages in monorepo
new ForkTsCheckerWebpackPlugin({
  issue: {
    include: { file: 'packages/core/**/*' },
    exclude: [
      { file: '**/node_modules/**' },
      { file: '**/*.test.ts' }
    ]
  }
})

const issueConfig = process.env.NODE_ENV === 'development' 
  ? {
      // Relaxed filtering in development
      exclude: [
        { severity: 'warning' },
        { code: ['TS7006', 'TS7053'] } // Ignore implicit any warnings
      ]
    }
  : {
      // Strict filtering in production
      include: { severity: ['error', 'warning'] }
    };

new ForkTsCheckerWebpackPlugin({
  issue: issueConfig
})

// Gradually enable strict checking
new ForkTsCheckerWebpackPlugin({
  issue: {
    exclude: [
      // Temporarily exclude strict null checks in legacy files
      {
        file: 'src/legacy/**/*',
        code: ['TS2531', 'TS2532', 'TS2533']
      }
    ]
  }
})

/**
 * Compare two issues for sorting
 * Orders by: severity, file, location, code, message
 */
function compareIssues(issueA: Issue, issueB: Issue): number;

/**
 * Check if two issues are equal
 */
function equalsIssues(issueA: Issue, issueB: Issue): boolean;

/**
 * Create issue predicate from issue match pattern
 * @param context - Base context directory for file matching
 * @param match - Issue match pattern
 * @returns Predicate function for filtering issues
 */
function createIssuePredicateFromIssueMatch(context: string, match: IssueMatch): IssuePredicate;