dravoice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dravoice contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Dravoice
+
+Dravoice is a local-first CLI for compiling Markdown, MDX, and plain-text
+writing corpora into reusable voice guidance and deterministic draft review
+notes.
+
+It is not an AI-authorship detector, grammar checker, prose linter, or
+third-party author imitation tool. It helps a writer inspect and reuse their
+own measurable rhythm, register, evidence habits, discourse shape, and
+structure.
+
+## Quick Start
+
+```bash
+npx --package dravoice drav learn --examples ./articles --out ./dravoice-voice
+npx --package dravoice drav inspect --voice ./dravoice-voice
+npx --package dravoice drav prompt --voice ./dravoice-voice --format agents --out AGENTS.md
+npx --package dravoice drav brief --voice ./dravoice-voice --topic "A new article topic" --evidence notes.md --out brief.md
+npx --package dravoice drav review draft.md --voice ./dravoice-voice
+npx --package dravoice drav review draft.md --voice ./dravoice-voice --mode strict --format json
+```
+
+`learn` writes a schemaVersion 2 `profile.json` plus local metadata. `inspect`
+makes the learned feature families visible, `prompt` turns high-confidence
+observations into drafting guidance, `brief` creates an evidence-first article
+plan, and `review` reports family-level drift.
+
+## Fresh Install Smoke Test
+
+From a packed tarball:
+
+```bash
+npm pack
+npm exec --package ./dravoice-0.1.0.tgz -- drav --help
+```

package/bin/dravoice.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "../src/index.js";
+
+const code = await runCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdout: process.stdout,
+  stderr: process.stderr,
+});
+
+process.exitCode = code;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "dravoice",
+  "version": "0.1.0",
+  "description": "Compile article voice profiles into reusable LLM writing context, evidence-first briefs, and deterministic draft review notes.",
+  "type": "module",
+  "bin": {
+    "drav": "bin/dravoice.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "node ../../scripts/check-js-syntax.js packages/js-cli",
+    "test": "node --test test/v2.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "voice",
+    "writing",
+    "cli",
+    "llm",
+    "markdown"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hilmimuktitama/dravoice.git",
+    "directory": "packages/js-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hilmimuktitama/dravoice/issues"
+  },
+  "homepage": "https://github.com/hilmimuktitama/dravoice#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,204 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  prepareVoiceBenchmark,
+  renderBenchmarkReport,
+  scoreVoiceBenchmark,
+} from "./v2/benchmark.js";
+import { renderVoiceBriefV2, voiceArticleBriefV2 } from "./v2/brief.js";
+import { renderInspectV2 } from "./v2/inspect.js";
+import { learnVoicePackV2, loadVoicePackV2 } from "./v2/profile.js";
+import { voicePromptPackV2 } from "./v2/prompt.js";
+import { renderVoiceReviewV2, reviewVoiceDraftV2 } from "./v2/review.js";
+
+export {
+  learnVoicePackV2 as learnVoicePack,
+  loadVoicePackV2 as loadVoicePack,
+  reviewVoiceDraftV2 as reviewVoiceDraft,
+  voicePromptPackV2 as voicePromptPack,
+};
+export { renderInspectV2, renderVoiceReviewV2 as renderVoiceReview };
+export { renderVoiceBriefV2 as renderVoiceBrief, voiceArticleBriefV2 as voiceArticleBrief };
+export { prepareVoiceBenchmark, renderBenchmarkReport, scoreVoiceBenchmark };
+
+export async function runCli(args, io) {
+  try {
+    const [command, ...rest] = args;
+    if (!command || command === "--help" || command === "-h") {
+      io.stdout.write(helpText());
+      return 0;
+    }
+
+    if (command === "learn") {
+      const { options } = parseArgs(rest, ["examples", "out"]);
+      const profile = learnVoicePackV2({
+        examplesDir: resolvePath(io.cwd, requiredOption(options, "examples")),
+        outDir: resolvePath(io.cwd, requiredOption(options, "out")),
+      });
+      io.stdout.write(`Generated V2 voice pack from ${profile.source.documentCount} document(s). Corpus confidence: ${profile.source.confidence.band}.\n`);
+      return 0;
+    }
+
+    if (command === "review") {
+      const { options, positional } = parseArgs(rest, ["voice", "mode", "format"]);
+      const file = positional[0];
+      if (!file) {
+        throw new Error("Missing draft file path for review");
+      }
+      const result = reviewVoiceDraftV2({
+        file: resolvePath(io.cwd, file),
+        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
+        cwd: io.cwd,
+        mode: options.mode ?? "balanced",
+      });
+      if (options.format === "json") {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      } else {
+        io.stdout.write(renderVoiceReviewV2(result));
+      }
+      return result.exitCode;
+    }
+
+    if (command === "prompt") {
+      const { options } = parseArgs(rest, ["voice", "format", "out"]);
+      const rendered = voicePromptPackV2({
+        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
+        format: options.format ?? "agents",
+        outPath: options.out ? resolvePath(io.cwd, options.out) : undefined,
+      });
+      if (!options.out) {
+        io.stdout.write(rendered);
+      }
+      return 0;
+    }
+
+    if (command === "brief") {
+      const { options } = parseArgs(rest, ["voice", "topic", "evidence", "format", "out"]);
+      const result = voiceArticleBriefV2({
+        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
+        topic: requiredOption(options, "topic"),
+        evidence: options.evidence ? resolvePath(io.cwd, options.evidence) : undefined,
+        cwd: io.cwd,
+      });
+      const rendered = options.format === "json" ? `${JSON.stringify(result, null, 2)}\n` : renderVoiceBriefV2(result);
+      if (options.out) {
+        const outPath = resolvePath(io.cwd, options.out);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, rendered, "utf8");
+      } else {
+        io.stdout.write(rendered);
+      }
+      return 0;
+    }
+
+    if (command === "inspect") {
+      const { options } = parseArgs(rest, ["voice"]);
+      const profile = loadVoicePackV2(resolvePath(io.cwd, options.voice ?? "."));
+      io.stdout.write(renderInspectV2(profile));
+      return 0;
+    }
+
+    if (command === "benchmark") {
+      return runBenchmarkCli(rest, io);
+    }
+
+    io.stderr.write(`Unknown command: ${command}\n`);
+    return 2;
+  } catch (error) {
+    io.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+}
+
+function runBenchmarkCli(args, io) {
+  const [benchmarkCommand, ...rest] = args;
+  if (benchmarkCommand === "prepare") {
+    const { options } = parseArgs(rest, ["examples", "topic", "out", "seed"]);
+    const benchmark = prepareVoiceBenchmark({
+      examplesDir: resolvePath(io.cwd, requiredOption(options, "examples")),
+      topic: requiredOption(options, "topic"),
+      outDir: resolvePath(io.cwd, requiredOption(options, "out")),
+      seed: options.seed ?? "1",
+    });
+    io.stdout.write(`Prepared benchmark at ${resolvePath(io.cwd, requiredOption(options, "out"))} with ${benchmark.corpus.fileCount} source article(s).\n`);
+    return 0;
+  }
+
+  if (benchmarkCommand === "score") {
+    const { options } = parseArgs(rest, ["run", "judge", "format"]);
+    const result = scoreVoiceBenchmark({
+      runDir: resolvePath(io.cwd, requiredOption(options, "run")),
+      judgePath: options.judge ? resolvePath(io.cwd, options.judge) : undefined,
+    });
+    if (options.format === "json") {
+      io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      io.stdout.write(renderBenchmarkReport(result));
+    }
+    return result.exitCode;
+  }
+
+  throw new Error(`Unknown benchmark command: ${benchmarkCommand ?? ""}`.trim());
+}
+
+function parseArgs(args, allowedOptionNames) {
+  const allowed = new Set(allowedOptionNames);
+  const options = {};
+  const positional = [];
+  let parseOptions = true;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (parseOptions && arg === "--") {
+      parseOptions = false;
+      continue;
+    }
+
+    if (!parseOptions || !arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+
+    const equalsIndex = arg.indexOf("=");
+    const key = equalsIndex === -1 ? arg.slice(2) : arg.slice(2, equalsIndex);
+    if (!allowed.has(key)) {
+      throw new Error(`Unknown option --${key}`);
+    }
+
+    const inlineValue = equalsIndex === -1 ? null : arg.slice(equalsIndex + 1);
+    const value = inlineValue ?? args[index + 1];
+    if (value === undefined || value === "" || (inlineValue === null && value.startsWith("--"))) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    options[key] = value;
+    if (inlineValue === null) {
+      index += 1;
+    }
+  }
+  return { options, positional };
+}
+
+function requiredOption(options, name) {
+  if (!options[name]) {
+    throw new Error(`Missing required option --${name}`);
+  }
+  return options[name];
+}
+
+function resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.join(cwd, value);
+}
+
+function helpText() {
+  return [
+    "drav learn --examples ./articles --out ./dravoice-voice",
+    "drav inspect --voice ./dravoice-voice",
+    "drav prompt --voice ./dravoice-voice --format agents --out AGENTS.md",
+    "drav brief --voice ./dravoice-voice --topic \"New topic\" --evidence notes.md --out brief.md",
+    "drav review draft.md --voice ./dravoice-voice --mode balanced --format text",
+    "drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
+    "drav benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json",
+    "",
+  ].join("\n");
+}

package/src/v2/analyzers/discourse.js

@@ -0,0 +1,52 @@
+import { rate, topItems } from "../text-utils.js";
+
+const TRANSITIONS = {
+  additive: /\b(also|and|another|again|plus)\b/i,
+  contrast: /\b(but|however|although|yet|instead|still)\b/i,
+  causal: /\b(because|so|therefore|since|as a result)\b/i,
+  temporal: /\b(then|before|after|while|when|first|second|later)\b/i,
+  example: /\b(for example|such as|including|like)\b/i,
+  conclusion: /\b(so|therefore|finally|in the end|the lesson)\b/i,
+};
+
+export function analyzeDiscourse(documents) {
+  const sentences = documents.flatMap((document) => document.sentences);
+  const labels = sentences.map((sentence) => transitionLabel(sentence.text));
+  const transitionRates = {};
+  for (const key of Object.keys(TRANSITIONS)) {
+    transitionRates[key] = rate(labels.filter((label) => label === key).length, sentences.length, 2);
+  }
+
+  return {
+    family: "discourse",
+    confidence: sentences.length >= 12 ? "medium" : "low",
+    features: {
+      transitionRates,
+      transitionSequence: labels.filter(Boolean).slice(0, 12),
+      sentenceCallbacks: callbackRate(sentences),
+    },
+    examples: topItems(labels.filter(Boolean), 5).map((item) => item.value),
+    warnings: sentences.length < 12 ? ["Discourse confidence is limited because the corpus has fewer than 12 sentences."] : [],
+    revisionHandles: ["Compare how sentences turn, contrast, explain, and return to earlier ideas."],
+  };
+}
+
+export function transitionLabel(text) {
+  for (const [label, pattern] of Object.entries(TRANSITIONS)) {
+    if (pattern.test(text)) {
+      return label;
+    }
+  }
+  return "plain";
+}
+
+function callbackRate(sentences) {
+  let callbacks = 0;
+  for (let index = 1; index < sentences.length; index += 1) {
+    const previous = new Set(sentences[index - 1].tokens.filter((word) => word.length > 3));
+    if (sentences[index].tokens.some((word) => previous.has(word))) {
+      callbacks += 1;
+    }
+  }
+  return rate(callbacks, Math.max(1, sentences.length - 1), 2);
+}

package/src/v2/analyzers/evidence.js

@@ -0,0 +1,43 @@
+import { rate, topItems } from "../text-utils.js";
+
+const EVIDENCE_PATTERNS = {
+  date: /\b\d{1,2}:\d{2}\s?(?:am|pm)?\b|\b20\d{2}-\d{2}-\d{2}\b|\b(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
+  number: /\b\d+(?:\.\d+)?\b/,
+  quote: /"[^"]+"|'[^']+'|^>/,
+  url: /https?:\/\/\S+/i,
+  citation: /\[[^\]]+\]\([^)]+\)|\([A-Z][A-Za-z]+,\s*\d{4}\)/,
+  sourceAttribution: /\b(according to|reported|observed|noted|recorded|quoted|interviewed|surveyed|field notes said|data shows|study found|the memo|the log|the report)\b/i,
+  sensory: /\b(cold|warm|hot|cool|quiet|loud|bright|dark|red|blue|green|rough|smooth|sharp|soft|smelled|smell|scent|tasted|heard|sound|noise|flashed|visible|physical|rain|metal|smoke)\b/i,
+  specificExample: /\b(for example|for instance|such as|including|included|includes|sample|case in point|specifically|in one case)\b/i,
+};
+
+const ABSTRACT_CLAIM_RE = /\b(always|never|everyone|everything|nothing|best|better|worse|important|obvious|clearly|should|must|need to|have to|all|none|every)\b/i;
+
+export function analyzeEvidence(documents) {
+  const sentences = documents.flatMap((document) => document.sentences);
+  const evidenceSentences = sentences.filter((sentence) => evidenceTypes(sentence.text).length > 0);
+  const claimSentences = sentences.filter((sentence) => ABSTRACT_CLAIM_RE.test(sentence.text));
+  const typeValues = evidenceSentences.flatMap((sentence) => evidenceTypes(sentence.text));
+
+  return {
+    family: "evidence",
+    confidence: sentences.length >= 12 ? "medium" : "low",
+    features: {
+      sentenceCount: sentences.length,
+      evidenceSentenceCount: evidenceSentences.length,
+      evidenceSentenceRate: rate(evidenceSentences.length, sentences.length, 2),
+      claimSentenceRate: rate(claimSentences.length, sentences.length, 2),
+      unsupportedClaimRate: rate(Math.max(0, claimSentences.length - evidenceSentences.length), sentences.length, 2),
+      evidenceTypes: topItems(typeValues, 8),
+    },
+    examples: topItems(typeValues, 4).map((item) => `${item.value}: ${item.count}`),
+    warnings: sentences.length < 12 ? ["Evidence confidence is limited because the corpus has fewer than 12 sentences."] : [],
+    revisionHandles: ["Compare how broad claims are supported by concrete scenes, numbers, quotes, citations, or examples."],
+  };
+}
+
+export function evidenceTypes(text) {
+  return Object.entries(EVIDENCE_PATTERNS)
+    .filter(([, pattern]) => pattern.test(text))
+    .map(([type]) => type);
+}

package/src/v2/analyzers/lexical.js

@@ -0,0 +1,58 @@
+import {
+  FUNCTION_WORDS,
+  characterNgrams,
+  contentWords,
+  distribution,
+  rate,
+  tokenizeWords,
+  topItems,
+} from "../text-utils.js";
+
+export function analyzeLexical(documents) {
+  const text = documents.map((document) => document.text).join("\n\n");
+  const words = tokenizeWords(text);
+  const content = contentWords(text);
+  const sentences = documents.flatMap((document) => document.sentences);
+  const functionWordSet = new Set(FUNCTION_WORDS);
+
+  return {
+    family: "lexical",
+    confidence: confidenceFor(words.length),
+    features: {
+      wordCount: words.length,
+      contentWordCount: content.length,
+      vocabularyRichness: {
+        uniqueContentWords: new Set(content).size,
+        contentTypeTokenRatio: rate(new Set(content).size, content.length, 3),
+      },
+      wordLength: distribution(words.map((word) => word.length)),
+      functionWords: topItems(words.filter((word) => functionWordSet.has(word)), 24),
+      characterTrigrams: topItems(characterNgrams(text, 3), 24),
+      repeatedMotifs: topItems(content, 16).filter((item) => item.count > 1),
+      punctuation: {
+        commaRate: rate(count(text, /,/g), sentences.length, 2),
+        semicolonRate: rate(count(text, /;/g), sentences.length, 2),
+        colonRate: rate(count(text, /:/g), sentences.length, 2),
+        questionRate: rate(count(text, /\?/g), sentences.length, 2),
+        dashRate: rate(count(text, /--|-/g), sentences.length, 2),
+      },
+    },
+    examples: topItems(content, 5).map((item) => item.value),
+    warnings: words.length < 200 ? ["Lexical confidence is limited because the corpus has fewer than 200 words."] : [],
+    revisionHandles: ["Compare function words, vocabulary richness, motifs, and punctuation habits."],
+  };
+}
+
+function confidenceFor(wordCount) {
+  if (wordCount >= 2000) {
+    return "high";
+  }
+  if (wordCount >= 120) {
+    return "medium";
+  }
+  return "low";
+}
+
+function count(text, pattern) {
+  return Array.from(text.matchAll(pattern)).length;
+}

package/src/v2/analyzers/register.js

@@ -0,0 +1,34 @@
+import { contentWords, rate, topItems } from "../text-utils.js";
+
+const REGISTER_MARKERS = {
+  narrative: ["scene", "moment", "watched", "waited", "noticed", "remembered", "described", "story"],
+  explanatory: ["because", "so", "therefore", "means", "shows", "explains", "reason", "pattern"],
+  argumentative: ["should", "must", "better", "important", "claim", "therefore", "argue", "evidence"],
+  instructional: ["start", "fix", "use", "avoid", "keep", "write", "revise", "follow"],
+  reflective: ["lesson", "pause", "changed", "remember", "noticed", "felt", "learned", "realized"],
+  technical: ["file", "test", "system", "code", "api", "build"],
+  personal: ["i", "my", "we", "our"],
+  formal: ["requires", "outcomes", "process", "alignment", "therefore"],
+};
+
+export function analyzeRegister(documents) {
+  const text = documents.map((document) => document.text.toLowerCase()).join("\n\n");
+  const words = new Set(contentWords(text));
+  const scores = Object.entries(REGISTER_MARKERS).map(([value, markers]) => ({
+    value,
+    score: rate(markers.filter((marker) => text.includes(marker) || words.has(marker)).length, markers.length, 2),
+  })).sort((left, right) => right.score - left.score || left.value.localeCompare(right.value));
+
+  return {
+    family: "register",
+    confidence: documents.length >= 3 ? "medium" : "low",
+    features: {
+      primary: scores[0] ?? { value: "unknown", score: 0 },
+      scores,
+      topContentWords: topItems(contentWords(text), 12),
+    },
+    examples: scores.slice(0, 3).map((item) => `${item.value}: ${item.score}`),
+    warnings: documents.length < 3 ? ["Register confidence is limited because the corpus has fewer than 3 documents."] : [],
+    revisionHandles: ["Check whether the draft uses the same broad register and genre mix as the corpus."],
+  };
+}

package/src/v2/analyzers/rhetorical-shape.js

@@ -0,0 +1,48 @@
+import { evidenceTypes } from "./evidence.js";
+import { transitionLabel } from "./discourse.js";
+import { topItems } from "../text-utils.js";
+
+export function analyzeRhetoricalShape(documents) {
+  const documentMoves = documents.map((document) => document.sentences.map((sentence) => moveFor(sentence.text)));
+  const sentenceMoves = documentMoves.flat();
+  const openingMoves = documents.flatMap((document) => document.sentences.slice(0, 3).map((sentence) => moveFor(sentence.text)));
+  const sequences = [];
+  for (const moves of documentMoves) {
+    for (let index = 0; index < moves.length - 1; index += 1) {
+      sequences.push(`${moves[index]} -> ${moves[index + 1]}`);
+    }
+  }
+
+  return {
+    family: "rhetoricalShape",
+    confidence: sentenceMoves.length >= 12 ? "medium" : "low",
+    features: {
+      moveRates: topItems(sentenceMoves, 12),
+      openingMoves: openingMoves.slice(0, 9),
+      commonSequences: topItems(sequences, 12),
+    },
+    examples: openingMoves.slice(0, 5),
+    warnings: sentenceMoves.length < 12 ? ["Rhetorical-shape confidence is limited because the corpus has fewer than 12 sentences."] : [],
+    revisionHandles: ["Compare the draft's opening and move sequence against observed source patterns."],
+  };
+}
+
+export function moveFor(text) {
+  if (evidenceTypes(text).length > 0) {
+    return "scene-or-evidence";
+  }
+  const transition = transitionLabel(text);
+  if (transition === "contrast") {
+    return "turn";
+  }
+  if (transition === "causal" || transition === "conclusion") {
+    return "implication";
+  }
+  if (/\b(should|must|rule|lesson|start|fix|avoid|keep)\b/i.test(text)) {
+    return "advice";
+  }
+  if (/\b(always|never|everyone|everything|important|best|better|worse|should|must|all|none|every)\b/i.test(text)) {
+    return "abstract-claim";
+  }
+  return "statement";
+}

package/src/v2/analyzers/rhythm.js

@@ -0,0 +1,47 @@
+import { distribution, rate } from "../text-utils.js";
+
+export function analyzeRhythm(documents) {
+  const sentences = documents.flatMap((document) => document.sentences);
+  const paragraphs = documents.flatMap((document) => document.paragraphs);
+  const blocks = documents.flatMap((document) => document.blocks);
+
+  return {
+    family: "rhythm",
+    confidence: confidenceFor(sentences.length),
+    features: {
+      documentCount: documents.length,
+      sentenceCount: sentences.length,
+      paragraphCount: paragraphs.length,
+      sentenceWords: distribution(sentences.map((sentence) => sentence.tokens.length)),
+      paragraphWords: distribution(paragraphs.map((paragraph) => paragraph.text.split(/\s+/).filter(Boolean).length)),
+      paragraphSentences: distribution(paragraphs.map((paragraph) => countParagraphSentences(sentences, paragraph))),
+      headingDensity: rate(documents.reduce((sum, document) => sum + document.headings.length, 0), sentences.length, 2),
+      listDensity: rate(blocks.filter((block) => block.type === "list").length, paragraphs.length, 2),
+      quoteDensity: rate(blocks.filter((block) => block.type === "quote").length, paragraphs.length, 2),
+    },
+    examples: [
+      `sentenceWords.median: ${distribution(sentences.map((sentence) => sentence.tokens.length)).median}`,
+      `paragraphWords.median: ${distribution(paragraphs.map((paragraph) => paragraph.text.split(/\s+/).filter(Boolean).length)).median}`,
+    ],
+    warnings: sentences.length < 12 ? ["Rhythm confidence is limited because the corpus has fewer than 12 usable sentences."] : [],
+    revisionHandles: ["Compare sentence and paragraph pacing against the learned range."],
+  };
+}
+
+function countParagraphSentences(sentences, paragraph) {
+  return Math.max(1, sentences.filter((sentence) =>
+    sentence.line >= paragraph.line &&
+    sentence.line < paragraph.line + 8 &&
+    sentence.headingId === paragraph.headingId
+  ).length);
+}
+
+function confidenceFor(sentenceCount) {
+  if (sentenceCount >= 30) {
+    return "high";
+  }
+  if (sentenceCount >= 8) {
+    return "medium";
+  }
+  return "low";
+}

package/src/v2/analyzers/structure.js

@@ -0,0 +1,24 @@
+import { distribution, rate } from "../text-utils.js";
+import { moveFor } from "./rhetorical-shape.js";
+
+export function analyzeStructure(documents) {
+  const sectionLengths = documents.flatMap((document) =>
+    document.sections.map((section) => section.blocks.reduce((sum, block) => sum + block.lines.join(" ").split(/\s+/).filter(Boolean).length, 0))
+  );
+  const openingMoves = documents.flatMap((document) => document.sentences.slice(0, 2).map((sentence) => moveFor(sentence.text)));
+
+  return {
+    family: "structure",
+    confidence: documents.length >= 3 ? "medium" : "low",
+    features: {
+      sectionWords: distribution(sectionLengths),
+      headingCount: distribution(documents.map((document) => document.headings.length)),
+      openingMoves,
+      listDocumentRate: rate(documents.filter((document) => document.blocks.some((block) => block.type === "list")).length, documents.length, 2),
+      quoteDocumentRate: rate(documents.filter((document) => document.blocks.some((block) => block.type === "quote")).length, documents.length, 2),
+    },
+    examples: openingMoves.slice(0, 5),
+    warnings: documents.length < 3 ? ["Structure confidence is limited because the corpus has fewer than 3 documents."] : [],
+    revisionHandles: ["Compare headings, list/quote use, section size, and opening structure."],
+  };
+}