LOBSTER Report - no schema

CHANGELOG.md

@@ -25,6 +25,11 @@
   - Added detailed examples and configuration parameters for `lobster-codebeamer`,
   `lobster-cpptest`, `lobster-report`, `lobster-html_report`, and `lobster-online_report` tools
 
+* LOBSTER report
+  - New yaml configuration file.
+  - Without need to specify level types like requirement, implementation or activity.
+  - All lobster tools will create .lobster files without schema, all elements are items.
+
 ### 1.0.2
 
 * `lobster-trlc`:

Makefile

@@ -71,8 +71,8 @@ packages: clean-packages
 	PYTHONPATH= \
 		pip3 install --prefix test_install_monolithic \
 		packages/lobster-monolithic/meta_dist/*.whl
-	diff -Naur test_install/lib/python*/site-packages/lobster test_install_monolithic/lib/python*/site-packages/lobster -x "*.pyc" -x "*pkg*" -x "pkg/*"
-	diff -Naur test_install/bin test_install_monolithic/bin -x "*pkg*" -x "pkg/*"
+	diff -Naur test_install/lib/python*/site-packages/lobster test_install_monolithic/lib/python*/site-packages/lobster -x "*.pyc" -x "*pkg*" -x "pkg/*" -x "*yamale"
+	diff -Naur test_install/bin test_install_monolithic/bin -x "*pkg*" -x "pkg/*" -x "*yamale"
 
 	# Very basic smoke test to ensure the tools are packaged properly
 	python3 -m venv test_install_monolithic_venv

data/lobster_ok.yaml

@@ -0,0 +1,15 @@
+Requirements: !LevelDefinition
+  name: Requirements
+  source:
+  - file: trlc_ok.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Code
+
+Code: !LevelDefinition
+  name: Code
+  source:
+  - file: python_ok.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements

documentation/config_files.md

@@ -1,11 +1,234 @@
 # LOBSTER Configuration Files
 
-A lobster config file (by default `lobster.conf`) declares the tracing
+A lobster config file (by default `lobster.yaml`) declares the tracing
+policy. The syntax is fairly simple and best explained by example.
+The new yaml configuration does not need an assignment to the three different 
+level types requirements, implementation or activity anymore.
+It just reflect a image of the internal stucture of the dictionary containing the 
+different level definitions.
+
+The new yaml configuration supports lobster files with version 5 and without schema.
+
+## Levels
+
+The core feature is an item level:
+A typical level declaration might look like this:
+
+``` yaml
+Code: !LevelDefinition
+  name: Code
+  source:
+  - file: cpp.lobster
+  - file: matlab.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+```
+
+What we have here is an implementation level called `Code` that has
+two data sources (a C++ extract and a MATLAB extract). This code is
+supposed to contain tracing tags that link it to items from the
+`Requirements` level.
+
+### Level attributes
+
+#### source
+
+The `source` attribute assigns a LOBSTER file to contribute to this
+level.
+
+#### traces and needs_tracing_up
+
+The `traces` attribute declares the expected tracing link. This
+declares that the items in this level are expected to be linked to
+items from that level. It is possible to have more than one level
+mentioned here (but it probably makes no sense).
+`needs_tracing_up` need tobe set to true
+
+For example, here we declare that requirements are the top-level
+(since there are no links expected), and code should trace to the
+requirements.
+
+``` yaml
+Requirements: !LevelDefinition
+  name: Requirements
+  source:
+  - file: trlc.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Code
+
+Code: !LevelDefinition
+  name: Code
+  source:
+  - file: python.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+```
+
+#### breakdown_requirements and needs_tracing_down
+
+Sometimes you might want alternatives. For example we could have two
+possibly ways to verify a requirement: by proof or by test. If we just
+do this:
+
+``` yaml
+Requirements: !LevelDefinition
+  name: Requirements
+  source:
+  - file: trlc.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Code
+  - - Unit Test
+  - - Formal Proof
+
+Code: !LevelDefinition
+  name: Code
+  source:
+  - file: ada.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+
+Unit Test: !LevelDefinition
+  name: Unit Test
+  source:
+  - file: aunit.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+
+Formal Proof: !LevelDefinition
+  name: Formal Proof
+  source:
+  - file: gnatprove.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+```
+
+Then we would get lots of errors as the tooling would require a
+requirement to be broken down into all three. The `breakdown_requirements`
+configuration can help here:
+
+
+``` yaml
+Requirements: !LevelDefinition
+  name: Requirements
+  source:
+  - file: trlc.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Code
+  - - Unit Test
+    - Formal Proof
+```
+
+Now an item is considered to be completely traced if it has both a
+link to code, and either a link to a test or a link to a proof.
+
+**Note:**
+Don't forget that the `traces` configuration is always mandatory.
+You cannot build links with a configuration that uses only `breakdown_requirements`.
+
+# Examples
+
+A simple example that just links SIMULINK models to requirements
+stored in codebeamer:
+
+``` yaml
+Requirements: !LevelDefinition
+  name: Requirements
+  source:
+  - file: cbtrace.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Models
+
+Models: !LevelDefinition
+  name: Models
+  source:
+  - file: mh_imp_trace.lobster
+  needs_tracing_up: true
+  traces:
+  - Requirements
+```
+
+A more complex example that breaks down system requirements in
+codebeamer to TRLC software requirements. The C++ implementation is
+traced against software requirements. Unit tests show software
+requirements coverage and integration tests show system requirements
+coverage. For non-functional system requirements we alternatively show
+they are met with some hand-written analysis (for which we've created
+our own custom LOBSTER trace tool).
+
+``` yaml
+System Requirements: !LevelDefinition
+  name: System Requirements
+  source:
+  - file: cbtrace.lobster
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Software Requirements
+  - - Integration Tests
+  - - Analysis
+
+Software Requirements: !LevelDefinition
+  name: Software Requirements
+  source:
+  - file: trlc.lobster
+  needs_tracing_up: true
+  traces:
+  - System Requirements
+  needs_tracing_down: true
+  breakdown_requirements:
+  - - Code
+  - - Unit Tests
+
+Code: !LevelDefinition
+  name: Code
+  source:
+  - file: cpptrace.lobster
+  needs_tracing_up: true
+  traces:
+  - Software Requirements
+
+Unit Tests: !LevelDefinition
+  name: Unit Tests
+  source:
+  - file: gtest_unit.lobster
+  needs_tracing_up: true
+  traces:
+  - Software Requirements
+
+Integration Tests: !LevelDefinition
+  name: Integration Tests
+  source:
+  - file: gtest_int.lobster
+  needs_tracing_up: true
+  traces:
+  - System Requirements
+
+Analysis: !LevelDefinition
+  name: Analysis
+  source:
+  - file: analysis.lobster
+  needs_tracing_up: true
+  traces:
+  - System Requirements
+```
+
+
+# Deprecated .conf Configuration Files
+
+The deprecated .conf lobster config file (by default `lobster.conf`) declares the tracing
 policy. The syntax is fairly simple and best explained by example.
 
 ## Levels
 
-The core feature is an item level, and there are three kinds:
+The core feature is an item level, and there are three kinds need to be assigned:
 
 * requirements (for things like trlc, codebeamer, systemweaver, doors, ...)
 * implementation (for things like code or models)
@@ -128,7 +351,7 @@ our own custom LOBSTER trace tool).
 
 ```
 requirements "System Requirements" {
-   source: "cbtrace.lobster"
+   source: "cbtrace.lobster";
    requires: "Integration Tests" or "Analysis";
 }
 

documentation/manual-lobster_codebeamer.md

@@ -67,6 +67,17 @@ You can now configure retry behavior for failed HTTPS requests using the followi
   num_request_retry: 3
   ```
 
+- `schema`
+
+  *Type*: `str`
+
+  *Description*: Per default lobster-codebeamer will generate a .lobster file with version 5 without schema `lobster-req-trace`.
+                 To generate a version 4 with schema `lobster-req-trace` add Requirement as schema into your YAML configuration file.
+  *Example*:
+  ```yaml
+  schema: Requirement
+  ```
+
 Notes:
 - Retries will **only** be attempted if `retry_error_codes` parameter is defined in the config.
 - If `num_request_retry` not defined, the default value of 5 will be used.

documentation/manual-lobster_cpp.md

@@ -9,3 +9,10 @@ for example:
 
 Here the error `clang-diagnostic-error` will be ignored.
 You can also specify a list of errors to ignore.
+
+Per default lobster-cpp will generate a .lobster file with version 5 without schema `lobster-imp-trace`.
+To generate a version 3 with schema `lobster-imp-trace` add the command line argument `kind`,
+for example:
+```bash
+> lobster-cpp --kind="imp" ...
+```

documentation/manual-lobster_cpptest.md

@@ -78,18 +78,24 @@ The regex used for each test-tag is as follows:
 ## Preparing cpptest YAML config-file
 
 You have to provide a YAML configuration file that defines the settings to be applied by the tool.
-The tool supports exactly four configuration attributes:
-`output_file`, `codebeamer_url`, `kind`, and `files`.
+The tool supports three configuration attributes:
+`output_file`, `codebeamer_url` and `files`.
 
 This file must include the `codebeamer_url`. All other attributes are optional.
 
 ```cpptest-config.yaml
 output_file: "unit_tests.lobster"
-kind: "req"
 
 codebeamer_url: "https://codebeamer.example.com/cb"
  ```
 
+Per default lobster-cpptest will generate a .lobster file with version 5 without schema `lobster-act-trace`.
+To generate a version 3 with schema `lobster-act-trace` add the optional configuration attribute `kind`,
+
+```cpptest-config.yaml
+kind: "req"
+ ```
+
 * Note: Orphan tests, will be always written into the output_file.
  Be aware these tests do not have any references.
 

documentation/manual-lobster_gtest.md

@@ -51,6 +51,13 @@ command line might look like:
 $ lobster_gtest . --out gtests.lobster
 ```
 
+Per default lobster-gtest will generate a .lobster file with version 5 without schema `lobster-imp-trace`.
+To generate a version 3 with schema `lobster-imp-trace` add the command line argument `kind`,
+
+```sh
+$ lobster_gtest --kind="imp" ...
+```
+
 ## Example
 
 The LOBSTER testsuite contains a working example:

documentation/manual-lobster_pkg.md

@@ -7,6 +7,13 @@ The generated `.lobster` file can be used with the LOBSTER traceability framewor
 
 For more details on `ecu.test` see https://www.tracetronic.com/products/ecu-test/.
 
+Per default lobster-pkg will generate a .lobster file with version 5 without schema `lobster-act-trace`.
+To generate a version 3 with schema `lobster-act-trace` add the command line argument `kind`,
+for example:
+```bash
+> lobster-pkg --kind="act" ...
+```
+
 ## Features
 
 - Parses `.pkg` and `.ta` files (or directories containing them) to extract traceability information.