glossarist 0.4.2 → 0.4.3

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "glossarist",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "sideEffects": false,
   "files": [
-    "src"
+    "src",
+    "data/concept-model/shapes/glossarist.shacl.ttl",
+    "data/concept-model/README.md"
   ],
   "exports": {
     ".": {
@@ -34,10 +36,23 @@
       "types": "./src/validators/index.d.ts",
       "import": "./src/validators/index.js",
       "default": "./src/validators/index.js"
+    },
+    "./rdf": {
+      "types": "./src/rdf/index.d.ts",
+      "import": "./src/rdf/index.js",
+      "default": "./src/rdf/index.js"
+    },
+    "./transforms": {
+      "types": "./src/transforms/index.d.ts",
+      "import": "./src/transforms/index.js",
+      "default": "./src/transforms/index.js"
     }
   },
   "scripts": {
     "lint": "eslint src/ test/",
+    "sync:model": "node scripts/sync-concept-model.mjs",
+    "gen:predicates": "node scripts/gen-predicates.mjs",
+    "prebuild": "npm run gen:predicates",
     "pretest": "node test/fixtures/build-fixtures.js",
     "test": "find test -name '*.test.js' | sort | xargs node --test",
     "test:verbose": "find test -name '*.test.js' | sort | xargs node --test --test-reporter spec",
@@ -68,8 +83,13 @@
     "access": "public"
   },
   "dependencies": {
+    "@rdfjs/data-model": "^2.0.0",
+    "@rdfjs/dataset": "^2.0.0",
     "js-yaml": "^5.0.0",
-    "jszip": "^3.10.1"
+    "jsonld": "^8.3.3",
+    "jszip": "^3.10.1",
+    "n3": "^1.17.0",
+    "rdf-validate-shacl": "^0.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/concept-collection.js

@@ -65,6 +65,43 @@ export class ConceptCollection {
     }));
   }
 
+  /**
+   * Cascading section membership filter. Returns concepts whose
+   * section closure includes `sectionId`.
+   *
+   * A concept in section "3.1.1" matches `bySection('3.1')` and
+   * `bySection('3')` because the section closure walks ancestors
+   * transitively (mirrors owl:TransitiveProperty on
+   * gloss:hasParentSection in the concept-model ontology).
+   *
+   * Two calling conventions:
+   *
+   *   bySection('3.1', { register })          // register expands each concept's section closure
+   *   bySection(['3.1', '3'])                  // pre-expanded target set (any of these must match)
+   *
+   * Concept-side membership is read from `concept.sections` if set,
+   * otherwise from `concept.groups` (a flat list of section IDs).
+   */
+  bySection(sectionId, options = {}) {
+    if (Array.isArray(sectionId)) {
+      const targetSet = new Set(sectionId);
+      return new ConceptCollection(this[_items].filter(c => {
+        const ids = options.register
+          ? options.register.conceptSectionIds(c)
+          : _flatConceptSectionIds(c);
+        return ids.some(id => targetSet.has(id));
+      }));
+    }
+    if (!options.register) {
+      throw new Error('bySection(sectionId) requires { register } to expand the concept section closures');
+    }
+    const target = sectionId;
+    return new ConceptCollection(this[_items].filter(c => {
+      const ids = options.register.conceptSectionIds(c);
+      return ids.includes(target);
+    }));
+  }
+
   index() {
     const map = new Map();
     for (const c of this[_items]) map.set(c.id, c);
@@ -106,3 +143,23 @@ export class ConceptCollection {
   slice(...args) { return new ConceptCollection(this[_items].slice(...args)); }
   concat(...args) { return new ConceptCollection(this[_items].concat(...args)); }
 }
+
+// Standalone helper for the array-closure case where no register is
+// available. Mirrors the lookup done inside Register#conceptSectionIds
+// but without ancestor expansion (the closure is already provided).
+function _flatConceptSectionIds(concept) {
+  if (!concept) return [];
+  const out = [];
+  for (const source of [concept.sections, concept.groups]) {
+    if (!Array.isArray(source)) continue;
+    for (const entry of source) {
+      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/index.js

@@ -56,3 +56,18 @@ export {
   isKnownEntityType,
   parseEntityPath,
 } from './entity-directory.js';
+
+// RDF serialization layer (WS C). Mirrors lib/glossarist/rdf/.
+export {
+  PRED, PREFIXES, SKOSXL, WELL_KNOWN,
+  deterministicId, deterministicBnode,
+  conceptUri, conceptToQuads,
+  localizedConceptUri, localizedConceptToQuads,
+  designationToQuads, skosLabelPredicate, skosxlLabelPredicate,
+  detailedDefinitionToQuads,
+  conceptSourceToQuads,
+  collectQuads, writeTurtle, writeNTriples, writeJsonld, sortQuads,
+  validateShacl, loadShapes, quadsToDataset,
+} from './rdf/index.js';
+
+export { ConceptToGlossTransform } from './transforms/concept-to-gloss.transform.js';

package/src/models/concept.js

@@ -19,6 +19,12 @@ export class Concept extends GlossaristModel {
 
     this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related ?? data.related_concepts ?? [], RelatedConcept);
     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)
+      : [];
+    this.sections = Array.isArray(data.sections)
+      ? data.sections.map(s => typeof s === 'string' ? s : (s?.id ?? s?.sectionId ?? null)).filter(Boolean)
+      : [];
     this.tags = Array.isArray(data.tags) ? [...data.tags] : [];
     this.dates = _mapInstances(data.dates ?? [], ConceptDate);
     this.sources = _mapInstances(data.sources ?? [], ConceptSource);

package/src/models/dataset-color.js

@@ -0,0 +1,79 @@
+// Per-dataset color spec, light/dark variants.
+//
+// A DatasetColor may be:
+//   - a single hex string (legacy, applied to both modes)
+//   - an explicit { light, dark } pair
+//
+// Round-trips through Register.toJSON unchanged so the data lives in
+// the GCR package. Consumers call resolvedColor(mode) to pick the
+// right hex for the current UI mode.
+
+/**
+ * @typedef {string} DatasetColorSpec
+ * @typedef {{ light: string, dark: string }} DatasetColorPair
+ * @typedef {DatasetColorSpec | DatasetColorPair} DatasetColor
+ */
+
+export const COLOR_MODES = Object.freeze(['light', 'dark']);
+
+/**
+ * Returns the right hex for the given mode. Falls back to the single
+ * hex when the spec is a string. Returns null when the spec is null
+ * or when the requested mode is missing from a pair.
+ *
+ * @param {DatasetColor | null | undefined} color
+ * @param {'light' | 'dark'} mode
+ * @returns {string | null}
+ */
+export function resolveColor(color, mode) {
+  if (color == null) return null;
+  if (typeof color === 'string') return color;
+  if (typeof color === 'object') {
+    if (!mode) return color.light ?? color.dark ?? null;
+    return color[mode] ?? null;
+  }
+  return null;
+}
+
+/**
+ * True when the spec declares an explicit {light, dark} object.
+ * Lets callers distinguish "single hex" from "per-mode pair" without
+ * repeating the typeof check.
+ */
+export function isColorPair(color) {
+  return color != null && typeof color === 'object';
+}
+
+/**
+ * Validates a color spec. A valid spec is either:
+ *   - a string matching /^#[0-9a-fA-F]{3,8}$/
+ *   - an object with `light` and `dark` string fields, each matching
+ *     the same pattern
+ *
+ * Returns null when valid, or an error message describing the issue.
+ */
+export function validateColor(color) {
+  if (color == null) return null;
+  if (typeof color === 'string') return hexError(color);
+  if (typeof color === 'object') {
+    if (color.light == null && color.dark == null) {
+      return 'color pair must have at least one of `light` or `dark`';
+    }
+    if (color.light != null) {
+      const e = hexError(color.light);
+      if (e) return `color.light: ${e}`;
+    }
+    if (color.dark != null) {
+      const e = hexError(color.dark);
+      if (e) return `color.dark: ${e}`;
+    }
+    return null;
+  }
+  return `unexpected color type ${typeof color}`;
+}
+
+const HEX_RE = /^#[0-9a-fA-F]{3,8}$/;
+function hexError(s) {
+  if (typeof s !== 'string') return `expected string, got ${typeof s}`;
+  return HEX_RE.test(s) ? null : `not a valid hex color: ${JSON.stringify(s)}`;
+}

package/src/models/designation.js

@@ -5,6 +5,16 @@ import { GrammarInfo } from './grammar-info.js';
 import { RelatedConcept } from './related-concept.js';
 import { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './designation-relationship.js';
 
+// Maps a normative-status local-name to the matching SKOS/SKOS-XL label
+// predicate local-name. Lives on the model so a new status requires a
+// single edit here, not edits in every emitter.
+const SKOS_LABEL_BY_NORMATIVE_STATUS = Object.freeze({
+  preferred: 'prefLabel',
+  deprecated: 'hiddenLabel',
+  admitted: 'altLabel',
+  deprecated_: 'altLabel',
+});
+
 export class Designation extends RegistrableModel {
   constructor(data = {}) {
     super();
@@ -53,6 +63,34 @@ export class Designation extends RegistrableModel {
     return obj;
   }
 
+  // RDF class local-name for this designation subtype. Override in
+  // subclasses that map to a different ontology class.
+  rdfClass() {
+    return 'Expression';
+  }
+
+  // SKOS label predicate URI (skos:prefLabel / skos:altLabel / skos:hiddenLabel)
+  // appropriate for this designation's normative status. Falls back to
+  // skos:altLabel for unknown statuses.
+  skosLabelPredicate(skosNs) {
+    const label = this._skosLabelLocalName();
+    return `${skosNs}${label}`;
+  }
+
+  // SKOS-XL label predicate URI (skosxl:prefLabel / etc.).
+  skosxlLabelPredicate(skosxlNs) {
+    const label = this._skosLabelLocalName();
+    return `${skosxlNs}${label}`;
+  }
+
+  _skosLabelLocalName() {
+    const status = String(this.normativeStatus ?? '')
+      .split(/[/#]/)
+      .pop()
+      .trim();
+    return SKOS_LABEL_BY_NORMATIVE_STATUS[status] ?? 'altLabel';
+  }
+
   static fromJSON(data) {
     return Designation.fromData(data);
   }
@@ -87,6 +125,10 @@ export class Abbreviation extends Expression {
     this.truncation = data.truncation ?? false;
   }
 
+  rdfClass() {
+    return 'Abbreviation';
+  }
+
   toJSON() {
     const obj = super.toJSON();
     if (this.acronym) obj.acronym = true;
@@ -101,6 +143,10 @@ export class Abbreviation extends Expression {
 Designation.register('abbreviation', Abbreviation);
 
 export class Symbol extends Designation {
+  rdfClass() {
+    return 'Symbol';
+  }
+
   static fromJSON(data) { return new Symbol(data); }
 }
 
@@ -112,6 +158,10 @@ export class LetterSymbol extends Symbol {
     this.text = data.text ?? null;
   }
 
+  rdfClass() {
+    return 'LetterSymbol';
+  }
+
   toJSON() {
     const obj = super.toJSON();
     if (this.text != null) obj.text = this.text;
@@ -130,6 +180,10 @@ export class GraphicalSymbol extends Symbol {
     this.image = data.image ?? null;
   }
 
+  rdfClass() {
+    return 'GraphicalSymbol';
+  }
+
   toJSON() {
     const obj = super.toJSON();
     if (this.text != null) obj.text = this.text;

package/src/models/index.d.ts

@@ -42,6 +42,8 @@ export class GlossaristModel {
   static fromJSON(data: Record<string, unknown>): GlossaristModel;
   equals(other: GlossaristModel): boolean;
   clone(): GlossaristModel;
+  protected _lazy<T>(cacheKey: string, rawKey: string, wrapFn: (item: any) => T): T[];
+  protected _serialize(obj: Record<string, unknown>, jsonKey: string, cacheKey: string, rawKey: string): void;
 }
 
 export class Concept extends GlossaristModel {
@@ -117,6 +119,9 @@ export class Designation extends GlossaristModel {
   readonly pronunciations: Pronunciation[];
   readonly sources: ConceptSource[];
   readonly related: (RelatedConcept | DesignationRelationship)[];
+  rdfClass(): string;
+  skosLabelPredicate(skosNs: string): string;
+  skosxlLabelPredicate(skosxlNs: string): string;
   static register(type: string, cls: typeof Designation): void;
   static fromData(data: Record<string, unknown>): Designation;
   static fromJSON(data: Record<string, unknown>): Designation;
@@ -250,13 +255,125 @@ export class DetailedDefinition extends GlossaristModel {
   static fromJSON(data: Record<string, unknown>): DetailedDefinition;
 }
 
-export class NonVerbRep extends GlossaristModel {
-  readonly type: string | null;
-  readonly ref: string | null;
-  readonly text: string | null;
+export class RegistrableModel extends GlossaristModel {
+  static register(type: string, cls: typeof RegistrableModel): void;
+  static fromData(data: Record<string, unknown>): RegistrableModel;
+}
+
+export class FigureImage extends GlossaristModel {
+  constructor(data?: Record<string, unknown>);
+  readonly src: string | null;
+  readonly format: string | null;
+  readonly role: string | null;
+  readonly width: number | null;
+  readonly height: number | null;
+  readonly scale: number | null;
+  static fromJSON(data: Record<string, unknown>): FigureImage;
+}
+
+export class NonVerbalEntity extends RegistrableModel {
+  constructor(data?: Record<string, unknown>);
+  readonly caption: Record<string, string> | null;
+  readonly description: Record<string, string> | null;
+  readonly alt: Record<string, string> | null;
   readonly sources: ConceptSource[];
+  findById(targetId: string): NonVerbalEntity | null;
+  allIds(): string[];
+  static fromJSON(data: Record<string, unknown>): NonVerbalEntity;
+}
+
+export class SharedNonVerbalEntity extends NonVerbalEntity {
+  constructor(data?: Record<string, unknown>);
+  readonly id: string | null;
+  readonly identifier: string | null;
+  findById(targetId: string): SharedNonVerbalEntity | null;
+  allIds(): string[];
+  static fromJSON(data: Record<string, unknown>): SharedNonVerbalEntity;
+}
+
+export class Figure extends SharedNonVerbalEntity {
+  constructor(data?: Record<string, unknown>);
+  readonly images: FigureImage[];
+  readonly subfigures: Figure[];
+  findById(targetId: string): Figure | null;
+  allIds(): string[];
+  static fromJSON(data: Record<string, unknown>): Figure;
+}
+
+export class Table extends SharedNonVerbalEntity {
+  constructor(data?: Record<string, unknown>);
+  readonly content: Record<string, unknown> | null;
+  readonly format: string | null;
+  static fromJSON(data: Record<string, unknown>): Table;
+}
+
+export class Formula extends SharedNonVerbalEntity {
+  constructor(data?: Record<string, unknown>);
+  readonly expression: Record<string, string> | null;
+  readonly notation: string | null;
+  static fromJSON(data: Record<string, unknown>): Formula;
+}
+
+export const NON_VERBAL_TYPES: readonly string[];
+
+export class NonVerbRep extends NonVerbalEntity {
+  readonly type: string | null;
+  readonly images: FigureImage[];
+  static fromJSON(data: Record<string, unknown>): NonVerbRep;
 }
 
+export class NonVerbalReference extends RegistrableModel {
+  constructor(data?: Record<string, unknown>);
+  readonly entityId: string | null;
+  readonly display: string | null;
+  readonly dedupKey: readonly [string, string | null];
+  static fromJSON(data: Record<string, unknown> | string): NonVerbalReference;
+  static register(type: string, cls: typeof NonVerbalReference): void;
+}
+
+export class FigureReference extends NonVerbalReference {
+  static fromJSON(data: Record<string, unknown> | string): FigureReference;
+}
+
+export class TableReference extends NonVerbalReference {
+  static fromJSON(data: Record<string, unknown> | string): TableReference;
+}
+
+export class FormulaReference extends NonVerbalReference {
+  static fromJSON(data: Record<string, unknown> | string): FormulaReference;
+}
+
+export class BibliographyEntry extends GlossaristModel {
+  constructor(data?: Record<string, unknown>);
+  readonly id: string | null;
+  readonly reference: string | null;
+  readonly title: string | null;
+  readonly link: string | null;
+  readonly type: string | null;
+  static fromJSON(data: Record<string, unknown>): BibliographyEntry;
+}
+
+export class BibliographyData extends GlossaristModel {
+  constructor(data?: Record<string, unknown>);
+  readonly entries: BibliographyEntry[];
+  find(id: string): BibliographyEntry | null;
+  readonly keys: string[];
+  toYAML(): string;
+  toJSON(): { bibliography: BibliographyEntry[] };
+  static fromYAML(yamlString: string): BibliographyData;
+  static fromJSON(data: Record<string, unknown>): BibliographyData;
+}
+
+export function fetchLocalizedString(
+  hash: Record<string, string> | null,
+  lang: string,
+  fallback?: string | null,
+): string | null;
+
+export function localizedStringIsEmpty(hash: Record<string, string> | null): boolean;
+
+export function localizedStringIsPresent(hash: Record<string, string> | null): boolean;
+
 export class GcrStatistics extends GlossaristModel {
   readonly totalConcepts: number;
   readonly conceptsWithDefinitions: number;

package/src/models/index.js

@@ -1,5 +1,18 @@
 export { Register, REGISTER_STATUSES } from './register.js';
 export { Section, ORDERING_METHODS } from './section.js';
+export { resolveColor, isColorPair, validateColor, COLOR_MODES } from './dataset-color.js';
+export {
+  RELATION_CATEGORIES,
+  categoryOf,
+  categoryDefinition,
+  uncategorizedTypes,
+  duplicatedTypes,
+} from './relation-categories.js';
+export {
+  RELATION_COLOR_DEFAULTS,
+  resolveRelationColor,
+  categoryColorPair,
+} from './relation-colors.js';
 export { GlossaristModel } from './base.js';
 export { Concept } from './concept.js';
 export { LocalizedConcept } from './localized-concept.js';

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