codespan

Beautiful diagnostic reporting for text-based programming languages — Crystal port of rust codespan
A Crystal-native port focused on faithful diagnostic behavior.

Architecture · Development · Guidelines · Testing · PR Workflow · Porting Parity

codespan transforms compiler errors into readable diagnostics — spanning code regions with carets, underlines, and labels to provide context and clarity. This Crystal port keeps the precision and clarity of rust-codespan while adapting implementation details to Crystal idioms.

Status: 156 specs, 19 golden parity tests, rendering complete for all display styles (Rich/Medium/Short).

Quick Start

shards install
crystal spec

Features

• Rich diagnostic rendering: Box-drawing borders, carets, multiline labels with ╭│╰ markers
• Three display styles: Rich (full source context), Medium (header + notes), Short (header only)
• Unicode & tab support: Tab-stop-aware spacing, CJK/wide character display width
• LSP integration: Byte offset ↔ LSP position/range conversion with UTF-16 encoding
• 19 golden parity tests: Validated byte-for-byte against Rust codespan output

Installation

dependencies:
  codespan:
    github: dsisnero/codespan

Usage

require "codespan"

files = Codespan::Reporting::Files::SimpleFiles.new
file_id = files.add("test.cr", "1 + \"hello\"\n")

diagnostic = Codespan::Reporting::Diagnostic.error
  .with_message("type mismatch")
  .with_code("E0001")
  .with_labels([
    Codespan::Reporting::Label.primary(file_id, 4...11)
      .with_message("expected Int, found String"),
  ])

config = Codespan::Reporting::Term::Config.new
output = Codespan::Reporting::Term.emit_into_string(config, files, diagnostic)
puts output

Development

shards install
crystal tool format --check src spec
ameba src spec
crystal spec

Documentation

Contributors

• Dominic Sisneros — creator and maintainer