chaffjs 0.19.0 → 0.20.0

package/genres.yaml

@@ -9,7 +9,8 @@
 #            paths (the file's path), then per language an opening (the body's first line, past front matter and
 #            headings) or a line with min_lines (how many lines must have that shape). A wrong suggestion misleads
 #            more than none, so a cue is added only where the corpus shows it does not fire on other kinds.
-# Which genres a rule applies to at all is the rule's use_for; the numbers behind a level are the rule's by_genre.
+# Which genres a rule applies to at all is the rule's use_for (a rule it leaves out is listed under "did not run" the same
+# way); the numbers behind a level are the rule's by_genre.
 
 groups:
   - id: technical
@@ -51,11 +52,33 @@ groups:
       stock-transition: off
       announcing-opener: off
       colon-lead-in: off
+      emoji-heading: off
       bold-label-list: off
+      # A clause, a definition or a claim is a paragraph of one sentence by form.
+      one-sentence-paragraph-run: off
+      ai-structure: off
       # Statutes and opinions write "not inconsistent with" on purpose.
       double-negative: off
+      # Drafting writes "in the event that" and "for the purpose of" on purpose.
+      wordy-phrase: off
+      weasel-word: off
+      sentence-initial-so: off
       # Legal drafting writes 「…を行う」 and "make a payment" as its register; the corpus statutes are full of them.
       nominalization: off
+      # すなわち and that is, open a definition that restates on purpose.
+      paragraph-restatement: off
+      # A statute or contract opens with its first article, and its titles are formal names.
+      no-lead: off
+      title-length: off
+      # Drafting writes a number twice on purpose: thirty (30) days.
+      number-style-consistency: off
+      # An enumeration of conditions mixes 〜こと and 〜とき by what each condition is.
+      list-item-form-mix: off
+      # A paper's citations, figures and abstract: only the academic paper genre turns these on.
+      citation-style-mix: off
+      citation-reference-mismatch: off
+      figure-reference-order: off
+      abstract-length: off
   # A help page repeats its heading in its first line (To upload a file, ...) and states no claims to back up.
   - id: docs
     name: { ja: 説明書, en: Documentation }
@@ -84,7 +107,14 @@ groups:
       stock-transition: off
       announcing-opener: off
       colon-lead-in: off
+      emoji-heading: off
       bold-label-list: off
+      ai-structure: off
+      # A paper's citations, figures and abstract: only the academic paper genre turns these on.
+      citation-style-mix: off
+      citation-reference-mismatch: off
+      figure-reference-order: off
+      abstract-length: off
   # Science writes in the passive, hedges its claims on purpose (may, suggest) and cites numbers as its evidence.
   - id: academic
     name: { ja: 学術, en: Academic }
@@ -106,13 +136,19 @@ groups:
       section-length-uniformity: off
       paragraph-length-variance: off
       stock-transition: off
+      emoji-heading: off
       bold-label-list: off
+      ai-structure: off
       requirement-smell: off
   # Length, rhythm, repetition and register are the author's choices in literature, and dialogue mixes styles.
   # Only what one work can hold itself to runs: consistent spacing and commas, and numbering without gaps.
   - id: literature
     name: { ja: 文学, en: Literature }
     rules:
+      # A character who says "never" and later makes an exception is the story, not a drafting slip.
+      absolute-exception: off
+      # A story's narrator and its characters each say 私 or 僕 in their own voice.
+      person-consistency: off
       max-sentence-length: off
       max-paragraph-length: off
       ngram-repetition: off
@@ -146,6 +182,9 @@ groups:
       double-keigo: off
       no-em-dash: off
       emoji-density: off
+      elapsed-years-mismatch: off
+      fact-conflict: off
+      summary-fact-mismatch: off
       sentence-rhythm: off
       rule-of-three: off
       section-length-uniformity: off
@@ -156,6 +195,7 @@ groups:
       stock-transition: off
       announcing-opener: off
       colon-lead-in: off
+      emoji-heading: off
       bold-label-list: off
       nominalization: off
       dangling-reference: off
@@ -172,7 +212,35 @@ groups:
       double-negative: off
       ra-nuki: off
       spelling-consistency: off
+      orthographic-variant: off
+      translationese-density: off
+      unknown-word: off
+      redundant-expression: off
       requirement-smell: off
+      # Dialogue may misuse an idiom on purpose, to draw the speaker.
+      idiom-misuse: off
+      paragraph-restatement: off
+      # A story or poem chooses its own opening and its own title.
+      no-lead: off
+      title-length: off
+      # A narrator spells out numbers in dialogue and writes figures in a date.
+      number-style-consistency: off
+      list-item-form-mix: off
+      # Dialogue and verse set each line apart.
+      one-sentence-paragraph-run: off
+      # Dialect and old usage ("an hospital") are the work's voice, and dialogue leans on "very".
+      article-sound: off
+      very-adjective: off
+      # A paper's citations, figures and abstract: only the academic paper genre turns these on.
+      citation-style-mix: off
+      citation-reference-mismatch: off
+      figure-reference-order: off
+      abstract-length: off
+      # A narrator and a character speak as they speak: dialect ("would of"), "So," and hearsay are the voice.
+      homophone-slip: off
+      wordy-phrase: off
+      weasel-word: off
+      sentence-initial-so: off
   # A speech opens with greetings and closes with thanks: that is its form, not padding.
   - id: speech
     name: { ja: 話し言葉, en: Speech }
@@ -191,10 +259,30 @@ groups:
       stock-transition: off
       announcing-opener: off
       colon-lead-in: off
+      ai-structure: off
       # A transcript keeps the speaker's words: hedges and ら dropped as spoken.
       double-negative: off
       ra-nuki: off
       requirement-smell: off
+      article-sound: off
+      very-adjective: off
+      homophone-slip: off
+      wordy-phrase: off
+      weasel-word: off
+      sentence-initial-so: off
+      # A speaker says it again so the room hears it: 要するに, in other words.
+      paragraph-restatement: off
+      # An address or a transcript is titled by occasion (第221回国会における…演説) and opens as spoken.
+      no-lead: off
+      title-length: off
+      # Spoken numbers are transcribed as heard.
+      number-style-consistency: off
+      list-item-form-mix: off
+      # A paper's citations, figures and abstract: only the academic paper genre turns these on.
+      citation-style-mix: off
+      citation-reference-mismatch: off
+      figure-reference-order: off
+      abstract-length: off
 
 genres:
   - id: technical/spec
@@ -260,6 +348,8 @@ genres:
     # In the corpus the rule fires on nearly every set of minutes, English and Japanese.
     # A header block of labelled fields (- **日時**：…, - **出席者**：…) is the form of minutes, not a list of captions.
     rules:
+      # Minutes jot points down as they come: a noun, a remark, a decision, side by side.
+      list-item-form-mix: off
       agentless-passive: off
       bold-label-list: off
   - id: legal/contract
@@ -346,6 +436,9 @@ genres:
       paths: ["(^|[/_-])(faqs?|q-?and-?a)([/_.-]|$)"]
       ja: { line: "^(?:#{1,6}\\s*)?(?:[QＱ][0-9０-９]*[.．:：、\\s　]|問[0-9０-９]+[.．:：\\s　])|^#{1,6}\\s*(?:よくある(?:ご)?質問|Ｑ＆Ａ|Q&A)", min_lines: 2 }
       en: { line: "^(?:#{1,6}\\s*)?Q[0-9]*[.:)]\\s|^#{1,6}\\s*(?:FAQs?|Frequently asked questions)\\b", min_lines: 2 }
+    # A question is the heading: its length is the reader's question, not a name to shorten.
+    rules:
+      title-length: off
   - id: docs/glossary
     name: { ja: 用語集, en: Glossary }
     summary:
@@ -375,6 +468,13 @@ genres:
           line: "^(?:#{1,6}\\s*)?(?:\\d+\\.?\\s+)?(?:Abstract|Keywords|Methods?|Methodology|Results|Discussion|Conclusions?|Related [Ww]ork|Bibliography|References)\\s*$",
           min_lines: 4,
         }
+    # A paper is read against its own apparatus: one citation style, citations that match the reference list, figures
+    # numbered in the order they are referred to, and an abstract of a fixed length.
+    rules:
+      citation-style-mix: normal
+      citation-reference-mismatch: normal
+      figure-reference-order: normal
+      abstract-length: normal
   - id: literature/fiction
     name: { ja: 小説, en: Fiction }
     summary:
@@ -431,6 +531,8 @@ genres:
       en: { line: "^(?:Mr|Ms|Mrs|Dr)\\. [A-Z][A-Z-]{2,}(?: of [A-Z][a-z]+)?\\. ", min_lines: 3 }
     # A transcript records what was said: its sentences, repeats and register are the speaker's, not the writer's to fix.
     rules:
+      # Several people speak, each naming themselves their own way.
+      person-consistency: off
       max-sentence-length: off
       max-paragraph-length: off
       ngram-repetition: off

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chaffjs",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Prose validation harness. Finds what is hard to read, and never rewrites it for you.",
   "keywords": [
     "chaff",
@@ -37,6 +37,10 @@
     "./api": {
       "types": "./src/api.ts",
       "import": "./dist/api.js"
+    },
+    "./grade": {
+      "types": "./src/grade-api.ts",
+      "import": "./dist/grade-api.js"
     }
   },
   "files": [
@@ -47,6 +51,7 @@
     "genres.yaml",
     "profiles",
     "reference-headings.yaml",
+    "structure-baseline.yaml",
     "rules",
     "skills",
     "styles",
@@ -61,8 +66,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.125.0",
-    "@chaffjs/lang-en": "0.17.0",
-    "@chaffjs/lang-ja": "0.18.0",
+    "@chaffjs/lang-en": "0.18.0",
+    "@chaffjs/lang-ja": "0.19.0",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-gfm-table": "^2.0.0",

package/rules/absolute-exception.yaml

@@ -0,0 +1,83 @@
+id: absolute-exception
+layer: L3
+status: experimental
+how_to_find: absolute-exception
+word_list: absolute-word
+extra_word_lists: [exception-marker, light-verb]
+requires: [structure, pos]
+severity: warning
+
+name:
+  ja: 言い切った決まりに、別の所で例外がある
+  en: An absolute rule with an exception written elsewhere
+
+why:
+  ja: 「すべての〜は…しなければならない」「一切…してはならない」と例外なしに言い切った決まりに、後の別の条や段落で「ただし…を除く」と例外を書くと、言い切った文だけを読んだ人は例外を知らずに従います。後から足した条や、別の文書から写した例外で起きます。例外を言い切った文と同じ条や段落に書いていれば（ただし書）、それは決まりの一部なので、ここには出ません。二つの文が同じ行為について言っているかは、中身の語の重なりで見ます。
+  en: 'A rule stated without exception ("all staff must", "must never") that a later article or paragraph makes an exception to ("except", "unless") misleads a reader who stops at the rule. It happens when an exception is added later or copied from another document. An exception in the same article or paragraph is the rule''s own proviso and is not reported. Whether two sentences are about the same act is read from the content words they share.'
+
+message:
+  ja: 「{word}」と言い切っていますが、{otherLine} 行目に同じ行為の例外（「{exception}」）があります
+  en: 'This says "{word}", but line {otherLine} makes an exception ("{exception}") for the same act'
+
+how_to_fix:
+  ja: 言い切った文に例外を書き足すか（「次条に定める場合を除き」）、例外のほうを消すかを決めてください。
+  en: Either add the exception to the absolute rule ("except as set out in section 5") or remove the exception.
+
+placeholders:
+  word:
+    ja: すべて
+    en: always
+  exception:
+    ja: ただし
+    en: except
+  otherLine:
+    ja: 〇
+    en: N
+
+levels: { strict: error, normal: warning, relaxed: info }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: structure
+summary:
+  ja: 「すべての〜は…しなければならない」と言い切った決まりに、別の条や段落で「ただし…を除く」と例外を書いた所
+  en: 'A rule stated without exception ("must always") that another article or paragraph makes an exception to ("except")'
+example:
+  ja:
+    before: |
+      ## 第1条（提出）
+
+      社員は、すべての経費の領収書を経理部に提出しなければならない。
+
+      ## 第2条（少額の経費）
+
+      千円未満の経費は、領収書を経理部に提出する対象から除く。
+    after: |
+      ## 第1条（提出）
+
+      社員は、次条に定めるものを除き、すべての経費の領収書を経理部に提出しなければならない。
+
+      ## 第2条（少額の経費）
+
+      千円未満の経費は、領収書を経理部に提出する対象から除く。
+  en:
+    before: |
+      ## 1. Receipts
+
+      Staff must always send the receipt for every expense to the finance team.
+
+      ## 2. Small expenses
+
+      Staff need not send the receipt to the finance team for an expense under ten dollars, except for travel.
+    after: |
+      ## 1. Receipts
+
+      Except as set out in section 2, staff must always send the receipt for every expense to the finance team.
+
+      ## 2. Small expenses
+
+      Staff need not send the receipt to the finance team for an expense under ten dollars, except for travel.
+
+not_flagged:
+  ja: 例外を言い切った文と同じ条や段落に書いた文（ただし書）、言い切った文そのものが例外を持つ文、言い切った文の中身の語を半分以上くり返さない例外は指摘しません。義務の語（しなければならない・してはならない）の無い言い切りと、鉤括弧の中の語も見ません。
+  en: An exception in the same article or paragraph (a proviso), an absolute rule that carries its own exception, and an exception that does not repeat most of the rule's content words are not reported. A statement with no obligation word (must, shall, must not) and words inside quotation marks are not read.

package/rules/abstract-length.yaml

@@ -0,0 +1,130 @@
+id: abstract-length
+layer: L3
+status: experimental
+how_to_find: abstract-length
+severity: info
+
+name:
+  ja: 要旨が長すぎる、または無い
+  en: Abstract too long, or missing
+
+why:
+  ja: 読み手は要旨だけを読んで、本文を読むかを決めます。要旨が長すぎると、その判断に本文と同じだけ時間がかかり、投稿先の字数の上限も超えがちです。節を立てた論文に要旨が無いと、読み手は本文を読み進めないと何の研究かが分かりません。要旨は、「要旨」「抄録」「Abstract」の見出しの下の文、それだけを書いた行の次の段落、または段落の頭の「要旨：」「【要旨】」の後ろの文です。和文の論文の英文の Abstract は、英語の語数で測ります。
+  en: 'Readers decide from the abstract alone whether to read the paper. An abstract that runs long takes as much time as the paper to judge, and tends to exceed the venue''s word limit. A paper with sections but no abstract makes the reader read on before learning what the study is. The abstract is the text under an "Abstract" heading, the paragraph after a line that says only "Abstract", or the text after "Abstract:" at the head of a paragraph. The Japanese abstract (要旨) of a bilingual paper is measured in characters.'
+
+message:
+  ja: 要旨が長すぎます
+  en: The abstract is too long
+
+messages:
+  chars:
+    ja: 要旨が {count} 字あります（{limit} 字まで）
+    en: The abstract has {count} characters (up to {limit})
+  words:
+    ja: 要旨が {count} 語あります（{limit} 語まで）
+    en: The abstract has {count} words (up to {limit})
+  missing:
+    ja: 節を立てた論文ですが、要旨がありません
+    en: This paper has sections but no abstract
+
+how_to_fix:
+  ja: 要旨は、目的・方法・結果・結論を一、二文ずつに絞ってください。要旨が無ければ、本文の前に「要旨」の節を足します。
+  en: Cut the abstract to a sentence or two each for the aim, the method, the results and the conclusion. If there is none, add an "Abstract" section before the body.
+
+levels:
+  ja: { strict: 600, normal: 1000, relaxed: 1400 }
+  en: { strict: 250, normal: 400, relaxed: 500 }
+
+use_for: [academic, legal, docs, literature, speech]
+
+group: structure
+summary:
+  ja: 字数（英語は語数）の上限を超える要旨と、節を立てた論文で要旨が無いもの
+  en: An abstract over the length limit, or a paper with sections that has no abstract
+example:
+  ja:
+    config: { genre: academic/paper }
+    before: |
+      # 昼寝と記憶
+
+      ## はじめに
+
+      昼寝が記憶に与える影響を調べた。
+
+      ## 方法
+
+      大学生 40 人に単語を覚えてもらった。
+    after: |
+      # 昼寝と記憶
+
+      ## 要旨
+
+      大学生 40 人で、昼寝が単語の記憶を助けるかを調べた。
+
+      ## はじめに
+
+      昼寝が記憶に与える影響を調べた。
+
+      ## 方法
+
+      大学生 40 人に単語を覚えてもらった。
+  en:
+    config: { genre: academic/paper }
+    before: |
+      # Naps and memory
+
+      ## Introduction
+
+      We studied how naps affect memory.
+
+      ## Methods
+
+      Forty students learned a list of words.
+    after: |
+      # Naps and memory
+
+      ## Abstract
+
+      With forty students, we tested whether a nap helps them remember words.
+
+      ## Introduction
+
+      We studied how naps affect memory.
+
+      ## Methods
+
+      Forty students learned a list of words.
+
+not_flagged:
+  ja: 要旨の有無は、「はじめに」「方法」「結果」「考察」のような論文の節の見出しが二つ以上ある文書だけで見ます。要旨に付けた札（要旨：、【要旨】）は数えません。論文のジャンルでだけ見ます。
+  en: 'Whether an abstract is present is checked only in a document with two or more headings that name a paper''s sections (Introduction, Methods, Results, Discussion). The label itself ("Abstract:") is not counted. Only the academic paper genre runs this rule.'
+level_meaning:
+  ja: 要旨 {limit} 字まで
+  en: up to {limit} words in the abstract
+rewrite:
+  ja:
+    direction: 要旨を、目的・方法・結果・結論をそれぞれ一、二文で言う形に縮めてください。背景の説明や先行研究の紹介は本文に移します。数字は、結論を支える一つか二つだけを残します。要旨が無ければ、本文から目的・方法・結果・結論を抜き出して要旨を書きます。
+    pairs:
+      - before: 近年、睡眠と記憶の関係については多くの研究が行われており、さまざまな知見が得られてきた。本研究では、そうした流れを踏まえ、昼寝が単語の記憶に与える影響について、大学生を対象として詳しく調べることとした。
+        after: 昼寝が単語の記憶を助けるかを、大学生 40 人で調べた。
+      - before: 実験の結果、昼寝をした群は、昼寝をしなかった群と比べて、翌日の再生率が高い傾向が見られ、その差は統計的にも意味のあるものであった。
+        after: 昼寝をした群は、翌日の再生率が 12 ポイント高かった。
+    keep:
+      - 本文にある目的・方法・結果・結論
+      - 結論を支える数字
+    avoid:
+      - 本文に無い結果を書く
+      - 結論を弱める・強める
+  en:
+    direction: Shorten the abstract to a sentence or two each for the aim, the method, the results and the conclusion. Move background and earlier work into the body. Keep only the one or two figures the conclusion rests on. If there is no abstract, write one from the aim, method, results and conclusion in the body.
+    pairs:
+      - before: In recent years, a great deal of research has examined the relationship between sleep and memory, and many findings have been reported. Building on this body of work, the present study set out to examine in detail the effect of naps on word memory in university students.
+        after: We tested whether a nap helps forty university students remember words.
+      - before: The results of the experiment showed that the group that napped tended to recall more words the next day than the group that did not, and the difference was statistically significant.
+        after: Students who napped recalled 12 points more words the next day.
+    keep:
+      - the aim, method, results and conclusion stated in the body
+      - the figures the conclusion rests on
+    avoid:
+      - stating a result the body does not report
+      - softening or strengthening the conclusion

package/rules/adversative-ga-repeat.yaml

@@ -0,0 +1,58 @@
+id: adversative-ga-repeat
+layer: L3
+status: experimental
+how_to_find: sentence-conjunctive-count
+word_list: adversative-particle
+requires: [pos]
+languages: [ja]
+severity: info
+
+name:
+  ja: 一文に逆接の「が」が二度
+  en: Two contrastive が in one sentence
+
+why:
+  ja: 「〜だが、〜するが、〜」のように逆接の「が」を一文で二度使うと、話が二度ひっくり返り、書き手の言いたい向きが読み手に分からなくなります。数えるのは接続助詞の「が」だけで、「私が」のような格助詞の「が」は数えません。
+  en: In Japanese, a sentence that turns twice with the contrastive particle が (〜だが、〜するが、) leaves the reader unsure which way it finally points. Only the conjunctive が is counted, not the case particle (私が).
+
+message:
+  ja: 一文に逆接の「が」が {count} 個あります（{limit} 個まで）
+  en: "{count} contrastive が in one sentence (limit {limit})"
+
+how_to_fix:
+  ja: 一つ目の「が」の所で文を切り、次の文を「しかし」で始めるか、どちらかの逆接を順接に言い換えてください。
+  en: Split the sentence at the first が and open the next with しかし, or turn one of the two into a plain link.
+
+levels: { strict: 1, normal: 1, relaxed: 2 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: readability
+summary:
+  ja: 「〜だが、〜するが、」のように、一文の中で逆接の「が」を二度使った所
+  en: A Japanese sentence that turns twice on the contrastive particle が
+example:
+  ja:
+    before: |
+      予算は足りるが、人手が足りないが、納期は守ります。
+    after: |
+      予算は足ります。人手は足りませんが、納期は守ります。
+
+not_flagged:
+  ja: 接続助詞の「が」だけを数えます。格助詞の「が」（私が、会社が）と、鉤括弧で引いたものの中は数えません。「けれど」「けど」も数えません。
+  en: Only the conjunctive が, outside 「」. The case particle が (私が) and けれど / けど are not counted.
+level_meaning:
+  ja: 一文の逆接の「が」{limit} 個まで
+  en: up to {limit} contrastive が in a sentence
+rewrite:
+  ja:
+    direction: 一つ目の逆接の「が」の所で文を切ってください。次の文の頭に、前との関係を言う語（しかし、ただし）を置けます。
+    pairs:
+      - before: 予算は足りるが、人手が足りないが、納期は守ります。
+        after: 予算は足ります。人手は足りませんが、納期は守ります。
+      - before: 新機能は便利だが、設定が難しいが、慣れれば速い。
+        after: 新機能は便利です。ただし設定が難しく、慣れるまでは時間がかかります。
+    keep:
+      - 二つの逆接が言っている事柄
+    avoid:
+      - 「が」を「けれど」に替えるだけで、一文のまま残す

package/rules/ai-generated-composite.yaml

@@ -18,6 +18,7 @@ from:
   - assistant-residue
   - announcing-opener
   - colon-lead-in
+  - ai-structure
 
 name:
   ja: 生成文の特徴がそろっている
@@ -38,7 +39,7 @@ how_to_fix:
 # 何種そろったら出すか。spec §20.2 は 3。
 levels: { strict: 2, normal: 3, relaxed: 5 }
 
-use_for: [blog, business, legal, docs, academic, literature, speech]
+use_for: [technical/readme, blog, business, legal, docs, academic, literature, speech]
 
 group: ai-tells
 summary: