Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

29.1 KB
Raw Blame
/**
 * Dialogue-craft deterministic primitives (#1307) for the editorial check
 * registry. Pure and dependency-free (no side-effecting imports) so it stays
 * unit-testable in isolation — mirrors ./proseTics.js and ./cliches.js.
 *
 * Two scanners back the two deterministic dialogue checks in checkRegistry.js:
 *   - findSaidBookisms()           → `dialogue.said-bookisms`     (ornate / non-speech tags)
 *   - findUnattributedDialogueRuns() → `dialogue.attribution-clarity` (untrackable speakers)
 *
 * Their LLM siblings (`dialogue.on-the-nose`, `dialogue.voice-distinctiveness`,
 * `dialogue.reported-speech`) handle the judgment cases these pure scanners
 * can't: subtext-free / "as you know, Bob" dialogue, per-character voice
 * distinctiveness against canon, and the decisive line that was narrated as
 * reported speech instead of quoted (which no quote-delimited scan can see,
 * because there is no quote on the page to find).
 *
 * Quote handling: only DOUBLE quotes (straight " and curly “ ”) are treated as
 * dialogue delimiters. Single quotes are deliberately excluded — they collide
 * with apostrophes (it's, don't, ’em) and would wreck precision. Manuscripts in
 * the pipeline use double-quote dialogue, so this is a safe simplification.
 */

import { escapeRegExp } from '../textUtils.js';

// Straight + curly double quotes. Used both as a character class body (DQUOTE)
// and to build "quoted span" / "non-quote run" regexes.
const DQUOTE = '"“”';
const DQUOTE_CLASS = `[${DQUOTE}]`;
const NON_DQUOTE = `[^${DQUOTE}]`;

// A "speaker" token that can sit beside a dialogue tag — a capitalized proper
// name or a personal pronoun. Used to anchor a tag verb to a real attribution
// (so "the dog growled" in narration doesn't read as a said-bookism).
const SPEAKER = "(?:[A-Z][\\w'’\\-]+|he|she|they|him|her|them|I|we|you|it)";

// Said-bookisms — ornate speech-tag verbs that should almost always collapse to
// "said" / "asked". Curated, lowercase, base form; the matcher inflects each to
// its -s / past-tense forms. A series can mute entries (allowWords) or extend
// the list (extraWords) for genre voice.
export const SAID_BOOKISMS = Object.freeze([
  'expostulate', 'ejaculate', 'opine', 'interject', 'enunciate', 'articulate',
  'proclaim', 'exclaim', 'vociferate', 'bellow', 'thunder', 'simper', 'chortle',
  'guffaw', 'snarl', 'growl', 'hiss', 'purr', 'quip', 'retort', 'riposte',
  'interpose', 'remonstrate', 'expound', 'asseverate', 'aver', 'posit',
  'postulate', 'elucidate', 'intone', 'drawl', 'bleat', 'splutter', 'sputter',
  'wheeze', 'rasp', 'croak', 'trill', 'warble', 'pontificate', 'declaim',
  'orate', 'soliloquize',
]);

// Non-speech actions misused as speech tags — you cannot smile / laugh / nod a
// line of dialogue. ("'Yes,' she smiled.") Base form; inflected by the matcher.
export const NON_SPEECH_TAGS = Object.freeze([
  'smile', 'grin', 'laugh', 'chuckle', 'nod', 'shrug', 'sigh', 'frown',
  'beam', 'wink', 'sob', 'snort', 'gesture', 'scowl', 'smirk', 'pout',
  'wince', 'gulp', 'shudder',
]);

// Plain, invisible speech tags — the ones a writer SHOULD use. Presence of any
// of these (or an action beat) is what makes a dialogue line "attributed" for
// the attribution-clarity scan. Grouped by base lemma so the tag-variety check
// (#1587) can collapse inflections ("said"/"says") onto one verb when measuring
// per-scene monotony; the surface forms include irregulars (said, told, spoke)
// that inflectVerb() can't generate, so the groups are the source of truth.
export const PLAIN_SPEECH_TAG_GROUPS = Object.freeze([
  { base: 'say', forms: ['said', 'says', 'say'] },
  { base: 'ask', forms: ['asked', 'asks', 'ask'] },
  { base: 'reply', forms: ['replied', 'replies'] },
  { base: 'whisper', forms: ['whispered', 'whispers'] },
  { base: 'shout', forms: ['shouted', 'shouts'] },
  { base: 'mutter', forms: ['muttered', 'mutters'] },
  { base: 'murmur', forms: ['murmured', 'murmurs'] },
  { base: 'answer', forms: ['answered', 'answers'] },
  { base: 'call', forms: ['called', 'calls'] },
  { base: 'cry', forms: ['cried', 'cries'] },
  { base: 'yell', forms: ['yelled', 'yells'] },
  { base: 'snap', forms: ['snapped', 'snaps'] },
  { base: 'breathe', forms: ['breathed', 'breathes'] },
  { base: 'add', forms: ['added', 'adds'] },
  { base: 'continue', forms: ['continued', 'continues'] },
  { base: 'state', forms: ['stated', 'states'] },
  { base: 'demand', forms: ['demanded', 'demands'] },
  { base: 'tell', forms: ['told', 'tells'] },
  { base: 'speak', forms: ['spoke', 'speaks'] },
]);

// Flattened surface forms — kept for the attribution scan's PLAIN_TAG_RE, which
// only needs "is this token a plain speech tag", not which lemma it maps to.
const PLAIN_SPEECH_TAGS = Object.freeze(PLAIN_SPEECH_TAG_GROUPS.flatMap((g) => g.forms));

function normalizeWord(p) {
  return typeof p === 'string' ? p.trim().toLowerCase() : '';
}

// Regular inflections of a base verb for tag matching: base, +s, and the past
// tense (+ed, drop-e +d, or doubled-final-consonant +ed). Returns lowercased,
// de-duped surface forms. Mirrors the inflection rules in proseTics.inflect().
function inflectVerb(base) {
  const b = base.toLowerCase();
  const forms = new Set([b, `${b}s`]);
  if (b.endsWith('e')) {
    forms.add(`${b}d`);
  } else {
    forms.add(`${b}ed`);
    // Short CVC base doubles its final consonant: nod → nodded. The `qu…` arm
    // catches words where the `u` is part of a `qu` onset rather than the vowel
    // (quip → quipped), which the plain CVC test would miss (it reads `u` as a vowel).
    if (/[^aeiou][aeiou][^aeiouwxy]$/.test(b) || /qu[aeiou][^aeiouwxy]$/.test(b)) {
      forms.add(`${b}${b.slice(-1)}ed`);
    }
  }
  return [...forms];
}

// Map every inflected surface form of a verb list back to its base, honoring an
// allow-list (muted bases) and extra additions. Returns { forms[], formToBase }.
function buildVerbForms(seed, opts = {}) {
  const allow = new Set((Array.isArray(opts.allowWords) ? opts.allowWords : []).map(normalizeWord).filter(Boolean));
  const extra = (Array.isArray(opts.extraWords) ? opts.extraWords : []).map(normalizeWord).filter(Boolean);
  const formToBase = new Map();
  const seen = new Set();
  for (const w of [...seed, ...extra]) {
    const norm = normalizeWord(w);
    if (!norm || seen.has(norm) || allow.has(norm)) continue;
    seen.add(norm);
    for (const f of inflectVerb(norm)) if (!formToBase.has(f)) formToBase.set(f, norm);
  }
  return { forms: [...formToBase.keys()], formToBase };
}

// Build the two dialogue-tag regexes for a set of inflected verb forms:
//   after-quote:  "…," she opined   /   "…," opined Marlon
//   before-quote: She opined, "…"
// The verb must sit immediately beside a double-quote span and a speaker, so a
// bare narrated verb ("the dog growled") never matches. Returns null when the
// effective form list is empty.
function buildTagMatchers(forms) {
  if (!forms.length) return null;
  // Longest-first so "expostulated" wins over a shorter prefix under alternation.
  const alt = forms.slice().sort((a, b) => b.length - a.length).map(escapeRegExp).join('|');
  const VERB = `(${alt})`;
  // After a closing quote: capture the terminal punctuation that sits INSIDE the
  // quote (`," ` vs `." `) so the caller can tell a real tag from an action beat.
  // Group 1 = that punctuation (may be empty); group 2 = the verb. Standard prose
  // ends a quote with a comma when a tag follows ("…," she said) and a period
  // when the dialogue is a complete sentence and the next clause is a separate
  // action beat ("…." She smiled.) — a period-terminated quote is NOT a tag.
  // The `d` (hasIndices) flag exposes each capture group's offset via match
  // `.indices`, so scanTagMatchers can dedupe on the VERB's absolute position —
  // a split-quote tag ("Yes," she said, "but…") is seen by BOTH passes at
  // different match starts but the same verb offset, so it counts once.
  const after = new RegExp(`([,.!?])?${DQUOTE_CLASS}\\s+(?:${SPEAKER}\\s+)?${VERB}\\b`, 'gid');
  // Before an opening quote: speaker → verb → optional comma/colon → quote. This
  // ordering is unambiguously a tag, so no punctuation gate is needed. Group 1 = verb.
  const before = new RegExp(`\\b${SPEAKER}\\s+${VERB}\\s*[,:]?\\s*${DQUOTE_CLASS}`, 'gid');
  return { after, before };
}

// Given a tag's `kind` and the punctuation that terminated the preceding quote,
// decide whether it reads as a real dialogue tag (worth flagging) vs an action
// beat that merely follows a complete line of dialogue (legitimate — leave it):
//   - non-speech ("she smiled"): a misuse ONLY when comma-attached like a speech
//     tag ("Of course," she smiled). After a period/!/? the quote is a complete
//     sentence and "She smiled." is a separate, correct action beat.
//   - bookism ("she opined"): an ornate SPEECH verb is a valid (if ugly) tag after
//     a comma/?/! or a tag-continuing quote with no terminal mark — but not after a
//     period, where the following clause is a new sentence, not a tag.
function punctAllowsTag(kind, punct) {
  if (kind === 'non-speech') return punct === ',';
  return punct !== '.';
}

// Walk both quote-adjacent matchers over `text` and let `onMatch` decide what a
// match means. `onMatch(matched, index, punct, full)` receives the matched verb
// surface, its offset, the in-quote terminal punctuation (null for the
// before-quote pass, which needs no punctuation gate), and the full match text;
// it returns a result object (must include `verb` for de-dup) or null to skip.
// Results are deduped by (verb @ index) so the two regexes don't double-report a
// tag, and returned in position order. Shared by findSaidBookisms (kind-aware
// gating) and the tag-variety inventory (kind-agnostic gating).
function scanTagMatchers(text, matchers, onMatch) {
  if (!matchers) return [];
  const out = [];
  const seen = new Set();
  const passes = [
    { re: matchers.after, verbGroup: 2, punctGroup: 1 },
    { re: matchers.before, verbGroup: 1, punctGroup: null },
  ];
  for (const { re, verbGroup, punctGroup } of passes) {
    re.lastIndex = 0;
    let m;
    while ((m = re.exec(text)) !== null) {
      const matched = m[verbGroup];
      const punct = punctGroup !== null ? (m[punctGroup] || '') : null;
      // De-dup and anchor on the VERB's absolute offset (via the `d`-flag capture
      // indices), not the match start — a split-quote tag matches in BOTH passes
      // at different starts but the same verb offset, so it counts once.
      const verbIndex = m.indices?.[verbGroup]?.[0] ?? m.index;
      const res = onMatch(matched, verbIndex, punct, m[0]);
      if (!res) continue;
      const key = `${res.verb}@${verbIndex}`;
      if (seen.has(key)) continue;
      seen.add(key);
      out.push({ ...res, index: verbIndex });
    }
  }
  return out.sort((a, b) => a.index - b.index);
}

/**
 * Find said-bookism and non-speech dialogue tags in `text`. Only verbs sitting
 * immediately beside a double-quote span (a real dialogue tag) are returned, so
 * narrated uses of the same verb ("the engine growled") are not flagged.
 *
 * @param {string} text
 * @param {{ allowWords?: string[], extraWords?: string[] }} [opts]
 *   allowWords — bases to mute (house-style / genre voice).
 *   extraWords — extra bookism bases to flag (treated as 'bookism' kind).
 * @returns {Array<{ verb: string, kind: 'bookism'|'non-speech', index: number, anchor: string }>}
 *   in position order, deduped by (verb-base @ index) so the two regexes don't
 *   double-report the same tag.
 */
export function findSaidBookisms(text, opts = {}) {
  if (typeof text !== 'string' || !text) return [];
  const bookisms = buildVerbForms(SAID_BOOKISMS, opts);
  // Non-speech tags share the allow-list but ignore extraWords (those extend the
  // bookism list, semantically), so build them with only the allow-list applied.
  const nonSpeech = buildVerbForms(NON_SPEECH_TAGS, { allowWords: opts.allowWords });
  const kindByForm = new Map();
  for (const [form, base] of bookisms.formToBase) kindByForm.set(form, { base, kind: 'bookism' });
  // Non-speech wins only where a form isn't already a bookism (no overlap today).
  for (const [form, base] of nonSpeech.formToBase) if (!kindByForm.has(form)) kindByForm.set(form, { base, kind: 'non-speech' });

  const matchers = buildTagMatchers([...kindByForm.keys()]);
  return scanTagMatchers(text, matchers, (matched, index, punct, full) => {
    const info = kindByForm.get(matched.toLowerCase());
    if (!info) return null;
    // For the after-quote pass (punct !== null), gate on the in-quote terminal
    // punctuation so an action beat following a complete sentence ("…." She
    // smiled.) isn't flagged as a misused tag, and reject a CAPITALIZED word
    // after the quote — that's the subject of a NEW sentence (narration), e.g.
    // `"Run!" Thunder rolled overhead.`, not a tag. The before-quote pass has no
    // punctuation to weigh.
    if (punct !== null) {
      if (!punctAllowsTag(info.kind, punct)) return null;
      if (matched[0] !== matched[0].toLowerCase()) return null;
    }
    return { verb: info.base, kind: info.kind, anchor: full.trim() };
  });
}

// A single regex matching any plain-speech-tag word (whole-word, case-insens.),
// used to decide whether a dialogue paragraph carries attribution.
const PLAIN_TAG_RE = new RegExp(`\\b(?:${PLAIN_SPEECH_TAGS.join('|')})\\b`, 'i');
// All bookism + non-speech inflected forms also count as attribution (an ornate
// tag is still a tag — it's the said-bookism check's job to flag it, not the
// attribution check's job to call it unattributed). Built once at module load.
const ORNATE_TAG_RE = (() => {
  const { forms } = buildVerbForms([...SAID_BOOKISMS, ...NON_SPEECH_TAGS]);
  return forms.length ? new RegExp(`\\b(?:${forms.map(escapeRegExp).join('|')})\\b`, 'i') : null;
})();
const QUOTED_SPAN_RE = new RegExp(`${DQUOTE_CLASS}${NON_DQUOTE}*${DQUOTE_CLASS}`, 'g');

// A paragraph is a "dialogue line" when it contains a complete quoted span.
const hasQuotedSpan = (para) => {
  QUOTED_SPAN_RE.lastIndex = 0;
  return QUOTED_SPAN_RE.test(para);
};

// A dialogue paragraph is "attributed" when it carries a speech tag (plain or
// ornate) OR an action beat — substantial non-quoted prose that grounds who is
// speaking. Both signals are measured on the NON-QUOTED remainder: a tag word
// that appears INSIDE the dialogue ("I said no.") is spoken text, not
// attribution, so the tag regexes must run on the narration around the quote,
// not the whole paragraph.
function isAttributed(para, beatChars) {
  const beat = para.replace(QUOTED_SPAN_RE, ' ').replace(/\s+/g, ' ').trim();
  if (PLAIN_TAG_RE.test(beat) || (ORNATE_TAG_RE && ORNATE_TAG_RE.test(beat))) return true;
  return beat.length >= beatChars;
}

/**
 * Find runs of consecutive unattributed dialogue paragraphs — a stretch of
 * back-and-forth where no tag or action beat re-anchors the speaker, so the
 * reader loses track of who is talking. Paragraphs are split on blank/newline
 * boundaries; only dialogue paragraphs (those with a quoted span) participate,
 * and a non-dialogue paragraph (pure narration) breaks a run.
 *
 * @param {string} text
 * @param {{ minRun?: number, beatChars?: number }} [opts]
 *   minRun — consecutive unattributed dialogue lines before a run is flagged
 *            (default 6 — two speakers alternating stay trackable for a few
 *            exchanges; a longer untagged run is where tracking genuinely fails).
 *   beatChars — non-quoted chars that count a paragraph as carrying an action
 *               beat (default 16).
 * @returns {Array<{ count: number, index: number, anchor: string }>}
 *   one entry per run; `index` is the offset of the run's first line, `anchor`
 *   is that first line (trimmed, capped) so the editor can jump to the run start.
 */
export function findUnattributedDialogueRuns(text, opts = {}) {
  if (typeof text !== 'string' || !text) return [];
  const minRun = Math.max(2, Number.isInteger(opts.minRun) ? opts.minRun : 6);
  const beatChars = Number.isInteger(opts.beatChars) ? opts.beatChars : 16;

  // Split into paragraphs, tracking each paragraph's absolute start offset.
  const paras = [];
  const re = /[^\n]+/g;
  let m;
  while ((m = re.exec(text)) !== null) {
    if (m[0].trim()) paras.push({ text: m[0], index: m.index });
  }

  const out = [];
  let runStart = -1; // offset of the first line in the current unattributed run
  let runFirst = ''; // that first line's text
  let runCount = 0;
  const flush = () => {
    if (runCount >= minRun && runStart >= 0) {
      out.push({ count: runCount, index: runStart, anchor: runFirst.trim().slice(0, 200) });
    }
    runStart = -1;
    runFirst = '';
    runCount = 0;
  };
  for (const p of paras) {
    if (!hasQuotedSpan(p.text)) {
      // Pure narration breaks any in-progress dialogue run.
      flush();
      continue;
    }
    if (isAttributed(p.text, beatChars)) {
      // An attributed dialogue line re-anchors the speaker — the run resets, but
      // this line itself is fine (not part of an UNattributed run).
      flush();
      continue;
    }
    // Unattributed dialogue line — extend (or start) the current run.
    if (runCount === 0) { runStart = p.index; runFirst = p.text; }
    runCount += 1;
  }
  flush();
  return out;
}

/**
 * Attribute spoken dialogue paragraphs to the cast for a coarse dialogue-share
 * signal (cast representation & balance, #1312). For each dialogue paragraph
 * (one carrying a quoted span) the speaker is inferred from the NON-quoted beat
 * around the quote — exactly the surface the attribution-clarity scan reads — so
 * a name spoken INSIDE the dialogue ("I saw Bram") doesn't mis-attribute the
 * line. A paragraph is credited to the FIRST owner whose token matches the beat;
 * paragraphs whose speaker can't be resolved (no name/alias in the beat) are
 * counted as `unattributed` rather than guessed, per the absent-vs-empty rule.
 *
 * Deliberately coarse: it measures *who is credited with speaking lines*, not a
 * precise turn-by-turn transcript. That's the right grain for a balance ratio
 * (does one character dominate the dialogue?), and it stays pure + dependency-
 * free — the caller supplies the per-owner matchers it already builds for canon.
 *
 * @param {string} text
 * @param {Array<{ key: string, matcher: RegExp }>} owners
 *   one entry per character; `matcher` is a non-global whole-token regex (e.g.
 *   the one checkRegistry's characterMatcher builds). Longest-token-first order
 *   is the caller's responsibility (it governs which owner wins a beat that
 *   names two characters — first match wins).
 * @returns {{ byOwner: Map<string, number>, total: number, attributed: number, unattributed: number }}
 *   byOwner — dialogue-paragraph count per matched owner key (only owners with ≥1
 *   line appear); total — all dialogue paragraphs; attributed/unattributed split.
 */
export function attributeDialogueByOwner(text, owners) {
  const byOwner = new Map();
  const result = { byOwner, total: 0, attributed: 0, unattributed: 0 };
  if (typeof text !== 'string' || !text) return result;
  const list = (Array.isArray(owners) ? owners : []).filter(
    (o) => o && typeof o.key === 'string' && o.matcher instanceof RegExp
  );

  const re = /[^\n]+/g;
  let m;
  while ((m = re.exec(text)) !== null) {
    const para = m[0];
    if (!para.trim() || !hasQuotedSpan(para)) continue;
    result.total += 1;
    // The beat is the narration around the quote — the only place a tag/name
    // legitimately attributes the speaker (a name inside the quote is spoken text).
    const beat = para.replace(QUOTED_SPAN_RE, ' ').replace(/\s+/g, ' ').trim();
    let owner = null;
    if (beat) {
      // Credit the owner whose name appears EARLIEST in the beat — the speaker.
      // In "…," Aria told Bram. the leftmost name (Aria) is the speaker; picking
      // by list (canon) order instead would make attribution depend on canon
      // ordering and credit a beat that merely mentions a second character to
      // the wrong owner. Ties (same index — impossible for distinct names, but
      // guarded) keep first-listed.
      let bestIndex = Infinity;
      for (const o of list) {
        o.matcher.lastIndex = 0; // non-global, but reset defensively
        const m2 = o.matcher.exec(beat);
        if (m2 && m2.index < bestIndex) { bestIndex = m2.index; owner = o.key; }
      }
    }
    if (owner) {
      result.attributed += 1;
      byOwner.set(owner, (byOwner.get(owner) || 0) + 1);
    } else {
      result.unattributed += 1;
    }
  }
  return result;
}

// ---------------------------------------------------------------------------
// Dialogue tag variety / within-scene tag monotony (#1587)
// ---------------------------------------------------------------------------
//
// The said-bookisms scan flags ornate tags; this scan flags the opposite tics
// at the *scene* grain: one tag verb hammered over and over ("she said" eight
// times in a scene) reads as monotony, while a different fancy verb on nearly
// every line ("said / asked / replied / murmured / whispered" churn) reads as a
// thesaurus rummage. Both pull the reader out — the craft target is mostly the
// invisible "said"/"asked" with enough variation to stay unnoticed.
//
// "Scene" is approximated by splitting on common manuscript scene dividers; a
// section with no dividers is treated as a single scene (the right fallback).

// Map every plain-tag inflected surface form → its base lemma, honoring an
// allow-list of muted bases. Mirrors buildVerbForms() but reads the explicit
// PLAIN groups (irregulars like said/told/spoke can't be generated by
// inflectVerb()). Returns a Map<form, base>.
function buildPlainTagForms(opts = {}) {
  const allow = new Set((Array.isArray(opts.allowWords) ? opts.allowWords : []).map(normalizeWord).filter(Boolean));
  const formToBase = new Map();
  for (const { base, forms } of PLAIN_SPEECH_TAG_GROUPS) {
    if (allow.has(base)) continue;
    for (const f of forms) {
      const norm = normalizeWord(f);
      if (norm && !allow.has(norm) && !formToBase.has(norm)) formToBase.set(norm, base);
    }
  }
  return formToBase;
}

// Build the form→base map and quote matchers for the speech-tag inventory once,
// so a multi-scene scan can reuse them instead of recompiling regexes per scene.
function buildTagInventory(opts = {}) {
  const formToBase = buildPlainTagForms(opts);
  const ornate = buildVerbForms(SAID_BOOKISMS, opts);
  // Plain wins on overlap (none today), so only add ornate forms not already mapped.
  for (const [f, b] of ornate.formToBase) if (!formToBase.has(f)) formToBase.set(f, b);
  return { formToBase, matchers: buildTagMatchers([...formToBase.keys()]) };
}

// Scan `text` for speech tags using a prebuilt inventory. Both plain and ornate
// tags are speech verbs, so gate them like a bookism: a period-terminated quote
// starts a NEW sentence (not a tag), and a capitalized word after the quote is
// that sentence's subject (narration).
function scanTagInventory(text, { formToBase, matchers }) {
  return scanTagMatchers(text, matchers, (matched, index, punct, full) => {
    const base = formToBase.get(matched.toLowerCase());
    if (!base) return null;
    if (punct !== null) {
      if (punct === '.') return null;
      if (matched[0] !== matched[0].toLowerCase()) return null;
    }
    return { verb: base, anchor: full.trim() };
  });
}

/**
 * Inventory the *speech* dialogue tags in `text` — every plain ("said", "asked")
 * or ornate ("opined") tag verb sitting beside a double-quote span, mapped back
 * to its base lemma so inflections collapse. Non-speech action "tags" ("she
 * smiled") are deliberately excluded: they aren't speech-tag vocabulary and are
 * the said-bookisms scan's concern. Reuses the same after/before quote matchers
 * and the same punctuation/case gating as findSaidBookisms(), so a narrated verb
 * ("the engine growled") or an action beat after a complete sentence is not
 * counted as a tag.
 *
 * @param {string} text
 * @param {{ allowWords?: string[], extraWords?: string[] }} [opts]
 *   allowWords — bases to mute; extraWords — extra ornate bases to count as tags.
 * @returns {Array<{ verb: string, index: number, anchor: string }>} position-ordered.
 */
export function inventoryDialogueTags(text, opts = {}) {
  if (typeof text !== 'string' || !text) return [];
  return scanTagInventory(text, buildTagInventory(opts));
}

// A line is a scene divider when it is ONLY a centered break: a markdown heading
// ("## Scene 2"), or a rule of repeated * - — – • · ~ marks ("***", "* * *",
// "———"). Such a line ends the current scene and starts the next.
function isSceneBreakLine(line) {
  const t = line.trim();
  if (!t) return false;
  if (/^#{1,6}\s+\S/.test(t)) return true;
  return /^(?:[*\-—–•·~][ \t]*){3,}$/.test(t);
}

/**
 * Split `text` into scenes on common manuscript scene dividers (centered rules
 * and markdown scene headings). The divider line itself belongs to neither
 * adjacent scene. A text with no dividers yields a single scene spanning all of
 * it — the correct fallback for a manuscript that doesn't mark scene breaks.
 *
 * @param {string} text
 * @returns {Array<{ text: string, index: number, ordinal: number }>}
 *   ordinal is 1-based; index is the absolute offset of the scene's first line.
 */
export function splitScenes(text) {
  if (typeof text !== 'string' || !text) return [];
  const scenes = [];
  let buf = [];
  let start = -1;
  const flush = () => {
    if (start >= 0 && buf.join('').trim()) {
      scenes.push({ text: buf.join(''), index: start, ordinal: scenes.length + 1 });
    }
    buf = [];
    start = -1;
  };
  // Keep line terminators so absolute offsets stay exact across the split.
  const re = /[^\n]*\n|[^\n]+$/g;
  let m;
  while ((m = re.exec(text)) !== null) {
    const line = m[0];
    if (isSceneBreakLine(line)) {
      flush();
      continue;
    }
    if (start < 0) start = m.index;
    buf.push(line);
  }
  flush();
  return scenes;
}

/**
 * Flag dialogue-tag variety problems per scene: within-scene MONOTONY (one tag
 * verb dominates a tag-dense scene) and OVER-VARIATION (almost every tagged line
 * uses a different verb — thesaurus churn). Scenes with too few tags to judge
 * are skipped. Pure: splits scenes deterministically, inventories tags, and
 * applies count/ratio thresholds.
 *
 * @param {string} text
 * @param {{ allowWords?: string[], extraWords?: string[], minTags?: number,
 *           monotonyCount?: number, monotonyRatio?: number,
 *           overVariationRatio?: number, minDistinct?: number }} [opts]
 *   minTags — speech tags a scene needs before variety is judged (default 6).
 *   monotonyCount / monotonyRatio — dominant verb must hit BOTH a raw count and
 *     a share-of-tags ratio to flag monotony (defaults 6 / 0.7).
 *   overVariationRatio / minDistinct — distinct-verbs ÷ tags must exceed the
 *     ratio with at least minDistinct verbs to flag churn (defaults 0.85 / 5).
 * @returns {Array<{ type: 'monotony'|'over-variation', sceneOrdinal: number,
 *   verb: string|null, count: number, total: number, distinct: number,
 *   index: number, anchor: string }>}
 */
export function findDialogueTagVariety(text, opts = {}) {
  if (typeof text !== 'string' || !text) return [];
  const minTags = Math.max(3, Number.isInteger(opts.minTags) ? opts.minTags : 6);
  const monotonyCount = Math.max(2, Number.isInteger(opts.monotonyCount) ? opts.monotonyCount : 6);
  const monotonyRatio = Number.isFinite(opts.monotonyRatio) ? opts.monotonyRatio : 0.7;
  const overVariationRatio = Number.isFinite(opts.overVariationRatio) ? opts.overVariationRatio : 0.85;
  const minDistinct = Math.max(2, Number.isInteger(opts.minDistinct) ? opts.minDistinct : 5);

  // Build the tag vocabulary + matchers once and reuse across every scene.
  const inventory = buildTagInventory(opts);
  const out = [];
  for (const scene of splitScenes(text)) {
    const tags = scanTagInventory(scene.text, inventory);
    const total = tags.length;
    if (total < minTags) continue;

    const freq = new Map();
    const firstAt = new Map();
    for (const t of tags) {
      freq.set(t.verb, (freq.get(t.verb) || 0) + 1);
      if (!firstAt.has(t.verb)) firstAt.set(t.verb, t);
    }
    const distinct = freq.size;

    // Dominant verb — monotony when it BOTH repeats enough AND owns most tags.
    let domVerb = null;
    let domCount = 0;
    for (const [verb, count] of freq) {
      if (count > domCount) { domCount = count; domVerb = verb; }
    }
    if (domVerb && domCount >= monotonyCount && domCount / total >= monotonyRatio) {
      const anchorHit = firstAt.get(domVerb);
      out.push({
        type: 'monotony',
        sceneOrdinal: scene.ordinal,
        verb: domVerb,
        count: domCount,
        total,
        distinct,
        index: scene.index + (anchorHit ? anchorHit.index : 0),
        anchor: anchorHit ? anchorHit.anchor : '',
      });
      continue; // a monotone scene can't also be over-varied; don't double-report.
    }

    // Over-variation — a fresh verb on (nearly) every tagged line.
    if (distinct >= minDistinct && distinct / total >= overVariationRatio) {
      out.push({
        type: 'over-variation',
        sceneOrdinal: scene.ordinal,
        verb: null,
        count: distinct,
        total,
        distinct,
        index: scene.index,
        anchor: tags[0].anchor,
      });
    }
  }
  return out;
}