dravoice 0.1.0

package/src/v2/review.js

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocument } from "./document-model.js";
+import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
+import { clampScore } from "./text-utils.js";
+
+const REVIEW_MODES = {
+  loose: {
+    findingThresholds: null,
+    exitOnDrift: false,
+  },
+  balanced: {
+    findingThresholds: { evidence: 65, rhythm: 55, rhetoricalShape: 50 },
+    exitOnDrift: false,
+  },
+  strict: {
+    findingThresholds: { evidence: 75, rhythm: 70, rhetoricalShape: 65 },
+    exitOnDrift: true,
+  },
+};
+
+export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "balanced" }) {
+  const reviewMode = normalizeReviewMode(mode);
+  const sourceProfile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
+  const filePath = path.resolve(file);
+  const draftDocument = parseDocument({
+    filePath,
+    rootDir: cwd,
+    contents: fs.readFileSync(filePath, "utf8"),
+  });
+  const draftProfile = buildVoiceProfileV2({ documents: [draftDocument] });
+
+  if (
+    draftDocument.wordCount < sourceProfile.calibration.minimumDraftSize.words ||
+    draftDocument.sentences.length < sourceProfile.calibration.minimumDraftSize.sentences
+  ) {
+    return {
+      schemaVersion: 2,
+      file: displayPath(filePath, cwd),
+      summary: {
+        mode: reviewMode,
+        fit: { band: "insufficient-evidence", distance: 0 },
+        familyScores: {},
+        corpusConfidence: sourceProfile.source.confidence,
+      },
+      findings: [],
+      exitCode: 0,
+    };
+  }
+
+  const familyScores = scoreFamilies(sourceProfile, draftProfile);
+  const distance = Math.round(Object.values(familyScores).reduce((sum, score) => sum + (100 - score), 0) / Object.keys(familyScores).length);
+  const findings = reviewFindings(sourceProfile, draftProfile, familyScores, reviewMode);
+  const fit = {
+    band: fitBand(distance, findings),
+    distance,
+  };
+
+  return {
+    schemaVersion: 2,
+    file: displayPath(filePath, cwd),
+    summary: {
+      mode: reviewMode,
+      fit,
+      familyScores,
+      corpusConfidence: sourceProfile.source.confidence,
+    },
+    findings,
+    exitCode: REVIEW_MODES[reviewMode].exitOnDrift && fit.band === "drift" ? 1 : 0,
+  };
+}
+
+export function renderVoiceReviewV2(result) {
+  const lines = [
+    "Voice rewrite notes, not AI detection.",
+    "",
+    result.file,
+    `Voice fit: ${capitalize(result.summary.fit.band)} (${result.summary.fit.distance} 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("");
+  if (result.findings.length === 0) {
+    lines.push("No high-confidence V2 voice drift findings.");
+    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}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function scoreFamilies(source, draft) {
+  return {
+    rhythm: rhythmScore(source.families.rhythm.features, draft.families.rhythm.features),
+    lexical: lexicalScore(source.families.lexical.features, draft.families.lexical.features),
+    register: source.families.register.features.primary.value === draft.families.register.features.primary.value ? 90 : 58,
+    discourse: transitionScore(source.families.discourse.features.transitionRates, draft.families.discourse.features.transitionRates),
+    rhetoricalShape: sequenceScore(source.families.rhetoricalShape.features.openingMoves, draft.families.rhetoricalShape.features.openingMoves),
+    evidence: evidenceScore(source.families.evidence.features, draft.families.evidence.features),
+    structure: sequenceScore(source.families.structure.features.openingMoves, draft.families.structure.features.openingMoves),
+  };
+}
+
+function rhythmScore(source, draft) {
+  const sentenceDelta = Math.abs(source.sentenceWords.median - draft.sentenceWords.median);
+  const paragraphDelta = Math.abs(source.paragraphWords.median - draft.paragraphWords.median);
+  return clampScore(100 - sentenceDelta * 4 - paragraphDelta * 0.6);
+}
+
+function lexicalScore(source, draft) {
+  const ratioDelta = Math.abs(source.vocabularyRichness.contentTypeTokenRatio - draft.vocabularyRichness.contentTypeTokenRatio);
+  const wordLengthDelta = Math.abs(source.wordLength.median - draft.wordLength.median);
+  return clampScore(100 - ratioDelta * 100 - wordLengthDelta * 8);
+}
+
+function transitionScore(source, draft) {
+  const keys = Array.from(new Set([...Object.keys(source), ...Object.keys(draft)]));
+  const delta = keys.reduce((sum, key) => sum + Math.abs((source[key] ?? 0) - (draft[key] ?? 0)), 0);
+  return clampScore(100 - delta * 150);
+}
+
+function sequenceScore(source, draft) {
+  if (source.length === 0 || draft.length === 0) {
+    return 100;
+  }
+  let matches = 0;
+  for (let index = 0; index < Math.min(source.length, draft.length); index += 1) {
+    if (source[index] === draft[index]) {
+      matches += 1;
+    } else if (source.includes(draft[index]) || draft.includes(source[index])) {
+      matches += 0.5;
+    }
+  }
+  return clampScore(100 * matches / Math.min(source.length, draft.length));
+}
+
+function evidenceScore(source, draft) {
+  const rateDelta = Math.max(0, source.evidenceSentenceRate - draft.evidenceSentenceRate);
+  const unsupportedDelta = Math.max(0, draft.unsupportedClaimRate - source.unsupportedClaimRate);
+  return clampScore(100 - rateDelta * 180 - unsupportedDelta * 180);
+}
+
+function reviewFindings(source, draft, scores, mode) {
+  const modeConfig = REVIEW_MODES[mode];
+  if (source.source?.confidence?.band === "weak" || !modeConfig.findingThresholds) {
+    return [];
+  }
+  const findings = [];
+  if (scores.evidence < modeConfig.findingThresholds.evidence) {
+    findings.push({
+      id: "v2.evidence-drift",
+      family: "evidence",
+      priority: "review",
+      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) {
+    findings.push({
+      id: "v2.rhythm-drift",
+      family: "rhythm",
+      priority: "consider",
+      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) {
+    findings.push({
+      id: "v2.shape-drift",
+      family: "rhetoricalShape",
+      priority: "consider",
+      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.",
+    });
+  }
+  return findings;
+}
+
+function normalizeReviewMode(mode) {
+  const normalized = String(mode ?? "balanced").toLowerCase();
+  if (!Object.hasOwn(REVIEW_MODES, normalized)) {
+    throw new Error(`Unsupported review mode: ${mode}. Expected loose, balanced, or strict.`);
+  }
+  return normalized;
+}
+
+function fitBand(distance, findings) {
+  if (findings.some((finding) => finding.priority === "review") || distance >= 35) {
+    return "drift";
+  }
+  if (findings.length > 0 || distance >= 20) {
+    return "watch";
+  }
+  return "close";
+}
+
+function displayPath(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join("/");
+  }
+  return filePath.split(path.sep).join("/");
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/src/v2/text-utils.js

@@ -0,0 +1,123 @@
+const WORD_RE = /[a-z][a-z0-9'-]*/gi;
+const ABBREVIATIONS = ["Dr.", "Mr.", "Mrs.", "Ms.", "Prof.", "Sr.", "Jr.", "e.g.", "i.e."];
+
+export const FUNCTION_WORDS = [
+  "a", "an", "and", "as", "at", "because", "but", "by", "for", "from",
+  "if", "in", "into", "is", "it", "its", "of", "on", "or", "that",
+  "the", "their", "then", "there", "this", "to", "was", "we", "with",
+  "you", "your", "i", "my", "not", "so", "before", "after", "while",
+];
+
+export const STOP_WORDS = new Set([
+  ...FUNCTION_WORDS,
+  "about", "also", "between", "can", "could", "each", "had", "has",
+  "have", "more", "one", "only", "our", "out", "over", "should",
+  "than", "they", "were", "when", "where", "which", "who", "will",
+  "would",
+]);
+
+export function normalizeText(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+export function tokenizeWords(text) {
+  return (String(text ?? "").match(WORD_RE) ?? [])
+    .map((word) => word.toLowerCase().replace(/'s$/, ""));
+}
+
+export function contentWords(text) {
+  return tokenizeWords(text).filter((word) => word.length > 2 && !STOP_WORDS.has(word));
+}
+
+export function splitSentences(text) {
+  let protectedText = String(text ?? "");
+  const replacements = new Map();
+  const protect = (pattern, prefix) => {
+    protectedText = protectedText.replace(pattern, (match) => {
+      const key = `__${prefix}_${replacements.size}__`;
+      replacements.set(key, match);
+      return key;
+    });
+  };
+
+  for (const abbreviation of ABBREVIATIONS) {
+    protectedText = protectedText.replaceAll(abbreviation, abbreviation.replaceAll(".", "§"));
+  }
+  protect(/https?:\/\/\S+/g, "URL");
+  protect(/\b[\w/-]+\.(?:js|ts|py|md|mdx|txt|html|json|yml|yaml|toml)\b/g, "PATH");
+  protect(/\b\d+(?:\.\d+)+\b/g, "VERSION");
+
+  const parts = protectedText
+    .split(/(?<=[.!?])\s+(?=["'(\[]?[A-Z0-9])/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  return parts.map((part) => {
+    let restored = part.replaceAll("§", ".");
+    for (const [key, value] of replacements.entries()) {
+      restored = restored.replaceAll(key, value);
+    }
+    return restored;
+  });
+}
+
+export function characterNgrams(text, size = 3) {
+  const compact = normalizeText(text).replace(/[^a-z0-9]+/g, " ").trim();
+  const grams = [];
+  for (let index = 0; index <= compact.length - size; index += 1) {
+    const gram = compact.slice(index, index + size);
+    if (!gram.includes(" ")) {
+      grams.push(gram);
+    }
+  }
+  return grams;
+}
+
+export function distribution(values) {
+  if (!values.length) {
+    return { count: 0, min: 0, max: 0, mean: 0, median: 0, p25: 0, p75: 0 };
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  return {
+    count: sorted.length,
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    mean: round(sorted.reduce((sum, value) => sum + value, 0) / sorted.length, 2),
+    median: percentile(sorted, 0.5),
+    p25: percentile(sorted, 0.25),
+    p75: percentile(sorted, 0.75),
+  };
+}
+
+export function topItems(values, limit = 10) {
+  const counts = new Map();
+  for (const value of values.filter(Boolean)) {
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+    .slice(0, limit)
+    .map(([value, count]) => ({ value, count }));
+}
+
+export function rate(count, total, digits = 3) {
+  return round(count / Math.max(1, total), digits);
+}
+
+export function round(value, digits = 0) {
+  const multiplier = 10 ** digits;
+  const rounded = Math.floor(value * multiplier + 0.5) / multiplier;
+  return digits === 0 ? Math.trunc(rounded) : rounded;
+}
+
+export function clampScore(value) {
+  return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+function percentile(sortedValues, ratio) {
+  const index = Math.min(
+    sortedValues.length - 1,
+    Math.max(0, Math.round((sortedValues.length - 1) * ratio)),
+  );
+  return sortedValues[index];
+}