Expose selected paths and format escaped selectors

[rsheldiii]

Shortcut Link

• TODO

Summary of Changes

Applications inspecting field selectors currently have to traverse the selection tree and implement escaping themselves. Add CompiledMask#each_path to yield decoded path segments and JsonMask.format_path to turn a path or prefix back into an escaped selector.

JsonMask.compile("id,assets(url,width)").each_path.to_a returns [["id"], ["assets", "url"], ["assets", "width"]]. JsonMask::WILDCARD distinguishes wildcard segments from a literal "*" field. Enumeration preserves the compiled selector's whole-field and terminal-wildcard behavior; formatting preserves literal names, including whitespace and NUL.

The APIs support consumers such as schema validators while keeping schema policy in the application. README examples and the changelog document the new contract. The version is prepared as 0.3.0.

Human Rationale

Bob wants MCP field validation to be easy to read, with small, decoupled abstractions. He chose path enumeration and formatting as general selector-library capabilities that can remove traversal and escaping code from Wistia. He asked for this PR to be reviewed before merging and publishing to RubyGems.

AI Usage

Codex implemented the APIs, documentation, and tests, then ran the full test/lint task and built the gem. A code-simplifier agent independently reviewed readability and correctness and checked 1,000 generated selector/value projection round trips without failures.

How to Test

Feature Flags

None.

Steps

• bundle exec rake — 53 tests, 271 assertions, no failures; RuboCop inspected all 13 Ruby files with no offenses.
• Coverage includes block and Enumerator use, nested selections, wildcards versus literal stars, redundant selections, blank selectors, path-array mutation isolation, every ASCII character, Unicode, and equivalent projection after formatting and recompiling.
• bundle exec rake build — successfully builds pkg/json-mask-0.3.0.gem.
• CI runs the test/lint task on Ruby 3.1, 3.2, 3.3, 3.4, and 4.0.

Screenshots / Videos (User-Facing Only)

BEFORE:

• Consumers recursively inspect selection_tree and escape diagnostic paths themselves.

AFTER:

• Consumers use mask.each_path and JsonMask.format_path(path).