driftdetect-detectors 0.1.0

package/dist/base/ast-detector.js

@@ -0,0 +1,699 @@
+/**
+ * AST Detector - AST-based detection base class
+ *
+ * Provides Tree-sitter query helpers and utilities for AST-based pattern detection.
+ * Extends BaseDetector with specialized methods for traversing and querying ASTs.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: ast, regex, semantic, structural, and custom
+ */
+import { BaseDetector } from './base-detector.js';
+// ============================================================================
+// AST Detector Abstract Class
+// ============================================================================
+/**
+ * Abstract base class for AST-based detectors
+ *
+ * Provides Tree-sitter query helpers and utilities for pattern detection
+ * that operates on parsed AST structures.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: ast
+ *
+ * @example
+ * ```typescript
+ * class FunctionNamingDetector extends ASTDetector {
+ *   readonly id = 'structural/function-naming';
+ *   readonly category = 'structural';
+ *   readonly subcategory = 'naming-conventions';
+ *   readonly name = 'Function Naming Detector';
+ *   readonly description = 'Detects function naming patterns';
+ *   readonly supportedLanguages = ['typescript', 'javascript'];
+ *
+ *   async detect(context: DetectionContext): Promise<DetectionResult> {
+ *     if (!context.ast) {
+ *       return this.createEmptyResult();
+ *     }
+ *
+ *     const functions = this.findNodes(context.ast, 'function_declaration');
+ *     // Analyze function naming patterns...
+ *   }
+ *
+ *   generateQuickFix(violation: Violation): QuickFix | null {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
+export class ASTDetector extends BaseDetector {
+    /**
+     * Detection method is always 'ast' for AST-based detectors
+     *
+     * @requirements 6.4 - Detector declares detection method as 'ast'
+     */
+    detectionMethod = 'ast';
+    // ============================================================================
+    // Node Finding Methods
+    // ============================================================================
+    /**
+     * Find all nodes of a specific type in the AST
+     *
+     * Traverses the entire AST and returns all nodes matching the specified type.
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of node to find (e.g., 'function_declaration', 'class_declaration')
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const functions = this.findNodes(ast, 'function_declaration');
+     * const classes = this.findNodes(ast, 'class_declaration');
+     * ```
+     */
+    findNodes(ast, nodeType) {
+        const results = [];
+        this.traverse(ast, (node) => {
+            if (node.type === nodeType) {
+                results.push(node);
+            }
+        });
+        return results;
+    }
+    /**
+     * Find all nodes matching multiple types
+     *
+     * @param ast - The AST to search
+     * @param nodeTypes - Array of node types to find
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const declarations = this.findNodesByTypes(ast, ['function_declaration', 'arrow_function']);
+     * ```
+     */
+    findNodesByTypes(ast, nodeTypes) {
+        const typeSet = new Set(nodeTypes);
+        const results = [];
+        this.traverse(ast, (node) => {
+            if (typeSet.has(node.type)) {
+                results.push(node);
+            }
+        });
+        return results;
+    }
+    /**
+     * Find the first node of a specific type
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of node to find
+     * @returns The first matching node, or null if not found
+     */
+    findFirstNode(ast, nodeType) {
+        let result = null;
+        this.traverse(ast, (node) => {
+            if (node.type === nodeType) {
+                result = node;
+                return false; // Stop traversal
+            }
+            return undefined;
+        });
+        return result;
+    }
+    /**
+     * Find nodes matching a predicate function
+     *
+     * @param ast - The AST to search
+     * @param predicate - Function that returns true for matching nodes
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const asyncFunctions = this.findNodesWhere(ast, (node) =>
+     *   node.type === 'function_declaration' && node.text.includes('async')
+     * );
+     * ```
+     */
+    findNodesWhere(ast, predicate) {
+        const results = [];
+        this.traverse(ast, (node) => {
+            if (predicate(node)) {
+                results.push(node);
+            }
+        });
+        return results;
+    }
+    // ============================================================================
+    // Ancestor/Descendant Methods
+    // ============================================================================
+    /**
+     * Find the nearest ancestor of a specific type
+     *
+     * Traverses up the tree from the given node to find the first ancestor
+     * matching the specified type.
+     *
+     * @param node - The starting node
+     * @param nodeType - The type of ancestor to find
+     * @param ast - The AST containing the node (needed for parent lookup)
+     * @returns The ancestor node, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const parentClass = this.findAncestor(methodNode, 'class_declaration', ast);
+     * ```
+     */
+    findAncestor(node, nodeType, ast) {
+        const parentChain = this.getParentChain(ast, node);
+        // Search from immediate parent up to root
+        for (let i = parentChain.length - 1; i >= 0; i--) {
+            const parent = parentChain[i];
+            if (parent && parent.type === nodeType) {
+                return parent;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find all ancestors of a node
+     *
+     * @param node - The starting node
+     * @param ast - The AST containing the node
+     * @returns Array of ancestor nodes from immediate parent to root
+     */
+    findAllAncestors(node, ast) {
+        const parentChain = this.getParentChain(ast, node);
+        return parentChain.reverse();
+    }
+    /**
+     * Find all descendants of a node
+     *
+     * @param node - The starting node
+     * @returns Array of all descendant nodes
+     */
+    findDescendants(node) {
+        const descendants = [];
+        const collect = (n) => {
+            for (const child of n.children) {
+                descendants.push(child);
+                collect(child);
+            }
+        };
+        collect(node);
+        return descendants;
+    }
+    /**
+     * Find descendants of a specific type
+     *
+     * @param node - The starting node
+     * @param nodeType - The type of descendants to find
+     * @returns Array of matching descendant nodes
+     */
+    findDescendantsByType(node, nodeType) {
+        const results = [];
+        const search = (n) => {
+            for (const child of n.children) {
+                if (child.type === nodeType) {
+                    results.push(child);
+                }
+                search(child);
+            }
+        };
+        search(node);
+        return results;
+    }
+    // ============================================================================
+    // Node Text Methods
+    // ============================================================================
+    /**
+     * Get the text content of a node
+     *
+     * Returns the source text corresponding to the node's position.
+     * If content is provided, extracts from content; otherwise uses node.text.
+     *
+     * @param node - The node to get text for
+     * @param content - Optional source content to extract from
+     * @returns The text content of the node
+     *
+     * @example
+     * ```typescript
+     * const functionName = this.getNodeText(identifierNode, context.content);
+     * ```
+     */
+    getNodeText(node, content) {
+        if (content) {
+            const lines = content.split('\n');
+            const startLine = node.startPosition.row;
+            const endLine = node.endPosition.row;
+            const startCol = node.startPosition.column;
+            const endCol = node.endPosition.column;
+            if (startLine === endLine) {
+                // Single line
+                const line = lines[startLine];
+                return line ? line.slice(startCol, endCol) : node.text;
+            }
+            else {
+                // Multi-line
+                const result = [];
+                for (let i = startLine; i <= endLine; i++) {
+                    const line = lines[i];
+                    if (!line)
+                        continue;
+                    if (i === startLine) {
+                        result.push(line.slice(startCol));
+                    }
+                    else if (i === endLine) {
+                        result.push(line.slice(0, endCol));
+                    }
+                    else {
+                        result.push(line);
+                    }
+                }
+                return result.join('\n');
+            }
+        }
+        return node.text;
+    }
+    /**
+     * Get the trimmed text content of a node
+     *
+     * @param node - The node to get text for
+     * @param content - Optional source content to extract from
+     * @returns The trimmed text content
+     */
+    getNodeTextTrimmed(node, content) {
+        return this.getNodeText(node, content).trim();
+    }
+    // ============================================================================
+    // Pattern Matching Methods
+    // ============================================================================
+    /**
+     * Match an AST against a pattern
+     *
+     * Searches the AST for nodes matching the specified pattern and returns
+     * all matches with their confidence scores.
+     *
+     * @param ast - The AST to search
+     * @param pattern - The pattern to match
+     * @returns Array of match results
+     *
+     * @example
+     * ```typescript
+     * const matches = this.matchPattern(ast, {
+     *   type: 'function_declaration',
+     *   children: [{ type: 'identifier', capture: 'name' }]
+     * });
+     * ```
+     */
+    matchPattern(ast, pattern) {
+        const results = [];
+        this.traverse(ast, (node) => {
+            const captures = new Map();
+            const confidence = this.matchNode(node, pattern, captures);
+            if (confidence > 0) {
+                results.push({
+                    node,
+                    confidence,
+                    captures,
+                    startPosition: node.startPosition,
+                    endPosition: node.endPosition,
+                });
+            }
+        });
+        return results;
+    }
+    /**
+     * Match a single node against a pattern
+     *
+     * @param node - The node to match
+     * @param pattern - The pattern to match against
+     * @param captures - Map to store captured nodes
+     * @returns Confidence score (0-1), 0 if no match
+     */
+    matchNode(node, pattern, captures) {
+        let score = 1.0;
+        // Check type
+        if (pattern.type !== undefined && node.type !== pattern.type) {
+            return 0;
+        }
+        // Check text
+        if (pattern.text !== undefined) {
+            const textMatches = this.matchText(node.text, pattern.text, pattern.exactText);
+            if (!textMatches) {
+                return 0;
+            }
+        }
+        // Check children count constraints
+        if (pattern.minChildren !== undefined && node.children.length < pattern.minChildren) {
+            return 0;
+        }
+        if (pattern.maxChildren !== undefined && node.children.length > pattern.maxChildren) {
+            return 0;
+        }
+        // Check custom predicate
+        if (pattern.predicate !== undefined && !pattern.predicate(node)) {
+            return 0;
+        }
+        // Check child patterns
+        if (pattern.children !== undefined && pattern.children.length > 0) {
+            const childScore = this.matchChildPatterns(node, pattern.children, pattern.matchDescendants, captures);
+            if (childScore === 0) {
+                return 0;
+            }
+            score *= childScore;
+        }
+        // Capture the node if requested
+        if (pattern.capture !== undefined) {
+            captures.set(pattern.capture, node);
+        }
+        return score;
+    }
+    /**
+     * Match text against a pattern (string or regex)
+     */
+    matchText(text, pattern, exact) {
+        if (pattern instanceof RegExp) {
+            return pattern.test(text);
+        }
+        if (exact) {
+            return text === pattern;
+        }
+        return text.includes(pattern);
+    }
+    /**
+     * Match child patterns against node children
+     */
+    matchChildPatterns(node, childPatterns, matchDescendants, captures) {
+        const nodesToSearch = matchDescendants
+            ? this.findDescendants(node)
+            : node.children;
+        let matchedCount = 0;
+        for (const childPattern of childPatterns) {
+            let found = false;
+            for (const child of nodesToSearch) {
+                const childCaptures = captures || new Map();
+                const confidence = this.matchNode(child, childPattern, childCaptures);
+                if (confidence > 0) {
+                    found = true;
+                    matchedCount++;
+                    // Merge captures
+                    if (captures) {
+                        for (const [key, value] of childCaptures) {
+                            captures.set(key, value);
+                        }
+                    }
+                    break;
+                }
+            }
+            if (!found) {
+                return 0; // Required child pattern not found
+            }
+        }
+        return matchedCount / childPatterns.length;
+    }
+    // ============================================================================
+    // Traversal Methods
+    // ============================================================================
+    /**
+     * Traverse the AST depth-first
+     *
+     * Visits each node in the AST, calling the visitor function.
+     * The visitor can return false to stop traversal of a subtree.
+     *
+     * @param ast - The AST to traverse
+     * @param visitor - Function called for each node
+     * @param options - Traversal options
+     *
+     * @example
+     * ```typescript
+     * this.traverse(ast, (node, parent, depth) => {
+     *   console.log(`${node.type} at depth ${depth}`);
+     *   if (depth > 5) return false; // Stop going deeper
+     * });
+     * ```
+     */
+    traverse(ast, visitor, options = {}) {
+        const { maxDepth, skipTypes, includeRoot = true } = options;
+        const skipSet = skipTypes ? new Set(skipTypes) : null;
+        const visit = (node, parent, depth) => {
+            // Check max depth
+            if (maxDepth !== undefined && depth > maxDepth) {
+                return true;
+            }
+            // Check if type should be skipped
+            if (skipSet && skipSet.has(node.type)) {
+                return true;
+            }
+            // Call visitor
+            const result = visitor(node, parent, depth);
+            // If visitor returns false, stop traversal of this subtree
+            if (result === false) {
+                return true;
+            }
+            // Traverse children
+            for (const child of node.children) {
+                visit(child, node, depth + 1);
+            }
+            return true;
+        };
+        if (includeRoot) {
+            visit(ast.rootNode, null, 0);
+        }
+        else {
+            for (const child of ast.rootNode.children) {
+                visit(child, ast.rootNode, 1);
+            }
+        }
+    }
+    /**
+     * Traverse a specific node and its descendants
+     *
+     * @param node - The node to start traversal from
+     * @param visitor - Function called for each node
+     * @param options - Traversal options
+     */
+    traverseNode(node, visitor, options = {}) {
+        const { maxDepth, skipTypes } = options;
+        const skipSet = skipTypes ? new Set(skipTypes) : null;
+        const visit = (n, parent, depth) => {
+            if (maxDepth !== undefined && depth > maxDepth) {
+                return true;
+            }
+            if (skipSet && skipSet.has(n.type)) {
+                return true;
+            }
+            const result = visitor(n, parent, depth);
+            if (result === false) {
+                return true;
+            }
+            for (const child of n.children) {
+                visit(child, n, depth + 1);
+            }
+            return true;
+        };
+        visit(node, null, 0);
+    }
+    // ============================================================================
+    // Utility Methods
+    // ============================================================================
+    /**
+     * Get the parent chain from root to a specific node
+     *
+     * @param ast - The AST to search
+     * @param targetNode - The node to find parents for
+     * @returns Array of parent nodes from root to immediate parent
+     */
+    getParentChain(ast, targetNode) {
+        const parents = [];
+        const findParents = (node, chain) => {
+            if (node === targetNode) {
+                parents.push(...chain);
+                return true;
+            }
+            for (const child of node.children) {
+                if (findParents(child, [...chain, node])) {
+                    return true;
+                }
+            }
+            return false;
+        };
+        findParents(ast.rootNode, []);
+        return parents;
+    }
+    /**
+     * Get the immediate parent of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the parent of
+     * @returns The parent node, or null if node is root
+     */
+    getParent(ast, node) {
+        const chain = this.getParentChain(ast, node);
+        return chain.length > 0 ? chain[chain.length - 1] ?? null : null;
+    }
+    /**
+     * Get the depth of a node in the AST
+     *
+     * @param ast - The AST containing the node
+     * @param targetNode - The node to get depth for
+     * @returns The depth (0 for root), or -1 if not found
+     */
+    getNodeDepth(ast, targetNode) {
+        let foundDepth = -1;
+        this.traverse(ast, (node, _parent, depth) => {
+            if (node === targetNode) {
+                foundDepth = depth;
+                return false;
+            }
+            return undefined;
+        });
+        return foundDepth;
+    }
+    /**
+     * Check if a node is a leaf node (has no children)
+     *
+     * @param node - The node to check
+     * @returns true if the node has no children
+     */
+    isLeafNode(node) {
+        return node.children.length === 0;
+    }
+    /**
+     * Get direct children of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type of children to find
+     * @returns Array of matching child nodes
+     */
+    getChildrenByType(node, nodeType) {
+        return node.children.filter((child) => child.type === nodeType);
+    }
+    /**
+     * Get the first direct child of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type of child to find
+     * @returns The first matching child, or null if not found
+     */
+    getFirstChildByType(node, nodeType) {
+        return node.children.find((child) => child.type === nodeType) ?? null;
+    }
+    /**
+     * Check if a node has a child of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type to check for
+     * @returns true if a child of the specified type exists
+     */
+    hasChildOfType(node, nodeType) {
+        return node.children.some((child) => child.type === nodeType);
+    }
+    /**
+     * Check if a node has a descendant of a specific type
+     *
+     * @param node - The starting node
+     * @param nodeType - The type to check for
+     * @returns true if a descendant of the specified type exists
+     */
+    hasDescendantOfType(node, nodeType) {
+        const descendants = this.findDescendantsByType(node, nodeType);
+        return descendants.length > 0;
+    }
+    /**
+     * Get siblings of a node (other children of the same parent)
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find siblings for
+     * @returns Array of sibling nodes (excluding the node itself)
+     */
+    getSiblings(ast, node) {
+        const parent = this.getParent(ast, node);
+        if (!parent) {
+            return [];
+        }
+        return parent.children.filter((child) => child !== node);
+    }
+    /**
+     * Get the next sibling of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the next sibling for
+     * @returns The next sibling, or null if none exists
+     */
+    getNextSibling(ast, node) {
+        const parent = this.getParent(ast, node);
+        if (!parent) {
+            return null;
+        }
+        const index = parent.children.indexOf(node);
+        if (index === -1 || index === parent.children.length - 1) {
+            return null;
+        }
+        return parent.children[index + 1] ?? null;
+    }
+    /**
+     * Get the previous sibling of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the previous sibling for
+     * @returns The previous sibling, or null if none exists
+     */
+    getPreviousSibling(ast, node) {
+        const parent = this.getParent(ast, node);
+        if (!parent) {
+            return null;
+        }
+        const index = parent.children.indexOf(node);
+        if (index <= 0) {
+            return null;
+        }
+        return parent.children[index - 1] ?? null;
+    }
+    /**
+     * Count nodes of a specific type in the AST
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of nodes to count
+     * @returns The count of matching nodes
+     */
+    countNodes(ast, nodeType) {
+        return this.findNodes(ast, nodeType).length;
+    }
+    /**
+     * Check if the AST contains a node of a specific type
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type to check for
+     * @returns true if a node of the specified type exists
+     */
+    hasNodeOfType(ast, nodeType) {
+        return this.findFirstNode(ast, nodeType) !== null;
+    }
+    /**
+     * Get the line number of a node (1-indexed)
+     *
+     * @param node - The node to get the line number for
+     * @returns The line number (1-indexed)
+     */
+    getLineNumber(node) {
+        return node.startPosition.row + 1;
+    }
+    /**
+     * Get the column number of a node (1-indexed)
+     *
+     * @param node - The node to get the column number for
+     * @returns The column number (1-indexed)
+     */
+    getColumnNumber(node) {
+        return node.startPosition.column + 1;
+    }
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if a detector is an AST detector
+ *
+ * @param detector - The detector to check
+ * @returns true if the detector is an ASTDetector
+ */
+export function isASTDetector(detector) {
+    return detector.detectionMethod === 'ast';
+}
+//# sourceMappingURL=ast-detector.js.map