Skip to content

IMPROVEMENT_PLAN.md

Latest commit

 

History

History
155 lines (114 loc) · 8.89 KB

IMPROVEMENT_PLAN.md

File metadata and controls

155 lines (114 loc) · 8.89 KB

План работ по улучшению Code2MARKDOWN

Введение

Этот план разработан на основе руководств по качеству кода и структуре скриптов, найденных в папке .roo/rules. Цель - улучшить структуру проекта, качество кода и процессы разработки для Code2MARKDOWN.

1. Улучшение структуры проекта и управления зависимостями

Задачи:

  1. Миграция на uv:

    • Инициализировать проект с помощью uv init
    • Перенести зависимости из requirements.txt в pyproject.toml
    • Разделить runtime и dev зависимости
    • Настроить синхронизацию окружения через uv sync

  2. Реорганизация структуры каталогов:

    • Переместить основной код в src/ каталог
    • Убедиться, что структура тестов зеркальна структуре src/
    • Обновить все импорты в соответствии с новой структурой

  3. Обновление .gitignore:

    • Добавить стандартные игнорируемые файлы и каталоги Python
    • Убедиться, что все логи, временные файлы и артефакты сборки исключены

2. Улучшение импортов и архитектуры

Задачи:

  1. Переход на абсолютные импорты:

    • Проверить и обновить все относительные импорты на абсолютные
    • Убедиться, что структура пакетов поддерживает абсолютные импорты

  2. Принцип инверсии зависимостей:

    • Проанализировать архитектуру на предмет соблюдения принципа инверсии зависимостей
    • При необходимости рефакторить код для улучшения архитектуры

  3. Проверка на циклические импорты:

    • Настроить pre-commit hook для проверки циклических импортов
    • Устранить все найденные циклические импорты

3. Настройка автоматического контроля качества

Задачи:

  1. Конфигурация Ruff:

    • Настроить Ruff в pyproject.toml согласно рекомендациям
    • Интегрировать ruff-format для автоформатирования кода

  2. Настройка pre-commit хуков:

    • Создать .pre-commit-config.yaml
    • Добавить хуки для Ruff, ruff-format и mypy
    • Добавить локальный хук для проверки циклических импортов
    • Установить хуки через pre-commit install

  3. Интеграция mypy:

    • Настроить mypy в pyproject.toml
    • Добавить аннотации типов в код где это необходимо

4. Улучшение тестирования

Задачи:

  1. Реорганизация тестов:

    • Убедиться, что структура тестов зеркальна структуре src/
    • Обновить импорты в тестах при необходимости

  2. Измерение покрытия кода:

    • Настроить измерение покрытия кода тестами
    • Добавить проверку покрытия в CI/CD

  3. Расширение тестового покрытия:

    • Написать недостающие тесты для ключевых компонентов
    • Добавить тесты для новых функций

5. Рефакторинг и техническое обслуживание

Задачи:

  1. Удаление мертвого кода:

    • Запустить ruff check . --select F401,F841 --fix для автоматического удаления неиспользуемого кода
    • Провести ручной аудит кода на предмет неиспользуемых функций и переменных

  2. Аудит зависимостей:

    • Настроить регулярную проверку устаревших зависимостей
    • Обновить зависимости до последних версий

  3. Анализ архитектуры:

    • Создать или обновить скрипт для анализа архитектуры проекта
    • Запускать его регулярно для выявления проблем

6. Организация вспомогательных скриптов

Задачи:

  1. Создание структуры для скриптов:

    • Создать каталог scripts/development/
    • Переместить или создать вспомогательные скрипты в этой директории

  2. Документирование скриптов:

    • Добавить docstring к каждому скрипту
    • Создать README.md в каталоге скриптов с описанием их назначения

  3. Упаковка логики в модули:

    • Преобразовать shell команды в Python скрипты с аргументами
    • Вынести общую функциональность в утилитарные модули

  4. Изоляция среды:

    • При необходимости настроить отдельное окружение для скриптов
    • Документировать зависимости скриптов

7. CI/CD интеграция

Задачи:

  1. Интеграция скриптов в CI/CD:

    • Добавить шаги для выполнения вспомогательных скриптов в CI/CD
    • Убедиться, что скрипты не влияют на сборку production версии

  2. Контроль качества в CI/CD:

    • Добавить шаги для Ruff, mypy и других инструментов контроля качества
    • Настроить проверку покрытия кода

8. Анализ логов и отслеживание ошибок

Задачи:

  1. Система анализа логов:

    • Создать скрипт или инструмент для анализа логов выполнения скриптов
    • Настроить сбор и анализ stdout/stderr

  2. Отслеживание ошибок:

    • Реализовать механизм для суммирования результатов выполнения скриптов
    • Настроить уведомления о критических ошибках

9. Управление жизненным циклом скриптов

Задачи:

  1. Архивация скриптов:
    • Создать каталог scripts/development/archive/
    • Переместить неиспользуемые скрипты в архив
    • Документировать причины архивации

Приоритеты и сроки

  1. Высокий приоритет (1-2 недели):

    • Миграция на uv и реорганизация структуры проекта
    • Настройка автоматического контроля качества
    • Переход на абсолютные импорты

  2. Средний приоритет (2-4 недели):

    • Улучшение тестирования и измерение покрытия
    • Рефакторинг и удаление мертвого кода
    • Организация вспомогательных скриптов

  3. Низкий приоритет (1-2 месяца):

    • CI/CD интеграция
    • Анализ логов и отслеживание ошибок
    • Управление жизненным циклом скриптов

Заключение

Этот план поможет улучшить качество кода, организацию проекта и процессы разработки для Code2MARKDOWN. Следование этим рекомендациям приведет к более поддерживаемому и надежному коду, а также улучшит опыт разработчиков, работающих с проектом.