nollm 0.0.0 → 0.2.0

package/README.md

@@ -2,10 +2,14 @@
 
 Lint against LLMisms in your codebase.
 
+Pronounced "nollum": like gollum, with an n.
+
 `nollm` reads every file that git tracks or does not ignore.
 It checks prose files line by line, and code files comment by comment.
 Each finding prints as soon as it is found.
 
+![!this project was created with claude code](https://i.imgflip.com/4h68b2.jpg)
+
 ```
 npx nollm
 ```
@@ -47,12 +51,21 @@ Paths can be files or directories.
 
 The exit code is 1 when there are findings, and 2 on a usage error.
 
-Output looks like this:
+Output is one block per file, grouped by rule:
 
 ```
-README.md:3:14  filler-word  Filler. Delete it or replace it: "simply"
-src/index.js:1:1  what-comment  Comment narrates what the code does. Say why, or delete it: "// This function"
-2 problems in 2 files (5 files checked, 0.07s)
+README.md
+  filler-word  Filler. Delete it or replace it
+    3:14  "simply"
+    3:33  "robust"
+  chat-opener  Chat opener. Start with the answer
+    7:1   "Great question"
+
+src/index.js
+  what-comment  Comment narrates what the code does. Say why, or delete it
+    1:1  "// This function"
+
+4 problems in 2 files (5 files checked, 0.07s)
 ```
 
 ## What gets checked
@@ -62,30 +75,39 @@ Every line is checked.
 
 Code files: JavaScript, TypeScript, Python, Ruby, Rust, Go, shell, YAML, TOML, HTML, Handlebars, `.gjs`, `.gts`, and many more.
 Only comments are checked, so identifiers and string contents do not trigger rules.
-The `error-exclamation` rule is the exception. It checks every line, because it targets error strings.
 
 Files of other types, binary files, lockfiles, minified files, and files over 2 MB are skipped.
 
 ## Rules
 
-| Rule                  | Catches                                                                 |
-| --------------------- | ----------------------------------------------------------------------- |
-| `banned-word`         | genuinely, load-bearing, crutch, spearheaded, fails loudly, and friends |
-| `em-dash`             | The em dash character                                                   |
-| `bold-fragment`       | `**Bold label:** followed by plain text` in markdown                    |
-| `filler-word`         | simply, robust, leverage, utilize, in order to, keep in mind, and more  |
-| `llm-vocabulary`      | delve, tapestry, crucial, game-changer, battle-tested, and more         |
-| `chat-opener`         | Lines that start with "Great question", "Certainly", "Let me", and more |
-| `chat-closer`         | "Hope this helps", "Let me know if", "Feel free to", and more           |
-| `ai-disclosure`       | "As an AI", "my training data", and more                                |
-| `error-exclamation`   | "Oops", "Uh oh", "Something went wrong"                                 |
-| `contrast-cliche`     | "not just X, but Y" and "it's not X, it's Y"                            |
-| `rhetorical-question` | "Why? Because" and "The result?"                                        |
-| `emoji`               | Emoji                                                                   |
-| `diff-comment`        | Comments about the change: "no longer", "as discussed", "previously"    |
-| `what-comment`        | Comments that narrate the code: "This function returns", "Loop over"    |
-
-Run `nollm --list-rules` for the full list.
+| Rule                      | Catches                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `banned-word`             | genuinely, load-bearing, crutch, spearheaded, fails loudly, and friends                                            |
+| `em-dash`                 | The em dash character                                                                                              |
+| `bold-list-item`          | List items like `- **Label:** plain text`                                                                          |
+| `filler-word`             | simply, seamlessly, seamless, robust                                                                               |
+| `llm-vocabulary`          | delve, tapestry, crucial, game-changer, battle-tested, and more                                                    |
+| `chat-opener`             | Lines that start with "Great question", "Certainly", "Let me", and more                                            |
+| `chat-closer`             | "Hope this helps", "Let me know if", "Feel free to", and more                                                      |
+| `ai-disclosure`           | "As an AI", "my training data", and more                                                                           |
+| `contrast-cliche`         | "not just X, but Y" and "it's not X, it's Y"                                                                       |
+| `rhetorical-question`     | "Why? Because" and "The result?"                                                                                   |
+| `emoji-list`              | List items that start with an emoji                                                                                |
+| `no-short-term-relevance` | Comments that stop making sense once the change lands: "no longer", "no behavior change", "for now", "Previously," |
+| `what-comment`            | Comments that narrate the code: "This function returns", "Loop over"                                               |
+| `quoted-error`            | Comments that quote an error message: `"Cannot read properties of..."`                                             |
+| `dramatic-verb`           | blows up, dies with, falls over, chokes on, and friends                                                            |
+| `parenthetical-aside`     | Asides like `(and their compiled handles)`                                                                         |
+| `long-sentence`           | A sentence over 30 words                                                                                           |
+| `wall-of-text`            | A paragraph over 120 words or 7 sentences                                                                          |
+| `uniform-paragraphs`      | Three or more paragraphs in a row of about the same length                                                         |
+| `uniform-sentences`       | Four or more sentences of about the same length                                                                    |
+
+Run `nollm --list-rules` for the full list with the scope of each rule.
+
+Prose and comments get different rules.
+For example, `em-dash` runs in code comments and not in markdown.
+To change where a rule runs, set its `scope` in the config.
 
 ## Configuration
 
@@ -110,7 +132,10 @@ export default {
 
   rules: {
     // turn a rule off
-    "em-dash": false,
+    "chat-opener": false,
+
+    // run a built in rule somewhere else
+    "em-dash": { scope: "text" },
 
     // add a rule, or replace a built in one
     "open-todo": {
@@ -124,13 +149,18 @@ export default {
 
 In JSON configs, write the pattern as a string and add flags in a `flags` key.
 
+A rule can also have a `check` function instead of a pattern.
+It gets every line of the file as `{ text, line, column }`, plus the scope, and returns findings of the same shape, plus `text`.
+The `paragraphs` export groups those lines into paragraphs with word and sentence counts.
+
 `scope` is one of:
 
 - `prose`: prose files only
 - `comments`: comments in code files only
+- `text`: prose and comments. This is the default
 - `everywhere`: every line of every file
 
-A rule with no scope runs in prose and in comments.
+A config entry for a built in rule can change only `scope` or `message`. The pattern stays.
 
 To silence one line, put `nollm-ignore-next-line` on the line before it.
 To silence a whole file, put `nollm-ignore-file` anywhere in it.

package/bin/nollm.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
 import { main } from "../src/cli.js";
 
+// A closed pipe, for example `nollm | head`, is not an error.
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+
 process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nollm",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "lint against LLMisms in your codebase",
   "keywords": [
     "comments",
@@ -31,14 +31,6 @@
       "default": "./src/index.js"
     }
   },
-  "scripts": {
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "lint": "oxlint && pnpm format:check && publint && pnpm lint:prose",
-    "lint:fix": "oxlint --fix && oxfmt",
-    "lint:prose": "node bin/nollm.js",
-    "test": "vitest run"
-  },
   "dependencies": {
     "ignore": "^7.0.9",
     "lilconfig": "^3.1.3",
@@ -49,10 +41,18 @@
     "oxfmt": "^0.68.0",
     "oxlint": "^1.83.0",
     "publint": "^0.3.24",
+    "release-plan": "^0.18.0",
     "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">= 22.5"
   },
-  "packageManager": "pnpm@11.22.0"
-}
+  "scripts": {
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint && pnpm format:check && publint && pnpm lint:prose",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "lint:prose": "node bin/nollm.js",
+    "test": "vitest run"
+  }
+}

package/src/check.js

@@ -45,6 +45,20 @@ function run(findings, segments, rules, scope) {
     const rule = rules[r];
     if (!applies(rule, scope)) continue;
 
+    if (typeof rule.check === "function") {
+      const found = rule.check(segments, scope);
+      for (let f = 0; f < found.length; f++) {
+        findings.push({
+          line: found[f].line,
+          column: found[f].column,
+          ruleId: rule.id,
+          message: rule.message,
+          text: found[f].text,
+        });
+      }
+      continue;
+    }
+
     for (let s = 0; s < segments.length; s++) {
       const segment = segments[s];
       const pattern = rule.pattern;

package/src/cli.js

@@ -60,7 +60,8 @@ export async function main(
 
   if (values["list-rules"]) {
     for (let i = 0; i < rules.length; i++) {
-      stdout.write(`${rules[i].id.padEnd(20)} ${rules[i].message}\n`);
+      const scope = (rules[i].scope ?? "text").padEnd(10);
+      stdout.write(`${rules[i].id.padEnd(24)} ${scope} ${rules[i].message}\n`);
     }
     return 0;
   }
@@ -86,11 +87,8 @@ export async function main(
       git: values.git,
       jobs,
       onResult(result) {
-        if (values.quiet) return;
-        const findings = result.findings;
-        for (let i = 0; i < findings.length; i++) {
-          stdout.write(formatFinding(result.file, findings[i], paint));
-        }
+        if (values.quiet || result.findings.length === 0) return;
+        stdout.write(formatFile(result.file, result.findings, paint));
       },
     });
   } catch (error) {
@@ -107,8 +105,43 @@ export async function main(
   return summary.findings > 0 ? 1 : 0;
 }
 
-function formatFinding(file, finding, paint) {
-  const where = paint("dim", `${file}:${finding.line}:${finding.column}`);
-  const rule = paint("yellow", finding.ruleId);
-  return `${where}  ${rule}  ${finding.message}: ${JSON.stringify(finding.text)}\n`;
+/**
+ * One block per file:
+ *
+ *   README.md
+ *     wall-of-text  Wall of text. Split the paragraph
+ *       3:1   "131 words, 9 sentences: The linter reads every..."
+ *       40:1  "202 words, 12 sentences: Each worker loads the..."
+ *
+ * Findings are grouped by rule, in order of first appearance.
+ */
+function formatFile(file, findings, paint) {
+  const groups = new Map();
+  for (let i = 0; i < findings.length; i++) {
+    const finding = findings[i];
+    let group = groups.get(finding.ruleId);
+    if (!group) {
+      group = { message: finding.message, items: [] };
+      groups.set(finding.ruleId, group);
+    }
+    group.items.push(finding);
+  }
+
+  let out = `${paint("underline", file)}\n`;
+  for (const [ruleId, group] of groups) {
+    out += `  ${paint("yellow", ruleId)}  ${group.message}\n`;
+
+    let width = 0;
+    for (let i = 0; i < group.items.length; i++) {
+      const item = group.items[i];
+      width = Math.max(width, `${item.line}:${item.column}`.length);
+    }
+
+    for (let i = 0; i < group.items.length; i++) {
+      const item = group.items[i];
+      const where = `${item.line}:${item.column}`.padEnd(width);
+      out += `    ${paint("dim", where)}  ${JSON.stringify(item.text)}\n`;
+    }
+  }
+  return out + "\n";
 }

package/src/config.js

@@ -62,15 +62,15 @@ function resolveRules(overrides = {}, words = []) {
 
   for (let i = 0; i < builtinRules.length; i++) {
     const rule = builtinRules[i];
-    const override = overrides[rule.id];
+    const override = overrideFor(overrides, rule);
     if (override === false) continue;
-    rules.push(isObject(override) ? customRule(rule.id, override) : rule);
+    rules.push(isObject(override) ? customRule(rule.id, override, rule) : rule);
   }
 
   for (const id in overrides) {
     const override = overrides[id];
     if (!isObject(override)) continue;
-    if (builtinRules.some((rule) => rule.id === id)) continue;
+    if (builtinRules.some((rule) => namesOf(rule).includes(id))) continue;
     rules.push(customRule(id, override));
   }
 
@@ -86,12 +86,35 @@ function resolveRules(overrides = {}, words = []) {
   return rules;
 }
 
-function customRule(id, override) {
+/**
+ * The config entry for a built in rule, under its id or one of its old ids.
+ */
+function overrideFor(overrides, rule) {
+  const name = namesOf(rule).find((candidate) => candidate in overrides);
+  return name === undefined ? undefined : overrides[name];
+}
+
+function namesOf(rule) {
+  return [rule.id].concat(rule.aliases ?? []);
+}
+
+/**
+ * Builds a rule from a config entry.
+ * Keys that the entry leaves out come from the built in rule, when there is one.
+ */
+function customRule(id, override, base = {}) {
+  const message = override.message ?? base.message ?? id;
+  const scope = override.scope ?? base.scope;
+  const check = override.check ?? (override.pattern === undefined ? base.check : undefined);
+
+  if (typeof check === "function") {
+    return { id, message, check, scope };
+  }
   return {
     id,
-    message: override.message ?? id,
-    pattern: toGlobal(id, override.pattern, override.flags),
-    scope: override.scope,
+    message,
+    pattern: toGlobal(id, override.pattern ?? base.pattern, override.flags),
+    scope,
   };
 }
 
@@ -102,7 +125,9 @@ function toGlobal(id, pattern, flags = "") {
   if (pattern instanceof RegExp) {
     return pattern.global ? pattern : new RegExp(pattern.source, pattern.flags + "g");
   }
-  throw new Error(`Rule "${id}" needs a pattern: a RegExp, or a string with optional flags`);
+  throw new Error(
+    `Rule "${id}" needs a pattern (a RegExp, or a string with optional flags) or a check function`,
+  );
 }
 
 function isObject(value) {

package/src/index.d.ts

@@ -1,12 +1,31 @@
-export type Scope = "prose" | "comments" | "everywhere";
+export type Scope = "prose" | "comments" | "text" | "everywhere";
 
-export interface Rule {
+export interface PatternRule {
   id: string;
+  /** Old ids of this rule. A config may still refer to the rule by one of them. */
+  aliases?: string[];
   message: string;
   pattern: RegExp;
   scope?: Scope;
 }
 
+export interface ShapeFinding {
+  line: number;
+  column: number;
+  text: string;
+}
+
+export interface CheckRule {
+  id: string;
+  /** Old ids of this rule. A config may still refer to the rule by one of them. */
+  aliases?: string[];
+  message: string;
+  check: (segments: Segment[], scope: Scope) => ShapeFinding[];
+  scope?: Scope;
+}
+
+export type Rule = PatternRule | CheckRule;
+
 export interface Finding {
   line: number;
   column: number;
@@ -48,8 +67,9 @@ export interface Config {
 }
 
 export interface RuleConfig {
-  pattern: RegExp | string;
+  pattern?: RegExp | string;
   flags?: string;
+  check?: (segments: Segment[], scope: Scope) => ShapeFinding[];
   message?: string;
   scope?: Scope;
 }
@@ -83,6 +103,15 @@ export function collectFiles(
 ): Promise<string[]>;
 export function extractComments(source: string, language: Language): Segment[];
 export function extractLines(source: string): Segment[];
+export function paragraphs(segments: Segment[], options?: { inComments?: boolean }): Paragraph[];
+
+export interface Paragraph {
+  line: number;
+  column: number;
+  words: number;
+  sentences: number[];
+  preview: string;
+}
 export function findConfig(cwd: string): Promise<string | null>;
 export function loadConfig(configPath: string | null): Promise<Config>;
 export function lint(options?: LintOptions): Promise<Summary>;

package/src/index.js

@@ -5,3 +5,4 @@ export { extractComments, extractLines } from "./comments.js";
 export { findConfig, loadConfig, SEARCH_PLACES } from "./config.js";
 export { lint } from "./lint.js";
 export { rules } from "./rules.js";
+export { paragraphs } from "./shape.js";

package/src/rules.js

@@ -1,14 +1,19 @@
+import { longSentences, uniformParagraphs, uniformSentences, wallOfText } from "./shape.js";
+
 /**
- * A rule is a regular expression plus a message.
+ * A rule is a regular expression plus a message,
+ * or a check function that reads all lines at once.
  *
  * scope controls where the rule runs:
  *   prose      → markdown and text files
  *   comments   → comments inside code files
+ *   text       → both of the above (the default)
  *   everywhere → every line of every file
  *
- * A rule with no scope runs in prose and in comments.
- *
  * Patterns must have the g flag.
+ *
+ * A check function gets the segments of one file and the scope
+ * they came from. It returns { line, column, text } per finding.
  */
 
 function words(list) {
@@ -35,31 +40,7 @@ const BANNED_WORDS = [
   "carrying",
 ];
 
-const FILLER_WORDS = [
-  "simply",
-  "seamlessly",
-  "seamless",
-  "robust",
-  "powerful",
-  "comprehensive",
-  "leverage",
-  "leverages",
-  "leveraged",
-  "leveraging",
-  "utilize",
-  "utilizes",
-  "utilized",
-  "utilizing",
-  "in order to",
-  "prior to",
-  "in the event that",
-  "it is worth noting",
-  "it's worth noting",
-  "it is important to note",
-  "it's important to note",
-  "it should be noted",
-  "keep in mind",
-];
+const FILLER_WORDS = ["simply", "seamlessly", "seamless", "robust"];
 
 const LLM_VOCABULARY = [
   "delve",
@@ -150,33 +131,59 @@ const AI_DISCLOSURES = [
   "my training data",
 ];
 
-const ERROR_EXCLAMATIONS = [
-  "uh oh",
-  "uh-oh",
-  "oh no",
-  "oops",
-  "whoops",
-  "there seems to be a problem",
-  "something went wrong",
-];
-
-const DIFF_TALK = [
+// Talk that only makes sense while the change is under review.
+// Once merged, nobody reading the code knows what "the old way" or "this PR" was.
+const PR_TALK = [
+  // The change itself
   "as requested",
   "as discussed",
   "per the discussion",
   "per our discussion",
   "per the review",
   "per review",
+  "per feedback",
+  "based on feedback",
+  "review feedback",
+  "review comment",
+  "review comments",
+  "addressing feedback",
+  "addresses feedback",
+  "addressed feedback",
+  "requested changes",
+  "code review",
+  "reviewer",
+  "reviewers",
   "this pr",
+  "this mr",
+  "pr description",
+  "pull request",
+  "merge request",
   "this commit",
   "this diff",
   "this change",
+  "this refactor",
+  "the refactor",
+  "this migration",
+  "this upgrade",
+  "the upgrade",
+  "after upgrading",
+  "before upgrading",
+  "since upgrading",
+  "version bump",
+  "this bump",
+  "cherry-picked",
+  "cherry picked",
+  "backported",
+  "rebased",
+  "merge conflict",
+  "merge conflicts",
+  "work in progress",
+  "wip",
+  // How the code used to be
   "no longer",
   "used to be",
   "used to use",
   "used to return",
-  "previously",
-  "formerly",
   "the old implementation",
   "the old version",
   "the old code",
@@ -195,8 +202,221 @@ const DIFF_TALK = [
   "now handles",
   "now lives",
   "moved to",
+  "never worked",
+  "wasn't working",
+  "was not working",
+  "weren't working",
+  "were not working",
+  "didn't work before",
+  "did not work before",
+  "stopped working",
+  "was failing",
+  "were failing",
+  "started failing",
+  "kept failing",
+  "on the main branch",
+  "on the master branch",
+  "compared to main",
+  "compared to master",
+  // Claims that nothing changed
+  "no behavior change",
+  "no behaviour change",
+  "no functional change",
+  "no functional changes",
+  "no-op change",
+  "behavior is unchanged",
+  "behaviour is unchanged",
+  "behavior unchanged",
+  "behaviour unchanged",
+  "no change in behavior",
+  "no change in behaviour",
+  "same as before",
+  "same behavior as before",
+  "same behaviour as before",
+  "behaves as before",
+  "behaves the same",
+  "works the same",
+  "functionally equivalent",
+  "functionally identical",
+  "preserves behavior",
+  "preserves behaviour",
+  "preserve behavior",
+  "preserve behaviour",
+  "preserves existing behavior",
+  "preserves existing behaviour",
+  "existing behavior",
+  "existing behaviour",
+  "unchanged from",
+  // Leaving things as they were
+  "keeping it off",
+  "keeping it on",
+  "keeping this off",
+  "keeping this on",
+  "keeping it disabled",
+  "keeping it enabled",
+  "keeping this disabled",
+  "keeping this enabled",
+  "keep it off",
+  "keep this off",
+  "kept as is",
+  "kept as-is",
+  "left as is",
+  "left as-is",
+  "leave as is",
+  "leave as-is",
+  "leaving as is",
+  "leaving as-is",
+  "left in place",
+  "left untouched",
+  "left alone",
+  "leaving this alone",
+  "not touching",
+  "didn't touch",
+  "did not touch",
+  // Scope and follow-ups
+  "for now",
+  "out of scope",
+  "scope of this",
+  "follow-up pr",
+  "follow up pr",
+  "in a follow-up",
+  "in a follow up",
+  "as a follow-up",
+  "as a follow up",
+  "separate pr",
+  "later pr",
+  "future pr",
+  "another pr",
+  "next pr",
+  "will be removed",
+  "can be removed",
+  "to be removed",
+  "should be removed",
+  "safe to remove",
+  "safe to delete",
+  "can be deleted",
+  "will be deleted",
+  "remove this once",
+  "remove this after",
+  "remove this when",
+  "delete this once",
+  "delete this after",
+  "clean up later",
+  "cleanup later",
+  "clean this up later",
+  "will clean up",
+  "will be cleaned up",
+  "quick fix",
+  "quick hack",
+  "quick and dirty",
+  "band-aid",
+  "bandaid",
+  "band aid",
+  "stopgap",
+  "stop-gap",
+  "stop gap",
+  "hotfix",
+  "hot fix",
+  // The author talking about their own process
+  "tested locally",
+  "verified locally",
+  "confirmed locally",
+  "works locally",
+  "tested with",
+  "tested on",
+  "tested against",
+  "verified with",
+  "confirmed with",
+  "ci passes",
+  "passes ci",
+  "ci is green",
+  "ci was failing",
+  "ci fails",
+  "ci failed",
+  "i tested",
+  "i verified",
+  "i checked",
+  "i confirmed",
+  "i tried",
+  "i went with",
+  "i chose",
+  "i opted",
+  "i decided",
+  "i ended up",
+  "i left",
+  "i kept",
+  "i removed",
+  "i replaced",
+  "i added",
+  "i moved",
+  "i renamed",
+  "i changed",
+  "i updated",
+  "i bumped",
+  "i couldn't",
+  "i could not",
+  "i'm not sure",
+  "i am not sure",
+  "not sure if",
+  "not sure why",
+  "not sure whether",
+  "we tested",
+  "we verified",
+  "we confirmed",
+  "we decided",
+  "we went with",
+  "we opted",
+  "we couldn't",
+  "we could not",
+];
+
+// PR talk only when it opens a sentence. "used previously" is fine.
+const PR_OPENERS = ["previously", "formerly", "originally"];
+
+const DRAMATIC_VERBS = [
+  "blow up",
+  "blows up",
+  "blowing up",
+  "blew up",
+  "die with",
+  "dies with",
+  "died with",
+  "fall over",
+  "falls over",
+  "fell over",
+  "choke on",
+  "chokes on",
+  "choked on",
+  "trip over",
+  "trips over",
+  "tripped over",
+  "bites us",
+  "bites you",
+  "bit us",
+  "explode",
+  "explodes",
+  "exploded",
+  "barf",
+  "barfs",
+];
+
+const ERROR_OPENERS = [
+  "Cannot",
+  "Could not",
+  "Couldn't",
+  "Unable to",
+  "Failed to",
+  "Unexpected",
+  "Invalid",
+  "Expected",
+  "Missing",
+  "Uncaught",
+  "Assertion Failed",
+  "Maximum call stack",
 ];
 
+const ASIDE_OPENERS = ["and", "but", "though", "although", "plus", "as well as", "not to mention"];
+
 const WHAT_COMMENT_STARTS = [
   "this function",
   "this method",
@@ -237,6 +457,9 @@ const WHAT_COMMENT_STARTS = [
 // A comment starts after its marker, so the rule skips the marker first.
 const COMMENT_START = String.raw`^\s*(?:\/\/+|#+|\*+|\/\*+|<!--|--|;+|%+|"""|''')?\s*`;
 
+// The start of a comment or of a sentence, as a lookbehind.
+const SENTENCE_START = String.raw`(?<=${COMMENT_START}|[.!?:;]\s+)`;
+
 export const rules = [
   {
     id: "banned-word",
@@ -247,11 +470,12 @@ export const rules = [
     id: "em-dash",
     message: "Em dash. Use a comma, a colon, or a new sentence",
     pattern: /\u2014/g,
+    scope: "comments",
   },
   {
-    id: "bold-fragment",
-    message: "Bold fragment followed by plain text",
-    pattern: /^\s*(?:[-*+]|\d+[.)])?\s*(?:\*\*[^*\n]{1,80}\*\*|__[^_\n]{1,80}__):?\s+\S/gm,
+    id: "bold-list-item",
+    message: "List item with a bold label followed by plain text",
+    pattern: /^\s*(?:[-*+]|\d+[.)])\s+(?:\*\*[^*\n]{1,80}\*\*|__[^_\n]{1,80}__):?(?=\s+[^\s*_])/gm,
     scope: "prose",
   },
   {
@@ -282,12 +506,6 @@ export const rules = [
     message: "Text written from the point of view of a chat assistant",
     pattern: anyOf(AI_DISCLOSURES),
   },
-  {
-    id: "error-exclamation",
-    message: "Error message with an exclamation instead of a cause",
-    pattern: anyOf(ERROR_EXCLAMATIONS),
-    scope: "everywhere",
-  },
   {
     id: "contrast-cliche",
     message: "Contrast cliche (not just X, but Y)",
@@ -302,20 +520,67 @@ export const rules = [
     scope: "prose",
   },
   {
-    id: "emoji",
-    message: "Emoji",
-    pattern: /(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)/gu,
+    id: "emoji-list",
+    message: "List item that starts with an emoji",
+    pattern:
+      /^\s*(?:[-*+]|\d+[.)])\s+(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)/gmu,
+    scope: "prose",
   },
   {
-    id: "diff-comment",
-    message: "Comment describes the change, not the code. Put it in the commit message",
-    pattern: anyOf(DIFF_TALK),
+    id: "no-short-term-relevance",
+    aliases: ["diff-comment"],
+    message: "Comment only makes sense while the change is under review. Say it in the PR",
+    pattern: new RegExp(
+      String.raw`\b(?:${words(PR_TALK)})\b|${SENTENCE_START}(?:${words(PR_OPENERS)})\b`,
+      "gmi",
+    ),
+    scope: "comments",
+  },
+  {
+    id: "quoted-error",
+    message:
+      "Comment quotes an error message. Say what breaks and why, not what the terminal printed",
+    pattern: new RegExp(
+      String.raw`["\u201C](?:(?:${words(ERROR_OPENERS)})\b|\w+Error:|\w+ is not (?:a function|defined|iterable)\b)[^"\u201D\n]*["\u201D]?`,
+      "g",
+    ),
     scope: "comments",
   },
+  {
+    id: "dramatic-verb",
+    message: "Dramatic failure verb. Say what happens: throws, hangs, returns null",
+    pattern: anyOf(DRAMATIC_VERBS),
+  },
+  {
+    id: "parenthetical-aside",
+    message: "Parenthetical aside. Make it a sentence, or delete it",
+    pattern: new RegExp(String.raw`\((?:${words(ASIDE_OPENERS)})\b[^()\n]*\)?`, "gi"),
+  },
   {
     id: "what-comment",
     message: "Comment narrates what the code does. Say why, or delete it",
     pattern: new RegExp(String.raw`${COMMENT_START}(?:${words(WHAT_COMMENT_STARTS)})\b`, "gmi"),
     scope: "comments",
   },
+  {
+    id: "long-sentence",
+    message: "Long sentence. One idea per sentence",
+    check: longSentences,
+  },
+  {
+    id: "wall-of-text",
+    message: "Wall of text. Split the paragraph",
+    check: wallOfText,
+  },
+  {
+    id: "uniform-paragraphs",
+    message: "Consecutive paragraphs of the same length",
+    check: uniformParagraphs,
+    scope: "prose",
+  },
+  {
+    id: "uniform-sentences",
+    message: "Sentences of the same length. Vary the rhythm",
+    check: uniformSentences,
+  },
 ];

package/src/shape.js

@@ -0,0 +1,262 @@
+/**
+ * Shape rules look at paragraphs instead of single lines.
+ *
+ * A paragraph is a run of lines with no blank line between them.
+ * Comment markers, headings, tables, and fenced code do not count.
+ * A list item or a JSDoc tag starts a new paragraph.
+ */
+
+const MARKER = /^\s*(?:\/\/+|#+|\*+|\/\*+|<!--|--|;+|%+|"""|''')?\s*/;
+const TRAILER = /\s*(?:\*\/|-->|"""|''')\s*$/;
+const LIST_ITEM = /^(?:[-*+]|\d+[.)])\s+|^@\w+/;
+const SENTENCE_END = /[.!?]+(?:["')\]]+)?(?:\s+|$)/;
+
+export const WALL_WORDS = 120;
+export const WALL_SENTENCES = 7;
+export const LONG_SENTENCE_WORDS = 30;
+export const UNIFORM_PARAGRAPH_MIN_WORDS = 25;
+export const UNIFORM_PARAGRAPH_SPREAD = 1.25;
+export const UNIFORM_SENTENCE_MIN_COUNT = 4;
+export const UNIFORM_SENTENCE_MIN_WORDS = 8;
+export const UNIFORM_SENTENCE_VARIATION = 0.2;
+
+/**
+ * Groups segments into paragraphs.
+ *
+ * Pass inComments: true for comment segments, so that
+ * comment markers are removed before counting.
+ *
+ * Each paragraph has:
+ *   line, column → where it starts
+ *   words        → word count
+ *   sentences    → word count per sentence
+ *   preview      → its first few words
+ */
+export function paragraphs(segments, options) {
+  const result = group(segments, options);
+
+  for (let i = 0; i < result.length; i++) {
+    const paragraph = result[i];
+    const spans = paragraph.spans;
+    const sentences = [];
+    for (let s = 0; s < spans.length; s++) sentences.push(spans[s].words);
+    paragraph.sentences = sentences;
+    delete paragraph.spans;
+    delete paragraph.pieces;
+  }
+
+  return result;
+}
+
+/**
+ * Groups segments into paragraphs and keeps where each sentence starts.
+ *
+ * Each paragraph has the public fields, plus two internal ones:
+ *   spans  → { offset, words, preview } per sentence
+ *   pieces → { offset, line, column } per source line
+ *
+ * locate() turns an offset into the paragraph's text back into a position.
+ */
+function group(segments, { inComments = false } = {}) {
+  const result = [];
+  let current = null;
+  let inFence = false;
+  let previousLine = 0;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const text = inComments ? strip(segment.text) : segment.text.trim();
+
+    if (text.startsWith("```") || text.startsWith("~~~")) {
+      inFence = !inFence;
+      current = null;
+      continue;
+    }
+
+    const gap = segment.line !== previousLine + 1;
+    previousLine = segment.line;
+
+    if (inFence || text.length === 0 || text.startsWith("#") || text.startsWith("|")) {
+      current = null;
+      continue;
+    }
+
+    if (gap || current === null || LIST_ITEM.test(text)) {
+      current = { line: segment.line, column: segment.column, text: "", pieces: [] };
+      result.push(current);
+    }
+
+    if (current.text.length > 0) current.text += " ";
+    current.pieces.push({
+      offset: current.text.length,
+      line: segment.line,
+      column: segment.column + segment.text.indexOf(text),
+    });
+    current.text += text;
+  }
+
+  for (let i = 0; i < result.length; i++) {
+    const paragraph = result[i];
+    const spans = sentenceSpans(paragraph.text);
+    let words = 0;
+    for (let s = 0; s < spans.length; s++) words += spans[s].words;
+    paragraph.spans = spans;
+    paragraph.words = words;
+    paragraph.preview = preview(paragraph.text);
+    delete paragraph.text;
+  }
+
+  return result;
+}
+
+/**
+ * The line and column of an offset into a paragraph's text.
+ */
+function locate(paragraph, offset) {
+  const pieces = paragraph.pieces;
+  let piece = pieces[0];
+  for (let i = 1; i < pieces.length; i++) {
+    if (pieces[i].offset > offset) break;
+    piece = pieces[i];
+  }
+  return { line: piece.line, column: piece.column + (offset - piece.offset) };
+}
+
+export function wallOfText(segments, scope) {
+  const found = [];
+  const all = paragraphs(segments, { inComments: scope === "comments" });
+
+  for (let i = 0; i < all.length; i++) {
+    const paragraph = all[i];
+    if (paragraph.words <= WALL_WORDS && paragraph.sentences.length <= WALL_SENTENCES) continue;
+    found.push({
+      line: paragraph.line,
+      column: paragraph.column,
+      text: `${paragraph.words} words, ${paragraph.sentences.length} sentences: ${paragraph.preview}`,
+    });
+  }
+
+  return found;
+}
+
+export function longSentences(segments, scope) {
+  const found = [];
+  const all = group(segments, { inComments: scope === "comments" });
+
+  for (let i = 0; i < all.length; i++) {
+    const spans = all[i].spans;
+    for (let s = 0; s < spans.length; s++) {
+      if (spans[s].words <= LONG_SENTENCE_WORDS) continue;
+      const at = locate(all[i], spans[s].offset);
+      found.push({
+        line: at.line,
+        column: at.column,
+        text: `${spans[s].words} words: ${spans[s].preview}`,
+      });
+    }
+  }
+
+  return found;
+}
+
+export function uniformParagraphs(segments, scope) {
+  const found = [];
+  const all = paragraphs(segments, { inComments: scope === "comments" });
+  let start = 0;
+
+  while (start < all.length) {
+    let end = start;
+    let min = all[start].words;
+    let max = min;
+
+    while (end + 1 < all.length) {
+      const next = all[end + 1].words;
+      const lo = Math.min(min, next);
+      const hi = Math.max(max, next);
+      if (lo < UNIFORM_PARAGRAPH_MIN_WORDS || hi > lo * UNIFORM_PARAGRAPH_SPREAD) break;
+      min = lo;
+      max = hi;
+      end++;
+    }
+
+    if (end - start >= 2 && min >= UNIFORM_PARAGRAPH_MIN_WORDS) {
+      const counts = [];
+      for (let i = start; i <= end; i++) counts.push(all[i].words);
+      found.push({
+        line: all[start].line,
+        column: all[start].column,
+        text: `${counts.length} paragraphs of ${counts.join(", ")} words`,
+      });
+      start = end + 1;
+    } else {
+      start++;
+    }
+  }
+
+  return found;
+}
+
+export function uniformSentences(segments, scope) {
+  const found = [];
+  const all = paragraphs(segments, { inComments: scope === "comments" });
+
+  for (let i = 0; i < all.length; i++) {
+    const lengths = all[i].sentences;
+    if (lengths.length < UNIFORM_SENTENCE_MIN_COUNT) continue;
+
+    const mean = all[i].words / lengths.length;
+    if (mean < UNIFORM_SENTENCE_MIN_WORDS) continue;
+
+    let squares = 0;
+    for (let s = 0; s < lengths.length; s++) squares += (lengths[s] - mean) ** 2;
+    const variation = Math.sqrt(squares / lengths.length) / mean;
+    if (variation >= UNIFORM_SENTENCE_VARIATION) continue;
+
+    found.push({
+      line: all[i].line,
+      column: all[i].column,
+      text: `${lengths.length} sentences of ${lengths.join(", ")} words`,
+    });
+  }
+
+  return found;
+}
+
+function strip(text) {
+  return text.replace(TRAILER, "").replace(MARKER, "").trim();
+}
+
+function sentenceSpans(text) {
+  const spans = [];
+  const ends = new RegExp(SENTENCE_END.source, "g");
+  let start = 0;
+  let match;
+
+  while ((match = ends.exec(text)) !== null) {
+    push(start, text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  push(start, text.slice(start));
+  return spans;
+
+  function push(offset, part) {
+    const count = wordCount(part);
+    if (count > 0) spans.push({ offset, words: count, preview: preview(part) });
+  }
+}
+
+function wordCount(text) {
+  let count = 0;
+  let inWord = false;
+  for (let i = 0; i < text.length; i++) {
+    const space = text.charCodeAt(i) <= 32;
+    if (!space && !inWord) count++;
+    inWord = !space;
+  }
+  return count;
+}
+
+function preview(text) {
+  const words = text.split(/\s+/, 6);
+  return words.join(" ") + (words.length === 6 ? "..." : "");
+}