prose.mjs

Functions

Imports

It imports prose-engine.mjs. No module of this repo imports it.

Source

1/**
2 * The one check on AI-written prose, and the one measure of an author's voice, for every app that has a model write text
3 * a person will read: Carrel's drafts, Foxhound's emails. It flags; it never rewrites. What a flag means is the caller's
4 * call: Carrel shows it to the author, Foxhound regenerates the email.
5 *
6 * - `checkProse` runs the avoid-ai-writing engine (prose-engine.mjs, a generated copy: see update-prose-engine.mjs) and
7 *   adds what the engine does not see: the "not X, it's Y" construction across two sentences, a paragraph that closes on
8 *   a list of three, the caller's own words and phrases, and each dash on the line it sits on. Words the caller allows
9 *   are dropped from every source.
10 * - `profileOf`, `distanceFrom` and `nearestPassages` measure a text against the author's own passages in the manner of
11 *   Burrows' Delta (sentence length, punctuation, contractions and function-word rates). Statistics cannot say whose prose
12 *   a text is, only that it reads unlike the passages; and the passages nearest the author's usual style are the
13 *   examples a model writes from best (Wang et al., Findings of EMNLP 2025: examples beat a described style).
14 *
15 * Nothing here scores text against an AI detector or aims to pass one. The goal is prose a reader finds worth reading.
16 */
17
18import AIDetector from "./prose-engine.mjs";
19
20/** @typedef {"critical" | "high" | "medium" | "low"} Severity */
21/** @typedef {{ check: string, message: string, excerpt: string | null, line: number | null, severity: Severity }} ProseIssue */
22/** @typedef {"general" | "technical" | "marketing" | "personal"} ProseContext */
23
24// ---------- the habits
25
26/** "It's not just a house, it's a promise." / "This isn't only about money; it's about pride." / "It wasn't about money. It was about pride." */
27export const NOT_JUST = [
28  /(?:\bnot|n['’]t)\s+(?:just|only|merely|simply)\s+[^.!?;:,]{1,60}[,;:.]\s*(?:it|this|that|he|she|they|we|you)(?:['’](?:s|re)|\s+(?:is|was|are|were))\b/iu,
29  /\b(?:it|this|that)(?:['’]s\s+not|\s+is\s+not|\s+was\s+not|\s+isn['’]t|\s+wasn['’]t)\s+[^.!?;:,]{1,50}[.,;:]\s*(?:it|this|that)(?:['’]s|\s+(?:is|was))\b/iu,
30];
31
32/** A sentence that closes its paragraph on a three-item list of one- or two-word items. */
33const CLOSING_TRIAD = /(?:^|[.!?]\s+)([^.!?]*?\b([\p{L}'’]+(?:\s[\p{L}'’]+)?),\s+([\p{L}'’]+(?:\s[\p{L}'’]+)?),?\s+(?:and|or)\s+([\p{L}'’]+(?:\s[\p{L}'’]+)?)[.!])\s*$/u;
34
35const DASH = /\s*[—–]\s*|\s--\s/gu;
36
37/**
38 * Stock phrases of a model writing to a customer, which the engine's lists (built from articles and posts) miss. Pass
39 * them as `phrases` when the text is an email.
40 */
41export const EMAIL_PHRASES = [
42  "I hope this email finds you well",
43  "I hope this message finds you well",
44  "we understand that",
45  "rest assured",
46  "at your earliest convenience",
47  "please don't hesitate to",
48  "feel free to reach out",
49  "thank you for your understanding",
50];
51
52/** @param {string} s */
53function escapeRegExp(s) {
54  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
55}
56
57/** A whole-word, any-case match for a word or phrase, with either apostrophe. @param {string} phrase */
58function phraseRegExp(phrase) {
59  return new RegExp(`(?<![\\p{L}'’])${escapeRegExp(phrase).replace(/'/g, "['’]")}(?![\\p{L}])`, "giu");
60}
61
62/**
63 * The line `excerpt` first appears on, counted from `firstLine`, or null when it is not in the text as written (the engine
64 * reports some findings as a count, not a quotation).
65 * @param {string[]} lines @param {number} firstLine @param {string} excerpt
66 */
67function lineOf(lines, firstLine, excerpt) {
68  const re = phraseRegExp(excerpt);
69  const i = lines.findIndex((l) => {
70    re.lastIndex = 0;
71    return re.test(l);
72  });
73  return i === -1 ? null : firstLine + i;
74}
75
76/**
77 * Every habit in `text`, each with the words it concerns and the line they are on.
78 *
79 * - `context` tunes the engine's lists: "marketing" tolerates sales words, "technical" tolerates jargon. Default "general".
80 * - `phrases` adds the caller's own words and phrases (an author's list, `EMAIL_PHRASES`); `allow` takes words back out,
81 *   from the engine's lists as well as from `phrases`.
82 * - `dashes: "allow"` leaves em and en dashes alone, for an author whose own prose uses them; by default each line with
83 *   one is flagged.
84 * - `firstLine` is the file line `text` starts on, when it is a body cut from below a header.
85 *
86 * @param {string} text
87 * @param {{ context?: ProseContext, phrases?: string[], allow?: string[], dashes?: "flag" | "allow", firstLine?: number }} [options]
88 * @returns {ProseIssue[]}
89 */
90export function checkProse(text, options = {}) {
91  const { context = "general", phrases = [], allow = [], dashes = "flag", firstLine = 1 } = options;
92  const allowed = new Set(allow.map((w) => w.toLowerCase()));
93  const lines = text.split("\n");
94  /** @type {ProseIssue[]} */
95  const out = [];
96  const seen = new Set();
97  /** @param {ProseIssue} issue */
98  const add = (issue) => {
99    const key = `${issue.check}\u0000${(issue.excerpt ?? issue.message).toLowerCase()}\u0000${issue.line}`;
100    if (seen.has(key)) return;
101    seen.add(key);
102    out.push(issue);
103  };
104
105  const result = AIDetector.analyzeText(text, { contextMode: context, sourceMode: "rendered-markdown" });
106  for (const issue of result.issues) {
107    // Each dash is reported on its own line below; the engine's is a count for the whole text.
108    if (issue.type === "em-dash") continue;
109    if (allowed.has(String(issue.text).toLowerCase())) continue;
110    const label = AIDetector.TYPE_LABELS[issue.type] ?? issue.type;
111    const quoted = lineOf(lines, firstLine, issue.text);
112    const suggestion = String(issue.suggestion ?? "").replace(/\.+$/, "");
113    // A quoted finding names words to change; the rest (rhythm, density) describe the whole text.
114    const message =
115      quoted === null
116        ? `${label}: ${String(issue.text).replace(/\.+$/, "")}.${suggestion ? ` ${suggestion}.` : ""}`
117        : `${label}: "${issue.text}".${suggestion ? ` Try: ${suggestion}.` : ""}`;
118    add({
119      check: issue.type,
120      message,
121      excerpt: quoted === null ? null : issue.text,
122      line: quoted,
123      severity: issue.severity,
124    });
125  }
126
127  // Every occurrence of the caller's phrases counts, two on one line included, except the one the engine
128  // already reported (it names each word once, on its first line).
129  const reported = new Set(out.filter((i) => i.excerpt).map((i) => `${String(i.excerpt).toLowerCase()}\u0000${i.line}`));
130  for (const phrase of phrases) {
131    if (allowed.has(phrase.toLowerCase())) continue;
132    const re = phraseRegExp(phrase);
133    lines.forEach((line, i) => {
134      for (const m of line.matchAll(re)) {
135        if (reported.delete(`${m[0].toLowerCase()}\u0000${firstLine + i}`)) continue;
136        out.push({ check: "phrase", message: `"${phrase}" is on the list of stock phrases.`, excerpt: m[0], line: firstLine + i, severity: "high" });
137      }
138    });
139  }
140
141  // The engine sees some "not X, it's Y" lines itself; ours reports only the ones it missed.
142  const parallel = new Set(out.filter((i) => i.check === "negative-parallelism").map((i) => i.line));
143  lines.forEach((line, i) => {
144    const m = NOT_JUST.map((re) => re.exec(line)).find(Boolean);
145    if (m && !parallel.has(firstLine + i)) add({ check: "not-x-but-y", message: `The "not X, it's Y" construction.`, excerpt: m[0], line: firstLine + i, severity: "medium" });
146    if (dashes === "flag") {
147      for (const d of line.matchAll(DASH)) {
148        const at = d.index ?? 0;
149        const excerpt = line.slice(Math.max(0, at - 20), at + d[0].length + 20).trim();
150        add({ check: "dash", message: "A dash where a comma, a full stop or brackets would do.", excerpt, line: firstLine + i, severity: "medium" });
151      }
152    }
153  });
154
155  // Paragraphs, with the line each one ends on.
156  let start = 0;
157  for (let i = 0; i <= lines.length; i++) {
158    if (i === lines.length || lines[i].trim() === "") {
159      const paragraph = lines.slice(start, i).join(" ").trim();
160      const m = CLOSING_TRIAD.exec(paragraph);
161      if (m && !paragraph.startsWith("#")) {
162        add({ check: "closing-triad", message: "The paragraph closes on a list of three.", excerpt: m[1].trim(), line: firstLine + Math.max(start, i - 1), severity: "medium" });
163      }
164      start = i + 1;
165    }
166  }
167  return out.sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity));
168}
169
170/**
171 * What a model is told before it writes, in plain words, so the checks have less to find. The habits are the ones
172 * `checkProse` flags; the rest are what the checks cannot see. Callers add the author's own excerpts and guide.
173 */
174export const WRITING_RULES = `Write the way the author's excerpts read, not the way a model usually writes.
175
176- Say the thing. No run-up ("Here's the thing", "Let's be honest"), no closing summary, no moral at the end.
177- Plain words over impressive ones: "use" not "leverage", "shows" not "is a testament to". No delve, tapestry, landscape, realm, navigate (unless literal), crucial, pivotal, seamless, robust.
178- No "not X, it's Y", and no "It isn't about X. It's about Y."
179- Lists of three only when there are three things. Never end a paragraph on one for rhythm.
180- No dashes as all-purpose joiners. Use a comma, a full stop or brackets.
181- Contractions where the author uses them. Vary sentence length the way the excerpts do; short sentences are fine, a run of them is a tic.
182- No hedging stacks ("may potentially", "it could be argued"). Commit, or say what you don't know and why.
183- Concrete over abstract: a number, a name, an example, a thing that happened. Cut a sentence that would fit any article on the subject.
184- No inflated significance ("plays a vital role", "stands as", "marks a pivotal moment") and no vague authority ("experts say", "studies show") without the source.
185- No chatbot leftovers: "I hope this helps", "Great question", "As an AI", "Certainly!".
186- Bold and headings only where the author's own posts use them.`;
187
188// ---------- the voice
189
190const FUNCTION_WORDS = [
191  "the", "and", "of", "to", "a", "in", "that", "it", "was", "he", "she", "i", "you", "with", "for", "on", "as",
192  "at", "but", "had", "his", "her", "not", "be", "is", "they", "by", "from", "this", "so", "all", "were", "there",
193  "which", "would", "when", "then", "what", "if", "into", "out", "up", "like", "just", "some", "no", "one", "or",
194];
195
196/** How long a text needs to be before its profile means anything. */
197const MIN_WORDS = 250;
198/** The chunk size passages are cut into, so their spread can be measured. */
199const CHUNK_WORDS = 300;
200/** The most one feature can add to the distance, in standard deviations. */
201const MAX_Z = 5;
202/** A floor on sentence length's spread, relative to its mean, so passages that agree closely cannot make it dominate. */
203const MIN_SPREAD = 0.15;
204
205/** @typedef {Record<string, number>} Features */
206/** @typedef {{ mean: Features, spread: Features, chunks: number, words: number }} Profile */
207/** @typedef {{ name: string, value: number, mean: number, z: number }} FeatureReading */
208/** @typedef {{ distance: number, furthest: FeatureReading[] }} VoiceReading */
209
210/** @param {string} text */
211function words(text) {
212  return text.toLowerCase().match(/[\p{L}]+(?:['’][\p{L}]+)*/gu) ?? [];
213}
214
215/** @param {string} text */
216function sentences(text) {
217  return text
218    .replace(/\s+/g, " ")
219    .split(/(?<=[.!?])["”’)]?\s+(?=["“‘(]?[\p{Lu}\d])/u)
220    .map((s) => s.trim())
221    .filter((s) => words(s).length > 0);
222}
223
224/** @param {number} count @param {number} total */
225function per1000(count, total) {
226  return total === 0 ? 0 : (count * 1000) / total;
227}
228
229/** @param {string} text @returns {Features} */
230function features(text) {
231  const all = words(text);
232  const total = all.length;
233  const sents = sentences(text);
234  /** @type {Map<string, number>} */
235  const counts = new Map();
236  for (const w of all) counts.set(w, (counts.get(w) ?? 0) + 1);
237  const count = (/** @type {RegExp} */ re) => text.match(re)?.length ?? 0;
238
239  /** @type {Features} */
240  const out = {
241    "sentence length": sents.length === 0 ? 0 : total / sents.length,
242    commas: per1000(count(/,/g), total),
243    semicolons: per1000(count(/;/g), total),
244    colons: per1000(count(/:/g), total),
245    dashes: per1000(count(/—|–|--/g), total),
246    questions: per1000(count(/\?/g), total),
247    exclamations: per1000(count(/!/g), total),
248    // People editing a model's draft toward their own voice added contractions above all (Baumler et al., ACL 2026).
249    contractions: per1000(all.filter((w) => /['’](?:s|t|re|ve|ll|d|m)$/.test(w)).length, total),
250  };
251  for (const fw of FUNCTION_WORDS) out[`"${fw}"`] = per1000(counts.get(fw) ?? 0, total);
252  return out;
253}
254
255/** Cuts text into runs of about CHUNK_WORDS words, on paragraph boundaries where it can. @param {string} text */
256function chunks(text) {
257  const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
258  /** @type {string[]} */
259  const out = [];
260  /** @type {string[]} */
261  let current = [];
262  let size = 0;
263  for (const p of paragraphs) {
264    current.push(p);
265    size += words(p).length;
266    if (size >= CHUNK_WORDS) {
267      out.push(current.join("\n\n"));
268      current = [];
269      size = 0;
270    }
271  }
272  if (size >= CHUNK_WORDS / 2) out.push(current.join("\n\n"));
273  return out;
274}
275
276/**
277 * The profile of the author's passages, or null when there is too little of their text to compare with.
278 * @param {string[]} passages
279 * @returns {Profile | null}
280 */
281export function profileOf(passages) {
282  const pieces = passages.flatMap(chunks);
283  if (pieces.length < 3) return null;
284  const rows = pieces.map(features);
285  const names = Object.keys(rows[0]);
286  /** @type {Features} */
287  const mean = {};
288  /** @type {Features} */
289  const spread = {};
290  for (const name of names) {
291    const values = rows.map((r) => r[name] ?? 0);
292    const m = values.reduce((a, b) => a + b, 0) / values.length;
293    const variance = values.reduce((a, b) => a + (b - m) ** 2, 0) / (values.length - 1);
294    mean[name] = m;
295    // A spread of zero would make any difference infinitely far. A rate cannot be measured finer than one occurrence
296    // in a chunk, so that is its floor; sentence length gets a relative one.
297    const floor = name === "sentence length" ? MIN_SPREAD * Math.max(1, m) : 1000 / CHUNK_WORDS;
298    spread[name] = Math.max(Math.sqrt(variance), floor);
299  }
300  return { mean, spread, chunks: pieces.length, words: passages.reduce((n, p) => n + words(p).length, 0) };
301}
302
303/**
304 * How far `text` reads from the profile (the mean of each feature's distance in standard deviations, each capped at
305 * MAX_Z so one habit cannot outweigh the rest), with the three furthest features; null when `text` is too short.
306 * @param {Profile} profile
307 * @param {string} text
308 * @returns {VoiceReading | null}
309 */
310export function distanceFrom(profile, text) {
311  if (words(text).length < MIN_WORDS) return null;
312  const f = features(text);
313  const scored = Object.keys(profile.mean).map((name) => {
314    const value = f[name] ?? 0;
315    const mean = profile.mean[name] ?? 0;
316    return { name, value, mean, z: (value - mean) / (profile.spread[name] ?? 1) };
317  });
318  const distance = scored.reduce((a, s) => a + Math.min(MAX_Z, Math.abs(s.z)), 0) / scored.length;
319  const furthest = [...scored].sort((a, b) => Math.abs(b.z) - Math.abs(a.z)).slice(0, 3);
320  return { distance, furthest };
321}
322
323/**
324 * The `count` excerpts (about 300 words each, cut on paragraph boundaries) that read most like the author's usual
325 * style: the examples to hand a model before it writes.
326 * @param {Profile} profile
327 * @param {string[]} passages
328 * @param {number} [count]
329 * @returns {string[]}
330 */
331export function nearestPassages(profile, passages, count = 5) {
332  return passages
333    .flatMap(chunks)
334    .map((text) => ({ text, reading: distanceFrom(profile, text) }))
335    .filter((c) => c.reading !== null)
336    .sort((a, b) => /** @type {VoiceReading} */ (a.reading).distance - /** @type {VoiceReading} */ (b.reading).distance)
337    .slice(0, count)
338    .map((c) => c.text);
339}
340
341/**
342 * Where a text counts as reading unlike the passages. Set between the fixtures in test/prose.test.mjs (measured
343 * 2026-10-24: the passages themselves 0.46 to 0.54, the same register not in them 0.78, a public-domain passage by
344 * Henry James 1.47). An app recalibrates once it holds the author's own text: the fixtures stand in for it.
345 */
346export const VOICE_THRESHOLD = 1.1;
347
348/** One feature reading in words, for a flag. @param {FeatureReading} f */
349export function describeFeature(f) {
350  const round = (/** @type {number} */ n) => (n >= 10 ? Math.round(n) : Math.round(n * 10) / 10);
351  if (f.name === "sentence length") return `sentences average ${round(f.value)} words against ${round(f.mean)} in your passages`;
352  return `${round(f.value)} ${f.name} per 1,000 words against ${round(f.mean)}`;
353}