chaffjs 0.22.0 → 0.24.0

package/src/render/rules-json.ts

@@ -14,6 +14,7 @@ import { loadStyles } from "../style-load.ts";
 import type { OptionLayer } from "../rule-options.ts";
 import { CUSTOM_TYPES } from "../custom/parse.ts";
 import { DEFAULT_DEPTH, REWRITE_DEPTHS, depthMeaning } from "../rewrite-depth.ts";
+import type { ReportedGuide } from "../genre-guide/report.ts";
 
 const TEXT: Texts<{
   readonly offBySetting: string;
@@ -185,6 +186,7 @@ export const rulesJson = (
   language: string,
   genre: string,
   optionLayers: readonly OptionLayer[] = [],
+  guide?: ReportedGuide,
 ): string => {
   const text = TEXT[uiLanguageOf(language)];
   const preset = presetLevels(genre);
@@ -196,6 +198,8 @@ export const rulesJson = (
       schema_version: 2,
       config_file: "chaff.yaml",
       detected: { genre, language },
+      // What a good document of the genre does: null unless the genre was set (--genre, chaff.yaml) and its guide is on.
+      guide: guide ?? null,
       ...(config.applied === undefined ? {} : { style: styleOf(config) }),
       values_you_can_use: ["strict", "normal", "relaxed", "off"],
       values_note: text.valuesNote,

package/src/render/sarif.ts

@@ -1,5 +1,6 @@
 import { messageOf, readableText } from "./text.ts";
 import type { Finding, RuleDefinition, Severity } from "../plugin.ts";
+import type { RunGuide } from "../genre-guide/report.ts";
 
 /**
  * 指摘を SARIF 2.1.0 で出す。GitHub の code scanning に上げるため。
@@ -114,7 +115,8 @@ const notRunNotifications = (notRun: readonly NotRunOnFile[]): SarifNotification
   }));
 };
 
-export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = []): string => {
+/** guides: the guides of the genres this run set, each with its language; none adds no run properties. */
+export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = [], guides: readonly RunGuide[] = []): string => {
   return `${JSON.stringify(
     {
       $schema: SCHEMA,
@@ -124,6 +126,7 @@ export const renderSarif = (located: readonly Located[], version: string, notRun
           tool: { driver: { name: "chaff", version, informationUri: INFORMATION_URI, rules: usedRules(located) } },
           invocations: [{ executionSuccessful: true, toolConfigurationNotifications: notRunNotifications(notRun) }],
           results: located.map(resultOf),
+          ...(guides.length === 0 ? {} : { properties: { guides: guides.map((entry) => ({ ...entry.guide, language: entry.language })) } }),
         },
       ],
     },

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

package/src/style-parse.ts

@@ -1,5 +1,8 @@
 import { isLevel } from "./levels.ts";
 import type { Level, Localized } from "./plugin.ts";
+import { guideLayerOf, type GuideLayer } from "./genre-guide/layer.ts";
+import { guideProblemText } from "./genre-guide/problem-text.ts";
+import { knownGenres } from "./known-genres.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.
@@ -21,6 +24,8 @@ export type StyleDefinition = {
   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;
+  /** Its changes to the genre guides (genre-guide/layer.ts), between a rule pack's and chaff.yaml's. */
+  readonly guide?: GuideLayer | undefined;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -85,6 +90,15 @@ const limitsOf = (value: unknown, rules: Readonly<Record<string, Level>>, where:
   );
 };
 
+/** The style's guide: as a layer named after the style. undefined when it writes none. */
+const guideOf = (value: unknown, id: string, where: string): GuideLayer | undefined => {
+  if (value === undefined) return undefined;
+  const read = guideLayerOf(value, `style: ${id}`, knownGenres());
+  const [problem] = read.problems;
+  if (problem !== undefined) throw new Error(`${where}: ${guideProblemText(problem, "en")}`);
+  return read.layer;
+};
+
 /** 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;
@@ -99,7 +113,10 @@ export const styleOf = (raw: unknown, where: string): StyleDefinition => {
   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`);
+  const guide = guideOf(raw["guide"], id, where);
+  if (Object.keys(rules).length === 0 && Object.keys(options).length === 0 && guide === undefined) {
+    throw new Error(`${where}: a style must set rules, options or guide`);
+  }
   return {
     id,
     name: localizedOf(raw["name"], "name", where),
@@ -108,5 +125,6 @@ export const styleOf = (raw: unknown, where: string): StyleDefinition => {
     rules,
     options,
     limits: limitsOf(raw["limits"], rules, where),
+    ...(guide === undefined ? {} : { guide }),
   };
 };