glossarist 0.4.19 → 0.4.20

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

@@ -0,0 +1,74 @@
+// Warns when binary `has_part` / `is_part_of` edges duplicate
+// PartitiveRelation members, or when a concept has many binary
+// has_part edges that should be consolidated into a PartitiveRelation.
+//
+// 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';
+
+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.partitiveRelations ?? concept.partitiveHyperedges ?? [];
+
+    // 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 ` +
+          `PartitiveRelation member; pick one encoding to avoid divergence`,
+        );
+      }
+    }
+
+    // Cluster: 3+ binary has_part edges suggests PartitiveRelation territory.
+    if (binaryTargets.size >= 3) {
+      this.addIssue(result,
+        `${path}relatedConcepts`,
+        `${binaryTargets.size} binary has_part edges on this concept; ` +
+        `consider converting to a PartitiveRelation (which can carry ` +
+        `completeness, plurality, and criterion metadata)`,
+      );
+    }
+  }
+}
+
+function _refKey(ref) {
+  if (!ref) return null;
+  const source = ref.source ?? '';
+  const id = ref.id ?? '';
+  if (!source && !id) return null;
+  return `${source}:${id}`;
+}

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

@@ -0,0 +1,60 @@
+// 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/index.js

@@ -17,6 +17,12 @@ export {
   NonVerbalRefIntegrityRule,
   OrphanedImagesRule,
 } from './v3-rules.js';
+export { PartitiveHyperedgeShapeRule } from './partitive-hyperedge-rule.js';
+export { PartitiveDriftRule } from './partitive-drift-rule.js';
+export { SourcedFromLocalityRule } from './sourced-from-locality-rule.js';
+export { PartitiveRelationCoherenceRule } from './partitive-relation-coherence-rule.js';
+export { ExternalConceptShapeRule } from './external-concept-shape-rule.js';
+export { BinaryHasPartRedundancyRule } from './binary-has-part-redundancy-rule.js';
 
 import { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
 import { RegisterValidator } from './register-validator.js';
@@ -33,6 +39,12 @@ import {
   CiteRefIntegrityRule,
   NonVerbalRefIntegrityRule,
 } from './v3-rules.js';
+import { PartitiveHyperedgeShapeRule } from './partitive-hyperedge-rule.js';
+import { PartitiveDriftRule } from './partitive-drift-rule.js';
+import { SourcedFromLocalityRule } from './sourced-from-locality-rule.js';
+import { PartitiveRelationCoherenceRule } from './partitive-relation-coherence-rule.js';
+import { ExternalConceptShapeRule } from './external-concept-shape-rule.js';
+import { BinaryHasPartRedundancyRule } from './binary-has-part-redundancy-rule.js';
 
 const _default = new ConceptValidator()
   .addRule(new LanguageCodeRule())
@@ -47,7 +59,13 @@ const _default = new ConceptValidator()
   .addRule(new SourceUrnFormatRule())
   .addRule(new RelationshipTypeRule())
   .addRule(new CiteRefIntegrityRule())
-  .addRule(new NonVerbalRefIntegrityRule());
+  .addRule(new NonVerbalRefIntegrityRule())
+  .addRule(new PartitiveHyperedgeShapeRule())
+  .addRule(new PartitiveDriftRule())
+  .addRule(new SourcedFromLocalityRule())
+  .addRule(new PartitiveRelationCoherenceRule())
+  .addRule(new ExternalConceptShapeRule())
+  .addRule(new BinaryHasPartRedundancyRule());
 
 export function validateConcept(concept) {
   return _default.validate(concept);

package/src/validators/partitive-drift-rule.js

@@ -0,0 +1,51 @@
+// Warns when a concept expresses the same partitive relationship via
+// BOTH a binary edge (broader_partitive / narrower_partitive /
+// has_part / is_part_of) AND a PartitiveHyperedge part targeting the
+// same concept. Round 1's decision (TODO.hyperedges/24) was "binary
+// and hyperedge coexist, no automatic reconciliation." This rule is
+// the detector for the resulting drift: pure warning, doesn't block
+// save, just surfaces the duplication so the author can pick one
+// encoding.
+//
+// See TODO.hyperedges-v2/21 for the design rationale.
+
+import { ValidationRule } from './validation-rule.js';
+
+const BINARY_PARTITIVE_TYPES = new Set([
+  'broader_partitive', 'narrower_partitive',
+  'has_part', 'is_part_of',
+]);
+
+export class PartitiveDriftRule extends ValidationRule {
+  constructor() { super('partitive-drift', 'warning'); }
+
+  validate(concept, path, result) {
+    const hyperedgeTargets = new Set();
+    for (const he of concept.partitiveHyperedges ?? []) {
+      const comp = he.comprehensive;
+      const compKey = `${comp?.source ?? ''}|${comp?.id ?? ''}`;
+      for (const part of he.parts ?? []) {
+        const key = `${part.source ?? ''}|${part.id ?? ''}`;
+        if (key === '|' || key === compKey) continue;
+        hyperedgeTargets.add(key);
+      }
+    }
+
+    if (hyperedgeTargets.size === 0) return;
+
+    const related = concept.relatedConcepts ?? [];
+    for (let i = 0; i < related.length; i++) {
+      const rc = related[i];
+      if (!BINARY_PARTITIVE_TYPES.has(rc.type)) continue;
+      const ref = rc.ref;
+      const key = `${ref?.source ?? ''}|${ref?.id ?? ''}`;
+      if (hyperedgeTargets.has(key)) {
+        this.addIssue(result,
+          `${path}relatedConcepts[${i}]`,
+          `concept has both a binary '${rc.type}' edge and a ` +
+          `PartitiveHyperedge part targeting (${ref?.source ?? '?'}, ` +
+          `${ref?.id ?? '?'}); pick one encoding to avoid divergence`);
+      }
+    }
+  }
+}

package/src/validators/partitive-hyperedge-rule.js

@@ -0,0 +1,75 @@
+import { ValidationRule } from './validation-rule.js';
+
+// Validates semantic invariants of PartitiveHyperedge entries that
+// the model constructor does NOT enforce. The constructor already
+// rejects empty comprehensive, empty parts, self-loops, invalid
+// marker values, and duplicate markers. This rule provides a
+// defensive walk at validation time plus a warning for the
+// implicit-enumeration case (absent in the source YAML, filled by
+// the model's DEFAULT_ENUMERATION constant).
+export class PartitiveHyperedgeShapeRule extends ValidationRule {
+  constructor() { super('partitive-hyperedge-shape'); }
+
+  validate(concept, path, result) {
+    const edges = concept.partitiveHyperedges ?? [];
+    for (let i = 0; i < edges.length; i++) {
+      const he = edges[i];
+      const base = `${path}partitiveHyperedges[${i}]`;
+
+      this._checkComprehensive(he, i, base, result);
+      this._checkParts(he, i, base, result);
+      this._checkMarkers(he, i, base, result);
+      this._checkSelfLoop(he, i, base, result);
+    }
+  }
+
+  _checkComprehensive(he, idx, base, result) {
+    const ref = he.comprehensive;
+    if (!ref || (!ref.source && !ref.id)) {
+      this.addIssue(result, `${base}.comprehensive`,
+        `partitive_hyperedge ${idx + 1} has empty comprehensive`);
+    }
+  }
+
+  _checkParts(he, idx, base, result) {
+    const parts = he.parts ?? [];
+    if (parts.length === 0) {
+      this.addIssue(result, `${base}.parts`,
+        `partitive_hyperedge ${idx + 1} has no parts`);
+      return;
+    }
+    for (let j = 0; j < parts.length; j++) {
+      const p = parts[j];
+      if (!p || (!p.source && !p.id)) {
+        this.addIssue(result, `${base}.parts[${j}]`,
+          `partitive_hyperedge ${idx + 1} part ${j + 1} has empty ref`);
+      }
+    }
+  }
+
+  _checkMarkers(he, idx, base, result) {
+    const markers = he.markers ?? [];
+    const seen = new Set();
+    for (const m of markers) {
+      if (seen.has(m)) {
+        this.addIssue(result, `${base}.markers`,
+          `partitive_hyperedge ${idx + 1} has duplicate marker '${m}'`);
+      }
+      seen.add(m);
+    }
+  }
+
+  _checkSelfLoop(he, idx, base, result) {
+    const c = he.comprehensive;
+    if (!c) return;
+    const cKey = `${c.source ?? ''}:${c.id ?? ''}`;
+    for (let j = 0; j < (he.parts ?? []).length; j++) {
+      const p = he.parts[j];
+      const pKey = `${p?.source ?? ''}:${p?.id ?? ''}`;
+      if (pKey === cKey) {
+        this.addIssue(result, `${base}.parts[${j}]`,
+          `partitive_hyperedge ${idx + 1} part ${j + 1} cannot be the comprehensive`);
+      }
+    }
+  }
+}

package/src/validators/partitive-relation-coherence-rule.js

@@ -0,0 +1,107 @@
+// Validates PartitiveRelation coherence per ISO 704 / ISO 12620.
+//
+// Checks (per TODO.partitive-relation-v2 item 13):
+//   1. ERROR: each relation has ≥2 partitives (ISO 704 "two or more")
+//   2. ERROR: no two relations on the same concept share the same
+//      comprehensive + same criterion (duplicate decomposition —
+//      violates ISO 12620 coordinate-concept coherence)
+//   3. WARNING: a concept with multiple relations where any relation
+//      lacks criterion (cannot verify distinctness from siblings)
+//   4. WARNING: a TypeSharedPlurality with is_uncertain=true but
+//      is_shared=false (semantically odd — broken line qualifies
+//      the close-set double line; without `double`, what's being
+//      qualified?)
+//
+// Lives in the validator framework, not the model constructor, per
+// invariant I8 (TODO.hyperedges-v2/00). Constructors enforce type-shape;
+// validators enforce semantics.
+
+import { ValidationRule } from './validation-rule.js';
+
+export class PartitiveRelationCoherenceRule extends ValidationRule {
+  constructor() { super('partitive-relation-coherence'); }
+
+  validate(concept, path, result) {
+    const relations = concept.partitiveRelations ?? concept.partitiveHyperedges ?? [];
+    if (relations.length === 0) return;
+
+    // Check 1: ≥2 partitives per relation. (The constructor also
+    // rejects this, but a warning here surfaces it in the result
+    // bundle for CI visibility.)
+    for (let i = 0; i < relations.length; i++) {
+      const partitiveCount = (relations[i]?.partitives ?? []).length;
+      if (partitiveCount < 2) {
+        this.addIssue(result,
+          `${path}partitiveRelations[${i}].partitives`,
+          `PartitiveRelation ${i + 1} has ${partitiveCount} partitive(s); ` +
+          `ISO 704 requires ≥2 (use a binary has_part edge for pairwise facts)`,
+        );
+      }
+    }
+
+    // Check 2: no duplicate (comprehensive + criterion) on the same concept.
+    const seen = new Map();
+    for (let i = 0; i < relations.length; i++) {
+      const rel = relations[i];
+      const compKey = _conceptRefKey(rel?.comprehensive);
+      const critKey = _criterionKey(rel?.criterion);
+      if (compKey == null || critKey == null) continue;
+      const key = `${compKey}|${critKey}`;
+      if (seen.has(key)) {
+        this.addIssue(result,
+          `${path}partitiveRelations[${i}]`,
+          `duplicate PartitiveRelation (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 relations.
+    if (relations.length > 1) {
+      for (let i = 0; i < relations.length; i++) {
+        if (!relations[i]?.criterion) {
+          result.addWarning(
+            `${path}partitiveRelations[${i}].criterion`,
+            `concept has multiple PartitiveRelations but relation ${i + 1} ` +
+            `has no criterion; cannot verify distinctness from siblings`,
+          );
+        }
+      }
+    }
+
+    // Check 4: plurality coherence (warning).
+    for (let i = 0; i < relations.length; i++) {
+      const plural = relations[i]?.plurality;
+      if (!plural) continue;
+      if (plural.isUncertain && !plural.isShared) {
+        result.addWarning(
+          `${path}partitiveRelations[${i}].plurality`,
+          `plurality has isUncertain=true without isShared=true (semantically odd: ` +
+          `ISO 704 broken line qualifies the close-set double line plurality; ` +
+          `without double, what is being qualified?)`,
+        );
+      }
+    }
+  }
+}
+
+function _conceptRefKey(ref) {
+  if (!ref) return null;
+  const source = ref.source ?? '';
+  const id = ref.id ?? '';
+  if (!source && !id) return null;
+  return `${source}:${id}`;
+}
+
+function _criterionKey(criterion) {
+  if (!criterion || typeof criterion !== 'object') return null;
+  // Sort values for stable comparison regardless of language key order.
+  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/sourced-from-locality-rule.js

@@ -0,0 +1,53 @@
+// Validates that every ConceptSource#sourced_from Citation includes a
+// locality. Per concept-model commit 9c065df ("sourced_from citations
+// must include locality"), a sourced_from entry without a locality is
+// incomplete — the reader cannot locate the definition in the upstream
+// document. The schema (schemas/v3/concept.yaml) enforces this at
+// YAML-load time; this rule surfaces violations in already-parsed
+// Concepts for defense-in-depth.
+//
+// Severity: error. A sourced_from without locality is data loss for
+// the reader.
+
+import { ValidationRule } from './validation-rule.js';
+
+export class SourcedFromLocalityRule extends ValidationRule {
+  constructor() { super('sourced-from-locality', 'error'); }
+
+  validate(concept, path, result) {
+    const sources = concept.sources ?? [];
+    for (let i = 0; i < sources.length; i++) {
+      const source = sources[i];
+      const sourcedFrom = source.sourcedFrom ?? source.sourced_from ?? [];
+      for (let j = 0; j < sourcedFrom.length; j++) {
+        const citation = sourcedFrom[j];
+        const locality = citation?.locality;
+        if (!locality || (!locality.type && !locality.referenceFrom && !locality.reference_from)) {
+          this.addIssue(result,
+            `${path}sources[${i}].sourced_from[${j}].locality`,
+            `sourced_from citation ${j + 1} on source ${i + 1} has no locality ` +
+            `(expected type + reference_from so the reader can locate the definition)`);
+        }
+      }
+    }
+
+    for (const lang of concept.languages ?? []) {
+      const lc = concept.localization?.(lang);
+      if (!lc) continue;
+      const lcSources = lc.sources ?? [];
+      for (let i = 0; i < lcSources.length; i++) {
+        const source = lcSources[i];
+        const sourcedFrom = source.sourcedFrom ?? source.sourced_from ?? [];
+        for (let j = 0; j < sourcedFrom.length; j++) {
+          const citation = sourcedFrom[j];
+          const locality = citation?.locality;
+          if (!locality || (!locality.type && !locality.referenceFrom && !locality.reference_from)) {
+            this.addIssue(result,
+              `${path}localizations.${lang}.sources[${i}].sourced_from[${j}].locality`,
+              `sourced_from citation ${j + 1} on localization source ${i + 1} has no locality`);
+          }
+        }
+      }
+    }
+  }
+}