glossarist 0.4.39 → 0.4.41

package/src/models/relation-categories.ts

@@ -0,0 +1,167 @@
+// Categorization SSOT for the 52 glossarist relationship types.
+
+import { RELATIONSHIP_TYPES } from './related-concept.js';
+
+export interface CategoryDefinition {
+  label: string;
+  description: string;
+  types: ReadonlyArray<string>;
+}
+
+type CategoryKey =
+  | 'lifecycle'
+  | 'hierarchical'
+  | 'associative'
+  | 'comparative'
+  | 'spatiotemporal'
+  | 'lexical'
+  | 'mapping'
+  | 'definitional';
+
+/**
+ * Each type in RELATIONSHIP_TYPES belongs to exactly one category. The
+ * categories mirror the concept-model taxonomy. Adding a new type
+ * means adding a taxonomy entry — no code changes here.
+ */
+export const RELATION_CATEGORIES: Readonly<Record<CategoryKey, CategoryDefinition>> = Object.freeze({
+  lifecycle: Object.freeze({
+    label: 'Lifecycle',
+    description: 'Concept lifecycle transitions: supersession, deprecation, replacement.',
+    types: Object.freeze([
+      'deprecates', 'deprecated_by',
+      'supersedes', 'superseded_by',
+      'replaces', 'replaced_by',
+      'invalidates', 'invalidated_by',
+      'retires', 'retired_by',
+    ]),
+  }) as CategoryDefinition,
+
+  hierarchical: Object.freeze({
+    label: 'Hierarchical',
+    description: 'Broader/narrower relations, including SKOS and ISO 25964 generic/partitive/instantial.',
+    types: Object.freeze([
+      'broader', 'narrower',
+      'broader_generic', 'narrower_generic',
+      'broader_partitive', 'narrower_partitive',
+      'broader_instantial', 'narrower_instantial',
+    ]),
+  }) as CategoryDefinition,
+
+  associative: Object.freeze({
+    label: 'Associative',
+    description: 'Generic see-also references between concepts.',
+    types: Object.freeze([
+      'see', 'related_concept',
+      'related_concept_broader', 'related_concept_narrower',
+      'references',
+    ]),
+  }) as CategoryDefinition,
+
+  comparative: Object.freeze({
+    label: 'Comparative',
+    description: 'Compare / contrast relations between concepts.',
+    types: Object.freeze(['compare', 'contrast']),
+  }) as CategoryDefinition,
+
+  spatiotemporal: Object.freeze({
+    label: 'Spatiotemporal',
+    description: 'Sequential, spatial, and temporal relations.',
+    types: Object.freeze([
+      'sequentially_related_concept',
+      'spatially_related_concept',
+      'temporally_related_concept',
+    ]),
+  }) as CategoryDefinition,
+
+  lexical: Object.freeze({
+    label: 'Lexical',
+    description: 'Lexical relations between designations across languages.',
+    types: Object.freeze(['homograph', 'false_friend']),
+  }) as CategoryDefinition,
+
+  mapping: Object.freeze({
+    label: 'Mapping',
+    description: 'SKOS mapping properties for cross-vocabulary alignment.',
+    types: Object.freeze([
+      'equivalent', 'close_match',
+      'broad_match', 'narrow_match', 'related_match',
+    ]),
+  }) as CategoryDefinition,
+
+  definitional: Object.freeze({
+    label: 'Definitional',
+    description: 'ISO 19135 concept-to-concept relations: definition, part, instance, inheritance, versioning.',
+    types: Object.freeze([
+      'has_concept', 'is_concept_of',
+      'instance_of', 'has_instance',
+      'has_definition', 'definition_of',
+      'has_part', 'is_part_of',
+      'inherits', 'inherited_by',
+      'has_version', 'version_of',
+      'current_version', 'current_version_of',
+      'provides', 'provided_by',
+    ]),
+  }) as CategoryDefinition,
+});
+
+const _CATEGORY_BY_TYPE: ReadonlyMap<string, string> = (() => {
+  const map = new Map<string, string>();
+  for (const [cat, def] of Object.entries(RELATION_CATEGORIES)) {
+    for (const t of def.types) map.set(t, cat);
+  }
+  return map;
+})();
+
+const _CATEGORY_ALIASES: Readonly<Record<string, string>> = {
+  conceptInstance: 'definitional',
+  versioning: 'definitional',
+};
+
+/**
+ * Returns the category key for the given relationship type, or null
+ * when the type is not categorized.
+ */
+export function categoryOf(type: string): string | null {
+  return _CATEGORY_BY_TYPE.get(type) ?? null;
+}
+
+/**
+ * Returns the category definition for the given category key.
+ * Accepts both canonical names (definitional) and aliases from
+ * earlier glossarist-js versions.
+ */
+export function categoryDefinition(categoryKey: string): CategoryDefinition | null {
+  const canonical = _CATEGORY_ALIASES[categoryKey] ?? categoryKey;
+  return (RELATION_CATEGORIES as Readonly<Record<string, CategoryDefinition>>)[canonical] ?? null;
+}
+
+/**
+ * MECE sanity check. Returns the list of relationship types that are
+ * NOT categorized.
+ */
+export function uncategorizedTypes(): string[] {
+  return RELATIONSHIP_TYPES.filter((t) => !_CATEGORY_BY_TYPE.has(t));
+}
+
+/**
+ * MECE sanity check. Returns a list of { type, count } entries for any
+ * type that appears in MORE than one category.
+ */
+export function duplicatedTypes(): ReadonlyArray<{ type: string; count: number }> {
+  const counts = new Map<string, number>();
+  for (const def of Object.values(RELATION_CATEGORIES)) {
+    for (const t of def.types) {
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+  }
+  const out: { type: string; count: number }[] = [];
+  for (const [type, count] of counts) {
+    if (count > 1) out.push({ type, count });
+  }
+  return out;
+}
+
+export {
+  RELATION_CATEGORIES as RELATION_CATEGORIES_READONLY,
+  type CategoryKey as RelationCategoryKey,
+};

package/src/models/{relation-colors.js → relation-colors.ts}

@@ -6,10 +6,27 @@
 
 import { categoryOf, categoryDefinition } from './relation-categories.js';
 
-// One { light, dark } pair per category. Keeping these in glossarist-js
-// lets the defaults ship with the library; consumers only need to
-// customize when they want to deviate.
-export const RELATION_COLOR_DEFAULTS = Object.freeze({
+export interface ColorPair {
+  light: string;
+  dark: string;
+}
+
+export interface RelationColorPalette {
+  byCategory: Readonly<Record<string, ColorPair>>;
+  byType: Readonly<Record<string, ColorPair>>;
+}
+
+export interface ResolveRelationColorOptions {
+  overrides?: Partial<RelationColorPalette>;
+  mode?: 'light' | 'dark';
+}
+
+/**
+ * One { light, dark } pair per category. Keeping these in glossarist-js
+ * lets the defaults ship with the library; consumers only need to
+ * customize when they want to deviate.
+ */
+export const RELATION_COLOR_DEFAULTS: RelationColorPalette = Object.freeze({
   byCategory: Object.freeze({
     lifecycle:      { light: '#B43A2E', dark: '#F87171' },
     hierarchical:   { light: '#1F6FEB', dark: '#6EA8FE' },
@@ -19,39 +36,32 @@ export const RELATION_COLOR_DEFAULTS = Object.freeze({
     lexical:        { light: '#D97706', dark: '#FBBF24' },
     mapping:        { light: '#2563EB', dark: '#93BBFD' },
     definitional:   { light: '#65A30D', dark: '#A3E635' },
-  }),
-
-  // Per-type overrides. Use the same { light, dark } shape. Keys are
-  // relationship-type local names. Empty by default — consumers may
-  // populate this through `overrides.byType` at call time.
-  byType: Object.freeze({}),
+  }) as Readonly<Record<string, ColorPair>>,
+  byType: Object.freeze({}) as Readonly<Record<string, ColorPair>>,
 });
 
 /**
- * Resolves the color for a relationship type.
- *
- * Resolution order:
+ * Resolves the color for a relationship type. Resolution order:
  *   1. overrides.byType[type]
  *   2. RELATION_COLOR_DEFAULTS.byType[type]
  *   3. overrides.byCategory[category]
  *   4. RELATION_COLOR_DEFAULTS.byCategory[category]
  *   5. null (uncategorized or unrecognized type)
- *
- * @param {string} type - relationship type local name
- * @param {{ overrides?: { byType?: object, byCategory?: object }, mode?: 'light'|'dark' }} [options]
- * @returns {string | null}
  */
-export function resolveRelationColor(type, options = {}) {
+export function resolveRelationColor(
+  type: string,
+  options: ResolveRelationColorOptions = {},
+): string | null {
   const mode = options.mode ?? 'light';
   const overrides = options.overrides ?? {};
-
   const typeOverride = overrides.byType?.[type] ?? RELATION_COLOR_DEFAULTS.byType[type];
   if (typeOverride) return pickMode(typeOverride, mode);
 
   const category = categoryOf(type);
   if (!category) return null;
 
-  const categoryOverride = overrides.byCategory?.[category] ?? RELATION_COLOR_DEFAULTS.byCategory[category];
+  const categoryOverride =
+    overrides.byCategory?.[category] ?? RELATION_COLOR_DEFAULTS.byCategory[category];
   if (!categoryOverride) return null;
 
   return pickMode(categoryOverride, mode);
@@ -61,16 +71,19 @@ export function resolveRelationColor(type, options = {}) {
  * Returns the { light, dark } pair for a category, merging overrides
  * over defaults. Useful for UIs that want to render a legend.
  */
-export function categoryColorPair(categoryKey, overrides = {}) {
+export function categoryColorPair(
+  categoryKey: string,
+  overrides: { byCategory?: Record<string, Partial<ColorPair>> } = {},
+): ColorPair | null {
   const def = categoryDefinition(categoryKey);
   if (!def) return null;
   const fromOverride = overrides.byCategory?.[categoryKey];
   const fromDefault = RELATION_COLOR_DEFAULTS.byCategory[categoryKey];
   if (!fromDefault && !fromOverride) return null;
-  return { ...(fromDefault ?? {}), ...(fromOverride ?? {}) };
+  return { ...(fromDefault ?? { light: '', dark: '' }), ...(fromOverride ?? {}) } as ColorPair;
 }
 
-function pickMode(pair, mode) {
+function pickMode(pair: ColorPair | string | null, mode: 'light' | 'dark'): string | null {
   if (pair == null) return null;
   if (typeof pair === 'string') return pair;
   return pair[mode] ?? pair.light ?? pair.dark ?? null;

package/src/models/{relation-loader.js → relation-loader.ts}

@@ -4,43 +4,52 @@
 // dispatches each file to the appropriate class (PartitiveHyperedge,
 // GenericHyperedge, future leaves) based on its `type` field, via
 // HyperedgeRegistry.
-//
-// The wire-shape contract is owned by the JSON Schema at
-// `schemas/v3/relation.yaml` (concept-model repo) — this loader
-// produces the corresponding JS model instances. See
-// docs/design/relations-as-files.md (concept-model).
-//
-// Adding a new hyperedge type means: declare the leaf class with the
-// metadata block, register it. The loader picks it up automatically —
-// no edits here.
 
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import type { Dirent } from 'node:fs';
 import * as yaml from 'js-yaml';
 import { HyperedgeRegistry } from './hyperedge-registry.js';
+import type { HyperedgeClass } from './hyperedge-registry.js';
+import type { AbstractHyperedge } from './abstract-hyperedge.js';
 
-// Backward-compat: snapshot of registered classes keyed by typeTag.
-// Prefer HyperedgeRegistry.forTypeTag() for new code — this snapshot
-// is frozen at module load and won't pick up runtime registrations
-// from tests (the OCP test in Phase 11 registers a mock type after
-// import).
-export const TYPE_TO_CLASS = new Proxy({}, {
-  get(_target, prop) {
-    return HyperedgeRegistry.forTypeTag(prop);
-  },
-  ownKeys() {
-    return HyperedgeRegistry.allTypeTags();
-  },
-  getOwnPropertyDescriptor() {
-    return { enumerable: true, configurable: true };
+interface HyperedgeDocument {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface HyperedgeClassWithFromJson extends HyperedgeClass {
+  fromJSON(data: unknown): AbstractHyperedge;
+}
+
+/**
+ * Backward-compat: snapshot of registered classes keyed by typeTag.
+ * Prefer HyperedgeRegistry.forTypeTag() for new code — this snapshot
+ * is frozen at module load and won't pick up runtime registrations
+ * from tests (the OCP test in Phase 11 registers a mock type after
+ * import).
+ */
+export const TYPE_TO_CLASS = new Proxy(
+  {} as Record<string, HyperedgeClass>,
+  {
+    get(_target: unknown, prop: string | symbol): HyperedgeClass | null {
+      return typeof prop === 'string' ? HyperedgeRegistry.forTypeTag(prop) : null;
+    },
+    ownKeys(): string[] {
+      return HyperedgeRegistry.allTypeTags();
+    },
+    getOwnPropertyDescriptor(): PropertyDescriptor {
+      return { enumerable: true, configurable: true };
+    },
   },
-});
+);
 
 /**
  * Thrown by `loadAll` when a relation file has an unknown `type`,
  * malformed structure, or a class that fails to instantiate.
  */
 export class RelationLoadError extends Error {
-  constructor(path, message) {
+  readonly path: string;
+  constructor(path: string, message: string) {
     super(`relation-loader: ${path}: ${message}`);
     this.path = path;
   }
@@ -51,32 +60,27 @@ export class RelationLoadError extends Error {
  * returning a Map keyed by comprehensive-id.
  *
  * Returns an empty Map if `relationsDir` doesn't exist or is empty.
- *
- * @param {string} relationsDir — path to a `relations/` directory
- *   containing `<comprehensive-id>/<slug>.yaml` files (per the
- *   schema in schemas/v3/relation.yaml).
- * @returns {Map<string, Array<AbstractHyperedge>>} — for each
- *   comprehensive id, the list of relations that have it as their
- *   comprehensive.
  */
-export function loadAll(relationsDir) {
-  const result = new Map();
+export function loadAll(
+  relationsDir: string | null | undefined,
+): Map<string, AbstractHyperedge[]> {
+  const result = new Map<string, AbstractHyperedge[]>();
   if (!relationsDir) return result;
   if (!existsSync(relationsDir)) return result;
 
   const entries = readdirSync(relationsDir, { withFileTypes: true });
-  for (const compEntry of entries) {
+  for (const compEntry of entries as Dirent[]) {
     if (!compEntry.isDirectory()) continue;
     const compId = compEntry.name;
     const compDir = `${relationsDir}/${compId}`;
     if (!result.has(compId)) result.set(compId, []);
     const files = readdirSync(compDir)
-      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+      .filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'))
       .sort();
     for (const file of files) {
       const path = `${compDir}/${file}`;
       const rel = loadOne(path);
-      if (rel) result.get(compId).push(rel);
+      if (rel) result.get(compId)?.push(rel);
     }
   }
   return result;
@@ -93,19 +97,19 @@ export const RelationLoader = Object.freeze({ loadAll, loadOne });
 /**
  * Load a single relation file. Returns null if the file is missing,
  * unreadable, or doesn't have a recognized `type` field. Throws
- * `RelationLoadError` on malformed content (e.g., invalid `members`
- * count, wrong comprehensive shape, YAML parse error).
+ * `RelationLoadError` on malformed content.
  */
-export function loadOne(path) {
-  let doc;
+export function loadOne(path: string): AbstractHyperedge | null {
+  let doc: unknown;
   try {
     doc = yaml.load(readFileSync(path, 'utf8'));
   } catch (e) {
-    throw new RelationLoadError(path, `YAML parse failed: ${e.message}`);
+    throw new RelationLoadError(path, `YAML parse failed: ${(e as Error).message}`);
   }
   if (!doc || typeof doc !== 'object') return null;
-  if (!doc.type) return null;
-  const Cls = HyperedgeRegistry.forTypeTag(doc.type);
-  if (!Cls) return null;  // Unknown type — let the validator report it
-  return Cls.fromJSON(doc);
+  const d = doc as HyperedgeDocument;
+  if (!d.type) return null;
+  const Cls = HyperedgeRegistry.forTypeTag(d.type) as HyperedgeClassWithFromJson | null;
+  if (!Cls) return null;
+  return Cls.fromJSON(d);
 }

package/src/models/section.ts

@@ -0,0 +1,61 @@
+import { GlossaristModel } from './base.js';
+import type { LocalizedString } from './generic-member.js';
+
+export const ORDERING_METHODS: ReadonlyArray<string> = Object.freeze([
+  'systematic',
+  'mixed',
+  'alphabetical',
+]);
+
+export type OrderingMethod = string;
+
+export interface SectionJson {
+  id?: string | null;
+  names?: LocalizedString;
+  ordering?: OrderingMethod | null;
+  children?: ReadonlyArray<SectionJson | Section>;
+}
+
+export class Section extends GlossaristModel {
+  readonly id: string | null;
+  readonly names: LocalizedString;
+  readonly ordering: OrderingMethod | null;
+  readonly children: ReadonlyArray<Section>;
+
+  constructor(data: SectionJson = {}) {
+    super();
+    this.id = data.id ?? null;
+    this.names = (data.names as LocalizedString) ?? {};
+    this.ordering = data.ordering ?? null;
+    this.children = (data.children ?? []).map((c) =>
+      c instanceof Section ? c : new Section(c as SectionJson),
+    );
+  }
+
+  name(lang: string): string | null {
+    return this.names[lang] ?? this.names['eng'] ?? null;
+  }
+
+  descendantById(id: string): Section | null {
+    for (const child of this.children) {
+      if (child.id === id) return child;
+      const found = child.descendantById(id);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  override toJSON(): SectionJson {
+    const obj: SectionJson = { id: this.id };
+    if (Object.keys(this.names).length > 0) obj.names = { ...this.names };
+    if (this.ordering != null) obj.ordering = this.ordering;
+    if (this.children.length > 0) {
+      obj.children = this.children.map((c) => c.toJSON());
+    }
+    return obj;
+  }
+
+  static override fromJSON(data: SectionJson): Section {
+    return new Section(data);
+  }
+}