head_music 17.3.0 → 17.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5c0dadcdb3b7bba85e7de810d0d52d960e6bf2b9386b62db9ec201336e084bb
-  data.tar.gz: 33c3b42e6b07ed88649b6fb0c7b42476c9d45edbc18ef0cc458ff8978b876c4c
+  metadata.gz: 5a439a4b39c708eb38984b3878e7bc0c02ce92d7c693d34041ed3b8c69acfffe
+  data.tar.gz: d0b702f38b7de8826fe7a345c3b17d0a8ea8c963bd922343889ba97a47f3538e
 SHA512:
-  metadata.gz: eb3e9c1f84f2efbf87947a2037b9804cf9e16247be5c180509cb06a9c3c66229513b8cdcc2e10fa1d8f2f7ed952b91de99375e5939de33665aec909331f8f115
-  data.tar.gz: f871c26bf5da1052474f5317d72788df760f994f3264dbebc6ad35e91b91124088378524b46f4fc50721f6b9442453978018f6c012dd40f55926a66dd516539c
+  metadata.gz: 266406dca2449e15a0d72e4ac315190929aa048d18c6236f07d5eea23d5b220dcc037408edb7f5a2a508e677dee5bbf70bb96b620e1bcdcf75df145623efff9e
+  data.tar.gz: 81fcf78c8ec6234b1478d0c6ca92acdc096bb714de76e33d1bd19bf21e52fce8c0b3831fa72b2e8ec2cbe4dad21d399886cd0e62c416934fd6778ab08d03308d

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         activesupport-version: ['7.2', '8.0']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
@@ -43,7 +43,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -57,7 +57,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - 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@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/security.yml

@@ -8,13 +8,14 @@ on:
   schedule:
     # Run security checks daily at 9 AM UTC
     - cron: '0 9 * * *'
+  workflow_dispatch:
 
 jobs:
   security:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.rubocop.yml

@@ -31,6 +31,12 @@ RSpec/ContextWording:
 RSpec/MultipleExpectations:
   Enabled: false
 
+# Several data-driven specs build examples from collections resolved at
+# definition time (e.g. `legacy.each`, `melodic_guides.each`), which requires
+# those values to live as locals in the example-group scope.
+RSpec/LeakyLocalVariable:
+  Enabled: false
+
 RSpec/NestedGroups:
   Max: 5
 

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.5.0] - 2026-07-21
+
+### Added
+
+- Sung text (lyrics) can be attached to the notes of a voice. `HeadMusic::Content::Placement#sing(text, verse:, hyphen_after:)` assigns a syllable to a placement, keyed by verse so a note carries at most one syllable per verse and any number of verses (`glo` on verse 1, `peace` on verse 2 of the same note). A new immutable `HeadMusic::Content::Syllable` value object stores only the minimal linguistic fact — `text`, `verse`, and a `hyphen_after` boolean marking that the word continues onto the next sung note; the MusicXML `syllabic` value (`single`/`begin`/`middle`/`end`) is derived at render time rather than stored, and a melisma is represented by the absence of a syllable on the held notes rather than a stored flag. Syllables serialize through `Placement#to_h` and round-trip through the composition hash deserializer, validated at the import boundary by `Composition::SchemaValues` (non-empty text, a positive-integer verse, and no duplicate verse per placement).
+- The MusicXML writer emits a `<lyric number="N">` element as the last child of each `<note>`, on the lead note of a chord only and the attack of a tied chain only, deriving `<syllabic>` from the `hyphen_after` booleans of the syllable and its predecessor in the same verse and XML-escaping the text. Held notes of a melisma carry no `<lyric>`, matching MusicXML's continuation-by-absence. ABC `w:` lyric-line input and the MusicXML `<extend/>` melisma line remain out of scope for a future release.
+
+## [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,9 +1,9 @@
 PATH
   remote: .
   specs:
-    head_music (17.3.0)
+    head_music (17.5.0)
       activesupport (>= 7.0, < 10)
-      humanize (~> 2.0)
+      humanize (>= 2, < 4)
       i18n (~> 1.8)
 
 GEM
@@ -30,98 +30,100 @@ GEM
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
-    bigdecimal (3.2.2)
-    bundler-audit (0.9.2)
-      bundler (>= 1.2.0, < 3)
+    bigdecimal (4.1.2)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
       thor (~> 1.0)
     childprocess (5.1.0)
       logger (~> 1.5)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.3.7)
-    connection_pool (2.5.3)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
     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)
+    dry-configurable (1.4.0)
+      dry-core (~> 1.0)
       zeitwerk (~> 2.6)
-    dry-core (1.1.0)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.2.0)
+    dry-inflector (1.3.1)
     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)
+    dry-schema (1.16.0)
       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)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-types (1.8.3)
-      bigdecimal (~> 3.0)
+    dry-types (1.9.1)
+      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)
+    flay (2.14.4)
       erubi (~> 1.10)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.0)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.0)
-    flog (4.8.0)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.1, > 3.1.0)
+    flog (4.9.4)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.8)
-    humanize (2.5.1)
-    i18n (1.14.7)
+    humanize (3.1.0)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     json (2.21.1)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
-    language_server-protocol (3.17.0.5)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    language_server-protocol (3.17.0.6)
     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)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    ostruct (0.6.3)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    path_expander (1.1.3)
-    prism (1.4.0)
-    public_suffix (6.0.2)
+    path_expander (2.0.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.4.2)
     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)
+    regexp_parser (2.12.0)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -129,43 +131,46 @@ GEM
     rspec-its (2.0.0)
       rspec-core (>= 3.13.0)
       rspec-expectations (>= 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.6.0)
+    rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
-    ruby_parser (3.21.1)
+    ruby_parser (3.22.0)
       racc (~> 1.5)
       sexp_processor (~> 4.16)
-    rubycritic (4.11.0)
+    rubycritic (5.0.0)
       flay (~> 2.13)
       flog (~> 4.7)
       launchy (>= 2.5.2)
+      ostruct
       parser (>= 3.3.0.5)
+      prism (>= 1.6.0)
       rainbow (~> 3.1.1)
       reek (~> 6.5.0, < 7.0)
       rexml
@@ -174,40 +179,35 @@ GEM
       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)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    standard (1.50.0)
+    sexp_processor (4.17.5)
+    simplecov (1.0.2)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    thor (1.4.0)
+      rubocop-performance (~> 1.26.0)
+    thor (1.5.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)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     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.44)
-    zeitwerk (2.7.3)
+    yard (0.9.45)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-22

data/head_music.gemspec

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

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