jlpt 1.0.0

data/lib/jlpt/analyzers/corpus_stats.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Corpus Lexical Diversity and Statistical Analyzer.
+  #
+  # Computes Type-Token Ratio (TTR), total word count, unique word count,
+  # and hapax legomena count for text.
+  #
+  module CorpusStats
+    class << self
+      # Analyze text corpus stats and lexical diversity (TTR)
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] corpus statistics hash
+      def analyze(text)
+        cleaned = Preprocessor.clean(text)
+        return empty_stats if cleaned.empty?
+
+        tokens = Tokenizer.lemmata(cleaned)
+        return empty_stats if tokens.empty?
+
+        total = tokens.length
+        counts = tokens.tally
+        unique = counts.keys.length
+        hapax = counts.values.count(1)
+        ttr = (unique.to_f / total).round(2)
+
+        { total_words: total, unique_words: unique, hapax_count: hapax, ttr: ttr }
+      end
+
+      private
+
+      def empty_stats
+        { total_words: 0, unique_words: 0, hapax_count: 0, ttr: 0.0 }
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/dokkai.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Dokkai (Reading Comprehension) Readability Evaluator.
+  #
+  # Evaluates Japanese text complexity for reading comprehension tasks,
+  # sentence length distribution, particle density, and recommended target reading time.
+  #
+  module Dokkai
+    PARTICLES_REGEX = /[はがをにで行とからよりへね]/.freeze
+
+    class << self
+      # Evaluate reading comprehension complexity and estimated reading time
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] Dokkai metrics including reading time and readability score
+      def evaluate(text)
+        cleaned = Preprocessor.clean(text)
+        return empty_evaluation if cleaned.empty?
+
+        build_evaluation_metrics(cleaned)
+      end
+
+      private
+
+      def build_evaluation_metrics(cleaned)
+        sents = Preprocessor.sentences(cleaned)
+        avg_len = (cleaned.length.to_f / [sents.length, 1].max).round(1)
+        particles = cleaned.scan(PARTICLES_REGEX).length
+
+        { readability_score: calculate_readability(avg_len, particles, cleaned.length),
+          estimated_reading_time_min: (cleaned.length / 400.0).round(2),
+          sentence_count: sents.length, avg_sentence_length: avg_len, particle_count: particles }
+      end
+
+      def calculate_readability(avg_len, particles, char_len)
+        density = (particles.to_f / [char_len, 1].max) * 100.0
+        score = (avg_len * 0.5) + (density * 2.0)
+        [score.round(2), 100.0].min
+      end
+
+      def empty_evaluation
+        {
+          readability_score: 0.0,
+          estimated_reading_time_min: 0.0,
+          sentence_count: 0,
+          avg_sentence_length: 0.0,
+          particle_count: 0
+        }
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/exam_readiness.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Exam Readiness and Level Coverage Evaluator.
+  #
+  # Evaluates how well input text aligns with a target JLPT exam level (N5-N1),
+  # calculating target level vocabulary density and readiness score.
+  #
+  module ExamReadiness
+    LEVEL_THRESHOLD_MAP = { n5: 1, n4: 2, n3: 3, n2: 4, n1: 5 }.freeze
+
+    class << self
+      # Evaluate readiness score for a target JLPT level
+      #
+      # @param text [String] Japanese text
+      # @param target_level [Symbol, String] target exam level (:n5, :n4, :n3, :n2, :n1)
+      # @return [Hash] exam readiness metrics
+      def evaluate(text, target_level: :n3)
+        target_sym = target_level.to_s.downcase.to_sym
+        target_val = LEVEL_THRESHOLD_MAP[target_sym] || 3
+
+        res = JLPT.analyze(text)
+        current_val = LEVEL_THRESHOLD_MAP[res.recommended_level] || 1
+
+        readiness = calculate_readiness_score(current_val, target_val, res.score)
+        status = determine_readiness_status(readiness)
+
+        { target_level: target_sym, current_level: res.recommended_level,
+          readiness_score: readiness, status: status }
+      end
+
+      private
+
+      def calculate_readiness_score(current_val, target_val, score)
+        diff = current_val - target_val
+        if diff >= 0
+          100.0
+        else
+          [(100.0 + (diff * 25.0) + (score * 0.2)).round(2), 0.0].max
+        end
+      end
+
+      def determine_readiness_status(score)
+        case score
+        when 90.0..100.0 then :ready
+        when 60.0..89.99 then :moderate
+        else                  :needs_practice
+        end
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/grammar.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JLPT
+  # JLPT Grammar Pattern Detection Engine.
+  #
+  # Recognizes Japanese grammar constructions across levels N5 to N1.
+  #
+  module Grammar
+    PATTERNS = [
+      { pattern: /てはいけない|てはならない/, level: :n5, name: '〜てはいけない' },
+      { pattern: /てください|てくださいませんか/, level: :n5, name: '〜てください' },
+      { pattern: /なければならない|なければいけない/, level: :n5, name: '〜なければならない' },
+      { pattern: /ことができる|ことができない/, level: :n4, name: '〜ことができる' },
+      { pattern: /ようになっている/, level: :n4, name: '〜ようになっている' },
+      { pattern: /わけがない|わけではない/, level: :n3, name: '〜わけがない' },
+      { pattern: /に違いない/, level: :n2, name: '〜に違いない' },
+      { pattern: /ざるを得ない/, level: :n1, name: '〜ざるを得ない' }
+    ].freeze
+
+    class << self
+      # Detect grammar patterns in text
+      #
+      # @param text [String] Japanese text
+      # @return [Array<Hash>] array of detected grammar hashes
+      def extract(text)
+        cleaned = Preprocessor.clean(text)
+        return [] if cleaned.empty?
+
+        PATTERNS.filter_map do |rule|
+          { name: rule[:name], level: rule[:level], pattern: rule[:pattern] } if cleaned.match?(rule[:pattern])
+        end
+      end
+
+      # Breakdown of detected grammar patterns by JLPT level
+      #
+      # @param text [String] Japanese text
+      # @return [Hash{Symbol => Array<String>}]
+      def breakdown(text)
+        extracted = extract(text)
+        res = { n5: [], n4: [], n3: [], n2: [], n1: [] }
+
+        extracted.each do |g|
+          lvl = g[:level]
+          res[lvl] << g[:name] if res.key?(lvl)
+        end
+        res
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/jukugo.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Jukugo (Kanji Compound) Extractor and Classifier.
+  #
+  # Identifies multi-kanji compound words (2-kanji, 3-kanji, 4-kanji Yojijukugo)
+  # in Japanese text.
+  #
+  module Jukugo
+    JUKUGO_REGEX = /[\u4E00-\u9FFF]{2,}/.freeze
+
+    class << self
+      # Extract all kanji compounds from Japanese text
+      #
+      # @param text [String] Japanese text
+      # @return [Array<String>] unique array of Jukugo compounds
+      def extract(text)
+        cleaned = Preprocessor.clean(text)
+        return [] if cleaned.empty?
+
+        cleaned.scan(JUKUGO_REGEX).uniq
+      end
+
+      # Breakdown compounds by character length (2-kanji, 3-kanji, 4-kanji+)
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] hash with keys :two_char, :three_char, :yojijukugo, :long
+      def breakdown(text)
+        result = { two_char: [], three_char: [], yojijukugo: [], long: [] }
+        extract(text).each { |c| categorize_compound(c, result) }
+        result
+      end
+
+      private
+
+      def categorize_compound(compound, result)
+        case compound.length
+        when 2 then result[:two_char] << compound
+        when 3 then result[:three_char] << compound
+        when 4 then result[:yojijukugo] << compound
+        else        result[:long] << compound
+        end
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/loanwords.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Japanese Word Origin and Loanword (Gairaigo 外来語) Detector.
+  #
+  # Categorizes vocabulary into Katakana loanwords (Gairaigo), Sino-Japanese
+  # Kanji compounds (Kango), and native Japanese words (Wago).
+  #
+  module Loanwords
+    KATAKANA_REGEX = /^[\u30A0-\u30FFー]+$/.freeze
+    KANJI_REGEX = /[\u4E00-\u9FFF]/.freeze
+
+    class << self
+      # Extract all Katakana loanwords (Gairaigo) from text
+      #
+      # @param text [String] Japanese text
+      # @return [Array<String>] unique array of loanword lemmata
+      def extract(text)
+        cleaned = Preprocessor.clean(text)
+        return [] if cleaned.empty?
+
+        lemmas = Tokenizer.lemmata(cleaned)
+        lemmas.select { |lemma| lemma.match?(KATAKANA_REGEX) && lemma.length >= 2 }.uniq
+      end
+
+      # Categorize text vocabulary by word origin (Wago, Kango, Gairaigo)
+      #
+      # @param text [String] Japanese text
+      # @return [Hash{Symbol => Array<String>}] origin breakdown hash
+      def breakdown(text)
+        cleaned = Preprocessor.clean(text)
+        res = { gairaigo: [], kango: [], wago: [] }
+        return res if cleaned.empty?
+
+        Tokenizer.lemmata(cleaned).uniq.each do |lemma|
+          categorize_lemma(lemma, res)
+        end
+        res
+      end
+
+      private
+
+      def categorize_lemma(lemma, res)
+        if lemma.match?(KATAKANA_REGEX) && lemma.length >= 2
+          res[:gairaigo] << lemma
+        elsif lemma.match?(KANJI_REGEX)
+          res[:kango] << lemma
+        else
+          res[:wago] << lemma
+        end
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/onomatopeia.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Onomatopoeia (擬音語 Giongo & 擬態語 Gitaito) Extractor.
+  #
+  # Identifies Japanese sound-symbolic and mimetic words in Hiragana or Katakana.
+  #
+  module Onomatopeia
+    ONOMATOPOEIA_PATTERNS = %w[
+      どきどき わくわく ぺらぺら にこにこ ふわふわ ぎっしり
+      ギリギリ イライラ キラキラ ドキドキ ニコニコ ペラペラ
+      もちもち すらすら どんどん だんだん いろいろ
+    ].freeze
+
+    class << self
+      # Extract onomatopoeia words from Japanese text
+      #
+      # @param text [String] Japanese text
+      # @return [Array<String>] unique array of onomatopoeias
+      def extract(text)
+        cleaned = Preprocessor.clean(text)
+        return [] if cleaned.empty?
+
+        matches = ONOMATOPOEIA_PATTERNS.select { |word| cleaned.include?(word) }
+        matches.uniq
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/pitch_accent.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Pitch Accent Profiler and Pattern Lookup.
+  #
+  # Categorizes pitch accent types (Heiban / 平板 [0], Atamadaka / 頭高 [1], Nakadaka / 中高 [2+], Odaka / 尾高)
+  # for Japanese vocabulary words.
+  #
+  module PitchAccent
+    # Built-in pitch accent database for common words
+    ACCENT_MAP = {
+      '学校' => { type: :odaka, pattern: 0 },
+      '私' => { type: :heiban, pattern: 0 },
+      '日本' => { type: :atamadaka, pattern: 1 },
+      '猫' => { type: :atamadaka, pattern: 1 },
+      '犬' => { type: :atamadaka, pattern: 2 },
+      '本' => { type: :atamadaka, pattern: 1 },
+      '先生' => { type: :nakadaka, pattern: 3 }
+    }.freeze
+
+    class << self
+      # Lookup pitch accent for a vocabulary word
+      #
+      # @param word [String] vocabulary word
+      # @return [Hash, nil] pitch accent hash with :type and :pattern
+      def accent_for(word)
+        return nil if word.nil? || word.to_s.strip.empty?
+
+        ACCENT_MAP[word.to_s.strip] || { type: :heiban, pattern: 0 }
+      end
+
+      # Profile pitch accent patterns in Japanese text
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] breakdown of pitch accent types in text
+      def profile(text)
+        tokens = Tokenizer.tokenize(text)
+        result = { heiban: 0, atamadaka: 0, nakadaka: 0, odaka: 0 }
+
+        tokens.each do |t|
+          info = accent_for(t[:surface])
+          next unless info
+
+          type = info[:type]
+          result[type] += 1 if result.key?(type)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/pos_profiler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Part-of-Speech (POS) Distribution Profiler.
+  #
+  # Analyzes Japanese tokens and calculates percentage breakdown per POS category
+  # (nouns, verbs, adjectives, particles, adverbs, symbols).
+  #
+  module PosProfiler
+    POS_LABELS = {
+      '名詞' => :noun,
+      '動詞' => :verb,
+      '形容詞' => :adjective,
+      '助詞' => :particle,
+      '副詞' => :adverb,
+      '記号' => :symbol
+    }.freeze
+
+    class << self
+      # Analyze text POS distribution
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] POS breakdown hash with counts and distribution
+      def profile(text)
+        tokens = Tokenizer.tokenize(text)
+        return empty_profile if tokens.empty?
+
+        counts = Hash.new(0)
+        tokens.each do |token|
+          category = POS_LABELS[token[:pos]] || :other
+          counts[category] += 1
+        end
+
+        total = tokens.length
+        dist = counts.transform_values { |cnt| (cnt.to_f / total * 100).round(2) }
+
+        { counts: counts, distribution: dist, total_tokens: total }
+      end
+
+      private
+
+      def empty_profile
+        { counts: {}, distribution: {}, total_tokens: 0 }
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/simplifier.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Text Simplifier and Beginner Synonym Recommender.
+  #
+  # Scans Japanese text for complex N2/N1 vocabulary and recommends simpler
+  # N5/N4/N3 synonym alternatives for Japanese language learners.
+  #
+  module Simplifier
+    SIMPLIFICATIONS = {
+      '著しい' => { reading: 'いちじるしい', suggestions: %w[大きい 目立つ] },
+      '著しく' => { reading: 'いちじるしく', suggestions: %w[大きく 目立って] },
+      '未曽有' => { reading: 'みぞう', suggestions: %w[今までにない 初めての] },
+      '浸透' => { reading: 'しんとう', suggestions: %w[広がる 伝わる] },
+      '阻害' => { reading: 'そがい', suggestions: %w[邪魔する 妨げる] },
+      '急速' => { reading: 'きゅうそく', suggestions: %w[とても速い 急に] },
+      '懸念' => { reading: 'けねん', suggestions: %w[心配 不安] },
+      '普及' => { reading: 'ふきゅう', suggestions: %w[広まる みんなが使う] }
+    }.freeze
+
+    class << self
+      # Analyze text and return simplification suggestions for high-level words
+      #
+      # @param text [String] Japanese text
+      # @return [Array<Hash>] array of simplification suggestions
+      def simplify(text)
+        cleaned = Preprocessor.clean(text)
+        return [] if cleaned.empty?
+
+        SIMPLIFICATIONS.filter_map do |word, data|
+          build_suggestion(word, data) if cleaned.include?(word)
+        end
+      end
+
+      private
+
+      def build_suggestion(word, data)
+        level = Dictionary.vocab_level(word) || :n1
+        {
+          word: word,
+          level: level,
+          reading: data[:reading],
+          suggestions: data[:suggestions]
+        }
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/style_profiler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Style and Speech Register Profiler.
+  #
+  # Analyzes polite vs plain form usage, Keigo honorifics (Sonkeigo/Kenjougo),
+  # dialect markers, and internet slang in Japanese text.
+  #
+  module StyleProfiler
+    POLITE_ENDINGS = /(?:です|ます|でした|ました|ではありません|ではありませんでした|でしょう)\b/.freeze
+    KEIGO_SONKEIGO_PATTERNS = /(?:お|ご)\p{L}+(?:になる|なさる|くださる)|いらっしゃる|おっしゃる|ご覧/.freeze
+    KEIGO_KENJOUGO_PATTERNS = /(?:お|ご)\p{L}+(?:する|いたします)|申す|申し上げ|参る|参り|いただく|いただき|存じる|存じ/.freeze
+    SLANG_PATTERNS = /(?:[wW]{2,}|笑|ｗｗ|やねん|やで|ほんま)/.freeze
+
+    class << self
+      # Analyze text style and return detailed profile hash
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] style profile with formality, keigo, and register metrics
+      def profile(text)
+        cleaned = Preprocessor.clean(text)
+        return empty_profile if cleaned.empty?
+
+        build_style_profile(cleaned)
+      end
+
+      private
+
+      def build_style_profile(cleaned)
+        polite = cleaned.scan(POLITE_ENDINGS).length
+        sonkeigo = cleaned.scan(KEIGO_SONKEIGO_PATTERNS).length
+        kenjougo = cleaned.scan(KEIGO_KENJOUGO_PATTERNS).length
+        slang = cleaned.scan(SLANG_PATTERNS).length
+
+        formality = calculate_formality(cleaned, polite, sonkeigo, kenjougo)
+        register = formality > 50.0 ? :polite : :plain
+
+        { formality_score: formality, register: register, polite_count: polite,
+          sonkeigo_count: sonkeigo, kenjougo_count: kenjougo, slang_count: slang }
+      end
+
+      def calculate_formality(text, polite_count, sonkeigo_count, kenjougo_count)
+        sentences = Preprocessor.sentences(text)
+        return 0.0 if sentences.empty?
+
+        ratio = (polite_count + (sonkeigo_count * 1.5) + (kenjougo_count * 1.5)) / sentences.length
+        [(ratio * 60.0).round(2), 100.0].min
+      end
+
+      def empty_profile
+        {
+          formality_score: 0.0,
+          register: :plain,
+          polite_count: 0,
+          sonkeigo_count: 0,
+          kenjougo_count: 0,
+          slang_count: 0
+        }
+      end
+    end
+  end
+end

data/lib/jlpt/analyzers/syntax.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Syntax and Sentence Clause Complexity Analyzer.
+  #
+  # Identifies conjunction particles and subordinate clause connectives
+  # (が, けど, から, ので, とき, たら, ば, なら, のに, けれども), calculating
+  # clause density and syntactic complexity indices.
+  #
+  module Syntax
+    CONJUNCTION_PATTERNS = /(?:けれども|けれど|けど|ので|から|とき|たら|なら|のに|が|し)\b/.freeze
+
+    class << self
+      # Analyze syntactic clause complexity of Japanese text
+      #
+      # @param text [String] Japanese text
+      # @return [Hash] syntax complexity metrics
+      def analyze(text)
+        cleaned = Preprocessor.clean(text)
+        return empty_analysis if cleaned.empty?
+
+        compute_syntax_metrics(cleaned)
+      end
+
+      private
+
+      def compute_syntax_metrics(cleaned)
+        sents = Preprocessor.sentences(cleaned)
+        matches = cleaned.scan(CONJUNCTION_PATTERNS)
+        cnt = matches.length
+        avg_clauses = ((cnt + sents.length).to_f / [sents.length, 1].max).round(2)
+
+        { conjunction_count: cnt, conjunctions: matches.uniq, sentence_count: sents.length,
+          avg_clauses_per_sentence: avg_clauses, complexity_index: [(avg_clauses * 25.0).round(2), 100.0].min }
+      end
+
+      def empty_analysis
+        { conjunction_count: 0, conjunctions: [], sentence_count: 0,
+          avg_clauses_per_sentence: 1.0, complexity_index: 0.0 }
+      end
+    end
+  end
+end