codespan

---

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

Document	Purpose
Architecture	System design, data flow, package responsibilities
Development	Prerequisites, setup, daily workflow
Coding Guidelines	Code style, error handling, naming conventions
Testing	Test commands, conventions, golden parity
PR Workflow	Commits, PRs, branch naming, review process
Porting Parity	Upstream commit pin, coverage ledger, parity verification

Contributors

• Dominic Sisneros — creator and maintainer