@jjlmoya/utils-language 1.10.1 → 1.11.0

package/src/tool/lexical-coverage-vocabulary-calculator/types.ts

@@ -0,0 +1,33 @@
+export type CoverageTarget = 80 | 90 | 95 | 98;
+export type ContentType = 'conversation' | 'travel' | 'media' | 'generalReading' | 'novels' | 'business' | 'academic';
+export type CoverageStatus = 'below-target' | 'at-target' | 'buffer';
+
+export interface VocabularyPreset {
+  id: ContentType;
+  wordsByCoverage: Record<CoverageTarget, number>;
+}
+
+export interface LexicalCoverageInputs {
+  contentType: ContentType;
+  knownWords: number;
+  targetCoverage: CoverageTarget;
+}
+
+export interface CoverageCheckpoint {
+  coverage: CoverageTarget;
+  words: number;
+}
+
+export interface LexicalCoveragePlan {
+  inputs: LexicalCoverageInputs;
+  recommendedWords: number;
+  knownWords: number;
+  estimatedCoverage: number;
+  unknownPerHundred: number;
+  gapWords: number;
+  status: CoverageStatus;
+  checkpoints: CoverageCheckpoint[];
+  nextCheckpoint: CoverageCheckpoint | null;
+}
+
+export type LexicalCoverageResult = { ok: true; plan: LexicalCoveragePlan } | { ok: false; error: string };

package/src/tool/lexical-coverage-vocabulary-calculator/ui.ts

@@ -0,0 +1,50 @@
+export interface LexicalCoverageUI extends Record<string, string> {
+  contentType: string;
+  conversation: string;
+  travel: string;
+  media: string;
+  generalReading: string;
+  novels: string;
+  business: string;
+  academic: string;
+  knownWords: string;
+  knownWordsHint: string;
+  targetCoverage: string;
+  coverage80: string;
+  coverage90: string;
+  coverage95: string;
+  coverage98: string;
+  resetButton: string;
+  quickStart: string;
+  conversationPreset: string;
+  readingPreset: string;
+  workPreset: string;
+  resultTitle: string;
+  emptyResult: string;
+  checkInputs: string;
+  invalidWords: string;
+  invalidContentType: string;
+  invalidCoverage: string;
+  belowTarget: string;
+  atTarget: string;
+  buffer: string;
+  recommendedWords: string;
+  vocabularyKnown: string;
+  estimatedCoverage: string;
+  gapWords: string;
+  unknownPerHundred: string;
+  coverageRoute: string;
+  nextCheckpoint: string;
+  noMoreCheckpoints: string;
+  words: string;
+  wordUnit: string;
+  unknownWords: string;
+  targetMarker: string;
+  coverageNote: string;
+  wordFamilyNote: string;
+  contentTypeHelp: string;
+  interpretationTitle: string;
+  actionBelow: string;
+  actionAt: string;
+  actionBuffer: string;
+}

package/src/tool/lexical-coverage-vocabulary-calculator/validation.ts

@@ -0,0 +1,18 @@
+export const validation = {
+  reviewedAt: '2026-09-02',
+  methodology: 'The calculator maps a content profile to four planning checkpoints for receptive vocabulary size and estimates an intermediate coverage by linear interpolation. It is a transparent heuristic based on frequency-band research, not a test of language ability.',
+  sources: [
+    'https://www.scienceguide.nl/wp-content/uploads/2017/11/nation-2006-vocabulary.pdf',
+    'https://asele.org/media/2025/03/8izquierdogilm-adelcarmenlaselecciondellexicoenlaensananza.pdf',
+  ],
+  referenceCases: [
+    { contentType: 'conversation', targetCoverage: '80%', expectedWords: 2000 },
+    { contentType: 'novels', targetCoverage: '95%', expectedWords: 8000 },
+    { contentType: 'business', targetCoverage: '95%', expectedWords: 8000 },
+  ],
+  limitations: [
+    'The checkpoints describe word families or frequency bands in source research and may not match an app count of lemmas or surface forms.',
+    'Coverage varies by language, corpus, genre, topic, proper nouns, morphology, background knowledge, and the learner\'s ability to infer meaning.',
+    'The result does not certify comprehension, speaking ability, fluency, or a CEFR level.',
+  ],
+};

package/src/tools.ts

@@ -2,7 +2,8 @@ import type { ToolDefinition } from './types';
 import { CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL } from './tool/cefr-language-skill-profile-planner';
 import { LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL } from './tool/language-shadowing-session-planner';
 import { LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL } from './tool/language-learning-study-plan-planner';
+import { LEXICAL_COVERAGE_VOCABULARY_CALCULATOR_TOOL } from './tool/lexical-coverage-vocabulary-calculator/entry';
 
-export const ALL_TOOLS: ToolDefinition[] = [LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL, CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL, LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL];
+export const ALL_TOOLS: ToolDefinition[] = [LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL, CEFR_LANGUAGE_SKILL_PROFILE_PLANNER_TOOL, LANGUAGE_SHADOWING_SESSION_PLANNER_TOOL, LEXICAL_COVERAGE_VOCABULARY_CALCULATOR_TOOL];
 
 export { ALL_ENTRIES } from './entries';