@herb-tools/linter 0.7.4 → 0.8.0

package/docs/rules/html-no-empty-headings.md

@@ -15,56 +15,34 @@ Headings relay the structure of a webpage and provide a meaningful, hierarchical
 ### ✅ Good
 
 ```erb
-<h*>Heading Content</h*>
-```
+<h1>Heading Content</h1>
 
-```erb
-<h*><span>Text</span><h*>
-```
+<h1><span>Text</span></h1>
 
-```erb
 <div role="heading" aria-level="1">Heading Content</div>
-```
 
-```erb
-<h* aria-hidden="true">Heading Content</h*>
-```
+<h1 aria-hidden="true">Heading Content</h1>
 
-```erb
-<h* hidden>Heading Content</h*>
+<h1 hidden>Heading Content</h1>
 ```
 
 ### 🚫 Bad
 
 ```erb
 <h1></h1>
-```
 
-```erb
 <h2></h2>
-```
 
-```erb
 <h3></h3>
-```
 
-```erb
 <h4></h4>
-```
 
-```erb
 <h5></h5>
-```
 
-```erb
 <h6></h6>
-```
 
-```erb
 <div role="heading" aria-level="1"></div>
-```
 
-```erb
 <h1><span aria-hidden="true">Inaccessible text</span></h1>
 ```
 

package/docs/rules/html-no-positive-tab-index.md

@@ -41,8 +41,7 @@ The recommended approach is to structure your HTML in the correct tab order and
 
 <button tabindex="2">Second in tab order</button>
 
-
-<input tabindex="5" type="text">
+<input tabindex="5" type="text" autocomplete="off">
 
 <button tabindex="10">Submit</button>
 ```

package/docs/rules/html-no-self-closing.md

@@ -22,6 +22,21 @@ Self-closing syntax is an XHTML artifact. In HTML:
 Removing the slash ensures HTML5-compliant, cleaner markup and avoids mixing
 XHTML and HTML styles.
 
+## Exception for Email Templates
+
+::: info
+This rule is automatically disabled for ActionMailer view files (paths matching `**/views/**/*_mailer/**/*`) because older email clients, particularly legacy versions of Microsoft Outlook, require self-closing syntax for proper rendering of void elements like `<br />`.
+:::
+
+If you want to enable this rule for email templates as well, you can override the default exclusion in your `.herb.yml` configuration:
+
+```yaml [.herb.yml]
+linter:
+  rules:
+    html-no-self-closing:
+      exclude: []  # Override to enable for all files including ActionMailer views
+```
+
 ## Examples
 
 ### ✅ Good
@@ -33,7 +48,7 @@ XHTML and HTML styles.
 <custom-element></custom-element>
 
 <img src="/logo.png" alt="Logo">
-<input type="text">
+<input type="text" autocomplete="off">
 <br>
 <hr>
 ```
@@ -51,7 +66,7 @@ XHTML and HTML styles.
 
 <img src="/logo.png" alt="Logo" />
 
-<input type="text" />
+<input type="text" autocomplete="off" />
 
 <br />
 

package/docs/rules/html-no-space-in-tag.md

@@ -0,0 +1,66 @@
+# Linter Rule: Enforce consistent spacing within HTML tags
+
+**Rule:** `html-no-space-in-tag`
+
+## Description
+
+Enforce consistent spacing within HTML opening and closing tags. This rule ensures:
+- Exactly one space between tag name and first attribute
+- Exactly one space between attributes
+- No extra spaces before the closing `>` in non-self-closing tags
+- Exactly one space before `/>` in self-closing tags
+- No whitespace in closing tags (e.g., `</div>`)
+- Consistent indentation in multiline tags
+
+## Rationale
+
+Consistent spacing within HTML tags improves code readability and maintainability. Extra or missing spaces can make templates harder to scan and can indicate formatting inconsistencies across a codebase. This rule enforces a canonical style that is both readable and machine-parseable.
+
+Self-closing tags (`<img />`, `<br />`) should have exactly one space before the `/>` to maintain visual consistency with HTML5 and JSX conventions.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div class="foo"></div>
+
+<img src="/logo.png" alt="Logo">
+
+<input class="foo" name="bar">
+
+<div class="foo" data-x="bar"></div>
+
+<div
+  class="foo"
+  data-x="bar"
+>
+  foo
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div  class="foo"></div>
+
+<div class="foo" ></div>
+
+<img alt="Logo" src="/logo.png">
+
+<div class="foo"      data-x="bar"></div>
+
+<div
+   class="foo"
+    data-x="bar"
+>
+  foo
+</div>
+
+<div >
+</  div>
+```
+
+## References
+
+- [Inspiration: ERB Lint `SpaceInHtmlTag` rule](https://github.com/shopify/erb_lint)

package/docs/rules/html-no-title-attribute.md

@@ -33,7 +33,7 @@ This rule allows `title` on `<iframe>` and `<link>` elements where it serves spe
 <button aria-label="Close dialog">×</button>
 
 <!-- Use aria-describedby for additional context -->
-<input type="password" aria-describedby="pwd-help">
+<input type="password" aria-describedby="pwd-help" autocomplete="off">
 <div id="pwd-help">Password must be at least 8 characters</div>
 
 <!-- Exceptions: title allowed on iframe and links -->
@@ -52,7 +52,7 @@ This rule allows `title` on `<iframe>` and `<link>` elements where it serves spe
 <span title="Required field">*</span>
 
 <!-- Don't use title on form elements -->
-<input type="text" title="Enter your name">
+<input type="text" title="Enter your name" autocomplete="off">
 
 <select title="Choose your country">
   <option>US</option>

package/docs/rules/html-no-underscores-in-attribute-names.md

@@ -23,7 +23,7 @@ Underscores in attribute names violate the HTML specification and are not suppor
 ```html
 <div data-user-id="123"></div>
 
-<img aria-label="Close">
+<img aria-label="Close" alt="Close">
 
 <div data-<%= key %>-attribute="value"></div>
 ```
@@ -33,7 +33,7 @@ Underscores in attribute names violate the HTML specification and are not suppor
 ```html
 <div data_user_id="123"></div>
 
-<img aria_label="Close">
+<img aria_label="Close" alt="Close">
 
 <div data-<%= key %>_attribute="value"></div>
 ```

package/docs/rules/html-tag-name-lowercase.md

@@ -33,7 +33,7 @@ This rule does not apply to child elements within `<svg>` tags, as SVG element n
 ```erb
 <div class="container"></div>
 
-<input type="text" name="username">
+<input type="text" name="username" autocomplete="off">
 
 <span>Label</span>
 
@@ -45,7 +45,7 @@ This rule does not apply to child elements within `<svg>` tags, as SVG element n
 ```erb
 <DIV class="container"></DIV>
 
-<Input type="text" name="username">
+<Input type="text" name="username" autocomplete="off">
 
 <Span>Label</Span>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -36,13 +36,21 @@
       "types": "./dist/types/src/cli.d.ts",
       "require": "./dist/src/cli.js",
       "default": "./dist/src/cli.js"
+    },
+    "./loader": {
+      "types": "./dist/types/loader.d.ts",
+      "import": "./dist/loader.js",
+      "require": "./dist/loader.cjs",
+      "default": "./dist/loader.js"
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.7.4",
-    "@herb-tools/highlighter": "0.7.4",
-    "@herb-tools/node-wasm": "0.7.4",
-    "@herb-tools/printer": "0.7.4",
+    "@herb-tools/config": "0.8.0",
+    "@herb-tools/core": "0.8.0",
+    "@herb-tools/highlighter": "0.8.0",
+    "@herb-tools/node-wasm": "0.8.0",
+    "@herb-tools/printer": "0.8.0",
+    "@herb-tools/rewriter": "0.8.0",
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli/argument-parser.ts

@@ -1,50 +1,58 @@
 import dedent from "dedent"
 
 import { parseArgs } from "util"
-import { statSync } from "fs"
-import { join } from "path"
-
 import { Herb } from "@herb-tools/node-wasm"
 
 import { THEME_NAMES, DEFAULT_THEME } from "@herb-tools/highlighter"
 import type { ThemeInput } from "@herb-tools/highlighter"
 
-import { name, version } from "../../package.json"
+import { name, version, dependencies } from "../../package.json"
 
 export type FormatOption = "simple" | "detailed" | "json"
 
 export interface ParsedArguments {
-  pattern: string
+  patterns: string[]
+  configFile?: string
   formatOption: FormatOption
   showTiming: boolean
   theme: ThemeInput
   wrapLines: boolean
   truncateLines: boolean
   useGitHubActions: boolean
+  fix: boolean
+  ignoreDisableComments: boolean
+  force: boolean
+  init: boolean
+  loadCustomRules: boolean
 }
 
 export class ArgumentParser {
   private readonly usage = dedent`
-    Usage: herb-lint [file|glob-pattern|directory] [options]
+    Usage: herb-lint [files|directories|glob-patterns...] [options]
 
     Arguments:
-      file             Single file to lint
-      glob-pattern     Files to lint (defaults to **/*.html.erb)
-      directory        Directory to lint (automatically appends **/*.html.erb)
+      files            Files, directories, or glob patterns to lint (defaults to configured extensions in .herb.yml)
+                       Multiple arguments are supported (e.g., herb-lint file1.erb file2.erb dir/ "**/*.erb")
 
     Options:
-      -h, --help       show help
-      -v, --version    show version
-      --format         output format (simple|detailed|json) [default: detailed]
-      --simple         use simple output format (shortcut for --format simple)
-      --json           use JSON output format (shortcut for --format json)
-      --github         enable GitHub Actions annotations (combines with --format)
-      --no-github      disable GitHub Actions annotations (even in GitHub Actions environment)
-      --theme          syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
-      --no-color       disable colored output
-      --no-timing      hide timing information
-      --no-wrap-lines  disable line wrapping
-      --truncate-lines enable line truncation (mutually exclusive with line wrapping)
+      -h, --help                    show help
+      -v, --version                 show version
+      --init                        create a .herb.yml configuration file in the current directory
+      -c, --config-file <path>      explicitly specify path to .herb.yml config file
+      --force                       force linting even if disabled in .herb.yml
+      --fix                         automatically fix auto-correctable offenses
+      --ignore-disable-comments     report offenses even when suppressed with <%# herb:disable %> comments
+      --format                      output format (simple|detailed|json) [default: detailed]
+      --simple                      use simple output format (shortcut for --format simple)
+      --json                        use JSON output format (shortcut for --format json)
+      --github                      enable GitHub Actions annotations (combines with --format)
+      --no-github                   disable GitHub Actions annotations (even in GitHub Actions environment)
+      --no-custom-rules             disable loading custom rules from project (custom rules are loaded by default from .herb/rules/**/*.{mjs,js})
+      --theme                       syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
+      --no-color                    disable colored output
+      --no-timing                   hide timing information
+      --no-wrap-lines               disable line wrapping
+      --truncate-lines              enable line truncation (mutually exclusive with line wrapping)
   `
 
   parse(argv: string[]): ParsedArguments {
@@ -53,6 +61,11 @@ export class ArgumentParser {
       options: {
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
+        init: { type: "boolean" },
+        "config-file": { type: "string", short: "c" },
+        force: { type: "boolean" },
+        fix: { type: "boolean" },
+        "ignore-disable-comments": { type: "boolean" },
         format: { type: "string" },
         simple: { type: "boolean" },
         json: { type: "boolean" },
@@ -62,7 +75,8 @@ export class ArgumentParser {
         "no-color": { type: "boolean" },
         "no-timing": { type: "boolean" },
         "no-wrap-lines": { type: "boolean" },
-        "truncate-lines": { type: "boolean" }
+        "truncate-lines": { type: "boolean" },
+        "no-custom-rules": { type: "boolean" }
       },
       allowPositionals: true
     })
@@ -74,7 +88,9 @@ export class ArgumentParser {
 
     if (values.version) {
       console.log("Versions:")
-      console.log(`  ${name}@${version}, ${Herb.version}`.split(", ").join("\n  "))
+      console.log(`  ${name}@${version}`)
+      console.log(`  @herb-tools/printer@${dependencies["@herb-tools/printer"]}`)
+      console.log(`  ${Herb.version}`.split(", ").join("\n  "))
       process.exit(0)
     }
 
@@ -120,23 +136,18 @@ export class ArgumentParser {
     }
 
     const theme = values.theme || DEFAULT_THEME
-    const pattern = this.getFilePattern(positionals)
-
-    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions }
+    const patterns = this.getFilePatterns(positionals)
+    const fix = values.fix || false
+    const force = !!values.force
+    const ignoreDisableComments = values["ignore-disable-comments"] || false
+    const configFile = values["config-file"]
+    const init = values.init || false
+    const loadCustomRules = !values["no-custom-rules"]
+
+    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init, loadCustomRules }
   }
 
-  private getFilePattern(positionals: string[]): string {
-    let pattern = positionals.length > 0 ? positionals[0] : "**/*.html.erb"
-
-    try {
-      const stat = statSync(pattern)
-      if (stat.isDirectory()) {
-        pattern = join(pattern, "**/*.html.erb")
-      }
-    } catch {
-      // Not a file/directory, treat as glob pattern
-    }
-
-    return pattern
+  private getFilePatterns(positionals: string[]): string[] {
+    return positionals
   }
 }

package/src/cli/file-processor.ts

@@ -1,26 +1,42 @@
-import { readFileSync } from "fs"
-import { resolve } from "path"
 import { Herb } from "@herb-tools/node-wasm"
 import { Linter } from "../linter.js"
+import { loadCustomRules } from "../loader.js"
+import { Config } from "@herb-tools/config"
+
+import { readFileSync, writeFileSync } from "fs"
+import { resolve } from "path"
 import { colorize } from "@herb-tools/highlighter"
+
 import type { Diagnostic } from "@herb-tools/core"
 import type { FormatOption } from "./argument-parser.js"
+import type { HerbConfigOptions } from "@herb-tools/config"
 
 export interface ProcessedFile {
   filename: string
   offense: Diagnostic
   content: string
+  autocorrectable?: boolean
 }
 
 export interface ProcessingContext {
   projectPath?: string
   pattern?: string
+  fix?: boolean
+  ignoreDisableComments?: boolean
+  linterConfig?: HerbConfigOptions['linter']
+  config?: Config
+  loadCustomRules?: boolean
 }
 
 export interface ProcessingResult {
   totalErrors: number
   totalWarnings: number
+  totalInfo: number
+  totalHints: number
+  totalIgnored: number
+  totalWouldBeIgnored?: number
   filesWithOffenses: number
+  filesFixed: number
   ruleCount: number
   allOffenses: ProcessedFile[]
   ruleOffenses: Map<string, { count: number, files: Set<string> }>
@@ -29,55 +45,146 @@ export interface ProcessingResult {
 
 export class FileProcessor {
   private linter: Linter | null = null
+  private customRulesLoaded: boolean = false
+
+  private isRuleAutocorrectable(ruleName: string): boolean {
+    if (!this.linter) return false
+
+    const RuleClass = (this.linter as any).rules.find((rule: any) => {
+      const instance = new rule()
+
+      return instance.name === ruleName
+    })
+
+    if (!RuleClass) return false
+
+    return RuleClass.autocorrectable === true
+  }
 
   async processFiles(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
     let totalErrors = 0
     let totalWarnings = 0
+    let totalInfo = 0
+    let totalHints = 0
+    let totalIgnored = 0
+    let totalWouldBeIgnored = 0
     let filesWithOffenses = 0
+    let filesFixed = 0
     let ruleCount = 0
+
     const allOffenses: ProcessedFile[] = []
     const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
 
-    for (const filename of files) {
-      const filePath = context?.projectPath ? resolve(context.projectPath, filename) : resolve(filename)
-      const content = readFileSync(filePath, "utf-8")
-      const parseResult = Herb.parse(content)
-
-      if (parseResult.errors.length > 0) {
-        if (formatOption !== 'json') {
-          console.error(`${colorize(filename, "cyan")} - ${colorize("Parse errors:", "brightRed")}`)
-
-          for (const error of parseResult.errors) {
-            console.error(`  ${colorize("✗", "brightRed")} ${error.message}`)
+    if (!this.linter) {
+      let customRules = undefined
+      let customRuleInfo: Array<{ name: string, path: string }> = []
+      let customRuleWarnings: string[] = []
+
+      if (context?.loadCustomRules && !this.customRulesLoaded) {
+        try {
+          const result = await loadCustomRules({
+            baseDir: context.projectPath,
+            silent: formatOption === 'json'
+          })
+
+          customRules = result.rules
+          customRuleInfo = result.ruleInfo
+          customRuleWarnings = result.warnings
+
+          this.customRulesLoaded = true
+
+          if (customRules.length > 0 && formatOption !== 'json') {
+            const ruleText = customRules.length === 1 ? 'rule' : 'rules'
+            console.log(colorize(`\nLoaded ${customRules.length} custom ${ruleText}:`, "green"))
+
+            for (const { name, path } of customRuleInfo) {
+              const relativePath = context.projectPath ? path.replace(context.projectPath + '/', '') : path
+              console.log(colorize(`  • ${name}`, "cyan") + colorize(` (${relativePath})`, "dim"))
+            }
+
+            if (customRuleWarnings.length > 0) {
+              console.log()
+              for (const warning of customRuleWarnings) {
+                console.warn(colorize(`  ⚠ ${warning}`, "yellow"))
+              }
+            }
+
+            console.log()
+          }
+        } catch (error) {
+          if (formatOption !== 'json') {
+            console.warn(colorize(`Warning: Failed to load custom rules: ${error}`, "yellow"))
           }
         }
-
-        for (const error of parseResult.errors) {
-          allOffenses.push({ filename, offense: error, content })
-        }
-
-        totalErrors++
-        filesWithOffenses++
-        continue
       }
 
-      if (!this.linter) {
-        this.linter = new Linter(Herb)
-      }
+      this.linter = Linter.from(Herb, context?.config, customRules)
+    }
 
-      const lintResult = this.linter.lint(content, { fileName: filename })
+    for (const filename of files) {
+      const filePath = context?.projectPath ? resolve(context.projectPath, filename) : resolve(filename)
+      let content = readFileSync(filePath, "utf-8")
+
+      const lintResult = this.linter.lint(content, {
+        fileName: filename,
+        ignoreDisableComments: context?.ignoreDisableComments
+      })
 
       if (ruleCount === 0) {
         ruleCount = this.linter.getRuleCount()
       }
 
-      if (lintResult.offenses.length === 0) {
+      if (context?.fix && lintResult.offenses.length > 0) {
+        const autofixResult = this.linter.autofix(content, {
+          fileName: filename,
+          ignoreDisableComments: context?.ignoreDisableComments
+        })
+
+        if (autofixResult.fixed.length > 0) {
+          writeFileSync(filePath, autofixResult.source, "utf-8")
+
+          filesFixed++
+
+          if (formatOption !== 'json') {
+            console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${autofixResult.fixed.length} offense(s)`, "green")}`)
+          }
+        }
+
+        content = autofixResult.source
+
+        for (const offense of autofixResult.unfixed) {
+          allOffenses.push({
+            filename,
+            offense: offense,
+            content,
+            autocorrectable: this.isRuleAutocorrectable(offense.rule)
+          })
+
+          const ruleData = ruleOffenses.get(offense.rule) || { count: 0, files: new Set() }
+          ruleData.count++
+          ruleData.files.add(filename)
+          ruleOffenses.set(offense.rule, ruleData)
+        }
+
+        if (autofixResult.unfixed.length > 0) {
+          totalErrors += autofixResult.unfixed.filter(offense => offense.severity === "error").length
+          totalWarnings += autofixResult.unfixed.filter(offense => offense.severity === "warning").length
+          totalInfo += autofixResult.unfixed.filter(offense => offense.severity === "info").length
+          totalHints += autofixResult.unfixed.filter(offense => offense.severity === "hint").length
+          filesWithOffenses++
+        }
+      } else if (lintResult.offenses.length === 0) {
         if (files.length === 1 && formatOption !== 'json') {
           console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize("No issues found", "green")}`)
         }
       } else {
         for (const offense of lintResult.offenses) {
-          allOffenses.push({ filename, offense: offense, content })
+          allOffenses.push({
+            filename,
+            offense: offense,
+            content,
+            autocorrectable: this.isRuleAutocorrectable(offense.rule)
+          })
 
           const ruleData = ruleOffenses.get(offense.rule) || { count: 0, files: new Set() }
           ruleData.count++
@@ -87,10 +194,34 @@ export class FileProcessor {
 
         totalErrors += lintResult.errors
         totalWarnings += lintResult.warnings
+        totalInfo += lintResult.offenses.filter(o => o.severity === "info").length
+        totalHints += lintResult.offenses.filter(o => o.severity === "hint").length
         filesWithOffenses++
       }
+      totalIgnored += lintResult.ignored
+      if (lintResult.wouldBeIgnored) {
+        totalWouldBeIgnored += lintResult.wouldBeIgnored
+      }
+    }
+
+    const result: ProcessingResult = {
+      totalErrors,
+      totalWarnings,
+      totalInfo,
+      totalHints,
+      totalIgnored,
+      filesWithOffenses,
+      filesFixed,
+      ruleCount,
+      allOffenses,
+      ruleOffenses,
+      context
+    }
+
+    if (totalWouldBeIgnored > 0) {
+      result.totalWouldBeIgnored = totalWouldBeIgnored
     }
 
-    return { totalErrors, totalWarnings, filesWithOffenses, ruleCount, allOffenses, ruleOffenses, context }
+    return result
   }
 }