From fbe24be0588a565b91adab3d3bbcc9fe5e599d48 Mon Sep 17 00:00:00 2001
From: Marco Roth <marco.roth@intergga.ch>
Date: Sat, 21 Mar 2026 02:50:18 +0100
Subject: [PATCH] Linter: Implement `actionview-strict-locals-first-line` rule

---
 .../packages/linter/docs/rules/README.md      |  33 +++++
 .../actionview-strict-locals-first-line.md    |  65 +++++++++
 javascript/packages/linter/src/rules.ts       |   2 +
 .../actionview-strict-locals-first-line.ts    | 119 ++++++++++++++++
 .../src/rules/erb-strict-locals-required.ts   |  11 +-
 javascript/packages/linter/src/rules/index.ts |   1 +
 ...w-strict-locals-first-line.autofix.test.ts | 127 ++++++++++++++++++
 ...ctionview-strict-locals-first-line.test.ts | 102 ++++++++++++++
 8 files changed, 452 insertions(+), 8 deletions(-)
 create mode 100644 javascript/packages/linter/docs/rules/actionview-strict-locals-first-line.md
 create mode 100644 javascript/packages/linter/src/rules/actionview-strict-locals-first-line.ts
 create mode 100644 javascript/packages/linter/test/autofix/actionview-strict-locals-first-line.autofix.test.ts
 create mode 100644 javascript/packages/linter/test/rules/actionview-strict-locals-first-line.test.ts

diff --git a/javascript/packages/linter/docs/rules/README.md b/javascript/packages/linter/docs/rules/README.md
index 45b93e98f..04b426b5d 100644
--- a/javascript/packages/linter/docs/rules/README.md
+++ b/javascript/packages/linter/docs/rules/README.md
@@ -4,9 +4,16 @@ This page contains documentation for all Herb Linter rules.
 
 ## Available Rules
 
+#### Action View
+
 - [`actionview-no-silent-helper`](./actionview-no-silent-helper.md) - Disallow silent ERB tags for Action View helpers
 - [`actionview-no-silent-render`](./actionview-no-silent-render.md) - Disallow calling `render` without outputting the result
 - [`actionview-no-void-element-content`](./actionview-no-void-element-content.md) - Disallow content arguments for void Action View elements
+- [`actionview-strict-locals-first-line`](./actionview-strict-locals-first-line.md) - Require strict locals on the first line of partials with a blank line after.
+
+
+#### ERB
+
 - [`erb-comment-syntax`](./erb-comment-syntax.md) - Disallow Ruby comments immediately after ERB tags
 - [`erb-no-case-node-children`](./erb-no-case-node-children.md) - Don't use `children` for `case/when` and `case/in` nodes
 - [`erb-no-conditional-html-element`](./erb-no-conditional-html-element.md) - Disallow conditional HTML elements
@@ -36,12 +43,21 @@ This page contains documentation for all Herb Linter rules.
 - [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around ERB tags
 - [`erb-right-trim`](./erb-right-trim.md) - Enforce consistent right-trimming syntax.
 - [`erb-strict-locals-comment-syntax`](./erb-strict-locals-comment-syntax.md) - Enforce strict locals comment syntax.
+- [`erb-strict-locals-required`](./erb-strict-locals-required.md) - Require strict locals in Rails partials.
+
+
+#### Herb
+
 - [`herb-disable-comment-malformed`](./herb-disable-comment-malformed.md) - Detect malformed `herb:disable` comments.
 - [`herb-disable-comment-missing-rules`](./herb-disable-comment-missing-rules.md) - Require rule names in `herb:disable` comments.
 - [`herb-disable-comment-no-duplicate-rules`](./herb-disable-comment-no-duplicate-rules.md) - Disallow duplicate rule names in `herb:disable` comments.
 - [`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.
+
+
+#### HTML
+
 - [`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.
@@ -77,11 +93,28 @@ This page contains documentation for all Herb Linter rules.
 - [`html-no-underscores-in-attribute-names`](./html-no-underscores-in-attribute-names.md) - Disallow underscores in HTML attribute names
 - [`html-require-script-nonce`](./html-require-script-nonce.md) - Require `nonce` attribute on script tags and helpers
 - [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
+
+
+#### Parser
+
 - [`parser-no-errors`](./parser-no-errors.md) - Disallow parser errors in HTML+ERB documents
+
+
+#### Source
+
 - [`source-indentation`](./source-indentation.md) - Indent with spaces instead of tabs.
+
+
+#### SVG
+
 - [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements
+
+
+#### Turbo
+
 - [`turbo-permanent-require-id`](./turbo-permanent-require-id.md) - Require `id` attribute on elements with `data-turbo-permanent`
 
+
 ## Contributing
 
 To add a new linter rule you can scaffold a new rule by running:
diff --git a/javascript/packages/linter/docs/rules/actionview-strict-locals-first-line.md b/javascript/packages/linter/docs/rules/actionview-strict-locals-first-line.md
new file mode 100644
index 000000000..4d3324423
--- /dev/null
+++ b/javascript/packages/linter/docs/rules/actionview-strict-locals-first-line.md
@@ -0,0 +1,65 @@
+# Linter Rule: Require strict locals on the first line with a blank line after
+
+**Rule:** `actionview-strict-locals-first-line`
+
+## Description
+
+Requires that the strict locals declaration:
+
+1. Appears on the **first line** of a Rails partial template
+2. Is followed by a **blank line** before any content
+
+A partial is any template whose filename begins with an underscore (e.g. `_card.html.erb`).
+
+## Rationale
+
+While Rails accepts strict locals declarations anywhere in a partial, placing them at the very top, followed by a blank line, makes the partial's expected locals immediately visible and visually separated from the template body. This mirrors conventions like `# frozen_string_literal: true` in Ruby files.
+
+Enforcing this placement ensures that locals are the first thing you see when opening the file, that the partial's public API is clearly separated from its content, and consistent across all partials in the codebase.
+
+## Examples
+
+### ✅ Good
+
+```erb [app/views/users/_card.html.erb]
+<%# locals: (user:) %>
+
+<div class="user-card">
+  <%= user.name %>
+</div>
+```
+
+### 🚫 Bad
+
+Strict locals not on the first line:
+
+```erb [app/views/users/_card.html.erb]
+<div class="user-card">
+  <%# locals: (user:) %>
+  <%= user.name %>
+</div>
+```
+
+Strict locals after a leading blank line:
+
+```erb [app/views/users/_card.html.erb]
+
+<%# locals: (user:) %>
+
+<div class="user-card">
+  <%= user.name %>
+</div>
+```
+
+Strict locals on line 1 but no blank line before content:
+
+```erb [app/views/users/_card.html.erb]
+<%# locals: (user:) %>
+<div class="user-card">
+  <%= user.name %>
+</div>
+```
+
+## References
+
+- [Action View - Strict Locals](https://guides.rubyonrails.org/action_view_overview.html#strict-locals)
diff --git a/javascript/packages/linter/src/rules.ts b/javascript/packages/linter/src/rules.ts
index 050aed818..ef3014ff2 100644
--- a/javascript/packages/linter/src/rules.ts
+++ b/javascript/packages/linter/src/rules.ts
@@ -3,6 +3,7 @@ import type { RuleClass } from "./types.js"
 import { ActionViewNoSilentHelperRule } from "./rules/actionview-no-silent-helper.js"
 import { ActionViewNoSilentRenderRule } from "./rules/actionview-no-silent-render.js"
 import { ActionViewNoVoidElementContentRule } from "./rules/actionview-no-void-element-content.js"
+import { ActionViewStrictLocalsFirstLineRule } from "./rules/actionview-strict-locals-first-line.js"
 
 import { ERBCommentSyntax } from "./rules/erb-comment-syntax.js";
 import { ERBNoCaseNodeChildrenRule } from "./rules/erb-no-case-node-children.js"
@@ -93,6 +94,7 @@ export const rules: RuleClass[] = [
   ActionViewNoSilentHelperRule,
   ActionViewNoSilentRenderRule,
   ActionViewNoVoidElementContentRule,
+  ActionViewStrictLocalsFirstLineRule,
 
   ERBCommentSyntax,
   ERBNoCaseNodeChildrenRule,
diff --git a/javascript/packages/linter/src/rules/actionview-strict-locals-first-line.ts b/javascript/packages/linter/src/rules/actionview-strict-locals-first-line.ts
new file mode 100644
index 000000000..49dc466ce
--- /dev/null
+++ b/javascript/packages/linter/src/rules/actionview-strict-locals-first-line.ts
@@ -0,0 +1,119 @@
+import { BaseRuleVisitor } from "./rule-utils.js"
+import { ParserRule } from "../types.js"
+import { createLiteral } from "@herb-tools/core"
+
+import { isERBStrictLocalsNode, isHTMLTextNode } from "@herb-tools/core"
+import { isPartialFile } from "./file-utils.js"
+
+import type { ParseResult, DocumentNode, ERBStrictLocalsNode } from "@herb-tools/core"
+import type { UnboundLintOffense, LintOffense, LintContext, FullRuleConfig } from "../types.js"
+
+class ActionViewStrictLocalsFirstLineVisitor extends BaseRuleVisitor {
+  visitDocumentNode(node: DocumentNode) {
+    const { children } = node
+
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i]
+      if (!isERBStrictLocalsNode(child)) continue
+
+      const next = children[i + 1]
+      if (!next) break
+
+      if (isHTMLTextNode(next)) {
+        if (!next.content.startsWith("\n\n") && children[i + 2]) {
+          this.addOffense(
+            "Add a blank line after the strict locals declaration.",
+            child.location
+          )
+        }
+      } else {
+        this.addOffense(
+          "Add a blank line after the strict locals declaration.",
+          child.location
+        )
+      }
+
+      break
+    }
+
+    this.visitChildNodes(node)
+  }
+
+  visitERBStrictLocalsNode(node: ERBStrictLocalsNode): void {
+    if (isPartialFile(this.context.fileName) !== true) return
+
+    if (node.location.start.line !== 1) {
+      this.addOffense(
+        "Strict locals declaration must be on the first line of the partial.",
+        node.location
+      )
+    }
+  }
+}
+
+export class ActionViewStrictLocalsFirstLineRule extends ParserRule {
+  static autocorrectable = true
+  static ruleName = "actionview-strict-locals-first-line"
+  static introducedIn = this.version("unreleased")
+
+  get parserOptions() {
+    return { strict_locals: true }
+  }
+
+  get defaultConfig(): FullRuleConfig {
+    return {
+      enabled: false,
+      severity: "error",
+    }
+  }
+
+  check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense[] {
+    if (isPartialFile(context?.fileName) !== true) return []
+
+    const visitor = new ActionViewStrictLocalsFirstLineVisitor(this.ruleName, context)
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+
+  autofix(offense: LintOffense, result: ParseResult): ParseResult | null {
+    const children = result.value.children
+
+    const index = children.findIndex(child =>
+      child.location.start.line === offense.location.start.line &&
+      child.location.start.column === offense.location.start.column
+    )
+
+    if (index === -1) return null
+
+    if (offense.location.start.line === 1) {
+      const next = children[index + 1]
+
+      if (isHTMLTextNode(next)) {
+        children.splice(index + 1, 1, createLiteral("\n\n"))
+      } else {
+        children.splice(index + 1, 0, createLiteral("\n\n"))
+      }
+    } else {
+      const [node] = children.splice(index, 1)
+
+      if (index > 0) {
+        const previous = children[index - 1]
+
+        if (isHTMLTextNode(previous) && /^\s*$/.test(previous.content)) {
+          children.splice(index - 1, 1)
+        }
+      }
+
+      const firstChild = children[0]
+
+      if (!firstChild || !isHTMLTextNode(firstChild) || !firstChild.content.startsWith("\n\n")) {
+        children.unshift(createLiteral("\n\n"))
+      }
+
+      children.unshift(node)
+    }
+
+    return result
+  }
+}
diff --git a/javascript/packages/linter/src/rules/erb-strict-locals-required.ts b/javascript/packages/linter/src/rules/erb-strict-locals-required.ts
index 7826f19a6..0e126b21b 100644
--- a/javascript/packages/linter/src/rules/erb-strict-locals-required.ts
+++ b/javascript/packages/linter/src/rules/erb-strict-locals-required.ts
@@ -1,5 +1,5 @@
 import { ParserRule } from "../types.js"
-import { Location, ERBStrictLocalsNode, LiteralNode } from "@herb-tools/core"
+import { Location, ERBStrictLocalsNode, createLiteral } from "@herb-tools/core"
 import { BaseRuleVisitor } from "./rule-utils.js"
 
 import { isPartialFile } from "./file-utils.js"
@@ -39,7 +39,7 @@ export class ERBStrictLocalsRequiredRule extends ParserRule {
 
     if (visitor.foundStrictLocals) return []
 
-    const document = result.value as DocumentNode
+    const document = result.value
     const firstChild = document.children[0]
     const end = firstChild ? firstChild.location.end : Location.zero.end
 
@@ -52,12 +52,7 @@ export class ERBStrictLocalsRequiredRule extends ParserRule {
   }
 
   autofix(_offense: LintOffense, result: ParseResult): ParseResult | null {
-    (result.value.children as unknown[]).unshift(LiteralNode.from({
-      type: "AST_LITERAL_NODE",
-      location: Location.zero,
-      errors: [],
-      content: "<%# locals: () %>\n\n",
-    }))
+    result.value.children.unshift(createLiteral("<%# locals: () %>\n\n"))
 
     return result
   }
diff --git a/javascript/packages/linter/src/rules/index.ts b/javascript/packages/linter/src/rules/index.ts
index 15123bbfd..b2c92ca0f 100644
--- a/javascript/packages/linter/src/rules/index.ts
+++ b/javascript/packages/linter/src/rules/index.ts
@@ -6,6 +6,7 @@ export * from "./herb-disable-comment-base.js"
 export * from "./actionview-no-silent-helper.js"
 export * from "./actionview-no-silent-render.js"
 export * from "./actionview-no-void-element-content.js"
+export * from "./actionview-strict-locals-first-line.js"
 
 export * from "./erb-comment-syntax.js"
 export * from "./erb-no-case-node-children.js"
diff --git a/javascript/packages/linter/test/autofix/actionview-strict-locals-first-line.autofix.test.ts b/javascript/packages/linter/test/autofix/actionview-strict-locals-first-line.autofix.test.ts
new file mode 100644
index 000000000..a2b40c713
--- /dev/null
+++ b/javascript/packages/linter/test/autofix/actionview-strict-locals-first-line.autofix.test.ts
@@ -0,0 +1,127 @@
+import dedent from "dedent"
+import { describe, test, expect, beforeAll } from "vitest"
+import { Herb } from "@herb-tools/node-wasm"
+import { Linter } from "../../src/linter.js"
+import { ActionViewStrictLocalsFirstLineRule } from "../../src/rules/actionview-strict-locals-first-line.js"
+
+describe("actionview-strict-locals-first-line autofix", () => {
+  beforeAll(async () => {
+    await Herb.load()
+  })
+
+  test("adds blank line after strict locals on line 1", () => {
+    const input = dedent`
+      <%# locals: (user:) %>
+      <div><%= user.name %></div>
+    `
+    const expected = dedent`
+      <%# locals: (user:) %>
+
+      <div><%= user.name %></div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toBe(expected)
+    expect(result.fixed).toHaveLength(1)
+    expect(result.unfixed).toHaveLength(0)
+  })
+
+  test("moves strict locals after a leading blank line to first line", () => {
+    const input = "\n<%# locals: (user:) %>\n\n<div><%= user.name %></div>\n"
+    const expected = "<%# locals: (user:) %>\n\n<div><%= user.name %></div>\n"
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toBe(expected)
+    expect(result.fixed).toHaveLength(1)
+    expect(result.unfixed).toHaveLength(0)
+  })
+
+  test("moves strict locals after other top-level content to first line", () => {
+    const input = dedent`
+      <%# This is a comment %>
+      <%# locals: (user:) %>
+
+      <div><%= user.name %></div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toContain("<%# locals: (user:) %>")
+    expect(result.source).toMatch(/^<%# locals: \(user:\) %>/)
+    expect(result.fixed).toHaveLength(1)
+    expect(result.unfixed).toHaveLength(0)
+  })
+
+  test("does not autofix strict locals nested inside HTML elements", () => {
+    const input = dedent`
+      <div class="card">
+        <%# locals: (user:) %>
+        <%= user.name %>
+      </div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toBe(input)
+    expect(result.fixed).toHaveLength(0)
+    expect(result.unfixed).toHaveLength(1)
+  })
+
+  test("adds blank line after strict locals when followed by another comment", () => {
+    const input = dedent`
+      <%# locals: (user:) %>
+      <%# Some helper comment %>
+
+      <div><%= user.name %></div>
+    `
+    const expected = dedent`
+      <%# locals: (user:) %>
+
+      <%# Some helper comment %>
+
+      <div><%= user.name %></div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toBe(expected)
+    expect(result.fixed).toHaveLength(1)
+    expect(result.unfixed).toHaveLength(0)
+  })
+
+  test("does not modify files that already comply", () => {
+    const input = dedent`
+      <%# locals: (user:) %>
+
+      <div><%= user.name %></div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "_partial.html.erb" })
+
+    expect(result.source).toBe(input)
+    expect(result.fixed).toHaveLength(0)
+    expect(result.unfixed).toHaveLength(0)
+  })
+
+  test("does not modify non-partial files", () => {
+    const input = dedent`
+      <%# locals: (user:) %>
+      <div><%= user.name %></div>
+    `
+
+    const linter = new Linter(Herb, [ActionViewStrictLocalsFirstLineRule])
+    const result = linter.autofix(input, { fileName: "show.html.erb" })
+
+    expect(result.source).toBe(input)
+    expect(result.fixed).toHaveLength(0)
+    expect(result.unfixed).toHaveLength(0)
+  })
+})
diff --git a/javascript/packages/linter/test/rules/actionview-strict-locals-first-line.test.ts b/javascript/packages/linter/test/rules/actionview-strict-locals-first-line.test.ts
new file mode 100644
index 000000000..6a231d7fa
--- /dev/null
+++ b/javascript/packages/linter/test/rules/actionview-strict-locals-first-line.test.ts
@@ -0,0 +1,102 @@
+import dedent from "dedent"
+import { describe, test } from "vitest"
+import { ActionViewStrictLocalsFirstLineRule } from "../../src/rules/actionview-strict-locals-first-line.js"
+import { createLinterTest } from "../helpers/linter-test-helper.js"
+
+const { expectNoOffenses, expectError, assertOffenses } = createLinterTest(ActionViewStrictLocalsFirstLineRule, { enabled: true })
+
+describe("ActionViewStrictLocalsFirstLineRule", () => {
+  test("allows strict locals on line 1 followed by a blank line", () => {
+    expectNoOffenses(dedent`
+      <%# locals: (user:) %>
+
+      <div><%= user.name %></div>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("allows strict locals on line 1 with no content after", () => {
+    expectNoOffenses(`<%# locals: (user:) %>`, { fileName: "_partial.html.erb" })
+    expectNoOffenses(`<%# locals: (user:) %>\n`, { fileName: "_partial.html.erb" })
+  })
+
+  test("flags strict locals not on the first line", () => {
+    expectError("Strict locals declaration must be on the first line of the partial.")
+
+    assertOffenses(dedent`
+      <div class="card">
+        <%# locals: (user:) %>
+        <%= user.name %>
+      </div>
+    `, { fileName: "_card.html.erb" })
+  })
+
+  test("flags strict locals after a leading blank line", () => {
+    expectError("Strict locals declaration must be on the first line of the partial.")
+
+    assertOffenses(`\n<%# locals: (user:) %>`, { fileName: "_partial.html.erb" })
+  })
+
+  test("flags strict locals after other content", () => {
+    expectError("Strict locals declaration must be on the first line of the partial.")
+
+    assertOffenses(dedent`
+      <%# This is a comment %>
+      <%# locals: (user:) %>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("flags strict locals on line 1 without a blank line before content", () => {
+    expectError("Add a blank line after the strict locals declaration.")
+
+    assertOffenses(dedent`
+      <%# locals: (user:) %>
+      <div><%= user.name %></div>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("flags strict locals on line 1 without a blank line before an ERB tag", () => {
+    expectError("Add a blank line after the strict locals declaration.")
+
+    assertOffenses(dedent`
+      <%# locals: (message:) %>
+      <%= message %>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("does not flag non-partial files", () => {
+    expectNoOffenses(dedent`
+      <div class="card">
+        <%# locals: (user:) %>
+      </div>
+    `, { fileName: "show.html.erb" })
+  })
+
+  test("does not flag when no strict locals declaration", () => {
+    expectNoOffenses(dedent`
+      <div><%= user.name %></div>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("does not flag when filename is not provided", () => {
+    expectNoOffenses(`<%# locals: (user:) %>`, { fileName: undefined })
+  })
+
+  test("allows strict locals with whitespace trimming marker on line 1 with blank line", () => {
+    expectNoOffenses(dedent`
+      <%# locals: (user:) -%>
+
+      <div><%= user.name %></div>
+    `, { fileName: "_partial.html.erb" })
+  })
+
+  test("flags strict locals inside an HTML element", () => {
+    expectError("Strict locals declaration must be on the first line of the partial.")
+
+    assertOffenses(dedent`
+      <div>
+        <%# locals: (user:) %>
+        <%= user.name %>
+      </div>
+    `, { fileName: "_partial.html.erb" })
+  })
+})