assess

Score C# files for Calor migration potential.

Bash

calor assess <path> [options]

Overview

The assess command scans a C# codebase and scores each file based on how much it would benefit from Calor's features. calor analyze remains an alias for backward compatibility.

Use this command to:

Prioritize migration efforts - Focus on files that benefit most from Calor's contracts and effects
Understand your codebase - See which patterns are most common across your project
Generate reports - Export analysis in JSON or SARIF format for tooling integration

Quick Start

Bash

# Analyze current directory
calor assess .

# Analyze with detailed breakdown
calor assess ./src --verbose

# Export as JSON for processing
calor assess ./src --format json --output analysis.json

Scoring Dimensions

Each file is scored across eight dimensions that correspond to Calor language features:

Dimension	Weight	What It Detects	Calor Feature
ContractPotential	18%	Argument validation, `ArgumentException` throws, range checks	`§Q`/`§S` contracts
NullSafetyPotential	18%	Nullable types, `?.`, `??`, null checks	`Option\<T\>`
ErrorHandlingPotential	18%	Try/catch blocks, throw statements	`Result\<T,E\>`
EffectPotential	13%	File I/O, network calls, database access, console	`§E` effect declarations
ApiComplexityPotential	13%	Undocumented public APIs	Calor metadata requirements
PatternMatchPotential	8%	Switch statements/expressions	Exhaustiveness checking
AsyncPotential	6%	`async`, `await`, `Task<T>`, and cancellation	Calor async model
LinqPotential	6%	LINQ methods and query syntax	Calor collection patterns

The total score (0-100) is the weighted sum of individual dimension scores.

Priority Bands

Files are categorized into priority bands based on their total score:

Priority	Score Range	Meaning
Critical	76-100	Excellent migration candidate - high density of patterns that Calor improves
High	51-75	Good migration candidate - significant benefit from Calor features
Medium	26-50	Some benefit from migration - moderate pattern density
Low	0-25	Minimal benefit - few patterns that Calor addresses

Command Options

Option	Short	Default	Description
`--format`	`-f`	`text`	Output format: `text`, `json`, or `sarif`
`--output`	`-o`	stdout	Write output to file instead of stdout
`--threshold`	`-t`	`0`	Minimum score to include (0-100)
`--top`	`-n`	`20`	Number of top files to show
`--verbose`	`-v`	`false`	Show detailed per-file breakdown

Output Formats

Text (Default)

Human-readable summary with ASCII bar charts:

Plain Text

=== Calor Migration Analysis ===

Analyzed: 42 files
Skipped: 8 files (generated/errors)
Average Score: 34.2/100

Priority Breakdown:
  Critical (76-100): 2 files
  High (51-75):      8 files
  Medium (26-50):    18 files
  Low (0-25):        14 files

Average Scores by Dimension:
  ErrorHandlingPotential   45.2 |#########
  ContractPotential        38.1 |#######
  NullSafetyPotential      35.6 |#######
  EffectPotential          28.4 |#####
  AsyncPotential           24.5 |####
  ApiComplexityPotential   22.1 |####
  LinqPotential            15.8 |###
  PatternMatchPotential    12.3 |##

Top 20 Files for Migration:
--------------------------------------------------------------------------------
 82/100 [Critical]  src/Services/PaymentProcessor.cs
 78/100 [Critical]  src/Services/OrderService.cs
 65/100 [High]      src/Repositories/UserRepository.cs
...

With --verbose, each file shows dimension breakdown:

Plain Text

82/100 [Critical]  src/Services/PaymentProcessor.cs
         ErrorHandlingPotential: 95 (12 patterns)
         ContractPotential: 88 (8 patterns)
         EffectPotential: 75 (6 patterns)
         NullSafetyPotential: 62 (15 patterns)

JSON

Machine-readable format for processing:

Bash

calor assess ./src --format json --output analysis.json

JSON

{
  "version": "2.0",
  "command": "assess",
  "diagnostics": [],
  "summary": { "total": 0, "errors": 0, "warnings": 0, "info": 0 },
  "data": {
    "rootPath": "/path/to/src",
    "summary": { "totalFiles": 42, "averageScore": 34.2 },
    "files": [
      {
        "path": "Services/PaymentProcessor.cs",
        "score": 82.3,
        "priority": "critical"
      }
    ]
  }
}

The assessment payload lives under data; diagnostics and counts use the shared schema 2.0 envelope.

SARIF

SARIF (Static Analysis Results Interchange Format) for IDE and CI/CD integration:

Bash

calor assess ./src --format sarif --output analysis.sarif

SARIF output integrates with:

VS Code - SARIF Viewer extension
GitHub - Code scanning alerts
Azure DevOps - Build results
Other tools - Any SARIF-compatible viewer

Each scoring dimension becomes a SARIF rule (e.g., Calor-ContractPotential), and findings appear as diagnostics in your IDE.

Exit Codes

Code	Meaning
`0`	Success - no high-priority files found
`1`	Success - high or critical priority files found
`2`	Error - invalid arguments, directory not found, etc.

Use exit code 1 in CI/CD to flag codebases with high migration potential:

Bash

# Fail CI if high-priority migration candidates exist
calor assess ./src --threshold 51
if [ $? -eq 1 ]; then
  echo "High-priority Calor migration candidates found"
fi

Practical Examples

Find Top Migration Candidates

Bash

# Show top 10 files scoring above 50
calor assess ./src --threshold 50 --top 10

CI/CD Integration

YAML

# GitHub Actions example
- name: Analyze Calor migration potential
  run: |
    calor assess ./src --format sarif --output calor-analysis.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: calor-analysis.sarif

Generate Migration Report

Bash

# Full JSON report for documentation
calor assess . --format json --output migration-report.json

# Parse with jq to find critical files
cat migration-report.json | jq '.files[] | select(.priority == "critical") | .path'

Verbose Analysis of Specific Area

Bash

# Deep dive into a specific directory
calor assess ./src/Services --verbose --top 50

Skipped Files

The analyzer automatically skips:

Generated files: *.g.cs, *.generated.cs, *.Designer.cs
Build directories: obj/, bin/
Version control: .git/
Dependencies: node_modules/
Files with parse errors

Skipped files are reported in the summary but don't affect scoring.