@d3lm/lint-preset 1.5.5 → 1.5.6

package/README.md

@@ -273,6 +273,8 @@ 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`.
+
 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.
 
 ### Text Kept as Written
@@ -287,7 +289,7 @@ To keep a drawing that is wider than the width, put it in a code fence or add `c
 
 ### 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. A comment that is one paragraph stays on one line up to `singleLineWidth` plus `tolerance`, capped by `maxWidth`. A word or code span 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`, 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 or code span 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

@@ -1351,9 +1351,9 @@ function analyzeParagraph(paragraph, options) {
     parentheticalOverflow: options.maxWidth === void 0 ? void 0 : options.maxWidth - options.width,
     keepFirstLine: paragraph.kind === "tag"
   };
-  const layOut = (from, settings) => {
-    const even2 = layoutTokens(from, firstLimit, restLimit, settings);
-    return { even: even2, wrapped: breakAfterSentence(even2, firstLimit, restLimit, settings) };
+  const layOut = (from, settings, extra) => {
+    const even2 = layoutTokens(from, firstLimit + extra, restLimit + extra, settings);
+    return { even: even2, wrapped: breakAfterSentence(even2, firstLimit + extra, restLimit + extra, settings) };
   };
   const units = bindLineStarts(paragraph.kind === "tag" ? bindTagHead(tokens) : tokens, startsLine);
   const hardLimit = restLimit + (options.maxWidth === void 0 ? options.tolerance : options.maxWidth - options.width);
@@ -1370,9 +1370,9 @@ function analyzeParagraph(paragraph, options) {
       return { ...first, text, verbatim: false, hardBreak: HARD_BREAK.test(text) };
     });
   };
-  const settle = (settings) => {
+  const settle = (settings, extra = 0) => {
     let current = units;
-    let { even: even2, wrapped: wrapped2 } = layOut(current, settings);
+    let { even: even2, wrapped: wrapped2 } = layOut(current, settings, extra);
     for (; ; ) {
       const body = bodyOf(wrapped2);
       const rewrap = structureOf(body);
@@ -1387,11 +1387,19 @@ function analyzeParagraph(paragraph, options) {
         return { tier: "manual", reason: `rewrap would read as ${reading}` };
       }
       current = current.toSpliced(start - 1, 2, pair);
-      ({ even: even2, wrapped: wrapped2 } = layOut(current, settings));
+      ({ even: even2, wrapped: wrapped2 } = layOut(current, settings, extra));
     }
   };
-  const settled = settle(layoutOptions);
-  const layout = "wrapped" in settled ? settled : settle({ ...layoutOptions, keepSteps: true });
+  const layoutAt = (extra) => {
+    const settings = {
+      ...layoutOptions,
+      tolerance: layoutOptions.tolerance - extra,
+      parentheticalOverflow: layoutOptions.parentheticalOverflow === void 0 ? void 0 : layoutOptions.parentheticalOverflow - extra
+    };
+    const settled = settle(settings, extra);
+    return "wrapped" in settled ? settled : settle({ ...settings, keepSteps: true }, extra);
+  };
+  const layout = layoutAt(0);
   if (!("wrapped" in layout)) {
     return keep(layout);
   }
@@ -1456,10 +1464,22 @@ function analyzeParagraph(paragraph, options) {
       }
     }
   }
-  const suggestion = wrapped.map(
+  const isVerdict = (issue) => ISSUE_TIERS[issue.type] === "verdict";
+  const matchesWiderLayout = () => {
+    for (let extra = 1; extra <= layoutOptions.tolerance; extra += 1) {
+      const wider = layoutAt(extra);
+      if ("wrapped" in wider && sameLayout(wider.wrapped, currentLines)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  const accepted = lineIssues.some((issue) => isVerdict(issue)) && matchesWiderLayout();
+  const suggested = accepted ? currentLines : wrapped;
+  const suggestion = suggested.map(
     (words, position) => `${prefix}${position === 0 ? paragraph.marker : hang}${words.join(" ")}`
   );
-  const wrapIssues = lineIssues.map((issue) => lineIssue(issue.type, paragraph.lines[issue.line], options));
+  const wrapIssues = lineIssues.filter((issue) => !accepted || !isVerdict(issue)).map((issue) => lineIssue(issue.type, paragraph.lines[issue.line], options));
   const issues = byLine([...overflow, ...wrapIssues, ...styleIssues(paragraph, options)]);
   return { ...base, reflowable: true, issues, suggestion };
 }
@@ -2897,7 +2917,8 @@ 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>         Columns prose may go past width to save a line, within max-width (default: 0)
+  --tolerance <n>         Columns prose may go past width to save a line, within max-width (default: 0).
+                          A paragraph that has the layout for a width up to that much wider also passes
   --[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