docs: document AI terraform plan analysis (internal/ai + cmd/sless-plan + provider schema)

2026-03-12 08:39:08 +03:00
parent 582b589e38
commit d9ed96e201
2 changed files with 94 additions and 0 deletions
@@ -646,3 +646,66 @@ for _, k := range keys { envVars = append(envVars, corev1.EnvVar{Name: k, Value:

 **Тесты:** 2 теста в `controllers/function_controller_unit_test.go`
 (4 env vars → алфавитный порядок после SLESS_ENTRYPOINT; пустой Env → только SLESS_ENTRYPOINT).
+
+---
+
+## 2026-03-12 — AI-анализ terraform plan через Google Gemini
+
+**Решение:** Добавлен необязательный AI-анализ вывода `terraform plan` с уровнями детализации 0–5.
+АI невидим по умолчанию — не влияет на существующие `.tf` файлы и workflow.
+
+**Причина:**
+- Разработчики хотят понимать что именно изменится в инфраструктуре перед применением.
+- Уровни позволяют самостоятельно выбирать глубину анализа (от краткого обзора до полного аудита).
+- Не ломает backward compatibility: `ai_hint_level` не указан → поведение идентично прежнему.
+
+**Архитектура:**
+```
+provider "sless" { ai_hint_level = 3 }
+    ↓ os.Setenv("AI_HINT_LEVEL", "3")  (в provider.Configure)
+sless-plan    ← CLI обёртка над terraform plan
+    ↓ запускает terraform plan, захватывает вывод
+    ↓ если AI_HINT_LEVEL > 0 → internal/ai/analyzer.go
+    ↓ POST к Gemini REST API (net/http)
+    ↓ выводит анализ пользователю
+```
+
+**Новые файлы:**
+| Файл | Назначение |
+|------|------------|
+| `internal/ai/provider.go` | `LLMProvider` interface + `Config` struct + `NewProvider` фабрика |
+| `internal/ai/google_gemini.go` | Gemini 2.0 Flash через `net/http` (без внешних зависимостей) |
+| `internal/ai/prompts.go` | Системные промпты для уровней 1–5, `BuildPrompt(level, plan)`, `LevelName(level)` |
+| `internal/ai/analyzer.go` | Оркестратор: `NewAnalyzer`, `Analyze`, `FormatResult`, `truncatePlan(8000)` |
+| `internal/ai/cloud_llm.go` | Заглушка: миграционный путь на облачный LLM в будущем |
+| `cmd/sless-plan/main.go` | CLI: запускает `terraform plan`, читает уровень, вызывает AI |
+
+**Изменённые файлы:**
+- `terraform/provider/internal/provider/provider.go` — добавлен атрибут `ai_hint_level` (Optional Int64)
+
+**Уровни анализа (env: `AI_HINT_LEVEL`):**
+| Уровень | Описание |
+|---------|----------|
+| 0 | Выключен (default) — AI не вызывается |
+| 1 | Только синтаксические ошибки и опечатки |
+| 2 | Базовый обзор изменений |
+| 3 | Умеренный: потенциальные проблемы + рекомендации |
+| 4 | Детальный: security review + best practices |
+| 5 | Полный аудит: всё включая compliance |
+
+**Как передаётся уровень (приоритет по убыванию):**
+1. `--ai-level` флаг CLI
+2. `AI_HINT_LEVEL` env var (выставляется провайдером через `os.Setenv` в `Configure`)
+3. `TF_VAR_ai_hint_level` env var
+4. Дефолт: 0
+
+**Почему `net/http` без Google SDK:**
+Gemini SDK требует внешней зависимости → `go.mod` провайдера должен оставаться неизменным.
+REST API Gemini достаточен: один endpoint, один JSON запрос/ответ.
+
+**Backward compatibility:**
+- Провайдер без `ai_hint_level` → `config.AIHintLevel.IsNull() == true` → `os.Setenv` не вызывается.
+- `sless-plan` без `AI_HINT_LEVEL` → уровень 0 → AI не вызывается → вывод идентичен `terraform plan`.
+- Существующие `.tf` файлы изменять не нужно.
+
+**Коммиты:** `d5ce8c2` (internal/ai + cmd/sless-plan), `582b589` (provider schema)