v3.0.2

Highlights

• rules_score: root causes are argued by RootCauseAssessment records. They replace Mitigation and SafetyMeasure.
• rules_score: failure modes trace to concrete public API methods, generated from the public API class diagrams.
• rules_score: formal RST test specifications, and Given/When/Then text derived from gtest test names.
• rules_score: documentation is keyed by the full target label, so equal target names in different packages or repositories no longer collide.
• rules_score: $TransferInGate links fault trees, requirement ASILs are checked, and the certified-scope check is repository-aware.
• PlantUML and validation: class template parameters and specializations.
• cr_checker: // and /* */ headers are interchangeable.

Breaking changes

These changes require edits to build files, TRLC files or PlantUML diagrams.

rules_score: root cause assessments replace mitigations and safety measures (#534)

• New TRLC type ScoreReq.RootCauseAssessment with root_causes, measures, safety, rationale and version. An assessment without measures argues that the root cause does not apply.

• Removed: ScoreReq.Mitigation, ScoreReq.SafetyMeasure, AoU.root_causes (and :root_causes: in .rst aou_req directives) and root causes in CompReq.derived_from.

• Every CompReq.derived_from entry needs a version: Package.Item@<version>.

• safety_analysis takes the assessment files in the new attribute assessments. safety_measures may only contain assumptions_of_use and component_requirements targets.

• assumptions_of_use and component_requirements targets no longer need the fault_trees target in deps.

• The traceability report has the levels "Assumptions of Use" and "Root Cause Assessments" instead of "Safety Measures". Custom LOBSTER templates must use {OWN_AOU_BLOCK} and {ASSESSMENT_BLOCK} instead of {SAFETYMEASURES_BLOCK}.

  # before
  safety_analysis(
      ...
      safety_measures = [
          "//docs:sample_aous",
          "sample_safety_analysis_safetymeasures.trlc",
      ],
  )
  
  # now
  safety_analysis(
      ...
      assessments = ["sample_safety_analysis_assessments.trlc"],
      safety_measures = ["//docs:sample_aous"],
  )

  ScoreReq.RootCauseAssessment ShmemCreatedWrongNameAssessed {
      root_causes = [sample_safety_analysis_fta.ShmemCreatedWrongName]
      measures = [SampleType.SampleAoU@1]
      safety = ScoreReq.Asil.B
      rationale = "The user prevents the wrong name through the assumption of use."
      version = 1
  }
  

rules_score: failure modes reference public API methods (#555)

• FailureMode.interface is a list of ScoreReq.ApiMethod records instead of a free-text string. The records are generated from the public_api class diagrams of an architectural_design: one per public method name (overloads collapsed) and one per free function.

• architectural_design has the new attribute package, the TRLC package of the generated records. It is required with public_api .puml diagrams and rejected without them.

• failure_modes must list the architectural_design in deps, and the failure mode files import its package.

• safety_analysis.arch_design is removed.

• The traceability level "Architecture" is replaced by "Public API". Custom LOBSTER templates must use {PUBLIC_API_SOURCES} instead of {ARCH_SOURCES}.

  # before
  architectural_design(
      name = "sample_seooc_design",
      public_api = ["public_api.puml"],
  )
  failure_modes(
      name = "sample_failure_modes",
      srcs = ["failure_modes.trlc"],
  )
  safety_analysis(
      ...
      arch_design = ":sample_seooc_design",
  )
  
  # now
  architectural_design(
      name = "sample_seooc_design",
      package = "sample_seooc_api",
      public_api = ["public_api.puml"],
  )
  failure_modes(
      name = "sample_failure_modes",
      srcs = ["failure_modes.trlc"],
      deps = [":sample_seooc_design"],
  )
  safety_analysis(
      ...
  )

  // before
  interface = "safety_software_seooc_example.SampleLibraryAPI.GetNumber"
  
  // now
  import sample_seooc_api
  ...
  interface = [sample_seooc_api.safety_software_seooc_example_SampleLibraryAPI_GetNumber]
  

rules_score: documentation is keyed by the full target label (#542)

• Pages and sources of units, components, unit designs, dependency modules, architectural designs and test-case coverage are keyed by <repo>/<package>/<name> (_main for the main repository) instead of the bare target name.
  • units/<label path>/index.rst, units/<label path>/<diagram>.puml, units/<label path>/<design>.rst.inc
  • components/<label path>/index.rst, components/<label path>/requirements/...
  • Page titles are the full label.
  • The HTML of a dependency module is merged to <repo>/<package>/<dep>/ instead of <dep>/. Links to published dependency pages change.
• Custom rules that consume the providers must adapt:
  • SphinxModuleInfo.transitive_modules and SphinxNeedsInfo.needs_modules are structs with path (the label path) instead of name.
  • UnitInfo.dependent_labels and ComponentInfo.dependent_labels are depsets of structs (unit_label, dependencies), one per unit, instead of depsets of labels (#533).

PlantUML: the provided-interface binding )- is removed (#544)

• Component )- Interface is rejected. Write the provided binding as -, -- or --(). Layout and style hints (-up-, --[bold]--) stay allowed.

  ' before
  Gateway )- ResponseApi
  
  ' now
  Gateway - ResponseApi

• A bare -- between a component and an interface is a provided binding and no longer an association.

Skills

• The SKILL.md files of rules-score, score-architecture, score-requirements, score-safety-analysis and score-testing changed. Downstream repositories must regenerate their sync_skills goldens.

Stricter validations

These changes need no new syntax, but input that built before can now fail.

TRLC requirement ASILs (#540)

• A FeatReq or CompReq must not have a lower ASIL than any requirement it is derived from. An upstream ASIL_B forbids QM, an upstream ASIL_D requires ASIL_D.
• trlc is raised from 3.0.1 to 3.1.1. Raise it if you pin an older version.

Root cause assessments (#534)

Errors in the safety_analysis build:

• A root cause is listed by more than one assessment.
• An assessment lists a root cause that no fault_trees target generates, or a measure that is not an own AoU or a CompReq of safety_measures.
• The safety of an assessment is below the ASIL of a failure mode of its root causes or above the ASIL of a listed measure.

Failures of the traceability report of the dependable_element:

• A root cause has no assessment.
• An own AoU is not listed as a measure of any assessment.

Certified scope (#533)

• unit.scope entries are resolved relative to the package of the unit and matched together with the repository: an exact target, :__pkg__ or :__subpackages__ in the same repository. A scope in another repository no longer matches by package path alone. Add the repository, for example @seooc//:sample_library.
• A component no longer implicitly certifies nested components. A unit implicitly certifies its own implementation.
• The message is Unit <unit label> depends on <dependency label>, but the dependency is not in any certified scope (<reason>).
• Violations warn with maturity = "development" and fail otherwise, so release builds can fail on dependencies the old check accepted.

Documentation names (#542)

• Basenames of design diagrams and images must be unique within a unit.
• design_name must be unique within its parent component (case-insensitive).

Public API diagrams (#555)

• The public_api diagrams of an architectural_design must be class diagrams.
• Public API classes must not declare conversion operators, new, delete or co_await. The parser fails with UnsupportedOperator.

$TransferInGate (#545)

• $TransferInGate(alias, connection) connects to the fault tree of the failure mode connection. The build fails when:
  • alias is not the fully qualified name of a failure mode (for example "Transfer1").
  • The target is unknown or ambiguous.
  • The transfers form a cycle, including a transfer to the own tree.
  • The gate alias collides with another node of the same diagram.
• Transfers across different fault_trees targets are not supported.
• A root cause inherited through a transfer is assessed once. The safety of its assessment must be at least the ASIL of all failure modes of all trees it belongs to.

New features

rules_score

• Failure-mode-to-API traceability (#555): the report traces failure modes to the public API methods in the "Public API" level. The safety analysis page shows one badge per guideword.
• Formal test specifications (#550): the new rule test_specification takes an RST file with a Test Goal, an optional Test Focus and at least one Test Step (optional Precondition, Action, Expected). A unit lists them in test_specs, a test refers to one with RecordProperty("test-spec", "//pkg:label"). The coverage lock gets a spec key per test case, which must not be mixed with Given/When/Then keys.
• Given/When/Then from test names (#505): a test named [<Prefix>_]Given<X>[_When<Y>]_(Expect|Then)<Z> does not need the given/when/then properties. This needs a lobster version with --derive-gwt-from-test-name. With lobster 1.0.6 only the properties are used. A test case in a coverage lock needs a Given and a Then. The When is optional.

PlantUML and validation

• Class template parameters (type, non-type, template-template, parameter packs, optional names) are modeled in PlantUML and compared with the C++ implementation by position, count, kind and pack marker. An omitted design name is unconstrained, an explicit name must match (#532).
• Partial and explicit specializations are matched to the design by their fully qualified base name. Their template arguments are not compared. Explicit instantiations are ignored (#532).

cr_checker

• C, C++, Rust and TRLC headers may use either // or /* */. The other form is derived from the template, and --fix keeps the form a file already uses (#554).

Bug fixes

• cr_checker: --modified-only honors inputs and :(exclude) pathspecs. Before, it checked all modified files. A leading YAML frontmatter block of a Markdown file is kept in front of the header, and --fix no longer breaks it (#546).
• rules_score: the architecture key conflict check of a dependable element works for elements in non-root packages and external repositories (#543).

Migration checklist

Breaking changes:

1. Replace Mitigation/SafetyMeasure records by RootCauseAssessment records and pass them through safety_analysis.assessments. Remove root_causes from AoUs and root causes from CompReq.derived_from. Add @<version> to every derived_from entry.
2. Add package to architectural_design targets with public_api, list them in the deps of failure_modes, remove arch_design from safety_analysis, and write FailureMode.interface as a list of ApiMethod records.
3. Update custom LOBSTER templates: {OWN_AOU_BLOCK} and {ASSESSMENT_BLOCK} replace {SAFETYMEASURES_BLOCK}, and {PUBLIC_API_SOURCES} replaces {ARCH_SOURCES}.
4. Adapt links to documentation paths (<repo>/<package>/<dep>/) and custom rules that read the changed provider fields.
5. Replace Component )- Interface by Component - Interface in PlantUML component diagrams.
6. Regenerate the sync_skills goldens.

Stricter validations:

7. Check the ASIL of every FeatReq and CompReq against its upstream requirements.
8. Give every root cause exactly one assessment and list every own AoU in an assessment.
9. Add the repository to unit.scope entries of external targets and build with maturity = "release".
10. Make design diagram and image basenames unique per unit and design_name unique per component.
11. Make sure public_api diagrams are class diagrams without unsupported operators.
12. Check $TransferInGate calls: use the fully qualified failure mode as alias and a failure mode of another tree as connection.