paperlint 7.2.0 → 9.0.0

package/src/domain/paper-source.test.ts

@@ -1,6 +1,6 @@
 /**
  * The paper as one text: includes spliced where they stand, every character mapped back to its
- * file, a missing file reported, a subfile's body only, and a file that includes itself entered once.
+ * file, a file with nothing behind it left out, a subfile's body only, and a file that includes itself entered once.
  * The reader is a stand-in that finds `\input{…}` by position, so these tests are about assembling,
  * not about parsing LaTeX (the LaTeX adapter's own tests cover `includes`).
  */
@@ -41,8 +41,7 @@ describe("assemblePaper — the text TeX reads", () => {
       main,
       deps({ "s/one.tex": "one", "two.tex": "two" }),
     );
-    expect(p.text).toBe("AoneBtwoC");
-    expect(p.missing).toEqual([]);
+    expect(p.text).toBe("Aone\nBtwo\nC");
     expect([...new Set(p.segments.map((g) => g.file))]).toEqual([
       "paper.tex",
       "s/one.tex",
@@ -57,7 +56,7 @@ describe("assemblePaper — the text TeX reads", () => {
       main,
       deps({ "a.tex": "[\\input{s/b}]", "s/b.tex": "BB" }),
     );
-    expect(p.text).toBe("x[BB]y");
+    expect(p.text).toBe("x[BB\n]\ny");
     expect(originOf(p, { start: 2, end: 4 })).toEqual({
       file: "s/b.tex",
       source: "BB",
@@ -66,18 +65,10 @@ describe("assemblePaper — the text TeX reads", () => {
     });
   });
 
-  it("🔴 a missing file is reported where it stands, and left out", () => {
-    const main = "a\\input{gone}b";
-    const p = assemblePaper("paper.tex", main, deps({}));
+  it("a file the reader has none of contributes nothing", () => {
+    const p = assemblePaper("paper.tex", "a\\input{gone}b", deps({}));
     expect(p.text).toBe("ab");
-    expect(p.missing).toEqual([
-      {
-        file: "paper.tex",
-        target: "gone",
-        span: { start: 1, end: 13 },
-        via: { start: 1, end: 13 },
-      },
-    ]);
+    expect(p.segments.map((g) => g.file)).toEqual(["paper.tex", "paper.tex"]);
   });
 });
 
@@ -99,7 +90,7 @@ describe("assemblePaper — subfiles and a file that includes itself", () => {
       "<\\subfile{s}>",
       deps({ "s.tex": "ALL" }),
     );
-    expect(p.text).toBe("<ALL>");
+    expect(p.text).toBe("<ALL\n>");
   });
 
   it("a file that includes itself is entered once", () => {
@@ -108,7 +99,54 @@ describe("assemblePaper — subfiles and a file that includes itself", () => {
       "m\\input{a}",
       deps({ "a.tex": "a\\input{a}\\input{paper.tex}" }),
     );
-    expect(p.text).toBe("ma");
+    expect(p.text).toBe("ma\n");
+  });
+});
+
+describe("assemblePaper — TeX's end of line after the last line of an included file", () => {
+  // Measured with TeX Live 2026: `a\input f b` with f = `foo`, no final newline, typesets «afoo b» —
+  // the file's last line is ended like any other; `f` = `bar` plus a newline typesets the same; an
+  // empty file reads no line and adds nothing.
+  it("a file whose last line has no newline is ended, so what follows it is a new word", () => {
+    const p = assemblePaper(
+      "paper.tex",
+      "a\\input{f}b",
+      deps({ "f.tex": "foo" }),
+    );
+    expect(p.text).toBe("afoo\nb");
+  });
+
+  it("a file that ends with a newline gets no second one", () => {
+    const p = assemblePaper(
+      "paper.tex",
+      "a\\input{f}b",
+      deps({ "f.tex": "foo\n" }),
+    );
+    expect(p.text).toBe("afoo\nb");
+  });
+
+  it("an empty file reads no line: it adds nothing", () => {
+    const p = assemblePaper("paper.tex", "a\\input{f}b", deps({ "f.tex": "" }));
+    expect(p.text).toBe("ab");
+  });
+
+  it("the main file is not ended: its text is the caller's, as given", () => {
+    const p = assemblePaper("paper.tex", "no newline", deps({}));
+    expect(p.text).toBe("no newline");
+  });
+
+  it("the end of line belongs to the file it ends, at the end of that file", () => {
+    const p = assemblePaper(
+      "paper.tex",
+      "a\\input{f}b",
+      deps({ "f.tex": "foo" }),
+    );
+    expect(originOf(p, { start: 4, end: 5 })).toEqual({
+      file: "f.tex",
+      source: "foo",
+      span: { start: 3, end: 4 },
+      via: { start: 1, end: 10 },
+    });
   });
 });
 
@@ -129,7 +167,7 @@ describe("originOf — where a span of the assembled text comes from", () => {
   });
 
   it("after the include: offsets in the main file past the macro", () => {
-    expect(originOf(p, { start: 5, end: 7 })).toEqual({
+    expect(originOf(p, { start: 6, end: 8 })).toEqual({
       file: "paper.tex",
       source: "ab\\input{x}cd",
       span: { start: 11, end: 13 },
@@ -147,10 +185,10 @@ describe("originOf — where a span of the assembled text comes from", () => {
   });
 
   it("an empty span at the very end belongs to the last stretch; outside the text there is none", () => {
-    expect(originOf(p, { start: 7, end: 7 })?.span).toEqual({
+    expect(originOf(p, { start: 8, end: 8 })?.span).toEqual({
       start: 13,
       end: 13,
     });
-    expect(originOf(p, { start: 9, end: 9 })).toBe(null);
+    expect(originOf(p, { start: 10, end: 10 })).toBe(null);
   });
 });

package/src/domain/paper-source.ts

@@ -9,12 +9,19 @@
  * answers about one file (the class, the outline, the rendered text, the body's passages) is
  * answered about the paper, unchanged. A subfile is a document of its own; only its body is spliced.
  *
+ * ── THE END OF AN INCLUDED FILE'S LAST LINE ─────────────────────────────────────
+ * TeX ends every line it reads with its end-of-line character, the last line of a file included:
+ * `a\input{f}b` with `f` holding `foo` and no final newline typesets "afoo b" (measured, TeX Live
+ * 2026), not "afoob". The splice does the same: an included file whose text does not end in a newline
+ * gets one, mapped to the end of that file; an empty file read no line and gets nothing. The main file
+ * is the caller's text and is left as given.
+ *
  * ── WHAT IS NOT DONE ─────────────────────────────────────────────────────────────
  * No macro is expanded, so a path built from a macro (`\input{\dir/intro}`) is read as written. A
- * file that cannot be found is left out and named in `missing`; a file that includes itself,
- * directly or through others, is spliced once.
+ * file the caller's `read` has none of contributes nothing; a file that includes itself, directly or
+ * through others, is spliced once.
  */
-import { extname, normalize } from "node:path";
+import { posix } from "node:path";
 import type { Span } from "./tex-document.ts";
 
 /** One `\input`, `\include` or `\subfile` in a source: the path as written and where the macro stands. */
@@ -46,27 +53,17 @@ export interface Segment {
   readonly via: Span | null;
 }
 
-/** An include whose file was not found, where it stands. */
-export interface MissingInclude {
-  readonly file: string;
-  readonly target: string;
-  readonly span: Span;
-  /** Where it stands in the main file (the include itself, or the one that brought its file in). */
-  readonly via: Span;
-}
-
-/** The paper as one text, the map back to its files, and the includes that were not found. */
+/** The paper as one text, and the map back to its files. */
 export interface PaperSource {
   readonly main: string;
   readonly text: string;
   readonly segments: readonly Segment[];
-  readonly missing: readonly MissingInclude[];
 }
 
 /** The paths TeX tries for a target: `name.tex`, then `name` — or the name alone if it has one. */
 const candidates = (target: string): readonly string[] => {
-  const t = normalize(target.trim());
-  return extname(t) === "" ? [`${t}.tex`, t] : [t];
+  const t = posix.normalize(target.trim());
+  return posix.extname(t) === "" ? [`${t}.tex`, t] : [t];
 };
 
 /** The first candidate path that exists, with its text. */
@@ -81,11 +78,10 @@ function found(
   return hits[0] ?? null;
 }
 
-/** An assembled piece of text: the text, its segments from 0, and the includes not found. */
+/** An assembled piece of text: the text and its segments from 0. */
 interface Piece {
   readonly text: string;
   readonly segments: readonly Segment[];
-  readonly missing: readonly MissingInclude[];
 }
 
 /** `segments` moved by `by` characters. */
@@ -111,11 +107,10 @@ const copied = ({ file, text, from, to, via }: Stretch): Piece => ({
     to > from
       ? [{ start: 0, end: to - from, file, source: text, from, via }]
       : [],
-  missing: [],
 });
 
 /** Nothing: an include left out. */
-const NOTHING: Piece = { text: "", segments: [], missing: [] };
+const NOTHING: Piece = { text: "", segments: [] };
 
 /** Pieces joined in order. */
 const joined = (pieces: readonly Piece[]): Piece =>
@@ -123,7 +118,6 @@ const joined = (pieces: readonly Piece[]): Piece =>
     (acc, p) => ({
       text: acc.text + p.text,
       segments: [...acc.segments, ...shifted(p.segments, acc.text.length)],
-      missing: [...acc.missing, ...p.missing],
     }),
     NOTHING,
   );
@@ -153,7 +147,7 @@ function spliced(file: string, text: string, range: Span, ctx: Context): Piece {
       pieces: [
         ...acc.pieces,
         at(acc.cursor, inc.span.start),
-        included(file, inc, ctx),
+        included(inc, ctx),
       ],
       cursor: inc.span.end,
     }),
@@ -162,23 +156,30 @@ function spliced(file: string, text: string, range: Span, ctx: Context): Piece {
   return joined([...pieces, at(cursor, range.end)]);
 }
 
-/** One include: the file it names, spliced, or — when not found — nothing, and a report. */
-function included(file: string, inc: Include, ctx: Context): Piece {
+/** TeX's end of line after the last line of `file`, standing where its text ends: one newline. */
+const endOfLine = (file: string, text: string, via: Span | null): Piece => ({
+  text: "\n",
+  segments: [{ start: 0, end: 1, file, source: text, from: text.length, via }],
+});
+
+/** One include: the file it names, spliced, or — when the reader has none of it — nothing. */
+function included(inc: Include, ctx: Context): Piece {
   const via = ctx.via ?? inc.span;
   const hit = found(inc.target, ctx.deps.read);
-  if (hit === null)
-    return {
-      ...NOTHING,
-      missing: [{ file, target: inc.target, span: inc.span, via }],
-    };
-  if (ctx.stack.includes(hit.path)) return NOTHING;
+  if (hit === null || ctx.stack.includes(hit.path)) return NOTHING;
   const body = inc.macro === "subfile" ? ctx.deps.documentBody(hit.text) : null;
-  return spliced(
-    hit.path,
-    hit.text,
-    body ?? { start: 0, end: hit.text.length },
-    { deps: ctx.deps, stack: [...ctx.stack, hit.path], via },
-  );
+  const range = body ?? { start: 0, end: hit.text.length };
+  const piece = spliced(hit.path, hit.text, range, {
+    deps: ctx.deps,
+    stack: [...ctx.stack, hit.path],
+    via,
+  });
+  // The last line of the file is read to its end; a subfile's body ends inside its last line.
+  const endsLine =
+    range.end === hit.text.length &&
+    hit.text !== "" &&
+    !hit.text.endsWith("\n");
+  return endsLine ? joined([piece, endOfLine(hit.path, hit.text, via)]) : piece;
 }
 
 /** The paper whose main file is `main` (a path relative to the paper directory) with `text`. */
@@ -193,12 +194,7 @@ export function assemblePaper(
     { start: 0, end: text.length },
     { deps, stack: [main], via: null },
   );
-  return {
-    main,
-    text: p.text,
-    segments: p.segments,
-    missing: p.missing,
-  };
+  return { main, text: p.text, segments: p.segments };
 }
 
 /** Where a span of the assembled text stands: in which file, at which offsets, and via which include. */

package/src/domain/paper-sources.ts

@@ -0,0 +1,94 @@
+/**
+ * WHAT A DATABASE IS — the values the bibtex reader (`BibReader`, src/ports/bib-reader.ts) returns for
+ * a `.bib`, or for the body of a `filecontents` block: its entries, and the bytes bibtex takes from
+ * them. Which databases a paper reads is TeX's answer, recorded by the build (`_build/sources.json`,
+ * src/domain/sources-record.ts, docs/design/paper-sources.md §1); nothing here decides it.
+ */
+import type { AbsolutePath } from "./paths.ts";
+import type { Span } from "./tex-document.ts";
+
+/** The main file's name — the file TeX is given. */
+export const MAIN_FILE = "paper.tex";
+
+/** A name in a name list (`author`, `editor`), split into its parts as BibTeX defines them. */
+export interface BibName {
+  readonly lastName?: string;
+  readonly firstName?: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+  /** A name written as one unit (`{World Health Organization}`). */
+  readonly name?: string;
+}
+
+/**
+ * The `@string`s in force: each name as bibtex folds it (upper case) → its value as bibtex takes it,
+ * the `@string`s it used expanded and its LaTeX as written. bibtex reads a paper's databases one after
+ * the other with one table of them, so a `@string` an earlier database defines is in force in a later
+ * one (measured: `\\bibliography{abbreviations,references}` typesets an entry of `references.bib` with
+ * the author and booktitle `abbreviations.bib` defines; in the other order both are undefined).
+ */
+export type BibStrings = Readonly<Record<string, string>>;
+
+/** One entry of a database. */
+export interface BibEntry {
+  /** Lower-cased (`@Article` → `article`). */
+  readonly type: string;
+  readonly key: string;
+  /** From its `@` to its closing brace or parenthesis, in the text of the file that holds it. */
+  readonly span: Span;
+  /** Its fields, LaTeX read into text (`{\"u}` → `ü`, `\url{x}` → a link); a list field joined by ` and `. */
+  readonly fields: Readonly<Record<string, string>>;
+  /** Its name lists (`author`, `editor`, …), each name split into its parts. */
+  readonly names: Readonly<Record<string, readonly BibName[]>>;
+}
+
+/** The bytes of one database, where they sit, and what the reader read from them. */
+export interface BibText {
+  /** The file holding the bytes: the `.bib`, or the `.tex` that holds the block. */
+  readonly path: AbsolutePath;
+  /** That file's whole text; every span here is an offset into it. */
+  readonly text: string;
+  /** The database inside `text`: all of it for a `.bib`, the body for a block. */
+  readonly body: Span;
+  readonly entries: readonly BibEntry[];
+  /** The same entries as bibtex takes them, in order: what two databases are compared by. */
+  readonly written: readonly WrittenEntry[];
+  /** The `@preamble` commands, as written, in order: bibtex writes them into the `.bbl`. */
+  readonly preamble: readonly string[];
+  /** The `@string`s the databases bibtex read before this one left in force: none for one read alone. */
+  readonly inherited: BibStrings;
+  /** The `@string`s in force after it — `inherited` and its own, a later one winning: what the next database starts with. */
+  readonly strings: BibStrings;
+}
+
+/**
+ * An entry as bibtex takes it from the database: the type, the key, and each field's value with the
+ * `@string`s it uses expanded where it uses them (a later redefinition changes nothing) and its LaTeX
+ * as written — `{\"o}` and `ö` are different values here, as they are in the `.bbl` bibtex writes.
+ */
+export interface WrittenEntry {
+  /** Lower-cased, as bibtex reads it. */
+  readonly type: string;
+  readonly key: string;
+  /** Whitespace runs folded to one space, as bibtex folds them. */
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+/**
+ * What bibtex takes from a database, for comparing two: each entry as bibtex reads it, in order, its
+ * fields in name order, and the `@preamble` commands. Nothing else in the bytes reaches the `.bbl`:
+ * not the text between entries (a `filecontents` header among it), not a `@string` no entry uses.
+ */
+const contentOf = (b: BibText): string =>
+  JSON.stringify([
+    b.written.map((e) => [
+      e.type,
+      e.key,
+      Object.entries(e.fields).sort(([x], [y]) => x.localeCompare(y)),
+    ]),
+    b.preamble,
+  ]);
+
+/** Whether two databases hold the same, as TeX's own copy of a block holds the block's. */
+export const sameDatabase = (a: BibText, b: BibText): boolean =>
+  contentOf(a) === contentOf(b);

package/src/domain/sources-record.test.ts

@@ -0,0 +1,71 @@
+/**
+ * The record of a build as a value: the one text it is parsed from, what a rule reads off it, and what
+ * changed since it was made. The files it is about are `src/sources-record.test.ts`'s.
+ */
+import { describe, expect, it } from "vitest";
+import { parseSha256 } from "./sha256.ts";
+import {
+  changesSince,
+  describeChanges,
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "./sources-record.ts";
+
+const A = "a".repeat(64);
+const B = "b".repeat(64);
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+    { path: "sections/intro.tex", role: "body" },
+  ],
+  written: ["refs.bib"],
+  bibdata: ["refs"],
+  bibtex: {
+    ran: true,
+    databases: ["refs.bib"],
+    keys: ["k1"],
+    exit: 2,
+    errors: [{ message: "bad", file: "refs.bib", line: 4 }],
+  },
+  sha256: { "paper.tex": A, "macros.tex": null },
+};
+
+describe("serializing a record", () => {
+  it("is two-space JSON with a final newline, so a diff of two builds reads", () => {
+    expect(serializeSourcesRecord({ ...RECORD, bibtex: { ran: false } })).toBe(
+      `${JSON.stringify({ ...RECORD, bibtex: { ran: false } }, null, 2)}\n`,
+    );
+  });
+});
+
+describe("what changed since the record", () => {
+  const now = (files: Readonly<Record<string, string>>) => (p: string) =>
+    files[p] === undefined ? null : parseSha256(files[p]);
+
+  it("a record whose files are as hashed has no change, a file absent then and now included", () => {
+    expect(changesSince(RECORD, now({ "paper.tex": A }))).toEqual([]);
+  });
+
+  it("an edited file, a deleted one, and a file that appeared where there was none", () => {
+    expect(changesSince(RECORD, now({ "macros.tex": B }))).toEqual([
+      { path: "paper.tex", change: "deleted" },
+      { path: "macros.tex", change: "added" },
+    ]);
+    expect(changesSince(RECORD, now({ "paper.tex": B }))).toEqual([
+      { path: "paper.tex", change: "edited" },
+    ]);
+  });
+
+  it("names the changes in a line a finding can carry", () => {
+    expect(
+      describeChanges([
+        { path: "paper.tex", change: "edited" },
+        { path: "sections/a.tex", change: "deleted" },
+      ]),
+    ).toBe("paper.tex edited, sections/a.tex deleted");
+    expect(describeChanges([])).toBe("");
+  });
+});

package/src/domain/sources-record.ts

@@ -0,0 +1,136 @@
+/**
+ * WHAT THE LAST BUILD READ — `<paper>/_build/sources.json`, written by `paperlint build` from TeX's
+ * own files (docs/design/paper-sources.md §1) and read, offline, by the rules that need to know which
+ * files make up a paper and which bibliography it uses. Nothing else answers either question: no
+ * code of paperlint reads TeX source to decide them.
+ *
+ *   { "schema": 1,
+ *     "inputs":  [ { "path": "paper.tex", "role": "body" }, … ],  the files of the paper directory TeX
+ *                                                                 read, in first-read order
+ *     "written": [ "refs.bib" ],                                  the `.bib` and `.tex` files TeX wrote (filecontents)
+ *     "bibdata": [ "refs" ],                                      what `\bibdata` told bibtex to read
+ *     "bibtex":  { "ran": true, "databases": [ "refs.bib" ],      the files bibtex opened, the keys it
+ *                  "keys": [ … ], "exit": 0, "errors": [] },      typeset, how it ended
+ *     "sha256":  { "paper.tex": "…", … } }                        every input and every database bibtex
+ *                                                                 opened, by path and bytes
+ *
+ * 🔴 A role is the file's, and the main file is the body. A file is `preamble` when TeX read it only
+ * before `\begin{document}` — before it opened `paper.aux` for writing (measured) — and `body` when
+ * any read of it came after. The main file, the first one read, is `body` whatever its place in that
+ * order: it holds `\begin{document}` itself.
+ *
+ * The text of the file is checked once, where it enters: `SourcesCodec` (`src/ports/sources-codec.ts`),
+ * whose adapter holds the zod schema of this shape. The domain holds the value.
+ *
+ * 🔴 STALENESS is the record's own question: `changesSince` compares the bytes now with `sha256`, one
+ * key per file, so a rule can tell that the paper changed after the build without running TeX. A `.bib`
+ * TeX wrote is hashed too: the rules read it from disk, so an edit to it after the build is a change.
+ */
+import type { Sha256 } from "./sha256.ts";
+
+export const SOURCES_SCHEMA = 1;
+export const SOURCES_DIR = "_build";
+export const SOURCES_FILE = "sources.json";
+
+/** The job name every file a build writes carries (`paper.aux`, `paper.fls`): the build names its job so. */
+export const JOBNAME = "paper";
+
+/** Before or after `\begin{document}`. */
+export type InputRole = "preamble" | "body";
+
+/** One file of the paper directory that TeX read. `path` is relative to it, with forward slashes. */
+export interface RecordedInput {
+  readonly path: string;
+  readonly role: InputRole;
+}
+
+/** One error bibtex reported, as its `.blg` says it. */
+export interface BibtexError {
+  readonly message: string;
+  /** The file it was reading (`refs.bib`, `paper.aux`). */
+  readonly file: string;
+  /** Null when bibtex named no line. */
+  readonly line: number | null;
+}
+
+/** What the build's bibtex did — or that the build ran none (the paper names no database). */
+export type RecordedBibtex =
+  | { readonly ran: false }
+  | {
+      readonly ran: true;
+      /** The database files it opened, as it names them (`refs.bib`, `bibs/x.bib`). */
+      readonly databases: readonly string[];
+      /** The keys it typeset: every `\bibitem` of the `.bbl`. */
+      readonly keys: readonly string[];
+      readonly exit: number;
+      readonly errors: readonly BibtexError[];
+    };
+
+export interface SourcesRecord {
+  readonly schema: typeof SOURCES_SCHEMA;
+  readonly inputs: readonly RecordedInput[];
+  readonly written: readonly string[];
+  readonly bibdata: readonly string[];
+  readonly bibtex: RecordedBibtex;
+  /** Path → digest of its bytes; null for a file that was not there when the record was made. */
+  readonly sha256: Readonly<Record<string, string | null>>;
+}
+
+export type ParsedRecord =
+  | { readonly ok: true; readonly record: SourcesRecord }
+  | { readonly ok: false; readonly why: string };
+
+/** The record as the file holds it: two-space JSON and a final newline, so a diff of two builds reads. */
+export const serializeSourcesRecord = (r: SourcesRecord): string =>
+  `${JSON.stringify(r, null, 2)}\n`;
+
+// ── staleness ───────────────────────────────────────────────────────────────────────────
+
+export type ChangeKind = "edited" | "deleted" | "added";
+
+/** One file whose bytes are not those the build hashed. */
+export interface Change {
+  readonly path: string;
+  readonly change: ChangeKind;
+}
+
+/**
+ * The files whose bytes now differ from the record's: edited, deleted, or present where the record saw
+ * none. `now` answers for one path with the digest of its bytes, or null when there is no such file.
+ * Empty when the record is current.
+ */
+export function changesSince(
+  r: SourcesRecord,
+  now: (path: string) => Sha256 | null,
+): readonly Change[] {
+  return Object.entries(r.sha256).flatMap(
+    ([path, recorded]): readonly Change[] => {
+      const current = now(path);
+      if (current === recorded) return [];
+      if (current === null) return [{ path, change: "deleted" }];
+      return [{ path, change: recorded === null ? "added" : "edited" }];
+    },
+  );
+}
+
+/** `paper.tex edited, sections/a.tex deleted` — what a finding names. */
+export const describeChanges = (cs: readonly Change[]): string =>
+  cs.map((c) => `${c.path} ${c.change}`).join(", ");
+
+/**
+ * The name among `names` that `name` stands for: `name` itself, else the one name equal to it ignoring
+ * case — null when there is none, or several. TeX opens a file by the name the source gives it; on a
+ * file system that ignores case that is the source's spelling, on one that does not TeX retries
+ * without case, and the record holds the disk's spelling either way. A name and the record's spelling
+ * of it are matched by this, once, wherever one is looked up in the other.
+ */
+export function spelledIn(
+  names: readonly string[],
+  name: string,
+): string | null {
+  if (names.includes(name)) return name;
+  const [only, ...more] = names.filter(
+    (n) => n.toLowerCase() === name.toLowerCase(),
+  );
+  return only !== undefined && more.length === 0 ? only : null;
+}