@glossarist/concept-browser 0.7.104 → 0.7.106

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.104",
+  "version": "0.7.106",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "sync:model": "node scripts/sync-concept-model.mjs",
     "build:full": "npm run generate-ontology && npm run fetch-datasets && npm run generate-data && node scripts/build-edges.js && npm run build",
     "build:site": "concept-browser --site build",
+    "smoke": "node scripts/smoke.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "mutation:test": "stryker run stryker.config.mjs",
@@ -58,6 +59,7 @@
     "fast-check": "^4.8.0",
     "happy-dom": "^20.9.0",
     "n3": "^1.26.0",
+    "playwright": "^1.62.1",
     "rdf-validate-shacl": "^0.4.5",
     "typescript": "~5.7.3",
     "vitest": "^4.1.5",

package/scripts/generate-data.mjs

@@ -1344,6 +1344,9 @@ async function processDataset(dir, register, opts) {
   await writeDatasetRdf(register, manifest, concepts, refMaps, opts);
 
   // Copy bibliography.yaml → bibliography.json
+  // ALWAYS emit bibliography.json — empty stub `{ bibliography: [] }` when no
+  // source exists — so the concept detail page's unconditional fetch doesn't
+  // 404 (issue #174). The build never emits a request it can't satisfy.
   const bibPath = path.join(sourceRoot, 'bibliography.yaml');
   if (fs.existsSync(bibPath)) {
     const rawBib = readYaml(bibPath);
@@ -1351,6 +1354,9 @@ async function processDataset(dir, register, opts) {
     writeJson(path.join(DATA, register, 'bibliography.json'), bibData);
     const bibCount = bibData.bibliography.length;
     console.log(`  Copied bibliography (${bibCount} entries)`);
+  } else {
+    writeJson(path.join(DATA, register, 'bibliography.json'), { bibliography: [] });
+    console.log(`  Emitted empty bibliography.json (no source bibliography.yaml)`);
   }
 
   // Copy images/ with magic-byte validation + manifest emission.

package/scripts/smoke.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Post-build smoke test — deploy gate that catches runtime errors the
+ * type-checker and unit tests can't see.
+ *
+ * WHAT THIS CATCHES
+ *   - Hydration TypeError (#171: `r.conceptGenericRelations.length`).
+ *   - Dynamic-import resolution failures (the tsx devDep bug).
+ *   - Failed resource requests the build itself caused (#174:
+ *     bibliography.json / /learn / favicon 404s).
+ *   - Config-not-honored regressions (#162/#166: branding.fonts).
+ *
+ * WHAT THIS DOES NOT DO
+ *   - Functional UI testing (use Vitest + @vue/test-utils for that).
+ *   - Cross-browser coverage (Chromium only — WebKit/Safari differences
+ *     are caught by manual pre-release validation).
+ *
+ * USAGE
+ *   npm run smoke            # assumes dist/ already built
+ *   npm run build:full       # build:full pipeline now includes smoke
+ *
+ * The test serves dist/ on a random localhost port, loads each URL in a
+ * headless Chromium, and asserts zero `pageerror` events plus zero 404s
+ * on same-origin resources. Any failure exits non-zero so CI/deploy
+ * gates fail loudly.
+ */
+import { chromium } from 'playwright';
+import { createServer } from 'http';
+import { statSync, createReadStream } from 'fs';
+import { extname, join, normalize, resolve as pathResolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const DIST = pathResolve(__dirname, '..', 'dist');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg':  'image/svg+xml',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.ico':  'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2':'font/woff2',
+  '.ttf':  'font/ttf',
+  '.map':  'application/json; charset=utf-8',
+  '.xml':  'application/xml; charset=utf-8',
+  '.txt':  'text/plain; charset=utf-8',
+  '.webmanifest': 'application/manifest+json; charset=utf-8',
+};
+
+function serveDist(root) {
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      try {
+        const urlPath = decodeURIComponent((req.url ?? '/').split('?')[0]);
+        let filePath = join(root, urlPath);
+        // SPA fallback: if no extension and the file doesn't exist as a
+        // directory, try .html, then fall back to 200.html / index.html.
+        if (!extname(filePath)) {
+          if (statSafe(filePath)?.isFile()) {
+            return sendFile(res, filePath);
+          }
+          const candidates = [
+            filePath + '.html',
+            join(filePath, 'index.html'),
+            join(root, '200.html'),
+            join(root, 'index.html'),
+          ];
+          for (const c of candidates) {
+            if (statSafe(c)?.isFile()) {
+              return sendFile(res, c);
+            }
+          }
+          res.writeHead(404);
+          return res.end('Not found');
+        }
+        if (statSafe(filePath)?.isFile()) {
+          return sendFile(res, filePath);
+        }
+        res.writeHead(404);
+        return res.end('Not found');
+      } catch (e) {
+        res.writeHead(500);
+        res.end(String(e ?? 'server error'));
+      }
+    });
+    // Use port 0 to let the OS pick a free port; retrieve it after listen.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolve({ server, origin: `http://127.0.0.1:${port}` });
+    });
+  });
+}
+
+function statSafe(p) {
+  try { return statSync(p); } catch { return null; }
+}
+
+function sendFile(res, filePath) {
+  const safe = normalize(filePath);
+  const ct = MIME[extname(safe)] ?? 'application/octet-stream';
+  res.writeHead(200, { 'Content-Type': ct });
+  createReadStream(safe).pipe(res);
+}
+
+/**
+ * Pages to probe. Use relative paths from the served origin. The smoke
+ * test runs AFTER the build, so anything present in dist/ is fair game.
+ * The home page always exists; the rest are best-effort (404 → skip).
+ */
+const PAGE_PATHS = [
+  '/',
+  '/learn/',
+  '/learn/relationships/',
+  '/learn/designations/',
+  '/learn/statuses/',
+];
+
+/**
+ * Consumer-provided files that concept-browser's build does NOT emit.
+ * The smoke test runs against concept-browser's own dist (no datasets
+ * configured), so these will 404. That's not a regression — it's a
+ * "consumer hasn't provided data" condition. Listed here so we can
+ * filter them out of the failure signal.
+ */
+const CONSUMER_DATA_FILES = [
+  '/datasets.json',
+  '/site-config.json',
+  '/data/cross-ref-index.json',
+];
+
+function isConsumerDataFile(url) {
+  try {
+    const u = new URL(url);
+    return CONSUMER_DATA_FILES.some(f => u.pathname === f || u.pathname.startsWith('/data/'));
+  } catch {
+    return false;
+  }
+}
+
+async function probePage(browser, origin, path) {
+  const url = new URL(path, origin).toString();
+  const page = await browser.newPage();
+  const errors = [];
+  const failedRequests = [];
+
+  page.on('pageerror', (e) => {
+    errors.push({ kind: 'pageerror', message: e.message, stack: e.stack ?? '' });
+  });
+  page.on('console', (msg) => {
+    if (msg.type() !== 'error') return;
+    const text = msg.text();
+    // Browser consoles emit a generic "Failed to load resource: ... 404"
+    // message for every network 404 — the URL is NOT in the text, so we
+    // can't filter by file here. We track real 404s via the response
+    // event below and discard the generic console message to avoid
+    // double-counting noise.
+    if (/Failed to load resource/i.test(text)) return;
+    // Cross-origin font CDN warnings are out of our control.
+    if (/fonts\.g(oogle|static)\.com/.test(text)) return;
+    errors.push({ kind: 'console.error', message: text });
+  });
+  page.on('requestfailed', (req) => {
+    const u = req.url();
+    if (u.startsWith(origin) && !isConsumerDataFile(u)) {
+      failedRequests.push({ url: u, failure: req.failure()?.errorText ?? 'failed' });
+    }
+  });
+  page.on('response', (resp) => {
+    const u = resp.url();
+    if (u.startsWith(origin) && resp.status() >= 400 && !isConsumerDataFile(u)) {
+      failedRequests.push({ url: u, status: resp.status() });
+    }
+  });
+
+  try {
+    const resp = await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
+    if (resp && resp.status() >= 400) {
+      // 404 on a non-home page = the build didn't emit it. Treat as
+      // skip, not fail (the home page is the load-bearing probe).
+      return { path, url, status: resp.status(), bodyLen: 0, errors, failedRequests, skipped: path !== '/' };
+    }
+    // Wait a beat for any deferred hydration effect to fire.
+    await page.waitForTimeout(500);
+    const bodyLen = await page.evaluate(() => document.body?.innerText?.length ?? 0);
+    return { path, url, status: resp?.status() ?? 0, bodyLen, errors, failedRequests, skipped: false };
+  } catch (e) {
+    errors.push({ kind: 'navigation', message: String(e) });
+    return { path, url, status: 0, bodyLen: 0, errors, failedRequests, skipped: false };
+  } finally {
+    await page.close();
+  }
+}
+
+function formatFindings(results) {
+  const lines = [];
+  for (const r of results) {
+    if (r.skipped) {
+      lines.push(`\n  ${r.path}  (HTTP ${r.status} — skipped, not in this build)`);
+      continue;
+    }
+    if (r.errors.length === 0 && r.failedRequests.length === 0 && r.bodyLen > 0) continue;
+    lines.push(`\n  ${r.path}  (HTTP ${r.status}, body ${r.bodyLen} chars)`);
+    for (const e of r.errors) {
+      lines.push(`    [${e.kind}] ${e.message}`);
+    }
+    for (const f of r.failedRequests) {
+      lines.push(`    [request] ${f.status ?? f.failure}  ${f.url}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function ensureDist() {
+  if (!statSafe(DIST)?.isDirectory()) {
+    console.error(`smoke: dist/ not found at ${DIST}`);
+    console.error(`       run \`npm run build\` first, or use \`npm run build:full\`.`);
+    process.exit(2);
+  }
+  if (!statSafe(join(DIST, 'index.html'))?.isFile()) {
+    console.error(`smoke: dist/index.html missing — build did not complete.`);
+    process.exit(2);
+  }
+}
+
+async function main() {
+  await ensureDist();
+  const { server, origin } = await serveDist(DIST);
+
+  let exitCode = 0;
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const results = [];
+    for (const path of PAGE_PATHS) {
+      // Skip paths the build didn't emit (e.g. /learn/* if page-types
+      // config doesn't synthesize them). 404 on the navigation itself
+      // is recorded; the probe still runs to catch prefetch 404s.
+      const r = await probePage(browser, origin, path);
+      results.push(r);
+    }
+
+    const anyFail = results.some(r =>
+      !r.skipped && (r.errors.length > 0 || r.failedRequests.length > 0 || r.bodyLen === 0)
+    );
+    const findings = formatFindings(results);
+
+    if (anyFail) {
+      exitCode = 1;
+      console.error(`\n  FAIL  smoke test found problems:${findings}\n`);
+    } else {
+      const skipped = results.filter(r => r.skipped).length;
+      console.log(`\n  OK    smoke test passed (${results.length - skipped} pages, ${skipped} skipped, 0 errors).`);
+    }
+  } finally {
+    await browser.close();
+    server.close();
+  }
+  process.exit(exitCode);
+}
+
+main().catch((e) => {
+  console.error('smoke: fatal error', e);
+  process.exit(1);
+});

package/src/__tests__/components/rake-bundles.test.ts

@@ -315,4 +315,24 @@ describe('drawRakeBundles — rake contract', () => {
     expect(svg.querySelectorAll('circle.rake-junction').length).toBe(2);
     expect(svg.querySelectorAll('path').length).toBe(2);
   });
+
+  it('renders ellipsis "…" text when completeness is partial', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation({ completeness: 'partial' })],
+    });
+    const ellipsis = svg.querySelectorAll('text.rake-ellipsis');
+    expect(ellipsis.length).toBe(1);
+    expect(ellipsis[0].textContent).toBe('…');
+  });
+
+  it('does NOT render ellipsis when completeness is complete', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation({ completeness: 'complete' })],
+    });
+    expect(svg.querySelectorAll('text.rake-ellipsis').length).toBe(0);
+  });
 });

package/src/__tests__/composables/use-concept-edges-defensive.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { computed, ref } from 'vue';
+import type { Router } from 'vue-router';
+import { useConceptEdges } from '../../composables/use-concept-edges';
+import { useVocabularyStore } from '../../stores/vocabulary';
+import type { Manifest, GraphEdge } from '../../adapters/types';
+import { makeManifest, setupPinia } from '../test-helpers';
+import { getFactory, resetFactory } from '../../adapters/factory';
+
+/**
+ * Regression test for issue #171 — `TypeError: r.conceptGenericRelations.length
+ * at hydration`.
+ *
+ * Bug (2026-08-01): on the live `glossarist/cie-eilv` deployment, every concept
+ * page threw `TypeError: undefined is not an object (evaluating
+ * 'r.conceptGenericRelations.length')` at hydration time. The concept detail
+ * view failed to render. No unit test caught this because every existing test
+ * passes a well-formed Concept instance.
+ *
+ * Root cause: any code path that made the `conceptGenericRelations` computed
+ * throw (or made the destructured value undefined at hydration) crashed the
+ * template's `v-if="conceptGenericRelations.length"` access. The fix has two
+ * arms:
+ *
+ *   1. The composable wraps its computed getters in try/catch so a malformed
+ *      concept never propagates an exception into the render path.
+ *   2. The template uses `v-if="conceptGenericRelations?.length"` so an
+ *      undefined destructured value is treated as "no relations" instead of
+ *      throwing.
+ *
+ * This spec exercises the composable's defensive layer directly: malformed
+ * concepts, partially-formed relations, and the null/undefined concept value
+ * must all produce `[]` — never throw, never return `undefined`.
+ */
+describe('useConceptEdges — defensive projection (regression for #171)', () => {
+  const URN_SOURCE = 'urn:glossarist:fixtures';
+  const manifest: Manifest = makeManifest({
+    id: 'fixtures',
+    datasetUri: URN_SOURCE,
+    uriBase: 'https://glossarist.org',
+  });
+  const noEdges: GraphEdge[] = [];
+  const noopRouter = { push() {} } as unknown as Router;
+
+  let store: ReturnType<typeof useVocabularyStore>;
+
+  beforeEach(() => {
+    setupPinia();
+    resetFactory();
+    store = useVocabularyStore();
+    store.manifests.set(manifest.id, manifest);
+
+    const factory = getFactory();
+    factory.resolveRelatedRef = vi.fn((ref: { source: string | null; id: string | null } | null) =>
+      ref?.source === URN_SOURCE && ref.id
+        ? { registerId: manifest.id, conceptId: ref.id }
+        : null,
+    );
+  });
+
+  /**
+   * The core regression: any malformed concept input must NOT propagate an
+   * exception through the composable. The computed must always resolve to an
+   * array (possibly empty). This is what the template's `?.length` defensive
+   * access relies on — and what the prior crash violated.
+   */
+  it('never throws when concept.relations is malformed (issue #171)', () => {
+    const malformedConcepts = [
+      /* relations is undefined */
+      { id: 'a', localization: () => null, languages: [], relatedConcepts: [] },
+      /* relations is null */
+      { id: 'b', relations: null, localization: () => null, languages: [], relatedConcepts: [] },
+      /* relations contains a non-hyperedge object */
+      { id: 'c', relations: [{ not: 'a relation' }], localization: () => null, languages: [], relatedConcepts: [] },
+      /* relations contains a hyperedge whose comprehensive is missing */
+      { id: 'd', relations: [{ members: [] }], localization: () => null, languages: [], relatedConcepts: [] },
+      /* relations contains a hyperedge with null members */
+      { id: 'e', relations: [{ comprehensive: { source: URN_SOURCE, id: '1.1' }, members: null }], localization: () => null, languages: [], relatedConcepts: [] },
+      /* the concept itself is an empty object */
+      {} as any,
+    ];
+
+    for (const concept of malformedConcepts) {
+      const { conceptPartitiveRelations, conceptGenericRelations, conceptRelated } = useConceptEdges(
+        computed(() => concept),
+        computed(() => 'fixtures'),
+        computed(() => manifest),
+        computed(() => noEdges),
+        noopRouter,
+      );
+      /* Each computed must resolve without throwing. */
+      expect(() => conceptPartitiveRelations.value).not.toThrow();
+      expect(() => conceptGenericRelations.value).not.toThrow();
+      expect(() => conceptRelated.value).not.toThrow();
+      /* And must produce an array (never undefined). */
+      expect(Array.isArray(conceptPartitiveRelations.value)).toBe(true);
+      expect(Array.isArray(conceptGenericRelations.value)).toBe(true);
+      expect(Array.isArray(conceptRelated.value)).toBe(true);
+    }
+  });
+
+  it('returns a complete return shape — every key always present', () => {
+    /* The original issue text hypothesized an early-return path that omitted
+       `conceptGenericRelations`. Pin the contract: every documented key is
+       present in the return object, regardless of input. */
+    const result = useConceptEdges(
+      ref(null) as any,
+      computed(() => 'fixtures'),
+      computed(() => manifest),
+      computed(() => noEdges),
+      noopRouter,
+    );
+    const requiredKeys = [
+      'conceptUriValue',
+      'outgoingEdges',
+      'incomingEdges',
+      'edgeDisplayCache',
+      'getEdgeDisplay',
+      'designationFor',
+      'edgeBadgeColor',
+      'inverseEdgeType',
+      'conceptRelated',
+      'conceptPartitiveRelations',
+      'conceptGenericRelations',
+      'resolveRelatedRef',
+      'getResolvedRef',
+      'relatedLabel',
+      'navigateEdge',
+      'navigateRelated',
+    ] as const;
+    for (const key of requiredKeys) {
+      expect(result, `missing key: ${key}`).toHaveProperty(key);
+      expect(result[key as keyof typeof result], `undefined value for key: ${key}`).toBeDefined();
+    }
+  });
+
+  it('returns [] (not undefined) when concept.relations entries throw on instanceof check', () => {
+    /* Simulate the failure mode where a bundled class import ends up undefined
+       at hydration — `r instanceof undefined` throws. The composable's try/catch
+       must swallow it and yield []. */
+    const Bomb = function () {} as any;
+    Object.defineProperty(Bomb.prototype, Symbol.hasInstance, {
+      value: () => { throw new Error('simulated instanceof failure'); },
+    });
+    const concept = {
+      id: 'bomb',
+      relations: [new Bomb()],
+      localization: () => null,
+      languages: [],
+      relatedConcepts: [],
+    };
+    const { conceptGenericRelations, conceptPartitiveRelations } = useConceptEdges(
+      computed(() => concept),
+      computed(() => 'fixtures'),
+      computed(() => manifest),
+      computed(() => noEdges),
+      noopRouter,
+    );
+    expect(() => conceptGenericRelations.value).not.toThrow();
+    expect(() => conceptPartitiveRelations.value).not.toThrow();
+    expect(conceptGenericRelations.value).toEqual([]);
+    expect(conceptPartitiveRelations.value).toEqual([]);
+  });
+});