glossarist 0.4.41 → 0.4.42

package/package.json

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

package/src/diff/{canonical-json.js → canonical-json.ts}

@@ -3,26 +3,24 @@
 // Sorts object keys recursively so two semantically-equal values produce
 // identical strings regardless of insertion order. Arrays preserve order
 // (they're ordered in domain semantics). Undefined values are dropped.
-//
-// Used by the diff layer to compare items whose `toJSON()` may emit keys
-// in different orders depending on conditional inclusion (e.g.,
-// PartitiveHyperedge#toJSON omits `markers` when empty).
 
-export function canonicalJson(value) {
-  return JSON.stringify(toCanonical(value));
+type JsonInput = null | undefined | string | number | boolean | JsonInput[] | { [k: string]: JsonInput };
+
+export function canonicalJson(value: JsonInput | unknown): string {
+  return JSON.stringify(toCanonical(value as JsonInput));
 }
 
-export function deepEqualCanonical(a, b) {
+export function deepEqualCanonical(a: JsonInput | unknown, b: JsonInput | unknown): boolean {
   return canonicalJson(a) === canonicalJson(b);
 }
 
-function toCanonical(value) {
+function toCanonical(value: JsonInput): unknown {
   if (value == null) return null;
   if (Array.isArray(value)) return value.map(toCanonical);
   if (typeof value === 'object') {
-    const out = {};
+    const out: Record<string, unknown> = {};
     for (const k of Object.keys(value).sort()) {
-      const v = toCanonical(value[k]);
+      const v = toCanonical((value as Record<string, JsonInput>)[k] as JsonInput);
       if (v !== undefined) out[k] = v;
     }
     return out;

package/src/diff/identity.ts

@@ -0,0 +1,33 @@
+// Shared identity helper for the diff layer.
+//
+// Per invariant N1, identity is a model concern. Models expose
+// `identity()` returning a stable string. This helper dispatches: if
+// the value is a model with `identity()`, call it; otherwise fall
+// back to canonical JSON of `toJSON()`.
+
+import { canonicalJson } from './canonical-json.js';
+
+interface Identifiable {
+  identity(): string;
+}
+interface HasToJSON {
+  toJSON(): unknown;
+}
+
+function hasIdentity(v: unknown): v is Identifiable {
+  return v != null && typeof v === 'object' && typeof (v as { identity?: unknown }).identity === 'function';
+}
+
+function hasToJSON(v: unknown): v is HasToJSON {
+  return v != null && typeof v === 'object' && typeof (v as { toJSON?: unknown }).toJSON === 'function';
+}
+
+export function identityOf(item: unknown): string {
+  if (item == null) return '';
+  if (hasIdentity(item)) return item.identity();
+  if (typeof item === 'string') return item;
+  if (typeof item === 'number') return String(item);
+  if (typeof item === 'boolean') return String(item);
+  if (hasToJSON(item)) return canonicalJson(item.toJSON());
+  return canonicalJson(item);
+}

package/src/diff/{similarity.js → similarity.ts}

@@ -2,22 +2,18 @@
 //
 // `computeSimilarity(changeCount, totalItems)` returns a value in
 // [0, 1] rounded to SIMILARITY_PRECISION_DECIMALS decimal places. The
-// rounding matches what glossarist-ruby's diff layer produces, so
-// similarity scores are stable across repos.
-//
-// `averageSimilarity(values)` averages an array of per-item similarity
-// scores (used by ConceptCollectionDiff to roll up matched concepts).
+// rounding matches what glossarist-ruby's diff layer produces.
 
 export const SIMILARITY_PRECISION_DECIMALS = 4;
 const _SCALE = 10 ** SIMILARITY_PRECISION_DECIMALS;
 
-export function computeSimilarity(changeCount, totalItems) {
+export function computeSimilarity(changeCount: number, totalItems: number): number {
   if (totalItems <= 0) return 1.0;
   const ratio = Math.min(changeCount / totalItems, 1);
   return Math.round((1 - ratio) * _SCALE) / _SCALE;
 }
 
-export function averageSimilarity(values) {
+export function averageSimilarity(values: ReadonlyArray<number>): number {
   if (values.length === 0) return 1.0;
   const sum = values.reduce((a, b) => a + b, 0);
   return Math.round((sum / values.length) * _SCALE) / _SCALE;

package/src/diff/text-diff.ts

@@ -0,0 +1,167 @@
+import { GlossaristModel } from '../models/base.js';
+
+const HUNK_EQUAL = 'equal';
+const HUNK_ADDED = 'added';
+const HUNK_REMOVED = 'removed';
+
+export type TextHunkType = typeof HUNK_EQUAL | typeof HUNK_ADDED | typeof HUNK_REMOVED;
+
+const TOKEN_RE = /(\s+)|(\S+)/g;
+
+export interface TextHunkJson {
+  type: TextHunkType;
+  text: string;
+}
+
+export class TextHunk extends GlossaristModel {
+  readonly type: TextHunkType;
+  readonly text: string;
+
+  constructor(data: TextHunkJson = { type: HUNK_EQUAL, text: '' }) {
+    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 ?? '';
+  }
+
+  override toJSON(): TextHunkJson {
+    return { type: this.type, text: this.text };
+  }
+
+  static override fromJSON(data: TextHunkJson): TextHunk {
+    return new TextHunk(data);
+  }
+}
+
+export interface TextDiffJson {
+  oldText?: string;
+  old_text?: string;
+  newText?: string;
+  new_text?: string;
+  hunks?: ReadonlyArray<TextHunkJson | TextHunk>;
+}
+
+export class TextDiff extends GlossaristModel {
+  readonly oldText: string;
+  readonly newText: string;
+  private readonly _hunks: ReadonlyArray<TextHunk>;
+
+  constructor(data: TextDiffJson = {}) {
+    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(): ReadonlyArray<TextHunk> {
+    return this._hunks;
+  }
+
+  get hasChanges(): boolean {
+    return this._hunks.some((h) => h.type !== HUNK_EQUAL);
+  }
+
+  get addedText(): string {
+    return this._hunks
+      .filter((h) => h.type === HUNK_ADDED)
+      .map((h) => h.text)
+      .join('');
+  }
+
+  get removedText(): string {
+    return this._hunks
+      .filter((h) => h.type === HUNK_REMOVED)
+      .map((h) => h.text)
+      .join('');
+  }
+
+  override toJSON(): TextDiffJson & { old_text: string; new_text: string; hunks: ReadonlyArray<TextHunkJson> } {
+    return {
+      old_text: this.oldText,
+      new_text: this.newText,
+      hunks: this._hunks.map((h) => h.toJSON()),
+    };
+  }
+
+  static override fromJSON(data: TextDiffJson): TextDiff {
+    return new TextDiff(data);
+  }
+}
+
+export function diffText(oldText: string | null | undefined, newText: string | null | undefined): TextDiff {
+  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: string): string[] {
+  if (text.length === 0) return [];
+  return text.match(TOKEN_RE) ?? [];
+}
+
+function lcsHunks(a: string[], b: string[]): TextHunk[] {
+  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: Array<{ type: TextHunkType; text: string }> = [];
+  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] ?? 0) >= (dp[i]![j - 1] ?? 0)) {
+      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: ReadonlyArray<{ type: TextHunkType; text: string }>,
+): Array<{ type: TextHunkType; text: string }> {
+  const out: Array<{ type: TextHunkType; text: string }> = [];
+  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/diff/identity.js

@@ -1,22 +0,0 @@
-// Shared identity helper for the diff layer.
-//
-// Per invariant N1 (TODO.hyperedges-v2/00-master-plan.md), identity is a
-// model concern. Models expose `identity()` returning a stable string.
-// This helper dispatches: if the value is a model with `identity()`,
-// call it; otherwise fall back to canonical JSON of `toJSON()`.
-//
-// Both `concept-diff.js` (compute side) and `diff-patch.js` (apply side)
-// import this — closing the duplication that previously allowed the two
-// sides to drift.
-
-import { canonicalJson } from './canonical-json.js';
-
-export function identityOf(item) {
-  if (item == null) return '';
-  if (typeof item.identity === 'function') return item.identity();
-  if (typeof item === 'string') return item;
-  if (typeof item === 'number') return String(item);
-  if (typeof item === 'boolean') return String(item);
-  if (typeof item.toJSON === 'function') return canonicalJson(item.toJSON());
-  return canonicalJson(item);
-}

package/src/diff/text-diff.js

@@ -1,128 +0,0 @@
-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;
-}