glossarist 0.4.49 → 0.4.51

package/src/rdf/deterministic-id.ts

@@ -1,69 +0,0 @@
-// Stable ID helpers for RDF emission. Mirrors glossarist-ruby's
-// Digest::MD5.hexdigest(content)[0..11] for cross-runtime stability.
-//
-// Browser safety: node:crypto is loaded lazily so bundlers don't
-// tree-shake the import into browser bundles. The runtime check uses
-// `createRequire` from `node:module` (also lazy) which is the
-// documented way to use CommonJS `require` from ESM.
-
-let nodeCreateHash: ((alg: string) => { update(data: string): { digest(enc: string): string } }) | null = null;
-let nodeCryptoChecked = false;
-
-function getNodeCreateHash() {
-  if (nodeCryptoChecked) return nodeCreateHash;
-  nodeCryptoChecked = true;
-  try {
-    // Lazy require — works in both CJS and ESM (Node ≥ 12).
-    // Wrapped in Function() so bundlers don't statically resolve it.
-    let requireFn;
-    try {
-      // ESM: use createRequire from node:module
-      const mod = (Function('m', 'return require(m)'))('node:module');
-      requireFn = mod.createRequire(import.meta.url);
-    } catch {
-      // CJS or already-require-available environment
-      requireFn = (m: string) => (Function('m', 'return require(m)'))(m);
-    }
-    const crypto = requireFn('node:crypto');
-    nodeCreateHash = crypto.createHash.bind(crypto);
-  } catch {
-    nodeCreateHash = null;
-  }
-  return nodeCreateHash;
-}
-
-// 12-char hex prefix, mirroring glossarist-ruby's
-// `Digest::MD5.hexdigest(content)[0..11]`. Same content → same ID across
-// processes, machines, and language runtimes (Ruby vs JS) when MD5 is
-// available. Falls back to a 12-char FNV-1a hash in the browser.
-export function deterministicId(...parts: ReadonlyArray<unknown>): string {
-  const seed = parts.filter(p => p !== null && p !== undefined).join('|');
-  const createHash = getNodeCreateHash();
-  if (createHash) {
-    return createHash('md5').update(seed).digest('hex').slice(0, 12);
-  }
-  return fnv1a12(seed);
-}
-
-// Stable blank-node label for an RDF fragment identified by its parent
-// subject + role + index.
-export function deterministicBnode(subject: string, role: string, index: number): string {
-  return `_:b${deterministicId(subject, role, index)}`;
-}
-
-// 12-char FNV-1a hash.
-function fnv1a12(seed: string): string {
-  let h1 = 0x811c9dc5;
-  for (let i = 0; i < seed.length; i++) {
-    h1 ^= seed.charCodeAt(i);
-    h1 = Math.imul(h1, 0x01000193);
-  }
-  const seed2 = `${seed}|fnv2`;
-  let h2 = 0x811c9dc5;
-  for (let i = 0; i < seed2.length; i++) {
-    h2 ^= seed2.charCodeAt(i);
-    h2 = Math.imul(h2, 0x01000193);
-  }
-  return ((h1 >>> 0).toString(16).padStart(8, '0')
-    + (h2 >>> 0).toString(16).padStart(8, '0')).slice(0, 12);
-}

package/src/rdf/document-writer.ts

@@ -1,87 +0,0 @@
-// Quads → canonical Turtle / N-Triples / JSON-LD document.
-//
-// Turtle is produced via N3.Writer. JSON-LD via the `jsonld` package
-// (fromRDF + compact against the canonical context). N-Triples is provided
-// as a stable fallback that doesn't depend on prefix maps.
-import { Writer as N3Writer } from 'n3';
-import jsonld from 'jsonld';
-import { PREFIXES } from './prefixes.js';
-
-// Collects all quads yielded by an emitter into an array. Useful for tests
-// and for callers that want to inspect the quad stream directly.
-export function collectQuads(quadsIterable) {
-  const out: unknown[] = [];
-  for (const q of quadsIterable) out.push(q);
-  return out;
-}
-
-// Returns a Turtle serialization of `quads` using the canonical prefix map
-// generated from the vendored concept-model JSON-LD context. Quads are
-// sorted deterministically so the same input always produces byte-equivalent
-// output across runs.
-export function writeTurtle(quads, { prefixes = PREFIXES } = {}) {
-  const sorted = sortQuads(quads);
-  return new Promise((resolve, reject) => {
-    const writer = new N3Writer({ prefixes, format: 'Turtle' });
-    for (const q of sorted) writer.addQuad(q);
-    writer.end((err, result) => {
-      if (err) reject(err);
-      else resolve(result);
-    });
-  });
-}
-
-// Returns an N-Triples serialization of `quads` — no prefixes, no bnode
-// shortening. Useful when consumers need a totally stable wire format.
-export function writeNTriples(quads) {
-  const sorted = sortQuads(quads);
-  return new Promise((resolve, reject) => {
-    const writer = new N3Writer({ format: 'N-Triples' });
-    for (const q of sorted) writer.addQuad(q);
-    writer.end((err, result) => {
-      if (err) reject(err);
-      else resolve(result);
-    });
-  });
-}
-
-// Returns a compacted JSON-LD serialization of `quads`. The context defaults
-// to the canonical glossarist JSON-LD context derived from the vendored
-// PREFIXES. Quads are sorted first for deterministic output.
-export async function writeJsonld(quads, { context = defaultJsonldContext() } = {}) {
-  const sorted = sortQuads(quads);
-  const nquads = await writeNTriples(sorted);
-  const expanded = await jsonld.fromRDF(nquads, { format: 'application/n-quads' });
-  const compacted = await jsonld.compact(expanded, context);
-  return JSON.stringify(compacted, null, 2);
-}
-
-function defaultJsonldContext() {
-  const ctx = {};
-  for (const [prefix, uri] of Object.entries(PREFIXES)) {
-    ctx[prefix] = uri;
-  }
-  return ctx;
-}
-
-// Sort by (subject.value, predicate.value, object.termType, object.value,
-// graph.value). Bnodes sort by their generated ID which is deterministic
-// because we use content-addressed IDs.
-export function sortQuads(quads) {
-  return [...quads].sort(compareQuad);
-}
-
-function compareQuad(a, b) {
-  let cmp = cmpTerm(a.subject, b.subject);
-  if (cmp !== 0) return cmp;
-  cmp = cmpTerm(a.predicate, b.predicate);
-  if (cmp !== 0) return cmp;
-  cmp = cmpTerm(a.object, b.object);
-  if (cmp !== 0) return cmp;
-  return cmpTerm(a.graph, b.graph);
-}
-
-function cmpTerm(a, b) {
-  if (a.termType !== b.termType) return a.termType.localeCompare(b.termType);
-  return String(a.value).localeCompare(String(b.value));
-}

package/src/rdf/gloss-concept.ts

@@ -1,115 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-// Concept → RDF quads. Mirrors glossarist-ruby's `Rdf::GlossConcept`.
-//
-// URI shape: `<uriBase>/<registerId>/concept/<conceptId>`.
-// Localized concepts: `<uriBase>/<registerId>/concept/<conceptId>/<lang>`.
-// Figure/Table/Formula references: `<uriBase>/<registerId>/<kind>/<entityId>`.
-import { PRED } from './predicates.js';
-import { WELL_KNOWN } from './prefixes.js';
-import { localizedConceptToQuads } from './gloss-localized-concept.js';
-import { conceptSourceToQuads } from './gloss-source.js';
-import { partitiveRelationToQuads, partitiveRelationSubjectUri } from './gloss-partitive-relation.js';
-import { genericHyperedgeToQuads, genericHyperedgeSubjectUri, GENERIC_HYPEREDGE_LINK_PREDICATE } from './gloss-generic-hyperedge.js';
-import { PartitiveHyperedge } from '../models/partitive-hyperedge.js';
-import { GenericHyperedge } from '../models/generic-hyperedge.js';
-import { namedNode, literal, quad } from './terms.js';
-
-// Per-type RDF emitter dispatch. Keyed by class. Adding a new hyperedge
-// type with its own emitter means: (1) write the emitter module,
-// (2) add one entry here. Per TODO Phase 6e this should be a
-// self-registering registry; for the two current types, the dispatch
-// table is simpler and keeps the dependency graph acyclic.
-const HYPEREDGE_EMITTERS: Map<unknown, Record<string, unknown>> = new Map([
-  [PartitiveHyperedge, {
-    linkPredicate: PRED.gloss.hasPartitiveRelation,
-    subjectUri: partitiveRelationSubjectUri,
-    toQuads: partitiveRelationToQuads,
-  }],
-  [GenericHyperedge, {
-    linkPredicate: GENERIC_HYPEREDGE_LINK_PREDICATE,
-    subjectUri: genericHyperedgeSubjectUri,
-    toQuads: genericHyperedgeToQuads,
-  }],
-]);
-
-// Kind tag → URI segment. Each NonVerbalReference subtype has a
-// predictable URL path so the same entity is reachable from any
-// concept that references it.
-const NVR_KIND_SEGMENT = {
-  FigureReference: 'figure',
-  TableReference: 'table',
-  FormulaReference: 'formula',
-};
-
-// Builds the URI for a NonVerbalReference target entity. Returns null
-// when the reference has no entityId (e.g., inline display-only refs).
-function nonVerbalReferenceUri(ref, options) {
-  const kind = NVR_KIND_SEGMENT[ref.constructor.name];
-  if (!kind || !ref.entityId) return null;
-  const base = String(options.uriBase ?? '').replace(/\/+$/, '');
-  return `${base}/${options.registerId}/${kind}/${ref.entityId}`;
-}
-
-export function conceptUri(concept, { registerId, uriBase }) {
-  const id = String(concept.id ?? concept.termid ?? '');
-  const base = String(uriBase ?? '').replace(/\/+$/, '');
-  return `${base}/${registerId}/concept/${id}`;
-}
-
-export function* conceptToQuads(concept, options) {
-  const subjectUri = conceptUri(concept, options);
-  const s = namedNode(subjectUri);
-
-  yield quad(s, namedNode(WELL_KNOWN.rdfType), namedNode(PRED.gloss.Concept));
-  yield quad(s, namedNode(WELL_KNOWN.rdfType), namedNode(WELL_KNOWN.skosConcept));
-
-  yield quad(s, namedNode(PRED.gloss.identifier), literal(String(concept.id ?? concept.termid ?? '')));
-
-  if (concept.status) {
-    yield quad(s, namedNode(PRED.gloss.hasStatus), namedNode(`${PRED.gloss.$ns}status/${concept.status}`));
-  }
-
-  // NonVerbal references — emit the link quad only. The actual
-  // Figure/Table/Formula entity quads are emitted by `nonVerbalEntityToQuads`
-  // when the dataset's NVR collection is iterated.
-  for (const ref of [...(concept.figures ?? []), ...(concept.tables ?? []), ...(concept.formulas ?? [])]) {
-    const targetUri = nonVerbalReferenceUri(ref, options);
-    if (targetUri) {
-      yield quad(s, namedNode(PRED.gloss.hasNonVerbalRep), namedNode(targetUri));
-    }
-  }
-
-  for (const lang of concept.languages) {
-    const lc = concept.localization(lang);
-    if (!lc) continue;
-    const lcUri = `${subjectUri}/${lang}`;
-    yield quad(s, namedNode(PRED.gloss.hasLocalization), namedNode(lcUri));
-    yield* localizedConceptToQuads(lc, { parentUri: subjectUri, language: lang });
-  }
-
-  let srcIndex = 0;
-  for (const source of concept.sources ?? []) {
-    yield* conceptSourceToQuads(source, { subjectUri, index: srcIndex });
-    srcIndex += 1;
-  }
-
-  // Iterate the unified relations array. Dispatch via per-type
-  // emitter table.
-  let relIdx = 0;
-  for (const relation of concept.relations ?? []) {
-    const emitter = HYPEREDGE_EMITTERS.get(relation.constructor) as unknown as { linkPredicate: string; subjectUri: (a: string, b: unknown, c: number) => string; toQuads: (a: unknown, b: { parentUri: string; index: number }) => Iterable<unknown> } | undefined;
-    if (!emitter) {
-      // Unknown hyperedge type — skip rather than crash. The OCP
-      // contract (Phase 11) tests that new types register an emitter;
-      // skipping here gives external consumers a soft-failure path
-      // when they pass around abstract hyperedges the JS layer doesn't
-      // recognize yet.
-      relIdx += 1;
-      continue;
-    }
-    const relSubject = emitter.subjectUri(subjectUri, relation, relIdx);
-    yield quad(s, namedNode(emitter.linkPredicate), namedNode(relSubject));
-    yield* emitter.toQuads(relation, { parentUri: subjectUri, index: relIdx });
-    relIdx += 1;
-  }
-}

package/src/rdf/gloss-designation.ts

@@ -1,72 +0,0 @@
-// Designation → RDF quads. Mirrors glossarist-ruby's
-// `Rdf::GlossDesignation` + the per-subtype classes (GlossExpression,
-// GlossAbbreviation, etc.). The ontology class for each subtype is
-// provided by the model itself via Designation#rdfClass (OCP: new
-// subtypes register without editing this emitter).
-import { PRED, PREFIXES } from './predicates.js';
-import { SKOSXL, WELL_KNOWN } from './prefixes.js';
-import { deterministicBnode } from './deterministic-id.js';
-import { normalizeEnum } from './normalize-enum.js';
-import { namedNode, literal, quad } from './terms.js';
-
-const XSD_BOOLEAN = 'http://www.w3.org/2001/XMLSchema#boolean';
-
-// Boolean flag fields on designation subtypes. Each entry maps a model
-// field name to its ontology predicate. Only emitted when the value is
-// truthy, so legacy data without the fields round-trips unchanged.
-const BOOLEAN_FLAGS = [
-  ['acronym', PRED.gloss.isAcronym],
-  ['initialism', PRED.gloss.isInitialism],
-  ['truncation', PRED.gloss.isTruncation],
-  ['international', PRED.gloss.isInternational],
-  ['absent', PRED.gloss.isAbsent],
-];
-
-// Returns the SKOS-XL predicate (as a string URI) appropriate for this
-// designation's normative status. Mirrors `skosxl_label_for` in Ruby.
-// The dispatch lives on the Designation model so a new status requires
-// a single edit there, not here.
-export function skosxlLabelPredicate(designation) {
-  return designation.skosxlLabelPredicate(PREFIXES.skosxl);
-}
-
-// Returns the matching plain-SKOS predicate URI (skos:prefLabel etc.).
-// Used when emitting direct SKOS alongside reified SKOS-XL.
-export function skosLabelPredicate(designation) {
-  return designation.skosLabelPredicate(PREFIXES.skos);
-}
-
-// Emits quads for one designation. Yields them lazily so callers can
-// compose many designations into a single stream without intermediate
-// arrays.
-//
-// `subjectUri` is the URI of the LocalizedConcept that owns this designation.
-// `index` is the position of the designation within its parent's terms list
-// — used to make the bnode ID deterministic.
-export function* designationToQuads(designation, { subjectUri, language, index }) {
-  const desigSubject = deterministicBnode(subjectUri, 'desig', index);
-
-  const labelPredicate = namedNode(skosxlLabelPredicate(designation));
-  yield quad(namedNode(subjectUri), labelPredicate, namedNode(desigSubject));
-
-  yield quad(namedNode(desigSubject), namedNode(WELL_KNOWN.rdfType), namedNode(`${PRED.gloss.$ns}${designation.rdfClass()}`));
-  yield quad(namedNode(desigSubject), namedNode(WELL_KNOWN.rdfType), namedNode(WELL_KNOWN.skosxlLabel));
-  yield quad(namedNode(desigSubject), namedNode(SKOSXL.literalForm), literal(designation.designation ?? '', language));
-
-  if (designation.normativeStatus) {
-    const statusToken = normalizeEnum(designation.normativeStatus);
-    if (statusToken) {
-      const statusUri = `${PRED.gloss.$ns}norm/${statusToken}`;
-      yield quad(namedNode(desigSubject), namedNode(PRED.gloss.normativeStatus), namedNode(statusUri));
-    }
-  }
-
-  // Subtype-specific boolean flags. Skipping when falsy preserves
-  // backward compatibility with simpler designations.
-  const booleanType = namedNode(XSD_BOOLEAN);
-  for (const [field, predicate] of BOOLEAN_FLAGS) {
-    if (designation[field as string]) {
-      yield quad(namedNode(desigSubject), namedNode(predicate as string), literal('true', booleanType));
-    }
-  }
-}

package/src/rdf/gloss-detailed-definition.ts

@@ -1,69 +0,0 @@
-// DetailedDefinition → RDF quads. Mirrors glossarist-ruby's
-// `Rdf::GlossDetailedDefinition`. Used for definitions, notes, examples,
-// and annotations — they all share the same shape (content + optional
-// sources + nested examples).
-//
-// The emitter takes a `linkPredicate` (e.g. PRED.gloss.hasDefinition,
-// PRED.gloss.hasNote, PRED.gloss.hasExample) so callers can reuse it for
-// any role.
-import { PRED } from './predicates.js';
-import { WELL_KNOWN } from './prefixes.js';
-import { deterministicBnode } from './deterministic-id.js';
-import { namedNode, literal, quad } from './terms.js';
-
-export function* detailedDefinitionToQuads(definition, {
-  subjectUri, language, index, role,
-}) {
-  const linkPredicate = linkPredicateFor(role);
-  const defSubject = deterministicBnode(subjectUri, role, index);
-
-  yield quad(namedNode(subjectUri), namedNode(linkPredicate), namedNode(defSubject));
-  yield quad(namedNode(defSubject), namedNode(WELL_KNOWN.rdfType), namedNode(PRED.gloss.DetailedDefinition));
-
-  if (definition.content) {
-    yield quad(
-      namedNode(defSubject),
-      namedNode(WELL_KNOWN.rdfValue),
-      literal(definition.content, language),
-    );
-  }
-
-  // Plain SKOS direct literal — so non-SKOS-XL consumers see definitions.
-  // The reified form above carries the same text with sources/examples;
-  // this direct literal makes SPARQL `?c skos:definition ?d` work.
-  const directPredicate = directSkosPredicateFor(role);
-  if (directPredicate && definition.content) {
-    yield quad(namedNode(subjectUri), namedNode(directPredicate), literal(definition.content, language));
-  }
-
-  let exampleIndex = 0;
-  for (const example of definition.examples ?? []) {
-    yield* detailedDefinitionToQuads(example, {
-      subjectUri: defSubject, language, index: exampleIndex, role: 'hasScopedExample',
-    });
-    exampleIndex += 1;
-  }
-}
-
-function linkPredicateFor(role) {
-  switch (role) {
-    case 'hasDefinition': return PRED.gloss.hasDefinition;
-    case 'hasNote': return PRED.gloss.hasNote;
-    case 'hasExample': return PRED.gloss.hasExample;
-    case 'hasScopedExample': return PRED.gloss.hasScopedExample;
-    case 'hasAnnotation': return PRED.gloss.hasAnnotation;
-    default: throw new Error(`Unknown detailed-definition role: ${role}`);
-  }
-}
-
-function directSkosPredicateFor(role) {
-  switch (role) {
-    case 'hasDefinition': return PRED.skos.definition;
-    case 'hasNote': return PRED.skos.scopeNote;
-    case 'hasExample': return PRED.skos.example;
-    case 'hasScopedExample': return PRED.skos.example;
-    // No direct SKOS counterpart for annotations.
-    case 'hasAnnotation': return null;
-    default: return null;
-  }
-}

package/src/rdf/gloss-localized-concept.ts

@@ -1,79 +0,0 @@
-// LocalizedConcept → RDF quads. Mirrors glossarist-ruby's
-// `Rdf::GlossLocalizedConcept` + the `EmitsExtraTriples` hook.
-//
-// Emits BOTH reified SKOS-XL labels AND direct SKOS literals, so consumers
-// that don't implement SKOS-XL still see labels/definitions/notes/examples
-// as plain literals. This is the same shape glossarist-ruby emits after
-// WS-B Phase 1.
-import { PRED, PREFIXES } from './predicates.js';
-import { WELL_KNOWN } from './prefixes.js';
-import { designationToQuads, skosLabelPredicate } from './gloss-designation.js';
-import { detailedDefinitionToQuads } from './gloss-detailed-definition.js';
-import { conceptSourceToQuads } from './gloss-source.js';
-import { nonVerbalRepToQuads } from './gloss-non-verbal-rep.js';
-import { namedNode, literal, quad } from './terms.js';
-const DCTERMS_LANGUAGE = `${PREFIXES.dcterms}language`;
-
-export function localizedConceptUri(parentUri, language) {
-  return `${parentUri}/${language}`;
-}
-
-export function* localizedConceptToQuads(localizedConcept, { parentUri, language }) {
-  const subjectUri = localizedConceptUri(parentUri, language);
-  const s = namedNode(subjectUri);
-
-  yield quad(s, namedNode(WELL_KNOWN.rdfType), namedNode(PRED.gloss.LocalizedConcept));
-  yield quad(s, namedNode(WELL_KNOWN.rdfType), namedNode(WELL_KNOWN.skosConcept));
-  yield quad(s, namedNode(PRED.gloss.isLocalizationOf), namedNode(parentUri));
-  yield quad(s, namedNode(DCTERMS_LANGUAGE), literal(language));
-
-  if (localizedConcept.entryStatus) {
-    yield quad(s, namedNode(PRED.gloss.hasEntryStatus), namedNode(`${PRED.gloss.$ns}entstatus/${localizedConcept.entryStatus}`));
-  }
-  if (localizedConcept.domain) {
-    yield quad(s, namedNode(PRED.gloss.domain), literal(localizedConcept.domain));
-  }
-  if (localizedConcept.release) {
-    yield quad(s, namedNode(PRED.gloss.release), literal(localizedConcept.release));
-  }
-  if (localizedConcept.script) {
-    yield quad(s, namedNode(PRED.gloss.script), literal(localizedConcept.script));
-  }
-  if (localizedConcept.system) {
-    yield quad(s, namedNode(PRED.gloss.conversionSystem), literal(localizedConcept.system));
-  }
-
-  let desigIndex = 0;
-  for (const designation of localizedConcept.terms ?? []) {
-    yield* designationToQuads(designation, { subjectUri, language, index: desigIndex });
-    // Direct SKOS literal alongside the reified SKOS-XL form.
-    yield quad(s, namedNode(skosLabelPredicate(designation)), literal(designation.designation, language));
-    desigIndex += 1;
-  }
-
-  yield* definitionsToQuads(localizedConcept.definitions, { subjectUri, language, role: 'hasDefinition' });
-  yield* definitionsToQuads(localizedConcept.notes, { subjectUri, language, role: 'hasNote' });
-  yield* definitionsToQuads(localizedConcept.examples, { subjectUri, language, role: 'hasExample' });
-  yield* definitionsToQuads(localizedConcept.annotations, { subjectUri, language, role: 'hasAnnotation' });
-
-  let nvrIndex = 0;
-  for (const nvr of localizedConcept.nonVerbalRep ?? []) {
-    yield* nonVerbalRepToQuads(nvr, { parentUri: subjectUri, index: nvrIndex, language });
-    nvrIndex += 1;
-  }
-
-  let srcIndex = 0;
-  for (const source of localizedConcept.sources ?? []) {
-    yield* conceptSourceToQuads(source, { subjectUri, index: srcIndex });
-    srcIndex += 1;
-  }
-}
-
-function* definitionsToQuads(definitions, { subjectUri, language, role }) {
-  if (!definitions) return;
-  let i = 0;
-  for (const def of definitions) {
-    yield* detailedDefinitionToQuads(def, { subjectUri, language, index: i, role });
-    i += 1;
-  }
-}