# Реалистичный план: PAPA YU как AI-аудитор проектов

**Цель:** не «ещё один Cursor», а специализированный AI-аудитор — уникальная ниша. План привязан к текущему коду и разбит на шаги с минимальным риском.

---

## Реализовано (текущая сборка)

- **П.1** — LLM-narrative: `fetch_narrative_for_report()` в `llm_planner.rs`, вызов из `analyze_project_cmd` и `run_batch`; fallback на шаблон при отсутствии API.
- **П.2** — В промпт «Предложить исправления» добавлено явное указание учитывать findings из отчёта.
- **П.3** — **AuditLogger**: `audit_log.rs`, команды `audit_log_list_cmd`, запись при анализе и apply; страница «Журнал» (/audit). **SecretsGuard**: `secrets_guard.rs`, `scan_secrets_cmd`, страница «Секреты» (/secrets). **PolicyEngine**: `policy_engine.rs`, `get_policies_cmd`, `run_policy_check_cmd`, страница «Политики» (/policies).
- **П.5 (упрощённый)** — RAG: `commands/rag_query.rs`, `rag_query_cmd` (контекст из файлов проекта + вопрос → LLM), страница «Вопрос по проекту» (/project-chat).

---

## 1. LLM → осмысленный narrative вместо шаблонов

**Сейчас:** в `analyze_project.rs` функция `build_human_narrative()` собирает текст из шаблонов: «Я проанализировал проект X», «Это React+Vite», «Найдено проблем: N. Рекомендую: …».

**Цель:** отправлять в LLM структурированный контекст (путь, тип проекта, findings, actions, signals) и получать один короткий narrative (2–4 предложения) для отчёта и agent-sync.

**Шаги:**

| # | Задача | Где | Оценка |
|---|--------|-----|--------|
| 1.1 | Вынести сборку «llm_context для narrative» в отдельную функцию (path, project_type, findings, actions, signals → JSON или текст). | `analyze_project.rs` | малый |
| 1.2 | Добавить опциональный вызов LLM для narrative: если заданы `PAPAYU_LLM_*`, после построения отчёта вызвать API с этим контекстом и промптом «Напиши краткий вывод аудитора для разработчика (2–4 предложения)». | новый модуль `narrative_llm.rs` или в `llm_planner.rs` | малый |
| 1.3 | Подставить ответ LLM в `report.narrative` вместо `build_human_narrative()`. Fallback: при ошибке/отсутствии API — текущий шаблон. | `analyze_project.rs` | малый |

**Риск:** низкий. Не ломает существующий поток, только обогащает текст.

---

## 2. Код-генерация по findings → LLM, preview, apply

**Сейчас:** есть цепочка: анализ → отчёт (findings + actions) → «Предложить исправления» (LLM генерирует план действий) → preview (diff) → apply. Генерация «безопасных» действий без LLM — в `generate_actions_from_report` (эвристики: README, .gitignore, tests).

**Цель:** явно вести от findings к исправлениям: findings + контекст кода → LLM → actions → preview → apply.

**Шаги:**

| # | Задача | Где | Оценка |
|---|--------|-----|--------|
| 2.1 | В режиме «Предложить исправления» передавать в LLM не только goal/report, но и список findings с evidence (уже есть в `AnalyzeReport`). Промпт: «По этим находкам предложи конкретные правки (EDIT_FILE, CREATE_FILE)». | `llm_planner.rs`, конструирование prompt | малый |
| 2.2 | Опционально: кнопка «Исправить по finding» — по одному выбранному finding отправить в LLM контекст (файл/фрагмент) и получить один или несколько actions, затем preview. | UI: `Tasks.tsx` + новая command `generate_actions_for_finding` | средний |
| 2.3 | Оставить текущий preview/apply без изменений (уже показывают diff и применяют с проверкой). | — | — |

**Риск:** низкий. Расширяем существующий LLM-контур.

---

## 3. Оживить «заглушки»: PolicyEngine, SecretsGuard, AuditLogger

**Сейчас:** в другом проекте (papayu-main) упоминаются маршруты `/policies`, `/audit`, `/secrets` как заглушки. В papa-yu их нет — фокус на задачах и анализе.

**Цель:** ввести в papa-yu три модуля, привязанные к Rust-бэкенду, без переписывания всего приложения.

**Шаги:**

| # | Задача | Где | Оценка |
|---|--------|-----|--------|
| 3.1 | **AuditLogger** — логирование действий аудитора (анализ, apply, undo, отказ). Rust: команда `audit_log(event_type, payload)` + запись в файл `.papa-yu/audit.log` или SQLite. UI: страница «Журнал» — список последних событий (дата, тип, проект, результат). | `src-tauri/src/audit_log.rs`, `lib.rs`, новая страница `AuditLog.tsx`, маршрут `/audit` | средний |
| 3.2 | **SecretsGuard** — проверка проекта на типичные утечки (ключи в коде, .env в репо, хардкод паролей). Rust: сканирование выбранной папки (эвристики + опционально regex из конфига), возврат списка «подозрений» без хранения секретов. UI: страница «Секреты» — кнопка «Проверить», таблица файл/строка/тип. | `src-tauri/src/secrets_guard.rs`, команда `scan_secrets`, страница `SecretsGuard.tsx`, маршрут `/secrets` | средний |
| 3.3 | **PolicyEngine** — набор правил аудита (например «обязателен README», «запрещён коммит .env»). Rust: конфиг правил (JSON), проверка проекта по правилам, отчёт pass/fail. UI: страница «Политики» — список правил, результат последней проверки. | `src-tauri/src/policy_engine.rs`, команды `get_policies`, `run_policy_check`, страница `PolicyEngine.tsx`, маршрут `/policies` | средний |

**Риск:** средний. Новый код, но изолированные модули.

---

## 4. Deep analysis: парсинг кода, уязвимости, мёртвый код

**Сейчас:** анализ в `analyze_project.rs` — обход файловой системы, эвристики (наличие README, tests, .gitignore и т.д.), без разбора содержимого кода.

**Цель:** не только структура, но и парсинг кода (tree-sitter), поиск типичных уязвимостей, индикация мёртвого кода.

**Шаги:**

| # | Задача | Где | Оценка |
|---|--------|-----|--------|
| 4.1 | Подключить tree-sitter (Rust: `tree-sitter` crate) для одного языка-пилота (например JavaScript/TypeScript). Обход выбранных файлов, построение AST, подсчёт функций/классов, экспортов. | новый модуль `src-tauri/src/deep_analysis/` или `code_parser.rs` | большой |
| 4.2 | Добавить в отчёт «глубокие» findings: неиспользуемые экспорты (мёртвый код), простые паттерны риска (eval, innerHTML без санитизации — по правилам). | расширить `Finding`, вызов парсера из `analyze_project` или отдельной command | средний |
| 4.3 | Опционально: интеграция с Snyk Code / аналогом (уже есть `snyk_sync`) — показывать код-уязвимости рядом с нашими findings. | уже частично есть; доработать отображение в UI | малый |

**Риск:** большой для 4.1 (зависимость, поддержка языков). Рационально начать с одного языка и набора из 3–5 правил.

---

## 5. RAG по документации и коду: чат с контекстом проекта

**Сейчас:** domain notes, project_content, выбор папки/файлов. Чат «с агентом» в UI есть, но без RAG по загруженному проекту.

**Цель:** пользователь выбрал проект → задаёт вопросы в чате → агент отвечает с опорой на индекс кода/документации (RAG).

**Шаги:**

| # | Задача | Где | Оценка |
|---|--------|-----|--------|
| 5.1 | Индексация: по выбранному пути собрать «документы» (файлы с расширениями .md, .ts, .tsx, .rs и т.д.), разбить на чанки, опционально эмбеддинги (внешний API или локальная модель). Хранить индекс в `.papa-yu/rag_index` (SQLite + векторы или только текст для простого поиска). | новый модуль `src-tauri/src/rag/` (index, search), команды `rag_index_project`, `rag_query` | большой |
| 5.2 | Поиск по запросу: по тексту вопроса найти релевантные чанки (keyword или semantic), сформировать контекст для LLM. | `rag/query.rs` | средний |
| 5.3 | Чат: поле «Вопрос по проекту» → вызов `rag_query` + вызов LLM с контекстом → ответ в UI. Без переделки всего чата — один сценарий «вопрос по коду». | `Tasks.tsx` или отдельная вкладка «Вопросы по проекту», команда `chat_on_project` | средний |

**Риск:** большой для полного RAG с эмбеддингами. Упрощённый вариант: индексация без эмбеддингов, поиск по ключевым словам + контекст из найденных файлов в промпт — быстрее внедрить.

---

## Приоритеты и порядок

| Приоритет | Блок | Зачем первым |
|-----------|------|--------------|
| 1 | П.1 — LLM-narrative | Быстрый визуальный выигрыш, малый объём работ, не ломает поток. |
| 2 | П.2 — Findings → LLM → apply | Уже есть цепочка; усиление связи findings → исправления усиливает позицию «аудитор». |
| 3 | П.3 — AuditLogger | Минимальная «оживляющая» заглушка: всё что делается — логируется. Нужно для доверия и аудита. |
| 4 | П.3 — SecretsGuard | Сильно востребовано в аудите; эвристики без тяжёлых зависимостей. |
| 5 | П.3 — PolicyEngine | Завершает триаду «аудиторских» модулей. |
| 6 | П.5 — RAG упрощённый | Чат по проекту без полного RAG: индекс файлов + keyword-поиск + контекст в LLM. |
| 7 | П.4 — Deep analysis | Самый тяжёлый; после закрепления п.1–3 и 5 имеет смысл вводить tree-sitter по одному языку. |
| 8 | П.5 — RAG с эмбеддингами | При необходимости углубления чата по коду. |

---

## Кратко по файлам

- **Narrative от LLM:** `analyze_project.rs` (build_human_narrative → вызов LLM), новый хелпер в `llm_planner.rs` или `narrative_llm.rs`.
- **Findings → LLM:** `llm_planner.rs` (prompt), `generate_actions_from_report.rs` / новая command для одного finding.
- **Audit/Secrets/Policy:** новые модули в `src-tauri/src/`, новые страницы и маршруты в `src/App.tsx`.
- **Deep analysis:** новый модуль `code_parser` / `deep_analysis`, расширение `analyze_project` или отдельная command.
- **RAG:** новый модуль `rag/`, команды индексации и запроса, блок чата в UI.

Документ можно использовать как дорожную карту для спринтов и оценок.