Add advanced CSS-like selector syntax to Foresta.js AST query engine

[Copilot]

Extends Foresta.js with CSS-inspired selector syntax for querying JavaScript ASTs, enabling attribute filtering, pseudo-classes, combinators, and logical operators while maintaining backward compatibility.

Implementation

Attribute Selectors

• Exact match: Literal[value=42]
• String operators: [name^="is"] (starts), [name$="Value"] (ends), [name*="test"] (contains)
• RegExp patterns: [name~/^get[A-Z]/]
• Nested properties: CallExpression[callee.name=fetch]

Pseudo-Classes

• Negation: :not([value=42])
• Position: :first-child, :last-child, :nth-child(n)
• State: :empty, :has(ReturnStatement)

Combinators

• Direct child: BlockStatement > VariableDeclaration
• Adjacent sibling: Property + Property
• General sibling: Property ~ Property
• Space: Consecutive parent chain (unchanged from v1 for compatibility)

Logical Operators

• OR: VariableDeclaration, FunctionDeclaration

Additional AST Support

Added visitor methods for FunctionDeclaration, IfStatement, ReturnStatement, SwitchStatement, Export nodes, ArrowFunctionExpression, AwaitExpression, ArrayExpression.

Example Usage

// Find all fetch() API calls
new foresta('CallExpression[callee.name=fetch]')

// Find getters matching naming convention
new foresta('Identifier[name~/^get[A-Z]/]')

// Find functions with return statements
new foresta('FunctionExpression:has(ReturnStatement)')

// Find non-empty objects
new foresta('ObjectExpression:not(:empty)')

// Export function declarations
new foresta('ExportNamedDeclaration > FunctionDeclaration')

Notes

• Space combinator maintains v1 behavior (consecutive parent chain, not CSS descendant)
• 57 tests with 89% coverage
• User-provided regex patterns are executed without validation

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add advanced selector types and options for Foresta.js AST engine</issue_title>
<issue_description>## Overview
Expand Foresta.js selector engine to support advanced selector types and options, inspired by CSS selectors and attribute syntax. These enhancements will enable even more powerful queries on JavaScript ASTs, supporting use-cases like attribute querying, logical compounds, structural queries, and more.

---

Requirements

Implement the following selector types/options with comprehensive unit tests covering all syntax examples and ensuring correctness across lexical scopes, closures, async contexts, promises, etc. The implementation should work seamlessly with all ASTs generated by Esprima.

1. Property Value Attribute Selectors

• Literal[value=42] // match Literal nodes with value 42
• Identifier[name^="is"] // match identifiers with names starting with 'is'

2. Negations

• VariableDeclarator:not(#foo) // match VariableDeclarators not named 'foo'

3. Ancestor & Structural Selectors

• FunctionDeclaration VariableDeclaration // VariableDeclaration within a function
• BlockStatement > VariableDeclaration // VariableDeclaration as direct child of a block
• Property + Property // Sibling properties within an object expression

4. Pseudo-Classes

• :first-child, :last-child, :nth-child(n)
• :empty (node has no children)
• :has(selector) for parent nodes containing a match

5. Logical & Group Compound Selectors

• VariableDeclaration, FunctionDeclaration // OR
• (VariableDeclarator[name=foo] FunctionExpression) // AND/grouping

6. Reference & Usage Queries

• CallExpression[callee.name=fetch] // Find all fetch() calls

7. Scope Queries

• Scope filtering: match variables limited to global, local, or block

8. Control Flow/Contextual Selectors

• IfStatement > ReturnStatement // Return inside if
• SwitchCase > Literal // Literal inside case

9. Pattern Selectors (RegExp)

• Identifier[name~/^get[A-Z]/] // Identifiers starting with 'get' followed by a capital

10. Source Location Selectors

• :range[10:15-10:30] // Nodes covering character/line range

11. JSDoc or Export Selectors

• ExportNamedDeclaration > FunctionDeclaration // Top-level export functions

---

PR/Validation

• Add Jest unit tests for all new selector syntaxes and edge cases, including block scopes, async/await, closures, and promise chains
• Ensure all new selectors work on code samples with nested/complex scopes
• Update the README with usage examples for each new selector type

---

Notes

• Follow existing code and test conventions
• See discussion in (README and examples/basic.js) for design history

---

Please implement with GitHub Copilot, referencing this issue, and assign to @joelmartinez.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add advanced selector types and options for Foresta.js AST engine #7

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.