strictdoc/backend/sdoc_source_code/reader_rust.py

Path:

Lines:

610

Non-empty lines:

563

Non-empty lines covered with requirements:

563 / 563 (100.0%)

Functions:

Functions covered by requirements:

16 / 16 (100.0%)

1 - 610 | entire file

"7.2.1. Language-aware parsing of source code" (REQUIREMENT)

"""

@relation(SDOC-SRS-142, scope=file)

"""

from enum import IntEnum

from pathlib import Path

from typing import Optional, Union

import tree_sitter_rust as ts_rust

from tree_sitter import Language, Node, Parser, Query, QueryCursor

from strictdoc.backend.sdoc_source_code.constants import FunctionAttribute

from strictdoc.backend.sdoc_source_code.marker_parser import MarkerParser

from strictdoc.backend.sdoc_source_code.models.language import LanguageItem

from strictdoc.backend.sdoc_source_code.models.language_item_marker import (

    LanguageItemMarker,

    RangeMarkerType,

from strictdoc.backend.sdoc_source_code.models.line_marker import LineMarker

from strictdoc.backend.sdoc_source_code.models.range_marker import (

    ForwardRangeMarker,

    RangeMarker,

from strictdoc.backend.sdoc_source_code.models.source_file_info import (

    SourceFileTraceabilityInfo,

from strictdoc.backend.sdoc_source_code.models.source_location import ByteRange

from strictdoc.backend.sdoc_source_code.parse_context import ParseContext

from strictdoc.backend.sdoc_source_code.processors.general_language_marker_processors import (

    language_item_marker_processor,

    line_marker_processor,

    range_marker_processor,

    source_file_traceability_info_processor,

from strictdoc.helpers.cast import assert_cast

from strictdoc.helpers.file_stats import SourceFileStats

from strictdoc.helpers.file_system import file_open_read_bytes

39 - 40 | line

"3.1.14. Valid positions of doc comments" (REQUIREMENT)
"3.1.8. File, line and range markers" (REQUIREMENT)
"3.1.10. Forward relations to Rust items" (REQUIREMENT)

SDOC-LLR-177

3.1.14. Valid positions of doc comments

MID:

7bf3f26c335741398a50e9679a0d4c84

UID:

SDOC-LLR-177

STATUS:

Active

STATEMENT:

StrictDoc shall find doc comments where the language allows_ them and ignore those in other positions.

.. _allows: https://doc.rust-lang.org/reference/attributes.html#r-attributes.allowed-position

COMMENT:

Since doc comments are syntactic sugar for doc attributes, allowed position rules for attributes apply.

RELATIONS (Parent):

SDOC-SRS-204 Language-aware parsing of Rust code

RELATIONS (File):

strictdoc/backend/sdoc_source_code/reader_rust.py, lines: 39-40, line

SDOC-LLR-171

3.1.8. File, line and range markers

MID:

e1be1f38dd374f82abd9691d081f293b

UID:

SDOC-LLR-171

STATUS:

Active

STATEMENT:

StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers.
These marker types shall be parsed from `regular line and block comments`_.

Note: File markers may also result from the inner doc comments of the top-level module.

.. _regular line and block comments: https://doc.rust-lang.org/rust-by-example/hello/comment.html#comments

RELATIONS (Parent):

RELATIONS (File):

SDOC-LLR-173

3.1.10. Forward relations to Rust items

MID:

9d7e371ad7a146e1968cd9bbb7a6790f

UID:

SDOC-LLR-173

STATUS:

Active

STATEMENT:

StrictDoc shall support linking from a requirement in SDoc to a language item in Rust code by using a :code:`FILE`
relation of type :code:`FUNCTION`. For example

.. code-block:: strictdoc

[REQUIREMENT]
UID: REQ-1
RELATIONS:
- TYPE: File
VALUE: file.rs
FUNCTION: file::foo

This shall work for all kinds of Rust items that have a `canonical path`_, including const, enum, fn, mod, static,
struct, trait, type, union.

.. _canonical path: https://doc.rust-lang.org/reference/paths.html#canonical-paths

RELATIONS (Parent):

SDOC-SRS-204 Language-aware parsing of Rust code

RELATIONS (File):

# @relation(SDOC-LLR-177, SDOC-LLR-171, SDOC-LLR-173, scope=line)

TS_QUERY = """

39 - 40 | line

; Query 0: Outer doc attribute, line doc, or block doc in allowed positions

    (attribute_item

      (attribute

        (identifier) @_attribute_id (#eq? @_attribute_id "doc")

          value: (string_literal (string_content) @doc.comment)))+

    (line_comment

      outer: (outer_doc_comment_marker)

      doc: (doc_comment) @doc.comment)+

    (block_comment

      outer: (outer_doc_comment_marker)

      doc: (doc_comment) @doc.comment)

  (attribute_item)*

    ; any identifiable item, most notably functions

    (_ name: [(identifier)(field_identifier)(type_identifier)(lifetime)] @doc.item_identifier)

    ; impl MyStruct

    (impl_item type: (type_identifier) @doc.item_identifier)

    ; extern "C"

    (foreign_mod_item (extern_modifier) @doc.item_identifier)

    ; match arm

    (match_arm (match_pattern) @doc.item_identifier)

    ; assignment inside struct initializer

    (field_initializer field: (field_identifier) @doc.item_identifier)

    ; Statement like 1;

    (expression_statement) @doc.item_identifier

    ; Expression like x + y

    (binary_expression) @doc.item_identifier

    ; Expression like (x + y)

    (parenthesized_expression) @doc.item_identifier

    ; Named "type" field of any enclosing node (usually body), e.g. type within tuple struct.

    type: (_)

  ] @doc.item

; Query 1: Inner doc attribute, line doc or block doc in allowed positions.

; Note: We have to repeat the identical inner pattern, alternations don't help here.

;       See https://github.com/tree-sitter/tree-sitter/issues/3480.

  (function_item

    name: (identifier) @doc.item_identifier

    body: (block

        (inner_attribute_item

          (attribute

            (identifier) @_attribute_id (#eq? @_attribute_id "doc")

            value: (string_literal (string_content) @doc.comment)))+

        (line_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)+

        (block_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)

  (mod_item

    name: (identifier) @doc.item_identifier

    body: (declaration_list

        (inner_attribute_item

          (attribute

            (identifier) @_attribute_id (#eq? @_attribute_id "doc")

            value: (string_literal (string_content) @doc.comment)))+

        (line_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)+

        (block_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)

  (impl_item

    type: (type_identifier) @doc.item_identifier

    body: (declaration_list

        (inner_attribute_item

          (attribute

            (identifier) @_attribute_id (#eq? @_attribute_id "doc")

            value: (string_literal (string_content) @doc.comment)))+

        (line_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)+

        (block_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)

  (foreign_mod_item (extern_modifier) @doc.item_identifier

    body: (declaration_list

        (inner_attribute_item

          (attribute

            (identifier) @_attribute_id (#eq? @_attribute_id "doc")

            value: (string_literal (string_content) @doc.comment)))+

        (line_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)+

        (block_comment

          inner: (inner_doc_comment_marker)

          doc: (doc_comment) @doc.comment)

] @doc.item

; Query 2: Inner line or block doc comment of file-level module.

(source_file

    (line_comment

      inner: (inner_doc_comment_marker)

        doc: (doc_comment) @doc.comment)+

    (block_comment

      inner: (inner_doc_comment_marker)

        doc: (doc_comment) @doc.comment)

) @doc.item

; Query 3: normal line or block comment

[(line_comment !doc)+

 (block_comment !doc)] @normal_comment

; Query 4: Identifiable items. Those where it's clear how to link by forward relations.

  (const_item name: (identifier) @doc.item_identifier) @doc.item

  (enum_item name: (type_identifier) @doc.item_identifier) @doc.item

  (function_item name: (identifier) @doc.item_identifier) @doc.item

  (mod_item name: (identifier) @doc.item_identifier) @doc.item

  (static_item name: (identifier) @doc.item_identifier) @doc.item

  (struct_item name: (type_identifier) @doc.item_identifier) @doc.item

  (trait_item name: (type_identifier) @doc.item_identifier) @doc.item

  (type_item name: (type_identifier) @doc.item_identifier) @doc.item

  (union_item name: (type_identifier) @doc.item_identifier) @doc.item

"""

class RustTsQuery(IntEnum):

    """Give the queries from TS_QUERY a friendly name."""

    OUTER_DOC_COMMENT = 0

    INNER_DOC_COMMENT = 1

    INNER_DOC_COMMENT_FILEMODULE = 2

    NORMAL_COMMENT = 3

    IDENTIFIABLE_ITEM = 4

202 - 215 | function comments_text_from_comment_nodes()

"3.1.12. Collapse doc comments" (REQUIREMENT)

SDOC-LLR-175

3.1.12. Collapse doc comments

MID:

04b5927294c34710995d3671040dd8ae

UID:

SDOC-LLR-175

STATUS:

Active

STATEMENT:

Multiple scattered doc comments shall be collapsed as done by the rustdoc_ tool when using the collapse-docs option
to determine the highlight range(s).

For example, rustdoc would collapse alle these comments into the description of :code:`fn foo()`

.. code-block:: rust
:number-lines:

/// Some
/// line

/// doc,

/**
* and some
* block dock,
*/

#[doc = "and some"]

#[doc = "doc attr."]

fn foo() {
}

In the given example, the StrictDoc highlight range for the relation marker shall be from line 1 to line 16.

.. _rustdoc: https://github.com/rust-lang/rust/tree/main/src/tools/rustdoc

RELATIONS (Parent):

SDOC-SRS-204 Language-aware parsing of Rust code

RELATIONS (File):

strictdoc/backend/sdoc_source_code/reader_rust.py, lines: 202-215, function comments_text_from_comment_nodes()

def comments_text_from_comment_nodes(comments: list[Node]) -> str:

"""

    Join multiple comment nodes into one multi-line string.

    @relation(SDOC-LLR-175, scope=function)

"""

    comment_text = assert_cast(comments[0].text, bytes).decode("utf-8")

    last_row = comments[0].start_point.row

    for comment_part in comments[1:]:

        new_lines = comment_part.start_point.row - last_row

        last_row = comment_part.start_point.row

        comment_text += "\n" * new_lines + assert_cast(

            comment_part.text, bytes

        ).decode("utf-8")

    return comment_text

202 - 215 | function comments_text_from_comment_nodes()

def special_description(item: Node, identifier_text: str) -> Optional[str]:

"""

    Make a description for language constructs that are not functions.

    The default Function description assumes the object actually represents a function.

    However, the Rust reader reuses Function to represent many different Rust specific object types.

    We have to give them a suitable Rust specific description.

"""

    if item.type == "associated_type":

        return f"associated type {identifier_text}"

    elif item.type in ("binary_expression", "parenthesized_expression"):

        return f"expression {identifier_text}"

    elif item.type == "const_item":

        return f"const {identifier_text}"

    elif item.type == "const_parameter":

        return f"const parameter {identifier_text}"

    elif item.type == "function_item":

        return f"fn {identifier_text}()"

    elif item.type == "enum_item":

        return f"enum {identifier_text}"

    elif item.type == "enum_variant":

        return f"enum variant {identifier_text}"

    elif item.type == "expression_statement":

        return f"statement {identifier_text}"

    elif item.type == "extern_crate_declaration":

        return f"crate {identifier_text}"

    elif item.type == "field_declaration":

        return f"field {identifier_text}"

    elif item.type == "field_initializer":

        return f"field initializer {identifier_text}"

    elif item.type == "foreign_mod_item":

        return f"foreign module {identifier_text}"

    elif item.type == "impl_item":

        return f"impl {identifier_text}"

    elif item.type == "match_arm":

        return f"match arm {identifier_text}"

    elif item.type == "macro_definition":

        return f"macro {identifier_text}"

    elif item.type == "mod_item":

        return f"module {identifier_text}"

    elif item.type == "lifetime_parameter":

        return f"lifetime {identifier_text}"

    elif item.type == "static_item":

        return f"static {identifier_text}"

    elif item.type == "struct_item":

        return f"struct {identifier_text}"

    elif item.type == "trait_item":

        return f"trait {identifier_text}"

    elif item.type == "type_item":

        return f"type {identifier_text}"

    elif item.type == "type_parameter":

        return f"type parameter {identifier_text}"

    elif item.type == "union_item":

        return f"union {identifier_text}"

    elif item.type in ("primitive_type", "type_identifier"):

        return f"type {identifier_text}"

    return None

class SourceFileTraceabilityReader_Rust:

    @staticmethod

    def supported_elements() -> list[str]:

        return []

    def __init__(self, custom_tags: Optional[set[str]] = None) -> None:

        self.custom_tags: Optional[set[str]] = custom_tags

    def read(

        self,

        input_buffer: bytes,

        file_path: Optional[str] = None,

    ) -> SourceFileTraceabilityInfo:

        file_stats = SourceFileStats.create(input_buffer)

        parse_context = ParseContext(file_path, file_stats)

        traceability_info = SourceFileTraceabilityInfo([])

        parser = ParserRun(

            input_buffer, parse_context, traceability_info, self.custom_tags

        parser()

        source_file_traceability_info_processor(

            traceability_info, parse_context

        return traceability_info

    def read_from_file(self, file_path: str) -> SourceFileTraceabilityInfo:

"""

        Generate the source file traceability info for one particular Rust file.

        The created SourceFileTraceabilityInfo is filled partially local information:

        - functions: Markers are associated, but only those resulting from local markers.

        - markers: Markers that stem from markup in this file.

        - ng_map_reqs_to_markers: Mapping of requirement IDs to Marker objects for markers directly defined in the source file.

"""

        with file_open_read_bytes(file_path) as file:

            sdoc_content = file.read()

            sdoc = self.read(sdoc_content, file_path=file_path)

            return sdoc

class ParserRun:

    def __init__(

        self,

        input_buffer: bytes,

        parse_context: ParseContext,

        traceability_info: SourceFileTraceabilityInfo,

        custom_tags: Optional[set[str]],

):

        rust_language = Language(ts_rust.language())

        self.parser = Parser(rust_language)  # type: ignore[call-arg, unused-ignore]

        self.TS_QUERY = Query(rust_language, TS_QUERY)

        self.input_buffer: bytes = input_buffer

        self.parse_context = parse_context

        self.traceability_info = traceability_info

        self.custom_tags: Optional[set[str]] = custom_tags

    def __call__(self) -> None:

        tree = self.parser.parse(self.input_buffer)

        cursor = QueryCursor(self.TS_QUERY)

        matches = cursor.matches(tree.root_node)

        seen_nodes = set()

        deferred_matches = []

        for query_index, captures in matches:

            if query_index == RustTsQuery.IDENTIFIABLE_ITEM:

                # The query for identifiable items overlaps with comment based queries. Move results for identifiable

                # items last, so that a result can be skipped if a LanguageItem was already created.

                deferred_matches.append(captures)

            elif query_index in (

                RustTsQuery.OUTER_DOC_COMMENT,

                RustTsQuery.INNER_DOC_COMMENT,

                RustTsQuery.INNER_DOC_COMMENT_FILEMODULE,

):

                assert len(captures["doc.item"]) == 1

                item = captures["doc.item"][0]

                doc_comment = captures["doc.comment"]

                if (

                    item.type == "source_file"

                    and "doc.item_identifier" not in captures

):

                    self._process_anonymous_module_comment(

                        doc_comment,

                        item,

                else:

                    if "doc.item_identifier" in captures:

                        # doc comment on named item

                        assert len(captures["doc.item_identifier"]) == 1

                        identifier = assert_cast(

                            captures["doc.item_identifier"][0].text, bytes

                        ).decode()

                    else:

                        # doc comment on anonymous item

                        identifier = assert_cast(item.text, bytes).decode()

                    self._process_doc_comment(

                        doc_comment,

                        item,

                        identifier,

                seen_nodes.add(item.id)

            elif query_index == RustTsQuery.NORMAL_COMMENT:

                self._process_normal_comment(captures["normal_comment"])

        for captures in deferred_matches:

            assert len(captures["doc.item"]) == 1

            assert len(captures["doc.item_identifier"]) == 1

            item = captures["doc.item"][0]

            if item.id not in seen_nodes:

                identifier = assert_cast(

                    captures["doc.item_identifier"][0].text, bytes

                ).decode()

                self._process_item_for_forward_relation(item, identifier)

390 - 420 | function ParserRun._process_anonymous_module_comment()

"3.1.1. Auto-scoped relation markers in Rust docs" (REQUIREMENT)
"3.1.9. Source nodes from doc comments" (REQUIREMENT)

SDOC-LLR-164

3.1.1. Auto-scoped relation markers in Rust docs

MID:

d83cab2dcd014d328b348acc37c6f4a6

UID:

SDOC-LLR-164

STATEMENT:

If a StrictDoc relation marker is inside a `Rust doc comment`_, the marker scope shall be set to exact the item the Rust
language defines as target of the containing doc comment. The :code:`@relation(scope=...)` parameter shall therefore
be optional and shall be ignored if provided.

.. code-block:: rust
:number-lines:

/// @relation(REQ-1)
impl Foo {

/// @relation(REQ-2)
fn foo() {
}
}

In the given example, the first marker shall link REQ-1 to the :code:`impl Foo` implementation,
highlighting lines 1 to 7. The second marker shall link REQ-2 to the :code:`fn foo()` function,
highlighting lines 4 to 6.

.. _Rust doc comment: https://doc.rust-lang.org/rust-by-example/meta/doc.html#doc-comments

COMMENT:

Note that doc comments are syntactic sugar for `doc attribute`_ s, which shall also be supported.
To figure detailed doc comment rules from the rust-lang specification it's sometimes useful
to check for general attribute rules, if explicit doc comment rules are missing.

.. _doc attribute: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html

RELATIONS (Parent):

RELATIONS (File):

SDOC-LLR-172

3.1.9. Source nodes from doc comments

MID:

b9b2e4d377db42f5b3fb7aeabaf3f72a

UID:

SDOC-LLR-172

STATUS:

Active

STATEMENT:

If a Rust doc comments contains custom tags, and the containing Rust source file matches an entry in the
source node configuration, StrictDoc shall create document nodes from the custom tags and automatically
link the created node with the Rust item targeted by the doc comment.

RELATIONS (Parent):

RELATIONS (File):

    def _process_anonymous_module_comment(

        self, comments: list[Node], module: Node

    ) -> None:

"""

        Create marker, item and source nodes for file-level module from tree-sitter doc comment nodes.

        @relation(SDOC-LLR-164, SDOC-LLR-172, scope=function)

"""

        comment_text = comments_text_from_comment_nodes(comments)

        source_node = MarkerParser.parse(

            input_string=comment_text,

            line_start=1,

            line_end=self.parse_context.file_stats.lines_total,

            comment_line_start=module.start_point.row + 1,

            comment_byte_range=ByteRange.create_from_ts_nodes(

                comments[0], comments[-1]

),

            custom_tags=self.custom_tags,

            default_scope="file",

        for marker_ in source_node.markers:

            if not isinstance(marker_, LanguageItemMarker):

                continue

            # At the top level, only accept the scope=file markers.

            # Everything else will be handled by functions and classes.

            if marker_.scope != RangeMarkerType.FILE:

                print(  # noqa: T201

                    "warning: comment to top-level module is not scope=file, ignoring"

                continue

            language_item_marker_processor(marker_, self.parse_context)

            self.traceability_info.markers.append(marker_)

390 - 420 | function ParserRun._process_anonymous_module_comment()

422 - 492 | function ParserRun._process_doc_comment()

"3.1.1. Auto-scoped relation markers in Rust docs" (REQUIREMENT)
"3.1.9. Source nodes from doc comments" (REQUIREMENT)

SDOC-LLR-164

3.1.1. Auto-scoped relation markers in Rust docs

MID:

d83cab2dcd014d328b348acc37c6f4a6

UID:

SDOC-LLR-164

STATEMENT:

COMMENT:

RELATIONS (Parent):

RELATIONS (File):

SDOC-LLR-172

3.1.9. Source nodes from doc comments

MID:

b9b2e4d377db42f5b3fb7aeabaf3f72a

UID:

SDOC-LLR-172

STATUS:

Active

STATEMENT:

RELATIONS (Parent):

RELATIONS (File):

    def _process_doc_comment(

        self,

        comments: list[Node],

        item: Node,

        identifier_text: str,

    ) -> None:

"""

        Create markers, items and source nodes from tree-sitter doc comment nodes.

        @relation(SDOC-LLR-164, SDOC-LLR-172, scope=function)

"""

        assert len(comments) >= 1

        comment_text = comments_text_from_comment_nodes(comments)

        line_start_0_based = min(

            item.start_point[0], comments[0].start_point[0]

        line_end_0_based = max(item.end_point[0], comments[-1].end_point[0])

        source_node = MarkerParser.parse(

            input_string=comment_text,

            line_start=line_start_0_based + 1,

            line_end=line_end_0_based + 1

            if self.input_buffer[-1] == 10

            else line_end_0_based,

            comment_line_start=comments[0].start_point[0] + 1,

            comment_byte_range=ByteRange.create_from_ts_nodes(

                comments[0], comments[-1]

),

            custom_tags=self.custom_tags,

            entity_name=identifier_text,

            default_scope="function",

        function_markers: list[

            Union[

                LanguageItemMarker, LineMarker, RangeMarker, ForwardRangeMarker

        ] = []

        for marker_ in source_node.markers:

            if isinstance(marker_, LanguageItemMarker) and (

                language_item_marker_ := marker_

):

                if (

                    description := special_description(item, identifier_text)

                ) is not None:

                    language_item_marker_.set_description(description)

                # adds marker to context, and connects context requirements with marker

                language_item_marker_processor(

                    language_item_marker_, self.parse_context

                self.traceability_info.markers.append(language_item_marker_)

                function_markers.append(marker_)

        name = self.canonical_path(item.parent, identifier_text)

        new_function_for_rust_item = LanguageItem(

            parent=self.traceability_info,

            name=name,

            display_name=name,

            line_begin=item.start_point[0] + 1,

            line_end=item.end_point[0] + 1,

            code_byte_range=ByteRange.create_from_ts_node(item),

            child_functions=[],

            markers=[],

            attributes={FunctionAttribute.DEFINITION},

        if len(source_node.fields) > 0:

            source_node.function = new_function_for_rust_item

        self.traceability_info.source_nodes.append(source_node)

        self.traceability_info.functions.append(new_function_for_rust_item)

        self.traceability_info.ng_map_names_to_markers[identifier_text] = (

            function_markers

422 - 492 | function ParserRun._process_doc_comment()

494 - 532 | function ParserRun._process_normal_comment()

"3.1.8. File, line and range markers" (REQUIREMENT)

SDOC-LLR-171

3.1.8. File, line and range markers

MID:

e1be1f38dd374f82abd9691d081f293b

UID:

SDOC-LLR-171

STATUS:

Active

STATEMENT:

RELATIONS (Parent):

RELATIONS (File):

    def _process_normal_comment(self, comments: list[Node]) -> None:

"""

        Create markers and items from tree-sitter normal comment nodes.

        @relation(SDOC-LLR-171, scope=function)

"""

        comment_text = comments_text_from_comment_nodes(comments)

        line_start_0_based = comments[0].start_point.row

        line_end_0_based = comments[-1].end_point.row

        source_node = MarkerParser.parse(

            input_string=comment_text,

            line_start=line_start_0_based + 1,

            line_end=line_end_0_based + 1,

            comment_line_start=line_start_0_based + 1,

            comment_byte_range=ByteRange.create_from_ts_nodes(

                comments[0], comments[-1]

),

        for marker_ in source_node.markers:

            if (

                isinstance(marker_, LanguageItemMarker)

                and (marker_.scope is RangeMarkerType.FILE)

                and (language_item_marker := marker_)

):

                language_item_marker.ng_range_line_begin = 1

                language_item_marker.ng_range_line_end = (

                    self.parse_context.file_stats.lines_total

                language_item_marker_processor(

                    language_item_marker, self.parse_context

            elif isinstance(marker_, RangeMarker) and (range_marker := marker_):

                range_marker_processor(range_marker, self.parse_context)

            elif isinstance(marker_, LineMarker) and (line_marker := marker_):

                line_marker_processor(line_marker, self.parse_context)

            else:

                print(  # noqa: T201

                    "warning: Ignoring @relation. Only scope=file|line|range_start is supported in regular "

                    "Rust comments. Use doc comments otherwise."

494 - 532 | function ParserRun._process_normal_comment()

534 - 557 | function ParserRun._process_item_for_forward_relation()

"3.1.10. Forward relations to Rust items" (REQUIREMENT)

SDOC-LLR-173

3.1.10. Forward relations to Rust items

MID:

9d7e371ad7a146e1968cd9bbb7a6790f

UID:

SDOC-LLR-173

STATUS:

Active

STATEMENT:

RELATIONS (Parent):

SDOC-SRS-204 Language-aware parsing of Rust code

RELATIONS (File):

    def _process_item_for_forward_relation(

        self, item: Node, identifier: str

    ) -> None:

"""

        Create item objects from tree-sitter doc comment nodes to support forward relations.

        Corresponding markers will be created and resolved later by FileTraceabilityIndex,

        see validate_and_resolve.

        @relation(SDOC-LLR-173, scope=function)

"""

        name = self.canonical_path(item.parent, identifier)

        function = LanguageItem(

            parent=self.traceability_info,

            name=name,

            display_name=name,

            line_begin=item.start_point[0] + 1,

            line_end=max(item.end_point[0] + 1, item.start_point[0] + 2),

            code_byte_range=ByteRange.create_from_ts_node(item),

            child_functions=[],

            markers=[],

            attributes={FunctionAttribute.DEFINITION},

        self.traceability_info.functions.append(function)

534 - 557 | function ParserRun._process_item_for_forward_relation()

559 - 610 | function ParserRun.canonical_path()

"3.1.11. Forward relation by canonical path" (REQUIREMENT)

SDOC-LLR-174

3.1.11. Forward relation by canonical path

MID:

d01b2204fcb44882b991ca11ce567f52

UID:

SDOC-LLR-174

STATUS:

Active

STATEMENT:

The identifier for forward relations shall be the `canonical path`_ as the rustc compiler would set it when invoked for
a single file like

.. code-block:: shell

rustc --crate-type rlib --emit=obj src/lib.rs

Note: :code:`cargo build` usually result in a different canonical path, since it considers the file position relative to
the crate root. Using a single file as root is a simplification, needed because StrictDoc is unaware of the Rust
file and directory-based module hierarchy.

.. _canonical path: https://doc.rust-lang.org/reference/paths.html#canonical-paths

COMMENT:

The canonical path of an item can be observed with :code:`objdump -t lib.o --demangle=rust`. For example, given this
source file

.. code-block:: rust
:number-lines:

pub mod foo {

pub trait Foo {
fn foo(&self) {}
}

pub struct Bar(i32);

impl Foo for Bar {
fn foo(&self) {}
}
}

:code:`objdump` will show

.. code-block:: shell

<lib::foo::Bar as lib::foo::Foo>::foo

Alas, a forward relation would be

.. code-block:: strictdoc

[REQUIREMENT]
UID: REQ-1
RELATIONS:
- TYPE: File
VALUE: file.rs
FUNCTION: <lib::foo::Bar as lib::foo::Foo>::foo

RELATIONS (Parent):

SDOC-SRS-204 Language-aware parsing of Rust code

RELATIONS (File):

strictdoc/backend/sdoc_source_code/reader_rust.py, lines: 559-610, function ParserRun.canonical_path()

    def canonical_path(

        self, parent_scope: Optional[Node], item_path_segment: str

    ) -> str:

"""

        Construct a canonical path in best-effort.

        @relation(SDOC-LLR-174, scope=function)

"""

        cursor: Optional[Node] = parent_scope

        if (

            cursor is not None

            and cursor.type == "declaration_list"

            and cursor.parent is not None

            and cursor.parent.type == "impl_item"

):

            cursor = cursor.parent

            item_being_implemented = cursor.child_by_field_name("type")

            assert item_being_implemented is not None

            canonical_path_item_being_implemented = self.canonical_path(

                cursor,

                assert_cast(item_being_implemented.text, bytes).decode("utf-8"),

            impl_trait_node = cursor.child_by_field_name("trait")

            if impl_trait_node is not None:

                # rust-lang.org: For trait implementations, [the path prefix] is the canonical path of the item being

                # implemented followed by as followed by the canonical path to the trait all surrounded in angle (<>)

                # brackets.

                trait = self.canonical_path(

                    None,

                    assert_cast(impl_trait_node.text, bytes).decode("utf-8"),

                path_prefix = (

                    f"<{canonical_path_item_being_implemented} as {trait}>"

            else:

                # rust-lang.org: For bare implementations, [the path prefix] is the canonical path of the item being

                # implemented surrounded by angle (<>) brackets.

                path_prefix = f"<{canonical_path_item_being_implemented}>"

        else:

            path_prefix_segments = []

            while cursor is not None:

                name_node = cursor.child_by_field_name("name")

                if name_node is not None:

                    name = assert_cast(name_node.text, bytes).decode("utf-8")

                    path_prefix_segments.append(name)

                cursor = cursor.parent

            path_prefix_segments.append(Path(self.parse_context.filename).stem)

            path_prefix = "::".join(reversed(path_prefix_segments))

        # rust-lang.org: The canonical path is defined as a path prefix appended by the path segment the item itself

        # defines.

        return f"{path_prefix}::{item_path_segment}"

1 - 610 | entire file