feat: add graphical Miette diagnostics

This commit is contained in:
Dandaedre 2026-09-29 17:20:24 +02:00
parent 0cb7ec3011
commit b40112a724
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
6 changed files with 80 additions and 17 deletions

View File

@ -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)

View File

@ -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

View File

@ -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)

View File

@ -73,12 +73,12 @@ struct Cli {
#[arg(long, value_name = "GLOB", action = clap::ArgAction::Append)]
ignore: Vec<String>,
/// 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,

View File

@ -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<String, serde_json::Error> {
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<String, serde_json::Error> {
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();

View File

@ -38,8 +38,8 @@ Options:
Virtual filename used only for standard-input language and path scoping
--ignore <GLOB>
Skip source paths matching a glob; may be supplied more than once
--output <human|concise|json>
Select human, concise, or versioned JSON output [default: human]
--output <human|miette|concise|json>
Select plain human, graphical Miette, concise, or versioned JSON output [default: human]
--fail-confidence <FAIL_CONFIDENCE>
Return exit code 1 when a document reaches this evidence-confidence score [default: 100]
--fail-level <FAIL_LEVEL>