glossarist 0.4.43 → 0.4.44

package/package.json

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

package/src/errors.ts

@@ -1,42 +1,23 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-/**
- * Base error for all glossarist errors.
- */
+/** Base error for all glossarist errors. */
 export class GlossaristError extends Error {
-  /**
-   * @param {string} message
-   * @param {{ cause?: Error }} [options]
-   */
-  constructor(message, options) {
+  constructor(message: string, options?: { cause?: Error }) {
     super(message, options);
     this.name = 'GlossaristError';
   }
 }
 
-/**
- * Thrown when a function receives invalid input (null, undefined, wrong type).
- */
+/** Thrown when a function receives invalid input (null, undefined, wrong type). */
 export class InvalidInputError extends GlossaristError {
-  /**
-   * @param {string} what - description of the invalid input
-   * @param {string} [expected] - description of what was expected
-   */
-  constructor(what, expected) {
+  constructor(what: string, expected?: string) {
     const msg = expected ? `${what} (expected ${expected})` : what;
     super(msg);
     this.name = 'InvalidInputError';
   }
 }
 
-/**
- * Thrown when YAML content cannot be parsed.
- */
+/** Thrown when YAML content cannot be parsed. */
 export class YamlParseError extends GlossaristError {
-  /**
-   * @param {string} context - what was being parsed (e.g. concept ID)
-   * @param {Error} cause - the original YAML parse error
-   */
-  constructor(context, cause) {
+  constructor(context: string, cause: Error) {
     super(`Failed to parse YAML for ${context}: ${cause.message}`, { cause });
     this.name = 'YamlParseError';
   }

package/src/migration/hyperedge-migrator.ts

@@ -1,120 +1,104 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 // v1 → v2 PartitiveHyperedge migration.
 //
 // Pure function: takes a v1 PartitiveHyperedge hash, returns a v2
-// PartitiveHyperedge 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, presence: 'required', count: 'exactly_one' }, ...]
-//   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).
-//
-// ─── Migration decision table (v1 markers → v2 multiplicity) ──────
-//
-// v1 markers encoded per-relation plurality claims. v2 multiplicity
-// is per-member. The mapping is lossy; reviewers must set per-member
-// multiplicity individually after migration.
-//
-//   | v1 markers              | Likely multiplicity for each partitive         | Notes                                                  |
-//   |-------------------------|------------------------------------------------|--------------------------------------------------------|
-//   | (none)                  | `compulsory`                                   | Default; reviewer confirms                             |
-//   | `[double]`              | `compulsory_multiple` or `compulsory_at_least_one` | Reviewer distinguishes "all required" from "≥1 required" |
-//   | `[dashed]`              | `optional` or `optional_multiple`              | Reviewer distinguishes single vs multiple              |
-//   | `[double, dashed]`      | `optional_multiple` or `compulsory_at_least_one` | Plurality claim; reviewer distinguishes uncertain vs required |
-//   | (single-part v1 edge)   | (cannot migrate — needs ≥2 partitives)         | Convert to a binary `has_part` edge                    |
-//
-// `is_delimiting` is NEVER set by migration. ISO 704:2022 says
-// delimiting depends on the concept system and coordinate concepts,
-// which migration cannot infer. Reviewer sets it based on domain
-// knowledge (see DelimitingCoherenceRule for cross-relation checks).
+// PartitiveHyperedge hash. Idempotent.
 
-export function migrateHyperedgeToRelation(v1Hash) {
+export interface V1HyperedgeHash {
+  comprehensive?: { source?: string; id?: string; text?: string };
+  parts?: ReadonlyArray<{ source?: string; id?: string }>;
+  enumeration?: string;
+  content?: string | null;
+  markers?: ReadonlyArray<string>;
+}
+
+export interface V2HyperedgeHash {
+  comprehensive: { source?: string; id?: string };
+  partitives: ReadonlyArray<{
+    ref: { source?: string; id?: string };
+    presence: string;
+    count: string;
+  }>;
+  completeness: string;
+  migrationWarning?: string;
+}
+
+export function migrateHyperedgeToRelation(
+  v1Hash: V1HyperedgeHash | ReadonlyArray<V1HyperedgeHash> | null,
+): V2HyperedgeHash | ReadonlyArray<V2HyperedgeHash | null> | null {
   if (v1Hash == null) return null;
   if (Array.isArray(v1Hash)) {
-    return v1Hash.map(migrateHyperedgeToRelation);
+    return v1Hash.map(migrateHyperedgeToRelation) as ReadonlyArray<V2HyperedgeHash | null>;
   }
 
-  const out = {
-    comprehensive: { ...(v1Hash.comprehensive ?? {}) },
+  const h = v1Hash as V1HyperedgeHash;
+  const out: Partial<V2HyperedgeHash> = {
+    comprehensive: { ...(h.comprehensive ?? {}) },
   };
 
-  const parts = Array.isArray(v1Hash.parts) ? v1Hash.parts : [];
-  out.partitives = parts.map(ref => ({
+  const parts = Array.isArray(h.parts) ? h.parts : [];
+  out.partitives = parts.map((ref) => ({
     ref: { ...ref },
     presence: 'required',
     count: 'exactly_one',
   }));
 
-  out.completeness = _migrateEnumeration(v1Hash.enumeration);
+  out.completeness = _migrateEnumeration(h.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) {
+  if (h.content != null) {
     out.migrationWarning = (out.migrationWarning ?? '') +
       ` v1 'content' field was dropped (v2 PartitiveHyperedge carries no prose; ` +
       `move valuable text to the comprehensive concept's notes).`;
   }
 
-  if (Array.isArray(v1Hash.markers) && v1Hash.markers.length > 0) {
+  if (Array.isArray(h.markers) && h.markers.length > 0) {
     out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'markers' field (${v1Hash.markers.join(', ')}) was dropped; ` +
+      ` v1 'markers' field (${h.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;
+  return out as V2HyperedgeHash;
 }
 
-// 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) {
+export function downgradeRelationToHyperedge(
+  v2Hash: Partial<V2HyperedgeHash> | ReadonlyArray<Partial<V2HyperedgeHash>> | null,
+): unknown {
   if (v2Hash == null) return null;
   if (Array.isArray(v2Hash)) {
     return v2Hash.map(downgradeRelationToHyperedge);
   }
 
-  const out = {
-    comprehensive: { ...(v2Hash.comprehensive ?? {}) },
+  const v2 = v2Hash as V2HyperedgeHash;
+  const out: {
+    comprehensive: { source?: string; id?: string };
+    parts: Array<{ source?: string; id?: string }>;
+    enumeration: string;
+  } = {
+    comprehensive: { ...(v2.comprehensive ?? {}) },
+    parts: [],
+    enumeration: '',
   };
 
-  out.parts = (v2Hash.partitives ?? []).map(m => ({ ...(m.ref ?? {}) }));
-  out.enumeration = _downgradeCompleteness(v2Hash.completeness);
-
-  // criterion, multiplicity, is_delimiting have no v1 equivalent —
-  // dropped silently.
+  out.parts = (v2.partitives ?? []).map((m) => ({ ...(m.ref ?? {}) }));
+  out.enumeration = _downgradeCompleteness(v2.completeness);
 
   return out;
 }
 
-function _migrateEnumeration(value) {
+function _migrateEnumeration(value: string | undefined): string {
   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) {
+function _downgradeCompleteness(value: string | undefined): string {
   if (value === 'partial') return 'open';
   return 'closed';
 }

package/src/models/concept.ts

@@ -467,7 +467,7 @@ function _migrateV1Hash(
   hash: Record<string, unknown>,
 ): Record<string, unknown> | null {
   if (cls === PartitiveHyperedge && v1Key === 'partitive_hyperedges') {
-    return migrateHyperedgeToRelation(hash) as Record<string, unknown>;
+    return migrateHyperedgeToRelation(hash) as unknown as Record<string, unknown>;
   }
   return null;
 }

package/src/sort.ts

@@ -1,14 +1,10 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 const NATURAL_SORT_RE = /(\d+|\D+)/g;
 const DIGIT_RE = /^\d+$/;
 
 /**
  * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
- * @param {string} a
- * @param {string} b
- * @returns {number}
  */
-export function naturalSort(a, b) {
+export function naturalSort(a: string, b: string): number {
   const pa = a.match(NATURAL_SORT_RE) || [];
   const pb = b.match(NATURAL_SORT_RE) || [];
   for (let i = 0; i < Math.max(pa.length, pb.length); i++) {

package/src/transforms/concept-to-gloss.transform.ts

@@ -1,14 +1,9 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-// ConceptToGlossTransform — JS port of glossarist-ruby's
-// `Transforms::ConceptToGlossTransform`. Converts a Concept model into
-// ontology-faithful RDF (Turtle, JSON-LD, N-Triples).
+// ConceptToGlossTransform — converts a Concept model into RDF.
 //
 // Usage:
-//   import { ConceptToGlossTransform } from 'glossarist/transforms';
-//   const xform = new ConceptToGlossTransform({ registerId: 'iso-6709', uriBase: 'https://glossarist.org' });
+//   const xform = new ConceptToGlossTransform({ registerId: 'iso-6709', uriBase: 'https://example.org' });
 //   const ttl = await xform.toTurtle(concept);
-//   const jsonld = await xform.toJsonld(concept);
-//   const ttlAll = await xform.toTurtleAll(concepts);
+
 import { conceptToQuads } from '../rdf/gloss-concept.js';
 import {
   collectQuads,
@@ -17,62 +12,70 @@ import {
   writeJsonld,
 } from '../rdf/document-writer.js';
 
-// No hardcoded default URI base. Callers MUST pass options.uriBase so
-// concept IRIs reflect the consumer's domain.
+type QuadLike = unknown;
+type ConceptLike = { registerId?: string; id?: string | number } & Record<string, unknown>;
+
+interface WriterEntry {
+  write: (quads: QuadLike[] | QuadLike, transform: ConceptToGlossTransform) => Promise<unknown>;
+}
 
-// Writer registry. Each entry is `{ write: (quads, transform) => Promise<string> }`.
-// Adding a new output format is a single entry here, not six new methods.
-const WRITERS = Object.freeze({
-  turtle:    { write: (quads) => writeTurtle(quads) },
-  ntriples:  { write: (quads) => writeNTriples(quads) },
-  jsonld:    { write: (quads, t) => writeJsonld(quads, t._jsonldOpts()) },
+const WRITERS: Readonly<Record<string, WriterEntry>> = Object.freeze({
+  turtle:   { write: (quads) => writeTurtle(quads as QuadLike[]) },
+  ntriples: { write: (quads) => writeNTriples(quads as QuadLike[]) },
+  jsonld:   { write: (quads, t) => writeJsonld(quads as QuadLike[], t._jsonldOpts() as never) },
 });
 
 export class ConceptToGlossTransform {
-  constructor(options = {}) {
+  readonly registerId: string | undefined;
+  readonly uriBase: string;
+  readonly jsonldContext: unknown;
+
+  constructor(options: { registerId?: string; uriBase?: string; jsonldContext?: unknown } = {}) {
     this.registerId = options.registerId;
-    this.uriBase = options.uriBase?.replace(/\/+$/, '');
-    if (!this.uriBase) throw new Error('ConceptToGlossTransform requires options.uriBase — the deployment canonical URI root.');
+    this.uriBase = (options.uriBase ?? '').replace(/\/+$/, '');
+    if (!this.uriBase) {
+      throw new Error(
+        'ConceptToGlossTransform requires options.uriBase — the deployment canonical URI root.',
+      );
+    }
     this.jsonldContext = options.jsonldContext;
   }
 
-  toTurtle(target)    { return this._serialize(target, 'turtle'); }
-  toTurtleAll(targets) { return this._serialize(targets, 'turtle'); }
-  toJsonld(target)    { return this._serialize(target, 'jsonld'); }
-  toJsonldAll(targets) { return this._serialize(targets, 'jsonld'); }
-  toNTriples(target)  { return this._serialize(target, 'ntriples'); }
-  toNTriplesAll(targets) { return this._serialize(targets, 'ntriples'); }
+  toTurtle(target: ConceptLike): Promise<unknown> { return this._serialize(target, 'turtle'); }
+  toTurtleAll(targets: Iterable<ConceptLike>): Promise<unknown> { return this._serialize(targets, 'turtle'); }
+  toJsonld(target: ConceptLike): Promise<unknown> { return this._serialize(target, 'jsonld'); }
+  toJsonldAll(targets: Iterable<ConceptLike>): Promise<unknown> { return this._serialize(targets, 'jsonld'); }
+  toNTriples(target: ConceptLike): Promise<unknown> { return this._serialize(target, 'ntriples'); }
+  toNTriplesAll(targets: Iterable<ConceptLike>): Promise<unknown> { return this._serialize(targets, 'ntriples'); }
 
-  // Single dispatcher: collect quads for one concept or many, then hand
-  // off to the registered writer. Replaces six near-identical methods.
-  async _serialize(target, format) {
+  async _serialize(target: ConceptLike | Iterable<ConceptLike>, format: string): Promise<unknown> {
     const writer = WRITERS[format];
     if (!writer) throw new Error(`Unknown serialization format: ${format}`);
     const quads = this._collect(target);
     return writer.write(quads, this);
   }
 
-  _collect(target) {
-    if (target && typeof target[Symbol.iterator] === 'function') {
-      const quads = [];
-      for (const concept of target) {
-        for (const q of conceptToQuads(concept, this._optsFor(concept))) {
+  _collect(target: ConceptLike | Iterable<ConceptLike>): QuadLike[] {
+    if (target && typeof (target as Iterable<ConceptLike>)[Symbol.iterator] === 'function') {
+      const quads: QuadLike[] = [];
+      for (const concept of target as Iterable<ConceptLike>) {
+        for (const q of conceptToQuads(concept as never, this._optsFor(concept))) {
           quads.push(q);
         }
       }
       return quads;
     }
-    return collectQuads(conceptToQuads(target, this._optsFor(target)));
+    return collectQuads(conceptToQuads(target as never, this._optsFor(target as ConceptLike)));
   }
 
-  _optsFor(concept) {
+  _optsFor(concept: ConceptLike): { registerId: string; uriBase: string } {
     return {
       registerId: this.registerId ?? concept.registerId ?? 'glossary',
       uriBase: this.uriBase,
     };
   }
 
-  _jsonldOpts() {
+  _jsonldOpts(): { context?: unknown } {
     return this.jsonldContext ? { context: this.jsonldContext } : {};
   }
 }

package/src/transforms/index.ts

@@ -1,2 +1 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 export { ConceptToGlossTransform } from './concept-to-gloss.transform.js';

package/src/uuid.ts

@@ -1,29 +1,32 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
 import { createHash } from 'crypto';
 
 const NAMESPACE_UUID = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
 
-export function uuidV5(namespace, name) {
+export function uuidV5(namespace: string, name: string): string {
   const ns = _parseUuid(namespace);
   const hash = createHash('sha1').update(ns).update(name, 'utf8').digest();
-  hash[6] = (hash[6] & 0x0f) | 0x50;
-  hash[8] = (hash[8] & 0x3f) | 0x80;
+  hash[6] = ((hash[6] ?? 0) & 0x0f) | 0x50;
+  hash[8] = ((hash[8] ?? 0) & 0x3f) | 0x80;
   return _formatUuid(hash);
 }
 
-export function conceptUuid(conceptId, namespace = NAMESPACE_UUID) {
+export function conceptUuid(conceptId: string, namespace: string = NAMESPACE_UUID): string {
   return uuidV5(namespace, conceptId);
 }
 
-export function localizedConceptUuid(conceptId, languageCode, namespace = NAMESPACE_UUID) {
+export function localizedConceptUuid(
+  conceptId: string,
+  languageCode: string,
+  namespace: string = NAMESPACE_UUID,
+): string {
   return uuidV5(namespace, `${conceptId}:${languageCode}`);
 }
 
-function _parseUuid(str) {
+function _parseUuid(str: string): Buffer {
   return Buffer.from(str.replace(/-/g, ''), 'hex');
 }
 
-function _formatUuid(hash) {
+function _formatUuid(hash: Buffer): string {
   const h = hash.toString('hex');
   return [h.slice(0, 8), h.slice(8, 12), h.slice(12, 16), h.slice(16, 20), h.slice(20, 32)].join('-');
 }