Расширение CPQ-BML для VS Code

Профессиональное многофункциональное расширение Visual Studio Code для языка Oracle CPQ BigMachines Language (BML). Это расширение представляет собой идеальную среду разработки для специалистов по CPQ, предоставляя IntelliSense, подсветку синтаксиса, надежную диагностику/линтер, форматирование в масштабе рабочей области, удаленную интеграцию REST и ИИ-ассистента на базе MCP.

📖 Содержание

• Возможности вкратце

• Ключевые возможности

  • 1. Языковая поддержка и IntelliSense

  • 2. Форматтер и Beautifier рабочей области

  • 3. BML-линтер и диагностика в реальном времени

  • 4. Улучшенные комментарии и заголовки документации

  • 5. Интерактивная панель настроек WebView

  • 6. Удаленная интеграция REST и синхронизация

  • 7. Сервер Model Context Protocol (MCP) для интеграции с ИИ

  • 8. Интеграция навыков ИИ-агентов (AgentSkills.io)

  • 9. Цветовые темы BML

• ⌨ Справочник команд

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

• 🔧 Настройки форматтера (.bmlbeautifyrc)

• 📂 Структура проекта

• 🚀 Установка и настройка

• 💻 Локальная разработка

• 📄 Лицензия и журнал изменений

Related MCP server: Salesforce CLI MCP Server

✨ Возможности вкратце

• 🎨 Цветовые темы BML: четыре адаптированные темы редактора с глубокой семантической раскраской токенов.

• 💡 IntelliSense: контекстное автодополнение, подсказки по сигнатурам и всплывающие подсказки по параметрам.

• 🔍 Линтер и диагностика: более 70 проверок в реальном времени для выявления проблем безопасности (SQL-инъекции, захардкоженные секреты), гарантированных ошибок компиляции/выполнения, сверенных с официальной документацией Oracle по BML, устаревших API и логических ошибок.

• 📖 Офлайн-просмотр справки: документация в стиле Docusaurus (с блоками :::note/:::warning) мгновенно открывается из любой всплывающей подсказки — интернет-соединение не требуется.

• 🛠 Форматирование всей рабочей области: рекурсивное форматирование каталогов или выбранных папок.

• ☁ Интеграция REST: синхронизируйте, компилируйте, проверяйте, отлаживайте и развертывайте функции BML непосредственно в удаленных экземплярах CPQ.

• 🤖 Подключение ИИ-агентов (MCP): создавайте и отлаживайте код с помощью ИИ через защищенный локальный сервер Model Context Protocol (MCP).

• 🧠 Навыки ИИ-агентов (AgentSkills.io): включает 8 предварительно скомпилированных семантических навыков для внедрения глубоких знаний предметной области CPQ и BML в ИИ-ассистентов, таких как Claude Code.

• 📝 Улучшенные комментарии: различимое визуальное оформление задач, тегов, директив и заголовков функций.

🔍 Ключевые возможности

1. Языковая поддержка и IntelliSense

• Богатая подсветка синтаксиса: полная поддержка грамматики для методов BML, операторов управления потоком (if, elif, else, for), запросов к базе данных (bmql), операторов и литералов.

• Библиотека сниппетов: мгновенные контекстные каркасы кода для циклов, типовых операций со строками, манипуляций с JSON и системных функций.

• Автодополнение и подсказки: сигнатуры, возвращаемые типы и списки параметров появляются по мере ввода в соответствии со спецификациями Oracle CPQ.

• Офлайн-просмотр справки: каждая всплывающая подсказка для встроенной функции содержит ссылку 📖 Читать офлайн-справку, которая открывает быструю автономную панель документации — интернет-соединение не требуется. Она отображает блоки в стиле Docusaurus :::note/:::tip/:::warning как полноценные цветные рамки (а не необработанный Markdown), подобранные под тему вашего редактора, и переиспользует одну панель при повторных открытиях, поэтому повторные обращения выполняются мгновенно, а не запускают предварительный просмотр каждый раз.

• Интеграция проверки орфографии: предварительно настроена с определениями cspell.json для автоматической поддержки функций, специфичных для CPQ (strtojavadate, jsonarrayrefid, bmql и т. д.), без срабатывания ошибок правописания.

2. Форматтер и Beautifier рабочей области

• Рекурсивное форматирование: выполните CPQ-BML: Beautify / Format All BML Files in Workspace (cpqBml.beautifyWorkspace), чтобы рекурсивно отформатировать файлы BML.

• Интерфейс выбора папок: многоселективный элемент быстрого выбора (quick pick) отображает корневые пути и папки рабочей области, позволяя выбирать конкретные модули.

• Соглашения CPQ: стандартизирует отступы, пробелы, расположение скобок и обеспечивает соблюдение правил регистра, например автоматическую замену ключевого слова not на обязательное для компилятора NOT.

• Гибкая настройка: поведение форматтера можно переопределять для конкретных каталогов с помощью локальных JSON-файлов .bmlbeautifyrc.

3. BML-линтер и диагностика в реальном времени

Расширение включает собственный статический анализатор BML для выявления дефектов, антипаттернов и уязвимостей до загрузки кода в CPQ:

Инлайн-подавления

Вы можете точечно обходить отдельные правила линтера с помощью комментариев. Директивы нечувствительны к регистру и работают как в строчных, так и в блочных комментариях:

// bml-lint-disable-file               ← suppress everything in this file
// bml-lint-disable                    ← start of suppressed block
// bml-lint-enable                     ← end of suppressed block
x = 10 / 0; // bml-lint-disable-line  ← suppress diagnostics on this line
/* bml-lint-disable-next-line */       ← suppress all diagnostics on the next line
// bml-lint-disable-next-line bml-operator-fix, bml-spelling-error
x = 10 / 0;                            ← only those two codes are suppressed

Поддерживаемые стили директив:

[!TIP] Если опустить список кодов, подавляются все диагностики; перечисление одного или нескольких кодов bml-* подавляет только эти конкретные правила. Для многих диагностик доступны быстрые исправления (значок лампочки; Ctrl+. или Cmd+.), позволяющие мгновенно автоматически устранить проблемы со стилем точек с запятой, опечатки в переменных, ошибки форматирования или устаревшие API.

4. Better Comments и заголовки документации

Повышайте читаемость кода, оформляя комментарии в виде категоризированных задач, статусов или визуальных выделений.

Стилизация пользовательских тегов

Директивы и блочные заголовки

• Директивы линтера и форматирования: комментарии вроде // bml-lint-disable-line или /* beautify ignore:start */ оформляются характерной фиолетовой рамкой, чтобы управляющие теги оставались заметными, но не мешали.

• Стандартные заголовки документации: блоки документации функций, начинающиеся с Function Name:, Description:, Inputs: или Returns:, автоматически группируются и окрашиваются светло-голубым курсивом.

5. Интерактивная панель настроек WebView

Настраивайте подключения и функции с помощью специальной графической панели через CPQ-BML: Open Settings (cpqBml.settings.open):

• Вкладка «Подключение»: укажите URL сайта вашего сервера, схему аутентификации и активные учётные данные API.

• Вкладка «Окружения»: храните несколько песочниц (например, Dev, Test, UAT, Production) для переключения активных целевых сред.

• Вкладка «Функции»: включайте и отключайте правила линтера, стилизацию Better Comments и общие вспомогательные функции расширения в понятном интерфейсе.

• Интеграция безопасного хранилища: напрямую работает с VS Code Secret Storage API. Учётные данные, пароли и токены сохраняются в связке ключей вашей ОС и никогда не записываются в конфигурационные файлы открытым текстом.

• Проверка подключения: проверка в один клик подтверждает удалённые учётные данные и связь с сайтом непосредственно перед применением настроек.

6. Удалённая REST-интеграция и синхронизация

Выполняйте рабочие процессы разработки CPQ полностью внутри локального редактора:

• Получение кода: загружайте функции Utility Library и функции Commerce Process (cpqBml.rest.pullLibraryFunctions, cpqBml.rest.pullCommerceFunctions) с удалённого сервера вместе с их метаданными.

• Удалённая валидация и компиляция: запустите CPQ-BML: Validate Current File Against CPQ, чтобы вызвать серверный компилятор Oracle для активного документа и вывести диагностику синтаксиса локально.

• Отладчик песочницы: нажмите CPQ-BML: Debug Current Function on CPQ, чтобы открыть диалог выбора параметров, отправить тестовые значения в среду выполнения песочницы и просмотреть стандартные выходные данные в терминале.

• Управление развёртыванием: разворачивайте изменённый код мгновенно — сохранением отдельных файлов, пакетными развёртываниями библиотеки утилит или полными конфигурациями commerce-процессов.

7. Сервер Model Context Protocol (MCP) для интеграции с ИИ

Расширение запускает встроенный защищённый сервер Model Context Protocol (MCP), позволяющий ИИ-ассистентам для программирования (таким как Claude Code) безопасно просматривать, отлаживать и разворачивать код в вашем рабочем пространстве.

graph TD
    subgraph External Environment
        AI[AI Client / Claude Code]
    end
    subgraph VS Code Host
        MCP[MCP Server <br> 127.0.0.1:47821]
        Ext[CPQ-BML Extension]
        Sec[OS Keychain / Secret Storage]
    end
    subgraph Cloud Service
        CPQ[Oracle CPQ Sandbox / Instance]
    end

    AI -- "MCP JSON-RPC Protocol" --> MCP
    MCP -- "Internal Bridge (No Auth Shared)" --> Ext
    Ext -- "Retrieves Credentials" --> Sec
    Ext -- "REST API Requests" --> CPQ

Модель безопасности

Учётные данные, cookie-файлы и секретные токены хранятся в защищённом контексте расширения. MCP-сервер не раскрывает эти значения ИИ-клиенту. Он действует только как исполнитель, направляя запросы через локальный экземпляр расширения.

Изоляция работы ИИ

Когда ИИ-агент запрашивает изменение или загрузку файла через MCP, расширение создаёт изолированную рабочую копию [variableName]-AI.bml. Это не позволяет агенту перезаписывать ваши локальные скрипты и гарантирует, что вы сможете просмотреть изменения с помощью инструмента сравнения (diff) перед их фиксацией.

Предоставляемые MCP-инструменты

• list_util_functions: перечисляет все функции удалённой библиотеки утилит.

• list_commerce_functions: перечисляет все commerce-скрипты в экземпляре CPQ.

• pull_function: загружает стандартный BML и сохраняет локально в виде файлов .bml и -meta.json.

• save_function: применяет обновления в среде CPQ.

• validate_function: запрашивает серверный компилятор CPQ для проверки изменений.

• debug_function: выполняет функцию удалённо с тестовыми параметрами.

• deploy_function / mass_deploy_util_functions: разворачивает отдельные или пакетные функции.

• deploy_commerce_process: публикует всю конфигурацию процесса.

• create_util_function: создаёт каркас и публикует совершенно новую функцию утилиты.

• create_override: создаёт редактируемое переопределение стандартной (системной) функции — оно требуется до того, как функцию можно будет проверить, сохранить или развернуть.

• remove_override: возвращает переопределённую стандартную функцию к системной версии CPQ (разрушающее действие; требует confirm:true).

8. Интеграция навыков ИИ-агентов (AgentSkills.io)

CPQ-BML поставляется с предварительно скомпилированным набором «Agent Skills», разработанным в соответствии со спецификацией AgentSkills.io. Это внедряет глубокие знания предметной области в ИИ-ассистентов для программирования (таких как Claude Code или Cursor), которые нативно распознают эти навыки при взаимодействии с вашим рабочим пространством.

Настройка без конфигурации: Когда вы включаете MCP-сервер в настройках расширения, CPQ-BML автоматически регистрирует эти навыки в вашем рабочем пространстве. Выполнять какие-либо ручные команды настройки не нужно! Чтобы пакет расширения оставался компактным, а рабочее пространство — чистым:

• Огромная семантическая база знаний сжимается в высокооптимизированный архив .br на этапе сборки.

• Во время выполнения расширение прозрачно распаковывает эти знания в защищённый каталог VS Code Global Storage.

• Оно автоматически создаёт файлы-указатели (например, .agents/skills.json, CLAUDE.md, .cursorrules) в вашем рабочем пространстве, которые направляют вашего ИИ-ассистента к глобальному хранилищу.

Вместо того чтобы ваш ИИ вслепую пытался редактировать BML, исходя из стандартных предположений JavaScript, расширение предоставляет контекстно-зависимые рекомендации по:

• Уникальным ограничениям синтаксиса BML (например, отсутствие var или let, == вместо ===, NOT вместо !).

• Синтаксису Direct Database Access и BMQL.

• Лучшим практикам работы со словарями, JSON и строками в CPQ.

• Правильному использованию CPQ-BML MCP-инструментов (таких как pull_function, save_function, validate_function) в рамках сквозного рабочего процесса разработки с ИИ.

ИИ динамически получает эти контекстные правила в реальном времени, устраняя разрыв между стандартной генерацией кода LLM и проприетарной средой выполнения Oracle CPQ.

9. Цветовые темы BML

В состав расширения входят четыре специализированные темы:

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

[!NOTE] Цветовая подсветка синтаксиса определяется темой. Расширение не навязывает внешним темам свои переопределения. Выберите одну из тем BML (Ctrl+K Ctrl+T / Cmd+K Cmd+T), чтобы увидеть цвета токенов, специфичных для CPQ.

Детали цветов

• Категоризированные функции: отдельные цвета назначаются категориям встроенных функций (например, строки, математика, даты, БД/BMQL, массивы, URL, словари, JSON, XML).

• Доступ к атрибутам: переменные-члены CPQ (такие как line.attribute и transaction.attribute) выделяются иначе, чем обычные переменные.

• Операторы: математические, логические операторы и операторы присваивания оформляются по-разному, помогая замечать опечатки в синтаксисе, например написание = вместо ==.

⌨ Справочник команд

Используйте палитру команд (Ctrl+Shift+P / Cmd+Shift+P), чтобы вызвать эти действия:

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

Настройте эти параметры в settings.json в VS Code или через редактор параметров:

{
  "cpqBml.connection.enabled": true,
  "cpqBml.connection.siteUrl": "example.bigmachines.com",
  "cpqBml.connection.authMethod": "basic",
  "cpqBml.connection.username": "api_developer",
  "cpqBml.connection.environments": [
    {
      "name": "Dev Sandbox",
      "siteUrl": "dev.bigmachines.com",
      "username": "api_developer",
      "authMethod": "basic"
    }
  ],
  "cpqBml.rest.restVersion": "v18",
  "cpqBml.rest.commerceProcess": "oraclecpqo",
  "cpqBml.rest.commerceDocument": "transaction",
  "cpqBml.rest.pullFolder": "library",
  "cpqBml.features.lint": true,
  "cpqBml.features.comments": true,
  "cpqBml.mcp.enable": false,
  "cpqBml.mcp.port": 47821,
  "cpqBml.mcp.logToTerminal": false,
  "cpqBml.debug.logRestDetails": false,
  "cpqBml.debug.logOutputToFile": false
}

🔧 Параметры форматирования (.bmlbeautifyrc)

Поместите файл конфигурации .bmlbeautifyrc в любую директорию, чтобы настроить правила форматирования BML. Параметры созданы по образцу структур JS-beautify:

{
  "indent_size": 2,
  "brace_style": "collapse",
  "preserve_newlines": true,
  "max_preserve_newlines": 1,
  "space_before_conditional": true
}

📂 Структура проекта

Проект имеет модульную структуру с четким разделением сервисов редактора BML, REST-сетевого взаимодействия, тестовых утилит и интеграции с ИИ:

├── app/                              # Extension Core Source Code
│   └── lang/                         # Language Intelligence & Tooling
│       ├── beautify/                 # Code Formatter & Beautification Engine
│       │   ├── commandWorkspace.js   # Workspace-wide mass formatter
│       │   ├── docHeader.js          # Auto-insert /// doc block comment completion
│       │   └── index.js              # Formatting core config/integration
│       ├── comments/                 # Better Comments parser (tags, directives, headers)
│       ├── intellisense/             # IntelliSense (autocompletions, hovers, signatures)
│       │   ├── index.js              # Go to definition, References, Rename registrations
│       │   ├── workspaceIndex.js     # Codebase scanner indexing util.* & commerce.*
│       │   ├── helpViewer.js         # Fast offline docs webview (Docusaurus-style ::: admonitions)
│       │   └── custom-snippets.json  # Smart snippet database
│       ├── lint/                     # Real-time Native Static Diagnostics
│       │   ├── lint.js               # Central rule runner pipeline
│       │   ├── nullSafety.js         # Checks nullable results of bmql() / get()
│       │   ├── infiniteLoop.js       # Identifies empty or non-populating loops
│       │   └── best-practices/       # BMQL safety, security, doc-verified guaranteed failures, etc.
│       ├── mcp/                      # Model Context Protocol AI Tool Integration
│       │   ├── server.js             # Local MCP server implementation
│       │   └── tools/                # Declarative AI helper tools
│       ├── metrics/                  # Code quality analysis WebView Dashboard
│       │   ├── complexity.js         # Cyclomatic complexity & nesting depth calculations
│       │   ├── report.js             # Metrics accumulator logic
│       │   └── reportWebview.js      # WebView layout rendering
│       ├── rest/                     # Oracle CPQ REST Client Integration
│       ├── settings-panel/           # Extension settings GUI dashboard WebView
│       ├── testing/                  # Safe sandboxed local execution & unit testing
│       │   ├── runner.js             # Sidecar *.bmltest.json executor
│       │   └── snapshot.js           # Regression snapshot comparisons
│       └── xslt/                     # XSLT formatting, & linking features
│
├── test/                             # Automated Test Suites
│   ├── linter/                       # Tests for suppressions & core linter behaviors
│   ├── mcp/                          # Tests for local MCP tool server
│   └── rest/                         # Offline mocked testing for CPQ REST sync
│
├── extension.js                      # Extension Activation/Deactivation Entry-point
├── package.json                      # VS Code Extension manifest & command declarations
└── README.md                         # Project documentation

🚀 Установка и настройка

1. Установка из Marketplace: Найдите «CPQ-BML» на панели расширений VS Code (Ctrl+Shift+X / Cmd+Shift+X) и нажмите Установить.

2. Первичная настройка: При первой загрузке автоматически откроется Панель настроек.

3. Настройка окружений: Укажите данные вашего сайта, выберите метод аутентификации и проверьте подключение.

4. Безопасное хранение учетных данных: Используйте команды CPQ-BML: Set CPQ Password или CPQ-BML: Set CPQ Auth Token, чтобы безопасно хранить ваши пароли или ключи.

💻 Локальная разработка

Если вы хотите запустить, доработать или внести вклад в развитие этого расширения:

Предварительные требования

• Node.js (рекомендуется v22 или новее)

• Visual Studio Code

Шаги

1. Клонируйте репозиторий:

   git clone https://github.com/vikram-vn/cpq-bml.git
   cd cpq-bml

2. Установите зависимости:

   npm install

3. Скомпилируйте проект:

   npm run compile

4. Запустите хост расширения: Откройте корневую рабочую область в VS Code и нажмите F5 (или перейдите в Run and Debug -> Launch Extension). Откроется окно хоста разработки расширения, где вы сможете сразу проверить поддержку BML.

📄 Лицензия и журнал изменений

• Лицензия: Этот проект распространяется по лицензии MIT License.

• Журнал изменений: Подробная история версий, дополнения и обновления доступны в CHANGELOG.md.

• Отказ от ответственности: Это расширение является независимым проектом сообщества, не аффилированным с Oracle Corporation или BigMachines, не спонсируемым и не одобряемым ими, а также никак иначе с ними не связанным.