nollm 0.1.0 → 0.3.0

package/README.md

@@ -30,7 +30,7 @@ Add a script to `package.json`:
 }
 ```
 
-Requires Node 22.13 or newer.
+Requires Node 24 or newer.
 
 ## Usage
 
@@ -39,12 +39,24 @@ nollm [options] [paths...]
 ```
 
 With no paths, `nollm` checks the current directory.
-Paths can be files or directories.
+Paths can be files or directories, and they can be relative or absolute:
+
+```
+nollm docs/guide.md
+nollm /srv/site/docs/guide.md
+```
+
+A file under the current directory is reported by its relative path.
+A file outside it keeps its absolute path, so the report never points at it
+through a row of `..`.
+Ignore patterns from the config describe the project, so they apply under the
+current directory and leave paths outside it alone.
 
 | Option            | Effect                                                             |
 | ----------------- | ------------------------------------------------------------------ |
 | `--jobs <n>`      | Number of worker threads. Defaults to the CPU count.               |
 | `--config <path>` | Config file to use.                                                |
+| `--diff <ref>`    | Check only the lines this branch adds or changes since `<ref>`.    |
 | `--no-git`        | Do not ask git for the file list. Read `.gitignore` files instead. |
 | `--quiet`         | Print only the summary.                                            |
 | `--list-rules`    | Print every rule and exit.                                         |
@@ -68,6 +80,40 @@ src/index.js
 4 problems in 2 files (5 files checked, 0.07s)
 ```
 
+## Checking only a pull request
+
+A large codebase written before you added `nollm` has findings everywhere.
+`--diff` reports only the lines the current branch touches, so a pull request
+is judged on what it adds:
+
+```
+nollm --diff origin/main
+```
+
+The comparison starts at the merge base, the same range the pull request shows.
+Commits that landed on `origin/main` after you branched do not count as yours.
+Uncommitted edits and new files count, so the command works before you push.
+
+A finding is kept by the line it points at.
+A rule that reports at the top of a block, such as `wall-of-text`, stays quiet
+when the branch grows a paragraph further down.
+
+The diff is read in the repository the paths point at, not the one you happen
+to stand in, so `nollm --diff main /srv/site` works from anywhere.
+
+The base ref has to be in that clone. A shallow checkout, or one that fetched
+a single branch, does not have it, and `nollm` then names the command that
+fetches it.
+
+In GitHub Actions, fetch the base branch first:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: npx nollm --diff origin/${{ github.base_ref }}
+```
+
 ## What gets checked
 
 Prose files: markdown, text, reStructuredText, AsciiDoc, and files named `README`, `CHANGELOG`, `LICENSE`, and similar.
@@ -80,28 +126,28 @@ Files of other types, binary files, lockfiles, minified files, and files over 2
 
 ## Rules
 
-| 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                                     |
-| `diff-comment`        | Comments about the change: "no longer", "as discussed", "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                         |
+| 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.
 
@@ -175,6 +221,7 @@ const findings = check("README.md", "This is simply the best.");
 
 const summary = await lint({
   roots: ["src", "docs"],
+  diff: "origin/main",
   onResult({ file, findings }) {
     // runs once per file, as soon as it is done
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nollm",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "lint against LLMisms in your codebase",
   "keywords": [
     "comments",
@@ -37,7 +37,7 @@
     "tinypool": "^2.2.0"
   },
   "devDependencies": {
-    "@tsconfig/node-lts": "^24.0.1",
+    "@tsconfig/node24": "^24.0.1",
     "oxfmt": "^0.68.0",
     "oxlint": "^1.83.0",
     "publint": "^0.3.24",
@@ -45,7 +45,7 @@
     "vitest": "^5.0.1"
   },
   "engines": {
-    "node": ">= 22.5"
+    "node": ">= 24"
   },
   "scripts": {
     "format": "oxfmt",

package/src/cli.js

@@ -6,17 +6,22 @@ import { rules } from "./rules.js";
 const HELP = `Usage: nollm [options] [paths...]
 
 Checks files for LLMisms and prints each finding as soon as it is found.
-Files that git ignores are skipped.
+Paths may be relative or absolute. Files that git ignores are skipped.
 
 Options:
   --jobs, -j <n>     Number of worker threads (default: cpu count)
   --config <path>    Config file (default: nollm.config.js in the current directory)
+  --diff <ref>       Check only the lines this branch adds or changes since <ref>
   --no-git           Do not ask git for the file list. Read .gitignore files instead
   --quiet, -q        Print only the summary
   --list-rules       Print every rule and exit
   --version, -v      Print the version and exit
   --help, -h         Print this help and exit
 
+Examples:
+  nollm docs/guide.md            a path relative to the current directory
+  nollm /srv/site/docs/guide.md  an absolute path
+
 Exit code 1 when there are findings. Exit code 2 on a usage error.
 `;
 
@@ -33,6 +38,7 @@ export async function main(
       options: {
         jobs: { type: "string", short: "j" },
         config: { type: "string" },
+        diff: { type: "string" },
         git: { type: "boolean", default: true },
         quiet: { type: "boolean", short: "q", default: false },
         "list-rules": { type: "boolean", default: false },
@@ -61,7 +67,7 @@ export async function main(
   if (values["list-rules"]) {
     for (let i = 0; i < rules.length; i++) {
       const scope = (rules[i].scope ?? "text").padEnd(10);
-      stdout.write(`${rules[i].id.padEnd(20)} ${scope} ${rules[i].message}\n`);
+      stdout.write(`${rules[i].id.padEnd(24)} ${scope} ${rules[i].message}\n`);
     }
     return 0;
   }
@@ -85,6 +91,7 @@ export async function main(
       cwd,
       configPath: values.config,
       git: values.git,
+      diff: values.diff,
       jobs,
       onResult(result) {
         if (values.quiet || result.findings.length === 0) return;
@@ -116,29 +123,14 @@ export async function main(
  * 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 (const [ruleId, items] of Map.groupBy(findings, (finding) => finding.ruleId)) {
+    out += `  ${paint("yellow", ruleId)}  ${items[0].message}\n`;
 
-    for (let i = 0; i < group.items.length; i++) {
-      const item = group.items[i];
+    const width = Math.max(...items.map((item) => `${item.line}:${item.column}`.length));
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
       const where = `${item.line}:${item.column}`.padEnd(width);
       out += `    ${paint("dim", where)}  ${JSON.stringify(item.text)}\n`;
     }

package/src/config.js

@@ -62,7 +62,7 @@ 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) : rule);
   }
@@ -70,12 +70,12 @@ function resolveRules(overrides = {}, words = []) {
   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));
   }
 
   if (words.length > 0) {
-    const escaped = words.map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const escaped = words.map((word) => RegExp.escape(word));
     rules.push({
       id: "custom-word",
       message: "Banned word (nollm config)",
@@ -86,6 +86,18 @@ function resolveRules(overrides = {}, words = []) {
   return rules;
 }
 
+/**
+ * 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.

package/src/diff.js

@@ -0,0 +1,272 @@
+import { execFile } from "node:child_process";
+import { realpath, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+/**
+ * The checkout hint, for the one audience it helps.
+ *
+ * GitHub Actions checks out one branch at depth 1, which is what breaks
+ * --diff there. Anyone else gets the fetch line above it and no noise.
+ */
+function checkoutHint() {
+  if (process.env.GITHUB_ACTIONS !== "true") return [];
+  return ["In GitHub Actions, set fetch-depth: 0 on actions/checkout."];
+}
+
+/** Stands for every line of a file, used for files that are new in full. */
+export const ALL_LINES = true;
+
+/**
+ * The lines a branch adds or changes, per file.
+ *
+ * Returns a Map from path to a Set of line numbers in the new file, or to
+ * ALL_LINES when the whole file is new.
+ * Paths are relative to cwd, so they match what collectFiles returns.
+ *
+ * The comparison starts at the merge base of base and the working tree, so
+ * commits that land on base after the branch point stay out of the result.
+ * Uncommitted edits and files git does not track yet count as part of the
+ * branch, so the same call works before a push.
+ *
+ * Files with no added or changed lines are left out. So are deleted files.
+ */
+export async function changedLines(base, { cwd = process.cwd(), roots = ["."] } = {}) {
+  const changed = new Map();
+  for (const top of await repositories(roots, cwd)) {
+    for (const [file, lines] of await changedIn(base, top)) changed.set(file, lines);
+  }
+  return changed;
+}
+
+/**
+ * The repositories the roots live in, one entry each.
+ *
+ * A root names where to look, so that is where git is asked. Running nollm
+ * from one directory against another used to diff the directory it was run
+ * from, which is not the one holding the files.
+ */
+async function repositories(roots, cwd) {
+  const tops = new Set();
+  const seen = new Set();
+
+  for (let i = 0; i < roots.length; i++) {
+    const absolute = resolve(cwd, roots[i]);
+    const dir = (await isDirectory(absolute)) ? absolute : dirname(absolute);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+
+    await checkBase(dir);
+    tops.add(await real(await topLevel(dir)));
+  }
+  return tops;
+}
+
+/**
+ * The lines one repository changed, keyed by absolute path.
+ *
+ * Paths are absolute because the caller labels files against its own
+ * directory, which is not always this repository.
+ */
+async function changedIn(base, top) {
+  await checkRef(base, top);
+
+  const args = [
+    "diff",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-renames",
+    "--no-prefix",
+    "--unified=0",
+    "--diff-filter=ACM",
+    "--merge-base",
+    base,
+  ];
+
+  let stdout;
+  try {
+    ({ stdout } = await run("git", args, { cwd: top, maxBuffer: 256 * 1024 * 1024 }));
+  } catch (error) {
+    const reason = firstLine(error.stderr) ?? error.message;
+    if (reason.includes("no merge base")) throw await noMergeBase(base, top);
+    throw new Error(`Could not diff against "${base}" in ${top}: ${reason}`);
+  }
+
+  const changed = new Map();
+  for (const [file, lines] of parse(stdout)) changed.set(resolve(top, file), lines);
+  for (const file of await untracked(top)) changed.set(resolve(top, file), ALL_LINES);
+  return changed;
+}
+
+async function topLevel(dir) {
+  return (await tryGit(["rev-parse", "--show-toplevel"], dir))?.trim() ?? dir;
+}
+
+async function isDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** The path with its symlinks followed, so it matches how files are labelled. */
+async function real(path) {
+  try {
+    return await realpath(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Says what is wrong with a base ref before git says it less clearly.
+ *
+ * A checkout that fetched one branch, or fetched to a shallow depth, is the
+ * usual reason a ref is missing. CI does both by default, so the ref a pull
+ * request is against is often the one that is not there.
+ */
+async function checkBase(dir) {
+  if ((await tryGit(["rev-parse", "--is-inside-work-tree"], dir)) === null) {
+    throw new Error(`Not a git repository, so --diff has nothing to compare: ${dir}`);
+  }
+}
+
+async function checkRef(base, dir) {
+  if ((await tryGit(["rev-parse", "--verify", "-q", `${base}^{commit}`], dir)) !== null) return;
+
+  throw new Error(
+    [
+      `Could not find "${base}" in ${dir}.`,
+      `Fetch it with: git -C ${dir} fetch ${await fetchArgs(base, dir)}`,
+      ...checkoutHint(),
+    ].join("\n"),
+  );
+}
+
+/**
+ * The error for a ref that exists but shares no history with the branch.
+ */
+async function noMergeBase(base, dir) {
+  const shallow = (await tryGit(["rev-parse", "--is-shallow-repository"], dir))?.trim() === "true";
+  if (!shallow) {
+    return new Error(`"${base}" and the branch in ${dir} share no history, so there is no diff.`);
+  }
+  return new Error(
+    [
+      `No merge base with "${base}" in ${dir}. This clone is shallow, so the shared commit is missing.`,
+      `Deepen it with: git -C ${dir} fetch --unshallow`,
+      ...checkoutHint(),
+    ].join("\n"),
+  );
+}
+
+/**
+ * How to fetch a missing ref. "origin/develop" needs "origin develop".
+ *
+ * A branch name may hold a slash of its own, so the first part counts as a
+ * remote only when the repository lists it as one. A repository with no
+ * remotes gives nothing to check against, so the usual reading wins.
+ */
+async function fetchArgs(base, cwd) {
+  const cut = base.indexOf("/");
+  if (cut <= 0) return `origin ${base}`;
+
+  const listed = (await tryGit(["remote"], cwd))?.trim();
+  const remotes = listed ? listed.split("\n") : [];
+  if (remotes.length === 0 || remotes.includes(base.slice(0, cut))) {
+    return `${base.slice(0, cut)} ${base.slice(cut + 1)}`;
+  }
+  return `origin ${base}`;
+}
+
+/** Runs git and returns its output, or null when it fails. */
+async function tryGit(args, cwd) {
+  try {
+    const { stdout } = await run("git", args, { cwd });
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Files git does not track yet.
+ *
+ * collectFiles lists these, so a file a branch adds but has not committed
+ * still counts as part of the diff.
+ */
+async function untracked(cwd) {
+  let stdout;
+  try {
+    ({ stdout } = await run("git", ["ls-files", "-z", "--others", "--exclude-standard"], {
+      cwd,
+      maxBuffer: 256 * 1024 * 1024,
+    }));
+  } catch {
+    return [];
+  }
+
+  const files = [];
+  const parts = stdout.split("\0");
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i].length > 0) files.push(parts[i]);
+  }
+  return files;
+}
+
+/**
+ * Reads a unified diff produced with --unified=0 and --no-prefix.
+ *
+ * Every file starts with a "diff --git" line, so that line marks where the
+ * next "+++" is a header and not a line of added content that starts with "++".
+ */
+function parse(patch) {
+  const changed = new Map();
+  const lines = patch.split("\n");
+
+  let file = null;
+  let expectHeader = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (line.startsWith("diff --git ")) {
+      file = null;
+      expectHeader = true;
+      continue;
+    }
+
+    if (expectHeader && line.startsWith("+++ ")) {
+      const path = line.slice(4);
+      expectHeader = false;
+      if (path === "/dev/null") continue;
+      file = path;
+      if (!changed.has(file)) changed.set(file, new Set());
+      continue;
+    }
+
+    if (file === null || !line.startsWith("@@")) continue;
+
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!hunk) continue;
+
+    const start = Number(hunk[1]);
+    const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+    const set = changed.get(file);
+    for (let n = 0; n < count; n++) set.add(start + n);
+  }
+
+  for (const [path, set] of changed) {
+    if (set.size === 0) changed.delete(path);
+  }
+  return changed;
+}
+
+function firstLine(text) {
+  if (!text) return null;
+  const trimmed = text.trim();
+  return trimmed.length > 0 ? trimmed.split("\n")[0] : null;
+}

package/src/files.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
+import { readFileSync } from "node:fs";
+import { glob, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import ignore from "ignore";
 
@@ -8,27 +9,58 @@ const run = promisify(execFile);
 
 const ALWAYS_SKIPPED = new Set([".git", "node_modules"]);
 
+/**
+ * glob leaves dotfiles out unless a pattern asks for them, and the tool checks
+ * files such as .gitignore and everything under .github.
+ */
+const EVERYTHING = ["**/*", "**/.*", "**/.*/**"];
+
 /**
  * Lists the files to check.
  *
- * Paths come back relative to cwd, with forward slashes.
+ * Roots may be relative or absolute.
+ * A file under cwd comes back relative to cwd, with forward slashes.
+ * A file outside cwd keeps its absolute path, so a report never has to point
+ * at it through a row of "..".
+ *
  * Files that git ignores are left out.
  *
  * Inside a git work tree the list comes from git itself.
  * Elsewhere, or with git: false, the tool reads .gitignore files while it walks.
+ * git only knows about its own work tree, so roots outside cwd are always
+ * walked.
  *
- * The ignore option takes patterns in .gitignore syntax.
+ * The ignore option takes patterns in .gitignore syntax. They describe the
+ * project, so they apply under cwd and leave paths outside cwd alone.
+ *
+ * Roots and cwd are compared after their symlinks are followed. On macOS a
+ * temp directory is reached through /var and lives in /private/var, and
+ * without this a path under cwd would look like a path outside it.
  */
 export async function collectFiles(
   roots,
   { cwd = process.cwd(), git = true, ignore: patterns = [] } = {},
 ) {
-  const files = git ? await fromGit(roots, cwd) : null;
-  const list = files ?? (await fromWalk(roots, cwd));
+  const base = await real(cwd);
+  const inside = [];
+  const outside = [];
+  for (let i = 0; i < roots.length; i++) {
+    const absolute = await real(resolve(cwd, roots[i]));
+    if (isInside(base, absolute)) inside.push(absolute);
+    else outside.push(absolute);
+  }
+
+  let list = [];
+  if (inside.length > 0) {
+    const tracked = git ? await fromGit(inside, cwd) : null;
+    list = tracked ?? (await fromWalk(inside, base));
+  }
+  if (outside.length > 0) list = list.concat(await fromWalk(outside, base));
+
   if (patterns.length === 0) return list;
 
   const matcher = ignore().add(patterns);
-  return list.filter((file) => !matcher.ignores(file));
+  return list.filter((file) => isAbsolute(file) || !matcher.ignores(file));
 }
 
 async function fromGit(roots, cwd) {
@@ -58,46 +90,64 @@ async function fromGit(roots, cwd) {
   return files;
 }
 
-async function fromWalk(roots, cwd) {
+async function fromWalk(roots, base) {
   const files = [];
   for (let i = 0; i < roots.length; i++) {
-    const absolute = resolve(cwd, roots[i]);
-    const info = await stat(absolute);
+    const root = roots[i];
+    const info = await stat(root);
     if (info.isFile()) {
-      files.push(toPosix(relative(cwd, absolute)));
+      files.push(label(base, root));
       continue;
     }
-    await walk(absolute, cwd, [], files);
+
+    const entries = glob(EVERYTHING, { cwd: root, withFileTypes: true, exclude: skips(root) });
+    for await (const entry of entries) {
+      if (entry.isFile()) files.push(label(base, join(entry.parentPath, entry.name)));
+    }
   }
   return files;
 }
 
-async function walk(dir, cwd, filters, files) {
-  const local = await readIgnore(dir);
-  const active = local ? filters.concat([local]) : filters;
-  const entries = await readdir(dir, { withFileTypes: true });
+/**
+ * Tells glob which entries to leave out. Saying yes to a directory prunes it,
+ * so an ignored tree is never opened.
+ *
+ * A .gitignore applies to the directory that holds it and to everything below.
+ * So each entry is matched against the chain of files from the root down to
+ * its own directory. Chains are built once per directory and kept.
+ *
+ * glob asks this question synchronously, so the reads are synchronous. It is
+ * one small file per directory, which is what the walk read before.
+ */
+function skips(root) {
+  const chains = new Map();
 
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    if (ALWAYS_SKIPPED.has(entry.name)) continue;
+  const chainFor = (dir) => {
+    const known = chains.get(dir);
+    if (known) return known;
+
+    const parent = dir === root || dirname(dir) === dir ? [] : chainFor(dirname(dir));
+    const local = readIgnore(dir);
+    const chain = local ? parent.concat([local]) : parent;
+    chains.set(dir, chain);
+    return chain;
+  };
+
+  return (entry) => {
+    if (ALWAYS_SKIPPED.has(entry.name)) return true;
 
-    const absolute = join(dir, entry.name);
     const isDir = entry.isDirectory();
-    if (!isDir && !entry.isFile()) continue;
-    if (isIgnored(absolute, isDir, active)) continue;
+    if (!isDir && !entry.isFile()) return true;
 
-    if (isDir) {
-      await walk(absolute, cwd, active, files);
-    } else {
-      files.push(toPosix(relative(cwd, absolute)));
-    }
-  }
+    const absolute = join(entry.parentPath, entry.name);
+    return isIgnored(absolute, isDir, chainFor(entry.parentPath));
+  };
 }
 
-async function readIgnore(dir) {
+function readIgnore(dir) {
   let content;
   try {
-    content = await readFile(join(dir, ".gitignore"), "utf8");
+    content = readFileSync(join(dir, ".gitignore"), "utf8");
   } catch {
     return null;
   }
@@ -113,6 +163,28 @@ function isIgnored(absolute, isDir, filters) {
   return false;
 }
 
+/**
+ * How a file is named in a report: relative to the base directory when it sits
+ * under it, absolute when it does not.
+ */
+function label(base, absolute) {
+  return toPosix(isInside(base, absolute) ? relative(base, absolute) : absolute);
+}
+
+function isInside(base, absolute) {
+  const rel = relative(base, absolute);
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/** The path with its symlinks followed, or the path itself if it is missing. */
+async function real(path) {
+  try {
+    return await realpath(path);
+  } catch {
+    return path;
+  }
+}
+
 function toPosix(path) {
   return sep === "/" ? path : path.split(sep).join("/");
 }

package/src/index.d.ts

@@ -2,6 +2,8 @@ export type Scope = "prose" | "comments" | "text" | "everywhere";
 
 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;
@@ -15,6 +17,8 @@ export interface ShapeFinding {
 
 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;
@@ -82,6 +86,8 @@ export interface LintOptions {
   cwd?: string;
   configPath?: string;
   git?: boolean;
+  /** A git ref. Only lines added or changed since the merge base are reported. */
+  diff?: string;
   jobs?: number;
   onResult?: (result: FileResult) => void;
 }
@@ -93,6 +99,11 @@ export function check(filePath: string, source: string, rules?: Rule[]): Finding
 export function classify(
   filePath: string,
 ): { kind: "prose" } | { kind: "code"; language: Language } | null;
+export const ALL_LINES: true;
+export function changedLines(
+  base: string,
+  options?: { cwd?: string; roots?: string[] },
+): Promise<Map<string, Set<number> | typeof ALL_LINES>>;
 export function collectFiles(
   roots: string[],
   options?: { cwd?: string; git?: boolean; ignore?: string[] },

package/src/index.js

@@ -1,4 +1,5 @@
 export { check } from "./check.js";
+export { ALL_LINES, changedLines } from "./diff.js";
 export { classify } from "./languages.js";
 export { collectFiles } from "./files.js";
 export { extractComments, extractLines } from "./comments.js";

package/src/lint.js

@@ -1,11 +1,16 @@
+import { realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Tinypool } from "tinypool";
 import { findConfig, loadConfig } from "./config.js";
+import { ALL_LINES, changedLines } from "./diff.js";
 import { collectFiles } from "./files.js";
 
 /**
  * Checks every file under the given roots.
  *
+ * With diff set to a git ref, only the files that changed since the merge base
+ * are read, and only findings on added or changed lines are reported.
+ *
  * onResult runs once per file, as soon as that file is done.
  * The returned promise resolves after the last file.
  */
@@ -14,38 +19,70 @@ export async function lint({
   cwd = process.cwd(),
   configPath,
   git = true,
+  diff,
   jobs,
   onResult = () => {},
 } = {}) {
   const resolvedConfig = configPath ? resolve(cwd, configPath) : await findConfig(cwd);
   const config = await loadConfig(resolvedConfig);
-  const files = await collectFiles(roots, { cwd, git, ignore: config.ignore });
+  let files = await collectFiles(roots, { cwd, git, ignore: config.ignore });
+
+  // collectFiles labels files against the real cwd, so absolute paths built
+  // from those labels line up with the ones the diff reports.
+  let changed = null;
+  let base = cwd;
+  if (diff) {
+    changed = await changedLines(diff, { cwd, roots });
+    base = await realCwd(cwd);
+    files = files.filter((file) => changed.has(resolve(base, file)));
+  }
 
-  const pool = new Tinypool({
-    filename: new URL("./worker.js", import.meta.url).href,
-    workerData: { configPath: resolvedConfig, cwd },
-    maxThreads: jobs,
-  });
+  // The pool is torn down when this function ends, however it ends.
+  await using pool = Object.assign(
+    new Tinypool({
+      filename: new URL("./worker.js", import.meta.url).href,
+      workerData: { configPath: resolvedConfig, cwd },
+      maxThreads: jobs,
+    }),
+    { [Symbol.asyncDispose]: () => pool.destroy() },
+  );
 
   const summary = { files: files.length, checked: 0, findings: 0, filesWithFindings: 0 };
 
-  try {
-    const pending = [];
-    for (let i = 0; i < files.length; i++) {
-      const done = pool.run(files[i]).then((result) => {
-        if (!result.skipped) summary.checked++;
-        if (result.findings.length > 0) {
-          summary.findings += result.findings.length;
-          summary.filesWithFindings++;
-        }
-        onResult(result);
-      });
-      pending.push(done);
-    }
-    await Promise.all(pending);
-  } finally {
-    await pool.destroy();
+  const pending = [];
+  for (let i = 0; i < files.length; i++) {
+    const done = pool.run(files[i]).then((result) => {
+      if (changed) result = onlyChanged(result, changed.get(resolve(base, result.file)));
+      if (!result.skipped) summary.checked++;
+      if (result.findings.length > 0) {
+        summary.findings += result.findings.length;
+        summary.filesWithFindings++;
+      }
+      onResult(result);
+    });
+    pending.push(done);
   }
+  await Promise.all(pending);
 
   return summary;
 }
+
+async function realCwd(cwd) {
+  try {
+    return await realpath(cwd);
+  } catch {
+    return cwd;
+  }
+}
+
+/**
+ * Keeps the findings that sit on a line the branch adds or changes.
+ *
+ * A finding is placed by the line it points at. A rule that reports at the top
+ * of a paragraph, such as wall-of-text, is therefore quiet when the branch
+ * extends that paragraph further down.
+ */
+function onlyChanged(result, lines) {
+  if (lines === ALL_LINES || result.findings.length === 0) return result;
+  return { ...result, findings: result.findings.filter((finding) => lines.has(finding.line)) };
+}

package/src/rules.js

@@ -131,17 +131,55 @@ const AI_DISCLOSURES = [
   "my training data",
 ];
 
-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",
@@ -164,10 +202,176 @@ 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",
 ];
 
-// Diff talk only when it opens a sentence. "used previously" is fine.
-const DIFF_OPENERS = ["previously", "formerly"];
+// PR talk only when it opens a sentence. "used previously" is fine.
+const PR_OPENERS = ["previously", "formerly", "originally"];
 
 const DRAMATIC_VERBS = [
   "blow up",
@@ -323,10 +527,11 @@ export const rules = [
     scope: "prose",
   },
   {
-    id: "diff-comment",
-    message: "Comment describes the change, not the code. Put it in the commit message",
+    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(DIFF_TALK)})\b|${SENTENCE_START}(?:${words(DIFF_OPENERS)})\b`,
+      String.raw`\b(?:${words(PR_TALK)})\b|${SENTENCE_START}(?:${words(PR_OPENERS)})\b`,
       "gmi",
     ),
     scope: "comments",