@d3lm/lint-preset 1.5.5 → 1.6.0

package/dist/comments.d.cts

@@ -10,8 +10,8 @@ interface WrapOptions {
      */
     readonly avoidSentenceOrphans: boolean;
     /**
-     * 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.
+     * Sets how many columns a line may exceed its limit before it counts as overflowing.
+     * A layout also uses those columns when that saves a line.
      */
     readonly tolerance: number;
     /**
@@ -21,7 +21,13 @@ interface WrapOptions {
 }
 type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced' | 'split-parenthetical';
 /**
- * JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay intact like code spans.
+ * Splits text into words. JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay
+ * intact like code spans.
+ *
+ * A Markdown link stays intact too, since a link that continues on the next line can't be followed
+ * in an editor. rust-analyzer, for one, only resolves an intra-doc link that sits on one line of
+ * a `///` comment. A link is one word, like a code span, but its own words keep one space between
+ * them, like the words around it.
  */
 declare function tokenize(text: string): string[];
 /**
@@ -30,7 +36,12 @@ declare function tokenize(text: string): string[];
  */
 declare function wrapTokens(tokens: readonly string[], firstLimit: number, restLimit: number, options: WrapOptions): string[][];
 
-type CommentKind = 'jsdoc' | 'block';
+/**
+ * Describes the syntax of a comment. Rust has doc comments for the item after them (`outer`, like `///` and `/**`)
+ * and for the item that holds them (`inner`, like `//!` and `/*!`). A `line` comment is a run of plain line comments
+ * (`//`), which is never rewrapped.
+ */
+type CommentKind = 'jsdoc' | 'block' | 'line' | 'outer-line-doc' | 'inner-line-doc' | 'outer-block-doc' | 'inner-block-doc';
 type ParagraphKind = 'prose' | 'list' | 'tag' | 'code' | 'other';
 interface AnalyzeOptions extends WrapOptions {
     /**
@@ -75,7 +86,8 @@ interface ParagraphReport {
     /**
      * 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 table, a diagram, or `@example`. A paragraph that is accepted with the layout for a
+     * wider width within the tolerance keeps its lines.
      */
     readonly suggestion: readonly string[] | null;
 }
@@ -95,9 +107,12 @@ interface CommentReport {
     readonly paragraphs: readonly ParagraphReport[];
 }
 /**
- * Finds all own-line block and JSDoc comments in a JavaScript or TypeScript source file and reports
- * how each paragraph deviates from a greedy wrap at `options.width`. Line comments (`//`) are never
- * analyzed. A source with a syntax error that stops the parser has no reports.
+ * Finds all own-line block and JSDoc comments in a JavaScript or TypeScript source file, or block
+ * and doc comments in a Rust source file (`.rs`), and reports how each paragraph deviates from a
+ * greedy wrap at `options.width`. A run of Rust line doc comments (`///` or `//!`) counts as one
+ * comment. A run of other line comments (`//`) on their own lines is never rewrapped, and it is
+ * only reported when a line is longer than the maximum. A source with a syntax error that stops
+ * the parser has no reports.
  */
 declare function analyzeSource(source: string, filename: string, options: AnalyzeOptions): CommentReport[];
 /**
@@ -115,16 +130,17 @@ declare function hasVerdictIssues(report: CommentReport): boolean;
  */
 declare function rewrapComment(report: CommentReport): string;
 /**
- * Returns the syntax tree of the source as JSON, without positions or comments, used to verify
- * that only comments changed. Moving or rewording a comment keeps it the same, while any change
- * to a string, template, regex, JSX text, or where a statement ends changes it. A source that
- * doesn't parse has no tree to compare, so all of its text counts.
+ * Returns the syntax tree of the source as JSON, without positions or comments, used to verify that
+ * only comments changed. Moving or rewording a comment leaves the tree the same, while any change to
+ * a string, template, regex, JSX text, or where a statement ends changes it. A source that doesn't
+ * parse has no tree to compare, so all of its text counts. A Rust source is compared by its tokens
+ * instead, with each run of doc comments as one marker (see `rustFingerprint`).
  */
 declare function codeFingerprint(source: string, filename: string): string;
 
 type AgentRunner = 'claude' | 'codex' | 'cursor';
 type HookMode = 'agent' | 'report' | 'off';
-type AgentScope = 'suspicious' | 'all';
+type AgentScope = 'suspicious' | 'failing' | 'all';
 interface AgentConfig {
     /**
      * Names the agent CLI to spawn. Defaults to the host that triggered the hook, or `claude`
@@ -179,8 +195,10 @@ interface AgentConfig {
      * Selects which comments the agent sees. `suspicious` (default) is a triage, not a full review.
      * It only sends comments with hints, like a possible semicolon or a line that may end with the
      * first word of a sentence, and comments with issues in parts the tool never rewraps, so most
-     * runs never call the agent. The tool fixes the layout of prose itself. `all` sends every comment
-     * in changed lines, so that the agent reviews the wording of each against its rules.
+     * runs never call the agent. The tool fixes the layout of prose itself. `failing` sends only
+     * the comments with verdicts, the ones that fail `comments check`, and no comment that only has
+     * hints. `all` sends every comment in changed lines, so that the agent reviews the wording of
+     * each against its rules.
      */
     readonly scope?: AgentScope;
 }
@@ -196,8 +214,9 @@ interface HookConfig {
 }
 interface CommentsConfig {
     /**
-     * Sets the preferred line length for comments, including indentation and the comment prefix.
-     * Defaults to prettier's `printWidth`, or 80.
+     * Sets the preferred line length for comments, including indentation and the comment
+     * prefix. Defaults to prettier's `printWidth`, or 80. In Rust files, it defaults to
+     * rustfmt's `comment_width` instead, which is 80 by default too.
      */
     readonly width?: number;
     /**
@@ -214,8 +233,9 @@ interface CommentsConfig {
     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. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a
-     * legacy hard limit of `width + tolerance`.
+     * 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`.
      */
     readonly tolerance?: number;
     /**
@@ -236,9 +256,15 @@ interface CommentsConfig {
      */
     readonly style?: boolean;
     /**
-     * Lists the file extensions to process. Defaults to JavaScript and TypeScript extensions.
+     * Lists the file extensions to process. Defaults to JavaScript, TypeScript, and Rust extensions.
      */
     readonly extensions?: readonly string[];
+    /**
+     * Lists glob patterns, relative to the repository root, of the only files to process.
+     * Without patterns, every file with one of the `extensions` is processed. `ignore` still
+     * skips files that match both.
+     */
+    readonly include?: readonly string[];
     /**
      * Lists glob patterns, relative to the repository root, of files to skip.
      */

package/dist/comments.d.ts

@@ -10,8 +10,8 @@ interface WrapOptions {
      */
     readonly avoidSentenceOrphans: boolean;
     /**
-     * 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.
+     * Sets how many columns a line may exceed its limit before it counts as overflowing.
+     * A layout also uses those columns when that saves a line.
      */
     readonly tolerance: number;
     /**
@@ -21,7 +21,13 @@ interface WrapOptions {
 }
 type LineIssueType = 'overflow' | 'underfill' | 'orphan' | 'widow' | 'unbalanced' | 'split-parenthetical';
 /**
- * JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay intact like code spans.
+ * Splits text into words. JSDoc writes types and `{@link ...}` tags as `{...}` groups, so they stay
+ * intact like code spans.
+ *
+ * A Markdown link stays intact too, since a link that continues on the next line can't be followed
+ * in an editor. rust-analyzer, for one, only resolves an intra-doc link that sits on one line of
+ * a `///` comment. A link is one word, like a code span, but its own words keep one space between
+ * them, like the words around it.
  */
 declare function tokenize(text: string): string[];
 /**
@@ -30,7 +36,12 @@ declare function tokenize(text: string): string[];
  */
 declare function wrapTokens(tokens: readonly string[], firstLimit: number, restLimit: number, options: WrapOptions): string[][];
 
-type CommentKind = 'jsdoc' | 'block';
+/**
+ * Describes the syntax of a comment. Rust has doc comments for the item after them (`outer`, like `///` and `/**`)
+ * and for the item that holds them (`inner`, like `//!` and `/*!`). A `line` comment is a run of plain line comments
+ * (`//`), which is never rewrapped.
+ */
+type CommentKind = 'jsdoc' | 'block' | 'line' | 'outer-line-doc' | 'inner-line-doc' | 'outer-block-doc' | 'inner-block-doc';
 type ParagraphKind = 'prose' | 'list' | 'tag' | 'code' | 'other';
 interface AnalyzeOptions extends WrapOptions {
     /**
@@ -75,7 +86,8 @@ interface ParagraphReport {
     /**
      * 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 table, a diagram, or `@example`. A paragraph that is accepted with the layout for a
+     * wider width within the tolerance keeps its lines.
      */
     readonly suggestion: readonly string[] | null;
 }
@@ -95,9 +107,12 @@ interface CommentReport {
     readonly paragraphs: readonly ParagraphReport[];
 }
 /**
- * Finds all own-line block and JSDoc comments in a JavaScript or TypeScript source file and reports
- * how each paragraph deviates from a greedy wrap at `options.width`. Line comments (`//`) are never
- * analyzed. A source with a syntax error that stops the parser has no reports.
+ * Finds all own-line block and JSDoc comments in a JavaScript or TypeScript source file, or block
+ * and doc comments in a Rust source file (`.rs`), and reports how each paragraph deviates from a
+ * greedy wrap at `options.width`. A run of Rust line doc comments (`///` or `//!`) counts as one
+ * comment. A run of other line comments (`//`) on their own lines is never rewrapped, and it is
+ * only reported when a line is longer than the maximum. A source with a syntax error that stops
+ * the parser has no reports.
  */
 declare function analyzeSource(source: string, filename: string, options: AnalyzeOptions): CommentReport[];
 /**
@@ -115,16 +130,17 @@ declare function hasVerdictIssues(report: CommentReport): boolean;
  */
 declare function rewrapComment(report: CommentReport): string;
 /**
- * Returns the syntax tree of the source as JSON, without positions or comments, used to verify
- * that only comments changed. Moving or rewording a comment keeps it the same, while any change
- * to a string, template, regex, JSX text, or where a statement ends changes it. A source that
- * doesn't parse has no tree to compare, so all of its text counts.
+ * Returns the syntax tree of the source as JSON, without positions or comments, used to verify that
+ * only comments changed. Moving or rewording a comment leaves the tree the same, while any change to
+ * a string, template, regex, JSX text, or where a statement ends changes it. A source that doesn't
+ * parse has no tree to compare, so all of its text counts. A Rust source is compared by its tokens
+ * instead, with each run of doc comments as one marker (see `rustFingerprint`).
  */
 declare function codeFingerprint(source: string, filename: string): string;
 
 type AgentRunner = 'claude' | 'codex' | 'cursor';
 type HookMode = 'agent' | 'report' | 'off';
-type AgentScope = 'suspicious' | 'all';
+type AgentScope = 'suspicious' | 'failing' | 'all';
 interface AgentConfig {
     /**
      * Names the agent CLI to spawn. Defaults to the host that triggered the hook, or `claude`
@@ -179,8 +195,10 @@ interface AgentConfig {
      * Selects which comments the agent sees. `suspicious` (default) is a triage, not a full review.
      * It only sends comments with hints, like a possible semicolon or a line that may end with the
      * first word of a sentence, and comments with issues in parts the tool never rewraps, so most
-     * runs never call the agent. The tool fixes the layout of prose itself. `all` sends every comment
-     * in changed lines, so that the agent reviews the wording of each against its rules.
+     * runs never call the agent. The tool fixes the layout of prose itself. `failing` sends only
+     * the comments with verdicts, the ones that fail `comments check`, and no comment that only has
+     * hints. `all` sends every comment in changed lines, so that the agent reviews the wording of
+     * each against its rules.
      */
     readonly scope?: AgentScope;
 }
@@ -196,8 +214,9 @@ interface HookConfig {
 }
 interface CommentsConfig {
     /**
-     * Sets the preferred line length for comments, including indentation and the comment prefix.
-     * Defaults to prettier's `printWidth`, or 80.
+     * Sets the preferred line length for comments, including indentation and the comment
+     * prefix. Defaults to prettier's `printWidth`, or 80. In Rust files, it defaults to
+     * rustfmt's `comment_width` instead, which is 80 by default too.
      */
     readonly width?: number;
     /**
@@ -214,8 +233,9 @@ interface CommentsConfig {
     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. It never goes past `maxWidth`. When `maxWidth` is omitted, it also sets a
-     * legacy hard limit of `width + tolerance`.
+     * 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`.
      */
     readonly tolerance?: number;
     /**
@@ -236,9 +256,15 @@ interface CommentsConfig {
      */
     readonly style?: boolean;
     /**
-     * Lists the file extensions to process. Defaults to JavaScript and TypeScript extensions.
+     * Lists the file extensions to process. Defaults to JavaScript, TypeScript, and Rust extensions.
      */
     readonly extensions?: readonly string[];
+    /**
+     * Lists glob patterns, relative to the repository root, of the only files to process.
+     * Without patterns, every file with one of the `extensions` is processed. `ignore` still
+     * skips files that match both.
+     */
+    readonly include?: readonly string[];
     /**
      * Lists glob patterns, relative to the repository root, of files to skip.
      */