Возможности ESKA и Explorer

Где проходят границы

Поддерживается Designer XML . EDT-проекты и конвертация форматов не предоставляются. new создаёт каркас, а не готовую конфигурацию или визуальную форму. Дизайнеры форм, макетов и XDTO, отладчик 1С, запуск пользовательского приложения и тестовый раннер не входят в текущий набор. Изменения работающей ИБ автоматически не выгружаются: исходная XML-выгрузка должна быть получена отдельно.

Свойства редактируются по закрытой схеме backend. Произвольное добавление и удаление объектов метаданных не предоставляется. Конструктор запросов не обещает полную семантическую проверку языка; текущие зависимости от bsl-analyzer описаны в разделе конструктора . Сборка файла не развёртывает его в рабочую ИБ.

Полная поставка и API имеют проверки на Linux и Windows для конкретных этапов. Группы подпроектов, выравнивание и активность проверены на Linux ARM64, VS Code 1.144.0, bsl-analyzer 0.4.2 в ru/en. Это не подтверждает их native-приёмку на macOS, VSCodium, Remote или другой версии анализатора. Результаты конкретных сред хранятся в отчётах .

Это альтернативные входы, использующие одни исходники и один eska.toml :

eska-check check — неправильная запись: у eska-check нет подкоманды check . У eska-build , наоборот, действие сохраняется. Запуск eska-build без подкоманды равен обычной сборке. eska-project без подкоманды проверяет корневые descriptors; eska без подкоманды запускает свою проверку проекта.

Прямые eska-project context , validate , analyzer-config и serve , а также eska-build unpack не имеют одноимённых входов общего CLI. Для IDE используется eska-project serve --stdio ; eska ide --stdio — явно выбираемый legacy-вход. Общие eska new/init дополнительно работают с Git-workflow и платформой; самостоятельные eska-project new/init этих побочных действий не выполняют.

Пути, язык и выбор области

eska --project-dir ./accounting status --format json
eska-project --project-dir ./accounting context --format json
eska-build --project-dir ./accounting build --dry-run --format json

--project-dir — каталог начала поиска manifest, а не путь к самому TOML. Имена команд, ключи TOML/JSON и error codes не переводятся. --lang ru|en выбирает human-вывод; JSON сохраняет язык-независимую схему. Доступны --help и --version ; у каждого компонента собственный help без запуска 1С.

Не смешивайте области: --project NAME / -p NAME выбирает member в командах, которые поддерживают этот флаг; --workspace выбирает все members; --application NAME выбирает контекст анализа; форматтер использует --member . У eska-check нет --project и --workspace .

Полный комплект

Linux и macOS:

curl --proto '=https' --tlsv1.2 -LsSf https://odineska.github.io/eska/install | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://odineska.github.io/eska/install.ps1 | iex"

Скрипт устанавливает опубликованный комплект, а не произвольную feature-ветку. Полный комплект содержит все шесть утилит. Они размещаются в пользовательской установке; после изменения PATH откройте новый терминал. Повторный запуск установщика обновляет весь комплект до версий выбранного выпуска. Ранее поставленные через Explorer компоненты не должны мешать такому обновлению. Внешний BSL Analyzer в эти шесть программ не входит и обновляется отдельно.

Проверьте не только оболочку, но и компоненты:

eska --version
eska-project --version
eska-build --version
eska-check --version
eska-vcs --version
eska-fmt --version

Не смешивайте случайные версии. Компоненты публикуются согласованным набором; кроме номера проверяются машинные контракты и схема конфигурации designer-xml-4 . Версия IDE API развивается отдельно от версии crate. Число в имени VSIX само по себе не доказывает наличие нужного backend API.

Cargo и сборка исходников

Полный опубликованный набор через Cargo:

cargo install --locked eska-project eska-check eska-build eska-vcs eska-fmt eska

Можно установить только нужный компонент. Для дерева и свойств нужен project; для одного форматтера — fmt; для CI — check и внешний анализатор. Установка только crate eska не заменяет компоненты, которым он делегирует работу. Для воспроизводимой Cargo-установки указывайте одинаковые совместимые версии пакетов выбранного выпуска через имя@версия .

Сборка текущего checkout из корня ESKA:

cargo build --workspace --bins --release --locked

Используйте Rust из rust-toolchain.toml . На Unix можно добавить target/release в PATH текущего shell; в GUI удобнее задать абсолютные пути. На Windows исполняемые файлы имеют .exe . Этот способ позволяет проверить исходники до публикации нового выпуска. Новый backend со старым Explorer не добавит отсутствующий интерфейс: обновлять нужно обе стороны.

Explorer и анализатор

Установите VSIX через Extensions → Install from VSIX… . Текущий идентификатор расширения — 1c-tooling.eska-explorer ; GitHub-организация проектов — odineska . Это разные идентификаторы, менять publisher при настройке редактора не нужно. Минимальный VS Code API — 1.109.0. Текущий backend — eska-project .

Команда Подготовить project, форматтер и языковой компонент проверяет три инструмента и предлагает установку отсутствующих. Для первой ESKA предлагается полный комплект; самостоятельный Analyzer устанавливается из своего app-релиза. Дерево работает и при отсутствующем или неисправном анализаторе.

Стандартные имена сначала ищутся в управляемой установке, затем в абсолютных каталогах PATH. Относительные PATH entries пропускаются. Явно заданный путь не имеет fallback: его исчезновение или несовместимость требует исправить настройку.

Анализатор должен быть именно совместимым bsl-analyzer-app с командами contract , check-config , analyze --format jsonl и lsp --mode stdio . ESKA проверяет контракт, а не только имя файла. Для текущих примеров использована версия 0.4.2; наличие готового upstream asset для вашей ОС/CPU проверяется отдельно. Соседняя архитектура автоматически не подставляется. Совместимую локальную сборку можно указать в eska.explorer.analyzerExecutable и CLI --analyzer .

Одна машина, Remote и работа без сети

Backend, анализатор и форматтер должны работать на машине workspace . В Remote SSH / WSL / Dev Containers настройки путей относятся к соответствующему extension host. Web extension host, виртуальные workspace и недоверенная рабочая область не поддерживаются. Наличие корректной конфигурации Remote ещё не означает проведённую native-приёмку этой среды.

После установки повторное подключение не требует сети. Для полностью offline работы задайте существующие пути и отключите отдельные проверки обновлений project, Analyzer и форматтера. Установленная библиотека БСП тоже используется без сети; первая загрузка отсутствующей библиотеки требует доступ к репозиторию.

Есть готовая выгрузка Designer XML

eska-project init ./accounting --source src --name accounting
eska-project --project-dir ./accounting validate --format json

init определяет тип по корневому XML. Если source не указан, проверяются обычные варианты корень и src ; неоднозначность требует явного выбора. XML/BSL и непрозрачные ресурсы не перекодируются. Существующий manifest не перезаписывается. У самостоятельного project-инструмента нет инициализации Git и запуска платформы. Обычные правила производных файлов добавляются без удаления пользовательских .gitignore -правил.

Нужен новый каркас

eska-project new ./audit-users --type processing --source src

Поддерживаются configuration , extension , processing , report . Создаются eska.toml , source-каталог и служебные правила проекта. Готового XML объекта нет : до анализа/сборки поместите настоящую выгрузку в source. Нельзя принимать успешный new за создание рабочей конфигурации или формы 1С.

Есть CF, CFE, EPF или ERF

Получить только XML в новый каталог:

eska-build unpack ./incoming/AuditUsers.epf ./audit-users-xml --platform-version 8.3.27.2342
eska-project init ./audit-users-xml --source . --name audit-users

Или сразу создать проект общим CLI:

eska new ./audit-users --from ./incoming/AuditUsers.epf --platform-version 8.3.27.2342 --workflow github-flow

Это альтернативные маршруты. Для распаковки нужна платформа 1С; родитель destination должен существовать, сам destination — отсутствовать. Тип определяется по выгруженному содержимому. Общий new --from может подготовить Git и workflow; --no-vcs явно отключает Git. Установленная версия платформы в примерах — образец, её нужно заменить точной доступной версией из platform list .

Как устроен проект

audit-users/
├── eska.toml
├── src/
│   ├── АудитПользователей.xml
│   └── АудитПользователей/Ext/ObjectModule.bsl
└── build/                         # появляется после сборки

[project]
name = "audit-users"
type = "processing"
source = "src"
source_format = "designer-xml"

[build]
platform_version = "8.3.27.2342"
artifacts_directory = "build"

Project name — техническое имя ESKA, имя объекта 1С берётся из XML. Пути собственных source/artifacts/member должны быть относительными, без .. и выхода через symlink. source = "." допустим. Windows drive/UNC-путь не подходит для этих относительных полей; при записи manifest используются / . Абсолютные машинные пути задаются в соответствующих настройках инструментов или явной ссылке на внешнюю библиотеку.

Пользовательский config находится в стандартном config-каталоге ОС в подкаталоге eska , либо в ${ESKA_CONFIG_DIR}/config.toml . Это не каталог установки библиотек: ESKA_CONFIG_DIR не переносит ~/.eska/lib .

Создать отсутствующий machine config или открыть его в редакторе:

eska config init
eska config edit
# прямые входы: eska-build config init / config edit

Обычное чтение проекта не создаёт глобальный config автоматически. Для Distrobox:

[build]
runner = "distrobox"
container = "onec-alt10"
platform_arch = "arm64"

Для native host используется runner = "host" ; container при этом не задаётся. runner = "auto" разрешает обычный поиск. При Distrobox имя контейнера обязательно. CLI/environment overrides и точная build-версия описаны в разделе сборки .

Приоритеты конфигурации

Manifest проекта задаёт переносимые данные; machine config — особенности машины. Workspace владеет политикой анализа и workflow; member не объявляет второй независимый контекст поверх корневого. Форматирование имеет собственный явный порядок наследования: профиль → workspace → member → overrides → параметры операции. Неизвестные поля строгих схем отклоняются, а не молча игнорируются.

Не редактируйте производный bsl-analyzer.toml как второй источник истины. Используйте [tools.bsl-analyzer] для настроек анализатора, [tools.eska-check] для порогов CI и [format] для форматирования.

Workspace — состав проектов. Приложение — определённый набор базы, расширений и внешних объектов для анализа и выбора основы сборки. Один физический member может использоваться в нескольких приложениях.

solution/
├── eska.toml
└── src/
    ├── base/eska.toml
    ├── integration/eska.toml
    ├── regional/eska.toml
    ├── audit-users/eska.toml
    └── audit-report/eska.toml

Корневой manifest текущей схемы:

[workspace.members.accounting]
configuration = "src/base"
extensions = [
    { path = "src/integration" },
    { path = "src/regional", depends_on = ["integration"], scope = "DataSeparation" },
]
external_objects = ["src/audit-users", "src/audit-report"]

[analysis]
default_application = "accounting"

[build]
platform_version = "8.3.27.2342"

[tools.bsl-analyzer.diagnostics.parameters]
LineLength = false

Каждый путь ведёт к каталогу с собственным eska.toml и уникальным project.name . depends_on содержит имена расширений, а поля path — пути проектов. Для расширений доступны InfoBase (default) и DataSeparation . Циклы, неизвестные зависимости и несоответствие типа роли отклоняются. Каталог XML берётся из project.source ; ESKA не дописывает ещё один /src .

Старые формы workspace.members = [...] и отдельная [applications] в схеме designer-xml-4 не принимаются. Не переносите такие фрагменты из старых примеров.

Основная конфигурация необязательна. Без неё контекст называется ограниченным ( limited_context = true ), а не ошибочно «полным». В качестве базы можно выбрать внешнюю XML-выгрузку или именованную библиотеку без создания member:

[workspace.members.tools]
configuration = { library = "ssl_3_1" }
external_objects = ["src/audit-users", "src/audit-report"]

Либо configuration = { source = "/data/reference/src" } . Внешняя основа должна быть Designer XML конфигурации, а не CF или каталог нескольких разных форматов. Она остаётся read-only reference: не участвует в Git/member-командах и не становится второй редактируемой конфигурацией дерева.

Выбор приложения и области

eska-project context --application accounting --format json
eska check --application accounting --format json
eska build -p audit-users
eska build --workspace --dry-run --format json

Если приложений несколько, задайте default или --application для анализа. В Explorer есть Выбрать приложение для анализа . Одно подключение LSP обслуживает один выбранный контекст, а не все приложения сразу.

При new/init внутри workspace используйте --application NAME , если приложений несколько. ESKA добавляет member в соответствующую роль и проверяет состав до записи. Не создаётся второй независимый Git/workflow у member. Сборка отчёта/обработки наследует базу своего приложения; неоднозначный выбор основы требует исправить конфигурацию, а не выбрать случайную соседнюю базу.

Автоматическое подключение

В каталоге проекта обработки или отчёта:

eska add ssl_3_1
# альтернативный прямой вход:
eska-project add ssl_3_1

Поддерживаются известные публичные библиотеки ssl_3_1 и ssl_3_2 . При отсутствии ESKA получает текущую master известного репозитория и устанавливает её в ~/.eska/lib/<name> . В глобальном каталоге регистрируется source src/cf , в проекте появляется одна ссылка:

[analysis.configuration]
library = "ssl_3_1"

Повторный add использует установленную и зарегистрированную копию без сети и не переключает её на новый commit. Это подключение , а не неявный update библиотеки. Другая существующая основа не заменяется. Неизвестный или чужой неуправляемый каталог не считается разрешением перезаписать его.

В workspace выбирается текущий member либо один явный -p :

eska add ssl_3_1 -p audit-users --format json

Первой установке требуется VCS-компонент. Установленная reference-копия не становится member и не клонируется отдельно в каждый проект. Если у приложения уже есть собственная база, не добавляйте поверх неё вторую несовместимую основу.

Зарегистрировать свою существующую выгрузку

В пользовательском config.toml :

[libraries.company_base]
source = "/data/bases/company/src"

В проекте library = "company_base" , а в workspace — configuration = { library = "company_base" } . source может быть абсолютным или относительным от глобального config , не от текущего проекта. Существует также прямая [analysis.configuration] source = "..." без имени. library и source — альтернативы; одновременно они не задаются.

Сейчас в контексте одна такая основа. Несколько библиотек одновременно — отложенная возможность. Валидация и fingerprint относятся к выбранной записи; посторонняя запись каталога не должна ломать текущий проект. Explorer наблюдает глобальный config и может восстановиться после исправления выбранной записи, сохраняя dirty BSL. Замена основы анализатора обычно создаёт новый LSP-контекст.

Что переиспользуется при сборке

Сборщик получает основу из тех же настроек. Для именованной библиотеки подготавливаются общий CF и закрытая служебная ИБ; каждый потребитель получает свою изменяемую копию. Проверяются source snapshot, версия платформы, runner, исполняемый файл и контейнер. Общий кеш находится в системном пользовательском cache eska/libraries ; при нестандартном config — в соседнем cache/libraries . Он не размещается в исходниках ~/.eska/lib .

Повторная сборка сверяет содержимое и не принимает одинаковые размер/mtime за доказательство неизменности. clean потребителя не удаляет библиотеку и её общую подготовку. Явный --base-configuration FILE.cf имеет приоритет над автоматической XML-основой.

Откройте папку проекта или workspace, выберите представление ESKA и подключение. Подключение не запускает платформу и не выполняет автоматическую сборку. В multi-root workspace папка выбирается явно; для защиты исходников учитываются и дополнительные папки. Статус показывает фактически подключённый backend.

Дерево метаданных

В корне показаны конфигурации и подпроекты; разделы метаданных находятся прямо внутри проекта. «Общие», коллекции объектов, вложенные реквизиты и табличные части, роли модулей, формы, команды и поддерживаемые ресурсы предоставляются backend. Ветки читаются лениво. Ошибка одного проекта или узла не скрывает здоровые ветки.

Имена объектов не переводятся. treeLanguage выбирает ru-RU/en-US для подписей разделов, ролей и типов результатов. Переключение языка не меняет имена в XML. Дерево можно обновить целиком или у конкретного узла; если файловые события были исключены настройками наблюдения VS Code, используйте ручное обновление.

Открытие и переход от файла

• Выбор существующего модуля открывает BSL. Объект только с бинарным модулем остаётся доступен через свойства и XML; отсутствующий BSL не создаётся.
• Для формы доступны её XML и модуль, без визуального дизайнера формы.
• Открыть XML открывает descriptor; Свойства — отдельную панель редактора.
• Показать открытый файл в дереве eska получает ancestry от backend, раскрывает нужные группы и выбирает metadata- или файловый узел.
• Переходы используют реальные пути и проверяют принадлежность source; неизвестный файл не выдаётся за распознанный объект 1С.

У объекта с группой Модули нажатие на сам объект открывает свойства, даже если BSL-файл один; дочерний модуль открывает код. Общие модули, команды, боты, HTTP/Web-сервисы, WebSocket-клиенты, сервисы интеграции и перерасчёты могут открывать свой BSL непосредственно по имени. XML доступен отдельным действием. Для точного выделения в изменённом XML сначала сохраните файл и обновите ветку.

У подписки на событие клик переходит к процедуре обработчика в общем модуле того же проекта. Отсутствующий модуль или процедура дают пояснение; Открыть XML открывает саму подписку.

У справочников, планов счетов, планов видов характеристик и планов видов расчёта доступны Предопределённые данные из Ext/Predefined.xml : ленивое раскрытие, свойства, переход к имени в XML, поиск по имени/описанию. Отдельного редактора создания, удаления и перестройки списка предопределённых элементов нет.

Поиск метаданных

Лупа открывает поиск по именам и синонимам. Индекс строится отдельно для проектов, показывает состояние и ошибки и не требует индекса BSL. Выбор результата раскрывает дерево и выбирает объект. Поиск не является поиском произвольных имён физических файлов. Отключённые проекты в фоновый поиск не включаются.

Ищется буквальная подстрока без учёта регистра по нераскрытым веткам и синонимам всех языков. Нечёткий поиск и приравнивание ё к е не выполняются. Результат показывает тип, проект и владельца; модули и виртуальные группы не входят в выдачу. Пока индекс строится, результаты частичные; при ошибках XML — неполные. Показывается до 50 результатов на проект: при усечении уточните запрос. Закрытие Quick Pick отменяет поиск, но уже начатый индекс может достроиться; отключение подпроекта освобождает его индекс.

Сортировка, фильтры и группы проектов

По умолчанию используется исходный порядок. Алфавитная сортировка включается для конкретного проекта и сохраняется. Она учитывает язык и числа ( Поле2 раньше Поле10 ), не меняя XML или порядок самих проектов.

Фильтр пустых разделов относится к корню конфигурации/расширения и «Общим». Группы внутри объектов сохраняются. Есть действия показать, скрыть и вернуть проектный выбор к настройке по умолчанию. Это не фильтр отключённых проектов.

Два и более видимых расширения, отчёта или обработки одного типа образуют виртуальную группу. Порог независим для каждого типа; одиночные members и конфигурации остаются на исходном уровне. Группы сохраняют понятную навигацию, выбор и раскрытие; не создают каталогов и не меняют manifest.

Файловые группы

После метаданных доступны Настройки проекта , Документация , Прочие файлы . Manifest, Git/editor/agent-настройки распознаются по конкретным именам; README — как документация; остальное — как прочие файлы. Каталоги сохраняют физическую вложенность. Source и корни members не дублируются обычным файловым деревом. Пустые контейнеры members скрываются, появление обычных файлов возвращает их.

В документацию попадают README.md , README.ru.md , README-ru.md независимо от регистра; произвольный notes.md относится к прочим файлам. В настройках распознаются manifest, analyzer config, Git-файлы, .vscode , .editorconfig , .github / .gitlab , agent-файлы и каталоги. Известный каталог показывается целиком, его вложенные README не переносятся. Глобальный config вне проекта не добавляется.

Папки читаются по запросу, нерекурсивные наблюдатели обновляют снимки. Символические ссылки видны, цикл к физическому предку не раскрывается бесконечно. Иконки и Git-подсветка физических файлов используют редактор; metadata-узлы показывают соответствующие изменения через существующую Git-интеграцию.

Git-декорации: M — изменение, A / U — добавленный или неотслеживаемый, R — переименование, D — удаление, ! — конфликт, • — изменения внутри объекта/группы. Удалённые metadata-объекты отдельно не восстанавливаются в дереве. Unsaved BSL сам по себе не меняет Git-статус. Без встроенного Git или при git.decorations.enabled = false дерево работает без подсветки. Масштаб, клавиатурная навигация и темы используют стандартные механизмы VS Code; смена темы не переподключает проект.

В меню корневого member выберите Отключить проект . Узел остаётся с именем, типом и пометкой отключения; metadata session, поисковый индекс и собственные наблюдатели освобождаются. Ненужные исходники анализатора исключаются; его общая работа с активными потребителями продолжается. Запоздалый ответ не возвращает отключённые узлы. Включить проект открывает свежую session и возвращает обычный цикл загрузки, включая уже открытые BSL-документы.

Если отключённая база или расширение нужны активному проекту, подсказка показывает потребителей ( requiredBy ) по приложениям. Нужные общие исходники сохраняются; собственные фоновые задания отключённого проекта не возобновляются. Один LSP продолжает обслуживать выбранное приложение; второй контекст автоматически не запускается. Последний потребитель освобождает процесс, аренду и наблюдатели.

Зависимость можно отключить в дереве . Это освобождает её metadata-ресурсы, но необходимые потребителю исходники остаются в общем семантическом контексте. Поэтому отключение большой базы при активном расширении не обещает полностью освободить индекс анализатора базы. requiredBy учитывает все активные приложения; выбранный LSP остаётся один.

Скрыть отключенные — отдельный фильтр. Его переключение не включает проекты и не запускает сервисы. Показать отключенные остаётся доступным в заголовке и палитре даже при всех скрытых members. Группы типов пересчитываются после фильтра: два отчёта → один видимый отчёт → группа исчезает; показ обоих возвращает её.

Активность и фильтр сохраняются локально по физическим корням workspace/members, а не по месту узла или имени группы. Файл состояния лежит рядом с пользовательским config в state/workspaces/<hash>/activity.json . Manifest и исходники не меняются. Конфликт новой ревизии другого подключения требует переподключиться; чужое предпочтение не перезаписывается автоматически.

Открытие файла отключённого проекта и поиск не включают его. Native-буферы, Undo/Redo и действующие правила защиты сохраняются. Явные самостоятельные CLI/CI команды продолжают использовать заданный состав независимо от фильтра IDE. Standalone-проект этой функцией не отключается. Требуется API 1.35.

Панель Свойства читает объект и схему редактирования из ESKA. Редактор не угадывает допустимые поля по внешнему виду XML. Read-only поле показывает причину; неизвестное свойство не становится доступным только потому, что похоже на строку. Идентичность объекта и пути вложенных полей предоставляет backend.

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

Чтение и связанные объекты

Заголовок показывает синоним, а при его отсутствии — имя объекта. Поиск находит подписи, XML-имена, значения и вложенные поля; составные значения раскрываются. Подписи следуют языку дерева, неизвестные поля сохраняют XML-имена. Один язык локализованной строки показывается без кода языка, несколько — каждый со своим. xsi:nil , пустая строка, Undefined и Null различаются.

Ссылки показывают имя/синоним, иконку и вид цели; нажатие открывает её свойства в том же проекте. Поддержаны языки, стили, формы, хранилища, функциональные опции, картинки, реквизиты, значения перечислений и предопределённые элементы. У вложенной цели виден владелец. Стандартный реквизит ведёт к владельцу, процедура — к общему модулю. Недоступная цель показывает причину. Определяемые типы и характеристики доступны по ссылкам; «Любой документ» не выдаётся за один конкретный объект.

Предпросмотр общей картинки

Изображение показывается с фоном прозрачности, форматом и размерами. Поддержаны PNG, JPEG, GIF, BMP, ICO, WebP, SVG и ZIP-наборы, где backend выбирает подходящий детальный вариант современного интерфейса. Лимит изображения — 8 MiB, архива — 32 MiB; ZIP не распаковывается в source. Обновить перечитывает ресурс. Если файл отсутствует или не распознан, свойства остаются доступны с пояснением; изменение изображения не входит в preview.

Сохранение, отмена и конфликт

Панель сначала открывается для чтения. Замочек разрешает доступные схеме поля этой вкладки. Строка сохраняется по Enter или выходу из поля, Esc отменяет ввод; списки и флажки сохраняются сразу. Флажок появляется только для доказанного boolean; строка "true" остаётся текстом. История панели и Ctrl+Z/Ctrl+Shift+Z отменяют/повторяют подтверждённые изменения. Открыть XML у поля выделяет его элемент, Обновить перечитывает объект. Конфликт сохраняет черновик.

Применение привязано к точному снимку файла. ESKA проверяет схему, поддержку, связанные ограничения и актуальность до записи; меняет только выбранный участок, сохраняя остальные bytes, BOM/EOL и непрозрачные данные. В IDE session доступны соответствующие Undo/Redo. Новый отдельный CLI-процесс не наследует эту историю. Если файл уже изменён другим участником, обновите свойства и повторите осознанно; устаревший snapshot не является правом затереть новый текст.

Переименование учитывает допустимость имени, конфликт имён/путей, доказанные ссылки и неопределённые случаи. Preview нужно прочитать до Apply. Это не обещание заменить каждое похожее слово во всех строках, комментариях и BSL. Изменения выполняются как проверенная операция; для прерванной записи есть отдельная проверка/recovery. Создание или удаление объектов этим действием не заменяется.

Те же операции из CLI и для автоматизации

eska-project metadata inspect --format json
eska-project metadata inspect --object 'catalog:Товары'
eska-project metadata types types.json
eska-project metadata choices reference.json
eska-project metadata check change.json
eska-project metadata apply change.json
eska-project metadata rename-preview rename.json
eska-project metadata rename-apply rename.json
eska-project metadata rename-recovery recovery.json

inspect даёт точные objectId , snapshot , пути полей, допустимые значения, причины read-only и возможности операций. В workspace выберите один -p NAME . Файл запроса можно заменить - для stdin. Формат запроса берётся из ответа схемы, а не собирается по предположению о расположении XML.

Пример изменения комментария после получения реального snapshot/path :

{
  "schemaVersion": 1,
  "objectId": "catalog:Товары",
  "snapshot": "точный SHA-256 из editing.snapshot",
  "path": [
    {
      "key": {
        "namespace": "http://v8.1c.ru/8.3/MDClasses",
        "name": "Comment"
      },
      "occurrence": 0
    }
  ],
  "change": { "kind": "text", "value": "Используется в интеграции" }
}

Сначала metadata check , затем metadata apply . Это образец структуры, а не готовый запрос к любому проекту. Все варианты типов, ссылок, связанного контекста и восстановления приведены в контракте редактирования .

ESKA читает сведения поставщиков и UUID из Ext/ParentConfigurations.bin и сопоставляет их с проверенными metadata/source identities. Explorer показывает состояние объекта и получает права на конкретные файлы. Принадлежность и правило вычисляет backend, а не расширение файла или локальная догадка интерфейса.

Защищённое представление eska-protected: показывает проверенный снимок через backend. Обычные чистые вкладки могут быть переведены в защищённый просмотр; dirty-текст сохраняется с ограничением записи. Пользовательские files.readonlyInclude / files.readonlyExclude , файловые права и overrides редактора не становятся собственностью ESKA.

eska.explorer.supportPolicy = false выключает обычную защиту Explorer и снимает только правила, добавленные ESKA. Это не отменяет запрет платформы/файловой системы и не освобождает исходник, который удерживает активная query-сессия. Закрытие такой сессии снимает только её временное ограничение.

При изменении правил поддержка перечитывается по запросу. Не нужно предварительно индексировать весь проект ради одного видимого файла. Временное исчезновение уже известных правил не должно превращать запрещённый файл в редактируемый. Подробные приоритеты и неподдержанные случаи — в support policy .

Редактор запросов позволяет работать с SDBL без XML escaping, BSL-маркеров | и удвоенных кавычек. Он отделяет сохранение черновика от изменения исходника .

Запрос в XML

Поддерживаются запросы наборов данных СКД и ручных динамических списков в поддерживаемом XML формы. Выберите запрос в дереве/списке запросов владельца. Каждому запросу соответствует собственная identity, даже если в XML их несколько. Save меняет выбранный текст запроса, сохраняя обрамление и остальные bytes XML. Если владельцем является dirty native-буфер, он остаётся dirty: операция не даёт разрешение молча сохранить весь файл на диск.

Автоматически формируемый список и неизвестный payload не превращаются в ручной редактируемый запрос. Кавычки, & , < , > и переводы строк перекодируются backend, а не ручными строковыми заменами адаптера.

Запрос в BSL

Поставьте курсор внутри цельного строкового литерала и выберите Редактировать запрос отдельно . Название переменной не имеет значения. Вычисляемое выражение, конкатенация или шаблон не считаются одним статическим литералом. Backend объясняет отказ, сохраняя модуль.

Запрос.Текст =
    "ВЫБРАТЬ
    |    Пользователи.Наименование КАК Имя
    |ИЗ
    |    Справочник.Пользователи КАК Пользователи";

В дочернем редакторе виден только запрос. Split-вкладки делят одну сессию; повторное открытие возвращает в неё. При закрытии dirty-родителя редактор сначала даёт обычный выбор сохранить, не сохранять или отменить. ESKA фиксирует снимок после решения пользователя, без скрытого сохранения или отбрасывания текста.

Дочерний редактор временно заменяет вкладки родителя; попытка навигации обратно возвращает фокус дочернему. Применение, отмена или завершённое закрытие возвращают родителя и позицию. Отмена самого закрытия оставляет запрос открытым.

Применение и восстановление

Перед применением проверяются текст/версия буфера, диск, descriptor, поддержка и выбранный контекст. Внешняя правка вызывает конфликт; оба текста сохраняются. Нельзя считать старый checkpoint подтверждением права перезаписать новый модуль. После перезапуска продолжение явное. Если исходник или контекст изменились, сначала сравните владельца и примите решение; автоматического слияния двух разных версий тела запроса нет.

Активная сессия удерживает своего владельца и защищает от конкурирующих изменений свойств, переименования и иных source-операций backend. Private-снимки и буферы ограничены бюджетом; слишком большой запрос не превращается в частично сохранённый. Точные лимиты и версии capabilities описаны в IDE protocol .

Языковые сервисы в черновике

Для BSL-владельца ESKA может построить неизменяемую BSL-проекцию запроса и карту позиций; Explorer передаёт её уже работающему LSP выбранного приложения. Это не второй индексатор и не запись временного модуля в source. Диагностика, переходы и допустимые правки переводятся обратно по карте. Native-документ не меняется, а после освобождения проекции восстанавливается его актуальный буфер.

Недоступный анализатор, неизвестная карта или неподдержанное соответствие позиций не дают права применить приблизительную правку. Сами редактирование черновика и backend-конструктор не требуют этой семантической помощи.

Откройте запрос и выберите Конструктор запросов . Он работает над текущим черновиком и получает исключительное владение им на время диалога. Родительский редактор остаётся без ввода. Применить/завершить конструктора публикует одну новую ревизию черновика; исходник меняется только последующим обычным сохранением XML-запроса или явным применением BSL-запроса. Отмена не меняет черновик.

Каталог таблиц основан на выбранном приложении: база, нужные расширения, поддерживаемые стандартные поля и связанные metadata-объявления. Другие приложения не подмешиваются. Поля каталогов, документов, табличных частей, регистров и других поддерживаемых источников предоставляет ESKA. Наличие имени в каталоге не означает полного вывода типа выражения или проверки выполнения запроса.

Таблицы, поля и соединения

Простые изменения alias не затрагивают похожие слова в строках и комментариях, пути метаданных или затенённую вложенную область. Источник без КАК/AS сохраняет полную квалификацию. Порядок JOIN не меняется механически, если это сделает ссылку на источник недопустимой.

Условия, группировки и сортировка

Редактор условий поддерживает дерево И / ИЛИ / НЕ , сравнения, NULL и МЕЖДУ. Для каждого JOIN редактируется свой ON. WHERE и HAVING различаются; перенос условия между ними — отдельное явное действие. Выражения и операнды проверяются структурно, с сохранением неизменённых неизвестных фрагментов.

Можно задавать список группировок, агрегатные выражения, порядок и направление сортировки. Правки связываются с соответствующей областью запроса. Вложенная SELECT-область не получает автоматически общий порядок внешнего UNION.

UNION и выходные колонки

Вкладка объединений и матрица показывают ветки и позиции выходных колонок. Доступны копирование/удаление ветки, выбор UNION с сохранением или исключением дублей, согласованные добавление, удаление и перестановка колонок. Отсутствующее значение новой колонки может заполняться NULL . Неравное число полей блокирует применение изменённого запроса. Выравнивание и перенос колонки подтверждаются по preview, а порядок/итоги общего объединения относятся к его общему хвосту.

Пакеты, подзапросы и временные таблицы

Дерево пакета показывает операторы и вложенные области. Поддержаны отдельные действия над операторами и временными таблицами, переход к текущему определению, назначение имени результата и поддержанный индекс. Копирование оператора выделяет новое имя назначения. Области и ссылки проверяются до изменения; пакет не сводится к редактированию случайной первой SELECT-ветки.

Итоги и СКД

Для поддержанной секции итогов задаются агрегатные выражения, Общие итоги , уровни группировки, иерархия и заполнение периодов. Пустой список выражений означает автоматические итоги. Удаление последнего уровня группировки удаляет соответствующую секцию, а добавление возвращает её. Доступная операция зависит от распознанной структуры и capabilities backend.

Поддержанные расширения СКД редактируются в своём структурном контексте. Это не полный визуальный редактор схемы компоновки: ресурсы, оформление, настройки пользователя и произвольные XML-узлы не объявляются реализованными этой вкладкой.

Настройки SELECT и работа с текстом

Настройки запроса меняют поддержанные DISTINCT, ALLOWED, TOP, AUTOORDER и FOR UPDATE через проверяемый preview. Текст открывает полный буфер, сравнение и работу с исходными комментариями. Показать в тексте связывает строку модели с диапазоном; переход из текста выбирает соответствующую область. Ошибочный ввод остаётся в буфере для исправления, а не уничтожает прежний запрос.

Если комментарий нельзя однозначно перенести, выберите Назначить позиции исходных комментариев и явно задайте размещение. Исходные комментарии и неизменённый текст не должны исчезать ради удобства генератора.

Групповые действия и клавиатура

В табличных списках доступны флажки и диапазон Shift, общая панель копирования, удаления и перемещения. Используются Alt+↑/↓, Delete, Ctrl/Cmd+D; двойной щелчок, Enter или F2 открывают ячейку, Enter принимает, Escape отменяет. Групповое действие выполняется атомарно и согласует aliases/выходы UNION. Preview показывает результат до публикации; команда старой ревизии отклоняется.

Что конструктор не доказывает

ESKA отвечает за разбор поддержанной структуры, допустимость операции, сохранение токенов/комментариев и минимальную правку. Неизвестная конструкция сохраняется как точный исходный текст с объяснением недоступности операции. Существование визуального контроля не обещает полный разбор произвольного SDBL.

Полная семантика, вывод типов, языковые сервисы всех областей и подтверждённый автоматический подбор связей зависят от дальнейших контрактов bsl-analyzer. Их нельзя считать реализованными только по наличию панели. Финальную корректность исполняемого запроса проверяйте на своей платформе и данных.

Базовая подсветка BSL/SDBL, скобки, комментарии и отступы входят в Explorer. Семантические сервисы работают через отдельный внешний bsl-analyzer-app . Он запускается при открытии подходящего BSL-документа или командой Перезапустить языковой сервис BSL . Одно открытие дерева LSP не запускает.

Доступны поддерживаемые сервером диагностика, hover, completion, definition, type definition, references, signature help, symbols/outline, inlay hints, семантическая подсветка, rename и quick fixes. Реальные возможности определяет контракт выбранного сервера и проверяемый адаптер; неизвестные серверные команды и файловые create/delete/rename не исполняются как произвольная автоматизация.

Контекст, ошибки и несколько окон

Перед запуском Explorer получает приложение от ESKA, проверяет бинарник, свежесть и владение конфигом, затем удерживает lease на конкретный снимок. Один root содержит один bsl-analyzer.toml выбранного приложения. Несовместимый второй контекст или попытка перезаписи при чужой аренде дают явный конфликт. Сначала остановите клиентов старого контекста, затем осознанно переключите его.

Обычные изменения XML/BSL обновляют модель. Изменения manifest, выбранной библиотеки или входов конфига проходят повторную проверку. Неизменённый fingerprint сохраняет процесс и актуальные диагностики. Подписки и ответы привязаны к текущему документу, версии и модели: поздний ответ не применяется к другой версии или повторно открытому файлу.

При установленном конфликтующем elishevkirill.bsl-analyzer-lsp собственный клиент Explorer приостанавливается, чтобы два сервера не конкурировали. Пользователь явно выбирает, какое расширение оставить включённым. Explorer не отключает стороннее расширение скрытой командой и не подменяет его бинарник.

Производный bsl-analyzer.toml

Первичные настройки:

[tools.bsl-analyzer.diagnostics.parameters]
LineLength = false

[tools.eska-check]
max_errors = 0

eska-project analyzer-config status --format json
eska-project analyzer-config prepare --analyzer /path/to/bsl-analyzer-app

status читает состояние без записи. prepare проверяет контекст и реальный config выбранным анализатором, затем публикует только разрешённый производный файл. Данные о владении и fingerprint связывают его с manifest и sources. Смена управляемого контекста при необходимости требует --switch-context ; этот флаг не отменяет чужую действующую аренду.

Если уже есть пользовательский bsl-analyzer.toml , обычный prepare его не присваивает. Используйте preview миграции, проверьте перенос политики и примените только с точным токеном:

eska-project analyzer-config migrate --format json
eska-project analyzer-config migrate --apply --preview-token TOKEN --format json

Оригинал сохраняется в backup. Конфликт исходных настроек или новый снимок требует нового preview. После миграции редактируется eska.toml , а не обе копии.

Подсказки многострочных аргументов

С API 1.34 продолжения строкового аргумента получают визуальный отступ первой строки с учётом подписей параметров и вложенных вызовов. Для точного совпадения связанные подписи и невидимые отступы используют шрифт редактора . Независимые однострочные вызовы сохраняют штатные hints. Исходный текст не меняется: в буфер не вставляются реальные пробелы и не появляются лишние Undo-операции.

Выравнивание действует при editor.inlayHints.enabled = "on" . Условные режимы по модификаторам, явная поддержка доступности и hints с действиями/resolve сохраняют штатное отображение без выравнивания. Смена темы, масштаба и hint font не должна менять исходник. Эта визуальная функция отличается от настройки форматтера indent_multiline_strings , которая действительно меняет отступы source.

Безопасность языковых правок

Rename, quick fix и серверный text edit проверяются целиком перед применением: все цели, версии документов, контекст, support policy, временные владельцы, read-only и файловые границы. Отказ одной цели отменяет весь edit. Применяется одна native-транзакция с Undo. Для ресурсоопераций файлов разрешение не выдаётся; неизвестные server commands отклоняются. Защищённый просмотр не становится редактируемым от того, что ответ пришёл через LSP.

eska-fmt работает без анализатора, платформы и metadata-индекса. Общая eska fmt делегирует ту же операцию. По умолчанию без секции [format] используется профиль 1c версии 1 . Доступны также eska и именованные пользовательские профили.

[format]
profile = "team"
profile_version = 1
exclude = ["**/generated/**"]

[format.profiles.team]
based_on = "1c"

[format.profiles.team.common]
column_limit = 100

[format.bsl]
indent_style = "space"
indent_width = 4

[[format.overrides]]
include = ["src/CommonModules/Legacy/**"]

[format.overrides.bsl]
column_limit = 0

Порядок: профиль → общие/языковые настройки workspace → member → совпавшие workspace overrides → member overrides → параметры операции. В списке overrides последнее совпадение побеждает. Glob относится к объявившему его manifest, поддерживает * , ? , ** и / ; абсолютные пути, .. и \ не используются. Изменение версии программы само по себе не выбирает новую версию профиля.

Проверка, preview и запись

eska fmt --check
eska fmt --diff
eska fmt --dump-config --format json
eska fmt src/CommonModules/Обмен/Ext/Module.bsl --check
eska-fmt --member audit-users --check
eska-fmt --workspace --check

Без --check / --diff форматтер записывает поддержанные изменения выбранной области. Scope — файл или каталог объекта относительно project-dir; без scope выбираются исходники. --dump-config показывает эффективную политику и происхождение значений без записи. --style принимает разреженный JSON override одной операции, например --style '{"column_limit":100}' .

Обычный BSL fmt сохраняет содержимое строк, включая встроенный запрос. Для явного форматирования статического запроса есть --query-at — UTF-8 byte offset в BSL, либо --query-index — индекс запроса XML от нуля. Вычисляемая строка не считается статическим запросом. Миграция старых настроек: сначала --migrate-config , затем осознанный --apply-migration с backup.

Что можно настраивать

Полный каталог ключей, defaults, диапазонов и примеры профиля eska находятся в справочнике форматирования . Значение column_limit = 0 отключает ориентир длины, а не структурные проверки. Форматтер не переписывает непонятный фрагмент приблизительно и не заменяет компиляцию.

В редакторе

Используйте стандартные Format Document и Format Selection с ESKA как formatter. Для native VS Code format on save выберите 1c-tooling.eska-explorer как default formatter для BSL/SDBL. Отдельная настройка eska.explorer.formatOnSave по умолчанию false . Настройки отступов редактора не переопределяют [format] .

Форматирование query-черновика меняет черновик, а не его владельца. Запрещённые на поддержке файлы не форматируются; редактируемые с поддержкой — только по явно выбранному непустому участку. Если план выходит за выделение, он отклоняется. Тела методов &ИзменениеИКонтроль / &ChangeAndValidate , включая запросы внутри, сохраняются. Пользовательские read-only правила проверяются отдельно.

Различайте три уровня:

eska-project validate --format json
eska check --application accounting --format json --report ./reports/check.json
# альтернативный прямой вход:
eska-check --application accounting --format json --report ./reports/check.json

Для --report подготовьте существующий допустимый каталог назначения вне исходников; команда не должна использовать путь отчёта как способ перезаписать source. Укажите --analyzer /path/to/bsl-analyzer-app либо ESKA_BSL_ANALYZER ; по умолчанию используется имя bsl-analyzer-app из PATH.

Пороги результата

[tools.eska-check]
max_errors = 0
max_warnings = 0
# max_information = 0
# max_hints = 0

По умолчанию допускается ноль ошибок; остальные уровни не ограничены. Пороги — неотрицательные целые. Они не подменяют параметры отдельных правил [tools.bsl-analyzer] и не передаются как случайная секция upstream config. Workspace владеет общей политикой и составом анализа.

Полный контекст включает подключённую reference-библиотеку. Проверка обработки с БСП может поэтому вернуть замечания в самой БСП, а не только в вашем модуле. Разбирайте пути в files[].path и выбранные правила анализатора; отсутствие правок в библиотеке не исключает её автоматически из check .

Не принимайте отсутствие отдельных diagnostics за успешный анализ. Требуются завершённый поток, согласованные счётчики, полный ожидаемый набор BSL и отсутствие failed files. Повреждённый XML, неизвестный неподдержанный фрагмент, изменение входов во время проверки и частичный ответ не дают законченного success-отчёта. В CI сохраняйте и exit code, и JSON: локализованный stderr предназначен человеку.

--timeout ограничивает процессы анализатора; default — 600 секунд. eska-check не принимает фильтр только изменённых файлов: политики частичного анализа вроде непустых diff_base / ignored_authors отклоняются. Для CI проверяется весь выбранный application, независимо от активности Explorer.

Проверка форматирования — отдельный шаг:

eska fmt --check --format json

У fmt 0 означает отсутствие требуемых изменений, 1 — необходимость форматирования в check-режиме; ошибки и отмена различаются его машинным отчётом. Полные exit codes и JSON поля приведены в контракте fmt .

ESKA выражает операции через задачу и политику проекта. В [vcs.workflow] выбираются trunk , git-flow , github-flow или custom . У workspace workflow принадлежит корню; свой независимый workflow у member не создаётся.

[vcs.workflow]
preset = "github-flow"

Для custom задаются база/main, тип рабочей ветки и шаблон task-имени, remote, стратегия синхронизации, integration target, условия публикации/finish и удаления локальной ветки. Допустимые значения и совместимые комбинации определяет строгий контракт workflow; произвольная строка не включает новую стратегию. Перед start существующий repository должен пройти preflight.

Получить проект и начать задачу

eska clone https://example.org/team/solution.git ./solution
cd solution
eska status
eska start AUDIT-42

clone не угадывает, как инициализировать неподготовленную выгрузку: если manifest отсутствует, выполните соответствующий init . start не прячет dirty-изменения автоматическим stash. При отказе сначала сохраните или явно отложите свою работу.

Посмотреть изменения и историю

eska status --format json
eska diff
eska diff --raw
eska diff --semantic
eska diff main HEAD --semantic --format json
eska diff main HEAD --since-branch-point --semantic
eska history --limit 10 --format json

Файловый diff показывает изменения путей; semantic diff объясняет известные объекты, свойства, модули и методы BSL, формы и другие поддержанные элементы. Это не полный компилятор BSL. Для неизвестного или повреждённого фрагмента показывается честный file-level fallback с причиной, а не вымышленный смысл. Читаются затронутые пути и нужные snapshots; весь проект не сканируется ради каждого status или draft сообщения.

В workspace некоторые команды принимают повторяемый -p NAME или --workspace . Явная область не даёт права включить в commit исходные изменения соседнего member. Для revision diff используются зафиксированные снимки revisions, а не случайное сочетание старого descriptor с новым рабочим файлом.

Сохранить commit

eska save --dry-run
eska save -m "Добавлен аудит активных пользователей"

Preview показывает точный выбранный scope, файлы и сообщение, не запускает editor/hooks и не меняет index/refs/worktree. Обычный save повторяет preflight. Без -m готовится draft по известным изменениям и используется настроенный editor. При неполном semantic-разборе причина показывается отдельно, не маскируя проблему. save не отправляет commit на сервер.

Переключиться или отложить работу

eska shelve --dry-run --format json
eska shelve
eska shelves --format json
eska switch --base --dry-run --format json
eska switch --base
eska switch AUDIT-42
eska unshelve --dry-run --format json
eska unshelve

Полка сохраняет staged и unstaged отдельно, non-ignored untracked, удаления, mode и raw index. Это repository-wide состояние, включая соседние проекты workspace и файлы вне вложенного member. unshelve ID позволяет выбрать запись; без ID используется полка текущей ветки. Восстановление проверяет branch/base и конфликты; ошибка не должна уничтожить единственную копию состояния.

switch возвращается на base или на существующую задачу. Он не завершает её и не выполняет безусловный reset --hard . Dry-run полезен перед переходом, когда есть изменения всего repository.

Завершить задачу

eska finish

finish проверяет политику, чистоту всего worktree, интеграцию/публикацию и ancestry, затем завершает локальную задачу. По preset/политике может удаляться локальная task-ветка. Commit в task-ветке сам по себе не означает, что условия finish выполнены. Squash/rebase может не подтверждаться проверкой достижимости исходного tip; автоматического признания такой интеграции нет.

Отдельные eska sync , publish , push , merge и rebase не реализованы . Если команда использует Git-сервер, PR/MR и интеграция выполняются существующими инструментами вашей команды. Например, git push — Git, а не скрытая часть save. Не добавляйте отсутствующие команды из roadmap в CI.

Сборка использует установленную платформу, а не скачивает и не заменяет её. Версия в [build].platform_version — точная версия сборки. Для BSL-анализа есть отдельная target version; это не обещание найти native binary автоматически.

Найти и выбрать платформу

eska platform list --format json
eska doctor --format json
# прямые входы:
eska-build platform list --format json
eska-project doctor --format json

Machine config выбирает runner auto , host или distrobox , контейнер и архитектуру. Явный --ibcmd либо ESKA_IBCMD задаёт executable; доступны --platform-arch / ESKA_PLATFORM_ARCH и --distrobox / ESKA_DISTROBOX . Путь и имя контейнера — машинные данные, а не переносимая настройка каждого member.

eska build --platform-version 8.3.27.2342
eska build --select-platform
eska build --ibcmd /opt/1cv8/arm64/8.3.27.2342/ibcmd

Эти build-флаги относятся к одному запуску и не переписывают закреплённую версию. --select-platform требует интерактивного выбора и не комбинируется с явной --platform-version . Несуществующая точная версия не заменяется ближайшей. --ibcmd — путь к executable, не shell-команда с аргументами.

На Linux Distrobox позволяет использовать установленную в контейнере платформу. Нужен общий доступ к исходникам и рабочим каталогам. Явный host executable не является просьбой автоматически искать другую установку в контейнере. Нативная применимость конкретной версии 1С, архитектуры и ОС проверяется отдельно.

Предварительный план и результат

eska build --dry-run --format json
eska build --output ./build/audit-users.epf --manifest

Dry-run проходит обычные discovery/preflight и поиск платформы, показывает источники, порядок, основу, тип/путь артефакта, существование старого результата и runner. Он не создаёт артефакт или служебную ИБ, но может проверить executable. Отдельная следующая сборка заново проверяет входы.

По умолчанию артефакт размещается в build или artifacts_directory . --output задаёт один путь при одном выбранном проекте и разрешается относительно эффективного корня проекта/workspace. -p NAME выбирает members; --workspace собирает согласованный набор. До исполнения проверяются конфликты выходов. Частичная ошибка не должна выглядеть как успешная сборка всего workspace.

Основа для EPF/ERF

Для реквизитов, запросов и BSL с типами основной конфигурации нужна эта база. Она берётся из [analysis.configuration] либо из приложения member. library и прямой XML source используют описанный выше механизм подготовки. Без ссылки сборка остаётся прежней — с пустой ИБ; ссылка на типы базы при этом может быть отклонена самой платформой.

Готовый CF можно задать на один запуск:

eska build --base-configuration ./input/base.cf --manifest

Этот CF имеет приоритет над автоматической основой. XML-выгрузка и установленная БСП читаются как source, а все изменяемые данные платформы принадлежат служебным каталогам сборщика. Создание файла артефакта внутри reference-source не допускается.

Повторная сборка, паспорт и clean

Совместимая служебная ИБ переиспользуется. --recreate-infobase пересоздаёт её для выбранного build. При именованной библиотеке это не требует уничтожать проверенный общий CF и шаблон для других потребителей.

--manifest фиксирует source snapshot и создаёт рядом <artifact>.manifest.json . Паспорт содержит сведения об исходниках, результате, платформе и provenance; для XML-основы — также base_context со snapshot и библиотекой. При отсутствии доступного Git provenance не подделывается. Паспорт — не цифровая подпись релиза и не доказательство полного пользовательского тестирования.

Ошибки и отмена сохраняют прежний опубликованный результат и удаляют собственный staging по контракту операции. Оставшиеся повреждённые/чужие managed-данные не должны без проверки присваиваться следующему запуску.

eska clean
eska-build clean --workspace

Clean удаляет только управляемые служебные ИБ в выбранной области, проверяя ownership. Исходники, опубликованные артефакты, их паспорта и глобальная библиотека сохраняются. Это не универсальное удаление всего каталога build .

eska import ./incoming/new-version.epf --dry-run --format json
eska import ./incoming/new-version.epf

Import заменяет весь выбранный source, а не добавляет только новые файлы. Preview показывает изменения; перед подтверждением разберите свои локальные правки. В интерактивном режиме подтверждение явное, для сознательного неинтерактивного применения предусмотрен --force . Это разрешение конкретной замены, а не игнорирование структурных, типов или файловых проверок.

В workspace выбирается один текущий member или -p NAME ; все проекты разом не импортируются. Тип файла/выгрузки должен соответствовать проекту. Подготовка проходит в своём staging; обработанная ошибка откатывает прежние bytes. Recovery копии при конфликте сохраняются для разбирательства, а не удаляются как мусор. Build-версия при import используется для этого вызова; изменение входного файла не переписывает общую конфигурацию машины.

eska patch --base main --dry-run --format json
eska patch --base main --output ./build/hotfix.cfe

Это ограниченная операция по зафиксированным изменениям методов общих модулей между сравниваемой базой и HEAD. Если --base не задан, используется integration target workflow. Uncommitted-правка не становится содержимым patch.

Нужны чистое проверенное состояние, подходящий workflow/состав, поддержанные изменения и точная платформа. Для patch требуется соответствующий 1cv8 рядом с ibcmd ; Distrobox выбирается тем же явным способом. Preview полезен как самостоятельная проверка применимости и не запускает платформу. Неизвестное, неподдержанное или изменение за пределами контракта отклоняется с причиной. Существующий output-файл не перезаписывается.

Patch не является универсальным сборщиком всех изменений metadata, форм и данных. Конкретные допустимые виды изменений и предсказуемые отказы описаны в контракте patch-extension .

eska version --format json
eska version bump patch
eska version bump minor
eska version bump major

Читается и изменяется существующая Version в корневом descriptor 1С. Поддерживаются числовые компоненты и сохранение принятого формата по контракту; непонятная или отсутствующая версия не превращается в придуманное значение. Проверяются тип, snapshot и границы записи. Версию платформы в [build] это действие не меняет.

В workspace чтение может выбирать несколько -p или --workspace , bump должен однозначно выбрать целевой проект. eska --version , номер VSIX и номер Cargo crate — другие версии, не редактируемые этой командой.

Полный комплект и выборочные компоненты

eska update --check --format json
eska update
eska update --target-version VERSION --format json

--target-version принимает точный стабильный выпуск и не выполняет downgrade. Способ обновления зависит от происхождения установки: Cargo, полный installer, выборочный component-archive или ручная копия. Неопознанная установка не даёт обновлятору право выбрать случайный канал. Cargo checkout/dev binary обычно обновляется пересборкой, а не принудительной заменой опубликованным пакетом.

Полный установщик при повторном запуске обновляет весь согласованный комплект. В текущем коде распознавание cargo-dist receipt в CLI и Explorer ещё ожидает прежнего владельца 1c-tooling . Receipt с source.owner = "odineska" может быть отклонён как неподдерживаемая установка. До исправления этого ограничения используйте повторный запуск официального shell/PowerShell установщика из раздела установки ; публичный адрес проекта — odineska .

Для component ZIP предусмотрены свои status , install , inspect , remove в поставляемом components.py ; receipt доказывает владение конкретными файлами. Это отдельная утилита комплекта, не подкоманды eska update . Установка такого bundle через Python требует Python 3.11+; установленные Rust-инструменты и обычная подготовка через Explorer Python не требуют.

Управление из Explorer

Единый статус ESKA показывает подключённый project, состояния/версии/path форматтера и Analyzer. Отличайте «бинарник проверен» от «LSP запущен и готов». Нажатие статуса выполняет Обновить все компоненты ESKA и BSL Analyzer ; общее обновление уже является явным действием пользователя. Для выбора отдельных операций есть Управление компонентами и отдельные проверки обновлений.

Полный cargo-dist bundle обновляется целиком, раздельные управляемые компоненты — через свои ZIP. Собственный явно заданный executable автоматически не затирается. Повторное общее обновление ожидает ту же операцию; сбой одного компонента не мешает обработать остальные. Project/formatter/Analyzer проверяются независимо. Фоновые проверки выполняются не чаще суток для каждого инструмента; ручное действие не обязано ждать этот интервал.

На выборе/загрузке проверяются origin, хеши, состав архива, target и контракт исполняемого файла. Журнал, backups и общий claim нужны для согласованности обновлений разными frontend. После прерывания используйте соответствующую Восстановить установку… ; чужая новая правка сохраняет backups и требует решения. Просто удалить claim живого процесса — не способ исправить установку.

Что удалять и что сохранять

• Управляемый компонент удаляется штатным components.py remove с его receipt.
• Cargo-компонент удаляется средствами Cargo; ручная копия — по правилам вашей установки.
• VSIX удаляется менеджером расширений редактора; это отдельная установка.
• eska clean очищает служебные ИБ, а не пользовательскую библиотеку и не весь комплект.
• ~/.eska/lib содержит общие копии библиотек; не удаляйте их как кеш, если они нужны проектам.
• Глобальный config, private query-черновики и локальная активность — пользовательские данные. Удаление executable само по себе не означает намерение удалить их.

Полная процедура, схемы receipts и сценарии отказов приведены в поставке компонентов и обновлении CLI .

Настройки ниже — текущие публичные поля eska.explorer . Путь к executable указывается без дополнительных аргументов. auto языка дерева следует ru/en редактора. Пользовательская активность, сортировка и проектный выбор фильтра не являются новыми ключами JSON settings: они сохраняются собственным состоянием.

Действия палитры и контекстных меню

Некоторые действия показываются только для подходящего узла или состояния. Например, применение требует query-сессии, а включение проекта — отключённого member. Команда без подходящего контекста не обещает осмысленного результата.

Стандартные Format Document/Selection, Rename и действия языковых providers предоставляются через native API редактора, а не отдельными одинаковыми командами палитры ESKA. Их ограничения описаны в соответствующих разделах.

Начните с --version , doctor , context и точного пути выбранной программы. Не увеличивайте timeout, пока не ясно, какой процесс и какая стадия остановились.

Журнал Explorer

Показать журнал подключения открывает события подключения и компонентов: время, PID, executable, версия, request ID/метод, очередь, поколение, timeout и причина завершения. Блок от connection_connect до process_closed помогает отделить отказ domain от аварии процесса и задержки. Текст исходников и полные тела запросов не предназначены для диагностических событий.

Для сообщения об ошибке укажите ОС/CPU, редактор, источник установки и версии, project type, выбранное application, воспроизводимые шаги, ожидаемый/полученный результат и соответствующий участок журнала. Воспроизведение на копии проекта лучше случайного изменения рабочего source или удаления всех кешей.

Задача и ожидаемый результат

Команда поддерживает конфигурацию на БСП 3.1. Нужно доработать внешнюю обработку АудитПользователей : получить список действующих пользователей, исключить помеченных на удаление и недействительных, отсортировать по имени. Результат — исходники в Git и собранный audit-users.epf с паспортом, который можно передать на проверку в нужную базу 1С.

В этом маршруте ESKA выполняет получение XML, подключение базы БСП для анализа и сборки, навигацию, редактирование запроса, форматирование, проверки и сборку. Сама обработка/её форма создаётся средствами 1С: ESKA не выдаёт пустой каркас за готовый пользовательский интерфейс.

Что нужно подготовить

1. Существующий AuditUsers.epf в каталоге incoming . Это может быть простая внешняя обработка, созданная в Конфигураторе. Если уже есть XML, используйте отдельный путь init вместо new --from .
2. Совместимую установленную платформу с ibcmd ; ниже использована 8.3.27.2342 . Замените её своей точной версией.
3. Текущий комплект ESKA, Explorer и совместимый bsl-analyzer-app .
4. Git и имя/почту автора для workflow. Если Git пока не нужен, выберите --no-vcs и пропустите шаги start/save.
5. Базу для ручной приёмки, действительно использующую совместимую БСП. Версия master публичной библиотеки и версия вашей рабочей конфигурации не обязаны быть одинаковыми: для реального проекта используйте подходящую основу.

Структура рабочего каталога до начала:

work/
└── incoming/
    └── AuditUsers.epf

Работа выполняется в собственной копии, не внутри checkout исходного кода ESKA.

Шаг 1. Проверить инструменты и платформу

eska --version
eska-project --version
eska-build --version
eska-fmt --version
eska-check --version
eska-vcs --version
eska platform list --format json

Если платформа доступна только в Distrobox, один раз настройте пользовательский config с runner = "distrobox" , вашим container и platform_arch . На Windows используется host с собственным ibcmd.exe ; Linux-путь из примера не переносится в Windows-настройки.

Шаг 2. Получить проект из EPF

Из work :

eska new ./audit-users --from ./incoming/AuditUsers.epf --platform-version 8.3.27.2342 --workflow github-flow
cd audit-users
eska-project validate --format json

ESKA распакует файл, определит processing , создаст manifest, Git/workflow по выбранному режиму. В src найдите реальный XML и Ext/ObjectModule.bsl объекта: имя исходника определяется metadata, а не названием входного EPF.

Если XML уже был, альтернативный старт:

eska init ./audit-users --source src --name audit-users --workflow github-flow --platform-version 8.3.27.2342

Не выполняйте init повторно поверх созданного manifest. Если нужен только проект без Git/платформенной настройки, вместо общего init используйте eska-project init и настраивайте остальное явно.

Шаг 3. Подключить БСП

eska add ssl_3_1 --format json
eska-project context --format json

Если библиотеки нет, ожидайте первую установку в ~/.eska/lib/ssl_3_1 из master известного репозитория. Если копия уже зарегистрирована, она используется без загрузки и не обновляется скрыто. В manifest появится:

[analysis.configuration]
library = "ssl_3_1"

В context.sources должны присутствовать внешняя reference-конфигурация и ваша обработка; limited_context должен стать false . БСП не появляется как второй writable member и не включается целиком в Git проекта.

Для точной базы заказчика вместо публичной master зарегистрируйте собственную выгрузку как company_base в глобальном каталоге и выберите её. Это особенно важно, если в рабочей конфигурации изменены стандартные поля или расширения.

Шаг 4. Начать Git-задачу

После создания проекта сделайте первый commit с исходниками и подключением библиотеки. new создаёт репозиторий, но не первый commit:

eska status
eska save --dry-run
eska save -m "Создан проект обработки и подключена БСП"
eska start AUDIT-42

Если проект уже имел историю, сохраните только осознанно выбранные изменения: start не прячет dirty-состояние автоматически. Перед save проверьте preview. Для GitHub Flow создаётся task-ветка по политике. Разрешение на создание ветки в этом учебном проекте обработки не означает переключение ветки checkout ESKA.

Шаг 5. Открыть Explorer и выбрать основу

Откройте audit-users в VS Code/VSCodium. При необходимости задайте три пути:

{
  "eska.explorer.executable": "/path/to/eska-project",
  "eska.explorer.analyzerExecutable": "/path/to/bsl-analyzer-app",
  "eska.explorer.formatterExecutable": "/path/to/eska-fmt"
}

Это шаблоны абсолютных путей workspace host, не готовые Linux-пути для всех ОС. Найдите объект/модуль в дереве либо откройте файл и выполните Показать открытый файл в дереве eska . Проверьте отдельные состояния project и языкового сервиса. Конфликтующее BSL-расширение нужно выбрать/отключить явно.

При открытии BSL будет подготовлен управляемый config. Для явной проверки из CLI:

eska-project analyzer-config status --format json
eska-project analyzer-config prepare

Если Analyzer установлен только в частном каталоге Explorer и не доступен в PATH, передайте CLI --analyzer или ESKA_BSL_ANALYZER . Настройка VS Code не является глобальной переменной окружения для любого внешнего терминала.

Шаг 6. Написать метод обработки

В модуле объекта разместите функцию:

Функция ПолучитьАктивныхПользователей() Экспорт

    Запрос = Новый Запрос;
    Запрос.Текст =
        "ВЫБРАТЬ
        |    Пользователи.Ссылка КАК Пользователь,
        |    Пользователи.Наименование КАК Имя
        |ИЗ
        |    Справочник.Пользователи КАК Пользователи
        |ГДЕ
        |    НЕ Пользователи.ПометкаУдаления
        |    И НЕ Пользователи.Недействителен
        |УПОРЯДОЧИТЬ ПО
        |    Имя";

    Возврат Запрос.Выполнить().Выгрузить();

КонецФункции

В использованной выгрузке БСП 3.1 справочник называется Пользователи , а поле недействительности — Недействителен . Проверьте их в своей базе через metadata- каталог/переходы, если используете другую основу. Метод возвращает таблицу значений; способ показа, команда формы или экспорт результата относятся к самой обработке и стандартным механизмам 1С.

Для работы с запросом поставьте курсор внутрь литерала и выберите Редактировать запрос отдельно . Откройте конструктор:

1. В источниках выберите Справочник.Пользователи с alias Пользователи .
2. В полях добавьте ссылку и наименование; задайте выходные aliases.
3. В условиях задайте исключение пометки удаления и недействительных.
4. В порядке — имя по возрастанию.
5. Сравните preview с исходным запросом и завершите конструктор.
6. Сохраните черновик, затем явно Применить запрос к модулю .
7. Проверьте native Undo/Redo и отдельно сохраните модуль.

Ctrl+S в BSL-черновике не заменяет шаг Apply. При конфликте сначала сравните владельца; не переносите запрос в изменённый модуль по устаревшей позиции.

Шаг 7. Форматирование и проверка

eska fmt
eska fmt --check --format json

Подготовьте каталог reports любым стандартным способом вашей ОС и добавьте строку /reports/ в .gitignore , чтобы большой отчёт не попал в commit. Затем:

eska check --format json --report ./reports/check.json

Смотрите exit code и полный JSON-результат. Ноль ошибок по установленному порогу — не обещание отсутствия всех warnings: ограничения задаются в [tools.eska-check] . Если команда не завершилась, исправьте причину, а не передавайте partial-отчёт как успешную приёмку. Реальные данные, права и результаты выборки нужно проверить в подходящей базе 1С отдельно.

Reference-БСП входит в полный анализ. Поэтому даже небольшой собственный модуль может получить exit 1 из-за диагностик библиотечных модулей. В проверенном примере отчёт имел complete = true , но порог ошибок был превышен в БСП; у собственной функции оставалась подсказка CodeOutOfRegion об оформлении области. Это завершённая проверка с замечаниями, а не успешный quality gate.

Шаг 8. Собрать файл с базой БСП

eska build --dry-run --format json
eska build --output ./build/audit-users.epf --manifest

В preview проверьте XML/library-основу и точную платформу. При первом запуске может потребоваться подготовка CF и template ИБ библиотеки. Повторные обработки и отчёты с той же основой переиспользуют проверенный результат, получая свои ИБ. Никакого ручного копирования БСП в src обработки не требуется.

Ожидаются:

build/
├── audit-users.epf
└── audit-users.epf.manifest.json

В паспорте для этой основы должен быть source.base_context с библиотекой и snapshot. При необходимости выберите явно готовый CF через --base-configuration , но не смешивайте случайную базу с ожидаемой основой.

Шаг 9. Проверить roundtrip и поведение

Дополнительная проверка собранного файла без замены исходного проекта:

eska-build unpack ./build/audit-users.epf ../audit-users-roundtrip --platform-version 8.3.27.2342 --format json

Destination должен отсутствовать. Сравните модуль и metadata-имя в новой выгрузке с исходниками. Это проверяет сохранение файла платформой, но не выполняет запрос.

Для функциональной приёмки используйте тестовую ИБ нужной конфигурации. Вызов из подходящего server-контекста 1С выглядит так:

Обработка = ВнешниеОбработки.Создать(ПолноеИмяФайла, Ложь);
Пользователи = Обработка.ПолучитьАктивныхПользователей();

Путь должен быть доступен тому host, где выполняется код 1С; права на создание внешних обработок определяет ваша база. Проверьте обычного активного, недействительного и помеченного на удаление пользователя. В результате должны остаться только активные, с колонками Пользователь и Имя , упорядоченные по имени. ESKA не создаёт этих тестовых пользователей и не выполняет запрос за вас.

Шаг 10. Проверить diff и сохранить работу

eska diff --semantic
eska save --dry-run
eska save -m "Добавлен аудит активных пользователей БСП"

Проверьте, что в commit попали метод и переносимые настройки, а не библиотека, служебная ИБ или частный машинный config. Отправка ветки и review выполняются обычным процессом команды. finish вызывается после удовлетворения workflow политики, не сразу после создания commit.

Как этот же пример вырастает в workspace

Добавьте проект отчёта и используйте одну reference-базу:

[workspace.members.audit]
configuration = { library = "ssl_3_1" }
external_objects = ["src/audit-users", "src/audit-report"]

[analysis]
default_application = "audit"

[build]
platform_version = "8.3.27.2342"

У каждого member должен быть свой валидный source и eska.toml с уникальным именем. Обработка и отчёт используют одну основу, но собираются в разные файлы и свои изменяемые ИБ. eska build --workspace --dry-run покажет оба плана. В большом workspace неиспользуемый отчёт можно отключить в Explorer; это не исключит его из явного CLI build/CI. Фильтр скрытия отдельно влияет на группы дерева.

Что проверено в примере

Команды сверены с текущей справкой. В отдельном playground проверены подключение существующей библиотеки, контекст из двух источников, первый commit, создание task-ветки, форматирование, полный анализ, build и распаковка результата настоящей платформой 8.3.27.2342 в Linux ARM64 / Distrobox ALT. Текст модуля сохранился после roundtrip; manifest указал основу ssl_3_1 . Анализ завершился с exit 1 из-за диагностик БСП; успешного прохождения порога пример не заявляет. Первая загрузка master и общий кеш имеют отдельные проверки библиотеки. Выборка на пользовательских данных, форма обработки и бизнес-приёмка в рабочей ИБ не подменяются roundtrip-проверкой.

Только дерево и свойства

Установить eska-project и Explorer → eska-project init существующей выгрузки → подключиться → найти metadata → свойства/source. Git, анализатор и 1С не нужны, пока не выполняются соответствующие операции.

Полный цикл разработки

Подключить или распаковать source → настроить приложение/workflow → start → изменить свойства/модуль/запрос → fmt/check → build → diff/save → review команды. Пример с БСП выше показывает конкретные команды этого маршрута.

Получить XML из EPF/ERF и собрать обратно

eska-build unpack в новый каталог → eska-project init --source . → при необходимости library/base CF → eska-build build → unpack нового файла в другой отсутствующий каталог → сравнение результата.

Полный CI-анализ

Закрепить комплект и Analyzer → получить исходники → проверить конфиг/контекст → eska fmt --check → eska check --application APP --report FILE --format json → сохранить отчёт и exit code. Сборка 1С — отдельный шаг, если доступна платформа.

Отдельный сборочный агент

Установить eska-build и нужную платформу → настроить machine runner → получить XML → build preview → build с manifest → опубликовать полученный артефакт штатным CI. Оболочка eska , GUI и LSP не обязательны.

Расширение вместе с базой

Объявить роли в workspace.members.APP → указать dependencies/scope → проверить context --application APP → анализировать выбранное приложение → собрать конкретный extension или весь workspace. Сборка CFE не устанавливает расширение в пользовательскую ИБ.

Прерваться и вернуться к задаче

Посмотреть repository-wide состояние → shelve preview → shelve → switch на base или другую существующую задачу → вернуться → unshelve preview → unshelve. Сохраняются границы staged/unstaged и non-ignored untracked.

Обновить source из нового файла 1С

Получить новый CF/CFE/EPF/ERF → import preview → разобраться с локальными изменениями → подтвердить одну выбранную замену source → validate/diff/check/build. Не заменять import-командой соседние members или машинный config.

Проверить применимость patch-extension

Зафиксировать поддержанные изменения общих модулей → patch --base REV --dry-run → прочитать план/причину отказа → при поддержанной области собрать в новый CFE точной платформой с ibcmd / 1cv8 . Неподдержанные изменения требуют обычного пути расширения, а не обхода preflight.

Справочник всех публичных команд построен по текущей справке шести бинарников. Он включает metadata inspect/types/choices/check/apply, rename/recovery, analyzer-config status/prepare/migrate, версии и selectors, платформенные операции, все workflow/полки, update и опции форматтера.

Точная справка своей установленной сборки всегда доступна локально:

eska --help
eska-project --help
eska-check --help
eska-fmt --help
eska-build --help
eska-vcs --help

Roadmap содержит также ещё не реализованные возможности. Исторический отчёт измеряет свой этап/среду; актуальные пользовательские действия определяет код и это руководство, а не старое «следующая задача» внутри отчёта.