@speclynx/apidom-datamodel 4.0.1 → 4.0.3

package/src/elements/Comment.ts

@@ -0,0 +1,16 @@
+import StringElement from '../primitives/StringElement.ts';
+import type { Meta, Attributes } from '../types.ts';
+
+/**
+ * CommentElement represents a comment in the source document.
+ *
+ * @public
+ */
+class CommentElement extends StringElement {
+  constructor(content?: string, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'comment';
+  }
+}
+
+export default CommentElement;

package/src/elements/LinkElement.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Element = _interopRequireDefault(require("../primitives/Element.cjs"));
+/**
+ * LinkElement represents a hyperlink in ApiDOM.
+ *
+ * Hyperlinking MAY be used to link to other resources, provide links to
+ * instructions on how to process a given element (by way of a profile or
+ * other means), and may be used to provide meta data about the element in
+ * which it's found. The meaning and purpose of the hyperlink is defined by
+ * the link relation according to RFC 5988.
+ *
+ * @public
+ */
+class LinkElement extends _Element.default {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'link';
+  }
+
+  /**
+   * The relation identifier for the link, as defined in RFC 5988.
+   */
+  get relation() {
+    if (this.hasAttributesProperty('relation')) {
+      return this.attributes.get('relation');
+    }
+    return undefined;
+  }
+  set relation(relation) {
+    this.attributes.set('relation', relation);
+  }
+
+  /**
+   * The URI for the given link.
+   */
+  get href() {
+    if (this.hasAttributesProperty('href')) {
+      return this.attributes.get('href');
+    }
+    return undefined;
+  }
+  set href(href) {
+    this.attributes.set('href', href);
+  }
+}
+var _default = exports.default = LinkElement;

package/src/elements/LinkElement.mjs

@@ -0,0 +1,45 @@
+import Element from "../primitives/Element.mjs";
+/**
+ * LinkElement represents a hyperlink in ApiDOM.
+ *
+ * Hyperlinking MAY be used to link to other resources, provide links to
+ * instructions on how to process a given element (by way of a profile or
+ * other means), and may be used to provide meta data about the element in
+ * which it's found. The meaning and purpose of the hyperlink is defined by
+ * the link relation according to RFC 5988.
+ *
+ * @public
+ */
+class LinkElement extends Element {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'link';
+  }
+
+  /**
+   * The relation identifier for the link, as defined in RFC 5988.
+   */
+  get relation() {
+    if (this.hasAttributesProperty('relation')) {
+      return this.attributes.get('relation');
+    }
+    return undefined;
+  }
+  set relation(relation) {
+    this.attributes.set('relation', relation);
+  }
+
+  /**
+   * The URI for the given link.
+   */
+  get href() {
+    if (this.hasAttributesProperty('href')) {
+      return this.attributes.get('href');
+    }
+    return undefined;
+  }
+  set href(href) {
+    this.attributes.set('href', href);
+  }
+}
+export default LinkElement;

package/src/elements/LinkElement.ts

@@ -0,0 +1,49 @@
+import Element, { type Meta, type Attributes } from '../primitives/Element.ts';
+
+/**
+ * LinkElement represents a hyperlink in ApiDOM.
+ *
+ * Hyperlinking MAY be used to link to other resources, provide links to
+ * instructions on how to process a given element (by way of a profile or
+ * other means), and may be used to provide meta data about the element in
+ * which it's found. The meaning and purpose of the hyperlink is defined by
+ * the link relation according to RFC 5988.
+ *
+ * @public
+ */
+class LinkElement extends Element {
+  constructor(content?: unknown, meta?: Meta, attributes?: Attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'link';
+  }
+
+  /**
+   * The relation identifier for the link, as defined in RFC 5988.
+   */
+  get relation(): Element | undefined {
+    if (this.hasAttributesProperty('relation')) {
+      return this.attributes.get('relation');
+    }
+    return undefined;
+  }
+
+  set relation(relation: string | Element | undefined) {
+    this.attributes.set('relation', relation);
+  }
+
+  /**
+   * The URI for the given link.
+   */
+  get href(): Element | undefined {
+    if (this.hasAttributesProperty('href')) {
+      return this.attributes.get('href');
+    }
+    return undefined;
+  }
+
+  set href(href: string | Element | undefined) {
+    this.attributes.set('href', href);
+  }
+}
+
+export default LinkElement;

package/src/elements/ParseResult.cjs

@@ -0,0 +1,91 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ArrayElement = _interopRequireDefault(require("../primitives/ArrayElement.cjs"));
+var _index = require("../predicates/index.cjs");
+/**
+ * ParseResultElement represents the result of parsing a document.
+ *
+ * Contains the parsed API element, any result elements, and annotations
+ * (warnings and errors) from the parsing process.
+ *
+ * @public
+ */
+class ParseResultElement extends _ArrayElement.default {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'parseResult';
+  }
+
+  /**
+   * The main API element from the parse result.
+   */
+  get api() {
+    return this.filter(item => (0, _index.includesClasses)(item, ['api'])).first;
+  }
+
+  /**
+   * All result elements from the parse result.
+   */
+  get results() {
+    return this.filter(item => (0, _index.includesClasses)(item, ['result']));
+  }
+
+  /**
+   * The first result element.
+   */
+  get result() {
+    return this.results.first;
+  }
+
+  /**
+   * All annotation elements (warnings and errors).
+   */
+  get annotations() {
+    return this.filter(item => item.element === 'annotation');
+  }
+
+  /**
+   * All warning annotations.
+   */
+  get warnings() {
+    return this.filter(item => item.element === 'annotation' && (0, _index.includesClasses)(item, ['warning']));
+  }
+
+  /**
+   * All error annotations.
+   */
+  get errors() {
+    return this.filter(item => item.element === 'annotation' && (0, _index.includesClasses)(item, ['error']));
+  }
+
+  /**
+   * Whether the parse result is empty (contains only annotations).
+   */
+  get isEmpty() {
+    return this.reject(item => item.element === 'annotation').length === 0;
+  }
+
+  /**
+   * Replaces the first result element with the given replacement.
+   * @returns true if replacement was successful, false otherwise
+   */
+  replaceResult(replacement) {
+    const {
+      result
+    } = this;
+    if (result === undefined) {
+      return false;
+    }
+    const content = this._content;
+    const searchIndex = content.findIndex(e => e === result);
+    if (searchIndex === -1) {
+      return false;
+    }
+    content[searchIndex] = replacement;
+    return true;
+  }
+}
+var _default = exports.default = ParseResultElement;

package/src/elements/ParseResult.mjs

@@ -0,0 +1,86 @@
+import ArrayElement from "../primitives/ArrayElement.mjs";
+import { includesClasses } from "../predicates/index.mjs";
+/**
+ * ParseResultElement represents the result of parsing a document.
+ *
+ * Contains the parsed API element, any result elements, and annotations
+ * (warnings and errors) from the parsing process.
+ *
+ * @public
+ */
+class ParseResultElement extends ArrayElement {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'parseResult';
+  }
+
+  /**
+   * The main API element from the parse result.
+   */
+  get api() {
+    return this.filter(item => includesClasses(item, ['api'])).first;
+  }
+
+  /**
+   * All result elements from the parse result.
+   */
+  get results() {
+    return this.filter(item => includesClasses(item, ['result']));
+  }
+
+  /**
+   * The first result element.
+   */
+  get result() {
+    return this.results.first;
+  }
+
+  /**
+   * All annotation elements (warnings and errors).
+   */
+  get annotations() {
+    return this.filter(item => item.element === 'annotation');
+  }
+
+  /**
+   * All warning annotations.
+   */
+  get warnings() {
+    return this.filter(item => item.element === 'annotation' && includesClasses(item, ['warning']));
+  }
+
+  /**
+   * All error annotations.
+   */
+  get errors() {
+    return this.filter(item => item.element === 'annotation' && includesClasses(item, ['error']));
+  }
+
+  /**
+   * Whether the parse result is empty (contains only annotations).
+   */
+  get isEmpty() {
+    return this.reject(item => item.element === 'annotation').length === 0;
+  }
+
+  /**
+   * Replaces the first result element with the given replacement.
+   * @returns true if replacement was successful, false otherwise
+   */
+  replaceResult(replacement) {
+    const {
+      result
+    } = this;
+    if (result === undefined) {
+      return false;
+    }
+    const content = this._content;
+    const searchIndex = content.findIndex(e => e === result);
+    if (searchIndex === -1) {
+      return false;
+    }
+    content[searchIndex] = replacement;
+    return true;
+  }
+}
+export default ParseResultElement;

package/src/elements/ParseResult.ts

@@ -0,0 +1,94 @@
+import ArrayElement from '../primitives/ArrayElement.ts';
+import type Element from '../primitives/Element.ts';
+import { includesClasses } from '../predicates/index.ts';
+import type { Meta, Attributes } from '../primitives/Element.ts';
+
+/**
+ * ParseResultElement represents the result of parsing a document.
+ *
+ * Contains the parsed API element, any result elements, and annotations
+ * (warnings and errors) from the parsing process.
+ *
+ * @public
+ */
+class ParseResultElement extends ArrayElement {
+  constructor(content?: unknown[], meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'parseResult';
+  }
+
+  /**
+   * The main API element from the parse result.
+   */
+  get api(): Element | undefined {
+    return this.filter((item) => includesClasses(item, ['api'])).first;
+  }
+
+  /**
+   * All result elements from the parse result.
+   */
+  get results(): ArrayElement {
+    return this.filter((item) => includesClasses(item, ['result']));
+  }
+
+  /**
+   * The first result element.
+   */
+  get result(): Element | undefined {
+    return this.results.first;
+  }
+
+  /**
+   * All annotation elements (warnings and errors).
+   */
+  get annotations(): ArrayElement {
+    return this.filter((item) => item.element === 'annotation');
+  }
+
+  /**
+   * All warning annotations.
+   */
+  get warnings(): ArrayElement {
+    return this.filter(
+      (item) => item.element === 'annotation' && includesClasses(item, ['warning']),
+    );
+  }
+
+  /**
+   * All error annotations.
+   */
+  get errors(): ArrayElement {
+    return this.filter((item) => item.element === 'annotation' && includesClasses(item, ['error']));
+  }
+
+  /**
+   * Whether the parse result is empty (contains only annotations).
+   */
+  override get isEmpty(): boolean {
+    return this.reject((item) => item.element === 'annotation').length === 0;
+  }
+
+  /**
+   * Replaces the first result element with the given replacement.
+   * @returns true if replacement was successful, false otherwise
+   */
+  replaceResult(replacement: Element): boolean {
+    const { result } = this;
+
+    if (result === undefined) {
+      return false;
+    }
+
+    const content = this._content as Element[];
+    const searchIndex = content.findIndex((e) => e === result);
+    if (searchIndex === -1) {
+      return false;
+    }
+
+    content[searchIndex] = replacement;
+
+    return true;
+  }
+}
+
+export default ParseResultElement;

package/src/elements/RefElement.cjs

@@ -0,0 +1,34 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Element = _interopRequireDefault(require("../primitives/Element.cjs"));
+/**
+ * RefElement represents a reference to another element in ApiDOM.
+ * @public
+ */
+class RefElement extends _Element.default {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'ref';
+    if (!this.path) {
+      this.path = 'element';
+    }
+  }
+
+  /**
+   * Path of referenced element to transclude instead of element itself.
+   * @defaultValue 'element'
+   */
+  get path() {
+    if (this.hasAttributesProperty('path')) {
+      return this.attributes.get('path');
+    }
+    return undefined;
+  }
+  set path(newValue) {
+    this.attributes.set('path', newValue);
+  }
+}
+var _default = exports.default = RefElement;

package/src/elements/RefElement.mjs

@@ -0,0 +1,29 @@
+import Element from "../primitives/Element.mjs";
+/**
+ * RefElement represents a reference to another element in ApiDOM.
+ * @public
+ */
+class RefElement extends Element {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'ref';
+    if (!this.path) {
+      this.path = 'element';
+    }
+  }
+
+  /**
+   * Path of referenced element to transclude instead of element itself.
+   * @defaultValue 'element'
+   */
+  get path() {
+    if (this.hasAttributesProperty('path')) {
+      return this.attributes.get('path');
+    }
+    return undefined;
+  }
+  set path(newValue) {
+    this.attributes.set('path', newValue);
+  }
+}
+export default RefElement;

package/src/elements/RefElement.ts

@@ -0,0 +1,33 @@
+import Element, { type Meta, type Attributes } from '../primitives/Element.ts';
+
+/**
+ * RefElement represents a reference to another element in ApiDOM.
+ * @public
+ */
+class RefElement extends Element {
+  constructor(content?: unknown, meta?: Meta, attributes?: Attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'ref';
+
+    if (!this.path) {
+      this.path = 'element';
+    }
+  }
+
+  /**
+   * Path of referenced element to transclude instead of element itself.
+   * @defaultValue 'element'
+   */
+  get path(): Element | undefined {
+    if (this.hasAttributesProperty('path')) {
+      return this.attributes.get('path');
+    }
+    return undefined;
+  }
+
+  set path(newValue: string | Element | undefined) {
+    this.attributes.set('path', newValue);
+  }
+}
+
+export default RefElement;

package/src/elements/SourceMap.cjs

@@ -0,0 +1,140 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _StringElement = _interopRequireDefault(require("../primitives/StringElement.cjs"));
+/**
+ * Shape with optional source position properties.
+ * @public
+ */
+
+/**
+ * SourceMapElement stores source position as a compact VLQ-encoded string.
+ *
+ * The encoded string contains 6 values: startLine, startCharacter, startOffset,
+ * endLine, endCharacter, endOffset. All values use UTF-16 code units,
+ * compatible with LSP, TextDocument, and JavaScript string indexing.
+ *
+ * web-tree-sitter automatically provides position data in UTF-16 code units.
+ *
+ * @public
+ */
+class SourceMapElement extends _StringElement.default {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'sourceMap';
+  }
+
+  /**
+   * Transfers source position properties from one object to another.
+   */
+  static transfer(from, to) {
+    to.startLine = from.startLine;
+    to.startCharacter = from.startCharacter;
+    to.startOffset = from.startOffset;
+    to.endLine = from.endLine;
+    to.endCharacter = from.endCharacter;
+    to.endOffset = from.endOffset;
+  }
+
+  /**
+   * Creates a SourceMapElement from source position properties.
+   * Returns undefined if any position property is not a number.
+   * Also assigns position properties to the instance for inspection.
+   */
+  static from(source) {
+    const {
+      startLine,
+      startCharacter,
+      startOffset,
+      endLine,
+      endCharacter,
+      endOffset
+    } = source;
+    if (typeof startLine !== 'number' || typeof startCharacter !== 'number' || typeof startOffset !== 'number' || typeof endLine !== 'number' || typeof endCharacter !== 'number' || typeof endOffset !== 'number') {
+      return undefined;
+    }
+    const packed = packSourceMap([startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]);
+    const sourceMap = new SourceMapElement(packed);
+    sourceMap.startLine = startLine;
+    sourceMap.startCharacter = startCharacter;
+    sourceMap.startOffset = startOffset;
+    sourceMap.endLine = endLine;
+    sourceMap.endCharacter = endCharacter;
+    sourceMap.endOffset = endOffset;
+    return sourceMap;
+  }
+
+  /**
+   * Decodes the VLQ string and applies source position properties to the target.
+   */
+  applyTo(target) {
+    if (!this.content) return;
+    [target.startLine, target.startCharacter, target.startOffset, target.endLine, target.endCharacter, target.endOffset] = unpackSourceMap(this.content);
+  }
+}
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+// Encode one unsigned integer to Base64-VLQ
+function vlqEncodeInt(value) {
+  let vlq = value >>> 0; // ensure unsigned 32-bit
+  let out = '';
+  do {
+    let digit = vlq & 31; // 5 bits
+    vlq >>>= 5;
+    if (vlq !== 0) digit |= 32; // continuation bit
+    out += BASE64[digit];
+  } while (vlq !== 0);
+  return out;
+}
+
+// Decode one unsigned integer from Base64-VLQ, starting at `index`
+function vlqDecodeInt(str, index = 0) {
+  let result = 0;
+  let shift = 0;
+  let i = index;
+  while (true) {
+    const ch = str[i++];
+    const digit = BASE64.indexOf(ch);
+    if (digit === -1) throw new Error(`Invalid Base64 VLQ char: ${ch}`);
+    const cont = (digit & 32) !== 0;
+    result |= (digit & 31) << shift;
+    shift += 5;
+    if (!cont) break;
+  }
+  return {
+    value: result >>> 0,
+    next: i
+  };
+}
+
+/**
+ * Span of 6 position values: [startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]
+ * @public
+ */
+
+/**
+ * Encodes 6 position values into a compact VLQ string.
+ * @public
+ */
+function packSourceMap(v) {
+  return 'sm1:' + v.map(vlqEncodeInt).join('');
+}
+
+/**
+ * Decodes a VLQ string into 6 position values.
+ * @public
+ */
+function unpackSourceMap(packed) {
+  const s = packed.startsWith('sm1:') ? packed.slice(4) : packed;
+  const out = [];
+  let i = 0;
+  for (let k = 0; k < 6; k++) {
+    const r = vlqDecodeInt(s, i);
+    out.push(r.value);
+    i = r.next;
+  }
+  return out;
+}
+var _default = exports.default = SourceMapElement;