calliope-ts 0.0.1 → 0.0.3

package/dist/caesura.js

@@ -0,0 +1,202 @@
+// caesura.ts — Caesura placement, shared by the display and rhyme layers.
+//
+// A caesura is the line's medial pause.  Two kinds are distinguished:
+//  • 'hard' — an overt break at an Intonational-Unit boundary (comma, dash,
+//    colon, semicolon …): the punctuation projection.
+//  • 'soft' — a single INFERRED medial caesura for a punctuation-free line
+//    (Kiparsky 1975, via McAleese: "phonological phrasing determines the
+//    location of caesurae in verse").
+//
+// Extracted from display.ts (2026-06-13) so the rhyme layer can find the words
+// that immediately precede caesurae (for pre-caesural internal-rhyme detection)
+// without importing the display module.  Pure analysis — no colour/chalk here.
+import { isPunctuation } from './parser.js';
+import { computeBoundaries } from './calliope/boundaries.js';
+/** Foot-boundary syllable indices from a scansion string (cumulative syllable
+ *  count after each foot; silent beats '-' are not syllables). */
+function footBoundarySet(scansion) {
+    const set = new Set();
+    let c = 0;
+    for (const foot of scansion.split('|')) {
+        for (const ch of foot)
+            if ('xwnms'.includes(ch))
+                c++;
+        set.add(c);
+    }
+    return set;
+}
+// A new phonological/syntactic phrase opens at these POS tags: prepositions &
+// subordinators (IN), infinitival "to" (TO), coordinators (CC), wh/relativizers,
+// verb-particles (RP), and the predicate's verb/modal.  The major medial caesura
+// of a line falls immediately BEFORE such a word — far more reliably read off the
+// (robust) POS tags than off FinNLP's (noisy) phonological-phrase grouping, which
+// mis-bracketed e.g. "The epic | feast…".  Determiners/articles are excluded (they
+// continue a phrase a preposition already opened: "as | one empty bag").
+const PHRASE_ONSET_POS = new Set([
+    'IN', 'TO', 'CC', 'WDT', 'WP', 'WP$', 'WRB', 'RP',
+    'VB', 'VBD', 'VBG', 'VBN', 'VBP', 'VBZ', 'MD',
+]);
+// Directional/spatial adverbs that open a phrase ("snowed-in OUT of many routes",
+// "drifting DOWN to sleep").  FinNLP often tags these RB rather than RP/IN, so the
+// POS set alone misses them; a small curated lemma list recovers them with low
+// over-fire risk (a generic RB like "very"/"quickly" is NOT a phrase onset).
+const DIRECTIONAL_ONSET = new Set([
+    'out', 'in', 'up', 'down', 'off', 'away', 'back', 'forth', 'over',
+    'around', 'along', 'through', 'apart', 'aside', 'onward', 'onwards',
+]);
+/** True if a word opens a new phonological/syntactic phrase (a caesura candidate). */
+function isPhraseOnset(w) {
+    if (PHRASE_ONSET_POS.has(w.lexicalClass))
+        return true;
+    return w.lexicalClass === 'RB' && DIRECTIONAL_ONSET.has(w.word.toLowerCase());
+}
+/**
+ * Caesura positions for a line, keyed by the syllable index AFTER which the pause
+ * falls (= number of syllables to its left).
+ *  • 'hard' — an overt break at an Intonational-Unit boundary.
+ *  • 'soft' — a single INFERRED medial caesura for a punctuation-free line.
+ *    Candidates are the boundaries just before a phrase/clause onset
+ *    (PHRASE_ONSET_POS); the one nearest the line's midpoint that lies in the
+ *    central third AND coincides with a foot boundary wins — so it is medial,
+ *    never mid-foot, and consistent across structurally-parallel lines.  Read in
+ *    LINEAR order (robust to clitic-group reordering); needs a line of ≥ 8
+ *    syllables.
+ */
+export function computeCaesurae(words, ius, scansion) {
+    const caes = new Map();
+    // Graded boundary strength (Wagner Ch.4–5) keyed by syllable index, so each
+    // caesura carries the strength of its underlying ϕ/ι break — used both to COLOUR
+    // the mark and to gate strong-ϕ hard caesurae on a line-relative threshold.
+    const bounds = computeBoundaries(words, ius);
+    const strengthAt = new Map();
+    for (const b of bounds.phi) {
+        const prev = strengthAt.get(b.syllableIndex) ?? 0;
+        if (b.strength > prev)
+            strengthAt.set(b.syllableIndex, b.strength);
+    }
+    const strOf = (syl) => strengthAt.get(syl) ?? 0;
+    const setHard = (syl) => caes.set(syl, { kind: 'hard', strength: Math.max(0.6, strOf(syl)) });
+    // Caesurae must sit on FOOT BOUNDARIES (when the scansion is known).  The line's
+    // metrical feet ARE the scansion's own segmentation, so a break that falls mid-
+    // foot has no metrical reality — it merely fragments a foot (often into a lone
+    // monosyllable: "But ‖ Oh ‖ ye…") and it made the reading view disagree with the
+    // detailed "Feet:" view, which already marks foot-edge breaks only.  Punctuation
+    // is a caesura CANDIDATE, never an override: an IU boundary that does not land on
+    // a foot edge is dropped (the soft-caesura fallback below then offers one medial,
+    // foot-aligned break if the line is long enough).
+    const footEdges = scansion ? footBoundarySet(scansion) : null;
+    const iuOf = new Map();
+    for (let i = 0; i < ius.length; i++) {
+        for (const pp of ius[i].phonologicalPhrases) {
+            for (const cg of pp.cliticGroups)
+                for (const tok of cg.tokens)
+                    iuOf.set(tok, i);
+        }
+    }
+    let cum = 0;
+    let prevIu;
+    let prevWasContentful = false;
+    const onsetPositions = [];
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass) || w.syllables.length === 0) {
+            // A COMMA is an overt medial pause — the canonical caesura marker — but in
+            // the Match-Theory hierarchy it is only a ϕ (minor) break, NOT an ι boundary
+            // (dash/colon/semicolon DO project an ι, so those are caught by the IU test
+            // below).  So detect a comma here directly: a comma after a contentful word,
+            // landing on a foot edge, is a hard caesura.  (Without this, the comma→ϕ
+            // reclassification silently dropped every comma caesura, taking pre-caesural
+            // and caesural internal-rhyme detection with it.)
+            if (prevWasContentful && (w.lexicalClass === ',' || w.word === ',')
+                && (!footEdges || footEdges.has(cum))) {
+                setHard(cum);
+            }
+            continue;
+        }
+        const iu = iuOf.get(w);
+        if (prevIu !== undefined && iu !== undefined && iu !== prevIu
+            && (!footEdges || footEdges.has(cum))) {
+            setHard(cum); // IU boundary landing on a foot edge → hard caesura
+        }
+        // A phrase-onset word that is NOT the line's first word opens a candidate
+        // caesura immediately before it.
+        if (prevWasContentful && isPhraseOnset(w))
+            onsetPositions.push(cum);
+        cum += w.syllables.length;
+        prevIu = iu;
+        prevWasContentful = true;
+    }
+    const total = cum;
+    // STRONG-ϕ hard caesura (Wagner Ch.5): a ϕ boundary whose NSBR-scaled strength
+    // clears a line-relative threshold — a major medial break after a long branching
+    // phrase — is a hard caesura even without punctuation, provided it lands on a foot
+    // edge and is medial.  Threshold is relative (strength is already line-normalised),
+    // so a comma after a short phrase does NOT trigger one.
+    if (total >= 8) {
+        const lo = Math.max(2, Math.ceil(total / 3));
+        const hi = Math.floor((2 * total) / 3);
+        for (const b of bounds.phi) {
+            const c = b.syllableIndex;
+            if (c < lo || c > hi)
+                continue;
+            if (footEdges && !footEdges.has(c))
+                continue;
+            if (caes.has(c))
+                continue;
+            if (b.strength >= 0.75)
+                caes.set(c, { kind: 'hard', strength: b.strength });
+        }
+    }
+    // Infer ONE medial caesura only when the line carries no overt (hard) break.
+    // Prefer the STRONGEST candidate boundary, tie-broken by nearness to the midpoint.
+    if (caes.size === 0 && total >= 8 && onsetPositions.length > 0) {
+        const mid = total / 2;
+        const lo = Math.max(2, Math.ceil(total / 3));
+        const hi = Math.floor((2 * total) / 3);
+        let best = -1, bestStr = -1, bestDist = Infinity;
+        for (const c of onsetPositions) {
+            if (c < lo || c > hi)
+                continue; // medial third only
+            if (footEdges && !footEdges.has(c))
+                continue; // align to a foot boundary
+            const str = strOf(c);
+            const d = Math.abs(c - mid);
+            if (str > bestStr + 1e-6 || (Math.abs(str - bestStr) <= 1e-6 && d < bestDist)) {
+                bestStr = str;
+                bestDist = d;
+                best = c;
+            }
+        }
+        if (best > 0)
+            caes.set(best, { kind: 'soft', strength: Math.max(0.25, bestStr) });
+    }
+    // A caesura is a MEDIAL pause: a line-terminal comma/IU close lands at the last
+    // syllable (cum == total) and is the line break's own boundary, not a caesura.
+    // Dropping it here keeps every consumer consistent — the detailed view used to
+    // print a spurious trailing '‖' the reading view (correctly) never showed, and
+    // the rhyme layer would have double-counted the end word as "pre-caesural".
+    caes.delete(total);
+    return caes;
+}
+/**
+ * The words that immediately PRECEDE a caesura in a line — i.e. each word whose
+ * cumulative syllable count lands exactly on a caesura position.  Used by the
+ * rhyme layer for pre-caesural internal-rhyme detection.  Returned in linear
+ * (reading) order; the caesura kind is paired so callers can weight hard vs
+ * inferred breaks if they wish.
+ */
+export function preCaesuralWords(words, ius, scansion) {
+    const caes = computeCaesurae(words, ius, scansion);
+    if (caes.size === 0)
+        return [];
+    const out = [];
+    let cum = 0;
+    for (const w of words) {
+        if (isPunctuation(w.lexicalClass) || w.syllables.length === 0)
+            continue;
+        cum += w.syllables.length;
+        const info = caes.get(cum);
+        if (info)
+            out.push({ word: w, kind: info.kind });
+    }
+    return out;
+}

package/dist/calliope/boundaries.d.ts

@@ -0,0 +1,19 @@
+import { ClsWord, IntonationalUnit } from '../types.js';
+export interface BoundaryInfo {
+    level: 'kappa' | 'phi' | 'iota';
+    strength: number;
+    raw: number;
+    syllableIndex: number;
+}
+export interface LineBoundaries {
+    /** ϕ boundaries in document order: phi[k] is the boundary OPENING the k-th ϕ.
+     *  phi[0] is the line's left edge (strength 0 — not a real internal break). */
+    phi: BoundaryInfo[];
+    /** ι boundaries in document order, same convention. */
+    iota: BoundaryInfo[];
+}
+/**
+ * Compute graded boundary strength for every ϕ and ι boundary in a line.
+ */
+export declare function computeBoundaries(words: ClsWord[], ius: IntonationalUnit[]): LineBoundaries;
+//# sourceMappingURL=boundaries.d.ts.map

package/dist/calliope/boundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries.d.ts","sourceRoot":"","sources":["../../src/calliope/boundaries.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B;mFAC+E;IAC/E,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,uDAAuD;IACvD,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAuFD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,cAAc,CAyD3F"}

package/dist/calliope/boundaries.js

@@ -0,0 +1,182 @@
+// calliope/boundaries.ts — graded prosodic boundary strength (Wagner 2005 Ch. 4–5).
+//
+// The labelled κ/ϕ/ι hierarchy is the SKELETON; this module adds the relational
+// FLESH Wagner argues the grid actually encodes — a graded boundary strength rather
+// than a categorical label.  Each ϕ/ι boundary gets a strength scaled RELATIVE to the
+// line's other boundaries (the NSBR, Normalized Scopally-determined Boundary Rank,
+// Ch. 5 §5.3): the strongest boundary in the line is 1.0, the rest fall below it.
+//
+// The raw strength of a boundary between left unit A and right unit B combines:
+//   • the categorical level (ι ≫ ϕ ≫ κ) — the SBR base rank;
+//   • punctuation coincidence — a comma/dash/colon at the boundary makes it stronger;
+//   • the LENGTH of the preceding constituent (a boundary after a long, branching
+//     phrase is stronger — Wagner Ch. 5 look-back);
+//   • clause separation — a boundary between subject|predicate or main|subordinate
+//     clause (their dependency LCA is at/near the root) is stronger;
+//   • associative coordination — a boundary internal to a same-coordinator series is
+//     WEAKER (equal-rank, flat).
+//
+// Strength feeds (a) the colored bracket rendering (display.ts) and (b) caesura
+// placement (caesura.ts): a hard caesura needs a boundary whose strength clears a
+// line-relative threshold, not an absolute one.
+function isPunct(w) {
+    return /^[^A-Za-z0-9]+$/.test(w.lexicalClass) || w.syllables.length === 0;
+}
+/** Dependency depth of a word (number of governors up to the root). */
+function depthOf(w, memo) {
+    const seen = new Set();
+    let d = 0;
+    let cur = w;
+    while (cur) {
+        if (memo.has(cur)) {
+            d += memo.get(cur);
+            break;
+        }
+        if (seen.has(cur))
+            break; // cycle guard
+        seen.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        d++;
+        cur = g;
+    }
+    memo.set(w, d);
+    return d;
+}
+/** The syntactic head of a ϕ — the lowest-depth (closest to root) content token. */
+function phraseHead(tokens, memo) {
+    let best = null;
+    let bestD = Infinity;
+    for (const t of tokens) {
+        if (isPunct(t))
+            continue;
+        const d = depthOf(t, memo);
+        if (d < bestD) {
+            bestD = d;
+            best = t;
+        }
+    }
+    return best;
+}
+/** Lowest-common-ancestor depth of two words in the dependency tree. */
+function lcaDepth(a, b, memo) {
+    const anc = new Map();
+    let cur = a;
+    let d = 0;
+    const seen = new Set();
+    while (cur && !seen.has(cur)) {
+        anc.set(cur, d++);
+        seen.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        cur = g;
+    }
+    cur = b;
+    const seen2 = new Set();
+    while (cur && !seen2.has(cur)) {
+        if (anc.has(cur))
+            return depthOf(cur, memo);
+        seen2.add(cur);
+        const g = cur.dependency?.governor;
+        if (!g || g === cur || isPunct(g))
+            break;
+        cur = g;
+    }
+    return 0; // disjoint subtrees / different roots → treat as top-level (depth 0)
+}
+/** Is there a comma / dash / terminal punctuation token between A and B in surface
+ *  order, and is it a strong (ι-class) one? */
+function punctBetween(words, a, b) {
+    let comma = false, strong = false;
+    for (const w of words) {
+        if (w.absoluteIndex <= a.absoluteIndex || w.absoluteIndex >= b.absoluteIndex)
+            continue;
+        if (!isPunct(w))
+            continue;
+        if (w.word === ',' || w.lexicalClass === ',')
+            comma = true;
+        if (/^[.!?:;…]$/.test(w.word) || /^[.!?:;-]$/.test(w.lexicalClass) ||
+            w.lexicalClass === '-LRB-' || w.lexicalClass === '-RRB-')
+            strong = true;
+    }
+    return { comma, strong };
+}
+function sylCount(tokens) {
+    let n = 0;
+    for (const t of tokens)
+        n += t.syllables.length;
+    return n;
+}
+/** Flatten the ϕ of an ι into token lists. */
+function phiTokenLists(iu) {
+    return iu.phonologicalPhrases.map(pp => pp.cliticGroups.flatMap(cg => cg.tokens).filter(t => !isPunct(t)));
+}
+/**
+ * Compute graded boundary strength for every ϕ and ι boundary in a line.
+ */
+export function computeBoundaries(words, ius) {
+    const memo = new Map();
+    const maxDepth = Math.max(1, ...words.filter(w => !isPunct(w)).map(w => depthOf(w, memo)));
+    // Flatten ϕ across all ι in document order, remembering each ϕ's ι index.
+    const flatPhi = [];
+    ius.forEach((iu, iuIdx) => {
+        phiTokenLists(iu).forEach((tokens, ppIdx) => {
+            if (tokens.length)
+                flatPhi.push({ tokens, iuIdx, ppIdx });
+        });
+    });
+    let cumSyl = 0;
+    const phi = [];
+    const iota = [];
+    for (let k = 0; k < flatPhi.length; k++) {
+        const cur = flatPhi[k];
+        const prev = k > 0 ? flatPhi[k - 1] : null;
+        const isIotaBoundary = !!prev && cur.iuIdx !== prev.iuIdx;
+        let raw = 0;
+        if (prev) {
+            const aHead = phraseHead(prev.tokens, memo); // left phrase head
+            const bHead = phraseHead(cur.tokens, memo); // right phrase head
+            const aLast = prev.tokens[prev.tokens.length - 1];
+            const bFirst = cur.tokens[0];
+            // base rank by level
+            raw += isIotaBoundary ? 3.0 : 1.0;
+            // punctuation coincidence
+            const p = punctBetween(words, aLast, bFirst);
+            if (p.strong)
+                raw += 2.0;
+            else if (p.comma)
+                raw += 1.2;
+            // length of the preceding constituent (look-back): longer → stronger
+            raw += Math.min(1.5, sylCount(prev.tokens) / 6);
+            // clause separation: a shallow dependency LCA (near the root) → strong
+            if (aHead && bHead) {
+                const lca = lcaDepth(aHead, bHead, memo);
+                raw += 1.2 * (1 - Math.min(1, lca / maxDepth)); // shallow LCA → +clause bonus
+            }
+            // associative coordination weakening: same coordinator across the boundary
+            if (startsCoordinator(cur.tokens) && !p.comma && !p.strong)
+                raw -= 0.4;
+        }
+        const info = {
+            level: isIotaBoundary ? 'iota' : 'phi',
+            strength: 0, // filled after normalisation
+            raw: Math.max(0, raw),
+            syllableIndex: cumSyl,
+        };
+        phi.push(info);
+        if (isIotaBoundary)
+            iota.push(info);
+        cumSyl += sylCount(cur.tokens);
+    }
+    // NSBR normalisation: scale to the strongest boundary in the line (0..1).
+    const maxRaw = Math.max(0, ...phi.map(b => b.raw));
+    for (const b of phi)
+        b.strength = maxRaw > 0 ? b.raw / maxRaw : 0;
+    return { phi, iota };
+}
+function startsCoordinator(tokens) {
+    const t = tokens[0];
+    return !!t && (t.lexicalClass === 'CC' || t.canonicalRel === 'CC');
+}

package/dist/calliope/bracketing.d.ts

@@ -0,0 +1,11 @@
+import { ClsSentence, ClsWord } from '../types.js';
+/**
+ * Run the cyclic Compound + Nuclear Stress Rules (Wagner-extended) over the
+ * sentence's dependency tree and write each word's `phraseStress` (1 = strongest).
+ */
+export declare function computePhraseStress(sent: ClsSentence): void;
+/**
+ * Partition the sentence's words into ϕ-domains over the dependency tree.
+ */
+export declare function computePhiDomains(sent: ClsSentence): Map<ClsWord, number>;
+//# sourceMappingURL=bracketing.d.ts.map

package/dist/calliope/bracketing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bracketing.d.ts","sourceRoot":"","sources":["../../src/calliope/bracketing.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AA4HnD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAmF3D;AA4GD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CA6BzE"}