Add getRightmostFailure function for debugging match failures

[Copilot]

Overview

Added a new getRightmostFailure() function that traverses a MatchFail tree to find the failure with the greatest start span position. This helps debug parser failures by identifying where the parse actually got the furthest before failing.

Background

When a pattern fails to match, the resulting MatchFail can have a complex structure of nested failures with child matches. During debugging, the "rightmost" failure (the one that progressed furthest into the input) typically indicates where the actual problem is located.

Implementation

The new function:

• Recursively traverses the entire MatchFail tree
• Compares start positions using the existing Path.compareTo() method
• Returns the failure with the greatest start span
• Only processes MatchFail types (ignores MatchOk, MatchLR, MatchError)

Usage Example

import { match, MatchKind, getRightmostFailure } from "@justinmchase/uffda";

const result = match(pattern, scope);

if (result.kind === MatchKind.Fail) {
  const rightmost = getRightmostFailure(result);
  console.error(`Parse failed at position ${rightmost.span.start}`);
  console.error(`Pattern that failed: ${rightmost.pattern.name}`);
}

Testing

Added comprehensive unit tests in src/match.test.ts covering:

• Simple cases with no children
• Multiple children at different positions
• Deeply nested failures
• Complex trees with multiple branches
• Edge cases (empty children, mixed match types)

Closes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[debug]: Please add a function for matches which lets you find the "right most" failure</issue_title>
<issue_description>When a pattern fails to match the resulting Match can have a complex structure of inner matches, scopes and patterns.

Please make a function which can traverse a MatchFail and find the "right most" failure.

Right most is defined as match which is a "fail" but also has the greatest start span. Compare the scopes of matches and keep drilling into failure matches children finding the largest start scope.

For background we want to use this to debug a match failure, the right most failure is typically where the problem is.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #47

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.