@glossarist/concept-browser 0.7.43 → 0.7.45

package/scripts/lib/build/non-verbal-consumer.mjs

@@ -0,0 +1,221 @@
+/**
+ * Non-verbal entity consumer — reads source entities (JSON-LD preferred,
+ * YAML fallback) and writes per-entity JSON + indexes to public/data/{ds}/.
+ *
+ * Source layout (preferred — produced by `glossarist export`):
+ *   {sourceRoot}/figures/{id}.json
+ *   {sourceRoot}/tables/{id}.json
+ *   {sourceRoot}/formulas/{id}.json
+ *
+ * Fallback layout (raw glossarist YAML — converted minimally until
+ * glossarist-ruby publishes export support for these entities):
+ *   {sourceRoot}/figures/{id}.yaml
+ *   {sourceRoot}/tables/{id}.yaml
+ *   {sourceRoot}/formulas/{id}.yaml
+ *
+ * Output layout:
+ *   public/data/{ds}/figures/{id}.json
+ *   public/data/{ds}/tables/{id}.json
+ *   public/data/{ds}/formulas/{id}.json
+ *   public/data/{ds}/figures-index.json   { id: filename }
+ *   public/data/{ds}/tables-index.json
+ *   public/data/{ds}/formulas-index.json
+ */
+
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+/** @typedef {'figure' | 'table' | 'formula'} NonVerbalKind */
+
+/** @type {Record<NonVerbalKind, { dir: string, type: string }>} */
+const KIND_META = {
+  figure:  { dir: 'figures',  type: 'Figure'  },
+  table:   { dir: 'tables',   type: 'Table'   },
+  formula: { dir: 'formulas', type: 'Formula' },
+};
+
+/**
+ * Convert a raw glossarist YAML entity to a JSON-LD-style document.
+ * This is a temporary consumer-side bridge until glossarist-ruby's
+ * `glossarist export` ships entity JSON-LD output natively.
+ *
+ * The output matches the wire format documented in TODO.figures/11-round-trip-spec.md.
+ *
+ * @param {Record<string, any>} yaml  Parsed YAML entity.
+ * @param {NonVerbalKind} kind
+ * @returns {Record<string, any>}     JSON-LD-style document.
+ */
+function yamlEntityToJsonLd(yaml, kind) {
+  const meta = KIND_META[kind];
+  const doc = {
+    '@type': `gl:${meta.type}`,
+    'gl:id': yaml.id,
+  };
+  if (yaml.identifier) doc['gl:identifier'] = yaml.identifier;
+  if (yaml.caption) doc['gl:caption'] = yaml.caption;
+  if (yaml.alt) doc['gl:altText'] = yaml.alt;
+  if (yaml.description) doc['gl:description'] = yaml.description;
+  if (Array.isArray(yaml.sources) && yaml.sources.length) {
+    doc['gl:source'] = yaml.sources.map(s => yamlSourceToJsonLd(s));
+  }
+
+  if (kind === 'figure') {
+    if (Array.isArray(yaml.images)) {
+      doc['gl:image'] = yaml.images.map(img => ({
+        'gl:src': img.src,
+        'gl:format': img.format,
+        ...(img.role ? { 'gl:role': img.role } : {}),
+        ...(img.width != null ? { 'gl:width': img.width } : {}),
+        ...(img.height != null ? { 'gl:height': img.height } : {}),
+        ...(img.scale != null ? { 'gl:scale': img.scale } : {}),
+      }));
+    }
+    if (Array.isArray(yaml.subfigures) && yaml.subfigures.length) {
+      doc['gl:subfigure'] = yaml.subfigures.map(sub => yamlEntityToJsonLd(sub, 'figure'));
+    }
+  } else if (kind === 'table') {
+    if (yaml.content) {
+      const c = { ...yaml.content };
+      if (c.type) {
+        c['gl:type'] = c.type;
+        delete c.type;
+      }
+      doc['gl:content'] = c;
+    }
+    if (yaml.format) doc['gl:format'] = yaml.format;
+  } else if (kind === 'formula') {
+    if (yaml.expression) doc['gl:expression'] = yaml.expression;
+    if (yaml.notation) doc['gl:notation'] = yaml.notation;
+  }
+
+  return doc;
+}
+
+function yamlSourceToJsonLd(s) {
+  const out = {};
+  if (s.id) out['gl:id'] = s.id;
+  if (s.type) out['gl:sourceType'] = s.type;
+  if (s.status) out['gl:sourceStatus'] = s.status;
+  if (s.modification) out['gl:modification'] = s.modification;
+  if (s.origin) {
+    const o = {};
+    if (s.origin.ref) {
+      o['gl:ref'] = typeof s.origin.ref === 'string'
+        ? s.origin.ref
+        : {
+            ...(s.origin.ref.source ? { 'gl:source': s.origin.ref.source } : {}),
+            ...(s.origin.ref.id ? { 'gl:id': s.origin.ref.id } : {}),
+            ...(s.origin.ref.version ? { 'gl:version': s.origin.ref.version } : {}),
+            ...(s.origin.ref.text ? { 'gl:text': s.origin.ref.text } : {}),
+          };
+    }
+    if (s.origin.locality) {
+      const l = s.origin.locality;
+      o['gl:locality'] = {
+        ...(l.type ? { 'gl:localityType': l.type } : {}),
+        ...(l.reference_from ? { 'gl:referenceFrom': l.reference_from } : {}),
+        ...(l.reference_to ? { 'gl:referenceTo': l.reference_to } : {}),
+      };
+    }
+    if (s.origin.link) o['gl:link'] = s.origin.link;
+    if (Object.keys(o).length) out['gl:origin'] = o;
+  }
+  return out;
+}
+
+/**
+ * Read entities of one kind from sourceDir. Tries JSON first, falls back to YAML.
+ *
+ * @param {string} sourceDir
+ * @param {NonVerbalKind} kind
+ * @returns {Promise<Array<{ id: string, doc: Record<string, any> }>>}
+ */
+async function readEntitiesForKind(sourceDir, kind) {
+  const meta = KIND_META[kind];
+  const dir = path.join(sourceDir, meta.dir);
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  for (const file of files) {
+    const full = path.join(dir, file);
+    const st = await stat(full);
+    if (!st.isFile()) continue;
+    const ext = path.extname(file).toLowerCase();
+    const id = path.basename(file, ext);
+    if (ext === '.json') {
+      try {
+        const doc = JSON.parse(await readFile(full, 'utf8'));
+        out.push({ id, doc });
+      } catch (e) {
+        console.warn(`  Warning: failed to parse ${full}: ${e.message}`);
+      }
+    } else if (ext === '.yaml' || ext === '.yml') {
+      try {
+        const raw = yaml.load(await readFile(full, 'utf8'));
+        if (!raw || typeof raw !== 'object') continue;
+        out.push({ id, doc: yamlEntityToJsonLd(raw, kind) });
+      } catch (e) {
+        console.warn(`  Warning: failed to parse ${full}: ${e.message}`);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Consume non-verbal entities from sourceDir and write to public/data/{ds}/.
+ *
+ * @param {string} sourceRoot  Absolute path to the dataset source root.
+ * @param {string} destRoot    Absolute path to public/data/{ds}/.
+ * @returns {Promise<{ figures: number, tables: number, formulas: number, warnings: string[] }>}
+ */
+export async function consumeDatasetEntities(sourceRoot, destRoot) {
+  const counts = { figures: 0, tables: 0, formulas: 0 };
+  const warnings = [];
+
+  for (const kind of /** @type {NonVerbalKind[]} */ (['figure', 'table', 'formula'])) {
+    const meta = KIND_META[kind];
+    const entities = await readEntitiesForKind(sourceRoot, kind);
+    if (entities.length === 0) continue;
+
+    const outDir = path.join(destRoot, meta.dir);
+    await mkdir(outDir, { recursive: true });
+
+    const index = {};
+    for (const { id, doc } of entities) {
+      const docId = doc['gl:id'] ?? doc['gloss:id'] ?? id;
+      if (docId !== id) {
+        warnings.push(`${meta.dir}/${id}: gl:id (${docId}) does not match filename`);
+      }
+      const dest = path.join(outDir, `${id}.json`);
+      await writeFile(dest, JSON.stringify(doc, null, 2));
+      index[id] = `${meta.dir}/${id}.json`;
+
+      // Basic validation warnings — non-fatal, surface to authors.
+      if (!doc[`gl:${kind === 'figure' ? 'altText' : ''}`] && kind === 'figure') {
+        warnings.push(`${meta.dir}/${id}: missing gl:altText (accessibility)`);
+      }
+      if (!doc['gl:caption']) {
+        warnings.push(`${meta.dir}/${id}: missing gl:caption`);
+      }
+    }
+
+    const indexDest = path.join(destRoot, `${meta.dir}-index.json`);
+    await writeFile(indexDest, JSON.stringify(index, null, 2));
+
+    counts[meta.dir] = entities.length;
+  }
+
+  return {
+    figures: counts.figures,
+    tables: counts.tables,
+    formulas: counts.formulas,
+    warnings,
+  };
+}

package/scripts/lib/local-path-safety.mjs

@@ -0,0 +1,68 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Assert that a dataset's `localPath` is safe to use as an in-place source.
+ *
+ * "Safe" means: the resolved physical location of `localPath` is disjoint
+ * from the staging directory (`.datasets/<id>`). If they overlap, staging
+ * operations (rm, extract, clone) would destroy the user's source data —
+ * the data-loss bug reported in v0.7.43.
+ *
+ * Returns the resolved absolute path on success; throws on any hazard.
+ *
+ * @param {string} datasetId
+ * @param {string} localPath - relative to `root` (or absolute)
+ * @param {{ root?: string, datasetsDir?: string }} [opts]
+ * @returns {string} resolved absolute path
+ */
+/**
+ * Compute the canonical physical path of `p`, resolving symlinks on the
+ * existing prefix. If `p` itself exists, this is just `realpathSync(p)`.
+ * If not, we walk up to the nearest existing ancestor, realpath it, and
+ * re-append the non-existent tail. This is needed because macOS tmpdir
+ * (`/var/folders/...`) is a symlink to `/private/var/folders/...`; without
+ * this, prefix comparisons across the symlink boundary silently fail.
+ */
+function physicalPath(p) {
+  if (fs.existsSync(p)) return fs.realpathSync(p);
+  const parent = path.dirname(p);
+  const parentReal = fs.existsSync(parent) ? fs.realpathSync(parent) : physicalPath(parent);
+  return path.join(parentReal, path.basename(p));
+}
+
+export function assertLocalPathSafe(datasetId, localPath, { root = process.cwd(), datasetsDir } = {}) {
+  const datasetsRoot = datasetsDir || path.join(root, '.datasets');
+  const localResolved = path.resolve(root, localPath);
+
+  if (!fs.existsSync(localResolved)) {
+    throw new Error(`localPath for ${datasetId} does not exist: ${localResolved}`);
+  }
+
+  const localReal = fs.realpathSync(localResolved);
+  const stagedAbs = path.join(datasetsRoot, datasetId);
+  const stagedReal = physicalPath(stagedAbs);
+
+  if (localReal === stagedReal) {
+    throw new Error(
+      `localPath for ${datasetId} resolves to the same physical location as .datasets/${datasetId} ` +
+      `(${localReal}). Refusing to operate — source and staging would clobber. ` +
+      `Use a path outside .datasets/.`
+    );
+  }
+  if (localReal.startsWith(stagedReal + path.sep)) {
+    throw new Error(
+      `localPath for ${datasetId} is nested inside .datasets/${datasetId}. ` +
+      `Refusing to operate — staging operations would destroy source data. ` +
+      `Use a path outside .datasets/.`
+    );
+  }
+  if (stagedReal.startsWith(localReal + path.sep)) {
+    throw new Error(
+      `localPath for ${datasetId} contains .datasets/${datasetId}. ` +
+      `Refusing to operate — staging operations would destroy source data. ` +
+      `Use a path outside localPath.`
+    );
+  }
+  return localReal;
+}

package/src/__tests__/bibliography-adapter.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BibliographyAdapter } from '../adapters/bibliography-adapter';
+
+function makeResponse(status: number, body: unknown): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as Response;
+}
+
+describe('BibliographyAdapter', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns null for findById before load', () => {
+    const a = new BibliographyAdapter('iso', {
+      basePath: '/',
+      fetcher: async () => makeResponse(200, { bibliography: [] }),
+    });
+    expect(a.findById('ref-1')).toBeNull();
+    expect(a.all()).toEqual([]);
+  });
+
+  it('loads bibliography once and deduplicates subsequent calls', async () => {
+    let calls = 0;
+    const fetcher = vi.fn(async () => {
+      calls++;
+      return makeResponse(200, {
+        bibliography: [
+          { id: 'ref-1', title: 'ISO Standard', type: 'misc' },
+        ],
+      });
+    });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    await a.load();
+    expect(calls).toBe(1);
+    expect(a.findById('ref-1')?.id).toBe('ref-1');
+  });
+
+  it('treats 404 as missing bibliography — no throw, findById returns null', async () => {
+    const fetcher = vi.fn(async () => makeResponse(404, {}));
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await expect(a.load()).resolves.toBeUndefined();
+    expect(a.findById('ref-1')).toBeNull();
+  });
+
+  it('swallows network errors — loaded becomes true to prevent retry storms', async () => {
+    const fetcher = vi.fn(async () => { throw new Error('boom'); });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    expect(a.all()).toEqual([]);
+    await a.load();
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it('clear() resets state so the next load() refetches', async () => {
+    let calls = 0;
+    const fetcher = vi.fn(async () => {
+      calls++;
+      return makeResponse(200, { bibliography: [{ id: 'x' }] });
+    });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    a.clear();
+    expect(a.findById('x')).toBeNull();
+    await a.load();
+    expect(calls).toBe(2);
+  });
+
+  it('builds URLs from basePath + datasetId', async () => {
+    const fetcher = vi.fn(async () => makeResponse(200, { bibliography: [] }));
+    const a = new BibliographyAdapter('isotc204', { basePath: '/cb/', fetcher });
+    await a.load();
+    expect(fetcher).toHaveBeenCalledWith('/cb/data/isotc204/bibliography.json');
+  });
+});

package/src/__tests__/content-renderer-nvr-mentions.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { renderContent } from '../utils/content-renderer';
+import type { RenderOptions } from '../utils/content-renderer';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+
+type NvResolver = (kind: NonVerbalKind, id: string, display?: string) => string;
+
+function makeOpts(nonVerbalRefResolver?: NvResolver): RenderOptions {
+  return { nonVerbalRefResolver };
+}
+
+describe('content-renderer — non-verbal mentions', () => {
+  it('dispatches {{fig:id}} to nonVerbalRefResolver as figure', () => {
+    const calls: Array<[NonVerbalKind, string, string | undefined]> = [];
+    const resolver: NvResolver = (kind, id, display) => {
+      calls.push([kind, id, display]);
+      return `<a href="#figure-ds-${id}">${id}</a>`;
+    };
+    const out = renderContent('See {{fig:mixed-reflection}} in the diagram.', makeOpts(resolver));
+    expect(calls).toEqual([['figure', 'mixed-reflection', undefined]]);
+    expect(out).toContain('href="#figure-ds-mixed-reflection"');
+  });
+
+  it('dispatches {{table:id}} to nonVerbalRefResolver as table', () => {
+    const resolver: NvResolver = (kind) => `<a href="#${kind}-ds-x">x</a>`;
+    const out = renderContent('See {{table:wavelengths}}.', makeOpts(resolver));
+    expect(out).toContain('href="#table-ds-x"');
+  });
+
+  it('dispatches {{formula:id}} to nonVerbalRefResolver as formula', () => {
+    const resolver: NvResolver = (kind) => `<a href="#${kind}-ds-x">x</a>`;
+    const out = renderContent('Use {{formula:e-mc2}}.', makeOpts(resolver));
+    expect(out).toContain('href="#formula-ds-x"');
+  });
+
+  it('passes the display override as the third resolver arg', () => {
+    const calls: Array<[NonVerbalKind, string, string | undefined]> = [];
+    const resolver: NvResolver = (kind, id, display) => {
+      calls.push([kind, id, display]);
+      return '<span/>';
+    };
+    renderContent('{{fig:foo, Figure 3}}', makeOpts(resolver));
+    expect(calls[0]).toEqual(['figure', 'foo', 'Figure 3']);
+  });
+
+  it('falls back to a typed span when no resolver is configured', () => {
+    const out = renderContent('{{fig:foo}}', makeOpts(undefined));
+    expect(out).toContain('nv-ref nv-ref--figure');
+    expect(out).toContain('foo');
+  });
+
+  it('falls back to entityId as label when display override is absent and no resolver', () => {
+    const out = renderContent('{{table:wavelengths}}', makeOpts(undefined));
+    expect(out).toContain('wavelengths');
+    expect(out).toContain('nv-ref--table');
+  });
+});

package/src/__tests__/locale.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { pickLocaleText, pickLocaleMap } from '../utils/locale';
+
+describe('locale — fetchLocalizedString-backed resolution', () => {
+  it('returns the requested locale when present', () => {
+    const map = { eng: 'hello', fra: 'bonjour' };
+    expect(pickLocaleText(map, 'fra')).toBe('bonjour');
+  });
+
+  it('falls back through the chain when the requested locale is missing', () => {
+    const map = { eng: 'hello' };
+    expect(pickLocaleText(map, 'fra', ['eng'])).toBe('hello');
+  });
+
+  it('falls back to the first available locale when nothing in the chain matches', () => {
+    // Per the i18n-first invariant: never show nothing. If the user asks
+    // for a locale that is missing AND the chain misses too, return the
+    // first available locale's text rather than empty.
+    expect(pickLocaleText({ deu: 'hallo' }, 'fra', ['eng'])).toBe('hallo');
+  });
+
+  it('returns "" when the map is empty', () => {
+    expect(pickLocaleText({}, 'fra', ['eng'])).toBe('');
+  });
+
+  it('returns null from pickLocaleMap when the map is empty', () => {
+    expect(pickLocaleMap({}, 'fra', ['eng'])).toBeNull();
+  });
+
+  it('returns the resolved locale alongside the text', () => {
+    const r = pickLocaleMap({ eng: 'hi', fra: 'salut' }, 'fra', ['eng']);
+    expect(r).toEqual({ locale: 'fra', text: 'salut' });
+  });
+
+  it('returns null when map is undefined', () => {
+    expect(pickLocaleMap(undefined, 'eng')).toBeNull();
+    expect(pickLocaleText(undefined, 'eng')).toBe('');
+  });
+
+  it('passes the fallback chain explicitly (no internal fallback inside fetchLocalizedString)', () => {
+    // fetchLocalizedString is called with null fallback for each locale
+    // we try. The chain is owned by THIS module, not the leaf primitive.
+    const map = { eng: 'hello', fra: 'salut' };
+    expect(pickLocaleText(map, 'deu', ['fra', 'eng'])).toBe('salut');
+  });
+});

package/src/__tests__/model-bridge-entity-refs.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { conceptFromJson } from '../adapters/model-bridge';
+import type { Concept } from 'glossarist';
+
+interface ConceptWithEntityRefs {
+  readonly figures: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+  readonly tables: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+  readonly formulas: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+}
+
+function refsOf(c: Concept): ConceptWithEntityRefs {
+  return c as unknown as ConceptWithEntityRefs;
+}
+
+function conceptWithRefs(): Concept {
+  return conceptFromJson({
+    '@context': 'https://glossarist.org/ns/context.jsonld',
+    '@id': 'https://www.geolexica.org/isotc204/concept/3.1.1.1',
+    '@type': 'gl:Concept',
+    'gl:identifier': '3.1.1.1',
+    'gl:localizedConcept': {
+      eng: {
+        '@id': 'https://www.geolexica.org/isotc204/concept/3.1.1.1/eng',
+        '@type': 'gl:LocalizedConcept',
+        'gl:languageCode': 'eng',
+        'gl:entryStatus': 'valid',
+        'gl:designation': [{ '@type': 'gl:Expression', 'gl:term': 'entity' }],
+      },
+    },
+    'gl:figureRef': [
+      'mixed-reflection',
+      { '@id': '../figure/dispersion-prism' },
+      { '@id': '../figure/standard-wavelengths', 'gl:display': 'Figure 3' },
+    ],
+    'gl:tableRef': [{ '@id': '../table/wavelength-table' }],
+    'gl:formulaRef': ['e-mc2'],
+  });
+}
+
+describe('conceptFromJson — structural entity refs', () => {
+  it('extracts bare-string figure refs', () => {
+    const c = refsOf(conceptWithRefs());
+    const ids = c.figures.map(f => f.entityId);
+    expect(ids).toContain('mixed-reflection');
+  });
+
+  it('extracts @id-only figure refs by last path segment', () => {
+    const c = refsOf(conceptWithRefs());
+    const ids = c.figures.map(f => f.entityId);
+    expect(ids).toContain('dispersion-prism');
+  });
+
+  it('preserves gl:display as the reference display override', () => {
+    const c = refsOf(conceptWithRefs());
+    const withDisplay = c.figures.find(f => f.entityId === 'standard-wavelengths');
+    expect(withDisplay?.display).toBe('Figure 3');
+  });
+
+  it('extracts table refs from gl:tableRef', () => {
+    const c = refsOf(conceptWithRefs());
+    expect(c.tables.map(t => t.entityId)).toContain('wavelength-table');
+  });
+
+  it('extracts formula refs from gl:formulaRef', () => {
+    const c = refsOf(conceptWithRefs());
+    expect(c.formulas.map(f => f.entityId)).toContain('e-mc2');
+  });
+
+  it('returns empty arrays when no ref fields are present', () => {
+    const c = refsOf(conceptFromJson({
+      '@context': 'https://glossarist.org/ns/context.jsonld',
+      '@id': 'https://example.org/x/concept/1',
+      '@type': 'gl:Concept',
+      'gl:identifier': '1',
+      'gl:localizedConcept': {
+        eng: {
+          '@type': 'gl:LocalizedConcept',
+          'gl:languageCode': 'eng',
+          'gl:entryStatus': 'valid',
+          'gl:designation': [{ '@type': 'gl:Expression', 'gl:term': 'x' }],
+        },
+      },
+    }));
+    expect(c.figures).toEqual([]);
+    expect(c.tables).toEqual([]);
+    expect(c.formulas).toEqual([]);
+  });
+
+  it('skips malformed entries (empty string, null, missing @id)', () => {
+    const c = refsOf(conceptFromJson({
+      '@context': 'https://glossarist.org/ns/context.jsonld',
+      '@id': 'https://example.org/x/concept/1',
+      '@type': 'gl:Concept',
+      'gl:identifier': '1',
+      'gl:localizedConcept': {
+        eng: {
+          '@type': 'gl:LocalizedConcept',
+          'gl:languageCode': 'eng',
+          'gl:entryStatus': 'valid',
+          'gl:designation': [{ '@type': 'gl:Expression', 'gl:term': 'x' }],
+        },
+      },
+      'gl:figureRef': [
+        '',
+        null,
+        {},
+        { '@id': '' },
+        { ref: '' },
+        '   ',
+      ],
+    }));
+    expect(c.figures).toEqual([]);
+  });
+});

package/src/__tests__/non-verbal-anchor.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import {
+  anchorId,
+  ANCHOR_KIND_SELECTORS,
+} from '../utils/non-verbal-anchor';
+
+describe('non-verbal-anchor', () => {
+  describe('anchorId', () => {
+    it('joins kind + datasetId + entityId with hyphens', () => {
+      expect(anchorId('figure', 'iala-2023', 'mixed-reflection'))
+        .toBe('figure-iala-2023-mixed-reflection');
+    });
+
+    it('uses the kind name as prefix (not an alias)', () => {
+      expect(anchorId('table', 'iso', 'standard-wavelengths'))
+        .toBe('table-iso-standard-wavelengths');
+      expect(anchorId('formula', 'iso', 'e-mc2'))
+        .toBe('formula-iso-e-mc2');
+    });
+  });
+
+  describe('ANCHOR_KIND_SELECTORS', () => {
+    it('contains one selector per kind', () => {
+      expect(ANCHOR_KIND_SELECTORS).toContain('a[href^="#figure-"]');
+      expect(ANCHOR_KIND_SELECTORS).toContain('a[href^="#table-"]');
+      expect(ANCHOR_KIND_SELECTORS).toContain('a[href^="#formula-"]');
+    });
+
+    it('has exactly three selectors (one per kind)', () => {
+      expect(ANCHOR_KIND_SELECTORS.length).toBe(3);
+    });
+  });
+});