glossarist 0.4.50 → 0.4.51

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);
-}

package/src/models/hyperedge-member.ts

@@ -1,121 +0,0 @@
-// HyperedgeMember — abstract base shape for the members of any directed
-// 1→N hyperedge (PartitiveMember, GenericMember, future AssociativeMember,
-// SequentialMember).
-//
-// Carries ONLY the dimensions shared by every hyperedge member type:
-//   ref       — ConceptRef [1] (the member concept)
-//   presence  — 'required' | 'optional' (default: required)
-//   count     — 'exactly_one' | 'at_least_one' | 'multiple' (default: exactly_one)
-//
-// These three form the ISO 704:2022 MECE pair (presence × count). The
-// pair is the shared invariant across all hyperedge types — that's
-// why it lives on the base.
-//
-// Type-specific extensions live on the leaves:
-//   PartitiveMember  — is_delimiting (rake-diagram semantics, ISO 704 §5.5.4.2.2)
-//   GenericMember    — delimitingCharacteristic (intension difference, ISO 704 §5.5.4.2.1)
-//
-// 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 { PARTITIVE_PRESENCE_VALUES, DEFAULT_PRESENCE, isValidPresence } from './partitive-presence.js';
-import type { PartitivePresence } from './partitive-presence.js';
-import { PARTITIVE_COUNT_VALUES, DEFAULT_COUNT, isValidCount } from './partitive-count.js';
-import type { PartitiveCount } from './partitive-count.js';
-import { multiplicityFromPair } from './multiplicity.js';
-
-export interface HyperedgeMemberJson {
-  ref: ConceptRefJson | ConceptRef;
-  presence?: PartitivePresence;
-  count?: PartitiveCount;
-}
-
-export abstract class HyperedgeMember extends GlossaristModel {
-  readonly ref: ConceptRef;
-  readonly presence: PartitivePresence;
-  readonly count: PartitiveCount;
-
-  constructor(data: HyperedgeMemberJson = { ref: {} }) {
-    super();
-    this.ref = _ensureRef(data.ref);
-    this.presence = _resolvePresence(data.presence);
-    this.count = _resolveCount(data.count);
-
-    _assertValidPair(this.presence, this.count);
-  }
-
-  get isRequired(): boolean { return this.presence === 'required'; }
-  get isOptional(): boolean { return this.presence === 'optional'; }
-
-  override identity(): string {
-    return HyperedgeMember.identityOf(this);
-  }
-
-  override toJSON(): HyperedgeMemberJson {
-    const obj: HyperedgeMemberJson = { ref: this.ref.toJSON() };
-    if (this.presence !== DEFAULT_PRESENCE) obj.presence = this.presence;
-    if (this.count !== DEFAULT_COUNT) obj.count = this.count;
-    return obj;
-  }
-
-  static identityOf(
-    value: { ref?: { source?: string | null; id?: string | null } | null } | null | undefined,
-  ): string {
-    const v = value ?? {};
-    const ref = v.ref ?? {};
-    return `${ref.source ?? ''}:${ref.id ?? ''}`;
-  }
-
-  static override fromJSON(_data: HyperedgeMemberJson): HyperedgeMember {
-    // Abstract base — subclasses MUST override. The base
-    // implementation is a typed marker that dispatches to the wrong
-    // class would surface as a runtime error rather than silently
-    // returning a mis-typed instance.
-    throw new Error(
-      'HyperedgeMember.fromJSON must be overridden by a subclass',
-    );
-  }
-}
-
-function _ensureRef(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(
-      'HyperedgeMember.ref must be a non-empty ConceptRef ' +
-      '(source, id, or text required)',
-    );
-  }
-  return ref;
-}
-
-function _resolvePresence(value: PartitivePresence | null | undefined): PartitivePresence {
-  const p = value ?? DEFAULT_PRESENCE;
-  if (!isValidPresence(p)) {
-    throw new Error(
-      `invalid presence ${JSON.stringify(value)}; ` +
-      `must be one of: ${PARTITIVE_PRESENCE_VALUES.join(', ')}`,
-    );
-  }
-  return p;
-}
-
-function _resolveCount(value: PartitiveCount | null | undefined): PartitiveCount {
-  const c = value ?? DEFAULT_COUNT;
-  if (!isValidCount(c)) {
-    throw new Error(
-      `invalid count ${JSON.stringify(value)}; ` +
-      `must be one of: ${PARTITIVE_COUNT_VALUES.join(', ')}`,
-    );
-  }
-  return c;
-}
-
-function _assertValidPair(presence: PartitivePresence, count: PartitiveCount): void {
-  // Delegate to the multiplicity SSOT. The canonical error string
-  // lives in one place: multiplicity.ts. Calling multiplicityFromPair
-  // throws on the invalid combination; we don't need to duplicate the
-  // error message here.
-  multiplicityFromPair(presence, count);
-}

package/src/models/hyperedge-registry.ts

@@ -1,145 +0,0 @@
-// HyperedgeRegistry — single source of truth for hyperedge type dispatch.
-//
-// Each hyperedge leaf class (PartitiveHyperedge, GenericHyperedge, future
-// TemporalHyperedge, AssociativeHyperedge, etc.) registers itself once at
-// module load. External systems (parser, serializer, diff, RDF emitter,
-// validators) read from this registry instead of branching on instanceof
-// or hardcoding per-type tables.
-//
-// Adding a new hyperedge type:
-//   1. Declare the leaf class with the 6-field metadata block
-//      (wireKey, typeTag, rdfType, memberClass, v1WireKeys, kindLabel).
-//   2. Call HyperedgeRegistry.register(MyClass) at the bottom of the file.
-//
-// Nothing else in the codebase changes. That is the OCP contract.
-//
-// Three indexes support three lookup patterns:
-//   byWireKey  — parser/serializer/diff-patch dispatch by YAML/JSON key
-//   byTypeTag  — per-file loader dispatch by `type: ...` discriminator
-//   byRdfType  — RDF emitter dispatch by ontology class IRI
-//
-// The abstract base (AbstractHyperedge) has no wireKey and is skipped
-// by register() — it cannot be instantiated through the registry.
-
-import type { AbstractHyperedge } from './abstract-hyperedge.js';
-
-/**
- * Shape a registered hyperedge class must satisfy. Every leaf class
- * in src/models/ matches this shape (declared as static fields).
- */
-export interface HyperedgeClass {
-  readonly wireKey: string;
-  readonly typeTag: string;
-  readonly rdfType: string;
-  readonly memberClass: new (...args: never[]) => unknown;
-  readonly v1WireKeys?: ReadonlyArray<string>;
-  readonly kindLabel?: string;
-  readonly name: string;
-}
-
-class HyperedgeRegistry {
-  static _byWireKey: Map<string, HyperedgeClass> = new Map();
-  static _byTypeTag: Map<string, HyperedgeClass> = new Map();
-  static _byRdfType: Map<string, HyperedgeClass> = new Map();
-
-  static register(cls: HyperedgeClass | undefined): boolean {
-    if (!cls || !cls.wireKey || !cls.typeTag || !cls.rdfType) return false;
-    if (this._byWireKey.has(cls.wireKey)) {
-      throw new Error(
-        `HyperedgeRegistry: duplicate wireKey '${cls.wireKey}' ` +
-        `(trying to register ${cls.name}; already registered to ` +
-        `${this._byWireKey.get(cls.wireKey)?.name})`,
-      );
-    }
-    if (this._byTypeTag.has(cls.typeTag)) {
-      throw new Error(
-        `HyperedgeRegistry: duplicate typeTag '${cls.typeTag}' ` +
-        `(trying to register ${cls.name})`,
-      );
-    }
-    if (this._byRdfType.has(cls.rdfType)) {
-      throw new Error(
-        `HyperedgeRegistry: duplicate rdfType '${cls.rdfType}' ` +
-        `(trying to register ${cls.name})`,
-      );
-    }
-    this._byWireKey.set(cls.wireKey, cls);
-    this._byTypeTag.set(cls.typeTag, cls);
-    this._byRdfType.set(cls.rdfType, cls);
-    return true;
-  }
-
-  /**
-   * Test-only. Removes a class from all three indexes. Used by the OCP
-   * spec to clean up mock types it adds during a test run.
-   */
-  static unregister(cls: HyperedgeClass | undefined): boolean {
-    if (!cls) return false;
-    const r1 = this._byWireKey.delete(cls.wireKey);
-    const r2 = this._byTypeTag.delete(cls.typeTag);
-    const r3 = this._byRdfType.delete(cls.rdfType);
-    return r1 || r2 || r3;
-  }
-
-  static forWireKey(key: string): HyperedgeClass | null {
-    return this._byWireKey.get(key) ?? null;
-  }
-  static forTypeTag(tag: string): HyperedgeClass | null {
-    return this._byTypeTag.get(tag) ?? null;
-  }
-  static forRdfType(type: string): HyperedgeClass | null {
-    return this._byRdfType.get(type) ?? null;
-  }
-
-  static allClasses(): HyperedgeClass[] {
-    // Dedup in case the same class is reachable via multiple indexes.
-    const seen = new Set<HyperedgeClass>();
-    const out: HyperedgeClass[] = [];
-    for (const cls of this._byTypeTag.values()) {
-      if (!seen.has(cls)) {
-        seen.add(cls);
-        out.push(cls);
-      }
-    }
-    return out;
-  }
-
-  static allWireKeys(): string[] { return [...this._byWireKey.keys()]; }
-  static allTypeTags(): string[] { return [...this._byTypeTag.keys()]; }
-
-  /**
-   * Snapshot of every registered wire-shape identifier (v2 wireKey plus
-   * any v1 legacy keys). Used by the parser to reserve STRUCTURAL_KEYS
-   * and to know which top-level YAML keys to walk for hyperedge data.
-   */
-  static allWireAndLegacyKeys(): string[] {
-    const out: string[] = [];
-    for (const cls of this.allClasses()) {
-      out.push(cls.wireKey);
-      for (const k of cls.v1WireKeys ?? []) out.push(k);
-    }
-    return out;
-  }
-}
-
-/**
- * Helper: partition a unified hyperedge array by wire key. Used by
- * Concept.toJSON, ConceptSerializer, and diff-patch to emit per-type
- * wire keys without per-type branching in those files. Adding a new
- * hyperedge type "just works" because the group is keyed by the
- * class's static wireKey.
- */
-export function groupHyperedgesByWireKey(
-  hyperedges: ReadonlyArray<AbstractHyperedge> | null | undefined,
-): Record<string, AbstractHyperedge[]> {
-  const out: Record<string, AbstractHyperedge[]> = {};
-  for (const h of hyperedges ?? []) {
-    const key = (h?.constructor as unknown as HyperedgeClass | undefined)?.wireKey;
-    if (!key) continue;
-    if (!out[key]) out[key] = [];
-    out[key].push(h);
-  }
-  return out;
-}
-
-export { HyperedgeRegistry };