sctodo 0.2.3

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 (рекомендуется)

Пакет sctodo опубликован на PyPI; CLI-команда после установки — sct:

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

Требуется Python ≥ 3.10. Актуальная версия на PyPI: 0.2.3.

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

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.

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

После pip install sctodo или pipx install sctodo команда доступна как sct. Ниже — те же примеры; при разработке из исходников замените sct на .venv/bin/sct.

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

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

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

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

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

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

sct --version
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

Какие файлы сканируются

По умолчанию — текстовые файлы с расширениями из DEFAULT_INCLUDE_SUFFIXES в sct/core/config.py:

.py, .pyi, .rs, .go, .js, .jsx, .ts, .tsx, .c, .h, .cpp, .hpp, .java, .kt, .lua, .vim, .sh, .bash, .zsh, .md, .yaml, .yml, .toml, .json, .sql, .rb, .php, .swift, .scala, .cs, .html, .css, .scss, .tf

Файлы без расширения и с другими суффиксами пропускаются. Содержимое читается как UTF-8.

Исключения по каталогам (DEFAULT_EXCLUDE_DIRS): .git, .hg, .svn, __pycache__, .venv, venv, node_modules, .mypy_cache, .pytest_cache, .ruff_cache, dist, build, .sct, tests, test.

Дополнительно не заходят в каталоги, имя которых начинается с . (например .github), даже если их нет в списке.

Настройка через .sct/config.json

{
  "include_suffixes": [".py", ".md", ".tf"],
  "exclude_dirs": ["vendor"]
}

• include_suffixes — заменяет дефолтный список расширений целиком.
• exclude_dirs — добавляет каталоги к дефолтному списку исключений (дефолт не убирается).

После правки конфига выполните sct sync --full.

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

sct list --json

{
  "version": "0.2.3",
  "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.