@glossarist/concept-browser 0.7.50 → 0.7.52

package/scripts/lib/vocab-turtle.mjs

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VOCAB_PATH = join(__dirname, '..', '..', 'data', 'glossarist-vocab.json');
+
+function loadVocab(path = VOCAB_PATH) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function ttlLit(s) {
+  if (s == null) return '""';
+  const escaped = String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+  return `"${escaped}"`;
+}
+
+function ttlPrefixed(qname) {
+  const colonIdx = qname.indexOf(':');
+  if (colonIdx < 0) return qname;
+  const local = qname.slice(colonIdx + 1);
+  const escaped = local.replace(/([/])/g, '\\$1');
+  return `${qname.slice(0, colonIdx + 1)}${escaped}`;
+}
+
+export function buildVocabularyTurtle() {
+  const vocab = loadVocab();
+  const lines = [
+    '@prefix skos: <http://www.w3.org/2004/02/skos/core#> .',
+    '@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .',
+    '@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .',
+    '@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .',
+    '@prefix dcterms: <http://purl.org/dc/terms/> .',
+    '@prefix gloss: <https://www.glossarist.org/ontologies/> .',
+    '',
+  ];
+
+  for (const scheme of vocab.schemes) {
+    const schemeLines = [
+      `${ttlPrefixed(scheme.schemeIri)} a skos:ConceptScheme ;`,
+      `  rdfs:label ${ttlLit(scheme.label)} ;`,
+    ];
+    for (const term of scheme.terms) {
+      schemeLines.push(`  skos:hasTopConcept ${ttlPrefixed(term.iri)} ;`);
+    }
+    schemeLines[schemeLines.length - 1] = schemeLines[schemeLines.length - 1].replace(/ ;$/, ' .');
+    lines.push(...schemeLines);
+
+    for (const term of scheme.terms) {
+      lines.push(`${ttlPrefixed(term.iri)} a skos:Concept ;`);
+      lines.push(`  rdfs:label ${ttlLit(term.label)} ;`);
+      lines.push(`  skos:inScheme ${ttlPrefixed(scheme.schemeIri)} .`);
+      lines.push('');
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+export function listVocabSchemes() {
+  return loadVocab().schemes;
+}

package/scripts/normalize-yaml.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, extname, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const YAML_EXTS = new Set(['.yaml', '.yml']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist']);
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      out.push(...walk(full));
+    } else if (YAML_EXTS.has(extname(entry))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function normalizeYaml({ root = ROOT, check = false, paths = [] } = {}) {
+  const searchDirs = paths.length > 0 ? paths.map(p => join(root, p)) : [join(root, '.datasets')];
+
+  const files = [];
+  for (const dir of searchDirs) {
+    try {
+      statSync(dir);
+    } catch {
+      continue;
+    }
+    files.push(...walk(dir));
+  }
+  files.sort();
+
+  let checked = 0;
+  let nonNfc = 0;
+  const fixed = [];
+
+  for (const file of files) {
+    const original = readFileSync(file, 'utf8');
+    checked++;
+    if (!isNfc(original)) {
+      nonNfc++;
+      if (!check) {
+        writeFileSync(file, original.normalize('NFC'), 'utf8');
+        fixed.push(relative(root, file));
+      } else {
+        fixed.push(relative(root, file));
+      }
+    }
+  }
+
+  return { checked, nonNfc, fixed, check };
+}
+
+function isNfc(s) {
+  return s === s.normalize('NFC');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const check = args.includes('--check');
+  const paths = args.filter(a => !a.startsWith('-') && a !== 'normalize');
+
+  const { checked, nonNfc, fixed } = normalizeYaml({ check, paths });
+
+  if (check) {
+    if (nonNfc === 0) {
+      process.stdout.write(`NFC OK: ${checked} file(s) checked, all normalized\n`);
+      return;
+    }
+    process.stderr.write(`NFC check failed: ${nonNfc} of ${checked} file(s) are not NFC-normalized\n\n`);
+    for (const f of fixed) {
+      process.stderr.write(`  ${f}\n`);
+    }
+    process.exit(1);
+  } else {
+    if (nonNfc === 0) {
+      process.stdout.write(`NFC OK: ${checked} file(s) checked, all already normalized\n`);
+      return;
+    }
+    process.stdout.write(`Normalized ${nonNfc} of ${checked} file(s)\n`);
+    for (const f of fixed) {
+      process.stdout.write(`  ${f}\n`);
+    }
+  }
+}
+
+const isDirectEntry = process.argv[1] &&
+  fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isDirectEntry) {
+  main();
+}

package/scripts/sync-concept-model.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Sync vendored concept-model data artifacts from the upstream git repo.
+//
+// concept-model is a data-only repo. It is not an npm package. We vendor
+// the small set of artifacts we actually need (glossarist.context.jsonld,
+// glossarist.ttl, shapes/glossarist.shacl.ttl) so this repo's build scripts
+// can run without any runtime dependency on concept-model.
+//
+// Usage:
+//   npm run sync:model                # latest release tag
+//   npm run sync:model -- v3.0.0      # specific tag
+//   node scripts/sync-concept-model.mjs --ref main   # any git ref
+//
+// Output: data/concept-model/* updated in place. Review the diff and commit.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const OUT_DIR = resolve(ROOT, 'data', 'concept-model');
+const REPO = 'glossarist/concept-model';
+
+function parseArgs(argv) {
+  const out = { ref: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--ref') out.ref = argv[++i];
+    else if (!a.startsWith('--')) out.ref = a;
+  }
+  return out;
+}
+
+function latestTag() {
+  return execSync(`gh api repos/${REPO}/releases/latest --jq .tag_name`, { encoding: 'utf8' }).trim();
+}
+
+function fetchFile(ref, path) {
+  const url = `https://raw.githubusercontent.com/${REPO}/${ref}/${path}`;
+  return execSync(`curl -fsSL ${url}`, { encoding: 'utf8' });
+}
+
+const args = parseArgs(process.argv);
+const ref = args.ref || latestTag();
+if (!ref) {
+  console.error('Could not determine concept-model ref to sync.');
+  process.exit(1);
+}
+
+console.log(`Syncing from ${REPO}@${ref}`);
+
+mkdirSync(resolve(OUT_DIR, 'shapes'), { recursive: true });
+
+function fetchAny(ref, candidates) {
+  for (const p of candidates) {
+    try {
+      return fetchFile(ref, p);
+    } catch (e) {
+      // try next
+    }
+  }
+  throw new Error(`Could not fetch any of: ${candidates.join(', ')}`);
+}
+
+const targets = {
+  'glossarist.context.jsonld': ['ontologies/glossarist.context.jsonld', 'glossarist.context.jsonld'],
+  'glossarist.ttl': ['ontologies/glossarist.ttl', 'glossarist.ttl'],
+  'shapes/glossarist.shacl.ttl': ['ontologies/shapes/glossarist.shacl.ttl', 'shapes/glossarist.shacl.ttl'],
+};
+
+let updated = 0;
+for (const [outPath, candidates] of Object.entries(targets)) {
+  const content = fetchAny(ref, candidates);
+  writeFileSync(resolve(OUT_DIR, outPath), content);
+  console.log(`  ✓ ${outPath} (${content.length} bytes)`);
+  updated++;
+}
+
+writeFileSync(
+  resolve(OUT_DIR, 'SOURCE.json'),
+  JSON.stringify({ repo: REPO, ref, syncedAt: new Date().toISOString() }, null, 2) + '\n',
+);
+
+console.log(`\nSynced ${updated} file(s) from ${REPO}@${ref}.`);
+console.log('Review the diff, then commit.');

package/scripts/validate-shacl.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// SHACL validation gate for concept-browser's data pipeline.
+//
+// Walks `public/data/` (or any directory passed as argv[2]), parses every
+// `.ttl` file, and validates it against the vendored SHACL shapes. Fails
+// the build on any violation.
+//
+// Usage:
+//   node scripts/validate-shacl.mjs                  # validates public/data
+//   node scripts/validate-shacl.mjs path/to/dir      # validates a custom dir
+//   SHAPES_PATH=/path/to/shapes.ttl node scripts/validate-shacl.mjs
+//                                                     # uses a custom shapes file
+//
+// The shapes path defaults to the vendored file at
+// `data/concept-model/shapes/glossarist.shacl.ttl` (synced from
+// glossarist/concept-model via `npm run sync:model`). Pass --shapes <path>
+// or set SHAPES_PATH to override.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Parser as N3Parser, DataFactory } from 'n3';
+import rdfDataset from '@rdfjs/dataset';
+import ShaclValidator from 'rdf-validate-shacl';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VENDORED_SHAPES = resolve(__dirname, '..', 'data', 'concept-model', 'shapes', 'glossarist.shacl.ttl');
+
+const COMBINED_FACTORY = {
+  namedNode: DataFactory.namedNode,
+  blankNode: DataFactory.blankNode,
+  literal: DataFactory.literal,
+  defaultGraph: DataFactory.defaultGraph,
+  quad: DataFactory.quad,
+  fromTerm: DataFactory.fromTerm,
+  fromQuad: DataFactory.fromQuad,
+  dataset: rdfDataset.dataset.bind(rdfDataset),
+};
+const createDataset = COMBINED_FACTORY.dataset;
+const ShaclValidatorCtor = ShaclValidator.default ?? ShaclValidator;
+
+function parseArgs(argv) {
+  const out = { dataRoot: 'public/data', shapesPath: null };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--shapes') {
+      out.shapesPath = argv[++i];
+      if (!out.shapesPath) throw new Error('--shapes requires a path argument');
+    } else if (arg === '--help' || arg === '-h') {
+      console.log(USAGE);
+      process.exit(0);
+    } else {
+      out.dataRoot = arg;
+    }
+  }
+  if (process.env.SHAPES_PATH && !out.shapesPath) {
+    out.shapesPath = process.env.SHAPES_PATH;
+  }
+  return out;
+}
+
+const USAGE = `Usage: validate-shacl.mjs [options] [data-root]
+
+Options:
+  --shapes <path>   Path to a SHACL shapes .ttl file (overrides the default
+                    vendored shapes under data/concept-model/shapes/).
+  --help, -h        Show this help.
+
+Environment:
+  SHAPES_PATH       Same as --shapes. Lower priority than the CLI flag.
+
+Default data-root is public/data.
+`;
+
+function resolveShapesPath(cliPath) {
+  if (cliPath) return cliPath;
+  if (!statSync(VENDORED_SHAPES, { throwIfNoEntry: false })) {
+    throw new Error(
+      `Vendored SHACL shapes not found at ${VENDORED_SHAPES}.\n` +
+      `Run \`npm run sync:model\` to fetch them from glossarist/concept-model, ` +
+      `or pass --shapes <path>, or set SHAPES_PATH=<path>.`,
+    );
+  }
+  return VENDORED_SHAPES;
+}
+
+function parseTurtle(text, baseIri) {
+  const parser = new N3Parser({ baseIRI: baseIri });
+  const out = createDataset();
+  return new Promise((resolve, reject) => {
+    parser.parse(text, (err, quad) => {
+      if (err) reject(err);
+      else if (quad) out.add(quad);
+      else resolve(out);
+    });
+  });
+}
+
+function* walkTtl(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) yield* walkTtl(full);
+    else if (extname(full) === '.ttl') yield full;
+  }
+}
+
+function formatViolation(v) {
+  const focus = v.focusNode?.value ?? '(unknown)';
+  const shape = v.shape?.value ?? '(unknown)';
+  const path = v.path?.value ?? '';
+  const message = (v.message && v.message.length > 0)
+    ? v.message.map(m => m.value).join('; ')
+    : '(no message)';
+  const pathPart = path ? `\n    path:    ${path}` : '';
+  return `    shape:   ${shape}${pathPart}\n    node:    ${focus}\n    message: ${message}`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const shapesPath = resolveShapesPath(args.shapesPath);
+
+  let shapesDataset;
+  try {
+    const shapesText = readFileSync(shapesPath, 'utf8');
+    shapesDataset = await parseTurtle(shapesText, `file://${shapesPath}`);
+  } catch (e) {
+    console.error(`Failed to load SHACL shapes from ${shapesPath}: ${e.message}`);
+    process.exit(2);
+  }
+
+  const validator = new ShaclValidatorCtor(shapesDataset, { factory: COMBINED_FACTORY });
+
+  let statDir;
+  try {
+    statDir = statSync(args.dataRoot);
+  } catch (e) {
+    console.error(`Data root not found: ${args.dataRoot}`);
+    process.exit(2);
+  }
+  if (!statDir.isDirectory()) {
+    console.error(`Data root is not a directory: ${args.dataRoot}`);
+    process.exit(2);
+  }
+
+  const files = [...walkTtl(args.dataRoot)];
+  if (files.length === 0) {
+    console.log(`No .ttl files under ${args.dataRoot} — SHACL gate skipped.`);
+    return;
+  }
+
+  const violations = [];
+  for (const path of files) {
+    let graph;
+    try {
+      const text = readFileSync(path, 'utf8');
+      graph = await parseTurtle(text, `file://${path}`);
+    } catch (e) {
+      violations.push({ path, parseError: e.message });
+      continue;
+    }
+    const report = validator.validate(graph);
+    if (!report.conforms) {
+      for (const v of report.results) {
+        violations.push({ path, result: v });
+      }
+    }
+  }
+
+  if (violations.length === 0) {
+    console.log(`SHACL validation passed — ${files.length} file(s) conform.`);
+    return;
+  }
+
+  console.error(`SHACL validation FAILED — ${violations.length} violation(s) in ${files.length} file(s):\n`);
+  let currentPath = null;
+  for (const v of violations) {
+    if (v.path !== currentPath) {
+      currentPath = v.path;
+      console.error(`\n  ${v.path}`);
+    }
+    if (v.parseError) {
+      console.error(`    PARSE ERROR: ${v.parseError}`);
+    } else {
+      console.error(formatViolation(v.result));
+    }
+  }
+  console.error('');
+  process.exit(1);
+}
+
+main().catch((e) => {
+  console.error(`validate-shacl: unexpected error: ${e.stack ?? e}`);
+  process.exit(2);
+});

package/src/__fixtures__/concept-shape.ttl

@@ -0,0 +1,20 @@
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@prefix ex: <http://example.org/> .
+
+ex:ConceptShape
+    a sh:NodeShape ;
+    sh:targetClass skos:Concept ;
+    sh:property [
+        sh:path skos:prefLabel ;
+        sh:datatype rdf:langString ;
+        sh:minCount 1 ;
+        sh:message "skos:prefLabel must be an rdf:langString (language-tagged literal)." ;
+    ] ;
+    sh:property [
+        sh:path skos:definition ;
+        sh:datatype rdf:langString ;
+        sh:message "skos:definition must be an rdf:langString (language-tagged literal)." ;
+    ] .

package/src/__fixtures__/shacl/bad/concept.ttl

@@ -0,0 +1,7 @@
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+# Missing language tag on skos:prefLabel — should violate the shape.
+<https://glossarist.org/test/concept/bad>
+    a skos:Concept ;
+    skos:prefLabel "no lang tag" ;
+    skos:definition "Also no lang tag." .

package/src/__fixtures__/shacl/good/concept.ttl

@@ -0,0 +1,8 @@
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+
+<https://glossarist.org/test/concept/good>
+    a skos:Concept ;
+    skos:prefLabel "atomic data unit"@eng ;
+    skos:definition "A data unit that cannot be subdivided."@eng ;
+    dcterms:language "eng" .