feat(isc): stage(name) syntax, some() constructor, list values with comments

- Codemod: stage(translit) { -> stage translit {
- Parser: accept stage(name) { syntax
- Parser: some() constructor (one-or-more match)
- Codemod: multi-line list values with # comments before items

Verification: 193/289 maps equivalent (67%).

Author: ronaldtse

exe/codemod-imp-to-isc

@@ -283,17 +283,15 @@ module Interscript
             @out << "\n#{indent}notes {"
             convert_notes_list_until_dedent(indent)
             @out << "\n#{indent}}"
-          elsif @scanner.scan(/(?:\A|\n)([ \t]+)([A-Za-z_][\w]*)[ \t]*:[ \t]*\n([ \t]+)-[ \t]*/)
-            # Multi-line list value: `field:\n    - item1\n    - item2`
+          elsif @scanner.scan(/(?:\A|\n)([ \t]+)([A-Za-z_][\w]*)[ \t]*:[ \t]*\n(?:[ \t]*#[^\n]*\n)*([ \t]+)-[ \t]*/)
+            # Multi-line list value: `field:\n    # optional comment\n    - item1\n    - item2`
             indent = @scanner[1]
             field = @scanner[2]
-            first_item_indent = @scanner[3]
+            item_indent = @scanner[3]
             @out << "\n#{indent}#{field} "
-            # Read the first item value
             text = @scanner.scan(/[^\n]+/).to_s
             @out << text
-            # Read subsequent `- item` lines at the same or deeper indent
-            while @scanner.check(/\n[ \t]{#{first_item_indent.length},}-[ \t]/)
+            while @scanner.check(/\n[ \t]{#{item_indent.length},}-[ \t]/)
               @scanner.scan(/\n[ \t]+-[ \t]+/)
               text = @scanner.scan(/[^\n]+/).to_s
               @out << " " + text
@@ -551,7 +549,10 @@ module Interscript
 
       def convert_stage_header
         # Legacy `stage {` becomes `stage main {` if no name is given.
-        if @scanner.scan(/\s*\{/)
+        # `stage(translit) {` becomes `stage translit {`.
+        if @scanner.scan(/\s*\(([A-Za-z_]\w*)\)\s*\{/)
+          @out << " #{@scanner[1]} {"
+        elsif @scanner.scan(/\s*\{/)
           @out << " main {"
         elsif @scanner.scan(/\s+([A-Za-z_]\w*)\s*\{/)
           @out << " #{@scanner[1]} {"

lib/interscript/isc/grammar/concerns/items.rb

@@ -17,11 +17,19 @@ module Items
               any_constructor |
               capture_constructor |
               maybe_constructor |
+              some_constructor |
               function_call |
               capture_reference |
               alias_reference
           end
 
+          # some(...) — one or more matches (greedy).
+          rule(:some_constructor) do
+            str("some") >> str("(") >> whitespace? >>
+              item.as(:some_inner) >>
+              whitespace? >> str(")")
+          end
+
           # Function call: upcase, downcase, title_case, reverse, etc.
           # These appear as the `to` value in sub rules: `sub "X" upcase`.
           rule(:function_call) do
@@ -107,7 +115,7 @@ module Items
               str("none") | str("boundary") | str("line_start") |
               str("line_end") | str("word_boundary") |
               str("downcase") | str("upcase") | str("title_case") |
-              str("capture") | str("maybe") | str("ref")
+              str("capture") | str("maybe") | str("some") | str("ref")
           end
 
           # Concatenation: one or more atoms. The continuation pattern

lib/interscript/isc/grammar/concerns/stages.rb

@@ -11,8 +11,9 @@ module Stages
           include Parslet
 
           rule(:stage_block) do
-            str("stage") >> whitespace >>
-              identifier.as(:stage_name) >> whitespace? >>
+            str("stage") >>
+              (str("(") >> identifier.as(:stage_name) >> str(")") |
+               whitespace >> identifier.as(:stage_name)) >> whitespace? >>
               braced(stage_item.repeat(0)).as(:stage)
           end
 

lib/interscript/isc/items.rb

@@ -111,6 +111,19 @@ def inspect
         end
       end
 
+      # Wraps a one-or-more sub-expression (greedy).
+      class Some
+        attr_reader :inner
+
+        def initialize(inner)
+          @inner = inner
+        end
+
+        def inspect
+          "Some(#{@inner.inspect})"
+        end
+      end
+
       class Range
         attr_reader :lo, :hi
 

lib/interscript/isc/transform.rb

@@ -57,6 +57,7 @@ class Transform < Parslet::Transform
       rule(ref: subtree(:h)) { Items::Capture.new(h[:digit].to_s.to_i) }
       rule(capture_inner: subtree(:inner)) { Items::CaptureGroup.new(materialize_item(inner)) }
       rule(maybe_inner: subtree(:inner)) { Items::Maybe.new(materialize_item(inner)) }
+      rule(some_inner: subtree(:inner)) { Items::Some.new(materialize_item(inner)) }
 
       rule(dquote: simple(:_)) { '"' }
       rule(backslash: simple(:_)) { "\\" }