@libraz/libcantus 0.9.2 → 0.9.3

package/dist/model/index.d.cts

@@ -1,6 +1,7 @@
-import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-r2sh-jOO.cjs';
-import { a as ChordQuality, C as Chord$1 } from '../index-BOBXBNwP.cjs';
-import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-BjXtOFNk.cjs';
+import { D as DetectChordOptions } from '../index-CnZCo29u.cjs';
+import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-DYt4iKsn.cjs';
+import { a as ChordQuality, C as Chord$1 } from '../index-BNlGP86A.cjs';
+import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-ZTbdaVFM.cjs';
 import { N as Note$1, S as SpelledInterval } from '../index-CGMZNCx6.cjs';
 import { K as KeyScale } from '../types-MGP29r3t.cjs';
 
@@ -399,14 +400,14 @@ declare class Chord {
      * @param pitches MIDI pitches or bare pitch classes.
      * @returns Ranked chord interpretations (may be empty).
      */
-    static detect(pitches: number[]): Chord[];
+    static detect(pitches: number[], opts?: DetectChordOptions): Chord[];
     /**
      * The single best chord interpretation of a pitch set.
      *
      * @param pitches MIDI pitches or bare pitch classes.
      * @returns The top-ranked chord, or null when nothing matches.
      */
-    static detectBest(pitches: number[]): Chord | null;
+    static detectBest(pitches: number[], opts?: DetectChordOptions): Chord | null;
     /** The root pitch class (0..11). */
     get rootPc(): number;
     /** The chord quality. */

package/dist/model/index.d.ts

@@ -1,6 +1,7 @@
-import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-2bJW1Zp_.js';
-import { a as ChordQuality, C as Chord$1 } from '../index-CM5W4rcm.js';
-import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-D7BAx3S3.js';
+import { D as DetectChordOptions } from '../index-JnF4v9bx.js';
+import { H as HarmonicFunction, a as ChordAnalysis, C as Cadence, B as BorrowedSource } from '../function-DVH4Eusr.js';
+import { a as ChordQuality, C as Chord$1 } from '../index-Bt4tOUD9.js';
+import { d as VoicingOptions, c as StyledVoicingOptions, C as ChordScaleMatch } from '../styled-DZ7GjShb.js';
 import { N as Note$1, S as SpelledInterval } from '../index-CGMZNCx6.js';
 import { K as KeyScale } from '../types-MGP29r3t.js';
 
@@ -399,14 +400,14 @@ declare class Chord {
      * @param pitches MIDI pitches or bare pitch classes.
      * @returns Ranked chord interpretations (may be empty).
      */
-    static detect(pitches: number[]): Chord[];
+    static detect(pitches: number[], opts?: DetectChordOptions): Chord[];
     /**
      * The single best chord interpretation of a pitch set.
      *
      * @param pitches MIDI pitches or bare pitch classes.
      * @returns The top-ranked chord, or null when nothing matches.
      */
-    static detectBest(pitches: number[]): Chord | null;
+    static detectBest(pitches: number[], opts?: DetectChordOptions): Chord | null;
     /** The root pitch class (0..11). */
     get rootPc(): number;
     /** The chord quality. */

package/dist/model/index.js

@@ -4,13 +4,13 @@ import {
   Key,
   Note,
   Progression
-} from "../chunk-COKTX2G5.js";
-import "../chunk-GQKN5KDT.js";
-import "../chunk-LN7ZZMD2.js";
-import "../chunk-XTC3X6MS.js";
+} from "../chunk-SGU7SPLK.js";
+import "../chunk-IT2O4XFE.js";
+import "../chunk-CHMXELDS.js";
+import "../chunk-C5XYKUVG.js";
 import "../chunk-DYWFNC4A.js";
-import "../chunk-7Y7WF64D.js";
-import "../chunk-CCBLVAPK.js";
+import "../chunk-MIWO425M.js";
+import "../chunk-FBQK3ZQN.js";
 export {
   Chord,
   Interval,

package/dist/{styled-D7BAx3S3.d.ts → styled-DZ7GjShb.d.ts}

@@ -1,4 +1,4 @@
-import { C as Chord } from './index-CM5W4rcm.js';
+import { C as Chord } from './index-Bt4tOUD9.js';
 
 /**
  * Test whether every chord pitch class is contained in a scale.

package/dist/{styled-BjXtOFNk.d.cts → styled-ZTbdaVFM.d.cts}

@@ -1,4 +1,4 @@
-import { C as Chord } from './index-BOBXBNwP.cjs';
+import { C as Chord } from './index-BNlGP86A.cjs';
 
 /**
  * Test whether every chord pitch class is contained in a scale.

package/dist/theory/index.cjs

@@ -352,8 +352,10 @@ function classifySeventh(thirdIc, fifthIc, seventhIc) {
 function stackThirds(degree, key, size) {
   const tones = scaleTonesInDegreeOrder(key);
   const length = tones.length;
-  if (length === 0) {
-    return { rootPc: pitchClass2(key.rootPc), quality: "maj", intervals: [0, 4, 7] };
+  if (length !== 7) {
+    throw new Error(
+      `diatonic chord stacking requires a heptatonic scale (received ${length} tones)`
+    );
   }
   const idx = (step) => ((degree + step) % length + length) % length;
   const rootPc = tones[idx(0)] ?? pitchClass2(key.rootPc);
@@ -671,32 +673,17 @@ function isLeadingToneResolution(prev, cur, key) {
 function roleOf(pitch, chord, chordId = 0) {
   const interval = ((Math.trunc(pitch) - chord.rootPc) % 12 + 12) % 12;
   const tones = new Set(chord.intervals.map((i) => (i % 12 + 12) % 12));
-  const hasHigherSeventh = tones.has(10) || tones.has(11);
   const hasThird = tones.has(3) || tones.has(4);
   const isSuspendedTone = !hasThird && (interval === 5 && tones.has(5) || interval === 2 && tones.has(2));
+  const chordRole = chordToneRole(pitch, chord);
   let role;
   let lock;
-  if (interval === 0) {
-    role = "root";
-    lock = "identity";
-  } else if (isSuspendedTone) {
+  if (isSuspendedTone) {
     role = "third";
     lock = "quality";
-  } else if (interval === 3 || interval === 4) {
-    role = "third";
-    lock = "quality";
-  } else if (interval === 6 || interval === 7 || interval === 8) {
-    role = "fifth";
-    lock = "voicing";
-  } else if (interval === 9 && tones.has(3) && tones.has(6) && !hasHigherSeventh) {
-    role = "seventh";
-    lock = "voicing";
-  } else if (interval === 9 && tones.has(9) && !hasHigherSeventh) {
-    role = "sixth";
-    lock = "voicing";
-  } else if (interval === 10 || interval === 11) {
-    role = "seventh";
-    lock = "voicing";
+  } else if (chordRole !== null) {
+    role = chordRole;
+    lock = chordRole === "root" ? "identity" : chordRole === "third" ? "quality" : "voicing";
   } else {
     role = "tension";
     lock = "voicing";
@@ -704,6 +691,33 @@ function roleOf(pitch, chord, chordId = 0) {
   return { role, lock, belongsToChordId: chordId };
 }
 
+// src/core/validation/index.ts
+var DEFAULT_GENERATION_BUDGET = 1e6;
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be finite; received ${value}`);
+  }
+  return value;
+}
+function assertInteger(value, name, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+  assertFiniteNumber(value, name);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertPositiveInt(value, name, max = DEFAULT_GENERATION_BUDGET) {
+  return assertInteger(value, name, 1, max);
+}
+function assertGenerationBudget(estimated, name, limit = DEFAULT_GENERATION_BUDGET) {
+  assertFiniteNumber(estimated, name);
+  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);
+  if (estimated < 0 || estimated > limit) {
+    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);
+  }
+  return estimated;
+}
+
 // src/theory/safety/index.ts
 var NoteSafety = /* @__PURE__ */ ((NoteSafety2) => {
   NoteSafety2[NoteSafety2["Safe"] = 0] = "Safe";
@@ -732,6 +746,31 @@ var ReasonFlag = /* @__PURE__ */ ((ReasonFlag2) => {
 })(ReasonFlag || {});
 var SUGGESTION_WINDOW = 12;
 var MAX_SUGGESTIONS = 3;
+var REASON_SEVERITY = [
+  [2 /* Tension */, 1 /* Warning */, 1 /* Warning */],
+  [4 /* AvoidNote */, 1 /* Warning */, 2 /* Dissonant */],
+  [8 /* ScaleTone */, 1 /* Warning */, 1 /* Warning */],
+  [16 /* NonScale */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32 /* OutOfRange */, 1 /* Warning */, 1 /* Warning */],
+  [64 /* Tritone */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [128 /* LargeLeap */, 1 /* Warning */, 2 /* Dissonant */],
+  [1024 /* VerticalDissonance */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [2048 /* ParallelPerfect */, 1 /* Warning */, 2 /* Dissonant */],
+  [4096 /* HiddenParallel */, 1 /* Warning */, 2 /* Dissonant */],
+  [8192 /* VoiceCrossing */, 1 /* Warning */, 2 /* Dissonant */],
+  [16384 /* Suspension */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32768 /* NeedsResolution */, 1 /* Warning */, 2 /* Dissonant */]
+];
+function minimumSafetyForReasons(reasons, profile) {
+  let minimum = 0 /* Safe */;
+  const severityIndex = profile === "strict" ? 2 : 1;
+  for (const entry of REASON_SEVERITY) {
+    if (reasons & entry[0]) {
+      minimum = Math.max(minimum, entry[severityIndex]);
+    }
+  }
+  return minimum;
+}
 function pitchClass5(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -756,8 +795,27 @@ function stepResolution(pitch, chord) {
   return void 0;
 }
 function evaluateSafety(q) {
+  assertSafetyContext(q);
+  assertFiniteNumber(q.candidatePitch, "candidatePitch");
   return evaluateInternal(q, true);
 }
+function assertSafetyContext(q) {
+  if (q.prevPitch !== void 0) assertFiniteNumber(q.prevPitch, "prevPitch");
+  if (q.vocalLow !== void 0) assertFiniteNumber(q.vocalLow, "vocalLow");
+  if (q.vocalHigh !== void 0) assertFiniteNumber(q.vocalHigh, "vocalHigh");
+  if (q.vocalLow !== void 0 && q.vocalHigh !== void 0 && q.vocalLow > q.vocalHigh) {
+    throw new RangeError("vocalLow must not exceed vocalHigh");
+  }
+  assertGenerationBudget(q.otherVoices.length, "other voices");
+  for (let index = 0; index < q.otherVoices.length; index += 1) {
+    const voice = q.otherVoices[index];
+    if (!voice) continue;
+    assertFiniteNumber(voice.pitch, `otherVoices[${index}].pitch`);
+    if (voice.prevPitch !== void 0) {
+      assertFiniteNumber(voice.prevPitch, `otherVoices[${index}].prevPitch`);
+    }
+  }
+}
 function evaluateInternal(q, collectSuggestions) {
   let reasons = 0;
   let level = 0 /* Safe */;
@@ -818,9 +876,11 @@ function evaluateInternal(q, collectSuggestions) {
     const pc = Math.abs(pitch - q.prevPitch) % 12;
     if (pc === 6) {
       reasons |= 64 /* Tritone */;
+      raise(2 /* Dissonant */);
     }
     if (isForbiddenMelodicLeap(q.prevPitch, pitch)) {
       reasons |= 128 /* LargeLeap */;
+      raise(parallelSeverity);
     }
     if (pc === 1) {
       reasons |= 256 /* MinorSecond */;
@@ -865,6 +925,7 @@ function evaluateInternal(q, collectSuggestions) {
       }
     }
   }
+  raise(minimumSafetyForReasons(reasons, q.profile));
   const result = { safety: level, reasons, rationale: describe(reasons, q) };
   if (resolveTo !== void 0) {
     result.resolveTo = resolveTo;
@@ -928,11 +989,15 @@ function describe(reasons, q) {
   return q.chord ? "Placeable" : "No chord context";
 }
 function enumerateSafePitches(q, pitchLow, pitchHigh) {
+  assertSafetyContext(q);
   const chordTones = [];
   const others = [];
-  if (!Number.isFinite(pitchLow) || !Number.isFinite(pitchHigh)) {
-    return [];
+  assertInteger(pitchLow, "pitchLow");
+  assertInteger(pitchHigh, "pitchHigh");
+  if (pitchLow > pitchHigh) {
+    throw new RangeError(`pitchLow must not exceed pitchHigh; received ${pitchLow} > ${pitchHigh}`);
   }
+  assertGenerationBudget(pitchHigh - pitchLow + 1, "safe pitch candidates");
   for (let pitch = pitchHigh; pitch >= pitchLow; pitch -= 1) {
     const result = evaluateInternal({ ...q, candidatePitch: pitch }, false);
     if (result.safety === 2 /* Dissonant */) {
@@ -1101,10 +1166,58 @@ function spellScale(tonic, key) {
 function spellPitchClasses(pcs, tonic, key) {
   return pcs.map((pc) => spellPitchClass(pc, tonic, key));
 }
+function chordLetterOffset(interval, chord) {
+  switch (interval) {
+    case 0:
+    case 12:
+      return 0;
+    case 1:
+    case 2:
+    case 13:
+    case 14:
+      return 1;
+    case 3:
+    case 4:
+    case 15:
+    case 16:
+      return 2;
+    case 5:
+    case 17:
+    case 18:
+      return 3;
+    case 6:
+    case 7:
+    case 8:
+    case 19:
+      return 4;
+    case 9:
+      return chord.quality === "dim7" ? 6 : 5;
+    case 20:
+    case 21:
+      return 5;
+    case 10:
+    case 11:
+    case 22:
+    case 23:
+      return 6;
+    default: {
+      const octaves = Math.floor(Math.max(0, interval) / 12);
+      const simple = mod122(interval);
+      const simpleOffset = [0, 1, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6][simple] ?? 0;
+      return octaves * 7 + simpleOffset;
+    }
+  }
+}
+function spellChordFromRoot(chord, root) {
+  return chord.intervals.map((interval) => {
+    const letter = mod72(root.letter + chordLetterOffset(interval, chord));
+    const pc = mod122(chord.rootPc + interval);
+    return { letter, alter: alterFor(letter, pc) };
+  });
+}
 function spellChord(chord, tonic, key) {
-  return chord.intervals.map(
-    (interval) => spellPitchClass(mod122(chord.rootPc + interval), tonic, key)
-  );
+  const root = spellPitchClass(chord.rootPc, tonic, key);
+  return spellChordFromRoot(chord, root);
 }
 function noteNames(notes) {
   return notes.map(formatNote);
@@ -1397,12 +1510,23 @@ function resolveRanges(opts) {
     if (opts.ranges.length === 0) {
       throw new Error("ranges must contain at least one voice range");
     }
-    return opts.ranges.map((range) => ({ ...range }));
+    assertGenerationBudget(opts.ranges.length, "voice ranges", 128);
+    return opts.ranges.map((range, index) => {
+      assertFiniteNumber(range.min, `ranges[${index}].min`);
+      assertFiniteNumber(range.max, `ranges[${index}].max`);
+      if (range.min > range.max) {
+        throw new RangeError(`ranges[${index}].min must not exceed max`);
+      }
+      assertGenerationBudget(
+        Math.floor(range.max) - Math.ceil(range.min) + 1,
+        `ranges[${index}] span`,
+        4096
+      );
+      return { ...range };
+    });
   }
   const voices = opts?.voices ?? 4;
-  if (voices < 1) {
-    throw new Error("voices must be at least 1");
-  }
+  assertPositiveInt(voices, "voices", 128);
   if (voices === 4) {
     return SATB_RANGES.map((range) => ({ ...range }));
   }
@@ -1421,6 +1545,8 @@ function resolveRanges(opts) {
 function voiceChord(chord, opts) {
   const ranges = resolveRanges(opts);
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  assertFiniteNumber(maxSpacing, "maxSpacing");
+  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
   const candidates = enumerateVoicings(chord, ranges, maxSpacing);
   let best;
   let bestScore = Number.POSITIVE_INFINITY;
@@ -1445,8 +1571,11 @@ function voiceChord(chord, opts) {
   return best;
 }
 function voiceProgression(chords, opts) {
+  assertGenerationBudget(chords.length * 4e3, "voiced progression search");
   const ranges = resolveRanges(opts);
   const maxSpacing = opts?.maxSpacing ?? DEFAULT_MAX_SPACING;
+  assertFiniteNumber(maxSpacing, "maxSpacing");
+  if (maxSpacing < 0) throw new RangeError("maxSpacing must be non-negative");
   const result = [];
   let prev;
   for (const chord of chords) {
@@ -1552,7 +1681,12 @@ function nearestPc(target, pcs) {
 }
 function voiceChordStyled(chord, opts) {
   const style = opts?.style ?? "close";
-  const base = 12 * ((opts?.octave ?? DEFAULT_STYLE_OCTAVE) + 1);
+  const octave = opts?.octave ?? DEFAULT_STYLE_OCTAVE;
+  assertInteger(octave, "styled voicing octave", -10, 10);
+  if (opts?.topNote !== void 0) {
+    assertFiniteNumber(opts.topNote, "styled voicing topNote");
+  }
+  const base = 12 * (octave + 1);
   const rootPc = pitchClass7(chord.rootPc);
   const bassPc = pitchClass7(chord.bassPc ?? chord.rootPc);
   const omitRoot = style === "rootless" || opts?.rootless === true;
@@ -1568,11 +1702,11 @@ function voiceChordStyled(chord, opts) {
     const guide = roles.includes("seventh") ? "seventh" : roles.includes("sixth") ? "sixth" : "fifth";
     order = order.filter((_pc, i) => {
       const role = roles[i];
-      return role === "root" || role === "third" || role === guide;
+      return _pc === bassPc || role === "root" || role === "third" || role === guide;
     });
   }
   if (omitRoot) {
-    order = order.filter((pc) => pc !== rootPc);
+    order = order.filter((pc) => pc !== rootPc || chord.bassPc !== void 0 && pc === bassPc);
   }
   if (order.length === 0) {
     return [];
@@ -1601,6 +1735,18 @@ function voiceChordStyled(chord, opts) {
   } else if (style === "drop3" && stack.length >= 3) {
     stack[stack.length - 3] = (stack[stack.length - 3] ?? 0) - 12;
   }
+  if (chord.bassPc !== void 0) {
+    const bassIndexInStack = stack.findIndex((pitch) => pitchClass7(pitch) === bassPc);
+    if (bassIndexInStack >= 0) {
+      const otherLowest = Math.min(
+        ...stack.filter((_pitch, index) => index !== bassIndexInStack),
+        Number.POSITIVE_INFINITY
+      );
+      while ((stack[bassIndexInStack] ?? 0) >= otherLowest) {
+        stack[bassIndexInStack] = (stack[bassIndexInStack] ?? 0) - 12;
+      }
+    }
+  }
   return stack.sort((a, b) => a - b);
 }
 // Annotate the CommonJS export names for ESM import in node: