CPQ-BML Enterprise VS Code Extension Suite

A modern, high-performance Language Server, Static Analysis Engine, Visual Architecture Visualizer, and AI Model Context Protocol (MCP) Suite for BigMachines CPQ Language (BML) and Oracle CPQ Cloud.

📑 Table of Contents

1. Executive Overview
2. Subsystem Architecture & Deep Dive
   • Visual Dependency & Blast Radius Graph
   • Cloud Property Inspector & Virtual Documents
   • Modular IntelliSense, Autocomplete & Navigation
   • Deterministic BML Beautifier & Formatter
   • Real-Time Static Analysis & Security Linter
   • Model Context Protocol (MCP) AI Suite
   • Offline BML Sandbox & Logic Scratchpad
   • Cloud REST Sync & Safe 3-Way Diff
   • Code Quality & Software Science Metrics
   • Document Engine XSLT & XML Subsystem
   • Standalone Headless LSP Daemon
3. BML Built-in Function Domain Catalog (13 Categories)
4. Command Palette & Keyboard Shortcut Cheat Sheet
5. Configuration & Environment Reference
   • Cloud Environment (.env)
   • Beautifier Configuration (.bmlbeautifyrc)
   • VS Code Settings Matrix
6. Enterprise Best Practices & Governor Limits
7. License & Disclaimer

1. Executive Overview

Historically, developing BigMachines CPQ BML (BigMachines Extensible Language) has been constrained by browser-based textarea editors, lack of static type checking, zero cross-file refactoring tools, and fragile manual deployments.

The CPQ-BML Extension Suite transforms enterprise CPQ engineering into a first-class IDE experience:

• Offline-First Productivity: Develop, browse, lint, format, and execute BML scripts locally with instant responsiveness and zero cloud latency.
• Deterministic AST Architecture: Fully parsed BML Abstract Syntax Trees (AST) ensure reliable formatting, semantic analysis, and boundary enforcement.
• Enterprise Security & Compliance: Static linter blocks SQL/BMQL injection vulnerabilities, infinite loops, and governor limit breaches before code ever reaches production.
• Modern Webview Cockpits: React 19 and Pure CSS dashboards power the Cloud Property Inspector, Visual Dependency Graph, and Interactive Settings Panel.
• AI-Native Engineering (MCP): Implements the Model Context Protocol (MCP) to integrate autonomous AI pair-programmers (Cursor, GitHub Copilot, Google Antigravity, Claude Desktop, ChatGPT) with 24 dedicated tools for CPQ exploration, validation, debugging, and deployment.

2. Subsystem Architecture & Deep Dive

2.1. Visual Dependency & Blast Radius Graph

Powered by Cytoscape.js and React 19, the Visual Dependency Graph resolves the complete topology of your CPQ implementation:

• Interactive Node Exploration: Visualizes function-to-function calls (util.pricing.*), Commerce Process rules (Constraints, Hiding, Validation), Commerce Actions (Clean Save, Submit, Modify), and Configuration attributes.
• Blast Radius Calculation: When modifying a core library function, select Calculate Blast Radius to highlight every upstream caller, rule, and transactional action impacted across your entire codebase.
• Focus & Isolation Modes: Filter by depth, isolate specific namespaces (util.bom.*), or collapse leaf nodes to analyze high-level enterprise architecture.
• Command: CPQ-BML: Open Architecture & Blast Radius Dependency Graph (cpqBml.showDependencyGraph).

┌───────────────────────────────────────────────────────────┐
│              Visual Dependency & Blast Radius             │
│                                                           │
│  [ Commerce Rule: HideDiscount ]                          │
│          │                                                │
│          ▼                                                │
│  [ Action: CleanSave ] ──► [ util.pricing.calculateTotal ] │
│                                      │                    │
│                                      ▼                    │
│                        [ util.math.roundCurrency ]        │
└───────────────────────────────────────────────────────────┘

2.2. Cloud Property Inspector & Virtual Documents

A dedicated, high-performance metadata inspection panel that connects directly to Oracle CPQ Cloud REST APIs:

• Live Component Browsing: Search, inspect, and filter Commerce Attributes, Actions, Rules, Integrations, Data Tables, and Parts without opening a web browser.
• Read-Only Virtual Documents (cpq-cloud://): Inspecting a cloud script or payload opens a virtual document buffer. This prevents accidental dirty edits or local workspace pollution while allowing full syntax highlighting and code copying.
• Cursor Code Injection: Single-click action to inject attribute variable names (line.discount_l), JSON paths, or library calls directly into your active editor cursor.
• Command: CPQ-BML: Inspect Component / Action / Attribute (cpqBml.cloud.inspectIntegration).

2.3. Modular IntelliSense, Autocomplete & Navigation

The IntelliSense engine provides context-aware completions, signature tooltips, and cross-file symbol resolution:

• Modular Built-in Functions: 153 BML built-in functions organized into 13 dedicated categories (array, bmql, bom, commerce, date, dictionary, json, math, session, string, system, url, xml). Each function includes full signatures, parameter types, documentation, and working examples.
• Dynamic BMQL $variable Completions: Inside any bmql("SELECT ... WHERE col = $...") query literal, typing $ introspects in-scope local variables and suggests type-compatible variables.
• Object Member Completion:
  • Dotted attribute access: line. suggests line-level attributes; transaction. suggests header attributes.
  • Client-side CPQJS access: CPQJS. suggests client extension methods (actionExists, getAttributes, etc.).
  • Library namespaces: util. suggests folders; util.pricing. suggests functions within that folder.
• Code Navigation:
  • Go to Definition (F12): Jumps to the exact line of any workspace library function or local variable declaration.
  • Find All References (Shift+F12): Locates every call site of a library function across all workspace .bml files.
  • Call Hierarchy (Shift+Alt+H): Visualizes callers and callees in VS Code's native Call Hierarchy tree.
  • Inlay Parameter Hints: Displays parameter names (replace(str:, oldStr:, newStr:)) and inferred return types inline.

2.4. Deterministic BML Beautifier & Formatter

An advanced, AST-aware formatting engine built specifically for BML syntax nuances:

• Minimal Range Diff Optimizer: Calculates surgical edit ranges rather than replacing the entire document buffer, preserving breakpoints, cursor location, and clean undo history.
• On-Type Formatting: Automatically cleans and aligns the current statement upon typing ; or block closure }.
• Directives Support:
  • /* beautify ignore:start */ and /* beautify ignore:end */ protect custom ASCII art, complex mathematical matrix formulas, or raw string blocks from modification.
• Configurable Rules (.bmlbeautifyrc):
  • Clean camelCase configuration options: indentSize, indentChar, indentWithTabs, braceStyle (collapse, expand, preserveInline), preserveNewlines, maxPreserveNewlines, spaceBeforeConditional, spaceInParen, spaceInEmptyParen, endWithNewline, wrapLineLength, enforceSemicolons, uppercaseReservedWords.

2.5. Real-Time Static Analysis & Security Linter

Analyzes code on every keystroke using comprehensive AST visitors to catch critical defects before testing:

• BMQL Injection Defense: Flags raw string concatenation in queries (e.g., bmql("SELECT ... WHERE id = '" + id + "'")) and offers an instant Quick-Fix (Ctrl+.) to convert it to a parameterized $id binding.
• Governor Limit Protection:
  • Detects database queries (bmql()) executed inside for or while loops (N+1 query trap).
  • Flags unbounded while (true) loops missing termination break conditions.
• Type Safety & Schema Validation:
  • Validates assignment compatibility between Integer, Float, String, Date, Boolean, and collections.
  • Validates Data Table column limits and type mismatches.
• Deprecated Functions: Highlights legacy CPQ functions (getpartsdata, gettabledata) and guides refactoring to modern BMQL queries.
• Workspace Security Audit: Run a full workspace security audit to generate a detailed compliance report.

2.6. Model Context Protocol (MCP) AI Suite

The extension embeds an autonomous Model Context Protocol (MCP) server conforming to the 2024-11-05 standard, enabling AI assistants (Cursor, GitHub Copilot, Google Antigravity, Claude Desktop, ChatGPT) to serve as expert CPQ engineers:

• Autonomous Discovery & Inspection:
  • list_cloud_functions, get_bml_function_code, inspect_cloud_metadata, introspect_schema.
• Automated Linting & Quality Assurance:
  • lint_bml_code, audit_bml_code, format_bml_code, calculate_metrics.
• Safe Local Sandbox Execution:
  • run_bml_locally, evaluate_bmql_query.
• Safe Cloud Deployment Gate:
  • validate_remote_bml, deploy_bml_function (enforces mandatory human review and pre-flight validation before updating remote CPQ instances).

2.7. Offline BML Sandbox & Logic Scratchpad

Test complex BML business logic without deploying to a live CPQ instance:

• Local Evaluator: Executes string manipulation, mathematical algorithms, date computations, JSONPath queries, and dictionary transformations completely offline.
• Live Execution Output: Captures all print(...) statements and execution times directly in the BML Output Panel.
• Commands:
  • CPQ-BML: Open BML Logic Scratchpad (Offline Sandbox)
  • CPQ-BML: Run BML Script Locally (Scratchpad)

2.8. Cloud REST Sync & Safe 3-Way Diff

Seamless integration with Oracle CPQ Cloud REST Web Services (v12 through v17+):

• Environment Management: Switch effortlessly between Development, Test, UAT, and Production environments.
• Safe 3-Way Diff on Pull: If a remote function was modified by another developer, pulling triggers an interactive side-by-side diff editor. You can merge remote changes without overwriting local uncommitted work.
• CPQ DevKit Terminal: Dedicated pseudo-terminal streaming real-time compilation logs, deployment statuses, and remote debug traces.

2.9. Code Quality & Software Science Metrics

Quantitative measurement of codebase health to prevent technical debt:

• McCabe Cyclomatic Complexity (CCN): Measures independent execution paths through if, elif, for, while, and logical operators. Flags functions exceeding complexity thresholds (CCN > 15).
• Halstead Software Science: Calculates program vocabulary, length, volume ($V$), difficulty ($D$), and estimated implementation effort ($E$).
• Maintainability Index (MI): Computes a composite maintainability score (0–100 scale) incorporating Cyclomatic Complexity, Halstead Volume, and Source Lines of Code (SLOC).
• Command: BML: Show Code Metrics (cpqBml.showMetrics).

2.10. Document Engine XSLT & XML Subsystem

For CPQ Document Engine templates, proposals, and email generation:

• XSL Formatting: Deterministic formatting for complex .xsl stylesheets.
• XPath 1.0 Autocompletion: Contextual autocomplete for XML node trees and attributes.
• BML Integration: Real-time validation for BML functions interacting with XML (readxmlsingle, readxmlmultiple, transformxml, applytemplate).

2.11. Standalone Headless LSP Daemon

The Language Server Protocol (LSP) core can operate as an independent background daemon over standard input/output (stdio):

• Cross-Editor Compatibility: Integrate CPQ-BML intelligence into Neovim, Emacs, Sublime Text, Helix, Zed, or custom web editors.
• CI/CD Quality Gate: Run the standalone server headlessly in GitHub Actions, GitLab CI, or Jenkins to block PRs containing BMQL vulnerabilities or lint errors.
• Protocol: Full LSP v3.17 compliance (Completions, Hover, Signature Help, Inlay Hints, Diagnostics, Formatting, Document Symbols).

3. BML Built-in Function Domain Catalog (13 Categories)

All 153 BML built-in functions are strictly categorized into their canonical domains:

4. Command Palette & Keyboard Shortcut Cheat Sheet

5. Configuration & Environment Reference

Cloud Environment (.env)

Create a .env file in your workspace root to define connection targets:

# Oracle CPQ Cloud Active Profile
CPQ_SITE_URL=https://myinstance.bigmachines.com
CPQ_USERNAME=admin_user
CPQ_PASSWORD=SecurePassword123!
CPQ_AUTH_METHOD=oauth2          # Options: oauth2, basic
CPQ_REST_VERSION=v17            # Options: v12, v14, v15, v16, v17
CPQ_COMMERCE_PROCESS=oraclecpqo
CPQ_COMMERCE_DOCUMENT=transaction
CPQ_TIMEOUT_MS=30000

Beautifier Configuration (.bmlbeautifyrc)

Create a .bmlbeautifyrc JSON configuration in your workspace root (camelCase is canonical; legacy snake_case options are also supported):

{
  "indentSize": 4,
  "indentChar": " ",
  "indentWithTabs": false,
  "braceStyle": "collapse",
  "spaceBeforeConditional": true,
  "spaceInParen": false,
  "spaceInEmptyParen": false,
  "preserveNewlines": true,
  "maxPreserveNewlines": 2,
  "endWithNewline": true,
  "wrapLineLength": 100,
  "uppercaseReservedWords": true,
  "logicalOperatorCasing": "uppercase",
  "formatBmqlStrings": true,
  "formatJsonStrings": true,
  "normalizeElif": true,
  "enforceSemicolons": false
}

VS Code Settings Matrix (settings.json)

{
  // Enable / disable core subsystems
  "cpqBml.features.intellisense": true,
  "cpqBml.features.linter": true,
  "cpqBml.features.formatter": true,
  "cpqBml.features.inlayHints": true,
  "cpqBml.features.spellCheck": true,
  "cpqBml.features.metrics": true,

  // Linter Severity & Thresholds
  "cpqBml.lint.maxLoopDepth": 3,
  "cpqBml.lint.maxBlockDepth": 5,
  "cpqBml.lint.flagBmqlInLoops": true,
  "cpqBml.lint.flagBmqlInjection": true,
  "cpqBml.lint.flagDeprecatedBuiltins": true,

  // Inlay Hints Display
  "cpqBml.inlayHints.parameterNames": true,
  "cpqBml.inlayHints.variableTypes": true,
  "cpqBml.inlayHints.suppressRedundant": true
}

6. Enterprise Best Practices & Governor Limits

When writing production BML, adhere to the following enterprise standards enforced by the static linter:

1. Never Concatenate BMQL Parameters:

   // ❌ BAD: High security risk of BMQL injection and query syntax breakage
   records = bmql("SELECT sku, price FROM parts WHERE category = '" + userCat + "'");
   
   // ✅ GOOD: Safe parameterized binding
   records = bmql("SELECT sku, price FROM parts WHERE category = $userCat");
   

2. Never Query BMQL Inside Loops (N+1 Anti-Pattern):

   // ❌ BAD: Triggers governor limits and severely degrades site response times
   for item in lineItems {
       partNum = get(item, "partNumber");
       rs = bmql("SELECT cost FROM part_cost WHERE part_number = $partNum");
   }
   
   // ✅ GOOD: Batch query upfront, then index into a typed dictionary
   rs = bmql("SELECT part_number, cost FROM part_cost WHERE category = $activeCategory");
   costMap = dict("float");
   for row in rs {
       put(costMap, get(row, "part_number"), getfloat(row, "cost"));
   }
   for item in lineItems {
       partNum = get(item, "partNumber");
       if (containskey(costMap, partNum)) {
           unitCost = get(costMap, partNum);
       }
   }
   

3. Always Check BMQL Errors on Dynamic Queries:

   records = bmql("SELECT id, rate FROM tax_matrix WHERE state = $stateCode");
   if (haserror(records)) {
       errMsg = getmessage(records);
       print("BMQL Query Execution Failed: " + errMsg);
       throwerror("Unable to calculate taxes. Please contact system administrator.");
   }
   

4. Use Stringbuilder for Repeated Concatenation:

   // ❌ BAD: Creates O(N^2) temporary String objects in heap memory
   result = "";
   for row in records {
       result = result + get(row, "sku") + ",";
   }
   
   // ✅ GOOD: High-performance O(N) mutable buffer
   sb = stringbuilder();
   for row in records {
       sbappend(sb, get(row, "sku"), ",");
   }
   result = sbtostring(sb);
   

5. Eliminate Magic Numbers & Hardcoded Strings:

   • Define status codes and threshold constants at the top of functions or query them from system configuration Data Tables.

7. License & Disclaimer

• License: Proprietary and Confidential. All rights reserved. See LICENSE for details.
• Disclaimer: This extension is an independent developer tool designed for BigMachines CPQ BML development. It is not affiliated with, endorsed by, or sponsored by Oracle Corporation or BigMachines, Inc. All trademarks are the property of their respective owners.