@ihabdevteam/core 0.8.0

package/dist/packages/core/src/utils/koreanSyllable.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 한글 음절 분해/조립/거리 계산 유틸
+ * @public
+ */
+export declare const CHOSEONG: readonly ["ㄱ", "ㄲ", "ㄴ", "ㄷ", "ㄸ", "ㄹ", "ㅁ", "ㅂ", "ㅃ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅉ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+export declare const JUNGSEONG: readonly ["ㅏ", "ㅐ", "ㅑ", "ㅒ", "ㅓ", "ㅔ", "ㅕ", "ㅖ", "ㅗ", "ㅘ", "ㅙ", "ㅚ", "ㅛ", "ㅜ", "ㅝ", "ㅞ", "ㅟ", "ㅠ", "ㅡ", "ㅢ", "ㅣ"];
+/** 종성 0번은 받침 없음 */
+export declare const JONGSEONG: readonly ["", "ㄱ", "ㄲ", "ㄳ", "ㄴ", "ㄵ", "ㄶ", "ㄷ", "ㄹ", "ㄺ", "ㄻ", "ㄼ", "ㄽ", "ㄾ", "ㄿ", "ㅀ", "ㅁ", "ㅂ", "ㅄ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+export interface Syllable {
+    cho: number;
+    jung: number;
+    jong: number;
+}
+/** @public 한 글자를 초/중/종성으로 분해. 한글 음절이 아니면 null. */
+export declare function parseSyllable(ch: string): Syllable | null;
+/**
+ * @public 단어→음절 분해 배열 캐시 팩토리. `[...word].map(parseSyllable)`를 단어당 1회만 수행한다.
+ * 캐시 수명은 호출부가 소유한다 — 모듈 레벨에 두면 영속, 함수 안에 두면 호출당 새 캐시.
+ * (프리뷰 편집기와 wordTrainingRuntime이 동일 로직을 중복 정의하던 것을 단일화.)
+ */
+export declare function createDecompCache(): (word: string) => (Syllable | null)[];
+/** @public 초/중/종성 index로 한글 음절 조립. */
+export declare function composeSyllable(cho: number, jung: number, jong?: number): string;
+/**
+ * 두 단어의 음운 차이 분류 (학습 단계).
+ *  - 'cho'   : 정확히 한 음절에서 초성만 차이 (예: 가구↔나구, 강↔망)
+ *  - 'jung'  : 정확히 한 음절에서 중성만 차이 (예: 가↔거, 보↔바)
+ *  - 'jong'  : 정확히 한 음절에서 종성만 차이 (예: 가↔강, 강↔강)
+ *  - 'random': 그 외 — 음절 수가 다르거나, 2음절 이상 차이, 또는 한 음절에서 2개 이상 구성요소 차이
+ * @public
+ */
+export type DifficultyLevel = 'random' | 'jong' | 'jung' | 'cho' | 'count';
+export declare function classifyPairDifficulty(a: string, b: string): DifficultyLevel;
+/** @public 단어의 초성 자모 ('가구' → 'ㄱ') */
+export declare function firstChoseongOf(word: string): string;
+/** @public 문자열 전체를 초성으로 변환 ('한지민' → 'ㅎㅈㅁ'). 한글 음절이 아닌 문자는 그대로 유지. */
+export declare function toChoseong(text: string): string;
+/** @public 검색어가 초성으로만 이루어졌는지 (예: 'ㅎㅈ' → true, '한' → false) */
+export declare function isAllChoseong(search: string): boolean;
+/**
+ * @public 초성 검색을 지원하는 부분 일치 매칭 — 검색어가 전부 초성이면 대상 텍스트도
+ * 초성으로 변환해 비교(예: 'ㄷ' → '단어 표' 매칭), 아니면 일반 부분 문자열 매칭.
+ */
+export declare function matchesChoseongSearch(text: string, search: string): boolean;
+/**
+ * @public 단어 검색어 매칭(부분 일치=contains) — 검색어의 각 글자가 '완성 음절'이거나 '음소 자모'(초성·중성)인
+ * 혼합 검색을 지원한다. 완성 음절은 그 자리 음절과 정확히 같아야 하고, 자음 자모는 그 자리 음절의 초성과,
+ * 모음 자모는 그 자리 음절의 중성과 같으면 된다 — 위치(앞·중간·뒤) 무관.
+ * 예: 'ㄱ'→'가수'(초성 ㄱ), 'ㅏ'→'가수'(중성 ㅏ), 'ㄱㅅ'→'가수', '가ㄴ'→'가난', 'ㄱ수'→'가수', '가수'→'가수'.
+ * 검색어에 종성 겹자모·비한글 등 위 종류가 아닌 문자가 있으면 일반 부분 문자열로 폴백한다.
+ */
+export declare function matchesWordQuery(word: string, query: string): boolean;
+/** @public 복합 종성 index → 구성 자모 배열 (예: 9(ㄺ) → ['ㄹ','ㄱ']) */
+export declare const JONG_DECOMPOSE: Record<number, string[]>;
+/** @public 단어가 특정 자모(음소)를 어디든 (초성/종성/복합종성) 포함하는지 */
+export declare function wordContainsPhoneme(word: string, jamo: string): boolean;
+/** @public 단어가 특정 자모를 초성(onset)으로 포함하는지 */
+export declare function wordContainsChoseong(word: string, jamo: string): boolean;
+/** @public 단어가 특정 모음을 중성(vowel)으로 포함하는지 */
+export declare function wordContainsJungseong(word: string, jamo: string): boolean;
+/** @public 단어가 특정 자모를 종성(coda)으로 포함하는지.
+ *  글자 입력: 겹받침 '원형'(ㅄ 등) 정확 매칭. 발음 입력: 겹받침을 구성 자모(ㅂ 등)로 분해해 대표음 매칭. */
+export declare function wordContainsJongseong(word: string, jamo: string): boolean;
+/** @public 단어의 한글 음절 개수 (한글 이외 문자는 제외) */
+export declare function syllableLength(word: string): number;
+/** @public 단어의 모든 한글 음절에 종성(받침)이 없는지 (열린 음절로만 구성) */
+export declare function wordHasNoCoda(word: string): boolean;
+/**
+ * @public 단어에 '하나의 음절'이 주어진 초성/중성/종성 제약을 **모두** 만족하는지.
+ * 여러 자리를 함께 선택하면 서로 다른 음절에 흩어져 있는 게 아니라 같은 음절에서 결합해야 한다
+ * (예: 초성 ㄱ + 종성 ㅇ → '강'·'공'만 매칭, '코딩'처럼 다른 음절에 흩어진 건 제외).
+ * 각 제약은 배열(OR) — 미지정(null/undefined) 자리는 검사하지 않는다. jongNone은 그 음절이 받침 없음.
+ */
+export declare function wordHasSyllableMatching(word: string, parts: {
+    cho?: string[] | null;
+    jung?: string[] | null;
+    jong?: string[] | null;
+    jongNone?: boolean;
+}, position?: 'head' | 'mid' | 'tail' | null): boolean;
+/**
+ * @public 문자열이 음절 패턴 DSL 문법인지 — 쉼표(,) 포함 여부로 판별한다.
+ * 일반 단어 검색어엔 쉼표가 쓰이지 않으므로 충돌 없이 자동 분기할 수 있다.
+ */
+export declare function isSyllablePattern(query: string): boolean;
+/**
+ * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 자리(음절) 단위로 자동 분해하며,
+ * **분해된 총 자리 수는 반드시 단어의 음절 수와 같아야** 매칭된다. 한 자리는 다음 중 하나:
+ *  - 빈 자리(쉼표 사이가 비어 있음) — 무관(아무 음절이나 허용).
+ *  - 완성 음절 한 글자(예: '가') — 그 자리 음절이 정확히 이 글자와 같아야 함.
+ *  - 자음/모음 한 글자(예: 'ㄴ', 'ㅏ') — 자음이면 그 자리 초성이, 모음이면 그 자리 중성이 정확히 그
+ *    자모여야 함(나머지는 무관).
+ *  - 초성·중성·종성 3자모 템플릿(예: '__ㄱ', 쉼표로 나눈 조각이 정확히 3글자일 때만) — 각 자리가 '_'면
+ *    무관, 자모면 그 위치(초성/중성/종성)가 정확히 그 자모여야 함. 종성 자리 '_'는 받침 유무 모두 허용.
+ * 쉼표 사이에 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 자동 분해된다
+ * (3글자로 붙이면 템플릿과 구분이 안 되므로 예외 — 그 경우는 쉼표로 나눠 쓴다).
+ * 예: '가,,다' → 3음절, 첫 음절 '가' · 가운데 무관 · 끝 음절 '다'.
+ * 예: '__ㄱ,고' → 2음절, 첫 음절 종성이 'ㄱ'(초성·중성 무관) · 끝 음절 '고'.
+ * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 4음절, 첫 음절 '가' · 둘째 음절 초성 'ㄴ' · 셋째 무관 · 넷째 '다'.
+ * 해석할 수 없는 글자(자음·모음·완성 음절이 아님)가 섞이면 그 자리는 항상 매칭 실패 처리되어 결과가
+ * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
+ */
+export declare function matchesSyllablePattern(word: string, pattern: string): boolean;
+/**
+ * @public 음절 패턴 DSL을 대립쌍 생성용 구성요소(초성/중성/종성) 집합으로 축약한다.
+ * 패턴의 모든 자리(atom)가 지정한 초성/중성/종성 자모를 종류별로 합집합(OR)해 돌려준다 —
+ * 훈련 '글자 입력' 모드에서 이 조합을 buildMultiPartPosContrast에 넣어 (위치 지정과 함께)
+ * "그 자리의 해당 음소만 다른 최소대립쌍"을 오답으로 만든다.
+ * 예: 'ㄱ,ㄱ'(연속 초성 ㄱ) → { cho: ['ㄱ'] } → 위치 음절의 초성만 다른 실단어가 오답.
+ *     'ㄱ_ㄱ'(초성 ㄱ·종성 ㄱ) → { cho: ['ㄱ'], jong: ['ㄱ'] }.
+ * 완성 음절 자리('가')는 그 음절의 초성·중성(·종성)을 모두 제약으로 넣는다.
+ * 지정된 음소가 하나도 없으면(무관/무효 자리뿐) null — 호출부는 무작위 오답으로 폴백한다.
+ */
+export declare function patternToComposition(pattern: string): {
+    cho: string[] | null;
+    jung: string[] | null;
+    jong: string[] | null;
+} | null;
+/**
+ * @public 단어 검색 '글자 입력'의 형식 유효성 검사.
+ * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), 초성·중성·종성 3자모 템플릿('__ㄱ', 정확히 3글자),
+ * 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: '_' 오용, 라틴 문자, 한 자리에 음소 4개 이상인 '___ㄱ')는 무효.
+ * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
+ */
+export declare function validateSyllableSearchInput(input: string): {
+    ok: boolean;
+};
+/** @public 단어 구성요소 종류 (초성/중성/종성) */
+export type CompositionPart = 'cho' | 'jung' | 'jong';
+/**
+ * @public
+ * 정확히 `count`개 음절에서 지정 구성요소(초성/중성/종성)만 다르고 나머지 성분은 완전히 동일한
+ * 실제 단어들을 찾는다. (compose-and-check 방식 — wordSet 멤버십으로 실재 단어만 반환)
+ *
+ * 예: findTypedContrastWords('가수', 'jung', 2, set) → ['개시','고소','기사', …] (모음 2곳 차이)
+ *
+ * @param word     기준 단어
+ * @param type     대립 종류 (cho/jung/jong)
+ * @param count    차이 나는 음절 수 (대립 갯수)
+ * @param wordSet  유효 단어 집합 (여기 포함된 단어만 결과에 포함)
+ * @param limit    최대 결과 수 (조기 종료로 연산량 제한, 기본 Infinity)
+ */
+export declare function findTypedContrastWords(word: string, type: CompositionPart, count: number, wordSet: Set<string>, limit?: number): string[];
+/**
+ * @public
+ * 위치 구분 없이 두 단어의 서로 다른 음소(초성/중성/종성 슬롯) 총 개수를 센다.
+ * 음절 수가 다르거나 한글이 아닌 문자가 있으면 -1.
+ * 예: countPhonemeDiff('독립','독일') → 2 (둘째 음절 초성 ㄹ↔ㅇ, 종성 ㅂ↔ㄹ)
+ */
+export declare function countPhonemeDiff(a: string, b: string): number;
+/**
+ * 단어 목록을 검색어로 거르고, 앞에서부터 맞는 것을 위로 올린다.
+ *
+ * 회원 앱의 '단어 관리'와 어드민의 '데이터 → 단어'가 이 규칙을 각자 한 벌씩 적고
+ * 있었다. 주석까지 서로를 가리키고 있었는데("회원 앱 '단어 관리'와 같은 매칭 규칙",
+ * "단어표 '글자 입력'과 동일 규약") — 알면서 베낀 것이다. 한쪽만 고치면 두 화면이
+ * 같은 검색어에 다른 결과를 내놓는다.
+ *
+ * 규칙은 셋이다.
+ *  · **의미 없는 입력은 조건으로 보지 않는다.** 공백·쉼표·밑줄만 남은 것은 아직 다
+ *    치지 않은 패턴이라, 그걸로 거르면 목록이 통째로 빈다.
+ *  · **패턴 DSL 이면 자리 맞춤으로 본다**('ㄱ_ㄱ' 처럼). 아니면 초성·완성음절+초성·
+ *    부분문자열을 모두 받는 공용 매칭으로 본다.
+ *  · **앞에서부터 맞는 것을 위로.** '나'로 찾을 때 '가시나무'가 먼저 나오면 '나무'가
+ *    묻힌다. 앞 글자 수만큼 잘라 맞춰 보면 '첫 음절부터 일치'만 남는다(초성도 같다).
+ *    같은 순위 안에서는 원래 순서를 지킨다 — Array.sort 가 안정 정렬이다.
+ *
+ * @param items 거를 목록 — 단어와 발음을 가진 것이면 무엇이든
+ * @param query 사용자가 친 검색어(다듬지 않은 것을 그대로 넘겨도 된다)
+ * @public
+ */
+export declare function searchAndRankWords<T extends {
+    word: string;
+    pronunciation?: string | null;
+}>(items: T[], query: string): T[];