glossarist 0.4.14 → 0.4.16

package/src/diff/list-diff.js

@@ -0,0 +1,227 @@
+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/diff/text-diff.js

@@ -0,0 +1,128 @@
+import { GlossaristModel } from '../models/base.js';
+
+const HUNK_EQUAL = 'equal';
+const HUNK_ADDED = 'added';
+const HUNK_REMOVED = 'removed';
+
+const TOKEN_RE = /(\s+)|(\S+)/g;
+
+export class TextHunk extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    if (![HUNK_EQUAL, HUNK_ADDED, HUNK_REMOVED].includes(data.type)) {
+      throw new Error(`TextHunk type must be 'equal', 'added', or 'removed' (got ${data.type})`);
+    }
+    this.type = data.type;
+    this.text = data.text ?? '';
+  }
+
+  toJSON() {
+    return { type: this.type, text: this.text };
+  }
+
+  static fromJSON(data) {
+    return new TextHunk(data);
+  }
+}
+
+export class TextDiff extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.oldText = data.oldText ?? data.old_text ?? '';
+    this.newText = data.newText ?? data.new_text ?? '';
+    this._hunks = (data.hunks ?? []).map(h => h instanceof TextHunk ? h : new TextHunk(h));
+  }
+
+  get hunks() {
+    return this._hunks;
+  }
+
+  get hasChanges() {
+    return this._hunks.some(h => h.type !== HUNK_EQUAL);
+  }
+
+  get addedText() {
+    return this._hunks.filter(h => h.type === HUNK_ADDED).map(h => h.text).join('');
+  }
+
+  get removedText() {
+    return this._hunks.filter(h => h.type === HUNK_REMOVED).map(h => h.text).join('');
+  }
+
+  toJSON() {
+    return {
+      old_text: this.oldText,
+      new_text: this.newText,
+      hunks: this._hunks.map(h => h.toJSON()),
+    };
+  }
+
+  static fromJSON(data) {
+    return new TextDiff(data);
+  }
+}
+
+export function diffText(oldText, newText) {
+  const oldStr = String(oldText ?? '');
+  const newStr = String(newText ?? '');
+  const oldTokens = tokenize(oldStr);
+  const newTokens = tokenize(newStr);
+  const hunks = lcsHunks(oldTokens, newTokens);
+  return new TextDiff({ oldText: oldStr, newText: newStr, hunks });
+}
+
+function tokenize(text) {
+  if (text.length === 0) return [];
+  return text.match(TOKEN_RE) ?? [];
+}
+
+function lcsHunks(a, b) {
+  const n = a.length;
+  const m = b.length;
+
+  if (n === 0) return m === 0 ? [] : [new TextHunk({ type: HUNK_ADDED, text: b.join('') })];
+  if (m === 0) return [new TextHunk({ type: HUNK_REMOVED, text: a.join('') })];
+
+  const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1] + 1
+        : Math.max(dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+
+  const raw = [];
+  let i = n;
+  let j = m;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      raw.push({ type: HUNK_EQUAL, text: a[i - 1] });
+      i--; j--;
+    } else if (dp[i - 1][j] >= dp[i][j - 1]) {
+      raw.push({ type: HUNK_REMOVED, text: a[i - 1] });
+      i--;
+    } else {
+      raw.push({ type: HUNK_ADDED, text: b[j - 1] });
+      j--;
+    }
+  }
+  while (i > 0) { raw.push({ type: HUNK_REMOVED, text: a[i - 1] }); i--; }
+  while (j > 0) { raw.push({ type: HUNK_ADDED, text: b[j - 1] }); j--; }
+  raw.reverse();
+
+  return coalesce(raw).map(h => new TextHunk(h));
+}
+
+function coalesce(raw) {
+  const out = [];
+  for (const r of raw) {
+    const last = out[out.length - 1];
+    if (last && last.type === r.type) {
+      last.text += r.text;
+    } else {
+      out.push({ type: r.type, text: r.text });
+    }
+  }
+  return out;
+}

package/src/index.d.ts

@@ -15,6 +15,27 @@ export {
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index';
 
+// Concept diff
+export {
+  diffConcepts,
+  diffLocalizedConcepts,
+  diffText,
+  diffList,
+  diffSet,
+  ConceptDiff,
+  ConceptLevelDiff,
+  LocalizedConceptDiff,
+  MetadataDiff,
+  DiffStats,
+  ListDiff,
+  TextDiff,
+  TextHunk,
+  Change,
+  Added,
+  Removed,
+  Changed,
+} from './diff/index';
+
 // GCR reader
 export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
 

package/src/index.js

@@ -1,4 +1,23 @@
 export { naturalSort } from './sort.js';
+export {
+  diffConcepts,
+  diffLocalizedConcepts,
+  diffText,
+  diffList,
+  diffSet,
+  ConceptDiff,
+  ConceptLevelDiff,
+  LocalizedConceptDiff,
+  MetadataDiff,
+  DiffStats,
+  ListDiff,
+  TextDiff,
+  TextHunk,
+  Change,
+  Added,
+  Removed,
+  Changed,
+} from './diff/index.js';
 export { loadGcr, GcrPackage, parseConceptYaml } from './gcr-reader.js';
 export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader.js';
 export { writeConcept, writeConcepts } from './concept-writer.js';

package/src/models/concept.js

@@ -7,6 +7,7 @@ import { ConceptSource } from './concept-source.js';
 import { FigureReference } from './non-verbal-references.js';
 import { TableReference } from './non-verbal-references.js';
 import { FormulaReference } from './non-verbal-references.js';
+import { diffConcepts } from '../diff/concept-diff.js';
 
 export class Concept extends GlossaristModel {
   constructor(data = {}) {
@@ -58,6 +59,10 @@ export class Concept extends GlossaristModel {
     return this._cache[lang];
   }
 
+  diff(other, language = 'eng') {
+    return diffConcepts(this, other, language);
+  }
+
   primaryDesignation(lang) {
     return this.localization(lang)?.primaryDesignation ?? null;
   }

package/src/rdf/bnode-id.js

@@ -6,11 +6,30 @@
 // strategy: MD5 (via node:crypto) when available, FNV-1a fallback for
 // browser bundles.
 //
-// Cross-process stability matches glossarist-ruby's deterministic-id
-// when node:crypto is available. Within a single process, FNV-1a is
-// also stable.
+// Browser safety: node:crypto is loaded lazily via runtime check so
+// bundlers don't tree-shake the import into the browser bundle.
 
-import { createHash } from 'node:crypto';
+let nodeCreateHash = null;
+let nodeCryptoChecked = false;
+
+function getNodeCreateHash() {
+  if (nodeCryptoChecked) return nodeCreateHash;
+  nodeCryptoChecked = true;
+  try {
+    let requireFn;
+    try {
+      const mod = (Function('m', 'return require(m)'))('node:module');
+      requireFn = mod.createRequire(import.meta.url);
+    } catch {
+      requireFn = (m) => (Function('m', 'return require(m)'))(m);
+    }
+    const crypto = requireFn('node:crypto');
+    nodeCreateHash = crypto.createHash.bind(crypto);
+  } catch {
+    nodeCreateHash = null;
+  }
+  return nodeCreateHash;
+}
 
 function fnv1a(seed) {
   let h = 0x811c9dc5;
@@ -24,12 +43,13 @@ function fnv1a(seed) {
 export function deterministicBnodeId(...parts) {
   const seed = parts.filter(p => p != null && p !== '').join('|');
   if (!seed) return `b${fnv1a('empty')}`;
-  // MD5 matches glossarist-ruby's deterministic-id for cross-process
-  // stability. Truncated to 12 hex chars — enough collision resistance
-  // for bnode IDs within a single document.
-  try {
-    return createHash('md5').update(seed).digest('hex').slice(0, 12);
-  } catch {
-    return `b${fnv1a(seed)}`;
+  const createHash = getNodeCreateHash();
+  if (createHash) {
+    try {
+      return createHash('md5').update(seed).digest('hex').slice(0, 12);
+    } catch {
+      // fall through to FNV
+    }
   }
+  return `b${fnv1a(seed)}`;
 }

package/src/rdf/deterministic-id.js

@@ -1,17 +1,71 @@
-import { createHash } from 'node:crypto';
+// Stable ID helpers for RDF emission. Mirrors glossarist-ruby's
+// Digest::MD5.hexdigest(content)[0..11] for cross-runtime stability.
+//
+// Browser safety: node:crypto is loaded lazily so bundlers don't
+// tree-shake the import into browser bundles. The runtime check uses
+// `createRequire` from `node:module` (also lazy) which is the
+// documented way to use CommonJS `require` from ESM.
+
+let nodeCreateHash = null;
+let nodeCryptoChecked = false;
+
+function getNodeCreateHash() {
+  if (nodeCryptoChecked) return nodeCreateHash;
+  nodeCryptoChecked = true;
+  try {
+    // Lazy require — works in both CJS and ESM (Node ≥ 12).
+    // Wrapped in Function() so bundlers don't statically resolve it.
+    let requireFn;
+    try {
+      // ESM: use createRequire from node:module
+      const mod = (Function('m', 'return require(m)'))('node:module');
+      requireFn = mod.createRequire(import.meta.url);
+    } catch {
+      // CJS or already-require-available environment
+      requireFn = (m) => (Function('m', 'return require(m)'))(m);
+    }
+    const crypto = requireFn('node:crypto');
+    nodeCreateHash = crypto.createHash.bind(crypto);
+  } catch {
+    nodeCreateHash = null;
+  }
+  return nodeCreateHash;
+}
 
 // 12-char hex prefix, mirroring glossarist-ruby's
 // `Digest::MD5.hexdigest(content)[0..11]`. Same content → same ID across
-// processes, machines, and language runtimes (Ruby vs JS).
+// processes, machines, and language runtimes (Ruby vs JS) when MD5 is
+// available. Falls back to a 12-char FNV-1a hash in the browser.
 export function deterministicId(...parts) {
   const seed = parts.filter(p => p !== null && p !== undefined).join('|');
-  return createHash('md5').update(seed).digest('hex').slice(0, 12);
+  const createHash = getNodeCreateHash();
+  if (createHash) {
+    return createHash('md5').update(seed).digest('hex').slice(0, 12);
+  }
+  return fnv1a12(seed);
 }
 
 // Stable blank-node label for an RDF fragment identified by its parent
-// subject + role + index. Useful for reified resources like DetailedDefinition,
-// Designation, ConceptSource where the bnode ID must be deterministic to
-// produce byte-equivalent Turtle across runs.
+// subject + role + index.
 export function deterministicBnode(subject, role, index) {
   return `_:b${deterministicId(subject, role, index)}`;
 }
+
+// 12-char FNV-1a hash. Two 32-bit passes concatenated and truncated.
+// Not as collision-resistant as MD5 but adequate for bnode IDs in a
+// single document. Used only when node:crypto is unavailable.
+function fnv1a12(seed) {
+  let h1 = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i++) {
+    h1 ^= seed.charCodeAt(i);
+    h1 = Math.imul(h1, 0x01000193);
+  }
+  const seed2 = `${seed}|fnv2`;
+  let h2 = 0x811c9dc5;
+  for (let i = 0; i < seed2.length; i++) {
+    h2 ^= seed2.charCodeAt(i);
+    h2 = Math.imul(h2, 0x01000193);
+  }
+  return ((h1 >>> 0).toString(16).padStart(8, '0')
+    + (h2 >>> 0).toString(16).padStart(8, '0')).slice(0, 12);
+}

package/src/rdf/index.d.ts

@@ -315,7 +315,5 @@ export interface ValidationReport {
   }>;
 }
 
-export declare function loadShapes(options?: { shapesPath?: string }): Promise<Dataset>;
-export declare function validateShacl(dataDataset: Dataset, options?: { shapes?: Dataset; shapesPath?: string }): Promise<ValidationReport>;
-export declare function clearShapesCache(): void;
-export declare function quadsToDataset(quads: Iterable<Quad>): Dataset;
+// SHACL validator moved to ./shacl-entry subpath. Importing from
+// 'glossarist/rdf/shacl' in Node-only; 'glossarist/rdf' is browser-safe.

package/src/rdf/index.js

@@ -50,6 +50,8 @@ export {
   sortQuads,
 } from './document-writer.js';
 export { writeTurtleSync } from './write-turtle-sync.js';
-export { validateShacl, loadShapes, clearShapesCache, quadsToDataset } from './shacl.js';
+// SHACL validator moved to glossarist/rdf/shacl subpath — it depends on
+// node:fs/promises, node:path, node:url at module top-level, which would
+// break browser bundles. Importing 'glossarist/rdf' alone is browser-safe.
 export { quadSectionsToClassInstances } from './sections-builder.js';
 export { provenanceToQuads } from './provenance-emitter.js';

package/src/rdf/shacl-entry.d.ts

@@ -0,0 +1,6 @@
+// Type declarations for the Node-only SHACL validator subpath.
+//
+// Mirrors src/rdf/shacl-entry.js. Separated from ./rdf so that browser
+// bundles don't pull in node:fs/promises, node:path, node:url.
+
+export { validateShacl, loadShapes, clearShapesCache, quadsToDataset } from './shacl';

package/src/rdf/shacl-entry.js

@@ -0,0 +1,9 @@
+// Node-only SHACL validator entry. Separated from glossarist/rdf so that
+// browser bundles can import RDF emitters/writers without pulling in
+// node:fs/promises, node:path, node:url.
+//
+// Usage (Node only):
+//   import { validateShacl, loadShapes, clearShapesCache, quadsToDataset }
+//     from 'glossarist/rdf/shacl';
+
+export { validateShacl, loadShapes, clearShapesCache, quadsToDataset } from './shacl.js';