glossarist 0.4.15 → 0.4.17

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