Tommy/improve-ref-handling

[tommaso-moro]

Closes: #728

Overview

This PR significantly improves how we handle refs in the get_file_contents tool, after users reported the tool being often broken from bad ref handling.

The problem

Despite the tool description, models can pass as argument to the tool a ref formatted either as fully qualified (e.g. refs/heads/beanch_name) or as short user-friendly names (e.g. branch_name).

The get_repository_content endpoint from the Github API is able to handle both flexibly:

However, the get_reference endpoint doesn't (it requires a ref formatted in a specific way):

Our previous logic would fail often because it uses both endpoints but it was not handling user-friendly refs (e.g. branch_name, heads/branch_name, tag_name), which are often provided by models to the tool. This would thus break the tool.

The Solution

This PR introduces new, robust logic to resolve a ref by identifying the format in which it was provided and constructing a fully qualified ref accordingly. In short, the new resolveGitReference function now handles:

• Fully-Qualified refs: refs/heads/main
• Partially-Qualified refs: heads/main
• Short Name refs: main (discovering automatically if it's a branch or a tag)

This ensures that the tool can handle the most common ways in which the ref input is provided by the user.

Additionally, I added:

• Comprehensive tests that cover all new logic paths.
• I have added quite detailed comments to the function itself to make the resolution logic, which can be tedious, much easier to follow

Demo

[Copilot]

Pull Request Overview

This PR significantly improves the ref handling in the get_file_contents tool to better handle different ref formats that models commonly provide. The issue was that while the GitHub API's content endpoint can handle both fully-qualified refs (refs/heads/branch_name) and short names (branch_name), the reference endpoint requires fully-qualified refs, causing the tool to fail frequently.

Key changes:

• Enhanced resolveGitReference function with robust logic to handle fully-qualified, partially-qualified, and short name refs
• Added comprehensive test coverage for all ref resolution scenarios
• Improved error handling and logging for better diagnostics

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
pkg/github/repositories.go	Enhanced resolveGitReference function with improved ref resolution logic and detailed documentation
pkg/github/repositories_test.go	Added comprehensive test cases covering all ref format scenarios and error conditions

[almaleksia]

I really like this logic!
Left some comments, mostly flow and readability related.