@libraz/libcantus 0.9.1 → 0.9.2

package/src/analyze/arrange/tracks.ts

@@ -0,0 +1,279 @@
+/**
+ * Arrangement track-role analysis: a single harmony is inferred from every
+ * track's notes pooled together, each track is then analysed against that shared
+ * harmony, and notes that clash with the sounding chord are collected as
+ * conflicts.
+ */
+
+import { isStrongBeat, parseTimeSignature, type TimeSignature } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  evaluateSafety,
+  NoteSafety,
+  type SafetyProfile,
+  type VoiceSnapshot,
+} from '../../theory/safety/index.js';
+import {
+  type CadenceHit,
+  type ChordTimeline,
+  chordTimelineFromNotes,
+  detectCadences,
+} from '../timeline/index.js';
+import { type AnalyzedNote, analyzeVoice, type VoiceNote } from '../voice/index.js';
+import { covers, EPS, type PreparedTrack, poolNotes, prepareTracks } from './internal.js';
+
+/**
+ * The musical role a track plays in the arrangement.
+ *
+ * @category Arrangement & Analysis
+ */
+export type TrackRole = 'melody' | 'harmony' | 'bass' | 'other';
+
+/**
+ * One input track: its notes plus optional name and role.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementTrack = {
+  name?: string;
+  role?: TrackRole;
+  notes: NoteEvent[];
+};
+
+/**
+ * A track after analysis: its resolved name, role, and per-note annotations.
+ *
+ * @category Arrangement & Analysis
+ */
+export type TrackAnalysis = {
+  name: string;
+  role: TrackRole;
+  /** One {@link AnalyzedNote} per note, labelled against the inferred chords. */
+  notes: AnalyzedNote[];
+};
+
+/**
+ * A note that clashes with the harmony sounding beneath it.
+ *
+ * @category Arrangement & Analysis
+ */
+export type Conflict = {
+  beat: number;
+  trackName: string;
+  pitch: number;
+  /** The clash severity: {@link NoteSafety.Warning} or {@link NoteSafety.Dissonant}. */
+  safety: NoteSafety;
+  /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
+  reasons: number;
+  rationale?: string;
+};
+
+/**
+ * The full result of {@link analyzeArrangement}.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementAnalysis = {
+  key: KeyScale;
+  timeline: ChordTimeline;
+  segmentConfidence: number[];
+  cadences: CadenceHit[];
+  tracks: TrackAnalysis[];
+  /** Notes clashing with the sounding harmony, worst severity first. */
+  conflicts: Conflict[];
+};
+
+/**
+ * Options controlling {@link analyzeArrangement} and {@link tensionCurve}.
+ *
+ * @category Arrangement & Analysis
+ */
+export type ArrangementOptions = {
+  /** Key context; inferred from the pooled notes when omitted. */
+  key?: KeyScale;
+  /**
+   * Time signature; defaults to 4/4.
+   *
+   * @defaultValue `4/4`
+   */
+  ts?: TimeSignature;
+  /**
+   * Chord-slot length in beats; defaults to one bar of `ts`.
+   *
+   * @defaultValue one bar of `ts`
+   */
+  harmonicRhythm?: number;
+  /**
+   * Safety profile used for conflict detection; defaults to `pop`.
+   *
+   * @defaultValue `'pop'`
+   */
+  profile?: SafetyProfile;
+};
+
+/**
+ * Sounding pitches of every sub-voice at a beat, excluding one sub-voice.
+ *
+ * Only the sub-voice under analysis is excluded — sibling sub-voices of the
+ * same track are included, so dissonant clusters inside a single polyphonic
+ * track are still detected.
+ */
+function otherVoicesSounding(
+  prepared: PreparedTrack[],
+  excludeTrack: number,
+  excludeVoice: number,
+  beat: number,
+): VoiceSnapshot[] {
+  const out: VoiceSnapshot[] = [];
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    for (let v = 0; v < track.voices.length; v += 1) {
+      if (t === excludeTrack && v === excludeVoice) {
+        continue;
+      }
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      for (const note of subVoice.sounding) {
+        if (!covers(note, beat)) {
+          continue;
+        }
+        const snap: VoiceSnapshot = { pitch: note.pitch };
+        if (note.prevPitch !== undefined) {
+          snap.prevPitch = note.prevPitch;
+        }
+        out.push(snap);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The beats at which a note must be checked against the harmony: its onset,
+ * plus the onset of every later chord segment the note sustains across. Each
+ * crossed segment is visited exactly once (at its own start), so a boundary
+ * beat is never evaluated twice for the same note.
+ */
+function evaluationBeats(note: VoiceNote, timeline: ChordTimeline): number[] {
+  const noteEnd = note.startBeat + note.durationBeat;
+  const beats = [note.startBeat];
+  for (const segment of timeline.segments) {
+    if (segment.startBeat > note.startBeat + EPS && segment.startBeat < noteEnd - EPS) {
+      beats.push(segment.startBeat);
+    }
+  }
+  return beats;
+}
+
+/**
+ * Analyse a whole arrangement against a single inferred harmony.
+ *
+ * The chord timeline and key are inferred from the pooled notes of every track
+ * (see {@link chordTimelineFromNotes}); pooling all voices is robust even when
+ * roles are absent or a track doubles the harmony, so it is preferred over
+ * deriving the harmony from a subset. Zero- and negative-length notes never
+ * sound, so they are dropped at ingest and appear in neither the annotations
+ * nor the conflicts.
+ *
+ * Voice analysis assumes one monophonic voice at a time, so each track is
+ * first partitioned into monophonic sub-voices (a polyphonic block-chord track
+ * fans out into one sub-voice per simultaneous note; a monophonic track is
+ * unaffected). Each sub-voice is labelled note-by-note against the harmony
+ * with {@link analyzeVoice}, seeing every other sub-voice — including siblings
+ * within the same track — as its accompaniment. Every note is then re-checked
+ * with {@link evaluateSafety} at its onset and again at each chord change it
+ * sustains across, so a held note that clashes with a later chord is caught:
+ * evaluations that are not {@link NoteSafety.Safe} become conflicts, one per
+ * clashing beat, sorted worst severity first and then by beat.
+ *
+ * @param tracks The tracks to analyse.
+ * @param opts Analysis options; see {@link ArrangementOptions}.
+ * @returns The inferred harmony, per-track annotations, cadences, and conflicts.
+ * @example
+ * ```ts
+ * import { analyzeArrangement } from '@libraz/libcantus';
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 2 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 2 },
+ * ];
+ * const { key, conflicts } = analyzeArrangement([{ role: 'melody', notes: melody }]);
+ * conflicts; // notes clashing with the inferred harmony, worst severity first
+ * ```
+ * @category Arrangement & Analysis
+ */
+export function analyzeArrangement(
+  tracks: ArrangementTrack[],
+  opts: ArrangementOptions = {},
+): ArrangementAnalysis {
+  const ts = opts.ts ?? parseTimeSignature('4/4');
+  const profile: SafetyProfile = opts.profile ?? 'pop';
+  const pooled = poolNotes(tracks);
+
+  const { timeline, key, segmentConfidence } = chordTimelineFromNotes(pooled, {
+    key: opts.key,
+    ts,
+    harmonicRhythm: opts.harmonicRhythm,
+  });
+  const cadences = detectCadences(timeline, key);
+  const prepared = prepareTracks(tracks);
+
+  const trackAnalyses: TrackAnalysis[] = [];
+  const conflicts: Conflict[] = [];
+
+  for (let t = 0; t < prepared.length; t += 1) {
+    const track = prepared[t];
+    if (!track) {
+      continue;
+    }
+    const notes: AnalyzedNote[] = [];
+    for (let v = 0; v < track.voices.length; v += 1) {
+      const subVoice = track.voices[v];
+      if (!subVoice) {
+        continue;
+      }
+      notes.push(
+        ...analyzeVoice(subVoice.voice, timeline.at, key, (beat) =>
+          otherVoicesSounding(prepared, t, v, beat),
+        ),
+      );
+
+      for (const note of subVoice.voice) {
+        for (const beat of evaluationBeats(note, timeline)) {
+          const result = evaluateSafety({
+            profile,
+            candidatePitch: note.pitch,
+            chord: timeline.at(beat),
+            key,
+            otherVoices: otherVoicesSounding(prepared, t, v, beat),
+            strongBeat: isStrongBeat(beat, ts),
+          });
+          if (result.safety !== NoteSafety.Safe) {
+            const conflict: Conflict = {
+              beat,
+              trackName: track.name,
+              pitch: note.pitch,
+              safety: result.safety,
+              reasons: result.reasons,
+            };
+            if (result.rationale !== undefined) {
+              conflict.rationale = result.rationale;
+            }
+            conflicts.push(conflict);
+          }
+        }
+      }
+    }
+    // Sub-voice results interleave; restore the track's onset-then-pitch order.
+    notes.sort((a, b) => a.noteId - b.noteId);
+    trackAnalyses.push({ name: track.name, role: track.role, notes });
+  }
+
+  conflicts.sort((a, b) => b.safety - a.safety || a.beat - b.beat);
+
+  return { key, timeline, segmentConfidence, cadences, tracks: trackAnalyses, conflicts };
+}

package/src/{detect → analyze/detect}/index.ts

@@ -4,8 +4,9 @@
  * which only go name -> notes.
  */
 
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, chordQualities, makeChord } from '../chord/index.js';
+import type { KeyScale } from '../../core/types.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { chordPitchClasses, chordQualities, makeChord } from '../../theory/chord/index.js';
 import {
   HARMONIC_MINOR_MASK,
   MAJOR_MASK,
@@ -13,8 +14,7 @@ import {
   majorKey,
   minorKey,
   NATURAL_MINOR_MASK,
-} from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+} from '../../theory/scale/index.js';
 
 /**
  * A candidate chord interpretation of a pitch set.

package/src/analyze/functional/borrowed.ts

@@ -0,0 +1,84 @@
+/**
+ * Borrowed chords (modal interchange) and the Neapolitan.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { HARMONIC_MINOR_MASK } from '../../theory/scale/index.js';
+import { isDiatonic, isMinorKey, parallelKey } from './function.js';
+import { isNeapolitan, mod12 } from './internal.js';
+
+/**
+ * The origin of a recognized non-diatonic chord, or null when none applies.
+ *
+ * @category Functional Harmony
+ */
+export type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+
+/**
+ * In a minor key, whether a non-diatonic chord is explained by the harmonic
+ * minor scale on the same tonic (major V, V7, the raised-leading-tone viio).
+ * Such chords are in-key chromatic alterations, not modal interchange.
+ */
+function isHarmonicMinorAlteration(chord: Chord, key: KeyScale): boolean {
+  return (
+    isMinorKey(key) &&
+    isDiatonic(chord, { rootPc: mod12(key.rootPc), modeMask12: HARMONIC_MINOR_MASK })
+  );
+}
+
+/**
+ * Whether a chord is borrowed from the parallel mode (modal interchange).
+ *
+ * True when the chord is not diatonic to `key` but is diatonic to its
+ * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
+ * tonic and major IV in a minor key. Two non-diatonic families are excluded:
+ * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
+ * a minor key, chords explained by the harmonic minor scale (the major
+ * dominant and raised-leading-tone chords), which are in-key alterations
+ * rather than interchange even though they happen to fit the parallel major.
+ *
+ * @param chord The chord to test.
+ * @param key The prevailing key.
+ * @returns True if the chord is borrowed from the parallel mode.
+ * @category Functional Harmony
+ */
+export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
+  if (isDiatonic(chord, key)) {
+    return false;
+  }
+  if (isHarmonicMinorAlteration(chord, key)) {
+    return false;
+  }
+  return isDiatonic(chord, parallelKey(key));
+}
+
+/**
+ * Identify where a non-diatonic chord comes from.
+ *
+ * The Neapolitan (major triad on b2) is recognized first, since it sits
+ * outside both parallel modes; parallel-mode borrowing follows the
+ * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * and unrecognized chromatic chords all yield null.
+ *
+ * @param chord The chord to classify.
+ * @param key The prevailing key.
+ * @returns The borrowing source, or null.
+ * @category Functional Harmony
+ */
+export function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {
+  if (isDiatonic(chord, key)) {
+    return null;
+  }
+  if (isNeapolitan(chord, key)) {
+    return 'neapolitan';
+  }
+  if (isBorrowedChord(chord, key)) {
+    return isMinorKey(key) ? 'parallel-major' : 'parallel-minor';
+  }
+  return null;
+}

package/src/analyze/functional/cadence.ts

@@ -0,0 +1,66 @@
+/**
+ * Cadence detection between two successive chords.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { isMinorKey } from './function.js';
+import { mod12 } from './internal.js';
+
+/**
+ * A recognized cadence type, or null when a chord pair forms none.
+ *
+ * @category Functional Harmony
+ */
+export type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
+
+/**
+ * Classify the cadence formed by moving from one chord to the next.
+ *
+ * - authentic: V (dominant a fifth above the tonic) to I
+ * - plagal: IV (a fourth above the tonic) to I
+ * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
+ *   minor)
+ * - half: any chord other than the dominant itself to V
+ *
+ * A static V-to-V repeat with no root motion is not a cadence and yields null.
+ *
+ * @param from The penultimate chord.
+ * @param to The final chord.
+ * @param key The prevailing key.
+ * @returns The cadence type, or null.
+ * @example
+ * ```ts
+ * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
+ * ```
+ * @category Functional Harmony
+ */
+export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
+  const tonic = mod12(key.rootPc);
+  const fromOffset = mod12(from.rootPc - tonic);
+  const toOffset = mod12(to.rootPc - tonic);
+  // Deceptive targets: the diatonic submediant (vi at offset 9 in major, VI at
+  // offset 8 in minor) plus, in a major key, the borrowed flat-submediant bVI
+  // at offset 8.
+  const deceptiveTargets = isMinorKey(key) ? [8] : [8, 9];
+  if (fromOffset === 7 && toOffset === 0) {
+    return 'authentic';
+  }
+  if (fromOffset === 5 && toOffset === 0) {
+    return 'plagal';
+  }
+  if (fromOffset === 7 && deceptiveTargets.includes(toOffset)) {
+    return 'deceptive';
+  }
+  // A move to the dominant is a half cadence, but a no-root-motion V-to-V repeat
+  // is not a cadence at all.
+  if (toOffset === 7 && fromOffset !== 7) {
+    return 'half';
+  }
+  return null;
+}

package/src/analyze/functional/function.ts

@@ -0,0 +1,184 @@
+/**
+ * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
+ * mirroring, and full chord analysis.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
+import { isScaleTone, MAJOR_MASK, NATURAL_MINOR_MASK } from '../../theory/scale/index.js';
+import { type BorrowedSource, borrowedSource } from './borrowed.js';
+import { degreeRootPc, isNeapolitan, mod12 } from './internal.js';
+import { chordToRoman } from './roman.js';
+
+/**
+ * The three broad harmonic functions of tonal music.
+ *
+ * @category Functional Harmony
+ */
+export type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
+
+/** Harmonic function of each semitone offset above the tonic (major context). */
+const FUNCTION_BY_OFFSET: readonly HarmonicFunction[] = [
+  'tonic', // 0  I
+  'subdominant', // 1  bII (Neapolitan)
+  'subdominant', // 2  ii
+  'tonic', // 3  bIII
+  'tonic', // 4  iii
+  'subdominant', // 5  IV
+  'dominant', // 6  #IV / bV
+  'dominant', // 7  V
+  'subdominant', // 8  bVI
+  'tonic', // 9  vi
+  'subdominant', // 10 bVII
+  'dominant', // 11 vii
+];
+
+/**
+ * Whether a key's scale has a minor third and no major third (a minor key).
+ *
+ * @category Functional Harmony
+ */
+export function isMinorKey(key: KeyScale): boolean {
+  const hasMinorThird = (key.modeMask12 >> 3) & 1;
+  const hasMajorThird = (key.modeMask12 >> 4) & 1;
+  return Boolean(hasMinorThird) && !hasMajorThird;
+}
+
+/**
+ * The harmonic function of a chord in a key, from its root's offset above the
+ * tonic. The mapping follows common-practice major-key function and is a useful
+ * approximation in minor and for borrowed chords.
+ *
+ * @param chord The chord.
+ * @param key The prevailing key.
+ * @returns The harmonic function.
+ * @category Functional Harmony
+ */
+export function functionOf(chord: Chord, key: KeyScale): HarmonicFunction {
+  return FUNCTION_BY_OFFSET[mod12(chord.rootPc - key.rootPc)] ?? 'tonic';
+}
+
+/**
+ * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
+ *
+ * @category Functional Harmony
+ */
+export type ChordAnalysis = {
+  function: HarmonicFunction;
+  borrowed: boolean;
+  source: BorrowedSource;
+  roman: string;
+};
+
+/**
+ * Whether every pitch class of a chord belongs to the key's scale.
+ *
+ * The test is strict against the key's own mode mask: in a natural-minor key
+ * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
+ * leading tone lies outside the mask. Borrowing predicates treat that case as
+ * an in-key alteration separately (see {@link isBorrowedChord}).
+ *
+ * @param chord The chord to test.
+ * @param key The prevailing key.
+ * @returns True if all chord pitch classes are scale tones.
+ * @category Functional Harmony
+ */
+export function isDiatonic(chord: Chord, key: KeyScale): boolean {
+  return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));
+}
+
+/**
+ * The parallel key: same tonic, opposite mode.
+ *
+ * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
+ * maps to the parallel major; any other key maps to the parallel natural minor.
+ *
+ * @param key The key to mirror.
+ * @returns The parallel major or natural-minor key on the same tonic.
+ * @category Functional Harmony
+ */
+export function parallelKey(key: KeyScale): KeyScale {
+  return {
+    rootPc: mod12(key.rootPc),
+    modeMask12: isMinorKey(key) ? MAJOR_MASK : NATURAL_MINOR_MASK,
+  };
+}
+
+/** Diminished-family qualities: diminished triad, dim7, half-diminished. */
+function isDiminishedQuality(quality: ChordQuality): boolean {
+  return quality === 'dim' || quality === 'dim7' || quality === 'm7b5';
+}
+
+/** Whether the chord's interval template carries a major third above the root. */
+function hasMajorThird(chord: Chord): boolean {
+  return chord.intervals.some((interval) => mod12(interval) === 4);
+}
+
+/**
+ * Quality-aware harmonic function, refining the offset table where chord
+ * quality disambiguates: diminished chords on the leading tone or the raised
+ * subdominant resolve by semitone and act as dominants; the Neapolitan and the
+ * major-third chords on bVI/bVII borrowed from the parallel minor act as
+ * subdominant (predominant) harmony. All other chords keep {@link functionOf}.
+ */
+function qualityAwareFunction(chord: Chord, key: KeyScale): HarmonicFunction {
+  const offset = mod12(chord.rootPc - key.rootPc);
+  if (isDiminishedQuality(chord.quality) && (offset === 11 || offset === 6)) {
+    return 'dominant';
+  }
+  if (isNeapolitan(chord, key)) {
+    return 'subdominant';
+  }
+  if (!isMinorKey(key) && hasMajorThird(chord) && (offset === 8 || offset === 10)) {
+    return 'subdominant';
+  }
+  return functionOf(chord, key);
+}
+
+/**
+ * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
+ *
+ * The function is quality-aware (see the predicates behind it), the source
+ * follows {@link borrowedSource}, and the numeral comes from
+ * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
+ * including the Neapolitan, which the stricter parallel-mode predicate
+ * {@link isBorrowedChord} does not count.
+ *
+ * @param chord The chord to analyze.
+ * @param key The prevailing key.
+ * @returns The chord analysis.
+ * @example
+ * ```ts
+ * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
+ * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
+ * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
+ * ```
+ * @category Functional Harmony
+ */
+export function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {
+  const source = borrowedSource(chord, key);
+  return {
+    function: qualityAwareFunction(chord, key),
+    borrowed: source !== null,
+    source,
+    roman: chordToRoman(chord, key),
+  };
+}
+
+/**
+ * The secondary dominant (V7) that tonicizes a scale degree.
+ *
+ * @param targetDegree 0-based scale degree to tonicize.
+ * @param key The prevailing key.
+ * @returns A dominant-seventh chord a fifth above the target's root.
+ * @category Functional Harmony
+ */
+export function secondaryDominant(targetDegree: number, key: KeyScale): Chord {
+  const targetRoot = degreeRootPc(targetDegree + 1, key);
+  return makeChord(mod12(targetRoot + 7), 'dom7');
+}

package/src/analyze/functional/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Functional harmony: Roman-numeral parsing and formatting, harmonic function
+ * (tonic / subdominant / dominant), cadence detection, and borrowed chords.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+export type { BorrowedSource } from './borrowed.js';
+export { borrowedSource, isBorrowedChord } from './borrowed.js';
+export type { Cadence } from './cadence.js';
+export { detectCadence } from './cadence.js';
+export type { ChordAnalysis, HarmonicFunction } from './function.js';
+export {
+  analyzeChord,
+  functionOf,
+  isDiatonic,
+  isMinorKey,
+  parallelKey,
+  secondaryDominant,
+} from './function.js';
+export { chordToRoman, romanToChord } from './roman.js';

package/src/analyze/functional/internal.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared helpers for the functional-harmony modules.
+ *
+ * Roots are pitch classes measured against the key tonic, so borrowed and
+ * chromatic chords are handled by their semitone offset rather than requiring a
+ * spelled key signature.
+ */
+
+import type { KeyScale } from '../../core/types.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
+
+export function mod12(n: number): number {
+  return ((n % 12) + 12) % 12;
+}
+
+/** Diatonic pitch class of a 1-based scale degree in a key. */
+export function degreeRootPc(degreeNumber: number, key: KeyScale): number {
+  const tones = scaleTonesInDegreeOrder(key);
+  if (tones.length === 0) {
+    return mod12(key.rootPc);
+  }
+  return tones[(degreeNumber - 1) % tones.length] ?? mod12(key.rootPc);
+}
+
+/** Whether a chord is the Neapolitan: a major triad on the flat second degree. */
+export function isNeapolitan(chord: Chord, key: KeyScale): boolean {
+  return mod12(chord.rootPc - key.rootPc) === 1 && chord.quality === 'maj';
+}