Rubocop markdown snippets

[zzak]

Introduce rubocop-md for our markdown files.

This ensures any code snippets in the guides also follow the Rails coding conventions, without having to manually review every change that comes in.

I've intentionally disabled Style/StringLiterals in the guides because that is a much larger change, and figured I would follow up with a single PR to do that after this gets merged.

You can see some of the changes broken down further in zzak#2 and zzak#3.

[matthewd]

I like the idea, though there are some specifics that don't seem great (attr_reader, %Q) -- being documentation examples, it can be better for us to use more generic constructs than optimise for the actual [dummy] content that's present as shown.

I also spotted a rubocop:disable comment somewhere.. does that show up in the generated docs?

[zzak]

Reverted some of the extraneous rules in 3ffc441.

I also spotted a rubocop:disable comment somewhere.. does that show up in the generated docs?

It did show up, so I reverted that as well. In spite of the docs providing an alternative method (<span style="display:none;"># rubocop:disable all</span>) that did not work when specifying this specific rule.. so probably better to just disable it.

We probably shouldn't worry about redundant begin/end in our docs 😂 and fine if we have to catch that one in code review IMO.

[zzak]

Regardless of the style consistency wins, the fact this does a Ripper.sexp to check the syntax of the code caught this which is a huge benefit IMO.

[sambostock]

I think this is a syntax error because of the space between routing and (.

If I'm correct, I'm surprised it isn't caught by RuboCop, especially given #47186 (comment)... 🤔

Was this autocorrected?

[zzak]

@sambostock Thanks for taking a look!

This is not a syntax error, although I would prefer routing(...), it doesn't seem like there is a rule for that at least in our config.

>> RUBY_VERSION
=> "3.3.0"
?> def foo bar
?>   puts bar
>> end
=> :foo
>>
>> foo "omg"
omg
=> nil
>> foo("omg")
omg
=> nil
>> foo ("omg")
omg
=> nil

[koic]

I think the syntax error that @sambostock tells is as follows:

With space

invalid syntax:

% ruby -vce 'routing (/^save@/i     => :forwards)'
ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-darwin19]
-e:1: void value expression
...ing (/^save@/i     => :forwards)
-e: compile error (SyntaxError)

No space

valid syntax:

% ruby -vce 'routing(/^save@/i     => :forwards)'
ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-darwin19]
Syntax OK

The same is true for Ruby 3.3.0-dev.

[zzak]

Thanks! I will fix it.

[zzak]

@sambostock @koic Fixed in 321c8df, but I wonder why Ripper.sexp didn't catch this? Is there another rule we can add that would have caught it?

[koic]

I'm not sure, but maybe there is something wrong with the Parser gem. Unfortunately, the cause has not been determined.

[palkan]

Both Ripper and Parser recognize this syntax:

irb(main):003:0> Ripper.sexp('routing (/^save@/i     => :forwards)')
=> 
[:program,
   [:@ident, "routing", [1, 0]],
   [:args_add_block,
    [[:paren,
      [:case,
       [:regexp_literal, [[:@tstring_content, "^save@", [1, 10]]], [:@regexp_end, "/i", [1, 16]]],
       [:in, [:symbol_literal, [:symbol, [:@ident, "forwards", [1, 27]]]], nil, nil]]]],
    false]]]]

irb(main):006:0> Parser::CurrentRuby.parse('routing (/^save@/i     => :forwards)')
=> 
s(:send, nil, :routing,                                                      
  s(:begin,                                                                  
    s(:match_pattern,                                                
      s(:regexp,                                                     
        s(:str, "^save@"),                                           
        s(:regopt, :i)),                                             
      s(:sym, :forwards)))) 

But:

$ ruby -w -e 'routing (/^save@/i     => :forwards)'

-e:1: void value expression
...ing (/^save@/i     => :forwards)
-e: compile error (SyntaxError)

🤷‍♂️