@speclynx/apidom-datamodel 1.12.2 → 2.0.1

package/src/primitives/Element.cjs

@@ -23,6 +23,60 @@ var _ObjectSlice = _interopRequireDefault(require("../ObjectSlice.cjs"));
  * @public
  */
 class Element {
+  // ============================================================
+  // Public Properties
+  // ============================================================
+
+  /**
+   * Parent element reference (set when tree is frozen).
+   */
+  parent;
+
+  // ============================================================================
+  // Source Position (LSP-compatible, TextDocument-compatible, UTF-16 code units)
+  // web-tree-sitter automatically provides position data in UTF-16 code units.
+  // ============================================================================
+
+  /**
+   * Starting line number (0-based).
+   * Compatible with LSP Position.line.
+   */
+  startLine;
+
+  /**
+   * Starting character offset within the line (0-based, UTF-16 code units).
+   * Compatible with LSP Position.character.
+   */
+  startCharacter;
+
+  /**
+   * Starting offset from beginning of document (UTF-16 code units).
+   * Can be used directly as JavaScript string index.
+   */
+  startOffset;
+
+  /**
+   * Ending line number (0-based).
+   * Compatible with LSP Position.line.
+   */
+  endLine;
+
+  /**
+   * Ending character offset within the line (0-based, UTF-16 code units).
+   * Compatible with LSP Position.character.
+   */
+  endCharacter;
+
+  /**
+   * Ending offset from beginning of document (UTF-16 code units).
+   * Can be used directly as JavaScript string index.
+   */
+  endOffset;
+
+  // ============================================================
+  // Protected Properties
+  // ============================================================
+
   /**
    * The element type identifier.
    * @internal
@@ -47,11 +101,6 @@ class Element {
    */
   _attributes;
 
-  /**
-   * Parent element reference (set when tree is frozen).
-   */
-  parent;
-
   // ============================================================
   // Prototype-assigned properties (set in elements.ts)
   // Using 'declare' allows TypeScript to know about these
@@ -205,22 +254,6 @@ class Element {
     this.setMetaProperty('classes', value);
   }
 
-  /** Human-readable title. */
-  get title() {
-    return this.getMetaProperty('title', '');
-  }
-  set title(value) {
-    this.setMetaProperty('title', value);
-  }
-
-  /** Human-readable description. */
-  get description() {
-    return this.getMetaProperty('description', '');
-  }
-  set description(value) {
-    this.setMetaProperty('description', value);
-  }
-
   /** Hyperlinks associated with this element. */
   get links() {
     return this.getMetaProperty('links', []);
@@ -292,41 +325,6 @@ class Element {
     Object.freeze(this);
   }
 
-  // ============================================================
-  // Cloneable Implementation
-  // ============================================================
-
-  /**
-   * Creates a deep clone of this element.
-   */
-  clone() {
-    const Ctor = this.constructor;
-    const copy = new Ctor();
-    copy.element = this.element;
-    if (this._meta) {
-      copy._meta = this._meta.clone();
-    }
-    if (this._attributes) {
-      copy._attributes = this._attributes.clone();
-    }
-
-    // Clone content based on its type
-    const {
-      _content
-    } = this;
-    if (_content instanceof Element) {
-      copy._content = _content.clone();
-    } else if (_content instanceof _KeyValuePair.default) {
-      copy._content = _content.clone();
-    } else if (Array.isArray(_content)) {
-      copy._content = _content.map(el => el.clone());
-    } else {
-      // Primitives are immutable, assign as-is
-      copy._content = _content;
-    }
-    return copy;
-  }
-
   // ============================================================
   // ToValue Implementation
   // ============================================================
@@ -407,10 +405,6 @@ class Element {
     return ref;
   }
 
-  // ============================================================
-  // Protected Helpers
-  // ============================================================
-
   /**
    * Gets a meta property, creating it with default value if not present.
    */
@@ -432,6 +426,62 @@ class Element {
   setMetaProperty(name, value) {
     this.meta.set(name, value);
   }
+
+  /**
+   * Has meta property.
+   */
+  hasMetaProperty(name) {
+    if (!this.isMetaEmpty) {
+      return this.meta.hasKey(name);
+    }
+    return false;
+  }
+
+  /**
+   * Checks if meta is empty.
+   */
+  get isMetaEmpty() {
+    return this._meta === undefined || this.meta.isEmpty;
+  }
+
+  /**
+   * Gets an attribute property, creating it with default value if not present.
+   */
+  getAttributesProperty(name, defaultValue) {
+    if (!this.hasAttributesProperty(name)) {
+      if (this.isFrozen) {
+        const element = this.refract(defaultValue);
+        element.freeze();
+        return element;
+      }
+      this.attributes.set(name, defaultValue);
+    }
+    return this.attributes.get(name);
+  }
+
+  /**
+   * Sets an attributes property.
+   */
+  setAttributesProperty(name, value) {
+    this.attributes.set(name, value);
+  }
+
+  /**
+   * Has attributes property.
+   */
+  hasAttributesProperty(name) {
+    if (!this.isAttributesEmpty) {
+      return this.attributes.hasKey(name);
+    }
+    return false;
+  }
+
+  /**
+   * Checks if attributes is empty.
+   */
+  get isAttributesEmpty() {
+    return this._attributes === undefined || this.attributes.isEmpty;
+  }
 }
 
 // Re-export types for convenience

package/src/primitives/Element.mjs

@@ -17,6 +17,60 @@ import ObjectSlice from "../ObjectSlice.mjs";
  * @public
  */
 class Element {
+  // ============================================================
+  // Public Properties
+  // ============================================================
+
+  /**
+   * Parent element reference (set when tree is frozen).
+   */
+  parent;
+
+  // ============================================================================
+  // Source Position (LSP-compatible, TextDocument-compatible, UTF-16 code units)
+  // web-tree-sitter automatically provides position data in UTF-16 code units.
+  // ============================================================================
+
+  /**
+   * Starting line number (0-based).
+   * Compatible with LSP Position.line.
+   */
+  startLine;
+
+  /**
+   * Starting character offset within the line (0-based, UTF-16 code units).
+   * Compatible with LSP Position.character.
+   */
+  startCharacter;
+
+  /**
+   * Starting offset from beginning of document (UTF-16 code units).
+   * Can be used directly as JavaScript string index.
+   */
+  startOffset;
+
+  /**
+   * Ending line number (0-based).
+   * Compatible with LSP Position.line.
+   */
+  endLine;
+
+  /**
+   * Ending character offset within the line (0-based, UTF-16 code units).
+   * Compatible with LSP Position.character.
+   */
+  endCharacter;
+
+  /**
+   * Ending offset from beginning of document (UTF-16 code units).
+   * Can be used directly as JavaScript string index.
+   */
+  endOffset;
+
+  // ============================================================
+  // Protected Properties
+  // ============================================================
+
   /**
    * The element type identifier.
    * @internal
@@ -41,11 +95,6 @@ class Element {
    */
   _attributes;
 
-  /**
-   * Parent element reference (set when tree is frozen).
-   */
-  parent;
-
   // ============================================================
   // Prototype-assigned properties (set in elements.ts)
   // Using 'declare' allows TypeScript to know about these
@@ -199,22 +248,6 @@ class Element {
     this.setMetaProperty('classes', value);
   }
 
-  /** Human-readable title. */
-  get title() {
-    return this.getMetaProperty('title', '');
-  }
-  set title(value) {
-    this.setMetaProperty('title', value);
-  }
-
-  /** Human-readable description. */
-  get description() {
-    return this.getMetaProperty('description', '');
-  }
-  set description(value) {
-    this.setMetaProperty('description', value);
-  }
-
   /** Hyperlinks associated with this element. */
   get links() {
     return this.getMetaProperty('links', []);
@@ -286,41 +319,6 @@ class Element {
     Object.freeze(this);
   }
 
-  // ============================================================
-  // Cloneable Implementation
-  // ============================================================
-
-  /**
-   * Creates a deep clone of this element.
-   */
-  clone() {
-    const Ctor = this.constructor;
-    const copy = new Ctor();
-    copy.element = this.element;
-    if (this._meta) {
-      copy._meta = this._meta.clone();
-    }
-    if (this._attributes) {
-      copy._attributes = this._attributes.clone();
-    }
-
-    // Clone content based on its type
-    const {
-      _content
-    } = this;
-    if (_content instanceof Element) {
-      copy._content = _content.clone();
-    } else if (_content instanceof KeyValuePair) {
-      copy._content = _content.clone();
-    } else if (Array.isArray(_content)) {
-      copy._content = _content.map(el => el.clone());
-    } else {
-      // Primitives are immutable, assign as-is
-      copy._content = _content;
-    }
-    return copy;
-  }
-
   // ============================================================
   // ToValue Implementation
   // ============================================================
@@ -401,10 +399,6 @@ class Element {
     return ref;
   }
 
-  // ============================================================
-  // Protected Helpers
-  // ============================================================
-
   /**
    * Gets a meta property, creating it with default value if not present.
    */
@@ -426,6 +420,62 @@ class Element {
   setMetaProperty(name, value) {
     this.meta.set(name, value);
   }
+
+  /**
+   * Has meta property.
+   */
+  hasMetaProperty(name) {
+    if (!this.isMetaEmpty) {
+      return this.meta.hasKey(name);
+    }
+    return false;
+  }
+
+  /**
+   * Checks if meta is empty.
+   */
+  get isMetaEmpty() {
+    return this._meta === undefined || this.meta.isEmpty;
+  }
+
+  /**
+   * Gets an attribute property, creating it with default value if not present.
+   */
+  getAttributesProperty(name, defaultValue) {
+    if (!this.hasAttributesProperty(name)) {
+      if (this.isFrozen) {
+        const element = this.refract(defaultValue);
+        element.freeze();
+        return element;
+      }
+      this.attributes.set(name, defaultValue);
+    }
+    return this.attributes.get(name);
+  }
+
+  /**
+   * Sets an attributes property.
+   */
+  setAttributesProperty(name, value) {
+    this.attributes.set(name, value);
+  }
+
+  /**
+   * Has attributes property.
+   */
+  hasAttributesProperty(name) {
+    if (!this.isAttributesEmpty) {
+      return this.attributes.hasKey(name);
+    }
+    return false;
+  }
+
+  /**
+   * Checks if attributes is empty.
+   */
+  get isAttributesEmpty() {
+    return this._attributes === undefined || this.attributes.isEmpty;
+  }
 }
 
 // Re-export types for convenience

package/src/primitives/MemberElement.cjs

@@ -23,7 +23,11 @@ class MemberElement extends _Element.default {
     if (key !== undefined) {
       this.key = key;
     }
-    if (value !== undefined) {
+
+    // Note: We check arguments.length to distinguish between:
+    // - new MemberElement('key') - value not provided, don't set
+    // - new MemberElement('key', undefined) - value explicitly undefined, set it
+    if (arguments.length >= 2) {
       this.value = value;
     }
   }
@@ -48,7 +52,7 @@ class MemberElement extends _Element.default {
     return this._content.value;
   }
   set value(value) {
-    this._content.value = this.refract(value);
+    this._content.value = value === undefined ? undefined : this.refract(value);
   }
 }
 var _default = exports.default = MemberElement;

package/src/primitives/MemberElement.mjs

@@ -18,7 +18,11 @@ class MemberElement extends Element {
     if (key !== undefined) {
       this.key = key;
     }
-    if (value !== undefined) {
+
+    // Note: We check arguments.length to distinguish between:
+    // - new MemberElement('key') - value not provided, don't set
+    // - new MemberElement('key', undefined) - value explicitly undefined, set it
+    if (arguments.length >= 2) {
       this.value = value;
     }
   }
@@ -43,7 +47,7 @@ class MemberElement extends Element {
     return this._content.value;
   }
   set value(value) {
-    this._content.value = this.refract(value);
+    this._content.value = value === undefined ? undefined : this.refract(value);
   }
 }
 export default MemberElement;

package/src/primitives/ObjectElement.cjs

@@ -210,8 +210,6 @@ class ObjectElement extends _CollectionElement.default {
     return memo;
   }
 
-  // Fantasy Land
-
   /**
    * Returns an empty object element.
    */

package/src/primitives/ObjectElement.mjs

@@ -204,8 +204,6 @@ class ObjectElement extends CollectionElement {
     return memo;
   }
 
-  // Fantasy Land
-
   /**
    * Returns an empty object element.
    */

package/src/registration.cjs

@@ -25,6 +25,14 @@ var _LinkElement = _interopRequireDefault(require("./elements/LinkElement.cjs"))
 exports.LinkElement = _LinkElement.default;
 var _RefElement = _interopRequireDefault(require("./elements/RefElement.cjs"));
 exports.RefElement = _RefElement.default;
+var _Annotation = _interopRequireDefault(require("./elements/Annotation.cjs"));
+exports.AnnotationElement = _Annotation.default;
+var _Comment = _interopRequireDefault(require("./elements/Comment.cjs"));
+exports.CommentElement = _Comment.default;
+var _ParseResult = _interopRequireDefault(require("./elements/ParseResult.cjs"));
+exports.ParseResultElement = _ParseResult.default;
+var _SourceMap = _interopRequireDefault(require("./elements/SourceMap.cjs"));
+exports.SourceMapElement = _SourceMap.default;
 var _ObjectSlice = _interopRequireDefault(require("./ObjectSlice.cjs"));
 exports.ObjectSlice = _ObjectSlice.default;
 var _KeyValuePair = _interopRequireDefault(require("./KeyValuePair.cjs"));

package/src/registration.mjs

@@ -9,6 +9,10 @@ import MemberElement from "./primitives/MemberElement.mjs";
 import ObjectElement from "./primitives/ObjectElement.mjs";
 import LinkElement from "./elements/LinkElement.mjs";
 import RefElement from "./elements/RefElement.mjs";
+import AnnotationElement from "./elements/Annotation.mjs";
+import CommentElement from "./elements/Comment.mjs";
+import ParseResultElement from "./elements/ParseResult.mjs";
+import SourceMapElement from "./elements/SourceMap.mjs";
 import ObjectSlice from "./ObjectSlice.mjs";
 import KeyValuePair from "./KeyValuePair.mjs";
 /**
@@ -65,6 +69,6 @@ Element.prototype.refract = refract;
  * Contains all of the element classes, and related structures and methods
  * for handling with element instances.
  */
-export { Element, CollectionElement, NullElement, StringElement, NumberElement, BooleanElement, ArrayElement, MemberElement, ObjectElement, LinkElement, RefElement, refract, ObjectSlice, KeyValuePair };
+export { Element, CollectionElement, NullElement, StringElement, NumberElement, BooleanElement, ArrayElement, MemberElement, ObjectElement, LinkElement, RefElement, AnnotationElement, CommentElement, ParseResultElement, SourceMapElement, refract, ObjectSlice, KeyValuePair };
 
 // Re-export types from element classes

package/src/serialisers/JSONSerialiser.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
 exports.default = void 0;
+var _SourceMap = _interopRequireDefault(require("../elements/SourceMap.cjs"));
 /**
  * Serialized representation of an Element in JSON Refract format.
  * @public
@@ -46,12 +48,23 @@ class JSONSerialiser {
     const payload = {
       element: element.element
     };
-    if (element._meta && element._meta.length > 0) {
+    if (!element.isMetaEmpty) {
       payload.meta = this.serialiseObject(element.meta);
     }
-    if (element._attributes && element._attributes.length > 0) {
+    if (!element.isAttributesEmpty) {
       payload.attributes = this.serialiseObject(element.attributes);
     }
+
+    // Serialize source position as __mappings__ in meta (skip for SourceMapElement itself)
+    if (!(element instanceof _SourceMap.default)) {
+      const sourceMap = _SourceMap.default.from(element);
+      if (sourceMap) {
+        if (!payload.meta) {
+          payload.meta = {};
+        }
+        payload.meta.__mappings__ = this.serialise(sourceMap);
+      }
+    }
     const content = this.serialiseContent(element.content);
     if (content !== undefined) {
       payload.content = content;
@@ -71,8 +84,26 @@ class JSONSerialiser {
     if (element.element !== value.element) {
       element.element = value.element;
     }
-    if (value.meta) {
-      this.deserialiseObject(value.meta, element.meta);
+
+    // Extract __mappings__ without mutating input, filter remaining meta
+    let mappingsDoc;
+    let metaToDeserialize = value.meta;
+    if (value.meta?.__mappings__) {
+      const {
+        __mappings__,
+        ...rest
+      } = value.meta;
+      mappingsDoc = __mappings__;
+      metaToDeserialize = Object.keys(rest).length > 0 ? rest : undefined;
+    }
+    if (metaToDeserialize) {
+      this.deserialiseObject(metaToDeserialize, element.meta);
+    }
+
+    // Restore source position from __mappings__
+    if (mappingsDoc) {
+      const sourceMap = this.deserialise(mappingsDoc);
+      sourceMap.applyTo(element);
     }
     if (value.attributes) {
       this.deserialiseObject(value.attributes, element.attributes);

package/src/serialisers/JSONSerialiser.mjs

@@ -1,23 +1,20 @@
+import SourceMapElement from "../elements/SourceMap.mjs";
 /**
  * Serialized representation of an Element in JSON Refract format.
  * @public
  */
-
 /**
  * Serialized representation of a KeyValuePair in JSON Refract format.
  * @public
  */
-
 /**
  * Possible content types in a serialized element.
  * @public
  */
-
 /**
  * Input document format for deserialization.
  * @public
  */
-
 /**
  * JSONSerialiser handles serialization and deserialization of ApiDOM elements
  * to and from JSON Refract format.
@@ -42,12 +39,23 @@ class JSONSerialiser {
     const payload = {
       element: element.element
     };
-    if (element._meta && element._meta.length > 0) {
+    if (!element.isMetaEmpty) {
       payload.meta = this.serialiseObject(element.meta);
     }
-    if (element._attributes && element._attributes.length > 0) {
+    if (!element.isAttributesEmpty) {
       payload.attributes = this.serialiseObject(element.attributes);
     }
+
+    // Serialize source position as __mappings__ in meta (skip for SourceMapElement itself)
+    if (!(element instanceof SourceMapElement)) {
+      const sourceMap = SourceMapElement.from(element);
+      if (sourceMap) {
+        if (!payload.meta) {
+          payload.meta = {};
+        }
+        payload.meta.__mappings__ = this.serialise(sourceMap);
+      }
+    }
     const content = this.serialiseContent(element.content);
     if (content !== undefined) {
       payload.content = content;
@@ -67,8 +75,26 @@ class JSONSerialiser {
     if (element.element !== value.element) {
       element.element = value.element;
     }
-    if (value.meta) {
-      this.deserialiseObject(value.meta, element.meta);
+
+    // Extract __mappings__ without mutating input, filter remaining meta
+    let mappingsDoc;
+    let metaToDeserialize = value.meta;
+    if (value.meta?.__mappings__) {
+      const {
+        __mappings__,
+        ...rest
+      } = value.meta;
+      mappingsDoc = __mappings__;
+      metaToDeserialize = Object.keys(rest).length > 0 ? rest : undefined;
+    }
+    if (metaToDeserialize) {
+      this.deserialiseObject(metaToDeserialize, element.meta);
+    }
+
+    // Restore source position from __mappings__
+    if (mappingsDoc) {
+      const sourceMap = this.deserialise(mappingsDoc);
+      sourceMap.applyTo(element);
     }
     if (value.attributes) {
       this.deserialiseObject(value.attributes, element.attributes);