wowlab_tidy/languages/rust/rules/api/

filesystem_boundary.rs

#[cfg(test)]
use googletest::prelude::*;
use ra_ap_syntax::{
    AstNode, NodeOrToken, SyntaxToken,
    ast::{self},
};

use crate::{AstCtx, Example, Violation};

#[rustfmt::skip]
const EXAMPLES: &[Example] = &[
    Example {
        label: "direct std fs call",
        code: "fn load() { let _ = std::fs::read(\"input\"); }",
        pass: false,
    },
    Example {
        label: "leading-colon std path",
        code: "fn take(_: &::std::path::Path) {}",
        pass: false,
    },
    Example {
        label: "grouped fs and path imports",
        code: "use std::{fs as native_fs, path::{Path, PathBuf}};",
        pass: false,
    },
    Example {
        label: "nested platform filesystem import",
        code: "use std::os::{unix::fs::PermissionsExt, windows::fs as windows_fs};",
        pass: false,
    },
    Example {
        label: "tempfile import alias",
        code: "use tempfile as scratch;",
        pass: false,
    },
    Example {
        label: "extern tempfile crate",
        code: "extern crate tempfile as scratch;",
        pass: false,
    },
    Example {
        label: "process temp directory",
        code: "fn scratch() { let _ = std::env::temp_dir(); }",
        pass: false,
    },
    Example {
        label: "filesystem path inside assertion macro",
        code: "fn verify() { assert!(std::path::Path::new(\"x\").is_absolute()); }",
        pass: false,
    },
    Example {
        label: "shared filesystem API",
        code: "use wowlab_fs::{file, path::Path};\nfn load(path: &Path) { let _ = file::read_text(path); }",
        pass: true,
    },
    Example {
        label: "unrelated path module",
        code: "fn normalize(path: custom::path::Path) {}",
        pass: true,
    },
    Example {
        label: "forbidden text in a string",
        code: "const HELP: &str = \"use std::fs instead\";",
        pass: true,
    },
    Example {
        label: "forbidden text in a comment",
        code: "// std::path is implemented behind the shared boundary",
        pass: true,
    },
];

crate::ast_rule!(
    filesystem_boundary,
    "Require filesystem and native-path access to go through `wowlab-fs`.",
    "One filesystem boundary gives the workspace consistent path vocabulary, temporary-file ownership, atomic persistence, symlink policy, and contextual errors.",
    High,
);

fn check_filesystem_boundary(ctx: &AstCtx<'_>) -> Vec<Violation> {
    let mut violations = Vec::new();
    let mut trees = Vec::new();

    for item in ctx.nodes::<ast::Use>() {
        let Some(root) = item.use_tree() else {
            continue;
        };

        trees.push(root);

        while let Some(tree) = trees.pop() {
            let segments = use_tree_segments(&tree);

            if let Some(forbidden) = forbidden_path(&segments) {
                violations.push(ctx.violation(
                    &tree,
                    format!(
                        "`{forbidden}` bypasses the shared filesystem boundary; use `wowlab-fs`"
                    ),
                ));

                continue;
            }

            if let Some(children) = tree.use_tree_list() {
                trees.extend(children.use_trees());
            }
        }
    }

    for path in ctx
        .nodes::<ast::Path>()
        .filter(|path| !inside_use_tree(path))
        .filter(is_outermost_path)
    {
        let segments = path_segments(&path);

        if let Some(forbidden) = forbidden_path(&segments) {
            violations.push(ctx.violation(
                &path,
                format!("`{forbidden}` bypasses the shared filesystem boundary; use `wowlab-fs`"),
            ));
        }
    }

    for item in ctx.nodes::<ast::ExternCrate>() {
        if item
            .name_ref()
            .is_some_and(|name| name.text() == "tempfile")
        {
            violations.push(ctx.violation(
                &item,
                "`tempfile` bypasses shared temporary-file ownership; use `wowlab-fs`",
            ));
        }
    }

    for expression in ctx.nodes::<ast::MacroExpr>() {
        let Some(call) = expression.macro_call() else {
            continue;
        };
        let Some(forbidden) = forbidden_macro_path(&call) else {
            continue;
        };

        violations.push(ctx.violation(
            &expression,
            format!(
                "`{forbidden}` inside a macro bypasses the shared filesystem boundary; use `wowlab-fs`"
            ),
        ));
    }

    violations
}

fn inside_use_tree(path: &ast::Path) -> bool {
    path.syntax()
        .ancestors()
        .skip(1)
        .any(|node| ast::UseTree::cast(node).is_some())
}

fn is_outermost_path(path: &ast::Path) -> bool {
    let nested = path
        .syntax()
        .ancestors()
        .skip(1)
        .any(|node| ast::Path::cast(node).is_some());

    !nested
}

fn path_segments(path: &ast::Path) -> Vec<ast::NameRef> {
    let mut segments = Vec::new();
    let mut current = Some(path.clone());

    while let Some(path) = current {
        if let Some(name) = path.segment().and_then(|segment| segment.name_ref()) {
            segments.push(name);
        }

        current = path.qualifier();
    }

    segments.reverse();

    segments
}

fn use_tree_segments(tree: &ast::UseTree) -> Vec<ast::NameRef> {
    let mut ancestors = tree
        .syntax()
        .ancestors()
        .filter_map(ast::UseTree::cast)
        .collect::<Vec<_>>();

    ancestors.reverse();

    let mut segments = Vec::new();

    for path in ancestors.into_iter().filter_map(|tree| tree.path()) {
        for segment in path_segments(&path) {
            if segment.text() != "self" {
                segments.push(segment);
            }
        }
    }

    segments
}

fn forbidden_path(segments: &[ast::NameRef]) -> Option<&'static str> {
    let first = segments.first()?.text();

    if first == "tempfile" {
        return Some("tempfile");
    }

    let [first, second, tail @ ..] = segments else {
        return None;
    };

    if first.text() != "std" {
        return None;
    }

    match second.text().as_str() {
        "fs" => Some("std::fs"),
        "path" => Some("std::path"),
        "env" if tail.first().is_some_and(|name| name.text() == "temp_dir") => {
            Some("std::env::temp_dir")
        }
        "os" if matches!(
            tail,
            [platform, filesystem, ..]
                if matches!(platform.text().as_str(), "unix" | "windows")
                    && filesystem.text() == "fs"
        ) =>
        {
            Some("std::os::*::fs")
        }
        _ => None,
    }
}

fn forbidden_macro_path(call: &ast::MacroCall) -> Option<&'static str> {
    const PATTERNS: &[(&str, &[&str])] = &[
        (
            "std::os::unix::fs",
            &["std", ":", ":", "os", ":", ":", "unix", ":", ":", "fs"],
        ),
        (
            "std::os::windows::fs",
            &["std", ":", ":", "os", ":", ":", "windows", ":", ":", "fs"],
        ),
        (
            "std::env::temp_dir",
            &["std", ":", ":", "env", ":", ":", "temp_dir"],
        ),
        ("std::fs", &["std", ":", ":", "fs"]),
        ("std::path", &["std", ":", ":", "path"]),
        ("tempfile", &["tempfile", ":", ":"]),
    ];

    let mut tokens = Vec::new();

    for element in call.syntax().descendants_with_tokens() {
        if let Some(token) = NodeOrToken::into_token(element)
            && !token.kind().is_trivia()
        {
            tokens.push(token);
        }
    }

    PATTERNS
        .iter()
        .find_map(|(name, pattern)| contains_token_sequence(&tokens, pattern).then_some(*name))
}

fn contains_token_sequence(tokens: &[SyntaxToken], pattern: &[&str]) -> bool {
    tokens.windows(pattern.len()).any(|window| {
        window
            .iter()
            .zip(pattern)
            .all(|(token, expected)| token.text() == *expected)
    })
}

crate::tidy_ast_test!(check_filesystem_boundary, {
    crate::example_tests!(EXAMPLES, check_filesystem_boundary);

    #[gtest]
    fn grouped_imports_report_forbidden_branches_once() -> Result<()> {
        let violations =
            run("use std::{fs as native_fs, path::{Path, PathBuf}, collections::HashMap};");

        verify_eq!(violations.len(), 2)
    }

    #[gtest]
    fn test_modules_do_not_bypass_the_boundary() -> Result<()> {
        let violations =
            run("#[cfg(test)]\nmod tests {\n    fn fixture() { std::fs::write(\"x\", \"y\"); }\n}");

        verify_eq!(violations.len(), 1)
    }
});