Suggest Reviewers

Suggest Reviewers Helper

This skill provides a Python helper script that analyzes git blame data for the /git:suggest-reviewers command. The script handles the complex task of identifying which lines were changed and who authored the original code.

When to Use This Skill

Use this skill when implementing the /git:suggest-reviewers command. The helper script should be invoked during Step 3 of the command implementation (analyzing git blame for changed lines).

DO NOT implement git blame analysis manually - always use the provided analyze_blame.py script.

Prerequisites

• Python 3.6 or higher
• Git repository with commit history
• Git CLI available in PATH

Helper Script: analyze_blame.py

The analyze_blame.py script automates the complex process of:

1. Parsing git diff output to identify specific line ranges that were modified
2. Running git blame on only the changed line ranges (not entire files)
3. Extracting and aggregating author information with statistics
4. Filtering out bot accounts automatically

Usage

For uncommitted changes:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode uncommitted \
  --file path/to/file1.go \
  --file path/to/file2.py \
  --output json

For committed changes on a feature branch:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode committed \
  --base-branch main \
  --file path/to/file1.go \
  --file path/to/file2.py \
  --output json

Parameters

• --mode: Required. Either uncommitted or committed

  • uncommitted: Analyzes unstaged/staged changes against HEAD
  • committed: Analyzes committed changes against a base branch

• --base-branch: Required when mode is committed. The base branch to compare against (e.g., main, master)

• --file: Can be specified multiple times. Each file to analyze for blame information. Only changed files should be passed.

• --output: Output format. Default is json. Options:

  • json: Machine-readable JSON output
  • text: Human-readable text output

Output Format (JSON)

{
  "Author Name": {
    "line_count": 45,
    "most_recent_date": "2024-10-15T14:23:10",
    "files": ["file1.go", "file2.go"],
    "email": "author@example.com"
  },
  "Another Author": {
    "line_count": 23,
    "most_recent_date": "2024-09-20T09:15:33",
    "files": ["file3.py"],
    "email": "another@example.com"
  }
}

Output Fields

• line_count: Total number of modified lines authored by this person
• most_recent_date: ISO 8601 timestamp of their most recent contribution to the changed code
• files: Array of files where this author has contributions in the changed lines
• email: Author's email address from git commits

Bot Filtering

The script automatically filters out common bot accounts:

• GitHub bots (e.g., dependabot[bot], renovate[bot])
• CI bots (e.g., openshift-ci-robot, k8s-ci-robot)
• Generic bot patterns (any name containing [bot] or ending in -bot)

Implementation Steps

Step 1: Collect changed files

Before invoking the script, collect the list of changed files based on the scenario:

Uncommitted changes:

# Get staged and unstaged files
files=$(git diff --name-only --diff-filter=d HEAD)
files+=" $(git diff --name-only --diff-filter=d --cached)"

Committed changes:

# Get files changed from base branch
files=$(git diff --name-only --diff-filter=d ${base_branch}...HEAD)

Step 2: Invoke the script

Build the command with the appropriate mode and all changed files:

# Start building the command
cmd="python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py"

# Add mode
if [ "$has_uncommitted" = true ] || [ "$on_base_branch" = true ]; then
  cmd="$cmd --mode uncommitted"
else
  cmd="$cmd --mode committed --base-branch $base_branch"
fi

# Add each file
for file in $files; do
  cmd="$cmd --file $file"
done

# Add output format
cmd="$cmd --output json"

# Execute and capture JSON output
blame_data=$($cmd)

Step 3: Parse the output

The JSON output can be parsed using Python, jq, or any JSON parser:

# Example using jq to get top contributor
echo "$blame_data" | jq -r 'to_entries | sort_by(-.value.line_count) | .[0].key'

# Example using Python
python3 << EOF
import json
import sys

data = json.loads('''$blame_data''')

# Sort by line count
sorted_authors = sorted(data.items(), key=lambda x: x[1]['line_count'], reverse=True)

for author, stats in sorted_authors:
    print(f"{author}: {stats['line_count']} lines, last modified {stats['most_recent_date']}")
EOF

Step 4: Combine with OWNERS data

After getting blame data, merge it with OWNERS file information to produce the final ranked list of reviewers.

Error Handling

No changed files

If no files are passed to the script:

Error: No files specified. Use --file option at least once.

Resolution: Ensure you've detected changed files (via git diff --name-only) before invoking the script.

Invalid mode

If an invalid mode is specified:

Error: Invalid mode 'invalid'. Must be 'uncommitted' or 'committed'.

Resolution: Use either --mode uncommitted or --mode committed.

Missing base branch in committed mode

If --mode committed is used without --base-branch:

Error: --base-branch is required when mode is 'committed'.

Resolution: Provide the base branch: --base-branch main