Metadata-Version: 2.4
Name: sctodo
Version: 0.2.2
Summary: Source Code Todo — scan TODO/DONE markers in code
Author: Basyrov Rustam
License-Expression: MIT
Project-URL: Homepage, https://github.com/rustbas/sct
Project-URL: Repository, https://github.com/rustbas/sct
Project-URL: Changelog, https://github.com/rustbas/sct/blob/main/CHANGELOG.md
Keywords: todo,source-code,cli,tui,textual
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual<1.0.0,>=0.47.0
Provides-Extra: dev
Dynamic: license-file

# 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`**:

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

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

```bash
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`.

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

```bash
# 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 для скриптов

```bash
.venv/bin/sct list --json
```

```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` | Выход |

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

## Тесты

```bash
.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](CHANGELOG.md).
