calliope-ts 0.0.1

package/src/rhyme.ts

@@ -0,0 +1,328 @@
+// rhyme.ts — Rhyme-pair classification, stanza rhyme-scheme detection, and
+// poetic FORM identification.
+//
+// Rhyme typology follows the maintainer's LYRICAL app (meter_exemplars.ts
+// RHYME_TYPES) so the two toolkits stay cross-compatible: perfect / rich /
+// family / assonant / consonant / augmented / diminished / wrenched / eye /
+// identical, with the structural qualifiers masculine / feminine / dactylic.
+// Phonology comes from the augmented CMU dictionary (nounsing-pro); the
+// orthographic (eye/wrenched) tier is a deliberately guarded fallback.
+//
+// FORM is a stanza/poem-level verdict (this is where "ballad" lives — a
+// quatrain with ballad rhyme AND alternating 4·3 beats — NOT in the rhythm
+// pass).  Form names align with LYRICAL's FORM_REGISTRY where they overlap
+// (Couplet, Triplet, Quatrain, Limerick, Petrarchan/Shakespearean Sonnet…).
+
+import * as nounsing from 'nounsing-pro';
+import { LineResult, PhonologicalScansionDetail } from './types.js';
+import { isPunctuation } from './parser.js';
+import { ictusProfile } from './scansion.js';
+
+export type RhymeTypeName =
+  | 'identical' | 'rich' | 'perfect' | 'family'
+  | 'assonant' | 'consonant' | 'augmented' | 'diminished'
+  | 'wrenched' | 'eye';
+
+export interface RhymePair {
+  type: RhymeTypeName;
+  /** masculine (stress on final syllable) / feminine (penult) / dactylic (antepenult) */
+  structure?: 'masculine' | 'feminine' | 'dactylic';
+}
+
+const VOWEL_RE = /^(AA|AE|AH|AO|AW|AY|EH|ER|EY|IH|IY|OW|OY|UH|UW)/;
+const PLOSIVES = new Set(['B', 'D', 'G', 'P', 'T', 'K']);
+const FRICATIVES = new Set(['V', 'DH', 'Z', 'ZH', 'JH', 'F', 'TH', 'S', 'SH', 'CH', 'HH']);
+const NASALS = new Set(['M', 'N', 'NG']);
+
+const isVowelPhone = (p: string) => VOWEL_RE.test(p);
+const base = (p: string) => p.replace(/[0-9]/g, '');
+const sameFamily = (a: string, b: string) =>
+  (PLOSIVES.has(a) && PLOSIVES.has(b)) || (FRICATIVES.has(a) && FRICATIVES.has(b)) || (NASALS.has(a) && NASALS.has(b));
+
+function phonesOf(word: string): string[] | null {
+  const clean = word.toLowerCase().replace(/[^a-z']/g, '');
+  if (!clean) return null;
+  try {
+    const ph = nounsing.firstPhonesForWord(clean);
+    if (typeof ph === 'string' && ph.length > 0) return ph.split(' ');
+  } catch { /* OOV */ }
+  return null;
+}
+
+/** Index of the LAST stressed (1/2) vowel; falls back to the last vowel. */
+function lastStressedIdx(ph: string[]): number {
+  let lastVowel = -1;
+  for (let i = ph.length - 1; i >= 0; i--) {
+    if (!isVowelPhone(ph[i])) continue;
+    if (lastVowel < 0) lastVowel = i;
+    if (/[12]$/.test(ph[i])) return i;
+  }
+  return lastVowel;
+}
+
+/** masculine/feminine/dactylic from how many vowels FOLLOW the rhyming vowel. */
+function structureOf(ph: string[], idx: number): RhymePair['structure'] {
+  let after = 0;
+  for (let i = idx + 1; i < ph.length; i++) if (isVowelPhone(ph[i])) after++;
+  return after === 0 ? 'masculine' : after === 1 ? 'feminine' : 'dactylic';
+}
+
+/** Guarded orthographic tier: shared ending ≥3 chars, matching final phone if
+ *  known, and never on a shared bare "-ing" (mass false positives). */
+function orthographicTier(a: string, b: string, pa: string[] | null, pb: string[] | null): RhymeTypeName | null {
+  const wa = a.toLowerCase().replace(/[^a-z]/g, '');
+  const wb = b.toLowerCase().replace(/[^a-z]/g, '');
+  if (wa.length < 3 || wb.length < 3) return null;
+  let common = 0;
+  while (common < Math.min(wa.length, wb.length) && wa[wa.length - 1 - common] === wb[wb.length - 1 - common]) common++;
+  if (common < 3) return null;
+  if (wa.slice(-3) === 'ing' && wb.slice(-3) === 'ing' && common <= 4) return null;
+  if (pa && pb && base(pa[pa.length - 1]) !== base(pb[pb.length - 1])) return null;
+  // Wrenched when the shared ending is an UNSTRESSED suffix of a polysyllable
+  // (temperate/date, manifestation/convention); plain eye-rhyme otherwise.
+  const polyUnstressed = (ph: string[] | null) => {
+    if (!ph) return false;
+    const idx = lastStressedIdx(ph);
+    return idx >= 0 && structureOf(ph, idx) !== 'masculine';
+  };
+  return polyUnstressed(pa) !== polyUnstressed(pb) ? 'wrenched' : 'eye';
+}
+
+/** Classify the rhyme relation between two line-end words (or null). */
+export function classifyRhymePair(a: string, b: string): RhymePair | null {
+  const wa = a.toLowerCase().replace(/[^a-z']/g, '');
+  const wb = b.toLowerCase().replace(/[^a-z']/g, '');
+  if (!wa || !wb) return null;
+  const pa = phonesOf(a);
+  const pb = phonesOf(b);
+  if (wa === wb) return { type: 'identical', structure: pa ? structureOf(pa, lastStressedIdx(pa)) : undefined };
+  if (!pa || !pb) {
+    const t = orthographicTier(a, b, pa, pb);
+    return t ? { type: t } : null;
+  }
+  const ia = lastStressedIdx(pa);
+  const ib = lastStressedIdx(pb);
+  if (ia < 0 || ib < 0) return null;
+  const ra = pa.slice(ia);
+  const rb = pb.slice(ib);
+  const structure = structureOf(pa, ia);
+  const sameStructure = structure === structureOf(pb, ib);
+
+  const norm = (seg: string[]) => seg.map(base);
+  const na = norm(ra);
+  const nb = norm(rb);
+  const partsEqual = na.length === nb.length && na.every((p, i) => p === nb[i]);
+
+  if (partsEqual && sameStructure) {
+    const onsetA = ia > 0 ? base(pa[ia - 1]) : '';
+    const onsetB = ib > 0 ? base(pb[ib - 1]) : '';
+    return { type: onsetA === onsetB ? 'rich' : 'perfect', structure };
+  }
+
+  const vowelSame = na[0] === nb[0];
+  const codaA = na.slice(1).filter(p => !isVowelPhone(p));
+  const codaB = nb.slice(1).filter(p => !isVowelPhone(p));
+  const codaEq = codaA.length === codaB.length && codaA.every((p, i) => p === codaB[i]);
+
+  if (vowelSame) {
+    // Same stressed vowel.  Matching-length codas whose consonants pair up
+    // within one phonetic family (wet/deck, dame/grain) → family rhyme.
+    if (codaA.length === codaB.length && codaA.length > 0
+        && codaA.every((p, i) => p === codaB[i] || sameFamily(p, codaB[i]))) {
+      return { type: 'family', structure };
+    }
+    // One extra trailing consonant on the second/first word (bray/brave).
+    if (codaA.length + 1 === codaB.length && codaA.every((p, i) => p === codaB[i])) return { type: 'augmented', structure };
+    if (codaB.length + 1 === codaA.length && codaB.every((p, i) => p === codaA[i])) return { type: 'diminished', structure };
+    return { type: 'assonant', structure };
+  }
+  if (codaEq && codaA.length > 0) return { type: 'consonant', structure };
+  const t = orthographicTier(a, b, pa, pb);
+  return t ? { type: t } : null;
+}
+
+// Strength tiers for scheme detection.
+const STRONG: Set<RhymeTypeName> = new Set(['identical', 'rich', 'perfect', 'family']);
+const SLANT: Set<RhymeTypeName> = new Set(['assonant', 'consonant', 'augmented', 'diminished', 'wrenched', 'eye']);
+
+export interface LineRhyme {
+  endWord: string;
+  letter: string;          // scheme letter ('A', 'B', …; '·' = unrhymed)
+  type?: RhymeTypeName;    // relation to the matched earlier line
+  matchedLine?: number;    // 0-based index within the stanza
+}
+
+/** Detect a stanza's rhyme scheme from its line-end words.  Strong rhymes
+ *  bind; slant-tier rhymes bind only when no strong candidate exists. */
+export function detectScheme(endWords: string[]): LineRhyme[] {
+  const out: LineRhyme[] = [];
+  let nextLetter = 0;
+  for (let i = 0; i < endWords.length; i++) {
+    let best: { j: number; pair: RhymePair } | null = null;
+    for (let j = i - 1; j >= 0; j--) {
+      const pair = classifyRhymePair(endWords[j], endWords[i]);
+      if (!pair) continue;
+      if (STRONG.has(pair.type)) { best = { j, pair }; break; }    // nearest strong wins
+      if (!best && SLANT.has(pair.type)) best = { j, pair };       // else nearest slant
+    }
+    if (best) {
+      out.push({ endWord: endWords[i], letter: out[best.j].letter, type: best.pair.type, matchedLine: best.j });
+    } else {
+      out.push({ endWord: endWords[i], letter: String.fromCharCode(65 + (nextLetter++ % 26)) });
+    }
+  }
+  // Rebind pass: a STRONG rhyme claims its partner back from an earlier
+  // slant-tier binding.  (Sonnet 130: "rare" first slant-binds to the red/head
+  // group, then "compare" arrives as its perfect partner — the couplet wins.)
+  for (let k = 0; k < out.length; k++) {
+    const r = out[k];
+    if (r.matchedLine === undefined || !r.type || !STRONG.has(r.type)) continue;
+    const target = out[r.matchedLine];
+    if (target.matchedLine !== undefined && target.type && SLANT.has(target.type)) {
+      const fresh = String.fromCharCode(65 + (nextLetter++ % 26));
+      target.letter = fresh;
+      target.type = undefined;
+      target.matchedLine = undefined;
+      r.letter = fresh;
+    }
+  }
+  // Lines whose letter never recurs are unrhymed: mark '·' for readability.
+  const counts = new Map<string, number>();
+  for (const r of out) counts.set(r.letter, (counts.get(r.letter) ?? 0) + 1);
+  for (const r of out) if ((counts.get(r.letter) ?? 0) < 2) r.letter = '·';
+  // Re-letter the survivors in order of first appearance (A, B, C…).
+  const remap = new Map<string, string>();
+  let k = 0;
+  for (const r of out) {
+    if (r.letter === '·') continue;
+    if (!remap.has(r.letter)) remap.set(r.letter, String.fromCharCode(65 + (k++ % 26)));
+    r.letter = remap.get(r.letter)!;
+  }
+  return out;
+}
+
+const schemeStr = (rs: LineRhyme[]) => rs.map(r => r.letter).join('');
+
+/** Canonical scheme for FORM matching: every line gets a letter in sequential
+ *  first-appearance order, unrhymed lines (·) each their own — so "·A·A"
+ *  compares as "ABCB". */
+function canonicalScheme(rs: LineRhyme[]): string {
+  const remap = new Map<string, string>();
+  let k = 0;
+  const next = () => String.fromCharCode(65 + (k++ % 26));
+  let out = '';
+  for (const r of rs) {
+    if (r.letter === '·') { out += next(); continue; }
+    if (!remap.has(r.letter)) remap.set(r.letter, next());
+    out += remap.get(r.letter)!;
+  }
+  return out;
+}
+
+/** Stanza-level form verdict (LYRICAL-compatible names where they overlap). */
+function stanzaForm(rhymes: LineRhyme[], details: PhonologicalScansionDetail[]): string | undefined {
+  const s = canonicalScheme(rhymes);
+  const n = rhymes.length;
+  const meters = details.map(d => (d.consensusMeter ?? d.meter).split(' ')[0]);
+  const dominant = (name: string, frac = 0.5) => meters.filter(m => m === name).length / n >= frac;
+
+  if (n === 2 && s === 'AA') return 'couplet';
+  if (n === 3) {
+    if (s === 'ABA') return 'triplet (tercet, ABA)';
+    if (s === 'AAA') return 'mono-rhymed triplet';
+  }
+  if (n === 4) {
+    // Beat counts for the ballad gate: footCount (classical) or ictus count.
+    const beats = details.map((d, i) =>
+      d.footCount > 0 ? d.footCount : ictusProfile(d.scansion).ictuses);
+    const alt43 = beats.length === 4 && beats[0] === beats[2] && beats[1] === beats[3]
+      && beats[0] === beats[1] + 1;
+    if (s === 'ABAB' || s === 'ABCB') {
+      if (alt43) return `ballad stanza (${s}, ${beats[0]}·${beats[1]})`;
+      return s === 'ABAB' ? 'quatrain (cross-rhymed, ABAB)' : `ballad-rhyme quatrain (ABCB)`;
+    }
+    if (s === 'ABBA') return 'quatrain (envelope, ABBA)';
+    if (s === 'AABB') return 'quatrain (couplet pair, AABB)';
+    if (s === 'AAAA') return 'mono-rhymed quatrain';
+  }
+  if (n === 5 && s === 'AABBA') {
+    const ternary = meters.filter(m => m === 'anapestic' || m === 'amphibrachic' || m === 'dactylic').length >= 3;
+    return ternary ? 'limerick (AABBA, ternary)' : 'limerick rhyme (AABBA)';
+  }
+  if (n === 6 && s === 'ABABCC') return 'sextilla / Venus-and-Adonis stanza (ABABCC)';
+  if (n === 7 && s === 'ABABBCC') return 'rhyme royal (ABABBCC)';
+  if (n === 8 && (s === 'ABABABCC' || s === 'ABABABAB')) return `octave (${s})`;
+
+  // Unrhymed stanza: blank verse when iambic pentameter dominates.
+  const unrhymed = rhymes.every(r => r.letter === '·');
+  if (unrhymed && n >= 3) {
+    const iambicPenta = details.filter(d =>
+      (d.consensusMeter ?? d.meter) === 'iambic pentameter').length / n;
+    if (iambicPenta >= 0.6) return 'blank verse';
+    if (details.every(d => d.meterName === 'free verse') || details.some(d => d.rhythmNote)) return undefined; // rhythm layer already speaks
+  }
+  return undefined;
+}
+
+/** Poem-level form verdicts that span stanzas (sonnets, terza rima…). */
+function poemForm(stanzas: { rhymes: LineRhyme[]; details: PhonologicalScansionDetail[] }[]): string | undefined {
+  const all = stanzas.flatMap(st => st.rhymes);
+  const n = all.length;
+  // Whole-poem scheme with stanza-local letters concatenated is NOT meaningful;
+  // re-detect across the full poem for sonnet/terza checks.
+  if (n === 14) {
+    const rs = detectScheme(all.map(r => r.endWord));
+    const s = canonicalScheme(rs);
+    if (/^ABABCDCDEFEFGG$/.test(s)) return 'Shakespearean Sonnet';
+    if (/^ABBAABBA/.test(s)) return 'Petrarchan Sonnet';
+    if (s.endsWith('GG') || /(..)\1*..$/.test(s)) {
+      // 14 iambic-pentameter lines with a closing couplet still reads sonnet-like.
+      const last2 = rs[12].letter !== '·' && rs[12].letter === rs[13].letter;
+      const iambicPenta = stanzas.flatMap(st => st.details)
+        .filter(d => (d.consensusMeter ?? d.meter) === 'iambic pentameter').length / 14;
+      if (last2 && iambicPenta >= 0.5) return 'sonnet (14 lines, closing couplet)';
+    }
+  }
+  // Terza rima: chained tercets ABA BCB CDC…
+  if (stanzas.length >= 3 && stanzas.every(st => st.rhymes.length === 3)) {
+    let chained = true;
+    for (let i = 0; i + 1 < stanzas.length && chained; i++) {
+      const mid = stanzas[i].rhymes[1].endWord;
+      const nxt = stanzas[i + 1].rhymes;
+      const p1 = classifyRhymePair(mid, nxt[0].endWord);
+      const p3 = classifyRhymePair(mid, nxt[2].endWord);
+      if (!(p1 && STRONG.has(p1.type)) || !(p3 && STRONG.has(p3.type))) chained = false;
+    }
+    if (chained) return 'terza rima (ABA BCB CDC…)';
+  }
+  return undefined;
+}
+
+/** Last syllable-bearing word of a line (across its merged sentences). */
+function lineEndWord(line: LineResult): string {
+  const ws = line.sentence.words.filter(w => !isPunctuation(w.lexicalClass) && w.syllables.length > 0);
+  return ws.length ? ws[ws.length - 1].word : '';
+}
+
+/**
+ * Annotate rhyme letters/types (`detail.rhyme`) and form verdicts
+ * (`detail.formNote`) across a poem.  Stanza forms are per-stanza; a poem-level
+ * form (sonnet, terza rima) overrides stanza notes.  Annotation-only — no
+ * meter/scansion/certainty is touched.
+ */
+export function applyRhymeAndForm(stanzas: LineResult[][]): void {
+  const analyzed = stanzas.map(lines => {
+    const details = lines.map(l => l.phonologicalScansion);
+    const rhymes = detectScheme(lines.map(lineEndWord));
+    return { details, rhymes };
+  });
+  for (const { details, rhymes } of analyzed) {
+    const form = stanzaForm(rhymes, details);
+    for (let i = 0; i < details.length; i++) {
+      details[i].rhyme = rhymes[i];
+      details[i].formNote = form;
+    }
+  }
+  const pform = poemForm(analyzed);
+  if (pform) for (const { details } of analyzed) for (const d of details) d.formNote = pform;
+}