calliope-ts 0.0.1

package/dist/scandroid.js

@@ -0,0 +1,435 @@
+// scandroid.ts — Optional Scandroid integration: provides classic iambic and
+// anapestic scansion algorithms from Hartman’s Scandroid, adapted to TypeScript.
+// This module is purely functional; it does not modify the main pipeline and
+// can be omitted without affecting the phonological scansion.
+// ─── Constants from scanstrings.py ─────────────────────────────────
+const STRESS = '/';
+const SLACK = 'x';
+const PROMOTED = '%';
+const FOOTDIV = '|';
+/** Foot dictionary for iambic lines (Scandroid’s footDict). */
+const IAMBIC_FOOT_DICT = {
+    'x/': 'iamb',
+    'xx': 'pyrrhic',
+    '//': 'spondee',
+    '/x': 'trochee',
+    'x/x': 'amphibrach',
+    '//x': 'palimbacchius',
+    'xx/': 'anapest',
+    '/': 'defective',
+    '/xx': 'dactyl',
+    '/x/': 'cretic',
+    'x//': 'bacchius',
+    'x%': '(iamb)',
+    'xx%': '(anapest)',
+    '%x': '(trochee)',
+    'x/xx': '2nd paeon',
+    'xx/x': '3rd paeon',
+};
+/** Foot dictionary for anapestic lines (Scandroid’s AnapSubs). */
+const ANAPESTIC_FOOT_DICT = {
+    'xx/': 'anapest',
+    '/x/': 'cretic',
+    'x//': 'bacchius',
+    'x/': 'iamb',
+    'x%': '(iamb)',
+    'xx%': '(anapest)',
+    '//': 'spondee',
+    'xx/x': '3rd paeon',
+    'x/x': 'amphibrach',
+    '///': 'molossus',
+    '/x%': '(cretic)',
+    '//x': 'palimbacchius',
+};
+// ─── Utility functions (adapted from scanutilities.py) ────────────
+/** Generator-like function to walk through a string in chunks, matching a dictionary. */
+function footFinder(fDict, str, chunkSize, start, end) {
+    const result = [];
+    let pos = start;
+    while (pos < end) {
+        const chunk = str.slice(pos, pos + chunkSize);
+        if (chunk in fDict) {
+            pos += chunkSize;
+            result.push({ foot: fDict[chunk], index: pos });
+        }
+        else {
+            // signal failure by returning empty array
+            return [];
+        }
+    }
+    return result;
+}
+/** Find the longest match of a RegExp in a string (last occurrence of longest length). */
+function longestMatch(rx, s) {
+    let start = -1, length = 0;
+    let current = 0;
+    let m;
+    while ((m = rx.exec(s.slice(current))) !== null) {
+        const mStart = current + m.index;
+        const mEnd = mStart + m[0].length;
+        if (mEnd - mStart >= length) {
+            start = mStart;
+            length = mEnd - mStart;
+        }
+        current = mStart + 1;
+    }
+    return start >= 0 ? { start, length } : null;
+}
+/** Compute line length in feet by counting non-adjacent stresses (for anapestic estimation). */
+function altLineLenCalc(marks) {
+    const arr = marks.split('');
+    for (let i = 0; i < arr.length; i++) {
+        if (i === 0 || arr[i - 1] === '/') {
+            if (arr[i] === '/')
+                arr[i] = 'x';
+        }
+    }
+    return arr.filter(ch => ch === '/').length;
+}
+// ─── Complexity measurement (from Scandroid’s _measureComplexity) ──
+function iambicComplexity(footlist, numFeet) {
+    if (footlist.length !== numFeet)
+        return 100;
+    let prevIsTrochee = false;
+    let points = 0;
+    for (let i = 0; i < footlist.length; i++) {
+        let f = footlist[i];
+        if (f.startsWith('(') && f.endsWith(')'))
+            f = f.slice(1, -1);
+        if (['spondee', 'pyrrhic', 'trochee'].includes(f))
+            points += 2;
+        if (['anapest', 'defective', '3rd paeon', 'amphibrach', 'palimbacchius', '2nd paeon'].includes(f))
+            points += 4;
+        if (['dactyl', 'cretic', 'bacchius'].includes(f))
+            points += 10;
+        if (f === 'trochee') {
+            if (i === footlist.length - 1)
+                points += 6;
+            if (prevIsTrochee)
+                points += 8;
+            prevIsTrochee = true;
+        }
+        else
+            prevIsTrochee = false;
+        if ((f === 'trochee' || f === 'defective') /* bounds test omitted for simplicity */)
+            points += 4;
+    }
+    return points;
+}
+function anapesticComplexity(footlist) {
+    if (footlist.length === 0)
+        return 100;
+    let points = 0;
+    for (const f of footlist) {
+        if (f === 'bacchius')
+            points += 2;
+        else if (f === '(anapest)')
+            points += 1;
+        else if (f === 'iamb' || f === '(iamb)')
+            points += 2;
+        else if (f === 'cretic')
+            points += 4;
+        else if (['spondee', 'pyrrhic'].includes(f))
+            points += 4;
+        else if (['amphibrach', '3rd paeon'].includes(f))
+            points += 4;
+        else if (['2nd paeon', 'molossus', 'palimbacchius'].includes(f))
+            points += 5;
+    }
+    return points;
+}
+// ─── Iambic Algorithm 1: Corral the Weird ─────────────────────────
+export function scandroidCorralWeird(marks, numFeet) {
+    const footlist = [];
+    let remaining = marks;
+    let lastFoot = '';
+    // Step 1: handle terminal slack (extra syllables at end)
+    const normLen = numFeet * 2;
+    if (remaining.length > normLen + 1 && ['x/xx', 'xx/x'].includes(remaining.slice(-4))) {
+        lastFoot = IAMBIC_FOOT_DICT[remaining.slice(-4)];
+        remaining = remaining.slice(0, -4);
+    }
+    else if (remaining.length >= normLen && ['x/x', '//x'].includes(remaining.slice(-3))) {
+        lastFoot = IAMBIC_FOOT_DICT[remaining.slice(-3)];
+        remaining = remaining.slice(0, -3);
+    }
+    // Step 2: handle acephalous (headless) line
+    if (remaining.length <= normLen - 2 && (remaining.startsWith('/x/x') || remaining.startsWith('/xxx'))) {
+        footlist.push('defective');
+        remaining = remaining.slice(1);
+    }
+    const currLen = remaining.length;
+    const needFeet = numFeet - footlist.length - (lastFoot ? 1 : 0);
+    const targetLen = needFeet * 2;
+    if (currLen === targetLen) {
+        const feet = footFinder(IAMBIC_FOOT_DICT, remaining, 2, 0, currLen);
+        if (feet.length === 0)
+            return { footlist: [], scansionMarks: '' };
+        footlist.push(...feet.map(f => f.foot));
+    }
+    else if (currLen < targetLen) {
+        // seek a defective foot (single stress)
+        const candidate = remaining.indexOf('x//');
+        if (candidate === -1 || candidate % 2 !== 0)
+            return { footlist: [], scansionMarks: '' };
+        const defectivePos = candidate + 2;
+        const before = footFinder(IAMBIC_FOOT_DICT, remaining, 2, 0, defectivePos);
+        if (before.length === 0)
+            return { footlist: [], scansionMarks: '' };
+        footlist.push(...before.map(f => f.foot));
+        footlist.push('defective');
+        const after = footFinder(IAMBIC_FOOT_DICT, remaining, 2, defectivePos + 1, currLen);
+        if (after.length === 0)
+            return { footlist: [], scansionMarks: '' };
+        footlist.push(...after.map(f => f.foot));
+    }
+    else {
+        // need anapests to fill extra syllables
+        const need = currLen - targetLen;
+        // collect candidate positions for anapest insertion
+        const candidates = [];
+        for (let i = 0; i < remaining.length; i++) {
+            if (remaining.slice(i, i + 4) === '/xx/')
+                candidates.push(i + 1);
+        }
+        if (candidates.length < need) {
+            for (let i = 0; i < remaining.length; i++) {
+                if (remaining.slice(i, i + 3) === 'xx/')
+                    candidates.push(i);
+            }
+        }
+        let pos = 0;
+        let anapestsUsed = 0;
+        while (pos < currLen) {
+            if (anapestsUsed < need && candidates.includes(pos)) {
+                const chunk = remaining.slice(pos, pos + 3);
+                if (!(chunk in IAMBIC_FOOT_DICT))
+                    return { footlist: [], scansionMarks: '' };
+                footlist.push(IAMBIC_FOOT_DICT[chunk]);
+                pos += 3;
+                anapestsUsed++;
+            }
+            else {
+                const chunk = remaining.slice(pos, pos + 2);
+                if (!(chunk in IAMBIC_FOOT_DICT))
+                    return { footlist: [], scansionMarks: '' };
+                footlist.push(IAMBIC_FOOT_DICT[chunk]);
+                pos += 2;
+            }
+        }
+    }
+    if (lastFoot)
+        footlist.push(lastFoot);
+    // Generate scansion string with foot divisions
+    const scansion = footlist.map(f => f.startsWith('(') ? f : f).join('|'); // simplistic
+    return { footlist, scansionMarks: scansion };
+}
+// ─── Iambic Algorithm 2: Maximize the Normal ─────────────────────
+export function scandroidMaximizeNormal(marks, numFeet) {
+    const possIambRE = /(x[x/])+/;
+    const match = longestMatch(possIambRE, marks);
+    if (!match)
+        return { footlist: [], scansionMarks: '' };
+    const { start, length } = match;
+    const runEnd = start + length;
+    const headMarks = marks.slice(0, start);
+    const tailMarks = marks.slice(runEnd);
+    const mainMarks = marks.slice(start, runEnd);
+    const footlist = [];
+    const headFeet = [];
+    const tailFeet = [];
+    // Scan the regular middle stretch
+    const mainFeet = footFinder(IAMBIC_FOOT_DICT, mainMarks, 2, 0, mainMarks.length);
+    if (mainFeet.length === 0)
+        return { footlist: [], scansionMarks: '' };
+    footlist.push(...mainFeet.map(f => f.foot));
+    // Scan head
+    if (headMarks.length > 0) {
+        if (headMarks.length % 2 === 0) {
+            const hf = footFinder(IAMBIC_FOOT_DICT, headMarks, 2, 0, headMarks.length);
+            if (hf.length === 0)
+                return { footlist: [], scansionMarks: '' };
+            headFeet.push(...hf.map(f => f.foot));
+        }
+        else {
+            if (headMarks.startsWith('/x')) {
+                headFeet.push('defective');
+                const rest = headMarks.slice(1);
+                if (rest.length > 0) {
+                    const hf = footFinder(IAMBIC_FOOT_DICT, rest, 2, 0, rest.length);
+                    if (hf.length === 0)
+                        return { footlist: [], scansionMarks: '' };
+                    headFeet.push(...hf.map(f => f.foot));
+                }
+            }
+            else {
+                // try to find an anapest in the head
+                const anap = headMarks.indexOf('xx/');
+                if (anap === -1)
+                    return { footlist: [], scansionMarks: '' };
+                const before = footFinder(IAMBIC_FOOT_DICT, headMarks, 2, 0, anap);
+                if (before.length === 0)
+                    return { footlist: [], scansionMarks: '' };
+                headFeet.push(...before.map(f => f.foot));
+                headFeet.push('anapest');
+                const after = footFinder(IAMBIC_FOOT_DICT, headMarks, 2, anap + 3, headMarks.length);
+                if (after.length === 0)
+                    return { footlist: [], scansionMarks: '' };
+                headFeet.push(...after.map(f => f.foot));
+            }
+        }
+    }
+    // Scan tail
+    if (tailMarks.length > 0) {
+        let lastFootStr = '';
+        let tailPart = tailMarks;
+        if (tailPart.slice(-1) === 'x' && tailPart.length > 2 && tailPart.slice(-3) in IAMBIC_FOOT_DICT) {
+            lastFootStr = IAMBIC_FOOT_DICT[tailPart.slice(-3)];
+            tailPart = tailPart.slice(0, -3);
+        }
+        const tf = footFinder(IAMBIC_FOOT_DICT, tailPart, 2, 0, tailPart.length);
+        if (tf.length === 0)
+            return { footlist: [], scansionMarks: '' };
+        tailFeet.push(...tf.map(f => f.foot));
+        if (lastFootStr)
+            tailFeet.push(lastFootStr);
+    }
+    const completeList = [...headFeet, ...footlist, ...tailFeet];
+    // Promote pyrrhics as in Scandroid’s PromotePyrrhics
+    for (let i = 0; i < completeList.length; i++) {
+        if (completeList[i] === 'pyrrhic') {
+            if (i < completeList.length - 1 && completeList[i + 1] === 'spondee') {
+                // nothing
+            }
+            else {
+                completeList[i] = '(iamb)';
+            }
+        }
+    }
+    const scansion = completeList.join('|');
+    return { footlist: completeList, scansionMarks: scansion };
+}
+// ─── Anapestic scanning ──────────────────────────────────────────
+export function scandroidAnapestic(marks, numFeet) {
+    let remaining = marks;
+    if (!numFeet) {
+        const [q, r] = [Math.floor(remaining.length / 3), remaining.length % 3];
+        let need = q;
+        if (r > 0)
+            need++;
+        need = Math.max(need, altLineLenCalc(remaining));
+        numFeet = need;
+    }
+    // Handle terminal slack (promotions etc.)
+    if (remaining.slice(-2) === 'xx')
+        remaining = remaining.slice(0, -1) + '%';
+    let lastFootStr = '';
+    if (remaining && remaining.slice(-1) === 'x') {
+        let tailStart = remaining.lastIndexOf('/');
+        tailStart = remaining.lastIndexOf('/', tailStart - 1);
+        if (tailStart === -1)
+            return { footlist: [], scansionMarks: '' };
+        const tail = remaining.slice(tailStart);
+        if (tail in ANAPESTIC_FOOT_DICT) {
+            lastFootStr = ANAPESTIC_FOOT_DICT[tail];
+            remaining = remaining.slice(0, tailStart);
+        }
+        else if (tail.length > 1 && tail.slice(1) in ANAPESTIC_FOOT_DICT) {
+            lastFootStr = ANAPESTIC_FOOT_DICT[tail.slice(1)];
+            remaining = remaining.slice(0, tailStart + 1);
+        }
+        else
+            return { footlist: [], scansionMarks: '' };
+    }
+    // Promote slack runs (long sequences of unstressed)
+    const slackRun = remaining.indexOf('xxxx');
+    if (slackRun !== -1) {
+        remaining = remaining.slice(0, slackRun + 2) + '%' + remaining.slice(slackRun + 3);
+    }
+    const len = remaining.length;
+    const footlist = [];
+    if (len === numFeet * 3) {
+        const feet = footFinder(ANAPESTIC_FOOT_DICT, remaining, 3, 0, len);
+        if (feet.length === 0)
+            return { footlist: [], scansionMarks: '' };
+        footlist.push(...feet.map(f => f.foot));
+    }
+    else {
+        const needDisyls = (numFeet * 3) - len;
+        if (needDisyls > numFeet)
+            return { footlist: [], scansionMarks: '' };
+        const pattern = '2'.repeat(needDisyls) + '3'.repeat(numFeet - needDisyls);
+        const allPerms = uniquePermutations(pattern);
+        let validPattern = null;
+        for (const pat of allPerms) {
+            let okay = true;
+            let idx = 0;
+            for (const d of pat) {
+                const stride = parseInt(d);
+                idx += stride;
+                if (!'/%'.includes(remaining[idx - 1])) {
+                    okay = false;
+                    break;
+                }
+            }
+            if (okay) {
+                validPattern = pat;
+                break;
+            }
+        }
+        if (!validPattern)
+            return { footlist: [], scansionMarks: '' };
+        let pos = 0;
+        for (const d of validPattern) {
+            const stride = parseInt(d);
+            const chunk = remaining.slice(pos, pos + stride);
+            if (chunk in ANAPESTIC_FOOT_DICT) {
+                footlist.push(ANAPESTIC_FOOT_DICT[chunk]);
+                pos += stride;
+            }
+            else
+                return { footlist: [], scansionMarks: '' };
+        }
+    }
+    if (lastFootStr)
+        footlist.push(lastFootStr);
+    const scansion = footlist.join('|');
+    return { footlist, scansionMarks: scansion };
+}
+// ─── Helper: unique permutations of a string ────────────────────
+function uniquePermutations(s) {
+    if (s.length <= 1 || s.length > 9)
+        return [s];
+    const results = [];
+    function permute(prefix, rest) {
+        if (rest.length === 0)
+            results.push(prefix);
+        const seen = new Set();
+        for (let i = 0; i < rest.length; i++) {
+            if (seen.has(rest[i]))
+                continue;
+            seen.add(rest[i]);
+            permute(prefix + rest[i], rest.slice(0, i) + rest.slice(i + 1));
+        }
+    }
+    permute('', s);
+    return results;
+}
+// ─── Public API: convert our relative stress to Scandroid marks ──
+export function stressToMarks(stressArray) {
+    return stressArray.map(s => (s === 's' ? STRESS : SLACK)).join('');
+}
+export function marksToFeetString(footlist) {
+    return footlist.join(' | ');
+}
+// ─── Convenience: produce a ScansionResult from footlist ─────────
+export function scansionResultFromFootlist(footlist, meter, complexity) {
+    return {
+        meter,
+        scansion: marksToFeetString(footlist),
+        certainty: 0, // not computed
+        weightScore: 0,
+        maxPossibleWeight: 0,
+        algorithm: 'Scandroid',
+    };
+}

package/dist/scansion.d.ts

@@ -0,0 +1,37 @@
+import { ClsWord, IntonationalUnit, KeyStress, MetreName, PhonologicalScansionDetail } from './types.js';
+export declare function extractKeyStresses(ius: IntonationalUnit[], words: ClsWord[]): KeyStress[];
+export declare function scoreMeters(keyStresses: KeyStress[], words: ClsWord[], ius?: IntonationalUnit[], force?: MetreName): PhonologicalScansionDetail;
+/** Per-line ictus profile parsed from a scansion string ("ns|wx|ns|ws|ws"). */
+export interface IctusProfile {
+    syllables: number;
+    ictuses: number;
+    intervals: number[];
+    anacrusis: number;
+}
+export declare function ictusProfile(scansion: string): IctusProfile;
+/**
+ * Stanza-level rhythm classification.  Fires only when:
+ *   (a) syllable counts VARY across the stanza (range ≥ 2) — a steady-count
+ *       stanza is accentual-syllabic territory and is left to the classical
+ *       machinery (this is what keeps loose iambics like Frost untouched); and
+ *   (b) no classical meter dominates confidently (≥60% of lines under one
+ *       meter at mean certainty ≥70).
+ * Then: alternating 4·3 ictuses → ballad; constant ictus count + interval
+ * family → dolnik / taktovik / accentual.  Single lines (or 2-line stanzas)
+ * get only the per-line free-verse refinement below.
+ */
+export declare function applyRhythmLayer(details: PhonologicalScansionDetail[]): void;
+/**
+ * Stanza-level consensus (McAleese A2.1 §5b, "where there is a tie, use
+ * surrounding patterns").  Each line keeps its own standalone scansion/meter;
+ * but when a line's top meter merely *edges out* the stanza's dominant meter (a
+ * near-tie, within `tie` of its own best fit), we annotate it with the dominant
+ * meter via `consensusMeter` — making the divergence EXPLICIT rather than
+ * silently homogenising it.  Confident lines (whose own meter clearly beats the
+ * dominant) are left untouched, so genuine metrical variation stays visible.
+ *
+ * Mutates the passed details in place.  No-op for <2 lines or a stanza with no
+ * unique dominant meter.
+ */
+export declare function applyStanzaConsensus(details: PhonologicalScansionDetail[], tie?: number): void;
+//# sourceMappingURL=scansion.d.ts.map

package/dist/scansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scansion.d.ts","sourceRoot":"","sources":["../src/scansion.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,OAAO,EACP,gBAAgB,EAGhB,SAAS,EACT,SAAS,EAET,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAgLpB,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAwCzF;AA2ZD,wBAAgB,WAAW,CACzB,WAAW,EAAE,SAAS,EAAE,EACxB,KAAK,EAAE,OAAO,EAAE,EAChB,GAAG,CAAC,EAAE,gBAAgB,EAAE,EACxB,KAAK,CAAC,EAAE,SAAS,GAChB,0BAA0B,CA4I5B;AAmBD,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CA8B3D;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,EAAE,GAAG,IAAI,CAmF5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,0BAA0B,EAAE,EACrC,GAAG,GAAE,MAAc,GAClB,IAAI,CA6DN"}