SysDevCleaner/README.md

# SysDevCleaner

<img src="sysdevcleaner.png" width="96" align="right" alt="значок SysDevCleaner">

Приложение для полного анализа Windows: находит кеши, временный мусор, остатки
разработки и тяжёлые программы, объясняет, что каждая находка означает, и даёт
удалить ровно то, что вы отметили.

Нужен Python 3.10+ и одна зависимость — [Dear PyGui](https://github.com/hoffstadt/DearPyGui)
(`pip install dearpygui`); `SysDevCleaner.bat` ставит её сам при первом запуске.
Если Dear PyGui недоступен, приложение откатывается на запасной интерфейс
на tkinter из стандартной библиотеки.

## Запуск

| Что запустить | Зачем |
|---|---|
| `SysDevCleaner.bat` | запуск с графическим интерфейсом |
| `SysDevCleaner-no-admin.bat` | то же, но без повышения прав |
| `sysdevcleaner-cli.bat` | консольный режим |
| `python run.py` | запуск из исходников |
| `python -m sysdevcleaner` | то же самое |
| `build-exe.bat` | собрать `dist\SysDevCleaner.exe` |
| `python make_icon.py` | перерисовать значок `sysdevcleaner.ico` |

## Права администратора

Приложение **всегда запускается с правами администратора**: без них недоступны
`Windows\Temp`, кеш обновлений Windows, Prefetch, `Windows.old` и история
Defender — а это обычно самая крупная добыча (у автора на тестовой машине
8.5 ГБ из 17.5 ГБ).

Как это сделано:

* собранный `SysDevCleaner.exe` несёт манифест UAC (`requireAdministrator`) —
  Windows поднимает права ещё до старта Python;
* при запуске из исходников приложение само перезапускается через
  `ShellExecuteW` с глаголом `runas` (см. `sysdevcleaner/winui.py`).

Отказ в UAC не фатален: программа продолжит работу с обычными правами, честно
напишет об этом в заголовке окна и в шапке, а недоступные пункты покажет
отдельной рекомендацией. Чтобы сознательно запуститься без повышения —
`SysDevCleaner-no-admin.bat` или переменная окружения `SYSDEVCLEAN_NO_ELEVATE=1`.

Консольный режим права не повышает: elevation открыл бы отдельное окно, и вывод
команды потерялся бы. Запускайте `sysdevcleaner-cli.bat` из консоли администратора,
если нужен полный охват.

## Заголовок окна

`dpg.create_viewport(title=...)` отдаёт заголовок в ANSI-функцию Windows как
UTF-8 байты, из-за чего русское название превращалось в
«SysDevCleaner вЂ" анализ...». Поэтому окно создаётся со служебным
ASCII-заголовком, а настоящее имя ставится через `SetWindowTextW` (UTF-16) —
`sysdevcleaner/winui.py`.

## Выбор дисков

По умолчанию сканируются все диски. Чтобы ограничить область, снимите лишние
флажки в строке **«Сканировать диски»** под заголовком окна — рядом появится
подпись вроде «только D:». Кнопка **«все»** возвращает полный охват.

Фильтр применяется ко всему сразу: к правилам путей, к поиску проектов, крупных
файлов и дубликатов, к списку дисков в отчёте. «Просканировать только D:»
действительно не трогает C:.

На вкладке «Обзор» у каждого диска есть кнопка **«только этот»** — один клик
ограничивает область этим диском и сразу запускает сканирование.

В консоли то же самое делает `--drive`:

```bash
python -m sysdevcleaner --drive D --categories projects
```

## Сборка в exe

```bash
build-exe.bat
```

Готовый файл появится в `dist\SysDevCleaner.exe` (~15 МБ, одним файлом).
Скрипт сам доставит PyInstaller и Dear PyGui, если их нет, **вошьёт в сборку
JetBrains Mono Nerd Font** (иначе на чужой машине без этого шрифта интерфейс
останется с кириллицей, но без иконок) и **встроит манифест UAC**, чтобы exe
сразу запрашивал права администратора.

Значок берётся из `sysdevcleaner.ico` — он ставится и на сам exe, и на окно
приложения (`create_viewport(small_icon=…, large_icon=…)`), поэтому иконка
одинакова в проводнике, на панели задач и в заголовке. Перерисовать:
`python make_icon.py` — метла рисуется геометрией, без зависимости от шрифта,
чтобы оставаться разборчивой на 16×16.

Ключи `build_exe.py`:

| Ключ | Что делает |
|---|---|
| `--onedir` | папка вместо одного файла: запускается быстрее, без распаковки во временный каталог |
| `--no-admin` | не встраивать манифест UAC (по умолчанию он есть) |
| `--no-font` | не вшивать шрифт, брать системный |
| `--console` | оставить окно консоли, чтобы видеть ошибки |
| `--icon ФАЙЛ` | свой значок `.ico` |

Шрифт можно подменить без пересборки: положите свой TTF в папку `fonts` рядом
с `SysDevCleaner.exe`.

## Шрифт и кириллица

Интерфейс построен на Dear PyGui, а тот рисует текст встроенным шрифтом
ProggyClean, в котором **нет кириллицы** — без настройки весь русский текст
превращается в пустые квадраты. Решение живёт в `sysdevcleaner/gui/fonts.py`:

1. после `create_context()`, но **до** `setup_dearpygui()` регистрируем свой TTF
   внутри `dpg.font_registry()` — на шаге `setup_dearpygui()` собирается атлас
   глифов, и позже добавить символы уже нельзя;
2. вызываем `dpg.bind_font()` внутри того же блока, пока шрифт заведомо жив;
3. на Dear PyGui **1.x** дополнительно просим диапазоны
   `mvFontRangeHint_Default` и `mvFontRangeHint_Cyrillic`. Начиная с **2.0** эти
   вызовы — no-op: диапазоны определяются автоматически по содержимому шрифта.
   Мы их всё равно делаем ради совместимости с 1.x, но глушим предупреждения.

По умолчанию берётся **JetBrains Mono Nerd Font** — в нём есть и полная
кириллица, и иконочные глифы, поэтому отдельный иконочный шрифт не нужен
(иконки в `sysdevcleaner/gui/icons.py`). Если его нет, подхватывается обычный
JetBrains Mono, затем Segoe UI, Calibri, Tahoma, Arial — тогда интерфейс
останется читаемым, но без иконок.

Можно положить любой свой TTF в папку `fonts/` рядом с приложением — она имеет
приоритет над системными шрифтами.

Важная деталь: берутся только иконки из BMP (U+E000–U+F8FF). Набор Material
Design Icons в Nerd Font лежит выше U+FFFF, а Dear ImGui собран с 16-битным
`ImWchar` и такие символы не отрисует.

## Что ищется

**Система Windows** — временные файлы пользователя и системы, кеш Windows Update,
оптимизация доставки, `Windows.old`, Prefetch, дампы аварийных завершений и
`MEMORY.DMP`, отчёты WER, кеш эскизов и значков, кеш шрифтов, INetCache, кеш
шейдеров DirectX, Корзина, `$PatchCache$`, логи установки Panther, история
проверок Defender, LiveKernelReports.

**Браузеры** — Chrome, Edge, Brave, Opera, Opera GX, Vivaldi, Yandex, Chromium,
Firefox, Tor. Для каждого профиля отдельно: HTTP-кеш, Code Cache, GPUCache,
кеши шейдеров и WebGPU, Service Worker, Media Cache, IndexedDB, отчёты Crashpad.

**Кеши разработки** — npm, Yarn, pnpm, Bun, Deno, node-gyp, Electron,
Playwright/Puppeteer, Cypress, pip, Poetry, uv, Conda, PyInstaller, NuGet,
Maven, Gradle, Cargo, Go (модули и сборка), JDK, Android SDK и образы
эмулятора, Flutter/Dart, Composer, RubyGems, Terraform, Helm, vcpkg/Conan,
ccache/sccache, Unity, Unreal DDC, Docker Desktop.

**IDE** — VS Code (и Insiders/VSCodium), Cursor, Windsurf, JetBrains (индексы,
кеши, данные старых версий), Visual Studio и его установщик, Xamarin, Eclipse,
NetBeans.

**Артефакты внутри проектов** — рекурсивный обход ваших папок с кодом:
`node_modules`, `.next`, `.nuxt`, `.turbo`, `.parcel-cache`, `.angular`,
`.svelte-kit`, `.astro`, `coverage`, `__pycache__`, `.pytest_cache`,
`.mypy_cache`, `.ruff_cache`, `.tox`, `.venv`, `target`, `bin`/`obj`, `.vs`,
`build`, `cmake-build-*`, `.gradle`, `.dart_tool`, `vendor`, `Pods`,
`Library` (Unity), `Intermediate`/`DerivedDataCache` (Unreal), `.terraform`,
`dist`, `out`.

**Приложения** — Discord, Slack, Teams, Telegram, Spotify, Steam, Epic,
Battle.net, EA/Origin, Adobe Media Cache, OBS, Zoom, Office, OneDrive, кеши
шейдеров NVIDIA и AMD, плюс автоматический поиск кешей любых Electron-программ.

**Пакетные менеджеры** — Chocolatey, Scoop, winget, Package Cache.

**Дополнительно (включается в настройках)** — крупные файлы от заданного
размера, дубликаты файлов (сверка по содержимому), список установленных
программ с реальным размером на диске и давностью использования.

## Как это устроено

Каждая находка получает уровень риска, и это определяет, что приложение
отмечает само:

| Риск | Что это значит | Отмечается автоматически |
|---|---|---|
| **Безопасно** | мусор, который система пересоздаёт сама | да |
| **Низкий риск** | кеш; после удаления первый запуск будет медленнее | нет |
| **Средний риск** | потеря состояния, нужна пересборка или повторная закачка | нет |
| **Высокий риск** | можно сломать проект — только осознанное решение | нет |

Защита от ошибок:

- корни дисков, `Windows`, `Program Files`, профиль пользователя и папки
  «Документы», «Рабочий стол», «Загрузки» и т.п. нельзя удалить — проверка
  срабатывает и при выборе, и повторно перед самим удалением;
- для каталогов вроде `%TEMP%` удаляется **содержимое**, а не сам каталог;
- по умолчанию всё уходит **в Корзину** — можно вернуть;
- есть **пробный запуск**: показывает точный план, ничего не трогая;
- приложение предупреждает, если браузер или редактор сейчас запущен, — занятые
  файлы всё равно не удалятся;
- каждая очистка пишется в журнал
  `%LOCALAPPDATA%\SysDevCleaner\journal\clean-*.json` — видно, что и когда было
  удалено.

## Вкладки

- **Обзор** — заполненность дисков, сводка по категориям и рекомендации:
  что чистить в первую очередь, где заброшенные проекты, какие программы весят
  много и давно не запускались.
- **Очистка** — находки, сгруппированные по категориям в раскрывающиеся
  разделы. У каждой строки свой флажок, у раздела — флажок «отметить всю
  категорию». Клик по названию показывает подробности внизу, наведение —
  полный путь во всплывающей подсказке. Есть фильтр по названию и пути.
- **Программы** — установленное ПО с сортировкой по размеру, простою, имени или
  издателю и поиском по названию. Колонка «простой» показывает, сколько дней не
  менялись файлы программы. Клик по строке открывает папку установки, кнопка —
  запускает штатный деинсталлятор.
- **Настройки** — какие категории сканировать, где искать проекты, включение
  поиска крупных файлов и дубликатов.
- **Журнал** — история очисток и ошибки доступа последнего сканирования.

## Консольный режим

```bash
python -m sysdevcleaner --categories devcache,projects --top 40
```

```bash
python -m sysdevcleaner --root "D:\code" --big-files 500 --duplicates 50 --report отчёт.txt
```

```bash
python -m sysdevcleaner --clean safe --dry-run
```

Ключи:

- `--categories` — `windows,browsers,devcache,projects,apps,logs,pkg` или `all`
- `--drive БУКВА` — сканировать только этот диск (можно повторять)
- `--root ПАПКА` — где искать проекты (можно повторять)
- `--big-files МБ`, `--duplicates МБ` — включить дополнительный анализ
- `--no-programs` — не собирать список установленных программ
- `--report ФАЙЛ` — сохранить подробный отчёт
- `--clean УРОВЕНЬ` — удалить находки с риском не выше `safe`/`low`/`medium`/`high`
- `--dry-run` — показать план, ничего не удаляя
- `--permanent` — удалять мимо Корзины
- `--yes` — без подтверждения

## Структура

```
build_exe.py      сборка в exe через PyInstaller
make_icon.py      генерация значка
sysdevcleaner/
  core/
    model.py      структуры данных, уровни риска и категории
    rules.py      каталог правил: 228 правил путей (496 шаблонов) + 43 правила артефактов
    util.py       размеры, защита путей, удаление в Корзину, список процессов
    scanner.py    раскрытие правил в находки, параллельный подсчёт размеров
    devscan.py    рекурсивный поиск артефактов внутри проектов
    heavy.py      крупные файлы и дубликаты (хеш по началу/середине/концу + полная сверка)
    programs.py   инвентаризация установленного ПО через реестр
    advisor.py    рекомендации и текстовый отчёт
    cleaner.py    удаление с журналом и повторной проверкой безопасности
  winui.py        заголовок окна через Unicode-API и повышение прав
  gui/
    app.py        интерфейс на Dear PyGui
    fonts.py      подключение TTF и кириллица (см. раздел «Шрифт и кириллица»)
    icons.py      иконки Nerd Font
    dpg_theme.py  тёмная и светлая темы для Dear PyGui
    app_tk.py     запасной интерфейс на tkinter
    theme_tk.py   темы для запасного интерфейса
  cli.py          консольный режим
```

## Что приложение не делает

Не трогает реестр, не «оптимизирует» систему, не отключает службы и не удаляет
ничего без вашей отметки. Список установленных программ показывается для
анализа — удаление запускает штатный деинсталлятор, а не вычищает файлы само.