wip

Author: Jamess-Lucass

copilot-instructions.md

@@ -0,0 +1,139 @@
+# Copilot Instructions
+
+This file provides guidance for GitHub Copilot and other AI coding assistants when working with code in this repository.
+
+## Project Overview
+
+GoatQuery is a .NET library that provides REST API query capabilities including paging, ordering, filtering, searching, and selecting. It consists of two main packages:
+
+- **GoatQuery**: Core library targeting .NET Standard 2.0/2.1 with lexer, parser, and evaluator components
+- **GoatQuery.AspNetCore**: ASP.NET Core integration targeting .NET 6.0/8.0 with action filters and middleware
+
+The library parses OData-like query syntax into expression trees and applies them to IQueryable sources.
+
+## Common Development Commands
+
+### Build
+
+Use the following commands to build the project:
+
+- Build all projects:
+  - `make build`
+- Build individual projects:
+  - `dotnet build ./src/GoatQuery/src --configuration Release`
+  - `dotnet build ./src/GoatQuery.AspNetCore/src --configuration Release`
+
+### Test
+
+Run tests using:
+
+- All tests:
+  - `make test`
+- Directly with dotnet:
+  - `dotnet test ./src/GoatQuery/tests`
+- Specific test categories:
+  - `dotnet test ./src/GoatQuery/tests --filter "Category=Filter"`
+  - `dotnet test ./src/GoatQuery/tests --filter "Category=OrderBy"`
+
+### Package and Publish
+
+- Create NuGet packages:
+  - `make package`
+- Publish to local feed:
+  - `make publish-local`
+
+### Run Example Application
+
+To run the example app:
+
+- `cd example`
+- `dotnet run`
+  Endpoints are available at `/controller/users` or `/minimal/users`.
+
+## Architecture Overview
+
+### Core Components
+
+**Lexer (`QueryLexer`)**: Tokenizes query strings into structured tokens (identifiers, operators, literals, etc.)
+
+**Parser (`QueryParser`)**: Converts tokens into Abstract Syntax Tree (AST) nodes representing filter expressions and order-by statements
+
+**Evaluators**: Transform AST nodes into LINQ Expression Trees:
+
+- `FilterEvaluator`: Handles filtering logic with support for comparison operators, logical operators, and special nullable handling
+- `OrderByEvaluator`: Processes ordering statements with multiple columns and directions
+
+**Query Application (`QueryableExtension.Apply`)**: Main entry point that orchestrates the entire pipeline from query string to modified IQueryable
+
+### AST Node Hierarchy
+
+- `QueryExpression` (base)
+  - `InfixExpression`: Binary operations (eq, ne, and, or, etc.)
+  - `Identifier`: Property references
+  - Literals: `StringLiteral`, `IntegerLiteral`, `GuidLiteral`, `DateTimeLiteral`, etc.
+
+### Supported Query Operations
+
+- **Filtering**: `firstname eq 'John'`, `age gt 21`, `date lt 2024-01-01`
+- **Logical operators**: `and`, `or` with proper precedence
+- **Comparison operators**: `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `contains`
+- **Data types**: String, Integer, Decimal, Float, Double, DateTime, Date, Guid, Boolean, Null
+- **Grouping**: Parentheses for expression precedence
+- **Ordering**: `firstname desc, age asc`
+- **Paging**: `top=10`, `skip=20`
+- **Counting**: `count=true`
+
+### ASP.NET Core Integration
+
+The `EnableQueryAttribute<T>` action filter automatically:
+
+1. Extracts query parameters from HTTP request
+2. Constructs Query object
+3. Applies query to controller's IQueryable result
+4. Returns paginated response with optional count
+
+### Property Mapping
+
+Uses `JsonPropertyNameAttribute` for mapping JSON property names to C# properties, enabling consistent API naming conventions.
+
+### Error Handling
+
+Uses FluentResults pattern throughout for comprehensive error reporting with detailed messages for invalid queries, unsupported operations, and type mismatches.
+
+## Testing Patterns
+
+Tests use xUnit with parameterized test data to validate:
+
+- Lexer tokenization accuracy
+- Parser AST generation
+- Filter evaluation correctness
+- OrderBy functionality
+- Integration scenarios
+
+Test data includes comprehensive edge cases for nullable types, date handling, numeric precision, and complex nested expressions.
+
+## Key Implementation Notes
+
+- **Nullable Handling**: Special logic for nullable DateTime comparisons using date-only operations
+- **Type Conversion**: Automatic conversion between numeric types with overflow detection
+- **Case Sensitivity**: Property names are case-insensitive, string operations use culture-invariant comparisons
+- **Performance**: Expression tree compilation for efficient query execution
+- **Security**: Parameterized expressions prevent injection attacks
+
+## Development Guidelines for Copilot
+
+When using Copilot to work on query evaluation logic:
+
+- Ensure consistency between lexer tokens, parser AST nodes, and evaluator logic
+- Add or update tests for new operators or data types
+- Consider nullable type handling for new features
+- Update both the core library and ASP.NET Core integration when adding functionality
+- Use the FluentResults pattern for error handling
+
+If you are refactoring, adding features, or fixing bugs, please:
+
+- Follow .NET and C# best practices
+- Write clear, maintainable code
+- Update documentation and tests as needed
+
+For any automation, prefer using Makefile targets or standard dotnet CLI commands.

src/GoatQuery/src/Ast/Node.cs

@@ -7,7 +7,7 @@ public Node(Token token)
         _token = token;
     }
 
-    public string TokenLiteral()
+    public virtual string TokenLiteral()
     {
         return _token.Literal;
     }

src/GoatQuery/src/Ast/PropertyPath.cs

@@ -15,13 +15,8 @@ public string GetFullPath()
         return string.Join("/", Segments);
     }
 
-    public string GetFirstSegment()
+    public override string TokenLiteral()
     {
-        return Segments.FirstOrDefault();
-    }
-
-    public List<string> GetRemainingSegments()
-    {
-        return Segments.Skip(1).ToList();
+        return GetFullPath();
     }
 }