arui-scripts 25.0.2 → 25.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ import { type Configuration } from '@rspack/core';
2
+ export declare const rsdoctorVersion: string;
3
+ export type RsdoctorSnapshot = {
4
+ schemaVersion: 1;
5
+ rsdoctorVersion: string;
6
+ bundles: Array<{
7
+ name: string;
8
+ dataFile: string;
9
+ }>;
10
+ };
11
+ type SnapshotOutput = {
12
+ directory: string;
13
+ snapshot: RsdoctorSnapshot;
14
+ };
15
+ export declare function enableRsdoctor(configuration: Configuration | Configuration[], outputDirectory: string | undefined, sourceRoot: string): Promise<SnapshotOutput | undefined>;
16
+ export declare function normalizeWorkspacePaths(value: unknown, root: string): unknown;
17
+ export declare function writeRsdoctorSnapshot({ directory, snapshot, }: SnapshotOutput): Promise<void>;
18
+ export {};
@@ -0,0 +1,139 @@
1
+ "use strict";
2
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
+ return new (P || (P = Promise))(function (resolve, reject) {
5
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
9
+ });
10
+ };
11
+ var __importDefault = (this && this.__importDefault) || function (mod) {
12
+ return (mod && mod.__esModule) ? mod : { "default": mod };
13
+ };
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ exports.rsdoctorVersion = void 0;
16
+ exports.enableRsdoctor = enableRsdoctor;
17
+ exports.normalizeWorkspacePaths = normalizeWorkspacePaths;
18
+ exports.writeRsdoctorSnapshot = writeRsdoctorSnapshot;
19
+ const path_1 = __importDefault(require("path"));
20
+ const fs_extra_1 = __importDefault(require("fs-extra"));
21
+ // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
22
+ const { dependencies } = require('../../../package.json');
23
+ exports.rsdoctorVersion = dependencies['@rsdoctor/rspack-plugin'];
24
+ // Rsdoctor reads source maps at this processAssets stage to attribute bundled code to modules.
25
+ const RSDOCTOR_SOURCE_MAPS_STAGE = 2400;
26
+ const PLUGIN_NAME = 'AruiRsdoctorSourceMaps';
27
+ /**
28
+ * Не дает Rsdoctor менять production source maps.
29
+ * Увидев devtool, Rsdoctor переписывает devtoolModuleFilenameTemplate на абсолютные пути,
30
+ * поэтому он подключается со скрытым devtool. Чтобы он все равно сопоставил код с модулями,
31
+ * картам на время его чтения выставляется абсолютный sourceRoot, затем они восстанавливаются.
32
+ */
33
+ function keepSourceMaps(rsdoctor, sourceRoot) {
34
+ return {
35
+ apply(compiler) {
36
+ /* eslint-disable no-param-reassign */
37
+ const { devtool } = compiler.options;
38
+ compiler.options.devtool = false;
39
+ rsdoctor.apply(compiler);
40
+ compiler.options.devtool = devtool;
41
+ /* eslint-enable no-param-reassign */
42
+ const { RawSource } = compiler.webpack.sources;
43
+ compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
44
+ const originals = new Map();
45
+ compilation.hooks.processAssets.tap({ name: PLUGIN_NAME, stage: RSDOCTOR_SOURCE_MAPS_STAGE - 1 }, () => {
46
+ compilation.getAssets().forEach(({ name, source }) => {
47
+ if (!name.endsWith('.map')) {
48
+ return;
49
+ }
50
+ const map = JSON.parse(source.source().toString());
51
+ originals.set(name, source);
52
+ compilation.updateAsset(name, new RawSource(JSON.stringify(Object.assign(Object.assign({}, map), { sourceRoot }))));
53
+ });
54
+ });
55
+ compilation.hooks.processAssets.tap({ name: PLUGIN_NAME, stage: RSDOCTOR_SOURCE_MAPS_STAGE + 1 }, () => {
56
+ originals.forEach((source, name) => compilation.updateAsset(name, source));
57
+ originals.clear();
58
+ });
59
+ });
60
+ },
61
+ };
62
+ }
63
+ function enableRsdoctor(configuration, outputDirectory, sourceRoot) {
64
+ return __awaiter(this, void 0, void 0, function* () {
65
+ if (!outputDirectory) {
66
+ return undefined;
67
+ }
68
+ const directory = path_1.default.resolve(outputDirectory);
69
+ const configurations = Array.isArray(configuration) ? configuration : [configuration];
70
+ const names = configurations.map((config, index) => config.name || (index === 0 ? 'main' : `client-${index}`));
71
+ if (new Set(names).size !== names.length) {
72
+ throw new Error('Rsdoctor requires unique client configuration names');
73
+ }
74
+ // Remove the completion marker before compiling so a failed build cannot reuse an old snapshot.
75
+ yield fs_extra_1.default.remove(path_1.default.join(directory, 'index.json'));
76
+ yield Promise.all(configurations.map((_, index) => fs_extra_1.default.remove(path_1.default.join(directory, `client-${index}/rsdoctor-data.json`))));
77
+ const { RsdoctorRspackPlugin } = yield import('@rsdoctor/rspack-plugin');
78
+ const bundles = configurations.map((config, index) => {
79
+ const reportDir = path_1.default.join(directory, `client-${index}`);
80
+ // eslint-disable-next-line no-param-reassign
81
+ config.plugins = [
82
+ ...(config.plugins || []),
83
+ keepSourceMaps(new RsdoctorRspackPlugin({
84
+ disableClientServer: true,
85
+ // Loader probes change module identifiers and therefore production module ids.
86
+ features: ['bundle'],
87
+ // Collect report data without adding new compilation warnings or quality gates.
88
+ linter: { level: 'Ignore' },
89
+ output: {
90
+ mode: 'brief',
91
+ reportDir,
92
+ reportCodeType: 'noCode',
93
+ options: { type: ['json'] },
94
+ },
95
+ }), sourceRoot),
96
+ ];
97
+ return { name: names[index], dataFile: `client-${index}/rsdoctor-data.json` };
98
+ });
99
+ return { directory, snapshot: { schemaVersion: 1, rsdoctorVersion: exports.rsdoctorVersion, bundles } };
100
+ });
101
+ }
102
+ // Jenkins builds use different absolute workspace paths. Rsdoctor matches modules by path.
103
+ function normalizeWorkspacePaths(value, root) {
104
+ if (Array.isArray(value)) {
105
+ return value.map((item) => normalizeWorkspacePaths(item, root));
106
+ }
107
+ if (!value || typeof value !== 'object') {
108
+ return value;
109
+ }
110
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => {
111
+ if (['path', 'root', 'file', 'filename', 'resource', 'resolved'].includes(key) &&
112
+ typeof item === 'string') {
113
+ if (item === root) {
114
+ return [key, '.'];
115
+ }
116
+ if (item.startsWith(`${root}/`) || item.startsWith(`${root}\\`)) {
117
+ return [key, `./${item.slice(root.length + 1).replace(/\\/g, '/')}`];
118
+ }
119
+ }
120
+ return [key, normalizeWorkspacePaths(item, root)];
121
+ }));
122
+ }
123
+ function writeRsdoctorSnapshot(_a) {
124
+ return __awaiter(this, arguments, void 0, function* ({ directory, snapshot, }) {
125
+ var _b, _c, _d;
126
+ for (const bundle of snapshot.bundles) {
127
+ const file = path_1.default.join(directory, bundle.dataFile);
128
+ // eslint-disable-next-line no-await-in-loop
129
+ const report = yield fs_extra_1.default.readJson(file);
130
+ if (typeof ((_b = report.data) === null || _b === void 0 ? void 0 : _b.root) !== 'string' ||
131
+ !Array.isArray((_d = (_c = report.data) === null || _c === void 0 ? void 0 : _c.chunkGraph) === null || _d === void 0 ? void 0 : _d.assets)) {
132
+ throw new Error(`Invalid Rsdoctor data: ${file}`);
133
+ }
134
+ // eslint-disable-next-line no-await-in-loop
135
+ yield fs_extra_1.default.writeJson(file, normalizeWorkspacePaths(report, report.data.root));
136
+ }
137
+ yield fs_extra_1.default.writeJson(path_1.default.join(directory, 'index.json'), snapshot, { spaces: 2 });
138
+ });
139
+ }
package/docs/cli.md CHANGED
@@ -20,6 +20,6 @@ npx create-arui-scripts-app my-app
20
20
 
21
21
  Полный список и описание — в [docs/commands.md](commands.md):
22
22
  `start`, `start:prod`, `build`, `docker-build`, `docker-build:compiled`, `test`, `test:vitest`,
23
- `archive-build`, `bundle-analyze`, `ensure-yarn`, `changelog`.
23
+ `archive-build`, `bundle-analyze`, `bundle-diff`, `ensure-yarn`, `changelog`.
24
24
 
25
25
  При production-сборке можно включить [проверку размера начального JS и CSS](settings.md#buildsizebudgets). Лимиты задаются через `buildSizeBudgets`; их превышение завершает сборку с ненулевым кодом.
package/docs/commands.md CHANGED
@@ -182,3 +182,75 @@ arui-scripts archive-build
182
182
  Так же при запуске будет генерироваться [stats-файл](https://webpack.js.org/api/stats/), который можно использовать в
183
183
  [сторонних](http://webpack.github.io/analyse/) инструментах, например для понимания почему тот или иной модуль попал в бандл.
184
184
  По умолчанию файл будет писаться в `.build/stats.json`, вы можете поменять это через отдельную [настройку statsOutputFilename](settings.md#statsOutputFilename).
185
+
186
+ ## bundle-diff
187
+
188
+ Генерирует [Rsdoctor Bundle Diff](https://rsdoctor.rs/guide/usage/bundle-diff) для двух production сборок клиента:
189
+ HTML отчеты, JSON diff, таблицу размеров `summary.json` и markdown комментарий для pull request `comment.md`.
190
+
191
+ Команду можно запускать локально или в CI/CD:
192
+ для сравнения достаточно подготовить каталоги snapshot.
193
+ При запуске в CI/CD получение baseline, публикацию отчетов и комментария в pull request нужно настроить в пайплайне CI/CD.
194
+
195
+ ### Сохранение данных production сборки
196
+
197
+ ```bash
198
+ ARUI_SCRIPTS_RSDOCTOR_OUTPUT=rsdoctor/current yarn build
199
+ ```
200
+
201
+ `yarn build` должен запускать `arui-scripts build`. Rsdoctor подключается к тем же production конфигурациям клиента, отдельная пересборка не нужна, серверные бандлы не учитываются.
202
+ Rsdoctor собирает только данные о бандле и не меняет результат сборки: JS, CSS и source maps совпадают со сборкой без этой переменной.
203
+ Встроенные lint правила Rsdoctor отключены, поэтому сбор данных не добавляет предупреждений. Обычный `bundle-analyze` сохраняет свое интерактивное поведение.
204
+
205
+ ### Сравнение
206
+
207
+ Перед запуском сравнения подготовьте snapshot нужного коммита целевой ветки в каталоге `rsdoctor/baseline`.
208
+ Команда `bundle-diff` не создает этот каталог и не скачивает baseline автоматически.
209
+ Подробнее процесс описан в разделе «Использование в CI».
210
+
211
+ ```bash
212
+ yarn arui-scripts bundle-diff \
213
+ --current rsdoctor/current \
214
+ --baseline rsdoctor/baseline \
215
+ --output rsdoctor/diff \
216
+ --report-url https://artifacts.example/reports/build-123/ \
217
+ --current-label 'feature/form @ current-sha' \
218
+ --baseline-label 'develop @ baseline-sha'
219
+ ```
220
+
221
+ | Опция | Назначение |
222
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
223
+ | `--current <directory>` | Обязательный каталог текущего snapshot с `index.json` |
224
+ | `--baseline <directory>` | Каталог базового snapshot; если он не передан, не содержит snapshot или собран другой версией Rsdoctor, выводятся текущие размеры и причина |
225
+ | `--output <directory>` | Каталог результата; по умолчанию `rsdoctor/diff` |
226
+ | `--report-url <url>` | URL, по которому будет опубликован каталог `--output`; без него ссылки на HTML отчеты относительные |
227
+ | `--current-label <label>` | Ветка/коммит текущей сборки для комментария |
228
+ | `--baseline-label <label>` | Ветка/коммит базовой сборки для комментария |
229
+
230
+ Метрики Total Size / JavaScript / CSS / HTML / Other Assets используют правила Rsdoctor (emitted assets, без source maps и LICENSE). Other Assets объединяет изображения, шрифты, медиа и прочие файлы.
231
+ Предсжатые копии `.gz` и `.br` в таблицу не входят, потому что дублируют те же JS и CSS; в HTML отчете Rsdoctor они видны отдельными assets.
232
+ Для нескольких клиентов таблица суммирует размеры их outputs; одинаковый файл в двух outputs учитывается дважды.
233
+
234
+ Для каждого общего имени клиента создаются `client-N.html` и `client-N.json`. Новые и удалённые конфигурации учитываются в итоговой таблице и отмечаются в комментарии; для них парного HTML diff нет. JSON содержит native diff assets/modules/packages. При нулевом baseline рост отмечается как `new`, без бесконечного процента.
235
+
236
+ Поврежденные данные, несовместимый текущий snapshot и ошибки генерации завершают команду с ненулевым кодом.
237
+
238
+ Каждый snapshot содержит версию формата (`schemaVersion`) и версию Rsdoctor (`rsdoctorVersion`).
239
+ Для сравнения оба snapshot должны быть созданы с той же версией Rsdoctor, которую использует команда,
240
+ и иметь поддерживаемую версию формата.
241
+
242
+ Изменение версии `arui-scripts` само по себе не делает snapshot несовместимыми.
243
+ Если версия Rsdoctor или формат snapshot изменились, baseline необходимо пересобрать
244
+ с совместимой версией Rsdoctor и поддерживаемым форматом.
245
+
246
+ ### Использование в CI
247
+
248
+ В пайплайне вашего CI/CD настройте сохранение и скачивание snapshot, публикацию отчетов
249
+ и обновление комментария в pull request. Эти действия выполняются вне команды `bundle-diff`.
250
+
251
+ 1. В сборке каждой ветки сохраняйте snapshot как артефакт, привязанный к SHA коммита.
252
+ 2. В сборке pull request скачайте snapshot последнего коммита целевой ветки в каталог baseline. Snapshot другого коммита подставлять не стоит: сравнение покажет чужие изменения. Если snapshot не найден, все равно запускайте команду: комментарий покажет текущие размеры и объяснит, что нужна сборка целевой ветки.
253
+ 3. Запустите `bundle-diff` с `--report-url`, указывающим, куда будет опубликован каталог `--output`, и опубликуйте этот каталог.
254
+ 4. Опубликуйте `comment.md` комментарием в pull request. При повторных запусках удобно обновлять прежний комментарий, найдя его по заголовку `Rsdoctor Bundle Diff Analysis`.
255
+
256
+ HTML отчет — самодостаточный файл со встроенным JavaScript. Если хранилище артефактов запрещает выполнение скриптов, отчет можно скачать и открыть локально.
package/docs/modules.md CHANGED
@@ -1058,3 +1058,46 @@ type GetResourcesRequest<GetResourcesParams = void> = {
1058
1058
  params: GetResourcesParams; // параметры, которые передаются в функцию получения ресурсов модуля
1059
1059
  };
1060
1060
  ```
1061
+
1062
+ # Контекст готовности и ошибок модуля
1063
+
1064
+ `mount`, `hydrate` и `update` получают опциональный четвёртый аргумент
1065
+ `ModuleLifecycleContext` с `signal`, `reportReady()` и `reportError(error)`.
1066
+ Старые модули продолжают работать без изменений. Чтобы хост ожидал явную готовность,
1067
+ добавьте к экспорту модуля `readiness: 'explicit'` и вызывайте
1068
+ `context?.reportReady()` после инициализации приложения. Контекст может отсутствовать
1069
+ при запуске в старом хосте. Без `readiness` готовность определяется завершением
1070
+ `mount` / `hydrate`, включая возвращённый Promise.
1071
+
1072
+ На хосте доступны `onReady`, `onError({ error, stage })` и `readyTimeoutMs`:
1073
+ в параметрах `useModuleMounter`, в настройках фабрики `createLazyMounter` или в props
1074
+ `ModuleComponent` от `createSsrMounter`. Таймаут по умолчанию отключён и применяется
1075
+ только к явной готовности. `reportError` сообщает фатальную ошибку экземпляра,
1076
+ останавливает его обновления и запускает cleanup. Внутренний Error Boundary React-модуля
1077
+ может передавать ошибки в этот callback; внешний Boundary хоста не видит другой root.
1078
+
1079
+ [Подробный контракт, примеры и правила очистки](../../arui-scripts-modules/README.md#готовность-и-ошибки-экземпляра-модуля).
1080
+
1081
+
1082
+ # Готовый адаптер React-модуля
1083
+
1084
+ Ручные `mount`, `hydrate`, `update`, `unmount` можно заменить на
1085
+ `createReactModule` из `@alfalab/scripts-modules/react`:
1086
+
1087
+ ```tsx
1088
+ import { createReactModule } from '@alfalab/scripts-modules/react';
1089
+ import { App } from './app';
1090
+
1091
+ export default createReactModule({ Component: App });
1092
+ ```
1093
+
1094
+ App получает props `{ runParams, serverState }`. Хелпер создаёт отдельный root для
1095
+ каждого контейнера, сохраняет состояние при update, гидрирует серверный HTML и
1096
+ сообщает ошибки через внутренний Error Boundary. Нужны React и ReactDOM 18+.
1097
+
1098
+ По умолчанию готовность наступает после первого commit, в том числе с Suspense
1099
+ fallback. Для ожидания данных задайте `readiness: 'explicit'` и вызовите в App
1100
+ `useModuleReady(data.status === 'success')`. Готовность отправляется один раз после
1101
+ commit с истинным условием. На сервере можно рендерить обычный App без обёрток хелпера.
1102
+
1103
+ [Подробные примеры и контракт](../../arui-scripts-modules/README.md#react-хелпер-модуля).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arui-scripts",
3
- "version": "25.0.2",
3
+ "version": "25.1.1",
4
4
  "main": "./build/index.js",
5
5
  "typings": "./build/index.d.ts",
6
6
  "exports": {
@@ -22,7 +22,7 @@
22
22
  "homepage": "https://github.com/core-ds/arui-scripts#readme",
23
23
  "bin": "./build/bin/index.js",
24
24
  "dependencies": {
25
- "@alfalab/arui-scripts-artifacts": "^1.0.0",
25
+ "@alfalab/arui-scripts-artifacts": "^1.0.1",
26
26
  "@alfalab/postcss-custom-properties": "^9.1.2",
27
27
  "@babel/core": "7.29.7",
28
28
  "@babel/plugin-proposal-decorators": "^7.29.7",
@@ -47,7 +47,10 @@
47
47
  "@babel/runtime": "^7.29.7",
48
48
  "@module-federation/runtime-tools": "^2.0.0",
49
49
  "@pmmmwh/react-refresh-webpack-plugin": "0.6.2",
50
+ "@rsdoctor/cli": "1.6.4",
51
+ "@rsdoctor/client": "1.6.4",
50
52
  "@rsdoctor/rspack-plugin": "1.6.4",
53
+ "@rsdoctor/utils": "1.6.4",
51
54
  "@rspack/cli": "2.2.5",
52
55
  "@rspack/core": "2.2.5",
53
56
  "@rspack/dev-server": "2.2.1",
@@ -124,7 +127,7 @@
124
127
  "ts-jest": "29.1.0",
125
128
  "ts-loader": "9.4.4",
126
129
  "ts-node": "10.9.2",
127
- "vite": "^8.3.1",
130
+ "vite": "^8.3.3",
128
131
  "vite-tsconfig-paths": "^6.1.1",
129
132
  "vitest": "^5.0.2",
130
133
  "webpack-bundle-analyzer": "4.10.2",
@@ -132,6 +135,7 @@
132
135
  "webpack-node-externals": "3.0.0"
133
136
  },
134
137
  "devDependencies": {
138
+ "@rsdoctor/types": "1.6.4",
135
139
  "@types/assets-webpack-plugin": "6.1.2",
136
140
  "@types/case-sensitive-paths-webpack-plugin": "2.1.6",
137
141
  "@types/compression-webpack-plugin": "4.0.1",
@@ -187,7 +191,7 @@
187
191
  "tsconfig": "tsconfig-local.json"
188
192
  }
189
193
  ],
190
- "/node_modules/@rspack/.+\\.(mjs|js)$": [
194
+ "/node_modules/.+\\.(mjs|js)$": [
191
195
  "babel-jest",
192
196
  {
193
197
  "presets": [
@@ -208,7 +212,7 @@
208
212
  ]
209
213
  },
210
214
  "transformIgnorePatterns": [
211
- "/node_modules/(?!@rspack/)"
215
+ "/node_modules/(?!@rspack/|@rsdoctor/|rslog/|strip-ansi/|ansi-regex/)"
212
216
  ]
213
217
  }
214
218
  }