chaffjs 0.27.1 → 0.29.0

package/src/structure/date-order.ts

@@ -1,9 +1,11 @@
 import type { StructureIssue } from "./issues.ts";
-import { runsOf, type Line } from "./runs.ts";
+import { siblingHeadingRunsOf } from "./heading-runs.ts";
+import { runsOf } from "./runs.ts";
 
 /**
- * 日程として並べた日付の順番。箇条書きの続いた項目か、表の続いた行で、日付をちょうど一つ持つものを並びとして読む。
- * 並びの向き（古い順か新しい順か）は多いほうで決め、それに逆らう一歩だけを言う。新しい順に並べた履歴は正しい並び。
+ * 日程として並べた日付の順番。箇条書きの続いた項目、表の続いた行、同じ親の下で同じ深さに並ぶ見出しで、
+ * 日付をちょうど一つ持つものを並びとして読む。
+ * 並びの向き（古い順か新しい順か）は多いほうで決め、それに逆らう一歩ごとに、その前後のうち並びから外れた日付を言う。新しい順に並べた履歴は正しい並び。
  * 向きが決まらない並び（上がりと下がりが同じ数）は何も言わない。逆らう一歩を言えるのは、日付が 4 つ以上の並びだけになる。
  * 向きに沿って並ぶ日付が半分以下の並びは、日付でなく別のもの（名前、版）で並べた一覧として何も言わない。
  */
@@ -12,13 +14,41 @@ export type DatedPoint = { readonly offset: number; readonly value: string };
 /** 並びとして比べられる日付の書き方。年月日、年月、月日は、同じ書き方どうしでしか比べない。 */
 const PRECISIONS = [/^\d{4}-\d{2}-\d{2}$/u, /^\d{4}-\d{2}$/u, /^\d{2}-\d{2}$/u];
 
-/** 行ごとの日付。ちょうど一つの行だけを並びに入れる。二つある行（期間）はどちらを並べたのか決められない。 */
-const datedLines = (run: readonly Line[], points: readonly DatedPoint[]): DatedPoint[] =>
+/** 並びの一行（箇条書きの項目、表の行、見出し）の原文の範囲。 */
+type Span = { readonly start: number; readonly end: number };
+
+/** 見出しの深さと原文の範囲。 */
+export type HeadingSpan = Span & { readonly depth: number };
+
+/**
+ * 同じ親の下で同じ深さに並ぶ見出し（変更履歴の版ごとの見出し）。浅い見出しが来たら、それより深い並びは閉じる。
+ * 深い見出し（### 追加）は並びを切らず、親ごとに別の並びになる。
+ */
+export const siblingHeadingRuns = (headings: readonly HeadingSpan[]): HeadingSpan[][] => siblingHeadingRunsOf(headings, (heading) => heading);
+
+/** 一行のただ一つの日付。二つある行（期間）はどちらを並べたのか決められないので、並びに入れない。 */
+const onlyDateIn = (line: Span, points: readonly DatedPoint[]): DatedPoint | undefined => {
+  const inside = points.filter((point) => point.offset >= line.start && point.offset <= line.end);
+  return inside.length === 1 ? inside[0] : undefined;
+};
+
+const datedLines = (run: readonly Span[], points: readonly DatedPoint[]): DatedPoint[] =>
   run.flatMap((line) => {
-    const inside = points.filter((point) => point.offset >= line.start && point.offset <= line.end);
-    return inside.length === 1 && inside[0] !== undefined ? [inside[0]] : [];
+    const date = onlyDateIn(line, points);
+    return date === undefined ? [] : [date];
   });
 
+/** 見出しの並びは、日付を一つ持つ見出しが続くあいだだけ。日付の無い見出しが混じる並び（問いに更新日を添えた FAQ）は、日付で並べたものではない。 */
+const datedStretches = (run: readonly Span[], points: readonly DatedPoint[]): DatedPoint[][] =>
+  run.reduce<DatedPoint[][]>(
+    (stretches, heading) => {
+      const date = onlyDateIn(heading, points);
+      if (date === undefined) return [...stretches, []];
+      return [...stretches.slice(0, -1), [...(stretches.at(-1) ?? []), date]];
+    },
+    [[]],
+  );
+
 const samePrecision = (dated: readonly DatedPoint[]): boolean => PRECISIONS.some((pattern) => dated.every((point) => pattern.test(point.value)));
 
 /** 上がりが多ければ 1、下がりが多ければ -1、同じ数なら 0（向きを決めない）。 */
@@ -37,23 +67,43 @@ export const longestInOrder = (values: readonly string[], direction: number): nu
 /** 日付のうち向きに沿うものが過半を占める。ひとつふたつの書き間違いなら残りが揃うが、名前順の一覧は揃わない。 */
 const mostlyInOrder = (values: readonly string[], direction: number): boolean => longestInOrder(values, direction) * 2 > values.length;
 
-/** 多いほうの向きに逆らう一歩。後ろの項目の日付を指す。 */
+const without = (values: readonly string[], index: number): string[] => values.filter((_, at) => at !== index);
+
+/**
+ * 向きに逆らう一歩（at - 1 から at）のうち、並びから外れているほう。取り除いたとき残りが長く揃うほうを指す。
+ * 前を取っても後ろを取っても同じだけ揃う（隣どうしの入れ替わり）なら、どちらとも決められないので後ろを指す。
+ */
+export const outOfPlace = (values: readonly string[], at: number, direction: number): number =>
+  longestInOrder(without(values, at - 1), direction) > longestInOrder(without(values, at), direction) ? at - 1 : at;
+
+/** 外れた日付に、前の日付を添える。先頭の日付には前が無いので、次の日付を添える。 */
+const issueAt = (dated: readonly DatedPoint[], at: number): StructureIssue[] => {
+  const point = dated[at];
+  if (point === undefined) return [];
+  const neighbour = at === 0 ? { next: dated[1]?.value ?? "" } : { previous: dated[at - 1]?.value ?? "" };
+  return [{ offset: point.offset, values: { date: point.value, ...neighbour } }];
+};
+
+/** 多いほうの向きに逆らう一歩ごとに、並びから外れた日付を指す。 */
 const againstMajority = (dated: readonly DatedPoint[]): StructureIssue[] => {
-  const steps = dated
-    .slice(1)
-    .map((point, index) => ({ point, previous: dated[index], sign: Math.sign(point.value.localeCompare(dated[index]?.value ?? "")) }));
-  const up = steps.filter((step) => step.sign > 0).length;
-  const down = steps.filter((step) => step.sign < 0).length;
-  const majority = majorityOf(up, down);
   const values = dated.map((point) => point.value);
+  const signs = values.slice(1).map((value, index) => Math.sign(value.localeCompare(values[index] ?? "")));
+  const majority = majorityOf(signs.filter((sign) => sign > 0).length, signs.filter((sign) => sign < 0).length);
   if (majority === 0 || !mostlyInOrder(values, majority)) return [];
-  return steps
-    .filter((step) => step.sign === -majority)
-    .map((step) => ({ offset: step.point.offset, values: { date: step.point.value, previous: step.previous?.value ?? "" } }));
+  return signs.flatMap((sign, index) => {
+    if (sign !== -majority) return [];
+    return issueAt(dated, outOfPlace(values, index + 1, majority));
+  });
 };
 
-export const dateOrderBreaks = (source: string, points: readonly DatedPoint[]): StructureIssue[] =>
-  runsOf(source).flatMap((run) => {
-    const dated = datedLines(run, points);
-    return samePrecision(dated) ? againstMajority(dated) : [];
-  });
+const breaksIn = (dated: readonly DatedPoint[]): StructureIssue[] => (samePrecision(dated) ? againstMajority(dated) : []);
+
+/** 見出しを箇条書きの中に書けば（「- ## 3.1.0 - 2026-10-02」）、同じ日付が両方の並びに入る。一度だけ言う。 */
+const oncePerOffset = (issues: readonly StructureIssue[]): StructureIssue[] =>
+  issues.filter((issue, index) => issues.findIndex((other) => other.offset === issue.offset) === index);
+
+export const dateOrderBreaks = (source: string, points: readonly DatedPoint[], headings: readonly HeadingSpan[] = []): StructureIssue[] =>
+  oncePerOffset([
+    ...runsOf(source).flatMap((run) => breaksIn(datedLines(run, points))),
+    ...siblingHeadingRuns(headings).flatMap((run) => datedStretches(run, points).flatMap(breaksIn)),
+  ]);

package/src/structure/date-outside-period.ts

@@ -0,0 +1,127 @@
+import { escapeRegExp } from "../orthography.ts";
+import type { StructureIssue } from "./issues.ts";
+import { TABLE_ROW } from "./runs.ts";
+import { statedPeriod, type DateMention, type Period, type PeriodWords } from "./stated-period.ts";
+
+/**
+ * 書いた期間の外の日付。期間の語で始まる一行（旅行期間：…）が期間を書き、その後ろ、同じ節の中の箇条書きの項目、表の行、見出しの日付を比べる。
+ * 地の文の日付は、年の無いもの（2月12日（金）の午前は…）だけを比べる。年のある日付は、過去の回や別の年の出来事を挙げることが多い。
+ * 期間の前後に置く予定（前泊、follow-up）、締め切りや予約の日、過去の回を言う語（period-aside）が、その行、文、節の見出しにあれば比べない。
+ * 年の無い期間（12月28日〜1月4日）は年をまたいで読む。
+ */
+export type HeadingSpan = { readonly start: number; readonly end: number; readonly depth: number };
+type Span = { readonly start: number; readonly end: number };
+
+export type OutsideWords = PeriodWords & { readonly asides: readonly string[] };
+
+const LIST_ITEM = /^[ \t]{0,12}(?:[-*+]|\d{1,3}[.)])[ \t]/u;
+const DAY_VALUE = /^(?:\d{4}-)?\d{2}-\d{2}$/u;
+
+const hasYear = (value: string): boolean => value.length === "2026-01-01".length;
+const monthDay = (value: string): string => value.slice(-"01-01".length);
+
+/** 期間の中か。両方に年があれば年月日で、どちらかに年が無ければ月日で比べ、終わりが始まりより前の月日は年をまたぐ期間と読む。 */
+export const insidePeriod = (value: string, period: Pick<Period, "start" | "end">): boolean => {
+  if (hasYear(value) && hasYear(period.start)) return value >= period.start && value <= period.end;
+  const [from, to, day] = [monthDay(period.start), monthDay(period.end), monthDay(value)];
+  return from <= to ? day >= from && day <= to : day >= from || day <= to;
+};
+
+const linesOf = (source: string): Span[] =>
+  source.split("\n").reduce<Span[]>((lines, text) => {
+    const start = (lines.at(-1)?.end ?? -1) + 1;
+    return [...lines, { start, end: start + text.length }];
+  }, []);
+
+const containing = <Item extends Span>(spans: readonly Item[], offset: number): Item | undefined =>
+  spans.find((span) => span.start <= offset && offset <= span.end);
+
+/** 英字の語は語の切れ目で、ほかは含むかで照らす。 */
+export const mentions = (text: string, words: readonly string[]): boolean => {
+  const lower = text.toLowerCase();
+  return words.some((word) => {
+    const target = word.toLowerCase();
+    if (!/[a-z]/u.test(target)) return lower.includes(target);
+    return new RegExp(`(?<![a-z])${escapeRegExp(target)}(?![a-z])`, "u").test(lower);
+  });
+};
+
+type Stated = Period & { readonly scopeStart: number; readonly scopeEnd: number };
+
+/**
+ * 期間の及ぶ範囲の始まり: 期間の行の後ろ。期間の行が箇条書きの項目なら、その箇条書きの後ろ。
+ * 「- Conference: May 3–5」「- Workshop: May 7」は催しを並べた一覧で、並んだ項目は期間の中の予定ではない。
+ */
+const scopeStart = (source: string, lines: readonly Span[], line: Span): number => {
+  const isListLine = (span: Span): boolean => LIST_ITEM.test(source.slice(span.start, span.end));
+  if (!isListLine(line)) return line.end;
+  const after = lines.filter((span) => span.start > line.start);
+  const listEnd = after.findIndex((span) => !isListLine(span));
+  return (listEnd === -1 ? (after.at(-1) ?? line) : (after[listEnd - 1] ?? line)).end;
+};
+
+/** 期間の行が属する節の深さ。行が見出しならその深さ、そうでなければ前の見出しの深さ（見出しの前なら 0）。 */
+const depthAt = (line: Span, headings: readonly HeadingSpan[]): number =>
+  (containing(headings, line.start) ?? headings.filter((heading) => heading.start < line.start).at(-1))?.depth ?? 0;
+
+/** 期間の及ぶ範囲の終わり: 同じか浅い深さの次の見出しか、次の期間の行。 */
+const scopeEnd = (line: Span, next: number, headings: readonly HeadingSpan[], length: number): number => {
+  const depth = depthAt(line, headings);
+  const closing = headings.find((heading) => heading.start > line.end && heading.depth <= depth)?.start ?? length;
+  return Math.min(closing, next);
+};
+
+const statedPeriods = (
+  source: string,
+  lines: readonly Span[],
+  dates: readonly DateMention[],
+  headings: readonly HeadingSpan[],
+  words: OutsideWords,
+): Stated[] => {
+  const found = lines.flatMap((line) => {
+    const period = statedPeriod(source.slice(line.start, line.end), line.start, dates, words);
+    return period === undefined ? [] : [{ period, line }];
+  });
+  return found.map(({ period, line }, index) => ({
+    ...period,
+    scopeStart: scopeStart(source, lines, line),
+    scopeEnd: scopeEnd(line, found[index + 1]?.line.start ?? source.length, headings, source.length),
+  }));
+};
+
+const isItem = (text: string, line: Span, headings: readonly HeadingSpan[]): boolean =>
+  LIST_ITEM.test(text) || TABLE_ROW.test(text) || containing(headings, line.start) !== undefined;
+
+type Context = { readonly source: string; readonly lines: readonly Span[]; readonly headings: readonly HeadingSpan[]; readonly sentences: readonly Span[] };
+
+/** 日付を囲む行（項目）か文（地の文）と、その節の見出し。期間の外に置く語を探す所。 */
+const surroundings = (date: DateMention, line: Span, item: boolean, context: Context): string[] => {
+  const unit = item ? line : (containing(context.sentences, date.offset) ?? line);
+  const heading = context.headings.filter((candidate) => candidate.start <= date.offset).at(-1);
+  return [context.source.slice(unit.start, unit.end), heading === undefined ? "" : context.source.slice(heading.start, heading.end)];
+};
+
+const outsideOne = (date: DateMention, period: Stated, context: Context, asides: readonly string[]): boolean => {
+  if (!DAY_VALUE.test(date.value) || insidePeriod(date.value, period)) return false;
+  const line = containing(context.lines, date.offset);
+  if (line === undefined) return false;
+  const item = isItem(context.source.slice(line.start, line.end), line, context.headings);
+  if (!item && hasYear(date.value)) return false;
+  return !surroundings(date, line, item, context).some((text) => mentions(text, asides));
+};
+
+export const datesOutsidePeriod = (
+  source: string,
+  dates: readonly DateMention[],
+  headings: readonly HeadingSpan[],
+  sentences: readonly Span[],
+  words: OutsideWords,
+): StructureIssue[] => {
+  const lines = linesOf(source);
+  const context: Context = { source, lines, headings, sentences };
+  return statedPeriods(source, lines, dates, headings, words).flatMap((period) =>
+    dates
+      .filter((date) => date.offset > period.scopeStart && date.offset < period.scopeEnd && outsideOne(date, period, context, words.asides))
+      .map((date) => ({ offset: date.offset, values: { date: source.slice(date.offset, date.end), period: period.written } })),
+  );
+};

package/src/structure/definition-use.ts

@@ -135,6 +135,19 @@ const LABEL_SLACK = 3;
 const isLabel = (body: BodyText | undefined, term: string): boolean =>
   body !== undefined && (body.text.replaceAll(term, "").match(LETTER) ?? []).length <= LABEL_SLACK;
 
+/** 文書の位置が、題・見出し・条の見出しの行にあるか。見出しは節の中身に名前を付けるだけで、語を使った所ではない。 */
+export type IsTitle = (offset: number) => boolean;
+
+const NEVER_TITLE: IsTitle = () => false;
+
+const HAN = /\p{Script=Han}/u;
+
+/** 漢字で終わる語の後ろに漢字が続く現れは、もっと長い語の一部（監査委員会の監査委員、保険金請求権の保険金請求）。 */
+const continuesInHan = (texts: readonly BodyText[], term: string, offset: number): boolean => {
+  const body = sentenceAt(texts, offset);
+  return body !== undefined && HAN.test(term.at(-1) ?? "") && HAN.test(body.text.charAt(offset - body.start + term.length));
+};
+
 const CAPITAL_OR_NON_LATIN = /\p{Lu}|[^\p{Script=Latin}\p{N}\s\p{P}]/u;
 
 /**
@@ -145,18 +158,26 @@ const isDistinctive = (term: string): boolean => CAPITAL_OR_NON_LATIN.test(term)
 
 /**
  * 文の途中で括弧に入れて定義した語（(the "Seller")、以下「甲」という）を、その定義の文より前で使っている所。最初の一つだけ。
- * 定義の文の中の現れ（株式会社GovTech東京（以下「GovTech東京」という。））は、定義する名前そのものなので数えない。札の文も数えない。
+ * 定義の文の中の現れ（株式会社GovTech東京（以下「GovTech東京」という。））は、定義する名前そのものなので数えない。札の文も、
+ * isTitle が言う題・見出しの行も、漢字で終わる語にさらに漢字が続く長い語の一部も数えない。
  * 定義の条（"Seller" means、「甲」とは）は条の並びの頭にも終わりにも置く書き方があるので、前で使っても言わない。
  * 定義の語の無い括弧の引用（("The key point is")）は例の引用と同じ形なので、その語を引用符で挙げただけの現れ
  * （Its sentences open with "The key point is"）は使用ではない。定義の語のある定義（(the "Seller")、以下「買主」という）は、
  * 引用符に入れた現れ（The "Seller" ships）も使用。
  */
-export const usesBeforeDefinition = (terms: readonly DefinedTerm[], texts: readonly BodyText[], mentioned: Mentioned = NEVER_MENTIONED): TermUse[] =>
+export const usesBeforeDefinition = (
+  terms: readonly DefinedTerm[],
+  texts: readonly BodyText[],
+  mentioned: Mentioned = NEVER_MENTIONED,
+  isTitle: IsTitle = NEVER_TITLE,
+): TermUse[] =>
   groupsOf(terms)
     .filter((group) => group.first.inline && isDistinctive(group.first.term))
     .flatMap(({ first: defined, spans }) => {
       const defining = sentenceAt(texts, defined.span.start)?.start ?? defined.span.start;
       const uses = usesOf(defined.term, texts, spans, "exact", defined.bare === true ? mentioned : NEVER_MENTIONED);
-      const first = uses.find((offset) => !isLabel(sentenceAt(texts, offset), defined.term));
+      const first = uses.find(
+        (offset) => !isLabel(sentenceAt(texts, offset), defined.term) && !isTitle(offset) && !continuesInHan(texts, defined.term, offset),
+      );
       return first !== undefined && first < defining ? [{ term: defined, offset: first }] : [];
     });

package/src/structure/due-date.ts

@@ -0,0 +1,46 @@
+import type { StructureIssue } from "./issues.ts";
+import { linesOf } from "./lines.ts";
+import { isTotalLabel } from "./total.ts";
+
+/**
+ * A due date before the issue date. A line (or a list item, or a table's first column) starting with an issue-date word
+ * (発行日, Issued) and one starting with a due-date word (お支払期限, Payment due), each with a full date on it: a due date
+ * earlier than the first issue date, and written near it (the header block of an invoice or a quote), is reported. A due
+ * line that says its deadline has passed (期限切れ, overdue) reports on a deadline rather than setting one. Pure.
+ */
+export type DueWords = { readonly issue: readonly string[]; readonly due: readonly string[]; readonly passed: readonly string[] };
+
+/** How many lines from the issue date a due date may be and still be read as the same document's deadline. */
+const MAX_LINE_GAP = 8;
+
+/** A date of the structure tree: where it starts and its value (2026-11-25). */
+export type DatedPoint = { readonly offset: number; readonly value: string };
+
+const FULL_DATE = /^\d{4}-\d{2}-\d{2}$/u;
+
+type Labelled = { readonly kind: "issue" | "due"; readonly date: DatedPoint; readonly line: number };
+
+const kindOf = (text: string, words: DueWords): Labelled["kind"] | undefined => {
+  if (isTotalLabel(text, words.issue)) return "issue";
+  return isTotalLabel(text, words.due) ? "due" : undefined;
+};
+
+const labelledDates = (source: string, dates: readonly DatedPoint[], words: DueWords): Labelled[] =>
+  linesOf(source).flatMap((line) => {
+    const passed = words.passed.some((word) => line.text.toLowerCase().includes(word.toLowerCase()));
+    const kind = passed ? undefined : kindOf(line.text, words);
+    const end = line.start + line.text.length;
+    const onLine = dates.filter((date) => date.offset >= line.start && date.offset <= end && FULL_DATE.test(date.value));
+    const [date] = onLine;
+    return kind === undefined || date === undefined || onLine.length > 1 ? [] : [{ kind, date, line: line.number }];
+  });
+
+export const dueBeforeIssue = (source: string, dates: readonly DatedPoint[], words: DueWords): StructureIssue[] => {
+  if (words.issue.length === 0 || words.due.length === 0) return [];
+  const labelled = labelledDates(source, dates, words);
+  const issued = labelled.find((entry) => entry.kind === "issue");
+  if (issued === undefined) return [];
+  return labelled
+    .filter((entry) => entry.kind === "due" && entry.date.value < issued.date.value && Math.abs(entry.line - issued.line) < MAX_LINE_GAP)
+    .map((entry) => ({ offset: entry.date.offset, values: { due: entry.date.value, issued: issued.date.value } }));
+};

package/src/structure/heading-runs.ts

@@ -0,0 +1,24 @@
+/**
+ * Headings at one depth under one parent heading, as a changelog's version or dated headings stand. A shallower heading
+ * closes the runs deeper than it; a deeper heading (### Added) ends none. A heading pointOf turns down still closes the
+ * deeper runs but joins no run and opens none, so "## Install" between two version headings does not split them.
+ */
+export const siblingHeadingRunsOf = <Heading extends { readonly depth: number }, Point>(
+  headings: readonly Heading[],
+  pointOf: (heading: Heading) => Point | undefined,
+): Point[][] => {
+  const runs: Point[][] = [];
+  const open = new Map<number, Point[]>();
+  headings.forEach((heading) => {
+    [...open.keys()].filter((depth) => depth > heading.depth).forEach((depth) => open.delete(depth));
+    const point = pointOf(heading);
+    if (point === undefined) return;
+    const run = open.get(heading.depth) ?? [];
+    if (!open.has(heading.depth)) {
+      open.set(heading.depth, run);
+      runs.push(run);
+    }
+    run.push(point);
+  });
+  return runs;
+};

package/src/structure/install-pin.ts

@@ -0,0 +1,115 @@
+// An install command that pins the document's own package (npm install wrapkit@3.1.0) to a version other than the one its
+// release list says is current. Pure: reads the source, the releases the document lists, and the install command shapes.
+import { escapeRegExp } from "../orthography.ts";
+
+/** One release the document lists: a version heading with its section, or a list item that starts with a version. */
+export type Release = { readonly version: string; readonly start: number; readonly end: number };
+
+/** A package pinned to one exact version by an install command. */
+export type Pin = { readonly offset: number; readonly name: string; readonly version: string };
+
+/** Where the document names itself: its title, and the paragraph that opens it. */
+export type OwnText = { readonly title: string; readonly opening: string };
+
+export type PinIssue = {
+  readonly offset: number;
+  readonly variant: "newest" | "section";
+  readonly values: { readonly pinned: string; readonly release: string };
+};
+
+const NAME = "(@?[A-Za-z0-9][\\w.\\/-]*)";
+/**
+ * Exactly one version: not a range (^3.0.0, >=3.0.0), not a prerelease or build (3.0.0-beta.1), not a tag (latest). A
+ * sentence's period may follow (install wrapkit@3.1.0.), a fourth part may not (3.1.0.1).
+ */
+const EXACT_VERSION = "(\\d{1,4}\\.\\d{1,4}\\.\\d{1,4})(?![\\w+-]|\\.\\w)";
+/** The rest of a command: on its line, up to a ; && | or a closing backtick. */
+const COMMAND_REST = "[^\\n;&|`]*";
+
+/** A lexicon shape ("npm install {name}@{version}") as the command and the pin it takes. */
+export type InstallShape = { readonly command: RegExp; readonly pin: RegExp };
+
+/** A shape read from the lexicon; undefined when it does not name a command, then both parts in that order. */
+export const installShape = (shape: string): InstallShape | undefined => {
+  const [command = "", rest = ""] = shape.split("{name}");
+  const [separator, tail] = rest.split("{version}");
+  if (command.trim() === "" || separator === undefined || tail === undefined) return undefined;
+  const words = command.trim().split(/\s+/u).map(escapeRegExp).join("[ \\t]+");
+  const pin = escapeRegExp(separator).replaceAll(" ", "[ \\t]+");
+  return {
+    command: new RegExp(`(?<![\\w.-])${words}(?=[ \\t])${COMMAND_REST}`, "gu"),
+    pin: new RegExp(`(?<=[ \\t])${NAME}${pin}${EXACT_VERSION}`, "gu"),
+  };
+};
+
+const pinsAfter = (command: RegExpExecArray, shape: InstallShape): Pin[] =>
+  [...command[0].matchAll(shape.pin)].flatMap((match) => {
+    const [whole, name, version] = match;
+    if (name === undefined || version === undefined) return [];
+    return [{ offset: command.index + match.index + whole.length - version.length, name, version }];
+  });
+
+/** Each pin an install command makes, read with the lexicon's command shapes. Flags and other packages may come first. */
+export const pinsIn = (source: string, shapes: readonly string[]): Pin[] =>
+  shapes
+    .flatMap((text) => {
+      const shape = installShape(text);
+      return shape === undefined ? [] : [...source.matchAll(shape.command)].flatMap((command) => pinsAfter(command, shape));
+    })
+    .filter((pin, index, pins) => pins.findIndex((other) => other.offset === pin.offset) === index);
+
+/** The whole name, scope included: a page about react does not own @types/react. */
+const names = (text: string, name: string): boolean => new RegExp(`(?<![\\w@/.-])${escapeRegExp(name)}(?![\\w/-])`, "iu").test(text);
+
+/**
+ * The pins of the document's own package: those its title names, or, when the title names none (a changelog titled
+ * "Changelog"), those its opening paragraph names. Another package pinned in the same document is a dependency.
+ */
+const ownPins = (pins: readonly Pin[], own: OwnText): Pin[] => {
+  const titled = pins.filter((pin) => names(own.title, pin.name));
+  return titled.length > 0 ? titled : pins.filter((pin) => names(own.opening, pin.name));
+};
+
+const PARAGRAPH_BREAK = /\n[ \t]*\n/u;
+
+/** The document's title, its first top-level heading, and the paragraph that opens the text after it. */
+export const ownTextOf = (source: string, headings: readonly { readonly depth: number; readonly text: string; readonly end: number }[]): OwnText => {
+  const title = headings.find((heading) => heading.depth === 1);
+  const rest = source.slice(title?.end ?? 0).trimStart();
+  const opening = rest.startsWith("#") ? "" : (rest.split(PARAGRAPH_BREAK)[0] ?? "");
+  return { title: title?.text ?? "", opening };
+};
+
+const partsOf = (version: string): number[] => version.split(".").map(Number);
+
+const isNewer = (left: string, right: string): boolean => {
+  const [a, b] = [partsOf(left), partsOf(right)];
+  const differing = a.findIndex((part, index) => part !== b[index]);
+  return differing !== -1 && (a[differing] ?? 0) > (b[differing] ?? 0);
+};
+
+/** The newest release by version order; a prerelease (4.0.0-beta.1) is not the one a reader is told to install. */
+const newestOf = (releases: readonly Release[]): string | undefined =>
+  releases
+    .map((release) => release.version)
+    .filter((version) => !version.includes("-"))
+    .reduce<string | undefined>((newest, version) => (newest === undefined || isNewer(version, newest) ? version : newest), undefined);
+
+/** The release whose section holds a position, innermost first: a pin under "## 3.2.0" belongs to 3.2.0. */
+const sectionAt = (releases: readonly Release[], offset: number): Release | undefined =>
+  releases.filter((release) => release.start <= offset && offset < release.end).at(-1);
+
+/**
+ * Each pin of the document's own package that differs from its release: the release whose section it is in, or else the
+ * newest the document lists. A document that lists no release says nothing to compare.
+ */
+export const installPinMismatches = (pins: readonly Pin[], releases: readonly Release[], own: OwnText): PinIssue[] => {
+  const newest = newestOf(releases);
+  if (newest === undefined) return [];
+  return ownPins(pins, own).flatMap((pin) => {
+    const section = sectionAt(releases, pin.offset);
+    const release = section?.version ?? newest;
+    if (release === pin.version) return [];
+    return [{ offset: pin.offset, variant: section === undefined ? "newest" : "section", values: { pinned: pin.version, release } }];
+  });
+};