// Invocation flow

// Kod opens a new file and initially sends the entire document to node for
// parsing. UID is an opaque symbol identifying the translation unit ("file") in
// a global space.
// Here, source is "var x = 4 + 5;"
[kod -> node] parse(UID, language, name, source)
// node finds an appropriate parser for language and parses the source
              var parser = parserForLanguage(language)
              var ast = parser.parse(source)
              index[UID] = {ast:ast, name:name}

// then node sends an "ast updated for UID" message to kod
[node -> kod] updateAST(UID, AST, extent=[0,14])

// now, the source is updated due to an edit -- source is now:
// "var x = 4 + 5;\nfoo();"
// so kod sends a request for incremental parsing. "source" passed to node is:
// "\nfoo();" which is all text after the previous ast node and up until the
// next affected ast node.
[kod -> node] parse(UID, language, name, source="\nfoo();",
                    modifiedRange=[14,0],
                    changeLengthDelta=7)
// kod finds the appropriate parser and loads the AST
              var parser = parserForLanguage(language)
              var ast = index[UID].ast
// the parser deduces the "farthest" (most minimal) branch which need to be
// re-parsed as an effect of the edit:
              var affectedNode = parser.affectedNode(ast, modifiedRange,
                                                     changeLengthDelta)
// parses and patches the ast
              parser.parseAndPatch(source, ast, modifiedRange)
// finally node sends an "ast updated for UID" message to kod, passing the new
// ast and telling kod to what extent the source was affected
[node -> kod] updateAST(UID, AST, affectedNode.extent)

// now, an edit is made which modifies an ast node/branch so source become:
// "var x = 4 + 5;\nfoo(x);" (added: passing "x" as an argument to "foo")
// kod sends a "parse" request:
[kod -> node] parse(UID, language, name, source="x",
                    modifiedRange=[20,0],
                    changeLengthDelta=1)
// kod finds the appropriate parser and loads the AST
              var parser = parserForLanguage(language)
              var ast = index[UID].ast
// the parser deduces the "farthest" (most minimal) branch which need to be
// re-parsed as an effect of the edit:
              var affectedNode = parser.affectedNode(ast, modifiedRange,
                                                     changeLengthDelta)
// the source is expanded to include the extent of affectedNode
// TODO: "text" is the complete text of the translation unit, but need an API
              var newExtent = affectedNode.extent
              newExtent.length += changeLengthDelta
              source = text.substr(newExtent.location, newExtent.length)
// parses and patches the ast
              parser.parseAndPatch(source, ast, affectedNode)
// finally we send a "ast updated for UID" message to kod, passing the new
// ast and telling kod to what extent the source was affected
[node -> kod] updateAST(UID, AST, affectedNode.extent)