RuleScript v1.10.1

RuleScript v1.10.1

RuleScript v1.10.1 fixes editor analysis for scripts that are analyzed from text while belonging to a file inside a project subdirectory.

Source-File-Aware Analysis

RuleScriptEngine.Analyze and RuleScriptEngine.TryAnalyze now include overloads that accept the script source file path:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules"
};

var result = engine.TryAnalyze(craneScript, @"eqp\crane.rules");

Relative imports inside the analyzed script are resolved from the source file directory instead of always using WorkingDirectory. For example, when analyzing eqp/crane.rules, import "port" as port; resolves to eqp/port.rules.

The previous overloads continue to resolve imports from WorkingDirectory.

Validation

The release is covered by regression tests for:

• strict Analyze resolving imports relative to the supplied source file
• best-effort TryAnalyze resolving imports relative to the supplied source file, including incomplete editor buffers

RuleScript v1.10.0

RuleScript v1.10.0

RuleScript v1.10.0 promotes HostTrigger runtime support to the stable release line. The release adds long-running script runtimes that can wait for host-dispatched trigger requests, exposes HostTrigger metadata through analysis/runtime symbols, and aligns runtime creation with existing file execution and debug-session flows.

HostTrigger Functions

Scripts can mark user functions as host-dispatched triggers:

@HostTrigger("LotArrived")
function OnLotArrived(lotId: string) -> void:
    Print("lot arrived: " + lotId);
    return;
endfunction

HostTrigger metadata is surfaced through RuleScriptFunctionSymbol.HostTriggerMetadata and RuleScriptAnalysisResult.HostTriggers, allowing embedding applications to discover available trigger names, signatures, parameters, documentation, and source ranges before running a script.

Long-Running Runtime

RuleScriptEngine.CreateRuntime creates a RuleScriptRuntime that can be started, triggered, and stopped by the host:

var engine = new RuleScriptEngine
{
    ExecutionTimeoutEnabled = false
};

var runtime = engine.CreateRuntime(script);
var running = runtime.StartAsync();

await runtime.TriggerAsync("LotArrived", ["LOT-001"]);
await runtime.TriggerAsync("LotArrived", ["LOT-002"]);

await runtime.StopAsync();
await running;

A script runtime must contain a trigger dispatcher:

parallel:
    trigger task:
        dispatch;
    endtask
endparallel

The dispatcher remains active after each request, so StartAsync continues running until the host calls StopAsync, cancellation is requested, or the runtime faults.

Runtime Creation From Files

RuleScriptEngine.CreateRuntimeFromFile starts from the same project-loading behavior as ExecuteFile and ExecuteFileAsync:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules",
    ExecutionTimeoutEnabled = false
};

var runtime = engine.CreateRuntimeFromFile("main");

foreach (var trigger in runtime.HostTriggers)
{
    Console.WriteLine($"{trigger.HostTriggerMetadata?.Name}: {trigger.Signature}");
}

File-based runtime creation honors WorkingDirectory, ScriptFileExtension, ImportResolver, and existing import/module loading behavior.

Debug Session Runtime Support

RuleScriptDebugSession can create runtimes from script text or files while preserving breakpoint, stepping, pause, continue, and runtime-event inspection behavior:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules",
    ExecutionTimeoutEnabled = false
};

engine.AddBreakpoint("main.rules", 12);

var session = new RuleScriptDebugSession(engine);
var runtime = session.CreateRuntimeFromFile("main.rules");

var running = runtime.StartAsync();
var pause = await session.WaitForPauseAsync();

Console.WriteLine(pause.Kind);
Console.WriteLine(session.CurrentSnapshot?.CallStack.Count);

session.Continue();

await runtime.TriggerAsync("LotArrived", ["LOT-001"]);
await runtime.StopAsync();
await running;

Debug event handlers are installed while the runtime is executing and restored after the runtime completes.

Formatter Support

RuleScriptFormatter.Format now formats HostTrigger attributes with the attribute attached to @ and the following function declaration on its own line:

@HostTrigger("TriggerTest")
export function Test():
    Print("Something triggered");
endfunction

Spaced input such as @ HostTrigger(...) export function is normalized to the canonical attribute form.

Compatibility Notes

• Existing scripts, host functions, built-ins, imports, Execute, ExecuteAsync, ExecuteFile, and ExecuteFileAsync behavior remain compatible.
• Existing parallel, task, trigger task, and dispatch syntax is unchanged.
• HostTrigger handlers are executed by the interpreter; host threads enqueue trigger requests instead of directly invoking user functions.
• HostTrigger handlers may call built-in functions such as Print.
• Registered host-function thread-safety checks continue to apply to ordinary parallel task execution.
• StopAsync is the expected way to end a long-running HostTrigger runtime.

Validation

The v1.10.0 work is covered by tests for:

• HostTrigger lexer, parser, analysis, and runtime metadata
• runtime start, trigger dispatch, FIFO request ordering, and stop behavior
• keeping trigger dispatchers alive after handling requests
• CreateRuntimeFromFile project loading and working-directory behavior
• debug-session runtime creation from script text and files
• breakpoint pause and continue behavior in debug-created runtimes
• HostTrigger handler calls to built-in and registered host functions
• formatter normalization for @HostTrigger(...) function
• formatter normalization for @HostTrigger(...) export function
• v1.9 strongly typed function and overload regression coverage

RuleScript v1.9.0

RuleScript v1.9.0

RuleScript v1.9.0 adds strongly typed user functions while keeping existing scripts compatible. The release focuses on function signatures, overload analysis, runtime overload dispatch, and diagnostics.

Explicit Return Types

Functions may now declare a return type:

function Add(a: number, b: number) -> number:
    return a + b;
endfunction

The existing syntax remains valid:

function Add(a, b):
    return a + b;
endfunction

Supported function types are any, null, number, string, bool, boolean, array, object, and void.

void means the function must not return a value. return; is valid, but return 123; is reported as an analysis error.

Return Type Diagnostics

Declared return types are validated during analysis. A function declared as -> number must return number values from every return statement.

When a declared non-void function does not return on every path, analysis reports:

Not all code paths return a value.

Old-style functions remain valid. When an old-style function returns a value, analysis emits a compatibility warning recommending an explicit return type.

Function Overloads

User functions may share a name when their parameter signatures differ:

function Format(value: number) -> string:
    return ToString(value);
endfunction

function Format(value: string) -> string:
    return value;
endfunction

Duplicate signatures are rejected:

Duplicate function signature 'Add(number, number)'.

All overloads with the same name must use the same declared return type:

Function overloads for 'Convert' must use the same return type.

Overload Resolution

Analysis and runtime overload resolution use:

• function name
• argument count
• argument type compatibility
• exact matches before any

Return type does not participate in overload resolution. If no candidate matches, analysis/runtime reports no matching overload. If multiple candidates tie, analysis/runtime reports an ambiguous overload.

Host, User, And Built-In Functions

User, host, and built-in functions now participate in the same overload set. A script can define a user function with the same name as a host or built-in function when the signatures differ.

Runtime dispatch selects the best matching overload from the available user, host, and built-in candidates without implicit type conversion.

Compatibility And Scope

• Existing function syntax remains supported.
• Existing scripts continue to run.
• Parser, binder, runtime, and symbol architecture remain incremental extensions of the v1.8 model.
• No generics, nullable type syntax, delegates, lambdas, interfaces, or new executable syntax were added.
• Runtime does not perform automatic type conversion for overload selection.

Validation

The v1.9.0 work is covered by tests for:

• parser support for -> returnType
• old syntax compatibility
• declared return type metadata
• return type mismatch diagnostics
• missing return warnings
• old syntax return warnings
• duplicate function signatures
• unified overload return type rules
• no matching overload diagnostics
• ambiguous overload diagnostics
• runtime overload dispatch
• user/host/built-in overload coexistence
• v1.8 regression coverage

RuleScript v1.8.0

RuleScript v1.8.0

RuleScript v1.8.0 is a maintenance-focused refactor for editor and analyzer infrastructure. It does not add Rule Script syntax, executable language constructs, or runtime behavior changes.

Unified Function Symbols

Function metadata is now represented by RuleScriptFunctionSymbol across user, imported, host, and built-in functions. Function origin is described by RuleScriptFunctionKind:

• User
• Imported
• Host
• Builtin

Use RuleScriptAnalysisResult.Functions for unified editor-facing lookup. Each function symbol can carry parameter metadata, return type, source location, documentation, host metadata, built-in metadata, or import metadata.

The legacy RuleScriptHostFunctionSymbol and RuleScriptBuiltinFunctionSymbol public classes remain available as obsolete compatibility adapters. Existing code can continue to read HostFunctions, BuiltinFunctions, and RegisteredHostFunctions, while new integrations should prefer RuleScriptFunctionSymbol.

Shared Function Resolution

Function lookup for analysis and editor metadata now flows through a shared resolver model. Diagnostics, Go To Definition, and Find References can resolve user, imported, host, and built-in functions through unified RuleScriptFunctionSymbol metadata instead of switching across separate function symbol classes.

Source Locations And Ranges

Internal source mapping is centralized through RuleScriptSourceMapper. Diagnostics, analysis symbols, runtime event ranges, and navigation metadata use the same RuleScriptSourceRange mapping and half-open range containment rules.

External DTOs such as RuleScriptDefinitionInfo, RuleScriptReferenceInfo, RuleScriptDiagnostic, and runtime events keep their existing output shape.

Reusable Document Analysis

Editor integrations can parse and analyze a document once with RuleScriptLanguageService.AnalyzeDocument:

var document = RuleScriptLanguageService.AnalyzeDocument(engine, source);

var definition = RuleScriptLanguageService.GetDefinition(document, line: 4, column: 1);
var references = RuleScriptLanguageService.FindReferences(document, line: 4, column: 1);

RuleScriptDocumentAnalysisResult contains source text, tokens, statements, regions, and RuleScriptAnalysisResult. RuleScriptAnalysisCache can reuse unchanged per-document analysis results and replace only the updated document.

This is a low-risk cache boundary for editor features. It is not a full incremental compiler.

Compatibility And Scope

• No Rule Script runtime behavior changes.
• No parser syntax changes.
• No formatter output changes.
• No executable language constructs added.
• Existing public APIs remain available.
• Obsolete function symbol adapters are retained for compatibility.
• Rename, Hover, Completion, Monaco UI, and LSP transport remain outside this refactor.

Validation

The v1.8.0 maintenance refactor is protected by regression tests for:

• Unified user, imported, host, and built-in function symbols.
• Public adapter compatibility.
• Go To Definition and Find References for functions, parameters, and variables.
• Missing symbol behavior.
• Shared source range mapping.
• Reusable document analysis and cache behavior.
• Formatter, diagnostics, and runtime behavior stability.

RuleScript v1.7.0

RuleScript v1.7.0

RuleScript v1.7.0 focuses on Navigation API metadata for editor integrations. It adds Core APIs for Go To Definition and Find References without changing parser architecture, semantic analysis behavior, runtime execution, or Rule Script syntax.

Navigation API

Use RuleScriptLanguageService to query one-based source positions:

using RuleScript.Core;

var definition = RuleScriptLanguageService.GetDefinition(source, line: 4, column: 1);
var references = RuleScriptLanguageService.FindReferences(source, line: 4, column: 1);

When navigation needs host function metadata or project import resolution from a configured engine, pass the engine explicitly:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules"
};

var definition = RuleScriptLanguageService.GetDefinition(engine, source, line: 3, column: 1);
var references = RuleScriptLanguageService.FindReferences(engine, source, line: 3, column: 1);

Go To Definition

GetDefinition returns RuleScriptDefinitionInfo? with symbol name, kind, source range, selection range, documentation, external status, parameter metadata, and return type.

For editor adapters that prefer direct coordinates, RuleScriptDefinitionInfo also exposes convenience properties derived from SelectionRange first and then Range:

• File
• Line
• Column
• EndLine
• EndColumn

Supported symbols:

• Local functions.
• Imported exported functions.
• Built-in and registered host functions.
• Function parameters.
• Local variables.
• Global variables.

Host functions are external metadata. They expose documentation, parameter information, and return type, but they do not have a source range.

Find References

FindReferences returns IReadOnlyList<RuleScriptReferenceInfo> with declaration and usage metadata. Each reference exposes Range plus direct File, Line, Column, EndLine, and EndColumn convenience properties.

Supported symbols:

• Functions, including declaration and calls.
• Imported functions, including current-file uses and import-module references.
• Host functions, including an external declaration marker and all calls in the current source.
• Function parameters.
• Local variables.
• Global variables.

Compatibility and Scope

• No new Rule Script keyword or executable syntax is introduced.
• Runtime execution and Execute behavior are unchanged.
• Parser, binder, type checker, and module architecture remain intact.
• RuleScript.Core provides source metadata only. Monaco, Ctrl+Click behavior, peek windows, highlight rendering, and other UI concerns remain outside Core.

Validation

• Debug build: 0 warnings and 0 errors.
• Test suite: 587 passed, 0 failed, 0 skipped.

RuleScript v1.6.0

RuleScript v1.6.0

RuleScript v1.6.0 focuses on source formatting and editor metadata. It adds a Core formatter, multi-line comments, region directives, and documentation comments without changing runtime behavior or adding executable language constructs.

Formatter

Use the public formatter API to normalize indentation, spacing, line endings, and block layout:

using RuleScript.Core.Formatting;

var formatted = RuleScriptFormatter.Format(source);

The formatter supports every syntax available through v1.5.0, including parallel and task, and preserves generic or dedicated block endings such as endtask and endparallel. Blank lines, line comments, multi-line comments, documentation comments, and region directives are retained. Standalone comments follow the indentation of the next syntax element, and multi-line comment content is indented beneath its delimiters.

Multi-line Comments

Scripts can use /* ... */ comments across one or more lines:

/* Load and update the player. */
var player = LoadPlayer();

Comment delimiters inside strings remain string content. An unclosed multi-line comment produces a syntax diagnostic at its opening /*.

Regions

#region and #endregion are non-executable editor directives:

#region Player
function UpdatePlayer():
    Print("update");
endfunction
#endregion

RuleScriptLanguageService.GetRegions(source) returns named, nested, one-based source ranges suitable for folding. Regions do not reach the Interpreter, Binder, or type checker.

Documentation Comments

Consecutive /// lines immediately before a function become function documentation:

/// Gets a player name.
/// @param id Player ID
/// @return Player name
function GetPlayerName(id):
    return "Player";
endfunction

Documentation is available through RuleScriptFunctionSymbol.Documentation and RuleScriptLanguageService.GetFunctionDocumentation(source, functionName). It is metadata only and does not affect execution.

Host registrations can provide the same editor metadata through RuleScriptHostFunctionOptions.Documentation or RuleScriptFunctionAttribute.Documentation. The options-based registration API also groups parameters, return type, thread-safety, and future metadata without adding more positional overload parameters.

Attribute scanning supports methods returning Task and Task<T>. A final CancellationToken parameter is injected by the Engine and is not exposed as a script argument.

Compatibility and Scope

• Existing v1.5.0 scripts and public Lexer.Tokenize() comment-skipping behavior remain compatible.
• No new executable keyword, flow-control construct, async primitive, lock, channel, actor, rename, code action, quick fix, syntax rewriter, or syntax walker is introduced.
• Monaco and other editor UI integrations remain outside RuleScript.Core.

Validation

• Debug build: 0 warnings and 0 errors.
• Test suite: 569 passed, 0 failed, 0 skipped.

RuleScript v1.5.0

RuleScript v1.5.0

RuleScript v1.5.0 adds script-level parallel execution, cooperative parallel debugging, and recursive user functions.

Parallel Execution

Parallel execution uses four keywords: parallel, task, endtask, and endparallel. Both dedicated endings and the generic end are accepted.

values = parallel:
    task:
        return LoadA();
    endtask
    task:
        return LoadB();
    endtask
endparallel;

parallel waits for every task. Expression results preserve declaration order, and a task without return contributes null. Task-local variables and function stacks are isolated; the host RuntimeContext is shared and synchronized. Concurrent reads and writes are safe, but compound operations such as read-modify-write are not atomic.

Host Integration and Safety

Host functions are denied inside tasks unless registered as thread-safe. Use the threadSafe: true registration overload or decorate a public instance method with [RuleScriptFunction(ThreadSafe = true)] and call RegisterFunctions(host).

RuleScriptEngine.Stop(), execution timeout, loop limits, statement limits, and call-depth limits cooperatively cancel or constrain parallel work. A task failure cancels sibling tasks and is reported with its declaration index. Static analysis also detects indirect calls to host functions from parallel tasks.

Debugging and User Functions

• A breakpoint or step pause establishes a shared barrier so all parallel tasks pause cooperatively.
• Continue, Step Over, and Stop release every task waiting at the shared pause barrier.
• Long-running host functions join a pause after returning to the next cooperative boundary.
• Recursive user functions can complete within MaxCallDepth; infinite recursion remains constrained when CallDepthLimitEnabled is enabled.

This release does not add async, await, locks, channels, actors, task handles, or fire-and-forget execution to the language.

Validation

• Release build: 0 warnings and 0 errors.
• Test suite: 534 passed, 0 failed, 0 skipped.
• NuGet package version: 1.5.0.

RuleScript v1.4.0

RuleScript v1.4.0

RuleScript v1.4.0 expands the language's data-manipulation features and editor analysis, and introduces explicit module boundaries.

Language and Runtime

• Added elseif branches, object literals, object and array target assignments, conditional member access (?.), and null coalescing (??).
• Added array and object destructuring declarations.
• Added const, export function, and export const.
• Added ArrayInsert, ArrayRemoveAt, ArraySort, ObjectKeys, and ObjectContainsKey.

Static Analysis and Public API

• Added richer object-shape, collection-element, assignment, nullability, and function-return inference.
• Added typed metadata for every built-in function.
• Added readonly and export metadata to variable and function symbols.
• Imported export const declarations are included in cursor-aware VisibleVariables.
• Added diagnostics for missing properties, invalid or readonly assignments, invalid indexes, null access, invalid null coalescing, and duplicate object properties.

Breaking Changes

• Imported functions and constants are private unless explicitly declared with export.
• Modules without explicit exports no longer expose members through global or alias imports.
• Existing imported declarations must be migrated to export function or export const.
• elseif, export, and const are newly reserved words.

Validation

• Release build: 0 warnings and 0 errors.
• Test suite: 514 passed, 0 failed, 0 skipped.
• NuGet package version: 1.4.0.

RuleScript v1.3.0

RuleScript v1.3.0

Highlights

RuleScript v1.3.0 adds non-fallthrough switch statements, multi-value and guarded cases, a script-level null literal, and switch-specific semantic diagnostics while preserving existing script and host API compatibility.

switch status:
    case "ok":
        result = "Continue";
    case "warning", "error" when retryCount <= 3:
        result = "Inspect";
    case "warning" when retryCount > 3:
        result = "Escalate";
    case null:
        result = "Missing status";
    default:
        result = "Unknown status";
endswitch

Switch Behavior

• The switch expression is evaluated exactly once.
• The first eligible case executes once without fallthrough; break is not required.
• Comma-separated labels and consecutive empty labels can share a body.
• A when guard runs only after its label matches and must evaluate to bool.
• default is optional, unique, and must be last.
• end can replace endswitch.
• Synchronous and asynchronous execution are supported.

Analysis and Public API

• Added RuleScriptDiagnosticCodes.DuplicateCase (RS2006).
• Added RuleScriptDiagnosticCodes.MissingDefaultBranch (RS2007).
• Added switch/case type compatibility and guard-type analysis.
• Added public SwitchStatement, SwitchCase, and SwitchLabel AST records.
• Added Null, Switch, Case, Default, When, and EndSwitch token types.
• Updated symbol collection for variables declared in case and default bodies.

Compatibility

Existing scripts and v1.2.0 host integrations remain compatible unless a script used a newly reserved word as an identifier. New reserved words are switch, case, default, when, endswitch, and null.

Validation

• Release build: 0 warnings and 0 errors.
• Test suite: 399 passed, 0 failed, 0 skipped.
• Package version: 1.3.0.

For complete syntax and API documentation, see the Language Guide, Debugging and Analysis, and API Reference by Class.

RuleScript v1.2.0

RuleScript v1.2.0

Highlights

RuleScript v1.2.0 adds realtime semantic diagnostics and configurable runtime safety limits while preserving v1.1.0 source compatibility. Analysis and execution continue to read current script and import content on every call; this release does not introduce a compiled-program or cross-execution source cache.

Semantic Diagnostics

• Added stable, machine-readable codes through RuleScriptDiagnosticCodes.
• Added RuleScriptDiagnosticSeverity values for Info, Warning, and Error.
• Added diagnostics for undefined variables and functions, incompatible known types, and duplicate declarations.
• Added source locations and half-open ranges to semantic diagnostics.
• Added RuleScriptAnalysisResult.Diagnostics to strict analysis results.
• Added RuleScriptEngine.KnownVariables, SetKnownVariable, RemoveKnownVariable, and ClearKnownVariables for host-provided analysis symbols.
• Preserved realtime analysis by reading current script and import content on every analysis call.

Runtime Limits

• Added ExecutionTimeout and ExecutionTimeoutEnabled.
• Added MaxCallDepth and CallDepthLimitEnabled.
• Added MaxExecutedStatements and StatementExecutionLimitEnabled.
• Preserved MaxLoopIterations and LoopIterationLimitEnabled.
• Applied enabled limits consistently to synchronous, asynchronous, file, and debug-session execution.
• Included the configured limit name and value in runtime errors.

Reliability and Compatibility

• Fixed best-effort parser recovery so duplicate parameters and unmatched block terminators cannot stall realtime analysis.
• Kept v1.1.0 public APIs source compatible.
• Kept existing scripts valid unless an enabled runtime limit is exceeded.
• Kept semantic diagnostics advisory; execution behavior remains unchanged.

Validation

• Release build: 0 warnings and 0 errors.
• Test suite: 374 passed, 0 failed, 0 skipped.
• Package version: 1.2.0.

For setup and API examples, see the RuleScript Wiki, especially Debugging and Analysis and API Reference by Class.