@herb-tools/linter 0.7.5 → 0.8.0

package/README.md

@@ -30,11 +30,6 @@ bun add -g @herb-tools/linter
 
 :::
 
-Then run directly:
-```bash
-herb-lint template.html.erb
-```
-
 ### One-time Usage
 For occasional use without installing:
 ```bash
@@ -63,11 +58,33 @@ bun add -D @herb-tools/linter
 
 :::
 
-After installing as a dev dependency, add a lint NPM script to your `package.json`:
-```json
+After installing as a dev dependency, initialize the configuration:
+
+:::code-group
+
+```shell [npm]
+npx herb-lint --init
+```
+
+```shell [pnpm]
+pnpm herb-lint --init
+```
+
+```shell [yarn]
+yarn herb-lint --init
+```
+
+```shell [bun]
+bunx herb-lint --init
+```
+
+:::
+
+Then add a lint NPM script to your `package.json`:
+```json [package.json]
 {
   "scripts": {
-    "herb:lint": "herb-lint '**/*.html.erb'"
+    "herb:lint": "herb-lint"
   }
 }
 ```
@@ -100,9 +117,17 @@ bun run herb:lint
 
 Basic usage:
 ```bash
+npx @herb-tools/linter
+npx @herb-tools/linter app/views/
 npx @herb-tools/linter template.html.erb
-npx @herb-tools/linter "**/*.html.erb"
-npx @herb-tools/linter app/
+npx @herb-tools/linter "**/*.rhtml"
+npx @herb-tools/linter "**/*.xml.erb"
+```
+
+**Initialize configuration:**
+```bash
+# Create a .herb.yml configuration file
+npx @herb-tools/linter --init
 ```
 
 #### Options
@@ -184,7 +209,7 @@ npx @herb-tools/linter --format=simple --github
 
 **Example: `--github` (GitHub annotations + detailed format)**
 ```
-::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.7.5::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
+::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.8.0::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
 
 [error] Missing required `alt` attribute on `<img>` tag [html-img-require-alt]
 
@@ -199,7 +224,7 @@ template.html.erb:3:3
 
 **Example: `--format=simple --github` (GitHub annotations + simple format)**
 ```
-::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.7.5::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
+::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.8.0::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
 
 template.html.erb:
   3:3 ✗ Missing required `alt` attribute on `<img>` tag [html-img-require-alt]
@@ -250,7 +275,7 @@ npx @herb-tools/linter template.html.erb --json
         "end": { "line": 1, "column": 22 }
       },
       "severity": "error",
-      "code": "erb-requires-trailing-newline",
+      "code": "erb-require-trailing-newline",
       "source": "Herb Linter"
     }
   ],
@@ -282,6 +307,221 @@ JSON output fields:
 - `clean`: Whether there were no offenses (`null` when `completed=false`)
 - `message`: Error or informational message (`null` on success)
 
+### Disabling Rules Inline <Badge type="info" text="v0.8.0+" />
+
+You can disable linting rules for specific lines using inline comments. This is useful when you need to allow certain code that would otherwise trigger a linting offense.
+
+#### Disabling a Single Rule
+
+Add a comment at the end of the line with `herb:disable` followed by the rule name:
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+```
+
+#### Disabling Multiple Rules
+
+You can disable multiple rules on the same line by separating rule names with commas:
+
+```erb
+<DIV id='test' class="<%= "hello" %>">test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+#### Disabling All Rules
+
+To disable all linting rules for a specific line, use `all`:
+
+```erb
+<DIV id='test' class="<%= "hello" %>">test</DIV> <%# herb:disable all %>
+```
+
+::: warning Important
+Inline disable comments only affect the line they appear on. Each line that needs linting disabled must have its own disable comment.
+:::
+
+## Configuration
+
+Create a `.herb.yml` file in your project root to configure the linter:
+
+```bash
+npx @herb-tools/linter --init
+```
+
+### Basic Configuration
+
+```yaml [.herb.yml]
+linter:
+  enabled: true
+
+  # Additional glob patterns to include (additive to defaults)
+  include:
+    - '**/*.xml.erb'
+
+  # Glob patterns to exclude from linting
+  exclude:
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+
+  rules:
+    # Disable a rule
+    erb-no-extra-newline:
+      enabled: false
+
+    # Change rule severity
+    html-tag-name-lowercase:
+      severity: warning  # error, warning, info, or hint
+```
+
+### Rule-Level File Patterns
+
+Apply rules to specific files using `include`, `only`, and `exclude` patterns:
+
+```yaml [.herb.yml]
+linter:
+  rules:
+    # Apply rule only to component files
+    html-img-require-alt:
+      include:
+        - 'app/components/**/*'
+      exclude:
+        - 'app/components/legacy/**/*'
+
+    # Restrict rule to specific directory (overrides include)
+    html-tag-name-lowercase:
+      only:
+        - 'app/views/**/*'
+      exclude:
+        - 'app/views/admin/**/*'
+```
+
+**Pattern precedence:**
+1. `only` - When present, rule applies ONLY to these files (ignores all `include`)
+2. `include` - When `only` is absent, rule applies only to these files (additive)
+3. `exclude` - Always applied regardless of `include` or `only`
+
+### Force Flag
+
+Process files even when excluded or when linter is disabled:
+
+```bash
+# Force linting when disabled in config
+herb-lint --force
+
+# Force linting on an excluded file
+herb-lint --force app/views/excluded-file.html.erb
+```
+
+When using `--force` on an excluded file, the linter will show a warning but proceed with linting.
+
+### Custom Rules
+
+Create custom linter rules for project-specific requirements by placing ES module files (`.mjs`) in `.herb/rules/`:
+
+::: info File Extension
+Custom rules must use the `.mjs` extension to avoid Node.js module type warnings. The `.mjs` extension explicitly marks files as ES modules.
+:::
+
+::: code-group
+
+
+```js [.herb/rules/no-inline-styles.mjs]
+import { BaseRuleVisitor, ParserRule } from "@herb-tools/linter"
+
+class NoDivTagsVisitor extends BaseRuleVisitor {
+  visitHTMLOpenTagNode(node) {
+    if (!node.tag_name) return
+    if (node.tag_name.value !== "div") return
+
+    this.addOffense(
+      `Avoid using \`<div>\` tags. Consider using semantic HTML elements like \`<section>\`, \`<article>\`, \`<nav>\`, \`<main>\`, \`<header>\`, \`<footer>\`, or \`<aside>\` instead.`,
+      node.tag_name.location
+    )
+  }
+}
+
+export default class NoDivTagsRule extends ParserRule {
+  name = "no-div-tags"
+
+  check(result, context) {
+    const visitor = new NoDivTagsVisitor(this.name, context)
+    visitor.visit(result.value)
+    return visitor.offenses
+  }
+}
+```
+
+```js [.herb/rules/no-inline-styles.mjs]
+import { BaseRuleVisitor, getAttributes, getAttributeName } from "@herb-tools/linter"
+
+class NoInlineStylesVisitor extends BaseRuleVisitor {
+  visitHTMLOpenTagNode(node) {
+    const attributes = getAttributes(node)
+
+    for (const attribute of attributes) {
+      const attributeName = getAttributeName(attribute)
+
+      if (attributeName === "style") {
+        this.addOffense(
+          `Avoid using inline \`style\` attributes. Use CSS classes instead.`,
+          attribute.location,
+          "warning"
+        )
+      }
+    }
+
+    super.visitHTMLOpenTagNode(node)
+  }
+}
+
+export default class NoInlineStylesRule {
+  name = "no-inline-styles"
+
+  check(parseResult, context) {
+    const visitor = new NoInlineStylesVisitor(this.name, context)
+    visitor.visit(parseResult.value)
+    return visitor.offenses
+  }
+}
+```
+
+:::
+
+**Rule Configuration:**
+
+The `defaultConfig` getter is optional. If not specified, custom rules default to:
+- `enabled: true` - Rule is enabled by default
+- `severity: "error"` - Offenses are reported as errors
+- `exclude: []` - No files are excluded
+
+You can override the `defaultConfig` getter to customize these defaults, as shown in the example above where severity is set to `"warning"`.
+
+**Rule Properties:**
+
+- `static type` - Optional, defaults to `"parser"`. Can be `"parser"`, `"lexer"`, or `"source"`
+- `name` - Required, the rule identifier used in configuration and output
+- `check()` - Required, the method that checks for offenses
+- `defaultConfig` - Optional, returns the default configuration for the rule
+- `isEnabled()` - Optional, dynamically determines if the rule should run
+- `autofix()` - Optional, implements automatic fixing for the rule
+
+Custom rules are loaded automatically by default. Use `--no-custom-rules` to disable them.
+
+When custom rules are loaded, the linter will display them:
+
+```
+Loaded 2 custom rules:
+  • no-inline-styles (.herb/rules/no-inline-styles.mjs)
+  • require-aria-labels (.herb/rules/require-aria-labels.mjs)
+```
+
+::: warning Rule Name Clashes
+If a custom rule has the same name as a built-in rule or another custom rule, you'll see a warning. The custom rule will override the built-in rule.
+:::
+
+::: tip Hot Reload
+Custom rules are automatically reloaded when changed in editors with the Herb Language Server. No need to restart your editor!
+:::
+
 ### Language Server Integration
 
 The linter is automatically integrated into the [Herb Language Server](https://herb-tools.dev/projects/language-server), providing real-time validation in supported editors like VS Code, Zed, and Neovim.