Skip to main content

norm_spec_core/
scan.rs

1//! Deterministic structural-scan classification and aggregation.
2
3use std::collections::{BTreeMap, BTreeSet};
4
5use serde::{Deserialize, Serialize};
6
7use crate::SCAN_API_VERSION;
8
9const RECURRING_FILENAME_LIMIT: usize = 20;
10
11/// Filesystem-neutral observation of one traversed directory.
12#[derive(Clone, Debug, Eq, PartialEq)]
13pub struct DirectoryObservation {
14    path: String,
15    file_names: Vec<String>,
16}
17
18impl DirectoryObservation {
19    /// Construct an observation from a portable relative path and regular files.
20    #[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/// Kind of symbolic link observed without traversal.
33#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
34#[serde(rename_all = "lowercase")]
35pub enum ScanSymlinkKind {
36    /// Link target is a directory.
37    Directory,
38    /// Link target is a regular file.
39    File,
40    /// Link target is unavailable or another filesystem object.
41    Other,
42}
43
44/// Action taken for an observed symbolic link.
45#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
46#[serde(rename_all = "kebab-case")]
47pub enum ScanSymlinkAction {
48    /// The scanner reported the link without following it.
49    NotFollowed,
50}
51
52/// Portable symbolic-link observation in a scan response.
53#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
54pub struct ScanSymlink {
55    /// Path relative to the scan root.
56    pub path: String,
57    /// Observed target kind.
58    pub kind: ScanSymlinkKind,
59    /// Explicit no-follow action.
60    pub action: ScanSymlinkAction,
61}
62
63impl ScanSymlink {
64    /// Construct a no-follow symbolic-link observation.
65    #[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/// One traversed directory summarized for machine output.
76#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
77pub struct ScannedDirectory {
78    /// Path relative to the scan root.
79    pub path: String,
80    /// Number of path components below the scan root.
81    pub depth: usize,
82    /// Number of visible regular files, excluding `.norm` and other dotfiles.
83    pub file_count: usize,
84    /// Whether the directory contains a regular `.norm` file.
85    pub has_norm: bool,
86}
87
88/// Naming-style counts collected from directories and visible files.
89#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
90pub struct ScanNaming {
91    /// Counts for non-root directories, including untraversed directory links.
92    pub directories: BTreeMap<String, usize>,
93    /// Counts for visible regular filenames.
94    pub files: BTreeMap<String, usize>,
95}
96
97/// Filename found in two or more traversed directories.
98#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
99pub struct RecurringFilename {
100    /// Exact filename including its extension.
101    pub name: String,
102    /// Number of distinct directories containing the filename.
103    pub dir_count: usize,
104}
105
106/// Aggregate `.norm` coverage across traversed directories.
107#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
108pub struct NormCoverage {
109    /// Total traversed directories, including the root.
110    pub total_dirs: usize,
111    /// Traversed directories containing a regular `.norm` file.
112    pub dirs_with_norm: usize,
113    /// Coverage ratio rounded to three decimal places.
114    pub ratio: f64,
115}
116
117/// Versioned deterministic structural-scan response.
118#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
119pub struct ScanResponse {
120    /// Version of the scan response protocol.
121    #[serde(rename = "apiVersion")]
122    pub api_version: String,
123    /// Root marker for every portable path in the response.
124    pub root: String,
125    /// Number of traversed directories.
126    pub directory_count: usize,
127    /// Traversed directories ordered by portable path.
128    pub directories: Vec<ScannedDirectory>,
129    /// Untraversed symbolic links ordered by portable path.
130    pub symlinks: Vec<ScanSymlink>,
131    /// Deterministic naming-style counts.
132    pub naming: ScanNaming,
133    /// Recurring filenames ordered by count descending and name ascending.
134    pub recurring_filenames: Vec<RecurringFilename>,
135    /// Aggregate convention-file coverage.
136    pub norm_coverage: NormCoverage,
137}
138
139impl ScanResponse {
140    /// Aggregate explicit traversal observations into the versioned response.
141    #[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/// Return whether a directory is infrastructure excluded from structural scan.
232#[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/// Classify one directory name or filename into a deterministic style bucket.
252#[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}