git log --after="2026-05-20" --reverse --no-patch --format="%s%n%n%b%n========================================"

v2.6.0
### ✨ Новые возможности (Feat)
- **JSON конфигурация**: Полная поддержка форматов `config.json` и `config.local.json` для чтения и сохранения настроек.
- **Hot-Reload конфигурации**: Автоматическое отслеживание изменений файлов конфигурации в реальном времени с поддержкой пользовательских коллбэков (требует `watchdog`). Реализован "тихий" режим (`notify=False`) для программных сохранений.
- **Универсальное переопределение через ENV**: Возможность переопределения любых значений конфигурации через переменные окружения по шаблону `CH_[SECTION]_[KEY]`.
- **Интеграция с Pydantic**: Встроенная валидация и типизация настроек через Pydantic-модели (опциональная зависимость).
- **Контекстное логирование**: Добавлена функция `bind_context` для автоматического прикрепления метаданных (например, ID запроса) ко всем логам внутри `ContextVar`.
- **JSON логирование**: Новая возможность вывода структурированных логов в формате JSON.
- **Автоматическое маскирование секретов**: Логгер теперь умеет автоматически скрывать чувствительные данные.
- **Новый декоратор (`@timeout`)**: Реализован универсальный декораторы для управления таймаутами синхронных и асинхронных функций.
- **CLI для секретов**: Внедрена консольная утилита `chutils secrets` для удобного управления системным хранилищем прямо из терминала.

### 🛠️ Улучшения и рефакторинг (Refactor)
- **Архитектура SOLID в модуле конфигурации**: Глубокий рефакторинг модуля `config` с внедрением `ConfigManager` (управление состоянием) и паттерна Стратегия (`ConfigProvider`) для поддержки различных форматов.
- **Обратная совместимость (Deprecation)**: Обеспечен плавный переход при доступе к приватным глобальным переменным старого модуля `config` с помощью перехвата `__getattr__` и вывода `DeprecationWarning`.
- **DRY в конфигурации**: Вспомогательные функции вынесены в `utils.py`, устранено дублирование при типизации.

### 📝 Документация (Docs)
- **Интерактивный справочник API**: Документация `docs/api.md` нормализована (DRY). Технические детали перенесены в docstrings (Google Style) исходного кода для автогенерации через `mkdocstrings`.
- **Новые примеры и рецепты**: Расширен README.md, добавлены подробные инструкции по Pydantic, Hot-Reload, CLI и декораторам. Обновлена книга рецептов (`docs/recipes.md`).

### ✅ Тесты и Сборка (Test & Build)
- **Переход на PEP 621**: Метаданные сборки в `pyproject.toml` приведены к современному стандарту. `pydantic` и `watchdog` вынесены в опциональные зависимости.
- **Изоляция и TDD**: Значительно расширено покрытие тестами (особенно для декораторов, watcher и провайдеров). Улучшена реактивность глобального состояния и обеспечена полная изоляция тестов `ConfigManager`.
- **Обновление тулинга**: Зависимости для разработки (`pytest`, `pyfakefs`, `mkdocstrings`) обновлены и ограничены Python 3.10+ (без потери поддержки Python 3.9 для конечных пользователей).

v2.6.1
### ✨ Новые возможности (Feat)
- **Публичное API для путей**: Добавлены функции `are_paths_initialized()` и `get_config_paths()` в модуль `config`, предоставляющие официальный способ доступа к состоянию инициализации и путям файлов конфигурации.

### 🐞 Исправления ошибок (Fix)
- **Обратная совместимость**: Исправлена регрессия (`ImportError`), возникавшая в зависимых проектах при обращении к внутренним атрибутам `_BASE_DIR`, `_get_config_paths` и др. Доступ восстановлен через механизм PEP 562.
- **Информативные предупреждения**: Сообщения `DeprecationWarning` теперь содержат конкретные рекомендации по замене устаревших атрибутов на новые публичные функции.

### 🛡️ Безопасность (Security)
- **Защита от Path Traversal**: Исправлена критическая уязвимость в функции `get_config_path`. Теперь библиотека блокирует попытки выхода за пределы корня проекта через использование `..` или абсолютных путей в конфигурации.

### ✅ Тесты (Test)
- **Тесты безопасности**: Добавлена серия тестов, проверяющих блокировку атак типа Path Traversal и корректность логирования попыток несанкционированного доступа.

v2.7.0

В этом релизе мы значительно расширили арсенал разработчика, добавив мощные инструменты для тестирования, создания CLI-интерфейсов, управления жизненным циклом и интеграции с AI-агентами.

## ✨ Новые возможности (Features)

### 🤖 AI-интеграция и Developer Experience (DX)
- **Генерация карты API и семантического индекса**: Добавлена новая команда chutils dev generate-context. В базовом режиме она выполняет интроспекцию и генерирует карту публичного API (Markdown/JSON). А при использовании флага --tree строится иерархический семантический индекс через AST-парсинг с определением связей, слоев абстракций и весов модулей, что радикально улучшает контекст для LLM-агентов.
- **Генерация JSON Schema**: Внедрена команда `chutils config generate-schema --model <path>`. Теперь Pydantic-модели можно экспортировать в стандартный JSON Schema, что обеспечивает поддержку автодополнения конфигурации (`config.yml`) прямо в IDE (VSCode, PyCharm).
- **Специализированная документация для AI**: Созданы файлы `INTEGRATION_AI.md`, `ai_hints.md` и манифесты `GEMINI.md` для мгновенного погружения AI-агентов в контекст проекта.

### 🛠 Утилиты для тестирования (Testing DX)
- **Модуль `chutils.testing`**: Появился набор готовых pytest-фикстур для безопасного и изолированного тестирования:
  - `mock_chutils_config`: Удобная подмена настроек и отключение ENV-переопределений.
  - `mock_chutils_secrets`: Полная изоляция от системного хранилища (Keyring) во время тестов.
  - `capture_chutils_logs`: Надежный перехват логов и контекста (`bind_context`) через патчинг `callHandlers`.

### 🚀 CLI Booster (Быстрое создание консольных утилит)
- **Декоратор `@cli_command`**: Превращает любую функцию в полноценную CLI-команду с автоматическим маппингом аргументов (включая `list` и `Path`), поддержкой `asyncio` "из коробки" и парсингом Google-style docstrings для создания красивой `--help` справки.

### 🔄 Управление жизненным циклом (Lifecycle)
- **Graceful Shutdown**: Новый модуль `lifecycle` с декоратором `@register_cleanup` и функцией `setup_graceful_shutdown`. Обеспечивает безопасное завершение работы приложения (перехват SIGINT, SIGTERM) с гарантированным выполнением синхронных и асинхронных коллбэков очистки по таймауту.

### 🚩 Фича-флаги (Feature Flags)
- **Управление доступностью**: Внедрен модуль `features` для управления фича-флагами через конфиг. Поддерживает включение/выключение функционала по условию среды (`CH_ENV`), процентному раскатыванию (Rollout) и включает декоратор `@require_feature`.

### ⏱ Работа со временем (Time Utilities)
- **Модуль `time`**: Новые утилиты `utc_now()`, `parse_datetime()` и функция `humanize_timedelta()` (с поддержкой русского и английского языков) для вывода человекочитаемой разницы во времени (например, "5 минут назад").

### 📡 Трассировка и OpenTelemetry (OTEL)
- **Модуль `tracing`**: Добавлена опциональная интеграция с OpenTelemetry. Декоратор `@trace`, поддержка экспортеров (Console, OTLP) и автоматическая инъекция `trace_id` и `span_id` в логи (JSON и текстовые).

### 🌐 Удаленная конфигурация
- **HttpConfigProvider**: Добавлена поддержка загрузки, кэширования и фонового опроса (polling) конфигурации по HTTP/HTTPS (с поддержкой Basic Auth). Формат (JSON, YAML, INI) определяется автоматически.

### 🔍 Диагностика и отладка конфигурации (Config Diagnostics)
- Команда chutils config debug: Внедрен мощный инструмент для интерактивной отладки конфигурации. Теперь можно легко отследить происхождение каждого значения (загружено ли оно из файла YAML/INI, переопределено ли через ENV-переменные или загружено удаленно).
- Безопасность и форматирование: Поддержка вывода трассировки в виде дерева (tree), таблицы (table) или json. Встроен механизм автоматического маскирования чувствительных данных (паролей, ключей, токенов) при выводе отчетов.

## 🛠️ Улучшения и исправления (Refactor & Fixes)
- **Конфигурация**: Добавлена возможность программного сохранения конфига без запуска Hot-Reload триггеров (`notify=False`).
- **CLI**: Исправлена потеря заголовков секций при выводе отладочной информации (`chutils config debug`) за счет отключения парсинга rich-тегов в текстовом режиме.
- **CLI**: Улучшена изоляция вывода dev-команд — статусные сообщения перенесены в `stderr`, оставляя `stdout` чистым для JSON-вывода.
- **Секреты**: Добавлен механизм плавной миграции для системного `keyring` (который станет опциональным в 3.0.0) с возможностью подавления предупреждений.
- **Тестирование (Рефакторинг)**: Структура тестов полностью реорганизована и разделена на логические категории: unit, integration и manual для упрощения навигации и запуска.

## 📝 Документация (Docs)
- Полностью обновлен интерактивный справочник API (`api.md`), добавлено описание модулей `cache`, `exceptions`, `time`, `features` и `lifecycle`.
- Раздел с рецептами (`recipes.md`) пополнился примерами использования CLI Booster, фича-флагов и интеграции JSON Schema в IDE.
- Значительно реорганизована и расширена папка `examples/`.

v2.7.1

# 🚀 Релиз 2.7.1 — Исправление проблем с импортом

Этот патч устраняет критическую ошибку, которая препятствовала использованию библиотеки в проектах с минимальным набором зависимостей.

## 🐛 Исправления (Bug Fixes)
- **Критический баг с ImportError**: Исправлена ошибка, из-за которой библиотека `chutils` не могла быть импортирована, если в окружении отсутствовал пакет `python-json-logger`. Теперь все опциональные компоненты корректно обрабатывают свое отсутствие, не нарушая работу основного ядра.
- **Стабильность ленивой загрузки**: Улучшена надежность механизма `__getattr__` (PEP 562) для модулей, зависящих от внешних библиотек.

## 🛡️ Улучшения стабильности (Quality of Life)
- **Smoke Tests**: Внедрена новая система «дымового тестирования». Теперь при каждой сборке автоматически проверяется работоспособность библиотеки в «пустом» окружении (без `pydantic`, `rich`, `keyring` и других экстра-зависимостей). Это гарантирует, что базовый функционал (логирование, конфиг) всегда останется доступным.
- **Безопасные экспорты**: Проведен аудит экспортируемых символов во всех подмодулях логгера, чтобы исключить подобные ошибки в будущем.

## ⚠️ Заметка по обновлению
Если вы столкнулись с ошибкой `ImportError: cannot import name 'ChutilsJsonFormatter'` при обновлении до версии 2.7.0, версия **2.7.1** полностью решает эту проблему. Рекомендуется всем пользователям.


v2.7.2
### 🐞 Исправления ошибок (Fix)
- **Восстановление API `get_config_paths()`**: Исправлена регрессия, допущенная в v2.7.0. Функция снова возвращает кортеж из 2-х элементов `(main, local)`, что устраняет ошибку `ValueError` в коде, написанном под старые версии библиотеки.
- **Детекция JSON-логгера**: Исправлена ошибка в `dev.py`, из-за которой вывод JSON содержал управляющие символы Rich, что мешало автоматическому парсингу.

### 🛠️ Улучшения и рефакторинг (Refactor)
- **Централизованная детекция окружения (env.py)**: Внедрен новый легковесный механизм обнаружения зависимостей (`rich`, `pydantic`, `watchdog`, `opentelemetry`). Теперь проверка наличия пакетов происходит через `find_spec` без их фактического импорта, что значительно ускоряет холодный старт библиотеки.
- **Публичное API (Root Exports)**: Проведен глобальный аудит экспортов. Теперь **все** публичные функции, классы, исключения и флаги доступности из подмодулей доступны напрямую через `import chutils`. Это делает библиотеку максимально удобной для использования в IDE.
- **Улучшение стабильности тестов**: Рефакторинг импортов позволил устранить проблемы с «залипанием» имен, сделав `monkeypatching` зависимостей в тестах на 100% надежным.

### 📝 Документация и CLI (Docs/CLI)
- **Интерактивная справка**: Во все команды CLI (`dev`, `config`, `secrets`) добавлены практические примеры вызова в блоке `--help`.
- **Рецепты**: В `docs/recipes.md` добавлен раздел по использованию инструментов разработчика и генерации контекста для AI-агентов.
- **Обновление API Map**: Карта проекта перегенерирована с учетом всех новых экспортов.

v2.7.3
### ✨ Новые возможности (Feat)
- **Глубокая семантическая индексация для AI**: AST-индексатор (`dev generate-context --tree`) теперь собирает расширенную структурную информацию для LLM-агентов. Добавлено:
  - Разрешение полных путей базовых классов на основе импортов модуля (информация о наследовании).
  - Извлечение методов классов (сохраняются публичные, защищенные `_method` и `__init__`; служебные dunder-методы отфильтровываются).
  - Автоматическое обнаружение абстрактных методов по декоратору `@abstractmethod`.
- **Умная настройка ширины консоли (Rich)**: Реализован механизм управления шириной вывода `rich`, решающий проблему «сломанного» форматирования и излишних переносов строк в узких терминалах IDE (например, PyCharm). Добавлено автоопределение среды (расширение до 140 символов) и возможность ручной фиксации ширины через параметр `console_width` в секции `[CLI]` файла конфигурации.

### 🐞 Исправления ошибок (Fix)
- **Падение при отсутствии опциональных зависимостей**: Исправлен критический баг в модуле `env.py`. Ранее функция `importlib.util.find_spec` выбрасывала `ModuleNotFoundError` при проверке вложенных подмодулей (например, `opentelemetry.trace`), если базовый пакет вообще не был установлен. Теперь библиотека безопасно обрабатывает такие случаи, что гарантирует работу `chutils` в минимальных (чистых) окружениях.

v2.7.4
### 🐞 Исправления ошибок (Fix)
- **Централизация приоритетов конфигурации**: Логика слияния переменных окружения (`CH_SECTION_KEY`) перенесена непосредственно в ядро системы (`core.get_config`). Это устранило критический баг, из-за которого Pydantic-модели и функция `get_config_section` игнорировали переопределения из ENV-переменных.
- **Сохранение регистра в INI-файлах**: `IniConfigProvider` теперь сохраняет оригинальный регистр ключей (`optionxform = str`), что обеспечивает консистентность поведения с YAML/JSON и гарантирует корректную работу маппинга в Pydantic-модели.

### 🛠️ Улучшения и рефакторинг (Refactor)
- **Регистронезависимый поиск (Fallback)**: В функции `get_config_value` и `get_config_section` добавлен механизм поиска без учета регистра. Если точное совпадение не найдено, система выполнит поиск в альтернативном регистре, что делает работу с ENV-переменными более устойчивой к ошибкам именования.
- **Оптимизация геттеров**: Из типизированных геттеров удалена избыточная логика ручного обращения к `os.getenv`, так как все данные теперь консолидированы в едином словаре конфигурации.

### ✅ Тесты (Test)
- **Новый набор тестов (`test_priority_unification.py`)**: Добавлены комплексные тесты для проверки приоритетов ENV в моделях, сохранения регистра в INI и корректности регистронезависимого поиска.
- **Управление состоянием**: Обновлены существующие тесты для обеспечения гарантированного сброса кэша `ConfigManager` между запусками.

v2.8.0

В этом релизе проделана колоссальная работа по улучшению безопасности, внедрению строгой типизации, ускорению холодного старта, созданию Банка few-shot примеров для ИИ и запуску встроенного инструмента для аудита AI-готовности проектов.

## ✨ Новые возможности (Features)

### 🤖 AI-интеграция и Developer Experience (DX)
- **Линтер AI-готовности кодовой базы (`ai-lint`)**: Добавлен новый статический анализатор `chutils dev ai-lint`. Он позволяет автоматически оценивать готовность проекта к работе с ИИ-агентами по ряду специализированных правил:
  - `ManifestRule` — проверка наличия и корректности ИИ-манифестов (`GEMINI.md`, `agents.md` и др.).
  - `DocstringQualityRule` — validation соответствия docstrings стандарту Google Style и наличия type hints.
  - `SecurityHardcodeRule` — поиск жестко прописанных API-ключей, токенов и паролей (комбинация AST и текстового сканирования).
  - `ChutilsIntegrationRule` — рекомендации по замене стандартных вызовов логирования/секретов на безопасные утилиты `chutils`.
  - `APIMapRule` — автоматическая сверка карты публичного API (`api_map.md`) с реальным кодом.
- **Поддержка конфигурации линтера**: Добавлена гибкая интеграция настроек линтера в `pyproject.toml` (секция `[tool.chutils.ai-lint]`), поддержка переменных окружения, CLI-флагов и файлов исключения `.chutilsignore`.
- **Банк few-shot примеров для ИИ-ассистентов (Few-Shot Bank)**: Создан каталог `docs/ai_examples/`, содержащий структурированные и проверенные примеры решения типовых задач с использованием библиотеки. Они служат контекстом (few-shot prompting) для повышения качества работы ИИ-ассистентов (Antigravity, Gemini CLI и др.).
- **Интеграция few-shot в контекст ИИ**: В команду `chutils dev generate-context` добавлена поддержка флага `--few-shot` для автоматического подмешивания базы few-shot примеров в генерируемый контекстный файл проекта.

### 🛡️ Безопасность путей (Path Traversal Protection)
- **Функция `resolve_safe_path`**: Реализован новый инструмент безопасности в модуле `chutils.fs`, предотвращающий атаки обхода директорий (Path Traversal) при работе с пользовательскими файлами. Возбуждает кастомное исключение `PathTraversalError`, если результирующий путь пытается выйти за границы разрешенной директории (sandbox).
- **Стандартизация исключений**: Все исключения библиотеки (`ChutilsException`) теперь поддерживают подробный структурированный контекст (`self.context`) и поле `hint` с дружелюбными советами для пользователя по решению возникшей ошибки.

### 🔍 Диагностика и отладка настроек
- **Вывод дефолтных настроек**: В команду `chutils config debug` добавлены параметры `--model` (`-m`) и `--defaults` (`-d`) для автоматического парсинга и отображения дефолтных значений из Pydantic моделей в истории источников.

---

## 🛠️ Улучшения и рефакторинг (Refactor & Performance)

### ⚡ Ускорение холодного старта (Lazy Imports)
- **Ленивая инициализация**: Внедрен динамический импорт через `__getattr__` (PEP 562) для тяжелых внутренних подмодулей (`config.generator`, `config.schema`, `logger.formatters`), что сократило время импорта библиотеки за счет откладывания загрузки тяжелых внешних зависимостей (`pydantic`, `python-json-logger`) до момента реального вызова функций.

### ✍️ Модульность логгера (LoggerBuilder)
- **Декомпозиция `core.py`**: Архитектура системы логирования была декомпозирована для повышения тестируемости. Логика конфигурации обработчиков, ротации и маскирования секретов вынесена в класс `LoggerBuilder` (`logger/internal/builder.py`), логика кастомных уровней (`devdebug`, `mediumdebug`) — в `logger/internal/levels.py`. Сохранена 100% обратная совместимость публичной сигнатуры `setup_logger()`.

### 🎛️ 100% Строгая типизация (Strict Mypy)
- **Strict Mode**: Вся кодовая база библиотеки переведена на строгий режим проверки типов (`strict = true`).
- **Модуль `chutils.typing`**: Создан выделенный модуль для хранения общих протоколов и сложных типов проекта. Оптимизирована и нормализована типизация декораторов (`@retry`, `@timeout`, `@trace`) с помощью `ParamSpec` и `TypeVar`.
- **Типизация примеров**: Все 21 пример в каталоге `/examples` полностью адаптированы для успешного прохождения strict Mypy.

### ⚙️ Инфраструктура и CI/CD
- **Тестирование Python 3.14**: В матрицу автоматического тестирования GitHub Actions добавлена экспериментальная поддержка Python 3.14 (pre-release), обеспечивая раннее обнаружение регрессий.

---

## 🐛 Исправления ошибок (Bug Fixes)

- **Стабильность в чистых окружениях**: Исправлен критический баг детекции пакетов, приводивший к падениям `importlib.util.find_spec` при отсутствии установленных родительских библиотек (например, `opentelemetry`).
- **Улучшенный UX при отсутствии зависимостей**: Реализован перехват `OptionalDependencyError` в CLI для вывода понятных подсказок с командами установки (`pip install chutils[...]`).
- **Интеллектуальное слияние ENV**: Исправлено слияние переменных окружения со сложными именами (содержащими подчеркивания в имени секций или ключей), благодаря чему Pydantic-модели теперь корректно получают переопределения из внешней среды.
- **Интеграция с pyfakefs**: Устранены гонки и конфликты при двойном импорте ContextVar и использовании OpenTelemetry в тестах с фейковой файсовой системой.
- **Регистр в INI**: `IniConfigProvider` теперь сохраняет оригинальный регистр ключей (`optionxform = str`) для совместимости с Pydantic.
- **AST Детекция**: Исправлено распознавание абстрактных классов в AST-индексаторе по декораторам абстрактных методов и наследованию от `ABC` / `abc.ABCMeta`.

---

## 📝 Документация (Docs)

- Добавлены подробные руководства и примеры для `ai-lint`, `resolve_safe_path` и Банка few-shot примеров.
- Карта публичного API `api_map.md` и иерархический индекс `project_index.json` полностью обновлены и перегенерированы.

v2.9.0

# 🚀 Релиз v2.9.0 — Масштабное расширение экосистемы разработки

Мы рады представить версию **2.9.0**! Мы значительно расширили инструментарий разработчика, добавив встроенную шину событий, легковесный DI-контейнер, ограничитель запросов, планировщик задач, новые криптографические и файловые утилиты, а также повысили стабильность работы в различных средах.

---

## ✨ Новые модули и возможности

### 📡 Внутренняя шина событий (`chutils.events`)
Появилась потокобезопасная in-memory шина событий:
* Декоратор `@subscribe` для регистрации синхронных и асинхронных обработчиков.
* Функции `publish` and `publish_async` для отправки событий. Асинхронные обработчики при синхронной публикации выполняются в фоновом Event Loop на выделенном потоке, не блокируя выполнение программы.
* Гибкие стратегии обработки ошибок (`IGNORE`, `FAIL_FAST`, `COLLECT` с выбросом `EventBusExceptionGroup`).
* Полная интеграция с Pydantic-моделями в качестве полезной нагрузки.

### 💉 Внедрение зависимостей (`chutils.di`)
Внедрен полноценный DI-контейнер для управления компонентами приложения:
* Жизненные циклы `singleton` (потокобезопасный с double-checked locking) и `transient`.
* Декоратор `@provide` для фабрик зависимостей.
* Декоратор `@inject` и маркер `Inject()` для прозрачного автоматического внедрения зависимостей в аргументы функций по их аннотациям типов (Auto-wiring).
* Защита от циклических зависимостей с изоляцией потоков (`threading.local`).

### ⏱ Планировщик фоновых задач (`chutils.tasks`)
Простой инструмент для запуска периодических задач:
* Декоратор `@periodic_task` для синхронных и асинхронных функций.
* Интеграция с graceful shutdown (`chutils.lifecycle`) для безопасного завершения работы.
* Контроль параллельного выполнения (`overlap=False/True`) и обработка исключений.

### 🛡️ Ограничение частоты запросов (`chutils.decorators.rate_limit`)
Добавлен мощный инструмент контроля нагрузки на функции:
* Алгоритмы *Token Bucket* (маркерная корзина с поддержкой всплесков) и *Leaky Bucket* (сглаживание нагрузки).
* Поддержка быстрого падения (`wait=False` с выбросом `RateLimitExceededError`) и ожидания (`wait=True` с приостановкой потока/таски).
* Разделение лимитов по ключам (`key_func`).

### 📁 Безопасная работа с путями и архивами (`chutils.fs`)
* **Надежное удаление (`remove_path` / `cleanup_paths`):** Удаление путей с повторными попытками при блокировках и стратегиями поведения (`raise`, `warn`, `rename_orphan`). При переносе заблокированных файлов в орфаны (`.orphan`) поддерживается разрешение коллизий имен.
* **Санитизация имен (`safe_filename`):** Очистка строк от запрещенных символов, опциональная транслитерация кириллицы в латиницу и умное ограничение длины с сохранением сложных расширений (например, `.tar.gz`).
* **Архивация каталогов (`zip_folder`):** Рекурсивное сжатие папок в ZIP с поддержкой гибкого исключения файлов по glob-шаблонам (`exclude`), например, `.git`, `*.pyc`.

### 🔏 Новые модули `text` and `crypto`
* **`chutils.text`:**
  * Естественная сортировка строк с числами (`natsort_key`).
  * Нечеткое сравнение схожести текстов (`is_significant_difference` на базе `rapidfuzz`).
* **`chutils.crypto`:**
  * Портативное детерминированное Fernet-шифрование строк и файлов по seed-паролю (детерминированная KDF на основе SHA-256).

### ⚙️ Расширение плагинной системы
* Система плагинов с ленивой загрузкой через `entry_points` для расширения провайдеров секретов, провайдеров конфигураций, обработчиков логов и метрик с полной изоляцией ошибок инициализации.

---

## 🛠️ Оптимизации и исправления (Quality of Life)

* **Устранение конфликтов тестирования:** Исправлена критическая ошибка `AttributeError: type object 'Path' has no attribute '_flavour'` при совместном использовании `pyfakefs` и `mocker` в тестах `secret_manager_env` на Python 3.10+ (фикстура `mocker` заменена на `monkeypatch` с точечным мокированием).
* **Повышение надежности `setup_logger`:** Введена строгая валидация аргументов `**kwargs`. Попытки передать невалидные параметры приводят к выбрасыванию стандартного `TypeError`.
* **Настройка логирования:** Добавлена функция `setup_logger_from_config(config_section_name)` для явного конфигурирования логгера из YAML/JSON файла настроек.
* **Исправление шаблона инициализации:** `chutils init` теперь генерирует конфигурационный файл с актуальными ключами (`log_level`, `log_file_name`) для модуля логирования.
* **CLI Трассировка:** Команда `chutils config debug` получила флаг `--include-fallbacks` для AST-парсинга дефолтных fallback-значений настроек прямо из кода.
* **CLI Сканирование сторонних проектов:** Команда `chutils dev generate-context` расширена флагом `--project` для построения семантической карты API внешних репозиториев с поддержкой парсинга правил `.gitignore` и `.chutilsignore`.
* **Документация:** Написан подробный справочник CLI команд (`docs/cli/`) для MkDocs.

---

## 📈 Покрытие и Стабильность

* Глобальный статический анализ типов `mypy --strict` успешно пройден на всей кодовой базе.
* Покрытие тестами критического модуля `fs.py` доведено до **92%**, а новые модули покрыты тестами на **98-100%**.
* Общее число тестов проекта достигло **497**, все они проходят успешно.

v3.0.0

================================================================================
📝 ТЕКСТ ДЛЯ PULL REQUEST (PR) В MASTER
================================================================================

## feat: Релиз версии v3.0.0 — Масштабная эволюция экосистемы chutils

Этот PR переводит библиотеку на мажорную версию **v3.0.0**. Произведена стабилизация и очистка API, унификация исключений, перевод на современную типизацию Python 3.10+ и интеграция продвинутых инструментов автоматизации разработки и взаимодействия с AI-агентами.

### ⚠️ Ломающие изменения (Breaking Changes)
* **Минимальные требования**: Повышена минимальная версия Python до **>= 3.10**.
* **Очистка устаревшего API**: Полностью удалены deprecated приватные глобальные переменные и функции обратной совместимости в `chutils.config` (`_BASE_DIR`, `_CONFIG_FILE_PATH`, `_initialize_paths`, `_sync_legacy_state` и др.). Внутреннее состояние теперь доступно только через публичные функции или прямой экспорт `_cm`.
* **Унификация исключений**: Все ошибки импорта опциональных зависимостей (`cryptography`, `rapidfuzz`, `keyring`, `watchdog`, `pydantic`, `httpx` и др.) переведены со стандартного `RuntimeError` на специализированный `OptionalDependencyError`.
* **Exception Groups**: Класс `EventBusExceptionGroup` теперь наследуется от стандартного `ExceptionGroup` (с использованием бэкпорта `exceptiongroup` на Python 3.10).

### ✨ Основные нововведения (Features)
* **Строгий режим геттеров (Config & Secrets)**:
  - Добавлен параметр `required=True` для всех функций `get_config_*` и `SecretManager.get_secret`. При отсутствии настроек или секретов теперь гарантированно выбрасываются `ConfigKeyNotFoundError` и `SecretNotFoundError` с детальным `context` и `hint`.
* **Инструменты AI-разработки (DX)**:
  - **`dev generate-few-shot`**: Автоматический AST-анализ целевого проекта и генерация банка few-shot примеров (`docs/ai_examples/`) для обучения ИИ правильным архитектурным паттернам кодовой базы.
  - **`dev chat-context`**: Интерактивный CLI-сборщик контекстных срезов проекта для минимизации контекстного окна LLM.
  - **`ai-lint`**: Поддержка точечного инлайн-игнорирования правил через комментарии `# chutils: ignore[RuleName]`.
* **Инструменты тестирования и мокирования**:
  - **`dev mock`**: Декларативный мок-сервер с поддержкой задержек, RegExp-подстановок, горячей перезагрузки и проксирования запросов на реальный бэкенд (`--proxy-fallback`).
  - **`dev scaffold`**: Интерактивный CLI-генератор скелета проекта по принципам Чистой Архитектуры с поддержкой инверсии зависимостей.
* **Новые функциональные модули**:
  - **`chutils.web`**: Умный HTTP-клиент (`WebClient`, `AsyncWebClient`) с автоматической ротацией прокси, User-Agent и защитой от перегрузок.
  - **`chutils.scraping.humanize`**: Математически достоверная имитация действий человека (кривые Безье для мыши, логнормальные паузы, опечатки клавиатуры) и обход детект-систем для Playwright и Selenium.
  - **`chutils.scraping.captcha`**: Клиенты для RuCaptcha, Anti-Captcha и CapMonster Cloud.
  - **`chutils.decorators.circuit_breaker`**: Паттерн предохранителя для изоляции и автоматического восстановления при сбоях внешних интеграций.
* **Git-интеграция**:
  - **`dev install-hooks`**: Автоматическая установка и настройка Git pre-commit хуков (Ruff, Mypy) в целевые репозитории.

### 🔧 Улучшения и рефакторинг (Refactor)
* Полный переход на встроенную типизацию Python 3.10+ (отказ от `typing.Optional`, `typing.List` и т.д. в пользу `T | None` и `list[T]`).
* Успешно пройдена проверка `mypy --strict` на 100% кодовой базы библиотеки и примеров.
* Написаны TDD-тесты для всех новых возможностей, покрытие ключевых модулей составляет **92-100%**. Общее число тестов проекта выросло до **635** (все тесты успешно проходят).

---

================================================================================
🚀 ТЕКСТ ДЛЯ РЕЛИЗА (RELEASE NOTES)
================================================================================

# 🚀 Релиз v3.0.0 — Масштабная эволюция экосистемы chutils

Мы рады представить долгожданную мажорную версию **v3.0.0**! В этом релизе мы провели глубокую чистку API, повысили строгость типизации и безопасности, а также значительно расширили возможности библиотеки для автоматизации веб-скрейпинга, безопасной настройки и продвинутого взаимодействия с AI-ассистентами.

---

## ⚠️ Ломающие изменения (Breaking Changes)

1. **Python 3.10+**: Минимальная поддерживаемая версия Python повышена до **3.10**. Поддержка Python 3.9 прекращена.
2. **Удаление устаревшей конфигурации**: Из модуля `chutils.config` удалены все deprecated-переменные (`_BASE_DIR`, `_CONFIG_FILE_PATH`, `_initialize_paths` и др.). Для доступа к путям используйте публичные функции `get_config_paths()` и `are_paths_initialized()`.
3. **Унификация ошибок**: Ошибки отсутствия опциональных зависимостей (extras) теперь стандартизированы. Вместо `RuntimeError` выбрасывается `OptionalDependencyError` (наследуется от `ChutilsException`). Исключение снабжено свойством `hint`, которое подскажет точную команду для установки нужного пакета (например, `pip install chutils[crypto]`).
4. **Exception Groups**: Класс `EventBusExceptionGroup` теперь унаследован от стандартного `ExceptionGroup` (с автоматическим фоллбеком для Python 3.10), что позволяет использовать современную конструкцию `except*` для обработки событий.

---

## ✨ Новые возможности (Features)

### 🤖 AI-интеграция и Developer Experience (DX)
* **Банк few-shot примеров (`dev generate-few-shot`)**: Новая CLI-команда анализирует проект с помощью AST, находит используемые архитектурные слои (Use Cases, Repositories, DI, Logger, Exceptions) и автоматически генерирует для них качественные примеры в `docs/ai_examples/`, а также обновляет `GEMINI.md` манифест. Это существенно повышает качество работы внешних AI-агентов с вашим кодом.
* **Контекстный AI-срез (`dev chat-context`)**: Команда с интерактивным интерфейсом собирает только нужные части проекта и примеры в один компактный Markdown-файл, экономя токены при передаче контекста в LLM.
* **Игнорирование правил в `ai-lint`**: Поддерживается гибкое инлайн-игнорирование статических проверок через комментарии вида `# chutils: ignore[RuleName]`.

### 🛡️ Строгий режим API (Strict mode)
* В геттеры конфигурации `get_config_*` и получение секретов `SecretManager.get_secret` добавлен флаг `required: bool = False`. Если передать `required=True`, библиотека гарантированно выбросит `ConfigKeyNotFoundError` или `SecretNotFoundError` вместо возврата `None`.

### 🌐 Умная автоматизация и веб-скрейпинг
* **`chutils.web`**: Модуль умного HTTP-клиента с автоматической ротацией User-Agent, интеграцией пулов прокси и защитой от частых запросов (Rate Limiter).
* **`chutils.scraping.humanize`**: Библиотека имитации поведения человека. Включает генерацию движения курсора мыши по кривым Безье, клавиатурный ввод с джиттером и симуляцией опечаток, а также маскировку Selenium/Playwright для обхода Cloudflare и анти-бот систем.
* **`chutils.scraping.captcha`**: Клиенты для интеграции с RuCaptcha, Anti-Captcha и CapMonster Cloud.

### 🛡️ Паттерн Circuit Breaker (Предохранитель)
* Декоратор `@circuit_breaker` для защиты приложения от падений внешних HTTP API. Поддерживает переключение состояний (CLOSED, OPEN, HALF-OPEN), блокировку повторных запросов на время восстановления и потокобезопасность.

### 🛠️ Инфраструктура разработки
* **`dev scaffold`**: CLI-генератор структуры проекта по Clean Architecture. Создает шаблоны домена, прикладного слоя, презентации и DI-контейнера.
* **`dev mock`**: Декларативный локальный HTTP мок-сервер с поддержкой конфигурации в YAML/JSON, RegExp в роутах и горячей перезагрузки.
* **`dev install-hooks`**: Быстрая установка Git-хуков (pre-commit, commit-msg) для запуска проверок Ruff и Mypy перед коммитом.

---

## 📈 Покрытие и Стабильность
* Кодовая база переведена на строгий режим проверки типов (`strict = true` в mypy).
* Написаны детальные тесты для всех модулей, общее число тестов достигло **635** (покрытие нового кода составляет **>92%**).
* Документация (MkDocs) полностью синхронизирована с новыми модулями, добавлены страницы `docs/web.md`, `docs/scraping.md`, `docs/captcha.md` и руководство `docs/dependencies.md`.
