genius-api 0.3.0

data/CONTRIBUTING.md

@@ -0,0 +1,368 @@
+# Project code style
+
+This file includes code style references which can help when contributing to project.
+
+## Documentation content
+
+1. [Overview][1]
+2. [Project structure][2]
+    1. [Outer layer][2.1]
+    2. [Inner layer][2.2]
+    3. [Extensions][2.3]
+    4. [Rakelib][2.4]
+3. [Naming convention][3]
+    1. [File naming][3.1]
+    2. [Module naming][3.2]
+    3. [Class naming][3.3]
+    4. [Parameters naming][3.4]
+    5. [Variables naming][3.5]
+4. [Code semantics][4]
+    1. [Define modules][4.1]
+    2. [Define classes][4.2]
+    3. [Define methods][4.3]
+5. [Contributing][5]
+    1. [Git commits][5.1]
+    2. [RuboCop][5.2]
+    3. [RSpec][5.3]
+    4. [Docscribe][5.4]
+    5. [RBS][5.5]
+    6. [Steep][5.6]
+6. [TODO][6]
+7. [License][7]
+
+## Overview
+
+This project will show patterns and tips to contribute in this project. Feel free to contribute there!
+
+## Project structure
+
+The project tree consists of several directories. Some of them are described at
+RubyGems [documentation](https://guides.rubygems.org/make-your-own-gem/). See it for clearance.
+
+Folder structure in the `lib` directory deserves special attention. There are two other folders there — `lib/extensions`
+and `lib/genius`, the last of which is divided into two more layers - outer and inner. The `api.rb` file (referred as
+the main file) acts as the outer layer, into which the entire interface is imported which is defined in inner layer
+referred as `lib/genius/api` folder.
+
+### Outer layer
+
+As mentioned above, the outer layer consists of only one main file where other files are included. The file consists of
+a main module and its submodule to preserve the structure of the project tree, as indicated in the
+RubyGems [documentation](https://guides.rubygems.org/patterns/#consistent-naming). The other files act as a category for
+the main module which is called `Genius`. Outer layer is stored in `lib/genius`
+
+### Inner layer
+
+The inner layer is a kind of bunch of interfaces and extensions (categories) for the main module. Each of the interface
+is named after the resource in [Genius API documentation](https://docs.genius.com). Inner layer is stored
+in `lib/genius/api`.
+
+### Extensions
+
+Extensions are the files which represents the methods which are used in a bunch of other methods in the inner layer.
+This kind of interfaces were bundled in a separate folder for multiple reuse in other methods. They are not a part of
+the `Genius` module interface, so it means that they are a category to other structures (`Hash`, `Object` or `String`
+classes). Extensions are stored in `lib/extensions`.
+
+### Rakelib
+
+Rakelib is another sort of extensions but it is used for generating the documentation. Note that the files in this
+directory are distributed under the BSD license!
+
+## Naming convention
+
+This paragraph will show the main conventions in naming of some structures or objects, such as files, classes, variables
+to represent their semantics more clear.
+
+### File naming
+
+The files are named after the resource from the [Genius API documentation](https://docs.genius.com). File names should
+not contain uppercase letters or contain non-letter characters except for the underscore. All files should be stored in
+the [inner layer](https://github.com/unurgunite/genius-api/CODESTYLE.md#inner-layer).
+
+### Module naming
+
+Modules should be defined inside the `Genius` module — a top-level project module — and they should be named after the
+filename where they defined.
+
+### Class naming
+
+For the most part, classes are used to represent errors and they are stored in the inner layers file — `api/errors.rb`.
+Each of this classes must end with the word `Error`.
+
+### Parameters naming
+
+Parameters should be named as a keyword arguments. This rule does not apply to private methods.
+See: [Style/OptionHash](https://www.rubydoc.info/github/bbatsov/RuboCop/RuboCop/Cop/Style/OptionHash)
+
+### Variables naming
+
+Variables should be named as in a style guide of the RuboCop.
+See: [Naming/VariableName](https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Naming/VariableName)
+
+## Code semantics
+
+This paragraph will show some of the style guides for defining some sorts of the structures.
+
+### Define modules
+
+All of the modules defined as a category for the main module `Genius`. For e.g., `Genius::Account`
+
+```ruby
+# lib/genius/api/account.rb
+module Genius # :nodoc:
+  module Account # :nodoc:
+    # some interface
+  end
+end
+```
+
+Among other things, modules must have documentation on the top of them. Documentation should consist of a brief
+description of the module, its semantics and the semantics of its interface - objects that the module uses, extensions,
+etc. For e.g.,
+
+```ruby
+# This module reflects the structure of our world, consisting of a class of people and a class of animals.
+module World
+  class Animal # :nodoc:
+    # some interface
+  end
+
+  class Human # :nodoc:
+    # some interface
+  end
+end
+```
+
+If no documentation is attached to the module, then a special tag in the form of a comment should be placed next to its
+name, indicating this — `# :nodoc:`. In instance,
+
+```ruby
+
+module A # :nodoc:
+  # some interface
+end
+```
+
+### Define classes
+
+As mentioned above, classes are usually represents error objects. This classes should be stored in a separate file
+— `lib/genius/errors.rb`, they must be inherited from the `Genius::Errors::GeniusExceptionSuperClass` which in turn is
+inherited from `StandardError` and they must have at least two readable attributes — `:msg` and `:exception_type`.
+Moreover, this constructor must invoke method `super(message)`. Declaration of more arguments for debugging or
+additional info to represent while error raised is optional. An example interface logic for such a class would be as
+follows:
+
+```ruby
+
+class SomeError < GeniusExceptionSuperClass # :nodoc:
+  attr_reader :msg, :exception_type, :some_useful_argument
+
+  # @param [String (frozen)] msg Exception message.
+  # @param [String (frozen)] exception_type Exception type.
+  # @param [String (frozen)] some_useful_argument Some useful stuff for debugging.
+  # @return [String (frozen)]
+  def initialize(msg: "Some error message.", exception_type: "some_exception_error", some_useful_argument: nil)
+    super(message)
+    @msg = msg + some_useful_argument
+    @exception_type = exception_type
+  end
+end
+```
+
+As modules, classes must have documentation on top of them and if there is no documentation was attached (in instance,
+if there is a category for built-in objects as `Hash` or `String` classes) there should be a special tag inside a
+comment which should be placed next to the class name — `# :nodoc:`.
+
+### Define methods
+
+Methods, among other structures, must have at least some documentation, consisting of at least its signature, as well as
+the arguments that the method takes. The documentation must be written in a specific syntax, according to
+the [YARD documentation](https://www.rubydoc.info/gems/yard/file/docs/Tags.md). This rule is specific for methods inside
+classes interface if they are object constructors, because they always point to the instance declaration, so they do not
+require explicit specification of their signature at the top of the comments section. For this sort of methods the
+return type can be omitted.
+
+Required YARD tags to indicate and theirs abstract syntax:
+
+- `@param [Class] param_name documentation.`
+- `@raise [ExceptionClass] if something went wrong.`
+- `@return [Class]`
+
+Required YARD tags to indicate and theirs abstract syntax:
+
+- `@private`
+- `@example Example usage`
+- `@option variable_name [Class] :option documentation.`
+- `@see #method_name`
+
+Example for regular singleton methods (inside modules)
+
+```ruby
+
+module M # :nodoc:
+  module A # :nodoc:
+    class << self
+      # +M::A.foo+                                    -> Integer
+      #
+      # Method documenation.
+      #
+      # @param [Integer] arg1 First integer argument.
+      # @param [Integer] arg2 Second integer argument.
+      # @raise [RuntimeError] if one of the argument is not an integer.
+      # @return [Integer]
+      def foo(arg1: nil, arg2: nil)
+        unless arg1.is_a?(Integer) || arg2.is_a?(Integer)
+          raise RuntimeError, 'Some error was raised'
+        end
+        arg1 + arg2
+      rescue RuntimeError => e
+        e.message
+      end
+    end
+  end
+end
+```
+
+Example for regular constructors.
+
+```ruby
+
+class SomeError < GeniusExceptionSuperClass # :nodoc:
+  attr_reader :msg, :exception_type, :some_useful_argument
+
+  # @param [String (frozen)] msg Exception message.
+  # @param [String (frozen)] exception_type Exception type.
+  # @param [String (frozen)] some_useful_argument Some useful stuff for debugging.
+  # @return [String (frozen)]
+  def initialize(msg: "Some error message.", exception_type: "some_exception_error", some_useful_argument: nil)
+    super(message)
+    @msg = msg + some_useful_argument
+    @exception_type = exception_type
+  end
+end 
+```
+
+## Contributing
+
+This section will demonstrate the rules for contributing in project
+
+### Git commits
+
+Git commits should clearly describe the purpose of your commit. For example, commits as _"Do smth"_ or _"Refactored some
+files"_ do not actually represent theirs content. Commits as _"Refactored `README.md`"_ reflects theirs content, so it
+will be unused to delve into the purpose of the commit most of the time.
+
+### RuboCop
+
+See: [RuboCop documentation](https://docs.rubocop.org/rubocop/index.html)
+
+Before pushing, you must be sure that the code you write is correct, so it should always be formatted through a static
+analyzer. Look towards the `rubocop -D` and `rubocop -A` commands.
+
+### RSpec
+
+Before pushing, run the test suite to ensure nothing is broken:
+
+```shell
+bundle exec rspec
+```
+
+The test suite currently has 84 examples with 0 failures.
+
+### Docscribe
+
+Docscribe keeps YARD annotations in sync with the codebase. After making changes to method signatures, run:
+
+```shell
+bundle exec docscribe lib
+```
+
+This will check for missing or outdated documentation. To regenerate annotations automatically:
+
+```shell
+bundle exec docscribe -A --rbs-collection lib
+```
+
+The project's docscribe configuration is in `docscribe.yml` at the project root.
+
+### RBS
+
+RBS type signatures are located in `sig/` directory. After adding or changing methods, update the corresponding `.rbs`
+files. Validate signatures with:
+
+```shell
+bundle exec rbs validate
+```
+
+### Steep
+
+Steep performs static type checking using RBS signatures. Run the type checker:
+
+```shell
+bundle exec steep check
+```
+
+All type errors must be resolved before committing.
+
+## TODO
+
+- [ ] Look at the documentation with fresh eyes
+- [ ] Check the file for all sorts of errors
+
+## License
+
+The documentation is available as open source under the terms of
+the [CC BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/)
+
+![CC BY-SA 4.0](https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by-nc.svg)
+
+[1]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#overview
+
+[2]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#project-structure
+
+[2.1]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#outer-layer
+
+[2.2]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#inner-layer
+
+[2.3]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#extensions
+
+[2.4]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#rakelib
+
+[3]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#naming-convention
+
+[3.1]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#file-naming
+
+[3.2]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#module-naming
+
+[3.3]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#class-naming
+
+[3.4]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#parameters-naming
+
+[3.5]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#variables-naming
+
+[4]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#code-semantics
+
+[4.1]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#define-modules
+
+[4.2]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#define-classes
+
+[4.3]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#define-methods
+
+[5]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#contributing
+
+[5.1]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#git-commits
+
+[5.2]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#rubocop
+
+[5.3]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#rspec
+
+[5.4]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#docscribe
+
+[5.5]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#rbs
+
+[5.6]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#steep
+
+[6]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#todo
+
+[7]:https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md#license

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'parallel', '< 2.0' # 2.0+ requires Ruby >= 3.3

data/Gemfile.lock

@@ -0,0 +1,174 @@
+PATH
+  remote: .
+  specs:
+    genius-api (0.3.0)
+      httparty (~> 0.21)
+      nokogiri
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    bigdecimal (4.1.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
+    diff-lcs (1.6.2)
+    docscribe (1.4.1)
+      parser (>= 3.3)
+      prism (~> 1.8)
+    dotenv (2.7.6)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
+    fileutils (1.8.0)
+    httparty (0.24.2)
+      csv
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
+    json (2.19.9)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mini_mime (1.1.5)
+    multi_xml (0.9.1)
+      bigdecimal (>= 3.1, < 5)
+    nokogiri (1.19.3-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.87.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
+    rubocop-sorted_methods_by_call (1.2.3)
+      lint_roller
+      rubocop (>= 1.72.0)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    steep (2.0.0)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.17.0.4, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.2)
+      prism (>= 0.25.0)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 4.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 5)
+      uri (>= 0.12.0)
+    strscan (3.1.8)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    yard (0.9.44)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  coderay
+  docscribe
+  dotenv (~> 2.7.6)
+  genius-api!
+  parallel (< 2.0)
+  rake (~> 13.0)
+  rbs
+  rspec (~> 3.4)
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  rubocop-sorted_methods_by_call
+  steep
+  yard
+
+BUNDLED WITH
+  4.0.14