@lithia-js/native 1.0.0-canary.2

package/src/router/transformer.rs

@@ -0,0 +1,281 @@
+//! Utilities to transform filesystem route file paths into normalized HTTP
+//! route paths and regular expressions used by the router.
+//!
+//! This module exposes the `PathTransformer` trait which defines the
+//! transformations required to convert a filesystem-style route (for example
+//! `users/[id]/route.ts`) into a normalized runtime path (`/users/:id/route`),
+//! a route regex and helper utilities. The `NativePathTransformer` implements
+//! the trait with the typical behaviour expected by the framework.
+//!
+//! Public API:
+//! - `PathTransformer` trait: abstraction used across the codebase to convert
+//!   and normalize paths.
+//! - `NativePathTransformer`: default implementation used by the native router.
+
+use regex::Regex;
+
+/// Trait that defines path transformation utilities used by the router.
+/// Implementors convert filesystem file paths into normalized route paths,
+/// detect dynamic segments, and produce regular expressions suitable for
+/// matching incoming requests.
+pub trait PathTransformer {
+    /// Transform a filesystem file path into a normalized route-like path.
+    ///
+    /// Example: `users/[id]/route.ts` -> `users/:id/route`.
+    fn transform_file_path(&self, path: &str) -> String;
+
+    /// Normalize a route path applying a global prefix, ensuring a leading
+    /// slash and removing trailing slashes where appropriate.
+    ///
+    /// Example: `("/users", "/api")` -> `/api/users`.
+    fn normalize_path(&self, path: &str, global_prefix: &str) -> String;
+
+    /// Return true when the supplied path contains dynamic segments (e.g.
+    /// `:id`).
+    fn is_dynamic_route(&self, path: &str) -> bool;
+
+    /// Generate a regular expression string from a normalized route path.
+    ///
+    /// Example: `/users/:id` -> `^/users/([^\/]+)$`.
+    fn generate_route_regex(&self, path: &str) -> String;
+
+    /// Clone the transformer as a boxed trait object.
+    fn clone_box(&self) -> Box<dyn PathTransformer>;
+}
+
+/// Join `base` and `path`, ensuring there is at most one separator between
+/// them. If `base` is empty, `path` is returned unchanged.
+fn with_base(path: &str, base: &str) -> String {
+    if base.is_empty() {
+        path.to_string()
+    } else {
+        format!(
+            "{}/{}",
+            base.trim_end_matches('/'),
+            path.trim_start_matches('/')
+        )
+    }
+}
+
+/// Ensure the provided `path` starts with a leading slash.
+fn with_leading_slash(path: &str) -> String {
+    if path.starts_with('/') {
+        path.to_string()
+    } else {
+        format!("/{}", path)
+    }
+}
+
+/// Remove a trailing slash from `path` except when the path is `/`.
+fn without_trailing_slash(path: &str) -> String {
+    if path.ends_with('/') && path.len() > 1 {
+        path.trim_end_matches('/').to_string()
+    } else {
+        path.to_string()
+    }
+}
+
+/// Default `PathTransformer` implementation used by the native router.
+/// It converts filesystem route file names and patterns (including dynamic
+/// segments like `[id]` and catch-all `[...path]`) into normalized runtime
+/// path templates and regexes.
+#[derive(Clone)]
+pub struct NativePathTransformer {
+    remove_ext: Regex,
+    remove_groups: Regex,
+    catch_all_named: Regex,
+    catch_all: Regex,
+    dynamic: Regex,
+    dynamic_detector: Regex,
+    route_param: Regex,
+}
+
+impl NativePathTransformer {
+    /// Construct a new `NativePathTransformer` with precompiled regular
+    /// expressions tuned for route syntax used by the framework.
+    pub fn new() -> Self {
+        Self {
+            remove_ext: Regex::new(r"\.[A-Za-z]+$").unwrap(),
+            remove_groups: Regex::new(r"\(([^(/\\]+)\)[/\\]").unwrap(),
+            catch_all_named: Regex::new(r"\[\.\.\.(\w+)\]").unwrap(),
+            catch_all: Regex::new(r"\[\.\.\.]").unwrap(),
+            dynamic: Regex::new(r"\[([^/\]]+)\]").unwrap(),
+            dynamic_detector: Regex::new(r":\w+").unwrap(),
+            route_param: Regex::new(r":(\w+)").unwrap(),
+        }
+    }
+}
+
+impl PathTransformer for NativePathTransformer {
+    fn transform_file_path(&self, path: &str) -> String {
+        let mut result = path.to_string();
+
+        result = self.remove_ext.replace(&result, "").to_string();
+        result = self.remove_groups.replace(&result, "").to_string();
+        result = self
+            .catch_all_named
+            .replace_all(&result, "**:$1")
+            .to_string();
+        result = self.catch_all.replace_all(&result, "**").to_string();
+        result = self.dynamic.replace_all(&result, ":$1").to_string();
+        result = result.replace('\\', "/");
+
+        result
+    }
+
+    fn normalize_path(&self, path: &str, global_prefix: &str) -> String {
+        let combined = with_base(path, global_prefix);
+        let no_trailing = without_trailing_slash(&combined);
+        with_leading_slash(&no_trailing)
+    }
+
+    fn is_dynamic_route(&self, path: &str) -> bool {
+        self.dynamic_detector.is_match(path)
+    }
+
+    fn generate_route_regex(&self, path: &str) -> String {
+        let escaped = path.replace('/', r"\/");
+
+        let regex_body = self
+            .route_param
+            .replace_all(&escaped, r"([^\/]+)")
+            .to_string();
+
+        format!("^{}$", regex_body)
+    }
+
+    fn clone_box(&self) -> Box<dyn PathTransformer> {
+        Box::new(self.clone())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use regex::Regex;
+
+    fn transformer() -> NativePathTransformer {
+        NativePathTransformer::new()
+    }
+
+    #[test]
+    fn transform_file_path_removes_extension() {
+        let t = transformer();
+        assert_eq!(t.transform_file_path("users/route.ts"), "users/route")
+    }
+
+    #[test]
+    fn transform_file_path_removes_route_groups() {
+        let t = transformer();
+        assert_eq!(t.transform_file_path("(v1)/users/route.ts"), "users/route")
+    }
+
+    #[test]
+    fn transform_file_path_dynamic_segments() {
+        let t = transformer();
+        assert_eq!(
+            t.transform_file_path("users/[id]/route.ts"),
+            "users/:id/route"
+        )
+    }
+
+    #[test]
+    fn transform_file_path_multiple_dynamic_segments() {
+        let t = transformer();
+        assert_eq!(
+            t.transform_file_path("users/[userId]/posts/[postId]/route.ts"),
+            "users/:userId/posts/:postId/route"
+        )
+    }
+
+    #[test]
+    fn transform_file_path_catch_all_named() {
+        let t = transformer();
+        assert_eq!(
+            t.transform_file_path("files/[...path]/route.ts"),
+            "files/**:path/route"
+        )
+    }
+
+    #[test]
+    fn transform_file_path_catch_all_unnamed() {
+        let t = transformer();
+        assert_eq!(
+            t.transform_file_path("files/[...]/route.ts"),
+            "files/**/route"
+        )
+    }
+
+    #[test]
+    fn transform_file_path_normalizes_windows_separators() {
+        let t = transformer();
+        assert_eq!(
+            t.transform_file_path(r"users\[id]\route.ts"),
+            "users/:id/route"
+        )
+    }
+
+    #[test]
+    fn normalize_path_applies_global_prefix() {
+        let t = transformer();
+        assert_eq!(t.normalize_path("/users", "/api"), "/api/users")
+    }
+
+    #[test]
+    fn normalize_path_removes_trailing_slash() {
+        let t = transformer();
+        assert_eq!(t.normalize_path("/users/", ""), "/users")
+    }
+
+    #[test]
+    fn normalize_path_ensures_leading_slash() {
+        let t = transformer();
+        assert_eq!(t.normalize_path("users", ""), "/users")
+    }
+
+    #[test]
+    fn detects_dynamic_route() {
+        let t = transformer();
+        assert!(t.is_dynamic_route("/users/:id"));
+    }
+
+    #[test]
+    fn detects_static_route() {
+        let t = transformer();
+        assert!(!t.is_dynamic_route("/about"));
+    }
+
+    #[test]
+    fn generate_route_regex_static() {
+      let t = transformer();
+      let regex_str = t.generate_route_regex("/about");
+      let regex = Regex::new(&regex_str).unwrap();
+
+      assert!(regex.is_match("/about"));
+      assert!(!regex.is_match("/about/us"));
+    }
+
+    #[test]
+    fn generate_route_regex_dynamic() {
+      let t = transformer();
+      let regex_str = t.generate_route_regex("/users/:id");
+      let regex = Regex::new(&regex_str).unwrap();
+
+      assert!(regex.is_match("/users/123"));
+      assert!(regex.is_match("/users/abc"));
+      assert!(!regex.is_match("/users/"));
+      assert!(!regex.is_match("/users/123/profile"));
+    }
+
+    #[test]
+    fn generate_route_regex_nested_dynamic() {
+      let t = transformer();
+      let regex_str = t.generate_route_regex("/users/:userId/posts/:postId");
+      let regex = Regex::new(&regex_str).unwrap();
+
+      assert!(regex.is_match("/users/42/posts/100"));
+      assert!(regex.is_match("/users/john/posts/abc"));
+      assert!(!regex.is_match("/users/42/posts/"));
+      assert!(!regex.is_match("/users/42/posts/100/comments"));
+    }
+}

package/src/scanner/mod.rs

@@ -0,0 +1,345 @@
+//! Utilities for scanning project directories and matching files using glob patterns.
+//!
+//! This module exposes a small, focused file scanner implemented in Rust that is
+//! used by the native builder to discover route files and other project
+//! artifacts. It provides a simple `FileScanner` trait and a `NativeFileScanner`
+//! concrete implementation that walks directories, applies include/ignore glob
+//! patterns and returns structured `FileInfo` results.
+//!
+//! The scanner intentionally keeps behaviour minimal and deterministic:
+//! - Includes are required: if no include patterns are provided, an empty list
+//!   is returned.
+//! - Ignore patterns are optional and applied after include matching.
+//! - Returned file paths are sorted by their relative path to ensure stable
+//!   ordering across runs.
+
+use globset::{Glob, GlobSetBuilder};
+use napi_derive::napi;
+
+use std::io;
+
+/// Information about a discovered file.
+/// - `path` is the path relative to the scanned directory (using `/` as
+///   separator on all platforms).
+/// - `full_path` is the absolute filesystem path to the file.
+#[napi(object)]
+#[derive(Debug, Clone)]
+pub struct FileInfo {
+    /// Relative path from the scanned directory
+    pub path: String,
+
+    /// Absolute path from the filesystem root
+    pub full_path: String,
+}
+
+/// Options controlling scanning behaviour.
+/// - `include`: list of glob patterns that select files to include. If
+///   omitted or empty, the scanner returns an empty result set.
+/// - `ignore`: optional list of glob patterns used to exclude matching files
+///   from the previously included set.
+#[napi(object)]
+#[derive(Debug, Clone, Default)]
+pub struct ScanOptions {
+    /// Glob patterns to include files.
+    pub include: Option<Vec<String>>,
+
+    /// Glob patterns to ignore (applied after include matching).
+    pub ignore: Option<Vec<String>>,
+}
+
+/// Trait that abstracts a directory scanner used by the native build system.
+/// Implementors must return a list of `FileInfo` entries corresponding to the
+/// files discovered under the provided `path_components` directory. This trait
+/// is intentionally small to make testing and mocking straightforward in
+/// higher-level code.
+pub trait FileScanner {
+    /// Scan a directory described by `path_components` and return matching
+    /// `FileInfo` entries.
+    /// `path_components` is a slice of path segments that will be joined onto
+    /// the current working directory to form the target scanning directory.
+    /// `options` may contain include/ignore glob patterns.
+    fn scan_dir(
+        &self,
+        path_components: &[String],
+        options: Option<ScanOptions>,
+    ) -> io::Result<Vec<FileInfo>>;
+}
+
+/// Native `FileScanner` implementation that walks the filesystem using
+/// `walkdir` and matches paths against glob patterns using `globset`.
+/// This scanner is fast enough for typical project sizes and deterministic
+/// because it sorts results by relative path before returning them.
+#[derive(Debug, Clone)]
+pub struct NativeFileScanner;
+
+impl NativeFileScanner {
+    /// Create a new `NativeFileScanner` instance.
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl FileScanner for NativeFileScanner {
+    fn scan_dir(
+        &self,
+        path_components: &[String],
+        options: Option<ScanOptions>,
+    ) -> io::Result<Vec<FileInfo>> {
+        let cwd = std::env::current_dir()?;
+        let mut target_path = cwd;
+
+        for part in path_components {
+            target_path = target_path.join(part);
+        }
+
+        if !target_path.exists() {
+            return Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("Target directory {:?} does not exist", target_path),
+            ));
+        }
+
+        let options = options.unwrap_or_default();
+
+        let include_patterns = match options.include {
+            Some(patterns) if !patterns.is_empty() => patterns,
+            _ => return Ok(Vec::new()),
+        };
+
+        let mut include_builder = GlobSetBuilder::new();
+        for pattern in &include_patterns {
+            let glob = Glob::new(pattern).map_err(|e| {
+                io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("Invalid include glob pattern '{}': {}", pattern, e),
+                )
+            })?;
+            include_builder.add(glob);
+        }
+        let include_matcher = include_builder.build().map_err(|e| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("Failed to build include matcher: {}", e),
+            )
+        })?;
+
+        let ignore_matcher = if let Some(ignore_patterns) = options.ignore {
+            let mut ignore_builder = GlobSetBuilder::new();
+            for pattern in &ignore_patterns {
+                let glob = Glob::new(pattern).map_err(|e| {
+                    io::Error::new(
+                        io::ErrorKind::InvalidInput,
+                        format!("Invalid ignore glob pattern '{}': {}", pattern, e),
+                    )
+                })?;
+                ignore_builder.add(glob);
+            }
+            Some(ignore_builder.build().map_err(|e| {
+                io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("Failed to build ignore matcher: {}", e),
+                )
+            })?)
+        } else {
+            None
+        };
+
+        let mut file_infos: Vec<FileInfo> = Vec::new();
+
+        for entry in walkdir::WalkDir::new(&target_path)
+            .into_iter()
+            .filter_map(|e| e.ok())
+            .filter(|e| e.file_type().is_file())
+        {
+            let path = entry.path();
+            let relative = path
+                .strip_prefix(&target_path)
+                .unwrap_or(path)
+                .to_string_lossy()
+                .replace('\\', "/");
+
+            if !include_matcher.is_match(&relative) {
+                continue;
+            }
+
+            if let Some(ref ignore) = ignore_matcher {
+                if ignore.is_match(&relative) {
+                    continue;
+                }
+            }
+
+            file_infos.push(FileInfo {
+                full_path: path.to_string_lossy().to_string(),
+                path: relative,
+            });
+        }
+
+        file_infos.sort_by(|a, b| a.path.cmp(&b.path));
+
+        Ok(file_infos)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::{fs, path::Path};
+    use tempfile::TempDir;
+
+    fn create_test_files(dir: &Path) -> io::Result<()> {
+        fs::create_dir_all(dir.join("src"))?;
+        fs::create_dir_all(dir.join("dist"))?;
+        fs::create_dir_all(dir.join("tests"))?;
+
+        // TypeScript files
+        fs::write(dir.join("src/index.ts"), "export default {}")?;
+        fs::write(dir.join("src/utils.ts"), "export const util = 1")?;
+
+        // JavaScript files
+        fs::write(dir.join("src/legacy.js"), "module.exports = {}")?;
+
+        // Test files
+        fs::write(dir.join("tests/index.test.ts"), "test('works', () => {})")?;
+
+        // JSON files
+        fs::write(dir.join("package.json"), "{}")?;
+        fs::write(dir.join("tsconfig.json"), "{}")?;
+
+        // Build output
+        fs::write(dir.join("dist/index.js"), "console.log('built')")?;
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_scan_with_default_ts_pattern() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(&[temp_dir.path().to_string_lossy().to_string()], None)
+            .unwrap();
+
+        // Sem include patterns, não deve retornar nada
+        assert_eq!(result.len(), 0);
+    }
+
+    #[test]
+    fn test_scan_typescript_files() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(
+                &[temp_dir.path().to_string_lossy().to_string()],
+                Some(ScanOptions {
+                    include: Some(vec!["**/*.ts".to_string()]),
+                    ignore: None,
+                }),
+            )
+            .unwrap();
+
+        // Deve encontrar apenas .ts files
+        let paths: Vec<_> = result.iter().map(|f| f.path.as_str()).collect();
+        assert_eq!(paths.len(), 3);
+        assert!(paths.contains(&"src/index.ts"));
+        assert!(paths.contains(&"src/utils.ts"));
+        assert!(paths.contains(&"tests/index.test.ts"));
+    }
+
+    #[test]
+    fn test_scan_with_custom_include_patterns() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(
+                &[temp_dir.path().to_string_lossy().to_string()],
+                Some(ScanOptions {
+                    include: Some(vec!["**/*.ts".to_string(), "**/*.js".to_string()]),
+                    ignore: None,
+                }),
+            )
+            .unwrap();
+
+        let paths: Vec<_> = result.iter().map(|f| f.path.as_str()).collect();
+        assert_eq!(paths.len(), 5); // 3 .ts + 2 .js files
+        assert!(paths.contains(&"src/legacy.js"));
+        assert!(paths.contains(&"dist/index.js"));
+    }
+
+    #[test]
+    fn test_scan_with_ignore_patterns() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(
+                &[temp_dir.path().to_string_lossy().to_string()],
+                Some(ScanOptions {
+                    include: Some(vec!["**/*.ts".to_string(), "**/*.js".to_string()]),
+                    ignore: Some(vec!["**/*.test.ts".to_string(), "**/dist/**".to_string()]),
+                }),
+            )
+            .unwrap();
+
+        let paths: Vec<_> = result.iter().map(|f| f.path.as_str()).collect();
+        // Should exclude test files and dist folder
+        assert_eq!(paths.len(), 3);
+        assert!(paths.contains(&"src/index.ts"));
+        assert!(paths.contains(&"src/utils.ts"));
+        assert!(paths.contains(&"src/legacy.js"));
+        assert!(!paths.contains(&"tests/index.test.ts"));
+        assert!(!paths.contains(&"dist/index.js"));
+    }
+
+    #[test]
+    fn test_scan_json_files_only() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(
+                &[temp_dir.path().to_string_lossy().to_string()],
+                Some(ScanOptions {
+                    include: Some(vec!["**/*.json".to_string()]),
+                    ignore: None,
+                }),
+            )
+            .unwrap();
+
+        let paths: Vec<_> = result.iter().map(|f| f.path.as_str()).collect();
+        assert_eq!(paths.len(), 2);
+        assert!(paths.contains(&"package.json"));
+        assert!(paths.contains(&"tsconfig.json"));
+    }
+
+    #[test]
+    fn test_scan_specific_directory_with_globs() {
+        let temp_dir = TempDir::new().unwrap();
+        create_test_files(temp_dir.path()).unwrap();
+
+        let scanner = NativeFileScanner::new();
+        let result = scanner
+            .scan_dir(
+                &[temp_dir.path().to_string_lossy().to_string()],
+                Some(ScanOptions {
+                    include: Some(vec!["src/**/*.ts".to_string()]),
+                    ignore: None,
+                }),
+            )
+            .unwrap();
+
+        let paths: Vec<_> = result.iter().map(|f| f.path.as_str()).collect();
+        // Only src/ directory .ts files
+        assert_eq!(paths.len(), 2);
+        assert!(paths.contains(&"src/index.ts"));
+        assert!(paths.contains(&"src/utils.ts"));
+        assert!(!paths.contains(&"tests/index.test.ts"));
+    }
+}