91 lines
5.9 KiB
Markdown
91 lines
5.9 KiB
Markdown
# Randomayzer AI Security Review Exporter
|
||
|
||
`tools/export-review.ps1` — утилита для создания автономных snapshot и diff пакетов репозитория для внешних AI security reviewers, у которых нет прямого доступа к GitHub репозиторию или локальной файловой системе.
|
||
|
||
---
|
||
|
||
## 1. Возможности
|
||
|
||
- **Full Snapshot Mode (по умолчанию)**: Создает полный ZIP-архив репозитория на основе `git archive HEAD`.
|
||
- **Diff Mode (`-Diff`)**: Создает компактный пакет изменений между базовым коммитом (`-Base`) и `HEAD`, включая патч, список измененных файлов, измененные исходники, полный набор тестов, схему базы данных и документацию.
|
||
- **Review Context (`REVIEW_CONTEXT.md`)**: В каждый архив автоматически встраивается файл метаданных с полным SHA, веткой, временной меткой, состоянием working tree и статистикой `git log`.
|
||
- **Secret Safety Check**: Проверяет tracked-файлы на наличие потенциальных секретов (`.env`, `*.pem`, `*.key`, `credentials.json`, `secrets.json`) и блокирует экспорт при обнаружении.
|
||
- **Dirty Worktree Warning / Guard**: Предупреждает о наличии незакоммиченных изменений (снапшот собирается строго из `HEAD`) или прерывает выполнение при флаге `-RequireClean`.
|
||
- **Zero External Dependencies**: Работает на Windows PowerShell 5.1 и PowerShell 7+ с использованием стандартных API .NET (`System.IO.Compression`). Сторонние архиваторы (7-Zip, WinRAR) не требуются.
|
||
- **Корректная работа с пробелами в путях** (например, `E:\Agent projects\Randomayzer`).
|
||
|
||
---
|
||
|
||
## 2. Быстрый старт
|
||
|
||
Запуск из корня проекта:
|
||
|
||
### Полный снимок репозитория (Full Snapshot)
|
||
```powershell
|
||
.\tools\export-review.ps1
|
||
```
|
||
Архив сохраняется по умолчанию в папку `Desktop\Randomayzer Reviews\randomayzer-review-<shortSHA>.zip`.
|
||
|
||
### Diff последнего коммита (`HEAD^` vs `HEAD`)
|
||
```powershell
|
||
.\tools\export-review.ps1 -Diff
|
||
```
|
||
Создает архив `randomayzer-diff-review-<shortSHA>.zip`, содержащий:
|
||
- `REVIEW_CONTEXT.md`
|
||
- `REVIEW_DIFF.patch`
|
||
- `REVIEW_CHANGED_FILES.txt`
|
||
- Измененные файлы в структуре каталогов проекта
|
||
- Полный набор тестов `tests/*`
|
||
- Схему `prisma/schema.prisma`, `package.json`, `.env.example`, документацию `docs/*`
|
||
|
||
### Diff от определенного коммита
|
||
```powershell
|
||
.\tools\export-review.ps1 -Diff -Base b5467f6
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Параметры
|
||
|
||
| Параметр | Тип | Описание |
|
||
|---|---|---|
|
||
| `-Diff` | Switch | Включает режим формирования diff-пакета вместо полного снимка. |
|
||
| `-Base <SHA>` | String | Базовый коммит для сравнения в режиме `-Diff` (по умолчанию `HEAD^`). |
|
||
| `-OutputDir <Path>` | String | Пользовательский путь для сохранения ZIP-файлов (по умолчанию `Desktop\Randomayzer Reviews\`). |
|
||
| `-RequireClean` | Switch | Завершает работу с ошибкой, если в working tree есть незакоммиченные файлы. |
|
||
| `-AllowSensitiveTrackedFiles` | Switch | Отключает блокировку экспорта при обнаружении подозрительных tracked-файлов. |
|
||
| `-CopyPrompt` | Switch | Автоматически копирует в буфер обмена Windows текст задания для security reviewer. |
|
||
|
||
---
|
||
|
||
## 4. Примеры использования
|
||
|
||
### Экспорт со строгой проверкой чистоты рабочей директории
|
||
```powershell
|
||
.\tools\export-review.ps1 -RequireClean
|
||
```
|
||
|
||
### Экспорт в пользовательскую директорию с копированием промпта
|
||
```powershell
|
||
.\tools\export-review.ps1 -Diff -Base bc2b658 -OutputDir "D:\Audits" -CopyPrompt
|
||
```
|
||
|
||
После выполнения в буфере обмена будет готов стандартизированный промпт:
|
||
> «В приложенном архиве snapshot Randomayzer на commit `<SHA>`.
|
||
> Используй архив как source of truth.
|
||
> Не используй GitHub HEAD вместо него.
|
||
> Выполни ранее выданное security review задание.»
|
||
|
||
---
|
||
|
||
## 5. Гарантии безопасности архива
|
||
|
||
1. **Изоляция от локального мусора**: В ZIP-архив **никогда не попадают**:
|
||
- `.git`
|
||
- `node_modules`
|
||
- `.next` сборки и кэш
|
||
- Локальные незакоммиченные файлы
|
||
- Локальные `.env`, `.env.local`
|
||
- IDE-файлы (`.vscode`, `.idea`)
|
||
2. **Точность снимка**: Файлы извлекаются напрямую из Git-объектов коммита (`git archive` для Full или `git show HEAD:<path>` для Diff), поэтому локальные изменения в рабочей директории не искажают снимок.
|
||
3. **Защита от утечки секретов**: Сканирование имен файлов блокирует экспорт при случайном попадании приватных ключей или файлов конфигурации в индекс Git.
|