Skip to content

feat(rules_score): requirements from Sphinx-Needs, test cases back as needs - #575

Draft
antonkri wants to merge 7 commits into
mainfrom
feat/lobster-sphinx-needs
Draft

antonkri wants to merge 7 commits into
mainfrom
feat/lobster-sphinx-needs

Conversation

@antonkri

Copy link
Copy Markdown

Draft / prototype – used by eclipse-score/baselibs#799 together with eclipse-score/docs-as-code#1039.

Motivation

Requirements in S-CORE modules are written as Sphinx-Needs (docs-as-code). Today the requirement
macros of rules_score only accept TRLC, so a dependable_element cannot use them without
duplicating them in TRLC. This PR lets the dependable_element keep its validation and LOBSTER
traceability while taking requirements from needs.json, and hands the test results back to the
Sphinx-Needs documentation.

flowchart LR
  N["needs.json\n(docs_bundle / platform)"] -->|lobster_sphinx_needs| DE["dependable_element\n(validation + LOBSTER report)"]
  T["gtest + lobster-tracing"] --> DE
  DE -->|lobster_report_to_needs| J["<name>_needs.json\n(testcase Needs)"]
  J -->|"docs(dependable_elements)"| D["docs-as-code Sphinx build"]
Loading

Changes

Requirements from Sphinx-Needs (lobster_sphinx_needs) – counterpart of lobster-trlc

  • feature_requirements, component_requirements, assumed_system_requirements,
    assumptions_of_use accept needs = [...]: needs.json files or score_docs_as_code
    docs_bundle labels (mapped to their .__internal__.needs_local export). srcs is optional now;
    TRLC and needs can be combined.
  • One central conversion config lobster/config/lobster_sphinx_needs.yaml
    (stkh_req→AssumedSystemReq, feat_req→FeatReq, comp_req→CompReq with
    derived_from/covers as tracing targets, aou_req→AoU); each kind selects its type via
    --need-type. Tag req <id>@<version>, [version==N] link filters become @N, invalid needs
    are skipped, a plain RST list page is rendered.
  • feature_requirements(feat_id = ...) / component_requirements(comp_id = ...) are mandatory with
    needs: only needs whose satisfied_by link names that feature/component are converted, so a
    platform-wide needs.json can be passed as is. stkh_req/aou_req belong to the platform and are
    not filtered.

Test cases back to Sphinx-Needs (lobster_report_to_needs)

  • dependable_element provides <name>_needs.json: one testcase Need per test case of its LOBSTER
    report, with the ID scheme and fields of the score_docs_as_code test.xml parser
    (partially_verifies/fully_verifies, result, test_type, derivation_technique).
  • dependable_element(docs = False) skips the element's own Sphinx HTML documentation
    (<name>_doc, <name>.serve) when docs-as-code documents it.

Tests

  • test_lobster_sphinx_needs, test_lobster_report_to_needs (unit tests),
    test_requirements_needs_output + analysis tests (requirements_needs_test.bzl) on
    fixtures/sphinx_needs/needs.json, test_dependable_element_needs_json on an example element with
    docs = False.
  • build --nobuild //... in the test module, //:format.check, //:copyright.check.
  • baselibs#799: feat_id/comp_id select 15 feature / 6 component requirements; 43 test cases exported.

Open points

  • The dependable element chain is testonly (components are test rules), so a docs build importing
    <name>_needs.json becomes testonly as well.
  • Architecture items, validation result and integrity level are not exported to Sphinx-Needs yet.
  • lobster-gtest only knows lobster-tracing; full/partial verification is taken from the test
    description (:Fullyverifies: / :Partiallyverifies:), otherwise partially_verifies.

Counterpart of lobster-trlc for requirements written as Sphinx-Needs
directives. The requirement macros (assumed_system_requirements,
feature_requirements, component_requirements, assumptions_of_use) accept
`needs` (score_docs_as_code docs_bundle targets or needs.json files) in
addition to or instead of TRLC `srcs`. lobster_sphinx_needs converts the
needs into the same LOBSTER requirement items (kind CompReq/FeatReq/
AssumedSystemReq/AoU, tag `req <need id>@<version>`, link fields as
tracing targets, `[version==N]` -> `@N`), so component,
dependable_element and the reports are unchanged. Needs with status
invalid are skipped; a plain RST page lists the converted needs.
lobster_sphinx_needs uses one central conversion configuration for all
requirement kinds; each kind selects its need type via --need-type.
needs_lobster_config and the id-pattern option are removed.

feature_requirements(feat_id) and component_requirements(comp_id) are
mandatory with needs: only needs whose satisfied_by link names that
feature/component are converted (--satisfied-by), so a platform-wide
needs.json can be passed as is. stkh_req and aou_req belong to the
platform and are not filtered.

Signed-off-by: Anton Krivoborodov <[email protected]>
lobster_report_to_needs converts the test cases (activity items) of a
dependable element's LOBSTER report into Sphinx-Needs testcase Needs,
using the ID scheme and fields of the score_docs_as_code test.xml parser.
dependable_element provides them as <name>_needs.json, consumed by
score_docs_as_code's docs(dependable_elements = [...]).

docs = False skips the element's own Sphinx HTML documentation
(<name>_doc, <name>.serve) when another Sphinx build documents it.

Signed-off-by: Anton Krivoborodov <[email protected]>
@github-actions

Copy link
Copy Markdown

Coverage Report

Coverage report was generated.

Full report can be downloaded from the CI artifacts (expand Artifacts at the bottom of the run).

Overall coverage rate:

lines......: 91.0%
functions......: 61.4%

The index of a dependable element depended on //third_party/docs_runtime:dot
unconditionally, so building it fetched the docs_runtime apt sysroot from
snapshot.ubuntu.com even when no Sphinx documentation is built. Graphviz is
now only wired in with docs = True; lobster_rst_report falls back to its
text note without it.

Signed-off-by: Anton Krivoborodov <[email protected]>
@github-actions

Copy link
Copy Markdown

Coverage Report

Coverage report was generated.

Full report can be downloaded from the CI artifacts (expand Artifacts at the bottom of the run).

Overall coverage rate:

lines......: 91.0%
functions......: 61.4%

failure_modes(needs = ...) turns the comp_saf_fmea needs of a
score_docs_as_code FMEA into generated FailureMode records (named by the
need ID, interface resolved via violated real_arc_int_op needs), so fault
trees reference them unchanged. Without TRLC assessments, safety_analysis
derives one assessment per sufficient FMEA need from its root causes and
mitigated_by measures.

The Sphinx-Needs tests move into fixture packages to keep test/BUILD
below the 100 KB pre-commit limit.
@github-actions

Copy link
Copy Markdown

Coverage Report

Coverage report was generated.

Full report can be downloaded from the CI artifacts (expand Artifacts at the bottom of the run).

Overall coverage rate:

lines......: 91.0%
functions......: 61.4%

@github-actions

Copy link
Copy Markdown

Coverage Report

Coverage report was generated.

Full report can be downloaded from the CI artifacts (expand Artifacts at the bottom of the run).

Overall coverage rate:

lines......: 91.0%
functions......: 61.4%

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant