dravoice 0.1.2 → 0.1.3

package/src/v2/prompt.js

@@ -1,64 +1,65 @@
-import fs from "node:fs";
-import path from "node:path";
-import { loadVoicePackV2 } from "./profile.js";
-
-export function voicePromptPackV2({ voice, format = "agents", outPath }) {
-  const profile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
-  if (format !== "agents" && format !== "claude" && format !== "system") {
-    throw new Error(`Unsupported prompt format: ${format}`);
-  }
-  const rendered = renderPrompt(profile, format);
-  if (outPath) {
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, rendered, "utf8");
-  }
-  return rendered;
-}
-
-function renderPrompt(profile, format) {
-  const header = {
-    agents: "# Dravoice V2 Writing Guidance",
-    claude: "# CLAUDE.md guidance for Dravoice V2",
-    system: "System writing guidance: Dravoice V2",
-  }[format];
-  const preface = {
-    agents: "Use this as local, inspectable drafting guidance from the writer's own corpus. It is not an AI detector or a license to imitate a third party.",
-    claude: "Use these project-local voice notes when drafting or reviewing prose for this repository. Treat them as guidance, not identity proof.",
-    system: "Follow these local voice constraints when writing prose. Do not expose private source text or claim authorship identity from them.",
-  }[format];
-  const lines = [
-    header,
-    "",
-    preface,
-    "",
-    "## Summary",
-    "",
-    ...profile.guidance.summary.map((item) => `- ${item}`),
-    "",
-    "## Feature Families",
-    "",
-  ];
-
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${family.confidence} confidence; ${family.revisionHandles[0]}`);
-  }
-
-  lines.push("", "## Drafting Rules", "");
-  for (const rule of profile.guidance.draftingRules) {
-    lines.push(`- ${rule}`);
-  }
-
-  lines.push("", "## Avoid", "");
-  for (const item of profile.guidance.avoid) {
-    lines.push(`- ${item}`);
-  }
-
-  if (profile.guidance.examples.length) {
-    lines.push("", "## Source-Backed Examples", "");
-    for (const example of profile.guidance.examples) {
-      lines.push(`- ${example}`);
-    }
-  }
-
-  return `${lines.join("\n")}\n`;
-}
+import fs from "node:fs";
+import path from "node:path";
+import { writeUtf8FileSafely } from "./io-utils.js";
+import { loadVoicePackV2 } from "./profile.js";
+
+export function voicePromptPackV2({ voice, format = "agents", outPath }) {
+  const profile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
+  if (format !== "agents" && format !== "claude" && format !== "system") {
+    throw new Error(`Unsupported prompt format: ${format}`);
+  }
+  const rendered = renderPrompt(profile, format);
+  if (outPath) {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    writeUtf8FileSafely(outPath, rendered);
+  }
+  return rendered;
+}
+
+function renderPrompt(profile, format) {
+  const header = {
+    agents: "# Dravoice V2 Writing Guidance",
+    claude: "# CLAUDE.md guidance for Dravoice V2",
+    system: "System writing guidance: Dravoice V2",
+  }[format];
+  const preface = {
+    agents: "Use this as local, inspectable drafting guidance from the writer's own corpus. It is not an AI detector or a license to imitate a third party.",
+    claude: "Use these project-local voice notes when drafting or reviewing prose for this repository. Treat them as guidance, not identity proof.",
+    system: "Follow these local voice constraints when writing prose. Do not expose private source text or claim authorship identity from them.",
+  }[format];
+  const lines = [
+    header,
+    "",
+    preface,
+    "",
+    "## Summary",
+    "",
+    ...profile.guidance.summary.map((item) => `- ${item}`),
+    "",
+    "## Feature Families",
+    "",
+  ];
+
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${family.confidence} confidence; ${family.revisionHandles[0]}`);
+  }
+
+  lines.push("", "## Drafting Rules", "");
+  for (const rule of profile.guidance.draftingRules) {
+    lines.push(`- ${rule}`);
+  }
+
+  lines.push("", "## Avoid", "");
+  for (const item of profile.guidance.avoid) {
+    lines.push(`- ${item}`);
+  }
+
+  if (profile.guidance.examples.length) {
+    lines.push("", "## Source-Backed Examples", "");
+    for (const example of profile.guidance.examples) {
+      lines.push(`- ${example}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/v2/review.js

@@ -1,173 +1,177 @@
-import fs from "node:fs";
-import path from "node:path";
-import { parseDocument } from "./document-model.js";
-import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
-import { familyDiagnosticsFor, styleDistanceFromDiagnostics } from "./stylometry.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 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 fit = {
-    band: fitBand(distance, findings, familyDiagnostics),
-    distance,
-  };
-
-  return {
-    schemaVersion: 2,
-    file: displayPath(filePath, cwd),
-    summary: {
-      mode: reviewMode,
-      fit,
-      familyScores,
-      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])),
-      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 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, familyDiagnostics) {
-  const maxDrift = Math.max(0, ...Object.values(familyDiagnostics).map((item) => item.drift));
-  if (findings.some((finding) => finding.priority === "review") || distance >= 35 || maxDrift >= 1.25) {
-    return "drift";
-  }
-  if (findings.length > 0 || distance >= 20 || maxDrift > 0) {
-    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);
-}
+import path from "node:path";
+import { parseDocument } from "./document-model.js";
+import { readUtf8FileBounded } from "./io-utils.js";
+import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
+import { familyDiagnosticsFor, styleDistanceFromDiagnostics } from "./stylometry.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 = resolvePath(cwd, file);
+  const draftDocument = parseDocument({
+    filePath,
+    rootDir: cwd,
+    contents: readUtf8FileBounded(filePath, { label: "Draft file", maxBytes: 2 * 1024 * 1024 }),
+  });
+  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 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 fit = {
+    band: fitBand(distance, findings, familyDiagnostics),
+    distance,
+  };
+
+  return {
+    schemaVersion: 2,
+    file: displayPath(filePath, cwd),
+    summary: {
+      mode: reviewMode,
+      fit,
+      familyScores,
+      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])),
+      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 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, familyDiagnostics) {
+  const maxDrift = Math.max(0, ...Object.values(familyDiagnostics).map((item) => item.drift));
+  if (findings.some((finding) => finding.priority === "review") || distance >= 35 || maxDrift >= 1.25) {
+    return "drift";
+  }
+  if (findings.length > 0 || distance >= 20 || maxDrift > 0) {
+    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 resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}