glossarist 0.3.7 → 0.3.8

package/package.json

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

package/src/concept-reader.js

@@ -20,7 +20,7 @@ function assertDir(dir, fnName) {
  *
  * @example
  * const concepts = readConcepts('./geolexica-v2/');
- * console.log(concepts[0].localizations.eng.terms[0].designation);
+ * console.log(concepts[0].localization('eng').terms[0].designation);
  */
 export function readConcepts(dir) {
   assertDir(dir, 'readConcepts');

package/src/gcr-reader.js

@@ -418,7 +418,7 @@ export class GcrPackage {
  *
  * @example
  * const concept = parseConceptYaml('termid: "001"\neng:\n  terms:\n    - designation: test', '001');
- * console.log(concept.localizations.eng.terms[0].designation); // "test"
+ * console.log(concept.localization('eng').terms[0].designation); // "test"
  */
 export function parseConceptYaml(raw, context) {
   return conceptParser.parse(raw, context);

package/src/index.js

@@ -7,7 +7,7 @@ export { ConceptCollection } from './concept-collection.js';
 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 { ReferenceResolver, Reference, referenceResolver, resolveBibliographyRecord } from './reference-resolver.js';
 export { parseMention } from './reference-mention.js';
 export { ReferenceClassifier } from './render-classification.js';
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';

package/src/models/base.js

@@ -15,4 +15,18 @@ export class GlossaristModel {
   clone() {
     return this.constructor.fromJSON(JSON.parse(JSON.stringify(this.toJSON())));
   }
+
+  _lazy(cacheKey, rawKey, wrapFn) {
+    if (this[cacheKey] === null) {
+      this[cacheKey] = this[rawKey].map(wrapFn);
+    }
+    return this[cacheKey];
+  }
+
+  _serialize(obj, jsonKey, cacheKey, rawKey) {
+    const items = this[cacheKey] ?? (this[rawKey].length > 0 ? this[rawKey] : []);
+    if (items.length > 0) {
+      obj[jsonKey] = items.map(i => (i instanceof GlossaristModel) ? i.toJSON() : i);
+    }
+  }
 }

package/src/models/concept.js

@@ -34,11 +34,6 @@ export class Concept extends GlossaristModel {
     return this.languages;
   }
 
-  /** @deprecated Use localization(lang) for model access, or toJSON().localizations for raw data */
-  get localizations() {
-    return this._rawLocalizations;
-  }
-
   localization(lang) {
     if (!(lang in this._rawLocalizations)) return undefined;
     if (!this._cache[lang]) {

package/src/models/localized-concept.js

@@ -131,20 +131,6 @@ export class LocalizedConcept extends GlossaristModel {
     return obj;
   }
 
-  _lazy(cacheKey, rawKey, wrapFn) {
-    if (this[cacheKey] === null) {
-      this[cacheKey] = this[rawKey].map(wrapFn);
-    }
-    return this[cacheKey];
-  }
-
-  _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);
-    }
-  }
-
   static fromJSON(data) {
     return new LocalizedConcept(data);
   }

package/src/reference-resolver.js

@@ -2,29 +2,11 @@ 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;
@@ -41,29 +23,26 @@ 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 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 },
+        }));
       }
     }
 
@@ -71,13 +50,11 @@ export class ReferenceResolver {
       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}]`));
         }
       }
 
@@ -92,37 +69,27 @@ export class ReferenceResolver {
     return refs;
   }
 
-  /**
-   * 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 +98,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;
@@ -173,17 +131,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,118 +162,57 @@ 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 } };
-    }
-    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;
+    switch (ref.type) {
+      case 'concept':      return this._resolveConcept(ref, registry);
+      case 'bibliography': return this._resolveBibliography(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;
     }
+  }
 
-    // 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) {
@@ -344,15 +230,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,26 @@
-/**
- * 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 } 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 '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 +28,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 +47,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';
   }
@@ -93,14 +63,4 @@ export class ReferenceClassifier {
   _classifyTypedRef(_ref) {
     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;
-  }
 }

package/src/validators/concept-validator.js

@@ -9,18 +9,13 @@ const VALID_ENTRY_STATUSES = new Set([
   'valid', 'draft', 'retired', 'notValid', 'superseded', 'withdrawn',
 ]);
 
-const _langs = (c) =>
-  c.languages ?? (c.localizations ? Object.keys(c.localizations) : []);
-
-const _loc = (c, lang) =>
-  typeof c.localization === 'function' ? c.localization(lang) : c.localizations?.[lang];
-
 export class LanguageCodeRule extends ValidationRule {
   constructor() { super('language-code'); }
   validate(concept, path, result) {
-    for (const lang of _langs(concept)) {
+    for (const lang of concept.languages) {
       if (!/^[a-z]{3}$/.test(lang)) {
-        result.addError(`${path}localizations.${lang}`,
+        this.addIssue(result,
+          `${path}localizations.${lang}`,
           `Invalid language code '${lang}': expected ISO 639-3 (3 lowercase letters)`);
       }
     }
@@ -30,15 +25,14 @@ export class LanguageCodeRule extends ValidationRule {
 export class DesignationTypeRule extends ValidationRule {
   constructor() { super('designation-type'); }
   validate(concept, path, result) {
-    for (const lang of _langs(concept)) {
-      const lc = _loc(concept, lang);
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
       if (!lc) continue;
-      const terms = lc.terms ?? [];
-      for (let i = 0; i < terms.length; i++) {
-        const t = terms[i];
-        const type = t.type ?? (typeof t.toJSON === 'function' ? t.toJSON().type : undefined);
+      for (let i = 0; i < lc.terms.length; i++) {
+        const type = lc.terms[i].type;
         if (type && !VALID_DESIGNATION_TYPES.has(type)) {
-          result.addError(`${path}localizations.${lang}.terms[${i}].type`,
+          this.addIssue(result,
+            `${path}localizations.${lang}.terms[${i}].type`,
             `Unknown designation type '${type}'`);
         }
       }
@@ -49,13 +43,13 @@ export class DesignationTypeRule extends ValidationRule {
 export class EntryStatusRule extends ValidationRule {
   constructor() { super('entry-status'); }
   validate(concept, path, result) {
-    for (const lang of _langs(concept)) {
-      const lc = _loc(concept, lang);
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
       if (!lc) continue;
-      const status = lc.entryStatus ?? lc.entry_status;
-      if (status && !VALID_ENTRY_STATUSES.has(status)) {
-        result.addError(`${path}localizations.${lang}.entry_status`,
-          `Unknown entry status '${status}'`);
+      if (lc.entryStatus && !VALID_ENTRY_STATUSES.has(lc.entryStatus)) {
+        this.addIssue(result,
+          `${path}localizations.${lang}.entry_status`,
+          `Unknown entry status '${lc.entryStatus}'`);
       }
     }
   }
@@ -71,30 +65,21 @@ export class ConceptValidator {
 
   validate(concept) {
     const result = new ValidationResult();
-    const hasModelApi = typeof concept.localization === 'function';
 
     if (!concept.id) {
       result.addError('id', 'Concept must have an id');
     }
 
-    const langs = hasModelApi ? concept.languages : Object.keys(concept.localizations ?? {});
-    if (langs.length === 0) {
+    if (concept.languages.length === 0) {
       result.addWarning('localizations', 'Concept must have at least one localization');
-    } else if (hasModelApi) {
-      for (const lang of langs) {
+    } else {
+      for (const lang of concept.languages) {
         const lc = concept.localization(lang);
         if (!lc || lc.terms.length === 0) {
           result.addWarning(`localizations.${lang}.terms`,
             `Localization '${lang}' must have at least one term`);
         }
       }
-    } else {
-      for (const [lang, lc] of Object.entries(concept.localizations ?? {})) {
-        if (!lc.terms || lc.terms.length === 0) {
-          result.addWarning(`localizations.${lang}.terms`,
-            `Localization '${lang}' must have at least one term`);
-        }
-      }
     }
 
     for (const rule of this._rules) {

package/src/validators/v3-rules.js

@@ -1,14 +1,8 @@
 import { ValidationRule } from './validation-rule.js';
 
-const _langs = (concept) =>
-  concept.languages ?? (concept.localizations ? Object.keys(concept.localizations) : []);
-
-const _loc = (concept, lang) =>
-  typeof concept.localization === 'function' ? concept.localization(lang) : concept.localizations?.[lang];
-
 const _eachLocalization = (concept, fn) => {
-  for (const lang of _langs(concept)) {
-    const lc = _loc(concept, lang);
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
     if (lc) fn(lang, lc);
   }
 };
@@ -19,7 +13,7 @@ export class RefShapeRule extends ValidationRule {
   validate(concept, path, result) {
     let sourceIdx = 0;
     _eachLocalization(concept, (lang, lc) => {
-      const sources = lc.sources ?? [];
+      const sources = lc.sources;
       for (let i = 0; i < sources.length; i++) {
         sourceIdx++;
         const origin = sources[i].origin;
@@ -38,7 +32,7 @@ export class RefShapeRule extends ValidationRule {
       }
     });
 
-    const related = concept.relatedConcepts ?? concept.related ?? [];
+    const related = concept.relatedConcepts;
     for (let i = 0; i < related.length; i++) {
       const ref = related[i].ref;
       if (!ref) continue;
@@ -56,7 +50,7 @@ export class LocalityCompletenessRule extends ValidationRule {
 
   validate(concept, path, result) {
     _eachLocalization(concept, (lang, lc) => {
-      const sources = lc.sources ?? [];
+      const sources = lc.sources;
       for (let i = 0; i < sources.length; i++) {
         const origin = sources[i].origin;
         if (!origin || !origin.locality) continue;
@@ -81,14 +75,14 @@ export class LocalizationConsistencyRule extends ValidationRule {
   constructor() { super('localization-consistency'); }
 
   validate(concept, path, result) {
-    const langs = _langs(concept);
-    const data = concept.raw?.data || concept;
+    const langs = concept.languages;
+    const data = concept.raw?.data || {};
     const declaredLangs = data.localized_concepts
       ? Object.keys(data.localized_concepts)
       : langs;
 
     for (const lang of declaredLangs) {
-      if (!concept.hasLocalization?.(lang) && !(concept.localizations?.[lang])) {
+      if (!concept.hasLocalization(lang)) {
         this.addIssue(result,
           `${path}localizations.${lang}`,
           `localized_concepts map has '${lang}' but no localization loaded`);
@@ -101,12 +95,10 @@ export class SchemaVersionRule extends ValidationRule {
   constructor() { super('schema-version', 'warning'); }
 
   validate(concept, path, result) {
-    const version = concept.schemaVersion ?? concept.schema_version;
-
-    if (version && String(version) !== '3') {
+    if (concept.schemaVersion && String(concept.schemaVersion) !== '3') {
       this.addIssue(result,
         `${path}schema_version`,
-        `schema_version is '${version}', expected '3'`);
+        `schema_version is '${concept.schemaVersion}', expected '3'`);
     }
   }
 }
@@ -115,11 +107,8 @@ export class DomainRefRule extends ValidationRule {
   constructor() { super('domain-ref', 'warning'); }
 
   validate(concept, path, result) {
-    const domains = concept.domains || [];
-
-    for (let i = 0; i < domains.length; i++) {
-      const domain = domains[i];
-      const json = typeof domain.toJSON === 'function' ? domain.toJSON() : domain;
+    for (let i = 0; i < concept.domains.length; i++) {
+      const json = concept.domains[i].toJSON();
       if (!json.concept_id && !json.urn) {
         this.addIssue(result,
           `${path}domains[${i}]`,
@@ -134,7 +123,7 @@ export class UuidFormatRule extends ValidationRule {
 
   validate(concept, path, result) {
     const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-    const id = concept.id || concept.uuid;
+    const id = concept.id;
 
     if (id && !UUID_RE.test(String(id))) {
       if (String(id).includes('-') && String(id).length > 20) {
@@ -153,7 +142,7 @@ export class SourceUrnFormatRule extends ValidationRule {
     const URN_RE = /^urn:[a-z0-9][a-z0-9-]{0,31}:[a-z0-9()+,\-.:=@;$_!*'%/?#]+$/i;
 
     _eachLocalization(concept, (lang, lc) => {
-      const sources = lc.sources ?? [];
+      const sources = lc.sources;
       for (let i = 0; i < sources.length; i++) {
         const source = lc.sources[i].origin?.ref?.source;
         if (!source || !source.startsWith('urn:')) continue;
@@ -180,23 +169,23 @@ function _findCiteMentions(concept) {
     }
   };
 
-  for (const lang of _langs(concept)) {
-    const lc = _loc(concept, lang);
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
     if (!lc) continue;
 
-    for (let i = 0; (lc.definitions ?? [])[i]; i++) {
+    for (let i = 0; lc.definitions[i]; i++) {
       walkText(lc.definitions[i]?.content, `localizations.${lang}.definitions[${i}].content`);
     }
-    for (let i = 0; (lc.notes ?? [])[i]; i++) {
+    for (let i = 0; lc.notes[i]; i++) {
       const content = typeof lc.notes[i] === 'object'
         ? (lc.notes[i]?.content ?? '')
         : String(lc.notes[i] ?? '');
       walkText(content, `localizations.${lang}.notes[${i}].content`);
     }
-    for (let i = 0; (lc.examples ?? [])[i]; i++) {
+    for (let i = 0; lc.examples[i]; i++) {
       walkText(lc.examples[i]?.content, `localizations.${lang}.examples[${i}].content`);
     }
-    for (let i = 0; (lc.annotations ?? [])[i]; i++) {
+    for (let i = 0; lc.annotations[i]; i++) {
       walkText(lc.annotations[i]?.content, `localizations.${lang}.annotations[${i}].content`);
     }
   }
@@ -212,13 +201,13 @@ function _findDuplicateSourceIds(concept) {
     seen.get(source.id).push(source);
   };
 
-  for (const source of (concept.sources ?? [])) record(source);
-  for (const lang of _langs(concept)) {
-    const lc = _loc(concept, lang);
+  for (const source of concept.sources) record(source);
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
     if (!lc) continue;
-    for (const source of (lc.sources ?? [])) record(source);
-    for (const designation of (lc.terms ?? [])) {
-      for (const source of (designation.sources ?? [])) record(source);
+    for (const source of (lc.sources)) record(source);
+    for (const designation of lc.terms) {
+      for (const source of designation.sources) record(source);
     }
   }
 
@@ -231,17 +220,17 @@ function _findDuplicateSourceIds(concept) {
 
 function _collectSourceIds(concept) {
   const ids = new Set();
-  for (const source of (concept.sources ?? [])) {
+  for (const source of concept.sources) {
     if (source?.id != null) ids.add(source.id);
   }
-  for (const lang of _langs(concept)) {
-    const lc = _loc(concept, lang);
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
     if (!lc) continue;
-    for (const source of (lc.sources ?? [])) {
+    for (const source of (lc.sources)) {
       if (source?.id != null) ids.add(source.id);
     }
-    for (const designation of (lc.terms ?? [])) {
-      for (const source of (designation.sources ?? [])) {
+    for (const designation of lc.terms) {
+      for (const source of designation.sources) {
         if (source?.id != null) ids.add(source.id);
       }
     }