[BeckettFrey]

This pull request introduces several improvements and stricter validation to the prouter routing system, with a focus on robust error handling, collision detection, and clearer documentation. The most significant changes include stricter validation of route patterns, a new case-insensitive collision check for filesystems, improved error messages and exception types, and comprehensive tests for edge cases.

Major improvements and validation changes:

• Stricter validation and error handling:

  • Changed exception types for missing root paths and existing result files from ValueError to FileNotFoundError and FileExistsError respectively, providing more precise error reporting. [1] [2] [3]
  • Improved route pattern validation: patterns are now validated before mutating internal state, ensuring no partial updates on failure. Prevents duplicate input patterns and overlapping input/output patterns.
  • Added type and value checks to ensure route handler nodes only modify basenames and always return Path objects, raising clear exceptions for violations.

• Filesystem collision detection:

  • Added a _detect_case_insensitive method to determine if the underlying filesystem is case-insensitive (e.g., APFS, HFS+, NTFS), and replayed all planned renames in order to catch any namespace collisions, including those caused by case-only differences. [1] [2]

• Save operation validation:

  • The save method now raises exceptions if called before building the graph, if routes are undefined, or if required files already exist, making the workflow safer and more predictable. [1] [2]

Documentation and configuration:

• Improved documentation and usage examples:

  • Updated the README.md to clarify that the tool never modifies the filesystem, expanded explanations for route patterns, handler constraints, and error cases. [1] [2]

• Pattern configuration:

  • Added a new "Visit pattern" regex to the pyproject.toml for use in shredguard pattern matching.

Testing:

• Added comprehensive tests for the GraphBuilder:
  • New test suite in tests/test_graph_builder.py covers initialization, route addition, collision detection, handler constraints, ambiguous matches, and save logic, ensuring all edge cases and error conditions are exercised.