@d3lm/lint-preset 1.5.1 → 1.5.4

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.
 
@@ -261,6 +261,7 @@ Verdicts are layout issues that can be measured without reading the prose. They
 Hints come from heuristics and can be false positives, because only the meaning of the prose shows whether the rule applies. A hint only sends a comment to the agent, which decides whether to change it. `check` only prints comments with verdicts, so a passing check stays quiet apart from its summary, even when hints remain after review. Use `list --suspicious` to inspect hints, which are marked with `(hint)` and never fail a check:
 
 - `orphan` means a line ends with the first word of a sentence, or the first of two lines ends with the start of a sentence that fits on the second without making it longer than the first
+- `split-parenthetical` means a line ends inside a parenthetical that the suggested rewrap keeps on one line within `maxWidth`
 - `em-dash` means the comment uses `—`
 - `dash` means the comment uses `–` or `--` between words
 - `semicolon` means the comment joins clauses with a semicolon
@@ -268,7 +269,9 @@ Hints come from heuristics and can be false positives, because only the meaning
 - `emphasis` means the comment uses `*emphasis*` or `**bold**`
 - `banner` means the comment is a divider made of repeated characters
 
-A paragraph with an `orphan` hint is not reported as `unbalanced`, because the suggested rewrap moves the word that the hint is about, and the agent may rightly keep that word where it is. A line that ends early is still an `underfill`, whatever its last word is.
+A paragraph with an `orphan` hint is not reported as `unbalanced` when that word is all that sets it apart from the suggested rewrap, because the agent may rightly keep the word where it is. This holds when the paragraph matches the rewrap that allows orphans. A paragraph that differs from that rewrap too, like a line that ends with the hinted word while more words fit on it, is still `unbalanced`. A line that ends early is still an `underfill`, whatever its last word is.
+
+In the same way, a paragraph that splits a parenthetical is not reported as `unbalanced` when the split is all that sets it apart from the suggested rewrap, because the split can read as well and keep the line closer to `width`. This holds when the lines before the split match the rewrap and the lines after it match the rewrap of the text after the split. Otherwise the paragraph is still `unbalanced`.
 
 Hints are only checked in prose, never in code spans, code blocks, `@example`, or URLs. Rules that can't be measured, like writing complete sentences, are part of the agent's prompt (see `DEFAULT_RULES` in `src/comments/agent.ts`). The prompt treats the style rules as preferences, so the agent keeps punctuation that carries meaning or reads clearly, and never changes code, code spans, literals, patterns, or quotations.
 
@@ -294,7 +297,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.
+A comment that is one paragraph stays on one line up to `singleLineWidth` plus `tolerance`, since that always saves a line, and this 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,7 +309,9 @@ export default defineConfig({
   // defaults to prettier's printWidth, or 80
   width: 100,
   maxWidth: 120,
-  // a comment that is one paragraph stays on one line up to this length, and wraps to `width` beyond it
+  // 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 plus `tolerance`, and wraps to `width` beyond it
   singleLineWidth: 120,
   avoidSentenceOrphans: true,
   // look for possible semicolons, em-dashes, dashes, label colons, emphasis, and banners as hints,

package/dist/bin/comments.js

@@ -24,8 +24,8 @@ 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.
-- 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.
+- 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. A long word, like an identifier or a code span, may stay at the end of a line when moving it would leave that line far shorter than the lines around it. Then leave the line breaks as they are.
 - 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.
 - Separate paragraphs with an empty comment line.
@@ -65,7 +65,8 @@ var ISSUE_DESCRIPTIONS = {
   underfill: "ends early, and words from the next line fit on it",
   widow: "leaves fewer than three words on the last line of its paragraph",
   unbalanced: "is in a paragraph whose lines are less even than the suggested rewrap",
-  orphan: "may end with the start of a new sentence, clause, or parenthetical, which belongs on the next line (leave it if the period or comma before it is part of an abbreviation, a name, or notation like `No. 3`)",
+  orphan: "may end with the start of a new sentence, clause, or parenthetical, which belongs on the next line (leave it if the period or comma before it is part of an abbreviation, a name, or notation like `No. 3`, or if it is a long word like an identifier and moving it would leave the line far shorter than the lines around it)",
+  "split-parenthetical": "may split a parenthetical that the suggested rewrap keeps on one line, past the width but within the maximum (leave it if the split reads as well, like at a comma inside a list, and the line stays closer to the width)",
   "em-dash": "may use an em-dash to join two thoughts (leave it if it's in a quotation, a title, or a string literal, or reads more clearly than the alternatives)",
   banner: "may be a section banner (leave it if it's part of a diagram, a table, a box, a Markdown rule, a separator in an example, or legal text)",
   semicolon: "may join clauses with a semicolon (leave it if it's code, a literal, not a clause join, or reads more clearly than a period or a joining word)",
@@ -131,7 +132,8 @@ function buildPrompt(options) {
     `Fix the formatting of the comments below, following the rules above. Paths are relative to ${options.root}. Widths include indentation and the comment prefix. The notes under each comment come from the tool's measurements, so never count columns yourself.`,
     "",
     "- After you finish, the tool rewraps every prose paragraph as described under Layout, so a layout note on a prose paragraph needs no change from you. Change only the wording there, and leave its line breaks to the tool.",
-    "- A note that a line may end with the start of a sentence, clause, or parenthetical is the exception. Only you can tell whether it does, so if it does, move those words to the start of the next line.",
+    "- A note that a line may end with the start of a sentence, clause, or parenthetical is the exception. Only you can tell whether it does, so if it does, move those words to the start of the next line, unless the Layout rules let a long word stay.",
+    "- A note that a line may split a parenthetical is the other exception. If the parenthetical reads better on one line, move the rest of it up to the end of that line yourself.",
     "- Parts kept as written are never rewrapped, and their notes say so. Fix those notes by hand, for example by breaking an overflowing prose line or by turning a long single-line comment into a multi-line one. Keep code, code spans, tables, box drawings, hard line breaks, and other intentional layout in them exactly as they are. If a note can only be fixed by changing those, leave it and say why in your reply.",
     `- Notes marked \`${HINT_MARKER}\` come from heuristics. If the rule doesn't actually apply, don't change anything for that note.`,
     "- Notes only point at places worth a look. Review each comment against the rules, and leave it as it is when it already follows them.",
@@ -489,6 +491,9 @@ function parentheticalGroups(tokens, limit) {
   }
   return groups;
 }
+function parentheticalAround(tokens, at, limit) {
+  return parentheticalGroups(tokens, limit).find((group) => group.start < at && at < group.end);
+}
 function bindParentheticals(tokens, limit) {
   const groups = new Map(parentheticalGroups(tokens, limit).map((group) => [group.start, group.end]));
   const units = [];
@@ -825,6 +830,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;
@@ -880,6 +898,7 @@ var ISSUE_TIERS = {
   widow: "verdict",
   unbalanced: "verdict",
   orphan: "hint",
+  "split-parenthetical": "hint",
   banner: "hint",
   "em-dash": "hint",
   semicolon: "hint",
@@ -1375,9 +1394,44 @@ function analyzeParagraph(paragraph, options) {
     if (hasWidow(currentLines) && !hasWidow(wrapped)) {
       lineIssues.push({ type: "widow", line: currentLines.length - 1 });
     }
-    if (lineIssues.length === 0 && overflow.length === 0 && (currentLines.length === wrapped.length || options.maxWidth !== void 0)) {
-      const line = wrapped.findIndex((words, position) => words.join(" ") !== currentLines[position]?.join(" "));
-      lineIssues.push({ type: sameLayout(even, currentLines) ? "orphan" : "unbalanced", line: Math.max(line, 0) });
+    const keepsOnlyOrphans = () => {
+      const free = settle({ ...layoutOptions, avoidSentenceOrphans: false });
+      return !("wrapped" in free) || sameLayout(free.wrapped, currentLines);
+    };
+    const splitsOnlyParenthetical = (line) => {
+      if (layoutOptions.parentheticalOverflow === void 0) {
+        return false;
+      }
+      const tokenCount = (lines) => tokenize(lines.flat().join(" ")).length;
+      const end = tokenCount(currentLines.slice(0, line + 1));
+      const group = parentheticalAround(tokens, end, restLimit + layoutOptions.parentheticalOverflow);
+      if (!group) {
+        return false;
+      }
+      const keepsGroup = wrapped.every((_, position) => {
+        const breakAt = tokenCount(wrapped.slice(0, position + 1));
+        return breakAt <= group.start || breakAt >= group.end;
+      });
+      if (!keepsGroup) {
+        return false;
+      }
+      const restOptions = { ...layoutOptions, keepFirstLine: false };
+      const rest = bindLineStarts(tokens.slice(end), startsLine);
+      const restLines = layoutTokens(rest, restLimit, restLimit, restOptions);
+      return sameLayout(breakAfterSentence(restLines, restLimit, restLimit, restOptions), currentLines.slice(line + 1));
+    };
+    if (overflow.length === 0 && (currentLines.length === wrapped.length || options.maxWidth !== void 0)) {
+      const line = Math.max(
+        wrapped.findIndex((words, position) => words.join(" ") !== currentLines[position]?.join(" ")),
+        0
+      );
+      if (lineIssues.length === 0 && sameLayout(even, currentLines)) {
+        lineIssues.push({ type: "orphan", line });
+      } else if (lineIssues.length === 0) {
+        lineIssues.push({ type: splitsOnlyParenthetical(line) ? "split-parenthetical" : "unbalanced", line });
+      } else if (lineIssues.every((issue) => issue.type === "orphan") && !sameLayout(even, currentLines) && !keepsOnlyOrphans()) {
+        lineIssues.push({ type: "unbalanced", line });
+      }
     }
   }
   const suggestion = wrapped.map(
@@ -1507,7 +1561,9 @@ function inspectSource(source, filename, options) {
       options.width,
       Math.min(options.singleLineWidth ?? options.width, options.maxWidth ?? Infinity)
     );
-    const paragraphOptions = shape.paragraphs.length === 1 && singleLineLength(shape.paragraphs[0], options) <= singleLineWidth ? { ...options, width: singleLineWidth } : options;
+    const singleLineLimit = Math.min(singleLineWidth + options.tolerance, options.maxWidth ?? Infinity);
+    const singleLine = shape.paragraphs.length === 1 ? singleLineLength(shape.paragraphs[0], options) : Infinity;
+    const paragraphOptions = singleLine <= singleLineLimit ? { ...options, width: Math.max(singleLineWidth, singleLine) } : options;
     const lines = sourceLines.slice(shape.startLine, shape.endLine + 1);
     reports.push({
       file: filename,
@@ -2167,23 +2223,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 +2343,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 +2854,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 +2875,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 +2901,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 +2989,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 +3050,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."
     );
   }
 }