# Changelog

Все важные изменения в проекте Fishertools будут документированы в этом файле.

## [0.4.5] - 2026-02-02

### 🐛 Critical Bug Fixes

**Исправлены критические ошибки в fishertools v0.4.4.2**

#### ✅ Исправлен модуль обучения (Learning Module)
- **Проблема:** FileNotFoundError при вызове `explain("lists")` - файл explanations.json не включался в пакет
- **Решение:** 
  - Создан `ExplanationLoader` с использованием `importlib.resources` для надежной загрузки
  - Обновлены MANIFEST.in и setup.py для включения JSON файлов
  - Добавлены fallback механизмы для разных версий Python
  - Четкие сообщения об ошибках при отсутствии файлов

#### 🔧 Улучшены сообщения об ошибках валидации
- **Проблема:** `validate_number("string", 0, 100)` выдавал непонятную ошибку сравнения операторов
- **Решение:**
  - Обернуты внутренние сравнения типов в try-catch блоки
  - ValidationError теперь содержит фактический и ожидаемый типы
  - Специальная обработка для None значений
  - Сообщения: "Expected number, got str" вместо технических ошибок Python

#### 📖 Добавлены контекстные объяснения ошибок
- **Новая функция:** `explain_error()` для образовательных объяснений ошибок валидации
- Система сопоставления паттернов ошибок с объяснениями
- Примеры исправления для распространенных ошибок
- Fallback объяснения для неизвестных паттернов
- Прогрессивно детальные объяснения для повторяющихся ошибок

#### 🎨 Улучшено форматирование строк (safe_format)
- **Новая функция:** Настраиваемое поведение для отсутствующих плейсхолдеров
- **PlaceholderBehavior enum:**
  - `PRESERVE` - оставляет оригинальные плейсхолдеры: `{name}`
  - `MISSING` - заменяет на: `[MISSING: name]` (по умолчанию)
  - `EMPTY` - заменяет пустой строкой
- Четкий API для конфигурации поведения
- Обратная совместимость с существующим кодом

#### ➕ Добавлена функция safe_average()
- **Новая функция:** Безопасное вычисление среднего с защитой от ошибок
- Возвращает указанное значение по умолчанию для пустых списков
- Автоматически фильтрует нечисловые значения
- Примеры:
  - `safe_average([1, 2, 3])` → `2.0`
  - `safe_average([], default=0)` → `0`
  - `safe_average([1, "text", 3])` → `2.0` (фильтрует "text")

#### 🛡️ Комплексная обработка ошибок
- Образовательные сообщения об ошибках для всех функций fishertools
- Объяснения для начинающих для распространенных ошибок Python
- Двухуровневое логирование (детальное для отладки, простое для пользователей)
- Предложения по исправлению для ошибок импорта и файловых операций
- Graceful degradation вместо полного отказа

#### ✅ Обеспечена обратная совместимость
- Все существующие сигнатуры функций сохранены
- Иерархия исключений ValidationError не изменена
- Debug декораторы сохраняют тот же формат вывода
- Никакие публичные функции или классы не удалены/переименованы
- Существующий код продолжает работать без изменений

#### 📦 Целостность распространения пакета
- Правильная конфигурация MANIFEST.in для включения JSON файлов
- Обновлены setup.py/pyproject.toml с package_data
- Поддержка как development, так и production установки
- Модуль обучения успешно находит файлы данных независимо от метода установки

#### 📊 Тестирование
- **341 новых тестов** для всех исправлений
- **99.6% успешных тестов** (340 из 341)
- Property-based тесты с Hypothesis для универсальной корректности
- Unit тесты для конкретных примеров и граничных случаев
- Тесты интеграции между модулями
- Тесты обратной совместимости

**Приоритет исправлений:** Критические → Высокие → Средние
- ✅ Критические: Модуль обучения (Requirement 1)
- ✅ Высокие: Сообщения об ошибках валидации (Requirement 2)
- ✅ Высокие: Контекстные объяснения (Requirement 3)
- ✅ Средние: Улучшения safe_format (Requirement 4)
- ✅ Средние: Функция safe_average (Requirement 5)
- ✅ Критические: Обратная совместимость (Requirement 6)
- ✅ Критические: Целостность пакета (Requirement 7)
- ✅ Высокие: Надежность обработки ошибок (Requirement 8)

## [0.4.4] - 2026-02-01

### 🚀 Major Code Quality Improvements

**Профессиональный рефакторинг на основе Code Review**

#### ✨ Новые возможности:
- **Единый источник версии** - создан `fishertools/_version.py` для централизованного управления версией
- **Улучшенная валидация входных данных** - `ask_int()` и `ask_float()` теперь с защитой от бесконечных циклов
- **Оптимизированные регулярные выражения** - предкомпилированные паттерны в `helpers.py` для лучшей производительности

#### 🔧 Улучшения качества кода:
- **Полные type hints** - добавлены `TypeVar` и `ParamSpec` в `decorators.py` для строгой типизации
- **Улучшенная обработка ошибок** - валидация параметров в `input_utils.py` (проверка min_val < max_val)
- **Защита от DoS** - добавлен параметр `max_attempts` в функции ввода
- **Оптимизация производительности** - предкомпилированные regex паттерны в `helpers.py`

#### 🐛 Bug Fixes:
- **Fixed undefined variable** - `standalone_escape` in `errors/formatters.py` (existing bug)
- **Consolidated regex patterns** - removed duplicate `ansi_escape` definition

#### 📦 Управление зависимостями:
- **Точное версионирование** - requirements.txt теперь с фиксированными версиями (requests==2.31.0, click==8.3.1)
- **Опциональные зависимости** - pyyaml вынесен в `[config]` extra для уменьшения базовых зависимостей
- **Улучшенная структура** - pyproject.toml с правильными диапазонами версий (>=X.Y.Z,<X+1.0.0)

#### 🛡️ Безопасность:
- **Валидация параметров** - проверка пустых промптов и некорректных диапазонов
- **Graceful error handling** - правильная обработка KeyboardInterrupt и EOFError
- **Type safety** - полная типизация для предотвращения runtime ошибок

#### 📚 Документация:
- **Улучшенные docstrings** - добавлены примеры использования и описания исключений
- **Консистентная версия** - синхронизация версий между setup.py, pyproject.toml и __init__.py

**Технический долг:** Устранены критические проблемы из Code Review:
- ✅ Несоответствие версий (HIGH)
- ✅ Отсутствие type hints в legacy модулях (HIGH)
- ✅ Отсутствие версионирования зависимостей (HIGH)
- ✅ Недостаточная валидация входных данных (MEDIUM)
- ✅ Неоптимальные регулярные выражения (LOW)

## [0.4.3.3] - 2026-02-01

### 🔧 Code Quality Improvements

**Масштабная оптимизация кода - устранены дублирующиеся литералы и снижена когнитивная сложность**

#### 📝 Константы вместо дублирующихся литералов:
- **fishertools/documentation/generator.py** - константы для имен файлов (INDEX_RST, CONF_PY, etc.)
- **fishertools/documentation/visual.py** - константы для HTML тегов (DIV_CLOSE, DIV_OPEN)
- **fishertools/examples/logger_example.py** - константы для имен лог-файлов
- **fishertools/examples/repository.py** - полный набор констант для концепций и паттернов кода
- **fishertools/learn/repl/command_handler.py** - константы для сообщений пользователю
- **fishertools/learn/repl/command_parser.py** - константы для сообщений об ошибках

#### 🧠 Рефакторинг сложных функций:
- **fishertools/examples/repository.py** - разбита анонимная функция с когнитивной сложностью 46 на множество специализированных методов
- **fishertools/learn/repl/engine.py** - функция `_handle_command` (сложность 65→15) разбита на 15 специализированных методов

#### 🐛 Исправлены синтаксические ошибки:
- **fishertools/documentation/api.py** - исправлена индентация и удален дублирующийся код
- **fishertools/readme_transformer.py** - исправлена индентация в блоке try-except
- **fishertools/visualization/formatters.py** - удален дублирующийся код функции

Код стал значительно более читаемым, поддерживаемым и менее подверженным ошибкам.

## [0.4.3.2] - 2026-02-01

### 🐛 Bug Fixes

**Исправлена ошибка индентации в readme_transformer.py**

#### Исправленные файлы:
- `fishertools/readme_transformer.py` - исправлена индентация в методе write_transformed_readme

Это исправление устраняет IndentationError в блоке try-except, который препятствовал корректной работе трансформера README.

## [0.4.3.1] - 2026-02-01

### 🐛 Bug Fixes

**Исправлены синтаксические ошибки в модуле documentation**

#### Исправленные файлы:
- `fishertools/documentation/code_validator.py` - удален дублирующийся код метода
- `fishertools/documentation/examples_manager.py` - добавлен отсутствующий блок except
- `fishertools/documentation/generator.py` - исправлена индентация в методе _generate_readthedocs_config

Эти исправления устраняют ошибки IndentationError и SyntaxError, которые препятствовали корректной работе модуля документации.

## [Unreleased] - 2026-01-30

### 🔧 Code Quality Refactoring (v0.4.3)

**Исправлен "spaghetti code" - библиотека стала более человечной!**

#### ✅ Реализован safe_string_operations
- **Было:** Stub-метод с `pass` (ничего не делал)
- **Стало:** Полноценный модуль с 6 функциями:
  - `safe_strip()` - безопасный strip с обработкой None
  - `safe_split()` - безопасный split с обработкой None
  - `safe_join()` - безопасный join с пропуском None
  - `safe_format()` - безопасное форматирование строк
  - `safe_lower()` / `safe_upper()` - безопасное изменение регистра

#### 🔢 Исправлена математика в safe_divide
- **Было:** `safe_divide(10, 0) = 0` (математически НЕПРАВИЛЬНО!)
- **Стало:** `safe_divide(10, 0) = None` (честно: результат неопределен)
- Можно явно указать default: `safe_divide(10, 0, default=0)`

#### 🐍 Упрощена обработка ошибок (Pythonic подход)
- Убраны избыточные проверки типов (было 50+ строк, стало 10)
- Используется EAFP (Easier to Ask Forgiveness than Permission)
- Проверяются только явно неправильные типы (None, bool, complex)
- Код стал проще и понятнее

#### 📦 Упрощены функции коллекций
- `safe_max()`, `safe_min()`, `safe_sum()` - с 30+ строк до 5 строк
- `safe_get()` - универсальный getter для любых коллекций
- Меньше кода, больше читаемости

#### 📊 Результаты
- ✅ Все 82 теста проходят
- 📉 -150 строк избыточного кода
- 📈 +6 новых полезных функций
- 🎯 100% математическая корректность

#### 📝 Документация
- Добавлен `REFACTORING_SUMMARY.md` с подробным описанием изменений
- Добавлен `examples/refactored_safe_usage.py` с примерами использования
- Обновлены docstrings с честными примерами

## [0.4.1] - 2026-01-29

### 🎨 Phase 1: Core Modules (Visualization, Validation, Debug)

**Три новых мощных модуля для разработки и обучения:**

#### 📊 Visualization Module
- `visualize()` - визуализация структур данных в понятном формате
- Поддержка списков, словарей, вложенных структур
- Ограничение глубины и количества элементов
- Форматирование с индексами и ключами

#### ✅ Validation Module
- `@validate_types` - проверка типов через type hints
- `validate_email()`, `validate_url()` - валидация данных
- `validate_number()`, `validate_string()` - проверка значений
- `validate_structure()` - валидация структуры данных
- `ValidationError` - исключение для ошибок валидации

#### 🔍 Debug Module
- `@debug_step_by_step` - пошаговое выполнение функций
- `@trace` - трассировка вызовов функций
- `set_breakpoint()` - точки останова для отладки
- Визуализация стека вызовов и значений переменных

#### 📈 Тестирование
- 65+ новых тестов для всех модулей
- 90%+ покрытие кода
- Property-based тесты с Hypothesis

---

## [0.4.0] - 2026-01-29

### 🎓 Knowledge Engine Interactive REPL

**Полнофункциональный интерактивный REPL для обучения Python:**

#### 🎯 Основные компоненты
- **REPLEngine** - главный интерактивный цикл с управлением состоянием
- **CommandParser** - парсинг пользовательского ввода с поддержкой команд и тем
- **CodeSandbox** - безопасное выполнение кода с ограничениями и таймаутом
- **SessionManager** - отслеживание прогресса и сохранение состояния сессии
- **CommandHandler** - обработка всех команд REPL
- **TopicDisplay** - форматирование и отображение тем

#### 📚 Функциональность
- **Просмотр тем:** /list, /search, /random, /categories, /category, /path
- **Навигация:** /next, /prev, /goto, /related
- **Выполнение кода:** /run, /modify, /exit_edit
- **Отслеживание прогресса:** /progress, /stats, /reset_progress
- **Управление сессией:** /history, /clear_history, /session
- **Справка:** /help, /commands, /about, /hint, /tip, /tips

#### 🔒 Безопасность
- Ограничение доступа к опасным операциям (file I/O, imports)
- Таймаут выполнения кода (5 секунд по умолчанию)
- Валидация кода перед выполнением
