From dcf2040d3bae88c130c58bf2a17de4ede45e2713 Mon Sep 17 00:00:00 2001 From: Brent Miller Date: Tue, 17 Nov 2026 17:08:21 -0600 Subject: [PATCH] docs(analyzers): record three candidates and queue follow-ups Read the BlazingFastDotnet guide a fourth time against the shipped rule set. Three shapes clear the bar: the Func middleware delegate, UseStaticFiles, and string.Split used only to enumerate. Four shapes already have an installed owner and move to the skipped file. Three Tier 2 shapes wait on a defect in review. Split the guidance-document history out of catalog.md into guidance-reads.md so both files stay under the line limit. Add every candidate, its score, and its code fix to plans/roadmap.md. --- lode/dotnet/analyzer-candidates/catalog.md | 69 +------ .../analyzer-candidates/guidance-reads.md | 101 ++++++++++ lode/dotnet/analyzer-candidates/index.md | 89 ++++++++- .../analyzer-candidates/skipped-decisions.md | 21 +- lode/lode-map.md | 5 +- plans/roadmap.md | 181 +++++++++++++++++- 6 files changed, 392 insertions(+), 74 deletions(-) create mode 100644 lode/dotnet/analyzer-candidates/guidance-reads.md diff --git a/lode/dotnet/analyzer-candidates/catalog.md b/lode/dotnet/analyzer-candidates/catalog.md index 9037ea7..5c017e3 100644 --- a/lode/dotnet/analyzer-candidates/catalog.md +++ b/lode/dotnet/analyzer-candidates/catalog.md @@ -1,5 +1,5 @@ # Analyzer Candidates: Settled Catalog -*Updated: 2026-11-17T22:44:32Z* +*Updated: 2026-11-17T23:06:12Z* This file holds the settled side of the register: which rule shipped, which idea was checked and rejected, and which sweep closed. Every rule ships from @@ -57,7 +57,7 @@ fix provider. The rules E128125 to E128129 and E128136 to E128138 carry a diagnostic only. - Source A: the .NET performance skill guide in `EgorBo/BlazingFastDotnet`. -- Source B: the runtime unsafe-code best-practices page in `dotnet/docs`. +- Source B: the runtime unsafe-code guidance page in `dotnet/docs`. This table records the rule IDs so a later session can check for ID reuse. The rule description and the fix shape live in `src/E128.Analyzers/README.md`. @@ -97,68 +97,9 @@ tree does not carry. - E128128: the caller places the anchor field. - E128129: the replacement depends on whether the caller needs a deep or a shallow copy. -The guidance rows that stay a document and not a rule: - -| Row | Why it stays a document | -| -------------------------------------- | ----------------------------------------- | -| Ordinal string comparison | CA1307, CA1309, and CA1310 cover it | -| `ToLower()` equality idiom | Meziantou covers it | -| Runtime knob tuning | Environment variables, not source | -| False sharing and cache-line padding | Not visible to the compiler | -| Thread-local and striped counters | Detection needs runtime behavior | -| `WebApplication.CreateSlimBuilder` | Project-level choice, not a code defect | -| Source-generated JSON registration | Whole-project configuration, no local fix | -| Object header and MethodTable access | No supported replacement | -| Fuzzing and raw IL validation | Process guidance, not a code shape | -| `AggressiveInlining` overuse | The size heuristic is too noisy | - -## Second Read Of The Guidance Documents - -A second read on 2026-10-31 found ten more rows with a code shape that an -analyzer can see. Nine of them ship. The tenth folded into a shipped rule. - -| ID | Rule | Source | Code fix | Noise | -| ------------- | ------------------------------------------------------ | ------- | -------- | ------ | -| none | Static byte array literal becomes an RVA span property | C5 | Yes | Low | -| E128131 | Parse and format UTF-8 bytes without a string | C7, C28 | Yes | Low | -| E128132 | Use an ordinal comparer in a string dictionary or set | C27 | Yes | Low | -| E128133 | Look up a span key with `GetAlternateLookup` | C10 | Yes | Medium | -| E128134 | Use `BitOperations` instead of a manual bit loop | C17 | Yes | Medium | -| E128135 | Use `TensorPrimitives` over a numeric span | C12 | Partial | Medium | -| E128136 | Use `Span` instead of a pointer and a length | 16.1 | No | Low | -| E128137 | Do not access nonpublic BCL members | 3.4 | No | Low | -| E128138 | Do not emit raw IL with `ILGenerator` | 18.1 | No | Low | -| none | Guard pointer indexing with `Debug.Assert` | 9.4 | No | High | - -The byte literal row folded into E128061. That rule owns every -`private static readonly T[]` field, so a second rule would report the same -field twice. The E128061 fix reads a constant byte sequence as a -`ReadOnlySpan` property and every other element type as -`ImmutableArray`. - -The unsafe guidance row 20.2 says to abandon a pooled buffer instead of -returning it in `finally`. The repository requires a zero and a return in -`finally`. Keep the repository rule. It satisfies the row, because the buffer -is provably unused at that point. - -The `Debug.Assert` guard idea stays unshipped. Its noise is high, so it needs a -real defect in review before a rule is worth the false positives. The E128139 -ID belongs to the unaligned-access rule below. - -## Third Read Of The Guidance Documents - -A third read on 2026-10-31 found three code shapes that the first two reads -missed. Two of them ship a code fix. E128139 covers the `bool` case only. - -| ID | Rule | Source | Code fix | Noise | -| ------- | ------------------------------------------------------------ | --------------------------------- | ---------------- | ------ | -| E128139 | Do not move a non-blittable type through an unaligned access | Unsafe guide, struct bit patterns | `bool` read only | Low | -| E128140 | Use a span bulk method instead of an element loop | Performance guide, bulk span APIs | Yes | Low | -| E128141 | Use a u8 literal instead of `Encoding.UTF8.GetBytes` | Performance guide, UTF-8 parsing | Yes | Low | - -E128139 extends E128118 to the `Unsafe` read and write calls. E128118 covers -`MemoryMarshal` only. E128140 covers the `Fill`, `Clear`, and `CopyTo` shapes. -E128141 needs C# 11 or later, and the rule checks the language version. +Each read of the two guidance documents, the rows that stay a document, and the +unshipped idea that waits on a real defect live in +[guidance-reads.md](guidance-reads.md). ## Proof-Test Sweep Candidates diff --git a/lode/dotnet/analyzer-candidates/guidance-reads.md b/lode/dotnet/analyzer-candidates/guidance-reads.md new file mode 100644 index 0000000..ed90e63 --- /dev/null +++ b/lode/dotnet/analyzer-candidates/guidance-reads.md @@ -0,0 +1,101 @@ +# Guidance Document Reads +*Updated: 2026-11-17T23:06:12Z* + +Two published guidance documents seeded a large part of the rule set. Source A +is the performance skill guide in `EgorBo/BlazingFastDotnet`. Source B is the +runtime unsafe-code guidance page in `dotnet/docs`. + +Each read below checked the guide against the shipped rule set and the +installed analyzers. The catalog keeps the shipped rule IDs. See +[catalog.md](catalog.md). + +## Rows That Stay A Document + +| Row | Why it stays a document | +| -------------------------------------- | ----------------------------------------- | +| Ordinal string comparison | CA1307, CA1309, and CA1310 cover it | +| `ToLower()` equality idiom | Meziantou covers it | +| Runtime knob tuning | Environment variables, not source | +| False sharing and cache-line padding | Not visible to the compiler | +| Thread-local and striped counters | Detection needs runtime behavior | +| `WebApplication.CreateSlimBuilder` | Project-level choice, not a code defect | +| Source-generated JSON registration | Whole-project configuration, no local fix | +| Object header and MethodTable access | No supported replacement | +| Fuzzing and raw IL validation | Process guidance, not a code shape | +| `AggressiveInlining` overuse | The size heuristic is too noisy | +| NativeAOT publish properties | Publish configuration, not source | +| Hot-path wrappers and hash choice | No traffic or security requirement | + +## Second Read + +A second read on 2026-10-31 found ten more rows with a code shape that an +analyzer can see. Nine of them ship. The tenth folded into a shipped rule. + +| ID | Rule | Source | Code fix | Noise | +| ------------- | ------------------------------------------------------ | ------- | -------- | ------ | +| none | Static byte array literal becomes an RVA span property | C5 | Yes | Low | +| E128131 | Parse and format UTF-8 bytes without a string | C7, C28 | Yes | Low | +| E128132 | Use an ordinal comparer in a string dictionary or set | C27 | Yes | Low | +| E128133 | Look up a span key with `GetAlternateLookup` | C10 | Yes | Medium | +| E128134 | Use `BitOperations` instead of a manual bit loop | C17 | Yes | Medium | +| E128135 | Use `TensorPrimitives` over a numeric span | C12 | Partial | Medium | +| E128136 | Use `Span` instead of a pointer and a length | 16.1 | No | Low | +| E128137 | Do not access nonpublic BCL members | 3.4 | No | Low | +| E128138 | Do not emit raw IL with `ILGenerator` | 18.1 | No | Low | +| none | Guard pointer indexing with `Debug.Assert` | 9.4 | No | High | + +The byte literal row folded into E128061. That rule owns every +`private static readonly T[]` field, so a second rule would report the same +field twice. The E128061 fix reads a constant byte sequence as a +`ReadOnlySpan` property and every other element type as +`ImmutableArray`. + +The unsafe guidance row 20.2 says to abandon a pooled buffer instead of +returning it in `finally`. The repository requires a zero and a return in +`finally`. Keep the repository rule. It satisfies the row, because the buffer +is provably unused at that point. + +The `Debug.Assert` guard idea stays unshipped. Its noise is high, so it needs a +real defect in review before a rule is worth the false positives. The E128139 +ID belongs to the unaligned-access rule. + +## Third Read + +A third read on 2026-10-31 found three code shapes that the first two reads +missed. Two of them ship a code fix. E128139 covers the `bool` case only. + +| ID | Rule | Source | Code fix | Noise | +| ------- | ------------------------------------------------------------ | --------------------------------- | ---------------- | ------ | +| E128139 | Do not move a non-blittable type through an unaligned access | Unsafe guide, struct bit patterns | `bool` read only | Low | +| E128140 | Use a span bulk method instead of an element loop | Performance guide, bulk span APIs | Yes | Low | +| E128141 | Use a u8 literal instead of `Encoding.UTF8.GetBytes` | Performance guide, UTF-8 parsing | Yes | Low | + +E128139 extends E128118 to the `Unsafe` read and write calls. E128118 covers +`MemoryMarshal` only. E128140 covers the `Fill`, `Clear`, and `CopyTo` shapes. +E128141 needs C# 11 or later, and the rule checks the language version. + +## Fourth Read + +A read on 2026-11-17 checked the whole guide against the shipped rule set and +the installed analyzers. The guide covers profiling, runtime knobs, NativeAOT, +ASP.NET Core, strings, and vectorization. + +Three shapes clear the bar and sit in [index.md](index.md): the `Func` +middleware delegate, `UseStaticFiles`, and `string.Split` used only to +enumerate. Three more join the Tier 2 table: a per-item `Parallel.For` body, a +`FileStream` captured by a parallel body, and a `readonly` field re-read inside +a loop. + +Four shapes have an installed owner. See +[skipped-decisions.md](skipped-decisions.md). + +Two extensions belong to shipped rules, not to new IDs. E128135 covers +`TensorPrimitives.Sum` only, and a `Min`, `Max`, `Add`, or `Multiply` loop is +the same shape. E128084 covers `List.GetRange` only, and an indexer loop over a +list is the shape that the open `CollectionsMarshal.AsSpan` Tier 2 row guards. + +## Related + +- [catalog.md](catalog.md): the settled rule catalog and the ID map +- [index.md](index.md): the open register +- [skipped-decisions.md](skipped-decisions.md): every declined shape and its reason diff --git a/lode/dotnet/analyzer-candidates/index.md b/lode/dotnet/analyzer-candidates/index.md index a2f751e..9360308 100644 --- a/lode/dotnet/analyzer-candidates/index.md +++ b/lode/dotnet/analyzer-candidates/index.md @@ -1,5 +1,5 @@ # Analyzer Candidates: Open Register -*Updated: 2026-11-17T22:44:32Z* +*Updated: 2026-11-17T23:06:12Z* One register for every open analyzer candidate, whichever repository noticed it. A candidate enters at status `new`, carries a four-dimension score, and leaves @@ -22,19 +22,92 @@ Each row: `Pattern | Source | Score | Status | Notes`. | candidate | Tier 2 shape that clears the bar and waits for a real defect | The four dimensions are frequency (0-2), coverage gap (0-1), expressibility -(0-1), and value (0-1). A total of 3 or more is RECOMMEND. The rubric lives in -[scoring-rubric.md](../../infrastructure/scoring-rubric.md). +(0-1), and value (0-1). A total of 3 or more is RECOMMEND. The dimension +definitions live in the `analyzer-review-miner` agent definition. ## Open Candidates -No open candidate. `ByteSizeType.Is` matches the type by simple name, so a -namespace move does not break the E128080 exemption. +The guide below is the same source that seeded the shipped performance rules. +Every shape it lists that already has an owner stays out of this table. +The declined shapes sit in [skipped-decisions.md](skipped-decisions.md). + +| Pattern | Source | Score | Status | Notes | +| ------- | ------ | ----- | ------ | ----- | +| Inline middleware takes a `Func` next delegate | BlazingFastDotnet skill guide | 4/5 | new | The `Use` overload allocates one closure per request. Detail below. | +| `UseStaticFiles()` in a minimal API app | BlazingFastDotnet skill guide | 4/5 | new | `MapStaticAssets` serves a build-time manifest. Detail below. | +| `string.Split` result only enumerated | BlazingFastDotnet skill guide | 3.5/5 | new | One array and one string per part allocate. Detail below. | + +`ByteSizeType.Is` matches the type by simple name, so a namespace move does not +break the E128080 exemption. The body-read shape shipped as E128227. See [catalog.md](catalog.md). The token-validation flag shape shipped as E128228. See [catalog.md](catalog.md). The JSON enumerator shape closed as skipped, because the enumerator releases no resource. See [skipped-decisions.md](skipped-decisions.md). +### Inline Middleware Next Delegate + +`app.Use(async (ctx, next) => ...)` binds the `Func, Task>` +overload. That overload allocates a `Func` closure on every request. +The `Func` overload passes `next` as a +`RequestDelegate`, so the call allocates nothing. + +```csharp +// Allocates a closure per request. +app.Use(async (context, next) => +{ + await next(); +}); + +// Allocates nothing. +app.Use(async (context, next) => +{ + await next(context); +}); +``` + +Detection: a `Use` call whose lambda declares a second parameter of type +`Func`. The rule reports that lambda. The `ctx` parameter must stay live +up to the `next` call, and the lambda must not reassign it. + +Fix: yes. The rewrite changes the lambda call and leaves the body intact. + +### Static Files Served Through the Runtime Pipeline + +`app.UseStaticFiles()` sends a file through middleware at request time. +`app.MapStaticAssets()` serves a build-time manifest that carries precompressed +variants and ETags. + +Detection: a `UseStaticFiles` call in a project that targets `net9.0` or later. + +Fix: no automatic fix. The call moves into the endpoint mapping section, and a +Razor app also changes how it references the assets. + +### `string.Split` Used Only to Enumerate + +`value.Split(sep)` allocates an array and one string per part. +`MemoryExtensions.Split` yields `Range` values over the existing string. + +```csharp +// Allocates the array and one string per part. +foreach (var part in line.Split(',')) +{ + Handle(part); +} + +// Allocates nothing. +foreach (var range in line.AsSpan().Split(',')) +{ + Handle(line.AsSpan()[range]); +} +``` + +Detection: a `Split` call whose result no code stores. The separator is a +`char` or a constant string. + +Fix: no automatic fix when the body stores a part as a string. The fix applies +when every read is a slice, a comparison, or a numeric parse. + ## Tier 2 Candidates These clear the same bar and wait for a real defect in review. @@ -59,7 +132,10 @@ maintainer chose prevention over the real-defect bar. | `[Flags]` member value that is not a power of two | constant collides with a lower bit | Low | | Dead store to a private field | assignment killed on every path before a read | Medium | | Loop with no exit path | `while (true)` with no exit call | Medium | -| `Base64.*` over `Convert.ToBase64String` or `Convert.FromBase64String` | call to the `Convert` base64 member, waiting on a real defect | Low | +| `Base64.*` over `Convert.ToBase64String`/`FromBase64String` | call to the `Convert` base64 member, waiting on a real defect | Low | +| `Parallel.For` with a per-item body | body holds no loop over a range | Medium | +| `FileStream` captured by a parallel body | shared stream position across reader threads | Medium | +| `readonly` field re-read inside a loop | field read by index, no write inside the loop | Low | ## Skipped Decisions @@ -87,6 +163,7 @@ declined on 2026-11-13 alongside the earlier decisions. - [catalog.md](catalog.md): settled rules, rejected ideas, and the ID map - [skipped-decisions.md](skipped-decisions.md): every declined shape and its reason +- [guidance-reads.md](guidance-reads.md): each read of the two guidance documents - [net11-conversion-sweep.md](net11-conversion-sweep.md): open .NET 11 conversion shapes - [async-sweep.md](async-sweep.md): closed async fire-and-forget sweep - [external-sweep.md](external-sweep.md): closed 2026-11-05 external rule-set sweep diff --git a/lode/dotnet/analyzer-candidates/skipped-decisions.md b/lode/dotnet/analyzer-candidates/skipped-decisions.md index afb81d0..f947c3e 100644 --- a/lode/dotnet/analyzer-candidates/skipped-decisions.md +++ b/lode/dotnet/analyzer-candidates/skipped-decisions.md @@ -1,6 +1,6 @@ # Analyzer Candidates: Skipped Decisions confidence: high -*Updated: 2026-11-17T16:21:02Z* +*Updated: 2026-11-17T23:06:12Z* The settled side of the open register. A skipped row keeps `/analyzer` from reporting the same idea twice. Each decision names the reason and the installed rule or the site count that settled it. The open side lives in [index.md](index.md), and the shipped rules live in [catalog.md](catalog.md). @@ -82,6 +82,25 @@ allocation is the price of the guard those rules buy. **Source**: Tier 2 register triage, 2026-11-14 +## Shapes With an Installed Owner + +The BlazingFastDotnet skill guide lists each shape below. An installed rule +already reports it, and `AnalysisLevel=latest-all` enables that rule in build. + +| Shape | Owner | +| ----- | ----- | +| A lambda that captures an outer local where a `static` lambda takes the state | IDE0320, "Make anonymous function static" | +| `lock` on a plain `object` field instead of `System.Threading.Lock` | IDE0330, "Use `System.Threading.Lock`" | +| `response.Headers["Content-Type"]` instead of the typed property | The ASP.NET Core analyzer titled "Use IHeaderDictionary properties instead of indexer" | +| A `RequestDelegate` that returns `Task` | The ASP.NET Core analyzer titled "Do not return a value from RequestDelegate" | + +**Evidence**: the installed SDK style configuration sets both IDE rules to +warning. Both ASP.NET Core analyzer titles come from +`Microsoft.AspNetCore.App.Analyzers.dll` in the installed ref pack. Checked on +2026-11-17. + +**Source**: BlazingFastDotnet skill guide, read 2026-11-17 + ## Declined from the .NET 11 Band The net11-upgrade close on 2026-11-13 checked each shape below and declined it. The conversion shapes that clear the bar live in [net11-conversion-sweep.md](net11-conversion-sweep.md). diff --git a/lode/lode-map.md b/lode/lode-map.md index a4b950a..3881d95 100644 --- a/lode/lode-map.md +++ b/lode/lode-map.md @@ -1,5 +1,5 @@ # Lode Map -*Updated: 2026-11-13T22:43:20Z* +*Updated: 2026-11-17T23:06:12Z* ## Generated Docs @@ -41,8 +41,9 @@ ### dotnet/analyzer-candidates/ - [index.md](dotnet/analyzer-candidates/index.md): Open register for every analyzer candidate, with schema, scores, and the capture ledger -- [catalog.md](dotnet/analyzer-candidates/catalog.md): Settled rules, rejected ideas, guidance-document rule maps, and the ID map +- [catalog.md](dotnet/analyzer-candidates/catalog.md): Settled rules, rejected ideas, and the ID map - [skipped-decisions.md](dotnet/analyzer-candidates/skipped-decisions.md): Every declined shape with its reason and site count +- [guidance-reads.md](dotnet/analyzer-candidates/guidance-reads.md): Each read of the two guidance documents, the document-only rows, and the unshipped idea - [net11-conversion-sweep.md](dotnet/analyzer-candidates/net11-conversion-sweep.md): Open .NET 11 conversion shapes with call-site evidence - [external-sweep.md](dotnet/analyzer-candidates/external-sweep.md): Closed 2026-11-05 external rule-set sweep, which leaves no candidate open - [performance-sweep.md](dotnet/analyzer-candidates/performance-sweep.md): Closed twenty-practice performance sweep that shipped E128203 to E128217, with probe evidence diff --git a/plans/roadmap.md b/plans/roadmap.md index 88075ee..1414f3f 100644 --- a/plans/roadmap.md +++ b/plans/roadmap.md @@ -1,4 +1,183 @@ # Roadmap -*Updated: 2026-11-13T12:24:13Z* +*Updated: 2026-11-17T23:07:20Z* Unplanned work awaiting a plan. + +Each entry carries the shape, the register score, and the code fix. The open +register lives in [index.md](../lode/dotnet/analyzer-candidates/index.md), and +the read that found these shapes lives in +[guidance-reads.md](../lode/dotnet/analyzer-candidates/guidance-reads.md). + +## Active + +### Middleware Next Delegate Closure +- **Added:** 2026-11-17T23:07:20Z +- **Register:** 4/5, `new`. Candidate for E128229. +- **Shape:** a `Use` lambda that takes a `Func` next delegate. That overload allocates one closure per request. + +```csharp +// Report +app.Use(async (HttpContext context, Func next) => +{ + await next(); +}); + +// Fix +app.Use(async (HttpContext context, RequestDelegate next) => +{ + await next(context); +}); +``` + +- **Fix scope:** rewrite the parameter type and the call. Report only where `context` stays live and is never reassigned. The `RequestDelegate` overload exists on .NET 7 and later. +- **Trigger:** Plan this entry first. The shape is clear and the fix is a local rewrite. + +### Static Files Mapped at Build Time +- **Added:** 2026-11-17T23:07:20Z +- **Register:** 4/5, `new`. Candidate for E128230. +- **Shape:** `UseStaticFiles` sends a file through middleware at request time. `MapStaticAssets` serves a build-time manifest with precompressed variants and ETags. + +```csharp +// Report +app.UseStaticFiles(); + +// Fix +app.MapStaticAssets(); +``` + +- **Fix scope:** report a `UseStaticFiles` call in a project that targets `net9.0` or later. No automatic fix, because the call moves into the endpoint mapping section. A Razor app also changes how it references the assets. +- **Trigger:** Plan after the middleware rule, because the same project shape and TFM check apply. + +### Split Result Used Only to Enumerate +- **Added:** 2026-11-17T23:07:20Z +- **Register:** 3.5/5, `new`. Candidate for E128231. +- **Shape:** `string.Split` allocates one array and one string per part. `MemoryExtensions.Split` yields `Range` values over the source string. + +```csharp +// Report +foreach (string part in line.Split(',')) +{ + total += int.Parse(part); +} + +// Fix +foreach (Range range in line.AsSpan().Split(',')) +{ + total += int.Parse(line.AsSpan()[range]); +} +``` + +- **Fix scope:** report only where no code stores the array. The separator is a `char` or a constant string. Rewrite only where every read is a slice, a comparison, or a numeric parse. Report without a fix when the body stores a part as a string. +- **Trigger:** Plan after the two ASP.NET Core rules. + +### TensorPrimitives Min and Max Loops +- **Added:** 2026-11-17T23:07:20Z +- **Register:** extension of E128135, no new ID. See [catalog.md](../lode/dotnet/analyzer-candidates/catalog.md). +- **Shape:** E128135 covers `TensorPrimitives.Sum` only. A loop that computes `Min`, `Max`, `Add`, or `Multiply` over one span is the same shape. + +```csharp +// Report +double max = double.MinValue; +foreach (double value in values) +{ + if (value > max) + { + max = value; + } +} + +// Fix +double max = TensorPrimitives.Max(values); +``` + +- **Fix scope:** reuse the E128135 detection and code fix. Add the four members to the same member table. Report only a single-span loop with no other side effect. +- **Trigger:** Plan with E128135. The extension touches one analyzer and one code fix. + +### List Indexer Loop to a Span +- **Added:** 2026-11-17T23:07:20Z +- **Register:** extension of E128084, no new ID. Guards the open `CollectionsMarshal.AsSpan` Tier 2 row. +- **Shape:** E128084 covers `List.GetRange` only. A `for` loop that indexes a `List` repeats a bounds check per element. + +```csharp +// Report +int total = 0; +for (int i = 0; i < items.Count; i++) +{ + total += items[i].Length; +} + +// Fix +int total = 0; +foreach (string item in CollectionsMarshal.AsSpan(items)) +{ + total += item.Length; +} +``` + +- **Fix scope:** suppress the report when the loop mutates the list. The span reads stale memory after a mutation, so the fix is wrong for that shape. +- **Trigger:** Plan with E128084. The fix reuses the existing `List.GetRange` rewrite. + +## Waiting + +### Parallel For Over a Per-Item Body +- **Added:** 2026-11-17T23:07:20Z +- **Register:** Tier 2, waits on a real defect. +- **Shape:** `Parallel.For` runs one delegate per item. A range partition runs one delegate per chunk. + +```csharp +// Report +Parallel.For(0, items.Count, i => Work(items[i])); + +// Fix +Parallel.ForEach(Partitioner.Create(0, items.Count), range => +{ + for (int i = range.Item1; i < range.Item2; i++) + { + Work(items[i]); + } +}); +``` + +- **Fix scope:** report a body with no loop. Suppress a body that awaits, because the range overload takes a synchronous delegate. +- **Trigger:** A real defect in review, or two occurrences in one commit. + +### FileStream Shared Across Reader Threads +- **Added:** 2026-11-17T23:07:20Z +- **Register:** Tier 2, waits on a real defect. +- **Shape:** one `FileStream` position shared by parallel readers. `File.OpenHandle` plus `RandomAccess.Read` reads at an explicit offset. + +```csharp +// Report +using FileStream stream = File.OpenRead(path); +Parallel.ForEach(offsets, offset => ReadAt(stream, offset)); + +// Fix +using SafeFileHandle handle = File.OpenHandle(path, FileMode.Open, FileAccess.Read); +Parallel.ForEach(offsets, offset => ReadAt(handle, offset)); +``` + +- **Fix scope:** report a `FileStream` local captured by a parallel body. The `ReadAt` helper changes to take a `SafeFileHandle` and an offset. +- **Trigger:** A real defect in review. The fix crosses a helper boundary, so it needs a site to prove. + +### Readonly Field Hoisted Out of a Loop +- **Added:** 2026-11-17T23:07:20Z +- **Register:** Tier 2, waits on a real defect. +- **Shape:** a loop reads the same `readonly` field by index. A local copy lets the JIT drop the repeated load and the bounds check. + +```csharp +// Report +for (int i = 0; i < _items.Length; i++) +{ + total += _items[i]; +} + +// Fix +int[] items = _items; +for (int i = 0; i < items.Length; i++) +{ + total += items[i]; +} +``` + +- **Fix scope:** report a `readonly` field only. A mutable field can change under a concurrent writer, and the local copy would hide the change. +- **Trigger:** A real defect in review, or a measured gain on a hot path.