driftdetect-detectors 0.1.0

package/dist/base/regex-detector.d.ts

@@ -0,0 +1,421 @@
+/**
+ * Regex Detector - Regex-based detection base class
+ *
+ * Provides pattern matching helpers and utilities for regex-based pattern detection.
+ * Extends BaseDetector with specialized methods for matching patterns in source code.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: ast, regex, semantic, structural, and custom
+ */
+import type { Location } from 'driftdetect-core';
+import { BaseDetector } from './base-detector.js';
+/**
+ * Result of a regex match with position information
+ */
+export interface RegexMatch {
+    /** The full matched text */
+    match: string;
+    /** Index of the match in the source string */
+    index: number;
+    /** Named capture groups (if any) */
+    groups: Record<string, string>;
+    /** Numbered capture groups (index 0 is full match) */
+    captures: string[];
+}
+/**
+ * Result of a regex match with line information
+ */
+export interface LineMatch {
+    /** The full matched text */
+    match: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** End line number (1-indexed) */
+    endLine: number;
+    /** End column number (1-indexed) */
+    endColumn: number;
+    /** Index of the match in the source string */
+    index: number;
+    /** Named capture groups (if any) */
+    groups: Record<string, string>;
+    /** Numbered capture groups (index 0 is full match) */
+    captures: string[];
+    /** The full line(s) containing the match */
+    lineContent: string;
+}
+/**
+ * Result of extracting named capture groups
+ */
+export interface CaptureResult {
+    /** The full matched text */
+    match: string;
+    /** Named capture groups */
+    groups: Record<string, string>;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+}
+/**
+ * Location of a pattern match in source code
+ */
+export interface PatternLocation {
+    /** File path (relative to project root) */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** End line number (1-indexed) */
+    endLine: number;
+    /** End column number (1-indexed) */
+    endColumn: number;
+    /** The matched text */
+    matchedText: string;
+    /** Named capture groups (if any) */
+    groups: Record<string, string>;
+}
+/**
+ * Options for regex matching operations
+ */
+export interface RegexMatchOptions {
+    /** Whether to match case-insensitively */
+    caseInsensitive?: boolean;
+    /** Whether to match across multiple lines */
+    multiline?: boolean;
+    /** Whether to use dotAll mode (. matches newlines) */
+    dotAll?: boolean;
+    /** Maximum number of matches to return (undefined = all) */
+    maxMatches?: number;
+}
+/**
+ * Abstract base class for regex-based detectors
+ *
+ * Provides pattern matching helpers and utilities for detection
+ * that operates on source code using regular expressions.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: regex
+ *
+ * @example
+ * ```typescript
+ * class TodoCommentDetector extends RegexDetector {
+ *   readonly id = 'documentation/todo-patterns';
+ *   readonly category = 'documentation';
+ *   readonly subcategory = 'comments';
+ *   readonly name = 'TODO Comment Detector';
+ *   readonly description = 'Detects TODO/FIXME comment patterns';
+ *   readonly supportedLanguages = ['typescript', 'javascript'];
+ *
+ *   async detect(context: DetectionContext): Promise<DetectionResult> {
+ *     const todoPattern = /\/\/\s*(TODO|FIXME):\s*(.+)/gi;
+ *     const matches = this.matchLines(context.content, todoPattern);
+ *     // Analyze TODO patterns...
+ *   }
+ *
+ *   generateQuickFix(violation: Violation): QuickFix | null {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class RegexDetector extends BaseDetector {
+    /**
+     * Detection method is always 'regex' for regex-based detectors
+     *
+     * @requirements 6.4 - Detector declares detection method as 'regex'
+     */
+    readonly detectionMethod: "regex";
+    /**
+     * Find all matches of a regex pattern in content
+     *
+     * Returns all matches with their positions and capture groups.
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match (will be made global if not already)
+     * @param options - Optional matching options
+     * @returns Array of match results
+     *
+     * @example
+     * ```typescript
+     * const matches = this.matchAll(content, /function\s+(\w+)/g);
+     * for (const match of matches) {
+     *   console.log(`Found function: ${match.captures[1]}`);
+     * }
+     * ```
+     */
+    protected matchAll(content: string, pattern: RegExp, options?: RegexMatchOptions): RegexMatch[];
+    /**
+     * Find all matches with line and column information
+     *
+     * Returns matches with their line numbers, columns, and the full line content.
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @param options - Optional matching options
+     * @returns Array of line match results
+     *
+     * @example
+     * ```typescript
+     * const matches = this.matchLines(content, /console\.log\(/g);
+     * for (const match of matches) {
+     *   console.log(`Found console.log at line ${match.line}, column ${match.column}`);
+     * }
+     * ```
+     */
+    protected matchLines(content: string, pattern: RegExp, options?: RegexMatchOptions): LineMatch[];
+    /**
+     * Extract named capture groups from all matches
+     *
+     * Useful for patterns with named groups like /(?<name>\w+)/
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern with named capture groups
+     * @param options - Optional matching options
+     * @returns Array of capture results with groups
+     *
+     * @example
+     * ```typescript
+     * const captures = this.extractCaptures(
+     *   content,
+     *   /function\s+(?<name>\w+)\s*\((?<params>[^)]*)\)/g
+     * );
+     * for (const capture of captures) {
+     *   console.log(`Function ${capture.groups.name} with params: ${capture.groups.params}`);
+     * }
+     * ```
+     */
+    protected extractCaptures(content: string, pattern: RegExp, options?: RegexMatchOptions): CaptureResult[];
+    /**
+     * Find locations of all pattern matches
+     *
+     * Returns Location objects compatible with the drift core types.
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @param file - The file path for the locations
+     * @param options - Optional matching options
+     * @returns Array of pattern locations
+     *
+     * @example
+     * ```typescript
+     * const locations = this.findPatternLocations(
+     *   context.content,
+     *   /import\s+.*\s+from\s+['"]([^'"]+)['"]/g,
+     *   context.file
+     * );
+     * ```
+     */
+    protected findPatternLocations(content: string, pattern: RegExp, file: string, options?: RegexMatchOptions): PatternLocation[];
+    /**
+     * Test if a pattern matches anywhere in the content
+     *
+     * @param content - The source content to test
+     * @param pattern - The regex pattern to test
+     * @returns true if the pattern matches
+     *
+     * @example
+     * ```typescript
+     * if (this.hasMatch(content, /export\s+default/)) {
+     *   // File has a default export
+     * }
+     * ```
+     */
+    protected hasMatch(content: string, pattern: RegExp): boolean;
+    /**
+     * Count the number of matches in content
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to count
+     * @returns Number of matches found
+     *
+     * @example
+     * ```typescript
+     * const importCount = this.countMatches(content, /^import\s+/gm);
+     * ```
+     */
+    protected countMatches(content: string, pattern: RegExp): number;
+    /**
+     * Find the first match of a pattern
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @returns The first match, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const firstFunction = this.findFirst(content, /function\s+(\w+)/);
+     * if (firstFunction) {
+     *   console.log(`First function: ${firstFunction.captures[1]}`);
+     * }
+     * ```
+     */
+    protected findFirst(content: string, pattern: RegExp): LineMatch | null;
+    /**
+     * Find the last match of a pattern
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @returns The last match, or null if not found
+     */
+    protected findLast(content: string, pattern: RegExp): LineMatch | null;
+    /**
+     * Find matches within a specific line range
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @param startLine - Start line (1-indexed, inclusive)
+     * @param endLine - End line (1-indexed, inclusive)
+     * @returns Array of matches within the line range
+     */
+    protected matchInRange(content: string, pattern: RegExp, startLine: number, endLine: number): LineMatch[];
+    /**
+     * Replace all matches of a pattern
+     *
+     * @param content - The source content
+     * @param pattern - The regex pattern to replace
+     * @param replacement - The replacement string or function
+     * @returns The content with replacements applied
+     *
+     * @example
+     * ```typescript
+     * const fixed = this.replaceAll(content, /var\s+/g, 'const ');
+     * ```
+     */
+    protected replaceAll(content: string, pattern: RegExp, replacement: string | ((match: string, ...args: unknown[]) => string)): string;
+    /**
+     * Split content by a pattern
+     *
+     * @param content - The source content to split
+     * @param pattern - The regex pattern to split by
+     * @param limit - Maximum number of splits
+     * @returns Array of split parts
+     */
+    protected splitByPattern(content: string, pattern: RegExp, limit?: number): string[];
+    /**
+     * Get all lines matching a pattern
+     *
+     * Returns complete lines that contain a match.
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to match
+     * @returns Array of objects with line number and content
+     *
+     * @example
+     * ```typescript
+     * const importLines = this.getMatchingLines(content, /^import\s+/);
+     * ```
+     */
+    protected getMatchingLines(content: string, pattern: RegExp): Array<{
+        line: number;
+        content: string;
+    }>;
+    /**
+     * Get lines NOT matching a pattern
+     *
+     * @param content - The source content to search
+     * @param pattern - The regex pattern to exclude
+     * @returns Array of objects with line number and content
+     */
+    protected getNonMatchingLines(content: string, pattern: RegExp): Array<{
+        line: number;
+        content: string;
+    }>;
+    /**
+     * Create a pattern that matches any of the given strings
+     *
+     * @param strings - Strings to match (will be escaped)
+     * @param flags - Optional regex flags
+     * @returns A regex that matches any of the strings
+     *
+     * @example
+     * ```typescript
+     * const keywords = this.createAlternationPattern(['var', 'let', 'const'], 'g');
+     * // Creates: /var|let|const/g
+     * ```
+     */
+    protected createAlternationPattern(strings: string[], flags?: string): RegExp;
+    /**
+     * Create a pattern that matches a word boundary version of strings
+     *
+     * @param strings - Strings to match as whole words
+     * @param flags - Optional regex flags
+     * @returns A regex that matches whole words only
+     *
+     * @example
+     * ```typescript
+     * const keywords = this.createWordBoundaryPattern(['var', 'let', 'const'], 'g');
+     * // Creates: /\b(?:var|let|const)\b/g
+     * ```
+     */
+    protected createWordBoundaryPattern(strings: string[], flags?: string): RegExp;
+    /**
+     * Escape special regex characters in a string
+     *
+     * @param str - String to escape
+     * @returns Escaped string safe for use in regex
+     *
+     * @example
+     * ```typescript
+     * const escaped = this.escapeRegex('file.ts'); // 'file\\.ts'
+     * ```
+     */
+    protected escapeRegex(str: string): string;
+    /**
+     * Create a pattern from a template with placeholders
+     *
+     * @param template - Template string with {name} placeholders
+     * @param values - Values to substitute for placeholders
+     * @param flags - Optional regex flags
+     * @returns A regex with placeholders replaced
+     *
+     * @example
+     * ```typescript
+     * const pattern = this.createPatternFromTemplate(
+     *   'import\\s+{name}\\s+from\\s+[\'\"]{module}[\'\"]',
+     *   { name: '\\w+', module: '[^\'\"]+' },
+     *   'g'
+     * );
+     * ```
+     */
+    protected createPatternFromTemplate(template: string, values: Record<string, string>, flags?: string): RegExp;
+    /**
+     * Convert a LineMatch to a Location object
+     *
+     * @param match - The line match to convert
+     * @param file - The file path
+     * @returns A Location object
+     */
+    protected lineMatchToLocation(match: LineMatch, file: string): Location;
+    /**
+     * Convert a PatternLocation to a Location object
+     *
+     * @param patternLocation - The pattern location to convert
+     * @returns A Location object
+     */
+    protected patternLocationToLocation(patternLocation: PatternLocation): Location;
+    /**
+     * Line index information for position calculations
+     */
+    private buildLineIndex;
+    /**
+     * Convert a string index to line/column position
+     */
+    private indexToPosition;
+    /**
+     * Get the content of one or more lines
+     */
+    private getLineContent;
+    /**
+     * Normalize a regex pattern with options
+     */
+    private normalizePattern;
+}
+/**
+ * Type guard to check if a detector is a regex detector
+ *
+ * @param detector - The detector to check
+ * @returns true if the detector is a RegexDetector
+ */
+export declare function isRegexDetector(detector: BaseDetector): detector is RegexDetector;
+//# sourceMappingURL=regex-detector.d.ts.map

package/dist/base/regex-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-detector.d.ts","sourceRoot":"","sources":["../../src/base/regex-detector.ts"],"names":[],"mappings":"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"}