feat: add support for strict mode in JSON/YAML parser adapters (#22)

Author: char0n

package-lock.json

@@ -52,7 +52,14 @@ Defines list of media types that this parser adapter recognizes.
 
 ### detect
 
-[Detection](https://github.com/speclynx/apidom/blob/main/packages/apidom-parser-adapter-json/src/adapter.ts#L3) is based on using [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) to indicate whether the provided source string is or isn't JSON string.
+Detection indicates whether the provided source string is valid JSON.
+
+Option | Type | Default | Description
+--- | --- | --- | ---
+<a name="detect-strict"></a>`strict` | `Boolean` | `false` | Use strict detection mode (native `JSON.parse`).
+
+In default mode, detection uses tree-sitter for parsing with error recovery.
+In strict mode, detection uses native `JSON.parse` which is faster but requires valid JSON.
 
 ### namespace
 
@@ -65,9 +72,26 @@ This adapter exposes an instance of [base ApiDOM namespace](https://github.com/s
 Option | Type | Default | Description
 --- | --- | --- | ---
 <a name="sourceMap"></a>`sourceMap` | `Boolean` | `false` | Indicate whether to generate source maps.
+<a name="strict"></a>`strict` | `Boolean` | `false` | Use strict parsing mode (native `JSON.parse`). When `true`, parsing is faster but throws on invalid JSON and doesn't support source maps.
 
 All unrecognized arbitrary options will be ignored.
 
+#### Parsing modes
+
+This adapter supports two parsing modes:
+
+**Tree-sitter mode** (default, `strict: false`):
+- Uses [web-tree-sitter](https://www.npmjs.com/package/web-tree-sitter) for parsing
+- Provides error recovery for malformed JSON
+- Supports source map generation
+- Slightly slower but more resilient
+
+**Strict mode** (`strict: true`):
+- Uses native `JSON.parse` for parsing
+- Faster performance
+- Throws `SyntaxError` on invalid JSON
+- Does not support source maps (throws error if both `strict` and `sourceMap` are `true`)
+
 ## Usage
 
 This parser adapter can be used directly or indirectly via [@speclynx/apidom-parser](https://github.com/speclynx/apidom/tree/main/packages/apidom-parser).
@@ -80,12 +104,19 @@ with [supported media types](#mediatypes).
 ```js
 import { parse, detect } from '@speclynx/apidom-parser-adapter-json';
 
-// detecting
+// detecting (tree-sitter mode - default)
 await detect('{"prop": "value"}'); // => true
 await detect('test'); // => false
 
-// parsing
+// detecting (strict mode)
+await detect('{"prop": "value"}', { strict: true }); // => true
+await detect('{invalid}', { strict: true }); // => false
+
+// parsing (tree-sitter mode - default, with source maps)
 const parseResult = await parse('{"prop": "value"}', { sourceMap: true });
+
+// parsing (strict mode - faster, no source maps)
+const parseResultStrict = await parse('{"prop": "value"}', { strict: true });
 ```
 
 ### Indirect usage

packages/apidom-parser-adapter-json/README.md

@@ -1,13 +1,13 @@
 import { ParseResultElement, Namespace } from '@speclynx/apidom-datamodel';
-import type { Tree } from 'web-tree-sitter';
+import { ApiDOMError } from '@speclynx/apidom-error';
 
-import lexicalAnalysis from './lexical-analysis/index.ts';
-import syntacticAnalysis from './syntactic-analysis/index.ts';
+import * as native from './native/index.ts';
+import * as treeSitter from './tree-sitter/index.ts';
 
 export type { JSONMediaTypes } from './media-types.ts';
-export type { Tree };
+export type { Tree } from './tree-sitter/index.ts';
 
-export { lexicalAnalysis, syntacticAnalysis };
+export { lexicalAnalysis, syntacticAnalysis } from './tree-sitter/index.ts';
 
 /**
  * @public
@@ -22,34 +22,34 @@ export const namespace = new Namespace();
 /**
  * @public
  */
-export const detectionRegExp =
-  // eslint-disable-next-line no-control-regex
-  /(?<true>^\s*true\s*$)|(?<false>^\s*false\s*$)|(?<null>^\s*null\s*$)|(?<number>^\s*\d+\s*$)|(?<object>^\s*{\s*)|(?<array>^\s*\[\s*)|(?<string>^\s*"(((?=\\)\\(["\\/bfnrt]|u[0-9a-fA-F]{4}))|[^"\\\x00-\x1F\x7F])*"\s*$)/;
+export const detectionRegExp = treeSitter.detectionRegExp;
 
 /**
  * @public
  */
-export const detect = async (source: string): Promise<boolean> => {
-  if (!detectionRegExp.test(source)) {
-    return false;
-  }
+export interface DetectOptions {
+  strict?: boolean;
+}
 
-  let cst: Tree | null = null;
-  try {
-    cst = await lexicalAnalysis(source);
-    return cst.rootNode.type !== 'ERROR';
-  } catch {
-    return false;
-  } finally {
-    cst?.delete();
+/**
+ * @public
+ */
+export const detect = async (
+  source: string,
+  { strict = false }: DetectOptions = {},
+): Promise<boolean> => {
+  if (strict) {
+    return native.detect(source);
   }
+  return treeSitter.detect(source);
 };
 
 /**
  * @public
  */
 export interface ParseFunctionOptions {
   sourceMap?: boolean;
+  strict?: boolean;
 }
 
 /**
@@ -63,11 +63,16 @@ export type ParseFunction = (
 /**
  * @public
  */
-export const parse: ParseFunction = async (source, { sourceMap = false } = {}) => {
-  const cst = await lexicalAnalysis(source);
-  try {
-    return syntacticAnalysis(cst, { sourceMap });
-  } finally {
-    cst.delete();
+export const parse: ParseFunction = async (source, { sourceMap = false, strict = false } = {}) => {
+  if (strict && sourceMap) {
+    throw new ApiDOMError(
+      'Cannot use sourceMap with strict parsing. Strict parsing does not support source maps.',
+    );
+  }
+
+  if (strict) {
+    return native.parse(source);
   }
+
+  return treeSitter.parse(source, { sourceMap });
 };

packages/apidom-parser-adapter-json/src/adapter.ts

@@ -0,0 +1,25 @@
+import { ParseResultElement, refract } from '@speclynx/apidom-datamodel';
+
+/**
+ * @public
+ */
+export const detect = async (source: string): Promise<boolean> => {
+  try {
+    JSON.parse(source);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * @public
+ */
+export const parse = async (source: string): Promise<ParseResultElement> => {
+  const pojo = JSON.parse(source);
+  const element = refract(pojo);
+  const parseResult = new ParseResultElement();
+  element.classes.push('result');
+  parseResult.push(element);
+  return parseResult;
+};

packages/apidom-parser-adapter-json/src/native/index.ts

@@ -0,0 +1,56 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { Tree } from 'web-tree-sitter';
+
+import lexicalAnalysis from './lexical-analysis/index.ts';
+import syntacticAnalysis from './syntactic-analysis/index.ts';
+
+export type { Tree };
+export { lexicalAnalysis, syntacticAnalysis };
+
+/**
+ * @public
+ */
+export const detectionRegExp =
+  // eslint-disable-next-line no-control-regex
+  /(?<true>^\s*true\s*$)|(?<false>^\s*false\s*$)|(?<null>^\s*null\s*$)|(?<number>^\s*\d+\s*$)|(?<object>^\s*{\s*)|(?<array>^\s*\[\s*)|(?<string>^\s*"(((?=\\)\\(["\\/bfnrt]|u[0-9a-fA-F]{4}))|[^"\\\x00-\x1F\x7F])*"\s*$)/;
+
+/**
+ * @public
+ */
+export const detect = async (source: string): Promise<boolean> => {
+  if (!detectionRegExp.test(source)) {
+    return false;
+  }
+
+  let cst: Tree | null = null;
+  try {
+    cst = await lexicalAnalysis(source);
+    return cst.rootNode.type !== 'ERROR';
+  } catch {
+    return false;
+  } finally {
+    cst?.delete();
+  }
+};
+
+/**
+ * @public
+ */
+export interface ParseOptions {
+  sourceMap?: boolean;
+}
+
+/**
+ * @public
+ */
+export const parse = async (
+  source: string,
+  { sourceMap = false }: ParseOptions = {},
+): Promise<ParseResultElement> => {
+  const cst = await lexicalAnalysis(source);
+  try {
+    return syntacticAnalysis(cst, { sourceMap });
+  } finally {
+    cst.delete();
+  }
+};

packages/apidom-parser-adapter-json/src/tree-sitter/index.ts

@@ -1,5 +1,6 @@
 import { Tree, Parser, Language } from 'web-tree-sitter';
 import treeSitter from 'web-tree-sitter/tree-sitter.wasm';
+// eslint-disable-next-line import/no-extraneous-dependencies
 import treeSitterJson from 'tree-sitter-json/tree-sitter-json.wasm';
 import { ApiDOMError } from '@speclynx/apidom-error';
 

…apter-json/src/lexical-analysis/index.ts …rc/tree-sitter/lexical-analysis/index.tspackages/apidom-parser-adapter-json/src/lexical-analysis/index.ts renamed to packages/apidom-parser-adapter-json/src/tree-sitter/lexical-analysis/index.ts packages/apidom-parser-adapter-json/src/lexical-analysis/index.ts renamed to packages/apidom-parser-adapter-json/src/tree-sitter/lexical-analysis/index.ts

@@ -87,4 +87,46 @@ describe('adapter', function () {
       }
     });
   });
+
+  context('strict mode', function () {
+    context('detect', function () {
+      specify('should detect valid JSON', async function () {
+        assert.isTrue(await adapter.detect('{"key": "value"}', { strict: true }));
+      });
+
+      specify('should not detect invalid JSON', async function () {
+        assert.isFalse(await adapter.detect('{key: value}', { strict: true }));
+      });
+    });
+
+    context('parse', function () {
+      specify('should parse valid JSON', async function () {
+        const parseResult = await adapter.parse(spec, { strict: true });
+
+        assert.isTrue(isParseResultElement(parseResult));
+        assert.isTrue(isObjectElement(parseResult.result));
+      });
+
+      specify('should throw on invalid JSON', async function () {
+        const invalidJson = '{key: value}';
+
+        try {
+          await adapter.parse(invalidJson, { strict: true });
+          assert.fail('Should have thrown an error');
+        } catch (error) {
+          assert.instanceOf(error, SyntaxError);
+        }
+      });
+
+      specify('should throw when strict and sourceMap are both true', async function () {
+        try {
+          await adapter.parse(spec, { strict: true, sourceMap: true });
+          assert.fail('Should have thrown an error');
+        } catch (error) {
+          assert.instanceOf(error, Error);
+          assert.include((error as Error).message, 'Cannot use sourceMap with strict parsing');
+        }
+      });
+    });
+  });
 });

…ter-json/src/syntactic-analysis/index.ts …/tree-sitter/syntactic-analysis/index.tspackages/apidom-parser-adapter-json/src/syntactic-analysis/index.ts renamed to packages/apidom-parser-adapter-json/src/tree-sitter/syntactic-analysis/index.ts packages/apidom-parser-adapter-json/src/syntactic-analysis/index.ts renamed to packages/apidom-parser-adapter-json/src/tree-sitter/syntactic-analysis/index.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import Benchmark from 'benchmark';
 import type { Deferred } from 'benchmark';
 
-import analyze from '../../src/lexical-analysis/index.ts';
+import analyze from '../../src/tree-sitter/lexical-analysis/index.ts';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fixturePath = path.join(__dirname, 'fixtures/data.json');