glossarist 0.3.7 → 0.4.0

package/src/reference-resolver.js

@@ -2,35 +2,32 @@ import { ConceptRef } from './models/concept-ref.js';
 import { parseMention } from './reference-mention.js';
 
 export class Reference {
-  /**
-   * @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;
   }
+
+  get dedupKey() {
+    if (this.type === 'bibliography') {
+      return ['bibliography',
+        this.sourceId ?? this.citation?.ref?.id ?? this.target];
+    }
+    if (this.type === 'figure' || this.type === 'table' || this.type === 'formula') {
+      return [this.type, this.lookupKey?.entityId ?? this.target];
+    }
+    if (this.type === 'concept') {
+      return ['concept',
+        this.lookupKey?.id ?? this.lookupKey?.designation ?? this.target];
+    }
+    return [this.type, this.target];
+  }
 }
 
 function refTarget(rc) {
@@ -41,43 +38,66 @@ function refTarget(rc) {
   return '';
 }
 
+export function 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);
+}
+
+export function findNonVerbalEntity(ref, registry) {
+  const { entityType, entityId } = ref.lookupKey ?? {};
+  if (!entityType || !entityId) return null;
+  const collection = registry[`nvr:${entityType}`];
+  if (!collection) return null;
+  for (const entity of collection) {
+    const found = entity.findById(entityId);
+    if (found) return found;
+  }
+  return null;
+}
+
 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 = [];
 
     for (const rc of concept.relatedConcepts) {
       const target = refTarget(rc);
       if (target) {
-        refs.push(new Reference('concept', target, rc.type, 'relatedConcepts'));
+        refs.push(new Reference('concept', target, rc.type, 'relatedConcepts', {
+          lookupKey: { id: target },
+        }));
       }
     }
 
+    for (const ref of concept.figures) {
+      refs.push(new Reference('figure', ref.display ?? ref.entityId, 'structural', 'figures', {
+        lookupKey: { entityType: 'figure', entityId: ref.entityId },
+      }));
+    }
+    for (const ref of concept.tables) {
+      refs.push(new Reference('table', ref.display ?? ref.entityId, 'structural', 'tables', {
+        lookupKey: { entityType: 'table', entityId: ref.entityId },
+      }));
+    }
+    for (const ref of concept.formulas) {
+      refs.push(new Reference('formula', ref.display ?? ref.entityId, 'structural', 'formulas', {
+        lookupKey: { entityType: 'formula', entityId: ref.entityId },
+      }));
+    }
+
     for (const lang of concept.languages) {
       const lc = concept.localization(lang);
       if (!lc) continue;
 
-      if (lc.sources) {
-        for (let i = 0; i < lc.sources.length; i++) {
-          const src = lc.sources[i];
-          const ref = src.origin?.toString() ?? '';
-          if (ref) {
-            refs.push(new Reference('standard', ref, src.type, `localizations.${lang}.sources[${i}]`));
-          }
+      for (let i = 0; i < lc.sources.length; i++) {
+        const src = lc.sources[i];
+        const ref = src.origin?.toString() ?? '';
+        if (ref) {
+          refs.push(new Reference('standard', ref, src.type, `localizations.${lang}.sources[${i}]`));
         }
       }
 
@@ -89,40 +109,40 @@ export class ReferenceResolver {
       }
     }
 
-    return refs;
+    return this._dedup(refs);
+  }
+
+  _dedup(refs) {
+    const seen = new Set();
+    return refs.filter(ref => {
+      const key = JSON.stringify(ref.dedupKey);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
   }
 
-  /**
-   * 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++) {
+    for (let i = 0; i < lc.definitions.length; 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] ?? '');
+    for (let i = 0; i < lc.notes.length; i++) {
+      const content = lc.notes[i]?.content;
       if (content) {
         out.push({ text: content, source: `localizations.${lang}.notes[${i}].content` });
       }
     }
-    for (let i = 0; (lc.examples ?? [])[i]; i++) {
+    for (let i = 0; i < lc.examples.length; 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++) {
+    for (let i = 0; i < lc.annotations.length; i++) {
       const content = lc.annotations[i]?.content;
       if (typeof content === 'string') {
         out.push({ text: content, source: `localizations.${lang}.annotations[${i}].content` });
@@ -131,15 +151,6 @@ export class ReferenceResolver {
     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;
@@ -156,6 +167,21 @@ export class ReferenceResolver {
             resolution: null,
           }));
           break;
+        case 'fig-ref':
+          refs.push(new Reference('figure', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'figure', entityId: parsed.key },
+          }));
+          break;
+        case 'table-ref':
+          refs.push(new Reference('table', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'table', entityId: parsed.key },
+          }));
+          break;
+        case 'formula-ref':
+          refs.push(new Reference('formula', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'formula', entityId: parsed.key },
+          }));
+          break;
         case 'numeric':
           refs.push(new Reference('concept', parsed.label ?? parsed.id, 'embedded', source, {
             lookupKey: { id: parsed.id },
@@ -173,17 +199,6 @@ export class ReferenceResolver {
     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) {
@@ -215,124 +230,71 @@ export class ReferenceResolver {
     );
   }
 
-  /**
-   * 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;
+    if (ref == null || registry == null) return null;
 
-    // Backward-compat: single ConceptCollection becomes a
-    // one-key registry.
-    if (isConceptCollection(registry)) {
-      registry = { _default: { concepts: registry } };
+    switch (ref.type) {
+      case 'concept':      return this._resolveConcept(ref, registry);
+      case 'bibliography': return this._resolveBibliography(ref, registry);
+      case 'figure':
+      case 'table':
+      case 'formula':      return this._resolveNonVerbal(ref, registry);
+      case 'dataset':      return this._resolveDataset(ref, registry);
+      case 'typed-ref':    return this._resolveTypedRef(ref, registry);
+      case 'standard':     return this._resolveStandard(ref, registry);
+      default:             return null;
     }
-    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;
-    }
+  _resolveNonVerbal(ref, registry) {
+    return findNonVerbalEntity(ref, registry);
+  }
 
-    // 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;
+  _resolveConcept(ref, registry) {
+    if (ref.lookupKey?.id) {
+      const dataset = ref.lookupKey.dataset;
+      if (dataset) {
+        return registry[dataset]?.concepts?.byId(ref.lookupKey.id) ?? null;
       }
-      // 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);
-        }
+      for (const entry of Object.values(registry)) {
+        const found = entry?.concepts?.byId(ref.lookupKey.id);
+        if (found) return found;
       }
       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;
+    if (ref.uri && ref.resolution?.datasetId) {
+      return registry[ref.resolution.datasetId]?.concepts?.byId(ref.resolution.conceptId) ?? null;
     }
+    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;
+  _resolveBibliography(ref, registry) {
+    if (ref.citation) {
+      return resolveBibliographyRecord(ref.citation.ref, registry) ?? ref.citation;
     }
-
-    // 4. Unanchored designation — search is a separate concern
-    //    (plan 06). For v8, return null.
-    if (ref.lookupKey?.designation) {
-      return null;
+    if (ref.uri && ref.resolution?.source) {
+      return resolveBibliographyRecord(ref.resolution, registry) ?? null;
     }
+    return null;
+  }
 
+  _resolveDataset(_ref, _registry) {
     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);
+  _resolveTypedRef(_ref, _registry) {
+    return null;
+  }
+
+  _resolveStandard(_ref, _registry) {
+    return null;
   }
 
   resolveAll(concept, registry) {
     const resolved = new Map();
     for (const ref of this.extractReferences(concept)) {
-      if (ref.type === 'concept' || ref.type === 'bibliography') {
+      if (ref.type === 'concept' || ref.type === 'bibliography'
+          || ref.type === 'figure' || ref.type === 'table' || ref.type === 'formula') {
         const target = this.resolveReference(ref, registry);
         if (target != null) {
           const key = ref.target ?? ref.uri ?? ref.sourceId;
@@ -344,15 +306,4 @@ export class ReferenceResolver {
   }
 }
 
-/**
- * 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();

package/src/render-classification.js

@@ -1,47 +1,29 @@
-/**
- * Classify a Reference for rendering.
- *
- * The classifier is constructed once per render with a registry
- * (and optional source dataset id). The classify() method is
- * pure and side-effect-free.
- *
- * Each `Reference.type` is its own `_classifyXxx` method. The
- * dispatch in classify() is closed for modification.
- */
+import { resolveBibliographyRecord, findNonVerbalEntity } from './reference-resolver.js';
 
 export class ReferenceClassifier {
-  /**
-   * @param {object} registry — the deployment's dataset registry.
-   * @param {string} [sourceDatasetId] — the dataset the source
-   *   concept belongs to; used to determine "same-dataset".
-   * @param {object} [options] — additional options (e.g. scope).
-   */
   constructor(registry = {}, sourceDatasetId = null, options = {}) {
     this.registry = registry;
     this.sourceDatasetId = sourceDatasetId;
     this.options = options;
   }
 
-  /**
-   * @param {Reference} ref
-   * @returns {string} — the classification (e.g. 'same-dataset',
-   *   'internal-citation', 'unresolved', etc.)
-   */
   classify(ref) {
     if (ref == null) return 'unknown';
 
     switch (ref.type) {
-      case 'concept':    return this._classifyConcept(ref);
-      case 'dataset':    return this._classifyDataset(ref);
+      case 'concept':      return this._classifyConcept(ref);
+      case 'dataset':      return this._classifyDataset(ref);
       case 'bibliography': return this._classifyBibliography(ref);
-      case 'typed-ref':  return this._classifyTypedRef(ref);
-      case 'standard':   return 'legacy-standard';
-      default:           return 'unknown';
+      case 'figure':
+      case 'table':
+      case 'formula':      return this._classifyNonVerbal(ref);
+      case 'typed-ref':    return this._classifyTypedRef(ref);
+      case 'standard':     return 'legacy-standard';
+      default:             return 'unknown';
     }
   }
 
   _classifyConcept(ref) {
-    // 1. URI form, resolved to a dataset.
     if (ref.uri) {
       const dsId = ref.resolution?.datasetId;
       if (!dsId) return 'unresolved';
@@ -49,21 +31,15 @@ export class ReferenceClassifier {
       if (dsId === this.sourceDatasetId) return 'same-dataset';
       return 'cross-dataset';
     }
-    // 2. Unanchored designation.
     if (ref.lookupKey?.designation) {
       return 'unresolved-designation';
     }
-    // 3. Id-style (id-match, short-id, numeric).
     if (ref.lookupKey?.id) {
       const dsId = ref.lookupKey.dataset;
       if (!this.registry[dsId]) return 'unresolved';
       if (dsId === this.sourceDatasetId) return 'same-dataset';
       return 'cross-dataset';
     }
-    // 4. Concept ref with target (legacy).
-    if (ref.target) {
-      return 'unresolved';
-    }
     return 'unresolved';
   }
 
@@ -74,18 +50,15 @@ export class ReferenceClassifier {
   }
 
   _classifyBibliography(ref) {
-    // 1. cite:key form: try the bibliography registry.
     if (ref.citation) {
-      const bioRecord = this._tryBibliography(ref.citation.ref);
-      if (bioRecord) return 'internal-citation';
-      return 'self-contained-citation';
+      return resolveBibliographyRecord(ref.citation.ref, this.registry)
+        ? 'internal-citation'
+        : 'self-contained-citation';
     }
-    // 2. URI form: try the bibliography registry, then the
-    //    resolution's datasetId (if it's a concept URI), else null.
     if (ref.uri) {
-      const bioRecord = this._tryBibliography(ref.resolution);
-      if (bioRecord) return 'internal-citation';
-      return 'external-citation';
+      return resolveBibliographyRecord(ref.resolution, this.registry)
+        ? 'internal-citation'
+        : 'external-citation';
     }
     return 'unresolved-citation';
   }
@@ -94,13 +67,9 @@ export class ReferenceClassifier {
     return 'typed-ref';
   }
 
-  _tryBibliography(citationRef) {
-    if (!citationRef?.source || !citationRef?.id) return null;
-    const bioColl = this.registry[`bibliography:${citationRef.source}`]?.concepts;
-    if (!bioColl) return null;
-    if (citationRef.version) {
-      return bioColl.byIdAnd(citationRef.id, citationRef.version) ?? null;
-    }
-    return bioColl.byId(citationRef.id) ?? null;
+  _classifyNonVerbal(ref) {
+    return findNonVerbalEntity(ref, this.registry)
+      ? 'internal-citation'
+      : 'external-citation';
   }
 }

package/src/validators/asset-index.js

@@ -0,0 +1,66 @@
+import { DATASET_ASSETS } from '../dataset-asset.js';
+
+export class AssetIndex {
+  constructor() {
+    this._paths = new Set();
+  }
+
+  get paths() {
+    return [...this._paths].sort();
+  }
+
+  get size() {
+    return this._paths.size;
+  }
+
+  register(path) {
+    if (path == null) return;
+    this._paths.add(this._normalize(path));
+  }
+
+  has(path) {
+    if (path == null) return false;
+    return this._paths.has(this._normalize(path));
+  }
+
+  [Symbol.iterator]() {
+    return this._paths[Symbol.iterator]();
+  }
+
+  _normalize(path) {
+    return String(path).replace(/^\//, '');
+  }
+
+  static async fromGcrPackage(pkg) {
+    const index = new AssetIndex();
+    const names = await pkg.imageFileNames();
+    for (const name of names) {
+      index.register(name);
+    }
+    return index;
+  }
+
+  static fromDirectory(datasetPath, fs) {
+    const index = new AssetIndex();
+    const imagesAsset = DATASET_ASSETS.find(
+      a => a.type === 'directory' && a.path === 'images');
+    if (!imagesAsset) return index;
+
+    const imagesDir = `${datasetPath}/${imagesAsset.path}`;
+    _walkDir(fs, imagesDir, imagesAsset.path, index);
+    return index;
+  }
+}
+
+function _walkDir(fs, dirPath, relativePrefix, index) {
+  if (!fs.existsSync(dirPath)) return;
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = `${dirPath}/${entry.name}`;
+    const relPath = `${relativePrefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      _walkDir(fs, fullPath, relPath, index);
+    } else {
+      index.register(relPath);
+    }
+  }
+}