@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,122 @@
+/**
+ * 단어훈련 문제생성 **공유 코어** (F19 통합).
+ * 편집기 미리보기(WordTrainingTypePreview)와 러너/런타임(wordTrainingRuntime)이
+ * 각자 중복 구현하던 "대립쌍 오답 생성" 규칙을 단일 출처로 모은다.
+ *
+ * 순수 함수만 둔다 — 오디오코드/id/async/이미지체크는 각 소비처 어댑터 책임.
+ * 발음 조회는 pronMap(단어→표준발음)을 인자로 받는다(런타임은 getPronMap(), 편집기는 자체 Map 주입).
+ */
+import { type Syllable } from './koreanSyllable';
+import { type CompositionFilter } from './wordTrainingRuntimeTypes';
+/**
+ * @public 1음절 단어를 합치기용 음소(초성 자음 + 중성 모음 [+ 종성])로 분해. 음소 합치기 문제용.
+ * 예: '가' → ['ㄱ','ㅏ'], '강' → ['ㄱ','ㅏ','ㅇ']. 파싱 실패 시 [word].
+ */
+export declare function phonemePartsOf(word: string): string[];
+/**
+ * @public 합치기 문제 **표시** 문장 — 미리보기·러너 공용. 음절/음소 모두 원문(자모는 자모 그대로: 'ㄱ','ㅏ')로 표시한다.
+ * TTS로 읽을 땐 자모를 낱자 이름으로 바꿔야 하지만(그건 jamoToNamesForSpeech가 합성 경로에서 처리), 화면 표기는 자모 유지.
+ * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"와 "ㅏ"를 합치면 어떤 소리가 되나요?`
+ */
+export declare function mergeQuestionText(parts: string[], phoneme?: boolean): string;
+/**
+ * @public 합치기 카드 질문 문장 — 러너(재생)·프리워밍 공용 단일 출처. typeKey로 음소 여부를 판별해 mergeQuestionText 호출.
+ */
+export declare function getMergeCardTitle(typeKey: string | undefined, parts: string[]): string;
+/**
+ * @public 바꾸기(대치) 카드 질문 문장 — 러너·프리워밍 공용. item의 word/changedFrom/changedTo로 구성.
+ * 프리워밍이 만든 문장이 러너 재생 문장과 문자 단위로 같아야 캐시 키가 일치하므로 반드시 이 함수를 공유한다.
+ */
+export declare function getChangeCardTitle(typeKey: string | undefined, item: Record<string, unknown>): string;
+/**
+ * @public 탈락(삭제) 카드 질문 문장 — 러너·프리워밍 공용. item의 word/dropped/missingConsonant로 구성.
+ */
+export declare function getDropCardTitle(typeKey: string | undefined, item: Record<string, unknown>): string;
+/**
+ * @public 카드형(합치기/바꾸기/탈락) 질문 문장을 반환한다. 카드형이 아니면 '' (빈 문자열).
+ * 러너(WordManipulationTrainingPagePopup.getCardStepMeta)와 프리워밍(앱)의 **단일 출처** — 그룹 판정(cardGroupOf)과
+ * 문장 문구를 한 곳에 모아, 프리워밍이 만든 문장과 러너가 재생하는 문장이 항상 문자 단위로 일치하게 한다.
+ */
+export declare function cardQuestionTitle(typeKey: string | undefined, item: Record<string, unknown>, parts: string[]): string;
+/**
+ * @public TTS 전용 변환 — 문장 속 따옴표로 감싼 낱개 자모("ㄱ")를 낱자 이름("기역")으로 치환하고 뒤 조사를 맞춘다.
+ * 표시 텍스트는 자모 그대로 두고(교육용 표기), 합성·캐시 키에만 이 변환을 적용한다. 자음은 명칭(ㄱ→기역),
+ * 모음은 소릿값(ㅏ→아). 음소 합치기뿐 아니라 음소 바꾸기·자음 탈락 등 자모가 든 모든 문장에 공통 적용된다.
+ */
+export declare function jamoToNamesForSpeech(text: string): string;
+/** 표준발음 조회 — 없으면 단어 자체(발음 데이터 없는 경우의 안전한 폴백). */
+declare function pronOf(word: string, pronMap: Map<string, string>): string;
+/**
+ * @public 음절 끝소리 규칙 — 종성을 7종성(ㄱㄴㄷㄹㅁㅂㅇ)으로 중화한 '표준발음' 음절.
+ * 합성 음절(대립쌍 오답)은 pronMap에 없어 발음이 비므로 단일 음절 발음을 계산해 채운다.
+ * (초성 그대로, 종성만 중화. 겹받침은 대표음. 단일 음절이 아니면 '' — 다음절 단어를 잘못 자르지 않게.)
+ */
+export declare function syllablePron(ch: string): string;
+/**
+ * @public 음절의 실제 소리(표준발음). pronMap에 있으면 그것, 없으면(합성 음절) 끝소리 규칙 발음, 그래도 없으면 철자.
+ * (예: '밡'·'밖'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
+ */
+export declare function soundOf(syll: string, pronMap: Map<string, string>): string;
+/** @public comp에서 실제로 선택된 파트 1개(초성 우선)를 반환. 없으면 null. */
+export declare function primarySelPart(comp: CompositionFilter | null): 'cho' | 'jung' | 'jong' | null;
+/** @public 음절(분해값 s)이 comp의 선택 파트들과 모두 일치하는지(=선택 음소를 가진 음절). */
+export declare function syllMatchesComp(s: Syllable, comp: CompositionFilter): boolean;
+/**
+ * @public 발음 모드에서 comp 매칭에 쓸 음절 배열. 표준발음(pronMap)의 음절수가 철자와 같으면 발음 음절로,
+ * 아니면(연음 등으로 정렬 불가) 철자 음절로 매칭한다. 대립 오답 생성은 항상 철자 기준(소리로 중복제거).
+ */
+export declare function matchSyllables(word: string, pronMap: Map<string, string>, phonemeView: 'char' | 'pron'): (Syllable | null)[];
+/**
+ * @public 정답 음절(분해 cs)의 지정 파트를 다른 음소로 바꿔 대립쌍 음절 n개 생성.
+ * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밡/밖→박)이 함께 나오지 않게 한다.
+ */
+export declare function syllableContrasts(cs: Syllable, part: 'cho' | 'jung' | 'jong', correct: string, n: number, pronMap: Map<string, string>): string[];
+/** @public 훈련 문제 한 개(편집기·러너 공용). distractors[0]=정답, 이후=오답. */
+export interface TrainingProblem {
+    question: string;
+    distractors: string[];
+}
+/**
+ * @public 2음절 단어 → [문제단어, 남는 1음절(정답), 대립쌍 오답 2]. 정답·오답 모두 '실단어'(wordSet)만 인정.
+ * 음소가 든 음절(T)을 남기고 다른 음절 탈락 → 남는 1음절이 실단어이고, 그 음절의 초성/중성/종성 대립 실단어가
+ * 2개 이상인 경우만 채택. 음소 미선택 시 무작위 음절. (편집기 미리보기·런타임 자동생성 공용.)
+ */
+export declare function buildDropContrastProblem(word: string, comp: CompositionFilter | null, pronMap: Map<string, string>, phonemeView: 'char' | 'pron', wordSet: Set<string>, dropPos?: number | null): TrainingProblem | null;
+/**
+ * @public 3음절 단어 → [문제단어, 남는 2음절(정답), 대립쌍 오답 2]. 정답·오답 모두 '실단어'만 인정.
+ * 음소가 든 음절(T)은 남기고 나머지 중 1개를 탈락시켜 2음절 정답을 만든 뒤, 정답 안 T 음절의 지정 파트만
+ * 바꿔 2음절 오답을 만든다. 음소 미선택 시 무작위. (편집기·런타임 공용.)
+ */
+export declare function buildDropContrast3Problem(word: string, comp: CompositionFilter | null, pronMap: Map<string, string>, phonemeView: 'char' | 'pron', wordSet: Set<string>, dropPos?: number | null): TrainingProblem | null;
+/**
+ * @public 합성어 부분 탈락 → [문제단어(합성어), 남는 실단어(정답), 그 단어의 대립쌍 실단어 오답 2].
+ * 합성어 근사: 앞/뒤로 나눈 두 조각이 '둘 다 실단어'(wordSet)인 첫 조합을 채택(예: 손수건=손+수건).
+ * 정답·오답 전부 실단어라 발음이 그대로. comp(훈련음소) 지정 시 남는 단어의 그 자리를 대립, 없으면 전 음절.
+ * dropPos: 0=어두 어근(앞) 탈락, 1=어말 어근(뒤) 탈락. 편집기·런타임 공용.
+ */
+export declare function buildDropCompoundProblem(word: string, comp: CompositionFilter | null, pronMap: Map<string, string>, phonemeView: 'char' | 'pron', wordSet: Set<string>, dropPos?: number | null): TrainingProblem | null;
+/**
+ * @public 1음절 받침 탈락 → [문제단어, 받침 뗀 음절(정답), 초성 대립 오답 2]. 받침 있는 1음절만.
+ *
+ * 정답 음절은 표준발음에서 만든다 — '넷(낻)'의 받침을 떼면 들리는 소리는 '네'가 아니라 '내'다.
+ * (1음절 단어는 고립형이라 문맥에 따른 변동이 없어, 표준발음이 곧 실제로 들리는 소리다.
+ *  2음절 이상 탈락훈련은 반대로 철자 기준이 맞다 — '놀이(노리)'에서 '놀'을 빼면 '리'가 아니라 '이'다.)
+ */
+export declare function buildDropFinalConsonantProblem(word: string, _comp: CompositionFilter | null, pronMap: Map<string, string>, _pv: 'char' | 'pron', _ws: Set<string>, _dropPos?: number | null): TrainingProblem | null;
+/**
+ * @public 1음절 자음(초성) 탈락 → [문제단어(받침 없는 자음 초성 1음절), 초성 뗀 순수 모음(정답), 모음 대립 오답 2].
+ * 자음을 빼면 ㅇ+모음만 남으므로(가→아) 오답도 ㅇ+다른 모음(아→오·우).
+ *
+ * 남는 모음은 표준발음에서 뽑는다 — '게(개)'에서 'ㄱ'을 빼면 들리는 소리는 '에'가 아니라 '애'다.
+ * 이 데이터의 ㅔ→ㅐ·ㅖ→ㅒ·ㅚ/ㅞ→ㅙ 정규화는 문맥과 무관해 고립 음절에도 그대로 적용된다.
+ */
+export declare function buildRemoveConsonantProblem(word: string, _comp: CompositionFilter | null, pronMap: Map<string, string>, _pv: 'char' | 'pron', _ws: Set<string>, _dropPos?: number | null): TrainingProblem | null;
+/** 위치 p를 와일드카드('*')로 마스킹한 "나머지 음절이 같은" 2·3음절 실단어 그룹(O(1) 조회). */
+export declare function buildSyllableMaskIndex(wordSet: Set<string>): Map<string, string[]>;
+/**
+ * 음절 바꾸기 — 한 음절을 '완전히 다른 음절'(minDiff=2음소↑ 차이)로 교체한 실단어를 정답으로.
+ * 같은 위치 1음절만, 2음소↑ 차, 발음 상이, 실단어(데이터)만. 합성 없음.
+ * compFrom=원래 음절 필터, compTo=바뀐 음절 필터, targetPos=바꿀 위치.
+ */
+export declare function buildChangeWholeSyllableProblem(word: string, compFrom: CompositionFilter | null, pronMap: Map<string, string>, phonemeView: 'char' | 'pron', maskIndex: Map<string, string[]>, targetPos?: number | null, compTo?: CompositionFilter | null, minDiff?: number): TrainingProblem | null;
+export { pronOf as pronFromMap };