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

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

В статье:

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

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

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

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

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

Файл, не попавший ни в один список, роняет сборку. Это единственная страховка такой раскладки: без неё новый файл однажды уехал бы на портал молча.

Тот же список продублирован в .gitattributes через export-ignore — он решает, что попадёт в Composer-пакет, потому что git archive его соблюдает. Списки обязаны совпадать, иначе на портал уедет разное в зависимости от способа установки. Сверяется автоматически и в обе стороны, см. check_gitattributes.

Что где лежит

путьчто это
install/index.phpSHIPустановщик, класс shef_options extends CModule
install/version.phpSHIPVERSION и VERSION_DATE — источник истины о версии
install/css/SHIPстили страницы настроек; установщик раскладывает их в /bitrix/css
.settings.phpSHIPнастройки модуля: ajax-контроллеры, карта раскладки installDir
include.phpSHIPточка входа модуля: подключает autoload.php, def-functions.php и register-js.php
def-functions.phpSHIPглобальные _log() и _pr(), которые зовёт трейт TraitList\Log
autoload.phpSHIPзависимости модуля и регистрация чужих namespace
project-context.phpSHIPзнает, есть ли на проекте Composer и где его vendor
options.php, options_conf.php, optionsconfig.phpSHIPстраница настроек модуля
lib/SHIPклассы модуля, имена файлов строго строчными
lang/ru/SHIPязыковые файлы, зеркалят структуру lib/
README.md, CHANGELOG.md, LICENSESHIP
composer.jsonSHIPманифест пакета
docs/KEEPвся документация, и модуля, и репозитория
build.shKEEPсборка и проверки
tests/KEEPтесты
examples/KEEPзапускаемые примеры к строительным блокам
.claude/skills/KEEPнавыки агента (источник для всей линейки) плюс evals/ внутри навыков, sync.sh и MANIFEST
.github/KEEPCI и релиз
CONTRIBUTING.mdKEEP
CLAUDE.mdKEEPпамятка агенту: она про репозиторий, а не про модуль
.gitattributes, .gitignoreKEEP
.php-cs-fixer.dist.phpKEEPправила форматирования; гоняются composer run lint, не из build.sh
composer.lockKEEPверсии инструментов разработчика; на зависимости пакета не влияет

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

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

Раньше модуль рендерил README.md прямо в настройках: отдельная вкладка, ajax-контроллер, вендорённый php-markdown и js-расширение к нему. В 3.0.0 этот блок убран целиком. Документация на GitHub всегда свежая, а не той версии, что когда-то поставили на портал, — значит, второй её копии внутри модуля хватало ровно на то, чтобы расходиться с первой. Заодно с ней из поставки ушли vendor/Michelf/, install/js/ и единственный ajax-контроллер модуля.

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

Bitrix\Main\Loader отображает класс в путь строчными, разбирая первые два сегмента namespace как id модуля: Shef\Options\Main\Utils ищется как bitrix/modules/shef.options/lib/main/utils.php. Отсюда же пустой registerNamespace в .settings.php — он нужен только для чужих namespace, а своих у модуля нет. Читает этот ключ autoload.php.

project-context.php выглядит частью той же механики, но ею не является: файл объявляет глобальный ShComposerContext и едет в поставку, однако в самом модуле его никто не подключает — registerNamespace задан пустым литералом. Это заготовка для модулей линейки, чей .settings.php может собрать список путей Composer через него.

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

Несимметричные имена каталогов фронта

install/css/shef.options/     -> /bitrix/css/shef.options/      (точка)
     (js)  shef-options/      -> /bitrix/js/shef-options/       (дефис)

Точка — id модуля, дефис — требование имён расширений Битрикса: каталог /bitrix/js/shef-options/options-markdown грузился бы как расширение shef-options.options-markdown.

Своего JS модуль с 3.0.0 не раскладывает — install/js/ в репозитории нет, — но getPublicJsDir() остался: по нему установщик убирает каталог, оставшийся на порталах от прежних версий.

Оба пути выводятся из MODULE_ID в Constants::getPublicCssDir() и getPublicJsDir() и больше нигде строкой не пишутся. Сходимость с раскладкой установщика проверяет tests/assets_test.php.

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