@d3lm/lint-preset 1.5.1 → 1.5.2

package/README.md

@@ -245,7 +245,7 @@ comments agent                     # hand suspicious comments to an agent, then
 comments check --cwd ../other-app  # run as if started in another project
 ```
 
-Without targets, only comments in uncommitted changes and untracked files are checked. `--staged` limits that to staged changes, `--base main` checks everything since the merge base with `main`, and `--repo` checks every file. Targets can be files, directories, `file:line`, or `file:start-end`. A comment that contains `comments-ignore` is skipped. A file with a syntax error is skipped as a whole and named in a warning, because the parser stops at the error and never sees the comments after it. JSX is read in `.js` files too.
+Without targets, only comments in uncommitted changes and untracked files are checked. `--base main` checks everything since the merge base with `main`, and `--repo` checks every file. `--whole-files` checks every comment in the changed files instead of only the comments on changed lines. Targets can be files, directories, `file:line`, or `file:start-end`. A comment that contains `comments-ignore` is skipped. A file with a syntax error is skipped as a whole and named in a warning, because the parser stops at the error and never sees the comments after it. JSX is read in `.js` files too.
 
 With `--json`, each paragraph of a comment comes with its issues and a `suggestion` that holds the exact rewrapped lines. Code blocks, `@example`, tables, drawings, directives, and other [text kept as written](#text-kept-as-written) have no suggestion.
 
@@ -294,7 +294,7 @@ A comment with an issue in a part that is kept is handed to the agent, which can
  */
 ```
 
-The separate `singleLineWidth` allowance is capped by `maxWidth`. Code and documented layout regions retain their exemptions. An indivisible token in measured prose that exceeds `maxWidth` is reported as overflow; the wrapper preserves it, so resolving that case requires changing the maximum or the comment manually. The legacy `tolerance` option sets a maximum of `width + tolerance` when `maxWidth` is omitted; an explicit `maxWidth` takes precedence. Direct `analyzeSource` callers can omit `maxWidth` to retain the legacy width/tolerance behavior.
+The separate `singleLineWidth` allowance is capped by `maxWidth`. Code and documented layout regions retain their exemptions. An indivisible token in measured prose that exceeds `maxWidth` is reported as overflow; the wrapper preserves it, so resolving that case requires changing the maximum or the comment manually. `tolerance` lets prose lines go up to that many columns past `width` when that saves a line in a paragraph of three or more lines, and it never goes past `maxWidth`. It defaults to 0. When `maxWidth` is omitted, `tolerance` also sets a legacy maximum of `width + tolerance`. Direct `analyzeSource` callers can omit `maxWidth` to retain the legacy width/tolerance behavior.
 
 Like prettier, `comments` looks for a config file in the current directory and its parents, up to the repository root. The config can be a `comments.config.{ts,mts,js,mjs,cjs}`, `.commentsrc`, or `.commentsrc.json` file, or a `comments` key in `package.json`. All options are optional.
 
@@ -306,6 +306,8 @@ export default defineConfig({
   // defaults to prettier's printWidth, or 80
   width: 100,
   maxWidth: 120,
+  // prose lines may go this many columns past `width` when that saves a line
+  tolerance: 0,
   // a comment that is one paragraph stays on one line up to this length, and wraps to `width` beyond it
   singleLineWidth: 120,
   avoidSentenceOrphans: true,

package/dist/bin/comments.js

@@ -24,7 +24,7 @@ When rules pull in different directions, the earlier one wins.
 
 ## Layout
 
-- After you finish, the tool rewraps prose paragraphs, list items, and JSDoc tag descriptions. The width is a preferred target. A parenthetical may extend a line up to the configured maximum so it stays together. In longer paragraphs, balanced lines take priority over keeping every parenthetical on one line. The tool also avoids short last lines where possible. Leave these line breaks to the tool, except for the sentence-orphan case below.
+- After you finish, the tool rewraps prose paragraphs, list items, and JSDoc tag descriptions. The width is a preferred target. A parenthetical may extend a line up to the configured maximum so it stays together, and lines may go up to the configured tolerance past the width when that saves a line. In longer paragraphs, balanced lines take priority over keeping every parenthetical on one line. The tool also avoids short last lines where possible. Leave these line breaks to the tool, except for the sentence-orphan case below.
 - Don't end a line with the first word of a new sentence, clause, or parenthetical, like \`This\` after a period, \`the\` after a comma, or \`(the\`. Move it to the next line instead.
 - In a paragraph of two lines, the first line ends with a sentence whenever the rest fits on the second line and is no longer than the first. Don't end it with the start of the next sentence, like \`A wrap\` in \`...lay out differently. A wrap\`. Move those words to the second line instead.
 - A comment whose whole text is one paragraph stays on a single line when that line fits a separate, larger single-line width, even past the width. Only a longer comment wraps to the width.
@@ -825,6 +825,19 @@ function layoutLines(tokens, firstLimit, restLimit, options) {
       return lines;
     }
   }
+  if (options.tolerance > 0 && greedy.length > 2) {
+    const fewer = balanceTokens(
+      tokens,
+      firstLimit + options.tolerance,
+      restLimit + options.tolerance,
+      greedy.length - 1,
+      options,
+      restLimit
+    );
+    if (fewer && !hasStep(fewer, restLimit - firstLimit)) {
+      return fewer;
+    }
+  }
   const balanced = balanceTokens(tokens, firstLimit, restLimit, greedy.length, options);
   if (balanced) {
     return balanced;
@@ -2167,23 +2180,12 @@ function snapshotChanges(root) {
 var DIFF_FLAGS = ["diff", "-U0", "--no-color", "--no-ext-diff", "--no-renames", "--src-prefix=a/", "--dst-prefix=b/"];
 function getChangedLines(root, scope = {}) {
   if (!hasHead(root)) {
-    const files = scope.staged ? splitPaths(gitOrThrow(root, ["diff", "-z", "--cached", "--name-only", "--diff-filter=d"])) : listFiles2(root);
-    return new Map(files.map((file) => [file, "all"]));
-  }
-  let args;
-  if (scope.staged) {
-    args = [...DIFF_FLAGS, "--cached", "HEAD"];
-  } else if (scope.base) {
-    const mergeBase = gitOrThrow(root, ["merge-base", scope.base, "HEAD"]).trim();
-    args = [...DIFF_FLAGS, mergeBase];
-  } else {
-    args = [...DIFF_FLAGS, "HEAD"];
+    return new Map(listFiles2(root).map((file) => [file, "all"]));
   }
-  const changed = parseUnifiedDiff(gitOrThrow(root, args));
-  if (!scope.staged) {
-    for (const file of listUntrackedFiles(root)) {
-      changed.set(file, "all");
-    }
+  const target = scope.base ? gitOrThrow(root, ["merge-base", scope.base, "HEAD"]).trim() : "HEAD";
+  const changed = parseUnifiedDiff(gitOrThrow(root, [...DIFF_FLAGS, target]));
+  for (const file of listUntrackedFiles(root)) {
+    changed.set(file, "all");
   }
   return changed;
 }
@@ -2298,7 +2300,7 @@ var Project = class {
       throw new Error("comments: not a git repository, so pass files or directories explicitly");
     }
     for (const [file, lines] of getChangedLines(this.root, scope)) {
-      add(path4.join(this.root, file), lines);
+      add(path4.join(this.root, file), scope.wholeFiles ? "all" : lines);
     }
     return files;
   }
@@ -2809,8 +2811,8 @@ Targets are files, directories, file:line, or file:start-end. Without targets, o
 overlapping uncommitted changes (and untracked files) are considered.
 
 Options:
-  --staged          Only consider staged changes
   --base <ref>      Consider changes since the merge base with <ref>
+  --whole-files     Consider every comment in the changed files, not only comments on changed lines
   --repo            Consider every file in the repository
   --suspicious      Only comments with layout issues (overflow, early line ends, last lines of one or two words)
                     or hints (possible orphans, em-dashes, banners, ...). For agent and hook (the default), only
@@ -2830,7 +2832,7 @@ Config overrides (take precedence over the config file):
   --width <n>             Preferred comment line length
   --max-width <n>         Hard limit for prose (default: 120, never below width)
   --single-line-width <n> Longest line a one-paragraph comment may stay on (default: 120)
-  --tolerance <n>         Legacy hard limit of width + n, unless max-width is set
+  --tolerance <n>         Columns prose may go past width to save a line, within max-width (default: 0)
   --[no-]orphans          Keep a sentence's first word off the end of a line, and end the first of two lines
                           with a sentence when the second is no longer than the first (default: on)
   --[no-]style            Look for possible semicolons, em-dashes, dashes, label colons, emphasis, and banners
@@ -2856,8 +2858,8 @@ var OPTIONS = {
   "max-files": { type: "string" },
   "max-agents": { type: "string" },
   instructions: { type: "string" },
-  staged: { type: "boolean" },
   base: { type: "string" },
+  "whole-files": { type: "boolean" },
   repo: { type: "boolean" },
   suspicious: { type: "boolean" },
   all: { type: "boolean" },
@@ -2944,7 +2946,7 @@ async function createProject(cwd, values) {
   return { project, configPath: loaded.filepath };
 }
 function scopeFrom(positionals, values) {
-  return { targets: positionals, staged: values.staged, base: values.base, repo: values.repo };
+  return { targets: positionals, base: values.base, wholeFiles: values["whole-files"], repo: values.repo };
 }
 function selectFrom(values, project) {
   if (values.all) {
@@ -3005,9 +3007,8 @@ function commentsOf(analyses) {
 function hintEmptyScope(analyses, scope) {
   const isDefaultScope = (scope.targets ?? []).length === 0 && !scope.repo && !scope.base;
   if (analyses.length === 0 && isDefaultScope) {
-    const changes = scope.staged ? "staged changes" : "uncommitted changes";
     log2(
-      `comments: no ${changes} in JavaScript or TypeScript files. Pass --repo, --base <ref>, or files to widen the scope.`
+      "comments: no uncommitted changes in JavaScript or TypeScript files. Pass --repo, --base <ref>, or files to widen the scope."
     );
   }
 }