glossarist 0.3.3 → 0.3.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glossarist",
-  "version": "0.3.3",
-  "description": "JavaScript SDK for Glossarist GCR packages \u2014 read, write, validate, and manage terminology concepts",
+  "version": "0.3.5",
+  "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/concept-collection.js

@@ -5,7 +5,6 @@ const _items = Symbol('items');
 export class ConceptCollection {
   constructor(concepts = []) {
     this[_items] = Array.from(concepts);
-    return new Proxy(this, _handler);
   }
 
   get length() { return this[_items].length; }
@@ -23,10 +22,35 @@ export class ConceptCollection {
   splice(...args) { return this[_items].splice(...args); }
   set(index, item) { this[_items][index] = item; }
 
+  toArray() { return [...this[_items]]; }
+
   byId(id) {
     return this[_items].find(c => c.id === id || c.termid === id);
   }
 
+  /**
+   * Find a concept by id and version.
+   *
+   * The version is matched against a top-level `version` field on
+   * the concept instance (e.g. `concept.version`). The deployment
+   * is responsible for setting this field on bibliographic records;
+   * the data model does not enforce its presence or type.
+   *
+   * If `version` is null, the method falls back to `byId(id)`. This
+   * supports the "version-agnostic" lookup for datasets where
+   * version is not tracked.
+   *
+   * @param {string} id
+   * @param {string | null} version
+   * @returns {Concept | null}
+   */
+  byIdAnd(id, version) {
+    if (version == null) return this.byId(id);
+    return this[_items].find(c =>
+      (c.id === id || c.termid === id) && c.version === version
+    ) ?? null;
+  }
+
   byPrefix(prefix) {
     return new ConceptCollection(this[_items].filter(c => c.id.startsWith(prefix)));
   }
@@ -62,14 +86,22 @@ export class ConceptCollection {
         for (const t of lc.terms) {
           if ((t.designation ?? '').toLowerCase().includes(q)) return true;
         }
-        for (const d of lc.definitions) {
-          if ((d.content ?? '').toLowerCase().includes(q)) return true;
-        }
+        if (this._searchDefs(lc.definitions, q)) return true;
+        if (this._searchDefs(lc.notes, q)) return true;
+        if (this._searchDefs(lc.examples, q)) return true;
+        if (this._searchDefs(lc.annotations, q)) return true;
       }
       return false;
     }));
   }
 
+  _searchDefs(arr, q) {
+    for (const d of arr) {
+      if ((d.content ?? '').toLowerCase().includes(q)) return true;
+    }
+    return false;
+  }
+
   allLanguages() {
     const set = new Set();
     for (const c of this[_items]) {
@@ -82,27 +114,3 @@ export class ConceptCollection {
   slice(...args) { return new ConceptCollection(this[_items].slice(...args)); }
   concat(...args) { return new ConceptCollection(this[_items].concat(...args)); }
 }
-
-const _handler = {
-  get(target, prop, receiver) {
-    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
-      return target[_items][Number(prop)];
-    }
-    if (prop === 'length') return target[_items].length;
-    const value = Reflect.get(target, prop, receiver);
-    return typeof value === 'function' ? value.bind(target) : value;
-  },
-  set(target, prop, value) {
-    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
-      target[_items][Number(prop)] = value;
-      return true;
-    }
-    return Reflect.set(target, prop, value);
-  },
-  has(target, prop) {
-    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
-      return Number(prop) in target[_items];
-    }
-    return Reflect.has(target, prop);
-  },
-};

package/src/concept-parser.js

@@ -1,6 +1,5 @@
 import yaml from 'js-yaml';
 import { Concept } from './models/concept.js';
-import { ConceptRef } from './models/concept-ref.js';
 import { RelatedConcept } from './models/related-concept.js';
 import { InvalidInputError, YamlParseError } from './errors.js';
 
@@ -88,17 +87,13 @@ function _normalizeRelated(arr) {
   if (!arr || !Array.isArray(arr)) return [];
   return arr.map(r => {
     if (r instanceof RelatedConcept) return r;
-    const data = { ...r };
-    if (data.ref) {
-      if (typeof data.ref !== 'object' || data.ref === null) {
-        throw new InvalidInputError(
-          `RelatedConcept.ref must be an object { source, id }, got: ${typeof data.ref}`,
-          'object',
-        );
-      }
-      data.ref = new ConceptRef(data.ref);
+    if (r.ref != null && typeof r.ref !== 'object') {
+      throw new InvalidInputError(
+        `RelatedConcept.ref must be an object { source, id }, got: ${typeof r.ref}`,
+        'object',
+      );
     }
-    return new RelatedConcept(data);
+    return new RelatedConcept(r);
   });
 }
 

package/src/gcr-reader.js

@@ -367,12 +367,42 @@ export class GcrPackage {
     return map;
   }
 
-  /** @private @param {string} filePath @returns {Promise<string | null>} */
-  async _readText(filePath) {
+  /**
+   * Read a text file from the package.
+   * @param {string} filePath
+   * @returns {Promise<string | null>} null if the file doesn't exist
+   */
+  async readText(filePath) {
     const entry = this._zip.file(filePath);
     if (!entry) return null;
     return entry.async('text');
   }
+
+  /**
+   * List all entry paths in the package.
+   * @returns {Array<{ path: string, dir: boolean }>}
+   */
+  entryPaths() {
+    const entries = [];
+    this._zip.forEach((relativePath, entry) => {
+      entries.push({ path: relativePath, dir: !!entry.dir });
+    });
+    return entries;
+  }
+
+  /**
+   * Check whether a specific entry exists in the package.
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  hasEntry(filePath) {
+    return this._zip.file(filePath) != null;
+  }
+
+  /** @private @deprecated Use readText instead */
+  async _readText(filePath) {
+    return this.readText(filePath);
+  }
 }
 
 // --- Concept YAML parsing ---

package/src/index.d.ts

@@ -34,6 +34,16 @@ export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
 // Reference resolution
 export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver';
 
+export type MentionParseResult = {
+  kind: 'cite-ref' | 'numeric' | 'unresolved';
+  key?: string;
+  label?: string | null;
+  id?: string;
+  raw: string;
+};
+
+export function parseMention(raw: string): MentionParseResult;
+
 // V1 support
 export { V1Reader, migrateV1ToV2 } from './v1-reader';
 

package/src/index.js

@@ -8,6 +8,8 @@ export { ManagedConceptCollection } from './managed-concept-collection.js';
 export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index.js';
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid.js';
 export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver.js';
+export { parseMention } from './reference-mention.js';
+export { ReferenceClassifier } from './render-classification.js';
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
 export { GlossaristError, InvalidInputError, YamlParseError } from './errors.js';
 
@@ -32,8 +34,8 @@ export {
   REGISTER_STATUSES, ORDERING_METHODS,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
-  Citation, ConceptRef, ConceptSource, RelatedConcept, ConceptReference, ConceptDate,
+  Citation, ConceptRef, ConceptSource, RelatedConcept, DesignationRelationship, ConceptReference, ConceptDate,
   DetailedDefinition, NonVerbRep,
   GcrMetadata, GcrStatistics,
-  RELATIONSHIP_TYPES, DATE_TYPES,
+  RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index.js';

package/src/models/concept-ref.js

@@ -5,17 +5,24 @@ export class ConceptRef extends GlossaristModel {
     super();
     this.source = data.source ?? null;
     this.id = data.id ?? null;
+    this.text = data.text ?? null;
   }
 
   toString() {
-    if (this.source && this.id) return `${this.source} ${this.id}`;
-    return this.source ?? this.id ?? '';
+    const parts = [];
+    if (this.source) parts.push(this.source);
+    if (this.id) parts.push(this.id);
+    const base = parts.join(' ');
+    if (this.text && base) return `${base} (${this.text})`;
+    if (this.text) return this.text;
+    return base;
   }
 
   toJSON() {
     const obj = {};
     if (this.source != null) obj.source = this.source;
     if (this.id != null) obj.id = this.id;
+    if (this.text != null) obj.text = this.text;
     return obj;
   }
 

package/src/models/concept-source.js

@@ -4,6 +4,7 @@ import { Citation } from './citation.js';
 export class ConceptSource extends GlossaristModel {
   constructor(data = {}) {
     super();
+    this.id = data.id ?? null;
     this.status = data.status ?? null;
     this.type = data.type ?? null;
     this.origin = data.origin
@@ -14,6 +15,7 @@ export class ConceptSource extends GlossaristModel {
 
   toJSON() {
     const obj = {};
+    if (this.id != null) obj.id = this.id;
     if (this.status != null) obj.status = this.status;
     if (this.type != null) obj.type = this.type;
     if (this.origin != null) obj.origin = this.origin.toJSON();

package/src/models/concept.js

@@ -30,6 +30,11 @@ export class Concept extends GlossaristModel {
     return Object.keys(this._rawLocalizations);
   }
 
+  get languageCodes() {
+    return this.languages;
+  }
+
+  /** @deprecated Use localization(lang) for model access, or toJSON().localizations for raw data */
   get localizations() {
     return this._rawLocalizations;
   }
@@ -68,6 +73,45 @@ export class Concept extends GlossaristModel {
     return lang in this._rawLocalizations;
   }
 
+  /**
+   * Find a source by its local id within this concept.
+   *
+   * The lookup walks concept-level, localization-level, and
+   * designation-level sources in that order, returning the first
+   * source whose `id` matches. Sources without an `id` are
+   * skipped. The id is local to the concept; uniqueness is
+   * enforced by the validator (see CiteRefIntegrityRule).
+   *
+   * @param {string} id
+   * @returns {ConceptSource | null}
+   */
+  findSourceById(id) {
+    if (typeof id !== 'string' || id.length === 0) return null;
+
+    // 1. Concept-level sources.
+    for (const source of this.sources) {
+      if (source.id === id) return source;
+    }
+
+    // 2. Localization-level sources.
+    for (const lang of this.languages) {
+      const lc = this.localization(lang);
+      if (!lc) continue;
+      for (const source of lc.sources) {
+        if (source.id === id) return source;
+      }
+
+      // 3. Designation-level sources.
+      for (const designation of lc.terms) {
+        for (const source of designation.sources) {
+          if (source.id === id) return source;
+        }
+      }
+    }
+
+    return null;
+  }
+
   toJSON() {
     const obj = { id: this.id };
     if (this.term != null) obj.term = this.term;

package/src/models/designation-relationship.js

@@ -0,0 +1,27 @@
+import { GlossaristModel } from './base.js';
+
+export const DESIGNATION_RELATIONSHIP_TYPES = Object.freeze([
+  // TBX (ISO 30042) / ISO 12620 term-level relationships
+  'abbreviated_form_for', 'short_form_for',
+]);
+
+export class DesignationRelationship extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.type = data.type ?? null;
+    this.content = data.content ?? null;
+    this.target = data.target ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.type != null) obj.type = this.type;
+    if (this.content != null) obj.content = this.content;
+    if (this.target != null) obj.target = this.target;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new DesignationRelationship(data);
+  }
+}

package/src/models/designation.js

@@ -3,6 +3,7 @@ import { ConceptSource } from './concept-source.js';
 import { Pronunciation } from './pronunciation.js';
 import { GrammarInfo } from './grammar-info.js';
 import { RelatedConcept } from './related-concept.js';
+import { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './designation-relationship.js';
 
 export class Designation extends GlossaristModel {
   static _registry = new Map();
@@ -38,7 +39,11 @@ export class Designation extends GlossaristModel {
       s => s instanceof ConceptSource ? s : new ConceptSource(s)
     );
     this.related = (data.related ?? []).map(
-      r => r instanceof RelatedConcept ? r : new RelatedConcept(r)
+      r => (r instanceof DesignationRelationship || r instanceof RelatedConcept)
+        ? r
+        : DESIGNATION_RELATIONSHIP_TYPES.includes(r.type)
+          ? DesignationRelationship.fromJSON(r)
+          : RelatedConcept.fromJSON(r)
     );
   }
 

package/src/models/index.d.ts

@@ -88,6 +88,7 @@ export class LocalizedConcept extends GlossaristModel {
   readonly definitions: DetailedDefinition[];
   readonly definition: DetailedDefinition[];
   readonly notes: DetailedDefinition[];
+  readonly annotations: DetailedDefinition[];
   readonly examples: DetailedDefinition[];
   readonly sources: ConceptSource[];
   readonly dates: ConceptDate[];
@@ -113,7 +114,7 @@ export class Designation extends GlossaristModel {
   readonly termType: string | null;
   readonly pronunciations: Pronunciation[];
   readonly sources: ConceptSource[];
-  readonly related: RelatedConcept[];
+  readonly related: (RelatedConcept | DesignationRelationship)[];
   static register(type: string, cls: typeof Designation): void;
   static fromData(data: Record<string, unknown>): Designation;
   static fromJSON(data: Record<string, unknown>): Designation;
@@ -194,6 +195,7 @@ export namespace Citation {
 export class ConceptRef extends GlossaristModel {
   readonly source: string | null;
   readonly id: string | null;
+  readonly text: string | null;
   toString(): string;
   static fromJSON(data: Record<string, unknown>): ConceptRef;
 }
@@ -212,6 +214,14 @@ export class RelatedConcept extends GlossaristModel {
   readonly ref: ConceptRef | null;
 }
 
+export const DESIGNATION_RELATIONSHIP_TYPES: readonly string[];
+export class DesignationRelationship extends GlossaristModel {
+  readonly type: string | null;
+  readonly content: string | null;
+  readonly target: string | null;
+  static fromJSON(data: Record<string, unknown>): DesignationRelationship;
+}
+
 export class ConceptReference extends GlossaristModel {
   readonly conceptId: string | null;
   readonly refType: string | null;

package/src/models/index.js

@@ -8,6 +8,7 @@ export { Citation } from './citation.js';
 export { ConceptRef } from './concept-ref.js';
 export { ConceptSource } from './concept-source.js';
 export { RelatedConcept, RELATIONSHIP_TYPES } from './related-concept.js';
+export { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './designation-relationship.js';
 export { ConceptReference } from './concept-reference.js';
 export { ConceptDate, DATE_TYPES } from './concept-date.js';
 export { DetailedDefinition } from './detailed-definition.js';

package/src/models/localized-concept.js

@@ -6,6 +6,10 @@ import { ConceptDate } from './concept-date.js';
 import { NonVerbRep } from './non-verb-rep.js';
 import { RelatedConcept } from './related-concept.js';
 
+function wrapAs(Cls) {
+  return item => item instanceof Cls ? item : new Cls(item);
+}
+
 export class LocalizedConcept extends GlossaristModel {
   constructor(data = {}) {
     super();
@@ -30,6 +34,7 @@ export class LocalizedConcept extends GlossaristModel {
     this._rawDefinition = data.definition ?? [];
     this._rawSources = data.sources ?? [];
     this._rawNotes = data.notes ?? [];
+    this._rawAnnotations = data.annotations ?? [];
     this._rawExamples = data.examples ?? [];
     this._rawDates = data.dates ?? [];
     this._rawNonVerbal = data.non_verbal_rep ?? data.non_verb ?? [];
@@ -39,6 +44,7 @@ export class LocalizedConcept extends GlossaristModel {
     this._definitions = null;
     this._sources = null;
     this._notes = null;
+    this._annotations = null;
     this._examples = null;
     this._dates = null;
     this._nonVerbal = null;
@@ -46,19 +52,11 @@ export class LocalizedConcept extends GlossaristModel {
   }
 
   get terms() {
-    if (this._terms === null) {
-      this._terms = this._rawTerms.map(t => Designation.fromData(t));
-    }
-    return this._terms;
+    return this._lazy('_terms', '_rawTerms', t => Designation.fromData(t));
   }
 
   get definitions() {
-    if (this._definitions === null) {
-      this._definitions = this._rawDefinition.map(
-        d => d instanceof DetailedDefinition ? d : new DetailedDefinition(d)
-      );
-    }
-    return this._definitions;
+    return this._lazy('_definitions', '_rawDefinition', wrapAs(DetailedDefinition));
   }
 
   get definition() {
@@ -66,57 +64,31 @@ export class LocalizedConcept extends GlossaristModel {
   }
 
   get sources() {
-    if (this._sources === null) {
-      this._sources = this._rawSources.map(
-        s => s instanceof ConceptSource ? s : new ConceptSource(s)
-      );
-    }
-    return this._sources;
+    return this._lazy('_sources', '_rawSources', wrapAs(ConceptSource));
   }
 
   get notes() {
-    if (this._notes === null) {
-      this._notes = this._rawNotes.map(
-        n => n instanceof DetailedDefinition ? n : new DetailedDefinition(n)
-      );
-    }
-    return this._notes;
+    return this._lazy('_notes', '_rawNotes', wrapAs(DetailedDefinition));
+  }
+
+  get annotations() {
+    return this._lazy('_annotations', '_rawAnnotations', wrapAs(DetailedDefinition));
   }
 
   get examples() {
-    if (this._examples === null) {
-      this._examples = this._rawExamples.map(
-        e => e instanceof DetailedDefinition ? e : new DetailedDefinition(e)
-      );
-    }
-    return this._examples;
+    return this._lazy('_examples', '_rawExamples', wrapAs(DetailedDefinition));
   }
 
   get dates() {
-    if (this._dates === null) {
-      this._dates = this._rawDates.map(
-        d => d instanceof ConceptDate ? d : new ConceptDate(d)
-      );
-    }
-    return this._dates;
+    return this._lazy('_dates', '_rawDates', wrapAs(ConceptDate));
   }
 
   get nonVerbalRep() {
-    if (this._nonVerbal === null) {
-      this._nonVerbal = this._rawNonVerbal.map(
-        n => n instanceof NonVerbRep ? n : new NonVerbRep(n)
-      );
-    }
-    return this._nonVerbal;
+    return this._lazy('_nonVerbal', '_rawNonVerbal', wrapAs(NonVerbRep));
   }
 
   get related() {
-    if (this._related === null) {
-      this._related = this._rawRelated.map(
-        r => r instanceof RelatedConcept ? r : new RelatedConcept(r)
-      );
-    }
-    return this._related;
+    return this._lazy('_related', '_rawRelated', wrapAs(RelatedConcept));
   }
 
   get primaryDesignation() {
@@ -146,47 +118,31 @@ export class LocalizedConcept extends GlossaristModel {
     if (this.reviewDecision) obj.review_decision = this.reviewDecision;
     if (this.reviewDecisionNotes) obj.review_decision_notes = this.reviewDecisionNotes;
 
-    const terms = this._terms ?? this._rawTerms;
-    if (terms.length > 0) {
-      obj.terms = terms.map(t => (typeof t.toJSON === 'function') ? t.toJSON() : t);
-    }
+    this._serialize(obj, 'terms', '_terms', '_rawTerms');
+    this._serialize(obj, 'definition', '_definitions', '_rawDefinition');
+    this._serialize(obj, 'notes', '_notes', '_rawNotes');
+    this._serialize(obj, 'annotations', '_annotations', '_rawAnnotations');
+    this._serialize(obj, 'examples', '_examples', '_rawExamples');
+    this._serialize(obj, 'sources', '_sources', '_rawSources');
+    this._serialize(obj, 'dates', '_dates', '_rawDates');
+    this._serialize(obj, 'non_verbal_rep', '_nonVerbal', '_rawNonVerbal');
+    this._serialize(obj, 'related', '_related', '_rawRelated');
 
-    const defs = this._definitions ?? (this._rawDefinition.length > 0 ? this._rawDefinition : []);
-    if (defs.length > 0) {
-      obj.definition = defs.map(d => (typeof d.toJSON === 'function') ? d.toJSON() : d);
-    }
-
-    const notes = this._notes ?? (this._rawNotes.length > 0 ? this._rawNotes : []);
-    if (notes.length > 0) {
-      obj.notes = notes.map(n => (typeof n.toJSON === 'function') ? n.toJSON() : n);
-    }
-
-    const examples = this._examples ?? (this._rawExamples.length > 0 ? this._rawExamples : []);
-    if (examples.length > 0) {
-      obj.examples = examples.map(e => (typeof e.toJSON === 'function') ? e.toJSON() : e);
-    }
-
-    const sources = this._sources ?? (this._rawSources.length > 0 ? this._rawSources : []);
-    if (sources.length > 0) {
-      obj.sources = sources.map(s => (typeof s.toJSON === 'function') ? s.toJSON() : s);
-    }
-
-    const dates = this._dates ?? (this._rawDates.length > 0 ? this._rawDates : []);
-    if (dates.length > 0) {
-      obj.dates = dates.map(d => (typeof d.toJSON === 'function') ? d.toJSON() : d);
-    }
+    return obj;
+  }
 
-    const nonVerbal = this._nonVerbal ?? (this._rawNonVerbal.length > 0 ? this._rawNonVerbal : []);
-    if (nonVerbal.length > 0) {
-      obj.non_verbal_rep = nonVerbal.map(n => (typeof n.toJSON === 'function') ? n.toJSON() : n);
+  _lazy(cacheKey, rawKey, wrapFn) {
+    if (this[cacheKey] === null) {
+      this[cacheKey] = this[rawKey].map(wrapFn);
     }
+    return this[cacheKey];
+  }
 
-    const related = this._related ?? (this._rawRelated.length > 0 ? this._rawRelated : []);
-    if (related.length > 0) {
-      obj.related = related.map(r => (typeof r.toJSON === 'function') ? r.toJSON() : r);
+  _serialize(obj, jsonKey, cacheKey, rawKey) {
+    const items = this[cacheKey] ?? (this[rawKey].length > 0 ? this[rawKey] : []);
+    if (items.length > 0) {
+      obj[jsonKey] = items.map(i => (typeof i.toJSON === 'function') ? i.toJSON() : i);
     }
-
-    return obj;
   }
 
   static fromJSON(data) {

package/src/models/related-concept.js

@@ -31,8 +31,6 @@ export const RELATIONSHIP_TYPES = Object.freeze([
   'sequentially_related_concept', 'spatially_related_concept', 'temporally_related_concept',
   // Lexical (ISO 12620 / TBX)
   'homograph', 'false_friend',
-  // Designation-level
-  'abbreviated_form_for', 'short_form_for',
 ]);
 
 export class RelatedConcept extends GlossaristModel {