lintel_diagnostics/

diagnostics.rs

use miette::{Diagnostic, LabeledSpan, NamedSource, SourceSpan};
use thiserror::Error;

/// Default label text used for span annotations when no specific instance path
/// is available. Checked by reporters to decide whether to show the path suffix.
pub const DEFAULT_LABEL: &str = "here";

/// A validation diagnostic with a granular error code (e.g. `validation(required)`).
///
/// Implements [`Diagnostic`] manually so the code can be computed at runtime
/// from the [`ValidationErrorKind`](lintel_validation_cache::ValidationErrorKind).
#[derive(Debug, Error)]
#[error("{message}")]
pub struct ValidationDiagnostic {
    pub src: NamedSource<String>,
    pub span: SourceSpan,
    pub schema_span: SourceSpan,
    pub path: String,
    pub instance_path: String,
    pub label: String,
    pub message: String,
    /// Schema URI this file was validated against (shown as a clickable link
    /// in terminals for remote schemas).
    pub schema_url: String,
    /// JSON Schema path that triggered the error (e.g. `/properties/jobs/oneOf`).
    pub schema_path: String,
    /// Granular diagnostic code (e.g. `validation(required)`).
    pub validation_code: String,
}

impl Diagnostic for ValidationDiagnostic {
    fn code<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
        Some(Box::new(&self.validation_code))
    }

    fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
        Some(Box::new(&self.schema_url))
    }

    fn help<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
        Some(Box::new(format!(
            "run `lintel explain --file {}` to see the full schema definition",
            self.path
        )))
    }

    fn source_code(&self) -> Option<&dyn miette::SourceCode> {
        Some(&self.src)
    }

    fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>> {
        Some(Box::new(
            [
                LabeledSpan::new(
                    Some(self.label.clone()),
                    self.span.offset(),
                    self.span.len(),
                ),
                LabeledSpan::new(
                    Some(format!("from {}", self.schema_url)),
                    self.schema_span.offset(),
                    self.schema_span.len(),
                ),
            ]
            .into_iter(),
        ))
    }
}

/// A single diagnostic produced during validation, formatting, or parsing.
#[derive(Debug, Error, Diagnostic)]
pub enum LintelDiagnostic {
    #[error("{message}")]
    #[diagnostic(code(parse))]
    Parse {
        #[source_code]
        src: NamedSource<String>,
        #[label("here")]
        span: SourceSpan,
        message: String,
    },

    #[error(transparent)]
    #[diagnostic(transparent)]
    Validation(ValidationDiagnostic),

    #[error("{path}: mismatched $schema on line {line_number}: {message}")]
    #[diagnostic(code(jsonl::schema_mismatch))]
    SchemaMismatch {
        path: String,
        line_number: usize,
        message: String,
    },

    #[error("{path}: {message}")]
    #[diagnostic(code(io))]
    Io { path: String, message: String },

    #[error("{path}: {message}")]
    #[diagnostic(code(schema::fetch))]
    SchemaFetch { path: String, message: String },

    #[error("{path}: {message}")]
    #[diagnostic(code(schema::compile))]
    SchemaCompile { path: String, message: String },

    #[error("Formatter would have printed the following content:\n\n{styled_path}\n\n{diff}")]
    #[diagnostic(
        code(format),
        help("run `lintel check --fix` or `lintel format` to fix formatting")
    )]
    Format {
        path: String,
        styled_path: String,
        diff: String,
    },
}

impl LintelDiagnostic {
    /// File path associated with this error.
    pub fn path(&self) -> &str {
        match self {
            LintelDiagnostic::Parse { src, .. } => src.name(),
            LintelDiagnostic::Validation(v) => &v.path,
            LintelDiagnostic::SchemaMismatch { path, .. }
            | LintelDiagnostic::Io { path, .. }
            | LintelDiagnostic::SchemaFetch { path, .. }
            | LintelDiagnostic::SchemaCompile { path, .. }
            | LintelDiagnostic::Format { path, .. } => path,
        }
    }

    /// Human-readable error message.
    pub fn message(&self) -> &str {
        match self {
            LintelDiagnostic::Parse { message, .. }
            | LintelDiagnostic::SchemaMismatch { message, .. }
            | LintelDiagnostic::Io { message, .. }
            | LintelDiagnostic::SchemaFetch { message, .. }
            | LintelDiagnostic::SchemaCompile { message, .. } => message,
            LintelDiagnostic::Validation(v) => &v.message,
            LintelDiagnostic::Format { .. } => "file is not properly formatted",
        }
    }

    /// Byte offset in the source file (for sorting).
    pub fn offset(&self) -> usize {
        match self {
            LintelDiagnostic::Parse { span, .. } => span.offset(),
            LintelDiagnostic::Validation(v) => v.span.offset(),
            LintelDiagnostic::SchemaMismatch { .. }
            | LintelDiagnostic::Io { .. }
            | LintelDiagnostic::SchemaFetch { .. }
            | LintelDiagnostic::SchemaCompile { .. }
            | LintelDiagnostic::Format { .. } => 0,
        }
    }
}

/// Convert a byte offset into 1-based (line, column).
///
/// Returns `(1, 1)` if the offset is 0 or the content is empty.
pub fn offset_to_line_col(content: &str, offset: usize) -> (usize, usize) {
    let offset = offset.min(content.len());
    let mut line = 1;
    let mut col = 1;
    for (i, ch) in content.char_indices() {
        if i >= offset {
            break;
        }
        if ch == '\n' {
            line += 1;
            col = 1;
        } else {
            col += 1;
        }
    }
    (line, col)
}

/// Find the byte offset of the first non-comment, non-blank line in the content.
///
/// Skips lines that start with `#` (YAML/TOML comments, modelines) or `//` (JSONC),
/// as well as blank lines. Returns 0 if all lines are comments or the content is empty.
fn first_content_offset(content: &str) -> usize {
    let mut offset = 0;
    for line in content.lines() {
        let trimmed = line.trim_start();
        if !trimmed.is_empty() && !trimmed.starts_with('#') && !trimmed.starts_with("//") {
            let key_start = line.len() - trimmed.len();
            return offset + key_start;
        }
        offset += line.len() + 1; // +1 for newline
    }
    0
}

/// Find the byte span `(offset, length)` of a JSON pointer path segment in the
/// source text, suitable for converting directly into a [`SourceSpan`].
///
/// For an `instance_path` like `/properties/name`, searches for the last segment
/// `name` as a JSON key (`"name"`) or YAML key (`name:`), and returns a span
/// covering the matched token.
///
/// For root-level errors (empty or "/" path), skips past leading comment and blank
/// lines so the error arrow points at actual content rather than modeline comments.
/// The returned span has zero length in this case since there is no specific token.
///
/// Falls back to `(0, 0)` if nothing is found.
pub fn find_instance_path_span(content: &str, instance_path: &str) -> (usize, usize) {
    if instance_path.is_empty() || instance_path == "/" {
        return (first_content_offset(content), 0);
    }

    // Get the last path segment (e.g., "/foo/bar/baz" -> "baz")
    let segment = instance_path.rsplit('/').next().unwrap_or("");
    if segment.is_empty() {
        return (0, 0);
    }

    // Try JSON-style key: "segment" — highlight including quotes
    let json_key = format!("\"{segment}\"");
    if let Some(pos) = content.find(&json_key) {
        return (pos, json_key.len());
    }

    // Try YAML-style key: segment: (at line start or after whitespace)
    let yaml_key = format!("{segment}:");
    let quoted_yaml_key = format!("\"{segment}\":");
    let mut offset = 0;
    for line in content.lines() {
        let trimmed = line.trim_start();
        if trimmed.starts_with(&quoted_yaml_key) {
            let key_start = line.len() - trimmed.len();
            // Highlight the quoted key without the trailing colon
            return (offset + key_start, quoted_yaml_key.len() - 1);
        }
        if trimmed.starts_with(&yaml_key) {
            let key_start = line.len() - trimmed.len();
            // Highlight just the key without the trailing colon
            return (offset + key_start, segment.len());
        }
        offset += line.len() + 1; // +1 for newline
    }

    (0, 0)
}

/// Build a label string combining the instance path and the schema path.
///
/// Returns just the `instance_path` when `schema_path` is empty.
pub fn format_label(instance_path: &str, schema_path: &str) -> String {
    if schema_path.is_empty() {
        instance_path.to_string()
    } else {
        format!("{instance_path} in {schema_path}")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn offset_zero_returns_line_one_col_one() {
        assert_eq!(offset_to_line_col("hello", 0), (1, 1));
    }

    #[test]
    fn offset_within_first_line() {
        assert_eq!(offset_to_line_col("hello world", 5), (1, 6));
    }

    #[test]
    fn offset_at_second_line() {
        assert_eq!(offset_to_line_col("ab\ncd\nef", 3), (2, 1));
    }

    #[test]
    fn offset_middle_of_second_line() {
        assert_eq!(offset_to_line_col("ab\ncd\nef", 4), (2, 2));
    }

    #[test]
    fn offset_at_third_line() {
        assert_eq!(offset_to_line_col("ab\ncd\nef", 6), (3, 1));
    }

    #[test]
    fn offset_past_end_clamps() {
        assert_eq!(offset_to_line_col("ab\ncd", 100), (2, 3));
    }

    #[test]
    fn empty_content() {
        assert_eq!(offset_to_line_col("", 0), (1, 1));
    }

    #[test]
    fn root_path_skips_yaml_modeline() {
        let content = "# yaml-language-server: $schema=https://example.com/s.json\nname: hello\n";
        let (offset, len) = find_instance_path_span(content, "");
        assert_eq!(offset, 59); // "name: hello" starts at byte 59
        assert_eq!(len, 0); // root-level: no specific token
        assert_eq!(offset_to_line_col(content, offset), (2, 1));
    }

    #[test]
    fn root_path_skips_multiple_comments() {
        let content = "# modeline\n# another comment\n\nname: hello\n";
        let (offset, _) = find_instance_path_span(content, "");
        assert_eq!(offset_to_line_col(content, offset), (4, 1));
    }

    #[test]
    fn root_path_no_comments_returns_zero() {
        let content = "{\"name\": \"hello\"}";
        assert_eq!(find_instance_path_span(content, ""), (0, 0));
    }

    #[test]
    fn root_path_skips_toml_modeline() {
        let content = "# :schema https://example.com/s.json\nname = \"hello\"\n";
        let (offset, _) = find_instance_path_span(content, "");
        assert_eq!(offset_to_line_col(content, offset), (2, 1));
    }

    #[test]
    fn root_path_slash_skips_comments() {
        let content = "# yaml-language-server: $schema=url\ndata: value\n";
        let (offset, _) = find_instance_path_span(content, "/");
        assert_eq!(offset_to_line_col(content, offset), (2, 1));
    }

    #[test]
    fn span_highlights_json_key() {
        let content = r#"{"name": "hello", "age": 30}"#;
        assert_eq!(find_instance_path_span(content, "/name"), (1, 6)); // "name"
        assert_eq!(find_instance_path_span(content, "/age"), (18, 5)); // "age"
    }

    #[test]
    fn span_highlights_yaml_key() {
        let content = "name: hello\nage: 30\n";
        assert_eq!(find_instance_path_span(content, "/name"), (0, 4)); // name
        assert_eq!(find_instance_path_span(content, "/age"), (12, 3)); // age
    }

    #[test]
    fn span_highlights_quoted_yaml_key() {
        let content = "\"on\": push\n";
        assert_eq!(find_instance_path_span(content, "/on"), (0, 4)); // "on"
    }

    // --- Error code tests ---

    #[test]
    fn error_codes() {
        use miette::Diagnostic;

        let cases: Vec<(LintelDiagnostic, &str)> = vec![
            (
                LintelDiagnostic::Parse {
                    src: NamedSource::new("f", String::new()),
                    span: 0.into(),
                    message: String::new(),
                },
                "parse",
            ),
            (
                LintelDiagnostic::Validation(ValidationDiagnostic {
                    src: NamedSource::new("f", String::new()),
                    span: 0.into(),
                    schema_span: 0.into(),
                    path: String::new(),
                    instance_path: String::new(),
                    label: String::new(),
                    message: String::new(),
                    schema_url: String::new(),
                    schema_path: String::new(),
                    validation_code: "validation(required)".to_string(),
                }),
                "validation(required)",
            ),
            (
                LintelDiagnostic::SchemaMismatch {
                    path: String::new(),
                    line_number: 0,
                    message: String::new(),
                },
                "jsonl::schema_mismatch",
            ),
            (
                LintelDiagnostic::Io {
                    path: String::new(),
                    message: String::new(),
                },
                "io",
            ),
            (
                LintelDiagnostic::SchemaFetch {
                    path: String::new(),
                    message: String::new(),
                },
                "schema::fetch",
            ),
            (
                LintelDiagnostic::SchemaCompile {
                    path: String::new(),
                    message: String::new(),
                },
                "schema::compile",
            ),
            (
                LintelDiagnostic::Format {
                    path: String::new(),
                    styled_path: String::new(),
                    diff: String::new(),
                },
                "format",
            ),
        ];

        for (error, expected_code) in cases {
            assert_eq!(
                error.code().expect("missing diagnostic code").to_string(),
                expected_code,
                "wrong code for {error:?}"
            );
        }
    }

    // --- format_label tests ---

    #[test]
    fn format_label_with_schema_path() {
        assert_eq!(
            format_label(
                "/jobs/build",
                "/properties/jobs/patternProperties/^[_a-zA-Z][a-zA-Z0-9_-]*$/oneOf"
            ),
            "/jobs/build in /properties/jobs/patternProperties/^[_a-zA-Z][a-zA-Z0-9_-]*$/oneOf"
        );
    }

    #[test]
    fn format_label_empty_schema_path() {
        assert_eq!(format_label("/name", ""), "/name");
    }
}