#338: Colored console report

api/src/main/java/org/itsallcode/openfasttrace/api/ColorScheme.java

@@ -0,0 +1,13 @@
+package org.itsallcode.openfasttrace.api;
+
+/**
+ * Color schemes
+ */
+public enum ColorScheme {
+    /** Black and white */
+    BLACK_AND_WHITE,
+    /** Monochrome (e.g for printers) */
+    MONOCHROME,
+    /** COLOR */
+    COLOR
+}

api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java

@@ -4,6 +4,8 @@
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
 import org.itsallcode.openfasttrace.api.report.ReportVerbosity;
 
+import java.util.Objects;
+
 /**
  * This class implements a parameter object to control the settings of OFT's
  * report mode.
@@ -14,13 +16,15 @@ public class ReportSettings
     private final boolean showOrigin;
     private final String outputFormat;
     private final Newline newline;
+    private final ColorScheme colorScheme;
 
     private ReportSettings(final Builder builder)
     {
         this.verbosity = builder.verbosity;
         this.showOrigin = builder.showOrigin;
         this.outputFormat = builder.outputFormat;
         this.newline = builder.newline;
+        this.colorScheme = Objects.requireNonNull(builder.colorScheme);
     }
 
     /**
@@ -63,6 +67,15 @@ public Newline getNewline()
         return this.newline;
     }
 
+    /**
+     * Get the color scheme
+     *
+     * @return color scheme
+     */
+    public ColorScheme getColorScheme() {
+        return this.colorScheme;
+    }
+
     /**
      * Create default report settings
      * 
@@ -92,6 +105,7 @@ public static class Builder
         private String outputFormat = ReportConstants.DEFAULT_REPORT_FORMAT;
         private boolean showOrigin = false;
         private ReportVerbosity verbosity = ReportVerbosity.FAILURE_DETAILS;
+        private ColorScheme colorScheme = ColorScheme.BLACK_AND_WHITE;
 
         private Builder()
         {
@@ -160,5 +174,16 @@ public Builder newline(final Newline newline)
             this.newline = newline;
             return this;
         }
+
+        /**
+         * Set the desired color scheme
+         *
+         * @param colorScheme color scheme to use
+         * @return <code>this</code> for fluent programming
+         */
+        public Builder colorScheme(final ColorScheme colorScheme) {
+            this.colorScheme = Objects.requireNonNull(colorScheme);
+            return this;
+        }
     }
 }

core/src/main/java/org/itsallcode/openfasttrace/core/cli/ArgumentValidator.java

@@ -40,7 +40,7 @@ private boolean validate()
     {
         final Optional<String> command = this.arguments.getCommand();
         boolean ok = false;
-        if (!command.isPresent())
+        if (command.isEmpty())
         {
             this.error = "Missing command";
             this.suggestion = "Add one of " + listCommands();
@@ -72,7 +72,7 @@ private boolean validateTraceCommand()
         if (this.arguments.getReportVerbosity() == ReportVerbosity.QUIET
                 && this.arguments.getOutputPath() != null)
         {
-            this.error = "combining stream verbosity 'quiet' and ouput to file is not supported.";
+            this.error = "combining stream verbosity 'quiet' and output to file is not supported.";
             this.suggestion = "remove output file parameter.";
         }
         else
@@ -132,5 +132,4 @@ public String getSuggestion()
     {
         return this.suggestion;
     }
-
 }

core/src/main/java/org/itsallcode/openfasttrace/core/cli/CliArguments.java

@@ -1,11 +1,10 @@
 package org.itsallcode.openfasttrace.core.cli;
 
-import static java.util.Arrays.asList;
-
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.*;
 
+import org.itsallcode.openfasttrace.api.ColorScheme;
 import org.itsallcode.openfasttrace.api.cli.DirectoryService;
 import org.itsallcode.openfasttrace.api.core.Newline;
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
@@ -37,6 +36,7 @@ public class CliArguments
     // [impl->dsn~reporting.html.linked-specification-item-origin~1]
     private boolean showOrigin;
     private final DirectoryService directoryService;
+    private ColorScheme colorScheme;
 
     /**
      * Create new {@link CliArguments}.
@@ -111,7 +111,7 @@ public List<String> getInputs()
     {
         if (this.unnamedValues == null || this.unnamedValues.size() <= 1)
         {
-            return asList(this.directoryService.getCurrent());
+            return List.of(this.directoryService.getCurrent());
         }
         return this.unnamedValues.subList(1, this.unnamedValues.size());
     }
@@ -293,6 +293,25 @@ public Set<String> getWantedTags()
         return this.wantedTags;
     }
 
+    /**
+     * Get the color scheme.
+     * <p>
+     * Defaults to {@link ColorScheme#COLOR}. The switch <code>-f</code> overrides this setting, so that the color
+     * scheme is always {@link ColorScheme#BLACK_AND_WHITE}.
+     * </p>
+     *
+     * @return the color scheme
+     */
+    public ColorScheme getColorScheme()
+    {
+        if (this.getOutputPath() == null) {
+            return (this.colorScheme == null) ? ColorScheme.COLOR : this.colorScheme;
+        }
+        else {
+            return ColorScheme.BLACK_AND_WHITE;
+        }
+    }
+
     /**
      * Set a list of tags to be applied as filter during import
      * 
@@ -349,4 +368,24 @@ public void setS(final boolean showOrigin)
     {
         setShowOrigin(showOrigin);
     }
+
+    /**
+     * Choose the color scheme.
+     *
+     * @param colorScheme color scheme to use for console output
+     */
+    public void setColorScheme(final ColorScheme colorScheme)
+    {
+        this.colorScheme = colorScheme;
+    }
+
+    /**
+     * Choose the color scheme.
+     *
+     * @param colorScheme color scheme to use for console output
+     */
+    public void setC(final ColorScheme colorScheme)
+    {
+        this.setColorScheme(colorScheme);
+    }
 }

core/src/main/java/org/itsallcode/openfasttrace/core/cli/commands/TraceCommand.java

@@ -71,6 +71,7 @@ private ReportSettings convertCommandLineArgumentsToReportSettings()
                 .verbosity(this.arguments.getReportVerbosity()) //
                 .newline(this.arguments.getNewline()) //
                 .showOrigin(this.arguments.getShowOrigin()) //
+                .colorScheme(this.arguments.getColorScheme()) //
                 .build();
     }
 }

core/src/main/resources/usage.txt

@@ -20,10 +20,14 @@ Converting options:
                                (e.g. file and line number)             
 
 Common options: 
-  -f, --file path              The output file. Defaults to STDOUT.
-  -n, --newline format         Newline format one of "unix", "windows", "oldmac"
   -a, --wanted-artifact-types  Import only specification items contained in the
                                comma-separated list
+  -c, --color-scheme scheme    Color scheme for output. One of "black-and-white",
+                               "monochrome", "color". Defaults to "color".
+                               Note that this option is ignored when -f is also
+                               set.
+  -f, --file path              The output file. Defaults to STDOUT.
+  -n, --newline format         Newline format. One of "unix", "windows", "oldmac"
   -t, --wanted-tags            Import only specification items that have at
                                least one tag contained in the comma-separated
                                list. Add a single underscore as first item in

core/src/test/java/org/itsallcode/openfasttrace/core/cli/TestArgumentValidator.java

@@ -54,7 +54,7 @@ void testTraceCommandQuietAndOutputFileGivenIsNotValid()
         cliArgs.setV(ReportVerbosity.QUIET);
         cliArgs.setOutputFile("outputFile");
         assertValidatorResult(
-                "combining stream verbosity 'quiet' and ouput to file is not supported.",
+                "combining stream verbosity 'quiet' and output to file is not supported.",
                 "remove output file parameter.");
     }
 

core/src/test/java/org/itsallcode/openfasttrace/core/cli/TestCliArguments.java

@@ -1,12 +1,13 @@
 package org.itsallcode.openfasttrace.core.cli;
 
-import static java.util.Arrays.asList;
 import static java.util.Collections.emptyList;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.*;
 
 import java.nio.file.Paths;
+import java.util.List;
 
+import org.itsallcode.openfasttrace.api.ColorScheme;
 import org.itsallcode.openfasttrace.api.core.Newline;
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
 import org.itsallcode.openfasttrace.api.report.ReportVerbosity;
@@ -54,7 +55,7 @@ void testSetOutputFormat()
     @Test
     void getStandardOutputFormatForExport()
     {
-        this.arguments.setUnnamedValues(asList(ConvertCommand.COMMAND_NAME));
+        this.arguments.setUnnamedValues(List.of(ConvertCommand.COMMAND_NAME));
         assertThat(this.arguments.getOutputFormat(),
                 equalTo(ExporterConstants.DEFAULT_OUTPUT_FORMAT));
     }
@@ -63,7 +64,7 @@ void getStandardOutputFormatForExport()
     @Test
     void getStandardOutputFormatForReport()
     {
-        this.arguments.setUnnamedValues(asList(TraceCommand.COMMAND_NAME));
+        this.arguments.setUnnamedValues(List.of(TraceCommand.COMMAND_NAME));
         assertThat(this.arguments.getOutputFormat(),
                 equalTo(ReportConstants.DEFAULT_REPORT_FORMAT));
     }
@@ -146,7 +147,7 @@ void testWantedArtifactTypesEmptyByDefault()
 
     // [utest->dsn~filtering-by-artifact-types-during-import~1]
     @Test
-    void testSetIngnoreArtifactTypes()
+    void testSetIgnoreArtifactTypes()
     {
         final String value = "impl,utest";
         this.arguments.setWantedArtifactTypes(value);
@@ -183,7 +184,7 @@ void testSetWantedTags()
 
     // [utest->dsn~filtering-by-tags-during-import~1]
     @Test
-    void testSetd()
+    void testSetD()
     {
         final String value = "client,server";
         this.arguments.setT(value);
@@ -232,4 +233,37 @@ void testSetS()
         this.arguments.setS(true);
         assertThat(this.arguments.getShowOrigin(), is(true));
     }
+
+    // [dsn~reporting.plain-text.ansi-color~1]
+    // [dsn~reporting.plain-text.ansi-font-style~1]
+    @Test
+    void testSetColorScheme()
+    {
+        this.arguments.setColorScheme(ColorScheme.MONOCHROME);
+        assertThat(this.arguments.getColorScheme(), is(ColorScheme.MONOCHROME));
+    }
+
+    // [dsn~reporting.plain-text.ansi-color~1]
+    // [dsn~reporting.plain-text.ansi-font-style~1]
+    @Test
+    void testSetC()
+    {
+        this.arguments.setC(ColorScheme.MONOCHROME);
+        assertThat(this.arguments.getColorScheme(), is(ColorScheme.MONOCHROME));
+    }
+
+
+    @Test
+    void testColorSchemeDefaultsToColor()
+    {
+        assertThat(this.arguments.getColorScheme(), is(ColorScheme.COLOR));
+    }
+
+    @Test
+    void testSetOutputFileOverridesColorSchemeSetting()
+    {
+        this.arguments.setColorScheme(ColorScheme.MONOCHROME);
+        this.arguments.setOutputFile("something");
+        assertThat(this.arguments.getColorScheme(), is(ColorScheme.BLACK_AND_WHITE));
+    }
 }

doc/spec/design.md

@@ -361,6 +361,29 @@ Covers:
 
 Needs: impl, utest
 
+### Plain Text Report ANSI Color
+`dsn~reporting.plain-text.ansi-color~1`
+
+The plain text report uses ANSI escape sequences to color the output.
+
+Covers:
+
+* `req~colored-plain-text-report~1`
+
+Needs: impl, utest
+
+### Plain Text Report ANSI Font Style
+`dsn~reporting.plain-text.ansi-font-style~1`
+
+The plain text report uses ANSI escape sequences to modify the font style of the output.
+
+Covers:
+
+* `req~colored-plain-text-report~1`
+* `req~monochrome-plain-text-report-with-font-style~1`
+
+Needs: impl, utest
+
 ### HTML Report
 
 #### HTML Report Inlines CSS

doc/spec/system_requirements.md

@@ -119,7 +119,9 @@ Needs: req
 
 A tracing report is a representation of the results of the requirement tracing OFT performs. Depending on their use, reports can be designed to be human readable, machine readable or both.
 
-#### Plain Text Report
+#### Console Reports
+
+##### Plain Text Report
 `feat~plain-text-report~1`
 
 OFT produces a tracing report in plain text.
@@ -321,7 +323,7 @@ The possible results are:
   2. Outdated:  link points to a specification item which has a higher revision number
   3. Predated:  link points to a specification item which has a lower revision number
   4. Ambiguous: link points to a specification item that has duplicates
-  5. Unwanted:  coverage provider has an artifact type the provider does not want
+  5. Unwanted:  coverage provider has an artifact type the requester does not want
   6. Orphaned:  link is broken - there is no matching coverage requester
 
 Covers:
@@ -528,6 +530,36 @@ Covers:
 
 Needs: dsn
 
+##### Monochrome Plain Text Report With Font Style
+`req~monochrome-plain-text-report-with-font-style~1`
+
+The plain text report supports different font styles to visually separate report elements.
+
+Rationale:
+
+This makes the report easier to read and works for people who are colorblind.
+
+Covers:
+
+* [feat~plain-text-report~1](#plain-text-report)
+
+Needs: dsn
+
+##### Colored Plain Text Report
+`req~colored-plain-text-report~1`
+
+The plain text report supports color to visually separate report elements.
+
+Rationale:
+
+This makes the report easier to read.
+
+Covers:
+
+* [feat~plain-text-report~1](#plain-text-report)
+
+Needs: dsn
+
 #### HTML Report
 
 ##### HTML Report is a Single File