feat: add parent pointers to nodes and a traverse function (#251)

Also throw in some other breaking changes and other cleanups.

BREAKING CHANGE: All nodes now have a `parentNode` field.

Shorthand object initializers now have a `null` value rather than using the same
node as the key and the value. This ensures no node gets traversed twice in a
traversal.

The `range` field has been removed from nodes. Code should now use `start` and
`end` instead.

Author: alangpierce

package.json

@@ -1,6 +1,7 @@
 {
   "name": "decaffeinate-parser",
   "description": "A better AST for CoffeeScript, inspired by CoffeeScriptRedux.",
+  "version": "0.0.0-development",
   "main": "dist/parser.js",
   "module": "dist/parser.mjs",
   "types": "dist/parser.d.ts",

src/mappers/mapObj.ts

@@ -21,7 +21,7 @@ export default function mapObj(context: ParseContext, node: Obj): ObjectInitiali
       members.push(new ObjectInitialiserMember(
         line, column, start, end, raw,
         value,
-        value
+        null
       ));
     } else if (property instanceof Assign && property.context === 'object') {
       let key = mapAny(context, property.variable);

src/nodes.ts

@@ -4,7 +4,7 @@ import ParseContext from './util/ParseContext';
 export type ChildField = Node | Array<Node | null> | null;
 
 export abstract class Node {
-  readonly range: [number, number];
+  parentNode: Node | null = null;
 
   constructor(
     readonly type: string,
@@ -14,8 +14,6 @@ export abstract class Node {
     readonly end: number,
     readonly raw: string,
   ) {
-    this.range = [start, end];
-    this.raw = raw;
   }
 
   getChildren(): Array<Node> {
@@ -316,7 +314,8 @@ export class ObjectInitialiserMember extends Node {
     end: number,
     raw: string,
     readonly key: Node,
-    readonly expression: Node,
+    // If null, this is a shorthand initializer and the key and value are the same.
+    readonly expression: Node | null,
   ) {
     super('ObjectInitialiserMember', line, column, start, end, raw);
   }

src/parser.ts

@@ -2,13 +2,32 @@ import lex from 'coffee-lex';
 import * as CoffeeScript from 'decaffeinate-coffeescript';
 import { patchCoffeeScript } from './ext/coffee-script';
 import mapProgram from './mappers/mapProgram';
-import { Program } from './nodes';
+import { Node, Program } from './nodes';
 import fixLocations from './util/fixLocations';
 import ParseContext from './util/ParseContext';
 
 export function parse(source: string): Program {
   patchCoffeeScript();
   let context = ParseContext.fromSource(source, lex, CoffeeScript.nodes);
   fixLocations(context, context.ast);
-  return mapProgram(context);
+  let program = mapProgram(context);
+  traverse(program, (node, parent) => {
+    node.parentNode = parent;
+  });
+  return program;
+}
+
+export function traverse(
+  node: Node,
+  callback: (node: Node, parent: Node | null) => boolean | void
+): void {
+  function traverseRec(currentNode: Node, currentParent: Node | null): void {
+    let shouldDescend = callback(currentNode, currentParent);
+    if (shouldDescend !== false) {
+      for (let child of currentNode.getChildren()) {
+        traverseRec(child, currentNode);
+      }
+    }
+  }
+  traverseRec(node, null);
 }

test/examples/addition/output.json

@@ -1,55 +1,45 @@
 {
   "body": {
     "column": 1,
+    "end": 5,
     "inline": false,
     "line": 1,
-    "range": [
-      0,
-      5
-    ],
     "raw": "3 + 4",
+    "start": 0,
     "statements": [
       {
         "column": 1,
+        "end": 5,
         "left": {
           "column": 1,
           "data": 3,
+          "end": 1,
           "line": 1,
-          "range": [
-            0,
-            1
-          ],
           "raw": "3",
+          "start": 0,
           "type": "Int"
         },
         "line": 1,
-        "range": [
-          0,
-          5
-        ],
         "raw": "3 + 4",
         "right": {
           "column": 5,
           "data": 4,
+          "end": 5,
           "line": 1,
-          "range": [
-            4,
-            5
-          ],
           "raw": "4",
+          "start": 4,
           "type": "Int"
         },
+        "start": 0,
         "type": "PlusOp"
       }
     ],
     "type": "Block"
   },
   "column": 1,
+  "end": 5,
   "line": 1,
-  "range": [
-    0,
-    5
-  ],
   "raw": "3 + 4",
+  "start": 0,
   "type": "Program"
 }

test/examples/array-with-multiple-members/output.json

@@ -1,68 +1,56 @@
 {
   "body": {
     "column": 1,
+    "end": 9,
     "inline": false,
     "line": 1,
-    "range": [
-      0,
-      9
-    ],
     "raw": "[1, 2, 3]",
+    "start": 0,
     "statements": [
       {
         "column": 1,
+        "end": 9,
         "line": 1,
         "members": [
           {
             "column": 2,
             "data": 1,
+            "end": 2,
             "line": 1,
-            "range": [
-              1,
-              2
-            ],
             "raw": "1",
+            "start": 1,
             "type": "Int"
           },
           {
             "column": 5,
             "data": 2,
+            "end": 5,
             "line": 1,
-            "range": [
-              4,
-              5
-            ],
             "raw": "2",
+            "start": 4,
             "type": "Int"
           },
           {
             "column": 8,
             "data": 3,
+            "end": 8,
             "line": 1,
-            "range": [
-              7,
-              8
-            ],
             "raw": "3",
+            "start": 7,
             "type": "Int"
           }
         ],
-        "range": [
-          0,
-          9
-        ],
         "raw": "[1, 2, 3]",
+        "start": 0,
         "type": "ArrayInitialiser"
       }
     ],
     "type": "Block"
   },
   "column": 1,
+  "end": 9,
   "line": 1,
-  "range": [
-    0,
-    9
-  ],
   "raw": "[1, 2, 3]",
+  "start": 0,
   "type": "Program"
 }

test/examples/array-with-single-member/output.json

@@ -1,46 +1,38 @@
 {
   "body": {
     "column": 1,
+    "end": 3,
     "inline": false,
     "line": 1,
-    "range": [
-      0,
-      3
-    ],
     "raw": "[1]",
+    "start": 0,
     "statements": [
       {
         "column": 1,
+        "end": 3,
         "line": 1,
         "members": [
           {
             "column": 2,
             "data": 1,
+            "end": 2,
             "line": 1,
-            "range": [
-              1,
-              2
-            ],
             "raw": "1",
+            "start": 1,
             "type": "Int"
           }
         ],
-        "range": [
-          0,
-          3
-        ],
         "raw": "[1]",
+        "start": 0,
         "type": "ArrayInitialiser"
       }
     ],
     "type": "Block"
   },
   "column": 1,
+  "end": 3,
   "line": 1,
-  "range": [
-    0,
-    3
-  ],
   "raw": "[1]",
+  "start": 0,
   "type": "Program"
 }

test/examples/assign/output.json

@@ -1,55 +1,45 @@
 {
   "body": {
     "column": 1,
+    "end": 5,
     "inline": false,
     "line": 1,
-    "range": [
-      0,
-      5
-    ],
     "raw": "a = 1",
+    "start": 0,
     "statements": [
       {
         "assignee": {
           "column": 1,
           "data": "a",
+          "end": 1,
           "line": 1,
-          "range": [
-            0,
-            1
-          ],
           "raw": "a",
+          "start": 0,
           "type": "Identifier"
         },
         "column": 1,
+        "end": 5,
         "expression": {
           "column": 5,
           "data": 1,
+          "end": 5,
           "line": 1,
-          "range": [
-            4,
-            5
-          ],
           "raw": "1",
+          "start": 4,
           "type": "Int"
         },
         "line": 1,
-        "range": [
-          0,
-          5
-        ],
         "raw": "a = 1",
+        "start": 0,
         "type": "AssignOp"
       }
     ],
     "type": "Block"
   },
   "column": 1,
+  "end": 5,
   "line": 1,
-  "range": [
-    0,
-    5
-  ],
   "raw": "a = 1",
+  "start": 0,
   "type": "Program"
 }

test/examples/backticks-with-string-inside/output.json

@@ -1,34 +1,28 @@
 {
   "body": {
     "column": 1,
+    "end": 23,
     "inline": false,
     "line": 1,
-    "range": [
-      0,
-      23
-    ],
     "raw": "`import foo from 'foo'`",
+    "start": 0,
     "statements": [
       {
         "column": 1,
         "data": "import foo from 'foo'",
+        "end": 23,
         "line": 1,
-        "range": [
-          0,
-          23
-        ],
         "raw": "`import foo from 'foo'`",
+        "start": 0,
         "type": "JavaScript"
       }
     ],
     "type": "Block"
   },
   "column": 1,
+  "end": 24,
   "line": 1,
-  "range": [
-    0,
-    24
-  ],
   "raw": "`import foo from 'foo'`\n",
+  "start": 0,
   "type": "Program"
 }