diff --git a/README.md b/README.md index 92c0fad..62071fc 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ZIP-based office documents. Eleven conservative, configurable rules cover copied assistant scaffolding, generic style residue, source-code placeholders, tutorial narration, and configured non-ASCII characters. Rules retain exact source spans, apply path/content scopes, and feed a bounded, explainable -confidence score. The detector renders source-highlighted human diagnostics, +confidence score. The detector renders plain or graphical Miette diagnostics, concise records, or versioned JSON Lines. The formatter applies only configured Unicode-to-ASCII replacements, supports check/diff modes, and requires explicit opt-in for atomic file writes. The stdio LSP publishes those same replacement @@ -26,6 +26,7 @@ Rust 1.98.1 or newer is required. ```sh cargo run --bin john-slop -- path/to/document path/to/source-directory +cargo run --bin john-slop -- --output miette path/to/document cargo run --bin john-slop-fmt -- path/to/document cargo run --bin john-slop-fmt -- --check path/to/document cargo run --bin john-slop-lsp @@ -50,7 +51,7 @@ and Vim setup. - [Documentation index](docs/README.md) - [Command-line usage and current capabilities](docs/usage.md) - [Helix and Vim formatter/LSP setup](docs/editors.md) -- [Human, concise, and JSON output contracts](docs/output.md) +- [Human, Miette, concise, and JSON output contracts](docs/output.md) - [Architecture and public library API](docs/architecture.md) - [Layered configuration](docs/configuration.md) - [Heuristics, confidence, and applicability](docs/heuristics.md) diff --git a/docs/output.md b/docs/output.md index 9053bb4..b9bdd69 100644 --- a/docs/output.md +++ b/docs/output.md @@ -1,6 +1,6 @@ # Detector output contracts -The detector exposes three formats through `--output`. All formats preserve the +The detector exposes four formats through `--output`. All formats preserve the same deterministic document and finding order. Requested paths retain command line order, directory entries are sorted by filename, archive order follows the container, and findings are sorted by byte span and rule ID. @@ -13,6 +13,14 @@ severity, stable rule code, message, and remediation help. A final line per document reports the confidence score/band and advice, warning, and error counts. The narratable renderer deliberately avoids ANSI escapes. +## Miette + +`--output miette` renders the same typed diagnostics with Miette's graphical +Unicode source annotations and a deterministic no-color theme, followed by the +same summary. This mode requires the default `fancy-diagnostics` Cargo feature; +builds made with `--no-default-features` accept the option but fall back to the +plain human renderer. + ## Concise `--output concise` emits one line per finding followed by one summary line. A diff --git a/docs/usage.md b/docs/usage.md index 4b5dfaa..1a97900 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -22,12 +22,14 @@ limits can be overridden with `--max-document-bytes`, `--max-archive-bytes`, `--max-expanded-bytes`, `--max-archive-entries`, `--max-compression-ratio`, and `--max-walk-depth`. -Select output with `--output human`, `--output concise`, or `--output json`. -Human mode renders plain source excerpts, exact labels, remediation help, and a -summary. Concise mode emits stable single-line finding and summary records. JSON -mode emits one object per analyzed document with `schema_version: 1`, summary -fields, exact byte spans, and every finding. Machine modes never emit ANSI -escapes or logs on stdout. +Select output with `--output human`, `--output miette`, `--output concise`, or +`--output json`. Human mode renders plain source excerpts, exact labels, +remediation help, and a summary. Miette mode uses Unicode graphical source +annotations when the default `fancy-diagnostics` feature is enabled and falls +back to human mode without that feature. Concise mode emits stable single-line +finding and summary records. JSON mode emits one object per analyzed document +with `schema_version: 1`, summary fields, exact byte spans, and every finding. +Machine modes never emit ANSI escapes or logs on stdout. Findings cover the embedded or overridden heuristic catalog and retain exact UTF-8 byte spans through every output mode. See [Output contracts](output.md) diff --git a/src/bin/john-slop.rs b/src/bin/john-slop.rs index 29878f8..00d480b 100644 --- a/src/bin/john-slop.rs +++ b/src/bin/john-slop.rs @@ -73,12 +73,12 @@ struct Cli { #[arg(long, value_name = "GLOB", action = clap::ArgAction::Append)] ignore: Vec, - /// Select human, concise, or versioned JSON output. + /// Select plain human, graphical Miette, concise, or versioned JSON output. #[arg( long, value_enum, default_value_t, - value_name = "human|concise|json", + value_name = "human|miette|concise|json", hide_possible_values = true )] output: OutputFormat, diff --git a/src/bin/john-slop/output.rs b/src/bin/john-slop/output.rs index 4fd39ea..039e5bb 100644 --- a/src/bin/john-slop/output.rs +++ b/src/bin/john-slop/output.rs @@ -3,6 +3,8 @@ use clap::ValueEnum; use john_slop::{Analysis, Finding, FindingDiagnostic, SourceId}; use miette::NarratableReportHandler; +#[cfg(feature = "fancy-diagnostics")] +use miette::{GraphicalReportHandler, GraphicalTheme}; use serde::Serialize; /// User-selectable detector presentation format. @@ -11,6 +13,8 @@ pub enum OutputFormat { /// Plain source-highlighted diagnostics followed by a document summary. #[default] Human, + /// Graphical Unicode diagnostics (falls back to plain output without the fancy feature). + Miette, /// One stable single-line record per finding plus one summary record. Concise, /// One versioned JSON object per analyzed document. @@ -25,6 +29,7 @@ pub(super) fn render_analysis( ) -> Result { match format { OutputFormat::Human => Ok(render_human(source_id, source, analysis)), + OutputFormat::Miette => Ok(render_miette(source_id, source, analysis)), OutputFormat::Concise => Ok(render_concise(source_id, analysis)), OutputFormat::Json => { serde_json::to_string(&JsonAnalysis::new(source_id, analysis)).map(|mut record| { @@ -41,7 +46,9 @@ pub(super) fn render_input_error( message: &str, ) -> Result { match format { - OutputFormat::Human => Ok(format!("{source}: input error: {message}\n")), + OutputFormat::Human | OutputFormat::Miette => { + Ok(format!("{source}: input error: {message}\n")) + } OutputFormat::Concise => Ok(format!("{source}: input-error: {message}\n")), OutputFormat::Json => serde_json::to_string(&JsonInputError { schema_version: 1, @@ -57,8 +64,6 @@ pub(super) fn render_input_error( } fn render_human(source_id: &SourceId, source: &str, analysis: &Analysis) -> String { - use std::fmt::Write as _; - let mut rendered = String::new(); let handler = NarratableReportHandler::new().without_cause_chain(); for finding in &analysis.findings { @@ -67,6 +72,34 @@ fn render_human(source_id: &SourceId, source: &str, analysis: &Analysis) -> Stri .render_report(&mut rendered, &diagnostic) .expect("writing a diagnostic to a String cannot fail"); } + append_summary(&mut rendered, source_id, analysis); + rendered +} + +#[cfg(feature = "fancy-diagnostics")] +fn render_miette(source_id: &SourceId, source: &str, analysis: &Analysis) -> String { + let mut rendered = String::new(); + let handler = GraphicalReportHandler::new_themed(GraphicalTheme::unicode_nocolor()) + .without_cause_chain() + .with_links(false); + for finding in &analysis.findings { + let diagnostic = FindingDiagnostic::new(source_id, source, finding); + handler + .render_report(&mut rendered, &diagnostic) + .expect("writing a diagnostic to a String cannot fail"); + } + append_summary(&mut rendered, source_id, analysis); + rendered +} + +#[cfg(not(feature = "fancy-diagnostics"))] +fn render_miette(source_id: &SourceId, source: &str, analysis: &Analysis) -> String { + render_human(source_id, source, analysis) +} + +fn append_summary(rendered: &mut String, source_id: &SourceId, analysis: &Analysis) { + use std::fmt::Write as _; + let summary = analysis.summary(); let band = summary .confidence_band @@ -82,7 +115,6 @@ fn render_human(source_id: &SourceId, source: &str, analysis: &Analysis) -> Stri summary.findings.errors, ) .expect("writing a summary to a String cannot fail"); - rendered } fn render_concise(source_id: &SourceId, analysis: &Analysis) -> String { @@ -249,6 +281,26 @@ mod tests { assert!(!output.contains('\u{1b}')); } + #[cfg(feature = "fancy-diagnostics")] + #[test] + fn miette_output_has_graphical_source_labels_and_summary() { + let (source, analysis) = analysis(); + let output = render_analysis( + OutputFormat::Miette, + &SourceId::File("article.md".into()), + &source, + &analysis, + ) + .unwrap(); + + assert!(output.contains("typography-non-ascii-hyphen")); + assert!(output.contains("╭─[article.md:")); + assert!(output.contains("╰────")); + assert!(output.contains("help:")); + assert!(output.contains("confidence")); + assert!(!output.contains('\u{1b}')); + } + #[test] fn json_output_is_one_versioned_machine_record() { let (source, analysis) = analysis(); diff --git a/tests/snapshots/cli__help_is_successful_and_names_the_command.snap b/tests/snapshots/cli__help_is_successful_and_names_the_command.snap index 640cc38..540eebe 100644 --- a/tests/snapshots/cli__help_is_successful_and_names_the_command.snap +++ b/tests/snapshots/cli__help_is_successful_and_names_the_command.snap @@ -38,8 +38,8 @@ Options: Virtual filename used only for standard-input language and path scoping --ignore Skip source paths matching a glob; may be supplied more than once - --output - Select human, concise, or versioned JSON output [default: human] + --output + Select plain human, graphical Miette, concise, or versioned JSON output [default: human] --fail-confidence Return exit code 1 when a document reaches this evidence-confidence score [default: 100] --fail-level