CsEffect.Analyzer 0.15.0

CsEffect.Analyzer

A Roslyn analyzer for tracking and propagating effect annotations in C# codebases.

Overview

CsEffect.Analyzer is the core component of the CsEffect system that provides compile-time analysis to ensure proper effect annotation propagation throughout your codebase. It helps you document and track side effects in your APIs by requiring explicit effect annotations on methods that perform or call effectful operations.

What it does

• Tracks effect propagation: Analyzes method calls to ensure that effectful operations are properly annotated
• Validates effect hierarchies: Supports effect inheritance where more general effects can satisfy more specific ones
• Interface validation: Ensures interface implementations don't introduce effects not declared on the interface
• Configurable severity: Effect authors can choose between warnings and errors for violations

Key Features

Effect Base Classes

• EffectAttribute - Base class for all effect attributes
• EffectTargetsAttribute - Specifies which types trigger the effect requirement
• EffectSeverityAttribute - Controls whether violations are warnings or errors

Diagnostics

• CSE001: Effect usage requires annotation - triggered when calling effectful APIs without proper attributes
• CSE002: Interface implementation effect mismatch - triggered when implementations add effects not on interfaces

Special Handling

• Top-level statements: Automatically excluded from analysis since they cannot be annotated
• Implicitly declared methods: Compiler-generated methods are ignored

Usage

Reference this package as an analyzer in your project:

<ItemGroup>
  <PackageReference Include="CsEffect.Analyzer" Version="0.2.0" OutputItemType="Analyzer" />
</ItemGroup>

Or for project references:

<ItemGroup>
  <ProjectReference Include="path\to\CsEffect.Analyzer.csproj" OutputItemType="Analyzer" />
</ItemGroup>

Creating Custom Effects

1. Define your effect attribute:

   [EffectTargets(typeof(MyEffectfulApi))]
   [EffectSeverity(EffectViolationLevel.Error)] // Optional: make violations errors
   public sealed class MyEffectAttribute : EffectAttribute
   {
   }
   

2. Annotate your effectful methods:

   [MyEffect]
   public void DoSomethingEffectful()
   {
       MyEffectfulApi.DoSomething();
   }
   

3. The analyzer will require callers to be annotated:

   [MyEffect] // Required by analyzer
   public void Caller()
   {
       DoSomethingEffectful();
   }
   

Effect Hierarchies

Effects can inherit from each other to create hierarchies:

public class IoEffectAttribute : EffectAttribute { } // General I/O

[EffectTargets(typeof(Console))]
public sealed class ConsoleEffectAttribute : IoEffectAttribute { } // Specific console I/O

Methods annotated with [IoEffect] can call methods that require [ConsoleEffect], but not vice versa.

License

MIT