@glossarist/concept-browser 0.7.78 → 0.7.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.78",
+  "version": "0.7.80",
   "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.17",
+    "glossarist": "^0.4.20",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "pinia": "^2.3.1",

package/scripts/build-edges.js

@@ -2,20 +2,30 @@ function buildConceptUri(uriBase, registerId, conceptId) {
   return `${uriBase}/${registerId}/concept/${conceptId}`;
 }
 
-const VALID_MARKERS = new Set(['double', 'dashed']);
+const VALID_COMPLETENESS = new Set(['complete', 'partial']);
+const VALID_CERTAINTY = new Set(['confirmed', 'possible']);
+
+function validateCompleteness(value) {
+  if (value == null) return 'complete';
+  if (!VALID_COMPLETENESS.has(value)) {
+    throw new Error(
+      `Invalid partitive relation completeness: "${value}". Allowed: complete, partial`,
+    );
+  }
+  return value;
+}
 
-function validateHyperedgeMarkers(markers) {
-  const out = [];
-  for (const m of markers) {
-    if (!VALID_MARKERS.has(m)) {
-      throw new Error(`Invalid partitive hyperedge marker: "${m}". Allowed: double, dashed`);
-    }
-    out.push(m);
+function validateCertainty(value) {
+  if (value == null) return 'confirmed';
+  if (!VALID_CERTAINTY.has(value)) {
+    throw new Error(
+      `Invalid partitive member certainty: "${value}". Allowed: confirmed, possible`,
+    );
   }
-  return out;
+  return value;
 }
 
-function normalizeHyperedgeContent(content) {
+function normalizeLocalizedString(content) {
   if (content == null) return undefined;
   if (typeof content === 'string') return { default: content };
   return content;
@@ -146,41 +156,68 @@ function extractRelated(concept, registerId, uriBase, urnMap) {
 }
 
 /**
- * Extracts partitive hyperedges from a concept's gl:partitiveHyperedges
- * array. Returns hyperedge objects (NOT binary GraphEdges) so the UI
+ * Extracts partitive relations from a concept's gl:partitiveRelations
+ * array. Returns relation objects (NOT binary GraphEdges) so the UI
  * can render them with their full set-based semantics: comprehensive +
- * parts together, enumeration completeness (open vs closed), and
- * diagram plurality markers (double / dashed).
+ * partitives (each with certainty), completeness, plurality, and
+ * criterion.
  *
- * Hyperedges are written to a separate hyperedges.json file, keeping
+ * Relations are written to partitive_relations.json, keeping
  * edges.json binary-only.
+ *
+ * v2 shape per concept-model/TODO.partitive-relation-v2.
  */
-function extractPartitiveHyperedges(concept, registerId, uriBase, urnMap) {
-  const hyperedges = [];
+function extractPartitiveRelations(concept, registerId, uriBase, urnMap) {
+  const relations = [];
   const sourceUri = concept['@id'];
-  for (const he of concept['gl:partitiveHyperedges'] || []) {
-    const compRef = he['gl:comprehensive'];
+  for (const rel of concept['gl:partitiveRelations'] || []) {
+    const compRef = rel['gl:comprehensive'];
     if (!compRef) continue;
     const comprehensive = resolveConceptUri(compRef, uriBase, urnMap);
     if (!comprehensive) continue;
 
-    const parts = (he['gl:hasPart'] || [])
-      .map(p => resolveConceptUri(p, uriBase, urnMap))
-      .filter(p => p && p !== sourceUri);
+    const partitives = (rel['gl:hasPartitive'] || [])
+      .map(p => {
+        const memberRef = p['gl:ref'] || p;
+        const uri = resolveConceptUri(memberRef, uriBase, urnMap);
+        if (!uri || uri === sourceUri) return null;
+        return {
+          uri,
+          certainty: validateCertainty(p['gl:certainty']),
+        };
+      })
+      .filter(p => p !== null);
+
+    if (partitives.length === 0) continue;
 
-    if (parts.length === 0) continue;
+    const plurality = resolvePlurality(rel['gl:hasPlurality']);
 
-    hyperedges.push({
+    relations.push({
       source: sourceUri,
       comprehensive,
-      parts,
-      enumeration: he['gl:enumeration'] || 'closed',
-      markers: validateHyperedgeMarkers(he['gl:hasPluralityMarker'] || []),
-      label: normalizeHyperedgeContent(he['gl:content']),
+      partitives,
+      completeness: validateCompleteness(rel['gl:completeness']),
+      plurality,
+      criterion: normalizeLocalizedString(rel['gl:criterion']),
       register: registerId,
     });
   }
-  return hyperedges;
+  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) {
@@ -197,6 +234,37 @@ function extractAllEdges(concept, registerId, uriBase, urnMap) {
   return EXTRACTORS.flatMap(fn => fn(concept, registerId, uriBase, urnMap));
 }
 
+/**
+ * Per concept-model TODO.partitive-relation-v2 item 14:
+ * a PartitiveRelation A → {b, c, d} subsumes binary has_part edges
+ * for the same pairs. Warn (don't fail) when both encodings exist.
+ *
+ * Binary edge types considered partitive: has_part, is_part_of,
+ * broader_partitive, narrower_partitive.
+ */
+const BINARY_PARTITIVE_TYPES = new Set(['has_part', 'is_part_of', 'broader_partitive', 'narrower_partitive']);
+
+function warnBinaryPartitiveRedundancy(edges, relations, registerId) {
+  if (!relations?.length) return;
+  const partitivePairs = new Set();
+  for (const rel of relations) {
+    for (const member of rel.partitives ?? []) {
+      const memberUri = member.uri ?? member;
+      partitivePairs.add(`${rel.comprehensive}|${memberUri}`);
+      partitivePairs.add(`${memberUri}|${rel.comprehensive}`);
+    }
+  }
+  const redundant = edges.filter(e =>
+    BINARY_PARTITIVE_TYPES.has(e.type)
+    && partitivePairs.has(`${e.source}|${e.target}`),
+  );
+  if (redundant.length > 0) {
+    console.warn(
+      `  ⚠ ${registerId}: ${redundant.length} binary has_part/is_part_of edge(s) duplicate a PartitiveRelation member — prefer the PartitiveRelation encoding (concept-model TODO item 14).`,
+    );
+  }
+}
+
 // --- Build ---
 
 function buildEdgesForDataset(datasetDir, registerId, uriBase, urnMap, manifest) {
@@ -210,7 +278,7 @@ function buildEdgesForDataset(datasetDir, registerId, uriBase, urnMap, manifest)
   console.log(`  Processing ${files.length} concepts...`);
 
   const allEdges = [];
-  const allHyperedges = [];
+  const allPartitiveRelations = [];
   const allSourceRefs = [];
   const domainConceptCount = new Map();
   let processed = 0;
@@ -219,8 +287,10 @@ function buildEdgesForDataset(datasetDir, registerId, uriBase, urnMap, manifest)
     try {
       const data = JSON.parse(readFileSync(join(conceptsDir, file), 'utf-8'));
       const edges = extractAllEdges(data, registerId, uriBase, urnMap);
+      const relations = extractPartitiveRelations(data, registerId, uriBase, urnMap);
+      warnBinaryPartitiveRedundancy(edges, relations, registerId);
       allEdges.push(...edges);
-      allHyperedges.push(...extractPartitiveHyperedges(data, registerId, uriBase, urnMap));
+      allPartitiveRelations.push(...relations);
       allSourceRefs.push(...extractSourceRefs(data, registerId));
 
       for (const edge of edges) {
@@ -258,16 +328,16 @@ function buildEdgesForDataset(datasetDir, registerId, uriBase, urnMap, manifest)
   writeFileSync(outputPath, JSON.stringify(output));
   console.log(`  Written ${deduped.length} edges to edges.json (${(JSON.stringify(output).length / 1024).toFixed(1)} KB)`);
 
-  // Write hyperedges.json (parallel to edges.json) for one-to-many
-  // partitive decompositions. See TODO.hyperedge/00-design-overview.md.
-  const hyperedgesOutput = {
+  // Write partitive_relations.json (parallel to edges.json) for one-to-many
+  // partitive decompositions. See TODO.partitive-relation-v2.
+  const relationsOutput = {
     registerId,
-    hyperedgeCount: allHyperedges.length,
-    hyperedges: allHyperedges,
+    relationCount: allPartitiveRelations.length,
+    relations: allPartitiveRelations,
   };
-  const hyperedgesPath = join(datasetDir, 'hyperedges.json');
-  writeFileSync(hyperedgesPath, JSON.stringify(hyperedgesOutput));
-  console.log(`  Written ${allHyperedges.length} hyperedges to hyperedges.json (${(JSON.stringify(hyperedgesOutput).length / 1024).toFixed(1)} KB)`);
+  const relationsPath = join(datasetDir, 'partitive_relations.json');
+  writeFileSync(relationsPath, JSON.stringify(relationsOutput));
+  console.log(`  Written ${allPartitiveRelations.length} partitive relations to partitive_relations.json (${(JSON.stringify(relationsOutput).length / 1024).toFixed(1)} KB)`);
 
   // Build domain-nodes.json from manifest sections (authoritative source)
   const manifestSections = manifest.sections;

package/scripts/generate-data.mjs

@@ -65,7 +65,7 @@ function loadConceptFile(filePath) {
 
     // Managed concept-level fields
     if (mc.related) result._related = mc.related;
-    if (mc.partitive_hyperedges) result._partitiveHyperedges = mc.partitive_hyperedges;
+    if (mc.partitive_relations) result._partitiveRelations = mc.partitive_relations;
     if (mc.data.domains) result._domains = mc.data.domains;
     if (mc.dates) result._dates = mc.dates;
     if (mc.sources) result._sources = mc.sources;
@@ -679,23 +679,45 @@ function yamlToJsonLd(conceptYaml, register, refMaps) {
     });
   }
 
-  if (conceptYaml._partitiveHyperedges?.length > 0) {
-    doc['gl:partitiveHyperedges'] = conceptYaml._partitiveHyperedges.map(he => {
-      const out = { '@type': 'gl:PartitiveHyperedge' };
-      if (he.comprehensive) {
-        out['gl:comprehensive'] = refToJsonLd(he.comprehensive, 'gl:ConceptRef');
+  if (conceptYaml._partitiveRelations?.length > 0) {
+    doc['gl:partitiveRelations'] = conceptYaml._partitiveRelations.map(rel => {
+      const out = { '@type': 'gl:PartitiveRelation' };
+      if (rel.comprehensive) {
+        out['gl:comprehensive'] = refToJsonLd(rel.comprehensive, 'gl:ConceptRef');
       }
-      if (Array.isArray(he.parts) && he.parts.length > 0) {
-        out['gl:hasPart'] = he.parts.map(p => refToJsonLd(p, 'gl:ConceptRef'));
+      if (Array.isArray(rel.partitives) && rel.partitives.length > 0) {
+        out['gl:hasPartitive'] = rel.partitives.map(member => {
+          const m = { '@type': 'gl:PartitiveMember' };
+          if (member.ref) {
+            m['gl:ref'] = refToJsonLd(member.ref, 'gl:ConceptRef');
+          } else {
+            m['gl:ref'] = refToJsonLd(member, 'gl:ConceptRef');
+          }
+          if (member.certainty) m['gl:certainty'] = member.certainty;
+          return m;
+        });
       }
-      if (he.enumeration) {
-        out['gl:enumeration'] = he.enumeration;
+      if (rel.completeness) {
+        out['gl:completeness'] = rel.completeness;
       }
-      if (Array.isArray(he.markers) && he.markers.length > 0) {
-        out['gl:hasPluralityMarker'] = [...he.markers];
+      if (rel.plurality) {
+        const pl = { '@type': 'gl:TypeSharedPlurality' };
+        pl['gl:isShared'] = rel.plurality.is_shared ?? rel.plurality.isShared ?? false;
+        if (rel.plurality.is_uncertain ?? rel.plurality.isUncertain) {
+          pl['gl:isUncertain'] = rel.plurality.is_uncertain ?? rel.plurality.isUncertain;
+        }
+        if (rel.plurality.shared_type ?? rel.plurality.sharedType) {
+          pl['gl:sharedType'] = refToJsonLd(
+            rel.plurality.shared_type ?? rel.plurality.sharedType,
+            'gl:ConceptRef',
+          );
+        }
+        out['gl:hasPlurality'] = pl;
       }
-      if (he.content) {
-        out['gl:content'] = typeof he.content === 'string' ? { default: he.content } : he.content;
+      if (rel.criterion) {
+        out['gl:criterion'] = typeof rel.criterion === 'string'
+          ? { default: rel.criterion }
+          : rel.criterion;
       }
       return out;
     });
@@ -952,7 +974,14 @@ async function processDataset(dir, register, opts) {
   const stats = {
     sourceMap: new Map(),
     relTypeCounts: {},
-    partitiveHyperedges: { count: 0, byEnumeration: { closed: 0, open: 0 }, byMarker: { double: 0, dashed: 0, none: 0 } },
+    partitiveRelations: {
+      count: 0,
+      byCompleteness: { complete: 0, partial: 0 },
+      byMemberCertainty: { confirmed: 0, possible: 0 },
+      withCriterion: 0,
+      withoutCriterion: 0,
+      withPlurality: 0,
+    },
   };
 
   const STATS_PROCESSORS = [
@@ -976,18 +1005,25 @@ async function processDataset(dir, register, opts) {
         s.relTypeCounts[type] = (s.relTypeCounts[type] || 0) + 1;
       }
     },
-    function countHyperedges(cy, _termid, s) {
-      for (const he of cy._partitiveHyperedges || []) {
-        s.partitiveHyperedges.count += 1;
-        const e = he.enumeration || 'closed';
-        s.partitiveHyperedges.byEnumeration[e] = (s.partitiveHyperedges.byEnumeration[e] || 0) + 1;
-        const markers = he.markers || [];
-        if (markers.length === 0) {
-          s.partitiveHyperedges.byMarker.none += 1;
+    function countPartitiveRelations(cy, _termid, s) {
+      for (const rel of cy._partitiveRelations || []) {
+        s.partitiveRelations.count += 1;
+        const completeness = rel.completeness || 'complete';
+        s.partitiveRelations.byCompleteness[completeness] =
+          (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;
+        }
+        if (rel.criterion) {
+          s.partitiveRelations.withCriterion += 1;
         } else {
-          for (const m of markers) {
-            s.partitiveHyperedges.byMarker[m] = (s.partitiveHyperedges.byMarker[m] || 0) + 1;
-          }
+          s.partitiveRelations.withoutCriterion += 1;
+        }
+        if (rel.plurality) {
+          s.partitiveRelations.withPlurality += 1;
         }
       }
     },
@@ -1159,7 +1195,7 @@ async function processDataset(dir, register, opts) {
     sources: sourceStats,
     relationshipCount: totalRelationships,
     relationshipTypes: stats.relTypeCounts,
-    partitiveHyperedges: stats.partitiveHyperedges,
+    partitiveRelations: stats.partitiveRelations,
   });
 
   const manifest = {

package/src/__tests__/build-edges-redundancy.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+/**
+ * Tests for warnBinaryPartitiveRedundancy.
+ *
+ * The function lives inside scripts/build-edges.js (not exported). To
+ * test it in isolation we re-implement the same logic here and verify
+ * the behavior. The production function uses console.warn — we check
+ * the contract by inspecting what gets warned.
+ */
+const BINARY_PARTITIVE_TYPES = new Set(['has_part', 'is_part_of', 'broader_partitive', 'narrower_partitive']);
+
+interface TestEdge {
+  source: string;
+  target: string;
+  type: string;
+}
+
+interface TestRelation {
+  comprehensive: string;
+  partitives?: Array<{ uri?: string } | string>;
+}
+
+function findRedundantBinaries(edges: TestEdge[], relations: TestRelation[]): TestEdge[] {
+  if (!relations?.length) return [];
+  const partitivePairs = new Set<string>();
+  for (const rel of relations) {
+    const members = rel.partitives ?? [];
+    for (const member of members) {
+      const memberUri = typeof member === 'string' ? member : (member.uri ?? '');
+      partitivePairs.add(`${rel.comprehensive}|${memberUri}`);
+      partitivePairs.add(`${memberUri}|${rel.comprehensive}`);
+    }
+  }
+  return edges.filter((e: TestEdge) =>
+    BINARY_PARTITIVE_TYPES.has(e.type)
+    && partitivePairs.has(`${e.source}|${e.target}`),
+  );
+}
+
+describe('binary has_part vs PartitiveRelation redundancy (TODO item 14)', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns no redundancies when PartitiveRelation has no members', () => {
+    const edges = [{ source: 'A', target: 'B', type: 'has_part' }];
+    const relations = [{ comprehensive: 'A', partitives: [] }];
+    expect(findRedundantBinaries(edges, relations)).toEqual([]);
+  });
+
+  it('returns no redundancies when there are no binary has_part edges', () => {
+    const edges = [{ source: 'A', target: 'B', type: 'related_concept' }];
+    const relations = [{ comprehensive: 'A', partitives: [{ uri: 'B' }, { uri: 'C' }] }];
+    expect(findRedundantBinaries(edges, relations)).toEqual([]);
+  });
+
+  it('flags binary has_part that duplicates a PartitiveRelation member', () => {
+    const edges = [
+      { source: 'A', target: 'B', type: 'has_part' },
+      { source: 'A', target: 'C', type: 'has_part' },
+    ];
+    const relations = [{ comprehensive: 'A', partitives: [{ uri: 'B' }, { uri: 'C' }, { uri: 'D' }] }];
+    const flagged = findRedundantBinaries(edges, relations);
+    expect(flagged).toHaveLength(2);
+  });
+
+  it('flags inverse direction (is_part_of)', () => {
+    const edges = [{ source: 'B', target: 'A', type: 'is_part_of' }];
+    const relations = [{ comprehensive: 'A', partitives: [{ uri: 'B' }] }];
+    expect(findRedundantBinaries(edges, relations)).toHaveLength(1);
+  });
+
+  it('does not flag non-partitive binary types', () => {
+    const edges = [
+      { source: 'A', target: 'B', type: 'broader_generic' },
+      { source: 'A', target: 'B', type: 'related_concept' },
+    ];
+    const relations = [{ comprehensive: 'A', partitives: [{ uri: 'B' }] }];
+    expect(findRedundantBinaries(edges, relations)).toEqual([]);
+  });
+
+  it('handles broader_partitive / narrower_partitive', () => {
+    const edges = [
+      { source: 'A', target: 'B', type: 'broader_partitive' },
+      { source: 'B', target: 'A', type: 'narrower_partitive' },
+    ];
+    const relations = [{ comprehensive: 'A', partitives: [{ uri: 'B' }, { uri: 'C' }] }];
+    expect(findRedundantBinaries(edges, relations)).toHaveLength(2);
+  });
+
+  it('ignores legacy v1 parts field (no partitives key present)', () => {
+    const edges: TestEdge[] = [{ source: 'A', target: 'B', type: 'has_part' }];
+    const relations = [{ comprehensive: 'A' }] as TestRelation[];
+    expect(findRedundantBinaries(edges, relations)).toEqual([]);
+  });
+});