glossarist 0.4.36 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.36",
+  "version": "0.4.37",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/models/abstract-hyperedge.ts

@@ -0,0 +1,164 @@
+// 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/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/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);
 }