dravoice 0.1.2 → 0.1.4

package/src/v2/brief.js

@@ -1,146 +1,154 @@
-import fs from "node:fs";
-import path from "node:path";
-import { evidenceTypes } from "./analyzers/evidence.js";
-import { parseDocument } from "./document-model.js";
-import { loadVoicePackV2 } from "./profile.js";
-
-export function voiceArticleBriefV2({ voice, topic, evidence, cwd = process.cwd() }) {
-  const profile = typeof voice === "string" ? loadVoicePackV2(resolvePath(cwd, voice)) : voice;
-  const evidenceResult = evidence ? evidenceAnchorsFromFile({ evidence, cwd }) : {
-    source: null,
-    anchors: [],
-  };
-
-  return {
-    schemaVersion: 2,
-    generatedBy: "dravoice-v2-brief",
-    topic,
-    voice: {
-      corpusConfidence: profile.source.confidence,
-      sourceFileCount: profile.source.documentCount,
-      sourceWordCount: profile.source.wordCount,
-      primaryRegister: profile.families.register.features.primary.value,
-      evidenceSentenceRate: profile.families.evidence.features.evidenceSentenceRate,
-      featureFamilies: Object.keys(profile.families),
-      draftingRules: profile.guidance.draftingRules.slice(0, 5),
-    },
-    workingThesis: `Draft a grounded article about ${topic}. Let the supplied evidence set the size of each claim before broadening the lesson.`,
-    evidence: evidenceResult,
-    missingEvidence: missingEvidenceFor({ topic, evidenceAnchors: evidenceResult.anchors }),
-    outline: outlineFor(profile),
-    voiceCautions: [
-      ...profile.guidance.avoid,
-      "Mark unsupported claims as [specific evidence needed] instead of inventing proof.",
-    ].slice(0, 5),
-  };
-}
-
-export function renderVoiceBriefV2(brief) {
-  const lines = [
-    `# Article Brief: ${brief.topic}`,
-    "",
-    "## Voice Source",
-    "",
-    `- Corpus confidence: ${capitalize(brief.voice.corpusConfidence.band)} - ${brief.voice.corpusConfidence.message}`,
-    `- Source files: ${brief.voice.sourceFileCount}`,
-    `- Primary register: ${brief.voice.primaryRegister}`,
-    `- Evidence sentence rate: ${brief.voice.evidenceSentenceRate}`,
-    "",
-    "## Working Thesis",
-    "",
-    `- ${brief.workingThesis}`,
-    "",
-    "## Evidence Anchors",
-    "",
-  ];
-
-  if (brief.evidence.anchors.length) {
-    for (const item of brief.evidence.anchors) {
-      const typeList = item.types.length ? ` (${item.types.join(", ")})` : "";
-      lines.push(`- ${brief.evidence.source}:${item.line}${typeList} - ${item.text}`);
-    }
-  } else {
-    lines.push("- [specific evidence needed] Add notes, dates, quotes, examples, or source links before drafting broad claims.");
-  }
-
-  lines.push("", "## Missing Evidence", "");
-  lines.push(...brief.missingEvidence.map((item) => `- ${item}`));
-
-  lines.push("", "## Outline", "");
-  lines.push(...brief.outline.map((item, index) => `${index + 1}. ${item}`));
-
-  lines.push("", "## Voice Cautions", "");
-  lines.push(...brief.voiceCautions.map((item) => `- ${item}`));
-
-  lines.push(
-    "",
-    "## Drafting Prompt",
-    "",
-    `Write the article about ${brief.topic} using the evidence anchors above. Keep claims close to concrete support, follow the voice cautions, and write [specific evidence needed] anywhere the brief does not supply enough ground.`,
-    "",
-  );
-
-  return lines.join("\n");
-}
-
-function evidenceAnchorsFromFile({ evidence, cwd }) {
-  const evidencePath = resolvePath(cwd, evidence);
-  const contents = fs.readFileSync(evidencePath, "utf8");
-  const document = parseDocument({
-    filePath: evidencePath,
-    rootDir: cwd,
-    contents,
-  });
-
-  return {
-    source: displayPath(evidencePath, cwd),
-    anchors: document.sentences
-      .map((sentence) => ({
-        line: sentence.line,
-        text: sentence.text,
-        types: evidenceTypes(sentence.text),
-      }))
-      .filter((sentence) => sentence.types.length > 0)
-      .slice(0, 8),
-  };
-}
-
-function missingEvidenceFor({ topic, evidenceAnchors }) {
-  const items = [
-    `Add [specific evidence needed] for the central claim about ${topic}.`,
-    "Add [specific evidence needed] for any number, date, quote, source, or example the article depends on.",
-  ];
-  if (evidenceAnchors.length === 0) {
-    items.unshift("No evidence anchors were detected; collect concrete notes before asking for a full draft.");
-  }
-  return items;
-}
-
-function outlineFor(profile) {
-  const opening = profile.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
-  const sentenceMedian = profile.families.rhythm.features.sentenceWords.median;
-  return [
-    opening
-      ? `Start from a concrete artifact or observation, keeping the opening shape compatible with: ${opening}.`
-      : "Start from a concrete artifact or observation before making the larger claim.",
-    "Name the pressure, question, or practical stakes that make the evidence matter.",
-    `Develop the article in the learned register with sentence pacing near the ${sentenceMedian}-word median where it fits.`,
-    "Close by returning to the evidence and leaving the reader with a practical handle, not a generic conclusion.",
-  ];
-}
-
-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 capitalize(value) {
-  return String(value ?? "").charAt(0).toUpperCase() + String(value ?? "").slice(1);
-}
+import path from "node:path";
+import { evidenceTypes } from "./analyzers/evidence.js";
+import { parseDocument } from "./document-model.js";
+import { readUtf8FileBounded } from "./io-utils.js";
+import { loadVoicePackV2 } from "./profile.js";
+
+export function voiceArticleBriefV2({ voice, topic, evidence, cwd = process.cwd() }) {
+  const profile = typeof voice === "string" ? loadVoicePackV2(resolvePath(cwd, voice)) : voice;
+  const evidenceResult = evidence ? evidenceAnchorsFromFile({ evidence, cwd }) : {
+    source: null,
+    anchors: [],
+  };
+
+  return {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2-brief",
+    topic,
+    voice: {
+      corpusConfidence: profile.source.confidence,
+      sourceFileCount: profile.source.documentCount,
+      sourceWordCount: profile.source.wordCount,
+      primaryRegister: profile.families.register.features.primary.value,
+      evidenceSentenceRate: profile.families.evidence.features.evidenceSentenceRate,
+      featureFamilies: Object.keys(profile.families),
+      draftingRules: profile.guidance.draftingRules.slice(0, 5),
+    },
+    workingThesis: `Draft a grounded article about ${topic}. Let the supplied evidence set the size of each claim before broadening the lesson.`,
+    evidence: evidenceResult,
+    missingEvidence: missingEvidenceFor({ topic, evidenceAnchors: evidenceResult.anchors }),
+    outline: outlineFor(profile),
+    voiceCautions: [
+      ...profile.guidance.avoid,
+      "Mark unsupported claims as [specific evidence needed] instead of inventing proof.",
+    ].slice(0, 5),
+  };
+}
+
+export function renderVoiceBriefV2(brief) {
+  const lines = [
+    `# Article Brief: ${safeInline(brief.topic)}`,
+    "",
+    "## Voice Source",
+    "",
+    `- Corpus confidence: ${capitalize(brief.voice.corpusConfidence.band)} - ${brief.voice.corpusConfidence.message}`,
+    `- Source files: ${brief.voice.sourceFileCount}`,
+    `- Primary register: ${brief.voice.primaryRegister}`,
+    `- Evidence sentence rate: ${brief.voice.evidenceSentenceRate}`,
+    "",
+    "## Working Thesis",
+    "",
+    `- ${safeInline(brief.workingThesis)}`,
+    "",
+    "## Evidence Anchors",
+    "",
+  ];
+
+  if (brief.evidence.anchors.length) {
+    for (const item of brief.evidence.anchors) {
+      const typeList = item.types.length ? ` (${item.types.join(", ")})` : "";
+      lines.push(`- ${safeInline(brief.evidence.source)}:${item.line}${typeList} - ${safeInline(item.text)}`);
+    }
+  } else {
+    lines.push("- [specific evidence needed] Add notes, dates, quotes, examples, or source links before drafting broad claims.");
+  }
+
+  lines.push("", "## Missing Evidence", "");
+  lines.push(...brief.missingEvidence.map((item) => `- ${safeInline(item)}`));
+
+  lines.push("", "## Outline", "");
+  lines.push(...brief.outline.map((item, index) => `${index + 1}. ${safeInline(item)}`));
+
+  lines.push("", "## Voice Cautions", "");
+  lines.push(...brief.voiceCautions.map((item) => `- ${safeInline(item)}`));
+
+  lines.push(
+    "",
+    "## Drafting Prompt",
+    "",
+    `Write the article about ${safeInline(brief.topic)} using the evidence anchors above. Keep claims close to concrete support, follow the voice cautions, and write [specific evidence needed] anywhere the brief does not supply enough ground.`,
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function evidenceAnchorsFromFile({ evidence, cwd }) {
+  const evidencePath = resolvePath(cwd, evidence);
+  const contents = readUtf8FileBounded(evidencePath, { label: "Evidence file", maxBytes: 1024 * 1024 });
+  const document = parseDocument({
+    filePath: evidencePath,
+    rootDir: cwd,
+    contents,
+  });
+
+  return {
+    source: displayPath(evidencePath, cwd),
+    anchors: document.sentences
+      .map((sentence) => ({
+        line: sentence.line,
+        text: sentence.text,
+        types: evidenceTypes(sentence.text),
+      }))
+      .filter((sentence) => sentence.types.length > 0)
+      .slice(0, 8),
+  };
+}
+
+function missingEvidenceFor({ topic, evidenceAnchors }) {
+  const items = [
+    `Add [specific evidence needed] for the central claim about ${topic}.`,
+    "Add [specific evidence needed] for any number, date, quote, source, or example the article depends on.",
+  ];
+  if (evidenceAnchors.length === 0) {
+    items.unshift("No evidence anchors were detected; collect concrete notes before asking for a full draft.");
+  }
+  return items;
+}
+
+function outlineFor(profile) {
+  const opening = profile.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
+  const sentenceMedian = profile.families.rhythm.features.sentenceWords.median;
+  return [
+    opening
+      ? `Start from a concrete artifact or observation, keeping the opening shape compatible with: ${opening}.`
+      : "Start from a concrete artifact or observation before making the larger claim.",
+    "Name the pressure, question, or practical stakes that make the evidence matter.",
+    `Develop the article in the learned register with sentence pacing near the ${sentenceMedian}-word median where it fits.`,
+    "Close by returning to the evidence and leaving the reader with a practical handle, not a generic conclusion.",
+  ];
+}
+
+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 capitalize(value) {
+  return String(value ?? "").charAt(0).toUpperCase() + String(value ?? "").slice(1);
+}
+
+function safeInline(value) {
+  return String(value ?? "")
+    .replace(/[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/`/g, "'")
+    .trim();
+}

package/src/v2/config.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { writeUtf8FileSafely } from "./io-utils.js";
+
+export const DEFAULT_EXAMPLES_DIR = "./articles";
+export const DEFAULT_VOICE_DIR = "./dravoice-voice";
+export const DEFAULT_PROMPT_FORMAT = "agents";
+export const DEFAULT_PROMPT_OUT = "AGENTS.md";
+
+const CONFIG_FILE = ".dravoice.yml";
+
+export function configPathFor(cwd) {
+  return path.join(cwd, CONFIG_FILE);
+}
+
+export function loadProjectConfig(cwd) {
+  const configPath = configPathFor(cwd);
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  const config = {};
+  const contents = fs.readFileSync(configPath, "utf8");
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const match = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(rawLine);
+    if (!match) {
+      continue;
+    }
+    const [, key, value] = match;
+    if (["voice", "examples", "promptFormat", "promptOut"].includes(key)) {
+      config[key] = unquoteYamlScalar(value.trim());
+    }
+  }
+  return config;
+}
+
+export function writeProjectConfig(cwd, updates = {}) {
+  const existing = loadProjectConfig(cwd);
+  const config = {
+    voice: updates.voice ?? existing.voice ?? DEFAULT_VOICE_DIR,
+    examples: updates.examples ?? existing.examples ?? DEFAULT_EXAMPLES_DIR,
+    promptFormat: updates.promptFormat ?? existing.promptFormat ?? DEFAULT_PROMPT_FORMAT,
+    promptOut: updates.promptOut ?? existing.promptOut ?? DEFAULT_PROMPT_OUT,
+  };
+  writeUtf8FileSafely(
+    configPathFor(cwd),
+    [
+      "# Dravoice project defaults",
+      `voice: ${displayPath(config.voice)}`,
+      `examples: ${displayPath(config.examples)}`,
+      `promptFormat: ${config.promptFormat}`,
+      `promptOut: ${displayPath(config.promptOut)}`,
+      "",
+    ].join("\n"),
+  );
+  return config;
+}
+
+export function resolveConfiguredPath(cwd, value) {
+  if (!value) {
+    return undefined;
+  }
+  return path.isAbsolute(value) ? value : path.join(cwd, value);
+}
+
+export function displayPath(value) {
+  return String(value).replace(/[\\/]+/g, "/");
+}
+
+function unquoteYamlScalar(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}

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, "/");
+}