tonal-guitar 0.1.0 → 0.2.0

package/README.md

@@ -40,7 +40,7 @@ import {
 } from "tonal-guitar";
 
 // 1. Get a shape and build a scale on the fretboard
-const shape = get("CAGED E Shape");
+const shape = get("E Shape");
 const scale = buildFrettedScale(shape, "A");
 
 // 2. Generate a pattern and walk it
@@ -52,8 +52,20 @@ console.log(toAsciiTab(notes));
 console.log(toAlphaTeX(notes, { tempo: 100, duration: 8 }));
 ```
 
+## v0.2.0 Changes
+
+- **`buildFromScale` pitch-correctness fix.** `buildFromScale` now relabels a shape into the requested scale's interval frame before building, so minor-tonic (and other non-major) scale names produce correct pitch content instead of silently building the shape's original (usually major) frame at the new tonic. See [buildFromScale](#tonaljs-integration) for the before/after example.
+- **`isShapeCompatible` chroma-set semantics.** Compatibility is now computed via interval-chroma-set coverage (enharmonic-safe) instead of raw interval-string comparison. This does not loosen relative-major/minor matching -- a major-frame shape is still incompatible with a minor scale name.
+- **New APIs:** `relabelShape` (pure tier, `src/transform.ts`) and `relabelShapeToScale` (integration tier) — see [Shape Relabeling](#shape-relabeling).
+- **New `ScaleShape` fields:** optional `quality` and `parentShape`, set on shapes derived via `relabelShape`.
+- **10 new registered entries:** 5 minor CAGED scale shapes and 5 minor pentatonic boxes — see [Minor-Quality Entries](#minor-quality-entries).
+
+See [CHANGELOG.md](./CHANGELOG.md) for full details.
+
 ## API
 
+For automated chord/scale shape correctness and quality checks, see [Audit](docs/api/audit.md) — also viewable live on the deployed Guitar Lab [`/shapes`](https://theguitarstudio.github.io/tonal-guitar/shapes) page.
+
 ### Tuning Constants
 
 Pre-defined tunings as `string[]` arrays (low string to high string):
@@ -125,15 +137,15 @@ fretboard(STANDARD, [0, 4]); // every note on strings 0-5, frets 0-4
 
 ### Shape Registry
 
-Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), and pentatonic boxes (5).
+Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), pentatonic boxes (5) -- plus (v0.2.0) 5 minor CAGED scale shapes and 5 minor pentatonic boxes, derived from the major-frame shapes via `relabelShape`. See [Minor-Quality Entries](#minor-quality-entries) below.
 
 #### `get(name: string) => ScaleShape | undefined`
 
 Retrieve a scale shape by name:
 
 ```js
-get("CAGED E Shape"); // => { name: "CAGED E Shape", system: "caged", strings: [...], ... }
-get("3NPS Pattern 1"); // => { name: "3NPS Pattern 1", system: "3nps", ... }
+get("E Shape"); // => { name: "E Shape", system: "caged", strings: [...], ... }
+get("3NPS Pattern 1 (Ionian)"); // => { name: "3NPS Pattern 1 (Ionian)", system: "3nps", ... }
 ```
 
 #### `all() => ScaleShape[]`
@@ -145,7 +157,7 @@ Get all registered scale shapes.
 Get all registered scale shape names:
 
 ```js
-names(); // => ["CAGED E Shape", "CAGED D Shape", "CAGED C Shape", ...]
+names(); // => ["E Shape", "D Shape", "C Shape", ...]
 ```
 
 #### `add(shape: ScaleShape) => ScaleShape`
@@ -176,13 +188,13 @@ Separate registry for chord shapes with the same API: `chordShapes.get()`, `chor
 Apply a scale shape to a root note and tuning, returning all fretted positions:
 
 ```js
-const scale = buildFrettedScale(get("CAGED E Shape"), "A");
+const scale = buildFrettedScale(get("E Shape"), "A");
 // => {
 //   empty: false,
 //   root: "A",
 //   scaleType: "",
 //   scaleName: "",
-//   shapeName: "CAGED E Shape",
+//   shapeName: "E Shape",
 //   tuning: ["E2", "A2", "D3", "G3", "B3", "E4"],
 //   notes: [
 //     { string: 0, fret: 5, note: "A2", pc: "A", interval: "1P", degree: 1, midi: 45, ... },
@@ -220,6 +232,66 @@ const chord = applyChordShape(chordShapes.get("E Shape"), "A");
 // }
 ```
 
+### Shape Relabeling
+
+#### `relabelShape(shape: ScaleShape, targetIntervals: string[], options?: RelabelOptions) => ScaleShape | undefined`
+
+Pure-tier primitive that rewrites a shape's per-string interval labels into a different, rotation-compatible interval frame (e.g. turning a major-frame CAGED shape into its natural-minor labeling). Geometry (which string/fret each note lands on) is unchanged -- only `strings` labels, `rootString`, `name`, `quality`, and `parentShape` change. Returns a new `ScaleShape` (the input is never mutated), or `undefined` when no valid relabeling exists (e.g. relabeling a 7-note shape into a 5-note pentatonic frame).
+
+```js
+import { relabelShape, get } from "tonal-guitar";
+
+const em = relabelShape(get("G Shape"), ["1P", "2M", "3m", "4P", "5P", "6m", "7m"], {
+  name: "Em Shape",
+  quality: "minor",
+  parentShape: "G Shape",
+});
+// em.rootString === 0, em.quality === "minor", em.parentShape === "G Shape"
+```
+
+```ts
+interface RelabelOptions {
+  name?: string;        // override the derived name (default: input shape.name)
+  quality?: string;      // value written to result.quality
+  parentShape?: string;  // value written to result.parentShape (default: shape.name)
+}
+```
+
+This is the primitive used to derive the 10 registered minor-quality entries -- see [Minor-Quality Entries](#minor-quality-entries) below, and `relabelShapeToScale` (in [Tonal.js Integration](#tonaljs-integration)) for the scale-name-driven wrapper.
+
+### Minor-Quality Entries
+
+The 5 CAGED and 5 pentatonic major-frame source shapes are each relabeled at import time (via `relabelShape`) into a paired minor-frame entry, registered under a distinct name. Geometry is identical to the parent shape -- only interval labels, `rootString`, and `quality`/`parentShape` metadata differ.
+
+#### Minor CAGED shapes
+
+| Parent shape | Registered minor name | `rootString` | `quality` |
+| --- | --- | --- | --- |
+| `"E Shape"` | `"Dm Shape"` | 2 | `"minor"` |
+| `"D Shape"` | `"Cm Shape"` | 1 | `"minor"` |
+| `"C Shape"` | `"Am Shape"` | 1 | `"minor"` |
+| `"A Shape"` | `"Gm Shape"` | 0 | `"minor"` |
+| `"G Shape"` | `"Em Shape"` | 0 | `"minor"` |
+
+#### Minor pentatonic boxes
+
+| Parent shape | Registered minor name | `rootString` | `quality` |
+| --- | --- | --- | --- |
+| `"Pentatonic Box 1"` | `"Pentatonic Box 1 Minor"` | 0 | `"minor-pentatonic"` |
+| `"Pentatonic Box 2"` | `"Pentatonic Box 2 Minor"` | 2 | `"minor-pentatonic"` |
+| `"Pentatonic Box 3"` | `"Pentatonic Box 3 Minor"` | 1 | `"minor-pentatonic"` |
+| `"Pentatonic Box 4"` | `"Pentatonic Box 4 Minor"` | 1 | `"minor-pentatonic"` |
+| `"Pentatonic Box 5"` | `"Pentatonic Box 5 Minor"` | 0 | `"minor-pentatonic"` |
+
+```js
+get("Em Shape");
+// => { name: "Em Shape", system: "caged", quality: "minor", parentShape: "G Shape", rootString: 0, ... }
+
+// Same fret positions as the major-frame parent at the relative-major root:
+buildFrettedScale(get("G Shape"), "C").notes;
+buildFrettedScale(get("Em Shape"), "A").notes; // same {string, fret} pairs, A=1P, C=3m
+```
+
 ### Pattern Generators
 
 All generators return `number[]` degree sequences.
@@ -278,7 +350,7 @@ sixths(7);  // same as ascendingIntervals(7, 5)
 Walk a degree pattern through a fretted scale, picking concrete notes:
 
 ```js
-const scale = buildFrettedScale(get("CAGED E Shape"), "A");
+const scale = buildFrettedScale(get("E Shape"), "A");
 const notes = walkPattern(scale, [1, 3, 5, 7, 6, 5, 4, 3, 2, 1]);
 ```
 
@@ -502,13 +574,36 @@ These functions require optional peer dependencies (`@tonaljs/scale`, `@tonaljs/
 Build a fretted scale using Tonal's `Scale.get()` for validation. Populates `scaleType` and `scaleName`:
 
 ```js
-const scale = buildFromScale(get("CAGED E Shape"), "A major");
+const scale = buildFromScale(get("E Shape"), "A major");
 scale.scaleType; // => "major"
 scale.scaleName; // => "A major"
 
 buildFromScale(get("Pentatonic Box 1"), "A minor pentatonic");
 ```
 
+> **v0.2.0 behavior change (pitch-correctness fix).** `buildFromScale` now relabels `shape` into `scaleName`'s interval frame (via `relabelShape`) before building. Previously, `buildFromScale(get("E Shape"), "A minor")` applied the major-frame shape as-is at the "A" tonic, silently producing **A-major pitch classes** tagged `scaleType: "aeolian"`. As of v0.2.0 the same call produces correct A-natural-minor notes (`A=1P`, `C=3m`, `E=5P`) in the relabeled geometry. If the shape can't be relabeled into the requested frame, `relabelShape` returns `undefined` and `buildFromScale` falls back to its pre-fix behavior (building the shape as-is), so no previously-working call regresses to empty. See [Shape Relabeling](#shape-relabeling) above.
+
+```js
+// v0.2.0: minor tonics now produce correct pitch content --
+// pre-fix this call produced A-major pitch classes (A, B, C#, D, E, F#, G#)
+// mislabeled as "aeolian"; post-fix it produces A-natural-minor pitch classes.
+const aMinor = buildFromScale(get("E Shape"), "A minor");
+[...new Set(aMinor.notes.map((n) => n.pc))].sort();
+// => ["A", "B", "C", "D", "E", "F", "G"]
+aMinor.notes.find((n) => n.pc === "C").interval; // => "3m"
+```
+
+#### `relabelShapeToScale(shape: ScaleShape, scaleName: string, options?: RelabelOptions) => ScaleShape | undefined`
+
+Integration-tier wrapper over the pure `relabelShape` primitive (see [Shape Relabeling](#shape-relabeling)): resolves `scaleName` via Tonal's `Scale.get()` and relabels `shape` into that scale's interval frame. Enharmonic spelling is inherited from the target scale's own intervals.
+
+```js
+relabelShapeToScale(get("G Shape"), "A minor", { name: "Em Shape", quality: "minor", parentShape: "G Shape" });
+// equals the pre-registered get("Em Shape")
+
+relabelShapeToScale(get("E Shape"), "bogus scale"); // => undefined
+```
+
 #### `relatedScales(frettedScale: FrettedScale) => Array<{ root: string, scale: string }>`
 
 Find all modal relatives (scales sharing the same pitch classes):
@@ -550,20 +645,67 @@ Returns `{ empty: true }` if the chord is not found in the key.
 
 #### `isShapeCompatible(shape: ScaleShape, scaleName: string) => boolean`
 
-Check if a shape's intervals are all present in a given scale:
+Check whether a shape is compatible with a scale by interval-chroma coverage (root-relative, enharmonic-safe): a shape is compatible iff its chroma set is a non-empty subset of the scale's chroma set.
+
+> **v0.2.0 behavior change.** The comparison is now chroma-based rather than raw interval-string comparison (fixes enharmonic spelling mismatches like `4A` vs `5d` across Tonal scale types). This is **not** a relative-major/minor loosening -- a major-frame shape is still incompatible with a minor scale name. The relative-major/minor identity is expressed through the registered minor-quality entries instead (see [Minor-Quality Entries](#minor-quality-entries)).
 
 ```js
-isShapeCompatible(get("CAGED E Shape"), "A major"); // => true
+isShapeCompatible(get("E Shape"), "A major"); // => true
 isShapeCompatible(get("Pentatonic Box 1"), "A major"); // => true (subset)
+isShapeCompatible(get("E Shape"), "A minor"); // => false (major frame ⊄ minor frame, root-relative)
+isShapeCompatible(get("Em Shape"), "A minor"); // => true (minor frame ⊆ minor frame)
+isShapeCompatible(get("Pentatonic Box 1 Minor"), "A minor"); // => true (minor-pent ⊆ natural-minor chromas)
+```
+
+#### `scalesContainingChord(chord: string, options?: ScalesContainingChordOptions) => ScalesContainingChordResult`
+
+Find scales that contain a chord's tones -- "what can I play over this chord". Resolves `chord` via Tonal's `Chord.get()`, then sweeps 12 chromatic roots x a fixed corpus of 11 scale types (`DEFAULT_SCALE_CORPUS`: major, dorian, phrygian, lydian, mixolydian, aeolian, locrian, harmonic minor, melodic minor, major pentatonic, minor pentatonic), keeping every candidate whose pitch-class set is a (tolerant) superset of the chord's. Results are partitioned into `rootAnchored` (scale tonic matches the chord's root) and `otherRoots` (every other root), each ranked by fit (`extraTones` ascending, then corpus order, then root-chroma distance, then name).
+
+```js
+import { scalesContainingChord } from "tonal-guitar";
+
+const result = scalesContainingChord("Cmaj7");
+result.chord; // => "Cmaj7"
+result.root; // => "C"
+result.rootAnchored.map((s) => s.name);
+// => ["C major", "C lydian"]
+// (C mixolydian and C dorian are excluded -- they don't contain the chord's B / E natural)
+
+scalesContainingChord("Cm7").rootAnchored.map((s) => s.name);
+// => ["C minor pentatonic", "C dorian", "C phrygian", "C minor"]
+// ("C major" is excluded -- it doesn't contain the chord's Eb / Bb)
 ```
 
+Containment is strict by default (`tolerateMissing: 0`). Pass `tolerateMissing: N` to admit scales missing up to `N` chord tones, recorded in each result's `omittedTones`:
+
+```js
+const tolerant = scalesContainingChord("Cm7", { tolerateMissing: 1 });
+tolerant.rootAnchored.find((s) => s.name === "C mixolydian").omittedTones; // => ["Eb"]
+```
+
+Never throws -- an unresolvable or empty chord name returns `{ chord: "", root: "", rootAnchored: [], otherRoots: [] }`.
+
+> **Note on "aeolian" naming.** `DEFAULT_SCALE_CORPUS` includes `"aeolian"`, but `@tonaljs/scale` normalizes that alias to its canonical dictionary entry (`Scale.get("A aeolian")` returns `{ type: "minor", name: "A minor", ... }` -- chroma-identical, just relabeled). As a result, aeolian-swept candidates surface in the output as e.g. `"A minor"`, not `"A aeolian"`.
+
 #### `modeShapes(modeName: string, shapeSystem?: string) => ScaleShape[]`
 
 Get all registered shapes compatible with a mode/scale:
 
 ```js
-modeShapes("A major", "caged"); // all CAGED shapes that fit A major
-modeShapes("A dorian"); // all shapes (any system) that fit A dorian
+modeShapes("C major", "caged"); // => 5 (major-frame CAGED shapes; minor entries excluded)
+
+// v0.2.0: minor tonics now resolve to the 10 registered minor-quality entries
+modeShapes("A minor", "caged");
+// => 5: "Dm Shape", "Cm Shape", "Am Shape", "Gm Shape", "Em Shape"
+modeShapes("A minor pentatonic", "pentatonic");
+// => the 5 "Pentatonic Box N Minor" entries
+modeShapes("A minor").length; // => 10 (5 minor CAGED + 5 minor pentatonic)
+
+// Chroma-subset coverage applies to any superset frame: the minor-pentatonic
+// chroma set {0,3,5,7,10} is also a subset of dorian's {0,2,3,5,7,9,10}, so
+modeShapes("A dorian");
+// => the 5 "Pentatonic Box N Minor" entries (there is no first-class dorian entry --
+// this is the minor-pentatonic entries' chroma set fitting dorian too)
 ```
 
 ## Types
@@ -572,8 +714,9 @@ The package exports these TypeScript interfaces:
 
 - `FrettedNote` — a note on the fretboard with position, pitch, and interval info
 - `FrettedScale` — a scale applied to the fretboard (with `empty` sentinel pattern)
-- `ScaleShape` — a scale shape definition (intervals per string)
+- `ScaleShape` — a scale shape definition (intervals per string, plus optional `quality`/`parentShape` metadata set on entries derived via `relabelShape`)
 - `ChordShape` — a chord voicing definition (one interval per string + fingerings + optional harmonic metadata)
+- `RelabelOptions` — options for `relabelShape`/`relabelShapeToScale` (`name`, `quality`, `parentShape`)
 - `Barre` — barre chord finger placement
 - `Fingering` — chord shape applied to a specific root
 - `FretboardPosition` — absolute position on the fretboard (string, fret, note, midi)