@glossarist/concept-browser 0.7.51 → 0.7.52

package/src/__tests__/concept-rdf/round-trip.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from 'vitest';
+import { Parser, Store } from 'n3';
+import { writeTurtle } from '../../components/concept-rdf/turtle-writer';
+import { writeJsonLd } from '../../components/concept-rdf/jsonld-writer';
+import { emitConceptGraph } from '../../components/concept-rdf/concept-emitter';
+import { GLOSS, SKOS, SKOSXL, DCTERMS, RDF, PROV, XSD } from '../../components/concept-rdf/predicates';
+import { CONCEPT_FIXTURES } from '../__fixtures__/concepts';
+
+function expandPrefixed(value: string): string {
+  if (value.startsWith('gloss:'))   return `https://www.glossarist.org/ontologies/${value.slice(6)}`;
+  if (value.startsWith('skos:'))    return `http://www.w3.org/2004/02/skos/core#${value.slice(5)}`;
+  if (value.startsWith('skosxl:'))  return `http://www.w3.org/2008/05/skos-xl#${value.slice(7)}`;
+  if (value.startsWith('dcterms:')) return `http://purl.org/dc/terms/${value.slice(8)}`;
+  if (value.startsWith('rdf:'))     return `http://www.w3.org/1999/02/22-rdf-syntax-ns#${value.slice(4)}`;
+  if (value.startsWith('rdfs:'))    return `http://www.w3.org/2000/01/rdf-schema#${value.slice(5)}`;
+  if (value.startsWith('prov:'))    return `http://www.w3.org/ns/prov#${value.slice(5)}`;
+  if (value.startsWith('xsd:'))     return `http://www.w3.org/2001/XMLSchema#${value.slice(4)}`;
+  return value;
+}
+
+function parseTurtle(turtle: string): Store {
+  const parser = new Parser({ format: 'Turtle' });
+  const store = new Store();
+  store.addQuads(parser.parse(turtle));
+  return store;
+}
+
+const RDF_TYPE = expandPrefixed(RDF.type);
+
+describe('RDF round-trip — Layer 2 fixture corpus (Turtle)', () => {
+  for (const fixture of CONCEPT_FIXTURES) {
+    describe(`fixture: ${fixture.name}`, () => {
+      it('parses without errors and yields a non-empty graph', () => {
+        const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+        const store = parseTurtle(writeTurtle(graph));
+        expect(store.size).toBeGreaterThan(0);
+      });
+
+      it('preserves the concept type and identifier', () => {
+        const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+        const store = parseTurtle(writeTurtle(graph));
+
+        const types = store.getObjects(fixture.uri, RDF_TYPE, null).map(q => q.value);
+        expect(types).toContain(expandPrefixed(GLOSS.Concept));
+        expect(types).toContain(expandPrefixed(SKOS.Concept));
+
+        const ids = store.getObjects(fixture.uri, expandPrefixed(GLOSS.identifier), null).map(q => q.value);
+        expect(ids).toContain(fixture.concept.id);
+      });
+
+      it('emits a skos:prefLabel and a skosxl:literalForm for every localization', () => {
+        const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+        const store = parseTurtle(writeTurtle(graph));
+
+        for (const lang of fixture.concept.languages) {
+          const lcUri = `${fixture.uri}/${lang}`;
+          const pref = store.getObjects(lcUri, expandPrefixed(SKOS.prefLabel), null);
+          expect(pref.length).toBeGreaterThan(0);
+
+          const lcTypes = store.getObjects(lcUri, RDF_TYPE, null).map(q => q.value);
+          expect(lcTypes).toContain(expandPrefixed(GLOSS.LocalizedConcept));
+
+          const xlLabels = store.getObjects(lcUri, expandPrefixed(SKOSXL.prefLabel), null);
+          expect(xlLabels.length).toBeGreaterThan(0);
+
+          const literalForms = xlLabels.flatMap(label =>
+            store.getObjects(label, expandPrefixed(SKOSXL.literalForm), null),
+          );
+          expect(literalForms.length).toBeGreaterThan(0);
+        }
+      });
+
+      it('preserves isLocalizationOf back-references', () => {
+        const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+        const store = parseTurtle(writeTurtle(graph));
+
+        for (const lang of fixture.concept.languages) {
+          const lcUri = `${fixture.uri}/${lang}`;
+          const parents = store.getObjects(lcUri, expandPrefixed(GLOSS.isLocalizationOf), null).map(q => q.value);
+          expect(parents).toContain(fixture.uri);
+        }
+      });
+    });
+  }
+});
+
+describe('RDF round-trip — Layer 2 fixture corpus (JSON-LD syntactic)', () => {
+  for (const fixture of CONCEPT_FIXTURES) {
+    it(`${fixture.name}: emits a parseable JSON-LD document with a non-empty @graph`, () => {
+      const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+      const doc = JSON.parse(writeJsonLd(graph));
+      expect(Array.isArray(doc['@graph'])).toBe(true);
+      expect(doc['@graph'].length).toBeGreaterThan(0);
+    });
+
+    it(`${fixture.name}: includes the concept and at least one localized concept node`, () => {
+      const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+      const doc = JSON.parse(writeJsonLd(graph));
+
+      const conceptNode = doc['@graph'].find((n: any) =>
+        Array.isArray(n['@type']) && n['@type'].includes('gloss:Concept'),
+      );
+      expect(conceptNode).toBeDefined();
+      expect(conceptNode['@id']).toBe(fixture.uri);
+
+      const lcNode = doc['@graph'].find((n: any) =>
+        Array.isArray(n['@type']) && n['@type'].includes('gloss:LocalizedConcept'),
+      );
+      expect(lcNode).toBeDefined();
+    });
+  }
+});
+
+describe('RDF round-trip — Turtle and JSON-LD agree on prefLabel values', () => {
+  for (const fixture of CONCEPT_FIXTURES) {
+    it(`${fixture.name}: prefLabel values are identical across formats`, () => {
+      const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+
+      const turtleStore = parseTurtle(writeTurtle(graph));
+      const doc = JSON.parse(writeJsonLd(graph));
+
+      for (const lang of fixture.concept.languages) {
+        const lcUri = `${fixture.uri}/${lang}`;
+        const turtleLabels = turtleStore.getObjects(lcUri, expandPrefixed(SKOS.prefLabel), null).map(q => q.value);
+
+        const lcNode = doc['@graph'].find((n: any) => n['@id'] === lcUri);
+        expect(lcNode).toBeDefined();
+
+        const raw = lcNode['skos:prefLabel'];
+        const arr = Array.isArray(raw) ? raw : [raw];
+        const jsonLabels = arr.map((v: any) => typeof v === 'string' ? v : v['@value']);
+
+        expect(jsonLabels.sort()).toEqual(turtleLabels.slice().sort());
+      }
+    });
+  }
+});
+
+describe('RDF round-trip — fixture-specific invariants', () => {
+  it('multilingual: emits three distinct localizations with matching language codes', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'multilingual')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const langs = ['eng', 'fra', 'jpn'];
+    for (const lang of langs) {
+      const lcUri = `${fixture.uri}/${lang}`;
+      const langsOnLc = store.getObjects(lcUri, expandPrefixed(GLOSS.language), null).map(q => q.value);
+      expect(langsOnLc).toContain(lang);
+    }
+  });
+
+  it('with-sources: every concept-level source is typed as gloss:ConceptSource', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'with-sources')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const sources = store.getObjects(fixture.uri, expandPrefixed(GLOSS.hasSource), null);
+    expect(sources.length).toBeGreaterThanOrEqual(3);
+    for (const src of sources) {
+      const types = store.getObjects(src, RDF_TYPE, null).map(q => q.value);
+      expect(types).toContain(expandPrefixed(GLOSS.ConceptSource));
+    }
+  });
+
+  it('with-non-verbal: emits at least three non-verbal representations (URI form, K4)', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'with-non-verbal')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const lcUri = `${fixture.uri}/eng`;
+    const uriLinks = store.getObjects(lcUri, expandPrefixed(GLOSS.hasNonVerbalRepresentation), null);
+    expect(uriLinks.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('with-dates: emits one hasDate blank node per date entry', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'with-dates')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const dates = store.getObjects(fixture.uri, expandPrefixed(GLOSS.hasDate), null);
+    expect(dates.length).toBe(3);
+  });
+
+  it('full-relationships: emits hasRelatedConcept for each related entry', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'full-relationships')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const rels = store.getObjects(fixture.uri, expandPrefixed(GLOSS.hasRelatedConcept), null);
+    expect(rels.length).toBe(5);
+
+    for (const blank of rels) {
+      const typeQuads = store.getObjects(blank, expandPrefixed(GLOSS.relationshipType), null);
+      expect(typeQuads.length).toBe(1);
+    }
+  });
+
+  it('full-relationships: supersedes / superseded_by emit dcterms:replaces / dcterms:isReplacedBy (URN form)', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'full-relationships')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const replaces = store.getObjects(fixture.uri, expandPrefixed(DCTERMS.replaces), null).map(q => q.value);
+    const isReplacedBy = store.getObjects(fixture.uri, expandPrefixed(DCTERMS.isReplacedBy), null).map(q => q.value);
+
+    expect(replaces.some(u => u.startsWith('urn:'))).toBe(true);
+    expect(isReplacedBy.some(u => u.startsWith('urn:'))).toBe(true);
+  });
+
+  it('full-relationships: when a resolveRef callback is provided, dcterms:replaces uses the resolved URI', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'full-relationships')!;
+    const resolver = (ref: { source?: string | null; id?: string | null }): string | undefined => {
+      if (ref.source === 'IEC' && ref.id === '60050-3.1.1') return 'https://glossarist.org/iec/concept/60050-3.1.1';
+      return undefined;
+    };
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri, { resolveRef: resolver });
+    const store = parseTurtle(writeTurtle(graph));
+
+    const replaces = store.getObjects(fixture.uri, expandPrefixed(DCTERMS.replaces), null).map(q => q.value);
+    expect(replaces).toContain('https://glossarist.org/iec/concept/60050-3.1.1');
+  });
+});
+
+describe('RDF round-trip — concept lifecycle (WS J3)', () => {
+  it('withdrawn concept with retired date emits prov:invalidatedAtTime', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'withdrawn')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const invalidated = store.getObjects(fixture.uri, expandPrefixed(PROV.invalidatedAtTime), null).map(q => q.value);
+    expect(invalidated).toContain('2024-09-15T00:00:00Z');
+  });
+
+  it('valid concept with retired date does not emit prov:invalidatedAtTime', () => {
+    const fixture = CONCEPT_FIXTURES.find(f => f.name === 'with-dates')!;
+    const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+    const store = parseTurtle(writeTurtle(graph));
+
+    const invalidated = store.getObjects(fixture.uri, expandPrefixed(PROV.invalidatedAtTime), null);
+    expect(invalidated.length).toBe(0);
+  });
+});

package/src/__tests__/concept-rdf/scoped-examples.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { Parser, Store } from 'n3';
+import { Concept } from 'glossarist';
+import { writeTurtle } from '../../components/concept-rdf/turtle-writer';
+import { emitConceptGraph } from '../../components/concept-rdf/concept-emitter';
+
+const G = 'https://www.glossarist.org/ontologies/';
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+function parse(turtle: string): Store {
+  const parser = new Parser({ format: 'Turtle' });
+  const store = new Store();
+  store.addQuads(parser.parse(turtle));
+  return store;
+}
+
+const BASE = 'https://glossarist.org/fixtures/scoped';
+
+describe('A3/B2 — DetailedDefinition helper with scoped examples recursion', () => {
+  it('emits a gloss:hasExample blank inside gloss:hasNote when the note has examples', () => {
+    const concept = Concept.fromJSON({
+      id: 'scoped.1',
+      uri: `${BASE}/scoped.1`,
+      status: 'valid',
+      localizations: {
+        eng: {
+          language_code: 'eng',
+          entry_status: 'valid',
+          terms: [{ type: 'expression', designation: 'scoped concept', normative_status: 'preferred' }],
+          definition: [{ content: 'Outer definition.' }],
+          notes: [{
+            content: 'NOTE — Outer note text.',
+            examples: [{ content: 'EXAMPLE — Nested scoped example.' }],
+          }],
+        },
+      },
+    });
+
+    const { graph } = emitConceptGraph(concept, concept.uri ?? "");
+    const store = parse(writeTurtle(graph));
+
+    const lcUri = `${BASE}/scoped.1/eng`;
+    const noteBlanks = store.getObjects(lcUri, `${G}hasNote`, null);
+    expect(noteBlanks.length).toBe(1);
+
+    const noteBlank = noteBlanks[0];
+    const noteTypes = store.getObjects(noteBlank, RDF_TYPE, null).map(q => q.value);
+    expect(noteTypes).toContain(`${G}DetailedDefinition`);
+
+    const innerExamples = store.getObjects(noteBlank, `${G}hasExample`, null);
+    expect(innerExamples.length).toBe(1);
+
+    const innerEx = innerExamples[0];
+    const innerExTypes = store.getObjects(innerEx, RDF_TYPE, null).map(q => q.value);
+    expect(innerExTypes).toContain(`${G}DetailedDefinition`);
+
+    const innerValues = store.getObjects(innerEx, 'http://www.w3.org/1999/02/22-rdf-syntax-ns#value', null);
+    expect(innerValues.length).toBe(1);
+    expect((innerValues[0] as any).value).toBe('EXAMPLE — Nested scoped example.');
+  });
+
+  it('recurses through arbitrarily deep scoped example chains', () => {
+    const concept = Concept.fromJSON({
+      id: 'scoped.2',
+      uri: `${BASE}/scoped.2`,
+      status: 'valid',
+      localizations: {
+        eng: {
+          language_code: 'eng',
+          entry_status: 'valid',
+          terms: [{ type: 'expression', designation: 'deep', normative_status: 'preferred' }],
+          definition: [{
+            content: 'Outer def.',
+            examples: [{
+              content: 'EXAMPLE level 1',
+              examples: [{
+                content: 'EXAMPLE level 2 (nested inside example)',
+              }],
+            }],
+          }],
+        },
+      },
+    });
+
+    const { graph } = emitConceptGraph(concept, concept.uri ?? "");
+    const store = parse(writeTurtle(graph));
+
+    const lcUri = `${BASE}/scoped.2/eng`;
+    const defBlanks = store.getObjects(lcUri, `${G}hasDefinition`, null);
+    expect(defBlanks.length).toBe(1);
+
+    const inner1 = store.getObjects(defBlanks[0], `${G}hasExample`, null);
+    expect(inner1.length).toBe(1);
+
+    const inner2 = store.getObjects(inner1[0], `${G}hasExample`, null);
+    expect(inner2.length).toBe(1);
+
+    const inner2Values = store.getObjects(inner2[0], 'http://www.w3.org/1999/02/22-rdf-syntax-ns#value', null);
+    expect((inner2Values[0] as any).value).toBe('EXAMPLE level 2 (nested inside example)');
+  });
+
+  it('does not emit gloss:hasExample when no scoped examples are present', () => {
+    const concept = Concept.fromJSON({
+      id: 'scoped.3',
+      uri: `${BASE}/scoped.3`,
+      status: 'valid',
+      localizations: {
+        eng: {
+          language_code: 'eng',
+          entry_status: 'valid',
+          terms: [{ type: 'expression', designation: 'flat', normative_status: 'preferred' }],
+          definition: [{ content: 'Flat def.' }],
+          notes: [{ content: 'Flat note.' }],
+        },
+      },
+    });
+
+    const { graph } = emitConceptGraph(concept, concept.uri ?? "");
+    const store = parse(writeTurtle(graph));
+
+    const lcUri = `${BASE}/scoped.3/eng`;
+    const noteBlanks = store.getObjects(lcUri, `${G}hasNote`, null);
+    const innerExamples = store.getObjects(noteBlanks[0], `${G}hasExample`, null);
+    expect(innerExamples.length).toBe(0);
+  });
+});

package/src/__tests__/concept-rdf/sections-builder.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { buildSections } from '../../components/concept-rdf/sections-builder';
+import { RdfGraph } from '../../components/concept-rdf/rdf-graph';
+import type { RdfResource } from '../../components/concept-rdf/rdf-graph';
+import { lit, iri, blank, triple } from '../../components/concept-rdf/rdf-graph';
+
+function freshGraph(): RdfGraph {
+  return new RdfGraph();
+}
+
+describe('buildSections', () => {
+  it('produces one ClassInstance per resource', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'gloss:Concept', classLabel: 'Concept', label: 'A' });
+    g.declare('https://ex/b', { classId: 'gloss:LocalizedConcept', classLabel: 'Localized', label: 'B' });
+
+    const sections = buildSections(g);
+    expect(sections).toHaveLength(2);
+    expect(sections[0].classId).toBe('gloss:Concept');
+    expect(sections[1].classId).toBe('gloss:LocalizedConcept');
+  });
+
+  it('carries the resource label as the section label', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { label: '3.1.1', classId: 'gloss:Concept', classLabel: 'Concept' });
+    const sections = buildSections(g);
+    expect(sections[0].label).toBe('3.1.1');
+  });
+
+  it('produces one PropValue per triple', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .literal('gloss:identifier', '1')
+      .literal('gloss:note', 'one')
+      .literal('gloss:note', 'two');
+
+    const props = buildSections(g)[0].props;
+    expect(props).toHaveLength(3);
+  });
+
+  it('marks blank node triples as nested', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .blank('gloss:hasSource', [triple('rdf:value', lit('ISO 1'))])
+      .literal('gloss:identifier', '1');
+
+    const props = buildSections(g)[0].props;
+    const sourceProp = props.find(p => p.predicate === 'gloss:hasSource')!;
+    expect(sourceProp.nested).toBe(true);
+    expect(sourceProp.values[0]).toContain('rdf:value');
+    expect(sourceProp.values[0]).toContain('ISO 1');
+  });
+
+  it('dedupes identical predicate+value pairs within a section', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .literal('gloss:note', 'one')
+      .literal('gloss:note', 'one');
+
+    const props = buildSections(g)[0].props;
+    expect(props).toHaveLength(1);
+  });
+
+  it('keeps separate nested and non-nested entries for the same predicate', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .literal('gloss:hasSource', 'plain string')
+      .blank('gloss:hasSource', [triple('rdf:value', lit('structured'))]);
+
+    const props = buildSections(g)[0].props;
+    const sources = props.filter(p => p.predicate === 'gloss:hasSource');
+    expect(sources).toHaveLength(2);
+    expect(sources.some(p => p.nested === true)).toBe(true);
+    expect(sources.some(p => !p.nested)).toBe(true);
+  });
+
+  it('formats IRI objects as the raw value', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .iri('gloss:related', 'https://ex/other');
+
+    const props = buildSections(g)[0].props;
+    expect(props[0].values[0]).toBe('https://ex/other');
+  });
+
+  it('formats language-tagged literals as the bare value', () => {
+    const g = freshGraph();
+    g.declare('https://ex/a', { classId: 'x', classLabel: 'X', label: 'a' })
+      .literal('skos:prefLabel', 'term', { lang: 'eng' });
+
+    const props = buildSections(g)[0].props;
+    expect(props[0].values[0]).toBe('term');
+  });
+});

package/src/__tests__/concept-rdf/shacl-conformance.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Parser as N3Parser, DataFactory } from 'n3';
+import rdfDataset from '@rdfjs/dataset';
+import ShaclValidator from 'rdf-validate-shacl';
+import { writeTurtle } from '../../components/concept-rdf/turtle-writer';
+import { emitConceptGraph } from '../../components/concept-rdf/concept-emitter';
+import { emitVocabularyGraph } from '../../components/concept-rdf/vocabulary-emitter';
+import { CONCEPT_FIXTURES } from '../__fixtures__/concepts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SHAPES_PATH = join(__dirname, '..', '..', '..', 'data', 'concept-model', 'shapes', 'glossarist.shacl.ttl');
+
+const FACTORY = {
+  namedNode: DataFactory.namedNode,
+  blankNode: DataFactory.blankNode,
+  literal: DataFactory.literal,
+  defaultGraph: DataFactory.defaultGraph,
+  quad: DataFactory.quad,
+  fromTerm: DataFactory.fromTerm,
+  fromQuad: DataFactory.fromQuad,
+  dataset: rdfDataset.dataset.bind(rdfDataset),
+};
+
+const ShaclValidatorCtor = (ShaclValidator as any).default ?? ShaclValidator;
+
+async function parseTurtle(text: string, baseIri: string) {
+  const parser = new N3Parser({ baseIRI: baseIri });
+  const out = FACTORY.dataset();
+  return new Promise((resolve, reject) => {
+    parser.parse(text, (err: Error | null, quad: any) => {
+      if (err) reject(err);
+      else if (quad) out.add(quad);
+      else resolve(out);
+    });
+  });
+}
+
+let validator: InstanceType<typeof ShaclValidatorCtor>;
+let vocabDataset: any;
+
+beforeAll(async () => {
+  const shapesText = readFileSync(SHAPES_PATH, 'utf8');
+  const shapes = await parseTurtle(shapesText, `file://${SHAPES_PATH}`);
+  validator = new ShaclValidatorCtor(shapes, { factory: FACTORY });
+
+  const vocabTtl = writeTurtle(emitVocabularyGraph());
+  vocabDataset = await parseTurtle(vocabTtl, 'https://glossarist.org/vocab');
+});
+
+interface Violation {
+  readonly shape: string;
+  readonly path: string;
+  readonly focus: string;
+  readonly message: string;
+}
+
+function violationsFor(report: any): Violation[] {
+  if (report.conforms) return [];
+  return report.results.map((r: any) => ({
+    shape:   r.shape?.value   ?? '(unknown)',
+    path:    r.path?.value    ?? '(unknown)',
+    focus:   r.focusNode?.value ?? '(unknown)',
+    message: r.message?.length ? r.message.map((m: any) => m.value).join('; ') : '',
+  }));
+}
+
+function uniquePaths(violations: readonly Violation[]): readonly string[] {
+  return [...new Set(violations.map(v => v.path))].sort();
+}
+
+describe('Layer 4 — SHACL conformance for every emitted fixture', () => {
+  for (const fixture of CONCEPT_FIXTURES) {
+    it(`${fixture.name}: emitted Turtle + vocab conforms to glossarist SHACL shapes`, async () => {
+      const { graph } = emitConceptGraph(fixture.concept, fixture.uri);
+      const ttl = writeTurtle(graph);
+      const data = await parseTurtle(ttl, fixture.uri);
+
+      const combined = FACTORY.dataset();
+      for (const q of (vocabDataset as any)) combined.add(q);
+      for (const q of (data as any)) combined.add(q);
+
+      const report = validator.validate(combined);
+      const violations = violationsFor(report);
+
+      if (!report.conforms) {
+        const detail = violations.map(v => `  path=${v.path}\n  focus=${v.focus}`).join('\n');
+        expect.fail(`SHACL violations for ${fixture.name}:\n${detail}`);
+      }
+      expect(report.conforms).toBe(true);
+    });
+  }
+
+  it('vocabulary graph is a valid skos:ConceptScheme set', async () => {
+    const vocabTtl = writeTurtle(emitVocabularyGraph());
+    const ds = await parseTurtle(vocabTtl, 'https://glossarist.org/vocab');
+    const SKOS = 'http://www.w3.org/2004/02/skos/core#';
+    const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+    const concepts = [...(ds as any)].filter((q: any) =>
+      q.predicate.value === RDF_TYPE && q.object.value === `${SKOS}Concept`,
+    );
+    const schemes = [...(ds as any)].filter((q: any) =>
+      q.predicate.value === RDF_TYPE && q.object.value === `${SKOS}ConceptScheme`,
+    );
+    expect(schemes.length).toBeGreaterThan(0);
+    expect(concepts.length).toBeGreaterThan(0);
+  });
+});