@glossarist/concept-browser 0.7.51 → 0.7.53

package/cli/index.mjs

@@ -9,6 +9,8 @@
  *   edges      Build cross-reference edges from generated concept data
  *   build      Full pipeline: fetch + generate + edges + vite build
  *   site       Same as build (alias)
+ *   normalize  NFC-normalize YAML files in .datasets/ (use --check for CI gate)
+ *   doctor     Diagnose the local environment (deps, datasets, shapes, context)
  *
  * Options:
  *   --site <id>  Site config to use (looks for site-config.yml in CWD)
@@ -61,9 +63,12 @@ Commands:
   edges      Build cross-reference edges from generated concepts
   build      Full pipeline (fetch + generate + edges + vite build)
   site       Same as build
+  normalize  NFC-normalize YAML files in .datasets/
+  doctor     Diagnose the local environment (deps, datasets, shapes, context)
 
 Options:
   --site <id>  Site config ID (looks for site-config.yml in CWD)
+  --check      (normalize only) Non-mutating; exit 1 if any file is not NFC
 
 Environment:
   SITE_CONFIG          Site config file path (highest priority)
@@ -187,6 +192,33 @@ Environment:
 
   const runner = commands[cmd];
   if (!runner) {
+    if (cmd === 'normalize') {
+      const { normalizeYaml } = await import('../scripts/normalize-yaml.mjs');
+      const check = process.argv.includes('--check');
+      const paths = process.argv.slice(2).filter(a => !a.startsWith('-') && a !== 'normalize');
+      const { checked, nonNfc, fixed } = normalizeYaml({ check, paths });
+      if (check) {
+        if (nonNfc === 0) {
+          console.log(`NFC OK: ${checked} file(s) checked, all normalized`);
+          return;
+        }
+        console.error(`NFC check failed: ${nonNfc} of ${checked} file(s) are not NFC-normalized\n`);
+        for (const f of fixed) console.error(`  ${f}`);
+        process.exit(1);
+      }
+      if (nonNfc === 0) {
+        console.log(`NFC OK: ${checked} file(s) checked, all already normalized`);
+      } else {
+        console.log(`Normalized ${nonNfc} of ${checked} file(s)`);
+        for (const f of fixed) console.log(`  ${f}`);
+      }
+      return;
+    }
+    if (cmd === 'doctor') {
+      const { main: doctorMain } = await import('../scripts/doctor.mjs');
+      await doctorMain();
+      return;
+    }
     console.error(`Unknown command: ${cmd}`);
     console.error('Run `concept-browser help` for usage.');
     process.exit(1);

package/env.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="vite/client" />
 
+declare const __CONCEPT_BROWSER_VERSION__: string;
+
 declare module '*.json' {
   const value: any;
   export default value;
@@ -10,3 +12,16 @@ declare module '*.vue' {
   const component: DefineComponent<{}, {}, any>
   export default component
 }
+
+declare module '@rdfjs/dataset' {
+  export function dataset(): any;
+  const _default: { dataset: typeof dataset };
+  export default _default;
+}
+
+declare module 'rdf-validate-shacl' {
+  export default class Validator {
+    constructor(shapes: any, options?: { factory?: any });
+    validate(data: any): { conforms: boolean; results: any[] };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.51",
+  "version": "0.7.53",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -17,10 +17,13 @@
     "fetch-datasets": "node scripts/fetch-datasets.mjs",
     "generate-data": "node scripts/generate-data.mjs",
     "generate-ontology": "node scripts/generate-ontology-data.mjs && node scripts/generate-ontology-schema.mjs",
+    "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",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "mutation:test": "stryker run stryker.config.mjs",
+    "validate:shacl": "node scripts/validate-shacl.mjs"
   },
   "dependencies": {
     "@plurimath/plurimath": "^0.2.2",
@@ -40,9 +43,16 @@
     "vue-router": "^4.5.1"
   },
   "devDependencies": {
+    "@rdfjs/dataset": "^2.0.2",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/d3": "^7.4.3",
+    "@types/n3": "^1.26.1",
     "@vue/test-utils": "^2.4.8",
+    "fast-check": "^4.8.0",
     "happy-dom": "^20.9.0",
+    "n3": "^1.26.0",
+    "rdf-validate-shacl": "^0.4.5",
     "typescript": "~5.7.3",
     "vitest": "^4.1.5",
     "vue-tsc": "^2.2.8"

package/scripts/__tests__/doctor.test.mjs

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { runDoctor, formatResults, CHECKS, NODE_MIN_MAJOR } from '../doctor.mjs';
+
+function makeTmpProject() {
+  const dir = mkdtempSync(join(tmpdir(), 'doctor-'));
+  return dir;
+}
+
+function writeDatasetsYml(root, ids) {
+  const entries = ids.map((id) => `  - id: ${id}\n    title: "${id}"\n    sourceRepo: "https://example.com/${id}"`).join('\n');
+  writeFileSync(join(root, 'datasets.yml'), `datasets:\n${entries}\n`);
+}
+
+function stubGenerated(root, ids) {
+  for (const id of ids) {
+    mkdirSync(join(root, 'public', 'data', id), { recursive: true });
+    writeFileSync(join(root, 'public', 'data', id, 'manifest.json'), '{}');
+  }
+  writeFileSync(join(root, 'public', 'datasets.json'), JSON.stringify(ids.map((id) => ({ id }))));
+}
+
+function stubFetched(root, ids) {
+  for (const id of ids) {
+    mkdirSync(join(root, '.datasets', id, 'concepts'), { recursive: true });
+  }
+}
+
+describe('doctor — unit checks', () => {
+  it('exposes NODE_MIN_MAJOR as a positive integer', () => {
+    expect(NODE_MIN_MAJOR).toBeGreaterThanOrEqual(18);
+    expect(Number.isInteger(NODE_MIN_MAJOR)).toBe(true);
+  });
+
+  it('registers exactly eight independent checks', () => {
+    expect(CHECKS).toHaveLength(8);
+    const ids = CHECKS.map((c) => c.name ?? c.toString());
+    expect(new Set(ids).size).toBe(8);
+  });
+});
+
+describe('doctor — runDoctor on synthetic projects', () => {
+  let root;
+
+  beforeEach(() => {
+    root = makeTmpProject();
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('fails on missing datasets.yml', async () => {
+    const { results } = await runDoctor(root);
+    const ymlCheck = results.find((r) => r.id === 'datasets-yml');
+    expect(ymlCheck.status).toBe('warn');
+  });
+
+  it('fails on malformed datasets.yml', async () => {
+    writeFileSync(join(root, 'datasets.yml'), 'datasets: [this is broken');
+    const { results, exitCode } = await runDoctor(root);
+    const ymlCheck = results.find((r) => r.id === 'datasets-yml');
+    expect(ymlCheck.status).toBe('fail');
+    expect(exitCode).toBe(1);
+  });
+
+  it('passes datasets-yml when the file parses and lists entries', async () => {
+    writeDatasetsYml(root, ['foo', 'bar']);
+    const { results } = await runDoctor(root);
+    const ymlCheck = results.find((r) => r.id === 'datasets-yml');
+    expect(ymlCheck.status).toBe('pass');
+    expect(ymlCheck.label).toContain('2 dataset(s)');
+  });
+
+  it('fails when registered datasets are not fetched', async () => {
+    writeDatasetsYml(root, ['foo']);
+    const { results, exitCode } = await runDoctor(root);
+    const fetched = results.find((r) => r.id === 'datasets-fetched');
+    expect(fetched.status).toBe('fail');
+    expect(fetched.detail).toContain('foo');
+    expect(exitCode).toBe(1);
+  });
+
+  it('passes when registered datasets exist under .datasets/{id}/concepts', async () => {
+    writeDatasetsYml(root, ['foo']);
+    stubFetched(root, ['foo']);
+    const { results } = await runDoctor(root);
+    const fetched = results.find((r) => r.id === 'datasets-fetched');
+    expect(fetched.status).toBe('pass');
+  });
+
+  it('fails when public/data manifest is missing', async () => {
+    writeDatasetsYml(root, ['foo']);
+    stubFetched(root, ['foo']);
+    const { results, exitCode } = await runDoctor(root);
+    const gen = results.find((r) => r.id === 'datasets-generated');
+    expect(gen.status).toBe('fail');
+    expect(gen.detail).toContain('foo');
+    expect(exitCode).toBe(1);
+  });
+
+  it('passes when manifests are present', async () => {
+    writeDatasetsYml(root, ['foo']);
+    stubFetched(root, ['foo']);
+    stubGenerated(root, ['foo']);
+    const { results } = await runDoctor(root);
+    const gen = results.find((r) => r.id === 'datasets-generated');
+    expect(gen.status).toBe('pass');
+  });
+
+  it('fails when public/datasets.json is missing', async () => {
+    writeDatasetsYml(root, ['foo']);
+    stubFetched(root, ['foo']);
+    mkdirSync(join(root, 'public', 'data', 'foo'), { recursive: true });
+    writeFileSync(join(root, 'public', 'data', 'foo', 'manifest.json'), '{}');
+    const { results, exitCode } = await runDoctor(root);
+    const j = results.find((r) => r.id === 'public-datasets-json');
+    expect(j.status).toBe('fail');
+    expect(exitCode).toBe(1);
+  });
+
+  it('does not crash when datasets.yml lists zero datasets', async () => {
+    writeFileSync(join(root, 'datasets.yml'), 'datasets: []\n');
+    const { results } = await runDoctor(root);
+    const ymlCheck = results.find((r) => r.id === 'datasets-yml');
+    expect(ymlCheck.status).toBe('warn');
+  });
+});
+
+describe('doctor — formatting', () => {
+  it('renders a pass/fail/warn glyph per result and a summary line', () => {
+    const out = formatResults([
+      { id: 'a', label: 'A is good', status: 'pass' },
+      { id: 'b', label: 'B is broken', status: 'fail', detail: 'because', hint: 'fix it' },
+      { id: 'c', label: 'C is suspect', status: 'warn' },
+    ]);
+    expect(out).toContain('✓ A is good');
+    expect(out).toContain('✗ B is broken');
+    expect(out).toContain('    because');
+    expect(out).toContain('→ fix it');
+    expect(out).toContain('! C is suspect');
+    expect(out).toMatch(/1 passed, 1 failed, 1 warnings \(3 total\)/);
+  });
+});

package/scripts/doctor.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// `concept-browser doctor` — environment diagnostic.
+//
+// Runs a series of independent checks (Node version, dependencies,
+// datasets registered / fetched / generated, SHACL shapes, JSON-LD
+// context) and prints a pass/fail summary. Exits non-zero if any
+// check fails.
+//
+// See docs/adr/0005-shacl-validation-gate.md and
+// TODO.streamline/15-tooling-and-developer-experience.md §O1.
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+export const NODE_MIN_MAJOR = 18;
+
+/**
+ * @typedef {'pass'|'fail'|'warn'} CheckStatus
+ * @typedef {{ id: string, label: string, status: CheckStatus, detail?: string, hint?: string }} CheckResult
+ * @typedef {{ cwd: string, pkgRoot: string, datasetsYml?: any, datasetsYmlError?: string }} DoctorContext
+ */
+
+/**
+ * Wrap a check so an unexpected throw becomes a fail result, and
+ * preserve the check's `id` as the wrapper's `name` so callers can
+ * reason about the registry without anonymous arrows.
+ *
+ * @param {string} id
+ * @param {() => (Promise<CheckResult> | CheckResult)} check
+ * @returns {(ctx: DoctorContext) => Promise<CheckResult>}
+ */
+function safe(id, check) {
+  const wrapped = async (ctx) => {
+    try {
+      return await check(ctx);
+    } catch (err) {
+      return {
+        id: 'unexpected',
+        label: 'Unexpected error',
+        status: 'fail',
+        detail: err?.message ?? String(err),
+      };
+    }
+  };
+  Object.defineProperty(wrapped, 'name', { value: id });
+  return wrapped;
+}
+
+function nodeVersionCheck() {
+  const major = Number.parseInt(process.versions.node.split('.')[0], 10);
+  return {
+    id: 'node-version',
+    label: `Node.js v${process.versions.node}`,
+    status: major >= NODE_MIN_MAJOR ? 'pass' : 'fail',
+    detail: major < NODE_MIN_MAJOR ? `requires >= v${NODE_MIN_MAJOR}` : undefined,
+    hint: major < NODE_MIN_MAJOR ? 'upgrade via nvm or your package manager' : undefined,
+  };
+}
+
+function packageDepsCheck(ctx) {
+  const nm = resolve(ctx.pkgRoot, 'node_modules');
+  if (!existsSync(nm)) {
+    return {
+      id: 'package-deps',
+      label: 'Dependencies installed',
+      status: 'fail',
+      detail: 'node_modules missing',
+      hint: 'run `npm install`',
+    };
+  }
+  const required = ['vue', 'vue-router', 'pinia', 'vite', 'n3', 'glossarist', '@rdfjs/dataset'];
+  const missing = required.filter((p) => !existsSync(join(nm, p)));
+  if (missing.length) {
+    return {
+      id: 'package-deps',
+      label: 'Dependencies installed',
+      status: 'fail',
+      detail: `missing: ${missing.join(', ')}`,
+      hint: 'run `npm install`',
+    };
+  }
+  return { id: 'package-deps', label: 'Dependencies installed', status: 'pass' };
+}
+
+function datasetsYmlCheck(ctx) {
+  const path = resolve(ctx.cwd, 'datasets.yml');
+  if (!existsSync(path)) {
+    return {
+      id: 'datasets-yml',
+      label: 'datasets.yml present',
+      status: 'warn',
+      detail: 'file not found at project root',
+      hint: 'datasets.yml registers every dataset the browser serves',
+    };
+  }
+  if (ctx.datasetsYmlError) {
+    return {
+      id: 'datasets-yml',
+      label: 'datasets.yml parses',
+      status: 'fail',
+      detail: ctx.datasetsYmlError,
+      hint: 'fix the YAML syntax error',
+    };
+  }
+  const datasets = ctx.datasetsYml?.datasets;
+  if (!Array.isArray(datasets) || datasets.length === 0) {
+    return {
+      id: 'datasets-yml',
+      label: 'datasets.yml lists datasets',
+      status: 'warn',
+      detail: '`datasets` key is empty or missing',
+      hint: 'add at least one dataset entry; see docs/adding-a-dataset.md',
+    };
+  }
+  return {
+    id: 'datasets-yml',
+    label: `datasets.yml lists ${datasets.length} dataset(s)`,
+    status: 'pass',
+  };
+}
+
+function datasetsFetchedCheck(ctx) {
+  const datasets = ctx.datasetsYml?.datasets ?? [];
+  if (!datasets.length) {
+    return { id: 'datasets-fetched', label: 'Source datasets fetched', status: 'warn', detail: 'no datasets registered' };
+  }
+  const dotDatasets = resolve(ctx.cwd, '.datasets');
+  const missing = datasets
+    .filter((d) => !existsSync(join(dotDatasets, d.id, 'concepts')))
+    .map((d) => d.id);
+  if (missing.length) {
+    return {
+      id: 'datasets-fetched',
+      label: 'Source datasets fetched',
+      status: 'fail',
+      detail: `.datasets/ missing: ${missing.join(', ')}`,
+      hint: 'run `npm run fetch-datasets`',
+    };
+  }
+  return { id: 'datasets-fetched', label: 'Source datasets fetched', status: 'pass' };
+}
+
+function datasetsGeneratedCheck(ctx) {
+  const datasets = ctx.datasetsYml?.datasets ?? [];
+  if (!datasets.length) {
+    return { id: 'datasets-generated', label: 'Generated data present', status: 'warn', detail: 'no datasets registered' };
+  }
+  const publicData = resolve(ctx.cwd, 'public', 'data');
+  const missing = datasets
+    .filter((d) => !existsSync(join(publicData, d.id, 'manifest.json')))
+    .map((d) => d.id);
+  if (missing.length) {
+    return {
+      id: 'datasets-generated',
+      label: 'Generated data present',
+      status: 'fail',
+      detail: `public/data/ missing manifest for: ${missing.join(', ')}`,
+      hint: 'run `npm run generate-data`',
+    };
+  }
+  return { id: 'datasets-generated', label: 'Generated data present', status: 'pass' };
+}
+
+function publicDatasetsJsonCheck(ctx) {
+  const path = resolve(ctx.cwd, 'public', 'datasets.json');
+  if (!existsSync(path)) {
+    return {
+      id: 'public-datasets-json',
+      label: 'public/datasets.json present',
+      status: 'fail',
+      hint: 'run `npm run generate-data`',
+    };
+  }
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf8'));
+    if (!Array.isArray(doc) || doc.length === 0) {
+      return {
+        id: 'public-datasets-json',
+        label: 'public/datasets.json non-empty',
+        status: 'warn',
+        detail: 'datasets list is empty',
+      };
+    }
+    return { id: 'public-datasets-json', label: 'public/datasets.json parses', status: 'pass' };
+  } catch (err) {
+    return {
+      id: 'public-datasets-json',
+      label: 'public/datasets.json parses',
+      status: 'fail',
+      detail: err.message,
+    };
+  }
+}
+
+function shaclShapesCheck(ctx) {
+  const shapesPath = resolve(ctx.pkgRoot, 'data', 'concept-model', 'shapes', 'glossarist.shacl.ttl');
+  if (!existsSync(shapesPath)) {
+    return {
+      id: 'shacl-shapes',
+      label: 'SHACL shapes present',
+      status: 'fail',
+      hint: 'run `npm run sync:model` to vendor shapes from concept-model',
+    };
+  }
+  const ttl = readFileSync(shapesPath, 'utf8');
+  const looksLikeShapes = /sh:\s*(NodeShape|PropertyShape|targetClass)/.test(ttl) || /a\s+sh:NodeShape/.test(ttl);
+  if (!looksLikeShapes) {
+    return {
+      id: 'shacl-shapes',
+      label: 'SHACL shapes well-formed',
+      status: 'fail',
+      detail: 'file exists but does not declare any sh:NodeShape',
+      hint: 're-sync from glossarist/concept-model',
+    };
+  }
+  return { id: 'shacl-shapes', label: 'SHACL shapes present', status: 'pass' };
+}
+
+function jsonldContextCheck(ctx) {
+  const ctxPath = resolve(ctx.pkgRoot, 'data', 'concept-model', 'glossarist.context.jsonld');
+  if (!existsSync(ctxPath)) {
+    return {
+      id: 'jsonld-context',
+      label: 'JSON-LD context present',
+      status: 'fail',
+      hint: 'run `npm run sync:model` to vendor the context',
+    };
+  }
+  try {
+    const doc = JSON.parse(readFileSync(ctxPath, 'utf8'));
+    if (!doc['@context'] || typeof doc['@context'] !== 'object') {
+      return {
+        id: 'jsonld-context',
+        label: 'JSON-LD context well-formed',
+        status: 'fail',
+        detail: 'missing or invalid @context key',
+      };
+    }
+    return { id: 'jsonld-context', label: 'JSON-LD context present', status: 'pass' };
+  } catch (err) {
+    return {
+      id: 'jsonld-context',
+      label: 'JSON-LD context parses',
+      status: 'fail',
+      detail: err.message,
+    };
+  }
+}
+
+/** @type {Array<(ctx: DoctorContext) => (Promise<CheckResult> | CheckResult)>} */
+export const CHECKS = [
+  safe('node-version', nodeVersionCheck),
+  safe('package-deps', packageDepsCheck),
+  safe('datasets-yml', datasetsYmlCheck),
+  safe('datasets-fetched', datasetsFetchedCheck),
+  safe('datasets-generated', datasetsGeneratedCheck),
+  safe('public-datasets-json', publicDatasetsJsonCheck),
+  safe('shacl-shapes', shaclShapesCheck),
+  safe('jsonld-context', jsonldContextCheck),
+];
+
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<{ results: CheckResult[], exitCode: number }>}
+ */
+export async function runDoctor(cwd = process.cwd()) {
+  const datasetsYmlPath = resolve(cwd, 'datasets.yml');
+  let datasetsYml;
+  let datasetsYmlError;
+  if (existsSync(datasetsYmlPath)) {
+    try {
+      datasetsYml = yaml.load(readFileSync(datasetsYmlPath, 'utf8'));
+    } catch (err) {
+      datasetsYmlError = err.message;
+    }
+  }
+  /** @type {DoctorContext} */
+  const ctx = { cwd, pkgRoot: PKG_ROOT, datasetsYml, datasetsYmlError };
+
+  const results = [];
+  for (const check of CHECKS) {
+    results.push(await check(ctx));
+  }
+  const failed = results.filter((r) => r.status === 'fail').length;
+  const exitCode = failed > 0 ? 1 : 0;
+  return { results, exitCode };
+}
+
+const STATUS_GLYPH = { pass: '✓', fail: '✗', warn: '!' };
+
+/**
+ * @param {CheckResult[]} results
+ * @returns {string}
+ */
+export function formatResults(results) {
+  const lines = [];
+  for (const r of results) {
+    lines.push(`${STATUS_GLYPH[r.status]} ${r.label}`);
+    if (r.detail) lines.push(`    ${r.detail}`);
+    if (r.hint) lines.push(`    → ${r.hint}`);
+  }
+  const pass = results.filter((r) => r.status === 'pass').length;
+  const fail = results.filter((r) => r.status === 'fail').length;
+  const warn = results.filter((r) => r.status === 'warn').length;
+  lines.push('');
+  lines.push(`${pass} passed, ${fail} failed, ${warn} warnings (${results.length} total)`);
+  return lines.join('\n');
+}
+
+export async function main() {
+  const { results, exitCode } = await runDoctor();
+  console.log(formatResults(results));
+  process.exit(exitCode);
+}
+
+// Run when invoked directly as a script.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}