@glossarist/concept-browser 0.7.114 → 0.7.115

package/scripts/lib/{build-cache.mjs → build-cache.ts}

@@ -11,8 +11,9 @@ import { dirname } from 'node:path';
  */
 
 export class BuildCache {
-  /** @param {string} cacheDir */
-  constructor(cacheDir) {
+  private cacheDir: string;
+
+  constructor(cacheDir: string) {
     this.cacheDir = cacheDir;
   }
 

package/scripts/lib/concept-formats.ts

@@ -0,0 +1,206 @@
+/**
+ * Concept format emitters — Turtle, SKOS JSON-LD, TBX.
+ *
+ * Extracted from generate-data.ts. Each function takes a JSON-LD concept
+ * object and serializes it to a different interchange format.
+ */
+
+import { ttlLit } from './turtle-escape';
+
+export function escapeTurtle(s: string): string {
+  return ttlLit(s).slice(1, -1);
+}
+
+export function escapeXml(s: any): string {
+  const str = Array.isArray(s) ? s.join(', ') : String(s ?? '');
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+export function conceptJsonToTurtle(concept: Record<string, any>): string {
+  const uri = concept['@id'] || '';
+  const id = concept['gl:identifier'] || '';
+  const lines = [
+    '@prefix skos: <http://www.w3.org/2004/02/skos/core#> .',
+    '@prefix dcterms: <http://purl.org/dc/terms/> .',
+    '',
+  ];
+
+  const props = ['  a skos:Concept'];
+  props.push(`  skos:notation "${escapeTurtle(id)}"`);
+
+  for (const [lang, lc] of Object.entries(concept['gl:localizedConcept'] || {}) as [string, any][]) {
+    if (lc['gl:designation']) {
+      for (const d of lc['gl:designation']) {
+        const term = d['gl:term'];
+        if (!term) continue;
+        const pred = d['gl:normativeStatus'] === 'preferred' ? 'skos:prefLabel' : 'skos:altLabel';
+        props.push(`  ${pred} "${escapeTurtle(term)}"@${lang}`);
+      }
+    }
+    if (lc['gl:definition']) {
+      for (const d of lc['gl:definition']) {
+        if (d['gl:content']) props.push(`  skos:definition "${escapeTurtle(d['gl:content'])}"@${lang}`);
+      }
+    }
+    if (lc['gl:notes']) {
+      for (const d of lc['gl:notes']) {
+        if (d['gl:content']) props.push(`  skos:scopeNote "${escapeTurtle(d['gl:content'])}"@${lang}`);
+      }
+    }
+  }
+
+  lines.push(`<${uri}>`);
+  lines.push(props.join(' ;\n'));
+  lines.push(' .');
+  return lines.join('\n');
+}
+
+export function conceptJsonToSkosJsonLd(concept: Record<string, any>): string {
+  const uri = concept['@id'] || '';
+  const id = concept['gl:identifier'] || '';
+
+  const doc: Record<string, any> = {
+    '@context': {
+      skos: 'http://www.w3.org/2004/02/skos/core#',
+      dcterms: 'http://purl.org/dc/terms/',
+      '@language': { '@container': '@language' },
+    },
+    '@id': uri,
+    '@type': 'skos:Concept',
+    'skos:notation': id,
+  };
+
+  const prefLabels: Record<string, string> = {};
+  const altLabels: Record<string, string> = {};
+  const definitions: Record<string, string> = {};
+  const scopeNotes: Record<string, string> = {};
+  for (const [lang, lc] of Object.entries(concept['gl:localizedConcept'] || {}) as [string, any][]) {
+    const descs = lc['gl:designation'] || [];
+    const pref = descs.find((d: any) => d['gl:normativeStatus'] === 'preferred' && d['gl:term']);
+    const alt = descs.find((d: any) => d['gl:normativeStatus'] !== 'preferred' && d['gl:term']);
+    if (pref) prefLabels[lang] = pref['gl:term'];
+    if (alt) altLabels[lang] = alt['gl:term'];
+    const def = (lc['gl:definition'] || [])[0];
+    if (def?.['gl:content']) definitions[lang] = def['gl:content'];
+    const note = (lc['gl:notes'] || [])[0];
+    if (note?.['gl:content']) scopeNotes[lang] = note['gl:content'];
+  }
+
+  if (Object.keys(prefLabels).length) doc['skos:prefLabel'] = prefLabels;
+  if (Object.keys(altLabels).length) doc['skos:altLabel'] = altLabels;
+  if (Object.keys(definitions).length) doc['skos:definition'] = definitions;
+  if (Object.keys(scopeNotes).length) doc['skos:scopeNote'] = scopeNotes;
+
+  return JSON.stringify(doc);
+}
+
+export function conceptJsonToTbx(concept: Record<string, any>): string {
+  const id = concept['gl:identifier'] || '';
+  const uri = concept['@id'] || '';
+  const localized = concept['gl:localizedConcept'] || {};
+
+  const langSections: { lang: string; termEntries: string[]; blocks: string }[] = [];
+  for (const [lang, lc] of Object.entries(localized) as [string, any][]) {
+    const descs = lc['gl:designation'] || [];
+    const definitions = (lc['gl:definition'] || []).filter((d: any) => d['gl:content']);
+    const notes = (lc['gl:notes'] || []).filter((d: any) => d['gl:content']);
+    const examples = (lc['gl:examples'] || []).filter((d: any) => d['gl:content']);
+    const sources = lc['gl:source'] || [];
+    const entryStatus = lc['gl:entryStatus'] || '';
+
+    if (!descs.length && !definitions.length) continue;
+
+    const termEntries: string[] = [];
+    for (const d of descs) {
+      const term = d['gl:term'];
+      if (!term) continue;
+      const status = d['gl:normativeStatus'] || '';
+      const type = d['@type'] || '';
+      let gramGrp = '';
+      if (d['gl:grammarInfo'] && d['gl:grammarInfo'].length > 0) {
+        const gi = d['gl:grammarInfo'][0];
+        if (gi['gl:gender']) gramGrp = `\n            <grammaticalGender>${escapeXml(gi['gl:gender'])}</grammaticalGender>`;
+        if (gi['gl:number']) gramGrp += `\n            <grammaticalNumber>${escapeXml(gi['gl:number'])}</grammaticalNumber>`;
+        for (const pos of ['noun', 'verb', 'adj', 'adverb', 'preposition', 'participle']) {
+          if (gi[`gl:${pos}`]) gramGrp += `\n            <partOfSpeech>${pos}</partOfSpeech>`;
+        }
+      }
+      let posBlock = '';
+      if (type.includes('Abbreviation')) posBlock = '\n            <partOfSpeech>abbreviation</partOfSpeech>';
+      if (type.includes('Symbol')) posBlock = '\n            <partOfSpeech>symbol</partOfSpeech>';
+
+      termEntries.push(`          <termEntry>
+            <langSet xml:lang="${lang}">
+              <tig>
+                <term>${escapeXml(term)}</term>${gramGrp}${posBlock}
+              </tig>
+            </langSet>
+          </termEntry>`);
+    }
+
+    let defBlock = '';
+    if (definitions.length) {
+      const defParts = definitions.map((d: any) => `            <p>${escapeXml(d['gl:content'])}</p>`).join('\n');
+      defBlock = `\n          <descrip type="definition">\n${defParts}\n          </descrip>`;
+    }
+
+    let noteBlock = '';
+    for (let i = 0; i < notes.length; i++) {
+      noteBlock += `\n          <note type="note">${escapeXml(notes[i]['gl:content'])}</note>`;
+    }
+    for (let i = 0; i < examples.length; i++) {
+      noteBlock += `\n          <note type="example">${escapeXml(examples[i]['gl:content'])}</note>`;
+    }
+
+    let sourceBlock = '';
+    for (const src of sources) {
+      const origin = src['gl:origin'] || {};
+      const parts: string[] = [];
+      const ref = origin['gl:ref'];
+      if (ref) {
+        const refParts: string[] = [];
+        if (ref['gl:source']) refParts.push(ref['gl:source']);
+        if (ref['gl:id']) refParts.push(ref['gl:id']);
+        parts.push(refParts.join(' ') || '');
+      }
+      if (origin['gl:locality']) {
+        const loc = origin['gl:locality'];
+        if (loc['gl:referenceFrom']) parts.push(loc['gl:localityType'] ? `${loc['gl:localityType']} ${loc['gl:referenceFrom']}` : loc['gl:referenceFrom']);
+      }
+      if (parts.filter(Boolean).length) {
+        sourceBlock += `\n          <ref>${escapeXml(parts.filter(Boolean).join(', '))}</ref>`;
+      }
+    }
+
+    let statusBlock = '';
+    if (entryStatus) {
+      statusBlock += `\n          <descrip type="entryStatus">${escapeXml(entryStatus)}</descrip>`;
+    }
+
+    const termEntriesBlock = termEntries.length ? '\n' + termEntries.join('\n') : '';
+    langSections.push({ lang, termEntries, blocks: [defBlock, noteBlock, sourceBlock, statusBlock].filter(b => b).join('') });
+  }
+
+  if (!langSections.length) return '';
+
+  const bodyEntries = langSections.map(ls => {
+    return `      <languageSection xml:lang="${ls.lang}">${ls.blocks}\n      </languageSection>`;
+  }).join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<tbx style="dca" type="TBX-Basic" xml:lang="en" xmlns="urn:iso:std:iso:30042:ed-2">
+  <tbxHeader>
+    <fileDesc>
+      <source>${escapeXml(uri)}</source>
+    </fileDesc>
+  </tbxHeader>
+  <text>
+    <body>
+      <conceptEntry id="${escapeXml(id)}">
+${bodyEntries}
+      </conceptEntry>
+    </body>
+  </text>
+</tbx>
+`;
+}

package/scripts/lib/concept-uri.ts

@@ -0,0 +1,14 @@
+/**
+ * Concept URI construction — single source of truth.
+ *
+ * Previously duplicated in:
+ *   scripts/generate-data.ts
+ *   scripts/bridge-to-astro.ts
+ *   scripts/build-edges.ts
+ *
+ * DRY: all three now import from here.
+ */
+
+export function buildConceptUri(uriBase: string, registerId: string, conceptId: string | number): string {
+  return `${uriBase}/${registerId}/concept/${conceptId}`;
+}

package/scripts/lib/{dataset-turtle.mjs → dataset-turtle.ts}

@@ -11,9 +11,10 @@ import {
   writeTurtle,
   PREFIXES,
 } from 'glossarist/rdf';
+import type { PrefixMap } from './yaml-types';
 
-function writerPrefixes() {
-  const out = {};
+function writerPrefixes(): PrefixMap {
+  const out: PrefixMap = {};
   // Only the prefixes this emitter actually uses — keeps the output
   // header focused.
   for (const k of ['dcat', 'skos', 'dcterms', 'prov', 'rdf', 'rdfs', 'xsd']) {
@@ -27,7 +28,7 @@ function writerPrefixes() {
   return out;
 }
 
-export async function buildDatasetTurtle(input) {
+export async function buildDatasetTurtle(input: any): Promise<string> {
   const quads = collectQuads(datasetToQuads(input));
   return writeTurtle(quads, { prefixes: writerPrefixes() });
 }

package/scripts/lib/harmonize-concept.ts

@@ -0,0 +1,86 @@
+/**
+ * YAML concept harmonization — normalizes multi-doc and simple formats
+ * into a single HarmonizedConcept shape.
+ *
+ * Extracted from generate-data.ts for testability and reuse.
+ */
+
+import fs from 'fs';
+import yaml from 'js-yaml';
+import type { HarmonizedConcept, YamlManagedConceptDoc } from './yaml-types';
+
+export const LEGACY_MULTIPLICITY_MAP: Record<string, { presence: string; count: string }> = {
+  compulsory:               { presence: 'required', count: 'exactly_one' },
+  optional:                 { presence: 'optional', count: 'exactly_one' },
+  compulsory_multiple:      { presence: 'required', count: 'multiple' },
+  optional_multiple:        { presence: 'optional', count: 'multiple' },
+  compulsory_at_least_one:  { presence: 'required', count: 'at_least_one' },
+};
+
+export const LEGACY_CERTAINTY_FROM_AXIS: Record<string, string> = {
+  required: 'confirmed',
+  optional: 'possible',
+};
+
+export function splitMultiplicity(multiplicity: string): { presence: string; count: string } {
+  return multiplicity in LEGACY_MULTIPLICITY_MAP
+    ? LEGACY_MULTIPLICITY_MAP[multiplicity]
+    : { presence: 'required', count: 'exactly_one' };
+}
+
+export function loadConceptFile(filePath: string): HarmonizedConcept {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const docs = yaml.loadAll(content, null, { schema: yaml.DEFAULT_SCHEMA }) as Record<string, any>[];
+
+  if (docs.length === 1 && docs[0].termid !== undefined) {
+    return docs[0] as HarmonizedConcept;
+  }
+
+  if (docs.length >= 1 && docs[0].data && docs[0].data.identifier !== undefined) {
+    const mc = docs[0] as YamlManagedConceptDoc;
+    const result: HarmonizedConcept = { termid: String(mc.data!.identifier) };
+
+    if (mc.related) result._related = mc.related as any;
+    if (mc.partitive_relations) result._partitiveRelations = mc.partitive_relations as any;
+    if (mc.generic_relations) result._genericRelations = mc.generic_relations as any;
+    if (mc.data!.domains) result._domains = mc.data!.domains;
+    if (mc.dates) result._dates = mc.dates as any;
+    if (mc.sources) result._sources = mc.sources as any;
+    if (mc.status) result._status = mc.status;
+    if (mc.schema_version) result._schemaVersion = mc.schema_version;
+    if (mc.date_accepted) result._dateAccepted = mc.date_accepted;
+
+    const MERGE_KEYS = [
+      'terms', 'definition', 'notes', 'annotations', 'examples', 'sources',
+      'dates', 'domain', 'references', 'entry_status', 'classification',
+      'review_type', 'review_date', 'review_decision_date', 'review_decision_event',
+      'review_status', 'review_decision', 'review_decision_notes',
+      'lineage_source_similarity', 'release', 'script', 'system',
+    ];
+
+    for (const doc of docs.slice(1)) {
+      if (!doc) continue;
+      const lang = doc.data?.language_code || doc.language_code;
+      if (!lang) continue;
+      const lcData = { ...(doc.data || {}) };
+      delete lcData.language_code;
+      for (const key of MERGE_KEYS) {
+        if (doc[key] !== undefined && lcData[key] === undefined) {
+          lcData[key] = doc[key];
+        }
+      }
+      (result as Record<string, any>)[lang] = lcData;
+    }
+    return result;
+  }
+
+  return docs[0] as HarmonizedConcept;
+}
+
+export function readYaml(filePath: string): any {
+  return yaml.load(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function stripHtml(s: string): string {
+  return s.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+}

package/scripts/lib/jsonld-emitter.ts

@@ -0,0 +1,169 @@
+/**
+ * JSON-LD wire-format emitters — convert YAML author objects to gl:* JSON-LD.
+ *
+ * Extracted from generate-data.ts. Each function maps one YAML entity
+ * (term, source, date, relation) to its JSON-LD wire representation.
+ *
+ * The 'gl:' prefix is the Glossarist JSON-LD namespace — see
+ * data/concept-model/ontologies/glossarist.context.jsonld.
+ */
+
+function resolveRefUri(term: string, refMaps: any): string | undefined {
+  if (!refMaps) return undefined;
+  const lc = term.toLowerCase();
+  if (refMaps.urnMap?.[lc]) return refMaps.urnMap[lc];
+  if (refMaps.designationMap?.[lc]) return refMaps.designationMap[lc];
+  if (refMaps.numericMap?.[term]) return refMaps.numericMap[term];
+  return undefined;
+}
+
+export function termToDesignation(term: Record<string, any>): Record<string, any> {
+  const typeMap: Record<string, string> = {
+    expression: 'gl:Expression',
+    abbreviation: 'gl:Abbreviation',
+    symbol: 'gl:Symbol',
+    letter_symbol: 'gl:LetterSymbol',
+    'graphical symbol': 'gl:GraphicalSymbol',
+  };
+  const doc: Record<string, any> = {
+    '@type': typeMap[term.type] || 'gl:Designation',
+    'gl:normativeStatus': term.normative_status || 'preferred',
+    'gl:term': term.designation,
+  };
+
+  if (term.grammar_info && term.grammar_info.length > 0) {
+    doc['gl:grammarInfo'] = term.grammar_info.map((gi: Record<string, any>) => {
+      const g: Record<string, any> = {};
+      if (gi.gender) g['gl:gender'] = gi.gender;
+      if (gi.number) g['gl:number'] = gi.number;
+      if (gi.partOfSpeech) g['gl:partOfSpeech'] = gi.partOfSpeech;
+      for (const pos of ['noun', 'verb', 'adj', 'adverb', 'preposition', 'participle']) {
+        if (gi[pos]) g[`gl:${pos}`] = gi[pos];
+      }
+      return g;
+    });
+  }
+
+  if (term.international !== undefined) doc['gl:international'] = term.international;
+  if (term.absent !== undefined) doc['gl:absent'] = term.absent;
+  if (term.geographical_area) doc['gl:geographicalArea'] = term.geographical_area;
+  if (term.term_type) doc['gl:termType'] = term.term_type;
+  if (term.prefix) doc['gl:prefix'] = term.prefix;
+  if (term.usage_info) doc['gl:usageInfo'] = term.usage_info;
+  if (term.field_of_application) doc['gl:fieldOfApplication'] = term.field_of_application;
+  if (term.acronym !== undefined) doc['gl:acronym'] = term.acronym;
+  if (term.initialism !== undefined) doc['gl:initialism'] = term.initialism;
+  if (term.truncation !== undefined) doc['gl:truncation'] = term.truncation;
+  if (term.text) doc['gl:text'] = term.text;
+  if (term.image) doc['gl:image'] = term.image;
+
+  if (term.related && term.related.length > 0) {
+    doc['gl:related'] = term.related.map((r: Record<string, any>) => {
+      const rel: Record<string, any> = {};
+      if (r.type) rel['gl:relationshipType'] = r.type;
+      if (r.target) {
+        rel['gl:target'] = r.target;
+      } else if (r.ref) {
+        const ref: Record<string, any> = { '@type': 'gl:ConceptRef' };
+        if (r.ref.source) ref['gl:source'] = r.ref.source;
+        if (r.ref.id) ref['gl:id'] = r.ref.id;
+        if (r.ref.text) ref['gl:text'] = r.ref.text;
+        rel['gl:ref'] = ref;
+      }
+      return rel;
+    });
+  }
+
+  return doc;
+}
+
+export function defsToJsonLd(defs: any[]): Record<string, any>[] {
+  if (!defs || !Array.isArray(defs)) return [];
+  return defs
+    .map(d => ({ '@type': 'gl:DetailedDefinition', 'gl:content': d.content || '' }))
+    .filter(d => d['gl:content']);
+}
+
+export function refToJsonLd(ref: any, typeName = 'gl:Ref'): Record<string, any> | undefined {
+  if (!ref) return undefined;
+  const refObj: Record<string, any> = { '@type': typeName };
+  if (typeof ref === 'string') {
+    refObj['gl:source'] = ref;
+  } else {
+    if (ref.source) refObj['gl:source'] = ref.source;
+    if (ref.id) refObj['gl:id'] = ref.id;
+    if (ref.version) refObj['gl:version'] = ref.version;
+    if (ref.text) refObj['gl:text'] = ref.text;
+  }
+  return refObj;
+}
+
+export function localityToJsonLd(loc: any): Record<string, any> | undefined {
+  if (!loc) return undefined;
+  const locObj: Record<string, any> = {};
+  if (loc.type) locObj['gl:localityType'] = loc.type;
+  if (loc.reference_from) locObj['gl:referenceFrom'] = loc.reference_from;
+  if (loc.referenceFrom) locObj['gl:referenceFrom'] = loc.referenceFrom;
+  if (loc.reference_to) locObj['gl:referenceTo'] = loc.reference_to;
+  if (loc.referenceTo) locObj['gl:referenceTo'] = loc.referenceTo;
+  return Object.keys(locObj).length > 0 ? locObj : undefined;
+}
+
+export function citationToJsonLd(citation: any): Record<string, any> {
+  const obj: Record<string, any> = {};
+  const ref = refToJsonLd(citation.ref);
+  if (ref) obj['gl:ref'] = ref;
+  const loc = localityToJsonLd(citation.locality);
+  if (loc) obj['gl:locality'] = loc;
+  if (citation.link) obj['gl:link'] = citation.link;
+  return obj;
+}
+
+export function sourcesToJsonLd(sources: any[]): Record<string, any>[] {
+  if (!sources || !Array.isArray(sources)) return [];
+  return sources.map(s => {
+    const doc: Record<string, any> = { '@type': 'gl:ConceptSource' };
+    if (s.id) doc['gl:id'] = s.id;
+    if (s.type) doc['gl:sourceType'] = s.type;
+    if (s.status) doc['gl:sourceStatus'] = s.status;
+    if (s.modification) doc['gl:modification'] = s.modification;
+    if (s.origin) {
+      const origin: Record<string, any> = { '@type': 'gl:Citation' };
+      const ref = refToJsonLd(s.origin.ref);
+      if (ref) origin['gl:ref'] = ref;
+      const loc = localityToJsonLd(s.origin.locality);
+      if (loc) origin['gl:locality'] = loc;
+      if (s.origin.link) origin['gl:link'] = s.origin.link;
+      doc['gl:origin'] = origin;
+    }
+    if (s.sourced_from && s.sourced_from.length) {
+      doc['gl:sourcedFrom'] = s.sourced_from.map((sf: any) => {
+        const cite: Record<string, any> = { '@type': 'gl:Citation' };
+        const ref = refToJsonLd(sf.ref);
+        if (ref) cite['gl:ref'] = ref;
+        const loc = localityToJsonLd(sf.locality);
+        if (loc) cite['gl:locality'] = loc;
+        if (sf.link) cite['gl:link'] = sf.link;
+        return cite;
+      });
+    }
+    return doc;
+  });
+}
+
+export function refsToJsonLd(refs: any[], refMaps: any): Record<string, any>[] {
+  if (!refs || !Array.isArray(refs)) return [];
+  return refs.map(r => {
+    if (r.id) {
+      const ref: Record<string, any> = { '@id': r.id, 'gl:term': r.term };
+      if (r.sourceId) ref['gl:sourceId'] = r.sourceId;
+      if (r.citation) ref['gl:citation'] = citationToJsonLd(r.citation);
+      return ref;
+    }
+    if (r.term && refMaps) {
+      const uri = resolveRefUri(r.term, refMaps);
+      if (uri) return { '@id': uri, 'gl:term': r.term };
+    }
+    return { '@id': r.id || r.term, 'gl:term': r.term };
+  }).filter(r => r['@id']);
+}

package/scripts/lib/{local-path-safety.mjs → local-path-safety.ts}

@@ -24,14 +24,18 @@ import path from 'path';
  * (`/var/folders/...`) is a symlink to `/private/var/folders/...`; without
  * this, prefix comparisons across the symlink boundary silently fail.
  */
-function physicalPath(p) {
+function physicalPath(p: string): string {
   if (fs.existsSync(p)) return fs.realpathSync(p);
   const parent = path.dirname(p);
   const parentReal = fs.existsSync(parent) ? fs.realpathSync(parent) : physicalPath(parent);
   return path.join(parentReal, path.basename(p));
 }
 
-export function assertLocalPathSafe(datasetId, localPath, { root = process.cwd(), datasetsDir } = {}) {
+export function assertLocalPathSafe(
+  datasetId: string,
+  localPath: string,
+  { root = process.cwd(), datasetsDir }: { root?: string; datasetsDir?: string } = {},
+): string {
   const datasetsRoot = datasetsDir || path.join(root, '.datasets');
   const localResolved = path.resolve(root, localPath);