Раскладка репозитория

Файл про устройство репозитория. Опорные точки модуля — в CLAUDE.md, процесс — в CONTRIBUTING.md, сборка — в build-and-install.md.

В статье:

Файл про устройство репозитория. Опорные точки модуля — в CLAUDE.md, процесс — в CONTRIBUTING.md, сборка — в build-and-install.md.

Модуль лежит в корне, и это вынужденно

Composer разворачивает в целевой каталог корень пакета целиком и подкаталоги выбирать не умеет. Поэтому lib/, install/, lang/ лежат прямо в корне репозитория, рядом с build.sh и .github/.

Плата за это — два списка в шапке build.sh:

  • SHIP — уезжает на портал и в Composer-пакет;
  • KEEP — остаётся в репозитории.

Файл, не попавший ни в один список, роняет сборку. Тот же список продублирован в .gitattributes через export-ignore; списки обязаны совпадать, сверяется автоматически, см. check_gitattributes.

Что где лежит

путьчто это
install/index.phpSHIPустановщик, класс shef_insync extends CModule: таблица импорта, левое меню, раскладка компонентов и js
install/version.phpSHIPVERSION и VERSION_DATE — источник истины о версии
install/components/shef.insync/SHIPкомпоненты import.from.file и import.stat.local; установщик раскладывает их в /bitrix/components
install/js/shef-insync/SHIPрасширение shef-insync.ui-anchors (страницы импорта в слайдере); установщик раскладывает в /bitrix/js
.settings.phpSHIPзависимости, раскладка, левое меню, контроллеры, откуда брать библиотеки XML
include.phpSHIPточка входа: autoload.php
autoload.phpSHIPподключает shef.options, shef.problems и регистрирует библиотеки XML
default_option.phpSHIPумолчания настроек
options.php, options_conf.phpSHIPстраница настроек на ShOptionsConfig из shef.options
lib/SHIPклассы модуля, имена файлов строго строчными
lang/ru/SHIPязыковые файлы, зеркалят структуру lib/
meta/orm.phpSHIPаннотации ORM для IDE; никем не подключается
vendor/sbwerewolf/SHIPсвоя копия библиотек разбора XML для установки архивом; версии — в vendor/versions.json
README.md, CHANGELOG.md, LICENSESHIP
composer.jsonSHIPманифест пакета bxshef/insync
docs/KEEPвся документация
build.shKEEPсборка и проверки
tests/KEEPтесты и заглушки ядра
examples/KEEPзапускаемые примеры
.claude/skills/KEEPнавыки агента: навыки линейки — копия из bx-shef/options (sync.sh --to), навыки про shef.insync — свои, перечислены в LOCAL.MANIFEST (sync.sh --local)
.github/KEEPCI и релиз
CONTRIBUTING.md, CLAUDE.mdKEEPпроцесс и памятка агенту
.gitattributes, .gitignoreKEEP

Что где в lib/

каталогчто там
agents/AAgent — базовый агент, Entity — описание агента, Manager — установка, запуск, остановка, поиск
api/AConnector — обращение к внешнему API по HTTP, Headers — маска секретных заголовков для лога
sync/интерфейсы импорта (IProcess, IElement, …), EStatus, AProcess
sync/fromfile/импорт файлов: AFileProcess, ACsvProcess, AXmlProcess, агент разбора AAgent, стратегии Strategy\*
sync/crm/ACrmProcess — импорт из сущностей CRM
sync/model/таблица импорта SyncTable, модели инфоблоков, каталога, складов
sync/integration/Manager — push-обновление страницы статистики
main/Constants, Utils, Access — кто управляет импортом
main/options/опции страницы настроек для модулей импорта: агент и пошаговый импорт
integration/intranet/провайдер страниц левого меню
traitlist/трейты: класс таблицы импорта, разбор XML

Нижний регистр в lib/ обязателен

Bitrix\Main\Loader отображает класс в путь строчными, разбирая первые два сегмента namespace как id модуля: Shef\InSync\Main\Utils ищется как bitrix/modules/shef.insync/lib/main/utils.php. Поэтому свой namespace в registerNamespace не нужен — там только библиотеки XML.

На macOS заглавная буква сходит с рук, на боевом Linux класс просто не найдётся. Проверяется в build.sh, check_lowercase, и в tests/autoload_test.php.

У vendor/ соглашение своё — PSR-4 с заглавными, путь задаёт .settings.php.

Компоненты и фронт

install/components/shef.insync/   -> /bitrix/components/shef.insync/
install/js/shef-insync/ui-anchors -> /bitrix/js/shef-insync/ui-anchors/

Каталог модуля браузеру недоступен, поэтому компоненты и js копирует установщик — карта в .settings.php, ключ installDir. Расширение находится ядром по имени shef-insync.ui-anchors: каталог через дефис — требование имён расширений. Сходимость с раскладкой проверяет tests/assets_test.php.

До 2.0.0 компоненты ложились в /local/components/shef.insync. Ядро смотрит туда первым, и оставшаяся копия перекрыла бы новую, поэтому установщик убирает её и при установке, и при удалении.

Минифицированных копий (*.min.js, *.min.css) нет. Ядро берёт .min, если он есть, — и устаревший .min молча побеждал бы исправленный исходник. Отсутствие проверяет tests/assets_test.php. *.min.min.* — мусор сборщиков, его отсекает .gitignore.

Раскладка страниц — штатные ui.* и свои несколько правил в style.css шаблона. Сетка и карточки shef.uiclear ушли вместе с зависимостью.

Документация не едет на портал

Документация живёт в репозитории. В поставке остаётся только README.md — как readme пакета, — и все ссылки из него ведут на GitHub.

Источник: insync/docs/module-structure.md — правки туда, сайт пересобирается сам.
CtrlI