PureSharp

English | 日本語 | 简体中文 | 繁體中文 | Esperanto | Klingon | Español | Français | Deutsch | 한국어

PureSharp is a toolset designed to strongly support "referential transparency" and "immutability" in C#, bringing the safety of functional programming to C#. It leverages Roslyn analyzers to enforce robust, bug-resistant code writing at the compilation level.

Core Concepts

1. Purity Enforcement: Explicitly declare logic without side effects and verify it mechanically.
2. Immutability Introduction: Achieve "non-reassignable local variables," a feature lacking in the language specification, through intuitive naming conventions.
3. Safe Control Flow: Provide pipeline-style conditional branching to prevent runtime exceptions and oversights.

Key Features

1. PureSharp.Core

Provides fundamental attributes and utilities.

• [PureMethod] attribute: Declares a method as "pure" (referentially transparent).
• Fluent.If: A fluent interface that allows if-else statements to be written as expressions.

2. PureSharp.Analyzers (Roslyn Analyzers)

Monitors code writing in real-time and reports rule violations.

Referential Transparency Verification (RTxxxx)

An Error is reported when a method annotated with [PureMethod] performs the following operations:

• Accessing static, mutable (non-readonly) fields.
• Calling non-pure methods (methods without [PureMethod]).
• I/O operations (access to Console, File, Network, etc.).

Local Variable Immutability Enforcement (LVPxxxx)

Achieves immutability using a naming convention that starts with an underscore (_).

• Mandatory Immutability: Prohibits reassignment to local variables starting with _ (Error).
• Initialization Enforcement: Variables starting with _ must be initialized at the time of declaration (Error).
• Naming Suggestion: Suggests adding an underscore (_) to variables that have never been reassigned (Warning).

FluentIf Termination Check (FIFxxxx)

• Verifies that chains starting with Fluent.If are correctly terminated with .Else(). Failure to terminate will result in a compile error.

---

Quick Start

1. Writing Referentially Transparent Methods

using PureSharp.Core;

public class Calculator
{
    private static int _globalCache; // Mutable static field

    [PureMethod]
    public int Add(int a, int b)
    {
        // OK: Calculation only
        return a + b; 
        
        // NG: Accessing static field causes RT0001 error
        // _globalCache = a + b; 
        
        // NG: I/O operations cause RT0003 error
        // Console.WriteLine(a); 
    }
}

2. Utilizing Immutable Local Variables

public void Process()
{
    int _result = Calculate(); // Declared as an immutable variable
    
    // NG: Attempting to reassign causes LVP0001 error
    // _result = 10; 
    
    int count = 0; // Regular variable
    // Suggestion: If not reassigned, a warning to change to "_count" (LVP0003)
}

3. Safe Conditional Branching (FluentIf)

int status = Fluent.If(score >= 80, () => 1)
                   .ElseIf(score >= 60, () => 2)
                   .Else(0); // Forgetting .Else() causes FIF0001 error

---

Project Structure

• PureSharp.Core: Provides core attributes and runtime libraries (.NET 10.0 / netstandard2.0).
• PureSharp.Analyzers: The main Roslyn analyzer (netstandard2.0).
• PureSharp.Analyzers.Tests: Unit tests to verify analyzer behavior (xUnit).

---

Diagnostic Configuration

PureSharp uses Roslyn's standard .editorconfig mechanism for configuring diagnostic severity. You can control how each diagnostic is reported (error, warning, or suppressed) using the dotnet_diagnostic.<ID>.severity setting.

Supported Diagnostics

Diagnostic ID	Category	Title	Default Severity
RT0001	Purity	Static field access in [PureMethod]	Error
RT0002	Purity	Non-pure method call in [PureMethod]	Error
RT0003	Purity	I/O operation in [PureMethod]	Error
LVP0001	Purity	Reassignment to immutable local variable prohibited	Error
LVP0002	Purity	Mandatory initialization of immutable local variable	Error
LVP0003	Naming	Suggestion to apply naming convention for immutable local variable	Warning
FIF0001	FluentIf	FluentIf chain termination check	Error

The complete diagnostic contract — full message text, target conditions, the v1.0 public contract surface, ID naming and category policy, and the compatibility rules for adding or changing a diagnostic — is defined in docs/DIAGNOSTICS.md, which is the single source of truth.

Configuration Example

Create (or update) .editorconfig in your project root:

# .editorconfig

root = true

[*.cs]
# Configure PureSharp diagnostic severities
# Valid values: none, silent, suggestion, warning, error

# Referential Transparency (RT) - default: error
dotnet_diagnostic.RT0001.severity = error
dotnet_diagnostic.RT0002.severity = error
dotnet_diagnostic.RT0003.severity = error

# Local Variable Purity (LVP) - default: error/warning
dotnet_diagnostic.LVP0001.severity = error
dotnet_diagnostic.LVP0002.severity = error
dotnet_diagnostic.LVP0003.severity = warning

# FluentIf (FIF) - default: error
dotnet_diagnostic.FIF0001.severity = error

Severity Levels

• error: Build fails if the diagnostic is triggered
• warning: Displays a warning but build succeeds
• suggestion: Minor suggestion (often used for code quality hints)
• silent: Suppresses the diagnostic from output but analysis still runs
• none: Completely suppresses the diagnostic

Example: Suppressing a Diagnostic

[*.cs]
# Suppress LVP0003 (naming suggestions)
dotnet_diagnostic.LVP0003.severity = none

---

Motivation for Development

C# is a very powerful language, but in large-scale development or complex logic, debugging can become difficult due to unintended side effects or variable reuse. PureSharp was born to provide developers with "freedom (from bugs)" in the form of "constraints."

---

License

This project is released under the MIT License.