head_music 12.5.0 → 13.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a02a5ef281eecc76bcf953aa51c04078858b4588f2b85c0b1a4d1f4d88464d6
-  data.tar.gz: 5a31a94133ffbb97944524d75aedcbbfcbf7ce769fe6049559818a1940438442
+  metadata.gz: ef07dfecedad63290f5f352704f96967dff09ba5bc305adf04b25c033bf580fb
+  data.tar.gz: fd20210a40bd733fada3307f6b9b772bd317168132443d164aa417a0d2c490bd
 SHA512:
-  metadata.gz: 369c959ae6f69cd609a65e4dee6b4aace0283d107132fec61f3b35afadfeb27d5386c60e969d88cfe626bdc0873e3c5dbed736513d93523e68c5dfca4127b6f1
-  data.tar.gz: 0f04cf766ce824188270ad00fe29866f652befcb0ff0d5c3eeaadd21e286b088bfb8883fe8687f94c0eaf2e216c5a2ee0377afc91756df18e9e587b5fef0eb41
+  metadata.gz: cee6694acb9303262ac645153f47462d5e6870e62853bc800d00e731dc0fc5321c00d2e75109c6805a1c2ba0d1b62ddbfdc8196bd445d52062097fd05c24d9eb
+  data.tar.gz: 8ee30bdeaf48faf0f43411352763c6d67ec3f5919c707054bcdee4ab07514936d09c335a03fa031e7df59479c597aeb4c165765b8c6de5210d9d45edd5639e3a

data/CHANGELOG.md

@@ -7,6 +7,133 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [13.0.0] - 2026-07-05
+
+### Added
+
+- `HeadMusic::Notation::NotationStyle` — named notation traditions (`british_brass_band`, `german`, `italian`, `concert_pitch`) resolved as sparse overlays on a `default` style, backed by `notation_styles.yml`, with `.get`/`.default` factories and `#notation_for`
+- `HeadMusic::Notation::InstrumentNotation` — the resolved notation value object (clef, sounding transposition, staves, and recorded register/clef alternatives) with value equality
+- `Instrument#notation(style:)` — notate an instrument through a chosen notation style, defaulting to `default`
+
+### Changed
+
+- Notation concerns (clef, sounding transposition, staff structure) now live in `NotationStyle` instead of on the instrument. `Instrument`'s notation methods (`default_staves`, `default_clefs`, `sounding_transposition`, etc.) delegate to the default style and resolve to the same values as before.
+- `Instrument#staff_schemes` now returns only the instrument's default scheme; named schemes (brass-band, German/Italian bass clarinet, and register/clef alternatives) have moved into notation styles.
+
+### Removed
+
+- `staff_schemes` data from `instruments.yml` and the internal `staff_schemes` plumbing on `Instrument`. Per-instrument notation conventions are now expressed as notation styles. (Breaking change — hence the major version bump.)
+
+## [12.6.0] - 2026-07-03
+
+### Added
+
+- `DiatonicMelody` guide: a free diatonic melody not bound to cantus firmus start/end constraints (note-count range configurable, defaulting to 5–24)
+- Configurable guidelines — a guideline can now carry configuration into a `RULESET` via `Annotation.with(...)` (wrapped in `Annotation::Configured`):
+  - `MinimumNotes` / `MaximumNotes` — configurable note-count floor and ceiling (`AtLeastEightNotes` / `UpToFourteenNotes` retained as named defaults)
+  - `NoteCountPerBar` — configurable `count` and `rhythmic_value` (unifies `OnePerBar`, `TwoPerBar`, `ThreePerBar`, `FourPerBar`)
+  - `DirectionChanges` — configurable `maximum_notes_per_direction` (unifies `ModerateDirectionChanges` and `FrequentDirectionChanges`)
+  - Configurable thresholds on `SingableRange`, `MostlyConjunct`, `LimitOctaveLeaps`, and `SecondSpeciesBreak`
+
+### Changed
+
+- Extracted `HeadMusic::Style::Guides::Base` for shared guide analysis behavior; `SpeciesMelody` and `SpeciesHarmony` now inherit from it
+- Hoisted the guidelines common to every guide into `MELODIC_CORE` / `HARMONIC_CORE` constants on the species base classes
+- `SingableRange`'s message now reflects the configured range
+- Renamed the `quality` rake task to `validate`
+
+## [12.5.0] - 2026-04-08
+
+### Changed
+
+- Improved fifth-species counterpoint guidelines
+- Code quality improvements
+
+### Removed
+
+- Combined 2+3+4 species guides and their guidelines
+
+## [12.4.0] - 2026-04-06
+
+### Added
+
+- Fifth-species (florid) counterpoint guides
+- Standard and alternate instrument tunings
+
+### Fixed
+
+- Ukulele family stringings, tunings, and range data
+
+## [12.3.0] - 2026-02-25
+
+### Added
+
+- Fourth-species counterpoint guides
+
+### Changed
+
+- Code quality pass
+
+## [12.2.0] - 2026-02-24
+
+### Changed
+
+- Improved guidelines for first-bar entry
+
+## [12.1.0] - 2026-02-24
+
+### Changed
+
+- Refactored species guidelines into separate first-bar, middle-bar, and final-bar rules
+- Unified `FinalBarWholeNote` and `FinalBarDottedHalfNote` into `NoteFillsFinalBar`
+
+## [12.0.1] - 2026-02-23
+
+### Changed
+
+- Renamed triple-meter guides
+
+## [12.0.0] - 2026-02-21
+
+### Added
+
+- Third-species 3:1 guidelines
+- Allow a descending minor sixth as a singable interval
+
+### Changed
+
+- Extracted shared base classes for guides and step-to-final-note guidelines
+- Refactored third-species dissonance handling and other files to reduce code smells
+
+## [11.8.0] - 2026-02-16
+
+### Added
+
+- `ThirdSpeciesMelody` and `ThirdSpeciesHarmony` guides
+- `ThirdSpeciesDissonanceTreatment` guideline
+- `FourToOne` guideline
+- Third-species counterpoint reference document
+
+## [11.7.0] - 2026-02-13
+
+### Added
+
+- Parallel-perfect check for first species
+
+### Changed
+
+- `Analysis#fitness` now uses the geometric mean
+
+## [11.6.1] - 2026-02-12
+
+### Added
+
+- Additional test coverage for the two-to-one guideline
+
+### Fixed
+
+- Accept an implied rest in the first bar of second-species counterpoint
+
 ## [11.6.0] - 2026-02-10
 
 ### Added

data/CLAUDE.md

@@ -26,8 +26,8 @@ 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
+# Run all validation checks (tests, linting, security)
+bundle exec rake validate
 
 # Open interactive console with gem loaded
 bin/console

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (12.5.0)
+    head_music (13.0.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -9,27 +9,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.2.1)
+    activesupport (8.1.3)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+      uri (>= 0.13.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.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)
@@ -38,7 +38,7 @@ GEM
       logger (~> 1.5)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.7)
     connection_pool (2.5.3)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
@@ -201,16 +201,18 @@ GEM
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
+    uri (1.1.1)
     virtus (2.0.0)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
-    yard (0.9.37)
+    yard (0.9.44)
     zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

data/Rakefile

@@ -33,8 +33,8 @@ end
 
 task default: :spec
 
-desc "Run all quality checks (tests, linting, security audit, code quality)"
-task quality: [:spec, :standard, "bundle:audit:check", :rubycritic]
+desc "Run all validation checks (tests, linting, security audit, code quality)"
+task validate: [:spec, :standard, "bundle:audit:check", :rubycritic]
 
 desc "Open an irb session preloaded with this library"
 task :console do

data/lib/head_music/content/bar.rb

@@ -3,17 +3,72 @@ module HeadMusic::Content; end
 
 # Representation of a bar in a composition
 # Encapsulates meter and key signature changes
+# and repeat structure (repeat barlines and volta brackets) as content semantics
 class HeadMusic::Content::Bar
-  attr_reader :composition
+  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes
   attr_accessor :key_signature, :meter
+  attr_writer :starts_repeat
 
   def initialize(composition, key_signature: nil, meter: nil)
     @composition = composition
     @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
     @meter = HeadMusic::Rudiment::Meter.get(meter) if meter
+    @starts_repeat = false
+    @ends_repeat_after_num_plays = nil
+    @plays_on_passes = nil
+  end
+
+  def starts_repeat?
+    @starts_repeat
+  end
+
+  def ends_repeat_after_num_plays=(value)
+    unless valid_ends_repeat_after_num_plays?(value)
+      raise ArgumentError, "ends_repeat_after_num_plays must be nil or an integer of at least 2"
+    end
+    @ends_repeat_after_num_plays = value
+  end
+
+  def ends_repeat?
+    !ends_repeat_after_num_plays.nil?
+  end
+
+  def plays_on_passes=(value)
+    unless valid_plays_on_passes?(value)
+      raise ArgumentError, "plays_on_passes must be nil or a non-empty array of unique positive integers"
+    end
+    @plays_on_passes = value
+  end
+
+  def plays_on_pass?(pass_number)
+    plays_on_passes.nil? || plays_on_passes.include?(pass_number)
   end
 
   def to_s
-    ["Bar", key_signature, meter].compact.join(" ")
+    ["Bar", key_signature, meter, repeat_summary].compact.join(" ")
+  end
+
+  private
+
+  def valid_ends_repeat_after_num_plays?(value)
+    return true if value.nil?
+
+    value.is_a?(Integer) && value >= 2
+  end
+
+  def valid_plays_on_passes?(value)
+    return true if value.nil?
+
+    value.is_a?(Array) && !value.empty? &&
+      value.all? { |pass| pass.is_a?(Integer) && pass.positive? } &&
+      value.uniq.length == value.length
+  end
+
+  def repeat_summary
+    parts = []
+    parts << "|:" if starts_repeat?
+    parts << ":|x#{ends_repeat_after_num_plays}" if ends_repeat?
+    parts << "(passes #{plays_on_passes.join(",")})" if plays_on_passes
+    parts.join(" ") unless parts.empty?
   end
 end

data/lib/head_music/content/comment.rb

@@ -0,0 +1,32 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# A comment is a free-text annotation, optionally anchored to a position in a composition.
+class HeadMusic::Content::Comment
+  attr_reader :composition, :text, :position
+
+  def initialize(composition, text, position = nil)
+    @composition = composition
+    @text = text
+    ensure_position(position)
+  end
+
+  def to_s
+    text
+  end
+
+  private
+
+  def ensure_position(position)
+    return if position.nil?
+
+    @position = if position.is_a?(HeadMusic::Content::Position)
+      unless position.composition.equal?(composition)
+        raise ArgumentError, "position belongs to a different composition"
+      end
+      position
+    else
+      HeadMusic::Content::Position.new(composition, position)
+    end
+  end
+end

data/lib/head_music/content/composition.rb

@@ -3,11 +3,14 @@ module HeadMusic::Content; end
 
 # A composition is musical content.
 class HeadMusic::Content::Composition
-  attr_reader :name, :key_signature, :meter, :voices
+  attr_reader :name, :key_signature, :meter, :voices, :composer, :origin, :comments
 
-  def initialize(name: nil, key_signature: nil, meter: nil)
+  def initialize(name: nil, key_signature: nil, meter: nil, composer: nil, origin: nil, comments: nil)
     ensure_attributes(name, key_signature, meter)
+    @composer = composer
+    @origin = origin
     @voices = []
+    @comments = Array(comments).map { |text| HeadMusic::Content::Comment.new(self, text) }
   end
 
   def add_voice(role: nil)
@@ -15,6 +18,11 @@ class HeadMusic::Content::Composition
     @voices.last
   end
 
+  def add_comment(text, position = nil)
+    @comments << HeadMusic::Content::Comment.new(self, text, position)
+    @comments.last
+  end
+
   def meter_at(bar_number)
     meter_change = last_meter_change(bar_number)
     meter_change ? meter_change.meter : meter

data/lib/head_music/instruments/instrument.rb

@@ -21,13 +21,12 @@ module HeadMusic::Instruments; end
 #   pitch_key: the pitch designation (e.g., "b_flat", "a", "c")
 #   alias_name_keys: alternative names for the instrument
 #   range_categories: size/range classifications
-#   staff_schemes: notation schemes (to be moved to NotationStyle later)
 class HeadMusic::Instruments::Instrument
   include HeadMusic::Named
 
   INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
 
-  attr_reader :name_key, :parent_key, :alias_name_keys, :range_categories, :staff_schemes_data
+  attr_reader :name_key, :parent_key, :alias_name_keys, :range_categories
 
   class << self
     # Factory method to get an Instrument instance
@@ -110,18 +109,29 @@ class HeadMusic::Instruments::Instrument
     @pitch_designation ||= HeadMusic::Rudiment::Spelling.get(pitch_key_to_designation)
   end
 
-  # Staff schemes (notation concern - kept for backward compatibility)
+  # Notation for this instrument in the given style (defaults to :default).
+  def notation(style: :default)
+    HeadMusic::Notation::NotationStyle.get(style).notation_for(self)
+  end
+
+  # Staff schemes are a notation concern; they now live in NotationStyle.
+  # These methods remain for backward compatibility and delegate to the
+  # default style. Referenced only inside method bodies, because the Notation
+  # module loads after Instruments (see head_music.rb load order).
   def staff_schemes
-    @staff_schemes ||= build_staff_schemes
+    [default_staff_scheme]
   end
 
   def default_staff_scheme
-    @default_staff_scheme ||=
-      staff_schemes.find(&:default?) || staff_schemes.first
+    @default_staff_scheme ||= HeadMusic::Instruments::StaffScheme.new(
+      key: "default",
+      instrument: self,
+      list: default_notation_staves_data
+    )
   end
 
   def default_staves
-    default_staff_scheme&.staves || []
+    default_staff_scheme.staves
   end
 
   def default_clefs
@@ -254,7 +264,6 @@ class HeadMusic::Instruments::Instrument
     @pitch_key = record["pitch_key"]
     @alias_name_keys = record["alias_name_keys"] || []
     @range_categories = record["range_categories"] || []
-    @staff_schemes_data = record["staff_schemes"] || {}
 
     initialize_name
   end
@@ -305,15 +314,10 @@ class HeadMusic::Instruments::Instrument
     end
   end
 
-  def build_staff_schemes
-    return parent&.staff_schemes || [] if staff_schemes_data.empty?
-
-    staff_schemes_data.map do |key, list|
-      HeadMusic::Instruments::StaffScheme.new(
-        key: key,
-        instrument: self,
-        list: list
-      )
-    end
+  # The raw staff-attribute list for this instrument's default notation,
+  # resolved from the default NotationStyle.
+  def default_notation_staves_data
+    notation = HeadMusic::Notation::NotationStyle.default.notation_for(self)
+    (notation&.staves || []).map(&:attributes)
   end
 end