From e268fbd71f1a5a31f46c60e0aa20d26a8ff46f2e Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Mon, 10 Aug 2026 18:12:47 +0300 Subject: [PATCH] =?UTF-8?q?docs(mxl):=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0?= =?UTF-8?q?=D0=BB=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BE=D0=B3=D1=80=D0=B0=D0=BD=D0=B8=D1=87=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F,=20=D1=83=D0=B1=D1=80=D0=B0=D1=82=D1=8C=20=D0=BF=D1=80?= =?UTF-8?q?=D0=BE=D1=82=D1=91=D0=BA=D1=88=D1=83=D1=8E=20=D1=80=D0=B5=D0=B0?= =?UTF-8?q?=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Раздел ограничений врал в обе стороны. Он обещал потерю областей Columns и Rectangle — они поддержаны предыдущим коммитом; и молчал про то, что теряется на самом деле. Проверено по коду обоих навыков, доли — по корпусу ERP 8.3.24: ячейки-поля ввода (53% макетов), несколько наборов колонок (63%), объединения вне ячеек (16%), рисунки (2%), цвета, скрытые строки, отступ, посторонние стили линий, группировки, колонтитулы и параметры печати. Отдельно записано, что многоязычные надписи не поддерживаются: при разборе берётся первый вариант текста, при генерации язык всегда ru — для двуязычных макетов остальные языки теряются. Заодно убрано то, что описывает реализацию, а не использование: - таблицы с точными текстами сообщений об ошибках и кодом возврата. Модель, вызвавшая навык, видит и текст, и код прямо в выводе; документировать их незачем, а протухают они молча — ровно как протух раздел ограничений. Правила, из-за которых ошибка возникает, остались; сами строки зафиксированы в кейсах через expectError, где расхождение ловится механически. В остальных пяти спеках таких таблиц и не было — там принята одна фраза «ненулевой код выхода и сообщение в stderr»; - фраза про порядок эмиссии именованных элементов: автор DSL на него не влияет. Сам факт (платформа хранит их отсортированными по имени) перенесён в docs/1c-spreadsheet-spec.md, где описывается XML-уровень, вместе с оговоркой, что случай с «ё» не проверен. Co-Authored-By: Claude Opus 5 (1M context) --- .../skills/mxl-compile/reference/dsl-spec.md | 48 +++++++++---------- docs/1c-spreadsheet-spec.md | 2 + docs/mxl-dsl-spec.md | 48 +++++++++---------- 3 files changed, 48 insertions(+), 50 deletions(-) diff --git a/.claude/skills/mxl-compile/reference/dsl-spec.md b/.claude/skills/mxl-compile/reference/dsl-spec.md index 9d9ec0fe..c5e18f77 100644 --- a/.claude/skills/mxl-compile/reference/dsl-spec.md +++ b/.claude/skills/mxl-compile/reference/dsl-spec.md @@ -138,18 +138,7 @@ ] ``` -Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. - -Ошибки (stderr, код возврата 1): - -| Условие | Сообщение | -|---------|-----------| -| нет `name` | `namedAreas: 'name' is required: …` | -| не задана ни одна ось | `namedAreas: at least one of 'rows'/'cols' is required: …` | -| список через запятую | `namedAreas: 'cols' must be a single number or range, got list "…": …` | -| диапазон задом наперёд | `namedAreas: 'rows' range is reversed "…": …` | - -Порядок именованных элементов в выходном XML — по имени: так их хранит платформа, компилятор сортирует сам. +Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. Имя обязательно, и хотя бы одна ось должна быть задана; нарушение любого из этих правил → ненулевой код выхода и сообщение в stderr. ## Строки (`rows[]`) @@ -189,14 +178,7 @@ - не выразить текст, совпадающий с `">"`, `"|"` или с шаблоном `"{...}"`; - `"|"` продолжает ячейку из предыдущей строки, только если её позиция известна явно (`col` задан или строка записана массивом). -Ошибки короткой формы (stderr, код возврата 1): - -| Условие | Сообщение | -|---------|-----------| -| `">"` без ячейки слева | `Row shorthand: '>' has no cell to the left: area "…", row N, cell M` | -| `"|"` без ячейки сверху | `Row shorthand: '|' has no cell above: area "…", row N, cell M` | -| объектный элемент с `col` | `Row shorthand: cell object must not carry 'col': area "…", row N, cell M` | -| элементов больше `columns` | `Row exceeds 'columns' (K): area "…", row N` | +`">"` без ячейки слева, `"|"` без ячейки сверху, объектный элемент с `col`, элементов больше `columns` → ненулевой код выхода и сообщение в stderr. ## Ячейки (`cells[]`) @@ -227,8 +209,24 @@ ## Ограничения -Текущая версия не поддерживает: -- Множественные наборы колонок (`columnsID`) -- Области типа Columns / Rectangle -- Рисунки (штрихкоды, картинки) -- Фон ячеек +DSL описывает не все конструкции табличного документа. Перечисленное ниже **теряется при +round-trip** (`/mxl-decompile` → `/mxl-compile`): в JSON оно не попадает, в сгенерированный +XML не возвращается. Доля — по корпусу типовой ERP 8.3.24 (10 924 макета), где измерялась. + +| Конструкция | Доля макетов | +|-------------|--------------| +| Ячейки-поля ввода (`containsValue` / `valueType` / `controlType`) | 53% | +| Несколько наборов колонок (`columnsID`) — свои ширины у группы строк | 63% | +| Объединения, не привязанные к ячейке (по всей высоте или ширине) | 16% | +| Рисунки и картинки (в т.ч. штрихкоды) | 2% | +| Цвет текста, цвет фона ячейки, скрытые строки/колонки, отступ | — | +| Рамка с разным стилем у разных сторон; стили линий кроме сплошной | — | +| Группировки строк и колонок | — | +| Колонтитулы, параметры печати, область печати | — | + +**Многоязычные надписи не поддерживаются:** при разборе берётся первый вариант текста, +при генерации язык всегда `ru`. Для двуязычных макетов (в ERP это почти весь корпус) +надписи на остальных языках теряются. + +Отдельно: пересборка макета из DSL — это полная перегенерация, а не точечная правка XML, +поэтому diff после round-trip обычно шире фактической доработки. diff --git a/docs/1c-spreadsheet-spec.md b/docs/1c-spreadsheet-spec.md index fd74a0ad..5ec3f977 100644 --- a/docs/1c-spreadsheet-spec.md +++ b/docs/1c-spreadsheet-spec.md @@ -249,6 +249,8 @@ ``` +**Порядок элементов `namedItem` — по имени.** Платформа хранит их отсортированными, регистронезависимо: на выборке 541 макета ERP 8.3.24 с несколькими именованными элементами иного порядка не встретилось ни разу. Сортировка ординальная (латиница раньше кириллицы); случай с «ё» в выборке не встретился и не проверен. + ### Тип Columns — вертикальная область ```xml diff --git a/docs/mxl-dsl-spec.md b/docs/mxl-dsl-spec.md index 0f324756..6f87f9c9 100644 --- a/docs/mxl-dsl-spec.md +++ b/docs/mxl-dsl-spec.md @@ -138,18 +138,7 @@ ] ``` -Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. - -Ошибки (stderr, код возврата 1): - -| Условие | Сообщение | -|---------|-----------| -| нет `name` | `namedAreas: 'name' is required: …` | -| не задана ни одна ось | `namedAreas: at least one of 'rows'/'cols' is required: …` | -| список через запятую | `namedAreas: 'cols' must be a single number or range, got list "…": …` | -| диапазон задом наперёд | `namedAreas: 'rows' range is reversed "…": …` | - -Порядок именованных элементов в выходном XML — по имени: так их хранит платформа, компилятор сортирует сам. +Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. Имя обязательно, и хотя бы одна ось должна быть задана; нарушение любого из этих правил → ненулевой код выхода и сообщение в stderr. ## Строки (`rows[]`) @@ -189,14 +178,7 @@ - не выразить текст, совпадающий с `">"`, `"|"` или с шаблоном `"{...}"`; - `"|"` продолжает ячейку из предыдущей строки, только если её позиция известна явно (`col` задан или строка записана массивом). -Ошибки короткой формы (stderr, код возврата 1): - -| Условие | Сообщение | -|---------|-----------| -| `">"` без ячейки слева | `Row shorthand: '>' has no cell to the left: area "…", row N, cell M` | -| `"|"` без ячейки сверху | `Row shorthand: '|' has no cell above: area "…", row N, cell M` | -| объектный элемент с `col` | `Row shorthand: cell object must not carry 'col': area "…", row N, cell M` | -| элементов больше `columns` | `Row exceeds 'columns' (K): area "…", row N` | +`">"` без ячейки слева, `"|"` без ячейки сверху, объектный элемент с `col`, элементов больше `columns` → ненулевой код выхода и сообщение в stderr. ## Ячейки (`cells[]`) @@ -227,8 +209,24 @@ ## Ограничения -Текущая версия не поддерживает: -- Множественные наборы колонок (`columnsID`) -- Области типа Columns / Rectangle -- Рисунки (штрихкоды, картинки) -- Фон ячеек +DSL описывает не все конструкции табличного документа. Перечисленное ниже **теряется при +round-trip** (`/mxl-decompile` → `/mxl-compile`): в JSON оно не попадает, в сгенерированный +XML не возвращается. Доля — по корпусу типовой ERP 8.3.24 (10 924 макета), где измерялась. + +| Конструкция | Доля макетов | +|-------------|--------------| +| Ячейки-поля ввода (`containsValue` / `valueType` / `controlType`) | 53% | +| Несколько наборов колонок (`columnsID`) — свои ширины у группы строк | 63% | +| Объединения, не привязанные к ячейке (по всей высоте или ширине) | 16% | +| Рисунки и картинки (в т.ч. штрихкоды) | 2% | +| Цвет текста, цвет фона ячейки, скрытые строки/колонки, отступ | — | +| Рамка с разным стилем у разных сторон; стили линий кроме сплошной | — | +| Группировки строк и колонок | — | +| Колонтитулы, параметры печати, область печати | — | + +**Многоязычные надписи не поддерживаются:** при разборе берётся первый вариант текста, +при генерации язык всегда `ru`. Для двуязычных макетов (в ERP это почти весь корпус) +надписи на остальных языках теряются. + +Отдельно: пересборка макета из DSL — это полная перегенерация, а не точечная правка XML, +поэтому diff после round-trip обычно шире фактической доработки.