1use std::collections::BTreeMap;
2use std::collections::BTreeSet;
3
4use anyhow::Context as _;
5use anyhow::Result;
6
7use super::markdown::inline_code;
8use super::model::Edge;
9use super::model::FileGraph;
10use super::model::FolderGraph;
11
12const NO_VIOLATIONS_FOUND: &str = "No outgoing dependency violations found.";
13
14#[derive(Clone, Copy)]
15pub enum Mode {
16 Files,
17 Folders,
18}
19
20impl Mode {
21 #[must_use]
22 const fn label(self) -> &'static str {
23 match self {
24 Self::Files => "files",
25 Self::Folders => "folders",
26 }
27 }
28}
29
30pub struct Analysis {
31 mode: Mode,
32 maximum: usize,
33 violations: BTreeMap<String, usize>,
34}
35
36impl Analysis {
37 pub fn files(graph: &FileGraph, maximum: usize) -> Result<Self> {
38 let violations = violating_sources(graph.edges().iter(), maximum).map(|(source, count)| {
39 let label = source.path().to_str().context("Outgoing dependency file path is not UTF-8")?;
40 Ok((label.to_owned(), count))
41 }).collect::<Result<_>>()?;
42 Ok(Self { mode: Mode::Files, maximum, violations })
43 }
44
45 #[must_use]
46 pub fn folders(graph: &FolderGraph, maximum: usize) -> Self {
47 let violations = violating_sources(graph.edges().keys(), maximum);
48 let violations = violations.map(|(source, count)| (source.label().clone(), count)).collect();
49 Self { mode: Mode::Folders, maximum, violations }
50 }
51
52 #[must_use]
53 pub fn has_violations(&self) -> bool {
54 !self.violations.is_empty()
55 }
56
57 #[must_use]
58 pub fn diagnostic(&self) -> String {
59 let mode = self.mode.label();
60 let mut output = if self.has_violations() {
61 format!(
62 "Outgoing dependency threshold exceeded (mode: {mode}, maximum: {}, violating sources: {}).\n",
63 self.maximum,
64 self.violations.len(),
65 )
66 } else {
67 format!("{NO_VIOLATIONS_FOUND} Mode: {mode}; maximum: {}.\n", self.maximum)
68 };
69 output.push_str(&self.violation_list(|label| format!("{label:?}")));
70 output
71 }
72
73 #[must_use]
74 pub fn markdown(&self) -> String {
75 let mode = self.mode.label();
76 let mut output = format!("# Outgoing dependency threshold\n\nMode: {mode}\n\nMaximum: {}\n\n", self.maximum);
77 if self.has_violations() {
78 output.push_str(&self.violation_list(inline_code));
79 } else {
80 output.push_str(NO_VIOLATIONS_FOUND);
81 output.push('\n');
82 }
83 output
84 }
85
86 #[must_use]
87 fn violation_list(&self, label: impl Fn(&str) -> String) -> String {
88 let mut output = String::new();
89 let maximum = self.maximum.to_string();
90 for (source, count) in &self.violations {
91 output.push_str("- ");
92 output.push_str(&label(source));
93 output.push_str(": ");
94 output.push_str(&count.to_string());
95 output.push_str(" outgoing dependencies (maximum: ");
96 output.push_str(&maximum);
97 output.push_str(")\n");
98 }
99 output
100 }
101}
102
103fn violating_sources<'a, Node: Ord + 'a>(
104 edges: impl Iterator<Item = &'a Edge<Node>>,
105 maximum: usize,
106) -> impl Iterator<Item = (&'a Node, usize)> {
107 let mut targets_by_source: BTreeMap<_, BTreeSet<_>> = BTreeMap::new();
108 for edge in edges {
109 targets_by_source.entry(edge.source()).or_default().insert(edge.target());
110 }
111 let counts = targets_by_source.into_iter().map(|(source, targets)| (source, targets.len()));
112 counts.filter(move |&(_, count)| count > maximum)
113}
114
115#[cfg(test)]
116mod tests {
117 use std::collections::BTreeMap;
118 use std::collections::BTreeSet;
119 use std::path::Path;
120 use std::path::PathBuf;
121
122 use anyhow::Error;
123 use anyhow::Result;
124 use claims::assert_ok;
125 use claims::assert_some;
126 use pretty_assertions::assert_eq;
127 use rstest::rstest;
128
129 use super::Analysis;
130 use super::Mode;
131 use super::NO_VIOLATIONS_FOUND;
132 use crate::SourcePath;
133 use crate::model::DependencyCount;
134 use crate::model::DependencyKind;
135 use crate::model::DependencyKind::Production;
136 use crate::model::DependencyKind::Test;
137 use crate::model::FileEdge;
138 use crate::model::FileGraph;
139 use crate::model::FileNode;
140 use crate::model::FolderEdge;
141 use crate::model::FolderGraph;
142 use crate::model::FolderNode;
143
144 fn file_node_fixture(path: PathBuf) -> Result<FileNode> {
145 SourcePath::new(path).map(FileNode::new)
146 }
147
148 fn graph_fixture(
149 dependencies: &[(&str, &str, DependencyKind, usize)],
150 isolated: &[&str],
151 ) -> Result<(FileGraph, FolderGraph)> {
152 let labels = dependencies.iter().flat_map(|&(source, target, _, _)| [source, target]);
153 let labels: BTreeSet<_> = labels.chain(isolated.iter().copied()).collect();
154 let files = labels.iter().map(|&label| file_node_fixture(label.into())).collect::<Result<_>>()?;
155 let file_edges = dependencies.iter().map(|&(source, target, kind, _)| {
156 Ok(FileEdge::new(file_node_fixture(source.into())?, file_node_fixture(target.into())?, kind))
157 }).collect::<Result<_>>()?;
158 let folders = labels.iter().map(|&label| FolderNode::new(label.into())).collect();
159 let folder_edges = dependencies.iter().map(|&(source, target, kind, weight)| {
160 let edge = FolderEdge::new(FolderNode::new(source.into()), FolderNode::new(target.into()), kind);
161 (edge, DependencyCount::new(weight))
162 }).collect();
163 Ok((FileGraph::new(files, file_edges)?, FolderGraph::new(folders, folder_edges)?))
164 }
165
166 #[rstest]
167 fn test_outgoing_direction(#[values(Mode::Files, Mode::Folders)] mode: Mode) {
168 let fixture = graph_fixture(&[
169 ("alpha", "sink", Production, 1),
170 ("beta", "sink", Production, 1),
171 ("gamma", "sink", Production, 1),
172 ("source", "alpha", Production, 1),
173 ("source", "beta", Production, 1),
174 ], &[]);
175 let (files, folders) = assert_ok!(fixture, "Incoming and outgoing dependencies must form valid graphs");
176
177 let system_under_test = match mode {
178 Mode::Files => Analysis::files(&files, 1),
179 Mode::Folders => Ok(Analysis::folders(&folders, 1)),
180 };
181 let system_under_test = assert_ok!(system_under_test, "Directed dependencies must support threshold analysis");
182
183 let expected = BTreeMap::from([(String::from("source"), 2)]);
184 assert_eq!(expected, system_under_test.violations, "Incoming dependencies must not contribute to the source count");
185 assert!(system_under_test.has_violations(), "Two outgoing targets must exceed a maximum of one");
186 }
187
188 #[rstest]
189 #[case::zero(0, true)]
190 #[case::above(1, true)]
191 #[case::equal(2, false)]
192 #[case::below(3, false)]
193 #[case::maximum(usize::MAX, false)]
194 fn test_distinct_targets_and_thresholds(
195 #[values(Mode::Files, Mode::Folders)] mode: Mode,
196 #[case] maximum: usize,
197 #[case] expected_violation: bool,
198 ) {
199 let fixture = graph_fixture(&[
200 ("source", "first", Production, usize::MAX),
201 ("source", "first", Test, usize::MAX),
202 ("source", "second", Test, 7),
203 ], &[]);
204 let (files, folders) = assert_ok!(fixture, "Mixed dependency kinds and large weights must form valid graphs");
205
206 let system_under_test = match mode {
207 Mode::Files => Analysis::files(&files, maximum),
208 Mode::Folders => Ok(Analysis::folders(&folders, maximum)),
209 };
210 let system_under_test = assert_ok!(system_under_test, "Threshold analysis must accept every usize maximum");
211
212 let expected = if expected_violation { BTreeMap::from([(String::from("source"), 2)]) } else { BTreeMap::new() };
213 assert_eq!(expected, system_under_test.violations, "Count distinct targets, not edge kinds or folder weights");
214 assert_eq!(expected_violation, system_under_test.has_violations(), "Only counts strictly above the maximum violate");
215 }
216
217 #[rstest]
218 #[case::empty(&[])]
219 #[case::isolated(&["isolated"])]
220 fn test_empty_and_isolated_reports(#[values(Mode::Files, Mode::Folders)] mode: Mode, #[case] isolated: &[&str]) {
221 let fixture = graph_fixture(&[], isolated);
222 let (files, folders) = assert_ok!(fixture, "Empty and isolated-node graphs must be valid");
223
224 let system_under_test = match mode {
225 Mode::Files => Analysis::files(&files, 0),
226 Mode::Folders => Ok(Analysis::folders(&folders, 0)),
227 };
228 let system_under_test = assert_ok!(system_under_test, "Graphs without edges must support threshold analysis");
229 let diagnostic = system_under_test.diagnostic();
230 let markdown = system_under_test.markdown();
231
232 assert!(!system_under_test.has_violations(), "An empty outgoing target set must satisfy a zero maximum");
233 assert!(diagnostic.contains(NO_VIOLATIONS_FOUND), "Diagnostic must explicitly state that no sources violate");
234 assert!(diagnostic.contains(&format!("Mode: {}; maximum: 0", mode.label())), "Diagnostic must identify its scope");
235 assert_eq!(Some(NO_VIOLATIONS_FOUND), markdown.lines().last(), "Markdown must explicitly state that no sources violate");
236 assert!(markdown.contains(&format!("Mode: {}", mode.label())), "Markdown must identify the analysis mode");
237 assert!(markdown.contains("Maximum: 0"), "Markdown must include the configured zero maximum");
238 assert!(!diagnostic.lines().any(|line| line.starts_with("- ")), "Diagnostic must not list isolated nodes");
239 assert!(!markdown.lines().any(|line| line.starts_with("- ")), "Markdown must not list isolated nodes");
240 }
241
242 #[rstest]
243 #[case::above(0, true)]
244 #[case::equal(1, false)]
245 fn test_self_edges(
246 #[values(Mode::Files, Mode::Folders)] mode: Mode,
247 #[case] maximum: usize,
248 #[case] expected_violation: bool,
249 ) {
250 let fixture = graph_fixture(&[("self", "self", Production, usize::MAX), ("self", "self", Test, 3)], &[]);
251 let (files, folders) = assert_ok!(fixture, "Self edges of both dependency kinds must form valid graphs");
252
253 let system_under_test = match mode {
254 Mode::Files => Analysis::files(&files, maximum),
255 Mode::Folders => Ok(Analysis::folders(&folders, maximum)),
256 };
257 let system_under_test = assert_ok!(system_under_test, "Self edges must support threshold analysis");
258
259 let expected = if expected_violation { BTreeMap::from([(String::from("self"), 1)]) } else { BTreeMap::new() };
260 assert_eq!(expected, system_under_test.violations, "A retained self edge must count as one distinct target");
261 assert_eq!(expected_violation, system_under_test.has_violations(), "Self-edge thresholds must use strict comparison");
262 }
263
264 #[rstest]
265 fn test_all_violations_in_sorted_order(#[values(Mode::Files, Mode::Folders)] mode: Mode) {
266 let fixture = graph_fixture(&[
267 ("zebra", "first", Production, 1),
268 ("zebra", "second", Test, 1),
269 ("middle", "first", Production, 1),
270 ("middle", "second", Production, 1),
271 ("alpha", "first", Production, 1),
272 ("alpha", "second", Production, 1),
273 ("alpha", "third", Production, 1),
274 ], &[]);
275 let (files, folders) = assert_ok!(fixture, "Several violating sources must form valid graphs");
276
277 let system_under_test = match mode {
278 Mode::Files => Analysis::files(&files, 1),
279 Mode::Folders => Ok(Analysis::folders(&folders, 1)),
280 };
281 let system_under_test = assert_ok!(system_under_test, "Every violating source must be analyzed");
282 let diagnostic = Error::msg(system_under_test.diagnostic()).to_string();
283 let markdown = system_under_test.markdown();
284 let diagnostic_lines: Vec<_> = diagnostic.lines().filter(|line| line.starts_with("- ")).collect();
285 let markdown_lines: Vec<_> = markdown.lines().filter(|line| line.starts_with("- ")).collect();
286
287 assert_eq!(vec![
288 "- \"alpha\": 3 outgoing dependencies (maximum: 1)",
289 "- \"middle\": 2 outgoing dependencies (maximum: 1)",
290 "- \"zebra\": 2 outgoing dependencies (maximum: 1)",
291 ], diagnostic_lines, "The complete error string must list all offending sources in label order");
292 assert_eq!(vec![
293 "- <code>alpha</code>: 3 outgoing dependencies (maximum: 1)",
294 "- <code>middle</code>: 2 outgoing dependencies (maximum: 1)",
295 "- <code>zebra</code>: 2 outgoing dependencies (maximum: 1)",
296 ], markdown_lines, "Markdown must list every source with its actual count and maximum");
297 let summary = format!("mode: {}, maximum: 1, violating sources: 3", mode.label());
298 assert!(diagnostic.contains(&summary), "The error summary must identify the mode, maximum, and violation total");
299 assert!(markdown.contains(&format!("Mode: {}", mode.label())), "Markdown must identify the analysis mode");
300 assert!(markdown.contains("Maximum: 1"), "Markdown must include the configured maximum");
301 }
302
303 #[test]
304 fn test_file_paths_and_folder_labels() {
305 let service = file_node_fixture(Path::new("src").join("api").join("deep").join("service.rs"));
306 let service = assert_ok!(service, "Nested source file must be a valid project-relative path");
307 let database = file_node_fixture(Path::new("src").join("storage").join("database.rs"));
308 let database = assert_ok!(database, "Target file must be a valid project-relative path");
309 let edge = FileEdge::new(service.clone(), database.clone(), Production);
310 let fixture = FileGraph::new(BTreeSet::from([service.clone(), database]), BTreeSet::from([edge]));
311 let fixture = assert_ok!(fixture, "Cross-folder dependency must form a valid file graph");
312 let folders = fixture.folders(Path::new("src"), Some(1), false);
313 let folders = assert_ok!(folders, "Folder aggregation must supply root-relative depth-folded labels");
314 let service_path = service.path().to_str();
315 let service_path = assert_some!(service_path, "Source fixture path must be UTF-8");
316
317 let system_under_test = Analysis::files(&fixture, 0);
318 let system_under_test = assert_ok!(system_under_test, "Nested source paths must support file threshold analysis");
319 let folder_analysis = Analysis::folders(&folders, 0);
320
321 let expected_files = BTreeMap::from([(service_path.to_owned(), 1)]);
322 assert_eq!(expected_files, system_under_test.violations, "File labels must retain the complete project-relative path");
323 let expected_folders = BTreeMap::from([(String::from("api"), 1)]);
324 assert_eq!(expected_folders, folder_analysis.violations, "Folder labels must come from the final aggregated graph");
325 let diagnostic_path = format!("{service_path:?}");
326 assert!(system_under_test.diagnostic().contains(&diagnostic_path), "Diagnostic must retain the complete file path");
327 }
328
329 #[rstest]
330 fn test_folder_self_edge_filtering(#[values(false, true)] include_self: bool) {
331 let service = file_node_fixture(Path::new("src").join("api").join("service.rs"));
332 let service = assert_ok!(service, "Service fixture path must be valid");
333 let request = file_node_fixture(Path::new("src").join("api").join("request.rs"));
334 let request = assert_ok!(request, "Request fixture path must be valid");
335 let edge = FileEdge::new(service.clone(), request.clone(), Production);
336 let fixture = FileGraph::new(BTreeSet::from([service, request]), BTreeSet::from([edge]));
337 let fixture = assert_ok!(fixture, "A dependency inside one folder must form a valid graph");
338 let folders = fixture.folders(Path::new("src"), None, include_self);
339 let folders = assert_ok!(folders, "Folder aggregation must apply the requested self-edge policy");
340
341 let system_under_test = Analysis::folders(&folders, 0);
342
343 let expected = if include_self { BTreeMap::from([(String::from("api"), 1)]) } else { BTreeMap::new() };
344 assert_eq!(expected, system_under_test.violations, "Analysis must count exactly the self edges retained by aggregation");
345 assert_eq!(include_self, system_under_test.has_violations(), "Analysis must not add or remove self edges");
346 }
347
348 #[rstest]
349 #[case("unsafe`<>&\n\r\t", "unsafe`<>&\n\r\t", "\"unsafe`<>&\\n\\r\\t\"")]
350 #[case("unsafe*[link]_\\~|", "unsafe*[link]_\~|", "\"unsafe*[link]_\\\\~|\"")]
351 #[case(
352 "unsafe\n## injected\n<script>alert(1)</script>",
353 "unsafe\n## injected\n<script>alert(1)</script>",
354 "\"unsafe\\n## injected\\n<script>alert(1)</script>\""
355 )]
356 fn test_report_label_escaping(
357 #[values(Mode::Files, Mode::Folders)] mode: Mode,
358 #[case] label: &str,
359 #[case] markdown_label: &str,
360 #[case] diagnostic_label: &str,
361 ) {
362 let fixture = graph_fixture(&[(label, "safe", Production, 1)], &[]);
363 let (files, folders) = assert_ok!(fixture, "Markup and control characters must be accepted as lexical graph labels");
364
365 let system_under_test = match mode {
366 Mode::Files => Analysis::files(&files, 0),
367 Mode::Folders => Ok(Analysis::folders(&folders, 0)),
368 };
369 let system_under_test = assert_ok!(system_under_test, "Special characters must not prevent threshold analysis");
370 let diagnostic = system_under_test.diagnostic();
371 let markdown = system_under_test.markdown();
372 let expected_diagnostic = format!("- {diagnostic_label}: 1 outgoing dependencies (maximum: 0)");
373 let expected_markdown = format!("- <code>{markdown_label}</code>: 1 outgoing dependencies (maximum: 0)");
374 let diagnostic_lines: Vec<_> = diagnostic.lines().filter(|line| line.starts_with("- ")).collect();
375 let markdown_lines: Vec<_> = markdown.lines().filter(|line| line.starts_with("- ")).collect();
376
377 assert_eq!(vec![expected_diagnostic.as_str()], diagnostic_lines, "Diagnostic labels must remain quoted on one line");
378 assert_eq!(vec![expected_markdown.as_str()], markdown_lines, "Markdown must preserve inline-code escaping");
379 assert!(!markdown.contains("<script>"), "A graph label must not inject HTML into the report");
380 assert!(!markdown.lines().any(|line| line.starts_with("## ")), "A graph label must not inject a report heading");
381 }
382
383 #[rstest]
384 #[case("unsafe\0\u{7}\u{1b}[31m\u{85}", "\"unsafe\\0\\u{7}\\u{1b}[31m\\u{85}\"")]
385 #[case("unsafe\u{2028}\u{202e}", "\"unsafe\\u{2028}\\u{202e}\"")]
386 #[case("quote\"and\\backslash", "\"quote\\\"and\\\\backslash\"")]
387 fn test_diagnostic_control_characters(
388 #[values(Mode::Files, Mode::Folders)] mode: Mode,
389 #[case] label: &str,
390 #[case] escaped: &str,
391 ) {
392 let fixture = graph_fixture(&[(label, "safe", Production, 1)], &[]);
393 let (files, folders) = assert_ok!(fixture, "Non-printing characters must be accepted as lexical graph labels");
394
395 let system_under_test = match mode {
396 Mode::Files => Analysis::files(&files, 0),
397 Mode::Folders => Ok(Analysis::folders(&folders, 0)),
398 };
399 let system_under_test = assert_ok!(system_under_test, "Control characters must not prevent threshold analysis");
400 let diagnostic = system_under_test.diagnostic();
401 let expected = format!("- {escaped}: 1 outgoing dependencies (maximum: 0)");
402
403 assert_eq!(Some(expected.as_str()), diagnostic.lines().last(), "Diagnostic labels must be quoted and control-safe");
404 assert!(diagnostic.chars().all(|character| character == '\n' || !character.is_control()), "Unsafe diagnostic control");
405 assert!(!diagnostic.contains('\u{202e}'), "A graph label must not change the diagnostic text direction");
406 }
407
408 #[cfg(any(unix, windows))]
409 #[rstest]
410 #[case::violating_path(0, true)]
411 #[case::nonviolating_path(1, false)]
412 fn test_file_path_encoding(#[case] maximum: usize, #[case] expected_error: bool) {
413 use std::ffi::OsString;
414
415 #[cfg(unix)]
416 let file_name = {
417 use std::os::unix::ffi::OsStringExt as _;
418 OsString::from_vec(vec![0xff])
419 };
420 #[cfg(windows)]
421 let file_name = {
422 use std::os::windows::ffi::OsStringExt as _;
423 OsString::from_wide(&[0xd800])
424 };
425 let file = file_node_fixture(file_name.into());
426 let file = assert_ok!(file, "A non-UTF-8 filename must remain a valid lexical source path");
427 let edge = FileEdge::new(file.clone(), file.clone(), Production);
428 let fixture = FileGraph::new(BTreeSet::from([file]), BTreeSet::from([edge]));
429 let fixture = assert_ok!(fixture, "A non-UTF-8 source must form a valid file graph");
430 let system_under_test = Analysis::files;
431
432 let result = system_under_test(&fixture, maximum);
433
434 assert_eq!(expected_error, result.is_err(), "Only reported source paths require lossless UTF-8 labels");
435 }
436}