@libraz/libcantus 0.9.2 → 0.9.3

package/dist/chunk-CHMXELDS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/analyze/functional/internal.ts","../src/analyze/functional/roman.ts","../src/analyze/functional/borrowed.ts","../src/analyze/functional/function.ts","../src/analyze/functional/cadence.ts","../src/analyze/detect/index.ts"],"sourcesContent":["/**\n * Shared helpers for the functional-harmony modules.\n *\n * Roots are pitch classes measured against the key tonic, so borrowed and\n * chromatic chords are handled by their semitone offset rather than requiring a\n * spelled key signature.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport type { Chord } from '../../theory/chord/index.js';\nimport { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';\n\nexport function mod12(n: number): number {\n  return ((n % 12) + 12) % 12;\n}\n\n/** Diatonic pitch class of a 1-based scale degree in a key. */\nexport function degreeRootPc(degreeNumber: number, key: KeyScale): number {\n  const tones = scaleTonesInDegreeOrder(key);\n  if (tones.length === 0) {\n    return mod12(key.rootPc);\n  }\n  return tones[(degreeNumber - 1) % tones.length] ?? mod12(key.rootPc);\n}\n\n/** Whether a chord is the Neapolitan: a major triad on the flat second degree. */\nexport function isNeapolitan(chord: Chord, key: KeyScale): boolean {\n  return mod12(chord.rootPc - key.rootPc) === 1 && chord.quality === 'maj';\n}\n","/**\n * Roman-numeral parsing and formatting.\n *\n * The {@link ROMAN_STYLE} table is the single source of truth for both\n * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual\n * inverses by construction.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport type { Chord, ChordQuality } from '../../theory/chord/index.js';\nimport { makeChord } from '../../theory/chord/index.js';\nimport { majorKey, scaleTonesInDegreeOrder } from '../../theory/scale/index.js';\nimport { degreeRootPc, mod12 } from './internal.js';\n\n/** Roman numeral glyphs indexed by degree number - 1. */\nconst ROMAN = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII'] as const;\n\n/** Roman glyph -> degree number (1..7). */\nconst ROMAN_TO_DEGREE: Record<string, number> = {\n  I: 1,\n  II: 2,\n  III: 3,\n  IV: 4,\n  V: 5,\n  VI: 6,\n  VII: 7,\n};\n\n/** Major-key Roman spelling for each semitone offset above the tonic. */\nconst OFFSET_SPELLING: readonly [number, string][] = [\n  [1, ''],\n  [2, 'b'],\n  [2, ''],\n  [3, 'b'],\n  [3, ''],\n  [4, ''],\n  [4, '#'],\n  [5, ''],\n  [6, 'b'],\n  [6, ''],\n  [7, 'b'],\n  [7, ''],\n];\n\n/** Choose a seventh-chord quality from a triad label and the numeral case. */\nfunction seventhQuality(base: 'maj' | 'min' | 'dim' | 'aug', halfDim: boolean): ChordQuality {\n  if (halfDim) {\n    return 'm7b5';\n  }\n  if (base === 'dim') {\n    return 'dim7';\n  }\n  if (base === 'aug') {\n    return 'aug7';\n  }\n  return base === 'maj' ? 'dom7' : 'min7';\n}\n\n/** Figure strings that denote a recognized figured-bass inversion. */\nconst INVERSION_FIGURES = new Set(['6', '64', '65', '43', '42', '2', '7']);\n\n/**\n * Canonical Roman-numeral rendering (numeral case and quality suffix) for every\n * supported chord quality. The table is the single source of truth for both\n * directions: {@link chordToRoman} renders from it and {@link romanToChord}\n * recognizes its exact case-sensitive suffixes, so the two stay mutual\n * inverses by construction. Suffixes are chosen to never collide with\n * figured-bass inversion digits (`6`, `64`, `65`, `43`, `42`, `2`) — the added\n * sixth is `add6`, the six-nine chord is `69` — and each (case, suffix) pair is\n * unique.\n */\nconst ROMAN_STYLE: Record<ChordQuality, { lower: boolean; suffix: string }> = {\n  maj: { lower: false, suffix: '' },\n  min: { lower: true, suffix: '' },\n  dim: { lower: true, suffix: 'o' },\n  aug: { lower: false, suffix: '+' },\n  maj7: { lower: false, suffix: 'maj7' },\n  min7: { lower: true, suffix: '7' },\n  dom7: { lower: false, suffix: '7' },\n  dim7: { lower: true, suffix: 'o7' },\n  m7b5: { lower: true, suffix: 'ø7' },\n  minMaj7: { lower: true, suffix: 'maj7' },\n  aug7: { lower: false, suffix: '+7' },\n  augMaj7: { lower: false, suffix: '+maj7' },\n  majb5: { lower: false, suffix: 'b5' },\n  '6': { lower: false, suffix: 'add6' },\n  min6: { lower: true, suffix: 'add6' },\n  '6/9': { lower: false, suffix: '69' },\n  sus2: { lower: false, suffix: 'sus2' },\n  sus4: { lower: false, suffix: 'sus4' },\n  add9: { lower: false, suffix: 'add9' },\n  add11: { lower: false, suffix: 'add11' },\n  maj9: { lower: false, suffix: 'maj9' },\n  min9: { lower: true, suffix: '9' },\n  dom9: { lower: false, suffix: '9' },\n  '7b9': { lower: false, suffix: '7b9' },\n  '7#9': { lower: false, suffix: '7#9' },\n  '7#11': { lower: false, suffix: '7#11' },\n  '7b13': { lower: false, suffix: '7b13' },\n  '11': { lower: false, suffix: '11' },\n  '13': { lower: false, suffix: '13' },\n  '5': { lower: false, suffix: '5' },\n};\n\n/** Reverse lookup of {@link ROMAN_STYLE}: `(case, exact suffix) -> quality`. */\nconst SUFFIX_QUALITY: ReadonlyMap<string, ChordQuality> = new Map(\n  (Object.entries(ROMAN_STYLE) as [ChordQuality, { lower: boolean; suffix: string }][]).map(\n    ([quality, style]) => [`${style.lower ? 'l' : 'u'}:${style.suffix}`, quality],\n  ),\n);\n\n/** Read figured-bass digits into a chord inversion and whether a seventh is implied. */\nfunction parseInversion(figures: string): { inversion: number; seventh: boolean } {\n  if (figures === '65') {\n    return { inversion: 1, seventh: true };\n  }\n  if (figures === '43') {\n    return { inversion: 2, seventh: true };\n  }\n  if (figures === '42' || figures === '2') {\n    return { inversion: 3, seventh: true };\n  }\n  if (figures === '7') {\n    return { inversion: 0, seventh: true };\n  }\n  if (figures === '64') {\n    return { inversion: 2, seventh: false };\n  }\n  if (figures === '6') {\n    return { inversion: 1, seventh: false };\n  }\n  return { inversion: 0, seventh: false };\n}\n\n/** Parse a Roman numeral (no secondary '/') into a root, quality, and inversion. */\nfunction parseSimpleRoman(\n  text: string,\n  key: KeyScale,\n): { rootPc: number; quality: ChordQuality; inversion: number } {\n  const match = /^([b#]?)([iIvV]+)(.*)$/.exec(text.trim());\n  if (!match) {\n    throw new Error(`Invalid Roman numeral: ${text}`);\n  }\n  const accidental = match[1] === 'b' ? -1 : match[1] === '#' ? 1 : 0;\n  const glyph = (match[2] ?? '').toUpperCase();\n  const degreeNumber = ROMAN_TO_DEGREE[glyph];\n  if (degreeNumber === undefined) {\n    throw new Error(`Invalid Roman numeral: ${text}`);\n  }\n  const isUpper = (match[2] ?? '')[0] === (match[2] ?? '')[0]?.toUpperCase();\n  const suffix = match[3] ?? '';\n  const rootPc = mod12(degreeRootPc(degreeNumber, key) + accidental);\n\n  // Canonical quality suffixes (exact match, case-sensitive on the numeral)\n  // come first so every chordToRoman rendering re-parses to the same quality:\n  // `V9` -> dom9 but `ii9` -> min9 and `Imaj9` -> maj9, and added-tone suffixes\n  // whose digits would otherwise be misread as figured bass (`Iadd6`, `I69`,\n  // `Isus2`, `Iadd11`) resolve to their qualities in root position.\n  const canonical = SUFFIX_QUALITY.get(`${isUpper ? 'u' : 'l'}:${suffix}`);\n  if (canonical !== undefined) {\n    return { rootPc, quality: canonical, inversion: 0 };\n  }\n\n  // Non-canonical spellings are limited to a complete quality marker followed\n  // by an optional major-seventh marker and a recognized figured bass. Never\n  // search substrings: `Vfoo` must not become diminished merely because it\n  // contains an \"o\", and unknown trailing text must be rejected in full.\n  const parsedSuffix = /^(o|°|dim|ø|\\+|aug)?(maj7|M7)?(65|64|43|42|7|6|2)?$/.exec(suffix);\n  if (!parsedSuffix) {\n    throw new Error(`Unsupported suffix \"${suffix}\" in Roman numeral: ${text}`);\n  }\n  const qualityMarker = parsedSuffix[1] ?? '';\n  const isDim = qualityMarker === 'o' || qualityMarker === '°' || qualityMarker === 'dim';\n  const isAug = qualityMarker === '+' || qualityMarker === 'aug';\n  const isHalfDim = qualityMarker === 'ø';\n  const explicitMaj7 = parsedSuffix[2] !== undefined;\n  const figures = parsedSuffix[3] ?? '';\n\n  // Reject figure strings that are neither a known figured-bass inversion nor a\n  // canonical quality suffix rather than silently degrading to a root triad.\n  if (figures !== '' && !INVERSION_FIGURES.has(figures)) {\n    throw new Error(`Unsupported figured-bass or extension \"${figures}\" in Roman numeral: ${text}`);\n  }\n\n  const { inversion, seventh } = parseInversion(figures);\n  // The ø glyph is the half-diminished seventh by definition (there is no\n  // half-diminished triad), so it always implies a seventh.\n  const hasSeventh = explicitMaj7 || seventh || isHalfDim;\n\n  let base: 'maj' | 'min' | 'dim' | 'aug';\n  if (isDim || isHalfDim) {\n    base = 'dim';\n  } else if (isAug) {\n    base = 'aug';\n  } else {\n    base = isUpper ? 'maj' : 'min';\n  }\n\n  let quality: ChordQuality;\n  if (explicitMaj7) {\n    quality = base === 'min' ? 'minMaj7' : base === 'aug' ? 'augMaj7' : 'maj7';\n  } else if (hasSeventh) {\n    quality = seventhQuality(base, isHalfDim);\n  } else if (base === 'dim') {\n    quality = 'dim';\n  } else if (base === 'aug') {\n    quality = 'aug';\n  } else {\n    quality = base;\n  }\n  return { rootPc, quality, inversion };\n}\n\n/** Build a chord from a parsed Roman numeral, attaching a bass for inversions. */\nfunction chordFromParsed(parsed: {\n  rootPc: number;\n  quality: ChordQuality;\n  inversion: number;\n}): Chord {\n  const chord = makeChord(parsed.rootPc, parsed.quality);\n  if (parsed.inversion > 0 && parsed.inversion < chord.intervals.length) {\n    chord.bassPc = mod12(parsed.rootPc + (chord.intervals[parsed.inversion] ?? 0));\n  }\n  return chord;\n}\n\n/**\n * Build the chord denoted by a Roman numeral in a key.\n *\n * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`\n * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions\n * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash\n * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree\n * whose root becomes a local major tonic for the applied chord. Inverted chords\n * carry a `bassPc`.\n *\n * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==\n * `m7b5`), since no half-diminished triad exists. Extension and added-tone\n * suffixes are the canonical case-sensitive forms emitted by\n * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->\n * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->\n * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->\n * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.\n * A figure string that is neither a recognized inversion nor a supported\n * quality suffix throws rather than silently degrading to a triad.\n *\n * @param text The Roman numeral.\n * @param key The prevailing key.\n * @returns The chord.\n * @example\n * ```ts\n * import { romanToChord, majorKey } from '@libraz/libcantus';\n * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }\n * ```\n * @category Functional Harmony\n */\nexport function romanToChord(text: string, key: KeyScale): Chord {\n  const trimmed = text.trim();\n  const slash = trimmed.indexOf('/');\n  if (slash >= 0) {\n    const applied = trimmed.slice(0, slash);\n    const target = trimmed.slice(slash + 1);\n    const targetRoot = parseSimpleRoman(target, key).rootPc;\n    const localKey = majorKey(targetRoot);\n    return chordFromParsed(parseSimpleRoman(applied, localKey));\n  }\n  return chordFromParsed(parseSimpleRoman(trimmed, key));\n}\n\n/** Case and suffix for rendering a chord quality as a Roman numeral. */\nfunction romanStyle(quality: ChordQuality): { lower: boolean; suffix: string } {\n  return ROMAN_STYLE[quality];\n}\n\n/** Choose the degree number and accidental to spell a root as a Roman numeral. */\nfunction romanSpelling(\n  rootPc: number,\n  key: KeyScale,\n): { degreeNumber: number; accidental: string } {\n  const tones = scaleTonesInDegreeOrder(key);\n  const diatonic = tones.indexOf(mod12(rootPc));\n  if (diatonic >= 0) {\n    return { degreeNumber: diatonic + 1, accidental: '' };\n  }\n  // Chromatic root: prefer a flat of the diatonic degree a semitone above it,\n  // then a sharp of the degree a semitone below. Degree 1 (the tonic) and\n  // degree 5 (the dominant) are skipped in the flat pass, so a raised leading\n  // tone spells as `#vii` rather than a flat tonic `bI`, and the tritone above\n  // the tonic spells as `#iv` rather than a flat fifth `bV` (matching the\n  // conventional `OFFSET_SPELLING` for offset 6).\n  for (let i = 0; i < tones.length; i += 1) {\n    const degreeNumber = i + 1;\n    if (degreeNumber === 1 || degreeNumber === 5) {\n      continue;\n    }\n    if (mod12((tones[i] ?? 0) - 1) === mod12(rootPc)) {\n      return { degreeNumber, accidental: 'b' };\n    }\n  }\n  for (let i = 0; i < tones.length; i += 1) {\n    if (mod12((tones[i] ?? 0) + 1) === mod12(rootPc)) {\n      return { degreeNumber: i + 1, accidental: '#' };\n    }\n  }\n  const [degreeNumber, accidental] = OFFSET_SPELLING[mod12(rootPc - key.rootPc)] ?? [1, ''];\n  return { degreeNumber, accidental };\n}\n\n/** Quality marker (without the seventh digit) used when a figure carries the 7. */\nfunction baseMarker(quality: ChordQuality): string {\n  if (quality === 'dim' || quality === 'dim7') {\n    return 'o';\n  }\n  if (quality === 'm7b5') {\n    return 'ø';\n  }\n  if (quality === 'aug' || quality === 'aug7') {\n    return '+';\n  }\n  if (quality === 'augMaj7') {\n    return '+maj7';\n  }\n  if (quality === 'maj7' || quality === 'minMaj7') {\n    return 'maj7';\n  }\n  return '';\n}\n\nconst TRIAD_FIGURES: Record<number, string> = { 1: '6', 2: '64' };\nconst SEVENTH_FIGURES: Record<number, string> = { 1: '65', 2: '43', 3: '42' };\n\n/** Qualities whose inversions render as lossless triad figures (6, 64). */\nconst TRIAD_FIGURE_QUALITIES: ReadonlySet<ChordQuality> = new Set(['maj', 'min', 'dim', 'aug']);\n\n/**\n * Qualities carrying a chordal seventh, whose inversions render as seventh\n * figures (65, 43, 42). Membership is decided by the quality itself — a 7th\n * above the root (10 or 11 semitones, or the diminished 7th of `dim7`) — never\n * by interval count, which would turn added-tone chords into false sevenths.\n */\nconst SEVENTH_FIGURE_QUALITIES: ReadonlySet<ChordQuality> = new Set([\n  'maj7',\n  'min7',\n  'dom7',\n  'dim7',\n  'm7b5',\n  'minMaj7',\n  'aug7',\n  'augMaj7',\n]);\n\n/**\n * Render a chord as a Roman numeral relative to a key.\n *\n * Diatonic roots take their scale-degree numeral directly, so numerals are\n * correct in both major and minor keys (and any custom scale). The quality\n * selects the case and suffix; chromatic roots receive a flat/sharp spelling by\n * convention. When the chord carries a `bassPc` on a chord tone, a figured-bass\n * inversion (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true\n * seventh chords; added-tone and extended qualities have no lossless figure and\n * render in root position instead (the bass is dropped, pitch classes are\n * preserved).\n *\n * @param chord The chord to name.\n * @param key The prevailing key.\n * @returns The Roman numeral string.\n * @example\n * ```ts\n * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';\n * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)\n * ```\n * @category Functional Harmony\n */\nexport function chordToRoman(chord: Chord, key: KeyScale): string {\n  const { degreeNumber, accidental } = romanSpelling(chord.rootPc, key);\n  const { lower, suffix } = romanStyle(chord.quality);\n  const numeral: string = ROMAN[degreeNumber - 1] ?? 'I';\n  const cased = lower ? numeral.toLowerCase() : numeral;\n\n  let inversion = 0;\n  if (chord.bassPc !== undefined) {\n    const idx = chord.intervals.findIndex((iv) => mod12(chord.rootPc + iv) === chord.bassPc);\n    if (idx > 0) {\n      inversion = idx;\n    }\n  }\n  if (inversion > 0) {\n    const figure = SEVENTH_FIGURE_QUALITIES.has(chord.quality)\n      ? SEVENTH_FIGURES[inversion]\n      : TRIAD_FIGURE_QUALITIES.has(chord.quality)\n        ? TRIAD_FIGURES[inversion]\n        : undefined;\n    if (figure !== undefined) {\n      return `${accidental}${cased}${baseMarker(chord.quality)}${figure}`;\n    }\n    // No lossless figured-bass symbol exists — the quality is an added-tone or\n    // extended chord, or the bass falls on a tension beyond the seventh — so\n    // fall back to root-position rendering with the quality suffix rather than\n    // emitting a figure that would re-parse as a different chord.\n  }\n  return `${accidental}${cased}${suffix}`;\n}\n","/**\n * Borrowed chords (modal interchange) and the Neapolitan.\n *\n * Roots are pitch classes measured against the key tonic, so borrowed and\n * chromatic chords are handled by their semitone offset rather than requiring a\n * spelled key signature.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport type { Chord } from '../../theory/chord/index.js';\nimport { HARMONIC_MINOR_MASK } from '../../theory/scale/index.js';\nimport { isDiatonic, isMinorKey, parallelKey } from './function.js';\nimport { isNeapolitan, mod12 } from './internal.js';\n\n/**\n * The origin of a recognized non-diatonic chord, or null when none applies.\n *\n * @category Functional Harmony\n */\nexport type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;\n\n/**\n * In a minor key, whether a non-diatonic chord is explained by the harmonic\n * minor scale on the same tonic (major V, V7, the raised-leading-tone viio).\n * Such chords are in-key chromatic alterations, not modal interchange.\n */\nfunction isHarmonicMinorAlteration(chord: Chord, key: KeyScale): boolean {\n  return (\n    isMinorKey(key) &&\n    isDiatonic(chord, { rootPc: mod12(key.rootPc), modeMask12: HARMONIC_MINOR_MASK })\n  );\n}\n\n/**\n * Whether a chord is borrowed from the parallel mode (modal interchange).\n *\n * True when the chord is not diatonic to `key` but is diatonic to its\n * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy\n * tonic and major IV in a minor key. Two non-diatonic families are excluded:\n * chords diatonic to neither mode (they are chromatic, not borrowed), and, in\n * a minor key, chords explained by the harmonic minor scale (the major\n * dominant and raised-leading-tone chords), which are in-key alterations\n * rather than interchange even though they happen to fit the parallel major.\n *\n * @param chord The chord to test.\n * @param key The prevailing key.\n * @returns True if the chord is borrowed from the parallel mode.\n * @category Functional Harmony\n */\nexport function isBorrowedChord(chord: Chord, key: KeyScale): boolean {\n  if (isDiatonic(chord, key)) {\n    return false;\n  }\n  if (isHarmonicMinorAlteration(chord, key)) {\n    return false;\n  }\n  return isDiatonic(chord, parallelKey(key));\n}\n\n/**\n * Identify where a non-diatonic chord comes from.\n *\n * The Neapolitan (major triad on b2) is recognized first, since it sits\n * outside both parallel modes; parallel-mode borrowing follows the\n * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,\n * and unrecognized chromatic chords all yield null.\n *\n * @param chord The chord to classify.\n * @param key The prevailing key.\n * @returns The borrowing source, or null.\n * @category Functional Harmony\n */\nexport function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {\n  if (isDiatonic(chord, key)) {\n    return null;\n  }\n  if (isNeapolitan(chord, key)) {\n    return 'neapolitan';\n  }\n  if (isBorrowedChord(chord, key)) {\n    return isMinorKey(key) ? 'parallel-major' : 'parallel-minor';\n  }\n  return null;\n}\n","/**\n * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key\n * mirroring, and full chord analysis.\n *\n * Roots are pitch classes measured against the key tonic, so borrowed and\n * chromatic chords are handled by their semitone offset rather than requiring a\n * spelled key signature.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport type { Chord, ChordQuality } from '../../theory/chord/index.js';\nimport { chordPitchClasses, makeChord } from '../../theory/chord/index.js';\nimport { isScaleTone, MAJOR_MASK, NATURAL_MINOR_MASK } from '../../theory/scale/index.js';\nimport { type BorrowedSource, borrowedSource } from './borrowed.js';\nimport { degreeRootPc, isNeapolitan, mod12 } from './internal.js';\nimport { chordToRoman } from './roman.js';\n\n/**\n * The three broad harmonic functions of tonal music.\n *\n * @category Functional Harmony\n */\nexport type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';\n\n/** Harmonic function of each semitone offset above the tonic (major context). */\nconst FUNCTION_BY_OFFSET: readonly HarmonicFunction[] = [\n  'tonic', // 0  I\n  'subdominant', // 1  bII (Neapolitan)\n  'subdominant', // 2  ii\n  'tonic', // 3  bIII\n  'tonic', // 4  iii\n  'subdominant', // 5  IV\n  'dominant', // 6  #IV / bV\n  'dominant', // 7  V\n  'subdominant', // 8  bVI\n  'tonic', // 9  vi\n  'subdominant', // 10 bVII\n  'dominant', // 11 vii\n];\n\n/**\n * Whether a key's scale has a minor third and no major third (a minor key).\n *\n * @category Functional Harmony\n */\nexport function isMinorKey(key: KeyScale): boolean {\n  const hasMinorThird = (key.modeMask12 >> 3) & 1;\n  const hasMajorThird = (key.modeMask12 >> 4) & 1;\n  return Boolean(hasMinorThird) && !hasMajorThird;\n}\n\n/**\n * The harmonic function of a chord in a key, from its root's offset above the\n * tonic. The mapping follows common-practice major-key function and is a useful\n * approximation in minor and for borrowed chords.\n *\n * @param chord The chord.\n * @param key The prevailing key.\n * @returns The harmonic function.\n * @category Functional Harmony\n */\nexport function functionOf(chord: Chord, key: KeyScale): HarmonicFunction {\n  return FUNCTION_BY_OFFSET[mod12(chord.rootPc - key.rootPc)] ?? 'tonic';\n}\n\n/**\n * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.\n *\n * @category Functional Harmony\n */\nexport type ChordAnalysis = {\n  function: HarmonicFunction;\n  borrowed: boolean;\n  source: BorrowedSource;\n  roman: string;\n};\n\n/**\n * Whether every pitch class of a chord belongs to the key's scale.\n *\n * The test is strict against the key's own mode mask: in a natural-minor key\n * the harmonic-minor dominant (major V) is *not* diatonic, since the raised\n * leading tone lies outside the mask. Borrowing predicates treat that case as\n * an in-key alteration separately (see {@link isBorrowedChord}).\n *\n * @param chord The chord to test.\n * @param key The prevailing key.\n * @returns True if all chord pitch classes are scale tones.\n * @category Functional Harmony\n */\nexport function isDiatonic(chord: Chord, key: KeyScale): boolean {\n  return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));\n}\n\n/**\n * The parallel key: same tonic, opposite mode.\n *\n * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)\n * maps to the parallel major; any other key maps to the parallel natural minor.\n *\n * @param key The key to mirror.\n * @returns The parallel major or natural-minor key on the same tonic.\n * @category Functional Harmony\n */\nexport function parallelKey(key: KeyScale): KeyScale {\n  return {\n    rootPc: mod12(key.rootPc),\n    modeMask12: isMinorKey(key) ? MAJOR_MASK : NATURAL_MINOR_MASK,\n  };\n}\n\n/** Diminished-family qualities: diminished triad, dim7, half-diminished. */\nfunction isDiminishedQuality(quality: ChordQuality): boolean {\n  return quality === 'dim' || quality === 'dim7' || quality === 'm7b5';\n}\n\n/** Whether the chord's interval template carries a major third above the root. */\nfunction hasMajorThird(chord: Chord): boolean {\n  return chord.intervals.some((interval) => mod12(interval) === 4);\n}\n\n/**\n * Quality-aware harmonic function, refining the offset table where chord\n * quality disambiguates: diminished chords on the leading tone or the raised\n * subdominant resolve by semitone and act as dominants; the Neapolitan and the\n * major-third chords on bVI/bVII borrowed from the parallel minor act as\n * subdominant (predominant) harmony. All other chords keep {@link functionOf}.\n */\nfunction qualityAwareFunction(chord: Chord, key: KeyScale): HarmonicFunction {\n  const offset = mod12(chord.rootPc - key.rootPc);\n  if (isDiminishedQuality(chord.quality) && (offset === 11 || offset === 6)) {\n    return 'dominant';\n  }\n  if (isNeapolitan(chord, key)) {\n    return 'subdominant';\n  }\n  if (!isMinorKey(key) && hasMajorThird(chord) && (offset === 8 || offset === 10)) {\n    return 'subdominant';\n  }\n  return functionOf(chord, key);\n}\n\n/**\n * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.\n *\n * The function is quality-aware (see the predicates behind it), the source\n * follows {@link borrowedSource}, and the numeral comes from\n * {@link chordToRoman}. `borrowed` is true whenever a source is identified —\n * including the Neapolitan, which the stricter parallel-mode predicate\n * {@link isBorrowedChord} does not count.\n *\n * @param chord The chord to analyze.\n * @param key The prevailing key.\n * @returns The chord analysis.\n * @example\n * ```ts\n * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';\n * analyzeChord(makeChord(7, 'dom7'), majorKey(0));\n * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }\n * ```\n * @category Functional Harmony\n */\nexport function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {\n  const source = borrowedSource(chord, key);\n  return {\n    function: qualityAwareFunction(chord, key),\n    borrowed: source !== null,\n    source,\n    roman: chordToRoman(chord, key),\n  };\n}\n\n/**\n * The secondary dominant (V7) that tonicizes a scale degree.\n *\n * @param targetDegree 0-based scale degree to tonicize.\n * @param key The prevailing key.\n * @returns A dominant-seventh chord a fifth above the target's root.\n * @category Functional Harmony\n */\nexport function secondaryDominant(targetDegree: number, key: KeyScale): Chord {\n  const targetRoot = degreeRootPc(targetDegree + 1, key);\n  return makeChord(mod12(targetRoot + 7), 'dom7');\n}\n","/**\n * Cadence detection between two successive chords.\n *\n * Roots are pitch classes measured against the key tonic, so borrowed and\n * chromatic chords are handled by their semitone offset rather than requiring a\n * spelled key signature.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport type { Chord } from '../../theory/chord/index.js';\nimport { isMinorKey } from './function.js';\nimport { mod12 } from './internal.js';\n\n/**\n * A recognized cadence type, or null when a chord pair forms none.\n *\n * @category Functional Harmony\n */\nexport type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;\n\n/**\n * Classify the cadence formed by moving from one chord to the next.\n *\n * - authentic: V (dominant a fifth above the tonic) to I\n * - plagal: IV (a fourth above the tonic) to I\n * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in\n *   minor)\n * - half: any chord other than the dominant itself to V\n *\n * A static V-to-V repeat with no root motion is not a cadence and yields null.\n *\n * @param from The penultimate chord.\n * @param to The final chord.\n * @param key The prevailing key.\n * @returns The cadence type, or null.\n * @example\n * ```ts\n * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';\n * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'\n * ```\n * @category Functional Harmony\n */\nexport function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {\n  const tonic = mod12(key.rootPc);\n  const fromOffset = mod12(from.rootPc - tonic);\n  const toOffset = mod12(to.rootPc - tonic);\n  // Deceptive targets: the diatonic submediant (vi at offset 9 in major, VI at\n  // offset 8 in minor) plus, in a major key, the borrowed flat-submediant bVI\n  // at offset 8.\n  const deceptiveTargets = isMinorKey(key) ? [8] : [8, 9];\n  if (fromOffset === 7 && toOffset === 0) {\n    return 'authentic';\n  }\n  if (fromOffset === 5 && toOffset === 0) {\n    return 'plagal';\n  }\n  if (fromOffset === 7 && deceptiveTargets.includes(toOffset)) {\n    return 'deceptive';\n  }\n  // A move to the dominant is a half cadence, but a no-root-motion V-to-V repeat\n  // is not a cadence at all.\n  if (toOffset === 7 && fromOffset !== 7) {\n    return 'half';\n  }\n  return null;\n}\n","/**\n * Recognition: infer a chord name from a set of pitches, or a key from a set of\n * pitch classes. This is the inverse direction of the chord/scale builders,\n * which only go name -> notes.\n */\n\nimport type { KeyScale } from '../../core/types.js';\nimport { assertFiniteNumber, assertGenerationBudget } from '../../core/validation/index.js';\nimport type { Chord, ChordQuality } from '../../theory/chord/index.js';\nimport { chordPitchClasses, chordQualities, makeChord } from '../../theory/chord/index.js';\nimport {\n  HARMONIC_MINOR_MASK,\n  MAJOR_MASK,\n  MELODIC_MINOR_MASK,\n  majorKey,\n  minorKey,\n  NATURAL_MINOR_MASK,\n} from '../../theory/scale/index.js';\n\n/**\n * A candidate chord interpretation of a pitch set.\n *\n * @category Recognition\n */\nexport type ChordMatch = {\n  rootPc: number;\n  quality: ChordQuality;\n  /** Chord tones absent from the input (an incomplete voicing). */\n  missingPcs: number[];\n  /** Input pitch classes not belonging to the chord. */\n  extraPcs: number[];\n  /** True when the input pitch-class set equals the chord exactly. */\n  exact: boolean;\n  /** Inversion implied by a known bass, or null for an unordered pitch-class set. */\n  inversion: number | null;\n  /** Bass pitch class when inverted (the lowest note is not the root). */\n  bassPc?: number;\n};\n\n/** Input interpretation for {@link detectChord} and {@link detectChordBest}. */\nexport type DetectChordOptions = {\n  /**\n   * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the\n   * input as unordered. `auto` (default) selects pitch-class mode only when all\n   * values lie in 0..11.\n   */\n  input?: 'auto' | 'midi' | 'pitchClass';\n  /** Explicit bass pitch class, including for an unordered pitch-class set. */\n  bassPc?: number;\n};\n\n/**\n * A candidate key interpretation of a pitch-class set.\n *\n * @category Recognition\n */\nexport type KeyMatch = {\n  key: KeyScale;\n  mode: 'major' | 'minor';\n  /** Fraction of input pitch classes that are in the scale, in [0, 1]. */\n  fit: number;\n};\n\n/** Reduce any integer to a pitch class in [0, 11]. */\nfunction pitchClass(value: number): number {\n  return ((Math.trunc(value) % 12) + 12) % 12;\n}\n\n/** Unique pitch classes of the input, sorted ascending. */\nfunction uniquePitchClasses(pitches: number[]): number[] {\n  return [...new Set(pitches.map(pitchClass))].sort((a, b) => a - b);\n}\n\nfunction assertPitches(pitches: number[]): void {\n  assertGenerationBudget(pitches.length, 'detection pitches');\n  for (let index = 0; index < pitches.length; index += 1) {\n    assertFiniteNumber(pitches[index] ?? Number.NaN, `pitches[${index}]`);\n  }\n}\n\n/**\n * Identify chords matching a set of pitches.\n *\n * Every input pitch class is tried as a root against every known chord quality.\n * A match is reported when all of the chord's tones are present in the input, or\n * when the only absent tone is the perfect fifth (a common omission in shell\n * voicings); matches are ranked best-first by fewest extra notes, then fewest\n * missing notes, then most specific (largest) chord. An exact match (no extras,\n * no missing) is flagged and ranked first.\n *\n * @param pitches MIDI pitches or bare pitch classes (octave-agnostic).\n * @returns Ranked chord interpretations (may be empty).\n * @example\n * ```ts\n * import { detectChord } from '@libraz/libcantus';\n * const matches = detectChord([60, 64, 67]); // C E G\n * matches[0]; // { rootPc: 0, quality: 'maj', exact: true, ... }\n * ```\n * @category Recognition\n */\nexport function detectChord(pitches: number[], opts: DetectChordOptions = {}): ChordMatch[] {\n  assertPitches(pitches);\n  if (opts.bassPc !== undefined) assertFiniteNumber(opts.bassPc, 'bassPc');\n  const input = uniquePitchClasses(pitches);\n  if (input.length === 0) {\n    return [];\n  }\n  const inputKind =\n    opts.input === undefined || opts.input === 'auto'\n      ? pitches.every((pitch) => Number.isInteger(pitch) && pitch >= 0 && pitch <= 11)\n        ? 'pitchClass'\n        : 'midi'\n      : opts.input;\n  const bassPc =\n    opts.bassPc !== undefined\n      ? pitchClass(opts.bassPc)\n      : inputKind === 'midi'\n        ? pitchClass(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity))\n        : undefined;\n  const inputSet = new Set(input);\n  const matches: ChordMatch[] = [];\n  const qualities = chordQualities();\n  for (const rootPc of input) {\n    for (const quality of qualities) {\n      const chord = makeChord(rootPc, quality);\n      const tones = chordPitchClasses(chord);\n      const toneSet = new Set(tones);\n      const missingPcs = tones.filter((pc) => !inputSet.has(pc));\n      // Accept an exact-tone match, or one whose only absent tone is the perfect\n      // fifth; any other missing tone (third, sus tone, seventh, ...) rejects.\n      const fifthPc = pitchClass(rootPc + 7);\n      if (missingPcs.length > 1 || (missingPcs.length === 1 && missingPcs[0] !== fifthPc)) {\n        continue;\n      }\n      const extraPcs = input.filter((pc) => !toneSet.has(pc));\n      const bassIndex =\n        bassPc === undefined\n          ? -1\n          : chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);\n      const inversion = bassPc === undefined ? null : bassIndex > 0 ? bassIndex : 0;\n      const match: ChordMatch = {\n        rootPc,\n        quality,\n        missingPcs,\n        extraPcs,\n        exact: extraPcs.length === 0 && missingPcs.length === 0,\n        inversion,\n      };\n      if (bassPc !== undefined && bassPc !== rootPc) {\n        match.bassPc = bassPc;\n      }\n      matches.push(match);\n    }\n  }\n  matches.sort((a, b) => {\n    if (a.extraPcs.length !== b.extraPcs.length) {\n      return a.extraPcs.length - b.extraPcs.length;\n    }\n    if (a.missingPcs.length !== b.missingPcs.length) {\n      return a.missingPcs.length - b.missingPcs.length;\n    }\n    // Prefer root position (the bass is the chord root) on a tie.\n    if ((a.inversion === 0) !== (b.inversion === 0)) {\n      return a.inversion === 0 ? -1 : 1;\n    }\n    const aSize = chordPitchClasses(makeChord(a.rootPc, a.quality)).length;\n    const bSize = chordPitchClasses(makeChord(b.rootPc, b.quality)).length;\n    return bSize - aSize;\n  });\n  return matches;\n}\n\n/**\n * The single best chord interpretation of a pitch set, or null if none.\n *\n * @param pitches MIDI pitches or bare pitch classes.\n * @returns The top-ranked chord, or null when nothing matches.\n * @example\n * ```ts\n * import { detectChordBest } from '@libraz/libcantus';\n * detectChordBest([60, 64, 67]); // C major triad: { rootPc: 0, quality: 'maj', ... }\n * ```\n * @category Recognition\n */\nexport function detectChordBest(pitches: number[], opts: DetectChordOptions = {}): Chord | null {\n  const best = detectChord(pitches, opts)[0];\n  if (!best) {\n    return null;\n  }\n  return makeChord(best.rootPc, best.quality, best.bassPc);\n}\n\n/**\n * Minor-scale variants scored for each minor-key candidate. Scoring against all\n * three lets the raised sixth and seventh (e.g. the leading tone G# in A minor)\n * count toward their own tonic instead of only penalizing it.\n */\nconst MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];\n\n/**\n * Rank major and minor keys by how well they contain a set of pitch classes.\n *\n * The tonic is weighted so that, among equally-fitting keys, the one whose root\n * appears in the input is preferred. Minor candidates are scored against the\n * natural, harmonic, and melodic minor variants and keep the best of the three,\n * so a minor cadence containing the leading tone still resolves to its own\n * tonic; the returned key is always the natural-minor scale. Returns all 24\n * keys ranked best-first, or an empty array for an empty input (mirroring\n * {@link detectChord}).\n *\n * @param pitches MIDI pitches or bare pitch classes.\n * @returns Ranked key interpretations (empty for an empty input).\n * @example\n * ```ts\n * import { detectKey } from '@libraz/libcantus';\n * const keys = detectKey([60, 62, 64, 65, 67, 69, 71]); // C major scale\n * keys[0].mode; // 'major', with keys[0].key.rootPc === 0\n * ```\n * @category Recognition\n */\nexport function detectKey(pitches: number[]): KeyMatch[] {\n  assertPitches(pitches);\n  const input = uniquePitchClasses(pitches);\n  if (input.length === 0) {\n    return [];\n  }\n  const counts = new Map<number, number>();\n  for (const pc of pitches.map(pitchClass)) {\n    counts.set(pc, (counts.get(pc) ?? 0) + 1);\n  }\n  const total = pitches.length;\n  const results: (KeyMatch & { score: number })[] = [];\n  for (let tonic = 0; tonic < 12; tonic += 1) {\n    for (const mode of ['major', 'minor'] as const) {\n      const key = mode === 'major' ? majorKey(tonic) : minorKey(tonic);\n      const masks = mode === 'major' ? [MAJOR_MASK] : MINOR_MASK_VARIANTS;\n      // Score each scale variant and keep the best; ties keep the earlier\n      // (more diatonic) variant.\n      let inScale = 0;\n      let weighted = Number.NEGATIVE_INFINITY;\n      for (const mask of masks) {\n        let variantInScale = 0;\n        let variantWeighted = 0;\n        for (const pc of input) {\n          const offset = (pc - tonic + 12) % 12;\n          if ((mask >> offset) & 1) {\n            variantInScale += 1;\n          }\n        }\n        for (const [pc, count] of counts) {\n          const offset = (pc - tonic + 12) % 12;\n          if ((mask >> offset) & 1) {\n            variantWeighted += count;\n          }\n        }\n        if (variantWeighted > weighted) {\n          weighted = variantWeighted;\n          inScale = variantInScale;\n        }\n      }\n      weighted += (counts.get(tonic) ?? 0) * 0.5;\n      results.push({\n        key,\n        mode,\n        fit: inScale / input.length,\n        score: weighted / total,\n      });\n    }\n  }\n  results.sort((a, b) => b.score - a.score);\n  return results.map(({ key, mode, fit }) => ({ key, mode, fit }));\n}\n"],"mappings":"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","names":["degreeNumber","hasMajorThird"]}

package/dist/{chunk-A4532ZFR.js → chunk-EH6EM37U.js}

@@ -5,7 +5,12 @@ import {
   createsVerticalDissonance,
   isForbiddenMelodicLeap,
   isScaleTone
-} from "./chunk-7Y7WF64D.js";
+} from "./chunk-MIWO425M.js";
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger
+} from "./chunk-FBQK3ZQN.js";
 
 // src/theory/safety/index.ts
 var NoteSafety = /* @__PURE__ */ ((NoteSafety2) => {
@@ -35,6 +40,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 pitchClass(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -59,8 +89,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 */;
@@ -121,9 +170,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 */;
@@ -168,6 +219,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;
@@ -231,11 +283,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 */) {
@@ -256,4 +312,4 @@ export {
   evaluateSafety,
   enumerateSafePitches
 };
-//# sourceMappingURL=chunk-A4532ZFR.js.map
+//# sourceMappingURL=chunk-EH6EM37U.js.map

package/dist/chunk-EH6EM37U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theory/safety/index.ts"],"sourcesContent":["import type { KeyScale } from '../../core/types.js';\nimport {\n  assertFiniteNumber,\n  assertGenerationBudget,\n  assertInteger,\n} from '../../core/validation/index.js';\nimport type { Chord } from '../chord/index.js';\nimport { chordPitchClasses } from '../chord/index.js';\nimport {\n  createsHiddenParallelPerfect,\n  createsParallelPerfect,\n  createsVerticalDissonance,\n  isForbiddenMelodicLeap,\n} from '../counterpoint/index.js';\nimport { isScaleTone } from '../scale/index.js';\n\n/**\n * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.\n *\n * @category Arrangement & Analysis\n */\nexport type SafetyProfile = 'strict' | 'pop';\n\n/**\n * Overall placeability verdict for a candidate pitch.\n *\n * @category Arrangement & Analysis\n */\nexport enum NoteSafety {\n  Safe = 0,\n  Warning = 1,\n  Dissonant = 2,\n}\n\n/**\n * Bit flags describing why a pitch received its verdict.\n *\n * @category Arrangement & Analysis\n */\nexport enum ReasonFlag {\n  ChordTone = 1 << 0,\n  Tension = 1 << 1,\n  AvoidNote = 1 << 2,\n  ScaleTone = 1 << 3,\n  NonScale = 1 << 4,\n  OutOfRange = 1 << 5,\n  Tritone = 1 << 6,\n  LargeLeap = 1 << 7,\n  MinorSecond = 1 << 8,\n  MajorSeventh = 1 << 9,\n  VerticalDissonance = 1 << 10,\n  ParallelPerfect = 1 << 11,\n  HiddenParallel = 1 << 12,\n  VoiceCrossing = 1 << 13,\n  Suspension = 1 << 14,\n  NeedsResolution = 1 << 15,\n}\n\n/**\n * A neighbouring voice's current and previous pitch.\n *\n * @category Arrangement & Analysis\n */\nexport type VoiceSnapshot = {\n  pitch: number;\n  prevPitch?: number;\n};\n\n/**\n * Everything needed to evaluate one candidate pitch.\n *\n * @category Arrangement & Analysis\n */\nexport type SafetyQuery = {\n  profile: SafetyProfile;\n  candidatePitch: number;\n  prevPitch?: number;\n  chord: Chord | null;\n  key: KeyScale;\n  otherVoices: VoiceSnapshot[];\n  strongBeat: boolean;\n  vocalLow?: number;\n  vocalHigh?: number;\n};\n\n/**\n * The verdict, reason flags, and optional resolution guidance.\n *\n * @category Arrangement & Analysis\n */\nexport type SafetyResult = {\n  safety: NoteSafety;\n  reasons: number;\n  resolveTo?: number;\n  suggestions?: number[];\n  rationale?: string;\n};\n\n/** Semitone radius searched around a rejected candidate for safe alternatives. */\nconst SUGGESTION_WINDOW = 12;\n/** Maximum number of alternative pitches returned in `SafetyResult.suggestions`. */\nconst MAX_SUGGESTIONS = 3;\n\n/** Canonical minimum verdict contributed by each non-informational reason. */\nconst REASON_SEVERITY: ReadonlyArray<\n  readonly [flag: ReasonFlag, pop: NoteSafety, strict: NoteSafety]\n> = [\n  [ReasonFlag.Tension, NoteSafety.Warning, NoteSafety.Warning],\n  [ReasonFlag.AvoidNote, NoteSafety.Warning, NoteSafety.Dissonant],\n  [ReasonFlag.ScaleTone, NoteSafety.Warning, NoteSafety.Warning],\n  [ReasonFlag.NonScale, NoteSafety.Dissonant, NoteSafety.Dissonant],\n  [ReasonFlag.OutOfRange, NoteSafety.Warning, NoteSafety.Warning],\n  [ReasonFlag.Tritone, NoteSafety.Dissonant, NoteSafety.Dissonant],\n  [ReasonFlag.LargeLeap, NoteSafety.Warning, NoteSafety.Dissonant],\n  [ReasonFlag.VerticalDissonance, NoteSafety.Dissonant, NoteSafety.Dissonant],\n  [ReasonFlag.ParallelPerfect, NoteSafety.Warning, NoteSafety.Dissonant],\n  [ReasonFlag.HiddenParallel, NoteSafety.Warning, NoteSafety.Dissonant],\n  [ReasonFlag.VoiceCrossing, NoteSafety.Warning, NoteSafety.Dissonant],\n  [ReasonFlag.Suspension, NoteSafety.Dissonant, NoteSafety.Dissonant],\n  [ReasonFlag.NeedsResolution, NoteSafety.Warning, NoteSafety.Dissonant],\n];\n\nfunction minimumSafetyForReasons(reasons: number, profile: SafetyProfile): NoteSafety {\n  let minimum = NoteSafety.Safe;\n  const severityIndex = profile === 'strict' ? 2 : 1;\n  for (const entry of REASON_SEVERITY) {\n    if (reasons & entry[0]) {\n      minimum = Math.max(minimum, entry[severityIndex]) as NoteSafety;\n    }\n  }\n  return minimum;\n}\n\nfunction pitchClass(pitch: number): number {\n  return ((Math.trunc(pitch) % 12) + 12) % 12;\n}\n\nfunction intervalAboveRoot(pitch: number, chord: Chord): number {\n  return (((pitchClass(pitch) - pitchClass(chord.rootPc)) % 12) + 12) % 12;\n}\n\nfunction isChordMember(pitch: number, chord: Chord): boolean {\n  return chordPitchClasses(chord).includes(pitchClass(pitch));\n}\n\n/** Whether the perfect fourth is an avoid note over this chord. */\nfunction avoidsFourth(chord: Chord): boolean {\n  return chord.intervals.includes(4) && !chord.intervals.includes(5);\n}\n\n/** Whether the major seventh is an avoid note over this chord (dominant). */\nfunction avoidsMajorSeventh(chord: Chord): boolean {\n  return chord.intervals.includes(4) && chord.intervals.includes(10);\n}\n\n/** Nearest chord tone at or below the candidate, within two semitones. */\nfunction stepResolution(pitch: number, chord: Chord): number | undefined {\n  for (let delta = 1; delta <= 2; delta += 1) {\n    if (isChordMember(pitch - delta, chord)) {\n      return pitch - delta;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Evaluate the safety of placing a candidate pitch in a voice.\n *\n * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)\n * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`\n * profile treats avoid notes and parallels as dissonant; `pop` treats them as\n * warnings. The final verdict is the worst severity among the reasons.\n *\n * @param q The candidate and its harmonic/voice-leading context.\n * @returns The verdict, reason bitmask, and optional resolution guidance.\n * @example\n * ```ts\n * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';\n * const result = evaluateSafety({\n *   profile: 'pop',\n *   candidatePitch: 60, // C over a C major chord\n *   chord: makeChord(0, 'maj'),\n *   key: majorKey(0),\n *   otherVoices: [],\n *   strongBeat: true,\n * });\n * result.safety === NoteSafety.Safe; // true — C is a chord tone\n * ```\n * @category Arrangement & Analysis\n */\nexport function evaluateSafety(q: SafetyQuery): SafetyResult {\n  assertSafetyContext(q);\n  assertFiniteNumber(q.candidatePitch, 'candidatePitch');\n  return evaluateInternal(q, true);\n}\n\n/** Validate all numeric context fields once at a public safety entry point. */\nfunction assertSafetyContext(q: Omit<SafetyQuery, 'candidatePitch'>): void {\n  if (q.prevPitch !== undefined) assertFiniteNumber(q.prevPitch, 'prevPitch');\n  if (q.vocalLow !== undefined) assertFiniteNumber(q.vocalLow, 'vocalLow');\n  if (q.vocalHigh !== undefined) assertFiniteNumber(q.vocalHigh, 'vocalHigh');\n  if (q.vocalLow !== undefined && q.vocalHigh !== undefined && q.vocalLow > q.vocalHigh) {\n    throw new RangeError('vocalLow must not exceed vocalHigh');\n  }\n  assertGenerationBudget(q.otherVoices.length, 'other voices');\n  for (let index = 0; index < q.otherVoices.length; index += 1) {\n    const voice = q.otherVoices[index];\n    if (!voice) continue;\n    assertFiniteNumber(voice.pitch, `otherVoices[${index}].pitch`);\n    if (voice.prevPitch !== undefined) {\n      assertFiniteNumber(voice.prevPitch, `otherVoices[${index}].prevPitch`);\n    }\n  }\n}\n\n/**\n * Core safety evaluation.\n *\n * @param q The candidate and its harmonic/voice-leading context.\n * @param collectSuggestions Whether to search for safe alternatives on a\n *   non-Safe verdict. Set false during that search itself to bound recursion.\n * @returns The verdict, reason bitmask, and optional guidance.\n */\nfunction evaluateInternal(q: SafetyQuery, collectSuggestions: boolean): SafetyResult {\n  let reasons = 0;\n  let level = NoteSafety.Safe;\n  let resolveTo: number | undefined;\n  const raise = (l: NoteSafety) => {\n    if (l > level) {\n      level = l;\n    }\n  };\n  const avoidSeverity = q.profile === 'strict' ? NoteSafety.Dissonant : NoteSafety.Warning;\n  const parallelSeverity = avoidSeverity;\n  const pitch = q.candidatePitch;\n\n  if (\n    (q.vocalLow !== undefined && pitch < q.vocalLow) ||\n    (q.vocalHigh !== undefined && pitch > q.vocalHigh)\n  ) {\n    reasons |= ReasonFlag.OutOfRange;\n    raise(NoteSafety.Warning);\n  }\n\n  const inScale = isScaleTone(pitch, q.key);\n  const chord = q.chord;\n\n  if (chord && isChordMember(pitch, chord)) {\n    reasons |= ReasonFlag.ChordTone;\n  } else if (chord) {\n    const ic = intervalAboveRoot(pitch, chord);\n    const isTension = ic === 2 || ic === 5 || ic === 9;\n    const avoid = (ic === 5 && avoidsFourth(chord)) || (ic === 11 && avoidsMajorSeventh(chord));\n    if (avoid) {\n      reasons |= ReasonFlag.AvoidNote;\n      if (isTension) {\n        reasons |= ReasonFlag.Tension;\n      }\n      reasons |= ReasonFlag.NeedsResolution;\n      resolveTo = stepResolution(pitch, chord);\n      raise(avoidSeverity);\n    } else if (isTension && inScale) {\n      reasons |= ReasonFlag.Tension;\n      raise(NoteSafety.Warning);\n    } else if (inScale) {\n      reasons |= ReasonFlag.ScaleTone;\n      raise(NoteSafety.Warning);\n    } else {\n      reasons |= ReasonFlag.NonScale;\n      raise(NoteSafety.Dissonant);\n    }\n  } else if (inScale) {\n    reasons |= ReasonFlag.ScaleTone;\n    raise(NoteSafety.Warning);\n  } else {\n    reasons |= ReasonFlag.NonScale;\n    raise(NoteSafety.Dissonant);\n  }\n\n  // Harmonic tritone against a chord tone (except in dominant chords, where the\n  // tritone is a defining, stable colour).\n  if (chord && !(chord.intervals.includes(4) && chord.intervals.includes(10))) {\n    const ic = intervalAboveRoot(pitch, chord);\n    const toneOffsets = chord.intervals.map((i) => ((i % 12) + 12) % 12);\n    if (toneOffsets.some((t) => Math.abs(ic - t) === 6)) {\n      reasons |= ReasonFlag.Tritone;\n    }\n  }\n\n  if (q.prevPitch !== undefined) {\n    // Quality flags reduce the melodic interval to its pitch-class interval so\n    // compound intervals are treated uniformly with their simple form. The\n    // forbidden-leap flag defers to the counterpoint rule, which preserves the\n    // octave boundary (an octave leap is allowed, wider leaps are not).\n    const pc = Math.abs(pitch - q.prevPitch) % 12;\n    if (pc === 6) {\n      reasons |= ReasonFlag.Tritone;\n      raise(NoteSafety.Dissonant);\n    }\n    if (isForbiddenMelodicLeap(q.prevPitch, pitch)) {\n      reasons |= ReasonFlag.LargeLeap;\n      raise(parallelSeverity);\n    }\n    if (pc === 1) {\n      reasons |= ReasonFlag.MinorSecond;\n    }\n    if (pc === 11) {\n      reasons |= ReasonFlag.MajorSeventh;\n    }\n  }\n\n  if (q.strongBeat) {\n    const twoVoice = q.otherVoices.length === 1;\n    const prev = q.prevPitch;\n    for (const ov of q.otherVoices) {\n      if (!createsVerticalDissonance(pitch, ov.pitch, twoVoice)) {\n        continue;\n      }\n      reasons |= ReasonFlag.VerticalDissonance;\n      raise(NoteSafety.Dissonant);\n      // A held pitch that was consonant on the previous step and is now\n      // dissonant against the same voice is a prepared suspension.\n      if (\n        prev !== undefined &&\n        pitch === prev &&\n        ov.prevPitch !== undefined &&\n        !createsVerticalDissonance(prev, ov.prevPitch, twoVoice)\n      ) {\n        reasons |= ReasonFlag.Suspension;\n      }\n    }\n  }\n\n  if (q.prevPitch !== undefined) {\n    const prev = q.prevPitch;\n    for (const ov of q.otherVoices) {\n      if (ov.prevPitch === undefined) {\n        continue;\n      }\n      // createsParallelPerfect covers every perfect class (unison/octave and\n      // fifth), so no separate octave check is needed.\n      if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {\n        reasons |= ReasonFlag.ParallelPerfect;\n        raise(parallelSeverity);\n      }\n      if (createsHiddenParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {\n        reasons |= ReasonFlag.HiddenParallel;\n        raise(parallelSeverity);\n      }\n      const crossedNow = pitch - ov.pitch;\n      const crossedPrev = prev - ov.prevPitch;\n      if (crossedNow !== 0 && crossedPrev !== 0 && crossedNow > 0 !== crossedPrev > 0) {\n        reasons |= ReasonFlag.VoiceCrossing;\n        raise(parallelSeverity);\n      }\n    }\n  }\n\n  // Keep reason production and verdict policy as one invariant even when a new\n  // call path skips an earlier local `raise`: informational flags (ChordTone,\n  // MinorSecond, MajorSeventh) may coexist with Safe; every policy flag above\n  // contributes at least its table severity.\n  raise(minimumSafetyForReasons(reasons, q.profile));\n\n  const result: SafetyResult = { safety: level, reasons, rationale: describe(reasons, q) };\n  if (resolveTo !== undefined) {\n    result.resolveTo = resolveTo;\n  }\n  if (collectSuggestions && level !== NoteSafety.Safe) {\n    const suggestions = findSafeNearby(q, pitch);\n    if (suggestions.length > 0) {\n      result.suggestions = suggestions;\n    }\n  }\n  return result;\n}\n\n/**\n * Find safe alternative pitches near a rejected candidate.\n *\n * Searches outward from the candidate within `SUGGESTION_WINDOW` semitones,\n * probing the pitch below before the one above at each distance so the result\n * is deterministic and ordered by nearness.\n *\n * @param q The safety context of the rejected candidate.\n * @param candidate The candidate pitch that was not Safe.\n * @returns Up to `MAX_SUGGESTIONS` safe pitches, nearest first.\n */\nfunction findSafeNearby(q: SafetyQuery, candidate: number): number[] {\n  const out: number[] = [];\n  for (let d = 1; d <= SUGGESTION_WINDOW; d += 1) {\n    for (const p of [candidate - d, candidate + d]) {\n      if (evaluateInternal({ ...q, candidatePitch: p }, false).safety === NoteSafety.Safe) {\n        out.push(p);\n        if (out.length >= MAX_SUGGESTIONS) {\n          return out;\n        }\n      }\n    }\n  }\n  return out;\n}\n\n/** Build a short human explanation from the reason flags. */\nfunction describe(reasons: number, q: SafetyQuery): string {\n  if (reasons & ReasonFlag.OutOfRange) {\n    return 'Outside the target vocal range';\n  }\n  if (reasons & ReasonFlag.Suspension) {\n    return 'Prepared suspension — a held consonance now dissonant, awaiting resolution';\n  }\n  if (reasons & ReasonFlag.VerticalDissonance) {\n    return 'Dissonant against a sounding voice on a strong beat';\n  }\n  if (reasons & ReasonFlag.AvoidNote) {\n    return 'Avoid note — clashes with a chord tone a semitone away';\n  }\n  if (reasons & ReasonFlag.ParallelPerfect) {\n    return 'Parallel perfect interval with another voice';\n  }\n  if (reasons & ReasonFlag.HiddenParallel) {\n    return 'Hidden perfect interval by similar motion';\n  }\n  if (reasons & ReasonFlag.VoiceCrossing) {\n    return 'Crosses another voice';\n  }\n  if (reasons & ReasonFlag.ChordTone) {\n    return 'Chord tone';\n  }\n  if (reasons & ReasonFlag.Tension) {\n    return 'Chord tension';\n  }\n  if (reasons & ReasonFlag.NonScale) {\n    return 'Outside the key';\n  }\n  if (reasons & ReasonFlag.ScaleTone) {\n    return 'Scale tone, not in the chord';\n  }\n  return q.chord ? 'Placeable' : 'No chord context';\n}\n\n/**\n * Enumerate placeable pitches in a range, chord tones first, descending.\n *\n * @param q The safety context minus the candidate pitch.\n * @param pitchLow Lowest MIDI pitch to consider (inclusive).\n * @param pitchHigh Highest MIDI pitch to consider (inclusive).\n * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.\n * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.\n * @example\n * ```ts\n * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';\n * const pitches = enumerateSafePitches(\n *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },\n *   60,\n *   72,\n * );\n * pitches; // placeable pitches in [60, 72], chord tones first, each group descending\n * ```\n * @category Arrangement & Analysis\n */\nexport function enumerateSafePitches(\n  q: Omit<SafetyQuery, 'candidatePitch'>,\n  pitchLow: number,\n  pitchHigh: number,\n): number[] {\n  assertSafetyContext(q);\n  const chordTones: number[] = [];\n  const others: number[] = [];\n  assertInteger(pitchLow, 'pitchLow');\n  assertInteger(pitchHigh, 'pitchHigh');\n  if (pitchLow > pitchHigh) {\n    throw new RangeError(`pitchLow must not exceed pitchHigh; received ${pitchLow} > ${pitchHigh}`);\n  }\n  assertGenerationBudget(pitchHigh - pitchLow + 1, 'safe pitch candidates');\n  for (let pitch = pitchHigh; pitch >= pitchLow; pitch -= 1) {\n    const result = evaluateInternal({ ...q, candidatePitch: pitch }, false);\n    if (result.safety === NoteSafety.Dissonant) {\n      continue;\n    }\n    if (result.reasons & ReasonFlag.ChordTone) {\n      chordTones.push(pitch);\n    } else {\n      others.push(pitch);\n    }\n  }\n  return [...chordTones, ...others];\n}\n"],"mappings":"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","names":["NoteSafety","ReasonFlag"]}

package/dist/chunk-FBQK3ZQN.js

@@ -0,0 +1,131 @@
+// 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 assertRange(value, min, max, name) {
+  assertFiniteNumber(value, name);
+  if (value < min || value > max) {
+    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+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;
+}
+function assertTimeSignature(ts, name = "time signature") {
+  assertPositiveInt(ts.numerator, `${name}.numerator`);
+  assertPositiveInt(ts.denominator, `${name}.denominator`);
+  if (ts.grouping !== void 0) {
+    if (ts.grouping.length === 0) {
+      throw new RangeError(`${name}.grouping must not be empty`);
+    }
+    let sum = 0;
+    for (let index = 0; index < ts.grouping.length; index += 1) {
+      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);
+    }
+    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;
+    const pulses = compound ? ts.numerator / 3 : ts.numerator;
+    if (sum !== pulses) {
+      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);
+    }
+  }
+  return ts;
+}
+function assertNoteEvent(event, name = "note event", options = {}) {
+  assertFiniteNumber(event.pitch, `${name}.pitch`);
+  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);
+  assertRange(
+    event.durationBeat,
+    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    `${name}.durationBeat`
+  );
+  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {
+    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);
+  }
+  if (event.velocity !== void 0) {
+    assertRange(event.velocity, 0, 127, `${name}.velocity`);
+  }
+  return event;
+}
+function assertNoteEvents(events, name = "note events", options = {}) {
+  assertGenerationBudget(events.length, `${name} count`, options.budget);
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event !== void 0) {
+      assertNoteEvent(event, `${name}[${index}]`, options);
+    }
+  }
+  return events;
+}
+
+// src/core/interval/index.ts
+var IntervalQuality = /* @__PURE__ */ ((IntervalQuality2) => {
+  IntervalQuality2[IntervalQuality2["PerfectConsonance"] = 0] = "PerfectConsonance";
+  IntervalQuality2[IntervalQuality2["ImperfectConsonance"] = 1] = "ImperfectConsonance";
+  IntervalQuality2[IntervalQuality2["Dissonance"] = 2] = "Dissonance";
+  return IntervalQuality2;
+})(IntervalQuality || {});
+function simpleInterval(semitones) {
+  return Math.abs(semitones) % 12;
+}
+function classifyInterval(semitones, twoVoice = true) {
+  const pc = simpleInterval(semitones);
+  if (pc === 0 || pc === 7) {
+    return 0 /* PerfectConsonance */;
+  }
+  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {
+    return 1 /* ImperfectConsonance */;
+  }
+  if (pc === 5) {
+    return twoVoice ? 2 /* Dissonance */ : 1 /* ImperfectConsonance */;
+  }
+  return 2 /* Dissonance */;
+}
+function isPerfectInterval(semitones) {
+  const pc = simpleInterval(semitones);
+  return pc === 0 || pc === 7;
+}
+function isConsonantInterval(semitones, twoVoice = true) {
+  const pc = simpleInterval(semitones);
+  if (pc === 5) {
+    return !twoVoice;
+  }
+  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;
+}
+
+export {
+  DEFAULT_GENERATION_BUDGET,
+  assertFiniteNumber,
+  assertInteger,
+  assertPositiveInt,
+  assertRange,
+  assertGenerationBudget,
+  assertTimeSignature,
+  assertNoteEvent,
+  assertNoteEvents,
+  IntervalQuality,
+  classifyInterval,
+  isPerfectInterval,
+  isConsonantInterval
+};
+//# sourceMappingURL=chunk-FBQK3ZQN.js.map

package/dist/chunk-FBQK3ZQN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/validation/index.ts","../src/core/interval/index.ts"],"sourcesContent":["import type { TimeSignature } from '../meter/index.js';\nimport type { NoteEvent } from '../types.js';\n\n/** Default upper bound for synchronous event/window/candidate generation. */\nexport const DEFAULT_GENERATION_BUDGET = 1_000_000;\n\n/** Require a finite JavaScript number and return it unchanged. */\nexport function assertFiniteNumber(value: number, name: string): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`${name} must be finite; received ${value}`);\n  }\n  return value;\n}\n\n/** Require an integer in the inclusive range `[min, max]`. */\nexport function assertInteger(\n  value: number,\n  name: string,\n  min = Number.MIN_SAFE_INTEGER,\n  max = Number.MAX_SAFE_INTEGER,\n): number {\n  assertFiniteNumber(value, name);\n  if (!Number.isSafeInteger(value) || value < min || value > max) {\n    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Require a positive safe integer, optionally capped by `max`. */\nexport function assertPositiveInt(\n  value: number,\n  name: string,\n  max = DEFAULT_GENERATION_BUDGET,\n): number {\n  return assertInteger(value, name, 1, max);\n}\n\n/** Require a finite number in the inclusive range `[min, max]`. */\nexport function assertRange(value: number, min: number, max: number, name: string): number {\n  assertFiniteNumber(value, name);\n  if (value < min || value > max) {\n    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Reject work estimates that would exceed a synchronous generation budget. */\nexport function assertGenerationBudget(\n  estimated: number,\n  name: string,\n  limit = DEFAULT_GENERATION_BUDGET,\n): number {\n  assertFiniteNumber(estimated, name);\n  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);\n  if (estimated < 0 || estimated > limit) {\n    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);\n  }\n  return estimated;\n}\n\n/** Validate a time signature, including additive grouping, before any early return. */\nexport function assertTimeSignature(ts: TimeSignature, name = 'time signature'): TimeSignature {\n  assertPositiveInt(ts.numerator, `${name}.numerator`);\n  assertPositiveInt(ts.denominator, `${name}.denominator`);\n  if (ts.grouping !== undefined) {\n    if (ts.grouping.length === 0) {\n      throw new RangeError(`${name}.grouping must not be empty`);\n    }\n    let sum = 0;\n    for (let index = 0; index < ts.grouping.length; index += 1) {\n      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);\n    }\n    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;\n    const pulses = compound ? ts.numerator / 3 : ts.numerator;\n    if (sum !== pulses) {\n      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);\n    }\n  }\n  return ts;\n}\n\n/** Validate the finite fields of one timeline note event. */\nexport function assertNoteEvent(\n  event: NoteEvent,\n  name = 'note event',\n  options: { allowNonPositiveDuration?: boolean } = {},\n): NoteEvent {\n  assertFiniteNumber(event.pitch, `${name}.pitch`);\n  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);\n  assertRange(\n    event.durationBeat,\n    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,\n    Number.MAX_SAFE_INTEGER,\n    `${name}.durationBeat`,\n  );\n  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {\n    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);\n  }\n  if (event.velocity !== undefined) {\n    assertRange(event.velocity, 0, 127, `${name}.velocity`);\n  }\n  return event;\n}\n\n/** Validate an event array and its allocation budget without copying it. */\nexport function assertNoteEvents(\n  events: NoteEvent[],\n  name = 'note events',\n  options: { allowNonPositiveDuration?: boolean; budget?: number } = {},\n): NoteEvent[] {\n  assertGenerationBudget(events.length, `${name} count`, options.budget);\n  for (let index = 0; index < events.length; index += 1) {\n    const event = events[index];\n    if (event !== undefined) {\n      assertNoteEvent(event, `${name}[${index}]`, options);\n    }\n  }\n  return events;\n}\n","/**\n * Counterpoint classification of a harmonic interval.\n *\n * @category Pitch & Intervals\n */\nexport enum IntervalQuality {\n  PerfectConsonance = 0,\n  ImperfectConsonance = 1,\n  Dissonance = 2,\n}\n\n/** Reduce an interval to a simple interval class in the range [0, 11]. */\nfunction simpleInterval(semitones: number): number {\n  return Math.abs(semitones) % 12;\n}\n\n/**\n * Classify an interval for counterpoint evaluation.\n *\n * The interval is reduced modulo 12, so compound intervals classify as their\n * simple equivalents. The perfect fourth (5) is context-dependent: with\n * `twoVoice` (the default) it classifies as a dissonance, matching\n * {@link isConsonantInterval}; otherwise it is an imperfect consonance.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns The counterpoint quality of the interval.\n * @example\n * ```ts\n * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';\n * classifyInterval(7); // IntervalQuality.PerfectConsonance\n * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)\n * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance\n * ```\n * @category Pitch & Intervals\n */\nexport function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {\n  const pc = simpleInterval(semitones);\n  if (pc === 0 || pc === 7) {\n    return IntervalQuality.PerfectConsonance;\n  }\n  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {\n    return IntervalQuality.ImperfectConsonance;\n  }\n  if (pc === 5) {\n    return twoVoice ? IntervalQuality.Dissonance : IntervalQuality.ImperfectConsonance;\n  }\n  return IntervalQuality.Dissonance;\n}\n\n/**\n * Test whether an interval is a perfect interval (unison/octave or fifth).\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.\n * @category Pitch & Intervals\n */\nexport function isPerfectInterval(semitones: number): boolean {\n  const pc = simpleInterval(semitones);\n  return pc === 0 || pc === 7;\n}\n\n/**\n * Test whether an interval is consonant.\n *\n * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint\n * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true\n * excludes it.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns True if the interval is consonant in the given context.\n * @category Pitch & Intervals\n */\nexport function isConsonantInterval(semitones: number, twoVoice = true): boolean {\n  const pc = simpleInterval(semitones);\n  if (pc === 5) {\n    return !twoVoice;\n  }\n  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;\n}\n"],"mappings":"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","names":["IntervalQuality"]}