glossarist 0.4.38 → 0.4.40

package/src/models/gcr-metadata.ts

@@ -0,0 +1,118 @@
+import * as yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { GcrStatistics } from './gcr-statistics.js';
+import type { GcrStatisticsJson } from './gcr-statistics.js';
+
+export interface GcrMetadataJson {
+  shortname?: string | null;
+  version?: string | null;
+  title?: string | null;
+  description?: string | null;
+  owner?: string | null;
+  tags?: ReadonlyArray<string>;
+  concept_count?: number;
+  conceptCount?: number;
+  languages?: ReadonlyArray<string>;
+  created_at?: string | null;
+  createdAt?: string | null;
+  glossarist_version?: string | null;
+  glossaristVersion?: string | null;
+  schema_version?: string;
+  schemaVersion?: string;
+  homepage?: string | null;
+  repository?: string | null;
+  license?: string | null;
+  uri_prefix?: string | null;
+  uriPrefix?: string | null;
+  concept_uri_template?: string | null;
+  conceptUriTemplate?: string | null;
+  compiled_formats?: ReadonlyArray<string>;
+  compiledFormats?: ReadonlyArray<string>;
+  statistics?: GcrStatisticsJson | GcrStatistics | null;
+}
+
+export class GcrMetadata extends GlossaristModel {
+  readonly shortname: string | null;
+  readonly version: string | null;
+  readonly title: string | null;
+  readonly description: string | null;
+  readonly owner: string | null;
+  readonly tags: ReadonlyArray<string>;
+  readonly conceptCount: number;
+  readonly languages: ReadonlyArray<string>;
+  readonly createdAt: string | null;
+  readonly glossaristVersion: string | null;
+  readonly schemaVersion: string;
+  readonly homepage: string | null;
+  readonly repository: string | null;
+  readonly license: string | null;
+  readonly uriPrefix: string | null;
+  readonly conceptUriTemplate: string | null;
+  readonly compiledFormats: ReadonlyArray<string>;
+  readonly statistics: GcrStatistics | null;
+
+  constructor(data: GcrMetadataJson = {}) {
+    super();
+    this.shortname = data.shortname ?? null;
+    this.version = data.version ?? null;
+    this.title = data.title ?? null;
+    this.description = data.description ?? null;
+    this.owner = data.owner ?? null;
+    this.tags = (data.tags as ReadonlyArray<string>) ?? [];
+    this.conceptCount = data.concept_count ?? data.conceptCount ?? 0;
+    this.languages = (data.languages as ReadonlyArray<string>) ?? [];
+    this.createdAt = data.created_at ?? data.createdAt ?? null;
+    this.glossaristVersion = data.glossarist_version ?? data.glossaristVersion ?? null;
+    this.schemaVersion = data.schema_version ?? data.schemaVersion ?? '1';
+    this.homepage = data.homepage ?? null;
+    this.repository = data.repository ?? null;
+    this.license = data.license ?? null;
+    this.uriPrefix = data.uri_prefix ?? data.uriPrefix ?? null;
+    this.conceptUriTemplate = data.concept_uri_template ?? data.conceptUriTemplate ?? null;
+    this.compiledFormats = data.compiled_formats ?? data.compiledFormats ?? [];
+    this.statistics = data.statistics
+      ? data.statistics instanceof GcrStatistics
+        ? data.statistics
+        : new GcrStatistics(data.statistics as GcrStatisticsJson)
+      : null;
+  }
+
+  get concept_count(): number { return this.conceptCount; }
+  get created_at(): string | null { return this.createdAt; }
+  get glossarist_version(): string | null { return this.glossaristVersion; }
+  get schema_version(): string { return this.schemaVersion; }
+  get uri_prefix(): string | null { return this.uriPrefix; }
+  get concept_uri_template(): string | null { return this.conceptUriTemplate; }
+  get compiled_formats(): ReadonlyArray<string> { return this.compiledFormats; }
+
+  override toJSON(): GcrMetadataJson {
+    const obj: GcrMetadataJson = {};
+    if (this.shortname != null) obj.shortname = this.shortname;
+    if (this.version != null) obj.version = this.version;
+    if (this.title != null) obj.title = this.title;
+    if (this.description != null) obj.description = this.description;
+    if (this.owner != null) obj.owner = this.owner;
+    if (this.tags.length > 0) obj.tags = [...this.tags];
+    if (this.conceptCount > 0) obj.concept_count = this.conceptCount;
+    if (this.languages.length > 0) obj.languages = [...this.languages];
+    if (this.createdAt != null) obj.created_at = this.createdAt;
+    if (this.glossaristVersion != null) obj.glossarist_version = this.glossaristVersion;
+    if (this.schemaVersion != null) obj.schema_version = this.schemaVersion;
+    if (this.homepage != null) obj.homepage = this.homepage;
+    if (this.repository != null) obj.repository = this.repository;
+    if (this.license != null) obj.license = this.license;
+    if (this.uriPrefix != null) obj.uri_prefix = this.uriPrefix;
+    if (this.conceptUriTemplate != null) obj.concept_uri_template = this.conceptUriTemplate;
+    if (this.compiledFormats.length > 0) obj.compiled_formats = [...this.compiledFormats];
+    if (this.statistics != null) obj.statistics = this.statistics.toJSON();
+    return obj;
+  }
+
+  static override fromJSON(data: GcrMetadataJson): GcrMetadata {
+    return new GcrMetadata(data);
+  }
+
+  static fromYaml(yamlString: string): GcrMetadata {
+    return new GcrMetadata(yaml.load(yamlString) as GcrMetadataJson);
+  }
+}

package/src/models/gcr-statistics.ts

@@ -0,0 +1,76 @@
+import { GlossaristModel } from './base.js';
+
+export interface GcrStatisticsJson {
+  total_concepts?: number;
+  totalConcepts?: number;
+  concepts_with_definitions?: number;
+  conceptsWithDefinitions?: number;
+  concepts_by_status?: Record<string, number>;
+  conceptsByStatus?: Record<string, number>;
+}
+
+interface ConceptLike {
+  languages: ReadonlyArray<string>;
+  localization(lang: string): {
+    definitions: ReadonlyArray<unknown>;
+    entryStatus?: string | null;
+  } | null | undefined;
+}
+
+export class GcrStatistics extends GlossaristModel {
+  readonly totalConcepts: number;
+  readonly conceptsWithDefinitions: number;
+  readonly conceptsByStatus: Record<string, number>;
+
+  constructor(data: GcrStatisticsJson = {}) {
+    super();
+    this.totalConcepts = data.total_concepts ?? data.totalConcepts ?? 0;
+    this.conceptsWithDefinitions =
+      data.concepts_with_definitions ?? data.conceptsWithDefinitions ?? 0;
+    this.conceptsByStatus =
+      (data.concepts_by_status as Record<string, number>) ??
+      (data.conceptsByStatus as Record<string, number>) ??
+      {};
+  }
+
+  get total_concepts(): number { return this.totalConcepts; }
+  get concepts_with_definitions(): number { return this.conceptsWithDefinitions; }
+  get concepts_by_status(): Record<string, number> { return this.conceptsByStatus; }
+
+  override toJSON(): GcrStatisticsJson {
+    const obj: GcrStatisticsJson = { total_concepts: this.totalConcepts };
+    if (this.conceptsWithDefinitions > 0) {
+      obj.concepts_with_definitions = this.conceptsWithDefinitions;
+    }
+    if (Object.keys(this.conceptsByStatus).length > 0) {
+      obj.concepts_by_status = this.conceptsByStatus;
+    }
+    return obj;
+  }
+
+  static override fromJSON(data: GcrStatisticsJson): GcrStatistics {
+    return new GcrStatistics(data);
+  }
+
+  static fromConcepts(concepts: ReadonlyArray<ConceptLike>): GcrStatistics {
+    const langs = new Set<string>();
+    let withDefs = 0;
+    const byStatus: Record<string, number> = {};
+
+    for (const concept of concepts) {
+      for (const lang of concept.languages) {
+        langs.add(lang);
+        const lc = concept.localization(lang);
+        if (lc && lc.definitions.length > 0) withDefs++;
+        const status = lc?.entryStatus ?? 'unknown';
+        byStatus[status] = (byStatus[status] ?? 0) + 1;
+      }
+    }
+
+    return new GcrStatistics({
+      total_concepts: concepts.length,
+      concepts_with_definitions: withDefs,
+      concepts_by_status: byStatus,
+    });
+  }
+}

package/src/models/hyperedge-colors.ts

@@ -0,0 +1,87 @@
+// Hyperedge color resolver — resolves display colors for a
+// PartitiveHyperedge based on its enumeration and the carrying
+// concept's category color.
+
+import { categoryColorPair } from './relation-colors.js';
+import type { ColorPair } from './relation-colors.js';
+
+const ENUMERATION_INTENSITY: Readonly<Record<string, number>> = Object.freeze({
+  closed: 1.0,
+  open: 0.55,
+});
+
+const DEFAULT_CATEGORY = 'hierarchical';
+
+export interface ResolveHyperedgeColorOptions {
+  category?: string;
+  overrides?: { byCategory?: Record<string, Partial<ColorPair>> };
+}
+
+export interface ResolvedHyperedgeColor {
+  light: string;
+  dark: string;
+  pattern: 'dashed' | 'double' | null;
+}
+
+interface HyperedgeLike {
+  enumeration?: string;
+  markers?: ReadonlyArray<string>;
+}
+
+export function resolveHyperedgeColor(
+  hyperedge: HyperedgeLike | null,
+  options: ResolveHyperedgeColorOptions = {},
+): ResolvedHyperedgeColor | null {
+  if (!hyperedge) return null;
+
+  const category = options.category ?? DEFAULT_CATEGORY;
+  const base = categoryColorPair(category, options.overrides);
+  if (!base) return null;
+
+  const intensity = ENUMERATION_INTENSITY[hyperedge.enumeration ?? ''] ?? 1.0;
+  const pattern = derivePattern(hyperedge.markers);
+
+  return {
+    light: tint(base.light, intensity),
+    dark: tint(base.dark, intensity),
+    pattern,
+  };
+}
+
+function derivePattern(
+  markers: ReadonlyArray<string> | null | undefined,
+): 'dashed' | 'double' | null {
+  const arr = markers ?? [];
+  if (arr.includes('dashed')) return 'dashed';
+  if (arr.includes('double')) return 'double';
+  return null;
+}
+
+/**
+ * Linear interpolation between the base color and white (light mode)
+ * or between the base and a neutral (dark mode). Pure-string inputs
+ * return the original color when intensity === 1.0.
+ */
+function tint(hex: string, ratio: number): string {
+  if (ratio >= 1.0) return hex;
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+
+  const target: ReadonlyArray<number> = [255, 255, 255];
+  const mixed = rgb.map((c, i) =>
+    Math.round(c + ((target[i] ?? 255) - c) * (1 - ratio)),
+  );
+  return '#' + mixed.map((c) => c.toString(16).padStart(2, '0')).join('');
+}
+
+function parseHex(s: string): [number, number, number] | null {
+  if (typeof s !== 'string') return null;
+  const m = s.match(/^#?([0-9a-f]{6})$/i);
+  if (!m) return null;
+  const n = m[1] as string;
+  return [
+    parseInt(n.slice(0, 2), 16),
+    parseInt(n.slice(2, 4), 16),
+    parseInt(n.slice(4, 6), 16),
+  ];
+}

package/src/models/non-verb-rep.ts

@@ -0,0 +1,48 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import type { NonVerbalEntityJson } from './non-verbal-entity.js';
+import { FigureImage } from './figure.js';
+import type { FigureImageJson } from './figure.js';
+
+export const NON_VERBAL_TYPES: ReadonlyArray<string> = Object.freeze([
+  'image', 'table', 'formula',
+]);
+
+export interface NonVerbRepJson extends NonVerbalEntityJson {
+  type?: string | null;
+  images?: ReadonlyArray<FigureImageJson | FigureImage>;
+}
+
+export class NonVerbRep extends NonVerbalEntity {
+  readonly type: string | null;
+  protected readonly _rawImages: ReadonlyArray<FigureImageJson | FigureImage>;
+  protected _images: ReadonlyArray<FigureImage> | null = null;
+
+  constructor(data: NonVerbRepJson = {}) {
+    super(data);
+    this.type = data.type ?? null;
+    this._rawImages = data.images ?? [];
+  }
+
+  override rdfClass(): string {
+    return 'NonVerbalRepresentation';
+  }
+
+  get images(): ReadonlyArray<FigureImage> {
+    return this._lazy<FigureImage>(
+      '_images',
+      '_rawImages',
+      (i) => (i instanceof FigureImage ? i : new FigureImage(i as FigureImageJson)),
+    );
+  }
+
+  override toJSON(): NonVerbRepJson {
+    const obj = super.toJSON() as NonVerbRepJson;
+    if (this.type != null) obj.type = this.type;
+    this._serialize(obj as unknown as Record<string, unknown>, 'images', '_images', '_rawImages');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbRepJson): NonVerbRep {
+    return new NonVerbRep(data);
+  }
+}

package/src/models/non-verbal-entity.ts

@@ -0,0 +1,65 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+import type { ConceptSourceJson } from './concept-source.js';
+
+export interface NonVerbalEntityJson {
+  caption?: string | null;
+  description?: string | null;
+  alt?: string | null;
+  sources?: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  type?: string | null;
+}
+
+export class NonVerbalEntity extends RegistrableModel {
+  readonly caption: string | null;
+  readonly description: string | null;
+  readonly alt: string | null;
+  protected readonly _rawSources: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  protected _sources: ReadonlyArray<ConceptSource> | null = null;
+
+  constructor(data: NonVerbalEntityJson = {}) {
+    super();
+    this.caption = data.caption ?? null;
+    this.description = data.description ?? null;
+    this.alt = data.alt ?? null;
+    this._rawSources = data.sources ?? [];
+  }
+
+  get sources(): ReadonlyArray<ConceptSource> {
+    return this._lazy<ConceptSource>(
+      '_sources',
+      '_rawSources',
+      (s) => (s instanceof ConceptSource ? s : new ConceptSource(s as ConceptSourceJson)),
+    );
+  }
+
+  /**
+   * Ontology class local-name. Subtypes override to return their specific
+   * class (Figure/Table/Formula). Used by the RDF emitter so a new subtype
+   * registers without editing the emitter (OCP).
+   */
+  rdfClass(): string {
+    return 'NonVerbalEntity';
+  }
+
+  findById(_targetId: string): NonVerbalEntity | null {
+    return null;
+  }
+
+  allIds(): string[] {
+    return [];
+  }
+
+  override toJSON(): NonVerbalEntityJson {
+    const obj: NonVerbalEntityJson = {};
+    if (this.caption != null) obj.caption = this.caption;
+    if (this.description != null) obj.description = this.description;
+    if (this.alt != null) obj.alt = this.alt;
+    this._serialize(obj as unknown as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbalEntityJson): NonVerbalEntity {
+    return NonVerbalEntity.fromData(data);
+  }
+}

package/src/models/non-verbal-reference.ts

@@ -0,0 +1,73 @@
+import { RegistrableModel } from './registrable.js';
+
+export interface NonVerbalReferenceJson {
+  entityId?: string | null;
+  entity_id?: string | null;
+  ref?: string | null;
+  id?: string | null;
+  display?: string | null;
+  type?: string;
+}
+
+/**
+ * Polymorphic JSON for NonVerbalReference: either a bare string (the
+ * entity id) or an object with `{ ref, display?, type? }`.
+ */
+export type NonVerbalReferenceInput =
+  | NonVerbalReferenceJson
+  | string
+  | NonVerbalReference;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyCtor = new (...args: any[]) => any;
+
+export class NonVerbalReference extends RegistrableModel {
+  readonly entityId: string | null;
+  readonly display: string | null;
+
+  constructor(data: NonVerbalReferenceJson = {}) {
+    super();
+    this.entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    this.display = data.display ?? null;
+  }
+
+  get dedupKey(): [string, string | null] {
+    return [this.constructor.name, this.entityId];
+  }
+
+  override toJSON(): NonVerbalReferenceJson | string {
+    if (this.display != null) {
+      return { ref: this.entityId ?? '', display: this.display };
+    }
+    return this.entityId ?? '';
+  }
+
+  static override fromJSON<T extends NonVerbalReference>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this: new (...args: any[]) => T,
+    data: NonVerbalReferenceInput,
+  ): T | NonVerbalReference {
+    if (data instanceof NonVerbalReference) return data;
+    if (typeof data === 'string') {
+      return new (this as new (d: NonVerbalReferenceJson) => T)({ entityId: data });
+    }
+    const entityId =
+      data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    const display = data.display ?? null;
+    const type = data.type;
+    const Self = this as unknown as { _registry(): Map<string, AnyCtor> };
+    if (type) {
+      const Cls = Self._registry().get(type);
+      if (Cls) {
+        return new (Cls as new (d: NonVerbalReferenceJson) => T)({
+          entityId: entityId ?? undefined,
+          display: display ?? undefined,
+        });
+      }
+    }
+    return new (this as new (d: NonVerbalReferenceJson) => T)({
+      entityId: entityId ?? undefined,
+      display: display ?? undefined,
+    });
+  }
+}

package/src/models/non-verbal-references.ts

@@ -0,0 +1,29 @@
+import { NonVerbalReference } from './non-verbal-reference.js';
+import type { NonVerbalReferenceInput } from './non-verbal-reference.js';
+
+export class FigureReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FigureReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FigureReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('figure', FigureReference);
+
+export class TableReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): TableReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as TableReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('table', TableReference);
+
+export class FormulaReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FormulaReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FormulaReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('formula', FormulaReference);