glossarist 0.4.42 → 0.4.44

package/src/diff/list-diff.js

@@ -1,227 +0,0 @@
-import { GlossaristModel } from '../models/base.js';
-import { Added, Removed, Changed, deserializeChange } from './change.js';
-import { diffText } from './text-diff.js';
-
-export class ListDiff extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this._added = (data.added ?? []).map(c => c instanceof Added ? c : Added.fromJSON(c));
-    this._removed = (data.removed ?? []).map(c => c instanceof Removed ? c : Removed.fromJSON(c));
-    this._changed = (data.changed ?? []).map(c => {
-      if (c instanceof Changed) return c;
-      return deserializeChange(c);
-    });
-  }
-
-  get added() { return this._added; }
-  get removed() { return this._removed; }
-  get changed() { return this._changed; }
-
-  get hasChanges() {
-    return this._added.length > 0 || this._removed.length > 0 || this._changed.length > 0;
-  }
-
-  get count() {
-    return this._added.length + this._removed.length + this._changed.length;
-  }
-
-  *entries() {
-    yield* this._added;
-    yield* this._removed;
-    yield* this._changed;
-  }
-
-  toJSON() {
-    return {
-      added: this._added.map(c => c.toJSON()),
-      removed: this._removed.map(c => c.toJSON()),
-      changed: this._changed.map(c => c.toJSON()),
-    };
-  }
-
-  static fromJSON(data) {
-    return new ListDiff(data);
-  }
-}
-
-/**
- * Diff two ordered lists using LCS alignment.
- *
- * - Items present in both (by identityKey) at the same relative position
- *   are "unchanged" and omitted from the result.
- * - Items only in the old list are "removed".
- * - Items only in the new list are "added".
- * - When an adjacent removed+added pair is detected at the same edit
- *   position, they are merged into a single "changed" entry. If both
- *   items expose text via textKey, a word-level TextDiff is attached.
- *
- * @param {Array} oldList
- * @param {Array} newList
- * @param {Object} [options]
- * @param {(item: any) => string} [options.identityKey] - equality key for matching items across lists
- * @param {(item: any) => string|null} [options.textKey] - extracts text content for word-level diff on changed items
- * @returns {ListDiff}
- */
-export function diffList(oldList = [], newList = [], options = {}) {
-  const identityKey = options.identityKey ?? defaultIdentityKey;
-  const textKey = options.textKey ?? null;
-
-  const oldArr = [...oldList];
-  const newArr = [...newList];
-
-  const oldKeys = oldArr.map(identityKey);
-  const newKeys = newArr.map(identityKey);
-
-  const dp = lcsTable(oldKeys, newKeys);
-  const ops = backtrackOps(dp, oldKeys, newKeys);
-
-  const added = [];
-  const removed = [];
-  const changed = [];
-
-  for (let k = 0; k < ops.length; k++) {
-    const op = ops[k];
-    if (op.type === 'equal') continue;
-
-    if (op.type === 'remove' && k + 1 < ops.length && ops[k + 1].type === 'add') {
-      const next = ops[k + 1];
-      const oldItem = oldArr[op.i];
-      const newItem = newArr[next.j];
-      changed.push(buildChanged(oldItem, newItem, textKey));
-      k++;
-    } else if (op.type === 'add' && k + 1 < ops.length && ops[k + 1].type === 'remove') {
-      const next = ops[k + 1];
-      const oldItem = oldArr[next.i];
-      const newItem = newArr[op.j];
-      changed.push(buildChanged(oldItem, newItem, textKey));
-      k++;
-    } else if (op.type === 'remove') {
-      removed.push(new Removed({ value: oldArr[op.i] }));
-    } else if (op.type === 'add') {
-      added.push(new Added({ value: newArr[op.j] }));
-    }
-  }
-
-  return new ListDiff({ added, removed, changed });
-}
-
-/**
- * Diff two unordered collections by identity key (set-based).
- *
- * - Items matched by identityKey in both lists are compared for full
- *   equality; if they differ → "changed".
- * - Items only in the old list are "removed".
- * - Items only in the new list are "added".
- *
- * Use this for collections where order does not carry meaning (e.g.
- * designations matched by term text, sources matched by ref, dates
- * matched by type).
- *
- * @param {Array} oldList
- * @param {Array} newList
- * @param {Object} options
- * @param {(item: any) => string} options.identityKey - key that identifies the same item across lists
- * @param {(item: any) => string|null} [options.textKey] - extracts text for word-level diff on changed items
- * @returns {ListDiff}
- */
-export function diffSet(oldList = [], newList = [], options = {}) {
-  const identityKey = options.identityKey ?? defaultIdentityKey;
-  const textKey = options.textKey ?? null;
-
-  const oldMap = new Map();
-  for (const item of oldList) {
-    oldMap.set(identityKey(item), item);
-  }
-
-  const seenKeys = new Set();
-  const added = [];
-  const changed = [];
-
-  for (const item of newList) {
-    const key = identityKey(item);
-    seenKeys.add(key);
-    if (oldMap.has(key)) {
-      const oldItem = oldMap.get(key);
-      if (!itemsEqual(oldItem, item)) {
-        changed.push(buildChanged(oldItem, item, textKey));
-      }
-    } else {
-      added.push(new Added({ value: item }));
-    }
-  }
-
-  const removed = [];
-  for (const item of oldList) {
-    if (!seenKeys.has(identityKey(item))) {
-      removed.push(new Removed({ value: item }));
-    }
-  }
-
-  return new ListDiff({ added, removed, changed });
-}
-
-function buildChanged(oldItem, newItem, textKey) {
-  const opts = { oldValue: oldItem, newValue: newItem };
-  if (textKey) {
-    const oldText = textKey(oldItem);
-    const newText = textKey(newItem);
-    if (oldText != null || newText != null) {
-      opts.textDiff = diffText(oldText ?? '', newText ?? '');
-    }
-  }
-  return new Changed(opts);
-}
-
-function itemsEqual(a, b) {
-  if (a === b) return true;
-  if (a instanceof GlossaristModel && b instanceof GlossaristModel) {
-    return a.equals(b);
-  }
-  return JSON.stringify(a) === JSON.stringify(b);
-}
-
-function defaultIdentityKey(item) {
-  if (item == null) return '';
-  if (typeof item === 'string') return item;
-  if (typeof item === 'number') return String(item);
-  if (item instanceof GlossaristModel) {
-    return JSON.stringify(item.toJSON());
-  }
-  return JSON.stringify(item);
-}
-
-function lcsTable(aKeys, bKeys) {
-  const m = aKeys.length;
-  const n = bKeys.length;
-  const dp = Array.from({ length: m + 1 }, () => new Uint32Array(n + 1));
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] = aKeys[i - 1] === bKeys[j - 1]
-        ? dp[i - 1][j - 1] + 1
-        : Math.max(dp[i - 1][j], dp[i][j - 1]);
-    }
-  }
-  return dp;
-}
-
-function backtrackOps(dp, aKeys, bKeys) {
-  const ops = [];
-  let i = aKeys.length;
-  let j = bKeys.length;
-  while (i > 0 && j > 0) {
-    if (aKeys[i - 1] === bKeys[j - 1]) {
-      ops.push({ type: 'equal', i: i - 1, j: j - 1 });
-      i--; j--;
-    } else if (dp[i - 1][j] >= dp[i][j - 1]) {
-      ops.push({ type: 'remove', i: i - 1, j });
-      i--;
-    } else {
-      ops.push({ type: 'add', i, j: j - 1 });
-      j--;
-    }
-  }
-  while (i > 0) { ops.push({ type: 'remove', i: i - 1, j }); i--; }
-  while (j > 0) { ops.push({ type: 'add', i, j: j - 1 }); j--; }
-  ops.reverse();
-  return ops;
-}

package/src/errors.js

@@ -1,42 +0,0 @@
-/**
- * Base error for all glossarist errors.
- */
-export class GlossaristError extends Error {
-  /**
-   * @param {string} message
-   * @param {{ cause?: Error }} [options]
-   */
-  constructor(message, options) {
-    super(message, options);
-    this.name = 'GlossaristError';
-  }
-}
-
-/**
- * Thrown when a function receives invalid input (null, undefined, wrong type).
- */
-export class InvalidInputError extends GlossaristError {
-  /**
-   * @param {string} what - description of the invalid input
-   * @param {string} [expected] - description of what was expected
-   */
-  constructor(what, expected) {
-    const msg = expected ? `${what} (expected ${expected})` : what;
-    super(msg);
-    this.name = 'InvalidInputError';
-  }
-}
-
-/**
- * Thrown when YAML content cannot be parsed.
- */
-export class YamlParseError extends GlossaristError {
-  /**
-   * @param {string} context - what was being parsed (e.g. concept ID)
-   * @param {Error} cause - the original YAML parse error
-   */
-  constructor(context, cause) {
-    super(`Failed to parse YAML for ${context}: ${cause.message}`, { cause });
-    this.name = 'YamlParseError';
-  }
-}

package/src/migration/hyperedge-migrator.js

@@ -1,119 +0,0 @@
-// v1 → v2 PartitiveHyperedge migration.
-//
-// Pure function: takes a v1 PartitiveHyperedge hash, returns a v2
-// PartitiveHyperedge hash. Idempotent. Used by the parser when loading
-// legacy YAML; available as a public API for one-shot dataset migrations.
-//
-// Field mapping (per TODO.partitive-relation-v2 items 01–05 and the
-// ISO 704:2022 correction):
-//
-//   comprehensive      → comprehensive     (unchanged shape)
-//   parts: [ref, ...]  → partitives: [{ ref, presence: 'required', count: 'exactly_one' }, ...]
-//   enumeration: open  → completeness: partial
-//   enumeration: closed→ completeness: complete
-//   markers: [...]     → (dropped — v2 uses per-member multiplicity
-//                          + is_delimiting; v1 markers encoded the
-//                          same information imprecisely and cannot
-//                          round-trip losslessly)
-//   content: "..."     → (dropped — structural edges carry no prose)
-//
-// Cardinality check: v1 allowed [1..*] parts; v2 requires [2..*].
-// A v1 hyperedge with exactly 1 part cannot migrate to v2 and is
-// returned with a `migrationWarning` field set so callers can decide
-// whether to surface it (the parser drops these with a warning).
-//
-// ─── Migration decision table (v1 markers → v2 multiplicity) ──────
-//
-// v1 markers encoded per-relation plurality claims. v2 multiplicity
-// is per-member. The mapping is lossy; reviewers must set per-member
-// multiplicity individually after migration.
-//
-//   | v1 markers              | Likely multiplicity for each partitive         | Notes                                                  |
-//   |-------------------------|------------------------------------------------|--------------------------------------------------------|
-//   | (none)                  | `compulsory`                                   | Default; reviewer confirms                             |
-//   | `[double]`              | `compulsory_multiple` or `compulsory_at_least_one` | Reviewer distinguishes "all required" from "≥1 required" |
-//   | `[dashed]`              | `optional` or `optional_multiple`              | Reviewer distinguishes single vs multiple              |
-//   | `[double, dashed]`      | `optional_multiple` or `compulsory_at_least_one` | Plurality claim; reviewer distinguishes uncertain vs required |
-//   | (single-part v1 edge)   | (cannot migrate — needs ≥2 partitives)         | Convert to a binary `has_part` edge                    |
-//
-// `is_delimiting` is NEVER set by migration. ISO 704:2022 says
-// delimiting depends on the concept system and coordinate concepts,
-// which migration cannot infer. Reviewer sets it based on domain
-// knowledge (see DelimitingCoherenceRule for cross-relation checks).
-
-export function migrateHyperedgeToRelation(v1Hash) {
-  if (v1Hash == null) return null;
-  if (Array.isArray(v1Hash)) {
-    return v1Hash.map(migrateHyperedgeToRelation);
-  }
-
-  const out = {
-    comprehensive: { ...(v1Hash.comprehensive ?? {}) },
-  };
-
-  const parts = Array.isArray(v1Hash.parts) ? v1Hash.parts : [];
-  out.partitives = parts.map(ref => ({
-    ref: { ...ref },
-    presence: 'required',
-    count: 'exactly_one',
-  }));
-
-  out.completeness = _migrateEnumeration(v1Hash.enumeration);
-
-  // v1 content + markers fields are dropped per TODO.partitive-relation-v2.
-  if (parts.length < 2) {
-    out.migrationWarning =
-      `v1 PartitiveHyperedge had ${parts.length} part(s); v2 requires ≥2. ` +
-      `Either add more partitives or convert to a binary has_part edge.`;
-  }
-
-  if (v1Hash.content != null) {
-    out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'content' field was dropped (v2 PartitiveHyperedge carries no prose; ` +
-      `move valuable text to the comprehensive concept's notes).`;
-  }
-
-  if (Array.isArray(v1Hash.markers) && v1Hash.markers.length > 0) {
-    out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'markers' field (${v1Hash.markers.join(', ')}) was dropped; ` +
-      `v2 uses per-member 'multiplicity' + 'is_delimiting'. Reviewer ` +
-      `should set these per partitive based on ISO 704:2022 notation.`;
-  }
-
-  return out;
-}
-
-// Inverse — v2 → v1 — exists only for tooling that must round-trip
-// through v1 consumers. NOT used by the parser; the serializer emits
-// v2 only. Lossy: drops criterion, multiplicity, is_delimiting.
-export function downgradeRelationToHyperedge(v2Hash) {
-  if (v2Hash == null) return null;
-  if (Array.isArray(v2Hash)) {
-    return v2Hash.map(downgradeRelationToHyperedge);
-  }
-
-  const out = {
-    comprehensive: { ...(v2Hash.comprehensive ?? {}) },
-  };
-
-  out.parts = (v2Hash.partitives ?? []).map(m => ({ ...(m.ref ?? {}) }));
-  out.enumeration = _downgradeCompleteness(v2Hash.completeness);
-
-  // criterion, multiplicity, is_delimiting have no v1 equivalent —
-  // dropped silently.
-
-  return out;
-}
-
-function _migrateEnumeration(value) {
-  if (value === 'open') return 'partial';
-  if (value === 'closed') return 'complete';
-  if (value == null) return 'complete';
-  // Unknown values default to complete (safe default — v2's safe default).
-  return 'complete';
-}
-
-function _downgradeCompleteness(value) {
-  if (value === 'partial') return 'open';
-  return 'closed';
-}

package/src/transforms/concept-to-gloss.transform.js

@@ -1,77 +0,0 @@
-// ConceptToGlossTransform — JS port of glossarist-ruby's
-// `Transforms::ConceptToGlossTransform`. Converts a Concept model into
-// ontology-faithful RDF (Turtle, JSON-LD, N-Triples).
-//
-// Usage:
-//   import { ConceptToGlossTransform } from 'glossarist/transforms';
-//   const xform = new ConceptToGlossTransform({ registerId: 'iso-6709', uriBase: 'https://glossarist.org' });
-//   const ttl = await xform.toTurtle(concept);
-//   const jsonld = await xform.toJsonld(concept);
-//   const ttlAll = await xform.toTurtleAll(concepts);
-import { conceptToQuads } from '../rdf/gloss-concept.js';
-import {
-  collectQuads,
-  writeTurtle,
-  writeNTriples,
-  writeJsonld,
-} from '../rdf/document-writer.js';
-
-// No hardcoded default URI base. Callers MUST pass options.uriBase so
-// concept IRIs reflect the consumer's domain.
-
-// Writer registry. Each entry is `{ write: (quads, transform) => Promise<string> }`.
-// Adding a new output format is a single entry here, not six new methods.
-const WRITERS = Object.freeze({
-  turtle:    { write: (quads) => writeTurtle(quads) },
-  ntriples:  { write: (quads) => writeNTriples(quads) },
-  jsonld:    { write: (quads, t) => writeJsonld(quads, t._jsonldOpts()) },
-});
-
-export class ConceptToGlossTransform {
-  constructor(options = {}) {
-    this.registerId = options.registerId;
-    this.uriBase = options.uriBase?.replace(/\/+$/, '');
-    if (!this.uriBase) throw new Error('ConceptToGlossTransform requires options.uriBase — the deployment canonical URI root.');
-    this.jsonldContext = options.jsonldContext;
-  }
-
-  toTurtle(target)    { return this._serialize(target, 'turtle'); }
-  toTurtleAll(targets) { return this._serialize(targets, 'turtle'); }
-  toJsonld(target)    { return this._serialize(target, 'jsonld'); }
-  toJsonldAll(targets) { return this._serialize(targets, 'jsonld'); }
-  toNTriples(target)  { return this._serialize(target, 'ntriples'); }
-  toNTriplesAll(targets) { return this._serialize(targets, 'ntriples'); }
-
-  // Single dispatcher: collect quads for one concept or many, then hand
-  // off to the registered writer. Replaces six near-identical methods.
-  async _serialize(target, format) {
-    const writer = WRITERS[format];
-    if (!writer) throw new Error(`Unknown serialization format: ${format}`);
-    const quads = this._collect(target);
-    return writer.write(quads, this);
-  }
-
-  _collect(target) {
-    if (target && typeof target[Symbol.iterator] === 'function') {
-      const quads = [];
-      for (const concept of target) {
-        for (const q of conceptToQuads(concept, this._optsFor(concept))) {
-          quads.push(q);
-        }
-      }
-      return quads;
-    }
-    return collectQuads(conceptToQuads(target, this._optsFor(target)));
-  }
-
-  _optsFor(concept) {
-    return {
-      registerId: this.registerId ?? concept.registerId ?? 'glossary',
-      uriBase: this.uriBase,
-    };
-  }
-
-  _jsonldOpts() {
-    return this.jsonldContext ? { context: this.jsonldContext } : {};
-  }
-}