tsz_solver/

diagnostics.rs

//! Diagnostic generation for the solver.
//!
//! This module provides error message generation for type checking failures.
//! It produces human-readable diagnostics with source locations and context.
//!
//! ## Architecture: Lazy Diagnostics
//!
//! To avoid expensive string formatting during type checking (especially in tentative
//! contexts like overload resolution), this module uses a two-phase approach:
//!
//! 1. **Collection**: Store structured data in `PendingDiagnostic` with `DiagnosticArg` values
//! 2. **Rendering**: Format strings lazily only when displaying to the user
//!
//! This prevents calling `type_to_string()` thousands of times for errors that are
//! discarded during overload resolution.
//!
//! ## Tracer Pattern (Zero-Cost Abstraction)
//!
//! The tracer pattern allows the same subtype checking logic to be used for both
//! fast boolean checks and detailed diagnostic generation, eliminating logic drift.
//!
//! - **`FastTracer`**: Zero-cost abstraction that compiles to a simple boolean return
//! - **`DiagnosticTracer`**: Collects detailed `SubtypeFailureReason` for error messages

use crate::TypeDatabase;
use crate::TypeFormatter;
use crate::def::DefinitionStore;
use crate::types::{TypeId, Visibility};
use std::sync::Arc;
use tsz_binder::SymbolId;
use tsz_common::interner::Atom;

// =============================================================================
// Tracer Pattern: Zero-Cost Diagnostic Abstraction
// =============================================================================

/// A trait for tracing subtype check failures.
///
/// This trait enables the same subtype checking logic to be used for both
/// fast boolean checks (via `FastTracer`) and detailed diagnostics (via `DiagnosticTracer`).
///
/// The key insight is that failure reasons are constructed lazily via a closure,
/// so `FastTracer` can skip the allocation entirely while `DiagnosticTracer` collects
/// detailed information.
///
/// # Example
///
/// ```rust,ignore
/// fn check_subtype_with_tracer<T: SubtypeTracer>(
///     source: TypeId,
///     target: TypeId,
///     tracer: &mut T,
/// ) -> bool {
///     if source == target {
///         return true;
///     }
///     tracer.on_mismatch(|| SubtypeFailureReason::TypeMismatch { source, target })
/// }
/// ```
pub trait SubtypeTracer {
    /// Called when a subtype mismatch is detected.
    ///
    /// The `reason` closure is only called if the tracer needs to collect
    /// the failure reason. This allows `FastTracer` to skip the allocation
    /// entirely while `DiagnosticTracer` can collect detailed information.
    ///
    /// # Returns
    ///
    /// - `true` if checking should continue (for collecting more nested failures)
    /// - `false` if checking should stop immediately (fast path)
    ///
    /// # Type Parameters
    ///
    /// The `reason` parameter is a closure that constructs the failure reason.
    /// It's wrapped in `FnOnce` so it's only called when needed.
    fn on_mismatch(&mut self, reason: impl FnOnce() -> SubtypeFailureReason) -> bool;
}

/// Object-safe version of `SubtypeTracer` for dynamic dispatch.
///
/// This trait is dyn-compatible and can be used as `&mut dyn DynSubtypeTracer`.
/// It has a simpler signature that takes the reason directly rather than a closure.
pub trait DynSubtypeTracer {
    /// Called when a subtype mismatch is detected.
    ///
    /// Unlike `SubtypeTracer::on_mismatch`, this takes the reason directly
    /// rather than a closure. This makes it object-safe (dyn-compatible).
    ///
    /// # Returns
    ///
    /// - `true` if checking should continue (for collecting more nested failures)
    /// - `false` if checking should stop immediately (fast path)
    fn on_mismatch_dyn(&mut self, reason: SubtypeFailureReason) -> bool;
}

/// Blanket implementation for all `SubtypeTracer` types.
impl<T: SubtypeTracer> DynSubtypeTracer for T {
    fn on_mismatch_dyn(&mut self, reason: SubtypeFailureReason) -> bool {
        self.on_mismatch(|| reason)
    }
}

#[cfg(test)]
/// Fast tracer that returns immediately on mismatch (zero-cost abstraction).
///
/// This tracer is used for fast subtype checks where we only care about the
/// boolean result. The `#[inline(always)]` attribute ensures that this compiles
/// to the same code as a simple `return false` statement with no runtime overhead.
///
/// # Zero-Cost Abstraction
///
/// ```rust,ignore
/// // With FastTracer, this compiles to:
/// // if condition { return false; }
/// if !tracer.on_mismatch(|| reason) { return false; }
/// ```
///
/// The closure is never called, so no allocations occur.
#[derive(Clone, Copy, Debug)]
pub struct FastTracer;

#[cfg(test)]
impl SubtypeTracer for FastTracer {
    /// Always return `false` to stop checking immediately.
    ///
    /// The `reason` closure is never called, so no `SubtypeFailureReason` is constructed.
    /// This is the zero-cost path - the compiler will optimize this to a simple boolean return.
    #[inline(always)]
    fn on_mismatch(&mut self, _reason: impl FnOnce() -> SubtypeFailureReason) -> bool {
        false
    }
}

#[cfg(test)]
/// Diagnostic tracer that collects detailed failure reasons.
///
/// This tracer is used when we need to generate detailed error messages.
/// It collects the first `SubtypeFailureReason` encountered and stops checking.
///
/// # Example
///
/// ```rust,ignore
/// let mut tracer = DiagnosticTracer::new();
/// check_subtype_with_tracer(source, target, &mut tracer);
/// if let Some(reason) = tracer.take_failure() {
///     // Generate error message from reason
/// }
/// ```
#[derive(Debug)]
pub struct DiagnosticTracer {
    /// The first failure reason encountered (if any).
    failure: Option<SubtypeFailureReason>,
}

#[cfg(test)]
impl DiagnosticTracer {
    /// Create a new diagnostic tracer.
    pub fn new() -> Self {
        Self { failure: None }
    }

    /// Take the collected failure reason, leaving `None` in its place.
    pub fn take_failure(&mut self) -> Option<SubtypeFailureReason> {
        self.failure.take()
    }

    /// Get a reference to the collected failure reason (if any).
    /// Check if any failure was collected.
    pub fn has_failure(&self) -> bool {
        self.failure.is_some()
    }
}

#[cfg(test)]
impl Default for DiagnosticTracer {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
impl SubtypeTracer for DiagnosticTracer {
    /// Collect the failure reason and stop checking.
    ///
    /// The `reason` closure is called to construct the detailed failure reason,
    /// which is stored for later use in error message generation.
    ///
    /// Returns `false` to stop checking after collecting the first failure.
    /// This matches the semantics of `FastTracer` while collecting diagnostics.
    #[inline]
    fn on_mismatch(&mut self, reason: impl FnOnce() -> SubtypeFailureReason) -> bool {
        // Only collect the first failure (subsequent failures are nested details)
        if self.failure.is_none() {
            self.failure = Some(reason());
        }
        false
    }
}

/// Detailed reason for a subtype check failure.
///
/// This enum captures all the different ways a subtype check can fail,
/// with enough detail to generate helpful error messages.
///
/// # Nesting
///
/// Some variants include `nested_reason` to capture failures in nested types.
/// For example, a property type mismatch might include why the property types
/// themselves don't match.
#[derive(Clone, Debug, PartialEq)]
pub enum SubtypeFailureReason {
    /// A required property is missing in the source type.
    MissingProperty {
        property_name: Atom,
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Multiple required properties are missing in the source type (TS2739).
    MissingProperties {
        property_names: Vec<Atom>,
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Property types are incompatible.
    PropertyTypeMismatch {
        property_name: Atom,
        source_property_type: TypeId,
        target_property_type: TypeId,
        nested_reason: Option<Box<Self>>,
    },
    /// Optional property cannot satisfy required property.
    OptionalPropertyRequired { property_name: Atom },
    /// Readonly property cannot satisfy mutable property.
    ReadonlyPropertyMismatch { property_name: Atom },
    /// Property visibility mismatch (private/protected vs public).
    PropertyVisibilityMismatch {
        property_name: Atom,
        source_visibility: Visibility,
        target_visibility: Visibility,
    },
    /// Property nominal mismatch (separate declarations of private/protected property).
    PropertyNominalMismatch { property_name: Atom },
    /// Return types are incompatible.
    ReturnTypeMismatch {
        source_return: TypeId,
        target_return: TypeId,
        nested_reason: Option<Box<Self>>,
    },
    /// Parameter types are incompatible.
    ParameterTypeMismatch {
        param_index: usize,
        source_param: TypeId,
        target_param: TypeId,
    },
    /// Too many parameters in source.
    TooManyParameters {
        source_count: usize,
        target_count: usize,
    },
    /// Tuple element count mismatch.
    TupleElementMismatch {
        source_count: usize,
        target_count: usize,
    },
    /// Tuple element type mismatch.
    TupleElementTypeMismatch {
        index: usize,
        source_element: TypeId,
        target_element: TypeId,
    },
    /// Array element type mismatch.
    ArrayElementMismatch {
        source_element: TypeId,
        target_element: TypeId,
    },
    /// Index signature value type mismatch.
    IndexSignatureMismatch {
        index_kind: &'static str, // "string" or "number"
        source_value_type: TypeId,
        target_value_type: TypeId,
    },
    /// No union member matches.
    NoUnionMemberMatches {
        source_type: TypeId,
        target_union_members: Vec<TypeId>,
    },
    /// No intersection member matches target (intersection requires at least one member).
    NoIntersectionMemberMatches {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// No overlapping properties for weak type target.
    NoCommonProperties {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Generic type mismatch (no more specific reason).
    TypeMismatch {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Intrinsic type mismatch (e.g., string vs number).
    IntrinsicTypeMismatch {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Literal type mismatch (e.g., "hello" vs "world" or "hello" vs 42).
    LiteralTypeMismatch {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Error type encountered - indicates unresolved type that should not be silently compatible.
    ErrorType {
        source_type: TypeId,
        target_type: TypeId,
    },
    /// Recursion limit exceeded during type checking.
    RecursionLimitExceeded,
    /// Parameter count mismatch.
    ParameterCountMismatch {
        source_count: usize,
        target_count: usize,
    },
    /// Excess property in object literal assignment (TS2353).
    ExcessProperty {
        property_name: Atom,
        target_type: TypeId,
    },
}

/// Diagnostic severity level.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DiagnosticSeverity {
    Error,
    Warning,
    Suggestion,
    Message,
}

// =============================================================================
// Lazy Diagnostic Arguments
// =============================================================================

/// Argument for a diagnostic message template.
///
/// Instead of eagerly formatting types to strings, we store the raw data
/// (`TypeId`, `SymbolId`, etc.) and only format when rendering.
#[derive(Clone, Debug)]
pub enum DiagnosticArg {
    /// A type reference (will be formatted via `TypeFormatter`)
    Type(TypeId),
    /// A symbol reference (will be looked up by name)
    Symbol(SymbolId),
    /// An interned string
    Atom(Atom),
    /// A plain string
    String(Arc<str>),
    /// A number
    Number(usize),
}

macro_rules! impl_from_diagnostic_arg {
    ($($source:ty => $variant:ident),* $(,)?) => {
        $(impl From<$source> for DiagnosticArg {
            fn from(v: $source) -> Self { Self::$variant(v) }
        })*
    };
}

impl_from_diagnostic_arg! {
    TypeId   => Type,
    SymbolId => Symbol,
    Atom     => Atom,
    usize    => Number,
}

impl From<&str> for DiagnosticArg {
    fn from(s: &str) -> Self {
        Self::String(s.into())
    }
}

impl From<String> for DiagnosticArg {
    fn from(s: String) -> Self {
        Self::String(s.into())
    }
}

/// A pending diagnostic that hasn't been rendered yet.
///
/// This stores the structured data needed to generate an error message,
/// but defers the expensive string formatting until rendering time.
#[derive(Clone, Debug)]
pub struct PendingDiagnostic {
    /// Diagnostic code (e.g., 2322 for type not assignable)
    pub code: u32,
    /// Arguments for the message template
    pub args: Vec<DiagnosticArg>,
    /// Primary source location
    pub span: Option<SourceSpan>,
    /// Severity level
    pub severity: DiagnosticSeverity,
    /// Related information (additional locations)
    pub related: Vec<Self>,
}

impl PendingDiagnostic {
    /// Create a new pending error diagnostic.
    pub const fn error(code: u32, args: Vec<DiagnosticArg>) -> Self {
        Self {
            code,
            args,
            span: None,
            severity: DiagnosticSeverity::Error,
            related: Vec::new(),
        }
    }

    /// Attach a source span to this diagnostic.
    pub fn with_span(mut self, span: SourceSpan) -> Self {
        self.span = Some(span);
        self
    }

    /// Add related information.
    pub fn with_related(mut self, related: Self) -> Self {
        self.related.push(related);
        self
    }
}

/// A source location span.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SourceSpan {
    /// Start position (byte offset)
    pub start: u32,
    /// Length in bytes
    pub length: u32,
    /// File path or name
    pub file: Arc<str>,
}

impl SourceSpan {
    pub fn new(file: impl Into<Arc<str>>, start: u32, length: u32) -> Self {
        Self {
            start,
            length,
            file: file.into(),
        }
    }
}

/// Related diagnostic information (e.g., "see declaration here").
#[derive(Clone, Debug)]
pub struct RelatedInformation {
    pub span: SourceSpan,
    pub message: String,
}

/// A type checking diagnostic.
#[derive(Clone, Debug)]
pub struct TypeDiagnostic {
    /// The main error message
    pub message: String,
    /// Diagnostic code (e.g., 2322 for "Type X is not assignable to type Y")
    pub code: u32,
    /// Severity level
    pub severity: DiagnosticSeverity,
    /// Primary source location
    pub span: Option<SourceSpan>,
    /// Related information (additional locations)
    pub related: Vec<RelatedInformation>,
}

impl TypeDiagnostic {
    /// Create a new error diagnostic.
    pub fn error(message: impl Into<String>, code: u32) -> Self {
        Self {
            message: message.into(),
            code,
            severity: DiagnosticSeverity::Error,
            span: None,
            related: Vec::new(),
        }
    }

    /// Add a source span to this diagnostic.
    pub fn with_span(mut self, span: SourceSpan) -> Self {
        self.span = Some(span);
        self
    }

    /// Add related information.
    pub fn with_related(mut self, span: SourceSpan, message: impl Into<String>) -> Self {
        self.related.push(RelatedInformation {
            span,
            message: message.into(),
        });
        self
    }
}

// =============================================================================
// Diagnostic Codes (matching TypeScript's)
// =============================================================================

/// TypeScript diagnostic codes for type errors.
///
/// These are re-exported from `tsz_common::diagnostics::diagnostic_codes` with
/// short aliases for ergonomic use within the solver. The canonical definitions
/// live in `tsz-common` to maintain a single source of truth.
pub mod codes {
    use tsz_common::diagnostics::diagnostic_codes as dc;

    // Type assignability
    pub use dc::ARGUMENT_OF_TYPE_IS_NOT_ASSIGNABLE_TO_PARAMETER_OF_TYPE as ARG_NOT_ASSIGNABLE;
    pub use dc::CANNOT_ASSIGN_TO_BECAUSE_IT_IS_A_READ_ONLY_PROPERTY as READONLY_PROPERTY;
    pub use dc::OBJECT_LITERAL_MAY_ONLY_SPECIFY_KNOWN_PROPERTIES_AND_DOES_NOT_EXIST_IN_TYPE as EXCESS_PROPERTY;
    pub use dc::PROPERTY_IS_MISSING_IN_TYPE_BUT_REQUIRED_IN_TYPE as PROPERTY_MISSING;
    pub use dc::PROPERTY_IS_PRIVATE_AND_ONLY_ACCESSIBLE_WITHIN_CLASS as PROPERTY_VISIBILITY_MISMATCH;
    pub use dc::PROPERTY_IS_PROTECTED_AND_ONLY_ACCESSIBLE_THROUGH_AN_INSTANCE_OF_CLASS_THIS_IS_A as PROPERTY_NOMINAL_MISMATCH;
    pub use dc::TYPE_HAS_NO_PROPERTIES_IN_COMMON_WITH_TYPE as NO_COMMON_PROPERTIES;
    pub use dc::TYPE_IS_MISSING_THE_FOLLOWING_PROPERTIES_FROM_TYPE as MISSING_PROPERTIES;
    pub use dc::TYPE_IS_NOT_ASSIGNABLE_TO_TYPE as TYPE_NOT_ASSIGNABLE;

    pub use dc::TYPES_OF_PROPERTY_ARE_INCOMPATIBLE as PROPERTY_TYPE_MISMATCH;

    // Function/call errors
    pub use dc::CANNOT_FIND_NAME;
    pub use dc::CANNOT_FIND_NAME_DO_YOU_NEED_TO_CHANGE_YOUR_TARGET_LIBRARY_TRY_CHANGING_THE_LIB as CANNOT_FIND_NAME_TARGET_LIB;
    pub use dc::CANNOT_FIND_NAME_DO_YOU_NEED_TO_CHANGE_YOUR_TARGET_LIBRARY_TRY_CHANGING_THE_LIB_2 as CANNOT_FIND_NAME_DOM;
    pub use dc::CANNOT_FIND_NAME_DO_YOU_NEED_TO_INSTALL_TYPE_DEFINITIONS_FOR_A_TEST_RUNNER_TRY_N as CANNOT_FIND_NAME_TEST_RUNNER;
    pub use dc::CANNOT_FIND_NAME_DO_YOU_NEED_TO_INSTALL_TYPE_DEFINITIONS_FOR_NODE_TRY_NPM_I_SAVE as CANNOT_FIND_NAME_NODE;
    pub use dc::EXPECTED_ARGUMENTS_BUT_GOT as ARG_COUNT_MISMATCH;
    pub use dc::PROPERTY_DOES_NOT_EXIST_ON_TYPE as PROPERTY_NOT_EXIST;
    pub use dc::PROPERTY_DOES_NOT_EXIST_ON_TYPE_DID_YOU_MEAN as PROPERTY_NOT_EXIST_DID_YOU_MEAN;
    pub use dc::THE_THIS_CONTEXT_OF_TYPE_IS_NOT_ASSIGNABLE_TO_METHODS_THIS_OF_TYPE as THIS_TYPE_MISMATCH;
    pub use dc::THIS_EXPRESSION_IS_NOT_CALLABLE as NOT_CALLABLE;

    // Null/undefined errors

    // Implicit any errors (7xxx series)
    pub use dc::FUNCTION_EXPRESSION_WHICH_LACKS_RETURN_TYPE_ANNOTATION_IMPLICITLY_HAS_AN_RETURN as IMPLICIT_ANY_RETURN_FUNCTION_EXPRESSION;
    pub use dc::MEMBER_IMPLICITLY_HAS_AN_TYPE as IMPLICIT_ANY_MEMBER;
    pub use dc::PARAMETER_IMPLICITLY_HAS_AN_TYPE as IMPLICIT_ANY_PARAMETER;
    pub use dc::VARIABLE_IMPLICITLY_HAS_AN_TYPE as IMPLICIT_ANY;
    pub use dc::WHICH_LACKS_RETURN_TYPE_ANNOTATION_IMPLICITLY_HAS_AN_RETURN_TYPE as IMPLICIT_ANY_RETURN;
}

/// Map well-known names to their specialized "cannot find name" diagnostic codes.
///
/// TypeScript emits different error codes for well-known globals that are missing
/// because they require specific type definitions or target library changes:
/// - Node.js globals (require, process, Buffer, etc.) → TS2580
/// - Test runner globals (describe, it, test, etc.) → TS2582
/// - Target library types (Promise, Symbol, Map, etc.) → TS2583
/// - DOM globals (document, console) → TS2584
fn cannot_find_name_code(name: &str) -> u32 {
    match name {
        // Node.js globals → TS2580
        "require" | "exports" | "module" | "process" | "Buffer" | "__filename" | "__dirname" => {
            codes::CANNOT_FIND_NAME_NODE
        }
        // Test runner globals → TS2582
        "describe" | "suite" | "it" | "test" => codes::CANNOT_FIND_NAME_TEST_RUNNER,
        // Target library types → TS2583
        "Promise" | "Symbol" | "Map" | "Set" | "Reflect" | "Iterator" | "AsyncIterator"
        | "SharedArrayBuffer" => codes::CANNOT_FIND_NAME_TARGET_LIB,
        // DOM globals → TS2584
        "document" | "console" => codes::CANNOT_FIND_NAME_DOM,
        // Everything else → TS2304
        _ => codes::CANNOT_FIND_NAME,
    }
}

// =============================================================================
// Message Templates
// =============================================================================

/// Get the message template for a diagnostic code.
///
/// Templates use {0}, {1}, etc. as placeholders for arguments.
/// Message strings are sourced from `tsz_common::diagnostics::diagnostic_messages`
/// to maintain a single source of truth with the checker.
pub fn get_message_template(code: u32) -> &'static str {
    tsz_common::diagnostics::get_message_template(code).unwrap_or("Unknown diagnostic")
}

// =============================================================================
// Type Formatting
// =============================================================================

// TypeFormatter is now in format.rs

// Diagnostic Builder
// =============================================================================

/// Builder for creating type error diagnostics.
pub struct DiagnosticBuilder<'a> {
    formatter: TypeFormatter<'a>,
}

impl<'a> DiagnosticBuilder<'a> {
    pub fn new(interner: &'a dyn TypeDatabase) -> Self {
        DiagnosticBuilder {
            formatter: TypeFormatter::new(interner),
        }
    }

    /// Create a diagnostic builder with access to symbol names.
    ///
    /// This prevents "Ref(N)" fallback strings in diagnostic messages by
    /// resolving symbol references to their actual names.
    pub fn with_symbols(
        interner: &'a dyn TypeDatabase,
        symbol_arena: &'a tsz_binder::SymbolArena,
    ) -> Self {
        DiagnosticBuilder {
            formatter: TypeFormatter::with_symbols(interner, symbol_arena),
        }
    }

    /// Create a diagnostic builder with access to definition store.
    ///
    /// This prevents "Lazy(N)" fallback strings in diagnostic messages by
    /// resolving `DefIds` to their type names.
    pub fn with_def_store(mut self, def_store: &'a DefinitionStore) -> Self {
        self.formatter = self.formatter.with_def_store(def_store);
        self
    }

    /// Create a "Type X is not assignable to type Y" diagnostic.
    pub fn type_not_assignable(&mut self, source: TypeId, target: TypeId) -> TypeDiagnostic {
        let source_str = self.formatter.format(source);
        let target_str = self.formatter.format(target);
        TypeDiagnostic::error(
            format!("Type '{source_str}' is not assignable to type '{target_str}'."),
            codes::TYPE_NOT_ASSIGNABLE,
        )
    }

    /// Create a "Property X is missing in type Y" diagnostic.
    pub fn property_missing(
        &mut self,
        prop_name: &str,
        source: TypeId,
        target: TypeId,
    ) -> TypeDiagnostic {
        let source_str = self.formatter.format(source);
        let target_str = self.formatter.format(target);
        TypeDiagnostic::error(
            format!(
                "Property '{prop_name}' is missing in type '{source_str}' but required in type '{target_str}'."
            ),
            codes::PROPERTY_MISSING,
        )
    }

    /// Create a "Property X does not exist on type Y" diagnostic.
    pub fn property_not_exist(&mut self, prop_name: &str, type_id: TypeId) -> TypeDiagnostic {
        let type_str = self.formatter.format(type_id);
        TypeDiagnostic::error(
            format!("Property '{prop_name}' does not exist on type '{type_str}'."),
            codes::PROPERTY_NOT_EXIST,
        )
    }

    /// Create a "Property X does not exist on type Y. Did you mean Z?" diagnostic (TS2551).
    pub fn property_not_exist_did_you_mean(
        &mut self,
        prop_name: &str,
        type_id: TypeId,
        suggestion: &str,
    ) -> TypeDiagnostic {
        let type_str = self.formatter.format(type_id);
        TypeDiagnostic::error(
            format!(
                "Property '{prop_name}' does not exist on type '{type_str}'. Did you mean '{suggestion}'?"
            ),
            codes::PROPERTY_NOT_EXIST_DID_YOU_MEAN,
        )
    }

    /// Create an "Argument not assignable" diagnostic.
    pub fn argument_not_assignable(
        &mut self,
        arg_type: TypeId,
        param_type: TypeId,
    ) -> TypeDiagnostic {
        let arg_str = self.formatter.format(arg_type);
        let param_str = self.formatter.format(param_type);
        TypeDiagnostic::error(
            format!(
                "Argument of type '{arg_str}' is not assignable to parameter of type '{param_str}'."
            ),
            codes::ARG_NOT_ASSIGNABLE,
        )
    }

    /// Create a "Cannot find name" diagnostic.
    pub fn cannot_find_name(&mut self, name: &str) -> TypeDiagnostic {
        // Skip TS2304 for identifiers that are clearly not valid names.
        // These are likely parse errors (e.g., ",", ";", "(") that were
        // added to the AST for error recovery. The parse error should have
        // already been emitted (e.g., TS1136 "Property assignment expected").
        let is_obviously_invalid = name.len() == 1
            && matches!(
                name.chars().next(),
                Some(
                    ',' | ';'
                        | ':'
                        | '('
                        | ')'
                        | '['
                        | ']'
                        | '{'
                        | '}'
                        | '+'
                        | '-'
                        | '*'
                        | '/'
                        | '%'
                        | '&'
                        | '|'
                        | '^'
                        | '!'
                        | '~'
                        | '<'
                        | '>'
                        | '='
                        | '.'
                )
            );

        if is_obviously_invalid {
            // Return a dummy diagnostic with empty message that will be ignored
            return TypeDiagnostic::error("", 0);
        }

        let code = cannot_find_name_code(name);
        TypeDiagnostic::error(format!("Cannot find name '{name}'."), code)
    }

    /// Create a "Type X is not callable" diagnostic.
    pub fn not_callable(&mut self, type_id: TypeId) -> TypeDiagnostic {
        let type_str = self.formatter.format(type_id);
        TypeDiagnostic::error(
            format!("Type '{type_str}' has no call signatures."),
            codes::NOT_CALLABLE,
        )
    }

    pub fn this_type_mismatch(
        &mut self,
        expected_this: TypeId,
        actual_this: TypeId,
    ) -> TypeDiagnostic {
        let expected_str = self.formatter.format(expected_this);
        let actual_str = self.formatter.format(actual_this);
        TypeDiagnostic::error(
            format!(
                "The 'this' context of type '{actual_str}' is not assignable to method's 'this' of type '{expected_str}'."
            ),
            codes::THIS_TYPE_MISMATCH,
        )
    }

    /// Create an "Expected N arguments but got M" diagnostic.
    pub fn argument_count_mismatch(&mut self, expected: usize, got: usize) -> TypeDiagnostic {
        TypeDiagnostic::error(
            format!("Expected {expected} arguments, but got {got}."),
            codes::ARG_COUNT_MISMATCH,
        )
    }

    /// Create a "Cannot assign to readonly property" diagnostic.
    pub fn readonly_property(&mut self, prop_name: &str) -> TypeDiagnostic {
        TypeDiagnostic::error(
            format!("Cannot assign to '{prop_name}' because it is a read-only property."),
            codes::READONLY_PROPERTY,
        )
    }

    /// Create an "Excess property" diagnostic.
    pub fn excess_property(&mut self, prop_name: &str, target: TypeId) -> TypeDiagnostic {
        let target_str = self.formatter.format(target);
        TypeDiagnostic::error(
            format!(
                "Object literal may only specify known properties, and '{prop_name}' does not exist in type '{target_str}'."
            ),
            codes::EXCESS_PROPERTY,
        )
    }

    // =========================================================================
    // Implicit Any Diagnostics (TS7006, TS7008, TS7010, TS7011)
    // =========================================================================

    /// Create a "Parameter implicitly has an 'any' type" diagnostic (TS7006).
    ///
    /// This is emitted when noImplicitAny is enabled and a function parameter
    /// has no type annotation and no contextual type.
    pub fn implicit_any_parameter(&mut self, param_name: &str) -> TypeDiagnostic {
        TypeDiagnostic::error(
            format!("Parameter '{param_name}' implicitly has an 'any' type."),
            codes::IMPLICIT_ANY_PARAMETER,
        )
    }

    /// Create a "Parameter implicitly has a specific type" diagnostic (TS7006 variant).
    ///
    /// This is used when the implicit type is known to be something other than 'any',
    /// such as when a rest parameter implicitly has 'any[]'.
    pub fn implicit_any_parameter_with_type(
        &mut self,
        param_name: &str,
        implicit_type: TypeId,
    ) -> TypeDiagnostic {
        let type_str = self.formatter.format(implicit_type);
        TypeDiagnostic::error(
            format!("Parameter '{param_name}' implicitly has an '{type_str}' type."),
            codes::IMPLICIT_ANY_PARAMETER,
        )
    }

    /// Create a "Member implicitly has an 'any' type" diagnostic (TS7008).
    ///
    /// This is emitted when noImplicitAny is enabled and a class/interface member
    /// has no type annotation.
    pub fn implicit_any_member(&mut self, member_name: &str) -> TypeDiagnostic {
        TypeDiagnostic::error(
            format!("Member '{member_name}' implicitly has an 'any' type."),
            codes::IMPLICIT_ANY_MEMBER,
        )
    }

    /// Create a "Variable implicitly has an 'any' type" diagnostic (TS7005).
    ///
    /// This is emitted when noImplicitAny is enabled and a variable declaration
    /// has no type annotation and the inferred type is 'any'.
    pub fn implicit_any_variable(&mut self, var_name: &str, var_type: TypeId) -> TypeDiagnostic {
        let type_str = self.formatter.format(var_type);
        TypeDiagnostic::error(
            format!("Variable '{var_name}' implicitly has an '{type_str}' type."),
            codes::IMPLICIT_ANY,
        )
    }

    /// Create an "implicitly has an 'any' return type" diagnostic (TS7010).
    ///
    /// This is emitted when noImplicitAny is enabled and a function declaration
    /// has no return type annotation and returns 'any'.
    pub fn implicit_any_return(&mut self, func_name: &str, return_type: TypeId) -> TypeDiagnostic {
        let type_str = self.formatter.format(return_type);
        TypeDiagnostic::error(
            format!(
                "'{func_name}', which lacks return-type annotation, implicitly has an '{type_str}' return type."
            ),
            codes::IMPLICIT_ANY_RETURN,
        )
    }

    /// Create a "Function expression implicitly has an 'any' return type" diagnostic (TS7011).
    ///
    /// This is emitted when noImplicitAny is enabled and a function expression
    /// has no return type annotation and returns 'any'.
    pub fn implicit_any_return_function_expression(
        &mut self,
        return_type: TypeId,
    ) -> TypeDiagnostic {
        let type_str = self.formatter.format(return_type);
        TypeDiagnostic::error(
            format!(
                "Function expression, which lacks return-type annotation, implicitly has an '{type_str}' return type."
            ),
            codes::IMPLICIT_ANY_RETURN_FUNCTION_EXPRESSION,
        )
    }
}

// =============================================================================
// Pending Diagnostic Builder (LAZY)
// =============================================================================

/// Builder for creating lazy pending diagnostics.
///
/// This builder creates `PendingDiagnostic` instances that defer expensive
/// string formatting until rendering time.
pub struct PendingDiagnosticBuilder;

// =============================================================================
// SubtypeFailureReason to PendingDiagnostic Conversion
// =============================================================================

impl SubtypeFailureReason {
    /// Return the primary diagnostic code for this failure reason.
    ///
    /// This is the single source of truth for mapping `SubtypeFailureReason` variants
    /// to diagnostic codes. Both the solver's `to_diagnostic` and the checker's
    /// `render_failure_reason` should use this to stay in sync.
    pub const fn diagnostic_code(&self) -> u32 {
        match self {
            Self::MissingProperty { .. } | Self::OptionalPropertyRequired { .. } => {
                codes::PROPERTY_MISSING
            }
            Self::MissingProperties { .. } => codes::MISSING_PROPERTIES,
            Self::PropertyTypeMismatch { .. } => codes::PROPERTY_TYPE_MISMATCH,
            Self::ReadonlyPropertyMismatch { .. } => codes::READONLY_PROPERTY,
            Self::PropertyVisibilityMismatch { .. } => codes::PROPERTY_VISIBILITY_MISMATCH,
            Self::PropertyNominalMismatch { .. } => codes::PROPERTY_NOMINAL_MISMATCH,
            Self::ReturnTypeMismatch { .. }
            | Self::ParameterTypeMismatch { .. }
            | Self::TupleElementMismatch { .. }
            | Self::TupleElementTypeMismatch { .. }
            | Self::ArrayElementMismatch { .. }
            | Self::IndexSignatureMismatch { .. }
            | Self::NoUnionMemberMatches { .. }
            | Self::NoIntersectionMemberMatches { .. }
            | Self::TypeMismatch { .. }
            | Self::IntrinsicTypeMismatch { .. }
            | Self::LiteralTypeMismatch { .. }
            | Self::ErrorType { .. }
            | Self::RecursionLimitExceeded
            | Self::ParameterCountMismatch { .. } => codes::TYPE_NOT_ASSIGNABLE,
            Self::TooManyParameters { .. } => codes::ARG_COUNT_MISMATCH,
            Self::NoCommonProperties { .. } => codes::NO_COMMON_PROPERTIES,
            Self::ExcessProperty { .. } => codes::EXCESS_PROPERTY,
        }
    }

    /// Convert this failure reason to a `PendingDiagnostic`.
    ///
    /// This is the "explain slow" path - called only when we need to report
    /// an error and want a detailed message about why the type check failed.
    pub fn to_diagnostic(&self, source: TypeId, target: TypeId) -> PendingDiagnostic {
        match self {
            Self::MissingProperty {
                property_name,
                source_type,
                target_type,
            } => PendingDiagnostic::error(
                codes::PROPERTY_MISSING,
                vec![
                    (*property_name).into(),
                    (*source_type).into(),
                    (*target_type).into(),
                ],
            ),

            Self::MissingProperties {
                property_names: _,
                source_type,
                target_type,
            } => PendingDiagnostic::error(
                codes::MISSING_PROPERTIES,
                vec![(*source_type).into(), (*target_type).into()],
            ),

            Self::PropertyTypeMismatch {
                property_name,
                source_property_type,
                target_property_type,
                nested_reason,
            } => {
                // Main error: Type not assignable
                let mut diag = PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                );

                // Add elaboration: Types of property 'x' are incompatible (TS2326)
                let elaboration = PendingDiagnostic::error(
                    codes::PROPERTY_TYPE_MISMATCH,
                    vec![(*property_name).into()],
                );
                diag = diag.with_related(elaboration);

                // If there's a nested reason, add that too
                if let Some(nested) = nested_reason {
                    let nested_diag =
                        nested.to_diagnostic(*source_property_type, *target_property_type);
                    diag = diag.with_related(nested_diag);
                }

                diag
            }

            Self::OptionalPropertyRequired { property_name } => {
                // This is a specific case of type not assignable
                PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                )
                .with_related(PendingDiagnostic::error(
                    codes::PROPERTY_MISSING, // Close enough - property is "missing" because it's optional
                    vec![(*property_name).into(), source.into(), target.into()],
                ))
            }

            Self::ReadonlyPropertyMismatch { property_name } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![source.into(), target.into()],
            )
            .with_related(PendingDiagnostic::error(
                codes::READONLY_PROPERTY,
                vec![(*property_name).into()],
            )),

            Self::PropertyVisibilityMismatch {
                property_name,
                source_visibility,
                target_visibility,
            } => {
                // TS2341/TS2445: Property 'x' is private in type 'A' but not in type 'B'
                PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                )
                .with_related(PendingDiagnostic::error(
                    codes::PROPERTY_VISIBILITY_MISMATCH,
                    vec![
                        (*property_name).into(),
                        format!("{source_visibility:?}").into(),
                        format!("{target_visibility:?}").into(),
                    ],
                ))
            }

            Self::PropertyNominalMismatch { property_name } => {
                // TS2446: Types have separate declarations of a private property 'x'
                PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                )
                .with_related(PendingDiagnostic::error(
                    codes::PROPERTY_NOMINAL_MISMATCH,
                    vec![(*property_name).into()],
                ))
            }

            Self::ReturnTypeMismatch {
                source_return,
                target_return,
                nested_reason,
            } => {
                let mut diag = PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                );

                // Add: Type 'X' is not assignable to type 'Y' (for return types)
                let return_diag = PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![(*source_return).into(), (*target_return).into()],
                );
                diag = diag.with_related(return_diag);

                if let Some(nested) = nested_reason {
                    let nested_diag = nested.to_diagnostic(*source_return, *target_return);
                    diag = diag.with_related(nested_diag);
                }

                diag
            }

            Self::ParameterTypeMismatch {
                param_index: _,
                source_param,
                target_param,
            } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![source.into(), target.into()],
            )
            .with_related(PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![(*source_param).into(), (*target_param).into()],
            )),

            Self::TooManyParameters {
                source_count,
                target_count,
            } => PendingDiagnostic::error(
                codes::ARG_COUNT_MISMATCH,
                vec![(*target_count).into(), (*source_count).into()],
            ),

            Self::TupleElementMismatch {
                source_count,
                target_count,
            } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![source.into(), target.into()],
            )
            .with_related(PendingDiagnostic::error(
                codes::ARG_COUNT_MISMATCH,
                vec![(*target_count).into(), (*source_count).into()],
            )),

            Self::TupleElementTypeMismatch {
                index: _,
                source_element,
                target_element,
            }
            | Self::ArrayElementMismatch {
                source_element,
                target_element,
            } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![source.into(), target.into()],
            )
            .with_related(PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![(*source_element).into(), (*target_element).into()],
            )),

            Self::IndexSignatureMismatch {
                index_kind: _,
                source_value_type,
                target_value_type,
            } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![source.into(), target.into()],
            )
            .with_related(PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![(*source_value_type).into(), (*target_value_type).into()],
            )),

            Self::NoUnionMemberMatches {
                source_type,
                target_union_members,
            } => {
                const UNION_MEMBER_DIAGNOSTIC_LIMIT: usize = 3;
                let mut diag = PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![(*source_type).into(), target.into()],
                );
                for member in target_union_members
                    .iter()
                    .take(UNION_MEMBER_DIAGNOSTIC_LIMIT)
                {
                    diag.related.push(PendingDiagnostic::error(
                        codes::TYPE_NOT_ASSIGNABLE,
                        vec![(*source_type).into(), (*member).into()],
                    ));
                }
                diag
            }

            Self::NoIntersectionMemberMatches {
                source_type,
                target_type,
            }
            | Self::TypeMismatch {
                source_type,
                target_type,
            }
            | Self::IntrinsicTypeMismatch {
                source_type,
                target_type,
            }
            | Self::LiteralTypeMismatch {
                source_type,
                target_type,
            }
            | Self::ErrorType {
                source_type,
                target_type,
            } => PendingDiagnostic::error(
                codes::TYPE_NOT_ASSIGNABLE,
                vec![(*source_type).into(), (*target_type).into()],
            ),

            Self::NoCommonProperties {
                source_type,
                target_type,
            } => PendingDiagnostic::error(
                codes::NO_COMMON_PROPERTIES,
                vec![(*source_type).into(), (*target_type).into()],
            ),

            Self::RecursionLimitExceeded => {
                // Recursion limit - use the source/target from the call site
                PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                )
            }

            Self::ParameterCountMismatch {
                source_count: _,
                target_count: _,
            } => {
                // Parameter count mismatch
                PendingDiagnostic::error(
                    codes::TYPE_NOT_ASSIGNABLE,
                    vec![source.into(), target.into()],
                )
            }

            Self::ExcessProperty {
                property_name,
                target_type,
            } => {
                // TS2353: Object literal may only specify known properties
                PendingDiagnostic::error(
                    codes::EXCESS_PROPERTY,
                    vec![(*property_name).into(), (*target_type).into()],
                )
            }
        }
    }
}

impl PendingDiagnosticBuilder {
    /// Create an "Argument not assignable" pending diagnostic.
    pub fn argument_not_assignable(arg_type: TypeId, param_type: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::ARG_NOT_ASSIGNABLE,
            vec![arg_type.into(), param_type.into()],
        )
    }

    /// Create an "Expected N arguments but got M" pending diagnostic.
    pub fn argument_count_mismatch(expected: usize, got: usize) -> PendingDiagnostic {
        PendingDiagnostic::error(codes::ARG_COUNT_MISMATCH, vec![expected.into(), got.into()])
    }
}

#[cfg(test)]
impl PendingDiagnosticBuilder {
    /// Create a "Type X is not assignable to type Y" pending diagnostic.
    pub fn type_not_assignable(source: TypeId, target: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::TYPE_NOT_ASSIGNABLE,
            vec![source.into(), target.into()],
        )
    }

    /// Create a "Property X is missing" pending diagnostic.
    pub fn property_missing(prop_name: &str, source: TypeId, target: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::PROPERTY_MISSING,
            vec![prop_name.into(), source.into(), target.into()],
        )
    }

    /// Create a "Property X does not exist" pending diagnostic.
    pub fn property_not_exist(prop_name: &str, type_id: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::PROPERTY_NOT_EXIST,
            vec![prop_name.into(), type_id.into()],
        )
    }

    /// Create a "Cannot find name" pending diagnostic.
    pub fn cannot_find_name(name: &str) -> PendingDiagnostic {
        let code = cannot_find_name_code(name);
        PendingDiagnostic::error(code, vec![name.into()])
    }

    /// Create a "Type is not callable" pending diagnostic.
    pub fn not_callable(type_id: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(codes::NOT_CALLABLE, vec![type_id.into()])
    }

    pub fn this_type_mismatch(expected_this: TypeId, actual_this: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::THIS_TYPE_MISMATCH,
            vec![actual_this.into(), expected_this.into()],
        )
    }

    /// Create a "Cannot assign to readonly property" pending diagnostic.
    pub fn readonly_property(prop_name: &str) -> PendingDiagnostic {
        PendingDiagnostic::error(codes::READONLY_PROPERTY, vec![prop_name.into()])
    }

    /// Create an "Excess property" pending diagnostic.
    pub fn excess_property(prop_name: &str, target: TypeId) -> PendingDiagnostic {
        PendingDiagnostic::error(
            codes::EXCESS_PROPERTY,
            vec![prop_name.into(), target.into()],
        )
    }
}

// =============================================================================
// Spanned Diagnostic Builder
// =============================================================================

/// A diagnostic builder that automatically attaches source spans.
///
/// This builder wraps `DiagnosticBuilder` and requires a file name and
/// position information for each diagnostic.
pub struct SpannedDiagnosticBuilder<'a> {
    builder: DiagnosticBuilder<'a>,
    file: Arc<str>,
}

impl<'a> SpannedDiagnosticBuilder<'a> {
    pub fn new(interner: &'a dyn TypeDatabase, file: impl Into<Arc<str>>) -> Self {
        SpannedDiagnosticBuilder {
            builder: DiagnosticBuilder::new(interner),
            file: file.into(),
        }
    }

    /// Create a spanned diagnostic builder with access to symbol names.
    ///
    /// This prevents "Ref(N)" fallback strings in diagnostic messages by
    /// resolving symbol references to their actual names.
    pub fn with_symbols(
        interner: &'a dyn TypeDatabase,
        symbol_arena: &'a tsz_binder::SymbolArena,
        file: impl Into<Arc<str>>,
    ) -> Self {
        SpannedDiagnosticBuilder {
            builder: DiagnosticBuilder::with_symbols(interner, symbol_arena),
            file: file.into(),
        }
    }

    /// Add access to definition store for `DefId` name resolution.
    ///
    /// This prevents "Lazy(N)" fallback strings in diagnostic messages by
    /// resolving `DefIds` to their type names.
    pub fn with_def_store(mut self, def_store: &'a DefinitionStore) -> Self {
        self.builder = self.builder.with_def_store(def_store);
        self
    }

    /// Create a span for this file.
    pub fn span(&self, start: u32, length: u32) -> SourceSpan {
        SourceSpan::new(std::sync::Arc::clone(&self.file), start, length)
    }

    /// Create a "Type X is not assignable to type Y" diagnostic with span.
    pub fn type_not_assignable(
        &mut self,
        source: TypeId,
        target: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .type_not_assignable(source, target)
            .with_span(self.span(start, length))
    }

    /// Create a "Property X is missing" diagnostic with span.
    pub fn property_missing(
        &mut self,
        prop_name: &str,
        source: TypeId,
        target: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .property_missing(prop_name, source, target)
            .with_span(self.span(start, length))
    }

    /// Create a "Property X does not exist" diagnostic with span.
    pub fn property_not_exist(
        &mut self,
        prop_name: &str,
        type_id: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .property_not_exist(prop_name, type_id)
            .with_span(self.span(start, length))
    }

    /// Create a "Property X does not exist on type Y. Did you mean Z?" diagnostic with span (TS2551).
    pub fn property_not_exist_did_you_mean(
        &mut self,
        prop_name: &str,
        type_id: TypeId,
        suggestion: &str,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .property_not_exist_did_you_mean(prop_name, type_id, suggestion)
            .with_span(self.span(start, length))
    }

    /// Create an "Argument not assignable" diagnostic with span.
    pub fn argument_not_assignable(
        &mut self,
        arg_type: TypeId,
        param_type: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .argument_not_assignable(arg_type, param_type)
            .with_span(self.span(start, length))
    }

    /// Create a "Cannot find name" diagnostic with span.
    pub fn cannot_find_name(&mut self, name: &str, start: u32, length: u32) -> TypeDiagnostic {
        self.builder
            .cannot_find_name(name)
            .with_span(self.span(start, length))
    }

    /// Create an "Expected N arguments" diagnostic with span.
    pub fn argument_count_mismatch(
        &mut self,
        expected: usize,
        got: usize,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .argument_count_mismatch(expected, got)
            .with_span(self.span(start, length))
    }

    /// Create a "Type is not callable" diagnostic with span.
    pub fn not_callable(&mut self, type_id: TypeId, start: u32, length: u32) -> TypeDiagnostic {
        self.builder
            .not_callable(type_id)
            .with_span(self.span(start, length))
    }

    pub fn this_type_mismatch(
        &mut self,
        expected_this: TypeId,
        actual_this: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .this_type_mismatch(expected_this, actual_this)
            .with_span(self.span(start, length))
    }

    /// Create an "Excess property" diagnostic with span.
    pub fn excess_property(
        &mut self,
        prop_name: &str,
        target: TypeId,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .excess_property(prop_name, target)
            .with_span(self.span(start, length))
    }

    /// Create a "Cannot assign to readonly property" diagnostic with span.
    pub fn readonly_property(
        &mut self,
        prop_name: &str,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        self.builder
            .readonly_property(prop_name)
            .with_span(self.span(start, length))
    }

    /// Add a related location to an existing diagnostic.
    pub fn add_related(
        &self,
        diag: TypeDiagnostic,
        message: impl Into<String>,
        start: u32,
        length: u32,
    ) -> TypeDiagnostic {
        diag.with_related(self.span(start, length), message)
    }
}

// =============================================================================
// Diagnostic Conversion
// =============================================================================

/// Convert a solver `TypeDiagnostic` to a checker Diagnostic.
///
/// This allows the solver's diagnostic infrastructure to integrate
/// with the existing checker diagnostic system.
impl TypeDiagnostic {
    /// Convert to a `checker::Diagnostic`.
    ///
    /// Uses the provided `file_name` if no span is present.
    pub fn to_checker_diagnostic(&self, default_file: &str) -> tsz_common::diagnostics::Diagnostic {
        use tsz_common::diagnostics::{
            Diagnostic, DiagnosticCategory, DiagnosticRelatedInformation,
        };

        let (file, start, length) = if let Some(ref span) = self.span {
            (span.file.to_string(), span.start, span.length)
        } else {
            (default_file.to_string(), 0, 0)
        };

        let category = match self.severity {
            DiagnosticSeverity::Error => DiagnosticCategory::Error,
            DiagnosticSeverity::Warning => DiagnosticCategory::Warning,
            DiagnosticSeverity::Suggestion => DiagnosticCategory::Suggestion,
            DiagnosticSeverity::Message => DiagnosticCategory::Message,
        };

        let related_information: Vec<DiagnosticRelatedInformation> = self
            .related
            .iter()
            .map(|rel| DiagnosticRelatedInformation {
                file: rel.span.file.to_string(),
                start: rel.span.start,
                length: rel.span.length,
                message_text: rel.message.clone(),
                category: DiagnosticCategory::Message,
                code: 0,
            })
            .collect();

        Diagnostic {
            file,
            start,
            length,
            message_text: self.message.clone(),
            category,
            code: self.code,
            related_information,
        }
    }
}

// =============================================================================
// Source Location Tracker
// =============================================================================

/// Tracks source locations for AST nodes during type checking.
///
/// This struct provides a convenient way to associate type checking
/// operations with their source locations for diagnostic generation.
#[derive(Clone)]
pub struct SourceLocation {
    /// File name
    pub file: Arc<str>,
    /// Start position (byte offset)
    pub start: u32,
    /// End position (byte offset)
    pub end: u32,
}

impl SourceLocation {
    pub fn new(file: impl Into<Arc<str>>, start: u32, end: u32) -> Self {
        Self {
            file: file.into(),
            start,
            end,
        }
    }

    /// Get the length of this location.
    pub const fn length(&self) -> u32 {
        self.end.saturating_sub(self.start)
    }

    /// Convert to a `SourceSpan`.
    pub fn to_span(&self) -> SourceSpan {
        SourceSpan::new(std::sync::Arc::clone(&self.file), self.start, self.length())
    }
}

/// A diagnostic collector that accumulates diagnostics with source tracking.
pub struct DiagnosticCollector<'a> {
    interner: &'a dyn TypeDatabase,
    file: Arc<str>,
    diagnostics: Vec<TypeDiagnostic>,
}

impl<'a> DiagnosticCollector<'a> {
    pub fn new(interner: &'a dyn TypeDatabase, file: impl Into<Arc<str>>) -> Self {
        DiagnosticCollector {
            interner,
            file: file.into(),
            diagnostics: Vec::new(),
        }
    }

    /// Get the collected diagnostics.
    pub fn diagnostics(&self) -> &[TypeDiagnostic] {
        &self.diagnostics
    }

    /// Take the collected diagnostics.
    pub fn take_diagnostics(&mut self) -> Vec<TypeDiagnostic> {
        std::mem::take(&mut self.diagnostics)
    }

    /// Report a type not assignable error.
    pub fn type_not_assignable(&mut self, source: TypeId, target: TypeId, loc: &SourceLocation) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder
            .type_not_assignable(source, target)
            .with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Report a property missing error.
    pub fn property_missing(
        &mut self,
        prop_name: &str,
        source: TypeId,
        target: TypeId,
        loc: &SourceLocation,
    ) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder
            .property_missing(prop_name, source, target)
            .with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Report a property not exist error.
    pub fn property_not_exist(&mut self, prop_name: &str, type_id: TypeId, loc: &SourceLocation) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder
            .property_not_exist(prop_name, type_id)
            .with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Report an argument not assignable error.
    pub fn argument_not_assignable(
        &mut self,
        arg_type: TypeId,
        param_type: TypeId,
        loc: &SourceLocation,
    ) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder
            .argument_not_assignable(arg_type, param_type)
            .with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Report a cannot find name error.
    pub fn cannot_find_name(&mut self, name: &str, loc: &SourceLocation) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder.cannot_find_name(name).with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Report an argument count mismatch error.
    pub fn argument_count_mismatch(&mut self, expected: usize, got: usize, loc: &SourceLocation) {
        let mut builder = DiagnosticBuilder::new(self.interner);
        let diag = builder
            .argument_count_mismatch(expected, got)
            .with_span(loc.to_span());
        self.diagnostics.push(diag);
    }

    /// Convert all collected diagnostics to checker diagnostics.
    pub fn to_checker_diagnostics(&self) -> Vec<tsz_common::diagnostics::Diagnostic> {
        self.diagnostics
            .iter()
            .map(|d| d.to_checker_diagnostic(&self.file))
            .collect()
    }
}

#[cfg(test)]
use crate::types::*;

#[cfg(test)]
#[path = "../tests/diagnostics_tests.rs"]
mod tests;