@glossarist/concept-browser 0.7.84 → 0.7.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.84",
+  "version": "0.7.86",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "astro": "^7.0.7",
     "d3": "^7.9.0",
     "favicons": "^7.2.0",
-    "glossarist": "^0.4.20",
+    "glossarist": "^0.4.24",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "pinia": "^2.3.1",

package/scripts/build-edges.js

@@ -4,6 +4,13 @@ function buildConceptUri(uriBase, registerId, conceptId) {
 
 const VALID_COMPLETENESS = new Set(['complete', 'partial']);
 const VALID_CERTAINTY = new Set(['confirmed', 'possible']);
+const VALID_MULTIPLICITY = new Set([
+  'compulsory',
+  'optional',
+  'compulsory_multiple',
+  'optional_multiple',
+  'compulsory_at_least_one',
+]);
 
 function validateCompleteness(value) {
   if (value == null) return 'complete';
@@ -15,14 +22,40 @@ function validateCompleteness(value) {
   return value;
 }
 
-function validateCertainty(value) {
-  if (value == null) return 'confirmed';
-  if (!VALID_CERTAINTY.has(value)) {
-    throw new Error(
-      `Invalid partitive member certainty: "${value}". Allowed: confirmed, possible`,
-    );
+/**
+ * Resolve a partitive member's multiplicity from JSON-LD.
+ *
+ * Reads gl:multiplicity first (v3 wire shape, ISO 704:2022). Falls back
+ * to migrating from gl:certainty (v2 wire shape) for one release cycle
+ * until upstream emits multiplicity natively.
+ *
+ *   confirmed → compulsory
+ *   possible  → optional
+ */
+function resolveMultiplicity(member) {
+  const m = member['gl:multiplicity'] ?? member.multiplicity;
+  if (m != null) {
+    if (!VALID_MULTIPLICITY.has(m)) {
+      throw new Error(
+        `Invalid partitive member multiplicity: "${m}". Allowed: ${[...VALID_MULTIPLICITY].join(', ')}`,
+      );
+    }
+    return m;
   }
-  return value;
+  const certainty = member['gl:certainty'] ?? member.certainty;
+  if (certainty != null) {
+    if (!VALID_CERTAINTY.has(certainty)) {
+      throw new Error(
+        `Invalid partitive member certainty: "${certainty}". Allowed: confirmed, possible`,
+      );
+    }
+    return certainty === 'possible' ? 'optional' : 'compulsory';
+  }
+  return 'compulsory';
+}
+
+function resolveIsDelimiting(member) {
+  return member['gl:isDelimiting'] === true || member.isDelimiting === true;
 }
 
 function normalizeLocalizedString(content) {
@@ -183,21 +216,19 @@ function extractPartitiveRelations(concept, registerId, uriBase, urnMap) {
         if (!uri || uri === sourceUri) return null;
         return {
           uri,
-          certainty: validateCertainty(p['gl:certainty']),
+          multiplicity: resolveMultiplicity(p),
+          isDelimiting: resolveIsDelimiting(p),
         };
       })
       .filter(p => p !== null);
 
     if (partitives.length === 0) continue;
 
-    const plurality = resolvePlurality(rel['gl:hasPlurality']);
-
     relations.push({
       source: sourceUri,
       comprehensive,
       partitives,
       completeness: validateCompleteness(rel['gl:completeness']),
-      plurality,
       criterion: normalizeLocalizedString(rel['gl:criterion']),
       register: registerId,
     });
@@ -205,21 +236,6 @@ function extractPartitiveRelations(concept, registerId, uriBase, urnMap) {
   return relations;
 }
 
-function resolvePlurality(plurality) {
-  if (!plurality) return null;
-  const isShared = plurality['gl:isShared'] ?? plurality.is_shared;
-  if (typeof isShared !== 'boolean') return null;
-  const isUncertain = plurality['gl:isUncertain'] ?? plurality.is_uncertain ?? false;
-  const sharedTypeRef = plurality['gl:sharedType'] ?? plurality.shared_type;
-  let sharedType = null;
-  if (sharedTypeRef) {
-    const source = sharedTypeRef['gl:source'] ?? sharedTypeRef.source;
-    const id = sharedTypeRef['gl:id'] ?? sharedTypeRef.id;
-    if (source && id) sharedType = `${source}:${id}`;
-  }
-  return { isShared, isUncertain, sharedType };
-}
-
 function resolveConceptUri(ref, uriBase, urnMap) {
   const source = ref['gl:source'] || ref['source'];
   const id = ref['gl:id'] || ref['id'];

package/scripts/generate-data.mjs

@@ -14,6 +14,23 @@ import { buildVersionHistoryTurtle } from './lib/version-turtle.mjs';
 import { buildBibliographyTurtle } from './lib/bibliography-turtle.mjs';
 import { ttlLit } from './lib/turtle-escape.mjs';
 import { firstNonEmpty } from './lib/first-non-empty.mjs';
+
+// Legacy v2 → v3 migration helper: derive a gl:certainty value from the
+// new ISO 704:2022 multiplicity so consumers that still read certainty
+// keep working during the one-release-cycle deprecation window.
+const CERTAINTY_FROM_MULTIPLICITY = {
+  compulsory: 'confirmed',
+  optional: 'possible',
+  compulsory_multiple: 'confirmed',
+  optional_multiple: 'possible',
+  compulsory_at_least_one: 'confirmed',
+};
+function multiplicityToCertainty(multiplicity) {
+  return multiplicity in CERTAINTY_FROM_MULTIPLICITY
+    ? CERTAINTY_FROM_MULTIPLICITY[multiplicity]
+    : null;
+}
+
 function buildConceptUri(uriBase, registerId, conceptId) {
   return `${uriBase}/${registerId}/concept/${conceptId}`;
 }
@@ -693,7 +710,18 @@ function yamlToJsonLd(conceptYaml, register, refMaps) {
           } else {
             m['gl:ref'] = refToJsonLd(member, 'gl:ConceptRef');
           }
-          if (member.certainty) m['gl:certainty'] = member.certainty;
+          // ISO 704:2022 multiplicity + is_delimiting (v3 wire shape).
+          // Emit both new and legacy fields for one release cycle so
+          // consumers that still read gl:certainty keep working.
+          if (member.multiplicity) m['gl:multiplicity'] = member.multiplicity;
+          if (member.is_delimiting === true || member.isDelimiting === true) {
+            m['gl:isDelimiting'] = true;
+          }
+          // Legacy gl:certainty — derived from multiplicity when not set
+          // explicitly. Remove after consumers migrate to multiplicity.
+          const legacyCertainty = member.certainty
+            ?? multiplicityToCertainty(member.multiplicity);
+          if (legacyCertainty) m['gl:certainty'] = legacyCertainty;
           return m;
         });
       }
@@ -977,7 +1005,14 @@ async function processDataset(dir, register, opts) {
     partitiveRelations: {
       count: 0,
       byCompleteness: { complete: 0, partial: 0 },
-      byMemberCertainty: { confirmed: 0, possible: 0 },
+      byMemberMultiplicity: {
+        compulsory: 0,
+        optional: 0,
+        compulsory_multiple: 0,
+        optional_multiple: 0,
+        compulsory_at_least_one: 0,
+      },
+      delimitingMembers: 0,
       withCriterion: 0,
       withoutCriterion: 0,
       withPlurality: 0,
@@ -1013,9 +1048,14 @@ async function processDataset(dir, register, opts) {
           (s.partitiveRelations.byCompleteness[completeness] || 0) + 1;
         const partitives = rel.partitives || [];
         for (const member of partitives) {
-          const certainty = member.certainty || 'confirmed';
-          s.partitiveRelations.byMemberCertainty[certainty] =
-            (s.partitiveRelations.byMemberCertainty[certainty] || 0) + 1;
+          // Prefer multiplicity; fall back to legacy certainty for one release.
+          const multiplicity = member.multiplicity
+            ?? (member.certainty === 'possible' ? 'optional' : 'compulsory');
+          s.partitiveRelations.byMemberMultiplicity[multiplicity] =
+            (s.partitiveRelations.byMemberMultiplicity[multiplicity] || 0) + 1;
+          if (member.is_delimiting === true || member.isDelimiting === true) {
+            s.partitiveRelations.delimitingMembers += 1;
+          }
         }
         if (rel.criterion) {
           s.partitiveRelations.withCriterion += 1;

package/scripts/migrate-v1-to-v3.d.mts

@@ -0,0 +1,6 @@
+// Type declarations for the .mjs script — vitest needs a typed surface.
+// The actual implementations are imported by value from the script.
+export function isV1PartitiveRelation(rel: unknown): boolean;
+export function migrateRelation(rel: unknown): Record<string, unknown> | null;
+export function migrateConceptData(data: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
+export function isAlreadyMigrated(content: unknown): boolean;

package/scripts/migrate-v1-to-v3.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * migrate-v1-to-v3.mjs — convert partitive relations from v1 (v2 certainty)
+ * to v3 (ISO 704:2022 multiplicity + is_delimiting) in vocab YAML sources.
+ *
+ * Input shape (v1):
+ *   partitive_relations:
+ *     - comprehensive: { source, id }
+ *       parts:
+ *         - { source, id }
+ *       enumeration: complete|partial
+ *       markers: [...]
+ *       content: ...
+ *
+ * Output shape (v3, glossarist 0.4.20 native):
+ *   partitive_relations:
+ *     - comprehensive: { source, id }
+ *       partitives:
+ *         - ref: { source, id }
+ *           certainty: confirmed|possible
+ *           # Migration notes: when glossarist publishes multiplicity
+ *           # natively, regenerate-data.mjs will emit gl:multiplicity
+ *           # alongside gl:certainty; no further YAML change needed.
+ *
+ * Mapping:
+ *   v1 `parts` (each)   → v3 `partitives[i].ref`
+ *   v1 `enumeration`    → v3 `completeness` (rename only)
+ *   v1 `markers`        → DROPPED (v3 reads multiplicity from per-member certainty)
+ *   v1 `content`        → DROPPED (not part of ISO 704 v3; was v1-only)
+ *
+ * The CLI is idempotent: files that already use `partitives:` are
+ * skipped (left to the user to convert by hand if needed).
+ *
+ * Usage:
+ *   node scripts/migrate-v1-to-v3.mjs path/to/dataset.yaml
+ *   node scripts/migrate-v1-to-v3.mjs --in datasets/vim --out datasets/vim-v3
+ *   node scripts/migrate-v1-to-v3.mjs --dry-run path/to/file.yaml
+ *
+ *   --in <dir|file>  input path (file or directory of .yaml)
+ *   --out <dir|file> output path (mirror of --in if not given)
+ *   --dry-run         print what would change; do not write
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ── Pure conversion logic (separated for testability) ────────────────
+
+/** Detect a partitive-relation in v1 shape. */
+export function isV1PartitiveRelation(rel) {
+  return rel && Array.isArray(rel.parts);
+}
+
+/** Convert a single v1 relation to v3 shape. */
+export function migrateRelation(rel) {
+  if (!isV1PartitiveRelation(rel)) return null;
+  return {
+    comprehensive: rel.comprehensive,
+    completeness: rel.enumeration === 'open'
+      ? 'partial'
+      : (rel.enumeration === 'closed' || rel.enumeration == null)
+        ? 'complete'
+        : rel.enumeration,
+    partitives: (rel.parts ?? []).map(p => ({
+      ref: p,
+      certainty: 'confirmed',
+    })),
+    ...(rel.content ? { content: rel.content } : {}),
+  };
+}
+
+/** Migrate a full concept's data block. Returns null if nothing to migrate. */
+export function migrateConceptData(data) {
+  if (!data?.partitive_relations?.length) return null;
+  const migrated = data.partitive_relations
+    .map(migrateRelation)
+    .filter(r => r !== null);
+  if (migrated.length === 0) return null;
+  return { ...data, partitive_relations: migrated };
+}
+
+/** Skip file if already migrated (uses v3 'partitives' field). */
+export function isAlreadyMigrated(content) {
+  return Boolean(content?.data?.partitive_relations?.some?.(rel => Array.isArray(rel.partitives)));
+}
+
+// ── File / directory walking ──────────────────────────────────────────
+
+function walkFiles(input) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return [input];
+  const out = [];
+  for (const entry of fs.readdirSync(input, { withFileTypes: true })) {
+    const full = path.join(input, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(full));
+    else if (entry.isFile() && /\.(ya?ml)$/i.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+/** Very small YAML parser sufficient for our shape — we only touch
+ *  data.partitive_relations[]. We intentionally use js-yaml when available
+ *  (via dynamic import) for full round-trip; otherwise a minimal regex
+ *  fallback handles the structure. */
+async function loadYamlModule() {
+  try {
+    return await import('js-yaml');
+  } catch {
+    return null;
+  }
+}
+
+function outputPath(input, file, outRoot) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return outRoot;
+  const rel = path.relative(input, file);
+  return path.join(outRoot, rel);
+}
+
+async function migrateFile(input, file, options, yaml) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const parsed = yaml ? yaml.load(raw) : JSON.parse(raw);
+  if (!parsed?.data) return { changed: false };
+  if (isAlreadyMigrated(parsed)) return { changed: false, skipped: true };
+  const migrated = migrateConceptData(parsed.data);
+  if (!migrated) return { changed: false };
+  parsed.data = { ...parsed.data, ...migrated };
+  const out = outputPath(input, file, options.out);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const outText = yaml ? yaml.dump(parsed) : JSON.stringify(parsed, null, 2);
+  if (!options.dryRun) fs.writeFileSync(out, outText);
+  return { changed: true, out, in: file };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const opts = { in: null, out: null, dryRun: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--in') opts.in = args[++i];
+    else if (a === '--out') opts.out = args[++i];
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (!opts.in) opts.in = a;
+    else if (!opts.out) opts.out = a;
+  }
+  if (!opts.in) {
+    console.error('Usage: node scripts/migrate-v1-to-v3.mjs --in <dir|file> [--out <dir|file>] [--dry-run]');
+    process.exit(1);
+  }
+  if (!opts.out) opts.out = opts.dryRun ? opts.in : `${opts.in}.v3`;
+  const yaml = await loadYamlModule();
+  if (!yaml) {
+    console.error('js-yaml is required; install via npm install js-yaml');
+    process.exit(1);
+  }
+  const files = walkFiles(opts.in);
+  let changed = 0, skipped = 0, total = 0;
+  for (const f of files) {
+    total++;
+    const res = await migrateFile(opts.in, f, opts, yaml);
+    if (res.changed) {
+      changed++;
+      console.log(`✓ ${res.in} → ${res.out}`);
+    } else if (res.skipped) {
+      skipped++;
+    }
+  }
+  console.log(`\n${changed} migrated, ${skipped} skipped (already v3), ${total - changed - skipped} unchanged.`);
+  if (opts.dryRun) console.log('(dry-run — no files written)');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}