app/lib/novels/checks.ts

Functions

Imports

It imports app/lib/novels/frontmatter.ts, app/lib/novels/layout.ts. Imported by app/lib/books.server.ts, app/lib/social/lint.ts, app/routes/book.file.tsx.

Source

1// The checks on save (design section 5): deterministic, inside the app, and for catching errors
2// early, never for deciding. Each takes a file and the book's context and returns findings; none
3// refuses anything. A finding names the file's own line, so the editor can point at it.
4
5import { list, parseFile } from "./frontmatter";
6import {
7  kindOf,
8  readMeta,
9  readingOrder,
10  type CharacterEntry,
11  type Meta,
12  type PlaceEntry,
13  type RuleEntry,
14  type SceneHeader,
15} from "./layout";
16import { checkProse, describeFeature, distanceFrom, VOICE_THRESHOLD, type Profile } from "@dustinedwards/site-runtime/prose";
17
18type CheckName = "header" | "continuity" | "timeline" | "world-rules" | "ai-habits" | "voice";
19
20export type Finding = {
21  path: string;
22  check: CheckName;
23  message: string;
24  line: number | null;
25  excerpt: string | null;
26};
27
28export type Bible = { characters: CharacterEntry[]; places: PlaceEntry[]; rules: RuleEntry[] };
29
30export type SceneRow = { path: string; header: SceneHeader };
31
32/**
33 * What the AI-habits check reads from shared/checks/ai-habits.md: Dustin's own words on top of the shared
34 * check's lists, the words he allows back, whether the constructions are matched, and dashes ("allow" once
35 * his passages in shared/voice/ use them, unless the file says otherwise).
36 */
37export type AiHabits = { words: string[]; allow: string[]; conditions: boolean; dashes: "flag" | "allow" | null };
38
39export type BookContext = {
40  bible: Bible;
41  /** Every scene's header, as the index holds it. The file being checked replaces its own row. */
42  scenes: SceneRow[];
43  habits: AiHabits;
44  voice: Profile | null;
45};
46
47/**
48 * The AI-tells list first kept in capsid/conventions.md (Writing style, 2026-09-25), on top of the shared
49 * check's own lists (site-runtime ./prose). Dustin adds words or allows one back in shared/checks/ai-habits.md.
50 * In fiction several of these are ordinary words, which is why a hit is a flag for him to weigh, not a rule.
51 */
52export const SEED_WORDS = [
53  "delve", "tapestry", "spans", "landscape", "realm", "navigate", "testament to", "boasts", "stands as",
54  "compelling", "must-read", "journey", "explore", "dive into", "discover", "it's worth noting",
55  "importantly", "furthermore",
56];
57
58/**
59 * shared/checks/ai-habits.md: `words:` adds to the seed, `allow:` takes a word back out of every list,
60 * `conditions: false` turns the constructions off, `dashes: flag` or `dashes: allow` overrides what the
61 * passages decide.
62 */
63export function readHabits(source: string | null): AiHabits {
64  if (source === null) return { words: SEED_WORDS, allow: [], conditions: true, dashes: null };
65  const { data } = parseFile(source);
66  const allow = list(data, "allow").map((w) => w.toLowerCase());
67  const words = [...SEED_WORDS, ...list(data, "words")].map((w) => w.toLowerCase()).filter((w) => !allow.includes(w));
68  const dashes = data.dashes === "flag" || data.dashes === "allow" ? data.dashes : null;
69  return { words: [...new Set(words)], allow, conditions: data.conditions !== false, dashes };
70}
71
72/** Dashes are flagged unless the author's own passages use them (one in 1,000 words or more), or the habits file says. */
73export function dashesFor(habits: Pick<AiHabits, "dashes">, voice: Profile | null): "flag" | "allow" {
74  return habits.dashes ?? ((voice?.mean.dashes ?? 0) >= 1 ? "allow" : "flag");
75}
76
77// ---------- helpers
78
79const DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?$/;
80
81/** A story date, normalised so two compare as strings; null when it is not one. */
82export function storyDate(value: string): string | null {
83  const m = DATE.exec(value.trim());
84  if (!m) return null;
85  const [, y, mo, d, h, mi] = m;
86  if (Number(mo) < 1 || Number(mo) > 12 || Number(d) < 1 || Number(d) > 31) return null;
87  return `${y}-${mo}-${d}T${h ?? "00"}:${mi ?? "00"}`;
88}
89
90function sameName(a: string, b: string): boolean {
91  return a.trim().toLowerCase() === b.trim().toLowerCase();
92}
93
94function findCharacter(bible: Bible, name: string): CharacterEntry | undefined {
95  return bible.characters.find((c) => sameName(c.name, name) || c.aliases.some((a) => sameName(a, name)));
96}
97
98function findPlace(bible: Bible, name: string): PlaceEntry | undefined {
99  return bible.places.find((p) => sameName(p.name, name) || p.aliases.some((a) => sameName(a, name)));
100}
101
102/** The line in the file where the header key sits, for a finding about it. */
103function headerLine(source: string, key: string): number | null {
104  const lines = source.split("\n");
105  const i = lines.findIndex((l) => l.startsWith(`${key}:`));
106  return i === -1 ? null : i + 1;
107}
108
109/** Every match of `re` in the body, with the file line it falls on. */
110function matchesIn(body: string, bodyLine: number, re: RegExp): { line: number; text: string }[] {
111  const out: { line: number; text: string }[] = [];
112  const lines = body.split("\n");
113  lines.forEach((line, i) => {
114    for (const m of line.matchAll(re)) out.push({ line: bodyLine + i, text: m[0] });
115  });
116  return out;
117}
118
119// ---------- the checks
120
121/** The header is where the other checks get their facts; a missing field makes them silent, so it is flagged. */
122function checkHeader(path: string, source: string, header: SceneHeader, hasHeader: boolean): Finding[] {
123  if (!hasHeader) {
124    return [{ path, check: "header", message: "This scene has no header, so the continuity and timeline checks cannot run.", line: 1, excerpt: null }];
125  }
126  const out: Finding[] = [];
127  for (const key of ["pov", "date", "location"] as const) {
128    if (!header[key]) out.push({ path, check: "header", message: `The header has no ${key}.`, line: headerLine(source, key) ?? 1, excerpt: null });
129  }
130  for (const key of ["goal", "conflict", "outcome"] as const) {
131    if (!header[key]) out.push({ path, check: "header", message: `The beats have no ${key} yet.`, line: headerLine(source, key) ?? 1, excerpt: null });
132  }
133  if (header.date && !storyDate(header.date)) {
134    out.push({
135      path,
136      check: "header",
137      message: `The date "${header.date}" is not a story date; write it as 2031-04-12 or 2031-04-12 14:30.`,
138      line: headerLine(source, "date"),
139      excerpt: header.date,
140    });
141  }
142  return out;
143}
144
145/** Continuity: everyone present is in the bible and alive (and born) at the scene's date; the location exists. */
146export function checkContinuity(path: string, source: string, header: SceneHeader, bible: Bible): Finding[] {
147  const out: Finding[] = [];
148  const date = storyDate(header.date);
149  const present = [...new Set([header.pov, ...header.characters].filter(Boolean))];
150  for (const name of present) {
151    const key = name === header.pov && !header.characters.includes(name) ? "pov" : "characters";
152    const character = findCharacter(bible, name);
153    if (!character) {
154      out.push({ path, check: "continuity", message: `${name} is in this scene but not in the bible (bible/characters/).`, line: headerLine(source, key), excerpt: name });
155      continue;
156    }
157    const died = storyDate(character.died);
158    const born = storyDate(character.born);
159    if (date && died && died < date) {
160      out.push({
161        path,
162        check: "continuity",
163        message: `${character.name} died ${character.died}, before this scene (${header.date}), and is present in it.`,
164        line: headerLine(source, key),
165        excerpt: name,
166      });
167    }
168    if (date && born && born > date) {
169      out.push({
170        path,
171        check: "continuity",
172        message: `${character.name} is born ${character.born}, after this scene (${header.date}), and is present in it.`,
173        line: headerLine(source, key),
174        excerpt: name,
175      });
176    }
177  }
178  if (header.location && !findPlace(bible, header.location)) {
179    out.push({
180      path,
181      check: "continuity",
182      message: `The location "${header.location}" is not in the bible (bible/places/).`,
183      line: headerLine(source, "location"),
184      excerpt: header.location,
185    });
186  }
187  return out;
188}
189
190/** Timeline: a scene dated before the scene it follows is flagged, unless its header says flashback: true. */
191export function checkTimeline(path: string, source: string, header: SceneHeader, scenes: SceneRow[]): Finding[] {
192  const date = storyDate(header.date);
193  if (!date || header.flashback) return [];
194  const ordered = readingOrder(scenes.filter((s) => s.path !== path).concat({ path, header }));
195  const at = ordered.findIndex((s) => s.path === path);
196  // The last scene before this one on the main line: a flashback does not move the story's clock.
197  for (let i = at - 1; i >= 0; i--) {
198    const prev = ordered[i]!;
199    const prevDate = storyDate(prev.header.date);
200    if (prev.header.flashback || !prevDate) continue;
201    if (date < prevDate) {
202      return [
203        {
204          path,
205          check: "timeline",
206          message: `Dated ${header.date}, before the scene it follows (${prev.path}, ${prev.header.date}), and not marked flashback: true.`,
207          line: headerLine(source, "date"),
208          excerpt: header.date,
209        },
210      ];
211    }
212    return [];
213  }
214  return [];
215}
216
217/** World rules: each rule's forbidden patterns, matched against the scene's prose. */
218export function checkWorldRules(path: string, source: string, rules: RuleEntry[]): Finding[] {
219  const { body, bodyLine } = parseFile(source);
220  const out: Finding[] = [];
221  for (const rule of rules) {
222    for (const pattern of rule.forbidden) {
223      let re: RegExp;
224      try {
225        re = new RegExp(pattern, "giu");
226      } catch {
227        continue; // Reported on the rule's own file by checkRuleFile.
228      }
229      for (const m of matchesIn(body, bodyLine, re)) {
230        if (m.text === "") continue;
231        out.push({ path, check: "world-rules", message: `Breaks the rule "${rule.name}" (forbidden: ${pattern}).`, line: m.line, excerpt: m.text });
232      }
233    }
234  }
235  return out;
236}
237
238/** A rule file whose pattern will not compile would never flag anything, so that is flagged on the rule. */
239export function checkRuleFile(path: string, source: string, rule: RuleEntry): Finding[] {
240  const out: Finding[] = [];
241  for (const pattern of rule.forbidden) {
242    try {
243      new RegExp(pattern, "giu");
244    } catch (error) {
245      out.push({
246        path,
247        check: "world-rules",
248        message: `The pattern ${pattern} is not a valid expression, so it matches nothing: ${error instanceof Error ? error.message : String(error)}`,
249        line: headerLine(source, "forbidden"),
250        excerpt: pattern,
251      });
252    }
253  }
254  return out;
255}
256
257/** The shared check's word lists, as against its constructions; `conditions: false` keeps only these. */
258const WORD_CHECKS = /^(?:phrase|tier\d)$/;
259
260// A word list alone teaches renaming (the site's ruling 117), so the shared check matches the
261// constructions too: "not X, it's Y", a paragraph closing on three, dashes, rhythm.
262export function checkAiHabits(path: string, source: string, habits: AiHabits, voice: Profile | null = null): Finding[] {
263  const { body, bodyLine } = parseFile(source);
264  return checkProse(body, { context: "personal", phrases: habits.words, allow: habits.allow, dashes: dashesFor(habits, voice), firstLine: bodyLine })
265    .filter((issue) => habits.conditions || WORD_CHECKS.test(issue.check))
266    .map((issue) => ({ path, check: "ai-habits", message: issue.message, line: issue.line, excerpt: issue.excerpt }));
267}
268
269export function checkVoice(path: string, source: string, profile: Profile | null): Finding[] {
270  if (!profile) return [];
271  const reading = distanceFrom(profile, parseFile(source).body);
272  if (!reading || reading.distance < VOICE_THRESHOLD) return [];
273  return [
274    {
275      path,
276      check: "voice",
277      message: `Reads unlike your passages in shared/voice/ (distance ${reading.distance.toFixed(2)}, flagged from ${VOICE_THRESHOLD}): ${reading.furthest
278        .map(describeFeature)
279        .join("; ")}.`,
280      line: null,
281      excerpt: null,
282    },
283  ];
284}
285
286/** Every check that applies to a file of this kind. */
287export function checkFile(path: string, source: string, context: BookContext): Finding[] {
288  const kind = kindOf(path);
289  const parsed = parseFile(source);
290  const meta: Meta = readMeta(path, parsed.data, Object.keys(parsed.data).length > 0);
291  if (meta.kind === "rule") return checkRuleFile(path, source, meta.entry);
292  if (kind !== "scene" || meta.kind !== "scene") return [];
293  return [
294    ...checkHeader(path, source, meta.header, meta.hasHeader),
295    ...checkContinuity(path, source, meta.header, context.bible),
296    ...checkTimeline(path, source, meta.header, context.scenes),
297    ...checkWorldRules(path, source, context.bible.rules),
298    ...checkAiHabits(path, source, context.habits, context.voice),
299    ...checkVoice(path, source, context.voice),
300  ];
301}
302
303/**
304 * The key that keeps a dismissal: the same check saying the same thing about the same words. The
305 * nth repeat of an identical finding gets its own key, so dismissing one does not hide the others.
306 */
307export async function fingerprints(found: Finding[]): Promise<string[]> {
308  const seen = new Map<string, number>();
309  return Promise.all(
310    found.map(async (f) => {
311      const base = JSON.stringify([f.check, f.message, f.excerpt]);
312      const n = seen.get(base) ?? 0;
313      seen.set(base, n + 1);
314      const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${base}#${n}`));
315      return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
316    }),
317  );
318}