1use std::collections::{BTreeMap, BTreeSet};
4
5use serde::{Deserialize, Serialize};
6
7use crate::SCAN_API_VERSION;
8
9const RECURRING_FILENAME_LIMIT: usize = 20;
10
11#[derive(Clone, Debug, Eq, PartialEq)]
13pub struct DirectoryObservation {
14 path: String,
15 file_names: Vec<String>,
16}
17
18impl DirectoryObservation {
19 #[must_use]
21 pub fn new(
22 path: impl Into<String>,
23 file_names: impl IntoIterator<Item = impl Into<String>>,
24 ) -> Self {
25 Self {
26 path: path.into(),
27 file_names: file_names.into_iter().map(Into::into).collect(),
28 }
29 }
30}
31
32#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
34#[serde(rename_all = "lowercase")]
35pub enum ScanSymlinkKind {
36 Directory,
38 File,
40 Other,
42}
43
44#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
46#[serde(rename_all = "kebab-case")]
47pub enum ScanSymlinkAction {
48 NotFollowed,
50}
51
52#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
54pub struct ScanSymlink {
55 pub path: String,
57 pub kind: ScanSymlinkKind,
59 pub action: ScanSymlinkAction,
61}
62
63impl ScanSymlink {
64 #[must_use]
66 pub fn new(path: impl Into<String>, kind: ScanSymlinkKind) -> Self {
67 Self {
68 path: path.into(),
69 kind,
70 action: ScanSymlinkAction::NotFollowed,
71 }
72 }
73}
74
75#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
77pub struct ScannedDirectory {
78 pub path: String,
80 pub depth: usize,
82 pub file_count: usize,
84 pub has_norm: bool,
86}
87
88#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
90pub struct ScanNaming {
91 pub directories: BTreeMap<String, usize>,
93 pub files: BTreeMap<String, usize>,
95}
96
97#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
99pub struct RecurringFilename {
100 pub name: String,
102 pub dir_count: usize,
104}
105
106#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
108pub struct NormCoverage {
109 pub total_dirs: usize,
111 pub dirs_with_norm: usize,
113 pub ratio: f64,
115}
116
117#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
119pub struct ScanResponse {
120 #[serde(rename = "apiVersion")]
122 pub api_version: String,
123 pub root: String,
125 pub directory_count: usize,
127 pub directories: Vec<ScannedDirectory>,
129 pub symlinks: Vec<ScanSymlink>,
131 pub naming: ScanNaming,
133 pub recurring_filenames: Vec<RecurringFilename>,
135 pub norm_coverage: NormCoverage,
137}
138
139impl ScanResponse {
140 #[must_use]
142 pub fn new(
143 mut observations: Vec<DirectoryObservation>,
144 mut symlinks: Vec<ScanSymlink>,
145 ) -> Self {
146 observations.sort_by(|left, right| left.path.cmp(&right.path));
147 symlinks.sort_by(|left, right| left.path.cmp(&right.path));
148
149 let mut directory_naming = BTreeMap::new();
150 let mut file_naming = BTreeMap::new();
151 let mut filename_counts = BTreeMap::new();
152 let mut directories = Vec::with_capacity(observations.len());
153 let mut dirs_with_norm: usize = 0;
154
155 for observation in observations {
156 if observation.path != "."
157 && let Some(name) = portable_file_name(&observation.path)
158 {
159 increment(&mut directory_naming, classify_name(name));
160 }
161 let has_norm = observation.file_names.iter().any(|name| name == ".norm");
162 if has_norm {
163 dirs_with_norm += 1;
164 }
165 let visible_files = observation
166 .file_names
167 .into_iter()
168 .filter(|name| !name.starts_with('.'))
169 .collect::<BTreeSet<_>>();
170 for name in &visible_files {
171 increment(&mut file_naming, classify_name(name));
172 increment(&mut filename_counts, name.clone());
173 }
174 directories.push(ScannedDirectory {
175 depth: portable_depth(&observation.path),
176 path: observation.path,
177 file_count: visible_files.len(),
178 has_norm,
179 });
180 }
181
182 for symlink in &symlinks {
183 if symlink.kind == ScanSymlinkKind::Directory
184 && let Some(name) = portable_file_name(&symlink.path)
185 {
186 increment(&mut directory_naming, classify_name(name));
187 }
188 }
189
190 let mut recurring_filenames = filename_counts
191 .into_iter()
192 .filter_map(|(name, dir_count)| {
193 (dir_count >= 2).then_some(RecurringFilename { name, dir_count })
194 })
195 .collect::<Vec<_>>();
196 recurring_filenames.sort_by(|left, right| {
197 right
198 .dir_count
199 .cmp(&left.dir_count)
200 .then_with(|| left.name.cmp(&right.name))
201 });
202 recurring_filenames.truncate(RECURRING_FILENAME_LIMIT);
203
204 let total_dirs = directories.len();
205 let thousandths = dirs_with_norm
206 .saturating_mul(1000)
207 .saturating_add(total_dirs / 2)
208 .checked_div(total_dirs)
209 .unwrap_or(0);
210 let ratio = f64::from(u32::try_from(thousandths).unwrap_or(1000)) / 1000.0;
211 Self {
212 api_version: SCAN_API_VERSION.to_owned(),
213 root: ".".to_owned(),
214 directory_count: total_dirs,
215 directories,
216 symlinks,
217 naming: ScanNaming {
218 directories: directory_naming,
219 files: file_naming,
220 },
221 recurring_filenames,
222 norm_coverage: NormCoverage {
223 total_dirs,
224 dirs_with_norm,
225 ratio,
226 },
227 }
228 }
229}
230
231#[must_use]
233pub fn is_ignored_directory(name: &str) -> bool {
234 matches!(
235 name,
236 ".git"
237 | "__pycache__"
238 | ".venv"
239 | "venv"
240 | "node_modules"
241 | ".mypy_cache"
242 | ".pytest_cache"
243 | ".idea"
244 | ".vscode"
245 | "dist"
246 | "build"
247 | "target"
248 )
249}
250
251#[must_use]
253pub fn classify_name(name: &str) -> String {
254 let stem = if name.starts_with('.') {
255 name
256 } else {
257 name.rsplit_once('.').map_or(name, |(stem, _)| stem)
258 };
259 if has_date_prefix(name) {
260 "date_prefix"
261 } else if is_delimited_ascii(stem, '-') {
262 "kebab-case"
263 } else if is_delimited_ascii(stem, '_') {
264 "snake_case"
265 } else if stem.is_empty() {
266 "mixed"
267 } else {
268 let has_upper = stem.chars().any(char::is_uppercase);
269 let has_lower = stem.chars().any(char::is_lowercase);
270 let alphanumeric = stem.chars().all(char::is_alphanumeric);
271 let upper_with_underscores = stem
272 .chars()
273 .filter(|character| *character != '_')
274 .all(char::is_alphanumeric);
275 let first = stem.chars().next();
276 if has_upper && !has_lower && upper_with_underscores {
277 "UPPER"
278 } else if first.is_some_and(char::is_uppercase) && has_lower && alphanumeric {
279 "PascalCase"
280 } else if first.is_some_and(char::is_lowercase) && has_upper && alphanumeric {
281 "camelCase"
282 } else if has_lower && !has_upper && alphanumeric {
283 "lowercase"
284 } else {
285 "mixed"
286 }
287 }
288 .to_owned()
289}
290
291fn increment(counts: &mut BTreeMap<String, usize>, key: String) {
292 *counts.entry(key).or_default() += 1;
293}
294
295fn portable_file_name(path: &str) -> Option<&str> {
296 path.rsplit('/').find(|component| !component.is_empty())
297}
298
299fn portable_depth(path: &str) -> usize {
300 if path == "." {
301 0
302 } else {
303 path.split('/')
304 .filter(|component| !component.is_empty())
305 .count()
306 }
307}
308
309fn is_delimited_ascii(value: &str, delimiter: char) -> bool {
310 value.contains(delimiter)
311 && value.split(delimiter).all(|part| {
312 !part.is_empty()
313 && part
314 .chars()
315 .all(|character| character.is_ascii_lowercase() || character.is_ascii_digit())
316 })
317}
318
319fn has_date_prefix(name: &str) -> bool {
320 let bytes = name.as_bytes();
321 let long = bytes.len() >= 11
322 && bytes[..4].iter().all(u8::is_ascii_digit)
323 && bytes.get(4) == Some(&b'-')
324 && bytes
325 .get(5..7)
326 .is_some_and(|part| part.iter().all(u8::is_ascii_digit))
327 && bytes.get(7) == Some(&b'-')
328 && bytes
329 .get(8..10)
330 .is_some_and(|part| part.iter().all(u8::is_ascii_digit))
331 && matches!(bytes.get(10), Some(b'-' | b'_'));
332 let compact = bytes.len() >= 9
333 && bytes[..8].iter().all(u8::is_ascii_digit)
334 && matches!(bytes.get(8), Some(b'-' | b'_'));
335 long || compact
336}
337
338#[cfg(test)]
339mod tests {
340 use std::collections::BTreeMap;
341
342 use super::{
343 DirectoryObservation, ScanResponse, ScanSymlink, ScanSymlinkKind, classify_name,
344 is_ignored_directory,
345 };
346
347 #[test]
348 fn naming_classification_covers_every_declared_bucket() {
349 for (name, expected) in [
350 ("2026-08-11-release.md", "date_prefix"),
351 ("my-module", "kebab-case"),
352 ("my_module.py", "snake_case"),
353 ("README.md", "UPPER"),
354 ("ModuleName", "PascalCase"),
355 ("moduleName", "camelCase"),
356 ("module.rs", "lowercase"),
357 ("module.name.rs", "mixed"),
358 ] {
359 assert_eq!(classify_name(name), expected);
360 }
361 }
362
363 #[test]
364 fn infrastructure_policy_is_explicit_and_bounded() {
365 for ignored in [
366 ".git",
367 "__pycache__",
368 ".venv",
369 "venv",
370 "node_modules",
371 ".mypy_cache",
372 ".pytest_cache",
373 ".idea",
374 ".vscode",
375 "dist",
376 "build",
377 "target",
378 ] {
379 assert!(is_ignored_directory(ignored));
380 }
381 assert!(!is_ignored_directory("docs"));
382 }
383
384 #[test]
385 fn response_aggregates_order_naming_recurrence_and_coverage() {
386 let response = ScanResponse::new(
387 vec![
388 DirectoryObservation::new("src", ["README.md", "lib.rs"]),
389 DirectoryObservation::new(".", ["README.md"]),
390 DirectoryObservation::new("docs", ["guide.md", ".norm"]),
391 ],
392 vec![ScanSymlink::new("linked-docs", ScanSymlinkKind::Directory)],
393 );
394 assert_eq!(response.directory_count, 3);
395 assert_eq!(response.directories[0].path, ".");
396 assert_eq!(response.directories[1].path, "docs");
397 assert_eq!(response.directories[1].file_count, 1);
398 assert!(response.directories[1].has_norm);
399 assert!((response.norm_coverage.ratio - 0.333).abs() < f64::EPSILON);
400 assert_eq!(response.recurring_filenames[0].name, "README.md");
401 assert_eq!(response.recurring_filenames[0].dir_count, 2);
402 assert_eq!(
403 response.naming.directories,
404 BTreeMap::from([("kebab-case".to_owned(), 1), ("lowercase".to_owned(), 2)])
405 );
406 assert_eq!(response.naming.files.get("UPPER"), Some(&2));
407 assert_eq!(response.symlinks[0].path, "linked-docs");
408 }
409
410 #[test]
411 fn recurring_filenames_are_stably_ordered_and_capped() {
412 let names = (0..=20)
413 .map(|index| format!("file-{index:02}"))
414 .collect::<Vec<_>>();
415 let response = ScanResponse::new(
416 vec![
417 DirectoryObservation::new("first", names.clone()),
418 DirectoryObservation::new("second", names),
419 ],
420 Vec::new(),
421 );
422 assert_eq!(response.recurring_filenames.len(), 20);
423 assert_eq!(response.recurring_filenames[0].name, "file-00");
424 assert_eq!(response.recurring_filenames[19].name, "file-19");
425 }
426}