From 765c61ba80ee15d3d74f381f043030e137a69660 Mon Sep 17 00:00:00 2001
From: Marco Roth <marco.roth@intergga.ch>
Date: Thu, 5 Mar 2026 15:04:48 +0100
Subject: [PATCH] Linter: Implement `herb-formatter-well-formatted` rule

---
 .../packages/linter/docs/rules/README.md      |   1 +
 .../rules/herb-formatter-well-formatted.md    |  82 ++++++
 javascript/packages/linter/package.json       |   1 +
 javascript/packages/linter/project.json       |   1 +
 javascript/packages/linter/src/linter.ts      |   3 +-
 javascript/packages/linter/src/rules.ts       |   2 +
 .../rules/herb-formatter-well-formatted.ts    | 245 ++++++++++++++++++
 javascript/packages/linter/src/types.ts       |   6 +-
 .../herb-formatter-well-formatted.test.ts     | 153 +++++++++++
 9 files changed, 491 insertions(+), 3 deletions(-)
 create mode 100644 javascript/packages/linter/docs/rules/herb-formatter-well-formatted.md
 create mode 100644 javascript/packages/linter/src/rules/herb-formatter-well-formatted.ts
 create mode 100644 javascript/packages/linter/test/rules/herb-formatter-well-formatted.test.ts

diff --git a/javascript/packages/linter/docs/rules/README.md b/javascript/packages/linter/docs/rules/README.md
index d16440e79..3aa602efb 100644
--- a/javascript/packages/linter/docs/rules/README.md
+++ b/javascript/packages/linter/docs/rules/README.md
@@ -38,6 +38,7 @@ This page contains documentation for all Herb Linter rules.
 - [`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.
+- [`herb-formatter-well-formatted`](./herb-formatter-well-formatted.md) - Check source is well-formatted.
 - [`html-allowed-script-type`](./html-allowed-script-type.md) - Restrict allowed `type` attributes for `<script>` tags
 - [`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.
diff --git a/javascript/packages/linter/docs/rules/herb-formatter-well-formatted.md b/javascript/packages/linter/docs/rules/herb-formatter-well-formatted.md
new file mode 100644
index 000000000..86dd47753
--- /dev/null
+++ b/javascript/packages/linter/docs/rules/herb-formatter-well-formatted.md
@@ -0,0 +1,82 @@
+# Linter Rule: Check source is well-formatted
+
+**Rule:** `herb-formatter-well-formatted`
+
+## Description
+
+This rule checks if the source code matches the output of the Herb Formatter. It shows formatting issues as diagnostics (squiggly lines in editors), allowing you to see what would change when formatting is applied.
+
+## Configuration
+
+This rule is **disabled by default**. To enable it, you must:
+
+1. Enable the formatter in your `.herb.yml`
+2. Enable this rule
+
+```yaml
+formatter:
+  enabled: true
+
+linter:
+  rules:
+    herb-formatter-well-formatted:
+      enabled: true
+```
+
+The rule will only run when both conditions are met. It also respects the formatter's file exclusion patterns.
+
+## Rationale
+
+This rule bridges the gap between linting and formatting by surfacing formatting issues as lint warnings. This is useful when:
+
+* You want to see formatting issues inline in your editor before running the formatter
+* You want CI to fail on unformatted code without actually modifying files
+* You prefer reviewing formatting changes before applying them
+
+To fix the issues, run the Herb formatter CLI: `herb format`.
+
+## Messages
+
+The rule generates contextual messages based on the type of formatting issue:
+
+* **Incorrect indentation: expected N spaces, found M** - When indentation differs
+* **Unexpected whitespace** - When extra whitespace should be removed
+* **Missing whitespace** - When whitespace should be added
+* **Incorrect line breaks** - When line break count differs
+* **Formatting differs from expected** - Generic message for other differences
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div>
+  <p>Hello</p>
+</div>
+```
+
+```erb
+<%= render partial: "header" %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>
+<p>Hello</p>
+</div>
+```
+
+```erb
+<div>   </div>
+```
+
+```erb
+<div>
+    <p>Too much indentation</p>
+</div>
+```
+
+## References
+
+- [GitHub Issue #916](https://github.com/marcoroth/herb/issues/916)
diff --git a/javascript/packages/linter/package.json b/javascript/packages/linter/package.json
index 756110c40..81f271a2f 100644
--- a/javascript/packages/linter/package.json
+++ b/javascript/packages/linter/package.json
@@ -48,6 +48,7 @@
   "dependencies": {
     "@herb-tools/config": "0.8.10",
     "@herb-tools/core": "0.8.10",
+    "@herb-tools/formatter": "0.8.10",
     "@herb-tools/highlighter": "0.8.10",
     "@herb-tools/node-wasm": "0.8.10",
     "@herb-tools/printer": "0.8.10",
diff --git a/javascript/packages/linter/project.json b/javascript/packages/linter/project.json
index f0b9b9154..ab04ff7e5 100644
--- a/javascript/packages/linter/project.json
+++ b/javascript/packages/linter/project.json
@@ -13,6 +13,7 @@
         "@herb-tools/config:build",
         "@herb-tools/core:build",
         "@herb-tools/browser:build",
+        "@herb-tools/formatter:build",
         "@herb-tools/highlighter:build",
         "@herb-tools/printer:build",
         "@herb-tools/rewriter:build"
diff --git a/javascript/packages/linter/src/linter.ts b/javascript/packages/linter/src/linter.ts
index 3cbac6a04..7a7d5693a 100644
--- a/javascript/packages/linter/src/linter.ts
+++ b/javascript/packages/linter/src/linter.ts
@@ -368,7 +368,8 @@ export class Linter {
     context = {
       ...context,
       validRuleNames: this.getAvailableRules().map(ruleClass => ruleClass.ruleName),
-      ignoredOffensesByLine
+      ignoredOffensesByLine,
+      config: this.config
     }
 
     const regularRules = this.rules.filter(ruleClass => ruleClass.ruleName !== "herb-disable-comment-unnecessary")
diff --git a/javascript/packages/linter/src/rules.ts b/javascript/packages/linter/src/rules.ts
index ad415815a..9b3965807 100644
--- a/javascript/packages/linter/src/rules.ts
+++ b/javascript/packages/linter/src/rules.ts
@@ -38,6 +38,7 @@ import { HerbDisableCommentNoDuplicateRulesRule } from "./rules/herb-disable-com
 import { HerbDisableCommentNoRedundantAllRule } from "./rules/herb-disable-comment-no-redundant-all.js"
 import { HerbDisableCommentUnnecessaryRule } from "./rules/herb-disable-comment-unnecessary.js"
 import { HerbDisableCommentValidRuleNameRule } from "./rules/herb-disable-comment-valid-rule-name.js"
+import { HerbFormatterWellFormattedRule } from "./rules/herb-formatter-well-formatted.js"
 
 import { HTMLAllowedScriptTypeRule } from "./rules/html-allowed-script-type.js"
 import { HTMLAnchorRequireHrefRule } from "./rules/html-anchor-require-href.js"
@@ -120,6 +121,7 @@ export const rules: RuleClass[] = [
   HerbDisableCommentNoRedundantAllRule,
   HerbDisableCommentUnnecessaryRule,
   HerbDisableCommentValidRuleNameRule,
+  HerbFormatterWellFormattedRule,
 
   HTMLAllowedScriptTypeRule,
   HTMLAnchorRequireHrefRule,
diff --git a/javascript/packages/linter/src/rules/herb-formatter-well-formatted.ts b/javascript/packages/linter/src/rules/herb-formatter-well-formatted.ts
new file mode 100644
index 000000000..ba35c123a
--- /dev/null
+++ b/javascript/packages/linter/src/rules/herb-formatter-well-formatted.ts
@@ -0,0 +1,245 @@
+import { Herb } from "@herb-tools/node-wasm"
+import { Location } from "@herb-tools/core"
+import { Formatter } from "@herb-tools/formatter"
+
+import { SourceRule } from "../types.js"
+import { positionFromOffset } from "./rule-utils.js"
+
+import type { UnboundLintOffense, LintContext, FullRuleConfig } from "../types.js"
+
+interface DiffRange {
+  startOffset: number
+  endOffset: number
+  originalContent: string
+  formattedContent: string
+}
+
+export class HerbFormatterWellFormattedRule extends SourceRule {
+  static autocorrectable = false
+  static ruleName = "herb-formatter-well-formatted"
+
+  get defaultConfig(): FullRuleConfig {
+    return {
+      enabled: false,
+      severity: "warning"
+    }
+  }
+
+  isEnabled(_source: string, context?: Partial<LintContext>): boolean {
+    const config = context?.config
+
+    if (!config) return true
+    if (!config.isFormatterEnabled) return false
+    if (context?.fileName && !config.isFormatterEnabledForPath(context.fileName)) return false
+
+    return true
+  }
+
+  check(source: string, context?: Partial<LintContext>): UnboundLintOffense[] {
+    const offenses: UnboundLintOffense[] = []
+
+    if (source.length === 0) return offenses
+
+    try {
+      const config = context?.config
+      const filePath = context?.fileName
+      const formatter = config ? Formatter.from(Herb, config) : new Formatter(Herb)
+      const formatted = formatter.format(source, {}, filePath)
+
+      if (source === formatted) return offenses
+
+      const diffs = this.computeDiffs(source, formatted)
+
+      for (const diff of diffs) {
+        const startPosition = positionFromOffset(source, diff.startOffset)
+        const endPosition = positionFromOffset(source, diff.endOffset)
+        const location = Location.from(startPosition.line, startPosition.column, endPosition.line, endPosition.column)
+        const message = this.generateMessage(diff)
+
+        offenses.push({
+          rule: this.ruleName,
+          code: this.ruleName,
+          source: "Herb Linter",
+          message,
+          location
+        })
+      }
+    } catch {
+      // Skip silently on formatting errors
+    }
+
+    return offenses
+  }
+
+  private computeDiffs(original: string, formatted: string): DiffRange[] {
+    const diffs: DiffRange[] = []
+    const originalLength = original.length
+    const formattedLength = formatted.length
+
+    let originalIndex = 0
+    let formattedIndex = 0
+
+    while (originalIndex < originalLength || formattedIndex < formattedLength) {
+      if (originalIndex < originalLength && formattedIndex < formattedLength && original[originalIndex] === formatted[formattedIndex]) {
+        originalIndex++
+        formattedIndex++
+        continue
+      }
+
+      const diffStartOriginal = originalIndex
+      const diffStartFormatted = formattedIndex
+      const syncPoint = this.findSyncPoint(original, formatted, originalIndex, formattedIndex)
+
+      if (syncPoint) {
+        const originalEnd = syncPoint.originalIndex
+        const formattedEnd = syncPoint.formattedIndex
+
+        if (originalEnd > diffStartOriginal || formattedEnd > diffStartFormatted) {
+          diffs.push({
+            startOffset: diffStartOriginal,
+            endOffset: Math.max(diffStartOriginal + 1, originalEnd),
+            originalContent: original.slice(diffStartOriginal, originalEnd),
+            formattedContent: formatted.slice(diffStartFormatted, formattedEnd)
+          })
+        }
+
+        originalIndex = originalEnd
+        formattedIndex = formattedEnd
+      } else {
+        diffs.push({
+          startOffset: diffStartOriginal,
+          endOffset: originalLength,
+          originalContent: original.slice(diffStartOriginal),
+          formattedContent: formatted.slice(diffStartFormatted)
+        })
+
+        break
+      }
+    }
+
+    return this.coalesceDiffs(diffs)
+  }
+
+  private findSyncPoint(original: string, formatted: string, originalStart: number, formattedStart: number): { originalIndex: number; formattedIndex: number } | null {
+    const originalLength = original.length
+    const formattedLength = formatted.length
+    const maxLookahead = 100
+    const minMatchLength = 3
+
+    for (let originalOffset = 1; originalOffset <= maxLookahead && originalStart + originalOffset <= originalLength; originalOffset++) {
+      for (let formattedOffset = 1; formattedOffset <= maxLookahead && formattedStart + formattedOffset <= formattedLength; formattedOffset++) {
+        const originalPosition = originalStart + originalOffset
+        const formattedPosition = formattedStart + formattedOffset
+
+        let matchLength = 0
+
+        while (
+          originalPosition + matchLength < originalLength &&
+          formattedPosition + matchLength < formattedLength &&
+          original[originalPosition + matchLength] === formatted[formattedPosition + matchLength]
+        ) {
+          matchLength++
+          if (matchLength >= minMatchLength) {
+            return { originalIndex: originalPosition, formattedIndex: formattedPosition }
+          }
+        }
+
+        if (originalPosition === originalLength && formattedPosition === formattedLength) {
+          return { originalIndex: originalPosition, formattedIndex: formattedPosition }
+        }
+      }
+    }
+
+    if (originalStart >= originalLength && formattedStart < formattedLength) {
+      return { originalIndex: originalLength, formattedIndex: formattedLength }
+    }
+
+    if (formattedStart >= formattedLength && originalStart < originalLength) {
+      return { originalIndex: originalLength, formattedIndex: formattedLength }
+    }
+
+    return null
+  }
+
+  private coalesceDiffs(diffs: DiffRange[]): DiffRange[] {
+    if (diffs.length <= 1) return diffs
+
+    const coalesced: DiffRange[] = []
+    let current = diffs[0]
+
+    for (let i = 1; i < diffs.length; i++) {
+      const next = diffs[i]
+
+      if (next.startOffset <= current.endOffset + 1) {
+        current = {
+          startOffset: current.startOffset,
+          endOffset: Math.max(current.endOffset, next.endOffset),
+          originalContent: current.originalContent + next.originalContent,
+          formattedContent: current.formattedContent + next.formattedContent
+        }
+      } else {
+        coalesced.push(current)
+        current = next
+      }
+    }
+
+    coalesced.push(current)
+
+    return coalesced
+  }
+
+  private generateMessage(diff: DiffRange): string {
+    const { originalContent, formattedContent } = diff
+
+    const originalIndentMatch = originalContent.match(/^[ \t]+/)
+    const formattedIndentMatch = formattedContent.match(/^[ \t]+/)
+
+    if (originalIndentMatch || formattedIndentMatch) {
+      const originalIndent = originalIndentMatch?.[0] || ""
+      const formattedIndent = formattedIndentMatch?.[0] || ""
+
+      if (originalIndent !== formattedIndent) {
+        const originalSpaces = this.countIndentation(originalIndent)
+        const formattedSpaces = this.countIndentation(formattedIndent)
+
+        if (originalSpaces !== formattedSpaces) {
+          return `Incorrect indentation: expected ${formattedSpaces} spaces, found ${originalSpaces}`
+        }
+      }
+    }
+
+    const originalIsWhitespace = /^[\s]+$/.test(originalContent)
+    const formattedIsWhitespace = /^[\s]+$/.test(formattedContent)
+
+    if (originalIsWhitespace && formattedContent === "") {
+      return "Unexpected whitespace"
+    }
+
+    if (originalContent === "" && formattedIsWhitespace) {
+      return "Missing whitespace"
+    }
+
+    const originalNewlines = (originalContent.match(/\n/g) || []).length
+    const formattedNewlines = (formattedContent.match(/\n/g) || []).length
+
+    if (originalNewlines !== formattedNewlines) {
+      return "Incorrect line breaks"
+    }
+
+    return "Formatting differs from expected"
+  }
+
+  private countIndentation(indent: string): number {
+    let count = 0
+
+    for (const char of indent) {
+      if (char === "\t") {
+        count += 2
+      } else {
+        count++
+      }
+    }
+
+    return count
+  }
+}
diff --git a/javascript/packages/linter/src/types.ts b/javascript/packages/linter/src/types.ts
index 92e1d3e2f..3133a5100 100644
--- a/javascript/packages/linter/src/types.ts
+++ b/javascript/packages/linter/src/types.ts
@@ -2,7 +2,7 @@ import { Diagnostic, LexResult, ParseResult, Location } from "@herb-tools/core"
 
 import type { rules } from "./rules.js"
 import type { Node, ParserOptions } from "@herb-tools/core"
-import type { RuleConfig } from "@herb-tools/config"
+import type { RuleConfig, Config } from "@herb-tools/config"
 import type { Mutable } from "@herb-tools/rewriter"
 
 export type { Mutable } from "@herb-tools/rewriter"
@@ -213,6 +213,7 @@ export interface LintContext {
   validRuleNames: string[] | undefined
   ignoredOffensesByLine: Map<number, Set<string>> | undefined
   ignoreDisableComments: boolean | undefined
+  config: Config | undefined
 }
 
 /**
@@ -222,7 +223,8 @@ export const DEFAULT_LINT_CONTEXT: LintContext = {
   fileName: undefined,
   validRuleNames: undefined,
   ignoredOffensesByLine: undefined,
-  ignoreDisableComments: undefined
+  ignoreDisableComments: undefined,
+  config: undefined
 } as const
 
 export abstract class SourceRule<TAutofixContext extends BaseAutofixContext = BaseAutofixContext> {
diff --git a/javascript/packages/linter/test/rules/herb-formatter-well-formatted.test.ts b/javascript/packages/linter/test/rules/herb-formatter-well-formatted.test.ts
new file mode 100644
index 000000000..f18ae8812
--- /dev/null
+++ b/javascript/packages/linter/test/rules/herb-formatter-well-formatted.test.ts
@@ -0,0 +1,153 @@
+import dedent from "dedent"
+
+import { describe, test, beforeAll, expect } from "vitest"
+
+import { Herb } from "@herb-tools/node-wasm"
+import { Linter } from "../../src/linter.js"
+import { Config } from "@herb-tools/config"
+
+import { HerbFormatterWellFormattedRule } from "../../src/rules/herb-formatter-well-formatted.js"
+
+function createTestConfig() {
+  return Config.fromObject({
+    formatter: {
+      enabled: true
+    },
+    linter: {
+      rules: {
+        "herb-formatter-well-formatted": { enabled: true }
+      }
+    }
+  })
+}
+
+function lintSource(source: string, context?: { fileName?: string }) {
+  const config = createTestConfig()
+  const linter = new Linter(Herb, [HerbFormatterWellFormattedRule], config)
+  const result = linter.lint(source, context)
+  return result.offenses.filter(o => o.rule === "herb-formatter-well-formatted")
+}
+
+describe("HerbFormatterWellFormattedRule", () => {
+  beforeAll(async () => {
+    await Herb.load()
+  })
+
+  describe("well-formatted source", () => {
+    test("should not report errors for already formatted HTML", () => {
+      const html = dedent`
+        <div>
+          <p>Hello</p>
+        </div>
+      `
+
+      const offenses = lintSource(html)
+      expect(offenses).toHaveLength(0)
+    })
+
+    test("should not report errors for simple one-line HTML", () => {
+      const html = `<p>Hello</p>`
+
+      const offenses = lintSource(html)
+      expect(offenses).toHaveLength(0)
+    })
+
+    test("should not report errors for empty source", () => {
+      const html = ``
+
+      const offenses = lintSource(html)
+      expect(offenses).toHaveLength(0)
+    })
+
+    test("should not report errors for formatted ERB", () => {
+      const html = `<div><%= @title %></div>`
+
+      const offenses = lintSource(html)
+      expect(offenses).toHaveLength(0)
+    })
+  })
+
+  describe("unformatted source", () => {
+    test("should report warning for incorrect indentation", () => {
+      const html = dedent`
+        <div>
+        <p>Hello</p>
+        </div>
+      ` + '\n'
+
+      const offenses = lintSource(html)
+      expect(offenses.length).toBeGreaterThan(0)
+      expect(offenses[0].severity).toBe("warning")
+      expect(offenses[0].message).toContain("indentation")
+    })
+
+    test("should report warning for formatting differences", () => {
+      const html = `<div>   </div>\n`
+
+      const offenses = lintSource(html)
+      expect(offenses.length).toBeGreaterThan(0)
+      expect(offenses[0].severity).toBe("warning")
+    })
+  })
+
+  describe("disabled by default", () => {
+    test("rule should be disabled by default", () => {
+      const rule = new HerbFormatterWellFormattedRule()
+
+      expect(rule.defaultConfig.enabled).toBe(false)
+    })
+
+    test("rule severity should be warning by default", () => {
+      const rule = new HerbFormatterWellFormattedRule()
+
+      expect(rule.defaultConfig.severity).toBe("warning")
+    })
+  })
+
+  describe("formatter config checks", () => {
+    test("rule should not run if formatter is not enabled in config", () => {
+      const configWithoutFormatter = Config.fromObject({
+        formatter: {
+          enabled: false
+        },
+        linter: {
+          rules: {
+            "herb-formatter-well-formatted": { enabled: true }
+          }
+        }
+      })
+
+      const linter = new Linter(Herb, [HerbFormatterWellFormattedRule], configWithoutFormatter)
+      const unformatted = dedent`
+        <div>
+        <p>Hello</p>
+        </div>
+      ` + '\n'
+
+      const result = linter.lint(unformatted)
+      const offenses = result.offenses.filter(o => o.rule === "herb-formatter-well-formatted")
+
+      expect(offenses).toHaveLength(0)
+    })
+
+    test("rule should run if formatter is enabled in config", () => {
+      const unformatted = dedent`
+        <div>
+        <p>Hello</p>
+        </div>
+      ` + '\n'
+
+      const offenses = lintSource(unformatted)
+      expect(offenses.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe("parse error handling", () => {
+    test("should gracefully skip source with parse errors", () => {
+      const html = `<div><p>Unclosed`
+
+      const offenses = lintSource(html)
+      expect(offenses).toHaveLength(0)
+    })
+  })
+})