Metadata-Version: 2.4
Name: sctodo
Version: 0.2.3
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
Project-URL: PyPI, https://pypi.org/project/sctodo/
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)

[![PyPI](https://img.shields.io/pypi/v/sctodo)](https://pypi.org/project/sctodo/)

Утилита для учёта задач прямо в исходниках: ищет метки `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`](https://pypi.org/project/sctodo/)** опубликован на PyPI; CLI-команда после установки — **`sct`**:

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

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

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

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

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

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

```bash
# 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`](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`

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

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

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

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

```bash
sct list --json
```

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

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

## Тесты

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