head_music 18.0.0 → 19.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a16868734e2fac408461d2202fcbc84be2a796a68371a81a7d2ad5bbeef516b
-  data.tar.gz: 02becc93275629796177a72894d81cc10feca0819847496e60aa3ddc6f5aac00
+  metadata.gz: 7462797fd33041d3ab9fea4cf10cfaf329213d6f96d3f3b9cbb4f6a73dfd2890
+  data.tar.gz: 01c4cff6e9f609ce9543be019c340b3c7a01c21928e7248345d5a50364d85705
 SHA512:
-  metadata.gz: e3533678a1a2b58558080cad6c03f04fe4b5b205d4413456b728c5ae2e1a598e3a09ebc0329c9f6fde263e84f857eb4571918087afe23a083278facaea7aa460
-  data.tar.gz: 3d605bff3a0459e56cddd4911e7699d2b295bf337e7f468094d0f4cc19e55f9b3036c21e59c95263f3bf19c69dfffa99093a8564f036aa625b776199e959e8f4
+  metadata.gz: c14082d1dc7e8405227b46be83e803b3037808c817200e8cadf18ead15dda70f17248d92a2c370d52f92eb9ea4241aa7dad07869e016979edc301c9d30f077aa
+  data.tar.gz: '06868ca14c8cca41f22c395cb04d84a6291492471cf034a9efd69afc4a822951cd2fc9ad4d2c7b4a94ed7d68b8bd70a8003090092b96291733ad1378f48c3d19'

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         activesupport-version: ['7.2', '8.0']
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
@@ -34,7 +34,7 @@ jobs:
 
     - name: Upload coverage to Codecov
       if: matrix.ruby-version == '3.3' && matrix.activesupport-version == '8.0'
-      uses: codecov/codecov-action@v5
+      uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         fail_ci_if_error: false
@@ -43,7 +43,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -57,7 +57,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
       id-token: write
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -31,7 +31,7 @@ jobs:
       run: gem build *.gemspec
 
     - name: Create GitHub Release
-      uses: softprops/action-gh-release@v2
+      uses: softprops/action-gh-release@v3
       with:
         files: '*.gem'
         generate_release_notes: true

data/.github/workflows/security.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `HeadMusic::Style::Guide` — a lookup facade over every style guide in the gem. `Guide.get("first_species_harmony")` resolves a key to a guide; an unknown key returns `nil` rather than raising, so a consumer can ask about a guide the gem does not have. `Guide.get!` raises `KeyError` instead, and `Guide.known?`, `.all`, `.keys`, and `.key_for` round out the surface. Keys are stable strings suitable for storing in a database. The registry holds twenty-three:
+
+  | Category | Keys |
+  | --- | --- |
+  | `:melody` | `fux_cantus_firmus`, `salzer_schachter_cantus_firmus`, `diatonic_melody`, `first_species_melody`, `second_species_melody`, `third_species_melody`, `third_species_triple_meter_melody`, `fourth_species_melody`, `combined_first_second_third_species_melody`, `fifth_species_melody`, `arch_contour_melody`, `ascending_contour_melody`, `descending_contour_melody`, `static_contour_melody`, `valley_contour_melody`, `wave_contour_melody` |
+  | `:harmony` | `first_species_harmony`, `second_species_harmony`, `third_species_harmony`, `third_species_triple_meter_harmony`, `fourth_species_harmony`, `combined_first_second_third_species_harmony`, `fifth_species_harmony` |
+
+- Guides now carry identity: `.key` (snake_case of the class name), `.category` (`:melody` or `:harmony`, derived from the `SpeciesMelody`/`SpeciesHarmony` ancestry), and `.display_name` (localizable, with a computed English default). Consumers no longer need to hand-maintain a map of guide constants to categories.
+- `HeadMusic::Style::Guides::Configured` — the guide-layer twin of `Annotation::Configured`. It pairs a guide class with options and answers `analyze(voice)`, so it drops into `Style::Analysis` wherever a guide class was expected. `Guides::Base.with(**options)` returns one, and `#with` layers further options without dropping earlier ones.
+- `HeadMusic::Style::Guides::ContourMelody` — one configurable guide replacing the six contour subclasses: `ContourMelody.with(contour: :arch, minimum_melodic_intervals: 2)`. An invalid contour raises `ArgumentError` at configuration time, not at analysis.
+
+### Changed
+
+- **Breaking.** The six contour guide classes are removed: `ArchContourMelody`, `AscendingContourMelody`, `DescendingContourMelody`, `StaticContourMelody`, `ValleyContourMelody`, and `WaveContourMelody`. Their rulesets are unchanged and still reachable — by key, through the registry. Migrate constant references to `Guide.get`:
+
+  | Removed constant | Replacement |
+  | --- | --- |
+  | `Guides::ArchContourMelody` | `Style::Guide.get("arch_contour_melody")` |
+  | `Guides::AscendingContourMelody` | `Style::Guide.get("ascending_contour_melody")` |
+  | `Guides::DescendingContourMelody` | `Style::Guide.get("descending_contour_melody")` |
+  | `Guides::StaticContourMelody` | `Style::Guide.get("static_contour_melody")` |
+  | `Guides::ValleyContourMelody` | `Style::Guide.get("valley_contour_melody")` |
+  | `Guides::WaveContourMelody` | `Style::Guide.get("wave_contour_melody")` |
+
+- **Breaking.** `Guides::DiatonicMelody.contour_ruleset` and `Guides::DiatonicMelody::CONTOUR_PEER_WEIGHT_BUDGET` are removed. The budget constant now lives on the guide that uses it, as `Guides::ContourMelody::PEER_WEIGHT_BUDGET`.
+- **Breaking.** Neither a configured guide nor `Guides::ContourMelody` has a `::RULESET` constant — read `#ruleset` or `.ruleset(**options)` instead. `Guides::Base.ruleset` is now a method rather than a bare constant read, and `ContourMelody` deliberately does not descend from `DiatonicMelody`, so a guide whose ruleset depends on configuration raises rather than silently resolving an ancestor's ruleset through Ruby's constant lookup.
+- **Breaking.** `guide.name` on a configured guide returns the underlying class name, which is shared across all six contour configurations. Persist `guide.key`, not `guide.name`; use `guide.display_name` for presentation.
+- `Style::Analysis.new` now raises `ArgumentError` when given something that cannot answer `analyze`. Previously a `nil` guide — the result of an unrecognized key — surfaced much later as a `NoMethodError` on `nil`.
+- **Breaking.** `Guides::Base.with` raises `ArgumentError` when given options for a guide that takes none, rather than accepting them and failing at the first `analyze` with Ruby's bare `wrong number of arguments (given 1, expected 0)`. A guide accepts configuration by declaring keywords on `.ruleset`, so `FuxCantusFirmus.with(contour: :arch)` now names the guide and the options it cannot take. `Guides::Configured` resolves its ruleset in its constructor for the same reason: a configuration error belongs at `.with`, not mid-grading.
+- **Breaking.** `Instruments::Instrument.get` no longer accepts a second positional argument. The deprecated two-argument form joined its arguments with an underscore, so `Instrument.get("trumpet", "in_c")` becomes `Instrument.get("trumpet_in_c")`. It never emitted a runtime deprecation warning, so check call sites rather than logs. The two-argument form also fell back to the base instrument when the combined name did not exist — `get("trumpet", "in_q")` returned the trumpet — where `get("trumpet_in_q")` returns `nil`.
+- The six contour rulesets are byte-for-byte what they were: the same ten rubric peers sharing φ⁻² evenly, `Contoured` at φ⁻¹, and the same per-contour motion gate (omitted for `static`). Fitness values are unchanged.
+
+- **Breaking.** The ABC parser and lexer and the MusicXML writer each shed a responsibility to a collaborator, leaving no file in the gem above a RubyCritic C. Behavior is unchanged and no public method signature moved, but four constants did, and the old names no longer resolve:
+  - `Notation::ABC::BodyLexer::Token` is now `Notation::ABC::Token`. The token type is consumed by `Parser` and `Preflight`, not just the lexer.
+  - `Notation::ABC::BodyLexer::ChordNote` is now `Notation::ABC::ChordScanner::ChordNote`, alongside the bracket-chord scanning that produces it.
+  - `Notation::ABC::Parser::REPEAT_ENDING_STYLES`, `REPEAT_STARTING_STYLES`, and `SECTION_ENDING_STYLES` are now on `Notation::ABC::RepeatTagger`, which applies the repeat and volta marks they describe.
+  - `Notation::MusicXML::Writer::XML_ESCAPES` is now `Notation::MusicXML::XmlText::ESCAPES`, shared with the note and lyric writers. `Writer::INDENT` still resolves, through the same module.
+
 ## [18.0.0] - 2026-07-27
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (18.0.0)
+    head_music (19.0.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)
@@ -87,7 +87,7 @@ GEM
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    json (2.21.1)
+    json (2.21.2)
     kramdown (2.5.2)
       rexml (>= 3.4.4)
     language_server-protocol (3.17.0.6)
@@ -180,7 +180,7 @@ GEM
       virtus (~> 2.0)
     securerandom (0.4.1)
     sexp_processor (4.17.5)
-    simplecov (1.0.2)
+    simplecov (1.0.3)
     standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)

data/README.md

@@ -52,6 +52,34 @@ chord = HeadMusic::Analysis::PitchSet.new(pitches)
 puts chord.major_triad?  # => true
 ```
 
+## Style Analysis
+
+Look up a style guide by key and analyze a voice against it. `Style::Guide.get` returns `nil` for an
+unknown key, so a stored key can be validated before use.
+
+```ruby
+guide = HeadMusic::Style::Guide.get('first_species_harmony')
+guide.category      # => :harmony
+guide.display_name  # => "First Species Harmony"
+
+analysis = HeadMusic::Style::Analysis.new(guide, voice)
+analysis.fitness    # => 0.0 to 1.0
+analysis.messages   # => ["Prefer contrary motion. Move voices in different melodic directions."]
+```
+
+Guides whose ruleset varies by configuration are built with `.with`. The six contour melodies are
+registered under their own keys, and each key is exactly one such configuration:
+
+```ruby
+HeadMusic::Style::Guide.get('arch_contour_melody')
+# the same guide, spelled out
+HeadMusic::Style::Guides::ContourMelody.with(contour: :arch, minimum_melodic_intervals: 2)
+```
+
+Configure it differently and you get a different guide — one the registry does not hold, whose `key`
+is `nil` and whose `display_name` falls back to the class. Prefer the key when you mean a registered
+guide, and `.with` when you deliberately want a configuration of your own.
+
 ## Documentation
 
 - **API Documentation**: [rubydoc.info/gems/head_music](https://rubydoc.info/gems/head_music)

data/lib/head_music/instruments/instrument.rb

@@ -31,17 +31,12 @@ class HeadMusic::Instruments::Instrument
   class << self
     # Factory method to get an Instrument instance
     # @param name [String, Symbol] instrument name (e.g., "clarinet", "clarinet_in_a")
-    # @param variant_key [String, Symbol, nil] DEPRECATED: variant key (for backward compatibility)
     # @return [Instrument, nil] instrument instance or nil if not found
-    def get(name, variant_key = nil)
+    def get(name)
       return name if name.is_a?(self)
 
       name_str = name.to_s
-      if variant_key
-        find_valid_instrument("#{name_str}_#{variant_key}") || find_valid_instrument(name_str)
-      else
-        find_valid_instrument(name_str) || find_valid_instrument(normalize_variant_name(name_str))
-      end
+      find_valid_instrument(name_str) || find_valid_instrument(normalize_variant_name(name_str))
     end
 
     def find_valid_instrument(name)

data/lib/head_music/locales/en.yml

@@ -566,3 +566,8 @@ en:
       staff: staff
       tuba: tuba
       tuning: tuning
+    style:
+      guides:
+        # Only keys whose humanized default is wrong need an entry here;
+        # HeadMusic::Style::Guide.display_name_for derives the rest.
+        salzer_schachter_cantus_firmus: "Salzer–Schachter Cantus Firmus"