jlpt 1.0.0

data/lib/jlpt/formatters/batch_processor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Batch Text, Subtitle, and Multi-Chapter Document Processor.
+  #
+  # Processes multiple text sections or chapters, generating difficulty roadmaps
+  # and per-section metric summaries.
+  #
+  module BatchProcessor
+    class << self
+      # Process a collection of text sections or chapters
+      #
+      # @param sections [Hash, Array<Hash>, Array<String>] sections mapping or list
+      # @return [Array<Hash>] roadmap of processed section difficulty metrics
+      def process(sections)
+        return [] if sections.nil? || sections.empty?
+
+        items = normalize_sections(sections)
+        items.map do |name, text|
+          res = JLPT.analyze(text)
+          { name: name, recommended_level: res.recommended_level, score: res.score,
+            word_count: res.word_count, sentence_count: res.sentence_count }
+        end
+      end
+
+      private
+
+      def normalize_sections(sections)
+        if sections.is_a?(Hash)
+          sections.to_a
+        elsif sections.is_a?(Array)
+          sections.map.with_index do |sec, idx|
+            sec.is_a?(Hash) ? [sec[:name] || "Section #{idx + 1}", sec[:text] || ''] : ["Section #{idx + 1}", sec.to_s]
+          end
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/jlpt/formatters/exporter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Learner Tools and Anki Flashcard Exporter.
+  #
+  # Identifies new / unknown vocabulary above a learner's current target level
+  # and exports flashcards in Anki TSV/CSV format.
+  #
+  module Exporter
+    LEVEL_ORDER = { n5: 1, n4: 2, n3: 3, n2: 4, n1: 5, non_jlpt: 6, out_of_jlpt: 6 }.freeze
+
+    class << self
+      # Extract vocabulary words that exceed the learner's current level
+      #
+      # @param text [String] Japanese text
+      # @param target_level [Symbol, String] learner's mastered level (:n5, :n4, :n3, :n2)
+      # @return [Array<Hash>] array of unknown word hashes
+      def find_unknown(text, target_level: :n4)
+        target_val = LEVEL_ORDER[target_level.to_s.downcase.to_sym] || 2
+        classified = VocabClassifier.classify(text)
+
+        unknown = classified.flat_map do |lvl, words|
+          extract_words_above_target(lvl, words, target_val)
+        end
+        unknown.uniq { |item| item[:word] }
+      end
+
+      # Export unknown words as Anki tab-separated values (TSV)
+      #
+      # @param text [String] Japanese text
+      # @param target_level [Symbol, String]
+      # @return [String] TSV formatted string
+      def to_anki_tsv(text, target_level: :n4)
+        items = find_unknown(text, target_level: target_level)
+        return '' if items.empty?
+
+        lines = items.map do |item|
+          "#{item[:word]}\t#{item[:word]}[#{item[:reading]}]\t#{item[:level].to_s.upcase}"
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      def extract_words_above_target(lvl, words, target_val)
+        lvl_val = LEVEL_ORDER[lvl] || 6
+        return [] unless lvl_val > target_val
+
+        words.map do |w|
+          { word: w, level: lvl, reading: Dictionary.reading_for(w) || w }
+        end
+      end
+    end
+  end
+end

data/lib/jlpt/formatters/furigana.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Furigana Generator and Romaji Transliteration Engine.
+  #
+  # Attaches Hiragana readings to Kanji words in HTML (<ruby>) or Markdown/Anki format,
+  # and provides Hepburn Romaji transliteration.
+  #
+  module Furigana
+    KANJI_REGEX = /[\u4E00-\u9FFF]/.freeze
+
+    class << self
+      # Render text with Furigana annotations
+      #
+      # @param text [String] Japanese input text
+      # @param format [Symbol] :html or :markdown (:anki)
+      # @return [String] formatted string
+      def render(text, format: :html)
+        tokens = Tokenizer.tokenize(text)
+        return '' if tokens.empty?
+
+        tokens.map { |token| render_token(token, format: format) }.join
+      end
+
+      # Transliterate Katakana/Hiragana to Hepburn Romaji
+      #
+      # @param text [String] Japanese text
+      # @return [String] Romaji string
+      def to_romaji(text)
+        tokens = Tokenizer.tokenize(text)
+        return '' if tokens.empty?
+
+        tokens.map { |t| kana_to_romaji(t[:reading]) }.join(' ').strip
+      end
+
+      private
+
+      def render_token(token, format:)
+        surface = token[:surface]
+        return surface unless surface.match?(KANJI_REGEX)
+
+        reading = determine_furigana_reading(surface, token[:reading])
+        return surface if reading.empty?
+
+        format == :html ? "<ruby><rb>#{surface}</rb><rt>#{reading}</rt></ruby>" : "#{surface}[#{reading}]"
+      end
+
+      def determine_furigana_reading(surface, reading)
+        if reading && reading != surface
+          katakana_to_hiragana(reading)
+        else
+          Dictionary.reading_for(surface) || ''
+        end
+      end
+
+      def katakana_to_hiragana(str)
+        str.tr('ァ-ン', 'ぁ-ん')
+      end
+
+      def kana_to_romaji(str)
+        return '' if str.nil?
+
+        str.tr('がぎぐげござじずぜぞだぢづでどばびぶべぼ', 'gagigugegozajizuzedodidudedobabibubebo')
+           .tr('あいうえおかきくけこさしすせそたちつてと', 'aiueokakikukesashisusesotachitsuteto')
+           .tr('なにぬねのはひふへほまみむめもやゆよらりるれろわをん', 'naninunenohahifuhemomamimumemoyayuyorarirurerowawon')
+      end
+    end
+  end
+end

data/lib/jlpt/formatters/reporter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JLPT
+  # Interactive Visual Reporter.
+  #
+  # Generates self-contained HTML reports with modern glassmorphism UI,
+  # difficulty level badges, progress bars, and GitHub-Flavored Markdown summaries.
+  #
+  module Reporter
+    class << self
+      # Render a beautiful, standalone HTML report for an AnalysisResult
+      #
+      # @param result [JLPT::AnalysisResult]
+      # @return [String] HTML string
+      def render_html(result)
+        furigana = Furigana.render(result.text, format: :html)
+        lvl = result.recommended_level.to_s.upcase
+
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="ja">
+          <head><meta charset="UTF-8"><title>JLPT Analysis Report - #{lvl}</title>#{html_style_block}</head>
+          <body>#{html_header_card(result)}<div class="card"><h2>Annotated Text</h2><div class="reading">#{furigana}</div></div></body>
+          </html>
+        HTML
+      end
+
+      # Render a Markdown report table
+      #
+      # @param result [JLPT::AnalysisResult]
+      # @return [String] Markdown string
+      def render_markdown(result)
+        <<~MARKDOWN
+          # JLPT Analysis Report
+
+          | Metric | Value |
+          | :--- | :--- |
+          | **Recommended Level** | #{result.recommended_level.to_s.upcase} |
+          | **Difficulty Score** | #{result.score} / 100 |
+          | **Kanji Density** | #{(result.kanji_density * 100).round(1)}% |
+          | **Word Count** | #{result.word_count} |
+          | **Sentence Count** | #{result.sentence_count} |
+        MARKDOWN
+      end
+
+      private
+
+      def html_style_block
+        <<~CSS
+          <style>
+            body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #f8fafc; padding: 2rem; }
+            .card { background: rgba(30, 41, 59, 0.8); border: 1px solid #334155; border-radius: 12px; padding: 1.5rem; margin-bottom: 1.5rem; backdrop-filter: blur(10px); }
+            .badge { display: inline-block; padding: 0.5rem 1rem; border-radius: 9999px; background: #6366f1; color: #fff; font-weight: bold; font-size: 1.25rem; }
+            .reading { line-height: 2.2; font-size: 1.2rem; }
+            rt { font-size: 0.75rem; color: #818cf8; }
+          </style>
+        CSS
+      end
+
+      def html_header_card(result)
+        <<~CARD
+          <div class="card">
+            <h1>JLPT Difficulty Report</h1>
+            <p>Recommended Level: <span class="badge">#{result.recommended_level.to_s.upcase}</span></p>
+            <p>Difficulty Score: <strong>#{result.score} / 100</strong></p>
+            <p>Kanji Density: <strong>#{(result.kanji_density * 100).round(1)}%</strong> | Sentences: <strong>#{result.sentence_count}</strong></p>
+          </div>
+        CARD
+      end
+    end
+  end
+end

data/lib/jlpt/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JLPT
+  VERSION = '1.0.0'
+end

data/lib/jlpt.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'jlpt/version'
+require_relative 'jlpt/core/config'
+require_relative 'jlpt/core/engine'
+require_relative 'jlpt/core/dictionary'
+require_relative 'jlpt/core/preprocessor'
+require_relative 'jlpt/core/tokenizer'
+require_relative 'jlpt/core/kanji'
+require_relative 'jlpt/core/kanji_details'
+require_relative 'jlpt/core/vocab_classifier'
+require_relative 'jlpt/core/analysis_result'
+require_relative 'jlpt/core/cache_manager'
+require_relative 'jlpt/core/analyzer'
+require_relative 'jlpt/analyzers/grammar'
+require_relative 'jlpt/analyzers/style_profiler'
+require_relative 'jlpt/analyzers/pitch_accent'
+require_relative 'jlpt/analyzers/conjugation'
+require_relative 'jlpt/analyzers/corpus_stats'
+require_relative 'jlpt/analyzers/dokkai'
+require_relative 'jlpt/analyzers/jukugo'
+require_relative 'jlpt/analyzers/loanwords'
+require_relative 'jlpt/analyzers/comparer'
+require_relative 'jlpt/analyzers/onomatopeia'
+require_relative 'jlpt/analyzers/pos_profiler'
+require_relative 'jlpt/analyzers/exam_readiness'
+require_relative 'jlpt/analyzers/syntax'
+require_relative 'jlpt/analyzers/simplifier'
+require_relative 'jlpt/formatters/furigana'
+require_relative 'jlpt/formatters/exporter'
+require_relative 'jlpt/formatters/reporter'
+require_relative 'jlpt/formatters/batch_processor'
+require_relative 'jlpt/cli'
+require_relative 'jlpt/active_model/validator'
+
+# Main entry point for the JLPT Japanese text analysis library.
+#
+module JLPT
+  class Error < StandardError; end
+
+  class << self
+    # Analyze Japanese text and return difficulty metrics & JLPT recommendation
+    #
+    # @param text [String] Japanese text
+    # @return [JLPT::AnalysisResult]
+    def analyze(text)
+      Analyzer.analyze(text)
+    end
+  end
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: jlpt
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jakub Polak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: natto
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Ruby library for Japanese morphological analysis, JLPT N5-N1 difficulty
+  scoring, furigana generation, kanji extraction, and pitch accent profiling.
+email:
+- jakub.polak.vz@gmail.com
+executables:
+- jlpt
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.ja.md
+- README.md
+- assets/logo.png
+- bin/jlpt
+- lib/jlpt.rb
+- lib/jlpt/active_model/validator.rb
+- lib/jlpt/analyzers/comparer.rb
+- lib/jlpt/analyzers/conjugation.rb
+- lib/jlpt/analyzers/corpus_stats.rb
+- lib/jlpt/analyzers/dokkai.rb
+- lib/jlpt/analyzers/exam_readiness.rb
+- lib/jlpt/analyzers/grammar.rb
+- lib/jlpt/analyzers/jukugo.rb
+- lib/jlpt/analyzers/loanwords.rb
+- lib/jlpt/analyzers/onomatopeia.rb
+- lib/jlpt/analyzers/pitch_accent.rb
+- lib/jlpt/analyzers/pos_profiler.rb
+- lib/jlpt/analyzers/simplifier.rb
+- lib/jlpt/analyzers/style_profiler.rb
+- lib/jlpt/analyzers/syntax.rb
+- lib/jlpt/cli.rb
+- lib/jlpt/core/analysis_result.rb
+- lib/jlpt/core/analyzer.rb
+- lib/jlpt/core/cache_manager.rb
+- lib/jlpt/core/config.rb
+- lib/jlpt/core/dictionary.rb
+- lib/jlpt/core/engine.rb
+- lib/jlpt/core/kanji.rb
+- lib/jlpt/core/kanji_details.rb
+- lib/jlpt/core/preprocessor.rb
+- lib/jlpt/core/tokenizer.rb
+- lib/jlpt/core/vocab_classifier.rb
+- lib/jlpt/data/kanji.json
+- lib/jlpt/data/vocab.json
+- lib/jlpt/formatters/batch_processor.rb
+- lib/jlpt/formatters/exporter.rb
+- lib/jlpt/formatters/furigana.rb
+- lib/jlpt/formatters/reporter.rb
+- lib/jlpt/version.rb
+homepage: https://github.com/kupolak/jlpt
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Japanese text analyzer and difficulty classifier for JLPT levels N5-N1
+test_files: []