dravoice 0.1.0 → 0.1.1

package/src/v2/revise-plan.js

@@ -0,0 +1,340 @@
+import fs from "node:fs";
+import path from "node:path";
+import { evidenceTypes, isAbstractClaim } from "./analyzers/evidence.js";
+import { transitionLabel } from "./analyzers/discourse.js";
+import { moveFor } from "./analyzers/rhetorical-shape.js";
+import { parseDocument } from "./document-model.js";
+import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
+import { clampScore, round } from "./text-utils.js";
+import {
+  STYLOMETRIC_REFERENCES,
+  calibratedFamilyDrift,
+  defaultStyleThresholds,
+  distanceByFamily,
+  familyScoreFromDistance,
+  familyWeight,
+} from "./stylometry.js";
+
+const MAX_ACTIONS = 8;
+
+const EDITABILITY = {
+  evidence: 1.00,
+  rhetoricalShape: 0.90,
+  rhythm: 0.80,
+  discourse: 0.75,
+  lexical: 0.55,
+  register: 0.50,
+  structure: 0.60,
+};
+
+export function revisePlanDraftV2({ file, voice, cwd = process.cwd(), maxActions = MAX_ACTIONS }) {
+  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] });
+  const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
+  const actions = rankedActions({
+    sourceProfile,
+    draftDocument,
+    familyDiagnostics,
+    maxActions,
+  });
+
+  return {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2-revise-plan",
+    file: displayPath(filePath, cwd),
+    method: {
+      name: "calibrated-stylometric-revision-plan",
+      references: STYLOMETRIC_REFERENCES,
+      caution: "Revision planning only; not AI detection and not proof of authorship.",
+    },
+    summary: {
+      corpusConfidence: sourceProfile.source.confidence,
+      distance: Math.round(Object.values(familyDiagnostics).reduce((sum, item) => sum + (100 - item.score), 0) / Object.keys(familyDiagnostics).length),
+      familyScores: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.score])),
+      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])),
+    },
+    actions,
+  };
+}
+
+export function renderRevisePlanV2(plan) {
+  const lines = [
+    "# Revision Plan",
+    "",
+    "Voice revision guidance, not AI detection.",
+    `Method: calibrated stylometric distance using Burrows Delta, Cosine Delta, function-word stylometry, and discourse features.`,
+    "",
+    plan.file,
+    `Corpus confidence: ${capitalize(plan.summary.corpusConfidence.band)} - ${plan.summary.corpusConfidence.message}`,
+    `Style distance: ${plan.summary.distance}`,
+    "Family scores:",
+  ];
+
+  for (const [family, score] of Object.entries(plan.summary.familyScores)) {
+    const drift = plan.summary.familyDrift[family];
+    lines.push(`- ${family}: ${score} (drift ${drift})`);
+  }
+
+  lines.push("");
+  if (plan.actions.length === 0) {
+    lines.push("No calibrated revision actions exceeded the writer's normal style variance.");
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  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("");
+  return lines.join("\n");
+}
+
+function familyDiagnosticsFor(sourceProfile, draftProfile) {
+  const thresholds = thresholdMap(sourceProfile);
+  return Object.fromEntries(Object.keys(sourceProfile.families).map((family) => {
+    const distance = distanceByFamily(
+      family,
+      sourceProfile.families[family].features,
+      draftProfile.families[family].features,
+    );
+    const threshold = thresholds[family]?.threshold ?? defaultStyleThresholds()[family]?.threshold ?? 0.4;
+    return [family, {
+      distance,
+      threshold,
+      drift: calibratedFamilyDrift(distance, threshold),
+      score: familyScoreFromDistance(distance, threshold),
+    }];
+  }));
+}
+
+function thresholdMap(sourceProfile) {
+  return sourceProfile.calibration?.styleThresholds?.families ?? defaultStyleThresholds();
+}
+
+function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, maxActions }) {
+  const confidence = confidenceWeight(sourceProfile.source.confidence.band);
+  const actions = [
+    ...evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+  ].filter((action) => action.actionScore > 0);
+
+  return actions
+    .sort((left, right) => right.actionScore - left.actionScore || left.id.localeCompare(right.id))
+    .slice(0, maxActions)
+    .map((action, index) => ({ ...action, rank: index + 1 }));
+}
+
+function evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "evidence";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const sourceRate = sourceProfile.families.evidence.features.evidenceSentenceRate;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const types = evidenceTypes(sentence.text);
+    const claim = isAbstractClaim(sentence.text);
+    const localMismatch = claim && types.length === 0
+      ? 1
+      : types.length === 0 && sourceRate >= 0.25
+        ? 0.65
+        : 0;
+    if (localMismatch <= 0) {
+      return [];
+    }
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: claim ? "review" : "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      localMismatch,
+      why: "This sentence carries a broad claim pattern without the concrete support rate learned from the source corpus.",
+      reviseBy: "Add concrete support: a scene, quote, number, date, citation, URL, sensory detail, or specific example the writer can verify.",
+    })];
+  });
+}
+
+function rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "rhythm";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const source = sourceProfile.families.rhythm.features.sentenceWords;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const wordCount = sentence.tokens.length;
+    const nearestBound = wordCount < source.p25 ? source.p25 : wordCount > source.p75 ? source.p75 : wordCount;
+    const localMismatch = Math.min(1, Math.abs(wordCount - nearestBound) / Math.max(1, source.median));
+    if (localMismatch <= 0) {
+      return [];
+    }
+    const direction = wordCount > source.p75 ? "longer" : "shorter";
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      localMismatch,
+      why: `This sentence is ${direction} than the learned sentence-length band (${source.p25}-${source.p75} words).`,
+      reviseBy: "Adjust sentence pacing toward the learned range by splitting, tightening, or pairing it with a deliberately shorter sentence.",
+    })];
+  });
+}
+
+function shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "rhetoricalShape";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0 || draftDocument.sentences.length === 0) {
+    return [];
+  }
+  const sourceOpening = sourceProfile.families.rhetoricalShape.features.openingMoves.slice(0, 3);
+  const draftOpening = draftDocument.sentences.slice(0, 3).map((sentence) => moveFor(sentence.text));
+  const mismatches = draftOpening.filter((move, index) => move !== sourceOpening[index]).length;
+  const localMismatch = mismatches / Math.max(1, Math.min(3, draftOpening.length));
+  if (localMismatch <= 0) {
+    return [];
+  }
+  return [makeAction({
+    family,
+    ordinal: 1,
+    priority: "consider",
+    unit: { type: "opening", line: draftDocument.sentences[0].line },
+    confidence,
+    drift,
+    localMismatch,
+    why: `Draft opening moves (${draftOpening.join(" -> ")}) drift from the learned opening pattern (${sourceOpening.join(" -> ")}).`,
+    reviseBy: "Rework the opening toward a compatible scene, claim, contrast, reflection, or evidence sequence without inventing new facts.",
+  })];
+}
+
+function discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "discourse";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const sourceTransitions = sourceProfile.families.discourse.features.transitionRates;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const label = transitionLabel(sentence.text);
+    if (label === "plain") {
+      return [];
+    }
+    const sourceRate = sourceTransitions[label] ?? 0;
+    const draftRate = draftDocument.sentences.filter((candidate) => transitionLabel(candidate.text) === label).length / Math.max(1, draftDocument.sentences.length);
+    const localMismatch = Math.max(0, draftRate - sourceRate);
+    if (localMismatch <= 0.1) {
+      return [];
+    }
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      localMismatch: Math.min(1, localMismatch),
+      why: `The draft overuses ${label} transitions compared with the source corpus.`,
+      reviseBy: "Vary the sentence turn: replace a repeated transition with a callback, concrete example, or direct continuation where it fits.",
+    })];
+  });
+}
+
+function documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const result = [];
+  for (const family of ["lexical", "register", "structure"]) {
+    const drift = familyDiagnostics[family]?.drift ?? 0;
+    if (drift <= 0) {
+      continue;
+    }
+    result.push(makeAction({
+      family,
+      ordinal: 1,
+      priority: "consider",
+      unit: { type: "document", line: draftDocument.sentences[0]?.line ?? 1 },
+      confidence,
+      drift,
+      localMismatch: 0.7,
+      why: documentLevelWhy(sourceProfile, family),
+      reviseBy: documentLevelReviseBy(family),
+    }));
+  }
+  return result;
+}
+
+function documentLevelWhy(sourceProfile, family) {
+  if (family === "lexical") {
+    return "Function words, character trigrams, punctuation, or word-length habits drift from the calibrated source profile.";
+  }
+  if (family === "register") {
+    return `The draft register differs from the learned primary register (${sourceProfile.families.register.features.primary.value}).`;
+  }
+  return "The document-level opening structure drifts from the source corpus.";
+}
+
+function documentLevelReviseBy(family) {
+  if (family === "lexical") {
+    return "Revise diction and punctuation only where it improves the article; avoid topic-word stuffing or random imperfections.";
+  }
+  if (family === "register") {
+    return "Bring the paragraph stance closer to the learned genre mix without pretending to be someone else.";
+  }
+  return "Reorder the first section so the piece starts with a structure the source corpus actually uses.";
+}
+
+function makeAction({ family, ordinal, priority, unit, confidence, drift, localMismatch, why, reviseBy }) {
+  return {
+    id: `v2.revise-plan.${family}.${ordinal}`,
+    family,
+    priority,
+    unit,
+    actionScore: clampScore(100 * confidence * familyWeight(family) * (EDITABILITY[family] ?? 0.6) * drift * localMismatch),
+    localMismatch: round(localMismatch, 3),
+    why,
+    reviseBy,
+  };
+}
+
+function confidenceWeight(band) {
+  if (band === "deep") {
+    return 1;
+  }
+  if (band === "strong") {
+    return 0.9;
+  }
+  if (band === "usable") {
+    return 0.75;
+  }
+  return 0.45;
+}
+
+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/stylometry.js

@@ -0,0 +1,236 @@
+import { clampScore, round } from "./text-utils.js";
+
+export const STYLOMETRIC_REFERENCES = [
+  "Burrows Delta (Burrows, 2002)",
+  "Cosine Delta (Smith & Aldridge, 2011)",
+  "Function-word stylometry (Kestemont, 2014)",
+  "Authorship-attribution feature families (Stamatatos, 2009)",
+  "Cohesion and discourse measures inspired by Coh-Metrix (Graesser et al., 2004)",
+];
+
+const DEFAULT_THRESHOLDS = {
+  rhythm: 0.36,
+  lexical: 0.32,
+  register: 0.45,
+  discourse: 0.28,
+  rhetoricalShape: 0.42,
+  evidence: 0.30,
+  structure: 0.42,
+};
+
+const FAMILY_WEIGHTS = {
+  rhythm: 0.75,
+  lexical: 0.85,
+  register: 0.50,
+  discourse: 0.70,
+  rhetoricalShape: 0.70,
+  evidence: 0.85,
+  structure: 0.65,
+};
+
+export function defaultStyleThresholds() {
+  return Object.fromEntries(Object.entries(DEFAULT_THRESHOLDS).map(([family, threshold]) => [
+    family,
+    { threshold, observations: 0 },
+  ]));
+}
+
+export function familyWeight(family) {
+  return FAMILY_WEIGHTS[family] ?? 0.6;
+}
+
+export function distanceByFamily(family, sourceFeatures, draftFeatures) {
+  if (family === "rhythm") {
+    return rhythmDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "lexical") {
+    return lexicalDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "register") {
+    return registerDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "discourse") {
+    return discourseDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "rhetoricalShape") {
+    return shapeDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "evidence") {
+    return evidenceDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "structure") {
+    return shapeDistance(sourceFeatures, draftFeatures);
+  }
+  return 0;
+}
+
+export function familyScoreFromDistance(distance, threshold) {
+  const basis = Math.max(0.01, threshold * 2);
+  return clampScore(100 - (distance / basis) * 100);
+}
+
+export function calibratedFamilyDrift(distance, threshold) {
+  return round(Math.max(0, distance - threshold) / Math.max(0.01, threshold), 3);
+}
+
+export function percentile(values, ratio) {
+  const sorted = values.filter((value) => Number.isFinite(value)).sort((left, right) => left - right);
+  if (sorted.length === 0) {
+    return 0;
+  }
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((sorted.length - 1) * ratio)));
+  return sorted[index];
+}
+
+function rhythmDistance(source, draft) {
+  return weightedMean([
+    [distributionDelta(source.sentenceWords, draft.sentenceWords), 0.40],
+    [distributionDelta(source.paragraphWords, draft.paragraphWords), 0.32],
+    [distributionDelta(source.paragraphSentences, draft.paragraphSentences), 0.16],
+    [Math.abs((source.listDensity ?? 0) - (draft.listDensity ?? 0)), 0.06],
+    [Math.abs((source.quoteDensity ?? 0) - (draft.quoteDensity ?? 0)), 0.06],
+  ]);
+}
+
+function lexicalDistance(source, draft) {
+  return weightedMean([
+    [topItemDistance(source.functionWords, draft.functionWords), 1.00],
+    [topItemDistance(source.characterTrigrams, draft.characterTrigrams), 0.85],
+    [punctuationDistance(source.punctuation, draft.punctuation), 0.85],
+    [Math.abs((source.vocabularyRichness?.contentTypeTokenRatio ?? 0) - (draft.vocabularyRichness?.contentTypeTokenRatio ?? 0)), 0.25],
+    [distributionDelta(source.wordLength, draft.wordLength), 0.40],
+  ]);
+}
+
+function registerDistance(source, draft) {
+  const primaryDelta = source.primary?.value === draft.primary?.value ? 0 : 0.65;
+  return weightedMean([
+    [primaryDelta, 0.8],
+    [topItemDistance(source.scores, draft.scores), 0.2],
+  ]);
+}
+
+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.75],
+    [callbackDelta, 0.25],
+  ]);
+}
+
+function evidenceDistance(source, draft) {
+  return weightedMean([
+    [Math.abs((source.evidenceSentenceRate ?? 0) - (draft.evidenceSentenceRate ?? 0)), 0.36],
+    [Math.abs((source.claimSentenceRate ?? 0) - (draft.claimSentenceRate ?? 0)), 0.18],
+    [Math.max(0, (draft.unsupportedClaimRate ?? 0) - (source.unsupportedClaimRate ?? 0)), 0.26],
+    [topItemDistance(source.evidenceTypes, draft.evidenceTypes), 0.20],
+  ]);
+}
+
+function shapeDistance(source, draft) {
+  return weightedMean([
+    [sequenceDistance(source.openingMoves, draft.openingMoves), 0.55],
+    [topItemDistance(source.moveRates, draft.moveRates), 0.25],
+    [topItemDistance(source.commonSequences, draft.commonSequences), 0.20],
+  ]);
+}
+
+function distributionDelta(source, draft) {
+  if (!source || !draft) {
+    return 0;
+  }
+  return weightedMean([
+    [relativeDelta(source.median, draft.median), 0.45],
+    [relativeDelta(source.p25, draft.p25), 0.20],
+    [relativeDelta(source.p75, draft.p75), 0.20],
+    [relativeDelta(source.mean, draft.mean), 0.15],
+  ]);
+}
+
+function punctuationDistance(source = {}, draft = {}) {
+  return rateMapDistance(source, draft);
+}
+
+function rateMapDistance(source = {}, draft = {}) {
+  const keys = Array.from(new Set([...Object.keys(source), ...Object.keys(draft)]));
+  if (keys.length === 0) {
+    return 0;
+  }
+  return keys.reduce((sum, key) => sum + Math.abs((source[key] ?? 0) - (draft[key] ?? 0)), 0) / keys.length;
+}
+
+function topItemDistance(sourceItems = [], draftItems = []) {
+  const source = normalizedItemMap(sourceItems);
+  const draft = normalizedItemMap(draftItems);
+  const delta = rateMapDistance(source, draft);
+  const cosine = cosineDistance(source, draft);
+  return weightedMean([
+    [delta, 0.45],
+    [cosine, 0.55],
+  ]);
+}
+
+function normalizedItemMap(items) {
+  const weightedItems = items.map((item) => ({
+    value: item.value,
+    weight: item.count ?? item.score ?? 0,
+  }));
+  const total = weightedItems.reduce((sum, item) => sum + item.weight, 0);
+  return Object.fromEntries(weightedItems.map((item) => [item.value, item.weight / Math.max(1, total)]));
+}
+
+function cosineDistance(left, right) {
+  const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)]));
+  if (keys.length === 0) {
+    return 0;
+  }
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (const key of keys) {
+    const leftValue = left[key] ?? 0;
+    const rightValue = right[key] ?? 0;
+    dot += leftValue * rightValue;
+    leftNorm += leftValue ** 2;
+    rightNorm += rightValue ** 2;
+  }
+  if (leftNorm === 0 && rightNorm === 0) {
+    return 0;
+  }
+  if (leftNorm === 0 || rightNorm === 0) {
+    return 1;
+  }
+  return Math.max(0, Math.min(1, 1 - dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm))));
+}
+
+function sequenceDistance(source = [], draft = []) {
+  if (source.length === 0 && draft.length === 0) {
+    return 0;
+  }
+  if (source.length === 0 || draft.length === 0) {
+    return 1;
+  }
+  const limit = Math.min(source.length, draft.length);
+  let matches = 0;
+  for (let index = 0; index < limit; index += 1) {
+    if (source[index] === draft[index]) {
+      matches += 1;
+    } else if (source.includes(draft[index]) || draft.includes(source[index])) {
+      matches += 0.5;
+    }
+  }
+  return 1 - matches / limit;
+}
+
+function relativeDelta(sourceValue, draftValue) {
+  return Math.abs((sourceValue ?? 0) - (draftValue ?? 0)) / Math.max(1, sourceValue ?? 0);
+}
+
+function weightedMean(weightedValues) {
+  const totalWeight = weightedValues.reduce((sum, [, weight]) => sum + weight, 0);
+  if (totalWeight === 0) {
+    return 0;
+  }
+  return round(weightedValues.reduce((sum, [value, weight]) => sum + value * weight, 0) / totalWeight, 3);
+}