STEP Business Rule Test - AI Labz Ltd (TM)

STEP Business Rule Test

This plugin provides an integration with the Stibo Systems STEP system.

Install

To install the distributable vsix package run

code --install-extension stepbusinessruletest-1.6.11.vsix

Setup

To allow development and testing of JavaScript business rules in VS Code, the STEP workbench can generate a VS Code workspace with an editable JavaScript file. The workspace will include a launch configuration configured to use this plugin to remotely execute the JavaScript file on the STEP server with all necessary configurations generated by STEP.

Usage

To test a JavaScript business rule, edit the JavaScript file, save it, and then run the JavaScript business rule from the Run and Debug tab.

Performance

Performance will be a bit slower than when the business rules run on the server normally for the following reasons.

1. In this test execution we run the Rhino JavaScript engine in debug mode to have better controls for terminating scripts that have fallen into an infinite loop.
2. The log messages written by the script will be sent back to VS Code as chunked HTTP response content inline in the script’s executing thread to provide the user with instant feedback while the business rule is still executing.

Business function parameters

The STEP Business Rule Test plugin does not support all parameter types available to STEP business functions. If the referenced node is of a type matching one of the node types supported by the business function, the plugin will map a node parameter type to the node reference by the nodeurl plugin parameter. All other parameter types are mapped to a null value. You can build a default value into the function code.

STEP business rule best practices

Every time a JavaScript business rule file is saved, the plugin enforces development conventions drawn from the STEP Business Rule Performance Recommendations:

Applied automatically on save (each one individually configurable, see Settings below):

• A standard STEP header comment is added if missing.
• A getStepLogger(manager) helper is added if missing, resolving the STEP manager logger with a console fallback.
• A JSDoc stub is added above any undocumented top-level function.
• The execute(...) function body is wrapped in a try { ... } catch (error) { logger.severe(...); throw error; } block. The catch re-throws - STEP requires this so the exception approval handler still runs; a caught-but-swallowed exception can leave objects inconsistently approved.
• Trailing whitespace is trimmed and line endings normalized.
• Optionally (off by default), the STEP-documented per-rule debug-flag pattern (var isDebug = false; function logDebug(message) {...}) can be inserted for development-time verbose logging - remember to leave isDebug false before deploying.

Flagged as warnings in the Problems panel:

• Function/variable/library-alias names that are not camelCase (or UPPER_CASE for constants).
• Boolean variables not prefixed with is/has/can/should.
• Write operations (setValue, setSimpleValue, create, delete, approve) inside loop bodies - STEP guidance recommends keeping transactions short.
• Repeated node/value lookups inside loops - STEP guidance recommends consolidating into a single query ("Use Arrays Over Multiple Database Calls").
• while(true)/for(;;) loops with no visible break/return - infinite loops can make the whole STEP installation unresponsive.
• getChildren() usage - queryChildren() is recommended instead to avoid memory problems on large selections (>10,000 children).
• catch blocks that do not re-throw.
• A var name; declaration whose first subsequent use looks like a read, not an assignment (likely undefined at that point).
• A non-execute function that calls STEP APIs which can throw (node/value lookups, mutations, JSON.parse) but has no try/catch anywhere in its body.
• Business rule files above a configurable line-count threshold, since STEP recompiles rule/library code on every execution.
• Any user-configured deprecated-API regex patterns.

Run the STEP: Apply Business Rule Best Practices command (Command Palette, or right-click in the editor) to apply all fixes on demand instead of waiting for save.

All of the above are configurable under Settings > Extensions > STEP Business Rule Test (stepbusinessruletest.bestPractices.*).

Right-click menu

Right-click inside a JavaScript file for a STEP Business Rule Test submenu with the most commonly used commands: Analyze Code (AI Review), Generate AI Comments, Apply Business Rule Best Practices, and Test AI Comment Provider. Everything below is also available via the Command Palette.

AI code review (beyond doc comments)

Run STEP: Analyze Code (AI Review) (Command Palette or right-click) for a deeper look than naming/deprecation warnings - it reviews the current selection, or the whole file if nothing is selected, and reports:

• Missing or weak error handling
• Uninitialized or misused variables
• STEP performance anti-patterns (writes in loops, getChildren() on large sets, etc.)
• Other bugs or risks

The review is grounded in the same STEP guidance used for comments (see below) plus your local API index if you've built one, and opens as a readable Markdown report beside your editor rather than as diagnostics, since AI review text doesn't reliably map back to exact source lines. Needs AI comments to be configured first (see below) - it uses the same aiComments.* provider settings.

AI-generated comments (optional, off by default)

By default, the JSDoc stub added above undocumented functions is a generic template (STEP business rule function: X. TODO: Describe purpose...) - no AI involved. You can optionally have an LLM write the actual one-sentence description instead. There are four ways to activate it, in order of how much setup they need:

Option A - local, free, one command (Ollama). Run STEP: Install & Configure Local AI (Ollama) from the Command Palette. It will:

1. Install Ollama via Homebrew if it isn't already on your machine (asks first) - or point yourself at ollama.com if you're not on macOS/without Homebrew.
2. Start the Ollama server if it isn't running.
3. Let you pick a model (llama3.1 recommended, or type any tag you like) and pull it.
4. Validate the model actually answers within the timeout - this catches "thinking"-model problems (see below) before you hit them yourself.
5. Write aiComments.enabled, aiComments.provider, and aiComments.model for you.

That's it - nothing else to configure. Your business rule source never leaves your machine, no API key, no per-call cost.

Option B - local, free, a server you already run (llama.cpp / LM Studio). No wizard for this one; set it by hand:

1. Start llama-server or LM Studio's local server on your machine.
2. Open Settings, search stepbusinessruletest.bestPractices.aiComments, set aiComments.enabled to true and aiComments.provider to custom-openai-compatible.
3. Set aiComments.endpoint to that server's chat-completions URL (e.g. http://localhost:8080/v1/chat/completions for llama.cpp, http://localhost:1234/v1/chat/completions for LM Studio) and aiComments.model to whatever model name that server expects.

Option C - cloud, paid (OpenAI or Anthropic/"Claude"). Run STEP: Configure Cloud AI Provider (OpenAI/Anthropic) from the Command Palette. It will:

1. Ask you to pick OpenAI or Anthropic.
2. Prompt for your API key in a masked input box and store it in VS Code's encrypted SecretStorage - never in plaintext settings.json. (Use STEP: Forget Stored Cloud AI API Key any time to remove it.)
3. Let you confirm/override the model (defaults: gpt-4o-mini for OpenAI, claude-haiku-4-5-20251001 for Anthropic).
4. Run a live test call and write aiComments.enabled/provider/model for you.

This calls each provider's HTTP completion API directly (OpenAI's /v1/chat/completions, Anthropic's /v1/messages) - it does not shell out to the Codex CLI or Claude Code CLI, which are interactive coding agents, not a fit for a one-shot call from a save hook. Your function source is sent to that provider for every comment generated - use Option A/B instead if that's not acceptable.

Option D - manual. Set the stepbusinessruletest.bestPractices.aiComments.* settings yourself (all four options ultimately just write these):

If comments look generic (STEP business rule function: X. TODO: Describe purpose...), that means AI isn't actually running - either it's disabled, or every call is silently failing (bad model name/tag, server not running, missing API key) and falling back to the template, which looks identical to AI being off. Run STEP: Test AI Comment Provider to check directly: it makes one real call and reports either the actual generated text, or a clear error explaining why it's failing.

Once any option above is active, you can trigger AI comments three ways:

• Type /** above a function and press Enter. VS Code auto-expands this into a 3-line JSDoc block; landing on the empty middle line triggers an AI description for that specific function immediately (Copilot-style), with a "Generating description..." placeholder while it's in flight.
• Run STEP: Generate AI Comments (Local/Cloud LLM) from the Command Palette to generate comments for every function on demand (with a progress notification). This force-regenerates every top-level function's comment, including ones that already have the generic template stub from a previous run - if the AI call fails for a given function during a forced run, its existing comment is left untouched rather than replaced with something worse.
• Turn on aiComments.enableOnSave (separate from aiComments.enabled - see the table above) to have it happen automatically whenever you save.

Every AI call is wrapped so a failed/slow/unreachable model always falls back to the template comment (for previously-undocumented functions) or is skipped (for previously-documented ones) - it can never break or block a save.

Avoid "thinking"/reasoning models for Ollama/custom-server options (qwen3, qwq, deepseek-r1, and similar hybrid-reasoning models) unless you raise maxOutputTokens well above the default and accept much higher latency - we tested this directly: a 4B "thinking" Qwen3 model spent its entire token budget on internal reasoning and returned an empty answer for a one-sentence task, even at 700 tokens / 30+ seconds. Plain instruct/coder models (e.g. llama3.1, deepseek-coder, qwen2.5-coder) answer directly in a couple of seconds.

The extension itself stays a few hundred KB - no model is ever bundled in the .vsix; the LLM (local or cloud) always lives outside the extension.

API grounding (optional, bring your own SDK docs)

AI comments can be grounded in the real STEP scripting API instead of just the raw function text - but the STEP scripting-api javadoc is Stibo Systems' own SDK documentation, so this extension does not, and will never, ship or bundle any of it. Instead, run STEP: Build Local API Index from SDK Docs and point it at the documentation/javadoc folder from your own STEP scripting-api download (the same one referenced in your STEP installation/license). It extracts a small lexical index (method name -> one-line description, plain keyword lookup, not embeddings or a vector store) for a curated set of core classes (Manager, Node, Product, BaseObject, and related types) and stores it in VS Code's private per-machine global storage - never inside the extension folder, never packaged, never synced, never sent anywhere except as prompt context to whichever AI provider you've configured above.

Once built, .methodName( calls found in a function body are looked up in your local index and injected into the LLM prompt as reference context automatically - no further setup needed. If you never run this command, AI comments still work fine; they just don't get this extra grounding.