@d3lm/lint-preset 1.6.2 → 1.6.3

package/README.md

@@ -258,6 +258,7 @@ Verdicts are layout issues that can be measured without reading the prose. They
 - `underfill` means a line ends early, so the paragraph needs more lines than it should
 - `widow` means fewer than three words sit on the last line of a paragraph
 - `unbalanced` means the lines are less even than in the suggested rewrap, or a line ends inside a link, code span, or `{...}` group (see [Text That Stays on One Line](#text-that-stays-on-one-line))
+- `wide` means a line ends more than `tolerance` columns past `width`, and past every line of the suggested rewrap, but within `maxWidth`
 
 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:
 
@@ -274,9 +275,9 @@ A paragraph with an `orphan` hint is not reported as `unbalanced` when that word
 
 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`.
 
-With a `tolerance`, a paragraph has no `underfill`, `widow`, or `unbalanced` verdict when it already has the layout that the tool produces for a wider `width`, up to `width` plus `tolerance`. Its suggestion then keeps the lines as they are. With `width: 100` and `tolerance: 5`, a paragraph that is laid out the way the tool lays it out for a width of 105 passes. A paragraph that only has hints keeps them, and a line past `maxWidth` is still an `overflow`.
+With a `tolerance`, a paragraph has no `underfill`, `widow`, `unbalanced`, or `wide` verdict when it already has the layout that the tool produces for a wider `width`, up to `width` plus `tolerance`. Its suggestion then keeps the lines as they are. With `width: 100` and `tolerance: 5`, a paragraph that is laid out the way the tool lays it out for a width of 105 passes. A paragraph that only has hints keeps them, and a line past `maxWidth` is still an `overflow`.
 
-The `tolerance` also holds for each line on its own, in both directions. A paragraph is not `unbalanced` when it has as many lines as the suggested rewrap and no line is more than `tolerance` columns shorter or longer than the same line of the rewrap. Its suggestion then keeps the lines as they are too. With `tolerance: 5`, a short word like `as` can start a line where the rewrap ends the line before with it. A line that is longer than in the rewrap must still end within `width` plus `tolerance`. This only applies to a paragraph whose only layout issue is `unbalanced`. A `widow` is still reported, and so is a paragraph that has an `orphan` hint too, so the rewrap still moves that word. A line that ends inside a link, code span, `{...}` group, or the head of a JSDoc tag is still `unbalanced` as well.
+The `tolerance` also holds for each line on its own. A paragraph is not `unbalanced` when it has as many lines as the suggested rewrap, each line but the last is at most `tolerance` columns shorter than the shortest of those lines in the rewrap, and no line ends more than `tolerance` columns past `width`, unless the same line of the rewrap does too. Its suggestion then keeps the lines as they are too. The shortest line of the rewrap is the measure, not the same line, since one word that moves to another line shifts every line after it. With `width: 100` and `tolerance: 5`, a paragraph whose rewrap has lines of 92 to 98 columns passes with lines of 87 to 105 columns, the last line aside. Without a `tolerance`, a paragraph needs the exact layout of the rewrap. This only applies to a paragraph whose only layout issue is `unbalanced`, so a line that is `wide` is still reported. A `widow` is still reported, and so is a paragraph that has an `orphan` hint too, so the rewrap still moves that word. A line that ends inside a link, code span, `{...}` group, or the head of a JSDoc tag is still `unbalanced` as well.
 
 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.
 
@@ -312,7 +313,7 @@ node native/verify/verify.mjs --corpus ~/.cargo/registry/src/index.crates.io-194
 
 ### Configuration
 
-`width` is the preferred line length, and `maxWidth` is the hard maximum, including indentation and the comment prefix. The CLI defaults `maxWidth` to 120, or to `width` if that is larger. The wrapper may go past `width`, up to `maxWidth`, to keep a parenthetical on one line. `tolerance` (default 0) lets lines in paragraphs of three or more lines go that many columns past `width` when that saves a line. `check` also accepts a paragraph that already has the layout for a wider `width`, up to `width` plus `tolerance`, and a paragraph whose lines are each within `tolerance` columns of the suggested rewrap (see [Issues](#issues)), while the tool itself still wraps to `width`. A comment that is one paragraph stays on one line up to `singleLineWidth` plus `tolerance`, capped by `maxWidth`. A word, code span, or link longer than `maxWidth` is never split and is reported as `overflow`.
+`width` is the preferred line length, and `maxWidth` is the hard maximum, including indentation and the comment prefix. The CLI defaults `maxWidth` to 120, or to `width` if that is larger. The wrapper may go past `width`, up to `maxWidth`, to keep a parenthetical on one line. `tolerance` (default 0) lets lines in paragraphs of three or more lines go that many columns past `width` when that saves a line. `check` also accepts a paragraph that already has the layout for a wider `width`, up to `width` plus `tolerance`, and a paragraph with as many lines as the suggested rewrap whose lines stay within `tolerance` columns of its shortest line and of `width` (see [Issues](#issues)), while the tool itself still wraps to `width`. A comment that is one paragraph stays on one line up to `singleLineWidth` plus `tolerance`, capped by `maxWidth`. A word, code span, or link longer than `maxWidth` is never split and is reported as `overflow`.
 
 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.
 

package/dist/bin/comments.js

@@ -75,6 +75,7 @@ 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, or that splits a link or code span that the rewrap keeps on one line",
+  wide: "ends more than the tolerance past the width, and past every line of the suggested rewrap",
   orphan: "may end with the start of a new sentence or parenthetical, or with the first word after a semicolon or colon, which belongs on the next line (leave it if the punctuation 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)",
@@ -1073,6 +1074,7 @@ var ISSUE_TIERS = {
   underfill: "verdict",
   widow: "verdict",
   unbalanced: "verdict",
+  wide: "verdict",
   orphan: "hint",
   "split-parenthetical": "hint",
   banner: "hint",
@@ -1659,6 +1661,14 @@ function analyzeParagraph(paragraph, options, language) {
       const restLines = layoutTokens(rest, restLimit, restLimit, restOptions);
       return sameLayout(breakAfterSentence(restLines, restLimit, restLimit, restOptions), currentLines.slice(line + 1));
     };
+    const differenceAt = (line) => {
+      const longest = Math.max(...wrapped.map((words) => words.join(" ").length));
+      const wide = currentLines.flatMap((words, position) => {
+        const limit = (position === 0 ? firstLimit : restLimit) + layoutOptions.tolerance;
+        return words.join(" ").length > Math.max(limit, longest) ? [{ type: "wide", line: position }] : [];
+      });
+      return wide.length > 0 ? wide : [{ type: "unbalanced", line }];
+    };
     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(" ")),
@@ -1667,9 +1677,11 @@ function analyzeParagraph(paragraph, options, language) {
       if (lineIssues.length === 0 && (sameLayout(even, currentLines) || keepsOnlySentenceStarts())) {
         lineIssues.push({ type: "orphan", line });
       } else if (lineIssues.length === 0) {
-        lineIssues.push({ type: splitsOnlyParenthetical(line) ? "split-parenthetical" : "unbalanced", line });
+        lineIssues.push(
+          ...splitsOnlyParenthetical(line) ? [{ type: "split-parenthetical", line }] : differenceAt(line)
+        );
       } else if (lineIssues.every((issue) => issue.type === "orphan") && !sameLayout(even, currentLines) && !keepsOnlyOrphans()) {
-        lineIssues.push({ type: "unbalanced", line });
+        lineIssues.push(...differenceAt(line));
       }
     }
     const splitLine = splitTokenLine(currentLines, tokens);
@@ -1687,14 +1699,15 @@ function analyzeParagraph(paragraph, options, language) {
     return false;
   };
   const staysNearLayout = () => {
-    if (currentLines.length !== wrapped.length || splitTokenLine(currentLines, units) !== -1) {
+    if (layoutOptions.tolerance === 0 || currentLines.length !== wrapped.length || splitTokenLine(currentLines, units) !== -1) {
       return false;
     }
+    const shortest = Math.min(...wrapped.slice(0, -1).map((words) => words.join(" ").length));
     return currentLines.every((words, position) => {
       const length = words.join(" ").length;
-      const suggestedLength = wrapped[position].join(" ").length;
       const limit = (position === 0 ? firstLimit : restLimit) + layoutOptions.tolerance;
-      return Math.abs(length - suggestedLength) <= layoutOptions.tolerance && length <= Math.max(suggestedLength, limit);
+      const isLast = position === currentLines.length - 1;
+      return (isLast || length >= shortest - layoutOptions.tolerance) && length <= Math.max(wrapped[position].join(" ").length, limit);
     });
   };
   const hasVerdict = lineIssues.some((issue) => isVerdict(issue));