musa-dsl 0.40.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,26 +126,55 @@ 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
       def self.default_system
         @default_scale_system
       end
+
+      # Convenience method to extend metadata for a scale kind by ID.
+      #
+      # Finds the ScaleKind class by its ID symbol and adds custom metadata to it.
+      # This is a shortcut for accessing the class directly and calling extend_metadata.
+      #
+      # @param scale_kind_id [Symbol] the scale kind identifier (e.g., :major, :dorian)
+      # @param metadata [Hash] key-value pairs to add as custom metadata
+      # @return [Hash] the updated custom_metadata hash
+      # @raise [KeyError] if scale kind not found
+      #
+      # @example
+      #   Scales.extend_metadata(:major, my_tag: :favorite)
+      #   Scales.extend_metadata(:dorian, mood: :nostalgic, suitable_for: [:jazz])
+      #
+      # @see ScaleKind.extend_metadata
+      def self.extend_metadata(scale_kind_id, **metadata)
+        system = default_system
+        raise KeyError, "No default scale system registered" unless system
+
+        klass = system.scale_kind_class(scale_kind_id)
+        raise KeyError, "Scale kind :#{scale_kind_id} not found" unless klass
+
+        klass.extend_metadata(**metadata)
+      end
     end
 
     # Abstract base class for musical scale systems.
@@ -294,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 ||= {}
@@ -303,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)
@@ -326,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
@@ -343,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
@@ -368,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?
@@ -427,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
@@ -443,28 +482,214 @@ 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
 
+      # Returns scale kinds matching the given metadata criteria.
+      #
+      # Without arguments, returns all registered scale kinds.
+      # With keyword arguments, filters by metadata values.
+      # With a block, filters using custom predicate on ScaleKind class.
+      #
+      # @param metadata_criteria [Hash] metadata key-value pairs to match
+      # @yield [kind_class] optional block for custom filtering
+      # @yieldparam kind_class [Class<ScaleKind>] the ScaleKind subclass
+      # @yieldreturn [Boolean] true to include this scale kind
+      # @return [Array<ScaleKind>] matching scale kind instances
+      #
+      # @example All scale kinds
+      #   tuning.scale_kinds
+      #   # => [major_kind, minor_kind, dorian_kind, ...]
+      #
+      # @example Filter by metadata
+      #   tuning.scale_kinds(family: :diatonic)
+      #   tuning.scale_kinds(brightness: -1..1)
+      #   tuning.scale_kinds(character: :jazz)
+      #
+      # @example Filter with block
+      #   tuning.scale_kinds { |klass| klass.intrinsic_metadata[:has_leading_tone] }
+      #
+      # @example Combined
+      #   tuning.scale_kinds(family: :greek_modes) { |klass| klass.metadata[:brightness] < 0 }
+      #
+      # @see ScaleKind.metadata
+      # @see ScaleKind.has_metadata?
+      def scale_kinds(**metadata_criteria, &block)
+        result = @scale_system.scale_kind_classes.keys.map { |id| self[id] }
+
+        unless metadata_criteria.empty?
+          result = result.select do |kind|
+            matches_metadata?(kind.class, metadata_criteria)
+          end
+        end
+
+        if block
+          result = result.select { |kind| block.call(kind.class) }
+        end
+
+        result
+      end
+
+      # Searches for a chord across multiple scale types.
+      #
+      # Iterates through the specified scale kinds and pitch roots to find
+      # all scales that contain the given chord. Returns chords with their
+      # containing scale as context.
+      #
+      # @param chord [Musa::Chords::Chord] the chord to search for
+      # @param roots [Range, Array, nil] pitch offsets to search (default: 0...notes_in_octave)
+      # @param metadata_criteria [Hash] metadata filters for scale kinds
+      # @return [Array<Musa::Chords::Chord>] chords with their containing scales
+      #
+      # @example Search G7 in greek mode scales
+      #   tuning = Scales.et12[440.0]
+      #   g7 = tuning.major[60].dominant.chord :seventh
+      #   tuning.search_chord_in_scales(g7, family: :greek_modes)
+      #
+      # @example Search with brightness filter
+      #   tuning.search_chord_in_scales(g7, brightness: -1..1)
+      #
+      # @example Search in all scale types
+      #   tuning.search_chord_in_scales(g7)
+      #
+      # @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].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
+
+        return kinds if metadata_criteria.empty?
+
+        kinds.select do |kind_id|
+          kind_class = @scale_system.scale_kind_class(kind_id)
+          matches_metadata?(kind_class, metadata_criteria)
+        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]
+          case value
+          when Range
+            actual.is_a?(Numeric) && value.include?(actual)
+          when Array
+            value.any? { |v| actual == v || (actual.is_a?(Array) && actual.include?(v)) }
+          else
+            actual == value || (actual.is_a?(Array) && actual.include?(value))
+          end
+        end
+      end
+
+      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
@@ -552,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
@@ -577,6 +804,35 @@ module Musa
         self[0]
       end
 
+      # Finds all scales of this kind that contain the given chord.
+      #
+      # Searches through scales rooted on different pitches to find which ones
+      # contain all the notes of the given chord. Returns chords with their
+      # containing scale as context.
+      #
+      # @param chord [Musa::Chords::Chord] the chord to search for
+      # @param roots [Range, Array, nil] pitch offsets to search (default: 0...notes_in_octave)
+      # @return [Array<Musa::Chords::Chord>] chords with their containing scales
+      #
+      # @example Find G major triad in all major scales
+      #   tuning = Scales.et12[440.0]
+      #   g_triad = tuning.major[60].dominant.chord
+      #   tuning.major.find_chord_in_scales(g_triad)
+      #   # => [Chord in C major (V), Chord in G major (I), Chord in D major (IV)]
+      #
+      # @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]
+          chord.as_chord_in_scale(scale)
+        end
+      end
+
       # Checks scale kind equality.
       #
       # @param other [ScaleKind]
@@ -685,8 +941,200 @@ module Musa
         @grade_names_index.keys
       end
 
+      # Returns intrinsic metadata derived from scale structure.
+      #
+      # This metadata is automatically calculated from the scale's pitch
+      # structure and cannot be modified. It includes:
+      #
+      # - **:id**: Scale kind identifier
+      # - **:grades**: Number of diatonic degrees
+      # - **:pitches**: Array of pitch offsets from root
+      # - **:intervals**: Intervals between consecutive degrees
+      # - **:has_leading_tone**: Whether scale has pitch 11 (semitone below octave)
+      # - **:has_tritone**: Whether scale contains tritone (pitch 6)
+      # - **:symmetric**: Type of symmetry if any (:equal, :palindrome, :repeating)
+      #
+      # @return [Hash] intrinsic metadata derived from structure
+      #
+      # @example
+      #   MajorScaleKind.intrinsic_metadata
+      #   # => { id: :major, grades: 7, pitches: [0, 2, 4, 5, 7, 9, 11],
+      #   #      intervals: [2, 2, 1, 2, 2, 2], has_leading_tone: true,
+      #   #      has_tritone: true, symmetric: nil }
+      def self.intrinsic_metadata
+        result = {}
+        result[:id] = id if respond_to?(:id)
+        result[:grades] = grades if respond_to?(:grades)
+        if respond_to?(:pitches)
+          result[:pitches] = pitches.map { |p| p[:pitch] }
+          result[:intervals] = compute_intervals
+          result[:has_leading_tone] = pitches.any? { |p| p[:pitch] == 11 }
+          result[:has_tritone] = pitches.any? { |p| p[:pitch] == 6 }
+          result[:symmetric] = compute_symmetry
+        end
+        result.compact
+      end
+
+      # Returns base metadata defined by the musa-dsl library.
+      #
+      # This metadata is defined in each ScaleKind subclass using the
+      # `@base_metadata` class instance variable. It typically includes:
+      #
+      # - **:family**: Scale family (:diatonic, :greek_modes, :pentatonic, etc.)
+      # - **:brightness**: Relative brightness (-3 to +3, major = 0)
+      # - **:character**: Array of descriptive tags
+      # - **:parent**: Parent scale and degree for modes
+      #
+      # @return [Hash] library-defined metadata
+      #
+      # @example
+      #   MajorScaleKind.base_metadata
+      #   # => { family: :diatonic, brightness: 0, character: [:bright, :stable] }
+      def self.base_metadata
+        @base_metadata || {}
+      end
+
+      # Returns custom metadata added by users at runtime.
+      #
+      # This metadata is added via {.extend_metadata} and can be cleared
+      # with {.reset_custom_metadata}. Takes precedence over base_metadata.
+      #
+      # @return [Hash] user-defined metadata
+      #
+      # @example
+      #   MajorScaleKind.extend_metadata(my_tag: :favorite)
+      #   MajorScaleKind.custom_metadata  # => { my_tag: :favorite }
+      def self.custom_metadata
+        @custom_metadata || {}
+      end
+
+      # Adds custom metadata to this scale kind.
+      #
+      # Custom metadata takes precedence over base_metadata when queried
+      # via {.metadata}. Multiple calls merge metadata together.
+      #
+      # @param metadata [Hash] key-value pairs to add
+      # @return [Hash] the updated custom_metadata hash (frozen)
+      #
+      # @example
+      #   MajorScaleKind.extend_metadata(my_mood: :happy, rating: 5)
+      #   MajorScaleKind.extend_metadata(suitable_for: [:pop, :classical])
+      #   MajorScaleKind.custom_metadata
+      #   # => { my_mood: :happy, rating: 5, suitable_for: [:pop, :classical] }
+      def self.extend_metadata(**metadata)
+        @custom_metadata ||= {}
+        @custom_metadata = @custom_metadata.merge(metadata).freeze
+      end
+
+      # Clears all custom metadata from this scale kind.
+      #
+      # @return [nil]
+      #
+      # @example
+      #   MajorScaleKind.extend_metadata(temp: :data)
+      #   MajorScaleKind.reset_custom_metadata
+      #   MajorScaleKind.custom_metadata  # => {}
+      def self.reset_custom_metadata
+        @custom_metadata = nil
+      end
+
+      # Returns combined metadata from all three layers.
+      #
+      # Layers are merged with later layers taking precedence:
+      # intrinsic_metadata < base_metadata < custom_metadata
+      #
+      # @return [Hash] combined metadata from all layers
+      #
+      # @example
+      #   MajorScaleKind.metadata
+      #   # => { id: :major, grades: 7, pitches: [...], family: :diatonic, ... }
+      def self.metadata
+        intrinsic_metadata
+          .merge(base_metadata)
+          .merge(custom_metadata)
+      end
+
+      # Returns a specific metadata value.
+      #
+      # @param key [Symbol] the metadata key
+      # @return [Object, nil] the value or nil if not found
+      #
+      # @example
+      #   MajorScaleKind.metadata_value(:family)  # => :diatonic
+      def self.metadata_value(key)
+        metadata[key]
+      end
+
+      # Checks whether metadata contains a key or key-value match.
+      #
+      # When called with just a key, checks for key existence.
+      # When called with key and value, checks for exact match or
+      # array inclusion (if metadata value is an array).
+      #
+      # @param key [Symbol] the metadata key
+      # @param value [Object, nil] optional value to match
+      # @return [Boolean] whether the condition is satisfied
+      #
+      # @example Key existence
+      #   MajorScaleKind.has_metadata?(:family)  # => true
+      #   MajorScaleKind.has_metadata?(:nonexistent)  # => false
+      #
+      # @example Value matching
+      #   MajorScaleKind.has_metadata?(:family, :diatonic)  # => true
+      #   MajorScaleKind.has_metadata?(:family, :pentatonic)  # => false
+      #
+      # @example Array inclusion
+      #   MajorScaleKind.has_metadata?(:character, :bright)  # => true
+      def self.has_metadata?(key, value = nil)
+        if value.nil?
+          metadata.key?(key)
+        else
+          metadata[key] == value ||
+            (metadata[key].is_a?(Array) && metadata[key].include?(value))
+        end
+      end
+
       private
 
+      # Computes intervals between consecutive scale degrees.
+      # @return [Array<Integer>, nil] intervals or nil if not calculable
+      # @api private
+      def self.compute_intervals
+        return nil unless respond_to?(:pitches) && pitches.size > 1
+        pitch_values = pitches.map { |p| p[:pitch] }
+        # Only compute within first octave
+        first_octave = pitch_values.take_while { |p| p < 12 }
+        first_octave.push(12) if first_octave.last != 12
+        first_octave.each_cons(2).map { |a, b| b - a }
+      end
+
+      # Computes symmetry type of the scale.
+      # @return [Symbol, nil] :equal, :palindrome, :repeating, or nil
+      # @api private
+      def self.compute_symmetry
+        return nil unless respond_to?(:pitches)
+        intervals = compute_intervals
+        return nil unless intervals && intervals.any?
+
+        # Check if intervals are all equal (e.g., whole tone: [2,2,2,2,2,2])
+        return :equal if intervals.uniq.size == 1
+
+        # Check for palindrome pattern
+        return :palindrome if intervals == intervals.reverse
+
+        # Check for repeating pattern
+        (1..intervals.size / 2).each do |len|
+          pattern = intervals.take(len)
+          if intervals.each_slice(len).all? { |slice| slice == pattern || slice.size < len }
+            return :repeating
+          end
+        end
+
+        nil
+      end
+
+      public
+
       # Creates internal index mapping function names to grade indices.
       #
       # @return [self]
@@ -738,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
     #
@@ -767,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
@@ -803,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.).
@@ -888,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)
 
@@ -916,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
@@ -1038,6 +1497,87 @@ module Musa
         @kind.tuning.offset_of_interval(interval_name)
       end
 
+      # Checks if all chord pitches exist in this scale.
+      #
+      # Uses the chord's definition to verify that every pitch in the chord
+      # can be found as a diatonic note in this scale.
+      #
+      # @param chord [Musa::Chords::Chord] the chord to check
+      # @return [Boolean] true if all chord notes are in scale
+      #
+      # @example
+      #   c_major = Scales.et12[440.0].major[60]
+      #   g7 = c_major.dominant.chord :seventh
+      #   c_major.contains_chord?(g7)  # => true
+      #
+      #   cm = c_major.tonic.chord.with_quality(:minor)
+      #   c_major.contains_chord?(cm)  # => false (Eb not in C major)
+      #
+      # @see #degree_of_chord
+      # @see #chord_on
+      def contains_chord?(chord)
+        chord.chord_definition.in_scale?(self, chord_root_pitch: chord.root.pitch)
+      end
+
+      # Returns the grade (0-based) where the chord root falls in this scale.
+      #
+      # @param chord [Musa::Chords::Chord] the chord to check
+      # @return [Integer, nil] grade (0-based) or nil if chord not in scale
+      #
+      # @example
+      #   c_major = Scales.et12[440.0].major[60]
+      #   g_chord = c_major.dominant.chord
+      #   c_major.degree_of_chord(g_chord)  # => 4 (V degree, 0-based)
+      #
+      # @see #contains_chord?
+      def degree_of_chord(chord)
+        return nil unless contains_chord?(chord)
+
+        note = note_of_pitch(chord.root.pitch, allow_chromatic: false)
+        note&.grade
+      end
+
+      # Creates a chord rooted on the specified scale degree.
+      #
+      # This is a convenience method that combines scale note access with
+      # chord creation. It's equivalent to `scale[grade].chord(...)`.
+      #
+      # @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 Create triads
+      #   scale.chord_on(0)           # Tonic triad (I)
+      #   scale.chord_on(:dominant)   # Dominant triad (V)
+      #   scale.chord_on(:IV)         # Subdominant triad
+      #
+      # @example Create extended chords
+      #   scale.chord_on(4, :seventh)              # V7
+      #   scale.chord_on(:dominant, :ninth)        # V9
+      #   scale.chord_on(0, :seventh, :major)      # Imaj7
+      #
+      # @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.
       #
       # Scales are equal if they have same kind and root pitch.
@@ -1109,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
     #
@@ -1175,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
@@ -1198,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.
@@ -1320,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
 
@@ -1391,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
 
@@ -1450,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