glossarist 0.4.50 → 0.4.52

package/src/concept-collection.ts

@@ -1,172 +0,0 @@
-import { naturalSort } from './sort.js';
-
-const _items = Symbol('items');
-
-export class ConceptCollection {
-  constructor(concepts = []) {
-    this[_items] = Array.from(concepts);
-  }
-
-  get length() { return this[_items].length; }
-  [Symbol.iterator]() { return this[_items][Symbol.iterator](); }
-
-  at(index) { return this[_items].at(index); }
-  indexOf(item) { return this[_items].indexOf(item); }
-  find(fn) { return this[_items].find(fn); }
-  findIndex(fn) { return this[_items].findIndex(fn); }
-  forEach(fn) { this[_items].forEach(fn); }
-  map(fn) { return this[_items].map(fn); }
-  reduce(fn, init) { return this[_items].reduce(fn, init); }
-  includes(item) { return this[_items].includes(item); }
-  push(...items) { return this[_items].push(...items); }
-  splice(...args) { return this[_items].splice(...args); }
-  set(index, item) { this[_items][index] = item; }
-
-  toArray() { return [...this[_items]]; }
-
-  byId(id) {
-    return this[_items].find(c => c.id === id || c.termid === id);
-  }
-
-  /**
-   * Find a concept by id and version.
-   *
-   * The version is matched against a top-level `version` field on
-   * the concept instance (e.g. `concept.version`). The deployment
-   * is responsible for setting this field on bibliographic records;
-   * the data model does not enforce its presence or type.
-   *
-   * If `version` is null, the method falls back to `byId(id)`. This
-   * supports the "version-agnostic" lookup for datasets where
-   * version is not tracked.
-   *
-   * @param {string} id
-   * @param {string | null} version
-   * @returns {Concept | null}
-   */
-  byIdAnd(id, version) {
-    if (version == null) return this.byId(id);
-    return this[_items].find(c =>
-      (c.id === id || c.termid === id) && c.version === version
-    ) ?? null;
-  }
-
-  byPrefix(prefix) {
-    return new ConceptCollection(this[_items].filter(c => c.id.startsWith(prefix)));
-  }
-
-  byLanguage(lang) {
-    return new ConceptCollection(this[_items].filter(c => c.hasLocalization(lang)));
-  }
-
-  byStatus(status) {
-    return new ConceptCollection(this[_items].filter(c => {
-      return c.languages.some(lang => c.localization(lang)?.entryStatus === status);
-    }));
-  }
-
-  /**
-   * Cascading section membership filter. Returns concepts whose
-   * section closure includes `sectionId`.
-   *
-   * A concept in section "3.1.1" matches `bySection('3.1')` and
-   * `bySection('3')` because the section closure walks ancestors
-   * transitively (mirrors owl:TransitiveProperty on
-   * gloss:hasParentSection in the concept-model ontology).
-   *
-   * Two calling conventions:
-   *
-   *   bySection('3.1', { register })          // register expands each concept's section closure
-   *   bySection(['3.1', '3'])                  // pre-expanded target set (any of these must match)
-   *
-   * Concept-side membership is read from `concept.sections` if set,
-   * otherwise from `concept.groups` (a flat list of section IDs).
-   */
-  bySection(sectionId, options = {}) {
-    if (Array.isArray(sectionId)) {
-      const targetSet = new Set(sectionId);
-      return new ConceptCollection(this[_items].filter(c => {
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        const ids = options.register
-          // @ts-expect-error TODO(Phase 2e): type this fully
-          ? options.register.conceptSectionIds(c)
-          : _flatConceptSectionIds(c);
-        return ids.some(id => targetSet.has(id));
-      }));
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (!options.register) {
-      throw new Error('bySection(sectionId) requires { register } to expand the concept section closures');
-    }
-    const target = sectionId;
-    return new ConceptCollection(this[_items].filter(c => {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      const ids = options.register.conceptSectionIds(c);
-      return ids.includes(target);
-    }));
-  }
-
-  index() {
-    const map = new Map();
-    for (const c of this[_items]) map.set(c.id, c);
-    return map;
-  }
-
-  sorted() {
-    const copy = [...this[_items]];
-    copy.sort((a, b) => naturalSort(a.id, b.id));
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    return new ConceptCollection(copy);
-  }
-
-  search(query) {
-    const q = query.toLowerCase();
-    return new ConceptCollection(this[_items].filter(c => {
-      for (const lang of c.languages) {
-        const lc = c.localization(lang);
-        if (!lc) continue;
-        for (const t of lc.terms) {
-          if ((t.designation ?? '').toLowerCase().includes(q)) return true;
-        }
-      }
-      for (const { text } of c.walkTexts()) {
-        if (text.toLowerCase().includes(q)) return true;
-      }
-      return false;
-    }));
-  }
-
-  allLanguages() {
-    const set = new Set();
-    for (const c of this[_items]) {
-      for (const lang of c.languages) set.add(lang);
-    }
-    return [...set].sort();
-  }
-
-  filter(fn) { return new ConceptCollection(this[_items].filter(fn)); }
-  slice(...args) { return new ConceptCollection(this[_items].slice(...args)); }
-  concat(...args) { return new ConceptCollection(this[_items].concat(...args)); }
-}
-
-// Standalone helper for the array-closure case where no register is
-// available. Mirrors the lookup done inside Register#conceptSectionIds
-// but without ancestor expansion (the closure is already provided).
-function _flatConceptSectionIds(concept) {
-  if (!concept) return [];
-  const out = [];
-  for (const source of [concept.sections, concept.groups]) {
-    if (!Array.isArray(source)) continue;
-    for (const entry of source) {
-      if (typeof entry === 'string') {
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        out.push(entry);
-      } else if (entry && typeof entry === 'object') {
-        const id = entry.id ?? entry.sectionId ?? entry.ref?.id;
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        if (id) out.push(String(id));
-      }
-    }
-  }
-  return out;
-}

package/src/concept-parser.ts

@@ -1,235 +0,0 @@
-import * as yaml from 'js-yaml';
-import { Concept } from './models/concept.js';
-import { RelatedConcept } from './models/related-concept.js';
-import { HyperedgeRegistry } from './models/hyperedge-registry.js';
-import { migrateHyperedgeToRelation } from './migration/hyperedge-migrator.js';
-import { InvalidInputError, YamlParseError } from './errors.js';
-
-// Structural keys are reserved at the concept level and excluded
-// from language localization discovery. The set is derived from
-// HyperedgeRegistry — every registered hyperedge class contributes
-// its wireKey and any v1WireKeys to the reserved set. Adding a new
-// hyperedge type means the parser reserves its wire key automatically;
-// no edits here.
-const STRUCTURAL_KEYS = new Set([
-  'termid', 'term', 'figures', 'tables', 'formulas',
-  'related', 'relatedConcepts',
-  'relations',
-  ..._registryStructuralKeys(),
-]);
-
-function _registryStructuralKeys() {
-  const out = [];
-  for (const cls of HyperedgeRegistry.allClasses()) {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    out.push(cls.wireKey);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    out.push(_camelCase(cls.wireKey));
-    for (const k of cls.v1WireKeys ?? []) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      out.push(k);
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      out.push(_camelCase(k));
-    }
-  }
-  return out;
-}
-
-function _camelCase(s) {
-  if (typeof s !== 'string' || !s.includes('_')) return s;
-  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-}
-
-export class ConceptParser {
-  parse(raw, context) {
-    const label = context ?? 'concept';
-
-    if (raw == null) {
-      throw new InvalidInputError(
-        `parseConceptYaml requires a non-empty YAML string (${label})`,
-        'non-null string',
-      );
-    }
-    if (typeof raw !== 'string' || raw.trim() === '') {
-      throw new InvalidInputError(
-        `parseConceptYaml requires a non-empty YAML string (${label})`,
-        'non-empty string',
-      );
-    }
-
-    let docs;
-    try {
-      // js-yaml 5.x dropped the explicit DEFAULT_SCHEMA export; the
-      // default schema is applied automatically when no `schema`
-      // option is passed. Passing CORE_SCHEMA reproduces the historical
-      // behavior (yaml.org core schema).
-      docs = yaml.loadAll(raw, { schema: yaml.CORE_SCHEMA ?? yaml.JSON_SCHEMA });
-    } catch (err) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      throw new YamlParseError(label, err);
-    }
-
-    return this._detectFormat(docs, label) === 'managed'
-      ? this._parseManaged(docs)
-      : this._parseCanonical(docs[0]);
-  }
-
-  _detectFormat(docs, label) {
-    if (docs.length >= 1 && docs[0]?.data?.identifier !== undefined) return 'managed';
-    if (docs[0] == null) throw new YamlParseError(label, new Error('YAML document is empty'));
-    return 'canonical';
-  }
-
-  _parseCanonical(doc) {
-    const localizations = {};
-    for (const key of Object.keys(doc)) {
-      if (!STRUCTURAL_KEYS.has(key) && typeof doc[key] === 'object' && doc[key] !== null) {
-        localizations[key] = doc[key];
-      }
-    }
-    return new Concept({
-      id: String(doc.termid),
-      term: doc.term || null,
-      localizations,
-      figures: doc.figures,
-      tables: doc.tables,
-      formulas: doc.formulas,
-      relations: _resolveHyperedgeData(doc),
-      raw: doc,
-    });
-  }
-
-  _parseManaged(docs) {
-    const mc = docs[0];
-    const localizations = {};
-
-    for (const doc of docs.slice(1)) {
-      if (!doc?.data?.language_code) continue;
-      const lang = doc.data.language_code;
-      const lcData = { ...doc.data };
-      delete lcData.language_code;
-      localizations[lang] = lcData;
-    }
-
-    // The hyperedge wire keys are reserved at concept level (top-level
-    // of the managed concept YAML), not under data:. Derive the list
-    // from the registry so adding a type doesn't require an edit here.
-    const conceptLevelOnlyKeys = [
-      'related',
-      'relations',
-      ...HyperedgeRegistry.allWireAndLegacyKeys(),
-    ];
-
-    assertConceptLevelOnly(mc, conceptLevelOnlyKeys);
-
-    return new Concept({
-      id: String(mc.data.identifier),
-      term: null,
-      localizations,
-      related: _normalizeRelated(mc.related),
-      relations: _resolveHyperedgeData(mc),
-      domains: mc.data.domains,
-      groups: mc.data.groups,
-      dates: mc.dates ?? mc.data?.dates,
-      sources: mc.sources ?? mc.data?.sources,
-      figures: mc.data?.figures,
-      tables: mc.data?.tables,
-      formulas: mc.data?.formulas,
-      status: mc.status,
-      schemaVersion: mc.schema_version,
-      raw: mc,
-    });
-  }
-}
-
-function assertConceptLevelOnly(mc, keys) {
-  const conceptId = mc?.data?.identifier ?? '<unknown>';
-  for (const key of keys) {
-    const camelKey = _camelCase(key);
-    if (mc?.data?.[key] != null && mc[key] == null && mc[camelKey] == null) {
-      throw new InvalidInputError(
-        `'${key}' must live at concept level (top-level of the managed ` +
-        `concept document), not under data:. Found data.${key} in concept ` +
-        `${conceptId}. Move the key out of the data: block.`,
-        'concept-level ' + key,
-      );
-    }
-  }
-}
-
-// Resolve hyperedge data from any input shape into a single unified
-// array. Iterates HyperedgeRegistry — for each registered class:
-//   - read its wireKey from the container (e.g. partitive_relations)
-//   - read any v1WireKeys (e.g. partitive_hyperedges) and migrate
-//   - tag each entry with the class's typeTag
-//
-// Returns null when no relation data is present, so Concept's
-// `_resolveHyperedges` falls back to the empty-array default.
-//
-// Adding a new hyperedge type means: declare it on a class, register.
-// The parser picks it up automatically — no edits here.
-function _resolveHyperedgeData(container) {
-  if (!container) return null;
-
-  if (Array.isArray(container.relations)) {
-    return container.relations;
-  }
-
-  const out = [];
-
-  for (const cls of HyperedgeRegistry.allClasses()) {
-    // v2 wire key (e.g. partitive_relations)
-    const arr = container[cls.wireKey] ?? container[_camelCase(cls.wireKey)];
-    if (Array.isArray(arr)) {
-      for (const r of arr) {
-        const tagged = _addTypeIfMissing(r, cls.typeTag);
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        if (tagged != null) out.push(tagged);
-      }
-    }
-
-    // v1 legacy wire keys (e.g. partitive_hyperedges) — migrated.
-    // The migration helper produces a v2 hash; we tag it with the
-    // typeTag so Concept's registry dispatch finds the right class.
-    for (const v1Key of cls.v1WireKeys ?? []) {
-      const v1Arr = container[v1Key] ?? container[_camelCase(v1Key)];
-      if (!Array.isArray(v1Arr)) continue;
-      for (const h of v1Arr) {
-        const hash = h?.toJSON && typeof h.toJSON === 'function' ? h.toJSON() : h;
-        const migrated = migrateHyperedgeToRelation(hash);
-        // @ts-expect-error TODO(Phase 2e): type this fully
-        if (migrated) out.push({ ...migrated, type: cls.typeTag });
-      }
-    }
-  }
-
-  return out.length > 0 ? out : null;
-}
-
-function _addTypeIfMissing(value, type) {
-  if (value == null) return null;
-  if (typeof value.toJSON === 'function') {
-    const hash = value.toJSON();
-    return hash.type ? hash : { ...hash, type };
-  }
-  if (typeof value === 'object') {
-    return value.type ? value : { ...value, type };
-  }
-  return value;
-}
-
-function _normalizeRelated(arr) {
-  if (!arr || !Array.isArray(arr)) return [];
-  return arr.map(r => {
-    if (r instanceof RelatedConcept) return r;
-    if (r.ref != null && typeof r.ref !== 'object') {
-      throw new InvalidInputError(
-        `RelatedConcept.ref must be an object { source, id }, got: ${typeof r.ref}`,
-        'object',
-      );
-    }
-    return new RelatedConcept(r);
-  });
-}
-
-export const conceptParser = new ConceptParser();

package/src/concept-reader.d.ts

@@ -1,13 +0,0 @@
-import type { Concept, Register } from './models/index';
-
-/** Read all concept YAML files from a directory. */
-export function readConcepts(dir: string): Concept[];
-
-/** Read a single concept by ID from a directory. */
-export function readConcept(dir: string, id: string): Concept | null;
-
-/** List all concept IDs in a directory, optionally filtered by prefix. */
-export function listConceptIds(dir: string, prefix?: string): string[];
-
-/** Read register.yaml from a dataset directory (if present). */
-export function readRegister(dir: string): Register | null;

package/src/concept-serializer.ts

@@ -1,110 +0,0 @@
-import * as yaml from 'js-yaml';
-import { PartitiveHyperedge } from './models/partitive-hyperedge.js';
-import { GenericHyperedge } from './models/generic-hyperedge.js';
-
-const DUMP_OPTS = { lineWidth: -1, noRefs: true, sortKeys: false, skipInvalid: true };
-
-// Partition the unified relations array by concrete type and emit
-// each type under its own wire key. Concept.relations holds mixed
-// types; the wire format stays split for backward compat with
-// existing consumers and the JSON Schema in concept-model.
-function _emitTypedRelations(concept) {
-  const partitiveRels = concept.relations.filter(r => r instanceof PartitiveHyperedge);
-  const genericRels = concept.relations.filter(r => r instanceof GenericHyperedge);
-  return {
-    partitive: partitiveRels.map(r => r.toJSON()),
-    generic: genericRels.map(r => r.toJSON()),
-  };
-}
-
-export class ConceptSerializer {
-  toCanonicalYaml(concept) {
-    const doc = { termid: concept.id };
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.term) doc.term = concept.term;
-
-    const { partitive, generic } = _emitTypedRelations(concept);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (partitive.length > 0) doc.partitive_relations = partitive;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (generic.length > 0) doc.generic_relations = generic;
-
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (lc) {
-        const lcObj = lc.toJSON();
-        delete lcObj.language_code;
-        doc[lang] = lcObj;
-      }
-    }
-
-    return yaml.dump(doc, DUMP_OPTS);
-  }
-
-  toManagedYaml(concept, uuidFn) {
-    const genId = uuidFn ?? (() => crypto.randomUUID());
-    const localizedConcepts = {};
-    const langDocs = [];
-
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (!lc) continue;
-      const lcId = genId();
-      localizedConcepts[lang] = lcId;
-
-      const lcObj = lc.toJSON();
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      langDocs.push({ data: lcObj, id: lcId });
-    }
-
-    const mainDoc = {
-      data: { identifier: concept.id, localized_concepts: localizedConcepts },
-      id: genId(),
-    };
-
-    if (concept.domains.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.data.domains = concept.domains.map(d => d.toJSON());
-    }
-
-    if (concept.relatedConcepts.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.related = concept.relatedConcepts.map(rc => rc.toJSON());
-    }
-    const { partitive, generic } = _emitTypedRelations(concept);
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (partitive.length > 0) mainDoc.partitive_relations = partitive;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (generic.length > 0) mainDoc.generic_relations = generic;
-    if (concept.sources.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.sources = concept.sources.map(s => s.toJSON());
-    }
-    if (concept.dates.length > 0) {
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      mainDoc.dates = concept.dates.map(d => d.toJSON());
-    }
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.status) mainDoc.status = concept.status;
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    if (concept.schemaVersion) mainDoc.schema_version = concept.schemaVersion;
-
-    const parts = [
-      '---\n' + yaml.dump(mainDoc, DUMP_OPTS),
-      ...langDocs.map(d => '---\n' + yaml.dump(d, DUMP_OPTS)),
-    ];
-    return parts.join('');
-  }
-
-  toYaml(concept, uuidFn) {
-    return concept.term
-      ? this.toCanonicalYaml(concept)
-      : this.toManagedYaml(concept, uuidFn);
-  }
-
-  toRegisterYaml(data) {
-    return yaml.dump(data, DUMP_OPTS);
-  }
-}
-
-export const conceptSerializer = new ConceptSerializer();

package/src/concept-writer.d.ts

@@ -1,7 +0,0 @@
-import { Concept } from './models/index';
-
-export function writeConcept(dir: string, concept: Concept, format?: 'canonical' | 'managed' | 'auto'): void;
-export function writeConcepts(dir: string, concepts: Concept[], options?: {
-  register?: Record<string, unknown>;
-  format?: 'canonical' | 'managed' | 'auto';
-}): void;

package/src/concept-writer.ts

@@ -1,47 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { conceptSerializer } from './concept-serializer.js';
-import { InvalidInputError } from './errors.js';
-
-function assertDir(dir, fnName) {
-  if (typeof dir !== 'string' || dir.trim() === '') {
-    throw new InvalidInputError(`${fnName} requires a directory path`, 'non-empty string');
-  }
-}
-
-export function writeConcept(dir, concept, format = 'auto') {
-  assertDir(dir, 'writeConcept');
-  if (!concept?.id) {
-    throw new InvalidInputError('writeConcept requires a Concept with an id', 'Concept');
-  }
-
-  const y = format === 'canonical'
-    ? conceptSerializer.toCanonicalYaml(concept)
-    : format === 'managed'
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      ? conceptSerializer.toManagedYaml(concept)
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      : conceptSerializer.toYaml(concept);
-
-  fs.writeFileSync(path.join(dir, `${concept.id}.yaml`), y, 'utf8');
-}
-
-export function writeConcepts(dir, concepts, options = {}) {
-  assertDir(dir, 'writeConcepts');
-  fs.mkdirSync(dir, { recursive: true });
-
-  for (const concept of concepts) {
-    // @ts-expect-error TODO(Phase 2e): type this fully
-    writeConcept(dir, concept, options.format);
-  }
-
-  // @ts-expect-error TODO(Phase 2e): type this fully
-  if (options.register) {
-    fs.writeFileSync(
-      path.join(dir, 'register.yaml'),
-      // @ts-expect-error TODO(Phase 2e): type this fully
-      conceptSerializer.toRegisterYaml(options.register),
-      'utf8',
-    );
-  }
-}

package/src/diff/canonical-json.ts

@@ -1,29 +0,0 @@
-// Canonical JSON for equality comparison.
-//
-// Sorts object keys recursively so two semantically-equal values produce
-// identical strings regardless of insertion order. Arrays preserve order
-// (they're ordered in domain semantics). Undefined values are dropped.
-
-type JsonInput = null | undefined | string | number | boolean | JsonInput[] | { [k: string]: JsonInput };
-
-export function canonicalJson(value: JsonInput | unknown): string {
-  return JSON.stringify(toCanonical(value as JsonInput));
-}
-
-export function deepEqualCanonical(a: JsonInput | unknown, b: JsonInput | unknown): boolean {
-  return canonicalJson(a) === canonicalJson(b);
-}
-
-function toCanonical(value: JsonInput): unknown {
-  if (value == null) return null;
-  if (Array.isArray(value)) return value.map(toCanonical);
-  if (typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const k of Object.keys(value).sort()) {
-      const v = toCanonical((value as Record<string, JsonInput>)[k] as JsonInput);
-      if (v !== undefined) out[k] = v;
-    }
-    return out;
-  }
-  return value;
-}