@faircopy/rules-default 1.15.0 → 1.16.0

package/README.md

@@ -1,6 +1,6 @@
 # @faircopy/rules-default
 
-Default ruleset for faircopy. Ships three rules targeting the most common landing-page copy patterns.
+Default ruleset for faircopy. Ships nine rules targeting the most common landing-page copy patterns.
 
 ## Install
 
@@ -12,6 +12,33 @@ npm i @faircopy/rules-default
 
 ## Rules
 
+### `no-complex-sentences`
+
+Flags individual sentences whose Flesch-Kincaid grade level exceeds a target.
+
+```
+warn[no-complex-sentences]: sentence readability is grade 18.5 — simplify to 12 or below
+```
+
+**Options:**
+
+```ts
+{
+  maxGradeLevel?: number  // Default: 12
+  minWords?: number       // Minimum words before scoring a sentence. Default: 10
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-complex-sentences': ['warn', { maxGradeLevel: 10, minWords: 8 }],
+}
+```
+
+---
+
 ### `no-em-dash`
 
 Bans the em-dash character (`—`, U+2014) in marketing copy.
@@ -65,6 +92,32 @@ rules: {
 
 ---
 
+### `no-filler-words`
+
+Bans filler words that pad out a sentence without adding meaning.
+
+```
+error[no-filler-words]: remove "just" — it's filler
+```
+
+**Options:**
+
+```ts
+{
+  words: string[]  // Default: ['just']
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-filler-words': ['error', { words: ['just', 'basically', 'literally'] }],
+}
+```
+
+---
+
 ### `no-rhetorical-scaffolding`
 
 Bans two formulaic patterns:
@@ -86,3 +139,178 @@ error[no-rhetorical-scaffolding]: avoid "Without X / With X" — drop the setup
   extraPatterns?: string[]               // Additional regex patterns to ban.
 }
 ```
+
+---
+
+### `no-non-inclusive-language`
+
+Flags non-inclusive terms and suggests neutral alternatives.
+
+Default terms include `guys`, `manpower`, `whitelist`, `blacklist`, `master`, `slave`, `crazy`, `insane`, `dumb`, `lame`, `sanity check`, `blind spot`, `grandfathered`, and `mankind`.
+
+```
+error[no-non-inclusive-language]: replace "guys" with a neutral alternative such as "everyone, team, folks"
+```
+
+**Options:**
+
+```ts
+{
+  terms?: { term: string; alternatives: string[]; exact?: boolean }[]
+  allowedTerms?: string[]
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-non-inclusive-language': ['error', {
+    terms: [
+      { term: 'guys', alternatives: ['everyone', 'team'] },
+      { term: 'rockstar', alternatives: ['expert', 'skilled'] },
+    ],
+    allowedTerms: ['master'],
+  }],
+}
+```
+
+Set `exact: true` on a multi-word term to match the whole phrase with word boundaries. This is useful for phrases like `sanity check`, ensuring `sanity checker` is not flagged.
+
+---
+
+### `no-redundant-phrases`
+
+Flags wordy redundant phrases and suggests concise replacements.
+
+Default phrases include:
+
+| Phrase | Suggested replacement |
+|---|---|
+| `in order to` | `to` |
+| `due to the fact that` | `because` |
+| `in spite of the fact that` | `although` |
+| `at this point in time` | `now` |
+| `in the event that` | `if` |
+| `for the purpose of` | `to` |
+| `with regard to` | `about` |
+| `in close proximity to` | `near` |
+| `a large number of` | `many` |
+| `the reason is that` | `because` |
+| `it is important to note that` | *(delete)* |
+| `needless to say` | *(delete)* |
+
+```
+warn[no-redundant-phrases]: "in order to" is redundant — use "to"
+```
+
+**Options:**
+
+```ts
+{
+  phrases?: { phrase: string; replacement: string }[]
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-redundant-phrases': ['warn', {
+    phrases: [
+      { phrase: 'in order to', replacement: 'to' },
+      { phrase: 'touch base', replacement: 'talk' },
+    ],
+  }],
+}
+```
+
+Set `replacement` to an empty string to suggest deleting the phrase entirely.
+
+---
+
+### `no-cliches`
+
+Flags overused or clichéd phrases and suggests fresher alternatives.
+
+Default phrases include:
+
+| Phrase | Suggested alternatives |
+|---|---|
+| `world-class` | `top-tier`, `exceptional`, `outstanding` |
+| `best-in-class` | `leading`, `top-performing`, `category-leading` |
+| `cutting-edge` | `advanced`, `modern`, `latest` |
+| `state-of-the-art` | `advanced`, `modern`, `sophisticated` |
+| `game changer` | `breakthrough`, `transformation`, `major advance` |
+| `think outside the box` | `be creative`, `innovate`, `find a new approach` |
+| `at the end of the day` | `ultimately`, `finally`, `in summary` |
+| `low-hanging fruit` | `easy wins`, `quick opportunities`, `simple targets` |
+| `move the needle` | `make a measurable difference`, `drive results`, `create impact` |
+| `circle back` | `follow up`, `reconnect`, `return to this` |
+| `hit the ground running` | `start quickly`, `get started immediately`, `begin effectively` |
+| `boil the ocean` | `take on too much`, `overcomplicate`, `lose focus` |
+| `paradigm shift` | `fundamental change`, `new approach`, `transformation` |
+| `next level` | `advanced`, `improved`, `elevated` |
+| `seamless` | `smooth`, `effortless`, `frictionless` |
+| `robust` | `strong`, `resilient`, `reliable` |
+| `leverage` | `use`, `take advantage of`, `utilize` |
+| `synergy` | `collaboration`, `combined effect`, `partnership` |
+
+```
+warn[no-cliches]: replace "world-class" with a fresher alternative such as "top-tier, exceptional, outstanding"
+```
+
+**Options:**
+
+```ts
+{
+  phrases?: { phrase: string; alternatives: string[] }[]
+  allow?: string[]
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-cliches': ['warn', {
+    phrases: [
+      { phrase: 'world-class', alternatives: ['top-tier', 'exceptional'] },
+      { phrase: 'low-hanging fruit', alternatives: ['easy wins'] },
+    ],
+    allow: ['robust'],
+  }],
+}
+```
+
+---
+
+### `no-passive-voice`
+
+Flags likely passive-voice constructions using auxiliary + past participle patterns.
+
+```
+warn[no-passive-voice]: rewrite passive construction "was approved" with a named actor
+```
+
+Passive voice often hides the actor and adds drag. Prefer naming who did the action unless the actor genuinely does not matter.
+
+**Options:**
+
+```ts
+{
+  auxiliaries?: string[]  // Default: ['is', 'are', 'was', 'were', 'be', 'been', 'being']
+  participles?: string[]  // Past participles to flag. Default is a curated list of common action participles.
+  allowedPhrases?: string[] // Phrases to allow even if they match the passive pattern.
+}
+```
+
+**Config example:**
+
+```ts
+rules: {
+  'no-passive-voice': ['warn', {
+    allowedPhrases: ['is licensed', 'was founded'],
+  }],
+}
+```

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 import { Rule } from '@faircopy/core';
 
+interface NoComplexSentencesOptions {
+    /** Target Flesch-Kincaid grade level. Sentences scoring above this are flagged. */
+    maxGradeLevel?: number;
+    /** Minimum words a sentence must contain before it is scored. Shorter sentences are too noisy. */
+    minWords?: number;
+}
+declare const noComplexSentences: Rule<NoComplexSentencesOptions>;
+
 interface NoEmDashOptions {
     /** Additionally flag en-dashes (U+2013). Default false. */
     flagEnDash?: boolean;
@@ -23,7 +31,67 @@ interface NoRhetoricalScaffoldingOptions {
 }
 declare const noRhetoricalScaffolding: Rule<NoRhetoricalScaffoldingOptions>;
 
+interface NonInclusiveTerm {
+    term: string;
+    alternatives: string[];
+    /** Set to true on a multi-word phrase to require word boundaries. Default false matches the phrase anywhere. Single-word terms always use word boundaries. */
+    exact?: boolean;
+}
+interface NoNonInclusiveLanguageOptions {
+    /** Terms to flag with suggested alternatives. */
+    terms?: NonInclusiveTerm[];
+    /** Additional allowed terms that override defaults. */
+    allowedTerms?: string[];
+}
+declare const noNonInclusiveLanguage: Rule<NoNonInclusiveLanguageOptions>;
+
+interface RedundantPhrase {
+    phrase: string;
+    replacement: string;
+}
+interface NoRedundantPhrasesOptions {
+    phrases?: RedundantPhrase[];
+}
+declare const noRedundantPhrases: Rule<NoRedundantPhrasesOptions>;
+
+interface NoPassiveVoiceOptions {
+    /** Auxiliary verbs that can introduce a passive construction. */
+    auxiliaries?: string[];
+    /** Past participles to flag when preceded by an auxiliary. */
+    participles?: string[];
+    /** Phrases to allow even if they match the passive pattern. */
+    allowedPhrases?: string[];
+}
+declare const noPassiveVoice: Rule<NoPassiveVoiceOptions>;
+
+interface ClichePhrase {
+    phrase: string;
+    alternatives: string[];
+}
+interface NoClichesOptions {
+    /** Phrases to flag with suggested alternatives. Replaces the default list. */
+    phrases?: ClichePhrase[];
+    /** Default phrases to allow. */
+    allow?: string[];
+}
+declare const noCliches: Rule<NoClichesOptions>;
+
+interface NoRepetitiveSentenceStartingsOptions {
+    /** Number of consecutive sentences that must share the same starting word before flagging. */
+    threshold?: number;
+    /** Minimum sentence length (in words) to count. Very short sentences are ignored. */
+    minWords?: number;
+    /** Words or phrases that are allowed to start multiple sentences. */
+    allow?: string[];
+}
+declare const noRepetitiveSentenceStartings: Rule<NoRepetitiveSentenceStartingsOptions>;
+
+interface NoFillerWordsOptions {
+    words: string[];
+}
+declare const noFillerWords: Rule<NoFillerWordsOptions>;
+
 /** All built-in rules keyed by their rule ID. */
 declare const ruleRegistry: Map<string, Rule>;
 
-export { type NoEmDashOptions, type NoRhetoricalScaffoldingOptions, type NoWeaselWordsOptions, noEmDash, noRhetoricalScaffolding, noWeaselWords, ruleRegistry };
+export { type ClichePhrase, type NoClichesOptions, type NoComplexSentencesOptions, type NoEmDashOptions, type NoFillerWordsOptions, type NoNonInclusiveLanguageOptions, type NoPassiveVoiceOptions, type NoRedundantPhrasesOptions, type NoRepetitiveSentenceStartingsOptions, type NoRhetoricalScaffoldingOptions, type NoWeaselWordsOptions, type NonInclusiveTerm, type RedundantPhrase, noCliches, noComplexSentences, noEmDash, noFillerWords, noNonInclusiveLanguage, noPassiveVoice, noRedundantPhrases, noRepetitiveSentenceStartings, noRhetoricalScaffolding, noWeaselWords, ruleRegistry };