tech-upd-recommender 0.1.0__tar.gz

tech_upd_recommender-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -m build)"
+    ]
+  }
+}

tech_upd_recommender-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: /Users/slavyan/Documents/ML/tech-update-recommender/.git/worktrees/funny-curie-1d77a6

tech_upd_recommender-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+sdist/
+wheels/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+
+# Linting
+.ruff_cache/
+
+# Distribution / packaging
+*.tar.gz
+*.zip
+
+# Environment variables / secrets
+.env
+.env.*
+!.env.example
+
+# Project-specific
+*.tech-update-recommender-cache/
+
+# OS
+.DS_Store
+Thumbs.db
+.DS_Store

tech_upd_recommender-0.1.0/CHECKLIST.md

@@ -0,0 +1,139 @@
+# Tech Update Recommender — Чеклист реализации
+
+Заполняется по мере работы. Подробности по каждому блоку — в `docs/blocks/`.
+
+Легенда: `[ ]` — не начато, `[~]` — в работе, `[x]` — готово.
+
+---
+
+## Блок 1 — Скелет проекта
+> Подробности: [docs/blocks/01-skeleton.md](docs/blocks/01-skeleton.md)
+
+- [x] `pyproject.toml` создан и валиден
+- [x] Структура директорий создана (`tech_update_recommender/`, `tests/`, `docs/`, `tests/fixtures/`)
+- [x] `tech_update_recommender/__init__.py` с `__version__`
+- [x] `models.py`: `PackageInfo`, `Advisory`, `DependencyReport`, `FullReport`, `LLMInput`
+- [x] `config.py`: `Config` + `load_config()` с каскадом дефолтов
+- [x] `cli.py`: `click`-команда `scan` со всеми опциями (заглушки)
+- [x] `--version` работает
+- [x] Логирование настроено (`--verbose` → DEBUG)
+- [x] `pip install -e ".[llm,dev]"` проходит
+- [x] `tests/test_models.py` — минимальные тесты моделей
+- [x] `tests/test_config.py` — каскад конфигурации
+- [x] `pytest -q` зелёный
+
+---
+
+## Блок 2 — SyftModule
+> Подробности: [docs/blocks/02-syft-module.md](docs/blocks/02-syft-module.md)
+
+- [x] `find_syft_binary()` + `SyftNotFoundError`
+- [x] `run_syft()` через `subprocess`, stdout во временный файл
+- [x] `SyftExecutionError` при ненулевом exit
+- [x] `parse_cyclonedx()` — извлечение purl, парсинг через `packageurl-python`
+- [x] Maven namespace склеивается корректно (`groupId:artifactId`)
+- [x] `SUPPORTED_ECOSYSTEMS` константа
+- [x] `split_supported()` — разделение на supported/unsupported
+- [x] Дедупликация пакетов
+- [x] Публичная функция `scan_project()`
+- [x] Иерархия исключений (`SyftError`, `SyftNotFoundError`, `SyftExecutionError`, `SyftParseError`)
+- [x] Фикстуры: `cyclonedx_simple.json`, `_mixed.json`, `_maven.json`, `_empty.json`, `_broken.json`
+- [x] `tests/test_syft_module.py` — все тест-кейсы из блока 2
+
+---
+
+## Блок 3 — DepsDevModule
+> Подробности: [docs/blocks/03-depsdev-module.md](docs/blocks/03-depsdev-module.md)
+
+- [x] Async HTTP-клиент с таймаутом и retry (3 попытки, exp backoff)
+- [x] `fetch_current_versions()` — batch POST `/v3alpha/versionbatch`
+- [x] Чанкирование при > 5000 пакетов
+- [x] `fetch_latest_versions()` — GET `/v3/systems/{system}/packages/{name}` параллельно
+- [x] Семафор concurrency = 20
+- [x] Дедупликация запросов GetPackage по `(system, name)`
+- [x] `compute_semver_diff()` в `utils.py` — major/minor/patch/None
+- [x] Поддержка нестрогого SemVer (Maven, PyPI)
+- [x] `cache.py`: SQLite-кеш с TTL
+- [x] `Cache.get/set/clear` API
+- [x] `build_report()` — основная функция модуля
+- [x] Корректные `outdated_count`, `vulnerable_count`
+- [x] Обработка 404 (latest_version=None)
+- [x] `DepsDevError` при недоступности API
+- [x] Нормализация имён (PyPI lowercase, Maven groupId:artifactId)
+- [x] Фикстуры: `depsdev_batch_response.json`, `depsdev_getpackage_express.json`, `depsdev_404.json`
+- [x] `tests/test_depsdev_module.py` — все тест-кейсы из блока 3
+
+---
+
+## Блок 4 — ReportModule
+> Подробности: [docs/blocks/04-report-module.md](docs/blocks/04-report-module.md)
+
+- [x] `render_report()` — публичный API
+- [x] Формат `table` через `rich.table.Table`
+- [x] Цвета: красный/жёлтый/зелёный/серый по статусу
+- [x] Summary-строка перед таблицей
+- [x] Секция unsupported с кратким упоминанием
+- [x] Формат `json` через `model_dump_json(indent=2)`
+- [x] Поле `llm_advice` в JSON-выводе при наличии
+- [x] Формат `markdown` с заголовками и таблицей
+- [x] Дисклеймер LLM-секции с подстановкой `{model_name}`
+- [x] Фильтр `only_outdated` применяется до рендера
+- [x] Summary считается по полному отчёту (не по фильтру)
+- [x] `tests/test_report.py` — все тест-кейсы из блока 4
+
+---
+
+## Блок 5 — LLMModule
+> Подробности: [docs/blocks/05-llm-module.md](docs/blocks/05-llm-module.md)
+
+- [x] `collect_project_tree()` — обход с исключениями (`node_modules`, `.git`, `venv`, …)
+- [x] Лимит строк дерева (default 200)
+- [x] `collect_dependency_files()` — поиск стандартных файлов
+- [x] Пропуск lock-файлов > 200 KB
+- [x] `build_llm_input()` — top-50 outdated/vulnerable
+- [x] Приоритизация: CVE → major → minor → patch
+- [x] System prompt из PLAN.md
+- [x] User prompt с отчётом, деревом, файлами
+- [x] Подсчёт токенов через `litellm.token_counter` или fallback
+- [x] Алгоритм усечения при превышении `max_context_tokens`
+- [x] `LLMContextOverflowError` если усечение не помогло
+- [x] `generate_advice()` через `litellm.completion`
+- [x] Ленивый импорт `litellm`
+- [x] `LLMNotAvailableError` при отсутствии зависимости
+- [x] Маппинг ошибок: `LLMAuthError`, `LLMRateLimitError`, `LLMNetworkError`
+- [x] Retry на rate limit (1 попытка через 5 сек)
+- [x] API-ключи не попадают в логи
+- [x] Поддержка локальных моделей (Ollama) без API-ключа
+- [x] `tests/test_llm_module.py` — все тест-кейсы из блока 5
+
+---
+
+## Блок 6 — Интеграция и финализация
+> Подробности: [docs/blocks/06-integration.md](docs/blocks/06-integration.md)
+
+- [x] CLI pipeline `scan` склеен (Syft → DepsDev → LLM → Report)
+- [x] Прогресс-бары через `rich.progress` (в stderr)
+- [x] Обработка ошибок верхнего уровня в `main()`, корректные exit codes
+- [x] Ошибка при `--mode advice/full` без указанной модели
+- [x] Конфиг `~/.tech-update-recommender.yaml` загружается, если есть
+- [x] `docs/tech-update-recommender.yaml.example` создан
+- [x] `README.md` написан (установка, quickstart, режимы, конфиг, env vars, ограничения)
+- [x] `CLAUDE.md` создан (карта модулей, контракты, тесты)
+- [x] `LICENSE` (MIT) в корне
+- [x] `tests/test_integration.py` — full pipeline с моками
+- [x] `ruff check .` + `ruff format --check .` зелёные
+- [ ] Ручной прогон на 2–3 реальных проектах разных экосистем
+- [x] Версия 0.1.0 в `pyproject.toml`
+- [x] `python -m build` создаёт wheel + sdist
+- [x] `twine check dist/*` без ошибок
+
+---
+
+## Сквозные требования (проверять в течение всех блоков)
+
+- [x] Все публичные функции имеют type hints
+- [x] Никаких `print()` для статусной информации (только `logging`)
+- [x] API-ключи никогда не логируются
+- [x] Все внешние вызовы (subprocess, HTTP) обёрнуты в try/except
+- [x] Тесты не требуют установленного syft и доступа к интернету
+- [x] `pytest -q` зелёный после каждого блока

tech_upd_recommender-0.1.0/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md — ориентир для агентов
+
+Краткий справочник по структуре Tech Update Recommender, контрактам между модулями и
+правилам, которым нужно следовать при доработке.
+
+## Карта модулей
+
+| Файл | Что делает |
+|------|------------|
+| `tech_update_recommender/__init__.py`        | Экспортирует `__version__`. |
+| `tech_update_recommender/__main__.py`        | `python -m tech_update_recommender` → `cli.main`. |
+| `tech_update_recommender/cli.py`             | Click-команда `scan`, склейка pipeline, обработка ошибок верхнего уровня. |
+| `tech_update_recommender/config.py`          | Pydantic-конфиг + каскад «CLI > env > yaml > defaults», `ConfigError`. |
+| `tech_update_recommender/cache.py`           | SQLite-кеш `(system, name, version) → JSON` с TTL. |
+| `tech_update_recommender/models.py`          | Pydantic-модели контрактов: `PackageInfo`, `DependencyReport`, `FullReport`, `LLMInput`, `Advisory`. |
+| `tech_update_recommender/syft_module.py`     | Запуск syft, парсинг CycloneDX, фильтр по `SUPPORTED_ECOSYSTEMS`, `SyftError`. |
+| `tech_update_recommender/depsdev_module.py`  | Async HTTP к deps.dev (batch + GetPackage), `build_report`, `DepsDevError`. |
+| `tech_update_recommender/llm_module.py`      | Сбор контекста (tree + dep-файлы), промпт, `litellm.completion`, `LLMError`. |
+| `tech_update_recommender/report.py`          | Рендер `FullReport` в `table` / `json` / `markdown`. |
+| `tech_update_recommender/utils.py`           | semver-сравнение, нормализация PyPI-имён, URL-кодирование. |
+
+## Контракты между модулями (одной строкой)
+
+- `scan_project(path) -> (supported, unsupported)` — оба списка `PackageInfo`.
+- `build_report(supported, unsupported, project_path, cache) -> FullReport` (async).
+- `build_llm_input(report, project_path) -> LLMInput`.
+- `generate_advice(llm_input, model, api_key=None, max_context_tokens=8000) -> str` (markdown).
+- `render_report(report, fmt, only_outdated=False, llm_advice=None, llm_model_name=None) -> str`.
+
+Pipeline: Syft → deps.dev (+ Cache) → LLM (опц.) → Report → stdout/файл.
+
+## Команды разработчика
+
+```bash
+pytest -q                  # все тесты (юнит + интеграционные)
+ruff check .               # линтер: E, F, I, B
+ruff format --check .      # форматирование
+python -m build            # сборка wheel + sdist
+twine check dist/*         # метаданные
+```
+
+## Что НЕ делать
+
+- Не печатать API-ключи в логах. `SecretStr` уже маскирует — не вытаскивайте
+  значение в логгер. В `generate_advice` ключ не логируется (см. блок 5).
+- Не превращать pipeline в agentic / tool-using. Tech Update Recommender делает один
+  LLM-вызов с собранным заранее контекстом — и всё. Без циклов «LLM зовёт
+  инструменты».
+- Не делать реальные HTTP/syft-вызовы в тестах. Используйте `aioresponses`
+  для deps.dev и моки `subprocess.run` / `scan_project` для syft.
+- Не лить `print()` для статуса — только `logging`. Прогресс — через
+  `rich.progress.Progress` и `Console(stderr=True)`.
+- Не трогать `cli` стайл вывода: stdout = только результат отчёта, stderr =
+  прогресс / сообщения / ошибки. Иначе `--output json` в pipe сломается.
+- Не публиковать на PyPI без явной просьбы. `python -m build` и
+  `twine check` — да; `twine upload` — нет.
+
+## Версионирование
+
+Версия в `tech_update_recommender/__init__.py` и `pyproject.toml` должна совпадать.
+Текущая релизная — `0.1.0`.

tech_upd_recommender-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DepScope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tech_upd_recommender-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: tech-upd-recommender
+Version: 0.1.0
+Summary: Open-source CLI utility for local dependency analysis with AI-powered update recommendations.
+Project-URL: Homepage, https://github.com/Alimhux/tech-update-recommender
+Project-URL: Issues, https://github.com/Alimhux/tech-update-recommender/issues
+Author-email: Alimhux <slavyan1011@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 DepScope contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,dependencies,deps.dev,sbom,security,syft
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: aiohttp
+Requires-Dist: certifi
+Requires-Dist: click
+Requires-Dist: litellm
+Requires-Dist: packageurl-python
+Requires-Dist: packaging
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: aioresponses; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Tech Update Recommender
+
+Tech Update Recommender — open-source CLI-утилита для локального анализа зависимостей проекта.
+Она находит application-level зависимости через [Syft](https://github.com/anchore/syft),
+проверяет их версии и известные уязвимости через [deps.dev](https://deps.dev),
+и опционально генерирует AI-рекомендации по обновлению через
+[LiteLLM](https://github.com/BerriAI/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+.
+
+```bash
+# Из 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 в зависимостях — этот инструмент удобнее
+ставить системно.
+
+```bash
+# 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
+
+```bash
+# 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`. Минимальный
+вариант:
+
+```yaml
+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`).                        |
+
+## Тесты и линтер
+
+```bash
+pytest -q
+ruff check .
+ruff format --check .
+```
+
+## Лицензия
+
+MIT — см. файл [`LICENSE`](LICENSE).