@d3lm/lint-preset 1.5.0 → 1.5.2

package/README.md

@@ -245,7 +245,7 @@ comments agent                     # hand suspicious comments to an agent, then
 comments check --cwd ../other-app  # run as if started in another project
 ```
 
-Without targets, only comments in uncommitted changes and untracked files are checked. `--staged` limits that to staged changes, `--base main` checks everything since the merge base with `main`, and `--repo` checks every file. Targets can be files, directories, `file:line`, or `file:start-end`. A comment that contains `comments-ignore` is skipped. A file with a syntax error is skipped as a whole and named in a warning, because the parser stops at the error and never sees the comments after it. JSX is read in `.js` files too.
+Without targets, only comments in uncommitted changes and untracked files are checked. `--base main` checks everything since the merge base with `main`, and `--repo` checks every file. `--whole-files` checks every comment in the changed files instead of only the comments on changed lines. Targets can be files, directories, `file:line`, or `file:start-end`. A comment that contains `comments-ignore` is skipped. A file with a syntax error is skipped as a whole and named in a warning, because the parser stops at the error and never sees the comments after it. JSX is read in `.js` files too.
 
 With `--json`, each paragraph of a comment comes with its issues and a `suggestion` that holds the exact rewrapped lines. Code blocks, `@example`, tables, drawings, directives, and other [text kept as written](#text-kept-as-written) have no suggestion.
 
@@ -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
 /**
@@ -294,7 +294,7 @@ A comment with an issue in a part that is kept is handed to the agent, which can
  */
 ```
 
-The separate `singleLineWidth` allowance is capped by `maxWidth`. Code and documented layout regions retain their exemptions. An indivisible token in measured prose that exceeds `maxWidth` is reported as overflow; the wrapper preserves it, so resolving that case requires changing the maximum or the comment manually. The legacy `tolerance` option sets a maximum of `width + tolerance` when `maxWidth` is omitted; an explicit `maxWidth` takes precedence. Direct `analyzeSource` callers can omit `maxWidth` to retain the legacy width/tolerance behavior.
+The separate `singleLineWidth` allowance is capped by `maxWidth`. Code and documented layout regions retain their exemptions. An indivisible token in measured prose that exceeds `maxWidth` is reported as overflow; the wrapper preserves it, so resolving that case requires changing the maximum or the comment manually. `tolerance` lets prose lines go up to that many columns past `width` when that saves a line in a paragraph of three or more lines, and it never goes past `maxWidth`. It defaults to 0. When `maxWidth` is omitted, `tolerance` also sets a legacy maximum of `width + tolerance`. Direct `analyzeSource` callers can omit `maxWidth` to retain the legacy width/tolerance behavior.
 
 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.
 
@@ -306,6 +306,8 @@ export default defineConfig({
   // defaults to prettier's printWidth, or 80
   width: 100,
   maxWidth: 120,
+  // prose lines may go this many columns past `width` when that saves a line
+  tolerance: 0,
   // a comment that is one paragraph stays on one line up to this length, and wraps to `width` beyond it
   singleLineWidth: 120,
   avoidSentenceOrphans: true,

package/dist/bin/comments.js

@@ -24,7 +24,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.
@@ -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(
@@ -781,6 +825,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;
@@ -1270,11 +1327,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 +1340,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);
@@ -2114,23 +2180,12 @@ function snapshotChanges(root) {
 var DIFF_FLAGS = ["diff", "-U0", "--no-color", "--no-ext-diff", "--no-renames", "--src-prefix=a/", "--dst-prefix=b/"];
 function getChangedLines(root, scope = {}) {
   if (!hasHead(root)) {
-    const files = scope.staged ? splitPaths(gitOrThrow(root, ["diff", "-z", "--cached", "--name-only", "--diff-filter=d"])) : listFiles2(root);
-    return new Map(files.map((file) => [file, "all"]));
-  }
-  let args;
-  if (scope.staged) {
-    args = [...DIFF_FLAGS, "--cached", "HEAD"];
-  } else if (scope.base) {
-    const mergeBase = gitOrThrow(root, ["merge-base", scope.base, "HEAD"]).trim();
-    args = [...DIFF_FLAGS, mergeBase];
-  } else {
-    args = [...DIFF_FLAGS, "HEAD"];
+    return new Map(listFiles2(root).map((file) => [file, "all"]));
   }
-  const changed = parseUnifiedDiff(gitOrThrow(root, args));
-  if (!scope.staged) {
-    for (const file of listUntrackedFiles(root)) {
-      changed.set(file, "all");
-    }
+  const target = scope.base ? gitOrThrow(root, ["merge-base", scope.base, "HEAD"]).trim() : "HEAD";
+  const changed = parseUnifiedDiff(gitOrThrow(root, [...DIFF_FLAGS, target]));
+  for (const file of listUntrackedFiles(root)) {
+    changed.set(file, "all");
   }
   return changed;
 }
@@ -2245,7 +2300,7 @@ var Project = class {
       throw new Error("comments: not a git repository, so pass files or directories explicitly");
     }
     for (const [file, lines] of getChangedLines(this.root, scope)) {
-      add(path4.join(this.root, file), lines);
+      add(path4.join(this.root, file), scope.wholeFiles ? "all" : lines);
     }
     return files;
   }
@@ -2756,8 +2811,8 @@ Targets are files, directories, file:line, or file:start-end. Without targets, o
 overlapping uncommitted changes (and untracked files) are considered.
 
 Options:
-  --staged          Only consider staged changes
   --base <ref>      Consider changes since the merge base with <ref>
+  --whole-files     Consider every comment in the changed files, not only comments on changed lines
   --repo            Consider every file in the repository
   --suspicious      Only comments with layout issues (overflow, early line ends, last lines of one or two words)
                     or hints (possible orphans, em-dashes, banners, ...). For agent and hook (the default), only
@@ -2777,7 +2832,7 @@ 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>         Legacy hard limit of width + n, unless max-width is set
+  --tolerance <n>         Columns prose may go past width to save a line, within max-width (default: 0)
   --[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
@@ -2803,8 +2858,8 @@ var OPTIONS = {
   "max-files": { type: "string" },
   "max-agents": { type: "string" },
   instructions: { type: "string" },
-  staged: { type: "boolean" },
   base: { type: "string" },
+  "whole-files": { type: "boolean" },
   repo: { type: "boolean" },
   suspicious: { type: "boolean" },
   all: { type: "boolean" },
@@ -2891,7 +2946,7 @@ async function createProject(cwd, values) {
   return { project, configPath: loaded.filepath };
 }
 function scopeFrom(positionals, values) {
-  return { targets: positionals, staged: values.staged, base: values.base, repo: values.repo };
+  return { targets: positionals, base: values.base, wholeFiles: values["whole-files"], repo: values.repo };
 }
 function selectFrom(values, project) {
   if (values.all) {
@@ -2952,9 +3007,8 @@ function commentsOf(analyses) {
 function hintEmptyScope(analyses, scope) {
   const isDefaultScope = (scope.targets ?? []).length === 0 && !scope.repo && !scope.base;
   if (analyses.length === 0 && isDefaultScope) {
-    const changes = scope.staged ? "staged changes" : "uncommitted changes";
     log2(
-      `comments: no ${changes} in JavaScript or TypeScript files. Pass --repo, --base <ref>, or files to widen the scope.`
+      "comments: no uncommitted changes in JavaScript or TypeScript files. Pass --repo, --base <ref>, or files to widen the scope."
     );
   }
 }