Я много работаю с проектами на веб-стеке и параллельно активно использую нейросети.
Со временем стало ясно: чтобы ИИ помогал не «вообще по PHP», а по конкретному проекту, ему нужен нормальный контекст. Не один файл, не случайный фрагмент, а полноценный срез кода.

В какой-то момент меня это достало настолько, что я сел и сделал отдельный инструмент — scan2json.
Это маленький PHP-репозиторий, который:

  • в одну сторону: сканирует проект и превращает его в JSON/JSONL;

  • в другую: по этому JSONL умеет собрать обратно структуру папок и файлов.

Репозиторий лежит на GitHub: https://github.com/simai/scan2json. В статье расскажу, зачем я его делал, как он устроен и как им можно пользоваться у себя.

Зачем вообще городить JSON вокруг кода

Если вы хоть раз пытались обсуждать реальный проект с ИИ, сценарий примерно такой.

  1. Открываем ChatGPT или другой LLM.

  2. Копируем в чат один файл.

  3. Получаем ответ.

  4. Выясняется, что нужен ещё конфиг, ещё шаблон, ещё один класс.

  5. Начинается бесконечный копипаст и объяснения «где что лежит».

Проблема в этом месте не в модели.
Проблема в том, что мы даём ей мозаику из обрывков, а не картину проекта.

Я хотел другого:

  • один раз собрать целостный снимок проекта;

  • чтобы в этом снимке были:

    • пути до файлов,

    • структура папок,

    • сам код;

  • и дальше уже разговаривать с ИИ, опираясь на этот снимок, а не таская куски руками.

Плагины в IDE помогают, но у них есть ограничения:

  • они живут внутри конкретного редактора;

  • не всегда удобно делиться этим контекстом с кем-то ещё (менеджером, аналитиком, подрядчиком);

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

Мне хотелось иметь отдельный артефакт — файл или набор файлов, который:

  • можно положить в репозиторий,

  • отправить ассистенту,

  • отдать другому разработчику,

  • скормить своему RAG-сервису.

Так родилась идея scan2json.

Что такое scan2json

Вся логика собрана в два файла:

  • scan.php — сканирует проект в JSON/JSONL;

  • restore.php — по JSONL разворачивает проект обратно в отдельную папку.

Оба скрипта работают через браузер и живут там же, где живёт ваш проект (под DOCUMENT_ROOT).
Bitrix обязателен не всегда: если он есть, можно использовать проверку на админа; если нет — используется обычный пароль.

Идеология простая:

  • scan.php — я запускаю, чтобы «сфотографировать» проект:

    • выбираю, какую папку сканировать;

    • при необходимости выкидываю лишнее;

    • получаю JSONL/JSON + архивы;

  • restore.php — я запускаю, когда:

    • хочу из этого JSONL собрать отдельную «лёгкую» копию проекта;

    • или передать кому-то набор JSONL + restore и дать ему возможность развернуть структуру у себя.

Дальше этим JSON можно кормить ассистентов, использовать в своих инструментах или сохранять как снапшот релиза.

Основные части инструмента

Я пойду от пользовательского сценария: что видит человек на экране и какие сущности за этим стоят.

Выбор корневой папки

Первое, что нужно сделать в scan.php, — выбрать, откуда сканировать.

Я сделал два варианта.

1. Ввести путь руками

Простой режим: у меня есть поле scan_folder.
Я пишу туда, например:

  • / — весь сайт целиком;

  • /local — кастомный код в Bitrix;

  • /bitrix/modules/fileman;

  • /project/app — если это не Bitrix, а условный PHP-проект.

Этот способ удобен, когда я уже знаю, где лежит нужный модуль.

2. Выбрать из списка

Если путь не помню или лень вспоминать, включаю режим «Select from list».
Там появляется мини-навигация:

  • строка «Current folder: …»;

  • кнопка «Go up one level»;

  • выпадающий список подпапок текущей директории.

Я просто кликаю по подпапкам и «проваливаюсь» туда, пока не дойду до нужного уровня.
Текущее положение хранится в сессии, так что можно туда-сюда ходить и подбирать правильный корень.

В обоих случаях в итоге получаю одну конкретную папку, которая будет корнем скана.

Тонкая настройка: кнопка Choose items…

Следующая фишка — возможность точно сказать, что включать, а что нет.

По умолчанию сканер идёт по всем вложенным папкам. Плюс в коде есть глобальные исключения (vendor, upload, какие-то служебные директории, бинарные файлы и т.п.).

Но бывают ситуации:

  • нужно сканировать весь модуль, но без конкретной тяжёлой папки;

  • нужно исключить пару больших файлов;

  • хочется аккуратно «обрезать» верхний уровень.

Для этого я добавил кнопку Choose items….

Как это работает:

  1. Я выбираю корневую папку (любой из двух способов).

  2. Нажимаю Choose items….

  3. Открывается панель со списком всех подпапок и файлов первого уровня внутри корня.

  4. Напротив каждого пункта — чекбокс.

  5. По умолчанию всё включено.

  6. Я снимаю галочки с того, что не хочу отдавать в JSON:

    • отдельные папки,

    • отдельные файлы.

  7. Нажимаю Apply selection.

Дальше сканер уже учитывает этот выбор:

  • на первом уровне он обходит только выбранные элементы,

  • внутрь выбранной папки заходит целиком и дальше работает как раньше,

  • поверх этого работают глобальные исключения (excludeDirs, excludeFiles и т.д.).

Если я никогда не нажимаю Choose items…, скрипт ведёт себя как в самой первой версии — сканирует всё дерево, кроме общих исключений.

Куда складывается результат

Всё, что связано со сканом, кладётся в папку scan_tmp под DOCUMENT_ROOT:

  • туда пишет временный список файлов,

  • туда же складывает JSONL, JSON, части и ZIP-архивы.

На странице видно, есть ли готовые данные, и есть отдельная кнопка Delete data — она удаляет содержимое scan_tmp и даёт начать с чистого листа.

Форматы вывода: JSONL, JSON и части

На выходе меня интересовало сразу несколько сценариев:

  • работать с JSONL в своих пайплайнах;

  • загружать полный JSON/части в GPT-ассистентов (там нужен один валидный JSON);

  • не думать о лимитах ассистентов по размеру файла.

JSONL

Это основной формат для «машинной» обработки.

Каждая строка — отдельный файл:

{"file":"local/components/app/orders/class.php","content":"..."}

Плюсы:

  • можно читать построчно, не держа всё в памяти;

  • удобно обрабатывать большими порциями;

  • хорошо ложится на любые стриминговые сценарии и индексы.

Я использую JSONL, если хочу:

  • написать свой скрипт/агента, который анализирует проект;

  • делать векторизацию кода и складывать всё это в базу;

  • комбинировать это с RAG-подходами.

JSON (цельный)

Многим внешним инструментам нужен один JSON-документ.
Например, GPT-ассистентам при загрузке файлов.

Поэтому я делаю ещё один вариант — массив:

[
  {"file":"...","content":"..."},
  {"file":"...","content":"..."}
]

Этот формат удобно:

  • грузить прямо в ассистента как файл;

  • хранить снепшоты релиза;

  • использовать в тех местах, где JSONL не поддерживается.

JSON по частям

Для больших проектов один JSON может оказаться слишком объёмным.
У ассистентов есть лимиты по размеру файла и по токенам.

Поэтому я добавил автоматическую нарезку:

  • при достижении примерно TOKEN_MAX слов текущий JSON закрывается;

  • создаётся следующая часть;

  • итогом получается несколько файлов:

    • project_1.json, project_2.json, project_3.json и т.п.

Важный момент: режется по строкам/записям, а не по байтам.
То есть каждый объект {file, content} всегда целиком внутри одного файла.

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

ZIP-архивы и подсчёт «токенов»

Дополнительно скрипт делает:

  • ZIP с JSONL;

  • ZIP с JSON;

  • ZIP с JSON-частями.

И выводит примерное количество «токенов» (по факту — слов) в данных.
Это не точный счётчик конкретной модели, но хороший ориентир по масштабу проекта.

Обратная сторона: restore.php и восстановление из JSONL

После того как я какое-то время пользовался только сканером, стало не хватать обратной операции.

Возникли сценарии:

  • «хочу у себя локально поднять минимальную копию проекта из снапшота»;

  • «хочу отдать подрядчику JSONL + скрипт, чтобы он сам развернул структуру у себя»;

  • «нужно быстро собрать песочницу только из тех файлов, которые попали в скан».

Так появился второй скрипт — restore.php.

Что он делает

В двух словах:

  • берёт JSONL, который сделал scan.php;

  • для каждой строки с {file, content}:

    • нормализует путь;

    • создаёт нужную папку;

    • записывает файл в выбран��ую директорию.

Важно:

  • restore.php не пытается быть полноценным бэкапом;

  • он честно восстанавливает только то, что было в JSONL:

    • если вы исключили vendor, в восстановленный проект он не попадёт;

    • если вы выкинули часть модулей через Choose items…, их тоже не будет.

То есть это именно восстановление фильтрованного среза, а не «верни мне прод ровно как был».

Как им пользоваться

Процесс простой:

  1. Кладу restore.php туда же, где scan.php.

  2. Открываю в браузере.

  3. Прохожу авторизацию:

    • либо через Bitrix-админа (если так настроено),

    • либо по паролю.

  4. Выбираю исходный JSONL:

    • либо из списка файлов в scan_tmp,

    • либо указываю путь вручную.

  5. Задаю целевую папку:

    • это директория под DOCUMENT_ROOT, например restored_project;

    • если её нет — скрипт создаст.

  6. Включаю или выключаю опции:

    • Dry run — просто посчитать, что было бы создано/перезаписано, без реальных записей;

    • Overwrite existing files — разрешить перезапись уже существующих файлов в целевой папке.

  7. Запускаю.

Скрипт идёт по JSONL построчно, аккуратно проверяет:

  • что путь относительный;

  • что нет попыток выйти через ..;

  • что конечный путь остаётся внутри целевой директории.

По итогу выдаёт статистику:

  • сколько строк обработано;

  • сколько валидных записей;

  • сколько файлов создано;

  • сколько перезаписано;

  • сколько пропущено;

  • с��олько записей были некорректны.

Для чего это удобно

На практике restore.php оказался полезен в таких ситуациях:

  • Лёгкая копия проекта для ИИ-экспериментов

    Не хочется тянуть продовый проект со всеми артефактами.
    Я делаю скан с аккуратными исключениями и разворачиваю этот срез отдельно.
    Там можно спокойно переписывать код, давать доступ ассистентам, ставить инструменты.

  • Передача проекта внешнему разработчику

    Вместо живого доступа к репо/серверу я могу:

    • сделать JSONL только из нужных частей,

    • отправить подрядчику JSONL + restore.php,

    • он у себя разворачивает структуру и работает.

  • Минимальный репро-проект

    Если баг живёт в каком-то модуле, можно:

    • отсканировать только этот модуль,

    • развернуть его в отдельную папку,

    • добавить нужные зависимости,

    • и воспроизводить проблему уже в уменьшенном окружении.

Как это всё используется на практике (мой рабочий цикл)

Пример того, как я живу с этим инструментом день-в-день.

Сценарий 1. Обсудить с ИИ доработку в существующем проекте

  1. Выбираю проект и добавляю scan.php (если его там ещё нет).

  2. Настраиваю:

    • исключения vendor, upload и то, что точно не нужно;

    • ограничиваю корень до нужного модуля;

    • при необходимости через Choose items… выкидываю тяжёлые или неинтересные папки.

  3. Запускаю скан. Получаю JSONL.

  4. Пишу небольшой скрипт/агента, который:

    • читает JSONL,

    • ищет нужные файлы по маскам,

    • собирает контекст и формирует запрос к модели.

  5. Дальше мы с ИИ обсуждаем уже не абстрактный PHP, а конкретный проект:
    модель реально видит файлы, о которых я говорю.

Сценарий 2. Ассистент «по проекту» в GPT

  1. Беру JSON-части (если проект большой) или один JSON-файл.

  2. Создаю GPT-ассистента.

  3. Загружаю эти файлы как «знания» ассистента.

  4. В инструкциях пишу, что это конкретный проект, и объясняю, как с ним работать.

  5. Разработчик приходит к ассистенту и спрашивает:

    • «Где у нас реализована регистрация?»

    • «Какие классы отвечают за оплату?»

    • «Помоги добавить ещё один статус заказа и не забыть про все места».

Ассистент отвечает уже на основе реального кода, а не по памяти модели.

Сценарий 3. Аудит legacy или чужого проекта

  1. Кидаю scan.php на сервер (лучше в стейджинг/копию).

  2. Сканирую нужную часть проекта.

  3. Получаю JSONL, вытаскиваю его к себе.

  4. Пользуюсь либо:

    • ассистентом, либо

    • своим скриптом, который бегает по JSONL.

Можно попросить ИИ:

  • описать архитектуру по директориям;

  • найти «подозрительные» место в коде;

  • составить список технического долга по модулям.

Сценарий 4. Восстановить срез как отдельный проект

  1. Беру уже готовый JSONL (например, старый снапшот релиза).

  2. Через restore.php разворачиваю это в restored_project/.

  3. Получаю отдельную структуру:

    • с теми же путями;

    • но без того, что я выкидывал при скане.

Дальше можно:

  • подключить туда свои инструменты;

  • дать доступ ассистентам;

  • использовать как «песочницу» для экспериментов.

Как попробовать у себя

Минимальный путь такой.

  1. Клонировать репозиторий

    git clone https://github.com/simai/scan2json.git

  2. Положить scan.php и restore.php в проект

    Например, в корень сайта под DOCUMENT_ROOT.
    Я обычно не коммичу их в основной репозиторий проекта, а держу только на сервере/копии.

  3. Настроить доступ

    В начале файлов есть константы:

    • ACCESS_BITRIX — использовать ли проверку через Bitrix-админа;

    • ACCESS_PASSWORD — пароль для простого режима.

    Я обязательно меняю пароль с дефолтного и не выкладываю скрипты наружу без защиты.

  4. Открыть scan.php в браузере

    • пройти авторизацию;

    • выбрать папку;

    • при необходимости нажать Choose items…;

    • запустить скан.

  5. Скачать JSONL/JSON/части

    Посмотреть, где появился scan_tmp, и забрать оттуда файлы.

  6. При желании — протестировать restore.php

    На отдельной тестовой директории:

    • указать JSONL;

    • задать новую папку;

    • сначала сделать Dry run, потом настоящий запуск.

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

Финал

Для меня scan2json — живой эксперимент, который родился из реальной боли:
я устал объяснять ИИ проекты по кусочкам.

Сейчас это уже не просто скрипт «на коленке», а небольшой набор инструментов:

  • scan.php — чтобы снять структурированный снимок проекта в JSON/JSONL;

  • restore.php — чтобы по этому снимку собрать отдельную копию.

Я сам активно пользуюсь им в своей работе и периодически его дорабатываю.
Если тебе эта идея откликается — можно:

  • взять репозиторий,

  • попробовать на своём проекте,

  • и, если будут мысли, завести issue или PR.

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