Enhancing the Morphir IR

[michelchan]

Required Reads

• Laika
• UnifiedJS

Proposal

By referencing existing solutions, we can improve Morphir’s IR and provide better tooling. We can create a three step process for working with the IR:

• Parse a Document/Source into AST/Element/IR
• Transform the tree with custom transformers
• Render the tree/Transpile IR

All IRs are serialized into a single Distribution, which means to do any transformations a language binding or tool needs to be aware of the full IR. We can change Morphir to have a document structure:

• A Document - Each file representing serialized Morphir is a document
• A Document Root/Concept - This contains the actual data for the node represented by the document
  • This may for example be a Type, a Value, a Module, a Package, or a Distribution
    • This is a key distinction between previous Morphir formats as you can deal with an IR in smaller pieces which makes it easier to write tools to transform and work with the IR
    • Also the inherent tree like structure allows for simple navigation and transformation
• Document “Metadata”/Context - This lives alongside the Document Root and allows metadata about the document to be stored

Virtual Tree Abstraction

A Morphir distribution can have one or many files within it including any dependencies it may need. The current Simple-Savings-It has five IR files in it and is manually packed by the maestro-cli; if we were to do the above proposal of defining the components in a single morphir.json file, we’d have a distribution of one IR file. By implementing Morphir as a document, we can view the entire distribution as a virtual tree abstraction. This allows us to create virtual links and “mount” them at specific points. This will allow us to not be bound by the file system and save on the size of the IR.

Relationships

In the existing Morphir codebase, the metadata (also known as attributes) is represented in the code as generics. In Morphir-Elm, you’d see this represented like type Type a, and in Morphir-Scala it as sealed trait Type[+A]. Generics added bulk to the IR and added complexity which makes the IR unwieldy and require custom tooling to process.

To better represent relationships, we are going to use a RDF (Resource Description Framework) style. RDF represents relationships in the form of subject-predicate-object expressions. We can apply this to our new document based approach in Morphir. We can have our Element nodes have relationships like:

Subject	Predicate	Object
Amount.incrementBy	is	Function Type
Amount.incrementBy	hasParameterOfType	Int
Amount.incrementBy	returns	Amount

Besides relationships, you can also embed other kinds of metadata such as version numbers, feature flags, etc. This provides a more robust way of handling configuration details.

Enabling Position

UnifiedJS stores position in its nodes that help track position of the starting and ending line numbers, column numbers, and offset numbers. We can add this to our Morphir Elements and return the exact position of referenced code in exceptions and code coverage reports.

Transformer

Turning Morphir into a DOM structure will give us the flexibility to manipulate nodes on the AST tree. Users will be able to transform their existing IR into new IR or new IR into existing IR (this may produce errors for unsupported features in the new IR).

For more specialized cases, users can use Rewriters to completely modify the structure. There would be two types of rewriters:
AST Rewriter - transformation from AST to AST which may add, remove, or modify nodes or attributes of nodes
IR Rewriter - transformation from IR to IR which may add, remove, or modify nodes or attributes of nodes

In Laika, rewriters look like this in code form:

val newDoc = doc.rewrite(RewriteRules.forSpans {
  case Emphasized(content, opts) => RewriteAction.Replace(Strong(content, opts))
})

This code replaces Emphasized nodes into Strong nodes. We would be able to make similar transformers in Morphir where you can specify what kind of node to replace. We can use Laika’s easy to read design as reference.