Use roslyn-query skill

handbook-dotnet

Query C# codebases structurally using Roslyn AST analysis, executed as throwaway scripts via dotnet run file.cs.

Grep finds text; Roslyn finds code. This skill generates single-file analysis scripts that answer questions text search cannot — who calls this method, which types implement this interface, where does untrusted data flow, which layers violate the architecture.

When to Use This Skill

Use the roslyn-query skill when you want to:

• Trace data flow from sources to sinks (taint analysis)
• Audit every assignment to a specific property
• Find all callers of a method, implementations of an interface, or overrides
• Detect pattern violations — empty catches, missing sanitizers, magic numbers
• Validate architecture layering
• Run an ad-hoc structural query over a codebase

Analysis Tiers

Pick the cheapest tier that answers the question.

Tier	Mechanism	Good for
1 — Syntax-only	CSharpSyntaxTree.ParseText(), no compilation	Assignment audits, empty catches, naming, complexity, method size
2 — Semantic	MSBuildWorkspace, loads the project	Callers, implementations, overrides, type graphs, data flow

Tier 1 packages:

#:package Microsoft.CodeAnalysis.CSharp@4.*

Tier 2 adds:

#:package Microsoft.CodeAnalysis.CSharp.Workspaces@4.*
#:package Microsoft.CodeAnalysis.Workspaces.MSBuild@4.*
#:package Microsoft.Build.Locator@1.*
#:property DisableMSBuildAssemblyCopyCheck=true

warning

Roslyn 4.x MSBuildWorkspace does not support .slnx. Open a .csproj with OpenProjectAsync instead — transitive project references load automatically.

Script Conventions

• Target path comes from args[0], defaulting to the current directory
• Output is file:line plus a description and context, using Path.GetRelativePath()
• Exit code 0 means clean, 1 means findings

dotnet run scripts/my-analysis.cs -- <target-path>

Skill Specification

---
name: roslyn-query
description: Query .NET/C# codebases using Roslyn AST analysis via dotnet run file. Use for tracing data flow, auditing API usage, finding pattern violations, or ad-hoc codebase queries.
argument-hint: "[analysis description or query type]"
---

# Roslyn Query

Query .NET/C# codebases using Roslyn AST analysis scripts executed via `dotnet run file.cs`.

Before generating scripts, load the `handbook-dotnet:dotnet-run-file` skill for execution conventions and directive syntax.

## When to Use

- Trace data flow from sources to sinks (taint analysis)
- Audit all assignments to specific properties
- Find all callers of a method
- Find all implementations of an interface
- Detect pattern violations (empty catches, missing sanitizers, etc.)
- Architecture validation (layer violations)
- Ad-hoc codebase structural queries

## Analysis Tiers

### Tier 1: Syntax-Only (fast, no compilation)

Uses `CSharpSyntaxTree.ParseText()` — parses files individually, no solution loading.

Best for:
- Property assignment audits (`x.Content = ...`)
- Empty catch block detection
- Naming convention checks
- Cyclomatic complexity
- Magic number/string detection
- Method size metrics
- Pattern matching on code structure

### Tier 2: Semantic (needs project/solution)

Uses `MSBuildWorkspace` — loads project, resolves types, enables cross-file analysis.

Best for:
- Find all callers of a method (`SymbolFinder.FindCallersAsync`)
- Find interface implementations (`SymbolFinder.FindImplementationsAsync`)
- Find method overrides (`SymbolFinder.FindOverridesAsync`)
- Type dependency graphs
- Full data flow analysis (`SemanticModel.AnalyzeDataFlow`)

## Instructions

### Step 1: Determine analysis type

Based on the user's request, choose the appropriate template from `references/templates.md`. If no template fits, compose a custom script using the patterns documented there.

### Step 2: Generate the script

Create a `.cs` file in a `scripts/` directory (or temp location) using `dotnet run file.cs` format with `#:package` directives.

For syntax-only analysis:
```csharp
#:package Microsoft.CodeAnalysis.CSharp@4.*
```

For semantic analysis, additionally:
```csharp
#:package Microsoft.CodeAnalysis.CSharp.Workspaces@4.*
#:package Microsoft.CodeAnalysis.Workspaces.MSBuild@4.*
#:package Microsoft.Build.Locator@1.*
#:property DisableMSBuildAssemblyCopyCheck=true
```

> **Note:** `DisableMSBuildAssemblyCopyCheck=true` suppresses the MSBL001 build error that requires `ExcludeAssets="runtime"` on MSBuild packages — an attribute `#:package` directives can't express. Safe for throwaway analysis scripts.
>
> **`.slnx` not supported:** Roslyn 4.x `MSBuildWorkspace` only supports `.sln`, not `.slnx`. Use `OpenProjectAsync` with a `.csproj` instead — transitive project references are loaded automatically.

### Step 3: Script conventions

- Accept target directory/path via `args[0]`, default to `Directory.GetCurrentDirectory()`
- Use `Path.GetRelativePath()` for output paths
- Print structured output: file:line, description, context
- Use color: green for safe, yellow for warnings, red for violations
- Exit code 0 = clean, 1 = findings

### Step 4: Execute

```bash
dotnet run scripts/my-analysis.cs -- <target-path>
```

### Step 5: Interpret results

Analyze the output. For taint analysis, categorize findings:
- **Safe** — trusted source (code-generated, AI output, literal null)
- **Already sanitized** — sanitizer call deeper in call chain (syntax-only false positive)
- **Needs investigation** — external input, user-authored content
- **Violation** — clear miss that should be fixed

## Key Roslyn APIs Quick Reference

Load `references/roslyn-api.md` for detailed API reference with code examples.

## Templates

Load `references/templates.md` for ready-to-use analysis script templates.

References

The skill ships two bundled references it loads on demand:

• references/roslyn-api.md — key Roslyn APIs with code examples
• references/templates.md — ready-to-use analysis script templates

Related

• dotnet-run-file — execution conventions and directive syntax for the generated scripts
• dotnet-analyzers — fix diagnostics that built-in analyzers already detect