driftdetect-detectors 0.1.0

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

@@ -0,0 +1,424 @@
+/**
+* Structural Detector - File/directory structure detection base class
+*
+* Provides path pattern matching helpers and utilities for structural pattern detection.
+* Extends BaseDetector with specialized methods for analyzing file and directory structures.
+*
+* @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';
+/**
+ * Supported naming conventions for file and identifier names
+ */
+export type NamingConvention = 'PascalCase' | 'camelCase' | 'kebab-case' | 'snake_case' | 'SCREAMING_SNAKE_CASE' | 'flatcase';
+/**
+ * Result of a naming convention check
+ */
+export interface NamingConventionResult {
+    /** Whether the name matches the convention */
+    matches: boolean;
+    /** The detected convention (if any) */
+    detectedConvention: NamingConvention | null;
+    /** Suggested name in the expected convention */
+    suggestedName?: string;
+}
+/**
+ * Result of a path pattern match
+ */
+export interface PathMatchResult {
+    /** Whether the path matches the pattern */
+    matches: boolean;
+    /** Captured groups from the pattern (if any) */
+    captures: Record<string, string>;
+    /** The matched portion of the path */
+    matchedPortion?: string;
+}
+/**
+ * Information about a file path
+ */
+export interface PathInfo {
+    /** Full file path */
+    fullPath: string;
+    /** Directory path (without file name) */
+    directory: string;
+    /** File name with extension */
+    fileName: string;
+    /** File name without extension */
+    baseName: string;
+    /** File extension (including the dot) */
+    extension: string;
+    /** Path segments (directories and file) */
+    segments: string[];
+    /** Depth of the path (number of directory levels) */
+    depth: number;
+}
+/**
+ * Options for path matching operations
+ */
+export interface PathMatchOptions {
+    /** Whether to match case-insensitively */
+    caseInsensitive?: boolean;
+    /** Whether to use extended glob patterns */
+    extendedGlob?: boolean;
+    /** Base path for relative matching */
+    basePath?: string;
+}
+/**
+ * Abstract base class for structural detectors
+ *
+ * Provides path pattern matching helpers and utilities for detection
+ * that operates on file and directory structures.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: structural
+ *
+ * @example
+ * ```typescript
+ * class FileNamingDetector extends StructuralDetector {
+ *   readonly id = 'structural/file-naming';
+ *   readonly category = 'structural';
+ *   readonly subcategory = 'naming-conventions';
+ *   readonly name = 'File Naming Detector';
+ *   readonly description = 'Detects file naming patterns';
+ *   readonly supportedLanguages = ['typescript', 'javascript'];
+ *
+ *   async detect(context: DetectionContext): Promise<DetectionResult> {
+ *     const fileName = this.getFileName(context.file);
+ *     const convention = this.matchNamingConvention(fileName, 'PascalCase');
+ *     // Analyze file naming patterns...
+ *   }
+ *
+ *   generateQuickFix(violation: Violation): QuickFix | null {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StructuralDetector extends BaseDetector {
+    /**
+     * Detection method is always 'structural' for structural detectors
+     *
+     * @requirements 6.4 - Detector declares detection method as 'structural'
+     */
+    readonly detectionMethod: "structural";
+    /**
+     * Match a file path against a glob pattern
+     *
+     * Supports common glob patterns:
+     * - `*` matches any characters except path separators
+     * - `**` matches any characters including path separators
+     * - `?` matches a single character
+     * - `[abc]` matches any character in the brackets
+     * - `[!abc]` matches any character not in the brackets
+     * - `{a,b,c}` matches any of the alternatives
+     *
+     * @param path - The file path to match
+     * @param pattern - The glob pattern to match against
+     * @param options - Optional matching options
+     * @returns PathMatchResult with match status and captures
+     *
+     * @example
+     * ```typescript
+     * const result = this.matchPath('src/components/Button.tsx', 'src/components/*.tsx');
+     * // result.matches === true
+     *
+     * const result2 = this.matchPath('src/utils/helpers.ts', '**\/*.test.ts');
+     * // result2.matches === false
+     * ```
+     */
+    protected matchPath(path: string, pattern: string, options?: PathMatchOptions): PathMatchResult;
+    /**
+     * Match a file name against a pattern
+     *
+     * Matches only the file name portion (not the directory path).
+     *
+     * @param fileName - The file name to match (with or without extension)
+     * @param pattern - The pattern to match against (glob or regex string)
+     * @param options - Optional matching options
+     * @returns PathMatchResult with match status
+     *
+     * @example
+     * ```typescript
+     * const result = this.matchFileName('Button.tsx', '*.tsx');
+     * // result.matches === true
+     *
+     * const result2 = this.matchFileName('useAuth.ts', 'use*.ts');
+     * // result2.matches === true
+     * ```
+     */
+    protected matchFileName(fileName: string, pattern: string, options?: PathMatchOptions): PathMatchResult;
+    /**
+     * Get the file extension from a path
+     *
+     * Returns the extension including the leading dot.
+     * For files with multiple extensions (e.g., .test.ts), returns only the last extension.
+     *
+     * @param path - The file path
+     * @returns The file extension (e.g., '.ts', '.tsx') or empty string if none
+     *
+     * @example
+     * ```typescript
+     * this.getFileExtension('src/Button.tsx'); // '.tsx'
+     * this.getFileExtension('README'); // ''
+     * this.getFileExtension('file.test.ts'); // '.ts'
+     * ```
+     */
+    protected getFileExtension(path: string): string;
+    /**
+     * Get the file name without extension from a path
+     *
+     * @param path - The file path
+     * @returns The file name without extension
+     *
+     * @example
+     * ```typescript
+     * this.getFileName('src/components/Button.tsx'); // 'Button'
+     * this.getFileName('README.md'); // 'README'
+     * this.getFileName('file.test.ts'); // 'file.test'
+     * ```
+     */
+    protected getFileName(path: string): string;
+    /**
+     * Get the directory path from a file path
+     *
+     * Returns the path without the file name.
+     *
+     * @param path - The file path
+     * @returns The directory path (empty string if file is in root)
+     *
+     * @example
+     * ```typescript
+     * this.getDirectoryPath('src/components/Button.tsx'); // 'src/components'
+     * this.getDirectoryPath('index.ts'); // ''
+     * this.getDirectoryPath('src/utils/'); // 'src/utils'
+     * ```
+     */
+    protected getDirectoryPath(path: string): string;
+    /**
+     * Get detailed information about a file path
+     *
+     * @param path - The file path to analyze
+     * @returns PathInfo object with all path components
+     *
+     * @example
+     * ```typescript
+     * const info = this.getPathInfo('src/components/Button.tsx');
+     * // info.directory === 'src/components'
+     * // info.fileName === 'Button.tsx'
+     * // info.baseName === 'Button'
+     * // info.extension === '.tsx'
+     * // info.segments === ['src', 'components', 'Button.tsx']
+     * // info.depth === 2
+     * ```
+     */
+    protected getPathInfo(path: string): PathInfo;
+    /**
+     * Check if a file is in a specific directory (or its subdirectories)
+     *
+     * @param path - The file path to check
+     * @param directory - The directory to check against
+     * @param recursive - Whether to check subdirectories (default: true)
+     * @returns true if the file is in the directory
+     *
+     * @example
+     * ```typescript
+     * this.isInDirectory('src/components/Button.tsx', 'src/components'); // true
+     * this.isInDirectory('src/components/ui/Button.tsx', 'src/components'); // true (recursive)
+     * this.isInDirectory('src/components/ui/Button.tsx', 'src/components', false); // false
+     * this.isInDirectory('src/utils/helpers.ts', 'src/components'); // false
+     * ```
+     */
+    protected isInDirectory(path: string, directory: string, recursive?: boolean): boolean;
+    /**
+     * Get the relative path from a base path
+     *
+     * @param path - The full file path
+     * @param basePath - The base path to make relative to
+     * @returns The relative path, or the original path if not under basePath
+     *
+     * @example
+     * ```typescript
+     * this.getRelativePath('src/components/Button.tsx', 'src'); // 'components/Button.tsx'
+     * this.getRelativePath('src/components/Button.tsx', 'src/components'); // 'Button.tsx'
+     * this.getRelativePath('other/file.ts', 'src'); // 'other/file.ts' (not under base)
+     * ```
+     */
+    protected getRelativePath(path: string, basePath: string): string;
+    /**
+     * Get the common base path of multiple paths
+     *
+     * @param paths - Array of file paths
+     * @returns The common base path, or empty string if none
+     *
+     * @example
+     * ```typescript
+     * this.getCommonBasePath(['src/a/file.ts', 'src/b/file.ts']); // 'src'
+     * this.getCommonBasePath(['src/components/Button.tsx', 'src/components/Input.tsx']); // 'src/components'
+     * this.getCommonBasePath(['a/file.ts', 'b/file.ts']); // ''
+     * ```
+     */
+    protected getCommonBasePath(paths: string[]): string;
+    /**
+     * Get sibling files (files in the same directory)
+     *
+     * @param path - The file path
+     * @param allFiles - Array of all file paths in the project
+     * @returns Array of sibling file paths (excluding the input file)
+     *
+     * @example
+     * ```typescript
+     * const siblings = this.getSiblingFiles('src/Button.tsx', projectFiles);
+     * // Returns other files in 'src/' directory
+     * ```
+     */
+    protected getSiblingFiles(path: string, allFiles: string[]): string[];
+    /**
+     * Check if a name matches a specific naming convention
+     *
+     * @param name - The name to check (file name, identifier, etc.)
+     * @param convention - The naming convention to check against
+     * @returns NamingConventionResult with match status and suggestions
+     *
+     * @example
+     * ```typescript
+     * this.matchNamingConvention('MyComponent', 'PascalCase'); // { matches: true, ... }
+     * this.matchNamingConvention('myFunction', 'camelCase'); // { matches: true, ... }
+     * this.matchNamingConvention('my-component', 'kebab-case'); // { matches: true, ... }
+     * this.matchNamingConvention('my_variable', 'snake_case'); // { matches: true, ... }
+     * this.matchNamingConvention('MAX_VALUE', 'SCREAMING_SNAKE_CASE'); // { matches: true, ... }
+     * ```
+     */
+    protected matchNamingConvention(name: string, convention: NamingConvention): NamingConventionResult;
+    /**
+     * Detect the naming convention of a name
+     *
+     * @param name - The name to analyze
+     * @returns The detected naming convention, or null if unknown
+     *
+     * @example
+     * ```typescript
+     * this.detectNamingConvention('MyComponent'); // 'PascalCase'
+     * this.detectNamingConvention('myFunction'); // 'camelCase'
+     * this.detectNamingConvention('my-component'); // 'kebab-case'
+     * this.detectNamingConvention('my_variable'); // 'snake_case'
+     * this.detectNamingConvention('MAX_VALUE'); // 'SCREAMING_SNAKE_CASE'
+     * this.detectNamingConvention('mycomponent'); // 'flatcase'
+     * ```
+     */
+    protected detectNamingConvention(name: string): NamingConvention | null;
+    /**
+     * Convert a name to a specific naming convention
+     *
+     * @param name - The name to convert
+     * @param convention - The target naming convention
+     * @returns The converted name
+     *
+     * @example
+     * ```typescript
+     * this.convertToConvention('myComponent', 'PascalCase'); // 'MyComponent'
+     * this.convertToConvention('MyComponent', 'camelCase'); // 'myComponent'
+     * this.convertToConvention('MyComponent', 'kebab-case'); // 'my-component'
+     * this.convertToConvention('myComponent', 'snake_case'); // 'my_component'
+     * this.convertToConvention('myComponent', 'SCREAMING_SNAKE_CASE'); // 'MY_COMPONENT'
+     * ```
+     */
+    protected convertToConvention(name: string, convention: NamingConvention): string;
+    /**
+     * Split a name into words based on common conventions
+     *
+     * @param name - The name to split
+     * @returns Array of words
+     */
+    private splitIntoWords;
+    /**
+     * Capitalize the first letter of a word
+     */
+    private capitalize;
+    /**
+     * Check if a file is a test file based on common patterns
+     *
+     * @param path - The file path to check
+     * @returns true if the file appears to be a test file
+     *
+     * @example
+     * ```typescript
+     * this.isTestFile('Button.test.ts'); // true
+     * this.isTestFile('Button.spec.tsx'); // true
+     * this.isTestFile('__tests__/Button.ts'); // true
+     * this.isTestFile('Button.tsx'); // false
+     * ```
+     */
+    protected isTestFile(path: string): boolean;
+    /**
+     * Check if a file is a type definition file
+     *
+     * @param path - The file path to check
+     * @returns true if the file is a type definition
+     *
+     * @example
+     * ```typescript
+     * this.isTypeDefinitionFile('types.d.ts'); // true
+     * this.isTypeDefinitionFile('index.d.ts'); // true
+     * this.isTypeDefinitionFile('Button.tsx'); // false
+     * ```
+     */
+    protected isTypeDefinitionFile(path: string): boolean;
+    /**
+     * Check if a file is an index/barrel file
+     *
+     * @param path - The file path to check
+     * @returns true if the file is an index file
+     *
+     * @example
+     * ```typescript
+     * this.isIndexFile('index.ts'); // true
+     * this.isIndexFile('src/index.tsx'); // true
+     * this.isIndexFile('Button.tsx'); // false
+     * ```
+     */
+    protected isIndexFile(path: string): boolean;
+    /**
+     * Check if a file is a configuration file
+     *
+     * @param path - The file path to check
+     * @returns true if the file appears to be a config file
+     *
+     * @example
+     * ```typescript
+     * this.isConfigFile('tsconfig.json'); // true
+     * this.isConfigFile('.eslintrc.js'); // true
+     * this.isConfigFile('vite.config.ts'); // true
+     * this.isConfigFile('Button.tsx'); // false
+     * ```
+     */
+    protected isConfigFile(path: string): boolean;
+    /**
+     * Create a Location object for a file
+     *
+     * @param file - The file path
+     * @param line - Line number (1-indexed, default: 1)
+     * @param column - Column number (1-indexed, default: 1)
+     * @returns A Location object
+     */
+    protected createFileLocation(file: string, line?: number, column?: number): Location;
+    /**
+     * Normalize a file path to use forward slashes
+     */
+    private normalizePath;
+    /**
+     * Convert a glob pattern to a regular expression
+     */
+    private globToRegex;
+    /**
+     * Escape special regex characters in a string
+     */
+    private escapeRegex;
+}
+/**
+ * Type guard to check if a detector is a structural detector
+ *
+ * @param detector - The detector to check
+ * @returns true if the detector is a StructuralDetector
+ */
+export declare function isStructuralDetector(detector: BaseDetector): detector is StructuralDetector;
+//# sourceMappingURL=structural-detector.d.ts.map

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

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