{"id":50928717,"url":"https://github.com/tareknajem04/jeninnet.filequery","last_synced_at":"2026-06-17T02:01:15.841Z","repository":{"id":362153987,"uuid":"1255449767","full_name":"TarekNajem04/Jeninnet.FileQuery","owner":"TarekNajem04","description":"High-performance file system querying with GitIgnore, Glob, and Regex pattern support for .NET.","archived":false,"fork":false,"pushed_at":"2026-06-10T01:02:18.000Z","size":2390,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T01:11:54.561Z","etag":null,"topics":["csharp","dotnet","file-search","gitignore","glob","nuget","pattern-matching","regex"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TarekNajem04.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.html","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":null},"created_at":"2026-05-31T20:57:29.000Z","updated_at":"2026-06-09T17:23:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TarekNajem04/Jeninnet.FileQuery","commit_stats":null,"previous_names":["tareknajem04/jeninnet.filequery"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/TarekNajem04/Jeninnet.FileQuery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TarekNajem04%2FJeninnet.FileQuery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TarekNajem04%2FJeninnet.FileQuery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TarekNajem04%2FJeninnet.FileQuery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TarekNajem04%2FJeninnet.FileQuery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TarekNajem04","download_url":"https://codeload.github.com/TarekNajem04/Jeninnet.FileQuery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TarekNajem04%2FJeninnet.FileQuery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34430688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnet","file-search","gitignore","glob","nuget","pattern-matching","regex"],"created_at":"2026-06-17T02:00:47.864Z","updated_at":"2026-06-17T02:01:15.835Z","avatar_url":"https://github.com/TarekNajem04.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jeninnet.FileQuery\r\n\r\n![GitHub Actions CI Workflow Status](https://img.shields.io/github/actions/workflow/status/TarekNajem04/Jeninnet.FileQuery/ci.yml)\r\n![GitHub release](https://img.shields.io/github/v/release/TarekNajem04/Jeninnet.FileQuery)\r\n![GitHub contributors](https://img.shields.io/github/contributors/TarekNajem04/Jeninnet.FileQuery)\r\n[![GitHub stars](https://img.shields.io/github/stars/TarekNajem04/Jeninnet.FileQuery)](https://github.com/TarekNajem04/Jeninnet.FileQuery/stargazers)\r\n[![GitHub license](https://img.shields.io/github/license/TarekNajem04/Jeninnet.FileQuery)](https://github.com/TarekNajem04/Jeninnet.FileQuery/blob/main/LICENSE)\r\n\r\n![NuGet Version](https://img.shields.io/nuget/v/Jeninnet.FileQuery)\r\n[![NuGet downloads](https://img.shields.io/nuget/dt/Jeninnet.FileQuery)](https://www.nuget.org/packages/Jeninnet.FileQuery.CommandLine/)\r\n\r\n**A high-performance, deterministic file discovery and filtering engine for .NET.**\r\n\r\n---\r\n\r\n## 📊 Repo Stats\r\n\r\n![Repobeats analytics image](https://repobeats.axiom.co/api/embed/57d92552dfb25309185f7457c01037a504b5fa24.svg \"Repobeats analytics image\")\r\n\r\n---\r\n\r\n`Jeninnet.FileQuery` is a modern, high-performance file query system designed for .NET 10 and C# 14. It combines multiple pattern dialects—**GitIgnore**, **Glob**, and **Regular Expressions**—into a unified, deterministic, and allocation-free matching pipeline. Decoupled from `System.IO`, the engine allows precise, scalable file discovery across massive directory structures on Windows, Linux, and macOS.\r\n\r\nThe Phase 2 observability surface adds async progress snapshots, optional match audit diagnostics, deep cancellation verification, and configurable IO recovery strategies without changing default query behavior.\r\n\r\n---\r\n\r\n## 📂 Project Suite Directory\r\n\r\nThis repository contains the core library and its companion packages:\r\n\r\n*   **[Core Engine (Jeninnet.FileQuery)](./src/Jeninnet.FileQuery/README.md)**: The main matching runtime, builders, and parser pipeline.\r\n*   **[CommandLine Integration (Jeninnet.FileQuery.CommandLine)](./src/Jeninnet.FileQuery.CommandLine/README.md)**: Bridges command-line arguments (using `System.CommandLine`) to file query patterns.\r\n*   **[DependencyInjection Integration (Jeninnet.FileQuery.DependencyInjection)](./src/Jeninnet.FileQuery.DependencyInjection/README.md)**: Configures and registers the engine and its components in standard .NET host applications.\r\n*   **[Documentation Suite (docs/)](./docs/README.md)**: Deep technical specifications, guides, and architectural whitepapers.\r\n*   **[Benchmark Suite (benchmarks/)](./benchmarks/README.md)**: Performance measurements and allocation verification.\r\n*   **[Samples (samples/)](./samples/AdvancedUsage/README.md)**: Practical examples showing basic to advanced usage.\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\nGet up and running in seconds using the fluent API.\r\n\r\n### Installation\r\n\r\nInstall the core package from NuGet:\r\n\r\n```bash\r\ndotnet add package Jeninnet.FileQuery\r\n```\r\n\r\n### Basic Usage\r\n\r\n```csharp\r\nusing Jeninnet.FileQuery;\r\n\r\n// 1. Configure the query using the fluent builder\r\nvar query = FileQuery.From(@\"C:\\MyProject\")\r\n                     .Where(\"**\")           // Exclude everything by default\r\n                     .Where(\"!*.tmp\")       // Include all .tmp files\r\n                     .Where(\"!src/**/*.cs\") // Include .cs files under the src folder\r\n                     .UsingHybrid()         // Auto-detect pattern dialects (GitIgnore/Glob/Regex)\r\n                     .IgnoreCase()          // Use case-insensitive matching\r\n                     .Build();\r\n\r\n// 2. Execute the query using the runtime engine\r\nvar engine = FileQueryRuntime.Create();\r\nvar files = engine.Execute(query);\r\n\r\nforeach (var file in files)\r\n{\r\n    Console.WriteLine(file);\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🏗️ High-Level Architecture Overview\r\n\r\n`Jeninnet.FileQuery` splits filesystem traversal, pattern compilation, and matching into distinct, highly optimized layers:\r\n\r\n```txt\r\n                     ┌───────────────────────┐\r\n                     │     Client Code       │\r\n                     └───────────┬───────────┘\r\n                                 │\r\n                                 ▼\r\n                     ┌───────────────────────┐\r\n                     │   FileQueryBuilder    │\r\n                     └───────────┬───────────┘\r\n                                 │\r\n                                 ▼\r\n                     ┌───────────────────────┐\r\n                     │       FileQuery       │\r\n                     │  (Immutable Request)  │\r\n                     └───────────┬───────────┘\r\n                                 │\r\n                                 ▼\r\n                     ┌───────────────────────┐\r\n                     │   IFileQueryEngine    │\r\n                     └───────────┬───────────┘\r\n                                 │ Executes\r\n                                 ▼\r\n                     ┌───────────────────────┐\r\n                     │   HybridPathMatcher   │\r\n                     └───────────┬───────────┘\r\n          ┌──────────────────────┼──────────────────────┐\r\n          ▼                      ▼                      ▼\r\n┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐\r\n│ GitIgnoreMatcher │   │   GlobMatcher    │   │   RegexMatcher   │\r\n└──────────────────┘   └──────────────────┘   └──────────────────┘\r\n          │                      │                      │\r\n          └──────────────────────┼──────────────────────┘\r\n                                 ▼\r\n                       ┌───────────────────┐\r\n                       │    IFileSystem    │\r\n                       └───────────────────┘\r\n```\r\n\r\n1.  **Orchestration \u0026 API Layer**: [FileQueryBuilder](./src/Jeninnet.FileQuery/FileQueryBuilder.cs) accepts configuration inputs and builds an immutable [FileQuery](./src/Jeninnet.FileQuery/FileQuery.cs) instance.\r\n2.  **Matching Layer**: [HybridPathMatcher](./src/Jeninnet.FileQuery/Matching/Compiled/HybridPathMatcher.cs) decomposes rules and routes them to target matchers (GitIgnore, Glob, Regex). GitIgnore inclusions take final precedence.\r\n3.  **Compilation \u0026 Parser Layer**: Tokenizes raw strings, checks them against semantic and structural invariants (e.g., recursive wildcard isolation), and produces compiled instruction sets.\r\n4.  **IO Traversal Layer**: Traverses directories using an stack-based or queue-based execution plan, decoupling all IO through the [IFileSystem](./src/Jeninnet.FileQuery/IO/IFileSystem.cs) interface.\r\n\r\n---\r\n\r\n## 💡 Advanced \u0026 Developer-Oriented Features\r\n\r\n### 1. POSIX Character Classes\r\nThe engine supports POSIX-named character classes within Glob and GitIgnore bracket expressions (e.g., `[[:digit:]]`). Supported classes include:\r\n*   `[:digit:]`: Decimal digits (`0-9`)\r\n*   `[:alpha:]`: Alphabetic characters\r\n*   `[:alnum:]`: Alphanumeric characters\r\n*   `[:space:]`: White space characters\r\n*   `[:blank:]`: Space or horizontal tab characters\r\n*   `[:upper:]` / `[:lower:]`: Uppercase / lowercase characters\r\n*   `[:print:]` / `[:graph:]`: Printable / visible characters\r\n*   `[:punct:]`: Punctuation and symbol characters\r\n*   `[:cntrl:]`: Control characters\r\n*   `[:xdigit:]`: Hexadecimal digits\r\n\r\n### 2. Zero-Allocation Matching Path\r\nTo support massive file trees containing millions of files, the matching evaluation loop is completely allocation-free, utilizing `ReadOnlySpan\u003cchar\u003e` and stack-allocated parsing arrays.\r\n\r\n### 3. Decoupled Filesystem Abstraction\r\nBy using the [IFileSystem](./src/Jeninnet.FileQuery/IO/IFileSystem.cs) interface, the traversal engine can run against virtual or mock filesystems (useful for cloud workloads and fast test isolation).\r\n\r\n### 4. Advanced Traversal Tuning\r\nThrough `TraversalOptions`, developers can choose between `DepthFirst` (stack-based) or `BreadthFirst` (queue-based) search strategies and control symlink behavior with policies like `Ignore`, `Follow`, or `FollowWithCycleDetection`.\r\n\r\n### 5. Observability and Recovery\r\nAsync scans can report live statistics through `IProgress\u003cFileQueryProgress\u003e`:\r\n\r\n```csharp\r\nvar progress = new Progress\u003cFileQueryProgress\u003e(snapshot =\u003e\r\n{\r\n    Console.WriteLine($\"{snapshot.EntriesScanned} entries scanned\");\r\n});\r\n\r\nawait foreach (var file in engine.ExecuteAsync(query, progress, cancellationToken))\r\n{\r\n    Console.WriteLine(file);\r\n}\r\n```\r\n\r\nOpt-in diagnostics explain match outcomes and responsible pattern metadata:\r\n\r\n```csharp\r\nvar diagnostics = new Progress\u003cFileQueryDiagnostic\u003e(entry =\u003e\r\n{\r\n    Console.WriteLine($\"{entry.RelativePath}: {entry.Outcome} ({entry.Pattern})\");\r\n});\r\n\r\nvar query = FileQuery.From(\"./src\")\r\n                     .Where(\"**\", \"!**/*.cs\")\r\n                     .WithDiagnostics(diagnostics)\r\n                     .WithErrorRecovery(FileQueryErrorRecoveryOptions.Retry(2))\r\n                     .Build();\r\n```\r\n\r\n---\r\n\r\n## 📜 Governance and Philosophy\r\n\r\nThe project adheres to the **[Jeninnet.FileQuery Constitution](./constitution.md)**:\r\n1.  **Engine‑First \u0026 Pattern‑Compiled**: Always tokenize, validate invariants, and compile before running; no ad-hoc string regexes or runtime heuristics.\r\n2.  **Compile‑Time Safe**: Malformed patterns never throw during tokenization; all syntax errors are captured during the invariant phase to output rich diagnostics.\r\n3.  **AOT-Ready**: Reflection is completely avoided to ensure compatibility with .NET Native AOT compilation.\r\n\r\n---\r\n\r\n## 🏛️ Compatibility \u0026 Tech Stack\r\n\r\n*   **TFM**: `.NET 10`\r\n*   **Language**: `C# 14`\r\n*   **Test Suite**: MSTest + Moq + Coverlet\r\n*   **Enforcement**: Central Package Management (CPM), strict `.editorconfig` rules, and architecture tests enforcing zero allocations.\r\n\r\n---\r\n\r\n## 🚀 Contributing \u0026 Roadmap\r\n\r\n*   Please consult **[CONTRIBUTING.md](./CONTRIBUTING.md)** before submitting pull requests.\r\n*   See **[ROADMAP.md](./ROADMAP.md)** for planned features (such as Progress Reporting, Audit Diagnostics, and Parallel Traversal).\r\n\r\n---\r\n\r\n## 📜 License\r\n\r\nThis project is licensed under the MIT License. See **[LICENSE](./LICENSE)** for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftareknajem04%2Fjeninnet.filequery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftareknajem04%2Fjeninnet.filequery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftareknajem04%2Fjeninnet.filequery/lists"}