dart-decimate 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,27 +1,520 @@
1
1
  use std::fmt::Write as _;
2
+ use std::io::IsTerminal as _;
2
3
 
3
- use super::types::JsonReport;
4
+ use super::{
5
+ human_details::{
6
+ best_text, fallback_best, kind_label, omitted_findings_message, summary_groups, why_text,
7
+ },
8
+ types::{Finding, FindingEdge, FindingKind, JsonReport, ReportSummary, Severity, Verdict},
9
+ };
10
+
11
+ const MAX_RELATED_FILES: usize = 8;
4
12
 
5
13
  /// Render a concise human report.
6
14
  #[must_use]
7
15
  pub fn render_human_report(report: &JsonReport) -> String {
16
+ render_human_report_with_style(report, Style::from_env())
17
+ }
18
+
19
+ #[derive(Clone, Copy)]
20
+ struct Style {
21
+ color: bool,
22
+ }
23
+
24
+ impl Style {
25
+ const fn plain() -> Self {
26
+ Self { color: false }
27
+ }
28
+
29
+ const fn colored() -> Self {
30
+ Self { color: true }
31
+ }
32
+
33
+ fn from_env() -> Self {
34
+ if std::env::var_os("NO_COLOR").is_some() {
35
+ return Self::plain();
36
+ }
37
+ if !std::io::stdout().is_terminal() {
38
+ return Self::plain();
39
+ }
40
+ match std::env::var("TERM") {
41
+ Ok(term) if term.eq_ignore_ascii_case("dumb") => Self::plain(),
42
+ _ => Self::colored(),
43
+ }
44
+ }
45
+
46
+ #[must_use]
47
+ fn paint(self, code: &str, text: &str) -> String {
48
+ if self.color {
49
+ format!("\x1b[{code}m{text}\x1b[0m")
50
+ } else {
51
+ text.to_owned()
52
+ }
53
+ }
54
+
55
+ #[must_use]
56
+ fn bold(self, text: &str) -> String {
57
+ self.paint("1", text)
58
+ }
59
+
60
+ #[must_use]
61
+ fn dim(self, text: &str) -> String {
62
+ self.paint("2", text)
63
+ }
64
+
65
+ #[must_use]
66
+ fn cyan(self, text: &str) -> String {
67
+ self.paint("36", text)
68
+ }
69
+
70
+ #[must_use]
71
+ fn green(self, text: &str) -> String {
72
+ self.paint("1;32", text)
73
+ }
74
+
75
+ #[must_use]
76
+ fn red(self, text: &str) -> String {
77
+ self.paint("1;31", text)
78
+ }
79
+ }
80
+
81
+ fn render_human_report_with_style(report: &JsonReport, style: Style) -> String {
8
82
  let mut rendered = String::new();
83
+ render_header(&mut rendered, report, style);
84
+ render_issue_summary(&mut rendered, &report.summary, style);
85
+
86
+ if report.findings.is_empty() {
87
+ if report.summary.findings == 0 && report.verdict == Verdict::Pass {
88
+ let _ = writeln!(
89
+ rendered,
90
+ "\n{}",
91
+ style.green("No findings. The selected Dart graph checks passed.")
92
+ );
93
+ } else {
94
+ let message = omitted_findings_message(&report.summary, report.verdict);
95
+ let message = if report.verdict == Verdict::Fail {
96
+ style.red(&message)
97
+ } else {
98
+ style.cyan(&message)
99
+ };
100
+ let _ = writeln!(rendered, "\n{message}");
101
+ }
102
+ return rendered;
103
+ }
104
+
105
+ let _ = writeln!(rendered, "\n{}", style.bold("Findings"));
106
+ for (index, finding) in report.findings.iter().enumerate() {
107
+ render_finding(&mut rendered, index + 1, finding, style);
108
+ }
109
+
110
+ if !report.next_steps.is_empty() {
111
+ let _ = writeln!(rendered, "\n{}", style.bold("Next Steps"));
112
+ for (index, step) in report.next_steps.iter().enumerate() {
113
+ let command = terminal_text(&step.command);
114
+ let reason = terminal_text(&step.reason);
115
+ let _ = writeln!(
116
+ rendered,
117
+ " {}. {}",
118
+ index + 1,
119
+ style.cyan(command.as_str())
120
+ );
121
+ let _ = writeln!(rendered, " Why: {reason}");
122
+ }
123
+ }
124
+
125
+ rendered
126
+ }
127
+
128
+ fn render_header(rendered: &mut String, report: &JsonReport, style: Style) {
129
+ let verdict = match report.verdict {
130
+ Verdict::Pass => style.green("PASS"),
131
+ Verdict::Fail => style.red("FAIL"),
132
+ };
133
+ let _ = writeln!(
134
+ rendered,
135
+ "{} {}: {verdict}",
136
+ style.bold("Dart Decimate"),
137
+ report.command.as_str()
138
+ );
9
139
  let _ = writeln!(
10
140
  rendered,
11
- "{:?} {}: {} findings across {} files",
12
- report.verdict,
13
- report.command.as_str(),
14
- report.summary.findings,
15
- report.summary.files
141
+ "Files: {} | Edges: {} | Findings: {}",
142
+ style.cyan(&report.summary.files.to_string()),
143
+ style.cyan(&report.summary.edges.to_string()),
144
+ style.cyan(&report.summary.findings.to_string())
16
145
  );
146
+ if report.summary.functions > 0 || report.summary.quality_score > 0 {
147
+ let _ = writeln!(
148
+ rendered,
149
+ "Quality: {}/100 | Functions: {} | Max cyclomatic: {} | Max cognitive: {}",
150
+ report.summary.quality_score,
151
+ report.summary.functions,
152
+ report.summary.max_cyclomatic_complexity,
153
+ report.summary.max_cognitive_complexity
154
+ );
155
+ }
156
+ }
157
+
158
+ fn render_issue_summary(rendered: &mut String, summary: &ReportSummary, style: Style) {
159
+ let groups = summary_groups(summary);
160
+ let visible = groups
161
+ .iter()
162
+ .filter(|(_, items)| !items.is_empty())
163
+ .collect::<Vec<_>>();
164
+
165
+ if visible.is_empty() {
166
+ return;
167
+ }
168
+
169
+ let _ = writeln!(rendered, "\n{}", style.bold("Issue Summary"));
170
+ for (name, items) in visible {
171
+ let _ = writeln!(rendered, " {}: {}", style.cyan(name), items.join(", "));
172
+ }
173
+ }
174
+
175
+ fn render_finding(rendered: &mut String, index: usize, finding: &Finding, style: Style) {
176
+ let severity = severity_label(finding.severity);
177
+ let severity = style.paint(severity_color(finding.severity), severity);
178
+ let _ = writeln!(
179
+ rendered,
180
+ "\n{}. [{}] {} at {}",
181
+ index,
182
+ severity,
183
+ style.bold(kind_label(finding.kind)),
184
+ location(finding)
185
+ );
186
+ let rule_id = terminal_text(&finding.rule_id);
187
+ let _ = writeln!(rendered, " Rule: {}", style.dim(&rule_id));
188
+ let _ = writeln!(rendered, " What: {}", terminal_text(&finding.message));
189
+ let _ = writeln!(rendered, " Why: {}", why_text(finding.kind));
190
+ render_evidence(rendered, finding, style);
191
+ render_best_action(rendered, finding, style);
192
+ }
193
+
194
+ fn render_evidence(rendered: &mut String, finding: &Finding, style: Style) {
195
+ let _ = writeln!(rendered, " Evidence:");
196
+ let _ = writeln!(rendered, " Location: {}", location(finding));
197
+ if let Some(fingerprint) = &finding.fingerprint {
198
+ let _ = writeln!(rendered, " Fingerprint: {}", terminal_text(fingerprint));
199
+ }
200
+ if let Some(edge) = &finding.edge {
201
+ render_edge(rendered, edge);
202
+ }
203
+ if !finding.files.is_empty() {
204
+ render_related_files(rendered, finding, style);
205
+ }
206
+ let safe = if finding.safe_to_delete {
207
+ "yes, after reviewing generated/dynamic usage"
208
+ } else {
209
+ "no; review or refactor before deleting"
210
+ };
211
+ let _ = writeln!(rendered, " Safe to delete: {safe}");
212
+ }
213
+
214
+ fn render_edge(rendered: &mut String, edge: &FindingEdge) {
215
+ let _ = writeln!(
216
+ rendered,
217
+ " Edge: {} {} -> {} ({})",
218
+ terminal_text(&edge.kind),
219
+ terminal_text(&edge.from),
220
+ terminal_text(&edge.to),
221
+ terminal_text(&edge.specifier)
222
+ );
223
+ }
17
224
 
18
- for finding in &report.findings {
225
+ fn render_related_files(rendered: &mut String, finding: &Finding, style: Style) {
226
+ if matches!(
227
+ finding.kind,
228
+ FindingKind::CircularDependency | FindingKind::ReExportCycle
229
+ ) {
19
230
  let _ = writeln!(
20
231
  rendered,
21
- "{}:{}:{} {} {}",
22
- finding.path, finding.line, finding.column, finding.rule_id, finding.message
232
+ " Cycle preview: {}",
233
+ style.cyan(&cycle_preview(&finding.files))
234
+ );
235
+ let _ = writeln!(
236
+ rendered,
237
+ " Files in cycle: {} total",
238
+ finding.files.len()
239
+ );
240
+ } else {
241
+ let _ = writeln!(
242
+ rendered,
243
+ " Related files: {}",
244
+ related_files_preview(&finding.files)
23
245
  );
24
246
  }
247
+ }
25
248
 
26
- rendered
249
+ fn render_best_action(rendered: &mut String, finding: &Finding, style: Style) {
250
+ let best = finding.actions.first().map_or_else(
251
+ || fallback_best(finding.kind),
252
+ |action| best_text(finding, action),
253
+ );
254
+ let _ = writeln!(rendered, " Best: {}", terminal_text(&best));
255
+
256
+ if let Some(command) = finding
257
+ .actions
258
+ .iter()
259
+ .find_map(|action| action.command.as_ref())
260
+ {
261
+ let command = terminal_text(command);
262
+ let _ = writeln!(rendered, " Inspect: {}", style.cyan(&command));
263
+ }
264
+ }
265
+
266
+ #[must_use]
267
+ fn location(finding: &Finding) -> String {
268
+ let path = if finding.path.is_empty() {
269
+ "<project>"
270
+ } else {
271
+ finding.path.as_str()
272
+ };
273
+ let path = terminal_text(path);
274
+ format!("{path}:{}:{}", finding.line, finding.column)
275
+ }
276
+
277
+ fn terminal_text(value: &str) -> String {
278
+ value
279
+ .chars()
280
+ .filter(|character| !character.is_control())
281
+ .collect()
282
+ }
283
+
284
+ #[must_use]
285
+ const fn severity_label(severity: Severity) -> &'static str {
286
+ match severity {
287
+ Severity::Error => "error",
288
+ Severity::Warning => "warn",
289
+ }
290
+ }
291
+
292
+ #[must_use]
293
+ const fn severity_color(severity: Severity) -> &'static str {
294
+ match severity {
295
+ Severity::Error => "1;31",
296
+ Severity::Warning => "1;33",
297
+ }
298
+ }
299
+
300
+ #[must_use]
301
+ fn cycle_preview(files: &[String]) -> String {
302
+ let mut visible = files
303
+ .iter()
304
+ .take(MAX_RELATED_FILES)
305
+ .map(|file| terminal_text(file))
306
+ .collect::<Vec<_>>();
307
+ if files.len() > MAX_RELATED_FILES {
308
+ visible.push(format!(
309
+ "... {} more files ...",
310
+ files.len() - MAX_RELATED_FILES
311
+ ));
312
+ }
313
+ if let Some(first) = files.first() {
314
+ visible.push(terminal_text(first));
315
+ }
316
+ visible.join(" -> ")
317
+ }
318
+
319
+ #[must_use]
320
+ fn related_files_preview(files: &[String]) -> String {
321
+ let mut visible = files
322
+ .iter()
323
+ .take(MAX_RELATED_FILES)
324
+ .map(|file| terminal_text(file))
325
+ .collect::<Vec<_>>();
326
+ if files.len() > MAX_RELATED_FILES {
327
+ visible.push(format!(
328
+ "... {} more files",
329
+ files.len() - MAX_RELATED_FILES
330
+ ));
331
+ }
332
+ visible.join(", ")
333
+ }
334
+
335
+ #[cfg(test)]
336
+ mod tests {
337
+ use super::*;
338
+ use crate::output::{FindingAction, ReportCommand};
339
+
340
+ #[test]
341
+ fn explains_large_cycles_with_truncated_evidence() {
342
+ let report = report_with_finding(cycle_finding(12));
343
+
344
+ let rendered = render_human_report_with_style(&report, Style::plain());
345
+
346
+ assert!(rendered.contains("Dart Decimate check: FAIL"));
347
+ assert!(rendered.contains("Architecture: 1 circular dependency"));
348
+ assert!(rendered.contains("[error] Circular dependency at lib/file_0.dart:1:0"));
349
+ assert!(rendered.contains("What: Circular dependency spans 12 Dart files"));
350
+ assert!(rendered.contains("Why: These files import or export each other in a loop."));
351
+ assert!(rendered.contains("Evidence:"));
352
+ assert!(rendered.contains("Cycle preview: lib/file_0.dart -> lib/file_1.dart"));
353
+ assert!(rendered.contains("... 4 more files ... -> lib/file_0.dart"));
354
+ assert!(rendered.contains("Files in cycle: 12 total"));
355
+ assert!(rendered.contains("Best: Break one import/export edge first."));
356
+ assert!(
357
+ rendered
358
+ .contains("Inspect: dart-decimate inspect --format json --file lib/file_0.dart")
359
+ );
360
+ }
361
+
362
+ #[test]
363
+ fn renders_color_when_enabled() {
364
+ let report = report_with_finding(cycle_finding(2));
365
+
366
+ let rendered = render_human_report_with_style(&report, Style::colored());
367
+
368
+ assert!(rendered.contains("\x1b[1;31mFAIL\x1b[0m"));
369
+ assert!(rendered.contains("\x1b[1;31merror\x1b[0m"));
370
+ assert!(
371
+ rendered
372
+ .contains("\x1b[36mlib/file_0.dart -> lib/file_1.dart -> lib/file_0.dart\x1b[0m")
373
+ );
374
+ }
375
+
376
+ #[test]
377
+ fn explains_safe_delete_actions_and_next_steps() {
378
+ let mut report = report_with_finding(Finding {
379
+ rule_id: "dart-decimate/dead-file".to_owned(),
380
+ fingerprint: None,
381
+ kind: FindingKind::DeadFile,
382
+ severity: Severity::Error,
383
+ message: "Dart file is unreachable from the configured entry points: lib/dead.dart"
384
+ .to_owned(),
385
+ path: "lib/dead.dart".to_owned(),
386
+ line: 1,
387
+ column: 0,
388
+ safe_to_delete: true,
389
+ files: Vec::new(),
390
+ edge: None,
391
+ actions: vec![FindingAction::new(
392
+ "delete-file",
393
+ "Delete the unreachable Dart file after confirming no dynamic entry point uses it",
394
+ true,
395
+ )
396
+ .with_dart_decimate_args([
397
+ "inspect",
398
+ "--format",
399
+ "json",
400
+ "--file",
401
+ "lib/dead.dart",
402
+ ])],
403
+ });
404
+ report.next_steps.push(crate::output::NextStep {
405
+ id: "trace-dead-file".to_owned(),
406
+ command: "dart-decimate inspect --format json --file lib/dead.dart".to_owned(),
407
+ reason: "Collect references before deleting the file".to_owned(),
408
+ });
409
+
410
+ let rendered = render_human_report_with_style(&report, Style::plain());
411
+
412
+ assert!(rendered.contains("Cleanup: 1 dead file"));
413
+ assert!(rendered.contains("Safe to delete: yes, after reviewing generated/dynamic usage"));
414
+ assert!(rendered.contains("Best: Delete the unreachable Dart file"));
415
+ assert!(rendered.contains("Next Steps"));
416
+ assert!(rendered.contains("Why: Collect references before deleting the file"));
417
+ }
418
+
419
+ #[test]
420
+ fn strips_control_characters_from_terminal_paths() {
421
+ let mut finding = cycle_finding(2);
422
+ finding.path = "lib/\x1b[31mbad.dart".to_owned();
423
+ finding.message = "Circular dependency includes lib/\x1b[31mbad.dart".to_owned();
424
+ finding.files = vec![
425
+ "lib/\x1b[31mbad.dart".to_owned(),
426
+ "lib/live.dart".to_owned(),
427
+ ];
428
+ let report = report_with_finding(finding);
429
+
430
+ let rendered = render_human_report_with_style(&report, Style::plain());
431
+
432
+ assert!(
433
+ !rendered
434
+ .chars()
435
+ .any(|character| { character.is_control() && character != '\n' })
436
+ );
437
+ assert!(!rendered.contains('\x1b'));
438
+ }
439
+
440
+ #[test]
441
+ fn renders_omitted_details_for_summary_only_failures() {
442
+ let mut report = report_with_finding(cycle_finding(2));
443
+ report.findings.clear();
444
+
445
+ let rendered = render_human_report_with_style(&report, Style::plain());
446
+
447
+ assert!(rendered.contains("Dart Decimate check: FAIL"));
448
+ assert!(rendered.contains("Findings: 1"));
449
+ assert!(rendered.contains("1 finding was omitted from this summary output."));
450
+ assert!(!rendered.contains("No findings. The selected Dart graph checks passed."));
451
+ }
452
+
453
+ fn report_with_finding(finding: Finding) -> JsonReport {
454
+ let mut summary = ReportSummary {
455
+ files: finding.files.len().max(1),
456
+ edges: finding.files.len(),
457
+ findings: 1,
458
+ ..ReportSummary::default()
459
+ };
460
+ match finding.kind {
461
+ FindingKind::CircularDependency => summary.cycles = 1,
462
+ FindingKind::DeadFile => summary.dead_files = 1,
463
+ _ => {}
464
+ }
465
+ JsonReport {
466
+ schema_version: "dart-decimate.report.v1".to_owned(),
467
+ kind: "combined".to_owned(),
468
+ tool: "dart-decimate".to_owned(),
469
+ command: ReportCommand::Check,
470
+ verdict: Verdict::Fail,
471
+ summary,
472
+ findings: vec![finding],
473
+ clone_groups: Vec::new(),
474
+ complexity: Vec::new(),
475
+ file_scores: Vec::new(),
476
+ hotspots: Vec::new(),
477
+ refactoring_targets: Vec::new(),
478
+ threshold_overrides: Vec::new(),
479
+ feature_flags: Vec::new(),
480
+ security_candidates: Vec::new(),
481
+ attack_surface: Vec::new(),
482
+ runtime_coverage: None,
483
+ next_steps: Vec::new(),
484
+ }
485
+ }
486
+
487
+ fn cycle_finding(count: usize) -> Finding {
488
+ let files = (0..count)
489
+ .map(|index| format!("lib/file_{index}.dart"))
490
+ .collect::<Vec<_>>();
491
+ let path = files[0].clone();
492
+ Finding {
493
+ rule_id: "dart-decimate/circular-dependency".to_owned(),
494
+ fingerprint: None,
495
+ kind: FindingKind::CircularDependency,
496
+ severity: Severity::Error,
497
+ message: format!("Circular dependency spans {count} Dart files"),
498
+ path: path.clone(),
499
+ line: 1,
500
+ column: 0,
501
+ safe_to_delete: false,
502
+ files,
503
+ edge: None,
504
+ actions: vec![
505
+ FindingAction::new(
506
+ "break-cycle",
507
+ "Move shared dependencies inward or invert one import edge",
508
+ false,
509
+ )
510
+ .with_dart_decimate_args([
511
+ "inspect",
512
+ "--format",
513
+ "json",
514
+ "--file",
515
+ path.as_str(),
516
+ ]),
517
+ ],
518
+ }
519
+ }
27
520
  }