dravoice 0.1.3 → 0.1.4

package/src/v2/review.js

@@ -10,11 +10,11 @@ const REVIEW_MODES = {
     exitOnDrift: false,
   },
   balanced: {
-    findingThresholds: { evidence: 65, rhythm: 55, rhetoricalShape: 50 },
+    findingThresholds: { evidence: 65, rhythm: 55, rhetoricalShape: 50, discourse: 55, lexical: 55, register: 55, structure: 55 },
     exitOnDrift: false,
   },
   strict: {
-    findingThresholds: { evidence: 75, rhythm: 70, rhetoricalShape: 65 },
+    findingThresholds: { evidence: 75, rhythm: 70, rhetoricalShape: 65, discourse: 65, lexical: 65, register: 70, structure: 91 },
     exitOnDrift: true,
   },
 };
@@ -34,6 +34,7 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
     draftDocument.wordCount < sourceProfile.calibration.minimumDraftSize.words ||
     draftDocument.sentences.length < sourceProfile.calibration.minimumDraftSize.sentences
   ) {
+    const familyConfidence = familyConfidenceFor(sourceProfile, {});
     return {
       schemaVersion: 2,
       file: displayPath(filePath, cwd),
@@ -41,6 +42,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
         mode: reviewMode,
         fit: { band: "insufficient-evidence", distance: 0 },
         familyScores: {},
+        familyConfidence,
+        suppressedFindings: suppressedFindingsFor(sourceProfile, familyConfidence),
         corpusConfidence: sourceProfile.source.confidence,
       },
       findings: [],
@@ -51,7 +54,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
   const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
   const familyScores = Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.score]));
   const distance = styleDistanceFromDiagnostics(familyDiagnostics);
-  const findings = reviewFindings(sourceProfile, draftProfile, familyScores, reviewMode);
+  const familyConfidence = familyConfidenceFor(sourceProfile, familyDiagnostics);
+  const findings = reviewFindings(sourceProfile, draftProfile, familyScores, reviewMode, familyConfidence);
   const fit = {
     band: fitBand(distance, findings, familyDiagnostics),
     distance,
@@ -64,6 +68,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
       mode: reviewMode,
       fit,
       familyScores,
+      familyConfidence,
+      suppressedFindings: suppressedFindingsFor(sourceProfile, familyConfidence),
       familyDistances: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.distance])),
       familyDrift: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.drift])),
       thresholds: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.threshold])),
@@ -76,71 +82,175 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
 
 export function renderVoiceReviewV2(result) {
   const lines = [
-    "Voice rewrite notes, not AI detection.",
+    "Voice review notes, not AI detection.",
     "",
     result.file,
-    `Voice fit: ${capitalize(result.summary.fit.band)} (${result.summary.fit.distance} distance)`,
+    `Fit: ${capitalize(result.summary.fit.band)} (${result.summary.fit.distance} style distance)`,
     `Corpus confidence: ${capitalize(result.summary.corpusConfidence.band)} - ${result.summary.corpusConfidence.message}`,
     "Family scores:",
   ];
 
   for (const [family, score] of Object.entries(result.summary.familyScores)) {
-    lines.push(`- ${family}: ${score}`);
+    lines.push(`- ${familyLabel(family)}: ${score}`);
   }
 
   lines.push("");
   if (result.findings.length === 0) {
-    lines.push("No high-confidence V2 voice drift findings.");
+    lines.push("No high-confidence voice drift findings.");
+    appendSuppressedFindings(lines, result.summary.suppressedFindings);
     lines.push("");
     return lines.join("\n");
   }
 
   lines.push("Start here:");
-  for (const finding of result.findings.slice(0, 6)) {
-    lines.push(`${finding.priority} ${finding.family} ${finding.id}`);
-    lines.push(`Why flagged: ${finding.why}`);
-    lines.push(`Revise by: ${finding.action}`);
+  result.findings.slice(0, 6).forEach((finding, index) => {
+    lines.push(`${index + 1}. ${priorityLabel(finding.priority)} ${familyLabel(finding.family)}`);
+    if (finding.confidence) {
+      lines.push(`Confidence: ${capitalize(finding.confidence.band)}; stability ${finding.confidence.stability}`);
+    }
+    lines.push(`Why: ${finding.why}`);
+    lines.push(`Do this: ${finding.action}`);
     lines.push("");
-  }
+  });
+  appendSuppressedFindings(lines, result.summary.suppressedFindings);
   return lines.join("\n");
 }
 
-function reviewFindings(source, draft, scores, mode) {
+function reviewFindings(source, draft, scores, mode, familyConfidence) {
   const modeConfig = REVIEW_MODES[mode];
   if (source.source?.confidence?.band === "weak" || !modeConfig.findingThresholds) {
     return [];
   }
   const findings = [];
-  if (scores.evidence < modeConfig.findingThresholds.evidence) {
+  if (shouldFlag("evidence", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.evidence-drift",
       family: "evidence",
       priority: "review",
+      confidence: familyConfidence.evidence,
       why: `Source evidence sentence rate is ${source.families.evidence.features.evidenceSentenceRate}; draft rate is ${draft.families.evidence.features.evidenceSentenceRate}.`,
       action: "Add concrete support before broad claims: a scene, quote, number, citation, URL, sensory detail, or specific example.",
     });
   }
-  if (scores.rhythm < modeConfig.findingThresholds.rhythm) {
+  if (shouldFlag("rhythm", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.rhythm-drift",
       family: "rhythm",
       priority: "consider",
+      confidence: familyConfidence.rhythm,
       why: `Source median sentence/paragraph length is ${source.families.rhythm.features.sentenceWords.median}/${source.families.rhythm.features.paragraphWords.median}; draft is ${draft.families.rhythm.features.sentenceWords.median}/${draft.families.rhythm.features.paragraphWords.median}.`,
       action: "Revise sentence and paragraph pacing toward the learned range.",
     });
   }
-  if (scores.rhetoricalShape < modeConfig.findingThresholds.rhetoricalShape) {
+  if (shouldFlag("rhetoricalShape", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.shape-drift",
       family: "rhetoricalShape",
       priority: "consider",
+      confidence: familyConfidence.rhetoricalShape,
       why: `Source opening shape is ${source.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ")}; draft opening shape is ${draft.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ")}.`,
       action: "Rework the opening so it uses a compatible scene, claim, contrast, reflection, or example sequence.",
     });
   }
+  if (shouldFlag("discourse", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.discourse-drift",
+      family: "discourse",
+      priority: "consider",
+      confidence: familyConfidence.discourse,
+      why: `Source transition rates are ${rateMapLabel(source.families.discourse.features.transitionRates)}; draft rates are ${rateMapLabel(draft.families.discourse.features.transitionRates)}.`,
+      action: "Revise repeated sentence turns, callbacks, and transitions so the draft does not lean on a different discourse pattern.",
+    });
+  }
+  if (shouldFlag("lexical", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.lexical-drift",
+      family: "lexical",
+      priority: "consider",
+      confidence: familyConfidence.lexical,
+      why: `Function-word, masked character, punctuation, or boundary-token habits drift from the calibrated source profile.`,
+      action: "Revise diction and punctuation where it improves the article; do not stuff source topic words or add artificial imperfections.",
+    });
+  }
+  if (shouldFlag("register", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.register-drift",
+      family: "register",
+      priority: "consider",
+      confidence: familyConfidence.register,
+      why: `Source primary register is ${source.families.register.features.primary.value}; draft primary register is ${draft.families.register.features.primary.value}.`,
+      action: "Bring the stance closer to the learned genre mix while preserving the draft's real subject and audience.",
+    });
+  }
+  if (shouldFlag("structure", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.structure-drift",
+      family: "structure",
+      priority: "consider",
+      confidence: familyConfidence.structure,
+      why: `Source heading/list/quote and section-size patterns differ from the draft's document structure.`,
+      action: "Adjust section shape, opening order, list use, or quote placement only where the article benefits from that structure.",
+    });
+  }
   return findings;
 }
 
+function shouldFlag(family, scores, modeConfig, familyConfidence) {
+  return familyConfidence[family]?.usableForFindings &&
+    Number.isFinite(scores[family]) &&
+    scores[family] < modeConfig.findingThresholds[family];
+}
+
+function familyConfidenceFor(sourceProfile, familyDiagnostics) {
+  const profileDiagnostics = sourceProfile.calibration?.familyDiagnostics ?? {};
+  return Object.fromEntries(Object.keys(sourceProfile.families ?? {}).map((family) => {
+    const profile = profileDiagnostics[family] ?? {};
+    const runtime = familyDiagnostics[family] ?? {};
+    return [family, {
+      band: sourceProfile.families[family]?.confidence ?? "low",
+      stability: runtime.stability ?? profile.stability ?? 0.45,
+      observations: profile.observations ?? runtime.observations ?? 0,
+      usableForFindings: profile.usableForFindings ?? sourceProfile.source?.confidence?.band !== "weak",
+      minimumEvidence: profile.minimumEvidence ?? null,
+    }];
+  }));
+}
+
+function suppressedFindingsFor(sourceProfile, familyConfidence) {
+  return Object.entries(familyConfidence)
+    .filter(([, confidence]) => !confidence.usableForFindings)
+    .map(([family, confidence]) => ({
+      family,
+      reason: suppressedReasonFor(sourceProfile, confidence),
+    }));
+}
+
+function suppressedReasonFor(sourceProfile, confidence) {
+  if (sourceProfile.source?.confidence?.band === "weak") {
+    return "weak corpus confidence; add more representative source documents before trusting this family.";
+  }
+  const minimum = confidence.minimumEvidence;
+  if (minimum && (!minimum.documentsMet || !minimum.sentencesMet || !minimum.wordsMet)) {
+    return `minimum evidence not met; requires ${minimum.requiredDocuments} document(s), ${minimum.requiredSentences} sentence(s), and ${minimum.requiredWords} word(s).`;
+  }
+  return "calibration stability is too low for a high-confidence finding.";
+}
+
+function appendSuppressedFindings(lines, suppressedFindings = []) {
+  if (!suppressedFindings.length) {
+    return;
+  }
+  lines.push("");
+  lines.push("Suppressed findings:");
+  suppressedFindings.slice(0, 6).forEach((item) => {
+    lines.push(`- ${familyLabel(item.family)}: ${item.reason}`);
+  });
+}
+
+function rateMapLabel(value = {}) {
+  return Object.entries(value).map(([key, rate]) => `${key}:${rate}`).join(", ") || "none";
+}
+
 function normalizeReviewMode(mode) {
   const normalized = String(mode ?? "balanced").toLowerCase();
   if (!Object.hasOwn(REVIEW_MODES, normalized)) {
@@ -175,3 +285,19 @@ function resolvePath(cwd, value) {
 function capitalize(value) {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
+
+function familyLabel(family) {
+  return {
+    evidence: "Evidence",
+    rhythm: "Rhythm",
+    rhetoricalShape: "Rhetorical shape",
+    discourse: "Discourse",
+    lexical: "Lexical style",
+    register: "Register",
+    structure: "Structure",
+  }[family] ?? capitalize(family);
+}
+
+function priorityLabel(priority) {
+  return priority === "review" ? "Review" : "Consider";
+}

package/src/v2/revise-plan.js

@@ -13,7 +13,7 @@ import {
   styleDistanceFromDiagnostics,
 } from "./stylometry.js";
 
-const MAX_ACTIONS = 8;
+const MAX_ACTIONS = 10;
 
 const EDITABILITY = {
   evidence: 1.00,
@@ -36,11 +36,13 @@ export function revisePlanDraftV2({ file, voice, cwd = process.cwd(), maxActions
   const draftProfile = buildVoiceProfileV2({ documents: [draftDocument] });
   const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
   const rollingWindows = rollingWindowsFor({ sourceProfile, draftDocument });
+  const paragraphWindows = paragraphWindowsFor({ sourceProfile, draftDocument });
   const actions = rankedActions({
     sourceProfile,
     draftDocument,
     familyDiagnostics,
     rollingWindows,
+    paragraphWindows,
     maxActions,
   });
 
@@ -61,6 +63,7 @@ export function revisePlanDraftV2({ file, voice, cwd = process.cwd(), maxActions
       familyDrift: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.drift])),
       thresholds: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.threshold])),
       rollingWindows,
+      paragraphWindows,
     },
     actions,
   };
@@ -81,7 +84,7 @@ export function renderRevisePlanV2(plan) {
 
   for (const [family, score] of Object.entries(plan.summary.familyScores)) {
     const drift = plan.summary.familyDrift[family];
-    lines.push(`- ${family}: ${score} (drift ${drift})`);
+    lines.push(`- ${familyLabel(family)}: ${score} (drift ${drift})`);
   }
 
   lines.push("");
@@ -93,17 +96,17 @@ export function renderRevisePlanV2(plan) {
 
   lines.push("Start here:");
   plan.actions.forEach((action, index) => {
-    lines.push(`${index + 1}. ${action.priority} ${action.family} ${action.id}`);
-    lines.push(`   Unit: ${action.unit.type} at line ${action.unit.line}`);
-    lines.push(`   Score: ${action.actionScore}`);
-    lines.push(`   Why flagged: ${action.why}`);
-    lines.push(`   Revise by: ${action.reviseBy}`);
+    lines.push(`${index + 1}. ${priorityLabel(action.priority)} ${familyLabel(action.family)}`);
+    lines.push(`   Where: ${unitLabel(action.unit)}`);
+    lines.push(`   Priority score: ${action.actionScore}`);
+    lines.push(`   Why: ${action.why}`);
+    lines.push(`   Do this: ${action.reviseBy}`);
   });
   lines.push("");
   return lines.join("\n");
 }
 
-function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, rollingWindows, maxActions }) {
+function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, rollingWindows, paragraphWindows, maxActions }) {
   const confidence = confidenceWeight(sourceProfile.source.confidence.band);
   const actions = [
     ...evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
@@ -111,6 +114,7 @@ function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, rollin
     ...shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
     ...discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
     ...rollingWindowActions({ rollingWindows, confidence }),
+    ...paragraphWindowActions({ paragraphWindows, confidence }),
     ...documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
   ].filter((action) => action.actionScore > 0);
 
@@ -322,6 +326,41 @@ function rollingWindowsFor({ sourceProfile, draftDocument }) {
     .slice(0, 4);
 }
 
+function paragraphWindowsFor({ sourceProfile, draftDocument }) {
+  const result = [];
+  for (const [index, paragraph] of draftDocument.paragraphs.entries()) {
+    const sentences = draftDocument.sentences.filter((sentence) =>
+      sentence.line >= paragraph.line &&
+      sentence.line <= (paragraph.lineNumbers?.at(-1) ?? paragraph.line)
+    );
+    if (sentences.length < 2) {
+      continue;
+    }
+    const paragraphProfile = buildVoiceProfileV2({ documents: [documentForParagraph(draftDocument, paragraph, sentences, index)] });
+    const diagnostics = familyDiagnosticsFor(sourceProfile, paragraphProfile);
+    const ranked = ["evidence", "rhythm", "discourse", "rhetoricalShape", "lexical"]
+      .map((family) => ({ family, ...diagnostics[family] }))
+      .sort((left, right) => right.drift - left.drift || (100 - right.score) - (100 - left.score));
+    const best = ranked[0];
+    if (best?.drift > 0) {
+      result.push({
+        family: best.family,
+        paragraph: index + 1,
+        startLine: paragraph.line,
+        endLine: paragraph.lineNumbers?.at(-1) ?? paragraph.line,
+        distance: best.distance,
+        drift: best.drift,
+        score: best.score,
+        threshold: best.threshold,
+        stability: best.stability,
+      });
+    }
+  }
+  return result
+    .sort((left, right) => right.drift - left.drift || left.startLine - right.startLine)
+    .slice(0, 4);
+}
+
 function rollingWindowStarts(sentenceCount, windowSize, stride) {
   const starts = [];
   for (let start = 0; start <= sentenceCount - windowSize; start += stride) {
@@ -363,6 +402,29 @@ function documentForSentences(draftDocument, sentences, windowIndex) {
   };
 }
 
+function documentForParagraph(draftDocument, paragraph, sentences, paragraphIndex) {
+  const block = {
+    type: paragraph.type,
+    line: paragraph.line,
+    heading: paragraph.heading,
+    headingId: paragraph.headingId,
+    headingDepth: 0,
+    lines: [paragraph.text],
+    lineNumbers: paragraph.lineNumbers ?? [paragraph.line],
+  };
+  return {
+    file: `${draftDocument.file ?? "draft"}#paragraph-${paragraphIndex + 1}`,
+    path: draftDocument.path,
+    headings: [],
+    sections: [{ heading: null, blocks: [block] }],
+    blocks: [block],
+    paragraphs: [paragraph],
+    sentences,
+    wordCount: sentences.reduce((sum, sentence) => sum + sentence.tokens.length, 0),
+    text: paragraph.text,
+  };
+}
+
 function rollingWindowActions({ rollingWindows, confidence }) {
   return rollingWindows.map((window, index) => makeAction({
     family: window.family,
@@ -378,6 +440,21 @@ function rollingWindowActions({ rollingWindows, confidence }) {
   }));
 }
 
+function paragraphWindowActions({ paragraphWindows, confidence }) {
+  return paragraphWindows.map((window, index) => makeAction({
+    family: window.family,
+    ordinal: `paragraph-${index + 1}`,
+    priority: window.family === "evidence" ? "review" : "consider",
+    unit: { type: "paragraph", line: window.startLine, endLine: window.endLine },
+    confidence,
+    drift: window.drift,
+    stability: window.stability,
+    localMismatch: Math.min(0.45, window.drift / Math.max(1, window.drift + 0.5)),
+    why: `Paragraph ${window.paragraph} shows localized ${window.family} drift beyond the writer's calibrated range.`,
+    reviseBy: rollingWindowReviseBy(window.family),
+  }));
+}
+
 function rollingWindowReviseBy(family) {
   if (family === "evidence") {
     return "Add or move concrete support into this local passage, or narrow the unsupported claims in the same window.";
@@ -435,3 +512,29 @@ function resolvePath(cwd, value) {
 function capitalize(value) {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
+
+function familyLabel(family) {
+  return {
+    evidence: "Evidence",
+    rhythm: "Rhythm",
+    rhetoricalShape: "Rhetorical shape",
+    discourse: "Discourse",
+    lexical: "Lexical style",
+    register: "Register",
+    structure: "Structure",
+  }[family] ?? capitalize(family);
+}
+
+function priorityLabel(priority) {
+  return priority === "review" ? "Review" : "Consider";
+}
+
+function unitLabel(unit) {
+  if (unit.type === "window") {
+    return `sentence window at lines ${unit.line}-${unit.endLine}`;
+  }
+  if (unit.type === "paragraph") {
+    return `paragraph at lines ${unit.line}-${unit.endLine}`;
+  }
+  return `${unit.type} at line ${unit.line}`;
+}

package/src/v2/stylometry.js

@@ -159,9 +159,9 @@ function discourseDistance(source, draft) {
   const transitionDelta = rateMapDistance(source.transitionRates, draft.transitionRates);
   const callbackDelta = Math.abs((source.sentenceCallbacks ?? 0) - (draft.sentenceCallbacks ?? 0));
   return weightedMean([
-    [transitionDelta, 0.55],
-    [topItemDistance(source.transitionBigrams, draft.transitionBigrams), 0.25],
-    [topItemDistance(source.transitionTrigrams, draft.transitionTrigrams), 0.10],
+    [transitionDelta, 0.65],
+    [topItemDistance(source.transitionBigrams, draft.transitionBigrams), 0.10],
+    [topItemDistance(source.transitionTrigrams, draft.transitionTrigrams), 0.025],
     [callbackDelta, 0.20],
   ]);
 }
@@ -188,10 +188,14 @@ function shapeDistance(source, draft) {
 
 function structureDistance(source, draft) {
   return weightedMean([
-    [distributionDelta(source.sectionWords, draft.sectionWords), 0.35],
-    [distributionDelta(source.headingCount, draft.headingCount), 0.20],
-    [Math.abs((source.listDocumentRate ?? 0) - (draft.listDocumentRate ?? 0)), 0.18],
-    [Math.abs((source.quoteDocumentRate ?? 0) - (draft.quoteDocumentRate ?? 0)), 0.12],
+    [distributionDelta(source.sectionWords, draft.sectionWords), 0.30],
+    [distributionDelta(source.headingCount, draft.headingCount), 0.16],
+    [distributionDelta(source.maxHeadingDepth, draft.maxHeadingDepth), 0.12],
+    [topItemDistance(source.sectionOrderPatterns, draft.sectionOrderPatterns), 0.12],
+    [topItemDistance(source.listPlacementPatterns, draft.listPlacementPatterns), 0.08],
+    [topItemDistance(source.quotePlacementPatterns, draft.quotePlacementPatterns), 0.08],
+    [Math.abs((source.listDocumentRate ?? 0) - (draft.listDocumentRate ?? 0)), 0.12],
+    [Math.abs((source.quoteDocumentRate ?? 0) - (draft.quoteDocumentRate ?? 0)), 0.08],
     [sequenceDistance(source.openingMoves, draft.openingMoves), 0.15],
   ]);
 }