@seafteam/seaf-archtool-core-plugin-suite 2026.31.0 → 2026.32.0

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.
@@ -75,6 +75,123 @@ imports:
75
75
  Выбранная архитектура привязана к вкладке (в разных вкладках можно открыть разные архитектуры). В Url проставляется параметр выбранной архитектуры, что позволяет ей делиться.
76
76
 
77
77
 
78
+ ## Общий манифест (common)
79
+
80
+ Кроме списка `imports`, root манифест может объявить общий манифест — содержимое, которое подмешивается
81
+ к манифесту **каждой** архитектуры на путях чтения (расчёт датасетов, меню, валидаторы). Пути записи в
82
+ него не ведут: сохранение через put-content всегда уходит в манифест конкретной архитектуры.
83
+
84
+ Общий манифест загружается под зарезервированными `alias: common` и `permission: __common` — использовать
85
+ эти значения в `imports` нельзя, root манифест с ними будет отклонён.
86
+
87
+ ### Форма 1: просто путь
88
+
89
+ ```yaml
90
+ common: master_permissions/common.yaml
91
+ ```
92
+
93
+ ### Форма 2: объект с архитектурными пакетами
94
+
95
+ ```yaml
96
+ common:
97
+ root: master_permissions/common.yaml
98
+ packages:
99
+ - root: seaf-common/package.yaml
100
+ id: seaf-common
101
+ version: "1.11.0"
102
+ - root: eco_facades/package.yaml
103
+ id: eco_facades
104
+ version: ">=1.0.0 <2.0.0"
105
+ ```
106
+
107
+ | Название | Обязательность | Описание |
108
+ |--------------------|----------------|-----------------------------------------------------------------------------------------------------------------------|
109
+ | root | Нет | Путь к файлу общего манифеста — произвольное содержимое, как в форме 1 |
110
+ | packages | Нет | Список архитектурных пакетов, из которых собирается общий манифест |
111
+ | packages[].root | Да | Путь к манифесту пакета |
112
+ | packages[].id | Да | Идентификатор пакета — должен совпадать с идентификатором в разделе `$package` этого пакета |
113
+ | packages[].version | Да | Ожидаемая версия пакета: диапазон semver. **Всегда пишите в кавычках** — см. ниже |
114
+
115
+ `root` и `packages` не исключают друг друга: общий манифест собирается из всех перечисленных корней —
116
+ сначала `root`, затем пакеты в порядке объявления. Порядок значим: при совпадении путей выигрывает
117
+ источник, объявленный позже, то есть пакет перекрывает `root`.
118
+
119
+ Дубли между корнями не отсеиваются: если один и тот же файл достижим из нескольких корней, он
120
+ загружается заново на каждый из них и мёржится по тому же правилу — выигрывает корень, объявленный
121
+ позже. На результат это обычно не влияет, потому что содержимое одинаковое, но лишние загрузки
122
+ стоят времени, поэтому общие для нескольких пакетов файлы лучше выносить в отдельный пакет и
123
+ подключать один раз.
124
+
125
+ ### Версии пакетов пишутся в кавычках
126
+
127
+ **Рекомендация: всегда пишите `version` в кавычках** — даже там, где YAML и без них разберёт значение
128
+ как строку. Тогда не нужно помнить, в каких случаях незакавыченная версия превратится в число и root
129
+ манифест не загрузится.
130
+
131
+ `version` обязана быть строкой. Кавычки сами по себе не проверяются — проверяется, чем значение
132
+ оказалось после разбора YAML. Если YAML разобрал его как число, root манифест будет отклонён:
133
+
134
+ ```yaml
135
+ version: "1.11.0" # правильно
136
+ version: ">=1.0.0 <2.0.0"
137
+ version: 1.11.0 # загрузится (три части YAML разбирает как строку), но не рекомендуется
138
+ version: 1.10 # ошибка: число, root манифест не загрузится
139
+ version: 1 # ошибка: число, root манифест не загрузится
140
+ ```
141
+
142
+ Причина в YAML: незакавыченную версию из одной или двух частей он разбирает как число, а число
143
+ `1.10` — это то же самое, что `1.1`. Для semver это разные требования: диапазон `1.1` не покрывает
144
+ версию `1.10.0`, а `1.10` не покрывает `1.1.0`. Молча подставить одно вместо другого хуже, чем
145
+ отвергнуть манифест, поэтому нестроковая `version` считается ошибкой:
146
+
147
+ ```text
148
+ Error in root manifest: common.packages[0] must have a non-empty 'version' property (quoted string, e.g. '1.11.0')
149
+ ```
150
+
151
+ Версия из трёх частей (`1.11.0`) и диапазоны вида `^1.10`, `~1.10`, `1.x` числом быть не могут, поэтому
152
+ и без кавычек остаются строкой и принимаются. Это не повод опускать кавычки: запись без них легко
153
+ по ошибке сократить до `1.10` или `1`, и root манифест перестанет загружаться.
154
+
155
+ ### Общий манифест можно не объявлять
156
+
157
+ Все перечисленные записи равнозначны друг другу и означают, что общего манифеста нет — архитектуры
158
+ грузятся сами по себе:
159
+
160
+ - атрибута `common` в root манифесте нет вовсе;
161
+ - `common:` без значения;
162
+ - `common: {}` — пустой объект;
163
+ - `common:` с пустым списком `packages` и без `root`.
164
+
165
+ Ошибкой ни одна из них не считается.
166
+
167
+ ### Общий манифест и ролевая модель
168
+
169
+ Общий манифест доступен только при включённой ролевой модели v2 (`VUE_APP_DOCHUB_ROLES_MODEL_V2=Y`).
170
+ Если она выключена, архитектура в root манифесте и так одна и доступна всем — подмешивать общий
171
+ манифест не к чему.
172
+
173
+ Объявленный при выключенной ролевой модели `common` не игнорируется — загрузка прерывается с ошибкой:
174
+
175
+ ```text
176
+ If the role model is disabled, the root manifest cannot declare a common manifest.
177
+ Value of VUE_APP_DOCHUB_ROLES_MODEL_V2=N
178
+ ```
179
+
180
+ Вырожденные записи из раздела выше под это правило не попадают: они равнозначны отсутствию `common`,
181
+ поэтому при выключенной ролевой модели ошибки не дают.
182
+
183
+ ### Проверка версий пакетов
184
+
185
+ Если объявлены `packages`, то после сборки общего манифеста ожидаемые версии сверяются с фактическими —
186
+ теми, что указаны в разделе `$package` самих пакетов (см. «Пакеты» в руководстве).
187
+
188
+ Несовпадение **не прерывает** загрузку: расхождения попадают в отклонения и видны в
189
+ `GET seaf-core/api/core/storage/problems` и в `GET /health/info`. Сверка различает три случая:
190
+
191
+ - пакет не найден в собранном общем манифесте;
192
+ - версия не удовлетворяет ожидаемому диапазону;
193
+ - сам диапазон задан некорректно (опечатка в root манифесте).
194
+
78
195
  ## Переменные окружения для управления ролевой моделью:
79
196
 
80
197
  | Название | Дефолт | Описание |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seafteam/seaf-archtool-core-plugin-suite",
3
- "version": "2026.31.0",
3
+ "version": "2026.32.0",
4
4
  "description": "Compiled artifacts for VSCode and JetBrains plugins",
5
5
  "author": "S.Nazarov",
6
6
  "contributors": [