glossarist 0.4.50 → 0.4.52

package/src/models/gcr-metadata.ts

@@ -1,118 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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/generic-hyperedge.ts

@@ -1,72 +0,0 @@
-// GenericHyperedge — an ISO 704 / ISO 1087-1 / ISO 12620 generic
-// relation connecting a comprehensive concept (the genus) to two
-// or more specific concepts (the species) which together constitute
-// a decomposition by some criterion of subdivision.
-//
-// Mirror of PartitiveHyperedge. Multiple GenericRelations on the same
-// comprehensive distinguished by `criterion` is the OIML pattern
-// (5.1 measurement standard has 6 criterion groups).
-//
-// See docs/design/generic-relation.md (concept-model repo).
-
-import { AbstractHyperedge } from './abstract-hyperedge.js';
-import type { AbstractHyperedgeJson } from './abstract-hyperedge.js';
-import { GenericMember } from './generic-member.js';
-import type { GenericMemberJson } from './generic-member.js';
-import { HyperedgeRegistry } from './hyperedge-registry.js';
-
-export interface GenericHyperedgeJson extends AbstractHyperedgeJson {
-  members: ReadonlyArray<GenericMemberJson | GenericMember>;
-}
-
-export class GenericHyperedge extends AbstractHyperedge {
-  // Per-class metadata block — the OCP contract.
-  static wireKey = 'generic_relations' as const;
-  static typeTag = 'generic_relation' as const;
-  static rdfType = 'gloss:GenericRelation' as const;
-  static memberClass = GenericMember;
-  static v1WireKeys: ReadonlyArray<string> = [];
-  static kindLabel = 'GEN';
-
-  declare readonly members: ReadonlyArray<GenericMember>;
-
-  constructor(data: Partial<GenericHyperedgeJson> = {}) {
-    super({
-      comprehensive: data.comprehensive ?? {},
-      members: data.members ?? [],
-      completeness: data.completeness ?? 'complete',
-      criterion: data.criterion,
-      sources: data.sources,
-      notes: data.notes,
-      status: data.status,
-    });
-    this.members = (Array.isArray(data.members) ? data.members : []).map((m) =>
-      m instanceof GenericMember ? m : new GenericMember(m as GenericMemberJson),
-    );
-  }
-
-  static identityOf(
-    value: {
-      comprehensive?: { source?: string | null; id?: string | null } | null;
-      members?: ReadonlyArray<{ ref?: { source?: string | null; id?: string | null } | null } | null>;
-    } | null | undefined,
-  ): string {
-    const v = value ?? {};
-    const c = v.comprehensive ?? {};
-    const memberKeys = (v.members ?? [])
-      .map((m) => {
-        const r = m?.ref ?? (m as { source?: string; id?: string } | null) ?? {};
-        return `${r.source ?? ''}:${r.id ?? ''}`;
-      })
-      .sort();
-    return `${c.source ?? ''}:${c.id ?? ''}|${memberKeys.join('|')}`;
-  }
-
-  static override fromJSON(data: GenericHyperedgeJson): GenericHyperedge {
-    return new GenericHyperedge(data);
-  }
-}
-
-export default GenericHyperedge;
-
-HyperedgeRegistry.register(GenericHyperedge);

package/src/models/generic-member.ts

@@ -1,80 +0,0 @@
-// GenericMember — one member of a GenericHyperedge.
-//
-// Per ISO 704:2022 §5.5.4.2.1 (Generic relations and general concepts):
-//
-//   "In a generic relation, the intension of the subordinate concept
-//    includes the intension of the superordinate concept plus at least
-//    one additional delimiting characteristic."
-//
-// See docs/design/abstract-hyperedge.md for the full rationale and
-// the computer-mouse worked example.
-
-import { HyperedgeMember } from './hyperedge-member.js';
-import type { HyperedgeMemberJson } from './hyperedge-member.js';
-
-export type LocalizedString = Readonly<Record<string, string>>;
-
-export interface GenericMemberJson extends HyperedgeMemberJson {
-  delimitingCharacteristic: LocalizedString | string;
-}
-
-export class GenericMember extends HyperedgeMember {
-  readonly delimitingCharacteristic: LocalizedString;
-
-  constructor(data: Partial<GenericMemberJson> = {}) {
-    // @ts-expect-error -- Partial<GenericMemberJson> defers the required
-    // delimitingCharacteristic check to _resolveDelimitingCharacteristic.
-    super(data);
-    this.delimitingCharacteristic = _resolveDelimitingCharacteristic(
-      data.delimitingCharacteristic,
-    );
-  }
-
-  override toJSON(): GenericMemberJson {
-    const base = super.toJSON() as GenericMemberJson;
-    base.delimitingCharacteristic = { ...this.delimitingCharacteristic };
-    return base;
-  }
-
-  static override fromJSON(data: GenericMemberJson): GenericMember {
-    return new GenericMember(data);
-  }
-}
-
-function _resolveDelimitingCharacteristic(
-  value: LocalizedString | string | null | undefined,
-): LocalizedString {
-  if (value == null) {
-    throw new Error(
-      'GenericMember.delimitingCharacteristic is required per ISO 704:2022 §5.5.4.2.1 ' +
-      '(the intension of a subordinate concept must include at least one additional ' +
-      'delimiting characteristic beyond the superordinate).',
-    );
-  }
-  if (typeof value === 'string') {
-    if (value.length === 0) {
-      throw new Error(
-        'GenericMember.delimitingCharacteristic cannot be empty (ISO 704:2022 §5.5.4.2.1)',
-      );
-    }
-    return { default: value };
-  }
-  if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(
-      ([, v]) => typeof v === 'string' && v.length > 0,
-    );
-    if (entries.length === 0) {
-      throw new Error(
-        'GenericMember.delimitingCharacteristic must have at least one non-empty string ' +
-        'value (ISO 704:2022 §5.5.4.2.1)',
-      );
-    }
-    return Object.fromEntries(entries) as LocalizedString;
-  }
-  throw new Error(
-    `GenericMember.delimitingCharacteristic must be a string or a language-keyed object; ` +
-    `got ${typeof value}`,
-  );
-}
-
-export default GenericMember;

package/src/models/grammar-info.ts

@@ -1,78 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export type GrammarGender = 'm' | 'f' | 'n' | 'c' | string;
-export type GrammarNumber = 'singular' | 'dual' | 'plural' | string;
-export type GrammarPartOfSpeech =
-  | 'noun'
-  | 'verb'
-  | 'adj'
-  | 'adverb'
-  | 'preposition'
-  | 'participle'
-  | string;
-
-export const GRAMMAR_GENDERS: ReadonlyArray<string> = Object.freeze([
-  'm', 'f', 'n', 'c',
-]);
-export const GRAMMAR_NUMBERS: ReadonlyArray<string> = Object.freeze([
-  'singular', 'dual', 'plural',
-]);
-export const GRAMMAR_PARTS_OF_SPEECH: ReadonlyArray<string> = Object.freeze([
-  'noun', 'verb', 'adj', 'adverb', 'preposition', 'participle',
-]);
-
-export interface GrammarInfoJson {
-  gender?: GrammarGender | null;
-  number?: GrammarNumber | null;
-  part_of_speech?: GrammarPartOfSpeech | null;
-  partOfSpeech?: GrammarPartOfSpeech | null;
-  noun?: boolean;
-  verb?: boolean;
-  adj?: boolean;
-  adverb?: boolean;
-  preposition?: boolean;
-  participle?: boolean;
-}
-
-export class GrammarInfo extends GlossaristModel {
-  readonly gender: GrammarGender | null;
-  readonly number: GrammarNumber | null;
-  readonly partOfSpeech: GrammarPartOfSpeech | null;
-  readonly noun: boolean;
-  readonly verb: boolean;
-  readonly adj: boolean;
-  readonly adverb: boolean;
-  readonly preposition: boolean;
-  readonly participle: boolean;
-
-  constructor(data: GrammarInfoJson = {}) {
-    super();
-    this.gender = data.gender ?? null;
-    this.number = data.number ?? null;
-    this.partOfSpeech = data.part_of_speech ?? data.partOfSpeech ?? null;
-    this.noun = data.noun ?? false;
-    this.verb = data.verb ?? false;
-    this.adj = data.adj ?? false;
-    this.adverb = data.adverb ?? false;
-    this.preposition = data.preposition ?? false;
-    this.participle = data.participle ?? false;
-  }
-
-  override toJSON(): GrammarInfoJson {
-    const obj: GrammarInfoJson = {};
-    if (this.gender != null) obj.gender = this.gender;
-    if (this.number != null) obj.number = this.number;
-    if (this.partOfSpeech != null) obj.part_of_speech = this.partOfSpeech;
-    if (this.noun) obj.noun = true;
-    if (this.verb) obj.verb = true;
-    if (this.adj) obj.adj = true;
-    if (this.adverb) obj.adverb = true;
-    if (this.preposition) obj.preposition = true;
-    if (this.participle) obj.participle = true;
-    return obj;
-  }
-
-  static override fromJSON(data: GrammarInfoJson): GrammarInfo {
-    return new GrammarInfo(data);
-  }
-}

package/src/models/hyperedge-colors.ts

@@ -1,87 +0,0 @@
-// 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/hyperedge-index.ts

@@ -1,101 +0,0 @@
-// HyperedgeIndex — directional index over a hyperedge set.
-//
-// A hyperedge is 1→N (one comprehensive, many members). The forward
-// query ("which hyperedges have X as comprehensive?") and the reverse
-// query ("which hyperedges have Y as a member?") are both useful. The
-// reverse query is the load-bearing one: OIML V 2-200:2010 concept
-// 5.13 is a member of one of 5.1's hyperedges AND the comprehensive
-// of its own 2 hyperedges — without an index, every "find hyperedges
-// mentioning X" turns into an O(N) walk over every hyperedge.
-//
-// The index is built on demand from a flat hyperedge list (typically
-// Concept.relations or the union of all concepts' relations in a
-// collection). It does not store state on Concept — Concept stays a
-// simple value object.
-//
-// Identity key matches HyperedgeRegistry / ConceptRef conventions:
-//   `${source}:${id}`   (empty source or id is rejected)
-
-import type { AbstractHyperedge } from './abstract-hyperedge.js';
-
-interface HyperedgeLike {
-  comprehensive?: { source?: string | null; id?: string | null } | null;
-  members?: ReadonlyArray<{ ref?: { source?: string | null; id?: string | null } | null }>;
-}
-
-export class HyperedgeIndex {
-  private readonly _byComprehensive: Map<string, HyperedgeLike[]>;
-  private readonly _byMember: Map<string, HyperedgeLike[]>;
-
-  constructor(hyperedges: ReadonlyArray<HyperedgeLike> = []) {
-    this._byComprehensive = new Map();
-    this._byMember = new Map();
-
-    for (const h of hyperedges) {
-      const cKey = _qualifiedId(h?.comprehensive);
-      if (cKey) _addToMapList(this._byComprehensive, cKey, h);
-      const members = Array.isArray(h?.members) ? h.members : [];
-      for (const m of members) {
-        const mKey = _qualifiedId(m?.ref ?? m);
-        if (mKey) _addToMapList(this._byMember, mKey, h);
-      }
-    }
-  }
-
-  // Hyperedges where the given concept is the comprehensive (the "1" side).
-  forComprehensive(qualifiedId: string): HyperedgeLike[] {
-    return this._byComprehensive.get(qualifiedId) ?? [];
-  }
-
-  // Hyperedges where the given concept appears as a member (the "many" side).
-  forMember(qualifiedId: string): HyperedgeLike[] {
-    return this._byMember.get(qualifiedId) ?? [];
-  }
-
-  // All concepts that appear as a comprehensive in any indexed hyperedge.
-  comprehensives(): string[] {
-    return [...this._byComprehensive.keys()];
-  }
-
-  // All concepts that appear as a member in any indexed hyperedge.
-  members(): string[] {
-    return [...this._byMember.keys()];
-  }
-
-  get size(): number {
-    return this._byComprehensive.size;
-  }
-}
-
-/**
- * Build a HyperedgeIndex across multiple Concepts' relations arrays
- * (a dataset-wide view). Each Concept contributes its own .relations.
- * Helper for the most common pattern: index once at collection load,
- * query many times.
- */
-export function buildDatasetIndex(
-  concepts: ReadonlyArray<{ relations?: ReadonlyArray<AbstractHyperedge | HyperedgeLike> }> = [],
-): HyperedgeIndex {
-  const all: HyperedgeLike[] = [];
-  for (const concept of concepts) {
-    for (const h of concept.relations ?? []) {
-      all.push(h as HyperedgeLike);
-    }
-  }
-  return new HyperedgeIndex(all);
-}
-
-function _qualifiedId(
-  ref: { source?: string | null; id?: string | null } | null | undefined,
-): string | null {
-  if (!ref) return null;
-  const source = ref.source ?? '';
-  const id = ref.id ?? '';
-  if (!source && !id) return null;
-  return `${source}:${id}`;
-}
-
-function _addToMapList<T>(map: Map<string, T[]>, key: string, value: T): void {
-  if (!map.has(key)) map.set(key, []);
-  map.get(key)?.push(value);
-}