chaffjs 0.17.0 → 0.19.0

package/src/structure/wrapped-tail.ts

@@ -1,22 +1,47 @@
 import type { Mention } from "../plugin.ts";
 
 /**
- * 参照を読む行と、その後ろにつないだ次の行。
+ * 参照を読む行と、その前後につないだ行。
  *
- * 72 桁で折り返す RFC は「Section 16.3.2\n   of [HTTP]」のように、参照と「どの文書の」を別の行に書く。行だけを読むと
- * 自分の文書の 16.3.2 に見える。改行と字下げは読み手には空白一つなので、そうつないだ文字列を言語の読み手に渡す。
- * 拾った参照は行の中にあるものだけを残す。次の行の参照は、次の行を読むときに拾う。位置は行の上のまま。
+ * 72 桁で折り返す RFC は「Section 16.3.2\n   of [HTTP]」「RFC 7657\n   (Sections 5.1 …)」のように、参照と「どの文書の」を別の行に書く。
+ * 行だけを読むと自分の文書の 16.3.2 に見える。改行と字下げは読み手には空白一つなので、そうつないだ文字列を言語の読み手に渡す。
+ * 拾った参照は行の中にあるものだけを残す。前後の行の参照は、その行を読むときに拾う。位置は行の上のまま。
+ * leadLength は text の先頭につないだ前の行の長さ（つなぎの空白を含む）。前の行をつながなければ無い。
  */
-export type WrappedLine = { readonly line: string; readonly text: string; readonly lineLength: number };
+export type WrappedLine = { readonly line: string; readonly text: string; readonly lineLength: number; readonly leadLength?: number };
 
-/** 見出しは次の行へ続かない。見出しの行か、次の行が無い・空なら、行だけ。 */
-export const wrappedLine = (text: string, onHeading: boolean, next: string | undefined): WrappedLine => {
+/**
+ * 前の行は末尾のこれだけを読む。文書の名前（「35 CFR」「RFC 7657」）は数語なので足りる。長く読むと前の行の参照
+ * （「Article 58 of the UK GDPR (powers),」）まで入り、その文書が次の行の括弧の中の参照に移る。
+ */
+export const LEAD_REACH = 24;
+
+/** 前の行の末尾。長ければ LEAD_REACH の内側の最初の空白から後ろにして、語の途中から始めない。空白が無ければ読まない。 */
+const leadOf = (previous: string | undefined): string => {
+  const trimmed = previous?.trim() ?? "";
+  if (trimmed.length <= LEAD_REACH) return trimmed;
+  const end = trimmed.slice(-LEAD_REACH);
+  const space = end.search(/\s/u);
+  return space === -1 ? "" : end.slice(space).trimStart();
+};
+
+/** 見出しは前後の行へ続かない。見出しの行か、前後の行が無い・空なら、その側はつながない。 */
+export const wrappedLine = (text: string, onHeading: boolean, next: string | undefined, previous?: string): WrappedLine => {
   const tail = onHeading ? "" : (next?.trim() ?? "");
-  if (tail === "") return { line: text, text, lineLength: text.length };
-  const kept = text.trimEnd();
-  return { line: text, text: `${kept} ${tail}`, lineLength: kept.length };
+  const lead = onHeading ? "" : leadOf(previous);
+  const kept = tail === "" ? text : text.trimEnd();
+  const joined = tail === "" ? text : `${kept} ${tail}`;
+  if (lead === "") return { line: text, text: joined, lineLength: kept.length };
+  // 全角どうしでも空白でつなぐ。詰めると、前の行の宛名（「…担当課」）が次の行の法令名（「構造改革特別区域法」）に付く。
+  const joint = `${lead} `;
+  return { line: text, text: `${joint}${joined}`, lineLength: kept.length, leadLength: joint.length };
 };
 
-/** 行の中で終わる参照だけ。つないだ次の行に入り込んだもの（「Sections 1,\n 2」の 2）は捨てる。 */
-export const onLine = (mentions: readonly Mention[], wrapped: WrappedLine): readonly Mention[] =>
-  mentions.filter((mention) => mention.end <= wrapped.lineLength);
+/** 行の中で始まり、行の中で終わる参照だけを、行の上の位置で。つないだ前後の行に入り込んだもの（「Sections 1,\n 2」の 2）は捨てる。 */
+export const onLine = (mentions: readonly Mention[], wrapped: WrappedLine): readonly Mention[] => {
+  const lead = wrapped.leadLength ?? 0;
+  if (lead === 0) return mentions.filter((mention) => mention.end <= wrapped.lineLength);
+  return mentions
+    .filter((mention) => mention.start >= lead && mention.end <= lead + wrapped.lineLength)
+    .map((mention) => ({ ...mention, start: mention.start - lead, end: mention.end - lead }));
+};

package/src/style-load.ts

@@ -0,0 +1,28 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+import { parseStyle, type StyleDefinition } from "./style-parse.ts";
+
+const STYLES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "styles");
+
+const loaded: { value: readonly StyleDefinition[] | undefined } = { value: undefined };
+
+const readStyle = (dir: string, file: string): StyleDefinition => {
+  try {
+    return parseStyle(parse(readFileSync(join(dir, file), "utf8")), file);
+  } catch (error) {
+    throw new Error(`cannot read ${join(dir, file)}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+};
+
+/** The bundled house styles (styles/*.yaml), by file name. Read once. */
+export const loadStyles = (dir: string = STYLES_DIR): readonly StyleDefinition[] => {
+  if (dir === STYLES_DIR && loaded.value !== undefined) return loaded.value;
+  const styles = readdirSync(dir)
+    .filter((file) => file.endsWith(".yaml"))
+    .toSorted((left, right) => left.localeCompare(right, "en"))
+    .map((file) => readStyle(dir, file));
+  if (dir === STYLES_DIR) loaded.value = styles;
+  return styles;
+};

package/src/style-parse.ts

@@ -0,0 +1,112 @@
+import { isLevel } from "./levels.ts";
+import type { Level, Localized } from "./plugin.ts";
+
+// A house style (styles/*.yaml): a well-known guideline a team picks with style: in chaff.yaml. It sets rule levels and
+// options, and says where they come from. Pure: the YAML comes in already parsed.
+
+export type StyleSource = { readonly title: Localized; readonly url: string };
+
+/** { rule id: { language: limit } }. A guideline gives a number for one language (60 characters for Japanese) and none for another. */
+export type StyleLimits = Readonly<Record<string, Readonly<Record<string, number>>>>;
+
+export type StyleDefinition = {
+  readonly id: string;
+  readonly name: Localized;
+  /** What the style decides, in one or two plain sentences. */
+  readonly summary: Localized;
+  /** The guideline the style follows, so a reader can check it. */
+  readonly source: StyleSource;
+  readonly rules: Readonly<Record<string, Level>>;
+  /** { rule id: { option: value } }, checked against the rules' declared options by the tests. */
+  readonly options: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  /** The numbers the guideline sets, by language. The rule needs a level under rules too, or the limit decides nothing. */
+  readonly limits: StyleLimits;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isLocalized = (value: unknown): value is Localized =>
+  isRecord(value) && typeof value["ja"] === "string" && typeof value["en"] === "string" && value["ja"] !== "" && value["en"] !== "";
+
+const localizedOf = (value: unknown, field: string, where: string): Localized => {
+  if (!isLocalized(value)) throw new Error(`${where}: ${field} needs a ja and an en text`);
+  return value;
+};
+
+const sourceOf = (value: unknown, where: string): StyleSource => {
+  if (!isRecord(value)) throw new Error(`${where}: source needs a title and a url`);
+  const url = value["url"];
+  if (typeof url !== "string" || !url.startsWith("https://")) throw new Error(`${where}: source.url must be an https:// address`);
+  return { title: localizedOf(value["title"], "source.title", where), url };
+};
+
+const levelsOf = (value: unknown, where: string): Record<string, Level> => {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error(`${where}: rules must be a map of rule ids to levels`);
+  return Object.fromEntries(
+    Object.entries(value).map(([id, level]) => {
+      if (!isLevel(level)) throw new Error(`${where}: ${id} has the level ${String(level)}; use strict, normal, relaxed or off`);
+      return [id, level];
+    }),
+  );
+};
+
+const optionsOf = (value: unknown, where: string): Record<string, Readonly<Record<string, unknown>>> => {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error(`${where}: options must be a map of rule ids`);
+  return Object.fromEntries(
+    Object.entries(value).map(([id, options]) => {
+      if (!isRecord(options)) throw new Error(`${where}: options.${id} must be a map of option names to values`);
+      return [id, options];
+    }),
+  );
+};
+
+const isLimit = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+const languageLimitsOf = (id: string, value: unknown, where: string): Record<string, number> => {
+  if (!isRecord(value) || Object.keys(value).length === 0) throw new Error(`${where}: limits.${id} must be a map of languages to numbers`);
+  return Object.fromEntries(
+    Object.entries(value).map(([language, limit]) => {
+      if (!isLimit(limit)) throw new Error(`${where}: limits.${id}.${language} must be a number above 0`);
+      return [language, limit];
+    }),
+  );
+};
+
+const limitsOf = (value: unknown, rules: Readonly<Record<string, Level>>, where: string): Record<string, Record<string, number>> => {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error(`${where}: limits must be a map of rule ids`);
+  return Object.fromEntries(
+    Object.entries(value).map(([id, byLanguage]) => {
+      if (rules[id] === undefined || rules[id] === "off") throw new Error(`${where}: limits.${id} needs ${id} under rules at a level that runs`);
+      return [id, languageLimitsOf(id, byLanguage, where)];
+    }),
+  );
+};
+
+/** One style file. Throws on anything it cannot read: the file ships with chaff, so a wrong entry is chaff's bug. */
+export const parseStyle = (raw: unknown, file: string): StyleDefinition => {
+  const id = isRecord(raw) ? raw["id"] : undefined;
+  if (isRecord(raw) && (typeof id !== "string" || `${id}.yaml` !== file)) throw new Error(`${file}: id must be the file's name without .yaml`);
+  return styleOf(raw, file);
+};
+
+/** One style, wherever it was written (where names it in what is thrown). Throws on anything it cannot read. */
+export const styleOf = (raw: unknown, where: string): StyleDefinition => {
+  if (!isRecord(raw)) throw new Error(`${where}: a style must be a map`);
+  const id = raw["id"];
+  if (typeof id !== "string" || id === "") throw new Error(`${where}: a style needs an id`);
+  const rules = levelsOf(raw["rules"], where);
+  const options = optionsOf(raw["options"], where);
+  if (Object.keys(rules).length === 0 && Object.keys(options).length === 0) throw new Error(`${where}: a style must set rules or options`);
+  return {
+    id,
+    name: localizedOf(raw["name"], "name", where),
+    summary: localizedOf(raw["summary"], "summary", where),
+    source: sourceOf(raw["source"], where),
+    rules,
+    options,
+    limits: limitsOf(raw["limits"], rules, where),
+  };
+};

package/src/subheading-line.ts

@@ -0,0 +1,106 @@
+import type { Span } from "./plugin.ts";
+
+/**
+ * 括弧でくくった短い句だけの行（「（経済再生）」「（目的）」）は、段落の中の小見出し。
+ * 改行だけで次の文へ続けて書かれると、分割器は次の文の頭に読み込み、その文の指摘が小見出しの行に出る。
+ * 小見出しは文を閉じないが、次の文へは続かないので、その行の後ろで段落を切って別々に分割する。
+ *
+ * かぎ括弧（「」『』）は引用で、後ろの文へ続くことがある（「…ますから」\n自分は…）ので含めない。
+ * 前の行が文の途中で終わるなら、括弧の行は文の中の挿入（折り返した文）なので切らない。
+ */
+const PAIRS: ReadonlyMap<string, string> = new Map([
+  ["（", "）"],
+  ["(", ")"],
+  ["【", "】"],
+  ["〔", "〕"],
+  ["［", "］"],
+  ["[", "]"],
+]);
+
+/** 小見出しとして読む括弧の中身の字数の上限。これより長い括弧の行は、括弧でくくった注記。 */
+const MAX_SUBHEADING_CHARS = 40;
+
+/** 中身の文が終わっている。「（ただし、例外を除く。）」は注記の文で、小見出しではない。 */
+const SENTENCE_END_INSIDE = /(?:[。！？!?])|(?:[.．]$)/u;
+/** 行が文で終わっている。句点の後に閉じ括弧・引用符が続いてよい。 */
+const ENDS_SENTENCE = /[。．！？.!?][」』"'”’)）\]］】〕]*$/u;
+
+/** 行が、次の行を導く印（「関連記事：」）で終わっている。その次の行は前の行の続きではない。 */
+const LEADS_IN = /[:：]$/u;
+
+const NEWLINE = /\r?\n/gu;
+
+export type Line = { readonly start: number; readonly end: number; readonly next: number };
+
+const linesOf = (text: string): Line[] => {
+  const breaks = [...text.matchAll(NEWLINE)];
+  const starts = [0, ...breaks.map((match) => match.index + match[0].length)];
+  return starts.map((start, index) => {
+    const found = breaks[index];
+    return { start, end: found?.index ?? text.length, next: found === undefined ? text.length : found.index + found[0].length };
+  });
+};
+
+/** 行が、括弧一組とその中の短い句だけか。 */
+export const isSubheadingLine = (line: string): boolean => {
+  const trimmed = line.trim();
+  const close = PAIRS.get(trimmed[0] ?? "");
+  if (close === undefined || !trimmed.endsWith(close)) return false;
+  const inner = trimmed.slice(1, -1);
+  const chars = [...inner].length;
+  return chars > 0 && chars <= MAX_SUBHEADING_CHARS && !inner.includes(close) && !inner.includes(trimmed[0] ?? "") && !SENTENCE_END_INSIDE.test(inner);
+};
+
+const hasText = (text: string, line: Line | undefined): boolean => line !== undefined && text.slice(line.start, line.end).trim().length > 0;
+
+/** 行の範囲（text の中の位置）。その行だけで一つの項目として立つか。 */
+export type StandsAlone = (start: number, end: number) => boolean;
+
+/**
+ * 一つで立つ行: 小見出しの行か standsAlone が言う行（リンクだけの行など）で、前の行が無いか、文で終わっているか、
+ * 次を導く「：」で終わっているか、それも一つで立つ行。前の行が文の途中で終わるなら、その行は折り返した文の中にある。
+ */
+export const standaloneLines = (text: string, standsAlone: StandsAlone = () => false): Line[] => {
+  const lines = linesOf(text);
+  const alone = (line: Line): boolean => isSubheadingLine(text.slice(line.start, line.end)) || standsAlone(line.start, line.end);
+  const startsFresh = (previous: Line | undefined): boolean => {
+    if (previous === undefined || alone(previous)) return true;
+    const written = text.slice(previous.start, previous.end).trimEnd();
+    return ENDS_SENTENCE.test(written) || LEADS_IN.test(written);
+  };
+  return lines.filter((line, index) => alone(line) && startsFresh(lines[index - 1]));
+};
+
+/**
+ * lines のうち、段落の終わり（end）まで切れ目なく続く後ろの並び。lines は text の順で、行は次の行の頭（next）で隣の行に続く。
+ * 段落の途中の 1 行は本文の文の一つで、終わりまで続く並びだけが本文の後に置いた一覧。
+ */
+export const closingRun = (lines: readonly Line[], end: number): readonly Line[] =>
+  lines.reduceRight<{ readonly run: readonly Line[]; readonly until: number }>(
+    (acc, line) => (line.next === acc.until ? { run: [line, ...acc.run], until: line.start } : acc),
+    { run: [], until: end },
+  ).run;
+
+/** 片の切れ目。前の片は end で終わり、次の片は next から始まる。 */
+type Cut = { readonly end: number; readonly next: number };
+
+/**
+ * 一つで立つ行（lines[index]）の切れ目。後ろに続く行があれば後ろで切る。前の行が「：」で終わる導きなら前でも切る。
+ * 文で終わる前の行は文の分割器が切るので、前では切らない。
+ */
+const cutsAround = (text: string, lines: readonly Line[], index: number): Cut[] => {
+  const [previous, line, following] = [lines[index - 1], lines[index], lines[index + 1]];
+  if (line === undefined) return [];
+  const leadsIn = previous !== undefined && LEADS_IN.test(text.slice(previous.start, previous.end).trimEnd());
+  return [...(leadsIn ? [{ end: previous.end, next: line.start }] : []), ...(hasText(text, following) ? [{ end: line.end, next: line.next }] : [])];
+};
+
+/** 段落 text を、一つで立つ行の後ろ（と、導きの行に続くときは前）で切った片。切る所が無ければ text 全体の 1 片。片は改行を含まない端で終わる。 */
+export const subheadingPieces = (text: string, standsAlone: StandsAlone = () => false): Span[] => {
+  const lines = linesOf(text);
+  const indexOf = new Map(lines.map((line, index) => [line.start, index]));
+  const cuts = standaloneLines(text, standsAlone).flatMap((line) => cutsAround(text, lines, indexOf.get(line.start) ?? 0));
+  const ordered = [...new Map(cuts.map((cut) => [cut.next, cut])).values()].toSorted((left, right) => left.next - right.next);
+  const starts = [0, ...ordered.map((cut) => cut.next)];
+  return starts.map((start, index) => ({ start, end: ordered[index]?.end ?? text.length }));
+};

package/src/tag-coverage.ts

@@ -0,0 +1,13 @@
+import type { Sentence } from "./plugin.ts";
+
+/**
+ * How many of the sentences came back with tokens. A prepared adapter tags every sentence, so "some" means it could not
+ * read part of the document (lang-ja returns no tokens for a paragraph its analyser threw on), and "none" that it tagged nothing.
+ */
+export type TagCoverage = "all" | "some" | "none";
+
+export const tagCoverage = (sentences: readonly Pick<Sentence, "tokens">[]): TagCoverage => {
+  const tagged = sentences.filter((sentence) => sentence.tokens !== undefined).length;
+  if (tagged === sentences.length) return "all";
+  return tagged === 0 ? "none" : "some";
+};

package/src/template-syntax.ts

@@ -0,0 +1,164 @@
+import { spanOf, type MarkdownNode } from "./markdown-node.ts";
+import type { Span } from "./plugin.ts";
+
+/** `closer` finds where each `close` starts. */
+type Delimiters = { readonly open: string; readonly close: string; readonly closer: RegExp };
+
+/**
+ * Template and MDX syntax written into the text: Liquid and Jinja tags (`{% ifversion %}`,
+ * `{% data variables.product.github %}`), outputs (`{{ page.title }}`, which also covers Hugo's shortcodes
+ * `{{< note >}}` and `{{% alert %}}`) and comments (`{# … #}`), and MDX comments (a block comment in braces).
+ */
+const DELIMITERS: readonly Delimiters[] = [
+  { open: "{%", close: "%}", closer: /%\}/gu },
+  { open: "{{", close: "}}", closer: /\}\}/gu },
+  { open: "{#", close: "#}", closer: /#\}/gu },
+  { open: "{/*", close: "*/}", closer: /\*\/\}/gu },
+];
+
+const OPENER = /\{(?=[{%#]|\/\*)/gu;
+
+// A tag never runs past a blank line: an unclosed `{{` is a character in the text, not a tag that swallows the page.
+const BLANK_LINE = /\n[ \t]*\n/gu;
+
+const stretchesOf = (text: string): Span[] => {
+  const breaks = [...text.matchAll(BLANK_LINE)];
+  const starts = [0, ...breaks.map((blank) => blank.index + blank[0].length)];
+  return starts.map((start, index) => ({ start, end: breaks[index]?.index ?? text.length }));
+};
+
+/** The first of the sorted `positions` at or after `from`. */
+const firstAtOrAfter = (positions: readonly number[], from: number, low = 0, high = positions.length): number | undefined => {
+  if (low >= high) return positions[low];
+  const middle = (low + high) >> 1;
+  return (positions[middle] ?? from) >= from ? firstAtOrAfter(positions, from, low, middle) : firstAtOrAfter(positions, from, middle + 1, high);
+};
+
+/**
+ * The tags in one stretch, left to right: each opener closes at the first closer after it, and an opener inside a tag
+ * opens nothing. Each opener looks its closer up instead of scanning for it, so a line of unclosed openers is linear.
+ */
+const tagsIn = (stretch: string): Span[] => {
+  const closers = DELIMITERS.map(({ closer }) => [...stretch.matchAll(closer)].map((match) => match.index));
+  return [...stretch.matchAll(OPENER)].reduce<Span[]>((tags, { index }) => {
+    if (index < (tags.at(-1)?.end ?? 0)) return tags;
+    const kind = DELIMITERS.findIndex(({ open }) => stretch.startsWith(open, index));
+    const delimiters = DELIMITERS[kind];
+    const close = delimiters === undefined ? undefined : firstAtOrAfter(closers[kind] ?? [], index + delimiters.open.length);
+    if (delimiters !== undefined && close !== undefined) tags.push({ start: index, end: close + delimiters.close.length });
+    return tags;
+  }, []);
+};
+
+/** Where the template syntax stands. Read `code` with code already blanked, so a `{{` inside backticks opens nothing. */
+export const templateSpans = (code: string): Span[] =>
+  stretchesOf(code).flatMap((stretch) =>
+    tagsIn(code.slice(stretch.start, stretch.end)).map((tag) => ({ start: stretch.start + tag.start, end: stretch.start + tag.end })),
+  );
+
+/** A line that starts with a JSX element's tag (`<Tabs>`, `</Tabs>`). HTML's tags are lower case and stay HTML. */
+const COMPONENT_START = /^[ \t]*<\/?[A-Z][^\n]*$/gmu;
+
+const QUOTED = /"[^"\n]*"|'[^'\n]*'/gu;
+
+/** Tags and nothing else, once quoted values are emptied and expressions taken out: `<TabItem value= label=>`. */
+const TAGS_ONLY = /^[ \t]*(?:<\/?[A-Za-z][\w.:-]*(?:[ \t][^<>{}]*)?>[ \t]*)+$/u;
+
+/** The line without its brace expressions, however deeply they nest; undefined when its braces do not balance. */
+const withoutExpressions = (line: string): string | undefined => {
+  const kept: string[] = [];
+  const depth = [...line.replace(QUOTED, '""')].reduce((level, char) => {
+    if (level < 0) return level;
+    if (char === "{") return level + 1;
+    if (char === "}") return level - 1;
+    if (level === 0) kept.push(char);
+    return level;
+  }, 0);
+  return depth === 0 ? kept.join("") : undefined;
+};
+
+const isComponentLine = (line: string): boolean => {
+  const bare = withoutExpressions(line);
+  return bare !== undefined && TAGS_ONLY.test(bare);
+};
+
+/**
+ * Lines of nothing but JSX tags. MDX reads such a line as a block of its own, so the text on the next line is a
+ * paragraph; CommonMark reads it as the start of an HTML block that runs to the next blank line and hides that text.
+ */
+export const componentLines = (source: string): Span[] =>
+  [...source.matchAll(COMPONENT_START)]
+    .filter((match) => isComponentLine(match[0]))
+    .map((match) => ({ start: match.index, end: match.index + match[0].length }));
+
+const IMPORT_START = /^import(?:\s|\{)/u;
+// The module's name in quotes ends the statement: "import data from 'CSV' before review." goes on, so it is prose.
+const IMPORT_FROM = /(?:[\s}*]from\s*|^import\s*)["'][^"'\n]*["'];?[ \t]*(?:\n|$)/u;
+
+/** JavaScript's shapes of `export`, read on the first line, so that "export default reports from…" stays a sentence. */
+const EXPORT_SHAPES: readonly RegExp[] = [
+  /^export\s+(?:async\s+)?function\b/u,
+  /^export\s+class\s+[\w$]/u,
+  /^export\s+(?:const|let|var)\s+[\w${[][^=]*=/u,
+  /^export\s+default\s+(?:async\s+)?(?:function|class)\b/u,
+  /^export\s+default\s*[{(["'`<]/u,
+  /^export\s+default\s+[\w$.]+\s*\(/u,
+  /^export\s+default\s+[\w$]+(?:\.[\w$]+)*;?\s*$/u,
+  /^export\s*[{*]/u,
+];
+
+const isExport = (paragraph: string): boolean => {
+  const firstLine = paragraph.split("\n", 1)[0] ?? "";
+  return EXPORT_SHAPES.some((shape) => shape.test(firstLine));
+};
+
+/** A paragraph that is MDX's `import`/`export` block: JavaScript, which MDX runs to the next blank line. */
+const isModuleBlock = (paragraph: string): boolean => (IMPORT_START.test(paragraph) && IMPORT_FROM.test(paragraph)) || isExport(paragraph);
+
+/** MDX's `import`/`export` lines: JavaScript, and only at the top level of the page. */
+export const moduleBlocks = (root: MarkdownNode, source: string): Span[] =>
+  (root.children ?? []).flatMap((node) => {
+    const span = node.type === "paragraph" ? spanOf(node) : undefined;
+    return span !== undefined && isModuleBlock(source.slice(span.start, span.end)) ? [span] : [];
+  });
+
+/** `[!NOTE]` and the like opening a quote: a GitHub alert (Obsidian's callouts write the same). */
+const alertMarkerAt = (source: string, start: number): Span | undefined => {
+  const marker = /\[![A-Za-z]+\][^\n]*/uy;
+  marker.lastIndex = start;
+  return marker.test(source) ? { start, end: marker.lastIndex } : undefined;
+};
+
+const QUOTE_MARK = /^[ \t]*>[ \t]?/gmu;
+
+/** The `>` that opens each line of a quote spanning `quote`: the quote's own mark, not its text. */
+const quoteMarks = (source: string, quote: Span): Span[] =>
+  [...source.slice(quote.start, quote.end).matchAll(QUOTE_MARK)].map((match) => ({
+    start: quote.start + match.index,
+    end: quote.start + match.index + match[0].length,
+  }));
+
+/**
+ * A GitHub alert (`> [!NOTE]`) is the writer's own text set in a box, not a quote: only its marker line and the `>` of
+ * each line are not prose. Undefined when the quote is not an alert.
+ */
+const alertMarks = (quote: MarkdownNode, whole: Span, source: string): Span[] | undefined => {
+  const first = quote.children?.[0];
+  const start = first?.type === "paragraph" ? spanOf(first)?.start : undefined;
+  const marker = start === undefined ? undefined : alertMarkerAt(source, start);
+  return marker === undefined ? undefined : [marker, ...quoteMarks(source, whole)];
+};
+
+/**
+ * Reads the alerts of one walk over the tree in pre-order: the marks of each alert, undefined for any other node. A
+ * quote inside a quote is quoted, even one that opens like an alert; pre-order meets the outer quote first.
+ */
+export const alertReader = (source: string): ((node: MarkdownNode) => Span[] | undefined) => {
+  const outer = { end: -1 };
+  return (node) => {
+    const quote = node.type === "blockquote" ? spanOf(node) : undefined;
+    if (quote === undefined || quote.start < outer.end) return undefined;
+    outer.end = quote.end;
+    return alertMarks(node, quote, source);
+  };
+};

package/src/text-above.ts

@@ -0,0 +1,49 @@
+/**
+ * 箇条書きや表のすぐ上に書いた文の塊。予告の文（以下の3点）や、割合の表の説明（売上の構成比）を読む rule が使う。
+ * 文書の頭まで読み返さないので、箇条書きや表の多い長い文書でも行数に比例する。
+ */
+export type TextBlock = { readonly start: number; readonly text: string };
+
+const BLANK = /^[ \t]*$/u;
+const LIST_MARKER = /^[ \t]*(?:[-*+]|\d{1,3}[.)])[ \t]/u;
+
+export const isBlank = (text: string): boolean => BLANK.test(text);
+
+/** 位置 end の改行で終わる行。 */
+const lineEndingAt = (source: string, end: number): TextBlock => {
+  const start = end === 0 ? 0 : source.lastIndexOf("\n", end - 1) + 1;
+  return { start, text: source.slice(start, end) };
+};
+
+/** start の行の一つ上の行。文書の最初の行なら undefined。 */
+export const lineAbove = (source: string, start: number): TextBlock | undefined => {
+  if (start === 0) return undefined;
+  const end = source.lastIndexOf("\n", start - 1);
+  return end < 0 ? undefined : lineEndingAt(source, end);
+};
+
+/**
+ * start の行より上の塊を、下の行から上へ。passed に当たる行（表の見出しの行など）と空行は、塊に着くまで飛ばす。
+ * 塊は次の空行まで。箇条書きの印で始まる行（親の項目）はそこで止める。下の行から順に返す。
+ */
+export const linesAbove = (source: string, start: number, passed: (text: string) => boolean = () => false): TextBlock[] => {
+  const block: TextBlock[] = [];
+  let line = lineAbove(source, start);
+  while (line !== undefined) {
+    if (isBlank(line.text) || (block.length === 0 && passed(line.text))) {
+      if (block.length > 0) break;
+    } else {
+      block.push(line);
+      if (LIST_MARKER.test(line.text)) break;
+    }
+    line = lineAbove(source, line.start);
+  }
+  return block;
+};
+
+/** 下の行から並べた塊を、一続きの文字列にする。 */
+export const joined = (source: string, lines: readonly TextBlock[]): TextBlock | undefined => {
+  const top = lines.at(-1);
+  const bottom = lines[0];
+  return top === undefined || bottom === undefined ? undefined : { start: top.start, text: source.slice(top.start, bottom.start + bottom.text.length) };
+};