feat: Replace the parser generated by Jison with a hand-built parser from JJU

BREAKING CHANGE: There is no `yy.parseError` to intercept error handling. Use the thrown error - it contains all available information. The error does not include the `hash` object with structured information. Look for the [documentd properties](/prantlf/jsonlint#error-handling). The location of the error occurrence is available as `location.start`, for example.

DEPRECATION: The only exposed object to use from now on is the `parse` method as a named export. Other exports (`parser` and `Parser`) are deprecated and will be removed in future.

The parser from ["Utilities to work with JSON/JSON5 documents"](/rlidwka/jju) is four times faster, than the prevous one, has approximatly the same size and can be easier enhanced, regarding both features and error handling.

Author: prantlf

.eslintignore

@@ -4,4 +4,5 @@ jsonlint*.js
 test/fails
 test/passes
 test/recursive
+test/v8
 web/*.min.*

.vscode/launch.json

@@ -4,11 +4,11 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "bin",
+      "name": "cli",
       "program": "${workspaceRoot}/lib/cli.js",
       "args": [
         "-C",
-        "package.json"
+        "test/passes/1.json"
       ],
       "skipFiles": [
         "<node_internals>/**/*.js"
@@ -18,7 +18,7 @@
       "type": "node",
       "request": "launch",
       "name": "test",
-      "program": "${workspaceRoot}/test/all-tests",
+      "program": "${workspaceRoot}/test/parse1.js",
       "args": [
         "--native-parser"
       ],

.vscode/settings.json

@@ -7,7 +7,11 @@
   "search.exclude": {
     "**/benchmarks/jison": true,
     "**/benchmarks/pegjs": true,
-    "**/coverage": true
-  },
+    "**/coverage": true,
+    "**/test/fails": true,
+    "**/test/passes": true,
+    "**/test/recursive": true,
+    "**/test/v8": true
+},
   "eslint.enable": true
 }

README.md

@@ -17,9 +17,9 @@ This is a fork of the original package with the following enhancements:
 * Can parse and skip JavaScript-style comments.
 * Can accept single quotes (apostrophes) as string delimiters.
 * Implements JavaScript modules using [UMD](https://github.com/umdjs/umd) to work everywhere.
-* Can use the native JSON parser to gain the [best performance](./benchmarks#json-parser-comparison), while showing error messages of the same quality.
+* Prefers using the native JSON parser to gain the [best performance](./benchmarks#json-parser-comparison), while showing error messages of the same quality.
 * Depends on up-to-date npm modules with no installation warnings.
-* Small size - 13.4 kB minified, 4.6 kB gzipped.
+* Small size - 17.6 kB minified, 6.1 kB gzipped.
 
 ## Command-line Interface
 
@@ -91,51 +91,65 @@ parse("{'creative': true /* for creativity */}", {
 })
 ```
 
-Parsing methods return the parsed object or throw an error. If the data cam be parsed, you will be able to validate them against a JSON schema in addition:
+The parsing method returns the parsed object or throws an error. If the parsing succeeds, you can to validate the input against a JSON schema too:
 
 ```js
-const { parser } = require('@prantlf/jsonlint')
-const validator = require('@prantlf/jsonlint/lib/validator')
-const validate = validator.compile('string with JSON schema')
+const { parse } = require('@prantlf/jsonlint')
+const { compile } = require('@prantlf/jsonlint/lib/validator')
+const validate = compile('string with JSON schema')
 // Throws an error in case of failure.
-validate(parser.parse('string with JSON data'))
+validate(parse('string with JSON data'))
 ```
 
-Compiling JSON schema supports the same options for customisation and performance improvement as parsing JSON data (`ignoreComments`, `allowSingleQuotedStrings`, `limitedErrorInfo`). They can be passed as the second (object) parameter. The optional second `environment` parameter can be passed as an additional property in the options object:
+Compiling JSON schema supports the same options as parsing JSON data (`ignoreComments`, `allowSingleQuotedStrings`). They can be passed as the second (object) parameter. The optional second `environment` parameter can be passed as an additional property in the options object too:
 
 ```js
-const validator = require('@prantlf/jsonlint/lib/validator')
-const validate = validator.compile('string with JSON schema', {
-  limitedErrorInfo: true,
+const validate = compile('string with JSON schema', {
   environment: 'json-schema-draft-04'
 })
-validate(jsonData)
 ```
 
 ### Performance
 
 This is a part of an output from the [parser benchmark](./benchmarks#json-parser-comparison), when parsing a 4.2 KB formatted string ([package.json](./package.json)) with Node.js 10.15.3:
 
     the built-in parser x 61,588 ops/sec ±0.75% (80 runs sampled)
-    the pure jison parser x 2,516 ops/sec ±1.31% (84 runs sampled)
-    the extended jison parser x 2,434 ops/sec ±0.74% (89 runs sampled)
+    the pure jju parser x 11,396 ops/sec ±1.05% (86 runs sampled)
+    the extended jju parser x 8,221 ops/sec ±0.99% (87 runs sampled)
+
+A custom JSON parser is [a lot slower](./benchmarks/results/performance.md#results) than the built-in one. However, it is more important to have a [clear error reporting](./benchmarks/results/errorReportingQuality.md#results) than the highest speed in scenarios like parsing configuration files. Extending the parser with the support for comments and single-quoted strings does not affect significantly the performance.
+
+### Error Handling
+
+If parsing fails, a `SyntaxError` will be thrown with the following properties:
+
+| Property   | Description                               |
+| ---------- | ----------------------------------------- |
+| `message`  | the full multi-line error message         |
+| `reason`   | one-line explanation of the error         |
+| `exzerpt`  | part of the input string around the error |
+| `pointer`  | "--^" pointing to the error in `exzerpt`  |
+| `location` | object pointing to the error location     |
+
+The `location` object contains properties `line`, `column` and `offset`.
 
-The custom JSON parser is [a lot slower](./benchmarks/results/performance.md#results) than the built-in one. However, it is more important to have a [clear error reporting](./benchmarks/results/errorReportingQuality.md#results) than the highest speed in scenarios like parsing configuration files. Extending the parser with the support for comments and single-quoted strings does not affect significantly the performance.
+The following code logs twice the following message:
 
-You can enable the (fastest) native JSON parser by the `limitedErrorInfo` option, if you do not need the full structured error information provided by the custom parser. The error thrown by the native parser includes the same rich message, but some properties are missing, because the native parser does not return structured information. Parts of the message are returned instead to allow custom error reporting:
+    Parse error on line 1, column 14:
+    {"creative": ?}
+    -------------^
+    Unexpected token ?
 
 ```js
 const { parse } = require('@prantlf/jsonlint')
 try {
-  parse('{"creative": ?}', { limitedErrorInfo: true })
+  parse('{"creative": ?}')
 } catch (error) {
   const { message, reason, exzerpt, pointer, location } = error
   const { column, line, offset } = location.start
-  // Logs the same text as is included in the `message` property:
-  //  Parse error on line 1, column 14:
-  //  {"creative": ?}
-  //  -------------^
-  //  Unexpected token ?
+  // Logs the complete error message:
+  console.log(message)
+  // Logs the same text as included in the `message` property:
   console.log(`Parse error on line ${line}, ${column} column:
 ${exzerpt}
 ${pointer}

lib/cli.js

@@ -2,7 +2,7 @@
 
 var fs = require('fs')
 var path = require('path')
-var parser = require('./jsonlint').parser
+var parser = require('./jsonlint')
 var formatter = require('./formatter')
 var sorter = require('./sorter')
 var validator = require('./validator')
@@ -36,43 +36,22 @@ var options = require('commander')
   })
   .parse(process.argv)
 
-// Workaround for missing column number in jison error output.
-function parseError (message, hash) {
-  const match = /Parse error on line (\d+):/.exec(message)
-  if (match) {
-    const loc = parseError.yy.yylloc
-    message = message.substr(0, match.index) +
-      `Parse error on line ${match[1]}` +
-      (loc ? `, column ${loc.first_column + 1}:` : ':') +
-      message.substr(match.index + match[0].length)
-  }
-  if (hash.recoverable) {
-    this.trace(message)
-  } else {
-    const error = new SyntaxError(message)
-    error.hash = hash
-    throw error
-  }
+function logNormalError (error, file) {
+  console.log('File:', file)
+  console.error(error.message)
 }
 
-parser.yy.parseError = parseError
-
-var parsedFile
-if (options.compact) {
-  parser.parseError = parser.yy.parseError = parser.lexer.parseError = function (str, hash) {
-    console.error(parsedFile + ': line ' + hash.loc.first_line + ', col ' + hash.loc.last_column + ', found: \'' + hash.token + '\' - expected: ' + hash.expected.join(', ') + '.')
-    throw new Error(str)
-  }
+function logCompactError (error, file) {
+  console.error(file + ': line ' + error.location.start.line +
+    ', col ' + error.location.start.column + ', ' + error.reason + '.')
 }
 
 function parse (source, file) {
   var parserOptions, parsed, formatted
-  parsedFile = file
   try {
     parserOptions = {
       ignoreComments: options.comments,
-      allowSingleQuotedStrings: options.singleQuotedStrings,
-      limitedErrorInfo: !(options.comments || options.singleQuotedStrings)
+      allowSingleQuotedStrings: options.singleQuotedStrings
     }
     parsed = parser.parse(source, parserOptions)
     if (options.sortKeys) {
@@ -87,19 +66,9 @@ function parse (source, file) {
       } catch (error) {
         var message = 'Loading the JSON schema failed: "' +
           options.validate + '".\n' + error.message
-        if (options.compact) {
-          console.error(file + ':', error.message)
-        }
         throw new Error(message)
       }
-      try {
-        validate(parsed)
-      } catch (error) {
-        if (options.compact) {
-          console.error(file + ':', error.message)
-        }
-        throw error
-      }
+      validate(parsed)
     }
     return JSON.stringify(parsed, null, options.indent)
   } catch (e) {
@@ -114,17 +83,19 @@ function parse (source, file) {
         // Re-parse so exception output gets better line numbers
         parsed = parser.parse(formatted)
       } catch (e) {
-        if (!options.compact) {
-          console.log('File:', file)
-          console.error(e)
+        if (options.compact) {
+          logCompactError(e, file)
+        } else {
+          logNormalError(e, file)
         }
         // force the pretty print before exiting
         console.log(formatted)
       }
     } else {
-      if (!options.compact) {
-        console.log('File:', file)
-        console.error(e)
+      if (options.compact) {
+        logCompactError(e, file)
+      } else {
+        logNormalError(e, file)
       }
     }
     process.exit(1)

lib/validator.js

@@ -55,8 +55,7 @@
     try {
       schema = jsonlint.parse(schema, {
         ignoreComments: options.ignoreComments,
-        allowSingleQuotedStrings: options.allowSingleQuotedStrings,
-        limitedErrorInfo: options.limitedErrorInfo
+        allowSingleQuotedStrings: options.allowSingleQuotedStrings
       })
       validate = ajv.compile(schema)
     } catch (error) {