Let ameba explain the issue at the specified location (#86)

spec/ameba/cli/cmd_spec.cr

@@ -78,11 +78,57 @@ module Ameba::Cli
         c.config.should eq ""
       end
 
+      describe "-e/--explain" do
+        it "configures file/line/column" do
+          c = Cli.parse_args %w(--explain src/file.cr:3:5)
+          c.location_to_explain.should_not be_nil
+
+          location_to_explain = c.location_to_explain.not_nil!
+          location_to_explain[:file].should eq "src/file.cr"
+          location_to_explain[:line].should eq 3
+          location_to_explain[:column].should eq 5
+        end
+
+        it "raises an error if location is not valid" do
+          expect_raises(Exception, "location should have PATH:line:column") do
+            Cli.parse_args %w(--explain src/file.cr:3)
+          end
+        end
+
+        it "raises an error if line number is not valid" do
+          expect_raises(Exception, "location should have PATH:line:column") do
+            Cli.parse_args %w(--explain src/file.cr:a:3)
+          end
+        end
+
+        it "raises an error if column number is not valid" do
+          expect_raises(Exception, "location should have PATH:line:column") do
+            Cli.parse_args %w(--explain src/file.cr:3:&)
+          end
+        end
+
+        it "raises an error if line/column are missing" do
+          expect_raises(Exception, "location should have PATH:line:column") do
+            Cli.parse_args %w(--explain src/file.cr)
+          end
+        end
+      end
+
       it "accepts unknown args as files" do
         c = Cli.parse_args %w(source1.cr source2.cr)
         c.files.should eq %w(source1.cr source2.cr)
       end
 
+      it "accepts one unknown arg as explain location if it has correct format" do
+        c = Cli.parse_args %w(source.cr:3:22)
+        c.location_to_explain.should_not be_nil
+
+        location_to_explain = c.location_to_explain.not_nil!
+        location_to_explain[:file].should eq "source.cr"
+        location_to_explain[:line].should eq 3
+        location_to_explain[:column].should eq 22
+      end
+
       it "allows args to be blank" do
         c = Cli.parse_args [] of String
         c.formatter.should be_nil

spec/ameba/formatter/explain_formatter_spec.cr

@@ -0,0 +1,70 @@
+require "../../spec_helper"
+
+module Ameba
+  def explanation(source)
+    output = IO::Memory.new
+    ErrorRule.new.catch(source)
+    location = {file: "source.cr", line: 1, column: 1}
+    Formatter::ExplainFormatter.new(output, location).finished([source])
+    output.to_s
+  end
+
+  describe Formatter::ExplainFormatter do
+    describe "#location" do
+      it "returns crystal location" do
+        location = Formatter::ExplainFormatter
+          .new(STDOUT, {file: "compiler.cr", line: 3, column: 8}).location
+
+        location.is_a?(Crystal::Location).should be_true
+        location.filename.should eq "compiler.cr"
+        location.line_number.should eq 3
+        location.column_number.should eq 8
+      end
+    end
+
+    describe "#output" do
+      it "returns io" do
+        output = Formatter::ExplainFormatter
+          .new(STDOUT, {file: "compiler.cr", line: 3, column: 8}).output
+        output.should eq STDOUT
+      end
+    end
+
+    describe "#finished" do
+      it "writes issue info" do
+        source = Source.new "a = 42", "source.cr"
+        output = explanation(source)
+        output.should contain "ISSUE INFO"
+        output.should contain "This rule always adds an error"
+        output.should contain "source.cr:1:1"
+      end
+
+      it "writes affected code" do
+        source = Source.new "a = 42", "source.cr"
+        output = explanation(source)
+        output.should contain "AFFECTED CODE"
+        output.should contain "a = 42"
+      end
+
+      it "writes rule info" do
+        source = Source.new "a = 42", "source.cr"
+        output = explanation(source)
+        output.should contain "RULE INFO"
+        output.should contain "Ameba/ErrorRule"
+        output.should contain "Always adds an error at 1:1"
+      end
+
+      it "writes detailed description" do
+        source = Source.new "a = 42", "source.cr"
+        output = explanation(source)
+        output.should contain "DETAILED DESCRIPTION"
+        output.should contain "TO BE DONE..."
+      end
+
+      it "writes nothing if location not found" do
+        source = Source.new "a = 42", "another_source.cr"
+        explanation(source).should be_empty
+      end
+    end
+  end
+end

spec/ameba/formatter/util_spec.cr

@@ -0,0 +1,29 @@
+require "../../spec_helper"
+
+module Ameba::Formatter
+  class Subject
+    include Util
+  end
+
+  subject = Subject.new
+
+  describe Util do
+    describe "#affected_code" do
+      it "returns nil if there is no such a line number" do
+        source = Source.new %(
+          a = 1
+        )
+        location = Crystal::Location.new("filename", 2, 1)
+        subject.affected_code(source, location).should be_nil
+      end
+
+      it "returns correct line if it is found" do
+        source = Source.new %(
+          a = 1
+        )
+        location = Crystal::Location.new("filename", 1, 1)
+        subject.affected_code(source, location).should eq "> a = 1\n  \e[33m^\e[0m"
+      end
+    end
+  end
+end

spec/ameba/runner_spec.cr

@@ -90,6 +90,41 @@ module Ameba
       end
     end
 
+    describe "#explain" do
+      io = IO::Memory.new
+
+      it "writes nothing if sources are valid" do
+        io.clear
+        runner = runner(formatter: formatter).run
+        runner.explain({file: "source.cr", line: 1, column: 2}, io)
+        io.to_s.should be_empty
+      end
+
+      it "writes the explanation if sources are not valid and location found" do
+        io.clear
+        rules = [ErrorRule.new] of Rule::Base
+        source = Source.new %(
+            a = 1
+          ), "source.cr"
+
+        runner = Runner.new(rules, [source], formatter).run
+        runner.explain({file: "source.cr", line: 1, column: 1}, io)
+        io.to_s.should_not be_empty
+      end
+
+      it "writes nothing if sources are not valid and location is not found" do
+        io.clear
+        rules = [ErrorRule.new] of Rule::Base
+        source = Source.new %(
+            a = 1
+          ), "source.cr"
+
+        runner = Runner.new(rules, [source], formatter).run
+        runner.explain({file: "source.cr", line: 1, column: 2}, io)
+        io.to_s.should be_empty
+      end
+    end
+
     describe "#success?" do
       it "returns true if runner has not been run" do
         runner.success?.should be_true