Merge pull request #172 from itsallcode/feature/#165_File_and_line_nu…

…mber_in_report

Feature/#165 file and line number in report

doc/design.md

@@ -327,6 +327,40 @@ Covers:
 
 Needs: impl, utest
 
+#### Plain Text Report Contains Specification Item Origin
+`dsn~reporting.plain-text.specification-item-origin~1`
+
+If enabled, the plain text report shows the origin of a specification item
+
+* for files: `<absolute path to file>:<line number>`
+
+Rationale:
+
+This format is recognized by most IDEs and automatically turned into a link in the IDE's console.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+#### Plain Text Report Link Contains Specification Item Origin
+`dsn~reporting.plain-text.linked-specification-item-origin~1`
+
+If enabled, the links in the plain text report show the origin of a specification item
+
+* for files: `<absolute path to file>:<line number>`
+
+Rationale:
+
+This format is recognized by most IDEs and automatically turned into a link in the IDE's console.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+Needs: impl, utest, itest
+
+### HTML Report
+
 #### HTML Report Inlines CSS
 `dsn~reporting.html.inline_css~1`
 
@@ -354,6 +388,26 @@ Covers:
 
 Needs: impl, itest
 
+#### HTML Report Contains Specification Item Origin
+`dsn~reporting.html.specification-item-origin~1`
+
+If enabled, the HTML report shows the origin of a specification item as an HTML link pointing to the source.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+#### HTML Report Link Contains Specification Item Origin
+`dsn~reporting.html.linked-specification-item-origin~1`
+
+If enabled, the links in the plain text report show the origin of a specification item as an HTML link pointing to the source.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+Needs: impl, utest, itest
+
 # Deployment View
 
 # Concepts

doc/system_requirements.md

@@ -452,6 +452,25 @@ Reports are the main way to find out if a projects requirements are covered prop
 
 #### Common Report Functions
 
+##### Requirement Origin in Report
+`req~reporting.requirement-origin~1`
+
+Users can choose to display the requirement origin (e.g. file and line number) in reports:
+
+* In the body of a specification item
+* For each link to a specification item 
+
+Rationale:
+
+This is especially useful for debugging since it makes finding broken sources faster.
+
+Covers:
+
+* [feat~plain-text-report~1](#plain-text-report)
+* [feat~html-report~1](#html-report)
+
+Needs: dsn
+
 #### Plain Text Report
 The plain text report is the most basic report variant. It serves two main purposes:
 

doc/usage.txt

@@ -16,6 +16,8 @@ Tracing options:
 Converting options:
   -o, --output-format format   Requirements format, one of "specobject"
                                Defaults to "specobject"
+  -s, --show-origin            Show the origin of specification items
+                               (e.g. file and line number)             
 
 Common options: 
   -f, --file path              The output file. Defaults to STDOUT.

doc/user_guide.md

@@ -420,59 +420,105 @@ Defaults to the platform standard if not given.
 
 If you are a software developer planning to integrate OFT into one of your programs or scripts, you will probably want to use the OFT API.
 
-Below you find a few short examples of how to use the OFT API. For details check the JavaDoc documentation of the interfaces in the source code.
-
-* [org.itsallcode.openfasttrace.Converter](../src/main/java/org/itsallcoded/openfasttrace/Converter.java)
-* [org.itsallcode.openfasttrace.Reporter](../src/main/java/org/itsallcoded/openfasttrace/Reporter.java)
+Below you find a few short examples of how to use the OFT API. For details check the JavaDoc documentation of the interface [org.itsallcode.openfasttrace.Oft](../src/main/java/org/itsallcoded/openfasttrace/Oft.java) in the source code.
 
 ### Using OFT From Java
 
 The Java interface uses the "fluent programming" paradigm to make the code more compact and easy to read.
 
-#### Using the Converter From Java
+The steps that you need to program using the OFT API depend on whether you want to covert between requirement formats
+
+    import -> export
+
+or run a report.
+
+     import -> link -> trace -> report
+
+#### Converting File from Java
 
-The following example code configures a `Converter` to read input form the relative paths `doc`, `src/main/java` and `src/main/test` and output the result to `/tmp/out.xml` in SpecObject format using Unix newlines. 
+The following example code use a OFT as a converter that scans the current working directory recursively (default import setting) and exports the found artifacts with the standard settings to a ReqM2 file. 
 
 ```JAVA
-import org.itsallcode.openfasttrace.Converter;
-import org.itsallcode.openfasttrace.core.Newline;
-import org.itsallcode.openfasttrace.mode.ConvertMode;
+import org.itsallcode.openfasttrace.Oft;
+import org.itsallcode.openfasttrace.core.SpecificationItem;
+```
 
-final List<String> inputs = Arrays.asList("doc", "src/main/java", "src/main/test");
-final Converter converter = new ConvertMode();
+Select input paths and import specification items from there:
 
-converter.addInputs(inputs)
-         .setNewline(Newline.UNIX)
-         .convertToFileInFormat("/tmp/out.xml", "specobject");
+```JAVA
+final Oft oft = Oft.create();
+final List<SpecificationItem> items = oft.importItems(settings);
 ```
 
-#### Using the Tracer From Java
+Export the items:
 
-The example below shows how to read documents for the `doc` directory ignoring the artifact types `feat` and `dsn`. The collected specification items are then traced and finally output in a plain text report to STDOUT with verbosity level `ALL`. 
+```JAVA
+oft.exportToPath(items, Paths.get("/output/path/export.oreqm"));
+```
+
+#### Tracing and Reporting From Java
+
+The example below shows how to use OFT as a reporter.  
 
 ```JAVA
-import org.itsallcode.openfasttrace.Reporter;
+import org.itsallcode.openfasttrace.Oft;
+import org.itsallcode.openfasttrace.core.LinkedSpecificationItem;
+import org.itsallcode.openfasttrace.core.SpecificationItem;
 import org.itsallcode.openfasttrace.core.Trace;
-import org.itsallcode.openfasttrace.mode.ReportMode;
+```
+
+The import is similar to the converter case, except this time we add an input path explicitly for the sake of demonstration: 
 
-final List<String> inputs = Arrays.asList("doc");
-final List<String> ignoreTypes = Arras.asList("feat", "dsn"); 
-final Reporter reporter = new ReportMode();
+```JAVA
+final ImportSettings settings = ImportSettings //
+        .builder() //
+        .addInputs("/input/path") //
+        .build;
+final Oft oft = Oft.create();
+final List<SpecificationItem> items = oft.importItems(settings);
+```
 
-reporter.addInputs(inputs)
-        .ignoreArtifactTypes(ignoreTypes);
+Now link the items together (i.e. make them navigable):
 
-final Trace trace = reporter.trace();
+```JAVA
+final List<LinkedSpecificationItem> linkedItems = oft.link(items);
+```
 
-reporter.setReportVerbosity(ReportVerbosity.ALL)
-        .reportToStdOutInFormat(trace, "plain");
+Run the tracer on the linked items:
 
-if(trace.isAllCovered())
+```JAVA
+final Trace trace = oft.trace(linkedItems);
+```
+
+Create a report from the trace:
+
+```JAVA
+oft.reportToStdOut(trace);
+```
+
+You can also use the trace results in you own code:
+
+```JAVA
+if (trace.hasNoDefects())
 {
-    // do something
+    // ... do something
 }
 ```
 
+#### Configuring the Steps
+
+Import, export and report each have a overloaded variant that can be configured using the following classes
+
+* [org.itsallcode.openfasttrace.ImportSettings](../src/main/java/org/itsallcoded/openfasttrace/ImportSettings.java)
+* [org.itsallcode.openfasttrace.ExportSettings](../src/main/java/org/itsallcoded/openfasttrace/ExportSettings.java)
+* [org.itsallcode.openfasttrace.ReportSettings](../src/main/java/org/itsallcoded/openfasttrace/ReportSettings.java)
+
+Each of those classes comes with a builder which is called like this:
+
+```JAVA
+ReportSettings settings = ReportSettings.builder().newline(Newline.UNIX).build();
+```
+
 ## Tool Support
 
 ### Tools for Authoring OFT Documents

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.itsallcode</groupId>
     <artifactId>openfasttrace</artifactId>
-    <version>1.2.2</version>
+    <version>2.0.0</version>
     <name>OpenFastTrace</name>
     <description>Free requirement tracking suite</description>
     <url>https://github.com/itsallcode/openfasttrace</url>
@@ -240,7 +240,7 @@
                 </executions>
                 <configuration>
                     <mainClass>org.itsallcode.openfasttrace.cli.CliStarter</mainClass>
-                    <commandlineArgs>trace doc src/main/java src/test/java</commandlineArgs>
+                    <commandlineArgs>trace -s doc src/main/java src/test/java</commandlineArgs>
                 </configuration>
             </plugin>
             <plugin>