fchek 1.0.0

package/skills/deps.md

@@ -0,0 +1,143 @@
+# skill: fchek deps — dependency граф и dead code
+
+## Что делает
+
+Показывает что импортируется/зависит от чего, что не используется совсем,
+и какие пакеты лишние. Невозможно держать в голове по всему проекту — пусть делает инструмент.
+
+## Поддерживаемые языки
+
+| Язык | Инструменты | Что находит |
+|---|---|---|
+| Python | ruff (F401) + vulture + pydeps | unused imports, dead functions, граф |
+| Rust | cargo-machete + cargo-udeps | unused Cargo.toml зависимости |
+| JS/TS | madge + depcheck | circular deps, unused npm packages |
+| Go | go mod + deadcode | unused modules, dead functions |
+
+## Синтаксис
+
+```bash
+fchek deps <file_or_dir> [--graph] [--unused-only]
+```
+
+- `--graph` — включить полный граф зависимостей (может быть большим)
+- `--unused-only` — показать только неиспользуемое
+
+## Вывод JSON
+
+### Python
+```json
+{
+  "status": "ok",
+  "command": "deps",
+  "data": {
+    "target": "src/",
+    "lang": "python",
+    "tools_used": ["ruff", "vulture"],
+    "unused_imports": [
+      { "file": "src/auth.py", "line": 3, "symbol": "'os' imported but unused", "code": "F401" }
+    ],
+    "dead_code": [
+      { "file": "src/utils.py", "line": 42, "issue": "unused function 'helper' (80% confidence)" }
+    ],
+    "graph": null
+  }
+}
+```
+
+### Rust
+```json
+{
+  "data": {
+    "lang": "rust",
+    "tools_used": ["cargo-machete"],
+    "unused_deps": ["serde_json", "regex"],
+    "machete_raw": "The following packages are not used: serde_json, regex"
+  }
+}
+```
+
+### JS/TS
+```json
+{
+  "data": {
+    "lang": "javascript",
+    "tools_used": ["madge", "depcheck"],
+    "circular_deps": [["src/a.ts", "src/b.ts", "src/a.ts"]],
+    "circular_count": 1,
+    "unused_packages": ["lodash", "moment"],
+    "unused_dev_packages": ["jest-circus"],
+    "missing_packages": ["react-dom"]
+  }
+}
+```
+
+## Как AI должен использовать это
+
+### Сценарий: "Почистить проект перед релизом"
+
+```bash
+# 1. Найти всё лишнее
+fchek deps .
+
+# 2. Python: unused_imports → удали импорты или fchek lint для автофикса
+fchek lint src/ --strict
+
+# 3. Rust: unused_deps → удали из Cargo.toml
+# "unused_deps": ["regex"] → убери regex из [dependencies]
+
+# 4. JS: unused_packages → удали из package.json
+# npm uninstall lodash moment
+
+# 5. circular_deps → это архитектурный баг → исправь вручную
+```
+
+### Сценарий: "Найти мёртвый код"
+
+```bash
+fchek deps src/ --unused-only
+# → dead_code[] содержит функции/классы с низкой уверенностью использования
+# → для каждого: fchek goto <file:line> → проверь references
+fchek goto src/utils.py:42
+# Если ref_count = 0 → безопасно удалить
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ unused_imports не пустой:
+  → запусти fchek lint --fix для автоматического удаления
+
+ЕСЛИ dead_code содержит items с confidence > 80%:
+  → высокая уверенность → проверь через goto → удали если ref_count = 0
+
+ЕСЛИ circular_deps не пустой:
+  → это архитектурная проблема
+  → нельзя фиксировать автоматически
+  → нужен рефакторинг структуры модулей
+
+ЕСЛИ unused_packages (JS):
+  → npm uninstall <package> для production deps
+  → npm uninstall --save-dev <package> для devDeps
+
+ЕСЛИ missing_packages (JS) не пустой:
+  → код использует пакеты которых нет в package.json
+  → npm install <package>
+```
+
+### Ключевые поля для AI
+
+| Поле | Что означает |
+|---|---|
+| `unused_imports[]` | Импорты которые объявлены но не используются |
+| `dead_code[]` | Функции/классы которые (вероятно) нигде не вызываются |
+| `circular_deps[]` | Циклические зависимости — A→B→A |
+| `unused_deps[]` | Пакеты в зависимостях которые не используются в коде |
+| `missing_packages[]` | Пакеты используются в коде но не объявлены |
+
+## Точность
+
+- `vulture` может давать false positives (помечает код используемый через reflection/eval)
+- Для Rust `cargo-machete` быстрее и не требует nightly; `cargo-udeps` точнее но нужен nightly
+- `madge` анализирует статические import/require — динамические import() не всегда находит
+- `depcheck` может не видеть зависимости используемые через конфиги (babel, jest и т.д.)

package/skills/docker.md

@@ -0,0 +1,61 @@
+# skill: fchek docker — Работа с контейнерами
+
+## Что делает
+
+Предоставляет интерфейс к Docker CLI. Позволяет просматривать запущенные контейнеры и получать логи для отладки приложений.
+
+## Синтаксис
+
+```bash
+# Показать запущенные контейнеры (добавь --all для всех)
+fchek docker list [--all]
+
+# Получить логи контейнера (по умолчанию последние 50 строк)
+fchek docker logs <container_name_or_id> [--tail=<num>]
+```
+
+## Вывод JSON
+
+### docker list
+```json
+{
+  "status": "ok",
+  "command": "docker",
+  "data": {
+    "containers": [
+      {
+        "ID": "a1b2c3d4e5f6",
+        "Names": "web-app",
+        "Image": "node:22",
+        "Status": "Up 2 hours",
+        "Ports": "0.0.0.0:8080->8080/tcp"
+      }
+    ]
+  }
+}
+```
+
+### docker logs
+```json
+{
+  "status": "ok",
+  "command": "docker",
+  "data": {
+    "container": "web-app",
+    "logs": "Server running at http://localhost:8080\n"
+  }
+}
+```
+
+## КАК AI ДОЛЖЕН ИСПОЛЬЗОВАТЬ ЭТО
+
+### Сценарии
+
+1. **Контейнер упал**: проверь список всех контейнеров, чтобы увидеть статус:
+   ```bash
+   fchek docker list --all
+   ```
+2. **Отладка ошибок**: получи логи контейнера для локализации проблемы:
+   ```bash
+   fchek docker logs web-app --tail=100
+   ```

package/skills/dom.md

@@ -0,0 +1,56 @@
+# skill: fchek dom — Web автоматизация и парсинг HTML
+
+## Что делает
+
+Загружает веб-страницу по URL или открывает локальный HTML-файл и извлекает элементы с помощью простых селекторов (теги, классы, ID). Позволяет получать текстовое содержимое, внутренний HTML-код или значения атрибутов.
+
+## Синтаксис
+
+```bash
+# Получить все ссылки с их HTML и текстом
+fchek dom https://example.com a
+
+# Получить значение атрибута href для всех ссылок
+fchek dom https://example.com a --attr=href
+
+# Найти элемент с ID header в локальном файле
+fchek dom index.html #header
+```
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "dom",
+  "data": {
+    "source": "index.html",
+    "selector": "#header",
+    "count": 1,
+    "matches": [
+      {
+        "tag": "div",
+        "attributes": {
+          "id": "header",
+          "class": "banner"
+        },
+        "text": "Welcome to my website",
+        "html": "<div id=\"header\" class=\"banner\">Welcome to my website</div>"
+      }
+    ]
+  }
+}
+```
+
+## КАК AI ДОЛЖЕН ИСПОЛЬЗОВАТЬ ЭТО
+
+### Сценарии
+
+1. **Проверка UI**: после запуска веб-сервера проверь структуру страницы:
+   ```bash
+   fchek dom http://localhost:3000 h1
+   ```
+2. **Извлечение данных**: собери все ссылки или пути изображений из файла разметки:
+   ```bash
+   fchek dom dist/index.html img --attr=src
+   ```

package/skills/fuzz.md

@@ -0,0 +1,167 @@
+# skill: fchek fuzz — fuzzing на минималках
+
+## Что делает
+
+Запускает fuzzer — инструмент который генерирует случайные/мутированные входы
+и ищет краши, зависания, неожиданное поведение.
+Находит edge cases которые ты никогда не напишешь вручную.
+
+## Поддерживаемые языки
+
+| Язык | Инструмент | Установка |
+|---|---|---|
+| C/C++ | AFL++ | `apt install afl++` (Linux/macOS) |
+| Rust | cargo-fuzz (libFuzzer) | `cargo install cargo-fuzz` + nightly |
+| Python | Atheris (Google libFuzzer) | `pip install atheris` (Linux/macOS) |
+| Go | go test -fuzz | встроен в Go 1.18+ |
+
+## Синтаксис
+
+```bash
+fchek fuzz <file> [--duration=60] [--target=<name>] [--corpus=<dir>]
+```
+
+- `--duration=60` — сколько секунд фаззить (default: 60)
+- `--target=<name>` — имя fuzz-цели (Rust: имя файла в fuzz/fuzz_targets/, Go: имя Fuzz* функции)
+- `--corpus=<dir>` — директория с seed-входами (начальные примеры для мутации)
+
+**Начни с `--duration=30` чтобы проверить что setup работает.**
+
+## Вывод JSON
+
+### Чисто (no crash)
+```json
+{
+  "status": "ok",
+  "command": "fuzz",
+  "data": {
+    "file": "/project/parse_input.c",
+    "lang": "c",
+    "tool": "AFL++",
+    "duration_s": 60,
+    "crashes_found": 0,
+    "hangs_found": 0,
+    "queue_entries": 47,
+    "verdict": "clean",
+    "findings_dir": "/tmp/fchek_findings"
+  }
+}
+```
+
+### Краш найден
+```json
+{
+  "data": {
+    "crashes_found": 3,
+    "verdict": "crashes_found",
+    "findings_dir": "/tmp/fchek_findings/default/crashes"
+  }
+}
+```
+
+### Rust
+```json
+{
+  "data": {
+    "lang": "rust",
+    "tool": "cargo-fuzz (libFuzzer)",
+    "fuzz_target": "fuzz_parse",
+    "crashed": true,
+    "crash_reason": "heap-use-after-free on address 0x...",
+    "execs_per_sec": 12400,
+    "coverage_points": 342,
+    "verdict": "crash_found"
+  }
+}
+```
+
+## Как AI должен использовать это
+
+### Сценарий: "Проверить парсер на краши"
+
+```bash
+# 1. Запустить fuzzer на 60 секунд
+fchek fuzz parse_input.c --duration=60
+
+# 2. Если crashes_found > 0:
+ls /tmp/fchek_findings/default/crashes/
+# → каждый файл в этой папке = входные данные которые крашат программу
+# → запусти вручную чтобы воспроизвести:
+./parse_input < /tmp/fchek_findings/default/crashes/id:000000,...
+
+# 3. Если verdict = "clean" — либо багов нет, либо нужно больше времени
+fchek fuzz parse_input.c --duration=300  # 5 минут
+```
+
+### Сценарий: "Rust fuzz target"
+
+```bash
+# Сначала создай fuzz target если нет:
+# cargo fuzz add fuzz_parse
+# (отредактируй fuzz/fuzz_targets/fuzz_parse.rs)
+
+fchek fuzz . --target=fuzz_parse --duration=60
+```
+
+### Сценарий: "Python — auto harness"
+
+```bash
+# Если в файле нет atheris кода — fchek создаёт harness автоматически
+# Ищет функции parse(), process() как точки входа
+fchek fuzz my_parser.py --duration=30
+
+# Если auto_harness: true в выводе — harness сгенерирован автоматически
+# Для точного контроля — напиши fuzz target вручную с FuzzedDataProvider
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ verdict = "crashes_found" или crashed: true:
+  → КРИТИЧНО — найден баг
+  → смотри crash_reason (AddressSanitizer / heap-use-after-free / etc.)
+  → находки лежат в findings_dir/default/crashes/
+  → воспроизведи минимальный краш-кейс
+  → исправь → запусти fuzz снова для проверки
+
+ЕСЛИ verdict = "hangs_found":
+  → найдены входы вызывающие зависание
+  → возможен бесконечный цикл при определённых условиях
+  → смотри findings_dir/default/hangs/
+
+ЕСЛИ verdict = "clean":
+  → за этот период багов не найдено
+  → не значит что их нет — fuzzing статистический
+  → увеличь --duration для большей уверенности
+
+ЕСЛИ queue_entries высокий (AFL++):
+  → fuzzer нашёл много интересных путей выполнения
+  → хороший знак — coverage растёт
+
+ЕСЛИ execs_per_sec очень низкий:
+  → код работает медленно → сначала fchek profile
+  → медленный код = медленный fuzzing = меньше охвата
+```
+
+### Что делать с найденными крашами
+
+1. Файлы в `findings_dir/default/crashes/` — это минимальные входы вызывающие краш
+2. Воспроизведи каждый вручную и убедись что воспроизводится
+3. Добавь как regression test
+4. Исправь баг
+5. Запусти `fchek fuzz` снова — убедись что crash не воспроизводится
+
+## Платформенные ограничения
+
+| Инструмент | Linux | macOS | Windows |
+|---|---|---|---|
+| AFL++ | ✓ | ✓ (brew) | ✗ WSL |
+| cargo-fuzz | ✓ | ✓ | частично |
+| Atheris | ✓ | ✓ (clang) | ✗ |
+| go test -fuzz | ✓ | ✓ | ✓ |
+
+## Требования к Rust fuzzing
+
+- `cargo install cargo-fuzz`
+- `rustup default nightly` (cargo-fuzz требует nightly)
+- Наличие fuzz targets в `fuzz/fuzz_targets/*.rs`

package/skills/goto.md

@@ -0,0 +1,111 @@
+# skill: fchek goto — LSP навигация по коду
+
+## Что делает
+
+Показывает определение символа на заданной строке и все места где этот символ используется.
+Работает в batch-режиме (без открытия редактора) — через LSP-протокол напрямую.
+
+## Поддерживаемые языки
+
+| Расширение | LSP сервер | Установка |
+|---|---|---|
+| `.rs` | rust-analyzer | `rustup component add rust-analyzer` |
+| `.cpp` / `.cc` / `.c` | clangd | `apt install clangd` |
+| `.py` | pyright | `pip install pyright` |
+| `.ts` / `.js` | typescript-language-server | `npm install -g typescript-language-server typescript` |
+
+## Синтаксис
+
+```bash
+fchek goto <file:line>
+fchek goto <file:line:col>
+```
+
+- `line` — номер строки (начиная с 1)
+- `col` — номер символа в строке (опционально, по умолчанию 0)
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "goto",
+  "data": {
+    "query": {
+      "file": "/path/to/main.rs",
+      "line": 42,
+      "col": 0
+    },
+    "lsp": {
+      "server": "rust-analyzer",
+      "language": "rust",
+      "root": "/path/to/project",
+      "timeout_ms": 15000
+    },
+    "definition": {
+      "file": "/path/to/utils.rs",
+      "line": 12,
+      "col": 4
+    },
+    "references": [
+      { "file": "/path/to/main.rs",  "line": 42, "col": 10 },
+      { "file": "/path/to/tests.rs", "line": 8,  "col": 3  }
+    ],
+    "ref_count": 2
+  }
+}
+```
+
+`definition: null` означает что LSP не нашёл определение (возможно, символ — встроенный).
+
+## Как AI должен использовать это
+
+### Сценарий: "Хочу понять что делает функция на строке X"
+
+```bash
+# 1. Перейди к определению
+fchek goto main.rs:42
+
+# 2. Прочитай файл определения: data.definition.file, начиная с data.definition.line
+# 3. Посмотри все места использования: data.references
+```
+
+### Сценарий: "Хочу найти все места где используется эта функция перед рефакторингом"
+
+```bash
+fchek goto utils.py:15
+# → data.references содержит все места вызова
+# Это точнее чем grep — LSP понимает скоупы
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ definition = null:
+  → символ встроенный, или LSP не смог разрезолвить
+  → попробуй col= точнее (укажи col начала идентификатора)
+
+ЕСЛИ ref_count = 0:
+  → функция нигде не используется (возможно мёртвый код)
+
+ЕСЛИ LSP server not found:
+  → запусти fchek doctor → посмотри что не установлено
+```
+
+## Автоопределение корня проекта
+
+`fchek goto` ищет корень проекта вверх по директориям:
+`Cargo.toml` / `package.json` / `CMakeLists.txt` / `.git` / `pyproject.toml` / `go.mod`
+
+Это важно для LSP — он должен знать root чтобы найти все файлы проекта.
+
+## Платформенные ограничения
+
+- Работает на Linux, macOS, Windows (если LSP-сервер установлен)
+- На Windows пути содержат `\` — fchek автоматически конвертирует в `file://` URI
+- Первый запуск rust-analyzer может быть медленным (индексация проекта)
+
+## Таймаут
+
+По умолчанию 15 секунд. Если LSP не отвечает — возвращает `status: "error"` с описанием.
+rust-analyzer на больших проектах может быть медленным при первом запуске.

package/skills/lint.md

@@ -0,0 +1,123 @@
+# skill: fchek lint — линтер + автофикс + diff
+
+## Что делает
+
+Запускает лучший линтер для языка, применяет safe auto-fixes,
+и показывает точный diff что именно изменилось.
+Один вызов вместо "запусти линтер, посмотри вывод, примени fix, проверь что изменилось".
+
+## Поддерживаемые языки
+
+| Язык | Инструменты | Установка |
+|---|---|---|
+| Python | ruff check + ruff format | `pip install ruff` |
+| Rust | cargo clippy --fix | встроен в cargo |
+| JS/TS | eslint --fix | `npm install -g eslint` |
+| C/C++ | clang-tidy + clang-format | `apt install clang-tidy clang-format` |
+| Go | gofmt -w + go vet | встроен в Go |
+
+## Синтаксис
+
+```bash
+fchek lint <file_or_dir> [--no-fix] [--strict]
+```
+
+- `--no-fix` — только репорт, не менять файлы
+- `--strict` — включить предупреждения (не только ошибки)
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "lint",
+  "data": {
+    "target": "src/auth.py",
+    "lang": "python",
+    "tool": "ruff",
+    "fix_applied": true,
+    "issues_before": 12,
+    "issues_after": 3,
+    "fixed_count": 9,
+    "remaining_issues": [
+      { "file": "src/auth.py", "line": 42, "col": 1, "code": "E501", "message": "line too long (95 > 88)" }
+    ],
+    "diff": [
+      {
+        "file": "src/auth.py",
+        "from_line": 15,
+        "changes": [
+          { "op": "-", "line": 15, "text": "import os,sys" },
+          { "op": "+", "line": 15, "text": "import os" },
+          { "op": "+", "line": 16, "text": "import sys" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Как AI должен использовать это
+
+### Сценарий: "Починить стиль перед коммитом"
+
+```bash
+# 1. Применить все safe-fixes
+fchek lint src/
+
+# 2. Смотри remaining_issues — то что нельзя починить автоматически
+# 3. Смотри diff — что именно изменилось
+
+# Если хочешь только проверить без изменений:
+fchek lint src/ --no-fix
+```
+
+### Сценарий: "Code review — найти все проблемы"
+
+```bash
+fchek lint . --strict --no-fix
+# → remaining_issues содержит всё включая предупреждения
+# → fix_applied: false → файлы не тронуты
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ remaining_issues пустой после fix:
+  → код чист ✓
+
+ЕСЛИ remaining_issues не пустой:
+  → issues которые нельзя починить автоматически
+  → смотри code (E501, W0611 и т.д.)
+  → реши сам: исправить вручную или добавить исключение
+
+ЕСЛИ diff содержит изменения в логике (не только форматирование):
+  → проверь через fchek bench что поведение не изменилось
+
+ЕСЛИ fix_applied: true, но issues_before === issues_after:
+  → все найденные проблемы — только ручные (lint не умеет их фиксить)
+```
+
+### Ключевые поля для AI
+
+| Поле | Что означает |
+|---|---|
+| `fixed_count` | Сколько проблем починено автоматически |
+| `remaining_issues[]` | Что осталось — нужно исправить вручную |
+| `diff[].changes` | op: `-` = удалено, `+` = добавлено, ` ` = контекст |
+| `issue_count` | Общее число оставшихся проблем |
+
+## Diff формат
+
+```json
+{ "op": "-", "line": 15, "text": "import os,sys" }   ← удалено
+{ "op": "+", "line": 15, "text": "import os" }        ← добавлено
+{ "op": " ", "line": 16, "text": "import sys" }       ← контекст (не изменилось)
+```
+
+## Платформенные замечания
+
+- `ruff` — самый быстрый Python линтер, заменяет flake8/pylint/isort за один вызов
+- `cargo clippy --fix` требует чистого git состояния, или передай `--allow-dirty` (уже передаётся внутри)
+- `clang-format` применяет форматирование по стилю проекта (`.clang-format` файл если есть)
+- `eslint` требует конфиг `.eslintrc` в проекте — без него может дать мало находок