calliope-ts 0.0.1

package/src/index.ts

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as readline from 'readline';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { parseDocument } from './parser.js';
+import {
+  assignLexicalStress,
+  applyCompoundStress,
+  applyNuclearStress,
+  assignRelativeStresses,
+} from './stress.js';
+import {
+  buildPhonologicalHierarchy,
+  renderHierarchy,
+  renderKeyStresses,
+  flattenDisplayEntries,
+} from './phonological.js';
+import { extractKeyStresses, scoreMeters, applyStanzaConsensus, applyRhythmLayer } from './scansion.js';
+import { applyRhymeAndForm } from './rhyme.js';
+import {
+  scandroidCorralWeird,
+  scandroidMaximizeNormal,
+  stressToMarks,
+} from './scandroid.js';
+import {
+  renderUnifiedDisplay,
+  renderFullLegend,
+  renderReadingView,
+  type ReadingStanza,
+} from './display.js';
+import type {
+  ClsSentence,
+  MetreName,
+  IntonationalUnit,
+  StressLevel,
+  ScansionResult,
+  LineResult,
+  PhonologicalScansionDetail,
+  SyllableDisplayEntry,
+  FootDisplayEntry,
+  FormattedDisplay,
+  DisplayOptions,
+} from './types.js';
+
+/**
+ * Scan one VERSE LINE (which may parse into several grammatical sentences).
+ *
+ * The line — not the sentence — is the metrical domain (McAleese; Kiparsky's
+ * "phonological phrasing determines the location of caesurae in verse").  A
+ * line like "You'll slurp potato soup. No straws! Suck gauze." is ONE iambic
+ * pentameter with internal intonational breaks, not three fragments each
+ * carrying its own meter.  So the linguistic passes (lexical stress, phrasal
+ * hierarchy, compound/nuclear/relative stress) run per sentence — those rules
+ * are intra-sentence by nature — but the metrical fit runs once over the
+ * line's full concatenated syllable stream, with each sentence's IUs preserved
+ * as IU boundaries (→ hard caesurae) inside the line.
+ */
+function processLine(sents: ClsSentence[]): LineResult | null {
+  if (sents.length === 0) return null;
+
+  const iusPerSent: IntonationalUnit[][] = [];
+  for (const sent of sents) {
+    assignLexicalStress(sent.words);
+    const sentIus = buildPhonologicalHierarchy(sent);
+    applyCompoundStress(sentIus);
+    applyNuclearStress(sentIus);
+    assignRelativeStresses(sent.words, sentIus);
+    iusPerSent.push(sentIus);
+  }
+
+  // Merge the sentences' streams into the line-level scansion domain.
+  const words = sents.flatMap(s => s.words);
+  const ius = iusPerSent.flat();
+  let merged: ClsSentence;
+  if (sents.length === 1) {
+    merged = sents[0];
+  } else {
+    // Re-index sequentially so per-sentence 1-based indices don't collide in
+    // any downstream order-by-index logic.  (All hierarchy/dependency passes
+    // above are already complete and reference words by object identity.)
+    words.forEach((w, i) => { w.index = i + 1; });
+    merged = {
+      index: sents[0].index,
+      nodes: null,
+      dependencies: sents.flatMap(s => s.dependencies),
+      words,
+      xml: '',
+    };
+  }
+
+  const keyStresses = extractKeyStresses(ius, words);
+
+  // Full phonological scansion over the whole line.
+  const phonoDetail = scoreMeters(keyStresses, words, ius);
+  phonoDetail.all = renderHierarchy(ius, words);
+  phonoDetail.keyStresses = renderKeyStresses(ius, words, keyStresses);
+
+  // Scandroid – use the actual foot count from the phonological detection
+  const stressPattern: StressLevel[] = words.flatMap((w) =>
+    w.syllables.map((s) => s.relativeStress ?? 'w')
+  );
+  const marks = stressToMarks(stressPattern);
+  const actualFeet = phonoDetail.footCount > 0 ? phonoDetail.footCount : 5; // fallback only if unknown
+  const corral = scandroidCorralWeird(marks, actualFeet);
+  const max = scandroidMaximizeNormal(marks, actualFeet);
+
+  const corralResult: ScansionResult | undefined = corral.footlist.length
+    ? {
+        meter: 'iambic',
+        scansion: corral.footlist.map(f => f.replace(/[()]/g, '')).join(' | '),
+        certainty: 0,
+        weightScore: 0,
+        maxPossibleWeight: 0,
+        algorithm: 'Scandroid Corral the Weird',
+      }
+    : undefined;
+  const maxResult: ScansionResult | undefined = max.footlist.length
+    ? {
+        meter: 'iambic',
+        scansion: max.footlist.map(f => f.replace(/[()]/g, '')).join(' | '),
+        certainty: 0,
+        weightScore: 0,
+        maxPossibleWeight: 0,
+        algorithm: 'Scandroid Maximise the Normal',
+      }
+    : undefined;
+
+  return {
+    sentence: merged,
+    phonologicalHierarchy: ius,
+    keyStresses,
+    phonologicalScansion: phonoDetail,
+    scandroidCorral: corralResult,
+    scandroidMaximise: maxResult,
+  };
+}
+
+/**
+ * Analyse a multi‑line text with stanza awareness.
+ * Returns a list of stanza arrays, each containing the per‑line results.
+ */
+
+/**
+ * Continuity rename (maintainer directive 2026-06-14): a line whose standalone
+ * meter merely edges out the stanza/poem-dominant meter (consensusMeter set by
+ * applyStanzaConsensus) ADOPTS the dominant meter as its base reading — the
+ * scansion, foot count, and certainty are re-fitted under that meter — and the
+ * numerically-best standalone meter is kept as a concise note
+ * (`standaloneMeter`).  Metrical continuity outranks a hair of fit score.
+ */
+function applyContinuityRename(results: LineResult[]): void {
+  // A stanza-level rhythm verdict (set on at least half the lines) means the
+  // group reads as accentual/dolnik/taktovik — classical continuity renaming
+  // does not apply there.
+  const noted = results.filter(r => r.phonologicalScansion.rhythmNote).length;
+  if (results.length > 0 && noted >= results.length / 2) return;
+  for (const res of results) {
+    const d = res.phonologicalScansion;
+    if (!d.consensusMeter) continue;
+    const family = d.consensusMeter.split(' ')[0] as MetreName;
+    const forced = scoreMeters(res.keyStresses, res.sentence.words, res.phonologicalHierarchy, family);
+    if (!forced || forced.meterName === 'free verse' || forced.footCount <= 0) continue;
+    d.standaloneMeter = d.meter;
+    d.meter = forced.meter;
+    d.meterName = forced.meterName;
+    d.footCount = forced.footCount;
+    d.scansion = forced.scansion;
+    d.certainty = forced.certainty;
+    d.summary = forced.summary;
+    d.consensusMeter = undefined;
+  }
+}
+
+export function analyzeStanzas(text: string, useScandroid = true): LineResult[][] {
+  const stanzas = text.split(/\n\s*\n/);
+  const results: LineResult[][] = [];
+  for (const stanza of stanzas) {
+    const lines = stanza.split('\n').filter(l => l.trim() !== '');
+    const stanzaResults: LineResult[] = [];
+    for (const line of lines) {
+      const doc = parseDocument(line);
+      const res = processLine(doc.sentences);
+      if (res) stanzaResults.push(res);
+    }
+    // Resolve near-tie lines toward the stanza's dominant meter (explicit, non-
+    // destructive: annotates phonologicalScansion.consensusMeter), then classify
+    // non-classical rhythm (dolnik/taktovik/accentual → rhythmNote; ballad is a
+    // FORM verdict and belongs to the rhyme-aware form layer).
+    applyStanzaConsensus(stanzaResults.map(r => r.phonologicalScansion));
+    // Classical-vs-accentual is decided FIRST (rhythm layer); continuity
+    // renaming applies only where no stanza-level accentual/dolnik verdict
+    // fired — otherwise the rename would snowball weak scattered classical
+    // readings into false dominance (Wyatt lost its "4-beat accentual").
+    applyRhythmLayer(stanzaResults.map(r => r.phonologicalScansion));
+    applyContinuityRename(stanzaResults);
+    results.push(stanzaResults);
+  }
+  // Poem-scale continuity: lines left un-renamed (their own stanza had no
+  // unique dominant) get a second chance against the poem-wide dominant.
+  if (results.length > 1) {
+    const all = results.flat();
+    applyStanzaConsensus(all.map(r => r.phonologicalScansion));
+    applyContinuityRename(all);
+    for (const st of results) applyRhythmLayer(st.map(r => r.phonologicalScansion));
+  }
+  // Rhyme scheme + poetic-form identification spans stanzas (sonnets, terza
+  // rima); annotation-only (rhyme/formNote on each line's detail).
+  applyRhymeAndForm(results);
+  return results;
+}
+
+/**
+ * Convenience wrapper: analyse a multi‑line text, ignore stanza breaks,
+ * return a flat list of LineResult for each line.
+ */
+export function analyzeText(text: string, useScandroid = true): LineResult[] {
+  const stanzaResults = analyzeStanzas(text, useScandroid);
+  return stanzaResults.flat();
+}
+
+/**
+ * Analyse a document for the reading view: like analyzeStanzas, but retains
+ * each original input line alongside its (1+) parsed sentence results so the
+ * stress gradient can be projected back over the verbatim text.
+ */
+export function analyzeReadingDocument(text: string): ReadingStanza[] {
+  const stanzas = text.split(/\n\s*\n/);
+  const out: ReadingStanza[] = [];
+  for (const stanza of stanzas) {
+    const rawLines = stanza.split('\n').filter(l => l.trim() !== '');
+    if (rawLines.length === 0) continue;
+    const lines = rawLines.map(raw => {
+      const doc = parseDocument(raw);
+      const res = processLine(doc.sentences);
+      return { raw, results: res ? [res] : [] };
+    });
+    applyStanzaConsensus(lines.flatMap(l => l.results.map(r => r.phonologicalScansion)));
+    applyRhythmLayer(lines.flatMap(l => l.results.map(r => r.phonologicalScansion)));
+    applyContinuityRename(lines.flatMap(l => l.results));
+    out.push({ lines });
+  }
+  if (out.length > 1) {
+    const all = out.flatMap(st => st.lines.flatMap(l => l.results));
+    applyStanzaConsensus(all.map(r => r.phonologicalScansion));
+    applyContinuityRename(all);
+    for (const st of out) applyRhythmLayer(st.lines.flatMap(l => l.results.map(r => r.phonologicalScansion)));
+  }
+  applyRhymeAndForm(out.map(st => st.lines.flatMap(l => l.results)));
+  return out;
+}
+
+// ─── CLI HELPERS ────────────────────────────────────────────────
+
+function showResults(text: string): void {
+  // Use the reading-document analysis so each LineResult keeps its verbatim input
+  // line (for the tail Reading Projection) and the stanza-consensus annotation.
+  const stanzas = analyzeReadingDocument(text);
+
+  for (let s = 0; s < stanzas.length; s++) {
+    if (stanzas.length > 1) {
+      console.log('\n' + chalk.bold('═══ Stanza ' + (s + 1) + ' ═══'));
+    }
+    for (const ln of stanzas[s].lines) {
+      for (const res of ln.results) {
+        console.log(renderUnifiedDisplay(res, ln.raw));
+      }
+    }
+  }
+}
+
+function showReadingView(text: string): void {
+  const stanzas = analyzeReadingDocument(text);
+  console.log(renderReadingView(stanzas));
+}
+
+// ─── MULTI-LINE INPUT (paste-friendly) ──────────────────────────
+// Goal: the user pastes a whole poem (stanza breaks and all) and presses Enter
+// ONCE to scan it; Esc returns to the menu.  The trick is distinguishing a blank
+// line that is a *stanza break* (part of the pasted burst) from a blank line that
+// means *"I'm done"* (a deliberate, later keystroke).  A paste streams in as one
+// rapid burst (sub-ms between lines); a human Enter comes after a real pause.  So
+// once a burst has been seen, the next Enter that arrives after an idle gap
+// submits — flushing the current line whether or not the paste ended in a newline.
+// The pure decision below is unit-tested (a TTY can't be driven from CI).
+
+export const ML_IDLE_MS = 120;
+
+export type MLEvent =
+  | { kind: 'char'; str: string; gap: number }
+  | { kind: 'return'; gap: number }
+  | { kind: 'backspace'; gap: number }
+  | { kind: 'escape' }
+  | { kind: 'eof' };
+
+export interface MLState { lines: string[]; cur: string; sawBurst: boolean; }
+export type MLResult = 'continue' | 'submit' | 'cancel';
+
+export function newMLState(): MLState { return { lines: [], cur: '', sawBurst: false }; }
+
+function mlHasContent(st: MLState): boolean {
+  return st.cur.trim() !== '' || st.lines.some(l => l.trim() !== '');
+}
+
+/**
+ * Fold one input event into the multi-line buffer, returning whether to keep
+ * reading ('continue'), scan the buffer ('submit'), or abandon it ('cancel').
+ *  • A burst-speed Enter (gap < ML_IDLE_MS) is always a line break — so pasted
+ *    stanza-break blank lines are preserved.
+ *  • After a burst, the first idle Enter submits (flushing any pending line).
+ *  • With no burst (slow hand-typing), a non-empty line + Enter is a line break and
+ *    a blank line submits — the conventional "blank line to finish".
+ *  • Esc cancels (→ menu); Ctrl-D submits whatever is there.
+ */
+export function feedMultilineEvent(st: MLState, ev: MLEvent): MLResult {
+  switch (ev.kind) {
+    case 'escape':
+      return 'cancel';
+    case 'eof':
+      if (st.cur.length) { st.lines.push(st.cur); st.cur = ''; }
+      return mlHasContent(st) ? 'submit' : 'cancel';
+    case 'backspace':
+      if (st.cur.length) st.cur = st.cur.slice(0, -1);
+      return 'continue';
+    case 'char': {
+      if (ev.gap < ML_IDLE_MS) st.sawBurst = true;
+      // A pasted chunk may arrive with embedded newlines in one event.
+      const parts = ev.str.split(/\r\n|\r|\n/);
+      for (let i = 0; i < parts.length; i++) {
+        if (i > 0) { st.lines.push(st.cur); st.cur = ''; }
+        st.cur += parts[i];
+      }
+      return 'continue';
+    }
+    case 'return': {
+      if (ev.gap < ML_IDLE_MS) {           // burst-speed → a line break (keep blanks)
+        st.sawBurst = true;
+        st.lines.push(st.cur); st.cur = '';
+        return 'continue';
+      }
+      // Deliberate (idle) Enter.
+      if (st.sawBurst || st.cur.trim() === '') {
+        if (st.cur.length) { st.lines.push(st.cur); st.cur = ''; }
+        return mlHasContent(st) ? 'submit' : 'continue';
+      }
+      // Slow hand-typing of a fresh non-empty line → just a line break.
+      st.lines.push(st.cur); st.cur = '';
+      return 'continue';
+    }
+  }
+}
+
+/** Strip trailing blank lines (e.g. a paste's trailing newline) from a buffer. */
+function trimTrailingBlanks(lines: string[]): string[] {
+  const out = lines.slice();
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+  return out;
+}
+
+/**
+ * Read a pasteable multi-line block from the TTY in raw mode (so Esc and the
+ * paste-burst timing are observable).  Resolves to the lines, or null if the user
+ * pressed Esc (→ return to menu).
+ */
+async function readPastableBlock(): Promise<string[] | null> {
+  const stdin = process.stdin;
+  return new Promise<string[] | null>((resolve) => {
+    const st = newMLState();
+    let lastTime = Date.now();
+    readline.emitKeypressEvents(stdin);
+    const wasRaw = !!(stdin as any).isRaw;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+
+    const onKey = (str: string | undefined, key: any) => {
+      const now = Date.now();
+      const gap = now - lastTime;
+      lastTime = now;
+      key = key || {};
+      if (key.ctrl && key.name === 'c') {                  // Ctrl-C → quit
+        cleanup(); process.stdout.write('\n'); process.exit(0);
+      }
+      let ev: MLEvent | null = null;
+      if (key.name === 'escape') ev = { kind: 'escape' };
+      else if (key.ctrl && key.name === 'd') ev = { kind: 'eof' };
+      else if (key.name === 'return' || key.name === 'enter') ev = { kind: 'return', gap };
+      else if (key.name === 'backspace') ev = { kind: 'backspace', gap };
+      else if (str && !key.ctrl && !key.meta) ev = { kind: 'char', str, gap };
+      if (!ev) return;                                     // ignore arrows / fn keys
+      // Echo (raw mode does not echo for us).
+      if (ev.kind === 'char') process.stdout.write(str!);
+      else if (ev.kind === 'return') process.stdout.write('\n');
+      else if (ev.kind === 'backspace' && st.cur.length) process.stdout.write('\b \b');
+
+      const result = feedMultilineEvent(st, ev);
+      if (result === 'submit') { cleanup(); process.stdout.write('\n'); resolve(st.lines); }
+      else if (result === 'cancel') { cleanup(); process.stdout.write('\n'); resolve(null); }
+    };
+
+    function cleanup() {
+      stdin.removeListener('keypress', onKey);
+      if (stdin.isTTY) stdin.setRawMode(wasRaw);
+      stdin.pause();
+    }
+    stdin.on('keypress', onKey);
+  });
+}
+
+async function replMode(): Promise<void> {
+  const prompts = (await import('prompts')).default;
+
+  console.log('');
+  console.log(chalk.bold('     CALLIOPE_TS — Phonological Poetry Scansion (CLI)  '));
+  console.log(chalk.dim('• Multi-Step Syntactic, Phonological, & Prosodic Analysis •'));
+  console.log('');
+
+  let running = true;
+  while (running) {
+    const response = await prompts({
+      type: 'select',
+      name: 'action',
+      message: 'Choose an action:',
+      choices: [
+        { title: 'Parse & Scan (multi-line reading view)', value: 'reading-multi' },
+        { title: 'Single Line Analysis (detailed view)', value: 'scan' },
+        { title: 'Line-by-Line Analysis (detailed view)', value: 'multiline' },
+        { title: 'Parse & Scan from File (reading view)', value: 'reading-file' },
+        { title: 'Analyze from File (detailed view)', value: 'file' },
+        { title: 'Display Legend', value: 'legend' },
+        { title: 'Exit', value: 'exit' },
+      ],
+    });
+
+    if (!response.action || response.action === 'exit') {
+      running = false;
+      console.log(chalk.dim('\nGoodbye.\n'));
+      break;
+    }
+
+    if (response.action === 'legend') {
+      console.log('\n' + renderFullLegend() + '\n');
+      continue;
+    }
+
+    if (response.action === 'scan') {
+      const lineResponse = await prompts({
+        type: 'text',
+        name: 'line',
+        message: 'Enter a line of verse:',
+      });
+      if (lineResponse.line && lineResponse.line.trim()) {
+        try {
+          showResults(lineResponse.line.trim());
+        } catch (err) {
+          console.error(chalk.red('Error during scansion:'), err);
+        }
+      }
+      continue;
+    }
+
+    if (response.action === 'file' || response.action === 'reading-file') {
+      const render = response.action === 'reading-file' ? showReadingView : showResults;
+      const fileResponse = await prompts({
+        type: 'text',
+        name: 'path',
+        message: 'Enter file path:',
+      });
+      if (fileResponse.path && fileResponse.path.trim()) {
+        try {
+          const text = fs.readFileSync(fileResponse.path.trim(), 'utf-8');
+          render(text);
+        } catch (err) {
+          console.error(chalk.red('Error reading file:'), err);
+        }
+      }
+      continue;
+    }
+
+    if (response.action === 'multiline' || response.action === 'reading-multi') {
+      const render = response.action === 'reading-multi' ? showReadingView : showResults;
+      console.log(chalk.dim('Paste your poem and press Enter to scan it.   (Esc to cancel)'));
+      const block = await readPastableBlock();
+      if (block === null) continue;          // Esc → back to the menu
+      const lines = trimTrailingBlanks(block);
+      if (lines.length > 0) {
+        try {
+          render(lines.join('\n'));
+        } catch (err) {
+          console.error(chalk.red('Error during scansion:'), err);
+        }
+      }
+      continue;
+    }
+  }
+}
+
+// ─── CLI ENTRY POINT ─────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  let rawArgs = process.argv.slice(2);
+  // --reading / -r : emit the compact reading view (poem in original formatting,
+  // syllables stress-coloured, + per-line stress maps) instead of the full dump.
+  const reading = rawArgs.includes('--reading') || rawArgs.includes('-r');
+  rawArgs = rawArgs.filter(a => a !== '--reading' && a !== '-r');
+  const show = reading ? showReadingView : showResults;
+
+  // Explicit arguments take precedence over piped stdin — otherwise running
+  // `calliope_ts "some line"` from a script/CI (where stdin is a non-TTY but
+  // empty) silently analysed the empty pipe and ignored the argument.
+  if (rawArgs.length > 0) {
+    // Check if first arg is a file
+    const firstArg = rawArgs[0];
+    if (fs.existsSync(firstArg) && fs.statSync(firstArg).isFile()) {
+      const text = fs.readFileSync(firstArg, 'utf-8');
+      show(text);
+      return;
+    }
+    // Otherwise treat as text input
+    const text = rawArgs.join(' ');
+    show(text);
+    return;
+  }
+
+  // No arguments: piped input (file redirect / heredoc) is the document.
+  if (!process.stdin.isTTY) {
+    const text = fs.readFileSync(0, 'utf-8');
+    show(text);
+    return;
+  }
+
+  // No arguments: launch interactive REPL
+  await replMode();
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch(err => {
+    console.error(chalk.red('Fatal error:'), err);
+    process.exit(1);
+  });
+}