kotoshu 0.3.0

data/lib/kotoshu/data/common_words/ru.yml

@@ -0,0 +1,484 @@
+# Russian common words by frequency
+# Source: Russian Wikipedia Corpus, Russian National Corpus
+# Last updated: 2025-01-15
+
+metadata:
+  language: ru
+  source: Russian Wikipedia Corpus, Russian National Corpus
+  source_url: https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists/Russian
+  total_words: 146269
+  last_updated: 2025-01-15
+  license: CC-BY-SA 4.0
+
+tiers:
+  top_50:
+    - и
+    - в
+    - не
+    - на
+    - я
+    - быть
+    - это
+    - он
+    - с
+    - как
+    - что
+    - а
+    - то
+    - они
+    - мы
+    - вы
+    - который
+    - для
+    - к
+    - по
+    - от
+    - все
+    - этот
+    - но
+    - его
+    - она
+    - или
+    - такой
+    - еще
+    - сказать
+    - их
+    - о
+    - только
+    - себя
+    - есть
+    - у
+    - кто
+    - мой
+    - год
+    - когда
+    - время
+    - свой
+    - так
+    - более
+    - тот
+    - через
+    - более
+    - более
+    - более
+
+  top_200:
+    - также
+    - из
+    - за
+    - что
+    - чтобы
+    - другие
+    - самый
+    - наш
+    - эти
+    - весь
+    - это
+    - если
+    - можно
+    - нет
+    - так
+    - новый
+    - работа
+    - люди
+    - без
+    - человек
+    - мир
+    - свой
+    - раз
+    - даже
+    - нам
+    - она
+    - под
+    - из
+    - один
+    - два
+    - три
+    - четыре
+    - пять
+    - шесть
+    - семь
+    - восемь
+    - девять
+    - десять
+    - первый
+    - второй
+    - третий
+    - четвертый
+    - пятый
+    - шестой
+    - седьмой
+    - восьмой
+    - девятый
+    - десятый
+    - последний
+    - новый
+    - старый
+    - молодой
+    - большой
+    - маленький
+    - хороший
+    - плохой
+    - лучший
+    - худший
+    - самый
+    - очень
+    - слишком
+    - достаточно
+    - много
+    - мало
+    - несколько
+    - немного
+    - весьма
+    - крайне
+    - абсолютно
+    - полностью
+    - целиком
+    - совсем
+    - почти
+    - приблизительно
+    - около
+    - примерно
+    - точно
+    - именно
+    - как раз
+    - именно
+    - прямо
+    - тут
+    - здесь
+    - там
+    - туда
+    - сюда
+    - отсюда
+    - оттуда
+    - везде
+    - нигде
+    - всюду
+    - негде
+    - где-то
+    - куда-то
+    - когда-то
+    - когда-нибудь
+    - иногда
+    - иногда
+    - иногда
+    - всегда
+    - никогда
+    - часто
+    - редко
+    - обычно
+    - вообще
+    - частности
+    - особенно
+    - главным образом
+    - прежде всего
+    - в основном
+    - по-прежнему
+    - по-прежнему
+    - до сих пор
+    - пока
+    - пока
+    - пока не
+    - в то время как
+    - в то время
+    - между тем
+    - тем временем
+    - тем не менее
+    - однако
+    - но
+    - зато
+    - же
+    - то есть
+    - а именно
+    - например
+    - скажем
+    - допустим
+    - предположим
+    - видимо
+    - по-видимому
+    - оказывается
+    - следовательно
+    - таким образом
+    - итак
+    - кстати
+    - между прочим
+    - во-первых
+    - во-вторых
+    - в-третьих
+    - с одной стороны
+    - с другой стороны
+    - кстати сказать
+    - разумеется
+    - конечно
+    - бесспорно
+    - несомненно
+    - безусловно
+    - без сомнения
+    - в самом деле
+    - в самом деле
+    - действительно
+    - на самом деле
+    - в действительности
+    - по существу
+    - в сущности
+    - по сути
+    - в конечном счете
+    - в итоге
+    - в результате
+    - вследствие
+    - благодаря
+    - из-за
+    - по причине
+    - в силу
+    - на основании
+    - согласно
+    - в соответствии
+    - вопреки
+    - несмотря на
+    - несмотря на то что
+    - хотя
+    - пусть
+    - даром что
+    - даже если
+    - если бы
+    - в случае если
+    - при условии что
+    - в том случае
+    - иначе
+    - иначе говоря
+    - другими словами
+    - лучше сказать
+    - точнее
+    - собственно
+    - впрочем
+    - наконец
+    - в конце концов
+    - в заключение
+    - словом
+    - короче говоря
+    - одним словом
+
+  top_1000:
+    - слово
+    - буква
+    - текст
+    - предложение
+    - фраза
+    - выражение
+    - термин
+    - понятие
+    - идея
+    - мысль
+    - мнение
+    - взгляд
+    - точка зрения
+    - позиция
+    - отношение
+    - подход
+    - способ
+    - метод
+    - прием
+    - средство
+    - инструмент
+    - оборудование
+    - аппарат
+    - механизм
+    - система
+    - структура
+    - организация
+    - учреждение
+    - предприятие
+    - компания
+    - фирма
+    - корпорация
+    - организация
+    - объединение
+    - союз
+    - ассоциация
+    - общество
+    - сообщество
+    - группа
+    - коллектив
+    - команда
+    - кружок
+    - секция
+    - отдел
+    - отделение
+    - подразделение
+    - филиал
+    - представительство
+    - агентство
+    - бюро
+    - комитет
+    - комиссия
+    - совет
+    - правление
+    - дирекция
+    - администрация
+    - управление
+    - министерство
+    - ведомство
+    - департамент
+    - служба
+    - орган
+    - власть
+    - государство
+    - страна
+    - регион
+    - область
+    - район
+    - город
+    - поселок
+    - деревня
+    - село
+    - место
+    - местность
+    - территория
+    - зона
+    - район
+    - округ
+    - район
+    - край
+    - пределы
+    - границы
+    - рубеж
+    - водораздел
+    - поворот
+    - пункт
+    - точка
+    - стадия
+    - этап
+    - фаза
+    - период
+    - эпоха
+    - эра
+    - время
+    - год
+    - сезон
+    - месяц
+    - неделя
+    - день
+    - сутки
+    - вечер
+    - утро
+    - ночь
+    - полдень
+    - полночь
+    - рассвет
+    - закат
+    - сумерки
+    - темнота
+    - свет
+    - тьма
+    - ясность
+    - ясность
+    - понятность
+    - понятность
+    - простота
+    - сложность
+    - трудность
+    - легкость
+    - возможность
+    - невозможность
+    - способность
+    - неспособность
+    - умение
+    - навык
+    - мастерство
+    - искусство
+    - ремесло
+    - профессия
+    - специальность
+    - квалификация
+    - образование
+    - воспитание
+    - обучение
+    - подготовка
+    - тренировка
+    - практика
+    - опыт
+    - знание
+    - понимание
+    - осознание
+    - осознавание
+    - познание
+    - изучение
+    - исследование
+    - анализ
+    - синтез
+    - оценка
+    - оценивание
+    - оценивание
+    - суждение
+    - мнение
+    - решение
+    - вывод
+    - заключение
+    - умозаключение
+    - заключение
+    - аргумент
+    - довод
+    - доказательство
+    - подтверждение
+    - опровержение
+    - утверждение
+    - отрицание
+    - признание
+    - отрицание
+    - согласие
+    - согласие
+    - отказ
+    - отказ
+    - принятие
+    - принятие
+    - принятие
+    - одобрение
+    - неодобрение
+    - поддержка
+    - противодействие
+    - сопротивление
+    - помощь
+    - содействие
+    - пособие
+    - поддержка
+    - подмога
+    - услуга
+    - одолжение
+    - любезность
+    - вежливость
+    - учтивость
+    - обходительность
+    - галантность
+    - приветливость
+    - радушие
+    - гостеприимство
+    - дружелюбие
+    - дружба
+    - приятельство
+    - товарищество
+    - партнёрство
+    - сотрудничество
+    - взаимодействие
+    - связь
+    - отношения
+    - общение
+    - беседа
+    - разговор
+    - диалог
+    - переговоры
+    - дискуссия
+    - обсуждение
+    - спор
+    - полемика
+    - дебаты
+    - прения
+    - дебаты
+    - диспут
+    - диспут
+    - прения
+    - дебаты
+    - дебаты
+    - дебаты
+    - дебаты
+    - дебаты
+    - дебаты

data/lib/kotoshu/data/common_words_loader.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'set'
+require 'fileutils'
+
+module Kotoshu
+  module Data
+    # Loads and provides access to common words data for all supported languages.
+    #
+    # This loader supports loading from:
+    # 1. Local YAML files in lib/kotoshu/data/common_words/{language}.yml
+    # 2. Frequency.json files downloaded from GitHub (via LanguageCache)
+    #
+    # Each language file contains:
+    # - metadata: Source information, word count, last updated
+    # - tiers: Top 50, top 200, and top 1000 most common words
+    #
+    # @example Loading English common words
+    #   loader = CommonWordsLoader.new
+    #   tiers = loader.load('en')
+    #   tiers[:top_50].include?('the')  # => true
+    #
+    # @example Getting available languages
+    #   CommonWordsLoader.available_languages  # => ['de', 'en', 'es', 'fr', 'pt', 'ru']
+    #
+    # @example Loading with tier specification
+    #   loader.load('en', tier: :top_200)  # Combines top_50 + top_200
+    class CommonWordsLoader
+      # Default data directory (local YAML files)
+      DATA_DIR = File.expand_path('../common_words', __FILE__).freeze
+
+      class << self
+        # Load common words for a language.
+        #
+        # @param language_code [String] ISO 639-1 language code (e.g., 'en', 'de')
+        # @param tier [Symbol] Tier level: :top_50, :top_200, or :top_1000
+        # @return [Hash{Symbol => Set}] Hash with :tiers (tier sets) and :metadata
+        def load(language_code, tier: :top_1000)
+          yaml_file = File.join(DATA_DIR, "#{language_code}.yml")
+
+          if File.exist?(yaml_file)
+            load_from_yaml(yaml_file, tier)
+          else
+            {
+              tiers: empty_tiers,
+              metadata: { source: 'none', language: language_code }
+            }
+          end
+        end
+
+        # Load from GitHub frequency.json (Phase 2 integration).
+        # Also handles Kelly frequency-list format from kotoshu/frequency-list-kelly
+        #
+        # @param language_code [String] ISO 639-1 language code
+        # @param frequency_path [String] Path to frequency.json file
+        # @return [Hash{Symbol => Set}] Hash with :tiers and :metadata
+        def load_from_frequency_file(frequency_path)
+          return { tiers: empty_tiers, metadata: {} } unless File.exist?(frequency_path)
+
+          data = JSON.parse(File.read(frequency_path, encoding: 'UTF-8'))
+
+          # Handle Kelly format: tiers[tier_name]['words']
+          # Check if format has nested 'words' key (Kelly format)
+          has_words_key = data.dig('tiers', 'top_50', 'words')
+
+          tiers = if has_words_key
+                    # Kelly format: data['tiers']['top_50']['words']
+                    {
+                      top_50: Set.new(data.dig('tiers', 'top_50', 'words') || []),
+                      top_200: Set.new(
+                        (data.dig('tiers', 'top_50', 'words') || []) +
+                        (data.dig('tiers', 'top_200', 'words') || [])
+                      ),
+                      top_1000: Set.new(
+                        (data.dig('tiers', 'top_50', 'words') || []) +
+                        (data.dig('tiers', 'top_200', 'words') || []) +
+                        (data.dig('tiers', 'top_1000', 'words') || [])
+                      )
+                    }
+                  else
+                    # Legacy format: data['tiers']['top_50'] is array
+                    {
+                      top_50: Set.new(data.dig('tiers', 'top_50') || []),
+                      top_200: Set.new((data.dig('tiers', 'top_50') || []) + (data.dig('tiers', 'top_200') || [])),
+                      top_1000: Set.new(
+                        (data.dig('tiers', 'top_50') || []) +
+                        (data.dig('tiers', 'top_200') || []) +
+                        (data.dig('tiers', 'top_1000') || [])
+                      )
+                    }
+                  end
+
+          metadata = data['metadata'] || {}
+
+          { tiers: tiers, metadata: metadata }
+        end
+
+        # Get list of languages with local YAML files.
+        #
+        # @return [Array<String>] List of available language codes
+        def available_languages
+          Dir.glob(File.join(DATA_DIR, '*.yml')).map { |f| File.basename(f, '.yml') }
+        end
+
+        # Check if a language has local data.
+        #
+        # @param language_code [String] ISO 639-1 language code
+        # @return [Boolean] True if data file exists
+        def available?(language_code)
+          File.exist?(File.join(DATA_DIR, "#{language_code}.yml"))
+        end
+
+        private
+
+        def load_from_yaml(yaml_file, requested_tier)
+          data = YAML.unsafe_load_file(yaml_file)
+
+          # Get all tiers from the data
+          yaml_tiers = data['tiers'] || {}
+
+          # Build cumulative tiers based on requested level
+          tier_50 = Set.new(yaml_tiers['top_50'] || [])
+          tier_200 = Set.new((yaml_tiers['top_50'] || []) + (yaml_tiers['top_200'] || []))
+          tier_1000 = Set.new(
+            (yaml_tiers['top_50'] || []) +
+            (yaml_tiers['top_200'] || []) +
+            (yaml_tiers['top_1000'] || [])
+          )
+
+          tiers = {
+            top_50: tier_50,
+            top_200: tier_200,
+            top_1000: tier_1000
+          }
+
+          metadata = data['metadata'] || {}
+
+          { tiers: tiers, metadata: metadata }
+        end
+
+        def empty_tiers
+          {
+            top_50: Set.new,
+            top_200: Set.new,
+            top_1000: Set.new
+          }
+        end
+      end
+    end
+  end
+end