@herb-tools/linter 0.8.9 → 0.9.0

package/docs/rules/html-require-closing-tags.md

@@ -0,0 +1,142 @@
+# Linter Rule: Require explicit closing tags
+
+**Rule:** `html-require-closing-tags`
+
+## Description
+
+Disallow the omission of optional closing tags for HTML elements where the closing tag is technically optional according to the HTML specification. This rule flags elements that have an `HTMLOmittedCloseTagNode` as their close tag.
+
+## Rationale
+
+While HTML allows certain closing tags to be omitted (implicitly closed by sibling elements or parent closing), explicit closing tags improve code readability and maintainability. They make the document structure clear at a glance and reduce ambiguity about where elements end.
+
+Explicit closing tags also:
+
+- Make templates easier to understand for developers unfamiliar with HTML's implicit closing rules
+- Reduce potential for subtle bugs when refactoring or moving code
+- Improve consistency across the codebase
+- Make diffs cleaner when adding content to elements
+
+## Elements with Optional Closing Tags
+
+This rule would flag elements that have omitted closing tags:
+
+- `<li>` - list items
+- `<dt>`, `<dd>` - definition list terms and descriptions
+- `<p>` - paragraphs
+- `<option>`, `<optgroup>` - select options and groups
+- `<thead>`, `<tbody>`, `<tfoot>` - table sections
+- `<tr>` - table rows
+- `<td>`, `<th>` - table cells
+- `<colgroup>` - table column groups
+- `<rt>`, `<rp>` - ruby annotations
+
+## Examples
+
+### ✅ Good
+
+Explicit closing tags:
+
+```erb
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+```erb
+<dl>
+  <dt>Term 1</dt>
+  <dd>Definition 1</dd>
+  <dt>Term 2</dt>
+  <dd>Definition 2</dd>
+</dl>
+```
+
+```erb
+<table>
+  <thead>
+    <tr>
+      <th>Header 1</th>
+      <th>Header 2</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Cell 1</td>
+      <td>Cell 2</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```erb
+<select>
+  <option>Option 1</option>
+  <option>Option 2</option>
+  <option>Option 3</option>
+</select>
+```
+
+```erb
+<div>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</div>
+```
+
+### 🚫 Bad
+
+Omitted closing tags (implicitly closed):
+
+```erb
+<ul>
+  <li>Item 1
+  <li>Item 2
+  <li>Item 3
+</ul>
+```
+
+```erb
+<dl>
+  <dt>Term 1
+  <dd>Definition 1
+  <dt>Term 2
+  <dd>Definition 2
+</dl>
+```
+
+```erb
+<table>
+  <thead>
+    <tr>
+      <th>Header 1
+      <th>Header 2
+  <tbody>
+    <tr>
+      <td>Cell 1
+      <td>Cell 2
+</table>
+```
+
+```erb
+<select>
+  <option>Option 1
+  <option>Option 2
+  <option>Option 3
+</select>
+```
+
+```erb
+<div>
+  <p>Paragraph 1
+  <p>Paragraph 2
+</div>
+```
+
+## References
+
+- [HTML Spec: Optional Tags](https://html.spec.whatwg.org/multipage/syntax.html#optional-tags)
+- [HTML Spec: Tag Omission](https://html.spec.whatwg.org/multipage/dom.html#concept-element-tag-omission)
+- [CSS-Tricks: Fighting the Space Between Inline Block Elements](https://css-tricks.com/fighting-the-space-between-inline-block-elements/)

package/docs/rules/parser-no-errors.md

@@ -39,15 +39,16 @@ By surfacing parser errors through the linter, developers can catch these critic
 ### 🚫 Bad
 
 ```html
-<!-- Mismatched closing tag -->
 <h2>Welcome to our site</h3>
+```
 
-<!-- Unclosed element -->
+```html
 <div>
   <p>This paragraph is never closed
 </div>
+```
 
-<!-- Missing opening tag -->
+```html
 Some content
 </div>
 ```
@@ -63,20 +64,6 @@ Some content
 <img src="image.jpg" alt="Description"></img>
 ```
 
-## Error Types
-
-This rule reports various parser error types:
-
-- **`UNCLOSED_ELEMENT_ERROR`**: Elements that are opened but never closed
-- **`MISSING_CLOSING_TAG_ERROR`**: Opening tags without matching closing tags
-- **`MISSING_OPENING_TAG_ERROR`**: Closing tags without matching opening tags
-- **`TAG_NAMES_MISMATCH_ERROR`**: Opening and closing tags with different names
-- **`QUOTES_MISMATCH_ERROR`**: Mismatched quotation marks in attributes
-- **`VOID_ELEMENT_CLOSING_TAG_ERROR`**: Void elements (like `<img>`) with closing tags
-- **`RUBY_PARSE_ERROR`**: Invalid Ruby syntax within ERB tags
-- **`UNEXPECTED_TOKEN_ERROR`**: Unexpected tokens during parsing
-- **`UNEXPECTED_ERROR`**: Other unexpected parsing issues
-
 ## References
 
 * [HTML Living Standard - Parsing](https://html.spec.whatwg.org/multipage/parsing.html)

package/docs/rules/turbo-permanent-require-id.md

@@ -0,0 +1,41 @@
+# Linter Rule: Require `id` attribute on elements with `data-turbo-permanent`
+
+**Rule:** `turbo-permanent-require-id`
+
+## Description
+
+Ensure that all HTML elements with the `data-turbo-permanent` attribute also have an `id` attribute. Without an `id`, Turbo can't track the element across page changes and the permanent behavior won't work as expected.
+
+## Rationale
+
+Turbo's `data-turbo-permanent` attribute marks an element to be persisted across page navigations. Turbo uses the element's `id` to match it between the current page and the new page. If no `id` is present, Turbo has no way to identify and preserve the element, so the `data-turbo-permanent` attribute has no effect.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div id="player" data-turbo-permanent>
+  <!-- This element will persist across page navigations -->
+</div>
+
+<audio id="background-music" data-turbo-permanent>
+  <source src="/music.mp3" type="audio/mpeg">
+</audio>
+```
+
+### 🚫 Bad
+
+```erb
+<div data-turbo-permanent>
+  <!-- Missing id: Turbo can't track this element -->
+</div>
+
+<audio data-turbo-permanent>
+  <source src="/music.mp3" type="audio/mpeg">
+</audio>
+```
+
+## References
+
+- [Turbo Handbook: Persisting Elements Across Page Loads](https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -22,7 +22,7 @@
     "watch": "tsc -b -w",
     "test": "vitest run",
     "test:watch": "vitest --watch",
-    "prepublishOnly": "yarn clean && yarn build && yarn test"
+    "prepublishOnly": "yarn clean && yarn build"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -33,9 +33,10 @@
       "default": "./dist/index.js"
     },
     "./cli": {
-      "types": "./dist/types/src/cli.d.ts",
-      "require": "./dist/src/cli.js",
-      "default": "./dist/src/cli.js"
+      "types": "./dist/types/cli.d.ts",
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.js",
+      "default": "./dist/cli.js"
     },
     "./loader": {
       "types": "./dist/types/loader.d.ts",
@@ -45,12 +46,12 @@
     }
   },
   "dependencies": {
-    "@herb-tools/config": "0.8.9",
-    "@herb-tools/core": "0.8.9",
-    "@herb-tools/highlighter": "0.8.9",
-    "@herb-tools/node-wasm": "0.8.9",
-    "@herb-tools/printer": "0.8.9",
-    "@herb-tools/rewriter": "0.8.9",
+    "@herb-tools/config": "0.9.0",
+    "@herb-tools/core": "0.9.0",
+    "@herb-tools/highlighter": "0.9.0",
+    "@herb-tools/node-wasm": "0.9.0",
+    "@herb-tools/printer": "0.9.0",
+    "@herb-tools/rewriter": "0.9.0",
     "picomatch": "^4.0.2",
     "tinyglobby": "^0.2.15"
   },

package/src/cli/argument-parser.ts

@@ -1,5 +1,6 @@
 import dedent from "dedent"
 
+import { availableParallelism } from "node:os"
 import { parseArgs } from "util"
 import { Herb } from "@herb-tools/node-wasm"
 
@@ -27,6 +28,7 @@ export interface ParsedArguments {
   init: boolean
   loadCustomRules: boolean
   failLevel?: DiagnosticSeverity
+  jobs: number
 }
 
 export class ArgumentParser {
@@ -53,6 +55,8 @@ export class ArgumentParser {
       --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})
+      -j, --jobs <n>                number of parallel workers for linting files [default: auto]
+                                    use "auto" to detect based on available CPU cores
       --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
@@ -83,7 +87,8 @@ export class ArgumentParser {
         "no-timing": { type: "boolean" },
         "no-wrap-lines": { type: "boolean" },
         "truncate-lines": { type: "boolean" },
-        "no-custom-rules": { type: "boolean" }
+        "no-custom-rules": { type: "boolean" },
+        jobs: { type: "string", short: "j" }
       },
       allowPositionals: true
     })
@@ -163,7 +168,20 @@ export class ArgumentParser {
       }
     }
 
-    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel }
+    let jobs = availableParallelism()
+
+    if (values.jobs && values.jobs !== "auto") {
+      const parsed = parseInt(values.jobs, 10)
+
+      if (isNaN(parsed) || parsed < 1) {
+        console.error(`Error: Invalid --jobs value "${values.jobs}". Must be a positive integer or "auto".`)
+        process.exit(1)
+      }
+
+      jobs = parsed
+    }
+
+    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel, jobs }
   }
 
   private getFilePatterns(positionals: string[]): string[] {

package/src/cli/file-processor.ts

@@ -3,13 +3,17 @@ 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 { Worker } from "node:worker_threads"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve, dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { availableParallelism } from "node:os"
 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"
+import type { WorkerInput, WorkerResult } from "./lint-worker.js"
 
 export interface ProcessedFile {
   filename: string
@@ -20,6 +24,7 @@ export interface ProcessedFile {
 
 export interface ProcessingContext {
   projectPath?: string
+  configPath?: string
   pattern?: string
   fix?: boolean
   fixUnsafe?: boolean
@@ -27,6 +32,7 @@ export interface ProcessingContext {
   linterConfig?: HerbConfigOptions['linter']
   config?: Config
   loadCustomRules?: boolean
+  jobs?: number
 }
 
 export interface ProcessingResult {
@@ -44,6 +50,13 @@ export interface ProcessingResult {
   context?: ProcessingContext
 }
 
+/**
+ * Minimum number of files required to use parallel processing.
+ * Below this threshold, sequential processing is faster due to
+ * worker thread startup overhead (loading WASM, config, etc.).
+ */
+const PARALLEL_FILE_THRESHOLD = 10
+
 export class FileProcessor {
   private linter: Linter | null = null
   private customRulesLoaded: boolean = false
@@ -51,18 +64,27 @@ export class FileProcessor {
   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
-    })
+    const ruleClass = (this.linter as any).rules.find(
+      (rule: any) => rule.ruleName === ruleName
+    )
 
-    if (!RuleClass) return false
+    if (!ruleClass) return false
 
-    return RuleClass.autocorrectable === true
+    return ruleClass.autocorrectable === true
   }
 
   async processFiles(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
+    const jobs = context?.jobs ?? 1
+    const shouldParallelize = jobs > 1 && files.length >= PARALLEL_FILE_THRESHOLD
+
+    if (shouldParallelize) {
+      return this.processFilesInParallel(files, jobs, formatOption, context)
+    }
+
+    return this.processFilesSequentially(files, formatOption, context)
+  }
+
+  private async processFilesSequentially(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
     let totalErrors = 0
     let totalWarnings = 0
     let totalInfo = 0
@@ -147,7 +169,7 @@ export class FileProcessor {
           filesFixed++
 
           if (formatOption !== 'json') {
-            console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${autofixResult.fixed.length} offense(s)`, "green")}`)
+            console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${autofixResult.fixed.length} ${autofixResult.fixed.length === 1 ? "offense" : "offenses"}`, "green")}`)
           }
         }
 
@@ -225,4 +247,161 @@ export class FileProcessor {
 
     return result
   }
+
+  private async processFilesInParallel(files: string[], jobs: number, formatOption: FormatOption, context?: ProcessingContext): Promise<ProcessingResult> {
+    const workerCount = Math.min(jobs, files.length)
+    const chunks = this.splitIntoChunks(files, workerCount)
+    const workerPath = this.resolveWorkerPath()
+
+    const workerPromises = chunks.map(chunk => this.runWorker(workerPath, chunk, context))
+    const workerResults = await Promise.all(workerPromises)
+
+    for (const result of workerResults) {
+      if (result.error) {
+        throw new Error(`Worker error: ${result.error}`)
+      }
+    }
+
+    return this.aggregateWorkerResults(workerResults, formatOption, context)
+  }
+
+  private resolveWorkerPath(): string {
+    try {
+      const currentDir = dirname(fileURLToPath(import.meta.url))
+
+      return join(currentDir, "lint-worker.js")
+    } catch {
+      return join(__dirname, "lint-worker.js")
+    }
+  }
+
+  private splitIntoChunks(files: string[], chunkCount: number): string[][] {
+    const chunks: string[][] = Array.from({ length: chunkCount }, () => [])
+
+    for (let i = 0; i < files.length; i++) {
+      chunks[i % chunkCount].push(files[i])
+    }
+
+    return chunks.filter(chunk => chunk.length > 0)
+  }
+
+  private runWorker(workerPath: string, files: string[], context?: ProcessingContext): Promise<WorkerResult> {
+    return new Promise((resolve, reject) => {
+      const workerData: WorkerInput = {
+        files,
+        projectPath: context?.projectPath || process.cwd(),
+        configPath: context?.configPath,
+        fix: context?.fix || false,
+        fixUnsafe: context?.fixUnsafe || false,
+        ignoreDisableComments: context?.ignoreDisableComments || false,
+        loadCustomRules: context?.loadCustomRules || false,
+      }
+
+      const worker = new Worker(workerPath, { workerData })
+
+      worker.on("message", (result: WorkerResult) => {
+        resolve(result)
+      })
+
+      worker.on("error", (error) => {
+        reject(error)
+      })
+
+      worker.on("exit", (code) => {
+        if (code !== 0) {
+          reject(new Error(`Worker exited with code ${code}`))
+        }
+      })
+    })
+  }
+
+  private aggregateWorkerResults(results: WorkerResult[], formatOption: FormatOption, context?: ProcessingContext): 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 result of results) {
+      totalErrors += result.totalErrors
+      totalWarnings += result.totalWarnings
+      totalInfo += result.totalInfo
+      totalHints += result.totalHints
+      totalIgnored += result.totalIgnored
+      totalWouldBeIgnored += result.totalWouldBeIgnored
+      filesWithOffenses += result.filesWithOffenses
+      filesFixed += result.filesFixed
+
+      if (result.ruleCount > 0) {
+        ruleCount = result.ruleCount
+      }
+
+      for (const offense of result.offenses) {
+        allOffenses.push({
+          filename: offense.filename,
+          offense: offense.offense,
+          content: offense.content,
+          autocorrectable: offense.autocorrectable
+        })
+      }
+
+      for (const [rule, data] of result.ruleOffenses) {
+        const existing = ruleOffenses.get(rule) || { count: 0, files: new Set<string>() }
+        existing.count += data.count
+
+        for (const file of data.files) {
+          existing.files.add(file)
+        }
+
+        ruleOffenses.set(rule, existing)
+      }
+
+      if (formatOption !== 'json') {
+        for (const fixMessage of result.fixMessages) {
+          const [filename, countStr] = fixMessage.split("\t")
+          const count = parseInt(countStr, 10)
+          console.log(`${colorize("\u2713", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${count} ${count === 1 ? "offense" : "offenses"}`, "green")}`)
+        }
+      }
+    }
+
+    const processingResult: ProcessingResult = {
+      totalErrors,
+      totalWarnings,
+      totalInfo,
+      totalHints,
+      totalIgnored,
+      filesWithOffenses,
+      filesFixed,
+      ruleCount,
+      allOffenses,
+      ruleOffenses,
+      context
+    }
+
+    if (totalWouldBeIgnored > 0) {
+      processingResult.totalWouldBeIgnored = totalWouldBeIgnored
+    }
+
+    return processingResult
+  }
+
+  /**
+   * Returns the default number of parallel jobs based on available CPU cores.
+   * Returns 1 if parallelism detection fails.
+   */
+  static defaultJobs(): number {
+    try {
+      return availableParallelism()
+    } catch {
+      return 1
+    }
+  }
 }

package/src/cli/file-url.ts

@@ -0,0 +1,6 @@
+import { resolve } from "node:path"
+
+export function fileUrl(filePath: string): string {
+  const absolutePath = resolve(filePath)
+  return `file://${absolutePath}`
+}

package/src/cli/formatters/detailed-formatter.ts

@@ -2,6 +2,8 @@ import { colorize, Highlighter, type ThemeInput, DEFAULT_THEME } from "@herb-too
 
 import { BaseFormatter } from "./base-formatter.js"
 import { LineWrapper } from "@herb-tools/highlighter"
+import { ruleDocumentationUrl } from "../../urls.js"
+import { fileUrl } from "../file-url.js"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { ProcessedFile } from "../file-processor.js"
@@ -27,24 +29,24 @@ export class DetailedFormatter extends BaseFormatter {
       await this.highlighter.initialize()
     }
 
+    const correctableTag = colorize(colorize("[Correctable]", "green"), "bold")
+    const autocorrectableSet = new Set(
+      allOffenses.filter(item => item.autocorrectable).map(item => item.offense)
+    )
+
     if (isSingleFile) {
       const { filename, content } = allOffenses[0]
-      const diagnostics = allOffenses.map(item => {
-        if (item.autocorrectable && item.offense.code) {
-          return {
-            ...item.offense,
-            message: `${item.offense.message} ${colorize(colorize("[Correctable]", "green"), "bold")}`
-          }
-        }
-        return item.offense
-      })
+      const diagnostics = allOffenses.map(item => item.offense)
 
       const highlighted = this.highlighter.highlight(filename, content, {
         diagnostics: diagnostics,
         splitDiagnostics: true,
         contextLines: 2,
         wrapLines: this.wrapLines,
-        truncateLines: this.truncateLines
+        truncateLines: this.truncateLines,
+        codeUrlBuilder: ruleDocumentationUrl,
+        fileUrlBuilder: (path) => fileUrl(path),
+        suffixBuilder: (diagnostic) => autocorrectableSet.has(diagnostic) ? correctableTag : undefined,
       })
 
       console.log(`\n${highlighted}`)
@@ -54,19 +56,15 @@ export class DetailedFormatter extends BaseFormatter {
       for (let i = 0; i < allOffenses.length; i++) {
         const { filename, offense, content, autocorrectable } = allOffenses[i]
 
-        let modifiedOffense = offense
-
-        if (autocorrectable && offense.code) {
-          modifiedOffense = {
-            ...offense,
-            message: `${offense.message} ${colorize(colorize("[Correctable]", "green"), "bold")}`
-          }
-        }
-
-        const formatted = this.highlighter.highlightDiagnostic(filename, modifiedOffense, content, {
+        const codeUrl = offense.code ? ruleDocumentationUrl(offense.code) : undefined
+        const suffix = autocorrectable ? correctableTag : undefined
+        const formatted = this.highlighter.highlightDiagnostic(filename, offense, content, {
           contextLines: 2,
           wrapLines: this.wrapLines,
-          truncateLines: this.truncateLines
+          truncateLines: this.truncateLines,
+          codeUrl,
+          fileUrl: fileUrl(filename),
+          suffix,
         })
         console.log(`\n${formatted}`)