/code-analysis

name: code-analysis
description: "Use the free built-in .NET SDK analyzers and analysis levels with gradual Roslyn warning promotion. USE FOR: the repo wants first-party .NET analyzers; CI should fail on analyzer warnings; the team needs AnalysisLevel or AnalysisMode guidance. DO NOT USE FOR: third-party analyzer selection by itself; formatting-only work. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENTS.md` commands first."

.NET Code Analysis

Trigger On

• the repo wants first-party .NET analyzers
• CI should fail on analyzer warnings
• the team needs `AnalysisLevel` or `AnalysisMode` guidance
• the repo needs a gradual Roslyn warning promotion strategy

Do Not Use For

• third-party analyzer selection by itself
• formatting-only work

Inputs

• the nearest `AGENTS.md`
• project files or `Directory.Build.props`
• current analyzer severity policy

Hard Rules for AI Agents

Non-negotiable. Violating these undermines the user's explicit intent.

1. Never disable or remove `TreatWarningsAsErrors` or `WarningsAsErrors` if the project has set them. Do not comment them out, set to `false`, wrap in a condition, or add `<TreatWarningsAsErrors>false</TreatWarningsAsErrors>` to make the build pass. 2. Never add `<NoWarn>` or `#pragma warning disable` for warnings the user chose to treat as errors, unless the user explicitly approves the suppression. 3. Never silently downgrade severity in `.editorconfig` (e.g. `error` to `warning` or `none`) to make a build succeed. 4. If warnings-as-errors breaks the build — fix the code. If the fix is too large, ask the user whether to defer that warning ID. 5. If warning volume is too large to fix in one pass — report count and categories to the user and ask which to tackle first. Do not unilaterally disable the policy.

Workflow

flowchart TD
    A[Start] --> B{New or legacy project?}
    B -->|New| C[TreatWarningsAsErrors=true immediately]
    B -->|Legacy| D[dotnet build, count warnings by ID]
    D --> E{"< 30 warnings?"}
    E -->|Yes| F[Fix all, then enable TreatWarningsAsErrors]
    E -->|No| G[Report counts to user, ask which batch first]
    G --> H[Add selected IDs to WarningsAsErrors]
    H --> I[Fix that batch, verify build]
    I --> J{More batches?}
    J -->|Yes| G
    J -->|No| F
    C --> K[Set AnalysisLevel latest-recommended]
    F --> K
    K --> L[Promote security CA3xxx/CA5xxx to error in .editorconfig]
    L --> M[Validate: build + CI green]

1. Start with SDK analyzers before third-party packages. 2. Detect project maturity: new or existing/legacy. 3. Enable `EnableNETAnalyzers`, `AnalysisLevel`, `AnalysisMode` in `Directory.Build.props`. 4. Apply the right warning promotion strategy (see below). 5. Per-rule severity goes in repo-root `.editorconfig`. 6. `dotnet build` is the analyzer gate in CI.

Warning Promotion Strategy

New Projects

Set these in `Directory.Build.props` immediately:

• `TreatWarningsAsErrors` = true
• `AnalysisLevel` = latest-recommended
• Security category = error in `.editorconfig`

Fix all warnings before merging.

Legacy Projects — Gradual Promotion

Blanket `TreatWarningsAsErrors` on a legacy codebase produces hundreds/thousands of errors. An agent cannot fix them all at once — context floods, fix quality drops. Promote in batches.

Phase 1: Trivial Hygiene (start here)

Mechanical fixes, lowest effort:

• CS8019 — unnecessary using directive (remove it)
• CS0219 — variable assigned but never used (remove it)
• CS0168 — variable declared but never used (remove it)
• CS1591 — missing XML comment for public member (add comment or disable for internal code)
• CS0612 — obsolete member used, no message (replace with non-obsolete API)
• CS0618 — obsolete member used, with message (follow migration guidance)

Add to `WarningsAsErrors`: `CS8019;CS0219;CS0168`. Fix all, then Phase 2.

Phase 2: Code Quality (ask user which categories)

• CA2000 — dispose objects before losing scope (Reliability)
• CA1062 — validate public method arguments (Design)
• CA1822 — mark members as static (Performance)
• CA1860 — avoid Enumerable.Any() for length check (Performance)
• CA1861 — avoid constant arrays as arguments (Performance)
• CA2007 — consider calling ConfigureAwait (Reliability)
• CS8600–CS8610 — nullable reference type warnings (Nullability)

Ask: "Which categories next — Nullability, Performance, or Reliability?" Add selected IDs to `WarningsAsErrors`, fix, repeat.

Phase 3: Security (always promote early)

Set in `.editorconfig` regardless of project maturity:

[*.cs]
dotnet_analyzer_diagnostic.category-Security.severity = error

Covers CA3001 (SQL injection), CA3002 (XSS), CA3003 (path injection), CA3075 (insecure DTD), CA5350/CA5351 (weak crypto), CA5394 (insecure randomness).

Phase 4: Full Coverage

Once all batches pass, transition to:

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<WarningsNotAsErrors>CA1707</WarningsNotAsErrors> <!-- explicit exceptions only -->

Interaction Protocol (legacy codebases)

1. Run `dotnet build`, count warnings by ID. 2. Report summary: "Found 47 CS8019, 23 CA1822, 12 CA2000, 8 CS8600." 3. Ask which batch to tackle. Recommend starting with Phase 1. 4. Fix selected batch, verify build. 5. Add those IDs to `WarningsAsErrors`. 6. Report back, ask about next batch.

Never skip the ask step. The user decides the pace.

Bootstrap When Missing

1. Detect current state:

• `dotnet --info`
• `rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors|WarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .`
• `dotnet build SOLUTION_OR_PROJECT 2>&1` — count warnings by ID

2. Classify: new (few/zero warnings) vs legacy (many warnings). 3. Enable `EnableNETAnalyzers`, `AnalysisLevel`, `Analy