feat: add structured detector output modes
This commit is contained in:
parent
c9b280e9fe
commit
cf4f0be12d
|
|
@ -565,6 +565,12 @@ version = "1.2.0"
|
|||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7655c9839580ee829dfacba1d1278c2b7883e50a277ff7541299489d6bdfdc45"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "jobserver"
|
||||
version = "0.1.35"
|
||||
|
|
@ -587,6 +593,7 @@ dependencies = [
|
|||
"miette",
|
||||
"regex",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"tempfile",
|
||||
"thiserror",
|
||||
"toml 1.1.6+spec-1.1.0",
|
||||
|
|
@ -903,6 +910,19 @@ dependencies = [
|
|||
"syn 3.0.6",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_json"
|
||||
version = "1.0.151"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"memchr",
|
||||
"serde",
|
||||
"serde_core",
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_spanned"
|
||||
version = "0.6.9"
|
||||
|
|
@ -1470,6 +1490,12 @@ version = "0.6.8"
|
|||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
|
||||
|
||||
[[package]]
|
||||
name = "zopfli"
|
||||
version = "0.8.3"
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@ globset = { version = "0.4.20", default-features = false }
|
|||
miette = { version = "7.6.0", default-features = false, features = ["derive"] }
|
||||
regex = "1.13.1"
|
||||
serde = { version = "1.0.229", features = ["derive"] }
|
||||
serde_json = "1.0.151"
|
||||
thiserror = "2.0.21"
|
||||
toml = "1.1.6"
|
||||
walkdir = "2.5.0"
|
||||
|
|
|
|||
|
|
@ -22,6 +22,13 @@ 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.
|
||||
|
||||
The current human-readable output contains the source identity, bounded evidence
|
||||
confidence, and finding count. Findings cover the embedded or overridden
|
||||
heuristic catalog and retain exact UTF-8 byte spans for later presentation.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
//! Detector command-line adapter.
|
||||
|
||||
#[path = "john-slop/output.rs"]
|
||||
mod output;
|
||||
|
||||
use std::{
|
||||
path::{Path, PathBuf},
|
||||
process::ExitCode,
|
||||
|
|
@ -13,6 +16,8 @@ use john_slop::{
|
|||
};
|
||||
use miette::{IntoDiagnostic, Result, WrapErr};
|
||||
|
||||
use output::{OutputFormat, render_analysis};
|
||||
|
||||
/// Inspect files, directories, or ZIP-based documents for low-care signals.
|
||||
#[derive(Debug, Parser)]
|
||||
#[command(
|
||||
|
|
@ -68,6 +73,16 @@ struct Cli {
|
|||
#[arg(long, value_name = "GLOB", action = clap::ArgAction::Append)]
|
||||
ignore: Vec<String>,
|
||||
|
||||
/// Select human, concise, or versioned JSON output.
|
||||
#[arg(
|
||||
long,
|
||||
value_enum,
|
||||
default_value_t,
|
||||
value_name = "human|concise|json",
|
||||
hide_possible_values = true
|
||||
)]
|
||||
output: OutputFormat,
|
||||
|
||||
/// Return exit code 1 when a document reaches this evidence-confidence score.
|
||||
#[arg(long, default_value_t = 100, value_parser = parse_confidence)]
|
||||
fail_confidence: u8,
|
||||
|
|
@ -154,11 +169,10 @@ fn run(cli: &Cli) -> Result<bool> {
|
|||
});
|
||||
if !is_ignored(&ignore, cli.stdin_filename.as_deref()) {
|
||||
let analysis = detector.analyze_with(&document.content, &context);
|
||||
println!(
|
||||
"{}: confidence {}, {} finding(s)",
|
||||
document.source,
|
||||
analysis.confidence.score(),
|
||||
analysis.findings.len()
|
||||
print!(
|
||||
"{}",
|
||||
render_analysis(cli.output, &document.source, &document.content, &analysis)
|
||||
.into_diagnostic()?
|
||||
);
|
||||
threshold_reached |= analysis.confidence.score() >= cli.fail_confidence;
|
||||
}
|
||||
|
|
@ -177,11 +191,10 @@ fn run(cli: &Cli) -> Result<bool> {
|
|||
}
|
||||
let context = john_slop::AnalysisContext::for_source(&document.source);
|
||||
let analysis = detector.analyze_with(&document.content, &context);
|
||||
println!(
|
||||
"{}: confidence {}, {} finding(s)",
|
||||
document.source,
|
||||
analysis.confidence.score(),
|
||||
analysis.findings.len()
|
||||
print!(
|
||||
"{}",
|
||||
render_analysis(cli.output, &document.source, &document.content, &analysis)
|
||||
.into_diagnostic()?
|
||||
);
|
||||
threshold_reached |= analysis.confidence.score() >= cli.fail_confidence;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,237 @@
|
|||
//! Deterministic detector output renderers.
|
||||
|
||||
use clap::ValueEnum;
|
||||
use john_slop::{Analysis, Finding, FindingDiagnostic, SourceId};
|
||||
use miette::NarratableReportHandler;
|
||||
use serde::Serialize;
|
||||
|
||||
/// User-selectable detector presentation format.
|
||||
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)]
|
||||
pub enum OutputFormat {
|
||||
/// Plain source-highlighted diagnostics followed by a document summary.
|
||||
#[default]
|
||||
Human,
|
||||
/// One stable single-line record per finding plus one summary record.
|
||||
Concise,
|
||||
/// One versioned JSON object per analyzed document.
|
||||
Json,
|
||||
}
|
||||
|
||||
pub(super) fn render_analysis(
|
||||
format: OutputFormat,
|
||||
source_id: &SourceId,
|
||||
source: &str,
|
||||
analysis: &Analysis,
|
||||
) -> Result<String, serde_json::Error> {
|
||||
match format {
|
||||
OutputFormat::Human => Ok(render_human(source_id, source, analysis)),
|
||||
OutputFormat::Concise => Ok(render_concise(source_id, analysis)),
|
||||
OutputFormat::Json => serde_json::to_string(&JsonAnalysis::new(source_id, analysis)),
|
||||
}
|
||||
}
|
||||
|
||||
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 {
|
||||
let diagnostic = FindingDiagnostic::new(source_id, source, finding);
|
||||
handler
|
||||
.render_report(&mut rendered, &diagnostic)
|
||||
.expect("writing a diagnostic to a String cannot fail");
|
||||
}
|
||||
let summary = analysis.summary();
|
||||
let band = summary
|
||||
.confidence_band
|
||||
.map_or("none", john_slop::ConfidenceBand::as_str);
|
||||
writeln!(
|
||||
rendered,
|
||||
"{}: confidence {} ({band}); {} finding(s): {} advice, {} warning, {} error",
|
||||
source_id,
|
||||
summary.confidence_score,
|
||||
summary.findings.total(),
|
||||
summary.findings.advice,
|
||||
summary.findings.warnings,
|
||||
summary.findings.errors,
|
||||
)
|
||||
.expect("writing a summary to a String cannot fail");
|
||||
rendered
|
||||
}
|
||||
|
||||
fn render_concise(source_id: &SourceId, analysis: &Analysis) -> String {
|
||||
use std::fmt::Write as _;
|
||||
|
||||
let mut rendered = String::new();
|
||||
for finding in &analysis.findings {
|
||||
writeln!(
|
||||
rendered,
|
||||
"{}:{}:{}: {}[{}]: {}",
|
||||
source_id,
|
||||
finding.byte_span.start,
|
||||
finding.byte_span.end,
|
||||
finding.severity,
|
||||
finding.rule_id,
|
||||
finding.message,
|
||||
)
|
||||
.expect("writing a finding to a String cannot fail");
|
||||
}
|
||||
let summary = analysis.summary();
|
||||
let band = summary
|
||||
.confidence_band
|
||||
.map_or("none", john_slop::ConfidenceBand::as_str);
|
||||
writeln!(
|
||||
rendered,
|
||||
"{}: summary: confidence={} band={band} advice={} warnings={} errors={} total={}",
|
||||
source_id,
|
||||
summary.confidence_score,
|
||||
summary.findings.advice,
|
||||
summary.findings.warnings,
|
||||
summary.findings.errors,
|
||||
summary.findings.total(),
|
||||
)
|
||||
.expect("writing a summary to a String cannot fail");
|
||||
rendered
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct JsonAnalysis<'a> {
|
||||
schema_version: u8,
|
||||
kind: &'static str,
|
||||
source: String,
|
||||
summary: JsonSummary,
|
||||
findings: Vec<JsonFinding<'a>>,
|
||||
}
|
||||
|
||||
impl<'a> JsonAnalysis<'a> {
|
||||
fn new(source_id: &SourceId, analysis: &'a Analysis) -> Self {
|
||||
let summary = analysis.summary();
|
||||
Self {
|
||||
schema_version: 1,
|
||||
kind: "analysis",
|
||||
source: source_id.to_string(),
|
||||
summary: JsonSummary {
|
||||
confidence_score: summary.confidence_score,
|
||||
confidence_band: summary.confidence_band,
|
||||
advice: summary.findings.advice,
|
||||
warnings: summary.findings.warnings,
|
||||
errors: summary.findings.errors,
|
||||
total: summary.findings.total(),
|
||||
},
|
||||
findings: analysis.findings.iter().map(JsonFinding::new).collect(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct JsonSummary {
|
||||
confidence_score: u8,
|
||||
confidence_band: Option<john_slop::ConfidenceBand>,
|
||||
advice: usize,
|
||||
warnings: usize,
|
||||
errors: usize,
|
||||
total: usize,
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct JsonFinding<'a> {
|
||||
rule_id: &'a str,
|
||||
category: john_slop::Category,
|
||||
severity: john_slop::FindingSeverity,
|
||||
message: &'a str,
|
||||
help: Option<&'a str>,
|
||||
byte_span: JsonSpan,
|
||||
matched_text: &'a str,
|
||||
weight: f64,
|
||||
fix: Option<JsonFix<'a>>,
|
||||
}
|
||||
|
||||
impl<'a> JsonFinding<'a> {
|
||||
fn new(finding: &'a Finding) -> Self {
|
||||
Self {
|
||||
rule_id: finding.rule_id.as_str(),
|
||||
category: finding.category,
|
||||
severity: finding.severity,
|
||||
message: &finding.message,
|
||||
help: finding.help.as_deref(),
|
||||
byte_span: JsonSpan {
|
||||
start: finding.byte_span.start,
|
||||
end: finding.byte_span.end,
|
||||
},
|
||||
matched_text: &finding.matched_text,
|
||||
weight: finding.weight,
|
||||
fix: finding.fix.as_ref().map(|fix| JsonFix {
|
||||
byte_span: JsonSpan {
|
||||
start: fix.byte_span.start,
|
||||
end: fix.byte_span.end,
|
||||
},
|
||||
replacement: &fix.replacement,
|
||||
}),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct JsonFix<'a> {
|
||||
byte_span: JsonSpan,
|
||||
replacement: &'a str,
|
||||
}
|
||||
|
||||
#[derive(Clone, Copy, Serialize)]
|
||||
struct JsonSpan {
|
||||
start: usize,
|
||||
end: usize,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use john_slop::{AnalysisContext, Config, Detector};
|
||||
|
||||
use super::*;
|
||||
|
||||
fn analysis() -> (String, Analysis) {
|
||||
let source = "préface—suffix".to_owned();
|
||||
let analysis = Detector::new(&Config::embedded())
|
||||
.unwrap()
|
||||
.analyze_with(&source, &AnalysisContext::for_path("article.md"));
|
||||
(source, analysis)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn human_output_has_source_excerpt_help_and_plain_summary() {
|
||||
let (source, analysis) = analysis();
|
||||
let output = render_analysis(
|
||||
OutputFormat::Human,
|
||||
&SourceId::File("article.md".into()),
|
||||
&source,
|
||||
&analysis,
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
assert!(output.contains("article.md"));
|
||||
assert!(output.contains("préface—suffix"));
|
||||
assert!(output.contains("diagnostic help:"));
|
||||
assert!(output.contains("confidence"));
|
||||
assert!(!output.contains('\u{1b}'));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn json_output_is_one_versioned_machine_record() {
|
||||
let (source, analysis) = analysis();
|
||||
let output = render_analysis(
|
||||
OutputFormat::Json,
|
||||
&SourceId::File("article.md".into()),
|
||||
&source,
|
||||
&analysis,
|
||||
)
|
||||
.unwrap();
|
||||
let value: serde_json::Value = serde_json::from_str(&output).unwrap();
|
||||
|
||||
assert_eq!(value["schema_version"], 1);
|
||||
assert_eq!(value["kind"], "analysis");
|
||||
assert_eq!(value["source"], "article.md");
|
||||
assert_eq!(value["findings"][0]["byte_span"]["start"], 8);
|
||||
assert!(!output.contains('\u{1b}'));
|
||||
assert!(!output.contains('\n'));
|
||||
}
|
||||
}
|
||||
21
src/model.rs
21
src/model.rs
|
|
@ -45,6 +45,24 @@ pub enum Category {
|
|||
SourceCode,
|
||||
}
|
||||
|
||||
impl Category {
|
||||
/// Return the stable kebab-case presentation name.
|
||||
pub const fn as_str(self) -> &'static str {
|
||||
match self {
|
||||
Self::Typography => "typography",
|
||||
Self::Style => "style",
|
||||
Self::PromptLeakage => "prompt-leakage",
|
||||
Self::SourceCode => "source-code",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for Category {
|
||||
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
formatter.write_str(self.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
/// Review severity attached to an individual configured finding.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
|
|
@ -93,7 +111,8 @@ impl Confidence {
|
|||
}
|
||||
|
||||
/// Named interpretation of a non-empty analysis score.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "kebab-case")]
|
||||
pub enum ConfidenceBand {
|
||||
/// Evidence exists but remains below the configured low threshold.
|
||||
BelowThreshold,
|
||||
|
|
|
|||
2
tasks.md
2
tasks.md
|
|
@ -144,7 +144,7 @@ formula are pinned by tests.
|
|||
while retaining every contributing diagnostic.
|
||||
- [x] Build detector CLI inputs for file, directory, and stdin (`--stdin-filename`
|
||||
for language/path scoping); add ignore and maximum-size controls.
|
||||
- [ ] Add human, concise, and versioned JSON output modes. Ensure JSON and stdout
|
||||
- [x] Add human, concise, and versioned JSON output modes. Ensure JSON and stdout
|
||||
diagnostics never contain logs or ANSI escapes.
|
||||
- [ ] Implement documented exit codes: `0` below fail threshold, `1` at/above it,
|
||||
`2` for usage/configuration/I/O failure. Add `--fail-level`.
|
||||
|
|
|
|||
|
|
@ -38,6 +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]
|
||||
--fail-confidence <FAIL_CONFIDENCE>
|
||||
Return exit code 1 when a document reaches this evidence-confidence score [default: 100]
|
||||
-h, --help
|
||||
|
|
|
|||
Loading…
Reference in New Issue