tech-upd-recommender 0.1.0

Open-source CLI utility for local dependency analysis with AI-powered update recommendations.

Tech Update Recommender

Tech Update Recommender — open-source CLI-утилита для локального анализа зависимостей проекта. Она находит application-level зависимости через Syft, проверяет их версии и известные уязвимости через deps.dev, и опционально генерирует AI-рекомендации по обновлению через LiteLLM.

Ключевые возможности:

• Локально, без отправки исходного кода на сервер.
• Поддержка ecosystem'ов npm, PyPI, Maven, Go, Cargo, RubyGems, NuGet.
• Кеш ответов deps.dev (SQLite, TTL 1 час) — повторные запуски быстрые.
• Несколько форматов вывода: table (rich), json, markdown.
• Выбор LLM-провайдера через LiteLLM (Anthropic / OpenAI / Gemini / Ollama).

Установка

Tech Update Recommender требует Python 3.11+.

# Из PyPI:
pip install tech-update-recommender[llm]
# или через pipx:
pipx install "tech-update-recommender[llm]"

# Из исходников (для разработки):
pip install -e ".[llm]"

Группа [llm] ставит litellm. Без неё Tech Update Recommender работает в режимах report (без LLM) и просто возвращает понятную ошибку, если запросить advice/full.

Установка Syft

Tech Update Recommender не пытается тянуть Syft в зависимостях — этот инструмент удобнее ставить системно.

# macOS:
brew install syft

# Linux / любой UNIX (официальный установщик):
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

Если syft установлен в нестандартное место — передайте путь через --syft-path или поле syft.path в ~/.tech-update-recommender.yaml.

Quickstart

# 1. Простой отчёт по фактам (без LLM):
tech-update-recommender scan ./my-project

# 2. Полный отчёт с AI-рекомендациями:
tech-update-recommender scan ./my-project --mode full \
    --llm-model gemini/gemini-2.0-flash

# 3. JSON в файл:
tech-update-recommender scan ./my-project --output json --save out.json

Режимы работы

Режим	Что делает
report	(default) только факты: версии, дельты semver, advisories.
advice	только AI-рекомендации (без таблицы фактов в LLM-секции — но summary остаётся).
full	факты + AI-рекомендации.

Режимы advice и full требуют указать LLM-модель (через CLI-аргумент, env var или конфиг). Без модели Tech Update Recommender сообщит ошибку конфигурации (exit code 5) и подскажет, что делать.

Флаг --no-llm принудительно понижает режим до report — удобно, если конфиг по умолчанию содержит модель, но прямо сейчас не хочется дёргать API.

Конфигурационный файл

Путь по умолчанию: ~/.tech-update-recommender.yaml. Файл опционален — при отсутствии используются значения по умолчанию.

Пример полной структуры см. в docs/tech-update-recommender.yaml.example. Минимальный вариант:

llm:
  model: "gemini/gemini-2.0-flash"
  max_context_tokens: 8000

cache:
  enabled: true
  ttl_seconds: 3600
  path: "~/.cache/tech-update-recommender/"

API-ключи лучше держать в env vars, а не в файле. Если всё-таки храните в файле — chmod 600 ~/.tech-update-recommender.yaml.

Переменные окружения

Переменная	Что задаёт
TUR_LLM_MODEL	Имя LLM-модели (как --llm-model).
TUR_LLM_API_KEY	Универсальный API-ключ.
ANTHROPIC_API_KEY	Используется, если TUR_LLM_API_KEY не задан.
OPENAI_API_KEY	То же самое.
GEMINI_API_KEY	То же самое.
TUR_SYFT_PATH	Путь к бинарнику syft (как --syft-path).

Каскад приоритетов значений (от высшего к низшему): CLI > env vars > ~/.tech-update-recommender.yaml > дефолты.

Поддерживаемые экосистемы

Экосистемы, для которых Tech Update Recommender умеет проверять версии и advisories через deps.dev:

• npm
• pypi
• maven
• golang
• cargo
• gem (RubyGems)
• nuget

Системные пакеты (deb, apk, rpm и т.п.), найденные Syft, не проверяются — они показываются отдельной секцией «Не проверено через deps.dev» (это ограничение API deps.dev, а не Tech Update Recommender).

Известные ограничения

• Syft требует lock-файлы. Если в проекте только requirements.txt без зафиксированных версий или без lock-файла — Syft найдёт меньше зависимостей, чем хотелось бы.
• deps.dev не знает системные пакеты. Контейнерные пакеты (deb / apk / rpm) выводятся отдельной секцией без проверки на устаревание/CVE.
• deps.dev v3alpha может меняться. Batch endpoint используется для получения advisories текущих версий; в случае поломки API — Tech Update Recommender выдаст понятную ошибку и не упадёт с traceback.
• LLM не гарантирует корректность рекомендаций. Это всегда advisory: проверяйте совместимость и тестируйте обновления.
• Нормализация имён пакетов. PyPI нормализует имена (Flask-Babel → flask-babel). Tech Update Recommender делает это на своей стороне для запросов и кеша.

Коды возврата

Код	Значение
0	Успех.
1	Любая прочая ошибка (с подсказкой использовать --verbose).
2	Ошибка Syft (SyftError).
3	Ошибка deps.dev (DepsDevError).
4	Ошибка LLM (LLMError и его подклассы).
5	Ошибка конфигурации (ConfigError).
130	Отменено пользователем (Ctrl+C).

Тесты и линтер

pytest -q
ruff check .
ruff format --check .

Лицензия

MIT — см. файл LICENSE.