musa-dsl 0.40.0 → 0.42.0

data/lib/musa-dsl/music/chords.rb

@@ -47,13 +47,15 @@ module Musa
     #
     # ### Move - Relocate specific chord tones to different octaves:
     #
-    #     chord.move(root: -1, seventh: 1)
+    #     chord.with_move(root: -1, seventh: 1)
     #     # Root down one octave, seventh up one octave
+    #     chord.move  # => { root: -1, seventh: 1 } (current settings)
     #
     # ### Duplicate - Add copies of chord tones in other octaves:
     #
-    #     chord.duplicate(root: -2, third: [-1, 1])
+    #     chord.with_duplicate(root: -2, third: [-1, 1])
     #     # Add root 2 octaves down, third 1 octave down and 1 up
+    #     chord.duplicate  # => { root: -2, third: [-1, 1] } (current settings)
     #
     # ### Octave - Transpose entire chord:
     #
@@ -90,8 +92,8 @@ module Musa
     # @example Voicing with move and duplicate
     #   scale = Scales::Scales.default_system.default_tuning.major[60]
     #   chord = scale.dominant.chord(:seventh)
-    #     .move(root: -1, third: -1)
-    #     .duplicate(fifth: [0, 1])
+    #     .with_move(root: -1, third: -1)
+    #     .with_duplicate(fifth: [0, 1])
     #
     # @example Feature navigation
     #   scale = Scales::Scales.default_system.default_tuning.major[60]
@@ -194,9 +196,9 @@ module Musa
         # Maps each chord position (root, third, fifth, etc.) to its corresponding
         # note in the scale or chromatic scale.
         #
-        # @param root [NoteInScale] chord root note
+        # @param root [Scales::NoteInScale] chord root note
         # @param chord_definition [ChordDefinition] chord structure
-        # @param scale [Scale] scale context
+        # @param scale [Scales::Scale] scale context
         # @return [Hash{Symbol => Array<NoteInScale>}] position to notes mapping
         #
         # @api private
@@ -214,7 +216,7 @@ module Musa
         #
         # @param root_pitch [Integer] MIDI pitch of chord root
         # @param features [Hash] desired chord features (quality:, size:, etc.)
-        # @param scale [Scale] scale context for diatonic filtering
+        # @param scale [Scales::Scale] scale context for diatonic filtering
         # @param allow_chromatic [Boolean] allow non-diatonic chords
         # @return [ChordDefinition, nil] matching definition or nil
         #
@@ -242,7 +244,7 @@ module Musa
       # @!attribute grade
       #   @return [Symbol] position name (:root, :third, :fifth, etc.)
       # @!attribute note
-      #   @return [NoteInScale] the note at this position
+      #   @return [Scales::NoteInScale] the note at this position
       #
       # @api private
       ChordGradeNote = Struct.new(:grade, :note, keyword_init: true)
@@ -253,8 +255,8 @@ module Musa
       #
       # Use {with_root} or create chords from scale notes instead.
       #
-      # @param root [NoteInScale] chord root note
-      # @param scale [Scale, nil] scale context (nil if chromatic notes present)
+      # @param root [Scales::NoteInScale] chord root note
+      # @param scale [Scales::Scale, nil] scale context (nil if chromatic notes present)
       # @param chord_definition [ChordDefinition] chord structure
       # @param move [Hash, nil] octave moves for positions
       # @param duplicate [Hash, nil] octave duplications for positions
@@ -423,10 +425,10 @@ module Musa
       #   chord.octave(2)
       def octave(octave)
         source_notes_map = @source_notes_map.transform_values do |notes|
-          notes.collect { |note| note.octave(octave) }.freeze
+          notes.collect { |note| note.at_octave(octave) }.freeze
         end.freeze
 
-        Chord.new(@root.octave(octave), @scale, chord_definition, @move, @duplicate, source_notes_map)
+        Chord.new(@root.at_octave(octave), @scale, chord_definition, @move, @duplicate, source_notes_map)
       end
 
       # Creates new chord with positions moved to different octaves.
@@ -439,11 +441,11 @@ module Musa
       # @return [Chord] new chord with moved positions
       #
       # @example Move root down, seventh up
-      #   chord.move(root: -1, seventh: 1)
+      #   chord.with_move(root: -1, seventh: 1)
       #
       # @example Drop voicing (move third and seventh down)
-      #   chord.move(third: -1, seventh: -1)
-      def move(**octaves)
+      #   chord.with_move(third: -1, seventh: -1)
+      def with_move(**octaves)
         Chord.new(@root, @scale, @chord_definition, @move.merge(octaves), @duplicate, @source_notes_map)
       end
 
@@ -457,17 +459,82 @@ module Musa
       # @return [Chord] new chord with duplicated positions
       #
       # @example Duplicate root two octaves down
-      #   chord.duplicate(root: -2)
+      #   chord.with_duplicate(root: -2)
       #
       # @example Duplicate third in multiple octaves
-      #   chord.duplicate(third: [-1, 1])
+      #   chord.with_duplicate(third: [-1, 1])
       #
       # @example Duplicate multiple positions
-      #   chord.duplicate(root: -1, fifth: 1)
-      def duplicate(**octaves)
+      #   chord.with_duplicate(root: -1, fifth: 1)
+      def with_duplicate(**octaves)
         Chord.new(@root, @scale, @chord_definition, @move, @duplicate.merge(octaves), @source_notes_map)
       end
 
+      # Finds this chord in other scales.
+      #
+      # Searches through scale kinds matching the given metadata criteria to find
+      # all scales that contain this chord. Returns new chord instances, each with
+      # its containing scale as context.
+      #
+      # @param roots [Range, Array, nil] pitch offsets to search (default: full octave)
+      # @param metadata [Hash] metadata filters for scale kinds (family:, brightness:, etc.)
+      # @return [Array<Chord>] this chord in different scale contexts
+      #
+      # @example Find G major triad in diatonic scales
+      #   g_triad = c_major.dominant.chord
+      #   g_triad.in_scales(family: :diatonic)
+      #
+      # @example Find chord in scales with specific brightness
+      #   g7.in_scales(brightness: -1..1)
+      #
+      # @example Iterate over results
+      #   g7.in_scales(family: :greek_modes).each do |chord|
+      #     scale = chord.scale
+      #     degree = scale.degree_of_chord(chord)
+      #     puts "#{scale.kind.class.id} on #{scale.root_pitch}: degree #{degree}"
+      #   end
+      #
+      # @see Musa::Scales::Scale#chord_on
+      # @see Musa::Scales::ScaleSystemTuning#search_chord_in_scales
+      def search_in_scales(roots: nil, **metadata)
+        tuning = @scale&.kind&.tuning || @root.scale.kind.tuning
+        tuning.search_chord_in_scales(self, roots: roots, **metadata)
+      end
+
+      # Creates an equivalent chord with the given scale as its context.
+      #
+      # Returns a new Chord object representing the same chord but with
+      # the specified scale as its harmonic context. Returns nil if the
+      # chord is not contained in the scale.
+      #
+      # @param scale [Musa::Scales::Scale] the target scale
+      # @return [Chord, nil] new chord with target scale, or nil if not contained
+      #
+      # @example
+      #   c_major = Scales.et12[440.0].major[60]
+      #   g7 = c_major.dominant.chord :seventh
+      #
+      #   g_mixolydian = Scales.et12[440.0].mixolydian[67]
+      #   g7_in_mixolydian = g7.as_chord_in_scale(g_mixolydian)
+      #   g7_in_mixolydian.scale  # => G Mixolydian scale
+      #
+      # @see #search_in_scales
+      # @see Musa::Scales::Scale#contains_chord?
+      def as_chord_in_scale(scale)
+        return nil unless scale.contains_chord?(self)
+
+        root_note = scale.note_of_pitch(@root.pitch, allow_chromatic: false)
+        return nil unless root_note
+
+        Chord.with_root(
+          root_note,
+          scale: scale,
+          name: @chord_definition.name,
+          move: @move.empty? ? nil : @move,
+          duplicate: @duplicate.empty? ? nil : @duplicate
+        )
+      end
+
       # Checks chord equality.
       #
       # Chords are equal if they have the same notes and chord definition.
@@ -504,12 +571,12 @@ module Musa
         notes_map = notes_map.transform_values(&:dup)
 
         moved&.each do |position, octave|
-          notes_map[position][0] = notes_map[position][0].octave(octave)
+          notes_map[position][0] = notes_map[position][0].at_octave(octave)
         end
 
         duplicated&.each do |position, octave|
           octave.arrayfy.each do |octave|
-            notes_map[position] << notes_map[position][0].octave(octave)
+            notes_map[position] << notes_map[position][0].at_octave(octave)
           end
         end