amka 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 39f2441f545f0d191f6d676cf36159edd5f73e84
-  data.tar.gz: 5d169c49e5b564d2418883e458da46c9e6fdafee
+SHA256:
+  metadata.gz: 5f2628c4521fdb7fc9d1c9a09318e9189d837ede318ac1d19ac5fc606a1b9c24
+  data.tar.gz: da07a7a6bb486d1409f26a25969fc109ec392bac6b9e8c237a88fd6d0a816650
 SHA512:
-  metadata.gz: 42afd4b4c20dfc561ac5583e8684ad4a078f1b7ff5532d7e7fc113d46812d4899e31783e4c4e6216d81401a2acfef1dedf09781b709e9a99dc6ec2d24f90a2bf
-  data.tar.gz: 5b2e20904e8ea39b2b960aeb61364d3964cc72446ed46ce20e22a496cfb3a1bc6f08fa0befcbd6a03ffa8dde3bd6925e83262be13837317d986c9b965c6466c0
+  metadata.gz: 56db96d08effcd378cb0c7f2bd7ae18041c2ce04c2d195152d94714e1fa750b67a1230467bd15b7871ec06dcd7632e96087dd7af3a55b44cbc4e248221a67754
+  data.tar.gz: a042775a314e742322c36c7769d07ffd152ce2893147226c64bafe12d6a4da6eaa281f931dcdc43cb22e3dc9fefa25b08e0dbd311f71a17179a769490a2938d7

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2025-04-16
+
+### Changed
+
+- Updated minimum Ruby version to 2.7.0
+- Migrated from Minitest to RSpec for testing
+- Modernized gem infrastructure
+- Added GitHub Actions for CI
+- Added SimpleCov for test coverage
+- Improved documentation
+
+### Security
+
+- Added MFA requirement for gem publishing
+- Updated development dependencies
+
+## [1.0.1] - 2015-10-15
+
+### Added
+
+- Initial release

data/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to AMKA
+
+Thank you for considering contributing to the AMKA gem! This document outlines the process for contributing to this project.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
+
+- **Use the GitHub issue tracker** — Check if the bug has already been reported by searching on GitHub under [Issues](https://github.com/ioagel/amka/issues).
+- **Use the bug report template** — If you're reporting a bug, be sure to include all the information requested in the bug report template.
+- **Provide specific examples** — Include specific steps to reproduce the problem, with example code if possible.
+- **Describe the behavior you observed** — What happened? How did it differ from what you expected?
+- **Include relevant details** — OS, Ruby version, AMKA gem version, etc.
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality.
+
+- **Use the GitHub issue tracker** — Check if the enhancement has already been suggested by searching on GitHub under [Issues](https://github.com/ioagel/amka/issues).
+- **Use the feature request template** — Include as much detail as possible in the template.
+- **Provide a clear use case** — Explain why this enhancement would be useful to most AMKA users.
+
+### Pull Requests
+
+- **Fill in the required template**
+- **Follow the Ruby style guide**
+- **Include tests** — Your patch won't be accepted if it doesn't have tests.
+- **Document your changes** — Update any relevant documentation.
+- **Include updates to the CHANGELOG.md** file for any user-facing changes.
+- **Create feature branches** — Don't ask us to pull from your main branch.
+
+## Development Process
+
+### Setting Up the Development Environment
+
+1. Fork and clone the repository
+2. Run `bin/setup` to install dependencies
+3. Run `bundle exec rake spec` to run the tests
+
+### Testing
+
+- All tests must pass before a pull request will be accepted
+- Write tests for all new functionality
+- Run tests using `bundle exec rake spec`
+- Check code coverage (we aim for >90%) using `open coverage/index.html` after running tests
+
+### Style Guidelines
+
+- Follow the Ruby style guide:
+  - Use 2 spaces for indentation
+  - Use snake_case for methods and variables
+  - Use CamelCase for classes and modules
+  - Add descriptive comments for public methods and classes
+- Run `bundle exec rubocop` before submitting to ensure code quality
+- Add YARD documentation for new public methods
+
+### Git Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature")
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Limit the first line to 72 characters or less
+- Reference issues and pull requests after the first line
+
+## Releasing a New Version
+
+For maintainers only:
+
+1. Update the version number in `lib/amka/version.rb`
+2. Update the CHANGELOG.md
+3. Run the test suite to make sure everything works
+4. Commit changes with message "Bump version to x.y.z"
+5. Tag the commit with "vx.y.z"
+6. Push to GitHub
+7. Run `bundle exec rake release`
+
+## Additional Resources
+
+- [General GitHub documentation](https://help.github.com)
+- [GitHub pull request documentation](https://help.github.com/articles/about-pull-requests/)
+- [Ruby style guide](https://github.com/rubocop/ruby-style-guide)
+
+Thank you for contributing!

data/README.md

@@ -1,23 +1,37 @@
 # AMKA and Luhn IDs Validator / Generator
-##### Α.Μ.Κ.Α (Αριθμός Μητρώου Κοινωνικής Ασφάλισης)
+
+[![Ruby CI](https://github.com/ioagel/amka/actions/workflows/ci.yml/badge.svg)](https://github.com/ioagel/amka/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/amka.svg)](https://badge.fury.io/rb/amka)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/gems/amka)
+
+## Α.Μ.Κ.Α (Αριθμός Μητρώου Κοινωνικής Ασφάλισης)
+
 This gem validates **A.M.K.A** Greek social security IDs by
 using the Luhn algorithm, as described in this [Wikipedia article](https://en.wikipedia.org/wiki/Luhn_algorithm).
 The only additional validation needed that applies to Greek A.M.K.A is that the
 first 6 digits must be a valid date (date of birth).
 
-The gem also *validates* and *generates* **Luhn** ids, as well as *generating*
-**AMKA** (like) ids. The *like* here means that the AMKA generated are not
+The gem also _validates_ and _generates_ **Luhn** ids, as well as _generating_
+**AMKA** (like) ids. The _like_ here means that the AMKA generated are not
 **real** as those provided by the Official Authorities in Greece.
 
 There is an online calculator in [planetcalc](http://planetcalc.com/2464/), you
 can validate the results of the gem, until you are confident that is working
 as it should. Try you own and your family AMKA.
 
-**DISCLAIMER**: The gem *does not* validate the real existence of the A.M.K.A or that it
+**DISCLAIMER**: The gem _does not_ validate the real existence of the A.M.K.A or that it
 belongs to a given person. The same applies to the generator.
 
+## Documentation
+
+- [Usage Guide](USAGE.md) - Comprehensive examples and use cases
+- [API Documentation](http://rubydoc.info/gems/amka) - Full method documentation
+- [Contributing Guide](CONTRIBUTING.md) - How to contribute to this gem
+- [Changelog](CHANGELOG.md) - Version history and changes
+
 ## Installation
-Requires ruby >= 2.0.0
+
+Requires ruby >= 2.7.0
 
 Add this line to your application's Gemfile:
 
@@ -27,13 +41,17 @@ gem 'amka'
 
 And then execute:
 
-    $ bundle
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install amka
+```bash
+gem install amka
+```
 
-## Usage
+## Quick Start
 
 ```ruby
 require 'amka'
@@ -43,6 +61,10 @@ Amka.valid?('01011441432')
 # returns false (i did not use a valid one in this example just in case
 # it belonged to a real person!!!!)
 
+# You can also pass the 4 digit year of birth as a second string argument
+# This will increase the accuracy of the date part of validation to 100%.
+Amka.valid?('111098xxxxx', '1998')
+
 # To generate (returns the AMKA as a string)
 Amka.generate
 
@@ -58,24 +80,28 @@ Amka::Luhn.valid?('1142376755673') # returns true
 # To generate a Luhn id
 # takes up to 2 arguments: total, id_start(optional)
 # total: how many digits you want in the Luhn generated
-# id_start: string of numbers to include from the start of the Luhn
-# - total must be greater than id_start by at least one, to account for the
-#   rightmost check digit.
+# id_start: string of numbers to include at the start of the Luhn
+# - total must be greater than the length of id_start by at least one, to
+# account for the rightmost check digit.
 Amka::Luhn.generate(13) # returns '5361281695669'
 Amka::Luhn.generate(10, '123456789') # returns '1234567897', 7 is the check digit.
 Amka::Luhn.generate(15, '12345') # returns something like: '123450789968798'
 ```
 
-## TODO
+See the [Usage Guide](USAGE.md) for more detailed examples and advanced usage.
 
-Add tests for the Luhn class.
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ioagel/amka.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/ioagel/amka>.
 
+Please see the [Contributing Guide](CONTRIBUTING.md) for more details on how to contribute.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/USAGE.md

@@ -0,0 +1,161 @@
+# AMKA Gem Usage Guide
+
+This document provides comprehensive examples and guidelines for using the AMKA gem in your Ruby projects.
+
+## Table of Contents
+
+- [AMKA Gem Usage Guide](#amka-gem-usage-guide)
+  - [Table of Contents](#table-of-contents)
+  - [Understanding AMKA](#understanding-amka)
+  - [Basic Usage](#basic-usage)
+    - [Installation](#installation)
+    - [Validation](#validation)
+    - [Generation](#generation)
+  - [Advanced Usage](#advanced-usage)
+    - [Working with Birth Dates](#working-with-birth-dates)
+    - [Using the Luhn Algorithm Directly](#using-the-luhn-algorithm-directly)
+  - [Error Handling](#error-handling)
+  - [Performance Considerations](#performance-considerations)
+  - [Use Cases](#use-cases)
+
+## Understanding AMKA
+
+An AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης) is a unique 11-digit identification number used in Greece. It's similar to a Social Security Number in the United States and follows these rules:
+
+1. It's always exactly 11 digits long
+2. The first 6 digits represent the person's date of birth in format DDMMYY
+3. The number (as a whole) must pass validation by the Luhn algorithm
+4. The last digit is a check digit computed using the Luhn algorithm
+
+## Basic Usage
+
+### Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'amka'
+```
+
+Or install it directly:
+
+```bash
+gem install amka
+```
+
+Then require it in your code:
+
+```ruby
+require 'amka'
+```
+
+### Validation
+
+You can validate an AMKA number with a simple call:
+
+```ruby
+# Basic validation
+Amka.valid?('01019012345')  # => true or false
+
+# The validation checks:
+# 1. If it's exactly 11 digits
+# 2. If the first 6 digits form a valid date (ddmmyy)
+# 3. If the number passes the Luhn algorithm check
+```
+
+When working with dates from different centuries, you can provide the 4-digit year for more accurate validation:
+
+```ruby
+# Explicitly specify century for validation
+Amka.valid?('01019012345', '1990')  # => true
+Amka.valid?('01019012345', '2090')  # => false (if the year doesn't match)
+```
+
+### Generation
+
+You can generate random valid AMKA numbers:
+
+```ruby
+# Generate a random valid AMKA
+amka = Amka.generate  # => "01019012345"
+```
+
+Or generate an AMKA with a specific birth date:
+
+```ruby
+# Generate an AMKA for someone born January 1, 1990
+amka = Amka.generate('1/1/1990')  # => "01019012345"
+
+# Days and months can be 1 or 2 digits
+amka = Amka.generate('15/12/1985')  # => "15128512345"
+```
+
+## Advanced Usage
+
+### Working with Birth Dates
+
+The first 6 digits of an AMKA represent a date of birth in DDMMYY format:
+
+```ruby
+amka = '01019012345'
+birth_date = Date.strptime(amka[0..5], '%d%m%y')  # => #<Date: 1990-01-01>
+
+# For ambiguous 2-digit years, you might need to adjust the century
+if birth_date > Date.today
+  birth_date = Date.strptime(amka[0..3] + '19' + amka[4..5], '%d%m%Y')
+end
+```
+
+### Using the Luhn Algorithm Directly
+
+The gem includes a standalone implementation of the Luhn algorithm that can be used for other purposes:
+
+```ruby
+# Validate any number against the Luhn algorithm
+Amka::Luhn.valid?('4532015112830366')  # => true (valid credit card number)
+Amka::Luhn.valid?('1234567890')        # => false
+
+# Generate a valid Luhn number of specific length
+luhn_id = Amka::Luhn.generate(16)  # => "4532015112830366"
+
+# Generate a valid Luhn number with a specific prefix
+luhn_id = Amka::Luhn.generate(16, '4532')  # => "4532015112830366"
+```
+
+## Error Handling
+
+The gem will raise descriptive `ArgumentError` exceptions for invalid inputs:
+
+```ruby
+begin
+  Amka.valid?(12345)  # Not a string
+rescue ArgumentError => e
+  puts e.message  # => "'12345': must be a string of digits only!"
+end
+
+begin
+  Amka.generate('invalid-date')
+rescue ArgumentError => e
+  puts e.message  # => "date of birth must be in this format: [d]d/[m]m/yyyy"
+end
+
+begin
+  Amka.generate('31/2/1990')  # February 31st doesn't exist
+rescue ArgumentError => e
+  puts e.message  # => "The date of birth is invalid!"
+end
+```
+
+## Performance Considerations
+
+- The validation and generation methods are lightweight and suitable for high-volume use
+- No external dependencies are required
+- All operations are performed in memory without any I/O
+
+## Use Cases
+
+- Government systems that need to validate AMKA numbers
+- Healthcare applications that need to work with patient identification
+- Testing systems that need to generate sample data
+- Any application that needs to implement the Luhn algorithm validation
+- Form validation for Greek websites

data/lib/amka/luhn.rb

@@ -1,40 +1,105 @@
+# frozen_string_literal: true
+
 module Amka
   # Implements the Luhn algorithm as described in the wikipedia article
   # https://en.wikipedia.org/wiki/Luhn_algorithm
+  #
+  # The Luhn algorithm (also known as the "modulus 10" or "mod 10" algorithm)
+  # is a simple checksum formula used to validate various identification numbers,
+  # such as credit card numbers, IMEI numbers, and national identification numbers
+  # (like AMKA in Greece).
+  #
+  # ## Algorithm Steps
+  # 1. Starting from the rightmost digit, double the value of every second digit
+  # 2. If doubling a number results in a two-digit number (>9), subtract 9 from the result
+  # 3. Sum all digits (both doubled and non-doubled)
+  # 4. If the total modulo 10 is 0, then the number is valid
+  #
+  # ## Uses
+  # This class provides both validation of existing IDs and generation of
+  # new valid IDs that follow the Luhn algorithm.
+  #
+  # @example Validate a Luhn ID
+  #   Amka::Luhn.valid?('79927398713')  #=> true
+  #
+  # @example Generate a new Luhn ID of specified length
+  #   Amka::Luhn.generate(10)  #=> "7992739871"
+  #
+  # @example Generate a Luhn ID with a specific prefix
+  #   Amka::Luhn.generate(16, '4532')  #=> "4532015112830366"
   class Luhn
-
+    # Validates if a given ID follows the Luhn algorithm
+    #
+    # Applies the standard Luhn algorithm to check if a number is valid:
+    # 1. From the rightmost digit, double every second digit
+    # 2. Sum the digits (if any doubled digit > 9, subtract 9)
+    # 3. If the sum is divisible by 10, the number is valid
+    #
+    # @param luhn_id [String] the ID to validate, must be a string containing only digits
+    # @return [Boolean] true if valid according to Luhn algorithm, false otherwise
+    # @raise [ArgumentError] if the ID is not a string of digits
+    # @example Validating a credit card number
+    #   Amka::Luhn.valid?('4532015112830366')  #=> true
+    # @example Validating an invalid number
+    #   Amka::Luhn.valid?('1234567890')  #=> false
     def self.valid?(luhn_id)
-      Utils.string_with_digits_or_fail luhn_id
+      Utils.string_with_digits_or_fail(luhn_id)
 
       digits_sum = calculate_digits_sum(luhn_id)
 
-      (digits_sum % 10) == 0
+      (digits_sum % 10).zero?
     end
 
+    # Generates a valid Luhn ID
+    #
+    # Creates a number that passes the Luhn check by:
+    # 1. Taking the provided prefix (or creating a random one)
+    # 2. Calculating what the check digit should be for the number to be valid
+    # 3. Appending the check digit to create a valid Luhn number
+    #
+    # @param total [Integer] the total length of the ID to generate
+    # @param id_start [String] optional digits to use at the start of the ID
+    # @return [String] a valid Luhn ID of exactly 'total' length
+    # @raise [ArgumentError] if arguments are invalid
+    # @example Generate a 16-digit number (like a credit card)
+    #   Amka::Luhn.generate(16)  #=> "4532015112830366"
+    # @example Generate a number with a specific prefix
+    #   Amka::Luhn.generate(10, '123456')  #=> "1234567897"
+    # @example Special case for length 1
+    #   Amka::Luhn.generate(1)  #=> "0"
     def self.generate(total, id_start = '')
       validate_generate_args_or_fail(total, id_start)
-      id_start == '' && total == 1 and return '0'
+      return '0' if id_start.empty? && total == 1
 
       last_digits_length = total - id_start.length
-      last_digits_except_check = ''
+      # Use String.new to create an unfrozen string
+      last_digits_except_check = String.new
       # subtract by one to account for the check digit
       (last_digits_length - 1).times { last_digits_except_check << rand(0..9).to_s }
-      luhn_id_except_check_digit = id_start << last_digits_except_check
+      # Using + instead of << for string concatenation to prevent frozen string issues
+      luhn_id_except_check_digit = id_start + last_digits_except_check
 
-      digits_sum = calculate_digits_sum(luhn_id_except_check_digit, true)
+      digits_sum = calculate_digits_sum(luhn_id_except_check_digit, generate: true)
 
       check_digit = (digits_sum * 9) % 10
 
-      luhn_id_except_check_digit << check_digit.to_s
+      luhn_id_except_check_digit + check_digit.to_s
     end
 
-    def self.calculate_digits_sum(luhn_id, generate = false)
+    # Calculates the sum of digits according to the Luhn algorithm
+    #
+    # This implementation handles both validation of existing numbers and
+    # generation of new numbers with the 'generate' parameter determining the pattern
+    # of which digits to double.
+    #
+    # @param luhn_id [String] the ID to calculate the sum for
+    # @param generate [Boolean] whether we're generating (affects digit doubling pattern)
+    # @return [Integer] the sum of digits according to Luhn algorithm rules
+    def self.calculate_digits_sum(luhn_id, generate: false)
       luhn_id_double = luhn_id.chars.reverse.map(&:to_i).map.with_index do |digit, i|
-        if (!generate && i.odd?) || (generate && i.even?)
-          if (digit *= 2) > 9
-            # digit = digit.to_s.chars.map(&:to_i).reduce(:+)
-            digit -= 9
-          end
+        if ((!generate && i.odd?) || (generate && i.even?)) && ((digit *= 2) > 9)
+          # Same as: digit = digit.to_s.chars.map(&:to_i).reduce(:+)
+          digit -= 9
         end
         digit
       end
@@ -42,14 +107,25 @@ module Amka
     end
     private_class_method :calculate_digits_sum
 
+    # Validates the arguments for the generate method
+    #
+    # Performs several checks:
+    # 1. Ensures id_start is a string containing only digits (or empty)
+    # 2. Ensures total is a positive integer
+    # 3. Ensures total > id_start.length to allow room for the check digit
+    #
+    # @param total [Integer] the total length of the ID to generate
+    # @param id_start [String] digits to use at the start of the ID
+    # @raise [ArgumentError] if arguments are invalid
     def self.validate_generate_args_or_fail(total, id_start)
-      Utils.string_with_digits_or_empty_or_fail id_start
-      Utils.positive_integer_or_fail total
-      total > id_start.length or
-        fail ArgumentError, "'#{total}': must be greater at least by one from string length: "\
-                            "#{id_start.length}, to account for the check digit!"
+      Utils.string_with_digits_or_empty_or_fail(id_start)
+      Utils.positive_integer_or_fail(total)
+
+      return if total > id_start.length
+
+      raise ArgumentError, "'#{total}': must be greater at least by one from string length: " \
+                           "#{id_start.length}, to account for the check digit!"
     end
     private_class_method :validate_generate_args_or_fail
-
   end
 end

data/lib/amka/utils.rb

@@ -1,57 +1,175 @@
-module Amka
+# frozen_string_literal: true
 
+module Amka
+  # Utility methods for the Amka module
+  #
+  # This class provides helper methods for parameter validation and date handling
+  # that are used throughout the AMKA implementation. These utilities encapsulate
+  # common validation logic and error handling to keep the main code cleaner.
+  #
+  # The methods primarily fall into these categories:
+  # - String validation (digits only, format checking)
+  # - Number validation
+  # - Date validation and conversion
+  #
+  # All validation methods follow a consistent pattern: they either succeed silently
+  # or raise descriptive ArgumentError exceptions.
   class Utils
     class << self
+      # Validates that the input is a string with only digits
+      #
+      # Used when a value must be a non-empty string of digits, such as
+      # an ID or number that needs to be processed digit by digit.
+      #
+      # @param id [String] the string to validate
+      # @raise [ArgumentError] if the string is not all digits
+      # @example
+      #   Utils.string_with_digits_or_fail('12345')  # => nil (success)
+      #   Utils.string_with_digits_or_fail('123abc') # => ArgumentError
+      #   Utils.string_with_digits_or_fail('')       # => ArgumentError
       def string_with_digits_or_fail(id)
-        id.is_a?(String) && id.match(/\A\d+\Z/) or
-          fail ArgumentError, "'#{id}': must be a string of digits only!"
+        return if id.is_a?(String) && id.match(/\A\d+\Z/)
+
+        raise ArgumentError, "'#{id}': must be a string of digits only!"
       end
 
+      # Validates that the input is a string with only digits or empty
+      #
+      # Similar to string_with_digits_or_fail but allows empty strings.
+      # Used when an optional string of digits is expected.
+      #
+      # @param id [String] the string to validate
+      # @raise [ArgumentError] if the string contains non-digits
+      # @example
+      #   Utils.string_with_digits_or_empty_or_fail('12345')  # => nil (success)
+      #   Utils.string_with_digits_or_empty_or_fail('')       # => nil (success)
+      #   Utils.string_with_digits_or_empty_or_fail('123abc') # => ArgumentError
       def string_with_digits_or_empty_or_fail(id)
-        id.is_a?(String) && id.match(/\A\d*\Z/) or
-          fail ArgumentError, "'#{id}': must be a string of digits or even an empty one!"
+        return if id.is_a?(String) && id.match(/\A\d*\Z/)
+
+        raise ArgumentError, "'#{id}': must be a string of digits or even an empty one!"
       end
 
+      # Validates that the input is a string with date in format dd/mm/yyyy
+      #
+      # Checks that the string follows the Greek date format where:
+      # - Day can be 1 or 2 digits (1-31)
+      # - Month can be 1 or 2 digits (1-12)
+      # - Year must be 4 digits
+      #
+      # Note: This only checks the format, not if the date is valid
+      # (e.g., 31/02/2022 would pass this check but is not a valid date)
+      #
+      # @param date [String] the date string to validate
+      # @raise [ArgumentError] if the date format is invalid
+      # @example
+      #   Utils.string_with_date_or_fail('1/1/2020')   # => nil (success)
+      #   Utils.string_with_date_or_fail('31/12/2020') # => nil (success)
+      #   Utils.string_with_date_or_fail('2020-12-31') # => ArgumentError
       def string_with_date_or_fail(date)
-        date.is_a?(String) && date.match(%r{\A\d?\d{1}/\d?\d{1}/\d{4}\Z}) or
-          fail ArgumentError, 'date of birth must be in this format: [d]d/[m]m/yyyy'
+        return if date.is_a?(String) && date.match(%r{\A\d?\d{1}/\d?\d{1}/\d{4}\Z})
+
+        raise ArgumentError, 'date of birth must be in this format: [d]d/[m]m/yyyy'
       end
 
+      # Validates that the input is a positive integer
+      #
+      # Used primarily for length/count parameters where negative or
+      # zero values would be invalid.
+      #
+      # @param num [Integer] the number to validate
+      # @raise [ArgumentError] if the number is not a positive integer
+      # @example
+      #   Utils.positive_integer_or_fail(10)  # => nil (success)
+      #   Utils.positive_integer_or_fail(0)   # => ArgumentError
+      #   Utils.positive_integer_or_fail(-5)  # => ArgumentError
+      #   Utils.positive_integer_or_fail('5') # => ArgumentError
       def positive_integer_or_fail(num)
-        num.is_a?(Integer) && num > 0 or
-          fail ArgumentError, "'#{num}': must be a non-zero positive integer!"
+        return if num.is_a?(Integer) && num.positive?
+
+        raise ArgumentError, "'#{num}': must be a non-zero positive integer!"
       end
 
+      # Validates that the given date string is a valid date
+      #
+      # This is a more comprehensive date validation that:
+      # 1. Checks the basic format
+      # 2. Confirms the date actually exists in the calendar
+      # 3. Optionally verifies it matches a specific 4-digit year
+      #
+      # This is particularly important for AMKA validation since the
+      # first 6 digits must represent a valid date of birth.
+      #
+      # @param date [String] the date string to validate in format ddmmyy
+      # @param year [String, nil] optional 4-digit year to check against
+      # @return [Boolean] true if date is valid, false otherwise
+      # @raise [ArgumentError] if year format or range is invalid
+      # @example Simple validation (auto-guesses century)
+      #   Utils.valid_date?('010190')  # => true (January 1, 1990)
+      # @example With explicit year
+      #   Utils.valid_date?('010190', '1990')  # => true
+      #   Utils.valid_date?('010190', '2090')  # => ArgumentError
       def valid_date?(date, year = nil)
         return false unless date.match(/\A\d{6,}\Z/)
 
-        unless year.nil?
-          year.is_a?(String) && year.match(/\A\d{4}\Z/) or
-            fail ArgumentError, 'Year must be a 4 digit string'
-          year.to_i >= 1800 && year.to_i <= Date.today.year or
-            fail ArgumentError, 'Year must be between 1800 and current!'
-          year[2..3] == date[4..5] or
-            fail ArgumentError, 'The last 2 digits of year parameter and the 2 digits'\
-                                ' that correspond to the year in date must be equal!'
-          begin
-            dob = Date.strptime(date[0..3] << year, '%d%m%Y')
-            return dob < Date.today
-          rescue ArgumentError
-            return false
-          end
+        if year
+          validate_year_format(year, date)
+          return validate_full_date(date, year)
+        end
+
+        validate_short_date(date)
+      end
+
+      private
+
+      # Validates the year format and range
+      #
+      # @param year [String] the 4-digit year to validate
+      # @param date [String] the date string (for year digit comparison)
+      # @raise [ArgumentError] if year format or range is invalid
+      def validate_year_format(year, date)
+        unless year.is_a?(String) && year.match(/\A\d{4}\Z/)
+          raise ArgumentError, 'Year must be a 4 digit string'
         end
 
-        begin
-          date_2_digit_year = Date.strptime(date[0..5], '%d%m%y')
-          if date_2_digit_year > Date.today
-            Date.strptime(date[0..3] << '19' << date[4..5], '%d%m%Y')
-          end
-          return true
-        rescue ArgumentError
-          return false
+        unless year.to_i.between?(1800, Date.today.year)
+          raise ArgumentError, 'Year must be between 1800 and current!'
         end
+
+        return if year[2..3] == date[4..5]
+
+        raise ArgumentError, 'The last 2 digits of year parameter and the 2 digits ' \
+                             'that correspond to the year in date must be equal!'
+      end
+
+      # Validates a date with a full 4-digit year
+      #
+      # Checks if the given date in DDMMYYYY format is valid and in the past.
+      #
+      # @param date [String] the date string (first 6 digits, format ddmmyy)
+      # @param year [String] the 4-digit year
+      # @return [Boolean] true if date is valid and in the past
+      def validate_full_date(date, year)
+        dob = Date.strptime(date[0..3] << year, '%d%m%Y')
+        dob < Date.today
+      rescue ArgumentError
+        false
+      end
+
+      # Validates a date with just 2-digit year
+      #
+      # Handles the ambiguity of 2-digit years by trying to interpret
+      # them as 20xx or 19xx years based on what makes sense.
+      #
+      # @param date [String] the date string (first 6 digits, format ddmmyy)
+      # @return [Boolean] true if date is valid
+      def validate_short_date(date)
+        date_2_digit_year = Date.strptime(date[0..5], '%d%m%y')
+        Date.strptime(date[0..3] << '19' << date[4..5], '%d%m%Y') if date_2_digit_year > Date.today
+        true
+      rescue ArgumentError
+        false
       end
     end
   end
-
 end

data/lib/amka/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Amka
-  VERSION = '1.0.1'
+  VERSION = '2.0.0'
 end

data/lib/amka.rb

@@ -1,10 +1,54 @@
-require 'amka/version'
+# frozen_string_literal: true
+
+require_relative 'amka/version'
 require 'date'
 
+# The Amka module provides functionality for validating and generating
+# Greek A.M.K.A (social security) IDs as well as generic Luhn algorithm IDs.
+# A.M.K.A IDs follow the Luhn algorithm and have their first 6 digits
+# representing the date of birth in format DDMMYY.
+#
+# An AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης) is a unique 11-digit
+# number assigned to each Greek citizen or resident who works, pays social
+# security contributions, or is entitled to healthcare. It follows these rules:
+#
+# 1. The first 6 digits represent the date of birth in format DDMMYY
+# 2. The remaining 5 digits include a check digit based on the Luhn algorithm
+# 3. The total length is always 11 digits
+#
+# @example Validating an AMKA
+#   Amka.valid?('01018012345')  #=> true or false
+#
+# @example Generating a random AMKA
+#   Amka.generate  #=> "21129012345"
+#
+# @example Generating an AMKA with specific birth date
+#   Amka.generate('21/12/1990')  #=> "21129012345"
+#
+# @author Ioannis Angelakopoulos
+# @since 1.0.0
 module Amka
+  # Standard error class for the Amka gem
+  class Error < StandardError; end
 
+  # Validates whether a given string is a valid AMKA
+  #
+  # The validation checks three conditions:
+  # 1. The AMKA must be exactly 11 digits long
+  # 2. The first 6 digits must form a valid date (DDMMYY format)
+  # 3. The entire number must satisfy the Luhn algorithm check
+  #
+  # @param amka [String] the AMKA to validate, must be a string containing only digits
+  # @param year [String, nil] optional four-digit year to match against
+  #   When provided, improves the validation by ensuring the birth year
+  #   matches exactly (resolves century ambiguity in 2-digit years)
+  # @return [Boolean] true if all validation criteria are met, false otherwise
+  # @example Validating with default century assumption
+  #   Amka.valid?('17019012345')  #=> true
+  # @example Validating with explicit year
+  #   Amka.valid?('17019012345', '1990')  #=> true
   def self.valid?(amka, year = nil)
-    Utils.string_with_digits_or_fail amka
+    Utils.string_with_digits_or_fail(amka)
 
     return false unless length_is_11?(amka)
 
@@ -13,19 +57,40 @@ module Amka
     false
   end
 
+  # Generates a random valid AMKA
+  #
+  # This method can create an AMKA with either:
+  # - A random valid birth date (when called without parameters)
+  # - A specific birth date (when called with a date parameter)
+  #
+  # The generated AMKA will always satisfy all validation rules:
+  # - 11 digits in length
+  # - First 6 digits form a valid date
+  # - Passes the Luhn algorithm check
+  #
+  # @param date_of_birth [String, nil] optional date in format 'dd/mm/yyyy'
+  # @return [String] a valid AMKA with the first 6 digits representing the
+  #   birth date, and the remainder satisfying the Luhn algorithm
+  # @example Generate a random AMKA
+  #   Amka.generate  #=> "01011912345"
+  # @example Generate an AMKA with specific birth date
+  #   Amka.generate('1/1/1990')  #=> "01019012345"
   def self.generate(date_of_birth = nil)
     return generate_with_date_of_birth(date_of_birth) unless date_of_birth.nil?
 
-    date_6_digits = ''
+    date_6_digits = String.new
     loop do
-      day = rand(0..3).to_s << rand(0..9).to_s
+      day = "#{rand(0..3)}#{rand(0..9)}"
       next if day == '00' || day.to_i > 31
-      month = rand(0..1).to_s << rand(0..2).to_s
+
+      month = "#{rand(0..1)}#{rand(0..2)}"
       next if month == '00' || month.to_i > 12
-      year = rand(19..20).to_s << rand(0..9).to_s << rand(0..9).to_s
+
+      year = "#{rand(19..20)}#{rand(0..9)}#{rand(0..9)}"
       next if year.to_i > Date.today.year
 
-      if Utils.valid_date?(date = day << month << year[2..3], year)
+      date = day + month + year[2..3]
+      if Utils.valid_date?(date, year)
         date_6_digits = date
         break
       end
@@ -34,23 +99,43 @@ module Amka
     Luhn.generate(11, date_6_digits)
   end
 
+  # Generates an AMKA with a specific date of birth
+  #
+  # @param date_of_birth [String] date in format 'dd/mm/yyyy'
+  #   Day and month can be either 1 or 2 digits
+  #   Year must be 4 digits
+  # @return [String] a valid AMKA with the given date of birth
+  # @raise [ArgumentError] if date format is invalid or date is invalid
+  # @example
+  #   Amka.generate_with_date_of_birth('1/12/1980')  #=> "01128012345"
+  # @example Invalid date raises an error
+  #   Amka.generate_with_date_of_birth('31/2/1990')
+  #   #=> ArgumentError: The date of birth is invalid!
   def self.generate_with_date_of_birth(date_of_birth)
-    Utils.string_with_date_or_fail date_of_birth
+    Utils.string_with_date_or_fail(date_of_birth)
 
-    day, month, year = date_of_birth.split('/').map { |i| i.length == 1 && ('0' << i) or i }
-    date_6_digit = day << month << year[2..3]
-    fail ArgumentError, 'The date of birth is invalid!' unless Utils.valid_date?(date_6_digit, year)
+    day, month, year = date_of_birth.split('/').map { |i| i.length == 1 ? "0#{i}" : i }
+    date_6_digit = day + month + year[2..3]
+    unless Utils.valid_date?(date_6_digit, year)
+      raise ArgumentError, 'The date of birth is invalid!'
+    end
 
     Luhn.generate(11, date_6_digit)
   end
   private_class_method :generate_with_date_of_birth
 
+  # Checks if the ID has exactly 11 digits
+  #
+  # AMKA numbers are required to be exactly 11 digits in length.
+  # This is a validation helper method.
+  #
+  # @param id [String] the ID to check
+  # @return [Boolean] true if length is 11, false otherwise
   def self.length_is_11?(id)
     id.length == 11
   end
   private_class_method :length_is_11?
-
 end
 
-require 'amka/luhn'
-require 'amka/utils'
+require_relative 'amka/luhn'
+require_relative 'amka/utils'

metadata

@@ -1,103 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: amka
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Ioannis Angelakopoulos
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2015-12-16 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest-reporters
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: mocha
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-description: 'Generates and Validates Greek A.M.K.A (social security number) and Luhn
-  IDs, using the Luhn algorithm. DISCLAIMER: It does not validate the real existence
-  of the A.M.K.A or that it belongs to a given person. The same applies to the generator.'
+date: 2025-04-16 00:00:00.000000000 Z
+dependencies: []
+description: 'Generates and Validates Greek A.M.K.A and Luhn IDs, using the Luhn algorithm.
+  DISCLAIMER: It does not validate the real existence of the A.M.K.A or that it belongs
+  to a given person. The same applies to the generator.'
 email:
 - ioagel@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".ruby-version"
-- Gemfile
+- CHANGELOG.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- amka.gemspec
-- bin/console
-- bin/setup
+- USAGE.md
 - lib/amka.rb
 - lib/amka/luhn.rb
 - lib/amka/utils.rb
@@ -105,8 +31,12 @@ files:
 homepage: https://github.com/ioagel/amka
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/ioagel/amka
+  source_code_uri: https://github.com/ioagel/amka
+  changelog_uri: https://github.com/ioagel/amka/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -114,16 +44,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.0
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: AMKA/Luhn IDs Generator and Validator
 test_files: []

data/.gitignore

@@ -1,9 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/

data/.ruby-version

@@ -1 +0,0 @@
-2.2.3@amka

data/Gemfile

@@ -1,4 +0,0 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in amka.gemspec
-gemspec

data/Rakefile

@@ -1,8 +0,0 @@
-require 'bundler/gem_tasks'
-
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.pattern = 'test/*_test.rb'
-end

data/amka.gemspec

@@ -1,28 +0,0 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'amka/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = "amka"
-  spec.version       = Amka::VERSION
-  spec.authors       = ["Ioannis Angelakopoulos"]
-  spec.email         = ["ioagel@gmail.com"]
-
-  spec.summary       = %q{AMKA/Luhn IDs Generator and Validator}
-  spec.description   = %q{Generates and Validates Greek A.M.K.A (social security number) and Luhn IDs, using the Luhn algorithm. DISCLAIMER: It does not validate the real existence of the A.M.K.A or that it belongs to a given person. The same applies to the generator.}
-  spec.homepage      = "https://github.com/ioagel/amka"
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-  spec.required_ruby_version = '>= 2.0.0'
-
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "minitest-reporters"
-  spec.add_development_dependency "mocha"
-  spec.add_development_dependency "bundler", "~> 1.10"
-  spec.add_development_dependency "rake", "~> 10.0"
-end

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "amka"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start

data/bin/setup

@@ -1,7 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-IFS=$'\n\t'
-
-bundle install
-
-# Do any other automated setup that you need to do here