glossarist 0.4.39 → 0.4.41

package/src/models/localized-concept.ts

@@ -0,0 +1,284 @@
+import { GlossaristModel } from './base.js';
+import { Designation } from './designation.js';
+import { DetailedDefinition } from './detailed-definition.js';
+import { ConceptSource } from './concept-source.js';
+import { ConceptDate } from './concept-date.js';
+import { NonVerbRep } from './non-verb-rep.js';
+import { RelatedConcept } from './related-concept.js';
+
+function wrapAs<T>(
+  Cls: new (...args: never[]) => T,
+): (item: unknown) => T {
+  return (item: unknown): T =>
+    item instanceof Cls ? item : new Cls(item as never);
+}
+
+const LOC_WIRE_NAMES: Readonly<Record<string, string>> = Object.freeze({
+  entryStatus: 'entry_status',
+  reviewType: 'review_type',
+  lineageSourceSimilarity: 'lineage_source_similarity',
+  reviewDate: 'review_date',
+  reviewDecisionDate: 'review_decision_date',
+  reviewDecisionEvent: 'review_decision_event',
+  reviewStatus: 'review_status',
+  reviewDecision: 'review_decision',
+  reviewDecisionNotes: 'review_decision_notes',
+});
+
+export interface LocalizedConceptJson {
+  language_code?: string | null;
+  languageCode?: string | null;
+  script?: string | null;
+  system?: string | null;
+  entry_status?: string | null;
+  entryStatus?: string | null;
+  classification?: string | null;
+  review_type?: string | null;
+  reviewType?: string | null;
+  domain?: string | null;
+  release?: string | null;
+  lineage_source_similarity?: string | null;
+  lineageSourceSimilarity?: string | null;
+  review_date?: string | null;
+  reviewDate?: string | null;
+  review_decision_date?: string | null;
+  reviewDecisionDate?: string | null;
+  review_decision_event?: string | null;
+  reviewDecisionEvent?: string | null;
+  review_status?: string | null;
+  reviewStatus?: string | null;
+  review_decision?: string | null;
+  reviewDecision?: string | null;
+  review_decision_notes?: string | null;
+  reviewDecisionNotes?: string | null;
+  terms?: ReadonlyArray<unknown>;
+  definition?: ReadonlyArray<unknown>;
+  sources?: ReadonlyArray<unknown>;
+  notes?: ReadonlyArray<unknown>;
+  annotations?: ReadonlyArray<unknown>;
+  examples?: ReadonlyArray<unknown>;
+  dates?: ReadonlyArray<unknown>;
+  non_verbal_rep?: ReadonlyArray<unknown>;
+  non_verb?: ReadonlyArray<unknown>;
+  related?: ReadonlyArray<unknown>;
+}
+
+type SlotName = 'definitions' | 'notes' | 'examples' | 'annotations';
+
+export class LocalizedConcept extends GlossaristModel {
+  static get DIFF_FIELDS(): ReadonlyArray<string> {
+    return Object.freeze([
+      'entryStatus', 'classification', 'reviewType', 'domain', 'release',
+      'lineageSourceSimilarity', 'script', 'system',
+      'reviewDate', 'reviewDecisionDate', 'reviewDecisionEvent',
+      'reviewStatus', 'reviewDecision', 'reviewDecisionNotes',
+    ]);
+  }
+
+  static wireNameFor(field: string): string {
+    return LOC_WIRE_NAMES[field] ?? field;
+  }
+
+  readonly languageCode: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly entryStatus: string | null;
+  readonly classification: string | null;
+  readonly reviewType: string | null;
+  readonly domain: string | null;
+  readonly release: string | null;
+  readonly lineageSourceSimilarity: string | null;
+  readonly reviewDate: string | null;
+  readonly reviewDecisionDate: string | null;
+  readonly reviewDecisionEvent: string | null;
+  readonly reviewStatus: string | null;
+  readonly reviewDecision: string | null;
+  readonly reviewDecisionNotes: string | null;
+
+  private readonly _rawTerms: ReadonlyArray<unknown>;
+  private readonly _rawDefinition: ReadonlyArray<unknown>;
+  private readonly _rawSources: ReadonlyArray<unknown>;
+  private readonly _rawNotes: ReadonlyArray<unknown>;
+  private readonly _rawAnnotations: ReadonlyArray<unknown>;
+  private readonly _rawExamples: ReadonlyArray<unknown>;
+  private readonly _rawDates: ReadonlyArray<unknown>;
+  private readonly _rawNonVerbal: ReadonlyArray<unknown>;
+  private readonly _rawRelated: ReadonlyArray<unknown>;
+  private _terms: ReadonlyArray<Designation> | null = null;
+  private _definitions: ReadonlyArray<DetailedDefinition> | null = null;
+  private _sources: ReadonlyArray<ConceptSource> | null = null;
+  private _notes: ReadonlyArray<DetailedDefinition> | null = null;
+  private _annotations: ReadonlyArray<DetailedDefinition> | null = null;
+  private _examples: ReadonlyArray<DetailedDefinition> | null = null;
+  private _dates: ReadonlyArray<ConceptDate> | null = null;
+  private _nonVerbal: ReadonlyArray<NonVerbRep> | null = null;
+  private _related: ReadonlyArray<RelatedConcept> | null = null;
+
+  constructor(data: LocalizedConceptJson = {}) {
+    super();
+    this.languageCode = data.language_code ?? data.languageCode ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.entryStatus = data.entry_status ?? data.entryStatus ?? null;
+    this.classification = data.classification ?? null;
+    this.reviewType = data.review_type ?? data.reviewType ?? null;
+    this.domain = data.domain ?? null;
+    this.release = data.release ?? null;
+    this.lineageSourceSimilarity =
+      data.lineage_source_similarity ?? data.lineageSourceSimilarity ?? null;
+    this.reviewDate = data.review_date ?? data.reviewDate ?? null;
+    this.reviewDecisionDate = data.review_decision_date ?? data.reviewDecisionDate ?? null;
+    this.reviewDecisionEvent = data.review_decision_event ?? data.reviewDecisionEvent ?? null;
+    this.reviewStatus = data.review_status ?? data.reviewStatus ?? null;
+    this.reviewDecision = data.review_decision ?? data.reviewDecision ?? null;
+    this.reviewDecisionNotes = data.review_decision_notes ?? data.reviewDecisionNotes ?? null;
+
+    this._rawTerms = data.terms ?? [];
+    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 ?? [];
+    this._rawRelated = data.related ?? [];
+  }
+
+  get terms(): ReadonlyArray<Designation> {
+    return this._lazy<Designation>(
+      '_terms',
+      '_rawTerms',
+      (t) => Designation.fromData(t),
+    );
+  }
+
+  get definitions(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_definitions',
+      '_rawDefinition',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get definition(): ReadonlyArray<DetailedDefinition> {
+    return this.definitions;
+  }
+
+  get sources(): ReadonlyArray<ConceptSource> {
+    return this._lazy<ConceptSource>(
+      '_sources',
+      '_rawSources',
+      wrapAs(ConceptSource),
+    );
+  }
+
+  get notes(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_notes',
+      '_rawNotes',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get annotations(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_annotations',
+      '_rawAnnotations',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get examples(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_examples',
+      '_rawExamples',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get dates(): ReadonlyArray<ConceptDate> {
+    return this._lazy<ConceptDate>(
+      '_dates',
+      '_rawDates',
+      wrapAs(ConceptDate),
+    );
+  }
+
+  get nonVerbalRep(): ReadonlyArray<NonVerbRep> {
+    return this._lazy<NonVerbRep>(
+      '_nonVerbal',
+      '_rawNonVerbal',
+      wrapAs(NonVerbRep),
+    );
+  }
+
+  get related(): ReadonlyArray<RelatedConcept> {
+    return this._lazy<RelatedConcept>(
+      '_related',
+      '_rawRelated',
+      wrapAs(RelatedConcept),
+    );
+  }
+
+  get primaryDesignation(): string | null {
+    return this.terms[0]?.designation ?? null;
+  }
+
+  get primaryDefinition(): string | null {
+    return this.definitions[0]?.content ?? null;
+  }
+
+  private *_textSlots(): Generator<[SlotName, ReadonlyArray<DetailedDefinition>]> {
+    yield ['definitions', this.definitions];
+    yield ['notes', this.notes];
+    yield ['examples', this.examples];
+    yield ['annotations', this.annotations];
+  }
+
+  *walkTexts(basePath: string): Generator<{ text: string; source: string }> {
+    for (const [name, arr] of this._textSlots()) {
+      for (let i = 0; i < arr.length; i++) {
+        const item = arr[i];
+        if (!item) continue;
+        yield* item.walkTexts(`${basePath}.${name}[${i}]`);
+      }
+    }
+  }
+
+  override toJSON(): LocalizedConceptJson {
+    const obj: LocalizedConceptJson = {};
+    if (this.languageCode) obj.language_code = this.languageCode;
+    if (this.script) obj.script = this.script;
+    if (this.system) obj.system = this.system;
+    if (this.entryStatus) obj.entry_status = this.entryStatus;
+    if (this.classification) obj.classification = this.classification;
+    if (this.reviewType) obj.review_type = this.reviewType;
+    if (this.domain) obj.domain = this.domain;
+    if (this.release) obj.release = this.release;
+    if (this.lineageSourceSimilarity != null) {
+      obj.lineage_source_similarity = this.lineageSourceSimilarity;
+    }
+    if (this.reviewDate) obj.review_date = this.reviewDate;
+    if (this.reviewDecisionDate) obj.review_decision_date = this.reviewDecisionDate;
+    if (this.reviewDecisionEvent) obj.review_decision_event = this.reviewDecisionEvent;
+    if (this.reviewStatus) obj.review_status = this.reviewStatus;
+    if (this.reviewDecision) obj.review_decision = this.reviewDecision;
+    if (this.reviewDecisionNotes) obj.review_decision_notes = this.reviewDecisionNotes;
+
+    this._serialize(obj as unknown as Record<string, unknown>, 'terms', '_terms', '_rawTerms');
+    this._serialize(obj as unknown as Record<string, unknown>, 'definition', '_definitions', '_rawDefinition');
+    this._serialize(obj as unknown as Record<string, unknown>, 'notes', '_notes', '_rawNotes');
+    this._serialize(obj as unknown as Record<string, unknown>, 'annotations', '_annotations', '_rawAnnotations');
+    this._serialize(obj as unknown as Record<string, unknown>, 'examples', '_examples', '_rawExamples');
+    this._serialize(obj as unknown as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    this._serialize(obj as unknown as Record<string, unknown>, 'dates', '_dates', '_rawDates');
+    this._serialize(obj as unknown as Record<string, unknown>, 'non_verbal_rep', '_nonVerbal', '_rawNonVerbal');
+    this._serialize(obj as unknown as Record<string, unknown>, 'related', '_related', '_rawRelated');
+
+    return obj;
+  }
+
+  static override fromJSON(data: LocalizedConceptJson): LocalizedConcept {
+    return new LocalizedConcept(data);
+  }
+}

package/src/models/register.ts

@@ -0,0 +1,315 @@
+import { GlossaristModel } from './base.js';
+import { Section } from './section.js';
+import type { SectionJson } from './section.js';
+import { resolveColor } from './dataset-color.js';
+import type { DatasetColor } from './dataset-color.js';
+import type { LocalizedString } from './generic-member.js';
+
+export const REGISTER_STATUSES: ReadonlyArray<string> = Object.freeze([
+  'current',
+  'superseded',
+  'withdrawn',
+  'draft',
+]);
+
+export interface RegisterJson {
+  schema_version?: string;
+  schemaVersion?: string;
+  id?: string | null;
+  name?: string | LocalizedString | null;
+  ref?: string | null;
+  refAliases?: ReadonlyArray<string>;
+  ref_aliases?: ReadonlyArray<string>;
+  year?: number | string | null;
+  urn?: string | null;
+  urnAliases?: ReadonlyArray<string>;
+  urn_aliases?: ReadonlyArray<string>;
+  status?: string | null;
+  supersedes?: string | null;
+  owner?: string | null;
+  sourceRepo?: string | null;
+  source_repo?: string | null;
+  tags?: ReadonlyArray<string>;
+  languages?: ReadonlyArray<string>;
+  languageOrder?: ReadonlyArray<string>;
+  language_order?: ReadonlyArray<string>;
+  ordering?: string | null;
+  logo?: Record<string, unknown> | null;
+  color?: DatasetColor | null;
+  description?: LocalizedString;
+  about?: LocalizedString;
+  provenance?: ReadonlyArray<Record<string, unknown>>;
+  contributors?: ReadonlyArray<Record<string, unknown>>;
+  sections?: ReadonlyArray<SectionJson | Section>;
+  [key: string]: unknown;
+}
+
+export class Register extends GlossaristModel {
+  readonly schemaVersion: string;
+  readonly id: string | null;
+  readonly name: string | LocalizedString | null;
+  readonly ref: string | null;
+  readonly refAliases: ReadonlyArray<string>;
+  readonly year: number | string | null;
+  readonly urn: string | null;
+  readonly urnAliases: ReadonlyArray<string>;
+  readonly status: string | null;
+  readonly supersedes: string | null;
+  readonly owner: string | null;
+  readonly sourceRepo: string | null;
+  readonly tags: ReadonlyArray<string>;
+  readonly languages: ReadonlyArray<string>;
+  readonly languageOrder: ReadonlyArray<string>;
+  readonly ordering: string | null;
+  readonly logo: Record<string, unknown> | null;
+  readonly color: DatasetColor | null;
+  readonly description: LocalizedString;
+  readonly about: LocalizedString;
+  readonly provenance: ReadonlyArray<Record<string, unknown>>;
+  readonly contributors: ReadonlyArray<Record<string, unknown>>;
+  readonly sections: ReadonlyArray<Section>;
+  private readonly _raw: Record<string, unknown>;
+
+  constructor(data: RegisterJson = {}) {
+    super();
+    this.schemaVersion = data.schema_version ?? data.schemaVersion ?? '3';
+    this.id = data.id ?? null;
+    this.name = (data.name as string | LocalizedString | null) ?? null;
+    this.ref = data.ref ?? null;
+    this.refAliases = data.refAliases ?? data.ref_aliases ?? [];
+    this.year = (data.year as number | string | null) ?? null;
+    this.urn = data.urn ?? null;
+    this.urnAliases = data.urnAliases ?? data.urn_aliases ?? [];
+    this.status = data.status ?? null;
+    this.supersedes = data.supersedes ?? null;
+    this.owner = data.owner ?? null;
+    this.sourceRepo = data.sourceRepo ?? data.source_repo ?? null;
+    this.tags = (data.tags as ReadonlyArray<string>) ?? [];
+    this.languages = (data.languages as ReadonlyArray<string>) ?? [];
+    this.languageOrder = data.languageOrder ?? data.language_order ?? [];
+    this.ordering = data.ordering ?? null;
+    this.logo = (data.logo as Record<string, unknown> | null) ?? null;
+    this.color = (data.color as DatasetColor | null) ?? null;
+    this.description = (data.description as LocalizedString) ?? {};
+    this.about = (data.about as LocalizedString) ?? {};
+    this.provenance = (data.provenance as ReadonlyArray<Record<string, unknown>>) ?? [];
+    this.contributors = (data.contributors as ReadonlyArray<Record<string, unknown>>) ?? [];
+    this.sections = (data.sections ?? []).map((s) =>
+      s instanceof Section ? s : new Section(s as SectionJson),
+    );
+    this._raw = this._extractRaw(data);
+  }
+
+  private _extractRaw(data: RegisterJson): Record<string, unknown> {
+    const known = new Set([
+      'schema_version', 'schemaVersion',
+      'id', 'name', 'ref', 'refAliases', 'ref_aliases',
+      'year', 'urn', 'urnAliases', 'urn_aliases',
+      'status', 'supersedes', 'owner',
+      'sourceRepo', 'source_repo', 'tags',
+      'languages', 'languageOrder', 'language_order',
+      'ordering', 'logo', 'color', 'description', 'about',
+      'provenance', 'contributors', 'sections',
+    ]);
+    const extra: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (!known.has(k)) extra[k] = v;
+    }
+    return extra;
+  }
+
+  sectionById(id: string): Section | null {
+    for (const section of this.sections) {
+      if (section.id === id) return section;
+      const found = section.descendantById(id);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  /**
+   * Walks the section tree upward from `sectionId`, returning the
+   * ancestor chain in immediate-parent-first order. The returned array
+   * does NOT include sectionId itself. Returns [] when sectionId is
+   * unknown or is a top-level section.
+   */
+  sectionAncestorIds(sectionId: string | null | undefined): string[] {
+    if (!sectionId) return [];
+    for (const root of this.sections) {
+      const chain = _ancestorChain(root, sectionId);
+      if (chain) return chain;
+    }
+    return [];
+  }
+
+  /**
+   * Returns the closure of `sectionId`: the section plus all of its
+   * ancestors. Concept-section membership tests should intersect the
+   * concept's section list with this closure.
+   */
+  sectionClosure(sectionId: string | null | undefined): string[] {
+    return sectionId ? [sectionId, ...this.sectionAncestorIds(sectionId)] : [];
+  }
+
+  /**
+   * Walks the section tree DOWNWARD from `sectionId`, returning all
+   * descendant section IDs in pre-order.
+   */
+  sectionDescendantIds(sectionId: string | null | undefined): string[] {
+    if (!sectionId) return [];
+    const section = this.sectionById(sectionId);
+    if (!section) return [];
+    const out: string[] = [];
+    for (const child of section.children) {
+      if (child.id) out.push(child.id);
+      out.push(...this.sectionDescendantIds(child.id));
+    }
+    return out;
+  }
+
+  sectionDescendantClosure(sectionId: string | null | undefined): string[] {
+    return sectionId ? [sectionId, ...this.sectionDescendantIds(sectionId)] : [];
+  }
+
+  /**
+   * Returns all section IDs the concept belongs to: the concept's own
+   * sections plus every ancestor of each.
+   */
+  conceptSectionIds(concept: { sections?: unknown; groups?: unknown }): string[] {
+    const own = conceptSectionIdList(concept);
+    if (own.length === 0) return [];
+    const closure = new Set<string>();
+    for (const id of own) {
+      for (const ancestor of this.sectionClosure(id)) closure.add(ancestor);
+    }
+    return [...closure];
+  }
+
+  sectionName(sectionId: string, lang: string): string | null {
+    const section = this.sectionById(sectionId);
+    return section ? section.name(lang) : null;
+  }
+
+  /**
+   * Localized display name. Returns the best-matching name string for
+   * the requested language, falling back to English, then to the first
+   * available language, then to null.
+   */
+  displayName(lang: string): string | null {
+    if (this.name == null) return null;
+    if (typeof this.name === 'string') return this.name;
+    if (typeof this.name === 'object') {
+      return (
+        this.name[lang] ??
+        this.name['eng'] ??
+        (Object.values(this.name)[0] as string | undefined) ??
+        null
+      );
+    }
+    return null;
+  }
+
+  resolvedColor(mode: 'light' | 'dark'): string | null {
+    return resolveColor(this.color, mode);
+  }
+
+  override toJSON(): RegisterJson {
+    const obj = { ...this._raw, schema_version: this.schemaVersion } as RegisterJson;
+    if (this.id != null) obj.id = this.id;
+    if (this.name != null) obj.name = this.name;
+    if (this.ref != null) obj.ref = this.ref;
+    if (this.refAliases.length > 0) obj.refAliases = [...this.refAliases];
+    if (this.year != null) obj.year = this.year;
+    if (this.urn != null) obj.urn = this.urn;
+    if (this.urnAliases.length > 0) obj.urnAliases = [...this.urnAliases];
+    if (this.status != null) obj.status = this.status;
+    if (this.supersedes != null) obj.supersedes = this.supersedes;
+    if (this.owner != null) obj.owner = this.owner;
+    if (this.sourceRepo != null) obj.sourceRepo = this.sourceRepo;
+    if (this.tags.length > 0) obj.tags = [...this.tags];
+    if (this.languages.length > 0) obj.languages = [...this.languages];
+    if (this.languageOrder.length > 0) obj.languageOrder = [...this.languageOrder];
+    if (this.ordering != null) obj.ordering = this.ordering;
+    if (this.logo != null) obj.logo = { ...this.logo };
+    if (this.color != null) {
+      obj.color =
+        typeof this.color === 'object' && this.color !== null
+          ? { ...this.color }
+          : this.color;
+    }
+    if (Object.keys(this.description).length > 0) obj.description = { ...this.description };
+    if (Object.keys(this.about).length > 0) obj.about = { ...this.about };
+    if (this.provenance.length > 0) obj.provenance = this.provenance.map((p) => ({ ...p }));
+    if (this.contributors.length > 0) obj.contributors = this.contributors.map((c) => ({ ...c }));
+    if (this.sections.length > 0) obj.sections = this.sections.map((s) => s.toJSON());
+    return obj;
+  }
+
+  static override fromJSON(data: RegisterJson): Register {
+    const instance = new Register(data);
+    const snakeToCamel = (k: string): string =>
+      k.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+    return new Proxy(instance, {
+      get(target: Register, prop: string | symbol): unknown {
+        if (typeof prop === 'string') {
+          if (prop in target) return (target as unknown as Record<string, unknown>)[prop];
+          if (prop in target._raw) return target._raw[prop];
+          const camel = snakeToCamel(prop);
+          if (camel in target) return (target as unknown as Record<string, unknown>)[camel];
+        }
+        return undefined;
+      },
+    });
+  }
+}
+
+/**
+ * Recursive walk: returns the ancestor chain of `targetId` within the
+ * subtree rooted at `section`, or null if targetId is not in this
+ * subtree.
+ */
+function _ancestorChain(
+  section: Section,
+  targetId: string,
+  ancestors: string[] = [],
+): string[] | null {
+  if (section.id === targetId) return [...ancestors].reverse();
+  for (const child of section.children) {
+    const childId = child.id;
+    if (childId == null) continue;
+    const nextAncestors = section.id != null ? [...ancestors, section.id] : [...ancestors];
+    const found = _ancestorChain(child, targetId, nextAncestors);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * Returns the list of section IDs a concept claims membership in.
+ * Concepts may carry section IDs via either `sections` (preferred) or
+ * `groups` (legacy). Each entry may be a string or an object with an
+ * `id` field; both forms are flattened to a string list.
+ */
+function conceptSectionIdList(concept: { sections?: unknown; groups?: unknown }): string[] {
+  if (!concept) return [];
+  const fromSections = concept.sections
+    ? _flattenSectionIds(concept.sections)
+    : [];
+  const fromGroups = concept.groups ? _flattenSectionIds(concept.groups) : [];
+  return [...fromSections, ...fromGroups];
+}
+
+function _flattenSectionIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === 'string') {
+      out.push(entry);
+    } else if (entry && typeof entry === 'object') {
+      const e = entry as { id?: string; sectionId?: string; ref?: { id?: string } };
+      const id = e.id ?? e.sectionId ?? e.ref?.id;
+      if (id) out.push(String(id));
+    }
+  }
+  return out;
+}