Adding Calor to Existing Projects

This guide walks you through adding Calor to an existing C# project, from enabling Calor to building with mixed Calor/C# code.

Overview

Adding Calor to an existing project is a gradual process:

  1. Initialize - Enable Calor with MSBuild integration
  2. Analyze - Find files that benefit most from Calor's features
  3. Write/Convert - Create new files in Calor, convert high-scoring C# files
  4. Build - Calor compiles automatically with your project

You don't need to convert everything at once. Calor and C# coexist seamlessly.

Step 1: Enable Calor in Your Project

Enable Calor with MSBuild integration:

Bash
# Initialize Calor in your project
calor init

# Or specify a specific project file
calor init --project MyApp.csproj

Your .csproj is updated with MSBuild targets that compile .calr files automatically during dotnet build.

Step 2: Analyze Your Codebase

Use calor analyze to find C# files that would benefit most from Calor:

Bash
# Analyze your source directory
calor analyze ./src

# Show top 10 candidates with detailed scores
calor analyze ./src --top 10 --verbose

Understanding the Output

Plain Text
=== Calor Migration Analysis ===

Analyzed: 42 files
Average Score: 34.2/100

Top 10 Files for Migration:
--------------------------------------------------------------------------------
 82/100 [Critical]  src/Services/PaymentProcessor.cs
 78/100 [Critical]  src/Services/OrderService.cs
 65/100 [High]      src/Repositories/UserRepository.cs
PriorityScoreRecommendation
Critical76-100Convert to Calor - high benefit
High51-75Good conversion candidate
Medium26-50Optional - some benefit
Low0-25Keep in C# - minimal benefit

Step 3: Add Your First Calor File

Create a new .calr file alongside your existing code:

Plain Text
§M{m001:Calculator}

§F{f001:Add:pub}
  §I{i32:a}
  §I{i32:b}
  §O{i32}
  §R (+ a b)
§/F{f001}

§/M{m001}

Step 4: Build and Verify

Bash
# Build your project - Calor compiles automatically
dotnet build

The build process:

  1. Finds all .calr files in your project
  2. Compiles each to .g.cs in the obj/calor/ directory
  3. Includes generated C# in the normal compilation

Step 5: Convert High-Scoring C# Files

Based on your analysis results, convert files that score High or Critical:

Bash
# Convert a single file
calor convert src/Services/PaymentProcessor.cs

# With benchmark comparison
calor convert src/Services/PaymentProcessor.cs --benchmark

For bulk conversion:

Bash
calor migrate ./src --dry-run  # Preview first
calor migrate ./src            # Execute

Optional: Enable Claude Code Integration

For AI-assisted Calor development:

Bash
calor init --ai claude

This adds:

  • /calor and /calor-convert skills
  • CLAUDE.md with guidelines instructing Claude to write new code in Calor and analyze C# files before modifying them

Using Claude Code

Write new Calor code:

Plain Text
/calor

Write a function that validates email addresses with:
- Precondition: input is not null or empty
- Postcondition: returns true only for valid emails

Convert existing C# to Calor:

Plain Text
/calor-convert src/Services/PaymentProcessor.cs

Best Practices

What to Convert First

  1. High-scoring files from calor analyze
  2. Files with complex validation - benefit from contracts
  3. Files with error handling - benefit from Result\<T,E\>
  4. Files with side effects - benefit from effect declarations

What to Keep in C#

  • Simple DTOs and record types
  • Auto-generated code (EF migrations, gRPC stubs)
  • Code using features Calor doesn't support yet

Next Steps