Add new Lint/UriEscapeUnescape cop

[koic]

Feature

This cop identifies places where URI.escape can be replaced by CGI.escape, URI.encode_www_form or URI.encode_www_form_component depending on your specific use case.
Also this cop identifies places where URI.unescape can be replaced by CGI.unescape, URI.decode_www_form or URI.decode_www_form_component depending on your specific use case.

% cat /tmp/example.rb
# frozen_string_literal: true

require 'uri'

URI.escape('http://example.com')
URI.encode('http://example.com')
URI.unescape('http://example.com')
URI.decode('http://example.com')

% bundle exec rubocop /tmp/example.rb
Inspecting 1 file
W

Offenses:

/tmp/example.rb:5:1: W: URI.escape method is obsolete and should not be used. Instead, use CGI.escape, URI.encode_www_form or URI.encode_www_form_component depending on your specific use case.
URI.escape('http://example.com')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
/tmp/example.rb:6:1: W: URI.encode method is obsolete and should not be used. Instead, use CGI.escape, URI.encode_www_form or URI.encode_www_form_component depending on your specific use case.
URI.encode('http://example.com')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
/tmp/example.rb:7:1: W: URI.unescape method is obsolete and should not be used. Instead, use CGI.unescape, URI.decode_www_form or URI.decode_www_form_component depending on your specific use case.
URI.unescape('http://example.com')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
/tmp/example.rb:8:1: W: URI.decode method is obsolete and should not be used. Instead, use CGI.unescape, URI.decode_www_form or URI.decode_www_form_component depending on your specific use case.
URI.decode('http://example.com')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1 file inspected, 4 offenses detected

Target Problem

Emulate the following Ruby's warnings.

% ruby -w -ruri -e "URI.escape('http://example.com')"
-e:1:in `<main>': warning: URI.escape is obsolete

% ruby -w -ruri -e "URI.encode('http://example.com')"
-e:1:in `<main>': warning: URI.escape is obsolete

% ruby -w -ruri -e "URI.unescape('http://example.com')"
-e:1:in `<main>': warning: URI.unescape is obsolete

% ruby -w -ruri -e "URI.decode('http://example.com')"
-e:1:in `<main>': warning: URI.unescape is obsolete

Other Information

This cop does not have autocorrect because these methods to replace depends on use case.

The following is an excerpt from the API Doc.

URI.escape

https://github.com/ruby/ruby/blob/cd6df5fb3c1e9b965071d6a92ed1c7d4a938560f/lib/uri/common.rb#L80-L87

    # == Description
    #
    # Escapes the string, replacing all unsafe characters with codes.
    #
    # This method is obsolete and should not be used. Instead, use
    # CGI.escape, URI.encode_www_form or URI.encode_www_form_component
    # depending on your specific use case
    #

URI.unescape

https://github.com/ruby/ruby/blob/cd6df5fb3c1e9b965071d6a92ed1c7d4a938560f/lib/uri/common.rb#L117-L122

    # == Description
    #
    # This method is obsolete and should not be used. Instead, use
    # CGI.unescape, URI.decode_www_form or URI.decode_www_form_component
    # depending on your specific use case.
    #

---

Before submitting the PR make sure the following are checked:

• Wrote good commit messages.
• Commit message starts with [Fix #issue-number] (if the related issue exists).
• Used the same coding conventions as the rest of the project.
• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Added an entry to the Changelog if the new code introduces user-observable changes. See changelog entry format.
• All tests(rake spec) are passing.
• The new code doesn't generate RuboCop offenses that are checked by rake internal_investigation.
• The PR relates to only one subject with a clear title
  and description in grammatically correct, complete sentences.
• Updated cop documentation with rake generate_cops_documentation (required only when you've added a new cop or changed the configuration/documentation of an existing cop).

[pocke]

👍

[jonworek]

I'm going through some of my code, but I'm hung up on the correct remediation for a violation of this rule.

depending on your specific use case

It's not obvious to me which use cases warrant which of the three options that were given. Are you able to elaborate?

Thanks.

[yuki24]

I also don't see why CGI.unescape should take the precedence over URI.unescape, aside from so over-used "consistency". Blindly suggesting and replacing valid use cases without explaining why is extremely unhelpful and non educational.

[Drenmi]

It's not obvious to me which use cases warrant which of the three options that were given. Are you able to elaborate?

CGI.escape URL encodes an arbitrary string. If that sounds like what you are doing, then that's the one you want. This is by far the more common use case. 🙂

URI.encode_www_form dumps an Enumerable to application/x-www-form-urlencoded data. (Basically a long query string.)

I also don't see why CGI.unescape should take the precedence over URI.unescape [...]

Because URI.unescape was marked as deprecated in Ruby trunk, and generates a deprecation warning in 2.4. I tried digging into the issue tracker, but there's no explanation why it was deprecated. You'd need to ask the right person on the Ruby core team.

Blindly suggesting and replacing valid use cases without explaining why is extremely unhelpful and non educational.

I agree, and the educational aspect is arguably the more important one. This message was ported directly from the commit in Ruby trunk. Perhaps "obsolete" should be reworded to "deprecated", but "obsolete" is the wording used in Ruby's own deprecation warning, and the suggested replacement was made by Ruby core team members themselves.

[yuki24]

Thanks @Drenmi for your fantastic explanation! I'm now 100% a proponent of this cop.

[matkoniecz]

I found http://blade.nagaokaut.ac.jp/cgi-bin/vframe.rb/ruby/ruby-core/29293?29179-31097 but I still have no idea why Ruby core team deprecated it.