From 6e107c3a7270ba366cc4db4a462c6b987f1b56a1 Mon Sep 17 00:00:00 2001 From: vishwajitdandage Date: Mon, 15 Jun 2026 13:42:04 +0530 Subject: [PATCH 1/3] feat(rules_score): add glossary support and example in SEOOC --- bazel/rules/rules_score/examples/seooc/BUILD | 1 + .../examples/seooc/design/arch_design.rst | 4 + .../rules_score/examples/seooc/docs/BUILD | 8 ++ .../examples/seooc/docs/glossary.rst | 19 +++++ .../assumed_system_requirements.trlc | 2 +- .../requirements/feature_requirements.trlc | 2 +- .../private/dependable_element.bzl | 10 +++ bazel/rules/rules_score/private/glossary.bzl | 83 +++++++++++++++++++ bazel/rules/rules_score/rules_score.bzl | 5 ++ .../dependable_element_index.template.rst | 9 ++ 10 files changed, 141 insertions(+), 2 deletions(-) create mode 100644 bazel/rules/rules_score/examples/seooc/docs/glossary.rst create mode 100644 bazel/rules/rules_score/private/glossary.bzl diff --git a/bazel/rules/rules_score/examples/seooc/BUILD b/bazel/rules/rules_score/examples/seooc/BUILD index e0ef69cb..3115cac7 100644 --- a/bazel/rules/rules_score/examples/seooc/BUILD +++ b/bazel/rules/rules_score/examples/seooc/BUILD @@ -55,6 +55,7 @@ dependable_element( dependability_analysis = [ ":sample_dependability_analysis", ], + glossary = ["//bazel/rules/rules_score/examples/seooc/docs:glossary"], integrity_level = "B", requirements = [ "//bazel/rules/rules_score/examples/seooc/docs/requirements:feature_requirements", diff --git a/bazel/rules/rules_score/examples/seooc/design/arch_design.rst b/bazel/rules/rules_score/examples/seooc/design/arch_design.rst index fe43befd..087f1d2a 100644 --- a/bazel/rules/rules_score/examples/seooc/design/arch_design.rst +++ b/bazel/rules/rules_score/examples/seooc/design/arch_design.rst @@ -17,6 +17,10 @@ Architectural Design This is the architectural design of the Safety Software SEooC Example: +The :term:`Architectural Design` describes how each :term:`Component` +contributes to fulfilling :term:`Feature Requirements` under the selected +:term:`Integrity Level`. + Static Architecture ------------------- diff --git a/bazel/rules/rules_score/examples/seooc/docs/BUILD b/bazel/rules/rules_score/examples/seooc/docs/BUILD index e2d391f4..812ffc5a 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/BUILD +++ b/bazel/rules/rules_score/examples/seooc/docs/BUILD @@ -11,6 +11,7 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* load("@trlc//:trlc.bzl", "trlc_requirements", "trlc_requirements_test") +load("//bazel/rules/rules_score:rules_score.bzl", "glossary") trlc_requirements( name = "aous", @@ -30,3 +31,10 @@ trlc_requirements_test( ], visibility = ["//visibility:public"], ) + +glossary( + name = "glossary", + srcs = ["glossary.rst"], + tags = ["manual"], + visibility = ["//visibility:public"], +) diff --git a/bazel/rules/rules_score/examples/seooc/docs/glossary.rst b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst new file mode 100644 index 00000000..93ba7161 --- /dev/null +++ b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst @@ -0,0 +1,19 @@ +Glossary +======== + +.. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating the level of safety rigor and + confidence required. D is the highest, QM is for non-safety components. + + feature requirements + High-level functional requirements describing what the safety element must do. + + architectural design + The structural design description of the SEooC, including components, + interfaces, and their interactions needed to realize the requirements. + + component + A software unit with defined responsibilities and interfaces, allocated + requirements, and associated implementation and verification evidence. diff --git a/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc b/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc index f6bf9ef0..08ca9c9a 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc +++ b/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc @@ -20,7 +20,7 @@ import ScoreReq /////////////////////////////// ScoreReq.AssumedSystemReq ASR_SAMPLE_001 { - description = "The system shall provide safe and reliable numeric value management through encapsulated classes" + description = "The system shall provide safe and reliable numeric value management through encapsulated classes, compliant with the selected :term:`integrity level`." safety = ScoreReq.Asil.B version = 1 rationale = "System-level requirement for managing numeric values in a safety-critical context" diff --git a/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc b/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc index 1123a0cf..e0489002 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc +++ b/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc @@ -20,7 +20,7 @@ import ScoreReq /////////////////////////////// ScoreReq.FeatReq FEAT_001 { - description = "The component shall provide a numeric value management interface that returns a `uint8_t` value on every read access" + description = "The :term:`component` shall provide a numeric value management interface that returns a `uint8_t` value on every read access, aligned with the :term:`feature requirements`." safety = ScoreReq.Asil.B derived_from = [SampleSEooC.ASR_SAMPLE_001@1] version = 1 diff --git a/bazel/rules/rules_score/private/dependable_element.bzl b/bazel/rules/rules_score/private/dependable_element.bzl index e0e77aea..a9f69be2 100644 --- a/bazel/rules/rules_score/private/dependable_element.bzl +++ b/bazel/rules/rules_score/private/dependable_element.bzl @@ -708,6 +708,7 @@ def _dependable_element_index_impl(ctx): "architectural_design", "dependability_analysis", "checklists", + "glossary", ] artifacts_by_type = {} @@ -823,6 +824,7 @@ def _dependable_element_index_impl(ctx): "{architectural_design}": "\n ".join(artifacts_by_type["architectural_design"]), "{dependability_analysis}": "\n ".join(artifacts_by_type["dependability_analysis"]), "{checklists}": "\n ".join(artifacts_by_type["checklists"]), + "{glossary}": "\n ".join(artifacts_by_type["glossary"]), "{submodules}": deps_links, "{traceability_report}": traceability_report, }, @@ -1102,6 +1104,10 @@ _dependable_element_index = rule( default = [], doc = "Safety checklists targets or files.", ), + "glossary": attr.label_list( + default = [], + doc = "Glossary targets or files defining terminology and definitions.", + ), "template": attr.label( allow_single_file = [".rst"], mandatory = True, @@ -1254,6 +1260,7 @@ def dependable_element( tests, integrity_level, checklists = [], + glossary = [], deps = [], maturity = "release", sphinx = Label("//bazel/rules/rules_score:score_build"), @@ -1289,6 +1296,8 @@ def dependable_element( depend on elements with a lower integrity level than its own. checklists: Optional list of labels to .rst or .md files containing safety checklists and verification documents. + glossary: Optional list of labels to .rst files containing + terminology and definitions for the dependable element. deps: Optional list of other module targets this element depends on. Cross-references will work automatically. sphinx: Label to sphinx build binary. Default: //bazel/rules/rules_score:score_build @@ -1317,6 +1326,7 @@ def dependable_element( architectural_design = architectural_design, dependability_analysis = dependability_analysis, checklists = checklists, + glossary = glossary, tests = tests, deps = deps, processed_deps = processed_deps, diff --git a/bazel/rules/rules_score/private/glossary.bzl b/bazel/rules/rules_score/private/glossary.bzl new file mode 100644 index 00000000..189bedd3 --- /dev/null +++ b/bazel/rules/rules_score/private/glossary.bzl @@ -0,0 +1,83 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +""" +Glossary build rule for S-CORE projects. + +This rule accepts glossary sources as ``.rst`` files and publishes them +through ``SphinxSourcesInfo`` for the ``dependable_element`` documentation +assembly pipeline. +""" + +load("//bazel/rules/rules_score:providers.bzl", "SphinxSourcesInfo") + +# ============================================================================ +# Private Rule Implementation +# ============================================================================ + +def _glossary_impl(ctx): + """Implementation for ``glossary`` rule. + + Args: + ctx: Rule context. + + Returns: + List of providers including: + - ``DefaultInfo`` with glossary source files + - ``SphinxSourcesInfo`` where ``srcs == deps`` (leaf rule) + """ + + source_files = depset(ctx.files.srcs) + + return [ + DefaultInfo(files = source_files), + SphinxSourcesInfo( + srcs = source_files, + deps = source_files, + ), + ] + +# ============================================================================ +# Rule Definition +# ============================================================================ + +_glossary = rule( + implementation = _glossary_impl, + doc = "Collect glossary documentation files and expose them to Sphinx.", + attrs = { + "srcs": attr.label_list( + allow_files = [".rst"], + mandatory = True, + doc = "Glossary source files (``.rst``).", + ), + }, +) + +# ============================================================================ +# Public Macro +# ============================================================================ + +def glossary(name, srcs, **kwargs): + """Define a glossary artifact for documentation assembly. + + Args: + name: Target name. + srcs: List of glossary source files (.rst). + visibility: Bazel visibility specification. + """ + + _glossary( + name = name, + srcs = srcs, + **kwargs + ) diff --git a/bazel/rules/rules_score/rules_score.bzl b/bazel/rules/rules_score/rules_score.bzl index 3df157f7..f2e5bb3e 100644 --- a/bazel/rules/rules_score/rules_score.bzl +++ b/bazel/rules/rules_score/rules_score.bzl @@ -49,6 +49,10 @@ load( "//bazel/rules/rules_score/private:feature_requirements.bzl", _feature_requirements = "feature_requirements", ) +load( + "//bazel/rules/rules_score/private:glossary.bzl", + _glossary = "glossary", +) load( "//bazel/rules/rules_score/private:filter_execpath.bzl", _filter_execpath = "filter_execpath", @@ -76,6 +80,7 @@ assumed_system_requirements = _assumed_system_requirements component_requirements = _component_requirements dependability_analysis = _dependability_analysis feature_requirements = _feature_requirements +glossary = _glossary filter_execpath = _filter_execpath fmea = _fmea sphinx_module = _sphinx_module diff --git a/bazel/rules/rules_score/templates/dependable_element_index.template.rst b/bazel/rules/rules_score/templates/dependable_element_index.template.rst index c6f55054..764b52f0 100644 --- a/bazel/rules/rules_score/templates/dependable_element_index.template.rst +++ b/bazel/rules/rules_score/templates/dependable_element_index.template.rst @@ -78,6 +78,15 @@ Checklists {checklists} +Glossary +-------- + +.. toctree:: + :maxdepth: 2 + :caption: Glossary + + {glossary} + Submodules ---------- This module includes the following submodules: From bc5d5fbab7a1dee6770b1bc31ca804f0159042bc Mon Sep 17 00:00:00 2001 From: vishwajitdandage Date: Wed, 17 Jun 2026 16:28:57 +0530 Subject: [PATCH 2/3] Add copyright notice and licensing information to glossary.rst --- bazel/rules/rules_score/README.md | 53 +++++++++++++++++++ .../rules/rules_score/docs/rule_reference.rst | 53 +++++++++++++++++++ .../examples/seooc/docs/glossary.rst | 14 +++++ bazel/rules/rules_score/rules_score.bzl | 8 +-- 4 files changed, 124 insertions(+), 4 deletions(-) diff --git a/bazel/rules/rules_score/README.md b/bazel/rules/rules_score/README.md index 5546d0c2..a4fc0092 100644 --- a/bazel/rules/rules_score/README.md +++ b/bazel/rules/rules_score/README.md @@ -29,6 +29,7 @@ for safety related automotive software. | `unit` | `UnitInfo`, `CertifiedScope` | | `component` | `ComponentInfo` | | `fmea` | `AnalysisInfo` | +| `glossary` | `SphinxSourcesInfo` | | `dependability_analysis` | `DependabilityAnalysisInfo` | | `dependable_element` | HTML documentation zip (Sphinx) | @@ -152,6 +153,57 @@ by the wrapping `dependability_analysis` test. --- +## `glossary` + +```starlark +glossary( + name = "project_glossary", + srcs = ["docs/glossary.rst"], +) +``` + +**`bazel build`** — collects glossary `.rst` sources and publishes them +through `SphinxSourcesInfo` so `dependable_element` can include terminology +sections in generated HTML documentation. + +Example glossary source (`.rst`): + +```rst +Glossary +======== + +.. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating required safety rigor. + + component + Software unit with defined interfaces, implementation, and tests. +``` + +Example term usage in requirements (`.trlc`): + +```trlc +ScoreReq.FeatReq FEAT_001 { + description = "The :term:`component` shall satisfy all :term:`feature requirements` assigned to integrity level B." + safety = ScoreReq.Asil.B + derived_from = [MyPkg.ASR_001@1] + version = 1 +} +``` + +Typical usage is to pass glossary targets into `dependable_element`: + +```starlark +dependable_element( + name = "my_seooc", + # ... + glossary = [":project_glossary"], +) +``` + +--- + ## `dependability_analysis` ```starlark @@ -187,6 +239,7 @@ dependable_element( architectural_design = [":my_design"], dependability_analysis = [":my_da"], components = [":my_component"], + glossary = [":project_glossary"], assumptions_of_use = [], tests = [], ) diff --git a/bazel/rules/rules_score/docs/rule_reference.rst b/bazel/rules/rules_score/docs/rule_reference.rst index ceca4bf1..9bc8dc81 100644 --- a/bazel/rules/rules_score/docs/rule_reference.rst +++ b/bazel/rules/rules_score/docs/rule_reference.rst @@ -254,6 +254,59 @@ Conditions that the *integrating project* must fulfil when using this SEooC. **Generated targets:** ```` (documentation), ``_test`` (TRLC validation) +.. _rule-glossary: + +glossary +~~~~~~~~ + +Collects glossary pages for Sphinx and forwards them to downstream +documentation assembly (for example through ``dependable_element``). + +.. code-block:: python + + glossary( + name = "project_glossary", + srcs = ["docs/glossary.rst"], + ) + +Example glossary source (``.rst``): + +.. code-block:: rst + + Glossary + ======== + + .. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating required safety rigor. + + component + Software unit with defined interfaces, implementation, and tests. + +.. list-table:: + :header-rows: 1 + :widths: 18 12 10 60 + + * - Attribute + - Type + - Required + - Description + * - ``name`` + - string + - yes + - Target name + * - ``srcs`` + - label list + - yes + - ``.rst`` files containing glossary definitions + * - ``visibility`` + - — + - no + - Bazel visibility + +**Generated targets:** ```` (documentation; no standalone test) + .. _rule-arch-design: .. _rule-architectural-design: diff --git a/bazel/rules/rules_score/examples/seooc/docs/glossary.rst b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst index 93ba7161..fbe9f734 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/glossary.rst +++ b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst @@ -1,3 +1,17 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + Glossary ======== diff --git a/bazel/rules/rules_score/rules_score.bzl b/bazel/rules/rules_score/rules_score.bzl index f2e5bb3e..9a6cb8e8 100644 --- a/bazel/rules/rules_score/rules_score.bzl +++ b/bazel/rules/rules_score/rules_score.bzl @@ -49,10 +49,6 @@ load( "//bazel/rules/rules_score/private:feature_requirements.bzl", _feature_requirements = "feature_requirements", ) -load( - "//bazel/rules/rules_score/private:glossary.bzl", - _glossary = "glossary", -) load( "//bazel/rules/rules_score/private:filter_execpath.bzl", _filter_execpath = "filter_execpath", @@ -61,6 +57,10 @@ load( "//bazel/rules/rules_score/private:fmea.bzl", _fmea = "fmea", ) +load( + "//bazel/rules/rules_score/private:glossary.bzl", + _glossary = "glossary", +) load( "//bazel/rules/rules_score/private:sphinx_module.bzl", _sphinx_module = "sphinx_module", From d3a91246b61eeeadba1d13f8d63ee404b2710e55 Mon Sep 17 00:00:00 2001 From: vishwajitdandage Date: Fri, 19 Jun 2026 10:24:11 +0530 Subject: [PATCH 3/3] [rules score] add aux_srcs to SphinxSourcesInfo in glossary implementation --- bazel/rules/rules_score/examples/seooc/docs/BUILD | 1 - bazel/rules/rules_score/private/glossary.bzl | 1 + .../templates/dependable_element_index.template.rst | 3 --- 3 files changed, 1 insertion(+), 4 deletions(-) diff --git a/bazel/rules/rules_score/examples/seooc/docs/BUILD b/bazel/rules/rules_score/examples/seooc/docs/BUILD index 812ffc5a..442a643b 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/BUILD +++ b/bazel/rules/rules_score/examples/seooc/docs/BUILD @@ -35,6 +35,5 @@ trlc_requirements_test( glossary( name = "glossary", srcs = ["glossary.rst"], - tags = ["manual"], visibility = ["//visibility:public"], ) diff --git a/bazel/rules/rules_score/private/glossary.bzl b/bazel/rules/rules_score/private/glossary.bzl index 189bedd3..fce1a480 100644 --- a/bazel/rules/rules_score/private/glossary.bzl +++ b/bazel/rules/rules_score/private/glossary.bzl @@ -44,6 +44,7 @@ def _glossary_impl(ctx): SphinxSourcesInfo( srcs = source_files, deps = source_files, + aux_srcs = depset(), ), ] diff --git a/bazel/rules/rules_score/templates/dependable_element_index.template.rst b/bazel/rules/rules_score/templates/dependable_element_index.template.rst index 764b52f0..f58ae14f 100644 --- a/bazel/rules/rules_score/templates/dependable_element_index.template.rst +++ b/bazel/rules/rules_score/templates/dependable_element_index.template.rst @@ -78,9 +78,6 @@ Checklists {checklists} -Glossary --------- - .. toctree:: :maxdepth: 2 :caption: Glossary