Parser: Introduce ERBStrictLocalsNode (#1424)

This pull request adds support for parsing and analyzing Rails strict
locals declarations in ERB templates and representing them as structured
`ERBStrictLocalsNode` nodes with individual `RubyStrictLocalNode`
children.

A new `strict_locals` parser option enables this analysis (defaults to
false). When enabled, `ERBContentNodes` matching the `<%# locals: (...)
%>` pattern are transformed into `ERBStrictLocalsNode` with fully
extracted local variable information.

 For example, the following template:

```erb
<%# locals: (user:, theme: "light", **attrs) %>
```

Produces the following with `strict_locals: true`:

```js
@ DocumentNode (location: (1:0)-(1:47))
└── children: (1 item)
    └── @ ERBStrictLocalsNode (location: (1:0)-(1:47))
        ├── tag_opening: "<%#" (location: (1:0)-(1:3))
        ├── content: " locals: (user:, theme: "light", **attrs) " (location: (1:3)-(1:45))
        ├── tag_closing: "%>" (location: (1:45)-(1:47))
        └── locals: (3 items)
            ├── @ RubyStrictLocalNode (location: (1:13)-(1:18))
            │   ├── name: "user" (location: (1:13)-(1:18))
            │   ├── default_value: ∅
            │   ├── required: true
            │   └── double_splat: false
            │
            ├── @ RubyStrictLocalNode (location: (1:20)-(1:34))
            │   ├── name: "theme" (location: (1:20)-(1:26))
            │   ├── default_value:
            │   │   └── @ RubyLiteralNode (location: (1:27)-(1:34))
            │   │       └── content: "\"light\""
            │   │
            │   ├── required: false
            │   └── double_splat: false
            │
            └── @ RubyStrictLocalNode (location: (1:38)-(1:43))
                ├── name: "attrs" (location: (1:38)-(1:43))
                ├── default_value: ∅
                ├── required: false
                └── double_splat: true
```

Author: marcoroth

config.yml

@@ -410,6 +410,54 @@ errors:
         - name: layout
           type: string
 
+    - name: StrictLocalsPositionalArgumentError
+      message:
+        template: "Strict locals only support keyword arguments. Positional argument `%s` is not allowed. Use keyword argument format: `%s:`."
+        arguments:
+          - name
+          - name
+
+      fields:
+        - name: name
+          type: string
+
+    - name: StrictLocalsBlockArgumentError
+      message:
+        template: "Strict locals only support keyword arguments. Block argument `&%s` is not allowed."
+        arguments:
+          - name
+
+      fields:
+        - name: name
+          type: string
+
+    - name: StrictLocalsSplatArgumentError
+      message:
+        template: "Strict locals only support keyword arguments. Splat argument `*%s` is not allowed."
+        arguments:
+          - name
+
+      fields:
+        - name: name
+          type: string
+
+    - name: StrictLocalsMissingParenthesisError
+      message:
+        template: "Strict locals declaration requires parentheses. Expected `locals: (...)` but got `locals: %s`."
+        arguments:
+          - rest
+
+      fields:
+        - name: rest
+          type: string
+
+    - name: StrictLocalsDuplicateDeclarationError
+      message:
+        template: "Duplicate strict locals declaration. Only the first `<%# locals: (...) %>` declaration is used by Rails."
+        arguments: []
+
+      fields: []
+
 warnings:
   fields: []
   types: []
@@ -1169,6 +1217,43 @@ nodes:
           kind:
             - RubyRenderLocalNode
 
+    - name: RubyStrictLocalNode
+      fields:
+        - name: name
+          type: token
+
+        - name: default_value
+          type: node
+          kind: RubyLiteralNode
+
+        - name: required
+          type: boolean
+
+        - name: double_splat
+          type: boolean
+
+    - name: ERBStrictLocalsNode
+      fields:
+        - name: tag_opening
+          type: token
+
+        - name: content
+          type: token
+
+        - name: tag_closing
+          type: token
+
+        - name: analyzed_ruby
+          type: analyzed_ruby
+
+        - name: prism_node
+          type: prism_node
+
+        - name: locals
+          type: array
+          kind:
+            - RubyStrictLocalNode
+
     - name: ERBYieldNode
       fields:
         - name: tag_opening

ext/herb/extension.c

@@ -140,6 +140,10 @@ static VALUE Herb_parse(int argc, VALUE* argv, VALUE self) {
     if (NIL_P(render_nodes)) { render_nodes = rb_hash_lookup(options, ID2SYM(rb_intern("render_nodes"))); }
     if (!NIL_P(render_nodes) && RTEST(render_nodes)) { parser_options.render_nodes = true; }
 
+    VALUE strict_locals = rb_hash_lookup(options, rb_utf8_str_new_cstr("strict_locals"));
+    if (NIL_P(strict_locals)) { strict_locals = rb_hash_lookup(options, ID2SYM(rb_intern("strict_locals"))); }
+    if (!NIL_P(strict_locals) && RTEST(strict_locals)) { parser_options.strict_locals = true; }
+
     VALUE prism_nodes = rb_hash_lookup(options, rb_utf8_str_new_cstr("prism_nodes"));
     if (NIL_P(prism_nodes)) { prism_nodes = rb_hash_lookup(options, ID2SYM(rb_intern("prism_nodes"))); }
     if (!NIL_P(prism_nodes) && RTEST(prism_nodes)) { parser_options.prism_nodes = true; }

ext/herb/extension_helpers.c

@@ -90,6 +90,7 @@ VALUE create_parse_result(AST_DOCUMENT_NODE_T* root, VALUE source, const parser_
   rb_hash_aset(kwargs, ID2SYM(rb_intern("analyze")), options->analyze ? Qtrue : Qfalse);
   rb_hash_aset(kwargs, ID2SYM(rb_intern("action_view_helpers")), options->action_view_helpers ? Qtrue : Qfalse);
   rb_hash_aset(kwargs, ID2SYM(rb_intern("render_nodes")), options->render_nodes ? Qtrue : Qfalse);
+  rb_hash_aset(kwargs, ID2SYM(rb_intern("strict_locals")), options->strict_locals ? Qtrue : Qfalse);
   rb_hash_aset(kwargs, ID2SYM(rb_intern("prism_nodes")), options->prism_nodes ? Qtrue : Qfalse);
   rb_hash_aset(kwargs, ID2SYM(rb_intern("prism_nodes_deep")), options->prism_nodes_deep ? Qtrue : Qfalse);
   rb_hash_aset(kwargs, ID2SYM(rb_intern("prism_program")), options->prism_program ? Qtrue : Qfalse);

java/herb_jni.c

@@ -77,6 +77,14 @@ Java_org_herb_Herb_parse(JNIEnv* env, jclass clazz, jstring source, jobject opti
       parser_options.render_nodes = (renderNodes == JNI_TRUE);
     }
 
+    jmethodID getStrictLocals =
+        (*env)->GetMethodID(env, optionsClass, "isStrictLocals", "()Z");
+
+    if (getStrictLocals != NULL) {
+      jboolean strictLocals = (*env)->CallBooleanMethod(env, options, getStrictLocals);
+      parser_options.strict_locals = (strictLocals == JNI_TRUE);
+    }
+
     jmethodID getPrismNodes =
         (*env)->GetMethodID(env, optionsClass, "isPrismNodes", "()Z");
 

java/org/herb/ParserOptions.java

@@ -6,6 +6,7 @@ public class ParserOptions {
   private boolean strict = true;
   private boolean actionViewHelpers = false;
   private boolean renderNodes = false;
+  private boolean strictLocals = false;
   private boolean prismNodes = false;
   private boolean prismNodesDeep = false;
   private boolean prismProgram = false;
@@ -57,6 +58,15 @@ public boolean isRenderNodes() {
     return renderNodes;
   }
 
+  public ParserOptions strictLocals(boolean value) {
+    this.strictLocals = value;
+    return this;
+  }
+
+  public boolean isStrictLocals() {
+    return strictLocals;
+  }
+
   public ParserOptions prismNodes(boolean value) {
     this.prismNodes = value;
     return this;

javascript/packages/core/src/parser-options.ts

@@ -4,6 +4,7 @@ export interface ParseOptions {
   strict?: boolean
   action_view_helpers?: boolean
   render_nodes?: boolean
+  strict_locals?: boolean
   prism_nodes?: boolean
   prism_nodes_deep?: boolean
   prism_program?: boolean
@@ -17,6 +18,7 @@ export const DEFAULT_PARSER_OPTIONS: SerializedParserOptions = {
   strict: true,
   action_view_helpers: false,
   render_nodes: false,
+  strict_locals: false,
   prism_nodes: false,
   prism_nodes_deep: false,
   prism_program: false,
@@ -41,6 +43,9 @@ export class ParserOptions {
   /** Whether ActionView render call detection was enabled during parsing. */
   readonly render_nodes: boolean
 
+  /** Whether strict locals analysis was enabled during parsing. */
+  readonly strict_locals: boolean
+
   /** Whether Prism node serialization was enabled during parsing. */
   readonly prism_nodes: boolean
 
@@ -60,6 +65,7 @@ export class ParserOptions {
     this.analyze = options.analyze ?? DEFAULT_PARSER_OPTIONS.analyze
     this.action_view_helpers = options.action_view_helpers ?? DEFAULT_PARSER_OPTIONS.action_view_helpers
     this.render_nodes = options.render_nodes ?? DEFAULT_PARSER_OPTIONS.render_nodes
+    this.strict_locals = options.strict_locals ?? DEFAULT_PARSER_OPTIONS.strict_locals
     this.prism_nodes = options.prism_nodes ?? DEFAULT_PARSER_OPTIONS.prism_nodes
     this.prism_nodes_deep = options.prism_nodes_deep ?? DEFAULT_PARSER_OPTIONS.prism_nodes_deep
     this.prism_program = options.prism_program ?? DEFAULT_PARSER_OPTIONS.prism_program

javascript/packages/linter/test/parse-cache.test.ts

@@ -73,6 +73,7 @@ describe("ParseCache", () => {
         prism_program: false,
         render_nodes: false,
         strict: true,
+        strict_locals: false,
         action_view_helpers: false,
       })
     })
@@ -89,6 +90,7 @@ describe("ParseCache", () => {
         prism_program: false,
         render_nodes: false,
         strict: false,
+        strict_locals: false,
         action_view_helpers: false,
       })
     })
@@ -105,6 +107,7 @@ describe("ParseCache", () => {
         prism_program: false,
         render_nodes: false,
         strict: true,
+        strict_locals: false,
         action_view_helpers: false,
       })
     })
@@ -121,6 +124,7 @@ describe("ParseCache", () => {
         prism_program: false,
         render_nodes: false,
         strict: false,
+        strict_locals: false,
         action_view_helpers: false,
       })
     })

javascript/packages/node/binding.gyp

@@ -22,6 +22,7 @@
         "./extension/libherb/analyze/parse_errors.c",
         "./extension/libherb/analyze/prism_annotate.c",
         "./extension/libherb/analyze/render_nodes.c",
+        "./extension/libherb/analyze/strict_locals.c",
         "./extension/libherb/analyze/transform.c",
         "./extension/libherb/analyze/action_view/attribute_extraction_helpers.c",
         "./extension/libherb/analyze/action_view/content_tag.c",

javascript/packages/node/extension/herb.cpp

@@ -130,6 +130,17 @@ napi_value Herb_parse(napi_env env, napi_callback_info info) {
         parser_options.render_nodes = render_nodes_value;
       }
 
+      napi_value strict_locals_prop;
+      bool has_strict_locals_prop;
+      napi_has_named_property(env, args[1], "strict_locals", &has_strict_locals_prop);
+
+      if (has_strict_locals_prop) {
+        napi_get_named_property(env, args[1], "strict_locals", &strict_locals_prop);
+        bool strict_locals_value;
+        napi_get_value_bool(env, strict_locals_prop, &strict_locals_value);
+        parser_options.strict_locals = strict_locals_value;
+      }
+
       napi_value prism_nodes_prop;
       bool has_prism_nodes_prop;
       napi_has_named_property(env, args[1], "prism_nodes", &has_prism_nodes_prop);

javascript/packages/printer/src/identity-printer.ts

@@ -394,6 +394,14 @@ export class IdentityPrinter extends Printer {
     // extracted metadata, nothing to print
   }
 
+  visitERBStrictLocalsNode(node: Nodes.ERBStrictLocalsNode): void {
+    this.printERBNode(node)
+  }
+
+  visitRubyStrictLocalNode(_node: Nodes.RubyStrictLocalNode): void {
+    // extracted metadata, nothing to print
+  }
+
   visitERBYieldNode(node: Nodes.ERBYieldNode): void {
     this.printERBNode(node)
   }