@jeongpd/korean-kinship 0.1.0 → 0.1.1

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,6 +156,24 @@ 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 chon-cutoff rule independently re-verified against all 45
+  spouse-containing golden entries.
+
+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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeongpd/korean-kinship",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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}`;
 }