@d3lm/lint-preset 1.5.0 → 1.5.1

package/README.md

@@ -285,7 +285,7 @@ A comment with an issue in a part that is kept is handed to the agent, which can
 
 ### Configuration
 
-`width` is the preferred line length; `maxWidth` is the hard maximum, including indentation and the comment prefix. The CLI defaults to a maximum of 120 columns (or `width`, if larger). A balanced parenthetical can extend a line past `width` when this keeps it together within `maxWidth`. In longer paragraphs, the wrapper balances all lines together and may split a parenthetical when that produces a better layout. If the parenthetical cannot fit on a line of its own, it wraps normally. For example, `width: 80, maxWidth: 120` keeps `(JSDoc types, \`{@link ...}\`)` together in the example below:
+`width` is the preferred line length; `maxWidth` is the hard maximum, including indentation and the comment prefix. The CLI defaults to a maximum of 120 columns (or `width`, if larger). A balanced parenthetical can extend a line past `width` when this keeps it together within `maxWidth`. In longer paragraphs, the wrapper balances all lines together and may split a parenthetical when that produces a better layout. A line never sticks out more than 15 columns past the line before it, like a full second line after a first line that the orphan rule keeps short, when up to two more lines avoid that. If the parenthetical cannot fit on a line of its own, it wraps normally. For example, `width: 80, maxWidth: 120` keeps `(JSDoc types, \`{@link ...}\`)` together in the example below:
 
 ```ts
 /**

package/dist/bin/comments.js

@@ -578,6 +578,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);
@@ -710,7 +712,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))) {
@@ -744,14 +795,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(
@@ -1270,11 +1314,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) => {
@@ -1283,29 +1327,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);