@jeongpd/korean-kinship 0.1.0

package/src/index.js

@@ -0,0 +1,5 @@
+export { resolve } from './resolve.js';
+export { GOLDEN_TERMS as termTable } from './data/golden-terms.js';
+import { PRIMITIVES } from './primitives.js';
+
+export const relationIds = Object.keys(PRIMITIVES);

package/src/primitives.js

@@ -0,0 +1,15 @@
+export const PRIMITIVES = {
+  father:     { generationDelta: 1,  edgeCost: 1, gender: 'M',  category: 'parent' },
+  mother:     { generationDelta: 1,  edgeCost: 1, gender: 'F',  category: 'parent' },
+  olderBro:   { generationDelta: 0,  edgeCost: 2, gender: 'M',  category: 'sibling', order: 'older' },
+  olderSis:   { generationDelta: 0,  edgeCost: 2, gender: 'F',  category: 'sibling', order: 'older' },
+  youngerBro: { generationDelta: 0,  edgeCost: 2, gender: 'M',  category: 'sibling', order: 'younger' },
+  youngerSis: { generationDelta: 0,  edgeCost: 2, gender: 'F',  category: 'sibling', order: 'younger' },
+  son:        { generationDelta: -1, edgeCost: 1, gender: 'M',  category: 'child' },
+  daughter:   { generationDelta: -1, edgeCost: 1, gender: 'F',  category: 'child' },
+  spouse:     { generationDelta: 0,  edgeCost: 0, gender: null, category: 'spouse' },
+};
+
+export function isValidRelationId(id) {
+  return Object.prototype.hasOwnProperty.call(PRIMITIVES, id);
+}

package/src/resolve.js

@@ -0,0 +1,138 @@
+import { PRIMITIVES, isValidRelationId } from './primitives.js';
+import { GOLDEN_TERMS } from './data/golden-terms.js';
+import { FALLBACK_TERMS, genericFallback } from './data/fallback-terms.js';
+
+function assertValidPath(path) {
+  if (!Array.isArray(path) || path.length === 0) {
+    throw new Error('resolve() requires a non-empty array of relation ids');
+  }
+  for (const id of path) {
+    if (!isValidRelationId(id)) {
+      throw new Error(`Unknown relation id: "${id}"`);
+    }
+  }
+}
+
+function pickBySelfGender(record, selfGender) {
+  if (selfGender === 'F' && record.F !== undefined) return record.F;
+  if (selfGender === 'M' && record.M !== undefined) return record.M;
+  return record.M ?? record.F;
+}
+
+// Exported for the compositional-rule tests only — not re-exported from src/index.js,
+// and package `exports` blocks deep imports, so this is not public API.
+export function walkPath(path) {
+  let generationDelta = 0;
+  let chonEdges = 0;
+  let bloodChonSoFar = 0;
+  let bloodChonAtFirstSpouse = null;
+  let firstSpouseIndex = null;
+  let relationClass = 'blood';
+  let olderYounger = null;
+  // Gender of the person the path lands on. Every primitive but `spouse` fixes it
+  // outright; a spouse hop flips it (null stays null — a path of nothing but spouse
+  // hops has no gendered person to anchor on).
+  let terminalGender = null;
+
+  for (const [index, id] of path.entries()) {
+    const rel = PRIMITIVES[id];
+    generationDelta += rel.generationDelta;
+    chonEdges += rel.edgeCost;
+
+    if (rel.category === 'sibling') {
+      olderYounger = rel.order;
+    }
+
+    if (rel.category === 'spouse') {
+      if (firstSpouseIndex === null) {
+        firstSpouseIndex = index;
+        bloodChonAtFirstSpouse = bloodChonSoFar;
+      }
+      relationClass = 'inlaw';
+      if (terminalGender !== null) {
+        terminalGender = terminalGender === 'M' ? 'F' : 'M';
+      }
+    } else {
+      bloodChonSoFar += rel.edgeCost;
+      terminalGender = rel.gender;
+    }
+  }
+
+  // In-law 촌수 is not the blood chon carried through. Korean puts no number on a
+  // relation once the chain crosses into another family: any hop *after* the first
+  // spouse hop (a second marriage link, or a blood hop taken from the spouse's own
+  // family — 사돈 territory) reports chon 0, as does a spouse hop onto a close blood
+  // relative (chon ≤ 2 at that point: self, child, sibling). Only a spouse hop onto a
+  // distant blood relative with nothing after it keeps that relative's own chon
+  // (큰아버지 3촌 → 큰어머니 3촌).
+  const hopsAfterFirstSpouse = firstSpouseIndex === null
+    ? 0
+    : path.length - 1 - firstSpouseIndex;
+
+  const chon = relationClass === 'inlaw'
+    ? ((hopsAfterFirstSpouse > 0 || bloodChonAtFirstSpouse <= 2) ? 0 : bloodChonAtFirstSpouse)
+    : chonEdges;
+
+  return { generationDelta, relationClass, olderYounger, chon, terminalGender };
+}
+
+// The descriptor key deliberately omits 친가/외가/처가/시가 `side`. Detecting it
+// correctly means finding the first hop that branches off the direct blood line (and
+// 처가 vs 시가 depends on opts.selfGender) — the previous implementation instead took
+// any father/mother hop at any position, which mis-tagged 사돈 paths like
+// son.spouse.father as 'paternal'. FALLBACK_TERMS is empty, so no entry needs side
+// yet; add it here, correctly, alongside the first Tier-2 entry that actually keys on it.
+function descriptorKey({ generationDelta, relationClass, olderYounger }) {
+  return [generationDelta, relationClass, olderYounger ?? '-'].join('|');
+}
+
+export function resolve(path, opts = {}) {
+  assertValidPath(path);
+  const selfGender = opts.selfGender;
+
+  const exact = GOLDEN_TERMS[path.join('.')];
+  if (exact) {
+    return {
+      path: [...path],
+      label: pickBySelfGender(exact, selfGender),
+      reverseLabel: exact.rev_M !== undefined
+        ? pickBySelfGender({ M: exact.rev_M, F: exact.rev_F }, selfGender)
+        : undefined,
+      chon: exact.chon,
+      formal: exact.formal !== undefined
+        ? exact.formal
+        : (exact.formal_M !== undefined || exact.formal_F !== undefined
+          ? pickBySelfGender({ M: exact.formal_M, F: exact.formal_F }, selfGender)
+          : undefined),
+      note: exact.note,
+      // Golden entries don't record it, but the same rule the compositional path uses
+      // applies: any spouse hop anywhere in the chain makes it an in-law relation.
+      relationClass: path.includes('spouse') ? 'inlaw' : 'blood',
+      source: 'golden',
+    };
+  }
+
+  const descriptor = walkPath(path);
+  const key = descriptorKey(descriptor);
+  const fallback = FALLBACK_TERMS[key];
+  if (fallback) {
+    return {
+      path: [...path],
+      label: pickBySelfGender(fallback, selfGender),
+      reverseLabel: fallback.rev_M !== undefined
+        ? pickBySelfGender({ M: fallback.rev_M, F: fallback.rev_F }, selfGender)
+        : undefined,
+      chon: descriptor.chon,
+      relationClass: descriptor.relationClass,
+      source: 'fallback-table',
+    };
+  }
+
+  return {
+    path: [...path],
+    label: genericFallback(descriptor),
+    chon: descriptor.chon,
+    relationClass: descriptor.relationClass,
+    source: 'generic',
+  };
+}