@glossarist/concept-browser 0.7.34 → 0.7.37

package/src/adapters/GraphDataSource.ts

@@ -0,0 +1,178 @@
+import type { GraphEdge, GraphNode, SectionNode } from './types';
+import type { Concept, RelatedConcept } from 'glossarist';
+import type { DatasetAdapter } from './DatasetAdapter';
+import { UriRouter } from './UriRouter';
+import { slugify } from '../utils/slugify';
+
+interface DomainNodeJson {
+  uri?: string;
+  id?: string;
+  registerId?: string;
+  label?: string;
+  names?: Record<string, string>;
+  conceptCount?: number;
+  children?: DomainNodeJson[];
+}
+
+interface SectionJson {
+  id: string;
+  names?: Record<string, string>;
+  children?: SectionJson[];
+}
+
+function resolveRefTarget(rc: RelatedConcept, uriBase: string, registerId: string, urnMap?: ReadonlyMap<string, string>): string {
+  if (!rc.ref) return '';
+  const ref = rc.ref;
+  if (ref.id) {
+    let reg = registerId;
+    if (ref.source && !ref.source.startsWith('http')) {
+      reg = urnMap?.get(ref.source) ?? ref.source;
+    }
+    return `${uriBase}/${reg}/concept/${ref.id}`;
+  }
+  if (ref.source && ref.source.startsWith('http')) return ref.source;
+  return ref.source || '';
+}
+
+export class GraphDataSource {
+  constructor(private adapter: DatasetAdapter) {}
+
+  private get baseUrl(): string {
+    return this.adapter.dataUrl;
+  }
+
+  private get registerId(): string {
+    return this.adapter.registerId;
+  }
+
+  private get uriBase(): string {
+    return this.adapter.manifest?.uriBase || 'https://glossarist.org';
+  }
+
+  private get urnMap(): ReadonlyMap<string, string> {
+    return this.adapter.urnMap;
+  }
+
+  async loadEdgeIndex(): Promise<GraphEdge[]> {
+    const resp = await fetch(`${this.baseUrl}/edges.json`);
+    if (!resp.ok) return [];
+    const data = await resp.json();
+    return data.edges ?? [];
+  }
+
+  async loadGraphNodes(): Promise<{ uriPrefix: string; nodes: [string, Record<string, string>, string][] }> {
+    const resp = await fetch(`${this.baseUrl}/graph-nodes.json`);
+    if (!resp.ok) return { uriPrefix: '', nodes: [] };
+    return await resp.json();
+  }
+
+  async loadDomainNodes(): Promise<GraphNode[]> {
+    const resp = await fetch(`${this.baseUrl}/domain-nodes.json`);
+    if (!resp.ok) return [];
+    const data = await resp.json();
+    return (data.domainNodes || []).map((dn: DomainNodeJson) => this.mapDomainNode(dn));
+  }
+
+  extractEdges(concept: Concept): GraphEdge[] {
+    const edges: GraphEdge[] = [];
+    const sourceUri = concept.uri || `${this.uriBase}/${this.registerId}/concept/${concept.id}`;
+
+    for (const rc of concept.relatedConcepts) {
+      const target = resolveRefTarget(rc, this.uriBase, this.registerId, this.urnMap);
+      if (target && target !== sourceUri) {
+        const parsed = UriRouter.parseUri(target);
+        edges.push({
+          source: sourceUri,
+          target,
+          type: rc.type || 'references',
+          label: rc.content || undefined,
+          register: parsed?.registerId ?? this.registerId,
+        });
+      }
+    }
+
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (!lc) continue;
+      for (const rc of lc.related) {
+        const target = resolveRefTarget(rc, this.uriBase, this.registerId, this.urnMap);
+        if (target && target !== sourceUri) {
+          const parsed = UriRouter.parseUri(target);
+          edges.push({
+            source: sourceUri,
+            target,
+            type: rc.type || 'references',
+            label: rc.content || undefined,
+            register: parsed?.registerId ?? this.registerId,
+            lang,
+          });
+        }
+      }
+    }
+
+    return edges;
+  }
+
+  extractDomainEdges(concept: Concept): GraphEdge[] {
+    const edges: GraphEdge[] = [];
+    const sourceUri = concept.uri || `${this.uriBase}/${this.registerId}/concept/${concept.id}`;
+
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (lc?.domain) {
+        edges.push({
+          source: sourceUri,
+          target: `${this.uriBase}/${this.registerId}/domain/${slugify(lc.domain)}`,
+          type: 'domain',
+          label: lc.domain,
+          register: this.registerId,
+          lang,
+        });
+      }
+    }
+    return edges;
+  }
+
+  getSectionTree(): SectionNode[] {
+    const nodes = this.adapter.manifest?.sections;
+    if (!nodes || nodes.length === 0) return [];
+    return nodes.map(s => this.mapManifestSection(s));
+  }
+
+  private mapDomainNode(dn: DomainNodeJson): GraphNode {
+    const node: GraphNode = {
+      uri: dn.uri ?? '',
+      register: dn.registerId ?? '',
+      conceptId: dn.uri?.split('/domain/')[1] || dn.id || '',
+      designations: dn.names || (dn.label ? { eng: dn.label } : {}),
+      status: 'domain',
+      loaded: true,
+      nodeType: 'domain' as const,
+      conceptCount: dn.conceptCount || 0,
+    };
+    if (dn.children && dn.children.length > 0) {
+      node.children = dn.children.map((c) => this.mapSectionNode(c));
+    }
+    return node;
+  }
+
+  private mapSectionNode(dn: DomainNodeJson): SectionNode {
+    const node: SectionNode = {
+      id: dn.id ?? '',
+      names: dn.names || (dn.label ? { eng: dn.label } : {}),
+      conceptCount: dn.conceptCount || 0,
+    };
+    if (dn.children && dn.children.length > 0) {
+      node.children = dn.children.map((c) => this.mapSectionNode(c));
+    }
+    return node;
+  }
+
+  private mapManifestSection(s: SectionJson): SectionNode {
+    const node: SectionNode = { id: s.id, names: s.names || {}, conceptCount: 0 };
+    if (s.children && s.children.length > 0) {
+      node.children = s.children.map(c => this.mapManifestSection(c));
+    }
+    return node;
+  }
+}

package/src/adapters/ReferenceResolver.ts

@@ -1,39 +1,45 @@
 import type { Resolution } from './types';
 import type { RoutingEntry } from '../config/types';
+import { UriRouter } from './UriRouter';
 
-interface DatasetEntry {
-  id: string;
-  uriPatterns: string[];
-}
+// ── Citation classification ────────────────────────────────────────────────
 
-function extractConceptId(uri: string, pattern: string): string | null {
-  if (!pattern.endsWith('*')) return null;
-  const base = pattern.slice(0, -1);
-  if (!uri.startsWith(base)) return null;
-  const remainder = uri.slice(base.length);
+export type CitationClassification =
+  | 'internal-citation'
+  | 'self-contained-citation'
+  | 'external-citation'
+  | 'unresolved-citation';
 
-  if (uri.startsWith('https://') || uri.startsWith('http://')) {
-    const match = remainder.match(/^\/?concept\/([^/?#]+)/);
-    return match ? match[1] : null;
-  }
-  if (uri.startsWith('urn:')) {
-    return remainder || null;
-  }
-  return null;
+export interface CiteResolution {
+  classification: CitationClassification;
+  resolved: { registerId: string; conceptId: string } | null;
 }
 
-function matchUriPattern(uri: string, pattern: string): boolean {
-  if (!pattern.endsWith('*')) return uri === pattern;
-  return uri.startsWith(pattern.slice(0, -1));
+/**
+ * Lightweight citation shape used for classification.
+ * Uses snake_case to match glossarist's Citation model conventions.
+ */
+interface CitationInput {
+  ref?: { source?: string | null; id?: string | null; version?: string | null } | null;
+  locality?: { type?: string | null; reference_from?: string | null; reference_to?: string | null; referenceFrom?: string | null; referenceTo?: string | null } | null;
+  link?: string | null;
 }
 
+// ── ReferenceResolver ──────────────────────────────────────────────────────
+
+/**
+ * Resolves references (citations, source refs, URNs) to concepts.
+ *
+ * Delegates URI pattern matching to UriRouter (the single authority for URI routing).
+ * Adds its own concerns on top: source-ref mapping, routing table, citation classification.
+ */
 export class ReferenceResolver {
-  private datasets: DatasetEntry[] = [];
   private routing: RoutingEntry[] = [];
   private sourceRefs = new Map<string, { datasetId: string; uriPrefix: string }>();
+  private readonly uriRouter: UriRouter;
 
-  registerDataset(id: string, uriPatterns: string[]): void {
-    this.datasets.push({ id, uriPatterns });
+  constructor(uriRouter: UriRouter) {
+    this.uriRouter = uriRouter;
   }
 
   registerSourceRef(sourceRef: string, datasetId: string, uriPrefix: string): void {
@@ -49,26 +55,20 @@ export class ReferenceResolver {
   }
 
   resolveReference(uri: string, sourceDatasetId?: string): Resolution {
-    // Step 1: Check provided datasets
-    for (const ds of this.datasets) {
-      for (const pattern of ds.uriPatterns) {
-        if (matchUriPattern(uri, pattern)) {
-          const conceptId = extractConceptId(uri, pattern);
-          if (conceptId) {
-            return {
-              type: 'internal',
-              registerId: ds.id,
-              conceptId,
-              crossDataset: sourceDatasetId != null && sourceDatasetId !== ds.id,
-            };
-          }
-        }
-      }
+    // Step 1: Check registered datasets via UriRouter
+    const resolved = this.uriRouter.resolveUri(uri);
+    if (resolved) {
+      return {
+        type: 'internal',
+        registerId: resolved.registerId,
+        conceptId: resolved.conceptId,
+        crossDataset: sourceDatasetId != null && sourceDatasetId !== resolved.registerId,
+      };
     }
 
     // Step 2: Check routing table
     for (const entry of this.routing) {
-      if (matchUriPattern(uri, entry.uri)) {
+      if (this.matchesRoutingPattern(uri, entry.uri)) {
         if (entry.type === 'site') {
           return {
             type: 'site',
@@ -79,7 +79,7 @@ export class ReferenceResolver {
         }
         if (entry.type === 'url') {
           const template = entry.url!;
-          const conceptId = this.extractConceptIdFromRouting(uri, entry.uri);
+          const conceptId = this.extractConceptIdFromRouting(uri);
           const url = template.includes('{conceptId}') && conceptId
             ? template.replace('{conceptId}', conceptId)
             : template;
@@ -115,14 +115,68 @@ export class ReferenceResolver {
     return null;
   }
 
-  private extractConceptIdFromRouting(uri: string, pattern: string): string | null {
-    for (const ds of this.datasets) {
-      for (const dsPattern of ds.uriPatterns) {
-        if (matchUriPattern(uri, dsPattern)) {
-          return extractConceptId(uri, dsPattern);
-        }
+  /**
+   * Classify a citation and resolve it to a concept if possible.
+   * Single source of truth for citation resolution — both classification
+   * and navigation target come from this one method.
+   */
+  resolveCite(citation: CitationInput | null | undefined, sourceDatasetId?: string): CiteResolution {
+    if (!citation?.ref?.source) {
+      return { classification: 'unresolved-citation', resolved: null };
+    }
+
+    const referenceFrom = citation.locality?.reference_from ?? citation.locality?.referenceFrom ?? '';
+    const resolution = this.resolveCitation(citation.ref.source, referenceFrom, sourceDatasetId);
+    if (resolution?.type === 'internal') {
+      return {
+        classification: 'internal-citation',
+        resolved: { registerId: resolution.registerId, conceptId: resolution.conceptId },
+      };
+    }
+
+    if (citation.link) {
+      return { classification: 'self-contained-citation', resolved: null };
+    }
+
+    return { classification: 'external-citation', resolved: null };
+  }
+
+  resolveRelatedRef(ref: { source: string | null; id: string | null } | null, sourceDatasetId?: string): { registerId: string; conceptId: string } | null {
+    if (!ref?.source || !ref?.id) return null;
+    const uri = `${ref.source}/${ref.id}`;
+    const resolution = this.resolveReference(uri, sourceDatasetId);
+    if (resolution.type === 'internal') {
+      return { registerId: resolution.registerId, conceptId: resolution.conceptId.replace(/^\//, '') };
+    }
+    if (ref.source.startsWith('urn:')) {
+      const directUri = ref.source + ref.id;
+      const directRes = this.resolveReference(directUri, sourceDatasetId);
+      if (directRes.type === 'internal') {
+        return { registerId: directRes.registerId, conceptId: directRes.conceptId.replace(/^\//, '') };
       }
     }
-    return extractConceptId(uri, pattern);
+    return null;
+  }
+
+  // ── Routing table helpers ────────────────────────────────────────────────
+
+  private matchesRoutingPattern(uri: string, pattern: string): boolean {
+    if (!pattern.endsWith('*')) return uri === pattern;
+    return uri.startsWith(pattern.slice(0, -1));
+  }
+
+  private extractConceptIdFromRouting(uri: string): string | null {
+    const resolved = this.uriRouter.resolveUri(uri);
+    if (resolved) return resolved.conceptId;
+    // Fallback: extract from URI structure
+    // HTTP: /concept/{id}
+    const httpMatch = uri.match(/\/concept\/([^/?#]+)/);
+    if (httpMatch) return httpMatch[1];
+    // URN: last colon-separated segment
+    if (uri.startsWith('urn:')) {
+      const parts = uri.split(':');
+      return parts.length > 0 ? parts[parts.length - 1] : null;
+    }
+    return null;
   }
 }

package/src/adapters/UriRouter.ts

@@ -1,34 +1,106 @@
 import type { Manifest } from './types';
 
+// ── URI pattern matching ────────────────────────────────────────────────────
+
+function matchUriPattern(uri: string, pattern: string): boolean {
+  if (!pattern.endsWith('*')) return uri === pattern;
+  return uri.startsWith(pattern.slice(0, -1));
+}
+
+function extractConceptId(uri: string, pattern: string): string | null {
+  if (!pattern.endsWith('*')) return null;
+  const base = pattern.slice(0, -1);
+  if (!uri.startsWith(base)) return null;
+  const remainder = uri.slice(base.length);
+
+  if (uri.startsWith('https://') || uri.startsWith('http://')) {
+    const match = remainder.match(/^\/?concept\/([^/?#]+)/);
+    return match ? match[1] : null;
+  }
+  if (uri.startsWith('urn:')) {
+    return remainder || null;
+  }
+  return null;
+}
+
+// ── Static parse regex ──────────────────────────────────────────────────────
+
 const URI_REGISTER_RE = /\/([^/]+)\/concept\/([^/]+)$/;
 
+// ── UriRouter ───────────────────────────────────────────────────────────────
+
+/**
+ * Single source of truth for URI routing.
+ *
+ * Maps URIs to {registerId, conceptId} pairs using dataset-registered URI
+ * patterns. Supports wildcard patterns, URN prefix mapping, and URI construction.
+ *
+ * ReferenceResolver delegates URI matching here and adds its own concerns
+ * (routing table, source refs, citation classification) on top.
+ */
 export class UriRouter {
-  private registerMap = new Map<string, { baseUrl: string; manifest: Manifest | null; uriBase: string }>();
+  /** registerId → { baseUrl, uriBase, uriPatterns } */
+  private registerMap = new Map<string, { baseUrl: string; uriBase: string; uriPatterns: string[] }>();
 
-  registerDataset(registerId: string, baseUrl: string, manifest?: Manifest) {
-    this.registerMap.set(registerId, {
-      baseUrl,
-      manifest: manifest ?? null,
-      uriBase: manifest?.uriBase ?? '',
-    });
+  /** URN prefix → registerId (extracted from uriPatterns at registration time) */
+  private urnMap = new Map<string, string>();
+
+  /**
+   * Register a dataset's URI patterns for routing.
+   * URN-prefixed patterns are also indexed for fast URN → registerId lookup.
+   */
+  registerDataset(registerId: string, baseUrl: string, uriBase: string, uriPatterns: string[]): void {
+    this.registerMap.set(registerId, { baseUrl, uriBase, uriPatterns });
+
+    for (const pattern of uriPatterns) {
+      const base = pattern.endsWith('*') ? pattern.slice(0, -1) : pattern;
+      if (base.startsWith('urn:')) {
+        // Store without trailing colon so prefix matching works naturally
+        const clean = base.endsWith(':') ? base.slice(0, -1) : base;
+        this.urnMap.set(clean, registerId);
+      }
+    }
   }
 
+  /**
+   * Resolve a URI to {registerId, conceptId} using registered patterns.
+   * Returns null if no registered dataset matches.
+   */
   resolveUri(uri: string): { registerId: string; conceptId: string } | null {
     for (const [registerId, info] of this.registerMap) {
-      const prefix = `${info.uriBase}/${registerId}/concept/`;
-      if (uri.startsWith(prefix)) {
-        return { registerId, conceptId: uri.slice(prefix.length) };
+      for (const pattern of info.uriPatterns) {
+        if (matchUriPattern(uri, pattern)) {
+          const conceptId = extractConceptId(uri, pattern);
+          if (conceptId) return { registerId, conceptId };
+        }
       }
     }
     return null;
   }
 
+  /** Resolve a URN prefix to a registerId. Matches by longest prefix. Returns null if unknown. */
+  resolveUrn(urn: string): string | null {
+    // Try exact match first, then progressively shorter prefixes
+    for (let len = urn.length; len > 0; len--) {
+      const prefix = urn.slice(0, len);
+      const match = this.urnMap.get(prefix);
+      if (match) return match;
+    }
+    return null;
+  }
+
+  /** Get the uriBase for a register. Returns empty string if unknown. */
+  getUriBase(registerId: string): string {
+    return this.registerMap.get(registerId)?.uriBase ?? '';
+  }
+
   /** Extract registerId and conceptId from any glossarist URI (no registration needed). */
   static parseUri(uri: string): { registerId: string; conceptId: string } | null {
     const m = uri.match(URI_REGISTER_RE);
     return m ? { registerId: m[1], conceptId: m[2] } : null;
   }
 
+  /** Construct a canonical URI for a concept. */
   buildUri(registerId: string, conceptId: string): string {
     const info = this.registerMap.get(registerId);
     const uriBase = info?.uriBase ?? '';

package/src/adapters/factory.ts

@@ -1,18 +1,18 @@
 import type { DatasetRegistry, Manifest, Resolution } from './types';
 import type { RoutingEntry as ConfigRoutingEntry } from '../config/types';
 import { DatasetAdapter } from './DatasetAdapter';
-import { UriRouter } from './UriRouter';
 import { ReferenceResolver } from './ReferenceResolver';
+import { UriRouter } from './UriRouter';
 
 export class AdapterFactory {
   private adapters = new Map<string, DatasetAdapter>();
-  private urnMap = new Map<string, string>();
-  readonly router = new UriRouter();
-  readonly resolver: ReferenceResolver;
   private crossRefIndex: Record<string, string[]> | null = null;
+  readonly uriRouter: UriRouter;
+  readonly resolver: ReferenceResolver;
 
   constructor() {
-    this.resolver = new ReferenceResolver();
+    this.uriRouter = new UriRouter();
+    this.resolver = new ReferenceResolver(this.uriRouter);
   }
 
   async discoverDatasets(datasetsUrl: string): Promise<DatasetAdapter[]> {
@@ -76,23 +76,43 @@ export class AdapterFactory {
   }
 
   private registerDataset(registerId: string, manifest: Manifest): void {
-    this.router.registerDataset(registerId, `${import.meta.env.BASE_URL}data/${registerId}`, manifest);
-
     const uriPatterns = [
       manifest.datasetUri,
       ...(manifest.uriAliases ?? []),
       manifest.uriBase ? `${manifest.uriBase}/${registerId}/*` : undefined,
     ].filter(Boolean) as string[];
-    this.resolver.registerDataset(registerId, uriPatterns);
 
-    if (manifest.datasetUri) this.urnMap.set(manifest.datasetUri, registerId);
-    for (const alias of manifest.uriAliases ?? []) {
-      const base = alias.endsWith('*') ? alias.slice(0, -1) : alias;
-      if (base.startsWith('urn:')) this.urnMap.set(base, registerId);
+    this.uriRouter.registerDataset(
+      registerId,
+      manifest.baseUrl,
+      manifest.uriBase,
+      uriPatterns,
+    );
+
+    // Propagate URN map to all adapters for ref-target resolution
+    const urnMap = new Map<string, string>();
+    for (const id of this.uriRouter.getRegisteredIds()) {
+      const uriBase = this.uriRouter.getUriBase(id);
+      if (!uriBase) continue;
+      // Reconstruct URN map from uriRouter registrations
+      for (const pattern of [manifest.datasetUri, ...(manifest.uriAliases ?? [])]) {
+        if (!pattern) continue;
+        const base = pattern.endsWith('*') ? pattern.slice(0, -1) : pattern;
+        if (base.startsWith('urn:')) urnMap.set(base, registerId);
+      }
     }
-
+    // Include URNs from all previously registered datasets
     for (const adapter of this.adapters.values()) {
-      adapter.setUrnMap(this.urnMap);
+      const m = adapter.manifest;
+      if (!m) continue;
+      for (const pattern of [m.datasetUri, ...(m.uriAliases ?? [])]) {
+        if (!pattern) continue;
+        const base = pattern.endsWith('*') ? pattern.slice(0, -1) : pattern;
+        if (base.startsWith('urn:')) urnMap.set(base, adapter.registerId);
+      }
+    }
+    for (const adapter of this.adapters.values()) {
+      adapter.setUrnMap(urnMap);
     }
   }
 
@@ -117,20 +137,7 @@ export class AdapterFactory {
   }
 
   resolveRelatedRef(ref: { source: string | null; id: string | null } | null, sourceDatasetId?: string): { registerId: string; conceptId: string } | null {
-    if (!ref?.source || !ref?.id) return null;
-    const uri = `${ref.source}/${ref.id}`;
-    const resolution = this.resolve(uri, sourceDatasetId);
-    if (resolution.type === 'internal') {
-      return { registerId: resolution.registerId, conceptId: resolution.conceptId.replace(/^\//, '') };
-    }
-    if (ref.source.startsWith('urn:')) {
-      const directUri = ref.source + ref.id;
-      const directRes = this.resolve(directUri, sourceDatasetId);
-      if (directRes.type === 'internal') {
-        return { registerId: directRes.registerId, conceptId: directRes.conceptId.replace(/^\//, '') };
-      }
-    }
-    return null;
+    return this.resolver.resolveRelatedRef(ref, sourceDatasetId);
   }
 
   resolveCitation(source: string, referenceFrom: string, sourceDatasetId?: string): Resolution | null {