@libraz/libcantus 0.9.1 → 0.9.3

package/src/{chord → theory/chord}/index.ts

@@ -1,5 +1,5 @@
+import type { KeyScale } from '../../core/types.js';
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
 /**
  * Chord quality identifiers understood by the chord builder.
@@ -70,6 +70,24 @@ export type Chord = {
   bassSpelling?: PitchSpelling;
 };
 
+/**
+ * A chord positioned in time: a root pitch class and quality placed at a beat,
+ * with optional harmonic-analysis hints. Serves as the neutral exchange record
+ * between progression generators and timeline analysers.
+ *
+ * @category Composition
+ */
+export type ChordSpan = {
+  rootPc: number;
+  quality: ChordQuality;
+  startBeat: number;
+  bassPc?: number;
+  /** 0-based scale degree of the chord root, when known. */
+  degree?: number;
+  /** True when the chord is a secondary dominant tonicizing another degree. */
+  secondaryDominant?: boolean;
+};
+
 /** Semitone offsets from the root for each supported chord quality. */
 const QUALITY_INTERVALS: Record<ChordQuality, number[]> = {
   maj: [0, 4, 7],
@@ -299,8 +317,10 @@ function classifySeventh(thirdIc: number, fifthIc: number, seventhIc: number): C
 function stackThirds(degree: number, key: KeyScale, size: 3 | 4): Chord {
   const tones = scaleTonesInDegreeOrder(key);
   const length = tones.length;
-  if (length === 0) {
-    return { rootPc: pitchClass(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: number) => (((degree + step) % length) + length) % length;
   const rootPc = tones[idx(0)] ?? pitchClass(key.rootPc);

package/src/{counterpoint → theory/counterpoint}/index.ts

@@ -1,5 +1,5 @@
-import { isConsonantInterval } from '../interval/index.js';
-import type { KeyScale } from '../types.js';
+import { isConsonantInterval } from '../../core/interval/index.js';
+import type { KeyScale } from '../../core/types.js';
 
 /** Reduce a MIDI pitch (or pitch class) to a pitch class in [0, 11]. */
 function pitchClass(pitch: number): number {

package/src/{harmony → theory/harmony}/index.ts

@@ -1,4 +1,4 @@
-import type { Chord } from '../chord/index.js';
+import { type Chord, chordToneRole } from '../chord/index.js';
 
 /**
  * Harmonic role a pitch plays within a chord.
@@ -57,33 +57,18 @@ export type VoicedRole = {
 export function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {
   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: HarmonyRole;
   let lock: LockLevel;
-  if (interval === 0) {
-    role = 'root';
-    lock = 'identity';
-  } else if (isSuspendedTone) {
+  if (isSuspendedTone) {
     role = 'third'; // suspended tone occupies the third's quality-defining slot
     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'; // diminished 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';

package/src/theory/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Public API of the theory layer. Re-exports every theory-layer module;
+ * also available from the package root.
+ */
+export type {
+  Chord as ChordData,
+  ChordQuality,
+  ChordSpan,
+  PitchSpelling,
+} from './chord/index.js';
+export {
+  chordFromDegree,
+  chordPitchClasses,
+  chordQualities,
+  chordToneRole,
+  diatonicSeventh,
+  diatonicTriad,
+  makeChord,
+} from './chord/index.js';
+export type {
+  ChordScaleMatch,
+  ChordScaleReportEntry,
+  ScaleChoice,
+} from './chordscale/index.js';
+export {
+  availableTensions,
+  avoidNotes,
+  chordScaleReport,
+  chordScales,
+  scaleMatchesChord,
+  scalesForChanges,
+} from './chordscale/index.js';
+export {
+  createsHiddenParallelPerfect,
+  createsParallelOctave,
+  createsParallelPerfect,
+  createsParallelUnison,
+  createsVerticalDissonance,
+  createsVoiceCrossing,
+  createsVoiceOverlap,
+  exceedsSpacing,
+  isForbiddenMelodicLeap,
+  isLeadingToneResolution,
+} from './counterpoint/index.js';
+export type { HarmonyRole, LockLevel, VoicedRole } from './harmony/index.js';
+export { roleOf } from './harmony/index.js';
+export type {
+  SafetyProfile,
+  SafetyQuery,
+  SafetyResult,
+  VoiceSnapshot,
+} from './safety/index.js';
+export {
+  enumerateSafePitches,
+  evaluateSafety,
+  NoteSafety,
+  ReasonFlag,
+} from './safety/index.js';
+export {
+  BLUES_MASK,
+  CHROMATIC_MASK,
+  DORIAN_MASK,
+  diatonicPitchClasses,
+  HARMONIC_MINOR_MASK,
+  isScaleTone,
+  LOCRIAN_MASK,
+  LYDIAN_MASK,
+  MAJOR_MASK,
+  MAJOR_PENTATONIC_MASK,
+  MELODIC_MINOR_MASK,
+  MINOR_PENTATONIC_MASK,
+  MIXOLYDIAN_MASK,
+  majorKey,
+  maskFromOffsets,
+  minorKey,
+  NAMED_SCALES,
+  NATURAL_MINOR_MASK,
+  nearestScaleTone,
+  OCTATONIC_HALF_WHOLE_MASK,
+  OCTATONIC_WHOLE_HALF_MASK,
+  PHRYGIAN_MASK,
+  pitchToScaleDegree,
+  scaleByName,
+  scaleTonesInDegreeOrder,
+  WHOLE_TONE_MASK,
+} from './scale/index.js';
+export {
+  noteNames,
+  spellChord,
+  spellPitchClass,
+  spellPitchClasses,
+  spellScale,
+} from './spelling/index.js';
+export {
+  formatChordSymbol,
+  parseChordSymbol,
+  transposeChordSymbol,
+} from './symbol/index.js';
+export type {
+  StyledVoicingOptions,
+  VoiceRange,
+  VoicingOptions,
+  VoicingStyle,
+} from './voicing/index.js';
+export {
+  nextVoicing,
+  SATB_RANGES,
+  voiceChord,
+  voiceChordStyled,
+  voiceLeadingCost,
+  voiceProgression,
+} from './voicing/index.js';

package/src/{safety → theory/safety}/index.ts

@@ -1,3 +1,9 @@
+import type { KeyScale } from '../../core/types.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+} from '../../core/validation/index.js';
 import type { Chord } from '../chord/index.js';
 import { chordPitchClasses } from '../chord/index.js';
 import {
@@ -7,7 +13,6 @@ import {
   isForbiddenMelodicLeap,
 } from '../counterpoint/index.js';
 import { isScaleTone } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -96,6 +101,36 @@ const SUGGESTION_WINDOW = 12;
 /** Maximum number of alternative pitches returned in `SafetyResult.suggestions`. */
 const MAX_SUGGESTIONS = 3;
 
+/** Canonical minimum verdict contributed by each non-informational reason. */
+const REASON_SEVERITY: ReadonlyArray<
+  readonly [flag: ReasonFlag, pop: NoteSafety, strict: NoteSafety]
+> = [
+  [ReasonFlag.Tension, NoteSafety.Warning, NoteSafety.Warning],
+  [ReasonFlag.AvoidNote, NoteSafety.Warning, NoteSafety.Dissonant],
+  [ReasonFlag.ScaleTone, NoteSafety.Warning, NoteSafety.Warning],
+  [ReasonFlag.NonScale, NoteSafety.Dissonant, NoteSafety.Dissonant],
+  [ReasonFlag.OutOfRange, NoteSafety.Warning, NoteSafety.Warning],
+  [ReasonFlag.Tritone, NoteSafety.Dissonant, NoteSafety.Dissonant],
+  [ReasonFlag.LargeLeap, NoteSafety.Warning, NoteSafety.Dissonant],
+  [ReasonFlag.VerticalDissonance, NoteSafety.Dissonant, NoteSafety.Dissonant],
+  [ReasonFlag.ParallelPerfect, NoteSafety.Warning, NoteSafety.Dissonant],
+  [ReasonFlag.HiddenParallel, NoteSafety.Warning, NoteSafety.Dissonant],
+  [ReasonFlag.VoiceCrossing, NoteSafety.Warning, NoteSafety.Dissonant],
+  [ReasonFlag.Suspension, NoteSafety.Dissonant, NoteSafety.Dissonant],
+  [ReasonFlag.NeedsResolution, NoteSafety.Warning, NoteSafety.Dissonant],
+];
+
+function minimumSafetyForReasons(reasons: number, profile: SafetyProfile): NoteSafety {
+  let minimum = NoteSafety.Safe;
+  const severityIndex = profile === 'strict' ? 2 : 1;
+  for (const entry of REASON_SEVERITY) {
+    if (reasons & entry[0]) {
+      minimum = Math.max(minimum, entry[severityIndex]) as NoteSafety;
+    }
+  }
+  return minimum;
+}
+
 function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
@@ -154,9 +189,30 @@ function stepResolution(pitch: number, chord: Chord): number | undefined {
  * @category Arrangement & Analysis
  */
 export function evaluateSafety(q: SafetyQuery): SafetyResult {
+  assertSafetyContext(q);
+  assertFiniteNumber(q.candidatePitch, 'candidatePitch');
   return evaluateInternal(q, true);
 }
 
+/** Validate all numeric context fields once at a public safety entry point. */
+function assertSafetyContext(q: Omit<SafetyQuery, 'candidatePitch'>): void {
+  if (q.prevPitch !== undefined) assertFiniteNumber(q.prevPitch, 'prevPitch');
+  if (q.vocalLow !== undefined) assertFiniteNumber(q.vocalLow, 'vocalLow');
+  if (q.vocalHigh !== undefined) assertFiniteNumber(q.vocalHigh, 'vocalHigh');
+  if (q.vocalLow !== undefined && q.vocalHigh !== undefined && 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 !== undefined) {
+      assertFiniteNumber(voice.prevPitch, `otherVoices[${index}].prevPitch`);
+    }
+  }
+}
+
 /**
  * Core safety evaluation.
  *
@@ -239,9 +295,11 @@ function evaluateInternal(q: SafetyQuery, collectSuggestions: boolean): SafetyRe
     const pc = Math.abs(pitch - q.prevPitch) % 12;
     if (pc === 6) {
       reasons |= ReasonFlag.Tritone;
+      raise(NoteSafety.Dissonant);
     }
     if (isForbiddenMelodicLeap(q.prevPitch, pitch)) {
       reasons |= ReasonFlag.LargeLeap;
+      raise(parallelSeverity);
     }
     if (pc === 1) {
       reasons |= ReasonFlag.MinorSecond;
@@ -298,6 +356,12 @@ function evaluateInternal(q: SafetyQuery, collectSuggestions: boolean): SafetyRe
     }
   }
 
+  // Keep reason production and verdict policy as one invariant even when a new
+  // call path skips an earlier local `raise`: informational flags (ChordTone,
+  // MinorSecond, MajorSeventh) may coexist with Safe; every policy flag above
+  // contributes at least its table severity.
+  raise(minimumSafetyForReasons(reasons, q.profile));
+
   const result: SafetyResult = { safety: level, reasons, rationale: describe(reasons, q) };
   if (resolveTo !== undefined) {
     result.resolveTo = resolveTo;
@@ -382,6 +446,7 @@ function describe(reasons: number, q: SafetyQuery): string {
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.
  * @example
  * ```ts
  * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
@@ -399,11 +464,15 @@ export function enumerateSafePitches(
   pitchLow: number,
   pitchHigh: number,
 ): number[] {
+  assertSafetyContext(q);
   const chordTones: number[] = [];
   const others: number[] = [];
-  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 === NoteSafety.Dissonant) {

package/src/theory/scale/degrees.ts

@@ -0,0 +1,123 @@
+import type { KeyScale } from '../../core/types.js';
+
+/** Reduce a pitch (or pitch class) to a pitch class in [0, 11]. */
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+/** Scale offset of a pitch relative to the key root, in [0, 11]. */
+function scaleOffset(pitch: number, key: KeyScale): number {
+  return (pitchClass(pitch) - pitchClass(key.rootPc) + 12) % 12;
+}
+
+/**
+ * Test whether a pitch belongs to the scale.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to test against.
+ * @returns True if the pitch class is a member of the scale.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, isScaleTone } from '@libraz/libcantus';
+ * const key = majorKey(0); // C major
+ * isScaleTone(64, key); // true — E is in C major
+ * isScaleTone(61, key); // false — C# is not
+ * ```
+ *
+ * @category Scales
+ */
+export function isScaleTone(pitch: number, key: KeyScale): boolean {
+  return ((key.modeMask12 >> scaleOffset(pitch, key)) & 1) === 1;
+}
+
+/**
+ * Find the nearest MIDI pitch whose pitch class is in the scale.
+ *
+ * The search expands symmetrically outward from `pitch`. On a tie (equal
+ * distance above and below) the lower pitch is returned.
+ *
+ * @param pitch MIDI pitch to snap.
+ * @param key The key/scale to snap to.
+ * @returns The nearest in-scale MIDI pitch.
+ *
+ * @category Scales
+ */
+export function nearestScaleTone(pitch: number, key: KeyScale): number {
+  const base = Math.round(pitch);
+  for (let distance = 0; distance < 12; distance += 1) {
+    const lower = base - distance;
+    if (isScaleTone(lower, key)) {
+      return lower;
+    }
+    const higher = base + distance;
+    if (isScaleTone(higher, key)) {
+      return higher;
+    }
+  }
+  return base;
+}
+
+/**
+ * Get the 0-based scale degree of a pitch.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param key The key/scale to measure against.
+ * @returns The 0-based degree, or -1 if the pitch is not in the scale.
+ *
+ * @category Scales
+ */
+export function pitchToScaleDegree(pitch: number, key: KeyScale): number {
+  const offset = scaleOffset(pitch, key);
+  if (((key.modeMask12 >> offset) & 1) === 0) {
+    return -1;
+  }
+  let degree = 0;
+  for (let n = 0; n < offset; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      degree += 1;
+    }
+  }
+  return degree;
+}
+
+/**
+ * List the pitch classes of a key's scale.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
+ */
+export function diatonicPitchClasses(key: KeyScale): number[] {
+  const root = pitchClass(key.rootPc);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs.sort((a, b) => a - b);
+}
+
+/**
+ * List the pitch classes of a key's scale in ascending scale-degree order.
+ *
+ * Degree 0 is the root; degrees follow the mask bits in offset order rather
+ * than sorted pitch-class order.
+ *
+ * @param key The key/scale to enumerate.
+ * @returns The member pitch classes ordered by scale degree.
+ *
+ * @category Scales
+ */
+export function scaleTonesInDegreeOrder(key: KeyScale): number[] {
+  const root = pitchClass(key.rootPc);
+  const pcs: number[] = [];
+  for (let n = 0; n < 12; n += 1) {
+    if (((key.modeMask12 >> n) & 1) === 1) {
+      pcs.push((root + n) % 12);
+    }
+  }
+  return pcs;
+}

package/src/theory/scale/index.ts

@@ -0,0 +1,28 @@
+export {
+  diatonicPitchClasses,
+  isScaleTone,
+  nearestScaleTone,
+  pitchToScaleDegree,
+  scaleTonesInDegreeOrder,
+} from './degrees.js';
+export { majorKey, minorKey, scaleByName } from './key.js';
+export {
+  BLUES_MASK,
+  CHROMATIC_MASK,
+  DORIAN_MASK,
+  HARMONIC_MINOR_MASK,
+  LOCRIAN_MASK,
+  LYDIAN_MASK,
+  MAJOR_MASK,
+  MAJOR_PENTATONIC_MASK,
+  MELODIC_MINOR_MASK,
+  MINOR_PENTATONIC_MASK,
+  MIXOLYDIAN_MASK,
+  maskFromOffsets,
+  NAMED_SCALES,
+  NATURAL_MINOR_MASK,
+  OCTATONIC_HALF_WHOLE_MASK,
+  OCTATONIC_WHOLE_HALF_MASK,
+  PHRYGIAN_MASK,
+  WHOLE_TONE_MASK,
+} from './masks.js';

package/src/theory/scale/key.ts

@@ -0,0 +1,56 @@
+import type { KeyScale } from '../../core/types.js';
+import { MAJOR_MASK, NAMED_SCALES, NATURAL_MINOR_MASK } from './masks.js';
+
+/**
+ * Build a `KeyScale` for a major key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { majorKey } from '@libraz/libcantus';
+ * const cMajor = majorKey(0); // C major: { rootPc: 0, modeMask12: MAJOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
+export function majorKey(rootPc: number): KeyScale {
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: MAJOR_MASK };
+}
+
+/**
+ * Build a `KeyScale` for a natural-minor key on the given root pitch class.
+ *
+ * @example
+ * ```ts
+ * import { minorKey } from '@libraz/libcantus';
+ * const aMinor = minorKey(9); // A natural minor: { rootPc: 9, modeMask12: NATURAL_MINOR_MASK }
+ * ```
+ *
+ * @category Scales
+ */
+export function minorKey(rootPc: number): KeyScale {
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: NATURAL_MINOR_MASK };
+}
+
+/**
+ * Build a `KeyScale` from a named scale (see {@link NAMED_SCALES}).
+ *
+ * @param name The scale name, e.g. `'dorian'` or `'harmonicMinor'`.
+ * @param rootPc The root pitch class.
+ * @returns The key/scale.
+ * @throws If the name is not a known scale.
+ *
+ * @example
+ * ```ts
+ * import { scaleByName } from '@libraz/libcantus';
+ * const dDorian = scaleByName('dorian', 2); // D Dorian, rootPc 2
+ * ```
+ *
+ * @category Scales
+ */
+export function scaleByName(name: string, rootPc: number): KeyScale {
+  const mask = NAMED_SCALES[name];
+  if (mask === undefined) {
+    throw new Error(`Unknown scale: ${name}`);
+  }
+  return { rootPc: ((rootPc % 12) + 12) % 12, modeMask12: mask };
+}