glossarist 0.4.1 → 0.4.3

package/src/models/register.js

@@ -1,5 +1,6 @@
 import { GlossaristModel } from './base.js';
 import { Section } from './section.js';
+import { resolveColor } from './dataset-color.js';
 
 export const REGISTER_STATUSES = Object.freeze([
   'current',
@@ -27,6 +28,7 @@ export class Register extends GlossaristModel {
     this.languageOrder = data.languageOrder ?? data.language_order ?? [];
     this.ordering = data.ordering ?? null;
     this.logo = data.logo ?? null;
+    this.color = data.color ?? null;
     this.description = data.description ?? {};
     this.about = data.about ?? {};
     this.provenance = data.provenance ?? [];
@@ -45,7 +47,7 @@ export class Register extends GlossaristModel {
       'status', 'supersedes', 'owner',
       'sourceRepo', 'source_repo', 'tags',
       'languages', 'languageOrder', 'language_order',
-      'ordering', 'logo', 'description', 'about',
+      'ordering', 'logo', 'color', 'description', 'about',
       'provenance', 'contributors', 'sections',
     ]);
     const extra = {};
@@ -64,11 +66,60 @@ export class Register extends GlossaristModel {
     return null;
   }
 
+  // Walks the section tree upward from `sectionId`, returning the
+  // ancestor chain in immediate-parent-first order. The returned array
+  // does NOT include sectionId itself. Returns [] when sectionId is
+  // unknown or is a top-level section.
+  //
+  // Mirrors glossarist-ruby's section-cascading walk (commit 43dca6b)
+  // and the ontology's owl:TransitiveProperty declaration on
+  // gloss:hasParentSection.
+  sectionAncestorIds(sectionId) {
+    if (!sectionId) return [];
+    for (const root of this.sections) {
+      const chain = _ancestorChain(root, sectionId);
+      if (chain) return chain;
+    }
+    return [];
+  }
+
+  // Returns the closure of `sectionId`: the section plus all of its
+  // ancestors. Concept-section membership tests should intersect the
+  // concept's section list with this closure so a concept in section
+  // "3.1.1" matches a filter on "3.1" or "3".
+  sectionClosure(sectionId) {
+    return [sectionId, ...this.sectionAncestorIds(sectionId)];
+  }
+
+  // Returns all section IDs the concept belongs to: the concept's own
+  // sections plus every ancestor of each. Concept-side section
+  // membership comes from `concept.sections` if set, otherwise from
+  // `concept.groups` (a flat list of section IDs as strings).
+  //
+  // Returns the union (deduped) so callers can do a single
+  // intersection test.
+  conceptSectionIds(concept) {
+    const own = conceptSectionIdList(concept);
+    if (own.length === 0) return [];
+    const closure = new Set();
+    for (const id of own) {
+      for (const ancestor of this.sectionClosure(id)) closure.add(ancestor);
+    }
+    return [...closure];
+  }
+
   sectionName(sectionId, lang) {
     const section = this.sectionById(sectionId);
     return section ? section.name(lang) : null;
   }
 
+  // Returns the hex color for the requested UI mode, falling back to
+  // the single hex when the spec is a string. Returns null when no
+  // color is set or when the requested mode is missing.
+  resolvedColor(mode) {
+    return resolveColor(this.color, mode);
+  }
+
   toJSON() {
     const obj = { ...this._raw, schema_version: this.schemaVersion };
     if (this.id != null) obj.id = this.id;
@@ -86,6 +137,11 @@ export class Register extends GlossaristModel {
     if (this.languageOrder.length > 0) obj.languageOrder = [...this.languageOrder];
     if (this.ordering != null) obj.ordering = this.ordering;
     if (this.logo != null) obj.logo = { ...this.logo };
+    if (this.color != null) {
+      obj.color = (typeof this.color === 'object' && this.color !== null)
+        ? { ...this.color }
+        : this.color;
+    }
     if (Object.keys(this.description).length > 0) obj.description = { ...this.description };
     if (Object.keys(this.about).length > 0) obj.about = { ...this.about };
     if (this.provenance.length > 0) obj.provenance = this.provenance.map(p => ({ ...p }));
@@ -108,3 +164,45 @@ export class Register extends GlossaristModel {
     });
   }
 }
+
+// Recursive walk: returns the ancestor chain of `targetId` within the
+// subtree rooted at `section`, or null if targetId is not in this
+// subtree. The chain is immediate-parent-first; the section itself is
+// not included. Built root-first, then reversed for the documented order.
+function _ancestorChain(section, targetId, ancestors = []) {
+  if (section.id === targetId) return [...ancestors].reverse();
+  for (const child of section.children) {
+    const found = _ancestorChain(child, targetId, [...ancestors, section.id]);
+    if (found) return found;
+  }
+  return null;
+}
+
+// Returns the list of section IDs a concept claims membership in.
+// Concepts may carry section IDs via either `sections` (preferred) or
+// `groups` (legacy). Each entry may be a string or an object with an
+// `id` field; both forms are flattened to a string list.
+function conceptSectionIdList(concept) {
+  if (!concept) return [];
+  const fromSections = concept.sections
+    ? _flattenSectionIds(concept.sections)
+    : [];
+  const fromGroups = concept.groups
+    ? _flattenSectionIds(concept.groups)
+    : [];
+  return [...fromSections, ...fromGroups];
+}
+
+function _flattenSectionIds(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    if (typeof entry === 'string') {
+      out.push(entry);
+    } else if (entry && typeof entry === 'object') {
+      const id = entry.id ?? entry.sectionId ?? entry.ref?.id;
+      if (id) out.push(String(id));
+    }
+  }
+  return out;
+}

package/src/models/relation-categories.js

@@ -0,0 +1,151 @@
+// Categorization SSOT for the 52 glossarist relationship types.
+//
+// Each type in RELATIONSHIP_TYPES belongs to exactly one category. The
+// categories are semantic buckets used for filtering and visualization
+// in concept-browser. Bringing the categorization into glossarist-js
+// means all consumers see the same buckets.
+
+import { RELATIONSHIP_TYPES } from './related-concept.js';
+
+// Category definitions. The `types` array is the exhaustive list of
+// relationship-type local names that fall into the category. Each type
+// must appear in exactly one category (verified by MECE test).
+export const RELATION_CATEGORIES = Object.freeze({
+  lifecycle: Object.freeze({
+    label: 'Lifecycle',
+    description: 'Concept lifecycle transitions: supersession, deprecation, replacement.',
+    types: Object.freeze([
+      'deprecates', 'deprecated_by',
+      'supersedes', 'superseded_by',
+      'replaces', 'replaced_by',
+      'invalidates', 'invalidated_by',
+      'retires', 'retired_by',
+    ]),
+  }),
+
+  hierarchical: Object.freeze({
+    label: 'Hierarchical',
+    description: 'Broader/narrower relations, including SKOS and ISO 25964 generic/partitive/instantial.',
+    types: Object.freeze([
+      'broader', 'narrower',
+      'broader_generic', 'narrower_generic',
+      'broader_partitive', 'narrower_partitive',
+      'broader_instantial', 'narrower_instantial',
+    ]),
+  }),
+
+  associative: Object.freeze({
+    label: 'Associative',
+    description: 'Generic see-also references between concepts.',
+    types: Object.freeze([
+      'see', 'related_concept',
+      'related_concept_broader', 'related_concept_narrower',
+      'references',
+    ]),
+  }),
+
+  comparative: Object.freeze({
+    label: 'Comparative',
+    description: 'Compare / contrast relations between concepts.',
+    types: Object.freeze(['compare', 'contrast']),
+  }),
+
+  spatiotemporal: Object.freeze({
+    label: 'Spatiotemporal',
+    description: 'Sequential, spatial, and temporal relations.',
+    types: Object.freeze([
+      'sequentially_related_concept',
+      'spatially_related_concept',
+      'temporally_related_concept',
+    ]),
+  }),
+
+  lexical: Object.freeze({
+    label: 'Lexical',
+    description: 'Lexical relations between designations across languages.',
+    types: Object.freeze(['homograph', 'false_friend']),
+  }),
+
+  mapping: Object.freeze({
+    label: 'Mapping',
+    description: 'SKOS mapping properties for cross-vocabulary alignment.',
+    types: Object.freeze([
+      'equivalent', 'close_match',
+      'broad_match', 'narrow_match', 'related_match',
+    ]),
+  }),
+
+  conceptInstance: Object.freeze({
+    label: 'Concept / Instance',
+    description: 'ISO 19135 concept-to-concept relations: definition, part, instance, inheritance.',
+    types: Object.freeze([
+      'has_concept', 'is_concept_of',
+      'instance_of', 'has_instance',
+      'has_definition', 'definition_of',
+      'has_part', 'is_part_of',
+      'inherits', 'inherited_by',
+    ]),
+  }),
+
+  versioning: Object.freeze({
+    label: 'Versioning',
+    description: 'Version lineage within the same concept identity.',
+    types: Object.freeze([
+      'has_version', 'version_of',
+      'current_version', 'current_version_of',
+    ]),
+  }),
+});
+
+// Reverse index built once. Maps each type local name to its category.
+const _CATEGORY_BY_TYPE = (() => {
+  const map = new Map();
+  for (const [cat, def] of Object.entries(RELATION_CATEGORIES)) {
+    for (const t of def.types) map.set(t, cat);
+  }
+  return map;
+})();
+
+/**
+ * Returns the category key for the given relationship type, or null
+ * when the type is not categorized (e.g. an unrecognized custom type).
+ */
+export function categoryOf(type) {
+  return _CATEGORY_BY_TYPE.get(type) ?? null;
+}
+
+/**
+ * Returns the category definition ({ label, description, types }) for
+ * the given category key, or null when the key is unknown.
+ */
+export function categoryDefinition(categoryKey) {
+  return RELATION_CATEGORIES[categoryKey] ?? null;
+}
+
+/**
+ * MECE sanity check. Returns the list of relationship types that are
+ * NOT categorized (i.e. present in RELATIONSHIP_TYPES but missing from
+ * RELATION_CATEGORIES). Used by the test suite to verify SSOT drift.
+ */
+export function uncategorizedTypes() {
+  return RELATIONSHIP_TYPES.filter(t => !_CATEGORY_BY_TYPE.has(t));
+}
+
+/**
+ * MECE sanity check. Returns a list of { type, categories } entries
+ * for any type that appears in MORE than one category. Should be
+ * empty when the categorization is mutually exclusive.
+ */
+export function duplicatedTypes() {
+  const counts = new Map();
+  for (const def of Object.values(RELATION_CATEGORIES)) {
+    for (const t of def.types) {
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+  }
+  const out = [];
+  for (const [type, count] of counts) {
+    if (count > 1) out.push({ type, count });
+  }
+  return out;
+}

package/src/models/relation-colors.js

@@ -0,0 +1,78 @@
+// Default color palette for relation categories and individual types.
+//
+// The defaults mirror concept-browser/data/colors.json. Per-deployment
+// overrides pass through resolveRelationColor(type, { overrides, mode })
+// and take precedence over category defaults.
+
+import { categoryOf, categoryDefinition } from './relation-categories.js';
+
+// One { light, dark } pair per category. Keeping these in glossarist-js
+// lets the defaults ship with the library; consumers only need to
+// customize when they want to deviate.
+export const RELATION_COLOR_DEFAULTS = Object.freeze({
+  byCategory: Object.freeze({
+    lifecycle:      { light: '#B43A2E', dark: '#F87171' },
+    hierarchical:   { light: '#1F6FEB', dark: '#6EA8FE' },
+    associative:    { light: '#6B7280', dark: '#9CA3AF' },
+    comparative:    { light: '#A855F7', dark: '#C4B5FD' },
+    spatiotemporal: { light: '#0D9488', dark: '#5EEAD4' },
+    lexical:        { light: '#D97706', dark: '#FBBF24' },
+    mapping:        { light: '#2563EB', dark: '#93BBFD' },
+    conceptInstance:{ light: '#65A30D', dark: '#A3E635' },
+    versioning:     { light: '#9333EA', dark: '#C4B5FD' },
+  }),
+
+  // Per-type overrides. Use the same { light, dark } shape. Keys are
+  // relationship-type local names. Empty by default — consumers may
+  // populate this through `overrides.byType` at call time.
+  byType: Object.freeze({}),
+});
+
+/**
+ * Resolves the color for a relationship type.
+ *
+ * Resolution order:
+ *   1. overrides.byType[type]
+ *   2. RELATION_COLOR_DEFAULTS.byType[type]
+ *   3. overrides.byCategory[category]
+ *   4. RELATION_COLOR_DEFAULTS.byCategory[category]
+ *   5. null (uncategorized or unrecognized type)
+ *
+ * @param {string} type - relationship type local name
+ * @param {{ overrides?: { byType?: object, byCategory?: object }, mode?: 'light'|'dark' }} [options]
+ * @returns {string | null}
+ */
+export function resolveRelationColor(type, options = {}) {
+  const mode = options.mode ?? 'light';
+  const overrides = options.overrides ?? {};
+
+  const typeOverride = overrides.byType?.[type] ?? RELATION_COLOR_DEFAULTS.byType[type];
+  if (typeOverride) return pickMode(typeOverride, mode);
+
+  const category = categoryOf(type);
+  if (!category) return null;
+
+  const categoryOverride = overrides.byCategory?.[category] ?? RELATION_COLOR_DEFAULTS.byCategory[category];
+  if (!categoryOverride) return null;
+
+  return pickMode(categoryOverride, mode);
+}
+
+/**
+ * Returns the { light, dark } pair for a category, merging overrides
+ * over defaults. Useful for UIs that want to render a legend.
+ */
+export function categoryColorPair(categoryKey, overrides = {}) {
+  const def = categoryDefinition(categoryKey);
+  if (!def) return null;
+  const fromOverride = overrides.byCategory?.[categoryKey];
+  const fromDefault = RELATION_COLOR_DEFAULTS.byCategory[categoryKey];
+  if (!fromDefault && !fromOverride) return null;
+  return { ...(fromDefault ?? {}), ...(fromOverride ?? {}) };
+}
+
+function pickMode(pair, mode) {
+  if (pair == null) return null;
+  if (typeof pair === 'string') return pair;
+  return pair[mode] ?? pair.light ?? pair.dark ?? null;
+}

package/src/rdf/deterministic-id.js

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+
+// 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).
+export function deterministicId(...parts) {
+  const seed = parts.filter(p => p !== null && p !== undefined).join('|');
+  return createHash('md5').update(seed).digest('hex').slice(0, 12);
+}
+
+// Stable blank-node label for an RDF fragment identified by its parent
+// subject + role + index. Useful for reified resources like DetailedDefinition,
+// Designation, ConceptSource where the bnode ID must be deterministic to
+// produce byte-equivalent Turtle across runs.
+export function deterministicBnode(subject, role, index) {
+  return `_:b${deterministicId(subject, role, index)}`;
+}

package/src/rdf/document-writer.js

@@ -0,0 +1,87 @@
+// 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 './predicates.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 = [];
+  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.js

@@ -0,0 +1,43 @@
+// Concept → RDF quads. Mirrors glossarist-ruby's `Rdf::GlossConcept`.
+//
+// URI shape: `<uriBase>/<registerId>/concept/<conceptId>`.
+// Localized concepts: `<uriBase>/<registerId>/concept/<conceptId>/<lang>`.
+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 { namedNode, literal, quad } from './terms.js';
+
+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}`));
+  }
+
+  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;
+  }
+}

package/src/rdf/gloss-designation.js

@@ -0,0 +1,72 @@
+// 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]) {
+      yield quad(namedNode(desigSubject), namedNode(predicate), literal('true', booleanType));
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+// 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;
+  }
+}