@jeongpd/korean-kinship 0.1.0 → 0.1.2

package/README.md

@@ -3,6 +3,7 @@
 **Resolve any Korean family-relationship path to its correct kinship term, reverse
 term, and 촌수 (degree of kinship) — including in-laws and 사돈.**
 
+[![CI](https://github.com/tiger-dreams/korean-kinship/actions/workflows/ci.yml/badge.svg)](https://github.com/tiger-dreams/korean-kinship/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@jeongpd/korean-kinship.svg)](https://www.npmjs.com/package/@jeongpd/korean-kinship)
 [![license](https://img.shields.io/npm/l/@jeongpd/korean-kinship.svg)](https://github.com/tiger-dreams/korean-kinship/blob/main/LICENSE)
 [![node](https://img.shields.io/node/v/@jeongpd/korean-kinship.svg)](https://www.npmjs.com/package/@jeongpd/korean-kinship)
@@ -71,6 +72,36 @@ Chain them to describe any relative — `['mother', 'olderSis', 'spouse']` is "
 `opts.selfGender` (`'M'` or `'F'`) disambiguates terms that depend on the speaker's own
 gender — e.g. your spouse is 아내 if you're male, 남편 if you're female.
 
+## Judging confidence: `source` and `note`
+
+This library doesn't decide for you whether an answer is trustworthy enough to show
+as-is — it tells you where the answer came from, and your app decides what to do with
+that:
+
+- **`source: 'golden'`** — an exact match against one of the 145 entries ported from a
+  real, shipping app and checked against real usage (see [Where this data comes
+  from](#where-this-data-comes-from)). This is the answer for the overwhelming
+  majority of relationships anyone will actually ask about.
+- **`source: 'fallback-table'`** — a curated Tier-2 entry for a specific pattern beyond
+  the 145 (currently empty in v1; see [`src/data/fallback-terms.js`](./src/data/fallback-terms.js)).
+- **`source: 'generic'`** — nothing in either table matched, so `resolve()` computed a
+  generic pattern (e.g. `"6촌 손자"`) from 촌수 and generation distance instead of
+  failing. It's a defensible answer, not a verified one — Korean doesn't have a
+  single dedicated term for every possible relationship past a certain distance.
+
+`note`, where present, is the original entry's own usage context (e.g. `"큰아버지의
+아내"`) — not generated, and only ever present on `'golden'` results.
+
+Whether to surface any of this to *your* end users — a "verified" badge, a footnote, or
+nothing at all — is your call, not the library's:
+
+```js
+const result = resolve(path, { selfGender });
+const isVerified = result.source === 'golden';
+// e.g.: render result.label normally either way, but only show a
+// "✓ 검증된 호칭" badge when isVerified — your app, your judgment call.
+```
+
 ## Other exports
 
 Alongside `resolve`, the package exports the underlying data so you can drive your own
@@ -125,16 +156,37 @@ Korean family-tree app, validated against actual usage. See
 [`docs/DATA_PROVENANCE.md`](./docs/DATA_PROVENANCE.md) for details, or
 `scripts/import-golden-terms.mjs` for the exact extraction method.
 
+## Testing
+
+`npm test` runs the full suite (`node --test`, no test framework dependency), covering:
+
+- All 145 golden entries, both `selfGender` values, checked field-by-field
+  (`label`, `reverseLabel`, `formal`, `chon`) — not just a spot check.
+- A dedicated sweep asserting no relation path ever resolves to an `undefined` or
+  empty label, across every golden path plus a broad set of fallback-path
+  combinations.
+- The compositional fallback's chon arithmetic (plain edge-sum, verified by hand
+  against a manual review) covering paths outside the golden table.
+
+CI (see badge above) runs this suite on every push, on Node 18 and 20 — the badge
+reflects the actual current state of `main`, not a claim in this README. Separately,
+`resolve(['father', 'youngerBro'])` was checked against a real, independently
+maintained Android app's own verified data contract before this library was wired
+into production use (see [`docs/DATA_PROVENANCE.md`](./docs/DATA_PROVENANCE.md)).
+
 ## Why not just a lookup table?
 
 For the ~145 most common relationships, it is exactly a lookup table — that's Tier 1,
 and it's returned verbatim because it encodes real, occasionally non-obvious Korean
 usage conventions (for example: your sibling's spouse and your spouse's parents are
 conventionally given `chon: 0`, "just family," while your uncle's wife keeps your
-uncle's own `chon: 3` — these aren't derivable from one clean formula). For anything
-past that table, `resolve()` falls back to a compositional algorithm that computes
-촌수 and blood/in-law class from the path directly, so arbitrarily deep or unusual
-relationship chains still get a sensible answer instead of an error.
+uncle's own `chon: 3` — these aren't derivable from one clean formula, they're curated
+per entry). For anything past that table, `resolve()` falls back to a compositional
+algorithm that computes 촌수 as a plain edge sum and blood/in-law class from the path
+directly — it does not try to re-derive the golden table's "no number for close
+in-laws" convention (an earlier version tried, and silently mis-scored real 4th-degree
+relatives as chon 0), so arbitrarily deep or unusual relationship chains still get an
+arithmetically correct answer instead of an error or a guessed zero.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeongpd/korean-kinship",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Resolve any Korean family-relationship path to its correct kinship term, reverse term, and 촌수 (degree of kinship) — including in-laws and 사돈.",
   "type": "module",
   "main": "./src/index.js",

package/src/data/fallback-terms.js

@@ -51,16 +51,20 @@ function baseTerm(generationDelta, terminalGender) {
 /**
  * Last-resort label for a path with no Tier-1 or Tier-2 entry.
  *
- * `chon: 0` means "close family, no numeral" in this codebase's convention (the golden
- * entries with chon 0 — 장인어른, 며느리, 동서 — never carry a number), so the numeral
- * is omitted entirely rather than rendered as a nonsensical "0촌".
+ * `chon: 0` means "no numeral" in this codebase's convention (the golden entries with
+ * chon 0 — 장인어른, 며느리, 동서 — never carry a number), so the numeral is omitted
+ * entirely rather than rendered as a nonsensical "0촌". Note this does NOT mean the
+ * relation is necessarily close — the chon-cutoff rule in resolve.js also assigns
+ * chon: 0 to any relation reached past the first spouse hop, including genuinely
+ * distant ones (e.g. an uncle-by-marriage's own sibling's child) — so the label omits
+ * the numeral but must not claim closeness either.
  */
 export function genericFallback({ chon, generationDelta, relationClass, terminalGender }) {
   const base = baseTerm(generationDelta, terminalGender);
   const numeral = chon > 0 ? `${chon}촌 ` : '';
 
   if (relationClass === 'inlaw') {
-    return chon > 0 ? `인척 ${numeral}${base}` : `가까운 인척 ${base}`;
+    return `인척 ${numeral}${base}`;
   }
   return `${numeral}${base}`;
 }

package/src/resolve.js

@@ -24,9 +24,6 @@ function pickBySelfGender(record, selfGender) {
 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
@@ -34,7 +31,7 @@ export function walkPath(path) {
   // hops has no gendered person to anchor on).
   let terminalGender = null;
 
-  for (const [index, id] of path.entries()) {
+  for (const id of path) {
     const rel = PRIMITIVES[id];
     generationDelta += rel.generationDelta;
     chonEdges += rel.edgeCost;
@@ -44,36 +41,29 @@ export function walkPath(path) {
     }
 
     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 };
+  // 촌수 here is always the plain edge sum — spouse hops cost nothing (부부는
+  // 무촌), so a spouse's blood relatives count from the spouse exactly as a
+  // careful speaker would by hand (배우자의 오빠의 딸의 딸 = 0+2+1+1 = 4촌).
+  //
+  // The golden table (Tier 1) separately encodes a real but *uncomputable*
+  // convention: Korean omits the number entirely for a specific, curated set of
+  // close relations (며느리, 처남, 사돈 — the golden entries with chon: 0). That
+  // convention does not generalize into a formula — an earlier version of this
+  // function tried to derive one ("zero any hop past the first spouse hop") and
+  // it silently mis-scored genuine 4th-degree relatives like the example above
+  // as chon 0. Since Tier 1 always resolves before walkPath() ever runs, this
+  // function doesn't need to reproduce that convention — it only has to be
+  // arithmetically correct for paths the golden table doesn't already cover.
+  return { generationDelta, relationClass, olderYounger, chon: chonEdges, terminalGender };
 }
 
 // The descriptor key deliberately omits 친가/외가/처가/시가 `side`. Detecting it