Скрипты сборки и утилиты

Директория scripts/ — это слой движка сборки и проверки. Большинство команд из package.json представляет собой тонкие обёртки над этими скриптами; скрипты можно запускать и напрямую, передавая аргументы для отладки.

Обзор скриптов

Скрипт	Команда-обёртка	Назначение
build-styles.mjs	pnpm build:styles	Компиляция scss share → dist/theme/ + dist/styles/
sync-exports.mjs	pnpm sync:exports (входит в pnpm build)	Генерация exports в package.json по структуре каталога исходников
verify-dts.mjs	pnpm verify:dts	Совпадение dts-артефактов с типами исходников
verify-styles.mjs	pnpm verify:styles	Шесть проверок scss (см. Система проверки)
verify-theme-contrast.mjs	pnpm verify:theme	Гейт контрастности AA 4.5:1 для тем
check-version-sync.mjs	pnpm verify:versions	Диапазон зависимости в каждой UI-библиотеке покрывает текущую версию share
gen-docs-data.mjs	pnpm docs:data	Разбор токенов / иконок / классов → docs/src/data/*.json
push-release.mjs	pnpm release:push	Отправка master + tag на GitHub, запуск архивации релиза
release-notes.mjs	—	Генерация описания релиза
extract-from-plus.mjs	pnpm extract	Одноразовый скрипт: извлечение общего слоя из репозитория plus (историческое использование)
normalize-styles.mjs	—	Нормализация стилей (исторический одноразовый)
patch-var-fallbacks.mjs	—	Массовое добавление fallback-значений для var() (исторический одноразовый)

sync-exports.mjs —— генератор ключей exports

Это самый проблемный скрипт из всех.

В package.json пакета @lh-ui/share 77 ключей exports (подобные ./core/button/*), и все они генерируются этим скриптом путём сканирования структуры каталогов src/ и styles/.

Процесс: артефакты vite build записаны на диск → sync:exports сканирует структуру es/ → перезаписывает поля exports / files в package.json.

Почему это важно:

• Добавили src/core/foo/bar.ts — в dev-режиме (через alias на исходники) он доступен сразу, но на стороне npm соответствующего ключа exports нет — после pnpm up у пользователей ниже по потоку возникает MODULE_NOT_FOUND.
• Перед релизом обязательно полный pnpm build (включая sync:exports), а не только build:dts.

Обратите внимание, скрипт меняет package.json: после запуска в git diff будут видны изменения exports — это нормально, их нужно закоммитить.

build-styles.mjs —— стилевые артефакты

Компилирует SCSS-исходники из styles/ в css:

dist/
├── theme/
│   ├── index.css          # Токены темы (светлая)
│   └── index-dark.css     # Тёмное переопределение
└── styles/
    └── index.css          # Полная агрегация (токены + все компоненты)

Также генерируется файл полной агрегации styles/index.scss (сканированием styles/*/index.scss); согласованность с ним проверяет пункт 4 в verify:styles — не правьте этот файл вручную.

В каждой UI-библиотеке есть свой build-styles.mjs (версия plus сканирует packages/components, версия vue2 — src/components); компоненты, у которых в share нет источника стилей, пропускаются тихо — поэтому в share должен быть соответствующий scss, иначе у компонента не будет стилевых артефактов на одном из концов.

gen-docs-data.mjs —— генерация данных для документации

pnpm docs:data

Разбирает четыре источника → docs/src/data/*.json:

Вывод	Источник	Содержимое
tokens.json	var.scss + var-dark.scss + variables.scss	185 светлых + 118 тёмных + 183 SCSS-переменные, сгруппированные по семантическим доменам
icons.json	src/.../icon/svgs.ts	37 встроенных иконок
classes.json	styles/*/index.scss	58 списков BEM-классов компонентов

Снабжён количественными утверждениями: если количество разобранных элементов не совпадает с ожидаемым (185 / 118 / 183 / 37 / 58), скрипт сразу выбрасывает ошибку. Это первая линия защиты от «токен случайно удалили / компонент случайно удалили».

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

push-release.mjs —— отправка релиза

pnpm release:push

Выполняется после pnpm release (публикация в npm + создание локального tag):

1. Отправка master на github-lhgb
2. Отправка tag текущей версии на github-lhgb
3. Запуск .github/workflows/release.yml: загрузка уже опубликованного tarball из npm → создание GitHub Release (с вложением lh-ui-share-<version>.tgz) → отправка tag в Gitee и вызов API Gitee для создания релиза

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

verify-theme-contrast.mjs —— гейт контрастности

Читает артефакты es/ (поэтому сначала нужно pnpm build), и с помощью getRelativeLuminance / getContrastRatio, экспортируемых из src/theme/themes/index.ts, считает контрастность WCAG для каждой пары «текст / фон»; значение ниже 4.5:1 означает провал.

Чтобы отладить отдельную цветовую пару, можно вызвать эти две функции прямо в node, не запуская полную проверку.

Исторические одноразовые скрипты

Скрипт	Описание
extract-from-plus.mjs	Извлечение общего слоя из lh-ui-plus при создании репозитория share. Сохранён как запись и больше не запускается — share уже является единственным источником (красная линия 2).
normalize-styles.mjs	Ранняя нормализация стилей (унификация способа ссылки на токены). Свою задачу выполнил.
patch-var-fallbacks.mjs	Массовое добавление fallback-значений для var(--lh-*). Это миграционный инструмент, предшествовавший пункту 2 verify:styles (проверка var fallback) — новый код должен содержать fallback вручную, не рассчитывайте на этот скрипт.

Сайт документации не является npm-артефактом

Поле files в package.json равно ["es", "lib", "dist", "styles"] и не включает docs/. Сайт документации собирается через pnpm docs:build в docs/dist/ и разворачивается вручную на семейном nginx (контракт описан в lh-ui/docs/部署/nginx-lhui.conf.md, другой репозиторий). Подробнее см. Процесс выпуска релиза.

Связанные документы

• Список команд — pnpm-команды для каждого скрипта
• Система проверки — логика проверок каждого verify-скрипта
• Процесс выпуска релиза — push-release и архивация в CI
• Точка входа пакета и подпути — 77 ключей, сгенерированных sync-exports