head_music 8.3.0 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec01f26a90e391dbe250ca2587586ceb9bc062a8eba06d97f52767eaf08bb2f0
-  data.tar.gz: b2253758a487b28f9e02ae6479da2586da39ff45337bca0a24f9634988ff9eb4
+  metadata.gz: c3abf9e12840eb88aee1cb454116cbd092f224eb1961cfda5567444ad9e91d2f
+  data.tar.gz: e7680154e971414788fc8bd1a87f53111bc82c9452f4df5a8ad47a74b1c5c16d
 SHA512:
-  metadata.gz: 6633eb9a47b72f81a44225d475d60b67924136809d469ba2a45ffe39ea6c1356ffbecd79e64f931c15146dd00980a9ff220c2b5c95deb955e5b3cf0eec7fef67
-  data.tar.gz: 5628ee5c9f0a442560f502d071f155e0d93771b3081572e9a98a86a154f387b0c9431662b051fd58bb9189b71906b5e7c9c29dbeddebd278f1d4a23d97416634
+  metadata.gz: 199c8cdba49e5d6e15e7047a8bb8ee28eaa5c8087c9f427916d087d4ce8986f04cf7dd354666247b389836256230d5c3535ff5fd79964443626e397c0cdb3288
+  data.tar.gz: d793d6730a790b088fcc7906bc6cb02b865364852767534c15c1b76b40622ae6a12b23a2bde5f651687e9ce124941501ae8d1f17f9a63a7c8c473a2112914024

data/.github/workflows/ci.yml

@@ -12,7 +12,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.3.0', '3.3', '3.4']
+        ruby-version: ['3.3', '3.4']
+        activesupport-version: ['7.2', '8.0']
 
     steps:
     - uses: actions/checkout@v4
@@ -21,13 +22,18 @@ jobs:
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems
+        bundler-cache: false
+
+    - name: Install dependencies with ActiveSupport ${{ matrix.activesupport-version }}
+      run: |
+        bundle config set --local path vendor/bundle
+        ACTIVESUPPORT_VERSION="${{ matrix.activesupport-version }}" bundle install
 
     - name: Run tests
       run: bundle exec rspec
 
     - name: Upload coverage to Codecov
-      if: matrix.ruby-version == '3.3.0'
+      if: matrix.ruby-version == '3.3' && matrix.activesupport-version == '8.0'
       uses: codecov/codecov-action@v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}

data/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [11.0.0] - 2026-01-05
+
+### Changed
+- **BREAKING**: Widened ActiveSupport dependency from `~> 7.0` to `>= 7.0, < 10` to support Rails 8.x
+- Improved I18n initialization to be non-destructive:
+  - No longer overwrites `I18n.default_locale` (allows Rails apps to control their default)
+  - Adds HeadMusic locales to `available_locales` instead of replacing them
+  - Only sets fallbacks if not already configured by the application
+- Updated CI workflow to test against both ActiveSupport 7.x and 8.x
+
+### Fixed
+- Fixed compatibility issue with Rails 8.1.x applications
+
+## [10.0.0] - 2025-12-01
+
+### Changed
+- Internal release for testing
+
+## [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

@@ -41,14 +41,26 @@ bundle exec rake doc
 bundle exec rake doc_stats
 ```
 
-### Linting and Formatting
+### Git Etiquette
 
-The project uses Standard Ruby for style enforcement. Always run linting before committing:
+**IMPORTANT: Do not make a commit unless I explicitly ask you to.** Wait for explicit instruction before running `git commit`.
+
+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
+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.
@@ -60,25 +72,38 @@ Tests are written in RSpec and located in the `/spec` directory, mirroring the `
 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
+  - Abstract concepts: pitch, interval, scale, chord, key
+  - Duration concepts (without visual representation)
+  - Factory methods: `.get()` for most rudiments
+
+2. **HeadMusic::Notation** - Visual music notation and representation
+  - Staff positions, lines, spaces, ledger lines
+  - Musical symbols (ASCII, Unicode, HTML entities)
+  - Clef placement and rendering
+  - Notehead shapes, stems, flags, beams
+  - Accidental placement rules
+  - Future: ties, slurs, articulations, dynamics
+
+3. **HeadMusic::Instruments** - Instrument definitions
+  - Instrument families and classification
+  - Pitch ranges and transposition
+  - Playing techniques
+  - Score ordering
+
+4. **HeadMusic::Content** - Musical composition representation
+  - Compositions, voices, bars, positions
+  - Notes in context (pitch + duration + placement)
+  - Temporal organization
+
+5. **HeadMusic::Analysis** - Musical analysis tools
+  - Intervals, chords, motion analysis
+  - Harmonic and melodic analysis
+  - Pitch class sets and collections
+
+6. **HeadMusic::Style** - Composition rules and guidelines
+  - Counterpoint rules
+  - Voice leading guidelines
+  - Style analysis
 
 ### Key Design Patterns
 
@@ -109,12 +134,21 @@ The gem supports multiple languages through the HeadMusic::Named mixin:
 - Shared examples in `spec/support/`
 - `composition_context.rb` provides test utilities
 
+### Documentation Philosophy
+
+This project deliberately deprioritizes formal documentation in favor of clear, comprehensive tests.
+
+- **Tests serve as documentation**: RSpec specs demonstrate how to use the code
+- **Comments explain "why", not "what"**: Only add comments when the implementation is surprising or non-obvious
+- **No YARD documentation required**: The code should be self-explanatory through clear naming and test examples
+- Documentation tools like `rake doc` and `rake doc_stats` exist but low coverage is intentional
+
 ### 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
 
@@ -130,5 +164,8 @@ The gem supports multiple languages through the HeadMusic::Named mixin:
 
 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
+3. Ensure translations are updated if names change
+
+## Music theory and concepts
+
+Please refer to MUSIC_THEORY.md for music theory domain knowledge.

data/Gemfile

@@ -1,10 +1,15 @@
 source "https://rubygems.org"
 
-ruby "3.3.0"
+ruby ">= 3.3.0"
 
 # Specify your gem's dependencies in head_music.gemspec
 gemspec
 
+# Allow CI to test against specific ActiveSupport versions
+if ENV["ACTIVESUPPORT_VERSION"]
+  gem "activesupport", "~> #{ENV["ACTIVESUPPORT_VERSION"]}.0"
+end
+
 gem "standard", require: false
 
 group :test do
@@ -16,6 +21,7 @@ end
 
 group :development do
   gem "bundler-audit", require: false
+  gem "rubycritic", require: false
   gem "yard", require: false
   gem "kramdown", require: false
 end

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    head_music (8.3.0)
-      activesupport (~> 7.0)
+    head_music (11.0.0)
+      activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
 
@@ -21,25 +21,81 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
     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)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.6.2)
     docile (1.4.1)
     drb (2.2.3)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    erubi (1.13.1)
+    flay (2.13.3)
+      erubi (~> 1.10)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.0)
+      sexp_processor (~> 4.0)
+    flog (4.8.0)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.1, > 3.1.0)
+      sexp_processor (~> 4.8)
     humanize (2.5.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
+    ice_nine (0.11.2)
     json (2.13.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     language_server-protocol (3.17.0.5)
+    launchy (3.1.1)
+      addressable (~> 2.8)
+      childprocess (~> 5.0)
+      logger (~> 1.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.25.5)
@@ -47,12 +103,20 @@ GEM
     parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
+    path_expander (1.1.3)
     prism (1.4.0)
+    public_suffix (6.0.2)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
     regexp_parser (2.10.0)
-    rexml (3.4.1)
+    rexml (3.4.4)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -94,7 +158,23 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
+    ruby_parser (3.21.1)
+      racc (~> 1.5)
+      sexp_processor (~> 4.16)
+    rubycritic (4.11.0)
+      flay (~> 2.13)
+      flog (~> 4.7)
+      launchy (>= 2.5.2)
+      parser (>= 3.3.0.5)
+      rainbow (~> 3.1.1)
+      reek (~> 6.5.0, < 7.0)
+      rexml
+      ruby_parser (~> 3.21)
+      simplecov (>= 0.22.0)
+      tty-which (~> 0.5.0)
+      virtus (~> 2.0)
     securerandom (0.4.1)
+    sexp_processor (4.17.4)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -114,12 +194,19 @@ GEM
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.25.0)
     thor (1.4.0)
+    thread_safe (0.3.6)
+    tty-which (0.5.0)
     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)
+    virtus (2.0.0)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
     yard (0.9.37)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-22
@@ -136,6 +223,7 @@ DEPENDENCIES
   rubocop
   rubocop-rake
   rubocop-rspec
+  rubycritic
   simplecov
   standard
   yard

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/README.md

@@ -101,6 +101,24 @@ bundle exec rake doc
 - `rake doc_stats` - Show documentation coverage statistics
 - `rake coverage` - Open coverage report in browser
 
+### Releasing a New Version
+
+1. Update the version number in `lib/head_music/version.rb`
+2. Commit the version change: `git commit -am "Bump version to X.Y.Z"`
+3. Push to main: `git push origin main`
+4. Release the gem:
+
+```bash
+bundle exec rake release
+```
+
+This will:
+- Build the gem
+- Create and push a git tag (e.g., `vX.Y.Z`)
+- Push the gem to RubyGems
+
+The git tag push also triggers a GitHub Actions workflow that creates a GitHub Release with auto-generated release notes.
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

data/Rakefile

@@ -26,10 +26,15 @@ rescue LoadError
   # bundler-audit not available
 end
 
+desc "Run RubyCritic code quality analysis"
+task :rubycritic do
+  sh "rubycritic lib"
+end
+
 task default: :spec
 
-desc "Run all quality checks (tests, linting, security audit)"
-task quality: [:spec, :standard, "bundle:audit:check"]
+desc "Run all quality checks (tests, linting, security audit, code quality)"
+task quality: [:spec, :standard, "bundle:audit:check", :rubycritic]
 
 desc "Open an irb session preloaded with this library"
 task :console do

data/head_music.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.3.0"
 
-  spec.add_runtime_dependency "activesupport", "~> 7.0"
+  spec.add_runtime_dependency "activesupport", ">= 7.0", "< 10"
   spec.add_runtime_dependency "humanize", "~> 2.0"
   spec.add_runtime_dependency "i18n", "~> 1.8"