glossarist 0.4.50 → 0.4.52

package/src/models/abstract-hyperedge.ts

@@ -1,164 +0,0 @@
-// AbstractHyperedge — shared base for directed 1→N hyperedges
-// (PartitiveHyperedge, GenericHyperedge, SequentialHyperedge, future
-// AssociativeHyperedge, etc.).
-//
-// Carries the common shape:
-//   - comprehensive: ConceptRef
-//   - members: 2+ MECE dimensioned concept refs (≥2 per ISO 704)
-//   - completeness: complete | partial
-//   - criterion: localized subdivision criterion (ISO 12620)
-//   - sources / notes / status: administrative metadata
-//
-// See docs/design/abstract-hyperedge.md (concept-model repo).
-
-import { GlossaristModel } from './base.js';
-import { ConceptRef } from './concept-ref.js';
-import type { ConceptRefJson } from './concept-ref.js';
-import { DEFAULT_COMPLETENESS, isValidCompleteness } from './completeness.js';
-import type { Completeness } from './completeness.js';
-import type { HyperedgeMember } from './hyperedge-member.js';
-import type { LocalizedString } from './generic-member.js';
-
-export interface AbstractHyperedgeJson {
-  comprehensive: ConceptRefJson;
-  members: ReadonlyArray<unknown>;
-  completeness: Completeness;
-  criterion?: LocalizedString;
-  sources?: ReadonlyArray<unknown>;
-  notes?: Record<string, unknown> | null;
-  status?: string | null;
-  /** PartitiveHyperedge wire alias (only present on PartitiveHyperedge JSON). */
-  partitives?: ReadonlyArray<unknown>;
-}
-
-export type CriterionInput = string | LocalizedString | null | undefined;
-
-export abstract class AbstractHyperedge extends GlossaristModel {
-  readonly comprehensive: ConceptRef;
-  readonly members: ReadonlyArray<HyperedgeMember>;
-  readonly completeness: Completeness;
-  readonly criterion: LocalizedString | null;
-  readonly sources: ReadonlyArray<unknown>;
-  readonly notes: Record<string, unknown> | null;
-  readonly status: string | null;
-
-  constructor(
-    data: AbstractHyperedgeJson = {
-      comprehensive: {},
-      members: [],
-      completeness: 'complete',
-    },
-  ) {
-    super();
-    this.comprehensive = _ensureComprehensive(data.comprehensive);
-    this.members = _ensureMembers(
-      data.members,
-      this.constructor.name,
-    ) as ReadonlyArray<HyperedgeMember>;
-    this.completeness = _resolveCompleteness(data.completeness);
-    this.criterion = _normalizeCriterion(data.criterion);
-    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
-    this.notes = (data.notes as Record<string, unknown> | null) ?? null;
-    this.status = data.status ?? null;
-
-    _assertNoSelfLoop(this.comprehensive, this.members);
-  }
-
-  get isComplete(): boolean { return this.completeness === 'complete'; }
-  get isPartial(): boolean { return this.completeness === 'partial'; }
-  get isCoordinate(): boolean { return this.members.length >= 2; }
-
-  hasCriterion(): boolean { return this.criterion != null; }
-
-  override identity(): string {
-    const Ctor = this.constructor as unknown as { identityOf: (v: unknown) => string };
-    return Ctor.identityOf(this);
-  }
-
-  override toJSON(): AbstractHyperedgeJson {
-    const obj: AbstractHyperedgeJson = {
-      comprehensive: this.comprehensive.toJSON(),
-      members: this.members.map((m) => m.toJSON()),
-      completeness: this.completeness,
-    };
-    if (this.criterion != null) obj.criterion = { ...this.criterion };
-    if (this.sources.length > 0) obj.sources = [...this.sources];
-    if (this.notes != null) obj.notes = { ...this.notes };
-    if (this.status != null) obj.status = this.status;
-    return obj;
-  }
-}
-
-function _ensureComprehensive(
-  value: ConceptRefJson | ConceptRef | null | undefined,
-): ConceptRef {
-  const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
-  if (!ref.source && !ref.id && !ref.text) {
-    throw new Error(
-      'AbstractHyperedge.comprehensive must be a non-empty ConceptReference ' +
-      '(source, id, or text required)',
-    );
-  }
-  return ref;
-}
-
-function _ensureMembers(
-  values: ReadonlyArray<unknown> | null | undefined,
-  typeName: string,
-): ReadonlyArray<unknown> {
-  if (!Array.isArray(values)) {
-    throw new Error(
-      `${typeName}.members must be an array (got ${values === null ? 'null' : typeof values})`,
-    );
-  }
-  if (values.length < 2) {
-    throw new Error(
-      `${typeName} requires ≥2 partitives (ISO 704); got ${values.length}`,
-    );
-  }
-  return values;
-}
-
-function _resolveCompleteness(
-  value: Completeness | null | undefined,
-): Completeness {
-  const c = value ?? DEFAULT_COMPLETENESS;
-  if (!isValidCompleteness(c)) {
-    throw new Error(
-      `completeness has invalid value ${JSON.stringify(value)}`,
-    );
-  }
-  return c;
-}
-
-function _normalizeCriterion(value: CriterionInput): LocalizedString | null {
-  if (value == null) return null;
-  if (typeof value === 'string') {
-    return value.length > 0 ? { default: value } : null;
-  }
-  if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(
-      ([, v]) => typeof v === 'string',
-    );
-    return entries.length > 0
-      ? (Object.fromEntries(entries) as LocalizedString)
-      : null;
-  }
-  return null;
-}
-
-function _assertNoSelfLoop(
-  comprehensive: ConceptRef,
-  members: ReadonlyArray<{ ref?: { source?: string | null; id?: string | null } }>,
-): void {
-  const cKey = `${comprehensive.source ?? ''}:${comprehensive.id ?? ''}`;
-  for (const m of members) {
-    const ref = m.ref;
-    const pKey = `${ref?.source ?? ''}:${ref?.id ?? ''}`;
-    if (pKey === cKey && (ref?.source || ref?.id)) {
-      throw new Error(
-        'Relation.members cannot include the comprehensive (no self-loops)',
-      );
-    }
-  }
-}

package/src/models/base.ts

@@ -1,110 +0,0 @@
-/**
- * GlossaristModel — abstract base for every domain model.
- *
- * Subclasses implement `toJSON()` (wire shape) and `identity()`
- * (stable string key for diff/dedupe). `equals()` and `clone()`
- * default to comparing via JSON serialization; subclasses may
- * override for performance.
- */
-
-/**
- * Any value that can be the output of `JSON.stringify`. Used as the
- * return type of {@link GlossaristModel.toJSON} so subclasses with
- * non-object JSON output (e.g. `NonVerbalReference.toJSON()` returns
- * a bare string for the no-display case) can override without
- * breaking variance. The object case accepts any object to avoid
- * forcing `<Model>Json` interfaces to declare explicit string index
- * signatures (TS interfaces don't have implicit index signatures).
- */
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | object;
-
-export abstract class GlossaristModel {
-  /** Wire-shape serialization. Subclasses MUST override. */
-  toJSON(): JsonValue {
-    throw new Error(`${this.constructor.name} must implement toJSON()`);
-  }
-
-  /** Stable identity string for diff, dedupe, registry keys. */
-  identity(): string {
-    throw new Error(`${this.constructor.name} must implement identity()`);
-  }
-
-  /** Default: structural equality via JSON. Override for semantic equality. */
-  equals(other: this): boolean {
-    if (!(other instanceof this.constructor)) return false;
-    return JSON.stringify(this.toJSON()) === JSON.stringify(other.toJSON());
-  }
-
-  /** Deep clone via JSON round-trip. Subclasses with non-JSON-safe
-   *  fields must override. */
-  clone(): this {
-    const Ctor = this.constructor as new (data: unknown) => this;
-    return new Ctor(JSON.parse(JSON.stringify(this.toJSON())));
-  }
-
-  /**
-   * Subclasses MUST override. Declared on the abstract base so callers
-   * who only have `typeof GlossaristModel` get a typed call site
-   * (rather than the static disappearing under `abstract`).
-   */
-  static fromJSON(_data: unknown): GlossaristModel {
-    throw new Error(`${this.name} must implement fromJSON()`);
-  }
-
-  /**
-   * Lazily wrap a raw array (plain hashes) into model instances.
-   * Used by Concept's lazy `figures`/`tables`/`formulas` getters so
-   * the wrap cost is only paid on first access.
-   *
-   * `cacheKey` and `rawKey` are private field names on `this`. The
-   * bracket access here is the only legitimate reflective pattern in
-   * the codebase (lazy field init). It is bracket-typed through a
-   * local alias rather than the public surface.
-   *
-   * Underscore-prefixed (not `protected`) so JS subclasses during the
-   * TS migration transition can call it without TS4094 on anonymous
-   * class expressions. Once all subclasses are .ts this can move to
-   * `protected`.
-   */
-  _lazy<TItem>(
-    cacheKey: string,
-    rawKey: string,
-    wrapFn: (raw: unknown) => TItem,
-  ): TItem[] {
-    const cache = this as unknown as Record<string, TItem[] | null | undefined>;
-    const raw = this as unknown as Record<string, unknown[] | undefined>;
-    if (cache[cacheKey] === null || cache[cacheKey] === undefined) {
-      const rawArr = raw[rawKey] ?? [];
-      cache[cacheKey] = rawArr.map((r) => wrapFn(r));
-    }
-    return cache[cacheKey] ?? [];
-  }
-
-  /**
-   * Helper for `toJSON()`: serialize a lazy-or-raw array under
-   * `jsonKey` only when it has items. Model instances go through
-   * `toJSON()`; primitives pass through.
-   */
-  _serialize(
-    obj: Record<string, unknown>,
-    jsonKey: string,
-    cacheKey: string,
-    rawKey: string,
-  ): void {
-    const self = this as unknown as Record<string, unknown[] | null | undefined>;
-    const cached = self[cacheKey];
-    const raw = self[rawKey];
-    const items = cached ?? (Array.isArray(raw) && raw.length > 0 ? raw : []);
-    if (items.length > 0) {
-      obj[jsonKey] = items.map((i) =>
-        i instanceof GlossaristModel ? i.toJSON() : i,
-      );
-    }
-  }
-}

package/src/models/bibliography-data.ts

@@ -1,64 +0,0 @@
-import * as yaml from 'js-yaml';
-import { GlossaristModel } from './base.js';
-import { BibliographyEntry } from './bibliography-entry.js';
-import type { BibliographyEntryJson } from './bibliography-entry.js';
-
-export interface BibliographyDataJson {
-  bibliography?: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-  entries?: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-}
-
-export class BibliographyData extends GlossaristModel {
-  private readonly _rawEntries: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-  private _entries: ReadonlyArray<BibliographyEntry> | null = null;
-
-  constructor(data: BibliographyDataJson | ReadonlyArray<BibliographyEntryJson | BibliographyEntry> = {}) {
-    super();
-    let entriesData: ReadonlyArray<BibliographyEntryJson | BibliographyEntry> | undefined;
-    if (Array.isArray(data)) {
-      entriesData = data;
-    } else {
-      entriesData = (data as BibliographyDataJson)?.bibliography ?? (data as BibliographyDataJson)?.entries ?? [];
-    }
-    this._rawEntries = Array.isArray(entriesData) ? entriesData : [];
-  }
-
-  get entries(): ReadonlyArray<BibliographyEntry> {
-    return this._lazy<BibliographyEntry>(
-      '_entries',
-      '_rawEntries',
-      (e) => (e instanceof BibliographyEntry ? e : new BibliographyEntry(e as BibliographyEntryJson)),
-    );
-  }
-
-  find(id: string): BibliographyEntry | null {
-    return this.entries.find((e) => e.id === id) ?? null;
-  }
-
-  get keys(): ReadonlyArray<string | null> {
-    return this.entries.map((e) => e.id);
-  }
-
-  override toJSON(): BibliographyDataJson {
-    if (this.entries.length === 0) return { bibliography: [] };
-    return { bibliography: this.entries.map((e) => e.toJSON()) };
-  }
-
-  toYAML(): string {
-    return yaml.dump(this.toJSON());
-  }
-
-  static fromYAML(yamlString: string): BibliographyData {
-    const parsed = yaml.load(yamlString) as
-      | BibliographyDataJson
-      | ReadonlyArray<BibliographyEntryJson>
-      | undefined;
-    return new BibliographyData(parsed ?? {});
-  }
-
-  static override fromJSON(
-    data: BibliographyDataJson | ReadonlyArray<BibliographyEntryJson>,
-  ): BibliographyData {
-    return new BibliographyData(data);
-  }
-}

package/src/models/bibliography-entry.ts

@@ -1,40 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export interface BibliographyEntryJson {
-  id?: string | null;
-  reference?: string | null;
-  title?: string | null;
-  link?: string | null;
-  type?: string | null;
-}
-
-export class BibliographyEntry extends GlossaristModel {
-  readonly id: string | null;
-  readonly reference: string | null;
-  readonly title: string | null;
-  readonly link: string | null;
-  readonly type: string | null;
-
-  constructor(data: BibliographyEntryJson = {}) {
-    super();
-    this.id = data.id ?? null;
-    this.reference = data.reference ?? null;
-    this.title = data.title ?? null;
-    this.link = data.link ?? null;
-    this.type = data.type ?? null;
-  }
-
-  override toJSON(): BibliographyEntryJson {
-    const obj: BibliographyEntryJson = {};
-    if (this.id != null) obj.id = this.id;
-    if (this.reference != null) obj.reference = this.reference;
-    if (this.title != null) obj.title = this.title;
-    if (this.link != null) obj.link = this.link;
-    if (this.type != null) obj.type = this.type;
-    return obj;
-  }
-
-  static override fromJSON(data: BibliographyEntryJson): BibliographyEntry {
-    return new BibliographyEntry(data);
-  }
-}

package/src/models/citation.ts

@@ -1,98 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Locality } from './locality.js';
-import type { LocalityJson } from './locality.js';
-
-export interface CitationRefJson {
-  source?: string | null;
-  id?: string | null;
-  version?: string | null;
-}
-
-export interface CitationJson {
-  ref?: CitationRefJson | CitationRef | null;
-  locality?: LocalityJson | Locality | null;
-  link?: string | null;
-  original?: string | null;
-  custom_locality?: string | null;
-  customLocality?: string | null;
-}
-
-export class CitationRef extends GlossaristModel {
-  readonly source: string | null;
-  readonly id: string | null;
-  readonly version: string | null;
-
-  constructor(data: CitationRefJson = {}) {
-    super();
-    this.source = data.source ?? null;
-    this.id = data.id ?? null;
-    this.version = data.version ?? null;
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    return parts.join(' ');
-  }
-
-  override toJSON(): CitationRefJson {
-    const obj: CitationRefJson = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.version != null) obj.version = this.version;
-    return obj;
-  }
-
-  static override fromJSON(data: CitationRefJson): CitationRef {
-    return new CitationRef(data);
-  }
-}
-
-export class Citation extends GlossaristModel {
-  /** Backward-compat alias for {@link CitationRef}. Original codebase
-   *  exposed the Ref class via `Citation.Ref`; keep that working. */
-  static readonly Ref = CitationRef;
-
-  readonly ref: CitationRef | null;
-  readonly locality: Locality | null;
-  readonly link: string | null;
-  readonly original: string | null;
-  readonly customLocality: string | null;
-
-  constructor(data: CitationJson | null = {}) {
-    super();
-    const d = data ?? {};
-    this.ref = d.ref
-      ? d.ref instanceof CitationRef
-        ? d.ref
-        : new CitationRef(d.ref)
-      : null;
-    this.locality = d.locality
-      ? d.locality instanceof Locality
-        ? d.locality
-        : new Locality(d.locality)
-      : null;
-    this.link = d.link ?? null;
-    this.original = d.original ?? null;
-    this.customLocality = d.custom_locality ?? d.customLocality ?? null;
-  }
-
-  override toString(): string {
-    return this.ref ? this.ref.toString() : '';
-  }
-
-  override toJSON(): CitationJson {
-    const obj: CitationJson = {};
-    if (this.ref != null) obj.ref = this.ref.toJSON();
-    if (this.locality != null) obj.locality = this.locality.toJSON();
-    if (this.link != null) obj.link = this.link;
-    if (this.original != null) obj.original = this.original;
-    if (this.customLocality != null) obj.custom_locality = this.customLocality;
-    return obj;
-  }
-
-  static override fromJSON(data: CitationJson): Citation {
-    return new Citation(data);
-  }
-}

package/src/models/concept-date.ts

@@ -1,48 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export type ConceptDateType = 'accepted' | 'amended' | 'retired' | string;
-
-export const DATE_TYPES: ReadonlyArray<string> = Object.freeze([
-  'accepted',
-  'amended',
-  'retired',
-]);
-
-export interface ConceptDateJson {
-  date?: string | null;
-  type?: ConceptDateType | null;
-}
-
-export class ConceptDate extends GlossaristModel {
-  readonly date: string | null;
-  readonly type: ConceptDateType | null;
-
-  constructor(data: ConceptDateJson = {}) {
-    super();
-    this.date = data.date ?? null;
-    this.type = data.type ?? null;
-  }
-
-  get parsedDate(): Date | null {
-    return this.date ? new Date(this.date) : null;
-  }
-
-  static identityOf(value: { type?: ConceptDateType | null } | null | undefined): string {
-    return value?.type ?? '';
-  }
-
-  override identity(): string {
-    return ConceptDate.identityOf(this);
-  }
-
-  override toJSON(): ConceptDateJson {
-    const obj: ConceptDateJson = {};
-    if (this.date != null) obj.date = this.date;
-    if (this.type != null) obj.type = this.type;
-    return obj;
-  }
-
-  static override fromJSON(data: ConceptDateJson): ConceptDate {
-    return new ConceptDate(data);
-  }
-}

package/src/models/concept-ref.ts

@@ -1,64 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-/**
- * Wire shape for ConceptRef. All three fields are optional on input
- * (any one is enough to identify a concept; usually source+id pair).
- * `text` is a free-form fallback for references that have no
- * machine-readable source.
- */
-export interface ConceptRefJson {
-  source?: string | null;
-  id?: string | null;
-  text?: string | null;
-}
-
-/**
- * ConceptRef — a reference to a concept by (source, id) pair, or by
- * free-form text when no machine-readable source exists.
- *
- * Identity: `${source ?? ''}|${id ?? ''}`. Two refs with the same
- * (source, id) are equal regardless of `text`.
- */
-export class ConceptRef extends GlossaristModel {
-  readonly source: string | null;
-  readonly id: string | null;
-  readonly text: string | null;
-
-  constructor(data: ConceptRefJson = {}) {
-    super();
-    this.source = data.source ?? null;
-    this.id = data.id ?? null;
-    this.text = data.text ?? null;
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    const base = parts.join(' ');
-    if (this.text && base) return `${base} (${this.text})`;
-    if (this.text) return this.text;
-    return base;
-  }
-
-  override toJSON(): ConceptRefJson {
-    const obj: ConceptRefJson = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.text != null) obj.text = this.text;
-    return obj;
-  }
-
-  override identity(): string {
-    return `${this.source ?? ''}|${this.id ?? ''}`;
-  }
-
-  static override fromJSON(data: ConceptRefJson): ConceptRef {
-    return new ConceptRef(data);
-  }
-
-  /** Convenience constructor for the common `(source, id)` form. */
-  static fromPair(source: string, id: string): ConceptRef {
-    return new ConceptRef({ source, id });
-  }
-}

package/src/models/concept-reference.ts

@@ -1,50 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export interface ConceptReferenceJson {
-  concept_id?: string | null;
-  conceptId?: string | null;
-  ref_type?: string | null;
-  refType?: string | null;
-  source?: string | null;
-  urn?: string | null;
-}
-
-export class ConceptReference extends GlossaristModel {
-  readonly conceptId: string | null;
-  readonly refType: string | null;
-  readonly source: string | null;
-  readonly urn: string | null;
-
-  constructor(data: ConceptReferenceJson = {}) {
-    super();
-    this.conceptId = data.concept_id ?? data.conceptId ?? null;
-    this.refType = data.ref_type ?? data.refType ?? null;
-    this.source = data.source ?? null;
-    this.urn = data.urn ?? null;
-  }
-
-  get isLocal(): boolean {
-    return this.urn == null && this.source == null;
-  }
-
-  get isExternal(): boolean {
-    return !this.isLocal;
-  }
-
-  static domain(conceptId: string): ConceptReference {
-    return new ConceptReference({ concept_id: conceptId, ref_type: 'domain' });
-  }
-
-  override toJSON(): ConceptReferenceJson {
-    const obj: ConceptReferenceJson = {};
-    if (this.conceptId != null) obj.concept_id = this.conceptId;
-    if (this.refType != null) obj.ref_type = this.refType;
-    if (this.source != null) obj.source = this.source;
-    if (this.urn != null) obj.urn = this.urn;
-    return obj;
-  }
-
-  static override fromJSON(data: ConceptReferenceJson): ConceptReference {
-    return new ConceptReference(data);
-  }
-}