glossarist 0.4.49 → 0.4.51

package/src/validators/asset-index.ts

@@ -1,67 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-import { DATASET_ASSETS } from '../dataset-asset.js';
-
-export class AssetIndex {
-  constructor() {
-    this._paths = new Set();
-  }
-
-  get paths() {
-    return [...this._paths].sort();
-  }
-
-  get size() {
-    return this._paths.size;
-  }
-
-  register(path) {
-    if (path == null) return;
-    this._paths.add(this._normalize(path));
-  }
-
-  has(path) {
-    if (path == null) return false;
-    return this._paths.has(this._normalize(path));
-  }
-
-  [Symbol.iterator]() {
-    return this._paths[Symbol.iterator]();
-  }
-
-  _normalize(path) {
-    return String(path).replace(/^\//, '');
-  }
-
-  static async fromGcrPackage(pkg) {
-    const index = new AssetIndex();
-    const names = await pkg.imageFileNames();
-    for (const name of names) {
-      index.register(name);
-    }
-    return index;
-  }
-
-  static fromDirectory(datasetPath, fs) {
-    const index = new AssetIndex();
-    const imagesAsset = DATASET_ASSETS.find(
-      a => a.type === 'directory' && a.path === 'images');
-    if (!imagesAsset) return index;
-
-    const imagesDir = `${datasetPath}/${imagesAsset.path}`;
-    _walkDir(fs, imagesDir, imagesAsset.path, index);
-    return index;
-  }
-}
-
-function _walkDir(fs, dirPath, relativePrefix, index) {
-  if (!fs.existsSync(dirPath)) return;
-  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
-    const fullPath = `${dirPath}/${entry.name}`;
-    const relPath = `${relativePrefix}/${entry.name}`;
-    if (entry.isDirectory()) {
-      _walkDir(fs, fullPath, relPath, index);
-    } else {
-      index.register(relPath);
-    }
-  }
-}

package/src/validators/binary-has-part-redundancy-rule.ts

@@ -1,67 +0,0 @@
-// Warns when binary `has_part` / `is_part_of` edges duplicate
-// PartitiveHyperedge members, or when a concept has many binary
-// has_part edges that should be consolidated into a PartitiveHyperedge.
-//
-// Per TODO.partitive-relation-v2 item 14, binary edges and
-// PartitiveRelations coexist by design. The asymmetry is pragmatic:
-// binary edges are compact for single pairwise facts; relations
-// carry completeness/plurality/criterion metadata. The redundancy
-// case (same fact encoded both ways) is harmless data-wise but
-// wasteful and should be flagged for migration.
-//
-// Severity: warning. Never blocks save.
-
-import { ValidationRule } from './validation-rule.js';
-import { refKey } from './ref-keys.js';
-
-const BINARY_HAS_PART_TYPES = new Set(['has_part', 'is_part_of']);
-
-export class BinaryHasPartRedundancyRule extends ValidationRule {
-  constructor() { super('binary-has-part-redundancy', 'warning'); }
-
-  validate(concept, path, result) {
-    const relations = concept.relations ?? [];
-
-    // Collect partitive refs from PartitiveRelations.
-    const relationTargets = new Set();
-    for (const rel of relations) {
-      const compKey = refKey(rel?.comprehensive);
-      const members = rel?.partitives ?? rel?.parts ?? [];
-      for (const member of members) {
-        const ref = member?.ref ?? member;
-        const key = refKey(ref);
-        if (key && key !== compKey) relationTargets.add(key);
-      }
-    }
-
-    // Collect binary has_part refs.
-    const binaryTargets = new Set();
-    const related = concept.relatedConcepts ?? [];
-    for (const rc of related) {
-      if (!BINARY_HAS_PART_TYPES.has(rc.type)) continue;
-      const key = refKey(rc?.ref);
-      if (key) binaryTargets.add(key);
-    }
-
-    // Redundancy: refs in both.
-    for (const target of relationTargets) {
-      if (binaryTargets.has(target)) {
-        this.addIssue(result,
-          `${path}relatedConcepts`,
-          `binary has_part edge for (${target}) is redundant — already in a ` +
-          `PartitiveHyperedge member; pick one encoding to avoid divergence`,
-        );
-      }
-    }
-
-    // Cluster: 3+ binary has_part edges suggests PartitiveHyperedge territory.
-    if (binaryTargets.size >= 3) {
-      this.addIssue(result,
-        `${path}relatedConcepts`,
-        `${binaryTargets.size} binary has_part edges on this concept; ` +
-        `consider converting to a PartitiveHyperedge (which can carry ` +
-        `completeness, multiplicity, and criterion metadata)`,
-      );
-    }
-  }
-}

package/src/validators/concept-validator.ts

@@ -1,93 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-import { ValidationRule } from './validation-rule.js';
-import { ValidationResult } from './validation-result.js';
-
-const VALID_DESIGNATION_TYPES = new Set([
-  'expression', 'abbreviation', 'symbol', 'graphical symbol', 'graphical_symbol',
-]);
-
-const VALID_ENTRY_STATUSES = new Set([
-  'valid', 'draft', 'retired', 'notValid', 'superseded', 'withdrawn',
-]);
-
-export class LanguageCodeRule extends ValidationRule {
-  constructor() { super('language-code'); }
-  validate(concept, path, result) {
-    for (const lang of concept.languages) {
-      if (!/^[a-z]{3}$/.test(lang)) {
-        this.addIssue(result,
-          `${path}localizations.${lang}`,
-          `Invalid language code '${lang}': expected ISO 639-3 (3 lowercase letters)`);
-      }
-    }
-  }
-}
-
-export class DesignationTypeRule extends ValidationRule {
-  constructor() { super('designation-type'); }
-  validate(concept, path, result) {
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (!lc) continue;
-      for (let i = 0; i < lc.terms.length; i++) {
-        const type = lc.terms[i].type;
-        if (type && !VALID_DESIGNATION_TYPES.has(type)) {
-          this.addIssue(result,
-            `${path}localizations.${lang}.terms[${i}].type`,
-            `Unknown designation type '${type}'`);
-        }
-      }
-    }
-  }
-}
-
-export class EntryStatusRule extends ValidationRule {
-  constructor() { super('entry-status'); }
-  validate(concept, path, result) {
-    for (const lang of concept.languages) {
-      const lc = concept.localization(lang);
-      if (!lc) continue;
-      if (lc.entryStatus && !VALID_ENTRY_STATUSES.has(lc.entryStatus)) {
-        this.addIssue(result,
-          `${path}localizations.${lang}.entry_status`,
-          `Unknown entry status '${lc.entryStatus}'`);
-      }
-    }
-  }
-}
-
-export class ConceptValidator {
-  _rules = [];
-
-  addRule(rule) {
-    this._rules.push(rule);
-    return this;
-  }
-
-  validate(concept) {
-    const result = new ValidationResult();
-
-    if (!concept.id) {
-      result.addError('id', 'Concept must have an id');
-    }
-
-    if (concept.languages.length === 0) {
-      result.addWarning('localizations', 'Concept must have at least one localization');
-    } else {
-      for (const lang of concept.languages) {
-        const lc = concept.localization(lang);
-        if (!lc || lc.terms.length === 0) {
-          result.addWarning(`localizations.${lang}.terms`,
-            `Localization '${lang}' must have at least one term`);
-        }
-      }
-    }
-
-    for (const rule of this._rules) {
-      rule.validate(concept, '', result);
-    }
-
-    return result;
-  }
-}

package/src/validators/delimiting-coherence-rule.ts

@@ -1,105 +0,0 @@
-// Validates delimiting coherence across a concept's PartitiveRelations
-// per ISO 704:2022.
-//
-// ISO 704:2022 (§5.5.4.2.1, rake diagram semantics):
-//   "Whether a part is delimiting depends on the concept system, the
-//    coordinate concepts, the inheritance principle, and the criterion
-//    of subdivision used."
-//
-// This rule surfaces three categories of issues that the model
-// constructor cannot catch (they're cross-relation, not per-instance):
-//
-//   1. WARNING: A PartitiveHyperedge where every partitive is
-//      is_delimiting=true overuses delimiting. Typically only some
-//      parts distinguish the comprehensive from coordinate concepts.
-//   2. ERROR: Two PartitiveRelations on the same concept with the
-//      same criterion but different is_delimiting for the same
-//      partitive ref — inconsistent delimiting claim about the same
-//      part. ISO 704 requires delimiting claims about a given part to
-//      be consistent across decompositions sharing a criterion.
-//   3. WARNING: A partitive marked is_delimiting=true on a relation
-//      with no criterion set. Delimiting is meaningful only relative
-//      to a subdivision criterion.
-//
-// Per TODO.partitive-relation-v3/06.
-
-import { ValidationRule } from './validation-rule.js';
-import { refKey, criterionKey } from './ref-keys.js';
-
-export class DelimitingCoherenceRule extends ValidationRule {
-  constructor() { super('delimiting-coherence'); }
-
-  validate(concept, path, result) {
-    const relations = concept.relations ?? [];
-    if (relations.length === 0) return;
-
-    _checkOveruse(relations, path, result);
-    _checkInconsistentAcrossRelations(relations, path, result, this);
-    _checkDelimitingWithoutCriterion(relations, path, result);
-  }
-}
-
-function _checkOveruse(relations, path, result) {
-  for (let i = 0; i < relations.length; i++) {
-    const rel = relations[i];
-    const members = rel?.partitives ?? [];
-    if (members.length < 2) continue;
-    const delimitingCount = members.filter(m => m?.is_delimiting === true).length;
-    if (delimitingCount === members.length) {
-      result.addWarning(
-        `${path}partitiveRelations[${i}]`,
-        `every partitive is marked is_delimiting=true; typically only ` +
-        `some parts distinguish the comprehensive from coordinate concepts`,
-      );
-    }
-  }
-}
-
-function _checkInconsistentAcrossRelations(relations, path, result, rule) {
-  const byCriterion = new Map();
-  for (let i = 0; i < relations.length; i++) {
-    const rel = relations[i];
-    const critKey = criterionKey(rel?.criterion);
-    if (critKey == null) continue;
-    if (!byCriterion.has(critKey)) byCriterion.set(critKey, []);
-    byCriterion.get(critKey).push({ rel, i });
-  }
-
-  for (const [, group] of byCriterion) {
-    const refDelimiting = new Map();
-    for (const { rel, i } of group) {
-      for (const m of rel?.partitives ?? []) {
-        const key = refKey(m?.ref);
-        if (key == null) continue;
-        const delimiting = m?.is_delimiting === true;
-        const existing = refDelimiting.get(key);
-        if (existing != null && existing.delimiting !== delimiting) {
-          rule.addIssue(result,
-            `${path}partitiveRelations[${i}].partitives`,
-            `inconsistent is_delimiting for ref (${key}) across ` +
-            `relations ${existing.relIdx} and ${i} with the same ` +
-            `criterion; ISO 704 requires delimiting claims about the ` +
-            `same part to be consistent`,
-          );
-        } else if (existing == null) {
-          refDelimiting.set(key, { delimiting, relIdx: i });
-        }
-      }
-    }
-  }
-}
-
-function _checkDelimitingWithoutCriterion(relations, path, result) {
-  for (let i = 0; i < relations.length; i++) {
-    const rel = relations[i];
-    if (rel?.criterion) continue;
-    const anyDelimiting = (rel?.partitives ?? []).some(m => m?.is_delimiting === true);
-    if (anyDelimiting) {
-      result.addWarning(
-        `${path}partitiveRelations[${i}].criterion`,
-        `relation has is_delimiting=true on partitives but no criterion; ` +
-        `delimiting is meaningful only relative to a subdivision criterion`,
-      );
-    }
-  }
-}

package/src/validators/external-concept-shape-rule.ts

@@ -1,60 +0,0 @@
-// Validates ExternalConcept shape (status: external).
-//
-// Per TODO.partitive-relation-v2 item 06, an ExternalConcept is a
-// ManagedConcept with status: external. External concepts:
-//   - MUST have at least one designation (the name by which they're referenced)
-//   - MUST NOT have a definition (contradicts status: external)
-//   - MUST NOT have sources (we don't define them)
-//
-// Severity: error. An external concept with a definition or sources
-// contradicts the semantic role of "external" and should be re-typed
-// to a real concept status (valid, draft, etc.).
-
-import { ValidationRule } from './validation-rule.js';
-
-export class ExternalConceptShapeRule extends ValidationRule {
-  constructor() { super('external-concept-shape', 'error'); }
-
-  validate(concept, path, result) {
-    if (concept.status !== 'external') return;
-
-    // Every concept — even an external one — needs at least one
-    // designation (the name by which it is referenced).
-    let designationCount = 0;
-    for (const lang of concept.languages ?? []) {
-      const lc = concept.localization?.(lang);
-      if (!lc) continue;
-      designationCount += (lc.terms ?? []).length;
-    }
-    if (designationCount === 0) {
-      this.addIssue(result,
-        `${path}localizations.*.terms`,
-        'ExternalConcept has no designations; every concept (including external) ' +
-        'needs at least one designation (the name by which it is referenced)',
-      );
-    }
-
-    // External concepts must NOT have a definition or sources.
-    for (const lang of concept.languages ?? []) {
-      const lc = concept.localization?.(lang);
-      if (!lc) continue;
-
-      if ((lc.definitions ?? []).length > 0) {
-        this.addIssue(result,
-          `${path}localizations.${lang}.definitions`,
-          `ExternalConcept has a definition in language '${lang}'; ` +
-          `external concepts are referenced but not defined here ` +
-          `(move the definition to the providing dataset and add a provided_by edge)`,
-        );
-      }
-
-      if ((lc.sources ?? []).length > 0) {
-        this.addIssue(result,
-          `${path}localizations.${lang}.sources`,
-          `ExternalConcept has sources in language '${lang}'; ` +
-          `external concepts should not carry sources (sources belong on the providing concept)`,
-        );
-      }
-    }
-  }
-}

package/src/validators/gcr-validator.ts

@@ -1,75 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-import * as yaml from 'js-yaml';
-import { DATASET_ASSETS } from '../dataset-asset.js';
-import { ValidationResult } from './validation-result.js';
-
-export class GcrValidator {
-  async validate(pkg) {
-    const result = new ValidationResult();
-    await this._validateMetadata(pkg, result);
-    await this._validateConcepts(pkg, result);
-    await this._validateAssets(pkg, result);
-    return result;
-  }
-
-  async _validateMetadata(pkg, result) {
-    const raw = await pkg.readText('metadata.yaml');
-    if (!raw) {
-      result.addError('metadata.yaml is missing');
-      return;
-    }
-
-    let meta;
-    try {
-      meta = yaml.load(raw);
-    } catch (e) {
-      result.addError(`metadata.yaml: invalid YAML: ${e.message}`);
-      return;
-    }
-
-    if (!meta.shortname) result.addError('metadata.yaml missing shortname');
-    if (!meta.version) result.addError('metadata.yaml missing version');
-    if (meta.concept_count == null) result.addError('metadata.yaml missing concept_count');
-  }
-
-  async _validateConcepts(pkg, result) {
-    const ids = await pkg.conceptIds();
-    if (ids.length === 0) {
-      result.addError('No concept files found in concepts/');
-    }
-  }
-
-  async _validateAssets(pkg, result) {
-    for (const asset of DATASET_ASSETS) {
-      if (asset.type === 'file') {
-        await this._validateFileAsset(pkg, asset.path, result);
-      } else if (asset.type === 'directory') {
-        await this._validateDirectoryAsset(pkg, asset.path, result);
-      }
-    }
-  }
-
-  async _validateFileAsset(pkg, path, result) {
-    const raw = await pkg.readText(path);
-    if (!raw) return;
-    try {
-      yaml.load(raw);
-    } catch (e) {
-      result.addError(`${path}: invalid YAML at line ${e.mark?.line ?? '?'}: ${e.message}`);
-    }
-  }
-
-  _validateDirectoryAsset(pkg, dirPath, result) {
-    let hasFiles = false;
-    let hasEntries = false;
-    for (const entry of pkg.entryPaths()) {
-      if (entry.path.startsWith(`${dirPath}/`)) {
-        hasEntries = true;
-        if (!entry.dir) hasFiles = true;
-      }
-    }
-    if (hasEntries && !hasFiles) {
-      result.addWarning(`${dirPath}/ directory exists but is empty`);
-    }
-  }
-}

package/src/validators/hyperedge-coherence-rule.ts

@@ -1,98 +0,0 @@
-// Validates hyperedge coherence per ISO 704 / ISO 12620.
-//
-// Applies to every AbstractHyperedge subclass (PartitiveHyperedge,
-// GenericHyperedge, future TemporalHyperedge / AssociativeHyperedge /
-// SequentialHyperedge). The ISO 704 / ISO 12620 invariants are
-// type-blind:
-//
-//   1. ERROR: each hyperedge has ≥2 members (ISO 704 "two or more")
-//   2. ERROR: no two hyperedges of the same type on the same concept
-//      share the same comprehensive + same criterion (duplicate
-//      decomposition — violates ISO 12620 coordinate-concept coherence)
-//   3. WARNING: a concept with multiple hyperedges of the same type
-//      where any lacks criterion (cannot verify distinctness from
-//      siblings)
-//
-// Lives in the validator framework, not the model constructor, per
-// invariant I8 (TODO.hyperedges-v2/00). Constructors enforce type-shape;
-// validators enforce semantics.
-//
-// Per TODO Phase 7: rule renamed from PartitiveRelationCoherenceRule
-// to HyperedgeCoherenceRule. The rule applies to all hyperedges; the
-// duplicate check is scoped per type so a Partitive and a Generic with
-// the same comprehensive+criterion don't false-positive.
-
-import { ValidationRule } from './validation-rule.js';
-import { refKey, criterionKey } from './ref-keys.js';
-import { AbstractHyperedge } from '../models/abstract-hyperedge.js';
-
-export class HyperedgeCoherenceRule extends ValidationRule {
-  constructor() { super('hyperedge-coherence'); }
-
-  validate(concept, path, result) {
-    const hyperedges = (concept.relations ?? []).filter(r => r instanceof AbstractHyperedge);
-    if (hyperedges.length === 0) return;
-
-    // Check 1: ≥2 members per hyperedge. (The constructor also
-    // rejects this, but a warning here surfaces it in the result
-    // bundle for CI visibility.)
-    for (let i = 0; i < hyperedges.length; i++) {
-      const memberCount = (hyperedges[i]?.members ?? []).length;
-      if (memberCount < 2) {
-        this.addIssue(result,
-          `${path}relations[${i}].members`,
-          `hyperedge ${i + 1} has ${memberCount} member(s); ` +
-          `ISO 704 requires ≥2 (use a binary edge for pairwise facts)`,
-        );
-      }
-    }
-
-    // Check 2: no duplicate (type + comprehensive + criterion) on the same concept.
-    // Scope by type so a Partitive and a Generic with the same comp+criterion
-    // don't false-positive — they're different decompositions.
-    const seen = new Map();
-    for (let i = 0; i < hyperedges.length; i++) {
-      const rel = hyperedges[i];
-      const typeTag = rel?.constructor?.typeTag ?? '';
-      const compKey = refKey(rel?.comprehensive);
-      const critKey = criterionKey(rel?.criterion);
-      if (compKey == null || critKey == null) continue;
-      const key = `${typeTag}|${compKey}|${critKey}`;
-      if (seen.has(key)) {
-        this.addIssue(result,
-          `${path}relations[${i}]`,
-          `duplicate ${rel.constructor.name} (same comprehensive + same criterion ` +
-          `as relation ${seen.get(key) + 1}); violates ISO 12620 coordinate-concept coherence`,
-        );
-      } else {
-        seen.set(key, i);
-      }
-    }
-
-    // Check 3: criterion documentation (warning) when concept has multiple
-    // hyperedges of the same type. Same-type-scope rationale as Check 2.
-    const byType = new Map();
-    for (const rel of hyperedges) {
-      const typeTag = rel?.constructor?.typeTag ?? '';
-      if (!byType.has(typeTag)) byType.set(typeTag, []);
-      byType.get(typeTag).push(rel);
-    }
-    for (const [typeTag, rels] of byType) {
-      if (rels.length <= 1) continue;
-      for (const rel of rels) {
-        if (!rel.criterion) {
-          const idx = hyperedges.indexOf(rel);
-          result.addWarning(
-            `${path}relations[${idx}].criterion`,
-            `concept has multiple ${typeTag} hyperedges but this one ` +
-            `has no criterion; cannot verify distinctness from siblings`,
-          );
-        }
-      }
-    }
-  }
-}
-
-// Backward-compat alias. Existing imports of PartitiveRelationCoherenceRule
-// continue to work; the rule is now type-blind.
-export const PartitiveRelationCoherenceRule = HyperedgeCoherenceRule;

package/src/validators/index.d.ts

@@ -1,43 +0,0 @@
-export class ValidationError {
-  readonly path: string;
-  readonly message: string;
-  readonly severity: 'error' | 'warning';
-  toString(): string;
-}
-
-export class ValidationRule {
-  readonly name: string;
-  readonly severity: 'error' | 'warning';
-  validate(value: any, path: string): ValidationError[];
-}
-
-export class ConceptValidator {
-  addRule(rule: ValidationRule): this;
-  validate(concept: any): {
-    valid: boolean;
-    errors: ValidationError[];
-    warnings: ValidationError[];
-  };
-}
-
-export class RegisterValidator {
-  validate(register: any): {
-    valid: boolean;
-    errors: ValidationError[];
-    warnings: ValidationError[];
-  };
-}
-
-export function validateConcept(concept: any): {
-  valid: boolean;
-  errors: ValidationError[];
-  warnings: ValidationError[];
-};
-
-export function validateRegister(register: any): {
-  valid: boolean;
-  errors: ValidationError[];
-  warnings: ValidationError[];
-};
-
-export function createConceptValidator(): ConceptValidator;

package/src/validators/ref-keys.ts

@@ -1,31 +0,0 @@
-// Shared identity-key helpers for cross-relation validators.
-//
-// Extracted from HyperedgeCoherenceRule and
-// BinaryHasPartRedundancyRule.
-// Eliminates drift: both rules now use the same notion of "same ref"
-// and "same criterion" instead of each defining its own _refKey and
-// _criterionKey with subtly different behaviors.
-
-export function refKey(ref) {
-  if (!ref) return null;
-  const source = ref.source ?? '';
-  const id = ref.id ?? '';
-  if (!source && !id) return null;
-  return `${source}:${id}`;
-}
-
-// Hashable key for a criterion (lang-keyed hash). Returns null when
-// no criterion is set OR when the criterion contains no string values.
-// Values are sorted so two criteria with the same strings in different
-// language-key order produce the same key (ISO 12620 coordinate-
-// concept coherence cares about the criterion's content, not the
-// language label order).
-export function criterionKey(criterion) {
-  if (!criterion || typeof criterion !== 'object') return null;
-  const values = Object.values(criterion)
-    .filter(v => typeof v === 'string')
-    .map(s => s.trim())
-    .filter(s => s.length > 0)
-    .sort();
-  return values.length > 0 ? values.join('|') : null;
-}

package/src/validators/register-validator.ts

@@ -1,18 +0,0 @@
-import { ValidationResult } from './validation-result.js';
-
-export class RegisterValidator {
-  validate(register) {
-    const result = new ValidationResult();
-    if (!register || typeof register !== 'object') {
-      result.addError('', 'Register must be a non-null object');
-      return result;
-    }
-    if (!register.schema_version) {
-      result.addWarning('schema_version', 'Register must have a schema_version');
-    }
-    if (!register.shortname) {
-      result.addWarning('shortname', 'Register should have a shortname');
-    }
-    return result;
-  }
-}