chaffjs 0.23.0 → 0.25.0

package/src/detectors/technical-docs.ts

@@ -4,6 +4,7 @@
 // shell-prompt lexicons.
 import { codeFences, codeSpans, type CodeFence } from "./code-fences.ts";
 import { quoteAt } from "./structure-tree.ts";
+import { escapeRegExp } from "../orthography.ts";
 import type { Detector, Finding, ProseDocument, Span, Token } from "../plugin.ts";
 
 const patternsOf = (doc: ProseDocument, id: string): string[] => (doc.lexicons[id] ?? []).map((entry) => entry.pattern);
@@ -112,10 +113,22 @@ export const commandsIn = (heading: string): string[] => {
 const collapse = (text: string): string => text.replace(/\s+/gu, " ");
 const OPTION_CHAR = /[A-Za-z0-9_-]/u;
 
+/**
+ * A command with arguments whose program the code runs under its package's name: chaff grade as npx chaffjs grade,
+ * python -m venv as python3 -m venv. The arguments must follow as written.
+ */
+const showsUnderPackageName = (text: string, wanted: string): boolean => {
+  const [program = "", ...rest] = wanted.split(" ");
+  if (rest.length === 0) return false;
+  const pattern = `(?<![A-Za-z0-9_.-])${escapeRegExp(program)}[A-Za-z0-9_.-]* ${rest.map(escapeRegExp).join(" ")}(?![A-Za-z0-9_-])`;
+  return new RegExp(pattern, "u").test(text);
+};
+
 /** Whether the code holds the command as a whole word: --force is not --force-with-lease, init is not initial. */
 export const showsCommand = (code: string, command: string): boolean => {
   const text = collapse(code);
   const wanted = collapse(command.trim());
+  if (showsUnderPackageName(text, wanted)) return true;
   const state = { at: text.indexOf(wanted) };
   while (state.at !== -1) {
     const before = text.charAt(state.at - 1);

package/src/detectors/unit-spacing.ts

@@ -0,0 +1,71 @@
+import type { Detector, Finding } from "../plugin.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { formMinority } from "./form-minority.ts";
+import { quoteAround } from "./quote-around.ts";
+
+// One document writing a number and a unit symbol both with a space between them ("5 GB") and without ("5GB"). Neither is
+// called right; per unit, the less common way is reported. The symbols come from each language's lexicon "unit-symbol".
+
+/** A number and its unit as written. form is "spaced" or "touching". */
+export type WrittenQuantity = { readonly offset: number; readonly written: string; readonly unit: string; readonly form: string };
+
+/** The less common way for one unit, with an example of the usual way and how many quantities of that unit there are. */
+export type UnitMinority = { readonly odd: WrittenQuantity; readonly usual: string; readonly count: number; readonly of: number };
+
+// Grouping commas, then at most one decimal point: 1.2.3 is a version, not a number.
+const NUMBER = "[0-9]+(?:,[0-9]{3})*(?:\\.[0-9]+)?";
+// A plain space, a no-break space or a narrow no-break space (the SI brochure's thin space between number and unit).
+const GAP = "[ \\u00A0\\u202F]?";
+
+/**
+ * Numbers followed by a unit symbol, at most one space between. The number must not be part of a word, a version or an
+ * address (v1.2GB, x86, 1.2.3GB), nor follow a hyphen: "10-8 cm" is as often a lost exponent as a range (5–10 GB, with
+ * an en dash, is read). The symbol must not run on into a word, a rate or a file name (5 GBit, 5 GB/s, 5GB.zip).
+ */
+export const quantitiesIn = (text: string, symbols: readonly string[]): WrittenQuantity[] => {
+  if (symbols.length === 0) return [];
+  const units = symbols
+    .toSorted((left, right) => right.length - left.length)
+    .map(escapeRegExp)
+    .join("|");
+  const pattern = new RegExp(`(?<![A-Za-z0-9_.,/:#-])${NUMBER}(?<gap>${GAP})(?<unit>${units})(?![A-Za-z0-9_/]|\\.[A-Za-z0-9_])`, "gu");
+  return [...text.matchAll(pattern)].map((match) => ({
+    offset: match.index,
+    written: match[0],
+    unit: match.groups?.["unit"] ?? "",
+    form: match.groups?.["gap"] === "" ? "touching" : "spaced",
+  }));
+};
+
+const minorityOf = (ofUnit: readonly WrittenQuantity[], limit: number): UnitMinority[] => {
+  const minority = formMinority(ofUnit, limit);
+  if (minority === undefined) return [];
+  return minority.odd.map((quantity) => ({ odd: quantity, usual: minority.usual.written, count: minority.odd.length, of: ofUnit.length }));
+};
+
+/** Per unit, the quantities written the less common way. "5 GB" and "500ms" in one document are two units, each consistent. */
+export const unitMinorities = (quantities: readonly WrittenQuantity[], limit: number): UnitMinority[] =>
+  [...new Set(quantities.map((quantity) => quantity.unit))]
+    .flatMap((unit) =>
+      minorityOf(
+        quantities.filter((quantity) => quantity.unit === unit),
+        limit,
+      ),
+    )
+    .toSorted((left, right) => left.odd.offset - right.odd.offset);
+
+export const unitSpacing: Detector = (doc, options): Finding[] => {
+  const text = doc.prose ?? doc.source;
+  const quantities = quantitiesIn(
+    text,
+    (doc.lexicons["unit-symbol"] ?? []).map((entry) => entry.pattern),
+  );
+  return unitMinorities(quantities, options.limit).map(({ odd, usual, count, of }) => ({
+    rule: "",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: quoteAround(text, odd.offset, odd.offset + odd.written.length),
+    values: { written: odd.written, usual, count, of, offset: odd.offset },
+  }));
+};

package/src/quoted-span.ts

@@ -41,5 +41,30 @@ export const quotedSpans = (text: string, marks: Marks = KAGI_MARKS): Span[] =>
 export const quotedIn = (sentence: Sentence, marks: Marks = KAGI_MARKS): Span[] =>
   quotedSpans(sentence.text, marks).map((span) => ({ start: sentence.span.start + span.start - 1, end: sentence.span.start + span.end + 1 }));
 
+const MARKS = /[\s\p{P}]+/u;
+const LETTERS = /^\p{L}+$/u;
+
+/** 記号と空白のあいだに残る語が、字だけの語で、多くとも allowed 個か。 */
+const holdsAtMost = (text: string, allowed: number): boolean => {
+  const words = text.split(MARKS).filter((word) => word !== "");
+  return words.length <= allowed && words.every((word) => LETTERS.test(word));
+};
+
+/**
+ * span だけを引いた引用符（"delves"、"?utm_source=chatgpt.com"、"October 26, 2026 – October 19, 2026"）の中か。
+ * 引用符が語だけを囲めば、その語は使ったのではなく例として挙げたもの。周りの記号と空白は語の一部に数えない。
+ * wordsBesides は、span のほかに引用符の中にあってよい語の数（日付なら曜日の一語）。
+ * 話した言葉の引用（"We ship on Monday, October 26," she said.）は語のほかの字を持つので当たらない。引用は一行の中だけを見る。
+ */
+export const isQuotedAlone = (text: string, span: Span, wordsBesides = 0): boolean => {
+  const lineStart = text.lastIndexOf("\n", span.start - 1) + 1;
+  const newline = text.indexOf("\n", span.end);
+  const line = text.slice(lineStart, newline === -1 ? text.length : newline);
+  const [start, end] = [span.start - lineStart, span.end - lineStart];
+  return quotedSpans(line, QUOTATION_MARKS).some(
+    (quoted) => quoted.start <= start && end <= quoted.end && holdsAtMost(`${line.slice(quoted.start, start)} ${line.slice(end, quoted.end)}`, wordsBesides),
+  );
+};
+
 /** inner が、spans のどれかにまるごと入っているか。 */
 export const isWithinAny = (spans: readonly Span[], inner: Span): boolean => spans.some((span) => inner.start >= span.start && inner.end <= span.end);

package/src/structure/definition-use.ts

@@ -4,7 +4,13 @@ import { inDocumentOrder } from "./issues.ts";
 
 // 定義した語が本文で使われているか、定義より前に使われていないか。どちらも木の定義と、本文の文の字面だけで決まる。
 
-export type DefinedTerm = { readonly term: string; readonly span: Span; readonly line: number; readonly inline: boolean };
+/** bare は、定義の語（means・以下…という・the）の無い括弧の引用（("Seller")）。例を引く括弧と同じ形。 */
+export type DefinedTerm = { readonly term: string; readonly span: Span; readonly line: number; readonly inline: boolean; readonly bare?: boolean };
+
+/** 文書の位置 [start, end) の語が、使ったのではなく引用符で例として挙げただけか。 */
+export type Mentioned = (start: number, end: number) => boolean;
+
+const NEVER_MENTIONED: Mentioned = () => false;
 
 /** 本文の一続き（文）。start は文書の中の位置。 */
 export type BodyText = { readonly start: number; readonly text: string };
@@ -30,7 +36,8 @@ export const definedTerms = (tree: StructureNode): DefinedTerm[] =>
             .replaceAll(EMPHASIS_MARKS, "")
             .trim()
         : "";
-    return isTerm(term) ? [{ term, span: node.span, line: node.line, inline: node.attrs["placement"] === "inline" }] : [];
+    const bare = node.attrs["form"] === "bare" ? { bare: true } : {};
+    return isTerm(term) ? [{ term, span: node.span, line: node.line, inline: node.attrs["placement"] === "inline", ...bare }] : [];
   });
 
 const LATIN_EDGE = /^[\p{Script=Latin}\p{N}]|[\p{Script=Latin}\p{N}]$/u;
@@ -56,11 +63,23 @@ const termPattern = (term: string, caseMatch: CaseMatch): RegExp => {
 
 const inside = (offset: number, spans: readonly Span[]): boolean => spans.some((span) => span.start <= offset && offset < span.end);
 
-/** 語の現れ（文書の中の位置）を順に。定義そのもの（"Seller" means、(the "Seller")）の中の現れは使用に数えない。 */
-export const usesOf = (term: string, texts: readonly BodyText[], definitionSpans: readonly Span[], caseMatch: CaseMatch = "loose"): number[] => {
+/**
+ * 語の現れ（文書の中の位置）を順に。定義そのもの（"Seller" means、(the "Seller")）の中の現れは使用に数えない。
+ * mentioned が言う現れ（引用符で例として挙げただけ）も数えない。
+ */
+export const usesOf = (
+  term: string,
+  texts: readonly BodyText[],
+  definitionSpans: readonly Span[],
+  caseMatch: CaseMatch = "loose",
+  mentioned: Mentioned = NEVER_MENTIONED,
+): number[] => {
   const pattern = termPattern(term, caseMatch);
   return texts.flatMap((body) =>
-    [...body.text.matchAll(pattern)].map((match) => body.start + match.index).filter((offset) => !inside(offset, definitionSpans)),
+    [...body.text.matchAll(pattern)]
+      .filter((match) => !mentioned(body.start + match.index, body.start + match.index + match[0].length))
+      .map((match) => body.start + match.index)
+      .filter((offset) => !inside(offset, definitionSpans)),
   );
 };
 
@@ -78,10 +97,20 @@ const groupsOf = (terms: readonly DefinedTerm[]): TermGroup[] => {
 };
 
 /** 定義したのに、定義の外で一度も使っていない語。同じ語の定義が二つあれば、最初の一つだけを言う（二つ目は duplicate-definition）。 */
-export const unusedDefinitions = (terms: readonly DefinedTerm[], texts: readonly BodyText[]): DefinedTerm[] =>
-  groupsOf(terms)
-    .filter((group) => usesOf(group.first.term, texts, group.spans).length === 0)
+export const unusedDefinitions = (terms: readonly DefinedTerm[], texts: readonly BodyText[], mentioned: Mentioned = NEVER_MENTIONED): DefinedTerm[] => {
+  const groups = groupsOf(terms);
+  const examples = quotesExamples(groups, texts, mentioned);
+  return groups
+    .filter((group) => !(examples && group.first.bare === true) && usesOf(group.first.term, texts, group.spans).length === 0)
     .map((group) => group.first);
+};
+
+/**
+ * 定義の語の無い括弧の引用（("Seller")）を、文書が一つも本文で使っていなければ、それは定義ではなく例の引用
+ * （Plain verbs, not metaphors ("silently fails")）。引用符で挙げただけの現れは使用に数えない。
+ */
+const quotesExamples = (groups: readonly TermGroup[], texts: readonly BodyText[], mentioned: Mentioned): boolean =>
+  !groups.some((group) => group.first.bare === true && usesOf(group.first.term, texts, group.spans, "loose", mentioned).length > 0);
 
 /** offset を含む文。texts は start の昇順で、二分探索で引く。 */
 const sentenceAt = (texts: readonly BodyText[], offset: number): BodyText | undefined => {
@@ -118,13 +147,16 @@ const isDistinctive = (term: string): boolean => CAPITAL_OR_NON_LATIN.test(term)
  * 文の途中で括弧に入れて定義した語（(the "Seller")、以下「甲」という）を、その定義の文より前で使っている所。最初の一つだけ。
  * 定義の文の中の現れ（株式会社GovTech東京（以下「GovTech東京」という。））は、定義する名前そのものなので数えない。札の文も数えない。
  * 定義の条（"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[]): TermUse[] =>
+export const usesBeforeDefinition = (terms: readonly DefinedTerm[], texts: readonly BodyText[], mentioned: Mentioned = NEVER_MENTIONED): 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");
+      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));
       return first !== undefined && first < defining ? [{ term: defined, offset: first }] : [];
     });