Brem rules score tutorial feedback

bazel/rules/rules_score/docs/user_guide/tutorial/architecture.rst

@@ -86,4 +86,6 @@ in Bazel. Therefore following bazel rules are available:
 
 Once the architecture is in place, the build parses the PlantUML diagram and validates it against the Bazel model. It verifies element names, structural hierarchy, and consistency between the declared diagram and the implemented architecture.
 
+How is this verification done? i.e. what build / test target?
+
 → Full guide: :doc:`../architectural_design`

bazel/rules/rules_score/docs/user_guide/tutorial/requirements.rst

@@ -77,4 +77,7 @@ To validate TRLC syntax and Traceability within the requirements, each of the re
 bazel targets exposes via a marco already a test target, which can be run via e.g.:
 ``bazel test //:assumed_system_requirements_test``.
 
+Why does it specify a relative path here? In the Build part it mentions building from the root, I think this distinction should be mentioned here (and saying to run the command from bazel/rules/rules_score/examples/minimal directory). Building from root or from the minimal directory seems to cause an issue with include paths? If building with full path, the include should be 
+#include "bazel/rules/rules_score/examples/minimal/src/my_unit.h" and if it's relative, it should be #include "src/my_unit.h". It doesn't seem to support building from the root and the tutorials dir.
+
 → Full guide: :doc:`../requirements`

bazel/rules/rules_score/docs/user_guide/tutorial/unit_design.rst

@@ -28,6 +28,7 @@ class_design.puml
 src/my_unit.h
 --------------
 
+Is this required? "can" is very vague, it should say exactly when it's required / what the benefit is.
 The public interface of the unit can be tied to its source symbols via a ``// trace:`` tag.
 
 .. literalinclude:: ../../examples/minimal/src/my_unit.h
@@ -76,8 +77,10 @@ from the ``unit``:
 
 The ``unit_design.static`` attribute accepts PlantUML files (class, state,
 object diagrams); use ``dynamic`` for sequence and activity diagrams.
+scope here is referring to unit(), not unit_design, right?
 ``scope`` declares which targets the unit "owns" — targets outside the scope
 that appear in the transitive implementation closure fail the scope check at
 build time.
+What's the transitive implementation closure?
 
 → Full guide: :doc:`../unit_design`

bazel/rules/rules_score/docs/user_guide/tutorial/validation.rst

@@ -25,10 +25,10 @@ Instead, test intent is captured as a **Given-When-Then** description right
 next to the code as record properties in the test name/body itself. The specification will
 then be rendered in the traceability report, together with the test results and coverage information.
 
-test/my_unit_test.cpp
+src/my_unit_test.cpp
 ----------------------
 
-.. literalinclude:: ../../examples/minimal/test/my_unit_test.cpp
+.. literalinclude:: ../../examples/minimal/src/my_unit_test.cpp
    :language: cpp
    :lines: 14-
 
@@ -45,6 +45,7 @@ They are picked up the same way as ``lobster-tracing`` — as plain
 traceability report. Test cases without them are still traced, but show up
 without a Given-When-Then specification.
 
+How do we generate the lobster report to see the given when then output?
 BUILD
 ------
 
@@ -73,4 +74,4 @@ Run the tests with:
 
    bazel test //:my_unit_test
 
-→ Full guide: :doc:`../unit_design`
+→ Full guide: :doc:`../validation`

bazel/rules/rules_score/examples/minimal/BUILD

@@ -33,7 +33,7 @@ filegroup(
         "requirements/feature_requirements.trlc",
         "src/my_unit.cpp",
         "src/my_unit.h",
-        "test/my_unit_test.cpp",
+        "src/my_unit_test.cpp",
     ],
     visibility = ["//bazel/rules/rules_score:__pkg__"],
 )
@@ -64,7 +64,7 @@ cc_library(
 
 cc_test(
     name = "my_unit_test",
-    srcs = ["test/my_unit_test.cpp"],
+    srcs = ["src/my_unit_test.cpp"],
     deps = [
         ":my_unit_lib",
         "@googletest//:gtest_main",
@@ -76,6 +76,13 @@ unit_design(
     static = ["docs/class_design.puml"],
 )
 
+# bazel build //bazel/rules/rules_score/examples/minimal:MyUnit currently fails to complile:
+# Failed to parse /home/q624760/.cache/bazel/_bazel_q624760/7f8ab4cad6514b4c7cf0f5238512a834/sandbox/linux-sandbox/729/execroot/_main/bazel/rules/rules_score/examples/minimal/docs/class_design.puml with any available parser
+#   Parsers tried: Component, Activity, Class, Sequence
+#   Parser with longest match: Class
+#   Failed at line 19: - _store : dict[str, str]
+#   Error: Pest error: Parsing error at (19, 21), expected [NUMBER], got []
+# Target //bazel/rules/rules_score/examples/minimal:MyUnit failed to build
 unit(
     name = "MyUnit",
     scope = ["//:my_unit_lib"],
@@ -99,5 +106,6 @@ dependable_element(
     dependability_analysis = [],
     integrity_level = "B",
     requirements = [":feature_requirements"],
+    # It would be good to have an example of a component test which tests the interaction of 2 components / units
     tests = [],
 )

bazel/rules/rules_score/examples/minimal/test/my_unit_test.cpp → bazel/rules/rules_score/examples/minimal/src/my_unit_test.cpp

@@ -24,14 +24,25 @@ TEST(MyUnitTest, ConfigureAndGet) {
                                   "configure is called with a known key");
   ::testing::Test::RecordProperty("then", "get returns the configured value");
 
-  MyUnit unit;
+  // Given a default-constructed MyUnit instance
+  MyUnit unit{};
+
+  // When configure is called with a key that hasn't been configured yet
   unit.configure("mode", "fast");
+
+  // Then get returns the configured value
   EXPECT_EQ(unit.get("mode"), "fast");
 }
 
 TEST(MyUnitTest, MissingKeyReturnsEmpty) {
   ::testing::Test::RecordProperty("lobster-tracing", "MinimalExample.FEAT_002");
 
-  MyUnit unit;
-  EXPECT_EQ(unit.get("undefined"), "");
+  // Given a default-constructed MyUnit instance
+  MyUnit unit{};
+
+  // When get is called with a key that hasn't been configured yet
+  const auto retrieved_value = unit.get("undefined");
+
+  // Then get returns an empty string
+  EXPECT_EQ(retrieved_value, "");
 }