@cratis/pi 7.102.0 → 7.103.1

package/package/corpus/skills/analyzing-dotnet-performance/references/critical-patterns.md

@@ -0,0 +1,291 @@
+# Critical .NET Performance Anti-Patterns
+
+## Contents
+
+- Async / Tasks
+- Memory / Allocation
+- Strings
+- Regular Expressions
+- JSON Serialization
+- Networking
+- General
+- Detection
+
+17 patterns that cause deadlocks, order-of-magnitude regressions, or excessive allocations.
+
+## Async / Tasks
+
+### Never Block on Async (Sync-over-Async)
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+public string GetData()
+    => GetDataAsync().Result;
+```
+✅
+```csharp
+public async Task<string> GetDataAsync()
+    => await GetDataInternalAsync();
+```
+**Impact: Deadlocks or thread pool starvation; wastes threads, destroys scalability.**
+
+### Never Await a ValueTask Multiple Times
+🔴 **AVOID** | .NET Core 2.1+
+
+❌
+```csharp
+ValueTask<int> vt = SomeMethodAsync();
+int a = await vt;
+int b = await vt;
+```
+✅
+```csharp
+int result = await SomeMethodAsync();
+```
+**Impact: Undefined behavior — silent data corruption or exceptions.**
+
+## Memory / Allocation
+
+### Use Span\<T\> / AsSpan Instead of Substring for Slicing
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+string sub = input.Substring(5, 10);
+```
+✅
+```csharp
+ReadOnlySpan<char> sub = input.AsSpan(5, 10);
+```
+**Impact: Eliminates per-slice allocations; 2-4x faster via vectorization.**
+
+### Use ArrayPool\<T\> for Temporary Buffers
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+byte[] buf = new byte[4096];
+```
+✅
+```csharp
+byte[] buf = ArrayPool<byte>.Shared.Rent(4096);
+Process(buf);
+ArrayPool<byte>.Shared.Return(buf);
+```
+**Impact: Dramatically reduces GC pressure for buffer-heavy workloads.**
+
+### Avoid stackalloc in Loops
+🔴 **AVOID** | .NET 5+
+
+❌
+```csharp
+for (int i = 0; i < 10_000; i++)
+    Span<byte> buf = stackalloc byte[1024];
+```
+✅
+```csharp
+Span<byte> buf = stackalloc byte[1024];
+for (int i = 0; i < 10_000; i++) { Process(buf); }
+```
+**Impact: StackOverflowException — unrecoverable, no catch possible.**
+
+### Avoid Boxing Value Types
+🔴 **AVOID** | .NET 6+
+
+❌
+```csharp
+string s = string.Format("{0}.{1}", major, minor);
+```
+✅
+```csharp
+string s = $"{major}.{minor}";
+```
+**Impact: When replacing `string.Format` with C# 10+ interpolation, typical improvements are ~40% faster with significantly less allocation. Actual gains vary by call site.**
+
+## Strings
+
+### Use StringComparison.Ordinal for Non-Linguistic Comparisons
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+bool found = text.IndexOf("Content-Type") >= 0;
+```
+✅
+```csharp
+bool found = text.Contains("Content-Type", StringComparison.Ordinal);
+```
+**Impact: 2-3x faster; OrdinalIgnoreCase hash codes ~3.3x faster.**
+
+### Use AsSpan Instead of Substring
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+int val = int.Parse(str.Substring(5, 3));
+```
+✅
+```csharp
+int val = int.Parse(str.AsSpan(5, 3));
+```
+**Impact: Eliminates one string allocation per parse operation.**
+
+## Regular Expressions
+
+### Use Source-Generated Regex [GeneratedRegex]
+🔴 **ALWAYS** use `[GeneratedRegex]` for all static regex patterns | .NET 7+
+
+❌
+```csharp
+private static readonly Regex s_re =
+    new(@"\w+@\w+\.\w+", RegexOptions.Compiled);
+```
+✅
+```csharp
+[GeneratedRegex(@"\w+@\w+\.\w+")]
+private static partial Regex EmailRegex();
+```
+**Impact: Always beneficial or neutral for static patterns — near-zero startup, better throughput, and required for AOT/trimming scenarios.**
+
+### Avoid Nested Quantifiers (Catastrophic Backtracking)
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+var r = new Regex(@"^(\w+)+$");
+```
+✅
+```csharp
+var r = new Regex(@"^\w+$", RegexOptions.NonBacktracking);
+```
+**Impact: Can hang process indefinitely on crafted input.**
+
+### Use TryGetValue Instead of ContainsKey + Indexer
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+if (dict.ContainsKey(key))
+    Use(dict[key]);
+```
+✅
+```csharp
+if (dict.TryGetValue(key, out var value))
+    Use(value);
+```
+**Impact: ~2x faster (50% reduction in lookup time).**
+
+### Avoid LINQ in Hot Paths
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+bool found = items.Any(x => x.Name == target);
+```
+✅
+```csharp
+bool found = false;
+foreach (var item in items)
+    if (item.Name == target) { found = true; break; }
+```
+**Impact: Eliminates 1-3 allocations per call; measurable in tight loops.**
+
+### Don't Iterate IEnumerable Multiple Times
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+foreach (Type t in types) { Validate(t); }
+_types = types.ToArray();
+```
+✅
+```csharp
+Type[] arr = types.ToArray();
+foreach (Type t in arr) { Validate(t); }
+_types = arr;
+```
+**Impact: Halves enumeration cost; prevents bugs from re-executing deferred queries.**
+
+## JSON Serialization
+
+### Use System.Text.Json Source Generator
+🔴 **DO** | .NET 6+
+
+❌
+```csharp
+string json = JsonSerializer.Serialize(post);
+```
+✅
+```csharp
+[JsonSerializable(typeof(BlogPost))]
+internal partial class AppJsonCtx : JsonSerializerContext { }
+string json = JsonSerializer.Serialize(post, AppJsonCtx.Default.BlogPost);
+```
+**Impact: 37-44% faster; enables trimming and Native AOT.**
+
+### Cache JsonSerializerOptions
+🔴 **DO** | .NET 5+
+
+❌
+```csharp
+JsonSerializer.Serialize(obj, new JsonSerializerOptions());
+```
+✅
+```csharp
+private static readonly JsonSerializerOptions s_opts = new();
+JsonSerializer.Serialize(obj, s_opts);
+```
+**Impact: Up to 592x slower without caching (.NET 6); always cache or use defaults.**
+
+## Networking
+
+### Reuse HttpClient Instances
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+using var client = new HttpClient();
+await client.GetStringAsync(url);
+```
+✅
+```csharp
+private static readonly HttpClient s_http = new(new SocketsHttpHandler
+{ PooledConnectionLifetime = TimeSpan.FromMinutes(5) });
+await s_http.GetStringAsync(url);
+```
+**Impact: Prevents socket exhaustion; 6-12x faster concurrent HTTPS.**
+
+## General
+
+### Use SearchValues\<T\> for Repeated Set Searches
+🔴 **DO** | .NET 8+
+
+❌
+```csharp
+int pos = text.IndexOfAny("ABCDEF".ToCharArray());
+```
+✅
+```csharp
+private static readonly SearchValues<char> s_hex = SearchValues.Create("ABCDEF");
+int pos = text.AsSpan().IndexOfAny(s_hex);
+```
+**Impact: 2-10x faster for chars; 10-30x faster for multi-string (.NET 9+).**
+
+## Detection
+
+Scan recipes for critical anti-patterns. Run these and report exact counts of issues found in each case.
+
+```bash
+# .IndexOf(string) without StringComparison (culture-aware, 2-3x slower)
+grep -rn --include='*.cs' -E '\.IndexOf\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .Substring( calls (allocates new string — consider AsSpan)
+grep -rn --include='*.cs' '\.Substring(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .StartsWith/.EndsWith without StringComparison (culture-aware, 2-3x slower)
+grep -rn --include='*.cs' -E '\.(StartsWith|EndsWith)\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .Contains(string) without StringComparison — NOTE: will also match collection .Contains() calls; filter to string receivers
+grep -rn --include='*.cs' -E '\.Contains\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```

package/package/corpus/skills/analyzing-dotnet-performance/references/io-and-serialization.md

@@ -0,0 +1,135 @@
+# I/O, Serialization & General Patterns
+
+## Contents
+
+- Use HttpCompletionOption.ResponseHeadersRead for Streaming
+- Use Async FileStream Operations
+- Use Memory\<byte\> Overloads for Stream.ReadAsync/WriteAsync
+- Use Span-Based TryFormat for Number Formatting
+- Use static readonly for Runtime Devirtualization
+- Avoid Explicit Static Constructors — Use Field Initializers
+- Detection
+  - Patterns Requiring Manual Review
+
+### Use HttpCompletionOption.ResponseHeadersRead for Streaming
+🟡 **DO** use `ResponseHeadersRead` when downloading large responses | .NET Core 3.0+
+
+❌
+```csharp
+var response = await client.GetAsync(uri);
+```
+✅
+```csharp
+using var response = await client.GetAsync(uri, HttpCompletionOption.ResponseHeadersRead);
+using var stream = await response.Content.ReadAsStreamAsync();
+await stream.CopyToAsync(destinationStream);
+```
+
+**Impact: ~2x faster for large downloads (10MB+), dramatically reduced memory usage.**
+
+### Use Async FileStream Operations
+🟡 **DO** use `FileStream` with `useAsync: true` for scalable file I/O | .NET 6+
+
+❌
+```csharp
+using var fs = new FileStream(path, FileMode.Open);
+```
+✅
+```csharp
+await using var fs = new FileStream(path, FileMode.Open, FileAccess.Read,
+    FileShare.Read, bufferSize: 4096, useAsync: true);
+
+byte[] buffer = new byte[1024];
+while (await fs.ReadAsync(buffer) != 0) { /* process */ }
+```
+
+**Impact: Up to 3x faster async reads; allocation reduced from megabytes to hundreds of bytes.**
+
+### Use Memory\<byte\> Overloads for Stream.ReadAsync/WriteAsync
+🟡 **DO** use `Memory<byte>`-based stream overloads instead of `byte[]` overloads | .NET 5+
+
+❌
+```csharp
+await stream.ReadAsync(buffer, 0, buffer.Length);
+await stream.WriteAsync(buffer, 0, buffer.Length);
+```
+✅
+```csharp
+await stream.ReadAsync(buffer.AsMemory());
+await stream.WriteAsync(buffer.AsMemory());
+```
+
+**Impact: Eliminates ~72 KB allocation per 1,000 read/write pairs on NetworkStream.**
+
+### Use Span-Based TryFormat for Number Formatting
+🟡 **DO** use `TryFormat` to format numbers into `Span<char>` buffers | .NET Core 2.1+
+
+❌
+```csharp
+string formatted = value.ToString();
+destination.Write(formatted);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[20];
+if (value.TryFormat(buffer, out int charsWritten))
+    destination.Write(buffer[..charsWritten]);
+```
+
+**Impact: Int32.ToString() ~2x faster in .NET Core 2.1, Int32 parsing ~5x faster in .NET Core 3.0.**
+
+### Use static readonly for Runtime Devirtualization
+🟡 **DO** store implementations in `static readonly` fields for JIT devirtualization | .NET Core 3.0+
+
+❌
+```csharp
+private static Base s_impl = new DerivedImpl();
+s_impl.Process();
+```
+✅
+```csharp
+private static readonly Base s_impl = new DerivedImpl();
+s_impl.Process();
+
+private static readonly bool s_feature =
+    Environment.GetEnvironmentVariable("Feature") == "1";
+```
+
+**Impact: Virtual call eliminated entirely — can be inlined to zero overhead. Dead code elimination in tier 1.**
+
+### Avoid Explicit Static Constructors — Use Field Initializers
+🟡 **AVOID** explicit `static` constructors when field initializers suffice | .NET Core 3.0+
+
+❌
+```csharp
+class Foo
+{
+    static readonly int s_value;
+    static Foo() { s_value = ComputeValue(); }
+}
+```
+✅
+```csharp
+class Foo
+{
+    static readonly int s_value = ComputeValue();
+}
+```
+
+**Impact: Enables better JIT optimization and reduces potential lock overhead on static method access.**
+
+## Detection
+
+Scan recipes for I/O and serialization anti-patterns. Run these and report exact counts.
+
+```bash
+# new HttpClient() (socket exhaustion risk)
+grep -rn --include='*.cs' 'new HttpClient(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# new JsonSerializerOptions() not cached (592x slower in .NET 6)
+grep -rn --include='*.cs' 'new JsonSerializerOptions' --exclude-dir=bin --exclude-dir=obj . | grep -v 'static\|readonly' | wc -l
+```
+
+### Patterns Requiring Manual Review
+
+- **`JsonSerializer.Serialize/Deserialize` without source-gen context**: Can't determine from grep if a context parameter is passed

package/package/corpus/skills/analyzing-dotnet-performance/references/memory-and-strings.md

@@ -0,0 +1,219 @@
+# Memory & String Patterns
+
+## Contents
+
+- Use ReadOnlySpan\<byte\> for Constant Byte Data
+- Use stackalloc for Small Temporary Buffers
+- Use Span.TryWrite for Allocation-Free Interpolation
+- Use Span.Split() for Zero-Allocation Splitting
+- Use UTF8 String Literals (u8 suffix)
+- Use ReadOnlySpan\<char\> Pattern Matching with switch
+- Use params ReadOnlySpan\<T\> to Eliminate Array Allocations
+- Avoid Chained String-Returning Operations
+- Cache char.ToString() for Known Character Sets
+- Detection
+  - Patterns Requiring Manual Review
+
+### Use ReadOnlySpan\<byte\> for Constant Byte Data
+🟡 **DO** assign constant byte arrays to `ReadOnlySpan<byte>` | .NET 5+
+
+❌
+```csharp
+byte[] data = new byte[] { 0x48, 0x65, 0x6C, 0x6C, 0x6F };
+```
+✅
+```csharp
+ReadOnlySpan<byte> data = [0x48, 0x65, 0x6C, 0x6C, 0x6F];
+ReadOnlySpan<int> primes = [2, 3, 5, 7, 11, 13];
+```
+
+**Impact: ~100x faster access than static byte[] field, zero allocation.**
+
+### Use stackalloc for Small Temporary Buffers
+🟡 **DO** use `stackalloc` for small, fixed-size temporary buffers | .NET Core+
+
+❌
+```csharp
+char[] buffer = new char[64];
+guid.TryFormat(buffer, out int written);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[64];
+guid.TryFormat(buffer, out int written);
+```
+
+**Impact: Zero heap allocation, no GC pressure, instant alloc/dealloc.**
+
+### Use Span.TryWrite for Allocation-Free Interpolation
+🟡 **DO** use `MemoryExtensions.TryWrite` to format into `Span<char>` buffers | .NET 6+
+
+❌
+```csharp
+string formatted = $"Date: {dt:R}";
+destination.Write(formatted);
+```
+✅
+```csharp
+Span<char> buffer = stackalloc char[64];
+buffer.TryWrite($"Date: {dt:R}", out int charsWritten);
+```
+
+**Impact: Zero heap allocation for formatting operations.**
+
+### Use Span.Split() for Zero-Allocation Splitting
+🟡 **DO** use `MemoryExtensions.Split` for allocation-free string splitting | .NET 9+
+
+❌
+```csharp
+string[] parts = input.Split(',');
+```
+✅
+```csharp
+foreach (Range range in input.AsSpan().Split(','))
+{
+    ReadOnlySpan<char> segment = input.AsSpan(range);
+}
+```
+
+**Impact: 208 bytes → 0 bytes per split, 2x faster.**
+
+### Use UTF8 String Literals (u8 suffix)
+🟡 **DO** use the `u8` suffix for compile-time UTF8 `ReadOnlySpan<byte>` | .NET 7+
+
+❌
+```csharp
+byte[] header = Encoding.UTF8.GetBytes("Content-Type");
+```
+✅
+```csharp
+ReadOnlySpan<byte> header = "Content-Type"u8;
+```
+
+**Impact: 17ns → 0.006ns — eliminates runtime transcoding entirely.**
+
+### Use ReadOnlySpan\<char\> Pattern Matching with switch
+🟡 **DO** use `switch` on `ReadOnlySpan<char>` for allocation-free string matching | C# 11+
+
+❌
+```csharp
+switch (attr.Value.Trim()) { case "preserve": /* ... */ break; }
+```
+✅
+```csharp
+switch (attr.Value.AsSpan().Trim())
+{
+    case "preserve": return Preserve;
+    case "default": return Default;
+}
+```
+
+**Impact: Eliminates string allocation from Trim() in switch-based dispatch.**
+
+### Use params ReadOnlySpan\<T\> to Eliminate Array Allocations
+🟡 **DO** add `params ReadOnlySpan<T>` overloads to library methods | C# 13 / .NET 9+
+
+❌
+```csharp
+public static void Log(params string[] messages) { /* ... */ }
+Log("Starting", "Processing", "Done");
+```
+✅
+```csharp
+public static void Log(params ReadOnlySpan<string> messages) { /* ... */ }
+Log("Starting", "Processing", "Done");
+```
+
+**Impact: Eliminates params array allocation. E.g., Path.Join with 5+ segments saves 64 bytes per call.**
+
+### Avoid Chained String-Returning Operations
+🟡 **AVOID** chains of 3+ string-returning method calls that each allocate intermediates | .NET Core+
+
+**Pattern 1: Chained .Replace() calls**
+
+❌
+```csharp
+string result = input.Replace("a", "b").Replace("c", "d").Replace("e", "f");
+```
+✅
+```csharp
+var sb = new StringBuilder(input.Length);
+// single pass replacing all patterns
+```
+
+**Pattern 2: Chained Regex.Replace() calls**
+
+❌
+```csharp
+public static string Underscore(this string input) =>
+    Regex3.Replace(Regex2.Replace(Regex1.Replace(input, "$1_$2"), "$1_$2"), "_").ToLower();
+```
+✅
+```csharp
+return string.Create(totalLength, state, (span, s) => { /* write directly */ });
+```
+
+**Pattern 3: += string concatenation in loops**
+
+❌
+```csharp
+string result = "";
+foreach (var part in parts)
+    result += separator + part;
+```
+✅
+```csharp
+var sb = new StringBuilder();
+foreach (var part in parts)
+    sb.Append(separator).Append(part);
+return sb.ToString();
+```
+
+**Impact: Eliminates N-1 intermediate string allocations per chain. For `+=` in loops, eliminates O(n²) total allocation.**
+
+### Cache char.ToString() for Known Character Sets
+🟡 **DO** cache `char.ToString()` results when the set of characters is small and known | .NET Core+
+
+❌
+```csharp
+return symbol.ToString();
+
+foreach (var prefix in UnitPrefixes)
+    input = input.Replace(prefix.Value.Name, prefix.Key.ToString());
+```
+✅
+```csharp
+private static readonly FrozenDictionary<char, string> s_charStrings =
+    new Dictionary<char, string>
+    {
+        ['k'] = "k", ['M'] = "M", ['G'] = "G",
+    }.ToFrozenDictionary();
+
+return s_charStrings[symbol];
+```
+
+**Impact: Eliminates one string allocation per char.ToString() call. Significant when called in loops or on hot paths.**
+
+## Detection
+
+Scan recipes for memory and string anti-patterns. Run these and report exact counts.
+
+```bash
+# .ToLower()/.ToUpper() without culture parameter (allocates + culture-sensitive)
+grep -rn --include='*.cs' -E '\.(ToLower|ToUpper)\(\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# Chained .Replace( calls (3+ on one line — intermediate string allocations)
+grep -rn --include='*.cs' '\.Replace(.*\.Replace(.*\.Replace(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# params in method signatures (array allocation per call)
+grep -rn --include='*.cs' 'params ' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# LINQ on strings — .All/.Any on IEnumerable<char> (replace with foreach loop)
+grep -rn --include='*.cs' -E '\.(All|Any)\(char\.' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```
+
+### Patterns Requiring Manual Review
+
+- **Boxing via string.Format**: Can't determine argument types from grep — needs type analysis
+- **`+=` string concatenation in loops**: `+=` matches all types (int, list, event, string) — needs type context to confirm string
+- **`char.ToString()`**: Requires knowing the variable type is `char` — not reliably greppable