glossarist 0.3.4 → 0.3.6

package/package.json

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

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)));
   }
@@ -90,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/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' | 'designation' | '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';
 

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/reference-mention.js

@@ -0,0 +1,82 @@
+/**
+ * Mention parser for {{...}} inline references in concept text.
+ *
+ * Pure function: takes a raw mention body (the text inside
+ * {{...}}) and returns a structured MentionParseResult.
+ *
+ * Convention: the ID always comes first, the display (render) text
+ * always comes last.  Every comma-separated form follows this:
+ *
+ *   {{id}}                        bare ID
+ *   {{id, display text}}          ID + display text
+ *   {{cite:key}}                  cite-key (source id)
+ *   {{cite:key, display text}}    cite-key + display text
+ *
+ * @typedef {Object} MentionParseResult
+ * @property {'cite-ref' | 'numeric' | 'designation' | 'unresolved'} kind
+ * @property {string} [key]   — for 'cite-ref': the local key
+ * @property {string} [label] — display text (always last)
+ * @property {string} [id]    — for 'numeric' / 'designation': the id
+ * @property {string} raw     — the original mention body
+ */
+
+const NUMERIC_RE = /^\d+(?:[.-]\d+)+$/;
+
+/**
+ * Parse the body of a {{...}} mention (without the braces).
+ *
+ * The function is pure: no I/O, no model lookups, no state.
+ * Resolution of the parsed result is the extractor's job.
+ *
+ * @param {string} raw — the trimmed text inside {{...}}
+ * @returns {MentionParseResult}
+ */
+export function parseMention(raw) {
+  const body = raw.trim();
+
+  // 1. cite:<key>[,display] — explicit citation reference.
+  //    Key is the source id; display text is optional.
+  const citeMatch = body.match(/^cite:([^,}]+)(?:,(.*))?$/);
+  if (citeMatch) {
+    const label = citeMatch[2] !== undefined ? unquoteLabel(citeMatch[2].trim()) : null;
+    return {
+      kind: 'cite-ref',
+      key: citeMatch[1].trim(),
+      label,
+      raw: body,
+    };
+  }
+
+  // 2. Comma-separated form: {{id, display}}.
+  //    ID always comes first, display text always comes last.
+  const commaIdx = body.indexOf(',');
+  if (commaIdx !== -1) {
+    const id = body.slice(0, commaIdx).trim();
+    const label = unquoteLabel(body.slice(commaIdx + 1).trim());
+
+    if (NUMERIC_RE.test(id)) {
+      return { kind: 'numeric', id, label, raw: body };
+    }
+    return { kind: 'designation', id, label, raw: body };
+  }
+
+  // 3. Bare numeric id.
+  if (NUMERIC_RE.test(body)) {
+    return { kind: 'numeric', id: body, label: null, raw: body };
+  }
+
+  // 4. Anything else is unresolved at the parse layer.
+  return { kind: 'unresolved', raw: body };
+}
+
+/**
+ * Strip surrounding double quotes from a label, unescaping
+ * CSV-style "" to a single ". If the input is not quoted,
+ * return it unchanged.
+ */
+function unquoteLabel(label) {
+  if (label.length >= 2 && label.startsWith('"') && label.endsWith('"')) {
+    return label.slice(1, -1).replace(/""/g, '"');
+  }
+  return label;
+}

package/src/reference-resolver.js

@@ -1,11 +1,35 @@
 import { ConceptRef } from './models/concept-ref.js';
+import { parseMention } from './reference-mention.js';
 
 export class Reference {
-  constructor(type, target, relationship, source) {
+  /**
+   * @param {string} type — the structural kind of the reference
+   *   ('concept', 'dataset', 'bibliography', 'typed-ref',
+   *   'standard').
+   * @param {string | null} target — the legacy flat display
+   *   string. Kept for backward compat with callers that only
+   *   read `r.target`.
+   * @param {string | null} [relationship] — the type of the
+   *   relationship that produced this reference (e.g. 'see',
+   *   'supersedes', 'source').
+   * @param {string | null} [source] — a JSON-pointer-ish path
+   *   indicating where in the concept the reference was
+   *   extracted from.
+   * @param {object} [extras] — additional fields (v8+):
+   *   `citation`, `sourceId`, `resolution`, `lookupKey`,
+   *   `label`, `quoted`, `uri`. All optional.
+   */
+  constructor(type, target, relationship, source, extras = {}) {
     this.type = type;
     this.target = target;
     this.relationship = relationship ?? null;
     this.source = source ?? null;
+
+    this.uri = extras.uri ?? null;
+    this.citation = extras.citation ?? null;
+    this.sourceId = extras.sourceId ?? null;
+    this.resolution = extras.resolution ?? null;
+    this.lookupKey = extras.lookupKey ?? null;
   }
 }
 
@@ -18,6 +42,21 @@ function refTarget(rc) {
 }
 
 export class ReferenceResolver {
+  /**
+   * Extract all embedded references from a concept's localizations.
+   *
+   * Walks definitions, notes, examples, and annotations text.
+   * For each `{{...}}` mention, runs `parseMention` to
+   * classify the form, then dispatches:
+   *   - 'cite-ref'  → look up the key in concept.sources; emit
+   *                   Bibliography Reference with the Citation.
+   *   - 'numeric'   → emit Concept Reference with the bare id
+   *                   (existing behavior).
+   *   - 'unresolved' → do not emit a Reference.
+   *
+   * @param {Concept} concept
+   * @returns {Reference[]}
+   */
   extractReferences(concept) {
     const refs = [];
 
@@ -42,47 +81,272 @@ export class ReferenceResolver {
         }
       }
 
-      const texts = [
-        ...(lc.definitions?.map(d => d.content ?? '') ?? []),
-        ...(lc.notes?.map(n => typeof n === 'object' ? (n.content ?? '') : String(n)) ?? []),
-      ];
-      for (const text of texts) {
-        refs.push(..._extractEmbedded(text));
+      const texts = this._collectTexts(lc, lang);
+      for (const { text, source } of texts) {
+        for (const ref of this._extractFromText(text, source, concept)) {
+          refs.push(ref);
+        }
       }
     }
 
     return refs;
   }
 
-  resolveReference(ref, collection) {
-    if (ref.type !== 'concept') return null;
-    return collection.byId(ref.target);
+  /**
+   * Collect all text fields from a localized concept, paired
+   * with diagnostic source paths.
+   *
+   * @param {LocalizedConcept} lc
+   * @param {string} lang
+   * @returns {{text: string, source: string}[]}
+   */
+  _collectTexts(lc, lang) {
+    const out = [];
+    for (let i = 0; (lc.definitions ?? [])[i]; i++) {
+      const content = lc.definitions[i]?.content;
+      if (typeof content === 'string') {
+        out.push({ text: content, source: `localizations.${lang}.definitions[${i}].content` });
+      }
+    }
+    for (let i = 0; (lc.notes ?? [])[i]; i++) {
+      const content = typeof lc.notes[i] === 'object'
+        ? (lc.notes[i]?.content ?? '')
+        : String(lc.notes[i] ?? '');
+      if (content) {
+        out.push({ text: content, source: `localizations.${lang}.notes[${i}].content` });
+      }
+    }
+    for (let i = 0; (lc.examples ?? [])[i]; i++) {
+      const content = lc.examples[i]?.content;
+      if (typeof content === 'string') {
+        out.push({ text: content, source: `localizations.${lang}.examples[${i}].content` });
+      }
+    }
+    for (let i = 0; (lc.annotations ?? [])[i]; i++) {
+      const content = lc.annotations[i]?.content;
+      if (typeof content === 'string') {
+        out.push({ text: content, source: `localizations.${lang}.annotations[${i}].content` });
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Walk a single text string and emit References for each
+   * `{{...}}` mention.
+   *
+   * @param {string} text
+   * @param {string} source — diagnostic path
+   * @param {Concept} concept — the owning concept (for cite-ref lookup)
+   * @returns {Reference[]}
+   */
+  _extractFromText(text, source, concept) {
+    const refs = [];
+    const re = /\{\{([^{}]*?)\}\}/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const parsed = parseMention(m[1]);
+      switch (parsed.kind) {
+        case 'cite-ref':
+          refs.push(this._resolveCiteRef(parsed, source, concept));
+          break;
+        case 'numeric':
+          refs.push(new Reference('concept', parsed.label ?? parsed.id, 'embedded', source, {
+            lookupKey: { id: parsed.id },
+          }));
+          break;
+        case 'designation':
+          refs.push(new Reference('concept', parsed.label ?? parsed.id, 'embedded', source, {
+            lookupKey: { designation: parsed.id },
+          }));
+          break;
+        case 'unresolved':
+          break;
+      }
+    }
+    return refs;
+  }
+
+  /**
+   * Resolve a `cite-ref` parser result against the concept's
+   * sources list. Emits a Bibliography Reference with the
+   * resolved Citation (if found) or an unresolved Reference
+   * (if not).
+   *
+   * @param {MentionParseResult} parsed
+   * @param {string} source — diagnostic path
+   * @param {Concept} concept — the owning concept
+   * @returns {Reference}
+   */
+  _resolveCiteRef(parsed, source, concept) {
+    const sourceEntry = concept?.findSourceById(parsed.key) ?? null;
+    if (!sourceEntry) {
+      return new Reference(
+        'bibliography',
+        parsed.label ?? parsed.key,
+        null,
+        source,
+        {
+          sourceId: parsed.key,
+          citation: null,
+          resolution: { kind: 'unresolved', reason: 'no-source' },
+        },
+      );
+    }
+    const displayTarget = parsed.label
+      ?? sourceEntry.origin?.toString()
+      ?? sourceEntry.id;
+    return new Reference(
+      'bibliography',
+      displayTarget,
+      null,
+      source,
+      {
+        sourceId: sourceEntry.id,
+        citation: sourceEntry.origin,
+        resolution: { kind: 'resolved', sourceId: sourceEntry.id },
+      },
+    );
+  }
+
+  /**
+   * Resolve a single reference against a registry (a map of
+   * datasetId → { concepts, register? }). The registry may also
+   * include 'bibliography:<source>' keys for bibliographic
+   * datasets.
+   *
+   * For a `type: 'bibliography'` Reference with an inline
+   * `citation`, the resolver first tries the bibliography
+   * registry (matching `citation.ref` by source/id/version);
+   * if not found, returns the inline Citation as a
+   * self-contained fallback.
+   *
+   * For a `type: 'bibliography'` Reference with a `uri` and
+   * `resolution.kind === 'bibliography-namespace'`, the
+   * resolver tries the bibliography registry by
+   * `resolution.source/id/version`.
+   *
+   * For `type: 'concept'` References with a `lookupKey.id`
+   * (id-match, short-id, or numeric), the resolver looks up
+   * the id in `lookupKey.dataset`'s ConceptCollection.
+   *
+   * Backward compat: when the second argument is a
+   * ConceptCollection (has `byId` but no `concepts` field), it
+   * is treated as a one-key registry of one default dataset.
+   */
+  resolveReference(ref, registry) {
+    if (ref == null) return null;
+
+    // Backward-compat: single ConceptCollection becomes a
+    // one-key registry.
+    if (isConceptCollection(registry)) {
+      registry = { _default: { concepts: registry } };
+    }
+    if (registry == null) return null;
+
+    // 1. cite:key form (Bibliography with inline Citation).
+    if (ref.type === 'bibliography' && ref.citation) {
+      const bioRecord = this._resolveBibliographyRecord(
+        ref.citation.ref,
+        registry,
+      );
+      if (bioRecord) return bioRecord;
+      return ref.citation;
+    }
+
+    // 2. URI form (urn:... or https:...) with
+    //    bibliography-namespace resolution.
+    if (ref.uri) {
+      if (ref.resolution?.kind === 'bibliography-namespace'
+          || (ref.resolution?.source && !ref.resolution?.datasetId)) {
+        const bioRecord = this._resolveBibliographyRecord(
+          ref.resolution,
+          registry,
+        );
+        if (bioRecord) return bioRecord;
+      }
+      // Concept URI lookup (for non-bibliography URIs).
+      if (ref.resolution?.datasetId) {
+        const coll = registry[ref.resolution.datasetId]?.concepts;
+        if (coll) {
+          return coll.byId(ref.resolution.conceptId);
+        }
+      }
+      return null;
+    }
+
+    // 3. Same-dataset concept id (numeric mention, id-match, etc.).
+    if (ref.lookupKey?.id) {
+      const coll = registry[ref.lookupKey.dataset]?.concepts;
+      if (coll) return coll.byId(ref.lookupKey.id);
+      return null;
+    }
+
+    // 3b. Backward-compat: a concept ref with a `target` (id)
+    //     but no `lookupKey` is looked up in the single
+    //     collection (backward-compat one-key registry).
+    if (ref.type === 'concept' && ref.target) {
+      const defaultColl = registry._default?.concepts;
+      if (defaultColl) return defaultColl.byId(ref.target);
+      // Try every dataset in the registry as a fallback.
+      for (const entry of Object.values(registry)) {
+        if (entry?.concepts?.byId(ref.target)) {
+          return entry.concepts.byId(ref.target);
+        }
+      }
+      return null;
+    }
+
+    // 4. Unanchored designation — search is a separate concern
+    //    (plan 06). For v8, return null.
+    if (ref.lookupKey?.designation) {
+      return null;
+    }
+
+    return null;
+  }
+
+  /**
+   * Try to resolve a Citation::Ref against the bibliography
+   * registry. The ref has shape { source, id, version? }.
+   *
+   * Returns the matching bibliographic record (a Concept), or
+   * null if no match.
+   */
+  _resolveBibliographyRecord(citationRef, registry) {
+    if (!citationRef?.source || !citationRef?.id) return null;
+    const bioColl = registry[`bibliography:${citationRef.source}`]?.concepts;
+    if (!bioColl) return null;
+    if (citationRef.version) {
+      return bioColl.byIdAnd(citationRef.id, citationRef.version);
+    }
+    return bioColl.byId(citationRef.id);
   }
 
-  resolveAll(concept, collection) {
+  resolveAll(concept, registry) {
     const resolved = new Map();
     for (const ref of this.extractReferences(concept)) {
-      if (ref.type === 'concept') {
-        resolved.set(ref.target, this.resolveReference(ref, collection));
+      if (ref.type === 'concept' || ref.type === 'bibliography') {
+        const target = this.resolveReference(ref, registry);
+        if (target != null) {
+          const key = ref.target ?? ref.uri ?? ref.sourceId;
+          if (key != null) resolved.set(key, target);
+        }
       }
     }
     return resolved;
   }
 }
 
-const CONCEPT_REF_RE = /\{\{([^}]+)\}\}|\b(\d+(?:\.\d+)+)\b/g;
-
-function _extractEmbedded(text) {
-  const refs = [];
-  let m;
-  CONCEPT_REF_RE.lastIndex = 0;
-  while ((m = CONCEPT_REF_RE.exec(text)) !== null) {
-    const target = m[1] ?? m[2];
-    if (target && /^\d+(\.\d+)+$/.test(target)) {
-      refs.push(new Reference('concept', target, 'embedded', null));
-    }
-  }
-  return refs;
+/**
+ * Type-guard for the single-collection case (backward compat).
+ * A ConceptCollection has `byId` but no `concepts` field.
+ */
+function isConceptCollection(x) {
+  return x != null
+    && typeof x === 'object'
+    && typeof x.byId === 'function'
+    && !('concepts' in x);
 }
 
 export const referenceResolver = new ReferenceResolver();