sctodo 0.2.2

Source Code Todo — scan TODO/DONE markers in code

Source Code Todo (sct)

Утилита для учёта задач прямо в исходниках: ищет метки TODO / DONE в коде, кэширует состояние в JSON и даёт CLI и TUI для просмотра и закрытия задач.

[!WARNING] Примечание: проект завайбкожен — большая часть кода и документации собрана с помощью ИИ (Cursor). С версии 0.2.0 добавлены тесты, CI и проверки перед правкой файлов; всё равно смотрите diff перед коммитом.

Идея

Пишешь код в редакторе (например, Neovim). Если что-то нужно доделать позже — оставляешь в файле метку с текстом задачи. sct сканирует проект, показывает список в терминале и при необходимости меняет метку в файле на DONE, сохраняя приоритет.

Приоритет кодируется буквами в маркере:

Маркер (открыто)	Приоритет
TODO	1
TODOO	2
TODOOO	3

Для закрытых задач — то же с DONE / DONEE / DONEEE (столько же букв E, сколько было O).

Установка

PyPI (рекомендуется)

Пакет на PyPI называется sctodo, CLI-команда — sct:

pip install sctodo
# или изолированно в ~/.local/bin:
pipx install sctodo

Из исходников (разработка)

cd /path/to/sct
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pip install -e .

Метаданные пакета и console-script sct — в pyproject.toml.

Использование

# TUI (нужен интерактивный терминал)
.venv/bin/sct

# Первичная настройка каталога .sct/
.venv/bin/sct init

# Синхронизация (по умолчанию инкрементальная)
.venv/bin/sct sync
.venv/bin/sct sync --full -v

# Проверка кэша и исходников
.venv/bin/sct doctor
.venv/bin/sct doctor --compare

# Список открытых задач (id в каждой строке)
.venv/bin/sct list
.venv/bin/sct list --no-id          # компактный вид
.venv/bin/sct list --priority 2
.venv/bin/sct list --all --json

# Закрыть / открыть: id, короткий префикс id (как git), или file:line
.venv/bin/sct done dd5be318
.venv/bin/sct done path/to/file.py:12
.venv/bin/sct done --dry-run dd5be
.venv/bin/sct reopen <id>

.venv/bin/sct --version
.venv/bin/python -m sct sync

Корень проекта ищется вверх по каталогам (наличие .sct/cache.json или .sct/config.json), либо задайте --root.

После обновления с 0.2.1 на 0.2.2 один раз выполните sct sync --full — схема id задач изменилась (теперь hash файла + номера строки).

Коды выхода

Код	Значение
0	Успех
1	Не найдено / неоднозначный префикс id
2	Устаревший кэш / строка изменилась (doctor, done)
3	Ошибка ввода-вывода
4	Неверное использование (например, TUI без TTY)

Метки в коде

Формат: TOD + от одной до трёх O (открыто) или DON + от одной до трёх E (сделано), затем : и текст задачи.

Примеры в исходных файлах (отдельная строка комментария):

• # TOD + O: + текст — приоритет 1, открыто
• # TOD + OO: + текст — приоритет 2
• # TOD + OOO: + текст — приоритет 3
• # DON + E: + текст — закрыто, приоритет 1

(В этом README маркеры разбиты, чтобы файл документации не попадал в собственный сканер.)

Кэш и конфиг

• Кэш: .sct/cache.json (в .gitignore)
• Конфиг: .sct/config.json — создайте через sct init или скопируйте .sct/config.json.example
• По умолчанию не сканируются каталоги tests/, test/, .venv, node_modules и др. (см. sct/core/config.py)

JSON для скриптов

.venv/bin/sct list --json

{
  "version": "0.2.0",
  "items": [ { "id": "…", "file": "…", "line": 1, … } ]
}

Удобно вызывать из Neovim через jobstart / system без отдельного плагина.

Клавиши TUI

Тёмный минималистичный интерфейс: список задач, строка деталей, статусная строка внизу.

Клавиша	Действие
j / k	Вниз / вверх по списку
g / G	Первая / последняя строка
Ctrl+d / Ctrl+u	Страница вниз / вверх
d	Закрыть задачу (с подтверждением)
o	Открыть снова
r	Синхронизация
a	Все / только открытые
/	Фильтр
?	Подсказка
q	Выход

При устаревшем кэше при старте показывается предупреждение.

Тесты

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

В CI то же самое (см. .github/workflows/ci.yml).

Планы

• Плагин или рецепты для Neovim (обёртка над sct list --json, переход к file:line)
• Создание GitHub Issues из задачи (заготовка в sct/core/github.py, пока не реализовано)

История версий

См. CHANGELOG.md.