@targetprocess/suggestion-context v0.0.6

Targetprocess DSL suggestion tools

This package exposes several modules which aim to assist with building auto-completion suggestions for Targetprocess DSLs.

It was designed primarily for API v2 DSL (also used in Metrics) and Automation Rules DSL, but can probably be used with other DSLs as well.

It defines several key concepts seen in these DSLs, such as:

• Types
  • Domain types, e.g. User Story or String
  • Collection types, e.g. Collection of Bugs, as seen on UserStory.Bugs
  • Generic types, e.g. arguments and return types of collection methods like .Where(...)
  • Union types, e.g. (UserStory or Bug), which can be used when several entity types are selected in Metrics editor or Rule Engine UI
• Field access, e.g. Feature.Name
• Function call, e.g. IIF(A, B, C) or Bugs.Where
• Root and nested scopes
  • Root scope defines a type of entity which serves as invisible root of formulas. For example, in Metrics it can also be accessed by special "field" called It.
  • Nested scope, most notable example is "enumerable methods" like .Where or .Select on collections. Inside these methods the scope (also available through It) refers to the element of collection instead of root entity type. This actually resembles a concept of lambdas from your typical programming languages.

Building suggestions

Typically, the process of building auto-completion suggestions for user-input DSL involves traversing some parse tree produced by the parser, where each node has information about its position in the original text.

Let's take a simple incomplete formula text entered by the user, e.g. Feature.Na. We assume that this formula is written for User Story as root entity type. The caret position is located at the end of the text, after Na.

    Field Access (caret is here)
       /      \
    "Na"   Field Access
             /      \
        "Feature"  <Root>

During the traversal the current text caret position is compared with the mentioned positions of parse tree nodes. When we reach some node which matches the caret position (which is the top-level Field Access), we try to infer the information about types around that node.

In our case we can infer that the target type of the expression on which we try to access something starting with "Na" has the type Feature.

Given that, we can then find all fields containing Na substring in their name.

Suggestion context

This module doesn't actually provide anything for parse tree traversal, because this logic varies from one DSL to another, and depends on the used DSL grammar, parser implementation, and suggestion client requirements.

Instead it provides a data structure called SuggestionContext, which allows to keep the parser-agnostic information about the current traversal state, such as the type of the root entity, nesting level, etc.

This context also allows to semi-automatically build other contexts for operations like "field access" or "nested scope of function call".

Usages

You can see the example usage of this package in Metrics Setup UI and Automation Rules UI.

By default, all parsing and analysis errors are logged to console. You can override the library's logger in defaultLoggerFactory, for example to disable all logging:

import { defaultLoggerFactory } from '@targetprocess/suggestion-context'

defaultLoggerFactory.logger = {
  error() {
    // do nothing
  }
}