glossarist 0.4.35 → 0.4.37

package/src/models/concept-system.ts

@@ -0,0 +1,152 @@
+// ConceptSystem — first-class concept system entity per ISO 12620 A.7.
+//
+// Promotes the previously-implicit concept system (domains + tags +
+// relation graph) to an explicit first-class entity. Per-file at
+// `concept-systems/<id>.yaml`.
+//
+// See docs/design/concept-systems.md (concept-model repo).
+
+import { GlossaristModel } from './base.js';
+import { ConceptRef } from './concept-ref.js';
+import {
+  CONCEPT_SYSTEM_TYPE,
+  CONCEPT_SYSTEM_TYPE_VALUES,
+  isValidConceptSystemType,
+} from './concept-system-type.js';
+import type { LocalizedString } from './generic-member.js';
+
+export interface ConceptSystemJson {
+  id: string;
+  name: LocalizedString;
+  type: string;
+  domain?: string | null;
+  purpose?: LocalizedString | null;
+  members: ReadonlyArray<unknown>;
+  hyperedges?: ReadonlyArray<unknown>;
+  rootConcepts?: ReadonlyArray<unknown>;
+  sources?: ReadonlyArray<unknown>;
+  status?: string | null;
+}
+
+export type ConceptSystemType = string;
+
+export class ConceptSystem extends GlossaristModel {
+  readonly id: string;
+  readonly name: LocalizedString;
+  readonly type: ConceptSystemType;
+  readonly domain: string | null;
+  readonly purpose: LocalizedString | null;
+  readonly members: ReadonlyArray<ConceptRef>;
+  readonly hyperedges: ReadonlyArray<unknown>;
+  readonly rootConcepts: ReadonlyArray<ConceptRef>;
+  readonly sources: ReadonlyArray<unknown>;
+  readonly status: string | null;
+
+  constructor(data: Partial<ConceptSystemJson> = {}) {
+    super();
+    this.id = _ensureNonEmptyString(data.id, 'id');
+    this.name = _ensureName(data.name);
+    this.type = _resolveType(data.type);
+    this.domain = data.domain ?? null;
+    this.purpose = data.purpose ?? null;
+    this.members = _ensureMembers(data.members);
+    this.hyperedges = Array.isArray(data.hyperedges) ? [...data.hyperedges] : [];
+    this.rootConcepts = Array.isArray(data.rootConcepts)
+      ? data.rootConcepts.map((c) =>
+          c instanceof ConceptRef ? c : new ConceptRef(c as { source?: string; id?: string; text?: string }),
+        )
+      : [];
+    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
+    this.status = data.status ?? null;
+  }
+
+  get isGeneric(): boolean     { return this.type === CONCEPT_SYSTEM_TYPE.GENERIC; }
+  get isPartitive(): boolean   { return this.type === CONCEPT_SYSTEM_TYPE.PARTITIVE; }
+  get isSequential(): boolean  { return this.type === CONCEPT_SYSTEM_TYPE.SEQUENTIAL; }
+  get isAssociative(): boolean { return this.type === CONCEPT_SYSTEM_TYPE.ASSOCIATIVE; }
+  get isMixed(): boolean       { return this.type === CONCEPT_SYSTEM_TYPE.MIXED; }
+
+  hasHyperedge(edgeId: string): boolean {
+    return (this.hyperedges as ReadonlyArray<string>).includes(edgeId);
+  }
+
+  hasMember(refOrUri: string | { source?: string | null; id?: string | null } | null | undefined): boolean {
+    const uri = typeof refOrUri === 'string' ? refOrUri : _refUri(refOrUri);
+    return this.members.some((m) => _refUri(m) === uri);
+  }
+
+  override identity(): string {
+    return this.id;
+  }
+
+  override toJSON(): ConceptSystemJson {
+    const obj: ConceptSystemJson = {
+      id: this.id,
+      name: { ...this.name },
+      type: this.type,
+      members: this.members.map((m) => m.toJSON()),
+    };
+    if (this.domain != null) obj.domain = this.domain;
+    if (this.purpose != null) obj.purpose = { ...this.purpose };
+    if (this.hyperedges.length > 0) obj.hyperedges = [...this.hyperedges];
+    if (this.rootConcepts.length > 0) obj.rootConcepts = this.rootConcepts.map((c) => c.toJSON());
+    if (this.sources.length > 0) obj.sources = [...this.sources];
+    if (this.status != null) obj.status = this.status;
+    return obj;
+  }
+
+  static override fromJSON(data: ConceptSystemJson): ConceptSystem {
+    return new ConceptSystem(data);
+  }
+}
+
+function _ensureNonEmptyString(value: unknown, fieldName: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`ConceptSystem#${fieldName} must be a non-empty string`);
+  }
+  return value;
+}
+
+function _ensureName(value: LocalizedString | null | undefined): LocalizedString {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('ConceptSystem#name must be a localized object (e.g. { eng: "..." })');
+  }
+  return { ...value };
+}
+
+function _resolveType(value: unknown): ConceptSystemType {
+  if (value == null) {
+    throw new Error(
+      'ConceptSystem#type is required; one of ' +
+      CONCEPT_SYSTEM_TYPE_VALUES.join(', '),
+    );
+  }
+  if (!isValidConceptSystemType(value)) {
+    throw new Error(
+      `ConceptSystem#type ${JSON.stringify(value)} invalid; ` +
+      `must be one of: ${CONCEPT_SYSTEM_TYPE_VALUES.join(', ')}`,
+    );
+  }
+  return value;
+}
+
+function _ensureMembers(values: ReadonlyArray<unknown> | null | undefined): ReadonlyArray<ConceptRef> {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error('ConceptSystem#members must be a non-empty array');
+  }
+  return values.map((v) =>
+    v instanceof ConceptRef
+      ? v
+      : new ConceptRef(v as { source?: string; id?: string; text?: string }),
+  );
+}
+
+function _refUri(
+  ref: { ref?: { source?: string | null; id?: string | null } | null; source?: string | null; id?: string | null } | null | undefined,
+): string {
+  const inner = ref?.ref ?? ref ?? {};
+  return `${inner.source ?? ''}:${inner.id ?? ''}`;
+}
+
+export default ConceptSystem;

package/src/models/concept-type.ts

@@ -0,0 +1,33 @@
+// ConceptType — ISO 704:2022 §5.2-5.3 general vs individual concept.
+//
+//   general    — concept corresponds to a category of objects
+//                (designated by terms or symbols)
+//   individual — concept corresponds to a unique object
+//                (designated by proper names / appellations)
+//
+// Individual concepts occupy the bottom rung of a concept ladder
+// and cannot be subdivided into more specific concepts, but CAN be
+// subdivided into parts via a partitive relation.
+
+export type ConceptType = 'general' | 'individual';
+
+export const CONCEPT_TYPE: Readonly<Record<'GENERAL' | 'INDIVIDUAL', ConceptType>> =
+  Object.freeze({
+    GENERAL: 'general',
+    INDIVIDUAL: 'individual',
+  });
+
+export const CONCEPT_TYPE_VALUES: ReadonlyArray<ConceptType> = Object.freeze(
+  Object.values(CONCEPT_TYPE),
+);
+
+export const DEFAULT_CONCEPT_TYPE: ConceptType = CONCEPT_TYPE.GENERAL;
+
+export function isValidConceptType(value: unknown): value is ConceptType {
+  return (
+    typeof value === 'string' &&
+    (CONCEPT_TYPE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+export default CONCEPT_TYPE;

package/src/models/{dataset-color.js → dataset-color.ts}

@@ -5,27 +5,34 @@
 //   - an explicit { light, dark } pair
 //
 // Round-trips through Register.toJSON unchanged so the data lives in
-// the GCR package. Consumers call resolvedColor(mode) to pick the
+// the GCR package. Consumers call resolveColor(mode) to pick the
 // right hex for the current UI mode.
 
-/**
- * @typedef {string} DatasetColorSpec
- * @typedef {{ light: string, dark: string }} DatasetColorPair
- * @typedef {DatasetColorSpec | DatasetColorPair} DatasetColor
- */
+export type ColorMode = 'light' | 'dark';
 
-export const COLOR_MODES = Object.freeze(['light', 'dark']);
+export type DatasetColorSpec = string;
+
+export interface DatasetColorPair {
+  light?: string;
+  dark?: string;
+}
+
+export type DatasetColor = DatasetColorSpec | DatasetColorPair;
+
+export const COLOR_MODES: ReadonlyArray<ColorMode> = Object.freeze([
+  'light',
+  'dark',
+]);
 
 /**
  * Returns the right hex for the given mode. Falls back to the single
  * hex when the spec is a string. Returns null when the spec is null
  * or when the requested mode is missing from a pair.
- *
- * @param {DatasetColor | null | undefined} color
- * @param {'light' | 'dark'} mode
- * @returns {string | null}
  */
-export function resolveColor(color, mode) {
+export function resolveColor(
+  color: DatasetColor | null | undefined,
+  mode: ColorMode,
+): string | null {
   if (color == null) return null;
   if (typeof color === 'string') return color;
   if (typeof color === 'object') {
@@ -37,10 +44,10 @@ export function resolveColor(color, mode) {
 
 /**
  * True when the spec declares an explicit {light, dark} object.
- * Lets callers distinguish "single hex" from "per-mode pair" without
- * repeating the typeof check.
  */
-export function isColorPair(color) {
+export function isColorPair(
+  color: DatasetColor | null | undefined,
+): color is DatasetColorPair {
   return color != null && typeof color === 'object';
 }
 
@@ -52,7 +59,9 @@ export function isColorPair(color) {
  *
  * Returns null when valid, or an error message describing the issue.
  */
-export function validateColor(color) {
+export function validateColor(
+  color: DatasetColor | null | undefined,
+): string | null {
   if (color == null) return null;
   if (typeof color === 'string') return hexError(color);
   if (typeof color === 'object') {
@@ -73,7 +82,7 @@ export function validateColor(color) {
 }
 
 const HEX_RE = /^#[0-9a-fA-F]{3,8}$/;
-function hexError(s) {
+function hexError(s: unknown): string | null {
   if (typeof s !== 'string') return `expected string, got ${typeof s}`;
   return HEX_RE.test(s) ? null : `not a valid hex color: ${JSON.stringify(s)}`;
 }

package/src/models/{definition-type.js → definition-type.ts}

@@ -7,6 +7,12 @@
 
 import { makeEnum } from './enum.js';
 
+export type DefinitionType =
+  | 'intensional'
+  | 'extensional'
+  | 'partitive'
+  | 'translated';
+
 export const DEFINITION_TYPE = makeEnum('DEFINITION_TYPE', {
   INTENSIONAL: 'intensional',
   EXTENSIONAL: 'extensional',
@@ -14,4 +20,5 @@ export const DEFINITION_TYPE = makeEnum('DEFINITION_TYPE', {
   TRANSLATED: 'translated',
 });
 
-export const DEFAULT_DEFINITION_TYPE = DEFINITION_TYPE.INTENSIONAL;
+export const DEFAULT_DEFINITION_TYPE: DefinitionType =
+  DEFINITION_TYPE.INTENSIONAL;

package/src/models/enum.ts

@@ -0,0 +1,60 @@
+// Enum factory — produces a frozen KEY/VALUES bundle, a frozen values
+// array, and an isValid predicate from a single `makeEnum` call.
+//
+// Adding a new enum means one line:
+//
+//   export const COLOR = makeEnum('COLOR', { RED: 'red', BLUE: 'blue' });
+//
+// The factory returns an object that exposes both the per-value
+// constants (COLOR.RED, COLOR.BLUE) and the VALUES list + isValid
+// predicate. The bundle is itself frozen.
+
+/**
+ * Output of {@link makeEnum}. Captures both the original key→value
+ * pairs (so `MY_ENUM.MY_KEY` is the literal string value) and the
+ * helper properties (`name`, `VALUES`, `isValid`).
+ */
+export type EnumBundle<TValues extends Readonly<Record<string, string>>> = {
+  readonly name: string;
+  readonly VALUES: ReadonlyArray<TValues[keyof TValues]>;
+  readonly isValid: (value: unknown) => value is TValues[keyof TValues];
+} & { readonly [K in keyof TValues]: TValues[K] };
+
+/**
+ * Build a frozen enum bundle.
+ *
+ * @param name Human-readable name used in error messages.
+ * @param values Object whose keys are the constant names and whose
+ *   string values are the wire representations.
+ */
+export function makeEnum<const TValues extends Readonly<Record<string, string>>>(
+  name: string,
+  values: TValues,
+): EnumBundle<TValues> {
+  if (typeof name !== 'string') {
+    throw new Error(`makeEnum: name must be a string, got ${typeof name}`);
+  }
+  if (typeof values !== 'object' || values === null) {
+    throw new Error(`makeEnum: values must be an object, got ${typeof values}`);
+  }
+  for (const [k, v] of Object.entries(values)) {
+    if (typeof v !== 'string') {
+      throw new Error(
+        `makeEnum(${name}): value for ${k} must be a string, got ${typeof v}`,
+      );
+    }
+  }
+
+  const frozen = Object.freeze({ ...values });
+  const valuesArr = Object.freeze(Object.values(frozen)) as ReadonlyArray<
+    TValues[keyof TValues]
+  >;
+  const isValid = (v: unknown): v is TValues[keyof TValues] =>
+    typeof v === 'string' && (valuesArr as readonly string[]).includes(v);
+
+  return Object.assign(Object.create(null) as object, frozen, {
+    name,
+    VALUES: valuesArr,
+    isValid,
+  }) as EnumBundle<TValues>;
+}

package/src/models/equivalence-degree.ts

@@ -0,0 +1,34 @@
+// EquivalenceDegree — ISO 704:2022 §7.7.3 cross-language equivalence.
+//
+//   full        — equivalent intension across languages (default)
+//   partial     — overlapping but not identical intension
+//   none        — no corresponding concept in this language
+//   directional — monodirectional equivalence (see equivalence_note)
+
+export type EquivalenceDegree =
+  | 'full'
+  | 'partial'
+  | 'none'
+  | 'directional';
+
+export const EQUIVALENCE_DEGREE: Readonly<Record<Uppercase<EquivalenceDegree>, EquivalenceDegree>> = Object.freeze({
+  FULL: 'full',
+  PARTIAL: 'partial',
+  NONE: 'none',
+  DIRECTIONAL: 'directional',
+});
+
+export const EQUIVALENCE_DEGREE_VALUES: ReadonlyArray<EquivalenceDegree> =
+  Object.freeze(Object.values(EQUIVALENCE_DEGREE));
+
+export const DEFAULT_EQUIVALENCE_DEGREE: EquivalenceDegree =
+  EQUIVALENCE_DEGREE.FULL;
+
+export function isValidEquivalenceDegree(value: unknown): value is EquivalenceDegree {
+  return (
+    typeof value === 'string' &&
+    (EQUIVALENCE_DEGREE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+export default EQUIVALENCE_DEGREE;

package/src/models/generic-hyperedge.ts

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

@@ -0,0 +1,80 @@
+// 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/{hyperedge-index.js → hyperedge-index.ts}

@@ -15,11 +15,19 @@
 //
 // Identity key matches HyperedgeRegistry / ConceptRef conventions:
 //   `${source}:${id}`   (empty source or id is rejected)
-//
-// See TODO Phase 9.
+
+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 {
-  constructor(hyperedges = []) {
+  private readonly _byComprehensive: Map<string, HyperedgeLike[]>;
+  private readonly _byMember: Map<string, HyperedgeLike[]>;
+
+  constructor(hyperedges: ReadonlyArray<HyperedgeLike> = []) {
     this._byComprehensive = new Map();
     this._byMember = new Map();
 
@@ -35,45 +43,51 @@ export class HyperedgeIndex {
   }
 
   // Hyperedges where the given concept is the comprehensive (the "1" side).
-  forComprehensive(qualifiedId) {
+  forComprehensive(qualifiedId: string): HyperedgeLike[] {
     return this._byComprehensive.get(qualifiedId) ?? [];
   }
 
   // Hyperedges where the given concept appears as a member (the "many" side).
-  forMember(qualifiedId) {
+  forMember(qualifiedId: string): HyperedgeLike[] {
     return this._byMember.get(qualifiedId) ?? [];
   }
 
   // All concepts that appear as a comprehensive in any indexed hyperedge.
-  comprehensives() {
+  comprehensives(): string[] {
     return [...this._byComprehensive.keys()];
   }
 
   // All concepts that appear as a member in any indexed hyperedge.
-  members() {
+  members(): string[] {
     return [...this._byMember.keys()];
   }
 
-  get size() {
+  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 = []) {
-  const all = [];
+/**
+ * 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);
+      all.push(h as HyperedgeLike);
     }
   }
   return new HyperedgeIndex(all);
 }
 
-function _qualifiedId(ref) {
+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 ?? '';
@@ -81,7 +95,7 @@ function _qualifiedId(ref) {
   return `${source}:${id}`;
 }
 
-function _addToMapList(map, key, value) {
+function _addToMapList<T>(map: Map<string, T[]>, key: string, value: T): void {
   if (!map.has(key)) map.set(key, []);
-  map.get(key).push(value);
+  map.get(key)?.push(value);
 }