Merge pull request peggyjs#451 from markw65/jsdoc-stack

Make stack.js ts clean

CHANGELOG.md

@@ -16,6 +16,7 @@ Released: TBD
 
 ### Minor Changes
 
+- [#451](https://github.com/peggyjs/peggy/pull/451) Make stack.js ts clean
 - [#439](https://github.com/peggyjs/peggy/pull/439) Make peg$computePosDetails a little faster
 - [#437](https://github.com/peggyjs/peggy/pull/437) Better type checking for visitor
 - [#435](https://github.com/peggyjs/peggy/pull/435) Setup tsconfig to detect use of library functions from es6 or later

lib/compiler/stack.js

@@ -1,8 +1,13 @@
+// @ts-check
 "use strict";
 
 const { SourceNode } = require("source-map-generator");
 const GrammarLocation = require("../grammar-location.js");
 
+/**
+ * @typedef {(string|SourceNode)[]} SourceArray
+ */
+
 /** Utility class that helps generating code for C-like languages. */
 class Stack {
   /**
@@ -27,7 +32,10 @@ class Stack {
      * @type {Record<number,{label:string,location:import("../peg.js").LocationRange}>}
      */
     this.labels         = {};
-    /* Stack of in-flight source mappings */
+    /**
+     *  Stack of in-flight source mappings
+     * @type {[SourceArray, number, PEG.LocationRange][]}
+     */
     this.sourceMapStack = [];
   }
 
@@ -49,6 +57,13 @@ class Stack {
     return this.varName + i;
   }
 
+  /**
+   *
+   * @param {PEG.LocationRange} location
+   * @param {SourceArray} chunks
+   * @param {string} [name]
+   * @returns
+   */
   static sourceNode(location, chunks, name) {
     const start = GrammarLocation.offsetStart(location);
     return new SourceNode(
@@ -150,7 +165,7 @@ class Stack {
   /**
    * Returns name of the variable at index `i`.
    *
-   * @param {number} [i] Index of the variable from top of the stack
+   * @param {number} i Index of the variable from top of the stack
    * @return {string} Generated name
    *
    * @throws {RangeError} If `i < 0` or more than the stack size
@@ -258,6 +273,11 @@ class Stack {
     return result;
   }
 
+  /**
+   *
+   * @param {SourceArray} parts
+   * @param {PEG.LocationRange} location
+   */
   sourceMapPush(parts, location) {
     if (this.sourceMapStack.length) {
       const top = this.sourceMapStack[this.sourceMapStack.length - 1];
@@ -281,12 +301,21 @@ class Stack {
     ]);
   }
 
+  /**
+   * @returns {{parts:SourceArray,location:PEG.LocationRange}}
+   */
   sourceMapPopInternal() {
+    const elt = this.sourceMapStack.pop();
+    if (!elt) {
+      throw new RangeError(
+        `Rule '${this.ruleName}': Attempting to pop an empty source map stack.\nBytecode: ${this.bytecode}`
+      );
+    }
     const [
       parts,
       index,
       location,
-    ] = this.sourceMapStack.pop();
+    ] = elt;
     const chunks = parts.splice(index).map(
       chunk => (chunk instanceof SourceNode
         ? chunk
@@ -305,6 +334,10 @@ class Stack {
     return { parts, location };
   }
 
+  /**
+   * @param {number} [offset]
+   * @returns {[SourceArray, number, PEG.LocationRange]|undefined}
+   */
   sourceMapPop(offset) {
     const { location } = this.sourceMapPopInternal();
     if (this.sourceMapStack.length
@@ -325,6 +358,7 @@ class Stack {
         newLoc,
       ]);
     }
+    return undefined;
   }
 }
 

test/unit/compiler/stack.spec.js

@@ -47,6 +47,13 @@ describe("utility class Stack", () => {
           "Rule 'rule': The variable stack underflow: attempt to use a variable 'v<x>' at an index -3.\nBytecode: 42"
         );
       });
+
+      it("`sourceMapPop`", () => {
+        expect(() => stack.sourceMapPop()).to.throw(
+          RangeError,
+          "Rule 'rule': Attempting to pop an empty source map stack.\nBytecode: 42"
+        );
+      });
     });
 
     it("`defines` returns an empty string", () => {
@@ -268,4 +275,14 @@ describe("utility class Stack", () => {
       );
     });
   });
+
+  describe("SourceNode handling", () => {
+    it("sourceNode handles unknown column", () => {
+      expect(Stack.sourceNode({
+        source: "",
+        start: { line:1, column:0, offset:0 },
+        end: { line:1, column:0, offset:0 },
+      }, ["foo"], "test").column).to.equal(null);
+    });
+  });
 });