doctordanila/scancore

Console tool to scan project structure and dump file contents, respecting .scancoreignore

v1.0.3 2026-03-15 00:59 UTC

Requires

• php: >=7.4

MIT

• Kuznetsov Danila
• Script Agency

README

Консольный инструмент для сканирования файловой структуры PHP-проекта и генерации дампа содержимого файлов с учётом правил игнорирования (.scancoreignore). Полезен для передачи контекста проекта в LLM, анализа кода, ревью или документирования.

Возможности

• init - команда для явного создания или перезаписи файла .scancoreignore. При первом запуске любой команды файл также создаётся автоматически (если отсутствует).
• tree - отображение структуры проекта в виде дерева (аналог команды tree в Linux).
• dump - создание текстового файла со всеми неигнорируемыми файлами и их содержимым.
• stats - сбор расширенной статистики по проекту:
  • Общее количество файлов и строк кода (без учёта пустых строк и комментариев).
  • Среднее количество строк на файл.
  • Распределение по типам файлов (PHP, JS, CSS, конфиги и т.д.).
  • Самые большие файлы (топ-10 по размеру).
  • Файлы с наибольшим количеством зависимостей (входящих и исходящих) - анализ use, extends, implements для PHP.
  • Активность по дням (количество изменённых файлов за последние даты).
  • Генерация HTML-отчёта с интерактивным графом зависимостей (на русском языке).
  • Генерация JSON-файла с полной информацией для дальнейшего анализа LLM.
• Поддержка .scancoreignore с синтаксисом, близким к .gitignore (кроме негативных шаблонов !).
• Фильтрация по подпапке для всех команд.
• Кроссплатформенность (Windows, Linux, macOS).

Требования

• PHP 7.4 или выше.

Установка

Установите пакет через Composer (рекомендуется в require-dev):

composer require doctordanila/scancore --dev

После установки исполняемый файл будет доступен как vendor/bin/scancore (в Windows - vendor\bin\scancore).

Настройка игнорирования

В корне проекта создайте файл .scancoreignore и перечислите пути/шаблоны, которые нужно исключить. Правила обрабатываются аналогично .gitignore.

Не волнуйтесь если не знаете, что добавлять в файл игнорирования. При первом запуске любой команды (tree, dump, stats) файл .scancoreignore создаётся автоматически, если его нет. Сначала предпринимается попытка скопировать содержимое .gitignore из корня проекта. Если .gitignore отсутствует, генерируется базовый шаблон со стандартными исключениями (системные папки, зависимости, логи, конфигурации, git). Для явного создания или принудительной перезаписи используйте команду init (см. ниже).

Пример:

# Системные папки
.idea
.vscode
.DS_Store

# Зависимости
/vendor
/node_modules

# Логи и временные файлы
*.log
/runtime

# Конфигурации окружения
.env
/phpunit.xml

# Git
.git/
.github/

Пояснения:

/vendor - игнорируется только папка vendor в корне.

.idea - игнорируется на любом уровне.

tests/_output/* - игнорируются файлы внутри tests/_output/ (но только в корне).

**/tests/_output/ - папка _output на любом уровне (слеш в конце означает "только директория").

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

Команда tree

Вывод полной структуры проекта:

vendor/bin/scancore tree

Вывод структуры только указанной подпапки (например, modules):

vendor/bin/scancore tree modules/tasks

Пример вывода:

modules/tasks/
├─ Module.php
├─ config/
│   └─ di.php
├─ domain/
│   ├─ entity/
│   │   └─ Task.php
│   └─ valueObject/
│       └─ TaskId.php
└─ presentation/
    └─ controller/
        └─ TaskController.php

Команда dump

Создание файла scancore_output.txt со всеми неигнорируемыми файлами и их содержимым:

vendor/bin/scancore dump

Указать имя выходного файла:

vendor/bin/scancore dump my_project_scan.txt

Ограничить дамп только файлами из определённой подпапки (например, modules/tasks):

vendor/bin/scancore dump . modules/tasks

Пояснения:

Команда нужна для того, чтобы вывести в единый файл всё содержимое файлов вашего проекта или отдельной его папки.

. во втором аргументе использует вывод в файл по умолчанию, используется, для того, чтобы не менять файл вывода, но указать определённую директорию сканирования

Содержимое результирующего файла:

Файл: modules/tasks/Module.php
<?php
// содержимое файла

Файл: modules/tasks/domain/entity/Task.php
<?php
// содержимое файла
...

Команда stats

Сбор статистики проекта и генерация двух отчётов: HTML (с графами и таблицами) и JSON (для LLM).

Базовый запуск (в текущей папке):

vendor/bin/scancore stats

Будут созданы файлы stats.html и stats_llm.txt.

Указать базовое имя файлов (например, myproject):

vendor/bin/scancore stats myproject

Создадутся myproject.html и myproject_llm.txt.

Ограничить анализ только подпапкой (например, src/):

vendor/bin/scancore stats . src

Здесь . означает использовать имя по умолчанию (stats), а src - подпапка для сканирования.

Что содержится в HTML-отчёте?

• Общая информация: количество файлов, строк кода, среднее количество строк на файл.
• Распределение по типам файлов (расширениям).
• Таблица самых больших файлов (топ-10).
• Таблица активности по дням (количество изменённых файлов за последние даты).
• Две таблицы зависимостей:
  • Файлы, от которых чаще всего зависят другие (наибольшее количество входящих зависимостей).
  • Файлы с наибольшим числом зависимостей (которые сами больше всего используют другие классы/интерфейсы).
• Интерактивный граф зависимостей для PHP-файлов (направленные рёбра: от файла к тому, от которого он зависит).

Что содержится в JSON-файле (*_llm.txt)?

Все данные в машиночитаемом формате, включая полный граф зависимостей, списки файлов с зависимостями и метрики. Удобно для передачи в LLM для дальнейшего анализа.

Команда init

Явное создание файла .scancoreignore в корне проекта.

vendor/bin/scancore init

Если файл уже существует, команда сообщит об этом и ничего не изменит. Для принудительной перезаписи используйте флаг --force (сокращённо -f):

vendor/bin/scancore init --force
# или
vendor/bin/scancore init -f

При создании файла используется тот же алгоритм, что и при автоматической генерации:

• Если в корне есть .gitignore, его содержимое копируется в .scancoreignore.
• Иначе создаётся файл с базовым набором правил (см. пример ниже).

Обновление включает:

• Добавлен пункт init в раздел "Возможности".
• В разделе "Использование" добавлен подраздел "Команда init" с описанием синтаксиса.
• Обновлён раздел Настройка игнорирования новым параграфом.