feat: Add comprehensive documentation for [GeneratedRegex] source generator, including usage, patterns, and common pitfalls

aalmada · aalmada · commit 093daaf5d95c · 2026-04-03T15:14:56.000+01:00
diff --git a/.github/skills/csharp_regex/SKILL.md b/.github/skills/csharp_regex/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: csharp_regex
+description: Use the [GeneratedRegex] source generator for ALL regex in .NET 7+ C#. Produces AOT-safe, trimming-friendly, compile-time regex with zero startup cost and better throughput than RegexOptions.Compiled. Trigger whenever the user writes, reviews, or asks about regex in C# — including new Regex(...), Regex.IsMatch, pattern matching, string validation, or text parsing — even if they don't mention source generation. Never suggest new Regex(...) with RegexOptions.Compiled when [GeneratedRegex] is available.
+---
+
+# C# Source-Generated Regex Skill
+
+Use `[GeneratedRegex]` on a `partial` method or property so the compiler emits a fully-optimised, AOT-safe `Regex` implementation at build time. This delivers the throughput of `RegexOptions.Compiled` with near-zero startup cost, and the output is ordinary C# that you can read and debug.
+
+## Why this matters
+
+`new Regex(pattern, RegexOptions.Compiled)` pays a heavy startup cost (reflection-emit, JIT compilation) and is not AOT-safe. `[GeneratedRegex]` compiles the pattern into readable C# during the build, giving you:
+
+- **Better throughput** than `RegexOptions.Compiled` (and more, in some benchmarks)
+- **Near-zero startup cost** — no JIT compile at runtime
+- **AOT / trimming safe** — no `Reflection.Emit`
+- **Debuggable** — step through the generated C# in any debugger
+- **Automatic singleton caching** — no `static readonly` field needed
+
+Diagnostic `SYSLIB1045` fires when the compiler detects a place that could use `[GeneratedRegex]` but doesn't.
+
+## Quick reference
+
+| Concept | See |
+|---------|-----|
+| Constraints, method vs property, minimal examples | [basics.md](references/basics.md) |
+| `RegexOptions`, timeouts, culture | [options.md](references/options.md) |
+| Where to declare regex, file organisation | [patterns.md](references/patterns.md) |
+| Common mistakes and compiler errors | [pitfalls.md](references/pitfalls.md) |
+
+## Minimal examples
+
+**Method (≥ .NET 7):**
+```csharp
+public static partial class Patterns
+{
+    [GeneratedRegex(@"\d+")]
+    public static partial Regex Digits();
+}
+```
+
+**Property (≥ .NET 9, C# 13):**
+```csharp
+public static partial class Patterns
+{
+    [GeneratedRegex(@"\d+")]
+    public static partial Regex Digits { get; }
+}
+```
+
+## Essential rules at a glance
+
+- The **containing class** must be `partial`.
+- Method form: must be `static`, `partial`, parameterless, non-generic, returning `Regex`.
+- Property form: must be `static`, `partial`, getter-only, returning `Regex` (C# 13 / .NET 9+).
+- Do **not** add `RegexOptions.Compiled` — it is ignored by the generator.
+- The generator handles caching; no `static readonly` field is needed.
+
+## What to read next
+
+- First time using `[GeneratedRegex]` → [basics.md](references/basics.md)
+- Need `IgnoreCase`, timeouts, or culture → [options.md](references/options.md)
+- Deciding where to put the declaration → [patterns.md](references/patterns.md)
+- Getting a compiler error → [pitfalls.md](references/pitfalls.md)
diff --git a/.github/skills/csharp_regex/references/basics.md b/.github/skills/csharp_regex/references/basics.md
@@ -0,0 +1,98 @@
+# GeneratedRegex Basics
+
+Source: https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-source-generators
+API ref: https://learn.microsoft.com/dotnet/api/system.text.regularexpressions.generatedregexattribute?view=net-10.0
+
+## Requirements
+
+| Requirement | Detail |
+|-------------|--------|
+| Runtime | .NET 7+ (method); .NET 9+ for property form |
+| Language | C# 11+ (method); C# 13+ (property) |
+| Namespace | `System.Text.RegularExpressions` |
+| NuGet | Built into `System.Text.RegularExpressions.dll` — no extra package |
+
+## How it works
+
+Applying `[GeneratedRegex]` to a `partial` method or property tells the Roslyn source generator (`System.Text.RegularExpressions.Generator`) to emit a complete `Regex`-derived class at compile time. The generated class:
+
+- Embeds all match logic as readable C# (no `Reflection.Emit`)
+- Caches a singleton instance so every call to the method / property returns the same object
+- Requires no explicit `static readonly` field — the caching is inside the generated implementation
+
+## Attribute constructors
+
+```csharp
+// Pattern only
+[GeneratedRegex(string pattern)]
+
+// Pattern + options
+[GeneratedRegex(string pattern, RegexOptions options)]
+
+// Pattern + options + culture
+[GeneratedRegex(string pattern, RegexOptions options, string cultureName)]
+
+// Pattern + options + timeout (ms)
+[GeneratedRegex(string pattern, RegexOptions options, int matchTimeoutMilliseconds)]
+
+// All four
+[GeneratedRegex(string pattern, RegexOptions options, int matchTimeoutMilliseconds, string cultureName)]
+```
+
+## Method form (≥ .NET 7)
+
+```csharp
+using System.Text.RegularExpressions;
+
+public static partial class Validators
+{
+    // basic
+    [GeneratedRegex(@"^\d{4}-\d{2}-\d{2}$")]
+    public static partial Regex IsoDateFormat();
+
+    // with options
+    [GeneratedRegex(@"^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$",
+        RegexOptions.IgnoreCase, "en-US")]
+    public static partial Regex Email();
+}
+```
+
+Usage:
+```csharp
+bool isValid = Validators.IsoDateFormat().IsMatch("2024-01-15"); // true
+```
+
+Note: each call to `IsoDateFormat()` returns the **same cached** `Regex` instance — the call is cheap.
+
+## Property form (≥ .NET 9, C# 13)
+
+```csharp
+public static partial class Validators
+{
+    [GeneratedRegex(@"^[A-Z]{2}\d{6}$")]
+    public static partial Regex PassportNumber { get; }
+}
+```
+
+Usage:
+```csharp
+bool ok = Validators.PassportNumber.IsMatch(input);
+```
+
+Prefer the property form if you use C# 13+ — it reads at the call site like a constant rather than a factory call.
+
+## Instance method
+
+When the regex is relevant only inside one class, declare it there directly:
+
+```csharp
+public partial class OrderValidator
+{
+    [GeneratedRegex(@"^\d{5}(-\d{4})?$")]
+    private static partial Regex ZipCode();
+
+    public bool IsValidZip(string zip) => ZipCode().IsMatch(zip);
+}
+```
+
+The class must still be `partial`.
diff --git a/.github/skills/csharp_regex/references/options.md b/.github/skills/csharp_regex/references/options.md
@@ -0,0 +1,65 @@
+# RegexOptions, Timeouts, and Culture
+
+Source: https://learn.microsoft.com/dotnet/api/system.text.regularexpressions.regexoptions?view=net-10.0
+Source: https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-source-generators
+
+## RegexOptions reference
+
+| Option | Notes |
+|--------|-------|
+| `IgnoreCase` | Case-insensitive match. Combine with `cultureName` for locale-aware casing. |
+| `Multiline` | `^` and `$` match line boundaries rather than string start/end. |
+| `Singleline` | `.` matches `\n` as well. |
+| `IgnorePatternWhitespace` | Unescaped whitespace is ignored; allows inline comments with `#`. |
+| `ExplicitCapture` | Only named groups capture; reduces allocations when you don't need unnamed groups. |
+| `NonBacktracking` | Linear-time matching (no catastrophic backtracking). Not supported by the source generator — use with `new Regex(...)`. |
+| `Compiled` | **Ignored by the source generator.** Do not include it. |
+| `RightToLeft` | Match right-to-left. Supported by the source generator. |
+| `CultureInvariant` | If combined with `IgnoreCase`, use invariant culture for case comparisons. |
+| `ECMAScript` | ECMAScript-compatible behaviour. Cannot combine with most other options. |
+
+Combine with bitwise OR:
+```csharp
+[GeneratedRegex(@"hello\s+world",
+    RegexOptions.IgnoreCase | RegexOptions.Multiline)]
+public static partial Regex HelloWorld();
+```
+
+## Culture for case-insensitive matching
+
+When `IgnoreCase` is set, supply a BCP-47 culture name to pin the casing table to a specific locale. The source generator bakes the casing table at **compile time** (unlike `new Regex(...)`, which resolves it at runtime).
+
+```csharp
+// Turkish: 'I' casing differs from en-US
+[GeneratedRegex(@"^[a-z]+$", RegexOptions.IgnoreCase, "tr-TR")]
+public static partial Regex LowercaseTurkish();
+
+// Invariant culture (portable, deterministic)
+[GeneratedRegex(@"^[a-z]+$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)]
+public static partial Regex LowercaseInvariant();
+```
+
+When no culture is specified and `IgnoreCase` is used, the generator uses the **invariant culture** at compile time. This differs from runtime `new Regex(...)` which uses the current culture. Always specify a culture when locale-sensitive matching matters.
+
+## Timeouts
+
+Pass a timeout (milliseconds) to guard against ReDoS on untrusted input. Use `Timeout.Infinite` (-1) only when the input is fully trusted and bounded.
+
+```csharp
+// 500 ms timeout — good for parsing untrusted user input
+[GeneratedRegex(@"(\w+\s*)+", RegexOptions.None, matchTimeoutMilliseconds: 500)]
+public static partial Regex WordSequence();
+
+// All four parameters
+[GeneratedRegex(@"^[a-z]+$",
+    RegexOptions.IgnoreCase,
+    matchTimeoutMilliseconds: 1000,
+    cultureName: "en-US")]
+public static partial Regex AlphaOnly();
+```
+
+> **Security:** Always set a timeout when the regex pattern or input comes from or is affected by user data. Polynomially-complex patterns (nested quantifiers, alternation with overlap) can cause runaway matching without a timeout.
+
+## NonBacktracking and source generation
+
+`RegexOptions.NonBacktracking` provides linear-time matching via a finite automaton engine. The source generator **does not support** this option — it will fall back to a runtime error or no-op. If you need linear-time guarantees, use `new Regex(pattern, RegexOptions.NonBacktracking)` and cache the instance in a `static readonly` field yourself.
diff --git a/.github/skills/csharp_regex/references/patterns.md b/.github/skills/csharp_regex/references/patterns.md
@@ -0,0 +1,113 @@
+# Organisation Patterns
+
+Source: https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-source-generators
+
+## Where to declare generated regex
+
+The right placement depends on scope and reuse:
+
+### Dedicated static class (recommended for shared patterns)
+
+Centralise patterns that are used across multiple files or feature areas:
+
+```csharp
+// File: Patterns.cs (or RegexPatterns.cs)
+using System.Text.RegularExpressions;
+
+public static partial class Patterns
+{
+    [GeneratedRegex(@"^\d{4}-\d{2}-\d{2}$")]
+    public static partial Regex IsoDate();
+
+    [GeneratedRegex(@"^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$",
+        RegexOptions.IgnoreCase, "en-US")]
+    public static partial Regex Email();
+
+    [GeneratedRegex(@"^\+?[1-9]\d{6,14}$")]
+    public static partial Regex PhoneE164();
+}
+```
+
+Usage anywhere in the assembly:
+```csharp
+if (!Patterns.Email().IsMatch(input)) { ... }
+```
+
+### Declaring on the consuming class (private scope)
+
+When only one class needs the pattern, declare it there to keep the scope narrow:
+
+```csharp
+public partial class InvoiceParser
+{
+    [GeneratedRegex(@"INV-\d{6}", RegexOptions.IgnoreCase)]
+    private static partial Regex InvoiceNumber();
+
+    public string? ExtractInvoiceNumber(string text) =>
+        InvoiceNumber().Match(text).Value;
+}
+```
+
+The class must be `partial` — if it isn't already, make it so.
+
+### Feature-area file splitting
+
+For large modules with many patterns, split a single `partial` class across multiple files by feature area:
+
+```
+Patterns/
+  Patterns.cs          ← partial class declaration (no members)
+  Patterns.Dates.cs    ← date-related patterns
+  Patterns.Email.cs    ← email/address patterns
+  Patterns.Finance.cs  ← currency, IBAN, card numbers
+```
+
+Each file:
+```csharp
+// Patterns.Dates.cs
+public static partial class Patterns
+{
+    [GeneratedRegex(@"^\d{4}-\d{2}-\d{2}$")]
+    public static partial Regex IsoDate();
+}
+```
+
+### Co-location with a validator
+
+When a pattern is the heart of a validation class, keep it co-located:
+
+```csharp
+public static partial class PostalCodeValidator
+{
+    [GeneratedRegex(@"^\d{5}(-\d{4})?$")]
+    private static partial Regex UsZip();
+
+    [GeneratedRegex(@"^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$",
+        RegexOptions.IgnoreCase)]
+    private static partial Regex UkPostcode();
+
+    public static bool Validate(string code, string country) =>
+        country switch
+        {
+            "US" => UsZip().IsMatch(code),
+            "UK" => UkPostcode().IsMatch(code),
+            _ => throw new ArgumentOutOfRangeException(nameof(country))
+        };
+}
+```
+
+## Naming conventions
+
+| Pattern | Recommended name | Rationale |
+|---------|-----------------|-----------|
+| Method form | Noun or noun phrase: `Email()`, `IsoDate()`, `PhoneNumber()` | The `()` implies a call; keep the name a descriptor of what it matches |
+| Property form | Same noun: `Email`, `IsoDate` | No parens, reads like a static constant |
+
+Avoid prefixes like `Get`, `Create`, or `Match` — the attribute already communicates the nature of the member.
+
+## Viewing the generated code
+
+In Visual Studio: right-click the method or property declaration → **Go To Definition**.
+Or expand **Dependencies → Analyzers → System.Text.RegularExpressions.Generator → RegexGenerator.g.cs** in Solution Explorer.
+
+The generated code is fully readable C# and can be stepped through in the debugger.
diff --git a/.github/skills/csharp_regex/references/pitfalls.md b/.github/skills/csharp_regex/references/pitfalls.md
