glossarist 0.4.40 → 0.4.42

package/src/models/localized-concept.ts

@@ -0,0 +1,284 @@
+import { GlossaristModel } from './base.js';
+import { Designation } from './designation.js';
+import { DetailedDefinition } from './detailed-definition.js';
+import { ConceptSource } from './concept-source.js';
+import { ConceptDate } from './concept-date.js';
+import { NonVerbRep } from './non-verb-rep.js';
+import { RelatedConcept } from './related-concept.js';
+
+function wrapAs<T>(
+  Cls: new (...args: never[]) => T,
+): (item: unknown) => T {
+  return (item: unknown): T =>
+    item instanceof Cls ? item : new Cls(item as never);
+}
+
+const LOC_WIRE_NAMES: Readonly<Record<string, string>> = Object.freeze({
+  entryStatus: 'entry_status',
+  reviewType: 'review_type',
+  lineageSourceSimilarity: 'lineage_source_similarity',
+  reviewDate: 'review_date',
+  reviewDecisionDate: 'review_decision_date',
+  reviewDecisionEvent: 'review_decision_event',
+  reviewStatus: 'review_status',
+  reviewDecision: 'review_decision',
+  reviewDecisionNotes: 'review_decision_notes',
+});
+
+export interface LocalizedConceptJson {
+  language_code?: string | null;
+  languageCode?: string | null;
+  script?: string | null;
+  system?: string | null;
+  entry_status?: string | null;
+  entryStatus?: string | null;
+  classification?: string | null;
+  review_type?: string | null;
+  reviewType?: string | null;
+  domain?: string | null;
+  release?: string | null;
+  lineage_source_similarity?: string | null;
+  lineageSourceSimilarity?: string | null;
+  review_date?: string | null;
+  reviewDate?: string | null;
+  review_decision_date?: string | null;
+  reviewDecisionDate?: string | null;
+  review_decision_event?: string | null;
+  reviewDecisionEvent?: string | null;
+  review_status?: string | null;
+  reviewStatus?: string | null;
+  review_decision?: string | null;
+  reviewDecision?: string | null;
+  review_decision_notes?: string | null;
+  reviewDecisionNotes?: string | null;
+  terms?: ReadonlyArray<unknown>;
+  definition?: ReadonlyArray<unknown>;
+  sources?: ReadonlyArray<unknown>;
+  notes?: ReadonlyArray<unknown>;
+  annotations?: ReadonlyArray<unknown>;
+  examples?: ReadonlyArray<unknown>;
+  dates?: ReadonlyArray<unknown>;
+  non_verbal_rep?: ReadonlyArray<unknown>;
+  non_verb?: ReadonlyArray<unknown>;
+  related?: ReadonlyArray<unknown>;
+}
+
+type SlotName = 'definitions' | 'notes' | 'examples' | 'annotations';
+
+export class LocalizedConcept extends GlossaristModel {
+  static get DIFF_FIELDS(): ReadonlyArray<string> {
+    return Object.freeze([
+      'entryStatus', 'classification', 'reviewType', 'domain', 'release',
+      'lineageSourceSimilarity', 'script', 'system',
+      'reviewDate', 'reviewDecisionDate', 'reviewDecisionEvent',
+      'reviewStatus', 'reviewDecision', 'reviewDecisionNotes',
+    ]);
+  }
+
+  static wireNameFor(field: string): string {
+    return LOC_WIRE_NAMES[field] ?? field;
+  }
+
+  readonly languageCode: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly entryStatus: string | null;
+  readonly classification: string | null;
+  readonly reviewType: string | null;
+  readonly domain: string | null;
+  readonly release: string | null;
+  readonly lineageSourceSimilarity: string | null;
+  readonly reviewDate: string | null;
+  readonly reviewDecisionDate: string | null;
+  readonly reviewDecisionEvent: string | null;
+  readonly reviewStatus: string | null;
+  readonly reviewDecision: string | null;
+  readonly reviewDecisionNotes: string | null;
+
+  private readonly _rawTerms: ReadonlyArray<unknown>;
+  private readonly _rawDefinition: ReadonlyArray<unknown>;
+  private readonly _rawSources: ReadonlyArray<unknown>;
+  private readonly _rawNotes: ReadonlyArray<unknown>;
+  private readonly _rawAnnotations: ReadonlyArray<unknown>;
+  private readonly _rawExamples: ReadonlyArray<unknown>;
+  private readonly _rawDates: ReadonlyArray<unknown>;
+  private readonly _rawNonVerbal: ReadonlyArray<unknown>;
+  private readonly _rawRelated: ReadonlyArray<unknown>;
+  private _terms: ReadonlyArray<Designation> | null = null;
+  private _definitions: ReadonlyArray<DetailedDefinition> | null = null;
+  private _sources: ReadonlyArray<ConceptSource> | null = null;
+  private _notes: ReadonlyArray<DetailedDefinition> | null = null;
+  private _annotations: ReadonlyArray<DetailedDefinition> | null = null;
+  private _examples: ReadonlyArray<DetailedDefinition> | null = null;
+  private _dates: ReadonlyArray<ConceptDate> | null = null;
+  private _nonVerbal: ReadonlyArray<NonVerbRep> | null = null;
+  private _related: ReadonlyArray<RelatedConcept> | null = null;
+
+  constructor(data: LocalizedConceptJson = {}) {
+    super();
+    this.languageCode = data.language_code ?? data.languageCode ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.entryStatus = data.entry_status ?? data.entryStatus ?? null;
+    this.classification = data.classification ?? null;
+    this.reviewType = data.review_type ?? data.reviewType ?? null;
+    this.domain = data.domain ?? null;
+    this.release = data.release ?? null;
+    this.lineageSourceSimilarity =
+      data.lineage_source_similarity ?? data.lineageSourceSimilarity ?? null;
+    this.reviewDate = data.review_date ?? data.reviewDate ?? null;
+    this.reviewDecisionDate = data.review_decision_date ?? data.reviewDecisionDate ?? null;
+    this.reviewDecisionEvent = data.review_decision_event ?? data.reviewDecisionEvent ?? null;
+    this.reviewStatus = data.review_status ?? data.reviewStatus ?? null;
+    this.reviewDecision = data.review_decision ?? data.reviewDecision ?? null;
+    this.reviewDecisionNotes = data.review_decision_notes ?? data.reviewDecisionNotes ?? null;
+
+    this._rawTerms = data.terms ?? [];
+    this._rawDefinition = data.definition ?? [];
+    this._rawSources = data.sources ?? [];
+    this._rawNotes = data.notes ?? [];
+    this._rawAnnotations = data.annotations ?? [];
+    this._rawExamples = data.examples ?? [];
+    this._rawDates = data.dates ?? [];
+    this._rawNonVerbal = data.non_verbal_rep ?? data.non_verb ?? [];
+    this._rawRelated = data.related ?? [];
+  }
+
+  get terms(): ReadonlyArray<Designation> {
+    return this._lazy<Designation>(
+      '_terms',
+      '_rawTerms',
+      (t) => Designation.fromData(t),
+    );
+  }
+
+  get definitions(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_definitions',
+      '_rawDefinition',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get definition(): ReadonlyArray<DetailedDefinition> {
+    return this.definitions;
+  }
+
+  get sources(): ReadonlyArray<ConceptSource> {
+    return this._lazy<ConceptSource>(
+      '_sources',
+      '_rawSources',
+      wrapAs(ConceptSource),
+    );
+  }
+
+  get notes(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_notes',
+      '_rawNotes',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get annotations(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_annotations',
+      '_rawAnnotations',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get examples(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_examples',
+      '_rawExamples',
+      wrapAs(DetailedDefinition),
+    );
+  }
+
+  get dates(): ReadonlyArray<ConceptDate> {
+    return this._lazy<ConceptDate>(
+      '_dates',
+      '_rawDates',
+      wrapAs(ConceptDate),
+    );
+  }
+
+  get nonVerbalRep(): ReadonlyArray<NonVerbRep> {
+    return this._lazy<NonVerbRep>(
+      '_nonVerbal',
+      '_rawNonVerbal',
+      wrapAs(NonVerbRep),
+    );
+  }
+
+  get related(): ReadonlyArray<RelatedConcept> {
+    return this._lazy<RelatedConcept>(
+      '_related',
+      '_rawRelated',
+      wrapAs(RelatedConcept),
+    );
+  }
+
+  get primaryDesignation(): string | null {
+    return this.terms[0]?.designation ?? null;
+  }
+
+  get primaryDefinition(): string | null {
+    return this.definitions[0]?.content ?? null;
+  }
+
+  private *_textSlots(): Generator<[SlotName, ReadonlyArray<DetailedDefinition>]> {
+    yield ['definitions', this.definitions];
+    yield ['notes', this.notes];
+    yield ['examples', this.examples];
+    yield ['annotations', this.annotations];
+  }
+
+  *walkTexts(basePath: string): Generator<{ text: string; source: string }> {
+    for (const [name, arr] of this._textSlots()) {
+      for (let i = 0; i < arr.length; i++) {
+        const item = arr[i];
+        if (!item) continue;
+        yield* item.walkTexts(`${basePath}.${name}[${i}]`);
+      }
+    }
+  }
+
+  override toJSON(): LocalizedConceptJson {
+    const obj: LocalizedConceptJson = {};
+    if (this.languageCode) obj.language_code = this.languageCode;
+    if (this.script) obj.script = this.script;
+    if (this.system) obj.system = this.system;
+    if (this.entryStatus) obj.entry_status = this.entryStatus;
+    if (this.classification) obj.classification = this.classification;
+    if (this.reviewType) obj.review_type = this.reviewType;
+    if (this.domain) obj.domain = this.domain;
+    if (this.release) obj.release = this.release;
+    if (this.lineageSourceSimilarity != null) {
+      obj.lineage_source_similarity = this.lineageSourceSimilarity;
+    }
+    if (this.reviewDate) obj.review_date = this.reviewDate;
+    if (this.reviewDecisionDate) obj.review_decision_date = this.reviewDecisionDate;
+    if (this.reviewDecisionEvent) obj.review_decision_event = this.reviewDecisionEvent;
+    if (this.reviewStatus) obj.review_status = this.reviewStatus;
+    if (this.reviewDecision) obj.review_decision = this.reviewDecision;
+    if (this.reviewDecisionNotes) obj.review_decision_notes = this.reviewDecisionNotes;
+
+    this._serialize(obj as unknown as Record<string, unknown>, 'terms', '_terms', '_rawTerms');
+    this._serialize(obj as unknown as Record<string, unknown>, 'definition', '_definitions', '_rawDefinition');
+    this._serialize(obj as unknown as Record<string, unknown>, 'notes', '_notes', '_rawNotes');
+    this._serialize(obj as unknown as Record<string, unknown>, 'annotations', '_annotations', '_rawAnnotations');
+    this._serialize(obj as unknown as Record<string, unknown>, 'examples', '_examples', '_rawExamples');
+    this._serialize(obj as unknown as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    this._serialize(obj as unknown as Record<string, unknown>, 'dates', '_dates', '_rawDates');
+    this._serialize(obj as unknown as Record<string, unknown>, 'non_verbal_rep', '_nonVerbal', '_rawNonVerbal');
+    this._serialize(obj as unknown as Record<string, unknown>, 'related', '_related', '_rawRelated');
+
+    return obj;
+  }
+
+  static override fromJSON(data: LocalizedConceptJson): LocalizedConcept {
+    return new LocalizedConcept(data);
+  }
+}

package/src/models/{relation-loader.js → relation-loader.ts}

@@ -4,43 +4,52 @@
 // dispatches each file to the appropriate class (PartitiveHyperedge,
 // GenericHyperedge, future leaves) based on its `type` field, via
 // HyperedgeRegistry.
-//
-// The wire-shape contract is owned by the JSON Schema at
-// `schemas/v3/relation.yaml` (concept-model repo) — this loader
-// produces the corresponding JS model instances. See
-// docs/design/relations-as-files.md (concept-model).
-//
-// Adding a new hyperedge type means: declare the leaf class with the
-// metadata block, register it. The loader picks it up automatically —
-// no edits here.
 
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import type { Dirent } from 'node:fs';
 import * as yaml from 'js-yaml';
 import { HyperedgeRegistry } from './hyperedge-registry.js';
+import type { HyperedgeClass } from './hyperedge-registry.js';
+import type { AbstractHyperedge } from './abstract-hyperedge.js';
 
-// Backward-compat: snapshot of registered classes keyed by typeTag.
-// Prefer HyperedgeRegistry.forTypeTag() for new code — this snapshot
-// is frozen at module load and won't pick up runtime registrations
-// from tests (the OCP test in Phase 11 registers a mock type after
-// import).
-export const TYPE_TO_CLASS = new Proxy({}, {
-  get(_target, prop) {
-    return HyperedgeRegistry.forTypeTag(prop);
-  },
-  ownKeys() {
-    return HyperedgeRegistry.allTypeTags();
-  },
-  getOwnPropertyDescriptor() {
-    return { enumerable: true, configurable: true };
+interface HyperedgeDocument {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface HyperedgeClassWithFromJson extends HyperedgeClass {
+  fromJSON(data: unknown): AbstractHyperedge;
+}
+
+/**
+ * Backward-compat: snapshot of registered classes keyed by typeTag.
+ * Prefer HyperedgeRegistry.forTypeTag() for new code — this snapshot
+ * is frozen at module load and won't pick up runtime registrations
+ * from tests (the OCP test in Phase 11 registers a mock type after
+ * import).
+ */
+export const TYPE_TO_CLASS = new Proxy(
+  {} as Record<string, HyperedgeClass>,
+  {
+    get(_target: unknown, prop: string | symbol): HyperedgeClass | null {
+      return typeof prop === 'string' ? HyperedgeRegistry.forTypeTag(prop) : null;
+    },
+    ownKeys(): string[] {
+      return HyperedgeRegistry.allTypeTags();
+    },
+    getOwnPropertyDescriptor(): PropertyDescriptor {
+      return { enumerable: true, configurable: true };
+    },
   },
-});
+);
 
 /**
  * Thrown by `loadAll` when a relation file has an unknown `type`,
  * malformed structure, or a class that fails to instantiate.
  */
 export class RelationLoadError extends Error {
-  constructor(path, message) {
+  readonly path: string;
+  constructor(path: string, message: string) {
     super(`relation-loader: ${path}: ${message}`);
     this.path = path;
   }
@@ -51,32 +60,27 @@ export class RelationLoadError extends Error {
  * returning a Map keyed by comprehensive-id.
  *
  * Returns an empty Map if `relationsDir` doesn't exist or is empty.
- *
- * @param {string} relationsDir — path to a `relations/` directory
- *   containing `<comprehensive-id>/<slug>.yaml` files (per the
- *   schema in schemas/v3/relation.yaml).
- * @returns {Map<string, Array<AbstractHyperedge>>} — for each
- *   comprehensive id, the list of relations that have it as their
- *   comprehensive.
  */
-export function loadAll(relationsDir) {
-  const result = new Map();
+export function loadAll(
+  relationsDir: string | null | undefined,
+): Map<string, AbstractHyperedge[]> {
+  const result = new Map<string, AbstractHyperedge[]>();
   if (!relationsDir) return result;
   if (!existsSync(relationsDir)) return result;
 
   const entries = readdirSync(relationsDir, { withFileTypes: true });
-  for (const compEntry of entries) {
+  for (const compEntry of entries as Dirent[]) {
     if (!compEntry.isDirectory()) continue;
     const compId = compEntry.name;
     const compDir = `${relationsDir}/${compId}`;
     if (!result.has(compId)) result.set(compId, []);
     const files = readdirSync(compDir)
-      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+      .filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'))
       .sort();
     for (const file of files) {
       const path = `${compDir}/${file}`;
       const rel = loadOne(path);
-      if (rel) result.get(compId).push(rel);
+      if (rel) result.get(compId)?.push(rel);
     }
   }
   return result;
@@ -93,19 +97,19 @@ export const RelationLoader = Object.freeze({ loadAll, loadOne });
 /**
  * Load a single relation file. Returns null if the file is missing,
  * unreadable, or doesn't have a recognized `type` field. Throws
- * `RelationLoadError` on malformed content (e.g., invalid `members`
- * count, wrong comprehensive shape, YAML parse error).
+ * `RelationLoadError` on malformed content.
  */
-export function loadOne(path) {
-  let doc;
+export function loadOne(path: string): AbstractHyperedge | null {
+  let doc: unknown;
   try {
     doc = yaml.load(readFileSync(path, 'utf8'));
   } catch (e) {
-    throw new RelationLoadError(path, `YAML parse failed: ${e.message}`);
+    throw new RelationLoadError(path, `YAML parse failed: ${(e as Error).message}`);
   }
   if (!doc || typeof doc !== 'object') return null;
-  if (!doc.type) return null;
-  const Cls = HyperedgeRegistry.forTypeTag(doc.type);
-  if (!Cls) return null;  // Unknown type — let the validator report it
-  return Cls.fromJSON(doc);
+  const d = doc as HyperedgeDocument;
+  if (!d.type) return null;
+  const Cls = HyperedgeRegistry.forTypeTag(d.type) as HyperedgeClassWithFromJson | null;
+  if (!Cls) return null;
+  return Cls.fromJSON(d);
 }

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