@faubulous/mentor-rdf 2.6.0 → 2.6.1

package/dist/index.js

@@ -480,6 +480,163 @@ var ResourceRepository = class {
     }
     return primary;
   }
+  /**
+   * Get the hierarchy relations of a predicate such as `rdfs:subClassOf`, read in a single pass.
+   * @param graphUris URIs of the graphs to search, `undefined` for the default graph.
+   * @param predicate The hierarchy predicate, e.g. `rdfs:subClassOf` or `rdfs:subPropertyOf`.
+   * @param options Optional query parameters.
+   * @returns A map from a node, named or blank, to its named parents, excluding the node itself.
+   */
+  getParentMap(graphUris, predicate, options) {
+    const result = /* @__PURE__ */ new Map();
+    for (let q of this.store.matchAll(graphUris, null, predicate, null, options?.includeInferred)) {
+      if (q.subject.termType != "NamedNode" && q.subject.termType != "BlankNode" || q.object.termType != "NamedNode" || q.subject.value == q.object.value) {
+        continue;
+      }
+      const parents = result.get(q.subject.value);
+      if (!parents) {
+        result.set(q.subject.value, [q.object.value]);
+      } else if (!parents.includes(q.object.value)) {
+        parents.push(q.object.value);
+      }
+    }
+    return result;
+  }
+  /**
+   * Get the root nodes of a hierarchy such as the class or the property hierarchy. A member with no
+   * visible parent is a root. A parent that is not one of the document's own nodes is referenced:
+   * the roots are then the top nodes of its chains of parents, as far as the graphs state them.
+   * @param members The nodes whose roots are wanted, e.g. the classes of the document.
+   * @param parents The parents of every node, see {@link getParentMap}.
+   * @param isOwn Whether a node belongs to the document; a chain that reaches one has no top of its own.
+   * @param isVisible Whether a parent is shown in the hierarchy at all.
+   * @param canBeRoot Whether a node is listed as a root, be it a member without visible parents or the top of a referenced chain.
+   * @returns An iterator of the root nodes.
+   */
+  *getHierarchyRoots(members, parents, isOwn, isVisible, canBeRoot = () => true) {
+    const yielded = /* @__PURE__ */ new Set();
+    const getVisibleParents = (iri) => (parents.get(iri) ?? []).filter(isVisible);
+    const finished = /* @__PURE__ */ new Set();
+    for (let m of members) {
+      let hasParent = false;
+      for (let p of getVisibleParents(m)) {
+        hasParent = true;
+        if (!isOwn(p)) {
+          for (let r of this._getTopNodes(p, getVisibleParents, isOwn, finished, /* @__PURE__ */ new Set())) {
+            if (!yielded.has(r) && canBeRoot(r)) {
+              yielded.add(r);
+              yield r;
+            }
+          }
+        }
+      }
+      if (!hasParent && !yielded.has(m) && canBeRoot(m)) {
+        yielded.add(m);
+        yield m;
+      }
+    }
+  }
+  /**
+   * Get the top nodes of the chains of parents of a referenced node.
+   * @param iri URI of a referenced node.
+   * @param getParents A function returning the visible parents of a node.
+   * @param isOwn Whether a node belongs to the document; a chain that reaches one has no top of its own.
+   * @param finished The referenced nodes whose top nodes were already yielded.
+   * @param path The nodes on the current chain, to stop at cycles.
+   * @returns An iterator of the top nodes not yielded for another chain before.
+   */
+  *_getTopNodes(iri, getParents, isOwn, finished, path) {
+    if (finished.has(iri)) {
+      return;
+    }
+    path.add(iri);
+    let isTop = true;
+    for (let p of getParents(iri)) {
+      if (isOwn(p) || finished.has(p)) {
+        isTop = false;
+      } else if (!path.has(p)) {
+        isTop = false;
+        yield* this._getTopNodes(p, getParents, isOwn, finished, path);
+      }
+    }
+    path.delete(iri);
+    finished.add(iri);
+    if (isTop) {
+      yield iri;
+    }
+  }
+  /**
+   * Indicate if a node is only referenced by the document: it is included if referenced terms
+   * are included, and it is not defined by another ontology of the document. Annotations or a
+   * declaration of a term from another vocabulary do not define it.
+   * @param graphUris URIs of the graphs to search, `undefined` for the default graph.
+   * @param node A node.
+   * @param options Optional query parameters.
+   * @param ontologies The other ontologies in the graphs, see {@link getOtherOntologiesOnce}.
+   * @returns `true` if the node is a referenced named node, `false` otherwise.
+   */
+  isReferenced(graphUris, node, options, ontologies) {
+    if (!(options?.includeReferenced ?? false) || node.termType != "NamedNode") {
+      return false;
+    }
+    return !ontologies().some((o) => this.isDefinedBy(graphUris, node, o));
+  }
+  /**
+   * Indicate if a node is a referenced term with one of the document's own terms below it in a
+   * hierarchy, so that the hierarchy from a referenced root down to the document is not broken.
+   * @param graphUris URIs of the graphs to search, `undefined` for the default graph.
+   * @param node A node.
+   * @param predicate The hierarchy predicate, e.g. `rdfs:subClassOf` or `rdfs:subPropertyOf`.
+   * @param options Optional query parameters.
+   * @param ontologies The other ontologies in the graphs, see {@link getOtherOntologiesOnce}.
+   * @param visited The nodes already visited, to stop at cycles.
+   * @returns `true` if a term of the document is a direct or indirect child of the node.
+   */
+  isReferencedAbove(graphUris, node, predicate, options, ontologies, visited = /* @__PURE__ */ new Set()) {
+    if (!this.isReferenced(graphUris, node, options, ontologies)) {
+      return false;
+    }
+    visited.add(node.value);
+    for (let q of this.store.matchAll(graphUris, null, predicate, node, options?.includeInferred)) {
+      if (visited.has(q.subject.value)) {
+        continue;
+      }
+      if (!this.skip(graphUris, q.subject, options) || this.isReferencedAbove(graphUris, q.subject, predicate, options, ontologies, visited)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Get an accessor for the other ontologies in the graphs that queries them on its first call
+   * only, as most queries never need them.
+   * @param graphUris URIs of the graphs to search, `undefined` for the default graph.
+   * @param options Optional query parameters.
+   * @returns A function returning the URIs of the other ontologies, see {@link _getOtherOntologies}.
+   */
+  getOtherOntologiesOnce(graphUris, options) {
+    let ontologies;
+    return () => ontologies ?? (ontologies = this._getOtherOntologies(graphUris, options));
+  }
+  /**
+   * Get the ontologies declared in the graphs other than the one the options select with `definedBy`.
+   * @param graphUris URIs of the graphs to search, `undefined` for the default graph.
+   * @param options Optional query parameters.
+   * @returns The URIs of the other ontologies, or none if the options select no ontology.
+   */
+  _getOtherOntologies(graphUris, options) {
+    if (!options?.definedBy) {
+      return [];
+    }
+    const definedBy = Uri.getNormalizedUri(options.definedBy);
+    const result = /* @__PURE__ */ new Set();
+    for (let q of this.store.matchAll(graphUris, null, rdf.type, owl.Ontology, false)) {
+      if (q.subject.termType == "NamedNode" && Uri.getNormalizedUri(q.subject.value) != definedBy) {
+        result.add(q.subject.value);
+      }
+    }
+    return [...result];
+  }
 };
 
 // src/rdf/concept-repository.ts
@@ -1403,8 +1560,9 @@ var ClassRepository = class extends ConceptRepository {
    */
   hasSubClasses(graphUris, subjectUri, options) {
     const o = namedNode2(subjectUri);
+    const ontologies = this.getOtherOntologiesOnce(graphUris, options);
     for (let q of this.store.matchAll(graphUris, null, rdfs.subClassOf, o)) {
-      if (!this.skip(graphUris, q.subject, options)) {
+      if (!this.skip(graphUris, q.subject, options) || this.isReferencedAbove(graphUris, q.subject, rdfs.subClassOf, options, ontologies)) {
         return true;
       }
     }
@@ -1419,8 +1577,12 @@ var ClassRepository = class extends ConceptRepository {
     if (subjectUri) {
       const yielded = /* @__PURE__ */ new Set();
       const o = namedNode2(subjectUri);
+      const ontologies = this.getOtherOntologiesOnce(graphUris, options);
       for (let q of this.store.matchAll(graphUris, null, rdfs.subClassOf, o, options?.includeInferred)) {
-        if (!this.skip(graphUris, q.subject, options) && !yielded.has(q.subject.value)) {
+        if (yielded.has(q.subject.value)) {
+          continue;
+        }
+        if (!this.skip(graphUris, q.subject, options) || this.isReferencedAbove(graphUris, q.subject, rdfs.subClassOf, options, ontologies)) {
           yielded.add(q.subject.value);
           yield q.subject.value;
         }
@@ -1601,28 +1763,23 @@ var ClassRepository = class extends ConceptRepository {
    * @returns An iterator of root classes in the repository.
    */
   *getRootClasses(graphUris, options) {
-    const yielded = /* @__PURE__ */ new Set();
     const classes = new Set(this.getClasses(graphUris, options));
-    for (let c of classes) {
-      let hasSuperClass = false;
-      for (let q of this.store.matchAll(graphUris, namedNode2(c), rdfs.subClassOf, null, options?.includeInferred)) {
-        const includeReferenced = options?.includeReferenced ?? false;
-        const skip = this.skip(graphUris, q.object, options);
-        if (q.object.termType != "NamedNode" || skip && (!includeReferenced || includeReferenced && this.hasSubject(graphUris, q.object.value))) {
-          continue;
-        }
-        hasSuperClass = q.object.value != q.subject.value;
-        if (!classes.has(q.object.value) && !yielded.has(q.object.value)) {
-          yielded.add(q.object.value);
-          yield q.object.value;
-        }
-        break;
+    const ontologies = this.getOtherOntologiesOnce(graphUris, options);
+    const superClasses = this.getParentMap(graphUris, rdfs.subClassOf, options);
+    const visible = /* @__PURE__ */ new Map();
+    const isVisible = (iri) => {
+      if (classes.has(iri)) {
+        return true;
       }
-      if (!hasSuperClass && !yielded.has(c)) {
-        yielded.add(c);
-        yield c;
+      let result = visible.get(iri);
+      if (result === void 0) {
+        const node = namedNode2(iri);
+        result = !this.skip(graphUris, node, options) || this.isReferenced(graphUris, node, options, ontologies);
+        visible.set(iri, result);
       }
-    }
+      return result;
+    };
+    yield* this.getHierarchyRoots(classes, superClasses, (iri) => classes.has(iri), isVisible);
   }
   /**
    * Indicate if there is an equivalent class of a given class.
@@ -1888,38 +2045,41 @@ var PropertyRepository = class extends ClassRepository {
    * @returns An iterator of properties of the given type.
    */
   *getRootPropertiesOfType(graphUris, typeUri, options) {
-    const yielded = /* @__PURE__ */ new Set();
-    const type = namedNode3(typeUri);
-    for (let q of this.store.matchAll(graphUris, null, rdf.type, type, options?.includeInferred)) {
-      if (this.skip(graphUris, q.subject, options)) {
-        continue;
-      }
-      let hasSuperProperty = false;
-      let referencedSuperProperty = null;
-      for (let q2 of this.store.matchAll(graphUris, q.subject, rdfs.subPropertyOf, null, options?.includeInferred)) {
-        if (options?.includeReferenced && !this.hasSubject(graphUris, q2.object.value)) {
-          referencedSuperProperty = q2.object.value;
-        } else if (this.skip(graphUris, q2.object, options)) {
-          continue;
+    const members = /* @__PURE__ */ new Map();
+    for (let q of this.store.matchAll(graphUris, null, rdf.type, namedNode3(typeUri), options?.includeInferred)) {
+      if (!this.skip(graphUris, q.subject, options)) {
+        members.set(q.subject.value, q.subject);
+      }
+    }
+    const ontologies = this.getOtherOntologiesOnce(graphUris, options);
+    const superProperties = this.getParentMap(graphUris, rdfs.subPropertyOf, options);
+    const referenced = /* @__PURE__ */ new Map();
+    const own = /* @__PURE__ */ new Map();
+    const isReferenced = (iri) => {
+      let result = referenced.get(iri);
+      if (result === void 0) {
+        const node = namedNode3(iri);
+        if (!(options?.includeReferenced ?? false)) {
+          result = false;
+        } else if (options?.definedBy) {
+          result = this.skip(graphUris, node, options) && this.isReferenced(graphUris, node, options, ontologies);
+        } else {
+          result = !this.hasSubject(graphUris, iri);
         }
-        hasSuperProperty = q2.object.value != q2.subject.value;
-        break;
+        referenced.set(iri, result);
       }
-      if (referencedSuperProperty && !yielded.has(referencedSuperProperty)) {
-        yielded.add(referencedSuperProperty);
-        yield referencedSuperProperty;
-      }
-      if (hasSuperProperty) {
-        continue;
-      }
-      if (typeUri === RDF.Property && this._hasSpecificType(graphUris, q.subject)) {
-        continue;
-      }
-      if (!yielded.has(q.subject.value)) {
-        yielded.add(q.subject.value);
-        yield q.subject.value;
+      return result;
+    };
+    const isOwn = (iri) => {
+      let result = own.get(iri);
+      if (result === void 0) {
+        result = !isReferenced(iri) && !this.skip(graphUris, namedNode3(iri), options);
+        own.set(iri, result);
       }
-    }
+      return result;
+    };
+    const canBeRoot = (iri) => typeUri !== RDF.Property || !this._hasSpecificType(graphUris, members.get(iri) ?? namedNode3(iri));
+    yield* this.getHierarchyRoots(members.keys(), superProperties, isOwn, (iri) => isOwn(iri) || isReferenced(iri), canBeRoot);
   }
   /**
    * Indicate whether a property is stated to be of a type that is more specific than rdf:Property.
@@ -1999,8 +2159,9 @@ var PropertyRepository = class extends ClassRepository {
    */
   hasSubProperties(graphUris, subjectUri, options) {
     const o = namedNode3(subjectUri);
+    const ontologies = this.getOtherOntologiesOnce(graphUris, options);
     for (let q of this.store.matchAll(graphUris, null, rdfs.subPropertyOf, o, options?.includeInferred)) {
-      if (!this.skip(graphUris, q.subject, options)) {
+      if (!this.skip(graphUris, q.subject, options) || this.isReferencedAbove(graphUris, q.subject, rdfs.subPropertyOf, options, ontologies)) {
         return true;
       }
     }
@@ -2016,8 +2177,9 @@ var PropertyRepository = class extends ClassRepository {
     if (subjectUri) {
       const yielded = /* @__PURE__ */ new Set();
       const o = namedNode3(subjectUri);
+      const ontologies = this.getOtherOntologiesOnce(graphUris, options);
       for (let q of this.store.matchAll(graphUris, null, rdfs.subPropertyOf, o, options?.includeInferred)) {
-        if (this.skip(graphUris, q.subject, options)) {
+        if (this.skip(graphUris, q.subject, options) && !this.isReferencedAbove(graphUris, q.subject, rdfs.subPropertyOf, options, ontologies)) {
           continue;
         }
         if (!yielded.has(q.subject.value)) {
@@ -2035,28 +2197,23 @@ var PropertyRepository = class extends ClassRepository {
    * @returns An iterator of root properties in the repository.
    */
   *getRootProperties(graphUris, options) {
-    const yielded = /* @__PURE__ */ new Set();
     const properties = new Set(this.getProperties(graphUris, options));
-    for (let p of properties) {
-      let hasSuperProperty = false;
-      for (let q of this.store.matchAll(graphUris, namedNode3(p), rdfs.subPropertyOf, null, options?.includeInferred)) {
-        const includeReferenced = options?.includeReferenced ?? false;
-        const skip = this.skip(graphUris, q.object, options);
-        if (q.object.termType != "NamedNode" || skip && (!includeReferenced || includeReferenced && this.hasSubject(graphUris, q.object.value))) {
-          continue;
-        }
-        hasSuperProperty = q.object.value != q.subject.value;
-        if (!properties.has(q.object.value) && !yielded.has(q.object.value)) {
-          yielded.add(q.object.value);
-          yield q.object.value;
-        }
-        break;
+    const ontologies = this.getOtherOntologiesOnce(graphUris, options);
+    const superProperties = this.getParentMap(graphUris, rdfs.subPropertyOf, options);
+    const visible = /* @__PURE__ */ new Map();
+    const isVisible = (iri) => {
+      if (properties.has(iri)) {
+        return true;
       }
-      if (!hasSuperProperty && !yielded.has(p)) {
-        yielded.add(p);
-        yield p;
+      let result = visible.get(iri);
+      if (result === void 0) {
+        const node = namedNode3(iri);
+        result = !this.skip(graphUris, node, options) || this.isReferenced(graphUris, node, options, ontologies);
+        visible.set(iri, result);
       }
-    }
+      return result;
+    };
+    yield* this.getHierarchyRoots(properties, superProperties, (iri) => properties.has(iri), isVisible);
   }
   /**
    * Indicate if there is an equivalent property of a given property.