dravoice 0.1.3 → 0.1.4

package/src/v2/doctor.js

@@ -0,0 +1,308 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_MAX_FILE_BYTES,
+  DEFAULT_MAX_FILES,
+  DEFAULT_MAX_TOTAL_BYTES,
+  VOICE_EXTENSIONS,
+  VOICE_SKIP_DIRS,
+  parseDocument,
+} from "./document-model.js";
+import { buildVoiceProfileV2 } from "./profile.js";
+
+export function diagnoseVoiceCorpusV2({ examplesDir, cwd = process.cwd() }) {
+  const requestedExamples = examplesDir ?? "./articles";
+  const resolvedExamples = resolvePath(cwd, requestedExamples);
+  const displayedExamples = path.isAbsolute(requestedExamples)
+    ? displayPath(resolvedExamples, cwd)
+    : displayPathForCommand(requestedExamples);
+  const baseResult = {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2-doctor",
+    examples: displayedExamples,
+    status: "needs-work",
+    exitCode: 1,
+    summary: emptySummary(),
+    files: [],
+    unsupportedFiles: [],
+    recommendations: [],
+  };
+
+  if (!fs.existsSync(resolvedExamples)) {
+    return {
+      ...baseResult,
+      recommendations: [
+        "Examples directory is missing.",
+        "Run mkdir -p articles, then copy at least 3 representative .md, .mdx, or .txt pieces into it.",
+        `If your writing lives elsewhere, run drav doctor --examples ${displayPathForCommand(requestedExamples) === "./articles" ? "~/path/to/writing" : displayPathForCommand(requestedExamples)}.`,
+      ],
+    };
+  }
+
+  if (!fs.statSync(resolvedExamples).isDirectory()) {
+    return {
+      ...baseResult,
+      recommendations: [
+        "Examples path is not a directory.",
+        "Point --examples at a folder containing representative .md, .mdx, or .txt pieces.",
+      ],
+    };
+  }
+
+  const discovered = discoverCorpusFiles(resolvedExamples);
+  const validDocuments = [];
+  const files = [];
+  let totalBytes = 0;
+
+  discovered.supportedFiles.forEach((filePath, index) => {
+    const relative = displayPath(filePath, resolvedExamples);
+    const extension = path.extname(filePath).toLowerCase();
+    const record = { path: relative, extension, wordCount: 0, sentenceCount: 0 };
+
+    try {
+      if (index >= DEFAULT_MAX_FILES) {
+        throw new Error(`Corpus contains more than ${DEFAULT_MAX_FILES} voice file(s) allowed.`);
+      }
+      const stats = fs.statSync(filePath);
+      if (stats.size > DEFAULT_MAX_FILE_BYTES) {
+        throw new Error(`Voice file ${relative} exceeds the ${DEFAULT_MAX_FILE_BYTES} byte limit.`);
+      }
+      totalBytes += stats.size;
+      if (totalBytes > DEFAULT_MAX_TOTAL_BYTES) {
+        throw new Error(`Voice corpus exceeds the ${DEFAULT_MAX_TOTAL_BYTES} byte total limit.`);
+      }
+      const contents = fs.readFileSync(filePath, "utf8");
+      if (contents.includes("\0")) {
+        throw new Error(`Voice file ${relative} looks like binary-looking text and cannot be analyzed.`);
+      }
+      const document = parseDocument({ filePath, rootDir: resolvedExamples, contents });
+      record.wordCount = document.wordCount;
+      record.sentenceCount = document.sentences.length;
+      validDocuments.push(document);
+    } catch (error) {
+      record.issue = error.message;
+    }
+
+    files.push(record);
+  });
+
+  const summary = summaryFor(validDocuments);
+  const unsupportedFiles = discovered.unsupportedFiles.map((filePath) => ({
+    path: displayPath(filePath, resolvedExamples),
+    extension: path.extname(filePath).toLowerCase() || null,
+  }));
+  const status = statusFor({ summary, files, supportedCount: discovered.supportedFiles.length });
+
+  return {
+    ...baseResult,
+    status,
+    exitCode: status === "ready" ? 0 : 1,
+    summary,
+    files,
+    unsupportedFiles,
+    recommendations: recommendationsFor({
+      status,
+      summary,
+      files,
+      unsupportedFiles,
+      examples: baseResult.examples,
+    }),
+  };
+}
+
+export function renderCorpusDoctorV2(result) {
+  const lines = [
+    "# Corpus Doctor",
+    "",
+    `Examples: ${result.examples}`,
+    `Status: ${result.status}`,
+    `Documents: ${result.summary.documentCount}`,
+    `Words: ${result.summary.wordCount}`,
+    `Sentences: ${result.summary.sentenceCount}`,
+    `Confidence: ${result.summary.confidence.band} - ${result.summary.confidence.message}`,
+    `Supported files: ${result.files.length}`,
+    `Unsupported files: ${result.unsupportedFiles.length}`,
+    "",
+  ];
+
+  const issueFiles = result.files.filter((file) => file.issue);
+  if (issueFiles.length > 0) {
+    lines.push("File issues:");
+    issueFiles.slice(0, 8).forEach((file) => {
+      lines.push(`- ${file.path}: ${file.issue}`);
+    });
+    if (issueFiles.length > 8) {
+      lines.push(`- ...and ${issueFiles.length - 8} more`);
+    }
+    lines.push("");
+  }
+
+  if (result.unsupportedFiles.length > 0) {
+    lines.push("Unsupported files:");
+    result.unsupportedFiles.slice(0, 8).forEach((file) => {
+      lines.push(`- ${file.path}`);
+    });
+    if (result.unsupportedFiles.length > 8) {
+      lines.push(`- ...and ${result.unsupportedFiles.length - 8} more`);
+    }
+    lines.push("");
+  }
+
+  if (result.summary.quality?.warnings?.length) {
+    lines.push("Corpus quality warnings:");
+    result.summary.quality.warnings.forEach((warning) => {
+      lines.push(`- ${warning}`);
+    });
+    lines.push("");
+  }
+
+  lines.push("Recommendations:");
+  result.recommendations.forEach((item) => {
+    lines.push(`- ${item}`);
+  });
+  lines.push("");
+  lines.push(`Next: ${nextStepFor(result)}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+function discoverCorpusFiles(rootDir) {
+  const supportedFiles = [];
+  const unsupportedFiles = [];
+  const stack = [rootDir];
+
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    const directories = [];
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!VOICE_SKIP_DIRS.has(entry.name)) {
+          directories.push(fullPath);
+        }
+      } else if (entry.isFile()) {
+        if (VOICE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+          supportedFiles.push(fullPath);
+        } else {
+          unsupportedFiles.push(fullPath);
+        }
+      }
+    }
+    stack.push(...directories.reverse());
+  }
+
+  return {
+    supportedFiles: supportedFiles.sort((left, right) => left.localeCompare(right)),
+    unsupportedFiles: unsupportedFiles.sort((left, right) => left.localeCompare(right)),
+  };
+}
+
+function summaryFor(documents) {
+  if (documents.length === 0) {
+    return emptySummary();
+  }
+  const source = buildVoiceProfileV2({ documents }).source;
+  return {
+    documentCount: source.documentCount,
+    wordCount: source.wordCount,
+    sentenceCount: source.sentenceCount,
+    confidence: source.confidence,
+    quality: source.quality,
+  };
+}
+
+function emptySummary() {
+  return {
+    documentCount: 0,
+    wordCount: 0,
+    sentenceCount: 0,
+    confidence: {
+      band: "weak",
+      message: "No usable source documents were found.",
+    },
+    quality: {
+      lengthSpread: { minWords: 0, maxWords: 0, minSentences: 0, maxSentences: 0 },
+      duplicateGroups: 0,
+      warnings: [],
+    },
+  };
+}
+
+function statusFor({ summary, files, supportedCount }) {
+  const issueCount = files.filter((file) => file.issue).length;
+  if (supportedCount === 0 || summary.documentCount === 0) {
+    return "needs-work";
+  }
+  if (issueCount > 0) {
+    return "needs-work";
+  }
+  if (summary.documentCount >= 3 && summary.sentenceCount >= 10) {
+    return "ready";
+  }
+  return "weak";
+}
+
+function recommendationsFor({ status, summary, files, unsupportedFiles, examples }) {
+  const recommendations = [];
+  const issueCount = files.filter((file) => file.issue).length;
+
+  if (status === "ready") {
+    recommendations.push("Corpus is ready for cautious profile learning.");
+    if (summary.quality?.warnings?.length) {
+      recommendations.push("Review corpus quality warnings before trusting strict calibration.");
+    }
+    recommendations.push(`Run drav init --examples ${examples}.`);
+    return recommendations;
+  }
+
+  if (files.length === 0) {
+    recommendations.push("Convert or copy your writing into Markdown, MDX, or plain text.");
+  }
+
+  if (summary.documentCount < 3) {
+    const remaining = 3 - summary.documentCount;
+    recommendations.push(`Add at least ${remaining} more representative long-form piece(s).`);
+  }
+
+  if (summary.sentenceCount < 10) {
+    recommendations.push("Use longer source pieces; Dravoice needs at least 10 total sentences for a ready corpus.");
+  }
+
+  if (issueCount > 0) {
+    recommendations.push("Fix or remove supported files with issues, then rerun drav doctor.");
+  }
+
+  if (unsupportedFiles.length > 0) {
+    recommendations.push("Supported extensions: .md, .mdx, .txt.");
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push("Add more representative long-form writing, then rerun drav doctor.");
+  }
+
+  return recommendations;
+}
+
+function nextStepFor(result) {
+  if (result.status === "ready") {
+    return `drav init --examples ${result.examples}`;
+  }
+  return "add more writing, then run drav doctor";
+}
+
+function resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.join(cwd, value);
+}
+
+function displayPath(filePath, rootDir) {
+  const relative = path.relative(rootDir, filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join("/");
+  }
+  return filePath.split(path.sep).join("/");
+}
+
+function displayPathForCommand(value) {
+  return String(value).replace(/[\\/]+/g, "/");
+}

package/src/v2/document-model.js

@@ -3,9 +3,10 @@ import path from "node:path";
 import { normalizeText, splitSentences, tokenizeWords } from "./text-utils.js";
 
 export const VOICE_EXTENSIONS = new Set([".md", ".mdx", ".txt"]);
-const DEFAULT_MAX_FILES = 500;
-const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
-const DEFAULT_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+export const VOICE_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", "__pycache__", "prompts", "voice-pack", "dravoice-voice"]);
+export const DEFAULT_MAX_FILES = 500;
+export const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
 
 export function loadDocuments({
   examplesDir,
@@ -56,6 +57,8 @@ export function parseDocument({ filePath, rootDir = process.cwd(), contents }) {
   let inFrontmatter = lines[0]?.trim() === "---";
   let inHtmlComment = false;
   let jsxBlockTag = null;
+  let mdxScaffoldDepth = 0;
+  let mdxExpressionDepth = 0;
 
   const flushParagraph = () => {
     if (currentParagraph?.lines.length) {
@@ -85,6 +88,16 @@ export function parseDocument({ filePath, rootDir = process.cwd(), contents }) {
       return;
     }
 
+    if (mdxScaffoldDepth > 0) {
+      mdxScaffoldDepth = Math.max(0, mdxScaffoldDepth + syntaxDepthDelta(trimmed));
+      return;
+    }
+
+    if (mdxExpressionDepth > 0) {
+      mdxExpressionDepth = Math.max(0, mdxExpressionDepth + curlyDepthDelta(trimmed));
+      return;
+    }
+
     if (inHtmlComment) {
       if (trimmed.includes("-->")) {
         inHtmlComment = false;
@@ -114,7 +127,19 @@ export function parseDocument({ filePath, rootDir = process.cwd(), contents }) {
       return;
     }
 
-    if (!trimmed || isMdxScaffold(trimmed) || isTableLine(trimmed) || isJsxLike(trimmed)) {
+    if (isMdxScaffold(trimmed)) {
+      flushParagraph();
+      mdxScaffoldDepth = Math.max(0, syntaxDepthDelta(trimmed));
+      return;
+    }
+
+    if (mdxExpressionStart(trimmed)) {
+      flushParagraph();
+      mdxExpressionDepth = Math.max(0, curlyDepthDelta(trimmed));
+      return;
+    }
+
+    if (!trimmed || isTableLine(trimmed) || isJsxLike(trimmed)) {
       if (!trimmed) {
         flushParagraph();
       }
@@ -277,6 +302,53 @@ function isMdxScaffold(trimmed) {
   return /^(?:import|export)\s/.test(trimmed);
 }
 
+function mdxExpressionStart(trimmed) {
+  return trimmed.startsWith("{") && /[A-Za-z_$][\w$]*\s*[.(]/.test(trimmed);
+}
+
+function syntaxDepthDelta(text) {
+  return curlyDepthDelta(text) + bracketDepthDelta(text) + parenDepthDelta(text);
+}
+
+function curlyDepthDelta(text) {
+  return depthDelta(text, "{", "}");
+}
+
+function bracketDepthDelta(text) {
+  return depthDelta(text, "[", "]");
+}
+
+function parenDepthDelta(text) {
+  return depthDelta(text, "(", ")");
+}
+
+function depthDelta(text, open, close) {
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    const previous = text[index - 1];
+    if (char === "'" && !inDouble && previous !== "\\") {
+      inSingle = !inSingle;
+      continue;
+    }
+    if (char === "\"" && !inSingle && previous !== "\\") {
+      inDouble = !inDouble;
+      continue;
+    }
+    if (inSingle || inDouble) {
+      continue;
+    }
+    if (char === open) {
+      depth += 1;
+    } else if (char === close) {
+      depth -= 1;
+    }
+  }
+  return depth;
+}
+
 function isTableLine(trimmed) {
   return /^\|.*\|$/.test(trimmed);
 }
@@ -291,7 +363,6 @@ function walkVoiceFiles(rootDir, { maxFiles, excludePaths }) {
     return result;
   }
   const stack = [rootDir];
-  const skipDirs = new Set([".git", "node_modules", "dist", "build", "__pycache__", "prompts", "voice-pack", "dravoice-voice"]);
   while (stack.length) {
     const current = stack.pop();
     if (isExcludedPath(current, excludePaths)) {
@@ -305,7 +376,7 @@ function walkVoiceFiles(rootDir, { maxFiles, excludePaths }) {
         continue;
       }
       if (entry.isDirectory()) {
-        if (!skipDirs.has(entry.name)) {
+        if (!VOICE_SKIP_DIRS.has(entry.name)) {
           directories.push(fullPath);
         }
       } else if (entry.isFile() && VOICE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {

package/src/v2/inspect.js

@@ -49,7 +49,7 @@ function featureSummary(name, features) {
     return `wordCount=${features.wordCount}; contentTypeTokenRatio=${features.vocabularyRichness.contentTypeTokenRatio}; wordLength.median=${features.wordLength.median}; maskedCharacterFourgrams=${features.maskedCharacterFourgrams?.length ?? 0}; functionWordBigrams=${features.functionWordBigrams?.length ?? 0}`;
   }
   if (name === "register") {
-    return `primary=${features.primary.value} (${features.primary.score}); alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
+    return `primary=${features.primary.value} (${features.primary.score}); mixedRegister=${features.mixedRegister ? "yes" : "no"}; markerSets=${features.markerSets?.length ?? 0}; alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
   }
   if (name === "discourse") {
     return `transitionRates=${Object.entries(features.transitionRates).map(([key, value]) => `${key}:${value}`).join(", ")}; sentenceCallbacks=${features.sentenceCallbacks}`;
@@ -61,7 +61,7 @@ function featureSummary(name, features) {
     return `evidenceSentenceRate=${features.evidenceSentenceRate}; claimSentenceRate=${features.claimSentenceRate}; supportedClaimRate=${features.supportedClaimRate}; unsupportedClaimRate=${features.unsupportedClaimRate}; evidenceTypes=${features.evidenceTypes.map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
   }
   if (name === "structure") {
-    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
+    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; maxHeadingDepth.median=${features.maxHeadingDepth?.median ?? 0}; sectionOrderPatterns=${features.sectionOrderPatterns?.length ?? 0}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
   }
   return JSON.stringify(features);
 }

package/src/v2/profile.js

@@ -17,9 +17,9 @@ import {
   stabilityFromDistances,
 } from "./stylometry.js";
 
-export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [] }) {
+export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [], registerMarkers }) {
   const documents = loadDocuments({ examplesDir, excludePaths });
-  const profile = buildVoiceProfileV2({ documents });
+  const profile = buildVoiceProfileV2({ documents, registerMarkers });
   if (outDir) {
     writeVoicePackV2(outDir, profile);
   }
@@ -39,9 +39,10 @@ export function loadVoicePackV2(voiceDir) {
   return profile;
 }
 
-export function buildVoiceProfileV2({ documents }) {
+export function buildVoiceProfileV2({ documents, registerMarkers }) {
   const source = sourceSummary(documents);
-  const families = analyzeFeatureFamilies(documents);
+  const families = analyzeFeatureFamilies(documents, { registerMarkers });
+  const styleThresholds = styleThresholdsFor(documents, families, { registerMarkers });
 
   return {
     schemaVersion: 2,
@@ -56,7 +57,8 @@ export function buildVoiceProfileV2({ documents }) {
         rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
         evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
       },
-      styleThresholds: styleThresholdsFor(documents, families),
+      styleThresholds,
+      familyDiagnostics: familyCalibrationDiagnostics({ source, families, styleThresholds }),
       minimumDraftSize: {
         words: source.confidence.band === "weak" ? 25 : 35,
         sentences: source.confidence.band === "weak" ? 3 : 4,
@@ -65,11 +67,11 @@ export function buildVoiceProfileV2({ documents }) {
   };
 }
 
-function analyzeFeatureFamilies(documents) {
+function analyzeFeatureFamilies(documents, { registerMarkers } = {}) {
   return {
     rhythm: analyzeRhythm(documents),
     lexical: analyzeLexical(documents),
-    register: analyzeRegister(documents),
+    register: analyzeRegister(documents, registerMarkers ? { markers: registerMarkers } : undefined),
     discourse: analyzeDiscourse(documents),
     rhetoricalShape: analyzeRhetoricalShape(documents),
     evidence: analyzeEvidence(documents),
@@ -77,15 +79,32 @@ function analyzeFeatureFamilies(documents) {
   };
 }
 
-function styleThresholdsFor(documents, fallbackFamilies) {
+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);
-      const heldoutFamilies = analyzeFeatureFamilies([documents[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,
@@ -109,7 +128,9 @@ function styleThresholdsFor(documents, fallbackFamilies) {
   }
 
   return {
-    method: "leave-one-out-cosine-delta",
+    method: documents.length >= 5
+      ? "leave-one-out-and-rotating-holdout-cosine-delta"
+      : "leave-one-out-cosine-delta",
     references: STYLOMETRIC_REFERENCES,
     families,
   };
@@ -168,6 +189,100 @@ function sourceSummary(documents) {
     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,
   };
 }