@glossarist/concept-browser 0.7.42 → 0.7.44

package/cli/index.mjs

@@ -20,7 +20,7 @@
  */
 
 import { loadSiteConfig } from '../scripts/load-site-config.mjs';
-import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -166,22 +166,21 @@ Environment:
       }
     }
 
-    // Run vite build using the package's vite.config.ts
+    // Run vite build using the package's vite.config.ts via programmatic API
     console.log(`\n=== BUILD SPA ===\n`);
     const viteConfig = resolve(pkgRoot, 'vite.config.ts');
-    const viteBin = [resolve(pkgRoot, 'node_modules', '.bin', 'vite'), 'vite'].find(p => {
-      try { execSync(`${p} --version`, { stdio: 'pipe' }); return true; } catch { return false; }
-    });
-    execSync(`${viteBin} build --config ${viteConfig}`, {
-      stdio: 'inherit',
-      env: { ...process.env },
+    const { build: viteBuild } = await import('vite');
+    await viteBuild({
+      configFile: viteConfig,
+      root: pkgRoot,
+      mode: 'production',
     });
 
-    // Run postbuild (404 page)
-    try {
-      const postbuild = resolve(pkgRoot, 'scripts', 'generate-404.js');
-      execSync(`node ${postbuild}`, { stdio: 'inherit' });
-    } catch {}
+    // Run postbuild (404 page) via dynamic import
+    const postbuild = resolve(pkgRoot, 'scripts', 'generate-404.js');
+    if (existsSync(postbuild)) {
+      await import(`file://${postbuild}`);
+    }
 
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.42",
+  "version": "0.7.44",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "favicons": "^7.2.0",
     "glossarist": "^0.3.7",
     "js-yaml": "^4.1.0",
+    "jszip": "^3.10.1",
     "pinia": "^2.3.1",
     "postcss": "^8.5.3",
     "sharp": "^0.34.5",

package/scripts/__tests__/concept-groups.test.mjs

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { getGroups } from '../lib/concept-groups.mjs';
+
+describe('getGroups', () => {
+  it('returns explicit eng.groups when present', () => {
+    expect(getGroups({ eng: { groups: ['g1', 'g2'] }, termid: 1 })).toEqual(['g1', 'g2']);
+  });
+
+  it('derives groups from _domains with ref_type=section', () => {
+    expect(getGroups({
+      termid: 1,
+      _domains: [
+        { ref_type: 'section', concept_id: 'section-102-01' },
+        { ref_type: 'section', concept_id: 'section-102-02' },
+      ],
+    })).toEqual(['102-01', '102-02']);
+  });
+
+  it('ignores _domains entries without ref_type=section', () => {
+    expect(getGroups({
+      termid: 1,
+      _domains: [
+        { ref_type: 'other', concept_id: 'x' },
+        { ref_type: 'section', concept_id: 'section-103' },
+      ],
+    })).toEqual(['103']);
+  });
+
+  it('falls through when _domains has no section entries', () => {
+    expect(getGroups({
+      termid: '103-01-02',
+      _domains: [{ ref_type: 'other', concept_id: 'x' }],
+    })).toEqual(['103']);
+  });
+
+  it('derives group from termid with NNN- prefix (e.g. IEV)', () => {
+    expect(getGroups({ termid: '103-01-02' })).toEqual(['103']);
+  });
+
+  it('derives group from dotted termid (e.g. VIM)', () => {
+    expect(getGroups({ termid: '1.2.3.4' })).toEqual(['1.2.3']);
+  });
+
+  it('returns empty array when no derivation matches', () => {
+    expect(getGroups({ termid: 'abc' })).toEqual([]);
+  });
+
+  it('returns empty array when termid is missing', () => {
+    expect(getGroups({})).toEqual([]);
+  });
+});

package/scripts/__tests__/fetch-datasets.test.mjs

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { assertLocalPathSafe } from '../lib/local-path-safety.mjs';
+
+function makeTmpTree() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cb-fetch-'));
+  const datasetsDir = path.join(root, '.datasets');
+  const sourceDir = path.join(root, 'source-data');
+  fs.mkdirSync(datasetsDir);
+  fs.mkdirSync(path.join(sourceDir, 'concepts'), { recursive: true });
+  fs.writeFileSync(path.join(sourceDir, 'concepts', 'a.yaml'), 'termid: 1\n');
+  return { root, datasetsDir, sourceDir };
+}
+
+describe('assertLocalPathSafe', () => {
+  let tree;
+
+  beforeEach(() => { tree = makeTmpTree(); });
+  afterEach(() => {
+    fs.rmSync(tree.root, { recursive: true, force: true });
+  });
+
+  it('returns resolved path for a safe external location', () => {
+    const resolved = assertLocalPathSafe('foo', tree.sourceDir, {
+      root: tree.root,
+      datasetsDir: tree.datasetsDir,
+    });
+    // Returns the realpath (symlinks resolved); on macOS tmpdir resolves
+    // /var → /private/var, so compare against realpath, not path.resolve.
+    expect(resolved).toBe(fs.realpathSync(path.resolve(tree.root, tree.sourceDir)));
+  });
+
+  it('throws when localPath does not exist', () => {
+    expect(() =>
+      assertLocalPathSafe('foo', path.join(tree.root, 'nope'), {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/does not exist/);
+  });
+
+  it('throws when localPath equals .datasets/<id>', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(staged, { recursive: true });
+    expect(() =>
+      assertLocalPathSafe('foo', staged, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/same physical location/);
+  });
+
+  it('throws when localPath is nested inside .datasets/<id>', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(path.join(staged, 'subdir'), { recursive: true });
+    expect(() =>
+      assertLocalPathSafe('foo', path.join(staged, 'subdir'), {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/nested inside/);
+  });
+
+  it('throws when localPath contains .datasets/<id> (parent-of-staging hazard)', () => {
+    // localPath = root itself, datasetsDir = root/.datasets — staging ops
+    // (rm -rf .datasets/<id>) would touch files inside localPath.
+    expect(() =>
+      assertLocalPathSafe('foo', tree.root, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/contains .datasets/);
+  });
+
+  it('throws when localPath is a symlink to .datasets/<id> (the reported bug)', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(staged, { recursive: true });
+    const symlinkPath = path.join(tree.root, 'evil-link');
+    fs.symlinkSync(staged, symlinkPath);
+    expect(() =>
+      assertLocalPathSafe('foo', symlinkPath, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/same physical location/);
+  });
+
+  it('does NOT modify the source directory (regression for data-loss bug)', () => {
+    const sentinel = path.join(tree.sourceDir, 'concepts', 'SENTINEL.yaml');
+    fs.writeFileSync(sentinel, 'termid: sentinel\n');
+    const beforeMtime = fs.statSync(sentinel).mtimeMs;
+
+    assertLocalPathSafe('foo', tree.sourceDir, {
+      root: tree.root,
+      datasetsDir: tree.datasetsDir,
+    });
+
+    // Source directory must be completely untouched after the safety check.
+    expect(fs.existsSync(sentinel)).toBe(true);
+    expect(fs.statSync(sentinel).mtimeMs).toBe(beforeMtime);
+    expect(fs.readdirSync(path.join(tree.sourceDir, 'concepts'))).toContain('SENTINEL.yaml');
+  });
+});

package/scripts/fetch-datasets.mjs

@@ -1,23 +1,26 @@
 #!/usr/bin/env node
 /**
- * fetch-datasets.mjs — Load datasets from .gcr files or clone source repos.
+ * fetch-datasets.mjs — Load datasets from .gcr files, local paths, or git repos.
  *
  * Reads site config (via load-site-config.mjs), for each dataset:
  *   1. If .gcr/{id}.gcr exists, extract to .datasets/{id}/
  *   2. Else download from gcrPackage URL and extract
- *   3. Else clone/update source repo into .datasets/{id}/
+ *   3. Else if localPath is set, use it in-place (NO copy, NO staging)
+ *   4. Else clone/update source repo into .datasets/{id}/
  *
  * After fetching, validates that all GCR dependencies are satisfiable
  * (either provided locally or routed externally).
  *
- * Supports localPath field in dataset config for local paths.
- * Supports GITHUB_TOKEN for private repos.
+ * No shell commands. All file ops use Node fs; ZIP uses JSZip; git uses
+ * execFileSync with array args (no shell interpolation).
  */
 import fs from 'fs';
 import path from 'path';
+import JSZip from 'jszip';
 import { loadGcr } from 'glossarist';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { loadSiteConfig } from './load-site-config.mjs';
+import { assertLocalPathSafe } from './lib/local-path-safety.mjs';
 
 const ROOT = process.cwd();
 const DATASETS_DIR = path.join(ROOT, '.datasets');
@@ -39,23 +42,29 @@ async function downloadGcr(url, destPath) {
   console.log(`  Saved to ${destPath} (${(buf.length / 1024).toFixed(0)} KB)`);
 }
 
-// --- GCR extraction ---
-function extractGcr(gcrPath, targetDir) {
-  if (fs.existsSync(targetDir)) {
-    fs.rmSync(targetDir, { recursive: true, force: true });
+// --- GCR extraction (pure JSZip; no shell, cross-platform) ---
+async function extractGcr(gcrPath, targetDir) {
+  const targetAbs = path.resolve(targetDir);
+  if (fs.existsSync(targetAbs)) {
+    fs.rmSync(targetAbs, { recursive: true, force: true });
   }
-  fs.mkdirSync(targetDir, { recursive: true });
-
-  try {
-    execSync(`unzip -o -q "${gcrPath}" -d "${targetDir}"`, { stdio: 'pipe' });
-  } catch {
-    try {
-      execSync(`python3 -c "import zipfile; zipfile.ZipFile('${gcrPath}').extractall('${targetDir}')"`, { stdio: 'pipe' });
-    } catch (e2) {
-      throw new Error(`Failed to extract ${gcrPath}`);
+  fs.mkdirSync(targetAbs, { recursive: true });
+
+  const buf = fs.readFileSync(gcrPath);
+  const zip = await JSZip.loadAsync(buf);
+  const entries = Object.values(zip.files);
+  for (const entry of entries) {
+    if (entry.dir) continue;
+    // zip-slip guard: refuse entries that escape targetDir
+    const dest = path.resolve(targetAbs, entry.name);
+    if (dest !== targetAbs && !dest.startsWith(targetAbs + path.sep)) {
+      throw new Error(`Refusing to extract entry outside target dir: ${entry.name}`);
     }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const content = await entry.async('nodebuffer');
+    fs.writeFileSync(dest, content);
   }
-  console.log(`  Extracted to ${targetDir}`);
+  console.log(`  Extracted to ${targetAbs}`);
 }
 
 // --- Read GCR metadata from ZIP without extraction ---
@@ -96,7 +105,7 @@ function validateDependencies(config, gcrMetadata) {
   return errors;
 }
 
-// --- Git operations ---
+// --- Git operations (execFileSync with array args — no shell) ---
 function cloneOrUpdate(sourceRepo, targetDir) {
   const env = { ...process.env };
   let repoUrl = sourceRepo;
@@ -104,24 +113,28 @@ function cloneOrUpdate(sourceRepo, targetDir) {
     repoUrl = sourceRepo.replace('https://', `https://x-access-token:${env.GITHUB_TOKEN}@`);
   }
 
-  if (fs.existsSync(path.join(targetDir, '.git'))) {
+  const targetAbs = path.resolve(targetDir);
+
+  if (fs.existsSync(path.join(targetAbs, '.git'))) {
     console.log(`  Updating existing clone...`);
     try {
-      execSync('git fetch origin', { cwd: targetDir, stdio: 'pipe', env });
-      execSync('git reset --hard origin/HEAD', { cwd: targetDir, stdio: 'pipe', env });
-      execSync('git clean -fd', { cwd: targetDir, stdio: 'pipe', env });
+      execFileSync('git', ['fetch', 'origin'], { cwd: targetAbs, stdio: 'pipe', env });
+      execFileSync('git', ['reset', '--hard', 'origin/HEAD'], { cwd: targetAbs, stdio: 'pipe', env });
+      execFileSync('git', ['clean', '-fd'], { cwd: targetAbs, stdio: 'pipe', env });
     } catch {
       console.warn(`  git update failed, re-cloning`);
-      fs.rmSync(targetDir, { recursive: true, force: true });
-      execSync(`git clone --depth 1 "${repoUrl}" "${targetDir}"`, { stdio: 'pipe', env });
+      fs.rmSync(targetAbs, { recursive: true, force: true });
+      execFileSync('git', ['clone', '--depth', '1', repoUrl, targetAbs], { stdio: 'pipe', env });
     }
   } else {
-    fs.mkdirSync(targetDir, { recursive: true });
+    fs.mkdirSync(targetAbs, { recursive: true });
     console.log(`  Cloning ${sourceRepo}...`);
-    execSync(`git clone --depth 1 "${repoUrl}" "${targetDir}"`, { stdio: 'pipe', env });
+    execFileSync('git', ['clone', '--depth', '1', repoUrl, targetAbs], { stdio: 'pipe', env });
   }
 }
 
+// --- localPath safety check: see scripts/lib/local-path-safety.mjs ---
+
 // --- Main ---
 console.log('Fetching glossarist datasets...\n');
 
@@ -137,7 +150,7 @@ for (const ds of config.datasets) {
   try {
     if (fs.existsSync(gcrPath)) {
       console.log(`  Using local .gcr/${ds.id}.gcr`);
-      extractGcr(gcrPath, targetDir);
+      await extractGcr(gcrPath, targetDir);
     } else if (ds.gcrPackage) {
       console.log(`  Using GCR package: ${ds.gcrPackage}`);
       try {
@@ -148,29 +161,18 @@ for (const ds of config.datasets) {
         console.log();
         continue;
       }
-      extractGcr(gcrPath, targetDir);
+      await extractGcr(gcrPath, targetDir);
+    } else if (ds.localPath) {
+      // localPath means "data is here, use in-place." No copy, no staging.
+      // generate-data.mjs reads from localPath directly via datasetDir(ds).
+      const localResolved = assertLocalPathSafe(ds.id, ds.localPath);
+      console.log(`  Using localPath in-place: ${localResolved}`);
+    } else if (ds.sourceRepo) {
+      cloneOrUpdate(ds.sourceRepo, targetDir);
     } else {
-      const envOverride = ds.localPath;
-      if (envOverride) {
-        console.log(`  Using local path: ${envOverride}`);
-        if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
-        const localConcepts = path.join(envOverride, 'concepts');
-        const targetConcepts = path.join(targetDir, 'concepts');
-        if (fs.existsSync(localConcepts)) {
-          if (fs.existsSync(targetConcepts)) fs.rmSync(targetConcepts, { recursive: true, force: true });
-          execSync(`cp -r "${localConcepts}" "${targetConcepts}"`, { stdio: 'pipe' });
-        }
-        const registerYaml = path.join(envOverride, 'register.yaml');
-        if (fs.existsSync(registerYaml)) {
-          fs.copyFileSync(registerYaml, path.join(targetDir, 'register.yaml'));
-        }
-      } else if (ds.sourceRepo) {
-        cloneOrUpdate(ds.sourceRepo, targetDir);
-      } else {
-        console.warn(`  No source configured, skipping`);
-        console.log();
-        continue;
-      }
+      console.warn(`  No source configured, skipping`);
+      console.log();
+      continue;
     }
 
     // Read metadata for dependency validation (from GCR ZIP, not extracted dir)

package/scripts/generate-data.mjs

@@ -3,12 +3,24 @@ import path from 'path';
 import yaml from 'js-yaml';
 import { naturalSort, Register, parseMention } from 'glossarist';
 import { loadSiteConfig } from './load-site-config.mjs';
-
+import { getGroups } from './lib/concept-groups.mjs';
 const __dirname = path.dirname(new URL(import.meta.url).pathname);
 const ROOT = process.cwd();
 const PUBLIC = path.join(ROOT, 'public');
 const DATA = path.join(PUBLIC, 'data');
 
+/**
+ * Resolve a dataset's source directory.
+ * - If `ds.localPath` is set, use it in-place (resolved against ROOT).
+ *   No staging, no copy. fetch-datasets.mjs verifies the path is safe.
+ * - Otherwise fall back to the standard .datasets/<id>/ staging dir.
+ */
+function datasetDir(ds) {
+  return ds.localPath
+    ? path.resolve(ROOT, ds.localPath)
+    : path.join(ROOT, '.datasets', ds.id);
+}
+
 const DS_PALETTE = [
   '#3366ff', '#0d9488', '#d97706', '#8b5cf6',
   '#ec4899', '#059669', '#dc2626', '#6366f1',
@@ -574,24 +586,6 @@ function getPrimaryDesignation(conceptYaml) {
   return descs;
 }
 
-function getGroups(conceptYaml) {
-  if (conceptYaml.eng && conceptYaml.eng.groups) return conceptYaml.eng.groups;
-  // Derive groups from domains (e.g. section-based grouping in G18)
-  if (conceptYaml._domains) {
-    const sectionIds = conceptYaml._domains
-      .filter(d => d.ref_type === 'section' && d.concept_id)
-      .map(d => d.concept_id.replace(/^section-/, ''));
-    if (sectionIds.length) return sectionIds;
-  }
-  const termid = String(conceptYaml.termid);
-  if (/^\d{3}-/.test(termid)) return [termid.substring(0, 3)];
-  if (/^\d+\.\d+\.\d+/.test(termid)) {
-    const parts = termid.split('.');
-    return [`${parts[0]}.${parts[1]}.${parts[2]}`];
-  }
-  return [];
-}
-
 function escapeTurtle(s) {
   return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
 }
@@ -952,7 +946,8 @@ function processDataset(dir, register, opts) {
   }
 
   // Copy bulk format files from compiled/ directory (full GCR)
-  const compiledDir = path.join(ROOT, '.datasets', register, 'compiled');
+  const sourceRoot = path.dirname(dir);
+  const compiledDir = path.join(sourceRoot, 'compiled');
   const bulkFormats = [];
   if (fs.existsSync(compiledDir)) {
     for (const file of fs.readdirSync(compiledDir)) {
@@ -1011,7 +1006,7 @@ function processDataset(dir, register, opts) {
   writeJson(path.join(DATA, register, 'manifest.json'), manifest);
 
   // Copy bibliography.yaml → bibliography.json
-  const bibPath = path.join(ROOT, '.datasets', register, 'bibliography.yaml');
+  const bibPath = path.join(sourceRoot, 'bibliography.yaml');
   if (fs.existsSync(bibPath)) {
     const bibData = readYaml(bibPath);
     writeJson(path.join(DATA, register, 'bibliography.json'), bibData);
@@ -1019,7 +1014,7 @@ function processDataset(dir, register, opts) {
   }
 
   // Copy images/
-  const imagesSrcDir = path.join(ROOT, '.datasets', register, 'images');
+  const imagesSrcDir = path.join(sourceRoot, 'images');
   if (fs.existsSync(imagesSrcDir) && fs.statSync(imagesSrcDir).isDirectory()) {
     const imagesDestDir = path.join(DATA, register, 'images');
     fs.mkdirSync(imagesDestDir, { recursive: true });
@@ -1048,8 +1043,8 @@ const registerCache = {};
 
 // Pre-load all register.yaml files (needed before buildRefMaps for URI pattern indexing)
 for (const ds of config.datasets) {
-  const registerDir = path.join(ROOT, '.datasets', ds.id);
-  const registerYamlPath = path.join(registerDir, 'register.yaml');
+  const dsDir = datasetDir(ds);
+  const registerYamlPath = path.join(dsDir, 'register.yaml');
   if (fs.existsSync(registerYamlPath)) {
     try {
       const raw = yaml.load(fs.readFileSync(registerYamlPath, 'utf8'));
@@ -1065,7 +1060,7 @@ const refMaps = buildRefMaps(config, registerCache);
 for (let i = 0; i < config.datasets.length; i++) {
   const ds = config.datasets[i];
 
-  const dir = path.join(ROOT, '.datasets', ds.id, 'concepts');
+  const dir = path.join(datasetDir(ds), 'concepts');
   if (!fs.existsSync(dir)) {
     console.warn(`Skipping ${ds.id}: source directory not found (${dir})`);
     console.warn(`  Run: npm run fetch-datasets`);
@@ -1107,8 +1102,8 @@ for (let i = 0; i < config.datasets.length; i++) {
     status: ds.editionStatus || reg?.status,
     ordering: reg?.ordering || null,
     sections: reg?.sections ? reg.sections.map(s => s.toJSON()) : [],
-    hasBibliography: fs.existsSync(path.join(ROOT, '.datasets', ds.id, 'bibliography.yaml')),
-    hasImages: fs.existsSync(path.join(ROOT, '.datasets', ds.id, 'images')),
+    hasBibliography: fs.existsSync(path.join(datasetDir(ds), 'bibliography.yaml')),
+    hasImages: fs.existsSync(path.join(datasetDir(ds), 'images')),
   });
   registry.push({
     id: ds.id,

package/scripts/lib/concept-groups.mjs

@@ -0,0 +1,16 @@
+export function getGroups(conceptYaml) {
+  if (conceptYaml.eng && conceptYaml.eng.groups) return conceptYaml.eng.groups;
+  if (conceptYaml._domains) {
+    const sectionIds = conceptYaml._domains
+      .filter(d => d.ref_type === 'section' && d.concept_id)
+      .map(d => d.concept_id.replace(/^section-/, ''));
+    if (sectionIds.length) return sectionIds;
+  }
+  const termid = String(conceptYaml.termid);
+  if (/^\d{3}-/.test(termid)) return [termid.substring(0, 3)];
+  if (/^\d+\.\d+\.\d+/.test(termid)) {
+    const parts = termid.split('.');
+    return [`${parts[0]}.${parts[1]}.${parts[2]}`];
+  }
+  return [];
+}

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__/dataset-view.test.ts

@@ -4,7 +4,7 @@ import { createPinia, setActivePinia } from 'pinia';
 import { createRouter, createMemoryHistory } from 'vue-router';
 import DatasetView from '../views/DatasetView.vue';
 import { useVocabularyStore } from '../stores/vocabulary';
-import type { Manifest, ConceptSummary } from '../adapters/types';
+import type { Manifest, ConceptSummary, SectionNode } from '../adapters/types';
 
 function makeManifest(overrides: Partial<Manifest> = {}): Manifest {
   return {
@@ -230,4 +230,98 @@ describe('DatasetView', () => {
     expect(prevBtn).toBeDefined();
     expect(prevBtn!.attributes('disabled')).toBeDefined();
   });
+
+  describe('hierarchical section filter', () => {
+    const HIERARCHICAL_TREE: SectionNode[] = [
+      {
+        id: '102',
+        names: { eng: 'Mathematics' },
+        conceptCount: 0,
+        children: [
+          { id: '102-01', names: { eng: 'Sets' }, conceptCount: 2 },
+          {
+            id: '102-02',
+            names: { eng: 'Numbers' },
+            conceptCount: 2,
+            children: [
+              { id: '102-02-01', names: { eng: 'Reals' }, conceptCount: 1 },
+            ],
+          },
+        ],
+      },
+      { id: '103', names: { eng: 'Functions' }, conceptCount: 1 },
+    ];
+
+    function makeHierarchicalAdapter(concepts: ConceptSummary[], sections: SectionNode[]) {
+      const dense = concepts.filter(Boolean);
+      return {
+        registerId: 'test',
+        index: dense,
+        manifest: null,
+        getConceptCount: () => dense.length,
+        getConcepts: () => dense,
+        isRangeLoaded: () => true,
+        ensureChunksForRange: async () => {},
+        ensureAllChunksLoaded: async () => {},
+        getAdjacentConcepts: () => ({ prev: null, next: null }),
+        getSectionTree: () => sections,
+      } as any;
+    }
+
+    function mountHierarchical(concepts: ConceptSummary[], sectionId: string) {
+      const store = useVocabularyStore();
+      store.manifests.set('test', makeManifest());
+      store.datasets.set('test', makeHierarchicalAdapter(concepts, HIERARCHICAL_TREE));
+      return mount(DatasetView, {
+        global: { plugins: [pinia, router] },
+        props: { registerId: 'test' },
+      });
+    }
+
+    it('matches concepts in a child section when filtering by parent (closure)', async () => {
+      const concepts: ConceptSummary[] = [
+        { id: 'a', designations: { eng: 'set A' }, eng: 'set A', status: 'valid', groups: ['102-01'] },
+        { id: 'b', designations: { eng: 'unrelated' }, eng: 'unrelated', status: 'valid', groups: ['999'] },
+      ];
+      const wrapper = mountHierarchical(concepts, 'section-102');
+      await router.push({ name: 'dataset', params: { registerId: 'test' }, query: { section: 'section-102' } });
+      await flushPromises();
+      expect(wrapper.text()).toContain('set A');
+      expect(wrapper.text()).not.toContain('unrelated');
+    });
+
+    it('matches concepts at arbitrary depth (grandparent closure)', async () => {
+      const concepts: ConceptSummary[] = [
+        { id: 'deep', designations: { eng: 'real number' }, eng: 'real number', status: 'valid', groups: ['102-02-01'] },
+        { id: 'other', designations: { eng: 'other concept' }, eng: 'other concept', status: 'valid', groups: ['103'] },
+      ];
+      const wrapper = mountHierarchical(concepts, 'section-102');
+      await router.push({ name: 'dataset', params: { registerId: 'test' }, query: { section: 'section-102' } });
+      await flushPromises();
+      expect(wrapper.text()).toContain('real number');
+      expect(wrapper.text()).not.toContain('other concept');
+    });
+
+    it('still matches by concept ID prefix when no groups are set', async () => {
+      const concepts: ConceptSummary[] = [
+        { id: '102.3.4', designations: { eng: 'numbered term' }, eng: 'numbered term', status: 'valid' },
+        { id: '999.1', designations: { eng: 'different section' }, eng: 'different section', status: 'valid' },
+      ];
+      const wrapper = mountHierarchical(concepts, 'section-102');
+      await router.push({ name: 'dataset', params: { registerId: 'test' }, query: { section: 'section-102' } });
+      await flushPromises();
+      expect(wrapper.text()).toContain('numbered term');
+      expect(wrapper.text()).not.toContain('different section');
+    });
+
+    it('renders the section display name when filter is active', async () => {
+      const concepts: ConceptSummary[] = [
+        { id: 'a', designations: { eng: 'set A' }, eng: 'set A', status: 'valid', groups: ['102-01'] },
+      ];
+      const wrapper = mountHierarchical(concepts, 'section-102');
+      await router.push({ name: 'dataset', params: { registerId: 'test' }, query: { section: 'section-102' } });
+      await flushPromises();
+      expect(wrapper.text()).toContain('102 — Mathematics');
+    });
+  });
 });

package/src/__tests__/section-display.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { sectionName, formatSectionLabel } from '../utils/section-display';
+
+describe('sectionName', () => {
+  it('prefers the requested language', () => {
+    expect(sectionName({ id: 'x', names: { eng: 'X', fra: 'X (fra)' } }, 'fra')).toBe('X (fra)');
+  });
+
+  it('falls back to English when requested language missing', () => {
+    expect(sectionName({ id: 'x', names: { eng: 'X' } }, 'deu')).toBe('X');
+  });
+
+  it('falls back to id when no names at all', () => {
+    expect(sectionName({ id: 'x', names: {} }, 'fra')).toBe('x');
+  });
+
+  it('falls back to id when names object missing', () => {
+    expect(sectionName({ id: 'x' }, 'fra')).toBe('x');
+  });
+});
+
+describe('formatSectionLabel', () => {
+  it('returns just id when name is empty', () => {
+    expect(formatSectionLabel({ id: '102', names: {} }, 'eng')).toBe('102');
+  });
+
+  it('returns just id when name equals id', () => {
+    expect(formatSectionLabel({ id: '102', names: { eng: '102' } }, 'eng')).toBe('102');
+  });
+
+  it('returns just name when name equals id-with-spaces (EXPRESS schema convention)', () => {
+    expect(formatSectionLabel({ id: 'action_schema', names: { eng: 'action schema' } }, 'eng')).toBe('action schema');
+  });
+
+  it('returns "id — name" when name is meaningfully different', () => {
+    expect(formatSectionLabel({ id: '102', names: { eng: 'Mathematics' } }, 'eng')).toBe('102 — Mathematics');
+  });
+
+  it('localizes the name lookup', () => {
+    expect(formatSectionLabel({ id: '102', names: { eng: 'Math', fra: 'Maths' } }, 'fra')).toBe('102 — Maths');
+  });
+
+  it('falls back through English when requested language has no name', () => {
+    expect(formatSectionLabel({ id: '102', names: { eng: 'Math' } }, 'fra')).toBe('102 — Math');
+  });
+});

package/src/__tests__/section-tree.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import type { SectionNode } from '../adapters/types';
+import {
+  findSectionNode,
+  collectDescendantSectionIds,
+  toSectionNode,
+  toSectionTree,
+} from '../utils/section-tree';
+
+const TREE: SectionNode[] = [
+  {
+    id: '102',
+    names: { eng: 'Mathematics' },
+    conceptCount: 0,
+    children: [
+      { id: '102-01', names: { eng: 'Sets' }, conceptCount: 5 },
+      {
+        id: '102-02',
+        names: { eng: 'Numbers' },
+        conceptCount: 3,
+        children: [
+          { id: '102-02-01', names: { eng: 'Reals' }, conceptCount: 1 },
+        ],
+      },
+    ],
+  },
+  { id: '103', names: { eng: 'Functions' }, conceptCount: 0 },
+];
+
+describe('findSectionNode', () => {
+  it('finds a root by id', () => {
+    expect(findSectionNode(TREE, '103')?.id).toBe('103');
+  });
+
+  it('finds a descendant by id (recursive)', () => {
+    expect(findSectionNode(TREE, '102-02-01')?.id).toBe('102-02-01');
+  });
+
+  it('returns null for unknown id', () => {
+    expect(findSectionNode(TREE, '999')).toBeNull();
+  });
+
+  it('returns null for empty tree', () => {
+    expect(findSectionNode([], '102')).toBeNull();
+  });
+});
+
+describe('collectDescendantSectionIds', () => {
+  it('includes root and all descendants at arbitrary depth', () => {
+    const ids = collectDescendantSectionIds(TREE, '102');
+    expect([...ids].sort()).toEqual(['102', '102-01', '102-02', '102-02-01']);
+  });
+
+  it('returns single-element set for a leaf', () => {
+    expect([...collectDescendantSectionIds(TREE, '103')]).toEqual(['103']);
+  });
+
+  it('returns empty set for unknown root', () => {
+    expect(collectDescendantSectionIds(TREE, '999').size).toBe(0);
+  });
+});
+
+describe('toSectionNode', () => {
+  it('maps minimal input with id only', () => {
+    expect(toSectionNode({ id: 'x' })).toEqual({
+      id: 'x',
+      names: {},
+      conceptCount: 0,
+    });
+  });
+
+  it('preserves names and conceptCount', () => {
+    expect(toSectionNode({ id: 'x', names: { eng: 'X' }, conceptCount: 7 })).toEqual({
+      id: 'x',
+      names: { eng: 'X' },
+      conceptCount: 7,
+    });
+  });
+
+  it('defaults missing id to empty string', () => {
+    expect(toSectionNode({}).id).toBe('');
+  });
+
+  it('defaults missing conceptCount to 0', () => {
+    expect(toSectionNode({ id: 'x' }).conceptCount).toBe(0);
+  });
+
+  it('defaults missing names to empty object', () => {
+    expect(toSectionNode({ id: 'x' }).names).toEqual({});
+  });
+
+  it('recursively maps children', () => {
+    const node = toSectionNode({
+      id: 'p',
+      names: { eng: 'Parent' },
+      children: [{ id: 'c', names: { eng: 'Child' } }],
+    });
+    expect(node.children?.[0]).toEqual({
+      id: 'c',
+      names: { eng: 'Child' },
+      conceptCount: 0,
+    });
+  });
+
+  it('omits children array when source has none', () => {
+    expect(toSectionNode({ id: 'x' }).children).toBeUndefined();
+  });
+
+  it('omits children array when source children is empty', () => {
+    expect(toSectionNode({ id: 'x', children: [] }).children).toBeUndefined();
+  });
+});
+
+describe('toSectionTree', () => {
+  it('maps a list of roots', () => {
+    const tree = toSectionTree([
+      { id: 'a', names: { eng: 'A' } },
+      { id: 'b' },
+    ]);
+    expect(tree).toHaveLength(2);
+    expect(tree[0].id).toBe('a');
+    expect(tree[1].names).toEqual({});
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(toSectionTree([])).toEqual([]);
+  });
+});

package/src/adapters/GraphDataSource.ts

@@ -3,6 +3,7 @@ import type { Concept, RelatedConcept } from 'glossarist';
 import type { DatasetAdapter } from './DatasetAdapter';
 import { UriRouter } from './UriRouter';
 import { slugify } from '../utils/slugify';
+import { toSectionNode, toSectionTree } from '../utils/section-tree';
 
 interface DomainNodeJson {
   uri?: string;
@@ -14,12 +15,6 @@ interface DomainNodeJson {
   children?: DomainNodeJson[];
 }
 
-interface SectionJson {
-  id: string;
-  names?: Record<string, string>;
-  children?: SectionJson[];
-}
-
 function resolveRefTarget(rc: RelatedConcept, uriBase: string, registerId: string, urnMap?: ReadonlyMap<string, string>): string {
   if (!rc.ref) return '';
   const ref = rc.ref;
@@ -136,7 +131,7 @@ export class GraphDataSource {
   getSectionTree(): SectionNode[] {
     const nodes = this.adapter.manifest?.sections;
     if (!nodes || nodes.length === 0) return [];
-    return nodes.map(s => this.mapManifestSection(s));
+    return toSectionTree(nodes);
   }
 
   private mapDomainNode(dn: DomainNodeJson): GraphNode {
@@ -151,28 +146,17 @@ export class GraphDataSource {
       conceptCount: dn.conceptCount || 0,
     };
     if (dn.children && dn.children.length > 0) {
-      node.children = dn.children.map((c) => this.mapSectionNode(c));
+      node.children = dn.children.map(c => this.domainNodeToSection(c));
     }
     return node;
   }
 
-  private mapSectionNode(dn: DomainNodeJson): SectionNode {
-    const node: SectionNode = {
-      id: dn.id ?? '',
+  private domainNodeToSection(dn: DomainNodeJson): SectionNode {
+    return toSectionNode({
+      id: dn.id,
       names: dn.names || (dn.label ? { eng: dn.label } : {}),
-      conceptCount: dn.conceptCount || 0,
-    };
-    if (dn.children && dn.children.length > 0) {
-      node.children = dn.children.map((c) => this.mapSectionNode(c));
-    }
-    return node;
-  }
-
-  private mapManifestSection(s: SectionJson): SectionNode {
-    const node: SectionNode = { id: s.id, names: s.names || {}, conceptCount: 0 };
-    if (s.children && s.children.length > 0) {
-      node.children = s.children.map(c => this.mapManifestSection(c));
-    }
-    return node;
+      conceptCount: dn.conceptCount,
+      children: dn.children,
+    });
   }
 }

package/src/components/AppSidebar.vue

@@ -8,6 +8,8 @@ import { useSiteConfig } from '../config/use-site-config';
 import NavIcon from './NavIcon.vue';
 import { useI18n, locale } from '../i18n';
 import type { SectionNode } from '../adapters/types';
+import { toSectionTree } from '../utils/section-tree';
+import { formatSectionLabel, sectionName as sectionLocalized } from '../utils/section-display';
 
 const OntologySidebarSection = defineAsyncComponent(() => import('./OntologySidebarSection.vue'));
 
@@ -174,26 +176,15 @@ function toggleSectionNode(id: string) {
 function getDatasetSections(dsId: string): SectionNode[] {
   const m = store.manifests.get(dsId);
   if (!m?.sections?.length) return [];
-  return m.sections.map(s => enrichSectionNode(s));
-}
-
-function enrichSectionNode(s: { id: string; names: Record<string, string>; children?: any[] }): SectionNode {
-  const node: SectionNode = { id: s.id, names: s.names || {}, conceptCount: 0 };
-  if (s.children && s.children.length > 0) {
-    node.children = s.children.map(c => enrichSectionNode(c));
-  }
-  return node;
+  return toSectionTree(m.sections);
 }
 
 function sectionLabel(section: SectionNode): string {
-  const name = section.names[locale.value] || section.names.eng || '';
-  return name || section.id;
+  return sectionLocalized(section, locale.value);
 }
 
 function sectionDisplay(section: SectionNode): string {
-  const name = sectionLabel(section);
-  if (name && name !== section.id) return `${section.id} — ${name}`;
-  return name || section.id;
+  return formatSectionLabel(section, locale.value);
 }
 
 function goToSection(dsId: string, sectionId: string) {

package/src/utils/section-display.ts

@@ -0,0 +1,21 @@
+import type { SectionNode } from '../adapters/types';
+
+interface SectionLike {
+  id: string;
+  names?: Record<string, string>;
+}
+
+export function sectionName(section: SectionLike, lang: string): string {
+  const names = section.names || {};
+  return names[lang] || names.eng || section.id;
+}
+
+export function formatSectionLabel(section: SectionLike, lang: string): string {
+  const names = section.names || {};
+  const name = names[lang] || names.eng || '';
+  const bare = section.id;
+  if (!name) return bare;
+  if (name === bare) return name;
+  if (name === bare.replace(/_/g, ' ')) return name;
+  return `${bare} — ${name}`;
+}

package/src/utils/section-tree.ts

@@ -0,0 +1,53 @@
+import type { SectionNode } from '../adapters/types';
+
+interface SectionLike {
+  id?: string;
+  names?: Record<string, string>;
+  conceptCount?: number;
+  children?: SectionLike[];
+}
+
+export function findSectionNode(
+  tree: readonly SectionNode[],
+  id: string,
+): SectionNode | null {
+  for (const node of tree) {
+    if (node.id === id) return node;
+    if (node.children) {
+      const found = findSectionNode(node.children, id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function collectDescendantSectionIds(
+  tree: readonly SectionNode[],
+  rootId: string,
+): Set<string> {
+  const root = findSectionNode(tree, rootId);
+  if (!root) return new Set();
+  const ids = new Set<string>();
+  const walk = (n: SectionNode) => {
+    ids.add(n.id);
+    n.children?.forEach(walk);
+  };
+  walk(root);
+  return ids;
+}
+
+export function toSectionNode(s: SectionLike): SectionNode {
+  const node: SectionNode = {
+    id: s.id ?? '',
+    names: s.names || {},
+    conceptCount: s.conceptCount ?? 0,
+  };
+  if (s.children && s.children.length > 0) {
+    node.children = s.children.map(toSectionNode);
+  }
+  return node;
+}
+
+export function toSectionTree(items: readonly SectionLike[]): SectionNode[] {
+  return items.map(toSectionNode);
+}

package/src/views/DatasetView.vue

@@ -9,7 +9,9 @@ import { langName, langLabel, sortLanguages } from '../utils/lang';
 import ConceptCard from '../components/ConceptCard.vue';
 import { useI18n, locale } from '../i18n';
 import { useSiteConfig } from '../config/use-site-config';
-import type { SectionNode } from '../adapters/types';
+import type { SectionNode, ConceptSummary } from '../adapters/types';
+import { collectDescendantSectionIds, findSectionNode } from '../utils/section-tree';
+import { formatSectionLabel } from '../utils/section-display';
 
 const props = defineProps<{ registerId: string }>();
 
@@ -167,20 +169,34 @@ const filtered = computed(() => {
   const q = filter.value.trim().toLowerCase();
   const lang = selectedLang.value;
   const sec = sectionQuery.value;
+  const closure = sectionClosure.value;
   return loadedConcepts.value.filter(c => {
     if (lang && !(lang in (c.designations ?? {}))) return false;
-    if (sec && !conceptMatchesSection(c, sec)) return false;
+    if (sec && !conceptMatchesSection(c, sec.replace(/^section-/, ''), closure)) return false;
     if (!q) return true;
     return (c.eng || '').toLowerCase().includes(q) || c.id.toLowerCase().includes(q);
   });
 });
 
-function conceptMatchesSection(concept: import('../adapters/types').ConceptSummary, sectionPrefix: string): boolean {
-  const prefix = sectionPrefix.replace(/^section-/, '');
-  // Check explicit groups (e.g. G18 sections derived from domains)
-  if (concept.groups?.length && concept.groups.includes(prefix)) return true;
-  // Check concept ID prefix matching (e.g. VIML/VIM numbered sections)
-  return concept.id.startsWith(prefix + '.') || concept.id.startsWith(prefix + '-');
+const sectionClosure = computed<Set<string> | null>(() => {
+  const q = sectionQuery.value;
+  if (!q) return null;
+  const prefix = q.replace(/^section-/, '');
+  const tree = getSections();
+  const closure = collectDescendantSectionIds(tree, prefix);
+  return closure.size > 0 ? closure : null;
+});
+
+function conceptMatchesSection(concept: ConceptSummary, sectionId: string, closure: Set<string> | null): boolean {
+  if (closure) {
+    if (concept.groups?.some(g => closure.has(g))) return true;
+    if (closure.has(sectionId)) {
+      return concept.id.startsWith(sectionId + '.') || concept.id.startsWith(sectionId + '-');
+    }
+    return false;
+  }
+  if (concept.groups?.length && concept.groups.includes(sectionId)) return true;
+  return concept.id.startsWith(sectionId + '.') || concept.id.startsWith(sectionId + '-');
 }
 
 function getSections(): SectionNode[] {
@@ -188,18 +204,12 @@ function getSections(): SectionNode[] {
   return adapter.value.getSectionTree();
 }
 
-function sectionName(section: SectionNode): string {
-  return section.names[locale.value] || section.names.eng || section.id;
-}
-
 const sectionDisplayName = computed(() => {
   if (!sectionQuery.value) return '';
   const prefix = sectionQuery.value.replace(/^section-/, '');
-  const sections = getSections();
-  const found = sections.find(s => s.id === prefix);
+  const found = findSectionNode(getSections(), prefix);
   if (!found) return prefix;
-  const name = sectionName(found);
-  return name !== found.id ? `${found.id} — ${name}` : name;
+  return formatSectionLabel(found, locale.value);
 });
 
 // Alphabetical grouping