mdt-module-builder 1.0.3 → 1.0.4

package/README.md

@@ -37,6 +37,12 @@ devtool/builder вызывают `npm run build` в репе модуля — м
   компоненты модуля читали бы чужой `ThemeContext`. CSS-сабпасы (`styles.css`) не externalize-ятся.
 - **lucide-react, mdt-client** — бандлятся внутрь `index.js` (должны быть установлены).
   Их внутренний `import "react"` тоже перехватывается шимом.
+  Почему lucide бандлится, а ui-kit шарится (решение зафиксировано, не пересматривать без новых данных):
+  ui-kit **обязан** быть общим по корректности — у него React-контекст (тема, провайдеры), две копии =
+  сломанная тема. Иконки lucide — stateless SVG без контекста, дубли безвредны. При этом lucide импортят
+  именованно из корня (`import { X } from "lucide-react"`), так что шаринг = отдать весь namespace →
+  MDT забандлил бы **все ~1900 иконок без tree-shaking**. Per-module бандл, наоборот, tree-shaking-ом
+  тянет только used-иконки (единицы, ~КБ). Пара дублей по модулям несравнимо дешевле, чем вся lucide в MDT.
 - **CSS** инлайнится в `index.js` (рантайм-инъекция `<style>`), как старый style-loader —
   оверлей копирует только `index.js`, отдельного `.css` нет.
 - **Tailwind (вариант A)** — билдер сам генерит утилиты Tailwind, найденные **только в `src`
@@ -45,6 +51,23 @@ devtool/builder вызывают `npm run build` в репе модуля — м
   (`--primary` и пр.) даёт MDT глобально. ui-kit из `node_modules` повторно не сканируется —
   его классы уже эмитит основная сборка MDT. Возможны дубли утилит между модулями — это принято.
 
+## Совместимость исходников модуля (webpack → Vite)
+
+Ядро воспроизводит удобства старого (webpack) билдера, чтобы исходники модуля не переписывать:
+
+- **tsconfig `paths` → `resolve.alias`.** Билдер читает `compilerOptions.paths`/`baseUrl` из
+  `tsconfig.json` модуля и разворачивает в alias'ы Vite (аналог `tsconfig-paths-webpack-plugin`).
+  Импорты вида `import x from "_core/scripts/..."` резолвятся без правок. Берётся первый target
+  маппинга; `prefix/*` → wildcard с захватом хвоста, точный ключ → строковый алиас.
+- **CSS-вложенность.** Компонентный CSS модуля (`import "./x.css"`) прогоняется через
+  `postcss-nested` (Sass-подобный `&`) + `autoprefixer` — та же семантика, что у старого
+  `postcss-loader`. Native CSS nesting не задействуется. Утилиты Tailwind генерятся отдельно.
+- **`.svg` как строка.** SVG импортится встроенным Vite-суффиксом `?raw`
+  (`import logo from "./logo.svg?raw"`) → строка с разметкой, инлайнится, без отдельного ассет-файла.
+  Байт-в-байт как старый `svg-inline-loader`. Билдер SVG специально не обрабатывает: **bare**-импорт
+  `.svg` без `?raw` уедет в отдельный файл, который контракт модуля (копируется только `index.js`)
+  потеряет — всегда с `?raw`.
+
 ## Доступ к функционалу MDT — `@mdt/*`
 
 Любой `@mdt/<имя>` билдер externalize-ит и резолвит в `globalThis.__mdtSdk["<имя>"]`. Наполняет этот

package/SHARED-DEPENDENCIES.md

@@ -1,119 +1,119 @@
-# Общие зависимости модулей: вынос в MDT
-
-Когда внешнему модулю нужна библиотека, которую логично держать **одним инстансом на всё
-приложение** (или не таскать её копию в каждый модуль), она «выносится» в MDT: MDT ставит её,
-экспонирует через `globalThis.__mdtShared`, а сборка модуля её **не бандлит**, а читает оттуда.
-Ровно так уже сделано для react-семьи; этот документ — про добавление новой такой зависимости.
-
----
-
-## Шаг 0. Решить: выносить или бандлить
-
-Выносим, если выполняется хотя бы одно:
-
-- **Нужен единый инстанс/контекст.** Несколько копий ломаются: react (hooks), `@tanstack/react-query`
-  (общий `QueryClient`/контекст). → выносить **обязательно**.
-- **Тяжёлая.** `echarts` ~1 МБ — копия в каждом модуле недопустима. → выносим ради веса.
-- **Нужна ≥ 2 модулям.** Дедуп.
-
-Если ничего из этого — **не выносим**. Просто импортируй в модуле, она забандлится внутрь. Ничего
-делать не надо.
-
----
-
-## План выноса (по шагам)
-
-Каждый шаг — действие и явное «Готово, когда». Не переходи к следующему, пока текущее не закрыто.
-
-### Шаг 1. Поставить зависимость в MDT
-
-```
-cd ui && npm i <dep>@<версия>
-```
-
-Версия, которую ты зафиксировал в MDT, **становится контрактом** — модули будут пользоваться
-этим мажором.
-
-> **Готово, когда:** `<dep>` стоит в `ui/package.json → dependencies`.
-
-### Шаг 2. Экспонировать в `__mdtShared`
-
-В `ui/vite-app/src/legacy/config-global.ts`:
-
-```ts
-import * as _Dep from "<dep>";
-// ...
-(globalThis as any).__mdtShared = Object.assign((globalThis as any).__mdtShared ?? {}, {
-  // ...уже существующие...
-  "<dep>": _Dep
-});
-```
-
-Ключ — **точный спецификатор импорта**. Для каждого подпути, который импортируют модули
-(`<dep>/sub`, например `zustand/middleware`), — отдельный `import * as` и отдельный ключ.
-
-> **Готово, когда:** в рантайме `globalThis.__mdtShared["<dep>"]` возвращает библиотеку.
-
-### Шаг 3. Externalize в билдере
-
-В `ui/module-builder/src/index.mjs` добавь спецификатор (и каждый подпуть) в массив `SHARED_GLOBALS`.
-
-> **Готово, когда:** сборка модуля ссылается на `globalThis.__mdtShared["<dep>"]`, а кода библиотеки
-> в `dist/index.js` нет. Имена экспортов перечислять **не нужно** — Rollup обращается к членам глобала сам.
-
-### Шаг 4. Доставить билдер в CI модуля
-
-Dev-стенд MDT собирает модуль **локальным** исходником билдера → новый `SHARED_GLOBALS` работает
-сразу. Для `npm run build` в репозитории модуля нужен **опубликованный** `mdt-module-builder` с этим
-изменением:
-
-```
-cd ui/module-builder && npm publish   # вручную, как и весь mdt-module-builder
-```
-
-> **Готово, когда:** в репо модуля стоит версия `mdt-module-builder`, где зависимость уже в `SHARED_GLOBALS`.
-
-### Шаг 5. Подключить в модуле (только типы)
-
-```
-npm i -D <dep>@<версия>   # в репозитории модуля; тот же мажор, что в MDT
-```
-
-Импортируй и пользуйся как обычно — в бандл библиотека не попадёт, тип берётся из devDependency.
-
-> **Готово, когда:** типы резолвятся, импорт компилируется.
-
-### Шаг 6. Проверить
-
-Собери модуль и убедись:
-
-- вес `dist/index.js` **не вырос** на размер библиотеки;
-- в нём есть `globalThis.__mdtShared["<dep>"]` и **нет** кода библиотеки.
-
-> **Готово, когда:** оба пункта выполнены.
-
----
-
-## Подводные камни
-
-- **Версия — это контракт.** Мажор в MDT и в модуле должен совпадать (как с react). Рассинхрон
-  даёт трудноуловимые поломки (аналог «Invalid hook call»).
-- **Подпуть — отдельный спецификатор.** `zustand/middleware` ≠ `zustand`. Каждый используемый
-  подпуть нужно добавить и в `__mdtShared` (Шаг 2), и в `SHARED_GLOBALS` (Шаг 3).
-- **`@tanstack/react-query`: единого инстанса мало.** Модуль должен обернуть своё дерево в
-  `<QueryClientProvider client={...}>`. Контекст работает именно потому, что инстанс один; сам
-  провайдер — ответственность модуля (каждый React-root монтируется отдельно через
-  `wrapComponent`/`createPageControl`).
-- **Default-импорт** (`import X from "echarts-for-react"`) работает через стандартный interop
-  Rollup; после выноса проверь в рантайме, что `X` — это сам компонент, а не неймспейс.
-- **react-семья — особый, исторический случай** (alias-шимы `SHARED_EXACT`/`SHARED_NAMES` с
-  перечислением имён). **Новые** зависимости добавляй в `SHARED_GLOBALS` — там имена перечислять не надо.
-
----
-
-## Текущий список общих зависимостей
-
-- **react-семья** (`SHARED_EXACT`, alias-шимы): `react`, `react-dom`, `react-dom/client`,
-  `react/jsx-runtime`, `react/jsx-dev-runtime`.
-- **Externalize** (`SHARED_GLOBALS`): `@tanstack/react-query`, `zustand`, `zustand/middleware`,
-  `zustand/react/shallow`, `echarts`, `echarts-for-react`.
+# Общие зависимости модулей: вынос в MDT
+
+Когда внешнему модулю нужна библиотека, которую логично держать **одним инстансом на всё
+приложение** (или не таскать её копию в каждый модуль), она «выносится» в MDT: MDT ставит её,
+экспонирует через `globalThis.__mdtShared`, а сборка модуля её **не бандлит**, а читает оттуда.
+Ровно так уже сделано для react-семьи; этот документ — про добавление новой такой зависимости.
+
+---
+
+## Шаг 0. Решить: выносить или бандлить
+
+Выносим, если выполняется хотя бы одно:
+
+- **Нужен единый инстанс/контекст.** Несколько копий ломаются: react (hooks), `@tanstack/react-query`
+  (общий `QueryClient`/контекст). → выносить **обязательно**.
+- **Тяжёлая.** `echarts` ~1 МБ — копия в каждом модуле недопустима. → выносим ради веса.
+- **Нужна ≥ 2 модулям.** Дедуп.
+
+Если ничего из этого — **не выносим**. Просто импортируй в модуле, она забандлится внутрь. Ничего
+делать не надо.
+
+---
+
+## План выноса (по шагам)
+
+Каждый шаг — действие и явное «Готово, когда». Не переходи к следующему, пока текущее не закрыто.
+
+### Шаг 1. Поставить зависимость в MDT
+
+```
+cd ui && npm i <dep>@<версия>
+```
+
+Версия, которую ты зафиксировал в MDT, **становится контрактом** — модули будут пользоваться
+этим мажором.
+
+> **Готово, когда:** `<dep>` стоит в `ui/package.json → dependencies`.
+
+### Шаг 2. Экспонировать в `__mdtShared`
+
+В `ui/vite-app/src/legacy/config-global.ts`:
+
+```ts
+import * as _Dep from "<dep>";
+// ...
+(globalThis as any).__mdtShared = Object.assign((globalThis as any).__mdtShared ?? {}, {
+  // ...уже существующие...
+  "<dep>": _Dep
+});
+```
+
+Ключ — **точный спецификатор импорта**. Для каждого подпути, который импортируют модули
+(`<dep>/sub`, например `zustand/middleware`), — отдельный `import * as` и отдельный ключ.
+
+> **Готово, когда:** в рантайме `globalThis.__mdtShared["<dep>"]` возвращает библиотеку.
+
+### Шаг 3. Externalize в билдере
+
+В `ui/module-builder/src/index.mjs` добавь спецификатор (и каждый подпуть) в массив `SHARED_GLOBALS`.
+
+> **Готово, когда:** сборка модуля ссылается на `globalThis.__mdtShared["<dep>"]`, а кода библиотеки
+> в `dist/index.js` нет. Имена экспортов перечислять **не нужно** — Rollup обращается к членам глобала сам.
+
+### Шаг 4. Доставить билдер в CI модуля
+
+Dev-стенд MDT собирает модуль **локальным** исходником билдера → новый `SHARED_GLOBALS` работает
+сразу. Для `npm run build` в репозитории модуля нужен **опубликованный** `mdt-module-builder` с этим
+изменением:
+
+```
+cd ui/module-builder && npm publish   # вручную, как и весь mdt-module-builder
+```
+
+> **Готово, когда:** в репо модуля стоит версия `mdt-module-builder`, где зависимость уже в `SHARED_GLOBALS`.
+
+### Шаг 5. Подключить в модуле (только типы)
+
+```
+npm i -D <dep>@<версия>   # в репозитории модуля; тот же мажор, что в MDT
+```
+
+Импортируй и пользуйся как обычно — в бандл библиотека не попадёт, тип берётся из devDependency.
+
+> **Готово, когда:** типы резолвятся, импорт компилируется.
+
+### Шаг 6. Проверить
+
+Собери модуль и убедись:
+
+- вес `dist/index.js` **не вырос** на размер библиотеки;
+- в нём есть `globalThis.__mdtShared["<dep>"]` и **нет** кода библиотеки.
+
+> **Готово, когда:** оба пункта выполнены.
+
+---
+
+## Подводные камни
+
+- **Версия — это контракт.** Мажор в MDT и в модуле должен совпадать (как с react). Рассинхрон
+  даёт трудноуловимые поломки (аналог «Invalid hook call»).
+- **Подпуть — отдельный спецификатор.** `zustand/middleware` ≠ `zustand`. Каждый используемый
+  подпуть нужно добавить и в `__mdtShared` (Шаг 2), и в `SHARED_GLOBALS` (Шаг 3).
+- **`@tanstack/react-query`: единого инстанса мало.** Модуль должен обернуть своё дерево в
+  `<QueryClientProvider client={...}>`. Контекст работает именно потому, что инстанс один; сам
+  провайдер — ответственность модуля (каждый React-root монтируется отдельно через
+  `wrapComponent`/`createPageControl`).
+- **Default-импорт** (`import X from "echarts-for-react"`) работает через стандартный interop
+  Rollup; после выноса проверь в рантайме, что `X` — это сам компонент, а не неймспейс.
+- **react-семья — особый, исторический случай** (alias-шимы `SHARED_EXACT`/`SHARED_NAMES` с
+  перечислением имён). **Новые** зависимости добавляй в `SHARED_GLOBALS` — там имена перечислять не надо.
+
+---
+
+## Текущий список общих зависимостей
+
+- **react-семья** (`SHARED_EXACT`, alias-шимы): `react`, `react-dom`, `react-dom/client`,
+  `react/jsx-runtime`, `react/jsx-dev-runtime`.
+- **Externalize** (`SHARED_GLOBALS`): `@tanstack/react-query`, `zustand`, `zustand/middleware`,
+  `zustand/react/shallow`, `echarts`, `echarts-for-react`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mdt-module-builder",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"description": "Сборщик внешних UI-модулей MDT (Vite).",
 	"type": "module",
 	"bin": {
@@ -25,6 +25,7 @@
 	"dependencies": {
 		"autoprefixer": "^10.4.0",
 		"postcss": "^8.4.0",
+		"postcss-nested": "^6.2.0",
 		"tailwindcss": "^3.4.0",
 		"vite": "^6.0.0"
 	},

package/src/index.mjs

@@ -14,6 +14,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
+// postcss-плагины для компонентного CSS модуля (см. css.postcss в moduleViteConfig). Оба —
+// прямые зависимости пакета, поэтому импортим статически (нужны только при реальной сборке).
+import autoprefixer from "autoprefixer";
+import postcssNested from "postcss-nested";
 
 // Спецификаторы, которые резолвятся на единственную копию MDT через window.__mdtShared.
 export const SHARED_EXACT = ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"];
@@ -89,6 +93,45 @@ function sharedAliases(shimDir) {
 	}));
 }
 
+// Толерантный парсер tsconfig (JSONC): вырезаем // и /* */ комментарии (не трогая их внутри строк)
+// и висячие запятые, затем JSON.parse.
+function parseJsonc(text) {
+	const noComments = text.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n\r]*|\/\*[\s\S]*?\*\//g, (_m, str) => (str ? str : ""));
+	return JSON.parse(noComments.replace(/,(\s*[}\]])/g, "$1"));
+}
+
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Разворачивает tsconfig `compilerOptions.paths` модуля в resolve.alias — аналог
+// tsconfig-paths-webpack-plugin старого (webpack) билдера. Без этого Vite не резолвит алиасы вида
+// "_core/*", которыми пользуется код модуля. Берём первый target маппинга (как tsconfig-paths по
+// умолчанию); wildcard `prefix/*` → regex с захватом хвоста, точный ключ → строковый алиас.
+function tsconfigAliases(root) {
+	let json;
+	try {
+		json = parseJsonc(fs.readFileSync(path.join(root, "tsconfig.json"), "utf8"));
+	} catch {
+		return [];
+	}
+	const co = json?.compilerOptions ?? {};
+	const paths = co.paths ?? {};
+	const baseDir = path.resolve(root, co.baseUrl ?? ".");
+	const aliases = [];
+	for (const [pattern, targets] of Object.entries(paths)) {
+		const target = Array.isArray(targets) ? targets[0] : undefined;
+		if (!target) continue;
+		if (pattern.endsWith("/*") && target.endsWith("/*")) {
+			const replBase = path.resolve(baseDir, target.slice(0, -2)).replace(/\\/g, "/");
+			aliases.push({ find: new RegExp(`^${escapeRegExp(pattern.slice(0, -2))}/(.*)$`), replacement: `${replBase}/$1` });
+		} else {
+			aliases.push({ find: pattern, replacement: path.resolve(baseDir, target) });
+		}
+	}
+	return aliases;
+}
+
 // Публичный SDK MDT: спецификаторы `@mdt/<имя>` отдаются модулю как externalize. Их экспорты
 // кладёт MDT в globalThis.__mdtSdk — по одному ключу на файл папки ui/mdt-sdk (см. _register.ts).
 // Добавить публичный API = создать файл в ui/mdt-sdk; перечислять имена/спецификаторы не нужно.
@@ -171,8 +214,13 @@ export function moduleViteConfig({ root, entry, outDir, watch = false, name = "_
 		configFile: false,
 		root,
 		logLevel: "warn",
-		resolve: { alias: sharedAliases(shimDir) },
+		// react/*-шимы + tsconfig `paths` модуля (напр. "_core/*") — иначе Vite их не резолвит.
+		resolve: { alias: [...sharedAliases(shimDir), ...tsconfigAliases(root)] },
 		plugins: [cssInjectPlugin(root)],
+		// Компонентный CSS модуля (import "./x.css") гоняем через postcss-nested (Sass-подобная
+		// вложенность `&`, как старый webpack builder) + autoprefixer. Инлайн-инъекцию делает
+		// cssInjectPlugin; `@tailwind utilities` генерятся отдельно (generateModuleTailwindCss).
+		css: { postcss: { plugins: [postcssNested(), autoprefixer()] } },
 		build: {
 			outDir,
 			emptyOutDir: true,
@@ -183,10 +231,11 @@ export function moduleViteConfig({ root, entry, outDir, watch = false, name = "_
 				// (точные спецификаторы) + ics-ui-kit с сабпасами (SHARED_PREFIXES). react/* — alias-шимы; lucide бандлится.
 				external: (id) => SHARED_GLOBALS.includes(id) || isSharedPrefix(id) || id.startsWith(MDT_SDK_PREFIX),
 					// host кладёт значения в __mdtShared/__mdtSdk с флагом __esModule, поэтому
-					// interop модуля (__toESM) корректно отдаёт `.default` для default-импорта
-					// (иначе default-импорт, напр. echarts-for-react, превращается в объект-неймспейс → React
-					// «Element type is invalid … got: object»).
-					output: { globals: globalRef }
+					// interop берёт `.default` для default-импорта. rolldown (dev) делает это сам (__toESM),
+					// а Rollup (Vite 6, CI модуля) — только с output.interop:"auto"; без него default-импорт
+					// биндится ко всему объекту-неймспейсу вместо .default (MDT.Navigation === undefined,
+					// echarts-for-react → «Element type is invalid … got: object»).
+					output: { globals: globalRef, interop: "auto" }
 			},
 			lib: {
 				entry,