dravoice 0.1.2 → 0.1.4

package/src/v2/profile.js

@@ -1,203 +1,342 @@
-import fs from "node:fs";
-import path from "node:path";
-import { analyzeDiscourse } from "./analyzers/discourse.js";
-import { analyzeEvidence } from "./analyzers/evidence.js";
-import { analyzeLexical } from "./analyzers/lexical.js";
-import { analyzeRegister } from "./analyzers/register.js";
-import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
-import { analyzeRhythm } from "./analyzers/rhythm.js";
-import { analyzeStructure } from "./analyzers/structure.js";
-import { loadDocuments } from "./document-model.js";
-import {
-  STYLOMETRIC_REFERENCES,
-  defaultStyleThresholds,
-  distanceByFamily,
-  percentile,
-  stabilityFromDistances,
-} from "./stylometry.js";
-
-export function learnVoicePackV2({ examplesDir, outDir }) {
-  const documents = loadDocuments({ examplesDir });
-  const profile = buildVoiceProfileV2({ documents });
-  if (outDir) {
-    writeVoicePackV2(outDir, profile);
-  }
-  return profile;
-}
-
-export function loadVoicePackV2(voiceDir) {
-  const profilePath = path.join(voiceDir, "profile.json");
-  if (!fs.existsSync(profilePath)) {
-    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
-  }
-  const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
-  if (profile.schemaVersion !== 2) {
-    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
-  }
-  return profile;
-}
-
-export function buildVoiceProfileV2({ documents }) {
-  const source = sourceSummary(documents);
-  const families = analyzeFeatureFamilies(documents);
-
-  return {
-    schemaVersion: 2,
-    generatedBy: "dravoice-v2",
-    tool: { name: "Dravoice", cli: "drav" },
-    source,
-    families,
-    guidance: guidanceFor({ source, families }),
-    calibration: {
-      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
-      tolerances: {
-        rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
-        evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
-      },
-      styleThresholds: styleThresholdsFor(documents, families),
-      minimumDraftSize: {
-        words: source.confidence.band === "weak" ? 25 : 35,
-        sentences: source.confidence.band === "weak" ? 3 : 4,
-      },
-    },
-  };
-}
-
-function analyzeFeatureFamilies(documents) {
-  return {
-    rhythm: analyzeRhythm(documents),
-    lexical: analyzeLexical(documents),
-    register: analyzeRegister(documents),
-    discourse: analyzeDiscourse(documents),
-    rhetoricalShape: analyzeRhetoricalShape(documents),
-    evidence: analyzeEvidence(documents),
-    structure: analyzeStructure(documents),
-  };
-}
-
-function styleThresholdsFor(documents, fallbackFamilies) {
-  const fallbackThresholds = defaultStyleThresholds();
-  const distancesByFamily = Object.fromEntries(Object.keys(fallbackFamilies).map((family) => [family, []]));
-
-  if (documents.length >= 2) {
-    for (let index = 0; index < documents.length; index += 1) {
-      const referenceDocuments = documents.filter((_, candidateIndex) => candidateIndex !== index);
-      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments);
-      const heldoutFamilies = analyzeFeatureFamilies([documents[index]]);
-      for (const family of Object.keys(fallbackFamilies)) {
-        distancesByFamily[family].push(distanceByFamily(
-          family,
-          referenceFamilies[family].features,
-          heldoutFamilies[family].features,
-        ));
-      }
-    }
-  }
-
-  const families = {};
-  for (const family of Object.keys(fallbackFamilies)) {
-    const observations = distancesByFamily[family];
-    const observedThreshold = observations.length > 0 ? percentile(observations, 0.9) : 0;
-    const fallback = fallbackThresholds[family].threshold;
-    families[family] = {
-      threshold: Math.max(0.01, Math.min(0.95, observedThreshold || fallback)),
-      observations: observations.length,
-      stability: stabilityFromDistances(observations),
-    };
-  }
-
-  return {
-    method: "leave-one-out-cosine-delta",
-    references: STYLOMETRIC_REFERENCES,
-    families,
-  };
-}
-
-function writeVoicePackV2(outDir, profile) {
-  fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
-  fs.writeFileSync(
-    path.join(outDir, ".dravoice.yml"),
-    [
-      "schemaVersion: 2",
-      "generatedBy: dravoice-v2",
-      `confidence: ${profile.source.confidence.band}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-}
-
-function sourceSummary(documents) {
-  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
-  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
-  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
-  return {
-    files: documents.map((document, index) => ({
-      id: `source-${index + 1}`,
-      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
-      wordCount: document.wordCount,
-      sentenceCount: document.sentences.length,
-    })),
-    documentCount: documents.length,
-    wordCount,
-    sentenceCount,
-    genres: [],
-    confidence,
-  };
-}
-
-function confidenceFor(documentCount, sentenceCount, wordCount) {
-  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
-    return { band: "deep", message: "Enough material for stricter family-level review." };
-  }
-  if (documentCount >= 5 && sentenceCount >= 30) {
-    return { band: "strong", message: "Enough examples for stable family-level review." };
-  }
-  if (documentCount >= 3 && sentenceCount >= 10) {
-    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
-  }
-  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
-}
-
-function guidanceFor({ source, families }) {
-  const primaryRegister = families.register.features.primary.value;
-  const evidenceRate = families.evidence.features.evidenceSentenceRate;
-  const sentenceMedian = families.rhythm.features.sentenceWords.median;
-  const opening = families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
-
-  const draftingRules = [
-    `Keep sentence pacing near the learned median of ${sentenceMedian} words when it fits the draft.`,
-    `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
-    evidenceRate > 0.35
-      ? "Anchor broad claims with concrete scenes, numbers, quotes, citations, or specific examples."
-      : "Do not force evidence density higher than the source corpus supports.",
-    opening
-      ? `Prefer opening moves compatible with: ${opening}.`
-      : "Start from the article's real subject rather than generic positioning.",
-  ];
-
-  return {
-    summary: [
-      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
-      `Primary register signal: ${primaryRegister}.`,
-    ],
-    draftingRules,
-    avoid: [
-      "Do not treat topic vocabulary as proof of voice fit.",
-      "Do not claim a draft is or is not the writer's true voice.",
-      "Do not invent concrete evidence to satisfy a style finding.",
-    ],
-    examples: [],
-  };
-}
-
-function toleranceFor(band, deep, strong, weak) {
-  if (band === "deep") {
-    return deep;
-  }
-  if (band === "strong") {
-    return strong;
-  }
-  return weak;
-}
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeDiscourse } from "./analyzers/discourse.js";
+import { analyzeEvidence } from "./analyzers/evidence.js";
+import { analyzeLexical } from "./analyzers/lexical.js";
+import { analyzeRegister } from "./analyzers/register.js";
+import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
+import { analyzeRhythm } from "./analyzers/rhythm.js";
+import { analyzeStructure } from "./analyzers/structure.js";
+import { loadDocuments } from "./document-model.js";
+import { readJsonFileBounded, writeUtf8FileSafely } from "./io-utils.js";
+import {
+  STYLOMETRIC_REFERENCES,
+  defaultStyleThresholds,
+  distanceByFamily,
+  percentile,
+  stabilityFromDistances,
+} from "./stylometry.js";
+
+export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [], registerMarkers }) {
+  const documents = loadDocuments({ examplesDir, excludePaths });
+  const profile = buildVoiceProfileV2({ documents, registerMarkers });
+  if (outDir) {
+    writeVoicePackV2(outDir, profile);
+  }
+  return profile;
+}
+
+export function loadVoicePackV2(voiceDir) {
+  const profilePath = path.join(voiceDir, "profile.json");
+  if (!fs.existsSync(profilePath)) {
+    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
+  }
+  const profile = readJsonFileBounded(profilePath, { label: "Dravoice profile", maxBytes: 2 * 1024 * 1024 });
+  if (profile.schemaVersion !== 2) {
+    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
+  }
+  validateVoiceProfileV2(profile, voiceDir);
+  return profile;
+}
+
+export function buildVoiceProfileV2({ documents, registerMarkers }) {
+  const source = sourceSummary(documents);
+  const families = analyzeFeatureFamilies(documents, { registerMarkers });
+  const styleThresholds = styleThresholdsFor(documents, families, { registerMarkers });
+
+  return {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2",
+    tool: { name: "Dravoice", cli: "drav" },
+    source,
+    families,
+    guidance: guidanceFor({ source, families }),
+    calibration: {
+      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
+      tolerances: {
+        rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
+        evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
+      },
+      styleThresholds,
+      familyDiagnostics: familyCalibrationDiagnostics({ source, families, styleThresholds }),
+      minimumDraftSize: {
+        words: source.confidence.band === "weak" ? 25 : 35,
+        sentences: source.confidence.band === "weak" ? 3 : 4,
+      },
+    },
+  };
+}
+
+function analyzeFeatureFamilies(documents, { registerMarkers } = {}) {
+  return {
+    rhythm: analyzeRhythm(documents),
+    lexical: analyzeLexical(documents),
+    register: analyzeRegister(documents, registerMarkers ? { markers: registerMarkers } : undefined),
+    discourse: analyzeDiscourse(documents),
+    rhetoricalShape: analyzeRhetoricalShape(documents),
+    evidence: analyzeEvidence(documents),
+    structure: analyzeStructure(documents),
+  };
+}
+
+function styleThresholdsFor(documents, fallbackFamilies, { registerMarkers } = {}) {
+  const fallbackThresholds = defaultStyleThresholds();
+  const distancesByFamily = Object.fromEntries(Object.keys(fallbackFamilies).map((family) => [family, []]));
+
+  if (documents.length >= 2) {
+    for (let index = 0; index < documents.length; index += 1) {
+      const referenceDocuments = documents.filter((_, candidateIndex) => candidateIndex !== index);
+      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments, { registerMarkers });
+      const heldoutFamilies = analyzeFeatureFamilies([documents[index]], { registerMarkers });
+      for (const family of Object.keys(fallbackFamilies)) {
+        distancesByFamily[family].push(distanceByFamily(
+          family,
+          referenceFamilies[family].features,
+          heldoutFamilies[family].features,
+        ));
+      }
+    }
+  }
+
+  if (documents.length >= 5) {
+    for (let start = 0; start < documents.length; start += 1) {
+      const heldoutIndexes = new Set([start, (start + 1) % documents.length]);
+      const referenceDocuments = documents.filter((_, index) => !heldoutIndexes.has(index));
+      const heldoutDocuments = documents.filter((_, index) => heldoutIndexes.has(index));
+      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments, { registerMarkers });
+      const heldoutFamilies = analyzeFeatureFamilies(heldoutDocuments, { registerMarkers });
+      for (const family of Object.keys(fallbackFamilies)) {
+        distancesByFamily[family].push(distanceByFamily(
+          family,
+          referenceFamilies[family].features,
+          heldoutFamilies[family].features,
+        ));
+      }
+    }
+  }
+
+  const families = {};
+  for (const family of Object.keys(fallbackFamilies)) {
+    const observations = distancesByFamily[family];
+    const observedThreshold = observations.length > 0 ? percentile(observations, 0.9) : 0;
+    const fallback = fallbackThresholds[family].threshold;
+    families[family] = {
+      threshold: Math.max(0.01, Math.min(0.95, observedThreshold || fallback)),
+      observations: observations.length,
+      stability: stabilityFromDistances(observations),
+    };
+  }
+
+  return {
+    method: documents.length >= 5
+      ? "leave-one-out-and-rotating-holdout-cosine-delta"
+      : "leave-one-out-cosine-delta",
+    references: STYLOMETRIC_REFERENCES,
+    families,
+  };
+}
+
+function writeVoicePackV2(outDir, profile) {
+  fs.mkdirSync(outDir, { recursive: true });
+  writeUtf8FileSafely(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`);
+  writeUtf8FileSafely(
+    path.join(outDir, ".dravoice.yml"),
+    [
+      "schemaVersion: 2",
+      "generatedBy: dravoice-v2",
+      `confidence: ${profile.source.confidence.band}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function validateVoiceProfileV2(profile, voiceDir) {
+  assertObject(profile.source, "profile.source", voiceDir);
+  assertObject(profile.source.confidence, "profile.source.confidence", voiceDir);
+  assertObject(profile.families, "profile.families", voiceDir);
+  for (const family of ["rhythm", "lexical", "register", "discourse", "rhetoricalShape", "evidence", "structure"]) {
+    assertObject(profile.families[family], `profile.families.${family}`, voiceDir);
+    assertObject(profile.families[family].features, `profile.families.${family}.features`, voiceDir);
+  }
+  assertObject(profile.guidance, "profile.guidance", voiceDir);
+  if (!Array.isArray(profile.guidance.summary) || !Array.isArray(profile.guidance.draftingRules) || !Array.isArray(profile.guidance.avoid)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: profile.guidance must include summary, draftingRules, and avoid arrays.`);
+  }
+  assertObject(profile.calibration, "profile.calibration", voiceDir);
+  assertObject(profile.calibration.minimumDraftSize, "profile.calibration.minimumDraftSize", voiceDir);
+  assertObject(profile.calibration.styleThresholds, "profile.calibration.styleThresholds", voiceDir);
+}
+
+function assertObject(value, field, voiceDir) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: missing ${field}.`);
+  }
+}
+
+function sourceSummary(documents) {
+  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
+  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
+  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
+  return {
+    files: documents.map((document, index) => ({
+      id: `source-${index + 1}`,
+      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
+      wordCount: document.wordCount,
+      sentenceCount: document.sentences.length,
+    })),
+    documentCount: documents.length,
+    wordCount,
+    sentenceCount,
+    genres: [],
+    confidence,
+    quality: sourceQualityFor(documents),
+  };
+}
+
+function sourceQualityFor(documents) {
+  const wordCounts = documents.map((document) => document.wordCount);
+  const sentenceCounts = documents.map((document) => document.sentences.length);
+  const fingerprints = new Map();
+  for (const document of documents) {
+    const fingerprint = documentFingerprint(document);
+    if (!fingerprint) {
+      continue;
+    }
+    fingerprints.set(fingerprint, (fingerprints.get(fingerprint) ?? 0) + 1);
+  }
+  const duplicateGroups = Array.from(fingerprints.values()).filter((count) => count > 1).length;
+  const minWords = minValue(wordCounts);
+  const maxWords = maxValue(wordCounts);
+  const warnings = [];
+  if (duplicateGroups > 0) {
+    warnings.push(`${duplicateGroups} duplicate-looking source group(s) detected; remove repeated drafts before trusting calibration.`);
+  }
+  if (documents.length >= 3 && minWords > 0 && maxWords / minWords >= 5) {
+    warnings.push(`Document length imbalance detected (${minWords}-${maxWords} words); long pieces may dominate the learned profile.`);
+  }
+  if (documents.some((document) => document.wordCount < 80)) {
+    warnings.push("One or more source files are very short; prefer representative long-form pieces.");
+  }
+  return {
+    lengthSpread: {
+      minWords,
+      maxWords,
+      minSentences: minValue(sentenceCounts),
+      maxSentences: maxValue(sentenceCounts),
+    },
+    duplicateGroups,
+    warnings,
+  };
+}
+
+function minValue(values) {
+  return values.length ? Math.min(...values) : 0;
+}
+
+function maxValue(values) {
+  return values.length ? Math.max(...values) : 0;
+}
+
+function documentFingerprint(document) {
+  return String(document.text ?? "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .replace(/[^a-z0-9 ]+/g, "")
+    .trim();
+}
+
+function familyCalibrationDiagnostics({ source, families, styleThresholds }) {
+  return Object.fromEntries(Object.keys(families).map((family) => {
+    const minimumEvidence = minimumEvidenceFor(family, source, families[family]);
+    const threshold = styleThresholds.families[family] ?? {};
+    return [family, {
+      confidence: families[family].confidence,
+      threshold: threshold.threshold ?? 0,
+      observations: threshold.observations ?? 0,
+      stability: threshold.stability ?? 0.45,
+      minimumEvidence,
+      usableForFindings: source.confidence.band !== "weak" &&
+        minimumEvidence.documentsMet &&
+        minimumEvidence.sentencesMet &&
+        minimumEvidence.wordsMet &&
+        (threshold.stability ?? 0.45) >= 0.35,
+    }];
+  }));
+}
+
+function minimumEvidenceFor(family, source, familyData) {
+  const requirements = {
+    rhythm: { documents: 1, sentences: 8, words: 80 },
+    lexical: { documents: 1, sentences: 4, words: 120 },
+    register: { documents: 3, sentences: 8, words: 120 },
+    discourse: { documents: 1, sentences: 12, words: 120 },
+    rhetoricalShape: { documents: 1, sentences: 12, words: 120 },
+    evidence: { documents: 1, sentences: 12, words: 120 },
+    structure: { documents: 3, sentences: 8, words: 120 },
+  }[family] ?? { documents: 1, sentences: 1, words: 1 };
+  const wordCount = familyData.features?.wordCount ?? source.wordCount;
+  const sentenceCount = familyData.features?.sentenceCount ?? source.sentenceCount;
+  return {
+    requiredDocuments: requirements.documents,
+    requiredSentences: requirements.sentences,
+    requiredWords: requirements.words,
+    documentsMet: source.documentCount >= requirements.documents,
+    sentencesMet: sentenceCount >= requirements.sentences,
+    wordsMet: wordCount >= requirements.words,
+  };
+}
+
+function confidenceFor(documentCount, sentenceCount, wordCount) {
+  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
+    return { band: "deep", message: "Enough material for stricter family-level review." };
+  }
+  if (documentCount >= 5 && sentenceCount >= 30) {
+    return { band: "strong", message: "Enough examples for stable family-level review." };
+  }
+  if (documentCount >= 3 && sentenceCount >= 10) {
+    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
+  }
+  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
+}
+
+function guidanceFor({ source, families }) {
+  const primaryRegister = families.register.features.primary.value;
+  const evidenceRate = families.evidence.features.evidenceSentenceRate;
+  const sentenceMedian = families.rhythm.features.sentenceWords.median;
+  const opening = families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
+
+  const draftingRules = [
+    `Keep sentence pacing near the learned median of ${sentenceMedian} words when it fits the draft.`,
+    `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
+    evidenceRate > 0.35
+      ? "Anchor broad claims with concrete scenes, numbers, quotes, citations, or specific examples."
+      : "Do not force evidence density higher than the source corpus supports.",
+    opening
+      ? `Prefer opening moves compatible with: ${opening}.`
+      : "Start from the article's real subject rather than generic positioning.",
+  ];
+
+  return {
+    summary: [
+      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
+      `Primary register signal: ${primaryRegister}.`,
+    ],
+    draftingRules,
+    avoid: [
+      "Do not treat topic vocabulary as proof of voice fit.",
+      "Do not claim a draft is or is not the writer's true voice.",
+      "Do not invent concrete evidence to satisfy a style finding.",
+    ],
+    examples: [],
+  };
+}
+
+function toleranceFor(band, deep, strong, weak) {
+  if (band === "deep") {
+    return deep;
+  }
+  if (band === "strong") {
+    return strong;
+  }
+  return weak;
+}