uilint-eslint 0.2.23 → 0.2.27

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
 import { Linter } from 'eslint';
-import { ESLintUtils } from '@typescript-eslint/utils';
+import { ESLintUtils, TSESTree } from '@typescript-eslint/utils';
 
 /**
  * Rule creation helper using @typescript-eslint/utils
@@ -70,6 +70,15 @@ interface RuleMeta {
      * - Configuration options explained
      */
     docs: string;
+    /**
+     * Internal utility dependencies that this rule requires.
+     * When the rule is copied to a target project, these utilities
+     * will be transformed to import from "uilint-eslint" instead
+     * of relative paths.
+     *
+     * Example: ["coverage-aggregator", "dependency-graph"]
+     */
+    internalDependencies?: string[];
 }
 /**
  * Helper to define rule metadata with type safety
@@ -236,6 +245,315 @@ declare function getRuleDocs(id: string): string | undefined;
  */
 declare function getAllRuleIds(): string[];
 
+/**
+ * File Categorizer
+ *
+ * Categorizes TypeScript/React files by their role in the codebase.
+ * Used for smart weighting in coverage aggregation.
+ *
+ * Categories:
+ * - core (1.0): hooks, components, services, stores - critical logic
+ * - utility (0.5): formatters, validators, helpers - supporting code
+ * - constant (0.25): config, constants, enums - static data
+ * - type (0): .d.ts files, type-only exports - no runtime impact
+ */
+type FileCategory = "core" | "utility" | "constant" | "type";
+interface FileCategoryResult {
+    category: FileCategory;
+    weight: number;
+    reason: string;
+}
+/**
+ * Categorize a TypeScript/React file by its role
+ */
+declare function categorizeFile(filePath: string, _projectRoot: string): FileCategoryResult;
+
+/**
+ * Coverage Aggregator
+ *
+ * Calculates weighted aggregate coverage for a component by tracing its
+ * dependencies and combining their coverage using smart weighting.
+ *
+ * Weighting strategy:
+ * - core (1.0): hooks, components, services - critical logic
+ * - utility (0.5): formatters, validators - supporting code
+ * - constant (0.25): config, constants - static data
+ * - type (0): .d.ts, type-only - no runtime impact
+ */
+
+/**
+ * Istanbul coverage JSON format (matching require-test-coverage.ts)
+ */
+interface IstanbulCoverage {
+    [filePath: string]: {
+        path: string;
+        statementMap: {
+            [key: string]: {
+                start: {
+                    line: number;
+                    column: number;
+                };
+                end: {
+                    line: number;
+                    column: number;
+                };
+            };
+        };
+        fnMap: {
+            [key: string]: {
+                name: string;
+                decl: {
+                    start: {
+                        line: number;
+                        column: number;
+                    };
+                    end: {
+                        line: number;
+                        column: number;
+                    };
+                };
+                loc: {
+                    start: {
+                        line: number;
+                        column: number;
+                    };
+                    end: {
+                        line: number;
+                        column: number;
+                    };
+                };
+            };
+        };
+        branchMap: {
+            [key: string]: {
+                loc: {
+                    start: {
+                        line: number;
+                        column: number;
+                    };
+                    end: {
+                        line: number;
+                        column: number;
+                    };
+                };
+                type: string;
+                locations: Array<{
+                    start: {
+                        line: number;
+                        column: number;
+                    };
+                    end: {
+                        line: number;
+                        column: number;
+                    };
+                }>;
+            };
+        };
+        s: {
+            [key: string]: number;
+        };
+        f: {
+            [key: string]: number;
+        };
+        b: {
+            [key: string]: number[];
+        };
+    };
+}
+/**
+ * Coverage information for a single file
+ */
+interface FileCoverageInfo {
+    filePath: string;
+    category: FileCategory;
+    weight: number;
+    statements: {
+        covered: number;
+        total: number;
+    };
+    percentage: number;
+}
+/**
+ * Aggregated coverage result for a component
+ */
+interface AggregatedCoverage {
+    /** The component file that was analyzed */
+    componentFile: string;
+    /** Coverage percentage for just the component file */
+    componentCoverage: number;
+    /** Weighted aggregate coverage across component + all dependencies */
+    aggregateCoverage: number;
+    /** Total number of files analyzed (component + dependencies) */
+    totalFiles: number;
+    /** Detailed coverage info for each file */
+    filesAnalyzed: FileCoverageInfo[];
+    /** Files with 0% coverage */
+    uncoveredFiles: string[];
+    /** The file with lowest coverage (excluding 0% files) */
+    lowestCoverageFile: {
+        path: string;
+        percentage: number;
+    } | null;
+}
+/**
+ * Calculate aggregate coverage for a component and its dependencies
+ *
+ * @param componentFile - Absolute path to the component file
+ * @param projectRoot - Project root directory
+ * @param coverageData - Istanbul coverage data
+ * @returns Aggregated coverage information
+ */
+declare function aggregateCoverage(componentFile: string, projectRoot: string, coverageData: IstanbulCoverage): AggregatedCoverage;
+
+/**
+ * Dependency Graph Builder
+ *
+ * Builds a dependency graph by tracing all imports from an entry file.
+ * Used for calculating aggregate test coverage across a component and its dependencies.
+ *
+ * Key behaviors:
+ * - Traces transitive dependencies (full depth)
+ * - Excludes node_modules (external packages)
+ * - Handles circular dependencies via visited set
+ * - Follows re-exports to actual source files
+ * - Caches results for performance
+ */
+interface DependencyGraph {
+    /** The entry file that was analyzed */
+    root: string;
+    /** All transitive dependencies (absolute paths, project files only) */
+    allDependencies: Set<string>;
+}
+/**
+ * Build a dependency graph starting from an entry file
+ *
+ * @param entryFile - Absolute path to the entry file
+ * @param projectRoot - Project root directory (used for determining project boundaries)
+ * @returns DependencyGraph with all transitive dependencies
+ */
+declare function buildDependencyGraph(entryFile: string, projectRoot: string): DependencyGraph;
+
+/**
+ * JSX Coverage Analyzer
+ *
+ * Analyzes JSX elements to determine test coverage for interactive elements
+ * like event handlers. Uses Istanbul coverage data to check if the code
+ * associated with JSX elements has been executed during tests.
+ *
+ * Phase 1: Core functions for statement-level coverage analysis
+ * Phase 2: Event handler extraction and analysis
+ * Phase 3: Conditional parent analysis + Component-level aggregation (partial TODO)
+ * Phase 4: Import dependency coverage + ESLint rule reporting (partial TODO)
+ */
+
+/**
+ * Istanbul coverage data for a single file
+ */
+type IstanbulFileCoverage = IstanbulCoverage[string];
+/**
+ * Source location with start and end positions
+ */
+interface SourceLocation {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * Coverage statistics for a code region
+ */
+interface CoverageStats {
+    /** Number of statements that were executed at least once */
+    covered: number;
+    /** Total number of statements in the region */
+    total: number;
+    /** Coverage percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Coverage result for a single JSX element
+ */
+interface JSXCoverageResult {
+    /** The data-loc attribute value for this element */
+    dataLoc: string;
+    /** Whether this element has any event handlers */
+    hasEventHandlers: boolean;
+    /** Names of event handlers found (e.g., ["onClick", "onSubmit"]) */
+    eventHandlerNames: string[];
+    /** Coverage statistics for statements within this element */
+    coverage: CoverageStats;
+    /** Whether the element is considered "covered" (percentage > 0) */
+    isCovered: boolean;
+}
+/**
+ * Creates a "file:line:column" format string for data-loc attribute
+ *
+ * @param filePath - Absolute or relative path to the file
+ * @param loc - Source location with start position
+ * @returns Formatted string like "src/Button.tsx:15:4"
+ */
+declare function buildDataLoc(filePath: string, loc: SourceLocation): string;
+/**
+ * Find statement IDs that overlap with the given source location
+ *
+ * A statement overlaps if its line range intersects with the location's
+ * line range. Column-level precision is not used for overlap detection.
+ *
+ * @param loc - The source location to check
+ * @param fileCoverage - Istanbul coverage data for the file
+ * @returns Set of statement IDs (keys from statementMap) that overlap
+ */
+declare function findStatementsInRange(loc: SourceLocation, fileCoverage: IstanbulFileCoverage): Set<string>;
+/**
+ * Calculate coverage statistics from a set of statement IDs
+ *
+ * @param statementIds - Set of statement IDs to check
+ * @param fileCoverage - Istanbul coverage data for the file
+ * @returns Coverage statistics with covered count, total, and percentage
+ */
+declare function calculateCoverageFromStatements(statementIds: Set<string>, fileCoverage: IstanbulFileCoverage): CoverageStats;
+/**
+ * Find coverage data for a file with path normalization
+ *
+ * Handles various path formats:
+ * - Absolute paths
+ * - Relative paths with or without leading slash
+ * - Paths that may differ in their base directory
+ *
+ * @param coverage - Full Istanbul coverage data
+ * @param filePath - The file path to find coverage for
+ * @returns File coverage data if found, undefined otherwise
+ */
+declare function findCoverageForFile(coverage: IstanbulCoverage, filePath: string): IstanbulFileCoverage | undefined;
+/**
+ * Check if a JSX attribute is an event handler (starts with "on" followed by uppercase)
+ *
+ * Event handlers follow the pattern: onClick, onSubmit, onChange, etc.
+ * This excludes spread attributes and non-event props like "only" or "once".
+ *
+ * @param attr - JSX attribute or spread attribute
+ * @returns true if the attribute is an event handler
+ */
+declare function isEventHandlerAttribute(attr: TSESTree.JSXAttribute | TSESTree.JSXSpreadAttribute): boolean;
+/**
+ * Analyze a JSX element for test coverage
+ *
+ * Main entry point that combines all the above functions to produce
+ * a complete coverage analysis for a single JSX element.
+ *
+ * @param jsxNode - The JSX element node from the AST
+ * @param filePath - Path to the file containing this element
+ * @param coverage - Istanbul coverage data
+ * @param ancestors - Optional ancestor nodes for resolving handler references
+ * @param projectRoot - Optional project root for resolving import paths
+ * @returns Coverage result for the JSX element
+ */
+declare function analyzeJSXElementCoverage(jsxNode: TSESTree.JSXElement, filePath: string, coverage: IstanbulCoverage, ancestors?: TSESTree.Node[], projectRoot?: string): JSXCoverageResult;
+
 /**
  * All available rules
  */
@@ -329,6 +647,36 @@ declare const rules: {
     }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "no-semantic-duplicates": _typescript_eslint_utils_ts_eslint.RuleModule<"semanticDuplicate" | "noIndex", [{
+        threshold?: number;
+        indexPath?: string;
+        minLines?: number;
+    }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    "require-test-coverage": _typescript_eslint_utils_ts_eslint.RuleModule<"noTestFile" | "noCoverage" | "belowThreshold" | "noCoverageData" | "belowAggregateThreshold" | "jsxBelowThreshold", [{
+        coveragePath?: string;
+        threshold?: number;
+        thresholdsByPattern?: Array<{
+            pattern: string;
+            threshold: number;
+        }>;
+        severity?: {
+            noTestFile?: "error" | "warn" | "off";
+            noCoverage?: "error" | "warn" | "off";
+            belowThreshold?: "error" | "warn" | "off";
+        };
+        testPatterns?: string[];
+        ignorePatterns?: string[];
+        mode?: "all" | "changed";
+        baseBranch?: string;
+        aggregateThreshold?: number;
+        aggregateSeverity?: "error" | "warn" | "off";
+        jsxThreshold?: number;
+        jsxSeverity?: "error" | "warn" | "off";
+    }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 /**
  * Plugin metadata
@@ -435,6 +783,36 @@ declare const plugin: {
         }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "no-semantic-duplicates": _typescript_eslint_utils_ts_eslint.RuleModule<"semanticDuplicate" | "noIndex", [{
+            threshold?: number;
+            indexPath?: string;
+            minLines?: number;
+        }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        "require-test-coverage": _typescript_eslint_utils_ts_eslint.RuleModule<"noTestFile" | "noCoverage" | "belowThreshold" | "noCoverageData" | "belowAggregateThreshold" | "jsxBelowThreshold", [{
+            coveragePath?: string;
+            threshold?: number;
+            thresholdsByPattern?: Array<{
+                pattern: string;
+                threshold: number;
+            }>;
+            severity?: {
+                noTestFile?: "error" | "warn" | "off";
+                noCoverage?: "error" | "warn" | "off";
+                belowThreshold?: "error" | "warn" | "off";
+            };
+            testPatterns?: string[];
+            ignorePatterns?: string[];
+            mode?: "all" | "changed";
+            baseBranch?: string;
+            aggregateThreshold?: number;
+            aggregateSeverity?: "error" | "warn" | "off";
+            jsxThreshold?: number;
+            jsxSeverity?: "error" | "warn" | "off";
+        }], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
 };
 /**
@@ -455,4 +833,4 @@ interface UILintESLint {
  */
 declare const uilintEslint: UILintESLint;
 
-export { type CacheEntry, type CacheStore, type CachedIssue, type LibraryName, type OptionFieldSchema, type RuleMeta, type RuleMeta as RuleMetadata, type RuleOptionSchema, type UILintESLint, clearCache$1 as clearCache, clearCacheEntry, clearCache as clearImportGraphCache, configs, createRule, uilintEslint as default, defineRuleMeta, findStyleguidePath, getAllRuleIds, getCacheEntry, getComponentLibrary, getRuleDocs, getRuleMetadata, getRulesByCategory, getStyleguide, hashContent, hashContentSync, loadCache, loadStyleguide, meta, plugin, ruleRegistry, rules, saveCache, setCacheEntry };
+export { type AggregatedCoverage, type CacheEntry, type CacheStore, type CachedIssue, type CoverageStats, type DependencyGraph, type FileCategory, type FileCategoryResult, type FileCoverageInfo, type IstanbulCoverage, type IstanbulFileCoverage, type JSXCoverageResult, type LibraryName, type OptionFieldSchema, type RuleMeta, type RuleMeta as RuleMetadata, type RuleOptionSchema, type SourceLocation, type UILintESLint, aggregateCoverage, analyzeJSXElementCoverage, buildDataLoc, buildDependencyGraph, calculateCoverageFromStatements, categorizeFile, clearCache$1 as clearCache, clearCacheEntry, clearCache as clearImportGraphCache, configs, createRule, uilintEslint as default, defineRuleMeta, findCoverageForFile, findStatementsInRange, findStyleguidePath, getAllRuleIds, getCacheEntry, getComponentLibrary, getRuleDocs, getRuleMetadata, getRulesByCategory, getStyleguide, hashContent, hashContentSync, isEventHandlerAttribute, loadCache, loadStyleguide, meta, plugin, ruleRegistry, rules, saveCache, setCacheEntry };