@glossarist/concept-browser 0.7.66 → 0.7.67

package/cli/index.mjs

@@ -30,9 +30,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 
 const commands = {
-  fetch: () => import('../scripts/fetch-datasets.mjs'),
-  generate: () => import('../scripts/generate-data.mjs'),
-  edges: () => import('../scripts/build-edges.js'),
+  fetch:    async () => (await import('../scripts/fetch-datasets.mjs')).main(),
+  generate: async () => { await import('../scripts/generate-data.mjs'); },
+  edges:    async () => (await import('../scripts/build-edges.js')).main(),
+  about:    async () => (await import('../scripts/process-about-pages.mjs')).main(),
 };
 
 function parseArgs(argv) {
@@ -61,7 +62,8 @@ Commands:
   fetch      Fetch/update datasets from GCR packages or source repos
   generate   Convert YAML concepts to JSON-LD static data
   edges      Build cross-reference edges from generated concepts
-  build      Full pipeline (fetch + generate + edges + vite build)
+  about      Compile per-dataset and per-group about pages
+  build      Full pipeline (fetch + generate + edges + about + vite build)
   site       Same as build
   normalize  NFC-normalize YAML files in .datasets/
   doctor     Diagnose the local environment (deps, datasets, shapes, context)
@@ -87,7 +89,7 @@ Environment:
     if (!process.env.BASE_PATH && config?.basePath) {
       process.env.BASE_PATH = config.basePath;
     }
-    for (const step of ['fetch', 'generate', 'edges']) {
+    for (const step of ['fetch', 'generate', 'edges', 'about']) {
       console.log(`\n=== ${step.toUpperCase()} ===\n`);
       await commands[step]();
     }
@@ -191,40 +193,43 @@ 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 (runner) {
+    await runner();
+    return;
+  }
+
+  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 already normalized`);
-      } else {
-        console.log(`Normalized ${nonNfc} of ${checked} file(s)`);
-        for (const f of fixed) console.log(`  ${f}`);
+        console.log(`NFC OK: ${checked} file(s) checked, all normalized`);
+        return;
       }
-      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 (cmd === 'doctor') {
-      const { main: doctorMain } = await import('../scripts/doctor.mjs');
-      await doctorMain();
-      return;
+    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}`);
     }
-    console.error(`Unknown command: ${cmd}`);
-    console.error('Run `concept-browser help` for usage.');
-    process.exit(1);
+    return;
   }
 
-  await runner();
+  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);
 }
 
 main().catch(e => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.66",
+  "version": "0.7.67",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "autoprefixer": "^10.4.21",
     "d3": "^7.9.0",
     "favicons": "^7.2.0",
-    "glossarist": "^0.4.12",
+    "glossarist": "^0.4.15",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "pinia": "^2.3.1",

package/scripts/__tests__/cli-script-contract.test.mjs

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+
+// Verifies every CLI-driven script exports main() and uses a
+// direct-invocation guard. This pins the contract documented in
+// TODO.bugs/03 and TODO.bugs/05: scripts are testable AND
+// auto-run when invoked directly. Without this contract, the CLI
+// would need a separate code path per script (some auto-run via
+// import side-effect, others need explicit m.main()).
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const SCRIPT_PATHS = [
+  '../../scripts/fetch-datasets.mjs',
+  '../../scripts/build-edges.js',
+  '../../scripts/process-about-pages.mjs',
+];
+
+describe('CLI script contract: every script exports main()', () => {
+  for (const scriptPath of SCRIPT_PATHS) {
+    it(`${scriptPath} exports main as a function`, async () => {
+      const mod = await import(scriptPath);
+      expect(typeof mod.main).toBe('function');
+    });
+  }
+});
+
+describe('CLI script contract: direct-invocation guard', () => {
+  for (const scriptPath of SCRIPT_PATHS) {
+    it(`${scriptPath} source uses realpathSync direct-invocation guard`, () => {
+      const abs = resolve(__dirname, scriptPath);
+      const src = readFileSync(abs, 'utf8');
+      expect(src).toMatch(/realpathSync\s*\(\s*process\.argv\[1\]/);
+      expect(src).toMatch(/realpathSync\s*\(\s*fileURLToPath\s*\(\s*import\.meta\.url\s*\)\s*\)/);
+    });
+  }
+});

package/scripts/__tests__/first-non-empty.test.mjs

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { firstNonEmpty } from '../lib/first-non-empty.mjs';
+
+describe('firstNonEmpty — register-wins resolution', () => {
+  it('returns the first value when both are present (register wins)', () => {
+    expect(firstNonEmpty('reg-value', 'ds-value')).toBe('reg-value');
+  });
+
+  it('falls through to site-config when register value is null', () => {
+    expect(firstNonEmpty(null, 'ds-value')).toBe('ds-value');
+  });
+
+  it('falls through to site-config when register value is undefined', () => {
+    expect(firstNonEmpty(undefined, 'ds-value')).toBe('ds-value');
+  });
+
+  it('falls through to site-config when register value is empty string', () => {
+    expect(firstNonEmpty('', 'ds-value')).toBe('ds-value');
+  });
+
+  it('falls through to site-config when register value is empty array', () => {
+    expect(firstNonEmpty([], ['ds-tag'])).toEqual(['ds-tag']);
+  });
+
+  it('returns the first value when site-config is empty', () => {
+    expect(firstNonEmpty('reg-value', '')).toBe('reg-value');
+    expect(firstNonEmpty('reg-value', null)).toBe('reg-value');
+    expect(firstNonEmpty('reg-value', undefined)).toBe('reg-value');
+  });
+
+  it('returns the first value when register is array and site-config is empty', () => {
+    expect(firstNonEmpty(['reg'], [])).toEqual(['reg']);
+  });
+
+  it('returns the default when both are absent', () => {
+    expect(firstNonEmpty(null, undefined, 'default')).toBe('default');
+  });
+
+  it('returns undefined when no arguments are non-empty', () => {
+    expect(firstNonEmpty(null, undefined, '', [])).toBeUndefined();
+  });
+
+  it('returns undefined when called with no arguments', () => {
+    expect(firstNonEmpty()).toBeUndefined();
+  });
+
+  it('does not skip falsy but meaningful values (e.g. 0, false)', () => {
+    expect(firstNonEmpty(0, 1)).toBe(0);
+    expect(firstNonEmpty(false, true)).toBe(false);
+  });
+});

package/scripts/__tests__/process-about-pages.test.mjs

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+const scriptPath = join(dirname(new URL(import.meta.url).pathname), '..', 'process-about-pages.mjs');
+
+// Process-about-pages discovers per-dataset about content from either
+// .datasets/<id>/about/ (fetched) OR site-config localPath overrides.
+// This spec covers both discovery paths plus the per-group path.
+describe('process-about-pages — discovery paths', () => {
+  let root;
+  let origCwd;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'about-pages-'));
+    origCwd = process.cwd();
+    process.chdir(root);
+    // The script writes to public/pages under CWD.
+    mkdirSync(join(root, 'public'), { recursive: true });
+  });
+
+  afterEach(() => {
+    process.chdir(origCwd);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  // Re-import each time with a cache-busting query so main() doesn't
+  // auto-run on cached load. The exported main() is invoked explicitly.
+  async function runMain() {
+    const url = new URL(`file://${scriptPath}?t=${Date.now()}`);
+    const mod = await import(url.href);
+    return mod.main();
+  }
+
+  function writeSiteConfig(datasets) {
+    const lines = ['id: test', 'datasets:'];
+    for (const d of datasets) {
+      lines.push(`  - id: ${d.id}`);
+      if (d.localPath) lines.push(`    localPath: ${d.localPath}`);
+      lines.push(`    title: "${d.id}"`);
+    }
+    writeFileSync(join(root, 'site-config.yml'), lines.join('\n') + '\n');
+  }
+
+  it('discovers about pages under .datasets/<id>/about/', async () => {
+    mkdirSync(join(root, '.datasets', 'foo', 'about'), { recursive: true });
+    writeFileSync(
+      join(root, '.datasets', 'foo', 'about', 'about.md'),
+      '# Foo\n\nThe foo dataset.',
+    );
+
+    await runMain();
+
+    const outPath = join(root, 'public', 'pages', 'dataset-foo-about.json');
+    expect(existsSync(outPath)).toBe(true);
+    const parsed = JSON.parse(readFileSync(outPath, 'utf8'));
+    expect(parsed.title).toBe('Foo');
+    expect(parsed.html).toContain('<h1>Foo</h1>');
+  });
+
+  it('discovers about pages via site-config localPath when .datasets/ is absent', async () => {
+    const localRoot = mkdtempSync(join(tmpdir(), 'local-ds-'));
+    try {
+      mkdirSync(join(localRoot, 'about'), { recursive: true });
+      writeFileSync(
+        join(localRoot, 'about', 'about.md'),
+        '# Bar\n\nLocal-path dataset.',
+      );
+      writeSiteConfig([{ id: 'bar', localPath: localRoot }]);
+
+      await runMain();
+
+      const outPath = join(root, 'public', 'pages', 'dataset-bar-about.json');
+      expect(existsSync(outPath)).toBe(true);
+      const parsed = JSON.parse(readFileSync(outPath, 'utf8'));
+      expect(parsed.title).toBe('Bar');
+    } finally {
+      rmSync(localRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('discovers group about pages under site-content/groups/<id>/about/', async () => {
+    mkdirSync(join(root, 'site-content', 'groups', 'mygroup', 'about'), { recursive: true });
+    writeFileSync(
+      join(root, 'site-content', 'groups', 'mygroup', 'about', 'about.md'),
+      '# My Group\n\nA group of datasets.',
+    );
+
+    await runMain();
+
+    const outPath = join(root, 'public', 'pages', 'group-mygroup-about.json');
+    expect(existsSync(outPath)).toBe(true);
+    const parsed = JSON.parse(readFileSync(outPath, 'utf8'));
+    expect(parsed.title).toBe('My Group');
+  });
+
+  it('skips silently when no about directories exist', async () => {
+    writeSiteConfig([{ id: 'lonely' }]);
+    // No .datasets, no localPath about/, no groups. The script runs to
+    // completion without throwing and produces no output pages.
+    await expect(runMain()).resolves.not.toThrow();
+    expect(existsSync(join(root, 'public', 'pages', 'dataset-lonely-about.json'))).toBe(false);
+  });
+});

package/scripts/build-edges.js

@@ -6,8 +6,8 @@
  * Usage: node scripts/build-edges.js
  */
 import { extractSourceRefs } from './extract-source-refs.js';
-import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
+import { readFileSync, writeFileSync, readdirSync, existsSync, realpathSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import yaml from 'js-yaml';
 import { Register } from 'glossarist';
@@ -252,6 +252,7 @@ function buildEdgesForDataset(datasetDir, registerId, uriBase, urnMap, manifest)
 }
 
 // Main
+export function main() {
 console.log('Building edge indexes...\n');
 
 if (!existsSync(DATA_DIR)) {
@@ -388,3 +389,10 @@ const refCount = Object.values(crossRefIndex).reduce((sum, arr) => sum + arr.len
 console.log(`Written cross-ref-index.json (${refCount} cross-references across ${datasets.length} datasets)`);
 
 console.log('Done.');
+}
+
+const isDirectInvocation = process.argv[1]
+  && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+if (isDirectInvocation) {
+  main();
+}

package/scripts/fetch-datasets.mjs

@@ -19,10 +19,9 @@ import path from 'path';
 import JSZip from 'jszip';
 import { loadGcr } from 'glossarist';
 import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
 import { loadSiteConfig } from './load-site-config.mjs';
-import { assertLocalPathSafe } from './lib/local-path-safety.mjs';
-
-const ROOT = process.cwd();
+import { assertLocalPathSafe } from './lib/local-path-safety.mjs';const ROOT = process.cwd();
 const DATASETS_DIR = path.join(ROOT, '.datasets');
 const GCR_DIR = path.join(ROOT, '.gcr');
 
@@ -136,68 +135,76 @@ function cloneOrUpdate(sourceRepo, targetDir) {
 // --- localPath safety check: see scripts/lib/local-path-safety.mjs ---
 
 // --- Main ---
-console.log('Fetching glossarist datasets...\n');
+export async function main() {
+  console.log('Fetching glossarist datasets...\n');
 
-const { config } = loadSiteConfig();
-const gcrMetadata = {};
+  const { config } = loadSiteConfig();
+  const gcrMetadata = {};
 
-for (const ds of config.datasets) {
-  console.log(`${ds.id}:`);
+  for (const ds of config.datasets) {
+    console.log(`${ds.id}:`);
 
-  const gcrPath = path.join(GCR_DIR, `${ds.id}.gcr`);
-  const targetDir = path.join(DATASETS_DIR, ds.id);
+    const gcrPath = path.join(GCR_DIR, `${ds.id}.gcr`);
+    const targetDir = path.join(DATASETS_DIR, ds.id);
 
-  try {
-    if (fs.existsSync(gcrPath)) {
-      console.log(`  Using local .gcr/${ds.id}.gcr`);
-      await extractGcr(gcrPath, targetDir);
-    } else if (ds.gcrPackage) {
-      console.log(`  Using GCR package: ${ds.gcrPackage}`);
-      try {
-        await downloadGcr(ds.gcrPackage, gcrPath);
-      } catch (e) {
-        console.warn(`  GCR download failed: ${e.message}`);
-        console.warn(`  Skipping ${ds.id}`);
+    try {
+      if (fs.existsSync(gcrPath)) {
+        console.log(`  Using local .gcr/${ds.id}.gcr`);
+        await extractGcr(gcrPath, targetDir);
+      } else if (ds.gcrPackage) {
+        console.log(`  Using GCR package: ${ds.gcrPackage}`);
+        try {
+          await downloadGcr(ds.gcrPackage, gcrPath);
+        } catch (e) {
+          console.warn(`  GCR download failed: ${e.message}`);
+          console.warn(`  Skipping ${ds.id}`);
+          console.log();
+          continue;
+        }
+        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 {
+        console.warn(`  No source configured, skipping`);
         console.log();
         continue;
       }
-      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 {
-      console.warn(`  No source configured, skipping`);
-      console.log();
-      continue;
-    }
 
-    // Read metadata for dependency validation (from GCR ZIP, not extracted dir)
-    const meta = await readGcrMetadata(gcrPath);
-    if (meta) {
-      gcrMetadata[ds.id] = meta;
-      console.log(`  ${meta.concept_count || '?'} concepts, ${meta.uri_prefix || 'no uri'}`);
+      // Read metadata for dependency validation (from GCR ZIP, not extracted dir)
+      const meta = await readGcrMetadata(gcrPath);
+      if (meta) {
+        gcrMetadata[ds.id] = meta;
+        console.log(`  ${meta.concept_count || '?'} concepts, ${meta.uri_prefix || 'no uri'}`);
+      }
+    } catch (e) {
+      console.warn(`  Failed: ${e.message}`);
+      console.warn(`  Skipping ${ds.id}`);
     }
-  } catch (e) {
-    console.warn(`  Failed: ${e.message}`);
-    console.warn(`  Skipping ${ds.id}`);
+    console.log();
   }
-  console.log();
-}
 
-// Dependency validation
-console.log('Validating dependencies...\n');
-const errors = validateDependencies(config, gcrMetadata);
-if (errors.length) {
-  console.error('Dependency validation FAILED:');
-  for (const err of errors) {
-    console.error(`  ✗ ${err}`);
+  // Dependency validation
+  console.log('Validating dependencies...\n');
+  const errors = validateDependencies(config, gcrMetadata);
+  if (errors.length) {
+    console.error('Dependency validation FAILED:');
+    for (const err of errors) {
+      console.error(`  ✗ ${err}`);
+    }
+    process.exit(1);
   }
-  process.exit(1);
+  console.log('All dependencies satisfied.\n');
+
+  console.log('Done.');
 }
-console.log('All dependencies satisfied.\n');
 
-console.log('Done.');
+const isDirectInvocation = process.argv[1]
+  && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+if (isDirectInvocation) {
+  await main();
+}

package/scripts/generate-data.mjs

@@ -13,6 +13,7 @@ import { buildAgentsTurtle } from './lib/agents-turtle.mjs';
 import { buildVersionHistoryTurtle } from './lib/version-turtle.mjs';
 import { buildBibliographyTurtle } from './lib/bibliography-turtle.mjs';
 import { ttlLit } from './lib/turtle-escape.mjs';
+import { firstNonEmpty } from './lib/first-non-empty.mjs';
 const __dirname = path.dirname(new URL(import.meta.url).pathname);
 const ROOT = process.cwd();
 const PUBLIC = path.join(ROOT, 'public');
@@ -1169,12 +1170,11 @@ for (let i = 0; i < config.datasets.length; i++) {
   // Use cached register
   const reg = registerCache[ds.id] || null;
 
-  // Resolve languages: register.yaml first, then site-config fallback
-  const dsLanguages = (reg?.languages?.length ? reg.languages : null)
-    || ds.languages
-    || ['eng'];
+  // Content fields: register-wins, site-config fallback. Layout-only
+  // fields (uri, color, gcrPackage) stay on site-config.
+  const dsLanguages = firstNonEmpty(reg?.languages, ds.languages, ['eng']);
 
-  // Resolve description: register.yaml first, then site-config
+  // Resolve description: register-wins (localized object), site-config fallback
   const defaultLang = dsLanguages[0] || 'eng';
   const regDesc = reg?.description;
   const dsDesc = ds.description;
@@ -1182,28 +1182,39 @@ for (let i = 0; i < config.datasets.length; i++) {
     ? regDesc[defaultLang] || Object.values(regDesc)[0] || ''
     : dsDesc || '';
 
-  // Resolve title: site-config override, then ref from register
-  const resolvedTitle = ds.title || reg?.ref || ds.id;
+  // Title: register.displayName wins (TODO.refactor/40 — Register.name
+  // is first-class in glossarist-js since v0.4.13). Site-config title
+  // is fallback, then ref (citation proxy), then id.
+  const resolvedTitle = reg?.displayName(defaultLang)
+    ?? ds.title
+    ?? reg?.ref
+    ?? ds.id;
 
   counts[ds.id] = await processDataset(dir, ds.id, {
     title: resolvedTitle,
     description: resolvedDescription,
-    owner: ds.owner || reg?.owner,
+    owner: firstNonEmpty(reg?.owner, ds.owner),
     languages: dsLanguages,
-    sourceRepo: ds.sourceRepo || reg?.sourceRepo,
-    languageOrder: ds.languageOrder || reg?.languageOrder,
-    ref: ds.ref || reg?.ref,
-    refAliases: ds.refAliases || reg?.refAliases,
-    tags: ds.tags || reg?.tags,
+    sourceRepo: firstNonEmpty(reg?.sourceRepo, ds.sourceRepo),
+    languageOrder: firstNonEmpty(reg?.languageOrder, ds.languageOrder),
+    ref: firstNonEmpty(reg?.ref, ds.ref),
+    refAliases: firstNonEmpty(reg?.refAliases, ds.refAliases),
+    tags: firstNonEmpty(reg?.tags, ds.tags),
     color: ds.color || DS_PALETTE[i % DS_PALETTE.length],
-    datasetUri: ds.uri || reg?.urn,
-    uriAliases: ds.uriAliases || reg?.urnAliases,
-    status: ds.editionStatus || reg?.status,
+    datasetUri: firstNonEmpty(reg?.urn, ds.uri),
+    uriAliases: firstNonEmpty(reg?.urnAliases, ds.uriAliases),
+    status: firstNonEmpty(reg?.status, ds.editionStatus),
     ordering: reg?.ordering || null,
     sections: reg?.sections ? reg.sections.map(s => s.toJSON()) : [],
     hasBibliography: fs.existsSync(path.join(datasetDir(ds), 'bibliography.yaml')),
     hasImages: fs.existsSync(path.join(datasetDir(ds), 'images')),
   });
+  const resolvedOwner = firstNonEmpty(reg?.owner, ds.owner) ?? '';
+  const resolvedTags = firstNonEmpty(reg?.tags, ds.tags) ?? [];
+  const resolvedDatasetUri = firstNonEmpty(reg?.urn, ds.uri);
+  const resolvedUriAliases = firstNonEmpty(reg?.urnAliases, ds.uriAliases);
+  const resolvedRef = firstNonEmpty(reg?.ref, ds.ref);
+  const resolvedRefAliases = firstNonEmpty(reg?.refAliases, ds.refAliases);
   registry.push({
     id: ds.id,
     manifestUrl: `/data/${ds.id}/manifest.json`,
@@ -1212,15 +1223,15 @@ for (let i = 0; i < config.datasets.length; i++) {
       description: resolvedDescription,
       conceptCount: counts[ds.id] || 0,
       languages: dsLanguages,
-      owner: ds.owner || reg?.owner || '',
-      tags: ds.tags || reg?.tags || [],
+      owner: resolvedOwner,
+      tags: resolvedTags,
       color: ds.color || DS_PALETTE[i % DS_PALETTE.length],
     },
-    datasetUri: ds.uri || reg?.urn || undefined,
+    datasetUri: resolvedDatasetUri,
     uriBase: config.uriBase || undefined,
-    uriAliases: ds.uriAliases || reg?.urnAliases || undefined,
-    ref: ds.ref || reg?.ref || undefined,
-    refAliases: ds.refAliases || reg?.refAliases || undefined,
+    uriAliases: resolvedUriAliases,
+    ref: resolvedRef,
+    refAliases: resolvedRefAliases,
   });
 }
 writeJson(path.join(PUBLIC, 'datasets.json'), registry);
@@ -1553,21 +1564,22 @@ for (const key of ['logo', 'footerLogo']) {
   }
 }
 
-// Build dataset translations map: merge site-config overrides with register.yaml descriptions
+// Build dataset translations map: register descriptions win, site-config fills gaps
 const datasetTranslations = {};
 for (const d of config.datasets) {
   const reg = registerCache[d.id];
   const translations = { ...d.translations };
 
-  // Merge register.yaml descriptions as translations
+  // Register descriptions are authoritative; site-config translations fill gaps
   if (reg?.description && typeof reg.description === 'object') {
     for (const [lang, desc] of Object.entries(reg.description)) {
       if (!translations[lang]) translations[lang] = {};
-      if (!translations[lang].description) translations[lang].description = desc;
+      translations[lang].description = desc;
     }
   }
 
-  // Merge register.yaml ref as translated title if not already set
+  // Title falls back to register.ref when site-config doesn't supply one
+  // (TODO.refactor/40 — replace ref with Register.name once it exists)
   if (reg?.ref) {
     const langs = reg.languages || [];
     for (const lang of langs) {

package/scripts/lib/first-non-empty.mjs

@@ -0,0 +1,19 @@
+/**
+ * Register-wins resolution for dataset content fields. Returns the
+ * first non-empty value among the arguments. Empty arrays and empty
+ * strings are treated as absent so a `[]` in register falls through
+ * to site-config.
+ *
+ * Used by generate-data.mjs to apply a single, uniform precedence
+ * rule across all dataset metadata fields (TODO.refactor/38).
+ */
+
+export function firstNonEmpty(...vals) {
+  for (const v of vals) {
+    if (v == null) continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    if (typeof v === 'string' && v === '') continue;
+    return v;
+  }
+  return undefined;
+}