calliope-ts 0.0.2 → 0.0.4

package/src/clio/caesura.ts

@@ -0,0 +1,145 @@
+// 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 { ClsWord, IntonationalUnit } from '../types.js';
+import { isPunctuation } from './parser.js';
+
+export type CaesuraKind = 'hard' | 'soft';
+
+/** Foot-boundary syllable indices from a scansion string (cumulative syllable
+ *  count after each foot; silent beats '-' are not syllables). */
+function footBoundarySet(scansion: string): Set<number> {
+  const set = new Set<number>();
+  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: ClsWord): boolean {
+  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: ClsWord[], ius: IntonationalUnit[], scansion?: string): Map<number, CaesuraKind> {
+  const caes = new Map<number, CaesuraKind>();
+  // 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<ClsWord, number>();
+  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: number | undefined;
+  let prevWasContentful = false;
+  const onsetPositions: number[] = [];
+  for (const w of words) {
+    if (isPunctuation(w.lexicalClass) || w.syllables.length === 0) continue;
+    const iu = iuOf.get(w);
+    if (prevIu !== undefined && iu !== undefined && iu !== prevIu
+        && (!footEdges || footEdges.has(cum))) {
+      caes.set(cum, 'hard');             // 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;
+
+  // Infer ONE medial caesura only when the line carries no overt (hard) break.
+  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, 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 d = Math.abs(c - mid);
+      if (d < bestDist) { bestDist = d; best = c; }
+    }
+    if (best > 0) caes.set(best, 'soft');
+  }
+  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: ClsWord[], ius: IntonationalUnit[], scansion?: string,
+): { word: ClsWord; kind: CaesuraKind }[] {
+  const caes = computeCaesurae(words, ius, scansion);
+  if (caes.size === 0) return [];
+  const out: { word: ClsWord; kind: CaesuraKind }[] = [];
+  let cum = 0;
+  for (const w of words) {
+    if (isPunctuation(w.lexicalClass) || w.syllables.length === 0) continue;
+    cum += w.syllables.length;
+    const kind = caes.get(cum);
+    if (kind) out.push({ word: w, kind });
+  }
+  return out;
+}

package/src/clio/depfix.ts

@@ -0,0 +1,88 @@
+// depfix.ts — Post-parse dependency repair via DepEdit rules (the `depedits`
+// npm package, the maintainer's TypeScript port of DepEdit).
+//
+// Runs AFTER en-parse, complementing the pre-parse tag corrections in
+// tagfix.ts: tagfix repairs what the tagger got wrong before the tree is
+// built; this pass repairs systematic attachment errors en-parse makes even
+// with correct tags.  Rules are written in DepEdit's declarative format
+// (definitions ⟶ relations ⟶ actions, tab-separated) over en-parse's own
+// label space (DOBJ/NSUBJ/DEP/…), so the round-trip is lossless and every
+// rule is independently testable.
+//
+// The rule set is deliberately small and evidence-based — each rule cites the
+// observed failure it corrects.  `depedits` is ESM-only; it is loaded lazily
+// and failures degrade gracefully (the unrepaired parse is still a parse).
+
+import { createRequire } from 'module';
+
+interface FinDepNode {
+  label: string;      // dependency label, e.g. "NSUBJ", "ROOT"
+  type: string;       // phrase type, e.g. "NP", "VP"
+  parent: number;     // 0-based index of governor token; -1 for root
+}
+
+// Observed failure (probe: "I had quit the programming paradigm"): en-parse
+// attaches BOTH nouns of a noun compound to the verb as parallel objects
+// ("programming ←DOBJ← quit", "paradigm ←DOBJ← quit"), and leaves the
+// determiner dangling on the first noun as generic DEP.  The repairs:
+//   1. Two adjacent common nouns sharing a governor with the same object
+//      relation → the first is a compound modifier (AMOD) of the second.
+//   2. A determiner left as DEP on a noun that has become a modifier →
+//      re-attach it as DET to that noun's head (the true NP head).
+const CALLIOPE_DEP_FIXES = [
+  'xpos=/NNS?/&func=/DOBJ|IOBJ/;xpos=/NNS?/&func=/DOBJ|IOBJ/;xpos=/VB.*/\t#3>#1;#3>#2;#1.#2\t#2>#1;#1:func=AMOD',
+  'xpos=/DT/&func=/DEP|EXT/;xpos=/NNS?/&func=/AMOD/;xpos=/NNS?.*/\t#2>#1;#3>#2\t#3>#1;#1:func=DET',
+].join('\n');
+
+let engine: { process(conllu: string): string } | null | undefined;
+
+function loadEngine(): typeof engine {
+  if (engine !== undefined) return engine;
+  try {
+    // This package compiles to ESM, where bare `require` does not exist, and
+    // the parse path is synchronous, so dynamic import() is not an option:
+    // createRequire gives a sync loader, and since `depedits` is itself
+    // ESM-only this resolves via Node's require(esm) (≥20.17 / ≥22.12).  On
+    // older runtimes it throws and the repair pass degrades to a no-op (the
+    // unrepaired parse is still a parse).
+    const req = createRequire(import.meta.url);
+    const { DepEditEngine } = req('depedits');
+    const e = new DepEditEngine();
+    e.loadIniString(CALLIOPE_DEP_FIXES);
+    engine = e;
+  } catch {
+    engine = null;
+  }
+  return engine;
+}
+
+/**
+ * Repair systematic en-parse attachment errors.  Returns a new deps array
+ * (same shape as en-parse's `toArray` output); on any failure returns the
+ * input unchanged.
+ */
+export function applyDepFixes(tokens: string[], tags: string[], deps: FinDepNode[]): FinDepNode[] {
+  const e = loadEngine();
+  if (!e || tokens.length === 0 || deps.length !== tokens.length) return deps;
+  try {
+    const conllu = tokens.map((tok, i) => {
+      const head = deps[i].parent >= 0 ? deps[i].parent + 1 : 0;
+      const safe = tok.replace(/\s/g, '_') || '_';
+      return `${i + 1}\t${safe}\t${safe}\t_\t${tags[i] || '_'}\t_\t${head}\t${deps[i].label || 'DEP'}\t_\t_`;
+    }).join('\n') + '\n\n';
+    const out = e.process(conllu);
+    const fixed: FinDepNode[] = deps.map(d => ({ ...d }));
+    for (const row of out.split('\n')) {
+      const cols = row.split('\t');
+      if (cols.length < 10) continue;
+      const idx = parseInt(cols[0], 10) - 1;
+      if (!(idx >= 0 && idx < fixed.length)) continue;
+      const head = parseInt(cols[6], 10);
+      fixed[idx].parent = Number.isFinite(head) ? head - 1 : fixed[idx].parent;
+      if (cols[7] && cols[7] !== '_') fixed[idx].label = cols[7];
+    }
+    return fixed;
+  } catch {
+    return deps;
+  }
+}