chaffjs 0.28.0 → 0.30.0

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

@@ -0,0 +1,192 @@
+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日）は年をまたいで読む。
+ * 文書の仕事の期間（開講期間：…）を文書の頭か概要の節で書いたものは文書全体の期間で、後ろのどの節でも、締め切りの語（period-deadline）のある項目や文の、
+ * 期間の終わりより後の年のある日付を指す（課題の提出が学期の後）。期間の前の締め切り（申込締切）と、旅行期間のように後に締め切りが来てよい期間は比べない。
+ */
+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[];
+  /** 文書の仕事がその中で済む期間の語（開講期間、Term）。この期間は締め切りとだけ比べる。 */
+  readonly terms: readonly string[];
+  readonly deadlines: readonly string[];
+  readonly overviews: 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 line: Span; readonly scopeStart: number; readonly scopeEnd: number; readonly nextPeriod: 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,
+    line,
+    nextPeriod: found[index + 1]?.line.start ?? source.length,
+    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));
+};
+
+const boundaryPattern = (word: string): RegExp => {
+  const target = escapeRegExp(word.toLowerCase());
+  return /[a-z]/u.test(word.toLowerCase()) ? new RegExp(`(?<![a-z])${target}(?![a-z])`, "gu") : new RegExp(target, "gu");
+};
+
+/** 締め切りの語を除いた文。「提出期限」の「期限」、「submit by」の「submit」は、期間の外に置く語として読まない。 */
+const withoutWords = (text: string, words: readonly string[]): string =>
+  words.toSorted((left, right) => right.length - left.length).reduce((rest, word) => rest.replace(boundaryPattern(word), " "), text.toLowerCase());
+
+/** 節の見出しの並び（その行の見出しと、それを囲む浅い見出し）。 */
+const enclosingHeadings = (offset: number, headings: readonly HeadingSpan[]): HeadingSpan[] =>
+  headings
+    .filter((heading) => heading.start < offset)
+    .toReversed()
+    .reduce<HeadingSpan[]>((chain, heading) => (heading.depth < (chain.at(-1)?.depth ?? Infinity) ? [...chain, heading] : chain), []);
+
+/** 文書の仕事の期間か: 表題（文書の頭の # の見出し）のほかの見出しより前か、概要の節（period-overview-heading）の行。 */
+const isDocumentTerm = (period: Stated, context: Context, overviews: readonly string[]): boolean => {
+  const sections = context.headings.filter((heading, index) => heading.start < period.line.start && !(index === 0 && heading.depth === 1));
+  if (sections.length === 0) return true;
+  return enclosingHeadings(period.line.start, context.headings).some((heading) => mentions(context.source.slice(heading.start, heading.end), overviews));
+};
+
+const afterEnd = (value: string, period: Period): boolean => hasYear(value) && hasYear(period.end) && value > period.end;
+
+const lateDeadline = (date: DateMention, period: Stated, context: Context, words: OutsideWords): boolean => {
+  if (!DAY_VALUE.test(date.value) || !afterEnd(date.value, period)) return false;
+  const line = containing(context.lines, date.offset);
+  if (line === undefined) return false;
+  const texts = surroundings(date, line, isItem(context.source.slice(line.start, line.end), line, context.headings), context);
+  if (!mentions(texts[0] ?? "", words.deadlines)) return false;
+  return !texts.some((text) => mentions(withoutWords(text, words.deadlines), words.asides));
+};
+
+const issueOf = (source: string, date: DateMention, period: Stated): StructureIssue => ({
+  offset: date.offset,
+  values: { date: source.slice(date.offset, date.end), period: period.written },
+});
+
+/** 期間の行の後ろ、同じ節の日程の日付で、期間の外のもの。 */
+const outsideInSection = (dates: readonly DateMention[], context: Context, words: OutsideWords): StructureIssue[] =>
+  statedPeriods(context.source, context.lines, dates, context.headings, words).flatMap((period) =>
+    dates
+      .filter((date) => date.offset > period.scopeStart && date.offset < period.scopeEnd && outsideOne(date, period, context, words.asides))
+      .map((date) => issueOf(context.source, date, period)),
+  );
+
+/** 文書の仕事の期間の行の後ろ、次の仕事の期間の行までの、期間の終わりより後の締め切り。 */
+const lateDeadlines = (dates: readonly DateMention[], context: Context, words: OutsideWords): StructureIssue[] =>
+  statedPeriods(context.source, context.lines, dates, context.headings, { ...words, labels: words.terms })
+    .filter((period) => isDocumentTerm(period, context, words.overviews))
+    .flatMap((period) =>
+      dates
+        .filter((date) => date.offset > period.line.end && date.offset < period.nextPeriod && lateDeadline(date, period, context, words))
+        .map((date) => issueOf(context.source, date, period)),
+    );
+
+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 };
+  const inSection = outsideInSection(dates, context, words);
+  const reported = new Set(inSection.map((issue) => issue.offset));
+  return [...inSection, ...lateDeadlines(dates, context, words).filter((issue) => !reported.has(issue.offset))];
+};

package/src/structure/date-range.ts

@@ -107,20 +107,48 @@ const sentenceAround = (source: string, start: DatedSpan, end: DatedSpan): { rea
   return { text: flat(source.slice(paragraphStart + from, end.end + to)), before: flat(head.slice(from)).trimEnd() };
 };
 
-/** 前の語と間の語の組（from … to）。同じ文のどこかに変更の語（moved、postponed）があれば、日付を動かした文で、期間ではない。 */
+/** 同じ文のどこかに変更の語（moved、postponed）があれば、日付を動かした文で、期間ではない。 */
+const isChange = (source: string, start: DatedSpan, end: DatedSpan, words: RangeWords): boolean => {
+  const sentence = sentenceAround(source, start, end).text;
+  return words.changes.some((change) => hasWord(sentence, change.toLowerCase()));
+};
+
+/** 前の語と間の語の組（from … to）。 */
 const framed = (source: string, start: DatedSpan, end: DatedSpan, joint: string, words: RangeWords): boolean => {
-  const sentence = sentenceAround(source, start, end);
-  const before = withoutTrailingWeekday(sentence.before, words.weekdays ?? []);
+  const before = withoutTrailingWeekday(sentenceAround(source, start, end).before, words.weekdays ?? []);
   const frame = words.frames.find((candidate) => candidate.joint === joint && endsWithWord(before, candidate.lead));
-  return frame !== undefined && !words.changes.some((change) => hasWord(sentence.text, change.toLowerCase()));
+  return frame !== undefined && !isChange(source, start, end, words);
+};
+
+const FULL_DATE = /^\d{4}-\d{2}-\d{2}$/u;
+
+/** 日付の前に曜日の名を添えた（Monday, October 5, 2026）。同じ行の、日付の直前だけを見る。 */
+const weekdayBefore = (source: string, date: DatedSpan, weekdays: readonly string[]): boolean => {
+  const before = source.slice(source.lastIndexOf("\n", date.offset - 1) + 1, date.offset).trimEnd();
+  return before !== "" && withoutTrailingWeekday(before, weekdays) !== before;
 };
 
-const isRange = (source: string, start: DatedSpan, end: DatedSpan, words: RangeWords): boolean => {
+/**
+ * 前の語の無い組の間の語だけ（October 5, 2026 to October 30, 2026）。「to」は日付を動かす文にも出るので、
+ * 期間の語で始まる行（Dates: …）か、両方が曜日を添えた年月日のときだけ期間と読む。変更の語のある文は読まない。
+ */
+const bareFramed = (source: string, start: DatedSpan, end: DatedSpan, written: string, words: RangeWords, isLabelled: (offset: number) => boolean): boolean => {
+  const weekdays = words.weekdays ?? [];
+  const joint = withoutTrailingWeekday(written, weekdays);
+  if (!words.frames.some((frame) => frame.joint === joint)) return false;
+  const withWeekdays = FULL_DATE.test(start.value) && FULL_DATE.test(end.value) && joint !== written && weekdayBefore(source, start, weekdays);
+  return (isLabelled(start.offset) || withWeekdays) && !isChange(source, start, end, words);
+};
+
+const isRange = (source: string, start: DatedSpan, end: DatedSpan, words: RangeWords, isLabelled: (offset: number) => boolean): boolean => {
   const written = jointOf(source, start, end);
   if (written === undefined) return false;
   const joint = withoutTrailingWeekday(written, words.weekdays ?? []);
   return (
-    isOneOf(joint, words.connectors) || (isOneOf(joint, words.openers) && closedAfter(source, end, words.closers)) || framed(source, start, end, joint, words)
+    isOneOf(joint, words.connectors) ||
+    (isOneOf(joint, words.openers) && closedAfter(source, end, words.closers)) ||
+    framed(source, start, end, joint, words) ||
+    bareFramed(source, start, end, written, words, isLabelled)
   );
 };
 
@@ -132,11 +160,19 @@ const writtenPeriod = (source: string, start: DatedSpan, end: DatedSpan): string
     .map((part) => part.trim())
     .join(" ");
 
-/** 隣り合う二つの日付のうち、期間をなし、終わりが始まりより前のもの。期間の書き出しを指し、書いたままの期間を見せる。 */
-export const reversedRanges = (source: string, dates: readonly DatedSpan[], words: RangeWords): StructureIssue[] =>
+/**
+ * 隣り合う二つの日付のうち、期間をなし、終わりが始まりより前のもの。期間の書き出しを指し、書いたままの期間を見せる。
+ * isLabelled は、その位置の日付が期間の語で始まる行（Dates: …）の、語より後ろにあるか。
+ */
+export const reversedRanges = (
+  source: string,
+  dates: readonly DatedSpan[],
+  words: RangeWords,
+  isLabelled: (offset: number) => boolean = () => false,
+): StructureIssue[] =>
   dates.slice(1).flatMap((end, index) => {
     const start = dates[index];
     if (start === undefined || !comparable(start.value, end.value) || end.value >= start.value) return [];
-    if (!isRange(source, start, end, words)) return [];
+    if (!isRange(source, start, end, words, isLabelled)) return [];
     return [{ offset: start.offset, values: { start: start.value, end: end.value, period: writtenPeriod(source, start, end) } }];
   });

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 } }];
+  });
+};