calliope-ts 0.0.2 → 0.0.4

package/dist/clio/caesura.d.ts

@@ -0,0 +1,27 @@
+import { ClsWord, IntonationalUnit } from '../types.js';
+export type CaesuraKind = 'hard' | 'soft';
+/**
+ * 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 declare function computeCaesurae(words: ClsWord[], ius: IntonationalUnit[], scansion?: string): Map<number, CaesuraKind>;
+/**
+ * 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 declare function preCaesuralWords(words: ClsWord[], ius: IntonationalUnit[], scansion?: string): {
+    word: ClsWord;
+    kind: CaesuraKind;
+}[];
+//# sourceMappingURL=caesura.d.ts.map

package/dist/clio/caesura.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caesura.d.ts","sourceRoot":"","sources":["../../src/clio/caesura.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAyC1C;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAoDtH;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,EAAE,CAYxC"}

package/dist/clio/caesura.js

@@ -0,0 +1,148 @@
+// 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';
+/** 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();
+    // 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)
+            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, 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 kind = caes.get(cum);
+        if (kind)
+            out.push({ word: w, kind });
+    }
+    return out;
+}

package/dist/clio/depfix.d.ts

@@ -0,0 +1,13 @@
+interface FinDepNode {
+    label: string;
+    type: string;
+    parent: number;
+}
+/**
+ * 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 declare function applyDepFixes(tokens: string[], tags: string[], deps: FinDepNode[]): FinDepNode[];
+export {};
+//# sourceMappingURL=depfix.d.ts.map

package/dist/clio/depfix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depfix.d.ts","sourceRoot":"","sources":["../../src/clio/depfix.ts"],"names":[],"mappings":"AAiBA,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAwBhG"}

package/dist/clio/depfix.js

@@ -0,0 +1,84 @@
+// 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';
+// 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;
+function loadEngine() {
+    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, tags, deps) {
+    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 = 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;
+    }
+}

package/dist/clio/display.d.ts

@@ -0,0 +1,32 @@
+import { ClsWord, LineResult } from '../types.js';
+export declare function renderUnifiedDisplay(result: LineResult, rawLine?: string): string;
+export declare function renderLegend(): string;
+/**
+ * The long-form legend triggered from the main menu's "Display Legend" option:
+ * the compact legend PLUS full Penn POS-tag and grammatical-dependency glossaries.
+ * (These glossaries are deliberately NOT part of the compact in-output legend.)
+ */
+export declare function renderFullLegend(): string;
+/** One input line with its (1+) parsed sentence results. */
+export interface ReadingLine {
+    raw: string;
+    results: LineResult[];
+}
+/** A stanza: a run of consecutive non-blank input lines. */
+export interface ReadingStanza {
+    lines: ReadingLine[];
+}
+/**
+ * Project per-syllable stress colours back onto the original line, preserving
+ * capitalisation, punctuation, spacing and any extrametrical fragments the
+ * pipeline dropped (e.g. possessive "'s").  Word-like tokens are coloured;
+ * everything between them (spaces, punctuation, dashes) is emitted verbatim.
+ *
+ * Alignment is tolerant: it matches each token to the next parsed word by
+ * normalised form (equal, or token starts with the word — handling "cat's"),
+ * with a small look-ahead resync so a stray/unsyllabified token never derails
+ * the rest of the line.  No original character is ever dropped.
+ */
+export declare function projectStressOntoLine(rawLine: string, words: ClsWord[]): string;
+export declare function renderReadingView(stanzas: ReadingStanza[]): string;
+//# sourceMappingURL=display.d.ts.map

package/dist/clio/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../src/clio/display.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,OAAO,EAMP,UAAU,EAGX,MAAM,aAAa,CAAC;AAuJrB,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAsQjF;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAUrC;AAuHD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAsBzC;AAqCD,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAuC/E;AAuOD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CA0FlE"}