Linter Rule: Enforce strict locals comment syntax

Rule: erb-strict-locals-comment-syntax

Description

Ensures that strict locals comments use the exact locals: ( ... ) syntax so they are properly recognized by Rails and tooling. Also validates that only keyword arguments are used (no positional, block, or splat arguments).

Rationale

Strict locals comments declare which locals are expected in a template. Misspellings or malformed syntax silently disable the declaration, leading to confusing runtime errors when required locals are missing.

Additionally, Rails only supports keyword arguments in strict locals declarations. Positional, block, and splat arguments will raise an ActionView::Error at render-time.

This rule catches invalid comment forms and argument types early during development.

Examples

✅ Good

Required keyword argument:

<%# locals: (user:) %>

Keyword argument with default value:

<%# locals: (user:, admin: false) %>

Complex default values:

<%# locals: (items: [], config: {}) %>

No locals (empty):

<%# locals: () %>

Double-splat for optional keyword arguments:

<%# locals: (message: "Hello", **attributes) %>

🚫 Bad

Wrong comment syntax

Missing colon after locals:

<%# locals() %>
Use `locals:` with a colon, not `locals()`. Correct format: `<%# locals: (...) %>`. (erb-strict-locals-comment-syntax)

Singular local instead of locals:

<%# local: (user:) %>
Use `locals:` (plural), not `local:`. (erb-strict-locals-comment-syntax)

Missing colon before parentheses:

<%# locals (user:) %>
Use `locals:` with a colon before the parentheses, not `locals (`. (erb-strict-locals-comment-syntax)

Missing parentheses around parameters:

<%# locals: user %>
Wrap parameters in parentheses: `locals: (name:)` or `locals: (name: default)`. (erb-strict-locals-comment-syntax)

Empty locals: without parentheses:

<%# locals: %>
Add parameters after `locals:`. Use `locals: (name:)` or `locals: ()` for no locals. (erb-strict-locals-comment-syntax)

Unbalanced parentheses:

<%# locals: (user: %>
Unbalanced parentheses in `locals:` comment. Ensure all opening parentheses have matching closing parentheses. (erb-strict-locals-comment-syntax)

Wrong tag type (must use ERB comment tag)

Ruby comment in execution tag:

<% # locals: (user:) %>
Use `<%#` instead of `<% #` for strict locals comments. Only ERB comment syntax is recognized by Rails. (erb-strict-locals-comment-syntax)
Use `<%#` instead of `<% #`. Ruby comments immediately after ERB tags can cause parsing issues. (erb-comment-syntax)

Unsupported argument types

Positional argument (use user: instead):

<%# locals: (user) %>
Positional argument `user` is not allowed. Use keyword argument format: `user:`. (erb-strict-locals-comment-syntax)

Block argument:

<%# locals: (&block) %>
Block argument `&block` is not allowed. Strict locals only support keyword arguments. (erb-strict-locals-comment-syntax)

Single splat argument:

<%# locals: (*args) %>
Splat argument `*args` is not allowed. Strict locals only support keyword arguments. (erb-strict-locals-comment-syntax)

Note: Double-splat (**attributes) IS supported for optional keyword arguments.

Invalid Ruby syntax

Trailing comma:

<%# locals: (user:,) %>
Unexpected comma in `locals:` parameters. (erb-strict-locals-comment-syntax)

Leading comma:

<%# locals: (, user:) %>
Unexpected comma in `locals:` parameters. (erb-strict-locals-comment-syntax)

Double comma:

<%# locals: (user:,, admin:) %>
Unexpected comma in `locals:` parameters. (erb-strict-locals-comment-syntax)

Duplicate declarations

Only one locals: comment is allowed per partial:

<%# locals: (user:) %>
<p>Content</p>
<%# locals: (admin:) %>
Duplicate `locals:` declaration. Only one `locals:` comment is allowed per partial (first declaration at line 1). (erb-strict-locals-comment-syntax)

References

• Action View - Strict Locals