glossarist 0.4.18 → 0.4.20

package/data/concept-model/shapes/glossarist.shacl.ttl

@@ -43,13 +43,17 @@ gloss:ConceptShape a sh:NodeShape ;
   sh:property [
     sh:path gloss:hasStatus ;
     sh:class skos:Concept ;
-    sh:valuesFrom <https://www.glossarist.org/ontologies/conceptstatus> ;
+    sh:valuesFrom <https://www.glossarist.org/ontologies/status> ;
     sh:maxCount 1 ;
   ] ;
   sh:property [
     sh:path gloss:hasRelatedConcept ;
     sh:class gloss:RelatedConcept ;
   ] ;
+  sh:property [
+    sh:path gloss:hasPartitiveHyperedge ;
+    sh:class gloss:PartitiveHyperedge ;
+  ] ;
   sh:property [
     sh:path gloss:hasDate ;
     sh:class gloss:ConceptDate ;
@@ -717,6 +721,152 @@ gloss:RelatedConceptShape a sh:NodeShape ;
     sh:maxCount 1 ;
   ] .
 
+# ══════════════════════════════════════════════════════════════════════════
+# Partitive Hyperedge shapes
+# ══════════════════════════════════════════════════════════════════════════
+
+gloss:PartitiveHyperedgeShape a sh:NodeShape ;
+  sh:targetClass gloss:PartitiveHyperedge ;
+  sh:property [
+    sh:path gloss:comprehensive ;
+    sh:class gloss:ConceptRef ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:hasPart ;
+    sh:class gloss:ConceptRef ;
+    sh:minCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:enumeration ;
+    sh:class skos:Concept ;
+    sh:valuesFrom <https://www.glossarist.org/ontologies/partitiveEnumeration> ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:hasPluralityMarker ;
+    sh:class skos:Concept ;
+    sh:valuesFrom <https://www.glossarist.org/ontologies/pluralityMarker> ;
+  ] ;
+  sh:property [
+    sh:path gloss:hyperedgeContent ;
+    sh:datatype xsd:string ;
+    sh:maxCount 1 ;
+  ] .
+
+# Ownership invariant — soft (warning severity). A PartitiveHyperedge
+# is *conventionally* carried by its comprehensive's own concept entry:
+#   <concept/X> gloss:hasPartitiveHyperedge [
+#     gloss:comprehensive [ a gloss:ConceptRef ; gloss:ref-id "X" ]
+#   ] .
+#
+# Datasets in the wild may legitimately cross-reference (a concept
+# carries a hyperedge whose comprehensive points elsewhere — e.g. for
+# indexing). We do not forbid this; we warn so reviewers can confirm
+# the cross-reference is intentional.
+#
+# The SPARQL constraint matches when the carrying concept's URI-ending
+# identifier differs from the comprehensive ConceptRef's `gloss:id`
+# literal.
+gloss:PartitiveHyperedgeOwnershipShape a sh:NodeShape ;
+  sh:targetClass gloss:PartitiveHyperedge ;
+  sh:severity sh:Warning ;
+  sh:message "partitive_hyperedge is carried by a concept that is not its comprehensive — confirm the cross-reference is intentional."@en ;
+  sh:sparql [
+    a sh:SPARQLConstraint ;
+    sh:prefixes [
+      sh:declare [
+        sh:prefix "gloss" ;
+        sh:namespace "https://www.glossarist.org/ontologies/"^^xsd:anyURI ;
+      ] ;
+      sh:declare [
+        sh:prefix "xsd" ;
+        sh:namespace "http://www.w3.org/2001/XMLSchema#"^^xsd:anyURI ;
+      ] ;
+    ] ;
+    sh:select """
+      SELECT $this ?carryingConcept ?compRef
+      WHERE {
+        ?carryingConcept gloss:hasPartitiveHyperedge $this .
+        $this gloss:comprehensive ?compRef .
+        # Two encoding shapes exist:
+        #   (a) ?compRef is a gloss:ConceptRef node with gloss:conceptRefId
+        #   (b) ?compRef is a direct URI ending in /<concept_id>
+        # We bind ?compKey to whichever form is present, then compare
+        # against the URI suffix of the carrying concept.
+        OPTIONAL { ?compRef gloss:conceptRefId ?literalId . }
+        BIND(COALESCE(?literalId, STRAFTER(STR(?compRef), CONCAT(STR(?carryingConcept), "/"))) AS ?compKey)
+        FILTER (BOUND(?compKey) && !STRENDS(STR(?carryingConcept), CONCAT("/", ?compKey)))
+      }
+    """ ;
+  ] .
+
+# ── Enum scheme shapes ───────────────────────────────────────────────────
+# PartitiveEnumeration and PluralityMarker are modelled as owl:Class
+# but functionally are SKOS ConceptSchemes. The shape asserts the
+# scheme contract: every instance must be a skos:ConceptScheme.
+
+gloss:PartitiveEnumerationShape a sh:NodeShape ;
+  sh:targetClass gloss:PartitiveEnumeration ;
+  sh:class skos:ConceptScheme .
+
+gloss:PluralityMarkerShape a sh:NodeShape ;
+  sh:targetClass gloss:PluralityMarker ;
+  sh:class skos:ConceptScheme .
+
+# ── Non-verbal entity hierarchy ──────────────────────────────────────────
+# Abstract base + shared dataset-wide entity. Concrete shapes
+# (Figure, Table, Formula) live elsewhere in this file.
+
+gloss:NonVerbalEntityShape a sh:NodeShape ;
+  sh:targetClass gloss:NonVerbalEntity ;
+  sh:property [
+    sh:path gloss:caption ;
+    sh:datatype xsd:string ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:altText ;
+    sh:datatype xsd:string ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:description ;
+    sh:datatype xsd:string ;
+  ] ;
+  sh:property [
+    sh:path gloss:hasSource ;
+    sh:class gloss:ConceptSource ;
+  ] .
+
+gloss:SharedNonVerbalEntityShape a sh:NodeShape ;
+  sh:targetClass gloss:SharedNonVerbalEntity ;
+  sh:class gloss:NonVerbalEntity ;
+  sh:property [
+    sh:path gloss:role ;
+    sh:datatype xsd:string ;
+    sh:maxCount 1 ;
+  ] .
+
+gloss:FigureImageShape a sh:NodeShape ;
+  sh:targetClass gloss:FigureImage ;
+  sh:property [
+    sh:path gloss:src ;
+    sh:datatype xsd:string ;
+    sh:minCount 1 ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:format ;
+    sh:datatype xsd:string ;
+    sh:maxCount 1 ;
+  ] ;
+  sh:property [
+    sh:path gloss:hasSubfigure ;
+    sh:class gloss:FigureImage ;
+  ] .
+
 gloss:GrammarInfoShape a sh:NodeShape ;
   sh:targetClass gloss:GrammarInfo ;
   sh:property [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/concept-diff.js

@@ -1,3 +1,15 @@
+/**
+ * @deprecated Import from `glossarist/diff` (i.e. `src/diff/index.js`)
+ * instead. This file is a backwards-compatibility shim left over from
+ * the pre-`eb6e61c` layout. It will be removed in the next major
+ * release.
+ *
+ * Migration:
+ *   - `import { diffConcepts } from 'glossarist/concept-diff'`
+ *   + `import { diffConcepts } from 'glossarist/diff'`
+ *
+ * See TODO.hyperedges-v2/12 for the deprecation rationale.
+ */
 export {
   diffConcepts,
   diffLocalizedConcepts,
@@ -16,4 +28,5 @@ export {
   Added,
   Removed,
   Changed,
+  Matched,
 } from './diff/index.js';

package/src/concept-parser.js

@@ -1,9 +1,18 @@
 import * as yaml from 'js-yaml';
 import { Concept } from './models/concept.js';
 import { RelatedConcept } from './models/related-concept.js';
+import { migrateHyperedgeToRelation } from './migration/partitive-relation-migrator.js';
 import { InvalidInputError, YamlParseError } from './errors.js';
 
-const STRUCTURAL_KEYS = new Set(['termid', 'term', 'figures', 'tables', 'formulas']);
+// Structural keys are reserved at the concept level and excluded
+// from language localization discovery. Updated for v2:
+// `partitive_relations` is the v2 wire name; `partitive_hyperedges`
+// is accepted as v1 backward-compat input.
+const STRUCTURAL_KEYS = new Set([
+  'termid', 'term', 'figures', 'tables', 'formulas',
+  'partitive_hyperedges', 'partitiveHyperedges',
+  'partitive_relations', 'partitiveRelations',
+]);
 
 export class ConceptParser {
   parse(raw, context) {
@@ -58,6 +67,7 @@ export class ConceptParser {
       figures: doc.figures,
       tables: doc.tables,
       formulas: doc.formulas,
+      partitiveRelations: _resolvePartitiveData(doc),
       raw: doc,
     });
   }
@@ -74,11 +84,14 @@ export class ConceptParser {
       localizations[lang] = lcData;
     }
 
+    assertConceptLevelOnly(mc, ['related', 'partitive_relations', 'partitive_hyperedges']);
+
     return new Concept({
       id: String(mc.data.identifier),
       term: null,
       localizations,
-      related: _normalizeRelated(mc.related ?? mc.data?.related),
+      related: _normalizeRelated(mc.related),
+      partitiveRelations: _resolvePartitiveData(mc),
       domains: mc.data.domains,
       groups: mc.data.groups,
       dates: mc.dates ?? mc.data?.dates,
@@ -93,6 +106,43 @@ export class ConceptParser {
   }
 }
 
+function assertConceptLevelOnly(mc, keys) {
+  const conceptId = mc?.data?.identifier ?? '<unknown>';
+  for (const key of keys) {
+    const camelKey = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    if (mc?.data?.[key] != null && mc[key] == null && mc[camelKey] == null) {
+      throw new InvalidInputError(
+        `'${key}' must live at concept level (top-level of the managed ` +
+        `concept document), not under data:. Found data.${key} in concept ` +
+        `${conceptId}. Move the key out of the data: block.`,
+        'concept-level ' + key,
+      );
+    }
+  }
+}
+
+// Resolves partitive relation data from any of three input shapes:
+//   v2 wire:    { partitive_relations: [...] }
+//   v2 camel:   { partitiveRelations: [...] }
+//   v1 wire:    { partitive_hyperedges: [...] }   ← migrated to v2
+//   v1 camel:   { partitiveHyperedges: [...] }    ← migrated to v2
+//
+// Returns null when no partitive data is present, so Concept's
+// `_resolvePartitiveRelations` falls back to the empty-array default.
+function _resolvePartitiveData(container) {
+  const v2 = container?.partitive_relations ?? container?.partitiveRelations;
+  if (Array.isArray(v2)) return v2;
+
+  const v1 = container?.partitive_hyperedges ?? container?.partitiveHyperedges;
+  if (Array.isArray(v1)) {
+    return v1
+      .map(h => (h?.toJSON && typeof h.toJSON === 'function') ? h.toJSON() : h)
+      .map(migrateHyperedgeToRelation)
+      .filter(h => h != null);
+  }
+  return null;
+}
+
 function _normalizeRelated(arr) {
   if (!arr || !Array.isArray(arr)) return [];
   return arr.map(r => {

package/src/concept-serializer.js

@@ -7,6 +7,13 @@ export class ConceptSerializer {
     const doc = { termid: concept.id };
     if (concept.term) doc.term = concept.term;
 
+    // v2: emit partitive_relations (was partitive_hyperedges in v1).
+    // Concept.partitiveRelations is the canonical v2 property; the
+    // v1 alias `partitiveHyperedges` points at the same array.
+    if (concept.partitiveRelations && concept.partitiveRelations.length > 0) {
+      doc.partitive_relations = concept.partitiveRelations.map(r => r.toJSON());
+    }
+
     for (const lang of concept.languages) {
       const lc = concept.localization(lang);
       if (lc) {
@@ -46,6 +53,10 @@ export class ConceptSerializer {
     if (concept.relatedConcepts.length > 0) {
       mainDoc.related = concept.relatedConcepts.map(rc => rc.toJSON());
     }
+    // v2 wire name. Concept loads both v1 and v2 input but emits only v2.
+    if (concept.partitiveRelations && concept.partitiveRelations.length > 0) {
+      mainDoc.partitive_relations = concept.partitiveRelations.map(r => r.toJSON());
+    }
     if (concept.sources.length > 0) {
       mainDoc.sources = concept.sources.map(s => s.toJSON());
     }

package/src/diff/canonical-json.js

@@ -0,0 +1,31 @@
+// Canonical JSON for equality comparison.
+//
+// Sorts object keys recursively so two semantically-equal values produce
+// identical strings regardless of insertion order. Arrays preserve order
+// (they're ordered in domain semantics). Undefined values are dropped.
+//
+// Used by the diff layer to compare items whose `toJSON()` may emit keys
+// in different orders depending on conditional inclusion (e.g.,
+// PartitiveHyperedge#toJSON omits `markers` when empty).
+
+export function canonicalJson(value) {
+  return JSON.stringify(toCanonical(value));
+}
+
+export function deepEqualCanonical(a, b) {
+  return canonicalJson(a) === canonicalJson(b);
+}
+
+function toCanonical(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return value.map(toCanonical);
+  if (typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) {
+      const v = toCanonical(value[k]);
+      if (v !== undefined) out[k] = v;
+    }
+    return out;
+  }
+  return value;
+}

package/src/diff/change.js

@@ -4,6 +4,7 @@ import { TextDiff } from './text-diff.js';
 export const CHANGE_ADDED = 'added';
 export const CHANGE_REMOVED = 'removed';
 export const CHANGE_CHANGED = 'changed';
+export const CHANGE_MATCHED = 'matched';
 
 function serializeValue(v) {
   if (v == null) return null;
@@ -100,11 +101,38 @@ export class Changed extends Change {
   }
 }
 
+// Matched is for set-membership records that exist in both sides of a
+// comparison but have no directionality — used by ConceptCollectionDiff
+// to track which concepts were paired by id, distinct from those that
+// were genuinely Added or Removed. Distinct from Added because the data
+// has a different semantic meaning; conflating them caused type drift
+// in round 1 (TODO.hyperedges-v2/08).
+export class Matched extends Change {
+  constructor(data = {}) {
+    super(data);
+    this.value = data.value ?? null;
+  }
+
+  get type() { return CHANGE_MATCHED; }
+
+  toJSON() {
+    const obj = { type: CHANGE_MATCHED };
+    if (this.path != null) obj.path = this.path;
+    obj.value = serializeValue(this.value);
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new Matched(data);
+  }
+}
+
 export function deserializeChange(data) {
   switch (data?.type) {
     case CHANGE_ADDED: return Added.fromJSON(data);
     case CHANGE_REMOVED: return Removed.fromJSON(data);
     case CHANGE_CHANGED: return Changed.fromJSON(data);
+    case CHANGE_MATCHED: return Matched.fromJSON(data);
     default:
       throw new Error(`Unknown change type: ${data?.type}`);
   }

package/src/diff/collection-diff.js

@@ -1,6 +1,7 @@
 import { GlossaristModel } from '../models/base.js';
-import { Added, Removed } from './change.js';
+import { Added, Removed, Matched, deserializeChange } from './change.js';
 import { ConceptDiff, DiffStats, diffConcepts } from './concept-diff.js';
+import { averageSimilarity } from './similarity.js';
 
 export class ConceptCollectionDiff extends GlossaristModel {
   constructor(data = {}) {
@@ -8,9 +9,9 @@ export class ConceptCollectionDiff extends GlossaristModel {
     this.oldCount = data.oldCount ?? data.old_count ?? 0;
     this.newCount = data.newCount ?? data.new_count ?? 0;
 
-    this._matched = wrapIdList(data.matched);
-    this._added = wrapIdList(data.added);
-    this._removed = wrapIdList(data.removed);
+    this._matched = wrapIdList(data.matched, Matched);
+    this._added = wrapIdList(data.added, Added);
+    this._removed = wrapIdList(data.removed, Removed);
 
     this._conceptDiffs = {};
     const raw = data.conceptDiffs ?? data.concept_diffs ?? {};
@@ -19,6 +20,8 @@ export class ConceptCollectionDiff extends GlossaristModel {
         ? diff
         : ConceptDiff.fromJSON(diff);
     }
+    this._statsCache = undefined;
+    this._similarityCache = undefined;
   }
 
   get matched() { return this._matched; }
@@ -41,29 +44,35 @@ export class ConceptCollectionDiff extends GlossaristModel {
   }
 
   get stats() {
-    let added = this._added.length;
-    let removed = this._removed.length;
-    let changed = 0;
-    for (const diff of Object.values(this._conceptDiffs)) {
-      const s = diff.stats;
-      added += s.added;
-      removed += s.removed;
-      changed += s.changed;
+    if (this._statsCache === undefined) {
+      let added = this._added.length;
+      let removed = this._removed.length;
+      let changed = 0;
+      for (const diff of Object.values(this._conceptDiffs)) {
+        const s = diff.stats;
+        added += s.added;
+        removed += s.removed;
+        changed += s.changed;
+      }
+      this._statsCache = new DiffStats({ added, removed, changed });
     }
-    return new DiffStats({ added, removed, changed });
+    return this._statsCache;
   }
 
   get similarity() {
-    if (this._matched.length === 0) return 0;
-    let sum = 0;
-    let n = 0;
-    for (const entry of this._matched) {
-      const id = entry.value;
-      const diff = this._conceptDiffs[id];
-      sum += diff ? diff.similarity : 1.0;
-      n++;
+    if (this._similarityCache === undefined) {
+      if (this._matched.length === 0) {
+        this._similarityCache = 0;
+      } else {
+        const values = this._matched.map(entry => {
+          const id = entry.value;
+          const diff = this._conceptDiffs[id];
+          return diff ? diff.similarity : 1.0;
+        });
+        this._similarityCache = averageSimilarity(values);
+      }
     }
-    return n > 0 ? Math.round((sum / n) * 10000) / 10000 : 1.0;
+    return this._similarityCache;
   }
 
   *walk() {
@@ -134,7 +143,7 @@ export function diffConceptCollections(oldCollection, newCollection, options = {
   return new ConceptCollectionDiff({
     oldCount: oldConcepts.length,
     newCount: newConcepts.length,
-    matched: matchedIds.map(id => new Added({ value: id })),
+    matched: matchedIds.map(id => new Matched({ value: id })),
     added: addedIds.map(id => new Added({ value: id })),
     removed: removedIds.map(id => new Removed({ value: id })),
     conceptDiffs,
@@ -158,7 +167,30 @@ function conceptsEqual(a, b) {
   return JSON.stringify(a?.toJSON?.()) === JSON.stringify(b?.toJSON?.());
 }
 
-function wrapIdList(data) {
+// `wrapIdList` deserializes each entry via deserializeChange, which
+// dispatches on `type`. The `expectedClass` parameter is a defensive
+// check: if the entry's deserialized type doesn't match the slot it's
+// being loaded into, throw. Prevents the round-1 bug where removed
+// entries silently became Added after a JSON round-trip.
+function wrapIdList(data, expectedClass) {
   if (!data) return [];
-  return data.map(c => c instanceof Added || c instanceof Removed ? c : Added.fromJSON(c));
+  return data.map(c => {
+    if (c instanceof Added || c instanceof Removed || c instanceof Matched) {
+      if (!(c instanceof expectedClass)) {
+        throw new Error(
+          `ConceptCollectionDiff: entry type ${c.constructor.name} ` +
+          `does not match slot ${expectedClass.name}`,
+        );
+      }
+      return c;
+    }
+    const deserialized = deserializeChange(c);
+    if (!(deserialized instanceof expectedClass)) {
+      throw new Error(
+        `ConceptCollectionDiff: deserialized entry type ` +
+        `${deserialized.constructor.name} does not match slot ${expectedClass.name}`,
+      );
+    }
+    return deserialized;
+  });
 }