head_music 17.3.0 → 17.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5c0dadcdb3b7bba85e7de810d0d52d960e6bf2b9386b62db9ec201336e084bb
-  data.tar.gz: 33c3b42e6b07ed88649b6fb0c7b42476c9d45edbc18ef0cc458ff8978b876c4c
+  metadata.gz: 4d075fb623ea50351c7ac422f44be04c265867253312b6b27faffaf76bb3b397
+  data.tar.gz: 5649553e987c0a98cd9388d24d6e15155f88da4e59eaf62f7a2d9f988e656b36
 SHA512:
-  metadata.gz: eb3e9c1f84f2efbf87947a2037b9804cf9e16247be5c180509cb06a9c3c66229513b8cdcc2e10fa1d8f2f7ed952b91de99375e5939de33665aec909331f8f115
-  data.tar.gz: f871c26bf5da1052474f5317d72788df760f994f3264dbebc6ad35e91b91124088378524b46f4fc50721f6b9442453978018f6c012dd40f55926a66dd516539c
+  metadata.gz: a89a0dfc44c68e823e5c1eff6c48b950b759cdd059c504adacd8bd6b3d06dc0b23bc1a13b690e68086526a33ab3bebc1617825abecfc3ab108c89425a44d6f55
+  data.tar.gz: 921ce718ccc4b728ed57dce347fbce73ae7c120960931b32933a5893f52992b4aa40ec115e248421a3f53d3a66defff0b4d7eac15efaf34ae51fae23e5e2a328

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.4.0] - 2026-07-20
+
+### Changed
+
+- Internal refactoring for clarity and maintainability, with no changes to public behavior or output. Complex classes were split along their natural seams by extracting focused collaborators and value objects, each with its own spec: `MusicXML::Preflight` and `MusicXML::RenderPlan` from the MusicXML `Writer`; `Instruments::InstrumentName`, `InstrumentCatalog`, and `StaffProfile` from `Instrument`; `Analysis::ChordAnalysis` from `PitchCollection`; `Content::SoundResolver` from `Placement`; `Time::SmpteConverter` and `MusicalTimeConverter` from `Conductor`; `Composition::SchemaValues` from `HashDeserializer`; `Pitch::NaturalStep` from `Pitch`; `Voice::MelodicLine` from `Voice`; `Dyad::ChordImplication` from `Dyad`; and `ABC::Preflight` plus per-voice note-assembly moved onto `ABC::VoiceState` in the ABC parser.
+- Shared value-object equality was consolidated into a `ValueEquality` mixin, and duplication was reduced across the style guides, notation writers, and rudiments.
+- Nested classes that had outgrown their host files were given their own files without changing their constant paths: `Named::Locale` and `Named::LocalizedName`, `Voice::MelodicNotePair`, `Spelling::EnharmonicEquivalence`, and `Style::Annotation::Configured`.
+
 ## [17.3.0] - 2026-07-19
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (17.3.0)
+    head_music (17.4.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)

data/lib/head_music/analysis/chord_analysis.rb

@@ -0,0 +1,123 @@
+# A module for musical analysis
+module HeadMusic::Analysis; end
+
+# Classifies a PitchCollection as a tertian chord: whether it is a triad,
+# seventh, or extended chord; its triad quality (major/minor/diminished/
+# augmented); and its inversion. "Tertian" means the pitches, once reduced to
+# within an octave and rotated, stack in thirds.
+class HeadMusic::Analysis::ChordAnalysis
+  # Scale-degree signatures (above the bass) of each tertian chord size, used
+  # to recognize a stack of thirds in any rotation.
+  TERTIAN_SONORITIES = {
+    implied_triad: [3],
+    triad: [3, 5],
+    seventh_chord: [3, 5, 7],
+    ninth_chord: [2, 3, 5, 7],
+    eleventh_chord: [2, 3, 4, 5, 7],
+    thirteenth_chord: [2, 3, 4, 5, 6, 7] # a.k.a. diatonic scale
+  }.freeze
+
+  # The interval-shorthand pairs (bass-to-third, third-to-fifth) that spell each
+  # triad quality, in every inversion.
+  TRIAD_PATTERNS = {
+    major: [%w[M3 m3], %w[m3 P4], %w[P4 M3]],
+    minor: [%w[m3 M3], %w[M3 P4], %w[P4 m3]],
+    diminished: [%w[m3 m3], %w[m3 A4], %w[A4 m3]],
+    augmented: [%w[M3 M3], %w[M3 d4], %w[d4 M3]]
+  }.freeze
+
+  attr_reader :collection
+
+  def initialize(collection)
+    @collection = collection
+  end
+
+  def triad?
+    collection.trichord? && tertian?
+  end
+
+  def consonant_triad?
+    major_triad? || minor_triad?
+  end
+
+  def major_triad?
+    triad_type?(:major)
+  end
+
+  def minor_triad?
+    triad_type?(:minor)
+  end
+
+  def diminished_triad?
+    triad_type?(:diminished)
+  end
+
+  def augmented_triad?
+    triad_type?(:augmented)
+  end
+
+  def root_position_triad?
+    collection.trichord? && stacked_in_thirds?(collection.reduction)
+  end
+
+  def first_inversion_triad?
+    collection.trichord? && stacked_in_thirds?(collection.reduction.uninvert)
+  end
+
+  def second_inversion_triad?
+    collection.trichord? && stacked_in_thirds?(collection.reduction.invert)
+  end
+
+  def seventh_chord?
+    collection.tetrachord? && tertian?
+  end
+
+  def root_position_seventh_chord?
+    collection.tetrachord? && stacked_in_thirds?(collection.reduction)
+  end
+
+  def first_inversion_seventh_chord?
+    collection.tetrachord? && stacked_in_thirds?(collection.reduction.uninvert)
+  end
+
+  def second_inversion_seventh_chord?
+    collection.tetrachord? && stacked_in_thirds?(collection.reduction.uninvert.uninvert)
+  end
+
+  def third_inversion_seventh_chord?
+    collection.tetrachord? && stacked_in_thirds?(collection.reduction.invert)
+  end
+
+  def ninth_chord?
+    collection.pentachord? && tertian?
+  end
+
+  def eleventh_chord?
+    collection.hexachord? && tertian?
+  end
+
+  def thirteenth_chord?
+    collection.heptachord? && tertian?
+  end
+
+  def tertian?
+    return false unless collection.diatonic_intervals.any?
+
+    inversion = collection.reduction
+    collection.pitches.length.times do
+      return true if TERTIAN_SONORITIES.value?(inversion.scale_degrees_above_bass_pitch)
+      inversion = inversion.invert
+    end
+    false
+  end
+
+  private
+
+  def triad_type?(type)
+    TRIAD_PATTERNS[type].include?(collection.reduction_diatonic_intervals.map(&:shorthand))
+  end
+
+  def stacked_in_thirds?(reduced_collection)
+    reduced_collection.diatonic_intervals.all?(&:third?)
+  end
+end

data/lib/head_music/analysis/circle.rb

@@ -46,14 +46,22 @@ class HeadMusic::Analysis::Circle < HeadMusic::Analysis::IntervalCycle
   def pitches_down
     @pitches_down ||= [starting_pitch].tap do |list|
       loop do
-        next_pitch = list.last - interval
-        next_pitch += octave while starting_pitch - next_pitch > 12
-        break if next_pitch.pitch_class == list.first.pitch_class
+        next_pitch = folded_down(list.last)
+        break if next_pitch.pitch_class == starting_pitch.pitch_class
 
         list << next_pitch
       end
     end
   end
 
+  private
+
+  # The next pitch a cycle-interval below, folded up by octaves to stay within an octave of the start.
+  def folded_down(pitch)
+    next_pitch = pitch - interval
+    next_pitch += octave while starting_pitch - next_pitch > 12
+    next_pitch
+  end
+
   private_class_method :new
 end

data/lib/head_music/analysis/diatonic_interval.rb

@@ -59,15 +59,17 @@ class HeadMusic::Analysis::DiatonicInterval
 
   # Override Named module method to try I18n and fall back to computed name
   def name(locale_code: nil)
-    if locale_code
-      name_key = HeadMusic::Utilities::HashKey.for(naming.name)
-      if I18n.backend.translations[locale_code]
-        locale_data = I18n.backend.translations[locale_code][:head_music] || {}
-        return locale_data[:diatonic_intervals][name_key] if locale_data.dig(:diatonic_intervals, name_key)
-        return locale_data[:chromatic_intervals][name_key] if locale_data.dig(:chromatic_intervals, name_key)
-      end
-    end
-    naming.name
+    computed_name = naming.name
+    return computed_name unless locale_code
+
+    translations = I18n.backend.translations[locale_code]
+    return computed_name unless translations
+
+    name_key = HeadMusic::Utilities::HashKey.for(computed_name)
+    locale_data = translations[:head_music] || {}
+    locale_data.dig(:diatonic_intervals, name_key) ||
+      locale_data.dig(:chromatic_intervals, name_key) ||
+      computed_name
   end
 
   def to_s
@@ -79,8 +81,9 @@ class HeadMusic::Analysis::DiatonicInterval
     if identifier.is_a?(String) || identifier.is_a?(Symbol)
       name = Parser.new(identifier)
       semitones = Semitones.new(name.degree_name.to_sym, name.quality_name).count
-      higher_pitch = HeadMusic::Rudiment::Pitch.from_number_and_letter(HeadMusic::Rudiment::Pitch.middle_c + semitones, name.higher_letter)
-      interval = new(HeadMusic::Rudiment::Pitch.middle_c, higher_pitch)
+      middle_c = HeadMusic::Rudiment::Pitch.middle_c
+      higher_pitch = HeadMusic::Rudiment::Pitch.from_number_and_letter(middle_c + semitones, name.higher_letter)
+      interval = new(middle_c, higher_pitch)
       interval.ensure_localized_name(name: identifier.to_s)
       interval
     else

data/lib/head_music/analysis/dyad/chord_implication.rb

@@ -0,0 +1,101 @@
+class HeadMusic::Analysis::Dyad
+  # Enumerates the chords (as PitchCollections) that contain a given dyad.
+  # Trichords and seventh chords are built at every chromatic root from a fixed
+  # table of interval stacks, then kept only when they actually span the dyad.
+  # An optional key narrows the results to diatonic chords and ranks the
+  # survivors by how many of their pitches the key contains.
+  class ChordImplication
+    TRICHORD_INTERVALS = [
+      %w[M3 P5],   # major triad
+      %w[m3 P5],   # minor triad
+      %w[m3 d5],   # diminished triad
+      %w[M3 A5],   # augmented triad
+      %w[P4 P5],   # sus4 (not a triad)
+      %w[M2 P5]    # sus2 (not a triad)
+    ].freeze
+
+    SEVENTH_CHORD_INTERVALS = [
+      %w[M3 P5 M7],   # major seventh
+      %w[M3 P5 m7],   # dominant seventh (major-minor)
+      %w[m3 P5 m7],   # minor seventh
+      %w[m3 P5 M7],   # minor-major seventh
+      %w[m3 d5 m7],   # half-diminished seventh
+      %w[m3 d5 d7],   # diminished seventh
+      %w[M2 M3 P5 m7], # dominant ninth
+      %w[m2 M3 P5 m7], # dominant minor ninth
+      %w[M2 m3 P5 m7], # minor ninth
+      %w[M2 M3 P5 M7]  # major ninth
+    ].freeze
+
+    attr_reader :dyad_pitch_classes, :key
+
+    def initialize(dyad_pitch_classes, key)
+      @dyad_pitch_classes = dyad_pitch_classes
+      @key = key
+    end
+
+    def trichords
+      @trichords ||= ranked(chords_from(TRICHORD_INTERVALS))
+    end
+
+    def seventh_chords
+      @seventh_chords ||= ranked(chords_from(SEVENTH_CHORD_INTERVALS))
+    end
+
+    private
+
+    # Without a key every chord stands; with one, keep the diatonic chords and
+    # order them by how much they agree with the key. Concentrating the key
+    # check here keeps filter and sort free of their own guards.
+    def ranked(chords)
+      return chords unless key
+
+      sort_by_diatonic_agreement(filter_by_key(chords))
+    end
+
+    def chords_from(interval_sets)
+      candidate_chords(interval_sets)
+        .select { |chord| includes_dyad?(chord) }
+        .uniq { |chord| chord.pitch_classes.sort.map(&:to_i) }
+    end
+
+    def candidate_chords(interval_sets)
+      candidate_roots.flat_map do |root_pitch|
+        interval_sets.map { |intervals| build_chord(root_pitch, intervals) }
+      end
+    end
+
+    def candidate_roots
+      HeadMusic::Rudiment::Spelling::CHROMATIC_SPELLINGS.map do |root_spelling|
+        HeadMusic::Rudiment::Pitch.get("#{root_spelling}4")
+      end
+    end
+
+    def build_chord(root_pitch, intervals)
+      chord_pitches = [root_pitch] + intervals.map do |name|
+        HeadMusic::Analysis::DiatonicInterval.get(name).above(root_pitch)
+      end
+      HeadMusic::Analysis::PitchCollection.new(chord_pitches)
+    end
+
+    def includes_dyad?(pitch_collection)
+      dyad_pitch_classes.all? { |pitch_class| pitch_collection.pitch_classes.include?(pitch_class) }
+    end
+
+    def filter_by_key(pitch_collections)
+      pitch_collections.select do |pitch_collection|
+        pitch_collection.pitches.all? { |pitch| diatonic_spellings.include?(pitch.spelling) }
+      end
+    end
+
+    def sort_by_diatonic_agreement(pitch_collections)
+      pitch_collections.sort_by do |pitch_collection|
+        -pitch_collection.pitches.count { |pitch| diatonic_spellings.include?(pitch.spelling) }
+      end
+    end
+
+    def diatonic_spellings
+      @diatonic_spellings ||= key.scale.spellings
+    end
+  end
+end

data/lib/head_music/analysis/dyad.rb

@@ -31,11 +31,7 @@ class HeadMusic::Analysis::Dyad
   end
 
   def possible_trichords
-    @possible_trichords ||= begin
-      trichords = generate_possible_trichords
-      trichords = filter_by_key(trichords) if key
-      sort_by_diatonic_agreement(trichords)
-    end
+    chord_implication.trichords
   end
 
   def possible_triads
@@ -43,11 +39,7 @@ class HeadMusic::Analysis::Dyad
   end
 
   def possible_seventh_chords
-    @possible_seventh_chords ||= begin
-      seventh_chords = generate_possible_seventh_chords
-      seventh_chords = filter_by_key(seventh_chords) if key
-      sort_by_diatonic_agreement(seventh_chords)
-    end
+    chord_implication.seventh_chords
   end
 
   def enharmonic_respellings
@@ -68,111 +60,39 @@ class HeadMusic::Analysis::Dyad
 
   private
 
-  TRICHORD_INTERVALS = [
-    %w[M3 P5],   # major triad
-    %w[m3 P5],   # minor triad
-    %w[m3 d5],   # diminished triad
-    %w[M3 A5],   # augmented triad
-    %w[P4 P5],   # sus4 (not a triad)
-    %w[M2 P5]    # sus2 (not a triad)
-  ].freeze
-
-  SEVENTH_CHORD_INTERVALS = [
-    %w[M3 P5 M7],   # major seventh
-    %w[M3 P5 m7],   # dominant seventh (major-minor)
-    %w[m3 P5 m7],   # minor seventh
-    %w[m3 P5 M7],   # minor-major seventh
-    %w[m3 d5 m7],   # half-diminished seventh
-    %w[m3 d5 d7],   # diminished seventh
-    %w[M2 M3 P5 m7], # dominant ninth
-    %w[m2 M3 P5 m7], # dominant minor ninth
-    %w[M2 m3 P5 m7], # minor ninth
-    %w[M2 M3 P5 M7]  # major ninth
-  ].freeze
-
-  def generate_possible_trichords
-    generate_possible_chords(TRICHORD_INTERVALS)
-  end
-
-  def generate_possible_seventh_chords
-    generate_possible_chords(SEVENTH_CHORD_INTERVALS)
-  end
-
-  def generate_possible_chords(interval_sets)
-    dyad_pitch_classes = [lower_pitch.pitch_class, upper_pitch.pitch_class]
-    chords = []
-
-    HeadMusic::Rudiment::Spelling::CHROMATIC_SPELLINGS.each do |root_spelling|
-      root_pitch = HeadMusic::Rudiment::Pitch.get("#{root_spelling}4")
-
-      interval_sets.each do |intervals|
-        chord_pitches = [root_pitch] + intervals.map { |name| HeadMusic::Analysis::DiatonicInterval.get(name).above(root_pitch) }
-        pitch_collection = HeadMusic::Analysis::PitchCollection.new(chord_pitches)
-
-        if dyad_pitch_classes.all? { |pc| pitch_collection.pitch_classes.include?(pc) }
-          chords << pitch_collection
-        end
-      end
-    end
-
-    chords.uniq { |chord| chord.pitch_classes.sort.map(&:to_i) }
-  end
-
-  def filter_by_key(pitch_collections)
-    return pitch_collections unless key
-
-    pitch_collections.select do |pitch_collection|
-      pitch_collection.pitches.all? { |pitch| diatonic_spellings.include?(pitch.spelling) }
-    end
-  end
-
-  def sort_by_diatonic_agreement(pitch_collections)
-    return pitch_collections unless key
-
-    pitch_collections.sort_by do |pitch_collection|
-      -pitch_collection.pitches.count { |pitch| diatonic_spellings.include?(pitch.spelling) }
-    end
-  end
-
-  def diatonic_spellings
-    @diatonic_spellings ||= key.scale.spellings
+  def chord_implication
+    @chord_implication ||= ChordImplication.new([lower_pitch.pitch_class, upper_pitch.pitch_class], key)
   end
 
   def generate_enharmonic_respellings
-    respellings = []
-
-    # Get enharmonic equivalents for each pitch
-    pitch1_equivalents = enharmonic_equivalents_for(pitch1)
-    pitch2_equivalents = enharmonic_equivalents_for(pitch2)
+    lower_equivalents = enharmonic_equivalents_for(pitch1)
+    upper_equivalents = enharmonic_equivalents_for(pitch2)
 
-    # Generate all combinations
-    pitch1_equivalents.each do |lower|
-      pitch2_equivalents.each do |upper|
-        next if lower.spelling == pitch1.spelling && upper.spelling == pitch2.spelling
-
-        respellings << self.class.new(lower, upper, key: key)
-      end
-    end
+    lower_equivalents.product(upper_equivalents)
+      .reject { |lower, upper| original_spelling?(lower, upper) }
+      .map { |lower, upper| self.class.new(lower, upper, key: key) }
+  end
 
-    respellings
+  def original_spelling?(lower, upper)
+    lower.spelling == pitch1.spelling && upper.spelling == pitch2.spelling
   end
 
   ALTERATION_SIGNS = {-2 => "bb", -1 => "b", 0 => "", 1 => "#", 2 => "##"}.freeze
 
   def enharmonic_equivalents_for(pitch)
-    target_pitch_class = pitch.pitch_class
-    equivalents = [pitch]
-
-    HeadMusic::Rudiment::LetterName.all.each do |letter_name|
-      ALTERATION_SIGNS.each_value do |sign|
-        spelling = HeadMusic::Rudiment::Spelling.get("#{letter_name}#{sign}")
-        next unless spelling && spelling.pitch_class == target_pitch_class
-        next if equivalents.any? { |equiv| equiv.spelling == spelling }
-
-        equivalents << HeadMusic::Rudiment::Pitch.fetch_or_create(spelling, pitch.register)
-      end
+    equivalent_pitches = enharmonic_spellings_for(pitch.pitch_class).map do |spelling|
+      HeadMusic::Rudiment::Pitch.fetch_or_create(spelling, pitch.register)
     end
+    [pitch, *equivalent_pitches].uniq(&:spelling)
+  end
+
+  def enharmonic_spellings_for(target_pitch_class)
+    all_spellings.select { |spelling| spelling.pitch_class == target_pitch_class }
+  end
 
-    equivalents
+  def all_spellings
+    HeadMusic::Rudiment::LetterName.all.flat_map do |letter_name|
+      ALTERATION_SIGNS.each_value.map { |sign| HeadMusic::Rudiment::Spelling.get("#{letter_name}#{sign}") }
+    end.compact
   end
 end

data/lib/head_music/analysis/interval_cycle.rb

@@ -41,15 +41,21 @@ class HeadMusic::Analysis::IntervalCycle
   def pitches_up
     @pitches_up ||= [starting_pitch].tap do |list|
       loop do
-        next_pitch = list.last + interval
-        next_pitch -= octave while next_pitch - starting_pitch > 12
-        break if next_pitch.pitch_class == list.first.pitch_class
+        next_pitch = folded_up(list.last)
+        break if next_pitch.pitch_class == starting_pitch.pitch_class
 
         list << next_pitch
       end
     end
   end
 
+  # The next pitch a cycle-interval above, folded down by octaves to stay within an octave of the start.
+  def folded_up(pitch)
+    next_pitch = pitch + interval
+    next_pitch -= octave while next_pitch - starting_pitch > 12
+    next_pitch
+  end
+
   def octave
     @octave ||= HeadMusic::Analysis::DiatonicInterval.get(:perfect_octave)
   end