@glossarist/concept-browser 0.7.51 → 0.7.53

package/src/__tests__/validate-shacl.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(__dirname, '..', '..', 'scripts', 'validate-shacl.mjs');
+const FIXTURES = join(__dirname, '..', '__fixtures__', 'shacl');
+const SHAPES = join(__dirname, '..', '__fixtures__', 'concept-shape.ttl');
+
+interface RunResult { code: number; stdout: string; stderr: string }
+interface RunOptions { env?: NodeJS.ProcessEnv; shapes?: string }
+interface ExecException extends Error {
+  status?: number;
+  stdout?: Buffer | string;
+  stderr?: Buffer | string;
+}
+
+function execCaught(cmd: string, args: string[], opts: Parameters<typeof execFileSync>[2] = {}): RunResult {
+  try {
+    const stdout = execFileSync(cmd, args, { encoding: 'utf8', ...opts }) as string;
+    return { code: 0, stdout, stderr: '' };
+  } catch (e) {
+    const err = e as ExecException;
+    return {
+      code: err.status ?? 1,
+      stdout: typeof err.stdout === 'string' ? err.stdout : (err.stdout?.toString() ?? ''),
+      stderr: typeof err.stderr === 'string' ? err.stderr : (err.stderr?.toString() ?? ''),
+    };
+  }
+}
+
+function runValidate(dataDir: string, { env, shapes }: RunOptions = {}): RunResult {
+  return execCaught('node', [SCRIPT, '--shapes', shapes ?? SHAPES, dataDir], {
+    env: { ...process.env, ...env },
+  });
+}
+
+function runValidateRaw(args: string[], { env }: RunOptions = {}): RunResult {
+  return execCaught('node', [SCRIPT, ...args], {
+    env: { ...process.env, ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+describe('validate-shacl.mjs', () => {
+  it('passes when a fixture conforms to the shapes', () => {
+    const goodDir = join(FIXTURES, 'good');
+    const result = runValidate(goodDir);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('SHACL validation passed');
+  });
+
+  it('fails when a fixture has missing language tags', () => {
+    const badDir = join(FIXTURES, 'bad');
+    const result = runValidate(badDir);
+    expect(result.code).not.toBe(0);
+    expect(result.stderr).toContain('SHACL validation FAILED');
+    expect(result.stderr).toContain('concept.ttl');
+    expect(result.stderr.toLowerCase()).toContain('langstring');
+  });
+
+  it('aggregates violations across multiple files', () => {
+    const result = runValidate(FIXTURES);
+    expect(result.code).not.toBe(0);
+    expect(result.stderr).not.toContain('good/concept.ttl');
+    expect(result.stderr).toContain('bad/concept.ttl');
+  });
+
+  it('exits cleanly when no .ttl files are found', () => {
+    const emptyDir = join(FIXTURES, 'empty');
+    const result = runValidate(emptyDir);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('No .ttl files');
+  });
+
+  it('errors clearly when --shapes path does not exist', () => {
+    const result = runValidate(FIXTURES, { shapes: '/does/not/exist.ttl' });
+    expect(result.code).not.toBe(0);
+    expect(result.stderr).toContain('Failed to load SHACL shapes');
+  });
+
+  it('accepts SHAPES_PATH env var as fallback when --shapes is omitted', () => {
+    const result = runValidate(join(FIXTURES, 'good'), {
+      env: { SHAPES_PATH: SHAPES },
+    });
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('SHACL validation passed');
+  });
+
+  it('uses the vendored shapes by default when no override is given', () => {
+    const result = runValidateRaw([join(FIXTURES, 'good')], {
+      env: { SHAPES_PATH: '' },
+    });
+    // The vendored shapes live at data/concept-model/shapes/glossarist.shacl.ttl
+    // and ship with the repo. The good fixture conforms to them.
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('SHACL validation passed');
+  });
+});

package/src/adapters/DatasetAdapter.ts

@@ -12,6 +12,12 @@ import type {
 import type { Concept } from 'glossarist';
 import { conceptFromJson } from './model-bridge';
 import { GraphDataSource } from './GraphDataSource';
+import {
+  ChunkLoadError,
+  ConceptNotFoundError,
+  IndexLoadError,
+  ManifestLoadError,
+} from '../errors';
 
 // ── Wire-format types for JSON responses ────────────────────────────────────
 
@@ -82,7 +88,7 @@ export class DatasetAdapter {
   async loadManifest(): Promise<Manifest> {
     if (this.manifestComplete && this.manifest) return this.manifest;
     const resp = await fetch(`${this.baseUrl}/manifest.json`);
-    if (!resp.ok) throw new Error(`Failed to load manifest for ${this.registerId}: ${resp.status}`);
+    if (!resp.ok) throw ManifestLoadError.make(this.registerId, resp.status);
     this.manifest = (await resp.json()) as Manifest;
     this.manifestComplete = true;
     return this.manifest;
@@ -97,7 +103,7 @@ export class DatasetAdapter {
     }
 
     const resp = await fetch(`${this.baseUrl}/index.json`);
-    if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}: ${resp.status}`);
+    if (!resp.ok) throw IndexLoadError.make(this.registerId, resp.status);
     const data = await resp.json();
 
     // Handle both old format (with eng/status fields) and new format (with designations map)
@@ -150,7 +156,7 @@ export class DatasetAdapter {
       meta = await metaResp.json();
     } else {
       const resp = await fetch(`${this.baseUrl}/index.json`);
-      if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}`);
+      if (!resp.ok) throw IndexLoadError.make(this.registerId, resp.status);
       const data = await resp.json();
       this.index = this.normalizeIndex(data as IndexJson);
       this.buildSummaryIndex();
@@ -180,7 +186,7 @@ export class DatasetAdapter {
     if (this.loadedChunks.has(chunkIndex)) return [];
     const chunkFile = `index-${String(chunkIndex).padStart(4, '0')}.json`;
     const resp = await fetch(`${this.baseUrl}/chunks/${chunkFile}`);
-    if (!resp.ok) throw new Error(`Failed to load chunk ${chunkIndex} for ${this.registerId}`);
+    if (!resp.ok) throw ChunkLoadError.make(this.registerId, chunkIndex, resp.status);
     const data = await resp.json();
     this.loadedChunks.add(chunkIndex);
     return data.concepts as ConceptEntry[];
@@ -255,7 +261,7 @@ export class DatasetAdapter {
     }
 
     const resp = await fetch(`${this.baseUrl}/concepts/${conceptId}.json`);
-    if (!resp.ok) throw new Error(`Concept ${conceptId} not found in ${this.registerId}`);
+    if (!resp.ok) throw ConceptNotFoundError.make(this.registerId, conceptId);
     const json = await resp.json();
     const concept = conceptFromJson(json);
     this.conceptCache.set(conceptId, concept);

package/src/adapters/GraphDataSource.ts

@@ -4,6 +4,7 @@ import type { DatasetAdapter } from './DatasetAdapter';
 import { UriRouter } from './UriRouter';
 import { slugify } from '../utils/slugify';
 import { toSectionNode, toSectionTree } from '../utils/section-tree';
+import { ConceptIdentity } from './concept-identity';
 
 interface DomainNodeJson {
   uri?: string;
@@ -23,7 +24,7 @@ function resolveRefTarget(rc: RelatedConcept, uriBase: string, registerId: strin
     if (ref.source && !ref.source.startsWith('http')) {
       reg = urnMap?.get(ref.source) ?? ref.source;
     }
-    return `${uriBase}/${reg}/concept/${ref.id}`;
+    return new ConceptIdentity(ref.id, reg, uriBase).uri;
   }
   if (ref.source && ref.source.startsWith('http')) return ref.source;
   return ref.source || '';

package/src/adapters/UriRouter.ts

@@ -1,4 +1,5 @@
 import type { Manifest } from './types';
+import { ConceptIdentity } from './concept-identity';
 
 // ── URI pattern matching ────────────────────────────────────────────────────
 
@@ -104,7 +105,7 @@ export class UriRouter {
   buildUri(registerId: string, conceptId: string): string {
     const info = this.registerMap.get(registerId);
     const uriBase = info?.uriBase ?? '';
-    return `${uriBase}/${registerId}/concept/${conceptId}`;
+    return new ConceptIdentity(conceptId, registerId, uriBase).uri;
   }
 
   getRegisteredIds(): string[] {

package/src/adapters/concept-identity.ts

@@ -0,0 +1,69 @@
+import { InvalidConceptIdentityError, InvalidConceptUriError } from '../errors';
+
+export interface ConceptIdentityParts {
+  readonly localId: string;
+  readonly registerId: string;
+  readonly uriBase: string;
+}
+
+const CONCEPT_URI_RE = /^(.+)\/([^/]+)\/concept\/(.+)$/;
+
+export class ConceptIdentity implements ConceptIdentityParts {
+  private readonly _uri: string;
+  private readonly _slug: string;
+  private readonly _path: string;
+
+  constructor(
+    public readonly localId: string,
+    public readonly registerId: string,
+    public readonly uriBase: string,
+  ) {
+    if (!localId || !registerId || !uriBase) {
+      throw new InvalidConceptIdentityError(
+        'ConceptIdentity requires non-empty localId, registerId, and uriBase',
+        { localId, registerId, uriBase },
+      );
+    }
+    this._uri = `${uriBase}/${registerId}/concept/${localId}`;
+    this._slug = localId;
+    this._path = `${registerId}/concepts/${localId}`;
+  }
+
+  get uri(): string { return this._uri; }
+  get slug(): string { return this._slug; }
+  get path(): string { return this._path; }
+
+  equals(other: ConceptIdentity): boolean {
+    return this._uri === other._uri;
+  }
+
+  toString(): string { return this._uri; }
+
+  toJSON(): ConceptIdentityParts {
+    return { localId: this.localId, registerId: this.registerId, uriBase: this.uriBase };
+  }
+
+  localizationUri(lang: string): string {
+    return `${this._uri}/${lang}`;
+  }
+
+  designationUri(lang: string, slug: string): string {
+    return `${this._uri}/${lang}/desig/${slug}`;
+  }
+
+  domainUri(domainSlug: string): string {
+    return `${this.uriBase}/${this.registerId}/domain/${domainSlug}`;
+  }
+
+  static fromUri(uri: string): ConceptIdentity {
+    const m = uri.match(CONCEPT_URI_RE);
+    if (!m) {
+      throw InvalidConceptUriError.make(uri);
+    }
+    return new ConceptIdentity(m[3], m[2], m[1]);
+  }
+
+  static isConceptUri(uri: string): boolean {
+    return CONCEPT_URI_RE.test(uri);
+  }
+}

package/src/adapters/factory.ts

@@ -5,6 +5,7 @@ import { ReferenceResolver } from './ReferenceResolver';
 import { UriRouter } from './UriRouter';
 import { NonVerbalEntityResolver } from './non-verbal-resolver';
 import { BibliographyAdapter } from './bibliography-adapter';
+import { DatasetRegistryLoadError, UnknownDatasetError } from '../errors';
 
 export class AdapterFactory {
   private adapters = new Map<string, DatasetAdapter>();
@@ -36,7 +37,7 @@ export class AdapterFactory {
       registry = JSON.parse(inline.textContent) as DatasetRegistry[];
     } else {
       const resp = await fetch(datasetsUrl);
-      if (!resp.ok) throw new Error(`Failed to load dataset registry: ${resp.status}`);
+      if (!resp.ok) throw DatasetRegistryLoadError.make(resp.status, datasetsUrl);
       registry = await resp.json() as DatasetRegistry[];
     }
 
@@ -132,7 +133,7 @@ export class AdapterFactory {
 
   async loadDataset(registerId: string): Promise<DatasetAdapter> {
     const adapter = this.adapters.get(registerId);
-    if (!adapter) throw new Error(`Unknown dataset: ${registerId}`);
+    if (!adapter) throw UnknownDatasetError.make(registerId);
 
     const manifest = await adapter.loadManifest();
     await adapter.loadIndex();

package/src/adapters/model-bridge.ts

@@ -36,6 +36,7 @@ import {
   GRAMMAR_PARTS_OF_SPEECH,
 } from 'glossarist/models';
 import type { ConceptSummary } from './types';
+import { ConceptIdentity } from './concept-identity';
 
 // ── JSON-LD wire-format types ─────────────────────────────────────────────
 
@@ -634,5 +635,5 @@ export function conceptToSummary(concept: Concept): ConceptSummary {
 
 export function conceptUri(concept: Concept, registerId: string, uriBase: string): string {
   if (concept.uri) return concept.uri;
-  return `${uriBase}/${registerId}/concept/${concept.id}`;
+  return new ConceptIdentity(concept.id, registerId, uriBase).uri;
 }

package/src/adapters/non-verbal/glossarist-augment.d.ts

@@ -91,6 +91,13 @@ declare module 'glossarist' {
     static register(type: string, cls: typeof NonVerbalReference): void;
   }
 
+  interface NonVerbRep {
+    readonly caption: string | null;
+    readonly description: string | null;
+    readonly alt: string | null;
+    readonly images: FigureImage[];
+  }
+
   class FigureReference extends NonVerbalReference {
     static fromJSON(data: Record<string, unknown> | string): FigureReference;
   }

package/src/adapters/non-verbal-resolver.ts

@@ -19,6 +19,7 @@ import type { NonVerbalKind } from './non-verbal/types';
 import type { NonVerbalEntity } from 'glossarist';
 import { KIND_TO_DIR, KIND_TO_BRIDGE } from './non-verbal/kind';
 import { anchorId } from '../utils/non-verbal-anchor';
+import { NonVerbalEntityNotFoundError } from '../errors';
 
 export type { NonVerbalKind } from './non-verbal/types';
 export type { NonVerbalEntity } from 'glossarist';
@@ -54,7 +55,7 @@ export class NonVerbalEntityResolver {
       const resp = await this.fetcher(url);
       if (resp.status === 404) return null;
       if (!resp.ok) {
-        throw new Error(`Failed to load ${kind} ${entityId} from ${datasetId}: ${resp.status}`);
+        throw NonVerbalEntityNotFoundError.make(datasetId, kind, entityId, resp.status);
       }
       const doc = (await resp.json()) as Record<string, unknown>;
       const entity = KIND_TO_BRIDGE[kind](doc);