feat(version-scanner): fix root anchoring in ignores, parametrize tests, and update docs

Author: chalmerlowe

scripts/version_scanner/README.md

@@ -45,12 +45,32 @@ pip install -r scripts/version_scanner/requirements.txt
 
 The scanner uses a YAML configuration file (`regex_config.yaml`) to define rules and regex patterns.
 
-## Ignoring Directories
+## Matrix File Format
 
-You can create a `.scannerignore` file in the directory you are scanning (usually the repo root) to list directories to skip, one per line.
+When using `--matrix-file`, you must provide a YAML file specifying dependencies and versions.
 
-## Known Issues & Future Investigations
-- **Binary Ignores in `.scannerignore`**: Recursive wildcard ignores (e.g., `*.jpg`) currently do not effectively ignore deeply nested binary files. The scanner logic should be investigated to support robust globbing or full-path suffix matching.
+### Example
+```yaml
+python:
+  - "3.10"
+  - "3.11"
+protobuf: "4.25.8"
+```
+
+> [!IMPORTANT]
+> **Versions must be specified as quoted strings** (e.g., `"3.10"`, not `3.10`). This prevents YAML parsers from converting them to floats (which would truncate `3.10` to `3.1`).
+
+## Ignoring Directories and Files
+
+In order to ignore files OR entire directories, you can add ignore patterns to the `.scannerignore` file located in the same directory as the script (`scripts/version_scanner/.scannerignore`). Ignore patterns should be added one per line.
+
+### Features
+- **Case-insensitive**: All patterns are matched case-insensitively.
+- **Globbing**: Supports standard shell globbing patterns (e.g., `*.jpg`, `test_*`).
+- **Subpaths**: You can specify subpaths (e.g., `packages/pkg_a/.nox`).
+- **Root Anchoring**: Patterns starting with a slash `/` are anchored to the root of the scan (e.g., `/packages` ignores the `packages` directory at root, but not `some/other/packages`).
+
+---
 
 ---
 

scripts/version_scanner/tests/unit/test_version_scanner.py

@@ -388,29 +388,25 @@ def test_scan_repository_wildcard_ignores(tmp_path):
         assert not match["file_path"].endswith("test.jpg")
 
 
-def test__should_ignore():
-    from version_scanner import _should_ignore
-    
-    ignore_patterns = [
-        ".git",
-        "*.jpg",
-        "packages/pkg_a/.nox",
-        "*.egg-info"
+DEFAULT_IGNORE_PATTERNS = [".git", "*.jpg", "packages/pkg_a/.nox", "*.egg-info"]
+
+@pytest.mark.parametrize(
+    "rel_path, name, ignore_patterns, expected",
+    [
+        pytest.param(".git", ".git", DEFAULT_IGNORE_PATTERNS, True, id="exact_match"),
+        pytest.param(".GIT", ".GIT", DEFAULT_IGNORE_PATTERNS, True, id="case_insensitive_match"),
+        pytest.param("some/path/image.jpg", "image.jpg", DEFAULT_IGNORE_PATTERNS, True, id="wildcard_subpath_match"),
+        pytest.param("image.JPG", "image.JPG", DEFAULT_IGNORE_PATTERNS, True, id="wildcard_case_insensitive_match"),
+        pytest.param("packages/pkg_a/.nox", ".nox", DEFAULT_IGNORE_PATTERNS, True, id="subpath_exact_match"),
+        pytest.param("google_cloud_pubsub.egg-info", "google_cloud_pubsub.egg-info", DEFAULT_IGNORE_PATTERNS, True, id="wildcard_directory_match"),
+        pytest.param("setup.py", "setup.py", DEFAULT_IGNORE_PATTERNS, False, id="no_match"),
+        pytest.param("packages", "packages", ["/packages"], True, id="anchored_root_match"),
+        pytest.param("some/other/packages", "packages", ["/packages"], False, id="anchored_root_nested_no_match"),
     ]
-    
-    # Exact match
-    assert _should_ignore(".git", ".git", ignore_patterns) is True
-    # Case insensitivity
-    assert _should_ignore(".GIT", ".GIT", ignore_patterns) is True
-    # Wildcard match
-    assert _should_ignore("some/path/image.jpg", "image.jpg", ignore_patterns) is True
-    assert _should_ignore("image.JPG", "image.JPG", ignore_patterns) is True
-    # Subpath match
-    assert _should_ignore("packages/pkg_a/.nox", ".nox", ignore_patterns) is True
-    # Wildcard directory match
-    assert _should_ignore("google_cloud_pubsub.egg-info", "google_cloud_pubsub.egg-info", ignore_patterns) is True
-    # Negative match
-    assert _should_ignore("setup.py", "setup.py", ignore_patterns) is False
+)
+def test__should_ignore(rel_path, name, ignore_patterns, expected):
+    from version_scanner import _should_ignore
+    assert _should_ignore(rel_path, name, ignore_patterns) is expected
 
 
 def test_load_ignore_file(tmp_path):

scripts/version_scanner/version_scanner.py

@@ -500,7 +500,19 @@ def read_package_file(file_path: str) -> List[str]:
 
 
 def _should_ignore(rel_path: str, name: str, ignore_patterns: List[str]) -> bool:
-    """Check if a file or directory matches any of the ignore patterns."""
+    """Check if a file or directory matches any of the ignore patterns.
+    
+    Directories and files can be ignored by providing an ignore pattern in the 
+    .scannerignore file.
+
+    Args:
+        rel_path: The relative path of the file or directory from the scan root.
+        name: The name of the file or directory (basename).
+        ignore_patterns: A list of ignore patterns (glob-like or subpaths).
+        
+    Returns:
+        True if the file or directory should be ignored, False otherwise.
+    """
     if not ignore_patterns:
         return False
     name_lower = name.lower()
@@ -511,10 +523,12 @@ def _should_ignore(rel_path: str, name: str, ignore_patterns: List[str]) -> bool
         if '/' in pattern:
             if pattern_lower.startswith('/'):
                 p = pattern_lower[1:]
+                if fnmatch.fnmatchcase(rel_path_norm, p):
+                    return True
             else:
                 p = pattern_lower
-            if fnmatch.fnmatchcase(rel_path_norm, p) or fnmatch.fnmatchcase(rel_path_norm, f"*/{p}"):
-                return True
+                if fnmatch.fnmatchcase(rel_path_norm, p) or fnmatch.fnmatchcase(rel_path_norm, f"*/{p}"):
+                    return True
         else:
             if fnmatch.fnmatchcase(name_lower, pattern_lower):
                 return True