musa-dsl 0.41.0 → 0.42.0

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

@@ -104,7 +104,7 @@ module Musa
       # Makes the scale system available via symbol lookup and dynamic method.
       # Optionally marks it as the default system.
       #
-      # @param scale_system [Class] the ScaleSystem subclass to register
+      # @param scale_system [Class<ScaleSystem>] the ScaleSystem subclass to register
       # @param default [Boolean] whether to set as default system
       # @return [self]
       #
@@ -126,20 +126,24 @@ module Musa
       # Retrieves a registered scale system by ID.
       #
       # @param id [Symbol] the scale system identifier
-      # @return [Class] the ScaleSystem subclass
+      # @return [Class<ScaleSystem>] the ScaleSystem subclass
       # @raise [KeyError] if scale system not found
       #
       # @example
       #   Scales[:et12]  # => EquallyTempered12ToneScaleSystem
-      def self.[](id)
+      def self.get(id)
         raise KeyError, "Scale system :#{id} not found" unless @scale_systems.key?(id)
 
         @scale_systems[id]
       end
 
+      class << self
+        alias_method :[], :get
+      end
+
       # Returns the default scale system.
       #
-      # @return [Class] the default ScaleSystem subclass
+      # @return [Class<ScaleSystem>] the default ScaleSystem subclass
       #
       # @example
       #   Scales.default_system  # => EquallyTempered12ToneScaleSystem
@@ -319,7 +323,7 @@ module Musa
       #
       # @example Modern high pitch
       #   modern = ScaleSystem[442.0]
-      def self.[](a_frequency)
+      def self.get(a_frequency)
         a_frequency = a_frequency.to_f
 
         @a_tunings ||= {}
@@ -328,6 +332,10 @@ module Musa
         @a_tunings[a_frequency]
       end
 
+      class << self
+        alias_method :[], :get
+      end
+
       # Returns semitone offset for a named interval.
       #
       # @param name [Symbol] interval name (e.g., :M3, :P5)
@@ -351,7 +359,7 @@ module Musa
 
       # Registers a scale kind (major, minor, etc.) with this system.
       #
-      # @param scale_kind_class [Class] ScaleKind subclass to register
+      # @param scale_kind_class [Class<ScaleKind>] ScaleKind subclass to register
       # @return [self]
       #
       # @example
@@ -368,7 +376,7 @@ module Musa
       # Retrieves a registered scale kind by ID.
       #
       # @param id [Symbol] scale kind identifier
-      # @return [Class] ScaleKind subclass
+      # @return [Class<ScaleKind>] ScaleKind subclass
       # @raise [KeyError] if not found
       def self.scale_kind_class(id)
         raise KeyError, "Scale kind class [#{id}] not found in scale system [#{self.id}]" unless @scale_kind_classes.key? id
@@ -393,7 +401,7 @@ module Musa
 
       # Returns the chromatic scale kind class.
       #
-      # @return [Class] chromatic ScaleKind subclass
+      # @return [Class<ScaleKind>] chromatic ScaleKind subclass
       # @raise [RuntimeError] if chromatic scale not defined
       def self.chromatic_class
         raise "Chromatic scale kind class for [#{self.id}] scale system undefined" if @chromatic_scale_kind_class.nil?
@@ -452,6 +460,12 @@ module Musa
     class ScaleSystemTuning
       extend Forwardable
 
+      # Creates a tuning instance for a scale system.
+      #
+      # @param scale_system [Class<ScaleSystem>] the ScaleSystem subclass
+      # @param a_frequency [Numeric] reference A frequency in Hz
+      #
+      # @api private
       def initialize(scale_system, a_frequency)
         @scale_system = scale_system
         @a_frequency = a_frequency
@@ -468,18 +482,75 @@ module Musa
 
       # TODO: allow scales not based in octaves but in other intervals (like fifths or other ratios). Possibly based on intervals definition of ScaleSystem plus a "generator interval" attribute
 
+      # @!method notes_in_octave
+      #   Returns the number of notes in one octave.
+      #   Delegated from {ScaleSystem.notes_in_octave}.
+      #   @return [Integer] notes per octave (e.g., 12 for chromatic)
+
+      # @!method offset_of_interval(name)
+      #   Returns semitone offset for a named interval.
+      #   Delegated from {ScaleSystem.offset_of_interval}.
+      #   @param name [Symbol] interval name (e.g., :M3, :P5)
+      #   @return [Integer] semitone offset
+
       def_delegators :@scale_system, :notes_in_octave, :offset_of_interval
 
-      attr_reader :a_frequency, :scale_system
+      # Reference A frequency in Hz.
+      # @return [Float]
+      attr_reader :a_frequency
+
+      # The parent scale system.
+      # @return [Class<ScaleSystem>] ScaleSystem subclass
+      attr_reader :scale_system
 
-      def [](scale_kind_class_id)
+      # Retrieves a scale kind by ID.
+      #
+      # Creates and caches {ScaleKind} instances for efficient reuse.
+      #
+      # @param scale_kind_class_id [Symbol] scale kind identifier (e.g., :major, :minor)
+      # @return [ScaleKind] scale kind instance
+      # @raise [KeyError] if scale kind not found
+      #
+      # @example
+      #   tuning[:major][60]   # C major scale
+      #   tuning[:minor][69]   # A minor scale
+      #
+      # @see ScaleKind
+      def get(scale_kind_class_id)
         @scale_kinds[scale_kind_class_id] ||= @scale_system.scale_kind_class(scale_kind_class_id).new self
       end
 
+      alias_method :[], :get
+
+      # Returns the chromatic scale kind.
+      #
+      # Provides access to the chromatic scale, which contains all pitches
+      # in the scale system. Used as fallback for non-diatonic notes.
+      #
+      # @return [ScaleKind] chromatic scale kind instance
+      #
+      # @example
+      #   tuning.chromatic[60]   # Chromatic scale at C
+      #
+      # @see ScaleSystem.chromatic_class
       def chromatic
         @chromatic_scale_kind
       end
 
+      # Calculates frequency for a MIDI pitch.
+      #
+      # Delegates to the scale system's frequency calculation using
+      # this tuning's A frequency as reference.
+      #
+      # @param pitch [Numeric] MIDI pitch number (60 = middle C)
+      # @param root [Numeric] root pitch of the scale (for non-equal temperaments)
+      # @return [Float] frequency in Hz
+      #
+      # @example
+      #   tuning.frequency_of_pitch(69, 60)  # => 440.0 (A4)
+      #   tuning.frequency_of_pitch(60, 60)  # => ~261.63 (C4)
+      #
+      # @see ScaleSystem.frequency_of_pitch
       def frequency_of_pitch(pitch, root)
         @scale_system.frequency_of_pitch(pitch, root, @a_frequency)
       end
@@ -492,7 +563,7 @@ module Musa
       #
       # @param metadata_criteria [Hash] metadata key-value pairs to match
       # @yield [kind_class] optional block for custom filtering
-      # @yieldparam kind_class [Class] the ScaleKind subclass
+      # @yieldparam kind_class [Class<ScaleKind>] the ScaleKind subclass
       # @yieldreturn [Boolean] true to include this scale kind
       # @return [Array<ScaleKind>] matching scale kind instances
       #
@@ -543,27 +614,33 @@ module Musa
       # @example Search G7 in greek mode scales
       #   tuning = Scales.et12[440.0]
       #   g7 = tuning.major[60].dominant.chord :seventh
-      #   tuning.chords_of(g7, family: :greek_modes)
+      #   tuning.search_chord_in_scales(g7, family: :greek_modes)
       #
       # @example Search with brightness filter
-      #   tuning.chords_of(g7, brightness: -1..1)
+      #   tuning.search_chord_in_scales(g7, brightness: -1..1)
       #
       # @example Search in all scale types
-      #   tuning.chords_of(g7)
+      #   tuning.search_chord_in_scales(g7)
       #
-      # @see ScaleKind#scales_containing
-      # @see Musa::Chords::Chord#in_scales
-      def chords_of(chord, roots: nil, **metadata_criteria)
+      # @see ScaleKind#find_chord_in_scales
+      # @see Musa::Chords::Chord#search_in_scales
+      def search_chord_in_scales(chord, roots: nil, **metadata_criteria)
         roots ||= 0...notes_in_octave
         kinds = filtered_scale_kind_ids(**metadata_criteria)
 
         kinds.flat_map do |kind_id|
-          self[kind_id].scales_containing(chord, roots: roots)
+          self[kind_id].find_chord_in_scales(chord, roots: roots)
         end
       end
 
       private
 
+      # Returns scale kind IDs filtered by metadata criteria.
+      #
+      # @param metadata_criteria [Hash] key-value pairs to match
+      # @return [Array<Symbol>] matching scale kind IDs
+      #
+      # @api private
       def filtered_scale_kind_ids(**metadata_criteria)
         kinds = @scale_system.scale_kind_classes.keys
 
@@ -575,6 +652,13 @@ module Musa
         end
       end
 
+      # Checks if a scale kind class matches the given criteria.
+      #
+      # @param kind_class [Class<ScaleKind>] ScaleKind subclass to check
+      # @param criteria [Hash] metadata key-value pairs to match
+      # @return [Boolean] true if all criteria match
+      #
+      # @api private
       def matches_metadata?(kind_class, criteria)
         criteria.all? do |key, value|
           actual = kind_class.metadata[key]
@@ -591,12 +675,21 @@ module Musa
 
       public
 
+      # Checks tuning equality.
+      #
+      # Tunings are equal if they have the same scale system and A frequency.
+      #
+      # @param other [ScaleSystemTuning] the tuning to compare
+      # @return [Boolean] true if equal
       def ==(other)
         self.class == other.class &&
             @scale_system == other.scale_system &&
             @a_frequency == other.a_frequency
       end
 
+      # Returns string representation.
+      #
+      # @return [String] human-readable description
       def inspect
         "<ScaleSystemTuning: scale_system = #{@scale_system} a_frequency = #{@a_frequency}>"
       end
@@ -684,11 +777,13 @@ module Musa
       #   major_kind = tuning[:major]
       #   c_major = major_kind[60]     # C major
       #   g_major = major_kind[67]     # G major
-      def [](root_pitch)
+      def get(root_pitch)
         @scales[root_pitch] = Scale.new(self, root_pitch: root_pitch) unless @scales.key?(root_pitch)
         @scales[root_pitch]
       end
 
+      alias_method :[], :get
+
       # Returns scale with default root (middle C, MIDI 60).
       #
       # @return [Scale] scale rooted on middle C
@@ -722,19 +817,19 @@ module Musa
       # @example Find G major triad in all major scales
       #   tuning = Scales.et12[440.0]
       #   g_triad = tuning.major[60].dominant.chord
-      #   tuning.major.scales_containing(g_triad)
+      #   tuning.major.find_chord_in_scales(g_triad)
       #   # => [Chord in C major (V), Chord in G major (I), Chord in D major (IV)]
       #
-      # @see Scale#chord_on
-      # @see ScaleSystemTuning#chords_in_scales
-      def scales_containing(chord, roots: nil)
+      # @see Musa::Chords::Chord#as_chord_in_scale
+      # @see ScaleSystemTuning#search_chord_in_scales
+      def find_chord_in_scales(chord, roots: nil)
         roots ||= 0...tuning.notes_in_octave
         base_pitch = chord.root.pitch % tuning.notes_in_octave
 
         roots.filter_map do |root_offset|
           root_pitch = base_pitch + root_offset
           scale = self[root_pitch]
-          scale.chord_on(chord)
+          chord.as_chord_in_scale(scale)
         end
       end
 
@@ -1091,9 +1186,9 @@ module Musa
     #     scale[:V]     # Fifth degree
     #     scale[:IV]    # Fourth degree
     #
-    # **With accidentals** (sharp # or flat _):
+    # **With accidentals** (sharp # or flat _). Use strings for #:
     #
-    #     scale[:I#]    # Raised tonic
+    #     scale['I#']   # Raised tonic
     #     scale[:V_]    # Flatted dominant
     #     scale['II##'] # Double-raised second
     #
@@ -1120,8 +1215,8 @@ module Musa
     #   c_major.dominant.pitch   # => 67 (G)
     #   c_major[:III].pitch      # => 64 (E)
     #
-    # @example Chromatic alterations
-    #   c_major[:I#].pitch       # => 61 (C#)
+    # @example Chromatic alterations (use strings for #)
+    #   c_major['I#'].pitch      # => 61 (C#)
     #   c_major[:V_].pitch       # => 66 (F#/Gb)
     #
     # @example Building chords
@@ -1156,7 +1251,16 @@ module Musa
         freeze
       end
 
-      # Delegates tuning access to kind.
+      # @!method tuning
+      #   Returns the tuning system associated with this scale.
+      #
+      #   Delegated from ScaleKind#tuning.
+      #
+      #   @return [ScaleSystemTuning] the tuning system used by this scale
+      #
+      #   @example
+      #     scale = Scales.et12[440.0].major[60]
+      #     scale.tuning  # => ScaleSystemTuning for 12-TET at A=440Hz
       def_delegators :@kind, :tuning
 
       # Scale kind (major, minor, etc.).
@@ -1241,11 +1345,11 @@ module Musa
       #   scale[:V]     # Dominant
       #   scale[:IV]    # Subdominant
       #
-      # @example With accidentals
-      #   scale[:I#]     # Raised tonic
+      # @example With accidentals (use strings for #)
+      #   scale['I#']    # Raised tonic
       #   scale[:V_]     # Flatted dominant
       #   scale['II##']  # Double-raised second
-      def [](grade_or_symbol)
+      def get(grade_or_symbol)
 
         raise ArgumentError, "grade_or_symbol '#{grade_or_symbol}' should be a Integer, String or Symbol" unless grade_or_symbol.is_a?(Symbol) || grade_or_symbol.is_a?(String) || grade_or_symbol.is_a?(Integer)
 
@@ -1269,6 +1373,8 @@ module Musa
         @notes_by_grade[wide_grade].sharp(sharps)
       end
 
+      alias_method :[], :get
+
       # Converts grade specifier to numeric grade and accidentals.
       #
       # @param grade_or_string_or_symbol [Integer, Symbol, String] grade specifier
@@ -1431,38 +1537,45 @@ module Musa
         note&.grade
       end
 
-      # Creates an equivalent chord with this scale as its context.
+      # Creates a chord rooted on the specified scale degree.
       #
-      # Returns a new Chord object that represents the same chord but with
-      # this scale as its harmonic context. The chord's voicing (move and
-      # duplicate settings) is preserved.
+      # This is a convenience method that combines scale note access with
+      # chord creation. It's equivalent to `scale[grade].chord(...)`.
       #
-      # @param chord [Musa::Chords::Chord] the source chord
-      # @return [Musa::Chords::Chord, nil] new chord with this scale, or nil if not contained
+      # @param grade [Integer, Symbol, String] scale degree (0-based numeric, function name like :tonic, or Roman numeral like :V)
+      # @param feature_values [Array<Symbol>] chord feature values (:seventh, :major, etc.)
+      # @param allow_chromatic [Boolean] allow non-diatonic chord notes
+      # @param move [Hash{Symbol => Integer}] initial octave moves for chord tones
+      # @param duplicate [Hash{Symbol => Integer, Array}] initial duplications
+      # @param features_hash [Hash] additional feature key-value pairs
+      # @return [Chords::Chord] chord rooted on the specified degree
       #
-      # @example
-      #   c_major = Scales.et12[440.0].major[60]
-      #   g7 = c_major.dominant.chord :seventh
+      # @example Create triads
+      #   scale.chord_on(0)           # Tonic triad (I)
+      #   scale.chord_on(:dominant)   # Dominant triad (V)
+      #   scale.chord_on(:IV)         # Subdominant triad
       #
-      #   g_mixolydian = Scales.et12[440.0].mixolydian[67]
-      #   g7_in_mixolydian = g_mixolydian.chord_on(g7)
-      #   g7_in_mixolydian.scale  # => G Mixolydian scale
+      # @example Create extended chords
+      #   scale.chord_on(4, :seventh)              # V7
+      #   scale.chord_on(:dominant, :ninth)        # V9
+      #   scale.chord_on(0, :seventh, :major)      # Imaj7
       #
-      # @see #contains_chord?
-      # @see #degree_of_chord
-      def chord_on(chord)
-        return nil unless contains_chord?(chord)
-
-        root_note = note_of_pitch(chord.root.pitch, allow_chromatic: false)
-        return nil unless root_note
-
-        Musa::Chords::Chord.with_root(
-          root_note,
-          scale: self,
-          name: chord.chord_definition.name,
-          move: chord.move.empty? ? nil : chord.move,
-          duplicate: chord.duplicate.empty? ? nil : chord.duplicate
-        )
+      # @example With voicing
+      #   scale.chord_on(:I, :seventh, move: {root: -1})
+      #   scale.chord_on(0, :triad, duplicate: {root: 1})
+      #
+      # @see NoteInScale#chord
+      # @see #get
+      def chord_on(grade, *feature_values,
+                   allow_chromatic: nil,
+                   move: nil,
+                   duplicate: nil,
+                   **features_hash)
+        self[grade].chord(*feature_values,
+                          allow_chromatic: allow_chromatic,
+                          move: move,
+                          duplicate: duplicate,
+                          **features_hash)
       end
 
       # Checks scale equality.
@@ -1536,9 +1649,10 @@ module Musa
     #
     # ## Scale Navigation
     #
-    #     note.scale(:minor)     # Same pitch in minor scale
-    #     note.major             # Same pitch in major scale
-    #     note.chromatic         # Same pitch in chromatic scale
+    #     note.scale                  # Parent scale this note belongs to
+    #     note.as_root_of(:minor)     # New minor scale with this pitch as root
+    #     note.minor                  # Same as note.as_root_of(:minor)
+    #     note.chromatic              # Same as note.as_root_of(:chromatic)
     #
     # ## Chord Construction
     #
@@ -1602,7 +1716,7 @@ module Musa
 
         @scale.kind.tuning.scale_system.scale_kind_classes.each_key do |name|
           define_singleton_method name do
-            scale(name)
+            as_root_of(name)
           end
         end
       end
@@ -1625,34 +1739,27 @@ module Musa
         @scale.kind.class.pitches[grade][:functions]
       end
 
-      # Transposes note or returns current octave.
-      #
-      # **Without argument**: Returns current octave relative to scale root.
-      #
-      # **With argument**: Returns note transposed by octave offset.
+      # Current octave relative to scale root.
+      # @return [Integer]
+      attr_reader :octave
+
+      # Returns note transposed by octave offset.
       #
-      # @param octave [Integer, nil] octave offset (nil to query current)
+      # @param offset [Integer] octave offset (positive = up, negative = down)
       # @param absolute [Boolean] if true, ignore current octave
-      # @return [Integer, NoteInScale] current octave or transposed note
-      # @raise [ArgumentError] if octave is not integer
-      #
-      # @example Query octave
-      #   note.octave  # => 0 (at scale root octave)
+      # @return [NoteInScale] transposed note
+      # @raise [ArgumentError] if offset is not integer
       #
       # @example Transpose relative
-      #   note.octave(1).pitch   # Up one octave from current
-      #   note.octave(-1).pitch  # Down one octave from current
+      #   note.at_octave(1).pitch   # Up one octave from current
+      #   note.at_octave(-1).pitch  # Down one octave from current
       #
       # @example Transpose absolute
-      #   note.octave(2, absolute: true).pitch  # At octave 2, regardless of current
-      def octave(octave = nil, absolute: false)
-        if octave.nil?
-          @octave
-        else
-          raise ArgumentError, "#{octave} is not integer" unless octave == octave.to_i
+      #   note.at_octave(2, absolute: true).pitch  # At octave 2, regardless of current
+      def at_octave(offset, absolute: false)
+        raise ArgumentError, "#{offset} is not integer" unless offset == offset.to_i
 
-          @scale[@grade + ((absolute ? 0 : @octave) + octave) * @scale.kind.class.grades]
-        end
+        @scale[@grade + ((absolute ? 0 : @octave) + offset) * @scale.kind.class.grades]
       end
 
       # Creates a copy with background scale context.
@@ -1747,6 +1854,13 @@ module Musa
         end
       end
 
+      # Calculates note at given pitch offset from current note.
+      #
+      # @param in_scale_pitch [Numeric] base pitch
+      # @param sharps [Integer] number of semitones to add (negative for flats)
+      # @return [NoteInScale] resulting note
+      #
+      # @api private
       def calculate_note_of_pitch(in_scale_pitch, sharps)
         pitch = in_scale_pitch + sharps * @scale.kind.tuning.scale_system.part_of_tone_size
 
@@ -1818,33 +1932,31 @@ module Musa
         @scale.kind.tuning.frequency_of_pitch(@pitch, @scale.root_pitch)
       end
 
-      # Changes scale while keeping pitch, or returns current scale.
-      #
-      # **Without argument**: Returns current scale.
-      #
-      # **With argument**: Returns note at same pitch in different scale kind.
+      # Parent scale this note belongs to.
+      # @return [Scale]
+      attr_reader :scale
+
+      # Creates a new scale with this note's pitch as the root.
       #
-      # @param kind_id_or_kind [Symbol, ScaleKind, nil] scale kind or ID
-      # @return [Scale, NoteInScale] current scale or note in new scale
+      # @param kind_id_or_kind [Symbol, ScaleKind] scale kind or ID
+      # @return [Scale] new scale rooted at this pitch
       #
-      # @example Query current scale
-      #   note.scale  # => <Scale: kind = MajorScaleKind ...>
+      # @example Create minor scale from a note
+      #   e = c_major[64]           # E in C major
+      #   e_minor = e.as_root_of(:minor)  # E minor scale
       #
-      # @example Change to minor
-      #   note.scale(:minor)  # Same pitch in minor scale
+      # @example With ScaleKind object
+      #   minor_kind = tuning[:minor]
+      #   e_minor = e.as_root_of(minor_kind)
       #
-      # @example Dynamic method
-      #   note.minor   # Same as note.scale(:minor)
-      #   note.major   # Same as note.scale(:major)
-      def scale(kind_id_or_kind = nil)
-        if kind_id_or_kind.nil?
-          @scale
+      # @example Dynamic method (equivalent)
+      #   note.minor   # Same as note.as_root_of(:minor)
+      #   note.major   # Same as note.as_root_of(:major)
+      def as_root_of(kind_id_or_kind)
+        if kind_id_or_kind.is_a? ScaleKind
+          kind_id_or_kind[@pitch]
         else
-          if kind_id_or_kind.is_a? ScaleKind
-            kind_id_or_kind[@pitch]
-          else
-            @scale.kind.tuning[kind_id_or_kind][@pitch]
-          end
+          @scale.kind.tuning[kind_id_or_kind][@pitch]
         end
       end
 
@@ -1877,7 +1989,7 @@ module Musa
       # @param move [Hash{Symbol => Integer}] initial octave moves
       # @param duplicate [Hash{Symbol => Integer, Array<Integer>}] initial duplications
       # @param features_hash [Hash] feature key-value pairs
-      # @return [Chord] chord rooted on this note
+      # @return [Chords::Chord] chord rooted on this note
       #
       # @example Default triad
       #   note.chord  # Major triad