Синхронизация 1c-metadata-manage с апстримом cc-1c-skills (без Python…

[uasy]

Синхронизация 1c-metadata-manage с апстримом cc-1c-skills (без Python-рантайма)

Тип: багфиксы + портирование новых возможностей + актуализация документации
Статус: протестировано на отдельной машине (Windows 10, платформа 1С 8.3.27.2074, база УТ 11) — готово к коммиту и открытию PR

Итог

content/skills/1c-metadata-manage/ — это самостоятельный (не сгенерированный) даунстрим-порт скиллов из апстрима cc-1c-skills под диспетчерскую архитектуру ai_rules_1c (один SKILL.md + docs/*.md + tools/1c-*/scripts/*.ps1, только PowerShell). Со временем апстрим ушёл вперёд: багфиксы, новая подсистема защиты объектов «на поддержке», движок ibcmd, значительно разросшийся DSL form-compile, поддержка .dt, множественные значения по умолчанию в СКД. Часть документации при этом отстала от уже реализованного в скриптах кода.

Этот PR закрывает разрыв: 53 изменённых файла + 18 новых, порт выполнен вручную по построчному диффу апстрима.

Не входит в этот PR: портирование Python-рантайма (.py-твины инструментов + регэксп-переключатель docs/*.md).

---

1. Критичные багфиксы

Порча данных при повторной работе с уже созданными объектами — не новая функциональность, а исправление существующего поведения.

• tools/1c-cfe-manage/scripts/cfe-borrow.ps1 — портирован целиком с актуальной версии cc (v1.8). До фикса повторное заимствование (re-borrow) объекта расширения:
  • затирало уже написанный код в Module.bsl пустым файлом;
  • генерировало новый [guid]::NewGuid() для формы вместо переиспользования старого — ломало стабильность идентичности формы между запусками;
  • задваивало реквизиты/табличные части в ChildObjects (не было дедупликации);
  • глобальный -replace по </ExtendedConfigurationObject> портил XML, если у объекта уже были заимствованные реквизиты (задевал не тот узел — заменён на анкер к первому вхождению);
  • не умело заимствовать «глубокие» пути через табличную часть (Объект.<ТЧ>.<Колонка>.<Sub>);
  • сканировало более узкий набор тегов привязки формы, чем апстрим (не было FooterDataPath, HeaderDataPath, MultipleValueDataPath и др.).
• tools/1c-form-scaffold/scripts/remove-form.ps1 — после удаления формы с назначением ≠ Object могла остаться битая ссылка на Default*Form (List/Choice/Record) — чистился только DefaultForm. Теперь сканируется любой узел *Form.
• tools/1c-form-validate/scripts/form-validate.ps1 — добавлены проверки уникальности имён (элементы/реквизиты/колонки ТЧ/команды/параметры формы: два элемента с одинаковым именем и разными ID раньше проходили валидацию молча) и расширенная DataPath-валидация (кроме основного DataPath теперь проверяются TitleDataPath/FooterDataPath/HeaderDataPath/MultipleValueDataPath/MultipleValuePresentDataPath/RowPictureDataPath/MultipleValuePictureDataPath).
• Путь автовалидации в 5 write-скриптах — tools/1c-cf-manage/scripts/cf-edit.ps1, tools/1c-interface-manage/scripts/interface-edit.ps1, tools/1c-subsystem-manage/scripts/{subsystem-edit,subsystem-compile}.ps1, tools/1c-meta-edit/scripts/meta-edit.ps1. Относительный путь к соседнему X-validate.ps1 был скопирован из раскладки апстрима (скиллы — соседние папки), но в ai_rules_1c инструменты сгруппированы иначе, поэтому Test-Path резолвился за пределы каталога инструмента и молча падал — автовалидация тихо пропускалась на каждом вызове. Пути поправлены и проверены realpath -m + test -f на фактическое разрешение файла.
• tools/1c-web-ops/scripts/web-publish.ps1 и весь блок ibcmd (см. §3) — автоопределение версии платформы сортировало кандидатов строково (FullName), а не как [version] — на многоверсионной машине строка "8.3.9" больше "8.3.23", то есть могла выбраться не та версия платформы. Исправлено на версийную сортировку везде, где встречался паттерн.

2. Support-guard — защита объектов «на поддержке» (адаптировано под .dev.env)

Апстрим добавил подсистему защиты от правки объектов, находящихся «на поддержке»/«на замке» у поставщика — до этого PR в ai_rules_1c её не было вообще (ни одного следа ParentConfigurations/editingAllowedCheck).

Новое:

• tools/_shared/support-guard.ps1 — общий helper (в апстриме логика дублирована по ~20 скриптам, здесь — централизована в одном месте). Экспортирует Assert-EditAllowed (write-guard, блокирует/предупреждает перед записью в объект на поддержке) и Get-SupportStatusForPath (read-only статус для info-команд). Парсинг Ext/ParentConfigurations.bin перенесён из cc как есть.
• tools/1c-support-edit/scripts/support-edit.ps1 — новый инструмент, порт из cc почти без изменений. Переключает состояние поддержки (-Set editable|off-support|locked, -Capability on|off).
• content/skills/1c-metadata-manage/docs/support-manage.md — новая дока: формат .bin, алгоритм guard'а, описание support-edit.
• .dev.env.example — новый параметр SUPPORT_EDIT_POLICY=deny|warn|off (по умолчанию deny, в стиле уже существующего NEW_OBJECTS_IN).
• content/skills/1c-metadata-manage/SKILL.md — новая строка диспетчерской таблицы → support-manage.md.

Write-guard встроен в 16 скриптов (cf-edit, role-compile, subsystem-compile, subsystem-edit, interface-edit, add-template, add-help, meta-compile, meta-edit, meta-remove, form-add, form-compile, form-edit, skd-compile, skd-edit, mxl-compile), read-only статус-строка — в 7 (role-info, subsystem-info, mxl-info, skd-info, form-info — через общий helper; meta-info, cf-info — оставлены как самодостаточный перенос из cc, см. §5).

3. ibcmd — headless-движок сборки/БД

Порт поддержки ibcmd.exe как альтернативы 1cv8.exe (headless, без Дизайнера) + Invoke-IbcmdProcess (неинтерактивный запуск: закрытый stdin, декодирование cp866). Задействовано в 12 файлах: tools/1c-epf-build/scripts/{epf-build,stub-db-create}.ps1, tools/1c-epf-dump/scripts/epf-dump.ps1, tools/1c-db-ops/scripts/{db-create,db-dump-cf,db-dump-xml,db-load-cf,db-load-git,db-load-xml,db-run,db-update}.ps1, tools/1c-web-ops/scripts/web-publish.ps1.

Обход .v8-project.json (Find-ProjectV8Path) сознательно не перенесён — в проекте -V8Path уже явный параметр, который заполняет вызывающий агент из .dev.env/PLATFORM_PATH; сама функция и её вызовы вычищены при переносе.

4. Новые инструменты

• db-dump-dt / db-load-dt — выгрузка/загрузка ИБ целиком (конфигурация + данные) в .dt через ibcmd. Новые разделы 9–10 в docs/db-manage.md, db-load-dt явно помечен как необратимая операция (в стиле уже имевшихся предупреждений для db-load-cf/db-load-xml).
• form-decompile — Form.xml → JSON-черновик, совместимый с form-compile (не lossless round-trip, явно падает на сложных случаях: ConditionalAppearance со scope, дизайн-тайм chart/planner). Даёт scaffold-by-example и структурный рефакторинг существующих форм — раньше такая возможность была только у MXL/СКД decompile. Новый раздел «3a. Decompile» в docs/form-manage.md, ключевое слово decompile добавлено в диспетчерскую таблицу SKILL.md.

5. form-compile — 11 новых DSL-модулей

tools/1c-form-compile/scripts/form-compile.ps1 заменён целиком версией апстрима (v1.23 → v1.174, 3389 → 6683 строк) поверх — только правка support-guard (§2). Базовый DSL-слой (input/checkbox/radio/label/group/table/columnGroup/pages/button/cmdBar/--from-object/пресеты) был уже в синхроне; локальных доработок ai_rules_1c в файле не было — диффом подтверждено, что перенос ничего не потерял.

Новые модули: roles-access (видимость/доступ по ролям в определении формы), dynamic-list (продвинутые параметры запроса, dataParameters, вычисляемые поля, filter/order/группировки), charts (ganttTable, chart, planner), companion-panels, command-interface, appearance (цвет/шрифт/рамка + conditionalAppearance), type-system-advanced, table-advanced, choice-params, special-fields, report-form, layout-advanced. Плюс Assert-UniqueName — валидатор дублей имён на этапе компиляции (зеркалит фикс §1 в form-validate.ps1).

Документация: 12 новых файлов tools/1c-form-compile/references/{roles-access,dynamic-list,charts,companion-panels,command-interface,appearance,type-system-advanced,table-advanced,layout-advanced,special-fields,choice-params,report-form}.md (зеркалят структуру cc) + docs/form-compile-dsl.md как таблица-указатель. Отдельно — docs/form-manage.md, раздел «Extension Forms»: код form-edit.ps1 уже поддерживал редактирование форм расширений (авто-детект по <BaseForm>, сдвиг ID на 1000000+, formEvents/elementEvents с callType Before/After/Override), но это не было задокументировано.

6. СКД — множественные значения по умолчанию

tools/1c-skd-{compile,edit,info}/scripts/*.ps1 заменены версиями апстрима + support-guard (§2). Добавлен разбор IN (a, b, c)-подобных значений по умолчанию с авто-установкой valueListAllowed=true и корректной эмиссией/удалением нескольких <value>-узлов при повторном редактировании параметра (раньше значение по умолчанию всегда было скаляром, а при повторном редактировании параметра со списком значений в XML могли оставаться осиротевшие <value>-узлы — это баг, не только недостающая фича).

Новый флаг skd-info -Name X -Raw -OutFile q.sql — текст запроса без заголовков и без лимита в 150 строк, для сценария round-trip («вытащить запрос → отредактировать → skd-edit set-query @q.sql»). Документация: docs/skd-manage.md (таблица параметров Info, пример, номера версий), tools/1c-skd-info/modes-reference.md (подраздел про -Raw и точный CLI-синтаксис round-trip).

7. Документация без изменения кода

Код уже умел, документация молчала:

• docs/meta-manage.md, tools/1c-meta-edit/{child-operations,json-dsl}.md — синтаксис составного типа ("Строка + Число(15,2) + СправочникСсылка.Контрагенты" инлайн, JSON-массив "type": [...]).
• docs/template-manage.md — тип макета DataCompositionSchema (5-й тип помимо HTML/Text/SpreadsheetDocument/BinaryData) и флаг -SetMainSKD (авто-привязка MainDataCompositionSchema).
• tools/1c-cf-manage/cf-edit-reference.md — CompatibilityMode до Version8_5_1 (обрывался на Version8_3_27); InterfaceCompatibilityMode — полный список из 7 значений (было только 3, не хватало Version8_2EnableTaxi, TaxiEnableVersion8_5, Version8_5EnableTaxi, Version8_5).
• docs/cf-manage.md — операции set-panels/set-home-page описаны как полноценные документированные операции с форматом и примерами (раньше — только упоминание в changelog-заметке); таблица Info-режима (Mode/Section/Limit/Offset/OutFile) дополнена; Init — параметры -Synonym/-Version/-Vendor/-CompatibilityMode.
• docs/web-manage.md — убраны несуществующие флаги -Force (web-stop) и -KeepApacheRunning/«или web-stop -Start» (web-unpublish) — подтверждено, что их нет в актуальных параметрах скриптов ни у cc, ни у ai_rules_1c; добавлена документация реально существующего, но не описанного флага -All у web-unpublish.ps1.

8. Мелкое

• content/skills/img-grid-analysis/scripts/overlay-grid.py — портирован целиком: валидация --cols/--rows (>0/≥0), max(1, round(...)) защита от вырожденной сетки в 0 строк, sys.stdout/stderr.reconfigure("utf-8"). Проверено python3 -m py_compile.
• docs/bsp-manage.md — не тронут, сознательно (см. §9 «Отклонения», п. 4).

---

9. Сознательные отклонения от апстрима

1. Источник политики support-guard/ibcmd — .dev.env, а не .v8-project.json. .v8-project.json в проекте только документирован (db-manage.md), но ни один скрипт его не читает — конфигурацию резолвит вызывающий агент, а не PowerShell, и -V8Path уже явный параметр. Поэтому: (а) Find-ProjectV8Path/Find-V8Project не портировались вообще; (б) новый параметр SUPPORT_EDIT_POLICY добавлен в .dev.env.example; (в) tools/_shared/support-guard.ps1 читает .dev.env тем же алгоритмом обхода каталогов вверх по дереву, что апстрим использовал для .v8-project.json, но по плоскому KEY=value, а не JSON.
2. Support-guard централизован в один общий helper, а не задублирован по 16 скриптам, как в апстриме (дублирование в апстриме — известный антипаттерн, здесь сознательно не унаследован).
3. meta-info.ps1 и cf-info.ps1 не переведены на общий helper. Их собственные read-only статус-функции самодостаточны и не зависят от .dev.env/.v8-project.json, перенесены из cc как есть. Централизация была бы чисто косметической (DRY) ценой смены способа получения UUID объекта (из уже распарсенного XML-атрибута → повторный walk-up дерева) без возможности проверить это исполнением — решили не рисковать в рамках этого PR.
4. docs/bsp-manage.md — параметр МассивЦелевыхОбъектов (текущий у ai_rules_1c) сохранён вместо апстримного ОбъектыНазначенияМассив. По оценке отчёта он ближе к реальному контракту диспетчера БСП «Дополнительные отчёты и обработки»; менять нечего до появления более сильного сигнала (например, прямой сверки с исходником БСП).
5. Идиома VRD-схемы в web-publish.ps1 (enableStandardOdata как атрибут <point> у ai_rules_1c против дочернего элемента <standardOdata enable="true"/> у cc) — не перенесена, отчёт не подтвердил, какой вариант канонический для платформы.

10. Тестирование

Проведено на отдельной машине (Windows 10, PowerShell 5.1, платформа 1С 8.3.27.2074, база — base/ut.dt ≈ 2.1 ГБ, выгрузка XML в src/ut/, исходники ai_rules_1c в install/ai_rules_1c/).

#	Проверка	Результат
1	Синтаксис 66 .ps1-файлов (PSParser::Tokenize, явный UTF-8)	✅
2	Support-guard: deny без .dev.env → exit 1; warn → предупреждение, exit 0; off → тихо, exit 0; support-edit -Set editable снимает блокировку	✅ (4/4 сценария)
3	cfe-borrow повторное заимствование формы: код в Module.bsl сохранён, форма не задвоилась в ChildObjects	✅
4	cf-edit автовалидация (modify-property Comment → cf-validate запускается автоматически, Validation OK)	✅
5	form-compile новые DSL (roles-access + charts) → form-validate → Validation OK (11 checks)	✅
6	skd-edit multi-value параметр: add-parameter со списком → modify-parameter → ровно 2 <value>, осиротевших нет	✅
7	db-dump-dt / db-load-dt через ibcmd: load 2102 МБ → база 5610 МБ → dump обратно 2117 МБ (<1% расхождение, ожидаемо после перестройки индексов)	✅
8	Регрессия: Assert-EditAllowed на объекте без Ext/ParentConfigurations.bin → exit 0, вывод пуст	✅
9	Выгрузка/сборка расширения, CFE-roundtrip (db-dump-cf → db-load-cf → db-update → db-dump-cf)	✅
10	Выгрузка/сборка расширения, XML-roundtrip (db-dump-xml -Mode Full → db-load-xml → db-update → db-dump-cf)	✅

Попутно найден и исправлен баг самого патча: tools/_shared/support-guard.ps1 был сохранён без UTF-8 BOM — PowerShell 5.1 при dot-source читает файл без BOM в системной кодировке (CP1252), кириллица в строковых литералах вызывала parse error. Файл пересохранён с BOM (у остальных .ps1 в патче BOM уже был).

11. Объём изменений

53 изменённых файла, 18 новых (полный список путей — git status в install/ai_rules_1c или разделы 1–8 выше). Untouched-подтверждено: erf-*/epf-bsp-* (doc-only обёртки, уже в синхроне), web-test (осознанно вынесен на 1c-tester), img-grid-analysis skill wrapper (уже установлен, порт — только внутренний скрипт, см. §8).

12. Не вошло / следующие шаги

• Python-рантайм (.py-твины инструментов + docs/*.md-переключатель) — намеренно не в этом PR. Требует отдельного решения по раскладке папок и по конвенции параметров окружения (.dev.env vs .v8-project.json), не механический перенос.
• Пункт §9.5 (идиома VRD-схемы web-publish.ps1) оставлен открытым — нужна независимая проверка, какой вариант канонический для платформы, прежде чем унифицировать.