Rule Reference

Documentation Rules

sphinx_module

Builds Sphinx-based HTML documentation from RST/MD source files. Supports cross-module dependencies and automatic HTML merging.

sphinx_module(
    name  = "my_docs",
    srcs  = glob(["docs/**/*.rst", "docs/**/*.md"]),
    index = "docs/index.rst",
    deps  = ["@external_module//:docs"],
)

Attribute	Type	Required	Description
name	string	yes	Target name; also the output directory prefix
srcs	label list	yes	RST, MD, image, and PlantUML source files
index	label	yes	Path to the root index.rst
deps	label list	no	Other sphinx_module or dependable_element targets for cross-referencing and HTML merging (default [])
testonly	bool	no	If True, only testonly targets may depend on this (default False)
visibility	—	no	Bazel visibility

Generated targets:

• <name> — HTML output under bazel-bin/<name>/html/; use in deps of other sphinx_module targets.

• <name>_needs — needs.json produced by the needs builder; consumed transitively by downstream modules for cross-module {requirement:downstream-ref} resolution. See Two-phase Sphinx build for the full data-flow description.

filter_execpath

Advanced. Resolves a Sphinx -D command-line argument (such as a Doxygen build output path) from a Bazel target’s outputs at analysis time, producing a fully-qualified string that can be passed to sphinx_module.extra_opts_targets. This is needed when a Sphinx extension (e.g. Breathe for Doxygen integration) requires a path that is only known once the dependency has been built.

filter_execpath(
    name           = "breathe_project_path",
    flag           = "-Dbreathe_projects.MyLib",
    target         = "//doc:doxygen_build",
    filter_pattern = "xml/index.xml",
)

sphinx_module(
    name               = "my_docs",
    srcs               = glob(["docs/**/*.rst"]),
    index              = "docs/index.rst",
    extra_opts_targets = [":breathe_project_path"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
flag	string	yes	The Sphinx -D flag name (e.g. "-Dbreathe_projects.MyLib")
target	label	yes	Bazel target whose output files are searched
filter_pattern	string	yes	Substring used to identify the relevant output file within target’s outputs

Provides: FilteredExecpathInfo — carries flag, resolved_path, and the combined arg string (flag=resolved_path). Consumed via sphinx_module.extra_opts_targets.

Artifact Rules

All artifact rules produce a SphinxSourcesInfo provider (documentation page) and carry typed traceability information for downstream structural rules.

assumed_system_requirements

System-level requirements that the SEooC receives from its operational context. These are too broad to be assigned to a single component.

assumed_system_requirements(
    name = "sys_req",
    srcs = ["docs/assumed_system_requirements.trlc"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.trlc files containing AssumedSystemReq records
deps	label list	no	Reserved for consistency; unused at root level (default [])
image_srcs	label list	no	Image/diagram files (.svg, .png, or .puml) referenced from description fields via .. image::/.. uml:: — see Adding Images and Diagrams to Requirement Descriptions (default [])
visibility	—	no	Bazel visibility (default ["//visibility:public"])

Generated targets: <name> (documentation), <name>_test (TRLC syntax/type validation)

feature_requirements

High-level requirements derived from AssumedSystemReq. Operate at the integration level; can only be satisfied by multiple components working together.

feature_requirements(
    name = "features",
    srcs = ["docs/features.trlc"],
    deps = [":sys_req"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.trlc files containing FeatReq records
deps	label list	no	assumed_system_requirements targets for derived_from cross-reference resolution (default [])
image_srcs	label list	no	Image/diagram files (.svg, .png, or .puml) referenced from description fields via .. image::/.. uml:: — see Adding Images and Diagrams to Requirement Descriptions (default [])
visibility	—	no	Bazel visibility (default ["//visibility:public"])

Generated targets: <name> (documentation), <name>_test (TRLC validation including cross-reference checks)

component_requirements

Requirements assigned to exactly one component; directly implementable and testable within that component.

component_requirements(
    name = "comp_req",
    srcs = ["docs/requirements.trlc"],
    deps = [":features"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.trlc files containing CompReq records
deps	label list	no	feature_requirements or assumed_system_requirements targets for derived_from resolution. Also list the assumptions_of_use target of a received AoU and the fault_trees target of referenced <fta_package>.<RootCause> records (default [])
image_srcs	label list	no	Image/diagram files (.svg, .png, or .puml) referenced from description fields via .. image::/.. uml:: — see Adding Images and Diagrams to Requirement Descriptions (default [])
visibility	—	no	Bazel visibility (default ["//visibility:public"])

Generated targets: <name> (documentation), <name>_test (TRLC validation)

A CompReq record’s derived_from field (CompReqSourceId) may also reference an AoU received from another dependable element, alongside its usual FeatReq/AssumedSystemReq references (e.g. [SampleType.SampleAoU@1]). The element’s own AoUs are never a derived_from source. This requires importing the AoU’s package and listing the assumptions_of_use target that defines it directly in this target’s deps — see Assumptions of Use.

assumptions_of_use

Conditions that the integrating project must fulfil when using this SEooC.

assumptions_of_use(
    name = "aous",
    srcs = ["docs/assumptions.trlc"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.trlc files (containing AoU records), .rst files, or labels to existing TrlcProviderInfo-providing targets. Every aou_req directive of an .rst source needs :root_causes: <fta_package>.<RootCause>, ...; a missing or unqualified value fails the conversion
deps	label list	no	Other requirement targets (TrlcProviderInfo) needed for cross-reference parsing (default []). List the fault_trees target: every AoU references the generated <fta_package>.<RootCause> records it addresses (root_causes, mandatory). Other assumptions_of_use targets are rejected here, as their AoUs would be extracted as own AoUs.
ref_package	string	no	TRLC package prefix used for derived_from cross-references when converting RST sources (default None)
lobster_config	label	no	Advanced: override the Lobster YAML configuration for AoU traceability extraction (default: built-in S-CORE AoU config)
visibility	—	no	Bazel visibility

Generated targets: <name> (documentation), <name>_test (TRLC validation)

glossary

Collects glossary pages for Sphinx and forwards them to downstream documentation assembly (for example through dependable_element).

glossary(
   name = "project_glossary",
   srcs = ["docs/glossary.rst"],
)

Example glossary source (.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.

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.rst files containing glossary definitions
visibility	—	no	Bazel visibility

Generated targets: <name> (documentation; no standalone test)

architectural_design

Bundles static, dynamic, public-API, and internal-API architecture views into a single target. Provides ArchitecturalDesignInfo consumed by dependable_element and safety_analysis.

architectural_design(
    name         = "arch",
    static       = ["docs/static_design.puml"],
    dynamic      = ["docs/sequence.puml"],
    public_api   = ["docs/public_api.puml"],
    internal_api = ["docs/internal_api.puml"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
static	label list	no	Static-view files – component/package diagrams only (.puml, .rst, .md, .svg, .png); see Multiple static PlantUML files below for multi-file resolution. Class diagrams belong in the elaborating unit’s own unit_design(static=[...]) instead, never here (default [])
dynamic	label list	no	Dynamic-view files; several sequence diagrams share a participant cast (see Multiple files in the other views) (default [])
public_api	label list	no	Public-API diagram files (.puml); also generates traceability items for safety analysis, exposed via ArchitecturalDesignInfo.public_api_lobster_files. Several class diagrams resolve as one group (default [])
internal_api	label list	no	Internal-API diagram files (.puml) describing interfaces exposed between components inside the SEooC; their FlatBuffers output is exposed via ArchitecturalDesignInfo.internal_api for downstream validation. Several class diagrams resolve as one group (default [])
maturity	string	no	"release" (default) treats validation findings as errors; "development" emits warnings and continues
visibility	—	no	Bazel visibility

Generated targets: <name> (provides ArchitecturalDesignInfo; no standalone test — consistency is validated as part of bazel test //pkg:my_element)

Multiple static PlantUML files

static accepts more than one .puml file, all component diagrams. This is intended for splitting a large architecture into a boundary overview diagram (the SEooC and its public interfaces only) and one or more detail diagrams that elaborate the internals, without repeating every relation and nested entity in both places. (Class diagrams are never allowed in static – put them in the elaborating unit’s own unit_design(static=[...]) instead.)

All .puml files passed to static are resolved together, in one pass, instead of one file at a time — see ComponentResolver::resolve_group. Once every file’s elements are known, they’re merged by entity id (the full dot-path of parent names). Rules for resolution and the merge:

• Implicit reparenting: a top-level element with a body in one file that has the same name, element type and stereotype as a nested declaration in exactly one other file is implicitly reparented onto that declaration’s parent chain, instead of becoming a new top-level entity. Matching is by name, so the files may use different aliases for the same entity. This is what lets a detail file declare only a component’s children (no wrapper) while an overview file nests that same component under the SEooC boundary. A bodyless element (component X without { ... }) and a rooted name (::X) are never reparented; they stay separate top-level entities. Reparenting is transitive: if the parent itself needs reparenting, that is resolved first (a cycle is an ImplicitParentCycle error). Matching nested declarations under more than one distinct parent is an AmbiguousImplicitParent error rather than an arbitrary guess.

• A relation’s source must be declared (or reparented) in the file that writes it; only its target may resolve to another file in the same static group, written as the declaring file writes it (its alias, else its name). The group is consulted only when the target isn’t found locally; more than one other file resolving it is an AmbiguousReference error. Referencing a source that isn’t local is a CrossFileRelationSource error – unless the relation is undirected (no arrowhead and no dependency-style decoration), in which case the two sides are swapped instead of erroring (the locally-declared endpoint becomes the source), since an undirected relation has no inherent direction to violate.

• Re-declaring the same entity (identical id) in more than one file is allowed as long as its stereotype and element type agree across files; their relations are unioned (duplicate relations are de-duplicated). This is what lets an overview file bare-declare a component or unit that a detail file elaborates further (whether by literally repeating the wrapper, or implicitly via reparenting above).

• Re-declaring the same id with a conflicting stereotype or element type across files is an error.

• A parent whose children are declared across more than one file is only allowed if a single file contains the full set of children (i.e. one file is the “home” file and the others only add a benign subset); if the children are genuinely split with no file containing all of them, this is reported as an error.

• Re-nesting an entity under a different parent in another file is not detected as a same-entity conflict, because the id encodes the parent chain — a different parent means a different id, hence a different entity. Such “wrong nesting” mistakes are instead caught by the existing Bazel-vs-diagram comparison (an entity nested under the wrong parent shows up as an extra/missing entry there).

Multiple files in the other views

Every view (static, dynamic, public_api, internal_api; for unit_design static and dynamic) is resolved as one group per view: ids are shared inside a view, never across views. The files of a view are split by diagram kind first (component, class, sequence, activity); a group never mixes kinds. static of architectural_design is component-only.

The kind is detected per file, in the order component, activity, class, sequence. Give each file a construct of its own kind: class (or a body with members) for class diagrams, participant or activate for sequence diagrams. package p { interface I } and a file of only a -> b : call() are component diagrams.

• Class diagrams (public_api, internal_api, unit_design static): same implicit reparenting and peer references as the component rules above. A declaration without a body is a reference. Re-declaring one id merges the declarations: a bodyless one merges into the one with a body (members, type aliases or enum literals; relationships do not count and are united); two bodies are class "<id>" is defined more than once; a different type or stereotype is a conflict. A namespace is defined only in files that own a defined child.

• Sequence diagrams (dynamic, unit_design dynamic): no reparenting. A message endpoint or create target that the file does not declare resolves to the explicit participant declarations of the other files of the view, by alias, else by name. A local declaration wins; distinct uids from several files are AmbiguousParticipantReference. activate/deactivate/destroy and ref over stay file-local.

• Activity diagrams carry no names and are independent per file.

See plantuml/parser/docs/element-identifiers.md (section 4) for examples.

unit_design

Attaches code-level design diagrams to a unit target. Accepts the same file types as architectural_design but scoped to a single unit’s internal implementation.

unit_design(
    name    = "my_unit_design",
    static  = ["class_diagram.rst", "class_diagram.puml"],
    dynamic = ["sequence_diagram.puml"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
static	label list	no	Static-view files (class diagrams, data-structure diagrams). When an .rst fragment references a .puml via .. uml::, list both files together. Class diagrams resolve as one group (default [])
dynamic	label list	no	Dynamic-view files (sequence, state diagrams). Sequence diagrams resolve as one group; a shared cast file declares the participants, scenario files reference them (default [])
visibility	—	no	Bazel visibility

Generated targets: <name> (no standalone test; diagrams are consumed by the parent unit)

failure_modes

Stage 1 of the safety analysis: the FailureMode records. The fault_trees diagrams reference them as tree top events (list the target in fault_trees.deps); safety_analysis renders and traces them.

failure_modes(
    name = "my_failure_modes",
    srcs = ["docs/failure_modes.trlc"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	yes	.trlc files containing FailureMode records
deps	label list	no	Targets providing TrlcProviderInfo needed to parse the records (default [])
lobster_config	label	no	lobster-trlc configuration for FailureMode extraction (default: the S-CORE failure mode config)
visibility	—	no	Bazel visibility

Generated targets: <name>, <name>_test (TRLC validation)

fault_trees

Stage 2 of the safety analysis: the fault-tree root causes. Requirement targets (assumptions_of_use, component_requirements) list it in deps to reference the generated <fta_package>.<RootCause> records, which breaks the dependency cycle between measures and analysis.

fault_trees(
    name = "my_fault_trees",
    srcs = ["docs/fta.puml"],
    deps = [":my_failure_modes"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
srcs	label list	no	FTA PlantUML diagram files (.puml) (default [])
deps	label list	no	failure_modes targets holding the failure modes the diagrams reference (default [])
fta_package	string	no	TRLC package name for the generated fta_events.trlc stub (the RootCause records derived from srcs). The target exports it (with the failure modes as context) as TrlcProviderInfo. Defaults to a sanitized form of the target’s package and name with a _fta suffix (e.g. pkg_sub__name_fta), so equally named targets of different packages do not collide. The repository is not part of it; set fta_package explicitly when equally named targets of different repositories meet in one build, when package names differ only in case or underscores (TRLC rejects those as too similar, e.g. pkg/fta:y and pkg:fta_y), and to get a stable, readable name for <fta_package>.<RootCause> references.
visibility	—	no	Bazel visibility

Generated targets: <name> (generated fta_events.trlc and the root-cause lobster file; no standalone test)

safety_analysis

Stage 3 of the safety analysis: renders the FMEA page from the failure_modes, a fault_trees target and the measures that address the root causes.

safety_analysis(
    name            = "my_safety_analysis",
    arch_design     = ":arch",
    failure_modes   = [":my_failure_modes"],
    fault_trees     = ":my_fault_trees",
    safety_measures = [":aous", "docs/mitigations.trlc"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
failure_modes	label list	no	failure_modes targets whose records are rendered and traced (default []). Every failure mode a root cause references must be listed; the assembler fails otherwise.
fault_trees	label	yes	fault_trees target providing the root causes
safety_measures	label list	no	Measures addressing the root causes (default []): assumptions_of_use / component_requirements targets and .trlc files containing Mitigation records (any other record type in such a file is rejected). Only the records of these entries are rendered and traced; the targets in their deps are used to resolve references only. The assumptions_of_use targets listed here are the own AoUs of the dependable_element whose dependability_analysis includes this target: they are rendered in the safety analysis, forwarded to dependees, and shown once however many safety analyses list them. An assumptions_of_use target that no safety_analysis lists here is neither rendered nor forwarded.
arch_design	label	yes	architectural_design target
visibility	—	no	Bazel visibility

Generated targets: <name> (documentation; no standalone test — traceability validated via the parent dependability_analysis)

dependability_analysis

Wraps one or more safety_analysis targets into a complete safety-analysis package. Running bazel test validates the full FMEA traceability chain.

dependability_analysis(
    name        = "analysis",
    arch_design = ":my_arch",
    safety_analysis = [":my_safety_analysis"],
)

Attribute	Type	Required	Description
name	string	yes	Target name
safety_analysis	label list	no	safety_analysis targets to include in this analysis (default []). A dependable_element stages the pages of each dependability_analysis under the analysis name as safety_analysis.rst / fta.puml, so list one safety_analysis per dependability_analysis and use several dependability_analysis targets for several safety analyses.
arch_design	label	no	Optional architectural_design target this analysis relates to (default None)
visibility	—	no	Bazel visibility

Generated targets: <name> (build → documentation; bazel test //pkg:analysis → full FMEA traceability validation)

Structural Rules

unit

The smallest independently testable software element. Ties together implementation targets, test targets, and an optional unit_design target. The name must match the unit name used in the static architecture PlantUML diagram.

unit(
    name           = "KeyValueStore",
    unit_design    = [":kvs_unit_design"],
    implementation = [":kvs_lib"],
    tests          = [":kvs_unit_test"],
)

Attribute	Type	Required	Description
name	string	yes	Target name; must match the <<unit>> name in the static PlantUML diagram unless design_name is set
design_name	string	no	Name to match against the static PlantUML diagram instead of name (default: name)
unit_design	label list	yes	unit_design targets describing the unit’s internal design
implementation	label list	yes	Library or binary targets that implement this unit (e.g. cc_library, py_library)
tests	label list	yes	Test targets that verify this unit (may be [])
scope	string list	no	Additional Bazel label strings, not already reachable through implementation, that this unit is allowed to depend on. Each entry is either a specific target label (//pkg:target, allowlisting just that target) or a package wildcard (//pkg:__pkg__ for everything directly in that package, //pkg:__subpackages__ for the whole package tree). Any transitive implementation dependency not covered by implementation or scope triggers a scope violation at dependable_element build time. (default [])
maturity	string	no	"release" (default) treats scope violations as errors; "development" emits warnings and continues
testonly	bool	no	If True, only testonly targets may depend on this unit (default True)
visibility	—	no	Bazel visibility

Generated targets: <name> (provides UnitInfo; no standalone test — the listed tests run via bazel test //pkg:... directly)

component

Groups unit (and optionally nested component) targets into a logical subsystem. Associates component-level requirements and integration tests. The name must match the component name in the static architecture PlantUML diagram.

component(
    name         = "KvsComponent",
    requirements = [":comp_req"],
    components   = [":KeyValueStore", ":StorageBackend"],
    tests        = [],
)

Attribute	Type	Required	Description
name	string	yes	Target name; must match the <<component>> name in the static PlantUML diagram unless design_name is set
design_name	string	no	Name to match against the static PlantUML diagram instead of name (default: name)
requirements	label list	yes	component_requirements or feature_requirements targets for this component
components	label list	no	Nested unit or component targets (default [])
tests	label list	yes	Integration test targets for the component as a whole (may be [])
testonly	bool	no	If True, only testonly targets may depend on this component (default True)
visibility	—	no	Bazel visibility

Generated targets: <name> (provides ComponentInfo; no standalone test — the listed tests run via bazel test //pkg:... directly)

dependable_element

Assembles all process artefacts into a complete SEooC. Runs Sphinx to generate unified HTML documentation and enforces architecture consistency, traceability, and scope checks at build/test time.

dependable_element(
    name                   = "my_seooc",
    integrity_level        = "B",
    requirements           = [":features"],
    architectural_design   = [":arch"],
    dependability_analysis = [":analysis"],
    components             = [":kvs_component"],
    tests                  = [],
)

Attribute	Type	Required	Description
name	string	yes	Target name; also becomes the SEooC documentation title
integrity_level	string	yes	"A", "B", "C", or "D" (D is highest: D > C > B > A)
requirements	label list	yes	feature_requirements or assumed_system_requirements targets
architectural_design	label list	yes	architectural_design targets
dependability_analysis	label list	yes	dependability_analysis targets
components	label list	yes	component or unit targets that implement this SEooC
tests	label list	yes	System-level test targets (may be [])
checklists	label list	no	Additional .rst / .md checklist files (default [])
glossary	label list	no	glossary targets whose pages are included in the generated documentation under a dedicated Glossary section (default [])
deps	label list	no	Other dependable_element targets for cross-referencing and HTML merging (default [])
aou_forwarding	label	no	Optional YAML file that selects which received AoUs to chain-forward to elements that depend on this one. Own AoUs (the assumptions_of_use targets consumed as safety_measures by the element’s safety analyses) are always forwarded automatically — no file needed. Every entry names the AoU with its version (Package.AOU_ID@<version>), so a justification is reviewed again when the AoU changes; unknown IDs, mismatching versions and duplicate entries fail the build. An AoU that reaches the element along several paths is received once; differing definitions fail the build. Schema: forwarded_aous: - aou_id: "Package.AOU_ID@1" justification: > Reason why this element cannot handle the AoU itself and must forward it to its own integrators. See requirements user guide for the full forwarding workflow.
maturity	string	no	"release" (default) treats certified-scope violations, architecture consistency errors, and missing traceability links as hard build/test failures. "development" downgrades them to warnings so the build/test still succeeds — useful when iterating before all scope, architecture, and traceability declarations are finalised. Always revert to ``”release”`` before a certification delivery.
generate_html_report	bool	no	If True, additionally generate a standalone LOBSTER HTML traceability report. Off by default: nothing consumes it (Sphinx renders the multi-page RST report under traceability_report/ instead), so it only adds a build action (default False)
testonly	bool	no	If True, only testonly targets may depend on this element (default True)
visibility	—	no	Bazel visibility

Generated targets:

Target	Purpose
<name>	Main target: build runs Sphinx; bazel test runs the traceability check
<name>_doc	Internal sphinx_module target; usable as deps in other Sphinx builds
<name>_index	Internal artefact-collection and architecture-validation target