@glossarist/concept-browser 0.7.51 → 0.7.52

package/src/__tests__/scripts/vocab-turtle.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { Parser, Store } from 'n3';
+import { buildVocabularyTurtle, listVocabSchemes } from '../../../scripts/lib/vocab-turtle.mjs';
+
+function parse(turtle: string): Store {
+  const parser = new Parser({ format: 'Turtle' });
+  const store = new Store();
+  store.addQuads(parser.parse(turtle));
+  return store;
+}
+
+const SKOS = 'http://www.w3.org/2004/02/skos/core#';
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+describe('buildVocabularyTurtle (mjs)', () => {
+  it('parses without errors and produces a non-empty graph', () => {
+    const ttl = buildVocabularyTurtle();
+    const store = parse(ttl);
+    expect(store.size).toBeGreaterThan(0);
+  });
+
+  it('declares at least one skos:ConceptScheme', () => {
+    const store = parse(buildVocabularyTurtle());
+    const schemes = [...store].filter(q =>
+      q.predicate.value === RDF_TYPE && q.object.value === `${SKOS}ConceptScheme`,
+    );
+    expect(schemes.length).toBeGreaterThan(0);
+  });
+
+  it('declares enumeration IRIs as skos:Concept instances', () => {
+    const store = parse(buildVocabularyTurtle());
+    const concepts = [...store].filter(q =>
+      q.predicate.value === RDF_TYPE && q.object.value === `${SKOS}Concept`,
+    );
+    expect(concepts.length).toBeGreaterThan(10);
+
+    const conceptIris = new Set(concepts.map(q => q.subject.value));
+    expect(conceptIris.has('https://www.glossarist.org/ontologies/status/valid')).toBe(true);
+    expect(conceptIris.has('https://www.glossarist.org/ontologies/norm/preferred')).toBe(true);
+    expect(conceptIris.has('https://www.glossarist.org/ontologies/datetype/accepted')).toBe(true);
+  });
+
+  it('listVocabSchemes returns the seven canonical schemes', () => {
+    const schemes = listVocabSchemes();
+    const ids = schemes.map(s => s.schemeIri);
+    expect(ids).toContain('gloss:status-scheme');
+    expect(ids).toContain('gloss:entstatus-scheme');
+    expect(ids).toContain('gloss:norm-scheme');
+    expect(ids).toContain('gloss:srcstatus-scheme');
+    expect(ids).toContain('gloss:srctype-scheme');
+    expect(ids).toContain('gloss:datetype-scheme');
+    expect(ids).toContain('gloss:rel-scheme');
+    expect(schemes.length).toBe(7);
+  });
+
+  it('emits skos:hasTopConcept and skos:inScheme bidirectionally', () => {
+    const store = parse(buildVocabularyTurtle());
+    const hasTopConcept = [...store].filter(q => q.predicate.value === `${SKOS}hasTopConcept`);
+    const inScheme = [...store].filter(q => q.predicate.value === `${SKOS}inScheme`);
+    expect(hasTopConcept.length).toBeGreaterThan(0);
+    expect(inScheme.length).toBe(hasTopConcept.length);
+  });
+});

package/src/__tests__/use-format-registry.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  registerFormat,
+  unregisterFormat,
+  getFormat,
+  listFormats,
+  clearFormats,
+  type FormatDescriptor,
+} from '../composables/use-format-registry';
+
+const BUILTIN_DESCRIPTORS: FormatDescriptor[] = [
+  { id: 'ttl',    extension: 'ttl',     mediaType: 'text/turtle',           label: 'Turtle',      available: 'both',         serialize: 'build' },
+  { id: 'jsonld', extension: 'jsonld',  mediaType: 'application/ld+json',   label: 'JSON-LD',     available: 'both',         serialize: 'build' },
+  { id: 'yaml',   extension: 'yaml',   mediaType: 'application/yaml',       label: 'YAML',        available: 'per-concept',  serialize: 'build' },
+  { id: 'tbx',    extension: 'tbx.xml', mediaType: 'application/x-tbx',     label: 'TBX',         available: 'aggregate',    serialize: 'build' },
+  { id: 'jsonl',  extension: 'jsonl',  mediaType: 'application/jsonl+json', label: 'JSON-Lines',  available: 'aggregate',    serialize: 'build' },
+];
+
+function resetToBuiltins() {
+  clearFormats();
+  for (const desc of BUILTIN_DESCRIPTORS) {
+    registerFormat(desc);
+  }
+}
+
+describe('FormatRegistry', () => {
+  beforeEach(resetToBuiltins);
+  afterEach(resetToBuiltins);
+
+  describe('registerFormat / getFormat', () => {
+    it('registers and retrieves a format by id', () => {
+      registerFormat({ id: 'csv', extension: 'csv', mediaType: 'text/csv', label: 'CSV', available: 'both', serialize: 'build' });
+      const got = getFormat('csv');
+      expect(got).toBeDefined();
+      expect(got?.extension).toBe('csv');
+      expect(got?.label).toBe('CSV');
+    });
+
+    it('overwrites an existing format with the same id', () => {
+      registerFormat({ id: 'csv', extension: 'csv', mediaType: 'text/csv', label: 'Old', available: 'both', serialize: 'build' });
+      registerFormat({ id: 'csv', extension: 'csv', mediaType: 'text/csv', label: 'New', available: 'both', serialize: 'build' });
+      expect(getFormat('csv')?.label).toBe('New');
+    });
+
+    it('returns undefined for unknown ids', () => {
+      expect(getFormat('does-not-exist')).toBeUndefined();
+    });
+  });
+
+  describe('unregisterFormat', () => {
+    it('removes a format from the registry', () => {
+      registerFormat({ id: 'csv', extension: 'csv', mediaType: 'text/csv', label: 'CSV', available: 'both', serialize: 'build' });
+      unregisterFormat('csv');
+      expect(getFormat('csv')).toBeUndefined();
+    });
+
+    it('is a no-op for unknown ids', () => {
+      expect(() => unregisterFormat('never-registered')).not.toThrow();
+    });
+  });
+
+  describe('listFormats', () => {
+    it('returns all registered formats sorted by label', () => {
+      const all = listFormats();
+      const labels = all.map(f => f.label);
+      const sorted = [...labels].sort((a, b) => a.localeCompare(b));
+      expect(labels).toEqual(sorted);
+    });
+
+    it('returns formats whose availability matches the filter or is "both"', () => {
+      const perConcept = listFormats({ availability: 'per-concept' });
+      for (const f of perConcept) {
+        expect(['per-concept', 'both']).toContain(f.available);
+      }
+    });
+
+    it('returns formats whose availability matches aggregate filter or is "both"', () => {
+      const aggregate = listFormats({ availability: 'aggregate' });
+      for (const f of aggregate) {
+        expect(['aggregate', 'both']).toContain(f.available);
+      }
+    });
+
+    it('includes both-availability formats in per-concept listings', () => {
+      const perConcept = listFormats({ availability: 'per-concept' });
+      const ids = perConcept.map(f => f.id);
+      expect(ids).toContain('ttl');
+      expect(ids).toContain('jsonld');
+      expect(ids).toContain('yaml');
+    });
+
+    it('excludes per-concept-only formats from aggregate listings', () => {
+      const aggregate = listFormats({ availability: 'aggregate' });
+      const ids = aggregate.map(f => f.id);
+      expect(ids).not.toContain('yaml');
+    });
+  });
+
+  describe('built-in registrations', () => {
+    it('registers ttl, jsonld, yaml, tbx, jsonl on module load', () => {
+      for (const id of ['ttl', 'jsonld', 'yaml', 'tbx', 'jsonl']) {
+        expect(getFormat(id)).toBeDefined();
+      }
+    });
+
+    it('gives ttl and jsonld a per-concept-and-aggregate availability', () => {
+      expect(getFormat('ttl')?.available).toBe('both');
+      expect(getFormat('jsonld')?.available).toBe('both');
+    });
+
+    it('gives yaml a per-concept-only availability', () => {
+      expect(getFormat('yaml')?.available).toBe('per-concept');
+    });
+
+    it('gives tbx and jsonl an aggregate-only availability', () => {
+      expect(getFormat('tbx')?.available).toBe('aggregate');
+      expect(getFormat('jsonl')?.available).toBe('aggregate');
+    });
+
+    it('declares media types distinct from extensions where appropriate', () => {
+      expect(getFormat('ttl')?.mediaType).toBe('text/turtle');
+      expect(getFormat('tbx')?.extension).toBe('tbx.xml');
+    });
+  });
+});

package/src/__tests__/utils/bcp47.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseLangTag,
+  formatLangTag,
+  canonicalLangTag,
+  isValidLangTag,
+  mapIso6393To6391,
+  mapIso6391To6393,
+  isNfc,
+  toNfc,
+} from '../../utils/bcp47';
+import { InvalidLangTagError } from '../../errors';
+
+describe('parseLangTag', () => {
+  it('maps ISO 639-3 codes to ISO 639-1', () => {
+    expect(parseLangTag('eng').primary).toBe('en');
+    expect(parseLangTag('fra').primary).toBe('fr');
+    expect(parseLangTag('deu').primary).toBe('de');
+  });
+
+  it('passes through unknown 3-letter codes unchanged', () => {
+    expect(parseLangTag('xxx').primary).toBe('xxx');
+  });
+
+  it('preserves ISO 639-1 codes', () => {
+    expect(parseLangTag('en').primary).toBe('en');
+    expect(parseLangTag('fr').primary).toBe('fr');
+  });
+
+  it('captures the script subtag', () => {
+    const tag = parseLangTag('zh-Hant');
+    expect(tag.script).toBe('Hant');
+  });
+
+  it('captures the region subtag (alpha-2)', () => {
+    const tag = parseLangTag('en-US');
+    expect(tag.region).toBe('US');
+  });
+
+  it('captures the region subtag (UN M.49 numeric)', () => {
+    const tag = parseLangTag('zh-156');
+    expect(tag.region).toBe('156');
+  });
+
+  it('captures variants', () => {
+    const tag = parseLangTag('ca-ES-valencia');
+    expect(tag.variants).toEqual(['valencia']);
+  });
+
+  it('captures private-use', () => {
+    const tag = parseLangTag('en-x-foo-bar');
+    expect(tag.privateUse).toEqual(['foo', 'bar']);
+  });
+
+  it('defaults multi-script languages to their primary script', () => {
+    expect(parseLangTag('zho').script).toBe('Hans');
+    expect(parseLangTag('srp').script).toBe('Cyrl');
+    expect(parseLangTag('uzb').script).toBe('Latn');
+  });
+
+  it('keeps an explicitly-provided script over the default', () => {
+    expect(parseLangTag('zho-Hant').script).toBe('Hant');
+  });
+
+  it('throws on invalid primary subtags', () => {
+    expect(() => parseLangTag('')).toThrow(InvalidLangTagError);
+    expect(() => parseLangTag('!@#')).toThrow(InvalidLangTagError);
+  });
+
+  it('throws on unrecognized subtag shapes', () => {
+    expect(() => parseLangTag('en-***')).toThrow(InvalidLangTagError);
+  });
+
+  it('preserves the original input on the tag', () => {
+    const tag = parseLangTag('eng-US');
+    expect(tag.raw).toBe('eng-US');
+  });
+});
+
+describe('formatLangTag', () => {
+  it('joins subtags with hyphens', () => {
+    const tag = parseLangTag('eng-Hant-US');
+    expect(formatLangTag(tag)).toBe('en-Hant-US');
+  });
+
+  it('omits undefined subtags', () => {
+    expect(formatLangTag(parseLangTag('eng'))).toBe('en');
+  });
+
+  it('emits private-use prefix', () => {
+    expect(formatLangTag(parseLangTag('en-x-foo'))).toBe('en-x-foo');
+  });
+
+  it('emits variants inline', () => {
+    expect(formatLangTag(parseLangTag('ca-valencia'))).toBe('ca-valencia');
+  });
+});
+
+describe('canonicalLangTag', () => {
+  it('canonicalizes ISO 639-3 codes to ISO 639-1', () => {
+    expect(canonicalLangTag('eng')).toBe('en');
+    expect(canonicalLangTag('fra')).toBe('fr');
+    expect(canonicalLangTag('zho')).toBe('zh-Hans');
+  });
+
+  it('preserves script+region on canonical form', () => {
+    expect(canonicalLangTag('zho-Hant-HK')).toBe('zh-Hant-HK');
+  });
+
+  it('is idempotent', () => {
+    const once = canonicalLangTag('eng-Hant-US');
+    expect(canonicalLangTag(once)).toBe(once);
+  });
+});
+
+describe('isValidLangTag', () => {
+  it('accepts well-formed tags', () => {
+    expect(isValidLangTag('en')).toBe(true);
+    expect(isValidLangTag('eng')).toBe(true);
+    expect(isValidLangTag('zh-Hans-CN')).toBe(true);
+    expect(isValidLangTag('en-x-foo')).toBe(true);
+  });
+
+  it('rejects malformed tags', () => {
+    expect(isValidLangTag('')).toBe(false);
+    expect(isValidLangTag('!!!')).toBe(false);
+  });
+});
+
+describe('ISO 639 mapping', () => {
+  it('maps 639-3 → 639-1', () => {
+    expect(mapIso6393To6391('eng')).toBe('en');
+    expect(mapIso6393To6391('fra')).toBe('fr');
+    expect(mapIso6393To6391('xxx')).toBeNull();
+  });
+
+  it('maps 639-1 → 639-3', () => {
+    expect(mapIso6391To6393('en')).toBe('eng');
+    expect(mapIso6391To6393('fr')).toBe('fra');
+    expect(mapIso6391To6393('xx')).toBeNull();
+  });
+
+  it('round-trips through both maps', () => {
+    for (const code of ['en', 'fr', 'de', 'ja', 'ar', 'ru']) {
+      const three = mapIso6391To6393(code)!;
+      expect(mapIso6393To6391(three)).toBe(code);
+    }
+  });
+});
+
+describe('NFC utilities', () => {
+  it('detects already-NFC strings', () => {
+    expect(isNfc('hello')).toBe(true);
+    expect(isNfc('atomic data unit')).toBe(true);
+  });
+
+  it('detects non-NFC strings', () => {
+    const nfd = 'café'.normalize('NFD');
+    expect(isNfc(nfd)).toBe(false);
+  });
+
+  it('normalizes non-NFC strings', () => {
+    const nfd = 'café'.normalize('NFD');
+    expect(toNfc(nfd)).toBe('café'.normalize('NFC'));
+  });
+});

package/src/__tests__/utils/color-theme.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createColorTheme, type ColorPair } from '../../utils/color-theme';
+import type { SiteColors } from '../../config/types';
+
+const COLORS_JSON = JSON.parse(readFileSync(join(process.cwd(), 'data', 'colors.json'), 'utf8'));
+
+describe('color system v2 — defaults', () => {
+  it('every relationship category has both light and dark variants', () => {
+    const entries = COLORS_JSON.relationshipCategory;
+    for (const [key, pair] of Object.entries(entries)) {
+      const p = pair as ColorPair;
+      expect(p.light, `${key}.light missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      expect(p.dark, `${key}.dark missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      expect(p.light).not.toBe(p.dark);
+    }
+  });
+
+  it('every group-kind has both light and dark variants', () => {
+    const entries = COLORS_JSON.groupKind;
+    for (const [key, pair] of Object.entries(entries)) {
+      const p = pair as ColorPair;
+      expect(p.light, `${key}.light missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      expect(p.dark, `${key}.dark missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+    }
+  });
+
+  it('every concept-status has both light and dark variants', () => {
+    const entries = COLORS_JSON.conceptStatus;
+    for (const [key, pair] of Object.entries(entries)) {
+      const p = pair as ColorPair;
+      expect(p.light, `${key}.light missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+      expect(p.dark, `${key}.dark missing`).toMatch(/^#[0-9A-Fa-f]{6}$/);
+    }
+  });
+});
+
+describe('color system v2 — resolution', () => {
+  it('falls back to category default when type has no override', () => {
+    const theme = createColorTheme(undefined);
+    const supersedes = theme.relationshipTypeColor('supersedes');
+    const lifecycle = theme.relationshipCategoryColor('lifecycle');
+    expect(supersedes).toEqual(lifecycle);
+  });
+
+  it('uses explicit type override when provided', () => {
+    const overrides: SiteColors = {
+      relationshipType: {
+        supersedes: { light: '#FF0000', dark: '#FF5555' },
+      },
+    };
+    const theme = createColorTheme(overrides);
+    const result = theme.relationshipTypeColor('supersedes');
+    expect(result).toEqual({ light: '#FF0000', dark: '#FF5555' });
+  });
+
+  it('uses string-form override (single hex applied to both modes)', () => {
+    const overrides: SiteColors = {
+      relationshipType: {
+        supersedes: '#ABCDEF',
+      },
+    };
+    const theme = createColorTheme(overrides);
+    const result = theme.relationshipTypeColor('supersedes');
+    expect(result).toEqual({ light: '#ABCDEF', dark: '#ABCDEF' });
+  });
+
+  it('falls back to associative category for unknown type', () => {
+    const theme = createColorTheme(undefined);
+    const result = theme.relationshipTypeColor('nonexistent_type');
+    expect(result).toEqual(theme.relationshipCategoryColor('associative'));
+  });
+
+  it('dataset override takes precedence over declared color', () => {
+    const overrides: SiteColors = {
+      dataset: {
+        'viml-2022': { light: '#FF0000', dark: '#FF5555' },
+      },
+    };
+    const theme = createColorTheme(overrides);
+    const declared = { light: '#0000FF', dark: '#00FF00' };
+    const result = theme.datasetColor('viml-2022', declared);
+    expect(result).toEqual({ light: '#FF0000', dark: '#FF5555' });
+  });
+
+  it('declared dataset color is used when no override', () => {
+    const theme = createColorTheme(undefined);
+    const declared = { light: '#0000FF', dark: '#00FF00' };
+    const result = theme.datasetColor('viml-2022', declared);
+    expect(result).toEqual(declared);
+  });
+
+  it('legacy single-hex declared color is applied to both modes', () => {
+    const theme = createColorTheme(undefined);
+    const result = theme.datasetColor('viml-2022', '#3366ff');
+    expect(result.light).toBe('#3366ff');
+    expect(result.dark).toBe('#3366ff');
+  });
+
+  it('concept status override works', () => {
+    const overrides: SiteColors = {
+      conceptStatus: {
+        valid: '#00FF00',
+      },
+    };
+    const theme = createColorTheme(overrides);
+    const result = theme.conceptStatusColor('valid');
+    expect(result).toEqual({ light: '#00FF00', dark: '#00FF00' });
+  });
+
+  it('group kind override works', () => {
+    const overrides: SiteColors = {
+      groupKind: {
+        lineage: { light: '#111111', dark: '#222222' },
+      },
+    };
+    const theme = createColorTheme(overrides);
+    const result = theme.groupKindColor('lineage');
+    expect(result).toEqual({ light: '#111111', dark: '#222222' });
+  });
+});
+
+describe('color system v2 — README contract', () => {
+  it('relationshipCategory defaults cover all 9 categories', () => {
+    const expected = [
+      'lifecycle', 'mapping', 'hierarchical', 'associative',
+      'comparative', 'definitional', 'spatiotemporal', 'lexical', 'designation',
+    ];
+    const actual = Object.keys(COLORS_JSON.relationshipCategory);
+    for (const e of expected) {
+      expect(actual).toContain(e);
+    }
+  });
+
+  it('groupKind defaults cover all 5 DatasetGroupKind values', () => {
+    const expected = ['lineage', 'topic', 'family', 'collection', 'default'];
+    const actual = Object.keys(COLORS_JSON.groupKind);
+    for (const e of expected) {
+      expect(actual).toContain(e);
+    }
+  });
+});

package/src/__tests__/utils/url-safety.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { isSafeUrl, sanitizeUrl } from '../../utils/url-safety';
+
+describe('isSafeUrl', () => {
+  it('accepts http and https URLs', () => {
+    expect(isSafeUrl('https://example.com')).toBe(true);
+    expect(isSafeUrl('http://example.com')).toBe(true);
+    expect(isSafeUrl('https://example.com/path?q=1')).toBe(true);
+  });
+
+  it('accepts mailto and tel URLs', () => {
+    expect(isSafeUrl('mailto:foo@example.org')).toBe(true);
+    expect(isSafeUrl('tel:+15551234567')).toBe(true);
+  });
+
+  it('accepts same-document and relative URLs', () => {
+    expect(isSafeUrl('#anchor')).toBe(true);
+    expect(isSafeUrl('/page')).toBe(true);
+    expect(isSafeUrl('./page')).toBe(true);
+    expect(isSafeUrl('../page')).toBe(true);
+  });
+
+  it('rejects javascript: URLs', () => {
+    expect(isSafeUrl('javascript:alert(1)')).toBe(false);
+    expect(isSafeUrl('javascript:/* */alert(1)')).toBe(false);
+  });
+
+  it('rejects data: URLs', () => {
+    expect(isSafeUrl('data:text/html,<script>alert(1)</script>')).toBe(false);
+    expect(isSafeUrl('data:image/png;base64,AAA')).toBe(false);
+  });
+
+  it('rejects file: URLs', () => {
+    expect(isSafeUrl('file:///etc/passwd')).toBe(false);
+  });
+
+  it('rejects URLs with whitespace, angle brackets, or quotes', () => {
+    expect(isSafeUrl('https://example.com/ foo')).toBe(false);
+    expect(isSafeUrl('https://example.com/<script>')).toBe(false);
+    expect(isSafeUrl('https://example.com/" onload="alert(1)')).toBe(false);
+  });
+
+  it('rejects malformed inputs', () => {
+    expect(isSafeUrl('')).toBe(false);
+    expect(isSafeUrl('   ')).toBe(false);
+    expect(isSafeUrl(null as unknown as string)).toBe(false);
+    expect(isSafeUrl(undefined as unknown as string)).toBe(false);
+  });
+
+  it('rejects unknown protocol schemes', () => {
+    expect(isSafeUrl('vbscript:msgbox(1)')).toBe(false);
+    expect(isSafeUrl('about:blank')).toBe(false);
+  });
+});
+
+describe('sanitizeUrl', () => {
+  it('returns the URL if safe', () => {
+    expect(sanitizeUrl('https://example.com')).toBe('https://example.com');
+  });
+
+  it('returns empty string for unsafe URLs', () => {
+    expect(sanitizeUrl('javascript:alert(1)')).toBe('');
+    expect(sanitizeUrl('data:text/html,<script>')).toBe('');
+  });
+});

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');
+  });
+});