head_music 8.1.1 → 8.2.1

data/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to HeadMusic
+
+Thank you for considering contributing to HeadMusic!
+
+Following these guidelines helps to communicate that you respect the team managing and developing this open source project. In return, we should reciprocate that respect in addressing your issue, assessing changes, and facilitating your pull requests.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [robert.head@gmail.com](mailto:robert.head@gmail.com).
+
+## What we are looking for
+
+HeadMusic is an open source project and we love to receive contributions from our community. There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into HeadMusic itself.
+
+## How to contribute
+
+### Reporting Bugs
+
+Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out [the required template](.github/ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster.
+
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+### Suggesting Enhancements
+
+Before creating enhancement suggestions, please check the existing issues as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in [the template](.github/ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
+
+### Pull Requests
+
+The process described here has several goals:
+
+- Maintain HeadMusic's quality
+- Fix problems that are important to users
+- Engage the community in working toward the best possible HeadMusic
+- Enable a sustainable system for HeadMusic's maintainers to review contributions
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes (`bundle exec rspec`).
+5. Make sure your code lints (`bundle exec rubocop`).
+6. Follow the [pull request template](.github/pull_request_template.md) when creating your PR.
+
+## Development Process
+
+Here's how to get started with development:
+
+1. Fork and clone the repository
+2. Run `bin/setup` to install dependencies
+3. Run `bundle exec rspec` to run the tests
+4. Run `bundle exec rubocop` to check code style
+5. Create a new branch for your feature or bug fix
+6. Make your changes and add tests
+7. Run the tests and linter to ensure everything passes
+8. Commit your changes with a clear commit message
+9. Push to your fork and submit a pull request
+
+### Setting up your development environment
+
+```bash
+git clone https://github.com/your-username/head_music.git
+cd head_music
+bin/setup
+```
+
+### Running tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/head_music/rudiment/pitch_spec.rb
+
+# Run tests matching a pattern
+bundle exec rspec -e "Pitch"
+```
+
+### Code style
+
+We use RuboCop with the Standard Ruby style guide. Before submitting a PR, please run:
+
+```bash
+bundle exec rubocop
+```
+
+To automatically fix many issues:
+
+```bash
+bundle exec rubocop --autocorrect
+```
+
+## Styleguides
+
+### 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 liberally after the first line
+- Consider starting the commit message with an applicable emoji:
+    - 🎨 `:art:` when improving the format/structure of the code
+    - 🐎 `:racehorse:` when improving performance
+    - 📝 `:memo:` when writing docs
+    - 🐛 `:bug:` when fixing a bug
+    - 🔥 `:fire:` when removing code or files
+    - ✅ `:white_check_mark:` when adding tests
+    - 🔒 `:lock:` when dealing with security
+    - ⬆️ `:arrow_up:` when upgrading dependencies
+    - ⬇️ `:arrow_down:` when downgrading dependencies
+
+### Ruby Styleguide
+
+All Ruby code must adhere to [Standard Ruby](https://github.com/testdouble/standard).
+
+### Documentation Styleguide
+
+- Use [YARD](https://yardoc.org/) for API documentation.
+- Include examples in your documentation when possible.
+
+## Community
+
+- Join our discussions in [GitHub Discussions](https://github.com/roberthead/head_music/discussions)
+- Ask questions in the [Issues](https://github.com/roberthead/head_music/issues)
+
+## Recognition
+
+Contributors who submit a pull request that gets merged will be added to our [Contributors list](https://github.com/roberthead/head_music/graphs/contributors).
+
+## Questions?
+
+Feel free to contact the project maintainer at [robert.head@gmail.com](mailto:robert.head@gmail.com) if you have any questions or concerns.
+
+Thank you for contributing to HeadMusic! 🎵

data/Gemfile

@@ -8,9 +8,14 @@ gemspec
 gem "standard", require: false
 
 group :test do
-  gem "codeclimate-test-reporter", "~> 1.0.0"
   gem "rubocop", require: false
   gem "rubocop-rspec", require: false
   gem "rubocop-rake", require: false
-  gem "simplecov"
+  gem "simplecov", require: false
+end
+
+group :development do
+  gem "bundler-audit", require: false
+  gem "yard", require: false
+  gem "kramdown", require: false
 end

data/Gemfile.lock

@@ -0,0 +1,147 @@
+PATH
+  remote: .
+  specs:
+    head_music (8.2.0)
+      activesupport (~> 7.0)
+      humanize (~> 2.0)
+      i18n (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.2.2.1)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+    ast (2.4.3)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    bundler-audit (0.9.2)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    diff-lcs (1.6.1)
+    docile (1.4.1)
+    drb (2.2.1)
+    humanize (2.5.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.11.3)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-its (1.3.1)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.3)
+    rubocop (1.75.4)
+      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.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.6.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    standard (1.49.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.2)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    thor (1.3.2)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    yard (0.9.37)
+
+PLATFORMS
+  arm64-darwin-22
+  arm64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  bundler-audit
+  head_music!
+  kramdown
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rspec-its (~> 1.2)
+  rubocop
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  standard
+  yard
+
+RUBY VERSION
+   ruby 3.3.0p0
+
+BUNDLED WITH
+   2.4.12

data/README.md

@@ -1,10 +1,19 @@
 # HeadMusic
 
-![Build status](https://circleci.com/gh/roberthead/head_music.svg?style=shield&circle-token=8b39a6f5e809e9baa321e0f13aa06c70c6511794)
-[![Code Climate](https://codeclimate.com/github/roberthead/head_music/badges/gpa.svg)](https://codeclimate.com/github/roberthead/head_music)
-[![Test Coverage](https://codeclimate.com/github/roberthead/head_music/badges/coverage.svg)](https://codeclimate.com/github/roberthead/head_music/coverage)
+[![CI](https://github.com/roberthead/head_music/workflows/CI/badge.svg)](https://github.com/roberthead/head_music/actions)
+[![Security](https://github.com/roberthead/head_music/workflows/Security/badge.svg)](https://github.com/roberthead/head_music/actions)
+[![Gem Version](https://badge.fury.io/rb/head_music.svg)](https://badge.fury.io/rb/head_music)
+[![Documentation](https://img.shields.io/badge/docs-yard-blue.svg)](https://rubydoc.info/gems/head_music)
 
-The *head_music* ruby gem models the elements of western music theory, such as note names, scales, key signatures, intervals, and chords.
+The **head_music** Ruby gem provides a toolkit for working with Western music theory. Model and manipulate the fundamental elements of music including pitches, scales, key signatures, intervals, and chords.
+
+## Features
+
+- **Western Music Theory Fundamentals**: Work with pitches, scales, intervals, chords, and key signatures
+- **Musical Analysis**: Analyze harmonic progressions, voice leading, and counterpoint
+- **Style Analysis**: Rules for species counterpoint and voice leading
+- **Internationalization**: Support for multiple languages (English, French, German, Italian, Russian, Spanish)
+- **Instrument Modeling**: Extensive database of musical instruments with ranges and properties
 
 ## Installation
 
@@ -16,27 +25,107 @@ gem 'head_music'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
     $ gem install head_music
 
-## Usage
+## Quick Start
+
+```ruby
+require 'head_music'
+
+# Work with pitches and intervals
+pitch = HeadMusic::Rudiment::Pitch.get('C4')
+higher_pitch = HeadMusic::Rudiment::Pitch.get('E4')
+interval = HeadMusic::Analysis::DiatonicInterval.new(pitch, higher_pitch)
+puts interval.name  # => "major third"
+
+# Create scales
+scale = HeadMusic::Rudiment::Scale.get('C', :major)
+puts scale.pitches.map(&:to_s)  # => ["C4", "D4", "E4", "F4", "G4", "A4", "B4"]
+
+# Analyze chords
+pitches = %w[C4 E4 G4].map { |p| HeadMusic::Rudiment::Pitch.get(p) }
+chord = HeadMusic::Analysis::PitchSet.new(pitches)
+puts chord.major_triad?  # => true
+```
+
+## Documentation
+
+- **API Documentation**: [rubydoc.info/gems/head_music](https://rubydoc.info/gems/head_music)
+- **Contributing Guide**: [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
-HeadMusic can be used as a foundation to build larger applications that notate, analyze, play, or generate music in the language of music theory.
+## Requirements
+
+- Ruby 3.3.0 or higher
+- ActiveSupport 7.0+
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests with coverage
+bundle exec rake
+
+# Run quality checks (tests + linting + security)
+bundle exec rake quality
+```
+
+### Code Quality
+
+```bash
+# Run linting
+bundle exec rubocop
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Run security audit
+bundle exec rake bundle:audit:check
+
+# Generate documentation
+bundle exec rake doc
+```
+
+### Available Rake Tasks
+
+- `rake spec` - Run tests
+- `rake quality` - Run tests, linting, and security audit
+- `rake doc` - Generate YARD documentation
+- `rake doc_stats` - Show documentation coverage statistics
+- `rake coverage` - Open coverage report in browser
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/head_music. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
+## Project Structure
+
+```
+lib/head_music/
+├── analysis/          # Musical analysis tools (intervals, chords, etc.)
+├── content/           # Musical content (compositions, voices, notes)
+├── instruments/       # Instrument definitions and properties
+├── rudiment/          # Basic music theory elements (pitches, scales, etc.)
+└── style/             # Style analysis and composition rules
+```
+
+## Code of Conduct
+
+This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## 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](LICENSE.txt).
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/roberthead/head_music/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/roberthead/head_music/discussions)
+- **Security**: For security issues, please email [robert.head@gmail.com](mailto:robert.head@gmail.com)

data/Rakefile

@@ -4,9 +4,39 @@ require "standard/rake"
 
 RSpec::Core::RakeTask.new(:spec)
 
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = %w[--protected --private]
+  end
+
+  desc "Generate documentation and show stats"
+  task :doc_stats => :doc do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  # YARD not available
+end
+
+begin
+  require "bundler/audit/task"
+  Bundler::Audit::Task.new
+rescue LoadError
+  # bundler-audit not available
+end
+
 task default: :spec
 
+desc "Run all quality checks (tests, linting, security audit)"
+task :quality => [:spec, :standard, "bundle:audit:check"]
+
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -I lib -r head_music.rb"
 end
+
+desc "Open coverage report in browser"
+task :coverage do
+  sh "open coverage/index.html" if File.exist?("coverage/index.html")
+end

data/head_music.gemspec

@@ -8,11 +8,20 @@ Gem::Specification.new do |spec|
   spec.authors = ["Rob Head"]
   spec.email = ["robert.head@gmail.com"]
 
-  spec.summary = "The rudiments of western music theory."
+  spec.summary = "The rudiments of western music theory and analysis."
   spec.description = "Work with the elements of western music theory, such as pitches, scales, intervals, and chords."
   spec.homepage = "https://github.com/roberthead/head_music"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/roberthead/head_music",
+    "changelog_uri" => "https://github.com/roberthead/head_music/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://rubydoc.info/gems/head_music",
+    "bug_tracker_uri" => "https://github.com/roberthead/head_music/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/}) || f.match(/\.gem$/)
   end
@@ -21,7 +30,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 3.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.add_runtime_dependency "activesupport", "~> 7.0"
   spec.add_runtime_dependency "humanize", "~> 2.0"
@@ -30,4 +39,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-its", "~> 1.2"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "yard", "~> 0.9"
 end

data/lib/head_music/analysis/diatonic_interval.rb

@@ -73,7 +73,7 @@ class HeadMusic::Analysis::DiatonicInterval
   end
 
   def spans?(pitch)
-    pitch >= lower_pitch && pitch <= higher_pitch
+    pitch.between?(lower_pitch, higher_pitch)
   end
 
   def quality

data/lib/head_music/analysis/sonority.rb

@@ -110,7 +110,7 @@ class HeadMusic::Analysis::Sonority
   alias_method :quintal?, :quartal?
 
   def diatonic_intervals_above_bass_pitch
-    return nil unless identifier
+    return [] unless identifier
 
     @diatonic_intervals_above_bass_pitch ||=
       SONORITIES[identifier].map { |shorthand| HeadMusic::Analysis::DiatonicInterval.get(shorthand) }

data/lib/head_music/content/staff.rb

@@ -8,12 +8,22 @@ class HeadMusic::Content::Staff
   attr_reader :default_clef, :line_count, :instrument
 
   def initialize(default_clef_key, instrument: nil, line_count: nil)
-    @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
-    @line_count = line_count || DEFAULT_LINE_COUNT
     @instrument = HeadMusic::Instruments::Instrument.get(instrument) if instrument
+    begin
+      @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
+    rescue KeyError, NoMethodError
+      puts("Warning: Clef '#{default_clef_key}' not found.")
+      if @instrument
+        puts("Using instrument clef.")
+        @default_clef = @instrument.default_staves.first.clef
+      else
+        @default_clef = HeadMusic::Rudiment::Clef.get(:treble_clef)
+      end
+    end
+    @line_count = line_count || DEFAULT_LINE_COUNT
   end
 
   def clef
-    default_clef || instrument&.default_staves&.first&.clef
+    default_clef
   end
 end

data/lib/head_music/content/voice.rb

@@ -110,6 +110,14 @@ class HeadMusic::Content::Voice
     placements.last.position.bar_number
   end
 
+  def last_placement
+    placements.last
+  end
+
+  def next_position
+    last_placement ? last_placement.next_position : HeadMusic::Content::Position.new(composition, 1, 1, 0)
+  end
+
   def to_s
     return pitches_string if role.to_s.strip == ""
 

data/lib/head_music/instruments/instrument.rb

@@ -82,9 +82,7 @@ class HeadMusic::Instruments::Instrument
     variants.find(&:default?) || variants.first
   end
 
-  def default_staff_scheme
-    default_variant&.default_staff_scheme
-  end
+  delegate :default_staff_scheme, to: :default_variant
 
   def default_staves
     default_staff_scheme&.staves || []