@glossarist/concept-browser 0.7.114 → 0.7.116

package/README.md

@@ -39,14 +39,57 @@ Your project (CWD)                    Package (read-only)
 │   └── my-vocab/             ─┤     ┌──────────────────────────┐
 │       └── concepts/*.yaml   ─┤     │ @glossarist/concept-browser │
 ├── public/                   ─┤ ──> │                          │
-│   └── (logos, favicons)     ─┤     │ generate-data.mjs        │
-├── .cb-content/   ← generated │     │ bridge-to-astro.mjs      │
+│   └── (logos, favicons)     ─┤     │ generate-data.ts         │
+├── .cb-content/   ← generated │     │ bridge-to-astro.ts       │
 └── dist/          ← output    │     │ astro build              │
                              ──┘     └──────────────────────────┘
 ```
 
 The package reads your config and data, generates `.cb-content/` (content collections) and `dist/` (static site) in your project. The package itself (`node_modules/`) is never modified.
 
+## Data / Deployment Boundary
+
+There is a strict separation between **dataset authors** and **deployers**:
+
+| Role | Owns | Does NOT touch |
+|------|------|----------------|
+| **Dataset author** | YAML concept files, bibliography, figures/tables | site-config.yml, deployment URLs, other datasets |
+| **Deployer** | site-config.yml, URI patterns, branding, fonts | dataset content, inline references, concept IDs |
+| **concept-browser** | Resolves every citation at runtime | — |
+
+The same dataset YAML works in any deployment. A citation like `{{cite:iso704}}` resolves differently depending on which datasets are co-deployed — the deployer's `site-config.yml:uriPatterns` decides.
+
+## Inline Content Syntax
+
+All inline references in concept text use the unified `{{kind:target}}` notation:
+
+| Kind | Syntax | Example | Description |
+|------|--------|---------|-------------|
+| cite | `{{cite:sourceId}}` | `{{cite:iso7301}}` | Cite a ConceptSource from this concept's `sources[]` |
+| cite+label | `{{cite:id, label}}` | `{{cite:iso7301, rice}}` | Same, with explicit display label |
+| urn | `{{urn:URN}}` | `{{urn:iso:std:iso:704}}` | Reference via URN routing |
+| fig | `{{fig:id}}` | `{{fig:diagram_3}}` | Reference a figure entity |
+| table | `{{table:id}}` | `{{table:unit_list}}` | Reference a table entity |
+| formula | `{{formula:id}}` | `{{formula:ohm_law}}` | Reference a formula entity |
+| bib | `{{bib:id}}` | `{{bib:ref_1}}` | Bibliography entry (no underlying concept) |
+| link | `{{link:URL}}` | `{{link:https://example.com}}` | External URL |
+| link+label | `{{link:URL, label}}` | `{{link:https://example.com, click here}}` | External URL with label |
+| image | `{{image:src}}` | `{{image:diagram.png}}` | Inline image embed |
+| image+alt | `{{image:src, alt}}` | `{{image:diagram.png, The diagram}}` | Image with alt text |
+| designation | `{{designation}}` | `{{measurement unit}}` | Reference by designation text |
+| numeric | `{{numeric_id}}` | `{{112-01-10}}` | Reference by numeric ID |
+
+The deprecated `<<ref,title>>` AsciiDoc xref syntax still works but emits a console warning. Migrate to the unified syntax.
+
+### Citation Resolution Cascade
+
+When concept-browser encounters `{{cite:sourceId}}`, it walks this cascade:
+
+1. **uriPatterns** — Is there a co-deployed dataset matching this URI? → internal link
+2. **routing[]** — Is there a routing entry in site-config.yml? → external link
+3. **citation.link** — Does the source have a canonical link? → flat bibliography record
+4. **unresolved** — No match → plain text
+
 ## Configuration
 
 Everything is in `site-config.yml`. See [`site-config.example.yml`](site-config.example.yml) for all options.

package/cli/index.mjs

@@ -3,15 +3,12 @@
 /**
  * Glossarist Concept Browser CLI — runtime entrypoint.
  *
- * This is the published bin entry. It stays as plain JS (no tsx dependency)
- * so consumers who install with --omit=dev can use it.
- *
- * The TypeScript version lives at cli/index.ts for type-checking during
- * development. The two files should be kept in sync manually until
- * TODO.typescript/03 adds a compile step.
+ * Imports compiled .js scripts (not .ts) because Node.js v24+ blocks
+ * type stripping for files under node_modules. Scripts are compiled
+ * to .js by `npm run build:scripts` during prepublishOnly.
  */
 
-import { loadSiteConfig } from '../scripts/load-site-config.mjs';
+import { loadSiteConfig } from '../scripts/load-site-config.js';
 import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -20,10 +17,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 
 const commands = {
-  fetch:    async () => (await import('../scripts/fetch-datasets.mjs')).main(),
-  generate: async () => { await import('../scripts/generate-data.mjs'); },
+  fetch:    async () => (await import('../scripts/fetch-datasets.js')).main(),
+  generate: async () => { await import('../scripts/generate-data.js'); },
   edges:    async () => (await import('../scripts/build-edges.js')).main(),
-  about:    async () => (await import('../scripts/process-about-pages.mjs')).main(),
+  about:    async () => (await import('../scripts/process-about-pages.js')).main(),
 };
 
 function parseArgs(argv) {
@@ -294,7 +291,7 @@ Environment:
     }
 
     console.log(`\n=== BRIDGE DATA ===\n`);
-    const bridge = resolve(pkgRoot, 'scripts', 'bridge-to-astro.mjs');
+    const bridge = resolve(pkgRoot, 'scripts', 'bridge-to-astro.js');
     if (existsSync(bridge)) {
       await import(`file://${bridge}`);
     }
@@ -334,7 +331,7 @@ Environment:
   }
 
   if (cmd === 'normalize') {
-    const { normalizeYaml } = await import('../scripts/normalize-yaml.mjs');
+    const { normalizeYaml } = await import('../scripts/normalize-yaml.js');
     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 });
@@ -357,7 +354,7 @@ Environment:
   }
 
   if (cmd === 'doctor') {
-    const { main: doctorMain } = await import('../scripts/doctor.mjs');
+    const { main: doctorMain } = await import('../scripts/doctor.js');
     await doctorMain();
     return;
   }

package/cli/index.ts

@@ -21,10 +21,7 @@
  *   GITHUB_TOKEN         GitHub token for private repos
  */
 
-// Scripts are still .mjs (TODO.typescript/02). These imports will be fully
-// typed once the scripts convert to .ts.
-// @ts-expect-error — .mjs module without declaration
-import { loadSiteConfig } from '../scripts/load-site-config.mjs';
+import { loadSiteConfig } from '../scripts/load-site-config';
 import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -40,10 +37,11 @@ interface ParsedArgs {
 type CommandRunner = () => Promise<void>;
 
 const commands: Record<string, CommandRunner> = {
-  fetch:    async () => (await import('../scripts/fetch-datasets.mjs' as string)).main(),
-  generate: async () => { await import('../scripts/generate-data.mjs' as string); },
-  edges:    async () => (await import('../scripts/build-edges.js' as string)).main(),
-  about:    async () => (await import('../scripts/process-about-pages.mjs' as string)).main(),
+  fetch:        async () => (await import('../scripts/fetch-datasets')).main(),
+  generate:     async () => { await import('../scripts/generate-data'); },
+  edges:        async () => (await import('../scripts/build-edges')).main(),
+  about:        async () => (await import('../scripts/process-about-pages')).main(),
+  'validate-yaml': async () => { await import('../scripts/validate-yaml'); },
 };
 
 function parseArgs(argv: readonly string[]): ParsedArgs {
@@ -308,7 +306,7 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
   }
 
   console.log(`\n=== BRIDGE DATA ===\n`);
-  const bridge: string = resolve(pkgRoot, 'scripts', 'bridge-to-astro.mjs');
+  const bridge: string = resolve(pkgRoot, 'scripts', 'bridge-to-astro.ts');
   if (existsSync(bridge)) {
     await import(`file://${bridge}`);
   }
@@ -341,7 +339,7 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
 }
 
 async function runNormalize(): Promise<void> {
-  const mod = await import('../scripts/normalize-yaml.mjs' as string);
+  const mod = await import('../scripts/normalize-yaml');
   const normalizeYaml = mod.normalizeYaml;
   const check: boolean = process.argv.includes('--check');
   const paths: string[] = process.argv.slice(2).filter(a => !a.startsWith('-') && a !== 'normalize');
@@ -414,7 +412,7 @@ Environment:
   }
 
   if (cmd === 'doctor') {
-    const mod = await import('../scripts/doctor.mjs' as string);
+    const mod = await import('../scripts/doctor');
     await mod.main();
     return;
   }

package/data/concept-model/shapes/glossarist.concept.yaml.schema.json

@@ -0,0 +1,255 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://glossarist.org/concept-model/shapes/glossarist.concept.yaml.schema.json",
+  "title": "Glossarist Concept YAML",
+  "description": "Schema for dataset author YAML files. Derived from scripts/lib/yaml-types.ts — the TypeScript interfaces are the source of truth.",
+  "type": "object",
+  "required": ["termid"],
+  "properties": {
+    "termid": {
+      "type": "string",
+      "description": "Unique concept identifier within the dataset"
+    },
+    "id": { "type": "string" },
+    "uri": { "type": "string", "format": "uri" },
+    "status": {
+      "type": "string",
+      "enum": ["valid", "not_valid", "withdrawn", "draft", "superseded"]
+    },
+    "_related": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/relation" }
+    },
+    "_partitiveRelations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/partitiveRelation" }
+    },
+    "_genericRelations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/genericRelation" }
+    },
+    "_domains": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "_dates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/date" }
+    },
+    "_sources": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/source" }
+    },
+    "_status": { "type": "string" },
+    "_schemaVersion": { "type": "string" },
+    "_dateAccepted": { "type": "string", "format": "date" }
+  },
+  "patternProperties": {
+    "^[a-z]{3}$": { "$ref": "#/$defs/localization" }
+  },
+  "additionalProperties": true,
+
+  "$defs": {
+    "localization": {
+      "type": "object",
+      "properties": {
+        "language_code": { "type": "string", "pattern": "^[a-z]{3}$" },
+        "terms": { "type": "array", "items": { "$ref": "#/$defs/term" } },
+        "definition": { "type": "array", "items": { "$ref": "#/$defs/content" } },
+        "notes": { "type": "array", "items": { "$ref": "#/$defs/content" } },
+        "examples": { "type": "array", "items": { "$ref": "#/$defs/content" } },
+        "annotations": { "type": "array", "items": { "$ref": "#/$defs/content" } },
+        "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
+        "dates": { "type": "array", "items": { "$ref": "#/$defs/date" } },
+        "domain": { "type": "array", "items": { "type": "string" } },
+        "entry_status": {
+          "type": "string",
+          "enum": ["valid", "not_valid", "withdrawn", "draft", "superseded"]
+        },
+        "classification": { "type": "string" },
+        "release": { "type": "string" }
+      }
+    },
+
+    "term": {
+      "type": "object",
+      "required": ["designation"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["expression", "abbreviation", "symbol", "letter_symbol", "graphical symbol"]
+        },
+        "designation": { "type": "string" },
+        "normative_status": {
+          "type": "string",
+          "enum": ["preferred", "admitted", "deprecated", ""]
+        },
+        "origin": { "$ref": "#/$defs/origin" },
+        "grammar_info": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/grammarInfo" }
+        },
+        "international": { "type": "boolean" },
+        "absent": { "type": "boolean" },
+        "geographical_area": { "type": "string" },
+        "term_type": { "type": "string" },
+        "prefix": { "type": "string" },
+        "usage_info": { "type": "string" },
+        "field_of_application": { "type": "string" }
+      }
+    },
+
+    "content": {
+      "type": "object",
+      "properties": {
+        "content": { "type": "string" }
+      }
+    },
+
+    "source": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["authoritative", "lineage", "adapted"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["identical", "modified", "restyled", "context-added", "extracted", "expanded-coverage"]
+        },
+        "origin": { "$ref": "#/$defs/origin" }
+      }
+    },
+
+    "origin": {
+      "type": "object",
+      "properties": {
+        "ref": {
+          "type": "object",
+          "properties": {
+            "source": { "type": "string" },
+            "id": { "type": "string" },
+            "version": { "type": "string" },
+            "text": { "type": "string" }
+          }
+        },
+        "locality": {
+          "type": "object",
+          "properties": {
+            "type": { "type": "string" },
+            "reference_from": { "type": "string" },
+            "reference_to": { "type": "string" }
+          }
+        },
+        "link": { "type": "string", "format": "uri" }
+      }
+    },
+
+    "grammarInfo": {
+      "type": "object",
+      "properties": {
+        "gender": { "type": "string" },
+        "number": { "type": "string" },
+        "partOfSpeech": { "type": "string" },
+        "noun": { "type": "boolean" },
+        "verb": { "type": "boolean" },
+        "adj": { "type": "boolean" },
+        "adverb": { "type": "boolean" },
+        "preposition": { "type": "boolean" },
+        "participle": { "type": "boolean" }
+      }
+    },
+
+    "date": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "date": { "type": "string", "format": "date" }
+      }
+    },
+
+    "relation": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "target": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "ref": { "type": "string" },
+                "uri": { "type": "string", "format": "uri" }
+              }
+            }
+          ]
+        },
+        "content": { "type": "string" },
+        "label": { "type": "string" }
+      }
+    },
+
+    "partitiveRelation": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "target": { "type": "string" },
+        "members": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/partitiveMember" }
+        },
+        "criterion": { "type": "string" },
+        "multiplicity": {
+          "type": "string",
+          "enum": ["compulsory", "optional", "compulsory_multiple", "optional_multiple", "compulsory_at_least_one"]
+        }
+      }
+    },
+
+    "partitiveMember": {
+      "type": "object",
+      "properties": {
+        "ref": { "type": "string" },
+        "uri": { "type": "string", "format": "uri" },
+        "presence": {
+          "type": "string",
+          "enum": ["required", "optional"]
+        },
+        "count": {
+          "type": "string",
+          "enum": ["exactly_one", "at_least_one", "multiple"]
+        },
+        "delimiting": { "type": "boolean" },
+        "multiplicity": {
+          "type": "string",
+          "enum": ["compulsory", "optional", "compulsory_multiple", "optional_multiple", "compulsory_at_least_one"]
+        }
+      }
+    },
+
+    "genericRelation": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "target": { "type": "string" },
+        "members": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "ref": { "type": "string" },
+                  "uri": { "type": "string", "format": "uri" }
+                }
+              }
+            ]
+          }
+        },
+        "criterion": { "type": "string" }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.114",
+  "version": "0.7.116",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -9,22 +9,25 @@
   "scripts": {
     "dev": "vite",
     "build": "vue-tsc --noEmit && vite build",
-    "postbuild": "node scripts/generate-404.js",
+    "postbuild": "tsx scripts/generate-404.ts",
     "preview": "vite preview",
-    "check:scripts": "node scripts/check-syntax.mjs",
-    "pretest": "node scripts/check-syntax.mjs",
-    "prebuild": "node scripts/check-syntax.mjs",
-    "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",
+    "check:scripts": "tsx scripts/check-syntax.ts",
+    "validate:yaml": "tsx scripts/validate-yaml.ts",
+    "validate:shacl": "tsx scripts/validate-shacl.ts",
+    "pretest": "tsx scripts/check-syntax.ts",
+    "prebuild": "tsx scripts/check-syntax.ts",
+    "fetch-datasets": "tsx scripts/fetch-datasets.ts",
+    "generate-data": "tsx scripts/generate-data.ts",
+    "generate-ontology": "tsx scripts/generate-ontology-data.ts && tsx scripts/generate-ontology-schema.ts",
+    "sync:model": "tsx scripts/sync-concept-model.ts",
+    "build:full": "npm run generate-ontology && npm run fetch-datasets && npm run generate-data && tsx scripts/build-edges.ts && npm run build",
     "build:site": "concept-browser --site build",
-    "smoke": "node scripts/smoke.mjs",
+    "build:scripts": "node scripts/build-scripts.mjs",
+    "prepublishOnly": "npm run build:scripts",
+    "smoke": "tsx scripts/smoke.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "mutation:test": "stryker run stryker.config.mjs",
-    "validate:shacl": "node scripts/validate-shacl.mjs",
     "dev:astro": "astro dev",
     "build:astro": "astro build",
     "preview:astro": "astro preview"
@@ -44,6 +47,7 @@
     "pinia": "^2.3.1",
     "sharp": "^0.34.5",
     "tailwindcss": "^4.3.2",
+    "tsx": "^4.23.4",
     "vite": "^8.1.4",
     "vue": "^3.5.13",
     "vue-router": "^4.5.1"
@@ -55,6 +59,8 @@
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/d3": "^7.4.3",
     "@types/n3": "^1.26.1",
+    "esbuild": "^0.28.1",
+    "glob": "^10.5.0",
     "@vue/test-utils": "^2.4.8",
     "fast-check": "^4.8.0",
     "happy-dom": "^20.9.0",

package/scripts/__tests__/{bibliography.test.mjs → bibliography.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { normalizeBibliography } from '../lib/bibliography.mjs';
+import { normalizeBibliography } from '../lib/bibliography';
 
 describe('normalizeBibliography', () => {
   it('wraps a bare array into { bibliography: [...] }', () => {

package/scripts/__tests__/{cli-script-contract.test.mjs → cli-script-contract.test.ts}

@@ -13,9 +13,9 @@ import { resolve, dirname } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const SCRIPT_PATHS = [
-  '../../scripts/fetch-datasets.mjs',
-  '../../scripts/build-edges.js',
-  '../../scripts/process-about-pages.mjs',
+  '../../scripts/fetch-datasets.ts',
+  '../../scripts/build-edges.ts',
+  '../../scripts/process-about-pages.ts',
 ];
 
 describe('CLI script contract: every script exports main()', () => {

package/scripts/__tests__/{concept-groups.test.mjs → concept-groups.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getGroups } from '../lib/concept-groups.mjs';
+import { getGroups } from '../lib/concept-groups';
 
 describe('getGroups', () => {
   it('returns explicit eng.groups when present', () => {

package/scripts/__tests__/{doctor.test.mjs → doctor.test.ts}

@@ -3,7 +3,7 @@ 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';
+import { runDoctor, formatResults, CHECKS, NODE_MIN_MAJOR } from '../doctor';
 
 function makeTmpProject() {
   const dir = mkdtempSync(join(tmpdir(), 'doctor-'));

package/scripts/__tests__/{fetch-datasets.test.mjs → fetch-datasets.test.ts}

@@ -2,7 +2,7 @@ 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';
+import { assertLocalPathSafe } from '../lib/local-path-safety';
 
 function makeTmpTree() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cb-fetch-'));

package/scripts/__tests__/{first-non-empty.test.mjs → first-non-empty.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { firstNonEmpty } from '../lib/first-non-empty.mjs';
+import { firstNonEmpty } from '../lib/first-non-empty';
 
 describe('firstNonEmpty — register-wins resolution', () => {
   it('returns the first value when both are present (register wins)', () => {

package/scripts/__tests__/{process-about-pages.test.mjs → process-about-pages.test.ts}

@@ -4,7 +4,7 @@ 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');
+const scriptPath = join(dirname(new URL(import.meta.url).pathname), '..', 'process-about-pages');
 
 // Process-about-pages discovers per-dataset about content from either
 // .datasets/<id>/about/ (fetched) OR site-config localPath overrides.