@glossarist/concept-browser 0.7.114 → 0.7.116

package/scripts/lib/yaml-types.ts

@@ -0,0 +1,262 @@
+/**
+ * YAML author-format TypeScript interfaces.
+ *
+ * These types describe the YAML wire format that dataset authors write
+ * and that `scripts/generate-data.ts` reads. They are the author-facing
+ * contract — the complement to `src/adapters/jsonld-types.ts` (the
+ * browser-facing JSON-LD wire format).
+ *
+ * MECE boundary:
+ *   - yaml-types.ts  → INPUT to the build pipeline (what authors write)
+ *   - jsonld-types.ts → OUTPUT of the build pipeline (what the browser reads)
+ *   - model-bridge.ts → converts JSON-LD → glossarist-js Concept instances
+ *
+ * Model-driven: field names match the YAML keys authors actually write
+ * (snake_case for author-facing, camelCase for internal normalized form).
+ */
+
+// ── Content blocks ─────────────────────────────────────────────────────────
+
+export interface YamlContent {
+  content?: string;
+}
+
+// ── Terms / designations ──────────────────────────────────────────────────
+
+export interface YamlTerm {
+  type?: string;
+  designation?: string;
+  normative_status?: string;
+  origin?: YamlOrigin;
+  grammar_info?: YamlGrammarInfo[];
+  english?: string[];
+}
+
+export interface YamlOrigin {
+  source?: string;
+  ref?: string;
+  version?: string;
+}
+
+export interface YamlGrammarInfo {
+  gender?: string;
+  number?: string;
+  partOfSpeech?: string;
+  noun?: boolean;
+  verb?: boolean;
+  adj?: boolean;
+  adverb?: boolean;
+  preposition?: boolean;
+  participle?: boolean;
+}
+
+// ── Sources ───────────────────────────────────────────────────────────────
+
+export interface YamlSource {
+  origin?: YamlOrigin;
+  ref?: string;
+  link?: string;
+  relationship_type?: string;
+  status?: string;
+  title?: string;
+  type?: string;
+}
+
+// ── Dates ─────────────────────────────────────────────────────────────────
+
+export interface YamlDate {
+  type?: string;
+  date?: string;
+}
+
+// ── Relations ─────────────────────────────────────────────────────────────
+
+export interface YamlRelation {
+  type?: string;
+  target?: string | { ref?: string; uri?: string };
+  content?: string;
+  label?: string;
+}
+
+export interface YamlPartitiveMember {
+  ref?: string;
+  uri?: string;
+  presence?: string;
+  count?: string;
+  delimiting?: boolean;
+  multiplicity?: string;
+  certainty?: string;
+  designation?: string;
+  content?: string;
+}
+
+export interface YamlPartitiveRelation {
+  type?: string;
+  target?: string;
+  members?: YamlPartitiveMember[];
+  criterion?: string;
+  multiplicity?: string;
+  certainty?: string;
+}
+
+export interface YamlGenericRelation {
+  type?: string;
+  target?: string;
+  members?: (string | { ref?: string; uri?: string })[];
+  criterion?: string;
+}
+
+// ── Localization (per-language concept data) ──────────────────────────────
+
+export interface YamlLocalization {
+  language_code?: string;
+  terms?: YamlTerm[];
+  definition?: YamlContent[];
+  notes?: YamlContent[];
+  examples?: YamlContent[];
+  annotations?: YamlContent[];
+  sources?: YamlSource[];
+  dates?: YamlDate[];
+  domain?: string[];
+  references?: YamlSource[];
+  entry_status?: string;
+  classification?: string;
+  review_type?: string;
+  review_date?: string;
+  review_decision_date?: string;
+  review_decision_event?: string;
+  review_status?: string;
+  review_decision?: string;
+  review_decision_notes?: string;
+  lineage_source_similarity?: number;
+  release?: string;
+  script?: string;
+  system?: string;
+  [key: string]: unknown;
+}
+
+// ── Harmonized concept (output of loadConceptFile) ────────────────────────
+//
+// After loadConceptFile(), the concept is normalized to this shape
+// regardless of whether the source was simple or managed format.
+// The `_`-prefixed fields are managed-concept metadata hoisted to top level.
+
+export interface HarmonizedConcept {
+  termid: string;
+  id?: string;
+  uri?: string;
+  status?: string;
+  _related?: YamlRelation[];
+  _partitiveRelations?: YamlPartitiveRelation[];
+  _genericRelations?: YamlGenericRelation[];
+  _domains?: string[];
+  _dates?: YamlDate[];
+  _sources?: YamlSource[];
+  _status?: string;
+  _schemaVersion?: string;
+  _dateAccepted?: string;
+  [lang: string]: unknown;
+}
+
+// ── Managed concept YAML doc (multi-doc format) ───────────────────────────
+
+export interface YamlManagedConceptDoc {
+  data?: {
+    identifier?: string | number;
+    language_code?: string;
+    domains?: string[];
+    [key: string]: unknown;
+  };
+  related?: YamlRelation[];
+  partitive_relations?: YamlPartitiveRelation[];
+  generic_relations?: YamlGenericRelation[];
+  dates?: YamlDate[];
+  sources?: YamlSource[];
+  status?: string;
+  schema_version?: string;
+  date_accepted?: string;
+  terms?: YamlTerm[];
+  definition?: YamlContent[];
+  notes?: YamlContent[];
+  examples?: YamlContent[];
+  [key: string]: unknown;
+}
+
+// ── Dataset manifest ──────────────────────────────────────────────────────
+
+export interface YamlManifestSection {
+  id?: string;
+  slug?: string;
+  title?: string;
+  name?: string;
+  members?: string[];
+  children?: YamlManifestSection[];
+  ordering?: string;
+}
+
+export interface YamlManifest {
+  id?: string;
+  title?: string;
+  description?: string;
+  lastUpdated?: string;
+  sourceRepoUrl?: string;
+  publisher?: string;
+  contactPoint?: string;
+  sections?: YamlManifestSection[];
+  languageOrder?: string[];
+  ref?: Record<string, string>;
+  refAliases?: string[];
+  editionStatus?: string;
+  ordering?: string;
+  [key: string]: unknown;
+}
+
+// ── Bibliography ──────────────────────────────────────────────────────────
+
+export interface YamlBibliographyEntry {
+  reference?: string;
+  title?: string;
+  link?: string;
+  author?: string;
+  date?: string;
+  publisher?: string;
+  type?: string;
+  [key: string]: unknown;
+}
+
+// ── News/content frontmatter ──────────────────────────────────────────────
+
+export interface YamlNewsFrontmatter {
+  title?: string;
+  date?: string;
+  categories?: string;
+  [key: string]: unknown;
+}
+
+// ── Content page config ───────────────────────────────────────────────────
+
+export interface YamlContentPage {
+  route?: string;
+  source?: string;
+  title?: string;
+  translations?: Record<string, { source?: string; title?: string }>;
+  [key: string]: unknown;
+}
+
+// ── SHACL constraint (ontology schema) ────────────────────────────────────
+
+export interface ShaclConstraint {
+  path?: string | null;
+  datatype?: string | null;
+  class?: string | null;
+  valuesFrom?: string | null;
+  nodeKind?: string | null;
+  minCount?: number | null;
+  maxCount?: number | null;
+  in?: string[];
+  [key: string]: unknown;
+}
+
+// ── Prefix map (Turtle emission) ──────────────────────────────────────────
+
+export type PrefixMap = Record<string, string>;

package/scripts/load-site-config.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+// scripts/load-site-config.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import yaml from "js-yaml";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var projectRoot = resolve(__dirname, "..");
+var SNAKE_TO_CAMEL = {
+  // Site-level
+  uri_base: "uriBase",
+  base_path: "basePath",
+  ui_languages: "uiLanguages",
+  dataset_groups: "datasetGroups",
+  dataset_translations: "datasetTranslations",
+  primary_color: "primaryColor",
+  dark_color: "darkColor",
+  owner_name: "ownerName",
+  owner_url: "ownerUrl",
+  powered_by: "poweredBy",
+  footer_nav: "footerNav",
+  footer_logo: "footerLogo",
+  news_dir: "newsDir",
+  // Dataset-level
+  gcr_package: "gcrPackage",
+  source_repo: "sourceRepo",
+  local_path: "localPath",
+  local_light: "localLight",
+  local_dark: "localDark",
+  uri_aliases: "uriAliases",
+  language_order: "languageOrder",
+  ref_aliases: "refAliases",
+  urn_aliases: "urnAliases",
+  existing_site_url: "existingSiteUrl",
+  edition_status: "editionStatus",
+  dataset_uri: "datasetUri",
+  schema_version: "schemaVersion"
+};
+function normalizeKey(key) {
+  if (typeof key !== "string") return key;
+  if (Object.prototype.hasOwnProperty.call(SNAKE_TO_CAMEL, key)) {
+    return SNAKE_TO_CAMEL[key];
+  }
+  if (key.includes("_") && /^[a-z][a-z0-9_]*$/.test(key)) {
+    return key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  }
+  return key;
+}
+function normalizeObject(obj) {
+  if (Array.isArray(obj)) return obj.map(normalizeObject);
+  if (obj && typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[normalizeKey(k)] = normalizeObject(v);
+    }
+    return out;
+  }
+  return obj;
+}
+function findConfigFile(args = []) {
+  if (process.env.SITE_CONFIG) {
+    return resolve(process.env.SITE_CONFIG);
+  }
+  for (const dir of [process.cwd(), projectRoot]) {
+    const p = resolve(dir, "site-config.yml");
+    if (existsSync(p)) return p;
+  }
+  throw new Error("No site config found. Set SITE_CONFIG or create site-config.yml");
+}
+function loadSiteConfig(args = []) {
+  const configPath = findConfigFile(args);
+  const raw = yaml.load(readFileSync(configPath, "utf-8"));
+  const config = normalizeObject(raw);
+  return { config, configPath };
+}
+function getProjectRoot() {
+  return projectRoot;
+}
+export {
+  getProjectRoot,
+  loadSiteConfig
+};

package/scripts/migrate-v1-to-v3.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+// scripts/migrate-v1-to-v3.ts
+import fs from "fs";
+import path from "path";
+function isV1PartitiveRelation(rel) {
+  return rel && Array.isArray(rel.parts);
+}
+function migrateRelation(rel) {
+  if (!isV1PartitiveRelation(rel)) return null;
+  return {
+    comprehensive: rel.comprehensive,
+    completeness: rel.enumeration === "open" ? "partial" : rel.enumeration === "closed" || rel.enumeration == null ? "complete" : rel.enumeration,
+    partitives: (rel.parts ?? []).map((p) => ({
+      ref: p,
+      certainty: "confirmed"
+    })),
+    ...rel.content ? { content: rel.content } : {}
+  };
+}
+function migrateConceptData(data) {
+  if (!data?.partitive_relations?.length) return null;
+  const migrated = data.partitive_relations.map(migrateRelation).filter((r) => r !== null);
+  if (migrated.length === 0) return null;
+  return { ...data, partitive_relations: migrated };
+}
+function isAlreadyMigrated(content) {
+  return Boolean(content?.data?.partitive_relations?.some?.((rel) => Array.isArray(rel.partitives)));
+}
+function walkFiles(input) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return [input];
+  const out = [];
+  for (const entry of fs.readdirSync(input, { withFileTypes: true })) {
+    const full = path.join(input, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(full));
+    else if (entry.isFile() && /\.(ya?ml)$/i.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+async function loadYamlModule() {
+  try {
+    return await import("js-yaml");
+  } catch {
+    return null;
+  }
+}
+function outputPath(input, file, outRoot) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return outRoot;
+  const rel = path.relative(input, file);
+  return path.join(outRoot, rel);
+}
+async function migrateFile(input, file, options, yaml) {
+  const raw = fs.readFileSync(file, "utf8");
+  const parsed = yaml ? yaml.load(raw) : JSON.parse(raw);
+  if (!parsed?.data) return { changed: false };
+  if (isAlreadyMigrated(parsed)) return { changed: false, skipped: true };
+  const migrated = migrateConceptData(parsed.data);
+  if (!migrated) return { changed: false };
+  parsed.data = { ...parsed.data, ...migrated };
+  const out = outputPath(input, file, options.out);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const outText = yaml ? yaml.dump(parsed) : JSON.stringify(parsed, null, 2);
+  if (!options.dryRun) fs.writeFileSync(out, outText);
+  return { changed: true, out, in: file };
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const opts = { in: null, out: null, dryRun: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--in") opts.in = args[++i];
+    else if (a === "--out") opts.out = args[++i];
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (!opts.in) opts.in = a;
+    else if (!opts.out) opts.out = a;
+  }
+  if (!opts.in) {
+    console.error("Usage: node scripts/migrate-v1-to-v3.mjs --in <dir|file> [--out <dir|file>] [--dry-run]");
+    process.exit(1);
+  }
+  if (!opts.out) opts.out = opts.dryRun ? opts.in : `${opts.in}.v3`;
+  const yaml = await loadYamlModule();
+  if (!yaml) {
+    console.error("js-yaml is required; install via npm install js-yaml");
+    process.exit(1);
+  }
+  const files = walkFiles(opts.in);
+  let changed = 0, skipped = 0, total = 0;
+  for (const f of files) {
+    total++;
+    const res = await migrateFile(opts.in, f, opts, yaml);
+    if (res.changed) {
+      changed++;
+      console.log(`\u2713 ${res.in} \u2192 ${res.out}`);
+    } else if (res.skipped) {
+      skipped++;
+    }
+  }
+  console.log(`
+${changed} migrated, ${skipped} skipped (already v3), ${total - changed - skipped} unchanged.`);
+  if (opts.dryRun) console.log("(dry-run \u2014 no files written)");
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+export {
+  isAlreadyMigrated,
+  isV1PartitiveRelation,
+  migrateConceptData,
+  migrateRelation
+};

package/scripts/normalize-yaml.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// scripts/normalize-yaml.ts
+import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, extname, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+var ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+var YAML_EXTS = /* @__PURE__ */ new Set([".yaml", ".yml"]);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist"]);
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      out.push(...walk(full));
+    } else if (YAML_EXTS.has(extname(entry))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+function normalizeYaml({ root = ROOT, check = false, paths = [] } = {}) {
+  const searchDirs = paths.length > 0 ? paths.map((p) => join(root, p)) : [join(root, ".datasets")];
+  const files = [];
+  for (const dir of searchDirs) {
+    try {
+      statSync(dir);
+    } catch {
+      continue;
+    }
+    files.push(...walk(dir));
+  }
+  files.sort();
+  let checked = 0;
+  let nonNfc = 0;
+  const fixed = [];
+  for (const file of files) {
+    const original = readFileSync(file, "utf8");
+    checked++;
+    if (!isNfc(original)) {
+      nonNfc++;
+      if (!check) {
+        writeFileSync(file, original.normalize("NFC"), "utf8");
+        fixed.push(relative(root, file));
+      } else {
+        fixed.push(relative(root, file));
+      }
+    }
+  }
+  return { checked, nonNfc, fixed, check };
+}
+function isNfc(s) {
+  return s === s.normalize("NFC");
+}
+function main() {
+  const args = process.argv.slice(2);
+  const check = args.includes("--check");
+  const paths = args.filter((a) => !a.startsWith("-") && a !== "normalize");
+  const { checked, nonNfc, fixed } = normalizeYaml({ check, paths });
+  if (check) {
+    if (nonNfc === 0) {
+      process.stdout.write(`NFC OK: ${checked} file(s) checked, all normalized
+`);
+      return;
+    }
+    process.stderr.write(`NFC check failed: ${nonNfc} of ${checked} file(s) are not NFC-normalized
+
+`);
+    for (const f of fixed) {
+      process.stderr.write(`  ${f}
+`);
+    }
+    process.exit(1);
+  } else {
+    if (nonNfc === 0) {
+      process.stdout.write(`NFC OK: ${checked} file(s) checked, all already normalized
+`);
+      return;
+    }
+    process.stdout.write(`Normalized ${nonNfc} of ${checked} file(s)
+`);
+    for (const f of fixed) {
+      process.stdout.write(`  ${f}
+`);
+    }
+  }
+}
+var isDirectEntry = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isDirectEntry) {
+  main();
+}
+export {
+  normalizeYaml
+};