Github Code Review

Рецензирование PR: дифы, инлайн-комментарии через gh или REST.

Метаданные навыка

Источник	Встроенный (установлен по умолчанию)
Путь	skills/github/github-code-review
Версия	1.1.0
Автор	VibeOS
Лицензия	MIT
Платформы	linux, macos, windows
Теги	GitHub, Code-Review, Pull-Requests, Git, Quality
Связанные навыки	github-auth, github-pr-workflow

Справочник: полный SKILL.md

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

GitHub Code Review

Выполняйте рецензирование кода локальных изменений перед отправкой или рецензируйте открытые PR на GitHub. Большая часть этого навыка использует обычный git — разделение gh/curl имеет значение только для взаимодействия с PR.

Предварительные требования

• Аутентификация на GitHub (см. навык github-auth)
• Нахождение внутри git-репозитория

Настройка (для взаимодействия с PR)

if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if _vibeos_env="${VIBEOS_HOME:-$HOME/.vibeos}/.env"; [ -f "$_vibeos_env" ] && grep -q "^GITHUB_TOKEN=" "$_vibeos_env"; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_vibeos_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
    fi
  fi
fi

REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)

---

1. Рецензирование локальных изменений (перед отправкой)

Это чистый git — работает везде, API не требуется.

Получение диффа

# Индексированные изменения (то, что будет закоммичено)
git diff --staged

# Все изменения относительно main (то, что будет в PR)
git diff main...HEAD

# Только имена файлов
git diff main...HEAD --name-only

# Сводка статистики (вставки/удаления по файлам)
git diff main...HEAD --stat

Стратегия рецензирования

1. Сначала получите общую картину:

git diff main...HEAD --stat
git log main..HEAD --oneline

2. Рецензируйте файл за файлом — используйте read_file для изменённых файлов для полного контекста, а diff — чтобы увидеть, что изменилось:

git diff main...HEAD -- src/auth/login.py

3. Проверьте на типичные проблемы:

# Отладочные операторы, TODO, console.log, оставленные в коде
git diff main...HEAD | grep -n "print(\|console\.log\|TODO\|FIXME\|HACK\|XXX\|debugger"

# Случайно проиндексированные большие файлы
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10

# Секреты или паттерны учётных данных
git diff main...HEAD | grep -in "password\|secret\|api_key\|token.*=\|private_key"

# Маркеры конфликтов слияния
git diff main...HEAD | grep -n "<<<<<<\|>>>>>>\|======="

4. Предоставьте структурированную обратную связь пользователю.

Формат вывода рецензии

При рецензировании локальных изменений представляйте результаты в следующей структуре:

## Сводка рецензии кода

### Критично
- **src/auth.py:45** — SQL-инъекция: пользовательский ввод передаётся напрямую в запрос.
  Предложение: Используйте параметризованные запросы.

### Предупреждения
- **src/models/user.py:23** — Пароль хранится в открытом виде. Используйте bcrypt или argon2.
- **src/api/routes.py:112** — Отсутствует ограничение скорости на эндпоинте входа.

### Предложения
- **src/utils/helpers.py:8** — Дублирует логику в `src/core/utils.py:34`. Объедините.
- **tests/test_auth.py** — Не хватает граничного случая: тест с истёкшим токеном.

### Выглядит хорошо
- Чистое разделение ответственности в слое middleware
- Хорошее покрытие тестами сценария «happy path»

---

2. Рецензирование Pull Request на GitHub

Просмотр деталей PR

С помощью gh:

gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only

С помощью git + curl:

PR_NUMBER=123

# Получить детали PR
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "
import sys, json
pr = json.load(sys.stdin)
print(f\"Title: {pr['title']}\")
print(f\"Author: {pr['user']['login']}\")
print(f\"Branch: {pr['head']['ref']} -> {pr['base']['ref']}\")
print(f\"State: {pr['state']}\")
print(f\"Body:\n{pr['body']}\")"

# Список изменённых файлов
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/files \
  | python3 -c "
import sys, json
for f in json.load(sys.stdin):
    print(f\"{f['status']:10} +{f['additions']:-4} -{f['deletions']:-4}  {f['filename']}\")"

Локальное переключение на PR для полной рецензии

Это работает с обычным git — gh не требуется:

# Получить ветку PR и переключиться на неё
git fetch origin pull/123/head:pr-123
git checkout pr-123

# Теперь можно использовать read_file, search_files, запускать тесты и т.д.

# Просмотреть diff относительно базовой ветки
git diff main...pr-123

С помощью gh (сокращение):

gh pr checkout 123

Оставление комментариев к PR

Общий комментарий к PR — с помощью gh:

gh pr comment 123 --body "В целом выглядит хорошо, ниже несколько предложений."

Общий комментарий к PR — с помощью curl:

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
  -d '{"body": "В целом выглядит хорошо, ниже несколько предложений."}'

Оставление инлайн-комментариев к рецензии

Одиночный инлайн-комментарий — с помощью gh (через API):

HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')

gh api repos/$OWNER/$REPO/pulls/123/comments \
  --method POST \
  -f body="Это можно упростить с помощью спискового включения." \
  -f path="src/auth/login.py" \
  -f commit_id="$HEAD_SHA" \
  -f line=45 \
  -f side="RIGHT"

Одиночный инлайн-комментарий — с помощью curl:

# Получить SHA головного коммита
HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments \
  -d "{
    \"body\": \"Это можно упростить с помощью спискового включения.\",
    \"path\": \"src/auth/login.py\",
    \"commit_id\": \"$HEAD_SHA\",
    \"line\": 45,
    \"side\": \"RIGHT\"
  }"

Отправка формальной рецензии (Одобрить / Запросить изменения)

С помощью gh:

gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "Смотрите инлайн-комментарии."
gh pr review 123 --comment --body "Несколько предложений, ничего блокирующего."

С помощью curl — атомарная рецензия с несколькими комментариями:

HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"COMMENT\",
    \"body\": \"Рецензия кода от VibeOS\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"Используйте параметризованные запросы для предотвращения SQL-инъекций.\"},
      {\"path\": \"src/models/user.py\", \"line\": 23, \"body\": \"Хешируйте пароли с помощью bcrypt перед сохранением.\"},
      {\"path\": \"tests/test_auth.py\", \"line\": 1, \"body\": \"Добавьте тест для граничного случая с истёкшим токеном.\"}
    ]
  }"

Значения события: "APPROVE", "REQUEST_CHANGES", "COMMENT"

Поле line относится к номеру строки в новой версии файла. Для удалённых строк используйте "side": "LEFT".

---

3. Чеклист рецензирования

При выполнении рецензии кода (локальной или PR) систематически проверяйте:

Корректность

• Делает ли код то, что заявлено?
• Обработаны ли граничные случаи (пустые входные данные, null, большие объёмы данных, конкурентный доступ)?
• Обрабатываются ли пути ошибок корректно?

Безопасность

• Нет жёстко закодированных секретов, учётных данных или API-ключей
• Валидация ввода для пользовательских данных
• Нет SQL-инъекций, XSS или path traversal
• Проверки аутентификации/авторизации там, где необходимо

Качество кода

• Понятные имена (переменные, функции, классы)
• Нет излишней сложности или преждевременной абстракции
• DRY — нет дублирующейся логики, которую следует вынести
• Функции сфокусированы (единственная ответственность)

Тестирование

• Протестированы ли новые пути кода?
• Покрыты ли сценарии «happy path» и ошибок?
• Тесты читаемы и поддерживаемы?

Производительность

• Нет N+1 запросов или излишних циклов
• Соответствующее кэширование там, где это полезно
• Нет блокирующих операций в асинхронных путях кода

Документация

• Документированы публичные API
• Неочевидная логика содержит комментарии, объясняющие «почему»
• README обновлён, если поведение изменилось

---

4. Рабочий процесс рецензирования перед отправкой

Когда пользователь просит вас «проверить код» или «проверить перед отправкой»:

1. git diff main...HEAD --stat — оценить объём изменений
2. git diff main...HEAD — прочитать полный diff
3. Для каждого изменённого файла используйте read_file, если нужен дополнительный контекст
4. Примените чеклист выше
5. Представьте результаты в структурированном формате (Критично / Предупреждения / Предложения / Выглядит хорошо)
6. Если найдены критические проблемы, предложите исправить их перед отправкой

---

5. Рабочий процесс рецензирования PR (от начала до конца)

Когда пользователь просит вас «проверить PR #N», «посмотреть этот PR» или даёт вам URL PR, следуйте этому рецепту:

Шаг 1: Настройка окружения

source "${VIBEOS_HOME:-$HOME/.vibeos}/skills/github/github-auth/scripts/gh-env.sh"
# Или выполните блок настройки из начала этого навыка

Шаг 2: Сбор контекста PR

Получите метаданные PR, описание и список изменённых файлов, чтобы понять объём перед погружением в код.

С помощью gh:

gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123

С помощью curl:

PR_NUMBER=123

# Детали PR (название, автор, описание, ветка)
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER

# Изменённые файлы с количеством строк
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/files

Шаг 3: Локальное переключение на PR

Это даёт вам полный доступ к read_file, search_files и возможность запускать тесты.

git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER

Шаг 4: Чтение диффа и понимание изменений

# Полный diff относительно базовой ветки
git diff main...HEAD

# Или пофайлово для больших PR
git diff main...HEAD --name-only
# Затем для каждого файла:
git diff main...HEAD -- path/to/file.py

Для каждого изменённого файла используйте read_file, чтобы увидеть полный контекст вокруг изменений — одних диффов может не хватить для выявления проблем, видимых только с окружающим кодом.

Шаг 5: Запуск автоматических проверок локально (если применимо)

# Запуск тестов, если есть тестовый набор
python -m pytest 2>&1 | tail -20
# или: npm test, cargo test, go test ./..., и т.д.

# Запуск линтера, если настроен
ruff check . 2>&1 | head -30
# или: eslint, clippy, и т.д.

Шаг 6: Применение чеклиста рецензирования (Раздел 3)

Пройдитесь по каждой категории: Корректность, Безопасность, Качество кода, Тестирование, Производительность, Документация.

Шаг 7: Отправка рецензии на GitHub

Соберите свои замечания и отправьте их в виде формальной рецензии с инлайн-комментариями.

С помощью gh:

# Если проблем нет — одобрить
gh pr review $PR_NUMBER --approve --body "Проверено VibeOS. Код выглядит чистым — хорошее покрытие тестами, проблем с безопасностью нет."

# Если найдены проблемы — запросить изменения с инлайн-комментариями
gh pr review $PR_NUMBER --request-changes --body "Найдено несколько проблем — смотрите инлайн-комментарии."

С помощью curl — атомарная рецензия с несколькими инлайн-комментариями:

HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# Сборка JSON рецензии — событие APPROVE, REQUEST_CHANGES или COMMENT
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"REQUEST_CHANGES\",
    \"body\": \"## Рецензия VibeOS\n\nНайдено 2 проблемы, 1 предложение. Смотрите инлайн-комментарии.\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"🔴 **Критично:** Пользовательский ввод передаётся напрямую в SQL-запрос — используйте параметризованные запросы.\"},
      {\"path\": \"src/models.py\", \"line\": 23, \"body\": \"⚠️ **Предупреждение:** Пароль сохранён без хеширования.\"},
      {\"path\": \"src/utils.py\", \"line\": 8, \"body\": \"💡 **Предложение:** Эта логика дублирует core/utils.py:34.\"}
    ]
  }"

Шаг 8: Также отправьте сводный комментарий

В дополнение к инлайн-комментариям оставьте комментарий верхнего уровня, чтобы автор PR получил полную картину с первого взгляда. Используйте формат вывода рецензии из references/review-output-template.md.

С помощью gh:

gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
## Сводка рецензии кода

**Вердикт: Запрошены изменения** (2 проблемы, 1 предложение)

### 🔴 Критично
- **src/auth.py:45** — Уязвимость SQL-инъекции

### ⚠️ Предупреждения
- **src/models.py:23** — Хранение пароля в открытом виде

### 💡 Предложения
- **src/utils.py:8** — Дублированная логика, рассмотрите возможность объединения

### ✅ Выглядит хорошо
- Чистый дизайн API
- Хорошая обработка ошибок в слое middleware

---
*Проверено VibeOS*
EOF
)"

Шаг 9: Очистка

git checkout main
git branch -D pr-$PR_NUMBER

Решение: Одобрить vs Запросить изменения vs Комментарий

• Одобрить — нет критических проблем или предупреждений, только незначительные предложения или всё чисто
• Запросить изменения — любая критическая проблема или предупреждение, которые следует исправить перед слиянием
• Комментарий — наблюдения и предложения, но ничего блокирующего (используйте, когда не уверены или PR является черновиком)