wdl_analysis/

diagnostics.rs

//! Module for all diagnostic creation functions.

use std::fmt;

use wdl_ast::AstToken;
use wdl_ast::Diagnostic;
use wdl_ast::Ident;
use wdl_ast::Span;
use wdl_ast::SupportedVersion;
use wdl_ast::TreeNode;
use wdl_ast::TreeToken;
use wdl_ast::Version;
use wdl_ast::v1::PlaceholderOption;

use crate::MisleadingDeclarationOrderRule;
use crate::UnnecessaryFunctionCall;
use crate::UnusedCallRule;
use crate::UnusedDeclarationRule;
use crate::UnusedImportRule;
use crate::UnusedInputRule;
use crate::types::CallKind;
use crate::types::CallType;
use crate::types::Type;
use crate::types::display_types;
use crate::types::v1::ComparisonOperator;
use crate::types::v1::NumericOperator;

/// Utility type to represent an input or an output.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Io {
    /// The I/O is an input.
    Input,
    /// The I/O is an output.
    Output,
}

impl fmt::Display for Io {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Input => write!(f, "input"),
            Self::Output => write!(f, "output"),
        }
    }
}

/// Represents the context for diagnostic reporting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Context {
    /// The name is a namespace introduced by an imported document.
    Namespace(Span),
    /// The name is a workflow name.
    Workflow(Span),
    /// The name is a task name.
    Task(Span),
    /// The name is a struct name.
    Struct(Span),
    /// The name is a struct member name.
    StructMember(Span),
    /// The name is an enum name.
    Enum(Span),
    /// The name is an enum choice name.
    EnumChoice(Span),
    /// A name from a scope.
    Name(NameContext),
}

impl Context {
    /// Gets the span of the name.
    fn span(&self) -> Span {
        match self {
            Self::Namespace(s) => *s,
            Self::Workflow(s) => *s,
            Self::Task(s) => *s,
            Self::Struct(s) => *s,
            Self::StructMember(s) => *s,
            Self::Enum(s) => *s,
            Self::EnumChoice(s) => *s,
            Self::Name(n) => n.span(),
        }
    }
}

impl fmt::Display for Context {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Namespace(_) => write!(f, "namespace"),
            Self::Workflow(_) => write!(f, "workflow"),
            Self::Task(_) => write!(f, "task"),
            Self::Struct(_) => write!(f, "struct"),
            Self::StructMember(_) => write!(f, "struct member"),
            Self::Enum(_) => write!(f, "enum"),
            Self::EnumChoice(_) => write!(f, "enum choice"),
            Self::Name(n) => n.fmt(f),
        }
    }
}

/// Represents the context of a name in a scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NameContext {
    /// The name was introduced by an task or workflow input.
    Input(Span),
    /// The name was introduced by an task or workflow output.
    Output(Span),
    /// The name was introduced by a private declaration.
    Decl(Span),
    /// The name was introduced by a workflow call statement.
    Call(Span),
    /// The name was introduced by a variable in workflow scatter statement.
    ScatterVariable(Span),
}

impl NameContext {
    /// Gets the span of the name.
    pub fn span(&self) -> Span {
        match self {
            Self::Input(s) => *s,
            Self::Output(s) => *s,
            Self::Decl(s) => *s,
            Self::Call(s) => *s,
            Self::ScatterVariable(s) => *s,
        }
    }
}

impl fmt::Display for NameContext {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Input(_) => write!(f, "input"),
            Self::Output(_) => write!(f, "output"),
            Self::Decl(_) => write!(f, "declaration"),
            Self::Call(_) => write!(f, "call"),
            Self::ScatterVariable(_) => write!(f, "scatter variable"),
        }
    }
}

impl From<NameContext> for Context {
    fn from(context: NameContext) -> Self {
        Self::Name(context)
    }
}

/// Creates a "name conflict" diagnostic.
pub fn name_conflict(name: &str, conflicting: Context, first: Context) -> Diagnostic {
    Diagnostic::error(format!("conflicting {conflicting} name `{name}`"))
        .with_label(
            format!("this {conflicting} conflicts with a previously used name"),
            conflicting.span(),
        )
        .with_label(
            format!("the {first} with the conflicting name is here"),
            first.span(),
        )
}

/// Constructs a "cannot index" diagnostic.
pub fn cannot_index(actual: &Type, span: Span) -> Diagnostic {
    Diagnostic::error("indexing is only allowed on `Array` and `Map` types")
        .with_label(format!("this is {actual:#}"), span)
}

/// Creates an "unknown name" diagnostic.
pub fn unknown_name(name: &str, span: Span) -> Diagnostic {
    // Handle special case names here
    let message = match name {
        "task" => "the `task` variable may only be used within a task command section or task \
                   output section using WDL 1.2 or later, or within a task requirements, task \
                   hints, or task runtime section using WDL 1.3 or later"
            .to_string(),
        _ => format!("unknown name `{name}`"),
    };

    Diagnostic::error(message).with_highlight(span)
}

/// Creates a "self-referential" diagnostic.
pub fn self_referential(name: &str, span: Span, reference: Span) -> Diagnostic {
    Diagnostic::error(format!("declaration of `{name}` is self-referential"))
        .with_label("self-reference is here", reference)
        .with_highlight(span)
}

/// Creates a "task reference cycle" diagnostic.
pub fn task_reference_cycle(
    from: &impl fmt::Display,
    from_span: Span,
    to: &str,
    to_span: Span,
) -> Diagnostic {
    Diagnostic::error("a name reference cycle was detected")
        .with_label(
            format!("ensure this expression does not directly or indirectly refer to {from}"),
            to_span,
        )
        .with_label(format!("a reference back to `{to}` is here"), from_span)
}

/// Creates a "workflow reference cycle" diagnostic.
pub fn workflow_reference_cycle(
    from: &impl fmt::Display,
    from_span: Span,
    to: &str,
    to_span: Span,
) -> Diagnostic {
    Diagnostic::error("a name reference cycle was detected")
        .with_label(format!("this name depends on {from}"), to_span)
        .with_label(format!("a reference back to `{to}` is here"), from_span)
}

/// Creates a "call conflict" diagnostic.
pub fn call_conflict<T: TreeToken>(
    name: &Ident<T>,
    first: NameContext,
    suggest_fix: bool,
) -> Diagnostic {
    let diagnostic = Diagnostic::error(format!(
        "conflicting call name `{name}`",
        name = name.text()
    ))
    .with_label(
        "this call name conflicts with a previously used name",
        name.span(),
    )
    .with_label(
        format!("the {first} with the conflicting name is here"),
        first.span(),
    );

    if suggest_fix {
        diagnostic.with_fix("add an `as` clause to the call to specify a different name")
    } else {
        diagnostic
    }
}

/// Creates a "namespace conflict" diagnostic.
pub fn namespace_conflict(
    name: &str,
    conflicting: Span,
    first: Span,
    suggest_fix: bool,
) -> Diagnostic {
    let diagnostic = Diagnostic::error(format!("conflicting import namespace `{name}`"))
        .with_label("this conflicts with another import namespace", conflicting)
        .with_label(
            "the conflicting import namespace was introduced here",
            first,
        );

    if suggest_fix {
        diagnostic.with_fix("add an `as` clause to the import to specify a namespace")
    } else {
        diagnostic
    }
}

/// Creates an "unknown namespace" diagnostic.
pub fn unknown_namespace<T: TreeToken>(ns: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!("unknown namespace `{ns}`", ns = ns.text())).with_highlight(ns.span())
}

/// Creates an "only one namespace" diagnostic.
pub fn only_one_namespace(span: Span) -> Diagnostic {
    Diagnostic::error("only one namespace may be specified in a call statement")
        .with_highlight(span)
}

/// Creates an "import cycle" diagnostic.
pub fn import_cycle(span: Span) -> Diagnostic {
    Diagnostic::error("import introduces a dependency cycle")
        .with_label("this import has been skipped to break the cycle", span)
}

/// Creates an "import failure" diagnostic.
pub fn import_failure(uri: &str, error: &anyhow::Error, span: Span) -> Diagnostic {
    Diagnostic::error(format!("failed to import `{uri}`: {error:#}")).with_highlight(span)
}

/// Creates an "incompatible import" diagnostic.
pub fn incompatible_import(
    import_version: &str,
    import_span: Span,
    importer_version: &Version,
) -> Diagnostic {
    Diagnostic::error("imported document has incompatible version")
        .with_label(
            format!("the imported document is version `{import_version}`"),
            import_span,
        )
        .with_label(
            format!(
                "the importing document is version `{version}`",
                version = importer_version.text()
            ),
            importer_version.span(),
        )
}

/// Creates an "import missing version" diagnostic.
pub fn import_missing_version(span: Span) -> Diagnostic {
    Diagnostic::error("imported document is missing a version statement").with_highlight(span)
}

/// Creates an "invalid relative import" diagnostic.
pub fn invalid_relative_import(error: &url::ParseError, span: Span) -> Diagnostic {
    Diagnostic::error(format!("{error:#}")).with_highlight(span)
}

/// Creates a "struct not in document" diagnostic.
pub fn struct_not_in_document<T: TreeToken>(name: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "a struct named `{name}` does not exist in the imported document",
        name = name.text()
    ))
    .with_label("this struct does not exist", name.span())
}

/// Creates an "imported struct conflict" diagnostic.
pub fn imported_struct_conflict(
    name: &str,
    conflicting: Span,
    first: Span,
    suggest_fix: bool,
) -> Diagnostic {
    let diagnostic = Diagnostic::error(format!("conflicting struct name `{name}`"))
        .with_label(
            "this import introduces a conflicting definition",
            conflicting,
        )
        .with_label("the first definition was introduced by this import", first);

    if suggest_fix {
        diagnostic.with_fix("add an `alias` clause to the import to specify a different name")
    } else {
        diagnostic
    }
}

/// Creates a "struct conflicts with import" diagnostic.
pub fn struct_conflicts_with_import(name: &str, conflicting: Span, import: Span) -> Diagnostic {
    Diagnostic::error(format!("conflicting struct name `{name}`"))
        .with_label("this name conflicts with an imported struct", conflicting)
        .with_label("the import that introduced the struct is here", import)
        .with_fix(
            "either rename the struct or use an `alias` clause on the import with a different name",
        )
}

/// Creates an "imported enum conflict" diagnostic.
pub fn imported_enum_conflict(
    name: &str,
    conflicting: Span,
    first: Span,
    suggest_fix: bool,
) -> Diagnostic {
    let diagnostic = Diagnostic::error(format!("conflicting enum name `{name}`"))
        .with_label(
            "this import introduces a conflicting definition",
            conflicting,
        )
        .with_label("the first definition was introduced by this import", first);

    if suggest_fix {
        diagnostic.with_fix("add an `alias` clause to the import to specify a different name")
    } else {
        diagnostic
    }
}

/// Creates an "enum conflicts with import" diagnostic.
pub fn enum_conflicts_with_import(name: &str, conflicting: Span, import: Span) -> Diagnostic {
    Diagnostic::error(format!("conflicting enum name `{name}`"))
        .with_label("this name conflicts with an imported enum", conflicting)
        .with_label("the import that introduced the enum is here", import)
        .with_fix(
            "either rename the enum or use an `alias` clause on the import with a different name",
        )
}

/// Creates a "duplicate workflow" diagnostic.
pub fn duplicate_workflow<T: TreeToken>(name: &Ident<T>, first: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "cannot define workflow `{name}` as only one workflow is allowed per source file",
        name = name.text(),
    ))
    .with_label("consider moving this workflow to a new file", name.span())
    .with_label("first workflow is defined here", first)
}

/// Creates a "recursive struct" diagnostic.
pub fn recursive_struct(name: &str, span: Span, member: Span) -> Diagnostic {
    Diagnostic::error(format!("struct `{name}` has a recursive definition"))
        .with_highlight(span)
        .with_label("this struct member participates in the recursion", member)
}

/// Creates a "recursive enum" diagnostic.
pub fn recursive_enum(name: &str, span: Span, ty: &str) -> Diagnostic {
    // Unlike `recursive_struct`, which labels individual members, an `enum` has a
    // single type for all of its choices. Just highlight the `enum` name, as
    // its type as a *whole* is recursive.
    Diagnostic::error(format!("enum `{name}` has a recursive definition"))
        .with_highlight(span)
        .with_help(format!("the type `{ty}` participates in the recursion"))
}

/// Creates an "unknown type" diagnostic.
pub fn unknown_type(name: &str, span: Span) -> Diagnostic {
    Diagnostic::error(format!("unknown type name `{name}`")).with_highlight(span)
}

/// Creates a "type mismatch" diagnostic.
pub fn type_mismatch(
    expected: &Type,
    expected_span: Span,
    actual: &Type,
    actual_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected {expected:#}, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
    .with_label(format!("this expects {expected:#}"), expected_span)
}

/// Creates a "non-empty array assignment" diagnostic.
pub fn non_empty_array_assignment(expected_span: Span, actual_span: Span) -> Diagnostic {
    Diagnostic::error("cannot assign an empty array to a non-empty array type")
        .with_label("this is an empty array", actual_span)
        .with_label("this expects a non-empty array", expected_span)
}

/// Creates a "call input type mismatch" diagnostic.
pub fn call_input_type_mismatch<T: TreeToken>(
    name: &Ident<T>,
    expected: &Type,
    actual: &Type,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected {expected:#}, but found {actual:#}",
    ))
    .with_label(
        format!(
            "input `{name}` is {expected:#}, but name `{name}` is {actual:#}",
            name = name.text(),
        ),
        name.span(),
    )
}

/// Creates a "no common type" diagnostic for arrays, maps, and scope unions.
///
/// This is called if the elements of a map or an array do not have a common
/// type.
pub fn no_common_type(
    expected: &Type,
    expected_span: Span,
    actual: &Type,
    actual_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: a type common to both {expected:#} and {actual:#} does not exist"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
    .with_label(
        format!("this and all prior elements had a common {expected:#}"),
        expected_span,
    )
}

/// Creates a "multiple type mismatch" diagnostic.
pub fn multiple_type_mismatch(
    expected: &[Type],
    expected_span: Span,
    actual: &Type,
    actual_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected {expected:#}, but found {actual:#}",
        expected = display_types(expected),
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
    .with_label(
        format!(
            "this expects {expected:#}",
            expected = display_types(expected)
        ),
        expected_span,
    )
}

/// Creates a "not a task member" diagnostic.
pub fn not_a_task_member<T: TreeToken>(member: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "the `task` variable does not have a member named `{member}`",
        member = member.text()
    ))
    .with_highlight(member.span())
}

/// Creates a "not a task.previous member" diagnostic.
pub fn not_a_previous_task_data_member<T: TreeToken>(member: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "`task.previous` does not have a member named `{member}`",
        member = member.text()
    ))
    .with_highlight(member.span())
}

/// Creates a "not a struct" diagnostic.
pub fn not_a_struct<T: TreeToken>(member: &Ident<T>, input: bool) -> Diagnostic {
    Diagnostic::error(format!(
        "{kind} `{member}` is not a struct",
        kind = if input { "input" } else { "struct member" },
        member = member.text()
    ))
    .with_highlight(member.span())
}

/// Creates a "not a struct member" diagnostic.
pub fn not_a_struct_member<T: TreeToken>(name: &str, member: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "struct `{name}` does not have a member named `{member}`",
        member = member.text()
    ))
    .with_highlight(member.span())
}

/// Creates a "not an enum choice" diagnostic.
pub fn not_an_enum_choice<T: TreeToken>(name: &str, choice: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "enum `{name}` does not have a choice named `{choice}`",
        choice = choice.text()
    ))
    .with_highlight(choice.span())
}

/// Creates a "non-literal enum value" diagnostic.
pub fn non_literal_enum_value(span: Span) -> Diagnostic {
    Diagnostic::error("enum choice value must be a literal expression")
        .with_highlight(span)
        .with_fix(
            "enum values must be literal expressions only (string literals, numeric literals, \
             collection literals, or struct literals); string interpolation, variable references, \
             and computed expressions are not allowed",
        )
}

/// Creates a "not a pair accessor" diagnostic.
pub fn not_a_pair_accessor<T: TreeToken>(name: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!(
        "cannot access a pair with name `{name}`",
        name = name.text()
    ))
    .with_highlight(name.span())
    .with_fix("use `left` or `right` to access a pair")
}

/// Creates a "missing struct members" diagnostic.
pub fn missing_struct_members<T: TreeToken>(
    name: &Ident<T>,
    count: usize,
    members: &str,
) -> Diagnostic {
    Diagnostic::error(format!(
        "struct `{name}` requires a value for member{s} {members}",
        name = name.text(),
        s = if count > 1 { "s" } else { "" },
    ))
    .with_highlight(name.span())
}

/// Creates a "map key not primitive" diagnostic.
pub fn map_key_not_primitive(span: Span, actual: &Type) -> Diagnostic {
    Diagnostic::error("expected map key to be a non-optional primitive type")
        .with_highlight(span)
        .with_label(format!("this is {actual:#}"), span)
}

/// Creates a "if conditional mismatch" diagnostic.
pub fn if_conditional_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected `if` conditional expression to be type `Boolean`, but found \
         {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates an "else if not supported" diagnostic.
pub fn else_if_not_supported(version: SupportedVersion, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "`else if` conditional clauses are not supported in WDL v{version}"
    ))
    .with_label("this `else if` is not supported", span)
    .with_fix("use WDL v1.3 or higher to use `else if` conditional clauses")
}

/// Creates an "else not supported" diagnostic.
pub fn else_not_supported(version: SupportedVersion, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "`else` conditional clauses are not supported in WDL v{version}"
    ))
    .with_label("this `else` is not supported", span)
    .with_fix("use WDL v1.3 or higher to use `else` conditional clauses")
}

/// Creates an "enum not supported" diagnostic.
pub fn enum_not_supported(version: SupportedVersion, span: Span) -> Diagnostic {
    Diagnostic::error(format!("enums are not supported in WDL v{version}"))
        .with_label("this enum is not supported", span)
        .with_fix("use WDL v1.3 or higher to use enums")
}

/// Creates a "logical not mismatch" diagnostic.
pub fn logical_not_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected `logical not` operand to be type `Boolean`, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates a "negation mismatch" diagnostic.
pub fn negation_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected negation operand to be type `Int` or `Float`, but found \
         {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates a "logical or mismatch" diagnostic.
pub fn logical_or_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected `logical or` operand to be type `Boolean`, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates a "logical and mismatch" diagnostic.
pub fn logical_and_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected `logical and` operand to be type `Boolean`, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates a "comparison mismatch" diagnostic.
pub fn comparison_mismatch(
    op: ComparisonOperator,
    span: Span,
    lhs: &Type,
    lhs_span: Span,
    rhs: &Type,
    rhs_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: operator `{op}` cannot compare {lhs:#} to {rhs:#}"
    ))
    .with_highlight(span)
    .with_label(format!("this is {lhs:#}"), lhs_span)
    .with_label(format!("this is {rhs:#}"), rhs_span)
}

/// Creates a "numeric mismatch" diagnostic.
pub fn numeric_mismatch(
    op: NumericOperator,
    span: Span,
    lhs: &Type,
    lhs_span: Span,
    rhs: &Type,
    rhs_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: {op} operator is not supported for {lhs:#} and {rhs:#}"
    ))
    .with_highlight(span)
    .with_label(format!("this is {lhs:#}"), lhs_span)
    .with_label(format!("this is {rhs:#}"), rhs_span)
}

/// Creates a "string concat mismatch" diagnostic.
pub fn string_concat_mismatch(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: string concatenation is not supported for {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), actual_span)
}

/// Creates an "unknown function" diagnostic.
pub fn unknown_function(name: &str, span: Span) -> Diagnostic {
    Diagnostic::error(format!("unknown function `{name}`")).with_label(
        "the WDL standard library does not have a function with this name",
        span,
    )
}

/// Creates an "unsupported function" diagnostic.
pub fn unsupported_function(minimum: SupportedVersion, name: &str, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "this use of function `{name}` requires a minimum WDL version of {minimum}"
    ))
    .with_highlight(span)
}

/// Creates a "too few arguments" diagnostic.
pub fn too_few_arguments(name: &str, span: Span, minimum: usize, count: usize) -> Diagnostic {
    Diagnostic::error(format!(
        "function `{name}` requires at least {minimum} argument{s} but {count} {v} supplied",
        s = if minimum == 1 { "" } else { "s" },
        v = if count == 1 { "was" } else { "were" },
    ))
    .with_highlight(span)
}

/// Creates a "too many arguments" diagnostic.
pub fn too_many_arguments(
    name: &str,
    span: Span,
    maximum: usize,
    count: usize,
    excessive: impl Iterator<Item = Span>,
) -> Diagnostic {
    let mut diagnostic = Diagnostic::error(format!(
        "function `{name}` requires no more than {maximum} argument{s} but {count} {v} supplied",
        s = if maximum == 1 { "" } else { "s" },
        v = if count == 1 { "was" } else { "were" },
    ))
    .with_highlight(span);

    for span in excessive {
        diagnostic = diagnostic.with_label("this argument is unexpected", span);
    }

    diagnostic
}

/// Constructs an "argument type mismatch" diagnostic.
pub fn argument_type_mismatch(name: &str, expected: &str, actual: &Type, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: argument to function `{name}` expects {expected}, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), span)
}

/// Constructs an "ambiguous argument" diagnostic.
pub fn ambiguous_argument(name: &str, span: Span, first: &str, second: &str) -> Diagnostic {
    Diagnostic::error(format!(
        "ambiguous call to function `{name}` with conflicting signatures `{first}` and `{second}`",
    ))
    .with_highlight(span)
}

/// Constructs an "index type mismatch" diagnostic.
pub fn index_type_mismatch(expected: &Type, actual: &Type, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected index to be {expected:#}, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), span)
}

/// Constructs an "type is not array" diagnostic.
pub fn type_is_not_array(actual: &Type, span: Span) -> Diagnostic {
    Diagnostic::error(format!(
        "type mismatch: expected an array type, but found {actual:#}"
    ))
    .with_label(format!("this is {actual:#}"), span)
}

/// Constructs a "cannot access" diagnostic.
pub fn cannot_access(actual: &Type, actual_span: Span) -> Diagnostic {
    Diagnostic::error(format!("cannot access {actual:#}"))
        .with_label(format!("this is {actual:#}"), actual_span)
}

/// Constructs a "cannot coerce to string" diagnostic.
pub fn cannot_coerce_to_string(actual: &Type, span: Span) -> Diagnostic {
    Diagnostic::error(format!("cannot coerce {actual:#} to type `String`"))
        .with_label(format!("this is {actual:#}"), span)
}

/// Creates an "unknown task or workflow" diagnostic.
pub fn unknown_task_or_workflow(namespace: Option<Span>, name: &str, span: Span) -> Diagnostic {
    let mut diagnostic =
        Diagnostic::error(format!("unknown task or workflow `{name}`")).with_highlight(span);

    if let Some(namespace) = namespace {
        diagnostic = diagnostic.with_label(
            format!("this namespace does not have a task or workflow named `{name}`"),
            namespace,
        );
    }

    diagnostic
}

/// Creates an "unknown call input/output" diagnostic.
pub fn unknown_call_io<T: TreeToken>(call: &CallType, name: &Ident<T>, io: Io) -> Diagnostic {
    Diagnostic::error(format!(
        "{kind} `{call}` does not have an {io} named `{name}`",
        kind = call.kind(),
        call = call.name(),
        name = name.text(),
    ))
    .with_highlight(name.span())
}

/// Creates an "unknown task input/output name" diagnostic.
pub fn unknown_task_io<T: TreeToken>(task_name: &str, name: &Ident<T>, io: Io) -> Diagnostic {
    Diagnostic::error(format!(
        "task `{task_name}` does not have an {io} named `{name}`",
        name = name.text(),
    ))
    .with_highlight(name.span())
}

/// Creates a "recursive workflow call" diagnostic.
pub fn recursive_workflow_call(name: &str, span: Span) -> Diagnostic {
    Diagnostic::error(format!("cannot recursively call workflow `{name}`")).with_highlight(span)
}

/// Creates a "missing call input" diagnostic.
pub fn missing_call_input<T: TreeToken>(
    kind: CallKind,
    target: &Ident<T>,
    input: &str,
    nested_inputs_allowed: bool,
) -> Diagnostic {
    let message = format!(
        "missing required call input `{input}` for {kind} `{target}`",
        target = target.text(),
    );

    if nested_inputs_allowed {
        Diagnostic::warning(message).with_highlight(target.span())
    } else {
        Diagnostic::error(message).with_highlight(target.span())
    }
}

/// Creates an "unused import" diagnostic.
pub fn unused_import(name: &str, span: Span) -> Diagnostic {
    Diagnostic::warning(format!("unused import namespace `{name}`"))
        .with_rule(UnusedImportRule::ID)
        .with_highlight(span)
}

/// Creates an "unused input" diagnostic.
pub fn unused_input(name: &str, span: Span) -> Diagnostic {
    Diagnostic::warning(format!("unused input `{name}`"))
        .with_rule(UnusedInputRule::ID)
        .with_highlight(span)
}

/// Creates an "unused declaration" diagnostic.
pub fn unused_declaration(name: &str, span: Span) -> Diagnostic {
    Diagnostic::warning(format!("unused declaration `{name}`"))
        .with_rule(UnusedDeclarationRule::ID)
        .with_highlight(span)
}

/// Creates a "misleading declaration order" diagnostic.
pub fn misleading_declaration_order(name: &str, span: Span) -> Diagnostic {
    Diagnostic::warning("variable declaration appears after the `command` section")
        .with_rule(MisleadingDeclarationOrderRule::ID)
        .with_highlight(span)
        .with_help(
            "this is visually misleading; tasks are evaluated in dependency order, not \
             top-to-bottom",
        )
        .with_fix(format!(
            "move the declaration of `{name}` above the `command` section"
        ))
}

/// Creates an "unused call" diagnostic.
pub fn unused_call(name: &str, span: Span) -> Diagnostic {
    Diagnostic::warning(format!("unused call `{name}`"))
        .with_rule(UnusedCallRule::ID)
        .with_highlight(span)
}

/// Creates an "unnecessary function call" diagnostic.
pub fn unnecessary_function_call(
    name: &str,
    span: Span,
    label: &str,
    label_span: Span,
) -> Diagnostic {
    Diagnostic::warning(format!("unnecessary call to function `{name}`"))
        .with_rule(UnnecessaryFunctionCall::ID)
        .with_highlight(span)
        .with_label(label.to_string(), label_span)
}

/// Generates a diagnostic error message when a placeholder option has a type
/// mismatch.
pub fn invalid_placeholder_option<N: TreeNode>(
    ty: &Type,
    span: Span,
    option: &PlaceholderOption<N>,
) -> Diagnostic {
    let message = match option {
        PlaceholderOption::Sep(_) => format!(
            "type mismatch for placeholder option `sep`: expected type `Array[P]` where P: any \
             primitive type, but found {ty:#}"
        ),
        PlaceholderOption::Default(_) => format!(
            "type mismatch for placeholder option `default`: expected any primitive type, but \
             found {ty:#}"
        ),
        PlaceholderOption::TrueFalse(_) => format!(
            "type mismatch for placeholder option `true/false`: expected type `Boolean`, but \
             found {ty:#}"
        ),
    };

    Diagnostic::error(message).with_label(format!("this is {ty:#}"), span)
}

/// Creates an invalid regex pattern diagnostic.
pub fn invalid_regex_pattern(
    function: &str,
    pattern: &str,
    error: &regex::Error,
    span: Span,
) -> Diagnostic {
    Diagnostic::error(format!(
        "invalid regular expression `{pattern}` used in function `{function}`: {error}"
    ))
    .with_label("invalid regular expression", span)
}

/// Creates a "not a custom type" diagnostic.
pub fn not_a_custom_type<T: TreeToken>(name: &Ident<T>) -> Diagnostic {
    Diagnostic::error(format!("`{}` is not a custom type", name.text())).with_label(
        "only struct and enum types can be referenced as values",
        name.span(),
    )
}

/// Creates a "no common inferred type for enum" diagnostic.
///
/// This diagnostic occurs during enum type calculation when no common type can
/// be inferred from the choice types.
pub fn no_common_inferred_type_for_enum(
    enum_name: &str,
    common_type: &Type,
    common_span: Span,
    discordant_type: &Type,
    discordant_span: Span,
) -> Diagnostic {
    Diagnostic::error(format!("cannot infer a common type for enum `{enum_name}`"))
        .with_label(
            format!(
                "this is the first choice with {discordant_type:#} that has no common type with \
                 {common_type:#}"
            ),
            discordant_span,
        )
        .with_label(
            format!("this is the last choice with a common {common_type:#}"),
            common_span,
        )
}

/// Creates an "enum choice does not coerce to type" diagnostic.
pub fn enum_choice_does_not_coerce_to_type(
    enum_name: &str,
    enum_span: Span,
    choice_name: &str,
    choice_span: Span,
    expected: &Type,
    actual: &Type,
) -> Diagnostic {
    Diagnostic::error(format!(
        "cannot coerce choice `{choice_name}` in enum `{enum_name}` from {actual:#} to \
         {expected:#}"
    ))
    .with_label(format!("this is the `{enum_name}` enum"), enum_span)
    .with_label(format!("this is the `{choice_name}` choice"), choice_span)
    .with_fix(format!(
        "change the value to something that coerces to {expected:#} or explicitly set the enum's \
         inner type"
    ))
}