calliope-ts 0.0.2 → 0.0.3

package/src/index.ts

@@ -3,20 +3,27 @@ import * as fs from 'fs';
 import * as readline from 'readline';
 import chalk from 'chalk';
 import { fileURLToPath } from 'url';
-import { parseDocument } from './parser.js';
+import { parseDocument, isPunctuation } from './parser.js';
+import { ProsodyEngine } from './engine.js';
+import { calliopeEngine } from './calliope/engine.js';
+import { clioEngine } from './clio/engine.js';
+// The FROZEN Clio pipeline + renderers (its own copy of the whole computational
+// tree).  When Clio is active the CLI runs entirely through these, so live changes
+// to the regular (Calliope) pipeline — scorer included — cannot affect Clio.
 import {
-  assignLexicalStress,
-  applyCompoundStress,
-  applyNuclearStress,
-  assignRelativeStresses,
-} from './stress.js';
+  analyzeReadingDocumentClio,
+  renderUnifiedDisplay as clioRenderUnifiedDisplay,
+  renderReadingView as clioRenderReadingView,
+  renderFullLegend as clioRenderFullLegend,
+  parseDocument as clioParseDocument,
+  isPunctuation as clioIsPunctuation,
+} from './clio/pipeline.js';
 import {
-  buildPhonologicalHierarchy,
   renderHierarchy,
   renderKeyStresses,
   flattenDisplayEntries,
 } from './phonological.js';
-import { extractKeyStresses, scoreMeters, applyStanzaConsensus, applyRhythmLayer } from './scansion.js';
+import { extractKeyStresses, scoreMeters, applyStanzaConsensus, applyRhythmLayer, applyMetricalityLayer } from './scansion.js';
 import { applyRhymeAndForm } from './rhyme.js';
 import {
   scandroidCorralWeird,
@@ -31,6 +38,7 @@ import {
 } from './display.js';
 import type {
   ClsSentence,
+  ClsWord,
   MetreName,
   IntonationalUnit,
   StressLevel,
@@ -43,6 +51,54 @@ import type {
   DisplayOptions,
 } from './types.js';
 
+// The active prosody engine for this process: Calliope (faithful, default) or
+// Clio (the frozen legacy / alternative parse), chosen by `--clio` or the REPL
+// menu.  The exported analysis functions default their `engine` parameter to
+// this, so library callers (tests, trials, benchmark) transparently use the
+// active engine without signature churn.
+let activeEngine: ProsodyEngine = calliopeEngine;
+
+/**
+ * Stanza-level discourse givenness (Wagner Ch.7, the plan's Gap 13) — CAREFUL and
+ * cross-line only.  A CONTENT word repeated from an EARLIER line of the same stanza
+ * is discourse-given, so it may be subordinated relative to a new-information sister
+ * (the relativiser reads `discourseGiven`).  Constraints that protect single-line
+ * scanning and thematically-focused words:
+ *   • the first line is never marked (no prior context);
+ *   • a lemma repeated WITHIN a single line is FOCUSED, not given → never marked
+ *     (Eliot's "Nothing … nothing", a refrain);
+ *   • only the 2nd-and-later occurrence (across lines) is marked, never the first;
+ *   • single-line input has no previous line, so nothing is marked — the standout
+ *     isolated-line feature is untouched.
+ * Mutates `discourseGiven` on the words; must run BEFORE the per-line relativisation.
+ */
+function markStanzaGivenness(docPerLine: ClsSentence[][]): void {
+  if (docPerLine.length < 2) return;                       // single line → no givenness
+  const key = (w: ClsWord) => w.word.toLowerCase().replace(/['’]/g, '');
+  // Lemmas that appear ≥2× within ANY one line are focal (refrain/emphasis) — exempt.
+  const focal = new Set<string>();
+  for (const sents of docPerLine) {
+    const counts = new Map<string, number>();
+    for (const sent of sents) for (const w of sent.words) {
+      if (!w.isContent) continue;
+      const k = key(w);
+      counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    for (const [k, n] of counts) if (n >= 2) focal.add(k);
+  }
+  const seen = new Set<string>();                          // content lemmas in PRIOR lines
+  for (const sents of docPerLine) {
+    const thisLine = new Set<string>();
+    for (const sent of sents) for (const w of sent.words) {
+      if (!w.isContent) continue;
+      const k = key(w);
+      if (seen.has(k) && !focal.has(k)) w.discourseGiven = true;
+      thisLine.add(k);
+    }
+    for (const k of thisLine) seen.add(k);
+  }
+}
+
 /**
  * Scan one VERSE LINE (which may parse into several grammatical sentences).
  *
@@ -56,16 +112,15 @@ import type {
  * 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 {
+function processLine(sents: ClsSentence[], engine: ProsodyEngine = activeEngine): 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);
+    // The selected engine runs the per-sentence linguistic passes (lexical →
+    // hierarchy → compound/nuclear → phrase → relative stress) and returns the
+    // prosodic hierarchy.  Calliope (default) and Clio differ only here.
+    const sentIus = engine.analyzeSentence(sent);
     iusPerSent.push(sentIus);
   }
 
@@ -172,15 +227,19 @@ function applyContinuityRename(results: LineResult[]): void {
   }
 }
 
-export function analyzeStanzas(text: string, useScandroid = true): LineResult[][] {
+export function analyzeStanzas(text: string, useScandroid = true, engine: ProsodyEngine = activeEngine): 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);
+    // Parse every line first, then mark cross-line discourse givenness BEFORE the
+    // per-line stress passes (relativisation reads `discourseGiven`).  Only the
+    // default (Calliope) relativiser consults it; Clio ignores the flag.
+    const docs = lines.map(line => parseDocument(line));
+    markStanzaGivenness(docs.map(d => d.sentences));
+    for (const doc of docs) {
+      const res = processLine(doc.sentences, engine);
       if (res) stanzaResults.push(res);
     }
     // Resolve near-tie lines toward the stanza's dominant meter (explicit, non-
@@ -204,6 +263,9 @@ export function analyzeStanzas(text: string, useScandroid = true): LineResult[][
     applyContinuityRename(all);
     for (const st of results) applyRhythmLayer(st.map(r => r.phonologicalScansion));
   }
+  // Prose-likeness hedge (Option 0): advisory, runs after the rhythm layer so it
+  // can defer to any accentual/dolnik verdict; annotation-only (metricalityNote).
+  applyMetricalityLayer(results.flatMap(st => 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);
@@ -214,8 +276,8 @@ export function analyzeStanzas(text: string, useScandroid = true): LineResult[][
  * 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);
+export function analyzeText(text: string, useScandroid = true, engine: ProsodyEngine = activeEngine): LineResult[] {
+  const stanzaResults = analyzeStanzas(text, useScandroid, engine);
   return stanzaResults.flat();
 }
 
@@ -224,15 +286,16 @@ export function analyzeText(text: string, useScandroid = true): LineResult[] {
  * 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[] {
+export function analyzeReadingDocument(text: string, engine: ProsodyEngine = activeEngine): 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);
+    const rawDocs = rawLines.map(raw => ({ raw, doc: parseDocument(raw) }));
+    markStanzaGivenness(rawDocs.map(rd => rd.doc.sentences));
+    const lines = rawDocs.map(({ raw, doc }) => {
+      const res = processLine(doc.sentences, engine);
       return { raw, results: res ? [res] : [] };
     });
     applyStanzaConsensus(lines.flatMap(l => l.results.map(r => r.phonologicalScansion)));
@@ -246,6 +309,7 @@ export function analyzeReadingDocument(text: string): ReadingStanza[] {
     applyContinuityRename(all);
     for (const st of out) applyRhythmLayer(st.lines.flatMap(l => l.results.map(r => r.phonologicalScansion)));
   }
+  applyMetricalityLayer(out.flatMap(st => st.lines.flatMap(l => l.results.map(r => r.phonologicalScansion))));
   applyRhymeAndForm(out.map(st => st.lines.flatMap(l => l.results)));
   return out;
 }
@@ -255,7 +319,10 @@ export function analyzeReadingDocument(text: string): ReadingStanza[] {
 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);
+  // Clio routes through its own frozen pipeline + renderer.
+  const isClio = activeEngine.name === 'clio';
+  const stanzas = (isClio ? analyzeReadingDocumentClio : analyzeReadingDocument)(text);
+  const render = isClio ? clioRenderUnifiedDisplay : renderUnifiedDisplay;
 
   for (let s = 0; s < stanzas.length; s++) {
     if (stanzas.length > 1) {
@@ -263,15 +330,16 @@ function showResults(text: string): void {
     }
     for (const ln of stanzas[s].lines) {
       for (const res of ln.results) {
-        console.log(renderUnifiedDisplay(res, ln.raw));
+        console.log(render(res, ln.raw));
       }
     }
   }
 }
 
 function showReadingView(text: string): void {
-  const stanzas = analyzeReadingDocument(text);
-  console.log(renderReadingView(stanzas));
+  const isClio = activeEngine.name === 'clio';
+  const stanzas = (isClio ? analyzeReadingDocumentClio : analyzeReadingDocument)(text);
+  console.log((isClio ? clioRenderReadingView : renderReadingView)(stanzas));
 }
 
 // ─── MULTI-LINE INPUT (paste-friendly) ──────────────────────────
@@ -426,6 +494,7 @@ async function replMode(): Promise<void> {
         { 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: 'Ask Clio instead (alternative parse) — toggle engine', value: 'engine' },
         { title: 'Display Legend', value: 'legend' },
         { title: 'Exit', value: 'exit' },
       ],
@@ -437,8 +506,21 @@ async function replMode(): Promise<void> {
       break;
     }
 
+    if (response.action === 'engine') {
+      // Toggle between Calliope (faithful, default) and Clio (the legacy /
+      // alternative parse).  Clio is Calliope's historian sister — sometimes
+      // on point, but not the primary poetic voice.
+      activeEngine = activeEngine.name === 'calliope' ? clioEngine : calliopeEngine;
+      const label = activeEngine.name === 'clio'
+        ? 'Clio — legacy / alternative parse'
+        : 'Calliope — faithful, default';
+      console.log(chalk.dim(`\n  Active engine: ${chalk.bold(label)}\n`));
+      continue;
+    }
+
     if (response.action === 'legend') {
-      console.log('\n' + renderFullLegend() + '\n');
+      const legend = activeEngine.name === 'clio' ? clioRenderFullLegend : renderFullLegend;
+      console.log('\n' + legend() + '\n');
       continue;
     }
 
@@ -494,6 +576,53 @@ async function replMode(): Promise<void> {
   }
 }
 
+// ─── PARSE-AUDIT DIAGNOSTIC ──────────────────────────────────────
+//
+// `--debug-parse` dumps, per word, the full chain the scansion rests on: POS
+// tag, dependency role + governor, prosodic membership (IU.PP.CP), and the
+// lexical / phrase / relative stress.  This is the audit instrument for the
+// POS + dependency + correction layers — read alongside trials/parse_audit.mjs,
+// which tabulates tag/dependency distributions and anomalies over a corpus.
+function debugParse(text: string): void {
+  // Clio audits through its own frozen parser; Calliope through the live one.
+  const isClio = activeEngine.name === 'clio';
+  const parse = isClio ? clioParseDocument : parseDocument;
+  const isPunct = isClio ? clioIsPunctuation : isPunctuation;
+  const lines = text.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    const doc = parse(line);
+    console.log('\n' + chalk.bold.cyan('› ' + line));
+    for (const sent of doc.sentences) {
+      // Route the audit dump through the active engine so --debug-parse reflects
+      // whichever engine (Calliope / Clio) is selected.
+      const ius = activeEngine.analyzeSentence(sent);
+      const loc = new Map<ClsWord, string>();
+      ius.forEach((iu, ii) =>
+        iu.phonologicalPhrases.forEach((pp, pi) =>
+          pp.cliticGroups.forEach((cg, ci) =>
+            cg.tokens.forEach(t => loc.set(t, `${ii + 1}.${pi + 1}.${ci + 1}`)))));
+      console.log(chalk.dim('  word         POS    C/F  dep            ←governor     IU.PP.CP  lex   phr  rel   canon      name'));
+      for (const w of sent.words) {
+        if (isPunctuation(w.lexicalClass)) continue;
+        const d = w.dependency;
+        const gov = d && d.governor ? d.governor.word : '—';
+        const cf = w.isContent ? 'C' : 'f';
+        const lex = w.syllables.map(s => (s.lexicalStress ?? s.stress)).join('');
+        const rel = w.syllables.map(s => s.relativeStress).join('');
+        // Calliope substrate (Stage 1): normalised relation + person/place flags.
+        const canon = w.canonicalRel ?? '-';
+        const name = w.isPersonName && w.isPlaceName ? 'P+C'
+          : w.isPersonName ? 'person' : w.isPlaceName ? 'place' : '';
+        console.log('  ' + w.word.padEnd(12) + w.lexicalClass.padEnd(6) + ' ' + cf + '   '
+          + (d ? d.dependentType : '?').padEnd(14) + ' ' + String(gov).padEnd(13) + ' '
+          + (loc.get(w) ?? '-').padEnd(9) + ' ' + lex.padEnd(5) + ' '
+          + String(w.phraseStress).padEnd(4) + ' ' + rel.padEnd(5) + ' '
+          + canon.padEnd(10) + ' ' + name);
+      }
+    }
+  }
+}
+
 // ─── CLI ENTRY POINT ─────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -502,7 +631,14 @@ async function main(): Promise<void> {
   // 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;
+  // --debug-parse : dump the per-word POS / dependency / prosody / stress chain.
+  const debugParseMode = rawArgs.includes('--debug-parse');
+  rawArgs = rawArgs.filter(a => a !== '--debug-parse');
+  // --clio : run the frozen legacy / alternative parse engine instead of the
+  // default faithful Calliope engine.
+  if (rawArgs.includes('--clio')) activeEngine = clioEngine;
+  rawArgs = rawArgs.filter(a => a !== '--clio');
+  const show = debugParseMode ? debugParse : 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
@@ -532,15 +668,23 @@ async function main(): Promise<void> {
   await replMode();
 }
 
+// Is this module being run directly as the CLI, or imported as a library?
+// A plain `process.argv[1] === fileURLToPath(import.meta.url)` check breaks under
+// `npm install -g`: npm invokes us through a symlink in its bin directory, so
+// process.argv[1] is that symlink's path, not the real dist/index.js. The two
+// never match, `main()` never fires, and the command exits silently. Resolve
+// symlinks on BOTH sides before comparing so the global command actually runs.
 let isMain = false;
 if (process.argv[1]) {
   try {
     isMain = fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
-  } catch { isMain = false; }
+  } catch {
+    isMain = false;
+  }
 }
 if (isMain) {
   main().catch(err => {
     console.error(chalk.red('Fatal error:'), err);
     process.exit(1);
   });
-}
+}