diag

Documentation

Overview

Package diag provides diagnostic reporting for the type checker.

Diagnostics are categorized by severity:

• Error: Type errors that prevent correctness (mismatches, undefined vars)
• Warning: Suspicious patterns that may indicate bugs (unreachable code)
• Hint: Suggestions for improvement (style, optimization)

Each diagnostic includes position, code, message, and severity. Diagnostics render in Rust-style format with source context and optional ANSI colors.

The Collector accumulates diagnostics during type checking with automatic deduplication. It supports snapshot/restore via Truncate for speculative checking where diagnostics may need to be rolled back.

Usage:

collector := diag.NewCollector("example.lua")
collector.Add(node, diag.ErrTypeMismatch, "expected %s, got %s", want, got)

if collector.HasErrors() {
    source := diag.ParseSource(sourceCode)
    fmt.Print(collector.RenderAllColored(source))
}

Index

• func ContextualHelp(code Code, format, _ string) (explanation, help string)
• type Code
  • func (c Code) Info() CodeInfo
  • func (c Code) Name() string
• type CodeInfo
• type Collector
  • func NewCollector(source string) *Collector
  • func (c *Collector) Add(node PositionHolder, code Code, format string, args ...any)
  • func (c *Collector) AddHint(node PositionHolder, code Code, format string, args ...any)
  • func (c *Collector) AddWarning(node PositionHolder, code Code, format string, args ...any)
  • func (c *Collector) All() []Diagnostic
  • func (c *Collector) Clear()
  • func (c *Collector) HasErrors() bool
  • func (c *Collector) HasWarnings() bool
  • func (c *Collector) Len() int
  • func (c *Collector) RenderAll(source SourceLines) string
  • func (c *Collector) RenderAllColored(source SourceLines) string
  • func (c *Collector) Source() string
  • func (c *Collector) Truncate(count int)
• type Diagnostic
  • func (d Diagnostic) Error() string
  • func (d Diagnostic) Render(source SourceLines) string
  • func (d Diagnostic) RenderColored(source SourceLines) string
  • func (d Diagnostic) String() string
• type Label
• type Position
  • func (p Position) String() string
• type PositionHolder
• type Severity
  • func (s Severity) String() string
• type SourceLines
  • func ParseSource(source string) SourceLines
  • func (s SourceLines) GetLine(n int) string
• type Span
  • func (s Span) SingleLine() bool
  • func (s Span) Valid() bool
• type SpanHolder

Functions

func ContextualHelp

func ContextualHelp(code Code, format, _ string) (explanation, help string)

ContextualHelp returns explanation and help text based on error patterns.

Types

type Code

type Code int

Code categorizes diagnostics by error type.

Each code has associated metadata (title, explanation) in codeInfos. Codes are formatted as E0000-E9999 for display.

const (
	ErrTypeMismatch Code = iota
	ErrUndefined
	ErrNotCallable
	ErrWrongArity
	ErrNoField
	ErrNotIndexable
	ErrNoSynthesizer
	ErrNoHandler
	ErrReadonly
	ErrUnreachable
	ErrMissingReturn
	ErrDepthLimit
	ErrUnresolvedTypeRef
	ErrCircularReference
	ErrNonExhaustive
	ErrUseBeforeAssign
	ErrPreconditionViolation
	ErrDuplicateDeclaration
	ErrInvalidIndexType
	ErrInvalidOperand
	ErrUnsatConstraint
	ErrOptionalCall
	ErrNoMethod
)

func (Code) Info

func (c Code) Info() CodeInfo

Info returns metadata for this code.

func (Code) Name

func (c Code) Name() string

Name returns the formatted code identifier (e.g., E0001).

type CodeInfo

type CodeInfo struct {
	Title       string
	Explanation string
}

CodeInfo holds metadata for a diagnostic code.

type Collector

type Collector struct {
	// contains filtered or unexported fields
}

Collector accumulates diagnostics during type checking. Thread-safe and supports deduplication by position and format string.

func NewCollector

func NewCollector(source string) *Collector

NewCollector creates a collector for the given source file.

func (*Collector) Add

func (c *Collector) Add(node PositionHolder, code Code, format string, args ...any)

Add records an error diagnostic.

func (*Collector) AddHint

func (c *Collector) AddHint(node PositionHolder, code Code, format string, args ...any)

AddHint records a hint diagnostic.

func (*Collector) AddWarning

func (c *Collector) AddWarning(node PositionHolder, code Code, format string, args ...any)

AddWarning records a warning diagnostic.

func (*Collector) All

func (c *Collector) All() []Diagnostic

All returns a copy of all diagnostics.

func (*Collector) Clear

func (c *Collector) Clear()

Clear removes all diagnostics.

func (*Collector) HasErrors

func (c *Collector) HasErrors() bool

HasErrors returns true if any error-severity diagnostics exist.

func (*Collector) HasWarnings

func (c *Collector) HasWarnings() bool

HasWarnings returns true if any warning-severity diagnostics exist.

func (*Collector) Len

func (c *Collector) Len() int

Len returns the number of diagnostics.

func (*Collector) RenderAll

func (c *Collector) RenderAll(source SourceLines) string

RenderAll formats all diagnostics without colors.

func (*Collector) RenderAllColored

func (c *Collector) RenderAllColored(source SourceLines) string

RenderAllColored formats all diagnostics with colors.

func (*Collector) Source

func (c *Collector) Source() string

Source returns the source file name.

func (*Collector) Truncate

func (c *Collector) Truncate(count int)

Truncate removes diagnostics added after count, rebuilding the dedup cache.

type Diagnostic

type Diagnostic struct {
	Position    Position
	Span        Span
	Code        Code
	Message     string
	Format      string
	Severity    Severity
	Explanation string
	Help        string
	Labels      []Label
}

Diagnostic represents a type error, warning, or hint.

A Diagnostic contains all information needed to display a rich error message:

• Position/Span: Where the error occurred for source highlighting
• Code: Categorizes the error for filtering and documentation lookup
• Message: The primary error description (formatted from Format + args)
• Explanation: Detailed description of why this is an error
• Help: Suggested fix or workaround
• Labels: Secondary source locations with annotations

Diagnostics implement the error interface for use in error handling.

func (Diagnostic) Error

func (d Diagnostic) Error() string

Error implements the error interface.

func (Diagnostic) Render

func (d Diagnostic) Render(source SourceLines) string

Render formats the diagnostic in Rust-style without colors.

The output format includes:

• Severity and error code header
• Source location with file:line:column
• Source line with underline highlighting
• Secondary labels (if any)
• Explanation note (if set)
• Help suggestion (if set)

func (Diagnostic) RenderColored

func (d Diagnostic) RenderColored(source SourceLines) string

RenderColored formats the diagnostic in Rust-style with ANSI colors.

Uses ANSI escape codes for terminal color output:

• Red for errors
• Yellow for warnings
• Cyan for hints
• Blue for line numbers and markers

func (Diagnostic) String

func (d Diagnostic) String() string

type Label

type Label struct {
	Span    Span
	Message string
}

Label marks a secondary source location with an annotation message.

Labels provide additional context for diagnostics, such as pointing to the declaration when an error involves both use and definition sites.

type Position

type Position struct {
	File   string
	Line   int
	Column int
}

Position identifies a location in source code.

Line and Column are 1-indexed to match editor conventions. File is the source file path for multi-file diagnostics.

func (Position) String

func (p Position) String() string

type PositionHolder

type PositionHolder interface {
	Line() int
}

PositionHolder is implemented by AST nodes that have line information.

type Severity

type Severity int

Severity indicates the importance level of a diagnostic.

Severity levels affect compilation behavior and IDE presentation:

• Error: Type errors that indicate likely runtime failures. May block execution.
• Warning: Suspicious patterns that may indicate bugs but are not type errors.
• Hint: Suggestions for improvement that do not indicate problems.

const (
	SeverityError Severity = iota
	SeverityWarning
	SeverityHint
)

func (Severity) String

func (s Severity) String() string

type SourceLines

type SourceLines []string

SourceLines holds source code split by lines for rendering diagnostics.

Lines are 0-indexed internally, but GetLine accepts 1-indexed line numbers to match Position.Line convention.

func ParseSource

func ParseSource(source string) SourceLines

ParseSource splits source code into lines for diagnostic rendering.

func (SourceLines) GetLine

func (s SourceLines) GetLine(n int) string

GetLine returns the 1-indexed line, or empty string if out of bounds.

type Span

type Span struct {
	StartLine int
	StartCol  int
	EndLine   int
	EndCol    int
}

Span defines a range in source code for highlighting.

All fields are 1-indexed. EndLine and EndCol may be 0 to indicate a point span (single character) or unknown extent.

func (Span) SingleLine

func (s Span) SingleLine() bool

SingleLine returns true if the span does not cross line boundaries.

func (Span) Valid

func (s Span) Valid() bool

Valid returns true if the span has meaningful positions.

type SpanHolder

type SpanHolder interface {
	PositionHolder
	Column() int
	LastLine() int
	LastColumn() int
}

SpanHolder extends PositionHolder with full range information.