chaffjs 0.34.0 → 0.36.0

package/src/detectors/blank-structure.ts

@@ -8,6 +8,7 @@ import { quoteAt } from "./structure-tree.ts";
 import { amountColumnOf, isTotalRowGap, type BodyRow } from "../structure/total-row-blank.ts";
 import { isAmountNameLine, isTotalLine } from "../structure/total-line.ts";
 import { isTotalLabel, withoutLeadingBlankCells } from "../structure/total.ts";
+import { isSpannedLabelGap } from "../structure/spanned-label-blank.ts";
 
 /** Fewer body rows than this, and one blank is as likely a choice as a gap. */
 const MIN_BODY_ROWS = 3;
@@ -67,8 +68,6 @@ const cellOffset = (cell: MarkdownNode | undefined, row: MarkdownNode | undefine
 /** Whether a row is a total, subtotal or tax row, judged from the row's source text. */
 export type IsTotalRow = (rowText: string) => boolean;
 
-const NO_TOTAL_ROWS: IsTotalRow = () => false;
-
 const rowSource = (source: string, row: MarkdownNode): string => {
   const span = spanOf(row);
   return span === undefined ? "" : source.slice(span.start, span.end);
@@ -79,30 +78,40 @@ const bodyRowOf = (source: string, row: MarkdownNode, isTotalRow: IsTotalRow): B
   cells: (row.children ?? []).map((cell) => (shows(cell) ? sourceOf(source, cell) : undefined)),
 });
 
+/** How a table's rows are read: which rows are totals, and the total words that make a cell a row label (Total score). */
+type TableReading = { readonly isTotalRow: IsTotalRow; readonly totalWords: readonly string[] };
+
+const NO_TOTALS: TableReading = { isTotalRow: () => false, totalWords: [] };
+
 /**
  * The one blank body cell of a column whose other body rows are all filled, unless it is a total row's blank beside its
- * amount. Such a blank still counts as a second blank, so the rows it shares a column with stay as unreported as before.
+ * amount, or the second column of a label that spans two (| Total score |  | 5 |). Such a blank still counts as a second
+ * blank, so the rows it shares a column with stay as unreported as before.
  */
-const columnBlank = (source: string, header: MarkdownNode, body: readonly MarkdownNode[], rows: readonly BodyRow[], column: number): Blank[] => {
+const columnBlank = (source: string, table: TableRows, totalWords: readonly string[], column: number): Blank[] => {
+  const { header, body, rows } = table;
   const blanks = rows.flatMap((row, index) => (row.cells[column] === undefined ? [index] : []));
   const at = blanks[0];
   const row = at === undefined ? undefined : rows[at];
   if (blanks.length !== 1 || at === undefined || row === undefined) return [];
   if (isTotalRowGap(row, column, amountColumnOf(rows, header.children?.length ?? 0))) return [];
+  if (isSpannedLabelGap(row.cells, column, totalWords)) return [];
   const offset = cellOffset(body[at]?.children?.[column], body[at]);
   const name = sourceOf(source, header.children?.[column]);
   return offset === undefined || name === "" ? [] : [{ offset, name }];
 };
 
+type TableRows = { readonly header: MarkdownNode; readonly body: readonly MarkdownNode[]; readonly rows: readonly BodyRow[] };
+
 /** The first column is skipped: a blank there often means "same as above". */
-const tableBlanksOf = (source: string, table: MarkdownNode, isTotalRow: IsTotalRow): Blank[] => {
+const tableBlanksOf = (source: string, table: MarkdownNode, reading: TableReading): Blank[] => {
   const [header, ...body] = table.children ?? [];
   if (header === undefined || body.length < MIN_BODY_ROWS) return [];
-  const rows = body.map((row) => bodyRowOf(source, row, isTotalRow));
+  const rows = body.map((row) => bodyRowOf(source, row, reading.isTotalRow));
   const columns = header.children?.length ?? 0;
   return Array.from({ length: columns }, (_unused, column) => column)
     .slice(1)
-    .flatMap((column) => columnBlank(source, header, body, rows, column));
+    .flatMap((column) => columnBlank(source, { header, body, rows }, reading.totalWords, column));
 };
 
 /** Quoted material is someone else's: email replies the document model found, and every Markdown blockquote. */
@@ -118,8 +127,8 @@ const blocksOutsideQuotes = (source: string, type: string, replies: readonly Spa
 };
 
 /** Blank cells in every table outside quotes. */
-export const tableBlanks = (source: string, replies: readonly Span[] = [], isTotalRow: IsTotalRow = NO_TOTAL_ROWS): Blank[] =>
-  blocksOutsideQuotes(source, "table", replies).flatMap((table) => tableBlanksOf(source, table, isTotalRow));
+export const tableBlanks = (source: string, replies: readonly Span[] = [], reading: TableReading = NO_TOTALS): Blank[] =>
+  blocksOutsideQuotes(source, "table", replies).flatMap((table) => tableBlanksOf(source, table, reading));
 
 type Item = { readonly node: MarkdownNode; readonly text: string | undefined; readonly empty: boolean };
 
@@ -192,5 +201,7 @@ const totalRowOf = (doc: ProseDocument): IsTotalRow => {
   return (rowText) => isTotalLine(rowText, totals) || isAmountNameLine(rowText, totals) || isTotalLabel(withoutLeadingBlankCells(rowText), taxes);
 };
 
-export const emptyTableCell: Detector = findingsOf("empty-table-cell", (doc) => tableBlanks(doc.source, doc.replyQuotes ?? [], totalRowOf(doc)));
+export const emptyTableCell: Detector = findingsOf("empty-table-cell", (doc) =>
+  tableBlanks(doc.source, doc.replyQuotes ?? [], { isTotalRow: totalRowOf(doc), totalWords: patternsOf(doc, "total-label") }),
+);
 export const emptyListItem: Detector = findingsOf("empty-list-item", (doc) => listBlanks(doc.source, doc.replyQuotes ?? []));

package/src/detectors/bracket-specified.ts

@@ -0,0 +1,25 @@
+import { asideAt } from "./open-end-names.ts";
+
+// A vague word pinned down by the bracket right after it: 一定の事項（インボイスに記載が必要な事項）, a reasonable fee (USD 50).
+// The aside says what the word leaves open, so the word is not vague there. An aside that only gives the phrase a name
+// (以下「措置」という, hereinafter the "Fee") pins nothing down. Pure: the words that start a name come in.
+
+/** What may stand between the vague word and the bracket: the noun it qualifies (事項, fee), no punctuation. */
+const BEFORE_BRACKET = /^[\p{L}\p{N}\p{M} ]{0,12}?(?=[（(])/u;
+
+const startsWithName = (aside: string, nameMarkers: readonly string[]): boolean => {
+  const lower = aside.trimStart().toLowerCase();
+  return nameMarkers.some((marker) => marker !== "" && lower.startsWith(marker.toLowerCase()));
+};
+
+/**
+ * Whether the words right after end (an offset in text) are pinned down by a bracket: at most a short noun, then an
+ * aside that opens and closes and holds more than a name. nameMarkers: the words that start a name (以下, hereinafter).
+ */
+export const specifiedByBracket = (text: string, end: number, nameMarkers: readonly string[]): boolean => {
+  const rest = text.slice(end);
+  const before = BEFORE_BRACKET.exec(rest);
+  if (before === null) return false;
+  const aside = asideAt(text, end + before[0].length);
+  return aside !== undefined && aside.trim() !== "" && !startsWithName(aside, nameMarkers);
+};

package/src/detectors/broken-link.ts

@@ -62,12 +62,36 @@ const CITATION_NUMBERS = /^[\d\s,，、–-]+$/u;
 /** 画像の参照（`![alt][label]`）の頭の印。指摘の範囲に含める。 */
 const IMAGE_MARK = "!";
 
+/** 印の前の逃がし（\）を数えるのに見る字数。 */
+const ESCAPE_REACH = 16;
+const BACKSLASH = "\\";
+
+/** 字の並びの終わりに続く \ の数。 */
+const trailingBackslashes = (text: string): number => {
+  const reversed = [...text].reverse();
+  const other = reversed.findIndex((char) => char !== BACKSLASH);
+  return other === -1 ? reversed.length : other;
+};
+
+/** start の括弧の直前に、逃がしていない ! がある（「\![x][]」は画像ではなくリンク）。 */
+const imageAt = (source: string, start: number): boolean => {
+  if (source.charAt(start - 1) !== IMAGE_MARK) return false;
+  return trailingBackslashes(source.slice(Math.max(0, start - 1 - ESCAPE_REACH), start - 1)) % 2 === 0;
+};
+
+/**
+ * 名前を省いた画像の参照（`![Complete][]`）は、サイトが全ページに定義を足す印や絵（mdBook の前処理、サイト共通の定義）。
+ * 画像の行き先をページの中で一度も書かずに名前だけで呼ぶのは、定義がページの外にあるとき。名前を書いた形（`![alt][logo]`）と
+ * リンク（`[text][]`）は指摘する。
+ */
+export const siteDefinedImage = (source: string, start: number, label: string): boolean => label === "" && imageAt(source, start);
+
 export const unresolvedReferences = (source: string, markup: Markup): Span[] =>
   markup.texts.flatMap((text) =>
     [...source.slice(text.start, text.end).matchAll(REFERENCE_LIKE)]
-      .filter((match) => !CITATION_NUMBERS.test(match[1] ?? ""))
+      .filter((match) => !CITATION_NUMBERS.test(match[1] ?? "") && !siteDefinedImage(source, text.start + match.index, match[2] ?? ""))
       .map((match) => ({ start: text.start + match.index, end: text.start + match.index + match[0].length }))
-      .map((span) => (source.charAt(span.start - 1) === IMAGE_MARK ? { start: span.start - 1, end: span.end } : span)),
+      .map((span) => (imageAt(source, span.start) ? { start: span.start - 1, end: span.end } : span)),
   );
 
 const emptyLinks = (doc: ProseDocument, markup: Markup): Finding[] =>

package/src/detectors/capitalised-term.ts

@@ -16,6 +16,18 @@ export type CapitalisedWords = {
   readonly divisions: readonly string[];
   /** Small words inside one name (Statement of Work, Trials and Betas). */
   readonly joiners: readonly string[];
+  /** Words that end a longer name the run only starts (Federal Food, Drug, and Cosmetic Act). */
+  readonly nameEnds: readonly string[];
+  /** Company forms and places, which end a name right after a comma too (Post Holdings, Inc.; Canton, Ohio). */
+  readonly formEnds: readonly string[];
+  /** Words before the quoted label in brackets that define the run ((the "FDA")). */
+  readonly definitionMarkers: readonly string[];
+  /** Words opening brackets that say where the run is defined ((as defined in the Merger Agreement)). */
+  readonly definedElsewhere: readonly string[];
+  /** Words before a party's capacity after its name (Citibank, N.A., as Administrative Agent). */
+  readonly capacityMarkers: readonly string[];
+  /** Articles, which may stand between a capacity word and the capacity (as the Borrower). */
+  readonly articles: readonly string[];
 };
 
 /** A term the document defines; bare is a definition with no defining word (("GPC")), which names more than it defines. */
@@ -100,15 +112,144 @@ const writtenInLowerCase = (text: string, term: string): boolean => {
   return new RegExp(String.raw`(?<!\p{L})${words}(?:e?s)?(?!\p{L})`, "u").test(text);
 };
 
+/** How many tokens past a run a longer name may still end (’s Investors Service, Inc: five). */
+const NAME_REACH = 8;
+/** Marks inside one name: Post Holdings, Inc; Davis Polk & Wardwell LLP; Moody’s Investors Service. */
+const NAME_GLUE = new Set([",", "&", ".", "'s", "’s"]);
+const DIGIT_START = /^\d/u;
+
+/** The last word of each name-ending entry (Kingdom of United Kingdom), without a closing full stop. */
+const lastWordsOf = (entries: readonly string[]): Set<string> =>
+  new Set(
+    entries
+      .flatMap((entry) =>
+        entry
+          .split(/[\s,]+/u)
+          .filter((word) => word !== "")
+          .slice(-1),
+      )
+      .map((word) => word.replace(/\.$/u, "")),
+  );
+
+/** Commas in a serial name's list (Federal Food, Drug, and Cosmetic Act). */
+const SERIAL_COMMAS = 2;
+
+type NameEnds = { readonly names: ReadonlySet<string>; readonly forms: ReadonlySet<string>; readonly formEntries: ReadonlySet<string> };
+
+/**
+ * Across a comma, a company form or a place ends the run's name only as the whole of what follows the comma (Post
+ * Holdings, Inc; London, United Kingdom), and a name word only at the end of a serial list of two commas, the last
+ * followed by a joiner (Federal Food, Drug, and Cosmetic Act): Confidential Information, Receiving Party and Servicer,
+ * Navistar Securities Corporation are two things each.
+ */
+const endsName = (glued: readonly Token[], at: number, ends: NameEnds, joiners: ReadonlySet<string>): boolean => {
+  const surface = glued[at]?.surface ?? "";
+  const before = glued.slice(0, at);
+  const surfaces = before.map((token) => token.surface);
+  const comma = surfaces.lastIndexOf(",");
+  if (comma === -1) return ends.forms.has(surface) || ends.names.has(surface);
+  const afterComma = glued.slice(comma + 1, at + 1);
+  if (ends.formEntries.has(afterComma.map((token) => token.surface).join(" "))) return true;
+  const commas = surfaces.filter((each) => each === ",").length;
+  return ends.names.has(surface) && commas >= SERIAL_COMMAS && joiners.has(afterComma[0]?.surface ?? "");
+};
+
+/** The run only starts a longer name: the words after it, joined by commas, ampersands and joiners, reach a word that ends a name. */
+const startsLongerName = (tokens: readonly Token[], end: number, ends: NameEnds, joiners: ReadonlySet<string>): boolean => {
+  const reach = tokens.slice(end, end + NAME_REACH);
+  const stop = reach.findIndex((token, at) => {
+    const before = tokens[end + at - 1];
+    return before === undefined || !adjacent(before, token) || !(NAME_GLUE.has(token.surface) || joiners.has(token.surface) || continues(token));
+  });
+  const glued = reach.slice(0, stop === -1 ? reach.length : stop);
+  return glued.some((_, at) => endsName(glued, at, ends, joiners));
+};
+
+/** A number right after the run makes it a numbered name (Proposition 65, Vaccines 2Go) or a contents line's page. */
+const numberedName = (last: Token, after: Token | undefined): boolean => after !== undefined && adjacent(last, after) && DIGIT_START.test(after.surface);
+
+/** The words as written and with their first letter capitalised (the, The), as one alternation. */
+const alternativesOf = (words: readonly string[]): string =>
+  words
+    .filter((word) => word !== "")
+    .flatMap((word) => [word, word.charAt(0).toUpperCase() + word.slice(1)])
+    .map(escapeRegExp)
+    .join("|");
+
+/** A quoted label: a capitalised word or more in quotes, closing the brackets or followed by another label ("Buyer" or "PNC"). */
+const QUOTED_LABEL = String.raw`["“]\p{Lu}[^"“”\n]{0,60}["”][ \t]*(?:\)|,|;|or[ \t]|and[ \t])`;
+
+/**
+ * Brackets right after a run that define it, so the run is what a definition names, not a term in use: a quoted label
+ * (Food and Drug Administration (the "FDA"), Certificate of Analysis ("COA")) or a pointer to where it is defined
+ * (Closing (as defined in the Merger Agreement)). A quoted phrase in lower case (("including records")) is no label.
+ */
+const definitionAfterPattern = (words: CapitalisedWords): RegExp => {
+  const markers = alternativesOf(words.definitionMarkers);
+  const elsewhere = alternativesOf(words.definedElsewhere);
+  const label = markers === "" ? QUOTED_LABEL : String.raw`(?:(?:${markers})[ \t]+)*${QUOTED_LABEL}`;
+  const opening = elsewhere === "" ? label : String.raw`(?:${label}|(?:${elsewhere})(?!\p{L}))`;
+  return new RegExp(String.raw`^[ \t]*\([ \t]*${opening}`, "u");
+};
+
+/** How much text after a run the bracket check reads. */
+const DEFINITION_AFTER_CHARS = 120;
+
+/** The initials of a run's words, with and without its joiners (PFHOF and PFHF for Pro Football Hall of Fame). */
+const initialsOf = (term: string, joiners: ReadonlySet<string>): string[] => {
+  const words = term.split(/[\s-]+/u).filter((word) => word !== "");
+  const initials = (kept: readonly string[]): string => kept.map((word) => word.charAt(0).toUpperCase()).join("");
+  return words.length < 2 ? [] : [initials(words), initials(words.filter((word) => !joiners.has(word)))];
+};
+
+/**
+ * The run names the capacity a named party acts in, in a list of parties to some agreement (Citibank, N.A., as
+ * Administrative Agent; the Company, as the Borrower): the name, a comma, a capacity word and perhaps an article.
+ */
+const capacityOfAName = (tokens: readonly Token[], start: number, words: CapitalisedWords): boolean => {
+  const before = tokens[start - 1];
+  const at = before !== undefined && words.articles.includes(before.surface) ? start - 2 : start - 1;
+  const marker = tokens[at];
+  const comma = tokens[at - 1];
+  const name = tokens[at - 2];
+  if (marker === undefined || comma?.surface !== "," || name === undefined) return false;
+  return words.capacityMarkers.includes(marker.surface) && (continues(name) || name.surface === ".");
+};
+
+/**
+ * Whether a run is a name by what surrounds it: a number after it, a longer name it starts, brackets after it that
+ * define it, initials that spell a term the document defines (“IRS” means the Internal Revenue Service), or a capacity.
+ */
+type NameCue = (tokens: readonly Token[], start: number, end: number, term: string) => boolean;
+
+const nameCues = (input: CapitalisedInput, joiners: ReadonlySet<string>): NameCue => {
+  const words = input.words;
+  const ends = { names: lastWordsOf(words.nameEnds), forms: lastWordsOf(words.formEnds), formEntries: new Set(words.formEnds) };
+  const definitionAfter = definitionAfterPattern(words);
+  const abbreviations = new Set([...input.defined.map((definition) => definition.term), ...input.named].filter((term) => ACRONYM.test(term)));
+  return (tokens, start, end, term) => {
+    const last = tokens[end - 1];
+    if (last === undefined) return false;
+    return (
+      numberedName(last, tokens[end]) ||
+      startsLongerName(tokens, end, ends, joiners) ||
+      definitionAfter.test(input.source.slice(last.span.end, last.span.end + DEFINITION_AFTER_CHARS)) ||
+      initialsOf(term, joiners).some((initials) => abbreviations.has(initials)) ||
+      capacityOfAName(tokens, start, words)
+    );
+  };
+};
+
 /**
  * The first use of each capitalised run used inside a sentence like a defined term that names nothing the language
  * package lists, is not set apart by markup, is never written in lower case, and neither is nor holds a defined or named
- * term in any case.
+ * term in any case. A run that starts a longer name, carries a number, or is defined by the brackets after it is a name.
  */
 export const capitalisedTerms = (input: CapitalisedInput): CapitalisedTerm[] => {
   const defining = input.defined.filter((definition) => definition.bare !== true && DEFINED_FORM.test(definition.term));
   if (defining.length < MIN_DEFINED) return [];
   const joiners = new Set(input.words.joiners);
+  const isName = nameCues(input, joiners);
   const divisions = new Set(input.words.divisions.flatMap(formsOf));
   const known = new Set([...input.defined.map((definition) => definition.term), ...input.named, ...input.words.names].flatMap(formsOf));
   const isKnown = (term: string): boolean => partsOf(term).some((part) => formsOf(part).some((form) => known.has(form)));
@@ -119,7 +260,8 @@ export const capitalisedTerms = (input: CapitalisedInput): CapitalisedTerm[] =>
       if (first === undefined || last === undefined || !placedLikeATerm(tokens[start - 1], tokens[end])) return [];
       if (inside(first.span.start, input.marked) || formsOf(first.surface).some((form) => divisions.has(form))) return [];
       const term = input.source.slice(first.span.start, last.span.end);
-      return isKnown(term) || writtenInLowerCase(input.readable, term) ? [] : [{ offset: first.span.start, term }];
+      if (isKnown(term) || isName(tokens, start, end, term)) return [];
+      return writtenInLowerCase(input.readable, term) ? [] : [{ offset: first.span.start, term }];
     }),
   );
   return uses.filter((use, index) => uses.findIndex((other) => formsOf(other.term).some((form) => formsOf(use.term).includes(form))) === index);
@@ -130,12 +272,20 @@ const QUOTED = /["“]([^"“”\n]{1,80}?)[,.]?["”]/gu;
 const HTML_ELEMENT = /<([a-z][a-z0-9]*)\b[^>]*>[^<]*<\/\1>/giu;
 const TABLE_ROW = /^[ \t]*\|.*$/gmu;
 const ITEM_LABEL = /^[ \t]*(?:[*+-]|\d+[.)])[ \t]+[^:\n]{1,80}:/gmu;
+const CAPTION_WORD = String.raw`\p{Lu}[\p{L}'’-]*`;
+const CAPTION_SMALL = String.raw`(?:of|and|or|to|the|for|with|in|on|a|an|by|from|under|upon|as|at|not)[ \t]+`;
+/** A clause's run-in caption: its number, then capitalised words up to a full stop or colon (5.8 No Representation or Warranty.). */
+const CAPTION = new RegExp(
+  String.raw`(?:^|(?<=[.;:][ \t]+))[ \t]*(?:(?:Section|Article|SECTION|ARTICLE)[ \t]+)?(?:\d+(?:\.\d+)*\.?|\([a-z\d]{1,4}\))[ \t]+` +
+    String.raw`${CAPTION_WORD}(?:(?:[ \t]+|[;,][ \t]*)(?:${CAPTION_SMALL})*${CAPTION_WORD}){0,10}(?=[.:](?:\s|$))`,
+  "gmu",
+);
 
 const spansOf = (source: string, pattern: RegExp): Span[] =>
   [...source.matchAll(pattern)].map((match) => ({ start: match.index, end: match.index + match[0].length }));
 
-/** Bold, HTML elements, table rows and list items' labels in a Markdown source: labels and cells, not running text. */
-export const setApartSpans = (source: string): Span[] => [BOLD, HTML_ELEMENT, TABLE_ROW, ITEM_LABEL].flatMap((pattern) => spansOf(source, pattern));
+/** Bold, HTML elements, table rows, list items' labels and clauses' run-in captions: labels and cells, not running text. */
+export const setApartSpans = (source: string): Span[] => [BOLD, HTML_ELEMENT, TABLE_ROW, ITEM_LABEL, CAPTION].flatMap((pattern) => spansOf(source, pattern));
 
 const LINK_DESTINATION = /\]\([^)\n]*\)|<?https?:\/\/[^\s)>]+>?/gu;
 

package/src/detectors/caps-caption.ts

@@ -0,0 +1,103 @@
+/**
+ * Captions set in capitals: a capital run that opens a paragraph and ends in a colon ("AGENCY:", "DIRECT HIRE AUTHORITY:
+ * This position is …"), or that is a paragraph of its own ("WORKING GROUP MEMBERS"). Notices, forms and reports set their
+ * captions this way by convention, and prose that names one ("the FOR FURTHER INFORMATION CONTACT section") repeats it.
+ * A line of a hard-wrapped paragraph in capitals (a disclaimer) has text above it, so it is no caption.
+ */
+import { linesOf, type Line } from "../structure/lines.ts";
+import type { Span } from "../plugin.ts";
+
+/** Markdown heading or list marks and spaces that may stand before a caption on its line. */
+const LINE_LEAD = /^[ \t]*(?:#{1,6}[ \t]+|[-*+][ \t]+)?$/u;
+const BLANK_LINE = /^[ \t\r]*$/u;
+const LINE_END = /^[ \t\r]*(?:\n|$)/u;
+const LEAD = /^[ \t]*(?:#{1,6}[ \t]+|[-*+][ \t]+)?/u;
+const CAPITAL_RUN = /^[A-Z][A-Z']*(?:,? [A-Z][A-Z']*)*/u;
+
+/** The line before the one that starts at lineStart, or undefined at the start of the source. */
+const lineBefore = (source: string, lineStart: number): string | undefined =>
+  lineStart === 0 ? undefined : source.slice(source.lastIndexOf("\n", lineStart - 2) + 1, lineStart - 1);
+
+const opensParagraph = (source: string, lineStart: number): boolean => {
+  const above = lineBefore(source, lineStart);
+  return above === undefined || BLANK_LINE.test(above);
+};
+
+/** Whether the text after a run ends the caption: a colon, or the end of a paragraph. */
+const endsCaption = (rest: string): boolean => {
+  if (rest.startsWith(":")) return true;
+  if (!LINE_END.test(rest)) return false;
+  const next = rest.slice(rest.indexOf("\n") + 1).split("\n", 1)[0] ?? "";
+  return !rest.includes("\n") || BLANK_LINE.test(next);
+};
+
+/** Whether the capital run at [start, end) of the source is a caption: it opens its paragraph and ends in a colon or the paragraph's end. */
+export const isCaptionAt = (source: string, start: number, end: number): boolean => {
+  const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+  return LINE_LEAD.test(source.slice(lineStart, start)) && opensParagraph(source, lineStart) && endsCaption(source.slice(end));
+};
+
+/** The capital run that opens a line, after its heading or list mark, with where it starts in the source. */
+const runOpening = (line: string, lineStart: number): { readonly words: string; readonly start: number } | undefined => {
+  const lead = LEAD.exec(line)?.[0].length ?? 0;
+  const words = CAPITAL_RUN.exec(line.slice(lead))?.[0];
+  return words === undefined ? undefined : { words, start: lineStart + lead };
+};
+
+/** The captions a source sets in capitals, each as its words ("FOR FURTHER INFORMATION CONTACT"). */
+export const captionsOf = (source: string): ReadonlySet<string> => {
+  const lines = source.split("\n");
+  const starts = lines.reduce<number[]>(
+    (acc, line) => {
+      acc.push((acc.at(-1) ?? 0) + line.length + 1);
+      return acc;
+    },
+    [0],
+  );
+  return new Set(
+    lines.flatMap((line, at) => {
+      const run = runOpening(line, starts[at] ?? 0);
+      return run !== undefined && isCaptionAt(source, run.start, run.start + run.words.length) ? [run.words] : [];
+    }),
+  );
+};
+
+/** A line ends a sentence when its last mark, past closing quotes and brackets, is a period, a question or an exclamation mark. */
+const SENTENCE_END = /[.!?]["'”’)\]]*[ \t\r]*$/u;
+const UPPER = /[A-Z]/u;
+const LOWER = /[a-z]/u;
+
+const isCapitalLine = (line: Line): boolean => {
+  const bare = line.text.replace(LEAD, "");
+  return UPPER.test(bare) && !LOWER.test(bare);
+};
+
+/** The lines in paragraphs: runs of lines between blank lines. */
+const paragraphsOf = (lines: readonly Line[]): Line[][] =>
+  lines.reduce<Line[][]>((paragraphs, line, index) => {
+    if (BLANK_LINE.test(line.text)) return paragraphs;
+    const above = lines[index - 1];
+    if (above !== undefined && !BLANK_LINE.test(above.text)) paragraphs.at(-1)?.push(line);
+    else paragraphs.push([line]);
+    return paragraphs;
+  }, []);
+
+const spanOf = (paragraph: readonly Line[]): Span[] => {
+  const first = paragraph[0];
+  const last = paragraph.at(-1);
+  return first === undefined || last === undefined ? [] : [{ start: first.start, end: last.start + last.text.length }];
+};
+
+/**
+ * The paragraphs in capitals at the head of a document, before its first sentence: a letterhead, an office's name, an
+ * address block (BOARD OF GOVERNORS / WASHINGTON, D.C. 20551). Every line is in capitals and none ends a sentence, so a
+ * disclaimer in capitals, which is sentences, is not one. A document with no sentence has no head to tell apart.
+ */
+export const letterheadSpans = (source: string): Span[] => {
+  const paragraphs = paragraphsOf(linesOf(source));
+  const firstSentence = paragraphs.findIndex((paragraph) => paragraph.some((line) => SENTENCE_END.test(line.text)));
+  return paragraphs
+    .slice(0, Math.max(firstSentence, 0))
+    .filter((paragraph) => paragraph.every(isCapitalLine))
+    .flatMap(spanOf);
+};

package/src/detectors/caps-phrase.ts

@@ -0,0 +1,17 @@
+// Phrases set in capitals by convention ("NOW, THEREFORE, BE IT RESOLVED" in a resolution). Pure.
+import { escapeRegExp } from "../orthography.ts";
+
+const COMMA_OR_SPACE = /,?\s+/u;
+
+const wordsOf = (text: string): string => text.trim().split(COMMA_OR_SPACE).join(" ");
+
+/**
+ * Whether a run of capitals is made only of the listed phrases of several words, one after another ("NOW, THEREFORE" then
+ * "BE IT RESOLVED"). A comma after a word, as a run of capitals writes it, is ignored. One-word entries (MUST) match nothing here.
+ */
+export const isConventionalPhrase = (run: string, entries: Iterable<string>): boolean => {
+  const phrases = [...entries].map(wordsOf).filter((phrase) => phrase.includes(" "));
+  if (phrases.length === 0) return false;
+  const one = `(?:${phrases.map(escapeRegExp).join("|")})`;
+  return new RegExp(`^${one}(?: ${one})*$`, "u").test(wordsOf(run));
+};