glossarist 0.4.50 → 0.4.51

package/src/concept-reader.d.ts

@@ -1,13 +0,0 @@
-import type { Concept, Register } from './models/index';
-
-/** Read all concept YAML files from a directory. */
-export function readConcepts(dir: string): Concept[];
-
-/** Read a single concept by ID from a directory. */
-export function readConcept(dir: string, id: string): Concept | null;
-
-/** List all concept IDs in a directory, optionally filtered by prefix. */
-export function listConceptIds(dir: string, prefix?: string): string[];
-
-/** Read register.yaml from a dataset directory (if present). */
-export function readRegister(dir: string): Register | null;

package/src/concept-serializer.ts

@@ -1,110 +0,0 @@
-import * as yaml from 'js-yaml';
-import { PartitiveHyperedge } from './models/partitive-hyperedge.js';
-import { GenericHyperedge } from './models/generic-hyperedge.js';
-
-const DUMP_OPTS = { lineWidth: -1, noRefs: true, sortKeys: false, skipInvalid: true };
-
-// Partition the unified relations array by concrete type and emit
-// each type under its own wire key. Concept.relations holds mixed
-// types; the wire format stays split for backward compat with
-// existing consumers and the JSON Schema in concept-model.
-function _emitTypedRelations(concept) {
-  const partitiveRels = concept.relations.filter(r => r instanceof PartitiveHyperedge);
-  const genericRels = concept.relations.filter(r => r instanceof GenericHyperedge);
-  return {
-    partitive: partitiveRels.map(r => r.toJSON()),
-    generic: genericRels.map(r => r.toJSON()),
-  };
-}
-
-export class ConceptSerializer {
-  toCanonicalYaml(concept) {
-    const doc = { termid: concept.id };
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.term) doc.term = concept.term;
-
-    const { partitive, generic } = _emitTypedRelations(concept);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (partitive.length > 0) doc.partitive_relations = partitive;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (generic.length > 0) doc.generic_relations = generic;
-
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (lc) {
-        const lcObj = lc.toJSON();
-        delete lcObj.language_code;
-        doc[lang] = lcObj;
-      }
-    }
-
-    return yaml.dump(doc, DUMP_OPTS);
-  }
-
-  toManagedYaml(concept, uuidFn) {
-    const genId = uuidFn ?? (() => crypto.randomUUID());
-    const localizedConcepts = {};
-    const langDocs = [];
-
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (!lc) continue;
-      const lcId = genId();
-      localizedConcepts[lang] = lcId;
-
-      const lcObj = lc.toJSON();
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      langDocs.push({ data: lcObj, id: lcId });
-    }
-
-    const mainDoc = {
-      data: { identifier: concept.id, localized_concepts: localizedConcepts },
-      id: genId(),
-    };
-
-    if (concept.domains.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.data.domains = concept.domains.map(d => d.toJSON());
-    }
-
-    if (concept.relatedConcepts.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.related = concept.relatedConcepts.map(rc => rc.toJSON());
-    }
-    const { partitive, generic } = _emitTypedRelations(concept);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (partitive.length > 0) mainDoc.partitive_relations = partitive;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (generic.length > 0) mainDoc.generic_relations = generic;
-    if (concept.sources.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.sources = concept.sources.map(s => s.toJSON());
-    }
-    if (concept.dates.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.dates = concept.dates.map(d => d.toJSON());
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.status) mainDoc.status = concept.status;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.schemaVersion) mainDoc.schema_version = concept.schemaVersion;
-
-    const parts = [
-      '---\n' + yaml.dump(mainDoc, DUMP_OPTS),
-      ...langDocs.map(d => '---\n' + yaml.dump(d, DUMP_OPTS)),
-    ];
-    return parts.join('');
-  }
-
-  toYaml(concept, uuidFn) {
-    return concept.term
-      ? this.toCanonicalYaml(concept)
-      : this.toManagedYaml(concept, uuidFn);
-  }
-
-  toRegisterYaml(data) {
-    return yaml.dump(data, DUMP_OPTS);
-  }
-}
-
-export const conceptSerializer = new ConceptSerializer();

package/src/concept-writer.d.ts

@@ -1,7 +0,0 @@
-import { Concept } from './models/index';
-
-export function writeConcept(dir: string, concept: Concept, format?: 'canonical' | 'managed' | 'auto'): void;
-export function writeConcepts(dir: string, concepts: Concept[], options?: {
-  register?: Record<string, unknown>;
-  format?: 'canonical' | 'managed' | 'auto';
-}): void;

package/src/concept-writer.ts

@@ -1,47 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { conceptSerializer } from './concept-serializer.js';
-import { InvalidInputError } from './errors.js';
-
-function assertDir(dir, fnName) {
-  if (typeof dir !== 'string' || dir.trim() === '') {
-    throw new InvalidInputError(`${fnName} requires a directory path`, 'non-empty string');
-  }
-}
-
-export function writeConcept(dir, concept, format = 'auto') {
-  assertDir(dir, 'writeConcept');
-  if (!concept?.id) {
-    throw new InvalidInputError('writeConcept requires a Concept with an id', 'Concept');
-  }
-
-  const y = format === 'canonical'
-    ? conceptSerializer.toCanonicalYaml(concept)
-    : format === 'managed'
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      ? conceptSerializer.toManagedYaml(concept)
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      : conceptSerializer.toYaml(concept);
-
-  fs.writeFileSync(path.join(dir, `${concept.id}.yaml`), y, 'utf8');
-}
-
-export function writeConcepts(dir, concepts, options = {}) {
-  assertDir(dir, 'writeConcepts');
-  fs.mkdirSync(dir, { recursive: true });
-
-  for (const concept of concepts) {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    writeConcept(dir, concept, options.format);
-  }
-
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  if (options.register) {
-    fs.writeFileSync(
-      path.join(dir, 'register.yaml'),
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      conceptSerializer.toRegisterYaml(options.register),
-      'utf8',
-    );
-  }
-}

package/src/diff/canonical-json.ts

@@ -1,29 +0,0 @@
-// Canonical JSON for equality comparison.
-//
-// 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.
-
-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: JsonInput | unknown, b: JsonInput | unknown): boolean {
-  return canonicalJson(a) === canonicalJson(b);
-}
-
-function toCanonical(value: JsonInput): unknown {
-  if (value == null) return null;
-  if (Array.isArray(value)) return value.map(toCanonical);
-  if (typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const k of Object.keys(value).sort()) {
-      const v = toCanonical((value as Record<string, JsonInput>)[k] as JsonInput);
-      if (v !== undefined) out[k] = v;
-    }
-    return out;
-  }
-  return value;
-}

package/src/diff/change.ts

@@ -1,175 +0,0 @@
-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.ts

@@ -1,245 +0,0 @@
-import { GlossaristModel } from '../models/base.js';
-import { Added, Removed, Matched, deserializeChange } from './change.js';
-import { ConceptDiff, DiffStats, diffConcepts } from './concept-diff.js';
-import { averageSimilarity } from './similarity.js';
-
-export class ConceptCollectionDiff extends GlossaristModel {
-  constructor(data: Record<string, unknown> = {}) {
-    super();
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this.oldCount = data.oldCount ?? data.old_count ?? 0;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this.newCount = data.newCount ?? data.new_count ?? 0;
-
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._matched = wrapIdList(data.matched, Matched);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._added = wrapIdList(data.added, Added);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._removed = wrapIdList(data.removed, Removed);
-
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._conceptDiffs = {};
-    const raw = data.conceptDiffs ?? data.concept_diffs ?? {};
-    for (const [id, diff] of Object.entries(raw)) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      this._conceptDiffs[id] = diff instanceof ConceptDiff
-        ? diff
-        : ConceptDiff.fromJSON(diff);
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._statsCache = undefined;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    this._similarityCache = undefined;
-  }
-
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  get matched() { return this._matched; }
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  get added() { return this._added; }
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  get removed() { return this._removed; }
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  get conceptDiffs() { return this._conceptDiffs; }
-
-  get changedIds() {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return Object.keys(this._conceptDiffs);
-  }
-
-  get hasChanges() {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return this._added.length > 0
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      || this._removed.length > 0
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      || Object.values(this._conceptDiffs).some(d => d.hasChanges);
-  }
-
-  conceptDiff(id) {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return this._conceptDiffs[id] ?? null;
-  }
-
-  get stats() {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (this._statsCache === undefined) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      let added = this._added.length;
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      let removed = this._removed.length;
-      let changed = 0;
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      for (const diff of Object.values(this._conceptDiffs)) {
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        const s = diff.stats;
-        added += s.added;
-        removed += s.removed;
-        changed += s.changed;
-      }
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      this._statsCache = new DiffStats({ added, removed, changed });
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return this._statsCache;
-  }
-
-  get similarity() {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (this._similarityCache === undefined) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      if (this._matched.length === 0) {
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        this._similarityCache = 0;
-      } else {
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        const values = this._matched.map(entry => {
-          const id = entry.value;
-          // @ts-expect-error TODO(Phase 2e): type this fully
-          const diff = this._conceptDiffs[id];
-          return diff ? diff.similarity : 1.0;
-        });
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        this._similarityCache = averageSimilarity(values);
-      }
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return this._similarityCache;
-  }
-
-  *walk() {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    for (let i = 0; i < this._added.length; i++) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      yield { path: `added[${i}]`, change: this._added[i] };
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    for (let i = 0; i < this._removed.length; i++) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      yield { path: `removed[${i}]`, change: this._removed[i] };
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    for (const [id, diff] of Object.entries(this._conceptDiffs)) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      for (const entry of diff.walk()) {
-        yield { path: `concepts.${id}.${entry.path}`, change: entry.change, conceptId: id, language: entry.language };
-      }
-    }
-  }
-
-  toJSON() {
-    const obj = {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      old_count: this.oldCount,
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      new_count: this.newCount,
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      matched: this._matched.map(c => c.toJSON()),
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      added: this._added.map(c => c.toJSON()),
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      removed: this._removed.map(c => c.toJSON()),
-      concept_diffs: {},
-    };
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    for (const [id, diff] of Object.entries(this._conceptDiffs)) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      obj.concept_diffs[id] = diff.toJSON();
-    }
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new ConceptCollectionDiff(data);
-  }
-}
-
-export function diffConceptCollections(oldCollection, newCollection, options = {}) {
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  const language = options.language ?? 'eng';
-
-  const oldConcepts = extractConcepts(oldCollection);
-  const newConcepts = extractConcepts(newCollection);
-
-  const oldMap = new Map(oldConcepts.map(c => [c.id, c]));
-  const newMap = new Map(newConcepts.map(c => [c.id, c]));
-
-  const oldIds = new Set(oldMap.keys());
-  const newIds = new Set(newMap.keys());
-
-  const matchedIds = [...newIds].filter(id => oldIds.has(id)).sort();
-  const addedIds = [...newIds].filter(id => !oldIds.has(id)).sort();
-  const removedIds = [...oldIds].filter(id => !newIds.has(id)).sort();
-
-  const conceptDiffs = {};
-  for (const id of matchedIds) {
-    const oldConcept = oldMap.get(id);
-    const newConcept = newMap.get(id);
-
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (options.skipUnchanged && conceptsEqual(oldConcept, newConcept)) {
-      continue;
-    }
-
-    const diff = diffConcepts(oldConcept, newConcept, language);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (diff.hasChanges || !options.skipUnchanged) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      conceptDiffs[id] = diff;
-    }
-  }
-
-  return new ConceptCollectionDiff({
-    oldCount: oldConcepts.length,
-    newCount: newConcepts.length,
-    matched: matchedIds.map(id => new Matched({ value: id })),
-    added: addedIds.map(id => new Added({ value: id })),
-    removed: removedIds.map(id => new Removed({ value: id })),
-    conceptDiffs,
-  });
-}
-
-function extractConcepts(collection) {
-  if (collection == null) return [];
-  if (Array.isArray(collection)) return collection;
-  if (typeof collection.toArray === 'function') return collection.toArray();
-  if (Symbol.iterator in Object(collection)) return [...collection];
-  return [];
-}
-
-function conceptsEqual(a, b) {
-  if (a === b) return true;
-  if (!a || !b) return false;
-  if (typeof a.equals === 'function' && typeof b.equals === 'function') {
-    return a.equals(b);
-  }
-  return JSON.stringify(a?.toJSON?.()) === JSON.stringify(b?.toJSON?.());
-}
-
-// `wrapIdList` deserializes each entry via deserializeChange, which
-// dispatches on `type`. The `expectedClass` parameter is a defensive
-// check: if the entry's deserialized type doesn't match the slot it's
-// being loaded into, throw. Prevents the round-1 bug where removed
-// entries silently became Added after a JSON round-trip.
-function wrapIdList(data, expectedClass) {
-  if (!data) return [];
-  return data.map(c => {
-    if (c instanceof Added || c instanceof Removed || c instanceof Matched) {
-      if (!(c instanceof expectedClass)) {
-        throw new Error(
-          `ConceptCollectionDiff: entry type ${c.constructor.name} ` +
-          `does not match slot ${expectedClass.name}`,
-        );
-      }
-      return c;
-    }
-    const deserialized = deserializeChange(c);
-    if (!(deserialized instanceof expectedClass)) {
-      throw new Error(
-        `ConceptCollectionDiff: deserialized entry type ` +
-        `${deserialized.constructor.name} does not match slot ${expectedClass.name}`,
-      );
-    }
-    return deserialized;
-  });
-}