Merge wip/cli-colour: colour diagnostics and highlight converted SQL on a terminal

Author: kvlonge

.github/demos/check-convert.gif

@@ -41,6 +41,7 @@ publish = false
 rust-version = "1.88"
 
 [workspace.dependencies]
+anstream = "1.0"
 arrow = { version = "60", default-features = false, features = ["ipc"] }
 clap = { version = "4.5", features = ["derive"] }
 duckdb = "=1.20000.0"

Cargo.lock

@@ -1,6 +1,6 @@
 //! The diagnostic code registry, the one source of every `SQ` code; append only, see codes.lock.
 
-use crate::diagnostics::models::CodeEntry;
+use crate::diagnostics::models::{CodeEntry, Palette};
 
 /// The prefix of a parse refusal's reason, before the parser's own message.
 pub const UNPARSED_PREFIX: &str = "the SQL does not parse: ";
@@ -37,6 +37,36 @@ pub const GUARD_PREFIX: &str = "E_GUARD_";
 pub const MAX_SHOWN_LINE: usize = 120;
 /// How many columns a tab takes when a source line is shown.
 pub const TAB_WIDTH: usize = 4;
+/// No styling: rendered diagnostics are plain text.
+pub const PLAIN_PALETTE: Palette = Palette {
+    error: "",
+    message: "",
+    gutter: "",
+    note: "",
+    help: "",
+    success: "",
+    keyword: "",
+    string: "",
+    number: "",
+    comment: "",
+    identifier: "",
+    reset: "",
+};
+/// rustc's terminal colours for diagnostics, and SQL highlighting colours for converted output.
+pub const ANSI_PALETTE: Palette = Palette {
+    error: "\x1b[1;31m",
+    message: "\x1b[1m",
+    gutter: "\x1b[1;34m",
+    note: "\x1b[1m",
+    help: "\x1b[1;36m",
+    success: "\x1b[1;32m",
+    keyword: "\x1b[35m",
+    string: "\x1b[32m",
+    number: "\x1b[33m",
+    comment: "\x1b[2m",
+    identifier: "\x1b[36m",
+    reset: "\x1b[0m",
+};
 
 /// SQL that does not parse.
 pub const PARSE_FIDELITY: &str = "SQ0001";

Cargo.toml

@@ -1,4 +1,5 @@
 pub mod diagnose;
 pub mod explain_code;
 pub mod render_diagnostics;
+pub mod render_styled_diagnostics;
 pub mod unplaced_diagnostic;

crates/sqlquack-core/src/diagnostics/constants.rs

@@ -1,104 +1,10 @@
 //! `render_diagnostics`: diagnostics as rustc-style text, the source line underlined at the span.
 
-use std::fmt::Write;
+use crate::diagnostics::constants::PLAIN_PALETTE;
+use crate::diagnostics::main::render_styled_diagnostics::render_styled_diagnostics;
+use crate::diagnostics::models::Diagnostic;
 
-use crate::diagnostics::_helpers::line_index::LineIndex;
-use crate::diagnostics::constants::{MAX_SHOWN_LINE, TAB_WIDTH};
-use crate::diagnostics::models::{Diagnostic, DiagnosticSpan};
-
-/// Every diagnostic of `source`, read from `path`, as text separated by blank lines.
+/// Every diagnostic of `source`, read from `path`, as plain text separated by blank lines.
 pub fn render_diagnostics(diagnostics: &[Diagnostic], source: &str, path: &str) -> String {
-    let lines = LineIndex::new(source);
-    diagnostics
-        .iter()
-        .map(|diagnostic| render_one(diagnostic, &lines, path))
-        .collect::<Vec<String>>()
-        .join("\n")
-}
-
-fn render_one(diagnostic: &Diagnostic, lines: &LineIndex<'_>, path: &str) -> String {
-    let mut text = format!(
-        "{}[{}]: {}\n",
-        diagnostic.severity.label(),
-        diagnostic.code,
-        diagnostic.message
-    );
-    let gutter = " ".repeat(
-        diagnostic
-            .span
-            .map_or(1, |span| span.line.to_string().len()),
-    );
-    match diagnostic.span {
-        Some(span) => {
-            let _ = writeln!(text, "{gutter}--> {path}:{}:{}", span.line, span.column);
-            let (shown, underline) = excerpt(lines.text(span.line), span);
-            let _ = writeln!(text, "{gutter} |");
-            let _ = writeln!(text, "{} | {shown}", span.line);
-            let _ = writeln!(text, "{gutter} | {underline} {}", diagnostic.label);
-            if !diagnostic.notes.is_empty() || diagnostic.help.is_some() {
-                let _ = writeln!(text, "{gutter} |");
-            }
-        }
-        None => {
-            let _ = writeln!(text, "{gutter}--> {path}");
-            let _ = writeln!(text, "{gutter} |");
-            let _ = writeln!(text, "{gutter} = note: {}", diagnostic.label);
-        }
-    }
-    for note in &diagnostic.notes {
-        let _ = writeln!(text, "{gutter} = note: {note}");
-    }
-    if let Some(help) = &diagnostic.help {
-        let _ = writeln!(text, "{gutter} = help: {help}");
-    }
-    text
-}
-
-/// The line as shown, windowed when long and with tabs expanded, and its underline.
-fn excerpt(line: &str, span: DiagnosticSpan) -> (String, String) {
-    let characters: Vec<char> = line.chars().collect();
-    let first = span.column.saturating_sub(1).min(characters.len());
-    let last = match span.end_line == span.line {
-        true => span
-            .end_column
-            .saturating_sub(1)
-            .clamp(first, characters.len()),
-        false => characters.len(),
-    }
-    .max(first + 1);
-    let window_start = match characters.len() > MAX_SHOWN_LINE {
-        true => first.saturating_sub(MAX_SHOWN_LINE / 2),
-        false => 0,
-    };
-    let window_end = (window_start + MAX_SHOWN_LINE).min(characters.len());
-    let mut shown = String::new();
-    let mut underline = String::new();
-    if window_start > 0 {
-        shown.push('…');
-        underline.push(' ');
-    }
-    for (index, character) in characters[window_start..window_end].iter().enumerate() {
-        let offset = window_start + index;
-        let width = match character {
-            '\t' => TAB_WIDTH,
-            _ => 1,
-        };
-        match character {
-            '\t' => shown.push_str(&" ".repeat(TAB_WIDTH)),
-            other => shown.push(*other),
-        }
-        let mark = match (first..last).contains(&offset) {
-            true => '^',
-            false => ' ',
-        };
-        underline.push_str(&mark.to_string().repeat(width));
-    }
-    if window_end < characters.len() {
-        shown.push('…');
-    }
-    let marked = last.min(window_end.max(first + 1));
-    for _ in window_end.max(first)..marked {
-        underline.push('^');
-    }
-    (shown, underline.trim_end().to_owned())
+    render_styled_diagnostics(diagnostics, source, path, &PLAIN_PALETTE)
 }

crates/sqlquack-core/src/diagnostics/main/mod.rs

@@ -0,0 +1,135 @@
+//! `render_styled_diagnostics`: diagnostics as rustc-style text in a palette, spans underlined.
+
+use std::fmt::Write;
+
+use crate::diagnostics::_helpers::line_index::LineIndex;
+use crate::diagnostics::constants::{MAX_SHOWN_LINE, TAB_WIDTH};
+use crate::diagnostics::models::{Diagnostic, DiagnosticSpan, Palette};
+
+/// Every diagnostic of `source` at `path`, styled by `style`; the plain palette is the plain text.
+pub fn render_styled_diagnostics(
+    diagnostics: &[Diagnostic],
+    source: &str,
+    path: &str,
+    style: &Palette,
+) -> String {
+    let lines = LineIndex::new(source);
+    diagnostics
+        .iter()
+        .map(|diagnostic| render_one(diagnostic, &lines, path, style))
+        .collect::<Vec<String>>()
+        .join("\n")
+}
+
+fn render_one(
+    diagnostic: &Diagnostic,
+    lines: &LineIndex<'_>,
+    path: &str,
+    style: &Palette,
+) -> String {
+    let Palette {
+        message,
+        gutter: blue,
+        note,
+        help,
+        reset,
+        ..
+    } = *style;
+    let severity = style.severity(diagnostic.severity);
+    let mut text = format!(
+        "{severity}{}[{}]{reset}{message}: {}{reset}\n",
+        diagnostic.severity.label(),
+        diagnostic.code,
+        diagnostic.message
+    );
+    let gutter = " ".repeat(
+        diagnostic
+            .span
+            .map_or(1, |span| span.line.to_string().len()),
+    );
+    match diagnostic.span {
+        Some(span) => {
+            let _ = writeln!(
+                text,
+                "{gutter}{blue}-->{reset} {path}:{}:{}",
+                span.line, span.column
+            );
+            let (shown, underline) = excerpt(lines.text(span.line), span);
+            let _ = writeln!(text, "{gutter} {blue}|{reset}");
+            let _ = writeln!(text, "{blue}{} |{reset} {shown}", span.line);
+            let _ = writeln!(
+                text,
+                "{gutter} {blue}|{reset} {severity}{underline} {}{reset}",
+                diagnostic.label
+            );
+            if !diagnostic.notes.is_empty() || diagnostic.help.is_some() {
+                let _ = writeln!(text, "{gutter} {blue}|{reset}");
+            }
+        }
+        None => {
+            let _ = writeln!(text, "{gutter}{blue}-->{reset} {path}");
+            let _ = writeln!(text, "{gutter} {blue}|{reset}");
+            let _ = writeln!(
+                text,
+                "{gutter} {blue}={reset} {note}note{reset}: {}",
+                diagnostic.label
+            );
+        }
+    }
+    for line in &diagnostic.notes {
+        let _ = writeln!(text, "{gutter} {blue}={reset} {note}note{reset}: {line}");
+    }
+    if let Some(advice) = &diagnostic.help {
+        let _ = writeln!(text, "{gutter} {blue}={reset} {help}help{reset}: {advice}");
+    }
+    text
+}
+
+/// The line as shown, windowed when long and with tabs expanded, and its underline.
+fn excerpt(line: &str, span: DiagnosticSpan) -> (String, String) {
+    let characters: Vec<char> = line.chars().collect();
+    let first = span.column.saturating_sub(1).min(characters.len());
+    let last = match span.end_line == span.line {
+        true => span
+            .end_column
+            .saturating_sub(1)
+            .clamp(first, characters.len()),
+        false => characters.len(),
+    }
+    .max(first + 1);
+    let window_start = match characters.len() > MAX_SHOWN_LINE {
+        true => first.saturating_sub(MAX_SHOWN_LINE / 2),
+        false => 0,
+    };
+    let window_end = (window_start + MAX_SHOWN_LINE).min(characters.len());
+    let mut shown = String::new();
+    let mut underline = String::new();
+    if window_start > 0 {
+        shown.push('…');
+        underline.push(' ');
+    }
+    for (index, character) in characters[window_start..window_end].iter().enumerate() {
+        let offset = window_start + index;
+        let width = match character {
+            '\t' => TAB_WIDTH,
+            _ => 1,
+        };
+        match character {
+            '\t' => shown.push_str(&" ".repeat(TAB_WIDTH)),
+            other => shown.push(*other),
+        }
+        let mark = match (first..last).contains(&offset) {
+            true => '^',
+            false => ' ',
+        };
+        underline.push_str(&mark.to_string().repeat(width));
+    }
+    if window_end < characters.len() {
+        shown.push('…');
+    }
+    let marked = last.min(window_end.max(first + 1));
+    for _ in window_end.max(first)..marked {
+        underline.push('^');
+    }
+    (shown, underline.trim_end().to_owned())
+}

crates/sqlquack-core/src/diagnostics/main/render_diagnostics.rs

@@ -19,6 +19,44 @@ impl Severity {
     }
 }
 
+/// The escape sequences that style diagnostics and SQL; empty strings render plain text.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Palette {
+    /// An error's label, code, underline and summary.
+    pub error: &'static str,
+    /// The headline message.
+    pub message: &'static str,
+    /// The `-->` arrow, the gutter and its line numbers.
+    pub gutter: &'static str,
+    /// The `note` label.
+    pub note: &'static str,
+    /// The `help` label.
+    pub help: &'static str,
+    /// A summary that reports success.
+    pub success: &'static str,
+    /// A SQL keyword or type name.
+    pub keyword: &'static str,
+    /// A SQL string literal.
+    pub string: &'static str,
+    /// A SQL number.
+    pub number: &'static str,
+    /// A SQL comment.
+    pub comment: &'static str,
+    /// A SQL identifier, quoted or not, including function names.
+    pub identifier: &'static str,
+    /// Ends any of the styles above.
+    pub reset: &'static str,
+}
+
+impl Palette {
+    /// The style of a diagnostic of `severity`.
+    pub fn severity(&self, severity: Severity) -> &'static str {
+        match severity {
+            Severity::Error => self.error,
+        }
+    }
+}
+
 /// One registered diagnostic code; codes are never reused or renumbered.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
 pub struct CodeEntry {

crates/sqlquack-core/src/diagnostics/main/render_styled_diagnostics.rs

@@ -3,7 +3,9 @@
 use pyo3::exceptions::PyValueError;
 use pyo3::{PyResult, pyfunction};
 use sqlquack::cli::main::convert_report::convert_report;
-use sqlquack::cli::models::{ConvertArguments, OutputArguments, OutputFormat, PolicyArguments};
+use sqlquack::cli::models::{
+    ColorArguments, ConvertArguments, OutputArguments, OutputFormat, PolicyArguments,
+};
 use sqlquack_core::diagnostics::main::render_diagnostics::render_diagnostics;
 use sqlquack_core::diagnostics::models::Diagnostic;
 
@@ -25,6 +27,7 @@ pub(crate) fn convert_json(sql: &str, request: &str, path: &str) -> PyResult<Str
             format: OutputFormat::Json,
             json: false,
         },
+        colors: ColorArguments::default(),
         conversion: PolicyArguments {
             policy: request.policy,
             builtin_policy: request.builtin_policy,

crates/sqlquack-core/src/diagnostics/models.rs

@@ -21,6 +21,7 @@ path = "src/bin/sqlquack.rs"
 bundled = ["sqlquack-duckdb/bundled"]
 
 [dependencies]
+anstream.workspace = true
 clap.workspace = true
 rayon.workspace = true
 serde.workspace = true