@d3lm/lint-preset 1.5.0 → 1.5.2

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;
     /**
@@ -210,8 +211,9 @@ interface CommentsConfig {
      */
     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;
     /**
@@ -210,8 +211,9 @@ interface CommentsConfig {
      */
     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

@@ -288,6 +288,8 @@ function hasWidow(lines) {
 }
 var FULLNESS_WEIGHT = 0.07;
 var PARENTHETICAL_SPLIT_WEIGHT = 2;
+var MAX_STEP = 15;
+var EXTRA_LINES = 2;
 function fewestLines(starts, target) {
   const total = starts.length - 1;
   const fewest = new Int32Array(total + 1);
@@ -420,7 +422,56 @@ function balanceTokens(tokens, firstLimit, restLimit, count, options, preferredL
   const bounds = [0, ...best.breaks, total];
   return bounds.slice(0, -1).map((start, index) => tokens.slice(start, bounds[index + 1]));
 }
+function hasStep(lines, offset = 0) {
+  return lines.some((line, index) => {
+    if (index === 0) {
+      return false;
+    }
+    const before = lineLength(lines[index - 1]) + (index === 1 ? offset : 0);
+    return lineLength(line) - before > MAX_STEP;
+  });
+}
+function splitCostsOf(tokens, limit) {
+  const splitCosts = /* @__PURE__ */ new Map();
+  for (const group of parentheticalGroups(tokens, limit)) {
+    const length = lineLength(tokens.slice(group.start, group.end));
+    for (let at = group.start + 1; at < group.end; at += 1) {
+      splitCosts.set(at, length * PARENTHETICAL_SPLIT_WEIGHT);
+    }
+  }
+  return splitCosts;
+}
+function hasParentheticals(tokens, restLimit, options) {
+  if (options.parentheticalOverflow === void 0) {
+    return false;
+  }
+  return bindParentheticals(tokens, restLimit + options.parentheticalOverflow).some((token) => isParenthetical(token));
+}
 function layoutTokens(tokens, firstLimit, restLimit, options) {
+  const lines = layoutLines(tokens, firstLimit, restLimit, options);
+  const offset = restLimit - firstLimit;
+  if (options.keepFirstLine || options.keepSteps || !hasStep(lines, offset)) {
+    return lines;
+  }
+  const overflow = hasParentheticals(tokens, restLimit, options) ? options.parentheticalOverflow ?? 0 : 0;
+  const splitCosts = overflow > 0 ? splitCostsOf(tokens, restLimit + overflow) : /* @__PURE__ */ new Map();
+  for (let count = lines.length + 1; count <= lines.length + EXTRA_LINES; count += 1) {
+    const even = balanceTokens(
+      tokens,
+      firstLimit + overflow,
+      restLimit + overflow,
+      count,
+      options,
+      restLimit,
+      splitCosts
+    );
+    if (even && !hasStep(even, offset)) {
+      return even;
+    }
+  }
+  return lines;
+}
+function layoutLines(tokens, firstLimit, restLimit, options) {
   if (options.parentheticalOverflow !== void 0) {
     const grouped = bindParentheticals(tokens, restLimit + options.parentheticalOverflow);
     if (grouped.some((token) => isParenthetical(token))) {
@@ -454,14 +505,7 @@ function layoutTokens(tokens, firstLimit, restLimit, options) {
           return expanded;
         });
       }
-      const splitCosts = /* @__PURE__ */ new Map();
-      const groups = parentheticalGroups(tokens, restLimit + options.parentheticalOverflow);
-      for (const group of groups) {
-        const length = lineLength(tokens.slice(group.start, group.end));
-        for (let at = group.start + 1; at < group.end; at += 1) {
-          splitCosts.set(at, length * PARENTHETICAL_SPLIT_WEIGHT);
-        }
-      }
+      const splitCosts = splitCostsOf(tokens, restLimit + options.parentheticalOverflow);
       const preferred = wrapTokens(tokens, firstLimit, restLimit, { ...options, parentheticalOverflow: void 0 });
       for (let count = minimumLines; count <= Math.max(preferred.length + 1, preserved.length); count += 1) {
         const balanced2 = balanceTokens(
@@ -491,6 +535,19 @@ function layoutTokens(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;
@@ -980,11 +1037,11 @@ function analyzeParagraph(paragraph, options) {
     parentheticalOverflow: options.maxWidth === void 0 ? void 0 : options.maxWidth - options.width,
     keepFirstLine: paragraph.kind === "tag"
   };
-  const layOut = (from) => {
-    const even2 = layoutTokens(from, firstLimit, restLimit, layoutOptions);
-    return { even: even2, wrapped: breakAfterSentence(even2, firstLimit, restLimit, layoutOptions) };
+  const layOut = (from, settings) => {
+    const even2 = layoutTokens(from, firstLimit, restLimit, settings);
+    return { even: even2, wrapped: breakAfterSentence(even2, firstLimit, restLimit, settings) };
   };
-  let units = bindLineStarts(paragraph.kind === "tag" ? bindTagHead(tokens) : tokens, startsLine);
+  const units = bindLineStarts(paragraph.kind === "tag" ? bindTagHead(tokens) : tokens, startsLine);
   const hardLimit = restLimit + (options.maxWidth === void 0 ? options.tolerance : options.maxWidth - options.width);
   const written = currentLines.map((words) => ` ${words.join(" ")} `);
   const staysInLimit = (unit) => {
@@ -993,29 +1050,38 @@ function analyzeParagraph(paragraph, options) {
   if (!units.every((unit) => staysInLimit(unit))) {
     return keep({ tier: "manual", reason: "unbreakable text across lines" });
   }
-  let { even, wrapped } = layOut(units);
   const bodyOf = (lines) => {
     return lines.map((words, position) => {
       const text = `${position === 0 ? paragraph.marker : hang}${words.join(" ")}`;
       return { ...first, text, verbatim: false, hardBreak: HARD_BREAK.test(text) };
     });
   };
-  for (; ; ) {
-    const body = bodyOf(wrapped);
-    const rewrap = structureOf(body);
-    if (!rewrap) {
-      break;
-    }
-    const tipping = body.findIndex((_, position) => structureOf(body.slice(0, position + 1)) !== void 0);
-    const start = wrapped.slice(0, Math.max(tipping, 1)).flat().length;
-    const pair = `${units[start - 1]} ${units[start]}`;
-    if (body.length < 2 || !staysInLimit(pair)) {
-      const reading = rewrap.tier === "code-like" ? "code" : rewrap.reason;
-      return keep({ tier: "manual", reason: `rewrap would read as ${reading}` });
+  const settle = (settings) => {
+    let current = units;
+    let { even: even2, wrapped: wrapped2 } = layOut(current, settings);
+    for (; ; ) {
+      const body = bodyOf(wrapped2);
+      const rewrap = structureOf(body);
+      if (!rewrap) {
+        return { even: even2, wrapped: wrapped2 };
+      }
+      const tipping = body.findIndex((_, position) => structureOf(body.slice(0, position + 1)) !== void 0);
+      const start = wrapped2.slice(0, Math.max(tipping, 1)).flat().length;
+      const pair = `${current[start - 1]} ${current[start]}`;
+      if (body.length < 2 || !staysInLimit(pair)) {
+        const reading = rewrap.tier === "code-like" ? "code" : rewrap.reason;
+        return { tier: "manual", reason: `rewrap would read as ${reading}` };
+      }
+      current = current.toSpliced(start - 1, 2, pair);
+      ({ even: even2, wrapped: wrapped2 } = layOut(current, settings));
     }
-    units = units.toSpliced(start - 1, 2, pair);
-    ({ even, wrapped } = layOut(units));
+  };
+  const settled = settle(layoutOptions);
+  const layout = "wrapped" in settled ? settled : settle({ ...layoutOptions, keepSteps: true });
+  if (!("wrapped" in layout)) {
+    return keep(layout);
   }
+  const { even, wrapped } = layout;
   const matchesLayout = sameLayout(wrapped, currentLines);
   const lineIssues = [];
   const overflow = options.maxWidth === void 0 ? [] : overflowIssues(paragraph.lines, options);
@@ -1229,7 +1295,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.