musa-dsl 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603ecc3ddd2b6bcead498e08a747035df5ff2c2e87e4f527c66c48d5631ab435
-  data.tar.gz: 37dde89a2c5ff9dda9691ff245fa06b4e870475fb7320ef10bca5ef0a7a84ed2
+  metadata.gz: 2a2ee1f86c7d0b4a6c6ecb95b92ea4b15ead3a305c9c6252ea74eb1d437b16fb
+  data.tar.gz: 07fea02dd0fe457b16c79e18eb82fedb0236c929fa3d1b1e3b32b621d419e6f7
 SHA512:
-  metadata.gz: 8b1bd0544fd6b6fe611718809e50422e3accf376e88da0832e7b22b7f5b279eb52d9cab2fe3c3f75d2e996e17f0c1a604a2e56676249c946dae533988db8a54c
-  data.tar.gz: 4c4dbcbfb7243f751205f275eaba483e8d29ce3ca5f59e600a1b8be9d1687c0815572916415b4dfbb0ac14ae7f2bbaec3ee610af2922fe8ab9de42e4ab3a04b2
+  metadata.gz: 0f186d4ac7ee38fb1984a7737e220c25a12411b104728181854898580a7059f87efc6828a769bee268695cb80d3d2818b6dadc0e21a4a1a3a57c853c7502817c
+  data.tar.gz: 84bf07953180497c334da1d471067a4561957da58a9aac4fe454bbfac364f4c44295e1e12e7ad935ca04f3e304e248fe9d89f2d866aaed9c62d87634d2fcbe15

data/.gitignore

@@ -12,3 +12,5 @@ test.musicxml
 doc
 .yardoc
 *.backup
+.vscode
+.ruby-lsp

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-gem 'rubocop', group: 'development'

data/docs/subsystems/music.md

@@ -20,10 +20,54 @@ The **Scales** module provides hierarchical access to musical scales with multip
 - `:et12` (EquallyTempered12ToneScaleSystem): 12-tone equal temperament (default)
 
 **Available scale kinds in et12:**
-- `:major` - Major scale (Ionian mode)
-- `:minor` - Natural minor scale (Aeolian mode)
-- `:minor_harmonic` - Harmonic minor scale (raised 7th degree)
-- `:chromatic` - Chromatic scale (all 12 semitones)
+
+*Core scales:*
+- `:major` - Major scale (Ionian mode) - 7 notes
+- `:minor` - Natural minor scale (Aeolian mode) - 7 notes
+- `:minor_harmonic` - Harmonic minor scale (raised 7th) - 7 notes
+- `:major_harmonic` - Harmonic major scale (lowered 6th) - 7 notes
+- `:chromatic` - Chromatic scale (all 12 semitones) - 12 notes
+
+*Greek/church modes:*
+- `:dorian` - Dorian mode (minor with major 6th) - 7 notes
+- `:phrygian` - Phrygian mode (minor with minor 2nd) - 7 notes
+- `:lydian` - Lydian mode (major with augmented 4th) - 7 notes
+- `:mixolydian` - Mixolydian mode (major with minor 7th) - 7 notes
+- `:locrian` - Locrian mode (diminished 5th and minor 2nd) - 7 notes
+
+*Pentatonic scales:*
+- `:pentatonic_major` - Major pentatonic (no 4th or 7th) - 5 notes
+- `:pentatonic_minor` - Minor pentatonic (no 2nd or 6th) - 5 notes
+
+*Blues scales:*
+- `:blues` - Blues scale (minor pentatonic + b5 blue note) - 6 notes
+- `:blues_major` - Major blues scale (major pentatonic + b3 blue note) - 6 notes
+
+*Symmetric scales:*
+- `:whole_tone` - Whole tone scale (all whole steps) - 6 notes
+- `:diminished_hw` - Diminished half-whole (octatonic) - 8 notes
+- `:diminished_wh` - Diminished whole-half (dominant diminished) - 8 notes
+
+*Melodic minor modes:*
+- `:minor_melodic` - Melodic minor (jazz minor) - 7 notes
+- `:dorian_b2` - Dorian b2 / Phrygian #6 - 7 notes
+- `:lydian_augmented` - Lydian augmented (#4, #5) - 7 notes
+- `:lydian_dominant` - Lydian dominant / Bartók scale (#4, b7) - 7 notes
+- `:mixolydian_b6` - Mixolydian b6 / Hindu scale - 7 notes
+- `:locrian_sharp2` - Locrian #2 / Half-diminished scale - 7 notes
+- `:altered` - Altered / Super Locrian (all tensions altered) - 7 notes
+
+*Ethnic/exotic scales:*
+- `:double_harmonic` - Double harmonic / Byzantine (two augmented 2nds) - 7 notes
+- `:hungarian_minor` - Hungarian minor / Gypsy minor (#4, raised 7th) - 7 notes
+- `:phrygian_dominant` - Phrygian dominant / Spanish Phrygian (b2, major 3rd) - 7 notes
+- `:neapolitan_minor` - Neapolitan minor (harmonic minor with b2) - 7 notes
+- `:neapolitan_major` - Neapolitan major (melodic minor with b2) - 7 notes
+
+*Bebop scales:*
+- `:bebop_dominant` - Bebop dominant (Mixolydian + major 7th passing) - 8 notes
+- `:bebop_major` - Bebop major (major + #5 passing) - 8 notes
+- `:bebop_minor` - Bebop minor (Dorian + major 7th passing) - 8 notes
 
 ## Chords System
 
@@ -93,6 +137,49 @@ third_up = c_major.tonic.sharp(4)  # => E (+4 semitones = major third)
 # Frequency calculation
 frequency = c_major.tonic.frequency  # => 261.63 Hz (middle C at A=440)
 
+# Greek modes (church modes)
+d_dorian = tuning.dorian[62]         # D Dorian (minor with major 6th)
+e_phrygian = tuning.phrygian[64]     # E Phrygian (minor with minor 2nd)
+f_lydian = tuning.lydian[65]         # F Lydian (major with augmented 4th)
+g_mixolydian = tuning.mixolydian[67] # G Mixolydian (major with minor 7th)
+b_locrian = tuning.locrian[71]       # B Locrian (diminished 5th)
+
+# Access notes in Greek modes by function
+d_dorian.tonic.pitch      # => 62 (D)
+d_dorian[:vi].pitch       # => 71 (B - the major 6th characteristic of Dorian)
+
+e_phrygian[:ii].pitch     # => 65 (F - the minor 2nd characteristic of Phrygian)
+
+f_lydian[:IV].pitch       # => 71 (B - the augmented 4th characteristic of Lydian)
+
+g_mixolydian[:VII].pitch  # => 77 (F - the minor 7th characteristic of Mixolydian)
+
+b_locrian[:v].pitch       # => 77 (F - the diminished 5th characteristic of Locrian)
+
+# Pentatonic and blues scales
+c_pent_maj = tuning.pentatonic_major[60]  # C major pentatonic
+a_pent_min = tuning.pentatonic_minor[69]  # A minor pentatonic
+a_blues = tuning.blues[69]                 # A blues scale
+a_blues[:blue].pitch  # => 75 (Eb - the blue note)
+
+# Symmetric scales
+c_whole = tuning.whole_tone[60]      # C whole tone
+c_dim_hw = tuning.diminished_hw[60]  # C diminished (half-whole)
+c_dim_wh = tuning.diminished_wh[60]  # C diminished (whole-half)
+
+# Melodic minor modes
+c_mel_min = tuning.minor_melodic[60]     # C melodic minor
+g_altered = tuning.altered[67]            # G altered (for G7alt chords)
+f_lyd_dom = tuning.lydian_dominant[65]   # F lydian dominant (F7#11)
+
+# Ethnic scales
+e_phry_dom = tuning.phrygian_dominant[64]  # E Phrygian dominant (flamenco)
+a_hung_min = tuning.hungarian_minor[69]    # A Hungarian minor
+
+# Bebop scales (8 notes for smooth eighth-note lines)
+g_bebop = tuning.bebop_dominant[67]  # G bebop dominant
+g_bebop[7].pitch  # => 78 (F# - the chromatic passing tone)
+
 # Create chords from scale degrees
 i_chord = c_major.tonic.chord        # C major triad [C, E, G]
 ii_chord = c_major.supertonic.chord  # D minor triad [D, F, A]
@@ -133,6 +220,230 @@ doubled = i_chord.duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 do
 lower = i_chord.octave(-1)  # Move chord down one octave
 ```
 
+### Chord-Scale Navigation
+
+MusaDSL provides methods to explore the relationship between chords and scales,
+enabling harmonic analysis and discovery of functional contexts.
+
+#### Checking if a Scale Contains a Chord
+
+```ruby
+c_major = Scales.et12[440.0].major[60]
+g7 = c_major.dominant.chord :seventh
+
+c_major.contains_chord?(g7)     # => true
+c_major.degree_of_chord(g7)     # => 4 (V degree, 0-based)
+
+# Non-diatonic chords return false/nil
+cm = c_major.tonic.chord.with_quality(:minor)  # C minor (Eb not in C major)
+c_major.contains_chord?(cm)     # => false
+c_major.degree_of_chord(cm)     # => nil
+```
+
+#### Creating a Chord in a Different Scale Context
+
+```ruby
+# Get the same chord but with a different scale as context
+g_mixolydian = Scales.et12[440.0].mixolydian[67]
+g7_in_mixolydian = g_mixolydian.chord_on(g7)
+g7_in_mixolydian.scale                        # => G Mixolydian scale
+g_mixolydian.degree_of_chord(g7_in_mixolydian)  # => 0 (I degree)
+```
+
+#### Finding Scales That Contain a Chord
+
+```ruby
+g_triad = c_major.dominant.chord  # G-B-D
+
+# Search in diatonic scales
+g_triad.in_scales(family: :diatonic)
+# => [Chord in C major (V), Chord in G major (I), Chord in D major (IV), ...]
+
+# Search using metadata filters
+g_triad.in_scales(family: :greek_modes, brightness: -1..1)
+
+# Search in all scale types
+g_triad.in_scales
+
+# Each result has its scale context
+g_triad.in_scales(family: :diatonic).each do |chord|
+  scale = chord.scale
+  degree = scale.degree_of_chord(chord)
+  puts "#{scale.kind.class.id} rooted on #{scale.root_pitch}: degree #{degree}"
+end
+# Output:
+# major rooted on 60: degree 4
+# major rooted on 67: degree 0
+# major rooted on 62: degree 3
+```
+
+#### Low-Level Navigation Methods
+
+```ruby
+tuning = Scales.et12[440.0]
+
+# Search at ScaleKind level
+tuning.major.scales_containing(g_triad)
+
+# Search at ScaleSystemTuning level with metadata filters
+tuning.chords_of(g7, family: :diatonic, roots: 60..71)
+```
+
+### Scale Kind Metadata
+
+Scale kinds in MusaDSL have a three-layer metadata system that provides
+both automatic structural information and extensible custom properties.
+
+#### Metadata Layers
+
+1. **Intrinsic metadata**: Automatically derived from scale structure
+   - `id`: Scale kind identifier
+   - `grades`: Number of scale 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 interval (pitch 6)
+   - `symmetric`: Type of symmetry if any (`:equal`, `:palindrome`, `:repeating`)
+
+2. **Base metadata**: Defined by musa-dsl library
+   - `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 (e.g., `{ scale: :major, degree: 2 }`)
+
+3. **Custom metadata**: Added by users at runtime
+
+#### Accessing Metadata
+
+```ruby
+tuning = Scales.et12[440.0]
+major_class = tuning.major.class
+
+# Get combined metadata (intrinsic < base < custom)
+major_class.metadata
+# => { id: :major, grades: 7, pitches: [0,2,4,5,7,9,11], family: :diatonic, ... }
+
+# Get specific layer
+major_class.intrinsic_metadata  # Structure-derived only
+major_class.base_metadata       # Library-defined only
+major_class.custom_metadata     # User-added only
+
+# Query helpers
+major_class.has_metadata?(:family)              # => true
+major_class.has_metadata?(:family, :diatonic)   # => true
+major_class.has_metadata?(:character, :bright)  # => true (array inclusion)
+major_class.metadata_value(:brightness)         # => 0
+```
+
+#### Extending Metadata
+
+Users can add custom metadata to any scale kind:
+
+```ruby
+# Extend a specific scale kind class
+tuning.dorian.class.extend_metadata(
+  my_mood: :nostalgic,
+  suitable_for: [:jazz, :fusion],
+  personal_rating: 5
+)
+
+# Or use the convenience method with scale ID
+Scales.extend_metadata(:dorian, my_mood: :nostalgic)
+
+# Multiple calls merge metadata
+Scales.extend_metadata(:phrygian, mood: :dark)
+Scales.extend_metadata(:phrygian, origin: :spanish)  # Merges with previous
+
+# Reset custom metadata if needed
+tuning.dorian.class.reset_custom_metadata
+```
+
+#### Custom Metadata Overrides
+
+Custom metadata takes precedence over base metadata:
+
+```ruby
+# Override library-defined family
+Scales.extend_metadata(:dorian, family: :my_custom_category)
+tuning.dorian.class.metadata[:family]  # => :my_custom_category
+```
+
+#### Brightness Scale Reference
+
+| Value | Meaning | Examples |
+|-------|---------|----------|
+| +3 | Very bright | Lydian augmented |
+| +2 | Bright | Lydian |
+| +1 | Slightly bright | Mixolydian, Lydian dominant |
+| 0 | Neutral (reference) | Major (Ionian) |
+| -1 | Slightly dark | Dorian |
+| -2 | Dark | Minor harmonic, Phrygian |
+| -3 | Very dark | Locrian, Natural minor |
+
+#### Scale Families
+
+- `:diatonic` - Major, minor natural, minor harmonic
+- `:greek_modes` - Dorian, Phrygian, Lydian, Mixolydian, Locrian
+- `:melodic_minor_modes` - Melodic minor and its modes
+- `:pentatonic` - Pentatonic major/minor
+- `:blues` - Blues scales
+- `:bebop` - Bebop scales
+- `:symmetric` - Whole tone, diminished
+- `:ethnic` - Hungarian, Spanish, Neapolitan, etc.
+- `:chromatic` - Chromatic scale
+
+### Searching Scale Kinds
+
+The `scale_kinds` method on ScaleSystemTuning allows searching and filtering
+scale kinds by their metadata properties.
+
+#### Basic Usage
+
+```ruby
+tuning = Scales.et12[440.0]
+
+# Get all scale kinds
+tuning.scale_kinds
+# => [major_kind, minor_kind, dorian_kind, ...]
+
+# Filter by family
+tuning.scale_kinds(family: :diatonic)
+# => [major_kind, minor_kind, minor_harmonic_kind, harmonic_major_kind]
+
+# Filter by brightness range
+tuning.scale_kinds(brightness: -1..1)
+
+# Filter by character
+tuning.scale_kinds(character: :jazz)
+```
+
+#### Custom Filtering with Blocks
+
+Use a block for complex filtering based on any metadata:
+
+```ruby
+# Scales with leading tone
+tuning.scale_kinds { |klass| klass.intrinsic_metadata[:has_leading_tone] }
+
+# Combine criteria and block
+tuning.scale_kinds(family: :greek_modes) { |klass| klass.metadata[:brightness]&.negative? }
+# => [dorian_kind, phrygian_kind, locrian_kind]
+```
+
+#### Integration with Chord Search
+
+The `chords_of` method uses the same metadata filtering:
+
+```ruby
+g7 = tuning.major[60].dominant.chord(:seventh)
+
+# Find G7 in diatonic scales
+tuning.chords_of(g7, family: :diatonic)
+
+# Find G7 in scales with specific brightness
+tuning.chords_of(g7, brightness: -1..1)
+```
+
 ## Defining Custom Scale Systems, Scale Kinds, and Chord Definitions
 
 The framework is extensible, allowing users to define custom tuning systems, scale types, and chord structures:
@@ -173,19 +484,19 @@ require 'musa-dsl'
 include Musa::Scales
 include Musa::Chords
 
-# Example 1: Define a custom pentatonic scale kind for the 12-tone system
-class PentatonicMajorScaleKind < ScaleKind
+# Example 1: Define a custom Hirajoshi scale (Japanese pentatonic)
+class HirajoshiScaleKind < ScaleKind
   class << self
     def id
-      :pentatonic_major
+      :hirajoshi
     end
 
     def pitches
       [{ functions: [:I, :_1, :tonic], pitch: 0 },
        { functions: [:II, :_2], pitch: 2 },
-       { functions: [:III, :_3], pitch: 4 },
-       { functions: [:V, :_5], pitch: 7 },
-       { functions: [:VI, :_6], pitch: 9 }]
+       { functions: [:III, :_3], pitch: 3 },
+       { functions: [:V, :_4], pitch: 7 },
+       { functions: [:VI, :_5], pitch: 8 }]
     end
 
     def grades
@@ -195,14 +506,14 @@ class PentatonicMajorScaleKind < ScaleKind
 end
 
 # Register the new scale kind with the 12-tone system
-Scales.et12.register(PentatonicMajorScaleKind)
+Scales.et12.register(HirajoshiScaleKind)
 
 # Use the new scale kind
 tuning = Scales.default_system.default_tuning
-c_pentatonic = tuning[:pentatonic_major][60]  # C pentatonic major
-puts c_pentatonic[0].pitch  # => 60 (C)
-puts c_pentatonic[1].pitch  # => 62 (D)
-puts c_pentatonic[2].pitch  # => 64 (E)
+c_hirajoshi = tuning[:hirajoshi][60]  # C Hirajoshi
+puts c_hirajoshi[0].pitch  # => 60 (C)
+puts c_hirajoshi[1].pitch  # => 62 (D)
+puts c_hirajoshi[2].pitch  # => 63 (Eb)
 
 # Example 2: Register a custom chord definition (sus4)
 Musa::Chords::ChordDefinition.register :sus4,

data/lib/musa-dsl/generative/darwin.rb

@@ -104,6 +104,8 @@ module Musa
       #     measures { |obj| dimension :value, obj[:score] }
       #     weight value: 1.0
       #   end
+      #
+      # @return [void]
       def initialize(&block)
         raise ArgumentError, 'block is needed' unless block
 
@@ -175,6 +177,14 @@ module Musa
         measured_objects.collect { |measured_object| measured_object[:object] }
       end
 
+      # Compares two measures by their weighted fitness.
+      #
+      # @param measure_a [Measure] first measure to compare
+      # @param measure_b [Measure] second measure to compare
+      #
+      # @return [Integer] comparison result (-1, 0, 1)
+      #
+      # @api private
       def evaluate_weights(measure_a, measure_b)
         measure_b.evaluate_weight(@weights) <=> measure_a.evaluate_weight(@weights)
       end
@@ -189,6 +199,7 @@ module Musa
         # @return [Hash] weight assignments
         attr_reader :_measures, :_weights
 
+        # @return [void]
         # @api private
         def initialize(&block)
           @_weights = {}
@@ -198,6 +209,9 @@ module Musa
         # Defines measures evaluation block.
         #
         # @yield [object] measures DSL block
+        #
+        # @return [Proc] the measures block
+        #
         # @api private
         def measures(&block)
           @_measures = block
@@ -205,7 +219,10 @@ module Musa
 
         # Assigns weights to features/dimensions.
         #
-        # @param feature_or_dimension_weights [Hash] name => weight pairs
+        # @param feature_or_dimension_weights [Hash{Symbol => Numeric}] name => weight pairs
+        #
+        # @return [void]
+        #
         # @api private
         def weight(**feature_or_dimension_weights)
           feature_or_dimension_weights.each do |name, value|
@@ -220,6 +237,7 @@ module Musa
       class MeasuresEvalContext
         include Musa::Extension::With
 
+        # @return [void]
         # @api private
         def initialize
           @_features = {}
@@ -238,6 +256,9 @@ module Musa
         # Marks object as having a feature.
         #
         # @param feature_name [Symbol] feature identifier
+        #
+        # @return [void]
+        #
         # @api private
         def feature(feature_name)
           @_features[feature_name] = true
@@ -247,6 +268,9 @@ module Musa
         #
         # @param dimension_name [Symbol] dimension identifier
         # @param value [Numeric] measured value
+        #
+        # @return [void]
+        #
         # @api private
         def dimension(dimension_name, value)
           @_dimensions[dimension_name] = value
@@ -254,6 +278,8 @@ module Musa
 
         # Marks object as non-viable (to be excluded).
         #
+        # @return [void]
+        #
         # @api private
         def die
           @_died = true
@@ -280,6 +306,12 @@ module Musa
       class Measure
         attr_reader :features, :dimensions, :normalized_dimensions
 
+        # @param features [Hash{Symbol => Boolean}] feature flags
+        # @param dimensions [Hash{Symbol => Numeric}] dimension values
+        # @param died [Boolean] viability status
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(features, dimensions, died)
           @features = features
@@ -319,6 +351,9 @@ module Musa
           total
         end
 
+        # Returns string representation of measure.
+        #
+        # @return [String] formatted measure description
         def inspect
           "Measure features=#{@features.collect { |k, _v| k }} dimensions=#{@normalized_dimensions.collect { |k, v| [k, [@dimensions[k].round(5), v.round(2)]] }.to_h}"
         end

data/lib/musa-dsl/generative/generative-grammar.rb

@@ -166,6 +166,8 @@ module Musa
       #
       # @param content [Object] element content
       # @param attributes [Hash, nil] element attributes
+      #
+      # @return [void]
       def initialize(content, attributes = nil)
         @content = content
         @attributes = attributes || {}
@@ -406,6 +408,14 @@ module Musa
 
         protected
 
+        # Generates condition block from simplified arguments.
+        #
+        # @param attribute [Symbol, nil] attribute to check
+        # @param after_collect_operation [Symbol, nil] operation on collected values
+        # @param comparison_method [Symbol, nil] comparison method to apply
+        # @param comparison_value [Object, nil] value to compare against
+        #
+        # @return [Proc, nil] condition block or nil if arguments incomplete
         def generate_simple_condition_block(attribute = nil,
                                             after_collect_operation = nil,
                                             comparison_method = nil,
@@ -451,6 +461,9 @@ module Musa
 
         # @param content [Object] node content
         # @param attributes [Hash] node attributes
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(content, attributes)
           super()
@@ -482,6 +495,9 @@ module Musa
       class BlockNode < Node
         # @param attributes [Hash] node attributes
         # @yield [parent, attributes] block to generate content
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(attributes, &block)
           @attributes = attributes
@@ -516,6 +532,9 @@ module Musa
       class ConditionNode < Node
         # @param node [Node] node to filter
         # @yield [option] condition block
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, &block)
           @node = node
@@ -545,6 +564,9 @@ module Musa
       class OrNode < Node
         # @param node1 [Node] first alternative
         # @param node2 [Node] second alternative
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node1, node2)
           @node1 = node1
@@ -579,6 +601,9 @@ module Musa
       class NextNode < Node
         # @param node [Node] first node in sequence
         # @param after [Node] node to follow
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, after)
           @node = node
@@ -609,6 +634,9 @@ module Musa
       class RepeatNode < Node
         # @param node [Node] node to repeat
         # @param max [Integer, nil] maximum repetitions (nil = infinite)
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, max = nil)
           @node = node

data/lib/musa-dsl/generative/markov.rb

@@ -113,6 +113,8 @@ module Musa
       #     start: :a,
       #     finish: :x
       #   )
+      #
+      # @return [void]
       def initialize(transitions:, start:, finish: nil, random: nil)
         @transitions = transitions.clone.freeze