head_music 8.2.1 → 9.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77530f6691ab779c127d7324218a10a854bb8fb96ccaf0244accd9dbc878f24f
-  data.tar.gz: 05b082c0029817aa3b3c6773c876000d61b7787915c0f157ad9af966da3ad73c
+  metadata.gz: 012ce64dd4174cbeec42f1d4825e9fd10af79ed8f4b83a3beedbc14a9aea34fa
+  data.tar.gz: a31dbb0b6b3d732bd41e1dbfe6a042a8395db05832d58848ec4d53e5ae4a4524
 SHA512:
-  metadata.gz: 965572974769529a7d971b0156c492195e9c7ea491d97e9445b3cc53714d802ffc0f2680559cb8449971391ef2b406f3a6283ca8ce6d8103c47713e71de954df
-  data.tar.gz: 6e5444274c959f209861c1622002351d255050e6faff66d2b69033d90c372736e15a2c74b8fb66e01841dfc5c1f29887cc753acd736d54e21e1d29608c0ee11f
+  metadata.gz: a98367425dcfb4899b24ef2e7986a7fbc594202c960b553ab35d3cecd5ee0b5ecb10f65e1e458fe2d1797b70eded378fd319b2cbfc7b9a5a2e393773ce75f06b
+  data.tar.gz: d3baf95b28de6c2df0e3d14250ed9c335cb3793d598eb7cf1c417dd40b6463bb57ddcda19be309a1045e835809ad3b9ad45dc0fd21797563319069da35db76bc

data/.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
 
     - name: Upload coverage to Codecov
       if: matrix.ruby-version == '3.3.0'
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         fail_ci_if_error: false

data/.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
       run: gem build *.gemspec
 
     - name: Create GitHub Release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
         files: '*.gem'
         generate_release_notes: true

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.0.0] - 2025-10-24
+
+### Added
+- Added `HeadMusic::Rudiment::Pitch::Parser` for strict pitch parsing
+- Added `HeadMusic::Rudiment::RhythmicValue::Parser` for rhythmic value parsing
+- Both parsers provide standardized `.parse()` class method API
+
+### Changed
+- `Pitch.from_name` now uses `Pitch::Parser` internally
+- `RhythmicValue.get` now uses `RhythmicValue::Parser` internally
+- `Note.get` now parses "pitch rhythmic_value" strings inline without Parse module
+
+### Removed
+- **BREAKING**: Removed `HeadMusic::Parse::Pitch` class
+- **BREAKING**: Removed `HeadMusic::Parse::RhythmicValue` class
+- **BREAKING**: Removed `HeadMusic::Parse::RhythmicElement` class
+- **BREAKING**: Removed entire `HeadMusic::Parse` module
+
+### Migration Guide
+
+If you were using the removed Parse classes, migrate as follows:
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::Pitch.new("C#4")
+pitch = parser.pitch
+
+# After (v9.x)
+pitch = HeadMusic::Rudiment::Pitch.get("C#4")
+# or for strict parsing:
+pitch = HeadMusic::Rudiment::Pitch::Parser.parse("C#4")
+```
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::RhythmicValue.new("dotted quarter")
+value = parser.rhythmic_value
+
+# After (v9.x)
+value = HeadMusic::Rudiment::RhythmicValue.get("dotted quarter")
+# or for strict parsing:
+value = HeadMusic::Rudiment::RhythmicValue::Parser.parse("dotted quarter")
+```
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::RhythmicElement.new("F#4 dotted-quarter")
+note = parser.note
+
+# After (v9.x)
+note = HeadMusic::Rudiment::Note.get("F#4 dotted-quarter")
+```
+
 ## [8.2.1] - 2025-06-21
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,151 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+HeadMusic is a Ruby gem for Western music theory. It provides a comprehensive toolkit for working with pitches, scales, intervals, chords, and musical analysis. The gem supports internationalization with translations in 7 languages.
+
+## Development Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests with coverage
+bundle exec rake
+
+# Run tests without coverage
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/head_music/rudiments/pitch_spec.rb
+
+# Run linting
+bundle exec rubocop
+
+# Run all quality checks (tests, linting, security)
+bundle exec rake quality
+
+# Open interactive console with gem loaded
+bin/console
+# or
+bundle exec rake console
+
+# Generate documentation
+bundle exec rake doc
+
+# Check documentation coverage
+bundle exec rake doc_stats
+```
+
+### Git Etiquette
+
+Do not make a commit unless I ask you to.
+
+When composing git commit messages, follow best-practices. However, do not mention yourself (claude) or list yourself as a co-author.
+
+This project uses a rebase flow and `main` as the mainline branch.
+
+### Code Style, Linting, and Formatting
+
+The project uses Standard Ruby for style enforcement. Always run linting after editing and before committing.
+
+```bash
+bundle exec rubocop -a
+```
+
+Always strip trailing whitespace from all lines being added or edited. Always include a blank line at the end of each file.
+
+Do not use an assignment inside a condition.
+
+### Testing
+
+Tests are written in RSpec and located in the `/spec` directory, mirroring the `/lib` structure. The project requires 90% code coverage minimum.
+
+## Architecture
+
+### Module Structure
+
+The codebase follows a domain-driven design with clear module boundaries:
+
+1. **HeadMusic::Rudiment** - Core music theory elements
+  - Pitch, Note, Scale, Key, Interval, Chord
+  - Factory methods: `.get()` for most rudiments
+
+2. **HeadMusic::Analysis** - Musical analysis tools
+  - Intervals, Chords, Motion analysis
+  - Harmonic and melodic analysis
+
+3. **HeadMusic::Content** - Musical composition representation
+  - Composition, Voice, Note, Rest
+  - Rhythmic values and time signatures
+
+4. **HeadMusic::Instruments** - Instrument definitions
+  - Instrument families and properties
+  - Pitch ranges and transposition
+
+5. **HeadMusic::Style** - Composition rules and guidelines
+  - Counterpoint rules
+  - Voice leading guidelines
+  - Style analysis
+
+### Key Design Patterns
+
+- **Factory Pattern**: Most musical objects use `.get()` factory methods
+- **Value Objects**: Immutable objects for musical concepts
+- **Named Mixin**: Provides internationalization support
+- **Delegation**: Extensive use of delegation for clean APIs
+
+### Entry Points
+
+- Main file: `lib/head_music.rb`
+- Module loading order is important and defined in the main file
+- Constants like GOLDEN_RATIO are defined at the top level
+
+## Important Implementation Details
+
+### Internationalization
+
+The gem supports multiple languages through the HeadMusic::Named mixin:
+- Translations in `lib/head_music/locales/`
+- Languages: en, de, es, fr, it, ja, nl
+- Use `I18n.locale = :de` to change language
+
+### Testing Patterns
+
+- Use `described_class` instead of hardcoding class names
+- Test files must end with `_spec.rb`
+- Shared examples in `spec/support/`
+- `composition_context.rb` provides test utilities
+
+### Code Style
+
+- Ruby 3.3.0+ features are allowed
+- Follow Standard Ruby style guide
+- Use YARD documentation format for public methods
+- Prefer delegation over inheritance
+- Always run `bundle exec rubocop -a` after editing ruby code
+
+## Common Development Tasks
+
+### Adding a New Musical Concept
+
+1. Create the class in the appropriate module
+2. Include `HeadMusic::Named` if it needs internationalization
+3. Add factory method `.get()` if appropriate
+4. Create corresponding spec file
+5. Add translations to locale files if using Named
+
+### Modifying Existing Classes
+
+1. Check for dependent classes that might be affected
+2. Run tests for the specific module: `bundle exec rspec spec/head_music/[module_name]`
+3. Update documentation with YARD comments
+4. Ensure translations are updated if names change
+
+## Music theory and concepts
+
+Please refer to MUSIC_THEORY.md for music theory domain knowledge.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (8.2.0)
+    head_music (9.0.0)
       activesupport (~> 7.0)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -22,54 +22,54 @@ GEM
       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)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.2)
     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)
+    diff-lcs (1.6.2)
     docile (1.4.1)
-    drb (2.2.1)
+    drb (2.2.3)
     humanize (2.5.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    json (2.11.3)
+    json (2.13.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
-    language_server-protocol (3.17.0.4)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.25.5)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
     prism (1.4.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
+    rake (13.3.0)
     regexp_parser (2.10.0)
     rexml (3.4.1)
-    rspec (3.13.0)
+    rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.3)
+    rspec-core (3.13.5)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.4)
+    rspec-expectations (3.13.5)
       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)
+    rspec-its (2.0.0)
+      rspec-core (>= 3.13.0)
+      rspec-expectations (>= 3.13.0)
+    rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.3)
-    rubocop (1.75.4)
+    rspec-support (3.13.4)
+    rubocop (1.75.8)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -80,7 +80,7 @@ GEM
       rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.46.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
@@ -99,12 +99,12 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    standard (1.49.0)
+    standard (1.50.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.2)
+      rubocop (~> 1.75.5)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -113,7 +113,7 @@ GEM
     standard-performance (1.8.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.25.0)
-    thor (1.3.2)
+    thor (1.4.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.1.4)
@@ -132,7 +132,7 @@ DEPENDENCIES
   kramdown
   rake (~> 13.0)
   rspec (~> 3.0)
-  rspec-its (~> 1.2)
+  rspec-its (~> 2.0)
   rubocop
   rubocop-rake
   rubocop-rspec

data/MUSIC_THEORY.md

@@ -0,0 +1,120 @@
+# Music Theory
+Domain-specific knowledge for this project.
+
+## Rudiments
+
+The rudiments of music theory are built up piece-by-piece.
+
+letter name
+  - C, D, E, F, G, A, B, …
+  - equivalent to:
+   - do, re, mi, fa, sol, la, si/ti, …
+
+alteration
+  - sharp, flat, double sharp, double flat
+  - optional
+  - none is same as 'natural'
+  - found in key signatures
+  - found in bars as accidentals
+
+spelling
+  - letter name + alteration
+  - example: "E♭"
+
+register
+  - an integer typically between 0 and 8
+  - represents the octaves of an 88-key piano
+  - scientific pitch notation
+    - middle C is C4
+    - increments between B and C
+      - a half step below C4 is B3.
+
+pitch
+  - spelling + register
+  - example: "E♭3"
+
+rhythmic unit
+  - duration
+  - expressed in fractions (or multiples) of a standard whole note
+    - whole, half, quarter, eighth, sixteenth, …
+    - breve, …
+
+rhythmic value (duration)
+  - a rhythmic unit plus optional augmentation dots
+  - augmentation dots extend the duration of the rhythmic unit
+    - one dot extends the rhythmic value 50%
+    - two dots extend the rhythmic value 75%
+    - two dots extend the rhythmic value 87.5%
+
+rest
+  - a rhythmic value that passes in silence
+
+note
+  - pitch + rhythmic value
+  - example: "E♭3 dotted quarter"
+
+unpitched note
+  - an unpitched percussion note, such as a drum hit
+  - a sounded rhythmic value without a specific pitch
+
+tied duration
+  - combines multiple rhythmic values into one longer note
+  - ties allow rhythmic values to be combined across barlines or strong beats
+
+articulation
+  - a category of expressions that modify how one or more notes are performed.
+  - level of connection
+    - staccatissimo - the most staccato, even shorted and more clipped
+    - staccato – detatched (shortened to lease space between adjacent notes)
+    - tenuto - held of the full value
+    - legato - smoothly connected
+  - emphasis
+    - accent - play with emphasis or a stronger attack
+    - marcato - markedly emphasized
+  - instrument specific
+    - bowings
+    - breath mark
+    - roll mark
+
+## Instrument Families
+
+There are several ways that people talk about families and other categorizations of instruments. For example, the "string family" or "woodwind family", but also more specifically, the word family is applied more specifically (e.g. the "oboe family").
+
+### Text Conversation with Brian Head (May 7, 2023)
+
+Brian Head, brother and faculty at USC Thornton School of Music
+https://music.usc.edu/brian-head/
+
+Robert Head:
+	Hey, Brian. You have a sec for a music question? I’m trying to come up with different terms for the way “family” is used. “Woodwind family” vs. “Oboe family”.
+
+Brian Head:
+	Those are good, I’d say.  In what context?
+
+Robert Head:
+	In my software project, I’m trying to define those relationships. One is a section of the orchestra and the other is species of instrument. But usually people, in my experience, just say “family”.
+	Is there some more precise terminology or adjective that can disambiguate those two terms?
+
+Brian Head:
+	Hmmm. Already “family” is informal. Blatter distinguishes between “choir” and “family” as in the  trumpet family” within the “brass choir”.
+
+Robert Head:
+	Ah, yes! I do like that.
+	But does it apply to percussion?
+	“Section” is another candidate, but that gets used for string parts as well.
+
+Brian Head:
+	Strings and percussion probably don’t think of themselves as a choir, but if you’re mainly looking for a taxonomically consistent word, that’s the feat I can think of at the moment.
+	Section is a good word, too, which easily flows between smaller and larger meanings.
+
+Robert Head:
+	Obviously, the four “families” is a garbage way to classify all instruments and it really is more applicable to the orchestral context, so maybe “orchestra family” or “orchestra section”.
+
+Brian Head:
+	I’d say that “family” is best used at the instrument level, as in “saxophone family”. Choir or section are better for larger collections. Still, both of those words connote membership in an orchestra. Or large ensemble.  “Woodwinds” or “percussion” describe the class of instruments themselves.
+
+Robert Head:
+	Cool
+
+Action Item: Call them orchestra_section
+DONE

data/Rakefile

@@ -12,7 +12,7 @@ begin
   end
 
   desc "Generate documentation and show stats"
-  task :doc_stats => :doc do
+  task doc_stats: :doc do
     sh "yard stats --list-undoc"
   end
 rescue LoadError
@@ -29,7 +29,7 @@ end
 task default: :spec
 
 desc "Run all quality checks (tests, linting, security audit)"
-task :quality => [:spec, :standard, "bundle:audit:check"]
+task quality: [:spec, :standard, "bundle:audit:check"]
 
 desc "Open an irb session preloaded with this library"
 task :console do

data/bin/check_instrument_consistency.rb

@@ -0,0 +1,86 @@
+require "yaml"
+
+# Load the YAML files
+instruments_file = "/Users/roberthead/github.com/roberthead/head_music/lib/head_music/instruments/instruments.yml"
+families_file = "/Users/roberthead/github.com/roberthead/head_music/lib/head_music/instruments/instrument_families.yml"
+
+instruments = YAML.load_file(instruments_file)
+families = YAML.load_file(families_file)
+
+puts "Checking for inconsistencies between instruments and their families...\n\n"
+
+inconsistencies = []
+
+instruments.each do |instrument_name, instrument_data|
+  family_key = instrument_data["family_key"]
+  next unless family_key
+
+  family_data = families[family_key]
+  next unless family_data
+
+  # Check orchestra_section_key consistency
+  instrument_section = instrument_data["orchestra_section_key"]
+  family_section = family_data["orchestra_section_key"]
+
+  if instrument_section && family_section && instrument_section != family_section
+    inconsistencies << {
+      instrument: instrument_name,
+      family: family_key,
+      field: "orchestra_section_key",
+      instrument_value: instrument_section,
+      family_value: family_section
+    }
+  end
+
+  # Check classification_keys consistency
+  instrument_classifications = instrument_data["classification_keys"] || []
+  family_classifications = family_data["classification_keys"] || []
+
+  # Check if instrument has classifications that conflict with family
+  if !instrument_classifications.empty? && !family_classifications.empty?
+    conflicts = instrument_classifications - family_classifications
+    if !conflicts.empty?
+      inconsistencies << {
+        instrument: instrument_name,
+        family: family_key,
+        field: "classification_keys",
+        instrument_value: instrument_classifications,
+        family_value: family_classifications,
+        conflicts: conflicts
+      }
+    end
+  end
+end
+
+if inconsistencies.empty?
+  puts "No inconsistencies found!"
+else
+  puts "Found #{inconsistencies.length} inconsistencies:\n\n"
+
+  inconsistencies.each_with_index do |issue, index|
+    puts "#{index + 1}. #{issue[:instrument]} (family: #{issue[:family]})"
+    puts "   Field: #{issue[:field]}"
+    puts "   Instrument value: #{issue[:instrument_value]}"
+    puts "   Family value: #{issue[:family_value]}"
+    if issue[:conflicts]
+      puts "   Conflicting classifications: #{issue[:conflicts]}"
+    end
+    puts ""
+  end
+end
+
+# Also check for instruments with orchestra_section_key but no family
+puts "\nInstruments with orchestra_section_key but no family_key:"
+instruments.each do |instrument_name, instrument_data|
+  if instrument_data["orchestra_section_key"] && !instrument_data["family_key"]
+    puts "- #{instrument_name}: #{instrument_data["orchestra_section_key"]}"
+  end
+end
+
+# Check for instruments with classification_keys but no family
+puts "\nInstruments with classification_keys but no family_key:"
+instruments.each do |instrument_name, instrument_data|
+  if instrument_data["classification_keys"] && !instrument_data["family_key"]
+    puts "- #{instrument_name}: #{instrument_data["classification_keys"]}"
+  end
+end

data/head_music.gemspec

@@ -38,7 +38,7 @@ 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 "rspec-its", "~> 2.0"
   spec.add_development_dependency "bundler-audit", "~> 0.9"
   spec.add_development_dependency "yard", "~> 0.9"
 end

data/lib/head_music/analysis/diatonic_interval/naming.rb

@@ -1,4 +1,4 @@
-# Accepts a number and number of semitones and privides the naming methods.
+# Accepts a number and number of semitones and provides the naming methods.
 class HeadMusic::Analysis::DiatonicInterval::Naming
   QUALITY_SEMITONES = HeadMusic::Analysis::DiatonicInterval::QUALITY_SEMITONES
   NUMBER_NAMES = HeadMusic::Analysis::DiatonicInterval::NUMBER_NAMES