glossarist 0.4.41 → 0.4.43

package/package.json

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

package/src/{compiled-format.js → compiled-format.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 /**
  * Registry of compiled/machine formats that can be bundled inside a GCR package.
  *

package/src/{concept-collection.js → concept-collection.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import { naturalSort } from './sort.js';
 
 const _items = Symbol('items');

package/src/{concept-diff.js → concept-diff.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 /**
  * @deprecated Import from `glossarist/diff` (i.e. `src/diff/index.js`)
  * instead. This file is a backwards-compatibility shim left over from

package/src/{concept-parser.js → concept-parser.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import * as yaml from 'js-yaml';
 import { Concept } from './models/concept.js';
 import { RelatedConcept } from './models/related-concept.js';

package/src/{concept-reader.js → concept-reader.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import fs from 'fs';
 import path from 'path';
 import * as yaml from 'js-yaml';

package/src/{concept-serializer.js → concept-serializer.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import * as yaml from 'js-yaml';
 import { PartitiveHyperedge } from './models/partitive-hyperedge.js';
 import { GenericHyperedge } from './models/generic-hyperedge.js';

package/src/{concept-writer.js → concept-writer.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import fs from 'fs';
 import path from 'path';
 import { conceptSerializer } from './concept-serializer.js';

package/src/{dataset-asset.js → dataset-asset.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 /**
  * Registry of dataset assets that can be bundled inside a GCR package.
  *

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/change.ts

@@ -0,0 +1,175 @@
+import { GlossaristModel } from '../models/base.js';
+import { TextDiff } from './text-diff.js';
+import type { TextDiffJson } from './text-diff.js';
+
+export const CHANGE_ADDED = 'added';
+export const CHANGE_REMOVED = 'removed';
+export const CHANGE_CHANGED = 'changed';
+export const CHANGE_MATCHED = 'matched';
+
+export type ChangeType = 'added' | 'removed' | 'changed' | 'matched';
+
+export interface ChangeJson {
+  type: ChangeType;
+  path?: string | null;
+  value?: unknown;
+  old_value?: unknown;
+  oldValue?: unknown;
+  new_value?: unknown;
+  newValue?: unknown;
+  text_diff?: TextDiffJson;
+  textDiff?: TextDiffJson;
+}
+
+function serializeValue(v: unknown): unknown {
+  if (v == null) return null;
+  if (v instanceof GlossaristModel) return v.toJSON();
+  if (Array.isArray(v)) return v.map(serializeValue);
+  if (typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      out[k] = serializeValue(val);
+    }
+    return out;
+  }
+  return v;
+}
+
+export class Change extends GlossaristModel {
+  readonly path: string | null;
+
+  constructor(data: Pick<ChangeJson, 'path'> = {}) {
+    super();
+    this.path = data.path ?? null;
+  }
+
+  get type(): ChangeType {
+    throw new Error(`${this.constructor.name} must override type getter`);
+  }
+
+  static override fromJSON(data: ChangeJson): Change {
+    return deserializeChange(data);
+  }
+}
+
+export class Added extends Change {
+  readonly value: unknown;
+
+  constructor(data: Pick<ChangeJson, 'path' | 'value'> = {}) {
+    super(data);
+    this.value = data.value ?? null;
+  }
+
+  override get type(): ChangeType { return CHANGE_ADDED; }
+
+  override toJSON(): ChangeJson {
+    const obj: ChangeJson = { type: CHANGE_ADDED };
+    if (this.path != null) obj.path = this.path;
+    obj.value = serializeValue(this.value);
+    return obj;
+  }
+
+  static override fromJSON(data: ChangeJson): Added {
+    return new Added(data as Pick<ChangeJson, 'path' | 'value'>);
+  }
+}
+
+export class Removed extends Change {
+  readonly value: unknown;
+
+  constructor(data: Pick<ChangeJson, 'path' | 'value'> = {}) {
+    super(data);
+    this.value = data.value ?? null;
+  }
+
+  override get type(): ChangeType { return CHANGE_REMOVED; }
+
+  override toJSON(): ChangeJson {
+    const obj: ChangeJson = { type: CHANGE_REMOVED };
+    if (this.path != null) obj.path = this.path;
+    obj.value = serializeValue(this.value);
+    return obj;
+  }
+
+  static override fromJSON(data: ChangeJson): Removed {
+    return new Removed(data as Pick<ChangeJson, 'path' | 'value'>);
+  }
+}
+
+export interface ChangedConstructorData {
+  path?: string | null;
+  oldValue?: unknown;
+  old_value?: unknown;
+  newValue?: unknown;
+  new_value?: unknown;
+  textDiff?: TextDiff | TextDiffJson;
+  text_diff?: TextDiffJson;
+}
+
+export class Changed extends Change {
+  readonly oldValue: unknown;
+  readonly newValue: unknown;
+  private readonly _textDiff: TextDiff | null;
+
+  constructor(data: ChangedConstructorData = {}) {
+    super(data as Pick<ChangeJson, 'path'>);
+    this.oldValue = data.oldValue ?? data.old_value ?? null;
+    this.newValue = data.newValue ?? data.new_value ?? null;
+    const td = data.textDiff ?? data.text_diff;
+    this._textDiff = td instanceof TextDiff ? td : td ? TextDiff.fromJSON(td) : null;
+  }
+
+  override get type(): ChangeType { return CHANGE_CHANGED; }
+
+  get textDiff(): TextDiff | null {
+    return this._textDiff;
+  }
+
+  override toJSON(): ChangeJson {
+    const obj: ChangeJson = { type: CHANGE_CHANGED };
+    if (this.path != null) obj.path = this.path;
+    obj.old_value = serializeValue(this.oldValue);
+    obj.new_value = serializeValue(this.newValue);
+    if (this._textDiff) obj.text_diff = this._textDiff.toJSON() as TextDiffJson;
+    return obj;
+  }
+
+  static override fromJSON(data: ChangeJson): Changed {
+    return new Changed(data as Required<Pick<ChangeJson, never>>);
+  }
+}
+
+// Matched is for set-membership records that exist in both sides of a
+// comparison but have no directionality — used by ConceptCollectionDiff.
+export class Matched extends Change {
+  readonly value: unknown;
+
+  constructor(data: Pick<ChangeJson, 'path' | 'value'> = {}) {
+    super(data);
+    this.value = data.value ?? null;
+  }
+
+  override get type(): ChangeType { return CHANGE_MATCHED; }
+
+  override toJSON(): ChangeJson {
+    const obj: ChangeJson = { type: CHANGE_MATCHED };
+    if (this.path != null) obj.path = this.path;
+    obj.value = serializeValue(this.value);
+    return obj;
+  }
+
+  static override fromJSON(data: ChangeJson): Matched {
+    return new Matched(data as Pick<ChangeJson, 'path' | 'value'>);
+  }
+}
+
+export function deserializeChange(data: ChangeJson): Change {
+  switch (data?.type) {
+    case CHANGE_ADDED: return Added.fromJSON(data);
+    case CHANGE_REMOVED: return Removed.fromJSON(data);
+    case CHANGE_CHANGED: return Changed.fromJSON(data);
+    case CHANGE_MATCHED: return Matched.fromJSON(data);
+    default:
+      throw new Error(`Unknown change type: ${(data as { type?: string })?.type}`);
+  }
+}

package/src/diff/{collection-diff.js → collection-diff.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY bridge during TS migration. TODO(Phase 2e): remove this directive and type all parameters.
 import { GlossaristModel } from '../models/base.js';
 import { Added, Removed, Matched, deserializeChange } from './change.js';
 import { ConceptDiff, DiffStats, diffConcepts } from './concept-diff.js';

package/src/diff/{concept-diff.js → concept-diff.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY bridge during TS migration. TODO(Phase 2e): remove this directive and type all parameters.
 import { GlossaristModel } from '../models/base.js';
 import { PartitiveHyperedge } from '../models/partitive-hyperedge.js';
 import { GenericHyperedge } from '../models/generic-hyperedge.js';

package/src/diff/{diff-patch.js → diff-patch.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY bridge during TS migration. TODO(Phase 2e): remove this directive and type all parameters.
 import { Concept } from '../models/concept.js';
 import { ConceptSource } from '../models/concept-source.js';
 import { ConceptDate } from '../models/concept-date.js';

package/src/diff/{diff-renderer.js → diff-renderer.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY bridge during TS migration. TODO(Phase 2e): remove this directive and type all parameters.
 import { TextDiff } from './text-diff.js';
 import { resolveMultiplicity } from '../models/multiplicity.js';
 

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/{index.js → index.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck — TEMPORARY bridge during TS migration. TODO(Phase 2e): remove this directive and type all parameters.
 export {
   TextHunk,
   TextDiff,

package/src/diff/list-diff.ts

@@ -0,0 +1,231 @@
+import { GlossaristModel } from '../models/base.js';
+import { Added, Removed, Changed, deserializeChange } from './change.js';
+import type { ChangeJson, ChangedConstructorData } from './change.js';
+import { diffText } from './text-diff.js';
+import { identityOf } from './identity.js';
+
+export interface ListDiffJson {
+  added?: ReadonlyArray<ChangeJson | Added>;
+  removed?: ReadonlyArray<ChangeJson | Removed>;
+  changed?: ReadonlyArray<ChangeJson | Changed>;
+}
+
+interface ListDiffOptions {
+  identityKey?: (item: unknown) => string;
+  textKey?: ((item: unknown) => string | null) | null;
+}
+
+export class ListDiff extends GlossaristModel {
+  private readonly _added: ReadonlyArray<Added>;
+  private readonly _removed: ReadonlyArray<Removed>;
+  private readonly _changed: ReadonlyArray<Changed>;
+
+  constructor(data: ListDiffJson = {}) {
+    super();
+    this._added = (data.added ?? []).map((c) =>
+      c instanceof Added ? c : Added.fromJSON(c),
+    ) as ReadonlyArray<Added>;
+    this._removed = (data.removed ?? []).map((c) =>
+      c instanceof Removed ? c : Removed.fromJSON(c),
+    ) as ReadonlyArray<Removed>;
+    this._changed = (data.changed ?? []).map((c) => {
+      if (c instanceof Changed) return c;
+      return deserializeChange(c) as Changed;
+    }) as ReadonlyArray<Changed>;
+  }
+
+  get added(): ReadonlyArray<Added> { return this._added; }
+  get removed(): ReadonlyArray<Removed> { return this._removed; }
+  get changed(): ReadonlyArray<Changed> { return this._changed; }
+
+  get hasChanges(): boolean {
+    return this._added.length > 0 || this._removed.length > 0 || this._changed.length > 0;
+  }
+
+  get count(): number {
+    return this._added.length + this._removed.length + this._changed.length;
+  }
+
+  *entries(): Generator<Added | Removed | Changed> {
+    yield* this._added;
+    yield* this._removed;
+    yield* this._changed;
+  }
+
+  override toJSON(): ListDiffJson {
+    return {
+      added: this._added.map((c) => c.toJSON()),
+      removed: this._removed.map((c) => c.toJSON()),
+      changed: this._changed.map((c) => c.toJSON()),
+    };
+  }
+
+  static override fromJSON(data: ListDiffJson): ListDiff {
+    return new ListDiff(data);
+  }
+}
+
+/**
+ * Diff two ordered lists using LCS alignment.
+ */
+export function diffList(
+  oldList: ReadonlyArray<unknown> = [],
+  newList: ReadonlyArray<unknown> = [],
+  options: ListDiffOptions = {},
+): ListDiff {
+  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: Added[] = [];
+  const removed: Removed[] = [];
+  const changed: 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]!;
+      changed.push(buildChanged(oldArr[op.i]!, newArr[next.j]!, textKey));
+      k++;
+    } else if (op.type === 'add' && k + 1 < ops.length && ops[k + 1]!.type === 'remove') {
+      const next = ops[k + 1]!;
+      changed.push(buildChanged(oldArr[next.i]!, newArr[op.j]!, 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).
+ */
+export function diffSet(
+  oldList: ReadonlyArray<unknown> = [],
+  newList: ReadonlyArray<unknown> = [],
+  options: ListDiffOptions = {},
+): ListDiff {
+  const identityKey = options.identityKey ?? defaultIdentityKey;
+  const textKey = options.textKey ?? null;
+
+  const oldMap = new Map<string, unknown>();
+  for (const item of oldList) {
+    oldMap.set(identityKey(item), item);
+  }
+
+  const seenKeys = new Set<string>();
+  const added: Added[] = [];
+  const changed: Changed[] = [];
+
+  for (const item of newList) {
+    const key = identityKey(item);
+    seenKeys.add(key);
+    if (oldMap.has(key)) {
+      const oldItem = oldMap.get(key);
+      if (oldItem !== undefined && !itemsEqual(oldItem, item)) {
+        changed.push(buildChanged(oldItem, item, textKey));
+      }
+    } else {
+      added.push(new Added({ value: item }));
+    }
+  }
+
+  const removed: 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: unknown,
+  newItem: unknown,
+  textKey: ((item: unknown) => string | null) | null,
+): Changed {
+  const opts: ChangedConstructorData = {
+    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: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a instanceof GlossaristModel && b instanceof GlossaristModel) {
+    return a.equals(b as never);
+  }
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function defaultIdentityKey(item: unknown): string {
+  return identityOf(item);
+}
+
+type Op = { type: 'equal' | 'add' | 'remove'; i: number; j: number };
+
+function lcsTable(aKeys: string[], bKeys: string[]): Uint32Array[] {
+  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: Uint32Array[], aKeys: string[], bKeys: string[]): Op[] {
+  const ops: Op[] = [];
+  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] ?? 0) >= (dp[i]![j - 1] ?? 0)) {
+      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/{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;