Merge pull request #317 from paulo-ferraz-oliveira/feature/minor-maintenance-updates

Maintenance updates

Author: elbrujohalcon

.github/workflows/ci.yml

@@ -1,27 +1,22 @@
 ---
 name: build
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
+on: [push, pull_request]
 jobs:
   ci:
     name: OTP ${{matrix.otp_vsn}} on ${{matrix.os}}
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        otp_vsn: [23, 24, 25]
-        os: [ubuntu-20.04, windows-latest]
+        otp_vsn: ['24', '25', '26']
+        rebar3_vsn: ['3.22']
+        os: [ubuntu-22.04, windows-2022]
     steps:
       - uses: actions/checkout@v3
       - uses: erlef/setup-beam@v1
         id: setup-beam
         with:
           otp-version: ${{matrix.otp_vsn}}
-          rebar3-version: '3.20'
+          rebar3-version: ${{matrix.rebar3_vsn}}
       - name: Restore _build
         uses: actions/cache@v3
         with:
@@ -43,7 +38,7 @@ jobs:
       - name: Compile
         run: rebar3 compile
       - name: Format check
-        if: ${{ matrix.os == 'ubuntu-20.04' }}
+        if: ${{ matrix.os == 'ubuntu-22.04' }}
         run: rebar3 format --verify
       - name: Run test
         run: rebar3 test

.github/workflows/lint.yml

@@ -5,14 +5,14 @@ on: [push, pull_request]
 
 jobs:
   md_and_yml:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
 
     steps:
       - uses: actions/checkout@v3
 
       # uses .markdownlint.yml for configuration
       - name: markdownlint
-        uses: DavidAnson/markdownlint-cli2-action@v5
+        uses: DavidAnson/markdownlint-cli2-action@v11
         with:
           globs: |
             LICENSE

.gitignore

@@ -1,18 +1,10 @@
-.eunit
-.rebar
-deps
-ebin
-*.o
-*.beam
-*.plt
 erl_crash.dump
-log*/
-_build
+_*
+doc/
+rebar3.crashdump
+.rebar3
+logs
+test/**/*.beam
+
 # Ignore elvis escript
 elvis
-rebar
-elvis.d
-doc
-rebar3.crashdump
-.rebar3/
-rebar3

CONTRIBUTING.md

@@ -33,4 +33,4 @@ file.
 ## Questions?
 
 If you have any questions or general comments regarding how to contribute, please use our public
-[hipchat room](http://inaka.net/hipchat).
+Erlanger Slack channel: [#elvis](https://erlanger.slack.com/archives/C01073W0E15).

LICENSE

@@ -2,7 +2,7 @@
 
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -194,7 +194,7 @@
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+       https://www.apache.org/licenses/LICENSE-2.0
 
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,

README.md

@@ -1,9 +1,7 @@
-# elvis_core [![GitHub Actions CI][ci-img]][ci] [![Erlang Support][support-img]][support]
+# elvis_core
 
-[ci]: https://github.com/inaka/elvis_core
-[ci-img]: https://github.com/inaka/elvis_core/workflows/build/badge.svg
-[support]: http://www.erlang.org
-[support-img]: https://img.shields.io/badge/Erlang/OTP-23+-blue
+[![GitHub Actions CI](https://github.com/inaka/elvis_core/workflows/build/badge.svg)](https://github.com/inaka/elvis_core)
+[![Erlang Support](https://img.shields.io/badge/Erlang/OTP-24+-blue)](https://www.erlang.org)
 
 `elvis_core` is the core library for the [`elvis`](https://github.com/inaka/elvis) Erlang style
 reviewer. It is also used by [`rebar3_lint`](https://github.com/project-fifo/rebar3_lint) for easier
@@ -59,7 +57,7 @@ current directory. If no configuration is found `{invalid_config, _}` is thrown.
 #### Providing configuration as a value
 
 Another option for using `elvis_core` from the shell is to explicitly provide the configuration as
-an argument to `rock/1`:
+an argument to `elvis_core:rock/1`:
 
 ```shell
 1> ElvisConfig = [#{dirs => ["src"], filter => "*.erl", rules => []}].
@@ -241,16 +239,16 @@ environment variables, i.e. as they would be found by `application:get_env/2,3`.
 ### Pre-defined rules
 
 A reference to all pre-defined rules (and some other information) implemented in `elvis_core` can be
-found in this repository's [RULES.md](RULES.md).
+found in this repository's [RULES.md](https://github.com/inaka/elvis_core/blob/main/RULES.md).
 
 ### User-defined rules
 
 The implementation of a new rule is a function that takes 3 arguments in the following order:
 
-1. `elvis_config:config()`: the value of option `config` as found in the
+1. `t:elvis_config:config()`: the value of option `config` as found in the
 [configuration](#configuration),
-1. `elvis_file:file()`: the file to be analyzed,
-1. `map()`: a configuration map specific to your user-defined rule.
+1. `t:elvis_file:file()`: the file to be analyzed,
+1. `t:erlang:map()`: a configuration map specific to your user-defined rule.
 
 This means you can define rules of your own (user-defined rules) as long as the functions that
 implement them respect this interface.

RULES.md

@@ -45,7 +45,7 @@ identified with `(since ...)` for convenience purposes.
 - [No Match in Condition](doc_rules/elvis_style/no_match_in_condition.md)
 - [No Nested try...catch Blocks](doc_rules/elvis_style/no_nested_try_catch.md)
 - [No Single-Clause Case Statements](doc_rules/elvis_style/no_single_clause_case.md)
-- [No Space after #](doc_rules/elvis_style/no_space_after_pount.md)
+- [No Space after #](doc_rules/elvis_style/no_space_after_pound.md)
 - [No Space](doc_rules/elvis_style/no_space.md)
 - [No Spec With Records](doc_rules/elvis_style/no_spec_with_records.md)
 - [No Specs](doc_rules/elvis_style/no_specs.md)

doc_rules/elvis_style/dont_repeat_yourself.md

@@ -1,6 +1,6 @@
 # Don't Repeat Yourself
 
-The *Don't Repeat Yourself* ([DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself)) rule checks
+The *Don't Repeat Yourself* ([DRY](https://en.wikipedia.org/wiki/Don't_repeat_yourself)) rule checks
 if there is repeated code within a module. A piece of code is considered repeated or duplicated when
 its structure can be found in at least another piece of code in the same module.
 

doc_rules/elvis_style/no_common_caveats_call.md

@@ -2,7 +2,7 @@
 
 (since [0.4.0](https://github.com/inaka/elvis_core/releases/tag/0.4.0))
 
-The [Erlang Efficiency Guide](http://erlang.org/doc/efficiency_guide/commoncaveats.html) has a list
+The [Erlang Efficiency Guide](https://erlang.org/doc/efficiency_guide/commoncaveats.html) has a list
 of "Common Caveats" suggesting more efficient alternatives to several common functions.  This rule
 provides warnings if you call "inefficient" functions with entirely equivalent (efficient)
 alternatives.

doc_rules/elvis_style/no_successive_maps.md

@@ -3,7 +3,7 @@
 (since [2.0.0](https://github.com/inaka/elvis_core/releases/tag/2.0.0))
 
 The idea behind this rule comes from
-[this email](http://erlang.org/pipermail/erlang-questions/2017-April/092112.html) by @kvakvs.
+[this email](https://erlang.org/pipermail/erlang-questions/2017-April/092112.html) by @kvakvs.
 Basically, the warning is emitted if a developer _forgets a comma_ and writes something like the following:
 
 ```erlang

doc_rules/elvis_style/operator_spaces.md

@@ -0,0 +1,35 @@
+# Operator Spaces
+
+There should be a space in the position (e.g., `right` or `left`) of the operators specified. The
+operator can be any string.
+
+> Works on `.beam` file? Not really! (it consumes results Ok, but these might be unexpected)
+
+## Options
+
+- `rules :: [{right | left, string()}].`
+  - default:
+    - before [1.5.0](https://github.com/inaka/elvis_core/releases/tag/1.5.0): `[{right, ","},
+    {right, "++"}, {left, "++"}]`
+    - since [1.5.0](https://github.com/inaka/elvis_core/releases/tag/1.5.0):
+
+```erlang
+          [{right, "++"}, {left, "++"}, {right, "="}, {left, "="}, {right, "+"}, {left, "+"},
+           {right, "-"}, {left, "-"}, {right, "*"}, {left, "*"}, {right, "/"}, {left, "/"},
+           {right, "=<"}, {left, "=<"}, {right, "<"}, {left, "<"}, {right, ">"}, {left, ">"},
+           {right, ">="}, {left, ">="}, {right, "=="}, {left, "=="}, {right, "=:="}, {left, "=:="},
+           {right, "/="}, {left, "/="}, {right, "=/="}, {left, "=/="}, {right, "--"}, {left, "--"},
+           {right, "=>"}, {left, "=>"}, {right, ":="}, {left, ":="}, {right, "<-"}, {left, "<-"},
+           {right, "<="}, {left, "<="}, {right, "||"}, {left, "||"}, {right, "|"}, {left, "|"},
+           {right, "::"}, {left, "::"}, {right, "->"}, {left, "->"}, {right, ","}]
+```
+
+## Example
+
+```erlang
+{elvis_style, operator_spaces, #{ rules => [{right, ","}
+                                          , {right, "++"}
+                                          , {left, "++"}
+                                           ]
+                                }}
+```

rebar.config

@@ -1,61 +1,58 @@
-%% -*- mode: erlang;erlang-indent-level: 2;indent-tabs-mode: nil -*-
-%% ex: ts=4 sw=4 ft=erlang et
+%% == Compiler and Profiles ==
 
-%% == Erlang Compiler ==
+{erl_opts,
+ [warn_unused_import, warn_export_vars, warnings_as_errors, verbose, report, debug_info]}.
 
-%% Erlang compiler options
-{erl_opts, [debug_info, warn_export_vars, warn_missing_spec, warn_unused_import]}.
+{minimum_otp_vsn, "23"}.
 
 {profiles,
  [{test,
    [{extra_src_dirs, ["test/examples"]},
     {deps, [{meck, "0.9.2"}]},
     {erl_opts, [nowarn_missing_spec, nowarn_export_all]},
-    {dialyzer, [{warnings, [no_return, unmatched_returns, error_handling]}]}]}]}.
+    {dialyzer, [{warnings, [no_return, error_handling]}, {plt_extra_apps, [common_test]}]},
+    {ct_opts, [{sys_config, ["./config/test.config"]}, {logdir, "./logs"}, {verbose, true}]},
+    {cover_enabled, true},
+    {cover_opts, [verbose]}]}]}.
 
-{ct_opts, [{sys_config, ["./config/test.config"]}, {logdir, "./logs"}, {verbose, true}]}.
+{alias, [{test, [compile, format, hank, xref, dialyzer, ct, cover, ex_doc]}]}.
 
-%% == Cover ==
-
-{cover_enabled, true}.
-
-{cover_opts, [verbose]}.
+{shell, [{config, "config/test.config"}]}.
 
-%% == Dependencies ==
+%% == Dependencies and plugins ==
 
-{deps, [{zipper, "1.0.1"}, {katana_code, "~> 2.0.2"}]}.
+{deps, [{zipper, "1.0.1"}, {katana_code, "~> 2.1.0"}]}.
 
-%% == Dialyzer ==
+{project_plugins,
+ [{rebar3_hank, "~> 1.4.0"},
+  {rebar3_hex, "~> 7.0.7"},
+  {rebar3_format, "~> 1.3.0"},
+  {rebar3_ex_doc, "0.2.18"}]}.
 
-{dialyzer,
- [{warnings, [no_return, unmatched_returns, error_handling, unknown]},
-  {plt_apps, top_level_deps},
-  {plt_extra_apps, [kernel, stdlib]},
-  {plt_location, local}]}.
+%% == Documentation ==
 
-{shell, [{config, "config/test.config"}]}.
+{ex_doc,
+ [{source_url, <<"https://github.com/inaka/elvis_core">>},
+  {extras, [<<"README.md">>, <<"LICENSE">>]},
+  {main, <<"readme">>}]}.
 
-%% == xref ==
+{hex, [{doc, #{provider => ex_doc}}]}.
 
-{xref_checks, [undefined_function_calls, locals_not_used, deprecated_function_calls]}.
+%% == Format ==
 
-%% == Aliases ==
+{format,
+ [{files,
+   ["config/**/*.config", "src/**/*.app.src", "src/**/*.erl", "test/*.erl", "*.config"]}]}.
 
-{alias, [{test, [format, xref, dialyzer, hank, ct, cover, edoc]}]}.
+%% == Hank ==
 
-{project_plugins,
- [{rebar3_hex, "~> 7.0.1"}, {rebar3_format, "~> 1.2.0"}, {rebar3_hank, "~> 1.3.0"}]}.
+{hank, [{ignore, ["test/*/**"]}]}.
 
-%% == hank ==
+%% == Dialyzer + XRef ==
 
-{hank,
- [{ignore,
-   [{"test/*/**", unnecessary_function_arguments},
-    {"test/*/**", unused_macros},
-    {"test/*/**", unused_callbacks}]}]}.
+{dialyzer, [{warnings, [no_return, unmatched_returns, error_handling, unknown]}]}.
 
-%% == format ==
+{xref_checks,
+ [undefined_function_calls, deprecated_function_calls, deprecated_functions]}.
 
-{format,
- [{files,
-   ["config/**/*.config", "src/**/*.app.src", "src/**/*.erl", "test/*.erl", "*.config"]}]}.
+{xref_extra_paths, ["test/**"]}.

src/elvis_core.app.src

@@ -7,5 +7,5 @@
   {modules, [elvis_core, elvis_config, elvis_result, elvis_utils, elvis_style]},
   {registered, []},
   {licenses, ["Apache 2.0"]},
-  {links, [{"Github", "https://github.com/inaka/elvis_core"}]},
+  {links, [{"GitHub", "https://github.com/inaka/elvis_core"}]},
   {build_tools, ["rebar3"]}]}.

src/elvis_core.erl

@@ -142,6 +142,7 @@ main([]) ->
 %%% Private
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+%% @private
 -spec combine_results(ok | {fail, [elvis_result:file()]},
                       ok | {fail, [elvis_result:file()]}) ->
                          ok | {fail, [elvis_result:file()]}.
@@ -157,6 +158,7 @@ apply_rules_and_print(Config, File) ->
     elvis_result:print_results(Results),
     Results.
 
+%% @private
 -spec apply_rules(elvis_config:configs() | elvis_config:config(),
                   File :: elvis_file:file()) ->
                      elvis_result:file().
@@ -168,25 +170,29 @@ apply_rules(Config, File) ->
         lists:foldl(fun apply_rule/2, Acc, merge_rules({file, ParseTree}, lists:flatten(Rules))),
     elvis_result:new(file, File, RulesResults).
 
+%% @private
 merge_rules({file, ParseTree}, ElvisConfigRules) ->
     ElvisAttrs =
         elvis_code:find(fun is_elvis_attr/1, ParseTree, #{traverse => content, mode => node}),
     ElvisAttrRules = elvis_attr_rules(ElvisAttrs),
     elvis_config:merge_rules(ElvisAttrRules, ElvisConfigRules).
 
+%% @private
 is_elvis_attr(Node) ->
     ktn_code:type(Node) =:= elvis.
 
+%% @private
 elvis_attr_rules([] = _ElvisAttrs) ->
     [];
 elvis_attr_rules(ElvisAttrs) ->
     [Rule || ElvisAttr <- ElvisAttrs, Rule <- ktn_code:attr(value, ElvisAttr)].
 
+%% @private
 -spec apply_rule({Mod, Fun} | {Mod, Fun, RuleCfg}, {Results, ElvisCfg, File}) -> Result
     when Mod :: module(),
          Fun :: atom(),
          RuleCfg :: rule_config(),
-         Results :: [elvis_result:rule()],
+         Results :: [elvis_result:rule() | elvis_result:elvis_error()],
          ElvisCfg :: elvis_config:config(),
          File :: elvis_file:file(),
          Result :: {Results, ElvisCfg, File}.
@@ -223,6 +229,7 @@ apply_rule({Module, Function, ConfigArgs}, {Result, Config, File}) ->
         end,
     {[RuleResult | Result], Config, File}.
 
+%% @private
 %% @doc Process a tules configuration argument and converts it to a map.
 ensure_config_map(_, _, Map) when is_map(Map) ->
     Map;