@herb-tools/linter 0.7.4 → 0.8.0

package/dist/types/types.d.ts

@@ -1,24 +1,76 @@
 import { Diagnostic, LexResult, ParseResult } from "@herb-tools/core";
-import type { defaultRules } from "./default-rules.js";
+import type { rules } from "./rules.js";
+import type { Node } from "@herb-tools/core";
+import type { RuleConfig } from "@herb-tools/config";
+import type { Mutable } from "@herb-tools/rewriter";
+export type { Mutable } from "@herb-tools/rewriter";
 export type LintSeverity = "error" | "warning" | "info" | "hint";
+export type FullRuleConfig = Required<Pick<RuleConfig, 'enabled' | 'severity'>> & Omit<RuleConfig, 'enabled' | 'severity'>;
 /**
  * Automatically inferred union type of all available linter rule names.
  * This type extracts the 'name' property from each rule class instance.
  */
-export type LinterRule = InstanceType<typeof defaultRules[number]>['name'];
-export interface LintOffense extends Diagnostic {
+export type LinterRule = InstanceType<typeof rules[number]>['name'];
+/**
+ * Base context for autofix operations. Contains the offending node.
+ * Rules can extend this interface to include rule-specific autofix data.
+ * Note: The node is typed as Mutable to allow direct mutation in autofix methods.
+ */
+export interface BaseAutofixContext {
+    /** The AST node, token, or data structure that caused the offense (mutable) */
+    node: Mutable<Node>;
+}
+/**
+ * A lint offense without severity bound. Rules produce these, and the Linter
+ * binds severity based on the rule's defaultConfig and user config overrides.
+ */
+export interface UnboundLintOffense<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> extends Omit<Diagnostic, 'severity'> {
     rule: LinterRule;
+    /** Context data for autofix, including the offending node and rule-specific data */
+    autofixContext?: TAutofixContext;
+}
+/**
+ * A lint offense with severity bound. The Linter produces these by binding
+ * severity to UnboundLintOffenses based on rule configuration.
+ */
+export interface LintOffense<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> extends UnboundLintOffense<TAutofixContext> {
     severity: LintSeverity;
 }
-export interface LintResult {
-    offenses: LintOffense[];
+export interface LintResult<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
+    offenses: LintOffense<TAutofixContext>[];
     errors: number;
     warnings: number;
+    info: number;
+    hints: number;
+    ignored: number;
+    wouldBeIgnored?: number;
+}
+/**
+ * Result of applying autofixes to source code
+ */
+export interface AutofixResult<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
+    /** The corrected source code with all fixes applied */
+    source: string;
+    /** Offenses that were successfully fixed */
+    fixed: LintOffense<TAutofixContext>[];
+    /** Offenses that could not be automatically fixed */
+    unfixed: LintOffense<TAutofixContext>[];
 }
-export declare abstract class ParserRule {
+/**
+ * Default configuration for rules when defaultConfig is not specified.
+ * Custom rules can omit defaultConfig and will use these defaults.
+ */
+export declare const DEFAULT_RULE_CONFIG: FullRuleConfig;
+/**
+ * Base class for parser rules.
+ */
+export declare abstract class ParserRule<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
     static type: "parser";
+    /** Indicates whether this rule supports autofix. Defaults to false. */
+    static autocorrectable: boolean;
     abstract name: string;
-    abstract check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+    get defaultConfig(): FullRuleConfig;
+    abstract check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
     /**
      * Optional method to determine if this rule should run.
      * If not implemented, rule is always enabled.
@@ -27,11 +79,26 @@ export declare abstract class ParserRule {
      * @returns true if rule should run, false to skip
      */
     isEnabled?(result: ParseResult, context?: Partial<LintContext>): boolean;
+    /**
+     * Optional method to automatically fix an offense by mutating the AST.
+     * If not implemented, the rule does not support autofix.
+     * @param offense - The offense to fix (includes autofixContext with node and rule-specific data)
+     * @param result - The parse result containing the AST (mutate it directly and return it)
+     * @param context - Optional context for linting
+     * @returns The mutated ParseResult if fixed, or null if the offense could not be fixed
+     */
+    autofix?(offense: LintOffense<TAutofixContext>, result: ParseResult, context?: Partial<LintContext>): ParseResult | null;
 }
-export declare abstract class LexerRule {
+/**
+ * Base class for lexer rules.
+ */
+export declare abstract class LexerRule<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
     static type: "lexer";
+    /** Indicates whether this rule supports autofix. Defaults to false. */
+    static autocorrectable: boolean;
     abstract name: string;
-    abstract check(lexResult: LexResult, context?: Partial<LintContext>): LintOffense[];
+    get defaultConfig(): FullRuleConfig;
+    abstract check(lexResult: LexResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
     /**
      * Optional method to determine if this rule should run.
      * If not implemented, rule is always enabled.
@@ -40,6 +107,15 @@ export declare abstract class LexerRule {
      * @returns true if rule should run, false to skip
      */
     isEnabled?(lexResult: LexResult, context?: Partial<LintContext>): boolean;
+    /**
+     * Optional method to automatically fix an offense by mutating tokens.
+     * If not implemented, the rule does not support autofix.
+     * @param offense - The offense to fix (includes autofixContext with node and rule-specific data)
+     * @param lexResult - The lex result containing tokens (mutate them directly and return)
+     * @param context - Optional context for linting
+     * @returns The mutated LexResult if fixed, or null if the offense could not be fixed
+     */
+    autofix?(offense: LintOffense<TAutofixContext>, lexResult: LexResult, context?: Partial<LintContext>): LexResult | null;
 }
 export interface LexerRuleConstructor {
     type: "lexer";
@@ -51,15 +127,21 @@ export interface LexerRuleConstructor {
  */
 export interface LintContext {
     fileName: string | undefined;
+    validRuleNames: string[] | undefined;
+    ignoredOffensesByLine: Map<number, Set<string>> | undefined;
+    ignoreDisableComments: boolean | undefined;
 }
 /**
  * Default context object with all keys defined but set to undefined
  */
 export declare const DEFAULT_LINT_CONTEXT: LintContext;
-export declare abstract class SourceRule {
+export declare abstract class SourceRule<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
     static type: "source";
+    /** Indicates whether this rule supports autofix. Defaults to false. */
+    static autocorrectable: boolean;
     abstract name: string;
-    abstract check(source: string, context?: Partial<LintContext>): LintOffense[];
+    get defaultConfig(): FullRuleConfig;
+    abstract check(source: string, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
     /**
      * Optional method to determine if this rule should run.
      * If not implemented, rule is always enabled.
@@ -68,6 +150,15 @@ export declare abstract class SourceRule {
      * @returns true if rule should run, false to skip
      */
     isEnabled?(source: string, context?: Partial<LintContext>): boolean;
+    /**
+     * Optional method to automatically fix an offense.
+     * If not implemented, the rule does not support autofix.
+     * @param offense - The offense to fix (includes autofixContext with node and rule-specific data)
+     * @param source - The original source code
+     * @param context - Optional context for linting
+     * @returns The corrected source if the offense can be fixed, null otherwise
+     */
+    autofix?(offense: LintOffense<TAutofixContext>, source: string, context?: Partial<LintContext>): string | null;
 }
 export interface SourceRuleConstructor {
     type: "source";

package/docs/rules/README.md

@@ -4,12 +4,23 @@ This page contains documentation for all Herb Linter rules.
 
 ## Available Rules
 
+- [`erb-comment-syntax`](./erb-comment-syntax.md) - Disallow Ruby comments immediately after ERB tags
+- [`erb-no-case-node-children`](./erb-no-case-node-children.md) - Don't use `children` for `case/when` and `case/in` nodes
 - [`erb-no-empty-tags`](./erb-no-empty-tags.md) - Disallow empty ERB tags
+- [`erb-no-extra-newline`](./erb-no-extra-newline.md) - Disallow extra newlines.
+- [`erb-no-extra-whitespace-inside-tags`](./erb-no-extra-whitespace-inside-tags.md) - Disallow multiple consecutive spaces inside ERB tags
 - [`erb-no-output-control-flow`](./erb-no-output-control-flow.md) - Prevents outputting control flow blocks
 - [`erb-no-silent-tag-in-attribute-name`](./erb-no-silent-tag-in-attribute-name.md) - Disallow ERB silent tags in HTML attribute names
 - [`erb-prefer-image-tag-helper`](./erb-prefer-image-tag-helper.md) - Prefer `image_tag` helper over `<img>` with ERB expressions
 - [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around ERB tags
-- [`erb-requires-trailing-newline`](./erb-requires-trailing-newline.md) - Enforces that all HTML+ERB template files end with exactly one trailing newline character.
+- [`erb-require-trailing-newline`](./erb-require-trailing-newline.md) - Enforces that all HTML+ERB template files end with exactly one trailing newline character.
+- [`erb-right-trim`](./erb-right-trim.md) - Enforce consistent right-trimming syntax.
+- [`herb-disable-comment-malformed`](./herb-disable-comment-malformed.md) - Detect malformed `herb:disable` comments.
+- [`herb-disable-comment-missing-rules`](./herb-disable-comment-missing-rules.md) - Require rule names in `herb:disable` comments.
+- [`herb-disable-comment-no-duplicate-rules`](./herb-disable-comment-no-duplicate-rules.md) - Disallow duplicate rule names in `herb:disable` comments.
+- [`herb-disable-comment-no-redundant-all`](./herb-disable-comment-no-redundant-all.md) - Disallow redundant use of `all` in `herb:disable` comments.
+- [`herb-disable-comment-unnecessary`](./herb-disable-comment-unnecessary.md) - Detect unnecessary `herb:disable` comments.
+- [`herb-disable-comment-valid-rule-name`](./herb-disable-comment-valid-rule-name.md) - Validate rule names in `herb:disable` comments.
 - [`html-anchor-require-href`](./html-anchor-require-href.md) - Requires an href attribute on anchor tags
 - [`html-aria-attribute-must-be-valid`](./html-aria-attribute-must-be-valid.md) - Disallow invalid or unknown `aria-*` attributes.
 - [`html-aria-label-is-well-formatted`](./html-aria-label-is-well-formatted.md) - `aria-label` must be well-formatted
@@ -20,21 +31,26 @@ This page contains documentation for all Herb Linter rules.
 - [`html-attribute-equals-spacing`](./html-attribute-equals-spacing.md) - No whitespace around `=` in HTML attributes
 - [`html-attribute-values-require-quotes`](./html-attribute-values-require-quotes.md) - Requires quotes around attribute values
 - [`html-avoid-both-disabled-and-aria-disabled`](./html-avoid-both-disabled-and-aria-disabled.md) - Avoid using both `disabled` and `aria-disabled` attributes
+- [`html-body-only-elements`](./html-body-only-elements.md) - Require content elements inside `<body>`.
 - [`html-boolean-attributes-no-value`](./html-boolean-attributes-no-value.md) - Prevents values on boolean attributes
+- [`html-head-only-elements`](./html-head-only-elements.md) - Require head-scoped elements inside `<head>`.
 - [`html-iframe-has-title`](./html-iframe-has-title.md) - `iframe` elements must have a `title` attribute
+- [`html-input-require-autocomplete`](./html-input-require-autocomplete.md) - Require `autocomplete` attributes on `<input>` tags.
 - [`html-img-require-alt`](./html-img-require-alt.md) - Requires `alt` attributes on `<img>` tags
 - [`html-navigation-has-label`](./html-navigation-has-label.md) - Navigation landmarks must have accessible labels
 - [`html-no-aria-hidden-on-focusable`](./html-no-aria-hidden-on-focusable.md) - Focusable elements should not have `aria-hidden="true"`
 - [`html-no-block-inside-inline`](./html-no-block-inside-inline.md) - Prevents block-level elements inside inline elements
 - [`html-no-duplicate-attributes`](./html-no-duplicate-attributes.md) - Prevents duplicate attributes on HTML elements
 - [`html-no-duplicate-ids`](./html-no-duplicate-ids.md) - Prevents duplicate IDs within a document
+- [`html-no-duplicate-meta-names`](./html-no-duplicate-meta-names.md) - Duplicate `<meta>` name attributes are not allowed.
 - [`html-no-empty-attributes`](./html-no-empty-attributes.md) - Attributes must not have empty values
 - [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
 - [`html-no-positive-tab-index`](./html-no-positive-tab-index.md) - Avoid positive `tabindex` values
-- [`html-no-self-closing`](./html-no-self-closing.md.md) - Disallow self closing tags
+- [`html-no-self-closing`](./html-no-self-closing.md) - Disallow self closing tags
+- [`html-no-space-in-tag`](./html-no-space-in-tag.md) - Disallow spaces in HTML tags
 - [`html-no-title-attribute`](./html-no-title-attribute.md) - Avoid using the `title` attribute
-- [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
 - [`html-no-underscores-in-attribute-names`](./html-no-underscores-in-attribute-names.md) - Disallow underscores in HTML attribute names
+- [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
 - [`parser-no-errors`](./parser-no-errors.md) - Disallow parser errors in HTML+ERB documents
 - [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements
 

package/docs/rules/erb-comment-syntax.md

@@ -0,0 +1,44 @@
+# Linter Rule: Disallow Ruby comments immediately after ERB tags
+
+**Rule:** `erb-comment-syntax`
+
+## Description
+
+Disallow ERB tags that start with `<% #` (with a space before the `#`). Use the ERB comment syntax `<%#` instead.
+
+## Rationale
+
+Ruby comments starting immediately after an ERB tag opening (e.g., `<% # comment %>`) can cause parsing issues in some contexts. The proper ERB comment syntax `<%# comment %>` is more reliable and explicitly designed for comments in templates.
+
+For multi-line comments or actual Ruby code with comments, ensure the content starts on a new line after the opening tag.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%# This is a proper ERB comment %>
+
+<%
+  # This is a proper ERB comment
+%>
+
+<%
+  # Multi-line Ruby comment
+  # spanning multiple lines
+%>
+```
+
+### 🚫 Bad
+
+```erb
+<% # This should be an ERB comment %>
+
+<%= # This should also be an ERB comment %>
+
+<%== # This should also be an ERB comment %>
+```
+
+## References
+
+- [Inspiration: ERB Lint `CommentSyntax` rule](https://github.com/shopify/erb_lint?tab=readme-ov-file#commentsyntax)

package/docs/rules/erb-no-case-node-children.md

@@ -0,0 +1,50 @@
+# Linter Rule: Don't use `children` for `case/when` and `case/in` nodes
+
+**Rule:** `erb-no-case-node-children`
+
+## Description
+
+Disallow placing content or expressions directly between the opening `<% case %>` and the first `<% when %>` or `<% in %>` clause in an HTML+ERB template.
+
+In Ruby and ERB, `case` expressions are intended to branch execution. Any content placed between the `case` and its `when`/`in` clauses is not executed as part of the branching logic, and may lead to confusion, orphaned output, or silent bugs.
+
+## Rationale
+
+Including content directly inside a `case block` is likely unintended and often leads to unclear or broken rendering logic.
+
+Most developers expect that nothing happens until the first `when`/`in` matches. Content in that location is often a copy/paste or indentation mistake and should be flagged to maintain clarity and correctness in templates.
+
+This mirrors how `case` works in Ruby itself and helps avoid surprising output.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<% case variable %>
+<% when "a" %>
+  A
+<% when "b" %>
+  B
+<% else %>
+  C
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<% case variable %>
+  This content is outside of any when/in/else block!
+<% when "a" %>
+  A
+<% when "b" %>
+  B
+<% else %>
+  C
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-extra-newline.md

@@ -0,0 +1,74 @@
+# Linter Rule: Disallow extra newlines
+
+**Rule:** `erb-no-extra-newline`
+
+## Description
+
+Disallow more than two consecutive blank lines in ERB templates. This rule enforces a maximum of two blank lines between content to maintain consistent vertical spacing throughout your templates.
+
+## Rationale
+
+Excessive blank lines can make templates harder to read and maintain. While some vertical spacing improves readability by visually separating logical sections, too many blank lines create unnecessary whitespace that:
+
+* Makes it harder to see related code on the same screen
+* Creates inconsistent visual rhythm in the codebase
+* Can accidentally accumulate through merge conflicts or refactoring
+* Provides no additional clarity beyond what 1-2 blank lines already achieve
+
+Limiting to two consecutive blank lines strikes a balance between allowing clear section separation while maintaining code density and readability.
+
+## Examples
+
+### ✅ Good
+
+```html
+line 1
+
+line 3
+
+<div>
+  <h1>Title</h1>
+</div>
+
+<div>
+  <h1>Section 1</h1>
+
+  <p>Content here</p>
+</div>
+
+<div>
+  <h1>Section 1</h1>
+
+
+  <h1>Section 2</h1>
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+line 1
+
+
+
+line 3
+
+<div>
+  <h1>Title</h1>
+
+
+
+  <p>Content</p>
+</div>
+
+<%= user.name %>
+
+
+
+
+<%= user.email %>
+```
+
+## References
+
+- [Inspiration: ERB Lint `ExtraNewline` rule](https://github.com/Shopify/erb_lint/blob/main/README.md)

package/docs/rules/erb-no-extra-whitespace-inside-tags.md

@@ -0,0 +1,39 @@
+# Linter Rule: Avoid extra whitespace inside ERB tags
+
+**Rule:** `erb-no-extra-whitespace-inside-tags`
+
+## Description
+
+This rule disallows **multiple consecutive spaces** immediately inside ERB tags (`<%`, `<%=`) or before the closing delimiter (`%>`). It ensures that ERB code is consistently and cleanly formatted, with exactly one space after the opening tag and one space before the closing tag (when appropriate).
+
+## Rationale
+
+Excess whitespace inside ERB tags can lead to inconsistent formatting and untidy templates. By enforcing a consistent amount of whitespace inside ERB tags, this rule improves code readability, aligns with the formatter and style guide expectations, and avoids unnecessary visual noise.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= output %>
+
+<% if condition %>
+  True
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<%=  output %>
+
+<%= output  %>
+
+<%  if condition  %>
+  True
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/{erb-requires-trailing-newline.md → erb-require-trailing-newline.md}

@@ -1,6 +1,6 @@
 # Linter Rule: Enforce trailing newline
 
-**Rule:** `erb-requires-trailing-newline`
+**Rule:** `erb-require-trailing-newline`
 
 ## Description
 

package/docs/rules/erb-right-trim.md

@@ -0,0 +1,52 @@
+# Linter Rule: Enforce consistent right-trimming syntax
+
+**Rule:** `erb-right-trim`
+
+## Description
+
+This rule enforces the use of `-%>` for right-trimming ERB output tags (like `<%= %>`) instead of `=%>`.
+
+## Rationale
+
+While `=%>` can be used for right-trimming whitespace in some ERB engines (like Erubi), it is an obscure and not well-defined syntax that lacks consistent support across most ERB implementations.
+
+The `-%>` syntax is the standard, well-documented approach for right-trimming that is universally supported and consistent with left-trimming syntax (`<%-`). Using `-%>` ensures compatibility across different ERB engines, improves code clarity, and aligns with established Rails and ERB conventions.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= title -%>
+
+<% if condition? %>
+  <h1>Content</h1>
+<% end %>
+
+<% items.each do |item| %>
+  <li><%= item -%></li>
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<%= title =%>
+
+
+<% title =%>
+
+
+<% if true =%>
+  <h1>Content</h1>
+<% end %>
+
+
+<% items.each do |item| =%>
+  <li><%= item %></li>
+<% end %>
+```
+
+## References
+
+- [Inspiration: ERB Lint `RightTrim` rule](https://github.com/Shopify/erb_lint/blob/main/README.md#righttrim)

package/docs/rules/herb-disable-comment-malformed.md

@@ -0,0 +1,45 @@
+# Linter Rule: Detect malformed `herb:disable` comments
+
+**Rule:** `herb-disable-comment-malformed`
+
+## Description
+
+Detects malformed `<%# herb:disable ... %>` comments that have syntax errors like trailing commas, leading commas, consecutive commas, or missing spaces after `herb:disable`.
+
+## Rationale
+
+Malformed `<%# herb:disable ... %>` comments can fail to parse correctly, leading to unexpected behavior where rules aren't actually disabled. This rule catches common syntax errors to ensure your disable comments work as intended.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase , html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable html-tag-name-lowercase, %>
+
+<div>test</div> <%# herb:disable , html-tag-name-lowercase %>
+
+<div>test</div> <%# herb:disable html-tag-name-lowercase,, html-attribute-double-quotes %>
+
+<div>test</div> <%# herb:disable html-tag-name-lowercase,, %>
+
+<DIV>test</DIV> <%# herb:disableall %>
+
+<DIV>test</DIV> <%# herb:disablehtml-tag-name-lowercase %>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-missing-rules.md

@@ -0,0 +1,60 @@
+# Linter Rule: Require rule names in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-missing-rules`
+
+## Description
+
+Requires that `<%# herb:disable %>` comments specify either `all` or at least one specific rule name.
+
+## Rationale
+
+A `<%# herb:disable %>` comment without any rule names serves no purpose and likely indicates an incomplete edit or mistake. The developer either:
+
+- Forgot to specify which rules to disable
+- Intended to use `herb:disable all` but forgot to add `all`
+- Started typing a comment but didn't finish
+
+This rule ensures all `<%# herb:disable %>` comments are complete and functional.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable all %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable %>
+
+<div>test</div> <%# herb:disable   %>
+```
+
+## Fix
+
+Add either `all` or specific rule names:
+
+**Option 1:** Disable all rules
+```erb
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+**Option 2:** Disable specific rules
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+```
+
+**Option 3:** Remove the comment if it's not needed
+```erb
+<div>test</div>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-no-duplicate-rules.md

@@ -0,0 +1,49 @@
+# Linter Rule: Disallow duplicate rule names in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-no-duplicate-rules`
+
+## Description
+
+Prevents listing the same rule name multiple times in a `<%# herb:disable ... %>` comment.
+
+## Rationale
+
+Listing a rule name more than once in a `<%# herb:disable ... %>` comment is unnecessary and likely indicates a copy-paste error or mistake. Each rule only needs to be mentioned once to be disabled.
+
+This rule helps keep disable comments clean and prevents confusion about which rules are being disabled.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase, html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-attribute-double-quotes, html-tag-name-lowercase, html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-tag-name-lowercase, html-attribute-double-quotes, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all, all %>
+```
+
+## Fix
+
+Remove the duplicate rule names, keeping only one instance of each:
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+## References
+
+\-