glossarist 0.4.19 → 0.4.22

package/src/diff/index.d.ts

@@ -29,8 +29,13 @@ export function diffText(oldText: string | null | undefined, newText: string | n
 export const CHANGE_ADDED: 'added';
 export const CHANGE_REMOVED: 'removed';
 export const CHANGE_CHANGED: 'changed';
+export const CHANGE_MATCHED: 'matched';
 
-export type ChangeType = typeof CHANGE_ADDED | typeof CHANGE_REMOVED | typeof CHANGE_CHANGED;
+export type ChangeType =
+  | typeof CHANGE_ADDED
+  | typeof CHANGE_REMOVED
+  | typeof CHANGE_CHANGED
+  | typeof CHANGE_MATCHED;
 
 export class Change extends GlossaristModel {
   readonly type: ChangeType;
@@ -66,6 +71,13 @@ export class Changed extends Change {
   static fromJSON(data: Record<string, unknown>): Changed;
 }
 
+export class Matched extends Change {
+  readonly type: 'matched';
+  readonly value: unknown;
+  toJSON(): { type: 'matched'; path?: string; value: unknown };
+  static fromJSON(data: Record<string, unknown>): Matched;
+}
+
 export function deserializeChange(data: Record<string, unknown>): Change;
 
 // ── List diff ──────────────────────────────────────────────────────────
@@ -126,6 +138,7 @@ export class ConceptLevelDiff extends GlossaristModel {
   readonly sources: ListDiff;
   readonly dates: ListDiff;
   readonly relatedConcepts: ListDiff;
+  readonly partitiveHyperedges: ListDiff;
   readonly groups: ListDiff;
   readonly sections: ListDiff;
   readonly tags: ListDiff;
@@ -147,6 +160,9 @@ export class LocalizedConceptDiff extends GlossaristModel {
   readonly related: ListDiff;
   readonly metadata: MetadataDiff;
   readonly hasChanges: boolean;
+  readonly stats: DiffStats;
+  readonly similarity: number;
+  readonly totalItems: number;
   walk(prefix?: string): Generator<DiffWalkEntry, void, unknown>;
   toJSON(): Record<string, unknown>;
   static fromJSON(data: Record<string, unknown>): LocalizedConceptDiff;
@@ -161,6 +177,8 @@ export class ConceptDiff extends GlossaristModel {
   readonly hasChanges: boolean;
   readonly localizationLanguages: string[];
   readonly stats: DiffStats;
+  readonly similarity: number;
+  readonly totalItems: number;
   localization(lang: string): LocalizedConceptDiff | null;
   walk(): Generator<ConceptDiffWalkEntry, void, unknown>;
   toJSON(): Record<string, unknown>;
@@ -177,3 +195,48 @@ export function diffLocalizedConcepts(
   oldLoc: any | null,
   newLoc: any | null,
 ): LocalizedConceptDiff;
+
+// ── Collection diff ────────────────────────────────────────────────────
+
+export class ConceptCollectionDiff extends GlossaristModel {
+  readonly oldCount: number;
+  readonly newCount: number;
+  readonly matched: Matched[];
+  readonly added: Added[];
+  readonly removed: Removed[];
+  readonly conceptDiffs: Record<string, ConceptDiff>;
+  readonly changedIds: string[];
+  readonly hasChanges: boolean;
+  readonly stats: DiffStats;
+  readonly similarity: number;
+  conceptDiff(id: string): ConceptDiff | null;
+  walk(): Generator<ConceptDiffWalkEntry, void, unknown>;
+  toJSON(): Record<string, unknown>;
+  static fromJSON(data: Record<string, unknown>): ConceptCollectionDiff;
+}
+
+export function diffConceptCollections(
+  oldCollection: any | null,
+  newCollection: any | null,
+  options?: { language?: string; skipUnchanged?: boolean },
+): ConceptCollectionDiff;
+
+// ── Rendering ──────────────────────────────────────────────────────────
+
+export interface RenderOptions {
+  colors?: boolean;
+  showUnchanged?: boolean;
+}
+
+export function renderConceptDiff(diff: ConceptDiff, options?: RenderOptions): string;
+export function renderCollectionDiff(diff: ConceptCollectionDiff, options?: RenderOptions): string;
+export function renderTextDiff(textDiff: TextDiff | Record<string, unknown>, options?: RenderOptions): string;
+
+// ── Patching ───────────────────────────────────────────────────────────
+
+export function applyDiff<T extends { toJSON(): Record<string, unknown> }>(
+  oldConcept: T,
+  diff: ConceptDiff,
+): T;
+
+export function reverseDiff(diff: ConceptDiff): ConceptDiff;

package/src/diff/index.js

@@ -9,9 +9,11 @@ export {
   Added,
   Removed,
   Changed,
+  Matched,
   CHANGE_ADDED,
   CHANGE_REMOVED,
   CHANGE_CHANGED,
+  CHANGE_MATCHED,
   deserializeChange,
 } from './change.js';
 

package/src/diff/similarity.js

@@ -0,0 +1,24 @@
+// Similarity scoring for the diff layer.
+//
+// `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).
+
+export const SIMILARITY_PRECISION_DECIMALS = 4;
+const _SCALE = 10 ** SIMILARITY_PRECISION_DECIMALS;
+
+export function computeSimilarity(changeCount, totalItems) {
+  if (totalItems <= 0) return 1.0;
+  const ratio = Math.min(changeCount / totalItems, 1);
+  return Math.round((1 - ratio) * _SCALE) / _SCALE;
+}
+
+export function averageSimilarity(values) {
+  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/index.d.ts

@@ -13,6 +13,8 @@ export {
   BibliographyEntry, BibliographyData,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
+  PartitiveHyperedge, PARTITIVE_ENUMERATION, PARTITIVE_ENUMERATION_VALUES,
+  PLURALITY_MARKER, PLURALITY_MARKER_VALUES,
 } from './models/index';
 
 // Concept diff

package/src/index.js

@@ -63,6 +63,8 @@ export {
   fetchLocalizedString, localizedStringIsEmpty, localizedStringIsPresent,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
+  PartitiveHyperedge, PARTITIVE_ENUMERATION, PARTITIVE_ENUMERATION_VALUES,
+  PLURALITY_MARKER, PLURALITY_MARKER_VALUES,
 } from './models/index.js';
 
 export { AssetIndex } from './validators/asset-index.js';

package/src/migration/partitive-relation-migrator.js

@@ -0,0 +1,99 @@
+// v1 → v2 PartitiveRelation migration.
+//
+// Pure function: takes a v1 PartitiveHyperedge hash, returns a v2
+// PartitiveRelation hash. Idempotent. Used by the parser when loading
+// legacy YAML; available as a public API for one-shot dataset migrations.
+//
+// Field mapping (per TODO.partitive-relation-v2 items 01–05 and the
+// ISO 704:2022 correction):
+//
+//   comprehensive      → comprehensive     (unchanged shape)
+//   parts: [ref, ...]  → partitives: [{ ref, multiplicity: 'compulsory' }, ...]
+//   enumeration: open  → completeness: partial
+//   enumeration: closed→ completeness: complete
+//   markers: [...]     → (dropped — v2 uses per-member multiplicity
+//                          + is_delimiting; v1 markers encoded the
+//                          same information imprecisely and cannot
+//                          round-trip losslessly)
+//   content: "..."     → (dropped — structural edges carry no prose)
+//
+// Cardinality check: v1 allowed [1..*] parts; v2 requires [2..*].
+// A v1 hyperedge with exactly 1 part cannot migrate to v2 and is
+// returned with a `migrationWarning` field set so callers can decide
+// whether to surface it (the parser drops these with a warning).
+
+export function migrateHyperedgeToRelation(v1Hash) {
+  if (v1Hash == null) return null;
+  if (Array.isArray(v1Hash)) {
+    return v1Hash.map(migrateHyperedgeToRelation);
+  }
+
+  const out = {
+    comprehensive: { ...(v1Hash.comprehensive ?? {}) },
+  };
+
+  const parts = Array.isArray(v1Hash.parts) ? v1Hash.parts : [];
+  out.partitives = parts.map(ref => ({
+    ref: { ...ref },
+    multiplicity: 'compulsory',
+  }));
+
+  out.completeness = _migrateEnumeration(v1Hash.enumeration);
+
+  // v1 content + markers fields are dropped per TODO.partitive-relation-v2.
+  if (parts.length < 2) {
+    out.migrationWarning =
+      `v1 PartitiveHyperedge had ${parts.length} part(s); v2 requires ≥2. ` +
+      `Either add more partitives or convert to a binary has_part edge.`;
+  }
+
+  if (v1Hash.content != null) {
+    out.migrationWarning = (out.migrationWarning ?? '') +
+      ` v1 'content' field was dropped (v2 PartitiveRelation carries no prose; ` +
+      `move valuable text to the comprehensive concept's notes).`;
+  }
+
+  if (Array.isArray(v1Hash.markers) && v1Hash.markers.length > 0) {
+    out.migrationWarning = (out.migrationWarning ?? '') +
+      ` v1 'markers' field (${v1Hash.markers.join(', ')}) was dropped; ` +
+      `v2 uses per-member 'multiplicity' + 'is_delimiting'. Reviewer ` +
+      `should set these per partitive based on ISO 704:2022 notation.`;
+  }
+
+  return out;
+}
+
+// Inverse — v2 → v1 — exists only for tooling that must round-trip
+// through v1 consumers. NOT used by the parser; the serializer emits
+// v2 only. Lossy: drops criterion, multiplicity, is_delimiting.
+export function downgradeRelationToHyperedge(v2Hash) {
+  if (v2Hash == null) return null;
+  if (Array.isArray(v2Hash)) {
+    return v2Hash.map(downgradeRelationToHyperedge);
+  }
+
+  const out = {
+    comprehensive: { ...(v2Hash.comprehensive ?? {}) },
+  };
+
+  out.parts = (v2Hash.partitives ?? []).map(m => ({ ...(m.ref ?? {}) }));
+  out.enumeration = _downgradeCompleteness(v2Hash.completeness);
+
+  // criterion, multiplicity, is_delimiting have no v1 equivalent —
+  // dropped silently.
+
+  return out;
+}
+
+function _migrateEnumeration(value) {
+  if (value === 'open') return 'partial';
+  if (value === 'closed') return 'complete';
+  if (value == null) return 'complete';
+  // Unknown values default to complete (safe default — v2's safe default).
+  return 'complete';
+}
+
+function _downgradeCompleteness(value) {
+  if (value === 'partial') return 'open';
+  return 'closed';
+}

package/src/models/completeness.js

@@ -0,0 +1,24 @@
+// Completeness — whether a PartitiveRelation's encoded partitives
+// constitute the whole comprehensive (complete) or only some of it
+// (partial).
+//
+// ISO 704 depicts this as the rake's backline: a backline ending with
+// a tooth is complete; a backline continuing without a tooth is
+// partial.
+//
+// Renamed from the v1 `PartitiveEnumeration` (closed|open) per
+// TODO.partitive-relation-v2 item 02. The semantic claim being
+// expressed is completeness of the decomposition, not "enumeration"
+// (which is a neutral-sounding word that doesn't convey the claim).
+
+import { makeEnum } from './enum.js';
+
+export const COMPLETENESS = makeEnum('COMPLETENESS', {
+  COMPLETE: 'complete',
+  PARTIAL: 'partial',
+});
+
+export const COMPLETENESS_VALUES = COMPLETENESS.VALUES;
+export const isValidCompleteness = COMPLETENESS.isValid;
+
+export const DEFAULT_COMPLETENESS = COMPLETENESS.COMPLETE;

package/src/models/concept-date.js

@@ -15,6 +15,14 @@ export class ConceptDate extends GlossaristModel {
     return this.date ? new Date(this.date) : null;
   }
 
+  static identityOf(value) {
+    return value?.type ?? '';
+  }
+
+  identity() {
+    return ConceptDate.identityOf(this);
+  }
+
   toJSON() {
     const obj = {};
     if (this.date != null) obj.date = this.date;

package/src/models/concept-ref.js

@@ -26,6 +26,10 @@ export class ConceptRef extends GlossaristModel {
     return obj;
   }
 
+  identity() {
+    return `${this.source ?? ''}|${this.id ?? ''}`;
+  }
+
   static fromJSON(data) {
     return new ConceptRef(data);
   }

package/src/models/concept-source.js

@@ -11,11 +11,18 @@ export class ConceptSource extends GlossaristModel {
       ? (data.origin instanceof Citation ? data.origin : new Citation(data.origin))
       : null;
     this.modification = data.modification ?? null;
-    this.sourced_from = (data.sourced_from ?? []).map(
+    this.sourcedFrom = (data.sourcedFrom ?? data.sourced_from ?? []).map(
       c => c instanceof Citation ? c : new Citation(c)
     );
   }
 
+  // Backward-compat alias for callers using the snake_case JS field name.
+  // Prefer `.sourcedFrom` going forward; the wire name remains
+  // `sourced_from` (see toJSON).
+  get sourced_from() {
+    return this.sourcedFrom;
+  }
+
   toJSON() {
     const obj = {};
     if (this.id != null) obj.id = this.id;
@@ -23,10 +30,22 @@ export class ConceptSource extends GlossaristModel {
     if (this.type != null) obj.type = this.type;
     if (this.origin != null) obj.origin = this.origin.toJSON();
     if (this.modification != null) obj.modification = this.modification;
-    if (this.sourced_from.length > 0) obj.sourced_from = this.sourced_from.map(c => c.toJSON());
+    if (this.sourcedFrom.length > 0) {
+      obj.sourced_from = this.sourcedFrom.map(c => c.toJSON());
+    }
     return obj;
   }
 
+  static identityOf(value) {
+    const v = value ?? {};
+    const ref = v?.origin?.ref ?? (v?.origin instanceof Citation ? v.origin.ref : null);
+    return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
+  }
+
+  identity() {
+    return ConceptSource.identityOf(this);
+  }
+
   static fromJSON(data) {
     return new ConceptSource(data);
   }

package/src/models/concept.js

@@ -1,6 +1,9 @@
 import { GlossaristModel } from './base.js';
 import { LocalizedConcept } from './localized-concept.js';
 import { RelatedConcept } from './related-concept.js';
+import { PartitiveHyperedge } from './partitive-hyperedge.js';
+import { PartitiveRelation } from './partitive-relation.js';
+import { migrateHyperedgeToRelation } from '../migration/partitive-relation-migrator.js';
 import { ConceptReference } from './concept-reference.js';
 import { ConceptDate } from './concept-date.js';
 import { ConceptSource } from './concept-source.js';
@@ -10,6 +13,18 @@ import { FormulaReference } from './non-verbal-references.js';
 import { diffConcepts } from '../diff/concept-diff.js';
 
 export class Concept extends GlossaristModel {
+  // Scalar fields the diff layer tracks at the concept level. Adding
+  // a new scalar metadata field requires only appending its name here;
+  // diff detection, patch application, and similarity scoring all pick
+  // it up automatically. (Invariant N2 — TODO.hyperedges-v2/07.)
+  static get DIFF_FIELDS() {
+    return Object.freeze(['status', 'term', 'uri', 'schemaVersion']);
+  }
+
+  static wireNameFor(field) {
+    return CONCEPT_WIRE_NAMES[field] ?? field;
+  }
+
   constructor(data = {}) {
     super();
     this.id = String(data.id ?? data.termid ?? '');
@@ -19,6 +34,12 @@ export class Concept extends GlossaristModel {
     this._cache = {};
 
     this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related ?? data.related_concepts ?? [], RelatedConcept);
+    this.partitiveRelations = _resolvePartitiveRelations(data);
+    // Backward-compat alias: v1 callers reading .partitiveHyperedges
+    // get the v2 relations (the v1 model is preserved at
+    // ../partitive-hyperedge.js for direct instantiation, but Concept
+    // exposes only v2).
+    this.partitiveHyperedges = this.partitiveRelations;
     this.domains = _normalizeDomains(data.domains, data.groups);
     this.groups = Array.isArray(data.groups)
       ? data.groups.map(g => typeof g === 'string' ? g : (g?.id ?? g?.sectionId ?? null)).filter(Boolean)
@@ -181,6 +202,9 @@ export class Concept extends GlossaristModel {
     if (this.relatedConcepts.length > 0) {
       obj.related = this.relatedConcepts.map(rc => rc.toJSON());
     }
+    if (this.partitiveRelations.length > 0) {
+      obj.partitive_relations = this.partitiveRelations.map(r => r.toJSON());
+    }
     if (this.domains.length > 0) {
       obj.domains = this.domains.map(d => d.toJSON());
     }
@@ -210,6 +234,37 @@ function _mapInstances(arr, Cls) {
   return arr.map(item => item instanceof Cls ? item : new Cls(item));
 }
 
+// Resolve partitive relations from any of three input shapes:
+//   1. data.partitiveRelations (v2, preferred)
+//   2. data.partitive_relations (v2 wire name)
+//   3. data.partitiveHyperedges / data.partitive_hyperedges (v1, migrated)
+//
+// v1 input is auto-migrated to v2 via the migrator. v1 instances
+// already constructed (rare — only direct callers) are migrated field
+// by field. The parser produces plain hashes so the common path is (3).
+function _resolvePartitiveRelations(data) {
+  if (Array.isArray(data.partitiveRelations)) {
+    return data.partitiveRelations.map(r =>
+      r instanceof PartitiveRelation ? r : new PartitiveRelation(r));
+  }
+  if (Array.isArray(data.partitive_relations)) {
+    return data.partitive_relations.map(r => new PartitiveRelation(r));
+  }
+  const v1 = data.partitiveHyperedges ?? data.partitive_hyperedges;
+  if (Array.isArray(v1)) {
+    return v1
+      .map(h => h instanceof PartitiveHyperedge ? h.toJSON() : h)
+      .map(migrateHyperedgeToRelation)
+      .filter(h => h != null)
+      .map(h => new PartitiveRelation(h));
+  }
+  return [];
+}
+
+const CONCEPT_WIRE_NAMES = Object.freeze({
+  schemaVersion: 'schema_version',
+});
+
 function _normalizeDomains(domains, groups) {
   if (domains) {
     return domains.map(d => d instanceof ConceptReference ? d : new ConceptReference(d));

package/src/models/designation.js

@@ -91,6 +91,21 @@ export class Designation extends RegistrableModel {
     return SKOS_LABEL_BY_NORMATIVE_STATUS[status] ?? 'altLabel';
   }
 
+  // Static identity works on a model instance OR its plain JSON form.
+  // The diff layer uses this so that patch-side identity (computed on
+  // plain JSON from toJSON) matches diff-side identity (computed on
+  // model instances).
+  static identityOf(value) {
+    const v = value ?? {};
+    const type = v.type ?? 'expression';
+    const text = String(v.designation ?? '').toLowerCase().trim();
+    return `${type}|${text}`;
+  }
+
+  identity() {
+    return Designation.identityOf(this);
+  }
+
   static fromJSON(data) {
     return Designation.fromData(data);
   }

package/src/models/detailed-definition.js

@@ -1,5 +1,6 @@
 import { GlossaristModel } from './base.js';
 import { Citation } from './citation.js';
+import { canonicalJson } from '../diff/canonical-json.js';
 
 export class DetailedDefinition extends GlossaristModel {
   constructor(data = {}) {
@@ -42,6 +43,16 @@ export class DetailedDefinition extends GlossaristModel {
     }
   }
 
+  static identityOf(value) {
+    if (value == null) return '';
+    if (typeof value.toJSON === 'function') return canonicalJson(value.toJSON());
+    return canonicalJson(value);
+  }
+
+  identity() {
+    return DetailedDefinition.identityOf(this);
+  }
+
   static fromJSON(data) {
     return new DetailedDefinition(data);
   }

package/src/models/enum.js

@@ -0,0 +1,42 @@
+// Enum factory — produces a frozen KEY/VALUES bundle, a frozen values
+// array, and an isValid* predicate from a single `makeEnum` call.
+//
+// Adding a new enum means one line:
+//
+//   export const COLOR = makeEnum('COLOR', { RED: 'red', BLUE: 'blue' });
+//
+// The factory returns:
+//   {
+//     CLOSED: 'closed',           // exposed by destructuring
+//     OPEN:   'open',
+//     VALUES: ['closed', 'open'],  // frozen array
+//     isValid: (v) => boolean,     // predicate
+//   }
+//
+// We attach the bundle via Object.assign on a frozen object so the
+// bundle is itself frozen and exposes both the per-value constants
+// (CLOSED, OPEN, ...) and the VALUES list + isValid predicate.
+
+export function makeEnum(name, values) {
+  if (typeof name !== 'string') {
+    throw new Error(`makeEnum: name must be a string, got ${typeof name}`);
+  }
+  if (typeof values !== 'object' || values === null) {
+    throw new Error(`makeEnum: values must be an object, got ${typeof values}`);
+  }
+  for (const [k, v] of Object.entries(values)) {
+    if (typeof v !== 'string') {
+      throw new Error(`makeEnum(${name}): value for ${k} must be a string, got ${typeof v}`);
+    }
+  }
+
+  const frozen = Object.freeze({ ...values });
+  const valuesArr = Object.freeze(Object.values(frozen));
+  const isValid = (v) => valuesArr.includes(v);
+
+  return Object.assign(Object.create(null), frozen, {
+    name,
+    VALUES: valuesArr,
+    isValid,
+  });
+}

package/src/models/hyperedge-colors.js

@@ -0,0 +1,71 @@
+// Hyperedge color resolver — resolves display colors for a
+// PartitiveHyperedge based on its enumeration and the carrying
+// concept's category color.
+//
+// Closed hyperedges render at full intensity (the relationship is
+// definitive — these are ALL the parts). Open hyperedges render at
+// reduced intensity (the relationship is partial — other parts may
+// exist).
+//
+// Marker-based styling (double = thicker stroke, dashed = dashed
+// pattern) is the caller's responsibility; this resolver returns
+// the color only, plus a `pattern` hint for marker-based styling.
+
+import { categoryColorPair } from './relation-colors.js';
+
+const ENUMERATION_INTENSITY = Object.freeze({
+  closed: 1.0,
+  open: 0.55,
+});
+
+const DEFAULT_CATEGORY = 'hierarchical';
+
+export function resolveHyperedgeColor(hyperedge, options = {}) {
+  if (!hyperedge) return null;
+
+  const category = options.category ?? DEFAULT_CATEGORY;
+  const base = categoryColorPair(category, options.overrides);
+  if (!base) return null;
+
+  const intensity = ENUMERATION_INTENSITY[hyperedge.enumeration] ?? 1.0;
+  const pattern = derivePattern(hyperedge.markers);
+
+  return {
+    light: tint(base.light, intensity),
+    dark: tint(base.dark, intensity),
+    pattern,
+  };
+}
+
+function derivePattern(markers) {
+  const arr = markers ?? [];
+  if (arr.includes('dashed')) return 'dashed';
+  if (arr.includes('double')) return 'double';
+  return null;
+}
+
+// Linear interpolation between the base color and white (light mode)
+// or between the base and a neutral (dark mode). Pure-string inputs
+// return the original color when intensity === 1.0.
+function tint(hex, ratio) {
+  if (ratio >= 1.0) return hex;
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+
+  const target = [255, 255, 255];
+  const mixed = rgb.map((c, i) =>
+    Math.round(c + (target[i] - c) * (1 - ratio)));
+  return '#' + mixed.map(c => c.toString(16).padStart(2, '0')).join('');
+}
+
+function parseHex(s) {
+  if (typeof s !== 'string') return null;
+  const m = s.match(/^#?([0-9a-f]{6})$/i);
+  if (!m) return null;
+  const n = m[1];
+  return [
+    parseInt(n.slice(0, 2), 16),
+    parseInt(n.slice(2, 4), 16),
+    parseInt(n.slice(4, 6), 16),
+  ];
+}