Address code review feedback - clarify comments and test docstrings

Co-authored-by: joocer <[email protected]>

Author: Copilot

opteryx/utils/paths.py

@@ -128,11 +128,11 @@ def match_wildcard(pattern: str, path: str) -> bool:
         >>> match_wildcard("bucket/path/*.parquet", "bucket/path/sub/file.parquet")
         False
     """
-    # Split pattern and path into parts
+    # Split pattern and path into parts using OS path separator for cross-platform compatibility
     pattern_parts = pattern.split(OS_SEP)
     path_parts = path.split(OS_SEP)
 
-    # Must have same number of parts for a match (unless using ** which we don't support yet)
+    # Must have same number of path parts for a match (wildcards don't cross directory boundaries)
     if len(pattern_parts) != len(path_parts):
         return False
 

tests/unit/utils/test_paths_wildcards.py

@@ -55,7 +55,14 @@ def test_split_wildcard_path():
 
 
 def test_match_wildcard():
-    """Test wildcard pattern matching with glob-like semantics"""
+    """
+    Test wildcard pattern matching with glob-like semantics.
+    
+    Glob-like semantics means wildcards don't cross directory boundaries:
+    - * matches any characters except path separators
+    - ? matches single character except path separators  
+    - [range] matches character range except path separators
+    """
     # Asterisk matches multiple characters (but not path separators)
     assert paths.match_wildcard("bucket/path/*.parquet", "bucket/path/file1.parquet") is True
     assert paths.match_wildcard("bucket/path/*.parquet", "bucket/path/file2.parquet") is True