@herb-tools/linter 0.4.2 → 0.5.0

package/docs/rules/erb-requires-trailing-newline.md

@@ -0,0 +1,37 @@
+# Linter Rule: Enforce trailing newline
+
+**Rule:** `erb-requires-trailing-newline`
+
+## Description
+
+This rule enforces that all HTML+ERB template files end with exactly one trailing newline character. This is a formatting convention widely adopted across many languages and tools.
+
+## Rationale
+
+Ensuring HTML+ERB files end with a single trailing newline aligns with POSIX conventions, where text files should end with a newline character.
+
+This practice avoids unnecessary diffs from editors or formatters that auto-insert final newlines, improving compatibility with command-line tools and version control systems. It also helps maintain a clean, predictable structure across view files.
+
+Trailing newlines are a common convention in Ruby and are enforced by tools like RuboCop and many Git-based workflows.
+
+## Examples
+
+### ✅ Good
+
+```
+<%= render partial: "header" %>
+<%= render partial: "footer" %>
+```
+
+### 🚫 Bad
+
+```erb
+<%= render partial: "header" %>
+<%= render partial: "footer" %>▌
+```
+
+## References
+
+- [POSIX: Text files and trailing newlines](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206)
+- [Git: Trailing newlines and diffs](https://git-scm.com/docs/git-diff#_generating_patches_with_p)
+- [EditorConfig: `insert_final_newline`](https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties#insert_final_newline)

package/docs/rules/html-anchor-require-href.md

@@ -4,7 +4,7 @@
 
 ## Description
 
-Disallow the use of anchor tags without anhref attribute in HTML templates. Use if you want to perform an action without having the user navigated to a new URL.
+Disallow the use of anchor tags without an `href` attribute in HTML templates. Use if you want to perform an action without having the user navigated to a new URL.
 
 ## Rationale
 

package/docs/rules/html-aria-level-must-be-valid.md

@@ -0,0 +1,37 @@
+# Linter Rule: `aria-level` must be between 1 and 6
+
+**Rule:** `html-aria-level-must-be-valid`
+
+## Description
+
+Ensure that the value of the `aria-level` attribute is a valid heading level: an integer between `1` and `6`. This attribute is used with `role="heading"` to indicate a heading level for non-semantic elements like `<div>` or `<span>`.
+
+## Rationale
+
+The WAI-ARIA specification defines `aria-level` as an integer between `1` (highest/most important) and `6` (lowest/subheading). Any other value is invalid and may confuse screen readers or fail accessibility audits.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div role="heading" aria-level="1">Main</div>
+<div role="heading" aria-level="6">Footnote</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div role="heading" aria-level="-1">Negative</div>
+
+<div role="heading" aria-level="0">Main</div>
+
+<div role="heading" aria-level="7">Too deep</div>
+
+<div role="heading" aria-level="foo">Invalid</div>
+```
+
+## References
+
+- [ARIA: `heading` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role)
+- [ARIA: `aria-level` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level)

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

@@ -0,0 +1,84 @@
+# Linter Rule: Disallow parser errors in HTML+ERB documents
+
+**Rule:** `parser-no-errors`
+
+## Description
+
+Report parser errors as linting offenses. This rule surfaces syntax errors, malformed HTML, and other parsing issues that prevent the document from being correctly parsed.
+
+## Rationale
+
+Parser errors indicate fundamental structural problems in HTML+ERB documents that can lead to unexpected rendering behavior, accessibility issues, and maintenance difficulties. These errors should be fixed before addressing other linting concerns as they represent invalid markup that browsers may interpret inconsistently.
+
+By surfacing parser errors through the linter, developers can catch these critical issues when running lint checks directly, without needing to switch to the language server or other tools.
+
+## Examples
+
+### ✅ Good
+
+```html
+<h2>Welcome to our site</h2>
+<p>This is a paragraph with proper structure.</p>
+
+<div class="container">
+  <img src="image.jpg" alt="Description">
+</div>
+```
+
+```erb
+<h2><%= @page.title %></h2>
+<p><%= @page.description %></p>
+
+<% if user_signed_in? %>
+  <div class="user-section">
+    <%= current_user.name %>
+  </div>
+<% end %>
+```
+
+### 🚫 Bad
+
+```html
+<!-- Mismatched closing tag -->
+<h2>Welcome to our site</h3>
+
+<!-- Unclosed element -->
+<div>
+  <p>This paragraph is never closed
+</div>
+
+<!-- Missing opening tag -->
+Some content
+</div>
+```
+
+```erb
+<!-- Invalid Ruby syntax in ERB -->
+<%= 1 + %>
+
+<!-- Mismatched quotes -->
+<div class="container'>Content</div>
+
+<!-- Void element with closing tag -->
+<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)
+* [W3C HTML Validator](https://validator.w3.org/)
+* [ERB Template Guide](https://guides.rubyonrails.org/layouts_and_rendering.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -33,9 +33,9 @@
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.4.2",
-    "@herb-tools/highlighter": "0.4.2",
-    "@herb-tools/node-wasm": "0.4.2",
+    "@herb-tools/core": "0.5.0",
+    "@herb-tools/highlighter": "0.5.0",
+    "@herb-tools/node-wasm": "0.5.0",
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli/argument-parser.ts

@@ -11,9 +11,11 @@ import type { ThemeInput } from "@herb-tools/highlighter"
 
 import { name, version } from "../../package.json"
 
+export type FormatOption = "simple" | "detailed" | "json" | "github"
+
 export interface ParsedArguments {
   pattern: string
-  formatOption: 'simple' | 'detailed'
+  formatOption: FormatOption
   showTiming: boolean
   theme: ThemeInput
   wrapLines: boolean
@@ -32,9 +34,11 @@ export class ArgumentParser {
     Options:
       -h, --help       show help
       -v, --version    show version
-      --format         output format (simple|detailed) [default: detailed]
+      --format         output format (simple|detailed|json|github) [default: detailed]
       --simple         use simple output format (shortcut for --format simple)
-      --theme          syntax highlighting theme (${THEME_NAMES.join('|')}) or path to custom theme file [default: ${DEFAULT_THEME}]
+      --json           use JSON output format (shortcut for --format json)
+      --github         use GitHub Actions output format (shortcut for --format github)
+      --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
@@ -45,15 +49,17 @@ export class ArgumentParser {
     const { values, positionals } = parseArgs({
       args: argv.slice(2),
       options: {
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean', short: 'v' },
-        format: { type: 'string' },
-        simple: { type: 'boolean' },
-        theme: { type: 'string' },
-        'no-color': { type: 'boolean' },
-        'no-timing': { type: 'boolean' },
-        'no-wrap-lines': { type: 'boolean' },
-        'truncate-lines': { type: 'boolean' }
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        format: { type: "string" },
+        simple: { type: "boolean" },
+        json: { type: "boolean" },
+        github: { type: "boolean" },
+        theme: { type: "string" },
+        "no-color": { type: "boolean" },
+        "no-timing": { type: "boolean" },
+        "no-wrap-lines": { type: "boolean" },
+        "truncate-lines": { type: "boolean" }
       },
       allowPositionals: true
     })
@@ -69,8 +75,8 @@ export class ArgumentParser {
       process.exit(0)
     }
 
-    let formatOption: 'simple' | 'detailed' = 'detailed'
-    if (values.format && (values.format === "detailed" || values.format === "simple")) {
+    let formatOption: FormatOption = "detailed"
+    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json" || values.format === "github")) {
       formatOption = values.format
     }
 
@@ -78,21 +84,29 @@ export class ArgumentParser {
       formatOption = "simple"
     }
 
-    if (values['no-color']) {
+    if (values.json) {
+      formatOption = "json"
+    }
+
+    if (values.github) {
+      formatOption = "github"
+    }
+
+    if (values["no-color"]) {
       process.env.NO_COLOR = "1"
     }
 
-    const showTiming = !values['no-timing']
+    const showTiming = !values["no-timing"]
 
-    let wrapLines = !values['no-wrap-lines']
+    let wrapLines = !values["no-wrap-lines"]
     let truncateLines = false
 
-    if (values['truncate-lines']) {
+    if (values["truncate-lines"]) {
       truncateLines = true
       wrapLines = false
     }
 
-    if (!values['no-wrap-lines'] && values['truncate-lines']) {
+    if (!values["no-wrap-lines"] && values["truncate-lines"]) {
       console.error("Error: Line wrapping and --truncate-lines cannot be used together. Use --no-wrap-lines with --truncate-lines.")
       process.exit(1)
     }

package/src/cli/file-processor.ts

@@ -4,32 +4,33 @@ import { Herb } from "@herb-tools/node-wasm"
 import { Linter } from "../linter.js"
 import { colorize } from "@herb-tools/highlighter"
 import type { Diagnostic } from "@herb-tools/core"
+import type { FormatOption } from "./argument-parser.js"
 
 export interface ProcessedFile {
   filename: string
-  diagnostic: Diagnostic
+  offense: Diagnostic
   content: string
 }
 
 export interface ProcessingResult {
   totalErrors: number
   totalWarnings: number
-  filesWithIssues: number
+  filesWithOffenses: number
   ruleCount: number
-  allDiagnostics: ProcessedFile[]
-  ruleViolations: Map<string, { count: number, files: Set<string> }>
+  allOffenses: ProcessedFile[]
+  ruleOffenses: Map<string, { count: number, files: Set<string> }>
 }
 
 export class FileProcessor {
   private linter: Linter | null = null
 
-  async processFiles(files: string[]): Promise<ProcessingResult> {
+  async processFiles(files: string[], formatOption: FormatOption = 'detailed'): Promise<ProcessingResult> {
     let totalErrors = 0
     let totalWarnings = 0
-    let filesWithIssues = 0
+    let filesWithOffenses = 0
     let ruleCount = 0
-    const allDiagnostics: ProcessedFile[] = []
-    const ruleViolations = new Map<string, { count: number, files: Set<string> }>()
+    const allOffenses: ProcessedFile[] = []
+    const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
 
     for (const filename of files) {
       const filePath = resolve(filename)
@@ -38,49 +39,54 @@ export class FileProcessor {
       const parseResult = Herb.parse(content)
 
       if (parseResult.errors.length > 0) {
-        console.error(`${colorize(filename, "cyan")} - ${colorize("Parse errors:", "brightRed")}`)
+        if (formatOption !== 'json' && formatOption !== 'github') {
+          console.error(`${colorize(filename, "cyan")} - ${colorize("Parse errors:", "brightRed")}`)
 
+          for (const error of parseResult.errors) {
+            console.error(`  ${colorize("✗", "brightRed")} ${error.message}`)
+          }
+        }
+
+        // Add parse errors to offenses for JSON output
         for (const error of parseResult.errors) {
-          console.error(`  ${colorize("✗", "brightRed")} ${error.message}`)
+          allOffenses.push({ filename, offense: error, content })
         }
 
         totalErrors++
-        filesWithIssues++
+        filesWithOffenses++
         continue
       }
 
       if (!this.linter) {
-        this.linter = new Linter()
+        this.linter = new Linter(Herb)
       }
 
-      const lintResult = this.linter.lint(parseResult.value)
+      const lintResult = this.linter.lint(content, { fileName: filename })
 
-      // Get rule count on first file
       if (ruleCount === 0) {
         ruleCount = this.linter.getRuleCount()
       }
 
       if (lintResult.offenses.length === 0) {
-        if (files.length === 1) {
+        if (files.length === 1 && formatOption !== 'json' && formatOption !== 'github') {
           console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize("No issues found", "green")}`)
         }
       } else {
-        // Collect messages for later display
         for (const offense of lintResult.offenses) {
-          allDiagnostics.push({ filename, diagnostic: offense, content })
+          allOffenses.push({ filename, offense: offense, content })
 
-          const ruleData = ruleViolations.get(offense.rule) || { count: 0, files: new Set() }
+          const ruleData = ruleOffenses.get(offense.rule) || { count: 0, files: new Set() }
           ruleData.count++
           ruleData.files.add(filename)
-          ruleViolations.set(offense.rule, ruleData)
+          ruleOffenses.set(offense.rule, ruleData)
         }
 
         totalErrors += lintResult.errors
         totalWarnings += lintResult.warnings
-        filesWithIssues++
+        filesWithOffenses++
       }
     }
 
-    return { totalErrors, totalWarnings, filesWithIssues, ruleCount, allDiagnostics, ruleViolations }
+    return { totalErrors, totalWarnings, filesWithOffenses, ruleCount, allOffenses, ruleOffenses }
   }
 }

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

@@ -3,9 +3,9 @@ import type { ProcessedFile } from "../file-processor.js"
 
 export abstract class BaseFormatter {
   abstract format(
-    allDiagnostics: ProcessedFile[],
+    allOffenses: ProcessedFile[],
     isSingleFile?: boolean
   ): Promise<void>
 
-  abstract formatFile(filename: string, diagnostics: Diagnostic[]): void
+  abstract formatFile(filename: string, offenses: Diagnostic[]): void
 }

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

@@ -18,8 +18,8 @@ export class DetailedFormatter extends BaseFormatter {
     this.truncateLines = truncateLines
   }
 
-  async format(allDiagnostics: ProcessedFile[], isSingleFile: boolean = false): Promise<void> {
-    if (allDiagnostics.length === 0) return
+  async format(allOffenses: ProcessedFile[], isSingleFile: boolean = false): Promise<void> {
+    if (allOffenses.length === 0) return
 
     if (!this.highlighter) {
       this.highlighter = new Highlighter(this.theme)
@@ -28,8 +28,8 @@ export class DetailedFormatter extends BaseFormatter {
 
     if (isSingleFile) {
       // For single file, use inline diagnostics with syntax highlighting
-      const { filename, content } = allDiagnostics[0]
-      const diagnostics = allDiagnostics.map(item => item.diagnostic)
+      const { filename, content } = allOffenses[0]
+      const diagnostics = allOffenses.map(item => item.offense)
 
       const highlighted = this.highlighter.highlight(filename, content, {
         diagnostics: diagnostics,
@@ -42,11 +42,11 @@ export class DetailedFormatter extends BaseFormatter {
       console.log(`\n${highlighted}`)
     } else {
       // For multiple files, show individual diagnostics with syntax highlighting
-      const totalMessageCount = allDiagnostics.length
+      const totalMessageCount = allOffenses.length
 
-      for (let i = 0; i < allDiagnostics.length; i++) {
-        const { filename, diagnostic, content } = allDiagnostics[i]
-        const formatted = this.highlighter.highlightDiagnostic(filename, diagnostic, content, { 
+      for (let i = 0; i < allOffenses.length; i++) {
+        const { filename, offense, content } = allOffenses[i]
+        const formatted = this.highlighter.highlightDiagnostic(filename, offense, content, { 
           contextLines: 2, 
           wrapLines: this.wrapLines,
           truncateLines: this.truncateLines
@@ -67,7 +67,7 @@ export class DetailedFormatter extends BaseFormatter {
     }
   }
 
-  formatFile(_filename: string, _diagnostics: Diagnostic[]): void {
+  formatFile(_filename: string, _offenses: Diagnostic[]): void {
     // Not used in detailed formatter
     throw new Error("formatFile is not implemented for DetailedFormatter")
   }

package/src/cli/formatters/github-actions-formatter.ts

@@ -0,0 +1,70 @@
+import { BaseFormatter } from "./base-formatter.js"
+
+import type { Diagnostic } from "@herb-tools/core"
+import type { ProcessedFile } from "../file-processor.js"
+
+// https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
+export class GitHubActionsFormatter extends BaseFormatter {
+  private static readonly MESSAGE_ESCAPE_MAP: Record<string, string> = {
+    '%': '%25',
+    '\n': '%0A',
+    '\r': '%0D'
+  }
+
+  private static readonly PARAM_ESCAPE_MAP: Record<string, string> = {
+    '%': '%25',
+    '\n': '%0A',
+    '\r': '%0D',
+    ':': '%3A',
+    ',': '%2C'
+  }
+
+  async format(allDiagnostics: ProcessedFile[]): Promise<void> {
+    for (const { filename, offense } of allDiagnostics) {
+      this.formatDiagnostic(filename, offense)
+    }
+
+    if (allDiagnostics.length > 0) {
+      console.log()
+    }
+  }
+
+  formatFile(filename: string, diagnostics: Diagnostic[]): void {
+    for (const diagnostic of diagnostics) {
+      this.formatDiagnostic(filename, diagnostic)
+    }
+  }
+
+  // GitHub Actions annotation format:
+  // ::{level} file={file},line={line},col={col}::{message}
+  //
+  private formatDiagnostic(filename: string, diagnostic: Diagnostic): void {
+    const level = diagnostic.severity === "error" ? "error" : "warning"
+    const { line, column } = diagnostic.location.start
+
+    const escapedFilename = this.escapeParam(filename)
+    const message = this.escapeMessage(diagnostic.message)
+
+    let fullMessage = message
+
+    if (diagnostic.code) {
+      fullMessage += ` [${diagnostic.code}]`
+    }
+
+    console.log(`\n::${level} file=${escapedFilename},line=${line},col=${column}::${fullMessage}`)
+  }
+
+  private escapeMessage(string: string): string {
+    return string.replace(
+      new RegExp(Object.keys(GitHubActionsFormatter.MESSAGE_ESCAPE_MAP).map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g'),
+      match => GitHubActionsFormatter.MESSAGE_ESCAPE_MAP[match]
+    )
+  }
+
+  private escapeParam(string: string): string {
+    return string.replace(
+      new RegExp(Object.keys(GitHubActionsFormatter.PARAM_ESCAPE_MAP).map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g'),
+      match => GitHubActionsFormatter.PARAM_ESCAPE_MAP[match]
+    )
+  }
+}

package/src/cli/formatters/index.ts

@@ -1,3 +1,5 @@
 export { BaseFormatter } from "./base-formatter.js"
 export { SimpleFormatter } from "./simple-formatter.js"
 export { DetailedFormatter } from "./detailed-formatter.js"
+export { JSONFormatter, type JSONOutput } from "./json-formatter.js"
+export { GitHubActionsFormatter } from "./github-actions-formatter.js"

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

@@ -0,0 +1,107 @@
+import { BaseFormatter } from "./base-formatter.js"
+
+import type { Diagnostic, SerializedDiagnostic } from "@herb-tools/core"
+import type { ProcessedFile } from "../file-processor.js"
+
+interface JSONOffense extends SerializedDiagnostic {
+  filename: string
+}
+
+interface JSONSummary {
+  filesChecked: number
+  filesWithOffenses: number
+  totalErrors: number
+  totalWarnings: number
+  totalOffenses: number
+  ruleCount: number
+}
+
+interface JSONTiming {
+  startTime: string
+  duration: number
+}
+
+export interface JSONOutput {
+  offenses: JSONOffense[]
+  summary: JSONSummary | null
+  timing: JSONTiming | null
+  completed: boolean
+  clean: boolean | null
+  message: string | null
+}
+
+interface JSONFormatOptions {
+  files: string[]
+  totalErrors: number
+  totalWarnings: number
+  filesWithOffenses: number
+  ruleCount: number
+  startTime: number
+  startDate: Date
+  showTiming: boolean
+}
+
+export class JSONFormatter extends BaseFormatter {
+  async format(allOffenses: ProcessedFile[]): Promise<void> {
+    const jsonOffenses: JSONOffense[] = allOffenses.map(({ filename, offense }) => ({
+      filename,
+      message: offense.message,
+      location: offense.location.toJSON(),
+      severity: offense.severity,
+      code: offense.code,
+      source: offense.source
+    }))
+
+    const output: JSONOutput = {
+      offenses: jsonOffenses,
+      summary: null,
+      timing: null,
+      completed: true,
+      clean: jsonOffenses.length === 0,
+      message: null
+    }
+
+    console.log(JSON.stringify(output, null, 2))
+  }
+
+  async formatWithSummary(allOffenses: ProcessedFile[], options: JSONFormatOptions): Promise<void> {
+    const jsonOffenses: JSONOffense[] = allOffenses.map(({ filename, offense }) => ({
+      filename,
+      message: offense.message,
+      location: offense.location.toJSON(),
+      severity: offense.severity,
+      code: offense.code,
+      source: offense.source
+    }))
+
+    const summary: JSONSummary = {
+      filesChecked: options.files.length,
+      filesWithOffenses: options.filesWithOffenses,
+      totalErrors: options.totalErrors,
+      totalWarnings: options.totalWarnings,
+      totalOffenses: options.totalErrors + options.totalWarnings,
+      ruleCount: options.ruleCount
+    }
+
+    const output: JSONOutput = {
+      offenses: jsonOffenses,
+      summary,
+      timing: null,
+      completed: true,
+      clean: options.totalErrors === 0 && options.totalWarnings === 0,
+      message: null
+    }
+
+    const duration = Date.now() - options.startTime
+    output.timing = options.showTiming ? {
+      startTime: options.startDate.toISOString(),
+      duration: duration
+    } : null
+
+    console.log(JSON.stringify(output, null, 2))
+  }
+
+  formatFile(_filename: string, _offenses: Diagnostic[]): void {
+    // Not used in JSON formatter, everything is handled in format()
+  }
+}