@d3lm/lint-preset 1.6.0 → 1.6.2

package/dist/comments.d.cts

@@ -2,11 +2,12 @@ type StyleIssueType = 'semicolon' | 'em-dash' | 'dash' | 'label-colon' | 'emphas
 
 interface WrapOptions {
     /**
-     * Sets whether a line may not end with the first word of a sentence, clause, or parenthetical,
-     * like `This`, `the` after a comma, or `(the`. Such a word moves to the next line instead.
-     * It also sets whether a line avoids ending with the first two words of a sentence, and whether
-     * the first of two lines ends with a sentence instead of the start of the next one, as long as
-     * the second line is then no longer than the first.
+     * Sets whether a line may not end with the first word of a sentence or parenthetical, like
+     * `This` or `(the`, or with the first word after a semicolon or colon. Such a word moves to
+     * the next line instead. The word after a comma may end a line. It also sets whether a line
+     * avoids ending with the first two words of a sentence, and whether the first of two lines
+     * ends with a sentence instead of the start of the next one, as long as the second line is
+     * then no longer than the first.
      */
     readonly avoidSentenceOrphans: boolean;
     /**
@@ -54,9 +55,9 @@ 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 plus `tolerance`,
-     * even past `width`, but never past `maxWidth`. It defaults to `width`.
+     * 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 plus `tolerance`, even past
+     * `width`, but never past `maxWidth`. It defaults to `width`.
      */
     readonly singleLineWidth?: number;
     readonly tabWidth: number;
@@ -84,10 +85,10 @@ interface ParagraphReport {
     readonly reason?: string;
     readonly issues: readonly IssueReport[];
     /**
-     * Holds the exact source lines for `startLine` through `endLine` when the paragraph is
-     * greedily wrapped to the width, or `null` when the paragraph isn't prose, e.g. code,
-     * a table, a diagram, or `@example`. A paragraph that is accepted with the layout for a
-     * wider width within the tolerance keeps its lines.
+     * Holds the exact source lines for `startLine` through `endLine` when the paragraph is greedily
+     * wrapped to the width, or `null` when the paragraph isn't prose, e.g. code, a table, a diagram,
+     * or `@example`. A paragraph that the tolerance accepts as it is, with the layout for a wider
+     * width or with lines close to this one, keeps its lines.
      */
     readonly suggestion: readonly string[] | null;
 }
@@ -228,24 +229,27 @@ interface CommentsConfig {
      * 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 plus `tolerance`, even past
      * `width`, and is wrapped to `width` beyond it. Defaults to 120, and the line never exceeds
-     * `maxWidth`.
+     * the `maxWidth` limit.
      */
     readonly singleLineWidth?: number;
     /**
-     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph of
-     * three or more lines. A paragraph that already has the layout for a wider `width`, up to `width`
-     * plus this many columns, also passes as it is. It never goes past `maxWidth`. When `maxWidth` is
-     * omitted, it also sets a legacy hard limit of `width + tolerance`.
+     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph
+     * of three or more lines. A paragraph that already has the layout for a wider `width`, up to
+     * `width` plus this many columns, also passes as it is. So does a paragraph with as many lines
+     * as the rewrap whose lines are each at most this many columns shorter or longer than in the
+     * rewrap. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a legacy hard
+     * limit of `width + tolerance`.
      */
     readonly tolerance?: number;
     /**
      * Keep the first word of a new sentence or parenthetical off the end of a line, e.g.
-     * `...the module. This` or `...reflows (the` followed by the rest on the next line.
-     * A paragraph of two lines also ends its first line with a sentence when the rest fits
-     * on the second line and is no longer than the first, instead of with the start of
-     * the next sentence, like `...the module. This one`. Other lines avoid ending with the
-     * first two words of a sentence, like `...opens. It allocates`, unless that makes them
-     * much less even. Defaults to `true`.
+     * `...the module. This` or `...reflows (the` followed by the rest on the next line. The same
+     * goes for the first word after a semicolon or colon, but not after a comma, so a line may
+     * end with `...the paths, and`. A paragraph of two lines also ends its first line with a
+     * sentence when the rest fits on the second line and is no longer than the first, instead
+     * of with the start of the next sentence, like `...the module. This one`. Other lines avoid
+     * ending with the first two words of a sentence, like `...opens. It allocates`, unless that
+     * makes them much less even. Defaults to `true`.
      */
     readonly avoidSentenceOrphans?: boolean;
     /**

package/dist/comments.d.ts

@@ -2,11 +2,12 @@ type StyleIssueType = 'semicolon' | 'em-dash' | 'dash' | 'label-colon' | 'emphas
 
 interface WrapOptions {
     /**
-     * Sets whether a line may not end with the first word of a sentence, clause, or parenthetical,
-     * like `This`, `the` after a comma, or `(the`. Such a word moves to the next line instead.
-     * It also sets whether a line avoids ending with the first two words of a sentence, and whether
-     * the first of two lines ends with a sentence instead of the start of the next one, as long as
-     * the second line is then no longer than the first.
+     * Sets whether a line may not end with the first word of a sentence or parenthetical, like
+     * `This` or `(the`, or with the first word after a semicolon or colon. Such a word moves to
+     * the next line instead. The word after a comma may end a line. It also sets whether a line
+     * avoids ending with the first two words of a sentence, and whether the first of two lines
+     * ends with a sentence instead of the start of the next one, as long as the second line is
+     * then no longer than the first.
      */
     readonly avoidSentenceOrphans: boolean;
     /**
@@ -54,9 +55,9 @@ 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 plus `tolerance`,
-     * even past `width`, but never past `maxWidth`. It defaults to `width`.
+     * 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 plus `tolerance`, even past
+     * `width`, but never past `maxWidth`. It defaults to `width`.
      */
     readonly singleLineWidth?: number;
     readonly tabWidth: number;
@@ -84,10 +85,10 @@ interface ParagraphReport {
     readonly reason?: string;
     readonly issues: readonly IssueReport[];
     /**
-     * Holds the exact source lines for `startLine` through `endLine` when the paragraph is
-     * greedily wrapped to the width, or `null` when the paragraph isn't prose, e.g. code,
-     * a table, a diagram, or `@example`. A paragraph that is accepted with the layout for a
-     * wider width within the tolerance keeps its lines.
+     * Holds the exact source lines for `startLine` through `endLine` when the paragraph is greedily
+     * wrapped to the width, or `null` when the paragraph isn't prose, e.g. code, a table, a diagram,
+     * or `@example`. A paragraph that the tolerance accepts as it is, with the layout for a wider
+     * width or with lines close to this one, keeps its lines.
      */
     readonly suggestion: readonly string[] | null;
 }
@@ -228,24 +229,27 @@ interface CommentsConfig {
      * 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 plus `tolerance`, even past
      * `width`, and is wrapped to `width` beyond it. Defaults to 120, and the line never exceeds
-     * `maxWidth`.
+     * the `maxWidth` limit.
      */
     readonly singleLineWidth?: number;
     /**
-     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph of
-     * three or more lines. A paragraph that already has the layout for a wider `width`, up to `width`
-     * plus this many columns, also passes as it is. It never goes past `maxWidth`. When `maxWidth` is
-     * omitted, it also sets a legacy hard limit of `width + tolerance`.
+     * Sets how many columns prose lines may go past `width` when that saves a line in a paragraph
+     * of three or more lines. A paragraph that already has the layout for a wider `width`, up to
+     * `width` plus this many columns, also passes as it is. So does a paragraph with as many lines
+     * as the rewrap whose lines are each at most this many columns shorter or longer than in the
+     * rewrap. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a legacy hard
+     * limit of `width + tolerance`.
      */
     readonly tolerance?: number;
     /**
      * Keep the first word of a new sentence or parenthetical off the end of a line, e.g.
-     * `...the module. This` or `...reflows (the` followed by the rest on the next line.
-     * A paragraph of two lines also ends its first line with a sentence when the rest fits
-     * on the second line and is no longer than the first, instead of with the start of
-     * the next sentence, like `...the module. This one`. Other lines avoid ending with the
-     * first two words of a sentence, like `...opens. It allocates`, unless that makes them
-     * much less even. Defaults to `true`.
+     * `...the module. This` or `...reflows (the` followed by the rest on the next line. The same
+     * goes for the first word after a semicolon or colon, but not after a comma, so a line may
+     * end with `...the paths, and`. A paragraph of two lines also ends its first line with a
+     * sentence when the rest fits on the second line and is no longer than the first, instead
+     * of with the start of the next sentence, like `...the module. This one`. Other lines avoid
+     * ending with the first two words of a sentence, like `...opens. It allocates`, unless that
+     * makes them much less even. Defaults to `true`.
      */
     readonly avoidSentenceOrphans?: boolean;
     /**

package/dist/comments.js

@@ -128,6 +128,7 @@ function findStyleIssues(lines) {
 // src/comments/wrap.ts
 var CLAUSE_END = /[.!?,;:]["')\]*_]*$/;
 var SENTENCE_END = /[.!?]["')\]*_]*$/;
+var STATEMENT_END = /[.!?;:]["')\]*_]*$/;
 var ABBREVIATIONS = /* @__PURE__ */ new Set([
   "e.g.",
   "i.e.",
@@ -359,8 +360,8 @@ function bindParentheticals(tokens, limit) {
   }
   return units;
 }
-function endsClause(token) {
-  return CLAUSE_END.test(token) && !isAbbreviation(token);
+function endsStatement(token) {
+  return STATEMENT_END.test(token) && !isAbbreviation(token);
 }
 function endsSentence(token) {
   return SENTENCE_END.test(token) && !isAbbreviation(token);
@@ -369,7 +370,7 @@ function opensAside(token) {
   return /^[([]/.test(token) && !/[)\]]["'`.,;:!?]*$/.test(token);
 }
 function isOrphan(previous, token) {
-  return opensAside(token) || endsClause(previous) && !CLAUSE_END.test(token);
+  return opensAside(token) || endsStatement(previous) && !CLAUSE_END.test(token);
 }
 function startsBlock(token) {
   return /^(?:\+|-+|=+|\*+|_{3,}|\d+[.)]|#{1,6})$/.test(token) || /^(?:>|@[A-Za-z]|`{3}|~{3}|\||<(?:\/?[A-Za-z]|[!?]))/.test(token);
@@ -1383,7 +1384,20 @@ function analyzeParagraph(paragraph, options, language) {
     }
     return false;
   };
-  const accepted = lineIssues.some((issue) => isVerdict(issue)) && matchesWiderLayout();
+  const staysNearLayout = () => {
+    if (currentLines.length !== wrapped.length || splitTokenLine(currentLines, units) !== -1) {
+      return false;
+    }
+    return currentLines.every((words, position) => {
+      const length = words.join(" ").length;
+      const suggestedLength = wrapped[position].join(" ").length;
+      const limit = (position === 0 ? firstLimit : restLimit) + layoutOptions.tolerance;
+      return Math.abs(length - suggestedLength) <= layoutOptions.tolerance && length <= Math.max(suggestedLength, limit);
+    });
+  };
+  const hasVerdict = lineIssues.some((issue) => isVerdict(issue));
+  const onlyUnbalanced = lineIssues.every((issue) => issue.type === "unbalanced");
+  const accepted = hasVerdict && (matchesWiderLayout() || onlyUnbalanced && staysNearLayout());
   const suggested = accepted ? currentLines : wrapped;
   const suggestion = suggested.map(
     (words, position) => `${prefix}${position === 0 ? paragraph.marker : hang}${words.join(" ")}`
@@ -1730,7 +1744,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, 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. The same goes for the first two words of a sentence, like \`It allocates\` after a period, when the note points at them. 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.
+- Don't end a line with the first word of a new sentence or parenthetical, like \`This\` after a period or \`(the\`, or with the first word after a semicolon or colon. Move it to the next line instead. The same goes for the first two words of a sentence, like \`It allocates\` after a period, when the note points at them. 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. The word after a comma is no such word. A line may end with it, like \`and\` in \`...the teardown paths, and\`.
 - 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.