diff --git a/bazel/rules/rules_score/docs/index.rst b/bazel/rules/rules_score/docs/index.rst index 41ba117a..2b05a94b 100644 --- a/bazel/rules/rules_score/docs/index.rst +++ b/bazel/rules/rules_score/docs/index.rst @@ -16,7 +16,7 @@ Rules SCORE for Bazel ===================== .. include:: overview.rst - :start-line: 14 + :start-line: 16 .. toctree:: :maxdepth: 2 diff --git a/bazel/rules/rules_score/docs/overview.rst b/bazel/rules/rules_score/docs/overview.rst index 15cd48ff..6c702222 100644 --- a/bazel/rules/rules_score/docs/overview.rst +++ b/bazel/rules/rules_score/docs/overview.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +:orphan: + Overview ======== diff --git a/bazel/rules/rules_score/docs/user_guide/requirements.rst b/bazel/rules/rules_score/docs/user_guide/requirements.rst index de884aa3..287b2a79 100644 --- a/bazel/rules/rules_score/docs/user_guide/requirements.rst +++ b/bazel/rules/rules_score/docs/user_guide/requirements.rst @@ -144,6 +144,8 @@ type defined in the For ``TRLC`` both a VSCode Extension and a LSP Server (e.g. for Clion) are `available `_ +.. _Assumed System Requirements: + Assumed System Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/bazel/rules/rules_score/docs/user_guide/tutorial/build.rst b/bazel/rules/rules_score/docs/user_guide/tutorial/build.rst index 7f0ee60c..23191417 100644 --- a/bazel/rules/rules_score/docs/user_guide/tutorial/build.rst +++ b/bazel/rules/rules_score/docs/user_guide/tutorial/build.rst @@ -33,8 +33,24 @@ Run the build from within the ``examples/minimal/`` standalone module: cd bazel/rules/rules_score/examples/minimal bazel build //:my_element +``bazel build //:my_element`` compiles the Sphinx documentation for the +``dependable_element`` together with its LOBSTER traceability report — the +report is rendered as part of the same documentation build. + Expected output files: .. code-block:: text - bazel-bin/my_element_doc/html/ ← Sphinx HTML documentation + bazel-bin/my_element_doc/html/ ← Sphinx HTML documentation + +Running Validations +-------------------- + +All validations — TRLC requirement checks, unit/component/dependable-element +tests, and the traceability completeness gate — are exposed as Bazel tests and +run with a single command: + +.. code-block:: bash + + cd bazel/rules/rules_score/examples/minimal + bazel test //... diff --git a/bazel/rules/rules_score/docs/user_guide/tutorial/index.rst b/bazel/rules/rules_score/docs/user_guide/tutorial/index.rst index 2339c18e..025d9f28 100644 --- a/bazel/rules/rules_score/docs/user_guide/tutorial/index.rst +++ b/bazel/rules/rules_score/docs/user_guide/tutorial/index.rst @@ -26,8 +26,7 @@ from the standalone module at By the end you will have a fully validated SEooC with requirements, a static architecture diagram, a unit design, and a passing build. -Workflow --------- +**Workflow:** The tutorial follows the S-CORE development flow top-down: specify *what* the element must do, design *how* it is structured, implement and verify it, and let @@ -35,18 +34,20 @@ the build check that every artefact stays consistent. :: - Step 1 Step 2 Step 3 Step 4 Step 5 - Requirements → SW Architectural → Unit Design → Validation → Build - Design - ─────────── ─────────────── ─────────── ────────── ───────── - AssumedSystemReq static diagram class/sequence unit & bazel build - FeatReq (components + units) diagram per component (runs every - CompReq → Bazel targets unit → code tests + consistency - (.trlc records) modelled after it it validates lobster- check) - against tracing + Step 0 Step 1 Step 2 Step 3 Step 4 Step 5 + Setup → Requirements → SW Architectural → Unit Design → Validation → Build + Design + ─────── ─────────── ─────────────── ─────────── ────────── ───────── + dependable AssumedSystemReq static diagram class/sequence unit & bazel build + _element FeatReq (components + units) diagram per component (runs every + target CompReq → Bazel targets unit → code tests + consistency + (.trlc records) modelled after it it validates lobster- check) + against tracing Each step builds on the previous one, and each has an automatic check: +0. **Setup** — declare the empty ``dependable_element`` target that later steps + fill in. → :doc:`setup` 1. **Requirements** — write ``AssumedSystemReq`` / ``FeatReq`` / ``CompReq`` TRLC records and wire their Bazel targets. Traceability is type-checked by ``trlc --verify``. → :doc:`requirements` @@ -68,8 +69,10 @@ Each step builds on the previous one, and each has an automatic check: ``bazel build //:my_element``. .. toctree:: - :maxdepth: 1 + :hidden: + :maxdepth: 2 + setup requirements architecture unit_design diff --git a/bazel/rules/rules_score/docs/user_guide/tutorial/setup.rst b/bazel/rules/rules_score/docs/user_guide/tutorial/setup.rst new file mode 100644 index 00000000..5ddf22bc --- /dev/null +++ b/bazel/rules/rules_score/docs/user_guide/tutorial/setup.rst @@ -0,0 +1,43 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Step 0 — Setup +=============== + +Before adding any content, declare the ``dependable_element`` target itself. All +other steps in this tutorial fill in the fields left empty here. + +BUILD +------ + +.. code-block:: starlark + + load( + "@score_tooling//bazel/rules/rules_score:rules_score.bzl", + "dependable_element", + ) + + dependable_element( + name = "my_element", + integrity_level = "B", + requirements = [], + assumptions_of_use = [], + architectural_design = [], + components = [], + dependability_analysis = [], + tests = [], + maturity = "development", + ) + +→ Next: :doc:`requirements` diff --git a/bazel/rules/rules_score/docs/user_guide/tutorial/validation.rst b/bazel/rules/rules_score/docs/user_guide/tutorial/validation.rst index 7c2fee24..3af39267 100644 --- a/bazel/rules/rules_score/docs/user_guide/tutorial/validation.rst +++ b/bazel/rules/rules_score/docs/user_guide/tutorial/validation.rst @@ -73,4 +73,4 @@ Run the tests with: bazel test //:my_unit_test -→ Full guide: :doc:`../validation.rst` +→ Full guide: :doc:`../validation` diff --git a/plantuml/sphinx/clickable_plantuml/README.md b/plantuml/sphinx/clickable_plantuml/README.md index 9203648c..51f15dc8 100644 --- a/plantuml/sphinx/clickable_plantuml/README.md +++ b/plantuml/sphinx/clickable_plantuml/README.md @@ -232,18 +232,18 @@ Rather than duplicating a hand-written, untested example here, this exact scenario is built and regression-tested as part of `rules_score`'s own test suite: -- [`overview.puml`](../../../bazel/rules/rules_score/test/fixtures/clickable_example/overview.puml) +- [`overview.puml`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/fixtures/clickable_example/overview.puml) references `Proxy` (a top-level leaf, per the *Role detection algorithm* above). -- [`proxy_detail.puml`](../../../bazel/rules/rules_score/test/fixtures/clickable_example/proxy_detail.puml) +- [`proxy_detail.puml`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/fixtures/clickable_example/proxy_detail.puml) defines `Proxy` as a `package` with a nested child, making it a *define*. Both files are wired into a real `architectural_design()` + `dependable_element()` target -(`clickable_example_lib` in [`bazel/rules/rules_score/test/BUILD`](../../../bazel/rules/rules_score/test/BUILD)), +(`clickable_example_lib` in [`bazel/rules/rules_score/test/BUILD`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/BUILD)), so every change to the parser, `puml_idmap`, or this extension is checked against genuinely Bazel-built `.idmap.json` artifacts — not just prose. The -[`clickable_example_link_rendered_test`](../../../bazel/rules/rules_score/test/check_clickable_example_link.sh) +[`clickable_example_link_rendered_test`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/check_clickable_example_link.sh) `sh_test` asserts that: - `overview.idmap.json` references `Proxy` @@ -267,7 +267,7 @@ detection algorithm* above: `package_a.InternalInterface`, since ids are rooted at the enclosing `package_a` package rather than the `@startuml` name. See `interface_example_lib` and `interface_example_link_rendered_test` in - [`bazel/rules/rules_score/test/BUILD`](../../../bazel/rules/rules_score/test/BUILD). + [`bazel/rules/rules_score/test/BUILD`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/BUILD). - **Pure class-diagram linking** — `class_overview.puml` references `AuditTrail` as a bare, member-less class, and `class_detail.puml` defines it (it has a method, making it the elaboration site). See @@ -285,7 +285,7 @@ matching definition in another — and are wired up the same way: FMEA/safety-analysis traceability) defines it. Both share the FQN `package_pub.PublicInterface`. See `public_api_example_lib` and `public_api_example_link_rendered_test` in - [`bazel/rules/rules_score/test/BUILD`](../../../bazel/rules/rules_score/test/BUILD). + [`bazel/rules/rules_score/test/BUILD`](https://github.com/eclipse-score/tooling/blob/main/bazel/rules/rules_score/test/BUILD). - **Static architecture unit links to its class diagram** — `unit_overview.puml` (a component diagram) shows `unit_one` as a leaf unit (no children, so a reference), and `unit_class_detail.puml` (a class diff --git a/validation/core/docs/specifications/class_design_sequence.md b/validation/core/docs/specifications/class_design_sequence.md index 398bbf76..8d501b76 100644 --- a/validation/core/docs/specifications/class_design_sequence.md +++ b/validation/core/docs/specifications/class_design_sequence.md @@ -11,6 +11,10 @@ SPDX-License-Identifier: Apache-2.0 ----------------------------------------------------------------------------- --> +--- +orphan: true +--- + # Class Design Sequence Specification ## Purpose