@d3lm/lint-preset 1.5.1 → 1.5.4

package/dist/comments.d.cts

@@ -9,7 +9,8 @@ interface WrapOptions {
      */
     readonly avoidSentenceOrphans: boolean;
     /**
-     * Sets how many columns a line may exceed its limit before it counts as overflowing.
+     * Sets how many columns a line may exceed its limit before it counts as overflowing. A layout
+     * also uses them when that saves a line.
      */
     readonly tolerance: number;
     /**
@@ -17,7 +18,7 @@ interface WrapOptions {
      */
     readonly parentheticalOverflow?: number;
 }
-type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced';
+type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced' | 'split-parenthetical';
 /**
  * JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay intact like code spans.
  */
@@ -42,8 +43,8 @@ interface AnalyzeOptions extends WrapOptions {
     readonly maxWidth?: number;
     /**
      * Sets the maximum length of the line that holds a comment whose whole text is one
-     * prose paragraph. Such a comment stays on one line up to this length, even past
-     * `width`. It defaults to `width`.
+     * prose paragraph. Such a comment stays on one line up to this length plus `tolerance`,
+     * even past `width`, but never past `maxWidth`. It defaults to `width`.
      */
     readonly singleLineWidth?: number;
     readonly tabWidth: number;
@@ -205,13 +206,15 @@ interface CommentsConfig {
     readonly maxWidth?: number;
     /**
      * Sets the maximum length of the line that holds a comment whose whole text is one prose
-     * paragraph. Such a comment stays on one line up to this length, even past `width`, and is
-     * wrapped to `width` beyond it. Defaults to 120 and never exceeds `maxWidth`.
+     * paragraph. Such a comment stays on one line up to this length plus `tolerance`, even past
+     * `width`, and is wrapped to `width` beyond it. Defaults to 120, and the line never exceeds
+     * `maxWidth`.
      */
     readonly singleLineWidth?: number;
     /**
-     * Sets a legacy hard limit of `width + tolerance` when `maxWidth` is omitted.
-     * An explicit `maxWidth` takes precedence.
+     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph of
+     * three or more lines. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a
+     * legacy hard limit of `width + tolerance`.
      */
     readonly tolerance?: number;
     /**

package/dist/comments.d.ts

@@ -9,7 +9,8 @@ interface WrapOptions {
      */
     readonly avoidSentenceOrphans: boolean;
     /**
-     * Sets how many columns a line may exceed its limit before it counts as overflowing.
+     * Sets how many columns a line may exceed its limit before it counts as overflowing. A layout
+     * also uses them when that saves a line.
      */
     readonly tolerance: number;
     /**
@@ -17,7 +18,7 @@ interface WrapOptions {
      */
     readonly parentheticalOverflow?: number;
 }
-type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced';
+type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced' | 'split-parenthetical';
 /**
  * JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay intact like code spans.
  */
@@ -42,8 +43,8 @@ interface AnalyzeOptions extends WrapOptions {
     readonly maxWidth?: number;
     /**
      * Sets the maximum length of the line that holds a comment whose whole text is one
-     * prose paragraph. Such a comment stays on one line up to this length, even past
-     * `width`. It defaults to `width`.
+     * prose paragraph. Such a comment stays on one line up to this length plus `tolerance`,
+     * even past `width`, but never past `maxWidth`. It defaults to `width`.
      */
     readonly singleLineWidth?: number;
     readonly tabWidth: number;
@@ -205,13 +206,15 @@ interface CommentsConfig {
     readonly maxWidth?: number;
     /**
      * Sets the maximum length of the line that holds a comment whose whole text is one prose
-     * paragraph. Such a comment stays on one line up to this length, even past `width`, and is
-     * wrapped to `width` beyond it. Defaults to 120 and never exceeds `maxWidth`.
+     * paragraph. Such a comment stays on one line up to this length plus `tolerance`, even past
+     * `width`, and is wrapped to `width` beyond it. Defaults to 120, and the line never exceeds
+     * `maxWidth`.
      */
     readonly singleLineWidth?: number;
     /**
-     * Sets a legacy hard limit of `width + tolerance` when `maxWidth` is omitted.
-     * An explicit `maxWidth` takes precedence.
+     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph of
+     * three or more lines. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a
+     * legacy hard limit of `width + tolerance`.
      */
     readonly tolerance?: number;
     /**

package/dist/comments.js

@@ -199,6 +199,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 = [];
@@ -535,6 +538,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;
@@ -590,6 +606,7 @@ var ISSUE_TIERS = {
   widow: "verdict",
   unbalanced: "verdict",
   orphan: "hint",
+  "split-parenthetical": "hint",
   banner: "hint",
   "em-dash": "hint",
   semicolon: "hint",
@@ -1085,9 +1102,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(
@@ -1220,7 +1272,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,
@@ -1282,8 +1336,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.