nollm 0.2.0 → 0.4.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.
@@ -90,7 +136,7 @@ Files of other types, binary files, lockfiles, minified files, and files over 2
 | `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"                                                                       |
+| `contrast-cliche`         | "not just X, but Y", "it's not X, it's Y", and "X, not Y: the rest"                                                |
 | `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," |
@@ -98,6 +144,7 @@ Files of other types, binary files, lockfiles, minified files, and files over 2
 | `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)`                                                                         |
+| `mid-phrase-break`        | A line that stops mid phrase, on a word such as the, of, or that                                                   |
 | `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                                                         |
@@ -175,6 +222,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.4.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,275 @@
+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 branch is compared against is often the one that is missing.
+ */
+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,59 @@ 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.
+ * 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,
+ * so 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 +91,65 @@ 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 +165,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)) };
+}

package/src/rules.js

@@ -1,4 +1,10 @@
-import { longSentences, uniformParagraphs, uniformSentences, wallOfText } from "./shape.js";
+import {
+  longSentences,
+  midPhraseBreaks,
+  uniformParagraphs,
+  uniformSentences,
+  wallOfText,
+} from "./shape.js";
 
 /**
  * A rule is a regular expression plus a message,
@@ -28,6 +34,23 @@ function escape(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Three shapes of one move: naming the thing it is not.
+ *
+ *   not just X, but Y
+ *   it is not X, it is Y
+ *   X, not Y: the rest
+ *
+ * The third wants a label colon, so "a, not https://b" stays out. It also
+ * stays on one line, so a wrapped block comment cannot join two sentences
+ * into a match.
+ */
+const CONTRAST_CLICHES = [
+  String.raw`\bnot (?:just|only|merely|simply) [^.\n]{1,60}?,? but(?: also)?\b`,
+  String.raw`\bit'?s not (?:just |about )?[^.\n]{1,40}?[,;] it'?s\b`,
+  String.raw`[^\s,:][^,:\n]{0,29},[ \t]+not[ \t]+[^,:\n]{1,30}:(?=\s|$)`,
+];
+
 const BANNED_WORDS = [
   "genuinely",
   "fails loudly",
@@ -508,9 +531,8 @@ export const rules = [
   },
   {
     id: "contrast-cliche",
-    message: "Contrast cliche (not just X, but Y)",
-    pattern:
-      /\b(?:not (?:just|only|merely|simply) [^.\n]{1,60}?,? but(?: also)?\b|it'?s not (?:just |about )?[^.\n]{1,40}?[,;] it'?s\b)/gi,
+    message: "Contrast cliche. State the thing directly",
+    pattern: new RegExp(CONTRAST_CLICHES.join("|"), "gi"),
   },
   {
     id: "rhetorical-question",
@@ -562,6 +584,11 @@ export const rules = [
     pattern: new RegExp(String.raw`${COMMENT_START}(?:${words(WHAT_COMMENT_STARTS)})\b`, "gmi"),
     scope: "comments",
   },
+  {
+    id: "mid-phrase-break",
+    message: "Line break in the middle of a phrase. Break where there is a pause",
+    check: midPhraseBreaks,
+  },
   {
     id: "long-sentence",
     message: "Long sentence. One idea per sentence",

package/src/shape.js

@@ -11,6 +11,86 @@ const TRAILER = /\s*(?:\*\/|-->|"""|''')\s*$/;
 const LIST_ITEM = /^(?:[-*+]|\d+[.)])\s+|^@\w+/;
 const SENTENCE_END = /[.!?]+(?:["')\]]+)?(?:\s+|$)/;
 
+/**
+ * Words that cannot end a thought.
+ * They point at whatever comes next,
+ * so a line that stops on one stopped in the middle of a phrase.
+ *
+ * Words that can stand at the end of a clause stay out, however often they
+ * also appear mid phrase. "Yes it can" and "give it to her" are ordinary,
+ * so can and her are not here.
+ */
+export const DANGLING_WORDS = [
+  "a",
+  "an",
+  "the",
+  "of",
+  "to",
+  "in",
+  "on",
+  "at",
+  "by",
+  "for",
+  "with",
+  "from",
+  "into",
+  "onto",
+  "upon",
+  "over",
+  "under",
+  "about",
+  "across",
+  "after",
+  "before",
+  "between",
+  "during",
+  "through",
+  "toward",
+  "towards",
+  "within",
+  "without",
+  "against",
+  "among",
+  "around",
+  "beyond",
+  "per",
+  "via",
+  "and",
+  "or",
+  "but",
+  "nor",
+  "that",
+  "which",
+  "who",
+  "whom",
+  "whose",
+  "if",
+  "when",
+  "while",
+  "because",
+  "although",
+  "though",
+  "unless",
+  "until",
+  "since",
+  "whether",
+  "is",
+  "are",
+  "was",
+  "were",
+  "has",
+  "have",
+  "had",
+  "its",
+  "their",
+  "your",
+  "our",
+  "my",
+  "every",
+];
+
+const DANGLING_END = new RegExp(String.raw`\b(${DANGLING_WORDS.join("|")})\s*$`, "i");
+
 export const WALL_WORDS = 120;
 export const WALL_SENTENCES = 7;
 export const LONG_SENTENCE_WORDS = 30;
@@ -23,8 +103,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.
+ * Pass inComments: true for comment segments,
+ * so comment markers are removed before counting.
  *
  * Each paragraph has:
  *   line, column → where it starts
@@ -260,3 +340,56 @@ function preview(text) {
   const words = text.split(/\s+/, 6);
   return words.join(" ") + (words.length === 6 ? "..." : "");
 }
+
+/**
+ * Line breaks that land in the middle of a phrase.
+ *
+ * A break reads as a pause, so the line before it should be able to stop.
+ * A line ending on a word that points at the next one cannot.
+ *
+ * Only a break the next line carries on counts.
+ * A blank line, a heading, a table, a fence, or a new list item
+ * each end the thought by themselves, so the line before one is skipped.
+ */
+export function midPhraseBreaks(segments, scope) {
+  const inComments = scope === "comments";
+  const found = [];
+  let fence = false;
+  let previous = null;
+
+  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("~~~")) {
+      fence = !fence;
+      previous = null;
+      continue;
+    }
+
+    if (fence || text.length === 0 || text.startsWith("#") || text.startsWith("|")) {
+      previous = null;
+      continue;
+    }
+
+    const carriesOn = previous !== null && segment.line === previous.line + 1;
+    if (carriesOn && !LIST_ITEM.test(text)) {
+      const match = DANGLING_END.exec(previous.text);
+      if (match) {
+        found.push({
+          line: previous.line,
+          column: previous.column + match.index,
+          text: match[1],
+        });
+      }
+    }
+
+    previous = {
+      text,
+      line: segment.line,
+      column: segment.column + segment.text.indexOf(text),
+    };
+  }
+
+  return found;
+}