Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 5 additions & 64 deletions lode/dotnet/analyzer-candidates/catalog.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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<T>` 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<byte>` property and every other element type as
`ImmutableArray<T>`.

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

Expand Down
101 changes: 101 additions & 0 deletions lode/dotnet/analyzer-candidates/guidance-reads.md
Original file line number Diff line number Diff line change
@@ -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<T>` 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<byte>` property and every other element type as
`ImmutableArray<T>`.

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<Task>`
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
89 changes: 83 additions & 6 deletions lode/dotnet/analyzer-candidates/index.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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<Task>` 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<HttpContext, Func<Task>, Task>`
overload. That overload allocates a `Func<Task>` closure on every request.
The `Func<HttpContext, RequestDelegate, Task>` 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<Task>`. 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.
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down
21 changes: 20 additions & 1 deletion lode/dotnet/analyzer-candidates/skipped-decisions.md
Original file line number Diff line number Diff line change
@@ -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).

Expand Down Expand Up @@ -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<T>` | 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).
Expand Down
Loading