chaffjs 0.8.0 → 0.9.0

package/src/commands/feedback.ts

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Finding, RuleDefinition } from "../plugin.ts";
+import type { Config } from "../config/load.ts";
+import { messageOf } from "../render/text.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+import { excerptsAround } from "../feedback/excerpt.ts";
+import { feedbackDraft, type FeedbackDraft, type FeedbackKind, type ReportedFinding } from "../feedback/draft.ts";
+
+export const FEEDBACK_FILE = ".chaff-feedback.md";
+const NEW_ISSUE = "https://github.com/isamu/lab/issues/new";
+/** GitHub cuts long titles, and a title can carry document text through a rule's message. */
+export const MAX_TITLE_LENGTH = 120;
+
+export type Checked = {
+  readonly findings: readonly Finding[];
+  readonly rules: readonly RuleDefinition[];
+  readonly language: string;
+  readonly genre: string;
+};
+
+export type FeedbackContext = {
+  readonly cwd: string;
+  readonly ui: UiLanguage;
+  readonly version: string;
+  readonly runtime: string;
+  readonly flag: (argv: readonly string[], name: string) => string | undefined;
+  readonly check: (path: string) => Promise<Checked>;
+  /** The reported rules' own settings in chaff.yaml (one line each), or undefined when none are set. */
+  readonly settingsOf: (ruleIds: readonly string[]) => string | undefined;
+};
+
+const TEXT: Texts<{
+  readonly usage: string;
+  readonly notFound: (path: string) => string;
+  readonly badLine: (lines: number) => string;
+  readonly noMatch: (list: string) => string;
+  readonly several: (list: string) => string;
+  readonly none: string;
+  readonly written: (file: string, lines: string) => string;
+  readonly send: string;
+  readonly link: (file: string) => string;
+  readonly neverSent: string;
+}> = {
+  ja: {
+    usage: [
+      "使い方: chaff feedback <file> --rule <rule-id> [--line N] [--with-config]   誤った指摘を報告する",
+      "        chaff feedback <file> --missed --line N [--with-config]           見逃しを報告する",
+    ].join("\n"),
+    notFound: (path) => `${path} がありません。`,
+    badLine: (lines) => `--line には 1〜${String(lines)} の行番号を書いてください。`,
+    noMatch: (list) => `その指摘が見つかりません。この文書の指摘:\n${list}`,
+    several: (list) => `その rule の指摘がいくつもあります。--line で一つ選んでください:\n${list}`,
+    none: "  （指摘はありません）",
+    written: (file, lines) => `報告の下書きを ${file} に書きました。文書から載せたのは ${lines} だけです。送る前に読んで、要らない所は消してください。`,
+    send: "送るには（どちらか）:",
+    link: (file) => `ブラウザで（開いたページに ${file} の中身を貼ります）:`,
+    neverSent: "chaff は何も送っていません。",
+  },
+  en: {
+    usage: [
+      "usage: chaff feedback <file> --rule <rule-id> [--line N] [--with-config]   report a wrong finding",
+      "       chaff feedback <file> --missed --line N [--with-config]           report something chaff missed",
+    ].join("\n"),
+    notFound: (path) => `${path} does not exist.`,
+    badLine: (lines) => `--line must be a line number from 1 to ${String(lines)}.`,
+    noMatch: (list) => `No such finding. The findings in this document:\n${list}`,
+    several: (list) => `That rule has several findings here. Pick one with --line:\n${list}`,
+    none: "  (no findings)",
+    written: (file, lines) =>
+      `Wrote a draft report to ${file}. From the document it includes only ${lines}. Read it before sending, and delete anything you do not want to share.`,
+    send: "To send it (either):",
+    link: (file) => `In a browser (paste the contents of ${file} into the page):`,
+    neverSent: "chaff has not sent anything.",
+  },
+};
+
+const lineList = (lines: readonly number[], ui: UiLanguage): string =>
+  ui === "ja" ? `${lines.join("、")} 行目の前後` : `the lines around ${lines.join(", ")}`;
+
+/** The findings the person picked: by rule, by line, or both. */
+const chosen = (findings: readonly Finding[], rule: string | undefined, line: number | undefined): Finding[] =>
+  findings.filter((finding) => (rule === undefined || finding.rule === rule) && (line === undefined || finding.line === line));
+
+const describe = (findings: readonly Finding[], none: string): string =>
+  findings.length === 0 ? none : findings.map((finding) => `  ${String(finding.line)}  ${finding.rule}`).join("\n");
+
+/** Pure: the reported rules' own lines of chaff.yaml's rules (a numeric limit wins over a level), or undefined when none is set. */
+export const settingsOf = (config: Pick<Config, "rules" | "limits">, ruleIds: readonly string[]): string | undefined => {
+  const lines = [...new Set(ruleIds)].flatMap((id) => {
+    const limit = config.limits[id];
+    const level = config.rules[id];
+    if (limit !== undefined) return [`  ${id}: ${String(limit)}`];
+    return level === undefined ? [] : [`  ${id}: ${level}`];
+  });
+  return lines.length === 0 ? undefined : ["rules:", ...lines].join("\n");
+};
+
+/** Pure: a title on one line, no longer than GitHub shows. */
+export const titleLine = (title: string): string => {
+  const flat = title.replace(/\s+/gu, " ").trim();
+  return flat.length <= MAX_TITLE_LENGTH ? flat : `${flat.slice(0, MAX_TITLE_LENGTH - 1)}…`;
+};
+
+/** Pure: a string a POSIX shell reads literally — single quotes, with any single quote closed, escaped and reopened. */
+export const shellQuoted = (text: string): string => `'${text.replaceAll("'", "'\\''")}'`;
+
+type Request = {
+  readonly path: string;
+  readonly kind: FeedbackKind;
+  readonly rule: string | undefined;
+  readonly line: number | undefined;
+  readonly withConfig: boolean;
+};
+
+/** What the person asked to report. A wrong finding is picked by rule or line; a miss needs the line. */
+const requestOf = (targets: readonly string[], argv: readonly string[], context: FeedbackContext): Request | undefined => {
+  const [path] = targets;
+  const kind: FeedbackKind = argv.includes("--missed") ? "missed" : "false-positive";
+  const rule = context.flag(argv, "--rule");
+  const lineFlag = context.flag(argv, "--line");
+  const line = lineFlag === undefined ? undefined : Number(lineFlag);
+  const lineMissing = kind === "missed" ? line === undefined : rule === undefined && line === undefined;
+  if (path === undefined || targets.length !== 1 || lineMissing || (line !== undefined && !Number.isInteger(line))) return undefined;
+  return { path, kind, rule, line, withConfig: argv.includes("--with-config") };
+};
+
+const reported = (findings: readonly Finding[], checked: Checked): ReportedFinding[] => {
+  const byId = new Map(checked.rules.map((definition) => [definition.id, definition]));
+  return findings.flatMap((finding) => {
+    const definition = byId.get(finding.rule);
+    return definition === undefined ? [] : [{ rule: finding.rule, line: finding.line, message: messageOf(definition, finding, checked.language) }];
+  });
+};
+
+/** The link carries the title only: the body holds document lines, and a URL ends up in history and logs. */
+const sendInstructions = (title: string, lines: readonly number[], ui: UiLanguage): string => {
+  const text = TEXT[ui];
+  return [
+    "",
+    `  ${text.written(FEEDBACK_FILE, lineList([...new Set(lines)], ui))}`,
+    "",
+    `  ${text.send}`,
+    `    gh issue create -R isamu/lab --title ${shellQuoted(title)} --body-file ${FEEDBACK_FILE}`,
+    `  ${text.link(FEEDBACK_FILE)}`,
+    `    ${NEW_ISSUE}?title=${encodeURIComponent(title)}`,
+    "",
+    `  ${text.neverSent}`,
+    "",
+  ].join("\n");
+};
+
+/** Why the request cannot be drafted, or the findings to report. */
+const pick = (request: Request, checked: Checked, lineCount: number, ui: UiLanguage): { readonly error: string } | { readonly findings: Finding[] } => {
+  const text = TEXT[ui];
+  if (request.line !== undefined && (request.line < 1 || request.line > lineCount)) return { error: text.badLine(lineCount) };
+  const picked = chosen(checked.findings, request.rule, request.line);
+  if (request.kind === "missed") return { findings: picked };
+  if (picked.length === 0) return { error: text.noMatch(describe(checked.findings, text.none)) };
+  // One finding per report: a rule picked alone could otherwise pull excerpts from all over the document.
+  if (picked.length > 1) return { error: text.several(describe(picked, text.none)) };
+  return { findings: picked };
+};
+
+/**
+ * `chaff feedback`: an issue draft from a run on the person's own document. It writes a file and prints how to
+ * send it; it never sends anything itself. Only the lines around the reported spot are copied from the document,
+ * and from chaff.yaml only the reported rules' settings unless --with-config is given.
+ */
+export const runFeedback = async (targets: readonly string[], argv: readonly string[], context: FeedbackContext): Promise<number> => {
+  const text = TEXT[context.ui];
+  const request = requestOf(targets, argv, context);
+  if (request === undefined) {
+    console.error(text.usage);
+    return 1;
+  }
+  if (!existsSync(request.path)) {
+    console.error(text.notFound(request.path));
+    return 1;
+  }
+  const source = readFileSync(request.path, "utf8");
+  const checked = await context.check(request.path);
+  const picked = pick(request, checked, source.split("\n").length, context.ui);
+  if ("error" in picked) {
+    console.error(picked.error);
+    return 1;
+  }
+  const findings = reported(picked.findings, checked);
+  const lines = request.kind === "missed" && request.line !== undefined ? [request.line] : findings.map((finding) => finding.line);
+  const configPath = join(context.cwd, "chaff.yaml");
+  const wholeConfig = request.withConfig && existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined;
+  const draft: FeedbackDraft = feedbackDraft(
+    {
+      kind: request.kind,
+      version: context.version,
+      runtime: context.runtime,
+      fileName: basename(request.path),
+      language: checked.language,
+      genre: checked.genre,
+      findings,
+      line: lines[0] ?? 0,
+      excerpts: excerptsAround(source, lines),
+      config: wholeConfig ?? context.settingsOf(findings.map((finding) => finding.rule)),
+    },
+    context.ui,
+  );
+  writeFileSync(join(context.cwd, FEEDBACK_FILE), draft.body, "utf8");
+  console.log(sendInstructions(titleLine(draft.title), lines, context.ui));
+  return 0;
+};

package/src/commands/test.ts

@@ -14,6 +14,7 @@ import { MACHINE_BANNER, renderPlan, renderSemantic } from "../render/semantic.t
 import type { Config } from "../config/load.ts";
 import type { Finding, RuleDefinition } from "../plugin.ts";
 import type { Failure } from "../backends/types.ts";
+import { profileFor } from "../profile/for-file.ts";
 
 export type TestContext = {
   readonly config: Config;
@@ -35,7 +36,7 @@ const judgeAll = async (
       const source = await readFile(path, "utf8");
       const language = applyByPath(config.byPath, config.baseDir, path).language ?? config.language ?? guessLanguage(source).language;
       const adapter = await loadAdapter(language);
-      const doc = buildDocument(path, source, adapter, teamRules(config));
+      const doc = buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language));
       const { genre } = resolveGenre(path, source, config);
       const rules = loadRules(language);
       return { path, outcome: await runSemantic(doc, rules, checks, config.rules, genre, options), rules, language };
@@ -55,7 +56,7 @@ const dryRun = async (
       const source = await readFile(path, "utf8");
       const language = applyByPath(config.byPath, config.baseDir, path).language ?? config.language ?? guessLanguage(source).language;
       const adapter = await loadAdapter(language);
-      const doc = buildDocument(path, source, adapter, teamRules(config));
+      const doc = buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language));
       const { genre } = resolveGenre(path, source, config);
       return { path, jobs: planSemantic(doc, loadRules(language), checks, config.rules, genre), sentences: doc.sentences.length };
     }),

package/src/commands/tree.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { loadAdapter } from "../adapter-load.ts";
 import { applyByPath } from "../config/by-path.ts";
+import { profileFor } from "../profile/for-file.ts";
 import { guessLanguage } from "../detect.ts";
 import { isMarkdownPath } from "../structure/markdown-path.ts";
 import { buildStructure } from "../structure/of.ts";
@@ -79,7 +80,8 @@ export const readTree = async (path: string, argv: readonly string[], context: T
   }
   // 日本語は形態素で数量と日付を読む。解析器が無ければ単位の表で読むので、木は作れる。
   await adapter.prepare?.({ pos: true });
-  return { source, tree: buildStructure({ path, source, language, markdown: isMarkdownPath(path) }, adapter.structure) };
+  const profile = profileFor(context.config, path, source, language);
+  return { source, tree: buildStructure({ path, source, language, markdown: isMarkdownPath(path), profile }, adapter.structure) };
 };
 
 const printTree = async (path: string, argv: readonly string[], context: TreeContext): Promise<boolean> => {

package/src/config/by-path.ts

@@ -1,6 +1,11 @@
 import { relative, sep } from "node:path";
 
-export type PathRule = { readonly files: readonly string[]; readonly genre: string | undefined; readonly language: string | undefined };
+export type PathRule = {
+  readonly files: readonly string[];
+  readonly genre: string | undefined;
+  readonly language: string | undefined;
+  readonly profile?: string | undefined;
+};
 
 /**
  * glob を正規表現にする。使うのは 3 つだけ。
@@ -36,12 +41,15 @@ export const matches = (glob: string, base: string, path: string): boolean => to
  * 後に書いたものが勝つ。上から順に当て、最後に当たったものを使う。
  * 「全体はこう、ここだけは違う」と書けるようにするため。
  */
-export const applyByPath = (rules: readonly PathRule[], base: string, path: string): { genre?: string; language?: string } =>
-  rules.reduce<{ genre?: string; language?: string }>((acc, rule) => {
+type PathSettings = { genre?: string; language?: string; profile?: string };
+
+export const applyByPath = (rules: readonly PathRule[], base: string, path: string): PathSettings =>
+  rules.reduce<PathSettings>((acc, rule) => {
     if (!rule.files.some((glob) => matches(glob, base, path))) return acc;
     return {
       ...acc,
       ...(rule.genre === undefined ? {} : { genre: rule.genre }),
       ...(rule.language === undefined ? {} : { language: rule.language }),
+      ...(rule.profile === undefined ? {} : { profile: rule.profile }),
     };
   }, {});

package/src/config/load.ts

@@ -11,6 +11,8 @@ export const CONFIG_FILE = "chaff.yaml";
 
 export type Config = {
   readonly genre: string | undefined;
+  /** 文書の種類（profiles/*.yaml の id）。none なら内容からも選ばない。 */
+  readonly profile: string | undefined;
   readonly aiBackend: BackendName;
   readonly language: string | undefined;
   readonly rules: Readonly<Record<string, Level>>;
@@ -39,6 +41,7 @@ const DEFAULT_BACKEND: BackendName = "anthropic";
 
 export const EMPTY: Config = {
   genre: undefined,
+  profile: undefined,
   language: undefined,
   rules: {},
   limits: {},
@@ -93,7 +96,7 @@ const toPathRule = (raw: unknown): PathRule | undefined => {
   const files = raw["files"];
   const globs = globsOf(files);
   if (globs.length === 0) return undefined;
-  return { files: globs, genre: str(raw["genre"]), language: str(raw["language"]) };
+  return { files: globs, genre: str(raw["genre"]), language: str(raw["language"]), profile: str(raw["profile"]) };
 };
 
 /** 利用者が書く語の並び。空白だけのものは落とす。 */
@@ -121,6 +124,7 @@ export const loadConfig = (path: string): Config => {
   const backend: BackendName = isBackend(declared) ? declared : DEFAULT_BACKEND;
   return {
     genre: str(raw["genre"]),
+    profile: str(raw["profile"]),
     language: str(raw["language"]),
     rules: rulesOf(raw["rules"]),
     limits: limitsOf(raw["rules"]),

package/src/detectors/char-shape.ts

@@ -1,4 +1,5 @@
-import type { Detector, Finding, Sentence } from "../plugin.ts";
+import type { Detector, DocumentProfile, Finding, Sentence } from "../plugin.ts";
+import { maskAddresses } from "../address-chain.ts";
 import { proseText } from "../measure.ts";
 
 /**
@@ -7,8 +8,8 @@ import { proseText } from "../measure.ts";
  */
 const KANJI_RUN = /[一-鿿]+/gu;
 
-const longestKanji = (sentence: Sentence): string =>
-  [...proseText(sentence).matchAll(KANJI_RUN)].reduce((longest, match) => (match[0].length > longest.length ? match[0] : longest), "");
+const longestKanji = (sentence: Sentence, profile: DocumentProfile | undefined): string =>
+  [...maskAddresses(proseText(sentence), profile).matchAll(KANJI_RUN)].reduce((longest, match) => (match[0].length > longest.length ? match[0] : longest), "");
 
 /**
  * 漢字が続くと、どこで語が切れるのか読み手が探すことになる。
@@ -16,7 +17,7 @@ const longestKanji = (sentence: Sentence): string =>
  */
 export const kanjiRun: Detector = (doc, options): Finding[] =>
   doc.sentences
-    .map((sentence) => ({ sentence, run: longestKanji(sentence) }))
+    .map((sentence) => ({ sentence, run: longestKanji(sentence, doc.profile) }))
     .filter(({ run }) => run.length > options.limit)
     .map(({ sentence, run }) => ({
       rule: "max-kanji-continuous",

package/src/document.ts

@@ -7,7 +7,7 @@ import { atxHeadingText, headingText } from "./heading-text.ts";
 import { maskSpans } from "./mask.ts";
 import { buildTree, NO_OUTLINE, type Outline } from "./structure/build.ts";
 import { isMarkdownPath } from "./structure/markdown-path.ts";
-import type { BulletList, LanguageAdapter, Paragraph, ProseDocument, Section, Sentence, Span, StructureNode } from "./plugin.ts";
+import type { BulletList, LanguageAdapter, Paragraph, ProseDocument, Section, Sentence, Span, StructureNode, DocumentProfile } from "./plugin.ts";
 
 type Place = { readonly offset?: number | undefined };
 type Node = {
@@ -253,7 +253,13 @@ export const teamRules = (config: {
   requiredSections: config.requiredSections,
 });
 
-export const buildDocument = (path: string, source: string, adapter: LanguageAdapter, team: TeamRules = EMPTY_TEAM): ProseDocument => {
+export const buildDocument = (
+  path: string,
+  source: string,
+  adapter: LanguageAdapter,
+  team: TeamRules = EMPTY_TEAM,
+  profile: DocumentProfile | undefined = undefined,
+): ProseDocument => {
   const root = parse(source);
   // 強調の記号は「本文でないもの」だが、太字の数を数えるときの「覆われた場所」ではない。
   // 同じ集合にすると、太字が自分の記号のせいで覆われた場所にあることになり、1 つも数えられなくなる。
@@ -289,9 +295,11 @@ export const buildDocument = (path: string, source: string, adapter: LanguageAda
       tree.value ??=
         patterns === undefined
           ? null
-          : buildTree({ path, source, language: adapter.id, outline: isMarkdownPath(path) ? outlineOf(root, source) : NO_OUTLINE }, patterns);
+          : buildTree({ path, source, language: adapter.id, outline: isMarkdownPath(path) ? outlineOf(root, source) : NO_OUTLINE, profile }, patterns);
       return tree.value ?? undefined;
     },
+    profile,
+    prose,
   };
 };
 

package/src/feedback/draft.ts

@@ -0,0 +1,102 @@
+import type { Texts, UiLanguage } from "../ui.ts";
+import type { Excerpt } from "./excerpt.ts";
+
+export type FeedbackKind = "false-positive" | "missed";
+
+export type ReportedFinding = { readonly rule: string; readonly line: number; readonly message: string };
+
+export type FeedbackInput = {
+  readonly kind: FeedbackKind;
+  readonly version: string;
+  readonly runtime: string;
+  readonly fileName: string;
+  readonly language: string;
+  readonly genre: string;
+  readonly findings: readonly ReportedFinding[];
+  /** The line the person reported: the finding's line, or for a miss the line they named. */
+  readonly line: number;
+  readonly excerpts: readonly Excerpt[];
+  readonly config: string | undefined;
+};
+
+export type FeedbackDraft = { readonly title: string; readonly body: string };
+
+const TEXT: Texts<{
+  readonly titleFalse: (rule: string, message: string) => string;
+  readonly titleMissed: (fileName: string, line: number) => string;
+  readonly what: Readonly<Record<FeedbackKind, string>>;
+  readonly environment: string;
+  readonly findings: string;
+  readonly excerpt: string;
+  readonly config: string;
+  readonly expected: string;
+  readonly expectedHint: Readonly<Record<FeedbackKind, string>>;
+  readonly lines: (from: number, to: number) => string;
+}> = {
+  ja: {
+    titleFalse: (rule, message) => `誤検出: ${rule} — ${message}`,
+    titleMissed: (fileName, line) => `見逃し: ${fileName} の ${String(line)} 行目`,
+    what: { "false-positive": "この指摘は誤りだと思います。", missed: "ここで chaff は何か言うべきだと思います。" },
+    environment: "環境",
+    findings: "指摘",
+    excerpt: "文書の該当箇所（この部分だけを載せています）",
+    config: "chaff.yaml",
+    expected: "期待すること",
+    expectedHint: {
+      "false-positive": "<!-- なぜ誤りか、本来どう読むべきかを書いてください -->",
+      missed: "<!-- 何が問題で、どの rule が言うべきだったかを書いてください -->",
+    },
+    lines: (from, to) => `${String(from)}〜${String(to)} 行目`,
+  },
+  en: {
+    titleFalse: (rule, message) => `False positive: ${rule} — ${message}`,
+    titleMissed: (fileName, line) => `Missed: ${fileName} line ${String(line)}`,
+    what: { "false-positive": "I think this finding is wrong.", missed: "I think chaff should say something here." },
+    environment: "Environment",
+    findings: "Findings",
+    excerpt: "The part of the document (only these lines are included)",
+    config: "chaff.yaml",
+    expected: "What I expected",
+    expectedHint: {
+      "false-positive": "<!-- Why it is wrong, and how the text should be read -->",
+      missed: "<!-- What is wrong in the text, and which rule should have said so -->",
+    },
+    lines: (from, to) => `lines ${String(from)}-${String(to)}`,
+  },
+};
+
+const fence = (content: string, language = ""): string => {
+  const longest = Math.max(2, ...[...content.matchAll(/`+/gu)].map((match) => match[0].length));
+  const ticks = "`".repeat(longest + 1);
+  return [`${ticks}${language}`, content, ticks].join("\n");
+};
+
+/** Pure: the issue title and body for a report. Nothing here reads files or the network. */
+export const feedbackDraft = (input: FeedbackInput, ui: UiLanguage): FeedbackDraft => {
+  const text = TEXT[ui];
+  const first = input.findings[0];
+  const title =
+    input.kind === "false-positive" && first !== undefined ? text.titleFalse(first.rule, first.message) : text.titleMissed(input.fileName, input.line);
+  const body = [
+    text.what[input.kind],
+    "",
+    `## ${text.environment}`,
+    "",
+    `- chaffjs ${input.version}`,
+    `- ${input.runtime}`,
+    `- ${input.fileName} · ${input.language} · ${input.genre}`,
+    ...(input.findings.length === 0
+      ? []
+      : ["", `## ${text.findings}`, "", ...input.findings.map((finding) => `- \`${finding.rule}\` (${String(finding.line)}): ${finding.message}`)]),
+    "",
+    `## ${text.excerpt}`,
+    ...input.excerpts.flatMap((excerpt) => ["", text.lines(excerpt.from, excerpt.to), "", fence(excerpt.lines.join("\n"))]),
+    ...(input.config === undefined ? [] : ["", `## ${text.config}`, "", fence(input.config.trimEnd(), "yaml")]),
+    "",
+    `## ${text.expected}`,
+    "",
+    text.expectedHint[input.kind],
+    "",
+  ].join("\n");
+  return { title, body };
+};

package/src/feedback/excerpt.ts

@@ -0,0 +1,23 @@
+/** Lines around a line of a document, 1-based and inclusive. Only these lines go into a report. */
+export type Excerpt = { readonly from: number; readonly to: number; readonly lines: readonly string[] };
+
+export const EXCERPT_RADIUS = 2;
+
+/** Pure: the excerpts around each line, overlapping ones merged, in document order. Lines outside the document are dropped. */
+export const excerptsAround = (source: string, lines: readonly number[], radius: number = EXCERPT_RADIUS): Excerpt[] => {
+  const all = source.split("\n");
+  const ranges = [...new Set(lines)]
+    .filter((line) => line >= 1 && line <= all.length)
+    .sort((left, right) => left - right)
+    .map((line) => ({ from: Math.max(1, line - radius), to: Math.min(all.length, line + radius) }));
+  const merged = ranges.reduce<{ from: number; to: number }[]>((acc, range) => {
+    const last = acc.at(-1);
+    if (last !== undefined && range.from <= last.to + 1) {
+      last.to = Math.max(last.to, range.to);
+      return acc;
+    }
+    acc.push({ ...range });
+    return acc;
+  }, []);
+  return merged.map(({ from, to }) => ({ from, to, lines: all.slice(from - 1, to) }));
+};

package/src/orthography.ts

@@ -80,8 +80,23 @@ const leftRunBeside = (chars: readonly string[], last: number, japanese: string
   return kind === "letter" && DIGIT.test(runStart(chars, last) ?? "") ? "after-digit" : kind;
 };
 
+/**
+ * 「第3条」「第4条第2項」の数字は番地の書き方で、空けるか詰めるかの好みではない。数えると、条番号の多い文書では
+ * 「2 か所」のような普通の書き方のほうが少数に見えてしまう。「第」のすぐ後ろの数字の並びは、両側とも数えない。
+ */
+const ORDINAL_PREFIX = "第";
+
+const isOrdinalRun = (chars: readonly string[], index: number): boolean => {
+  let first = index;
+  while (first > 0 && /[\d.]/u.test(chars[first - 1] ?? "")) first -= 1;
+  const before = chars[first - 1] === " " ? first - 2 : first - 1;
+  return chars[before] === ORDINAL_PREFIX;
+};
+
 const boundaryAt = (chars: readonly string[], index: number): Omit<Boundary, "offset"> | undefined => {
   const [left, right, after] = [chars[index], chars[index + 1], chars[index + 2]];
+  const numberAfterPrefix = left === ORDINAL_PREFIX && DIGIT.test((right === " " ? after : right) ?? "");
+  if (numberAfterPrefix || (DIGIT.test(left ?? "") && isOrdinalRun(chars, index))) return undefined;
   const touching = latinBeside(left, right, "before-digit") ?? leftRunBeside(chars, index, right);
   if (touching !== undefined) return { kind: touching, spaced: false };
   if (right !== " ") return undefined;

package/src/plugin.ts

@@ -93,6 +93,11 @@ export type NumberedLine = {
   readonly label: string;
   /** 番号に続く見出し。「第3条（支払）」の「支払」。本文しか無ければ空。 */
   readonly heading: string;
+  /**
+   * 番号に付いた語（"section"、"article"）。英米の文書は Section と Article を別のものとして使うので、
+   * 参照の attrs.numbering と比べて、この文書に無い種類の番号への参照（Section で組んだ法令の中の "Article 6"）を見分ける。
+   */
+  readonly numbering?: string | undefined;
   /** 番号の後ろの文字列全部。定義や参照はここから探す。 */
   readonly rest: string;
   /**
@@ -124,6 +129,16 @@ export type StructurePatterns = {
   readonly obligations: (text: string) => readonly Mention[];
   /** 数量。attrs.value に数、attrs.unit に単位。 */
   readonly quantities: (text: string) => readonly Mention[];
+  /**
+   * 「In this section—」のように、この後の定義はいま開いている条の中でだけ通じると宣言する行なら true。
+   * その条の定義に scope: "local" が付く。定義の並びが次の行から始まるので、定義の行だけを見ても分からない。
+   */
+  readonly opensDefinitionScope?: (text: string) => boolean;
+  /**
+   * 範囲が条より広いまとまり（「In this Part—」）なら、そのまとまりの深さ（NumberedLine.depth）。
+   * そのまとまりの中の定義どうしだけを比べる。無ければ、opensDefinitionScope のとおり条の中。
+   */
+  readonly definitionScopeDepth?: (text: string) => number | undefined;
   /** 日付。attrs.value に "2024-04-01"・"2024-04"・"04-01"・"2024" のどれか。無い言語は日付を読まない。 */
   readonly dates?: (text: string) => readonly Mention[];
   /**
@@ -131,6 +146,8 @@ export type StructurePatterns = {
    * 数字と点だけの通し番号は core が言語を問わず読むので、それを数量と見分けられるのは言語パッケージだけ。
    */
   readonly countedAfter?: (number: string, rest: string) => boolean;
+  /** 数の書き方（「二十二」「3」）を数にする。相対の参照の「前二項」「前条第二項」が使う。 */
+  readonly number?: (text: string) => number | undefined;
 };
 
 export type StructureKind = "doc" | "section" | "chapter" | "article" | "item" | "definition" | "reference" | "obligation" | "quantity" | "date";
@@ -150,6 +167,8 @@ export type StructureNode = {
   readonly level?: number;
   /** 範囲をまとめた行の最後の位置（NumberedLine.ordinalTo）。S 式には出さない。 */
   readonly ordinalTo?: number;
+  /** 番号に付いた語（NumberedLine.numbering）。S 式には出さない。 */
+  readonly numbering?: string;
 };
 
 // ───────── 文書モデルと rule ─────────
@@ -175,6 +194,65 @@ export type BulletList = { readonly span: Span; readonly items: readonly number[
  * detector に渡る唯一の入り口。core が I/O を済ませてから呼ぶ。
  * detector は純関数で、fs / network / clock に触れない。spec §6。
  */
+/**
+ * 文書の種類の知識（法令の番地の書き方など）。コードは種類を知らず、profiles/*.yaml に書いたものを読む。
+ * 言語ごとに一つに絞ったもの。正規表現は文字列のまま持ち、使う側が組み立てる。
+ */
+export type DocumentProfile = {
+  readonly id: string;
+  /** 番地の書き方。漢字の連なりにも、数量にも数えない。 */
+  readonly addresses: readonly string[];
+  /** 番地と番地のあいだ、番地の後ろに付く語。 */
+  readonly connectives: readonly string[];
+  /** 番地の並びのすぐ後ろに来てよい文字（正規表現）。無ければどこで終わってもよい。 */
+  readonly addressEnd?: string | undefined;
+  /**
+   * 条の前の行に置く見出しの形（正規表現。最初の括弧の中が見出しの言葉）。法令の「（解雇の予告）」。
+   * すぐ次の行の条が見出しを持たなければ、その条の見出しになる。
+   */
+  readonly caption?: string | undefined;
+  /** 前条・同項のように、書いた場所から番地が決まる参照の読み方。無ければ読まない。 */
+  readonly relative?: RelativeVocabulary | undefined;
+};
+
+/**
+ * 相対の参照の語彙。語の意味（一つ前・一つ後・直前に引いたもの・今いるところ）はコードが知り、どの語がそれに当たるかは種類が決める。
+ * units は単位の語から木の深さ（NumberedLine.depth）への対応。
+ */
+export type RelativeVocabulary = {
+  readonly before: readonly string[];
+  readonly after: readonly string[];
+  readonly same: readonly string[];
+  readonly current: readonly string[];
+  /** 「前各項」の「各」。一つ前だけでなく、前の全部。 */
+  readonly every: readonly string[];
+  /** 「前二項」の「二」のような、いくつ分かの数の書き方（正規表現）。数は言語パッケージの number が読む。 */
+  readonly count: string;
+  readonly units: Readonly<Record<string, number>>;
+  /** 「前条第二項」の「第」。後ろに続く番地の書き出し。 */
+  readonly suffixPrefix: string;
+  /**
+   * 最初のものに番号を振らない深さ（法令の項）。あれば「第二条第一号」は 2.1.1、「第四条第一項」は第四条そのものでもある。
+   */
+  readonly implicitFirst: number | undefined;
+  /** すぐ前に来てはいけない文字（正規表現）。「事前条件」の「前条」を参照にしない。 */
+  readonly notAfter: string | undefined;
+  /**
+   * 読み替え（「『前条』とあるのは『…』」）の括弧。中の前条・同項は読み替える先の文の言葉で、ここからは決められないので読まない。
+   * 閉じの直後に after、開きの直前に before のどれかがあるものだけ。
+   */
+  readonly substitution: { readonly open: string; readonly close: string; readonly after: readonly string[]; readonly before: readonly string[] } | undefined;
+  /** 条を書かずにこの単位で始まる番地（法令の「第一項」「第二号」）は、書いた場所を含むまとまりの中を指す。 */
+  readonly inside: readonly string[];
+  /**
+   * 並びをつなぐもの（正規表現。及び・若しくは・から・、・枝番号の「の二」）。すぐ前の参照とのあいだがこれとつなぎの語（connectives）と
+   * 閉じた括弧だけなら、条を書かない番地はその参照の続き。「第三十三条第七項若しくは第九項」の「第九項」は第三十三条の第九項。
+   */
+  readonly joiners: readonly string[];
+  /** 括弧書き（「（…）」）の開きと閉じ。並びの途中に挟まっても、並びを切らない。 */
+  readonly aside: { readonly open: string; readonly close: string } | undefined;
+};
+
 export type ProseDocument = {
   readonly path: string;
   readonly source: string;
@@ -196,6 +274,10 @@ export type ProseDocument = {
   readonly requiredSections: readonly string[];
   /** 番地の付いた木（§27）。adapter が structure を持たない言語では無い。 */
   readonly structure: StructureNode | undefined;
+  /** 文書の種類（法令など）。選ばれなければ無い。 */
+  readonly profile?: DocumentProfile | undefined;
+  /** 本文でないもの（コード・HTML・強調の印）を同じ長さの空白で覆った source。位置は source と同じ。 */
+  readonly prose?: string | undefined;
 };
 
 export type Severity = "error" | "warning" | "info";