Add --function_level command line option for specialized function-level localization

[Copilot]

This PR addresses the issue "函数级别的定位的命令应该是什么" (What should the command be for function-level localization?) by implementing a complete function-level localization feature for the Agentless fault localization system.

What's Changed

New CLI Option

Added --function_level command line argument that enables specialized function-level localization as an intermediate step between file-level and fine-grained line-level localization.

Key Features

• Targeted Function Localization: Uses existing localize_function_from_compressed_files and localize_function_from_raw_text methods specifically for function identification
• Seamless Pipeline Integration: Works with existing file-level outputs as input and feeds into fine-grained line-level localization
• Complete Output Structure: Includes found_function_locs, additional_artifact_loc_function, and function_loc_traj fields in results
• Flexible Usage: Can be used standalone or combined with other localization levels

Command Examples

Basic function-level localization:

python agentless/fl/localize.py --function_level \
    --output_folder results/function_level \
    --start_file results/file_level/loc_outputs.jsonl \
    --top_n 5 --compress

Complete localization pipeline:

# Step 1: Function-level localization
python agentless/fl/localize.py --function_level \
    --output_folder results/function_level \
    --start_file results/file_level/loc_outputs.jsonl \
    --top_n 3 --compress

# Step 2: Fine-grained localization using function results
python agentless/fl/localize.py --fine_grain_line_level \
    --output_folder results/edit_locations \
    --start_file results/function_level/loc_outputs.jsonl \
    --temperature 0.8 --num_samples 4

Updated Localization Hierarchy

The system now supports 4 distinct localization levels:

1. --file_level: Localize to suspicious files
2. --function_level: Localize to relevant functions (NEW)
3. --related_level: Localize to related code elements (classes, functions, variables)
4. --fine_grain_line_level: Localize to specific edit locations

Technical Implementation

• Argument Validation: Updated validation logic to support function_level as an alternative to related_level when used with fine_grain_line_level
• Data Flow: Modified fine_grain_line_level to use function_locs when function_level was used instead of related_locs
• Loading Support: Added capability to load existing function_locs from start_file for continued processing
• Documentation: Comprehensive updates to README with usage examples and integration patterns

Testing

Implemented comprehensive test suites validating:

• Argument parsing for all function_level combinations
• Validation logic for valid/invalid argument combinations
• Data flow between localization levels
• Output structure completeness

This change provides users with a more granular and focused approach to fault localization, specifically targeting functions when that level of precision is needed without the broader scope of related_level localization.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.