@speclynx/apidom-parser-adapter-json 4.0.1 → 4.0.3

package/src/tree-sitter/lexical-analysis/index.ts

@@ -0,0 +1,48 @@
+import { Tree, Parser, Language } from 'web-tree-sitter';
+import treeSitter from 'web-tree-sitter/web-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';
+
+let parser: Parser | null = null;
+let parserInitLock: Promise<Parser> | null = null;
+
+/**
+ * Lexical Analysis of source string using WebTreeSitter.
+ * This is WebAssembly version of TreeSitters Lexical Analysis.
+ *
+ * Given JavaScript doesn't support true parallelism, this
+ * code should be as lazy as possible and temporal safety should be fine.
+ * @public
+ */
+const analyze = async (source: string): Promise<Tree> => {
+  if (parser === null && parserInitLock === null) {
+    // acquire lock
+    parserInitLock = Parser.init({
+      wasmBinary: treeSitter,
+      locateFile: (scriptName: string) => scriptName,
+    } as unknown as EmscriptenModule)
+      .then(() => Language.load(treeSitterJson))
+      .then((jsonLanguage) => {
+        const parserInstance = new Parser();
+        parserInstance.setLanguage(jsonLanguage);
+        return parserInstance;
+      })
+      .finally(() => {
+        // release lock
+        parserInitLock = null;
+      });
+    parser = await parserInitLock;
+  } else if (parser === null && parserInitLock !== null) {
+    // await for lock to be released if there is one
+    parser = await parserInitLock;
+  } else if (parser === null) {
+    throw new ApiDOMError(
+      'Error while initializing web-tree-sitter and loading tree-sitter-json grammar.',
+    );
+  }
+
+  return parser.parse(source) as Tree;
+};
+
+export default analyze;

package/src/tree-sitter/syntactic-analysis/index.cjs

@@ -0,0 +1,280 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+const getCursorInfo = cursor => ({
+  type: cursor.nodeType,
+  startPosition: cursor.startPosition,
+  endPosition: cursor.endPosition,
+  startIndex: cursor.startIndex,
+  endIndex: cursor.endIndex,
+  text: cursor.nodeText,
+  isNamed: cursor.nodeIsNamed,
+  isMissing: cursor.nodeIsMissing,
+  hasError: cursor.currentNode.hasError,
+  fieldName: cursor.currentFieldName
+});
+const maybeAddSourceMap = (info, element, ctx) => {
+  if (!ctx.sourceMap) {
+    return;
+  }
+  element.startLine = info.startPosition.row;
+  element.startCharacter = info.startPosition.column;
+  element.startOffset = info.startIndex;
+  element.endLine = info.endPosition.row;
+  element.endCharacter = info.endPosition.column;
+  element.endOffset = info.endIndex;
+};
+
+// build json style object for an element
+const buildJsonStyle = (ctx, extras) => {
+  const jsonStyle = {
+    indent: ctx.indent
+  };
+  if (extras) Object.assign(jsonStyle, extras);
+  return {
+    json: jsonStyle
+  };
+};
+
+// detect indent from an object's first pair child position
+// called during transformChildren when we encounter the first pair
+const detectIndent = (objectColumn, firstPairColumn) => {
+  const diff = firstPairColumn - objectColumn;
+  return diff > 0 ? diff : 2;
+};
+const transform = (cursor, transformerMap, ctx) => {
+  const info = getCursorInfo(cursor);
+
+  // Handle missing anonymous literals
+  if (!info.isNamed && info.isMissing) {
+    const value = info.type || info.text;
+    const message = `(Missing ${value})`;
+    const element = new _apidomDatamodel.AnnotationElement(message);
+    element.classes.push('warning');
+    maybeAddSourceMap(info, element, ctx);
+    ctx.annotations.push(element);
+    return null;
+  }
+  const transformer = transformerMap[info.type];
+  if (!transformer) {
+    return null; // remove unrecognized nodes
+  }
+  return transformer(cursor, ctx);
+};
+const transformChildren = (cursor, transformerMap, ctx) => {
+  const results = [];
+  if (cursor.gotoFirstChild()) {
+    do {
+      const transformed = transform(cursor, transformerMap, ctx);
+      if (transformed !== null) {
+        results.push(transformed);
+      }
+    } while (cursor.gotoNextSibling());
+    cursor.gotoParent();
+  }
+  return results;
+};
+const createTransformers = transformerMap => ({
+  document(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.ParseResultElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Transform children
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+
+    // Mark first non-Annotation element as result
+    // @ts-ignore
+    const elements = element.findElements(_apidomDatamodel.isPrimitiveElement);
+    if (elements.length > 0) {
+      elements[0].classes.push('result');
+    }
+
+    // Add collected annotations
+    for (const annotation of ctx.annotations) {
+      element.push(annotation);
+    }
+    ctx.annotations = [];
+    return element;
+  },
+  object(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.ObjectElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Detect indent from first pair if style is enabled and not yet detected
+    if (ctx.style && ctx.indent === 0) {
+      if (cursor.gotoFirstChild()) {
+        do {
+          if (cursor.nodeType === 'pair') {
+            ctx.indent = detectIndent(info.startPosition.column, cursor.startPosition.column);
+            break;
+          }
+        } while (cursor.gotoNextSibling());
+        cursor.gotoParent();
+      }
+    }
+
+    // Transform children (pairs)
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    return element;
+  },
+  array(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.ArrayElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Transform children
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    return element;
+  },
+  pair(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    let key = null;
+    let value = null;
+
+    // Find key and value by field name
+    if (cursor.gotoFirstChild()) {
+      do {
+        const fieldName = cursor.currentFieldName;
+        if (fieldName === 'key') {
+          key = transform(cursor, transformerMap, ctx);
+        } else if (fieldName === 'value') {
+          value = transform(cursor, transformerMap, ctx);
+        } else if (cursor.nodeType === 'ERROR') {
+          // Process error nodes
+          transform(cursor, transformerMap, ctx);
+        }
+      } while (cursor.gotoNextSibling());
+      cursor.gotoParent();
+    }
+    const element = new _apidomDatamodel.MemberElement(key ?? new _apidomDatamodel.StringElement(''), value ?? new _apidomDatamodel.StringElement(''));
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  string(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    let element;
+    try {
+      element = new _apidomDatamodel.StringElement(JSON.parse(info.text));
+    } catch (error) {
+      element = new _apidomDatamodel.StringElement(info.text);
+      if (error instanceof Error) {
+        element.meta.set('jsonParse', {
+          isError: true,
+          errorType: error.name,
+          errorMessage: error.message
+        });
+      }
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  number(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.NumberElement(Number(info.text));
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx, {
+        rawContent: info.text
+      });
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  null(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.NullElement();
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  true(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.BooleanElement(true);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  false(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new _apidomDatamodel.BooleanElement(false);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  ERROR(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const isUnexpected = !info.hasError;
+    const message = isUnexpected ? `(Unexpected ${info.text})` : `(Error ${info.text})`;
+    const element = new _apidomDatamodel.AnnotationElement(message);
+    element.classes.push('error');
+    maybeAddSourceMap(info, element, ctx);
+    ctx.annotations.push(element);
+    return null;
+  }
+});
+
+// Create the transformers map with self-reference for recursion
+const transformers = {};
+Object.assign(transformers, createTransformers(transformers));
+
+/**
+ * Syntactic analysis translates TreeSitter CST directly into ApiDOM.
+ *
+ * Direct transformation from TreeSitter CST using TreeSitter cursor.
+ * TreeSitter cursor is a stateful object that allows us to walk syntax tree
+ * containing large number of nodes with maximum efficiency.
+ *
+ * Single pass transformation from CST to ApiDOM.
+ * @public
+ */
+const analyze = (cst, {
+  sourceMap = false,
+  style = false
+} = {}) => {
+  const cursor = cst.walk();
+  const ctx = {
+    sourceMap,
+    style,
+    indent: 0,
+    annotations: []
+  };
+  const result = transform(cursor, transformers, ctx);
+
+  // Handle case where there's no document, only errors
+  if (result === null) {
+    const parseResult = new _apidomDatamodel.ParseResultElement();
+    for (const annotation of ctx.annotations) {
+      parseResult.push(annotation);
+    }
+    return parseResult;
+  }
+  return result;
+};
+var _default = exports.default = analyze;

package/src/tree-sitter/syntactic-analysis/index.mjs

@@ -0,0 +1,276 @@
+import { BooleanElement, NullElement, NumberElement, ParseResultElement, MemberElement, ObjectElement, ArrayElement, StringElement, AnnotationElement, isPrimitiveElement } from '@speclynx/apidom-datamodel';
+const getCursorInfo = cursor => ({
+  type: cursor.nodeType,
+  startPosition: cursor.startPosition,
+  endPosition: cursor.endPosition,
+  startIndex: cursor.startIndex,
+  endIndex: cursor.endIndex,
+  text: cursor.nodeText,
+  isNamed: cursor.nodeIsNamed,
+  isMissing: cursor.nodeIsMissing,
+  hasError: cursor.currentNode.hasError,
+  fieldName: cursor.currentFieldName
+});
+const maybeAddSourceMap = (info, element, ctx) => {
+  if (!ctx.sourceMap) {
+    return;
+  }
+  element.startLine = info.startPosition.row;
+  element.startCharacter = info.startPosition.column;
+  element.startOffset = info.startIndex;
+  element.endLine = info.endPosition.row;
+  element.endCharacter = info.endPosition.column;
+  element.endOffset = info.endIndex;
+};
+
+// build json style object for an element
+const buildJsonStyle = (ctx, extras) => {
+  const jsonStyle = {
+    indent: ctx.indent
+  };
+  if (extras) Object.assign(jsonStyle, extras);
+  return {
+    json: jsonStyle
+  };
+};
+
+// detect indent from an object's first pair child position
+// called during transformChildren when we encounter the first pair
+const detectIndent = (objectColumn, firstPairColumn) => {
+  const diff = firstPairColumn - objectColumn;
+  return diff > 0 ? diff : 2;
+};
+const transform = (cursor, transformerMap, ctx) => {
+  const info = getCursorInfo(cursor);
+
+  // Handle missing anonymous literals
+  if (!info.isNamed && info.isMissing) {
+    const value = info.type || info.text;
+    const message = `(Missing ${value})`;
+    const element = new AnnotationElement(message);
+    element.classes.push('warning');
+    maybeAddSourceMap(info, element, ctx);
+    ctx.annotations.push(element);
+    return null;
+  }
+  const transformer = transformerMap[info.type];
+  if (!transformer) {
+    return null; // remove unrecognized nodes
+  }
+  return transformer(cursor, ctx);
+};
+const transformChildren = (cursor, transformerMap, ctx) => {
+  const results = [];
+  if (cursor.gotoFirstChild()) {
+    do {
+      const transformed = transform(cursor, transformerMap, ctx);
+      if (transformed !== null) {
+        results.push(transformed);
+      }
+    } while (cursor.gotoNextSibling());
+    cursor.gotoParent();
+  }
+  return results;
+};
+const createTransformers = transformerMap => ({
+  document(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new ParseResultElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Transform children
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+
+    // Mark first non-Annotation element as result
+    // @ts-ignore
+    const elements = element.findElements(isPrimitiveElement);
+    if (elements.length > 0) {
+      elements[0].classes.push('result');
+    }
+
+    // Add collected annotations
+    for (const annotation of ctx.annotations) {
+      element.push(annotation);
+    }
+    ctx.annotations = [];
+    return element;
+  },
+  object(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new ObjectElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Detect indent from first pair if style is enabled and not yet detected
+    if (ctx.style && ctx.indent === 0) {
+      if (cursor.gotoFirstChild()) {
+        do {
+          if (cursor.nodeType === 'pair') {
+            ctx.indent = detectIndent(info.startPosition.column, cursor.startPosition.column);
+            break;
+          }
+        } while (cursor.gotoNextSibling());
+        cursor.gotoParent();
+      }
+    }
+
+    // Transform children (pairs)
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    return element;
+  },
+  array(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new ArrayElement();
+    maybeAddSourceMap(info, element, ctx);
+
+    // Transform children
+    const children = transformChildren(cursor, transformerMap, ctx);
+    for (const child of children) {
+      element.push(child);
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    return element;
+  },
+  pair(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    let key = null;
+    let value = null;
+
+    // Find key and value by field name
+    if (cursor.gotoFirstChild()) {
+      do {
+        const fieldName = cursor.currentFieldName;
+        if (fieldName === 'key') {
+          key = transform(cursor, transformerMap, ctx);
+        } else if (fieldName === 'value') {
+          value = transform(cursor, transformerMap, ctx);
+        } else if (cursor.nodeType === 'ERROR') {
+          // Process error nodes
+          transform(cursor, transformerMap, ctx);
+        }
+      } while (cursor.gotoNextSibling());
+      cursor.gotoParent();
+    }
+    const element = new MemberElement(key ?? new StringElement(''), value ?? new StringElement(''));
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  string(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    let element;
+    try {
+      element = new StringElement(JSON.parse(info.text));
+    } catch (error) {
+      element = new StringElement(info.text);
+      if (error instanceof Error) {
+        element.meta.set('jsonParse', {
+          isError: true,
+          errorType: error.name,
+          errorMessage: error.message
+        });
+      }
+    }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  number(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new NumberElement(Number(info.text));
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx, {
+        rawContent: info.text
+      });
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  null(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new NullElement();
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  true(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new BooleanElement(true);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  false(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const element = new BooleanElement(false);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
+    maybeAddSourceMap(info, element, ctx);
+    return element;
+  },
+  ERROR(cursor, ctx) {
+    const info = getCursorInfo(cursor);
+    const isUnexpected = !info.hasError;
+    const message = isUnexpected ? `(Unexpected ${info.text})` : `(Error ${info.text})`;
+    const element = new AnnotationElement(message);
+    element.classes.push('error');
+    maybeAddSourceMap(info, element, ctx);
+    ctx.annotations.push(element);
+    return null;
+  }
+});
+
+// Create the transformers map with self-reference for recursion
+const transformers = {};
+Object.assign(transformers, createTransformers(transformers));
+
+/**
+ * Syntactic analysis translates TreeSitter CST directly into ApiDOM.
+ *
+ * Direct transformation from TreeSitter CST using TreeSitter cursor.
+ * TreeSitter cursor is a stateful object that allows us to walk syntax tree
+ * containing large number of nodes with maximum efficiency.
+ *
+ * Single pass transformation from CST to ApiDOM.
+ * @public
+ */
+const analyze = (cst, {
+  sourceMap = false,
+  style = false
+} = {}) => {
+  const cursor = cst.walk();
+  const ctx = {
+    sourceMap,
+    style,
+    indent: 0,
+    annotations: []
+  };
+  const result = transform(cursor, transformers, ctx);
+
+  // Handle case where there's no document, only errors
+  if (result === null) {
+    const parseResult = new ParseResultElement();
+    for (const annotation of ctx.annotations) {
+      parseResult.push(annotation);
+    }
+    return parseResult;
+  }
+  return result;
+};
+export default analyze;