feat: add graphical Miette diagnostics
This commit is contained in:
parent
0cb7ec3011
commit
b40112a724
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue