nollm 0.2.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.
@@ -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.2.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 },
@@ -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

@@ -75,7 +75,7 @@ function resolveRules(overrides = {}, words = []) {
   }
 
   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)",

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

@@ -86,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;
 }
@@ -97,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)) };
+}